mandrel 2.90.0 → 2.92.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 (175) hide show
  1. package/.agents/README.md +47 -7
  2. package/.agents/agents/story-worker.md +20 -0
  3. package/.agents/audit-checklists/lean.md +26 -0
  4. package/.agents/docs/agentrc-reference.json +5 -6
  5. package/.agents/docs/configuration.md +31 -30
  6. package/.agents/docs/workflows.md +7 -1
  7. package/.agents/instructions.md +3 -1
  8. package/.agents/runtime-deps.json +0 -2
  9. package/.agents/schemas/agentrc.schema.json +46 -45
  10. package/.agents/schemas/audit-rules.json +19 -0
  11. package/.agents/scripts/acceptance-eval.js +2 -6
  12. package/.agents/scripts/audit-exceptions.js +2 -4
  13. package/.agents/scripts/check-arch-cycles.js +1 -5
  14. package/.agents/scripts/check-context-budget.js +1 -5
  15. package/.agents/scripts/check-cyclomatic.js +1 -5
  16. package/.agents/scripts/check-dead-exports.js +23 -14
  17. package/.agents/scripts/check-doc-links.js +4 -4
  18. package/.agents/scripts/check-test-temp-hygiene.js +29 -33
  19. package/.agents/scripts/coverage-capture.js +14 -6
  20. package/.agents/scripts/diagnose-friction.js +8 -10
  21. package/.agents/scripts/generate-workflows-doc.js +5 -0
  22. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +2 -0
  23. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +36 -27
  24. package/.agents/scripts/lib/audit-exceptions/adapters/shortcut-markers.js +70 -0
  25. package/.agents/scripts/lib/audit-exceptions/adapters/source-scan.js +26 -0
  26. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  27. package/.agents/scripts/lib/baseline-schema-registry.js +3 -5
  28. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +11 -28
  29. package/.agents/scripts/lib/baselines/components.js +5 -5
  30. package/.agents/scripts/lib/baselines/crap-preview-scan.js +4 -1
  31. package/.agents/scripts/lib/baselines/crap-updater-cli.js +6 -4
  32. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -10
  33. package/.agents/scripts/lib/baselines/kinds/crap.js +4 -2
  34. package/.agents/scripts/lib/baselines/kinds/duplication.js +4 -2
  35. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +13 -6
  36. package/.agents/scripts/lib/baselines/refresh-service.js +10 -13
  37. package/.agents/scripts/lib/baselines/writer.js +4 -4
  38. package/.agents/scripts/lib/bdd-scenario-scanner.js +26 -31
  39. package/.agents/scripts/lib/bootstrap/gh-list.js +4 -5
  40. package/.agents/scripts/lib/bootstrap/gh-preflight.js +13 -8
  41. package/.agents/scripts/lib/child-exec.js +4 -4
  42. package/.agents/scripts/lib/claude/agents-projection.js +170 -0
  43. package/.agents/scripts/lib/claude/commands-projection.js +184 -0
  44. package/.agents/scripts/lib/close-validation/commands.js +28 -117
  45. package/.agents/scripts/lib/close-validation/gates.js +54 -48
  46. package/.agents/scripts/lib/close-validation/projections/crap.js +2 -1
  47. package/.agents/scripts/lib/close-validation/projections/maintainability.js +50 -15
  48. package/.agents/scripts/lib/config/agentrc-overlay.js +4 -7
  49. package/.agents/scripts/lib/config/commands.js +82 -7
  50. package/.agents/scripts/lib/config/explain.js +2 -1
  51. package/.agents/scripts/lib/config/gates/coverage.schema.js +39 -3
  52. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  53. package/.agents/scripts/lib/config/gates/crap.schema.js +5 -3
  54. package/.agents/scripts/lib/config/gates/duplication.schema.js +6 -11
  55. package/.agents/scripts/lib/config/gates/shared.js +2 -2
  56. package/.agents/scripts/lib/config/git-roots.js +120 -0
  57. package/.agents/scripts/lib/config/quality.js +46 -50
  58. package/.agents/scripts/lib/config/review-chain-default.js +4 -3
  59. package/.agents/scripts/lib/config/review-provider-clis.js +11 -0
  60. package/.agents/scripts/lib/config/temp-paths.js +3 -37
  61. package/.agents/scripts/lib/config-resolver.js +5 -9
  62. package/.agents/scripts/lib/config-settings-schema-delivery.js +2 -2
  63. package/.agents/scripts/lib/config-settings-schema-quality.js +3 -2
  64. package/.agents/scripts/lib/config-settings-schema.js +6 -7
  65. package/.agents/scripts/lib/coverage-baseline.js +2 -1
  66. package/.agents/scripts/lib/coverage-capture-affected.js +4 -3
  67. package/.agents/scripts/lib/coverage-capture-fullscope.js +3 -1
  68. package/.agents/scripts/lib/coverage-capture-passes.js +119 -34
  69. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  70. package/.agents/scripts/lib/coverage-capture.js +31 -20
  71. package/.agents/scripts/lib/coverage-utils.js +34 -16
  72. package/.agents/scripts/lib/cpu-pool.js +2 -4
  73. package/.agents/scripts/lib/crap-engine.js +19 -1
  74. package/.agents/scripts/lib/crap-utils.js +2 -1
  75. package/.agents/scripts/lib/dead-exports-knip.js +29 -11
  76. package/.agents/scripts/lib/detect-package-manager.js +13 -0
  77. package/.agents/scripts/lib/feedback-loop/graduator-gh.js +4 -2
  78. package/.agents/scripts/lib/full-suite-lock.js +25 -9
  79. package/.agents/scripts/lib/gates/baseline-store.js +2 -10
  80. package/.agents/scripts/lib/generated/agentrc-validator.js +4 -1
  81. package/.agents/scripts/lib/gh-env.js +72 -0
  82. package/.agents/scripts/lib/gh-exec.js +26 -1
  83. package/.agents/scripts/lib/maintainability-utils.js +8 -8
  84. package/.agents/scripts/lib/npm-scripts.js +1 -1
  85. package/.agents/scripts/lib/observability/signal-validator.js +2 -6
  86. package/.agents/scripts/lib/observability/terse-result.js +2 -6
  87. package/.agents/scripts/lib/orchestration/board-access-latch.js +19 -8
  88. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +10 -13
  89. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  90. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +3 -3
  91. package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js +2 -6
  92. package/.agents/scripts/lib/orchestration/light-suitability.js +5 -7
  93. package/.agents/scripts/lib/orchestration/pr-watch.js +7 -7
  94. package/.agents/scripts/lib/orchestration/project-meta-cache.js +2 -11
  95. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -9
  96. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +219 -0
  97. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +53 -5
  98. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +2 -2
  99. package/.agents/scripts/lib/orchestration/review-providers/llm-review.js +96 -0
  100. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  101. package/.agents/scripts/lib/orchestration/review-providers/native.js +13 -19
  102. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +3 -2
  103. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +2 -0
  104. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +11 -3
  105. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +4 -1
  106. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +49 -83
  107. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -3
  108. package/.agents/scripts/lib/orchestration/story-close/format-autofix.js +41 -15
  109. package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js +2 -4
  110. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +2 -13
  111. package/.agents/scripts/lib/orchestration/story-handoff.js +13 -5
  112. package/.agents/scripts/lib/orchestration/story-init-result.js +11 -0
  113. package/.agents/scripts/lib/orchestration/story-progress.js +3 -11
  114. package/.agents/scripts/lib/orchestration/ticketing/bulk.js +3 -5
  115. package/.agents/scripts/lib/orchestration/ticketing/transition.js +47 -21
  116. package/.agents/scripts/lib/orchestration/verify-credit.js +52 -28
  117. package/.agents/scripts/lib/single-story-sweep/protection-ctx.js +11 -11
  118. package/.agents/scripts/lib/single-story-sweep/protection.js +1 -9
  119. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +1 -5
  120. package/.agents/scripts/lib/source-extensions.js +30 -15
  121. package/.agents/scripts/lib/test-run-credit.js +1 -9
  122. package/.agents/scripts/lib/test-temp.js +22 -21
  123. package/.agents/scripts/lib/util/ajv.js +111 -0
  124. package/.agents/scripts/lib/util/atomic-write.js +30 -0
  125. package/.agents/scripts/lib/util/paths.js +51 -0
  126. package/.agents/scripts/lib/util/sleep.js +6 -0
  127. package/.agents/scripts/lib/util/slug.js +12 -0
  128. package/.agents/scripts/lib/validation-evidence.js +19 -40
  129. package/.agents/scripts/lib/worktree/lifecycle/force-drain.js +2 -1
  130. package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js +10 -28
  131. package/.agents/scripts/lib/worktree/lifecycle/reap.js +2 -2
  132. package/.agents/scripts/lib/worktree/node-modules-strategy.js +21 -14
  133. package/.agents/scripts/lint-issue-body.js +2 -2
  134. package/.agents/scripts/plan-context.js +2 -7
  135. package/.agents/scripts/providers/github/auth.js +3 -3
  136. package/.agents/scripts/providers/github/errors.js +3 -1
  137. package/.agents/scripts/providers/github/gh-token-diagnostics.js +10 -7
  138. package/.agents/scripts/providers/github/issues.js +6 -2
  139. package/.agents/scripts/providers/github/mappers.js +1 -5
  140. package/.agents/scripts/providers/github/projects-v2-graphql.js +11 -3
  141. package/.agents/scripts/providers/github/search-budget.js +3 -1
  142. package/.agents/scripts/resolve-doc-tiers.js +7 -20
  143. package/.agents/scripts/single-story-init.js +18 -14
  144. package/.agents/scripts/sync-agentrc.js +5 -14
  145. package/.agents/scripts/sync-claude-agents.js +38 -150
  146. package/.agents/scripts/sync-claude-commands.js +35 -218
  147. package/.agents/scripts/update-coverage-baseline.js +1 -1
  148. package/.agents/scripts/update-crap-baseline.js +1 -1
  149. package/.agents/scripts/update-duplication-baseline.js +2 -16
  150. package/.agents/scripts/validate-skills.js +6 -10
  151. package/.agents/skills/core/code-review-and-quality/SKILL.md +3 -18
  152. package/.agents/skills/core/documentation-and-adrs/SKILL.md +4 -14
  153. package/.agents/workflows/audit-exceptions.md +9 -0
  154. package/.agents/workflows/audit-lean.md +129 -0
  155. package/.agents/workflows/helpers/audit-lens-core.md +7 -0
  156. package/.agents/workflows/helpers/code-quality-guardrails.md +21 -0
  157. package/.agents/workflows/helpers/code-review.md +15 -1
  158. package/.agents/workflows/helpers/deliver-digest.md +1 -1
  159. package/.agents/workflows/helpers/deliver-reference.md +2 -2
  160. package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
  161. package/.agents/workflows/mandrel-plan.md +2 -2
  162. package/docs/CHANGELOG.md +42 -0
  163. package/lib/cli/doctor-checks/codex.js +6 -5
  164. package/lib/cli/doctor-checks/llm-review.js +102 -0
  165. package/lib/cli/doctor-checks/project-access.js +20 -10
  166. package/lib/cli/doctor-checks/sync-parity.js +65 -140
  167. package/lib/cli/doctor-checks/test-credit-path.js +69 -28
  168. package/lib/cli/doctor-checks/toolchain.js +5 -3
  169. package/lib/cli/registry.js +5 -0
  170. package/lib/migrations/helpers/retire-agentrc-key.js +3 -3
  171. package/lib/migrations/index.js +6 -0
  172. package/lib/migrations/steps/2.91.0-move-shared-crap-capture-script.js +84 -0
  173. package/lib/migrations/steps/2.91.0-retire-duplication-formats.js +23 -0
  174. package/lib/migrations/steps/2.91.0-unset-null-lint-command.js +54 -0
  175. package/package.json +1 -3
@@ -21,6 +21,7 @@ import {
21
21
  import os from 'node:os';
22
22
  import path from 'node:path';
23
23
  import { fileURLToPath } from 'node:url';
24
+ import { parseGateArgv } from './lib/cli-args.js';
24
25
  import { runAsCli } from './lib/cli-utils.js';
25
26
  import { mainCheckoutRoot } from './lib/config/temp-paths.js';
26
27
  import {
@@ -326,44 +327,39 @@ export function assertNoReservedIdStreams({
326
327
  return 1;
327
328
  }
328
329
 
330
+ const MODE_FLAGS = ['--snapshot', '--assert', '--clean'];
331
+
329
332
  /**
330
333
  * @param {string[]} argv
331
334
  * @returns {{ mode: 'snapshot'|'assert'|'clean', apply: boolean, ids: number[]|null, repoRoot: string, baseline: string|null, lintGlobs: string[] }}
332
335
  */
333
336
  export function parseArgv(argv) {
334
- let mode = 'assert';
335
- let apply = false;
336
- let ids = null;
337
- let repoRoot = REPO_ROOT;
338
- let baseline = null;
339
- let lintGlobs = [];
340
- for (let i = 0; i < argv.length; i += 1) {
341
- const arg = argv[i];
342
- if (arg === '--snapshot') mode = 'snapshot';
343
- else if (arg === '--assert') mode = 'assert';
344
- else if (arg === '--clean') mode = 'clean';
345
- else if (arg === '--yes') apply = true;
346
- else if (arg === '--lint-globs') {
347
- i += 1;
348
- lintGlobs = String(argv[i] ?? '')
349
- .split(',')
350
- .map((s) => s.trim())
351
- .filter(Boolean);
352
- } else if (arg === '--ids') {
353
- i += 1;
354
- ids = String(argv[i] ?? '')
355
- .split(',')
356
- .map((s) => Number(s.trim()))
357
- .filter((n) => Number.isInteger(n) && n > 0);
358
- } else if (arg === '--root') {
359
- i += 1;
360
- repoRoot = path.resolve(String(argv[i] ?? '.'));
361
- } else if (arg === '--baseline') {
362
- i += 1;
363
- baseline = path.resolve(String(argv[i] ?? '.'));
364
- }
365
- }
366
- return { mode, apply, ids, repoRoot, baseline, lintGlobs };
337
+ const values = parseGateArgv(argv, {
338
+ strings: ['lint-globs', 'ids', 'root', 'baseline'],
339
+ booleans: ['yes'],
340
+ });
341
+ const modeFlag = argv.filter((arg) => MODE_FLAGS.includes(arg)).at(-1);
342
+ return {
343
+ mode: modeFlag ? modeFlag.slice(2) : 'assert',
344
+ apply: values.yes,
345
+ ids:
346
+ values.ids === null
347
+ ? null
348
+ : splitList(values.ids)
349
+ .map(Number)
350
+ .filter((n) => Number.isInteger(n) && n > 0),
351
+ repoRoot: values.root === null ? REPO_ROOT : path.resolve(values.root),
352
+ baseline: values.baseline === null ? null : path.resolve(values.baseline),
353
+ lintGlobs: splitList(values['lint-globs'] ?? ''),
354
+ };
355
+ }
356
+
357
+ /** @param {string} raw */
358
+ function splitList(raw) {
359
+ return raw
360
+ .split(',')
361
+ .map((s) => s.trim())
362
+ .filter(Boolean);
367
363
  }
368
364
 
369
365
  /**
@@ -1,9 +1,10 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * Ensures `coverage/coverage-final.json` is fresh before the CRAP gate: skip
4
- * when the gate is off, no changed file is under `crap.targetDirs`, or the
5
- * content-digest stamp matches; otherwise run `test:coverage` (or, under
6
- * `coverage.captureScope: "affected"`, the consumer's `test:coverage:affected`)
3
+ * Ensures the coverage artifact (`coverage.coveragePath`) is fresh before the
4
+ * coverage and CRAP gates: skip when both are off, no changed file is under
5
+ * `crap.targetDirs`, or the content-digest stamp matches; otherwise run the
6
+ * coverage gate's `captureScript` as `<pm> run <script>` (or, under
7
+ * `coverage.captureScope: "affected"`, the consumer's affected variant)
7
8
  * behind the host-level full-suite lock and stamp on success. A green run that
8
9
  * leaves no artifact at `coveragePath` fails (exit 1) and is never stamped.
9
10
  * An own CRAP source gets a second, always full-scope pass via
@@ -31,6 +32,7 @@ import {
31
32
  import { tryScopedCapture } from './lib/coverage-capture-affected.js';
32
33
  import { runFullScopeCapture } from './lib/coverage-capture-fullscope.js';
33
34
  import {
35
+ captureGates,
34
36
  captureRefusal,
35
37
  runCapturePasses,
36
38
  } from './lib/coverage-capture-passes.js';
@@ -102,9 +104,15 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
102
104
  const lockHooks = lockEventHooks(claimLockEventSink(env));
103
105
  const args = parseArgs(argv);
104
106
  const config = resolveConfigImpl({ cwd: args.cwd });
105
- const { crap, coverage } = getQualityImpl(config);
107
+ const { crap, coverage } = captureGates(getQualityImpl(config));
106
108
  const scripts = readPackageScriptsImpl(args.cwd);
107
- const refused = captureRefusal({ crap, scripts, hasNpmScriptImpl, logger });
109
+ const refused = captureRefusal({
110
+ crap,
111
+ coverage,
112
+ scripts,
113
+ hasNpmScriptImpl,
114
+ logger,
115
+ });
108
116
  if (refused !== null) return refused;
109
117
 
110
118
  // Outermost first: the credit probe announces or refuses the run, and only
@@ -7,10 +7,9 @@
7
7
  * never a ticket comment. With no resolvable Story the write is skipped: a
8
8
  * missing signal beats a halted runner.
9
9
  */
10
- import { spawnSync } from 'node:child_process';
11
10
  import crypto from 'node:crypto';
12
11
  import { constants as osConstants } from 'node:os';
13
- import { INTERCEPTOR_MAX_BUFFER_BYTES } from './lib/child-exec.js';
12
+ import { REPORTED_MAX_BUFFER_BYTES, spawnChild } from './lib/child-exec.js';
14
13
  import { getLimits, resolveConfig } from './lib/config-resolver.js';
15
14
  import { Logger } from './lib/Logger.js';
16
15
  import { appendSignal } from './lib/observability/signals-writer.js';
@@ -85,6 +84,8 @@ const OVERFLOW_ERROR_CODE = 'ENOBUFS';
85
84
 
86
85
  const SIGNAL_EXIT_BASE = 128;
87
86
 
87
+ const BYTES_PER_MIB = 1024 * 1024;
88
+
88
89
  /**
89
90
  * For a `null` status, which must never reach `process.exit` (null exits 0).
90
91
  * SIGTERM + ENOBUFS = buffer overflow, SIGTERM otherwise = timeout, any other
@@ -125,7 +126,7 @@ function describeAbnormalExit(
125
126
  const shapes = {
126
127
  'buffer-overflow': {
127
128
  category: 'Tool Limitation',
128
- remediation: ` - ${signal} was sent because the command's output overflowed the interceptor's executionMaxBuffer bound (${executionMaxBuffer} bytes / 10 MiB) — the executionTimeoutMs bound (${executionTimeoutMs}ms) did not fire. Do NOT split the command into smaller steps: quieten or redirect its output, or raise the buffer bound.`,
129
+ remediation: ` - ${signal} was sent because the command's output overflowed the interceptor's executionMaxBuffer bound (${executionMaxBuffer} bytes / ${executionMaxBuffer / BYTES_PER_MIB} MiB) — the executionTimeoutMs bound (${executionTimeoutMs}ms) did not fire. Do NOT split the command into smaller steps: quieten or redirect its output, or raise the buffer bound.`,
129
130
  extraDetails: { executionMaxBuffer },
130
131
  },
131
132
  'interceptor-timeout': {
@@ -220,18 +221,15 @@ export async function main(args = process.argv.slice(2)) {
220
221
 
221
222
  const config = resolveConfig();
222
223
  const { executionTimeoutMs } = getLimits();
223
- // Deliberately below `MAX_BUFFER_BYTES`: a reported policy bound, not an
224
- // overflow guard.
225
- const executionMaxBuffer = INTERCEPTOR_MAX_BUFFER_BYTES;
224
+ // Reported, never passed: the wrapper applies its own ceiling, so the row
225
+ // names the bound that actually fires on an overflow.
226
+ const executionMaxBuffer = REPORTED_MAX_BUFFER_BYTES;
226
227
 
227
228
  const commandStr = cmdArgs.join(' ');
228
229
  Logger.error(`[Diagnostic Interceptor] Executing: ${commandStr}`);
229
230
 
230
- const result = spawnSync(cmdArgs[0], cmdArgs.slice(1), {
231
- stdio: 'pipe',
232
- encoding: 'utf-8',
231
+ const result = spawnChild(cmdArgs[0], cmdArgs.slice(1), {
233
232
  timeout: executionTimeoutMs,
234
- maxBuffer: executionMaxBuffer,
235
233
  });
236
234
 
237
235
  if (result.stdout) process.stdout.write(result.stdout);
@@ -81,6 +81,11 @@ export function renderWorkflowsDoc(catalog, loopCatalog = []) {
81
81
  '`.agents/skills/workflows/<name>/SKILL.md`, invoked as `$<name>` (e.g.',
82
82
  '`$mandrel-plan`; loop units as `$loops-<name>`). Each skill points Codex at',
83
83
  'the workflow file and passes the text after `$<name>` as its arguments.',
84
+ 'A `$loops-<name>` unit runs once per invocation: Codex has no `/loop`',
85
+ 'cadence, so re-invoke it (or schedule it) to iterate. At close, the default',
86
+ "review chain's `llm-review` entry reviews through `codex exec` when `claude`",
87
+ "is absent (`claude` wins when both are present); `mandrel doctor`'s",
88
+ '`llm-review-provider` check names the CLI that will serve it.',
84
89
  '`npm run sync:agents` likewise writes the role agents a workflow dispatches',
85
90
  '(`subagent_type: <role>`) as Codex custom agents',
86
91
  '`.codex/agents/mandrel-<role>.toml`; Codex loads those only in a trusted',
@@ -13,6 +13,7 @@ import { dependencyPins } from './dependency-pins.js';
13
13
  import { dependencyPolicy } from './dependency-policy.js';
14
14
  import { inlineSuppressions } from './inline-suppressions.js';
15
15
  import { scaExceptions } from './sca-exceptions.js';
16
+ import { shortcutMarkers } from './shortcut-markers.js';
16
17
  import { testSkips } from './test-skips.js';
17
18
  import { toolConfig } from './tool-config.js';
18
19
 
@@ -27,4 +28,5 @@ export const ADAPTERS = Object.freeze([
27
28
  ciGates,
28
29
  testSkips,
29
30
  codeAllowlists,
31
+ shortcutMarkers,
30
32
  ]);
@@ -10,6 +10,7 @@
10
10
  import { insideString } from '../locate.js';
11
11
  import { readText } from '../read.js';
12
12
  import { makeRecord } from '../record.js';
13
+ import { sourceScanAdapter } from './source-scan.js';
13
14
 
14
15
  const SCANNED_EXT_RE =
15
16
  /\.(?:[cm]?[jt]sx?|vue|svelte|astro|mdx?|css|scss|html)$/;
@@ -63,10 +64,36 @@ function matchLine(line) {
63
64
  }
64
65
 
65
66
  /** A pure comment line directly above, used when the directive carries no reason. */
67
+ function isPlainComment(text) {
68
+ return /^(?:\/\/|\/\*|\*|<!--)/.test(text) && !matchLine(text);
69
+ }
70
+
71
+ function commentBody(text) {
72
+ return text.replace(/^(?:\/\/+|\/\*+|\*+|<!--)\s*|\s*(?:\*\/|-->)$/g, '');
73
+ }
74
+
66
75
  function reasonAbove(lines, i) {
67
76
  const prev = lines[i - 1]?.trim() ?? '';
68
- if (!/^(?:\/\/|\/\*|\*|<!--)/.test(prev) || matchLine(prev)) return null;
69
- return prev.replace(/^(?:\/\/+|\/\*+|\*+|<!--)\s*|\s*(?:\*\/|-->)$/g, '');
77
+ return isPlainComment(prev) ? commentBody(prev) : null;
78
+ }
79
+
80
+ function reasonFor(hit, lines, i) {
81
+ return (
82
+ hit.reason?.replace(/\s*(?:\*\/|-->)\s*$/, '') || reasonAbove(lines, i)
83
+ );
84
+ }
85
+
86
+ function suppressionRecord(file, line, hit, reason) {
87
+ return makeRecord({
88
+ adapter: 'inline-suppressions',
89
+ category: 'inline',
90
+ surface: hit.tool,
91
+ file,
92
+ line,
93
+ target: hit.rule,
94
+ rule: `${hit.tool}:${hit.rule}`,
95
+ justification: reason,
96
+ });
70
97
  }
71
98
 
72
99
  function fileRecords(ctx, file) {
@@ -74,34 +101,16 @@ function fileRecords(ctx, file) {
74
101
  const records = [];
75
102
  lines.forEach((line, i) => {
76
103
  const hit = matchLine(line);
77
- if (!hit) return;
78
- const reason =
79
- hit.reason?.replace(/\s*(?:\*\/|-->)\s*$/, '') || reasonAbove(lines, i);
80
- records.push(
81
- makeRecord({
82
- adapter: 'inline-suppressions',
83
- category: 'inline',
84
- surface: hit.tool,
85
- file,
86
- line: i + 1,
87
- target: hit.rule,
88
- rule: `${hit.tool}:${hit.rule}`,
89
- justification: reason,
90
- }),
91
- );
104
+ if (hit)
105
+ records.push(
106
+ suppressionRecord(file, i + 1, hit, reasonFor(hit, lines, i)),
107
+ );
92
108
  });
93
109
  return records;
94
110
  }
95
111
 
96
- export const inlineSuppressions = Object.freeze({
112
+ export const inlineSuppressions = sourceScanAdapter({
97
113
  id: 'inline-suppressions',
98
- category: 'inline',
99
- applies: (ctx) =>
100
- ctx.scope.files.some((f) => SCANNED_EXT_RE.test(f))
101
- ? { applies: true, reason: 'source files present' }
102
- : { applies: false, reason: 'no scannable source files' },
103
- extract: (ctx) =>
104
- ctx.scope.files
105
- .filter((f) => SCANNED_EXT_RE.test(f))
106
- .flatMap((f) => fileRecords(ctx, f)),
114
+ extRe: SCANNED_EXT_RE,
115
+ fileRecords,
107
116
  });
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Deliberate-shortcut markers: `shortcut: <ceiling>, <trigger>` comments. The
3
+ * trigger rides as the justification, so the shared classifier reads a named
4
+ * trigger as `live`, a passed date as `expired`, a closed `until #N` as
5
+ * `orphaned`, and a missing trigger as `unjustified`.
6
+ *
7
+ * @module lib/audit-exceptions/adapters/shortcut-markers
8
+ */
9
+
10
+ import { insideString } from '../locate.js';
11
+ import { readText } from '../read.js';
12
+ import { makeRecord } from '../record.js';
13
+ import { sourceScanAdapter } from './source-scan.js';
14
+
15
+ const SCANNED_EXT_RE =
16
+ /\.(?:[cm]?[jt]sx?|vue|svelte|astro|mdx?|css|scss|html|py|go|rs|rb|java|kt|swift|cs|php|sh)$/;
17
+
18
+ const MARKER_RE = /(?:\/\/+|\/\*+|#+|<!--|^\s*\*)\s*shortcut:\s*(.*)$/g;
19
+
20
+ function stripCloser(text) {
21
+ return text.replace(/\s*(?:\*\/|-->)\s*$/, '').trim();
22
+ }
23
+
24
+ /** A bare date or `when #N` trigger gets the `until` lead the expiry and ticket readers key on. */
25
+ function withUntilLead(trigger) {
26
+ return /^(?:when\s+)?(?:#\d|\d{4}-\d{2}-\d{2}\b)/.test(trigger)
27
+ ? `until ${trigger}`
28
+ : trigger;
29
+ }
30
+
31
+ function parse(text) {
32
+ const body = stripCloser(text);
33
+ const comma = body.indexOf(',');
34
+ if (comma === -1) return { ceiling: body, trigger: '' };
35
+ return {
36
+ ceiling: body.slice(0, comma).trim(),
37
+ trigger: withUntilLead(body.slice(comma + 1).trim()),
38
+ };
39
+ }
40
+
41
+ function markerRecord(file, line, { ceiling, trigger }) {
42
+ return makeRecord({
43
+ adapter: 'shortcut-markers',
44
+ category: 'inline',
45
+ surface: 'shortcut-marker',
46
+ file,
47
+ line,
48
+ target: ceiling,
49
+ rule: trigger ? 'has-trigger' : 'no-trigger',
50
+ justification: trigger || null,
51
+ probe: trigger ? { verdict: 'live', basis: 'trigger-named' } : null,
52
+ });
53
+ }
54
+
55
+ function fileRecords(ctx, file) {
56
+ const records = [];
57
+ (readText(ctx.root, file) ?? '').split('\n').forEach((line, i) => {
58
+ const hit = [...line.matchAll(MARKER_RE)][0];
59
+ if (hit && !insideString(line, hit.index)) {
60
+ records.push(markerRecord(file, i + 1, parse(hit[1])));
61
+ }
62
+ });
63
+ return records;
64
+ }
65
+
66
+ export const shortcutMarkers = sourceScanAdapter({
67
+ id: 'shortcut-markers',
68
+ extRe: SCANNED_EXT_RE,
69
+ fileRecords,
70
+ });
@@ -0,0 +1,26 @@
1
+ /**
2
+ * The shared shell of an adapter that scans source files line by line for an
3
+ * inline comment shape: it applies when any scoped file matches `extRe`, and
4
+ * extracts `fileRecords(ctx, file)` over each matching file.
5
+ *
6
+ * @module lib/audit-exceptions/adapters/source-scan
7
+ */
8
+
9
+ /**
10
+ * @param {{ id: string, extRe: RegExp, fileRecords: (ctx: object, file: string) => object[] }} spec
11
+ * @returns {Readonly<object>}
12
+ */
13
+ export function sourceScanAdapter({ id, extRe, fileRecords }) {
14
+ return Object.freeze({
15
+ id,
16
+ category: 'inline',
17
+ applies: (ctx) =>
18
+ ctx.scope.files.some((f) => extRe.test(f))
19
+ ? { applies: true, reason: 'source files present' }
20
+ : { applies: false, reason: 'no scannable source files' },
21
+ extract: (ctx) =>
22
+ ctx.scope.files
23
+ .filter((f) => extRe.test(f))
24
+ .flatMap((f) => fileRecords(ctx, f)),
25
+ });
26
+ }
@@ -20,6 +20,7 @@ export const AUDIT_LENSES = Object.freeze([
20
20
  'devops',
21
21
  'documentation',
22
22
  'exceptions',
23
+ 'lean',
23
24
  'mobile',
24
25
  'navigability',
25
26
  'performance',
@@ -5,8 +5,7 @@
5
5
  import { readFileSync } from 'node:fs';
6
6
  import path from 'node:path';
7
7
  import { fileURLToPath } from 'node:url';
8
- import Ajv from 'ajv';
9
- import addFormats from 'ajv-formats';
8
+ import { createAjv } from './util/ajv.js';
10
9
 
11
10
  const __filename = fileURLToPath(import.meta.url);
12
11
  const __dirname = path.dirname(__filename);
@@ -50,11 +49,10 @@ export const BASELINE_SCHEMA_FILES = Object.freeze([
50
49
  * Build an AJV instance with the envelope and every per-kind baseline schema
51
50
  * pre-registered. Throws if any schema file is unreadable or fails to compile.
52
51
  *
53
- * @returns {Ajv} configured AJV with all baseline schemas registered.
52
+ * @returns {import('ajv').default} configured AJV with all baseline schemas registered.
54
53
  */
55
54
  export function buildBaselineSchemaAjv() {
56
- const ajv = new Ajv({ allErrors: true, strict: false });
57
- addFormats(ajv);
55
+ const ajv = createAjv({ allErrors: true, strict: false });
58
56
  for (const filename of BASELINE_SCHEMA_FILES) {
59
57
  const filePath = path.join(BASELINE_SCHEMAS_DIR, filename);
60
58
  const schema = JSON.parse(readFileSync(filePath, 'utf8'));
@@ -10,10 +10,11 @@
10
10
  import nodeFs from 'node:fs';
11
11
  import path from 'node:path';
12
12
  import { gzipSync } from 'node:zlib';
13
- import { Minimatch } from 'minimatch';
13
+ import picomatch from 'picomatch';
14
+ import { toPosix, walkFiles } from '../util/paths.js';
14
15
 
15
16
  /** Directories a bundle glob never descends into. */
16
- const SKIPPED_DIRS = new Set(['.git', 'node_modules']);
17
+ const SKIPPED_DIRS = ['.git', 'node_modules'];
17
18
 
18
19
  /**
19
20
  * @param {number} bytes
@@ -36,25 +37,6 @@ function staticBase(segments) {
36
37
  return base.join('/');
37
38
  }
38
39
 
39
- /**
40
- * @param {string} absDir
41
- * @param {typeof nodeFs} fs
42
- * @returns {string[]} Absolute file paths under `absDir`.
43
- */
44
- function walkFiles(absDir, fs) {
45
- if (!fs.existsSync(absDir)) return [];
46
- const out = [];
47
- for (const entry of fs.readdirSync(absDir, { withFileTypes: true })) {
48
- const abs = path.join(absDir, entry.name);
49
- if (entry.isDirectory()) {
50
- if (!SKIPPED_DIRS.has(entry.name)) out.push(...walkFiles(abs, fs));
51
- } else if (entry.isFile()) {
52
- out.push(abs);
53
- }
54
- }
55
- return out;
56
- }
57
-
58
40
  /**
59
41
  * Repo-relative files a bundle `path` (literal or glob) matches, sorted.
60
42
  *
@@ -65,17 +47,18 @@ function walkFiles(absDir, fs) {
65
47
  */
66
48
  function resolveBundleFiles(pattern, cwd, fs = nodeFs) {
67
49
  const posix = pattern.replace(/\\/g, '/').replace(/^\.\//, '');
68
- const matcher = new Minimatch(posix, { dot: true });
69
- if (!matcher.hasMagic()) {
50
+ if (!picomatch.scan(posix).isGlob) {
70
51
  const abs = path.resolve(cwd, posix);
71
52
  return fs.existsSync(abs) && fs.statSync(abs).isFile() ? [abs] : [];
72
53
  }
54
+ const isMatch = picomatch(posix, { dot: true });
73
55
  const base = staticBase(posix.split('/'));
74
- return walkFiles(path.resolve(cwd, base), fs)
75
- .filter((abs) =>
76
- matcher.match(path.relative(cwd, abs).split(path.sep).join('/')),
77
- )
78
- .sort();
56
+ return walkFiles(path.resolve(cwd, base), {
57
+ skipDirs: SKIPPED_DIRS,
58
+ filter: (abs, dirent) =>
59
+ dirent.isFile() && isMatch(toPosix(path.relative(cwd, abs))),
60
+ fsImpl: fs,
61
+ }).sort();
79
62
  }
80
63
 
81
64
  /**
@@ -2,7 +2,7 @@
2
2
  // buckets for per-component floors. The `*` component is the whole-repo
3
3
  // rollup and matches every row; overlap between components is allowed.
4
4
 
5
- import { Minimatch } from 'minimatch';
5
+ import picomatch from 'picomatch';
6
6
 
7
7
  const DEFAULT_COMPONENTS = Object.freeze({ '*': Object.freeze(['**']) });
8
8
 
@@ -10,18 +10,18 @@ const DEFAULT_COMPONENTS = Object.freeze({ '*': Object.freeze(['**']) });
10
10
  * Compiled matchers keyed by glob: `groupRows` runs over tens of thousands of
11
11
  * rows, and re-parsing each glob per row dominated its cost.
12
12
  *
13
- * @type {Map<string, import('minimatch').Minimatch>}
13
+ * @type {Map<string, (path: string) => boolean>}
14
14
  */
15
15
  const GLOB_MATCHER_CACHE = new Map();
16
16
 
17
17
  /**
18
18
  * @param {string} glob
19
- * @returns {import('minimatch').Minimatch}
19
+ * @returns {(path: string) => boolean}
20
20
  */
21
21
  function matcherFor(glob) {
22
22
  let matcher = GLOB_MATCHER_CACHE.get(glob);
23
23
  if (!matcher) {
24
- matcher = new Minimatch(glob, { dot: true });
24
+ matcher = picomatch(glob, { dot: true });
25
25
  GLOB_MATCHER_CACHE.set(glob, matcher);
26
26
  }
27
27
  return matcher;
@@ -91,7 +91,7 @@ export function groupRows(rows, components, keyField = 'path') {
91
91
  const list = Array.isArray(globs) ? globs : [];
92
92
  for (const glob of list) {
93
93
  if (typeof glob !== 'string' || glob.length === 0) continue;
94
- if (matcherFor(glob).match(normalized)) {
94
+ if (matcherFor(glob)(normalized)) {
95
95
  buckets[name].push(row);
96
96
  break;
97
97
  }
@@ -2,7 +2,9 @@
2
2
  * The scan → compare → report tail of `preview-gates.js#runCrapPreview`, once
3
3
  * its baseline is loaded and judged compatible.
4
4
  */
5
+
5
6
  import path from 'node:path';
7
+ import { COVERAGE_CAPTURE_DEFAULTS } from '../config/gates/coverage.schema.js';
6
8
  import { loadCoverage } from '../coverage-utils.js';
7
9
  import {
8
10
  KERNEL_VERSION,
@@ -81,7 +83,8 @@ export async function computeCrapPreviewScan({
81
83
  ? crap.ignoreGlobs
82
84
  : [];
83
85
  const requireCoverage = crap.requireCoverage !== false;
84
- const coveragePath = crap.coveragePath ?? 'coverage/coverage-final.json';
86
+ const coveragePath =
87
+ crap.coveragePath ?? COVERAGE_CAPTURE_DEFAULTS.coveragePath;
85
88
  const coverage = loadCoverage(path.resolve(cwd, coveragePath));
86
89
  // The configured tolerance keeps the preview aligned with the authoritative
87
90
  // gate: deltas at or under it are demoted, not failed.
@@ -6,6 +6,7 @@
6
6
  */
7
7
 
8
8
  import path from 'node:path';
9
+ import { COVERAGE_CAPTURE_DEFAULTS } from '../config/gates/coverage.schema.js';
9
10
  import { getBaselines, getQuality, resolveConfig } from '../config-resolver.js';
10
11
  import {
11
12
  isCoverageFresh,
@@ -23,8 +24,6 @@ import {
23
24
  SeatRefusal,
24
25
  } from './seat-missing.js';
25
26
 
26
- const DEFAULT_COVERAGE_PATH = 'coverage/coverage-final.json';
27
-
28
27
  const DEFAULT_MIN_RESOLUTION_RATE = 0.75;
29
28
 
30
29
  /**
@@ -83,7 +82,9 @@ export function resolveCrapUpdaterOptions(
83
82
  }
84
83
  const baselinePath = args.baselinePath ?? baselines?.crap?.path;
85
84
  const coveragePath =
86
- args.coveragePath ?? crap.coveragePath ?? DEFAULT_COVERAGE_PATH;
85
+ args.coveragePath ??
86
+ crap.coveragePath ??
87
+ COVERAGE_CAPTURE_DEFAULTS.coveragePath;
87
88
  return {
88
89
  targetDirs: Array.isArray(crap.targetDirs) ? crap.targetDirs : [],
89
90
  ignoreGlobs: Array.isArray(crap.ignoreGlobs) ? crap.ignoreGlobs : [],
@@ -91,7 +92,8 @@ export function resolveCrapUpdaterOptions(
91
92
  minMethodResolutionRate:
92
93
  crap.minMethodResolutionRate ?? DEFAULT_MIN_RESOLUTION_RATE,
93
94
  coveragePath,
94
- captureScript: crap.captureScript ?? 'test:coverage',
95
+ captureScript:
96
+ crap.captureScript ?? COVERAGE_CAPTURE_DEFAULTS.captureScript,
95
97
  baselinePath,
96
98
  absBaselinePath: path.isAbsolute(baselinePath)
97
99
  ? baselinePath
@@ -6,15 +6,11 @@ import { readFileSync } from 'node:fs';
6
6
  import { createRequire } from 'node:module';
7
7
  import path from 'node:path';
8
8
  import { resolveDependencyVersion } from '../dependency-version.js';
9
+ import { jscpdFormatsFor } from '../source-extensions.js';
9
10
 
10
11
  const DEFAULT_MIN_TOKENS = 50;
11
- /** Mirrors the `gates.duplication.formats` schema default. */
12
- const DEFAULT_FORMATS = Object.freeze([
13
- 'javascript',
14
- 'jsx',
15
- 'typescript',
16
- 'tsx',
17
- ]);
12
+ /** Derived from the scorable-extension SSOT; deliberately not configurable. */
13
+ const SCAN_FORMATS = Object.freeze(jscpdFormatsFor());
18
14
 
19
15
  const require = createRequire(import.meta.url);
20
16
 
@@ -220,7 +216,6 @@ function anchorIgnoreGlobs(ignoreGlobs, cwd) {
220
216
  * targetDirs: string[],
221
217
  * cwd?: string,
222
218
  * minTokens?: number,
223
- * formats?: string[],
224
219
  * ignoreGlobs?: string[],
225
220
  * detect: (opts: object) => Promise<Array<object>>,
226
221
  * readLineCount?: (absPath: string) => number,
@@ -231,7 +226,6 @@ export async function scanDuplication({
231
226
  targetDirs,
232
227
  cwd = process.cwd(),
233
228
  minTokens = DEFAULT_MIN_TOKENS,
234
- formats = DEFAULT_FORMATS,
235
229
  ignoreGlobs = [],
236
230
  detect,
237
231
  readLineCount: readLineCountFn = readLineCount,
@@ -246,7 +240,7 @@ export async function scanDuplication({
246
240
  silent: true,
247
241
  gitignore: false,
248
242
  reporters: [],
249
- format: formats,
243
+ format: [...SCAN_FORMATS],
250
244
  minTokens,
251
245
  ignore: anchorIgnoreGlobs(ignoreGlobs, cwd),
252
246
  });
@@ -5,6 +5,7 @@
5
5
 
6
6
  import path from 'node:path';
7
7
  import { fileURLToPath } from 'node:url';
8
+ import { COVERAGE_CAPTURE_DEFAULTS } from '../../config/gates/coverage.schema.js';
8
9
  import {
9
10
  COORDINATE_ORIGINAL,
10
11
  COORDINATE_TRANSPILED,
@@ -461,7 +462,8 @@ export function assessComparisonBasis(compareResult, opts = {}) {
461
462
 
462
463
  /**
463
464
  * The CRAP capture script an operator hint names — the resolved
464
- * `gates.crap.captureScript` when the caller passes it, else the default.
465
+ * `gates.crap.captureScript` when the caller passes it, else the coverage
466
+ * gate's default.
465
467
  *
466
468
  * @param {{ captureScript?: string } | undefined} ctx
467
469
  * @returns {string}
@@ -469,7 +471,7 @@ export function assessComparisonBasis(compareResult, opts = {}) {
469
471
  function captureScriptOf(ctx) {
470
472
  return typeof ctx?.captureScript === 'string' && ctx.captureScript.length > 0
471
473
  ? ctx.captureScript
472
- : 'test:coverage';
474
+ : COVERAGE_CAPTURE_DEFAULTS.captureScript;
473
475
  }
474
476
 
475
477
  /** @param {{ captureScript?: string } | undefined} ctx */