diffninja 0.1.0

package/dist/review/evidence-syntax.js

@@ -0,0 +1,478 @@
+/**
+ * Tree-sitter views of one definition's own source, used by the automatic
+ * evidence checks.
+ *
+ * The checks read definitions from snapshot indexes rather than whole files, so
+ * every parse starts from a single definition's text. A member definition is
+ * not a valid module on its own, so a container and a binding wrapper are
+ * retried before a fragment is reported unsupported: a fragment no attempt
+ * parses contributes no body, no return type, and no shape, and the caller says
+ * which definitions were left out instead of guessing.
+ *
+ * Every helper here is syntax-only. Nothing resolves a name to a value: a
+ * return type, a declared field, or a parameter binding is what the grammar
+ * wrote, and call/argument answers stay with the extractor indexes the checks
+ * already read.
+ */
+import Parser from "tree-sitter";
+import { loadGrammarPackage, resolveLanguage, } from "../languages/grammars.js";
+import { detectLanguage } from "../languages/registry.js";
+import { collapseWs } from "../languages/types.js";
+const parser = new Parser();
+/** One grammar handle, or a confirmed failure that must not be retried. */
+const grammars = new Map();
+function languageFor(file) {
+    const extractor = detectLanguage(file);
+    if (!extractor)
+        return null;
+    const key = extractor.grammarExport
+        ? `${extractor.grammarPackage}:${extractor.grammarExport}`
+        : extractor.grammarPackage;
+    const cached = grammars.get(key);
+    if (cached !== undefined)
+        return cached;
+    let language = null;
+    try {
+        language = resolveLanguage(loadGrammarPackage(extractor.grammarPackage), extractor.grammarExport);
+    }
+    catch {
+        // A grammar that cannot be installed or loaded leaves its definitions
+        // unchecked; the checks report them as unsupported rather than failing.
+        language = null;
+    }
+    grammars.set(key, language);
+    return language;
+}
+/**
+ * Literal text that only parses inside a container, so a class member or a
+ * bare function value can be parsed at all. The wrapper names cannot collide
+ * with an extracted definition: no definition span contains them.
+ */
+const CONTAINER_WRAPPER = (source) => `class __diffninjaEvidenceContainer {\n${source}\n}`;
+const BINDING_WRAPPER = (source) => `const __diffninjaEvidenceBinding = ${source};`;
+/**
+ * Parse one definition fragment, trying the text as written first and then the
+ * two wrappers above. The first attempt whose whole tree is error-free wins, so
+ * the same fragment always yields the same tree.
+ */
+export function parseFragment(file, text) {
+    const language = languageFor(file);
+    if (language === null)
+        return null;
+    const source = text.trim();
+    if (source === "")
+        return null;
+    const attempts = [
+        { source, lineOffset: 0 },
+        { source: CONTAINER_WRAPPER(source), lineOffset: 1 },
+        { source: BINDING_WRAPPER(source), lineOffset: 0 },
+    ];
+    for (const attempt of attempts) {
+        let tree = null;
+        try {
+            // @ts-expect-error tree-sitter Language under-specifies grammar module exports
+            parser.setLanguage(language);
+            tree = parser.parse(attempt.source);
+        }
+        catch {
+            // A grammar that rejects this fragment leaves nothing to read here.
+            tree = null;
+        }
+        if (tree === null || tree.rootNode.hasError)
+            continue;
+        return { tree, lineOffset: attempt.lineOffset };
+    }
+    return null;
+}
+/** Imports in a module prefix; an unfinished following class does not invalidate preceding imports. */
+export function moduleImports(file, prefix) {
+    const language = languageFor(file);
+    if (language === null)
+        return null;
+    let tree;
+    try {
+        // @ts-expect-error tree-sitter Language under-specifies grammar module exports
+        parser.setLanguage(language);
+        tree = parser.parse(prefix);
+    }
+    catch {
+        return null;
+    }
+    const imports = new Map();
+    for (const node of tree.rootNode.namedChildren) {
+        if (node.type !== "import_statement" || node.hasError)
+            continue;
+        const clause = node.namedChildren.find(child => child.type === "import_clause");
+        const literal = node.childForFieldName("source");
+        const module = literal?.namedChildren.find(child => child.type === "string_fragment")?.text;
+        if (!clause || module === undefined)
+            continue;
+        for (const child of clause.namedChildren) {
+            if (child.type === "identifier")
+                imports.set(child.text, module);
+            if (child.type === "namespace_import") {
+                const local = child.namedChildren.find(entry => entry.type === "identifier");
+                if (local)
+                    imports.set(local.text, module);
+            }
+            if (child.type !== "named_imports")
+                continue;
+            for (const specifier of child.namedChildren) {
+                if (specifier.type !== "import_specifier")
+                    continue;
+                const local = specifier.childForFieldName("alias") ?? specifier.childForFieldName("name");
+                if (local)
+                    imports.set(local.text, module);
+            }
+        }
+    }
+    return imports;
+}
+/* ------------------------------------------------------------------ bodies */
+/**
+ * Bodies that belong to a container rather than to a definition. `block` is
+ * deliberately absent: it is a function body in grammars that have no
+ * `statement_block`, and a nested control-flow block is always smaller.
+ */
+const CONTAINER_BODIES = {
+    class_body: true,
+    interface_body: true,
+    enum_body: true,
+    declaration_list: true,
+    field_declaration_list: true,
+    struct_body: true,
+    trait_body: true,
+    impl_body: true,
+    namespace_body: true,
+    module_body: true,
+    object_type: true,
+    program: true,
+    translation_unit: true,
+    source_file: true,
+    compilation_unit: true,
+    script: true,
+};
+/**
+ * The definition's own body. The fragment holds either the definition itself or
+ * one wrapper (a class the member was written in, or a binding the function
+ * value was assigned to), so the outermost node with a callable body is the
+ * definition being read. Breadth-first order picks the shallowest one, which
+ * keeps a large nested callback inside a default parameter from being taken for
+ * the definition's body, and ties are broken by position, so the choice is
+ * stable.
+ */
+export function definitionSyntax(fragment) {
+    let level = [fragment.tree.rootNode];
+    while (level.length > 0) {
+        const next = [];
+        for (const node of level) {
+            const body = node.childForFieldName("body");
+            if (body && !Object.hasOwn(CONTAINER_BODIES, body.type))
+                return { definition: node, body };
+            next.push(...node.children);
+        }
+        level = next;
+    }
+    return null;
+}
+/**
+ * Comment-free token stream of a body: leaf text in source order, one space
+ * between tokens. Formatting and comments are gone; every literal and operator
+ * is kept exactly as written, so two bodies match only when their tokens do.
+ */
+export function bodyTokenSignature(body) {
+    const tokens = [];
+    const walk = (node) => {
+        if (node.childCount === 0) {
+            const type = node.type;
+            if (type !== "comment" && !type.endsWith("_comment"))
+                tokens.push(node.text);
+            return;
+        }
+        for (const child of node.children)
+            walk(child);
+    };
+    walk(body);
+    return tokens.join(" ");
+}
+/* ------------------------------------------------------------- annotations */
+/** Declared response type name of a definition's return annotation, if any. */
+export function returnedResponseType(definition) {
+    return declaredResponseType(definition.childForFieldName("return_type"), true);
+}
+/** Declared fields written in one object literal type; empty when there are none. */
+function objectFields(objectNode) {
+    const fields = [];
+    for (const member of objectNode.namedChildren) {
+        if (member.type !== "property_signature")
+            continue;
+        const name = member.childForFieldName("name");
+        const annotation = member.childForFieldName("type");
+        if (!name || !annotation)
+            continue;
+        // A property signature's `type` field is the annotation node, which still
+        // carries its colon; the declared type is the node inside it.
+        const type = annotation.type === "type_annotation"
+            ? annotation.namedChildren[0] ?? annotation
+            : annotation;
+        fields.push({ name: name.text, type: collapseWs(type.text) });
+    }
+    return fields;
+}
+/** Wrapper type names whose single type argument is the declared response. */
+const RESPONSE_WRAPPERS = { Promise: true, Awaited: true, Readonly: true };
+/**
+ * The declared response type name of a type annotation, or null when the
+ * annotation declares something else. Only a plain name (`CreateResult`) or a
+ * known async/readonly wrapper of one (`Promise<CreateResult>`) is a response:
+ * an array of them (`CreateResult[]`), an arbitrary generic
+ * (`Wrapper<CreateResult>`), a union, or a function type is a different thing,
+ * and this check must not treat it as holding one response.
+ */
+export function declaredResponseType(annotation, awaited = false) {
+    if (!annotation)
+        return null;
+    const inner = annotation.type === "type_annotation" ? annotation.namedChildren[0] : annotation;
+    if (!inner)
+        return null;
+    if (inner.type === "type_identifier" || inner.type === "identifier")
+        return inner.text;
+    // `Promise<CreateResult>` is the response only where the code awaits it: an
+    // async definition's declared return, and a call whose result is awaited.
+    // A parameter or local declared as a Promise holds the pending value itself.
+    if (inner.type === "generic_type") {
+        if (!awaited)
+            return null;
+        const name = inner.childForFieldName("name");
+        const args = inner.childForFieldName("type_arguments");
+        if (!name || !args || !Object.hasOwn(RESPONSE_WRAPPERS, name.text))
+            return null;
+        const parameters = args.namedChildren;
+        if (parameters.length !== 1)
+            return null;
+        return declaredResponseType(parameters[0], true);
+    }
+    if (inner.type === "type_annotation")
+        return declaredResponseType(inner.namedChildren[0], awaited);
+    return null;
+}
+/** Name a declaration node declares, or null when it names none. */
+function declarationName(node) {
+    return (node.childForFieldName("name")?.text ??
+        node.namedChildren.find(child => child.type === "type_identifier")?.text ??
+        null);
+}
+/**
+ * Declared fields of the named interface or type alias in a fragment, or null
+ * when that declaration is not the one the fragment holds. The name is required
+ * because one line can carry several declarations: a fragment read for `B` that
+ * holds both `A` and `B` must never report `A`'s fields as `B`'s. `extends` and
+ * intersections are not followed, so this is only ever the fields written in the
+ * declaration itself; an empty array means it writes no field, which is a
+ * different answer from a declaration nobody could read.
+ */
+export function contractFields(fragment, name) {
+    const declarations = [];
+    walkSyntax(fragment.tree.rootNode, node => {
+        if (node.type === "interface_declaration" || node.type === "type_alias_declaration") {
+            declarations.push(node);
+        }
+    });
+    const matches = declarations.filter(declaration => declarationName(declaration) === name);
+    if (matches.length !== 1)
+        return null;
+    const declaration = matches[0];
+    if (declaration.type === "interface_declaration") {
+        const body = declaration.childForFieldName("body");
+        return body ? objectFields(body) : null;
+    }
+    const value = declaration.childForFieldName("value");
+    return value && value.type === "object_type" ? objectFields(value) : null;
+}
+/** Nodes that declare a named value with an explicit type annotation. */
+const TYPED_BINDING_NODES = {
+    required_parameter: true,
+    optional_parameter: true,
+    parameter: true,
+    typed_parameter: true,
+    variable_declarator: true,
+    public_field_definition: true,
+    property_declaration: true,
+};
+/**
+ * Names declared with a type annotation that names `typeName`: a parameter, a
+ * local, or a class field. Only a plainly named binding is returned; a
+ * destructuring pattern is left out, because its fields are read positions
+ * rather than one value the checks can follow.
+ */
+export function typedBindings(definition, typeName) {
+    const bindings = [];
+    const walk = (node) => {
+        if (Object.hasOwn(TYPED_BINDING_NODES, node.type)) {
+            const annotation = node.childForFieldName("type");
+            if (declaredResponseType(annotation) === typeName) {
+                const pattern = node.childForFieldName("pattern") ??
+                    node.childForFieldName("name") ??
+                    node.childForFieldName("left");
+                if (pattern?.type === "identifier") {
+                    bindings.push({ name: pattern.text, row: pattern.startPosition.row });
+                }
+            }
+        }
+        for (const child of node.children)
+            walk(child);
+    };
+    walk(definition);
+    return bindings;
+}
+/** Every node in the fragment, in pre-order. */
+export function walkSyntax(root, visit) {
+    visit(root);
+    for (const child of root.children)
+        walkSyntax(child, visit);
+}
+/** Properties whose read reports how many items a value holds. */
+const COUNT_PROPERTIES = { length: true, size: true, count: true };
+export function countReadOf(node) {
+    if (node.type !== "member_expression")
+        return null;
+    const property = node.childForFieldName("property");
+    if (property?.type !== "property_identifier" || !Object.hasOwn(COUNT_PROPERTIES, property.text))
+        return null;
+    const object = node.childForFieldName("object");
+    if (!object)
+        return null;
+    if (object.type === "identifier")
+        return { read: node, value: object.text, ofField: false };
+    if (object.type !== "member_expression")
+        return null;
+    const owner = object.childForFieldName("object");
+    const field = object.childForFieldName("property");
+    if (owner?.type !== "identifier" || field?.type !== "property_identifier")
+        return null;
+    return { read: node, value: field.text, ofField: true };
+}
+/**
+ * First count-named read inside a `return`, which is the number a receiver hands
+ * back to its own caller. That is the count a partial-failure question is about,
+ * more than any diagnostic log written after it.
+ */
+export function returnedCountRead(definition) {
+    let found = null;
+    walkSyntax(definition, node => {
+        if (found || node.type !== "return_statement")
+            return;
+        walkSyntax(node, inner => {
+            if (found)
+                return;
+            const count = countReadOf(inner);
+            if (count)
+                found = count;
+        });
+    });
+    return found;
+}
+/** Whole camel-case words that name a lifecycle or state value, never a part. */
+const STATE_WORDS = { status: true, state: true, stage: true, phase: true, lifecycle: true, mode: true };
+/** Whether one identifier or property name says the value is state. */
+function namesState(text) {
+    // `model` must not match `mode`, so words are compared whole at camel
+    // boundaries: `leaseStatus` and `status` name state; `model` does not.
+    const words = text.match(/[A-Z]+(?![a-z])|[A-Z]?[a-z]+|[0-9]+/g) ?? [text];
+    return words.some(word => Object.hasOwn(STATE_WORDS, word.toLowerCase()));
+}
+/**
+ * State/status properties in a call payload. A queue routing constant or a
+ * state-looking word inside a string is not by itself a state assignment.
+ */
+export function stateWritesAt(call) {
+    const values = new Set();
+    const record = (key, value) => {
+        if (!namesState(key.text))
+            return;
+        values.add(value ? `${key.text}: ${collapseWs(value.text)}` : key.text);
+    };
+    walkSyntax(call, node => {
+        if (node.type !== "pair")
+            return;
+        record(node.childForFieldName("key") ?? node.namedChildren[0] ?? node, node.childForFieldName("value"));
+    });
+    return [...values];
+}
+/** Call expressions written in one definition, in source order. */
+export function callsIn(definition) {
+    const calls = [];
+    walkSyntax(definition, node => {
+        if (node.type === "call_expression")
+            calls.push(node);
+    });
+    return calls;
+}
+/**
+ * Count-named reads in a body, in source order: the numbers a receiver reports,
+ * which are what a partial-failure question compares with the failures it never
+ * read.
+ */
+export function countReads(definition) {
+    const reads = [];
+    walkSyntax(definition, node => {
+        const count = countReadOf(node);
+        if (count)
+            reads.push(count);
+    });
+    return reads;
+}
+/**
+ * Whether two node handles denote the same syntax node. Tree-sitter hands back
+ * a fresh wrapper per field access, so `===` on handles is not a stable test:
+ * two handles for one node can differ between calls. Node ids are stable within
+ * one tree, which is what every structural question here compares.
+ */
+export function sameNode(left, right) {
+    return left !== null && left !== undefined && right !== null && right !== undefined && left.id === right.id;
+}
+/** Node types that declare a name local to one definition's body. */
+const VALUE_DECLARATIONS = {
+    variable_declarator: true,
+    required_parameter: true,
+    optional_parameter: true,
+    parameter: true,
+    typed_parameter: true,
+    rest_pattern: true,
+    function_declaration: true,
+    class_declaration: true,
+    import_specifier: true,
+};
+/**
+ * Names one definition declares for itself: its parameters, its locals, and any
+ * nested declaration. A call written under one of these names reaches the local
+ * value, not whatever definition elsewhere carries the same bare key, so a
+ * caller-side check must not resolve through the shadow.
+ */
+export function declaredValueNames(definition) {
+    const names = new Set();
+    walkSyntax(definition, node => {
+        if (!Object.hasOwn(VALUE_DECLARATIONS, node.type))
+            return;
+        const declared = node.childForFieldName("name") ??
+            node.childForFieldName("pattern") ??
+            node.childForFieldName("left") ??
+            node.childForFieldName("declarator");
+        if (declared?.type === "identifier")
+            names.add(declared.text);
+        if (node.type === "rest_pattern") {
+            const inner = node.namedChildren.find(child => child.type === "identifier");
+            if (inner)
+                names.add(inner.text);
+        }
+    });
+    return names;
+}
+/** Value of a string literal node, or the raw text of any other node. */
+export function staticStringValue(node) {
+    if (node.type === "string") {
+        const fragment = node.namedChildren.find((c) => c.type === "string_fragment");
+        return fragment ? fragment.text : "";
+    }
+    return node.text;
+}

package/dist/review/evidence-types.d.ts

@@ -0,0 +1,62 @@
+import type { ReviewContextNode } from "./types.js";
+/** Source evidence is snapshot-bound; syntactic relationships are not runtime proof. */
+export interface EvidenceExcerpt {
+    id: string;
+    label: string;
+    file: string;
+    line: number;
+    endLine?: number;
+    ref: string;
+    text: string;
+    role: "change" | "caller" | "contract" | "related" | "test";
+}
+export interface AutomaticFinding {
+    id: string;
+    kind: "unused-error-result" | "duplicate-body" | "broken-reference";
+    title: string;
+    scope: string;
+    limitation: string;
+    unitIds: string[];
+    evidence: EvidenceExcerpt[];
+}
+export interface CheckCoverage {
+    kind: AutomaticFinding["kind"];
+    status: "checked" | "partial" | "not-checked";
+    detail: string;
+}
+export interface ReviewAgendaEntry {
+    id: string;
+    title: string;
+    reason: string;
+    priority: number;
+    unitIds: string[];
+    findingIds: string[];
+    evidence: EvidenceExcerpt[];
+    context: ReviewContextNode[];
+}
+export interface PullRequestIntent {
+    title: string;
+    body: string;
+    url?: string;
+    baseRef?: string;
+    headRef?: string;
+}
+export interface IntentClaim {
+    text: string;
+    origin: "title" | "author" | "generated-summary";
+    status: "evidence-linked" | "not-established";
+    unitIds: string[];
+    explanation: string;
+}
+export interface IntentCrossCheck {
+    verdict: "not-established" | "contradicted" | "supported-within-checked-scope";
+    summary: string;
+    claims: IntentClaim[];
+    obligations: string[];
+}
+export interface ReviewEvidence {
+    findings: AutomaticFinding[];
+    checks: CheckCoverage[];
+    agenda: ReviewAgendaEntry[];
+    intent: IntentCrossCheck;
+}

package/dist/review/evidence-types.js

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

package/dist/review/evidence.d.ts

@@ -0,0 +1,31 @@
+import { type FunctionIndex } from "../extract.js";
+import type { ContextSources } from "./call-context.js";
+import type { AutomaticFinding, CheckCoverage, ReviewAgendaEntry } from "./evidence-types.js";
+import type { ReviewUnit } from "./types.js";
+export interface ReviewEvidenceOptions {
+    /** Prior-snapshot index; absent for patch-only input. */
+    before?: FunctionIndex;
+    /** Resulting-snapshot index; absent for patch-only input. */
+    after?: FunctionIndex;
+    /** Per-snapshot definition source readers; absent when nothing can be read. */
+    sources?: ContextSources;
+    /** Provenance label for prior-snapshot evidence, e.g. the base commit. */
+    baseRef?: string;
+    /** Provenance label for resulting-snapshot evidence, e.g. the head commit. */
+    headRef?: string;
+    /** Local module binding resolver over the resulting immutable snapshot. */
+    resolveImport?: (importer: string, specifier: string) => string | undefined;
+}
+export interface ReviewEvidenceResult {
+    findings: AutomaticFinding[];
+    checks: CheckCoverage[];
+    agenda: ReviewAgendaEntry[];
+}
+/**
+ * Automatic findings, check coverage, and the review agenda for one diff. Main
+ * calls this inside the index callback with the same snapshots it renders, so
+ * every excerpt names the revision it came from; a call without indexes or
+ * without source readers still returns an agenda over the hunks, with each
+ * check honestly not checked.
+ */
+export declare function buildReviewEvidence(units: readonly ReviewUnit[], options?: ReviewEvidenceOptions): ReviewEvidenceResult;