@holmes-lab/holmes-kit 0.40.0 → 0.41.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 (119) hide show
  1. package/CHANGELOG.md +312 -0
  2. package/README.md +79 -5
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-context.js +4 -3
  5. package/dist/holmes/cli/approve.js +22 -12
  6. package/dist/holmes/cli/autonomy.d.ts +21 -0
  7. package/dist/holmes/cli/autonomy.js +35 -5
  8. package/dist/holmes/cli/doctor.js +58 -6
  9. package/dist/holmes/cli/index.js +394 -267
  10. package/dist/holmes/cli/init.js +17 -6
  11. package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
  12. package/dist/holmes/cli/interactive-prompt.js +98 -16
  13. package/dist/holmes/cli/ledger-witness.d.ts +61 -0
  14. package/dist/holmes/cli/ledger-witness.js +212 -0
  15. package/dist/holmes/cli/playbook-skills.d.ts +3 -56
  16. package/dist/holmes/cli/playbook-skills.js +26 -349
  17. package/dist/holmes/config/config.d.ts +21 -0
  18. package/dist/holmes/config/config.js +22 -3
  19. package/dist/holmes/governance/approval-queue.d.ts +65 -1
  20. package/dist/holmes/governance/approval-queue.js +279 -9
  21. package/dist/holmes/governance/autonomous-shell.d.ts +13 -1
  22. package/dist/holmes/governance/autonomous-shell.js +157 -4
  23. package/dist/holmes/governance/autonomy.d.ts +216 -0
  24. package/dist/holmes/governance/autonomy.js +1162 -10
  25. package/dist/holmes/governance/install-manifest.d.ts +7 -4
  26. package/dist/holmes/governance/install-manifest.js +144 -14
  27. package/dist/holmes/governance/ledger-witness.d.ts +63 -0
  28. package/dist/holmes/governance/ledger-witness.js +296 -0
  29. package/dist/holmes/governance/provenance-chain.d.ts +8 -1
  30. package/dist/holmes/governance/provenance-chain.js +23 -4
  31. package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
  32. package/dist/holmes/governance/push-gate-runner.js +40 -3
  33. package/dist/holmes/governance/push-gate.d.ts +13 -2
  34. package/dist/holmes/governance/push-gate.js +106 -14
  35. package/dist/holmes/governance/recorded-pairs.d.ts +4 -0
  36. package/dist/holmes/governance/recorded-pairs.js +25 -1
  37. package/dist/holmes/governance/session-context.d.ts +7 -0
  38. package/dist/holmes/governance/session-context.js +34 -6
  39. package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
  40. package/dist/holmes/guardrail/advisory-line.js +718 -0
  41. package/dist/holmes/guardrail/anchor-scope-text.d.ts +9 -0
  42. package/dist/holmes/guardrail/anchor-scope-text.js +7 -0
  43. package/dist/holmes/guardrail/command-traits.d.ts +102 -0
  44. package/dist/holmes/guardrail/command-traits.js +379 -0
  45. package/dist/holmes/guardrail/fixtures/manager-builtins.json +23 -0
  46. package/dist/holmes/guardrail/fixtures/npm-commands.json +7 -0
  47. package/dist/holmes/guardrail/impact-gate.d.ts +6 -0
  48. package/dist/holmes/guardrail/impact-gate.js +32 -5
  49. package/dist/holmes/guardrail/outward-acts.d.ts +47 -0
  50. package/dist/holmes/guardrail/outward-acts.js +1102 -0
  51. package/dist/holmes/guardrail/refusal-codes.js +8 -1
  52. package/dist/holmes/guardrail/refusal-templates.d.ts +15 -0
  53. package/dist/holmes/guardrail/refusal-templates.js +71 -0
  54. package/dist/holmes/guardrail/risk-classifier.d.ts +22 -6
  55. package/dist/holmes/guardrail/risk-classifier.js +12 -118
  56. package/dist/holmes/guardrail/shell-lexer.d.ts +69 -0
  57. package/dist/holmes/guardrail/shell-lexer.js +567 -0
  58. package/dist/holmes/guardrail/write-target.js +7 -1
  59. package/dist/holmes/hooks/pre-tool-use.d.ts +71 -0
  60. package/dist/holmes/hooks/pre-tool-use.js +1466 -14
  61. package/dist/holmes/hooks/session-start.js +27 -1
  62. package/dist/holmes/hooks/stop.d.ts +7 -0
  63. package/dist/holmes/hooks/stop.js +39 -2
  64. package/dist/holmes/mcp/elicit-approval.d.ts +0 -21
  65. package/dist/holmes/mcp/elicit-approval.js +5 -2
  66. package/dist/holmes/mcp/handlers/approval-ask.js +3 -2
  67. package/dist/holmes/mcp/handlers/entity-integration.d.ts +1 -1
  68. package/dist/holmes/mcp/handlers/entity-integration.js +9 -6
  69. package/dist/holmes/mcp/handlers/entity-renumber.js +2 -1
  70. package/dist/holmes/mcp/handlers/entity-store.js +7 -2
  71. package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
  72. package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
  73. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -0
  74. package/dist/holmes/mcp/handlers/operator-inspection.js +25 -4
  75. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -1
  76. package/dist/holmes/mcp/handlers/spec-approval.js +28 -10
  77. package/dist/holmes/mcp/handlers/spec-lifecycle.js +10 -7
  78. package/dist/holmes/mcp/handlers/test-execution.d.ts +470 -3
  79. package/dist/holmes/mcp/handlers/test-execution.js +201 -21
  80. package/dist/holmes/mcp/handlers.d.ts +473 -8
  81. package/dist/holmes/mcp/handlers.js +6 -1
  82. package/dist/holmes/mcp/maintenance-analyze.d.ts +5 -0
  83. package/dist/holmes/mcp/maintenance-analyze.js +4 -2
  84. package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
  85. package/dist/holmes/mcp/maintenance-evidence.js +4 -1
  86. package/dist/holmes/mcp/tool-schemas.js +16 -10
  87. package/dist/holmes/project/baseline.d.ts +15 -2
  88. package/dist/holmes/project/baseline.js +11 -6
  89. package/dist/holmes/project/bounded-io.d.ts +1 -0
  90. package/dist/holmes/project/bounded-io.js +4 -2
  91. package/dist/holmes/project/change-source.d.ts +4 -0
  92. package/dist/holmes/project/change-source.js +13 -5
  93. package/dist/holmes/project/playbook-reference.d.ts +50 -0
  94. package/dist/holmes/project/playbook-reference.js +259 -0
  95. package/dist/holmes/project/playbook-skill-states.d.ts +94 -0
  96. package/dist/holmes/project/playbook-skill-states.js +396 -0
  97. package/dist/holmes/project/root.d.ts +9 -1
  98. package/dist/holmes/project/root.js +26 -3
  99. package/dist/holmes/project/running-package.d.ts +15 -0
  100. package/dist/holmes/project/running-package.js +87 -0
  101. package/dist/holmes/review/evidence-mode.d.ts +21 -0
  102. package/dist/holmes/review/evidence-mode.js +33 -0
  103. package/dist/holmes/review/head-worktree.d.ts +55 -0
  104. package/dist/holmes/review/head-worktree.js +329 -0
  105. package/dist/holmes/review/mrp.js +13 -3
  106. package/dist/holmes/review/run-provenance.d.ts +45 -0
  107. package/dist/holmes/review/run-provenance.js +314 -0
  108. package/dist/holmes/review/test-evidence.d.ts +174 -0
  109. package/dist/holmes/review/test-evidence.js +330 -2
  110. package/dist/holmes/review/test-reports.d.ts +94 -0
  111. package/dist/holmes/review/test-reports.js +382 -0
  112. package/dist/holmes/review/test-runner.d.ts +178 -65
  113. package/dist/holmes/review/test-runner.js +551 -319
  114. package/dist/holmes/review/test-units.d.ts +159 -0
  115. package/dist/holmes/review/test-units.js +814 -0
  116. package/dist/holmes/spec/entity-integration-transaction.d.ts +19 -2
  117. package/dist/holmes/spec/entity-integration-transaction.js +68 -7
  118. package/package.json +5 -2
  119. package/playbooks/publish/PLAYBOOK.md +2 -1
@@ -0,0 +1,9 @@
1
+ /**
2
+ * The anchor-scope refusal's text, in one place: the gate writes it, and the field report's tests produce it here
3
+ * instead of copying it by hand.
4
+ */
5
+ export interface AnchorScopeFailure {
6
+ id: string;
7
+ reason: string;
8
+ }
9
+ export declare function anchorScopeRefusal(relPath: string, failed: readonly AnchorScopeFailure[]): string;
@@ -0,0 +1,7 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.anchorScopeRefusal = anchorScopeRefusal;
4
+ function anchorScopeRefusal(relPath, failed) {
5
+ const each = failed.map((f) => `${relPath} is anchored to ${f.id} but falls outside its 'Files to Touch' scope (${f.reason})`).join('; ');
6
+ return `[Holmes-Kit] ${each} — extend that section first (spec edit is allowed), add it as a test under the anchored spec, or supply out-of-band approval`;
7
+ }
@@ -0,0 +1,102 @@
1
+ export declare const NPM_TABLE: {
2
+ commands: string[];
3
+ aliases: Record<string, string>;
4
+ dryRun: string[];
5
+ };
6
+ /** The npm command a word names, as npm's `deref` resolves it; undefined when npm would not run one. */
7
+ export declare function npmCommand(word: string): string | undefined;
8
+ export declare function npmHonoursDryRun(command: string): boolean;
9
+ /**
10
+ * A registry write: `true` for a command that writes, or a group whose writing sub-subcommands are listed with the
11
+ * ones that only read (a missing sub-subcommand reads; any other word is closed as a write).
12
+ */
13
+ export type WriteRule = true | {
14
+ writes: readonly string[];
15
+ reads: readonly string[];
16
+ };
17
+ /** npm's registry writes, by canonical command. */
18
+ export declare const NPM_WRITES: Readonly<Record<string, WriteRule>>;
19
+ /**
20
+ * The scripts an npm command runs, by canonical command (`run` runs the named one), and what `--ignore-scripts` skips
21
+ * (A-SPEC-794.71): for a script runner only the pre and post scripts (npm 11's run.js runs the named one), for a
22
+ * lifecycle command all of them. --dry-run skips none: run does not follow it, and publish runs prepublishOnly and
23
+ * postpublish under it (publish.js).
24
+ */
25
+ export interface ScriptRun {
26
+ names: readonly string[] | 'named';
27
+ ignoreSkips: 'prepost' | 'all';
28
+ }
29
+ export declare const NPM_SCRIPT_RUNS: Readonly<Record<string, ScriptRun>>;
30
+ /** Sub-subcommands that follow --dry-run by inheritance: npm's StagePublish extends Publish (stage/publish.js). */
31
+ export declare const NPM_DRY_RUN_SUBCOMMANDS: Readonly<Record<string, readonly string[]>>;
32
+ /** Whether a dry flag is on, read with its value: `--dry-run`, `--dry-run=<v>`, `--no-dry-run`; the last one wins. */
33
+ export declare function dryFlagOn(args: readonly string[], flags: readonly string[]): boolean;
34
+ /**
35
+ * Programs whose arguments are data (A-SPEC-794.71): only these exempt their arguments. Any other program — an unknown
36
+ * wrapper included — is read again from the first registry token among its arguments.
37
+ */
38
+ export declare const DATA_PROGRAMS: ReadonlySet<string>;
39
+ /** A-SPEC-794.74 — programs whose command-string positions are read (commandStrings); their other words are data. */
40
+ export declare const COMMAND_STRING_PROGRAMS: ReadonlySet<string>;
41
+ /** A-SPEC-794.74 — pnpm's names for a recursive run. */
42
+ export declare const PNPM_RECURSIVE: ReadonlySet<string>;
43
+ /** A release tool's own help and version flags: nothing is published. */
44
+ export declare const RELEASE_HELP: ReadonlySet<string>;
45
+ /** Program tokens that start a registry act when they appear among another program's arguments. */
46
+ export declare const REGISTRY_TOKENS: ReadonlySet<string>;
47
+ /** Options whose value is a command, by program; and programs whose positional arguments are commands. */
48
+ export declare const COMMAND_OPTIONS: Readonly<Record<string, readonly string[]>>;
49
+ export declare const POSITIONAL_COMMANDS: ReadonlySet<string>;
50
+ /** A package that runs a release tool's bin. */
51
+ export declare const PACKAGE_BINS: Readonly<Record<string, string>>;
52
+ /** A-SPEC-794.72 — the registry programs read as independent tokens in an unknown program's arguments. */
53
+ export declare const REGISTRY_PROGRAMS: ReadonlySet<string>;
54
+ /**
55
+ * A-SPEC-794.72 — programs that run the command after them: the subcommand they need, their valued options, the
56
+ * positional words before the command, whether `NAME=value` words come first, and the option after which the command
57
+ * starts. Push and publish share this one unwrapping.
58
+ */
59
+ export interface Wrapper {
60
+ sub?: string | readonly string[];
61
+ valued?: readonly string[];
62
+ positionals?: number;
63
+ assigns?: boolean;
64
+ commandFlag?: readonly string[];
65
+ toolArgs?: boolean;
66
+ }
67
+ export declare const WRAPPERS: Readonly<Record<string, Wrapper>>;
68
+ /** The command after a wrapper's own words, or null when the words do not run one. */
69
+ export declare function unwrapWith(w: Wrapper, args: readonly string[]): string[] | null;
70
+ /**
71
+ * A-SPEC-794.72 — the command strings a program runs, at the positions this table names. A string anywhere else is
72
+ * data. (Shells' -c, npx -c and npm exec -c are read where they were.)
73
+ */
74
+ export declare function commandStrings(name: string, args: readonly string[]): string[];
75
+ /** Runners that run scripts of the current package by name (globs allowed). */
76
+ export declare const SCRIPT_NAME_RUNNERS: ReadonlySet<string>;
77
+ /** npm options before the subcommand that take the next word as their value. */
78
+ export declare const NPM_VALUED_OPTIONS: ReadonlySet<string>;
79
+ /** A-SPEC-794.75 — `yarn workspaces foreach`'s valued options before the command it runs. */
80
+ export declare const YARN_FOREACH_VALUED: ReadonlySet<string>;
81
+ /** yarn: its own registry writes (v1 and berry's `npm` group) and its own subcommands (never a script name). */
82
+ export declare const YARN_WRITES: Readonly<Record<string, WriteRule>>;
83
+ export declare const YARN_NPM_WRITES: Readonly<Record<string, WriteRule>>;
84
+ export declare function managerBuiltins(tool: string): ReadonlySet<string>;
85
+ /** Release tools that publish: their dry-run flags, and the subcommand they need when they have one. */
86
+ export interface ReleaseTool {
87
+ dry: readonly string[];
88
+ needs?: (args: readonly string[]) => boolean;
89
+ }
90
+ export declare const RELEASE_TOOLS: Readonly<Record<string, ReleaseTool>>;
91
+ /** Runners that run a package script by name in every package: the script names they run, or null. */
92
+ export declare function runnerScripts(name: string, args: readonly string[]): string[] | null;
93
+ /** Shells whose `-c` string is a command, and that read their program from stdin without one. */
94
+ export declare const SHELL_PROGRAMS: RegExp;
95
+ /** Interpreters whose inline or stdin program is another language. */
96
+ export declare const INTERPRETERS: RegExp;
97
+ /** Their flag for an inline program. */
98
+ export declare const INLINE_FLAGS: ReadonlySet<string>;
99
+ /** Environment variables whose value a program runs as a command. */
100
+ export declare const COMMAND_VARIABLES: ReadonlySet<string>;
101
+ /** Programs that run the package named by their first positional word (with its version stripped). */
102
+ export declare const PACKAGE_RUNNERS: ReadonlySet<string>;
@@ -0,0 +1,379 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.PACKAGE_RUNNERS = exports.COMMAND_VARIABLES = exports.INLINE_FLAGS = exports.INTERPRETERS = exports.SHELL_PROGRAMS = exports.RELEASE_TOOLS = exports.YARN_NPM_WRITES = exports.YARN_WRITES = exports.YARN_FOREACH_VALUED = exports.NPM_VALUED_OPTIONS = exports.SCRIPT_NAME_RUNNERS = exports.WRAPPERS = exports.REGISTRY_PROGRAMS = exports.PACKAGE_BINS = exports.POSITIONAL_COMMANDS = exports.COMMAND_OPTIONS = exports.REGISTRY_TOKENS = exports.RELEASE_HELP = exports.PNPM_RECURSIVE = exports.COMMAND_STRING_PROGRAMS = exports.DATA_PROGRAMS = exports.NPM_DRY_RUN_SUBCOMMANDS = exports.NPM_SCRIPT_RUNS = exports.NPM_WRITES = exports.NPM_TABLE = void 0;
37
+ exports.npmCommand = npmCommand;
38
+ exports.npmHonoursDryRun = npmHonoursDryRun;
39
+ exports.dryFlagOn = dryFlagOn;
40
+ exports.unwrapWith = unwrapWith;
41
+ exports.commandStrings = commandStrings;
42
+ exports.managerBuiltins = managerBuiltins;
43
+ exports.runnerScripts = runnerScripts;
44
+ // @implements A-SPEC-794.80, A-SPEC-794.78, A-SPEC-794.76, A-SPEC-794.75, A-SPEC-794.74, A-SPEC-794.72, A-SPEC-794.71, A-SPEC-794.70, A-SPEC-794.69
45
+ /**
46
+ * What programs and subcommands do, in one table (A-SPEC-794.70): which subcommands of the package managers write to
47
+ * a registry, which follow --dry-run, which run package scripts (and which), which release tools publish, and which
48
+ * runners run a script by name. The outward judgement reads rows, not names: a new tool is a row.
49
+ *
50
+ * npm's spellings are npm's own: `fixtures/npm-commands.json` is frozen from npm's `lib/utils/cmd-list.js` (commands,
51
+ * aliases), and `npmCommand` resolves a word as npm's `deref` does (camelCase to kebab-case, exact command, alias, then
52
+ * a unique prefix of a command or an alias, followed through aliases). The dry-run set is the commands whose source
53
+ * reads `dry-run` (npm 11.17.0).
54
+ */
55
+ const table = __importStar(require("./fixtures/npm-commands.json"));
56
+ const builtins = __importStar(require("./fixtures/manager-builtins.json"));
57
+ exports.NPM_TABLE = {
58
+ commands: [...table.commands], aliases: { ...table.aliases }, dryRun: [...table.dryRun],
59
+ };
60
+ /** Every unique prefix of the command and alias names, as npm's `abbrev` builds it. */
61
+ const ABBREVS = (() => {
62
+ const names = [...new Set([...exports.NPM_TABLE.commands, ...Object.keys(exports.NPM_TABLE.aliases)])].sort();
63
+ const out = new Map();
64
+ for (const name of names) {
65
+ for (let k = 1; k <= name.length; k++) {
66
+ const p = name.slice(0, k);
67
+ if (p === name || !names.some((o) => o !== name && o.startsWith(p)))
68
+ out.set(p, name);
69
+ }
70
+ }
71
+ return out;
72
+ })();
73
+ /** The npm command a word names, as npm's `deref` resolves it; undefined when npm would not run one. */
74
+ function npmCommand(word) {
75
+ if (!word)
76
+ return undefined;
77
+ const c = /[A-Z]/.test(word) ? word.replace(/([A-Z])/g, (m) => `-${m.toLowerCase()}`) : word;
78
+ if (exports.NPM_TABLE.commands.includes(c))
79
+ return c;
80
+ if (Object.prototype.hasOwnProperty.call(exports.NPM_TABLE.aliases, c))
81
+ return exports.NPM_TABLE.aliases[c];
82
+ let a = ABBREVS.get(c);
83
+ while (a !== undefined && Object.prototype.hasOwnProperty.call(exports.NPM_TABLE.aliases, a))
84
+ a = exports.NPM_TABLE.aliases[a];
85
+ return a;
86
+ }
87
+ function npmHonoursDryRun(command) { return exports.NPM_TABLE.dryRun.includes(command); }
88
+ const group = (writes, reads) => ({ writes, reads });
89
+ /** npm's registry writes, by canonical command. */
90
+ exports.NPM_WRITES = {
91
+ publish: true, unpublish: true, deprecate: true, undeprecate: true, star: true, unstar: true,
92
+ 'dist-tag': group(['add', 'rm', 'set'], ['ls', 'list']),
93
+ owner: group(['add', 'rm', 'remove'], ['ls', 'list']),
94
+ access: group(['grant', 'revoke', 'set'], ['get', 'list', 'ls']),
95
+ team: group(['create', 'destroy', 'add', 'rm'], ['ls', 'list']),
96
+ token: group(['create', 'revoke'], ['list', 'ls']),
97
+ org: group(['set', 'rm'], ['ls', 'list']),
98
+ profile: group(['set', 'enable-2fa', 'disable-2fa'], ['get']),
99
+ stage: group(['publish', 'approve', 'reject'], ['list', 'view', 'download']),
100
+ trust: group(['github', 'gitlab', 'circleci', 'revoke'], ['list']),
101
+ };
102
+ const prepost = (s) => ({ names: [`pre${s}`, s, `post${s}`], ignoreSkips: 'prepost' });
103
+ exports.NPM_SCRIPT_RUNS = {
104
+ run: { names: 'named', ignoreSkips: 'prepost' }, test: prepost('test'), start: prepost('start'), stop: prepost('stop'),
105
+ restart: prepost('restart'),
106
+ // A-SPEC-794.74 — the install family runs the root package's install lifecycle; install-test also runs test
107
+ install: { names: ['preinstall', 'install', 'postinstall', 'prepare'], ignoreSkips: 'all' },
108
+ ci: { names: ['preinstall', 'install', 'postinstall', 'prepare'], ignoreSkips: 'all' },
109
+ rebuild: { names: ['preinstall', 'install', 'postinstall', 'prepare'], ignoreSkips: 'all' },
110
+ link: { names: ['preinstall', 'install', 'postinstall', 'prepare'], ignoreSkips: 'all' },
111
+ 'install-test': { names: ['preinstall', 'install', 'postinstall', 'prepare', 'pretest', 'test', 'posttest'], ignoreSkips: 'prepost' },
112
+ 'install-ci-test': { names: ['preinstall', 'install', 'postinstall', 'prepare', 'pretest', 'test', 'posttest'], ignoreSkips: 'prepost' },
113
+ version: { names: ['preversion', 'version', 'postversion'], ignoreSkips: 'all' },
114
+ pack: { names: ['prepack', 'prepare', 'postpack'], ignoreSkips: 'all' },
115
+ publish: { names: ['prepublishOnly', 'prepack', 'prepare', 'postpack', 'publish', 'postpublish'], ignoreSkips: 'all' },
116
+ };
117
+ /** Sub-subcommands that follow --dry-run by inheritance: npm's StagePublish extends Publish (stage/publish.js). */
118
+ exports.NPM_DRY_RUN_SUBCOMMANDS = { stage: ['publish'] };
119
+ /** Whether a dry flag is on, read with its value: `--dry-run`, `--dry-run=<v>`, `--no-dry-run`; the last one wins. */
120
+ function dryFlagOn(args, flags) {
121
+ let on = false;
122
+ for (let i = 0; i < args.length; i++) {
123
+ const a = args[i];
124
+ if (a === '--')
125
+ break;
126
+ for (const f of flags) {
127
+ // nopt: a boolean flag takes a following `true` or `false` as its value (A-SPEC-794.72)
128
+ if (a === f && /^(?:true|false)$/i.test(args[i + 1] ?? ''))
129
+ on = /^true$/i.test(args[i + 1]);
130
+ else if (a === f)
131
+ on = true;
132
+ // A-SPEC-794.74, 794.75 — as nopt's validateBoolean reads a value: `false` and `null` are false, a numeric value
133
+ // (`!isNaN(v)`, the empty value included) is `!!(+v)`, anything else is true
134
+ else if (a.startsWith(`${f}=`)) {
135
+ const v = a.slice(f.length + 1);
136
+ on = v === 'false' || v === 'null' ? false : !Number.isNaN(Number(v)) ? Boolean(Number(v)) : true;
137
+ }
138
+ else if (f.startsWith('--') && a === `--no-${f.slice(2)}`)
139
+ on = false;
140
+ }
141
+ }
142
+ return on;
143
+ }
144
+ /**
145
+ * Programs whose arguments are data (A-SPEC-794.71): only these exempt their arguments. Any other program — an unknown
146
+ * wrapper included — is read again from the first registry token among its arguments.
147
+ */
148
+ exports.DATA_PROGRAMS = new Set(['echo', 'printf', 'cat', 'head', 'tail', 'less', 'more', 'wc', 'ls', 'grep',
149
+ 'egrep', 'fgrep', 'rg', 'ag', 'jq', 'yq', 'sort', 'uniq', 'cut', 'tr', 'tee', 'diff', 'cmp', 'test', '[', '[[', 'true', 'false', ':',
150
+ 'date', 'basename', 'dirname', 'realpath', 'readlink', 'pwd', 'cd', 'pushd', 'popd', 'mkdir', 'rmdir', 'touch', 'rm', 'cp', 'mv', 'ln',
151
+ 'chmod', 'chown', 'stat', 'file', 'which', 'type', 'gh', 'jest', 'for', 'select', 'case', 'in', 'vitest', 'mocha', 'pytest', 'tsc', 'eslint', 'prettier',
152
+ 'curl', 'wget', 'sleep', 'kill', 'ps', 'pgrep', 'uptime', 'open', 'shasum', 'sha256sum', 'md5', 'base64', 'od', 'xxd', 'hexdump',
153
+ 'du', 'df', 'find', 'tar', 'zip', 'unzip', 'gzip', 'gunzip', 'holmes-kit', 'export', 'declare', 'local', 'readonly', 'typeset',
154
+ 'read', 'unset', 'set', 'shift', 'return', 'exit', 'wait', 'jobs', 'cmp', 'column', 'nl', 'fold', 'fmt', 'paste', 'join', 'comm',
155
+ 'launchctl', 'defaults', 'say', 'pbcopy', 'pbpaste', 'man', 'tldr', 'info', 'logger', 'notify-send', 'terminal-notifier']);
156
+ /** A-SPEC-794.74 — programs whose command-string positions are read (commandStrings); their other words are data. */
157
+ exports.COMMAND_STRING_PROGRAMS = new Set(['ssh', 'tmux', 'watchexec', 'nodemon', 'entr', 'watch',
158
+ 'parallel', 'concurrently', 'doppler', 'infisical', 'tar', 'zip', 'wget']);
159
+ /** A-SPEC-794.74 — pnpm's names for a recursive run. */
160
+ exports.PNPM_RECURSIVE = new Set(['m', 'multi', 'recursive']);
161
+ /** A release tool's own help and version flags: nothing is published. */
162
+ exports.RELEASE_HELP = new Set(['--help', '-h', '--version', '-v', '-V']);
163
+ /** Program tokens that start a registry act when they appear among another program's arguments. */
164
+ exports.REGISTRY_TOKENS = new Set(['npm', 'pnpm', 'yarn', 'bun', 'npx', 'pnpx', 'bunx', 'corepack',
165
+ 'semantic-release', 'np', 'release-it', 'nx', 'changeset', 'changesets', 'lerna', 'turbo', 'run-s', 'run-p', 'npm-run-all']);
166
+ /** Options whose value is a command, by program; and programs whose positional arguments are commands. */
167
+ exports.COMMAND_OPTIONS = {
168
+ npx: ['-c', '--call'], pnpx: ['-c'], bunx: ['-c'], nodemon: ['--exec', '-x'], nix: ['-c', '--command'],
169
+ 'nix-shell': ['--run', '--command'],
170
+ };
171
+ exports.POSITIONAL_COMMANDS = new Set(['concurrently']);
172
+ /** A package that runs a release tool's bin. */
173
+ exports.PACKAGE_BINS = {
174
+ '@changesets/cli': 'changeset', 'semantic-release': 'semantic-release', np: 'np', 'release-it': 'release-it', lerna: 'lerna',
175
+ nx: 'nx', '@nrwl/cli': 'nx', 'npm-run-all': 'npm-run-all', 'npm-run-all2': 'npm-run-all',
176
+ };
177
+ /** A-SPEC-794.72 — the registry programs read as independent tokens in an unknown program's arguments. */
178
+ exports.REGISTRY_PROGRAMS = new Set(['npm', 'pnpm', 'yarn', 'yarnpkg', 'bun']);
179
+ exports.WRAPPERS = {
180
+ timeout: { valued: ['-s', '-k', '--signal', '--kill-after'], positionals: 1 },
181
+ caffeinate: { valued: ['-t', '-w'] },
182
+ op: { sub: 'run', valued: ['--env-file', '--account', '--cache'] },
183
+ doppler: { sub: 'run', valued: ['-p', '--project', '-c', '--config', '--token', '--command'] },
184
+ infisical: { sub: 'run', valued: ['--env', '--path', '--projectId', '--token', '--command'] },
185
+ dotenv: { valued: ['-e', '-c', '-v', '-p'] },
186
+ dotenvx: { sub: 'run', valued: ['-f', '--env-file', '-e', '--env'] },
187
+ 'cross-env': { assigns: true },
188
+ 'aws-vault': { sub: 'exec', positionals: 1, valued: ['-d', '--duration', '--region'] },
189
+ nvm: { sub: 'exec', positionals: 1 },
190
+ volta: { sub: 'run', valued: ['--node', '--npm', '--yarn', '--pnpm'] },
191
+ mise: { sub: ['exec', 'x'], toolArgs: true }, fnm: { sub: 'exec', valued: ['--using'] }, asdf: { sub: 'exec' },
192
+ direnv: { sub: 'exec', positionals: 1 },
193
+ devbox: { sub: 'run' },
194
+ nix: { sub: 'develop', commandFlag: ['-c', '--command'] },
195
+ script: { valued: ['-t', '-T'], positionals: 1 },
196
+ launchctl: { sub: 'submit', valued: ['-l', '-p', '-o', '-e', '-g'] },
197
+ };
198
+ /** The command after a wrapper's own words, or null when the words do not run one. */
199
+ function unwrapWith(w, args) {
200
+ let rest = [...args];
201
+ if (w.sub !== undefined) {
202
+ const subs = typeof w.sub === 'string' ? [w.sub] : w.sub;
203
+ if (!subs.includes(rest[0] ?? ''))
204
+ return null;
205
+ rest = rest.slice(1);
206
+ }
207
+ // A-SPEC-794.74 — a tool list before `--` (`mise exec node@20 -- …`): the command is after `--`
208
+ if (w.toolArgs === true && rest.includes('--'))
209
+ return rest.slice(rest.indexOf('--') + 1);
210
+ if (w.commandFlag !== undefined) {
211
+ const k = rest.findIndex((a) => w.commandFlag?.includes(a));
212
+ return k < 0 ? null : rest.slice(k + 1);
213
+ }
214
+ let pos = 0;
215
+ for (let k = 0; k < rest.length; k++) {
216
+ const a = rest[k];
217
+ if (a === '--')
218
+ return rest.slice(k + 1);
219
+ if (w.valued?.includes(a)) {
220
+ k++;
221
+ continue;
222
+ }
223
+ if (a.startsWith('-'))
224
+ continue;
225
+ if (w.assigns === true && /^[A-Za-z_]\w*=/.test(a))
226
+ continue;
227
+ if (pos < (w.positionals ?? 0)) {
228
+ pos++;
229
+ continue;
230
+ }
231
+ return rest.slice(k);
232
+ }
233
+ return null;
234
+ }
235
+ const valuesOf = (args, names) => {
236
+ const out = [];
237
+ for (let k = 0; k < args.length; k++) {
238
+ for (const n of names) {
239
+ if (args[k] === n && args[k + 1] !== undefined)
240
+ out.push(args[k + 1]);
241
+ else if (n.startsWith('--') && args[k].startsWith(`${n}=`))
242
+ out.push(args[k].slice(n.length + 1));
243
+ }
244
+ }
245
+ return out;
246
+ };
247
+ /** The words after the options (valued ones skip their value), or after `--`. */
248
+ const afterOptions = (args, valued) => {
249
+ for (let k = 0; k < args.length; k++) {
250
+ if (args[k] === '--')
251
+ return args.slice(k + 1);
252
+ if (valued.includes(args[k])) {
253
+ k++;
254
+ continue;
255
+ }
256
+ if (!args[k].startsWith('-'))
257
+ return args.slice(k);
258
+ }
259
+ return [];
260
+ };
261
+ const asCommandText = (words) => (words.length === 0 ? [] : words.length === 1 ? [words[0]] : [words.map((v) => (/^[\w@%+=:,./-]+$/.test(v) ? v : `'${v.replace(/'/g, `'\\''`)}'`)).join(' ')]);
262
+ /**
263
+ * A-SPEC-794.72 — the command strings a program runs, at the positions this table names. A string anywhere else is
264
+ * data. (Shells' -c, npx -c and npm exec -c are read where they were.)
265
+ */
266
+ function commandStrings(name, args) {
267
+ switch (name) {
268
+ case 'doppler':
269
+ case 'infisical': return valuesOf(args, ['--command']);
270
+ case 'nodemon': return valuesOf(args, ['--exec', '-x']);
271
+ case 'concurrently': return args.filter((a) => !a.startsWith('-'));
272
+ case 'watch': return asCommandText(afterOptions(args, ['-n', '--interval', '-d']));
273
+ case 'watchexec': return asCommandText(afterOptions(args, ['-w', '--watch', '-e', '--exts', '-i', '--ignore', '-d', '--debounce', '--shell', '-s', '--signal']));
274
+ case 'entr': return valuesOf(args, ['-s']);
275
+ case 'ssh': {
276
+ const rest = afterOptions(args, ['-p', '-i', '-l', '-o', '-F', '-J', '-L', '-R', '-D', '-b', '-c', '-E', '-e', '-m', '-O', '-Q', '-S', '-W', '-w']);
277
+ return asCommandText(rest.slice(1));
278
+ }
279
+ case 'tmux': return ['new', 'new-session', 'new-window', 'split-window', 'respawn-pane'].includes(args[0] ?? '') ? asCommandText(afterOptions(args.slice(1), ['-s', '-n', '-c', '-t', '-x', '-y', '-e', '-F', '-l'])) : [];
280
+ case 'parallel': {
281
+ const rest = afterOptions(args, ['-j', '--jobs', '-S', '--sshlogin']);
282
+ const end = rest.indexOf(':::');
283
+ return asCommandText(end < 0 ? rest.slice(0, 1) : rest.slice(0, end));
284
+ }
285
+ case 'git': {
286
+ const sub = afterOptions(args, ['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--config-env', '--exec-path']);
287
+ const rest = sub.slice(1);
288
+ switch (sub[0]) {
289
+ case 'rebase': return valuesOf(rest, ['--exec', '-x']);
290
+ case 'bisect': return rest[0] === 'run' ? asCommandText(rest.slice(1)) : [];
291
+ case 'submodule': return rest[0] === 'foreach' ? asCommandText(rest.slice(1).filter((a) => a !== '--recursive' && a !== '-q' && a !== '--quiet')) : [];
292
+ case 'difftool':
293
+ case 'mergetool': return valuesOf(rest, ['-x', '--extcmd', '--tool-cmd']);
294
+ case 'filter-branch': return valuesOf(rest, ['--tree-filter', '--index-filter', '--msg-filter', '--env-filter', '--commit-filter', '--parent-filter', '--tag-name-filter']);
295
+ default: return [];
296
+ }
297
+ }
298
+ case 'tar': return [...valuesOf(args, ['--to-command', '--use-compress-program', '-I']), ...valuesOf(args, ['--checkpoint-action']).filter((v) => v.startsWith('exec=')).map((v) => v.slice(5))];
299
+ case 'zip': return valuesOf(args, ['-TT', '--unzip-command']);
300
+ case 'wget': return valuesOf(args, ['--use-askpass']);
301
+ case 'gh': return args[0] === 'alias' && args[1] === 'set' && args.includes('--shell') ? args.slice(2).filter((a) => !a.startsWith('-')).slice(1, 2) : [];
302
+ default: return [];
303
+ }
304
+ }
305
+ /** Runners that run scripts of the current package by name (globs allowed). */
306
+ exports.SCRIPT_NAME_RUNNERS = new Set(['run-s', 'run-p', 'npm-run-all']);
307
+ /** npm options before the subcommand that take the next word as their value. */
308
+ exports.NPM_VALUED_OPTIONS = new Set(['--prefix', '-C', '-w', '--workspace', '--tag', '--registry', '--otp',
309
+ '--userconfig', '--globalconfig', '--cache', '--loglevel', '--access', '--scope', '--dir', '--cwd', '--filter', '-F',
310
+ // A-SPEC-794.75 — yarn v1's valued options before the subcommand
311
+ '--network-timeout', '--cache-folder', '--mutex', '--modules-folder', '--global-folder', '--link-folder', '--network-concurrency']);
312
+ /** A-SPEC-794.75 — `yarn workspaces foreach`'s valued options before the command it runs. */
313
+ exports.YARN_FOREACH_VALUED = new Set(['--exclude', '--from', '--include', '--jobs', '-j', '--since']);
314
+ /** yarn: its own registry writes (v1 and berry's `npm` group) and its own subcommands (never a script name). */
315
+ exports.YARN_WRITES = {
316
+ publish: true, tag: group(['add', 'remove', 'rm'], ['list', 'ls']), owner: group(['add', 'remove', 'rm'], ['list', 'ls']),
317
+ };
318
+ exports.YARN_NPM_WRITES = {
319
+ publish: true, tag: group(['add', 'remove'], ['list']),
320
+ };
321
+ /**
322
+ * A-SPEC-794.76 — each package manager's own built-ins, frozen from its command list (fixtures/manager-builtins.json):
323
+ * a word that is not one of them runs a script of that name. One shared list let pnpm's `deploy` hide `yarn deploy`.
324
+ */
325
+ const BUILTINS = {
326
+ // A-SPEC-794.78 — only the names both yarn majors own: a name one major lacks may be a script there (`patch`, `check`)
327
+ yarn: new Set(builtins.yarn1.commands.filter((n) => builtins.yarnBerry.commands.includes(n))),
328
+ pnpm: new Set(builtins.pnpm.commands),
329
+ bun: new Set(builtins.bun.commands),
330
+ };
331
+ function managerBuiltins(tool) {
332
+ return tool === 'yarn' || tool === 'pnpm' || tool === 'bun' ? BUILTINS[tool] : new Set();
333
+ }
334
+ const firstPositional = (args) => args.find((a) => !a.startsWith('-'));
335
+ exports.RELEASE_TOOLS = {
336
+ 'semantic-release': { dry: ['--dry-run', '-d'] },
337
+ np: { dry: ['--preview'] },
338
+ 'release-it': { dry: ['--dry-run', '-d'] },
339
+ nx: { dry: ['--dry-run', '-d'], needs: (a) => a[0] === 'release' && !['version', 'changelog', 'plan'].includes(firstPositional(a.slice(1)) ?? '') },
340
+ changeset: { dry: [], needs: (a) => firstPositional(a) === 'publish' },
341
+ changesets: { dry: [], needs: (a) => firstPositional(a) === 'publish' },
342
+ lerna: { dry: [], needs: (a) => firstPositional(a) === 'publish' },
343
+ };
344
+ /** Runners that run a package script by name in every package: the script names they run, or null. */
345
+ function runnerScripts(name, args) {
346
+ const pos = args.filter((a) => !a.startsWith('-'));
347
+ if (name === 'lerna' && pos[0] === 'run')
348
+ return pos[1] !== undefined ? [pos[1]] : null;
349
+ if (name === 'turbo') {
350
+ const TURBO_OWN = new Set(['login', 'logout', 'link', 'unlink', 'prune', 'daemon', 'gen', 'generate', 'ls', 'info', 'telemetry', 'query', 'watch', 'boundaries', 'scan', 'bin']);
351
+ if (pos[0] === 'run')
352
+ return pos.slice(1);
353
+ return pos[0] !== undefined && !TURBO_OWN.has(pos[0]) ? pos : null;
354
+ }
355
+ if (name === 'nx' && pos[0] === 'run-many') {
356
+ for (let k = 0; k < args.length; k++) {
357
+ const m = /^--(?:target|targets)=(.+)$/.exec(args[k]);
358
+ if (m)
359
+ return m[1].split(',');
360
+ if ((args[k] === '-t' || args[k] === '--target' || args[k] === '--targets') && args[k + 1] !== undefined)
361
+ return args[k + 1].split(',');
362
+ }
363
+ return null;
364
+ }
365
+ if (name === 'nx' && pos[0] === 'run' && pos[1]?.includes(':'))
366
+ return [pos[1].split(':')[1]];
367
+ return null;
368
+ }
369
+ /** Shells whose `-c` string is a command, and that read their program from stdin without one. */
370
+ exports.SHELL_PROGRAMS = /^(?:ba|z|da|k|mk|fi|)sh$/;
371
+ /** Interpreters whose inline or stdin program is another language. */
372
+ exports.INTERPRETERS = /^(?:node|nodejs|python[0-9.]*|perl|ruby|php|deno)$/;
373
+ /** Their flag for an inline program. */
374
+ exports.INLINE_FLAGS = new Set(['-e', '--eval', '-p', '--print', '-c', '-E', '-r']);
375
+ /** Environment variables whose value a program runs as a command. */
376
+ exports.COMMAND_VARIABLES = new Set(['GIT_EDITOR', 'GIT_SEQUENCE_EDITOR', 'GIT_PAGER', 'GIT_SSH_COMMAND',
377
+ 'GIT_EXTERNAL_DIFF', 'EDITOR', 'VISUAL', 'PAGER', 'GIT_ASKPASS', 'SSH_ASKPASS']);
378
+ /** Programs that run the package named by their first positional word (with its version stripped). */
379
+ exports.PACKAGE_RUNNERS = new Set(['npx', 'pnpx', 'bunx', 'corepack']);
@@ -0,0 +1,23 @@
1
+ {
2
+ "source": "each package manager's own built-in commands (A-SPEC-794.76). yarn 1.22.22 and pnpm 9.15.9: taken from their published bundles (yarn lib/cli.js `commands`, camelCase names written as the CLI spells them; pnpm dist/pnpm.cjs `commandNames`). yarn 4 (berry) and bun 1: from their CLI references, because neither is installed on the machine that froze this list.",
3
+ "yarn1": {
4
+ "version": "1.22.22",
5
+ "from": "bundle",
6
+ "commands": ["access", "add", "audit", "autoclean", "bin", "cache", "check", "config", "create", "dedupe", "exec", "generate-lock-entry", "global", "help", "import", "info", "init", "install", "licenses", "link", "list", "lockfile", "login", "logout", "node", "outdated", "owner", "pack", "policies", "prune", "publish", "remove", "run", "tag", "team", "unlink", "unplug", "upgrade", "upgrade-interactive", "version", "versions", "why", "workspace", "workspaces"]
7
+ },
8
+ "yarnBerry": {
9
+ "version": "4",
10
+ "from": "CLI reference",
11
+ "commands": ["add", "bin", "cache", "config", "constraints", "dedupe", "dlx", "exec", "explain", "info", "init", "install", "link", "node", "npm", "pack", "patch", "patch-commit", "plugin", "rebuild", "remove", "run", "set", "stage", "unlink", "unplug", "up", "upgrade-interactive", "version", "why", "workspace", "workspaces"]
12
+ },
13
+ "pnpm": {
14
+ "version": "9.15.9",
15
+ "from": "bundle",
16
+ "commands": ["add", "audit", "bin", "c", "cache", "cat-file", "cat-index", "ci", "clean-install", "completion", "config", "create", "dedupe", "deploy", "dislink", "dlx", "doctor", "env", "exec", "fetch", "find-hash", "get", "i", "ic", "import", "init", "install", "install-clean", "install-test", "it", "la", "licenses", "link", "list", "ll", "ln", "ls", "m", "multi", "outdated", "pack", "patch", "patch-commit", "patch-remove", "prune", "publish", "rb", "rebuild", "recursive", "remove", "restart", "rm", "root", "run", "run-script", "self-update", "server", "set", "setup", "store", "t", "test", "tst", "un", "uni", "uninstall", "unlink", "up", "update", "upgrade", "why"]
17
+ },
18
+ "bun": {
19
+ "version": "1",
20
+ "from": "CLI reference",
21
+ "commands": ["run", "test", "x", "repl", "exec", "install", "i", "add", "a", "remove", "rm", "update", "outdated", "audit", "link", "unlink", "publish", "patch", "pm", "build", "init", "create", "upgrade", "completions", "discord", "help", "info", "why"]
22
+ }
23
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "source": "npm 11.17.0 lib/utils/cmd-list.js (commands, aliases); dryRun: the commands whose lib/commands source file reads dry-run",
3
+ "npmVersion": "11.17.0",
4
+ "commands": ["access", "adduser", "approve-scripts", "audit", "bugs", "cache", "ci", "completion", "config", "dedupe", "deny-scripts", "deprecate", "diff", "dist-tag", "docs", "doctor", "edit", "exec", "explain", "explore", "find-dupes", "fund", "get", "help", "help-search", "init", "install", "install-ci-test", "install-test", "link", "ll", "login", "logout", "ls", "org", "outdated", "owner", "pack", "ping", "pkg", "prefix", "profile", "prune", "publish", "query", "rebuild", "repo", "restart", "root", "run", "sbom", "search", "set", "shrinkwrap", "stage", "star", "stars", "start", "stop", "team", "test", "token", "trust", "undeprecate", "uninstall", "unpublish", "unstar", "update", "version", "view", "whoami"],
5
+ "aliases": { "author": "owner", "home": "docs", "issues": "bugs", "info": "view", "show": "view", "find": "search", "add": "install", "unlink": "uninstall", "remove": "uninstall", "rm": "uninstall", "r": "uninstall", "un": "uninstall", "rb": "rebuild", "list": "ls", "ln": "link", "create": "init", "i": "install", "it": "install-test", "cit": "install-ci-test", "u": "update", "up": "update", "c": "config", "s": "search", "se": "search", "tst": "test", "t": "test", "ddp": "dedupe", "v": "view", "run-script": "run", "clean-install": "ci", "clean-install-test": "install-ci-test", "x": "exec", "why": "explain", "la": "ll", "verison": "version", "ic": "ci", "innit": "init", "in": "install", "ins": "install", "inst": "install", "insta": "install", "instal": "install", "isnt": "install", "isnta": "install", "isntal": "install", "isntall": "install", "install-clean": "ci", "isntall-clean": "ci", "hlep": "help", "dist-tags": "dist-tag", "upgrade": "update", "udpate": "update", "rum": "run", "sit": "install-ci-test", "urn": "run", "ogr": "org", "add-user": "adduser" },
6
+ "dryRun": ["audit", "cache", "ci", "dedupe", "deprecate", "find-dupes", "install", "link", "pack", "prune", "publish", "unpublish", "update"]
7
+ }
@@ -57,6 +57,12 @@ export interface EditEvidenceVerdict {
57
57
  * material. Same locations, read from the type table rather than spelled twice.
58
58
  */
59
59
  export declare function isLowRiskTarget(target: string): boolean;
60
+ /** @implements A-SPEC-333.1 — every code the gate can emit, read off the remediation table. */
61
+ export declare function editEvidenceCodes(): Array<EditEvidenceReason['code']>;
62
+ /** @implements A-SPEC-333.2 — one code's remediation sentence, for an explanation said once per epoch. */
63
+ export declare function remediationFor(code: EditEvidenceReason['code']): string;
64
+ /** @implements A-SPEC-333.1 — lead with whichever refusal the caller must fix FIRST; a widen reason never speaks for a refusal. */
65
+ export declare function primaryReason(reasons: EditEvidenceReason[]): EditEvidenceReason | undefined;
60
66
  export declare function evaluateEditEvidence(inputArgs: EditEvidenceInput): EditEvidenceVerdict;
61
67
  /**
62
68
  * @implements A-SPEC-278
@@ -34,10 +34,13 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.isLowRiskTarget = isLowRiskTarget;
37
+ exports.editEvidenceCodes = editEvidenceCodes;
38
+ exports.remediationFor = remediationFor;
39
+ exports.primaryReason = primaryReason;
37
40
  exports.evaluateEditEvidence = evaluateEditEvidence;
38
41
  exports.preEditEvidenceDecision = preEditEvidenceDecision;
39
42
  exports.loadEditEvidence = loadEditEvidence;
40
- // @implements A-SPEC-279, A-SPEC-278.1, A-SPEC-278.2, A-SPEC-278.3, A-SPEC-278.4, A-SPEC-278.6
43
+ // @implements A-SPEC-279, A-SPEC-278.1, A-SPEC-278.2, A-SPEC-278.3, A-SPEC-278.4, A-SPEC-278.6, A-SPEC-333.1, A-SPEC-333.9, A-SPEC-333.10
41
44
  // @implements A-SPEC-278
42
45
  // @implements A-SPEC-277
43
46
  // @implements A-SPEC-276
@@ -46,6 +49,7 @@ const fs = __importStar(require("node:fs"));
46
49
  const crypto = __importStar(require("node:crypto"));
47
50
  const path = __importStar(require("node:path"));
48
51
  const spec_types_1 = require("../spec/spec-types");
52
+ const test_scope_1 = require("../rtm/test-scope");
49
53
  const CODE_EXTENSIONS = new Set([
50
54
  '.ts', '.mts', '.cts', '.tsx', '.jsx', '.js', '.mjs', '.cjs', '.py', '.cs', '.java', '.go',
51
55
  '.rs', '.cpp', '.cc', '.cxx', '.hpp', '.hh', '.h', '.rb', '.php', '.kt', '.kts', '.swift',
@@ -68,6 +72,20 @@ function isLowRiskTarget(target) {
68
72
  return false;
69
73
  return true;
70
74
  }
75
+ /** @implements A-SPEC-333.1 — every code the gate can emit, read off the remediation table. */
76
+ function editEvidenceCodes() {
77
+ return Object.keys(REMEDIATION);
78
+ }
79
+ /** @implements A-SPEC-333.2 — one code's remediation sentence, for an explanation said once per epoch. */
80
+ function remediationFor(code) {
81
+ return REMEDIATION[code];
82
+ }
83
+ /** @implements A-SPEC-333.1 — lead with whichever refusal the caller must fix FIRST; a widen reason never speaks for a refusal. */
84
+ function primaryReason(reasons) {
85
+ return reasons.find((r) => r.code === 'basis-drift')
86
+ ?? reasons.find((r) => r.code === 'target-drift')
87
+ ?? reasons[0];
88
+ }
71
89
  const REMEDIATION = {
72
90
  // @implements A-SPEC-278.4 — an Edit or Write call carries no digest, so "retry with the digest" could not be followed.
73
91
  'no-analysis': 'Run maintenance_analyze({ root, request, persist: true }) for this change; the gate finds an analysis persisted at this HEAD by itself (impact_gate_check also accepts its digest).',
@@ -174,6 +192,18 @@ function evaluateEditEvidence(inputArgs) {
174
192
  });
175
193
  escalate('widen');
176
194
  }
195
+ else if ((0, test_scope_1.architectureGoverningFiles)([target]).length > 0
196
+ && artifact.changedFilesSource === 'git-diff-default'
197
+ && !(artifact.uncertainty.architectureTouched ?? []).includes(target)) {
198
+ // @implements A-SPEC-333.9 — a basis built from the working tree's diff assessed the documents it held; an edit of
199
+ // a decision or C-SPEC document it did not hold is outside what was assessed
200
+ // @implements A-SPEC-333.10 — read from the structured field the artifact persists, never from the explaining sentence
201
+ reasons.push({
202
+ code: 'architecture-unchecked',
203
+ detail: `The analysis's architecture basis came from the working tree's diff and did not hold ${target}, so its constraints were not checked.`,
204
+ });
205
+ escalate('widen');
206
+ }
177
207
  // (6b) @implements A-SPEC-279 — the remaining two constraint axes. The condition is "was it
178
208
  // EXAMINED", not "does a constraint exist": 61 of this repository's 192 A-SPECs declare a non-none
179
209
  // breaking change, so widening on mere presence would fire on about a third of all edits and teach
@@ -204,10 +234,7 @@ function evaluateEditEvidence(inputArgs) {
204
234
  escalate('widen');
205
235
  }
206
236
  traceGapReason();
207
- // Lead with whichever refusal the caller must fix FIRST; a widen reason never speaks for a refusal.
208
- const primary = reasons.find((r) => r.code === 'basis-drift')
209
- ?? reasons.find((r) => r.code === 'target-drift')
210
- ?? reasons[0];
237
+ const primary = primaryReason(reasons);
211
238
  return {
212
239
  decision,
213
240
  reasons,