septum 0.1.6 → 0.1.8

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

@@ -21,50 +21,103 @@ export class DomainRepository {
   constructor(private db: Database) {}
 
   public upsertDomain(name: string, config: DomainConfig): number {
-    const normalizedName = name.trim();
-    const existing = this.getDomainByName(normalizedName);
+    return this.db.transaction(() => {
+      const normalizedName = name.trim();
+      let existing = this.getDomainByName(normalizedName);
 
-    // Merge dependencies and archetypes if existing and incoming is empty
-    let allowed = config.allowed_dependencies ?? [];
-    let forbidden = config.forbidden_dependencies ?? [];
-    let archetypes = config.archetypes ?? {};
+      // MCP-13: If duplicates exist with different casing, consolidate into canonical primary row
+      if (existing) {
+        const allMatching = this.db
+          .query<DomainRecord, [string]>("SELECT * FROM domains WHERE LOWER(name) = LOWER(?) ORDER BY id ASC")
+          .all(normalizedName);
+        if (allMatching.length > 1) {
+          const primary = allMatching[0];
+          const fields = [
+            ["allowed_dependencies", "allowed_deps_json"],
+            ["forbidden_dependencies", "forbidden_deps_json"],
+            ["archetypes", "archetypes_json"],
+          ] as const;
+          for (const [field, column] of fields) {
+            if (config[field] !== undefined) continue;
+            const values = allMatching.map(row => {
+              const parsed = JSON.parse(row[column]);
+              return JSON.stringify(Array.isArray(parsed) ? [...parsed].sort() : Object.entries(parsed).sort());
+            });
+            if (new Set(values).size > 1) {
+              throw new Error(`Conflicting legacy domain '${normalizedName}': provide '${field}' explicitly before consolidating case variants.`);
+            }
+          }
+          for (let i = 1; i < allMatching.length; i++) {
+            const duplicate = allMatching[i];
+            this.db.query("UPDATE files SET domain_id = ? WHERE domain_id = ?").run(primary.id, duplicate.id);
+            this.db.query("UPDATE vertical_slices SET domain_id = ? WHERE domain_id = ?").run(primary.id, duplicate.id);
+            this.db.query("DELETE FROM domains WHERE id = ?").run(duplicate.id);
+          }
+          existing = primary;
+        }
+      }
 
-    if (existing) {
-      if (allowed.length === 0 && existing.allowed_deps_json && existing.allowed_deps_json !== "[]") {
+      const targetName = existing ? existing.name : normalizedName;
+
+      // MCP-12: Distinguish absent (undefined -> preserve) from explicit empty ([] -> clear)
+      let allowed: string[];
+      if (config.allowed_dependencies !== undefined) {
+        allowed = config.allowed_dependencies;
+      } else if (existing?.allowed_deps_json) {
         try {
           allowed = JSON.parse(existing.allowed_deps_json);
-        } catch {}
+        } catch {
+          allowed = [];
+        }
+      } else {
+        allowed = [];
       }
-      if (forbidden.length === 0 && existing.forbidden_deps_json && existing.forbidden_deps_json !== "[]") {
+
+      let forbidden: string[];
+      if (config.forbidden_dependencies !== undefined) {
+        forbidden = config.forbidden_dependencies;
+      } else if (existing?.forbidden_deps_json) {
         try {
           forbidden = JSON.parse(existing.forbidden_deps_json);
-        } catch {}
+        } catch {
+          forbidden = [];
+        }
+      } else {
+        forbidden = [];
       }
-      if (Object.keys(archetypes).length === 0 && existing.archetypes_json && existing.archetypes_json !== "{}") {
+
+      let archetypes: Record<string, string>;
+      if (config.archetypes !== undefined) {
+        archetypes = config.archetypes;
+      } else if (existing?.archetypes_json) {
         try {
           archetypes = JSON.parse(existing.archetypes_json);
-        } catch {}
+        } catch {
+          archetypes = {};
+        }
+      } else {
+        archetypes = {};
       }
-    }
 
-    const allowedJson = JSON.stringify(allowed);
-    const forbiddenJson = JSON.stringify(forbidden);
-    const archetypesJson = JSON.stringify(archetypes);
-
-    const query = `
-      INSERT INTO domains (name, root_path, allowed_deps_json, forbidden_deps_json, archetypes_json)
-      VALUES (?, ?, ?, ?, ?)
-      ON CONFLICT(name) DO UPDATE SET
-        root_path = excluded.root_path,
-        allowed_deps_json = excluded.allowed_deps_json,
-        forbidden_deps_json = excluded.forbidden_deps_json,
-        archetypes_json = excluded.archetypes_json,
-        updated_at = CURRENT_TIMESTAMP
-    `;
-    this.db.query(query).run(normalizedName, config.root, allowedJson, forbiddenJson, archetypesJson);
-
-    const record = this.getDomainByName(normalizedName);
-    return record?.id ?? 0;
+      const allowedJson = JSON.stringify(allowed);
+      const forbiddenJson = JSON.stringify(forbidden);
+      const archetypesJson = JSON.stringify(archetypes);
+
+      const query = `
+        INSERT INTO domains (name, root_path, allowed_deps_json, forbidden_deps_json, archetypes_json)
+        VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(name) DO UPDATE SET
+          root_path = excluded.root_path,
+          allowed_deps_json = excluded.allowed_deps_json,
+          forbidden_deps_json = excluded.forbidden_deps_json,
+          archetypes_json = excluded.archetypes_json,
+          updated_at = CURRENT_TIMESTAMP
+      `;
+      this.db.query(query).run(targetName, config.root, allowedJson, forbiddenJson, archetypesJson);
+
+      const record = this.getDomainByName(targetName);
+      return record?.id ?? 0;
+    }).immediate();
   }
 
   public getDomainByName(name: string): DomainRecord | null {
@@ -268,7 +321,7 @@ export class DomainRepository {
       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."
+          ? "Compact view (<400 tokens). Use septum_symbol({ action: 'inspect', query: symbol }) for exact method signatures, or septum_domain({ action: 'catalog', domain, detail_level: 'full', file_filter: '<path>' }) for full member lists."
           : undefined,
     };
   }

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

@@ -1,10 +1,14 @@
 import * as fs from "node:fs";
+import * as path from "node:path";
 import type { Database } from "bun:sqlite";
 import type {
   DomainRecord,
   ExtractedSymbol,
   FileRecord,
   GetSymbolDetailsResponse,
+  FileConnectionsSummary,
+  ResolvedOutboundCall,
+  SymbolComplexitySmell,
   SymbolKind,
   SymbolRecord,
 } from "../../../types/index.ts";
@@ -310,7 +314,7 @@ export class SymbolRepository {
 
   public getSymbolDetails(
     symbolQuery: string,
-    options: { domain?: string; includeDependencies?: boolean } = {}
+    options: { domain?: string; includeDependencies?: boolean; workspaceRoot?: string } = {}
   ): GetSymbolDetailsResponse | null {
     const trimmed = symbolQuery.trim();
     if (!trimmed) return null;
@@ -380,85 +384,161 @@ export class SymbolRepository {
 
     // 2. Dependencies Injected (from signature type-hints and constructor)
     const dependenciesInjected = new Set<string>();
-    const extractTypeHints = (sig: string) => {
-      const paramMatch = sig.match(/\(([^)]*)\)/);
-      if (paramMatch && paramMatch[1]) {
-        const params = paramMatch[1].split(",");
-        const primitiveTypes = new Set([
-          "int", "string", "bool", "boolean", "float", "array", "iterable",
-          "callable", "void", "mixed", "object", "null", "never", "any", "number", "unknown"
-        ]);
-        for (const p of params) {
-          const parts = p.trim().replace(/^\?/, "").split(/\s+/);
-          if (parts.length >= 2) {
-            const rawType = parts[0].replace(/\[\]$/, "").replace(/^[\\$]/, "");
-            if (rawType && !primitiveTypes.has(rawType.toLowerCase()) && !rawType.startsWith("$")) {
-              dependenciesInjected.add(rawType);
+    const outboundCalls = new Set<string>();
+    const resolvedOutboundCalls: ResolvedOutboundCall[] = [];
+    let connectedFiles: FileConnectionsSummary = { imports_from: [], imported_by_count: 0 };
+
+    const shouldIncludeDeps = options.includeDependencies !== false;
+
+    if (shouldIncludeDeps) {
+      const extractTypeHints = (sig: string) => {
+        const paramMatch = sig.match(/\(([^)]*)\)/);
+        if (paramMatch && paramMatch[1]) {
+          const params = paramMatch[1].split(",");
+          const primitiveTypes = new Set([
+            "int", "string", "bool", "boolean", "float", "array", "iterable",
+            "callable", "void", "mixed", "object", "null", "never", "any", "number", "unknown"
+          ]);
+          for (const p of params) {
+            const parts = p.trim().replace(/^\?/, "").split(/\s+/);
+            if (parts.length >= 2) {
+              const rawType = parts[0].replace(/\[\]$/, "").replace(/^[\\$]/, "");
+              if (rawType && !primitiveTypes.has(rawType.toLowerCase()) && !rawType.startsWith("$")) {
+                dependenciesInjected.add(rawType);
+              }
             }
           }
         }
+      };
+
+      extractTypeHints(row.signature);
+
+      // Also check constructor injection if this is a method
+      if (containerName) {
+        const ctor = this.db
+          .query<{ signature: string }, [number, string, string]>(
+            "SELECT signature FROM symbols WHERE file_id = ? AND (name = ? OR name LIKE ?) LIMIT 1"
+          )
+          .get(row.file_id, `${containerName}::__construct`, `%::__construct`);
+        if (ctor) {
+          extractTypeHints(ctor.signature);
+        }
       }
-    };
 
-    extractTypeHints(row.signature);
-
-    // Also check constructor injection if this is a method
-    if (containerName) {
-      const ctor = this.db
-        .query<{ signature: string }, [number, string, string]>(
-          "SELECT signature FROM symbols WHERE file_id = ? AND (name = ? OR name LIKE ?) LIMIT 1"
-        )
-        .get(row.file_id, `${containerName}::__construct`, `%::__construct`);
-      if (ctor) {
-        extractTypeHints(ctor.signature);
-      }
-    }
+      // 3. Outbound Calls (inspected from physical source file lines if accessible)
+      try {
+        const fullPath = options.workspaceRoot
+          ? path.resolve(options.workspaceRoot, row.file_path)
+          : row.file_path;
+        if (fs.existsSync(fullPath)) {
+          const fileContent = fs.readFileSync(fullPath, "utf-8");
+          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 rawSlice = lines.slice(start, end).join("\n");
+          const sanitizedSlice = stripCommentsAndStrings(rawSlice);
+
+          // Match Static invocations: ClassName::methodName(
+          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]}`);
+            }
+          }
 
-    // 3. Outbound Calls (inspected from physical source file lines if accessible)
-    const outboundCalls = new Set<string>();
-    try {
-      if (fs.existsSync(row.file_path)) {
-        const fileContent = fs.readFileSync(row.file_path, "utf-8");
-        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 rawSlice = lines.slice(start, end).join("\n");
-        const sanitizedSlice = stripCommentsAndStrings(rawSlice);
-
-        // Match Static invocations: ClassName::methodName(
-        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 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) {
+            const propName = m[1];
+            const methodName = m[2];
+            const inferredClass = propName.charAt(0).toUpperCase() + propName.slice(1);
+            outboundCalls.add(`${inferredClass}::${methodName}`);
           }
-        }
 
-        // 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) {
-          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
+      }
 
-        // 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}`);
+      const depRepo = new DependencyRepository(this.db);
+      connectedFiles = depRepo.getFileConnections(row.file_path);
+
+      // 4. Resolve Outbound Calls to target symbol line ranges
+      const lookupStmt = this.db.query<
+        {
+          name: string;
+          line_start: number;
+          line_end: number;
+          line_count: number;
+          file_path: string;
+          domain_name: string;
+        },
+        [string, string, string, string]
+      >(`
+        SELECT
+          s.name,
+          s.line_start,
+          s.line_end,
+          s.line_count,
+          f.path AS file_path,
+          d.name AS domain_name
+        FROM symbols s
+        JOIN files f ON s.file_id = f.id
+        JOIN domains d ON f.domain_id = d.id
+        WHERE (s.name = ? OR s.name LIKE ? OR s.name LIKE ?)
+        ORDER BY CASE WHEN s.name = ? THEN 1 ELSE 2 END, s.line_start ASC
+        LIMIT 1
+      `);
+
+      for (const call of outboundCalls) {
+        try {
+          const target = lookupStmt.get(call, `%::${call}`, `${call}::%`, call);
+          if (target) {
+            resolvedOutboundCalls.push({
+              symbol: call,
+              target_file: target.file_path,
+              target_range: {
+                start_line: target.line_start,
+                end_line: target.line_end,
+                total_lines: target.line_count,
+              },
+              domain: target.domain_name,
+              is_resolved: true,
+            });
+          } else {
+            resolvedOutboundCalls.push({
+              symbol: call,
+              is_resolved: false,
+            });
           }
+        } catch {
+          resolvedOutboundCalls.push({
+            symbol: call,
+            is_resolved: false,
+          });
         }
       }
-    } catch {
-      // Graceful fallback if file not physically accessible
     }
 
-    const depRepo = new DependencyRepository(this.db);
-    const connectedFiles = depRepo.getFileConnections(row.file_path);
+    const complexitySmell: SymbolComplexitySmell | undefined =
+      row.line_count > 300
+        ? {
+            is_high_complexity: true,
+            threshold: 300,
+            total_lines: row.line_count,
+            warning: `Symbol '${row.name}' spans ${row.line_count} lines (exceeds 300-line threshold). Candidate for decomposition/refactoring.`,
+          }
+        : undefined;
 
     return {
       symbol: row.name,
@@ -474,6 +554,8 @@ export class SymbolRepository {
       visibility: row.visibility,
       dependencies_injected: Array.from(dependenciesInjected),
       outbound_calls: Array.from(outboundCalls),
+      resolved_outbound_calls: resolvedOutboundCalls.length > 0 ? resolvedOutboundCalls : undefined,
+      complexity_smell: complexitySmell,
       sibling_methods: siblingMethods.length > 0 ? siblingMethods : undefined,
       connected_files: connectedFiles,
     };

package/src/core/database/repository.ts

@@ -56,8 +56,17 @@ export class SeptumRepository {
     this.environment = new EnvironmentRepository(db);
   }
 
-  public runInTransaction<T>(fn: () => T): T {
-    return this.db.transaction(fn)();
+  public runInTransaction<T>(fn: () => T, immediate = false): T {
+    const transaction = this.db.transaction(fn);
+    return immediate ? transaction.immediate() : transaction();
+  }
+
+  public checkpoint(): void {
+    try {
+      this.db.run("PRAGMA wal_checkpoint(PASSIVE);");
+    } catch {
+      // Ignore if locked or busy
+    }
   }
 
   // --- Domain Methods ---
@@ -247,13 +256,16 @@ export class SeptumRepository {
 
   public getSymbolDetails(
     symbolQuery: string,
-    options: { domain?: string; includeDependencies?: boolean } = {}
+    options: { domain?: string; includeDependencies?: boolean; workspaceRoot?: string } = {}
   ): GetSymbolDetailsResponse | null {
     return this.symbols.getSymbolDetails(symbolQuery, options);
   }
 
-  public getSymbolImpact(symbolName: string): GetSymbolImpactResponse {
-    return this.dependencies.getSymbolImpact(symbolName);
+  public getSymbolImpact(
+    symbolName: string,
+    options: { domain?: string; workspaceRoot?: string } = {}
+  ): GetSymbolImpactResponse {
+    return this.dependencies.getSymbolImpact(symbolName, options);
   }
 
   public getFileInboundImpact(filePath: string): {

package/src/core/database/schema.ts

@@ -5,7 +5,7 @@ export const CURRENT_SCHEMA_VERSION = 4;
 export const TABLE_STATEMENTS = [
   `CREATE TABLE IF NOT EXISTS domains (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
-    name TEXT NOT NULL UNIQUE,
+    name TEXT NOT NULL UNIQUE COLLATE NOCASE,
     root_path TEXT NOT NULL,
     allowed_deps_json TEXT NOT NULL DEFAULT '[]',
     forbidden_deps_json TEXT NOT NULL DEFAULT '[]',

package/src/core/discovery/topology-detector.ts

@@ -126,29 +126,63 @@ export class TopologyDetector {
     if (isMonorepo) {
       architectureStyle = "monorepo-workspaces";
       const workspaceDirs = ["apps", "packages", "modules"];
-      const appDomains: string[] = [];
-      const packageDomains: string[] = [];
+      interface WorkspaceCandidate {
+        parent: string;
+        sub: string;
+        relRoot: string;
+      }
+      const candidates: WorkspaceCandidate[] = [];
 
       for (const parent of workspaceDirs) {
         const fullParent = path.join(projectRoot, parent);
         if (fs.existsSync(fullParent) && fs.statSync(fullParent).isDirectory()) {
           const subs = this.getSubdirectories(fullParent);
           for (const sub of subs) {
-            const relRoot = path.join(parent, sub);
-            const domainName = sub.toLowerCase();
-            if (parent === "apps") appDomains.push(domainName);
-            else packageDomains.push(domainName);
-
-            domains[domainName] = {
-              root: relRoot,
-              description: `Monorepo ${parent} package: ${sub}`,
-              allowed_dependencies: parent === "apps" ? packageDomains : [],
-              forbidden_dependencies: parent !== "apps" ? appDomains : [],
-              archetypes: this.inferDefaultArchetypes(path.join(projectRoot, relRoot)),
-            };
+            candidates.push({ parent, sub, relRoot: path.join(parent, sub) });
           }
         }
       }
+
+      // Detect collisions across workspace subdirectories
+      const nameCounts = new Map<string, number>();
+      for (const c of candidates) {
+        const lower = c.sub.toLowerCase();
+        nameCounts.set(lower, (nameCounts.get(lower) || 0) + 1);
+      }
+
+      const appDomains: string[] = [];
+      const packageDomains: string[] = [];
+      const items: Array<{ domainName: string; parent: string; sub: string; relRoot: string }> = [];
+
+      for (const c of candidates) {
+        const lower = c.sub.toLowerCase();
+        let domainName = (nameCounts.get(lower) || 0) > 1
+          ? `${c.parent}-${lower}`
+          : lower;
+
+        let uniqueName = domainName;
+        let counter = 2;
+        while (items.some((it) => it.domainName === uniqueName)) {
+          uniqueName = `${domainName}-${counter++}`;
+        }
+
+        if (c.parent === "apps") {
+          appDomains.push(uniqueName);
+        } else {
+          packageDomains.push(uniqueName);
+        }
+        items.push({ domainName: uniqueName, parent: c.parent, sub: c.sub, relRoot: c.relRoot });
+      }
+
+      for (const item of items) {
+        domains[item.domainName] = {
+          root: item.relRoot,
+          description: `Monorepo ${item.parent} package: ${item.sub}`,
+          allowed_dependencies: item.parent === "apps" ? packageDomains : [],
+          forbidden_dependencies: item.parent !== "apps" ? appDomains : [],
+          archetypes: this.inferDefaultArchetypes(path.join(projectRoot, item.relRoot)),
+        };
+      }
     }
 
     // 2. Modular DDD (app/Domain, src/modules, src/domains, etc.)
@@ -308,15 +342,21 @@ export class TopologyDetector {
 
   /**
    * Discovers project topology and persists domains and macro metadata directly into SQLite SSOT.
+   * If a domain is already registered, its existing root and policy are preserved on repeat init,
+   * while new domains discovered from the codebase are added.
    */
   public static discoverAndPersist(
     repo: SeptumRepository,
-    projectRoot: string = process.cwd()
+    projectRoot: string = process.cwd(),
+    forceResetPolicies: boolean = false
   ): Record<string, DomainConfig> {
     const topology = this.detect(projectRoot);
 
     for (const [name, config] of Object.entries(topology.domains)) {
-      repo.upsertDomain(name, config);
+      const existing = repo.domains.getDomainByName(name);
+      if (!existing || forceResetPolicies) {
+        repo.upsertDomain(name, config);
+      }
     }
 
     // Persist Macro Metadata SSOT
@@ -324,18 +364,30 @@ export class TopologyDetector {
     repo.setMeta("architecture_style", topology.architectureStyle);
     repo.setMeta("framework", topology.framework);
     repo.setMeta("language", topology.language);
+
+    const allRecords = repo.domains.getAllDomains();
     repo.setMeta(
       "macro_summary",
       JSON.stringify({
         projectType: topology.projectType,
         framework: topology.framework,
         architectureStyle: topology.architectureStyle,
-        domainsCount: Object.keys(topology.domains).length,
-        domains: Object.keys(topology.domains),
+        domainsCount: allRecords.length,
+        domains: allRecords.map((r) => r.name),
       })
     );
 
-    return topology.domains;
+    const result: Record<string, DomainConfig> = {};
+    for (const record of allRecords) {
+      result[record.name] = {
+        root: record.root_path,
+        allowed_dependencies: JSON.parse(record.allowed_deps_json || "[]"),
+        forbidden_dependencies: JSON.parse(record.forbidden_deps_json || "[]"),
+        archetypes: JSON.parse(record.archetypes_json || "{}"),
+      };
+    }
+
+    return result;
   }
 
   private static detectMonorepo(projectRoot: string): boolean {