audit-tools 0.45.0 → 0.48.0

package/wrapper/installer-verb-help.mjs

@@ -52,6 +52,18 @@ const VERB_DETAIL = Object.freeze({
   ],
 });
 
+/**
+ * One verb's one-line summary, with `{product}` bound to the slash-command the
+ * bin installs. The accessor exists so the surface can be RENDERED — the docs
+ * that list these verbs read this module rather than restating it, which is how
+ * `docs/audit-pkg/product.md` came to omit two of the four.
+ */
+export function installerVerbSummary(verb, product) {
+  const summary = VERB_SUMMARY[verb];
+  if (summary === undefined) throw new Error(`unknown installer verb: ${verb}`);
+  return summary.replace('{product}', product);
+}
+
 /** True when `verb` is one of the wrapper-intercepted installer verbs. */
 export function isInstallerVerb(verb) {
   return typeof verb === 'string' && INSTALLER_VERBS.includes(verb);
@@ -76,7 +88,7 @@ export function wantsInstallerVerbHelp(argv) {
  * installs (e.g. `/audit-code`); `usageName` is the bin as the caller invoked it.
  */
 export function installerVerbHelp(verb, { usageName, product }) {
-  const summary = VERB_SUMMARY[verb].replace('{product}', product);
+  const summary = installerVerbSummary(verb, product);
   return [
     `Usage: node ${usageName} ${verb} [--root PATH] [--quiet]`,
     '',
@@ -92,7 +104,5 @@ export function installerVerbHelp(verb, { usageName, product }) {
 
 /** The one-line summaries, for a bin's top-level help listing. */
 export function installerVerbSummaries(product) {
-  return INSTALLER_VERBS.map(
-    (verb) => `- ${verb} ${VERB_SUMMARY[verb].replace('{product}', product)}`,
-  );
+  return INSTALLER_VERBS.map((verb) => `- ${verb} ${installerVerbSummary(verb, product)}`);
 }

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)

package/docs/audit-pkg/development.md

@@ -1,113 +0,0 @@
-# Development
-
-## Repository layout
-
-- `src/`: implementation code
-- `schemas/`: JSON schemas for public and internal artifacts
-- `examples/`: validated artifact examples
-- `skills/audit-code/`: canonical prompt and skill-facing instructions
-- `dispatch/`: standalone result validation and merge helpers
-- `tests/`: vitest-based test suite and regression coverage
-- `dist/`: build output (gitignored, not checked in) produced by `npm run build` / the `prepack` script;
-  shipped only in the packed npm tarball
-
-## Agent handoff
-
-Long-term product direction lives in [`product.md`](product.md). Current state + immediate next steps are in
-[`HANDOFF.md`](../HANDOFF.md); open work in [`backlog.md`](../backlog.md). There is no
-shipped-sprint archive — that history lives in git + project memory.
-
-## Build and test
-
-```bash
-npm install
-npm run check
-npm test
-npx vitest run tests/audit/host-handoff.test.ts
-npm run verify:release
-```
-
-Run `npm install` from the repository root before running build, check, test, or
-package-scoped workflows in a fresh clone or git worktree. Missing
-`node_modules` can surface as misleading `audit-tools/shared` export or type
-errors because dependents may resolve stale compiled `dist/` output.
-
-The test suite is intentionally contract-heavy. Update tests when changing
-schema shape, prompt contracts, host-handoff behavior, installer output, or release
-workflow semantics.
-
-## Architecture
-
-The system separates deterministic extraction from bounded LLM judgment: intake, analysis artifacts,
-task planning, provider-neutral host workloads, strict result ingestion, and synthesis into
-`audit-report.md`. Backend/model selection, concurrency, retries, and transport belong to the host and
-are not audit-tools configuration.
-
-**The ordering has one home** — the `PRIORITY` array in `src/audit/orchestrator/nextStep.ts`, walked by
-`decideNextStep`. `src/audit/README.md` carries the conceptual grouping with the disclaimer that `PRIORITY` is
-authoritative; read the array for the real sequence. Copies of it have drifted before, which is why
-neither this file nor any other keeps a second one.
-
-Portability rules:
-
-- tool-specific collectors write tool-agnostic JSON
-- prompts consume artifacts and bounded source context
-- review work is attributable to files, lenses, passes, and tasks
-- coverage gaps are machine-detectable
-
-`AuditTask` is the coverage identity; `AuditResult[]` is the ingestion contract.
-
-## Adding language analyzers
-
-Language support should be adapter-based. A new analyzer should enrich shared
-artifacts instead of inventing a language-specific planning path.
-
-Avoid adding another bespoke manifest or project-file parser by default. First
-ask whether the signal is common in expected repositories, whether it provides
-direction or ownership that path heuristics cannot, and whether the same value
-could come from a generic analyzer-supplied ownership hint.
-
-Preferred outputs:
-
-- graph edges with kind, direction, confidence, and reason
-- entrypoints and surfaces
-- test-to-source links
-- package/module ownership hints, including analyzer-supplied `ownership_roots`
-  that become `analyzer-ownership-root-link` graph references
-- contract-suite links for small JSON Schema, workflow, package-script, or
-  TypeScript type suites when planner metrics show otherwise weak packets
-- external boundary hints
-- line counts and anchor summaries for large files
-
-Keep deep analyzers optional: a repository should still produce useful packets
-from manifests, paths, tests, and external analyzer results when a language has
-only fallback support. Command-backed analyzers should prove project intent
-before running — prefer repo-local config checks (`eslint.config.*`, `.eslintrc*`,
-`package.json` `eslintConfig`) over executing a globally installed tool and
-parsing its no-config failure.
-
-Language-agnostic semantic affinity is useful for ranking adjacent context but
-should stay low-authority: don't let shared token frequency alone force packet
-merges; use it for `boundary_files` or candidate explanations unless a
-deterministic edge corroborates the relationship.
-
-## Production readiness
-
-Drive priorities from field trials, not speculation: run representative
-repositories through planning, validate the bundle (`audit-code validate`), and
-compare `audit_plan_metrics.json` (packet count, weak-packet count, cohesion,
-merge/boundary edge kinds) across runs. Promote an extractor or planner change
-when those metrics expose a deterministic gap — and prefer improving shared
-graph resolution or generic analyzer ownership roots before adding another
-ecosystem-specific parser.
-
-Before treating a build as production-ready, verify the full review loop in one
-real host (`next-step` emits the complete workload → the host writes each bound
-result → `next-step` ingests them → `validate`), then run the release gate from a clean
-checkout (see [`release.md`](release.md) for what `npm run verify:release`
-covers and when to run it). Keep runtime command execution covered when
-changing it — including the Windows package-manager-shim path (see the Windows
-notes in [`operator-guide.md`](operator-guide.md)). If the
-final `audit-report.md` cannot be promoted from `.audit-tools/audit/` to
-`.audit-tools/audit-report.md` due to local permissions, completion still succeeds and the
-pre-promotion copy under `.audit-tools/audit/` is authoritative.

package/docs/audit-pkg/release.md

@@ -1,140 +0,0 @@
-# Release
-
-The maintainer land-and-publish flow — release gate, publication, version bumps —
-is owned by the ship skill (`.claude/skills/ship/SKILL.md`), including the
-generated gate-step list. `npm run release:patch` bumps + tags;
-`npm run release:patch:publish` runs the full flow (`release:minor` /
-`release:major` variants likewise). Routine CI exercises the
-Node majors matrixed in `.github/workflows/*.yml` (the matrix there is
-self-describing).
-
-This page keeps what the skill does not carry: manual host validation, manual
-workflow dispatch, trusted-publisher configuration, and troubleshooting.
-
-## Host validation — the manual half of the release gate
-
-The automated half of multi-host validation lives in `npm run verify:hosts`
-(wired into `verify:release`): it deploys every host surface into an isolated
-temp `$HOME` and re-runs each host's own `verify()` handler from the same
-`INSTALL_HOST_DEFINITIONS` table the postinstall deploy uses. That gate catches
-*our* drift — a missing, unparseable, or canonical-body-diverged asset — before
-publish.
-
-This checklist covers only what CI **cannot** reach: actually invoking
-`/audit-code` inside a GUI host and confirming a host handoff round-trips. A GUI
-host can change its asset format or command-rendering out from under us; the
-no-drift guard does not see that, so a human runs these rows at release. A failed
-row becomes a backlog item.
-
-Concrete semantic execution is outside the package boundary, so release
-validation covers workload emission and result ingestion rather than a matrix
-of execution backends.
-
-### How to run a row
-
-For each GUI host below:
-
-1. **Install** — from a clean repo, run `npm install -g audit-tools` (or the
-   local equivalent) so postinstall deploys the host surface, then open the
-   repository in the host.
-2. **Command appears** — confirm the host registers/offers `/audit-code` (slash
-   command, skill, or agent, per the host's setup kind).
-3. **One live handoff** — invoke `/audit-code` and let it run one bounded audit
-   step (a single `audit-code next-step` round-trip). If semantic work is
-   reached, complete one emitted host work item.
-4. **Result lands** — confirm the step's result artifact is written under
-   `.audit-tools/audit/` (e.g. `steps/current-step.json` advances and the
-   expected artifact for that step appears).
-
-Mark each cell pass / fail; record the release version and date **in the release's own
-notes or a `docs/reviews/` record — never by committing a filled copy of the grids below.**
-They are a timeless template, like `docs/end-of-sprint-report-template.md`.
-
-### Checklist (one row per GUI host)
-
-| Host | Surface deployed | 1. Install + open | 2. `/audit-code` visible | 3. One live handoff | 4. Result lands under `.audit-tools/audit/` |
-|---|---|---|---|---|---|
-| Antigravity | `.agent/skills/audit-code/SKILL.md` skill, `.gemini/commands/audit-code.toml` slash command, planning guide, AGENTS instructions | ☐ | ☐ | ☐ | ☐ |
-| OpenCode | global `/audit-code` command (npm-installed) + generated `opencode.json` project permissions | ☐ | ☐ | ☐ | ☐ |
-| VS Code | generated prompt file + custom agent + Copilot instructions (`INSTALL_HOST_DEFINITIONS.vscode`, `setup_kind: 'prompt+agent'`) | ☐ | ☐ | ☐ | ☐ |
-
-Notes / failures (file each as a backlog item):
-
--
-
-### remediate-code checklist (one row per GUI host)
-
-`remediate-code` has its own automated half — `npm run verify:remediate-hosts`
-(`scripts/remediate/verify-hosts.mjs`, wired into `verify:release`), the mirror of
-the audit gate: it deploys every remediate host surface into an isolated temp
-`$HOME` and re-runs each host's `verify()` handler from the same
-`INSTALL_HOST_DEFINITIONS` table. As with audit, that gate catches *our* drift but
-cannot invoke `/remediate-code` inside a live GUI host — a human runs the rows
-below at release, using the same GUI-host set.
-
-| Host | Surface deployed | 1. Install + open | 2. `/remediate-code` visible | 3. One live handoff | 4. Result lands under `.audit-tools/remediation/` |
-|---|---|---|---|---|---|
-| Antigravity | `.agent/skills/remediate-code/SKILL.md` skill, `.gemini/commands/remediate-code.toml` slash command, planning guide, AGENTS instructions | ☐ | ☐ | ☐ | ☐ |
-| OpenCode | global `/remediate-code` command (npm-installed) + generated `opencode.json` project permissions | ☐ | ☐ | ☐ | ☐ |
-| VS Code | generated prompt file + custom agent + Copilot instructions (`INSTALL_HOST_DEFINITIONS.vscode`, `setup_kind: 'prompt+agent'`) | ☐ | ☐ | ☐ | ☐ |
-
-Notes / failures (file each as a backlog item):
-
--
-
-## Manual workflow dispatch
-
-Use GitHub Actions `workflow_dispatch` to exercise or run the publish workflow.
-
-Dry run:
-
-- `dry_run=true`
-- `publish_tag=auto`
-
-Live publish:
-
-- `dry_run=false`
-- `publish_tag=auto` unless intentionally overriding the dist-tag
-
-`publish_tag=auto` resolves stable versions to `latest` and prerelease versions
-to `next`.
-
-Publishing a GitHub Release triggers the same workflow.
-
-## Trusted publisher setup
-
-npm Trusted Publishing is configured for this repository. If repository,
-workflow, or ownership details change, keep the npm trusted publisher entry
-aligned with:
-
-- owner or organization: `OhOkThisIsFine`
-- repository: `audit-tools`
-- workflow filename: `publish-package.yml`
-
-## Troubleshooting
-
-If a GitHub Actions run fails:
-
-1. download the uploaded `*-npm-logs` artifact
-2. rerun `npm ci` and `npm run verify:release` locally from the same commit
-3. for publish failures, rerun `publish-package.yml` with `dry_run=true`
-4. confirm npm Trusted Publishing still targets `publish-package.yml`
-
-For live child-process output while debugging the packaged/linked smokes:
-
-```bash
-AUDIT_CODE_VERBOSE=1 npm run smoke:packaged-audit-code
-AUDIT_CODE_VERBOSE=1 npm run smoke:linked-audit-code
-```
-
-The packaged smoke path strips inherited `npm_config_*`, `NODE_AUTH_TOKEN`, and
-`NPM_TOKEN` values before nested npm operations so dry runs and smoke installs
-do not accidentally inherit publish credentials or suppress tarball generation.
-
-Post-publish checks:
-
-```bash
-npm view audit-tools version
-npm view audit-tools dist-tags --json
-npm audit signatures
-```