diffninja 0.1.0

package/dist/languages/zig.d.ts

@@ -0,0 +1,2 @@
+import { type LanguageExtractor } from "./types.js";
+export declare const zigExtractor: LanguageExtractor;

package/dist/languages/zig.js

@@ -0,0 +1,243 @@
+import { heuristicCallSyntax } from "./call-syntax.js";
+import { childByType, collapseWs, locFromNode, namedChildren, sameNode, } from "./types.js";
+function getParamsLabel(params) {
+    if (!params || params.type !== "parameters")
+        return "()";
+    const names = [];
+    for (const p of namedChildren(params)) {
+        if (p.type !== "parameter")
+            continue;
+        const id = childByType(p, "identifier");
+        names.push(id?.text ?? "_");
+    }
+    return names.length === 0 ? "()" : `(${names.join(", ")})`;
+}
+function calleeKey(node, typeName) {
+    if (node.type === "identifier")
+        return node.text;
+    if (node.type === "field_expression") {
+        const object = node.namedChild(0);
+        const field = node.namedChild(1);
+        if (!object || !field)
+            return null;
+        const prop = field.text;
+        if (object.type === "identifier") {
+            if ((object.text === "self" || object.text === "this") && typeName) {
+                return `${typeName}.${prop}`;
+            }
+            return `${object.text}.${prop}`;
+        }
+        if (typeName)
+            return `${typeName}.${prop}`;
+        return prop;
+    }
+    // builtin @call etc.
+    if (node.type === "builtin_type" || node.type === "builtin_function") {
+        return null;
+    }
+    return null;
+}
+function statementsOf(block) {
+    if (!block)
+        return [];
+    if (block.type === "block" || block.type === "block_expression") {
+        const inner = block.type === "block_expression" ? childByType(block, "block") : block;
+        return inner ? namedChildren(inner) : namedChildren(block);
+    }
+    return [block];
+}
+function collectStatements(file, statements, typeName) {
+    const steps = [];
+    const seen = new Set();
+    const addCall = (key, node) => {
+        const mark = `${key}:${node.startIndex}`;
+        if (seen.has(mark))
+            return;
+        seen.add(mark);
+        const step = { type: "call", key, ...locFromNode(file, node) };
+        step.syntax = heuristicCallSyntax(node, key);
+        steps.push(step);
+    };
+    const walk = (node) => {
+        if (node.type === "function_declaration" ||
+            node.type === "struct_declaration" ||
+            node.type === "enum_declaration" ||
+            node.type === "union_declaration" ||
+            node.type === "opaque_declaration") {
+            return;
+        }
+        if (node.type === "if_statement") {
+            const kids = namedChildren(node);
+            const cond = kids.find((c) => c.type !== "block" &&
+                c.type !== "block_expression" &&
+                c.type !== "else_clause" &&
+                c.type !== "labeled_statement") ?? null;
+            const thenBlock = kids.find((c) => c.type === "block" || c.type === "block_expression") ?? null;
+            const elseClause = childByType(node, "else_clause");
+            const condText = cond ? collapseWs(cond.text) : "";
+            steps.push({
+                type: "branch",
+                key: condText ? `if:${condText}` : "if",
+                label: condText ? `if ${condText}` : "if",
+                ...locFromNode(file, cond ?? node),
+                children: collectStatements(file, statementsOf(thenBlock), typeName),
+            });
+            if (elseClause) {
+                // else_clause → block | labeled_statement → block | if_statement
+                const elseBody = childByType(elseClause, "block") ??
+                    childByType(elseClause, "block_expression") ??
+                    childByType(elseClause, "if_statement") ??
+                    childByType(elseClause, "labeled_statement") ??
+                    elseClause.namedChild(0) ??
+                    null;
+                if (elseBody?.type === "if_statement") {
+                    // else if — flatten by walking as nested if into else-if style
+                    const nested = collectStatements(file, [elseBody], typeName);
+                    for (const s of nested) {
+                        if (s.type === "branch" && s.key.startsWith("if:")) {
+                            steps.push({
+                                ...s,
+                                key: s.key.replace(/^if:/, "else-if:"),
+                                label: s.label.replace(/^if /, "else if "),
+                            });
+                        }
+                        else if (s.type === "branch" && s.key === "if") {
+                            steps.push({ ...s, key: "else-if", label: "else if" });
+                        }
+                        else {
+                            steps.push(s);
+                        }
+                    }
+                }
+                else if (elseBody?.type === "labeled_statement") {
+                    const blk = childByType(elseBody, "block") ?? elseBody.namedChild(0) ?? null;
+                    steps.push({
+                        type: "branch",
+                        key: "else",
+                        label: "else",
+                        ...locFromNode(file, elseClause),
+                        children: collectStatements(file, statementsOf(blk), typeName),
+                    });
+                }
+                else {
+                    steps.push({
+                        type: "branch",
+                        key: "else",
+                        label: "else",
+                        ...locFromNode(file, elseClause),
+                        children: collectStatements(file, statementsOf(elseBody), typeName),
+                    });
+                }
+            }
+            return;
+        }
+        if (node.type === "try_expression") {
+            steps.push({
+                type: "branch",
+                key: "try",
+                label: "try",
+                ...locFromNode(file, node),
+                children: collectStatements(file, namedChildren(node), typeName),
+            });
+            return;
+        }
+        if (node.type === "defer_statement") {
+            steps.push({
+                type: "branch",
+                key: "defer",
+                label: "defer",
+                ...locFromNode(file, node),
+                children: collectStatements(file, namedChildren(node), typeName),
+            });
+            return;
+        }
+        if (node.type === "switch_expression") {
+            for (const clause of namedChildren(node)) {
+                if (clause.type !== "switch_case")
+                    continue;
+                const kids = namedChildren(clause);
+                const bodyNode = kids.find((c) => c.type === "block" ||
+                    c.type === "block_expression" ||
+                    c.type === "call_expression" ||
+                    c.type === "identifier") ?? kids[kids.length - 1] ?? null;
+                const pattern = kids.find((c) => !sameNode(c, bodyNode)) ?? null;
+                const isElse = !pattern;
+                const text = pattern ? collapseWs(pattern.text) : "";
+                steps.push({
+                    type: "branch",
+                    key: isElse ? "else" : text ? `case:${text}` : "case",
+                    label: isElse ? "else" : text ? `case ${text}` : "case",
+                    ...locFromNode(file, pattern ?? clause),
+                    children: bodyNode
+                        ? collectStatements(file, [bodyNode], typeName)
+                        : [],
+                });
+            }
+            return;
+        }
+        if (node.type === "call_expression") {
+            const callee = node.namedChild(0);
+            if (callee) {
+                const key = calleeKey(callee, typeName);
+                if (key)
+                    addCall(key, node);
+            }
+            for (const child of namedChildren(node).slice(1))
+                walk(child);
+            return;
+        }
+        for (const child of namedChildren(node))
+            walk(child);
+    };
+    for (const stmt of statements)
+        walk(stmt);
+    return steps;
+}
+function handleFunction(file, node, typeName, functions) {
+    const name = childByType(node, "identifier")?.text ?? null;
+    if (!name)
+        return;
+    const params = childByType(node, "parameters");
+    const body = childByType(node, "block");
+    const key = typeName ? `${typeName}.${name}` : name;
+    functions.push({
+        key,
+        label: `${key}${getParamsLabel(params)}`,
+        file,
+        steps: body ? collectStatements(file, statementsOf(body), typeName) : [],
+        exported: true,
+        start: node.startIndex,
+        end: node.endIndex,
+    });
+}
+function handleStruct(file, name, struct, functions) {
+    for (const child of namedChildren(struct)) {
+        if (child.type === "function_declaration") {
+            handleFunction(file, child, name, functions);
+        }
+    }
+}
+function extractFromTree(file, _source, tree) {
+    const functions = [];
+    for (const stmt of namedChildren(tree.rootNode)) {
+        if (stmt.type === "function_declaration") {
+            handleFunction(file, stmt, null, functions);
+            continue;
+        }
+        if (stmt.type === "variable_declaration") {
+            const name = childByType(stmt, "identifier")?.text ?? null;
+            const struct = childByType(stmt, "struct_declaration");
+            if (name && struct) {
+                handleStruct(file, name, struct, functions);
+            }
+        }
+    }
+    return functions;
+}
+export const zigExtractor = {
+    id: "zig",
+    extensions: [".zig"],
+    // Modern grammar; npm `tree-sitter-zig` is nan-era and won't load on tree-sitter 0.25+
+    grammarPackage: "@tree-sitter-grammars/tree-sitter-zig",
+    extract: extractFromTree,
+};

package/dist/loc.d.ts

@@ -0,0 +1,17 @@
+import type { SourceLoc } from "./types.js";
+/** Pick optional loc fields for spreading onto a node/step. */
+export declare function pickLoc(loc: {
+    file?: string;
+    line?: number;
+    endLine?: number;
+} | null | undefined): Partial<SourceLoc>;
+/** Format as `file:line` or `file:line-line`. */
+export declare function formatSourceLoc(loc: SourceLoc): string;
+/**
+ * Convert byte offsets in `source` to 1-based line numbers.
+ * `end` is exclusive (tree-sitter endIndex).
+ */
+export declare function linesFromOffsets(source: string, start: number, end: number): {
+    line: number;
+    endLine?: number;
+};

package/dist/loc.js

@@ -0,0 +1,34 @@
+/** Pick optional loc fields for spreading onto a node/step. */
+export function pickLoc(loc) {
+    if (!loc?.file || loc.line == null)
+        return {};
+    if (loc.endLine != null && loc.endLine !== loc.line) {
+        return { file: loc.file, line: loc.line, endLine: loc.endLine };
+    }
+    return { file: loc.file, line: loc.line };
+}
+/** Format as `file:line` or `file:line-line`. */
+export function formatSourceLoc(loc) {
+    const range = loc.endLine != null && loc.endLine !== loc.line
+        ? `${loc.line}-${loc.endLine}`
+        : String(loc.line);
+    return `${loc.file}:${range}`;
+}
+/**
+ * Convert byte offsets in `source` to 1-based line numbers.
+ * `end` is exclusive (tree-sitter endIndex).
+ */
+export function linesFromOffsets(source, start, end) {
+    let line = 1;
+    for (let i = 0; i < start && i < source.length; i++) {
+        if (source.charCodeAt(i) === 10)
+            line += 1;
+    }
+    let endLine = line;
+    const last = Math.max(start, end - 1);
+    for (let i = start; i < last && i < source.length; i++) {
+        if (source.charCodeAt(i) === 10)
+            endLine += 1;
+    }
+    return endLine > line ? { line, endLine } : { line };
+}

package/dist/reach.d.ts

@@ -0,0 +1,17 @@
+import type { FunctionIndex } from "./extract.js";
+import type { CallNode } from "./types.js";
+/** Collapse a root→target node list into a linear single-child tree. */
+export declare function pathToTree(nodes: CallNode[]): CallNode;
+/**
+ * Collect every root-to-node path in `tree` that ends at `target`
+ * (first hit on a path; does not continue below the target).
+ */
+export declare function collectPathsTo(tree: CallNode, resolvedTarget: string, rawTarget: string): CallNode[];
+/**
+ * Find all call paths from `fromEntry` to `toEntry` in the indexed call graph.
+ * Expands via the same rules as `buildCallTree` (including branch forks).
+ *
+ * When several definitions share the entry name, every definition is walked
+ * (reach's contract is completeness). Order is stable across file reorderings.
+ */
+export declare function findReachPaths(fromEntry: string, toEntry: string, index: FunctionIndex, maxDepth: number): CallNode[];

package/dist/reach.js

@@ -0,0 +1,65 @@
+import { buildCallTree, buildCallTreeFromInfo, resolveAllEntries, resolveEntry, } from "./calltree.js";
+import { assignOptionalTreeFields } from "./types.js";
+function nodeMatchesTarget(nodeKey, resolvedTarget, rawTarget) {
+    if (nodeKey === resolvedTarget || nodeKey === rawTarget)
+        return true;
+    const stripped = nodeKey.replace(/\(\)$/, "");
+    if (stripped === resolvedTarget || stripped === rawTarget)
+        return true;
+    return (nodeKey.endsWith(`.${rawTarget}`) ||
+        nodeKey.endsWith(`.${resolvedTarget}`));
+}
+/** Collapse a root→target node list into a linear single-child tree. */
+export function pathToTree(nodes) {
+    if (nodes.length === 0) {
+        throw new Error("pathToTree requires at least one node");
+    }
+    const [head, ...rest] = nodes;
+    const tree = {
+        key: head.key,
+        label: head.label,
+        children: rest.length > 0 ? [pathToTree(rest)] : [],
+    };
+    return assignOptionalTreeFields(tree, head);
+}
+/**
+ * Collect every root-to-node path in `tree` that ends at `target`
+ * (first hit on a path; does not continue below the target).
+ */
+export function collectPathsTo(tree, resolvedTarget, rawTarget) {
+    const paths = [];
+    const walk = (node, ancestors) => {
+        const chain = [...ancestors, node];
+        if (nodeMatchesTarget(node.key, resolvedTarget, rawTarget)) {
+            paths.push(pathToTree(chain));
+            return;
+        }
+        for (const child of node.children) {
+            walk(child, chain);
+        }
+    };
+    walk(tree, []);
+    return paths;
+}
+/**
+ * Find all call paths from `fromEntry` to `toEntry` in the indexed call graph.
+ * Expands via the same rules as `buildCallTree` (including branch forks).
+ *
+ * When several definitions share the entry name, every definition is walked
+ * (reach's contract is completeness). Order is stable across file reorderings.
+ */
+export function findReachPaths(fromEntry, toEntry, index, maxDepth) {
+    const toKey = resolveEntry(toEntry, index) ?? toEntry;
+    const fromInfos = resolveAllEntries(fromEntry, index);
+    if (fromInfos.length === 0) {
+        const fromKey = resolveEntry(fromEntry, index) ?? fromEntry;
+        const tree = buildCallTree(fromKey, index, maxDepth);
+        return collectPathsTo(tree, toKey, toEntry);
+    }
+    const paths = [];
+    for (const info of fromInfos) {
+        const tree = buildCallTreeFromInfo(info, index, maxDepth);
+        paths.push(...collectPathsTo(tree, toKey, toEntry));
+    }
+    return paths;
+}

package/dist/render.d.ts

@@ -0,0 +1,18 @@
+import type { CallNode, DiffNode } from "./types.js";
+export interface RenderOptions {
+    /** When false, skip ANSI colors (useful for tests). Default: true */
+    color?: boolean;
+    /**
+     * Append `file:line` (or `file:line-line`) after each label.
+     * Default: false.
+     */
+    locs?: boolean;
+}
+/**
+ * Render a callstack diff as an ASCII tree with +/- markers.
+ */
+export declare function renderDiff(root: DiffNode, options?: RenderOptions): string;
+/**
+ * Render a single call tree as an ASCII tree (no +/- markers).
+ */
+export declare function renderTree(root: CallNode, options?: RenderOptions): string;

package/dist/render.js

@@ -0,0 +1,83 @@
+import pc from "picocolors";
+import { formatSourceLoc, pickLoc } from "./loc.js";
+function paint(status, text) {
+    switch (status) {
+        case "added":
+            return pc.blue(text);
+        case "removed":
+            return pc.magenta(text);
+        default:
+            return text;
+    }
+}
+function prefix(status) {
+    switch (status) {
+        case "added":
+            return pc.blue("+");
+        case "removed":
+            return pc.magenta("-");
+        default:
+            return " ";
+    }
+}
+function renderAsciiTree(root, options, withStatus) {
+    const useColor = options.color !== false;
+    const showLocs = options.locs === true;
+    const paintStatus = (status, text) => useColor ? paint(status, text) : text;
+    const statusPrefix = (status) => {
+        if (!useColor) {
+            switch (status) {
+                case "added":
+                    return "+";
+                case "removed":
+                    return "-";
+                default:
+                    return " ";
+            }
+        }
+        return prefix(status);
+    };
+    const locSuffix = (node) => {
+        if (!showLocs)
+            return "";
+        const loc = pickLoc(node);
+        if (!loc.file || loc.line == null)
+            return "";
+        // SAFETY: file and line were just validated as present above.
+        const text = `  ${formatSourceLoc(loc)}`;
+        return useColor ? pc.dim(text) : text;
+    };
+    const lines = [];
+    const walk = (node, indent, isLast, isRoot) => {
+        const branch = isRoot ? "" : isLast ? "└─ " : "├─ ";
+        const label = withStatus
+            ? paintStatus(node.status ?? "same", node.label)
+            : node.label;
+        const suffix = locSuffix(node);
+        const line = withStatus
+            ? `${statusPrefix(node.status ?? "same")} ${indent}${branch}${label}${suffix}`
+            : `${indent}${branch}${label}${suffix}`;
+        lines.push(line);
+        // Conditional arms omit the continuing │ rail — they are alternate paths,
+        // not a nested stack that continues past the branch.
+        const rail = node.kind === "branch" ? "   " : isLast || isRoot ? "   " : "│  ";
+        const childIndent = isRoot ? "" : `${indent}${rail}`;
+        node.children.forEach((child, index) => {
+            walk(child, childIndent, index === node.children.length - 1, false);
+        });
+    };
+    walk(root, "", true, true);
+    return lines.join("\n");
+}
+/**
+ * Render a callstack diff as an ASCII tree with +/- markers.
+ */
+export function renderDiff(root, options = {}) {
+    return renderAsciiTree(root, options, true);
+}
+/**
+ * Render a single call tree as an ASCII tree (no +/- markers).
+ */
+export function renderTree(root, options = {}) {
+    return renderAsciiTree(root, options, false);
+}

package/dist/review/brand.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The diffninja mark: a ninja's head in its hood, eyes showing through the
+ * slit, a red bandana tied at the back with its tails flying. Inline SVG, so
+ * both pages carry it under their no-external-resources policies.
+ */
+export declare const BRAND_MARK: string;
+/** Colors for {@link BRAND_MARK}; the hood stays dark, outlined so it reads on a dark page too. */
+export declare const BRAND_MARK_STYLES = "\n.brand-mark { width: 26px; height: 26px; flex: 0 0 auto; }\n.brand-mark .nj-hood { fill: #1f2328; stroke: var(--line-strong); stroke-width: 2; }\n.brand-mark .nj-band, .brand-mark .nj-tail { fill: #d1242f; }\n.brand-mark .nj-skin { fill: #f2c9a0; }\n.brand-mark .nj-eye { fill: #1f2328; }\n";

package/dist/review/brand.js

@@ -0,0 +1,25 @@
+/**
+ * The diffninja mark: a ninja's head in its hood, eyes showing through the
+ * slit, a red bandana tied at the back with its tails flying. Inline SVG, so
+ * both pages carry it under their no-external-resources policies.
+ */
+export const BRAND_MARK = [
+    '<svg class="brand-mark" viewBox="0 0 64 64" width="26" height="26" aria-hidden="true" focusable="false">',
+    '<path class="nj-tail" d="M49 19c5-1 9-4 13-9-1 6-4 10-9 13z"/>',
+    '<path class="nj-tail" d="M50 24c5 1 8 4 10 10-4-3-7-4-12-5z"/>',
+    '<circle class="nj-hood" cx="28" cy="34" r="24"/>',
+    '<path class="nj-band" d="M5 25c15-5 30-5 46 0l-1 7c-14-5-29-5-44 0z"/>',
+    '<circle class="nj-band" cx="50" cy="24" r="4"/>',
+    '<rect class="nj-skin" x="10" y="34" width="36" height="11" rx="5"/>',
+    '<ellipse class="nj-eye" cx="21" cy="39" rx="3" ry="3"/>',
+    '<ellipse class="nj-eye" cx="35" cy="39" rx="3" ry="3"/>',
+    "</svg>",
+].join("");
+/** Colors for {@link BRAND_MARK}; the hood stays dark, outlined so it reads on a dark page too. */
+export const BRAND_MARK_STYLES = `
+.brand-mark { width: 26px; height: 26px; flex: 0 0 auto; }
+.brand-mark .nj-hood { fill: #1f2328; stroke: var(--line-strong); stroke-width: 2; }
+.brand-mark .nj-band, .brand-mark .nj-tail { fill: #d1242f; }
+.brand-mark .nj-skin { fill: #f2c9a0; }
+.brand-mark .nj-eye { fill: #1f2328; }
+`;

package/dist/review/call-context.d.ts

@@ -0,0 +1,27 @@
+import { type FunctionIndex } from "../extract.js";
+import type { SourceLoc } from "../types.js";
+import type { ReviewContextNode, ReviewUnit } from "./types.js";
+/**
+ * Whole definition text for one snapshot, or `null` when the snapshot cannot
+ * confirm a definition at that span. Supplied by the caller because reading a
+ * snapshot belongs to the service, not to a pure selection function.
+ */
+export type ContextSourceReader = (definition: SourceLoc) => string | null;
+/** Per-snapshot readers for the node source text; absent means none is read. */
+export interface ContextSources {
+    readonly before?: ContextSourceReader;
+    readonly after?: ContextSourceReader;
+}
+/** Report blocks and addressable nodes for one hunk. */
+export interface UnitContext {
+    /** Report text in report order: both snapshots, the hunk-adjacent call first. */
+    entries: string[];
+    /** Structured context, highest retention priority first. */
+    nodes: ReviewContextNode[];
+}
+/**
+ * Per-hunk context: the standalone report blocks, adjacent to the hunk first
+ * with snapshot-local bindings, and the structured nodes those blocks were
+ * derived from. A hunk with neither gets no entry rather than an empty one.
+ */
+export declare function buildCallContext(units: readonly ReviewUnit[], before: FunctionIndex, after: FunctionIndex, sources?: ContextSources): Map<string, UnitContext>;