opencode-agent-harness 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (169) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/LICENSE +21 -0
  3. package/README.md +590 -2
  4. package/bin/agent-harness.js +3059 -0
  5. package/contrib/global-plugins/README.md +49 -0
  6. package/contrib/global-plugins/harness-freshness.ts +355 -0
  7. package/package.json +48 -4
  8. package/templates/.agents/AGENTS.md +204 -0
  9. package/templates/.agents/features/INDEX.md +10 -0
  10. package/templates/.agents/handoffs/README.md +87 -0
  11. package/templates/.agents/memory/dev-loop.md +59 -0
  12. package/templates/.agents/memory/domain-map.md +29 -0
  13. package/templates/.agents/memory/environments.md +35 -0
  14. package/templates/.agents/memory/flow-map.md +23 -0
  15. package/templates/.agents/memory/history.md +7 -0
  16. package/templates/.agents/memory/locations.md +14 -0
  17. package/templates/.agents/memory/model-routing.md +261 -0
  18. package/templates/.agents/memory/orchestration.md +183 -0
  19. package/templates/.agents/memory/owned-files.md +19 -0
  20. package/templates/.agents/memory/product-principles.md +37 -0
  21. package/templates/.agents/memory/quality-parameters.md +37 -0
  22. package/templates/.agents/memory/stack-versions.md +35 -0
  23. package/templates/.agents/memory/test-design-parameters.md +36 -0
  24. package/templates/.agents/nightly.json +17 -0
  25. package/templates/.agents/qa-plans/README.md +70 -0
  26. package/templates/.agents/qa-runs/README.md +21 -0
  27. package/templates/.agents/reviews/README.md +47 -0
  28. package/templates/.agents/rules/00-operating.md +199 -0
  29. package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
  30. package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
  31. package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
  32. package/templates/.agents/skills/docs/SKILL.md +140 -0
  33. package/templates/.agents/skills/features/SKILL.md +187 -0
  34. package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
  35. package/templates/.agents/skills/handoff/SKILL.md +85 -0
  36. package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
  37. package/templates/.agents/skills/planner/SKILL.md +112 -0
  38. package/templates/.agents/skills/product-manager/SKILL.md +115 -0
  39. package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
  40. package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
  41. package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
  42. package/templates/.agents/skills/system-architect/SKILL.md +42 -0
  43. package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
  44. package/templates/.github/workflows/ci.yml +148 -0
  45. package/templates/.github/workflows/deploy-uat.yml +95 -0
  46. package/templates/.github/workflows/nightly.yml +83 -0
  47. package/templates/.github/workflows/uat-health.yml +41 -0
  48. package/templates/.husky/pre-push +23 -0
  49. package/templates/.ignore +28 -0
  50. package/templates/.opencode/agents/data-engineer.md +37 -0
  51. package/templates/.opencode/agents/devops-engineer.md +37 -0
  52. package/templates/.opencode/agents/diagnostics-expert.md +37 -0
  53. package/templates/.opencode/agents/docs.md +37 -0
  54. package/templates/.opencode/agents/features.md +21 -0
  55. package/templates/.opencode/agents/frontend-engineer.md +37 -0
  56. package/templates/.opencode/agents/handoff.md +21 -0
  57. package/templates/.opencode/agents/mobile-engineer.md +37 -0
  58. package/templates/.opencode/agents/planner.md +34 -0
  59. package/templates/.opencode/agents/product-manager.md +29 -0
  60. package/templates/.opencode/agents/qa-architect.md +27 -0
  61. package/templates/.opencode/agents/qa-runner.md +17 -0
  62. package/templates/.opencode/agents/security-engineer.md +37 -0
  63. package/templates/.opencode/agents/system-architect.md +37 -0
  64. package/templates/.opencode/agents/ui-designer.md +37 -0
  65. package/templates/.opencode/commands/board.md +15 -0
  66. package/templates/.opencode/commands/checkpoint.md +25 -0
  67. package/templates/.opencode/commands/feature.md +56 -0
  68. package/templates/.opencode/commands/finish.md +36 -0
  69. package/templates/.opencode/commands/next.md +49 -0
  70. package/templates/.opencode/commands/report.md +55 -0
  71. package/templates/.opencode/commands/resume.md +39 -0
  72. package/templates/.opencode/commands/switch-model.md +34 -0
  73. package/templates/.opencode/commands/tidy.md +49 -0
  74. package/templates/.opencode/plugins/backlog-notify.ts +57 -0
  75. package/templates/.opencode/plugins/backlog.ts +272 -0
  76. package/templates/.opencode/plugins/checkpoint.ts +160 -0
  77. package/templates/.opencode/plugins/context-guard.ts +1164 -0
  78. package/templates/.opencode/plugins/diff.ts +85 -0
  79. package/templates/.opencode/plugins/gates.ts +71 -0
  80. package/templates/.opencode/plugins/job-notify.ts +241 -0
  81. package/templates/.opencode/plugins/orient.ts +67 -0
  82. package/templates/.opencode/plugins/session.ts +89 -0
  83. package/templates/.opencode/plugins/wait.ts +101 -0
  84. package/templates/.opencode/plugins/where.ts +70 -0
  85. package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
  86. package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
  87. package/templates/.vercelignore +16 -0
  88. package/templates/AGENTS.md +27 -0
  89. package/templates/BACKLOG.md +95 -0
  90. package/templates/docs/ci-cd-pipeline.md +81 -0
  91. package/templates/docs/gates.md +128 -0
  92. package/templates/docs/mcp-integrations.md +97 -0
  93. package/templates/docs/mobile-testing.md +555 -0
  94. package/templates/docs/nightly-testing.md +106 -0
  95. package/templates/docs/wsl-optimizations.md +290 -0
  96. package/templates/opencode.json +188 -0
  97. package/templates/scripts/agent-report.js +541 -0
  98. package/templates/scripts/agent-search.sh +117 -0
  99. package/templates/scripts/backlog.js +1864 -0
  100. package/templates/scripts/board-service.sh +207 -0
  101. package/templates/scripts/checkpoint.js +290 -0
  102. package/templates/scripts/finalize.js +277 -0
  103. package/templates/scripts/nightly.js +913 -0
  104. package/templates/scripts/orient.js +514 -0
  105. package/templates/scripts/qa/board-client.js +260 -0
  106. package/templates/scripts/qa/board-lib.js +96 -0
  107. package/templates/scripts/qa/board-sync.js +469 -0
  108. package/templates/scripts/qa/capacity-lib.js +916 -0
  109. package/templates/scripts/qa/check-backlog.js +427 -0
  110. package/templates/scripts/qa/check-capacity.js +85 -0
  111. package/templates/scripts/qa/check-ci-policy.js +164 -0
  112. package/templates/scripts/qa/check-concurrency.js +344 -0
  113. package/templates/scripts/qa/check-dispatch-config.js +296 -0
  114. package/templates/scripts/qa/check-docs.js +284 -0
  115. package/templates/scripts/qa/check-integrate.js +98 -0
  116. package/templates/scripts/qa/check-linger.js +160 -0
  117. package/templates/scripts/qa/check-prefix-stability.js +183 -0
  118. package/templates/scripts/qa/check-product.js +177 -0
  119. package/templates/scripts/qa/check-qa-plan.js +378 -0
  120. package/templates/scripts/qa/check-qa-scripts.js +85 -0
  121. package/templates/scripts/qa/check-quality.js +249 -0
  122. package/templates/scripts/qa/check-test-wiring.js +253 -0
  123. package/templates/scripts/qa/ci-triage.js +346 -0
  124. package/templates/scripts/qa/ci-usage-lib.js +185 -0
  125. package/templates/scripts/qa/ci-wait-lib.js +294 -0
  126. package/templates/scripts/qa/command-classifier.js +552 -0
  127. package/templates/scripts/qa/context-guard-core.js +1618 -0
  128. package/templates/scripts/qa/diff.js +174 -0
  129. package/templates/scripts/qa/feature-scaffold.js +224 -0
  130. package/templates/scripts/qa/fixtures/backlog.md +104 -0
  131. package/templates/scripts/qa/governance.js +174 -0
  132. package/templates/scripts/qa/hash-file.js +32 -0
  133. package/templates/scripts/qa/lease-lib.js +263 -0
  134. package/templates/scripts/qa/merge-backlog.js +324 -0
  135. package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
  136. package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
  137. package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
  138. package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
  139. package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
  140. package/templates/scripts/qa/mobile-e2e/check-flows.js +453 -0
  141. package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
  142. package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
  143. package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
  144. package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
  145. package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
  146. package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
  147. package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
  148. package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
  149. package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
  150. package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
  151. package/templates/scripts/qa/models.allowlist.txt +32 -0
  152. package/templates/scripts/qa/provider-stats.js +878 -0
  153. package/templates/scripts/qa/run-clean.js +83 -0
  154. package/templates/scripts/qa/run-gates.js +212 -0
  155. package/templates/scripts/qa/run-loop.js +220 -0
  156. package/templates/scripts/qa/session-recon.js +512 -0
  157. package/templates/scripts/qa/store-lib.js +324 -0
  158. package/templates/scripts/qa/tool-lib.js +134 -0
  159. package/templates/scripts/qa/where.js +214 -0
  160. package/templates/scripts/qa/wslconfig-merge.js +157 -0
  161. package/templates/scripts/serve.js +1328 -0
  162. package/templates/scripts/setup-nightly.sh +185 -0
  163. package/templates/scripts/setup-tmpfs.sh +374 -0
  164. package/templates/scripts/ship.js +586 -0
  165. package/templates/scripts/switch-reasoning-model.ps1 +101 -0
  166. package/templates/scripts/switch-reasoning-model.sh +104 -0
  167. package/templates/scripts/wait-for.js +342 -0
  168. package/templates/scripts/wsl-gpu.sh +180 -0
  169. package/templates/scripts/wsl-tune.sh +261 -0
@@ -0,0 +1,249 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ /*
4
+ * test:quality — mechanical code-quality gate on NEW/CHANGED code (harness-shipped).
5
+ *
6
+ * The gate side of the canonical rubric in `.agents/memory/quality-parameters.md`
7
+ * (P1 dead-code-free, P3 right-sized units, P4 one home per fact). It runs on the
8
+ * code a change ADDS or GROWS, so debt cannot be *introduced* — legacy debt is
9
+ * cleared by review rows, not blocked here:
10
+ *
11
+ * 1. P3 right-sized units — a changed file that is NEW or GREW past
12
+ * `--max-lines` (default 1000) is flagged. Touching an already-oversized
13
+ * legacy file without growing it does NOT flag (that is legacy debt, tracked
14
+ * as a review row, not a blocker on an unrelated one-line fix).
15
+ * 2. P1 dead-code-free — an exported identifier declared in a changed file that
16
+ * has ZERO other references in the whole repo (its own declaration is the
17
+ * only occurrence) is dead. Word-boundary scan, so a reference in any other
18
+ * file clears it; files that re-export via `export *` are skipped (their
19
+ * names are not provable by this scanner).
20
+ *
21
+ * Scope resolution (in priority order):
22
+ * - explicit `--paths a.ts,b.ts` — scan exactly these files;
23
+ * - else `git diff --name-only <base>...HEAD` — the change's files, where base
24
+ * defaults to `origin/main`, falling back to `main`, then `HEAD~1`;
25
+ * - else nothing changed -> green (nothing new to gate).
26
+ *
27
+ * node scripts/qa/check-quality.js [--base <ref>] [--max-lines N] [--paths a,b] [--strict]
28
+ *
29
+ * Exit 1 on any finding. `--strict` additionally surfaces warnings as failures
30
+ * (use it in CI on the diff; leave it off for the human loop).
31
+ */
32
+ const fs = require("fs");
33
+ const path = require("path");
34
+ const { execFileSync } = require("child_process");
35
+
36
+ const root = path.resolve(__dirname, "..", "..");
37
+
38
+ const CODE_EXT = /\.(?:[cm]?[jt]sx?|js)$/;
39
+ const IGNORE_DIRS = new Set(["node_modules", ".next", ".git", ".worktrees", ".harness-backup", "dist", "build", ".turbo", ".expo"]);
40
+
41
+ /* Convention-loaded entrypoints: their exports are consumed by a framework
42
+ * runtime (opencode discovers `.opencode/plugins|tools` by convention; Next.js
43
+ * discovers `route|page|layout|...` and `middleware|instrumentation`), so the
44
+ * zero-consumer scan cannot see an importer and would flag them as dead. Skip
45
+ * P1 for these; P3 (size) still applies. */
46
+ const CONVENTION_ENTRY =
47
+ /(?:^|\/)(?:\.opencode\/(?:plugins|tools)\/|app\/(?:.*\/)?(?:route|page|layout|loading|error|not-found|template|default)\.(?:[cm]?[jt]sx?)$|middleware\.[cm]?[jt]sx?$|instrumentation\.[cm]?[jt]sx?$)/;
48
+ function isConventionEntry(rel) {
49
+ return CONVENTION_ENTRY.test(String(rel).replace(/\\/g, "/"));
50
+ }
51
+
52
+ const args = process.argv.slice(2);
53
+ function flag(name, def) {
54
+ const i = args.indexOf("--" + name);
55
+ return i === -1 ? def : args[i + 1];
56
+ }
57
+ const maxLines = parseInt(flag("max-lines", "1000"), 10) || 1000;
58
+ const base = flag("base", "");
59
+ const pathsArg = flag("paths", "");
60
+ const strict = args.includes("--strict");
61
+
62
+ const findings = [];
63
+ const warnings = [];
64
+ const fail = (m) => {
65
+ findings.push(m);
66
+ console.log(" \u2717 " + m);
67
+ };
68
+ const warn = (m) => {
69
+ warnings.push(m);
70
+ console.log(" \u26a0 " + m);
71
+ };
72
+ const pass = (m) => console.log(" \u2713 " + m);
73
+
74
+ console.log("quality gate \u2014 mechanical quality on NEW/CHANGED code (rubric: .agents/memory/quality-parameters.md)");
75
+
76
+ function git(a) {
77
+ try {
78
+ return execFileSync("git", a, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
79
+ } catch (_) {
80
+ return null;
81
+ }
82
+ }
83
+
84
+ function inGitRepo() {
85
+ const r = git(["rev-parse", "--is-inside-work-tree"]);
86
+ return !!r && r.trim() === "true";
87
+ }
88
+
89
+ /* Files to scan: explicit --paths, else the change's files vs a base ref. */
90
+ function changedFiles() {
91
+ const candidates = [];
92
+ if (pathsArg) {
93
+ for (const p of pathsArg.split(",")) {
94
+ const f = p.trim();
95
+ if (f) candidates.push(f);
96
+ }
97
+ return candidates;
98
+ }
99
+ if (!inGitRepo()) return [];
100
+ let ref = base || "origin/main";
101
+ const has = (r) => git(["rev-parse", "--verify", "-q", r]) !== null;
102
+ if (!has(ref)) {
103
+ if (has("main")) ref = "main";
104
+ else if (has("HEAD~1")) ref = "HEAD~1";
105
+ else return [];
106
+ }
107
+ const changed = git(["diff", "--name-only", "--diff-filter=ACMR", ref, "--"]);
108
+ if (changed == null) return [];
109
+ const tracked = changed.split(/\r?\n/).filter(Boolean);
110
+ // Untracked new files are not in `git diff` — add them so a brand-new file with
111
+ // a dead export or an oversized body is gated before its first commit.
112
+ const porcelain = git(["status", "--porcelain"]) || "";
113
+ const untracked = porcelain
114
+ .split(/\r?\n/)
115
+ .filter((l) => l.startsWith("??"))
116
+ .map((l) => l.slice(3).trim())
117
+ .filter(Boolean);
118
+ return [...new Set([...tracked, ...untracked])];
119
+ }
120
+
121
+ function walk(dir, out) {
122
+ if (!fs.existsSync(dir)) return;
123
+ for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
124
+ if (IGNORE_DIRS.has(e.name) || e.name.startsWith(".")) continue;
125
+ const p = path.join(dir, e.name);
126
+ if (e.isDirectory()) walk(p, out);
127
+ else if (CODE_EXT.test(e.name)) out.push(p);
128
+ }
129
+ }
130
+
131
+ function fileList() {
132
+ const out = [];
133
+ walk(root, out);
134
+ return out.map((p) => path.relative(root, p).split(path.sep).join("/"));
135
+ }
136
+
137
+ function baseLineCount(rel) {
138
+ if (!inGitRepo()) return 0;
139
+ const blob = git(["show", `${base || "HEAD~1"}:${rel}`]);
140
+ return blob == null ? 0 : blob.split(/\r?\n/).length;
141
+ }
142
+
143
+ function countLines(rel) {
144
+ const p = path.join(root, rel);
145
+ if (!fs.existsSync(p)) return 0;
146
+ return fs.readFileSync(p, "utf8").split(/\r?\n/).length;
147
+ }
148
+
149
+ /* Exported top-level identifiers in a JS/TS file (function/const/let/var/class + explicit `export {a, b}`). */
150
+ function exportedNames(src) {
151
+ const names = new Set();
152
+ const reDecl =
153
+ /\bexport\s+(?:async\s+)?(?:function\s+|const\s+|let\s+|var\s+|class\s+|interface\s+|type\s+)([A-Za-z_$][\w$]*)/g;
154
+ const reList = /\bexport\s*\{([^}]+)\}/g;
155
+ let m;
156
+ while ((m = reDecl.exec(src))) names.add(m[1]);
157
+ while ((m = reList.exec(src))) {
158
+ for (const part of m[1].split(",")) {
159
+ const n = part.trim().split(/\s+as\s+/)[0].trim();
160
+ if (/^[A-Za-z_$][\w$]*$/.test(n)) names.add(n);
161
+ }
162
+ }
163
+ return [...names];
164
+ }
165
+
166
+ /* Count word-boundary occurrences of `name` across all repo code files. */
167
+ function repoOccurrences(name, rels) {
168
+ const re = new RegExp("\\b" + name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "\\b", "g");
169
+ let total = 0;
170
+ for (const rel of rels) {
171
+ const p = path.join(root, rel);
172
+ if (!fs.existsSync(p)) continue;
173
+ const src = fs.readFileSync(p, "utf8");
174
+ const hits = src.match(re);
175
+ if (hits) total += hits.length;
176
+ }
177
+ return total;
178
+ }
179
+
180
+ function lineCount(rel) {
181
+ return countLines(rel);
182
+ }
183
+
184
+ // ---- scope ------------------------------------------------------------------
185
+ const changed = changedFiles();
186
+ const rels = fileList();
187
+ const codeChanged = changed.filter((f) => CODE_EXT.test(f));
188
+ if (pathsArg && codeChanged.length === 0) {
189
+ fail(`--paths given but none matched code files (${pathsArg})`);
190
+ }
191
+
192
+ if (codeChanged.length === 0) {
193
+ console.log(" \u2713 no NEW/GROWN code files in scope \u2014 nothing to gate");
194
+ } else {
195
+ pass(`${codeChanged.length} changed code file(s) in scope`);
196
+ }
197
+
198
+ // ---- P3: right-sized units --------------------------------------------------
199
+ for (const rel of codeChanged) {
200
+ const n = lineCount(rel);
201
+ const baseN = baseLineCount(rel);
202
+ const isNew = baseN === 0;
203
+ const grew = n > baseN && n > maxLines && baseN <= maxLines;
204
+ if (n > maxLines && (isNew || grew)) {
205
+ fail(
206
+ `${rel} is ${n} lines (limit ${maxLines}) \u2014 right-size it: extract components/modules (quality parameter P3).`
207
+ );
208
+ } else if (n > maxLines) {
209
+ warn(
210
+ `${rel} is ${n} lines (already oversized; not grown by this change) \u2014 legacy debt, file a review row, don't grow it further.`
211
+ );
212
+ }
213
+ }
214
+
215
+ // ---- P1: zero-consumer exports ----------------------------------------------
216
+ for (const rel of codeChanged) {
217
+ const p = path.join(root, rel);
218
+ if (!fs.existsSync(p)) continue;
219
+ if (isConventionEntry(rel)) {
220
+ warnings.push(`${rel}: convention-loaded entrypoint — zero-consumer scan skipped`);
221
+ console.log(" \u26a0 " + warnings[warnings.length - 1]);
222
+ continue;
223
+ }
224
+ const src = fs.readFileSync(p, "utf8");
225
+ if (/\bexport\s*\*\s*from\b/.test(src)) {
226
+ warnings.push(`${rel}: re-exports via \`export *\` \u2014 zero-consumer scan skipped for it`);
227
+ console.log(" \u26a0 " + warnings[warnings.length - 1]);
228
+ continue;
229
+ }
230
+ for (const name of exportedNames(src)) {
231
+ const occ = repoOccurrences(name, rels);
232
+ if (occ <= 1) {
233
+ const declLine =
234
+ src
235
+ .split(/\r?\n/)
236
+ .findIndex((l) => new RegExp("\\b" + name + "\\b").test(l) && /export/.test(l)) + 1;
237
+ fail(`${rel}: export \`${name}\` has no consumer anywhere (${occ} occurrence(s) \u2014 its own declaration, line ${declLine}). Dead code (quality parameter P1).`);
238
+ }
239
+ }
240
+ }
241
+
242
+ // ---- result ---------------------------------------------------------------
243
+ console.log(
244
+ "\nRESULT: " +
245
+ (findings.length
246
+ ? `${findings.length} FAILURE(S) \u2014 new/changed code must not introduce dead exports or oversized files`
247
+ : "green \u2014 changed code is free of dead exports and oversized files")
248
+ );
249
+ process.exit(findings.length ? 1 : 0);
@@ -0,0 +1,253 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ /*
4
+ * test:wiring — orphan-test detector (harness-shipped).
5
+ *
6
+ * The mechanical side of test-design parameter T7: "a test that is authored but
7
+ * wired into no tier is not coverage". A `*.test.*` / `*.spec.*` file that no
8
+ * package.json script executes is neither regression protection nor a failure
9
+ * signal — it is dead weight that looks like coverage on a plan. F-105/F-117
10
+ * shipped exactly this (authored-then-unreferenced suites a later change had to
11
+ * wire by hand).
12
+ *
13
+ * Wiring rules:
14
+ * 1. Explicit reference — some script names the file directly, by directory
15
+ * prefix, or via a glob. This is the strong signal.
16
+ * 2. Managed directory — once ANY test file in a directory is explicitly
17
+ * referenced, every other test file in that directory must be too (or be
18
+ * waived). This is the F-105/F-117 failure mode: a test authored next to
19
+ * the wired ones and forgotten.
20
+ * 3. Default-discovery notice — a bare runner script (`vitest run`, bare
21
+ * `node --test`, `playwright test`, ...) DOES execute its default matches,
22
+ * but per-file wiring cannot be proven. Files in UNMANAGED directories are
23
+ * reported as notices and pass; `--strict` upgrades notices to failures for
24
+ * projects that want provable wiring.
25
+ *
26
+ * A deliberate orphan carries an explicit, auditable waiver comment in the file:
27
+ * // test-wiring-waived: reason — <why this file intentionally runs nowhere>
28
+ *
29
+ * node scripts/qa/check-test-wiring.js # orphan tests fail
30
+ * node scripts/qa/check-test-wiring.js --strict # discovery notices fail too
31
+ *
32
+ * Exit 0 when every test file is wired, discovery-covered, or waived; exit 1 on
33
+ * any orphan (or any notice under --strict).
34
+ */
35
+ const fs = require("fs");
36
+ const path = require("path");
37
+
38
+ const root = path.resolve(__dirname, "..", "..");
39
+ const strict = process.argv.includes("--strict");
40
+
41
+ const IGNORE_DIRS = new Set([
42
+ "node_modules",
43
+ ".git",
44
+ ".next",
45
+ ".worktrees",
46
+ ".harness-backup",
47
+ ".serve",
48
+ "dist",
49
+ "build",
50
+ "out",
51
+ "coverage",
52
+ ".turbo",
53
+ ".expo",
54
+ ".vercel",
55
+ ]);
56
+
57
+ const TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$/i;
58
+ const RUNNERS = new Set(["vitest", "jest", "mocha", "ava", "tap", "playwright"]);
59
+ const RUNNER_NOISE = new Set([
60
+ "npx",
61
+ "npx.cmd",
62
+ "pnpm",
63
+ "pnpm.cmd",
64
+ "yarn",
65
+ "npm",
66
+ "run",
67
+ "dlx",
68
+ "exec",
69
+ "node",
70
+ "node.exe",
71
+ "tsx",
72
+ "tsx.cmd",
73
+ "ts-node",
74
+ ]);
75
+
76
+ const pkgPath = path.join(root, "package.json");
77
+ if (!fs.existsSync(pkgPath)) {
78
+ console.error("FATAL: no package.json in project root");
79
+ process.exit(2);
80
+ }
81
+ let scripts = {};
82
+ try {
83
+ scripts = JSON.parse(fs.readFileSync(pkgPath, "utf8")).scripts || {};
84
+ } catch (e) {
85
+ console.error(`FATAL: unparseable package.json: ${e.message}`);
86
+ process.exit(2);
87
+ }
88
+
89
+ function norm(p) {
90
+ return p.replace(/\\/g, "/");
91
+ }
92
+
93
+ /* Strip shell decoration (quotes, chain operators, list commas) from a token. */
94
+ function cleanToken(t) {
95
+ return t
96
+ .replace(/^["']|["']$/g, "")
97
+ .replace(/^(?:&&|\|\||[;&|<>])+/, "")
98
+ .replace(/(?:&&|\|\||[;&|<>])+$/, "")
99
+ .replace(/^,|,$/g, "");
100
+ }
101
+
102
+ function tokens(cmd) {
103
+ return String(cmd)
104
+ .split(/\s+/)
105
+ .map(cleanToken)
106
+ .filter(Boolean);
107
+ }
108
+
109
+ function hasGlobMagic(t) {
110
+ return /[*?]/.test(t);
111
+ }
112
+
113
+ function globToRegExp(glob) {
114
+ const g = norm(glob);
115
+ let re = "";
116
+ for (let i = 0; i < g.length; i++) {
117
+ const c = g[i];
118
+ if (c === "*") {
119
+ if (g[i + 1] === "*") {
120
+ re += ".*";
121
+ i++;
122
+ if (g[i + 1] === "/") i++;
123
+ } else {
124
+ re += "[^/]*";
125
+ }
126
+ } else if (c === "?") {
127
+ re += "[^/]";
128
+ } else {
129
+ re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
130
+ }
131
+ }
132
+ return new RegExp("^" + re + "$");
133
+ }
134
+
135
+ function tokenMatches(token, rel) {
136
+ const t = norm(token).replace(/^\.\//, "").replace(/\/+$/, "");
137
+ if (!t) return false;
138
+ if (hasGlobMagic(t)) return globToRegExp(t).test(rel);
139
+ return rel === t || rel.startsWith(t + "/");
140
+ }
141
+
142
+ /* A bare runner command has no path/glob argument, so it executes its default
143
+ * discovery matches (e.g. `vitest run`, bare `node --test`). Install/init
144
+ * subcommands are not test runs. */
145
+ function isDiscoveryCommand(cmd) {
146
+ const ts = tokens(cmd);
147
+ const runnerIdx = ts.findIndex((t) => RUNNERS.has(t));
148
+ const usesNodeTest = ts.includes("--test") || ts.includes("--test-only");
149
+ if (runnerIdx !== -1 && ["install", "init", "--version", "-v"].includes(ts[runnerIdx + 1] || "")) {
150
+ return false;
151
+ }
152
+ if (runnerIdx === -1 && !usesNodeTest) return false;
153
+ const pathArg = ts.some(
154
+ (t) =>
155
+ !t.startsWith("-") &&
156
+ !RUNNERS.has(t) &&
157
+ !RUNNER_NOISE.has(t) &&
158
+ /[\\/]|^\.[\\/]|[*?]/.test(t)
159
+ );
160
+ return !pathArg;
161
+ }
162
+
163
+ function walk(dir, out) {
164
+ if (!fs.existsSync(dir)) return;
165
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
166
+ if (IGNORE_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
167
+ const abs = path.join(dir, entry.name);
168
+ if (entry.isDirectory()) walk(abs, out);
169
+ else if (TEST_FILE.test(entry.name)) out.push(abs);
170
+ }
171
+ }
172
+
173
+ function dirOf(rel) {
174
+ const i = rel.lastIndexOf("/");
175
+ return i === -1 ? "." : rel.slice(0, i);
176
+ }
177
+
178
+ const commands = Object.values(scripts);
179
+ const discoveryCommands = commands.filter(isDiscoveryCommand);
180
+ const testFiles = [];
181
+ walk(root, testFiles);
182
+
183
+ console.log("test-wiring gate \u2014 every *.test.* file is executed by a package script (T7)");
184
+
185
+ const wired = [];
186
+ const waived = [];
187
+ const notices = [];
188
+ const orphans = [];
189
+ const managedDirs = new Set();
190
+
191
+ for (const abs of testFiles.sort()) {
192
+ const rel = norm(path.relative(root, abs));
193
+ const src = fs.readFileSync(abs, "utf8");
194
+ const waiver = src.match(/test-wiring-waived:\s*(\S[^\r\n]*)/i);
195
+ if (waiver) {
196
+ waived.push({ rel, reason: waiver[1].trim() });
197
+ continue;
198
+ }
199
+ let matched = null;
200
+ for (const cmd of commands) {
201
+ const tok = tokens(cmd).find((t) => tokenMatches(t, rel));
202
+ if (tok) {
203
+ matched = { rel, via: tok };
204
+ break;
205
+ }
206
+ }
207
+ if (matched) {
208
+ wired.push(matched);
209
+ managedDirs.add(dirOf(rel));
210
+ }
211
+ }
212
+
213
+ for (const abs of testFiles.sort()) {
214
+ const rel = norm(path.relative(root, abs));
215
+ if (wired.some((w) => w.rel === rel) || waived.some((w) => w.rel === rel)) continue;
216
+ if (!managedDirs.has(dirOf(rel)) && discoveryCommands.length) {
217
+ notices.push({ rel, cmd: discoveryCommands[0] });
218
+ continue;
219
+ }
220
+ orphans.push(rel);
221
+ }
222
+
223
+ function short(cmd) {
224
+ const s = String(cmd);
225
+ return s.length > 90 ? s.slice(0, 87) + "..." : s;
226
+ }
227
+
228
+ for (const w of wired) console.log(` \u2713 ${w.rel} (wired via \`${w.via}\`)`);
229
+ for (const w of waived) console.log(` \u2713 ${w.rel} (waived: ${w.reason})`);
230
+ for (const n of notices) {
231
+ console.log(` \u26a0 ${n.rel} not referenced by any script \u2014 covered by default-discovery \`${short(n.cmd)}\` (not provable per-file)`);
232
+ }
233
+
234
+ const failures = [...orphans];
235
+ for (const n of notices) {
236
+ if (strict) failures.push(n.rel);
237
+ }
238
+
239
+ for (const rel of orphans) {
240
+ console.log(
241
+ ` \u2717 ${rel} is in an explicitly-managed test directory but no package.json script executes it`
242
+ );
243
+ }
244
+
245
+ if (!testFiles.length) console.log(" \u2713 no test files found \u2014 nothing to wire");
246
+
247
+ console.log(
248
+ "\nRESULT: " +
249
+ (failures.length
250
+ ? `${failures.length} ORPHAN test file(s) \u2014 wire each into its cheapest tier command (or delete it / add \`// test-wiring-waived: reason\`). A test in no script is not coverage (T7).`
251
+ : "green \u2014 every test file is wired or explicitly waived")
252
+ );
253
+ process.exit(failures.length ? 1 : 0);