@nifrajs/cli 2.12.1 → 2.14.1

package/dist/check.js

@@ -22,7 +22,9 @@ import { Glob } from "bun";
 import { diagnostic } from "./diagnostics.js";
 import { createSourceFacts } from "./internal/source-facts.js";
 import { importProjectTypeScript } from "./internal/typescript-import.js";
+import { freezeProjectFacts } from "./project-facts.js";
 import { RULE_CODES } from "./rules/codes.js";
+import { commentBlockMarkerReason } from "./rules/comment-markers.js";
 import { parseRulePacks, runRuleRegistry, sourceIndex } from "./rules/index.js";
 import { LEGACY_RULE_CODES, legacyRules } from "./rules/legacy.js";
 import { routeRules } from "./rules/routes.js";
@@ -788,6 +790,138 @@ function templateShape(ts, template, scope) {
     }
     return { staticText, dynamic };
 }
+/** Whether `name` is written to anywhere in the file - a plain, compound, or `++`/`--` assignment to a
+ * bare identifier of that name. A `let` that is is over-cautiously refused (it might be reassigned from
+ * request data); a `const` never needs this. Over-refusal only ever leaves an interpolation flagged as
+ * before, never the reverse. */
+function isReassignedInFile(ts, source, name) {
+    let found = false;
+    const visit = (node) => {
+        if (found)
+            return;
+        if (ts.isBinaryExpression(node) &&
+            node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+            node.operatorToken.kind <= ts.SyntaxKind.LastAssignment &&
+            ts.isIdentifier(node.left) &&
+            node.left.text === name) {
+            found = true;
+            return;
+        }
+        if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+            (node.operator === ts.SyntaxKind.PlusPlusToken ||
+                node.operator === ts.SyntaxKind.MinusMinusToken) &&
+            ts.isIdentifier(node.operand) &&
+            node.operand.text === name) {
+            found = true;
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return found;
+}
+/** Does `binding` bind `name` (as a plain identifier or nested inside a destructuring pattern)? Mirrors
+ * the pattern walk in {@link isShadowedAt}. */
+function bindingNameCovers(ts, binding, name) {
+    return ts.isIdentifier(binding)
+        ? binding.text === name
+        : binding.elements.some((element) => !ts.isOmittedExpression(element) &&
+            (ts.isIdentifier(element.name)
+                ? element.name.text === name
+                : bindingNameCovers(ts, element.name, name)));
+}
+/** Inspect the bindings a single scope node introduces DIRECTLY (not nested) for `name`: parameters and
+ * catch variables of a function/catch, `var`/`let`/`const` and function/class declarations of a
+ * statement list. Returns the readable initializer, `"shadow"` for a form we cannot read through, or
+ * `undefined` when this scope does not bind the name at all. */
+function directBinding(ts, source, scope, name) {
+    if (ts.isFunctionLike(scope)) {
+        for (const parameter of scope.parameters) {
+            if (bindingNameCovers(ts, parameter.name, name))
+                return "shadow";
+        }
+    }
+    if (ts.isCatchClause(scope)) {
+        const declared = scope.variableDeclaration;
+        if (declared !== undefined && bindingNameCovers(ts, declared.name, name))
+            return "shadow";
+    }
+    const statements = ts.isSourceFile(scope)
+        ? scope.statements
+        : ts.isBlock(scope) || ts.isModuleBlock(scope)
+            ? scope.statements
+            : ts.isCaseClause(scope) || ts.isDefaultClause(scope)
+                ? scope.statements
+                : undefined;
+    const lists = [];
+    if (statements !== undefined) {
+        for (const statement of statements) {
+            if (ts.isVariableStatement(statement))
+                lists.push(statement.declarationList);
+            if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) &&
+                statement.name?.text === name) {
+                return "shadow";
+            }
+        }
+    }
+    if ((ts.isForStatement(scope) || ts.isForInStatement(scope) || ts.isForOfStatement(scope)) &&
+        scope.initializer !== undefined &&
+        ts.isVariableDeclarationList(scope.initializer)) {
+        lists.push(scope.initializer);
+    }
+    for (const list of lists) {
+        for (const declaration of list.declarations) {
+            if (!bindingNameCovers(ts, declaration.name, name))
+                continue;
+            // A destructured or uninitialized binding, or a `var` (hoisting + reassignment risk), is not a
+            // value we can read one expression out of.
+            if (!ts.isIdentifier(declaration.name) || declaration.initializer === undefined)
+                return "shadow";
+            const isConst = (list.flags & ts.NodeFlags.Const) !== 0;
+            const isLet = (list.flags & ts.NodeFlags.Let) !== 0;
+            if (isConst)
+                return { initializer: declaration.initializer };
+            if (isLet && !isReassignedInFile(ts, source, name))
+                return { initializer: declaration.initializer };
+            return "shadow";
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve a query-call ARGUMENT identifier to the expression it was initialized from, so a statement
+ * parked in a variable is scanned as if it had been written inline at the call. This is the counterpart
+ * to {@link resolveStaticSqlText}: that folds a const's text INTO a template's shape; this unfolds the
+ * whole statement back out of the variable it was lifted into. Without it, ANY interpolated-SQL finding
+ * could be silenced, invisibly, by hoisting the statement to `const q = …` first.
+ *
+ * Same-file only. Nearest enclosing declaration wins, so a shadowing local is read and never a
+ * same-named module const. Reads through a `const`, or a `let` the file never reassigns, at function or
+ * module scope; transitive through an identifier-valued initializer; depth-capped. A parameter, an
+ * imported or destructured binding, a reassigned `let`, a `var`, or a name with no same-file
+ * declaration returns `undefined` - which leaves the argument scanned as itself (unflagged unless it is
+ * a module const that resolves to static text: exactly the pre-feature behavior).
+ */
+function resolveArgumentInitializer(ts, node, depth) {
+    if (depth > CONST_RESOLUTION_DEPTH)
+        return undefined;
+    const source = node.getSourceFile();
+    const name = node.text;
+    for (let scope = node.parent; scope !== undefined; scope = scope.parent) {
+        const binding = directBinding(ts, source, scope, name);
+        if (binding === "shadow")
+            return undefined;
+        if (binding !== undefined) {
+            let init = binding.initializer;
+            while (ts.isParenthesizedExpression(init))
+                init = init.expression;
+            return ts.isIdentifier(init) ? resolveArgumentInitializer(ts, init, depth + 1) : init;
+        }
+        if (ts.isSourceFile(scope))
+            break;
+    }
+    return undefined;
+}
 /** Describe only the first argument's syntax; comments/strings elsewhere cannot influence the result. */
 function sqlExpressionShape(ts, node, scope) {
     if (ts.isParenthesizedExpression(node))
@@ -872,6 +1006,17 @@ function sqlExpressionShape(ts, node, scope) {
             };
         }
     }
+    // A bare name that did not resolve to compile-time text. If it is a same-file binding we can prove
+    // holds one expression, scan THAT expression's shape - so a statement hoisted into `const q = …` is
+    // read exactly as if it were written inline at the call, closing the "extract a variable to launder
+    // the finding" hole. `literal` is forced false: the value arrived through a variable, which is the
+    // property the `unsafe`/`$queryRawUnsafe` hatch rule keys on.
+    if (ts.isIdentifier(node)) {
+        const initializer = resolveArgumentInitializer(ts, node, 0);
+        if (initializer !== undefined) {
+            return { ...sqlExpressionShape(ts, initializer, scope), literal: false };
+        }
+    }
     return {
         staticText: "",
         dynamic: true,
@@ -898,6 +1043,10 @@ function sqlMethod(ts, call) {
     return undefined;
 }
 const SQL_RECEIVER = /(?:^|\.)(?:db|sql|prisma|drizzle|database|conn|connection|client|tx)$/i;
+/** The opt-out pragma that silences one interpolated-SQL finding. Written `// nifra-expect sql-dynamic:
+ * <reason>` on the flagged line or in the comment block directly above it; the reason after the colon
+ * is mandatory (see {@link commentBlockMarkerReason}). Scoped to the single statement it sits on. */
+const SQL_DYNAMIC_PRAGMA = "nifra-expect sql-dynamic";
 /**
  * Scan one file's text for SQL assembled by interpolation. Pure + line-accurate.
  *
@@ -930,7 +1079,13 @@ export function scanInterpolatedSql(file, content, ts, imports) {
                 if (unsafeEscape || assembledSql) {
                     const index = node.getStart(source);
                     const line = source.getLineAndCharacterOfPosition(index).line + 1;
-                    out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() });
+                    // Sanctioned escape hatch for genuinely-dynamic-but-bound SQL (batch VALUES placeholder
+                    // generation, an allowlisted identifier). The reason is mandatory: a bare `// nifra-expect
+                    // sql-dynamic` with no reason after the colon does NOT silence, so the hatch always leaves a
+                    // greppable audit trail instead of becoming a second laundering trick.
+                    const silenced = commentBlockMarkerReason(lines, line, SQL_DYNAMIC_PRAGMA) !== undefined;
+                    if (!silenced)
+                        out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() });
                 }
             }
         }
@@ -1725,9 +1880,8 @@ function responseRouteSuggestion() {
         ],
     };
 }
-/** Run the three checks and assemble a structured, machine-readable result. The single source the CLI
- * report, `--json`, and the MCP tool all render from. */
-export async function collectCheckResult(cwd, opts = {}) {
+/** Build the rule input from one source walk and the other check-wide scans. */
+async function buildProjectScan(cwd, opts) {
     const fetches = [];
     const staticRoutes = [];
     const untypedClients = [];
@@ -1735,27 +1889,13 @@ export async function collectCheckResult(cwd, opts = {}) {
     const serverImports = [];
     const responseRoutes = [];
     const interpolatedSql = [];
-    // Route modules (rel + content) collected during the walk, so the TRANSITIVE server-only resolution
-    // (#4.4) - which needs fs-backed import resolution, not just per-file text - runs after the walk.
     const routeModules = [];
     const sourceFiles = [];
-    // Load the optional check config first - the typed-client scan needs the external-mount allowlist as it
-    // walks. It's a tiny pure-JSON read; a malformed file surfaces as a warning below, never blocking.
     const { config: checkConfig, error: checkConfigError, warnings: checkConfigWarnings, } = await loadCheckConfig(cwd);
-    // The interpolated-SQL rule parses with the TypeScript compiler, which is an optional peer. Resolved
-    // once, before the walk, so a project without it is told the rule did not run rather than being
-    // handed a clean report the rule never produced.
     const sqlCompiler = await (opts.loadTypeScript ?? (() => importProjectTypeScript(cwd)))();
-    // AST facts are a lazy refinement of lexical candidates. The parser is not invoked for a file until
-    // one of the route/import/response scanners finds something worth disambiguating, and the cache is
-    // shared across those rules for this check run.
     const sourceFacts = sqlCompiler === undefined ? undefined : createSourceFacts(sqlCompiler);
-    // One loader + parse cache for the whole walk, so a shared `sql-fragments.ts` is read once no matter
-    // how many route modules import a fragment out of it.
     const sqlImports = sqlCompiler === undefined ? undefined : createProjectSqlImports(cwd);
-    // lintsOnly: skip the tsc pass (seconds on a big project) and run just the near-instant source
-    // lints - the agent inner-loop mode; the full gate stays the definition of done.
-    const [tc, _, dr, manifestDrift] = await Promise.all([
+    const [typecheckResult, _, doctor, manifestDrift] = await Promise.all([
         opts.lintsOnly
             ? Promise.resolve({ ran: false, ok: true, note: "lints-only mode" })
             : typecheck(cwd, opts.signal),
@@ -1774,20 +1914,13 @@ export async function collectCheckResult(cwd, opts = {}) {
         import("./doctor.js").then((m) => m.collectDoctorResult(cwd)),
         scanServerManifestDrift(cwd),
     ]);
-    // #4.4: resolve the FULL transitive server-only chain per route. The resolver/reader are fs-backed
-    // (`Bun.resolveSync` from the importing file's dir + a sync read), so the walk follows the real local
-    // module graph (`route → ../data → ../db → node:crypto`). Both are best-effort + total: a resolve/read
-    // miss returns `undefined`, and the walk falls back to the direct edge. The whole walk is bounded
-    // (depth + visited caps), so a deep/cyclic graph can't blow up the check.
     const resolveModule = (fromFile, specifier) => {
         try {
-            // `fromFile` is a cwd-RELATIVE route path on the first hop (`routes/x.tsx`) but ABSOLUTE on the
-            // deeper hops the walk takes (it carries resolved absolute paths) - resolve the dir for each.
             const fromAbs = isAbsolute(fromFile) ? fromFile : join(cwd, fromFile);
             return Bun.resolveSync(specifier, dirname(fromAbs));
         }
         catch {
-            return undefined; // unresolvable (bare pkg without install, tsconfig path alias, missing file)
+            return undefined;
         }
     };
     const readModule = (absPath) => {
@@ -1801,6 +1934,38 @@ export async function collectCheckResult(cwd, opts = {}) {
     for (const { rel, content } of routeModules) {
         serverImports.push(...resolveServerOnlyChains(rel, content, resolveModule, readModule, sourceFacts));
     }
+    const source = sourceIndex(sourceFiles);
+    const facts = {
+        source,
+        routes: staticRoutes,
+        importGraph: serverImports,
+        packages: { doctor, manifestDrift },
+        ...(doctor.pipeline === undefined ? {} : { pipeline: doctor.pipeline }),
+        policies: { checkConfig, rulePacks: [] },
+        sourceFindings: { fetches, untypedClients, removedImports, responseRoutes, interpolatedSql },
+    };
+    return {
+        facts,
+        typecheck: typecheckResult,
+        sqlCompiler,
+        ...(checkConfigError === undefined ? {} : { checkConfigError }),
+        checkConfigWarnings,
+    };
+}
+/** Run the three checks and assemble a structured, machine-readable result. The single source the CLI
+ * report, `--json`, and the MCP tool all render from. */
+export async function collectCheckResult(cwd, opts = {}) {
+    const scan = await buildProjectScan(cwd, opts);
+    const factsSeed = scan.facts;
+    const { fetches, untypedClients, removedImports, responseRoutes, interpolatedSql } = factsSeed.sourceFindings;
+    const staticRoutes = factsSeed.routes;
+    const serverImports = factsSeed.importGraph;
+    const { doctor: dr, manifestDrift } = factsSeed.packages;
+    const { checkConfig } = factsSeed.policies;
+    const tc = scan.typecheck;
+    const sqlCompiler = scan.sqlCompiler;
+    const checkConfigError = scan.checkConfigError;
+    const checkConfigWarnings = scan.checkConfigWarnings;
     const diagnostics = [];
     const structuredExtras = [];
     if (checkConfigError !== undefined) {
@@ -1875,7 +2040,7 @@ export async function collectCheckResult(cwd, opts = {}) {
             });
     }
     const routes = staticRouteMap(staticRoutes);
-    for (const f of fetches.sort(bySite)) {
+    for (const f of [...fetches].sort(bySite)) {
         diagnostics.push({
             rule: "typed-client",
             severity: "error",
@@ -1886,7 +2051,7 @@ export async function collectCheckResult(cwd, opts = {}) {
             suggestion: ownFetchSuggestion(f, routes),
         });
     }
-    for (const f of removedImports.sort(bySite)) {
+    for (const f of [...removedImports].sort(bySite)) {
         const entry = REMOVED_IMPORTS.find((candidate) => f.snippet.includes(`"${candidate.specifier}`) ||
             f.snippet.includes(`'${candidate.specifier}`));
         diagnostics.push({
@@ -1898,7 +2063,7 @@ export async function collectCheckResult(cwd, opts = {}) {
             fix: entry?.replacement ?? "see the changelog",
         });
     }
-    for (const f of untypedClients.sort(bySite)) {
+    for (const f of [...untypedClients].sort(bySite)) {
         diagnostics.push({
             rule: "untyped-client",
             severity: "error",
@@ -1909,7 +2074,7 @@ export async function collectCheckResult(cwd, opts = {}) {
             suggestion: untypedClientSuggestion(f),
         });
     }
-    for (const f of serverImports.sort(bySite)) {
+    for (const f of [...serverImports].sort(bySite)) {
         // #4.4: the FULL transitive chain the import-resolution walk found - `route → ../data → ../db →
         // node:crypto`, matching the build leak-guard's depth - instead of just the direct edge. The chain's
         // tail is the actual server-only sink; the head is the route. When a precise resolve wasn't possible
@@ -1942,7 +2107,7 @@ export async function collectCheckResult(cwd, opts = {}) {
             },
         });
     }
-    for (const f of interpolatedSql.sort(bySite)) {
+    for (const f of [...interpolatedSql].sort(bySite)) {
         diagnostics.push({
             rule: "interpolated-sql",
             severity: "error",
@@ -1958,12 +2123,13 @@ export async function collectCheckResult(cwd, opts = {}) {
                     "Pass the value as an argument alongside the statement, so the driver binds it.",
                     `Or switch to the driver's tagged template (sql\`… ${SQL_INTERPOLATION_EXAMPLE} …\`): the tag receives substitutions separately and binds them.`,
                     "An identifier that genuinely cannot be bound (a table or column name) must be checked against an allowlist you control, never taken from the request.",
+                    "If the statement is dynamic but every value is already bound (generating `($1),($2),…` for a batch insert), mark it with a `// nifra-expect sql-dynamic: <reason>` comment on the line above - the reason is required.",
                 ],
             },
         });
     }
     // Advisory - surfaced but NOT folded into `ok`, so it never fails the gate (a raw Response is valid).
-    for (const f of responseRoutes.sort(bySite)) {
+    for (const f of [...responseRoutes].sort(bySite)) {
         diagnostics.push({
             rule: "response-route",
             severity: "warning",
@@ -1992,14 +2158,11 @@ export async function collectCheckResult(cwd, opts = {}) {
         }
         for (const finding of dr.duplicateInstalls) {
             const copies = finding.copies.map((copy) => `${copy.version} at ${copy.path}`).join("; ");
-            const identityHint = finding.package === "@nifrajs/core"
-                ? " (a second @nifrajs/core collapses `typeof backend` to `any` at `.merge()` - usually that error's root cause)"
-                : "";
             diagnostics.push({
                 rule: "duplicate-install",
                 severity: "error",
-                message: `${finding.package} resolves to multiple physical copies (${copies}) - module identity is unsafe${identityHint}`,
-                fix: "align dependency ranges and reinstall from the workspace root",
+                message: `${finding.package} identity preflight found ${finding.cause} (${copies}) - ${finding.explanation}`,
+                fix: finding.remediation,
                 suggestion: {
                     kind: "manual",
                     title: `Deduplicate ${finding.package}`,
@@ -2079,6 +2242,8 @@ export async function collectCheckResult(cwd, opts = {}) {
     // without nifra.assurance.ts retain the historical scan and hot path unchanged.
     const provided = opts.assurance;
     let applicationRulePacks = [];
+    let loadedPolicy = provided;
+    let loadedCapability = provided?.capability;
     const assuranceConfigPath = join(cwd, "nifra.assurance.ts");
     if (provided !== undefined ? provided.present : existsSync(assuranceConfigPath)) {
         try {
@@ -2105,6 +2270,14 @@ export async function collectCheckResult(cwd, opts = {}) {
                     const { collectCapabilityProjectReport } = await import("./capabilities-tool.js");
                     project = await collectCapabilityProjectReport(cwd, config.source, config.capabilities);
                 }
+                loadedPolicy = {
+                    present: true,
+                    config,
+                    ...(routeAssurance === undefined ? {} : { routeAssurance }),
+                    ...(project === undefined ? {} : { capability: project }),
+                    ...(evidence === undefined ? {} : { evidence }),
+                };
+                loadedCapability = project;
             }
             applicationRulePacks = parseRulePacks(config.rulePacks);
             const capabilityReport = project?.report;
@@ -2214,6 +2387,7 @@ export async function collectCheckResult(cwd, opts = {}) {
             }
         }
         catch (err) {
+            loadedPolicy = { present: true, error: err };
             diagnostics.push({
                 rule: "capability-config",
                 severity: "error",
@@ -2245,6 +2419,17 @@ export async function collectCheckResult(cwd, opts = {}) {
             }));
         }
         else {
+            if (contract.vacuous) {
+                // Every route hashes to the empty-schema digest, so the lock exists but the drift rule guards
+                // nothing: it can only ever compare "no schema" to "no schema". Say so, or a green contract check
+                // reads as proof of a stable contract when there is no contract to be stable.
+                structuredExtras.push(diagnostic({
+                    code: "NF-K001",
+                    severity: "info",
+                    message: "no route schemas declared - the trust manifest is vacuous: every contract hash is the empty-schema digest, so drift detection guards nothing. Declare route schemas (body/query/params/response) so the lock has a contract to protect.",
+                    verify: "nifra check --lints-only",
+                }));
+            }
             for (const finding of contract.diagnostics) {
                 diagnostics.push({
                     rule: "contract-drift",
@@ -2272,21 +2457,24 @@ export async function collectCheckResult(cwd, opts = {}) {
             });
         }
     }
+    const projectFacts = freezeProjectFacts({
+        ...factsSeed,
+        policies: {
+            ...factsSeed.policies,
+            ...(loadedPolicy === undefined ? {} : { assurance: loadedPolicy }),
+            ...(loadedCapability === undefined ? {} : { capability: loadedCapability }),
+            rulePacks: applicationRulePacks,
+        },
+    }, diagnostics);
     const ruleContext = {
         root: cwd,
-        sources: sourceIndex(sourceFiles),
-        project: {
-            legacyDiagnostics: diagnostics,
-            assurance: opts.assurance,
-            // Route registrations collected during the source walk, so the route-table rules
-            // (rules/routes.ts) lint them without a second scan.
-            staticRoutes,
-        },
+        sources: projectFacts.source,
+        project: projectFacts,
     };
     const structuredDiagnostics = [...structuredExtras];
     let registryDiagnostics = [];
     try {
-        registryDiagnostics = await runRuleRegistry(ruleContext, [...legacyRules, ...securityRules, ...routeRules], applicationRulePacks);
+        registryDiagnostics = await runRuleRegistry(ruleContext, [...legacyRules, ...securityRules, ...routeRules], projectFacts.policies.rulePacks);
         structuredDiagnostics.push(...registryDiagnostics);
     }
     catch (error) {