@dreamtree-org/graphify 1.0.0 → 1.1.2

package/dist/index.d.cts

@@ -51,15 +51,22 @@ interface ExportOptions {
  */
 declare function collectFiles(root: string): FileManifest;
 
-type Extractor = (path: string) => Promise<ExtractionResult>;
+/** `displayPath`, when given, is used for node ids/sourceFile instead of the read path — see extract(). */
+type Extractor = (path: string, displayPath?: string) => Promise<ExtractionResult>;
 /** File extension -> extractor module. Register new languages here. */
 declare const EXTRACTOR_REGISTRY: Record<string, Extractor>;
 /**
  * Dispatch a single file to its language extractor. Returns an empty
  * extraction (not a thrown error) for unregistered extensions so detect's
  * file list and extract's coverage can diverge without crashing a run.
+ *
+ * `displayPath` decouples where the file is read from (relative to the
+ * process cwd) from the path used in node ids and sourceFile attributes —
+ * the pipeline passes the project-root-relative path so ids stay stable
+ * and portable no matter which directory the pipeline was launched from
+ * (this is what makes cross-project merging's namespacing meaningful).
  */
-declare function extract(filePath: string): Promise<ExtractionResult>;
+declare function extract(filePath: string, displayPath?: string): Promise<ExtractionResult>;
 
 /**
  * Merge per-file extraction results into one graphology graph.
@@ -83,6 +90,28 @@ declare function extract(filePath: string): Promise<ExtractionResult>;
  */
 declare function buildGraph(extractions: ExtractionResult[]): Graph;
 
+interface ResolveOptions {
+    /**
+     * The scanned package's own name(s) (from package.json). Tests very
+     * commonly import the package's PUBLIC entry (`import { persist } from
+     * 'zustand/middleware'`) rather than a relative path — without this,
+     * those land on an opaque `module:` node and the test never connects to
+     * the source it exercises (so `graphify tests` under-selects).
+     */
+    selfNames?: string[];
+}
+interface ResolveStats {
+    /** Edge endpoints re-pointed from a guessed id to a real node id. */
+    resolvedEndpoints: number;
+    /** Placeholder module nodes dropped because the real file node replaced them. */
+    droppedPlaceholders: number;
+}
+/**
+ * Mutates `extractions` in place: re-points guessed edge endpoints at real
+ * node ids and drops the placeholder module nodes those guesses created.
+ */
+declare function resolveCrossFileReferences(extractions: ExtractionResult[], options?: ResolveOptions): ResolveStats;
+
 type ClusterAlgorithm = 'louvain' | 'leiden';
 interface ClusterOptions {
     /**
@@ -155,6 +184,17 @@ interface PipelineOptions {
     algorithm?: ClusterAlgorithm;
     /** Leiden-only: cap on outer iterations for very large graphs. */
     maxIterations?: number;
+    /**
+     * Pre-computed extractions from non-filesystem sources (e.g. a MySQL
+     * schema via extractMysql()) merged into the same graph as the code.
+     */
+    extraExtractions?: ExtractionResult[];
+    /**
+     * Incremental mode: reuse cached per-file extractions (keyed by content
+     * hash) and re-parse only changed files. The cache is warmed on every
+     * run either way — `update` only controls whether it's read.
+     */
+    update?: boolean;
     /** Called with a short progress message after each stage (e.g. for CLI stderr output). */
     onProgress?: (message: string) => void;
 }
@@ -186,7 +226,18 @@ interface NodeMatch {
     label: string;
     score: number;
 }
-/** Score every node by how many query tokens appear in its label or id. */
+/**
+ * Score every node against the query's tokens. Identifier-aware and
+ * typo-tolerant, in three tiers per token (best tier wins):
+ *
+ *   1. exact subtoken match (camelCase/snake_case-split word of the label
+ *      or id) — "storage" matches `fileStorage.js`;
+ *   2. plain substring of the label/id (the original v1 behavior);
+ *   3. fuzzy (Damerau-Levenshtein) match against a subtoken — "sorce"
+ *      still finds `scoreNodes`.
+ *
+ * Still fully lexical and deterministic — no LLM, no randomness.
+ */
 declare function scoreNodes(graph: Graph, query: string): NodeMatch[];
 /**
  * Best-effort single-node resolution: the highest-scoring lexical match,
@@ -216,8 +267,10 @@ interface QueryResult {
 }
 interface QueryOptions {
     dfs?: boolean;
-    /** Approximate cap on how many nodes to include (a stand-in for a true token budget — see docs). */
+    /** Hard cap on how many nodes to include. Defaults to a generous ceiling derived from `tokenBudget`. */
     budget?: number;
+    /** Approximate cap, in tokens (~4 chars each), on the serialized size of the result. Default 2000. */
+    tokenBudget?: number;
     maxDepth?: number;
     maxSeeds?: number;
 }
@@ -251,6 +304,291 @@ interface ExplainResult {
 /** Plain-language-ready explanation of the node that best matches `query`. */
 declare function explainNode(graph: Graph, query: string): ExplainResult | null;
 
+interface AffectedNode {
+    id: string;
+    label: string;
+    sourceFile: string;
+    sourceLocation: string;
+    /** 1 = depends on the target directly, 2 = one step removed, ... */
+    depth: number;
+    /** The dependency edge that pulled this node in (this node -> something already affected). */
+    via: {
+        relation: Relation;
+        confidence: Confidence;
+        /** The already-affected node this one depends on. */
+        dependsOn: string;
+    };
+}
+interface ImpactResult {
+    target: NodeMatch;
+    affected: AffectedNode[];
+    /** How many affected nodes there are per confidence tier of the edge that pulled each one in. */
+    byConfidence: Record<Confidence, number>;
+    maxDepth: number;
+    truncated: boolean;
+}
+interface ImpactOptions {
+    /** How many reverse hops to follow (default 3). */
+    maxDepth?: number;
+    /** Hard cap on affected nodes reported (default 200). */
+    limit?: number;
+}
+/**
+ * Resolve `nodeQuery` to its best-matching node, then reverse-BFS over
+ * incoming dependency edges. Returns null when nothing in the graph matches
+ * the query at all (same contract as explainNode()).
+ */
+declare function affectedBy(graph: Graph, nodeQuery: string, options?: ImpactOptions): ImpactResult | null;
+
+/**
+ * Cross-project graph merging — combine several already-built graphs (one
+ * per repo/project) into a single queryable global graph.
+ *
+ * Node ids inside one project are relative-path-based (`src/a.ts::foo`), so
+ * two projects' ids would collide. Every node id and sourceFile is therefore
+ * prefixed with `<project>/` — EXCEPT `module:*` (bare package imports) and
+ * `external:*` (unresolved reference targets) nodes, which deliberately stay
+ * unprefixed and shared: two repos importing the same package meet at the
+ * same node, so cross-repo bridges emerge in the merged graph instead of
+ * each repo floating as a disconnected island.
+ */
+interface MergeEntry {
+    /** Project name used as the id/sourceFile namespace prefix. */
+    name: string;
+    graph: Graph;
+}
+/**
+ * Merge the entries into one directed graph, applying the same
+ * deterministic-ordering and duplicate-edge rules as buildGraph(): entries
+ * are processed in name order, duplicate edges (possible via shared
+ * external nodes) keep the strongest confidence, and every node carries a
+ * `project` attribute (shared external nodes get `project: '(shared)'`
+ * once more than one project touches them).
+ */
+declare function mergeGraphs(entries: MergeEntry[]): Graph;
+
+/**
+ * MySQL schema extraction — introspect information_schema over a
+ * user-supplied DSN and map the schema onto the same ExtractionResult shape
+ * every code extractor produces, so tables/columns/foreign keys land in the
+ * same graph as the code that talks to them.
+ *
+ * Only ever surfaces the credential-free DSN rendering (see
+ * security.validateDsn()) in node attributes; the password never leaves the
+ * connection config.
+ */
+/** One `SELECT` against the live connection. Injectable so tests run on canned rows, mirroring security.ts's LookupFn pattern. */
+type DsnQueryFn = (sql: string, params: ReadonlyArray<string>) => Promise<Array<Record<string, unknown>>>;
+/**
+ * Extract the schema graph for the database named in `dsn`.
+ *
+ * Nodes: the schema, every table/view, every column.
+ * Edges: schema `contains` table, table `contains` column, FK column
+ * `references` the referenced table (EXTRACTED), view `references` its base
+ * tables (EXTRACTED via VIEW_TABLE_USAGE on MySQL >= 8.0.13, INFERRED via a
+ * VIEW_DEFINITION text match on older servers).
+ */
+declare function extractMysql(dsn: string, queryFn?: DsnQueryFn): Promise<ExtractionResult>;
+
+/**
+ * The graph feedback loop — `graphify save-result` logs which graph nodes
+ * actually helped answer a question (or led nowhere), and `graphify
+ * reflect` aggregates those logs into a recency-weighted LESSONS.md an
+ * agent can read at session start. This is what turns the graph from a
+ * static map into one that learns which landmarks matter.
+ */
+type ResultOutcome = 'useful' | 'dead_end' | 'corrected';
+type ResultType = 'query' | 'path' | 'explain' | 'affected';
+interface SavedResult {
+    question: string;
+    answer: string;
+    type: ResultType;
+    outcome: ResultOutcome;
+    /** Node ids/labels cited in the answer. */
+    nodes: string[];
+    /** What the right answer was — pairs with outcome 'corrected'. */
+    correction?: string;
+    savedAt: string;
+}
+/** Append one result to `<memoryDir>/result-<stamp>-<hash>.json`. Returns the file path. */
+declare function saveResult(entry: Omit<SavedResult, 'savedAt'>, memoryDir: string, now?: Date): Promise<string>;
+interface ReflectOptions {
+    /** A result's weight halves every this many days (default 30). */
+    halfLifeDays?: number;
+    /** Injectable clock for deterministic tests. */
+    now?: Date;
+    /** Only list nodes cited usefully at least this many distinct times (default 2). */
+    minCorroboration?: number;
+}
+/** Read every result JSON under `memoryDir` (missing dir = no results). */
+declare function loadResults(memoryDir: string): Promise<SavedResult[]>;
+/** Aggregate saved results into a LESSONS.md string. Deterministic given results + options.now. */
+declare function renderLessons(results: SavedResult[], options?: ReflectOptions): string;
+
+/**
+ * `graphify context` — the working-set pack. Instead of returning node
+ * names for the agent to chase (query -> then read whole files anyway),
+ * this fuses the two steps: the graph knows every entity's file and line,
+ * so rank the nodes relevant to the task, read just the relevant line
+ * ranges, and pack the actual code into a token budget. One call returns
+ * the code an agent needs to start a task.
+ */
+interface ContextSnippet {
+    nodeId: string;
+    label: string;
+    file: string;
+    startLine: number;
+    endLine: number;
+    code: string;
+    /** Why this snippet is in the pack (lexical match / neighbor-of relation). */
+    reason: string;
+    score: number;
+}
+interface ContextPack {
+    task: string;
+    snippets: ContextSnippet[];
+    /** Approximate tokens used out of the budget. */
+    tokens: number;
+    tokenBudget: number;
+    /** Ranked nodes that didn't fit the budget — the agent can pull them explicitly. */
+    overflow: Array<{
+        nodeId: string;
+        file: string;
+    }>;
+}
+interface ContextOptions {
+    /** Approximate token cap for the pack (default 4000). */
+    tokenBudget?: number;
+    maxSeeds?: number;
+    /** Cap on snippet length in lines (default 60). */
+    maxSnippetLines?: number;
+}
+type FileReader = (path: string) => Promise<string>;
+interface RankedNode {
+    id: string;
+    score: number;
+    reason: string;
+}
+/**
+ * Rank nodes for the task: lexical seeds first (their match score), then
+ * their graph neighbors at a decayed score, labeled with the relation that
+ * connects them. Deterministic (score desc, id asc).
+ */
+declare function rankForTask(graph: Graph, task: string, maxSeeds?: number): RankedNode[];
+declare function buildContextPack(graph: Graph, task: string, readFile: FileReader, options?: ContextOptions): Promise<ContextPack>;
+/** Render a pack as agent-ready markdown. */
+declare function renderContextPack(pack: ContextPack): string;
+
+declare function isTestFile(path: string): boolean;
+interface TestSelection {
+    /** What the selection was computed for (resolved node id, or the changed files). */
+    target: string;
+    /** Unique test files, most directly affected first. */
+    testFiles: Array<{
+        file: string;
+        depth: number;
+        via: string;
+    }>;
+    /** How many non-test nodes were in the blast radius (context for confidence). */
+    affectedNodeCount: number;
+}
+/** Test files reachable (reverse) from the node best matching `nodeQuery`. Null if nothing matches. */
+declare function testsForNode(graph: Graph, nodeQuery: string): TestSelection | null;
+/**
+ * Test files reachable from any of the given changed files (as reported by
+ * `git diff --name-only`). Changed test files select themselves. Unknown
+ * files (not in the graph) are skipped.
+ */
+declare function testsForChangedFiles(graph: Graph, changedFiles: string[]): TestSelection;
+
+/**
+ * `graphify review` — semantic graph diff between two git revisions.
+ * Full structural extraction is sub-second, so instead of parsing text
+ * diffs we build the graph at both revs and diff the graphs: which symbols
+ * appeared, disappeared, or got rewired — each with its blast radius and
+ * the test files worth running. One command answers both "what changed
+ * since I was last here" and "review this PR structurally".
+ */
+interface ChangedSymbol {
+    id: string;
+    label: string;
+    sourceFile: string;
+    /** Everything that depends on this symbol (computed in the graph where it exists). */
+    blastRadius: number;
+    /** Test files reachable from it. */
+    tests: string[];
+}
+interface RewiredSymbol extends ChangedSymbol {
+    gainedEdges: string[];
+    lostEdges: string[];
+}
+interface GraphDiff {
+    base: string;
+    head: string;
+    added: ChangedSymbol[];
+    removed: ChangedSymbol[];
+    rewired: RewiredSymbol[];
+}
+/** Extract a graph from a directory without exporting anything. */
+declare function graphForDirectory(root: string): Promise<Graph>;
+declare function diffGraphs(baseGraph: Graph, headGraph: Graph, base: string, head: string): GraphDiff;
+/** Diff two revisions of the repo at `repoRoot`. `head` defaults to the working head via a second archive of HEAD. */
+declare function reviewRevisions(repoRoot: string, base: string, head?: string): Promise<GraphDiff>;
+declare function renderReview(diff: GraphDiff): string;
+
+/**
+ * `graphify check` — architecture guardrails. Declarative dependency rules
+ * checked against the graph's edges, with CI-friendly results: an agent (or
+ * a pipeline) can verify an edit didn't violate the architecture before it
+ * lands. Cross-language, because the graph already is.
+ */
+interface DependencyRule {
+    /** Short rule name shown in violations. */
+    name: string;
+    /** Glob over the depending file (edge source's sourceFile). */
+    from: string;
+    /** Globs the dependency target's file must NOT match. */
+    disallow: string[];
+    /** Optional human explanation echoed with violations. */
+    reason?: string;
+}
+interface RulesConfig {
+    rules: DependencyRule[];
+}
+interface Violation {
+    rule: string;
+    reason?: string;
+    fromFile: string;
+    fromNode: string;
+    toFile: string;
+    toNode: string;
+    relation: string;
+}
+/**
+ * Minimal glob: `**` crosses directories, `*` stays within one segment.
+ * Anchored on both ends. Enough for path rules without a dependency.
+ */
+declare function globToRegExp(glob: string): RegExp;
+declare function validateRules(value: unknown): RulesConfig;
+/** Check every dependency edge in the graph against the rules. Deterministic ordering. */
+declare function checkRules(graph: Graph, config: RulesConfig): Violation[];
+
+/**
+ * Per-file extraction cache — what makes `--update` (and every rebuild
+ * behind a git hook or --watch) incremental. Entries are keyed by a hash of
+ * the file's CONTENT plus its root-relative path: content because that's
+ * what extraction depends on, path because node ids embed it. A stale entry
+ * for content that changed simply never matches again; the whole directory
+ * can always be deleted safely.
+ */
+declare class ExtractionCache {
+    private readonly dir;
+    constructor(outDir: string);
+    key(relFile: string, content: Buffer | string): string;
+    get(key: string): Promise<ExtractionResult | null>;
+    put(key: string, extraction: ExtractionResult): Promise<void>;
+}
+
 declare const ExtractionResultSchema: z.ZodObject<{
     nodes: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -298,4 +636,4 @@ declare class ExtractionValidationError extends Error {
  */
 declare function validateExtraction(value: unknown, context?: string): ExtractionResult;
 
-export { type Analysis, type ClusterAlgorithm, type ClusterOptions, type Confidence, EXTRACTOR_REGISTRY, type ExplainResult, type ExportOptions, type ExtractionResult, ExtractionResultSchema, ExtractionValidationError, type ExtractionValidationIssue, type FileCategory, type FileManifest, type GraphEdge, type GraphNode, type NodeMatch, type PathResult, type PipelineOptions, type PipelineResult, type QueryOptions, type QueryResult, type Relation, type TraversalEdge, type VisitedNode, analyze, buildGraph, cluster, collectFiles, explainNode, exportGraph, extract, loadGraph, queryGraph, renderReport, resolveNode, runPipeline, scoreNodes, shortestPath, validateExtraction };
+export { type AffectedNode, type Analysis, type ChangedSymbol, type ClusterAlgorithm, type ClusterOptions, type Confidence, type ContextOptions, type ContextPack, type ContextSnippet, type DependencyRule, type DsnQueryFn, EXTRACTOR_REGISTRY, type ExplainResult, type ExportOptions, ExtractionCache, type ExtractionResult, ExtractionResultSchema, ExtractionValidationError, type ExtractionValidationIssue, type FileCategory, type FileManifest, type GraphDiff, type GraphEdge, type GraphNode, type ImpactOptions, type ImpactResult, type MergeEntry, type NodeMatch, type PathResult, type PipelineOptions, type PipelineResult, type QueryOptions, type QueryResult, type ReflectOptions, type Relation, type ResolveStats, type ResultOutcome, type ResultType, type RewiredSymbol, type RulesConfig, type SavedResult, type TestSelection, type TraversalEdge, type Violation, type VisitedNode, affectedBy, analyze, buildContextPack, buildGraph, checkRules, cluster, collectFiles, diffGraphs, explainNode, exportGraph, extract, extractMysql, globToRegExp, graphForDirectory, isTestFile, loadGraph, loadResults, mergeGraphs, queryGraph, rankForTask, renderContextPack, renderLessons, renderReport, renderReview, resolveCrossFileReferences, resolveNode, reviewRevisions, runPipeline, saveResult, scoreNodes, shortestPath, testsForChangedFiles, testsForNode, validateExtraction, validateRules };