rungate 0.5.0 → 0.7.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.
- package/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +411 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- package/scripts/sync-spec-tests.ts +2 -1
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which tool names Claude Code actually knows, so a deny list denies things
|
|
3
|
+
* that exist (#885).
|
|
4
|
+
*
|
|
5
|
+
* The CLI validates every `--allowedTools` / `--disallowedTools` entry at
|
|
6
|
+
* startup and prints a warning for a name it does not recognise:
|
|
7
|
+
*
|
|
8
|
+
* Permission deny rule "SlashCommand" matches no known tool — check for typos.
|
|
9
|
+
* Permission deny rule "MultiEdit" matches no known tool — check for typos.
|
|
10
|
+
*
|
|
11
|
+
* Then it carries on. So **a rule that matches no known tool is
|
|
12
|
+
* indistinguishable from a rule that is holding** — eleven entries in a deny
|
|
13
|
+
* list read as eleven denials, and two of them are inert. Nothing asserted
|
|
14
|
+
* otherwise, which also means a tool renamed upstream silently turns its
|
|
15
|
+
* denial off and the only trace is a line in a log nobody greps.
|
|
16
|
+
*
|
|
17
|
+
* ## The record, and how it was taken
|
|
18
|
+
*
|
|
19
|
+
* Measured 2026-10-21 against `claude 2.1.306`, with this command — no network
|
|
20
|
+
* call is made, because the CLI validates the rules and then refuses the empty
|
|
21
|
+
* prompt:
|
|
22
|
+
*
|
|
23
|
+
* printf '' | claude -p --disallowedTools "<comma-separated names>"
|
|
24
|
+
*
|
|
25
|
+
* The candidate list probed was deliberately WIDER than anything this repo
|
|
26
|
+
* emits. A record built only from the names we use would be the question
|
|
27
|
+
* restated — `.claude/rules/checks-must-be-able-to-fail.md`'s #530 shape,
|
|
28
|
+
* where the artifact agrees because you put the value in it. 35 names went in;
|
|
29
|
+
* the 29 below came back known and 6 came back unknown.
|
|
30
|
+
*
|
|
31
|
+
* ## What this record is NOT
|
|
32
|
+
*
|
|
33
|
+
* It is not a claim about the CLI running in CI, which is a different version
|
|
34
|
+
* (`v2.1.303` at the time of writing). It is a claim about the vocabulary on
|
|
35
|
+
* the day and version named above, and `probePermissionRules` below is how a
|
|
36
|
+
* machine with a CLI re-takes it. A tree with no `claude` on PATH gets
|
|
37
|
+
* `UNMEASURED` from that probe and the static comparison from
|
|
38
|
+
* `unknownAgainstRecord`, which is `.claude/rules/checks-must-be-able-to-fail.md`'s
|
|
39
|
+
* split: enforce the half the repo owns, and make the other half say it did
|
|
40
|
+
* not run.
|
|
41
|
+
*/
|
|
42
|
+
|
|
43
|
+
import { probeExternalTool, toolProbe, type ToolProbe } from "./tool-probe";
|
|
44
|
+
|
|
45
|
+
export const CLAUDE_TOOL_VOCABULARY_VERSION = "2.1.306";
|
|
46
|
+
export const CLAUDE_TOOL_VOCABULARY_MEASURED_ON = "2026-10-21";
|
|
47
|
+
export const CLAUDE_TOOL_VOCABULARY_COMMAND =
|
|
48
|
+
`printf '' | claude -p --disallowedTools "<comma-separated names>"`;
|
|
49
|
+
|
|
50
|
+
/** Names the CLI resolved to a tool. Re-take with the command above. */
|
|
51
|
+
export const VERIFIED_KNOWN_TOOLS: ReadonlySet<string> = new Set([
|
|
52
|
+
"Agent",
|
|
53
|
+
"AskUserQuestion",
|
|
54
|
+
"Bash",
|
|
55
|
+
"BashOutput",
|
|
56
|
+
"Edit",
|
|
57
|
+
"EnterPlanMode",
|
|
58
|
+
"ExitPlanMode",
|
|
59
|
+
"Glob",
|
|
60
|
+
"Grep",
|
|
61
|
+
"KillShell",
|
|
62
|
+
"ListAgents",
|
|
63
|
+
"ListMcpResources",
|
|
64
|
+
"Monitor",
|
|
65
|
+
"NotebookEdit",
|
|
66
|
+
"Read",
|
|
67
|
+
"ReadMcpResource",
|
|
68
|
+
"ReportFindings",
|
|
69
|
+
"ScheduleWakeup",
|
|
70
|
+
"SendMessage",
|
|
71
|
+
"Skill",
|
|
72
|
+
"Task",
|
|
73
|
+
"TaskList",
|
|
74
|
+
"TaskStop",
|
|
75
|
+
"TodoWrite",
|
|
76
|
+
"ToolSearch",
|
|
77
|
+
"WebFetch",
|
|
78
|
+
"WebSearch",
|
|
79
|
+
"Workflow",
|
|
80
|
+
"Write",
|
|
81
|
+
]);
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* Names the CLI resolved to NOTHING, kept as data rather than deleted.
|
|
85
|
+
*
|
|
86
|
+
* This is the negative control the check needs, built from real readings
|
|
87
|
+
* instead of a synthetic typo: "every name is known" passes over an empty
|
|
88
|
+
* list, and a control made of names nobody writes proves only that the
|
|
89
|
+
* comparison runs. These are names this project or its history actually used.
|
|
90
|
+
*
|
|
91
|
+
* `NotebookRead` and `LS` are retired tools, probed as controls alongside the
|
|
92
|
+
* two the issue is about.
|
|
93
|
+
*/
|
|
94
|
+
export const VERIFIED_UNKNOWN_TOOLS: ReadonlySet<string> = new Set([
|
|
95
|
+
"LS",
|
|
96
|
+
"MultiEdit",
|
|
97
|
+
"NotebookRead",
|
|
98
|
+
"SlashCommand",
|
|
99
|
+
]);
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* The tool a permission rule names, with any path spec removed.
|
|
103
|
+
*
|
|
104
|
+
* `Edit(./**)` is a rule about the `Edit` tool, and the CLI resolves the tool
|
|
105
|
+
* name before it looks at the pattern. A check that compared the whole rule
|
|
106
|
+
* text to the vocabulary would report every path-scoped rule as unknown — a
|
|
107
|
+
* detector narrower than what it detects, arriving as a flood of false
|
|
108
|
+
* positives rather than as silence.
|
|
109
|
+
*/
|
|
110
|
+
export function ruleToolName(rule: string): string {
|
|
111
|
+
const open = rule.indexOf("(");
|
|
112
|
+
return (open === -1 ? rule : rule.slice(0, open)).trim();
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* The names in `rules` that the record does not vouch for, in order.
|
|
117
|
+
*
|
|
118
|
+
* One binding, so there is one thing to mutate. A name is vouched for only by
|
|
119
|
+
* `VERIFIED_KNOWN_TOOLS`: membership of `VERIFIED_UNKNOWN_TOOLS` is NOT an
|
|
120
|
+
* exemption, it is the record saying the opposite. The caller that keeps an
|
|
121
|
+
* inert rule on purpose declares it where it keeps it, and says why.
|
|
122
|
+
*/
|
|
123
|
+
export function unknownAgainstRecord(rules: readonly string[]): string[] {
|
|
124
|
+
return rules.map(ruleToolName).filter(name => !VERIFIED_KNOWN_TOOLS.has(name));
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** Every name the CLI complained about, in the order it complained. */
|
|
128
|
+
export function parseUnknownRuleWarnings(output: string): string[] {
|
|
129
|
+
const out: string[] = [];
|
|
130
|
+
for (const m of output.matchAll(/rule "([^"]+)" matches no known tool/g)) out.push(m[1]!);
|
|
131
|
+
return out;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
export interface PermissionRuleProbe {
|
|
135
|
+
/** `MEASURED` only when a CLI ran and validated the rules. */
|
|
136
|
+
reading: "MEASURED" | "UNMEASURED";
|
|
137
|
+
/** Names this CLI did not recognise. Empty and meaningless when UNMEASURED. */
|
|
138
|
+
unknown: string[];
|
|
139
|
+
probe: ToolProbe;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Ask the installed CLI which of `rules` it does not know.
|
|
144
|
+
*
|
|
145
|
+
* Takes no network: the CLI validates the rules, then refuses the empty prompt
|
|
146
|
+
* and exits. A tree with no `claude` on PATH reads `UNMEASURED` — not an empty
|
|
147
|
+
* `unknown` list, which is what a passing probe looks like.
|
|
148
|
+
*/
|
|
149
|
+
export function probePermissionRules(
|
|
150
|
+
rules: readonly string[],
|
|
151
|
+
opts?: { timeoutMs?: number; command?: string },
|
|
152
|
+
): PermissionRuleProbe {
|
|
153
|
+
const command = opts?.command ?? "claude";
|
|
154
|
+
const present = probeExternalTool(command, ["--version"], opts);
|
|
155
|
+
if (!present.available) return { reading: "UNMEASURED", unknown: [], probe: present };
|
|
156
|
+
|
|
157
|
+
const joined = rules.join(",");
|
|
158
|
+
let output: string;
|
|
159
|
+
try {
|
|
160
|
+
const r = Bun.spawnSync([command, "-p", "--disallowedTools", joined], {
|
|
161
|
+
stdin: new Blob([""]),
|
|
162
|
+
stdout: "pipe",
|
|
163
|
+
stderr: "pipe",
|
|
164
|
+
timeout: opts?.timeoutMs ?? 30_000,
|
|
165
|
+
});
|
|
166
|
+
output = `${r.stdout?.toString() ?? ""}${r.stderr?.toString() ?? ""}`;
|
|
167
|
+
} catch (e) {
|
|
168
|
+
const message = e instanceof Error ? e.message : String(e);
|
|
169
|
+
return {
|
|
170
|
+
reading: "UNMEASURED",
|
|
171
|
+
unknown: [],
|
|
172
|
+
probe: toolProbe({
|
|
173
|
+
outcome: "errored",
|
|
174
|
+
tool: `${command} -p --disallowedTools`,
|
|
175
|
+
reason: `the rule validation run did not complete: ${message.split("\n")[0]}`,
|
|
176
|
+
}),
|
|
177
|
+
};
|
|
178
|
+
}
|
|
179
|
+
return {
|
|
180
|
+
reading: "MEASURED",
|
|
181
|
+
unknown: parseUnknownRuleWarnings(output),
|
|
182
|
+
probe: toolProbe({
|
|
183
|
+
outcome: "available",
|
|
184
|
+
tool: `${command} -p --disallowedTools`,
|
|
185
|
+
reason: `${command} validated ${rules.length} permission rule(s)`,
|
|
186
|
+
}),
|
|
187
|
+
};
|
|
188
|
+
}
|
package/lib/cli-commands.ts
CHANGED
|
@@ -105,6 +105,21 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
|
|
|
105
105
|
summary: "Extract constraints from a project's docs into agent rules",
|
|
106
106
|
usage: "rungate extract-constraints",
|
|
107
107
|
},
|
|
108
|
+
// Registered so the GENERATED ai-review workflow has something to run. The
|
|
109
|
+
// reader has existed and been tested since #631 and nothing executed it:
|
|
110
|
+
// `lib/scaffold/ai-review-step.ts` emitted a warning saying so by name,
|
|
111
|
+
// because a scaffolded consumer has no copy of rungate's sources at a path
|
|
112
|
+
// the workflow could hardcode. This registry is the path (#675).
|
|
113
|
+
//
|
|
114
|
+
// No `projectRootFlag`: the argument is the findings payload, which lives
|
|
115
|
+
// outside the checkout by design (`RUNNER_TEMP`), and appending
|
|
116
|
+
// `--project-root <cwd>` would arrive as a second positional and be read as
|
|
117
|
+
// a second payload.
|
|
118
|
+
"ai-review-findings": {
|
|
119
|
+
script: "scripts/ai-review-findings.ts",
|
|
120
|
+
summary: "Adjudicate an AI review's findings payload — exits non-zero on a blocking finding",
|
|
121
|
+
usage: "rungate ai-review-findings <path-to-findings.json>",
|
|
122
|
+
},
|
|
108
123
|
};
|
|
109
124
|
|
|
110
125
|
/** The commands the AGENTS.md generator may publish to a consumer. */
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a commit SHA looks like, in ONE place (#602).
|
|
3
|
+
*
|
|
4
|
+
* `gates/schema.ts` has carried this pattern since #224 to keep a ref name
|
|
5
|
+
* out of `suiteMeasurement.measuredSha` — the field that says which tree a
|
|
6
|
+
* suite verdict is about. #602 adds a second field with the same job for
|
|
7
|
+
* the harness that did the grading, and a second copy of the pattern would
|
|
8
|
+
* be two deciders for one question: they would agree today, a mutation of
|
|
9
|
+
* either would leave the other refusing, and no behavioural test could
|
|
10
|
+
* tell them apart (`.claude/rules/checks-must-be-able-to-fail.md`, the
|
|
11
|
+
* fourth shape).
|
|
12
|
+
*
|
|
13
|
+
* It lives in `lib/` and not in `gates/` because the dependency runs that
|
|
14
|
+
* way: `gates/schema.ts` already imports from `lib/`, and `lib/` importing
|
|
15
|
+
* back would be a cycle.
|
|
16
|
+
*
|
|
17
|
+
* ## Why 7 and not 40
|
|
18
|
+
*
|
|
19
|
+
* `git rev-parse --short` is the form a human pastes and the form several
|
|
20
|
+
* scripts in this tree print. Demanding 40 would refuse readings that are
|
|
21
|
+
* correct, and a refusal that fires on correct input is the fastest way to
|
|
22
|
+
* build one everybody learns to work around. The thing being excluded is a
|
|
23
|
+
* REF NAME — `main`, `HEAD`, `origin/main`, `rungate/run-602` — because a
|
|
24
|
+
* ref is a pointer and the whole point of recording a SHA is that it still
|
|
25
|
+
* names the same tree tomorrow.
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
/** A commit SHA, short or full. Anchored at both ends: a ref name containing hex is not one. */
|
|
29
|
+
export const COMMIT_SHA = /^[0-9a-f]{7,40}$/i;
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Is this string a commit SHA?
|
|
33
|
+
*
|
|
34
|
+
* Exported beside the pattern so a caller never has to spell `.test()`
|
|
35
|
+
* against a shared `RegExp`. `COMMIT_SHA` carries no `g` flag, so it is
|
|
36
|
+
* stateless and safe to share — a `g` flag would make `lastIndex` persist
|
|
37
|
+
* across callers and produce alternating answers for one input, which is a
|
|
38
|
+
* check that cannot fail every other time it is asked.
|
|
39
|
+
*/
|
|
40
|
+
export function isCommitSha(value: unknown): value is string {
|
|
41
|
+
return typeof value === "string" && COMMIT_SHA.test(value);
|
|
42
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The commit subject a ship run writes, composed from an UNTRUSTED issue title.
|
|
3
|
+
*
|
|
4
|
+
* An issue title is picked by whoever filed the issue. It reaches a commit
|
|
5
|
+
* message in two positions — `workflows/ship.js`'s COMMIT phase, and
|
|
6
|
+
* `scripts/github-op.ts --title-from-issue`, whose PR title becomes the
|
|
7
|
+
* squash-merge subject — and both of them land that text on `main`.
|
|
8
|
+
*
|
|
9
|
+
* GitHub closes an issue when a merged commit message contains a closing
|
|
10
|
+
* keyword next to an issue reference, and **it does not care about markdown**.
|
|
11
|
+
* On 2026-10-19 commit `cfc1415d` quoted ``Fixes #644`` inside a backtick code
|
|
12
|
+
* span, as a SAMPLE INPUT in a message explaining this very class of bug, and
|
|
13
|
+
* #644 was closed three seconds after the merge. Backticks are not an escape;
|
|
14
|
+
* neither are quotes, parentheses or a code fence.
|
|
15
|
+
*
|
|
16
|
+
* So the title is neutralised here, in one binding, and `workflows/ship.js`
|
|
17
|
+
* carries an inline copy only because a workflow script cannot import (#69) —
|
|
18
|
+
* `test/commit-subject-quoting.test.ts` lifts that copy out and asserts the
|
|
19
|
+
* two agree over every fixture, so they are one decider with a comparator
|
|
20
|
+
* rather than two that silently diverge (#621).
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* GitHub's closing syntax: one of nine keywords, a colon or whitespace, then
|
|
25
|
+
* an issue reference in any of the four forms GitHub resolves — `#N`, `GH-N`,
|
|
26
|
+
* `owner/repo#N`, and a `github.com/owner/repo/(issues|pull)/N` URL.
|
|
27
|
+
*
|
|
28
|
+
* **This is deliberately a SECOND spelling of the grammar in
|
|
29
|
+
* `scripts/check-state-record-closes.ts`, not a shared literal.** That script
|
|
30
|
+
* detects closing references in a session record (#590, filed after
|
|
31
|
+
* `Filed and not fixed: #586` closed #586 one second after a merge); this
|
|
32
|
+
* neutralises them. They are exact duals, so sharing a regex literal would
|
|
33
|
+
* make a mutation of the grammar move both and leave the comparison green —
|
|
34
|
+
* two deciders that agree (`.claude/rules/checks-must-be-able-to-fail.md`,
|
|
35
|
+
* fourth shape). Instead the two are compared over a corpus, with the
|
|
36
|
+
* detector as the oracle, in `test/commit-subject-quoting.test.ts`.
|
|
37
|
+
*
|
|
38
|
+
* The script cannot be the owner either: `test/state-record-closes-mutation.ts`
|
|
39
|
+
* runs a mutant copy of it from a temp directory, and that only works while it
|
|
40
|
+
* has no relative imports. Same shape as #69 forcing ship.js's copy — the
|
|
41
|
+
* duplication is structural, so the answer is a comparator.
|
|
42
|
+
*
|
|
43
|
+
* Three details come from that grammar rather than from first principles, and
|
|
44
|
+
* each was wrong in this file's first draft:
|
|
45
|
+
*
|
|
46
|
+
* - `\b` AFTER the stem, so `closing #586` is not a keyword.
|
|
47
|
+
* - `\s*:\s*` as an alternative to `\s+`, because `fixed:#586` with no
|
|
48
|
+
* space is the form that shipped #586's defect.
|
|
49
|
+
* - the URL pinned to `github.com` and to `issues|pull`, where the first
|
|
50
|
+
* draft had `https?://\S*?/issues/` and would have mangled a link to any
|
|
51
|
+
* other tracker.
|
|
52
|
+
*
|
|
53
|
+
* The capture ends at the character before the digits so the fix can insert a
|
|
54
|
+
* space there, and the digits are a lookahead rather than consumed, so a
|
|
55
|
+
* reference is never truncated.
|
|
56
|
+
*/
|
|
57
|
+
const SLUG = "[A-Za-z0-9][A-Za-z0-9._-]*\\/[A-Za-z0-9][A-Za-z0-9._-]*";
|
|
58
|
+
export const CLOSING_REFERENCE = new RegExp(
|
|
59
|
+
`\\b(close[sd]?|fix(?:e[sd])?|resolve[sd]?)\\b(\\s*:\\s*|\\s+)` +
|
|
60
|
+
`((?:${SLUG})?#|GH-|https?:\\/\\/github\\.com\\/${SLUG}\\/(?:issues|pull)\\/)(?=\\d)`,
|
|
61
|
+
"gi",
|
|
62
|
+
);
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Break the adjacency GitHub parses, leaving the keyword and the number both
|
|
66
|
+
* readable.
|
|
67
|
+
*
|
|
68
|
+
* Breaking the adjacency rather than deleting anything is deliberate: this
|
|
69
|
+
* runs over a human's issue title, and a subject line with the number redacted
|
|
70
|
+
* is worse to read than one with a space in it. `fixes #500` becomes
|
|
71
|
+
* `fixes # 500`, which links nothing and says the same thing.
|
|
72
|
+
*/
|
|
73
|
+
export function neutraliseClosingKeywords(text: unknown): string {
|
|
74
|
+
return String(text ?? "").replace(CLOSING_REFERENCE, "$1$2$3 ");
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* `fix(#N): <neutralised title>`.
|
|
79
|
+
*
|
|
80
|
+
* The run's OWN `fix(#N):` prefix is composed after the transform and is
|
|
81
|
+
* deliberately untouched — that reference is the one this commit means, and
|
|
82
|
+
* neutralising it would break the link between every ship commit and its
|
|
83
|
+
* issue.
|
|
84
|
+
*/
|
|
85
|
+
export function commitSubject(issue: number, title: unknown): string {
|
|
86
|
+
if (!Number.isInteger(issue) || issue <= 0) {
|
|
87
|
+
throw new TypeError(`commitSubject needs a positive integer issue number, got ${JSON.stringify(issue)}`);
|
|
88
|
+
}
|
|
89
|
+
return `fix(#${issue}): ${neutraliseClosingKeywords(title)}`;
|
|
90
|
+
}
|