@sitar_fiercer4c/skills 0.1.0

package/skills/backend-code-review/references/report-format.md

@@ -0,0 +1,333 @@
+# Report format
+
+The shape below is the output contract. It came out of three rounds of a reader reacting to
+drafts, and each part of it earns its place — the notes explain what each is for so you can
+tell when a deviation is reasonable.
+
+## Contents
+
+- [Skeleton](#skeleton)
+- [Severity model](#severity-model)
+- [The MVCS skeleton](#the-mvcs-skeleton)
+- [Finding tables](#finding-tables)
+  - [What the Location column asserts](#what-the-location-column-asserts)
+  - [Rows whose claim names a set](#rows-whose-claim-names-a-set)
+  - [Two things every repair does](#two-things-every-repair-does)
+- [Worked example rows](#worked-example-rows)
+- [Inventory tables are transcribed, not typed](#inventory-tables-are-transcribed-not-typed)
+- [Closing sections](#closing-sections)
+
+---
+
+## Skeleton
+
+````markdown
+# Route Review — <scope, e.g. "full HTTP surface" or "POST surface">
+
+**Target:** <absolute path to the backend root>
+**Rules applied:** <path to code-rules.md> — <one-line paraphrase of the layering it mandates>
+**Scope:** all N routes across the M route files, plus the K routes defined inline in `<entrypoint>`.
+
+| Severity | Count | Meaning |
+|---|---|---|
+| 🔴 | N | Rule violation, security defect, or correctness bug |
+| 🟡 | N | Rule drift, duplication, fragile coupling |
+| ⚠️ | N | Observation / nit / inconsistency |
+| ✅ | N | Verified correct — worth keeping as-is |
+
+---
+
+## Route inventory
+
+| # | Method | Path (as mounted) | File:line | Auth | Validator |
+|---|---|---|---|---|---|
+| 1 | POST | `/api/auth/register` | `auth.routes.js:13` | — | ✅ |
+...
+
+**<X> of <N> routes have a validator.** <One sentence naming where they cluster, if they do.>
+
+---
+
+## Config
+*Methodology not yet established — this section was not reviewed.*
+
+## Controllers
+*Methodology not yet established — this section was not reviewed.*
+
+## Middleware
+*Methodology not yet established — this section was not reviewed.*
+
+## Models
+*Methodology not yet established — this section was not reviewed.*
+
+## Routes
+
+### `src/routes/<file>.js`
+
+> <Any file-level fact that changes how every route in it reads — most often the mount
+> prefix, when it differs from what the file's own comments claim.>
+
+#### `<METHOD> <path>` — line N
+`<middleware chain> → <controller>.<handler>`
+
+| Sev | Rule | Location | Finding |
+|---|---|---|---|
+| 🔴 | <code-rules section> | `file.js:LINE` | <finding> |
+
+### Routes defined in `src/<entrypoint>`
+...
+
+## Services
+*Methodology not yet established — this section was not reviewed.*
+
+## Utils
+*Methodology not yet established — this section was not reviewed.*
+
+## Validators
+*Methodology not yet established — this section was not reviewed.*
+
+---
+
+## Cross-cutting
+
+| Sev | Rule | Location | Finding |
+|---|---|---|---|
+
+---
+
+## Highest-value fixes, in order
+
+1. `file.js:LINE` — <what and why it ranks here>
+
+---
+
+## Notes on inputs
+
+<Anything true about a prior review document, or about the sweep/inventory scripts' own output,
+that a reader of this review needs. Omit the section if there is nothing. Never a finding row.>
+
+---
+
+## Files read for this review
+
+<list>
+
+Not read (referenced only): <list>
+````
+
+---
+
+## Severity model
+
+| Marker | Means |
+|---|---|
+| 🔴 | Rule violation, security defect, or correctness bug |
+| 🟡 | Rule drift, duplication, fragile coupling |
+| ⚠️ | Observation, nit, inconsistency |
+| ✅ | Verified correct — worth keeping as-is |
+
+Put the counts at the top. A reader deciding whether to read 400 lines of tables wants to know
+the shape of what is coming, and the counts are also the honest headline — a review with three
+🔴 and forty ⚠️ is a different message than the reverse, and burying that lets a reader
+mistake volume for severity.
+
+Count as you write rather than estimating up front; the tally has to match the tables or the
+whole document loses credibility on the first thing the reader can check.
+
+**`✅` rows are not padding.** A review listing only faults gives the reader no way to
+distinguish "examined and sound" from "not examined". That ambiguity matters most exactly where
+the stakes are highest — an auth middleware with no findings against it could mean it is
+correct or that nobody read it. Say which. It also makes the review usable as a record of what
+was verified, and it stops a correct-but-unusual construction from being "fixed" later by
+someone who assumes it was overlooked.
+
+Aim to record the non-obvious correct decisions, not every line that works: a security control
+that is properly closed, a guard placed before expensive work, an idempotency mechanism, a
+deliberate departure from a convention that turns out to be right.
+
+A `✅` row names the failure path it followed and what it found there — the catch block, the
+concurrent second caller, the missing-config case. The happy path working is the default, not
+evidence. Because the marker promises "examined and sound", it is the one row type where being
+wrong is worse than being absent: it stops the next reader from looking. Keep its scope to what
+you actually probed and do not let it spill onto adjacent code — a careful streaming mechanism
+can sit inside a `catch` that flattens every error to `404`, and a `✅` on the former reads as
+absolution for the latter.
+
+---
+
+## The MVCS skeleton
+
+The report's H2 headings come from the section list in the target repo's `code-rules.md`, in the
+order that file lists them — not from a fixed list in this skill. A repo whose rules file names
+`jobs` or `adapters` gets those headings.
+
+Every section that was not reviewed still gets its heading, carrying:
+
+```markdown
+*Methodology not yet established — this section was not reviewed.*
+```
+
+This is the point of the skeleton. Without those lines a reader cannot tell an unreviewed
+section from a clean one, and silence reads as a pass. With them, the report doubles as a map of
+how much of the architecture has been covered so far.
+
+---
+
+## Finding tables
+
+One H3 per route file, one H4 per route, one table per route.
+
+Under each H4, restate the middleware chain as `middleware → controller.handler`. It takes one
+line and it means a reader can see the route's full shape without opening the file.
+
+Columns:
+
+| Column | Contents |
+|---|---|
+| **Sev** | One marker. |
+| **Rule** | The `code-rules.md` section the finding is judged against — `routes`, `controllers`, `services`, `validators`, `services (DONTS)`. Use `—` when the finding is a security or correctness issue rather than a layering one. |
+| **Location** | `file.js:LINE` or `file.js:LINE–LINE`. Two locations when the finding is about a relationship (duplication, a helper that exists but is bypassed). `file.js` (absent) when the finding is that something is missing. |
+| **Finding** | Lead with a **bold claim in a few words**, then the evidence, then the consequence, then the repair. |
+
+Order rows within a table by severity, 🔴 first.
+
+The Rule column is what makes this a review against *this repo's stated architecture* rather
+than generic advice. If a finding cannot be tied to a rule and is not a security or correctness
+issue, it is probably a preference — cut it.
+
+### What the Location column asserts
+
+**Every line in a 🔴/🟡 Location is part of the defect.** The column is not "lines relevant to
+this row" — a reader treats each entry as something you are asking them to change, and a line
+folded in for context arrives as an accusation against code that is fine. Contributing context
+goes in the finding body, where it can be labelled as context.
+
+One review put `app.js:20` — `app.set('trust proxy', 1)` — into the Location of a 🟡 about
+rate-limiter keying. The trust-proxy line was background; the defect was elsewhere. The row read
+as "change your trust proxy setting", which was not the finding and was not correct.
+
+**Every path in a Location is under the reviewed source tree.** Two things reliably tempt their
+way into a finding row and do not belong there:
+
+- observations about a *previous review document* ("`ROUTE_REVIEW.md` cites the wrong line")
+- observations about the *tooling* ("`sweep.py` reports this export as used, but that is a false
+  positive")
+
+Both can be worth saying. Neither is a finding about the backend, and a reader scanning for code
+to fix has to stop and work out that this row is not about code. Put them in a `## Notes on
+inputs` section below the tables.
+
+**A row claiming an absence cites the whole construct.** "No `return`", "never calls the
+validator", "lacks a guard" — you can only see an absence across a complete unit. A range that
+stops before the closing brace does not support the claim, because the thing you say is missing
+may be on the next line, and that is precisely how one review reported a function as missing its
+`return results;` when the return was one line past the cited range. Cite from the signature to
+the closing brace, and quote the closing lines or the command that establishes the absence.
+`scripts/verify_citations.py` flags these; run it before the report is done.
+
+### Rows whose claim names a set
+
+Some findings are about a set rather than a spot: the keys a masking list is missing, the sites a
+duplicated block appears at, the variables a config module reads unguarded, the endpoints without
+a limiter. These are the rows that go wrong most often, and they go wrong the same way every
+time — the set is right minus one. A reader acts on the row, fixes what it names, and the missing
+element survives with the row marked done. That is worse than not raising it, because now nobody
+will look again.
+
+So a row whose claim names a set carries three things:
+
+1. **The count, stated as "N of N"** — "three of the three request keys that reach the logger",
+   not "keys including `code` and `state`". Writing the count forces you to have one.
+2. **Where the set came from**, named in the row: the sweep section, the grep, the inventory
+   column. "From `sweep.py --section request-inputs`" tells the reader the enumeration was
+   mechanical, and tells you that it was.
+3. **One repair clause per element.** If the claim names three keys, the repair names three keys.
+
+A repair with fewer clauses than the claim has elements is an **incomplete finding**, not a
+finding with a shortened repair — the missing clause is the whole cost of the row. This is
+checkable by counting, which is why it is stated this way: "repair the whole finding" is good
+advice that people follow when they remember the third element and not when they don't.
+
+The corollary is that these enumerations come from the scripts, not from recall. Recall is what
+produces "N−1 of N".
+
+### Two things every repair does
+
+**Name what the repair removes, not only what it adds.** A finding says one `JWT_SECRET` signs
+both session tokens and image-proxy tokens; the repair proposes a shared `getJwtSecret()` helper
+imported at all four sites. That is tidier code and the exact same defect — one secret, two token
+types — now with a helper making it convenient. A repair that leaves the complained-of property
+in place is not a repair. Say what stops being true: "image tokens move to `IMAGE_TOKEN_SECRET`,
+so a leaked session key no longer mints image URLs."
+
+**A repair that relocates code quotes the rule that gives the destination its job.** "Move this to
+the service layer" is a guess unless the rules file says the service owns it, and the guess is
+usually the layer you thought of first. Open the rules file, find the section for the destination,
+and quote the sentence. One review moved file-type validation — a `415` thrown on an unexpected
+extension — into a service, when the rules file had a `validators` section describing exactly that
+responsibility; the section was never opened. Quoting it costs one line and makes the repair
+arguable on the repo's own terms instead of on taste.
+
+Beyond those two: every 🔴 and 🟡 row ends in a repair — the function to extract, the module to
+create, the export to narrow, the signature to change. The reader is deciding what to do on
+Monday, and a row that stops at the consequence makes them re-derive a conclusion you already
+reached. If the right repair is genuinely contested, name the options and their costs and say
+which one the rules file favours; that still tells them where to start.
+
+---
+
+## Worked example rows
+
+The specificity below is the target. Each names a location, states what is true there, says what
+it costs, and says what to do — a reader can act on any of them without asking a follow-up
+question.
+
+| Sev | Rule | Location | Finding |
+|---|---|---|---|
+| 🔴 | services | `auth.service.js:76` | **One global secret resets any account.** `secretCode !== process.env.FORGOT_PASSWORD_SECRET_CODE` has no per-user binding, no expiry, no single-use consumption. Anyone who learns it resets every user's password given only an email. Issue a per-user random token instead, stored hashed with an expiry and cleared on use. |
+| 🟡 | services (DONTS) | `quotation.service.js:112, 131, 204, 288` | **Six helpers are exported but only ever called in-file.** `toNonNegativeNumber`, `round2`, `recalcItem`, `sanitizeDescriptionStyle`, `QUOTATION_ITEM_FIELDS`, `QUOTATION_HEADER_FIELDS` have no importer anywhere in `src`, `tests` or `scripts`, yet each has four or five callers inside this module. They are over-exported, not dead: drop them from the `export` block at `:640` and keep every definition. |
+| 🔴 | controllers | `email.controller.js:89` + `:107` | **Two Graph round-trips for one request.** `getAttachmentMetadata` calls `microsoft.getMessage` via `withGraph` (`email.service.js:612`), then `getAttachmentBuffer` runs `withGraph` again (597) — second connection load, second potential token refresh, second call for the same message. Should be one service function returning both. |
+| 🟡 | services / config | `s3Image.service.js:318, 471` vs `auth.middleware.js:20` | **`JWT_SECRET` is reused for two different token types.** Confusion is blocked today only by payload-shape luck — the auth middleware requires `payload.userId` (image tokens lack it) and the image verifier requires `payload.quotationId` (session tokens lack it). Neither check is documented as a security boundary, so a future payload change silently breaks it. `oauthState.js:3` already uses a dedicated secret — follow that. |
+| ✅ | services | `s3Image.service.js:470–495` | **Path traversal is properly closed.** The reconstructed key (488) is compared for equality against the signed `payload.key`, and that key was minted through a `^quotations\/([^/]+)\/images\/([^/]+)$` regex (298). A `..` in `:filename` cannot match a signed key. |
+
+Note what the last row does: it reports a security control that a reviewer would naturally probe,
+and records the specific attack it followed and why that attack fails. That is more useful than
+silence, because the next reader does not have to re-derive it — and it is a `✅` about a failure
+path, not about the code reading well.
+
+Note what the fourth row does — it names an adjacent place in the same codebase that already
+solves the problem correctly. A fix the reader can copy from their own repo lands better than an
+abstract recommendation.
+
+Note what the second row does *not* do: it does not say "delete them". Six exports with no
+importer look dead from outside the file and are not, and a review that says "safe to delete"
+about identifiers with in-file callers hands the reader a change that breaks the module. Naming
+the export block as the thing to edit is what makes the row safe to act on.
+
+---
+
+## Inventory tables are transcribed, not typed
+
+The route inventory, and any per-file handler inventory, take their line numbers from
+`scripts/list_routes.py` output — paste the column, do not retype it from the file you have open.
+
+This sounds pedantic and is not. Inventory rows are where citation errors cluster, because a
+finding's citation gets checked while writing the argument around it and an inventory row gets
+checked by nobody. One review's handler inventory for a single controller was off by three to six
+lines on every row, in a document whose finding citations were almost all exact. A reader who
+opens the first inventory row, lands three lines away, and finds nothing there has no way to know
+the rest of the report is better than this.
+
+---
+
+## Closing sections
+
+**Highest-value fixes, in order.** The tables are organised for lookup, which means they are not
+organised for action — a 🔴 in the last table is no less urgent than one in the first. This
+section is the answer to "what do I do Monday". Rank by exploitability and blast radius rather
+than by severity marker alone: an unauthenticated remote issue outranks an internal layering
+violation even when both are 🔴.
+
+**Files read for this review.** State the blast radius. A reader who knows a service was never
+opened can weigh the review's silence about it correctly. List what was referenced but not read
+separately.

package/skills/backend-code-review/scripts/list_routes.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""Enumerate Express routes with their real mounted paths.
+
+A route's real path is the router's mount prefix plus the path written in the
+route file. Doc comments naming the path drift from the mount point and cannot
+be trusted, so this resolves the prefix from the app entrypoint instead.
+
+Usage:
+    python3 list_routes.py <src-dir> [--json]
+
+Output is a scaffold, not a finding. Regex parsing misses dynamic mounts,
+re-exported routers, and conditionally registered routes, so confirm every row
+against the file before it goes into a review.
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+METHODS = ("get", "post", "put", "patch", "delete", "options", "head", "all")
+
+ENTRYPOINT_NAMES = ("app.js", "server.js", "index.js", "app.ts", "server.ts", "index.ts")
+
+
+def find_call(text, start):
+    """Return (inner_text, end_index) for the parenthesised call starting at `start`.
+
+    `start` is the index of the opening paren. Tracks string literals so a paren
+    or quote inside a route path doesn't unbalance the scan.
+    """
+    depth = 0
+    i = start
+    quote = None
+    while i < len(text):
+        ch = text[i]
+        if quote:
+            if ch == "\\":
+                i += 2
+                continue
+            if ch == quote:
+                quote = None
+        elif ch in "'\"`":
+            quote = ch
+        elif ch == "(":
+            depth += 1
+        elif ch == ")":
+            depth -= 1
+            if depth == 0:
+                return text[start + 1 : i], i
+        i += 1
+    return None, len(text)
+
+
+def split_args(inner):
+    """Split a call's argument list on top-level commas."""
+    args, depth, quote, current = [], 0, None, []
+    for i, ch in enumerate(inner):
+        if quote:
+            current.append(ch)
+            if ch == "\\":
+                continue
+            if ch == quote:
+                quote = None
+            continue
+        if ch in "'\"`":
+            quote = ch
+            current.append(ch)
+            continue
+        if ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+        if ch == "," and depth == 0:
+            args.append("".join(current).strip())
+            current = []
+            continue
+        current.append(ch)
+    if current:
+        args.append("".join(current).strip())
+    return [a for a in args if a]
+
+
+def line_of(text, index):
+    return text.count("\n", 0, index) + 1
+
+
+def strip_quotes(arg):
+    arg = arg.strip()
+    if len(arg) >= 2 and arg[0] in "'\"`" and arg[-1] == arg[0]:
+        return arg[1:-1]
+    return None
+
+
+def clean_ident(arg):
+    """Reduce an argument expression to something readable in a table cell."""
+    arg = " ".join(arg.split())
+    if len(arg) > 40:
+        arg = arg[:37] + "..."
+    return arg
+
+
+def parse_imports(text):
+    """Map imported identifier -> resolved module path fragment."""
+    out = {}
+    for m in re.finditer(r"import\s+(\w+)\s+from\s+['\"]([^'\"]+)['\"]", text):
+        out[m.group(1)] = m.group(2)
+    return out
+
+
+def parse_mounts(entry_text, imports):
+    """Map router identifier -> mount prefix, and collect non-router app.use middleware.
+
+    Returns (mounts, prefix_middleware) where mounts is {identifier: prefix} and
+    prefix_middleware is a list of (prefix, identifier, line) for middleware applied
+    by path prefix rather than inside a route file -- rate limiters, most often.
+    Those are worth surfacing because they are invisible from the route file.
+    """
+    mounts, prefix_middleware = {}, []
+    for m in re.finditer(r"\bapp\.use\s*\(", entry_text):
+        inner, _ = find_call(entry_text, m.end() - 1)
+        if inner is None:
+            continue
+        args = split_args(inner)
+        if len(args) < 2:
+            continue
+        prefix = strip_quotes(args[0])
+        if prefix is None:
+            continue
+        for ident in args[1:]:
+            ident = ident.strip()
+            if not re.fullmatch(r"\w+", ident):
+                continue
+            source = imports.get(ident, "")
+            if "route" in source.lower() or "route" in ident.lower():
+                mounts[ident] = prefix
+            else:
+                prefix_middleware.append(
+                    (prefix, ident, line_of(entry_text, m.start()))
+                )
+    return mounts, prefix_middleware
+
+
+def parse_routes(text, filename, prefix):
+    """Extract route definitions from a router file."""
+    rows = []
+    pattern = re.compile(r"\b(?:router|app)\.(" + "|".join(METHODS) + r")\s*\(")
+    for m in pattern.finditer(text):
+        method = m.group(1).upper()
+        inner, _ = find_call(text, m.end() - 1)
+        if inner is None:
+            continue
+        args = split_args(inner)
+        if not args:
+            continue
+        route_path = strip_quotes(args[0])
+        if route_path is None:
+            continue
+        rest = args[1:]
+        handler = clean_ident(rest[-1]) if rest else ""
+        middleware = [clean_ident(a) for a in rest[:-1]] if len(rest) > 1 else []
+        full = (prefix.rstrip("/") + route_path) if prefix else route_path
+        if not full.startswith("/"):
+            full = "/" + full
+        rows.append(
+            {
+                "method": method,
+                "path": full,
+                "route_path": route_path,
+                "file": filename,
+                "line": line_of(text, m.start()),
+                "middleware": middleware,
+                "handler": handler,
+                "has_auth": any("auth" in x.lower() for x in middleware),
+                "has_validator": any(
+                    "valid" in x.lower() for x in middleware
+                ),
+            }
+        )
+    return rows
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("src", help="backend source directory (the one containing app.js and routes/)")
+    ap.add_argument("--json", action="store_true", help="emit JSON instead of markdown")
+    args = ap.parse_args()
+
+    src = Path(args.src)
+    if not src.is_dir():
+        sys.exit(f"not a directory: {src}")
+
+    entry = next((src / n for n in ENTRYPOINT_NAMES if (src / n).exists()), None)
+    if entry is None:
+        sys.exit(f"no app entrypoint found in {src} (looked for {', '.join(ENTRYPOINT_NAMES)})")
+
+    entry_text = entry.read_text(encoding="utf-8", errors="replace")
+    imports = parse_imports(entry_text)
+    mounts, prefix_middleware = parse_mounts(entry_text, imports)
+
+    rows = []
+
+    # Routes defined inline in the entrypoint. These are worth flagging on sight:
+    # an endpoint outside routes/ has no controller and usually no middleware.
+    for r in parse_routes(entry_text, entry.name, ""):
+        r["inline_in_entrypoint"] = True
+        rows.append(r)
+
+    routes_dir = src / "routes"
+    if routes_dir.is_dir():
+        by_source = {}
+        for ident, prefix in mounts.items():
+            source = imports.get(ident, "")
+            by_source[Path(source).name] = prefix
+
+        for f in sorted(routes_dir.iterdir()):
+            if f.suffix not in (".js", ".ts", ".mjs"):
+                continue
+            prefix = by_source.get(f.name)
+            if prefix is None:
+                prefix = ""
+            text = f.read_text(encoding="utf-8", errors="replace")
+            for r in parse_routes(text, f.name, prefix):
+                r["inline_in_entrypoint"] = False
+                r["mounted"] = f.name in by_source
+                rows.append(r)
+
+    if args.json:
+        print(json.dumps({"routes": rows, "prefix_middleware": prefix_middleware}, indent=2))
+        return
+
+    print(f"# Route inventory — {src}\n")
+    print(f"Entrypoint: `{entry.name}`  ·  {len(rows)} routes\n")
+    print("| # | Method | Path (as mounted) | File:line | Middleware | Handler | Auth | Validator |")
+    print("|---|---|---|---|---|---|---|---|")
+    for i, r in enumerate(rows, 1):
+        mw = ", ".join(f"`{x}`" for x in r["middleware"]) or "—"
+        note = " **(inline)**" if r["inline_in_entrypoint"] else ""
+        print(
+            f"| {i} | {r['method']} | `{r['path']}`{note} | `{r['file']}:{r['line']}` "
+            f"| {mw} | `{r['handler']}` | {'yes' if r['has_auth'] else '—'} "
+            f"| {'yes' if r['has_validator'] else '—'} |"
+        )
+
+    with_validator = sum(1 for r in rows if r["has_validator"])
+    print(f"\n**{with_validator} of {len(rows)} routes have a validator.**")
+
+    unmounted = sorted({r["file"] for r in rows if not r["inline_in_entrypoint"] and not r.get("mounted")})
+    if unmounted:
+        print(
+            f"\n> Could not resolve a mount prefix for: {', '.join(f'`{u}`' for u in unmounted)}. "
+            "Paths above are unprefixed — resolve by hand before using."
+        )
+
+    if prefix_middleware:
+        print("\n## Middleware applied by path prefix\n")
+        print(
+            "Applied in the entrypoint rather than in a route file, so it is invisible "
+            "when reading the route. `app.use` matches all methods and all subpaths.\n"
+        )
+        print("| Prefix | Middleware | Entrypoint line |")
+        print("|---|---|---|")
+        for prefix, ident, line in prefix_middleware:
+            print(f"| `{prefix}` | `{ident}` | {line} |")
+
+
+if __name__ == "__main__":
+    main()