automated-qa 0.11.0

package/lib/qa/cli.mjs

@@ -0,0 +1,538 @@
+import x from"node:path";import{fileURLToPath as k}from"node:url";import{commandCatalog as q,groupedCatalog as j,nearest as p}from"./command-catalog.mjs";const f=Object.freeze({OK:0,FINDINGS:1,INVALID:2}),m=new Set(["base","auth","width","widths","parallel","routes","run","from","to","runs","fixer","fixer-timeout","max","nav-timeout","warm-timeout","settle","text-floor","integrity-share","label","keep","inventory","json-out","timeout","note","evidence","expires","by","approve","revoke","out","format","kind","limit","budget-cells","wall-ms","families","flow","max-mutations","update-selector","delete-selector","trace","policy","ids","port","build-cmd","start-cmd","debounce","seed","count","corpus","oracle","oracle-out","min-precision","min-recall","capture-dir","discard-first","layer","queue","search","flush-every","delay","height","launcher","launcher-timeout","oracle-path","auth-lease-fd","theme-storage-key","repo","around","depth","link-adapters","across","hours","stability-runs","checkpoint-minutes","shadow-trace","lane","lanes","runid","flow-workers","plan","evidence-envelope"]),h=new Set(["states","exercise"]),E=new Set(["static","cli","coherence","runtime","atlas","agent","tournament","e2e"]),A=new Set(["install","leak-check","no-install","no-journeys","no-warm","help","json","prod","autonomous","no-archive","mutate","ratchet","resume","fresh","strict","write","all","isolated","roles","ignore","quiet","once","verbose","fast","capture","capture-full","views","workflow","hook","crud","shadow","experiments","force","list","md","open","fix","clean","commit","serve","dry-run","keep-serving","stop","status","warmup","version","no-states","no-dark","dark","stdout","strict-json","no-color","phases","measure-only","fixer-protocol","no-autonomous","i-know-this-is-not-production","study","analysis","preflight"]);function U(e){const a=new Set([...m,...h,...A,...E,...Object.keys(u)]),t={command:null,positional:[],flags:{},passthru:[],json:!1};for(let r=0;r<e.length;r++){const n=e[r];if(n==="--"){t.passthru.push(...e.slice(r+1));break}if(!n.startsWith("--")){if(n==="-h"){t.flags.help=!0;continue}if(n.length>1&&n[0]==="-"){const i=p(n.slice(1),a);throw new d(`unknown flag ${n}`+(i?`; flags take two dashes -- did you mean --${i}?`:"; flags take two dashes")+". Use `qa <command> --help` for the flags this command takes, or `--` to pass arguments through verbatim.")}t.command===null?t.command=n:t.positional.push(n);continue}const s=n.indexOf("="),o=s>0?n.slice(2,s):n.slice(2);if(!o)throw new d(`${n} has no flag name before the "=". Use \`qa <command> --help\` for the flags this command takes.`);if(!a.has(o)){const i=p(o,a);throw new d(`unknown flag --${o}`+(i?`; did you mean --${i}?`:"")+". Use `qa <command> --help` for the flags this command takes, or `--` to pass arguments through verbatim.")}const c=m.has(o)||o==="version"&&t.command==="dev"&&t.positional[0]==="atlas";if(s>0){if(!c&&!h.has(o)&&!Object.hasOwn(u,o))throw new d(`--${o} does not take a value; use --${o} or omit it`);if(!n.slice(s+1))throw new d(`--${o} needs a value`);t.flags[o]=n.slice(s+1);continue}if(o==="json"){t.json=!0;continue}if(c){const i=e[r+1];if(i===void 0||/^-(?!\d)/.test(i))throw new d(`--${o} needs a value`);t.flags[o]=i,r++;continue}if(h.has(o)){const i=e[r+1];i!==void 0&&!/^-(?!\d)/.test(i)?(t.flags[o]=i,r++):t.flags[o]=!0;continue}t.flags[o]=!0}return t}class d extends Error{constructor(a){super(a),this.name="UsageError",this.exit=f.INVALID}}class R extends Error{constructor(a,t={}){super(a),this.name="InvalidError",this.exit=f.INVALID,Object.assign(this,t)}}function P(e,{required:a=!0}={}){const t=e.positional[0];if(!t){if(!a)return null;throw new d("missing <repo> \u2014 pass the repository path (absolute paths are safest)")}return x.resolve(process.cwd(),t)}const v=new Set(["login","login-user","login-pass"]),l="<redacted>",u=Object.freeze({login:"use the host-harness launcher, invoked by persona name","login-user":"use the host-harness launcher, invoked by persona name","login-pass":"use the host-harness launcher, invoked by persona name","login-path":"handled by the target-owned launcher itself",auth:"use the host-harness launcher and the per-run lease -- there is no shared auth-state file any more",fixer:"the host agent owns source fixes; run with --once to write a prioritized brief, then apply and verify the change from the host","fixer-protocol":"the CLI never launches an agent; run with --once to write a prioritized brief for the host agent","fixer-timeout":"there is no CLI fixer process to time; run with --once to hand the brief to the host agent","measure-only":"the no-fixer marathon is already measurement-only; run with --once for a bounded host handoff"});function C(e,{command:a,flags:t=Object.keys(u)}){for(const r of t)if(e.flags[r]!==void 0)throw new R(`qa ${a}: --${r} was removed -- ${u[r]}`)}const g=new Set(["base"]),w=new Set(["fixer","start-cmd","build-cmd"]),y=/pass|secret|token|key|credential|auth/i;function S(e){let a;try{a=new URL(e)}catch{return e}let t=!1;(a.username||a.password)&&(a.username=l,a.password="",t=!0);for(const r of[...a.searchParams.keys()])y.test(r)&&(a.searchParams.set(r,l),t=!0);return t?a.toString().replaceAll(encodeURIComponent(l),l):e}function I(e){return e.replace(/(^|\s)(--?[A-Za-z][\w-]*|[A-Za-z_]\w*)=(\S+)/g,(a,t,r,n)=>y.test(r)?`${t}${r}=${l}`:a)}function b(e,a){return v.has(e)?l:g.has(e)?S(a):w.has(e)?I(a):a}const N=new Set([...v,...g,...w]);function _(e){const a=[];for(let t=0;t<e.length;t++){const r=e[t],n=r.startsWith("--")?r.indexOf("="):-1,s=r.startsWith("--")?n>0?r.slice(2,n):r.slice(2):null;if(s===null||!N.has(s)){a.push(r);continue}if(n>0){a.push(`--${s}=${b(s,r.slice(n+1))}`);continue}a.push(r),t+1<e.length&&(a.push(b(s,e[t+1])),t++)}return a}function M(e,a){const t=[];for(const[r,n]of Object.entries(e.flags))if(!a.has(r))if(n===!0)t.push("--"+r);else{if(n===!1||n==null)continue;t.push("--"+r,String(n))}return t.push(...e.passthru),t}function F(e){return{say:(...n)=>{const s=n.join(`
+`);(e?process.stderr:process.stdout).write(s+`
+`)},warn:(...n)=>process.stderr.write(n.join(`
+`)+`
+`),emit:n=>{e&&process.stdout.write(JSON.stringify(n,null,2)+`
+`)},json:e}}function L(e,a){return e=String(e),e.length>=a?e:e+" ".repeat(a-e.length)}function V(e,a){return e=String(e),e.length>=a?e:" ".repeat(a-e.length)+e}function W(e,{indent:a="  "}={}){if(!e.length)return"";const t=[];for(const r of e)r.forEach((n,s)=>{t[s]=Math.max(t[s]??0,String(n??"").length)});return e.map(r=>a+r.map((n,s)=>s===r.length-1?String(n??""):L(n??"",t[s])).join("  ")).join(`
+`)}const G={"":`qa \u2014 evidence-first frontend verification
+
+Seven commands. The one long-running "do everything" command:
+  qa run <repo> --base URL --once
+                                  measures, prioritizes, and hands one brief to the host agent
+  qa run <repo> --base URL --hours 10
+                                  resumable measurement; waits for host-owned source changes
+
+COPY-PASTE FOR YOUR CURRENT CODEX/CLAUDE AGENT:
+  Use frontend-verify in this host worktree. Run \`qa run <repo> --base URL --once\`, read
+  the generated \`.verify/lanes/<class>/brief.md\`, own the source fixes and commits, then rerun
+  the same command to recheck.
+
+Then, for one check at a time:
+  qa verify <repo>                 static analysis, archived and triaged
+  qa verify <repo> --base URL      also measure the running app
+  qa verify <repo> --preflight     check readiness and explain blockers
+
+Read the evidence:
+  qa show <repo>                   ranked findings and coverage (triage)
+  qa show next <repo>              the next finding to fix
+  qa show report <repo>            self-contained HTML report
+
+  qa help --phases                 all commands, grouped by task
+  qa help --search TERM            find a command by task, artifact, or flag
+  qa help <command>                usage and options
+  qa help [command] --json         machine-readable help
+  qa dev version                   installed version
+
+Every pre-consolidation top-level name is retired (see RETIRED_COMMANDS in
+lib/qa/command-catalog.mjs for the full list): typing one exits 2 and names
+its replacement (qa help <old-name> does the same).
+
+Generic guessed mutation replay is disabled.
+Service-worker or cache-dependent protected journeys are unmeasured.
+
+Exit codes: 0 clean/done \xB7 1 findings or regression \xB7 2 could not run (never a pass).
+Relative <repo> paths resolve against your shell's working directory.`,get phases(){const e=q({commandsDir:k(new URL("./commands",import.meta.url)),help:this});return`qa commands \u2014 grouped by task
+
+`+j(e).map(({group:a,commands:t})=>a+`
+`+t.map(r=>`  ${this[r]?.split(`
+`)[0]??`qa ${r}`}`).join(`
+`)).join(`
+
+`)+`
+
+Use qa help <command> for options and examples.`},"verify preflight":`qa verify <repo> --preflight [--base URL] [--prod] [--strict]
+
+Preflight. Hard failures exit 2 and name what to fix: unreadable repo, node < 18,
+zero routes, unreachable --base, --prod against a detectable dev server, a lock
+held by another sweep, a malformed verify.roles.json. Warnings exit 0 (or 1 with
+--strict): Playwright/chromium missing, a build process running, stale auth
+state, dirty git tree, journeys absent while mutation routes exist, roles file
+absent while more than one principal was detected.`,"init study":`qa init <repo> --study [--json]
+
+Studies the repo and writes, under <repo>/.verify/:
+  research.json         everything below, with a confidence on every heuristic
+  research.md           the study a marathon's Phase 1 asks for
+  ledger.md             exactly inventory.counts.routes rows; both numbers printed
+  journeys.draft.mjs    one draft journey per mutation route, fields from source
+research.json's harness field and research.md's handoff group source mutations
+by exact entity identity, retain shared-hook importing routes, and rank affected
+routes/surfaces. Each item names source-derived assertion candidates and missing
+persona, declaration, fixture/cleanup, readback, driver, and provenance work.
+Validated declarations and present drivers are not execution: every handoff is
+source-derived/non-executed. No selectors, payloads, or runtime proof are guessed.
+The draft is never loaded by the sweep. Promote it to <repo>/verify.journeys.mjs
+after replacing every TODO selector.`,verify:`qa verify <repo> [any verify.sh flag] [--lane LANE] [--autonomous] [--json]
+       qa verify <repo> [--no-archive] [--keep N] [--link-adapters crud,shadow,experiments]
+
+Runs verify.sh with the flags given, unchanged. Then opens a private pending
+run directory and atomically writes immutable report snapshots plus normalized
+roles and the exact validated CRUD snapshots, with their sha256 digests. The
+agent receives only those explicit paths and never reads the live role or CRUD files.
+It always attempts a compatible qa-agent
+(a verified prebuilt binary, or a \`cargo build\` fallback) with those explicit
+paths, the run ID, lane and mode via --emit-result -- optional evidence by
+default (unmeasured when no compatible binary exists), never gating unless
+--autonomous makes it required. Only after the returned digests and schema
+are verified does the pending directory publish to .verify/runs/<id>/: a
+reader sees no run or a complete run, never a partial one. run.json carries
+the embedded result under \`agent\`, plus \`lane\` and \`runId\`; the archive
+also gets agent-result.json (its canonical bytes). Adapter evidence (qa measure crud,
+qa measure shadow replay, qa measure experiments) is NEVER folded in automatically: name the
+adapters explicitly with --link-adapters, and their findings travel with their
+own denominator rather than entering this run's counts. Appends to
+.verify/trajectory.jsonl and prints the triage. Exit is derived: 2 dominates
+(the gate itself invalid, OR --autonomous with an absent/invalid agent), else
+1 if the gate found gating evidence, else 0. --json output separates \`gate\`
+(verify.sh's own exit) from \`agent\` (the embedded result) so a consumer
+never conflates the two verdicts. --no-archive runs the same snapshot and
+agent sequence into a private pending directory and still emits gate/agent
+on stdout (--no-archive --autonomous still enforces require-agent) but
+publishes nothing: the pending directory is discarded, only after the
+result is validated, so a failure still leaves a diagnosis on stdout.
+
+--autonomous also produces the canonical three-file graph contract
+(nodes.jsonl, edges.jsonl, run-manifest.json) via the cargo-built qa-agent
+into .verify/autonomous/ and validates its manifest. This is reported under
+the JSON output's \`autonomous\` field, distinct from \`agent\`. Needs cargo;
+absent cargo is reported unmeasured. A required kernel or manifest failure
+is a hard exit 2. The earlier 42-file surface is retired.`,"show triage":`qa show <repo> [--run ID] [--json]
+
+Reads an archived run (latest by default). Groups runtime findings by (kind,
+selector) across routes, static by rule; ranks by severity, leverage, and
+determinism; prints every denominator; flags structural tells that mean the run
+measured something other than the app.`,"show next":`qa show next <repo> [--run ID] [--json]
+
+Picks the top finding from triage (skipping fids blocked by qa run loop), writes a
+brief to .verify/next.md and .verify/next.json: where, what, the atlas entry,
+affected routes, how to reproduce, how to waive with proof. Exit 1 when a finding
+was selected, 0 when there is nothing to fix, 2 when the run is invalid.`,"verify runs":`qa verify <repo> --base URL --runs 3 [--routes /a,/b] [--warmup] [sweep flags] [--json]
+
+Runs sweep.mjs N times serially (--parallel 1 forced) into .verify/stability/<id>/,
+plus .verify/stability.json (the latest). --warmup runs one extra, UNCOUNTED sweep
+first to prime the dev server compile; it is not one of the N. Any run that exits
+2, or whose own integrity gate is not ok, makes the WHOLE measurement INVALID
+(exit 2) -- partial results are still written, labelled invalid. Per finding:
+stable (N of N, gates), intermittent (>= ceil(2N/3), gates), ghost (< ceil(2N/3);
+listed under "needs reproduction", never gating). Exit 1 only when a gating
+stable/intermittent P0/P1 finding exists. Also reported: routes whose surface
+fingerprint differs between runs (informational), and per-metric min/median/max
+with env-sensitive marked when max/min > 3. Runs, routes, and cells are printed
+as denominators beside every count.`,"show diff":`qa show diff <repo> [--from ID] [--to ID] [--json]
+
+Fixed / new / persisting findings between two archived runs (default: the two
+newest). Identity is the fid, so a line shift does not read as fixed-and-new.`,"show ledger":`qa show ledger <repo> [--json]
+
+Prints the ledger: one row per inventory route with entities, mutations, whether
+a journey covers it, whether the latest run swept it, and its status. The row
+count is asserted equal to inventory.counts.routes.`,"show runs":`qa show runs <repo> [--json]
+
+Lists archived runs with mode, exit, counts and integrity.`,"run loop":`qa run loop <repo> [verify flags]
+
+Runs one ratcheted gate, ranks the next actionable finding, and writes
+.verify/next.md plus .verify/next.json for the host agent. Exit 0 means the
+measured scope is clean; exit 1 means the brief was handed off; exit 2 means
+the measurement was invalid. The CLI never launches an agent, executes a
+fixer command, or commits source. Use qa run <repo> --once for the normal
+bounded host-agent handoff.`,run:`qa run <repo> [--base URL | --serve] [--hours N]
+              [--lane LANE] [--lanes N] [--widths 390,1440] [--no-states] [--no-dark]
+              [--stability-runs 3] [--checkpoint-minutes 45] [--resume] [--fresh] [--keep-serving] [--no-autonomous]
+              [--once] [--dry-run] [--json] [passthrough verify flags]
+       qa run [kind] <repo> ...   kind: loop, watch, serve (default: below)
+
+The one long-running "do everything" command. With no kind, every phase below is
+a child \`qa <cmd>\` process; this command reads what each one wrote to .verify/
+and decides whether the next one runs:
+  0  --base is used as given. Otherwise this command builds and starts a
+     production server itself (qa run serve --prod; its base becomes --base,
+     stopped at the end unless --keep-serving). If that fails without an
+     explicit --serve, the run is static-only and the report says so; with
+     --serve the failure is INVALID.
+  1  qa verify --preflight -- exit 2 stops everything and prints its fix lines.
+     When a --base is known, its probe of it decides --prod automatically for
+     every phase below: prod -> add --prod, dev -> continue without it and
+     say timing findings will be P3, unknown -> continue without it.
+  2  qa init --study; qa init --roles --ignore -- init never overwrites. With
+     more than one principal and no roles file, init scaffolds one role per
+     principal (each owning "/") and the run continues, saying so.
+  2b Writes turn on when verify.crud.json declares every flow
+     "production": false and the base is loopback: the crud and coherence
+     phases pass --mutate themselves. The sweep gets --mutate only when an
+     app-owned journey declares mutates: true -- generic guessed replay is
+     disabled, so without such a journey the flag could only invalidate the
+     run, and the decision log says it was withheld. An explicit
+     --lane wins; otherwise real-integration is selected when
+     verify.auth-launcher.mjs exists and every persona in verify.roles.json
+     declares "expect". Draft journeys whose every field
+     and submit control resolved from source are promoted to
+     .verify/journeys.mjs under that same mutation opt-in. Each decision and
+     its reason is printed and lands in the exit report.
+  3  qa verify --ratchet (the baseline) -- exit 2 stops. No --base means a
+     static-only run, said plainly in the report.
+  3b deep measurement, once, in two groups: Group A (concurrent -- read-only
+     against the app, or writing only to an isolated target) is static
+     coherence, qa measure invariants mine + status (review/enforce stay a human
+     call), and qa measure shadow replay (when verify.shadow-trace.json or
+     .verify/shadow-trace.json exists -- a trace of real traffic cannot be
+     manufactured by the run). Group B (strictly serial -- these can all
+     write to the SAME dev database) is qa measure crud (under the mutation opt-in),
+     qa measure experiments (qa run generates the Node-owned default queue from
+     the baseline's Rust route priority when none exists, so it needs cargo;
+     pass --queue <path> for a supplied plan; wall time is a
+     quarter of what is left, at most 30 minutes), then runtime coherence
+     (under its own repo-declared opt-in). Whatever could not run is a named
+     line under "what was not measured" with how to enable it. Whichever
+     adapter left measured evidence is folded into the very next qa verify
+     via --link-adapters automatically.
+  4  qa verify --runs N on the baseline's runtime P0/P1 routes (skipped
+     when there are none) -- ghost findings are written into .verify/loop.json's
+     blocked list so the fix loop never chases them.
+  5  qa fix plan --lanes N (one worktree + brief per class, disjoint batches),
+     then waits for the host agent to execute the briefs. --once hands off
+     immediately with exit 1.
+  6  every chunk: qa show ledger, qa show report, one line appended to
+     .verify/trajectory.jsonl. If something was fixed and time remains,
+     qa verify runs again and qa show diff compares it -- new findings send it
+     back to step 4 with whatever time is left. After the depth ladder is
+     exhausted, runtime measurements repeat at --checkpoint-minutes cadence
+     without --resume; source changes wake the coordinator sooner. Static-only
+     runs wait for source changes. --once finishes after the first full pass.
+  7  exit report: .verify/marathon-report.md (routes total/clean/fixed with
+     commit hashes/open fids/needs-reproduction ghost fids, the ratchet
+     trajectory, every phase's command and exit code verbatim, what stayed
+     unmeasured, which adapters got linked, the depth ladder's rungs with
+     their --resume reused/rejected counts) plus a qa show report HTML. Its first
+     word is PASS, FAIL, or INVALID, matching this command's own exit code.
+--status reads .verify/marathon.json and prints phase, running/stopped/finished,
+minutes left, base, lane, writes on/off, depth rung, last command and decision,
+the last checkpoint counts, wait state, and the report path -- for an agent polling a
+background run. Exit 0 running or finished, 1 stopped mid-run (resume it), 2
+nothing has run here.
+A bare \`qa run <repo>\` on a repo whose .verify/marathon.json is not
+"done" resumes it -- this covers both a killed process and a --once handoff to
+open lanes; --fresh discards that state and starts over. A separate marathon.lock
+refuses a second live coordinator, including --fresh. --resume is still
+accepted and is a no-op. A recorded server that died is restarted only if
+--serve was given, otherwise that is INVALID. --dry-run prints the plan
+above with this run's actual flags and runs nothing. --mutate is added only
+by the declaration rule in step 2b, never by --hours or any other flag.
+Default --hours is 10, default --lanes is 4. Exit: 0 the final gate is
+clean, 1 it has findings (or lanes are ready/open, or time ran out with
+findings open), 2 a phase could not run.
+
+--fixer, --fixer-protocol, --fixer-timeout, --measure-only, and --commit are
+retired for qa run: the host agent owns source changes and commits. Use --once
+for a copy-paste-ready brief.
+loop/watch/serve are reachable by name (\`qa run loop ...\`, \`qa run watch ...\`,
+\`qa run serve ...\`) -- see qa help run loop / run watch / run serve for their
+own flags and exit codes.`,"fix fp":`qa fix fp add <repo> <fid> --note "why" [--evidence REF --expires YYYY-MM-DD] | qa fix fp list | qa fix fp rm <id>
+
+Source entries retain their content anchor. Runtime entries require evidence
+and expiry, and match only the same repository, rule, route, persona, selector
+and measurement identity -- lane, phase, width and rule version, the identity of
+the observation. The run's measurement modes are recorded on the entry, not part
+of that key, so climbing a depth-ladder rung does not retire the adjudication.
+Raw observations are never removed. Stored in
+~/.config/qa/known-false-positives.json (QA_HOME overrides).`,"dev selftest":`qa dev selftest [--parallel N] [--static] [--cli] [--coherence] [--runtime] [--atlas] [--e2e] [--agent] [--tournament] [--fast] [--all]
+
+Runs the selected suites. Node test files use four workers by default;
+--parallel N controls that limit. Child processes can spawn their own children.
+Choose --all, --fast, or individual suites, not a mixture. Default: static + cli, the two that need nothing but
+node. --fast runs every suite that does not drive a browser (static, cli,
+coherence, agent, tournament) -- the per-change gate, minutes not a quarter of
+an hour. --all runs every suite, and is what a release is graded on: --fast
+cannot see a probe rule that stopped matching, because every rule that needs a
+browser to fire lives in runtime/atlas/e2e.
+
+  static      selftest-static.sh -- every classifier rule, planted and asserted
+  cli         the unit suites plus selftest-cli.sh against fixture repos
+  coherence   selftest-coherence.sh -- the entity chain end to end: families,
+              the sparse obligation universe, a real mutation and authoritative
+              readback through a fake driver, the per-obligation join, the
+              confirmed root cause and its affected surfaces
+  runtime     selftest.sh -- the probes, differentially (needs Playwright)
+  atlas       selftest-atlas.sh -- every runtime finding kind still fires (needs Playwright)
+  e2e         selftest-e2e.sh -- one real run of the whole chain, inventory
+              through classify, sweep, the rust kernel, the artifact contract,
+              triage, report and SARIF, asserting the JOINS between them and
+              that two identical runs are byte-identical (needs Playwright and cargo)
+  agent       selftest-agent.sh -- the artifact contract through a symlinked install (needs cargo)
+  tournament  cargo test plus the adapter, privacy and benchmark gates (needs cargo)
+
+A suite that cannot run (no Playwright, no cargo) is reported as skipped, never
+as passed. Exit 1 if a suite failed, 2 if one could not run.`,"dev atlas":`qa dev atlas [--json] [--write] [--layer N] [--strict]
+
+Cross-references references/atlas.md (the 11-layer failure taxonomy) against
+the real detectors: bin/classify.mjs's static rules, bin/probe.js's and
+bin/sweep.mjs's runtime finding kinds, and lib/qa/atlas.mjs's KIND_ATLAS map.
+Classifies every S/R class as implemented (lists the rule/kind ids),
+deliberately-not-implemented (the reason from the "Evaluated and deliberately
+not implemented" table), or gap (nothing implements it); every G/H/A class as
+not-automatable (says which: a generated journey, a human question, or an
+architecture choice) -- and separately notes when a detector exists anyway for
+a class atlas.md itself marks not-automatable, since that usually means the
+detector is a partial proxy or the atlas's own Det column is stale. Also
+reports the reverse drift: every finding kind with no atlas id, and every
+atlas id a detector references that is not a row in atlas.md -- both are bugs.
+--layer N narrows the printed table to one layer (accepts "--layer N" or
+"--layer=N"; "--layer" alone is not a value flag in this CLI's shared parser).
+--write regenerates references/ATLAS-COVERAGE.md from the same data. Current
+producer-derived coverage:
+  v2: 77 of 105 S/R classes; 79 of 108 mode obligations
+  v1: 72 of 96 S/R classes; 74 of 99 mode obligations
+Both have 30 not-automatable classes. Producers are discovered recursively from
+every JavaScript finding producer under bin/ and lib/. Exit 1 under --strict when
+any drift was found, 0 otherwise -- gaps alone never fail the command.`,"show report":`qa show report <repo> [--run ID] [--out FILE] [--format html|sarif|github|junit]
+       qa show runs <repo> [--json]
+       qa show diff <repo> [--from ID] [--to ID] [--json]
+
+HTML is the default. Export formats preserve the archived gate exit.
+diff/runs/ci are also reachable directly under show (qa show diff/runs/ci <repo>),
+not only nested under report.
+
+Renders one self-contained HTML file (inline CSS/SVG/JS, no external URLs) from
+an archived run: verdict banner with exit code and denominators, integrity
+gauges, the trajectory as a line chart, the cell matrix heatmap, ranked
+findings, the mutation -> entity -> route sync graph, structural tells, and
+stability classes / the ledger when those have been written. Default output:
+<repo>/.verify/report.html.`,"show graph":`qa show graph <repo> --format dot|mermaid|json [--kind sync|transition]
+       qa show graph <repo> --run ID [--around RECORD_ID] [--depth N] [--limit N] [--json]
+
+Prints the mutation -> entity -> route sync graph from .verify/inventory.json
+(--kind sync, default), or the route -> route transition graph projected from
+.verify/autonomous/edges.jsonl (--kind transition) -- unmeasured and empty,
+exit 0, if that file has not been written yet.
+
+With --run, verifies nodes.jsonl/edges.jsonl against the archived run.json graph
+SHA-256 digests, VALIDATES graph integrity, and returns a bounded neighbourhood.
+--around must name an existing record id; --depth is a nonnegative integer
+(default 1), --limit a positive integer (default 200). --kind must name a finite
+node kind: finding, route, component, query, mutation, entity, endpoint, role,
+transition, or evidence. Unknown kinds/centres and invalid numbers exit 2.
+Collections carry returned/total/truncated. A requested graph that is absent or
+fails integrity validation exits 2 -- never an empty successful neighbourhood.`,"show ci":`qa show ci <repo> [--run ID] --format sarif|github|junit [--out file]
+
+Renders an archived run (latest by default) for a CI system:
+  sarif    SARIF 2.1.0, one result per finding, rules from distinct kinds,
+           partialFingerprints.fid, atlas ids as helpUri fragments
+  github   GitHub Actions workflow commands (::error/::warning/::notice), one per line
+  junit    JUnit XML: one testsuite per phase, one testcase per group
+Without --out the rendered content is written straight to stdout (redirect it);
+with --out it is written to that file (resolved against your shell's cwd) and a
+short summary is printed instead. Exit code mirrors the archived run's own exit.`,init:`qa init <repo> [--roles] [--workflow] [--hook] [--ignore] [--all] [--crud]
+
+Scaffolds the per-repo wiring. With no flags, does everything below (same as
+--all); a specific flag narrows it to just that one:
+  --roles     verify.roles.json \u2014 from .verify/research.json principals if
+              present, else one default role owning "/"
+  --ignore    .verifyignore (design-lab defaults noted, commented) and appends
+              .verify/ to .gitignore if it is not already ignored
+  --workflow  .github/workflows/frontend-verify.yml \u2014 static gate on every PR;
+              runtime gate + SARIF upload only when FRONTEND_VERIFY_BASE is set
+  --hook      prints (does not write) the Stop-hook JSON for ~/.claude/settings.json
+              and a pre-commit sample
+  --crud      verify.crud.json \u2014 one flow per entity qa init --study saw written,
+              every flow "production": false. Never implied by --all or by no
+              flags: this file is the opt-in that lets qa run write to the
+              app (on a loopback base), so write it only against a disposable DB
+Never overwrites an existing file; prints created / skipped-exists / appended
+for each action, so a second run is visibly a no-op.`,"run serve":`qa run serve <repo> [--prod] [--port N] [--build-cmd CMD] [--start-cmd CMD] [--timeout S]
+qa run serve <repo> --stop
+qa run serve <repo> --status
+
+Builds (with --prod, using the repo's own build script) then starts the app in
+the background -- start script for --prod, dev script otherwise -- detached in
+its own process group so this command returns while the app keeps running.
+Output goes to .verify/serve.log; state to .verify/serve.json. Waits for
+liveness (any HTTP response at --port, default 3000) up to --timeout seconds
+(default 180), then prints the exact "qa verify ... --base ..." line to run
+next. Refuses a second start while a recorded pid is still alive, and refuses
+if the port is already in use. A build failure or a liveness timeout exits 2
+with the log path. --stop kills the process group and clears the state file
+(always exit 0, idempotent). --status probes the recorded server and reports
+liveness plus dev/prod detection: exit 0 live, 1 not running.`,"run watch":`qa run watch <repo> [--debounce MS] [--once]
+
+Watches source files -- recursive fs.watch where the platform supports it
+(darwin, win32, linux on node >= 20), mtime polling every 2s otherwise --
+ignoring .verify, node_modules, .git, .next, dist, build, out. On change,
+re-runs the static gate (\`qa verify <repo>\`, a real child process) and
+prints fixed / new / persisting findings by fid since the previous archived
+run. --debounce sets the quiet period before a cycle runs (default 400ms);
+changes that arrive while a cycle is already running coalesce into exactly
+one follow-up cycle, never one per file. --once runs a single cycle after
+the first change and exits with that cycle's own gate exit code (for
+scripting and tests). Ctrl-C stops cleanly: the watcher stops taking new
+changes immediately, and an in-flight cycle is allowed to finish archiving
+before the process exits.`,"measure shadow":`qa measure shadow replay <repo> --trace FILE --base URL --isolated [--policy verify.shadow.json] [--ids /route/:id=123,...] [--auth state.json] [--json]
+
+Read-only replay of a collected shadow trace (bin/shadow-collector.mjs output)
+against an isolated target. Refuses (exit 2) without --isolated, against a
+target that looks production-like, without a policy declaring
+replay.isolated === true and replay.production === false, when the trace uses
+a route/endpoint template the policy's allow_routes/allow_endpoints does not
+cover, or when there is nothing replayable. Only replays GET navigations, in
+transition_index order; a non-GET trace row is always skipped, never issued.
+Compares same-origin traffic observed during each navigation to the trace's
+expectation for the same endpoint. Writes
+.verify/autonomous/shadow-replay.json. Exit 1 when a measured endpoint moved
+from 2xx to 4xx/5xx (finding shadow.drift), 0 when replayed clean.`,"measure invariants":`qa measure invariants mine    <repo>
+qa measure invariants review  <repo> --approve ID [--by NAME]
+qa measure invariants review  <repo> --revoke ID
+qa measure invariants enforce <repo>
+qa measure invariants status  <repo>
+
+The independent invariant authority, separate from the Rust output directory
+(agent/src/invariants/*.rs fail-closes Reviewed -> Enforced on purpose; this
+is the authority that can actually promote one). Proofs are sha256 digests of
+archived run files under .verify/runs/<id>/, recomputed at approve time and
+again at pack-load time -- a tampered archive makes approve refuse and makes
+the generated pack throw (infrastructure exit 2), never a finding.
+
+  mine     mines route-level candidates over archived runtime runs, writes
+           .verify/invariants/candidates.json
+  review   --approve ID promotes a candidate into the committed policy file
+           <repo>/verify.invariants.json (refused below support 2, above 0
+           counterexamples, or on any proof mismatch); --revoke ID removes one
+  enforce  regenerates .verify/rules/invariants.mjs, a runtime rule pack that
+           re-verifies every enforced proof on load and files
+           invariant.violated P1 findings for route-reachable / renders-text
+           (the only kinds a pack can independently re-check per cell; other
+           approved kinds still get proof-tamper protection, see \`status\`)
+  status   lifecycle table: candidate / approved / enforced, with support,
+           counterexamples, proof validity, and whether a kind is runtime-checked`,"fix plan":`qa fix plan   <repo> [--run ID] [--lanes N]
+qa fix gate   <class> <repo>
+qa fix close  <class> <repo>
+qa fix rebase <repo>
+qa fix board  <repo>
+
+Parallel class-level fixes. plan groups the latest archived run's findings
+into classes ((rule) or (kind, selector)), resolves the files each would
+touch, packs classes into batches whose files are disjoint (--lanes N wide,
+default 4), opens one git worktree + branch qa/<class> per lane of the first
+batch under .verify/lanes/<class>/tree, writes .verify/lanes/<class>/brief.md
+and .verify/board.md. Exit 1 lanes ready, 0 nothing to plan, 2 invalid.
+gate runs qa verify in that worktree with the plan's base and flags under one
+lock; exit 0 every finding of the class gone and no regression, 1 red (the
+worktree is reverted and the attempt recorded), 2 could not gate. close needs
+a passing gate: commits, pushes qa/<class>, opens the PR with the numbers,
+records it; never merges. rebase rebases every open lane onto main and
+re-gates; a conflict marks the lane conflict. board regenerates
+.verify/board.md. qa run plans the lanes and leaves source fixes and commits to
+the host agent; it never executes a fixer.`,"measure crud":`qa measure crud <repo> --base URL --mutate --max-mutations N [--flow NAME] [--auth state.json]
+
+Executable CRUD reconciliation: performs and observes create/read/update/delete
+plus reload and navigation reconciliation through a real browser, per flow x
+persona declared in <repo>/verify.crud.json (see references/verify.crud.example.json).
+Every browser context is intercepted before transmission: same-origin writes
+must match the selected declared flow and shared budget, including popups and
+workers; service workers are blocked. An authorization gap invalidates the run.
+Each persona's storage state is minted through <repo>/verify.auth-launcher.mjs
+(the same launcher and lease the sweep uses; verify.roles.json carries no
+credentials) and checked against the identity oracle where the app serves
+one; a persona that cannot be provisioned refuses the run rather than
+measuring the login page. --auth <state.json> overrides with one file for
+every persona; --launcher <path> and --oracle-path <path> override the launcher
+and the oracle endpoint exactly as they do for the sweep (defaults
+<repo>/verify.auth-launcher.mjs and /__qa/identity).
+Refuses without --mutate, refuses if verify.crud.json is absent or any flow's
+"production" is not literally false, without a positive --max-mutations,
+or against a non-loopback base (unless the explicit non-production override is
+used; production-looking names are always refused). A persona listed under a flow's "denied" is exercised for
+authorization only, never the full cycle. Mutations are capped at
+--max-mutations; a create this run performs is always affordable
+to clean up too, and cleanup is verified, never assumed. Writes
+.verify/crud-observed.json. Exit 0 measured clean, 1 on any P0/P1 finding
+(crud.create-failed, crud.write-lost, crud.update-lost, crud.delete-ineffective,
+crud.unauthorized-allowed, crud.cleanup-failed), 2 invalid (refused, or the run
+measured nothing).
+
+The create surface is found as \`form:visible\` on the flow's route, waited for
+(--form-timeout, default 10000ms). A surface that is not there at load -- a
+dialog behind a quick action, a form gated on a filter -- needs the flow to
+name an entry in <repo>/verify.journeys.mjs via "journey": its run() is
+called after landing on the route and must leave the surface mounted (the
+sweep drives the same entry, so write nothing in run()). "form_selector"
+names the surface when it is not a <form> (a dialog), "submit_selector" the
+control inside it that performs the write (clicked instead of
+requestSubmit()). A journey entry may carry create(page, { sentinel }) to
+perform the create itself where the generic filler cannot (a <select>-only
+form), returning { sentinel } when the text that proves the write is not
+what was typed. "update_selector" / "delete_selector" set to false declare
+the surface has no such control (step stays unmeasured, with that reason);
+"cleanup_required": false skips the direct DELETE for a record type the API
+cannot delete. Templates interpolate only {fixtureId} and {sentinel}; unresolved
+tokens are unmeasured, never guessed. Schema-v2 declarations may also name
+bounded canonical entity aliases for coherence.`,"measure coherence":`qa measure coherence <repo> [--views] [--base URL --mutate --flow NAME --max-mutations N]
+                          [--plan agent-result.json] [--flow-workers N] [--runid ID]
+
+Without --mutate, prints the coherence-IR denominators (writes, reads,
+surfaces per route component, candidates with their affected surfaces) and the
+fan-out view for every candidate mutation; --views adds the full fan-out
+(mutation -> surfaces) and fan-in (surface -> writers) tables and the
+obligation universe (mutation x surface x principal x context). No browser. Runtime mode is fail-closed: every
+selected flow must be schema-v2 with a crosscheck and the repository must
+provide a provenance adapter (verify.crud.json schema_version 2 with a
+crosscheck, verify.coherence.mjs, verify.coherence-provenance.mjs).
+--plan <agent-result.json> executes the obligations the Rust kernel selected
+(auto-detected from the latest archived run when its coherenceObligations
+dimension is measured) and reports planned/reached/compared/agreed;
+--flow-workers N runs isolated flows in parallel (distinct entities, or both
+flows declaring isolation: per-flow). Schema-v2 canonical entity aliases join
+declared endpoint families while retaining the original endpoint evidence.
+Incomplete evidence exits 2, never clean.`,"measure experiments":`qa measure experiments <repo> --base URL [--budget-cells N] [--wall-ms MS] [--families a,b] [--mutate] [sweep flags] [--json]
+
+Executes the accepted candidates from .verify/autonomous/experiment-queue.json,
+or --queue <path> naming one explicitly (a ranked plan -- never auto-executed
+elsewhere), as targeted sweeps, one control/treatment pair per (route, family):
+  latency-baseline-vs-injection   plain sweep vs the same route with --states slow
+  role-pair                       the two owning roles' cells from one sweep
+                                   (needs two roles in verify.roles.json)
+  mutation-vs-no-mutation         unmeasured: generic guessed replay is disabled and
+                                   fails closed; use declared CRUD or coherence instead
+navigation-vs-reload and cache-enabled-vs-disabled are also not executable by
+this tool and are always reported unmeasured with the reason. A trial whose sweep
+exits 2 invalidates that family for that route -- never averaged. Writes
+.verify/experiment.json, .verify/experiment-observations.json,
+.verify/autonomous/experiment-observation.json (via bin/experiment-runner.mjs)
+and .verify/autonomous/experiment-execution.json. Exit 0 measured clean, 1 a
+measured treatment introduced a P0/P1 the control lacked, 2 nothing was
+measured (missing queue, budget exhausted before anything ran, or every
+combination was ineligible/invalid).`,init:`qa init <repo> [--study|--analysis] [--roles|--crud|--ignore|--workflow|--hook|--all]
+
+Scaffolds declarations without overwriting them. --study writes source-derived research; --analysis additionally writes .verify/analysis.json and analysis.md with an evidence ledger, feature/context/risk/story/mutation/proof/fix view. It never invents business requirements or executes mutations.`,show:`qa show [kind] <repo> ...   kind: triage (default), next, report, ledger, graph, analysis
+
+Reads results. \u2018show analysis\u2019 renders the generated analysis and \u2018--format json\u2019 emits its structured artifact.`,"dev validate":`qa dev validate <repo> [--run ID]
+
+Validates every present artifact under <repo>/.verify/ (inventory.json,
+classify.json, sweep.json, research.json, stability.json, next.json,
+crud-observed.json, autonomous/shadow-replay.json,
+autonomous/experiment-execution.json) against the JSON Schemas in schemas/,
+using a dependency-free draft 2020-12 subset validator. Also validates the
+archived copies (inventory.json, classify.json, sweep.json, run.json) under
+.verify/runs/<id>/ -- <id> is --run when given, else the latest archived run
+if one exists; an explicit --run that does not resolve is an error. Prints a
+table of artifact -> ok/absent/VIOLATIONS/ERROR with the path and message of
+each violation. Absent is not a failure -- most artifacts are produced by
+commands nobody has run yet in a given repo. Exit 0 when every present
+artifact validates, 2 on any schema violation or unreadable/malformed file.`,measure:`qa measure <kind> <repo> ...   kind: coherence, crud, experiments, shadow, invariants
+
+Dispatches to one of the five deep-measurement adapters. Each kind keeps its
+own flags and subwords -- \`qa measure shadow replay <repo> ...\`, \`qa measure
+invariants mine|review|enforce|status <repo>\`. crud and coherence --mutate
+perform real, declared mutation writes under the repo's own opt-in
+(verify.crud.json); every other kind is read-only. See qa help measure
+coherence / measure crud / measure experiments / measure shadow / measure
+invariants for what each one measures and its exit codes.`,show:"qa show [kind] <repo> ...   kind: triage (default), next, report, ledger, graph, analysis\n\nReads results. With no kind, prints ranked findings and coverage (triage).\nreport's own sub-verbs stay reachable both nested (`qa show report\ndiff|runs|ci <repo>`) and directly (`qa show diff|runs|ci <repo>`). See qa\nhelp show triage / show next / show report / show ledger / show graph for\neach one's flags, output, and exit codes. `qa show analysis <repo>` renders the generated analysis; `--format json` emits its structured artifact.",fix:"qa fix <sub> ...   sub: plan, gate, close, rebase, board (lanes) \xB7 fp add|list|rm\n\nParallel class-level remediation (`qa fix plan <repo>`, `qa fix gate <class>\n<repo>`, ...) and the cross-repo false-positive memory (`qa fix fp\nadd|list|rm ...`). See qa help fix plan / fix fp for flags, output, and exit\ncodes.",dev:"qa dev <kind> ...   kind: atlas, selftest, validate, version\n\nMaintaining the harness itself, not the target repo under test: `qa dev atlas\n--strict`, `qa dev selftest --fast`, `qa dev validate <repo>`, `qa dev\nversion --json`. See qa help dev atlas / dev selftest / dev validate / dev\nversion for flags and exit codes.","dev version":`qa dev version
+
+Prints the installed name, semver, short commit, node version, and install
+root -- both as one line and, with --json, as {name, version, commit, node,
+root}.`};export{A as BOOLEAN_FLAGS,w as COMMAND_VALUE_FLAGS,f as EXIT,G as HELP,R as InvalidError,h as OPTIONAL_VALUE_FLAGS,l as REDACTED,u as REMOVED_FLAGS,v as SECRET_VALUE_FLAGS,E as SELFTEST_SUITES,g as URL_VALUE_FLAGS,d as UsageError,m as VALUE_FLAGS,M as forwardFlags,V as lpad,F as makeOutput,L as pad,U as parseArgs,_ as redactArgs,b as redactValue,C as rejectRemovedFlags,P as resolveRepo,W as table};

package/lib/qa/coherence/analyze.mjs

@@ -0,0 +1 @@
+import{createHash as k}from"node:crypto";import{canonicalize as b}from"../jcs.mjs";import{deriveOperationReadPairs as x,keyCoverage as P,reduceCoverage as E}from"./cache-key.mjs";function K(t,n){const o=P(t,n);return o==="covered"?!0:o==="not-covered"?!1:"unresolved"}const M=E;function N(t,n){return x(new Map((t??[]).map(o=>[o.id,o])),new Map((n??[]).map(o=>[o.id,o])))}function z(t){const n={kind:t.kind,mutationId:t.mutationId??t.mutation?.id??null,family:t.family??null,readIds:[...t.readIds??[]].sort()};return"crc:"+k("sha256").update(b(n)).digest("hex")}function C(t){return(t.writeCandidates??0)===0||(t.writesResolved??0)===0?"unmeasured":t.writesUnresolved||t.readsUnresolved||t.keysUnresolved||t.operationsUnresolved||t.operationReadPairsUnresolved||t.invalidationsUnresolved||t.ownershipEdgesUnresolved||t.writersWithNoReaderSurface||t.coverageUndecidable?"partial":"measured"}function R(t,n){return n!=="unmeasured"?null:(t.writeCandidates??0)===0?"no-write-candidates":"no-writes-resolved"}const _=Object.freeze(["no-write-candidates","no-writes-resolved"]);function $(t,{waivers:n=[]}={}){const o={...t?.coverage?.counts??{}},v=C(o),i={status:v,reason:R(o,v),counts:o,unresolved:[...t?.coverage?.unresolved??[]]},l=new Map;for(const e of t?.surfaces??[])for(const s of e.readIds??[])l.has(s)||l.set(s,[]),l.get(s).push(e);const u=[],S=new Map((t?.cacheKeys??[]).map(e=>[e.id,e])),U=new Map((t?.cacheOperations??[]).map(e=>[e.id,{...e,material:{...e.material,key:S.get(e.material.keyId)?.material??null}}]));for(const e of t?.mutations??[]){if(!e.family||!(e.writes??(e.pattern?[{pattern:e.pattern}]:[])).length)continue;const f=(t.reads??[]).filter(r=>r.family&&r.family===e.family);if(!f.length)continue;const g=(e.operationIds??[]).map(r=>U.get(r)).filter(Boolean),O=N(g,f),m=[],c=[];for(const r of f){const a=O.filter(p=>p.readId===r.id).map(p=>p.effectCoverage),I=M(a);I!=="covered"&&(I==="unresolved"?c.push(r):m.push(r))}if(!m.length){c.length&&(o.coverageUndecidable=(o.coverageUndecidable??0)+1,i.unresolved.push({kind:"coherence.coverage-undecidable",mutationId:e.id,family:e.family??null,source:{file:e.file,line:e.line},readIds:c.map(r=>r.id).sort()}));continue}const h=new Set,w=new Set,y=new Set;for(const r of m)for(const a of l.get(r.id)??[])h.add(a.id),a.route&&w.add(a.route),a.route&&a.component&&y.add(`${a.route}:${a.component}`);const d={kind:g.length===0?"coherence.no-invalidation-candidate":"coherence.partial-invalidation-candidate",severity:"P3",confirmed:!1,mutationId:e.id,source:{file:e.file,line:e.line},family:e.family??null,readIds:m.map(r=>r.id).sort(),unresolvedReadIds:c.map(r=>r.id).sort(),surfaceIds:[...h].sort(),routes:[...w].sort(),components:[...y].sort(),coverage:c.length?"partial":i.status};(e.familySource==="declaration"||f.some(r=>r.familySource==="declaration"))&&(d.confidence="uncertain",d.basis="declaration-backed"),d.rootCauseId=z(d),n.includes(d.rootCauseId)&&(d.waived=!0),u.push(d)}return u.sort((e,s)=>e.rootCauseId.localeCompare(s.rootCauseId)),i.status=C(o),i.reason=R(o,i.status),i.unresolved.sort((e,s)=>JSON.stringify(e).localeCompare(JSON.stringify(s))),{coverage:i,candidates:u,waived:u.filter(e=>e.waived)}}export{_ as UNSUPPORTED_COVERAGE_REASONS,$ as analyzeCoherence,z as coherenceRootCauseId,N as operationReadPairs,K as patternCovers,M as reduceOperationCoverage};

package/lib/qa/coherence/cache-key.mjs

@@ -0,0 +1,6 @@
+import{createCoherenceIdentity as Q}from"./identity.mjs";import{canonicalize as E}from"../jcs.mjs";import{deriveOperationReadPairs as ce,effectCoverage as fe,keyCoverage as pe,reduceCoverage as me}from"./contracts.mjs";const $=/^[A-Za-z_$][\w$]*$/,U=new Set(["dynamic-key","unknown-helper","unsupported-client","unsupported-expression","unsafe-number","non-json-value","contract-conflict","dynamic-import","namespace-spread","export-star","computed-member","ambiguous-alias","unresolved-module","unsupported-syntax"]);function y(n,e=0,t=n.length){for(;e<t&&/\s/.test(n[e]);)e++;for(;t>e&&/\s/.test(n[t-1]);)t--;return{start:e,end:t,text:n.slice(e,t)}}function S(n,e=","){const t=[];let s=0,r=null,l=!1;const o=[],a={"(":")","[":"]","{":"}"};for(let d=0;d<n.length;d++){const c=n[d];if(r){!l&&c===r&&(r=null),l=!l&&c==="\\",c!=="\\"&&(l=!1);continue}if(c==="'"||c==='"'||c==="`"){r=c;continue}if(a[c])o.push(a[c]);else if(c===o.at(-1))o.pop();else if(c===e&&o.length===0){const k=y(n,s,d);k.text&&t.push(k),s=d+1}}const h=y(n,s);return h.text&&t.push(h),t}function T(n){let e=null,t=!1;const s=[],r={"(":")","[":"]","{":"}"};for(let l=0;l<n.length;l++){const o=n[l];if(e){!t&&o===e&&(e=null),t=!t&&o==="\\",o!=="\\"&&(t=!1);continue}if(o==="'"||o==='"'||o==="`"){e=o;continue}if(r[o])s.push(r[o]);else if(o===s.at(-1))s.pop();else if(o===":"&&s.length===0)return l}return-1}function q(n,e,t=0){let s=null,r=!1;const l=[],o={"(":")","[":"]","{":"}"};for(let a=t;a<=n.length-e.length;a++){const h=n[a];if(s){!r&&h===s&&(s=null),r=!r&&h==="\\",h!=="\\"&&(r=!1);continue}if(h==="'"||h==='"'||h==="`"){s=h;continue}if(o[h]){l.push(o[h]);continue}if(h===l.at(-1)){l.pop();continue}if(l.length===0&&n.startsWith(e,a))return a}return-1}function _(n){if(n[0]==="`"&&/\$\{/.test(n))return null;if(n[0]==='"')try{return JSON.parse(n)}catch{return null}const e=n[0];if(e!=="'"&&e!=="`"||n.at(-1)!==e)return null;let t="";const s={n:`
+`,r:"\r",t:"	",b:"\b",f:"\f",v:"\v",0:"\0"};for(let r=1;r<n.length-1;r++){const l=n[r];if(l!=="\\"){t+=l;continue}const o=n[++r];if(o==null)return null;if(o==="x"&&/^[0-9a-fA-F]{2}$/.test(n.slice(r+1,r+3))){t+=String.fromCodePoint(Number.parseInt(n.slice(r+1,r+3),16)),r+=2;continue}if(o==="u"&&/^[0-9a-fA-F]{4}$/.test(n.slice(r+1,r+5))){t+=String.fromCodePoint(Number.parseInt(n.slice(r+1,r+5),16)),r+=4;continue}t+=s[o]??o}return t}function N(n){const e=n.trim();if(/^(?:true|false|null)$/.test(e))return{ok:!0,value:e==="null"?null:e==="true"};if(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(e)){const t=Number(e);return Number.isFinite(t)&&Math.abs(t)<=Number.MAX_SAFE_INTEGER?{ok:!0,value:t}:{ok:!1,reason:"unsafe-number"}}if(/^['"`]/.test(e)){const t=_(e);return t===null?{ok:!1,reason:"dynamic-key"}:{ok:!0,value:t}}if(e.startsWith("[")&&e.endsWith("]")){const t=[];for(const s of S(e.slice(1,-1))){if(s.text.startsWith("..."))return{ok:!1,reason:"unsupported-expression"};const r=N(s.text);if(!r.ok)return r;t.push(r.value)}return{ok:!0,value:t}}if(e.startsWith("{")&&e.endsWith("}")){const t={};for(const s of S(e.slice(1,-1))){const r=T(s.text);if(r<0||s.text.startsWith("...")||s.text.startsWith("["))return{ok:!1,reason:"unsupported-expression"};const l=s.text.slice(0,r).trim(),o=$.test(l)?l:_(l);if(o===null)return{ok:!1,reason:"unsupported-expression"};const a=N(s.text.slice(r+1));if(!a.ok)return a;t[o]=a.value}return{ok:!0,value:t}}return{ok:!1,reason:"unsupported-expression"}}function O(n,e,t){if(!n.file)return null;const s=n.source??"",r=(n.start??0)+e,l=(n.start??0)+t,o=s.slice(0,r);return{file:n.file,start:r,end:l,line:o.split(`
+`).length,column:r-o.lastIndexOf(`
+`)}}function I(n,e,t,s,r,l,o={}){return U.has(t)||(t="unsupported-expression"),{kind:n,expression:e,ownerSymbol:s.ownerSymbol??null,targetSymbol:o.targetSymbol??null,origin:O(s,r,l)??{file:s.file??"<unknown>",start:0,end:Math.max(1,e.length),line:1,column:1},resolutionPath:o.resolutionPath??[],resolution:"unresolved",reason:t}}function V(n,e,t,s){const r=N(n);if(r.ok)return{kind:"literal",value:r.value,...O(e,t,s)?{origin:O(e,t,s)}:{}};const l=n.trim(),o=$.test(l)||/^`[\s\S]*\$\{/.test(l)?"parameter":/\(/.test(l)?"call":"unknown",a=r.reason==="unsafe-number"?r.reason:o==="unknown"?"unsupported-expression":"dynamic-key";return I(o,l,a,e,t,s)}function Y(n,e={}){const t=String(n??""),s=y(t);if(!s.text)return{segments:[I("unknown","","unsupported-expression",e,s.start,Math.max(s.end,s.start+1))]};if(s.text.startsWith("[")&&s.text.endsWith("]")){const l=s.start+1;return{segments:S(s.text.slice(1,-1)).map(o=>V(o.text,e,l+o.start,l+o.end))}}const r=$.test(s.text)?e.bindings?.get?.(s.text)??e.bindings?.[s.text]:null;return Array.isArray(r)&&r.length===1?Y(r[0].expression,e):{segments:[V(s.text,e,s.start,s.end)]}}function j(n){const e=(n?.segments??[]).map(t=>t.kind==="literal"?{kind:"literal",value:t.value}:Object.fromEntries(["kind","expression","ownerSymbol","targetSymbol","origin","resolutionPath","resolution","reason"].filter(s=>Object.hasOwn(t,s)).map(s=>[s,t[s]])));return Q("cache-key",{segments:e})}function Z(n){return(n?.segments??[]).every(e=>e.kind==="literal"||e.kind==="wildcard"||e.resolution==="resolved")?"resolved":"unresolved"}function ee(n,e){return(n?.declarations??[]).find(t=>t.key===e)??null}function te(n,e,t){const s=(n?.declarations??[]).filter(l=>l.file===e&&l.name===t);if(s.length===1)return s[0].key;const r=(n?.imports??[]).filter(l=>l.file===e&&l.local===t&&l.resolution==="resolved");return r.length===1?r[0].target:null}function L(n){const e=f=>{let i=f;for(;i<n.length;){if(/\s/.test(n[i])){i++;continue}if(n[i]==="/"&&n[i+1]==="/"){for(i+=2;i<n.length&&n[i]!==`
+`;)i++;continue}if(n[i]==="/"&&n[i+1]==="*"){const x=n.indexOf("*/",i+2);if(x<0)return-1;i=x+2;continue}break}return i},t=e(0);if(n.slice(t,t+6)!=="return"||/[\w$]/.test(n[t+6]??""))return null;let s=t+6;for(;n[s]===" "||n[s]==="	";)s++;if(s>=n.length||/[\r\n\u2028\u2029]/.test(n[s]))return null;const r={"(":")","[":"]","{":"}"},l=new Set(Object.values(r)),o=[];let a=null,h=!1,d=null,c=s,k=-1;for(let f=s;f<n.length;f++){const i=n[f],x=n[f+1];if(d==="line"){i===`
+`&&(d=null);continue}if(d==="block"){i==="*"&&x==="/"&&(d=null,f++);continue}if(a){c=f+1,h?h=!1:i==="\\"?h=!0:i===a&&(a=null);continue}if(i==="/"&&x==="/"){d="line",f++;continue}if(i==="/"&&x==="*"){d="block",f++;continue}if(i==="'"||i==='"'||i==="`"){a=i,c=f+1;continue}if(r[i])o.push(r[i]);else if(l.has(i)){if(o.pop()!==i)return null}else if(i===";"&&o.length===0){k=f;break}/\s/.test(i)||(c=f+1)}if(a||d==="block"||o.length||c<=s||k>=0&&e(k+1)!==n.length||k<0&&e(c)!==n.length)return null;const u=y(n,s,c);return u.text?{text:u.text,start:u.start}:null}function ne(n,e){const t=e.find(l=>l.file===n.file)?.source??"";if(n.kind==="const"&&t[n.bodyStart-1]!=="{"){const l=t.slice(n.bodyStart,n.end);let o=y(l);return o.text.endsWith(";")&&(o=y(l,o.start,o.end-1)),{source:t,expression:o.text,start:n.bodyStart+o.start}}const s=t.slice(n.bodyStart,Math.max(n.bodyStart,n.end-1)),r=L(s);return r?{source:t,expression:r.text,start:n.bodyStart+r.start}:{source:t,expression:"",start:n.bodyStart}}function re(n,e){const t=y(n);if(!t.text.startsWith("{")||!t.text.endsWith("}"))return null;for(const s of S(t.text.slice(1,-1))){const r=T(s.text);if(r<0)continue;const l=s.text.slice(0,r).trim();if(($.test(l)?l:_(l))===e){const a=y(s.text,r+1);return{text:a.text,start:t.start+1+s.start+a.start}}}return null}function se(n){const e=q(n,"=>");if(e>=0){let t=n.slice(0,e).trim().replace(/^async\s+/,"");t.startsWith("(")&&t.endsWith(")")&&(t=t.slice(1,-1));const s=S(t).map(l=>l.text.split(/[:=]/)[0].trim()).filter(l=>$.test(l));let r=y(n,e+2);if(r.text.startsWith("{")&&r.text.endsWith("}")){const l=L(r.text.slice(1,-1));if(!l)return{params:s,body:"",start:r.start+1};r={text:l.text,start:r.start+1+l.start}}return{params:s,body:r.text,start:r.start}}return null}function D(n,e,t){const s=y(String(n??"")),r={text:s.text,options:{...e,start:(e.start??0)+s.start}};return t.get(r.text)??r}function b(n,e,t="dynamic-key",s=null,r=[]){return{patterns:[{segments:[I(/\(/.test(n)?"call":"parameter",n,t,e,0,Math.max(1,n.length),{targetSymbol:s,resolutionPath:r})]}],provenance:s?[{method:"symbol-evaluation",targetSymbol:s,resolutionPath:r}]:[],resolution:"unresolved",reason:t}}function B(n){const e=new Map;for(const t of n)e.set(E(j(t).material),t);return[...e.entries()].sort(([t],[s])=>t.localeCompare(s)).map(([,t])=>t)}function W(n,e,t){const s=D(n,e,t.env),r=s.text.replace(/\s+as\s+const\s*$/,"");e=s.options;const l=q(r,"?");if(l>=0){const p=q(r,":",l+1);if(p>l){const m=W(r.slice(l+1,p),{...e,start:(e.start??0)+l+1},t),g=W(r.slice(p+1),{...e,start:(e.start??0)+p+1},t),v=B([...m.patterns,...g.patterns]);return{patterns:v,provenance:[...m.provenance,...g.provenance],resolution:v.every(K=>Z(K)==="resolved")?"resolved":"unresolved",reason:m.reason??g.reason??null}}}if(r.startsWith("[")&&r.endsWith("]")){let p=[{segments:[]}];for(const m of S(r.slice(1,-1))){const g=m.text.match(/^\.\.\.([\s\S]+)$/),v={...e,start:(e.start??0)+1+m.start+(g?3:0)},X=W(g?g[1]:m.text,v,t).patterns.map(A=>g||A.segments.length===1?A.segments:[I("unknown",m.text,"unsupported-expression",v,0,m.text.length)]);p=p.flatMap(A=>X.map(H=>({segments:[...A.segments,...H]})))}return p=B(p),{patterns:p,provenance:[],resolution:p.every(m=>Z(m)==="resolved")?"resolved":"unresolved",reason:null}}const o=N(r);if(o.ok)return{patterns:[{segments:[{kind:"literal",value:o.value,...O(e,0,r.length)?{origin:O(e,0,r.length)}:{}}]}],provenance:[],resolution:"resolved",reason:null};const a=r.match(/^([A-Za-z_$][\w$]*)(?:\.([A-Za-z_$][\w$]*))?\s*\(([\s\S]*)\)$/),h=r.match(/^([A-Za-z_$][\w$]*)$/);if(!a&&!h)return b(r,e,o.reason??"unsupported-expression");const d=(a??h)[1],c=a?.[2]??null,k=e.bindings?.get?.(d);if(!a&&k?.length===1&&!(e.units??[]).some(p=>p.file===e.file))return W(k[0].expression,e,t);const u=te(e.symbolIndex,e.file,d);if(!u)return b(r,e,"dynamic-key");if(t.seen.has(u)||t.depth>=24)return b(r,e,"dynamic-key",u,[...t.path,u]);const f=ee(e.symbolIndex,u);if(!f)return b(r,e,"dynamic-key",u,[...t.path,u]);const i=ne(f,e.units??[]),x=c?re(i.expression,c):{text:i.expression,start:0};if(x==null||x.text==="")return b(r,e,"unsupported-expression",u,[...t.path,u]);let R=x.text,F=i.start+x.start;const P=a?se(R):null,G=a?r.indexOf("(")+1:0,C=a?S(a[3]).map(p=>D(p.text,{...e,start:(e.start??0)+G+p.start},t.env)):[],z=new Map(t.env);if(P)P.params.forEach((p,m)=>{C[m]&&z.set(p,C[m])}),R=P.body,F+=P.start;else if(a&&!c&&(f.kind==="function"||f.kind==="const"&&f.supported))i.source.slice(f.paramsStart,f.paramsEnd).split(",").map(m=>m.split(/[:=]/)[0].trim()).forEach((m,g)=>{$.test(m)&&C[g]&&z.set(m,C[g])});else if(a)return b(r,e,"unsupported-expression",u,[...t.path,u]);const J={...e,file:f.file,source:i.source,start:F,ownerSymbol:u},w=W(R,J,{depth:t.depth+1,seen:new Set([...t.seen,u]),path:[...t.path,u],env:z});w.provenance.push({method:"symbol-evaluation",targetSymbol:u,resolutionPath:[...t.path,u]});const M=e.contracts?.factories?.[u];if(M!=null){if(!Array.isArray(M)||M.some(v=>!Array.isArray(v?.segments)))return b(r,e,"contract-conflict",u,[...t.path,u]);const p=B(M),m=p.map(v=>E(j(v).material)),g=w.patterns.map(v=>E(j(v).material));return w.resolution==="resolved"&&E(g)!==E(m)?{...b(r,e,"contract-conflict",u,[...t.path,u]),provenance:[...w.provenance,{method:"explicit-contract",targetSymbol:u,resolutionPath:[...t.path,u]}]}:{patterns:p,provenance:[...w.provenance,{method:"explicit-contract",targetSymbol:u,resolutionPath:[...t.path,u]}],resolution:"resolved",reason:null}}return w}function ie(n,e={}){return W(String(n??""),e,{depth:0,seen:new Set,path:[e.ownerSymbol].filter(Boolean),env:new Map})}export{j as cacheKeyIdentity,ce as deriveOperationReadPairs,fe as effectCoverage,ie as evaluateCacheKeyExpression,pe as keyCoverage,Z as keyResolution,Y as parseTypedKeyExpression,me as reduceCoverage};

package/lib/qa/coherence/causes.mjs

@@ -0,0 +1 @@
+import{parseObligationId as b}from"./plan-join.mjs";const y={P0:0,P1:1,P2:2,P3:3},j=(n,r)=>(y[n]??9)<=(y[r]??9)?n:r;function V(n){const r=[3,4].includes(n?.schemaVersion),u=new Map;for(const c of n?.plan?.journeys??[])for(const s of c.targets??[])for(const i of s.obligations??[]){const d=r?i.mutationId&&i.surfaceId?i:null:b(i.id);if(!d)continue;const f=`${d.mutationId}|${d.surfaceId}`;u.has(f)||u.set(f,[]),u.get(f).push({...i,...d,route:s.route??null,journeyId:c.journeyId,flow:c.flow??null})}return u}function v(n,r=[]){return r.length?{runtime:"disagreed",reason:null}:n.length?n.filter(s=>s.status==="disagreed").length?{runtime:"disagreed",reason:null}:n.filter(s=>s.status==="agreed").length?{runtime:"agreed",reason:null}:{runtime:"unmeasured",reason:[...new Set(n.map(i=>i.reason??i.status))].sort().join(", ")}:{runtime:"unmeasured",reason:"no-planned-obligation-for-this-cause"}}function A(n,r){return n.waived?"waived":r==="disagreed"?"confirmed":r==="agreed"?"not-reproduced":"unmeasured"}function L({candidates:n=[],observed:r=null,surfaces:u=[],mutations:c=[]}){const s=V(r),i=new Map(u.map(e=>[e.id,e])),d=new Map(c.map(e=>[e.id,e])),f=r?.status==="measured"||r?.status==="partial",w=new Map;for(const e of r?.findings??[])e.rootCauseId&&(w.has(e.rootCauseId)||w.set(e.rootCauseId,[]),w.get(e.rootCauseId).push(e));const m=n.map(e=>{const o=(e.surfaceIds??[]).flatMap(t=>s.get(`${e.mutationId}|${t}`)??[]),a=w.get(e.rootCauseId)??[],l=r?v(o,a):{runtime:"unmeasured",reason:"no-runtime-evidence"},M=new Set(a.map(t=>t.route).filter(Boolean)),R=new Set(a.map(t=>t.surfaceId).filter(Boolean)),P=(e.surfaceIds??[]).map(t=>{const g=i.get(t),C=o.filter(k=>k.surfaceId===t);let p;return C.length?p=v(C):[3,4].includes(r?.schemaVersion)&&R.has(t)?p={runtime:"disagreed",reason:"finding-on-this-surface"}:![3,4].includes(r?.schemaVersion)&&g?.route&&M.has(g.route)?p={runtime:"disagreed",reason:"finding-on-this-route"}:p={runtime:"unmeasured",reason:r?"no-planned-obligation-for-this-surface":"no-runtime-evidence"},{surfaceId:t,route:g?.route??C[0]?.route??null,component:g?.component??null,runtime:p.runtime,reason:p.reason}}).sort((t,g)=>t.surfaceId.localeCompare(g.surfaceId)),h=d.get(e.mutationId)??null;return{rootCauseId:e.rootCauseId,kind:e.kind,mutationId:e.mutationId,mutation:h?.hook?`${h.hook}()`:null,source:e.source??(h?{file:h.file,line:h.line}:null),family:e.family??null,label:A(e,l.runtime),runtime:l.runtime,reason:l.reason,affectedSurfaces:P,routes:[...new Set(P.map(t=>t.route).filter(Boolean))].sort(),obligations:{planned:o.length,agreed:o.filter(t=>t.status==="agreed").length,disagreed:o.filter(t=>t.status==="disagreed").length,unmeasured:o.filter(t=>t.status==="unmeasured"||t.status==="reached").length},severity:"P3"}}),B=new Set(m.map(e=>e.rootCauseId)),$=new Map;if(f)for(const e of r?.findings??[]){const o=e.rootCauseId;if(!o||B.has(o))continue;const a=$.get(o)??{rootCauseId:o,kind:"coherence.unpredicted-runtime-cause",label:"confirmed",runtime:"disagreed",reason:null,mutationId:null,mutation:null,source:null,family:null,affectedSurfaces:[],routes:new Set,obligations:{planned:0,agreed:0,disagreed:0,unmeasured:0},severity:e.severity??"P3",surfaceIds:new Set};a.severity=j(e.severity??"P3",a.severity);const l=e.surfaceId??e.route??null;l&&!a.surfaceIds.has(l)&&(a.surfaceIds.add(l),a.affectedSurfaces.push({surfaceId:e.surfaceId??null,route:e.route??null,component:null,runtime:"disagreed",reason:null})),e.route&&a.routes.add(e.route),$.set(o,a)}for(const e of $.values())e.routes=[...e.routes].sort(),e.affectedSurfaces.sort((o,a)=>String(o.surfaceId).localeCompare(String(a.surfaceId))),delete e.surfaceIds,m.push(e);const S={confirmed:0,unmeasured:1,"not-reproduced":2,waived:3};m.sort((e,o)=>(S[e.label]??9)-(S[o.label]??9)||(y[e.severity]??9)-(y[o.severity]??9)||String(e.rootCauseId).localeCompare(String(o.rootCauseId)));const I={causes:m.length,confirmed:0,notReproduced:0,unmeasured:0,waived:0};for(const e of m)e.label==="confirmed"?I.confirmed++:e.label==="not-reproduced"?I.notReproduced++:e.label==="waived"?I.waived++:I.unmeasured++;return{status:r&&f?"measured":"unmeasured",reason:r?null:"no-runtime-evidence",causes:m,counts:I}}const E=n=>n.component?`${n.route}:${n.component}`:n.route??n.surfaceId;function N(n,{max:r=10}={}){const u=[],c=n?.causes??[];if(!c.length)return u;u.push(`causes: ${n.counts.confirmed} confirmed / ${n.counts.notReproduced} not reproduced / ${n.counts.unmeasured} unmeasured of ${n.counts.causes}`);for(const s of c.slice(0,r)){const i=s.source?.file?` (${s.source.file}:${s.source.line})`:"";u.push(`  [${s.label}] ${s.mutation??s.mutationId??s.rootCauseId}${i} writes ${s.family??"(unknown)"}`);for(const d of s.affectedSurfaces)u.push(`      ${E(d)} -- ${d.runtime}${d.reason?` (${d.reason})`:""}`)}return c.length>r&&u.push(`  ... ${c.length-r} more`),u}export{L as linkCauses,N as renderCauses};

package/lib/qa/coherence/concurrency.mjs

@@ -0,0 +1 @@
+function d(t=[]){const u=new Set(t),a=new Map([...u].map(e=>[e,{released:!1,waiters:[]}])),s=[],n=(e,r,o)=>s.push({sequence:s.length,type:e,actor:r??null,barrier:o});function c(e){if(!a.has(e))throw new Error(`unknown barrier: ${e}`);return a.get(e)}return{async arrive(e,r){c(r),n("arrive",e,r)},release(e){const r=c(e);if(!r.released){r.released=!0,n("release",null,e);for(const o of r.waiters.splice(0))o()}},wait(e,r,o){const i=c(r);return n("wait",e,r),i.released?(n("continue",e,r),Promise.resolve()):new Promise((l,f)=>{const w=setTimeout(()=>f(new Error(`barrier timeout: ${r}`)),o);i.waiters.push(()=>{clearTimeout(w),n("continue",e,r),l()})})},events:()=>s.map(e=>({...e}))}}function m(t){return!Array.isArray(t?.actors)||t.actors.length<2||new Set(t.actors).size!==t.actors.length?{ok:!1,reason:"concurrency requires distinct actors"}:Array.isArray(t.schedule)?!t.accept||typeof t.accept.kind!="string"?{ok:!1,reason:"correctness case requires an accepted outcome"}:["conflict","merge","last-writer-wins","observe-only"].includes(t.accept.kind)?{ok:!0}:{ok:!1,reason:"unsupported accepted outcome"}:{ok:!1,reason:"concurrency requires a schedule"}}export{d as createBarrierController,m as validateConcurrencySpec};