socraticode/dist/services/graph-analysis.d.ts

SocratiCode — MCP server for local codebase indexing, semantic search, and code dependency graphs. All private, all local via Docker.

import type { CodeGraph, CodeGraphNode } from "../types.js";
/**
 * Resolve a graph node's language for display/stats. Prefers the language stored
 * on the node at build time (correct for extensionless files, whose path carries
 * no extension); falls back to deriving it from the path extension for nodes with
 * no stored language (older persisted graphs, grammar-less extra-extension nodes,
 * and import-target-only nodes that discovery never content-detected).
 */
export declare function nodeLanguage(node: Pick<CodeGraphNode, "language" | "relativePath">): string;
/**
 * Fraction of captured imports that must resolve to project files before the
 * file graph is reported without a caveat.
 *
 * Measured across real repos, a resolver that cannot see a project's layout
 * lands an order of magnitude below one that can. The same 618-file Python
 * workspace resolved 35 of its 2,959 captured imports (1.2%) before the
 * issue #107 fix and 2,103 of them (71%) after; a second Python repo sits at
 * 42%, and a doc-heavy repo whose imports are largely external still reaches
 * 7.6%. 2% sits in the gap between the broken regime and the lowest healthy
 * reading, so the advisory fires on a resolver failure without nagging a
 * project that merely imports a lot of external code.
 *
 * It is a caveat on how to read the graph, not a verdict on the project: a
 * repo of scripts that import nothing but stdlib genuinely resolves near zero
 * and will trip this. That is why the advisory states what was measured and
 * names the benign explanation, and why there is no DEGRADED status token.
 */
export declare const LOW_IMPORT_RESOLUTION_RATIO = 0.02;
/**
 * Captured-import floor below which the ratio is not reported on at all.
 *
 * A handful of imports carries no signal — a five-file utility repo that
 * imports nothing but `os` and `json` would otherwise be told its graph is
 * degraded when it is complete and correct.
 */
export declare const LOW_IMPORT_RESOLUTION_MIN_IMPORTS = 20;
/**
 * Whether a built graph resolved so few of the imports it captured that its
 * dependency answers should be read as under-reporting rather than as
 * findings.
 *
 * `codebase_graph_status` reports READY on graph existence alone, so a graph
 * that resolved almost nothing is indistinguishable from a healthy one, and
 * every downstream tool answers "no dependency information" — which reads as
 * "nothing depends on this" rather than "the resolver failed" (issue #107).
 * Comparing resolved edges against the imports actually captured is what
 * separates the two: it is a per-project ratio that does not move with repo
 * size, unlike an absolute edge count, and it is not the symbol graph's
 * `unresolvedEdgePct`, which measures call-site resolution and reads high on
 * healthy repos.
 *
 * `importCount` is absent on graphs persisted before it was recorded; those
 * return false and print nothing until the next rebuild, rather than guessing.
 */
export declare function isImportResolutionLow(edgeCount: number, importCount?: number): boolean;
/**
 * Whether a persisted graph was built by an older release than the one now
 * serving it.
 *
 * A graph is stored once and served unchanged until something rebuilds it, so
 * an upgrade leaves the old artifact in place: the new binary answers queries
 * from a graph whose edges were resolved by the old one. Every signal a user
 * can read says healthy — `codebase_about` reports the new version because that
 * is the running binary, status reports READY because a graph exists — so a
 * graph cut before a language's resolver shipped is indistinguishable from that
 * resolver being broken. That cost a real bug report (issue #120), where a
 * 27-day-old graph built four days before PSR-4 resolution existed was measured
 * as a live defect in the current release.
 *
 * Ordered by SemVer precedence, prereleases included: a graph built by
 * `1.13.0-beta.1` is stale against a `1.13.0` server, because the beta predates
 * anything that landed in the run-up to the release. Build metadata carries no
 * precedence and is ignored.
 *
 * Returns false when either version is absent or unparseable: a graph persisted
 * before the stamp existed is unknown rather than stale, which the caller says
 * in its own words instead of guessing.
 */
export declare function isGraphBuilderStale(builtByVersion: string | undefined, runningVersion: string): boolean;
/**
 * The `Built by:` lines for `codebase_graph_status`: which build produced the
 * graph being served, and whether that is the build now answering.
 *
 * Warns rather than rebuilding. A rebuild is minutes of work on a large repo
 * and is the user's call, not a status call's side effect — and the reason to
 * surface this at all is that the user had no way to tell a stale artifact from
 * a broken resolver, which a sentence fixes.
 */
export declare function describeGraphBuilder(builtByVersion: string | undefined, runningVersion: string): string[];
/**
 * The symbol graph's unresolved share, stated as what it counts: every symbol
 * edge but the GDScript engine ones. A member call is reduced to its terminal
 * name, so a runtime or external-library callee is indistinguishable from a
 * project method that failed to resolve (issue #172).
 */
export declare function describeUnresolvedSymbolEdges(unresolvedEdgePct: number): string[];
/**
 * Get dependencies for a specific file.
 * The input path is normalized to forward slashes so lookups succeed
 * regardless of whether the caller passes `/` or `\` separators.
 */
export declare function getFileDependencies(graph: CodeGraph, relativePath: string): {
    imports: string[];
    importedBy: string[];
};
/**
 * Find circular dependencies in the graph.
 */
export declare function findCircularDependencies(graph: CodeGraph): string[][];
/**
 * Get summary statistics about the code graph.
 */
export declare function getGraphStats(graph: CodeGraph): {
    totalFiles: number;
    totalEdges: number;
    avgDependencies: number;
    mostConnected: Array<{
        file: string;
        connections: number;
    }>;
    orphans: string[];
    circularDeps: number;
    languageBreakdown: Record<string, number>;
};
/**
 * Generate a Mermaid diagram from a code graph.
 * Produces a flowchart showing file dependencies with color-coded language groups.
 */
export declare function generateMermaidDiagram(graph: CodeGraph): string;
//# sourceMappingURL=graph-analysis.d.ts.map