@shrkcrft/structural-search 0.1.0-alpha.10

package/dist/engine/apply-rewrite.d.ts

@@ -0,0 +1,29 @@
+import type { IRewritePlan } from '../schema/rewrite.js';
+export interface IApplyRewriteOptions {
+    projectRoot: string;
+    /** When true, just compute what would be written (no fs touch). */
+    dryRun?: boolean;
+}
+export interface IApplyRewriteResult {
+    filesChanged: number;
+    filesAttempted: number;
+    bytesWritten: number;
+    /** Files whose pre-existing content didn't match plan.edits[i].before. */
+    conflicts: readonly string[];
+    diagnostics: readonly string[];
+}
+/**
+ * Apply a rewrite plan to disk.
+ *
+ * Edits are applied in reverse offset order so earlier offsets stay
+ * valid as later edits shrink/grow the file. If the file content has
+ * changed since the plan was computed (any edit's `before` no longer
+ * matches the text at its position), the whole file is skipped and
+ * reported in `conflicts`. This is the safety mechanism — never
+ * silently overwrite drifted content.
+ *
+ * Dry-run mode (`--dry-run`) computes everything except the
+ * `writeFileSync`; useful for previewing what `apply` would do.
+ */
+export declare function applyRewritePlan(plan: IRewritePlan, options: IApplyRewriteOptions): IApplyRewriteResult;
+//# sourceMappingURL=apply-rewrite.d.ts.map

package/dist/engine/apply-rewrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-rewrite.d.ts","sourceRoot":"","sources":["../../src/engine/apply-rewrite.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,oBAAoB,GAC5B,mBAAmB,CAgDrB"}

package/dist/engine/apply-rewrite.js

@@ -0,0 +1,68 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+/**
+ * Apply a rewrite plan to disk.
+ *
+ * Edits are applied in reverse offset order so earlier offsets stay
+ * valid as later edits shrink/grow the file. If the file content has
+ * changed since the plan was computed (any edit's `before` no longer
+ * matches the text at its position), the whole file is skipped and
+ * reported in `conflicts`. This is the safety mechanism — never
+ * silently overwrite drifted content.
+ *
+ * Dry-run mode (`--dry-run`) computes everything except the
+ * `writeFileSync`; useful for previewing what `apply` would do.
+ */
+export function applyRewritePlan(plan, options) {
+    let filesChanged = 0;
+    let bytesWritten = 0;
+    const conflicts = [];
+    const diagnostics = [];
+    for (const f of plan.files) {
+        const abs = nodePath.resolve(options.projectRoot, f.path);
+        let text;
+        try {
+            text = readFileSync(abs, 'utf8');
+        }
+        catch (e) {
+            diagnostics.push(`${f.path}: read failed (${e.message})`);
+            continue;
+        }
+        // Verify every edit's `before` still matches.
+        let drifted = false;
+        for (const e of f.edits) {
+            const current = text.slice(e.start, e.end);
+            if (current !== e.before) {
+                drifted = true;
+                conflicts.push(f.path);
+                diagnostics.push(`${f.path}:${e.line}: expected "${e.before}" at offset ${e.start}, found "${current}" — skipping file`);
+                break;
+            }
+        }
+        if (drifted)
+            continue;
+        let next = text;
+        // Apply in reverse.
+        const sorted = [...f.edits].sort((a, b) => b.start - a.start);
+        for (const e of sorted) {
+            next = next.slice(0, e.start) + e.replacement + next.slice(e.end);
+        }
+        if (next === text)
+            continue;
+        if (!options.dryRun) {
+            writeFileSync(abs, next, 'utf8');
+            bytesWritten += Buffer.byteLength(next, 'utf8');
+        }
+        else {
+            bytesWritten += Buffer.byteLength(next, 'utf8');
+        }
+        filesChanged += 1;
+    }
+    return {
+        filesAttempted: plan.files.length,
+        filesChanged,
+        bytesWritten,
+        conflicts,
+        diagnostics,
+    };
+}

package/dist/engine/match-pattern.d.ts

@@ -0,0 +1,12 @@
+import * as ts from 'typescript';
+import type { StructuralPattern } from '../schema/pattern.js';
+/**
+ * Test a single AST node against a pattern. Returns true when the node
+ * is the kind the pattern targets AND every declared constraint holds.
+ *
+ * Patterns are intentionally narrow — a missing constraint never blocks
+ * a match (only constraint failure does). The walker calls
+ * `matchPattern` for every node; the matcher dispatches by `kind`.
+ */
+export declare function matchPattern(node: ts.Node, pattern: StructuralPattern): boolean;
+//# sourceMappingURL=match-pattern.d.ts.map

package/dist/engine/match-pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match-pattern.d.ts","sourceRoot":"","sources":["../../src/engine/match-pattern.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,KAAK,EAQV,iBAAiB,EAClB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAmB/E"}

package/dist/engine/match-pattern.js

@@ -0,0 +1,150 @@
+import * as ts from 'typescript';
+/**
+ * Test a single AST node against a pattern. Returns true when the node
+ * is the kind the pattern targets AND every declared constraint holds.
+ *
+ * Patterns are intentionally narrow — a missing constraint never blocks
+ * a match (only constraint failure does). The walker calls
+ * `matchPattern` for every node; the matcher dispatches by `kind`.
+ */
+export function matchPattern(node, pattern) {
+    switch (pattern.kind) {
+        case 'Identifier':
+            return ts.isIdentifier(node) && matchIdentifier(node, pattern);
+        case 'StringLiteral':
+            return ts.isStringLiteral(node) && matchStringLiteral(node, pattern);
+        case 'CallExpression':
+            return ts.isCallExpression(node) && matchCallExpression(node, pattern);
+        case 'NewExpression':
+            return ts.isNewExpression(node) && matchNewExpression(node, pattern);
+        case 'ImportDeclaration':
+            return ts.isImportDeclaration(node) && matchImportDeclaration(node, pattern);
+        case 'ClassDeclaration':
+            return ts.isClassDeclaration(node) && matchClassDeclaration(node, pattern);
+        case 'Decorator':
+            return ts.isDecorator(node) && matchDecorator(node, pattern);
+        default:
+            return false;
+    }
+}
+function matchIdentifier(node, pat) {
+    if (pat.name && pat.name !== '*' && node.text !== pat.name)
+        return false;
+    if (pat.nameRegex) {
+        const re = new RegExp(pat.nameRegex);
+        if (!re.test(node.text))
+            return false;
+    }
+    return true;
+}
+function matchStringLiteral(node, pat) {
+    if (pat.text !== undefined && node.text !== pat.text)
+        return false;
+    if (pat.textRegex) {
+        const re = new RegExp(pat.textRegex);
+        if (!re.test(node.text))
+            return false;
+    }
+    return true;
+}
+function matchCallExpression(node, pat) {
+    if (pat.callee) {
+        const callee = unwrapCallee(node.expression);
+        if (!callee || !ts.isIdentifier(callee))
+            return false;
+        if (!matchIdentifier(callee, pat.callee))
+            return false;
+    }
+    if (pat.argCount !== undefined && node.arguments.length !== pat.argCount)
+        return false;
+    if (pat.minArgs !== undefined && node.arguments.length < pat.minArgs)
+        return false;
+    return true;
+}
+function matchNewExpression(node, pat) {
+    if (pat.callee) {
+        const callee = unwrapCallee(node.expression);
+        if (!callee || !ts.isIdentifier(callee))
+            return false;
+        if (!matchIdentifier(callee, pat.callee))
+            return false;
+    }
+    return true;
+}
+function matchImportDeclaration(node, pat) {
+    if (!ts.isStringLiteral(node.moduleSpecifier))
+        return false;
+    const spec = node.moduleSpecifier.text;
+    if (pat.from !== undefined && spec !== pat.from)
+        return false;
+    if (pat.fromRegex) {
+        const re = new RegExp(pat.fromRegex);
+        if (!re.test(spec))
+            return false;
+    }
+    if (pat.sideEffectOnly === true) {
+        if (node.importClause)
+            return false;
+    }
+    if (pat.importedName) {
+        const clause = node.importClause;
+        if (!clause)
+            return false;
+        if (clause.namedBindings &&
+            ts.isNamedImports(clause.namedBindings) &&
+            clause.namedBindings.elements.some((e) => e.name.text === pat.importedName || (e.propertyName && e.propertyName.text === pat.importedName))) {
+            return true;
+        }
+        if (clause.name && clause.name.text === pat.importedName)
+            return true;
+        return false;
+    }
+    return true;
+}
+function matchClassDeclaration(node, pat) {
+    if (pat.name !== undefined) {
+        if (!node.name || node.name.text !== pat.name)
+            return false;
+    }
+    if (pat.nameRegex) {
+        if (!node.name)
+            return false;
+        const re = new RegExp(pat.nameRegex);
+        if (!re.test(node.name.text))
+            return false;
+    }
+    if (pat.hasDecoratorNamed) {
+        const mods = ts.canHaveDecorators(node) ? ts.getDecorators(node) : undefined;
+        if (!mods || mods.length === 0)
+            return false;
+        const found = mods.some((d) => decoratorIdentifierName(d) === pat.hasDecoratorNamed);
+        if (!found)
+            return false;
+    }
+    return true;
+}
+function matchDecorator(node, pat) {
+    const name = decoratorIdentifierName(node);
+    if (pat.name !== undefined && name !== pat.name)
+        return false;
+    if (pat.isCall !== undefined) {
+        const isCall = ts.isCallExpression(node.expression);
+        if (pat.isCall !== isCall)
+            return false;
+    }
+    return true;
+}
+function decoratorIdentifierName(d) {
+    const expr = d.expression;
+    if (ts.isIdentifier(expr))
+        return expr.text;
+    if (ts.isCallExpression(expr) && ts.isIdentifier(expr.expression))
+        return expr.expression.text;
+    return undefined;
+}
+function unwrapCallee(expr) {
+    // Allow `Foo.bar(...)` to match callee Identifier `bar`.
+    if (ts.isPropertyAccessExpression(expr))
+        return expr.name;
+    return expr;
+}

package/dist/engine/plan-rewrite.d.ts

@@ -0,0 +1,21 @@
+import { type IRewritePlan, type RewriteRecipe } from '../schema/rewrite.js';
+import type { StructuralPattern } from '../schema/pattern.js';
+export interface IPlanRewriteOptions {
+    projectRoot: string;
+    pattern: StructuralPattern;
+    recipe: RewriteRecipe;
+    /** Restrict to specific project-relative files. */
+    files?: readonly string[];
+    /** Cap on returned edits per file. Default 200. */
+    perFileLimit?: number;
+    /** Cap on total files included in the plan. Default 5000. */
+    fileLimit?: number;
+}
+/**
+ * Compute a rewrite plan: per-file edits keyed by character offset.
+ *
+ * Pure function — does NOT touch disk. `applyRewritePlan` (sibling)
+ * is the only write step, and it requires a plan as input.
+ */
+export declare function planRewrite(options: IPlanRewriteOptions): IRewritePlan;
+//# sourceMappingURL=plan-rewrite.d.ts.map

package/dist/engine/plan-rewrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-rewrite.d.ts","sourceRoot":"","sources":["../../src/engine/plan-rewrite.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAkB9D,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB,mDAAmD;IACnD,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CA+CtE"}

package/dist/engine/plan-rewrite.js

@@ -0,0 +1,187 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import * as ts from 'typescript';
+import { STRUCTURAL_REWRITE_SCHEMA, } from "../schema/rewrite.js";
+import { matchPattern } from "./match-pattern.js";
+const SOURCE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts']);
+const SKIP_DIRS = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.git',
+    '.sharkcraft',
+    '.next',
+    '.cache',
+    '.tmp-pack',
+    'out',
+    'target',
+]);
+/**
+ * Compute a rewrite plan: per-file edits keyed by character offset.
+ *
+ * Pure function — does NOT touch disk. `applyRewritePlan` (sibling)
+ * is the only write step, and it requires a plan as input.
+ */
+export function planRewrite(options) {
+    const perFileLimit = options.perFileLimit ?? 200;
+    const fileLimit = options.fileLimit ?? 5000;
+    const diagnostics = [];
+    validatePatternRecipeMatch(options.pattern, options.recipe, diagnostics);
+    const targets = options.files
+        ? options.files.map((f) => nodePath.resolve(options.projectRoot, f)).slice(0, fileLimit)
+        : walk(options.projectRoot).slice(0, fileLimit);
+    const files = [];
+    let totalEdits = 0;
+    let filesScanned = 0;
+    for (const abs of targets) {
+        filesScanned += 1;
+        let text;
+        try {
+            text = readFileSync(abs, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        let sf;
+        try {
+            sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true, pickScriptKind(abs));
+        }
+        catch (e) {
+            diagnostics.push(`${nodePath.relative(options.projectRoot, abs)}: parse failed (${e.message})`);
+            continue;
+        }
+        const rel = nodePath.relative(options.projectRoot, abs).split(nodePath.sep).join('/');
+        const edits = [];
+        visit(sf, sf, options.pattern, options.recipe, edits, perFileLimit);
+        if (edits.length === 0)
+            continue;
+        // Sort by start ascending (also the order the visitor produced
+        // them — depth-first, so this is essentially a no-op but defensive).
+        edits.sort((a, b) => a.start - b.start);
+        files.push({ path: rel, edits });
+        totalEdits += edits.length;
+    }
+    return {
+        schema: STRUCTURAL_REWRITE_SCHEMA,
+        pattern: options.pattern,
+        recipe: options.recipe,
+        filesScanned,
+        totalEdits,
+        files,
+        diagnostics,
+    };
+}
+function visit(node, sf, pattern, recipe, edits, perFileLimit) {
+    if (edits.length >= perFileLimit)
+        return;
+    if (matchPattern(node, pattern)) {
+        const edit = applyRecipe(node, sf, recipe);
+        if (edit)
+            edits.push(edit);
+    }
+    ts.forEachChild(node, (child) => visit(child, sf, pattern, recipe, edits, perFileLimit));
+}
+function applyRecipe(node, sf, recipe) {
+    switch (recipe.kind) {
+        case 'replace-identifier-name': {
+            if (!ts.isIdentifier(node))
+                return undefined;
+            return makeEdit(sf, node.getStart(sf), node.getEnd(), recipe.to);
+        }
+        case 'replace-call-callee': {
+            if (!ts.isCallExpression(node))
+                return undefined;
+            const callee = node.expression;
+            if (ts.isIdentifier(callee)) {
+                return makeEdit(sf, callee.getStart(sf), callee.getEnd(), recipe.to);
+            }
+            if (ts.isPropertyAccessExpression(callee)) {
+                return makeEdit(sf, callee.getStart(sf), callee.getEnd(), recipe.to);
+            }
+            return undefined;
+        }
+        case 'replace-import-from': {
+            if (!ts.isImportDeclaration(node))
+                return undefined;
+            const spec = node.moduleSpecifier;
+            if (!ts.isStringLiteral(spec))
+                return undefined;
+            // Replace just the inner string; preserve the quote characters.
+            const start = spec.getStart(sf) + 1;
+            const end = spec.getEnd() - 1;
+            return makeEdit(sf, start, end, recipe.to);
+        }
+        default:
+            return undefined;
+    }
+}
+function makeEdit(sf, start, end, replacement) {
+    const before = sf.text.slice(start, end);
+    if (before === replacement) {
+        // No-op edit; skip.
+        return { start, end, replacement, before, line: 0 };
+    }
+    const lineNo = sf.getLineAndCharacterOfPosition(start).line + 1;
+    return { start, end, replacement, before, line: lineNo };
+}
+function validatePatternRecipeMatch(pattern, recipe, diagnostics) {
+    const expected = {
+        'replace-identifier-name': 'Identifier',
+        'replace-call-callee': 'CallExpression',
+        'replace-import-from': 'ImportDeclaration',
+    };
+    const want = expected[recipe.kind];
+    if (want !== pattern.kind) {
+        diagnostics.push(`recipe "${recipe.kind}" expects pattern kind "${want}" but got "${pattern.kind}" — no edits will be produced`);
+    }
+}
+function walk(root) {
+    const out = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (SKIP_DIRS.has(name))
+                continue;
+            if (name.startsWith('.') && name !== '.')
+                continue;
+            const full = nodePath.join(dir, name);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                stack.push(full);
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            if (!SOURCE_EXTS.has(nodePath.extname(full).toLowerCase()))
+                continue;
+            out.push(full);
+        }
+    }
+    return out.sort();
+}
+function pickScriptKind(absPath) {
+    const ext = nodePath.extname(absPath).toLowerCase();
+    switch (ext) {
+        case '.tsx': return ts.ScriptKind.TSX;
+        case '.jsx': return ts.ScriptKind.JSX;
+        case '.js':
+        case '.mjs':
+        case '.cjs': return ts.ScriptKind.JS;
+        default: return ts.ScriptKind.TS;
+    }
+}

package/dist/engine/run-search.d.ts

@@ -0,0 +1,17 @@
+import type { IStructuralSearchResult } from '../schema/match.js';
+import type { StructuralPattern } from '../schema/pattern.js';
+export interface IRunSearchOptions {
+    projectRoot: string;
+    pattern: StructuralPattern;
+    /** Restrict to specific project-relative files (skips the walker). */
+    files?: readonly string[];
+    /** Cap on returned matches. Default 500. */
+    limit?: number;
+}
+/**
+ * Run a structural pattern against a project (or a file subset). Returns
+ * up to `limit` matches. Files that fail to parse get a diagnostic but
+ * do not abort the search.
+ */
+export declare function runSearch(options: IRunSearchOptions): IStructuralSearchResult;
+//# sourceMappingURL=run-search.d.ts.map

package/dist/engine/run-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-search.d.ts","sourceRoot":"","sources":["../../src/engine/run-search.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAoB,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAkB9D,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,sEAAsE;IACtE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,iBAAiB,GAAG,uBAAuB,CAuC7E"}

package/dist/engine/run-search.js

@@ -0,0 +1,157 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import * as ts from 'typescript';
+import { matchPattern } from "./match-pattern.js";
+const SOURCE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts']);
+const SKIP_DIRS = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.git',
+    '.sharkcraft',
+    '.next',
+    '.cache',
+    '.tmp-pack',
+    'out',
+    'target',
+]);
+/**
+ * Run a structural pattern against a project (or a file subset). Returns
+ * up to `limit` matches. Files that fail to parse get a diagnostic but
+ * do not abort the search.
+ */
+export function runSearch(options) {
+    const { projectRoot, pattern } = options;
+    const limit = options.limit ?? 500;
+    const targets = options.files ? options.files.map((f) => nodePath.resolve(projectRoot, f)) : walk(projectRoot);
+    const matches = [];
+    const diagnostics = [];
+    let filesScanned = 0;
+    let truncated = false;
+    for (const abs of targets) {
+        if (truncated)
+            break;
+        filesScanned += 1;
+        let text;
+        try {
+            text = readFileSync(abs, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        let sf;
+        try {
+            sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true, pickScriptKind(abs));
+        }
+        catch (e) {
+            diagnostics.push(`${nodePath.relative(projectRoot, abs)}: parse failed (${e.message})`);
+            continue;
+        }
+        const rel = nodePath.relative(projectRoot, abs).split(nodePath.sep).join('/');
+        visit(sf, sf, rel, pattern, matches, limit);
+        if (matches.length >= limit) {
+            truncated = true;
+        }
+    }
+    return {
+        schema: 'sharkcraft.structural-search/v1',
+        pattern: { kind: pattern.kind, summary: summarisePattern(pattern) },
+        filesScanned,
+        matchCount: matches.length,
+        truncated,
+        matches,
+        diagnostics,
+    };
+}
+function visit(node, sf, relPath, pattern, out, limit) {
+    if (out.length >= limit)
+        return;
+    if (matchPattern(node, pattern)) {
+        const start = node.getStart(sf);
+        const { line, character } = sf.getLineAndCharacterOfPosition(start);
+        const end = Math.min(node.getEnd(), start + 200);
+        const excerpt = sf.text
+            .slice(start, end)
+            .replace(/\s+/g, ' ')
+            .trim()
+            .slice(0, 140);
+        out.push({
+            file: relPath,
+            line: line + 1,
+            column: character,
+            nodeKind: ts.SyntaxKind[node.kind] ?? String(node.kind),
+            excerpt,
+        });
+    }
+    ts.forEachChild(node, (child) => visit(child, sf, relPath, pattern, out, limit));
+}
+function walk(root) {
+    const out = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (SKIP_DIRS.has(name))
+                continue;
+            if (name.startsWith('.') && name !== '.')
+                continue;
+            const full = nodePath.join(dir, name);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                stack.push(full);
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            if (!SOURCE_EXTS.has(nodePath.extname(full).toLowerCase()))
+                continue;
+            out.push(full);
+        }
+    }
+    return out.sort();
+}
+function pickScriptKind(absPath) {
+    const ext = nodePath.extname(absPath).toLowerCase();
+    switch (ext) {
+        case '.tsx': return ts.ScriptKind.TSX;
+        case '.jsx': return ts.ScriptKind.JSX;
+        case '.js':
+        case '.mjs':
+        case '.cjs': return ts.ScriptKind.JS;
+        default: return ts.ScriptKind.TS;
+    }
+}
+function summarisePattern(p) {
+    switch (p.kind) {
+        case 'Identifier':
+            return `Identifier name=${p.name ?? p.nameRegex ?? '*'}`;
+        case 'StringLiteral':
+            return `StringLiteral text=${p.text ?? p.textRegex ?? '*'}`;
+        case 'CallExpression':
+            return `CallExpression callee=${p.callee?.name ?? p.callee?.nameRegex ?? '*'}`;
+        case 'NewExpression':
+            return `NewExpression callee=${p.callee?.name ?? p.callee?.nameRegex ?? '*'}`;
+        case 'ImportDeclaration':
+            return `ImportDeclaration from=${p.from ?? p.fromRegex ?? '*'}`;
+        case 'ClassDeclaration':
+            return `ClassDeclaration name=${p.name ?? p.nameRegex ?? '*'} decorator=${p.hasDecoratorNamed ?? '-'}`;
+        case 'Decorator':
+            return `Decorator name=${p.name ?? '*'}`;
+        default:
+            return 'unknown';
+    }
+}