skill-bin-drift.ts
578 lines · scripts/skill-bin-drift.ts at 3f79d81
1#!/usr/bin/env -S bun --no-env-file --config=/dev/null
2/**
3 * Static skill-to-bin drift scanner (GSTA-133). Skills teach gstack's own bins;
4 * when a template names a bin that is gone, or passes a flag the bin's parser
5 * does not accept, the model runs a wrong command that still passes CI.
6 *
7 * Inputs: SKILL.md.tmpl (root and one level down), <skill>/sections/*.md.tmpl,
8 * <skill>/references/*.md, and the Claude-host renders (SKILL.md, sections/*.md, which carry the
9 * AUTO-GENERATED banner) so resolver-generated commands count. A render finding
10 * that its own skill's templates already report is dropped. --skill NAME limits
11 * the scan to one skill folder (the /write-skill diet step). Only fenced code
12 * blocks and inline backtick spans are read, so prose placeholders never match.
13 *
14 * Bin spellings recognised (every form the templates and renders use today):
15 * bin/gstack-x (repo-relative)
16 * ~/.claude/skills/gstack/bin/gstack-x (Claude install; also .claude/skills/...)
17 * $HOME/.claude/skills/gstack/bin/gstack-x, "$HOME"/.claude/skills/gstack/bin/gstack-x
18 * $GSTACK_BIN/gstack-x, ${GSTACK_BIN}/gstack-x (env-var hosts)
19 * {{BIN_DIR}}/gstack-x, {{INSTALLED_BIN_DIR}}/gstack-x (template placeholders)
20 * $GSTACK_ROOT/bin/gstack-x, $RUNTIME_ROOT/bin/gstack-x, {{RUNTIME_ROOT}}/bin/gstack-x
21 * ${B%/browse/*}/bin/gstack-x (any ${...}/bin/ expansion)
22 *
23 * A call's arguments end at an unquoted pipe, ;, &, &&, ||, redirect, $( ),
24 * backtick, closing parenthesis, comment or line end (backslash continuations
25 * join). <VALUE> and <two words> placeholders are words, not redirects. Flags after -- are
26 * positional.
27 *
28 * Flag discovery never executes a bin. Bash: case arm labels (--a), --a|--b),
29 * --a=*)) whose body does not only refuse, and test comparisons
30 * ([ "$1" = "--a" ]). TS/JS/Python: --flag tokens in code and string
31 * literals (usage text included), in the bin and in its relative imports one
32 * level deep. A bash bin that hands off to a .ts/.js/.mjs/.py file, or passes
33 * "$@" to a .sh file or sibling gstack-* bin, gains that file's flags. A bin
34 * .gitignore lists as a build output is read from bin/<name>.ts; with no
35 * source its flags are unchecked (UNCHECKED list).
36 *
37 * Reported, never failed: PERMISSIVE (a bash arg loop whose catch-all *) arm
38 * neither errors nor has a -*) error arm beside it, or a bash bin that never
39 * reads its arguments) and NO_HELP (no --help handling and no usage text
40 * outside comments). A sourced .sh library that never reads arguments gets
41 * neither label. Failures: DRIFT_UNKNOWN_BIN, DRIFT_UNKNOWN_FLAG.
42 * test/skill-bin-drift.test.ts holds today's misses in a shrink-only allowlist
43 * (test/fixtures/skill-bin-drift-allowlist.json).
44 */
45import * as fs from 'fs';
46import * as path from 'path';
48export const FIX_LINE = "fix the template or the bin's parser; the allowlist only shrinks";
49export const ALLOWLIST_FILE = 'test/fixtures/skill-bin-drift-allowlist.json';
51export type DriftCode = 'DRIFT_UNKNOWN_BIN' | 'DRIFT_UNKNOWN_FLAG';
53export interface BinCall {
54 file: string;
55 line: number;
56 bin: string;
57 flags: string[];
58}
60export interface Finding {
61 code: DriftCode;
62 file: string;
63 line: number;
64 bin: string;
65 flag?: string;
66 key: string;
67 fix: string;
68}
70export interface BinProfile {
71 bin: string;
72 exists: boolean;
73 flagsKnown: boolean;
74 flags: Set<string>;
75 permissive: boolean;
76 hasHelp: boolean;
77 sources: string[];
78}
80export interface DriftReport {
81 inputs: string[];
82 calls: BinCall[];
83 findings: Finding[];
84 binsInvoked: string[];
85 permissive: string[];
86 noHelp: string[];
87 unchecked: string[];
88}
90type Lang = 'sh' | 'ts' | 'py';
92const BIN_NAME = 'gstack-[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?';
93const BIN_PREFIX = String.raw`(?:~|\$HOME|\$\{HOME\}|"\$HOME")?/?\.claude/skills/gstack/|\$\{[^}\s]*\}/|\$\{?[A-Z_][A-Z0-9_]*\}?/|\{\{[A-Z_]+\}\}/`;
94const BIN_RE = new RegExp(
95 String.raw`(?<![\w./$}-])(?:(?:${BIN_PREFIX})?bin/|\$\{?GSTACK_BIN\}?/|\{\{(?:INSTALLED_)?BIN_DIR\}\}/)(${BIN_NAME})(?![\w.-]*[\w])`,
96 'g',
97);
98const FLAG_WORD = /^--[A-Za-z0-9][A-Za-z0-9_-]*/;
100/** Shell-style words after a bin, up to the first command boundary. */
101export function binArgs(rest: string, openQuote: string | null = null): string[] {
102 const words: string[] = [];
103 let i = 0;
104 if (openQuote) {
105 const close = rest.indexOf(openQuote);
106 if (close < 0) return [];
107 i = close + 1;
108 }
109 let cur = '';
110 let has = false;
111 let quote: string | null = null;
112 const push = () => { if (has) words.push(cur); cur = ''; has = false; };
113 for (; i < rest.length; i++) {
114 const c = rest[i]!;
115 if (quote) {
116 if (c === quote) quote = null;
117 else if (c === '\\' && quote === '"') cur += rest[++i] ?? '';
118 else cur += c;
119 continue;
120 }
121 if (c === "'" || c === '"') { quote = c; has = true; continue; }
122 if (c === '\\') { cur += rest[++i] ?? ''; has = true; continue; }
123 if (/\s/.test(c)) { push(); continue; }
124 if (c === '>') {
125 if (/^\d+$/.test(cur)) { cur = ''; has = false; }
126 push();
127 if ('>&|'.includes(rest[i + 1] ?? '')) i++;
128 while (/[ \t]/.test(rest[i + 1] ?? '')) i++;
129 while (i + 1 < rest.length && !/\s/.test(rest[i + 1]!) && !'|;&`)'.includes(rest[i + 1]!)) i++;
130 continue;
131 }
132 if ('|;&`)'.includes(c) || (c === '$' && rest[i + 1] === '(')) break;
133 if (c === '#' && !has) break;
134 if (c === '<') {
135 const ph = /^<[A-Za-z_][^<>\n]*>/.exec(rest.slice(i));
136 if (!ph) break;
137 cur += ph[0]; has = true; i += ph[0].length - 1;
138 continue;
139 }
140 cur += c; has = true;
141 }
142 push();
143 return words;
144}
146/** The quote character open at `end` in a shell line, if any. */
147function openQuoteAt(text: string, end: number): string | null {
148 let quote: string | null = null;
149 for (let i = 0; i < end; i++) {
150 const c = text[i]!;
151 if (quote) { if (c === quote) quote = null; else if (c === '\\' && quote === '"') i++; continue; }
152 if (c === '\\') { i++; continue; }
153 if (c === "'" || c === '"') quote = c;
154 }
155 return quote;
156}
158function flagsOf(words: string[]): string[] {
159 const out: string[] = [];
160 for (const w of words) {
161 if (w === '--') break;
162 const m = FLAG_WORD.exec(w);
163 if (m) out.push(m[0]);
164 }
165 return out;
166}
168function callsInSnippet(snippet: string, file: string, line: number, out: BinCall[]): void {
169 for (const m of snippet.matchAll(BIN_RE)) {
170 const end = m.index! + m[0].length;
171 const words = binArgs(snippet.slice(end), openQuoteAt(snippet, m.index!));
172 out.push({ file, line, bin: m[1]!, flags: flagsOf(words) });
173 }
174}
176const FENCE = /^\s*(`{3,}|~{3,})/;
178/** Bin calls inside fenced code blocks and inline backtick spans of one markdown file. */
179export function scanText(text: string, file: string): BinCall[] {
180 const out: BinCall[] = [];
181 const lines = text.split('\n');
182 let fence: string | null = null;
183 for (let i = 0; i < lines.length; i++) {
184 const raw = lines[i]!;
185 const marker = FENCE.exec(raw);
186 if (marker) {
187 if (!fence) fence = marker[1]!;
188 else if (marker[1]![0] === fence[0] && marker[1]!.length >= fence.length) fence = null;
189 continue;
190 }
191 if (fence) {
192 let logical = raw;
193 const start = i;
194 while (/\\$/.test(logical) && i + 1 < lines.length && !FENCE.test(lines[i + 1]!)) {
195 logical = logical.slice(0, -1) + ' ' + lines[++i]!;
196 }
197 callsInSnippet(logical, file, start + 1, out);
198 continue;
199 }
200 for (const span of raw.matchAll(/(`+)([^`]+?)\1(?!`)/g)) callsInSnippet(span[2]!, file, i + 1, out);
201 }
202 return out;
203}
205function readText(file: string): string {
206 try { return fs.readFileSync(file, 'utf8'); } catch { return ''; }
207}
209function isFile(file: string): boolean {
210 return fs.existsSync(file) && fs.statSync(file).isFile();
211}
213function langOf(file: string, text: string): Lang {
214 if (/\.py$/.test(file)) return 'py';
215 if (/\.(?:[cm]?[jt]s|tsx)$/.test(file)) return 'ts';
216 const first = text.split('\n', 1)[0] ?? '';
217 if (/^#!.*\bpython/.test(first)) return 'py';
218 if (/^#!.*\b(?:bun|node|deno)\b/.test(first)) return 'ts';
219 return 'sh';
220}
222const COMMENT: Record<Lang, RegExp> = { sh: /^\s*#/, py: /^\s*#/, ts: /^\s*(?:\/\/|\*|\/\*)/ };
224function codeLines(text: string, lang: Lang): string[] {
225 return text.split('\n').filter(l => !COMMENT[lang].test(l));
226}
228/** --flag tokens in TS/JS/Python code and string literals, usage text included. */
229export function literalFlags(text: string, lang: Lang = 'ts'): Set<string> {
230 const flags = new Set<string>();
231 for (const line of codeLines(text, lang)) {
232 for (const m of line.matchAll(/(?<![\w-])(--[A-Za-z][A-Za-z0-9_-]*)/g)) flags.add(m[1]!);
233 }
234 return flags;
235}
237const ARM = /^[ \t]*\(?[ \t]*((?:["']?-[-\w=*]*["']?[ \t]*\|[ \t]*)*["']?-[-\w=*]*["']?)[ \t]*\)([\s\S]*?)(?:;;|\besac\b)/gm;
238const refuses = (body: string) => !/\bshift\b|\b[A-Za-z_][A-Za-z0-9_]*=/.test(body)
239 && /\b(?:refuse|die|fail)\b|\bexit\s+[1-9]|\breturn\s+[1-9]/.test(body);
241/** Flags a bash bin's case arms (minus arms that only refuse) and test comparisons accept. */
242export function bashFlags(text: string): Set<string> {
243 const flags = new Set<string>();
244 const code = codeLines(text, 'sh').join('\n');
245 for (const arm of code.matchAll(ARM)) {
246 if (refuses(arm[2]!)) continue;
247 for (const label of arm[1]!.split('|')) {
248 const m = FLAG_WORD.exec(label.trim().replace(/^["']|["']$/g, ''));
249 if (m) flags.add(m[0]);
250 }
251 }
252 for (const m of code.matchAll(/(?:==?|!=)\s*["']?(--[A-Za-z0-9][A-Za-z0-9_-]*)/g)) flags.add(m[1]!);
253 return flags;
254}
256/** Top-level bash code plus the bodies of functions it (transitively) hands "$@" to; other functions' $1 is not the bin's. */
257function argScope(code: string): string {
258 const top: string[] = [];
259 const funcs = new Map<string, string[]>();
260 let cur: string | null = null;
261 for (const line of code.split('\n')) {
262 const start = /^\s*(?:function\s+)?([\w-]+)\s*\(\)\s*\{?\s*$/.exec(line);
263 if (cur === null && start) { cur = start[1]!; funcs.set(cur, []); continue; }
264 if (cur !== null) {
265 if (/^\}/.test(line)) cur = null;
266 else funcs.get(cur)!.push(line);
267 continue;
268 }
269 top.push(line);
270 }
271 const scope = [...top];
272 const included = new Set<string>();
273 for (let grew = true; grew;) {
274 grew = false;
275 const text = scope.join('\n');
276 for (const [name, body] of funcs) {
277 if (included.has(name) || !new RegExp(`(?:^|[\\s;&|(])${name}\\s+"\\$@"`, 'm').test(text)) continue;
278 included.add(name);
279 scope.push(...body);
280 grew = true;
281 }
282 }
283 return scope.join('\n');
284}
286const readsArgs = (code: string) => /\$\{?[1-9@*#]|getopts|\bshift\b/.test(code);
288/** A sourced .sh function library: it never reads arguments at top level, so permissive and help checks do not apply. */
289export function isShellLibrary(bin: string, text: string): boolean {
290 return bin.endsWith('.sh') && !readsArgs(argScope(codeLines(text, 'sh').join('\n')));
291}
293/** In a case over the arguments, a catch-all *) arm with no error and no -*) error arm; or arguments never read. */
294export function bashPermissive(text: string): boolean {
295 const code = argScope(codeLines(text, 'sh').join('\n'));
296 if (!readsArgs(code)) return true;
297 const argVars = new Set(['1']);
298 for (const m of code.matchAll(/\bfor\s+(\w+)\s+in\s+"\$@"/g)) argVars.add(m[1]!);
299 for (const m of code.matchAll(/\b(\w+)="?\$\{?1\b/g)) argVars.add(m[1]!);
300 const blocks = [...code.matchAll(/\bcase\s+"?\$\{?(\w+)[^\n]*?\bin\b([\s\S]*?)\besac\b/g)].filter(m => argVars.has(m[1]!));
301 const arms = blocks.flatMap(block => [...block[2]!.matchAll(/^[ \t]*\(?[ \t]*(["']?-?-?\*["']?)[ \t]*\)([\s\S]*?)(?:;;|$)/gm)]);
302 const errors = (body: string) => /\bexit\b|\breturn\b|\bdie\b|usage|>&2|\berr\b|fail|refuse/i.test(body);
303 const dashError = arms.some(a => /-/.test(a[1]!) && errors(a[2]!));
304 const silentCatchAll = arms.some(a => !/-/.test(a[1]!) && !errors(a[2]!));
305 return silentCatchAll && !dashError;
306}
308function hasUsage(text: string, lang: Lang): boolean {
309 return /usage/i.test(codeLines(text, lang).filter(l => !/^#!/.test(l)).join('\n'));
310}
312function resolveModule(fromFile: string, spec: string): string | null {
313 const base = path.resolve(path.dirname(fromFile), spec);
314 for (const cand of [base, `${base}.ts`, `${base}.js`, `${base}.mjs`, path.join(base, 'index.ts')]) {
315 if (isFile(cand)) return cand;
316 }
317 return null;
318}
320/** Relative imports (static, dynamic and require) of one source file. */
321export function relativeImports(file: string, text: string): string[] {
322 const out = new Set<string>();
323 for (const m of text.matchAll(/(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|^\s*import\s+)['"](\.{1,2}\/[^'"]+)['"]/gm)) {
324 const hit = resolveModule(file, m[1]!);
325 if (hit) out.add(hit);
326 }
327 return [...out];
328}
330/** Files a bash bin hands its arguments to: .ts/.js/.mjs/.py paths, and .sh files or sibling bins given "$@". */
331export function bashHandoffs(binFile: string, text: string, root: string): string[] {
332 const out = new Set<string>();
333 const binDir = path.dirname(binFile);
334 for (const line of codeLines(text, 'sh')) {
335 const forwards = /"\$@"/.test(line);
336 for (const m of line.matchAll(/[^\s'"=;|&<>]+\.(?:[cm]?[jt]s|py|sh)(?![\w.])/g)) {
337 if (m[0].endsWith('.sh') && !forwards) continue;
338 const tail = m[0].replace(/^.*(?:\}|\)|\$[A-Za-z_][A-Za-z0-9_]*)/, '').replace(/^\//, '');
339 if (!tail) continue;
340 const hit = [binDir, root].map(dir => path.resolve(dir, tail)).find(c => c !== binFile && isFile(c));
341 if (hit) out.add(hit);
342 }
343 if (!forwards) continue;
344 for (const m of line.matchAll(new RegExp(`(?:^|[/\\s"])(${BIN_NAME})(?![\\w.-])`, 'g'))) {
345 const cand = path.join(binDir, m[1]!);
346 if (cand !== binFile && isFile(cand)) out.add(cand);
347 }
348 }
349 return [...out];
350}
352/** Bin names .gitignore lists as build outputs (bin/<pattern> lines). */
353function builtPatterns(root: string): RegExp[] {
354 return readText(path.join(root, '.gitignore')).split('\n')
355 .map(l => /^\/?bin\/(gstack-[^\s/]+)$/.exec(l.trim())?.[1])
356 .filter((p): p is string => Boolean(p))
357 .map(p => new RegExp(`^${p.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`));
358}
360/** Static profile of one bin: accepted flags, permissive parsing, help text. */
361export function profileBin(root: string, bin: string, built: RegExp[] = builtPatterns(root)): BinProfile {
362 const binFile = path.join(root, 'bin', bin);
363 const profile: BinProfile = { bin, exists: false, flagsKnown: true, flags: new Set(), permissive: false, hasHelp: false, sources: [] };
364 const seen = new Set<string>();
365 const absorb = (file: string, text: string, lang: Lang, flags: Set<string>) => {
366 seen.add(file);
367 profile.sources.push(path.relative(root, file));
368 for (const f of flags) profile.flags.add(f);
369 if (hasUsage(text, lang)) profile.hasHelp = true;
370 };
371 const addScript = (file: string, followImports: boolean) => {
372 if (seen.has(file)) return;
373 const text = readText(file);
374 const lang = langOf(file, text);
375 absorb(file, text, lang, literalFlags(text, lang));
376 if (followImports && lang === 'ts') for (const dep of relativeImports(file, text)) addScript(dep, false);
377 };
378 if (built.some(re => re.test(bin)) && !/\.(?:[cm]?[jt]s|py)$/.test(bin)) {
379 profile.exists = true;
380 if (isFile(`${binFile}.ts`)) addScript(`${binFile}.ts`, true);
381 else profile.flagsKnown = false;
382 } else if (isFile(binFile)) {
383 profile.exists = true;
384 const text = readText(binFile);
385 if (langOf(binFile, text) !== 'sh') {
386 addScript(binFile, true);
387 } else {
388 absorb(binFile, text, 'sh', bashFlags(text));
389 if (isShellLibrary(bin, text)) profile.hasHelp = true;
390 else profile.permissive = bashPermissive(text);
391 for (const handoff of bashHandoffs(binFile, text, root)) {
392 if (seen.has(handoff)) continue;
393 const handoffText = readText(handoff);
394 if (langOf(handoff, handoffText) !== 'sh') addScript(handoff, true);
395 else absorb(handoff, handoffText, 'sh', bashFlags(handoffText));
396 }
397 }
398 }
399 if (profile.flags.has('--help')) profile.hasHelp = true;
400 return profile;
401}
403function subdirs(root: string): string[] {
404 return fs.readdirSync(root, { withFileTypes: true })
405 .filter(d => d.isDirectory() && !d.name.startsWith('.') && d.name !== 'node_modules' && d.name !== 'dist')
406 .map(d => d.name)
407 .sort();
408}
410/** Template sources, sections/references and Claude-host renders, repo-relative; one skill's when `skill` is set. */
411export function listInputs(root: string, skill?: string): string[] {
412 const out: string[] = [];
413 const add = (rel: string) => { if (isFile(path.join(root, rel))) out.push(rel); };
414 if (!skill) { add('SKILL.md.tmpl'); add('SKILL.md'); }
415 for (const dir of skill ? [skill] : subdirs(root)) {
416 add(`${dir}/SKILL.md.tmpl`);
417 add(`${dir}/SKILL.md`);
418 for (const sub of ['sections', 'references']) {
419 const full = path.join(root, dir, sub);
420 if (!fs.existsSync(full) || !fs.statSync(full).isDirectory()) continue;
421 for (const name of fs.readdirSync(full).sort()) {
422 if (name.endsWith('.md.tmpl') || name.endsWith('.md')) add(`${dir}/${sub}/${name}`);
423 }
424 }
425 }
426 return out;
427}
429const isTemplate = (file: string) => file.endsWith('.tmpl');
430const skillDirOf = (file: string) => (file.includes('/') ? file.split('/')[0]! : '.');
432export function findingKey(f: { file: string; bin: string; flag?: string }): string {
433 return f.flag ? `${f.file}:${f.bin}:${f.flag}` : `${f.file}:${f.bin}`;
434}
436function findingsFor(calls: BinCall[], profiles: Map<string, BinProfile>): Finding[] {
437 const out: Finding[] = [];
438 for (const call of calls) {
439 const profile = profiles.get(call.bin)!;
440 const make = (code: DriftCode, flag?: string): Finding => {
441 const base = { code, file: call.file, line: call.line, bin: call.bin, flag };
442 return { ...base, key: findingKey(base), fix: FIX_LINE };
443 };
444 if (!profile.exists) { out.push(make('DRIFT_UNKNOWN_BIN')); continue; }
445 if (!profile.flagsKnown) continue;
446 for (const flag of call.flags) if (!profile.flags.has(flag)) out.push(make('DRIFT_UNKNOWN_FLAG', flag));
447 }
448 return out;
449}
451/** Drop render findings whose skill's own templates already report the same bin and flag. */
452function dropRenderEchoes(findings: Finding[]): Finding[] {
453 const id = (f: Finding) => `${skillDirOf(f.file)}|${f.code}|${f.bin}|${f.flag ?? ''}`;
454 const fromTemplates = new Set(findings.filter(f => isTemplate(f.file)).map(id));
455 return findings.filter(f => isTemplate(f.file) || !fromTemplates.has(id(f)));
456}
458/** Scan a repository root (or a fixture laid out like one). */
459export function scanRepo(root: string, inputs: string[] = listInputs(root)): DriftReport {
460 const calls = inputs.flatMap(file => scanText(readText(path.join(root, file)), file));
461 const built = builtPatterns(root);
462 const profiles = new Map<string, BinProfile>();
463 for (const call of calls) if (!profiles.has(call.bin)) profiles.set(call.bin, profileBin(root, call.bin, built));
464 const seen = new Set<string>();
465 const findings = dropRenderEchoes(findingsFor(calls, profiles)).filter(f => {
466 const id = `${f.key}|${f.line}`;
467 if (seen.has(id)) return false;
468 seen.add(id);
469 return true;
470 });
471 findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.key.localeCompare(b.key));
472 const existing = [...profiles.values()].filter(p => p.exists).sort((a, b) => a.bin.localeCompare(b.bin));
473 return {
474 inputs,
475 calls,
476 findings,
477 binsInvoked: [...profiles.keys()].sort(),
478 permissive: existing.filter(p => p.permissive).map(p => p.bin),
479 noHelp: existing.filter(p => p.flagsKnown && !p.hasHelp).map(p => p.bin),
480 unchecked: existing.filter(p => !p.flagsKnown).map(p => p.bin),
481 };
482}
484export interface Allowlist { _comment?: string; entries: string[] }
486export function loadAllowlist(file: string): Allowlist {
487 const parsed = JSON.parse(fs.readFileSync(file, 'utf8')) as Allowlist;
488 if (!Array.isArray(parsed.entries)) throw new Error(`${file}: "entries" must be an array of finding keys`);
489 return parsed;
490}
492/** Findings the allowlist does not cover, and allowlist keys (for the scanned inputs, when given) that no longer reproduce. */
493export function compareAllowlist(findings: Finding[], allowlist: Allowlist, inputs?: string[]): { unlisted: Finding[]; stale: string[] } {
494 const allowed = new Set(allowlist.entries);
495 const live = new Set(findings.map(f => f.key));
496 const scanned = (key: string) => !inputs || inputs.some(file => key.startsWith(`${file}:`));
497 return {
498 unlisted: findings.filter(f => !allowed.has(f.key)),
499 stale: allowlist.entries.filter(k => scanned(k) && !live.has(k)),
500 };
501}
503export function formatFinding(f: Finding): string {
504 const what = f.code === 'DRIFT_UNKNOWN_BIN' ? `bin/${f.bin} does not exist` : `${f.bin} does not accept ${f.flag}`;
505 return `${f.code} ${f.file}:${f.line} bin=${f.bin}${f.flag ? ` flag=${f.flag}` : ''}: ${what}\n fix: ${f.fix}`;
506}
508const HELP = `Usage: scripts/skill-bin-drift.ts [--skill NAME] [--json] [--all] [--root DIR]
510Statically checks every gstack bin that skill templates, carved sections and
511Claude-host renders invoke: the bin must exist in bin/ and every --flag passed
512to it must appear in its parser (bash case arms or comparisons, TS/JS/Python
513flag literals one relative import deep, bash hand-offs to .ts/.js/.py/.sh).
514Never executes a bin.
516 --skill NAME scan only NAME/: its template, sections, references and
517 Claude render (stale allowlist entries are judged for those
518 files only)
519 --json print the report as JSON
520 --all list every finding, allowlisted ones included
521 --root DIR scan DIR instead of this checkout
522 --help show this help
524Exit codes: 0 no finding outside ${ALLOWLIST_FILE} and no stale entry;
5251 drift outside the allowlist or a stale allowlist entry; 2 bad usage.
526PERMISSIVE, NO_HELP and UNCHECKED bins are reported, never failed.`;
528interface CliOptions { json: boolean; all: boolean; root: string; skill?: string }
530function parseCli(argv: string[]): CliOptions | string {
531 const opts: CliOptions = { json: false, all: false, root: path.resolve(import.meta.dir, '..') };
532 for (let i = 0; i < argv.length; i++) {
533 const a = argv[i]!;
534 if (a === '--json') opts.json = true;
535 else if (a === '--all') opts.all = true;
536 else if (a === '--root' || a === '--skill') {
537 const v = argv[++i];
538 if (!v || v.startsWith('--')) return `${a} needs a value`;
539 if (a === '--root') opts.root = path.resolve(v);
540 else opts.skill = v.replace(/\/+$/, '');
541 } else return `unknown argument ${a}`;
542 }
543 if (opts.skill && listInputs(opts.root, opts.skill).length === 0) {
544 return `no skill named ${opts.skill} under ${opts.root} (expected ${opts.skill}/SKILL.md.tmpl or ${opts.skill}/SKILL.md)`;
545 }
546 return opts;
547}
549function main(argv: string[]): number {
550 if (argv.includes('--help') || argv.includes('-h')) { console.log(HELP); return 0; }
551 const opts = parseCli(argv);
552 if (typeof opts === 'string') { console.error(`skill-bin-drift: ${opts}\n\n${HELP}`); return 2; }
553 const report = scanRepo(opts.root, listInputs(opts.root, opts.skill));
554 const allowFile = path.join(opts.root, ALLOWLIST_FILE);
555 const allowlist = isFile(allowFile) ? loadAllowlist(allowFile) : { entries: [] };
556 const { unlisted, stale } = compareAllowlist(report.findings, allowlist, opts.skill ? report.inputs : undefined);
557 const unknownBins = report.findings.filter(f => f.code === 'DRIFT_UNKNOWN_BIN').length;
558 if (opts.json) {
559 console.log(JSON.stringify({
560 inputs: report.inputs.length, calls: report.calls.length, binsInvoked: report.binsInvoked.length,
561 unknownBins, unknownFlags: report.findings.length - unknownBins,
562 findings: report.findings, unlisted: unlisted.map(f => f.key), stale,
563 permissive: report.permissive, noHelp: report.noHelp, unchecked: report.unchecked,
564 }, null, 2));
565 } else {
566 for (const f of opts.all ? report.findings : unlisted) console.log(formatFinding(f));
567 for (const key of stale) console.log(`STALE_ALLOWLIST ${key}: no longer reproduces; delete it from ${ALLOWLIST_FILE}`);
568 console.log(`PERMISSIVE (${report.permissive.length}): ${report.permissive.join(' ') || 'none'}`);
569 console.log(`NO_HELP (${report.noHelp.length}): ${report.noHelp.join(' ') || 'none'}`);
570 console.log(`UNCHECKED (${report.unchecked.length}): ${report.unchecked.join(' ') || 'none'}`);
571 console.log(`skill-bin-drift: ${report.inputs.length} inputs, ${report.calls.length} calls, ${report.binsInvoked.length} bins, `
572 + `${unknownBins} unknown-bin and ${report.findings.length - unknownBins} unknown-flag findings `
573 + `(${unlisted.length} outside the allowlist, ${stale.length} stale entries)`);
574 }
575 return unlisted.length > 0 || stale.length > 0 ? 1 : 0;
576}
578if (import.meta.main) process.exit(main(process.argv.slice(2)));