Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* Wider anchors (phase 2 design 1.4, 4.13, P22 to P25, P42): what a skill's
* steps lean on beyond 1b's five kinds. A CI file (`gh workflow run x`), a
* compose service (`docker compose up x`) and a subcommand of the repo's own
* CLI (`acme connect`, where `acme` is a `bin` in package.json).
*
* Recall half: they change nothing and only warn, through 1b's
* `outOfDateLine`. Each is gone only when Trail is sure, from local file
* reads only (no process, no network): a param or variable, another repo,
* a folder that can't be known, a file over its size cap, a FIFO, a compose
* file that merges or includes others, more than 64 CI files, or a CLI whose
* registrations aren't all plain literals is never judged. The subcommand
* scan runs only with `scan: true` (a job cue's injection, `trail skills`),
* within its own 150 ms; SessionStart reads only the cache (P24).
*/
import { lstatSync, readdirSync, statSync } from 'node:fs';
import { isAbsolute, join, relative, resolve, sep } from 'node:path';
import type { ParsedSkill } from './types.js';
import { gitOf, readSmall, refOid } from './anchors-git.js';
import { binTarget, binsNear, cliNames, subcommandGone, type Cli } from './anchors-cli.js';
import { leadingCds, simpleCommands } from '../trace/shell.js';
import { programWords } from '../trace/shell-words.js';
import { unquote } from '../trace/shell-scan.js';
import { actionsFolder } from '../util/actions-folder.js';
export type WideKind = 'ci-file' | 'service' | 'subcommand';
/** where: the compose file (relative to the checkout) for a service, the program for a subcommand, 'GitHub Actions' for a CI file. */
export interface WideAnchor { kind: WideKind; name: string; step: number; where: string }
/** The subcommand scan's own deadline (4.13), inside the prompt hook's 400 ms. */
export const WIDE_SCAN_MS = 150;
const MAX_CI_FILES = 64;
const MAX_CI_BYTES = 64 * 1024;
const MAX_COMPOSE_BYTES = 256 * 1024;
const COMPOSE_NAMES = ['compose.yaml', 'compose.yml', 'docker-compose.yaml', 'docker-compose.yml'];
const OVERRIDES = ['compose.override.yaml', 'compose.override.yml', 'docker-compose.override.yaml', 'docker-compose.override.yml'];
const CI_WHERE = 'GitHub Actions';
const opaque = (w: string) => /[{}$`*?]|^\s*$/.test(w);
const inside = (top: string, p: string) => p === top || p.startsWith(top + sep);
const isDir = (p: string) => { try { return statSync(p).isDirectory(); } catch { return false; } };
const lexists = (p: string) => { try { lstatSync(p); return true; } catch { return false; } };
const posix = (p: string) => p.split(sep).join('/');
interface Found extends WideAnchor { at: string; compose?: { file: string; literal: boolean }; cli?: Cli; ref?: string | null }
/* ------------------------------------------------------------- finding */
/** A folder joined to the step's folder, or null when it can't be known ($VAR, ~, absolute, outside the checkout). */
function joinDir(top: string, base: string | null, d: string | undefined): string | null {
if (base === null || d === undefined) return null;
const x = unquote(d);
if (opaque(x) || isAbsolute(x) || x.startsWith('~') || x === '-') return null;
const j = resolve(base, x);
return inside(top, j) ? j : null;
}
/** The step's folder is in this checkout's repo: no nested `.git` between it and the checkout. */
function sameRepo(top: string, at: string): boolean {
for (let d = at; d !== top && inside(top, d); d = resolve(d, '..')) if (lexists(join(d, '.git'))) return false;
return true;
}
/** `gh workflow run|view|enable <x>`, `gh run list|watch --workflow[=] <x>`: x, or null (another repo, a param, an id). */
function ciTarget(w: string[]): string | null {
if (w[0] !== 'gh') return null;
const rest = w.slice(3);
if (rest.some((a) => /^(?:-R|--repo)(?:=|$)/.test(a))) return null;
let x: string | undefined;
if (/^workflow$/.test(w[1] ?? '') && /^(?:run|view|enable)$/.test(w[2] ?? '')) {
for (let i = 0; i < rest.length; i++) {
const a = rest[i]!;
if (/^(?:-f|-F|--raw-field|--field|--ref|-r|--json|-q|--jq|-t|--template)$/.test(a)) { i++; continue; }
if (a === '--') { x = rest[i + 1]; break; }
if (a.startsWith('-')) continue;
x = a;
break;
}
} else if (w[1] === 'run' && /^(?:list|watch)$/.test(w[2] ?? '')) {
for (let i = 0; i < rest.length; i++) {
const a = rest[i]!;
const m = /^--workflow=(.*)$/.exec(a);
if (m) { x = m[1]; break; }
if (/^--workflow$/.test(a) || (w[2] === 'list' && a === '-w')) { x = rest[i + 1]; break; }
}
}
if (!x || opaque(x) || /^\d+$/.test(x) || x.includes('/')) return null;
return x;
}
/** The `--ref` a `gh workflow` call names: the value, '' for one that can't be read, null for none. */
function ciRef(w: string[]): string | null {
for (let i = 3; i < w.length; i++) {
const m = /^--ref=(.*)$/.exec(w[i]!);
if (m) return opaque(m[1]!) ? '' : m[1]!;
if (w[i] === '--ref' || w[i] === '-r') return w[i + 1] && !opaque(w[i + 1]!) ? w[i + 1]! : '';
}
return null;
}
/** The branch the checkout is on (its own HEAD, a worktree's included), or null (detached, unreadable). */
function headBranch(top: string): string | null {
const dot = join(top, '.git');
let dir = dot;
try {
if (statSync(dot).isFile()) {
const m = /^gitdir:\s*(.+?)\s*$/m.exec(readSmall(dot, 4096) ?? '');
if (!m) return null;
dir = resolve(top, m[1]!);
}
} catch { return null; }
const m = /^ref:\s*refs\/heads\/(\S+)\s*$/.exec(readSmall(join(dir, 'HEAD'), 4096) ?? '');
return m ? m[1]! : null;
}
/**
* gh acts on the repo on GitHub, and runs its default branch's CI file unless `--ref` names another: this folder
* speaks for that only when the checkout has one remote (gh picks among several, upstream first), is on that
* remote's default branch at the commit last fetched for it, and isn't sparse; `--ref` may name only that branch.
* Anything else is not sure: an older branch, a fork, a branch behind (review).
*/
function ciSpeaks(top: string, ref: string | null): boolean {
const git = gitOf(top);
if (!git || git.reftable || git.sparse || git.remotes.size !== 1) return false;
const remote = [...git.remotes.keys()][0]!;
const branch = headBranch(top);
if (!branch || (ref !== null && ref !== branch && ref !== `refs/heads/${branch}`)) return false;
const def = /^ref:\s*refs\/remotes\/[^/]+\/(\S+)\s*$/.exec(readSmall(join(git.common, 'refs', 'remotes', remote, 'HEAD'), 4096) ?? '');
if (!def || def[1] !== branch) return false;
const here = refOid(git, `refs/heads/${branch}`);
return here !== null && here === refOid(git, `refs/remotes/${remote}/${branch}`);
}
const SUB_VALUE = new Set(['-e', '--env', '-u', '--user', '-w', '--workdir', '--name', '--entrypoint', '-l', '--label', '--tail', '-n', '--index',
'--since', '--until', '--timeout', '--scale', '--pull', '--wait-timeout', '--exit-code-from', '--attach', '--no-attach', '--cap-add', '--cap-drop',
'--env-from-file', '--platform', '-p', '--publish', '-v', '--volume']);
const SUB_BOOL = new Set(['-d', '--detach', '--rm', '--build', '--no-build', '--no-deps', '--force-recreate', '--no-recreate', '--remove-orphans',
'--wait', '--abort-on-container-exit', '--always-recreate-deps', '-V', '--renew-anon-volumes', '--quiet-pull', '--no-start', '--no-color',
'--no-log-prefix', '--timestamps', '-f', '--follow', '-T', '--no-TTY', '-i', '--interactive', '--service-ports', '--use-aliases',
'--privileged', '-y', '--yes', '--dry-run', '-q', '--quiet']);
/** `docker compose` / `docker-compose` with up|run|exec|start|restart|logs|stop: the `-f` values and the service words. */
function composeCall(w: string[]): { files: string[]; services: string[] } | null {
let i: number;
if (w[0] === 'docker-compose') i = 1;
else if (w[0] === 'docker' && w[1] === 'compose') i = 2;
else return null;
const files: string[] = [];
for (; i < w.length; i++) {
const a = w[i]!;
if (a === '-f' || a === '--file') { files.push(w[++i] ?? ''); continue; }
if (/^--file=/.test(a)) { files.push(a.slice(7)); continue; }
if (/^-f./.test(a)) { files.push(a.slice(2)); continue; }
// Another env file or project folder can name other compose files.
if (/^(?:--env-file|--project-directory)(?:=|$)/.test(a)) return null;
if (/^(?:-p|--project-name|--profile|--ansi|--progress|--parallel)$/.test(a)) { i++; continue; }
if (a.startsWith('-')) {
if (a.includes('=') || /^--(?:dry-run|compatibility|all-resources|verbose)$/.test(a)) continue;
return null;
}
break;
}
const sub = w[i];
if (!sub || !/^(?:up|run|exec|start|restart|logs|stop)$/.test(sub)) return null;
const many = !/^(?:run|exec)$/.test(sub);
const services: string[] = [];
for (let j = i + 1; j < w.length; j++) {
const a = w[j]!;
if (a === '--') break;
if (a.startsWith('-')) {
if (a.includes('=')) continue;
if (a === '-t') { if (sub !== 'logs') j++; continue; }
if (SUB_VALUE.has(a)) { j++; continue; }
if (SUB_BOOL.has(a)) continue;
return null; // a flag not known: the next word may be its value
}
services.push(a);
if (!many) break;
}
return { files, services: services.filter((s) => !opaque(s) && /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/.test(s)) };
}
/** `<bin> x`, `npx <bin> x`, `npm exec <bin> x`, `node <bin target> x`: the program and x (P23). A flag before x: none. */
function cliCall(w: string[], bins: Map<string, string>): { prog: string; x: string } | null {
let i = 1;
let prog: string | undefined = w[0];
if (w[0] === 'npx' || (w[0] === 'npm' && w[1] === 'exec')) {
i = w[0] === 'npx' ? 1 : 2;
while (w[i] && /^(?:-y|--yes|--no|-q|--quiet)$/.test(w[i]!)) i++;
prog = w[i++];
if (!prog || prog.startsWith('-')) return null;
} else if (w[0] === 'node') {
const t = w[1];
if (!t || t.startsWith('-')) return null;
const n = binTarget(t);
prog = [...bins].find(([, target]) => target === n)?.[0];
i = 2;
}
if (!prog || !bins.has(prog)) return null;
const x = w[i];
if (!x || !/^[a-z][a-z0-9-]{1,30}$/.test(x)) return null;
return { prog, x };
}
function found(skill: ParsedSkill, checkout: string): Found[] {
if (!checkout) return [];
const top = resolve(checkout);
const out: Found[] = [];
const all = skill.steps.map((s) => String(s.cmd ?? '')).join('\n');
const ciNever = /\bGH_REPO=/.test(all);
const composeNever = /\bCOMPOSE_FILE=/.test(all);
let moved = false; // a `cd` partway through a step or in an earlier one: later folders aren't known
for (const st of skill.steps) {
const { cds, rest } = leadingCds(String(st.cmd ?? ''));
let at: string | null = moved ? null : top;
for (const c of cds) at = joinDir(top, at, c);
if (cds.length) moved = true;
for (const simple of simpleCommands(rest || '')) {
const w = programWords(simple).map(unquote);
if (/^(?:cd|pushd|popd)$/.test(w[0] ?? '')) { at = null; moved = true; continue; }
if (at === null || !sameRepo(top, at)) continue;
const push = (f: Found) => { if (!out.some((o) => o.kind === f.kind && o.name === f.name && o.where === f.where)) out.push(f); };
const ci = ciNever ? null : ciTarget(w);
if (ci) push({ kind: 'ci-file', name: ci, step: st.n, where: CI_WHERE, at, ref: ciRef(w) });
const dc = composeNever ? null : composeCall(w);
if (dc && dc.files.length <= 1) {
const f = dc.files[0];
let file: string | undefined;
if (f !== undefined) {
const x = unquote(f);
file = opaque(x) || isAbsolute(x) || x.startsWith('~') || x === '-' ? undefined : resolve(at, x);
if (file && (!inside(top, file) || inside(actionsFolder(top), file))) file = undefined; // P22: that path is never printed
} else {
const name = COMPOSE_NAMES.find((n) => lexists(join(at!, n)));
file = name ? join(at, name) : undefined;
}
if (file) for (const s of dc.services) push({ kind: 'service', name: s, step: st.n, where: posix(relative(top, file)), at, compose: { file, literal: f !== undefined } });
}
const near = /^(?:gh|docker|docker-compose)$/.test(w[0] ?? '') ? null : binsNear(top, relative(top, at));
const call = near ? cliCall(w, near.bins) : null;
if (near && call) push({ kind: 'subcommand', name: call.x, step: st.n, where: call.prog, at, cli: { prog: call.prog, pkgDir: near.pkgDir, target: near.bins.get(call.prog)! } });
}
}
return out;
}
const plain = (f: Found): WideAnchor => ({ kind: f.kind, name: f.name, step: f.step, where: f.where });
/** The wider anchors in the skill's steps that can be checked here, each once (the first step that leans on it). */
export function wideAnchorsOf(skill: ParsedSkill, checkout: string, _env: NodeJS.ProcessEnv = process.env): WideAnchor[] {
return found(skill, checkout).map(plain);
}
/* ------------------------------------------------------------ checking */
/**
* A CI file's top-level `name:`: the name, null when the file has none, undefined when it can't be read plainly. A
* byte-order mark is dropped and a quoted key (`"name":`) counts; a file with no top-level key at all (a document
* indented as a whole, a flow mapping) is not sure (review).
*/
function topName(text: string): string | null | undefined {
let keys = 0;
for (const line of text.replace(/^\uFEFF/, '').replace(/\r/g, '').split('\n')) {
if (/^(?:[A-Za-z_][\w-]*|"[^"]*"|'[^']*')\s*:/.test(line)) keys++;
const m = /^(?:name|"name"|'name')\s*:(.*)$/.exec(line);
if (!m) continue;
const v = m[1]!.trim();
const q = /^(["'])(.*?)\1\s*(?:#.*)?$/.exec(v);
if (q) return q[1] === '"' && q[2]!.includes('\\') ? undefined : q[2]!;
const bare = v.replace(/\s+#.*$/, '').trim();
if (!bare || /^[|>&*!%@`"'[{]/.test(bare)) return undefined;
return bare;
}
return keys ? null : undefined;
}
/** The Actions folder, read once per check: its CI file names and top-level names (lower case), or why it can't judge. */
type CiFolder = { files: Set<string>; names: Set<string> } | 'absent' | 'unsure';
function ciFolder(top: string, deadline: number): CiFolder {
const folder = actionsFolder(top);
if (!isDir(folder)) return 'absent';
const list = readdirSync(folder).filter((n) => /\.ya?ml$/i.test(n));
if (list.length > MAX_CI_FILES) return 'unsure';
const files = new Set<string>();
const names = new Set<string>();
for (const n of list) {
if (Date.now() > deadline) return 'unsure';
files.add(n.replace(/\.ya?ml$/i, '').toLowerCase());
const text = readSmall(join(folder, n), MAX_CI_BYTES);
if (text === null) return 'unsure';
const name = topName(text);
if (name === undefined) return 'unsure';
if (name !== null) names.add(name.toLowerCase());
}
return { files, names };
}
function ciGone(top: string, x: string, folder: () => CiFolder): boolean {
if (/\.ya?ml$/i.test(x)) return isDir(actionsFolder(top)) && !lexists(join(actionsFolder(top), x));
const f = folder();
if (f === 'absent' || f === 'unsure') return false;
const want = x.toLowerCase();
return !f.files.has(want) && !f.names.has(want);
}
/** The service keys one indent under a column-0 `services:`; null when not sure (4.13, P25). */
export function composeServices(text: string): Set<string> | null {
if (/^\s*(?:include|extends)\s*:/m.test(text) || /<<\s*:/.test(text)) return null;
const lines = text.replace(/\r/g, '').split('\n');
let start = -1;
for (let i = 0; i < lines.length; i++) {
if (!/^services\s*:/.test(lines[i]!)) continue;
if (start >= 0 || !/^services\s*:\s*(?:#.*)?$/.test(lines[i]!)) return null;
start = i;
}
if (start < 0) return null;
let indent: string | null = null;
const names = new Set<string>();
for (let j = start + 1; j < lines.length; j++) {
const l = lines[j]!;
if (/^\s*(?:#.*)?$/.test(l)) continue;
if (!/^\s/.test(l)) break;
const m = /^(\s+)(\S.*)$/.exec(l)!;
if (m[1]!.includes('\t')) return null;
indent ??= m[1]!;
if (m[1] === indent) {
const k = /^(?:"([^"\\]+)"|'([^']+)'|([A-Za-z0-9._-]+))\s*:(?:\s|$)/.exec(m[2]!);
if (!k) return null;
names.add((k[1] ?? k[2] ?? k[3])!);
} else if (m[1]!.length < indent.length) return null;
}
return names;
}
function serviceGone(top: string, f: Found, env: NodeJS.ProcessEnv): boolean {
const c = f.compose!;
if (env.COMPOSE_FILE) return false;
const folder = resolve(c.file, '..');
if (!c.literal && OVERRIDES.some((o) => lexists(join(folder, o)))) return false;
for (const e of new Set([join(f.at, '.env'), join(folder, '.env'), join(top, '.env')])) {
if (!lexists(e)) continue;
const text = readSmall(e, MAX_CI_BYTES);
if (text === null || /^\s*(?:export\s+)?COMPOSE_FILE\s*=/m.test(text)) return false;
}
const text = readSmall(c.file, MAX_COMPOSE_BYTES);
const names = text === null ? null : composeServices(text);
return names !== null && !names.has(f.name);
}
/**
* Gone only when sure (4.13). `scan: false` reads only the cache for subcommands (SessionStart); `scan: true` may
* scan the CLI's source until `deadline` (default: WIDE_SCAN_MS from now). A check that throws or runs out of time is
* not gone, and a scan past its deadline caches nothing.
*/
export function wideGone(skill: ParsedSkill, checkout: string, env: NodeJS.ProcessEnv = process.env, opts: { scan: boolean; deadline?: number } = { scan: false }): WideAnchor[] {
const out: WideAnchor[] = [];
if (!checkout) return out;
const top = resolve(checkout);
const deadline = opts.deadline ?? Date.now() + WIDE_SCAN_MS;
const names = new Map<string, string[] | null>();
let ci: CiFolder | undefined;
const folder = () => (ci ??= ciFolder(top, deadline));
const speaks = new Map<string | null, boolean>();
const ciHere = (ref: string | null) => { if (!speaks.has(ref)) speaks.set(ref, ciSpeaks(top, ref)); return speaks.get(ref)!; };
// A sparse checkout leaves files out on purpose (D109): a CI file or a registration missing there is not sure.
let sparse: boolean | undefined;
const isSparse = () => (sparse ??= gitOf(top)?.sparse === true);
let all: Found[];
try { all = found(skill, checkout); } catch { return out; }
for (const f of all) {
try {
if (f.kind === 'ci-file' && !env.GH_REPO && ciHere(f.ref ?? null) && ciGone(top, f.name, folder)) out.push(plain(f));
else if (f.kind === 'service' && serviceGone(top, f, env)) out.push(plain(f));
else if (f.kind === 'subcommand' && f.cli && !isSparse()) {
const key = `${f.cli.pkgDir}\0${f.cli.prog}`;
if (!names.has(key)) names.set(key, cliNames(f.cli, top, env, { scan: opts.scan, deadline }));
if (subcommandGone(names.get(key)!, f.name)) out.push(plain(f));
}
} catch { /* not sure */ }
}
return out;
}