diffninja 0.1.0

package/dist/review/types.d.ts

@@ -0,0 +1,179 @@
+import type { PullRequestIntent, ReviewEvidence } from "./evidence-types.js";
+import type { ChangeFacts } from "./change-facts.js";
+import type { ReviewQuestion } from "./questions.js";
+import type { HunkHistory, ProjectContext } from "./history.js";
+export type ReviewStatus = "attention" | "uncertain" | "low" | "passed";
+/**
+ * Structural status for a call-flow node. The engine only knows `same`,
+ * `added`, and `removed`; the report derives `changed` for a `same` node whose
+ * descendants changed, which is what makes a same-signature caller visible.
+ */
+export type CallFlowStatus = "same" | "added" | "removed" | "changed";
+/**
+ * Actual resolved definition of a node, read from the snapshot it lived in.
+ * `text` is the definition's own source, never the call site's.
+ */
+export interface CallFlowSource {
+    file: string;
+    line: number;
+    endLine: number;
+    /**
+     * Opaque, printable provenance for the snapshot the text came from: the short
+     * commit of the `to` side, or of the `from` side for a removed node.
+     */
+    ref: string;
+    /**
+     * Definition source lines `line`..`endLine`, verbatim and complete. Nothing
+     * is trimmed: the report has to be readable without the repository, so a
+     * function is carried whole or not at all.
+     */
+    text: string;
+}
+/** One call in a report call-flow tree: root = definition, children = call sites. */
+export interface CallFlowNode {
+    key: string;
+    label: string;
+    status: CallFlowStatus;
+    /** File containing the call site (the root's own definition file at depth 0). */
+    file?: string;
+    line?: number;
+    /** End line of a call site spanning several lines. */
+    endLine?: number;
+    /**
+     * Verbatim first prose line of the definition's attached leading comment, or
+     * of its Python docstring. Absent when the definition has neither, or when its
+     * source could not be read. Never generated.
+     */
+    description?: string;
+    /** Absent when the call has no indexed definition, or its source is unreadable. */
+    source?: CallFlowSource;
+    children: CallFlowNode[];
+}
+/** Bounded call-flow trees that touch one changed file. */
+export interface CallFlowFile {
+    file: string;
+    /** Root definitions whose call paths reach this file, in engine order. */
+    trees: CallFlowNode[];
+    /** True when serialization dropped roots, children, depth, or nodes to fit the bounds. */
+    truncated: boolean;
+}
+/**
+ * Why structured call flows are present or absent. `available` means at least
+ * one changed file has trees; `no-changes` means there was nothing structural to
+ * attach (no changed file with text hunks, or no tree reaching one) and is not a
+ * safety claim; `needs-git-range` means the input was a patch; `failed` means
+ * the analysis threw.
+ */
+export type CallFlowAvailability = "available" | "needs-git-range" | "no-changes" | "failed";
+/**
+ * One keyed piece of structured review context for a hunk: a changed, caller, or
+ * callee definition with its snapshot-bound source and the call/binding evidence
+ * extracted for it. Nodes are selected deterministically and feed the evidence
+ * agenda and the reviewer's context.
+ */
+export interface ReviewContextNode {
+    /** Addressable identity inside one hunk, unique across snapshots, e.g. `after:checkout`. */
+    key: string;
+    /** Extractor label of the definition, e.g. `checkout(order, user)`. */
+    label: string;
+    file: string;
+    /** 1-based definition line, the location half of the node's identity. */
+    line: number;
+    /**
+     * Whole node text: the definition source as the snapshot has it, plus the
+     * selected call sites and bindings already extracted for it. Never a preview
+     * and never truncated.
+     */
+    detail: string;
+}
+/** One parsed piece of the input: a text hunk, or a file's metadata-only change. */
+export interface ReviewUnit {
+    id: string;
+    file: string;
+    header: string;
+    diff: string;
+    added: number;
+    removed: number;
+    oldStart: number;
+    newStart: number;
+    /**
+     * Why this unit cannot be judged from the diff alone (binary, rename, mode,
+     * symbolic link, submodule). A unit that carries one goes to manual review.
+     */
+    special?: string;
+    /**
+     * Report blocks for this hunk, in the order the report shows them: both
+     * snapshots, the call on a changed line first. They stay the readable report
+     * text; {@link ReviewUnit.contextNodes} carries the structured form.
+     */
+    callFlow?: string[];
+    /**
+     * Structured context for this hunk, highest retention priority first.
+     * An empty array is never set in place of "no context".
+     */
+    contextNodes?: ReviewContextNode[];
+    /** Commits that last changed the lines this hunk removes; git-range reviews only. */
+    history?: HunkHistory;
+}
+export interface ReviewItem extends ReviewUnit {
+    status: ReviewStatus;
+    priority: number;
+    /** Fixed templates over the local facts; a cited line is quoted from the diff itself. */
+    reasons: string[];
+    /** Local change facts; absent for manual units and fact-free passes. */
+    facts?: ChangeFacts;
+}
+export interface AgentOrder {
+    /** Every item id of the report exactly once, most important first; the report's items follow it. */
+    itemIds: string[];
+    orderedBy: string;
+    orderedAt: string;
+    /** diffninja's own order of the same items, kept so the page can still offer it. */
+    diffninjaIds: string[];
+}
+/** One line comment the reviewing agent suggests; the human adds it to their review or not. */
+export interface SuggestedComment {
+    path: string;
+    line: number;
+    side: "LEFT" | "RIGHT";
+    body: string;
+}
+export interface AgentComments {
+    comments: SuggestedComment[];
+    suggestedBy: string;
+    suggestedAt: string;
+}
+export interface ReviewReport {
+    title: string;
+    source: string;
+    createdAt: string;
+    pr?: PullRequestIntent;
+    evidence?: ReviewEvidence;
+    items: ReviewItem[];
+    callFlow: string[];
+    /**
+     * One entry per changed file with actual text hunks that a call-flow tree
+     * reaches, in report rank order. Metadata-only files and files no tree
+     * reaches are omitted rather than reported as empty trees.
+     */
+    callFlows: CallFlowFile[];
+    callFlowAvailability: CallFlowAvailability;
+    warnings: string[];
+    /** Questions for the reviewing agent's model, bound to hunks; answers never reorder the report. */
+    questions: ReviewQuestion[];
+    /** The reading order the reviewing agent recorded; once present, `items` follow it. */
+    agentOrder?: AgentOrder;
+    /** Line comments the reviewing agent suggested; nothing is posted until the human submits them. */
+    agentComments?: AgentComments;
+    /**
+     * Local repository context for a git-range review: prior reverts, contributor
+     * guidelines, and sibling-file conventions. Absent for a patch.
+     */
+    project?: ProjectContext;
+}
+export interface ReviewOptions {
+    /** Exact PR metadata, treated as untrusted evidence rather than instructions. */
+    pr?: PullRequestIntent;
+    /** Opt in to the locally installed project TypeScript checker; never a PR script. */
+    referenceProject?: string;
+}

package/dist/review/types.js

@@ -0,0 +1 @@
+export {};

package/dist/run.d.ts

@@ -0,0 +1,49 @@
+import type { FunctionIndex } from "./extract.js";
+import type { DiffResult, ReachResult, TreeResult } from "./types.js";
+export type DiffRunOptions = {
+    from?: string;
+    to?: string;
+    /** Symbol entrypoints (`-e`). */
+    entries?: string[];
+    /** File entrypoints (`--file`): expand to that file's exports. */
+    files?: string[];
+    paths?: string[];
+    cwd?: string;
+    maxDepth?: number;
+    /** When false, skip ANSI colors in ascii output. Default: true */
+    color?: boolean;
+    /** When true, append file:line suffixes in ascii. Default: false */
+    locs?: boolean;
+    /** Reuse parsed snapshots for contextual analysis, even without structural changes. */
+    onIndexes?: (before: FunctionIndex, after: FunctionIndex) => void;
+};
+export type TreeRunOptions = {
+    ref?: string;
+    entries?: string[];
+    files?: string[];
+    paths?: string[];
+    cwd?: string;
+    maxDepth?: number;
+    color?: boolean;
+    locs?: boolean;
+};
+export type ReachRunOptions = {
+    ref?: string;
+    /** Start symbol(s). */
+    entries?: string[];
+    /** Start file(s): every export in the file. */
+    files?: string[];
+    /** Target symbol to reach. */
+    to: string;
+    paths?: string[];
+    cwd?: string;
+    maxDepth?: number;
+    color?: boolean;
+    locs?: boolean;
+};
+/** Diff call stacks between two snapshots. Returns structured data + ASCII. */
+export declare function runDiff(options?: DiffRunOptions): DiffResult;
+/** View call tree(s) for entrypoint(s) from a single snapshot. */
+export declare function runTree(options: TreeRunOptions): TreeResult;
+/** Find all call paths from entrypoint(s) to a target symbol. */
+export declare function runReach(options: ReachRunOptions): ReachResult;

package/dist/run.js

@@ -0,0 +1,311 @@
+import { buildCallTreeFromInfo, exportsInFile, resolveEntry, resolveEntrypointFile, indexedFiles, } from "./calltree.js";
+import { buildIndex, extractCached } from "./extract.js";
+import { assertGitRepo, describeSnapshot, listSnapshotFiles, resolveDiffSnapshotsAndPaths, resolveSnapshotAndPaths, verifyCommit, visitCommitBlobs, visitWorktreeFiles, } from "./git.js";
+import { diffEntry, diffPinnedEntry, inferEntries, resolveExplicitDiffEntries, } from "./infer.js";
+import { collectPathsTo, findReachPaths } from "./reach.js";
+import { renderDiff, renderTree } from "./render.js";
+import { assignOptionalTreeFields } from "./types.js";
+function loadIndex(cwd, snapshot, pathFilters, cache = new Map()) {
+    const files = listSnapshotFiles(cwd, snapshot, pathFilters);
+    const extracted = new Map();
+    const extract = (file, source) => {
+        try {
+            extracted.set(file.path, extractCached(file.path, source, cache));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`warn: failed to parse ${file.path} @ ${snapshot.ref}: ${message}`);
+        }
+    };
+    if (snapshot.kind === "worktree") {
+        visitWorktreeFiles(cwd, files, extract);
+    }
+    else {
+        const filesByOid = new Map();
+        for (const file of files) {
+            if (!file.oid)
+                continue;
+            const matches = filesByOid.get(file.oid) ?? [];
+            matches.push(file);
+            filesByOid.set(file.oid, matches);
+        }
+        visitCommitBlobs(cwd, files, (oid, source) => {
+            for (const file of filesByOid.get(oid) ?? [])
+                extract(file, source);
+        });
+    }
+    const functions = [];
+    for (const file of files) {
+        functions.push(...(extracted.get(file.path) ?? []));
+    }
+    return buildIndex(functions);
+}
+/** Resolve `-e` symbols to concrete definitions. */
+function resolveSymbolInfos(index, symbols) {
+    const resolved = [];
+    const seen = new Set();
+    for (const entry of symbols) {
+        const key = resolveEntry(entry, index);
+        if (!key) {
+            throw new Error(`Entrypoint not found: ${entry}`);
+        }
+        const info = index.get(key);
+        if (!info) {
+            throw new Error(`Entrypoint not found: ${entry}`);
+        }
+        const id = `${info.file}\0${info.key}\0${info.line ?? ""}`;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        resolved.push(info);
+    }
+    return resolved;
+}
+/** Resolve `--file` paths to exported definitions (file-pinned). */
+function resolveFileInfos(index, files) {
+    const resolved = [];
+    const seen = new Set();
+    for (const entry of files) {
+        const file = resolveEntrypointFile(entry, indexedFiles(index));
+        const infos = exportsInFile(file, index);
+        if (infos.length === 0) {
+            throw new Error(`No exported entrypoints in ${file}`);
+        }
+        for (const info of infos) {
+            const id = `${info.file}\0${info.key}\0${info.line ?? ""}`;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            resolved.push(info);
+        }
+    }
+    return resolved;
+}
+function resolveEntrypointInfos(index, symbols, files) {
+    return [
+        ...resolveSymbolInfos(index, symbols),
+        ...resolveFileInfos(index, files),
+    ];
+}
+function serializeCallNode(node) {
+    const serialized = {
+        key: node.key,
+        label: node.label,
+        children: node.children.map(serializeCallNode),
+    };
+    return assignOptionalTreeFields(serialized, node);
+}
+function serializeDiffNode(node) {
+    const serialized = {
+        key: node.key,
+        label: node.label,
+        status: node.status,
+        children: node.children.map(serializeDiffNode),
+    };
+    return assignOptionalTreeFields(serialized, node);
+}
+/** Diff call stacks between two snapshots. Returns structured data + ASCII. */
+export function runDiff(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const maxDepth = options.maxDepth ?? 12;
+    const entriesOpt = options.entries ?? [];
+    const filesOpt = options.files ?? [];
+    const color = options.color !== false;
+    const locs = options.locs === true;
+    const hasExplicit = entriesOpt.length > 0 || filesOpt.length > 0;
+    assertGitRepo(cwd);
+    const { from, to, paths: resolvedPaths, } = resolveDiffSnapshotsAndPaths(cwd, options.from, options.to, options.paths ?? []);
+    if (from.kind === "commit")
+        verifyCommit(cwd, from.ref);
+    if (to.kind === "commit")
+        verifyCommit(cwd, to.ref);
+    const extractionCache = new Map();
+    const before = loadIndex(cwd, from, resolvedPaths, extractionCache);
+    const after = loadIndex(cwd, to, resolvedPaths, extractionCache);
+    extractionCache.clear();
+    options.onIndexes?.(before, after);
+    const fromLabel = describeSnapshot(from);
+    const toLabel = describeSnapshot(to);
+    const trees = [];
+    const asciiParts = [
+        `calldiff diff ${fromLabel} → ${toLabel}`,
+        "",
+    ];
+    const pushDiff = (entry, diff) => {
+        const ascii = renderDiff(diff, { color, locs });
+        trees.push({
+            entry,
+            ascii: renderDiff(diff, { color: false, locs }),
+            tree: serializeDiffNode(diff),
+        });
+        if (asciiParts.length > 2)
+            asciiParts.push("");
+        asciiParts.push(ascii);
+    };
+    if (hasExplicit) {
+        const explicit = resolveExplicitDiffEntries(before, after, entriesOpt, filesOpt);
+        for (const item of explicit) {
+            const diff = item.file
+                ? diffPinnedEntry(item.key, item.beforeInfo, item.afterInfo, before, after, maxDepth)
+                : diffEntry(item.key, before, after, maxDepth);
+            if (!diff)
+                continue;
+            pushDiff(item.key, diff);
+        }
+    }
+    else {
+        const entries = inferEntries(before, after, [], maxDepth);
+        if (entries.length === 0) {
+            const message = `No callstack changes between ${fromLabel} and ${toLabel}.`;
+            return {
+                mode: "diff",
+                from: fromLabel,
+                to: toLabel,
+                message,
+                trees: [],
+                ascii: message,
+            };
+        }
+        for (const entry of entries) {
+            const diff = diffEntry(entry, before, after, maxDepth);
+            if (!diff)
+                continue;
+            pushDiff(entry, diff);
+        }
+    }
+    if (trees.length === 0) {
+        const message = hasExplicit
+            ? "No callstack changes for requested entrypoints."
+            : "No callstack changes for inferred entrypoints.";
+        return {
+            mode: "diff",
+            from: fromLabel,
+            to: toLabel,
+            message,
+            trees: [],
+            ascii: `${asciiParts[0]}\n\n${message}`,
+        };
+    }
+    return {
+        mode: "diff",
+        from: fromLabel,
+        to: toLabel,
+        trees,
+        ascii: asciiParts.join("\n"),
+    };
+}
+/** View call tree(s) for entrypoint(s) from a single snapshot. */
+export function runTree(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const maxDepth = options.maxDepth ?? 12;
+    const color = options.color !== false;
+    const locs = options.locs === true;
+    const symbols = options.entries ?? [];
+    const files = options.files ?? [];
+    assertGitRepo(cwd);
+    const { snapshot, paths } = resolveSnapshotAndPaths(cwd, options.ref, options.paths ?? []);
+    if (snapshot.kind === "commit")
+        verifyCommit(cwd, snapshot.ref);
+    const index = loadIndex(cwd, snapshot, paths);
+    const infos = resolveEntrypointInfos(index, symbols, files);
+    const refLabel = describeSnapshot(snapshot);
+    const trees = [];
+    const asciiParts = [`calldiff tree ${refLabel}`, ""];
+    for (const info of infos) {
+        const tree = buildCallTreeFromInfo(info, index, maxDepth);
+        const ascii = renderTree(tree, { color, locs });
+        trees.push({
+            entry: info.key,
+            ascii: renderTree(tree, { color: false, locs }),
+            tree: serializeCallNode(tree),
+        });
+        if (asciiParts.length > 2)
+            asciiParts.push("");
+        asciiParts.push(ascii);
+    }
+    return {
+        mode: "tree",
+        ref: refLabel,
+        trees,
+        ascii: asciiParts.join("\n"),
+    };
+}
+/** Find all call paths from entrypoint(s) to a target symbol. */
+export function runReach(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const maxDepth = options.maxDepth ?? 12;
+    const color = options.color !== false;
+    const locs = options.locs === true;
+    const symbols = options.entries ?? [];
+    const files = options.files ?? [];
+    assertGitRepo(cwd);
+    const { snapshot, paths } = resolveSnapshotAndPaths(cwd, options.ref, options.paths ?? []);
+    if (snapshot.kind === "commit")
+        verifyCommit(cwd, snapshot.ref);
+    const index = loadIndex(cwd, snapshot, paths);
+    const targetKey = resolveEntry(options.to, index);
+    if (!targetKey) {
+        throw new Error(`Target not found: ${options.to}`);
+    }
+    const refLabel = describeSnapshot(snapshot);
+    const pathResults = [];
+    const entryKeys = [];
+    for (const entry of symbols) {
+        const key = resolveEntry(entry, index);
+        if (!key) {
+            throw new Error(`Entrypoint not found: ${entry}`);
+        }
+        if (!entryKeys.includes(key))
+            entryKeys.push(key);
+        const found = findReachPaths(entry, targetKey, index, maxDepth);
+        for (const path of found) {
+            pathResults.push({
+                ascii: renderTree(path, { color: false, locs }),
+                tree: serializeCallNode(path),
+            });
+        }
+    }
+    for (const info of resolveFileInfos(index, files)) {
+        if (!entryKeys.includes(info.key))
+            entryKeys.push(info.key);
+        const tree = buildCallTreeFromInfo(info, index, maxDepth);
+        for (const path of collectPathsTo(tree, targetKey, options.to)) {
+            pathResults.push({
+                ascii: renderTree(path, { color: false, locs }),
+                tree: serializeCallNode(path),
+            });
+        }
+    }
+    const fromLabel = entryKeys.length === 1 ? entryKeys[0] : entryKeys.join(", ");
+    const header = `calldiff reach ${refLabel}: ${fromLabel} → ${targetKey}`;
+    if (pathResults.length === 0) {
+        const message = `No paths from ${fromLabel} to ${targetKey}.`;
+        return {
+            mode: "reach",
+            ref: refLabel,
+            from: fromLabel,
+            to: targetKey,
+            message,
+            paths: [],
+            ascii: `${header}\n\n${message}`,
+        };
+    }
+    const asciiParts = [header, ""];
+    for (let i = 0; i < pathResults.length; i++) {
+        const path = pathResults[i];
+        if (i > 0)
+            asciiParts.push("");
+        if (pathResults.length > 1) {
+            asciiParts.push(`# path ${i + 1}`);
+        }
+        asciiParts.push(renderTree(path.tree, { color, locs }));
+    }
+    return {
+        mode: "reach",
+        ref: refLabel,
+        from: fromLabel,
+        to: targetKey,
+        paths: pathResults,
+        ascii: asciiParts.join("\n"),
+    };
+}