mandrel 2.94.0 → 2.95.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/.agents/runtime-deps.json +6 -6
  2. package/.agents/scripts/agents-bootstrap-github.js +1 -1
  3. package/.agents/scripts/board-backfill.js +1 -1
  4. package/.agents/scripts/boot-sweep.js +1 -1
  5. package/.agents/scripts/check-arch-cycles.js +69 -41
  6. package/.agents/scripts/check-doc-links.js +5 -7
  7. package/.agents/scripts/check-gherkin-corpus.js +2 -11
  8. package/.agents/scripts/clean-temp.js +1 -1
  9. package/.agents/scripts/cleanup-repo-test-temp.js +1 -1
  10. package/.agents/scripts/diagnose-friction.js +1 -1
  11. package/.agents/scripts/generate-lens-checklists.js +4 -4
  12. package/.agents/scripts/generate-skills-index.js +3 -2
  13. package/.agents/scripts/generate-workflows-doc.js +2 -1
  14. package/.agents/scripts/lib/audit-baselines/read.js +2 -1
  15. package/.agents/scripts/lib/audit-exceptions/adapters/tool-config.js +13 -3
  16. package/.agents/scripts/lib/audit-exceptions/globs.js +12 -1
  17. package/.agents/scripts/lib/audit-exceptions/probe.js +24 -2
  18. package/.agents/scripts/lib/audit-exceptions/read.js +2 -2
  19. package/.agents/scripts/lib/audit-to-stories/group-findings.js +77 -67
  20. package/.agents/scripts/lib/baselines/components.js +21 -19
  21. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -8
  22. package/.agents/scripts/lib/baselines/kinds/maintainability.js +2 -3
  23. package/.agents/scripts/lib/baselines/preview-gates.js +2 -2
  24. package/.agents/scripts/lib/baselines/refresh-service.js +4 -7
  25. package/.agents/scripts/lib/baselines/writer.js +2 -7
  26. package/.agents/scripts/lib/bdd-runner-detect.js +2 -2
  27. package/.agents/scripts/lib/bdd-step-index.js +3 -7
  28. package/.agents/scripts/lib/bootstrap/baseline-merge-driver.js +11 -7
  29. package/.agents/scripts/lib/bootstrap/install-ledger.js +19 -4
  30. package/.agents/scripts/lib/bootstrap/json-io.js +14 -0
  31. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +20 -44
  32. package/.agents/scripts/lib/bootstrap/quality-bootstrap.js +38 -54
  33. package/.agents/scripts/lib/branch-name-guard.js +2 -3
  34. package/.agents/scripts/lib/claude/agents-projection.js +1 -12
  35. package/.agents/scripts/lib/codex/agents-projection.js +2 -5
  36. package/.agents/scripts/lib/codex/skills-projection.js +4 -12
  37. package/.agents/scripts/lib/config/defaults.js +2 -1
  38. package/.agents/scripts/lib/config/qa.js +4 -5
  39. package/.agents/scripts/lib/config-schema.js +1 -8
  40. package/.agents/scripts/lib/config-settings-schema.js +0 -3
  41. package/.agents/scripts/lib/coverage-baseline.js +2 -3
  42. package/.agents/scripts/lib/coverage-utils.js +2 -1
  43. package/.agents/scripts/lib/cpu-pool.js +0 -1
  44. package/.agents/scripts/lib/cyclomatic-scope.js +2 -1
  45. package/.agents/scripts/lib/doc-tiers.js +2 -1
  46. package/.agents/scripts/lib/gh-exec.js +21 -1
  47. package/.agents/scripts/lib/git/sync-from-base.js +1 -1
  48. package/.agents/scripts/lib/import-graph.js +13 -28
  49. package/.agents/scripts/lib/json-utils.js +11 -0
  50. package/.agents/scripts/lib/label-constants.js +7 -1
  51. package/.agents/scripts/lib/maintainability-utils.js +14 -22
  52. package/.agents/scripts/lib/observability/runtime-friction.js +37 -1
  53. package/.agents/scripts/lib/orchestration/check-baselines/phases/parse-args.js +25 -1
  54. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +9 -12
  55. package/.agents/scripts/lib/orchestration/code-review.js +1 -6
  56. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  57. package/.agents/scripts/lib/orchestration/git-cleanup/phases/fast-forward.js +7 -14
  58. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes-ff.js +2 -21
  59. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +11 -20
  60. package/.agents/scripts/lib/orchestration/git-cleanup/phases/phase-drivers.js +65 -86
  61. package/.agents/scripts/lib/orchestration/git-cleanup/phases/prompts.js +2 -2
  62. package/.agents/scripts/lib/orchestration/git-cleanup/phases/stashes.js +15 -6
  63. package/.agents/scripts/lib/orchestration/lifecycle/emit-merge-unlanded.js +5 -2
  64. package/.agents/scripts/lib/orchestration/merge-block-class.js +47 -48
  65. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +20 -1
  66. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +2 -3
  67. package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +4 -2
  68. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -2
  69. package/.agents/scripts/lib/orchestration/story-close/ratchet-shrink-writeback.js +3 -3
  70. package/.agents/scripts/lib/orchestration/story-handoff.js +18 -5
  71. package/.agents/scripts/lib/orchestration/ticketing/transition.js +17 -21
  72. package/.agents/scripts/lib/runtime-deps/dep-resolution.js +19 -5
  73. package/.agents/scripts/lib/runtime-deps/scan-imports.js +4 -10
  74. package/.agents/scripts/lib/skills/parse-skill.js +2 -2
  75. package/.agents/scripts/lib/skills/walk-skill-files.js +7 -23
  76. package/.agents/scripts/lib/story-body/story-body.js +4 -14
  77. package/.agents/scripts/lib/util/atomic-write.js +14 -3
  78. package/.agents/scripts/lib/util/regex.js +4 -0
  79. package/.agents/scripts/notify.js +1 -1
  80. package/.agents/scripts/plan-context.js +1 -1
  81. package/.agents/scripts/plan-critics.js +3 -11
  82. package/.agents/scripts/providers/github/auth.js +0 -4
  83. package/.agents/scripts/providers/github/project-board.js +0 -1
  84. package/.agents/scripts/providers/github/tickets.js +0 -2
  85. package/.agents/scripts/resync-status-column.js +1 -1
  86. package/.agents/scripts/run-tests.js +1 -1
  87. package/.agents/scripts/test-wrapper.js +1 -1
  88. package/.agents/scripts/update-ticket-state.js +4 -3
  89. package/.agents/scripts/validate-skills.js +2 -1
  90. package/.agents/skills/core/gates-and-baselines/reference.md +1 -0
  91. package/.agents/workflows/audit-baselines.md +21 -9
  92. package/.agents/workflows/clean-git.md +1 -1
  93. package/.agents/workflows/helpers/audit-lens-core.md +1 -1
  94. package/.agents/workflows/helpers/code-quality-guardrails.md +3 -3
  95. package/README.md +1 -1
  96. package/docs/CHANGELOG.md +34 -0
  97. package/lib/cli/claude-code-version.js +13 -7
  98. package/lib/cli/doctor-checks/llm-review.js +12 -5
  99. package/lib/cli/doctor-checks/merge-driver.js +10 -6
  100. package/lib/cli/doctor-checks/project-access.js +21 -8
  101. package/lib/cli/doctor-checks/read-json.js +2 -15
  102. package/lib/cli/doctor-checks/spawn.js +29 -9
  103. package/lib/cli/doctor-checks/test-credit-path.js +2 -1
  104. package/lib/cli/doctor-checks/toolchain.js +16 -12
  105. package/lib/cli/doctor.js +31 -8
  106. package/lib/cli/registry.js +7 -10
  107. package/lib/cli/sync.js +46 -10
  108. package/lib/cli/uninstall.js +259 -175
  109. package/lib/cli/update.js +3 -3
  110. package/package.json +23 -20
@@ -1,21 +1,21 @@
1
1
  {
2
- "description": "Single source of truth for the third-party npm packages the .agents/ framework scripts import at runtime. This manifest ships *inside* .agents/ so it travels with the mandrel package into consumer projects. Consumers must provide these packages in the node_modules resolvable from their repository root (the framework scripts free-ride on the consumer's install). The `dependencies` block is fail-fast enforced by the preflight guard (.agents/scripts/lib/runtime-deps/ensure-installed.js); the `optionalDependencies` block lists packages that are imported behind graceful-degradation paths (try/catch or dev-only watch tooling) and are therefore declared but never preflight-blocked. A drift test (tests/scripts/runtime-deps-drift.test.js) asserts every third-party import under .agents/scripts/** is declared here. Version ranges mirror the framework's own root package.json. Two entries need their reason recorded. `@babel/parser` is pinned to ^7 because the kernel's fixed plugin list does not parse under 8.x, and the range is documentation rather than enforcement \u2014 `.agents/` resolves from the consumer's own node_modules \u2014 so the kernel asserts the resolved major at load. `babel-runtime` is declared even though no framework script imports it: four of the metric-core packages require it and none of them declares it, so it resolved only by being hoisted from the parse/dispatch plumbing this framework used to depend on. Declaring it makes the closure explicit and preflight-enforced. The import-vs-manifest drift guard only flags imported-but-undeclared, so a declared-but-unimported peer repair like this is legal by design.",
2
+ "description": "Single source of truth for the third-party npm packages the .agents/ framework scripts import at runtime. This manifest ships *inside* .agents/ so it travels with the mandrel package into consumer projects. Consumers must provide these packages in the node_modules resolvable from their repository root (the framework scripts free-ride on the consumer's install). The `dependencies` block is fail-fast enforced by the preflight guard (.agents/scripts/lib/runtime-deps/ensure-installed.js); the `optionalDependencies` block lists packages that are imported behind graceful-degradation paths (try/catch or dev-only watch tooling) and are therefore declared but never preflight-blocked. A drift test (tests/scripts/runtime-deps-drift.test.js) asserts every third-party import under .agents/scripts/** is declared here. Version ranges mirror the framework's own root package.json except where noted. Three entries need their reason recorded. `@babel/parser` is pinned to ^7 because the kernel's fixed plugin list does not parse under 8.x, and the range is documentation rather than enforcement \u2014 `.agents/` resolves from the consumer's own node_modules \u2014 so the kernel asserts the resolved major at load. `babel-runtime` is declared even though no framework script imports it: four of the metric-core packages require it and none of them declares it, so it resolved only by being hoisted from the parse/dispatch plumbing this framework used to depend on. Declaring it makes the closure explicit and preflight-enforced. The import-vs-manifest drift guard only flags imported-but-undeclared, so a declared-but-unimported peer repair like this is legal by design. `js-yaml` accepts both majors although package.json pins ^5 for markdownlint-cli2: consumers whose own tooling (cosmiconfig, rc-config-loader, @eslint/eslintrc) keeps 4.x at their root resolve that copy, and the framework imports only the named `load`, which both majors export and parse identically. 4.3.2 is the 4.x floor that clears GHSA-52cp-r559-cp3m, GHSA-h67p-54hq-rp68, GHSA-5p4m-2wfm-xmqj and GHSA-2883-xcg3-v3hh.",
3
3
  "dependencies": {
4
- "@babel/parser": "^7.29.3",
4
+ "@babel/parser": "^7.29.9",
5
5
  "ajv": "^8.20.0",
6
6
  "babel-runtime": "^6.26.0",
7
7
  "escomplex-plugin-metrics-module": "^0.1.0",
8
8
  "escomplex-plugin-syntax-babylon": "^0.1.0",
9
- "js-yaml": "^4.3.1",
10
- "picomatch": "^4.0.4",
9
+ "js-yaml": "^4.3.2 || ^5.4.3",
10
+ "picomatch": "^4.0.7",
11
11
  "typhonjs-ast-walker": "^0.2.1",
12
12
  "typhonjs-escomplex-commons": "^0.1.1"
13
13
  },
14
14
  "optionalDependencies": {
15
15
  "@commitlint/load": "^21.0.0",
16
- "chokidar": "^5.0.0",
16
+ "chokidar": "^6.0.0",
17
17
  "jscpd": "^4.0.0",
18
- "knip": "^6.17.1",
18
+ "knip": "^6.42.1",
19
19
  "typescript": ">=5.0.0 <7"
20
20
  }
21
21
  }
@@ -1,4 +1,4 @@
1
- /* node:coverage ignore file */
1
+ /* node:coverage ignore file -- live gh setup CLI; logic tested in lib/bootstrap */
2
2
  /**
3
3
  * agents-bootstrap-github — idempotent GitHub-side setup: label taxonomy,
4
4
  * optional project board, branch protection, merge methods.
@@ -210,7 +210,7 @@ async function applyPlan({ plan, issue, provider, projectId, sync, summary }) {
210
210
  else summary.failed += 1;
211
211
  }
212
212
 
213
- /* node:coverage ignore next */
213
+ /* node:coverage ignore next -- live CLI entry */
214
214
  export async function main(argv = process.argv.slice(2)) {
215
215
  const { values } = parseArgs({
216
216
  args: argv,
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- /* node:coverage ignore file */
2
+ /* node:coverage ignore file -- CLI shell over tested sweep libs */
3
3
 
4
4
  /**
5
5
  * boot-sweep.js — non-interactive *protected* merged-branch sweep over
@@ -18,6 +18,7 @@ import {
18
18
  DEFAULT_ROOTS,
19
19
  parseRelativeImports,
20
20
  } from './lib/import-graph.js';
21
+ import { writeFileAtomic } from './lib/util/atomic-write.js';
21
22
 
22
23
  // Shared with `audit-baselines.js`; re-exported as part of this module's contract.
23
24
  export {
@@ -28,19 +29,22 @@ export {
28
29
  readJsonBaseline as loadBaseline,
29
30
  };
30
31
 
32
+ const BASELINE_SCHEMA = 'https://mandrel.dev/baselines/arch-cycles.schema.json';
33
+
31
34
  /**
32
35
  * @param {string[]} argv
33
- * @returns {{ baselinePath: string | null, rootPath: string | null, json: boolean }}
36
+ * @returns {{ baselinePath: string | null, rootPath: string | null, json: boolean, update: boolean }}
34
37
  */
35
38
  export function parseArgv(argv = []) {
36
39
  const flags = parseGateArgv(argv, {
37
40
  strings: ['baseline', 'root'],
38
- booleans: ['json'],
41
+ booleans: ['json', 'update'],
39
42
  });
40
43
  return {
41
44
  baselinePath: flags.baseline,
42
45
  rootPath: flags.root,
43
46
  json: flags.json,
47
+ update: flags.update,
44
48
  };
45
49
  }
46
50
 
@@ -156,6 +160,41 @@ export function renderDiff(diff) {
156
160
  return lines.join('\n');
157
161
  }
158
162
 
163
+ /**
164
+ * `--root` scans one root relative to itself; otherwise every root is
165
+ * relativized against `cwd` so cross-root edges join one graph.
166
+ *
167
+ * @param {string} cwd
168
+ * @param {string | null} rootPath
169
+ * @returns {{ graphRoot: string, detected: string[][] }}
170
+ */
171
+ function detectCycles(cwd, rootPath) {
172
+ const graphRoot = rootPath ? path.resolve(cwd, rootPath) : path.resolve(cwd);
173
+ const scanDirs = (rootPath ? [rootPath] : DEFAULT_ROOTS).map((dir) =>
174
+ path.resolve(cwd, dir),
175
+ );
176
+ const presentScanDirs = scanDirs.filter((dir) => fs.existsSync(dir));
177
+ if (presentScanDirs.length === 0) {
178
+ throw new Error(`[arch-cycles] no scan root found: ${scanDirs.join(', ')}`);
179
+ }
180
+ const files = presentScanDirs.flatMap((dir) => collectJsFiles(dir));
181
+ return { graphRoot, detected: findCycles(buildGraph(files, graphRoot)) };
182
+ }
183
+
184
+ function writeReport({ json, baseline, report, stdout, stderr }) {
185
+ if (json) {
186
+ stdout.write(`${JSON.stringify(report, null, 2)}\n`);
187
+ return;
188
+ }
189
+ if (!baseline) {
190
+ stderr.write(
191
+ `[arch-cycles] ⚠ allowlist not found at ${report.baselinePath} — treating as empty\n`,
192
+ );
193
+ }
194
+ stdout.write(`\n--- arch-cycles preview ---\n`);
195
+ stdout.write(`${renderDiff(report)}\n`);
196
+ }
197
+
159
198
  /**
160
199
  * @param {{
161
200
  * argv?: string[],
@@ -163,7 +202,7 @@ export function renderDiff(diff) {
163
202
  * stdout?: { write: (s: string) => void },
164
203
  * stderr?: { write: (s: string) => void },
165
204
  * }} [opts]
166
- * @returns {Promise<number>} 0 = clean or removals-only; 1 = new cycle detected
205
+ * @returns {Promise<number>} 0 = clean, removals-only, or `--update`; 1 = new cycle detected
167
206
  */
168
207
  export async function runCli({
169
208
  argv = process.argv.slice(2),
@@ -171,52 +210,37 @@ export async function runCli({
171
210
  stdout = process.stdout,
172
211
  stderr = process.stderr,
173
212
  } = {}) {
174
- const { baselinePath, rootPath, json } = parseArgv(argv);
175
- // `--root` scans one root relative to itself; otherwise every root is
176
- // relativized against `cwd` so cross-root edges join one graph.
177
- const graphRoot = rootPath ? path.resolve(cwd, rootPath) : path.resolve(cwd);
178
- const scanDirs = (rootPath ? [rootPath] : DEFAULT_ROOTS).map((dir) =>
179
- path.resolve(cwd, dir),
180
- );
213
+ const { baselinePath, rootPath, json, update } = parseArgv(argv);
181
214
  const resolvedBaselinePath = path.resolve(
182
215
  cwd,
183
216
  baselinePath ?? path.join('baselines', 'arch-cycles.json'),
184
217
  );
185
- const presentScanDirs = scanDirs.filter((dir) => fs.existsSync(dir));
186
- if (presentScanDirs.length === 0) {
187
- throw new Error(`[arch-cycles] no scan root found: ${scanDirs.join(', ')}`);
218
+ const { graphRoot, detected } = detectCycles(cwd, rootPath);
219
+ if (update) {
220
+ const data = {
221
+ $schema: BASELINE_SCHEMA,
222
+ generatedAt: new Date().toISOString(),
223
+ cycles: detected,
224
+ };
225
+ writeFileAtomic(resolvedBaselinePath, `${JSON.stringify(data, null, 2)}\n`);
226
+ stdout.write(`[arch-cycles] wrote ${detected.length} cycle(s)\n`);
227
+ return 0;
188
228
  }
189
229
  const baseline = readJsonBaseline(resolvedBaselinePath);
190
230
  const allowlisted = Array.isArray(baseline?.cycles) ? baseline.cycles : [];
191
-
192
- const files = presentScanDirs.flatMap((dir) => collectJsFiles(dir));
193
- const graph = buildGraph(files, graphRoot);
194
- const detected = findCycles(graph);
195
231
  const diff = diffCycles(allowlisted, detected);
196
232
  const exitCode = diff.added.length > 0 ? 1 : 0;
197
-
198
- if (json) {
199
- const envelope = {
200
- kind: 'arch-cycles-report',
201
- root: graphRoot,
202
- baselinePath: resolvedBaselinePath,
203
- allowlisted: allowlisted.map(normalizeCycle),
204
- detected,
205
- added: diff.added,
206
- removed: diff.removed,
207
- exitCode,
208
- };
209
- stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
210
- } else {
211
- if (!baseline) {
212
- stderr.write(
213
- `[arch-cycles] ⚠ allowlist not found at ${resolvedBaselinePath} — treating as empty\n`,
214
- );
215
- }
216
- stdout.write(`\n--- arch-cycles preview ---\n`);
217
- stdout.write(`${renderDiff(diff)}\n`);
218
- }
219
-
233
+ const report = {
234
+ kind: 'arch-cycles-report',
235
+ root: graphRoot,
236
+ baselinePath: resolvedBaselinePath,
237
+ allowlisted: allowlisted.map(normalizeCycle),
238
+ detected,
239
+ added: diff.added,
240
+ removed: diff.removed,
241
+ exitCode,
242
+ };
243
+ writeReport({ json, baseline, report, stdout, stderr });
220
244
  return exitCode;
221
245
  }
222
246
 
@@ -226,7 +250,7 @@ runAsCli(import.meta.url, runCli, {
226
250
  errorPrefix: '[arch-cycles] ❌ Fatal error',
227
251
  usage: {
228
252
  invocation:
229
- 'node .agents/scripts/check-arch-cycles.js [--baseline <path>] [--root <dir>] [--json]',
253
+ 'node .agents/scripts/check-arch-cycles.js [--baseline <path>] [--root <dir>] [--json] [--update]',
230
254
  summary:
231
255
  'Ratchet on module-dependency cycles: compare the live import graph against the recorded baseline and fail on any newly added cycle.',
232
256
  flags: [
@@ -239,6 +263,10 @@ runAsCli(import.meta.url, runCli, {
239
263
  'Scan a single root instead of the distributed surface.',
240
264
  ],
241
265
  ['--json', 'Emit the comparison envelope as JSON.'],
266
+ [
267
+ '--update',
268
+ 'Rewrite the baseline to the detected cycles with a fresh generatedAt.',
269
+ ],
242
270
  ],
243
271
  notes: [
244
272
  'Exit codes:\n 0 clean, or removals only\n 1 a new cycle was detected',
@@ -12,6 +12,7 @@ import picomatch from 'picomatch';
12
12
  import { parseStandardCliArgs } from './lib/cli/standard-args.js';
13
13
  import { runAsCli } from './lib/cli-utils.js';
14
14
  import { Logger } from './lib/Logger.js';
15
+ import { toPosix } from './lib/util/paths.js';
15
16
 
16
17
  const __filename = fileURLToPath(import.meta.url);
17
18
  const __dirname = path.dirname(__filename);
@@ -146,7 +147,7 @@ function walkMarkdown(dirAbs, repoRoot, out) {
146
147
  if (entry.name === 'node_modules' || entry.name === '.git') continue;
147
148
  walkMarkdown(abs, repoRoot, out);
148
149
  } else if (entry.isFile() && entry.name.endsWith('.md')) {
149
- const rel = path.relative(repoRoot, abs).split(path.sep).join('/');
150
+ const rel = toPosix(path.relative(repoRoot, abs));
150
151
  if (!isExcludedRelPath(rel)) out.push(abs);
151
152
  }
152
153
  }
@@ -165,7 +166,7 @@ export function discoverMarkdown(rootAbs, scanRoots, exclude = []) {
165
166
  }
166
167
  const filtered = exclude.length
167
168
  ? out.filter((abs) => {
168
- const rel = path.relative(rootAbs, abs).split(path.sep).join('/');
169
+ const rel = toPosix(path.relative(rootAbs, abs));
169
170
  return !exclude.some((g) => picomatch.isMatch(rel, g, { dot: true }));
170
171
  })
171
172
  : out;
@@ -292,7 +293,7 @@ export function checkFile(absPath, repoRoot) {
292
293
  const source = fs.readFileSync(absPath, 'utf8');
293
294
  const masked = maskCodeRegions(source);
294
295
  const fileDir = path.dirname(absPath);
295
- const relFile = path.relative(repoRoot, absPath).split(path.sep).join('/');
296
+ const relFile = toPosix(path.relative(repoRoot, absPath));
296
297
  const workflowsDir = path.join(repoRoot, '.agents', 'workflows');
297
298
 
298
299
  const slashTokens = extractSlashTokens(masked);
@@ -322,10 +323,7 @@ export function checkFile(absPath, repoRoot) {
322
323
  resolved = path.resolve(fileDir, pathOnly);
323
324
  }
324
325
  // Boundary wins over existence; one link reports one kind.
325
- const relTarget = path
326
- .relative(repoRoot, resolved)
327
- .split(path.sep)
328
- .join('/');
326
+ const relTarget = toPosix(path.relative(repoRoot, resolved));
329
327
  if (escapesPayload(relFile, relTarget)) {
330
328
  violations.push({
331
329
  file: relFile,
@@ -20,6 +20,7 @@ import {
20
20
  listStepFiles,
21
21
  matchStep,
22
22
  } from './lib/bdd-step-index.js';
23
+ import { parseGateArgv } from './lib/cli-args.js';
23
24
  import { runAsCli } from './lib/cli-utils.js';
24
25
  import { getGherkinLint } from './lib/config/qa.js';
25
26
  import { resolveConfig } from './lib/config-resolver.js';
@@ -44,17 +45,7 @@ const HELP = {
44
45
  * @returns {{ cwd: string | null }}
45
46
  */
46
47
  export function parseArgs(argv = []) {
47
- const out = { cwd: null };
48
- for (let i = 0; i < argv.length; i += 1) {
49
- if (argv[i] === '--cwd') {
50
- const next = argv[i + 1];
51
- if (next && !next.startsWith('--')) {
52
- out.cwd = next;
53
- i += 1;
54
- }
55
- }
56
- }
57
- return out;
48
+ return parseGateArgv(argv, { strings: ['cwd'] });
58
49
  }
59
50
 
60
51
  /**
@@ -15,7 +15,7 @@ import { resolveConfig } from './lib/config-resolver.js';
15
15
  import { promptYesNo } from './lib/orchestration/git-cleanup/phases/prompts.js';
16
16
  import { createProvider } from './lib/provider-factory.js';
17
17
 
18
- /* node:coverage ignore next */
18
+ /* node:coverage ignore next -- CLI entry */
19
19
  async function main() {
20
20
  const { exitCode } = await runCleanTemp({
21
21
  argv: process.argv.slice(2),
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- /* node:coverage ignore file */
2
+ /* node:coverage ignore file -- CLI entrypoint convention, see docs/decisions.md */
3
3
 
4
4
  /**
5
5
  * Removes **test-reserved** per-Epic trees under `<repo>/temp/epic-<id>/` after
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- /* node:coverage ignore file */
2
+ /* node:coverage ignore file -- process-wrapping CLI */
3
3
 
4
4
  /**
5
5
  * Diagnostic interceptor: runs a command (argv words, no shell) and on
@@ -14,6 +14,7 @@ import { renderLensChecklist } from './lib/audit-suite/lens-checklist.js';
14
14
  import { AUDIT_LENSES } from './lib/audit-to-stories/audit-lenses.js';
15
15
  import { runAsCli } from './lib/cli-utils.js';
16
16
  import { Logger } from './lib/Logger.js';
17
+ import { toPosix } from './lib/util/paths.js';
17
18
 
18
19
  const __filename = fileURLToPath(import.meta.url);
19
20
  const __dirname = path.dirname(__filename);
@@ -79,10 +80,9 @@ function relChecklist(
79
80
  checklistsDir = CHECKLISTS_DIR,
80
81
  projectRoot = PROJECT_ROOT,
81
82
  ) {
82
- return path
83
- .relative(projectRoot, path.join(checklistsDir, basename))
84
- .split(path.sep)
85
- .join('/');
83
+ return toPosix(
84
+ path.relative(projectRoot, path.join(checklistsDir, basename)),
85
+ );
86
86
  }
87
87
 
88
88
  /**
@@ -26,6 +26,7 @@ import {
26
26
  LOCAL_SKILLS_SEGMENTS,
27
27
  PAYLOAD_SKILLS_SEGMENTS,
28
28
  } from './lib/skills/walk-skill-files.js';
29
+ import { toPosix } from './lib/util/paths.js';
29
30
 
30
31
  const GENERATOR_ID = 'generate-skills-index.js@1';
31
32
 
@@ -125,7 +126,7 @@ function writeManifest(manifest, outPath, root) {
125
126
 
126
127
  /** An emptied local zone removes its index rather than leave a stale one. */
127
128
  function writeLocalManifest(localFresh, localOutPath, root) {
128
- const rel = path.relative(root, localOutPath).split(path.sep).join('/');
129
+ const rel = toPosix(path.relative(root, localOutPath));
129
130
  if (localFresh === null) {
130
131
  if (fs.existsSync(localOutPath)) {
131
132
  fs.rmSync(localOutPath);
@@ -236,7 +237,7 @@ export function run({ argv = [], now = new Date(), repoRoot } = {}) {
236
237
 
237
238
  writeManifest(fresh, outPath, root);
238
239
  Logger.info(
239
- `wrote ${path.relative(root, outPath).split(path.sep).join('/')} (${fresh.skills.length} entries)`,
240
+ `wrote ${toPosix(path.relative(root, outPath))} (${fresh.skills.length} entries)`,
240
241
  );
241
242
  writeLocalManifest(localFresh, localOutPath, root);
242
243
  return { status: 0, output: '' };
@@ -12,6 +12,7 @@ import { parseArgs } from 'node:util';
12
12
  import { runAsCli } from './lib/cli-utils.js';
13
13
  import { Logger } from './lib/Logger.js';
14
14
  import { buildCatalog, buildLoopCatalog } from './lib/mandrel-catalog.js';
15
+ import { toPosix } from './lib/util/paths.js';
15
16
 
16
17
  const __filename = fileURLToPath(import.meta.url);
17
18
  const __dirname = path.dirname(__filename);
@@ -179,7 +180,7 @@ async function main(argv = process.argv.slice(2)) {
179
180
  });
180
181
 
181
182
  const { generated, original, root, docPath } = buildExpected(values.root);
182
- const rel = path.relative(root, docPath).split(path.sep).join('/');
183
+ const rel = toPosix(path.relative(root, docPath));
183
184
 
184
185
  if (values.check) {
185
186
  if (original === generated) {
@@ -7,6 +7,7 @@
7
7
 
8
8
  import fs from 'node:fs';
9
9
  import path from 'node:path';
10
+ import { toPosix } from '../util/paths.js';
10
11
 
11
12
  /**
12
13
  * @param {string} absolutePath
@@ -53,7 +54,7 @@ export function listFilesUnder(repoRoot, rootDir, scannerSkip = []) {
53
54
  if (entry.isDirectory()) {
54
55
  walk(child);
55
56
  } else if (entry.isFile()) {
56
- out.push(path.relative(repoRoot, child).split(path.sep).join('/'));
57
+ out.push(toPosix(path.relative(repoRoot, child)));
57
58
  }
58
59
  }
59
60
  };
@@ -110,6 +110,15 @@ const TS_LOOSENED = Object.freeze({
110
110
  skipLibCheck: true,
111
111
  });
112
112
 
113
+ // A JSONC `//` line directly above an entry is its reason, unless it is a
114
+ // commented-out entry (`// "src/old/**",`) rather than prose.
115
+ function commentAbove(text, line) {
116
+ const prev = (text ?? '').split('\n')[line - 2]?.trim() ?? '';
117
+ if (!prev.startsWith('//')) return null;
118
+ const body = prev.slice(2).trim();
119
+ return body && !/^[[\]{}"]/.test(body) ? body : null;
120
+ }
121
+
113
122
  function configRecord(
114
123
  ctx,
115
124
  {
@@ -125,16 +134,17 @@ function configRecord(
125
134
  anchors,
126
135
  },
127
136
  ) {
137
+ // Every target is a JSON string or key, so match it quoted.
138
+ const line = lineOf(text, `"${target}"`, anchors);
128
139
  return makeRecord({
129
140
  adapter: 'tool-config',
130
141
  category: 'config',
131
142
  surface,
132
143
  file,
133
- // Every target is a JSON string or key, so match it quoted.
134
- line: lineOf(text, `"${target}"`, anchors),
144
+ line,
135
145
  target,
136
146
  rule: `${surface}:${rule}`,
137
- justification,
147
+ justification: justification ?? commentAbove(text, line),
138
148
  probe: probe ?? globsProbe(ctx, globs),
139
149
  permanentHint,
140
150
  });
@@ -48,6 +48,13 @@ export function ignoreLineGlobs(line, dir = '') {
48
48
  .map((g) => (dir ? `${dir}/${g}` : g));
49
49
  }
50
50
 
51
+ // Emitted code and captured test data are excluded by design.
52
+ function byDesignHint(glob) {
53
+ const dir = /(?:^|\/)(generated|fixtures)(?:\/|$)/.exec(glob)?.[1];
54
+ if (dir === 'generated') return 'generated-path';
55
+ return dir === 'fixtures' ? 'fixture-path' : null;
56
+ }
57
+
51
58
  /**
52
59
  * @param {object} ctx
53
60
  * @param {string} glob - repo-relative.
@@ -59,7 +66,11 @@ function probeOne(ctx, glob) {
59
66
  dot: true,
60
67
  });
61
68
  if (ctx.scope.files.some((f) => isMatch(f)))
62
- return { verdict: 'live', basis: 'matches-tracked' };
69
+ return {
70
+ verdict: 'live',
71
+ basis: 'matches-tracked',
72
+ permanentHint: byDesignHint(clean),
73
+ };
63
74
  const base = staticBase(clean);
64
75
  if (base === '') return { verdict: 'unknown', basis: 'no-static-base' };
65
76
  if (fs.existsSync(path.join(ctx.root, base))) {
@@ -13,12 +13,34 @@ import fs from 'node:fs';
13
13
  import path from 'node:path';
14
14
  import process from 'node:process';
15
15
  import { spawnCaptureAsync } from '../child-exec.js';
16
+ import { toPosix } from '../util/paths.js';
16
17
  import { readJsonc } from './read.js';
17
18
 
18
19
  const PROBE_TIMEOUT_MS = 180_000;
19
20
 
21
+ // .native expands Windows 8.3 short names.
22
+ const realOrSelf = (p) => {
23
+ const plain = p.replace(/^\\\\\?\\/, '');
24
+ try {
25
+ return fs.realpathSync.native(plain);
26
+ } catch {
27
+ return plain;
28
+ }
29
+ };
30
+
31
+ // GitHub workflow-command property escaping (Windows drive colons arrive as %3A).
32
+ const unescapeProperty = (v) =>
33
+ v
34
+ .replace(/%2C/gi, ',')
35
+ .replace(/%3A/gi, ':')
36
+ .replace(/%0D/gi, '\r')
37
+ .replace(/%0A/gi, '\n')
38
+ .replace(/%25/g, '%');
39
+
20
40
  const relTo = (root, file) =>
21
- path.relative(root, path.resolve(root, file)).split(path.sep).join('/');
41
+ toPosix(
42
+ path.relative(realOrSelf(root), realOrSelf(path.resolve(root, file))),
43
+ );
22
44
 
23
45
  /** Each tool: package + bin, when it applies, its args, and how to read hits. */
24
46
  const TOOLS = Object.freeze([
@@ -35,7 +57,7 @@ const TOOLS = Object.freeze([
35
57
  /^::\w+ title=suppressions\/unused,file=([^,]+),line=(\d+)/gm,
36
58
  ),
37
59
  ].map((m) => ({
38
- file: relTo(root, m[1]),
60
+ file: relTo(root, unescapeProperty(m[1])),
39
61
  line: Number(m[2]),
40
62
  })),
41
63
  },
@@ -9,7 +9,7 @@
9
9
 
10
10
  import fs from 'node:fs';
11
11
  import path from 'node:path';
12
- import yaml from 'js-yaml';
12
+ import { load } from 'js-yaml';
13
13
 
14
14
  /**
15
15
  * @param {string} root
@@ -94,7 +94,7 @@ export function readYaml(root, rel) {
94
94
  const text = readText(root, rel);
95
95
  if (text === null) return null;
96
96
  try {
97
- return yaml.load(text) ?? null;
97
+ return load(text) ?? null;
98
98
  } catch {
99
99
  return null;
100
100
  }