optave-codegraph 3.13.0

package/dist/features/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/features/snapshot.ts"],"names":[],"mappings":"AAUA,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMvD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,UAAU,mBAAmB;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAqCD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,mBAAwB,GAChC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA4D9C;AAED,UAAU,qBAAqB;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,IAAI,CA2CvF;AAED,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,wBAAgB,YAAY,CAAC,OAAO,GAAE,qBAA0B,GAAG,aAAa,EAAE,CAoBjF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,IAAI,CAetF"}

package/dist/features/snapshot.js

@@ -0,0 +1,188 @@
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getDatabase } from '../db/better-sqlite3.js';
+import { findDbPath } from '../db/index.js';
+import { debug } from '../infrastructure/logger.js';
+import { ConfigError, DbError } from '../shared/errors.js';
+const NAME_RE = /^[a-zA-Z0-9_-]+$/;
+export function validateSnapshotName(name) {
+    if (!name || !NAME_RE.test(name)) {
+        throw new ConfigError(`Invalid snapshot name "${name}". Use only letters, digits, hyphens, and underscores.`);
+    }
+}
+export function snapshotsDir(dbPath) {
+    return path.join(path.dirname(dbPath), 'snapshots');
+}
+/**
+ * Atomically place `tmp` at `dest`.
+ * - force=true: renameSync (overwrites any existing file).
+ * - force=false: linkSync so EEXIST is detected atomically; then unlink tmp.
+ * Callers are responsible for cleaning up `tmp` on any thrown error.
+ */
+function atomicPlaceFile(tmp, dest, name, force) {
+    if (force) {
+        // renameSync overwrites atomically — the correct semantics for --force.
+        fs.renameSync(tmp, dest);
+        return;
+    }
+    // Non-force path: linkSync fails atomically with EEXIST if dest exists,
+    // closing the TOCTOU window between existsSync above and the final
+    // placement. We then unlink the temp file; on POSIX and NTFS, link
+    // creates a second reference so tmp can safely be removed.
+    try {
+        fs.linkSync(tmp, dest);
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            throw new ConfigError(`Snapshot "${name}" already exists. Use --force to overwrite.`);
+        }
+        throw err;
+    }
+    try {
+        fs.unlinkSync(tmp);
+    }
+    catch (cleanupErr) {
+        // Best-effort — dest is already in place, so a leftover tmp file is
+        // harmless. Log at debug so repeated failures surface during
+        // troubleshooting without noising up normal operation.
+        debug(`snapshotSave: failed to remove temp file ${tmp}: ${cleanupErr}`);
+    }
+}
+export function snapshotSave(name, options = {}) {
+    validateSnapshotName(name);
+    const dbPath = options.dbPath || findDbPath();
+    if (!fs.existsSync(dbPath)) {
+        throw new DbError(`Database not found: ${dbPath}`, { file: dbPath });
+    }
+    const dir = snapshotsDir(dbPath);
+    const dest = path.join(dir, `${name}.db`);
+    // Cheap fail-fast for the common non-force case; the authoritative check
+    // below uses an atomic linkSync that closes the TOCTOU window.
+    if (!options.force && fs.existsSync(dest)) {
+        throw new ConfigError(`Snapshot "${name}" already exists. Use --force to overwrite.`);
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    // VACUUM INTO a unique temp path on the same filesystem, then atomically
+    // place it at the destination. This closes the TOCTOU window between
+    // existsSync/unlinkSync/VACUUM INTO where two concurrent saves could
+    // observe a missing file or interleave their VACUUM writes.
+    //
+    // Unique temp name: process.pid is shared across worker_threads in the
+    // same process, so we add random bytes to keep concurrent callers in any
+    // thread from colliding on the temp path.
+    const tmp = path.join(dir, `.${name}.db.tmp-${process.pid}-${Date.now()}-${randomBytes(6).toString('hex')}`);
+    try {
+        fs.unlinkSync(tmp);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    const Database = getDatabase();
+    const db = new Database(dbPath, { readonly: true });
+    try {
+        db.exec(`VACUUM INTO '${tmp.replace(/'/g, "''")}'`);
+    }
+    finally {
+        db.close();
+    }
+    try {
+        atomicPlaceFile(tmp, dest, name, options.force);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch (cleanupErr) {
+            if (cleanupErr.code !== 'ENOENT') {
+                debug(`snapshotSave: failed to remove temp file ${tmp}: ${cleanupErr}`);
+            }
+        }
+        throw err;
+    }
+    const stat = fs.statSync(dest);
+    debug(`Snapshot saved: ${dest} (${stat.size} bytes)`);
+    return { name, path: dest, size: stat.size };
+}
+export function snapshotRestore(name, options = {}) {
+    validateSnapshotName(name);
+    const dbPath = options.dbPath || findDbPath();
+    const dir = snapshotsDir(dbPath);
+    const src = path.join(dir, `${name}.db`);
+    if (!fs.existsSync(src)) {
+        throw new DbError(`Snapshot "${name}" not found at ${src}`, { file: src });
+    }
+    // Remove WAL/SHM sidecars first so the old journal can't be replayed over
+    // the restored DB. unlink then check ENOENT — avoids the existsSync/unlinkSync
+    // race another process could wedge into.
+    for (const suffix of ['-wal', '-shm']) {
+        const sidecar = dbPath + suffix;
+        try {
+            fs.unlinkSync(sidecar);
+            debug(`Removed sidecar: ${sidecar}`);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    // Copy to a temp path next to the DB, then rename atomically. Readers that
+    // open dbPath during restore see either the pre-restore or post-restore
+    // file, never a partially-written one.
+    fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+    const tmp = `${dbPath}.restore-tmp-${process.pid}-${Date.now()}-${randomBytes(6).toString('hex')}`;
+    try {
+        fs.copyFileSync(src, tmp);
+        fs.renameSync(tmp, dbPath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch (cleanupErr) {
+            if (cleanupErr.code !== 'ENOENT') {
+                debug(`snapshotRestore: failed to remove temp file ${tmp}: ${cleanupErr}`);
+            }
+        }
+        throw err;
+    }
+    debug(`Restored snapshot "${name}" → ${dbPath}`);
+}
+export function snapshotList(options = {}) {
+    const dbPath = options.dbPath || findDbPath();
+    const dir = snapshotsDir(dbPath);
+    if (!fs.existsSync(dir))
+        return [];
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.db'))
+        .map((f) => {
+        const filePath = path.join(dir, f);
+        const stat = fs.statSync(filePath);
+        return {
+            name: f.replace(/\.db$/, ''),
+            path: filePath,
+            size: stat.size,
+            createdAt: stat.birthtime,
+        };
+    })
+        .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+}
+export function snapshotDelete(name, options = {}) {
+    validateSnapshotName(name);
+    const dbPath = options.dbPath || findDbPath();
+    const dir = snapshotsDir(dbPath);
+    const target = path.join(dir, `${name}.db`);
+    try {
+        fs.unlinkSync(target);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new DbError(`Snapshot "${name}" not found at ${target}`, { file: target });
+        }
+        throw err;
+    }
+    debug(`Deleted snapshot: ${target}`);
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/features/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/features/snapshot.ts"],"names":[],"mappings":"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"}

package/dist/features/structure-query.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Structure query functions — read-only DB queries for directory structure,
+ * hotspots, and module boundaries.
+ *
+ * Split from structure.ts to separate query-time concerns (DB reads, sorting,
+ * pagination) from build-time concerns (directory insertion, metrics computation,
+ * role classification).
+ */
+import type { CodegraphConfig } from '../types.js';
+interface StructureDataOpts {
+    directory?: string;
+    depth?: number;
+    sort?: string;
+    noTests?: boolean;
+    full?: boolean;
+    fileLimit?: number;
+    limit?: number;
+    offset?: number;
+}
+interface DirectoryEntry {
+    directory: string;
+    fileCount: number;
+    symbolCount: number;
+    fanIn: number;
+    fanOut: number;
+    cohesion: number | null;
+    density: number;
+    files: {
+        file: string;
+        lineCount: number;
+        symbolCount: number;
+        importCount: number;
+        exportCount: number;
+        fanIn: number;
+        fanOut: number;
+    }[];
+    subdirectories: string[];
+}
+export declare function structureData(customDbPath?: string, opts?: StructureDataOpts): {
+    directories: DirectoryEntry[];
+    count: number;
+    suppressed?: number;
+    warning?: string;
+};
+interface HotspotsDataOpts {
+    metric?: string;
+    level?: string;
+    limit?: number;
+    offset?: number;
+    noTests?: boolean;
+}
+export declare function hotspotsData(customDbPath?: string, opts?: HotspotsDataOpts): {
+    metric: string;
+    level: string;
+    limit: number;
+    items: unknown[];
+};
+interface ModuleBoundariesOpts {
+    threshold?: number;
+    config?: CodegraphConfig;
+}
+export declare function moduleBoundariesData(customDbPath?: string, opts?: ModuleBoundariesOpts): {
+    threshold: number;
+    modules: {
+        directory: string;
+        cohesion: number | null;
+        fileCount: number;
+        symbolCount: number;
+        fanIn: number;
+        fanOut: number;
+        files: string[];
+    }[];
+    count: number;
+};
+export {};
+//# sourceMappingURL=structure-query.d.ts.map

package/dist/features/structure-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure-query.d.ts","sourceRoot":"","sources":["../../src/features/structure-query.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAyBnD,UAAU,iBAAiB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,cAAc;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,EAAE,CAAC;IACJ,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AA+DD,wBAAgB,aAAa,CAC3B,YAAY,CAAC,EAAE,MAAM,EACrB,IAAI,GAAE,iBAAsB,GAC3B;IACD,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAmEA;AAeD,UAAU,gBAAgB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA4FD,wBAAgB,YAAY,CAC1B,YAAY,CAAC,EAAE,MAAM,EACrB,IAAI,GAAE,gBAAqB,GAC1B;IACD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB,CA4BA;AAED,UAAU,oBAAoB;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED,wBAAgB,oBAAoB,CAClC,YAAY,CAAC,EAAE,MAAM,EACrB,IAAI,GAAE,oBAAyB,GAC9B;IACD,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,EAAE,CAAC;KACjB,EAAE,CAAC;IACJ,KAAK,EAAE,MAAM,CAAC;CACf,CAuDA"}

package/dist/features/structure-query.js

@@ -0,0 +1,274 @@
+/**
+ * Structure query functions — read-only DB queries for directory structure,
+ * hotspots, and module boundaries.
+ *
+ * Split from structure.ts to separate query-time concerns (DB reads, sorting,
+ * pagination) from build-time concerns (directory insertion, metrics computation,
+ * role classification).
+ */
+import { openReadonlyOrFail, openReadonlyWithNative, testFilterSQL } from '../db/index.js';
+import { loadConfig } from '../infrastructure/config.js';
+import { isTestFile } from '../infrastructure/test-filter.js';
+import { normalizePath } from '../shared/constants.js';
+import { paginateResult } from '../shared/paginate.js';
+function buildDirectoryEntry(d, filesStmt, subdirsStmt, noTests) {
+    let files = filesStmt.all(d.id);
+    if (noTests)
+        files = files.filter((f) => !isTestFile(f.name));
+    const subdirs = subdirsStmt.all(d.id);
+    const fileCount = noTests ? files.length : d.file_count || 0;
+    return {
+        directory: d.name,
+        fileCount,
+        symbolCount: d.symbol_count || 0,
+        fanIn: d.fan_in || 0,
+        fanOut: d.fan_out || 0,
+        cohesion: d.cohesion,
+        density: fileCount > 0 ? (d.symbol_count || 0) / fileCount : 0,
+        files: files.map((f) => ({
+            file: f.name,
+            lineCount: f.line_count || 0,
+            symbolCount: f.symbol_count || 0,
+            importCount: f.import_count || 0,
+            exportCount: f.export_count || 0,
+            fanIn: f.fan_in || 0,
+            fanOut: f.fan_out || 0,
+        })),
+        subdirectories: subdirs.map((s) => s.name),
+    };
+}
+function applyFileLimit(result, fileLimit) {
+    const totalFiles = result.reduce((sum, d) => sum + d.files.length, 0);
+    if (totalFiles <= fileLimit)
+        return null;
+    let shown = 0;
+    for (const d of result) {
+        const remaining = fileLimit - shown;
+        if (remaining <= 0) {
+            d.files = [];
+        }
+        else if (d.files.length > remaining) {
+            d.files = d.files.slice(0, remaining);
+            shown = fileLimit;
+        }
+        else {
+            shown += d.files.length;
+        }
+    }
+    const suppressed = totalFiles - fileLimit;
+    return {
+        directories: result,
+        count: result.length,
+        suppressed,
+        warning: `${suppressed} files omitted (showing ${fileLimit}/${totalFiles}). Use --full to show all files, or narrow with --directory.`,
+    };
+}
+export function structureData(customDbPath, opts = {}) {
+    const db = openReadonlyOrFail(customDbPath);
+    try {
+        const rawDir = opts.directory || null;
+        const filterDir = rawDir && normalizePath(rawDir) !== '.' ? rawDir : null;
+        const maxDepth = opts.depth || null;
+        const sortBy = opts.sort || 'files';
+        const noTests = opts.noTests || false;
+        const full = opts.full || false;
+        const fileLimit = opts.fileLimit || 25;
+        // Get all directory nodes with their metrics
+        let dirs = db
+            .prepare(`
+        SELECT n.id, n.name, n.file, nm.symbol_count, nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
+        FROM nodes n
+        LEFT JOIN node_metrics nm ON n.id = nm.node_id
+        WHERE n.kind = 'directory'
+      `)
+            .all();
+        if (filterDir) {
+            const norm = normalizePath(filterDir);
+            dirs = dirs.filter((d) => d.name === norm || d.name.startsWith(`${norm}/`));
+        }
+        if (maxDepth) {
+            const baseDepth = filterDir ? normalizePath(filterDir).split('/').length : 0;
+            dirs = dirs.filter((d) => {
+                const depth = d.name.split('/').length - baseDepth;
+                return depth <= maxDepth;
+            });
+        }
+        // Sort
+        const sortFn = getSortFn(sortBy);
+        dirs.sort(sortFn);
+        // Get file metrics for each directory
+        const filesStmt = db.prepare(`
+      SELECT n.name, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count, nm.fan_in, nm.fan_out
+      FROM edges e
+      JOIN nodes n ON e.target_id = n.id
+      LEFT JOIN node_metrics nm ON n.id = nm.node_id
+      WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'file'
+    `);
+        const subdirsStmt = db.prepare(`
+      SELECT n.name
+      FROM edges e
+      JOIN nodes n ON e.target_id = n.id
+      WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'directory'
+    `);
+        const result = dirs.map((d) => buildDirectoryEntry(d, filesStmt, subdirsStmt, noTests));
+        // Apply global file limit unless full mode
+        if (!full) {
+            const limited = applyFileLimit(result, fileLimit);
+            if (limited)
+                return limited;
+        }
+        const base = { directories: result, count: result.length };
+        return paginateResult(base, 'directories', { limit: opts.limit, offset: opts.offset });
+    }
+    finally {
+        db.close();
+    }
+}
+/** Compute density from either fileCount/symbolCount or lineCount/symbolCount. */
+function computeHotspotDensity(symbolCount, fileCount, lineCount) {
+    if ((fileCount ?? 0) > 0)
+        return (symbolCount || 0) / (fileCount ?? 1);
+    if ((lineCount ?? 0) > 0)
+        return (symbolCount || 0) / (lineCount ?? 1);
+    return 0;
+}
+/** Map a native-engine hotspot row (camelCase keys) to the public HotspotEntry shape. */
+function mapNativeHotspotRow(r) {
+    return {
+        name: r.name,
+        kind: r.kind,
+        lineCount: r.lineCount,
+        symbolCount: r.symbolCount,
+        importCount: r.importCount,
+        exportCount: r.exportCount,
+        fanIn: r.fanIn,
+        fanOut: r.fanOut,
+        cohesion: r.cohesion,
+        fileCount: r.fileCount,
+        density: computeHotspotDensity(r.symbolCount, r.fileCount, r.lineCount),
+        coupling: (r.fanIn || 0) + (r.fanOut || 0),
+    };
+}
+/** Map a JS-path hotspot row (snake_case keys from SQLite) to the public HotspotEntry shape. */
+function mapJsHotspotRow(r) {
+    return {
+        name: r.name,
+        kind: r.kind,
+        lineCount: r.line_count,
+        symbolCount: r.symbol_count,
+        importCount: r.import_count,
+        exportCount: r.export_count,
+        fanIn: r.fan_in,
+        fanOut: r.fan_out,
+        cohesion: r.cohesion,
+        fileCount: r.file_count,
+        density: computeHotspotDensity(r.symbol_count, r.file_count, r.line_count),
+        coupling: (r.fan_in || 0) + (r.fan_out || 0),
+    };
+}
+/** ORDER BY clause for each ranking dimension (strategy pattern). */
+const HOTSPOT_ORDER_BY = {
+    'fan-in': 'nm.fan_in DESC NULLS LAST',
+    'fan-out': 'nm.fan_out DESC NULLS LAST',
+    density: 'nm.symbol_count DESC NULLS LAST',
+    coupling: '(COALESCE(nm.fan_in, 0) + COALESCE(nm.fan_out, 0)) DESC NULLS LAST',
+};
+/** Build the JS-path SQL query for a given metric and test filter. */
+function buildHotspotQuery(metric, testFilter) {
+    const orderBy = HOTSPOT_ORDER_BY[metric] ?? HOTSPOT_ORDER_BY['fan-in'];
+    return `SELECT n.name, n.kind, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count,
+                 nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
+          FROM nodes n JOIN node_metrics nm ON n.id = nm.node_id
+          WHERE n.kind = ? ${testFilter} ORDER BY ${orderBy} LIMIT ?`;
+}
+export function hotspotsData(customDbPath, opts = {}) {
+    const { db, nativeDb, close } = openReadonlyWithNative(customDbPath);
+    try {
+        const metric = opts.metric || 'fan-in';
+        const level = opts.level || 'file';
+        const limit = opts.limit || 10;
+        const noTests = opts.noTests || false;
+        const kind = level === 'directory' ? 'directory' : 'file';
+        // ── Native fast path: single query instead of 4 eagerly prepared ──
+        if (nativeDb?.getHotspots) {
+            const rows = nativeDb.getHotspots(kind, metric, noTests, limit);
+            const items = rows.map(mapNativeHotspotRow);
+            const base = { metric, level, limit, items };
+            return paginateResult(base, 'items', { limit: opts.limit, offset: opts.offset });
+        }
+        // ── JS fallback ───────────────────────────────────────────────────
+        const testFilter = testFilterSQL('n.name', noTests && kind === 'file');
+        const stmt = db.prepare(buildHotspotQuery(metric, testFilter));
+        const rows = stmt.all(kind, limit);
+        const items = rows.map(mapJsHotspotRow);
+        const base = { metric, level, limit, items };
+        return paginateResult(base, 'items', { limit: opts.limit, offset: opts.offset });
+    }
+    finally {
+        close();
+    }
+}
+export function moduleBoundariesData(customDbPath, opts = {}) {
+    const db = openReadonlyOrFail(customDbPath);
+    try {
+        const config = opts.config || loadConfig();
+        const threshold = opts.threshold ??
+            config.structure
+                ?.cohesionThreshold ??
+            0.3;
+        const dirs = db
+            .prepare(`
+        SELECT n.id, n.name, nm.symbol_count, nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
+        FROM nodes n
+        JOIN node_metrics nm ON n.id = nm.node_id
+        WHERE n.kind = 'directory' AND nm.cohesion IS NOT NULL AND nm.cohesion >= ?
+        ORDER BY nm.cohesion DESC
+      `)
+            .all(threshold);
+        const modules = dirs.map((d) => {
+            // Get files inside this directory
+            const files = db
+                .prepare(`
+          SELECT n.name FROM edges e
+          JOIN nodes n ON e.target_id = n.id
+          WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'file'
+        `)
+                .all(d.id).map((f) => f.name);
+            return {
+                directory: d.name,
+                cohesion: d.cohesion,
+                fileCount: d.file_count || 0,
+                symbolCount: d.symbol_count || 0,
+                fanIn: d.fan_in || 0,
+                fanOut: d.fan_out || 0,
+                files,
+            };
+        });
+        return { threshold, modules, count: modules.length };
+    }
+    finally {
+        db.close();
+    }
+}
+// ─── Helpers ──────────────────────────────────────────────────────────
+function getSortFn(sortBy) {
+    switch (sortBy) {
+        case 'cohesion':
+            return (a, b) => (b.cohesion ?? -1) - (a.cohesion ?? -1);
+        case 'fan-in':
+            return (a, b) => (b.fan_in || 0) - (a.fan_in || 0);
+        case 'fan-out':
+            return (a, b) => (b.fan_out || 0) - (a.fan_out || 0);
+        case 'density':
+            return (a, b) => {
+                const da = (a.file_count ?? 0) > 0 ? (a.symbol_count || 0) / (a.file_count ?? 1) : 0;
+                const db_ = (b.file_count ?? 0) > 0 ? (b.symbol_count || 0) / (b.file_count ?? 1) : 0;
+                return db_ - da;
+            };
+        case 'files':
+            return (a, b) => (b.file_count || 0) - (a.file_count || 0);
+        default:
+            return (a, b) => a.name.localeCompare(b.name);
+    }
+}
+//# sourceMappingURL=structure-query.js.map

package/dist/features/structure-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure-query.js","sourceRoot":"","sources":["../../src/features/structure-query.ts"],"names":[],"mappings":"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"}

package/dist/features/structure.d.ts

@@ -0,0 +1,39 @@
+import type { BetterSqlite3Database } from '../types.js';
+interface FileSymbolData {
+    definitions: {
+        name: string;
+        kind: string;
+        line: number;
+    }[];
+    imports: unknown[];
+    exports: unknown[];
+    calls?: unknown[];
+}
+export declare function buildStructure(db: BetterSqlite3Database, fileSymbols: Map<string, FileSymbolData>, _rootDir: string, lineCountMap: Map<string, number>, directories: Set<string>, changedFiles?: string[] | null): void;
+export { FRAMEWORK_ENTRY_PREFIXES } from '../graph/classifiers/roles.js';
+interface RoleSummary {
+    entry: number;
+    core: number;
+    utility: number;
+    adapter: number;
+    dead: number;
+    'dead-leaf': number;
+    'dead-entry': number;
+    'dead-ffi': number;
+    'dead-unresolved': number;
+    'test-only': number;
+    leaf: number;
+    [key: string]: number;
+}
+/**
+ * Classify every node in the graph into a role (core, entry, utility, etc.).
+ *
+ * When `changedFiles` is provided, only nodes from those files (and their
+ * edge neighbours) are reclassified. The returned `RoleSummary` in that case
+ * reflects **only the affected subset**, not the entire graph. Callers that
+ * need graph-wide totals should perform a full classification (omit
+ * `changedFiles`) or query the DB directly.
+ */
+export declare function classifyNodeRoles(db: BetterSqlite3Database, changedFiles?: string[] | null): RoleSummary;
+export { hotspotsData, moduleBoundariesData, structureData } from './structure-query.js';
+//# sourceMappingURL=structure.d.ts.map

package/dist/features/structure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure.d.ts","sourceRoot":"","sources":["../../src/features/structure.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAQzD,UAAU,cAAc;IACtB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5D,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;CACnB;AAmXD,wBAAgB,cAAc,CAC5B,EAAE,EAAE,qBAAqB,EACzB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,EACxC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,GAC7B,IAAI,CAgDN;AAKD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAIzE,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,qBAAqB,EACzB,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,GAC7B,WAAW,CAqBb;AAulBD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}