bmsdna-devtools 0.30.0__tar.gz → 0.31.0__tar.gz

{bmsdna_devtools-0.30.0 → bmsdna_devtools-0.31.0}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.5
 Name: bmsdna-devtools
-Version: 0.30.0
+Version: 0.31.0
 Summary: Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects
 Requires-Python: >=3.14
 Requires-Dist: pgdevkit[db]>=0.7.1
 Requires-Dist: requests>=2.32.0
 Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli-w>=1.0.0
 Requires-Dist: typer>=0.26.7
 Provides-Extra: lint
 Requires-Dist: sqlglot>=27.0.0; extra == 'lint'
@@ -18,7 +19,8 @@ one-shot PR summary (`bdt pr info`), PR creation, claiming an issue (`bdt issue
 merged-worktree/orphaned-test-DB cleanup), a commit-and-push helper with
 pre-flight checks, Azure log queries, and static checks (`bdt lint`) for
 postgres/psycopg SQL rules, pydantic-model placement, hand-wired HTTP access in
-TypeScript, and baseline tooling.
+TypeScript and baseline tooling, plus `bdt dead-code` for `.sql` files nothing loads and
+backend routes nothing calls.
 `bdt pr *` and `bdt issue *` auto-detect whether the current repo's `origin`
 remote is Azure DevOps or GitHub and use `az`/`gh` accordingly.
 Consolidates near-duplicate scripts that used to be copy-pasted across
@@ -48,11 +50,12 @@ Find the PR opened from the current branch and report build/check status
 GitHub — whichever `origin` points at.
 
 ```bash
-bdt pr status [--target-branch dev] [--wait]
+bdt pr status [--target-branch BRANCH] [--wait]
 ```
 
-Every `--target` / `--target-branch` option in bdt (`pr create/status/info/retry/publish/update/comment/watch-deploy`,
-`issue take`, `commit`) defaults to `dev`; pass `--target main` (or whatever your PRs go into) to override.
+The `--target` / `--target-branch` option of `pr create/retry/publish/update/comment/watch-deploy` and `commit`
+defaults to `dev`; pass `--target main` (or whatever your PRs go into) to override. `pr status`, `pr info` and
+`issue take` only look a PR up, so by default they don't filter on the target branch at all.
 
 If the PR can't be merged, that's reported immediately instead of polling
 for builds/checks that will never run — e.g. on Azure DevOps:
@@ -73,7 +76,7 @@ one is also waiting on approval.
 `*.visualstudio.com` HTTPS forms). Auth is an explicit PAT (`--pat` or
 `AZURE_DEVOPS_EXT_PAT`/`AZURE_DEVOPS_PAT` env var), falling back to a short-lived token from the
 caller's own `az login` — never embed a PAT literal in a script or CI file.
-`--target-branch` selects which PR to look at (ADO's search API needs one).
+`--target-branch` optionally restricts the lookup to PRs into that branch (default: any).
 
 **GitHub**: uses `gh`'s own auth (`gh auth login`) and always resolves the
 PR opened from the current branch — `gh pr view` has no target-branch
@@ -91,7 +94,7 @@ it watches a branch-triggered build/workflow run, not any particular PR.)
 ## `bdt pr info`
 
 ```bash
-bdt pr info [--json] [--pr-id N] [--target-branch dev]
+bdt pr info [--json] [--pr-id N] [--target-branch BRANCH]
 ```
 
 One-shot summary of the current branch's PR: link, state (open/merged/closed, draft), aggregate
@@ -102,7 +105,7 @@ the check rollup (only a failed check fails it; skipped/cancelled ones don't cou
 from the latest build of each pipeline (any failed result fails it; unfinished builds are pending, or
 `waiting` when a stage needs approval). `unknown` if Azure DevOps can't be asked.
 
-Azure DevOps limits: the PR is found by the current branch into `--target-branch` (default `dev`),
+Azure DevOps limits: the PR is found by the current branch (into `--target-branch` if given, else any target),
 a PR with merge conflicts is reported as an error (exit 1) like `pr status` does, and the closed
 work items are only those whose URL is in the PR description -- not ones linked via
 `bdt pr create --issue`.
@@ -323,12 +326,12 @@ last argument); extra args are passed through; `--dry-run` prints the command.
 It takes the issue first (like `bdt issue take`): before the agent starts it comments `Taken by <you>`
 on the issue, naming the session it is about to start -- for `claude` a `--session-id` is generated and
 passed, so the comment says `claude --resume <id>`; the prompt tells the agent not to take it again. For
-another `--agent` the comment just says `(via <agent>)`. `--dry-run` posts nothing. Like `issue take`, it doesn't comment again when the newest comment already is a claim.
+another `--agent` the comment just says `(via <agent>)`. `--dry-run` posts nothing. Like `issue take`, it doesn't comment again when the newest comment already is your claim; if it is someone else's, it stops (exit 1) unless `--force`.
 
 ## `bdt issue take`
 
 ```bash
-bdt issue take [NUMBER] [--target-branch dev]
+bdt issue take [NUMBER] [--target-branch BRANCH] [--force]
 ```
 
 Claims an issue (GitHub) or work item (Azure DevOps): comments `Taken by <you>` on it, followed by the
@@ -340,6 +343,43 @@ branch's PR closes (`Fixes #N`, or an issue/work-item URL in the PR body); it re
 that is none or several. If the issue's newest comment already is a "Taken by ..." claim (by anyone) it
 says so and posts nothing, so it's safe to run repeatedly -- including before `bdt issue do`.
 
+## `bdt translate`
+
+One `translations.toml` is the source of truth for all UI translations; `bdt translate` generates the
+per-language `de.json` / `en.json` / ... files from it. The generated files are build artifacts --
+add them to `.gitignore` and run `bdt translate` in your `just install` / build / CI steps.
+
+```toml
+# translations.toml (keys with dots must be quoted when `nested = true`)
+[ADD_BUTTON]
+en = "Add"
+de = "Hinzufügen"
+fr = "Ajouter"
+it = "Aggiungi"
+server_only = true   # optional: never emitted into the JSON files (backend-only text)
+```
+
+```toml
+# pyproject.toml
+[tool.bdt.translate]
+file = "translations.toml"             # default
+languages = ["en", "de", "fr", "it"]   # default
+required_languages = ["en"]            # default; `bdt translate add` fails without these
+output = ["frontend/src/assets/i18n"]  # directories receiving <lng>.json
+nested = false                         # true: "a.b.c" keys become nested JSON objects
+scan = ["frontend/src"]                # t("KEY") / $t("KEY") in .ts/.tsx/.js/.jsx/.vue
+scan_jinja = ["backend/print"]         # "KEY" | tr in .jinja2/.j2/.html
+```
+
+- A missing language falls back to `de`, then `en`, then the key itself.
+- Keys used in code but absent from `translations.toml` are appended with an English placeholder and
+  the command exits 1 without generating anything -- fill in the translations and rerun.
+- `bdt translate add KEY en=Add de=Hinzufügen fr=Ajouter it=Aggiungi` adds a key to `translations.toml` and
+  regenerates all JSON files in one go (the `required_languages` are mandatory; `--force` overwrites an existing key).
+- `bdt translate --check` writes nothing and exits 1 if code uses keys missing from the toml (for CI).
+- `bdt translate --import` merges existing `<lng>.json` files into `translations.toml` once, to migrate
+  a repo that so far hand-maintained its JSON files; then `git rm --cached` them and ignore them.
+
 ## `bdt worktree`
 
 ```bash
@@ -571,8 +611,9 @@ bdt logs fetch --env prod --out logs/ --keep-archive
 ## `bdt lint`
 
 Static checks (implementing [bmsuisse/skills#52](https://github.com/bmsuisse/skills/issues/52))
-for the `postgres-best-practices` skill's SQL rules, pydantic-model placement, and
-that the repo has its baseline tooling actually set up:
+for the `postgres-best-practices` skill's SQL rules, pydantic-model placement, hand-wired HTTP in
+TypeScript, and that the repo has its baseline tooling actually set up. Unused `.sql` files and
+dead backend routes are a separate command, [`bdt dead-code`](#bdt-dead-code):
 
 ```bash
 bdt lint                       # scan the current directory, recursively
@@ -661,6 +702,112 @@ already pulled in transitively via `pgdevkit[db]`, but declared explicitly as
 the `bmsdna-devtools[lint]` extra; a clear install hint is printed (not a raw
 `ImportError`) if it's ever missing.
 
+## `bdt dead-code`
+
+Dead code a linter can't see, in one command and one config table, `[tool.bdt.dead_code]`:
+
+- **`sql`** -- `.sql` files that no Python code loads;
+- **`routes`** -- backend (FastAPI) routes that neither non-generated frontend code nor a `url_for(...)`
+  call uses.
+
+Each check runs when it is configured (`sql_roots`, resp. `[[tool.bdt.dead_code.apps]]`); `--only sql` /
+`--only routes` (repeatable) narrows a run, e.g. to keep the slow one -- `routes` imports the app, so run
+`bdt` with the repo's own interpreter (`uv run bdt dead-code`) -- out of a prek hook. Exit code is 0 (clean), 1
+(findings) or 2 (setup problem: invalid config or pyproject.toml, nothing configured, the app doesn't import
+within 5 minutes -- the error shows the import's output).
+
+### `sql` -- unreferenced `.sql` files
+
+A `.sql` file that no Python code loads is a query left behind after its caller was deleted or renamed. Name the
+folders that hold *loadable* SQL (not schema/migration scripts, which are applied rather than loaded) and every
+file under them that nothing references is reported (`sql-file-unreferenced`):
+
+```toml
+[tool.bdt.dead_code]
+sql_roots = ["backend/db/queries"]            # repo-relative; a typo'd root is itself reported
+sql_loader_functions = ["load_sql"]           # default; add your own loader's name if it differs
+sql_unreferenced_ignore = ["backend/db/queries/legacy/*.sql"]   # globs for files reached some other way
+# exclude_dirs = ["generated"]                # extra directory names to skip, beyond .venv/node_modules/etc.
+```
+
+A file counts as referenced by a literal `load_sql("topic", "name")` call (positional or `topic=`/`name=`;
+topic = the file's parent directory, name = its stem); by a `load_sql("topic", some_var)` call in a Python file that
+also contains the stem as a string literal (so `name = "a" if x else "b"` and lookup tables work);
+by a string literal that is a path whose trailing segments equal the file's repo-relative path
+(`get_sql_with_prm_list("backend/api/sql/x.sql")`); or by its bare filename as a literal in a
+Python file under the SQL folder's parent (`_SQL_DIR / "x.sql"`). It never executes code, so a
+file reached through a fully computed path is a false positive -- list it in
+`sql_unreferenced_ignore`. References are searched across the whole repo, since the caller can live anywhere.
+A Python file that can't be parsed (including syntax newer than the interpreter running `bdt`) is itself
+reported as `sql-check-python-unparseable`, because references in it are unknown.
+
+### `routes` -- backend routes nobody uses
+
+Backend (FastAPI) operations that **no non-generated frontend code calls and no backend code references by
+name** -- dead routes that still have to be maintained, secured and tested.
+
+```toml
+[[tool.bdt.dead_code.apps]]
+name = "akeneo"                                   # label used in the report
+app = "main_app:app"                              # module:attribute, imported in a subprocess ...
+app_dir = "akeneo_editor/backend"                 # ... with this directory (repo-relative) as cwd/import root
+# openapi = "frontend/openapi.json"               # alternative to `app`: a committed OpenAPI document
+frontends = ["akeneo_editor/frontend/src"]        # repo-relative dirs or globs, e.g. "mdmapp/app/react_apps/*/src"
+exclude_prefixes = ["/external_api"]              # routes meant for other callers (external API, webhooks)
+exclude_tags = ["agent"]                          # e.g. LLM/MCP tools
+exclude_paths = ["/auth/*", "GET /health"]        # fnmatch globs on "/path" or "METHOD /path"
+baseline = "dead-code-baseline.txt"               # optional ratchet, see below
+# env = { SOME_REQUIRED_SETTING = "x" }           # extra environment for importing the app
+# exclude_frontend_globs = ["src/legacy/*"]       # repo-relative frontend files to ignore as callers
+# url_for_functions = ["url_for", "url_path_for"] # default; functions whose first argument names a route
+```
+
+Pair each backend app with *its own* frontends (one `[[...apps]]` entry per backend) -- a route
+called only by another backend's frontend is still unused here.
+
+The backend inventory is `app.openapi()` of the app **and of every mounted sub-app** (with the
+mount prefix), so it needs no committed schema and can't go stale; routes with
+`include_in_schema=False` are not considered.
+
+**Generated code never counts as a caller.** A generated client lists *every* route, so it is
+skipped (`generated/`, `*.gen.*`, `*.generated.*`, `api-types*`, `openapi_schema*`, `*.d.ts`), as are
+tests and e2e specs (`*.test.*`, `*.spec.*`, `__tests__/`, `tests/`, `e2e/`) -- for TypeScript,
+JavaScript and Vue files alike. Comments are blanked before scanning. An operation is called when
+non-generated code of one of the app's frontends has (strongest first):
+
+- **sdk** -- a reference to a hey-api SDK function (read from the `sdk.gen.ts` under that same frontend
+  directory, matched on method *and* url) or one of its react-query helpers (`fooOptions`, `fooMutation`,
+  `fooQueryKey`, ...). Each `frontends` directory is scoped to its own SDK, so two apps that both generate
+  `listItems` aren't confused;
+- **fetch** -- an openapi-fetch call `.GET("/path"` naming this method and path (a `DELETE` of the
+  same path with no call of its own is still reported);
+- **url** -- a string/template literal equal to the path template (any method), e.g. a hand-written
+  `fetch(`/api/x/${id}`)`, `"/api/x/" + id` or an `<a href=...>` -- nested templates like
+  `${qs ? `?a=${b}` : ""}` are handled;
+- **url-sfx** -- a literal (two or more segments) that is a suffix of the route (a client with a base URL,
+  or a `${base}` prefix).
+
+**Routes the backend refers to by name are used, too.** Auth redirects and OAuth callbacks have no frontend caller
+by nature -- the backend builds their URL: `request.url_for("auth_callback")`, `app.url_path_for("login")`,
+`{{ url_for('login') }}` in a template. A string literal passed (first argument, or `name=`) to one of
+`url_for_functions` in a non-test Python file or Jinja-style template (`.html`, `.jinja`, `.jinja2`, `.j2`) under the app's `app_dir`
+marks the route of that name as used (`"mount:name"` for a mounted sub-app counts as `name`). The route name is recovered from
+its `operationId`: FastAPI's default `name + path + method` form, a bare `name`, or `<prefix>-<name>` from a custom
+`generate_unique_id`; an OpenAPI file without operation ids can't be matched this way. It is a text match, so a call
+in a comment counts too.
+
+It is a heuristic: no type information, a URL literal matches every method of that path (and so does an
+SPA `<Link to="/users/${id}">`), and URLs assembled from non-literal pieces (including a non-literal route
+name in `url_for`) or handed to the client by the server are invisible -- exclude those routes explicitly. An app
+that exposes no documented operations (e.g. one wrapped in middleware that hides `openapi()`) is a setup error,
+not a clean pass. Run against our repos, the usual legitimate exclusions are health checks, the SPA
+catch-all, service-to-service endpoints and an external API folder.
+
+**Adopting it without fixing everything first:** set `baseline`, run
+`uv run bdt dead-code --update-baseline` once (it concerns the `routes` check only), and commit the file. From
+then on only *new* unused routes fail -- and a baseline line whose route has since been deleted, excluded or
+used is reported as `api-route-baseline-stale`, so the list can only shrink.
+
 ## `bdt find-injection`
 
 Scans backend and frontend code for injection risks, and warns when a web project has no

{bmsdna_devtools-0.30.0 → bmsdna_devtools-0.31.0}/README.md

@@ -5,7 +5,8 @@ one-shot PR summary (`bdt pr info`), PR creation, claiming an issue (`bdt issue
 merged-worktree/orphaned-test-DB cleanup), a commit-and-push helper with
 pre-flight checks, Azure log queries, and static checks (`bdt lint`) for
 postgres/psycopg SQL rules, pydantic-model placement, hand-wired HTTP access in
-TypeScript, and baseline tooling.
+TypeScript and baseline tooling, plus `bdt dead-code` for `.sql` files nothing loads and
+backend routes nothing calls.
 `bdt pr *` and `bdt issue *` auto-detect whether the current repo's `origin`
 remote is Azure DevOps or GitHub and use `az`/`gh` accordingly.
 Consolidates near-duplicate scripts that used to be copy-pasted across
@@ -35,11 +36,12 @@ Find the PR opened from the current branch and report build/check status
 GitHub — whichever `origin` points at.
 
 ```bash
-bdt pr status [--target-branch dev] [--wait]
+bdt pr status [--target-branch BRANCH] [--wait]
 ```
 
-Every `--target` / `--target-branch` option in bdt (`pr create/status/info/retry/publish/update/comment/watch-deploy`,
-`issue take`, `commit`) defaults to `dev`; pass `--target main` (or whatever your PRs go into) to override.
+The `--target` / `--target-branch` option of `pr create/retry/publish/update/comment/watch-deploy` and `commit`
+defaults to `dev`; pass `--target main` (or whatever your PRs go into) to override. `pr status`, `pr info` and
+`issue take` only look a PR up, so by default they don't filter on the target branch at all.
 
 If the PR can't be merged, that's reported immediately instead of polling
 for builds/checks that will never run — e.g. on Azure DevOps:
@@ -60,7 +62,7 @@ one is also waiting on approval.
 `*.visualstudio.com` HTTPS forms). Auth is an explicit PAT (`--pat` or
 `AZURE_DEVOPS_EXT_PAT`/`AZURE_DEVOPS_PAT` env var), falling back to a short-lived token from the
 caller's own `az login` — never embed a PAT literal in a script or CI file.
-`--target-branch` selects which PR to look at (ADO's search API needs one).
+`--target-branch` optionally restricts the lookup to PRs into that branch (default: any).
 
 **GitHub**: uses `gh`'s own auth (`gh auth login`) and always resolves the
 PR opened from the current branch — `gh pr view` has no target-branch
@@ -78,7 +80,7 @@ it watches a branch-triggered build/workflow run, not any particular PR.)
 ## `bdt pr info`
 
 ```bash
-bdt pr info [--json] [--pr-id N] [--target-branch dev]
+bdt pr info [--json] [--pr-id N] [--target-branch BRANCH]
 ```
 
 One-shot summary of the current branch's PR: link, state (open/merged/closed, draft), aggregate
@@ -89,7 +91,7 @@ the check rollup (only a failed check fails it; skipped/cancelled ones don't cou
 from the latest build of each pipeline (any failed result fails it; unfinished builds are pending, or
 `waiting` when a stage needs approval). `unknown` if Azure DevOps can't be asked.
 
-Azure DevOps limits: the PR is found by the current branch into `--target-branch` (default `dev`),
+Azure DevOps limits: the PR is found by the current branch (into `--target-branch` if given, else any target),
 a PR with merge conflicts is reported as an error (exit 1) like `pr status` does, and the closed
 work items are only those whose URL is in the PR description -- not ones linked via
 `bdt pr create --issue`.
@@ -310,12 +312,12 @@ last argument); extra args are passed through; `--dry-run` prints the command.
 It takes the issue first (like `bdt issue take`): before the agent starts it comments `Taken by <you>`
 on the issue, naming the session it is about to start -- for `claude` a `--session-id` is generated and
 passed, so the comment says `claude --resume <id>`; the prompt tells the agent not to take it again. For
-another `--agent` the comment just says `(via <agent>)`. `--dry-run` posts nothing. Like `issue take`, it doesn't comment again when the newest comment already is a claim.
+another `--agent` the comment just says `(via <agent>)`. `--dry-run` posts nothing. Like `issue take`, it doesn't comment again when the newest comment already is your claim; if it is someone else's, it stops (exit 1) unless `--force`.
 
 ## `bdt issue take`
 
 ```bash
-bdt issue take [NUMBER] [--target-branch dev]
+bdt issue take [NUMBER] [--target-branch BRANCH] [--force]
 ```
 
 Claims an issue (GitHub) or work item (Azure DevOps): comments `Taken by <you>` on it, followed by the
@@ -327,6 +329,43 @@ branch's PR closes (`Fixes #N`, or an issue/work-item URL in the PR body); it re
 that is none or several. If the issue's newest comment already is a "Taken by ..." claim (by anyone) it
 says so and posts nothing, so it's safe to run repeatedly -- including before `bdt issue do`.
 
+## `bdt translate`
+
+One `translations.toml` is the source of truth for all UI translations; `bdt translate` generates the
+per-language `de.json` / `en.json` / ... files from it. The generated files are build artifacts --
+add them to `.gitignore` and run `bdt translate` in your `just install` / build / CI steps.
+
+```toml
+# translations.toml (keys with dots must be quoted when `nested = true`)
+[ADD_BUTTON]
+en = "Add"
+de = "Hinzufügen"
+fr = "Ajouter"
+it = "Aggiungi"
+server_only = true   # optional: never emitted into the JSON files (backend-only text)
+```
+
+```toml
+# pyproject.toml
+[tool.bdt.translate]
+file = "translations.toml"             # default
+languages = ["en", "de", "fr", "it"]   # default
+required_languages = ["en"]            # default; `bdt translate add` fails without these
+output = ["frontend/src/assets/i18n"]  # directories receiving <lng>.json
+nested = false                         # true: "a.b.c" keys become nested JSON objects
+scan = ["frontend/src"]                # t("KEY") / $t("KEY") in .ts/.tsx/.js/.jsx/.vue
+scan_jinja = ["backend/print"]         # "KEY" | tr in .jinja2/.j2/.html
+```
+
+- A missing language falls back to `de`, then `en`, then the key itself.
+- Keys used in code but absent from `translations.toml` are appended with an English placeholder and
+  the command exits 1 without generating anything -- fill in the translations and rerun.
+- `bdt translate add KEY en=Add de=Hinzufügen fr=Ajouter it=Aggiungi` adds a key to `translations.toml` and
+  regenerates all JSON files in one go (the `required_languages` are mandatory; `--force` overwrites an existing key).
+- `bdt translate --check` writes nothing and exits 1 if code uses keys missing from the toml (for CI).
+- `bdt translate --import` merges existing `<lng>.json` files into `translations.toml` once, to migrate
+  a repo that so far hand-maintained its JSON files; then `git rm --cached` them and ignore them.
+
 ## `bdt worktree`
 
 ```bash
@@ -558,8 +597,9 @@ bdt logs fetch --env prod --out logs/ --keep-archive
 ## `bdt lint`
 
 Static checks (implementing [bmsuisse/skills#52](https://github.com/bmsuisse/skills/issues/52))
-for the `postgres-best-practices` skill's SQL rules, pydantic-model placement, and
-that the repo has its baseline tooling actually set up:
+for the `postgres-best-practices` skill's SQL rules, pydantic-model placement, hand-wired HTTP in
+TypeScript, and that the repo has its baseline tooling actually set up. Unused `.sql` files and
+dead backend routes are a separate command, [`bdt dead-code`](#bdt-dead-code):
 
 ```bash
 bdt lint                       # scan the current directory, recursively
@@ -648,6 +688,112 @@ already pulled in transitively via `pgdevkit[db]`, but declared explicitly as
 the `bmsdna-devtools[lint]` extra; a clear install hint is printed (not a raw
 `ImportError`) if it's ever missing.
 
+## `bdt dead-code`
+
+Dead code a linter can't see, in one command and one config table, `[tool.bdt.dead_code]`:
+
+- **`sql`** -- `.sql` files that no Python code loads;
+- **`routes`** -- backend (FastAPI) routes that neither non-generated frontend code nor a `url_for(...)`
+  call uses.
+
+Each check runs when it is configured (`sql_roots`, resp. `[[tool.bdt.dead_code.apps]]`); `--only sql` /
+`--only routes` (repeatable) narrows a run, e.g. to keep the slow one -- `routes` imports the app, so run
+`bdt` with the repo's own interpreter (`uv run bdt dead-code`) -- out of a prek hook. Exit code is 0 (clean), 1
+(findings) or 2 (setup problem: invalid config or pyproject.toml, nothing configured, the app doesn't import
+within 5 minutes -- the error shows the import's output).
+
+### `sql` -- unreferenced `.sql` files
+
+A `.sql` file that no Python code loads is a query left behind after its caller was deleted or renamed. Name the
+folders that hold *loadable* SQL (not schema/migration scripts, which are applied rather than loaded) and every
+file under them that nothing references is reported (`sql-file-unreferenced`):
+
+```toml
+[tool.bdt.dead_code]
+sql_roots = ["backend/db/queries"]            # repo-relative; a typo'd root is itself reported
+sql_loader_functions = ["load_sql"]           # default; add your own loader's name if it differs
+sql_unreferenced_ignore = ["backend/db/queries/legacy/*.sql"]   # globs for files reached some other way
+# exclude_dirs = ["generated"]                # extra directory names to skip, beyond .venv/node_modules/etc.
+```
+
+A file counts as referenced by a literal `load_sql("topic", "name")` call (positional or `topic=`/`name=`;
+topic = the file's parent directory, name = its stem); by a `load_sql("topic", some_var)` call in a Python file that
+also contains the stem as a string literal (so `name = "a" if x else "b"` and lookup tables work);
+by a string literal that is a path whose trailing segments equal the file's repo-relative path
+(`get_sql_with_prm_list("backend/api/sql/x.sql")`); or by its bare filename as a literal in a
+Python file under the SQL folder's parent (`_SQL_DIR / "x.sql"`). It never executes code, so a
+file reached through a fully computed path is a false positive -- list it in
+`sql_unreferenced_ignore`. References are searched across the whole repo, since the caller can live anywhere.
+A Python file that can't be parsed (including syntax newer than the interpreter running `bdt`) is itself
+reported as `sql-check-python-unparseable`, because references in it are unknown.
+
+### `routes` -- backend routes nobody uses
+
+Backend (FastAPI) operations that **no non-generated frontend code calls and no backend code references by
+name** -- dead routes that still have to be maintained, secured and tested.
+
+```toml
+[[tool.bdt.dead_code.apps]]
+name = "akeneo"                                   # label used in the report
+app = "main_app:app"                              # module:attribute, imported in a subprocess ...
+app_dir = "akeneo_editor/backend"                 # ... with this directory (repo-relative) as cwd/import root
+# openapi = "frontend/openapi.json"               # alternative to `app`: a committed OpenAPI document
+frontends = ["akeneo_editor/frontend/src"]        # repo-relative dirs or globs, e.g. "mdmapp/app/react_apps/*/src"
+exclude_prefixes = ["/external_api"]              # routes meant for other callers (external API, webhooks)
+exclude_tags = ["agent"]                          # e.g. LLM/MCP tools
+exclude_paths = ["/auth/*", "GET /health"]        # fnmatch globs on "/path" or "METHOD /path"
+baseline = "dead-code-baseline.txt"               # optional ratchet, see below
+# env = { SOME_REQUIRED_SETTING = "x" }           # extra environment for importing the app
+# exclude_frontend_globs = ["src/legacy/*"]       # repo-relative frontend files to ignore as callers
+# url_for_functions = ["url_for", "url_path_for"] # default; functions whose first argument names a route
+```
+
+Pair each backend app with *its own* frontends (one `[[...apps]]` entry per backend) -- a route
+called only by another backend's frontend is still unused here.
+
+The backend inventory is `app.openapi()` of the app **and of every mounted sub-app** (with the
+mount prefix), so it needs no committed schema and can't go stale; routes with
+`include_in_schema=False` are not considered.
+
+**Generated code never counts as a caller.** A generated client lists *every* route, so it is
+skipped (`generated/`, `*.gen.*`, `*.generated.*`, `api-types*`, `openapi_schema*`, `*.d.ts`), as are
+tests and e2e specs (`*.test.*`, `*.spec.*`, `__tests__/`, `tests/`, `e2e/`) -- for TypeScript,
+JavaScript and Vue files alike. Comments are blanked before scanning. An operation is called when
+non-generated code of one of the app's frontends has (strongest first):
+
+- **sdk** -- a reference to a hey-api SDK function (read from the `sdk.gen.ts` under that same frontend
+  directory, matched on method *and* url) or one of its react-query helpers (`fooOptions`, `fooMutation`,
+  `fooQueryKey`, ...). Each `frontends` directory is scoped to its own SDK, so two apps that both generate
+  `listItems` aren't confused;
+- **fetch** -- an openapi-fetch call `.GET("/path"` naming this method and path (a `DELETE` of the
+  same path with no call of its own is still reported);
+- **url** -- a string/template literal equal to the path template (any method), e.g. a hand-written
+  `fetch(`/api/x/${id}`)`, `"/api/x/" + id` or an `<a href=...>` -- nested templates like
+  `${qs ? `?a=${b}` : ""}` are handled;
+- **url-sfx** -- a literal (two or more segments) that is a suffix of the route (a client with a base URL,
+  or a `${base}` prefix).
+
+**Routes the backend refers to by name are used, too.** Auth redirects and OAuth callbacks have no frontend caller
+by nature -- the backend builds their URL: `request.url_for("auth_callback")`, `app.url_path_for("login")`,
+`{{ url_for('login') }}` in a template. A string literal passed (first argument, or `name=`) to one of
+`url_for_functions` in a non-test Python file or Jinja-style template (`.html`, `.jinja`, `.jinja2`, `.j2`) under the app's `app_dir`
+marks the route of that name as used (`"mount:name"` for a mounted sub-app counts as `name`). The route name is recovered from
+its `operationId`: FastAPI's default `name + path + method` form, a bare `name`, or `<prefix>-<name>` from a custom
+`generate_unique_id`; an OpenAPI file without operation ids can't be matched this way. It is a text match, so a call
+in a comment counts too.
+
+It is a heuristic: no type information, a URL literal matches every method of that path (and so does an
+SPA `<Link to="/users/${id}">`), and URLs assembled from non-literal pieces (including a non-literal route
+name in `url_for`) or handed to the client by the server are invisible -- exclude those routes explicitly. An app
+that exposes no documented operations (e.g. one wrapped in middleware that hides `openapi()`) is a setup error,
+not a clean pass. Run against our repos, the usual legitimate exclusions are health checks, the SPA
+catch-all, service-to-service endpoints and an external API folder.
+
+**Adopting it without fixing everything first:** set `baseline`, run
+`uv run bdt dead-code --update-baseline` once (it concerns the `routes` check only), and commit the file. From
+then on only *new* unused routes fail -- and a baseline line whose route has since been deleted, excluded or
+used is reported as `api-route-baseline-stale`, so the list can only shrink.
+
 ## `bdt find-injection`
 
 Scans backend and frontend code for injection risks, and warns when a web project has no

bmsdna_devtools-0.31.0/bmsdna/devtools/_api_dump.py

@@ -0,0 +1,58 @@
+"""Standalone (stdlib-only) helper of the `routes` check of `bdt dead-code`: list the documented HTTP operations of a
+FastAPI-like app, recursing into mounted sub-apps.
+
+It is executed in the *target repo's* interpreter via `python -c <this file's source> module:attr out.json`
+and must therefore never import `bmsdna.devtools`: the working directory is first on `sys.path` there, and a repo may
+ship its own top-level `bmsdna` package (CCMT2 does) that would shadow ours. `api_usage` imports it normally for
+`ops_from_doc`, so the OpenAPI-document parsing exists exactly once.
+"""
+
+import importlib
+import json
+import sys
+
+HTTP_METHODS = ("get", "post", "put", "patch", "delete", "options", "head")
+
+
+def ops_from_doc(doc, mount=""):
+    """Operations of one OpenAPI document as dicts, with `mount` prepended to every path."""
+    ops = []
+    for path, item in (doc.get("paths") or {}).items():
+        for method, op in item.items():
+            if method in HTTP_METHODS and isinstance(op, dict):
+                ops.append(
+                    {
+                        "method": method.upper(),
+                        "path": mount + path,
+                        "tags": list(op.get("tags") or []),
+                        "mount": mount,
+                        "operation_id": str(op.get("operationId") or ""),
+                    }
+                )
+    return ops
+
+
+def collect(app, mount=""):
+    """Operations of `app` and, recursively, of every mounted sub-app. Uses only `app.openapi()` and the
+    `.path`/`.app` attributes of mount routes -- not FastAPI internals, which change between releases (FastAPI 0.141 wraps
+    included routers in lazy objects that `app.routes` no longer lists as plain routes)."""
+    openapi = getattr(app, "openapi", None)
+    if not callable(openapi):
+        return []
+    ops = ops_from_doc(openapi(), mount)
+    for route in getattr(app, "routes", None) or []:
+        sub = getattr(route, "app", None)
+        if sub is not None and callable(getattr(sub, "openapi", None)) and isinstance(getattr(route, "path", None), str):
+            ops.extend(collect(sub, mount + route.path.rstrip("/")))
+    return ops
+
+
+def main(argv):
+    module_name, _, attr = argv[0].partition(":")
+    app = getattr(importlib.import_module(module_name), attr)
+    with open(argv[1], "w", encoding="utf-8") as out:
+        json.dump(collect(app), out)
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])