* chore(#2896): convert CONTEXT.md prose defect registry into enforced gates Squashes the prior 4-commit sequence and fixes defects found while resuming this branch: 5 orphaned/corrupted DEFECT fragment lines left by an earlier botched edit, 17 "Source of truth: Memtrace `find_symbol`" placeholders that had destroyed real file-path citations, and 3 DEFECT.GENERATIVE-* entries merged into one RULESET.GENERATIVE-FIX predicate (policy, not an unenforced defect) to satisfy the zero DEFECT.<NAME>.<field>= acceptance criterion. Six mechanizable defects get real gates: DEFECT.UNBOUNDED-SUBPROCESS (eslint-rules/require-subprocess-timeout.cjs), DEFECT.CANARY-VERSION-LEAK (scripts/lint-canary-version-leak.cjs + version-gate.yml), DEFECT.CHANGESET-PR-FIELD-DRIFT (findPrFieldDrift in changeset/lint.cjs), DEFECT.FRONTMATTER-SCALAR-BROAD-GREP, DEFECT.REMOVED-BUT-NEEDED, and DEFECT.DEFAULT-FLIP-DOCUMENTATION (new lint scripts, wired into lint:ci). Already-enforced and unenforceable prose entries are deleted; the gate is the record. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * chore(#2896): route the new lint tests' subprocess calls through the bounded process-seam helper The 4 new test files for this PR's lint checks called cp.spawnSync/ execFileSync directly with no timeout, tripping this repo's own existing local/no-unbounded-spawn ESLint rule. Route every one through runNode/gitOrThrow (tests/helpers/process-seam.cjs, tests/helpers/git-fixture.cjs) instead, matching the pattern already used elsewhere in the suite (e.g. tests/changeset-lint.test.cjs). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix: register claude-orchestration.cjs and regenerate stale generated indexes Pre-existing drift on next, unrelated to this PR's own change, surfaced by running lint:ci as part of verifying #2896: two cli_modules (claude-orchestration.cjs, write-set.cjs) landed without a manifest regen, and CONTEXT.md's own edits in this PR staled its two generated indexes. Adds the missing docs/INVENTORY.md row for claude-orchestration.cjs (write-set.cjs already had one — only its manifest entry was stale) and regenerates docs/INVENTORY-MANIFEST.json, docs/CONTEXT-INDEX.json, and examples/dynamic-context-management/CONTEXT-INDEX.json. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(#2896): default-flip-documentation lint's local fallback base was main, not next Found in review: every other base-ref fallback in this repo (see scripts/changeset/lint.cjs's DEFAULT_BASE, #2988) defaults to `next`, the integration branch every PR actually targets — `main` is the release branch. This script's local fallback (used only when GITHUB_BASE_REF is unset, i.e. never in CI, but potentially on a local or direct invocation) diffed against the wrong ref. No test exercised the unset-env-var path, so it shipped unnoticed; every e2e test sets GITHUB_BASE_REF explicitly and is unaffected by this fix. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(#2896): stale eslint comment, overclaiming CONTEXT.md wording, and an incompletely-regenerated manifest Found by the isolated Standards code-review pass: - eslint.config.mjs's require-subprocess-timeout comment said "'warn' for now... flip to 'error' once migrated" while the rule already shipped as 'error' with all 8 sites migrated in the same commit — described a state that never existed. - The CONTEXT.md pointer block claimed the rule's bounded call sites "never throw", but roadmap-upgrade.cts's pre-mutation clean-tree check correctly still throws on failure (it gates a destructive real-run migration; degrading to "assume clean" would risk clobbering uncommitted work) — softened the claim to describe both shapes accurately instead of overclaiming one. - docs/INVENTORY-MANIFEST.json's claude-orchestration.cjs/write-set.cjs entries from the prior "fix: register claude-orchestration.cjs..." commit didn't actually land — re-running the generator now includes them; lint:generated-sync is green. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * chore(#2896): backfill changeset pr field with the real PR number Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(#2896): normalize buildCorpus file paths to POSIX in lint-removed-but-needed Windows CI caught it: path.relative(root, abs) returns backslash- separated paths on Windows, but findSurvivingReferences's package-lock special case does file.startsWith('.github/workflows') — a forward- slash literal. On Windows the check silently never matched, so tests/removed-but-needed-lint.test.cjs's real-defect-shape fixture got exit 0 instead of the expected exit 1. Normalize at the production source (RULESET.CONTENT-PATH-NORMALIZATION) rather than the test side. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
@@ -22,6 +22,7 @@ const LINT_REASON = Object.freeze({
|
||||
OK_NO_USER_FACING_CHANGES: 'ok_no_user_facing_changes',
|
||||
FAIL_MISSING_FRAGMENT: 'fail_missing_fragment',
|
||||
FAIL_INVALID_FRAGMENT: 'fail_invalid_fragment',
|
||||
FAIL_PR_FIELD_DRIFT: 'fail_pr_field_drift',
|
||||
});
|
||||
|
||||
const OPT_OUT_LABEL = 'no-changelog';
|
||||
@@ -53,10 +54,47 @@ function isFragment(file) {
|
||||
return /^\.changeset\/[^/]+\.md$/.test(file) && !file.endsWith('/README.md');
|
||||
}
|
||||
|
||||
function evaluateLint({ changedFiles, labels, fragmentFailures = [] }) {
|
||||
/**
|
||||
* DEFECT.CHANGESET-PR-FIELD-DRIFT (#3316, #3325): a fragment's `pr:` field is
|
||||
* a guess (issue number, stacked-PR leftover) that never got backfilled to
|
||||
* the real PR number after `gh api POST /pulls` returned it.
|
||||
*
|
||||
* Pure: given `prEntries` (`[{ file, pr }]`, one entry per successfully
|
||||
* parsed changed fragment — `pr` is always a positive integer, since
|
||||
* `parseFragment` already rejects `pr: 0` / non-numeric values as
|
||||
* `invalid_pr` before a fragment ever reaches this function) and
|
||||
* `realPrNumber` (the PR this run belongs to, or `null` when unknown —
|
||||
* push/non-PR runs), returns every fragment whose `pr` disagrees with
|
||||
* `realPrNumber`. `realPrNumber == null` always yields `[]`: with no PR
|
||||
* event payload to compare against, there is nothing to drift-check.
|
||||
*
|
||||
* `pr === 0` is always silent regardless of `realPrNumber` — CONTRIBUTING.md
|
||||
* documents `pr: 0` as the deliberate placeholder used "during initial
|
||||
* commit" before `gh api POST /pulls` returns the real number, so it is not
|
||||
* yet a drifted value, just an unbackfilled one. (In practice `parseFragment`
|
||||
* already rejects `pr: 0` as `invalid_pr` before a fragment reaches this
|
||||
* function via `main()`'s wiring — this guard documents and locks in the
|
||||
* pure function's own contract independent of that upstream check.)
|
||||
*/
|
||||
function findPrFieldDrift(prEntries, realPrNumber) {
|
||||
if (realPrNumber == null) return [];
|
||||
const drift = [];
|
||||
for (const { file, pr } of prEntries) {
|
||||
if (pr === 0) continue;
|
||||
if (pr !== realPrNumber) {
|
||||
drift.push({ file, found: pr, expected: realPrNumber });
|
||||
}
|
||||
}
|
||||
return drift;
|
||||
}
|
||||
|
||||
function evaluateLint({ changedFiles, labels, fragmentFailures = [], prFieldDrift = [] }) {
|
||||
if (fragmentFailures.length > 0) {
|
||||
return { ok: false, reason: LINT_REASON.FAIL_INVALID_FRAGMENT, failures: fragmentFailures };
|
||||
}
|
||||
if (prFieldDrift.length > 0) {
|
||||
return { ok: false, reason: LINT_REASON.FAIL_PR_FIELD_DRIFT, drift: prFieldDrift };
|
||||
}
|
||||
if (changedFiles.some(isFragment)) {
|
||||
return { ok: true, reason: LINT_REASON.OK_FRAGMENT_PRESENT };
|
||||
}
|
||||
@@ -78,10 +116,18 @@ function main() {
|
||||
// GitHub Actions event payload path
|
||||
const eventPath = process.env.GITHUB_EVENT_PATH;
|
||||
let labels = [];
|
||||
// DEFECT.CHANGESET-PR-FIELD-DRIFT: the real PR number this run belongs to,
|
||||
// read from the same event payload. `null` on a push / non-PR run (no
|
||||
// `pull_request` in the payload, or no payload at all) — the drift check
|
||||
// below is a no-op in that case, it never fails a push run.
|
||||
let realPrNumber = null;
|
||||
if (eventPath && fs.existsSync(eventPath)) {
|
||||
try {
|
||||
const event = JSON.parse(fs.readFileSync(eventPath, 'utf8'));
|
||||
labels = (event.pull_request?.labels || []).map((l) => l.name);
|
||||
if (event.pull_request && Number.isInteger(event.pull_request.number)) {
|
||||
realPrNumber = event.pull_request.number;
|
||||
}
|
||||
} catch { /* fall through */ }
|
||||
}
|
||||
// #2988: local fallback must match the repo's integration branch (`next`),
|
||||
@@ -107,6 +153,7 @@ function main() {
|
||||
|
||||
// Validate the content of every changed fragment file.
|
||||
const fragmentFailures = [];
|
||||
const prEntries = [];
|
||||
for (const file of changedFiles) {
|
||||
if (!isFragment(file)) continue;
|
||||
// A fragment path in the diff that no longer exists on disk was deleted in
|
||||
@@ -125,10 +172,13 @@ function main() {
|
||||
const result = parseFragment(src);
|
||||
if (!result.ok) {
|
||||
fragmentFailures.push({ file, reason: result.reason, detail: result.detail });
|
||||
continue;
|
||||
}
|
||||
prEntries.push({ file, pr: result.fragment.pr });
|
||||
}
|
||||
|
||||
const verdict = evaluateLint({ changedFiles, labels, fragmentFailures });
|
||||
const prFieldDrift = findPrFieldDrift(prEntries, realPrNumber);
|
||||
const verdict = evaluateLint({ changedFiles, labels, fragmentFailures, prFieldDrift });
|
||||
if (process.argv.includes('--json')) {
|
||||
process.stdout.write(JSON.stringify({ ...verdict, changedFiles, labels }, null, 2) + '\n');
|
||||
} else if (verdict.ok) {
|
||||
@@ -141,6 +191,13 @@ function main() {
|
||||
process.stderr.write(` ${f.file}: ${f.reason}${detail}\n`);
|
||||
}
|
||||
process.stderr.write(`Fix the fragment(s) above before merging.\n`);
|
||||
} else if (verdict.reason === LINT_REASON.FAIL_PR_FIELD_DRIFT) {
|
||||
process.stderr.write(`\nERROR changeset-lint: ${verdict.reason}\n`);
|
||||
process.stderr.write(`The following .changeset fragment(s) have a stale \`pr:\` field (DEFECT.CHANGESET-PR-FIELD-DRIFT):\n`);
|
||||
for (const d of verdict.drift) {
|
||||
process.stderr.write(` ${d.file}: pr: ${d.found}, expected pr: ${d.expected}\n`);
|
||||
}
|
||||
process.stderr.write(`Backfill \`pr:\` with this PR's real number (see .changeset/README.md), then push again.\n`);
|
||||
} else {
|
||||
process.stderr.write(`\nERROR changeset-lint: ${verdict.reason}\n`);
|
||||
process.stderr.write(`PR touches user-facing files but does not include a .changeset/*.md fragment.\n`);
|
||||
@@ -152,4 +209,4 @@ function main() {
|
||||
|
||||
if (require.main === module) runMain(main);
|
||||
|
||||
module.exports = { evaluateLint, LINT_REASON, OPT_OUT_LABEL, isUserFacing, isFragment, DEFAULT_BASE };
|
||||
module.exports = { evaluateLint, LINT_REASON, OPT_OUT_LABEL, isUserFacing, isFragment, DEFAULT_BASE, findPrFieldDrift };
|
||||
|
||||
73
scripts/lint-canary-version-leak.cjs
Normal file
73
scripts/lint-canary-version-leak.cjs
Normal file
@@ -0,0 +1,73 @@
|
||||
#!/usr/bin/env node
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* Canary-version-leak lint (DEFECT.CANARY-VERSION-LEAK, CONTEXT.md).
|
||||
*
|
||||
* `package.json` `.version` on `main` must never carry a `-canary.<N>`
|
||||
* suffix — that suffix is a dev-branch/prerelease marker. Nothing published
|
||||
* depends on the string at runtime, but every consumer of the version
|
||||
* metadata (release flow, install banners, statusline) surfaces the
|
||||
* dev-channel label as if it were the shipped release. The 2026-05-16 audit
|
||||
* found `origin/main` at `"version": "1.50.0-canary.0"`, landed by a fix PR
|
||||
* that accidentally carried a version bump from a dev-branch base (commit
|
||||
* 2d32ad82, #3206).
|
||||
*
|
||||
* Modeled on scripts/lint-package-identity-drift.cjs / scripts/lint-table-schema-drift.cjs:
|
||||
* a standalone node script (not a node:test), exit 0 clean / exit 1 + message
|
||||
* on a leaked canary version. Wired to run only for PRs targeting `main`
|
||||
* (.github/workflows/version-gate.yml) — a canary version is expected and
|
||||
* harmless on every other branch.
|
||||
*/
|
||||
|
||||
const fs = require('node:fs');
|
||||
const path = require('node:path');
|
||||
|
||||
const CANARY_RE = /-canary\.\d+/;
|
||||
|
||||
/**
|
||||
* Pure: does this version string carry a `-canary.<N>` suffix?
|
||||
* @param {string} version
|
||||
* @returns {boolean}
|
||||
*/
|
||||
function isCanaryVersion(version) {
|
||||
return typeof version === 'string' && CANARY_RE.test(version);
|
||||
}
|
||||
|
||||
/**
|
||||
* Read `<root>/package.json` and return its `.version`, or null if the file
|
||||
* is missing/unreadable/unparsable.
|
||||
* @param {string} root
|
||||
* @returns {string|null}
|
||||
*/
|
||||
function readPackageVersion(root) {
|
||||
try {
|
||||
const raw = fs.readFileSync(path.join(root, 'package.json'), 'utf8');
|
||||
const pkg = JSON.parse(raw);
|
||||
return typeof pkg.version === 'string' ? pkg.version : null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function main() {
|
||||
const root = path.join(__dirname, '..');
|
||||
const version = readPackageVersion(root);
|
||||
if (version == null) {
|
||||
process.stderr.write('canary-version-leak: could not read/parse package.json .version\n');
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
if (!isCanaryVersion(version)) {
|
||||
process.stdout.write(`ok canary-version-leak: package.json version '${version}' carries no -canary.<N> suffix\n`);
|
||||
return;
|
||||
}
|
||||
process.stderr.write(`canary-version-leak: package.json version '${version}' carries a -canary.<N> suffix (DEFECT.CANARY-VERSION-LEAK).\n`);
|
||||
process.stderr.write('A -canary.<N> version must never land on main. Reset .version to the canonical\n');
|
||||
process.stderr.write('pre-canary stable before merging — see CONTEXT.md DEFECT.CANARY-VERSION-LEAK.\n');
|
||||
process.exitCode = 1;
|
||||
}
|
||||
|
||||
if (require.main === module) main();
|
||||
|
||||
module.exports = { isCanaryVersion, readPackageVersion, CANARY_RE };
|
||||
193
scripts/lint-default-flip-documentation.cjs
Normal file
193
scripts/lint-default-flip-documentation.cjs
Normal file
@@ -0,0 +1,193 @@
|
||||
#!/usr/bin/env node
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* lint-default-flip-documentation.cjs — DEFECT.DEFAULT-FLIP-DOCUMENTATION
|
||||
* (CONTEXT.md).
|
||||
*
|
||||
* ## Why
|
||||
*
|
||||
* A PR flips a config default but doesn't call out the migration semantics
|
||||
* (when the new default takes effect; existing configs vs new configs; what
|
||||
* the opt-back-in looks like — #3309, the v2 default flip from mid-flight to
|
||||
* end-of-phase).
|
||||
*
|
||||
* ## Scope (deliberately narrower than the full DEFECT.detect clause)
|
||||
*
|
||||
* The DEFECT text names two surfaces: `CONFIG_DEFAULTS` and
|
||||
* `buildNewProjectConfig`. This check covers ONLY the single-source-of-truth
|
||||
* defaults manifest, `gsd-core/bin/shared/config-defaults.manifest.json`
|
||||
* (what `CONFIG_DEFAULTS` in `src/configuration.cts` / `src/config.cts`
|
||||
* actually loads at runtime) — because it is pure JSON, a resolved
|
||||
* key→value-map diff between base and head is trivially reliable: no line
|
||||
* movement, reordering, or refactor can ever produce a false "value changed"
|
||||
* verdict, only an actual value change can.
|
||||
*
|
||||
* `buildNewProjectConfig`'s `hardcoded` object literal in `src/config.cts`
|
||||
* is DELIBERATELY OUT OF SCOPE here. It mixes literal values with
|
||||
* environment-derived branches (`hasBraveSearch`, etc.) and spreads of
|
||||
* `CONFIG_DEFAULTS.*` — there is no reliable way to compute its *resolved*
|
||||
* value map from source text alone without executing the compiled module at
|
||||
* both refs, and a line/AST-level diff of that literal would inherit exactly
|
||||
* the false-positive risk (a harmless refactor that moves or restructures
|
||||
* the literal reads as a "flip") this check exists to avoid. Per the audit's
|
||||
* own risk callout, a noisy check here is worse than no check — the
|
||||
* `buildNewProjectConfig` half of the DEFECT stays prose-only.
|
||||
*
|
||||
* ## What this checks
|
||||
*
|
||||
* If any *value* differs between the base and head resolved manifest
|
||||
* key→value maps (additions/removals alone don't count as a "flip" — the
|
||||
* symptom is specifically about an EXISTING default changing), fail unless
|
||||
* the PR body contains a `## Breaking Changes` (or `# Breaking Changes`)
|
||||
* heading.
|
||||
*
|
||||
* Needs a PR event payload (`GITHUB_EVENT_PATH`) to read the PR body — this
|
||||
* is a dedicated-workflow check (like `lint-canary-version-leak.cjs`), not a
|
||||
* `lint:ci` member, since a local/push run has no PR body to check against.
|
||||
*/
|
||||
|
||||
const fs = require('node:fs');
|
||||
const path = require('node:path');
|
||||
const cp = require('node:child_process');
|
||||
const { ExitError, runMain } = require('./lib/cli-exit.cjs');
|
||||
|
||||
const ROOT = path.join(__dirname, '..');
|
||||
const MANIFEST_PATH = path.join('gsd-core', 'bin', 'shared', 'config-defaults.manifest.json');
|
||||
const BREAKING_CHANGES_RE = /^#{1,6}\s*Breaking Changes\b/im;
|
||||
|
||||
/**
|
||||
* Pure: flatten a nested plain-object JSON value into dot-path
|
||||
* `{ "a.b.c": value }` leaves. Arrays and primitives are leaves (compared by
|
||||
* JSON.stringify equality, never recursed into) so array reordering reads as
|
||||
* one value change, not N.
|
||||
* @param {unknown} value
|
||||
* @param {string} prefix
|
||||
* @param {Record<string, unknown>} out
|
||||
* @returns {Record<string, unknown>}
|
||||
*/
|
||||
function flatten(value, prefix = '', out = {}) {
|
||||
if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
|
||||
for (const [key, v] of Object.entries(value)) {
|
||||
flatten(v, prefix ? `${prefix}.${key}` : key, out);
|
||||
}
|
||||
} else {
|
||||
out[prefix] = value;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Pure: given two resolved (already-flattened) key→value maps, return the
|
||||
* keys present in BOTH whose value differs. Additions/removals are NOT
|
||||
* "flips" — a brand-new default has no prior behavior to contradict.
|
||||
* @param {Record<string, unknown>} baseMap
|
||||
* @param {Record<string, unknown>} headMap
|
||||
* @returns {{ key: string, from: unknown, to: unknown }[]}
|
||||
*/
|
||||
function findDefaultValueChanges(baseMap, headMap) {
|
||||
const changes = [];
|
||||
for (const key of Object.keys(baseMap)) {
|
||||
if (!Object.prototype.hasOwnProperty.call(headMap, key)) continue;
|
||||
if (JSON.stringify(baseMap[key]) !== JSON.stringify(headMap[key])) {
|
||||
changes.push({ key, from: baseMap[key], to: headMap[key] });
|
||||
}
|
||||
}
|
||||
return changes;
|
||||
}
|
||||
|
||||
/**
|
||||
* Pure verdict: given the detected default-value changes and the PR body,
|
||||
* decide pass/fail.
|
||||
* @param {{ key: string, from: unknown, to: unknown }[]} changes
|
||||
* @param {string} prBody
|
||||
* @returns {{ ok: boolean, changes: object[] }}
|
||||
*/
|
||||
function evaluateDefaultFlipDoc(changes, prBody) {
|
||||
if (changes.length === 0) return { ok: true, changes: [] };
|
||||
if (BREAKING_CHANGES_RE.test(prBody || '')) return { ok: true, changes };
|
||||
return { ok: false, changes };
|
||||
}
|
||||
|
||||
/**
|
||||
* Read and JSON.parse the manifest at a given git ref. Returns `{}` when the
|
||||
* file doesn't exist at that ref (new file, or ref predates it) — that is
|
||||
* not a "flip", it's an addition, and is silently excluded by
|
||||
* findDefaultValueChanges's both-sides-present requirement anyway.
|
||||
* @param {string} root
|
||||
* @param {string} ref
|
||||
* @returns {Record<string, unknown>}
|
||||
*/
|
||||
function readManifestAtRef(root, ref) {
|
||||
let raw;
|
||||
try {
|
||||
raw = cp.execFileSync('git', ['show', `${ref}:${MANIFEST_PATH.split(path.sep).join('/')}`], {
|
||||
cwd: root,
|
||||
encoding: 'utf8',
|
||||
timeout: 15000,
|
||||
});
|
||||
} catch {
|
||||
return {};
|
||||
}
|
||||
try {
|
||||
return JSON.parse(raw);
|
||||
} catch (e) {
|
||||
throw new ExitError(2, `lint-default-flip-documentation: ${ref}:${MANIFEST_PATH} is not valid JSON: ${e.message}`);
|
||||
}
|
||||
}
|
||||
|
||||
function readPrBody() {
|
||||
const eventPath = process.env.GITHUB_EVENT_PATH;
|
||||
if (!eventPath || !fs.existsSync(eventPath)) return null;
|
||||
try {
|
||||
const event = JSON.parse(fs.readFileSync(eventPath, 'utf8'));
|
||||
return typeof event.pull_request?.body === 'string' ? event.pull_request.body : '';
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function main() {
|
||||
const prBody = readPrBody();
|
||||
if (prBody === null) {
|
||||
console.log('lint-default-flip-documentation: no PR event payload (not a pull_request run), skipping');
|
||||
return;
|
||||
}
|
||||
|
||||
const baseRef = `origin/${process.env.GITHUB_BASE_REF || 'next'}`; // #2988
|
||||
const baseMap = flatten(readManifestAtRef(ROOT, baseRef));
|
||||
const headMap = flatten(readManifestAtRef(ROOT, 'HEAD'));
|
||||
const changes = findDefaultValueChanges(baseMap, headMap);
|
||||
const verdict = evaluateDefaultFlipDoc(changes, prBody);
|
||||
|
||||
if (!verdict.ok) {
|
||||
const detail = verdict.changes
|
||||
.map((c) => ` ${c.key}: ${JSON.stringify(c.from)} → ${JSON.stringify(c.to)}`)
|
||||
.join('\n');
|
||||
throw new ExitError(
|
||||
1,
|
||||
'lint-default-flip-documentation: this PR changes an existing default value in\n'
|
||||
+ 'config-defaults.manifest.json (DEFECT.DEFAULT-FLIP-DOCUMENTATION) but the PR body has no\n'
|
||||
+ '`## Breaking Changes` section. Add one covering: (a) when the new default takes effect\n'
|
||||
+ '(config-set, fresh project, regenerated config), (b) the opt-back-in command\n'
|
||||
+ '(`gsd config-set <key> <old-value>`), (c) effect on in-flight artifacts. Changed default(s):\n'
|
||||
+ detail,
|
||||
);
|
||||
}
|
||||
console.log(
|
||||
changes.length === 0
|
||||
? 'ok lint-default-flip-documentation: no default value changed'
|
||||
: `ok lint-default-flip-documentation: ${changes.length} default value change(s), PR body documents Breaking Changes`,
|
||||
);
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
flatten,
|
||||
findDefaultValueChanges,
|
||||
evaluateDefaultFlipDoc,
|
||||
readManifestAtRef,
|
||||
MANIFEST_PATH,
|
||||
BREAKING_CHANGES_RE,
|
||||
};
|
||||
|
||||
if (require.main === module) runMain(main);
|
||||
237
scripts/lint-frontmatter-scalar-broad-grep.cjs
Normal file
237
scripts/lint-frontmatter-scalar-broad-grep.cjs
Normal file
@@ -0,0 +1,237 @@
|
||||
#!/usr/bin/env node
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* lint-frontmatter-scalar-broad-grep.cjs — DEFECT.FRONTMATTER-SCALAR-BROAD-GREP
|
||||
* (CONTEXT.md).
|
||||
*
|
||||
* ## Why
|
||||
*
|
||||
* A YAML-frontmatter scalar (e.g. VERIFICATION.md `status:`) read with
|
||||
* `grep "^key:"` over the WHOLE markdown report instead of the frontmatter
|
||||
* block returns extra matches whenever a `key:` line also appears in the
|
||||
* body (a code block, a copied artifact, an example). Piped into
|
||||
* `cut`/`tr`, those extra matches concatenate into a value that matches no
|
||||
* expected token, silently misrouting a valid state (#586/PR #650:
|
||||
* `grep "^status:"` also matched body `status:` lines, yielding
|
||||
* `passed+gaps_found+human_needed` instead of `passed` and blocking a
|
||||
* passed phase).
|
||||
*
|
||||
* The fix-forward is to scope the grep to the leading frontmatter block and
|
||||
* take only the first match:
|
||||
* sed -n '/^---$/,/^---$/p' "$f" | grep -m1 "^<key>:" | cut -d: -f2 | tr -d ' '
|
||||
*
|
||||
* ## What this scans
|
||||
*
|
||||
* Every fenced ```bash / ```sh code block in `gsd-core/workflows/*.md`,
|
||||
* `agents/*.md`, and `commands/**\/*.md`. Within each block, flags a
|
||||
* `grep "^key:"` / `grep '^key:'` invocation that:
|
||||
* - is NOT preceded (earlier in the SAME block) by a frontmatter-scoping
|
||||
* idiom (`sed -n '/^---$/,/^---$/p'`, a JS `/^---\n([\s\S]*?)\n---/`
|
||||
* extraction, or an equivalent range over the `---` delimiter), AND
|
||||
* - does NOT carry a `-m1` (or `-m 1`) flag, and is NOT immediately piped
|
||||
* into `head -1`/`head -n 1` (frontmatter always precedes the body in
|
||||
* these generated reports, so `head -1` on the whole file is the same
|
||||
* single-match guarantee as `-m1`), AND
|
||||
* - is used for exact-token comparison: piped (same line) into
|
||||
* `cut`/`tr`, or captured into a shell variable that is later compared
|
||||
* via `==`/`case` elsewhere in the same block.
|
||||
*
|
||||
* ## False-positive risk (moderate-to-high, per audit)
|
||||
*
|
||||
* Some `grep "^key:"` uses are intentionally whole-body (scanning multiple
|
||||
* report files at once, not one frontmatter block) and are not a bug. Add
|
||||
* `# lint-allow: frontmatter-scalar-broad-grep — <reason>` on the same line
|
||||
* (or the line immediately above) to suppress a specific invocation.
|
||||
*/
|
||||
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
const { ExitError, runMain } = require('./lib/cli-exit.cjs');
|
||||
|
||||
const ROOT = path.join(__dirname, '..');
|
||||
const DEFAULT_ROOTS = ['gsd-core/workflows', 'agents', 'commands'];
|
||||
|
||||
const FENCE_RE = /^```(bash|sh)\s*$/;
|
||||
const FENCE_END_RE = /^```\s*$/;
|
||||
|
||||
// A `grep "^key:"` / `grep '^key:'` invocation. Captures the key name and the
|
||||
// full option string preceding the pattern (so callers can check for -m1).
|
||||
const GREP_KEY_RE = /grep\s+((?:-\S+\s+)*)(["'])\^([A-Za-z_][\w-]*):\2/;
|
||||
|
||||
// A frontmatter-scoping idiom: a delimiter-range extraction anchored on the
|
||||
// `---` frontmatter fence, opened by `^---` (sed/awk `/^---$/,/^---$/p`, or a
|
||||
// JS regex like `/^---\n([\s\S]*?)\n---/`) and closed by a second `---`
|
||||
// within a short window. Matches both idioms without caring which language
|
||||
// wrote the delimiter.
|
||||
const FRONTMATTER_SCOPE_RE = /\^---[\s\S]{0,300}?---/;
|
||||
|
||||
const ALLOW_RE = /#\s*lint-allow:\s*frontmatter-scalar-broad-grep/;
|
||||
|
||||
// `| head -1` / `| head -n 1` immediately after the grep is functionally
|
||||
// equivalent to `-m1` for this check: frontmatter always precedes the body
|
||||
// in these generated reports, so the first grep match is always the
|
||||
// frontmatter's, and `head -1` discards every later (body) match exactly
|
||||
// like `-m1` would.
|
||||
function hasSingleMatchGuard(line, optionString) {
|
||||
if (/(^|\s)-m\s*1(\s|$)/.test(optionString) || /(^|\s)--max-count[= ]1(\s|$)/.test(optionString)) return true;
|
||||
return /\|\s*head\s+(-1|-n\s*1)\b/.test(line);
|
||||
}
|
||||
|
||||
function isSuppressed(lines, idx) {
|
||||
if (ALLOW_RE.test(lines[idx])) return true;
|
||||
if (idx > 0 && ALLOW_RE.test(lines[idx - 1])) return true;
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract fenced ```bash/```sh code blocks from markdown text.
|
||||
* @param {string} text
|
||||
* @returns {{ startLine: number, lines: string[] }[]}
|
||||
*/
|
||||
function extractBashBlocks(text) {
|
||||
const allLines = text.split(/\r?\n/);
|
||||
const blocks = [];
|
||||
let inBlock = false;
|
||||
let blockLines = [];
|
||||
let blockStart = 0;
|
||||
for (let i = 0; i < allLines.length; i += 1) {
|
||||
const line = allLines[i];
|
||||
if (!inBlock && FENCE_RE.test(line.trim())) {
|
||||
inBlock = true;
|
||||
blockLines = [];
|
||||
blockStart = i + 2; // first line INSIDE the block is 1-indexed i+2
|
||||
continue;
|
||||
}
|
||||
if (inBlock && FENCE_END_RE.test(line.trim())) {
|
||||
blocks.push({ startLine: blockStart, lines: blockLines });
|
||||
inBlock = false;
|
||||
continue;
|
||||
}
|
||||
if (inBlock) blockLines.push(line);
|
||||
}
|
||||
return blocks;
|
||||
}
|
||||
|
||||
/**
|
||||
* Pure: find every un-scoped, token-comparison `grep "^key:"` invocation in a
|
||||
* single fenced bash/sh block's lines. Returns `{ line, key, snippet }[]`
|
||||
* (line numbers relative to the block's startLine, already offset by caller).
|
||||
* @param {string[]} lines
|
||||
* @returns {{ lineIndex: number, key: string, snippet: string }[]}
|
||||
*/
|
||||
function findBroadGrepsInBlock(lines) {
|
||||
const findings = [];
|
||||
// Variables assigned from a grep-key capture on this block, so a later
|
||||
// `==`/`case` use of that variable (without an intervening scope/-m1) also
|
||||
// counts as "used for exact-token comparison".
|
||||
const capturedVars = new Set();
|
||||
let scopeSeenAt = -1;
|
||||
|
||||
for (let i = 0; i < lines.length; i += 1) {
|
||||
const line = lines[i];
|
||||
|
||||
if (FRONTMATTER_SCOPE_RE.test(line)) {
|
||||
scopeSeenAt = i;
|
||||
}
|
||||
|
||||
const m = line.match(GREP_KEY_RE);
|
||||
if (!m) continue;
|
||||
const [, options, , key] = m;
|
||||
if (hasSingleMatchGuard(line, options)) continue;
|
||||
if (isSuppressed(lines, i)) continue;
|
||||
// Scoping must appear strictly before this grep line in the same block.
|
||||
const scoped = scopeSeenAt !== -1 && scopeSeenAt <= i;
|
||||
if (scoped) continue;
|
||||
|
||||
const pipedToTokenTool = /\|\s*(cut|tr)\b/.test(line);
|
||||
const assignMatch = line.match(/^\s*(?:export\s+)?([A-Za-z_][\w]*)=\$\(/);
|
||||
if (assignMatch) capturedVars.add(assignMatch[1]);
|
||||
|
||||
let comparedLater = false;
|
||||
if (assignMatch) {
|
||||
const varName = assignMatch[1];
|
||||
for (let j = i + 1; j < lines.length; j += 1) {
|
||||
if (
|
||||
new RegExp(`\\$\\{?${varName}\\}?"?\\s*(==|!=)`).test(lines[j])
|
||||
|| new RegExp(`case\\s+"?\\$\\{?${varName}\\}?"?\\s+in`).test(lines[j])
|
||||
) {
|
||||
comparedLater = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (pipedToTokenTool || comparedLater) {
|
||||
findings.push({ lineIndex: i, key, snippet: line.trim() });
|
||||
}
|
||||
}
|
||||
return findings;
|
||||
}
|
||||
|
||||
function walkMarkdown(dir) {
|
||||
const out = [];
|
||||
let entries;
|
||||
try {
|
||||
entries = fs.readdirSync(dir, { withFileTypes: true });
|
||||
} catch {
|
||||
return out; // a missing root is not an error — some surfaces are optional
|
||||
}
|
||||
for (const entry of entries) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) out.push(...walkMarkdown(full));
|
||||
else if (entry.isFile() && entry.name.endsWith('.md')) out.push(full);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Scan the given roots (repo-relative) for un-scoped frontmatter-scalar
|
||||
* broad-greps.
|
||||
* @param {string[]} roots
|
||||
* @returns {{ file: string, line: number, key: string, snippet: string }[]}
|
||||
*/
|
||||
function scan(roots = DEFAULT_ROOTS) {
|
||||
const offenders = [];
|
||||
for (const rel of roots) {
|
||||
const abs = path.isAbsolute(rel) ? rel : path.join(ROOT, rel);
|
||||
for (const file of walkMarkdown(abs)) {
|
||||
const blocks = extractBashBlocks(fs.readFileSync(file, 'utf8'));
|
||||
for (const block of blocks) {
|
||||
for (const finding of findBroadGrepsInBlock(block.lines)) {
|
||||
offenders.push({
|
||||
file: path.relative(ROOT, file),
|
||||
line: block.startLine + finding.lineIndex,
|
||||
key: finding.key,
|
||||
snippet: finding.snippet,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return offenders;
|
||||
}
|
||||
|
||||
function main() {
|
||||
const rootsEnv = process.env.GSD_LINT_FRONTMATTER_SCALAR_ROOTS;
|
||||
const roots = rootsEnv ? rootsEnv.split(path.delimiter).filter(Boolean) : DEFAULT_ROOTS;
|
||||
const offenders = scan(roots);
|
||||
if (offenders.length > 0) {
|
||||
const detail = offenders.map((o) => ` ${o.file}:${o.line} ${o.snippet}`).join('\n');
|
||||
throw new ExitError(
|
||||
1,
|
||||
'lint-frontmatter-scalar-broad-grep: `grep "^key:"` over the whole file, compared to an\n'
|
||||
+ 'exact token, with no frontmatter scoping and no -m1 (DEFECT.FRONTMATTER-SCALAR-BROAD-GREP).\n'
|
||||
+ 'A body line beginning `key:` is enough to break this. Scope to the frontmatter block:\n'
|
||||
+ ' sed -n \'/^---$/,/^---$/p\' "$f" | grep -m1 "^<key>:" | cut -d: -f2 | tr -d \' \'\n'
|
||||
+ 'or add `# lint-allow: frontmatter-scalar-broad-grep — <reason>` if this is a genuine\n'
|
||||
+ 'whole-body scan:\n'
|
||||
+ detail,
|
||||
);
|
||||
}
|
||||
console.log(`ok lint-frontmatter-scalar-broad-grep: no un-scoped frontmatter-scalar greps in ${roots.length} root(s)`);
|
||||
}
|
||||
|
||||
module.exports = { findBroadGrepsInBlock, extractBashBlocks, scan, DEFAULT_ROOTS };
|
||||
|
||||
if (require.main === module) runMain(main);
|
||||
208
scripts/lint-removed-but-needed.cjs
Normal file
208
scripts/lint-removed-but-needed.cjs
Normal file
@@ -0,0 +1,208 @@
|
||||
#!/usr/bin/env node
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* lint-removed-but-needed.cjs — DEFECT.REMOVED-BUT-NEEDED (CONTEXT.md).
|
||||
*
|
||||
* ## Why
|
||||
*
|
||||
* A file/key gets removed because "no longer used" without verifying every
|
||||
* consumer (workflows, docs, manifests, npm scripts). #3316: root
|
||||
* `package-lock.json` was deleted while `package.json` still declares deps
|
||||
* and workflows still use `cache: 'npm'` + `npm ci` (which require a
|
||||
* lockfile). e3b52c70: docs referenced a removed `/gsd-new-workspace`
|
||||
* workflow after it was deleted.
|
||||
*
|
||||
* ## What this checks
|
||||
*
|
||||
* For every file deleted (`git diff --name-status <base>...HEAD`, status
|
||||
* `D`), grep the post-diff tree (`.github/workflows/`, `gsd-core/`, `docs/`,
|
||||
* `package.json`) for the deleted file's basename. Fails if any reference
|
||||
* survives. `package-lock.json` deletions additionally fail if any workflow
|
||||
* still uses `npm ci` or `cache: 'npm'`/`cache: "npm"` — those depend on a
|
||||
* lockfile even though they never spell out its filename.
|
||||
*
|
||||
* ## False-positive risk (moderate, per audit)
|
||||
*
|
||||
* A common basename (`index.js`, `config.json`) can coincidentally match an
|
||||
* unrelated file, and this only catches LITERAL string references — not a
|
||||
* variable holding the filename or a glob that happened to match it.
|
||||
*/
|
||||
|
||||
const fs = require('node:fs');
|
||||
const path = require('node:path');
|
||||
const cp = require('node:child_process');
|
||||
const { ExitError, runMain } = require('./lib/cli-exit.cjs');
|
||||
|
||||
const ROOT = path.join(__dirname, '..');
|
||||
const SCAN_ROOTS = ['.github/workflows', 'gsd-core', 'docs'];
|
||||
const EXTRA_FILES = ['package.json'];
|
||||
|
||||
// Skip these when walking SCAN_ROOTS — binary/generated content that can
|
||||
// never carry a meaningful basename reference, and is often large.
|
||||
const SKIP_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.ico', '.woff', '.woff2', '.ttf', '.zip']);
|
||||
|
||||
function escapeRegex(s) {
|
||||
return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
/**
|
||||
* Pure: does `content` contain a literal reference to `basename`, delimited
|
||||
* by non-identifier/non-path characters on both sides (so "foo.json" doesn't
|
||||
* match inside "old-foo.json.bak" style names but does match in a normal
|
||||
* path/prose context)?
|
||||
* @param {string} content
|
||||
* @param {string} basename
|
||||
* @returns {boolean}
|
||||
*/
|
||||
function referencesBasename(content, basename) {
|
||||
const re = new RegExp(`(^|[^\\w.-])${escapeRegex(basename)}($|[^\\w.-])`);
|
||||
return re.test(content);
|
||||
}
|
||||
|
||||
/**
|
||||
* Pure: given the deleted file's basename, does content contain a
|
||||
* lockfile-dependent idiom (`npm ci`, `cache: 'npm'` / `cache: "npm"`)?
|
||||
* Only meaningful for package-lock.json deletions.
|
||||
* @param {string} content
|
||||
* @returns {boolean}
|
||||
*/
|
||||
function referencesNpmLockfileDependency(content) {
|
||||
return /\bnpm ci\b/.test(content) || /cache:\s*['"]npm['"]/.test(content);
|
||||
}
|
||||
|
||||
function walk(dir) {
|
||||
const out = [];
|
||||
let entries;
|
||||
try {
|
||||
entries = fs.readdirSync(dir, { withFileTypes: true });
|
||||
} catch {
|
||||
return out;
|
||||
}
|
||||
for (const entry of entries) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) out.push(...walk(full));
|
||||
else if (entry.isFile() && !SKIP_EXT.has(path.extname(entry.name))) out.push(full);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Pure: given a list of deleted basenames and a `{ file, content }[]` corpus
|
||||
* of the post-diff tree, find every surviving reference.
|
||||
* @param {string[]} deletedFiles - repo-relative deleted paths
|
||||
* @param {{ file: string, content: string }[]} corpus
|
||||
* @returns {{ deletedFile: string, referencedIn: string, reason: string }[]}
|
||||
*/
|
||||
function findSurvivingReferences(deletedFiles, corpus) {
|
||||
const violations = [];
|
||||
for (const deletedFile of deletedFiles) {
|
||||
const basename = path.basename(deletedFile);
|
||||
for (const { file, content } of corpus) {
|
||||
if (referencesBasename(content, basename)) {
|
||||
violations.push({ deletedFile, referencedIn: file, reason: `basename '${basename}' still referenced` });
|
||||
}
|
||||
}
|
||||
if (basename === 'package-lock.json') {
|
||||
for (const { file, content } of corpus) {
|
||||
if (file.startsWith('.github/workflows') && referencesNpmLockfileDependency(content)) {
|
||||
violations.push({
|
||||
deletedFile,
|
||||
referencedIn: file,
|
||||
reason: '`npm ci` / `cache: \'npm\'` still present — both require a lockfile',
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return violations;
|
||||
}
|
||||
|
||||
function getDeletedFiles(root, baseRef) {
|
||||
// Deliberately let a git failure (unresolvable ref, no merge base, etc.)
|
||||
// propagate as a plain Error — main() treats ANY scan() failure as "cannot
|
||||
// resolve this base ref in this environment" and degrades to a skip,
|
||||
// matching lint-fix-has-regression-test.cjs. There is no failure mode here
|
||||
// that should hard-exit non-zero; a real drift is only ever reported once
|
||||
// the diff succeeds and findSurvivingReferences finds a violation.
|
||||
const out = cp.execFileSync('git', ['diff', '--name-status', `${baseRef}...HEAD`], {
|
||||
cwd: root,
|
||||
encoding: 'utf8',
|
||||
timeout: 15000,
|
||||
});
|
||||
return out
|
||||
.trim()
|
||||
.split('\n')
|
||||
.filter(Boolean)
|
||||
.filter((line) => line.startsWith('D\t'))
|
||||
.map((line) => line.slice(2));
|
||||
}
|
||||
|
||||
function buildCorpus(root) {
|
||||
const corpus = [];
|
||||
for (const rel of SCAN_ROOTS) {
|
||||
for (const abs of walk(path.join(root, rel))) {
|
||||
try {
|
||||
corpus.push({ file: path.relative(root, abs).replace(/\\/g, '/'), content: fs.readFileSync(abs, 'utf8') });
|
||||
} catch {
|
||||
// unreadable (broken symlink, binary that slipped past SKIP_EXT) — skip
|
||||
}
|
||||
}
|
||||
}
|
||||
for (const rel of EXTRA_FILES) {
|
||||
const abs = path.join(root, rel);
|
||||
try {
|
||||
corpus.push({ file: rel, content: fs.readFileSync(abs, 'utf8') });
|
||||
} catch {
|
||||
// optional file absent — skip
|
||||
}
|
||||
}
|
||||
return corpus;
|
||||
}
|
||||
|
||||
function scan(root, baseRef) {
|
||||
const deletedFiles = getDeletedFiles(root, baseRef);
|
||||
if (deletedFiles.length === 0) return [];
|
||||
const corpus = buildCorpus(root);
|
||||
return findSurvivingReferences(deletedFiles, corpus);
|
||||
}
|
||||
|
||||
function main() {
|
||||
const baseRef = `origin/${process.env.GSD_REMOVED_BUT_NEEDED_BASE || process.env.GITHUB_BASE_REF || 'next'}`;
|
||||
let violations;
|
||||
try {
|
||||
violations = scan(ROOT, baseRef);
|
||||
} catch (e) {
|
||||
// origin/<base> unreachable in this environment (e.g. a shallow local
|
||||
// clone with no matching remote-tracking ref) — degrade to a skip rather
|
||||
// than a false failure, matching lint-fix-has-regression-test.cjs.
|
||||
console.log(`lint-removed-but-needed: could not resolve ${baseRef}, skipping (${e.message})`);
|
||||
return;
|
||||
}
|
||||
if (violations.length > 0) {
|
||||
const detail = violations
|
||||
.map((v) => ` ${v.deletedFile} deleted, but still referenced in ${v.referencedIn}: ${v.reason}`)
|
||||
.join('\n');
|
||||
throw new ExitError(
|
||||
1,
|
||||
'lint-removed-but-needed: a deleted file is still referenced by a live consumer\n'
|
||||
+ '(DEFECT.REMOVED-BUT-NEEDED). Either restore the file or update every consumer in the\n'
|
||||
+ 'same commit — do not paper over with a workaround that loses reproducibility:\n'
|
||||
+ detail,
|
||||
);
|
||||
}
|
||||
console.log('ok lint-removed-but-needed: no deleted file has a surviving reference');
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
referencesBasename,
|
||||
referencesNpmLockfileDependency,
|
||||
findSurvivingReferences,
|
||||
getDeletedFiles,
|
||||
buildCorpus,
|
||||
scan,
|
||||
SCAN_ROOTS,
|
||||
EXTRA_FILES,
|
||||
};
|
||||
|
||||
if (require.main === module) runMain(main);
|
||||
Reference in New Issue
Block a user