@psnext/lscg 0.1.4 → 0.1.6

package/dist/src/graph/attribution.js

@@ -1,8 +1,8 @@
 import { spawnSync } from 'node:child_process';
 export function buildFileAttribution({ root, relativePath, source, nodes }) {
-    const blameLines = blameFile(root, relativePath);
-    if (!blameLines)
-        return null;
+    const blameResult = blameFile(root, relativePath);
+    if (blameResult.status !== 'complete')
+        return blameResult;
     const lineStarts = buildLineStarts(source);
     const contributorEmails = new Map();
     const nodeAttributions = nodes.flatMap((node) => {
@@ -10,7 +10,7 @@ export function buildFileAttribution({ root, relativePath, source, nodes }) {
         const uniqueEmails = new Set();
         let latest = null;
         for (let lineNumber = span.startLine; lineNumber <= span.endLine; lineNumber += 1) {
-            const blame = blameLines[lineNumber];
+            const blame = blameResult.blameLines[lineNumber];
             if (!blame)
                 continue;
             uniqueEmails.add(blame.email);
@@ -25,19 +25,37 @@ export function buildFileAttribution({ root, relativePath, source, nodes }) {
                 lastModifiedEmail: latest?.email ?? null
             }];
     });
+    if (contributorEmails.size === 0)
+        return { status: 'unavailable', reason: 'not_applicable' };
     return {
-        contributorEmails: [...contributorEmails.values()].sort((left, right) => left.email.localeCompare(right.email)),
-        nodeAttributions
+        status: 'complete',
+        attribution: {
+            contributorEmails: [...contributorEmails.values()].sort((left, right) => left.email.localeCompare(right.email)),
+            nodeAttributions
+        }
     };
 }
 function blameFile(root, relativePath) {
-    const result = spawnSync('git', ['-C', root, 'blame', '--follow', '--line-porcelain', '--', relativePath], {
-        encoding: 'utf8'
-    });
-    if (result.error || result.status !== 0 || !result.stdout.trim()) {
-        return null;
+    let result;
+    try {
+        result = spawnSync('git', ['-C', root, 'blame', '--follow', '--line-porcelain', '--', relativePath], {
+            encoding: 'utf8'
+        });
+    }
+    catch (error) {
+        return { status: 'failed', diagnostic: `git blame failed: ${diagnosticFor(error)}` };
     }
-    const lines = result.stdout.split(/\r?\n/);
+    if (result.error)
+        return { status: 'failed', diagnostic: `git blame failed: ${diagnosticFor(result.error)}` };
+    const stdout = typeof result.stdout === 'string' ? result.stdout : result.stdout.toString('utf8');
+    const stderr = typeof result.stderr === 'string' ? result.stderr : result.stderr.toString('utf8');
+    if (result.status !== 0) {
+        const detail = stderr.trim() || `exit status ${result.status ?? 'unknown'}`;
+        return { status: 'failed', diagnostic: `git blame failed: ${detail}` };
+    }
+    if (!stdout.trim())
+        return { status: 'unavailable', reason: 'not_applicable' };
+    const lines = stdout.split(/\r?\n/);
     const blameLines = [];
     let currentEmail = null;
     let currentTimestamp = 0;
@@ -63,7 +81,12 @@ function blameFile(root, relativePath) {
             }
         }
     }
-    return blameLines.length > 0 ? blameLines : null;
+    return blameLines.length > 0
+        ? { status: 'complete', blameLines }
+        : { status: 'unavailable', reason: 'unavailable' };
+}
+function diagnosticFor(error) {
+    return error instanceof Error ? error.message : String(error);
 }
 function isHeaderLine(line) {
     return /^[0-9a-f]{7,40} \d+ \d+(?: \d+)?$/.test(line);

package/dist/src/graph/explore.d.ts

@@ -0,0 +1,20 @@
+import type { ExploreDirection, ExploreEdgeKind, ExploreGraphResult, GraphScope } from '../types.js';
+export declare const EXPLORE_DEFAULT_DEPTH = 4;
+export declare const EXPLORE_MAX_NODES = 2000;
+export declare const EXPLORE_MAX_EDGES = 10000;
+export declare const EXPLORE_EDGE_KINDS: readonly ExploreEdgeKind[];
+export interface ExploreGraphOptions {
+    root?: string | undefined;
+    scope?: GraphScope;
+    anchor?: string | undefined;
+    file?: string | undefined;
+    search?: string | undefined;
+    direction?: ExploreDirection | undefined;
+    relationshipKinds?: readonly ExploreEdgeKind[] | undefined;
+    depth?: number | undefined;
+    nodeCap?: number | undefined;
+    edgeCap?: number | undefined;
+    candidateLimit?: number | undefined;
+}
+export declare function exploreGraph(options?: ExploreGraphOptions): ExploreGraphResult;
+//# sourceMappingURL=explore.d.ts.map

package/dist/src/graph/explore.js

@@ -0,0 +1,200 @@
+import { existsSync } from 'node:fs';
+import { databasePathForScope, normalizeScope } from '../config/paths.js';
+import { aggregateId, closeDatabase, openReadOnlyGraphDatabase, selectExploreAggregateEdges, selectExploreAggregates, selectExploreCandidates, selectExploreNode, selectExploreNodeRows, selectExploreSourcesForSearch, selectExploreTraversalEdges, selectFreshnessReport } from '../storage/database.js';
+import { repositoryForRoot } from './repository.js';
+export const EXPLORE_DEFAULT_DEPTH = 4;
+export const EXPLORE_MAX_NODES = 2_000;
+export const EXPLORE_MAX_EDGES = 10_000;
+export const EXPLORE_EDGE_KINDS = ['contains', 'defines', 'calls', 'imports', 'exports'];
+export function exploreGraph(options = {}) {
+    const repository = repositoryForRoot(options.root);
+    const scope = options.scope ?? 'repo';
+    const mode = options.anchor || options.file ? 'anchor' : 'full';
+    const request = {
+        root: repository.root,
+        scope,
+        mode,
+        ...(options.anchor ? { anchor: options.anchor.trim() } : {}),
+        ...(options.file ? { file: options.file.trim() } : {}),
+        ...(options.search ? { search: options.search.trim() } : {}),
+        direction: options.direction ?? 'both',
+        relationshipKinds: normalizeKinds(options.relationshipKinds),
+        depth: clamp(options.depth, 0, EXPLORE_DEFAULT_DEPTH, EXPLORE_DEFAULT_DEPTH),
+        nodeCap: clamp(options.nodeCap, 1, EXPLORE_MAX_NODES, EXPLORE_MAX_NODES),
+        edgeCap: clamp(options.edgeCap, 1, EXPLORE_MAX_EDGES, EXPLORE_MAX_EDGES),
+        candidateLimit: clamp(options.candidateLimit, 1, 100, 20)
+    };
+    const scopes = normalizeScope(scope);
+    return {
+        contract_version: 1,
+        repository,
+        request,
+        scopes: scopes.map((graphScope) => exploreScope(repository, graphScope, request))
+    };
+}
+function exploreScope(repository, graphScope, request) {
+    const databasePath = databasePathForScope(graphScope, repository.root);
+    if (!existsSync(databasePath))
+        return emptyScope(graphScope, databasePath, request, missingFreshness(databasePath));
+    let db;
+    try {
+        db = openReadOnlyGraphDatabase(databasePath);
+    }
+    catch (error) {
+        return emptyScope(graphScope, databasePath, request, {
+            state: 'unavailable', reason: 'unavailable_storage', message: `Explore storage is unavailable: ${diagnostic(error)}`,
+            recovery: 'Run lscg scan explicitly, then retry Explore.'
+        });
+    }
+    try {
+        const persistedFreshness = selectFreshnessReport(db, repository.id);
+        const freshness = freshnessFor(persistedFreshness);
+        if (request.mode === 'full')
+            return fullScope(db, repository, graphScope, databasePath, request, freshness);
+        return anchorScope(db, repository, graphScope, databasePath, request, freshness);
+    }
+    finally {
+        closeDatabase(db);
+    }
+}
+function fullScope(db, repository, scope, databasePath, request, freshness) {
+    const allAggregates = selectExploreAggregates(db, repository.id);
+    let searchState = { term: request.search ?? null, matchedNodeIds: [], containingAggregateIds: [] };
+    let aggregates = allAggregates;
+    let matchingSources = [];
+    if (request.search?.trim()) {
+        const normalized = request.search.trim().toLocaleLowerCase();
+        matchingSources = selectExploreSourcesForSearch(db, repository.id, request.search, 200);
+        const matchedNodeIds = matchingSources.map((row) => row.id);
+        const containingAggregateIds = [...new Set(matchingSources.flatMap((row) => row.fileId ? [aggregateId(repository.id, row.fileId)] : []))];
+        const matchingFiles = new Set(containingAggregateIds);
+        aggregates = allAggregates.filter((row) => matchingFiles.has(row.id) || row.path.toLocaleLowerCase().includes(normalized));
+        searchState = { term: request.search.trim(), matchedNodeIds, containingAggregateIds };
+    }
+    const aggregateNodes = aggregates.map((row) => aggregateNode(row, repository.id, scope));
+    const nodes = [...aggregateNodes, ...matchingSources.map((row) => sourceNode(row, repository.id, scope))];
+    const aggregateIds = new Set(aggregateNodes.map((node) => node.id));
+    const edges = selectExploreAggregateEdges(db, repository.id, request.relationshipKinds)
+        .filter((edge) => aggregateIds.has(edge.sourceAggregateId) && aggregateIds.has(edge.targetAggregateId))
+        .map((edge) => ({ id: edge.id, sourceId: edge.sourceAggregateId, targetId: edge.targetAggregateId, kind: edge.kind, confidence: edge.confidence, direction: 'forward', metadata: edge.metadata, count: edge.count, expansionKey: `aggregate-expand:${edge.sourceAggregateId}:${edge.targetAggregateId}:${edge.kind}` }));
+    const state = nodes.length > 0 ? 'ok' : 'empty';
+    return {
+        scope, databasePath, freshness, state, mode: 'full', nodes, edges,
+        search: searchState, filters: { direction: request.direction, relationshipKinds: [...request.relationshipKinds] },
+        truncation: noTruncation(request.nodeCap, request.edgeCap), expansionTargets: nodes.filter((node) => node.category === 'aggregate' && node.expandable).map((node) => node.expansionKey), warnings: freshnessWarnings(freshness)
+    };
+}
+function anchorScope(db, repository, scope, databasePath, request, freshness) {
+    const term = request.file ?? request.anchor ?? '';
+    const candidates = selectExploreCandidates(db, repository.id, term, { fileAnchor: Boolean(request.file), limit: request.candidateLimit });
+    const candidateContract = candidates.map(candidateContractFromRow);
+    const base = {
+        scope, databasePath, freshness, mode: 'anchor',
+        search: { term: null, matchedNodeIds: [], containingAggregateIds: [] },
+        filters: { direction: request.direction, relationshipKinds: [...request.relationshipKinds] },
+        expansionTargets: [], warnings: freshnessWarnings(freshness)
+    };
+    if (candidates.length === 0)
+        return { ...base, state: 'not_found', nodes: [], edges: [], candidates: [], truncation: noTruncation(request.nodeCap, request.edgeCap) };
+    if (candidates.length !== 1)
+        return { ...base, state: 'ambiguous', nodes: [], edges: [], candidates: candidateContract, truncation: noTruncation(request.nodeCap, request.edgeCap), warnings: [...base.warnings, 'Select one ranked candidate before traversal.'] };
+    const selected = candidates[0];
+    if (selected.kind === 'file' && selected.aggregateId) {
+        const aggregate = selectExploreAggregates(db, repository.id).find((row) => row.id === selected.aggregateId);
+        const node = aggregate ? aggregateNode(aggregate, repository.id, scope) : null;
+        return { ...base, state: node ? 'ok' : 'not_found', nodes: node ? [node] : [], edges: [], ...(node ? { anchor: node } : {}), candidates: candidateContract, expansionTargets: node ? [node.expansionKey] : [], truncation: noTruncation(request.nodeCap, request.edgeCap) };
+    }
+    const anchor = selectExploreNode(db, repository.id, selected.id);
+    if (!anchor)
+        return { ...base, state: 'not_found', nodes: [], edges: [], candidates: candidateContract, truncation: noTruncation(request.nodeCap, request.edgeCap) };
+    const traversal = traverse(db, repository.id, anchor, request);
+    const nodes = traversal.nodes.map((row) => sourceNode(row, repository.id, scope));
+    const anchorNode = nodes.find((node) => node.category === 'source' && node.id === anchor.id) ?? sourceNode(anchor, repository.id, scope);
+    return {
+        ...base, state: 'ok', nodes, edges: traversal.edges.map((edge) => edgeContract(edge, traversal.nodeIds)), anchor: anchorNode, candidates: candidateContract,
+        truncation: traversal.truncation, expansionTargets: [anchorNode.expansionKey ?? `node-expand:${anchorNode.id}`]
+    };
+}
+function traverse(db, repositoryId, anchor, request) {
+    const nodeIds = new Set([anchor.id]);
+    const allEdges = new Map();
+    let frontier = [anchor.id];
+    let omittedNodes = 0;
+    let omittedEdges = 0;
+    let deepestDepth = 0;
+    for (let depth = 1; depth <= request.depth && frontier.length > 0; depth += 1) {
+        const rows = selectExploreTraversalEdges(db, repositoryId, frontier, request.direction, request.relationshipKinds, request.edgeCap - allEdges.size + 1);
+        if (rows.length > request.edgeCap - allEdges.size)
+            omittedEdges += rows.length - Math.max(0, request.edgeCap - allEdges.size);
+        const uniqueRows = rows.filter((row) => !allEdges.has(row.id));
+        const adjacentIds = [...new Set(uniqueRows.flatMap((row) => adjacentFor(row, frontier, request.direction)))].filter((id) => !nodeIds.has(id));
+        const adjacentRows = selectExploreNodeRowsBounded(db, repositoryId, adjacentIds);
+        adjacentRows.sort(nodeOrder);
+        const available = Math.max(0, request.nodeCap - nodeIds.size);
+        const retained = adjacentRows.slice(0, available);
+        omittedNodes += Math.max(0, adjacentRows.length - retained.length);
+        for (const row of retained)
+            nodeIds.add(row.id);
+        const retainedIds = new Set(retained.map((row) => row.id));
+        for (const row of uniqueRows) {
+            if (allEdges.size >= request.edgeCap) {
+                omittedEdges += 1;
+                continue;
+            }
+            if (nodeIds.has(row.sourceId) && nodeIds.has(row.targetId))
+                allEdges.set(row.id, row);
+            else if (retainedIds.has(row.sourceId) || retainedIds.has(row.targetId))
+                omittedEdges += 1;
+        }
+        const next = retained.map((row) => row.id);
+        if (next.length === 0)
+            break;
+        frontier = next;
+        deepestDepth = depth;
+    }
+    const rows = selectExploreNodeRowsBounded(db, repositoryId, [...nodeIds]);
+    rows.sort(nodeOrder);
+    return { nodes: rows, nodeIds, edges: [...allEdges.values()], truncation: { bounded: omittedNodes > 0 || omittedEdges > 0, nodeCap: request.nodeCap, edgeCap: request.edgeCap, omittedNodes, omittedEdges, deepestDepth } };
+}
+function adjacentFor(row, frontier, direction) {
+    const hasSource = frontier.includes(row.sourceId);
+    const hasTarget = frontier.includes(row.targetId);
+    if (direction === 'incoming')
+        return hasTarget ? [row.sourceId] : [];
+    if (direction === 'outgoing')
+        return hasSource ? [row.targetId] : [];
+    return [...(hasSource ? [row.targetId] : []), ...(hasTarget ? [row.sourceId] : [])];
+}
+function edgeContract(edge, nodeIds) {
+    return { id: edge.id, sourceId: edge.sourceId, targetId: edge.targetId, kind: edge.kind, confidence: edge.confidence, direction: 'forward', metadata: edge.metadata };
+}
+function selectExploreNodeRowsBounded(db, repositoryId, ids) {
+    const rows = [];
+    for (let index = 0; index < ids.length; index += 500)
+        rows.push(...selectExploreNodeRows(db, repositoryId, ids.slice(index, index + 500)));
+    return rows;
+}
+function aggregateNode(row, repositoryId, scope) {
+    return { id: row.id, category: 'aggregate', kind: 'file', name: row.path, identity: { repositoryId, scope, path: row.path, qualifiedName: row.path }, path: row.path, language: row.language, expandable: row.childCount > 0, expansionKey: `aggregate-expand:${row.id}`, childCount: row.childCount };
+}
+function sourceNode(row, repositoryId, scope) {
+    return { id: row.id, category: 'source', kind: row.kind, type: row.type, name: row.name, identity: { repositoryId, scope, path: row.path, qualifiedName: row.name && row.path ? `${row.path}:${row.name}` : row.name }, path: row.path, span: { start: row.startPoint, end: row.endPoint }, metadata: row.metadata, ...(row.fileId ? { expansionKey: `aggregate-expand:${aggregateId(repositoryId, row.fileId)}` } : {}) };
+}
+function candidateContractFromRow(row) {
+    return { id: row.id, rank: row.rank, match: row.match, category: row.aggregateId && row.id === row.aggregateId ? 'aggregate' : 'source', kind: row.kind, name: row.name, qualifiedName: row.qualifiedName, path: row.path, ...(row.kind === 'file' ? {} : { span: { start: row.startPoint, end: row.endPoint } }) };
+}
+function freshnessFor(report) {
+    const message = report.state === 'fresh' ? 'Stored graph is fresh.' : report.state === 'degraded' ? 'Stored graph is degraded; some scan facts were retained.' : 'Stored graph is stale; Explore does not scan implicitly.';
+    return report.state === 'fresh'
+        ? { state: report.state, ...(report.reason ? { reason: report.reason } : {}), message }
+        : { state: report.state, ...(report.reason ? { reason: report.reason } : {}), message, recovery: 'Run lscg scan explicitly to refresh the stored graph.' };
+}
+function missingFreshness(databasePath) { return { state: 'missing', reason: 'missing_database', message: `No stored graph was found at ${databasePath}.`, recovery: 'Run lscg scan explicitly, then retry Explore.' }; }
+function freshnessWarnings(freshness) { return freshness.state === 'fresh' ? [] : [freshness.message, ...(freshness.recovery ? [freshness.recovery] : [])]; }
+function noTruncation(nodeCap, edgeCap) { return { bounded: false, nodeCap, edgeCap, omittedNodes: 0, omittedEdges: 0, deepestDepth: 0 }; }
+function emptyScope(scope, databasePath, request, freshness) { return { scope, databasePath, freshness, state: 'empty', mode: request.mode, nodes: [], edges: [], search: { term: request.search ?? null, matchedNodeIds: [], containingAggregateIds: [] }, filters: { direction: request.direction, relationshipKinds: [...request.relationshipKinds] }, truncation: noTruncation(request.nodeCap, request.edgeCap), expansionTargets: [], warnings: freshnessWarnings(freshness) }; }
+function normalizeKinds(kinds) { return [...new Set((kinds ?? EXPLORE_EDGE_KINDS).filter((kind) => EXPLORE_EDGE_KINDS.includes(kind)))]; }
+function clamp(value, min, max, fallback) { return value === undefined || !Number.isFinite(value) ? fallback : Math.max(min, Math.min(max, Math.trunc(value))); }
+function nodeOrder(a, b) { return `${a.path ?? ''}:${a.name ?? ''}:${a.id}`.localeCompare(`${b.path ?? ''}:${b.name ?? ''}:${b.id}`); }
+function diagnostic(error) { return error instanceof Error ? error.message : String(error); }
+//# sourceMappingURL=explore.js.map

package/dist/src/graph/repository.d.ts

@@ -1,4 +1,4 @@
-import type { GraphEdgeRow, GraphNodeRow, GraphNodeTextRow, NeighborRow, CallGraphMatch, RepositoryRecord, ScanSummary, StatusResult, StorageScope, ContextGraphResult } from '../types.js';
+import type { EnrichmentRunner, EnrichmentSummary, GraphEdgeRow, GraphNodeRow, GraphNodeTextRow, NeighborRow, CallGraphMatch, RepositoryRecord, ScanSummary, StatusResult, StorageScope, ContextGraphResult, FreshnessReport, ProgressReporter } from '../types.js';
 import { type PluginResourceLimits, type ScannerPlugin } from '../scanner/plugins.js';
 export declare function repositoryForRoot(root?: string | undefined): RepositoryRecord;
 export declare function initGraph({ root, scope }?: {
@@ -11,12 +11,37 @@ export declare function initGraph({ root, scope }?: {
         databasePath: string;
     }>;
 };
-export declare function scanRepository({ root, scope, plugins, pluginLimits }?: {
+export interface ScanRepositoryOptions {
     root?: string | undefined;
     scope?: StorageScope | 'both' | undefined;
     plugins?: readonly ScannerPlugin[] | undefined;
+    /** Enables the bundled Git attribution enrichment plugin. */
+    attribution?: boolean | undefined;
     pluginLimits?: Partial<PluginResourceLimits> | undefined;
-}): Promise<ScanSummary>;
+    full?: boolean | undefined;
+    enrichmentRunner?: EnrichmentRunner | undefined;
+    progress?: ProgressReporter | undefined;
+    /** Internal attempt label used by the Full Scan stabilization loop. */
+    attempt?: number | undefined;
+}
+/**
+ * A full scan must not report success with hash-incompatible enrichment work.
+ * Rebuild and drain again when a source changes while attribution is running.
+ */
+export declare function scanRepository(options?: ScanRepositoryOptions): Promise<ScanSummary>;
+export declare const defaultEnrichmentRunner: EnrichmentRunner;
+export interface DrainRepositoryEnrichmentOptions {
+    root?: string | undefined;
+    scope?: StorageScope | 'both' | undefined;
+    enrichmentRunner?: EnrichmentRunner | undefined;
+    pluginName?: string | undefined;
+    historyFingerprint?: string | null | undefined;
+}
+/**
+ * Drains persisted, hash-compatible attribution work. This is deliberately
+ * explicit: one-shot structural scans persist work but never start it.
+ */
+export declare function drainRepositoryEnrichment({ root, scope, enrichmentRunner, pluginName, historyFingerprint }?: DrainRepositoryEnrichmentOptions): Promise<EnrichmentSummary>;
 export declare function graphStatus({ root, scope }?: {
     root?: string | undefined;
     scope?: StorageScope | 'both' | undefined;
@@ -31,6 +56,7 @@ export declare function listNodes({ root, scope, kind, limit }?: {
     limit?: number | undefined;
 }): Array<{
     scope: StorageScope;
+    freshness: FreshnessReport;
 } & GraphNodeRow>;
 export declare function listNodeText({ root, scope, kind, term, limit }?: {
     root?: string | undefined;
@@ -41,14 +67,17 @@ export declare function listNodeText({ root, scope, kind, term, limit }?: {
 }): Array<{
     scope: StorageScope;
     root: string;
+    freshness: FreshnessReport;
 } & GraphNodeTextRow>;
-export declare function listEdges({ root, scope, kind, limit }?: {
+export declare function listEdges({ root, scope, kind, type, limit }?: {
     root?: string | undefined;
     scope?: StorageScope | 'both' | undefined;
     kind?: string | undefined;
+    type?: string | undefined;
     limit?: number | undefined;
 }): Array<{
     scope: StorageScope;
+    freshness: FreshnessReport;
 } & GraphEdgeRow>;
 export declare function neighbors({ root, scope, nodeId, depth, limit }?: {
     root?: string | undefined;
@@ -58,6 +87,7 @@ export declare function neighbors({ root, scope, nodeId, depth, limit }?: {
     limit?: number | undefined;
 }): Array<{
     scope: StorageScope;
+    freshness: FreshnessReport;
 } & NeighborRow>;
 export declare function callGraph({ root, scope, term, kind, depth, limit }?: {
     root?: string | undefined;
@@ -68,6 +98,7 @@ export declare function callGraph({ root, scope, term, kind, depth, limit }?: {
     limit?: number | undefined;
 }): Array<{
     scope: StorageScope;
+    freshness: FreshnessReport;
 } & CallGraphMatch>;
 export interface ContextGraphOptions {
     root?: string | undefined;
@@ -92,5 +123,6 @@ export declare function runReadOnlySql({ root, scope, sql, attachHome, limit }?:
 }): Array<{
     scope: StorageScope;
     rows: unknown[];
+    freshness: FreshnessReport;
 }>;
 //# sourceMappingURL=repository.d.ts.map