@psnext/lscg 0.1.1

package/dist/src/view/render.js

@@ -0,0 +1,321 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function renderSvgMarkup(model, options = {}) {
+    const nodes = options.includeHiddenNodes ? model.fullNodes : model.nodes;
+    const edges = options.includeHiddenNodes ? model.fullEdges : model.edges;
+    const baseViewBox = options.includeHiddenNodes ? model.fullInitialViewBox : model.initialViewBox;
+    const nodePresentations = nodes.map((node) => ({
+        node,
+        presentation: nodePresentation(node)
+    }));
+    const viewBox = expandViewBox(baseViewBox, Math.max(64, ...nodePresentations.map(({ presentation }) => presentation.padding)));
+    const width = Math.max(Math.round(viewBox.width), 1);
+    const height = Math.max(Math.round(viewBox.height), 1);
+    const graphLabel = `${model.repository.name} store graph`;
+    const title = options.includeHiddenNodes ? `${graphLabel} · full graph` : graphLabel;
+    const mode = options.interactive ? 'interactive' : 'snapshot';
+    const renderedEdges = edges
+        .map((edge) => {
+        const source = nodes.find((node) => node.id === edge.sourceId);
+        const target = nodes.find((node) => node.id === edge.targetId);
+        if (!source || !target)
+            return '';
+        return `
+      <line class="edge edge--${escapeHtml(edge.kind)}" x1="${formatNumber(source.x)}" y1="${formatNumber(source.y)}" x2="${formatNumber(target.x)}" y2="${formatNumber(target.y)}" marker-end="url(#arrow-${mode})" />`;
+    })
+        .join('');
+    const renderedNodes = nodes
+        .map((node) => {
+        const presentation = nodePresentation(node);
+        const labelY = node.kind === 'file' ? 0 : presentation.height / 2 + 14;
+        return `
+      <g class="node node--${escapeHtml(node.kind)}" data-node-id="${escapeHtml(node.id)}" data-node-kind="${escapeHtml(node.kind)}" data-node-shape="${escapeHtml(presentation.shape)}" transform="translate(${formatNumber(node.x)},${formatNumber(node.y)})">
+        ${renderNodeShapeMarkup(node, presentation)}
+        <text class="node-label" text-anchor="middle" dominant-baseline="${node.kind === 'file' ? 'middle' : 'hanging'}" y="${formatNumber(labelY)}">${escapeHtml(node.label)}</text>
+        <title>${escapeHtml(node.label)} (${escapeHtml(node.id)})</title>
+      </g>`;
+    })
+        .join('');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="${formatNumber(viewBox.x)} ${formatNumber(viewBox.y)} ${formatNumber(viewBox.width)} ${formatNumber(viewBox.height)}" width="${width}" height="${height}" role="img" aria-labelledby="title desc">
+  <title id="title">${escapeHtml(title)}</title>
+  <desc id="desc">${escapeHtml(`Force-directed graph for ${model.repository.name} in ${model.scope} scope.`)}</desc>
+  <defs>
+    <marker id="arrow-${mode}" viewBox="0 0 10 10" refX="7.5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#94a3b8" />
+    </marker>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="1" stdDeviation="1.5" flood-color="#0f172a" flood-opacity="0.18" />
+    </filter>
+  </defs>
+  <style>
+    :root { color-scheme: dark; }
+    svg { background: #020617; }
+    .edge { stroke: #64748b; stroke-opacity: 0.5; stroke-width: 1.25; }
+    .edge--imports { stroke: #f59e0b; }
+    .edge--exports { stroke: #a855f7; }
+    .edge--calls { stroke: #fb7185; }
+    .edge--defines { stroke: #22c55e; }
+    .edge--contains { stroke: #38bdf8; }
+    .node { filter: url(#shadow); }
+    .node-shape { stroke: #e2e8f0; stroke-opacity: 0.12; stroke-width: 1.5; shape-rendering: geometricPrecision; }
+    .node-label { fill: #e2e8f0; font: 11px/1.4 ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; font-weight: 600; paint-order: stroke; stroke: #020617; stroke-width: 3px; stroke-linejoin: round; }
+  </style>
+  <g class="edges">${renderedEdges}
+  </g>
+  <g class="nodes">${renderedNodes}
+  </g>
+</svg>`;
+}
+const interactiveHtmlTemplate = loadTemplateAsset('interactive.html');
+const interactiveCss = loadTemplateAsset('interactive.css');
+export function renderInteractiveHtml(model) {
+    const data = serializeInteractiveGraph(model);
+    const graphTitle = `${model.repository.name} store graph`;
+    const subtitle = model.anchorNodeId
+        ? `Anchored on ${model.nodes.find((node) => node.id === model.anchorNodeId)?.label ?? model.anchorNodeId}`
+        : 'Showing entire graph';
+    const searchTerm = escapeHtml(model.search ?? '');
+    return interactiveHtmlTemplate
+        .replace('{{CSS}}', interactiveCss)
+        .replaceAll('{{GRAPH_TITLE}}', escapeHtml(graphTitle))
+        .replace('{{SUBTITLE}}', escapeHtml(subtitle))
+        .replace('{{LEGEND_ITEMS}}', legendItems())
+        .replace('{{DATA}}', data)
+        .replace('{{SEARCH_TERM}}', searchTerm);
+}
+function loadTemplateAsset(name) {
+    const currentFileDir = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        path.resolve(currentFileDir, 'templates', name),
+        path.resolve(currentFileDir, '../../../src/view/templates', name),
+        path.resolve(process.cwd(), 'src/view/templates', name)
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return readFileSync(candidate, 'utf8');
+        }
+    }
+    throw new Error(`Missing view template asset ${name}. Looked in: ${candidates.join(', ')}`);
+}
+export function writeSvgSnapshot(filePath, svgMarkup) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    writeFileSync(filePath, svgMarkup, 'utf8');
+}
+function serializeInteractiveGraph(model) {
+    const nodes = model.fullNodes.map((node) => {
+        const presentation = nodePresentation(node);
+        return {
+            id: node.id,
+            kind: node.kind,
+            type: node.type,
+            name: node.name,
+            label: node.label,
+            degree: node.degree,
+            x: node.x,
+            y: node.y,
+            color: colorForKind(node.kind),
+            shape: presentation.shape,
+            width: presentation.width,
+            height: presentation.height,
+            presentationRadius: presentation.presentationRadius
+        };
+    });
+    const edges = model.fullEdges.map((edge) => ({
+        id: edge.id,
+        kind: edge.kind,
+        source: edge.sourceId,
+        target: edge.targetId,
+        confidence: edge.confidence,
+        metadataJson: edge.metadataJson
+    }));
+    return escapeJson(JSON.stringify({
+        repository: model.repository,
+        scope: model.scope,
+        search: model.search,
+        anchorNodeId: model.anchorNodeId,
+        fullNeighborhoods: model.fullNeighborhoods,
+        nodes,
+        edges
+    }));
+}
+function renderNodeShapeMarkup(node, presentation) {
+    const fill = colorForKind(node.kind);
+    switch (presentation.shape) {
+        case 'rounded-rect':
+            return `<rect class="node-shape node-shape--rounded-rect" x="${formatNumber(-presentation.width / 2)}" y="${formatNumber(-presentation.height / 2)}" width="${formatNumber(presentation.width)}" height="${formatNumber(presentation.height)}" rx="10" ry="10" fill="${fill}" />`;
+        case 'box':
+            return `<rect class="node-shape node-shape--box" x="${formatNumber(-presentation.width / 2)}" y="${formatNumber(-presentation.height / 2)}" width="${formatNumber(presentation.width)}" height="${formatNumber(presentation.height)}" rx="4" ry="4" fill="${fill}" />`;
+        case 'ellipse':
+            return `<ellipse class="node-shape node-shape--ellipse" cx="0" cy="0" rx="${formatNumber(presentation.width / 2)}" ry="${formatNumber(presentation.height / 2)}" fill="${fill}" />`;
+        case 'diamond':
+            return `<polygon class="node-shape node-shape--diamond" points="${shapePoints(presentation, 'diamond')}" fill="${fill}" />`;
+        case 'hexagon':
+            return `<polygon class="node-shape node-shape--hexagon" points="${shapePoints(presentation, 'hexagon')}" fill="${fill}" />`;
+        case 'user':
+            return renderUserNodeShapeMarkup(presentation, fill);
+        default:
+            return `<rect class="node-shape" x="${formatNumber(-presentation.width / 2)}" y="${formatNumber(-presentation.height / 2)}" width="${formatNumber(presentation.width)}" height="${formatNumber(presentation.height)}" rx="6" ry="6" fill="${fill}" />`;
+    }
+}
+function shapePoints(presentation, shape) {
+    const halfWidth = presentation.width / 2;
+    const halfHeight = presentation.height / 2;
+    if (shape === 'diamond') {
+        return `${formatNumber(0)},${formatNumber(-halfHeight)} ${formatNumber(halfWidth)},${formatNumber(0)} ${formatNumber(0)},${formatNumber(halfHeight)} ${formatNumber(-halfWidth)},${formatNumber(0)}`;
+    }
+    const inset = Math.min(halfWidth * 0.35, halfHeight * 0.9);
+    return `${formatNumber(-halfWidth + inset)},${formatNumber(-halfHeight)} ${formatNumber(halfWidth - inset)},${formatNumber(-halfHeight)} ${formatNumber(halfWidth)},${formatNumber(0)} ${formatNumber(halfWidth - inset)},${formatNumber(halfHeight)} ${formatNumber(-halfWidth + inset)},${formatNumber(halfHeight)} ${formatNumber(-halfWidth)},${formatNumber(0)}`;
+}
+function nodePresentation(node) {
+    const labelLength = Math.max(node.label.length, 1);
+    const shape = shapeForKind(node.kind);
+    const width = node.kind === 'file'
+        ? shapeWidthForKind(node.kind, labelLength)
+        : node.kind === 'user'
+            ? 72
+            : 16;
+    const height = node.kind === 'file'
+        ? shapeHeightForKind(node.kind, labelLength)
+        : node.kind === 'user'
+            ? 72
+            : 16;
+    const presentationRadius = Math.max(width, height) / 2 + 10;
+    return {
+        shape,
+        width,
+        height,
+        presentationRadius,
+        padding: Math.ceil(presentationRadius + 24)
+    };
+}
+function shapeForKind(kind) {
+    switch (kind) {
+        case 'file':
+            return 'rounded-rect';
+        case 'symbol':
+            return 'box';
+        case 'import':
+            return 'ellipse';
+        case 'export':
+            return 'diamond';
+        case 'call':
+            return 'hexagon';
+        case 'user':
+            return 'user';
+        default:
+            return 'box';
+    }
+}
+function shapeWidthForKind(kind, labelLength) {
+    if (kind === 'file') {
+        return Math.max(32, Math.min(320, Math.round(32 + labelLength * 7.8)));
+    }
+    return shapeSquareSizeForKind(kind, labelLength);
+}
+function shapeHeightForKind(kind, labelLength) {
+    if (kind === 'file') {
+        return 36;
+    }
+    return shapeSquareSizeForKind(kind, labelLength ?? 1);
+}
+function shapeSquareSizeForKind(kind, labelLength) {
+    const sizeByKind = {
+        symbol: { base: 64, perChar: 7, min: 96, max: 220 },
+        import: { base: 68, perChar: 7, min: 96, max: 220 },
+        export: { base: 68, perChar: 7, min: 96, max: 220 },
+        call: { base: 68, perChar: 7, min: 96, max: 220 },
+        user: { base: 68, perChar: 7, min: 72, max: 180 }
+    };
+    const spec = sizeByKind[kind];
+    return Math.max(spec.min, Math.min(spec.max, Math.round(spec.base + labelLength * spec.perChar)));
+}
+function expandViewBox(viewBox, padding) {
+    return {
+        x: viewBox.x - padding,
+        y: viewBox.y - padding,
+        width: viewBox.width + padding * 2,
+        height: viewBox.height + padding * 2
+    };
+}
+function renderUserNodeShapeMarkup(presentation, fill) {
+    const scale = Math.max(presentation.width, presentation.height) / 24;
+    return `<g class="node-shape node-shape--user" transform="scale(${formatNumber(scale)}) translate(-12,-12)" fill="none" stroke="${fill}" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+    <circle cx="12" cy="9" r="3" />
+    <circle cx="12" cy="12" r="10" />
+    <path d="M17.9691 20C17.81 17.1085 16.9247 15 11.9999 15C7.07521 15 6.18991 17.1085 6.03076 20" />
+  </g>`;
+}
+function colorForKind(kind) {
+    switch (kind) {
+        case 'file':
+            return '#38bdf8';
+        case 'symbol':
+            return '#22c55e';
+        case 'import':
+            return '#f59e0b';
+        case 'export':
+            return '#a855f7';
+        case 'call':
+            return '#fb7185';
+        case 'user':
+            return '#14b8a6';
+        default:
+            return '#94a3b8';
+    }
+}
+function escapeHtml(str) {
+    return str.replace(/[&<>"']/g, (match) => {
+        switch (match) {
+            case '&':
+                return '&amp;';
+            case '<':
+                return '&lt;';
+            case '>':
+                return '&gt;';
+            case '"':
+                return '&quot;';
+            case "'":
+                return '&#39;';
+            default:
+                return match;
+        }
+    });
+}
+function escapeJson(value) {
+    return value.replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+}
+function formatNumber(value) {
+    return Number.isFinite(value) ? Number(value.toFixed(2)).toString() : '0';
+}
+function legendItems() {
+    const items = [
+        ['file', 'File'],
+        ['symbol', 'Symbol'],
+        ['import', 'Import'],
+        ['export', 'Export'],
+        ['call', 'Call'],
+        ['user', 'Contributor']
+    ];
+    return items
+        .map(([kind, label]) => `
+          <button class="legend-toggle" type="button" data-kind-toggle="${escapeHtml(kind)}" aria-pressed="true">
+            ${legendIconMarkup(kind)}
+            <span>${escapeHtml(label)}</span>
+          </button>`)
+        .join('\n');
+}
+function legendIconMarkup(kind) {
+    if (kind === 'user') {
+        return `<span class="legend-icon legend-icon--user" aria-hidden="true">
+      <svg viewBox="0 0 24 24" fill="none" role="presentation" focusable="false" aria-hidden="true">
+        <circle cx="12" cy="9" r="3" stroke="currentColor" stroke-width="1.5" />
+        <circle cx="12" cy="12" r="10" stroke="currentColor" stroke-width="1.5" />
+        <path d="M17.9691 20C17.81 17.1085 16.9247 15 11.9999 15C7.07521 15 6.18991 17.1085 6.03076 20" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
+      </svg>
+    </span>`;
+    }
+    return `<span class="legend-swatch" aria-hidden="true" style="background:${colorForKind(kind)}"></span>`;
+}
+//# sourceMappingURL=render.js.map

package/dist/src/watch.d.ts

@@ -0,0 +1,40 @@
+import { scanRepository } from './graph/repository.js';
+import type { RepositoryRecord, StorageScope } from './types.js';
+export interface WatchCommandOptions {
+    root?: string | undefined;
+    scope?: StorageScope | 'both' | undefined;
+    intervalMs?: number | undefined;
+}
+export interface WatchSummary {
+    filesDiscovered: number;
+    filesScanned: number;
+    nodesWritten: number;
+    edgesWritten: number;
+    skippedCount: number;
+}
+export interface WatchEvent {
+    event: 'watching' | 'scan' | 'waiting' | 'rescan-triggered' | 'stopped';
+    mode?: 'watch' | 'scan --watch' | undefined;
+    phase?: 'initial' | 'rescan' | undefined;
+    reason?: 'file-change' | 'follow-up' | undefined;
+    repository: RepositoryRecord;
+    scope: StorageScope;
+    summary?: WatchSummary | undefined;
+    scans?: number | undefined;
+}
+export interface WatchDependencies {
+    scanRepository?: typeof scanRepository | undefined;
+    fingerprint?: ((root: string) => Promise<string> | string) | undefined;
+    emit?: ((event: WatchEvent) => void) | undefined;
+    wait?: ((ms: number, signal?: AbortSignal) => Promise<void>) | undefined;
+    signal?: AbortSignal | undefined;
+    mode?: 'watch' | 'scan --watch' | undefined;
+}
+export interface WatchRunResult {
+    repository: RepositoryRecord;
+    scope: StorageScope;
+    scans: number;
+    stopped: boolean;
+}
+export declare function watchRepository(options?: WatchCommandOptions, dependencies?: WatchDependencies): Promise<WatchRunResult>;
+//# sourceMappingURL=watch.d.ts.map

package/dist/src/watch.js

@@ -0,0 +1,118 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { repositoryForRoot, scanRepository } from './graph/repository.js';
+import { collectRepositoryFingerprint } from './scanner/fingerprint.js';
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+export async function watchRepository(options = {}, dependencies = {}) {
+    const scope = resolveWatchScope(options.scope);
+    const repository = repositoryForRoot(options.root);
+    const scanFn = dependencies.scanRepository ?? scanRepository;
+    const fingerprintFn = dependencies.fingerprint ?? ((root) => collectRepositoryFingerprint(root));
+    const emit = dependencies.emit ?? defaultEmit;
+    const wait = dependencies.wait ?? defaultWait;
+    const signal = dependencies.signal;
+    const mode = dependencies.mode ?? 'watch';
+    const intervalMs = options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    let scans = 0;
+    let stopped = false;
+    let currentFingerprint = await fingerprintFn(repository.root);
+    emit({
+        event: 'watching',
+        mode,
+        repository,
+        scope
+    });
+    try {
+        while (!signal?.aborted) {
+            const scanStartFingerprint = currentFingerprint;
+            const summary = await scanFn({ root: repository.root, scope });
+            scans += 1;
+            emit({
+                event: 'scan',
+                mode,
+                phase: scans === 1 ? 'initial' : 'rescan',
+                repository,
+                scope,
+                summary: summarizeScan(summary)
+            });
+            const scanEndFingerprint = await fingerprintFn(repository.root);
+            currentFingerprint = scanEndFingerprint;
+            if (signal?.aborted)
+                break;
+            if (scanEndFingerprint !== scanStartFingerprint) {
+                emit({
+                    event: 'rescan-triggered',
+                    mode,
+                    reason: 'follow-up',
+                    repository,
+                    scope
+                });
+                continue;
+            }
+            emit({
+                event: 'waiting',
+                mode,
+                repository,
+                scope
+            });
+            while (!signal?.aborted) {
+                await wait(intervalMs, signal);
+                const nextFingerprint = await fingerprintFn(repository.root);
+                if (nextFingerprint !== currentFingerprint) {
+                    currentFingerprint = nextFingerprint;
+                    emit({
+                        event: 'rescan-triggered',
+                        mode,
+                        reason: 'file-change',
+                        repository,
+                        scope
+                    });
+                    break;
+                }
+            }
+        }
+    }
+    finally {
+        stopped = true;
+        emit({
+            event: 'stopped',
+            mode,
+            repository,
+            scope,
+            scans
+        });
+    }
+    return {
+        repository,
+        scope,
+        scans,
+        stopped
+    };
+}
+function resolveWatchScope(scope) {
+    if (scope === undefined || scope === 'repo')
+        return 'repo';
+    throw new Error('watch mode supports repo scope only');
+}
+function summarizeScan(summary) {
+    return {
+        filesDiscovered: summary.filesDiscovered,
+        filesScanned: summary.filesScanned,
+        nodesWritten: summary.nodesWritten,
+        edgesWritten: summary.edgesWritten,
+        skippedCount: summary.skipped.length
+    };
+}
+function defaultEmit(event) {
+    console.log(JSON.stringify(event));
+}
+async function defaultWait(ms, signal) {
+    try {
+        await sleep(ms, undefined, signal ? { signal } : undefined);
+    }
+    catch (error) {
+        if (!signal?.aborted) {
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=watch.js.map

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@psnext/lscg",
+  "version": "0.1.1",
+  "description": "Local source context graphs for repositories, exposed as a CLI and MCP server.",
+  "type": "module",
+  "bin": {
+    "lscg": "./dist/bin/lscg.js"
+  },
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./mcp": "./dist/src/mcp/server.js"
+  },
+  "files": [
+    "dist",
+    "!dist/test",
+    "!dist/**/*.map"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepare": "npm run build",
+    "prestart": "npm run build",
+    "start": "node ./dist/bin/lscg.js",
+    "prescan": "npm run build",
+    "scan": "node ./dist/bin/lscg.js scan",
+    "prescan:watch": "npm run build",
+    "scan:watch": "node ./dist/bin/lscg.js scan --watch",
+    "prewatch": "npm run build",
+    "watch": "node ./dist/bin/lscg.js watch",
+    "premcp": "npm run build",
+    "mcp": "node ./dist/bin/lscg.js mcp",
+    "pretest": "npm run build",
+    "test": "node --test ./dist/test/*.test.js",
+    "prebenchmark:context": "npm run build",
+    "benchmark:context": "node ./dist/test/context-benchmark.js"
+  },
+  "keywords": [
+    "tree-sitter",
+    "sqlite",
+    "mcp",
+    "code-graph",
+    "context-graph"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "graphology": "^0.26.0",
+    "install-scripts": "^1.2.0",
+    "tree-sitter": "^0.21.1",
+    "tree-sitter-javascript": "^0.23.1",
+    "tree-sitter-typescript": "^0.23.2",
+    "zod": "^3.25.76"
+  },
+  "allowScripts": {
+    "tree-sitter@0.21.1": true,
+    "tree-sitter-javascript@0.23.1": true,
+    "tree-sitter-typescript@0.23.2": true
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^7.0.2"
+  }
+}