mandrel 2.89.0 → 2.91.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 +38 -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/board-backfill.js +253 -0
  14. package/.agents/scripts/check-arch-cycles.js +1 -5
  15. package/.agents/scripts/check-context-budget.js +1 -5
  16. package/.agents/scripts/check-cyclomatic.js +1 -5
  17. package/.agents/scripts/check-dead-exports.js +23 -14
  18. package/.agents/scripts/check-doc-links.js +4 -4
  19. package/.agents/scripts/check-test-temp-hygiene.js +29 -33
  20. package/.agents/scripts/coverage-capture.js +14 -6
  21. package/.agents/scripts/diagnose-friction.js +8 -10
  22. package/.agents/scripts/generate-workflows-doc.js +5 -0
  23. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +2 -0
  24. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +36 -27
  25. package/.agents/scripts/lib/audit-exceptions/adapters/shortcut-markers.js +70 -0
  26. package/.agents/scripts/lib/audit-exceptions/adapters/source-scan.js +26 -0
  27. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  28. package/.agents/scripts/lib/baseline-schema-registry.js +3 -5
  29. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +11 -28
  30. package/.agents/scripts/lib/baselines/components.js +5 -5
  31. package/.agents/scripts/lib/baselines/crap-preview-scan.js +4 -1
  32. package/.agents/scripts/lib/baselines/crap-updater-cli.js +6 -4
  33. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -10
  34. package/.agents/scripts/lib/baselines/kinds/crap.js +4 -2
  35. package/.agents/scripts/lib/baselines/kinds/duplication.js +4 -2
  36. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +13 -6
  37. package/.agents/scripts/lib/baselines/refresh-service.js +10 -13
  38. package/.agents/scripts/lib/baselines/writer.js +4 -4
  39. package/.agents/scripts/lib/bdd-scenario-scanner.js +26 -31
  40. package/.agents/scripts/lib/bootstrap/gh-list.js +4 -5
  41. package/.agents/scripts/lib/bootstrap/gh-preflight.js +13 -8
  42. package/.agents/scripts/lib/child-exec.js +4 -4
  43. package/.agents/scripts/lib/claude/agents-projection.js +170 -0
  44. package/.agents/scripts/lib/claude/commands-projection.js +184 -0
  45. package/.agents/scripts/lib/close-validation/commands.js +28 -117
  46. package/.agents/scripts/lib/close-validation/gates.js +54 -48
  47. package/.agents/scripts/lib/close-validation/process.js +5 -1
  48. package/.agents/scripts/lib/close-validation/projections/crap.js +2 -1
  49. package/.agents/scripts/lib/close-validation/projections/maintainability.js +50 -15
  50. package/.agents/scripts/lib/config/agentrc-overlay.js +4 -7
  51. package/.agents/scripts/lib/config/commands.js +82 -7
  52. package/.agents/scripts/lib/config/explain.js +2 -1
  53. package/.agents/scripts/lib/config/gates/coverage.schema.js +39 -3
  54. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  55. package/.agents/scripts/lib/config/gates/crap.schema.js +5 -3
  56. package/.agents/scripts/lib/config/gates/duplication.schema.js +6 -11
  57. package/.agents/scripts/lib/config/gates/shared.js +2 -2
  58. package/.agents/scripts/lib/config/git-roots.js +120 -0
  59. package/.agents/scripts/lib/config/quality.js +46 -50
  60. package/.agents/scripts/lib/config/review-chain-default.js +4 -3
  61. package/.agents/scripts/lib/config/review-provider-clis.js +11 -0
  62. package/.agents/scripts/lib/config/temp-paths.js +3 -37
  63. package/.agents/scripts/lib/config-resolver.js +5 -9
  64. package/.agents/scripts/lib/config-settings-schema-delivery.js +2 -2
  65. package/.agents/scripts/lib/config-settings-schema-quality.js +3 -2
  66. package/.agents/scripts/lib/config-settings-schema.js +6 -7
  67. package/.agents/scripts/lib/coverage-baseline.js +2 -1
  68. package/.agents/scripts/lib/coverage-capture-affected.js +4 -3
  69. package/.agents/scripts/lib/coverage-capture-fullscope.js +3 -1
  70. package/.agents/scripts/lib/coverage-capture-passes.js +119 -34
  71. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  72. package/.agents/scripts/lib/coverage-capture.js +80 -43
  73. package/.agents/scripts/lib/coverage-utils.js +34 -16
  74. package/.agents/scripts/lib/cpu-pool.js +2 -4
  75. package/.agents/scripts/lib/crap-engine.js +19 -1
  76. package/.agents/scripts/lib/crap-utils.js +2 -1
  77. package/.agents/scripts/lib/dead-exports-knip.js +29 -11
  78. package/.agents/scripts/lib/detect-package-manager.js +13 -0
  79. package/.agents/scripts/lib/feedback-loop/graduator-gh.js +4 -2
  80. package/.agents/scripts/lib/full-suite-lock.js +25 -9
  81. package/.agents/scripts/lib/gates/baseline-store.js +2 -10
  82. package/.agents/scripts/lib/generated/agentrc-validator.js +4 -1
  83. package/.agents/scripts/lib/gh-env.js +72 -0
  84. package/.agents/scripts/lib/gh-exec.js +26 -1
  85. package/.agents/scripts/lib/maintainability-utils.js +8 -8
  86. package/.agents/scripts/lib/npm-scripts.js +1 -1
  87. package/.agents/scripts/lib/observability/signal-validator.js +2 -6
  88. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  89. package/.agents/scripts/lib/observability/terse-result.js +2 -6
  90. package/.agents/scripts/lib/orchestration/board-access-latch.js +112 -0
  91. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +10 -13
  92. package/.agents/scripts/lib/orchestration/column-sync.js +107 -52
  93. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  94. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +3 -3
  95. package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js +2 -6
  96. package/.agents/scripts/lib/orchestration/light-suitability.js +5 -7
  97. package/.agents/scripts/lib/orchestration/pr-watch.js +7 -7
  98. package/.agents/scripts/lib/orchestration/project-meta-cache.js +2 -11
  99. package/.agents/scripts/lib/orchestration/project-meta-resolver.js +44 -17
  100. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -9
  101. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +219 -0
  102. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +53 -5
  103. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +2 -2
  104. package/.agents/scripts/lib/orchestration/review-providers/llm-review.js +96 -0
  105. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  106. package/.agents/scripts/lib/orchestration/review-providers/native.js +13 -19
  107. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +3 -2
  108. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +2 -0
  109. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +11 -3
  110. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -3
  111. package/.agents/scripts/lib/orchestration/story-close/format-autofix.js +41 -15
  112. package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js +2 -4
  113. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +2 -13
  114. package/.agents/scripts/lib/orchestration/story-handoff.js +27 -6
  115. package/.agents/scripts/lib/orchestration/story-progress.js +3 -11
  116. package/.agents/scripts/lib/orchestration/ticketing/bulk.js +3 -5
  117. package/.agents/scripts/lib/orchestration/verify-credit.js +52 -28
  118. package/.agents/scripts/lib/single-story-sweep/protection-ctx.js +11 -11
  119. package/.agents/scripts/lib/single-story-sweep/protection.js +1 -9
  120. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +1 -5
  121. package/.agents/scripts/lib/source-extensions.js +30 -15
  122. package/.agents/scripts/lib/test-run-credit.js +1 -9
  123. package/.agents/scripts/lib/test-temp.js +22 -21
  124. package/.agents/scripts/lib/util/ajv.js +111 -0
  125. package/.agents/scripts/lib/util/atomic-write.js +30 -0
  126. package/.agents/scripts/lib/util/paths.js +51 -0
  127. package/.agents/scripts/lib/util/sleep.js +6 -0
  128. package/.agents/scripts/lib/util/slug.js +12 -0
  129. package/.agents/scripts/lib/validation-evidence.js +19 -40
  130. package/.agents/scripts/lib/worktree/lifecycle/force-drain.js +2 -1
  131. package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js +10 -28
  132. package/.agents/scripts/lib/worktree/lifecycle/reap.js +2 -2
  133. package/.agents/scripts/lib/worktree/node-modules-strategy.js +21 -14
  134. package/.agents/scripts/lint-issue-body.js +2 -2
  135. package/.agents/scripts/plan-context.js +2 -7
  136. package/.agents/scripts/providers/github/auth.js +3 -3
  137. package/.agents/scripts/providers/github/board-add.js +18 -9
  138. package/.agents/scripts/providers/github/errors.js +3 -1
  139. package/.agents/scripts/providers/github/gh-token-diagnostics.js +10 -7
  140. package/.agents/scripts/providers/github/issues.js +6 -2
  141. package/.agents/scripts/providers/github/mappers.js +1 -5
  142. package/.agents/scripts/providers/github/projects-v2-graphql.js +26 -6
  143. package/.agents/scripts/providers/github/search-budget.js +3 -1
  144. package/.agents/scripts/resolve-doc-tiers.js +7 -20
  145. package/.agents/scripts/sync-agentrc.js +5 -14
  146. package/.agents/scripts/sync-claude-agents.js +38 -150
  147. package/.agents/scripts/sync-claude-commands.js +35 -218
  148. package/.agents/scripts/update-coverage-baseline.js +1 -1
  149. package/.agents/scripts/update-crap-baseline.js +1 -1
  150. package/.agents/scripts/update-duplication-baseline.js +2 -16
  151. package/.agents/scripts/validate-skills.js +6 -10
  152. package/.agents/skills/core/code-review-and-quality/SKILL.md +3 -18
  153. package/.agents/skills/core/documentation-and-adrs/SKILL.md +4 -14
  154. package/.agents/workflows/audit-exceptions.md +9 -0
  155. package/.agents/workflows/audit-lean.md +129 -0
  156. package/.agents/workflows/helpers/audit-lens-core.md +7 -0
  157. package/.agents/workflows/helpers/code-quality-guardrails.md +21 -0
  158. package/.agents/workflows/helpers/code-review.md +15 -1
  159. package/.agents/workflows/helpers/deliver-digest.md +1 -1
  160. package/.agents/workflows/helpers/deliver-reference.md +2 -2
  161. package/.agents/workflows/mandrel-plan.md +2 -2
  162. package/docs/CHANGELOG.md +48 -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 +124 -0
  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 +11 -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
@@ -6,11 +6,8 @@
6
6
  import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
7
7
  import path from 'node:path';
8
8
  import { fileURLToPath } from 'node:url';
9
-
10
- import Ajv2020 from 'ajv/dist/2020.js';
11
- import addFormats from 'ajv-formats';
12
-
13
9
  import { storyLedgerPath } from '../../config/temp-paths.js';
10
+ import { createAjv2020 } from '../../util/ajv.js';
14
11
 
15
12
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
16
13
  const SCHEMA_DIR = path.resolve(
@@ -42,8 +39,7 @@ function getValidator(schemaFile) {
42
39
  const schema = JSON.parse(
43
40
  readFileSync(path.resolve(SCHEMA_DIR, schemaFile), 'utf8'),
44
41
  );
45
- const ajv = new Ajv2020({ allErrors: true, strict: false });
46
- addFormats(ajv);
42
+ const ajv = createAjv2020({ allErrors: true, strict: false });
47
43
  const validator = ajv.compile(schema);
48
44
  _validators.set(schemaFile, validator);
49
45
  return validator;
@@ -7,6 +7,7 @@
7
7
  * @module lib/orchestration/light-suitability
8
8
  */
9
9
 
10
+ import { slugifyLabel } from '../util/slug.js';
10
11
  import { deriveStoryShape, SHAPE_CODES } from './complexity-gate.js';
11
12
  import { deriveChangeLevel } from './review-depth.js';
12
13
 
@@ -387,13 +388,10 @@ const RECEIPT_SLUG_MAX = 48;
387
388
  * @returns {string}
388
389
  */
389
390
  function slugifyPrompt(text) {
390
- const slug = text
391
- .toLowerCase()
392
- .replace(/[^a-z0-9]+/g, '-')
393
- .replace(/^-+|-+$/g, '')
394
- .slice(0, RECEIPT_SLUG_MAX)
395
- .replace(/-+$/g, '');
396
- return slug === '' ? 'light-change' : slug;
391
+ return slugifyLabel(text, {
392
+ max: RECEIPT_SLUG_MAX,
393
+ fallback: 'light-change',
394
+ });
397
395
  }
398
396
 
399
397
  const RECEIPT_TITLE_MAX = 72;
@@ -5,7 +5,7 @@
5
5
  * skip or wait forever on a check. Returns a verdict; no side effects.
6
6
  */
7
7
 
8
- import { spawnSync } from 'node:child_process';
8
+ import { runGh as spawnGh } from '../gh-exec.js';
9
9
  import { defaultSleep } from '../util/sleep.js';
10
10
  import { applyBehindUpdate } from './behind-recovery.js';
11
11
  import { createCancelledRunDiscount } from './cancelled-run-discount.js';
@@ -31,12 +31,12 @@ function ghRepoFlag(repo) {
31
31
  return trimmed.length > 0 ? ['--repo', trimmed] : [];
32
32
  }
33
33
 
34
- function runGh(args, { cwd, repo, spawnFn = spawnSync }) {
35
- const result = spawnFn('gh', [...args, ...ghRepoFlag(repo)], {
36
- cwd,
37
- encoding: 'utf-8',
38
- shell: false,
39
- });
34
+ function runGh(args, { cwd, repo, spawnFn }) {
35
+ const result = spawnGh(
36
+ [...args, ...ghRepoFlag(repo)],
37
+ { cwd, encoding: 'utf-8', shell: false },
38
+ spawnFn,
39
+ );
40
40
  return {
41
41
  status: result.status ?? 1,
42
42
  stdout: result.stdout ?? '',
@@ -10,6 +10,7 @@
10
10
  import fs from 'node:fs';
11
11
  import path from 'node:path';
12
12
  import { anchorTempRoot, tempRootFrom } from '../config/temp-paths.js';
13
+ import { writeFileAtomic } from '../util/atomic-write.js';
13
14
 
14
15
  /** One hour spans a delivery run's cold flips yet forces periodic refresh. */
15
16
  const DEFAULT_META_TTL_MS = 60 * 60 * 1000;
@@ -58,17 +59,7 @@ function readCacheFile(filePath) {
58
59
 
59
60
  /** Tmp + rename: a reader never sees a partial write. Throws; reaps the tmp. */
60
61
  function writeStoreAtomic(filePath, store) {
61
- fs.mkdirSync(path.dirname(filePath), { recursive: true });
62
- const tmp = `${filePath}.${process.pid}.tmp`;
63
- try {
64
- fs.writeFileSync(tmp, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
65
- fs.renameSync(tmp, filePath);
66
- } catch (err) {
67
- try {
68
- fs.unlinkSync(tmp);
69
- } catch {}
70
- throw err;
71
- }
62
+ writeFileAtomic(filePath, `${JSON.stringify(store, null, 2)}\n`);
72
63
  }
73
64
 
74
65
  /**
@@ -5,6 +5,14 @@
5
5
  * `projectV2 { … }` selection body as `projectFields`.
6
6
  */
7
7
 
8
+ import {
9
+ isProjectAccessFailure,
10
+ ProjectAccessError,
11
+ toProjectAccessError,
12
+ } from './board-access-latch.js';
13
+
14
+ export { ProjectAccessError };
15
+
8
16
  /**
9
17
  * Priority order. `viewer` (the ambient identity) is last so a configured
10
18
  * owner always wins.
@@ -42,8 +50,36 @@ function buildScopedQuery(scope, projectFields) {
42
50
  }
43
51
 
44
52
  /**
45
- * The first non-null `projectV2` node down the ladder; a throwing or null
46
- * rung is a miss. With no `owner`, only `viewer` is tried.
53
+ * One rung's `projectV2` node, or null for a miss. An owner miss (NOT_FOUND)
54
+ * and any other non-access error advance the ladder; a scope or auth refusal
55
+ * is raised as a `ProjectAccessError`.
56
+ */
57
+ async function queryRung(
58
+ provider,
59
+ scope,
60
+ { owner, projectNumber, projectFields },
61
+ ) {
62
+ const vars = scope.needsOwner
63
+ ? { owner, number: projectNumber }
64
+ : { number: projectNumber };
65
+ try {
66
+ const data = await provider.graphql(
67
+ buildScopedQuery(scope, projectFields),
68
+ vars,
69
+ );
70
+ return data?.[scope.root]?.projectV2 ?? null;
71
+ } catch (err) {
72
+ if (isProjectAccessFailure(err)) throw toProjectAccessError(err);
73
+ return null;
74
+ }
75
+ }
76
+
77
+ /**
78
+ * The first non-null `projectV2` node down the ladder. A null rung or an
79
+ * owner miss (NOT_FOUND — expected on two of three rungs) advances; a scope
80
+ * or auth refusal is identical on every rung, so it fails fast as a
81
+ * `ProjectAccessError` instead of being hidden by the ladder. With no
82
+ * `owner`, only `viewer` is tried.
47
83
  *
48
84
  * @param {{
49
85
  * provider: { graphql: Function },
@@ -52,6 +88,7 @@ function buildScopedQuery(scope, projectFields) {
52
88
  * projectFields: string,
53
89
  * }} args
54
90
  * @returns {Promise<object|null>} the resolved `projectV2` node, or null.
91
+ * @throws {ProjectAccessError} when the token cannot read the board.
55
92
  */
56
93
  export async function resolveProjectMeta(args) {
57
94
  const { provider, owner, projectNumber, projectFields } = args ?? {};
@@ -66,21 +103,11 @@ export async function resolveProjectMeta(args) {
66
103
 
67
104
  for (const scope of OWNER_SCOPES) {
68
105
  if (scope.needsOwner && !owner) continue;
69
-
70
- const query = buildScopedQuery(scope, projectFields);
71
- const vars = scope.needsOwner
72
- ? { owner, number: projectNumber }
73
- : { number: projectNumber };
74
-
75
- let data;
76
- try {
77
- data = await provider.graphql(query, vars);
78
- } catch {
79
- // Wrong owner type (NOT_FOUND) etc. — advance the ladder.
80
- continue;
81
- }
82
-
83
- const node = data?.[scope.root]?.projectV2;
106
+ const node = await queryRung(provider, scope, {
107
+ owner,
108
+ projectNumber,
109
+ projectFields,
110
+ });
84
111
  if (node) return node;
85
112
  }
86
113
 
@@ -14,9 +14,9 @@
14
14
 
15
15
  import { createHash } from 'node:crypto';
16
16
  import nodeFs from 'node:fs';
17
- import path from 'node:path';
18
17
 
19
18
  import { storyReviewDepositPath } from '../config/temp-paths.js';
19
+ import { writeFileAtomic } from '../util/atomic-write.js';
20
20
  import { resolveSharedBaseRef } from './review-base-ref.js';
21
21
 
22
22
  const DEPOSIT_KIND = 'story-review-deposit';
@@ -137,14 +137,7 @@ export function depositAsComputedReview(deposit) {
137
137
  */
138
138
  export function writeReviewDeposit(deposit, { config, fsImpl = nodeFs } = {}) {
139
139
  const target = storyReviewDepositPath(deposit.storyId, config);
140
- fsImpl.mkdirSync(path.dirname(target), { recursive: true });
141
- const tmpPath = `${target}.${process.pid}.tmp`;
142
- fsImpl.writeFileSync(
143
- tmpPath,
144
- `${JSON.stringify(deposit, null, 2)}\n`,
145
- 'utf8',
146
- );
147
- fsImpl.renameSync(tmpPath, target);
140
+ writeFileAtomic(target, `${JSON.stringify(deposit, null, 2)}\n`, { fsImpl });
148
141
  return target;
149
142
  }
150
143
 
@@ -0,0 +1,219 @@
1
+ /**
2
+ * review-providers/callers-context.js — the `<callers>` block for a `deep`
3
+ * review: lines outside the changed files that reference symbols the diff
4
+ * defines or removes, by `git grep` at the head ref. Every cap that drops
5
+ * context is reported so the provider records a degradation.
6
+ */
7
+
8
+ import { normalizeDepth } from './review-depth.js';
9
+
10
+ /** Widen after a measured review-time check. */
11
+ const CALLER_CONTEXT_DEPTHS = Object.freeze(['deep']);
12
+ const CALLERS_INSTRUCTION =
13
+ 'The <callers> block lists lines outside the diff that reference symbols ' +
14
+ 'the diff changes; a caller the change breaks is a finding.';
15
+
16
+ const CALLER_CAPS = Object.freeze({
17
+ maxSymbols: 20,
18
+ maxLinesPerSymbol: 25,
19
+ maxChars: 30_000,
20
+ });
21
+
22
+ const IDENT = '[A-Za-z_$][\\w$]*';
23
+ const DECLARATION_PATTERNS = Object.freeze([
24
+ new RegExp(`\\bfunction\\b\\s*\\*?\\s*(${IDENT})`, 'g'),
25
+ new RegExp(`\\bclass\\s+(${IDENT})`, 'g'),
26
+ new RegExp(`\\bexport\\s+(?:const|let|var)\\s+(${IDENT})`, 'g'),
27
+ ]);
28
+ const EXPORT_LIST = /\bexport\s*\{([^}]*)\}/g;
29
+ const NEW_FILE_HEADER = /^\+\+\+ b\/(.+)$/;
30
+ /** Comment prose ("the function returns…") declares nothing. */
31
+ const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*)/;
32
+
33
+ /** `export { A, B as C }` exports `A` and `C`. */
34
+ function exportListNames(list) {
35
+ const ident = new RegExp(`^${IDENT}$`);
36
+ return list
37
+ .split(',')
38
+ .map(
39
+ (entry) =>
40
+ entry
41
+ .trim()
42
+ .split(/\s+as\s+/)
43
+ .pop()
44
+ ?.trim() ?? '',
45
+ )
46
+ .filter((name) => ident.test(name) && name !== 'default');
47
+ }
48
+
49
+ function symbolsOnLine(line) {
50
+ const out = [];
51
+ for (const pattern of DECLARATION_PATTERNS) {
52
+ for (const match of line.matchAll(pattern)) out.push(match[1]);
53
+ }
54
+ for (const match of line.matchAll(EXPORT_LIST)) {
55
+ out.push(...exportListNames(match[1]));
56
+ }
57
+ return out;
58
+ }
59
+
60
+ /** Hunk bodies only, so `+++`/`---` headers never contribute. */
61
+ function scanDiff(diff) {
62
+ const found = new Set();
63
+ const files = [];
64
+ let inHunk = false;
65
+ for (const line of diff.split('\n')) {
66
+ if (line.startsWith('diff --git ')) {
67
+ inHunk = false;
68
+ continue;
69
+ }
70
+ if (!inHunk) {
71
+ const header = NEW_FILE_HEADER.exec(line);
72
+ if (header && !files.includes(header[1])) files.push(header[1]);
73
+ if (line.startsWith('@@')) inHunk = true;
74
+ continue;
75
+ }
76
+ for (const name of symbolsOnLine(changedCode(line))) found.add(name);
77
+ }
78
+ return { found, files };
79
+ }
80
+
81
+ /** The code of a `+`/`-` hunk line; `''` for context and comment-only lines. */
82
+ function changedCode(line) {
83
+ const body = line.slice(1);
84
+ if (!/^[+-]/.test(line) || COMMENT_LINE.test(body)) return '';
85
+ return body;
86
+ }
87
+
88
+ /** Longest first: short names grep noisily. */
89
+ function extractChangedSymbols(diff, maxSymbols = CALLER_CAPS.maxSymbols) {
90
+ const { found, files } = scanDiff(diff);
91
+ const ranked = [...found].sort(
92
+ (a, b) => b.length - a.length || a.localeCompare(b),
93
+ );
94
+ return {
95
+ symbols: ranked.slice(0, maxSymbols),
96
+ dropped: ranked.slice(maxSymbols),
97
+ files,
98
+ };
99
+ }
100
+
101
+ function callerGrepArgs(symbol, headRef, files) {
102
+ return [
103
+ 'grep',
104
+ '-n',
105
+ '-w',
106
+ '-F',
107
+ '-e',
108
+ symbol,
109
+ headRef,
110
+ '--',
111
+ '.',
112
+ ...files.map((file) => `:(exclude)${file}`),
113
+ ];
114
+ }
115
+
116
+ function formatHit(raw, headRef) {
117
+ const prefix = `${headRef}:`;
118
+ const rest = raw.startsWith(prefix) ? raw.slice(prefix.length) : raw;
119
+ const match = /^(.*?):(\d+):(.*)$/.exec(rest);
120
+ return match ? `${match[1]}:${match[2]}: ${match[3].trim()}` : null;
121
+ }
122
+
123
+ function readHits(result, headRef) {
124
+ if (result.status === 1) return [];
125
+ if (result.status !== 0) return null;
126
+ return result.stdout
127
+ .split('\n')
128
+ .map((raw) => formatHit(raw, headRef))
129
+ .filter((hit) => hit !== null);
130
+ }
131
+
132
+ function lookUpCallers({ symbols, files, headRef, cwd, gitSpawnFn, caps }) {
133
+ const sections = [];
134
+ const dropped = [];
135
+ let used = 0;
136
+ for (const symbol of symbols) {
137
+ const hits = readHits(
138
+ gitSpawnFn(cwd, ...callerGrepArgs(symbol, headRef, files)),
139
+ headRef,
140
+ );
141
+ if (hits === null) {
142
+ dropped.push(`${symbol} (lookup failed)`);
143
+ continue;
144
+ }
145
+ if (hits.length === 0) continue;
146
+ const kept = hits.slice(0, caps.maxLinesPerSymbol);
147
+ const section = `## ${symbol}\n${kept.join('\n')}\n`;
148
+ if (used + section.length > caps.maxChars) {
149
+ dropped.push(`${symbol} (total cap)`);
150
+ continue;
151
+ }
152
+ if (hits.length > kept.length) {
153
+ dropped.push(`${symbol} (${hits.length - kept.length} lines over cap)`);
154
+ }
155
+ sections.push(section);
156
+ used += section.length;
157
+ }
158
+ return { sections, dropped };
159
+ }
160
+
161
+ function buildCallersContext({
162
+ diff,
163
+ headRef,
164
+ cwd,
165
+ gitSpawnFn,
166
+ caps = CALLER_CAPS,
167
+ }) {
168
+ const extracted = extractChangedSymbols(diff, caps.maxSymbols);
169
+ const { sections, dropped } = lookUpCallers({
170
+ symbols: extracted.symbols,
171
+ files: extracted.files,
172
+ headRef,
173
+ cwd,
174
+ gitSpawnFn,
175
+ caps,
176
+ });
177
+ const body =
178
+ sections.length > 0
179
+ ? sections.join('\n')
180
+ : '(no references to changed symbols outside the changed files)\n';
181
+ return {
182
+ body,
183
+ dropped: [
184
+ ...extracted.dropped.map((symbol) => `${symbol} (symbol cap)`),
185
+ ...dropped,
186
+ ],
187
+ };
188
+ }
189
+
190
+ /**
191
+ * The instruction plus `<callers>` block at `deep` ('' below it), and a
192
+ * degradation `reason` when a cap or lookup left a symbol unchecked.
193
+ * `caps` overrides the 20 / 25 / 30,000 limits (tests).
194
+ */
195
+ export function buildCallersSection({
196
+ diff,
197
+ input,
198
+ cwd,
199
+ gitSpawnFn,
200
+ caps = CALLER_CAPS,
201
+ }) {
202
+ if (!CALLER_CONTEXT_DEPTHS.includes(normalizeDepth(input.depth))) {
203
+ return { text: '', reason: null };
204
+ }
205
+ const { body, dropped } = buildCallersContext({
206
+ diff,
207
+ headRef: input.headRef,
208
+ cwd,
209
+ gitSpawnFn,
210
+ caps,
211
+ });
212
+ return {
213
+ text: `\n${CALLERS_INSTRUCTION}\n\n<callers>\n${body}</callers>\n`,
214
+ reason:
215
+ dropped.length > 0
216
+ ? `callers block incomplete; not checked: ${dropped.join(', ')}`
217
+ : null,
218
+ };
219
+ }
@@ -12,6 +12,9 @@
12
12
  * A missing CLI throws at construction (the chain entry is optional). A
13
13
  * review with no verdict records one degraded gate via `getDegradations()`
14
14
  * and returns no findings, so "never ran" cannot read as "found nothing".
15
+ * A review that reached a verdict still records what it did not check — a
16
+ * truncated diff, a capped `<callers>` block (depth `deep` only) — beside
17
+ * its findings.
15
18
  *
16
19
  * @typedef {import('./types.js').Finding} Finding
17
20
  * @typedef {import('./types.js').ReviewInput} ReviewInput
@@ -25,6 +28,7 @@ import path from 'node:path';
25
28
  import { spawnCaptureAsync } from '../../child-exec.js';
26
29
  import { gitSpawn } from '../../git-utils.js';
27
30
  import { PROJECT_ROOT } from '../../project-root.js';
31
+ import { buildCallersSection } from './callers-context.js';
28
32
  import {
29
33
  clip,
30
34
  FINDINGS_SCHEMA_JSON,
@@ -51,7 +55,7 @@ const CLAUDE_ARGS = Object.freeze([
51
55
  const AUTH_ARGS = Object.freeze(['auth', 'status', '--json']);
52
56
  const INVOKE_TIMEOUT_MS = 10 * 60 * 1000;
53
57
  const AUTH_TIMEOUT_MS = 15 * 1000;
54
- /** Larger diffs are truncated; the reviewer is told so. */
58
+ /** Larger diffs are truncated; the reviewer is told so and a degradation is recorded. */
55
59
  const MAX_DIFF_CHARS = 200_000;
56
60
  const DEGRADATION_BASE = Object.freeze({
57
61
  tool: 'code-review',
@@ -67,19 +71,45 @@ const PROMPT_HEAD =
67
71
  'caller. Do not report style, naming, refactoring ideas, missing tests or ' +
68
72
  'anything you would merge anyway. For each problem give the file, the ' +
69
73
  'line in the new version, why it is wrong, and how to show it fails (an ' +
70
- 'input, command or test that exposes it).\n\n' +
74
+ 'input, command or test that exposes it). A `shortcut:` comment naming ' +
75
+ 'its ceiling and trigger is a decision, not a finding, unless this diff ' +
76
+ 'itself crosses the ceiling.\n\n' +
71
77
  'The diff below is authoritative — files on disk may not reflect it. ' +
72
78
  'Answer with a JSON object of this exact shape, no prose around it:\n\n' +
73
79
  '{"findings":[{"title":"...","body":"Why it is wrong: ... How to show it ' +
74
80
  'fails: ...","file":"...","line":1,"category":"bug"}]}\n\n' +
75
81
  'Emit {"findings":[]} if there is nothing you would block the merge for.\n\n';
76
82
 
83
+ /**
84
+ * The truncation degradation reason, or null when the diff fits: the
85
+ * unreviewed character count and the files whose first header is past the cut.
86
+ *
87
+ * @param {string} diff
88
+ * @returns {string|null}
89
+ */
90
+ function truncationReason(diff) {
91
+ if (diff.length <= MAX_DIFF_CHARS) return null;
92
+ const firstHeader = new Map();
93
+ for (const match of diff.matchAll(/^\+\+\+ b\/(.+)$/gm)) {
94
+ if (!firstHeader.has(match[1])) firstHeader.set(match[1], match.index);
95
+ }
96
+ const unreviewedFiles = [...firstHeader.values()].filter(
97
+ (index) => index >= MAX_DIFF_CHARS,
98
+ ).length;
99
+ return (
100
+ `diff truncated at ${MAX_DIFF_CHARS} characters: ` +
101
+ `${diff.length - MAX_DIFF_CHARS} characters and ${unreviewedFiles} ` +
102
+ 'file(s) not reviewed'
103
+ );
104
+ }
105
+
77
106
  /**
78
107
  * @param {ReviewInput} input
79
108
  * @param {string} diff
109
+ * @param {string} callers - the `<callers>` section, or '' below `deep`.
80
110
  * @returns {string}
81
111
  */
82
- function buildPrompt(input, diff) {
112
+ function buildPrompt(input, diff, callers) {
83
113
  const truncated = diff.length > MAX_DIFF_CHARS;
84
114
  const body = truncated ? diff.slice(0, MAX_DIFF_CHARS) : diff;
85
115
  const note = truncated
@@ -89,7 +119,7 @@ function buildPrompt(input, diff) {
89
119
  .replace('{headRef}', input.headRef)
90
120
  .replace('{ticketId}', String(input.ticketId))
91
121
  .replace('{depthDirective}', renderDepthDirective(input.depth));
92
- return `${head}<diff>\n${body}${note}\n</diff>\n`;
122
+ return `${head}<diff>\n${body}${note}\n</diff>\n${callers}`;
93
123
  }
94
124
 
95
125
  /**
@@ -222,6 +252,12 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
222
252
  /** @type {GateDegradation[]} */
223
253
  let degradations = [];
224
254
 
255
+ /** Record a not-checked slice without replacing the findings. */
256
+ function noteDegradation(reason) {
257
+ degradations.push({ ...DEGRADATION_BASE, reason });
258
+ deps.logger?.warn?.(`[code-review] Not checked: ${reason}.`);
259
+ }
260
+
225
261
  function settle(verdict) {
226
262
  if (!('reason' in verdict)) return verdict.findings;
227
263
  degradations.push({ ...DEGRADATION_BASE, reason: verdict.reason });
@@ -236,8 +272,20 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
236
272
  const diff = readDiff(gitSpawnFn, input);
237
273
  if ('reason' in diff) return settle(diff);
238
274
  if (diff.text.trim().length === 0) return [];
275
+ const truncation = truncationReason(diff.text);
276
+ if (truncation) noteDegradation(truncation);
277
+ const callers = buildCallersSection({
278
+ diff: diff.text,
279
+ input,
280
+ cwd: PROJECT_ROOT,
281
+ gitSpawnFn,
282
+ });
283
+ if (callers.reason) noteDegradation(callers.reason);
239
284
  return settle(
240
- await reviewInTempDir(buildPrompt(input, diff.text), runDeps),
285
+ await reviewInTempDir(
286
+ buildPrompt(input, diff.text, callers.text),
287
+ runDeps,
288
+ ),
241
289
  );
242
290
  },
243
291
  getDegradations() {
@@ -14,9 +14,9 @@
14
14
  import fs from 'node:fs';
15
15
  import path from 'node:path';
16
16
  import { spawnCaptureAsync, spawnChild } from '../../child-exec.js';
17
+ import { resolveAgentrcRoot } from '../../config/git-roots.js';
17
18
  import { resolvedTempRoot } from '../../config/temp-paths.js';
18
19
  import { resolveConfig } from '../../config-resolver.js';
19
- import { PROJECT_ROOT } from '../../project-root.js';
20
20
  import { PROVIDER_SEVERITY_MAP } from './provider-severity.js';
21
21
  import { renderDepthDirective } from './review-depth.js';
22
22
 
@@ -130,7 +130,7 @@ export async function invokeCodexExec(args, deps = {}) {
130
130
  const execArgs = ['exec', '--sandbox', 'read-only', '--ephemeral'];
131
131
  execArgs.push('--output-schema', schemaPath, '-o', lastMessagePath, '-');
132
132
  const result = await spawnCaptureAsync('codex', execArgs, {
133
- cwd: deps.cwd ?? PROJECT_ROOT,
133
+ cwd: deps.cwd ?? resolveAgentrcRoot(),
134
134
  input: buildReviewPrompt(args),
135
135
  shell: IS_WINDOWS,
136
136
  timeout: INVOKE_TIMEOUT_MS,
@@ -0,0 +1,96 @@
1
+ /**
2
+ * review-providers/llm-review.js — the default chain's host-portable LLM
3
+ * review: the first available of `code-review` (`claude --print`) then
4
+ * `codex` (`codex exec`), chosen once at construction. First-available, not
5
+ * both-optional, so a host with both CLIs pays for one LLM review per Story.
6
+ * Neither CLI throws, so an `optional: true` entry skips with one warning.
7
+ *
8
+ * @typedef {import('./types.js').ReviewProvider} ReviewProvider
9
+ * @typedef {import('./degraded-gates.js').GateDegradation} GateDegradation
10
+ */
11
+
12
+ import { REVIEW_PROVIDER_CLIS } from '../../config/review-provider-clis.js';
13
+ import { createCodeReviewProviderForRegistry } from './code-review.js';
14
+ import {
15
+ CODEX_REMEDIATIONS,
16
+ createCodexProvider,
17
+ defaultProbeCodexCommand,
18
+ } from './codex.js';
19
+ import { probeClaudeCli } from './security-review.js';
20
+
21
+ /** The delegate each CLI serves: what it probes and what it runs. */
22
+ const DELEGATE_BY_CLI = Object.freeze({
23
+ claude: { name: 'code-review', cli: 'claude', runs: 'claude --print' },
24
+ codex: { name: 'codex', cli: 'codex', runs: 'codex exec' },
25
+ });
26
+
27
+ /**
28
+ * @returns {Error}
29
+ */
30
+ export function buildLlmReviewUnavailableError() {
31
+ return new Error(
32
+ '[ReviewProviderFactory] codeReview provider "llm-review" found neither ' +
33
+ 'the `claude` CLI nor the `codex` CLI on PATH. Install the Claude Code ' +
34
+ 'CLI so `claude --version` succeeds. Or: ' +
35
+ `${CODEX_REMEDIATIONS.install} ${CODEX_REMEDIATIONS.fallback}`,
36
+ );
37
+ }
38
+
39
+ /**
40
+ * The first delegate whose CLI answers, or null.
41
+ *
42
+ * @param {{ probeClaudeFn?: () => boolean, probeCodexFn?: () => boolean }} [deps]
43
+ * @returns {(typeof DELEGATE_BY_CLI)[keyof typeof DELEGATE_BY_CLI] | null}
44
+ */
45
+ export function resolveLlmReviewDelegate(deps = {}) {
46
+ const probes = {
47
+ claude: deps.probeClaudeFn ?? probeClaudeCli,
48
+ codex: deps.probeCodexFn ?? defaultProbeCodexCommand,
49
+ };
50
+ const cli = REVIEW_PROVIDER_CLIS['llm-review'].find((c) => probes[c]());
51
+ return DELEGATE_BY_CLI[cli] ?? null;
52
+ }
53
+
54
+ /**
55
+ * @param {{
56
+ * probeClaudeFn?: () => boolean,
57
+ * probeCodexFn?: () => boolean,
58
+ * createCodeReviewFn?: (deps: object) => ReviewProvider,
59
+ * createCodexFn?: (deps: object) => ReviewProvider,
60
+ * logger?: { info?: Function, warn?: Function },
61
+ * }} [deps] - the `create*Fn` seams build the chosen delegate; it is handed
62
+ * a pre-passed probe so the CLI is not probed twice.
63
+ * @returns {ReviewProvider & { delegate: string, getDegradations: () => GateDegradation[] }}
64
+ */
65
+ export function createLlmReviewProvider(deps = {}) {
66
+ const chosen = resolveLlmReviewDelegate(deps);
67
+ if (!chosen) throw buildLlmReviewUnavailableError();
68
+ const build =
69
+ chosen.name === 'code-review'
70
+ ? (deps.createCodeReviewFn ?? createCodeReviewProviderForRegistry)
71
+ : (deps.createCodexFn ?? createCodexProvider);
72
+ const delegate = build({ probeFn: () => true, logger: deps.logger });
73
+ const logger = deps.logger;
74
+
75
+ return {
76
+ delegate: chosen.name,
77
+ async runReview(input) {
78
+ logger?.info?.(
79
+ `[llm-review] Reviewing through ${chosen.name} (${chosen.runs}).`,
80
+ );
81
+ return delegate.runReview(input);
82
+ },
83
+ getDegradations() {
84
+ return typeof delegate.getDegradations === 'function'
85
+ ? delegate.getDegradations()
86
+ : [];
87
+ },
88
+ };
89
+ }
90
+
91
+ /**
92
+ * @returns {ReviewProvider}
93
+ */
94
+ export function createLlmReviewProviderForRegistry() {
95
+ return createLlmReviewProvider();
96
+ }