audit-tools 0.32.22 → 0.32.27

package/dist/shared/validation/findingGrounding.js

@@ -19,6 +19,7 @@
  * E3 + P7).
  */
 import { readFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
 import { isAbsolute, join } from "node:path";
 /** Normalize text for content-matching: drop CR, collapse whitespace, trim. */
 export function normalizeForMatch(text) {
@@ -32,10 +33,92 @@ export function normalizeForMatch(text) {
  * grounding and any other consumer that matches a cited `affected_files` path
  * against a repo manifest. (Quote-and-verify resolves a cited path against the
  * filesystem instead, so it does not lowercase — see `verifyFindingGrounding`.)
+ *
+ * INV-B3-1: strips a leading `./` ONLY — it must NEVER strip the leading dot of a
+ * dotfile-directory segment (`.claude/…`, `.github/…`). The regex is anchored to
+ * `./` (dot-SLASH); do not broaden it to `/^\.\/?/` or similar, or every
+ * dotfile-dir citation silently un-grounds (it would no longer match its
+ * `git ls-files` form by exact membership).
  */
 export function normalizeRepoPath(p) {
     return p.trim().replace(/\\/g, "/").replace(/^\.\//, "").toLowerCase();
 }
+/**
+ * True when `p` is a bare basename — a single path segment with no separator
+ * (`advance.ts`), as opposed to a nested repo-relative path (`src/x/advance.ts`)
+ * or a dotfile-dir path (`.claude/hooks/x.mjs`). A bare basename is the one shape
+ * that cannot be resolved by a naive `root/<name>` join when the real file is
+ * nested, so it is the shape {@link resolveBasenameToTrackedPath} rescues.
+ */
+export function isBareBasename(p) {
+    const t = p.trim();
+    return t.length > 0 && !t.includes("/") && !t.includes("\\");
+}
+/**
+ * INV-B3-2: resolve a bare basename (`advance.ts`) to its UNIQUE tracked full
+ * path in the known-path corpus (`src/audit/orchestrator/advance.ts`). Returns
+ * the single matching corpus entry when exactly one tracked path has that
+ * basename; `undefined` when zero OR more-than-one path matches — an ambiguous
+ * basename stays a checkable signal, never a silent false-pass.
+ *
+ * Corpus-agnostic and case-insensitive on the basename: it works whether the
+ * caller's corpus is `normalizeRepoPath`-lowercased (the M-B3 gate) or
+ * case-preserving (the fs-resolving remediate consumers), and returns the corpus
+ * entry as-is so a case-preserving caller gets a real on-disk path back. Single
+ * source (drift-plan convention) — the gate, both orchestrators, and
+ * `groundDesignFinding` all resolve basenames through this one authority.
+ */
+export function resolveBasenameToTrackedPath(basename, knownPaths) {
+    const target = basename.trim().replace(/\\/g, "/");
+    if (target.length === 0 || target.includes("/"))
+        return undefined;
+    const targetLower = target.toLowerCase();
+    let match;
+    for (const path of knownPaths) {
+        const base = path.slice(path.lastIndexOf("/") + 1);
+        if (base.toLowerCase() === targetLower) {
+            if (match !== undefined)
+                return undefined; // >1 match → ambiguous
+            match = path;
+        }
+    }
+    return match;
+}
+/**
+ * Case-preserving corpus of the tracked working-tree paths at `root`, via
+ * `git ls-files` (forward-slashed, trimmed). This is the sibling of the M-B3
+ * gate's `enumerateRepoTreePaths` (which `normalizeRepoPath`-lowercases for
+ * membership matching): the remediate consumers that resolve a basename and then
+ * read the file off disk (line counting) need the REAL on-disk case, so this one
+ * does not lowercase. Degrades to an empty set when git is missing / not a repo
+ * (callers then fall back to their existing `existsSync` check — monotonic, never
+ * a regression). OS-agnostic: `shell: false`, forward-slash output.
+ */
+export function enumerateTrackedFilePaths(root) {
+    const known = new Set();
+    let result;
+    try {
+        result = spawnSync("git", ["ls-files"], {
+            cwd: root,
+            encoding: "utf8",
+            shell: false,
+            windowsHide: true,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+    }
+    catch {
+        return known;
+    }
+    if (!result || result.status !== 0 || typeof result.stdout !== "string") {
+        return known;
+    }
+    for (const line of result.stdout.split("\n")) {
+        const path = line.trim().replace(/\\/g, "/");
+        if (path.length > 0)
+            known.add(path);
+    }
+    return known;
+}
 /**
  * True when the (normalized) quoted span appears anywhere in the (normalized)
  * file content. An empty quote never matches (an empty quote grounds nothing).

package/dist/shared/validation/findingGrounding.js.map

@@ -1 +1 @@
-{"version":3,"file":"findingGrounding.js","sourceRoot":"","sources":["../../../src/shared/validation/findingGrounding.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"findingGrounding.js","sourceRoot":"","sources":["../../../src/shared/validation/findingGrounding.ts"],"names":[],"mappings":"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"}

package/docs/audit-pkg/operator-guide.md

@@ -175,6 +175,90 @@ Use `ui_mode: "visible"` when debugging provider stdout/stderr. Use
 `subprocess-template` or `vscode-task` only when you have a reliable launcher
 bridge.
 
+## Gate-0 provider confirmation
+
+The first thing an interactive audit run does — before it reads the repo — is
+pause on a **provider confirmation** step (Gate-0). The tool auto-detects the
+provider pool it can dispatch to, prices each candidate, and proposes a cost
+ordering (cheapest capable first). You confirm, reorder, or amend it. The
+mechanism behind the ordering is documented in
+[`spec/cost-first-routing.md`](../../spec/cost-first-routing.md); this section is
+only how to respond to the step.
+
+### When it fires
+
+- On the conversation/CLI path (`audit-code next-step`) it fires on **every** run,
+  even when only one — or zero — providers were auto-detected, so you can reorder,
+  exclude, self-report your own model roster, or add a provider that discovery missed.
+- Headless (`audit-code advance-audit`, no interactive host) it auto-completes with
+  the tool's price-ascending suggestion and never pauses.
+
+### How to respond
+
+The step prints the suggested pool as a priced table and asks you to write your
+decision to:
+
+```text
+.audit-tools/audit/provider-confirmation.input.json
+```
+
+**Writing that file is what lets the run proceed** — its presence is the "operator
+has acted" signal. To accept the suggestion verbatim, write just the version:
+
+```json
+{ "schema_version": "provider-confirmation-input/v1" }
+```
+
+Every other field is optional:
+
+```json
+{
+  "schema_version": "provider-confirmation-input/v1",
+  "cost_order": ["<provider-or-model-key>", "..."],
+  "exclude": ["<provider-name>"],
+  "include": ["<self-spawn-blocked provider to opt back in>"],
+  "host_models": [{ "model_id": "<your model id>", "tier": "frontier|capable|fast" }]
+}
+```
+
+- `cost_order` — the confirmed ordering, cheapest first, as a list of keys. A key
+  is either a **provider name** (as shown in the table) or a **host `model_id`** you
+  report in `host_models`. Keys you omit keep their suggested relative order,
+  appended after the ones you name; unrecognized keys are ignored. Omit it to accept
+  the suggested order.
+- `exclude` — drops a provider from the dispatchable pool.
+- `include` — opts a self-spawn-blocked provider back in. A CLI provider detected
+  while you are already inside a session of that same agent (`claude-code` under
+  `CLAUDECODE`, `codex` under `CODEX`) is excluded by default so the run can't
+  self-spawn a fresh agent; naming it here overrides that. Advanced — normally leave
+  it excluded.
+- `host_models` — reports your own (the host agent's) model roster so those tiers
+  are priced from the models.dev dataset and orderable here, not just at dispatch.
+
+You supply only ordering intent plus your model roster. The tool owns the prices,
+the capability flags, and the roster snapshot — you never hand-author those. If a
+provider you use isn't listed, it wasn't auto-detected: add its config to
+`session-config.json` (an OpenAI-compatible endpoint via
+`openai_compatible.{base_url,model,api_key_env}`, or a CLI backend via its
+`<name>.command`) and re-run the step.
+
+Once the input is written, re-run the continue command the step printed
+(`audit-code next-step`). The tool consumes the input and promotes it into both
+canonical artifacts: the per-tool `provider_confirmation.json` seam and the shared
+`.audit-tools/provider-confirmation.json`.
+
+### The confirmed pool persists — you aren't re-prompted
+
+The shared `.audit-tools/provider-confirmation.json` is written once and reused for
+the rest of the audit→remediate session. A later step, and a subsequent
+`remediate-code` run against the same repo, read and honor that pool without
+prompting again — `remediate-code` has no confirmation step of its own; it consumes
+the audit-side pool. You are only re-prompted if the discovered provider roster
+changes (a provider appears or disappears since it was confirmed), which forces a
+fresh confirmation so a vanished provider is never pinned. If the file is absent
+(for example a standalone remediate run with no prior audit), the run resolves its
+provider independently — absence is never an error.
+
 ## Model selection
 
 Conversation-level model choice belongs to the host conversation. The backend

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audit-tools",
-  "version": "0.32.22",
+  "version": "0.32.27",
   "private": false,
   "license": "ISC",
   "description": "Portable hybrid code auditing + remediation orchestrators for arbitrary repositories.",
@@ -42,7 +42,7 @@
     "test:doc-contract": "vitest run tests/audit/release-contract.test.mjs tests/audit/priority-chain-doc-sync.test.mjs tests/audit/file-lock-doc-sync.test.mjs tests/audit/host-asset-renderer-drift.test.mjs",
     "test": "npm run build && vitest run",
     "test:single": "npm run build && vitest run",
-    "verify:checks": "npm run check && npm run check:deadcode && npm run check:doc-manifest && npm run build && npm run verify:hosts && npm run verify:remediate-hosts && npm run smoke:packaged-audit-code && npm run smoke:packaged-remediate-code",
+    "verify:checks": "node scripts/shared/profile-run.mjs verify-checks check:deadcode check:doc-manifest build verify:hosts verify:remediate-hosts smoke:packaged-audit-code smoke:packaged-remediate-code",
     "verify:release": "npm run verify:checks && vitest run",
     "check:deadcode": "knip --no-config-hints",
     "check:doc-manifest": "node scripts/check-doc-manifest.mjs",