opencode-agent-harness 0.0.0-stage → 0.3.14
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.
- package/CHANGELOG.md +217 -0
- package/LICENSE +21 -0
- package/README.md +636 -2
- package/bin/agent-harness.js +3182 -0
- package/contrib/global-plugins/README.md +49 -0
- package/contrib/global-plugins/harness-freshness.ts +355 -0
- package/package.json +86 -4
- package/templates/.agents/AGENTS.md +148 -0
- package/templates/.agents/features/INDEX.md +10 -0
- package/templates/.agents/handoffs/README.md +87 -0
- package/templates/.agents/memory/dev-loop.md +59 -0
- package/templates/.agents/memory/domain-map.md +29 -0
- package/templates/.agents/memory/environments.md +35 -0
- package/templates/.agents/memory/flow-map.md +23 -0
- package/templates/.agents/memory/history.md +7 -0
- package/templates/.agents/memory/locations.md +14 -0
- package/templates/.agents/memory/model-routing.md +261 -0
- package/templates/.agents/memory/orchestration.md +183 -0
- package/templates/.agents/memory/owned-files.md +19 -0
- package/templates/.agents/memory/product-principles.md +37 -0
- package/templates/.agents/memory/quality-parameters.md +37 -0
- package/templates/.agents/memory/stack-versions.md +35 -0
- package/templates/.agents/memory/test-design-parameters.md +36 -0
- package/templates/.agents/nightly.json +17 -0
- package/templates/.agents/qa-plans/README.md +70 -0
- package/templates/.agents/qa-runs/README.md +21 -0
- package/templates/.agents/reviews/README.md +47 -0
- package/templates/.agents/rules/00-operating.md +199 -0
- package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
- package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
- package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
- package/templates/.agents/skills/docs/SKILL.md +140 -0
- package/templates/.agents/skills/features/SKILL.md +187 -0
- package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
- package/templates/.agents/skills/handoff/SKILL.md +85 -0
- package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
- package/templates/.agents/skills/planner/SKILL.md +112 -0
- package/templates/.agents/skills/product-manager/SKILL.md +115 -0
- package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
- package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
- package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
- package/templates/.agents/skills/system-architect/SKILL.md +42 -0
- package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
- package/templates/.github/workflows/ci.yml +148 -0
- package/templates/.github/workflows/deploy-uat.yml +95 -0
- package/templates/.github/workflows/nightly.yml +83 -0
- package/templates/.github/workflows/uat-health.yml +41 -0
- package/templates/.husky/pre-push +23 -0
- package/templates/.ignore +28 -0
- package/templates/.opencode/agents/data-engineer.md +37 -0
- package/templates/.opencode/agents/devops-engineer.md +37 -0
- package/templates/.opencode/agents/diagnostics-expert.md +37 -0
- package/templates/.opencode/agents/docs.md +37 -0
- package/templates/.opencode/agents/features.md +21 -0
- package/templates/.opencode/agents/frontend-engineer.md +37 -0
- package/templates/.opencode/agents/handoff.md +21 -0
- package/templates/.opencode/agents/mobile-engineer.md +37 -0
- package/templates/.opencode/agents/planner.md +34 -0
- package/templates/.opencode/agents/product-manager.md +29 -0
- package/templates/.opencode/agents/qa-architect.md +27 -0
- package/templates/.opencode/agents/qa-runner.md +17 -0
- package/templates/.opencode/agents/security-engineer.md +37 -0
- package/templates/.opencode/agents/system-architect.md +37 -0
- package/templates/.opencode/agents/ui-designer.md +37 -0
- package/templates/.opencode/commands/board.md +15 -0
- package/templates/.opencode/commands/checkpoint.md +25 -0
- package/templates/.opencode/commands/feature.md +56 -0
- package/templates/.opencode/commands/finish.md +36 -0
- package/templates/.opencode/commands/next.md +49 -0
- package/templates/.opencode/commands/report.md +55 -0
- package/templates/.opencode/commands/resume.md +39 -0
- package/templates/.opencode/commands/switch-model.md +34 -0
- package/templates/.opencode/commands/tidy.md +49 -0
- package/templates/.opencode/plugins/backlog-notify.ts +57 -0
- package/templates/.opencode/plugins/backlog.ts +272 -0
- package/templates/.opencode/plugins/checkpoint.ts +160 -0
- package/templates/.opencode/plugins/context-guard.ts +1164 -0
- package/templates/.opencode/plugins/diff.ts +85 -0
- package/templates/.opencode/plugins/gates.ts +71 -0
- package/templates/.opencode/plugins/job-notify.ts +241 -0
- package/templates/.opencode/plugins/orient.ts +67 -0
- package/templates/.opencode/plugins/session.ts +89 -0
- package/templates/.opencode/plugins/wait.ts +101 -0
- package/templates/.opencode/plugins/where.ts +70 -0
- package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
- package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
- package/templates/.vercelignore +16 -0
- package/templates/AGENTS.md +27 -0
- package/templates/BACKLOG.md +95 -0
- package/templates/docs/ci-cd-pipeline.md +81 -0
- package/templates/docs/gates.md +128 -0
- package/templates/docs/mcp-integrations.md +97 -0
- package/templates/docs/mobile-testing.md +555 -0
- package/templates/docs/nightly-testing.md +106 -0
- package/templates/docs/wsl-optimizations.md +290 -0
- package/templates/opencode.json +188 -0
- package/templates/scripts/agent-report.js +541 -0
- package/templates/scripts/agent-search.sh +117 -0
- package/templates/scripts/backlog.js +1924 -0
- package/templates/scripts/board-service.sh +214 -0
- package/templates/scripts/checkpoint.js +290 -0
- package/templates/scripts/finalize.js +416 -0
- package/templates/scripts/nightly.js +913 -0
- package/templates/scripts/orient.js +514 -0
- package/templates/scripts/qa/board-client.js +323 -0
- package/templates/scripts/qa/board-lib.js +96 -0
- package/templates/scripts/qa/board-sync.js +499 -0
- package/templates/scripts/qa/capacity-lib.js +916 -0
- package/templates/scripts/qa/check-backlog.js +434 -0
- package/templates/scripts/qa/check-capacity.js +85 -0
- package/templates/scripts/qa/check-ci-policy.js +164 -0
- package/templates/scripts/qa/check-concurrency.js +344 -0
- package/templates/scripts/qa/check-dispatch-config.js +296 -0
- package/templates/scripts/qa/check-docs.js +288 -0
- package/templates/scripts/qa/check-integrate.js +98 -0
- package/templates/scripts/qa/check-linger.js +160 -0
- package/templates/scripts/qa/check-prefix-stability.js +187 -0
- package/templates/scripts/qa/check-product.js +177 -0
- package/templates/scripts/qa/check-qa-plan.js +378 -0
- package/templates/scripts/qa/check-qa-scripts.js +85 -0
- package/templates/scripts/qa/check-quality.js +249 -0
- package/templates/scripts/qa/check-test-wiring.js +253 -0
- package/templates/scripts/qa/check-worktrees.js +93 -0
- package/templates/scripts/qa/ci-triage.js +346 -0
- package/templates/scripts/qa/ci-usage-lib.js +185 -0
- package/templates/scripts/qa/ci-wait-lib.js +294 -0
- package/templates/scripts/qa/command-classifier.js +552 -0
- package/templates/scripts/qa/context-guard-core.js +1618 -0
- package/templates/scripts/qa/diff.js +174 -0
- package/templates/scripts/qa/feature-scaffold.js +224 -0
- package/templates/scripts/qa/fixtures/backlog.md +104 -0
- package/templates/scripts/qa/governance.js +174 -0
- package/templates/scripts/qa/hash-file.js +32 -0
- package/templates/scripts/qa/lease-lib.js +263 -0
- package/templates/scripts/qa/merge-backlog.js +324 -0
- package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
- package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
- package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
- package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
- package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
- package/templates/scripts/qa/mobile-e2e/check-flows.js +568 -0
- package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
- package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
- package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
- package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
- package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
- package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
- package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
- package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
- package/templates/scripts/qa/models.allowlist.txt +32 -0
- package/templates/scripts/qa/provider-stats.js +878 -0
- package/templates/scripts/qa/run-clean.js +83 -0
- package/templates/scripts/qa/run-gates.js +213 -0
- package/templates/scripts/qa/run-loop.js +220 -0
- package/templates/scripts/qa/session-recon.js +512 -0
- package/templates/scripts/qa/store-lib.js +324 -0
- package/templates/scripts/qa/tool-lib.js +134 -0
- package/templates/scripts/qa/where.js +214 -0
- package/templates/scripts/qa/worktree-hygiene.js +217 -0
- package/templates/scripts/qa/wslconfig-merge.js +157 -0
- package/templates/scripts/serve.js +1328 -0
- package/templates/scripts/setup-nightly.sh +185 -0
- package/templates/scripts/setup-tmpfs.sh +374 -0
- package/templates/scripts/ship.js +586 -0
- package/templates/scripts/switch-reasoning-model.ps1 +101 -0
- package/templates/scripts/switch-reasoning-model.sh +104 -0
- package/templates/scripts/wait-for.js +342 -0
- package/templates/scripts/wsl-gpu.sh +180 -0
- package/templates/scripts/wsl-tune.sh +319 -0
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
"use strict";
|
|
3
|
+
/*
|
|
4
|
+
* test:docs — documentation hygiene gate (harness-shipped).
|
|
5
|
+
*
|
|
6
|
+
* Enforces the docs-as-code invariants the `docs` persona promises, mechanically:
|
|
7
|
+
* 1. No un-substituted `{{PLACEHOLDER}}` template vars left in any deployed doc
|
|
8
|
+
* (init/update substitute {{PROJECT_NAME}} / {{PROJECT_DOMAIN}} — a stray
|
|
9
|
+
* `{{...}}` in a shipped doc is a deploy bug).
|
|
10
|
+
* 2. No dangling relative markdown links in README.md / docs/** (a doc that
|
|
11
|
+
* points at a path that no longer exists is drift).
|
|
12
|
+
* 3. Every ADR (docs/adr/*.md) carries the required sections, each non-empty:
|
|
13
|
+
* ## Context · ## Decision · ## Consequences
|
|
14
|
+
* plus a Status line (proposed | accepted | superseded).
|
|
15
|
+
* 4. Changelog completeness: every shipped commit (`feat`/`fix`/`refactor`/
|
|
16
|
+
* `perf`) since CHANGELOG.md first appeared must be cited in it by short
|
|
17
|
+
* hash (`abc1234` — backticked or parenthesized). This is the mechanical
|
|
18
|
+
* backstop that keeps the changelog from silently drifting.
|
|
19
|
+
* 5. Review/audit ships are changelog-visible: a commit that delivers durable
|
|
20
|
+
* review findings under `.agents/reviews/**` is a meaningful milestone even
|
|
21
|
+
* though it ships as `docs`/`chore`, so it must be cited in CHANGELOG.md
|
|
22
|
+
* like any feat/fix (convention: append a `docs(review)` line). This makes
|
|
23
|
+
* "we ran a review and filed N rows" appear in the human changelog instead
|
|
24
|
+
* of being invisible because a code-quality review ships as `docs`/`chore`.
|
|
25
|
+
*
|
|
26
|
+
* Backward compatible: with no README.md and no docs/ tree the gate warns and
|
|
27
|
+
* passes — projects opt in by keeping docs. Links are checked only against the
|
|
28
|
+
* local filesystem; http(s)/mailto/`#anchor`/reference-style links are skipped.
|
|
29
|
+
* A missing CHANGELOG.md (or a git-less checkout) only warns — changelog
|
|
30
|
+
* completeness is enforced once a committed CHANGELOG.md exists.
|
|
31
|
+
*
|
|
32
|
+
* node scripts/qa/check-docs.js
|
|
33
|
+
*
|
|
34
|
+
* Exit 0 on: no docs, or every doc satisfying the contract.
|
|
35
|
+
* Exit 1 on: any placeholder left behind, dangling link, or malformed ADR.
|
|
36
|
+
*/
|
|
37
|
+
const fs = require("fs");
|
|
38
|
+
const path = require("path");
|
|
39
|
+
const { execFileSync } = require("child_process");
|
|
40
|
+
|
|
41
|
+
const root = path.resolve(__dirname, "..", "..");
|
|
42
|
+
|
|
43
|
+
const failures = [];
|
|
44
|
+
const pass = (m) => console.log(" \u2713 " + m);
|
|
45
|
+
const fail = (m) => {
|
|
46
|
+
failures.push(m);
|
|
47
|
+
console.log(" \u2717 " + m);
|
|
48
|
+
};
|
|
49
|
+
const warn = (m) => console.log(" \u26a0 " + m);
|
|
50
|
+
|
|
51
|
+
console.log("docs gate \u2014 docs-as-code: no placeholders, no dangling links, well-formed ADRs, complete changelog");
|
|
52
|
+
|
|
53
|
+
// ---- collect doc files -------------------------------------------------------
|
|
54
|
+
const docFiles = [];
|
|
55
|
+
const readme = path.join(root, "README.md");
|
|
56
|
+
if (fs.existsSync(readme)) docFiles.push({ abs: readme, rel: "README.md" });
|
|
57
|
+
|
|
58
|
+
const docsDir = path.join(root, "docs");
|
|
59
|
+
function collectDocs(dir, base) {
|
|
60
|
+
if (!fs.existsSync(dir)) return;
|
|
61
|
+
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
|
62
|
+
const abs = path.join(dir, entry.name);
|
|
63
|
+
if (entry.isDirectory()) collectDocs(abs, base);
|
|
64
|
+
else if (entry.name.endsWith(".md")) docFiles.push({ abs, rel: path.relative(base, abs) });
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
collectDocs(docsDir, root);
|
|
68
|
+
|
|
69
|
+
if (docFiles.length === 0) {
|
|
70
|
+
warn("no README.md and no docs/ tree \u2014 nothing to enforce");
|
|
71
|
+
console.log("\nRESULT: green (no docs)");
|
|
72
|
+
process.exit(0);
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
// ---- 1. no un-substituted template placeholders -----------------------------
|
|
76
|
+
// Only flag placeholders in prose: a doc that *documents* the token (e.g.
|
|
77
|
+
// `docs/gates.md` quoting `{{PLACEHOLDER}}` in a code span) must pass, while a
|
|
78
|
+
// real un-substituted var in prose still fails. Strip fenced blocks + inline
|
|
79
|
+
// code spans first (the F-305 docs-gate false positive).
|
|
80
|
+
function stripCode(src) {
|
|
81
|
+
return String(src)
|
|
82
|
+
.replace(/```[\s\S]*?```/g, "")
|
|
83
|
+
.replace(/`[^`\n]*`/g, "");
|
|
84
|
+
}
|
|
85
|
+
const PLACEHOLDER = /\{\{[A-Z_]+\}\}/;
|
|
86
|
+
for (const { abs, rel } of docFiles) {
|
|
87
|
+
const src = fs.readFileSync(abs, "utf8");
|
|
88
|
+
const m = stripCode(src).match(PLACEHOLDER);
|
|
89
|
+
if (m) fail(`${rel}: un-substituted placeholder \`${m[0]}\` \u2014 deploy substitutes it`);
|
|
90
|
+
else pass(`${rel}: no un-substituted template placeholders`);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
// ---- 2. no dangling relative links ------------------------------------------
|
|
94
|
+
// Links are a prose construct: a `plugin["tool.execute.before"](...)` example
|
|
95
|
+
// inside a code span is API notation, not a markdown link (the F-004 false
|
|
96
|
+
// positive). Strip fenced blocks + inline code spans before scanning.
|
|
97
|
+
function relativeLinks(src) {
|
|
98
|
+
const links = [];
|
|
99
|
+
const re = /(?<!\!)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
|
|
100
|
+
const prose = stripCode(src);
|
|
101
|
+
let m;
|
|
102
|
+
while ((m = re.exec(prose)) !== null) links.push(m[1]);
|
|
103
|
+
return links;
|
|
104
|
+
}
|
|
105
|
+
function isExternal(target) {
|
|
106
|
+
return (
|
|
107
|
+
/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(target) || // scheme (http:, mailto:, etc.)
|
|
108
|
+
/^\/\//.test(target) || // protocol-relative
|
|
109
|
+
/^#/.test(target) // anchor only
|
|
110
|
+
);
|
|
111
|
+
}
|
|
112
|
+
for (const { abs, rel } of docFiles) {
|
|
113
|
+
const src = fs.readFileSync(abs, "utf8");
|
|
114
|
+
let dangling = 0;
|
|
115
|
+
for (const raw of relativeLinks(src)) {
|
|
116
|
+
let target = raw.trim();
|
|
117
|
+
if (!target) continue;
|
|
118
|
+
if (target.startsWith("<") && target.endsWith(">")) target = target.slice(1, -1);
|
|
119
|
+
if (isExternal(target)) continue;
|
|
120
|
+
const filePart = target.split("#")[0];
|
|
121
|
+
if (!filePart) continue; // pure anchor (#heading)
|
|
122
|
+
const resolved = path.resolve(path.dirname(abs), filePart);
|
|
123
|
+
if (!fs.existsSync(resolved)) {
|
|
124
|
+
fail(`${rel}: dangling link \`${raw}\` \u2192 ${path.relative(root, resolved)} does not exist`);
|
|
125
|
+
dangling++;
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
if (dangling === 0) pass(`${rel}: relative links resolve`);
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
// ---- 3. ADRs carry Context / Decision / Consequences + Status ---------------
|
|
132
|
+
function section(src, re) {
|
|
133
|
+
const lines = src.split(/\r?\n/);
|
|
134
|
+
let inSec = false;
|
|
135
|
+
const body = [];
|
|
136
|
+
for (const raw of lines) {
|
|
137
|
+
const line = raw.trim();
|
|
138
|
+
if (!inSec) {
|
|
139
|
+
if (re.test(line)) inSec = true;
|
|
140
|
+
continue;
|
|
141
|
+
}
|
|
142
|
+
if (/^#{1,6}\s/.test(line)) break;
|
|
143
|
+
if (line && !/^<!--/.test(line) && !/_TODO:/.test(line)) body.push(line);
|
|
144
|
+
}
|
|
145
|
+
return body;
|
|
146
|
+
}
|
|
147
|
+
function hasSection(src, re) {
|
|
148
|
+
return section(src, re).length > 0;
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
const adrDir = path.join(docsDir, "adr");
|
|
152
|
+
if (!fs.existsSync(adrDir)) {
|
|
153
|
+
pass("no docs/adr/ directory \u2014 ADR checks skipped");
|
|
154
|
+
} else {
|
|
155
|
+
const adrs = fs
|
|
156
|
+
.readdirSync(adrDir, { withFileTypes: true })
|
|
157
|
+
.filter((e) => e.isFile() && e.name.endsWith(".md") && !/^(INDEX|README)\.md$/i.test(e.name))
|
|
158
|
+
.map((e) => e.name)
|
|
159
|
+
.sort();
|
|
160
|
+
if (adrs.length === 0) {
|
|
161
|
+
pass("docs/adr/ present but empty");
|
|
162
|
+
} else {
|
|
163
|
+
const H = {
|
|
164
|
+
context: /^#{1,6}\s*Context\b/i,
|
|
165
|
+
decision: /^#{1,6}\s*Decision\b/i,
|
|
166
|
+
consequences: /^#{1,6}\s*Consequences\b/i,
|
|
167
|
+
};
|
|
168
|
+
for (const name of adrs) {
|
|
169
|
+
const src = fs.readFileSync(path.join(adrDir, name), "utf8");
|
|
170
|
+
const missing = [];
|
|
171
|
+
if (!hasSection(src, H.context)) missing.push("## Context");
|
|
172
|
+
if (!hasSection(src, H.decision)) missing.push("## Decision");
|
|
173
|
+
if (!hasSection(src, H.consequences)) missing.push("## Consequences");
|
|
174
|
+
if (!/^Status:\s*(proposed|accepted|superseded|deprecated|rejected)\s*$/im.test(src) && !hasSection(src, /^#{1,6}\s*Status\b/i)) {
|
|
175
|
+
missing.push("Status (proposed|accepted|superseded)");
|
|
176
|
+
}
|
|
177
|
+
if (missing.length) fail(`adr/${name}: missing \u2014 ${missing.join(", ")}`);
|
|
178
|
+
else pass(`adr/${name}: context \u2192 decision \u2192 consequences + status present`);
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
// ---- 4. changelog completeness (every shipped commit is recorded) ----------
|
|
184
|
+
const changelogPath = path.join(root, "CHANGELOG.md");
|
|
185
|
+
function gitLog(args) {
|
|
186
|
+
try {
|
|
187
|
+
return execFileSync("git", args, {
|
|
188
|
+
cwd: root,
|
|
189
|
+
encoding: "utf8",
|
|
190
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
191
|
+
});
|
|
192
|
+
} catch {
|
|
193
|
+
return null;
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
if (!fs.existsSync(changelogPath)) {
|
|
197
|
+
warn("no CHANGELOG.md \u2014 changelog completeness not enforced");
|
|
198
|
+
} else {
|
|
199
|
+
const baseline = gitLog(["log", "--diff-filter=A", "--format=%H", "-1", "--", "CHANGELOG.md"]);
|
|
200
|
+
if (!baseline || !baseline.trim()) {
|
|
201
|
+
warn("CHANGELOG.md has no git history \u2014 changelog completeness skipped");
|
|
202
|
+
} else {
|
|
203
|
+
const changelog = fs.readFileSync(changelogPath, "utf8");
|
|
204
|
+
const cited = new Set();
|
|
205
|
+
const hashRe = /(?:`|[(])([0-9a-f]{7,40})(?:`|[)]|\s)/gi;
|
|
206
|
+
let m;
|
|
207
|
+
while ((m = hashRe.exec(changelog)) !== null) cited.add(m[1].slice(0, 7).toLowerCase());
|
|
208
|
+
|
|
209
|
+
// A squash-merged PR lands as ONE new commit on the default branch whose
|
|
210
|
+
// hash differs from the branch commit the CHANGELOG entry cites. That commit
|
|
211
|
+
// ships its own CHANGELOG.md delta (the entry was authored on the branch and
|
|
212
|
+
// squashed in), so a commit that itself modifies CHANGELOG.md is
|
|
213
|
+
// self-documenting — do not demand a citation for its rewritten hash. A
|
|
214
|
+
// shipped commit that forgot the changelog has no CHANGELOG.md delta and is
|
|
215
|
+
// still flagged.
|
|
216
|
+
const selfDocLog = gitLog([
|
|
217
|
+
"log",
|
|
218
|
+
"--no-merges",
|
|
219
|
+
"--format=%h",
|
|
220
|
+
`${baseline.trim()}..HEAD`,
|
|
221
|
+
"--",
|
|
222
|
+
"CHANGELOG.md",
|
|
223
|
+
]);
|
|
224
|
+
const selfDocumented = new Set(
|
|
225
|
+
selfDocLog ? selfDocLog.split(/\r?\n/).filter(Boolean).map((h) => h.toLowerCase()) : []
|
|
226
|
+
);
|
|
227
|
+
|
|
228
|
+
const log = gitLog(["log", "--no-merges", "--format=%h%x09%s", `${baseline.trim()}..HEAD`]);
|
|
229
|
+
if (log === null) {
|
|
230
|
+
warn("git unavailable \u2014 changelog completeness skipped");
|
|
231
|
+
} else {
|
|
232
|
+
const missing = [];
|
|
233
|
+
for (const line of log.split(/\r?\n/)) {
|
|
234
|
+
if (!line) continue;
|
|
235
|
+
const sep = line.indexOf("\t");
|
|
236
|
+
if (sep < 0) continue;
|
|
237
|
+
const hash = line.slice(0, sep);
|
|
238
|
+
const subject = line.slice(sep + 1);
|
|
239
|
+
if (!/^(feat|fix|refactor|perf)(\([^)]*\))?:/.test(subject)) continue;
|
|
240
|
+
if (!cited.has(hash.toLowerCase()) && !selfDocumented.has(hash.toLowerCase())) {
|
|
241
|
+
missing.push({ hash, subject });
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
// 5. Review/audit deliverables are milestones too — a commit that ships
|
|
246
|
+
// `.agents/reviews/**` is changelog-worthy even as docs/chore.
|
|
247
|
+
const reviewLog = gitLog([
|
|
248
|
+
"log",
|
|
249
|
+
"--no-merges",
|
|
250
|
+
"--format=%h%x09%s",
|
|
251
|
+
`${baseline.trim()}..HEAD`,
|
|
252
|
+
"--",
|
|
253
|
+
".agents/reviews/",
|
|
254
|
+
]);
|
|
255
|
+
if (reviewLog) {
|
|
256
|
+
for (const line of reviewLog.split(/\r?\n/)) {
|
|
257
|
+
if (!line) continue;
|
|
258
|
+
const sep = line.indexOf("\t");
|
|
259
|
+
if (sep < 0) continue;
|
|
260
|
+
const hash = line.slice(0, sep);
|
|
261
|
+
const subject = line.slice(sep + 1);
|
|
262
|
+
if (!cited.has(hash.toLowerCase()) && !selfDocumented.has(hash.toLowerCase())) {
|
|
263
|
+
missing.push({ hash, subject, note: "ships .agents/reviews/ — append a docs(review) changelog line" });
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
if (missing.length === 0) {
|
|
269
|
+
pass(`CHANGELOG.md: every shipped commit since ${baseline.trim().slice(0, 7)} is recorded`);
|
|
270
|
+
} else {
|
|
271
|
+
for (const { hash, subject, note } of missing) {
|
|
272
|
+
fail(
|
|
273
|
+
`CHANGELOG.md: missing entry for ${hash} \u2014 ${subject}` +
|
|
274
|
+
(note ? ` (${note})` : "")
|
|
275
|
+
);
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
console.log(
|
|
283
|
+
"\nRESULT: " +
|
|
284
|
+
(failures.length
|
|
285
|
+
? `${failures.length} FAILURE(S) \u2014 docs must have no placeholders, no dangling links, well-formed ADRs, and a complete changelog`
|
|
286
|
+
: "green \u2014 docs are in sync")
|
|
287
|
+
);
|
|
288
|
+
process.exit(failures.length ? 1 : 0);
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
"use strict";
|
|
3
|
+
/*
|
|
4
|
+
* test:integrate — pre-push rebase check (harness-shipped).
|
|
5
|
+
*
|
|
6
|
+
* Integrate-early gate: fails when the current branch is behind its upstream
|
|
7
|
+
* (`origin/main`), so board/code conflicts surface before push instead of at the
|
|
8
|
+
* merge. Runs a best-effort `git fetch`, then compares HEAD to the upstream
|
|
9
|
+
* tracking branch. On "behind", it fails with the exact rebase + re-gate
|
|
10
|
+
* sequence; on a dirty tree it warns that rebasing needs a clean tree.
|
|
11
|
+
*
|
|
12
|
+
* Exit 0 unless the branch is provably behind its upstream. Skipped outside a
|
|
13
|
+
* git repo / with no upstream configured.
|
|
14
|
+
*/
|
|
15
|
+
const fs = require("fs");
|
|
16
|
+
const path = require("path");
|
|
17
|
+
const { execFileSync, spawnSync } = require("child_process");
|
|
18
|
+
|
|
19
|
+
const root = path.resolve(__dirname, "..", "..");
|
|
20
|
+
|
|
21
|
+
function git(args) {
|
|
22
|
+
try {
|
|
23
|
+
return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
|
|
24
|
+
} catch (_) {
|
|
25
|
+
return null;
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function insideGitRepo() {
|
|
30
|
+
const r = git(["rev-parse", "--is-inside-work-tree"]);
|
|
31
|
+
return !!r && r.trim() === "true";
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function dirtyFiles() {
|
|
35
|
+
const out = git(["status", "--porcelain"]) || "";
|
|
36
|
+
return out.split(/\r?\n/).filter(Boolean);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
console.log("integrate gate \u2014 rebase onto main before pushing, so conflicts surface early");
|
|
40
|
+
|
|
41
|
+
if (!insideGitRepo()) {
|
|
42
|
+
console.log(" \u26a0 not a git repo \u2014 integrate gate skipped");
|
|
43
|
+
console.log("\nRESULT: skipped (0 failures)");
|
|
44
|
+
process.exit(0);
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
// Best-effort fetch (never blocks the gate on network/auth failure).
|
|
48
|
+
try {
|
|
49
|
+
git(["fetch", "--quiet", "origin"]);
|
|
50
|
+
} catch (_) {
|
|
51
|
+
/* offline — rely on the local remote refs */
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/* The integration TARGET is the canonical branch (`origin/main`), NOT the
|
|
55
|
+
* branch's own upstream (`@{u}` = `origin/<feature>`). Comparing HEAD to the
|
|
56
|
+
* branch's own remote falsely fails every legitimate post-rebase force-push:
|
|
57
|
+
* after `git rebase origin/main`, HEAD is ahead of the stale `origin/<feature>`
|
|
58
|
+
* and the gate demanded a rebase that had just been done, blocking the push.
|
|
59
|
+
* Fall back to `@{u}` only when the canonical branch cannot be determined. */
|
|
60
|
+
function integrationTarget() {
|
|
61
|
+
const sym = git(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
|
|
62
|
+
if (sym) return sym.trim();
|
|
63
|
+
for (const name of ["origin/main", "origin/master"]) {
|
|
64
|
+
if (git(["rev-parse", "--verify", "--quiet", name])) return name;
|
|
65
|
+
}
|
|
66
|
+
return (git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]) || "").trim();
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
const upstream = integrationTarget();
|
|
70
|
+
if (!upstream) {
|
|
71
|
+
console.log(" \u26a0 no canonical branch / upstream configured \u2014 integrate gate skipped");
|
|
72
|
+
console.log("\nRESULT: skipped (0 failures)");
|
|
73
|
+
process.exit(0);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
const counts = (git(["rev-list", "--left-right", "--count", `HEAD...${upstream}`]) || "").trim();
|
|
77
|
+
const parts = counts.split(/\s+/);
|
|
78
|
+
// `--left-right --count A...B` prints `<A-only>\t<B-only>`; here A=HEAD, B=upstream,
|
|
79
|
+
// so A-only = ahead, B-only = behind.
|
|
80
|
+
const ahead = parts.length === 2 ? parseInt(parts[0], 10) || 0 : 0;
|
|
81
|
+
const behind = parts.length === 2 ? parseInt(parts[1], 10) || 0 : 0;
|
|
82
|
+
|
|
83
|
+
const dirty = dirtyFiles().length;
|
|
84
|
+
|
|
85
|
+
if (behind > 0) {
|
|
86
|
+
console.log(` \u2717 behind ${upstream} by ${behind} commit(s) (ahead ${ahead})`);
|
|
87
|
+
console.log(
|
|
88
|
+
` rebase first: git rebase ${upstream} then re-run: npm run test:backlog && npm run test:concurrency`
|
|
89
|
+
);
|
|
90
|
+
if (dirty) console.log(" \u26a0 working tree is dirty \u2014 commit or stash before rebasing");
|
|
91
|
+
console.log(`\nRESULT: 1 FAILURE \u2014 rebase ${upstream} before push`);
|
|
92
|
+
process.exit(1);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
console.log(` \u2713 up to date with ${upstream} (ahead ${ahead})`);
|
|
96
|
+
if (dirty) console.log(` \u26a0 working tree is dirty (${dirty} change(s)) \u2014 commit before push`);
|
|
97
|
+
console.log("\nRESULT: green");
|
|
98
|
+
process.exit(0);
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
"use strict";
|
|
3
|
+
/*
|
|
4
|
+
* check-linger — process-vs-tests linger detector (harness-shipped).
|
|
5
|
+
*
|
|
6
|
+
* The exit-contract half of the test-design rubric (T1/T6/T9). A suite can report
|
|
7
|
+
* every test passing in milliseconds and still hold the process open for a
|
|
8
|
+
* minute on a pool/socket/timer — the measured F-132 case: 22 tests in 76 ms,
|
|
9
|
+
* process exit at 60.4 s. Nothing in a normal green run surfaces that, so it
|
|
10
|
+
* silently taxes every push. This wrapper runs a tier command, measures the real
|
|
11
|
+
* wall-clock, parses the runner's self-reported duration, and fails when the
|
|
12
|
+
* process lingers after the tests are done.
|
|
13
|
+
*
|
|
14
|
+
* node scripts/qa/check-linger.js # wraps `npm run test:quick`
|
|
15
|
+
* node scripts/qa/check-linger.js -- npm run test:api # wraps an explicit tier
|
|
16
|
+
* node scripts/qa/check-linger.js --max-linger 3 --ratio 0.25 -- <command...>
|
|
17
|
+
*
|
|
18
|
+
* Fail condition: `linger > max-linger seconds` AND `linger > ratio * test-time`
|
|
19
|
+
* (the ratio keeps long legitimate suites from failing on a proportional teardown).
|
|
20
|
+
* The child's own exit code is always propagated; a linger finding adds exit 1.
|
|
21
|
+
*/
|
|
22
|
+
const fs = require("fs");
|
|
23
|
+
const path = require("path");
|
|
24
|
+
const { spawnSync } = require("child_process");
|
|
25
|
+
|
|
26
|
+
const root = path.resolve(__dirname, "..", "..");
|
|
27
|
+
const argv = process.argv.slice(2);
|
|
28
|
+
|
|
29
|
+
function parseArgs(args) {
|
|
30
|
+
let maxLinger = 5;
|
|
31
|
+
let ratio = 0.5;
|
|
32
|
+
const rest = [];
|
|
33
|
+
for (let i = 0; i < args.length; i++) {
|
|
34
|
+
const a = args[i];
|
|
35
|
+
if (a === "--") {
|
|
36
|
+
rest.push(...args.slice(i + 1));
|
|
37
|
+
break;
|
|
38
|
+
}
|
|
39
|
+
if (a === "--max-linger") maxLinger = parseFloat(args[++i]);
|
|
40
|
+
else if (a.startsWith("--max-linger=")) maxLinger = parseFloat(a.split("=")[1]);
|
|
41
|
+
else if (a === "--ratio") ratio = parseFloat(args[++i]);
|
|
42
|
+
else if (a.startsWith("--ratio=")) ratio = parseFloat(a.split("=")[1]);
|
|
43
|
+
else rest.push(a);
|
|
44
|
+
}
|
|
45
|
+
return {
|
|
46
|
+
maxLinger: Number.isFinite(maxLinger) ? maxLinger : 5,
|
|
47
|
+
ratio: Number.isFinite(ratio) ? ratio : 0.5,
|
|
48
|
+
commandArgs: rest,
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
const { maxLinger: maxLingerSec, ratio, commandArgs } = parseArgs(argv);
|
|
53
|
+
|
|
54
|
+
function resolveCommand() {
|
|
55
|
+
if (commandArgs.length) return commandArgs.join(" ");
|
|
56
|
+
// No explicit command: wrap the project's pre-push tier (the one that pays the
|
|
57
|
+
// linger cost on every push) when it exists.
|
|
58
|
+
const pkgPath = path.join(root, "package.json");
|
|
59
|
+
if (fs.existsSync(pkgPath)) {
|
|
60
|
+
try {
|
|
61
|
+
const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
|
|
62
|
+
if (pkg.scripts && pkg.scripts["test:quick"]) return "npm run test:quick";
|
|
63
|
+
} catch (_) {
|
|
64
|
+
/* fall through to usage */
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
return null;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
const command = resolveCommand();
|
|
71
|
+
if (!command) {
|
|
72
|
+
console.error(
|
|
73
|
+
"usage: node scripts/qa/check-linger.js [--max-linger <sec>] [--ratio <x>] [--] <command...>\n" +
|
|
74
|
+
" (no command given and no `test:quick` script exists to wrap)"
|
|
75
|
+
);
|
|
76
|
+
process.exit(2);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
console.log(`linger gate \u2014 process wall-clock vs runner-reported test duration (T1/T6/T9)`);
|
|
80
|
+
console.log(` command: ${command}`);
|
|
81
|
+
console.log(` thresholds: linger > ${maxLingerSec}s and > ${ratio}\u00d7 test time\n`);
|
|
82
|
+
|
|
83
|
+
const started = process.hrtime.bigint();
|
|
84
|
+
const r = spawnSync(command, {
|
|
85
|
+
cwd: root,
|
|
86
|
+
shell: true,
|
|
87
|
+
encoding: "utf8",
|
|
88
|
+
maxBuffer: 256 * 1024 * 1024,
|
|
89
|
+
env: process.env,
|
|
90
|
+
windowsHide: true,
|
|
91
|
+
});
|
|
92
|
+
const wallMs = Number(process.hrtime.bigint() - started) / 1e6;
|
|
93
|
+
|
|
94
|
+
const out = (r.stdout || "") + (r.stderr || "");
|
|
95
|
+
if (out.trim()) process.stdout.write(out.endsWith("\n") ? out : out + "\n");
|
|
96
|
+
|
|
97
|
+
/* Runner-reported test duration. node:test prints `duration_ms 76.4` in its spec
|
|
98
|
+
* footer (TAP: `# duration_ms 76`); jest prints `Time: 1.234 s`; vitest prints
|
|
99
|
+
* `Duration 1.23s`. Prefer the LAST match (totals come last). */
|
|
100
|
+
function parseTestMs(text) {
|
|
101
|
+
const patterns = [
|
|
102
|
+
/duration_ms[:\s]+([0-9.]+)/gi,
|
|
103
|
+
/(?:^|\n)[^\S\n]*Time:[^\S\n]+([0-9.]+)\s*s/gi,
|
|
104
|
+
/(?:^|\n)[^\S\n]*Duration[^\S\n]+([0-9.]+)\s*s/gi,
|
|
105
|
+
];
|
|
106
|
+
const found = [];
|
|
107
|
+
for (const re of patterns) {
|
|
108
|
+
let m;
|
|
109
|
+
while ((m = re.exec(text))) {
|
|
110
|
+
const n = parseFloat(m[1]);
|
|
111
|
+
if (Number.isFinite(n)) found.push(n);
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
if (!found.length) return null;
|
|
115
|
+
return found[found.length - 1];
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
function parseTests(text) {
|
|
119
|
+
const m = text.match(/(?:^|\n)[#\u2139\s]*tests[:\s]+(\d+)/i);
|
|
120
|
+
return m ? parseInt(m[1], 10) : null;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
const testMs = parseTestMs(out);
|
|
124
|
+
const tests = parseTests(out);
|
|
125
|
+
const lingerMs = testMs == null ? null : wallMs - testMs;
|
|
126
|
+
|
|
127
|
+
const secs = (ms) => (ms / 1000).toFixed(1) + "s";
|
|
128
|
+
console.log("\nlinger analysis:");
|
|
129
|
+
if (testMs == null) {
|
|
130
|
+
console.log(` \u26a0 runner-reported duration not parseable \u2014 wall-clock only: ${secs(wallMs)}`);
|
|
131
|
+
console.log(" (supported: node:test `duration_ms`, jest `Time:`, vitest `Duration`)");
|
|
132
|
+
} else {
|
|
133
|
+
console.log(` runner-reported tests: ${tests == null ? "?" : tests} in ${secs(testMs)}`);
|
|
134
|
+
console.log(` process wall-clock: ${secs(wallMs)}`);
|
|
135
|
+
console.log(` linger after tests: ${secs(lingerMs)}`);
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
const lingered = testMs != null && lingerMs > maxLingerSec * 1000 && lingerMs > ratio * testMs;
|
|
139
|
+
if (lingered) {
|
|
140
|
+
console.log(
|
|
141
|
+
` \u2717 LINGER \u2014 the process held ${secs(lingerMs)} after the runner finished ` +
|
|
142
|
+
`(budget ${maxLingerSec}s). Close pools/sockets/timers in after(), or pin the runner's ` +
|
|
143
|
+
`force-exit (node:test: --test-force-exit). Record the suite's wall-clock + teardown in the ` +
|
|
144
|
+
"QA plan's `## Test budget` (T1/T6/T9)."
|
|
145
|
+
);
|
|
146
|
+
} else if (testMs != null) {
|
|
147
|
+
console.log(" \u2713 exit contract holds \u2014 process terminated within budget after the tests");
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
const childCode = r.status == null ? 1 : r.status;
|
|
151
|
+
const code = lingered ? 1 : childCode;
|
|
152
|
+
console.log(
|
|
153
|
+
"\nRESULT: " +
|
|
154
|
+
(lingered
|
|
155
|
+
? "FAILURE \u2014 passing-but-idling suite (linger > budget)"
|
|
156
|
+
: childCode === 0
|
|
157
|
+
? "green \u2014 command passed and no linger detected"
|
|
158
|
+
: `command failed (exit ${childCode}) \u2014 no linger finding`)
|
|
159
|
+
);
|
|
160
|
+
process.exit(code);
|