diffninja 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { Cli } from "incur";
+/**
+ * Whether the user asked incur to count or slice the output by tokens.
+ *
+ * These globals act on the value a command *returns*, so the ASCII fast path
+ * (which writes to stdout itself) has to opt out of them — otherwise the flags
+ * silently do nothing. See `emitAsciiOrData`.
+ */
+export declare function hasTokenFlag(argv: string[]): boolean;
+/** Strip lone `--` so `calldiff a b -- src` still works with incur. */
+export declare function normalizeArgv(argv: string[]): string[];
+export declare const cli: Cli.Cli<{
+    diff: {
+        args: {
+            from?: string | undefined;
+            to?: string | undefined;
+            paths?: string[] | undefined;
+        };
+        options: {
+            maxDepth: number;
+            locs: boolean;
+            entry?: string | string[] | undefined;
+            file?: string | string[] | undefined;
+            from?: string | undefined;
+            to?: string | undefined;
+        };
+    };
+} & {
+    tree: {
+        args: {
+            ref?: string | undefined;
+            paths?: string[] | undefined;
+        };
+        options: {
+            maxDepth: number;
+            locs: boolean;
+            entry?: string | string[] | undefined;
+            file?: string | string[] | undefined;
+        };
+    };
+} & {
+    reach: {
+        args: {
+            ref?: string | undefined;
+            paths?: string[] | undefined;
+        };
+        options: {
+            to: string;
+            maxDepth: number;
+            locs: boolean;
+            entry?: string | string[] | undefined;
+            file?: string | string[] | undefined;
+        };
+    };
+}, undefined, undefined, undefined>;
+export default cli;

package/dist/cli.js

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Cli, z } from "incur";
+import { runDiff, runReach, runTree } from "./run.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function readVersion() {
+    try {
+        const raw = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf8"));
+        // SAFETY: package.json is authored by this repo; only version is read.
+        const pkg = raw;
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const TOKEN_FLAGS = ["--token-count", "--token-limit", "--token-offset"];
+/**
+ * Whether the user asked incur to count or slice the output by tokens.
+ *
+ * These globals act on the value a command *returns*, so the ASCII fast path
+ * (which writes to stdout itself) has to opt out of them — otherwise the flags
+ * silently do nothing. See `emitAsciiOrData`.
+ */
+export function hasTokenFlag(argv) {
+    return argv.some((token) => TOKEN_FLAGS.some((flag) => token === flag || token.startsWith(`${flag}=`)));
+}
+/**
+ * Set from the argv actually being served. incur does not pass the raw argv to
+ * command handlers, and `normalizeArgv` is the one funnel every entry point
+ * (the CLI below, and the tests) already runs argv through.
+ */
+let tokenFlagActive = false;
+/** Strip lone `--` so `calldiff a b -- src` still works with incur. */
+export function normalizeArgv(argv) {
+    tokenFlagActive = hasTokenFlag(argv);
+    return argv.filter((token) => token !== "--");
+}
+function entriesFromOption(entry) {
+    if (entry === undefined)
+        return undefined;
+    return Array.isArray(entry) ? entry : [entry];
+}
+/**
+ * Default: classic ASCII (TTY + pipes) with optional CTAs.
+ * `--format` / `--json`: structured envelope for agents.
+ *
+ * The ASCII path writes to stdout itself so that piped output stays raw text
+ * (incur wraps a scalar payload as `{ data, cta }` once a CTA is attached).
+ * `--token-count` / `--token-limit` / `--token-offset` act on what a command
+ * *returns*, though, so under those flags we hand the ASCII back to incur and
+ * let it do the counting and slicing. The CTA is dropped there on purpose: it
+ * keeps the counted output exactly the tree the user asked about.
+ */
+function emitAsciiOrData(c, result, cta) {
+    if (!c.formatExplicit) {
+        if (tokenFlagActive)
+            return result.ascii;
+        process.stdout.write(result.ascii.endsWith("\n") ? result.ascii : `${result.ascii}\n`);
+        if (cta)
+            return c.ok({}, cta);
+        return;
+    }
+    return result;
+}
+const entryOption = z
+    .union([z.string(), z.array(z.string())])
+    .describe("Entrypoint symbol(s): functionName or ClassName.method");
+const fileOption = z
+    .union([z.string(), z.array(z.string())])
+    .describe("Entrypoint file(s): indexed source path; expands to that file's exports");
+const maxDepthOption = z.coerce
+    .number()
+    .default(12)
+    .describe("Max call-tree depth");
+const locsOption = z
+    .boolean()
+    .default(false)
+    .describe("Show call-site source locations (file:line)");
+const pathsArg = z
+    .array(z.string())
+    .optional()
+    .describe("Limit to these path prefixes");
+export const cli = Cli.create("calldiff", {
+    description: "Diff call stacks across git commits for agentic code review (23 languages)",
+    version: readVersion(),
+    hint: "Commands: diff (compare two trees), tree (view one tree), reach (paths between symbols). Path filters are trailing positionals (a leading -- is also accepted). Use --format json for structured agent output.",
+    sync: {
+        // One skill file covering all commands (default incur depth is 1 = per-command).
+        depth: 0,
+        suggestions: [
+            "Diff HEAD against my working tree with calldiff diff",
+            "View the call tree for createAgentSession with calldiff tree",
+            "Find call paths from runCheckout to sendEmail with calldiff reach",
+        ],
+    },
+})
+    .command("diff", {
+    description: "Diff call stacks between two git trees",
+    args: z.object({
+        from: z.string().optional().describe("Before ref (default: HEAD)"),
+        to: z.string().optional().describe("After ref (default: working tree)"),
+        paths: pathsArg,
+    }),
+    options: z.object({
+        entry: entryOption.optional(),
+        file: fileOption.optional(),
+        maxDepth: maxDepthOption,
+        locs: locsOption,
+        from: z.string().optional().describe('Left / "before" tree'),
+        to: z.string().optional().describe('Right / "after" tree'),
+    }),
+    alias: { entry: "e", file: "F" },
+    examples: [
+        { description: "HEAD vs working tree" },
+        {
+            description: "One ref vs working tree",
+            args: { from: "main" },
+        },
+        {
+            description: "Two commits / branches",
+            args: { from: "abc123", to: "def456" },
+        },
+        {
+            description: "Force entrypoints",
+            args: { from: "main", to: "feature" },
+            options: { entry: "createAgentSession" },
+        },
+        {
+            description: "File as entrypoint (all exports in that file)",
+            args: { from: "main", to: "feature" },
+            options: { file: "src/routes.ts" },
+        },
+    ],
+    usage: [
+        {},
+        { args: { from: true } },
+        { args: { from: true, to: true } },
+        {
+            args: { from: true, to: true, paths: true },
+            options: { entry: true },
+        },
+    ],
+    hint: "Semantics match git diff: no refs → HEAD vs worktree; one ref → that vs worktree; two refs → compare those trees.",
+    run(c) {
+        const entries = entriesFromOption(c.options.entry);
+        const files = entriesFromOption(c.options.file);
+        let result;
+        try {
+            result = runDiff({
+                from: c.options.from ?? c.args.from,
+                to: c.options.to ?? c.args.to,
+                entries,
+                files,
+                paths: c.args.paths,
+                maxDepth: c.options.maxDepth,
+                locs: c.options.locs,
+                color: !c.formatExplicit && !c.agent,
+            });
+        }
+        catch (error) {
+            return c.error({
+                code: "DIFF_FAILED",
+                message: error instanceof Error ? error.message : String(error),
+                exitCode: 1,
+            });
+        }
+        const cta = result.trees.length > 0
+            ? {
+                cta: {
+                    commands: result.trees.slice(0, 3).map((t) => ({
+                        command: "tree",
+                        options: { entry: t.entry },
+                        description: `View full call tree for ${t.entry}`,
+                    })),
+                },
+            }
+            : undefined;
+        return emitAsciiOrData(c, result, cta);
+    },
+})
+    .command("tree", {
+    description: "View a call tree (no diff) for one or more entrypoints",
+    args: z.object({
+        ref: z
+            .string()
+            .optional()
+            .describe("Git ref (default: working tree)"),
+        paths: pathsArg,
+    }),
+    options: z.object({
+        entry: entryOption.optional(),
+        file: fileOption.optional(),
+        maxDepth: maxDepthOption,
+        locs: locsOption,
+    }),
+    alias: { entry: "e", file: "F" },
+    examples: [
+        {
+            description: "Tree from working tree",
+            options: { entry: "createAgentSession" },
+        },
+        {
+            description: "Tree from a commit",
+            args: { ref: "HEAD" },
+            options: { entry: "PiService.createAgentSession" },
+        },
+        {
+            description: "Tree for every export in a file",
+            options: { file: "packages/api/src/routes.ts" },
+        },
+    ],
+    run(c) {
+        const entries = entriesFromOption(c.options.entry) ?? [];
+        const files = entriesFromOption(c.options.file) ?? [];
+        if (entries.length === 0 && files.length === 0) {
+            return c.error({
+                code: "MISSING_ENTRY",
+                message: "calldiff tree requires --entry / -e or --file / -F",
+                exitCode: 2,
+            });
+        }
+        try {
+            const result = runTree({
+                ref: c.args.ref,
+                entries,
+                files,
+                paths: c.args.paths,
+                maxDepth: c.options.maxDepth,
+                locs: c.options.locs,
+                color: !c.formatExplicit && !c.agent,
+            });
+            return emitAsciiOrData(c, result);
+        }
+        catch (error) {
+            return c.error({
+                code: "TREE_FAILED",
+                message: error instanceof Error ? error.message : String(error),
+                exitCode: 1,
+            });
+        }
+    },
+})
+    .command("reach", {
+    description: "Find all call paths from an entrypoint to a target symbol",
+    args: z.object({
+        ref: z
+            .string()
+            .optional()
+            .describe("Git ref (default: working tree)"),
+        paths: pathsArg,
+    }),
+    options: z.object({
+        entry: entryOption.optional(),
+        file: fileOption.optional(),
+        to: z
+            .string()
+            .describe("Target symbol to reach (functionName or ClassName.method)"),
+        maxDepth: maxDepthOption,
+        locs: locsOption,
+    }),
+    alias: { entry: "e", file: "F" },
+    examples: [
+        {
+            description: "Paths in the working tree",
+            options: { entry: "runCheckout", to: "sendEmail" },
+        },
+        {
+            description: "Paths at a commit, limited to a directory",
+            args: { ref: "HEAD", paths: ["examples/checkout"] },
+            options: { entry: "runCheckout", to: "sendEmail" },
+        },
+        {
+            description: "Paths from every export in a file",
+            options: { file: "packages/api/src/flow.ts", to: "notify" },
+        },
+    ],
+    run(c) {
+        const entries = entriesFromOption(c.options.entry) ?? [];
+        const files = entriesFromOption(c.options.file) ?? [];
+        if (entries.length === 0 && files.length === 0) {
+            return c.error({
+                code: "MISSING_ENTRY",
+                message: "calldiff reach requires --entry / -e or --file / -F",
+                exitCode: 2,
+            });
+        }
+        if (!c.options.to) {
+            return c.error({
+                code: "MISSING_TARGET",
+                message: "calldiff reach requires --to <symbol>",
+                exitCode: 2,
+            });
+        }
+        try {
+            const result = runReach({
+                ref: c.args.ref,
+                entries,
+                files,
+                to: c.options.to,
+                paths: c.args.paths,
+                maxDepth: c.options.maxDepth,
+                locs: c.options.locs,
+                color: !c.formatExplicit && !c.agent,
+            });
+            return emitAsciiOrData(c, result);
+        }
+        catch (error) {
+            return c.error({
+                code: "REACH_FAILED",
+                message: error instanceof Error ? error.message : String(error),
+                exitCode: 1,
+            });
+        }
+    },
+});
+export default cli;
+/** True when this file is the process entry (including npm `.bin` symlinks). */
+function executedAsCli() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+    }
+    catch {
+        return (entry.endsWith("/cli.ts") ||
+            entry.endsWith("/cli.js") ||
+            entry.endsWith("\\cli.ts") ||
+            entry.endsWith("\\cli.js"));
+    }
+}
+if (executedAsCli()) {
+    cli.serve(normalizeArgv(process.argv.slice(2))).catch((error) => {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+    });
+}

package/dist/diff.d.ts

@@ -0,0 +1,7 @@
+import type { CallNode, DiffNode } from "./types.js";
+/**
+ * Structural tree diff keyed by call identity.
+ * Children are aligned with LCS so output order stays close to the "after" tree.
+ */
+export declare function diffTrees(before: CallNode, after: CallNode): DiffNode;
+export declare function treeHasChanges(node: DiffNode): boolean;

package/dist/diff.js

@@ -0,0 +1,114 @@
+import { pickLoc } from "./loc.js";
+/**
+ * Structural tree diff keyed by call identity.
+ * Children are aligned with LCS so output order stays close to the "after" tree.
+ */
+export function diffTrees(before, after) {
+    return diffNode(before, after);
+}
+function diffNode(before, after) {
+    if (before && after) {
+        const node = {
+            key: after.key,
+            label: after.label,
+            kind: after.kind ?? before.kind,
+            ...pickLoc(after.file ? after : before),
+            // The definition is the one `after` resolved: a call whose callee lost its
+            // indexed definition reports no definition rather than a stale before one.
+            status: "same",
+            children: diffChildren(before.children, after.children),
+        };
+        if (after.definition)
+            node.definition = after.definition;
+        return node;
+    }
+    if (after) {
+        const node = {
+            key: after.key,
+            label: after.label,
+            kind: after.kind,
+            ...pickLoc(after),
+            status: "added",
+            children: after.children.map(markTree("added")),
+        };
+        if (after.definition)
+            node.definition = after.definition;
+        return node;
+    }
+    if (before) {
+        const node = {
+            key: before.key,
+            label: before.label,
+            kind: before.kind,
+            ...pickLoc(before),
+            status: "removed",
+            children: before.children.map(markTree("removed")),
+        };
+        if (before.definition)
+            node.definition = before.definition;
+        return node;
+    }
+    throw new Error("diffNode called with no trees");
+}
+function markTree(status) {
+    return function mark(node) {
+        const marked = {
+            key: node.key,
+            label: node.label,
+            kind: node.kind,
+            ...pickLoc(node),
+            status,
+            children: node.children.map(mark),
+        };
+        if (node.definition)
+            marked.definition = node.definition;
+        return marked;
+    };
+}
+function diffChildren(before, after) {
+    const n = before.length;
+    const m = after.length;
+    const dp = Array.from({ length: n + 1 }, () => Array.from({ length: m + 1 }, () => 0));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            if (before[i].key === after[j].key) {
+                dp[i][j] = dp[i + 1][j + 1] + 1;
+            }
+            else {
+                dp[i][j] = Math.max(dp[i + 1][j], dp[i][j + 1]);
+            }
+        }
+    }
+    const result = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (before[i].key === after[j].key) {
+            result.push(diffNode(before[i], after[j]));
+            i += 1;
+            j += 1;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1]) {
+            result.push(diffNode(before[i], null));
+            i += 1;
+        }
+        else {
+            result.push(diffNode(null, after[j]));
+            j += 1;
+        }
+    }
+    while (i < n) {
+        result.push(diffNode(before[i], null));
+        i += 1;
+    }
+    while (j < m) {
+        result.push(diffNode(null, after[j]));
+        j += 1;
+    }
+    return result;
+}
+export function treeHasChanges(node) {
+    if (node.status !== "same")
+        return true;
+    return node.children.some(treeHasChanges);
+}

package/dist/extract.d.ts

@@ -0,0 +1,26 @@
+import type { CallStep, FunctionInfo } from "./types.js";
+export declare function extractFunctions(file: string, source: string): FunctionInfo[];
+type CachedFunction = Omit<FunctionInfo, "file">;
+export type ExtractionCache = Map<string, CachedFunction[]>;
+export declare function extractCached(file: string, source: string, cache: ExtractionCache): FunctionInfo[];
+export type FunctionIndex = Map<string, FunctionInfo>;
+/** Callable and non-callable declarations available to snapshot review context. */
+export declare function allContextDefinitions(index: FunctionIndex): FunctionInfo[];
+/** NUL cannot occur in a path or a symbol key, so it is a safe separator. */
+export declare function fileScopedKey(file: string, key: string): string;
+export declare function flattenCallKeys(steps: CallStep[]): string[];
+/**
+ * Every function recorded when the index was built (including duplicates that
+ * lost the bare-key race). Indexes created as plain Maps fall back to values().
+ */
+export declare function allFunctions(index: FunctionIndex): FunctionInfo[];
+/**
+ * Definitions of `key` declared in `file`, top-level before locals, then in
+ * source order. Empty when that file declares none.
+ *
+ * Indexes created as plain Maps (not via {@link buildIndex}) fall back to a
+ * scan of their values.
+ */
+export declare function definitionsInFile(index: FunctionIndex, file: string, key: string): FunctionInfo[];
+export declare function buildIndex(functions: FunctionInfo[]): FunctionIndex;
+export {};

package/dist/extract.js

@@ -0,0 +1,152 @@
+/**
+ * Multi-language extraction: detect by file extension, load grammar
+ * (bundled or on-demand cache), parse, then run the language extractor.
+ */
+import { createHash } from "node:crypto";
+import Parser from "tree-sitter";
+import { loadGrammarPackage, resolveLanguage, } from "./languages/grammars.js";
+import { detectLanguage } from "./languages/registry.js";
+import { linesFromOffsets } from "./loc.js";
+const parser = new Parser();
+const languageCache = new Map();
+function grammarKey(npmPackage, grammarExport) {
+    return grammarExport ? `${npmPackage}:${grammarExport}` : npmPackage;
+}
+function loadLanguage(npmPackage, grammarExport) {
+    const key = grammarKey(npmPackage, grammarExport);
+    const cached = languageCache.get(key);
+    if (cached)
+        return cached;
+    const mod = loadGrammarPackage(npmPackage);
+    const language = resolveLanguage(mod, grammarExport);
+    languageCache.set(key, language);
+    return language;
+}
+export function extractFunctions(file, source) {
+    const extractor = detectLanguage(file);
+    if (!extractor)
+        return [];
+    const language = loadLanguage(extractor.grammarPackage, extractor.grammarExport);
+    // Grammar package exports are accepted by setLanguage at runtime; the
+    // published Language type requires fields not present on every package.
+    // @ts-expect-error tree-sitter Language under-specifies grammar module exports
+    parser.setLanguage(language);
+    const tree = parser.parse(source);
+    return extractor.extract(file, source, tree).map((fn) => {
+        if (fn.line != null)
+            return fn;
+        const lines = linesFromOffsets(source, fn.start, fn.end);
+        return { ...fn, ...lines };
+    });
+}
+export function extractCached(file, source, cache) {
+    const extractor = detectLanguage(file);
+    if (!extractor)
+        return [];
+    const digest = createHash("sha256").update(source).digest("hex");
+    const key = `${file}\0${extractor.id}\0${digest}`;
+    let functions = cache.get(key);
+    if (!functions) {
+        functions = extractFunctions(file, source).map(({ file: _ignored, ...fn }) => fn);
+        cache.set(key, functions);
+    }
+    return functions.map((fn) => ({ ...fn, file }));
+}
+/**
+ * Full extraction list for an index, including definitions shadowed by
+ * first-wins bare-key insertion in {@link buildIndex}.
+ */
+const indexDefinitions = new WeakMap();
+const indexContextDefinitions = new WeakMap();
+/** Callable and non-callable declarations available to snapshot review context. */
+export function allContextDefinitions(index) {
+    return indexContextDefinitions.get(index) ?? allFunctions(index);
+}
+/**
+ * Definitions grouped by `file\0key`, so a call can be resolved against the
+ * file it was written in instead of the global bare-key map. See #19.
+ */
+const indexByFile = new WeakMap();
+/** NUL cannot occur in a path or a symbol key, so it is a safe separator. */
+export function fileScopedKey(file, key) {
+    return `${file}\0${key}`;
+}
+export function flattenCallKeys(steps) {
+    const keys = [];
+    const walk = (list) => {
+        for (const step of list) {
+            if (step.type === "call") {
+                keys.push(step.key);
+                if (step.children)
+                    walk(step.children);
+            }
+            else {
+                walk(step.children);
+            }
+        }
+    };
+    walk(steps);
+    return keys;
+}
+/**
+ * Every function recorded when the index was built (including duplicates that
+ * lost the bare-key race). Indexes created as plain Maps fall back to values().
+ */
+export function allFunctions(index) {
+    return indexDefinitions.get(index) ?? [...index.values()];
+}
+/**
+ * Definitions of `key` declared in `file`, top-level before locals, then in
+ * source order. Empty when that file declares none.
+ *
+ * Indexes created as plain Maps (not via {@link buildIndex}) fall back to a
+ * scan of their values.
+ */
+export function definitionsInFile(index, file, key) {
+    const byFile = indexByFile.get(index);
+    if (byFile)
+        return byFile.get(fileScopedKey(file, key)) ?? [];
+    return [...index.values()].filter((fn) => fn.file === file && fn.key === key);
+}
+export function buildIndex(functions) {
+    const index = new Map();
+    const byFile = new Map();
+    const record = (fn) => {
+        const scoped = fileScopedKey(fn.file, fn.key);
+        const existing = byFile.get(scoped);
+        if (existing)
+            existing.push(fn);
+        else
+            byFile.set(scoped, [fn]);
+        if (!index.has(fn.key)) {
+            index.set(fn.key, fn);
+        }
+        if (fn.key.endsWith(".constructor")) {
+            const className = fn.key.slice(0, -".constructor".length);
+            const newKey = `new ${className}`;
+            const ctor = { ...fn, key: newKey, label: `new ${className}()` };
+            const scopedNew = fileScopedKey(fn.file, newKey);
+            const existingNew = byFile.get(scopedNew);
+            if (existingNew)
+                existingNew.push(ctor);
+            else
+                byFile.set(scopedNew, [ctor]);
+            if (!index.has(newKey)) {
+                index.set(newKey, ctor);
+            }
+        }
+    };
+    // Top level first: a helper declared inside a body must never take a bare key
+    // away from a real top-level definition somewhere else in the repo (#19).
+    const callables = functions.filter(fn => !fn.review?.kind);
+    for (const fn of callables)
+        if (!fn.local)
+            record(fn);
+    for (const fn of callables)
+        if (fn.local)
+            record(fn);
+    indexDefinitions.set(index, callables);
+    indexContextDefinitions.set(index, functions.slice());
+    indexByFile.set(index, byFile);
+    return index;
+}