septum 0.1.5 → 0.1.6

package/src/core/database/repositories/domain.repository.ts

@@ -7,6 +7,15 @@ import type {
   SymbolKind,
   SymbolRecord,
 } from "../../../types/index.ts";
+import { DependencyRepository } from "./dependency.repository.ts";
+
+const CONTAINER_KINDS = new Set<SymbolKind>([
+  "class",
+  "interface",
+  "trait",
+  "struct",
+  "enum",
+]);
 
 export class DomainRepository {
   constructor(private db: Database) {}
@@ -70,11 +79,15 @@ export class DomainRepository {
 
   public getDomainCatalog(
     domainName: string,
-    archetypeFilter?: string
+    archetypeFilter?: string,
+    options?: { detailLevel?: "compact" | "full"; fileFilter?: string }
   ): DomainCatalogResponse | null {
     const domain = this.getDomainByName(domainName);
     if (!domain) return null;
 
+    const detailLevel = options?.detailLevel ?? "compact";
+    const fileFilter = options?.fileFilter?.trim();
+
     const allowedDeps: string[] = JSON.parse(domain.allowed_deps_json || "[]");
     const forbiddenDeps: string[] = JSON.parse(domain.forbidden_deps_json || "[]");
 
@@ -87,7 +100,14 @@ export class DomainRepository {
     }
     filesQuery += " ORDER BY path ASC";
 
-    const files = this.db.query<FileRecord, any>(filesQuery).all(...params);
+    const allDomainFiles = this.db.query<FileRecord, any>(filesQuery).all(...params);
+    const totalFiles = allDomainFiles.length;
+
+    const files = fileFilter
+      ? allDomainFiles.filter((f) =>
+          f.path.replace(/\\/g, "/").toLowerCase().includes(fileFilter.replace(/\\/g, "/").toLowerCase())
+        )
+      : allDomainFiles;
 
     const catalogFiles: DomainCatalogResponse["files"] = [];
 
@@ -115,6 +135,10 @@ export class DomainRepository {
       }
     }
 
+    // Batch compute file connections for the domain (zero N+1)
+    const depRepo = new DependencyRepository(this.db);
+    const connectionsByPath = depRepo.getDomainFileConnections(domain.id);
+
     for (const file of files) {
       const symbols = symbolsByFileId.get(file.id) ?? [];
 
@@ -123,6 +147,7 @@ export class DomainRepository {
         {
           name: string;
           kind: SymbolKind;
+          lineSpan: string;
           properties: string[];
           methods: string[];
           signatures: string[];
@@ -130,63 +155,66 @@ export class DomainRepository {
       >();
 
       for (const sym of symbols) {
-        if (
-          sym.kind === "class" ||
-          sym.kind === "interface" ||
-          sym.kind === "trait" ||
-          sym.kind === "enum"
-        ) {
+        const lineSpan = `${sym.line_start}-${sym.line_end}`;
+        if (CONTAINER_KINDS.has(sym.kind)) {
           if (!symbolMap.has(sym.name)) {
             symbolMap.set(sym.name, {
               name: sym.name,
               kind: sym.kind,
+              lineSpan,
               properties: [],
               methods: [],
               signatures: [sym.signature],
             });
           }
-        } else if (sym.kind === "method") {
-          let targetContainer = Array.from(symbolMap.values()).pop();
+        } else if (sym.kind === "method" || sym.kind === "property") {
+          let targetContainer:
+            | {
+                name: string;
+                kind: SymbolKind;
+                lineSpan: string;
+                properties: string[];
+                methods: string[];
+                signatures: string[];
+              }
+            | undefined;
+
           if (sym.name.includes("::")) {
             const containerName = sym.name.split("::")[0];
-            if (symbolMap.has(containerName)) {
-              targetContainer = symbolMap.get(containerName);
+            const candidate = symbolMap.get(containerName);
+            if (candidate && CONTAINER_KINDS.has(candidate.kind)) {
+              targetContainer = candidate;
             }
           }
+
           if (targetContainer) {
-            targetContainer.methods.push(sym.signature);
-          } else {
-            symbolMap.set(sym.name, {
-              name: sym.name,
-              kind: sym.kind,
-              properties: [],
-              methods: [],
-              signatures: [sym.signature],
-            });
-          }
-        } else if (sym.kind === "property") {
-          let targetContainer = Array.from(symbolMap.values()).pop();
-          if (sym.name.includes("::")) {
-            const containerName = sym.name.split("::")[0];
-            if (symbolMap.has(containerName)) {
-              targetContainer = symbolMap.get(containerName);
+            if (sym.kind === "method") {
+              targetContainer.methods.push(sym.signature);
+            } else {
+              targetContainer.properties.push(sym.signature);
             }
-          }
-          if (targetContainer) {
-            targetContainer.properties.push(sym.signature);
           } else {
             symbolMap.set(sym.name, {
               name: sym.name,
               kind: sym.kind,
-              properties: [sym.signature],
+              lineSpan,
+              properties: sym.kind === "property" ? [sym.signature] : [],
               methods: [],
               signatures: [sym.signature],
             });
           }
         } else {
+          if (
+            detailLevel === "compact" &&
+            (sym.kind === "variable" || sym.kind === "constant") &&
+            sym.visibility === "private"
+          ) {
+            continue;
+          }
           symbolMap.set(sym.name, {
             name: sym.name,
             kind: sym.kind,
+            lineSpan,
             properties: [],
             methods: [],
             signatures: [sym.signature],
@@ -194,25 +222,54 @@ export class DomainRepository {
         }
       }
 
+      const rawConn = connectionsByPath.get(file.path);
+      const fileConnections = {
+        imports_from: rawConn?.imports_from ?? [],
+        imported_by_count: rawConn?.imported_by_count ?? 0,
+      };
+
       catalogFiles.push({
         path: file.path,
         archetype: file.archetype,
-        symbols: Array.from(symbolMap.values()).map((s) => ({
-          name: s.name,
-          kind: s.kind,
-          properties: s.properties.length > 0 ? s.properties : undefined,
-          methods: s.methods.length > 0 ? s.methods : undefined,
-          signatures: s.signatures.length > 0 ? s.signatures : undefined,
-        })),
+        line_count: file.line_count,
+        connections: fileConnections,
+        symbols: Array.from(symbolMap.values()).map((s) => {
+          if (detailLevel === "compact") {
+            return {
+              name: s.name,
+              kind: s.kind,
+              line_span: s.lineSpan,
+              methods_count: s.methods.length > 0 ? s.methods.length : undefined,
+              properties_count: s.properties.length > 0 ? s.properties.length : undefined,
+            };
+          }
+          return {
+            name: s.name,
+            kind: s.kind,
+            line_span: s.lineSpan,
+            methods_count: s.methods.length > 0 ? s.methods.length : undefined,
+            properties_count: s.properties.length > 0 ? s.properties.length : undefined,
+            properties: s.properties.length > 0 ? s.properties : undefined,
+            methods: s.methods.length > 0 ? s.methods : undefined,
+            signatures: s.signatures.length > 0 ? s.signatures : undefined,
+          };
+        }),
       });
     }
 
     return {
       domain: domain.name,
       root: domain.root_path,
+      detail_level: detailLevel,
+      total_files: totalFiles,
+      showing_files: catalogFiles.length,
       allowed_dependencies: allowedDeps,
       forbidden_dependencies: forbiddenDeps,
       files: catalogFiles,
+      agent_hint:
+        detailLevel === "compact"
+          ? "Compact view (<400 tokens). Use septum_get_symbol({ symbol }) for exact method signatures, or septum_get_domain_catalog({ domain, detail_level: 'full', file_filter: '<path>' }) for full member lists."
+          : undefined,
     };
   }
 }

package/src/core/database/repositories/file.repository.ts

@@ -44,25 +44,22 @@ export class FileRepository {
     mtimeMs: number = 0,
     sizeBytes: number = 0
   ): number {
-    const existing = this.getFileByPath(path);
-    if (existing) {
-      this.db
-        .query(
-          `UPDATE files 
-           SET domain_id = ?, archetype = ?, content_hash = ?, line_count = ?, mtime_ms = ?, size_bytes = ?, last_scanned_at = CURRENT_TIMESTAMP 
-           WHERE id = ?`
-        )
-        .run(domainId, archetype, contentHash, lineCount, mtimeMs, sizeBytes, existing.id);
-      return existing.id;
-    } else {
-      const result = this.db
-        .query(
-          `INSERT INTO files (domain_id, path, archetype, content_hash, line_count, mtime_ms, size_bytes) 
-           VALUES (?, ?, ?, ?, ?, ?, ?)`
-        )
-        .run(domainId, path, archetype, contentHash, lineCount, mtimeMs, sizeBytes);
-      return Number(result.lastInsertRowid);
-    }
+    const row = this.db
+      .query<{ id: number }, [number, string, string, string, number, number, number]>(
+        `INSERT INTO files (domain_id, path, archetype, content_hash, line_count, mtime_ms, size_bytes)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(path) DO UPDATE SET
+           domain_id = excluded.domain_id,
+           archetype = excluded.archetype,
+           content_hash = excluded.content_hash,
+           line_count = excluded.line_count,
+           mtime_ms = excluded.mtime_ms,
+           size_bytes = excluded.size_bytes,
+           last_scanned_at = CURRENT_TIMESTAMP
+         RETURNING id`
+      )
+      .get(domainId, path, archetype, contentHash, lineCount, mtimeMs, sizeBytes);
+    return row ? Number(row.id) : 0;
   }
 
   public updateFileMetadataOnly(id: number, mtimeMs: number, sizeBytes: number): void {
@@ -100,6 +97,10 @@ export class FileRepository {
     this.db.query("DELETE FROM files WHERE path = ?").run(path);
   }
 
+  public deleteFileByPath(path: string): void {
+    this.deleteFile(path);
+  }
+
   public getFileWithDomain(
     filePath: string
   ): { file: FileRecord; domain: DomainRecord } | null {

package/src/core/database/repositories/symbol.repository.ts

@@ -8,6 +8,26 @@ import type {
   SymbolKind,
   SymbolRecord,
 } from "../../../types/index.ts";
+import { DependencyRepository } from "./dependency.repository.ts";
+
+const SQL_KEYWORD_BLACKLIST = new Set([
+  "VALUES",
+  "WHERE",
+  "SELECT",
+  "FROM",
+  "JOIN",
+  "LIKE",
+  "INSERT",
+  "UPDATE",
+  "DELETE",
+]);
+
+function stripCommentsAndStrings(source: string): string {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/\/\/.*$/gm, " ")
+    .replace(/'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"|`(?:\\.|[^`\\])*`/g, '""');
+}
 
 export class SymbolRepository {
   constructor(private db: Database) {}
@@ -354,6 +374,10 @@ export class SymbolRepository {
       siblingMethods = classMethods.map((s) => s.name.replace(`${row.name}::`, ""));
     }
 
+    siblingMethods = Array.from(new Set(siblingMethods)).filter(
+      (m) => !SQL_KEYWORD_BLACKLIST.has(m.toUpperCase())
+    );
+
     // 2. Dependencies Injected (from signature type-hints and constructor)
     const dependenciesInjected = new Set<string>();
     const extractTypeHints = (sig: string) => {
@@ -398,30 +422,44 @@ export class SymbolRepository {
         const lines = fileContent.split(/\r?\n/);
         const start = Math.max(0, row.line_start - 1);
         const end = Math.min(lines.length, row.line_end);
-        const sliceLines = lines.slice(start, end).join("\n");
+        const rawSlice = lines.slice(start, end).join("\n");
+        const sanitizedSlice = stripCommentsAndStrings(rawSlice);
 
         // Match Static invocations: ClassName::methodName(
-        const staticCalls = sliceLines.matchAll(/([A-Z][a-zA-Z0-9_]+)::([a-zA-Z0-9_]+)\s*\(/g);
+        const staticCalls = sanitizedSlice.matchAll(/([A-Z][a-zA-Z0-9_]+)::([a-zA-Z0-9_]+)\s*\(/g);
         for (const m of staticCalls) {
           if (m[1] !== "self" && m[1] !== "parent" && m[1] !== "static") {
             outboundCalls.add(`${m[1]}::${m[2]}`);
           }
         }
 
-        // Match property calls: $this->property->method(
-        const propCalls = sliceLines.matchAll(/\$this->([a-zA-Z0-9_]+)->([a-zA-Z0-9_]+)\s*\(/g);
+        // Match PHP property calls: $this->property->method(
+        const propCalls = sanitizedSlice.matchAll(/\$this->([a-zA-Z0-9_]+)->([a-zA-Z0-9_]+)\s*\(/g);
         for (const m of propCalls) {
-          // Capitalize property name for clean domain inference (e.g. orderService -> OrderService::cancelOrder)
           const propName = m[1];
           const methodName = m[2];
           const inferredClass = propName.charAt(0).toUpperCase() + propName.slice(1);
           outboundCalls.add(`${inferredClass}::${methodName}`);
         }
+
+        // Match TS/JS property calls: this.property.method(
+        const tsPropCalls = sanitizedSlice.matchAll(/\bthis\.([a-zA-Z0-9_]+)\.([a-zA-Z0-9_]+)\s*\(/g);
+        for (const m of tsPropCalls) {
+          const propName = m[1];
+          const methodName = m[2];
+          if (propName !== "db") {
+            const inferredClass = propName.charAt(0).toUpperCase() + propName.slice(1);
+            outboundCalls.add(`${inferredClass}::${methodName}`);
+          }
+        }
       }
     } catch {
       // Graceful fallback if file not physically accessible
     }
 
+    const depRepo = new DependencyRepository(this.db);
+    const connectedFiles = depRepo.getFileConnections(row.file_path);
+
     return {
       symbol: row.name,
       kind: row.kind,
@@ -437,6 +475,7 @@ export class SymbolRepository {
       dependencies_injected: Array.from(dependenciesInjected),
       outbound_calls: Array.from(outboundCalls),
       sibling_methods: siblingMethods.length > 0 ? siblingMethods : undefined,
+      connected_files: connectedFiles,
     };
   }
 

package/src/core/database/repository.ts

@@ -122,11 +122,16 @@ export class SeptumRepository {
     this.files.deleteFile(path);
   }
 
+  public deleteFileByPath(path: string): void {
+    this.files.deleteFileByPath(path);
+  }
+
   public getDomainCatalog(
     domainName: string,
-    archetypeFilter?: string
+    archetypeFilter?: string,
+    options?: { detailLevel?: "compact" | "full"; fileFilter?: string }
   ): DomainCatalogResponse | null {
-    return this.domains.getDomainCatalog(domainName, archetypeFilter);
+    return this.domains.getDomainCatalog(domainName, archetypeFilter, options);
   }
 
   // --- Symbol Methods ---
@@ -171,10 +176,22 @@ export class SeptumRepository {
     return this.dependencies.getAllVerticalSlices();
   }
 
+  public countVerticalSlices(): number {
+    return this.dependencies.countVerticalSlices();
+  }
+
   public clearVerticalSlices(domainId?: number): void {
     this.dependencies.clearVerticalSlices(domainId);
   }
 
+  public getDomainFileConnections(domainId?: number) {
+    return this.dependencies.getDomainFileConnections(domainId);
+  }
+
+  public getFileConnections(filePath: string) {
+    return this.dependencies.getFileConnections(filePath);
+  }
+
   public getAllDependenciesWithDomains(): Array<{
     source_file: string;
     source_domain: string;

package/src/core/database/schema.ts

@@ -104,9 +104,10 @@ export const TABLE_STATEMENTS = [
 
 export const INDEX_STATEMENTS = [
   "CREATE INDEX IF NOT EXISTS idx_domains_name ON domains(name);",
-  "CREATE INDEX IF NOT EXISTS idx_files_domain_id ON files(domain_id);",
+  "CREATE INDEX IF NOT EXISTS idx_files_domain_id ON files(domain_id, id);",
   "CREATE INDEX IF NOT EXISTS idx_files_path ON files(path);",
   "CREATE INDEX IF NOT EXISTS idx_symbols_file_id ON symbols(file_id);",
+  "CREATE INDEX IF NOT EXISTS idx_symbols_file_lines ON symbols(file_id, line_start, line_end);",
   "CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);",
   "CREATE INDEX IF NOT EXISTS idx_symbols_kind ON symbols(kind);",
   "CREATE INDEX IF NOT EXISTS idx_symbols_line_count ON symbols(kind, line_count DESC);",
@@ -117,7 +118,7 @@ export const INDEX_STATEMENTS = [
   "CREATE INDEX IF NOT EXISTS idx_slices_route_name ON vertical_slices(route_name);",
   "CREATE INDEX IF NOT EXISTS idx_slices_controller ON vertical_slices(controller_class, action_name);",
   "CREATE INDEX IF NOT EXISTS idx_env_topology_status ON environment_topology(status);",
-  "CREATE INDEX IF NOT EXISTS idx_env_nodes_layer ON environment_nodes(layer);",
+  "CREATE INDEX IF NOT EXISTS idx_env_nodes_layer ON environment_nodes(layer, id);",
   "CREATE INDEX IF NOT EXISTS idx_env_nodes_status ON environment_nodes(status);",
 ];
 

package/src/core/ingestion/pipeline.ts

@@ -59,6 +59,11 @@ export class IngestionPipeline {
       domainNames = Object.keys(config.domains);
     }
 
+    const existingFilesMap = new Map<string, import("../../types/index.ts").FileRecord>();
+    for (const f of this.repo.getAllFiles()) {
+      existingFilesMap.set(f.path, f);
+    }
+
     for (const domainName of domainNames) {
       const domainCfg = config.domains[domainName];
       const domainId = this.repo.upsertDomain(domainName, domainCfg);
@@ -85,7 +90,13 @@ export class IngestionPipeline {
         config.settings.ignore_patterns,
         childDomainRoots
       );
-      const activeRelPaths: string[] = [];
+      const activeRelPaths = new Set<string>();
+
+      const pendingMetadataUpdates: Array<{
+        id: number;
+        mtimeMs: number;
+        sizeBytes: number;
+      }> = [];
 
       const pendingUpdates: Array<{
         fullPath: string;
@@ -100,7 +111,7 @@ export class IngestionPipeline {
 
       for (const { fullPath, relPath } of collectedFiles) {
         filesScanned++;
-        activeRelPaths.push(relPath);
+        activeRelPaths.add(relPath);
 
         let stat;
         try {
@@ -111,7 +122,7 @@ export class IngestionPipeline {
 
         const mtimeMs = Math.round(stat.mtimeMs);
         const sizeBytes = stat.size;
-        const existingFile = this.repo.getFileByPath(relPath);
+        const existingFile = existingFilesMap.get(relPath);
 
         // Tier 1: Fast OS metadata check (inode mtime + size + domain match)
         if (
@@ -133,8 +144,8 @@ export class IngestionPipeline {
           existingFile.domain_id === domainId &&
           existingFile.content_hash === currentHash
         ) {
-          // Content identical despite mtime bump (e.g. touch) - update metadata without re-parsing AST
-          this.repo.updateFileMetadataOnly(existingFile.id, mtimeMs, sizeBytes);
+          // Content identical despite mtime bump (e.g. touch) - queue metadata update for batch transaction
+          pendingMetadataUpdates.push({ id: existingFile.id, mtimeMs, sizeBytes });
           filesSkipped++;
           continue;
         }
@@ -158,6 +169,10 @@ export class IngestionPipeline {
 
       // Batch ACID Transaction per domain
       this.repo.runInTransaction(() => {
+        for (const meta of pendingMetadataUpdates) {
+          this.repo.updateFileMetadataOnly(meta.id, meta.mtimeMs, meta.sizeBytes);
+        }
+
         for (const item of pendingUpdates) {
           const fileId = this.repo.upsertFile(
             domainId,
@@ -176,8 +191,13 @@ export class IngestionPipeline {
           dependenciesIndexed += item.ast.dependencies.length;
         }
 
-        // State Reconciliation: Prune deleted files from DB
-        this.repo.deleteFilesNotInPaths(domainId, activeRelPaths);
+        // State Reconciliation: Prune deleted files from DB using pre-loaded existingFilesMap
+        for (const [existingPath, existingRecord] of existingFilesMap.entries()) {
+          if (existingRecord.domain_id === domainId && !activeRelPaths.has(existingPath)) {
+            this.repo.deleteFileByPath(existingPath);
+            existingFilesMap.delete(existingPath);
+          }
+        }
       });
     }
 
@@ -188,29 +208,28 @@ export class IngestionPipeline {
       detectedTopology.framework
     );
 
-    this.repo.clearVerticalSlices();
+    const slicesToPersist =
+      semanticSlices.length > 0
+        ? semanticSlices
+        : new CallGraphTracer(this.repo, projectRoot).traceAllSlices();
 
-    if (semanticSlices.length > 0) {
-      for (const slice of semanticSlices) {
-        this.repo.upsertVerticalSlice(slice);
-      }
-    } else {
-      // Heuristic Call-Graph Tracer fallback for Clean/Hexagonal or generic architectures
-      const callGraphTracer = new CallGraphTracer(this.repo, projectRoot);
-      const graphSlices = callGraphTracer.traceAllSlices();
-      for (const slice of graphSlices) {
+    this.repo.runInTransaction(() => {
+      this.repo.clearVerticalSlices();
+      for (const slice of slicesToPersist) {
         this.repo.upsertVerticalSlice(slice);
       }
-    }
+    });
 
     const durationMs = Math.round(performance.now() - startTime);
 
     // Update SSOT repo_meta watermark
-    this.repo.setMeta("last_sync", new Date().toISOString());
-    this.repo.setMeta("files_scanned", String(filesScanned));
-    this.repo.setMeta("files_updated", String(filesUpdated));
-    this.repo.setMeta("symbols_indexed", String(symbolsIndexed));
-    this.repo.setMeta("dependencies_indexed", String(dependenciesIndexed));
+    this.repo.runInTransaction(() => {
+      this.repo.setMeta("last_sync", new Date().toISOString());
+      this.repo.setMeta("files_scanned", String(filesScanned));
+      this.repo.setMeta("files_updated", String(filesUpdated));
+      this.repo.setMeta("symbols_indexed", String(symbolsIndexed));
+      this.repo.setMeta("dependencies_indexed", String(dependenciesIndexed));
+    });
 
     return {
       domains_processed: domainNames.length,
@@ -521,6 +540,10 @@ export class IngestionPipeline {
     const projectRoot = this.customWorkspaceRoot || process.cwd();
     const relPath = relative(projectRoot, fullPath).replace(/\\/g, "/");
 
+    if (this.shouldIgnore(relPath, config.settings.ignore_patterns ?? [])) {
+      return false;
+    }
+
     let targetDomainName: string | null = null;
     let targetDomainCfg = null;
 
@@ -535,8 +558,7 @@ export class IngestionPipeline {
     }
 
     if (!targetDomainName || !targetDomainCfg) {
-      targetDomainName = "core";
-      targetDomainCfg = { root: ".", allowed_dependencies: [], forbidden_dependencies: [], archetypes: {} };
+      return false;
     }
 
     const domainId = this.repo.upsertDomain(targetDomainName, targetDomainCfg);