@kentwynn/kgraph 0.1.27 → 0.2.0

package/dist/cli/commands/context.d.ts

@@ -1,4 +1,4 @@
-import type { Command } from "commander";
-import type { ContextResponse } from "../../types/cognition.js";
+import type { Command } from 'commander';
+import type { ContextResponse } from '../../types/cognition.js';
 export declare function registerContextCommand(program: Command): void;
 export declare function renderContextMarkdown(response: ContextResponse): string;

package/dist/cli/commands/context.js

@@ -1,43 +1,102 @@
-import { loadConfig } from "../../config/config.js";
-import { queryContext } from "../../context/context-query.js";
-import { assertWorkspace } from "../../storage/kgraph-paths.js";
-import { mapsExist, readMaps } from "../../storage/map-store.js";
-import { KGraphError, runCommand } from "../errors.js";
+import { loadConfig } from '../../config/config.js';
+import { queryContext } from '../../context/context-query.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { mapsExist, readMaps } from '../../storage/map-store.js';
+import { KGraphError, runCommand } from '../errors.js';
 export function registerContextCommand(program) {
     program
-        .command("context <query>")
-        .description("Return compact repo context for a query")
-        .option("--json", "Print JSON output")
+        .command('context <query>')
+        .description('Return compact repo context for a query')
+        .option('--json', 'Print JSON output')
         .action((query, options) => runCommand(async () => {
         if (!query.trim()) {
-            throw new KGraphError("Query cannot be empty.");
+            throw new KGraphError('Query cannot be empty.');
         }
         const workspace = await assertWorkspace(process.cwd());
         if (!(await mapsExist(workspace))) {
-            throw new KGraphError("KGraph maps are missing. Run `kgraph scan` first.");
+            throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
         }
         const config = await loadConfig(workspace);
         const maps = await readMaps(workspace);
         const response = await queryContext(workspace, config, maps, query);
-        console.log(options.json ? JSON.stringify(response, null, 2) : renderContextMarkdown(response));
+        console.log(options.json
+            ? JSON.stringify(response, null, 2)
+            : renderContextMarkdown(response));
     }));
 }
 export function renderContextMarkdown(response) {
     const lines = [`# KGraph Context`, ``, `Query: ${response.query}`, ``];
-    lines.push("## Matched Domains", "");
-    lines.push(...formatList(response.matchedDomains.map((item) => `- ${item.item.name} (${item.reasons.join(", ")})`)));
-    lines.push("", "## Relevant Files", "");
-    lines.push(...formatList(response.relevantFiles.map((item) => `- ${item.item.path} (${item.reasons.join(", ")})`)));
-    lines.push("", "## Relevant Symbols", "");
-    lines.push(...formatList(response.relevantSymbols.map((item) => `- ${item.item.name} in ${item.item.filePath}`)));
-    lines.push("", "## Relevant Cognition", "");
+    lines.push('## Matched Domains', '');
+    lines.push(...formatList(response.matchedDomains.map((item) => `- ${item.item.name} (${item.reasons.join(', ')})`)));
+    lines.push('', '## Relevant Files', '');
+    lines.push(...formatList(response.relevantFiles.map((item) => {
+        const f = item.item;
+        const meta = [
+            f.language,
+            f.tokenEstimate ? `~${f.tokenEstimate} tokens` : '',
+        ]
+            .filter(Boolean)
+            .join(', ');
+        return `- ${f.path}${meta ? ` [${meta}]` : ''}`;
+    })));
+    lines.push('', '## Relevant Symbols', '');
+    lines.push(...formatList(response.relevantSymbols.map((item) => {
+        const s = item.item;
+        const kindInfo = [s.kind, s.parentName].filter(Boolean).join(', ');
+        const lineRange = s.startLine != null && s.endLine != null
+            ? `:${s.startLine}-${s.endLine}`
+            : '';
+        return `- ${s.name} (${kindInfo}) in ${s.filePath}${lineRange}`;
+    })));
+    lines.push('', '## Relevant Cognition', '');
     lines.push(...formatList(response.relevantCognition.map((item) => `- ${item.item.title} [${item.item.referencesStatus}]`)));
-    lines.push("", "## Relationships", "");
-    lines.push(...formatList(response.relationships.map((relationship) => `- ${relationship.sourceId} ${relationship.relationshipType} ${relationship.targetId} (${relationship.confidence})`)));
-    lines.push("", "## Stale References", "");
+    lines.push('', '## Relationships', '');
+    lines.push(...formatGroupedRelationships(response.relationships));
+    lines.push('', '## Nearby Symbols (1-hop imports)', '');
+    lines.push(...formatList((response.nearbySymbols ?? []).map((s) => {
+        const kindInfo = [s.kind, s.parentName].filter(Boolean).join(', ');
+        const lineRange = s.startLine != null && s.endLine != null
+            ? `:${s.startLine}-${s.endLine}`
+            : '';
+        return `- ${s.name} (${kindInfo}) in ${s.filePath}${lineRange}`;
+    })));
+    lines.push('', '## Stale References', '');
     lines.push(...formatList(response.staleReferences.map((ref) => `- ${ref}`)));
-    return lines.join("\n");
+    return lines.join('\n');
+}
+function formatGroupedRelationships(relationships) {
+    const imports = relationships.filter((r) => r.relationshipType === 'import');
+    const calls = relationships.filter((r) => r.relationshipType === 'calls');
+    const contains = relationships.filter((r) => r.relationshipType === 'symbol-contains');
+    const other = relationships.filter((r) => r.relationshipType !== 'import' &&
+        r.relationshipType !== 'calls' &&
+        r.relationshipType !== 'symbol-contains' &&
+        r.relationshipType !== 'mentions' &&
+        r.relationshipType !== 'belongs-to-domain' &&
+        r.relationshipType !== 'stale-reference');
+    const lines = [];
+    if (imports.length > 0) {
+        lines.push('Imports:');
+        for (const r of imports)
+            lines.push(`  ${r.sourceId} → ${r.targetId}`);
+    }
+    if (calls.length > 0) {
+        lines.push('Calls:');
+        for (const r of calls)
+            lines.push(`  ${r.sourceId} → ${r.targetId}`);
+    }
+    if (contains.length > 0) {
+        lines.push('Contains:');
+        for (const r of contains)
+            lines.push(`  ${r.sourceId} contains ${r.targetId}`);
+    }
+    if (other.length > 0) {
+        lines.push('Other:');
+        for (const r of other)
+            lines.push(`  ${r.sourceId} ${r.relationshipType} ${r.targetId}`);
+    }
+    return lines.length > 0 ? lines : ['- None'];
 }
 function formatList(items) {
-    return items.length > 0 ? items : ["- None"];
+    return items.length > 0 ? items : ['- None'];
 }

package/dist/cli/commands/workflow.js

@@ -1,5 +1,4 @@
-import { updateCognition } from '../../cognition/cognition-updater.js';
-import { refreshCognitionReferenceStatuses } from '../../cognition/cognition-updater.js';
+import { refreshCognitionReferenceStatuses, updateCognition, } from '../../cognition/cognition-updater.js';
 import { loadConfig } from '../../config/config.js';
 import { queryContext } from '../../context/context-query.js';
 import { scanRepository } from '../../scanner/repo-scanner.js';
@@ -35,6 +34,7 @@ export async function runDefaultWorkflow(query) {
         console.log(renderWorkflowBanner({
             files: scan.files.length,
             symbols: scan.symbols.length,
+            skippedFiles: scan.skippedFiles,
             cognitionNotes: update.processed.length,
             integrations: config.integrations.map((integration) => ({
                 name: integration.name,

package/dist/cli/help.d.ts

@@ -3,6 +3,7 @@ interface WorkflowBannerStats {
     files: number;
     symbols: number;
     cognitionNotes: number;
+    skippedFiles?: number;
     integrations?: WorkflowBannerIntegration[];
 }
 interface WorkflowBannerIntegration {

package/dist/cli/help.js

@@ -77,7 +77,10 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         `  ${theme.bold('KGraph')} ${theme.dim('repo intelligence refreshed')}`,
         '',
         theme.bold('Refresh Complete'),
-        command('files', String(stats.files)),
+        command('files', String(stats.files) +
+            (stats.skippedFiles
+                ? ` (${stats.skippedFiles} unchanged, skipped)`
+                : '')),
         command('symbols', String(stats.symbols)),
         command('cognition notes processed', String(stats.cognitionNotes)),
         command('integration modes', integrationLine),

package/dist/context/context-query.js

@@ -73,6 +73,28 @@ export async function queryContext(workspace, config, maps, query) {
             .filter((s) => !symbolNames.has(s))
             .map((ref) => `${note.title}: ${ref}`),
     ]);
+    // Collect nearby symbols: exported symbols from files 1-hop imported by matched files
+    const matchedFilePaths = new Set([
+        ...relevantFiles.map((f) => f.item.path),
+        ...relevantSymbols.map((s) => s.item.filePath),
+    ]);
+    const matchedSymbolIds = new Set(relevantSymbols.map((s) => s.item.id));
+    const importedFilePaths = new Set();
+    for (const dep of maps.dependencyMap.dependencies) {
+        if (dep.kind === 'local' &&
+            dep.resolvedFile &&
+            matchedFilePaths.has(dep.fromFile)) {
+            importedFilePaths.add(dep.resolvedFile);
+        }
+    }
+    // Remove files already in the matched set
+    for (const p of matchedFilePaths)
+        importedFilePaths.delete(p);
+    const nearbySymbols = maps.symbolMap.symbols
+        .filter((s) => s.exported &&
+        importedFilePaths.has(s.filePath) &&
+        !matchedSymbolIds.has(s.id))
+        .slice(0, max);
     return {
         query,
         matchedDomains,
@@ -80,6 +102,7 @@ export async function queryContext(workspace, config, maps, query) {
         relevantSymbols,
         relevantCognition,
         relationships: relationships.slice(0, max),
+        nearbySymbols,
         staleReferences,
         warnings: [],
     };

package/dist/scanner/repo-scanner.js

@@ -46,21 +46,71 @@ export async function scanRepository(rootPath, config, previous) {
         unique: true,
         ignore: buildFastGlobIgnore(allExcludes),
     });
+    // Build lookup maps from previous scan for incremental skip
+    const prevFileByPath = new Map((previous?.files ?? []).map((f) => [f.path, f]));
+    const prevSymbolsByFile = new Map();
+    const prevDepsByFile = new Map();
+    const prevRelsBySource = new Map();
+    if (previous) {
+        for (const sym of previous.symbols) {
+            const arr = prevSymbolsByFile.get(sym.filePath) ?? [];
+            arr.push(sym);
+            prevSymbolsByFile.set(sym.filePath, arr);
+        }
+        for (const dep of previous.dependencies) {
+            const arr = prevDepsByFile.get(dep.fromFile) ?? [];
+            arr.push(dep);
+            prevDepsByFile.set(dep.fromFile, arr);
+        }
+        for (const rel of previous.relationships) {
+            if (rel.relationshipType !== 'import' &&
+                rel.relationshipType !== 'moved-from') {
+                const arr = prevRelsBySource.get(rel.sourceId) ?? [];
+                arr.push(rel);
+                prevRelsBySource.set(rel.sourceId, arr);
+            }
+        }
+    }
     const files = [];
     const symbols = [];
     const dependencies = [];
     const relationships = [];
     const warnings = [];
+    let skippedFiles = 0;
     for (const repoPath of entries.sort()) {
         if (shouldExclude(repoPath, mergedConfig)) {
             continue;
         }
         const absolutePath = path.join(rootPath, repoPath);
         try {
-            const [info, content] = await Promise.all([
-                stat(absolutePath),
-                readFile(absolutePath),
-            ]);
+            const info = await stat(absolutePath);
+            // Incremental skip: if mtime and size match previous, carry forward
+            const prevFile = prevFileByPath.get(repoPath);
+            if (prevFile &&
+                prevFile.sizeBytes === info.size &&
+                prevFile.modifiedAt === info.mtime.toISOString()) {
+                files.push({ ...prevFile, modifiedAt: info.mtime.toISOString() });
+                const prevSyms = prevSymbolsByFile.get(repoPath);
+                if (prevSyms)
+                    symbols.push(...prevSyms);
+                const prevDeps = prevDepsByFile.get(repoPath);
+                if (prevDeps)
+                    dependencies.push(...prevDeps);
+                const prevRels = prevRelsBySource.get(repoPath);
+                if (prevRels)
+                    relationships.push(...prevRels);
+                // Also carry forward symbol-sourced relationships
+                if (prevSyms) {
+                    for (const sym of prevSyms) {
+                        const symRels = prevRelsBySource.get(sym.id);
+                        if (symRels)
+                            relationships.push(...symRels);
+                    }
+                }
+                skippedFiles++;
+                continue;
+            }
+            const content = await readFile(absolutePath);
             const text = content.toString('utf8');
             const contentHash = crypto
                 .createHash('sha256')
@@ -105,7 +155,14 @@ export async function scanRepository(rootPath, config, previous) {
     resolveLocalDependencies(dependencies, files);
     relationships.push(...buildImportRelationships(dependencies));
     relationships.push(...detectMovedFiles(previous?.files ?? [], files));
-    return { files, symbols, dependencies, relationships, warnings };
+    return {
+        files,
+        symbols,
+        dependencies,
+        relationships,
+        warnings,
+        skippedFiles,
+    };
 }
 const SOURCE_EXTENSIONS = [
     '.ts',

package/dist/types/cognition.d.ts

@@ -1,5 +1,5 @@
-import type { CodeSymbol, Relationship, RepositoryFile } from "./maps.js";
-export type ReferenceStatus = "current" | "stale" | "unresolved" | "mixed";
+import type { CodeSymbol, Relationship, RepositoryFile } from './maps.js';
+export type ReferenceStatus = 'current' | 'stale' | 'unresolved' | 'mixed';
 export interface ParsedCognitionNote {
     title: string;
     domain?: string;
@@ -38,6 +38,7 @@ export interface ContextResponse {
     relevantSymbols: RankedItem<CodeSymbol>[];
     relevantCognition: RankedItem<CognitionNote>[];
     relationships: Relationship[];
+    nearbySymbols?: CodeSymbol[];
     staleReferences: string[];
     warnings: string[];
 }

package/dist/types/maps.d.ts

@@ -1,7 +1,7 @@
-export type ScanStatus = "mapped" | "generic" | "failed";
-export type DependencyKind = "local" | "package" | "unknown";
-export type SymbolKind = "function" | "class" | "method" | "type" | "interface" | "export" | "import";
-export type RelationshipType = "import" | "contains" | "symbol-contains" | "calls" | "mentions" | "belongs-to-domain" | "stale-reference" | "moved-from";
+export type ScanStatus = 'mapped' | 'generic' | 'failed';
+export type DependencyKind = 'local' | 'package' | 'unknown';
+export type SymbolKind = 'function' | 'class' | 'method' | 'type' | 'interface' | 'export' | 'import';
+export type RelationshipType = 'import' | 'contains' | 'symbol-contains' | 'calls' | 'mentions' | 'belongs-to-domain' | 'stale-reference' | 'moved-from';
 export interface RepositoryFile {
     id: string;
     path: string;
@@ -36,7 +36,7 @@ export interface Relationship {
     targetType: string;
     targetId: string;
     relationshipType: RelationshipType;
-    confidence: "high" | "medium" | "low";
+    confidence: 'high' | 'medium' | 'low';
 }
 export interface FileMap {
     generatedAt: string;
@@ -60,4 +60,5 @@ export interface ScanResult {
     dependencies: Dependency[];
     relationships: Relationship[];
     warnings: string[];
+    skippedFiles?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.1.27",
+  "version": "0.2.0",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {