@ankhorage/devtools 2.5.0 → 2.6.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.
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
 
4
4
  # @ankhorage/devtools
5
5
 
6
- ![license: MIT](././paradox/badges/license.svg) ![npm: v2.5.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: configured](././paradox/badges/tests.svg) ![paradox: warnings](././paradox/badges/docs.svg)
6
+ ![license: MIT](././paradox/badges/license.svg) ![npm: v2.6.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: configured](././paradox/badges/tests.svg) ![paradox: warnings](././paradox/badges/docs.svg)
7
7
 
8
8
  Shared tooling, repository automation, and agent standards for Ankhorage TypeScript projects
9
9
 
@@ -0,0 +1,2 @@
1
+ /*** Public CI-impact planning and GitHub Actions output boundary. */
2
+ export { type CiImpactConfiguration, type CiImpactJobDecision, type CiImpactKind, type CiImpactMode, type CiImpactPlan, type CiImpactSelection, type CiImpactSuite, type CiImpactWorkflowOutput, createCiImpactWorkflowOutput, planCiImpact, runCiImpact, } from './features/ci-impact/ciImpact.js';
@@ -0,0 +1,2 @@
1
+ /*** Public CI-impact planning and GitHub Actions output boundary. */
2
+ export { createCiImpactWorkflowOutput, planCiImpact, runCiImpact, } from './features/ci-impact/ciImpact.js';
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,2 @@
1
+ import { runCiImpact } from '../../ci-impact.js';
2
+ runCiImpact(process.argv.slice(2));
@@ -0,0 +1,43 @@
1
+ export type CiImpactKind = 'e2e' | 'smoke';
2
+ export type CiImpactMode = 'skip' | 'full' | 'changed' | 'scoped';
3
+ export interface CiImpactSelection {
4
+ readonly mode: CiImpactMode;
5
+ readonly scripts: readonly string[];
6
+ readonly reason: string;
7
+ }
8
+ export interface CiImpactPlan {
9
+ readonly base: string;
10
+ readonly unit: CiImpactSelection;
11
+ readonly e2e: CiImpactSelection;
12
+ readonly smoke: CiImpactSelection;
13
+ }
14
+ export interface CiImpactSuite {
15
+ readonly kind: CiImpactKind;
16
+ readonly script: string;
17
+ readonly paths: readonly string[];
18
+ }
19
+ export interface CiImpactConfiguration {
20
+ readonly complete?: Partial<Record<CiImpactKind, boolean>>;
21
+ readonly suites?: readonly CiImpactSuite[];
22
+ }
23
+ export interface CiImpactJobDecision {
24
+ readonly state: 'selected' | 'skipped' | 'full';
25
+ readonly reason: string;
26
+ readonly fallback: boolean;
27
+ }
28
+ export interface CiImpactWorkflowOutput {
29
+ readonly version: 1;
30
+ readonly plan: CiImpactPlan;
31
+ readonly jobs: Readonly<Record<string, CiImpactJobDecision>>;
32
+ }
33
+ interface CiImpactExecutionContext {
34
+ readonly cwd?: string;
35
+ readonly environment?: Readonly<Record<string, string | undefined>>;
36
+ }
37
+ /*** Select safe CI checks, using explicit suite ownership and Bun's dependency graph. */
38
+ export declare function planCiImpact(files: readonly string[] | null, scripts: Readonly<Record<string, string | undefined>>, configuration: CiImpactConfiguration | undefined, base: string): CiImpactPlan;
39
+ /*** Create safe, per-script GitHub Actions decisions from the canonical aggregate plan. */
40
+ export declare function createCiImpactWorkflowOutput(plan: CiImpactPlan, configuration: CiImpactConfiguration | undefined): CiImpactWorkflowOutput;
41
+ /*** Run the published CI impact command without evaluating repository values as shell commands. */
42
+ export declare function runCiImpact(argv: readonly string[], context?: CiImpactExecutionContext): void;
43
+ export {};
@@ -0,0 +1,203 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { readFileSync, writeFileSync } from 'node:fs';
3
+ import { join } from 'node:path';
4
+ import { writeCiImpactGitHubOutputs, writeCiImpactGitHubSummary } from './ciImpactGitHub.js';
5
+ /*** Select safe CI checks, using explicit suite ownership and Bun's dependency graph. */
6
+ export function planCiImpact(files, scripts, configuration, base) {
7
+ const full = files === null || files.some(isUnsafeChange);
8
+ const docs = files?.every(isDocumentation) === true;
9
+ const baseSelection = {
10
+ mode: full ? 'full' : 'skip',
11
+ scripts: [],
12
+ reason: full ? 'Unsafe or unavailable diff' : 'Documentation only',
13
+ };
14
+ const unit = scripts.test === undefined
15
+ ? { mode: 'skip', scripts: [], reason: 'No test script' }
16
+ : full
17
+ ? { mode: 'full', scripts: ['test'], reason: 'Unsafe or unavailable diff' }
18
+ : docs
19
+ ? baseSelection
20
+ : scripts.test.trim() === 'bun test'
21
+ ? { mode: 'changed', scripts: ['test'], reason: 'Bun transitive import graph' }
22
+ : { mode: 'full', scripts: ['test'], reason: 'Unrecognized test runner' };
23
+ return {
24
+ base,
25
+ unit,
26
+ e2e: selectSuites('e2e', files, scripts, configuration, full, docs),
27
+ smoke: selectSuites('smoke', files, scripts, configuration, full, docs),
28
+ };
29
+ }
30
+ /*** Create safe, per-script GitHub Actions decisions from the canonical aggregate plan. */
31
+ export function createCiImpactWorkflowOutput(plan, configuration) {
32
+ const jobs = Object.fromEntries(['e2e', 'smoke'].flatMap((kind) => suitesForKind(configuration, kind).map((suite) => [
33
+ suite.script,
34
+ createJobDecision(plan[kind], suite.script),
35
+ ])));
36
+ return { version: 1, plan, jobs };
37
+ }
38
+ /*** Run the published CI impact command without evaluating repository values as shell commands. */
39
+ export function runCiImpact(argv, context = {}) {
40
+ const operation = parseOperation(argv);
41
+ const cwd = context.cwd ?? process.cwd();
42
+ const environment = context.environment ?? process.env;
43
+ const planPath = join(environment.RUNNER_TEMP ?? '.', 'ankh-ci-impact-plan.json');
44
+ if (operation === 'plan') {
45
+ const { configuration, plan } = createPlan(cwd, environment);
46
+ writeFileSync(planPath, JSON.stringify(plan), { encoding: 'utf8' });
47
+ const output = createCiImpactWorkflowOutput(plan, configuration);
48
+ writeCiImpactGitHubOutputs(output, environment);
49
+ console.log(JSON.stringify(output, null, 2));
50
+ writeCiImpactGitHubSummary(plan, environment);
51
+ return;
52
+ }
53
+ const plan = JSON.parse(readFileSync(planPath, 'utf8'));
54
+ runPlan(plan, operation, cwd);
55
+ }
56
+ /*** Select scoped suites only when an exhaustive and unambiguous repository declaration is valid. */
57
+ function selectSuites(kind, files, scripts, configuration, full, docs) {
58
+ const defaults = (kind === 'e2e' ? ['test:e2e'] : ['test:smoke', 'test:standalone']).filter((name) => scripts[name] !== undefined);
59
+ const suites = suitesForKind(configuration, kind);
60
+ const validSuites = suites.length > 0 &&
61
+ new Set(suites.map((suite) => suite.script)).size === suites.length &&
62
+ suites.every((suite) => typeof scripts[suite.script] === 'string' &&
63
+ suite.paths.length > 0 &&
64
+ suite.paths.every(isSafePattern));
65
+ const fallbackScripts = defaults.length > 0
66
+ ? defaults
67
+ : suites.map((suite) => suite.script).filter((script) => scripts[script] !== undefined);
68
+ if (fallbackScripts.length === 0)
69
+ return { mode: 'skip', scripts: [], reason: 'No suite scripts' };
70
+ if (docs)
71
+ return { mode: 'skip', scripts: [], reason: 'Documentation only' };
72
+ if (full)
73
+ return { mode: 'full', scripts: fallbackScripts, reason: 'Unsafe or unavailable diff' };
74
+ if (configuration?.complete?.[kind] !== true || !validSuites) {
75
+ return { mode: 'full', scripts: fallbackScripts, reason: 'No complete suite mapping' };
76
+ }
77
+ const matches = (files ?? []).map((file) => suites.filter((suite) => suite.paths.some((pattern) => matchesPath(file, pattern))));
78
+ if (matches.some((found) => found.length !== 1)) {
79
+ return { mode: 'full', scripts: fallbackScripts, reason: 'Ambiguous or unmapped changed file' };
80
+ }
81
+ return {
82
+ mode: 'scoped',
83
+ scripts: [...new Set(matches.flat().map((suite) => suite.script))],
84
+ reason: 'Explicit complete suite mapping',
85
+ };
86
+ }
87
+ /*** Read only well-formed suite declarations from untrusted package metadata. */
88
+ function suitesForKind(configuration, kind) {
89
+ return configuration?.suites?.filter((suite) => suite.kind === kind) ?? [];
90
+ }
91
+ /*** Classify a declared script from the aggregate selection without allowing an implied pass. */
92
+ function createJobDecision(selection, script) {
93
+ if (selection.mode === 'full') {
94
+ return { state: 'full', reason: selection.reason, fallback: true };
95
+ }
96
+ if (selection.mode === 'skip') {
97
+ return { state: 'skipped', reason: selection.reason, fallback: false };
98
+ }
99
+ return selection.scripts.includes(script)
100
+ ? { state: 'selected', reason: selection.reason, fallback: false }
101
+ : { state: 'skipped', reason: selection.reason, fallback: false };
102
+ }
103
+ /*** Conservatively identify changes that invalidate impact pruning. */
104
+ function isUnsafeChange(file) {
105
+ return (/^(?:\.github\/|\.agents\/|scripts\/|tools\/|test\/|tests\/|config\/)/u.test(file) ||
106
+ /(?:^|\/)[^/]*\.config\.[^/]+$/u.test(file) ||
107
+ /(?:^|\/)(?:[^/]+\.lock|[^/]+\.lockb|(?:bun|package)-lock\.json|pnpm-lock\.yaml|yarn\.lock)$/u.test(file) ||
108
+ /^(?:package\.json|bunfig\.toml|AGENTS\.md|tsconfig[^/]*|playwright\.config\.[^/]+|vitest\.config\.[^/]+|jest\.config\.[^/]+|eslint\.config\.[^/]+|\.env[^/]*)$/u.test(file));
109
+ }
110
+ /*** Classify files whose changes cannot influence runtime test execution. */
111
+ function isDocumentation(file) {
112
+ return (file.startsWith('docs/') ||
113
+ file.startsWith('.changeset/') ||
114
+ (/\.(?:md|mdx)$/u.test(file) && !isUnsafeChange(file)) ||
115
+ file === 'LICENSE');
116
+ }
117
+ /*** Keep mapping syntax deliberately restricted to exact paths and directory descendants. */
118
+ function isSafePattern(pattern) {
119
+ return (!pattern.startsWith('/') &&
120
+ !pattern.includes('..') &&
121
+ /^(?:[a-zA-Z0-9_.@-]+\/)*[a-zA-Z0-9_.@*-]+$/u.test(pattern) &&
122
+ (!pattern.includes('*') || pattern.endsWith('/**')));
123
+ }
124
+ /*** Match one declared path or its explicit recursive directory ownership. */
125
+ function matchesPath(file, pattern) {
126
+ return pattern.endsWith('/**') ? file.startsWith(pattern.slice(0, -2)) : file === pattern;
127
+ }
128
+ /*** Read Git's binary-safe status output, failing closed for removals, renames, and invalid refs. */
129
+ function readChangedFiles(base, cwd) {
130
+ if (!/^[a-f0-9]{40}$/u.test(base))
131
+ return null;
132
+ try {
133
+ execFileSync('git', ['cat-file', '-e', base + '^{commit}'], { cwd, stdio: 'ignore' });
134
+ const output = execFileSync('git', ['diff', '--name-status', '--no-renames', '-z', base, 'HEAD', '--'], { cwd, encoding: 'utf8' });
135
+ const items = output.split('\0').filter(Boolean);
136
+ if (items.length % 2 !== 0)
137
+ return null;
138
+ const changes = Array.from({ length: items.length / 2 }, (_, index) => ({
139
+ status: items[index * 2],
140
+ path: items[index * 2 + 1],
141
+ }));
142
+ return changes.every((item) => /^[AMT]$/u.test(item.status) && !item.path.includes('\n'))
143
+ ? changes.map((item) => item.path)
144
+ : null;
145
+ }
146
+ catch {
147
+ return null;
148
+ }
149
+ }
150
+ /*** Produce a full plan when the workflow cannot prove a trustworthy PR delta. */
151
+ function createPlan(cwd, environment) {
152
+ const manifest = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
153
+ const base = environment.GITHUB_EVENT_NAME === 'pull_request' ? (environment.ANKH_CI_BASE_SHA ?? '') : '';
154
+ const files = base ? readChangedFiles(base, cwd) : null;
155
+ const configuration = parseCiImpactConfiguration(manifest.ankh?.ciImpact);
156
+ return { configuration, plan: planCiImpact(files, manifest.scripts ?? {}, configuration, base) };
157
+ }
158
+ /*** Reject malformed package metadata before it can become a scoped ownership declaration. */
159
+ function parseCiImpactConfiguration(value) {
160
+ if (typeof value !== 'object' ||
161
+ value === null ||
162
+ !Array.isArray(value.suites)) {
163
+ return undefined;
164
+ }
165
+ const { suites } = value;
166
+ if (!suites.every(isCiImpactSuite))
167
+ return undefined;
168
+ const { complete } = value;
169
+ return {
170
+ complete: typeof complete === 'object' && complete !== null ? complete : undefined,
171
+ suites,
172
+ };
173
+ }
174
+ /*** Validate untrusted JSON suite data before constructing the typed configuration. */
175
+ function isCiImpactSuite(value) {
176
+ if (typeof value !== 'object' || value === null)
177
+ return false;
178
+ const suite = value;
179
+ return ((suite.kind === 'e2e' || suite.kind === 'smoke') &&
180
+ typeof suite.script === 'string' &&
181
+ Array.isArray(suite.paths) &&
182
+ suite.paths.every((path) => typeof path === 'string'));
183
+ }
184
+ /*** Execute an already saved CI plan without shell interpolation. */
185
+ function runPlan(plan, kind, cwd) {
186
+ const selection = plan[kind];
187
+ if (selection.mode === 'skip')
188
+ return;
189
+ if (kind === 'unit' && selection.mode === 'changed') {
190
+ execFileSync('bun', ['test', '--changed=' + plan.base], { cwd, stdio: 'inherit' });
191
+ return;
192
+ }
193
+ for (const script of selection.scripts) {
194
+ execFileSync('bun', ['run', script], { cwd, stdio: 'inherit' });
195
+ }
196
+ }
197
+ /*** Restrict the public command to known operations before it reads or executes repository state. */
198
+ function parseOperation(argv) {
199
+ if (argv.length !== 1 || !['plan', 'unit', 'e2e', 'smoke'].includes(argv[0] ?? '')) {
200
+ throw new Error('Expected exactly one operation: plan, unit, e2e, or smoke.');
201
+ }
202
+ return argv[0];
203
+ }
@@ -0,0 +1,5 @@
1
+ import type { CiImpactPlan, CiImpactWorkflowOutput } from './ciImpact.js';
2
+ /*** Write JSON-safe records so external workflows can address arbitrary script identifiers. */
3
+ export declare function writeCiImpactGitHubOutputs(output: CiImpactWorkflowOutput, environment: Readonly<Record<string, string | undefined>>): void;
4
+ /*** Render the existing aggregate plan in the GitHub Actions step summary. */
5
+ export declare function writeCiImpactGitHubSummary(plan: CiImpactPlan, environment: Readonly<Record<string, string | undefined>>): void;
@@ -0,0 +1,31 @@
1
+ import { appendFileSync } from 'node:fs';
2
+ /*** Write JSON-safe records so external workflows can address arbitrary script identifiers. */
3
+ export function writeCiImpactGitHubOutputs(output, environment) {
4
+ if (environment.GITHUB_OUTPUT === undefined)
5
+ return;
6
+ const { plan } = output;
7
+ appendFileSync(environment.GITHUB_OUTPUT, [
8
+ 'impact=' + JSON.stringify(output),
9
+ 'unit=' + plan.unit.mode,
10
+ 'e2e=' + plan.e2e.mode,
11
+ 'smoke=' + plan.smoke.mode,
12
+ ].join('\n') + '\n');
13
+ }
14
+ /*** Render the existing aggregate plan in the GitHub Actions step summary. */
15
+ export function writeCiImpactGitHubSummary(plan, environment) {
16
+ if (environment.GITHUB_STEP_SUMMARY === undefined)
17
+ return;
18
+ appendFileSync(environment.GITHUB_STEP_SUMMARY, '### CI impact\n\n| Suite | Mode | Reason | Scripts |\n| --- | --- | --- | --- |\n' +
19
+ ['unit', 'e2e', 'smoke']
20
+ .map((kind) => '| ' +
21
+ kind +
22
+ ' | ' +
23
+ plan[kind].mode +
24
+ ' | ' +
25
+ plan[kind].reason +
26
+ ' | ' +
27
+ (plan[kind].scripts.join(', ') || '—') +
28
+ ' |')
29
+ .join('\n') +
30
+ '\n');
31
+ }
@@ -1,25 +1 @@
1
- type Kind = 'e2e' | 'smoke';
2
- type Mode = 'skip' | 'full' | 'changed' | 'scoped';
3
- interface Selection {
4
- readonly mode: Mode;
5
- readonly scripts: readonly string[];
6
- readonly reason: string;
7
- }
8
- interface Plan {
9
- readonly base: string;
10
- readonly unit: Selection;
11
- readonly e2e: Selection;
12
- readonly smoke: Selection;
13
- }
14
- interface Scope {
15
- readonly kind: Kind;
16
- readonly script: string;
17
- readonly paths: readonly string[];
18
- }
19
- interface Configuration {
20
- readonly complete?: Partial<Record<Kind, boolean>>;
21
- readonly suites?: readonly Scope[];
22
- }
23
- /*** Select safe CI checks, using explicit suite ownership and Bun's dependency graph. */
24
- export declare function planCiImpact(files: readonly string[] | null, scripts: Readonly<Record<string, string>>, configuration: Configuration | undefined, base: string): Plan;
25
1
  export {};
@@ -1,157 +1,2 @@
1
- import { execFileSync } from 'node:child_process';
2
- import { appendFileSync, readFileSync, writeFileSync } from 'node:fs';
3
- import { join } from 'node:path';
4
- /*** Select safe CI checks, using explicit suite ownership and Bun's dependency graph. */
5
- export function planCiImpact(files, scripts, configuration, base) {
6
- const full = files === null || files.some(isUnsafeChange);
7
- const docs = files !== null && files.every(isDocumentation);
8
- const baseSelection = {
9
- mode: full ? 'full' : 'skip',
10
- scripts: [],
11
- reason: full ? 'Unsafe or unavailable diff' : 'Documentation only',
12
- };
13
- const unit = scripts.test === undefined
14
- ? { mode: 'skip', scripts: [], reason: 'No test script' }
15
- : full
16
- ? { mode: 'full', scripts: ['test'], reason: 'Unsafe or unavailable diff' }
17
- : docs
18
- ? baseSelection
19
- : scripts.test.trim() === 'bun test'
20
- ? { mode: 'changed', scripts: ['test'], reason: 'Bun transitive import graph' }
21
- : { mode: 'full', scripts: ['test'], reason: 'Unrecognized test runner' };
22
- return {
23
- base,
24
- unit,
25
- e2e: selectSuites('e2e', files, scripts, configuration, full, docs),
26
- smoke: selectSuites('smoke', files, scripts, configuration, full, docs),
27
- };
28
- }
29
- /*** Select scoped suites only when an exhaustive repository declaration is valid. */
30
- function selectSuites(kind, files, scripts, configuration, full, docs) {
31
- const defaults = (kind === 'e2e' ? ['test:e2e'] : ['test:smoke', 'test:standalone']).filter((name) => scripts[name] !== undefined);
32
- const suites = configuration?.suites?.filter((suite) => suite.kind === kind) ?? [];
33
- const validSuites = suites.length > 0 &&
34
- suites.every((suite) => typeof scripts[suite.script] === 'string' &&
35
- suite.paths.length > 0 &&
36
- suite.paths.every((path) => typeof path === 'string' && isSafePattern(path)));
37
- const fallbackScripts = defaults.length > 0
38
- ? defaults
39
- : suites.map((suite) => suite.script).filter((script) => scripts[script] !== undefined);
40
- if (fallbackScripts.length === 0)
41
- return { mode: 'skip', scripts: [], reason: 'No suite scripts' };
42
- if (docs)
43
- return { mode: 'skip', scripts: [], reason: 'Documentation only' };
44
- if (full || files === null)
45
- return { mode: 'full', scripts: fallbackScripts, reason: 'Unsafe or unavailable diff' };
46
- if (configuration?.complete?.[kind] !== true || !validSuites) {
47
- return { mode: 'full', scripts: fallbackScripts, reason: 'No complete suite mapping' };
48
- }
49
- const matches = files.map((file) => suites.filter((suite) => suite.paths.some((pattern) => matchesPath(file, pattern))));
50
- if (matches.some((found) => found.length === 0)) {
51
- return { mode: 'full', scripts: fallbackScripts, reason: 'Unmapped changed file' };
52
- }
53
- const selected = [...new Set(matches.flat().map((suite) => suite.script))];
54
- return { mode: 'scoped', scripts: selected, reason: 'Explicit complete suite mapping' };
55
- }
56
- /*** Conservatively identify changes that invalidate impact pruning. */
57
- function isUnsafeChange(file) {
58
- return (/^(?:\.github\/|\.agents\/|scripts\/|test\/|tests\/|config\/)/u.test(file) ||
59
- /^(?:package\.json|bun\.lock|bunfig\.toml|AGENTS\.md|tsconfig[^/]*|playwright\.config\.[^/]+|vitest\.config\.[^/]+|jest\.config\.[^/]+|eslint\.config\.[^/]+|\.env[^/]*)$/u.test(file));
60
- }
61
- /*** Classify files whose changes cannot influence runtime test execution. */
62
- function isDocumentation(file) {
63
- return (file.startsWith('docs/') ||
64
- file.startsWith('.changeset/') ||
65
- (/\.(?:md|mdx)$/u.test(file) && !isUnsafeChange(file)) ||
66
- file === 'LICENSE');
67
- }
68
- /*** Keep mapping syntax deliberately restricted to exact paths and directory descendants. */
69
- function isSafePattern(pattern) {
70
- return (!pattern.startsWith('/') &&
71
- !pattern.includes('..') &&
72
- /^(?:[a-zA-Z0-9_.@-]+\/)*[a-zA-Z0-9_.@*-]+$/u.test(pattern) &&
73
- (!pattern.includes('*') || pattern.endsWith('/**')));
74
- }
75
- /*** Match one declared path or its explicit recursive directory ownership. */
76
- function matchesPath(file, pattern) {
77
- return pattern.endsWith('/**') ? file.startsWith(pattern.slice(0, -2)) : file === pattern;
78
- }
79
- /*** Read Git's binary-safe status output, failing closed for removals and invalid refs. */
80
- function readChangedFiles(base) {
81
- if (!/^[a-f0-9]{40}$/u.test(base))
82
- return null;
83
- try {
84
- execFileSync('git', ['cat-file', '-e', base + '^{commit}'], { stdio: 'ignore' });
85
- const output = execFileSync('git', ['diff', '--name-status', '--no-renames', '-z', base, 'HEAD', '--'], { encoding: 'utf8' });
86
- const items = output.split('\0').filter(Boolean);
87
- if (items.length % 2 !== 0)
88
- return null;
89
- const changes = Array.from({ length: items.length / 2 }, (_, index) => ({
90
- status: items[index * 2],
91
- path: items[index * 2 + 1],
92
- }));
93
- return changes.every((item) => /^[AMT]$/u.test(item.status) && !item.path.includes('\n'))
94
- ? changes.map((item) => item.path)
95
- : null;
96
- }
97
- catch {
98
- return null;
99
- }
100
- }
101
- /*** Produce a full plan when the workflow cannot prove a trustworthy PR delta. */
102
- function createPlan() {
103
- const manifest = JSON.parse(readFileSync('package.json', 'utf8'));
104
- const base = process.env.GITHUB_EVENT_NAME === 'pull_request' ? (process.env.ANKH_CI_BASE_SHA ?? '') : '';
105
- const files = base ? readChangedFiles(base) : null;
106
- return planCiImpact(files, manifest.scripts ?? {}, manifest.ankh?.ciImpact, base);
107
- }
108
- /*** Execute an already saved CI plan without shell interpolation. */
109
- function runPlan(plan, kind) {
110
- const selection = plan[kind];
111
- if (selection.mode === 'skip')
112
- return;
113
- if (kind === 'unit' && selection.mode === 'changed') {
114
- execFileSync('bun', ['test', '--changed=' + plan.base], { stdio: 'inherit' });
115
- return;
116
- }
117
- for (const script of selection.scripts) {
118
- execFileSync('bun', ['run', script], { stdio: 'inherit' });
119
- }
120
- }
121
- /*** Expose test decisions in GitHub outputs and a human-readable step summary. */
122
- function main() {
123
- const operation = process.argv[2];
124
- const planPath = join(process.env.RUNNER_TEMP ?? '.', 'ankh-ci-impact-plan.json');
125
- if (operation === 'plan') {
126
- const plan = createPlan();
127
- writeFileSync(planPath, JSON.stringify(plan));
128
- if (process.env.GITHUB_OUTPUT) {
129
- appendFileSync(process.env.GITHUB_OUTPUT, ['unit=' + plan.unit.mode, 'e2e=' + plan.e2e.mode, 'smoke=' + plan.smoke.mode].join('\n') +
130
- '\n');
131
- }
132
- console.log(JSON.stringify(plan, null, 2));
133
- if (process.env.GITHUB_STEP_SUMMARY) {
134
- appendFileSync(process.env.GITHUB_STEP_SUMMARY, '### CI impact\n\n| Suite | Mode | Reason | Scripts |\n| --- | --- | --- | --- |\n' +
135
- ['unit', 'e2e', 'smoke']
136
- .map((kind) => '| ' +
137
- kind +
138
- ' | ' +
139
- plan[kind].mode +
140
- ' | ' +
141
- plan[kind].reason +
142
- ' | ' +
143
- (plan[kind].scripts.join(', ') || '—') +
144
- ' |')
145
- .join('\n') +
146
- '\n');
147
- }
148
- return;
149
- }
150
- if (operation !== 'unit' && operation !== 'e2e' && operation !== 'smoke') {
151
- throw new Error('Expected plan, unit, e2e, or smoke');
152
- }
153
- const plan = JSON.parse(readFileSync(planPath, 'utf8'));
154
- runPlan(plan, operation);
155
- }
156
- if (import.meta.main)
157
- main();
1
+ import { runCiImpact } from '@ankhorage/devtools/ci-impact';
2
+ runCiImpact(process.argv.slice(2));
@@ -1,234 +1,3 @@
1
- import { execFileSync } from 'node:child_process';
2
- import { appendFileSync, readFileSync, writeFileSync } from 'node:fs';
3
- import { join } from 'node:path';
1
+ import { runCiImpact } from '@ankhorage/devtools/ci-impact';
4
2
 
5
- type Kind = 'e2e' | 'smoke';
6
- type Mode = 'skip' | 'full' | 'changed' | 'scoped';
7
- interface Selection {
8
- readonly mode: Mode;
9
- readonly scripts: readonly string[];
10
- readonly reason: string;
11
- }
12
- interface Plan {
13
- readonly base: string;
14
- readonly unit: Selection;
15
- readonly e2e: Selection;
16
- readonly smoke: Selection;
17
- }
18
- interface Scope {
19
- readonly kind: Kind;
20
- readonly script: string;
21
- readonly paths: readonly string[];
22
- }
23
- interface Configuration {
24
- readonly complete?: Partial<Record<Kind, boolean>>;
25
- readonly suites?: readonly Scope[];
26
- }
27
-
28
- /*** Select safe CI checks, using explicit suite ownership and Bun's dependency graph. */
29
- export function planCiImpact(
30
- files: readonly string[] | null,
31
- scripts: Readonly<Record<string, string>>,
32
- configuration: Configuration | undefined,
33
- base: string,
34
- ): Plan {
35
- const full = files === null || files.some(isUnsafeChange);
36
- const docs = files !== null && files.every(isDocumentation);
37
- const baseSelection: Selection = {
38
- mode: full ? 'full' : 'skip',
39
- scripts: [],
40
- reason: full ? 'Unsafe or unavailable diff' : 'Documentation only',
41
- };
42
- const unit: Selection =
43
- scripts.test === undefined
44
- ? { mode: 'skip', scripts: [], reason: 'No test script' }
45
- : full
46
- ? { mode: 'full', scripts: ['test'], reason: 'Unsafe or unavailable diff' }
47
- : docs
48
- ? baseSelection
49
- : scripts.test.trim() === 'bun test'
50
- ? { mode: 'changed', scripts: ['test'], reason: 'Bun transitive import graph' }
51
- : { mode: 'full', scripts: ['test'], reason: 'Unrecognized test runner' };
52
-
53
- return {
54
- base,
55
- unit,
56
- e2e: selectSuites('e2e', files, scripts, configuration, full, docs),
57
- smoke: selectSuites('smoke', files, scripts, configuration, full, docs),
58
- };
59
- }
60
-
61
- /*** Select scoped suites only when an exhaustive repository declaration is valid. */
62
- function selectSuites(
63
- kind: Kind,
64
- files: readonly string[] | null,
65
- scripts: Readonly<Record<string, string>>,
66
- configuration: Configuration | undefined,
67
- full: boolean,
68
- docs: boolean,
69
- ): Selection {
70
- const defaults = (kind === 'e2e' ? ['test:e2e'] : ['test:smoke', 'test:standalone']).filter(
71
- (name) => scripts[name] !== undefined,
72
- );
73
- const suites = configuration?.suites?.filter((suite) => suite.kind === kind) ?? [];
74
- const validSuites =
75
- suites.length > 0 &&
76
- suites.every(
77
- (suite) =>
78
- typeof scripts[suite.script] === 'string' &&
79
- suite.paths.length > 0 &&
80
- suite.paths.every((path) => typeof path === 'string' && isSafePattern(path)),
81
- );
82
- const fallbackScripts =
83
- defaults.length > 0
84
- ? defaults
85
- : suites.map((suite) => suite.script).filter((script) => scripts[script] !== undefined);
86
-
87
- if (fallbackScripts.length === 0)
88
- return { mode: 'skip', scripts: [], reason: 'No suite scripts' };
89
- if (docs) return { mode: 'skip', scripts: [], reason: 'Documentation only' };
90
- if (full || files === null)
91
- return { mode: 'full', scripts: fallbackScripts, reason: 'Unsafe or unavailable diff' };
92
- if (configuration?.complete?.[kind] !== true || !validSuites) {
93
- return { mode: 'full', scripts: fallbackScripts, reason: 'No complete suite mapping' };
94
- }
95
- const matches = files.map((file) =>
96
- suites.filter((suite) => suite.paths.some((pattern) => matchesPath(file, pattern))),
97
- );
98
- if (matches.some((found) => found.length === 0)) {
99
- return { mode: 'full', scripts: fallbackScripts, reason: 'Unmapped changed file' };
100
- }
101
- const selected = [...new Set(matches.flat().map((suite) => suite.script))];
102
- return { mode: 'scoped', scripts: selected, reason: 'Explicit complete suite mapping' };
103
- }
104
-
105
- /*** Conservatively identify changes that invalidate impact pruning. */
106
- function isUnsafeChange(file: string): boolean {
107
- return (
108
- /^(?:\.github\/|\.agents\/|scripts\/|test\/|tests\/|config\/)/u.test(file) ||
109
- /^(?:package\.json|bun\.lock|bunfig\.toml|AGENTS\.md|tsconfig[^/]*|playwright\.config\.[^/]+|vitest\.config\.[^/]+|jest\.config\.[^/]+|eslint\.config\.[^/]+|\.env[^/]*)$/u.test(
110
- file,
111
- )
112
- );
113
- }
114
-
115
- /*** Classify files whose changes cannot influence runtime test execution. */
116
- function isDocumentation(file: string): boolean {
117
- return (
118
- file.startsWith('docs/') ||
119
- file.startsWith('.changeset/') ||
120
- (/\.(?:md|mdx)$/u.test(file) && !isUnsafeChange(file)) ||
121
- file === 'LICENSE'
122
- );
123
- }
124
-
125
- /*** Keep mapping syntax deliberately restricted to exact paths and directory descendants. */
126
- function isSafePattern(pattern: string): boolean {
127
- return (
128
- !pattern.startsWith('/') &&
129
- !pattern.includes('..') &&
130
- /^(?:[a-zA-Z0-9_.@-]+\/)*[a-zA-Z0-9_.@*-]+$/u.test(pattern) &&
131
- (!pattern.includes('*') || pattern.endsWith('/**'))
132
- );
133
- }
134
-
135
- /*** Match one declared path or its explicit recursive directory ownership. */
136
- function matchesPath(file: string, pattern: string): boolean {
137
- return pattern.endsWith('/**') ? file.startsWith(pattern.slice(0, -2)) : file === pattern;
138
- }
139
-
140
- /*** Read Git's binary-safe status output, failing closed for removals and invalid refs. */
141
- function readChangedFiles(base: string): readonly string[] | null {
142
- if (!/^[a-f0-9]{40}$/u.test(base)) return null;
143
- try {
144
- execFileSync('git', ['cat-file', '-e', base + '^{commit}'], { stdio: 'ignore' });
145
- const output = execFileSync(
146
- 'git',
147
- ['diff', '--name-status', '--no-renames', '-z', base, 'HEAD', '--'],
148
- { encoding: 'utf8' },
149
- );
150
- const items = output.split('\0').filter(Boolean);
151
- if (items.length % 2 !== 0) return null;
152
- const changes = Array.from({ length: items.length / 2 }, (_, index) => ({
153
- status: items[index * 2],
154
- path: items[index * 2 + 1],
155
- }));
156
- return changes.every((item) => /^[AMT]$/u.test(item.status) && !item.path.includes('\n'))
157
- ? changes.map((item) => item.path)
158
- : null;
159
- } catch {
160
- return null;
161
- }
162
- }
163
-
164
- /*** Produce a full plan when the workflow cannot prove a trustworthy PR delta. */
165
- function createPlan(): Plan {
166
- const manifest = JSON.parse(readFileSync('package.json', 'utf8')) as {
167
- scripts?: Record<string, string>;
168
- ankh?: { ciImpact?: Configuration };
169
- };
170
- const base =
171
- process.env.GITHUB_EVENT_NAME === 'pull_request' ? (process.env.ANKH_CI_BASE_SHA ?? '') : '';
172
- const files = base ? readChangedFiles(base) : null;
173
- return planCiImpact(files, manifest.scripts ?? {}, manifest.ankh?.ciImpact, base);
174
- }
175
-
176
- /*** Execute an already saved CI plan without shell interpolation. */
177
- function runPlan(plan: Plan, kind: 'unit' | Kind): void {
178
- const selection = plan[kind];
179
- if (selection.mode === 'skip') return;
180
- if (kind === 'unit' && selection.mode === 'changed') {
181
- execFileSync('bun', ['test', '--changed=' + plan.base], { stdio: 'inherit' });
182
- return;
183
- }
184
- for (const script of selection.scripts) {
185
- execFileSync('bun', ['run', script], { stdio: 'inherit' });
186
- }
187
- }
188
-
189
- /*** Expose test decisions in GitHub outputs and a human-readable step summary. */
190
- function main(): void {
191
- const operation = process.argv[2];
192
- const planPath = join(process.env.RUNNER_TEMP ?? '.', 'ankh-ci-impact-plan.json');
193
- if (operation === 'plan') {
194
- const plan = createPlan();
195
- writeFileSync(planPath, JSON.stringify(plan));
196
- if (process.env.GITHUB_OUTPUT) {
197
- appendFileSync(
198
- process.env.GITHUB_OUTPUT,
199
- ['unit=' + plan.unit.mode, 'e2e=' + plan.e2e.mode, 'smoke=' + plan.smoke.mode].join('\n') +
200
- '\n',
201
- );
202
- }
203
- console.log(JSON.stringify(plan, null, 2));
204
- if (process.env.GITHUB_STEP_SUMMARY) {
205
- appendFileSync(
206
- process.env.GITHUB_STEP_SUMMARY,
207
- '### CI impact\n\n| Suite | Mode | Reason | Scripts |\n| --- | --- | --- | --- |\n' +
208
- (['unit', 'e2e', 'smoke'] as const)
209
- .map(
210
- (kind) =>
211
- '| ' +
212
- kind +
213
- ' | ' +
214
- plan[kind].mode +
215
- ' | ' +
216
- plan[kind].reason +
217
- ' | ' +
218
- (plan[kind].scripts.join(', ') || '—') +
219
- ' |',
220
- )
221
- .join('\n') +
222
- '\n',
223
- );
224
- }
225
- return;
226
- }
227
- if (operation !== 'unit' && operation !== 'e2e' && operation !== 'smoke') {
228
- throw new Error('Expected plan, unit, e2e, or smoke');
229
- }
230
- const plan = JSON.parse(readFileSync(planPath, 'utf8')) as Plan;
231
- runPlan(plan, operation);
232
- }
233
-
234
- if (import.meta.main) main();
3
+ runCiImpact(process.argv.slice(2));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ankhorage/devtools",
3
- "version": "2.5.0",
3
+ "version": "2.6.0",
4
4
  "description": "Shared tooling, repository automation, and agent standards for Ankhorage TypeScript projects",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -427,6 +427,7 @@
427
427
  ],
428
428
  "bin": {
429
429
  "ankhorage-changeset": "./dist/cli/bin/changeset.js",
430
+ "ankhorage-ci-impact": "./dist/cli/bin/ci-impact.js",
430
431
  "ankhorage-eslint": "./dist/cli/bin/eslint.js",
431
432
  "ankhorage-knip": "./dist/cli/bin/knip.js",
432
433
  "ankhorage-prettier": "./dist/cli/bin/prettier.js",
@@ -463,6 +464,10 @@
463
464
  "./capabilities": {
464
465
  "types": "./dist/capabilities/index.d.ts",
465
466
  "import": "./dist/capabilities/index.js"
467
+ },
468
+ "./ci-impact": {
469
+ "types": "./dist/ci-impact.d.ts",
470
+ "import": "./dist/ci-impact.js"
466
471
  }
467
472
  },
468
473
  "files": [