Skip to content

See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.

Health: count FastAPI aliases named like a check, recognise more DB session helpers

PaulMagos8aac9a01e331
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f943a66..0c0dd08 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,10 @@
# Changelog
+## Unreleased
+
+- **Fewer false Health alarms on FastAPI:** a dependency shortcut whose own name says it checks the caller, like `AdminAccess = Annotated[dict, Depends(check)]`, now counts as a login check even when its function has a plain name.
+- **More accurate Health on FastAPI:** more database session helpers (`get_sql_session`, `SessionLocal`, engine, connection and unit-of-work helpers) are recognised, so an endpoint that only has one of them is flagged instead of passing as protected.
+
## 0.1.4 (2026-10-28)
- **Safari fix:** cards now show up in Safari (and every browser on iPhone/iPad). Before, only the connection lines were drawn and card text appeared in the top-left corner. Reported by @fpv001 in #1, fixed by @PaulMagos in #3.
diff --git a/skills/floorplan/scripts/lib/health.mjs b/skills/floorplan/scripts/lib/health.mjs
index 8f4c334..17526d4 100644
--- a/skills/floorplan/scripts/lib/health.mjs
+++ b/skills/floorplan/scripts/lib/health.mjs
@@ -171,9 +171,11 @@ function findSecrets(src, f, out) {
const GUARD_NAME = /(^|_)(login|auth|authenticated|authorized?|jwt|token|permission|permissions|perm|role|roles|staff|admin|superuser|owner|scope|scopes|session|api_?key|signature|signed|hmac|device|member|user)(_|$)|_required$|^requires?_|^ensure_|^verify_|^check_(auth|token|user|session|permission|role|api)|protect|^is_?authenticated|^is_?admin/i;
const NOT_GUARD = /^(route|get|post|put|patch|delete|cached?|limit|limiter|rate_?limit\w*|cross_origin|wraps|staticmethod|classmethod|property|retry|timed|log\w*|swag_from|validate\w*|expects|marshal\w*|doc|json_required|fields?_required|params?_required|body_required|transaction\w*|csrf\w*|exempt)$/i;
const isGuardName = (name) => !!name && !NOT_GUARD.test(name) && GUARD_NAME.test(snake(name));
-// FastAPI dependencies that hand over a database session rather than check the caller (SessionDep, get_db)
-const DB_DEPENDENCY = /^(get_|new_|create_)?(async_)?(db|database|session|db_session|sessionmaker)$|(^|_)(db|database)(_|$)/i;
-const isGuardDep = (name) => isGuardName(name) && !DB_DEPENDENCY.test(name);
+// FastAPI dependencies that hand over a database session rather than check the caller
+// (SessionDep, get_db, get_sql_session, SessionLocal, a unit of work), matched on the snake_case name
+const DB_DEPENDENCY = /^(get_|new_|create_)?(async_)?(db|database|session|db_session|sessionmaker)$|(^|_)(db|database|sql\w*|engine|conn|connection|cursor|uow|unit_of_work)(_|$)|session_?(local|maker|factory)/i;
+const isDbDep = (name) => DB_DEPENDENCY.test(snake(name));
+const isGuardDep = (name) => isGuardName(name) && !isDbDep(name);
// A handler body that inspects the caller itself.
const INLINE_CHECK = /request\.headers(?:\.get)?\(?\s*\[?\s*['"](authorization|x-api-key|x-[\w-]*(token|key|secret|signature)[\w-]*)['"]|req\.headers(?:\.|\[\s*['"])(authorization|x-api-key)|\b(verify|check|require|validate|authenticate|authorize)_?\w*(auth|token|session|user|key|signature|webhook|hmac|jwt|device|staff|admin|permission|role|request|caller)\w*\s*\(|\bcurrent_user\b|get_jwt_identity|verify_jwt_in_request|compare_digest|abort\(\s*40[13]\b|,\s*40[13]\s*\)?\s*$|status(?:Code)?\s*[:=(]\s*40[13]\b|\.status\(\s*40[13]\s*\)|req\.user\b|req\.session\.user|req\.auth\b|jwt\.verify|jwtVerify|getServerSession|auth\(\)|currentUser\(|getAuth\(|auth\.getUser|getSession\(|verifyIdToken|getToken\(/m;
const SIGNATURE_CHECK = /hmac|signature|verify_?webhook|construct_?event|x-hub-signature|compare_digest|svix|webhooks?\.verify|jwt\.decode|oidc|id_token|authenticated|verify_\w*(token|request|push)/i;
@@ -324,6 +326,8 @@ function jsRoutes(src, f, out) {
* An alias checks the caller when its dependency function does: by its name (admin_user), by taking a
* checking dependency (Depends(require_login)), or by taking a checking alias itself, e.g.
* `AdminOffice = Annotated[Office, Depends(admin_owned_office)]` where admin_owned_office takes `admin: AdminUser`.
+ * An alias whose own name reads as a check counts too (`AdminAccess = Annotated[dict, Depends(check)]`),
+ * unless either name says it's a database session (`SqlSessionDep` over `get_sql_session`).
*/
function pyAliasGuards(files, findings) {
const byRepo = new Map(); // repo -> { aliases: Map(name -> {fn, file}), fns: Map(name -> {deps, types}) }
@@ -338,9 +342,10 @@ function pyAliasGuards(files, findings) {
const out = new Map();
for (const [repo, { aliases, fns }] of byRepo) {
const ok = new Map();
- const checks = (fn) => isGuardDep(fn) || (!DB_DEPENDENCY.test(fn) && !!fns.get(fn) && (fns.get(fn).deps.some(isGuardDep) || fns.get(fn).types.some((t) => ok.has(t))));
+ const checks = (fn) => isGuardDep(fn) || (!isDbDep(fn) && !!fns.get(fn) && (fns.get(fn).deps.some(isGuardDep) || fns.get(fn).types.some((t) => ok.has(t))));
+ const aliasChecks = (name, fn) => checks(fn) || (isGuardDep(name) && !isDbDep(fn));
// a few passes, so aliases built on other aliases resolve in any file order
- for (let pass = 0; pass < 3; pass++) for (const [name, a] of aliases) if (!ok.has(name) && checks(a.fn)) ok.set(name, a.file);
+ for (let pass = 0; pass < 3; pass++) for (const [name, a] of aliases) if (!ok.has(name) && aliasChecks(name, a.fn)) ok.set(name, a.file);
if (ok.size) out.set(repo, ok);
}
return out;
diff --git a/tests/fixtures/fastapi-annotated/app/main.py b/tests/fixtures/fastapi-annotated/app/main.py
index 5c4747c..e73c7ee 100644
--- a/tests/fixtures/fastapi-annotated/app/main.py
+++ b/tests/fixtures/fastapi-annotated/app/main.py
@@ -1,9 +1,11 @@
from fastapi import FastAPI
-from app.routers import feedback, notes, offices, things
+from app.routers import comments, feedback, notes, offices, reports, things
app = FastAPI()
app.include_router(things.router)
app.include_router(notes.router)
app.include_router(offices.router)
app.include_router(feedback.router)
+app.include_router(reports.router)
+app.include_router(comments.router)
diff --git a/tests/fixtures/fastapi-annotated/app/routers/comments.py b/tests/fixtures/fastapi-annotated/app/routers/comments.py
new file mode 100644
index 0000000..1ff2380
--- /dev/null
+++ b/tests/fixtures/fastapi-annotated/app/routers/comments.py
@@ -0,0 +1,22 @@
+"""Really open: only a database session from a less common helper name. Health must still flag it."""
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from sqlmodel import Session
+
+from app.deps import engine
+
+router = APIRouter()
+
+
+def get_sql_session():
+ with Session(engine) as session:
+ yield session
+
+
+SqlSessionDep = Annotated[Session, Depends(get_sql_session)]
+
+
[email protected]("/comments")
+async def add_comment(text: str, db: SqlSessionDep):
+ return {"ok": True}
diff --git a/tests/fixtures/fastapi-annotated/app/routers/reports.py b/tests/fixtures/fastapi-annotated/app/routers/reports.py
new file mode 100644
index 0000000..7895043
--- /dev/null
+++ b/tests/fixtures/fastapi-annotated/app/routers/reports.py
@@ -0,0 +1,20 @@
+"""Alias named like a check over a neutrally named function: AdminAccess guards through its own name."""
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Header, HTTPException
+
+router = APIRouter()
+
+
+def check(x_console_token: str = Header(...)):
+ if not x_console_token:
+ raise HTTPException(status_code=403)
+ return {"console": True}
+
+
+AdminAccess = Annotated[dict, Depends(check)]
+
+
[email protected]("/reports")
+async def create_report(title: str, access: AdminAccess):
+ return {"title": title}
diff --git a/tests/health.test.mjs b/tests/health.test.mjs
index 450c2b4..5665a9e 100644
--- a/tests/health.test.mjs
+++ b/tests/health.test.mjs
@@ -37,8 +37,9 @@ function openEndpoints(graph) {
test('FastAPI: Annotated dependency aliases count as sign-in checks (#4)', () => {
const graph = buildFixture('fastapi-annotated');
- assert.ok(graph.routes.length >= 5, `expected the sample's 5 endpoints, found ${graph.routes.length}`);
- // imported alias (AdminUser), same-file alias (MemberUser) and an alias whose dependency takes
- // AdminUser (OwnedOffice) are all protected; a route with only a database session (SessionDep) isn't
- assert.deepEqual(openEndpoints(graph), ['POST /feedback']);
+ assert.ok(graph.routes.length >= 7, `expected the sample's 7 endpoints, found ${graph.routes.length}`);
+ // imported alias (AdminUser), same-file alias (MemberUser), an alias whose dependency takes
+ // AdminUser (OwnedOffice) and an alias whose own name reads as a check (AdminAccess) are all protected;
+ // routes with only a database session (SessionDep, SqlSessionDep over get_sql_session) aren't
+ assert.deepEqual(openEndpoints(graph), ['POST /comments', 'POST /feedback']);
});