septum 0.1.1 → 0.1.3

package/README.md

@@ -61,6 +61,8 @@ Add Septum to your MCP client (`mcp.json` or `claude_desktop_config.json`):
 | `septum sync` | Fast incremental delta sync (< 15ms) for modified files |
 | `septum check --strict` | CI/CD gate: verify boundary integrity & fail on violations |
 | `septum query [domain]` | Inspect domain catalog, archetypes, and public signatures |
+| `septum locate <query>` | Locate symbol, class, interface, method, or error source |
+| `septum slice <route\|intent>` | Trace end-to-end vertical execution slice for route/intent |
 | `septum feature status\|clear` | Manage active feature lease and editing scope |
 | `septum serve` | Launch stdio MCP server for AI coding agents |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "septum",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Deterministic Bounded-Context, Structural File Catalog & Anti-Poisoning Partition for AI Agents",
   "type": "module",
   "main": "src/index.ts",

package/src/cli/templates/skill.ts

@@ -25,11 +25,14 @@ Skill ini berakar langsung pada riset rekayasa perangkat lunak terkemuka:
 
 ## 2. Kapan Wajib Menggunakan (Trigger Moments)
 
-Gunakan skill ini saat:
-1. Menghubungkan Septum pertama kali ke repositori baru atau codebase yang belum terpetakan.
+> [!NOTE] Zero-Config Default (\`septum init\`)
+> Untuk mayoritas proyek (library kecil/menengah, layered monolith standar, MVC, CLI, MCP tools), pengguna atau agen **cukup menjalankan \`septum init\`** di terminal. Perintah \`septum init\` secara default berjalan 100% otomatis tanpa wawancara manual (zero-config heuristic auto-detect & auto-ingest).
+
+Gunakan alur 4 langkah skill ini HANYA saat:
+1. Memetakan domain bisnis kustom / modular DDD enterprise yang kompleks di mana batasan dependency non-standar perlu disepakati bersama Tech Lead.
 2. Memetakan ulang domain bisnis setelah terjadi refactoring arsitektur besar (*re-mapping*).
-3. Mengonfigurasi fitur baru (\`features\` session) untuk mengunci daftar file yang boleh dimodifikasi (*allowed_touchpoints*) dan simbol yang wajib dipakai ulang (*reuse_symbols*).
-4. Pengguna meminta inisialisasi cerdas berbasis pemahaman AI pada struktur proyek.
+3. Mengonfigurasi sesi fitur baru (\`features\` session) untuk mengunci daftar file yang boleh dimodifikasi (*allowed_touchpoints*) dan simbol yang wajib dipakai ulang (*reuse_symbols*).
+4. Pengguna secara eksplisit meminta konsultasi desain domain boundary interaktif.
 
 ---
 

package/src/core/config/loader.ts

@@ -1,31 +1,44 @@
 import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
 import { Database } from "bun:sqlite";
 import type { ValidatedSeptumConfig } from "./schema.ts";
 import { TopologyDetector } from "../discovery/topology-detector.ts";
 import { SeptumDatabase } from "../database/client.ts";
 import { SeptumRepository } from "../database/repository.ts";
+import { resolveWorkspaceRoot, isAppHostDirectory } from "../resolver/path-resolver.ts";
 
 export class ConfigLoader {
   /**
    * Loads configuration with SQLite as the Single Source of Truth (SSOT).
    * Automatically executes Zero-Config TopologyDetector if the database has no domains.
    */
-  public static load(dbPath: string = ".septum/septum.db"): ValidatedSeptumConfig {
+  public static load(
+    dbPath?: string,
+    projectRoot?: string
+  ): ValidatedSeptumConfig {
+    const root = resolveWorkspaceRoot(projectRoot);
+    const resolvedDbPath = dbPath
+      ? (isAbsolute(dbPath) ? dbPath : join(root, dbPath))
+      : join(root, ".septum", "septum.db");
+
     // 1. If database exists and has registered domains, load directly from SQLite SSOT
-    if (existsSync(dbPath)) {
-      const dbConfig = ConfigLoader.loadFromDatabaseOrDefaults(dbPath);
+    if (existsSync(resolvedDbPath)) {
+      const dbConfig = ConfigLoader.loadFromDatabaseOrDefaults(resolvedDbPath);
       if (Object.keys(dbConfig.domains).length > 0) {
         return dbConfig;
       }
     }
 
     // 2. Zero-Config Auto-Discovery: Discover project topology and persist to SQLite
-    const septumDb = new SeptumDatabase(dbPath);
-    const repo = new SeptumRepository(septumDb.raw);
-    TopologyDetector.discoverAndPersist(repo, process.cwd());
-    septumDb.close();
+    // Guard against running auto-discovery inside MCP host / IDE installation folders
+    if (!isAppHostDirectory(root)) {
+      const septumDb = new SeptumDatabase(resolvedDbPath);
+      const repo = new SeptumRepository(septumDb.raw);
+      TopologyDetector.discoverAndPersist(repo, root);
+      septumDb.close();
+    }
 
-    return ConfigLoader.loadFromDatabaseOrDefaults(dbPath);
+    return ConfigLoader.loadFromDatabaseOrDefaults(resolvedDbPath);
   }
 
   public static getDefaultConfig(): ValidatedSeptumConfig {

package/src/core/database/client.ts

@@ -21,6 +21,7 @@ export class SeptumDatabase {
 
   private configurePragmas(): void {
     this.db.run("PRAGMA journal_mode = WAL;");
+    this.db.run("PRAGMA busy_timeout = 5000;");
     this.db.run("PRAGMA foreign_keys = ON;");
     this.db.run("PRAGMA synchronous = NORMAL;");
   }

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

@@ -276,4 +276,74 @@ export class DependencyRepository {
     };
   }
 
+  public getFileInboundImpact(filePath: string): {
+    direct_dependents_count: number;
+    top_consumers: string[];
+    symbols_count: number;
+    risk_level: "low" | "medium" | "high";
+  } {
+    const cleanPath = filePath.replace(/\\/g, "/");
+    const baseName = cleanPath.split("/").pop()?.replace(/\.[^.]+$/, "") || "";
+
+    const symbols = this.db
+      .query<{ name: string }, [string, string]>(
+        `SELECT s.name 
+         FROM symbols s 
+         JOIN files f ON s.file_id = f.id 
+         WHERE f.path = ? OR f.path LIKE ?`
+      )
+      .all(cleanPath, `%${cleanPath}`);
+
+    const matchedFiles = new Set<string>();
+
+    if (baseName.length >= 3) {
+      const depRows = this.db
+        .query<{ file: string }, [string, string, string]>(
+          `SELECT DISTINCT f.path AS file
+           FROM dependencies d
+           JOIN files f ON d.source_file_id = f.id
+           WHERE (d.target_symbol_or_path LIKE ? OR d.target_symbol_or_path LIKE ?)
+             AND f.path NOT LIKE ?`
+        )
+        .all(`%${cleanPath}%`, `%${baseName}%`, `%${cleanPath}`);
+
+      for (const row of depRows) {
+        matchedFiles.add(row.file);
+      }
+    }
+
+    for (const sym of symbols.slice(0, 8)) {
+      const symName = sym.name.split("::").pop() || sym.name;
+      if (symName.length >= 4) {
+        const symDeps = this.db
+          .query<{ file: string }, [string, string]>(
+            `SELECT DISTINCT f.path AS file
+             FROM dependencies d
+             JOIN files f ON d.source_file_id = f.id
+             WHERE d.target_symbol_or_path LIKE ?
+               AND f.path NOT LIKE ?
+             LIMIT 10`
+          )
+          .all(`%${symName}%`, `%${cleanPath}`);
+        for (const r of symDeps) {
+          matchedFiles.add(r.file);
+        }
+      }
+    }
+
+    const consumerList = Array.from(matchedFiles);
+    let riskLevel: "low" | "medium" | "high" = "low";
+    if (consumerList.length >= 5) {
+      riskLevel = "high";
+    } else if (consumerList.length >= 2) {
+      riskLevel = "medium";
+    }
+
+    return {
+      direct_dependents_count: consumerList.length,
+      top_consumers: consumerList.slice(0, 5),
+      symbols_count: symbols.length,
+      risk_level: riskLevel,
+    };
+  }
 }

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

@@ -22,6 +22,13 @@ export class FileRepository {
       .all(domainId);
   }
 
+  public countFiles(): number {
+    const row = this.db
+      .query<{ count: number }, []>("SELECT COUNT(*) as count FROM files")
+      .get();
+    return row?.count ?? 0;
+  }
+
   public upsertFile(
     domainId: number,
     path: string,

package/src/core/database/repository.ts

@@ -75,6 +75,10 @@ export class SeptumRepository {
     return this.files.getFileByPath(path);
   }
 
+  public countFiles(): number {
+    return this.files.countFiles();
+  }
+
   public getFilesByDomain(domainId: number): FileRecord[] {
     return this.files.getFilesByDomain(domainId);
   }
@@ -226,6 +230,15 @@ export class SeptumRepository {
     return this.dependencies.getSymbolImpact(symbolName);
   }
 
+  public getFileInboundImpact(filePath: string): {
+    direct_dependents_count: number;
+    top_consumers: string[];
+    symbols_count: number;
+    risk_level: "low" | "medium" | "high";
+  } {
+    return this.dependencies.getFileInboundImpact(filePath);
+  }
+
   // --- Metadata Methods ---
   public getMeta(key: string): string | null {
     return this.meta.getMeta(key);

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

@@ -43,8 +43,74 @@ export class TopologyDetector {
     ".idea",
     ".agents",
     "bin",
+    "locales",
+    "resources",
+    "public",
+    "assets",
+    "static",
+    ".output",
+    ".nuxt",
+    ".next",
+    ".turbo",
+    ".cache",
   ]);
 
+  private static readonly SOURCE_EXTENSIONS = new Set([
+    ".ts",
+    ".js",
+    ".tsx",
+    ".jsx",
+    ".php",
+    ".py",
+    ".go",
+    ".rs",
+    ".vue",
+  ]);
+
+  /**
+   * Reads compilerOptions.paths from tsconfig.json or jsconfig.json.
+   */
+  public static readTsConfigPaths(projectRoot: string): Record<string, string[]> {
+    for (const file of ["tsconfig.json", "jsconfig.json"]) {
+      const fullPath = path.join(projectRoot, file);
+      if (fs.existsSync(fullPath)) {
+        try {
+          const raw = fs.readFileSync(fullPath, "utf-8");
+          const stripped = raw.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, "");
+          const parsed = JSON.parse(stripped);
+          if (parsed.compilerOptions?.paths) {
+            return parsed.compilerOptions.paths;
+          }
+        } catch {
+          // Ignore tsconfig parse error
+        }
+      }
+    }
+    return {};
+  }
+
+  /**
+   * Checks whether a directory recursively contains any source code files.
+   */
+  private static hasSourceFiles(dir: string): boolean {
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name.startsWith(".") || this.IGNORED_DIRS.has(entry.name)) continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isFile()) {
+          const ext = path.extname(entry.name).toLowerCase();
+          if (this.SOURCE_EXTENSIONS.has(ext)) return true;
+        } else if (entry.isDirectory()) {
+          if (this.hasSourceFiles(full)) return true;
+        }
+      }
+    } catch {
+      // Ignore read errors
+    }
+    return false;
+  }
+
   /**
    * Detects project topology, classifies project type & architecture style, and maps domains.
    */
@@ -213,9 +279,11 @@ export class TopologyDetector {
       }
     }
 
-    // 5. Fallback: Top-level directories
+    // 5. Fallback: Top-level directories that contain source code
     if (Object.keys(domains).length === 0) {
-      const topDirs = this.getSubdirectories(projectRoot);
+      const topDirs = this.getSubdirectories(projectRoot).filter((d) =>
+        this.hasSourceFiles(path.join(projectRoot, d))
+      );
       for (const d of topDirs) {
         domains[d.toLowerCase()] = {
           root: d,
@@ -384,8 +452,8 @@ export class TopologyDetector {
       return "generic-php";
     }
     if (language === "typescript" || language === "javascript") {
+      const pkgJson = path.join(projectRoot, "package.json");
       try {
-        const pkgJson = path.join(projectRoot, "package.json");
         if (fs.existsSync(pkgJson)) {
           const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf-8"));
           const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };

package/src/core/ingestion/pipeline.ts

@@ -291,6 +291,19 @@ export class IngestionPipeline {
           middleware: "app/Http/Middleware/**",
         },
       };
+
+      if (existsSync(join(projectRoot, "resources/views"))) {
+        domains["views"] = {
+          root: "resources/views",
+          description: "Laravel Blade Templates and UI Views (auto-discovered)",
+          allowed_dependencies: [],
+          forbidden_dependencies: [],
+          archetypes: {
+            view: "resources/views/**/*.blade.php",
+          },
+        };
+      }
+
       return domains;
     }
 
@@ -433,6 +446,90 @@ export class IngestionPipeline {
   }
 
   private isSourceFile(path: string): boolean {
-    return /\.(ts|tsx|js|jsx|mjs|cjs|php|py|go|rs)$/i.test(path);
+    return /\.(ts|tsx|js|jsx|mjs|cjs|php|py|go|rs|vue|astro|svelte)$/i.test(path);
+  }
+
+  /**
+   * JIT single-file ingestion: quickly verifies and updates a single file's AST,
+   * symbols, and dependencies in SQLite if its mtime or content hash has changed.
+   * Runs in < 5ms for rapid delta sync without full project scans.
+   */
+  public async ingestFile(targetFilePath: string, config: ValidatedSeptumConfig): Promise<boolean> {
+    const fullPath = resolve(targetFilePath);
+    if (!existsSync(fullPath)) return false;
+
+    let stat;
+    try {
+      stat = statSync(fullPath);
+      if (!stat.isFile() || !this.isSourceFile(fullPath)) return false;
+    } catch {
+      return false;
+    }
+
+    const mtimeMs = Math.round(stat.mtimeMs);
+    const sizeBytes = stat.size;
+
+    const projectRoot = this.customWorkspaceRoot || process.cwd();
+    const relPath = relative(projectRoot, fullPath).replace(/\\/g, "/");
+
+    let targetDomainName: string | null = null;
+    let targetDomainCfg = null;
+
+    for (const [dName, dCfg] of Object.entries(config.domains)) {
+      const absRoot = resolve(projectRoot, dCfg.root).replace(/\\/g, "/");
+      const normFullPath = fullPath.replace(/\\/g, "/");
+      if (normFullPath === absRoot || normFullPath.startsWith(absRoot + "/")) {
+        targetDomainName = dName;
+        targetDomainCfg = dCfg;
+        break;
+      }
+    }
+
+    if (!targetDomainName || !targetDomainCfg) {
+      targetDomainName = "core";
+      targetDomainCfg = { root: ".", allowed_dependencies: [], forbidden_dependencies: [], archetypes: {} };
+    }
+
+    const domainId = this.repo.upsertDomain(targetDomainName, targetDomainCfg);
+    const existingFile = this.repo.getFileByPath(relPath);
+
+    // Tier 1: Fast OS metadata check
+    if (
+      existingFile &&
+      existingFile.mtime_ms === mtimeMs &&
+      existingFile.size_bytes === sizeBytes
+    ) {
+      return false; // Completely up to date
+    }
+
+    const content = readFileSync(fullPath, "utf-8");
+    const currentHash = computeContentHash(content);
+
+    // Tier 2: Hash verification
+    if (existingFile && existingFile.content_hash === currentHash) {
+      this.repo.updateFileMetadataOnly(existingFile.id, mtimeMs, sizeBytes);
+      return false;
+    }
+
+    const lineCount = content.split("\n").length;
+    const archetype = detectArchetype(relPath, targetDomainCfg.archetypes ?? {});
+    const ast = await this.parserEngine.parseFile(fullPath, content);
+
+    this.repo.runInTransaction(() => {
+      const fileId = this.repo.upsertFile(
+        domainId,
+        relPath,
+        archetype,
+        currentHash,
+        lineCount,
+        mtimeMs,
+        sizeBytes
+      );
+      this.repo.replaceFileSymbols(fileId, ast.symbols);
+      this.repo.replaceFileDependencies(fileId, ast.dependencies);
+    });
+
+    return true;
   }
 }
+

package/src/core/parser/extractors/base.ts

@@ -28,6 +28,7 @@ export function detectArchetype(filePath: string, archetypesMap: Record<string,
   if (lower.includes("middleware")) return "middleware";
   if (lower.includes("request")) return "request";
   if (lower.includes("resource")) return "resource";
+  if (lower.includes(".blade.php") || lower.includes("views/") || lower.includes("templates/")) return "view";
   if (lower.includes("util") || lower.includes("helper")) return "util";
 
   return "unknown";

package/src/core/parser/extractors/blade.ts

@@ -0,0 +1,158 @@
+import type {
+  ExtractedDependency,
+  ExtractedSymbol,
+  ParsedFileAST,
+} from "../../../types/index.ts";
+import type { CodeExtractor } from "./base.ts";
+
+export class BladeExtractor implements CodeExtractor {
+  public canHandle(filePath: string): boolean {
+    return /\.blade\.php$/i.test(filePath);
+  }
+
+  public async extract(filePath: string, content: string): Promise<ParsedFileAST> {
+    const symbols: ExtractedSymbol[] = [];
+    const dependencies: ExtractedDependency[] = [];
+
+    const lines = content.split(/\r?\n/);
+    const lineCount = lines.length;
+
+    // 1. Register the view itself as a top-level symbol
+    const viewName = this.normalizeViewName(filePath);
+    if (viewName) {
+      symbols.push({
+        name: viewName,
+        kind: "view",
+        signature: `@view(${viewName})`,
+        visibility: "public",
+        line_start: 1,
+        line_end: Math.max(1, lineCount),
+        line_count: Math.max(1, lineCount),
+      });
+
+      // Also register with view: prefix for explicit queries
+      symbols.push({
+        name: `view:${viewName}`,
+        kind: "view",
+        signature: `@view(${viewName})`,
+        visibility: "public",
+        line_start: 1,
+        line_end: Math.max(1, lineCount),
+        line_count: Math.max(1, lineCount),
+      });
+    }
+
+    // 2. Line-by-line scanning for Blade directives, components, and DOM IDs
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+      const lineNum = i + 1;
+
+      if (!trimmed) continue;
+
+      // Extends: @extends('layouts.app')
+      const extendsMatch = /@extends\s*\(\s*['"]([^'"]+)['"]\s*\)/.exec(trimmed);
+      if (extendsMatch) {
+        dependencies.push({
+          target: extendsMatch[1],
+          statement: trimmed,
+          line_number: lineNum,
+          is_external: false,
+        });
+      }
+
+      // Includes: @include('partials.store_card'), @includeIf, @includeWhen, @includeUnless
+      const includeRegex = /@include(?:If|When|Unless)?\s*\(\s*['"]([^'"]+)['"]/g;
+      let incMatch: RegExpExecArray | null;
+      while ((incMatch = includeRegex.exec(trimmed)) !== null) {
+        dependencies.push({
+          target: incMatch[1],
+          statement: trimmed,
+          line_number: lineNum,
+          is_external: false,
+        });
+      }
+
+      // Blade Components: <x-store.search-bar or <x-alert
+      const componentRegex = /<x-([a-zA-Z0-9_.\-]+)/g;
+      let compMatch: RegExpExecArray | null;
+      while ((compMatch = componentRegex.exec(trimmed)) !== null) {
+        const compTag = compMatch[1];
+        // Convert foo-bar to components.foo-bar or components.foo.bar
+        const compTarget = `components.${compTag.replace(/-/g, ".")}`;
+        dependencies.push({
+          target: compTarget,
+          statement: trimmed,
+          line_number: lineNum,
+          is_external: false,
+        });
+        symbols.push({
+          name: `<x-${compTag}>`,
+          kind: "component",
+          signature: `<x-${compTag}>`,
+          visibility: "public",
+          line_start: lineNum,
+          line_end: lineNum,
+          line_count: 1,
+        });
+      }
+
+      // Livewire: @livewire('search-dropdown')
+      const livewireMatch = /@livewire\s*\(\s*['"]([^'"]+)['"]/.exec(trimmed);
+      if (livewireMatch) {
+        dependencies.push({
+          target: `livewire:${livewireMatch[1]}`,
+          statement: trimmed,
+          line_number: lineNum,
+          is_external: false,
+        });
+      }
+
+      // Section: @section('content')
+      const sectionMatch = /@section\s*\(\s*['"]([^'"]+)['"]/.exec(trimmed);
+      if (sectionMatch) {
+        symbols.push({
+          name: `section:${sectionMatch[1]}`,
+          kind: "property",
+          signature: `@section('${sectionMatch[1]}')`,
+          visibility: "public",
+          line_start: lineNum,
+          line_end: lineNum,
+          line_count: 1,
+        });
+      }
+
+      // DOM ID attribute: id="laptop-slider" or id='laptop-slider'
+      const idMatch = /\bid=["']([a-zA-Z0-9_\-]+)["']/.exec(trimmed);
+      if (idMatch) {
+        const elementId = idMatch[1];
+        symbols.push({
+          name: `#${elementId}`,
+          kind: "property",
+          signature: `id="${elementId}"`,
+          visibility: "public",
+          line_start: lineNum,
+          line_end: lineNum,
+          line_count: 1,
+        });
+      }
+    }
+
+    return { symbols, dependencies };
+  }
+
+  /**
+   * Derive Laravel view name from path, e.g.:
+   * resources/views/partials/store_card.blade.php -> partials.store_card
+   */
+  private normalizeViewName(filePath: string): string | null {
+    const clean = filePath.replace(/\\/g, "/");
+    const viewsIdx = clean.indexOf("views/");
+    if (viewsIdx !== -1) {
+      const sub = clean.slice(viewsIdx + 6).replace(/\.blade\.php$/i, "");
+      return sub.replace(/\//g, ".");
+    }
+    const base = clean.split("/").pop()?.replace(/\.blade\.php$/i, "");
+    return base || null;
+  }
+}