opentology 0.3.7 → 0.3.8

package/dist/lib/deep-scan-triples.d.ts

@@ -8,8 +8,13 @@ export declare function batchTriples(triples: string[], batchSize?: number): str
 import type { StoreAdapter as FullStoreAdapter } from './store-adapter.js';
 type StoreAdapter = Pick<FullStoreAdapter, 'sparqlUpdate'>;
 export declare function deleteExistingSymbols(adapter: StoreAdapter, graphUri: string, modulePaths: string[]): Promise<void>;
-export declare function pushSymbolTriples(adapter: StoreAdapter, graphUri: string, result: DeepScanResult): Promise<{
+export interface PushResult {
     triplesInserted: number;
+    triplesFailed: number;
     batchCount: number;
-}>;
+    batchesFailed: number;
+    errors: string[];
+    retryHint: string | null;
+}
+export declare function pushSymbolTriples(adapter: StoreAdapter, graphUri: string, result: DeepScanResult): Promise<PushResult>;
 export {};

package/dist/lib/deep-scan-triples.js

@@ -84,7 +84,7 @@ export function generateSymbolTriples(result) {
     return triples;
 }
 // ── Batching ────────────────────────────────────────────────────
-export function batchTriples(triples, batchSize = 100) {
+export function batchTriples(triples, batchSize = 25) {
     const batches = [];
     for (let i = 0; i < triples.length; i += batchSize) {
         batches.push(triples.slice(i, i + batchSize));
@@ -110,11 +110,28 @@ export async function pushSymbolTriples(adapter, graphUri, result) {
         modulePaths.add(f.filePath);
     // Delete existing symbols for these modules
     await deleteExistingSymbols(adapter, graphUri, [...modulePaths]);
-    // Generate and batch-insert
+    // Generate and batch-insert with per-batch error handling
     const triples = generateSymbolTriples(result);
-    const batches = batchTriples(triples, 100);
-    for (const batch of batches) {
-        await adapter.sparqlUpdate(`INSERT DATA { GRAPH <${graphUri}> {\n${batch.join('\n')}\n} }`);
+    const batches = batchTriples(triples, 25);
+    let inserted = 0;
+    let failed = 0;
+    let batchesFailed = 0;
+    const errors = [];
+    for (let i = 0; i < batches.length; i++) {
+        const batch = batches[i];
+        try {
+            await adapter.sparqlUpdate(`INSERT DATA { GRAPH <${graphUri}> {\n${batch.join('\n')}\n} }`);
+            inserted += batch.length;
+        }
+        catch (err) {
+            batchesFailed++;
+            failed += batch.length;
+            const msg = err instanceof Error ? err.message : String(err);
+            errors.push(`Batch ${i + 1}/${batches.length} failed (${batch.length} triples): ${msg}`);
+        }
     }
-    return { triplesInserted: triples.length, batchCount: batches.length };
+    const retryHint = batchesFailed > 0
+        ? `${batchesFailed}/${batches.length} batches failed (${failed} triples lost). Re-run context_scan with depth="symbol" to retry. If failures persist, try reducing maxSymbols or disabling includeMethodCalls.`
+        : null;
+    return { triplesInserted: inserted, triplesFailed: failed, batchCount: batches.length, batchesFailed, errors, retryHint };
 }

package/dist/lib/deep-scanner-treesitter.d.ts

@@ -12,6 +12,7 @@ export type { TSNode, TSTree, TSLanguage };
 export declare abstract class TreeSitterExtractor implements LanguageExtractor {
     abstract readonly language: string;
     abstract readonly extensions: string[];
+    abstract readonly dependencyModel: import('./language-extractor.js').DependencyModel;
     /** WASM file name, e.g. 'tree-sitter-python.wasm' */
     protected abstract readonly wasmName: string;
     protected lang: TSLanguage | null;

package/dist/lib/deep-scanner-ts.d.ts

@@ -6,6 +6,7 @@ import type { LanguageExtractor, ExtractedSymbols } from './language-extractor.j
 export declare class TypeScriptExtractor implements LanguageExtractor {
     readonly language = "typescript";
     readonly extensions: string[];
+    readonly dependencyModel: "file-based";
     private tsMorph;
     isAvailable(): Promise<boolean>;
     extract(_filePaths: string[], rootDir: string, options: {

package/dist/lib/deep-scanner-ts.js

@@ -156,6 +156,7 @@ export class TypeScriptExtractor {
     constructor() {
         this.language = 'typescript';
         this.extensions = ['.ts', '.tsx', '.js', '.jsx'];
+        this.dependencyModel = 'file-based';
         this.tsMorph = null;
     }
     async isAvailable() {

package/dist/lib/deep-scanner.d.ts

@@ -2,6 +2,7 @@
  * Deep scanner — language-agnostic orchestrator for symbol-level codebase analysis.
  * Delegates to LanguageExtractor implementations (ts-morph, tree-sitter, etc.).
  */
+import type { DependencyModel } from './language-extractor.js';
 export interface DeepScanOptions {
     maxFiles?: number;
     maxSymbols?: number;
@@ -48,6 +49,12 @@ export interface MethodCallInfo {
     caller: string;
     callee: string;
 }
+export interface LanguageHint {
+    language: string;
+    dependencyModel: DependencyModel;
+    moduleScanApplicable: boolean;
+    recommendation: string;
+}
 export interface UnsupportedFileGroup {
     extension: string;
     language: string;
@@ -61,6 +68,7 @@ export interface DeepScanResult {
     functions: FunctionInfo[];
     methodCalls: MethodCallInfo[];
     unsupportedFiles: UnsupportedFileGroup[];
+    languageHints: LanguageHint[];
     fileCount: number;
     symbolCount: number;
     scanDurationMs: number;

package/dist/lib/deep-scanner.js

@@ -103,6 +103,20 @@ async function discoverUnsupportedFiles(rootDir, supportedExtensions) {
         .filter(g => g.count > 0)
         .sort((a, b) => b.count - a.count);
 }
+// ── Language hint generation ────────────────────────────────────
+const DEPENDENCY_MODEL_RECOMMENDATIONS = {
+    'file-based': 'Module-level dependency graph (depth="module") is applicable.',
+    'package-based': 'This language uses package-based imports — module-level scan is not applicable. Use depth="symbol" for class/method/call-level analysis.',
+    'framework-based': 'This language uses framework-level imports — module-level scan is not applicable. Use depth="symbol" for class/method/call-level analysis.',
+};
+function buildLanguageHints(extractors) {
+    return extractors.map(ext => ({
+        language: ext.language,
+        dependencyModel: ext.dependencyModel,
+        moduleScanApplicable: ext.dependencyModel === 'file-based',
+        recommendation: DEPENDENCY_MODEL_RECOMMENDATIONS[ext.dependencyModel],
+    }));
+}
 // ── Main entry point ────────────────────────────────────────────
 export async function deepScan(rootDir, options) {
     const maxFiles = options?.maxFiles ?? 500;
@@ -144,6 +158,7 @@ export async function deepScan(rootDir, options) {
             functions: [],
             methodCalls: [],
             unsupportedFiles: [],
+            languageHints: buildLanguageHints(available),
             fileCount: total,
             symbolCount: 0,
             scanDurationMs: Date.now() - start,
@@ -218,6 +233,7 @@ export async function deepScan(rootDir, options) {
         functions,
         methodCalls,
         unsupportedFiles,
+        languageHints: buildLanguageHints(available),
         fileCount: files.length,
         symbolCount,
         scanDurationMs: Date.now() - start,

package/dist/lib/extractors/go.d.ts

@@ -8,6 +8,7 @@ import type { ExtractedSymbols } from '../language-extractor.js';
 export declare class GoExtractor extends TreeSitterExtractor {
     readonly language = "go";
     readonly extensions: string[];
+    readonly dependencyModel: "package-based";
     protected readonly wasmName = "tree-sitter-go.wasm";
     protected extractFromTree(tree: TSTree, relPath: string, _source: string, includeMethodCalls: boolean): ExtractedSymbols;
     private extractStructFields;

package/dist/lib/extractors/go.js

@@ -8,6 +8,7 @@ export class GoExtractor extends TreeSitterExtractor {
         super(...arguments);
         this.language = 'go';
         this.extensions = ['.go'];
+        this.dependencyModel = 'package-based';
         this.wasmName = 'tree-sitter-go.wasm';
     }
     extractFromTree(tree, relPath, _source, includeMethodCalls) {

package/dist/lib/extractors/java.d.ts

@@ -8,6 +8,7 @@ import type { ExtractedSymbols } from '../language-extractor.js';
 export declare class JavaExtractor extends TreeSitterExtractor {
     readonly language = "java";
     readonly extensions: string[];
+    readonly dependencyModel: "package-based";
     protected readonly wasmName = "tree-sitter-java.wasm";
     protected extractFromTree(tree: TSTree, relPath: string, _source: string, includeMethodCalls: boolean): ExtractedSymbols;
     private getSuperclass;

package/dist/lib/extractors/java.js

@@ -8,6 +8,7 @@ export class JavaExtractor extends TreeSitterExtractor {
         super(...arguments);
         this.language = 'java';
         this.extensions = ['.java'];
+        this.dependencyModel = 'package-based';
         this.wasmName = 'tree-sitter-java.wasm';
     }
     extractFromTree(tree, relPath, _source, includeMethodCalls) {

package/dist/lib/extractors/python.d.ts

@@ -8,6 +8,7 @@ import type { ExtractedSymbols } from '../language-extractor.js';
 export declare class PythonExtractor extends TreeSitterExtractor {
     readonly language = "python";
     readonly extensions: string[];
+    readonly dependencyModel: "file-based";
     protected readonly wasmName = "tree-sitter-python.wasm";
     protected extractFromTree(tree: TSTree, relPath: string, _source: string, includeMethodCalls: boolean): ExtractedSymbols;
     private getBaseClasses;

package/dist/lib/extractors/python.js

@@ -9,6 +9,7 @@ export class PythonExtractor extends TreeSitterExtractor {
         super(...arguments);
         this.language = 'python';
         this.extensions = ['.py'];
+        this.dependencyModel = 'file-based';
         this.wasmName = 'tree-sitter-python.wasm';
     }
     extractFromTree(tree, relPath, _source, includeMethodCalls) {

package/dist/lib/extractors/rust.d.ts

@@ -8,6 +8,7 @@ import type { ExtractedSymbols } from '../language-extractor.js';
 export declare class RustExtractor extends TreeSitterExtractor {
     readonly language = "rust";
     readonly extensions: string[];
+    readonly dependencyModel: "file-based";
     protected readonly wasmName = "tree-sitter-rust.wasm";
     protected extractFromTree(tree: TSTree, relPath: string, _source: string, includeMethodCalls: boolean): ExtractedSymbols;
     private extractParams;

package/dist/lib/extractors/rust.js

@@ -8,6 +8,7 @@ export class RustExtractor extends TreeSitterExtractor {
         super(...arguments);
         this.language = 'rust';
         this.extensions = ['.rs'];
+        this.dependencyModel = 'file-based';
         this.wasmName = 'tree-sitter-rust.wasm';
     }
     extractFromTree(tree, relPath, _source, includeMethodCalls) {

package/dist/lib/extractors/swift.d.ts

@@ -8,6 +8,7 @@ import type { ExtractedSymbols } from '../language-extractor.js';
 export declare class SwiftExtractor extends TreeSitterExtractor {
     readonly language = "swift";
     readonly extensions: string[];
+    readonly dependencyModel: "framework-based";
     protected readonly wasmName = "tree-sitter-swift.wasm";
     protected extractFromTree(tree: TSTree, relPath: string, _source: string, includeMethodCalls: boolean): ExtractedSymbols;
     private extractClassLike;

package/dist/lib/extractors/swift.js

@@ -8,6 +8,7 @@ export class SwiftExtractor extends TreeSitterExtractor {
         super(...arguments);
         this.language = 'swift';
         this.extensions = ['.swift'];
+        this.dependencyModel = 'framework-based';
         this.wasmName = 'tree-sitter-swift.wasm';
     }
     extractFromTree(tree, relPath, _source, includeMethodCalls) {

package/dist/lib/language-extractor.d.ts

@@ -9,11 +9,15 @@ export interface ExtractedSymbols {
     functions: FunctionInfo[];
     methodCalls: MethodCallInfo[];
 }
+/** How a language resolves inter-file dependencies. */
+export type DependencyModel = 'file-based' | 'package-based' | 'framework-based';
 export interface LanguageExtractor {
     /** Language identifier, e.g. 'typescript', 'python', 'go' */
     readonly language: string;
     /** File extensions handled by this extractor, e.g. ['.ts', '.tsx'] */
     readonly extensions: string[];
+    /** How this language resolves dependencies between source files. */
+    readonly dependencyModel: DependencyModel;
     /** Check whether the extractor's dependencies are available at runtime. */
     isAvailable(): Promise<boolean>;
     /**

package/dist/mcp/server.js

@@ -381,12 +381,16 @@ async function handleContextScan(args) {
         // Auto-push triples server-side
         let pushStats = null;
         let moduleStats = null;
+        const pushWarnings = [];
         try {
             const config = loadConfig();
             const contextUri = `${config.graphUri}/context`;
             const adapter = await createReadyAdapter(config);
             // Push symbol triples
             pushStats = await pushSymbolTriples(adapter, contextUri, scanResult);
+            if (pushStats.errors.length > 0) {
+                pushWarnings.push(...pushStats.errors);
+            }
             // Also push module dependency graph (fixes #64)
             const snapshot = await scanCodebase(process.cwd());
             if (snapshot.dependencyGraph && snapshot.dependencyGraph.modules.length > 0) {
@@ -405,14 +409,20 @@ async function handleContextScan(args) {
             }
             await persistGraph(adapter, config, contextUri);
         }
-        catch {
-            // Non-fatal: push is best-effort
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            pushWarnings.push(`Push failed: ${msg}`);
         }
         const hints = [];
-        if (pushStats)
-            hints.push(`Symbol triples: ${pushStats.triplesInserted} in ${pushStats.batchCount} batches`);
+        if (pushStats) {
+            hints.push(`Symbol triples: ${pushStats.triplesInserted} inserted, ${pushStats.triplesFailed} failed, ${pushStats.batchCount} batches`);
+            if (pushStats.retryHint)
+                hints.push(pushStats.retryHint);
+        }
         if (moduleStats)
             hints.push(`Module triples: ${moduleStats.modules} modules, ${moduleStats.edges} edges`);
+        if (pushWarnings.length > 0)
+            hints.push(...pushWarnings);
         // Build compact summary — do NOT return full symbol arrays (#66)
         const compact = {
             deepScanAvailable: true,
@@ -424,6 +434,7 @@ async function handleContextScan(args) {
                 files: scanResult.fileCount,
                 symbols: scanResult.symbolCount,
             },
+            languageHints: scanResult.languageHints,
             scanDurationMs: scanResult.scanDurationMs,
             capped: scanResult.capped,
             warnings: scanResult.warnings,
@@ -512,9 +523,42 @@ async function handleContextScan(args) {
     catch {
         // Non-fatal: module triple push is best-effort
     }
+    // Generate language hints for module scan — helps LLM understand when module scan isn't applicable
+    const moduleLanguageHints = [];
+    const fileExtensionMap = {
+        '.ts': { lang: 'typescript', model: 'file-based' },
+        '.tsx': { lang: 'typescript', model: 'file-based' },
+        '.js': { lang: 'javascript', model: 'file-based' },
+        '.jsx': { lang: 'javascript', model: 'file-based' },
+        '.py': { lang: 'python', model: 'file-based' },
+        '.rs': { lang: 'rust', model: 'file-based' },
+        '.go': { lang: 'go', model: 'package-based' },
+        '.java': { lang: 'java', model: 'package-based' },
+        '.swift': { lang: 'swift', model: 'framework-based' },
+    };
+    if (snapshot.dependencyGraph) {
+        const detectedLangs = new Set();
+        for (const mod of snapshot.dependencyGraph.modules) {
+            const ext = '.' + mod.split('.').pop();
+            const info = fileExtensionMap[ext];
+            if (info && !detectedLangs.has(info.lang)) {
+                detectedLangs.add(info.lang);
+                const applicable = info.model === 'file-based';
+                moduleLanguageHints.push({
+                    language: info.lang,
+                    dependencyModel: info.model,
+                    moduleScanApplicable: applicable,
+                    recommendation: applicable
+                        ? 'Module-level dependency graph (depth="module") is applicable.'
+                        : `This language uses ${info.model} imports — module-level scan is not applicable. Use depth="symbol" for class/method/call-level analysis.`,
+                });
+            }
+        }
+    }
     return {
         codebaseSnapshot: snapshot,
         moduleStats,
+        languageHints: moduleLanguageHints.length > 0 ? moduleLanguageHints : undefined,
         _hint: moduleStats
             ? `Module triples auto-pushed: ${moduleStats.modules} modules, ${moduleStats.edges} edges. Query with: SELECT ?m WHERE { ?m a otx:Module }`
             : 'No dependency graph auto-extracted or push failed. Inspect key source files manually.',

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "opentology",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Ontology-powered project memory for AI coding assistants — your codebase as a knowledge graph",
   "type": "module",
   "bin": {
-    "opentology": "./dist/index.js"
+    "opentology": "dist/index.js"
   },
   "files": [
     "dist/"