audit-tools 0.46.0 → 0.49.0

package/dist/shared/validation/schemaFailure.d.ts

@@ -0,0 +1,9 @@
+import type { z } from "zod";
+/**
+ * The ONE rendering of a zod parse failure into a single-line message: each
+ * issue as `<dotted path>: <message>`, joined by `; `, with `<root>` standing in
+ * for an issue that carries no path. Single-sourced so two callers refusing the
+ * same malformed document cannot describe it differently.
+ */
+export declare function formatSchemaFailure(error: z.ZodError): string;
+//# sourceMappingURL=schemaFailure.d.ts.map

package/dist/shared/validation/schemaFailure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaFailure.d.ts","sourceRoot":"","sources":["../../../src/shared/validation/schemaFailure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CAO7D"}

package/dist/shared/validation/schemaFailure.js

@@ -0,0 +1,15 @@
+/**
+ * The ONE rendering of a zod parse failure into a single-line message: each
+ * issue as `<dotted path>: <message>`, joined by `; `, with `<root>` standing in
+ * for an issue that carries no path. Single-sourced so two callers refusing the
+ * same malformed document cannot describe it differently.
+ */
+export function formatSchemaFailure(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
+        return `${path}: ${issue.message}`;
+    })
+        .join("; ");
+}
+//# sourceMappingURL=schemaFailure.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemaFailure.js","sourceRoot":"","sources":["../../../src/shared/validation/schemaFailure.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAiB;IACnD,OAAO,KAAK,CAAC,MAAM;SAChB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACb,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACrE,OAAO,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IACrC,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

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

@@ -66,7 +66,7 @@ one bounded, persisted step. Useful diagnostic and recovery commands include:
 audit-code status
 audit-code explain-task <task_id>
 audit-code validate
-audit-code validate-results
+audit-code validate-results --results <file>
 audit-code requeue
 audit-code synthesize
 audit-code resynthesize
@@ -87,9 +87,12 @@ distinguishable from a clean one, invalidates the persisted step contract, and
 the next `next-step` re-reads the bound result files for the dropped items.
 
 `audit-code cleanup` removes `.audit-tools/audit/` only when the persisted run
-is complete or not started. Active, blocked, or missing-state runs are refused
-unless the operator explicitly supplies `--force`; `--dry-run` previews the
-decision.
+is complete or not started. Active or blocked runs are refused unless the
+operator explicitly supplies `--force`. A directory with no `audit_state.json`
+marker is refused whether or not `--force` is supplied: `--force` waives the
+evidence about a run's STATUS, never the evidence about its IDENTITY, and the
+verb will not delete a directory it cannot prove is an audit run. `--dry-run`
+previews the decision.
 
 ## Repository intent and analyzer policy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audit-tools",
-  "version": "0.46.0",
+  "version": "0.49.0",
   "private": false,
   "license": "ISC",
   "description": "Provider-neutral code auditing and remediation workflows for arbitrary repositories.",
@@ -44,15 +44,17 @@
     "build": "node scripts/shared/clean-dist.mjs && tsc -p tsconfig.json",
     "check": "tsc -p tsconfig.json --noEmit",
     "check:tests": "tsc -p tsconfig.test.json",
+    "check:scripts": "tsc -p tsconfig.scripts.json",
     "nightly:inbox": "node scripts/nightly/render-inbox.mjs",
     "nightly:ingest": "node scripts/nightly/ingest-answers.mjs",
     "test:doc-contract": "node scripts/shared/run-vitest-gate.mjs tests/audit/release-contract.test.ts tests/audit/file-lock-doc-sync.test.ts tests/audit/host-asset-renderer-drift.test.ts",
     "test": "npm run build && node scripts/shared/run-vitest-gate.mjs",
     "test:single": "npm run build && node scripts/shared/run-vitest-gate.mjs",
     "verify:guards": "node scripts/shared/run-vitest-gate.mjs --retry=2 --exclude \"**/audit-code-completion-*.test.ts\" --exclude \"**/audit-code-wrapper-*.test.ts\" --exclude \"**/audit/next-step-core-*.test.ts\" --exclude \"**/seam-host-only-next-step.test.ts\" --exclude \"**/*-e2e.test.*\" --exclude \"**/next-step-implement-dispatch.test.ts\" --exclude \"**/next-step-pipeline-dispatch.test.ts\"",
-    "verify:checks": "node scripts/shared/profile-run.mjs verify-checks check:control-bytes check:version-gates check:guard-reach check:ci-trigger-paths check:offload-lanes check:loop-core-patterns check:constitutional-doc-paths check:runtime-artifact-names check:executor-producers check:cli-surface check:deadcode check:lint check:dup check:depgraph check:doc-manifest check:doc-links check:doc-code-citations check:gate-enumeration check:philosophy-brief check:nightly-routine-prompt check:handoff-roadmap check:backlog-index check:memory-citations check:backlog-budget check:backlog-status check:backlog-line-numbers check:tests build verify:hosts verify:remediate-hosts pack:smoke smoke:packaged-audit-code smoke:packaged-remediate-code",
+    "verify:checks": "node scripts/shared/profile-run.mjs verify-checks check:control-bytes check:shared-primitives check:version-gates check:guard-reach check:ci-trigger-paths check:offload-lanes check:loop-core-patterns check:constitutional-doc-paths check:runtime-artifact-names check:executor-producers check:cli-surface check:deadcode check:lint check:dup check:depgraph check:doc-manifest check:doc-links check:doc-code-citations check:gate-enumeration check:philosophy-brief check:readme-sample-report check:proposal-red-at check:nightly-routine-prompt check:handoff-roadmap check:backlog-index check:memory-citations check:backlog-budget check:backlog-status check:backlog-line-numbers check:tests build check:scripts verify:hosts verify:remediate-hosts pack:smoke smoke:packaged-audit-code smoke:packaged-remediate-code",
     "verify:release": "npm run verify:checks && node scripts/shared/run-vitest-gate.mjs && npm run smoke:linked-audit-code && npm run smoke:linked-remediate-code",
     "check:control-bytes": "node scripts/check-control-bytes.mjs",
+    "check:shared-primitives": "node scripts/check-shared-primitives.mjs",
     "check:guard-reach": "node scripts/check-guard-reach.mjs",
     "closeout": "node scripts/render-closeout.mjs",
     "check:ci-trigger-paths": "node scripts/shared/generate-ci-trigger-paths.mjs --check",
@@ -64,6 +66,8 @@
     "check:doc-links": "node scripts/check-doc-links.mjs",
     "check:doc-code-citations": "node scripts/check-doc-code-citations.mjs",
     "check:philosophy-brief": "node scripts/check-philosophy-brief.mjs",
+    "check:readme-sample-report": "node --import tsx/esm scripts/check-readme-sample-report.mjs",
+    "check:proposal-red-at": "node scripts/check-proposal-red-at.mjs",
     "check:nightly-routine-prompt": "node scripts/check-nightly-routine-prompt.mjs",
     "verify:hosts": "node scripts/audit/verify-hosts.mjs",
     "verify:remediate-hosts": "node scripts/remediate/verify-hosts.mjs",
@@ -106,6 +110,7 @@
   "dependencies": {
     "commander": "^13.0.0",
     "smol-toml": "^1.6.1",
+    "strip-json-comments": "^5.0.3",
     "tree-sitter-wasms": "^0.1.13",
     "web-tree-sitter": "^0.25.10",
     "yaml": "^2.9.0",

package/scripts/audit/postinstall.mjs

@@ -63,7 +63,9 @@ const OPENCODE_AUDIT_BASH_PERMISSION = {
 // Resolved best-effort: on a fresh workspace checkout the shared dist may not
 // be built yet, in which case the OpenCode config deployment below is
 // skipped with a warning instead of failing the whole install.
-const sharedOpenCodePermissions = await resolveSharedOpenCodePermissions();
+const sharedOpenCodePermissions = /** @type {NonNullable<Awaited<ReturnType<typeof resolveSharedOpenCodePermissions>>>} */ (
+  await resolveSharedOpenCodePermissions()
+);
 
 // A pre-hardening deploy wrote agent-scope bash['*']='allow' (the historically
 // managed broad value). Migrate exactly that value away so the generated 'ask'
@@ -312,7 +314,7 @@ try {
   console.log(`audit-code: restart Claude Desktop for /audit-code to appear in the slash-command menu`);
   counts.succeeded++;
 } catch (err) {
-  console.warn(`audit-code: could not install Claude Desktop plugin (${err.message})`);
+  console.warn(`audit-code: could not install Claude Desktop plugin (${/** @type {any} */ (err).message})`);
   console.warn(`  Plugin directory: ${claudePluginDir}`);
   counts.failed++;
 }

package/scripts/postinstall.mjs

@@ -63,7 +63,7 @@ async function manageArtifactGitignore() {
     }
   } catch (err) {
     console.warn(
-      `[audit-tools] postinstall: .gitignore management skipped (${err?.message ?? err}).`,
+      `[audit-tools] postinstall: .gitignore management skipped (${/** @type {any} */ (err)?.message ?? err}).`,
     );
   }
 }

package/scripts/remediate/postinstall.mjs

@@ -84,7 +84,9 @@ function withoutRetiredRemediateCodeBashRules(rule) {
 // Resolved best-effort: on a fresh workspace checkout the shared dist may not
 // be built yet, in which case the OpenCode config deployment below is
 // skipped with a warning instead of failing the whole install.
-const sharedOpenCodePermissions = await resolveSharedOpenCodePermissions();
+const sharedOpenCodePermissions = /** @type {NonNullable<Awaited<ReturnType<typeof resolveSharedOpenCodePermissions>>>} */ (
+  await resolveSharedOpenCodePermissions()
+);
 
 // A pre-hardening deploy wrote agent-scope bash['*']='allow' (the historically
 // managed broad value). Migrate exactly that value away so the generated 'ask'

package/scripts/shared/install-host-assets.mjs

@@ -107,7 +107,7 @@ export function runInstalls(toolName, installs, counts) {
       console.log(`${toolName}: ${action} global ${install.label} at ${install.path}`);
       counts.succeeded++;
     } catch (err) {
-      console.warn(`${toolName}: could not install global ${install.label} (${err.message})`);
+      console.warn(`${toolName}: could not install global ${install.label} (${/** @type {any} */ (err).message})`);
       console.warn(`  To install manually, copy from:`);
       console.warn(`    ${install.sourcePath}`);
       console.warn(`  to:`);
@@ -126,6 +126,10 @@ export function runInstalls(toolName, installs, counts) {
  * historically worded this differently). `manualInstructions`, if given, is
  * an array of extra warn lines printed on failure only.
  */
+/**
+ * @param {{toolName: string, path: string, sharedOpenCodePermissions: any, buildMerged: Function, label: string, manualInstructions?: string[]}} options
+ * @param {{succeeded: number, failed: number}} counts
+ */
 export function installOpenCodeGlobalConfig(
   { toolName, path, sharedOpenCodePermissions, buildMerged, label, manualInstructions },
   counts,
@@ -145,7 +149,7 @@ export function installOpenCodeGlobalConfig(
     console.log(`${toolName}: ${action} global ${label} in ${path}`);
     counts.succeeded++;
   } catch (err) {
-    console.warn(`${toolName}: could not install global ${label} (${err.message})`);
+    console.warn(`${toolName}: could not install global ${label} (${/** @type {any} */ (err).message})`);
     for (const line of manualInstructions ?? []) console.warn(line);
     counts.failed++;
   }
@@ -175,7 +179,7 @@ export function installAntigravityPlugin(
     console.log(`${toolName}: ${skillAction} Antigravity plugin skill at ${antigravityPluginSkillPath}`);
     counts.succeeded++;
   } catch (err) {
-    console.warn(`${toolName}: could not install Antigravity plugin (${err.message})`);
+    console.warn(`${toolName}: could not install Antigravity plugin (${/** @type {any} */ (err).message})`);
     counts.failed++;
   }
 }

package/wrapper/audit-code-wrapper-build.mjs

@@ -32,7 +32,7 @@ function resolveSpawn(command, args) {
 }
 
 function runBuild(command, args) {
-  return new Promise((resolvePromise, rejectPromise) => {
+  return /** @type {Promise<void>} */ (new Promise((resolvePromise, rejectPromise) => {
     const resolved = resolveSpawn(command, args);
     const child = spawn(resolved.command, resolved.args, {
       cwd: repoRoot,
@@ -50,7 +50,7 @@ function runBuild(command, args) {
       }
       rejectPromise(new Error(`Command failed with exit code ${code}.`));
     });
-  });
+  }));
 }
 
 export async function shouldBuildDistForPaths({
@@ -120,7 +120,7 @@ async function acquireBuildLock() {
       process.stderr.write(JSON.stringify({ event: "build_lock_acquired", pid: process.pid, lock: buildLockPath, acquired_at: acquiredAt }) + '\n');
       return handle;
     } catch (error) {
-      if (error && error.code === 'EEXIST') {
+    if (error && /** @type {any} */ (error).code === 'EEXIST') {
         try {
           const lockStats = await stat(buildLockPath);
           if (Date.now() - lockStats.mtimeMs > BUILD_LOCK_MAX_AGE_MS) {

package/wrapper/audit-code-wrapper-install-hosts.mjs

@@ -404,7 +404,7 @@ export function buildHostCatalog({ root, host, assets }) {
         steps: definition.steps,
       };
     })
-    .filter(Boolean)
+    .filter((entry) => entry !== null)
     .map((entry) => ({
       ...entry,
       primary_path: entry.primary_path,
@@ -882,9 +882,9 @@ export async function verifyInstalledBootstrap(argv) {
     return;
   }
 
-  const assetPaths = installManifest.asset_paths ?? {};
+  const assetPaths = /** @type {any} */ (installManifest).asset_paths ?? {};
   const hostCatalog = new Map(
-    (installManifest.hosts ?? []).map((entry) => [entry.host, entry]),
+    (/** @type {any} */ (installManifest).hosts ?? []).map((entry) => [entry.host, entry]),
   );
   const selectedHosts = requestedHost && requestedHost !== 'all'
     ? getInstallHostKeys(requestedHost)

package/wrapper/audit-code-wrapper-lib.mjs

@@ -335,6 +335,7 @@ async function runDistCommandInline(commandName, argv, { ensureArtifactsDir = fa
   await cli.runCli([process.execPath, distCliEntry, commandName, ...commandArgs]);
 }
 
+/** @param {{usageName: string, argv?: string[], preferredEntrypoint?: string}} options */
 export async function runAuditCodeWrapper({
   usageName,
   argv = process.argv.slice(2),

package/wrapper/remediate-code-wrapper-install-hosts.mjs

@@ -406,7 +406,7 @@ export function buildHostCatalog({ root, host, assets }) {
         steps: definition.steps,
       };
     })
-    .filter(Boolean)
+    .filter((entry) => entry !== null)
     .map((entry) => ({
       ...entry,
       primary_path: entry.primary_path,
@@ -918,9 +918,9 @@ export async function verifyInstalledBootstrap(argv) {
     return;
   }
 
-  const assetPaths = installManifest.asset_paths ?? {};
+  const assetPaths = /** @type {any} */ (installManifest).asset_paths ?? {};
   const hostCatalog = new Map(
-    (installManifest.hosts ?? []).map((entry) => [entry.host, entry]),
+    (/** @type {any} */ (installManifest).hosts ?? []).map((entry) => [entry.host, entry]),
   );
   const selectedHosts = requestedHost && requestedHost !== 'all'
     ? getInstallHostKeys(requestedHost)