mandrel 2.95.0 → 2.97.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 (33) hide show
  1. package/.agents/audit-checklists/policies.md +23 -0
  2. package/.agents/audit-checklists/red-team.md +20 -0
  3. package/.agents/docs/agentrc-reference.json +2 -5
  4. package/.agents/docs/configuration.md +8 -6
  5. package/.agents/docs/workflows.md +4 -1
  6. package/.agents/schemas/agentrc.schema.json +46 -29
  7. package/.agents/schemas/audit-rules.json +48 -0
  8. package/.agents/schemas/audit-rules.schema.json +2 -2
  9. package/.agents/scripts/lib/audit-suite/selector.js +119 -27
  10. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +2 -0
  11. package/.agents/scripts/lib/baselines/duplication-scanner.js +44 -3
  12. package/.agents/scripts/lib/baselines/refresh-service.js +54 -14
  13. package/.agents/scripts/lib/config/explain.js +1 -7
  14. package/.agents/scripts/lib/config/gates/duplication.schema.js +12 -5
  15. package/.agents/scripts/lib/config-settings-schema-quality.js +0 -27
  16. package/.agents/scripts/lib/config-settings-schema.js +30 -0
  17. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  18. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +2 -14
  19. package/.agents/scripts/lib/orchestration/review-providers/generated-diff.js +61 -0
  20. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +19 -4
  21. package/.agents/scripts/lib/source-extensions.js +3 -2
  22. package/.agents/scripts/lint-issue-body.js +65 -10
  23. package/.agents/workflows/audit-documentation.md +5 -0
  24. package/.agents/workflows/audit-policies.md +221 -0
  25. package/.agents/workflows/audit-red-team.md +191 -0
  26. package/.agents/workflows/audit-security.md +4 -1
  27. package/.agents/workflows/mandrel-leverage.md +199 -0
  28. package/.agents/workflows/mandrel-plan.md +3 -1
  29. package/docs/CHANGELOG.md +23 -0
  30. package/lib/migrations/index.js +2 -0
  31. package/lib/migrations/steps/2.91.0-retire-duplication-formats.js +65 -9
  32. package/lib/migrations/steps/2.97.0-retire-quality-navigability.js +80 -0
  33. package/package.json +1 -1
@@ -10,8 +10,6 @@ import { jscpdFormatsFor } from '../source-extensions.js';
10
10
  import { toPosix } from '../util/paths.js';
11
11
 
12
12
  const DEFAULT_MIN_TOKENS = 50;
13
- /** Derived from the scorable-extension SSOT; deliberately not configurable. */
14
- const SCAN_FORMATS = Object.freeze(jscpdFormatsFor());
15
13
 
16
14
  const require = createRequire(import.meta.url);
17
15
 
@@ -42,6 +40,45 @@ function loadJscpd(requireFn) {
42
40
  }
43
41
  }
44
42
 
43
+ /**
44
+ * Extend-only: no input can drop a scorable format.
45
+ *
46
+ * @param {unknown} additionalFormats
47
+ * @returns {string[]}
48
+ */
49
+ function scanFormatsFor(additionalFormats) {
50
+ const extra = Array.isArray(additionalFormats) ? additionalFormats : [];
51
+ return [...new Set([...jscpdFormatsFor(), ...extra])];
52
+ }
53
+
54
+ /**
55
+ * Dot-prefixed extensions from jscpd's own format table. The tokenizer is
56
+ * resolved through jscpd: it is transitive, so pnpm-isolated installs do not
57
+ * hoist it. An unknown name throws rather than scanning nothing.
58
+ *
59
+ * @param {string[]} formats
60
+ * @param {NodeJS.Require} [requireFn] substitutes the module resolver
61
+ * @returns {Set<string>}
62
+ */
63
+ export function resolveFormatExtensions(formats, requireFn = require) {
64
+ if (!Array.isArray(formats) || formats.length === 0) return new Set();
65
+ loadJscpd(requireFn);
66
+ const { FORMATS } = createRequire(requireFn.resolve('jscpd'))(
67
+ '@jscpd/tokenizer',
68
+ );
69
+ const unknown = formats.filter((name) => !Object.hasOwn(FORMATS, name));
70
+ if (unknown.length > 0) {
71
+ throw new Error(
72
+ `[Duplication] unknown jscpd format(s) in duplication.additionalFormats: ${unknown.join(', ')}`,
73
+ );
74
+ }
75
+ return new Set(
76
+ formats.flatMap((name) =>
77
+ FORMATS[name].exts.map((ext) => `.${ext.toLowerCase()}`),
78
+ ),
79
+ );
80
+ }
81
+
45
82
  /**
46
83
  * Lazy CJS load: jscpd's ESM entry has a broken transitive `colors/safe`
47
84
  * specifier under strict ESM resolution, and importers that never scan should
@@ -213,6 +250,7 @@ function anchorIgnoreGlobs(ignoreGlobs, cwd) {
213
250
  * cwd?: string,
214
251
  * minTokens?: number,
215
252
  * ignoreGlobs?: string[],
253
+ * additionalFormats?: string[],
216
254
  * detect: (opts: object) => Promise<Array<object>>,
217
255
  * readLineCount?: (absPath: string) => number,
218
256
  * }} params
@@ -223,6 +261,7 @@ export async function scanDuplication({
223
261
  cwd = process.cwd(),
224
262
  minTokens = DEFAULT_MIN_TOKENS,
225
263
  ignoreGlobs = [],
264
+ additionalFormats = [],
226
265
  detect,
227
266
  readLineCount: readLineCountFn = readLineCount,
228
267
  }) {
@@ -230,13 +269,15 @@ export async function scanDuplication({
230
269
  throw new TypeError('scanDuplication: detect must be a function');
231
270
  }
232
271
  const dirs = Array.isArray(targetDirs) ? targetDirs : [];
272
+ // jscpd skips a format it does not know; refuse it instead.
273
+ resolveFormatExtensions(additionalFormats);
233
274
  const clones = await detect({
234
275
  path: dirs.map((dir) => toPosix(path.resolve(cwd, dir))),
235
276
  cwd,
236
277
  silent: true,
237
278
  gitignore: false,
238
279
  reporters: [],
239
- format: [...SCAN_FORMATS],
280
+ format: scanFormatsFor(additionalFormats),
240
281
  minTokens,
241
282
  ignore: anchorIgnoreGlobs(ignoreGlobs, cwd),
242
283
  });
@@ -34,7 +34,11 @@ import {
34
34
  import { isScorableSourceFile } from '../source-extensions.js';
35
35
  import { toPosix } from '../util/paths.js';
36
36
  import { buildBundleSizeScorer } from './bundle-size-scorer.js';
37
- import { resolveDetectClones, scanDuplication } from './duplication-scanner.js';
37
+ import {
38
+ resolveDetectClones,
39
+ resolveFormatExtensions,
40
+ scanDuplication,
41
+ } from './duplication-scanner.js';
38
42
  import { getKindModule } from './kernel.js';
39
43
  import { filterExcludedRows } from './kinds/maintainability.js';
40
44
  import { canonicalizeBaselinePath } from './path-canon.js';
@@ -53,21 +57,33 @@ const SUPPORTED_KINDS = Object.freeze([
53
57
  'bundle-size',
54
58
  ]);
55
59
 
60
+ /**
61
+ * Widened by `additionalFormats`.
62
+ *
63
+ * @param {{ additionalFormats?: string[] }} [opts]
64
+ * @returns {(p: string) => boolean}
65
+ */
66
+ function duplicationFileFilter({ additionalFormats } = {}) {
67
+ const extra = resolveFormatExtensions(additionalFormats);
68
+ if (extra.size === 0) return isScorableSourceFile;
69
+ return (p) =>
70
+ isScorableSourceFile(p) || extra.has(path.extname(p).toLowerCase());
71
+ }
72
+
56
73
  /**
57
74
  * Per-kind extension filter for diff-derived scope, over canonical POSIX paths.
58
75
  *
59
- * @type {Record<string, (p: string) => boolean>}
76
+ * @type {Record<string, (opts: object) => (p: string) => boolean>}
60
77
  */
61
- const KIND_FILE_PREDICATES = Object.freeze({
78
+ const KIND_FILE_FILTERS = Object.freeze({
62
79
  // The scanner walks exactly this set, so a scoped file it never scores
63
80
  // cannot trip the "produced no baseline rows" refusal.
64
- maintainability: isScorableSourceFile,
65
- crap: isScorableSourceFile,
66
- coverage: isScorableSourceFile,
67
- // jscpd's formats derive from the same set, so the scope matches the scan.
68
- duplication: isScorableSourceFile,
81
+ maintainability: () => isScorableSourceFile,
82
+ crap: () => isScorableSourceFile,
83
+ coverage: () => isScorableSourceFile,
84
+ duplication: duplicationFileFilter,
69
85
  // Bundle names are not paths: no changed file scopes a bundle row.
70
- 'bundle-size': () => false,
86
+ 'bundle-size': () => () => false,
71
87
  });
72
88
 
73
89
  /**
@@ -542,17 +558,40 @@ export async function deriveScopeFromDiff({
542
558
  }
543
559
 
544
560
  /**
561
+ * `opts.additionalFormats` widens only the duplication filter.
562
+ *
545
563
  * @param {string} kind
564
+ * @param {{ additionalFormats?: string[] }} [opts]
546
565
  * @returns {(p: string) => boolean}
547
566
  */
548
- export function fileFilterFor(kind) {
549
- const pred = KIND_FILE_PREDICATES[kind];
550
- if (!pred) {
567
+ export function fileFilterFor(kind, opts) {
568
+ const build = KIND_FILE_FILTERS[kind];
569
+ if (!build) {
551
570
  throw new Error(
552
571
  `fileFilterFor: no predicate registered for kind "${kind}"`,
553
572
  );
554
573
  }
555
- return pred;
574
+ return build(opts);
575
+ }
576
+
577
+ /**
578
+ * The diff-scope filter for `kind`.
579
+ * Best-effort config read:
580
+ * an unreadable config widens nothing.
581
+ *
582
+ * @param {string} kind
583
+ * @param {string} cwd
584
+ * @returns {(p: string) => boolean}
585
+ */
586
+ function diffScopeFilterFor(kind, cwd) {
587
+ let additionalFormats;
588
+ try {
589
+ additionalFormats = getQuality(resolveConfig({ cwd }))?.gates?.duplication
590
+ ?.additionalFormats;
591
+ } catch {
592
+ additionalFormats = undefined;
593
+ }
594
+ return fileFilterFor(kind, { additionalFormats });
556
595
  }
557
596
 
558
597
  /** Full, then explicit list, then diff-derived. */
@@ -577,7 +616,7 @@ async function resolveScope({
577
616
  const files = await deriveScopeFromDiff({
578
617
  baseRef,
579
618
  headRef,
580
- predicate: fileFilterFor(kind),
619
+ predicate: diffScopeFilterFor(kind, cwd),
581
620
  gitDiff,
582
621
  cwd,
583
622
  });
@@ -654,6 +693,7 @@ function buildDefaultDuplicationScorer({ cwd, config, quality, detect } = {}) {
654
693
  targetDirs,
655
694
  cwd: effectiveCwd,
656
695
  ignoreGlobs,
696
+ additionalFormats: dupCfg.additionalFormats,
657
697
  detect: detect ?? resolveDetectClones(),
658
698
  });
659
699
  };
@@ -86,7 +86,7 @@ const KEY_MEANINGS = Object.freeze({
86
86
 
87
87
  // planning.*
88
88
  'planning.navigation.routeGlobs':
89
- 'Glob patterns marking paths that add a user-facing route (plan-time reachability gate).',
89
+ 'Glob patterns marking paths that add a user-facing route (plan-time reachability gate, navigability lens, audit web probe).',
90
90
  'planning.navigation.navRegistry':
91
91
  'Tokens identifying the nav-registry SSOT a route-adding Story is expected to reference.',
92
92
 
@@ -127,12 +127,6 @@ const KEY_MEANINGS = Object.freeze({
127
127
  'When true, auto-file actionable retro proposals as follow-up issues.',
128
128
  'delivery.quality.requireBaselines':
129
129
  'When true, absent baseline artifacts fail close-validation instead of skipping cleanly.',
130
- 'delivery.quality.navigability.routeGlobs':
131
- 'Glob patterns marking user-facing routes for the navigability lens / journey gate.',
132
- 'delivery.quality.navigability.navRegistry':
133
- 'Tokens identifying the nav-registry SSOT the navigability lens expects.',
134
- 'delivery.quality.navigability.journeySuite':
135
- 'Optional journey-suite path the post-wave navigability integration gate runs.',
136
130
  'delivery.refactorStage.enabled':
137
131
  'Whether a dedicated refactor stage runs during delivery.',
138
132
  'delivery.acceptanceEval.maxRounds':
@@ -5,7 +5,7 @@ import { gateBase, LIST_OR_EXTENDER_OF_STRINGS } from './shared.js';
5
5
  export const DUPLICATION_GATE = {
6
6
  type: 'object',
7
7
  description:
8
- 'Code-duplication (DRY) gate (Story #3664). Shares the gate base and adds the scan-scope extras: the `targetDirs` the duplication scanner walks and `ignoreGlobs` to exclude files from the scan. The jscpd formats it reads are derived from the scorable-extension list every other gate scores (JavaScript, JSX, TypeScript, TSX), so they are not configurable (Story #5738).',
8
+ 'Code-duplication (DRY) gate (Story #3664). Shares the gate base and adds the scan-scope extras: the `targetDirs` the duplication scanner walks and `ignoreGlobs` to exclude files from the scan. The jscpd formats it reads always include the scorable-extension list every other gate scores (JavaScript, JSX, TypeScript, TSX, Story #5738); `additionalFormats` can only extend that list (Story #5849).',
9
9
  properties: {
10
10
  ...gateBase({
11
11
  enabled: false,
@@ -16,12 +16,19 @@ export const DUPLICATION_GATE = {
16
16
  targetDirs: {
17
17
  ...LIST_OR_EXTENDER_OF_STRINGS,
18
18
  description:
19
- "Directories whose scorable sources (`.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.tsx`, `.mts`, `.cts`) the duplication (DRY) gate scans for copy-paste clones. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal (Story #3664).",
19
+ "Directories whose scorable sources (`.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.tsx`, `.mts`, `.cts`), plus the files of any `additionalFormats`, the duplication (DRY) gate scans for copy-paste clones. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal (Story #3664).",
20
20
  default: ['src'],
21
21
  },
22
- // No `formats`: jscpd formats derive from `jscpdFormatsFor()`, and the
23
- // 2.91.0 migration `retire-duplication-formats` strips the old key from
24
- // `.agentrc.json` / `.agentrc.local.json` before this strict block sees it.
22
+ // No `formats`: the scorable jscpd formats derive from `jscpdFormatsFor()`,
23
+ // and the 2.91.0 migration `retire-duplication-formats` moves the old
24
+ // key's other languages into `additionalFormats` before stripping it.
25
+ additionalFormats: {
26
+ type: 'array',
27
+ items: { type: 'string', minLength: 1 },
28
+ description:
29
+ 'Extra jscpd format names (e.g. `python`, `go`) the duplication gate scans on top of the scorable formats it always reads. Extend-only: the scorable formats cannot be removed, and naming one here is a no-op. An unknown format name fails the scan rather than measuring nothing. The CRAP, MI, coverage and native-review gates still score only the scorable list (Story #5849).',
30
+ default: [],
31
+ },
25
32
  ignoreGlobs: {
26
33
  type: 'array',
27
34
  items: { type: 'string', minLength: 1 },
@@ -35,33 +35,6 @@ export const QUALITY_SCHEMA = {
35
35
  'Story #4495. Fail-closed baseline-enforcement policy for the unified check-baselines close-validation gate. When false (default), a consumer that enables baseline gates (crap/maintainability/…) but has not committed the corresponding baseline artifacts under baselines/ gets a clean skip-with-reason instead of a deterministic first-try close failure. Set true to keep the gate registered so an absent baseline artifact fails close-validation with a preflight hint naming the fix (the fail-closed posture).',
36
36
  default: false,
37
37
  },
38
- navigability: {
39
- type: 'object',
40
- description:
41
- "Navigability lens + journey-suite config (Epic #4131, F2/F3/F1/F4). Read by audit-suite/selector.js (route globs) and /mandrel-deliver's per-Story ceremony (journey suite). Opt-in: absent or empty routeGlobs degrades to a silent no-op.",
42
- properties: {
43
- routeGlobs: {
44
- type: 'array',
45
- items: { type: 'string' },
46
- description:
47
- 'Glob patterns (pages/**, app/**/route.ts) marking paths that add a user-facing route — the route-tree SSOT the navigability lens enumerates and the route-added routing predicate matches against.',
48
- default: [],
49
- },
50
- navRegistry: {
51
- type: 'array',
52
- items: { type: 'string' },
53
- description:
54
- 'Tokens identifying the nav-registry SSOT the navigability lens checks every route resolves a nav door against.',
55
- default: [],
56
- },
57
- journeySuite: {
58
- type: 'string',
59
- description:
60
- "Path or command for the per-persona journey suite /mandrel-deliver's per-Story ceremony runs.",
61
- },
62
- },
63
- additionalProperties: false,
64
- },
65
38
  },
66
39
  additionalProperties: false,
67
40
  };
@@ -141,6 +141,36 @@ const PROJECT_SCHEMA = {
141
141
  ],
142
142
  },
143
143
  commands: COMMANDS_SCHEMA,
144
+ policies: {
145
+ type: 'object',
146
+ description:
147
+ 'Published customer-facing policy corpus read by `/audit-policies`. Optional: absent means the lens and its applicability probe fall back to conventional policy file names (files under `policies/` or `legal/`, or basenames such as `privacy-policy` or `terms-of-service`).',
148
+ properties: {
149
+ corpusGlobs: {
150
+ type: 'array',
151
+ items: { type: 'string' },
152
+ description:
153
+ 'Globs naming where the published policy text lives (markdown, HTML, Astro or similar). Non-empty makes the project applicable for `/audit-policies` without a filesystem scan.',
154
+ },
155
+ impactMap: {
156
+ ...SAFE_STRING,
157
+ description:
158
+ 'Repo-relative path to a JSON object mapping code globs to arrays of policy paths; focuses a change-set-scoped `/audit-policies` run on the policies a change can invalidate.',
159
+ },
160
+ backingDocs: {
161
+ type: 'array',
162
+ items: { type: 'string' },
163
+ description:
164
+ 'Runbook or SOP globs. A policy claim a documented manual procedure honors is reported as backed, not as a finding.',
165
+ },
166
+ acceptedFindings: {
167
+ ...SAFE_STRING,
168
+ description:
169
+ 'Repo-relative path to a JSON array of `{ policy, quote, reason, reviewBy }` entries (`reviewBy` is `YYYY-MM-DD`). A matching unexpired entry suppresses the finding; an expired one is reported.',
170
+ },
171
+ },
172
+ additionalProperties: false,
173
+ },
144
174
  },
145
175
  additionalProperties: false,
146
176
  };