@shrkcrft/graph 0.1.0-alpha.10

package/dist/indexer/index-builder.js

@@ -0,0 +1,289 @@
+import { createHash } from 'node:crypto';
+import { readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { EdgeKind } from "../schema/edge-kind.js";
+import { NodeKind } from "../schema/node-kind.js";
+import { fingerprintFile } from "../store/file-fingerprint.js";
+import { GraphStore } from "../store/graph-store.js";
+import { summarizeCycles } from "../query/cycle-detection.js";
+import { summarizeUnresolvedImports } from "./unresolved-imports.js";
+import { detectWorkspacePackages, } from "./detect-workspace.js";
+import { EXTRACT_TS_FILE_SOURCE, extractTsFile, stitchPerFileReferences, } from "./extract-ts-file.js";
+import { extractPythonFile } from "./extract-python-file.js";
+import { extractGoFile } from "./extract-go-file.js";
+import { extractJavaFile } from "./extract-java-file.js";
+import { extractRustFile } from "./extract-rust-file.js";
+import { extractKotlinFile } from "./extract-kotlin-file.js";
+import { extractRubyFile } from "./extract-ruby-file.js";
+import { extractCsharpFile } from "./extract-csharp-file.js";
+import { extractElixirFile } from "./extract-elixir-file.js";
+import { extractPhpFile } from "./extract-php-file.js";
+import { extractDartFile } from "./extract-dart-file.js";
+import { extractSwiftFile } from "./extract-swift-file.js";
+import { createImportResolverContext, ImportResolution, resolveImport, } from "./resolve-imports.js";
+const SOURCE_EXTS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts',
+    // Web component formats — parsed by framework-scanners; the TS-AST
+    // extractor short-circuits on these.
+    '.vue', '.svelte', '.astro',
+    // Non-TS languages — handled by the per-language dispatcher.
+    '.py', '.go', '.java', '.rs', '.kt', '.kts', '.rb', '.cs', '.csx', '.ex', '.exs', '.php',
+    '.dart', '.swift',
+    // Schema-definition formats — File nodes only; framework-scanners
+    // does the SDL parsing.
+    '.graphql', '.gql',
+]);
+const SKIP_DIRS = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.git',
+    '.sharkcraft',
+    '.next',
+    '.cache',
+    '.tmp-pack',
+    'out',
+    'target',
+]);
+/**
+ * Build a full graph index and write it to disk. Overwrites any
+ * pre-existing store under `<root>/.sharkcraft/graph/`.
+ *
+ * Single-process, no worker pool yet. The compiler-API per-file extractor
+ * is fast enough at SharkCraft's size; worker-pool parallelism is a
+ * later optimisation tied to measured budgets (see code-intelligence.md
+ * §7).
+ */
+export function buildFullIndex(options) {
+    const start = Date.now();
+    const { projectRoot } = options;
+    const ignore = new Set([...SKIP_DIRS, ...(options.extraIgnore ?? [])]);
+    const sourceFiles = walkSources(projectRoot, ignore, options.maxFiles ?? 0);
+    const workspaces = detectWorkspacePackages(projectRoot);
+    const resolverCtx = createImportResolverContext(projectRoot, workspaces);
+    const nodes = [];
+    const edges = [];
+    const fingerprints = [];
+    const packageNodes = buildPackageNodes(workspaces);
+    for (const n of packageNodes)
+        nodes.push(n);
+    const fileIdByPath = new Map();
+    const packageDirIndex = buildPackageDirIndex(workspaces);
+    // Track per-file extracted + resolved imports so the stitcher pass
+    // can emit references-symbol / calls-symbol edges with cross-file
+    // targets resolved.
+    const extractedByPath = new Map();
+    const resolvedSpecByPath = new Map();
+    const defaultExportNameByPath = new Map();
+    for (const abs of sourceFiles) {
+        const fp = fingerprintFile(abs, projectRoot);
+        fingerprints.push(fp);
+        fileIdByPath.set(fp.path, fp.nodeId);
+        const extracted = fp.language === 'python' ? extractPythonFile(fp, abs)
+            : fp.language === 'go' ? extractGoFile(fp, abs)
+                : fp.language === 'java' ? extractJavaFile(fp, abs)
+                    : fp.language === 'rust' ? extractRustFile(fp, abs)
+                        : fp.language === 'kotlin' ? extractKotlinFile(fp, abs)
+                            : fp.language === 'ruby' ? extractRubyFile(fp, abs)
+                                : fp.language === 'csharp' ? extractCsharpFile(fp, abs)
+                                    : fp.language === 'elixir' ? extractElixirFile(fp, abs)
+                                        : fp.language === 'php' ? extractPhpFile(fp, abs)
+                                            : fp.language === 'dart' ? extractDartFile(fp, abs)
+                                                : fp.language === 'swift' ? extractSwiftFile(fp, abs)
+                                                    : extractTsFile(fp, abs);
+        nodes.push(extracted.fileNode);
+        for (const sym of extracted.symbolNodes)
+            nodes.push(sym);
+        for (const e of extracted.edges)
+            edges.push(e);
+        extractedByPath.set(fp.path, extracted);
+        defaultExportNameByPath.set(fp.path, extracted.fileNode.data?.['defaultExportName'] ?? undefined);
+        // BelongsToPackage edge for files inside a known package dir.
+        const pkg = findOwningPackage(fp.path, packageDirIndex);
+        if (pkg) {
+            edges.push(buildEdge(fp.nodeId, `package:${pkg.name}`, EdgeKind.BelongsToPackage, EXTRACT_TS_FILE_SOURCE));
+        }
+        // ImportsFile edges (resolved where possible).
+        const resolvedSpec = new Map();
+        for (const raw of extracted.rawImportSpecifiers) {
+            const r = resolveImport(raw.specifier, abs, resolverCtx);
+            resolvedSpec.set(raw.specifier, r.targetPath);
+            const data = {
+                specifier: r.specifier,
+                line: raw.line,
+                importKind: raw.kind,
+                resolutionKind: r.kind,
+            };
+            if (r.targetPath) {
+                const targetId = `file:${r.targetPath}`;
+                edges.push(buildEdge(fp.nodeId, targetId, EdgeKind.ImportsFile, EXTRACT_TS_FILE_SOURCE, data));
+            }
+            else {
+                const externalId = r.kind === ImportResolution.External
+                    ? `external:${r.specifier}`
+                    : `unresolved:${r.specifier}`;
+                edges.push(buildEdge(fp.nodeId, externalId, EdgeKind.ImportsFile, EXTRACT_TS_FILE_SOURCE, data));
+            }
+        }
+        resolvedSpecByPath.set(fp.path, resolvedSpec);
+    }
+    // Stitch references / calls edges now that bindings + targets are all
+    // collected. Loops over the same files; cheap.
+    for (const [path, extracted] of extractedByPath) {
+        const localNames = new Map();
+        for (const sym of extracted.symbolNodes)
+            localNames.set(sym.label, sym.id);
+        const refEdges = stitchPerFileReferences({
+            fileNodeId: extracted.fileNode.id,
+            extracted,
+            resolvedSpec: resolvedSpecByPath.get(path) ?? new Map(),
+            defaultExportNameByPath,
+            localSymbolNamesInThisFile: localNames,
+        });
+        for (const e of refEdges)
+            edges.push(e);
+    }
+    // PackageDependsOn aggregates: collapse internal ImportsFile edges to
+    // their owning package on both sides.
+    collectPackageDependsOn(edges, packageDirIndex);
+    // Drop duplicate edges (extractor may emit identical edges for `export
+    // { foo } from './foo'` and an `import` re-using the same line — same
+    // hashed id, last write wins). Edge dedupe by id.
+    const seen = new Set();
+    const dedupedEdges = [];
+    for (const e of edges) {
+        if (seen.has(e.id))
+            continue;
+        seen.add(e.id);
+        dedupedEdges.push(e);
+    }
+    const store = new GraphStore(projectRoot);
+    const cycles = summarizeCycles(nodes, dedupedEdges);
+    const unresolved = summarizeUnresolvedImports(dedupedEdges);
+    const manifest = store.writeSnapshot(nodes, dedupedEdges, fingerprints, {
+        projectRoot,
+        lastIndexedAt: new Date().toISOString(),
+        lastIndexDurationMs: Date.now() - start,
+        filesIndexed: fingerprints.length,
+        workspacePackages: workspaces.map((w) => w.name),
+        // nodesByKind / edgesByKind are filled in by the store.
+        nodesByKind: {},
+        edgesByKind: {},
+        cycleCount: cycles.cycleCount,
+        largestCycleSize: cycles.largestCycleSize,
+        filesInCycles: cycles.filesInCycles,
+        unresolvedImportCount: unresolved.unresolvedImportCount,
+        filesWithUnresolvedImports: unresolved.filesWithUnresolvedImports,
+        unresolvedImportSamples: unresolved.unresolvedImportSamples,
+    });
+    return { manifest, durationMs: Date.now() - start };
+}
+function walkSources(projectRoot, ignore, maxFiles) {
+    const out = [];
+    const stack = [projectRoot];
+    while (stack.length > 0) {
+        if (maxFiles > 0 && out.length >= maxFiles)
+            break;
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (ignore.has(name))
+                continue;
+            if (name.startsWith('.') && name !== '.')
+                continue;
+            const full = nodePath.join(dir, name);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                stack.push(full);
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            if (!SOURCE_EXTS.has(nodePath.extname(full).toLowerCase()))
+                continue;
+            out.push(full);
+            if (maxFiles > 0 && out.length >= maxFiles)
+                break;
+        }
+    }
+    return out.sort();
+}
+function buildPackageNodes(packages) {
+    return packages.map((p) => ({
+        id: `package:${p.name}`,
+        kind: NodeKind.Package,
+        label: p.name,
+        path: p.dir,
+        data: {
+            ...(p.entry ? { entry: p.entry } : {}),
+        },
+    }));
+}
+function buildPackageDirIndex(packages) {
+    // Sorted by length desc so the most-specific match wins (e.g.
+    // `packages/foo/sub` resolves before `packages/foo`).
+    const entries = [...packages]
+        .map((p) => ({ dir: p.dir.replace(/\/+$/, ''), name: p.name }))
+        .sort((a, b) => b.dir.length - a.dir.length);
+    return { entries };
+}
+function findOwningPackage(filePath, index) {
+    for (const e of index.entries) {
+        if (filePath === e.dir || filePath.startsWith(e.dir + '/')) {
+            return e;
+        }
+    }
+    return undefined;
+}
+function collectPackageDependsOn(edges, index) {
+    const pairs = new Map();
+    for (const e of edges) {
+        if (e.kind !== EdgeKind.ImportsFile)
+            continue;
+        const fromFile = stripPrefix(e.from, 'file:');
+        const toFile = stripPrefix(e.to, 'file:');
+        if (!fromFile || !toFile)
+            continue; // skip external / unresolved targets
+        const fromPkg = findOwningPackage(fromFile, index);
+        const toPkg = findOwningPackage(toFile, index);
+        if (!fromPkg || !toPkg)
+            continue;
+        if (fromPkg.name === toPkg.name)
+            continue;
+        const k = `${fromPkg.name}|${toPkg.name}`;
+        const cur = pairs.get(k);
+        if (cur)
+            cur.count += 1;
+        else
+            pairs.set(k, { from: fromPkg.name, to: toPkg.name, count: 1 });
+    }
+    for (const { from, to, count } of pairs.values()) {
+        edges.push(buildEdge(`package:${from}`, `package:${to}`, EdgeKind.PackageDependsOn, 'index-builder@v1', { count }));
+    }
+}
+function buildEdge(from, to, kind, source, data) {
+    return {
+        id: createHash('sha1').update(`${from}|${to}|${kind}`).digest('hex'),
+        from,
+        to,
+        kind,
+        source,
+        ...(data ? { data } : {}),
+    };
+}
+function stripPrefix(id, prefix) {
+    return id.startsWith(prefix) ? id.slice(prefix.length) : undefined;
+}

package/dist/indexer/resolve-imports.d.ts

@@ -0,0 +1,36 @@
+import { type ITsconfigPathsMap } from '@shrkcrft/boundaries';
+import type { IWorkspacePackage } from './detect-workspace.js';
+export declare enum ImportResolution {
+    Relative = "relative",
+    Alias = "alias",
+    Workspace = "workspace",
+    External = "external",
+    Unresolved = "unresolved"
+}
+export interface IResolvedImport {
+    /** Project-relative path to the target file, POSIX, when resolved. */
+    targetPath?: string;
+    kind: ImportResolution;
+    /** Specifier as it appeared in source. */
+    specifier: string;
+}
+export interface IImportResolverContext {
+    projectRoot: string;
+    workspacePackages: readonly IWorkspacePackage[];
+    tsconfigPaths: ITsconfigPathsMap;
+}
+export declare function createImportResolverContext(projectRoot: string, workspacePackages: readonly IWorkspacePackage[]): IImportResolverContext;
+/**
+ * Resolve an import specifier to a project-relative file path.
+ *
+ * Resolution order (cheapest first):
+ *   1. Relative (`./` or `../`) against the source file's directory.
+ *   2. tsconfig path aliases.
+ *   3. Workspace package name (exact match or `<pkg>/<sub>`).
+ *   4. External — left unresolved with `ImportResolution.External`.
+ *
+ * `fromAbsPath` is the absolute path of the importing file; needed for
+ * relative resolution.
+ */
+export declare function resolveImport(specifier: string, fromAbsPath: string, ctx: IImportResolverContext): IResolvedImport;
+//# sourceMappingURL=resolve-imports.d.ts.map

package/dist/indexer/resolve-imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-imports.d.ts","sourceRoot":"","sources":["../../src/indexer/resolve-imports.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAI/D,oBAAY,gBAAgB;IAC1B,QAAQ,aAAa;IACrB,KAAK,UAAU;IACf,SAAS,cAAc;IACvB,QAAQ,aAAa;IACrB,UAAU,eAAe;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,gBAAgB,CAAC;IACvB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,aAAa,EAAE,iBAAiB,CAAC;CAClC;AAED,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,iBAAiB,EAAE,SAAS,iBAAiB,EAAE,GAC9C,sBAAsB,CAMxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,sBAAsB,GAC1B,eAAe,CAwCjB"}

package/dist/indexer/resolve-imports.js

@@ -0,0 +1,144 @@
+import { existsSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { loadTsconfigPaths, resolveAliasCandidates, } from '@shrkcrft/boundaries';
+const PROBE_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts'];
+export var ImportResolution;
+(function (ImportResolution) {
+    ImportResolution["Relative"] = "relative";
+    ImportResolution["Alias"] = "alias";
+    ImportResolution["Workspace"] = "workspace";
+    ImportResolution["External"] = "external";
+    ImportResolution["Unresolved"] = "unresolved";
+})(ImportResolution || (ImportResolution = {}));
+export function createImportResolverContext(projectRoot, workspacePackages) {
+    return {
+        projectRoot,
+        workspacePackages,
+        tsconfigPaths: loadTsconfigPaths(projectRoot),
+    };
+}
+/**
+ * Resolve an import specifier to a project-relative file path.
+ *
+ * Resolution order (cheapest first):
+ *   1. Relative (`./` or `../`) against the source file's directory.
+ *   2. tsconfig path aliases.
+ *   3. Workspace package name (exact match or `<pkg>/<sub>`).
+ *   4. External — left unresolved with `ImportResolution.External`.
+ *
+ * `fromAbsPath` is the absolute path of the importing file; needed for
+ * relative resolution.
+ */
+export function resolveImport(specifier, fromAbsPath, ctx) {
+    if (specifier.startsWith('.')) {
+        const dir = nodePath.dirname(fromAbsPath);
+        const probe = probeCandidate(nodePath.resolve(dir, specifier));
+        if (probe) {
+            return {
+                specifier,
+                targetPath: toProjectRel(ctx.projectRoot, probe),
+                kind: ImportResolution.Relative,
+            };
+        }
+        return { specifier, kind: ImportResolution.Unresolved };
+    }
+    const aliasCandidates = resolveAliasCandidates(specifier, ctx.tsconfigPaths);
+    for (const cand of aliasCandidates) {
+        const abs = nodePath.resolve(ctx.projectRoot, cand);
+        const probe = probeCandidate(abs);
+        if (probe) {
+            return {
+                specifier,
+                targetPath: toProjectRel(ctx.projectRoot, probe),
+                kind: ImportResolution.Alias,
+            };
+        }
+    }
+    const ws = findWorkspacePackage(specifier, ctx.workspacePackages);
+    if (ws) {
+        const probe = resolveWorkspaceTarget(specifier, ws, ctx.projectRoot);
+        if (probe) {
+            return {
+                specifier,
+                targetPath: toProjectRel(ctx.projectRoot, probe),
+                kind: ImportResolution.Workspace,
+            };
+        }
+    }
+    return { specifier, kind: ImportResolution.External };
+}
+function probeCandidate(absPathNoExt) {
+    // If the path already has a known extension and exists, return it.
+    const ext = nodePath.extname(absPathNoExt);
+    if (PROBE_EXTS.includes(ext) && existsSafe(absPathNoExt) && isFile(absPathNoExt)) {
+        return absPathNoExt;
+    }
+    // Try appending each known extension.
+    for (const e of PROBE_EXTS) {
+        const cand = absPathNoExt + e;
+        if (existsSafe(cand) && isFile(cand))
+            return cand;
+    }
+    // Try as a directory with index.<ext>.
+    if (existsSafe(absPathNoExt) && isDir(absPathNoExt)) {
+        for (const e of PROBE_EXTS) {
+            const cand = nodePath.join(absPathNoExt, `index${e}`);
+            if (existsSafe(cand) && isFile(cand))
+                return cand;
+        }
+    }
+    return undefined;
+}
+function findWorkspacePackage(specifier, packages) {
+    for (const p of packages) {
+        if (specifier === p.name)
+            return p;
+        if (specifier.startsWith(p.name + '/'))
+            return p;
+    }
+    return undefined;
+}
+function resolveWorkspaceTarget(specifier, pkg, projectRoot) {
+    // Exact match → resolve via package entry, falling back to src/index.<ext>.
+    if (specifier === pkg.name) {
+        if (pkg.entry) {
+            const cand = nodePath.resolve(projectRoot, pkg.entry);
+            if (existsSafe(cand) && isFile(cand))
+                return cand;
+            // Some packages list ./dist/index.js as main; for source-time graphs
+            // we'd rather hit the src/. Try that next.
+        }
+        const srcIndex = nodePath.resolve(projectRoot, pkg.dir, 'src');
+        return probeCandidate(srcIndex);
+    }
+    // Subpath: `<pkg>/foo/bar`.
+    const sub = specifier.slice(pkg.name.length + 1);
+    return probeCandidate(nodePath.resolve(projectRoot, pkg.dir, sub));
+}
+function existsSafe(p) {
+    try {
+        return existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+function isFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function toProjectRel(projectRoot, abs) {
+    return nodePath.relative(projectRoot, abs).split(nodePath.sep).join('/');
+}

package/dist/indexer/unresolved-imports.d.ts

@@ -0,0 +1,20 @@
+import type { IEdge } from '../schema/edge.js';
+export interface IUnresolvedImportSummary {
+    /** Total `unresolved:<spec>` ImportsFile edges. */
+    unresolvedImportCount: number;
+    /** Distinct file ids with at least one unresolved import. */
+    filesWithUnresolvedImports: number;
+    /** Up to `sampleLimit` distinct specifier strings. */
+    unresolvedImportSamples: readonly string[];
+}
+/**
+ * Roll up unresolved imports from the indexer's edge list. The indexer
+ * already emits edges targeting `unresolved:<spec>` when the resolver
+ * fails (relative path doesn't exist, alias points nowhere, workspace
+ * package not found). This helper counts them so the manifest can
+ * carry a stable counter the doctor + dashboard read from.
+ *
+ * Pure function over the dedupe'd edge set; no I/O.
+ */
+export declare function summarizeUnresolvedImports(edges: readonly IEdge[], sampleLimit?: number): IUnresolvedImportSummary;
+//# sourceMappingURL=unresolved-imports.d.ts.map

package/dist/indexer/unresolved-imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unresolved-imports.d.ts","sourceRoot":"","sources":["../../src/indexer/unresolved-imports.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,WAAW,wBAAwB;IACvC,mDAAmD;IACnD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,6DAA6D;IAC7D,0BAA0B,EAAE,MAAM,CAAC;IACnC,sDAAsD;IACtD,uBAAuB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAID;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,SAAS,KAAK,EAAE,EACvB,WAAW,GAAE,MAA6B,GACzC,wBAAwB,CAkB1B"}

package/dist/indexer/unresolved-imports.js

@@ -0,0 +1,32 @@
+import { EdgeKind } from "../schema/edge-kind.js";
+const DEFAULT_SAMPLE_LIMIT = 10;
+/**
+ * Roll up unresolved imports from the indexer's edge list. The indexer
+ * already emits edges targeting `unresolved:<spec>` when the resolver
+ * fails (relative path doesn't exist, alias points nowhere, workspace
+ * package not found). This helper counts them so the manifest can
+ * carry a stable counter the doctor + dashboard read from.
+ *
+ * Pure function over the dedupe'd edge set; no I/O.
+ */
+export function summarizeUnresolvedImports(edges, sampleLimit = DEFAULT_SAMPLE_LIMIT) {
+    let unresolvedImportCount = 0;
+    const fileSet = new Set();
+    const sampleSet = new Set();
+    for (const e of edges) {
+        if (e.kind !== EdgeKind.ImportsFile)
+            continue;
+        if (!e.to.startsWith('unresolved:'))
+            continue;
+        unresolvedImportCount += 1;
+        fileSet.add(e.from);
+        if (sampleSet.size < sampleLimit) {
+            sampleSet.add(e.to.slice('unresolved:'.length));
+        }
+    }
+    return {
+        unresolvedImportCount,
+        filesWithUnresolvedImports: fileSet.size,
+        unresolvedImportSamples: [...sampleSet].sort(),
+    };
+}

package/dist/query/cycle-detection.d.ts

@@ -0,0 +1,40 @@
+import type { IEdge } from '../schema/edge.js';
+import type { INode } from '../schema/node.js';
+export interface ICycleSummary {
+    /** Number of strongly-connected components of size ≥ 2. */
+    cycleCount: number;
+    /** Size of the largest SCC of size ≥ 2 (0 if no cycles). */
+    largestCycleSize: number;
+    /** Total number of file nodes participating in some cycle. */
+    filesInCycles: number;
+}
+/**
+ * A single import cycle. `nodeIds` are the participating `file:<path>`
+ * node ids, in iteration order from Tarjan SCC (the entry node is at
+ * index 0; the cycle is undirected from a presentation standpoint).
+ * Renderers usually want to display `paths` instead — file ids are
+ * stable but bear the `file:` prefix.
+ */
+export interface IFileCycle {
+    /** Stable file node ids that form the cycle. */
+    nodeIds: readonly string[];
+    /** Project-relative file paths (filled when callers can resolve them). */
+    paths?: readonly string[];
+    /** Cycle size (== nodeIds.length). */
+    size: number;
+}
+/**
+ * Find every import cycle in the file-import directed graph. Returns
+ * one entry per SCC of size ≥ 2. Iterative Tarjan SCC over the
+ * `imports-file` subgraph; O(V+E) and stack-safe.
+ *
+ * `pathById` is optional — when supplied, the returned `paths` array
+ * is populated so callers don't have to re-resolve file ids.
+ */
+export declare function findFileCycles(nodes: readonly INode[], edges: readonly IEdge[], pathById?: ReadonlyMap<string, string>): readonly IFileCycle[];
+/**
+ * Roll-up over `findFileCycles` results. Kept for downstream callers
+ * (the indexer, doctor) that only care about counts.
+ */
+export declare function summarizeCycles(nodes: readonly INode[], edges: readonly IEdge[]): ICycleSummary;
+//# sourceMappingURL=cycle-detection.d.ts.map

package/dist/query/cycle-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle-detection.d.ts","sourceRoot":"","sources":["../../src/query/cycle-detection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG/C,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,0EAA0E;IAC1E,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,KAAK,EAAE,EACvB,KAAK,EAAE,SAAS,KAAK,EAAE,EACvB,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACrC,SAAS,UAAU,EAAE,CAsBvB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,KAAK,EAAE,EACvB,KAAK,EAAE,SAAS,KAAK,EAAE,GACtB,aAAa,CAaf"}