septum 0.1.3 → 0.1.4

package/src/core/database/schema.ts

@@ -1,120 +1,153 @@
-import type { Database } from "bun:sqlite";
-
-export const CURRENT_SCHEMA_VERSION = 2;
-
-export const TABLE_STATEMENTS = [
-  `CREATE TABLE IF NOT EXISTS domains (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    name TEXT NOT NULL UNIQUE,
-    root_path TEXT NOT NULL,
-    allowed_deps_json TEXT NOT NULL DEFAULT '[]',
-    forbidden_deps_json TEXT NOT NULL DEFAULT '[]',
-    archetypes_json TEXT NOT NULL DEFAULT '{}',
-    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
-  );`,
-
-  `CREATE TABLE IF NOT EXISTS files (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    domain_id INTEGER NOT NULL,
-    path TEXT NOT NULL UNIQUE,
-    archetype TEXT NOT NULL DEFAULT 'unknown',
-    content_hash TEXT NOT NULL,
-    line_count INTEGER NOT NULL DEFAULT 0,
-    mtime_ms INTEGER NOT NULL DEFAULT 0,
-    size_bytes INTEGER NOT NULL DEFAULT 0,
-    last_scanned_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    FOREIGN KEY (domain_id) REFERENCES domains(id) ON DELETE CASCADE
-  );`,
-
-  `CREATE TABLE IF NOT EXISTS symbols (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    file_id INTEGER NOT NULL,
-    name TEXT NOT NULL,
-    kind TEXT NOT NULL,
-    signature TEXT NOT NULL,
-    visibility TEXT NOT NULL DEFAULT 'public',
-    line_start INTEGER NOT NULL DEFAULT 0,
-    line_end INTEGER NOT NULL DEFAULT 0,
-    line_count INTEGER NOT NULL DEFAULT 1,
-    FOREIGN KEY (file_id) REFERENCES files(id) ON DELETE CASCADE
-  );`,
-
-  `CREATE TABLE IF NOT EXISTS dependencies (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    source_file_id INTEGER NOT NULL,
-    target_symbol_or_path TEXT NOT NULL,
-    import_statement TEXT NOT NULL,
-    line_number INTEGER NOT NULL DEFAULT 0,
-    is_external BOOLEAN NOT NULL DEFAULT 0,
-    FOREIGN KEY (source_file_id) REFERENCES files(id) ON DELETE CASCADE
-  );`,
-
-  `CREATE TABLE IF NOT EXISTS vertical_slices (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    domain_id INTEGER,
-    feature_key TEXT,
-    http_method TEXT NOT NULL,
-    route_uri TEXT NOT NULL,
-    route_name TEXT,
-    controller_class TEXT NOT NULL,
-    action_name TEXT NOT NULL,
-    controller_file TEXT,
-    controller_line INTEGER DEFAULT 0,
-    architecture_style TEXT NOT NULL DEFAULT 'clean',
-    entry_kind TEXT NOT NULL DEFAULT 'http_route',
-    execution_chain_json TEXT NOT NULL,
-    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    FOREIGN KEY (domain_id) REFERENCES domains(id) ON DELETE CASCADE
-  );`,
-
-  `CREATE TABLE IF NOT EXISTS repo_meta (
-    key TEXT PRIMARY KEY,
-    value TEXT NOT NULL,
-    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
-  );`,
-];
-
-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_path ON files(path);",
-  "CREATE INDEX IF NOT EXISTS idx_symbols_file_id ON symbols(file_id);",
-  "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);",
-  "CREATE INDEX IF NOT EXISTS idx_dependencies_source ON dependencies(source_file_id);",
-  "CREATE INDEX IF NOT EXISTS idx_dependencies_target ON dependencies(target_symbol_or_path);",
-  "CREATE INDEX IF NOT EXISTS idx_slices_route_uri ON vertical_slices(route_uri);",
-  "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);",
-];
-
-const DROP_ALL_TABLES = `
-  DROP TABLE IF EXISTS repo_meta;
-  DROP TABLE IF EXISTS vertical_slices;
-  DROP TABLE IF EXISTS dependencies;
-  DROP TABLE IF EXISTS symbols;
-  DROP TABLE IF EXISTS files;
-  DROP TABLE IF EXISTS domains;
-`;
-
-export function initializeDatabaseSchema(db: Database): void {
-  const versionRow = db.query<{ user_version: number }, []>("PRAGMA user_version;").get();
-  const userVersion = versionRow?.user_version ?? 0;
-
-  if (userVersion !== 0 && userVersion !== CURRENT_SCHEMA_VERSION) {
-    // Zero-kludge cache invalidation: outdated schema versions are cleanly dropped and recreated
-    db.run(DROP_ALL_TABLES);
-  }
-
-  for (const tableSql of TABLE_STATEMENTS) {
-    db.run(tableSql);
-  }
-
-  for (const indexSql of INDEX_STATEMENTS) {
-    db.run(indexSql);
-  }
-
-  db.run(`PRAGMA user_version = ${CURRENT_SCHEMA_VERSION};`);
-}
+import type { Database } from "bun:sqlite";
+
+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,
+    root_path TEXT NOT NULL,
+    allowed_deps_json TEXT NOT NULL DEFAULT '[]',
+    forbidden_deps_json TEXT NOT NULL DEFAULT '[]',
+    archetypes_json TEXT NOT NULL DEFAULT '{}',
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+  );`,
+
+  `CREATE TABLE IF NOT EXISTS files (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    domain_id INTEGER NOT NULL,
+    path TEXT NOT NULL UNIQUE,
+    archetype TEXT NOT NULL DEFAULT 'unknown',
+    content_hash TEXT NOT NULL,
+    line_count INTEGER NOT NULL DEFAULT 0,
+    mtime_ms INTEGER NOT NULL DEFAULT 0,
+    size_bytes INTEGER NOT NULL DEFAULT 0,
+    last_scanned_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (domain_id) REFERENCES domains(id) ON DELETE CASCADE
+  );`,
+
+  `CREATE TABLE IF NOT EXISTS symbols (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    file_id INTEGER NOT NULL,
+    name TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    signature TEXT NOT NULL,
+    visibility TEXT NOT NULL DEFAULT 'public',
+    line_start INTEGER NOT NULL DEFAULT 0,
+    line_end INTEGER NOT NULL DEFAULT 0,
+    line_count INTEGER NOT NULL DEFAULT 1,
+    nesting_depth INTEGER NOT NULL DEFAULT 1,
+    FOREIGN KEY (file_id) REFERENCES files(id) ON DELETE CASCADE
+  );`,
+
+  `CREATE TABLE IF NOT EXISTS dependencies (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    source_file_id INTEGER NOT NULL,
+    target_symbol_or_path TEXT NOT NULL,
+    import_statement TEXT NOT NULL,
+    line_number INTEGER NOT NULL DEFAULT 0,
+    is_external BOOLEAN NOT NULL DEFAULT 0,
+    FOREIGN KEY (source_file_id) REFERENCES files(id) ON DELETE CASCADE
+  );`,
+
+  `CREATE TABLE IF NOT EXISTS vertical_slices (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    domain_id INTEGER,
+    feature_key TEXT,
+    http_method TEXT NOT NULL,
+    route_uri TEXT NOT NULL,
+    route_name TEXT,
+    controller_class TEXT NOT NULL,
+    action_name TEXT NOT NULL,
+    controller_file TEXT,
+    controller_line INTEGER DEFAULT 0,
+    architecture_style TEXT NOT NULL DEFAULT 'clean',
+    entry_kind TEXT NOT NULL DEFAULT 'http_route',
+    execution_chain_json TEXT NOT NULL,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (domain_id) REFERENCES domains(id) ON DELETE CASCADE
+  );`,
+
+  `CREATE TABLE IF NOT EXISTS repo_meta (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+  );`,
+
+  `CREATE TABLE IF NOT EXISTS environment_topology (
+    layer TEXT PRIMARY KEY,
+    platform TEXT,
+    status TEXT NOT NULL,
+    detected_from_json TEXT NOT NULL DEFAULT '[]',
+    constraints_json TEXT NOT NULL DEFAULT '[]',
+    unresolved_inquiry TEXT,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+  );`,
+
+  `CREATE TABLE IF NOT EXISTS environment_nodes (
+    id TEXT PRIMARY KEY,
+    layer TEXT NOT NULL,
+    name TEXT NOT NULL,
+    platform TEXT NOT NULL,
+    canonical_tag TEXT NOT NULL DEFAULT 'unspecified',
+    domain_or_ip TEXT,
+    role TEXT,
+    status TEXT NOT NULL,
+    detected_from_json TEXT NOT NULL DEFAULT '[]',
+    constraints_json TEXT NOT NULL DEFAULT '[]',
+    connected_to_json TEXT NOT NULL DEFAULT '[]',
+    unresolved_inquiry TEXT,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+  );`,
+];
+
+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_path ON files(path);",
+  "CREATE INDEX IF NOT EXISTS idx_symbols_file_id ON symbols(file_id);",
+  "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);",
+  "CREATE INDEX IF NOT EXISTS idx_symbols_nesting_depth ON symbols(nesting_depth DESC);",
+  "CREATE INDEX IF NOT EXISTS idx_dependencies_source ON dependencies(source_file_id);",
+  "CREATE INDEX IF NOT EXISTS idx_dependencies_target ON dependencies(target_symbol_or_path);",
+  "CREATE INDEX IF NOT EXISTS idx_slices_route_uri ON vertical_slices(route_uri);",
+  "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_status ON environment_nodes(status);",
+];
+
+const DROP_ALL_TABLES = `
+  DROP TABLE IF EXISTS environment_nodes;
+  DROP TABLE IF EXISTS environment_topology;
+  DROP TABLE IF EXISTS repo_meta;
+  DROP TABLE IF EXISTS vertical_slices;
+  DROP TABLE IF EXISTS dependencies;
+  DROP TABLE IF EXISTS symbols;
+  DROP TABLE IF EXISTS files;
+  DROP TABLE IF EXISTS domains;
+`;
+
+export function initializeDatabaseSchema(db: Database): void {
+  const versionRow = db.query<{ user_version: number }, []>("PRAGMA user_version;").get();
+  const userVersion = versionRow?.user_version ?? 0;
+
+  if (userVersion !== 0 && userVersion !== CURRENT_SCHEMA_VERSION) {
+    // Zero-kludge cache invalidation: outdated schema versions are cleanly dropped and recreated
+    db.run(DROP_ALL_TABLES);
+  }
+
+  for (const tableSql of TABLE_STATEMENTS) {
+    db.run(tableSql);
+  }
+
+  for (const indexSql of INDEX_STATEMENTS) {
+    db.run(indexSql);
+  }
+
+  db.run(`PRAGMA user_version = ${CURRENT_SCHEMA_VERSION};`);
+}

package/src/core/parser/behavioral-analyzer.ts

@@ -0,0 +1,119 @@
+export interface MethodBehavioralSummary {
+  guards: string[];
+  hasTransaction: boolean;
+  emittedEvents: string[];
+  dispatchedJobs: string[];
+  mutations: string[];
+}
+
+export class BehavioralAnalyzer {
+  /**
+   * Analyzes the body of a method or function to extract semantic side-effects,
+   * authorization guards, database transactions, emitted events, and background job dispatches.
+   */
+  public static analyzeMethod(code: string): MethodBehavioralSummary {
+    const guards = new Set<string>();
+    let hasTransaction = false;
+    const emittedEvents = new Set<string>();
+    const dispatchedJobs = new Set<string>();
+    const mutations = new Set<string>();
+
+    const lines = code.split("\n");
+
+    for (const rawLine of lines) {
+      const line = rawLine.trim();
+      if (!line || line.startsWith("//") || line.startsWith("#")) continue;
+
+      // 1. Transaction Boundaries
+      if (
+        line.includes("DB::transaction") ||
+        line.includes("DB::beginTransaction") ||
+        line.includes("this.db.transaction") ||
+        line.includes(".transaction(")
+      ) {
+        hasTransaction = true;
+      }
+
+      // 2. Authorization Guards
+      // Laravel: $this->authorize('update', $order); or Gate::authorize(...)
+      const authMatch = line.match(/(?:\$this->authorize|Gate::authorize)\s*\(\s*['"]([^'"]+)['"]/);
+      if (authMatch) {
+        guards.add(authMatch[1]);
+      }
+      // Laravel: abort_if(!..., 403, '...');
+      if (line.includes("abort_if(") || line.includes("abort_unless(")) {
+        guards.add("abort_guard");
+      }
+      // TS / NestJS: @UseGuards(AuthGuard, RolesGuard)
+      const guardDecoratorMatch = line.match(/@UseGuards\s*\(([^)]+)\)/);
+      if (guardDecoratorMatch) {
+        const guardNames = guardDecoratorMatch[1].split(",").map((g) => g.trim());
+        for (const g of guardNames) guards.add(g);
+      }
+
+      // 3. Emitted Events
+      // Laravel: event(new OrderPlaced($order));
+      const eventNewMatch = line.match(/event\s*\(\s*new\s+([A-Za-z0-9_]+)/);
+      if (eventNewMatch) {
+        emittedEvents.add(eventNewMatch[1]);
+      }
+      // Laravel: Event::dispatch(new OrderPlaced($order)); or Event::dispatch('name');
+      const eventDispatchMatch = line.match(/Event::dispatch\s*\(\s*(?:new\s+)?([A-Za-z0-9_]+)/);
+      if (eventDispatchMatch) {
+        emittedEvents.add(eventDispatchMatch[1]);
+      }
+      // Laravel: broadcast(new OrderUpdated($order));
+      const broadcastMatch = line.match(/broadcast\s*\(\s*new\s+([A-Za-z0-9_]+)/);
+      if (broadcastMatch) {
+        emittedEvents.add(broadcastMatch[1]);
+      }
+      // EventEmitter: this.eventEmitter.emit('order.created', ...)
+      const nodeEmitMatch = line.match(/(?:eventEmitter|\$emit)\.emit\s*\(\s*['"]([^'"]+)['"]/);
+      if (nodeEmitMatch) {
+        emittedEvents.add(nodeEmitMatch[1]);
+      }
+
+      // 4. Dispatched Background Jobs
+      // Laravel: ProcessPaymentJob::dispatch($order); or ProcessPayment::dispatchSync(...)
+      const jobDispatchStaticMatch = line.match(/([A-Z][a-zA-Z0-9_]*(?:Job|Queue|Task|Process)[a-zA-Z0-9_]*)::dispatch/);
+      if (jobDispatchStaticMatch) {
+        dispatchedJobs.add(jobDispatchStaticMatch[1]);
+      }
+      // Laravel: dispatch(new ProcessPayment($order));
+      const dispatchNewMatch = line.match(/dispatch\s*\(\s*new\s+([A-Za-z0-9_]+)/);
+      if (dispatchNewMatch) {
+        dispatchedJobs.add(dispatchNewMatch[1]);
+      }
+      // BullMQ / Queue: queue.add('process-payment', ...)
+      const queueAddMatch = line.match(/(?:queue|queueService)\.add\s*\(\s*['"]([^'"]+)['"]/);
+      if (queueAddMatch) {
+        dispatchedJobs.add(queueAddMatch[1]);
+      }
+
+      // 5. Model Mutations
+      // Laravel / ORM: $order->update([...]);
+      const updateMatch = line.match(/\$([a-zA-Z0-9_]+)->update\s*\(/);
+      if (updateMatch) {
+        mutations.add(`${updateMatch[1]}.update()`);
+      }
+      // Laravel / ORM: $order->delete();
+      const deleteMatch = line.match(/\$([a-zA-Z0-9_]+)->delete\s*\(/);
+      if (deleteMatch) {
+        mutations.add(`${deleteMatch[1]}.delete()`);
+      }
+      // Direct property assignment: $order->status = 'completed';
+      const assignMatch = line.match(/\$([a-zA-Z0-9_]+)->([a-zA-Z0-9_]+)\s*=\s*([^;]+);/);
+      if (assignMatch && !["this", "request"].includes(assignMatch[1])) {
+        mutations.add(`${assignMatch[1]}.${assignMatch[2]}`);
+      }
+    }
+
+    return {
+      guards: Array.from(guards),
+      hasTransaction,
+      emittedEvents: Array.from(emittedEvents),
+      dispatchedJobs: Array.from(dispatchedJobs),
+      mutations: Array.from(mutations),
+    };
+  }
+}

package/src/core/parser/boundary-tracker.ts

@@ -126,3 +126,163 @@ export function findPythonBlockEnd(lines: string[], startLineIndex: number): num
 
   return lastContentLine;
 }
+
+/**
+ * Calculates the maximum control flow nesting depth within a code block (PHP, TS, JS, Go).
+ * Base depth is 1 (the function body itself).
+ * Nested control structures (if, else if, for, foreach, while, do, switch, try, catch)
+ * that open a block increase the active depth.
+ */
+export function calculateControlFlowNesting(
+  lines: string[],
+  startLineIndex: number,
+  endLineIndex: number
+): number {
+  if (startLineIndex >= endLineIndex) return 1;
+
+  let maxDepth = 1;
+  let currentDepth = 1;
+  let inMultiLineComment = false;
+  let insideBody = false;
+
+  const controlStack: number[] = [];
+  let braceDepth = 0;
+  let pendingControl = false;
+
+  const controlRegex = /\b(if|else\s+if|else|for|foreach|while|do|switch|try|catch)\b/;
+
+  const startIdx = Math.max(0, startLineIndex);
+  const endIdx = Math.min(lines.length - 1, endLineIndex);
+
+  for (let i = startIdx; i <= endIdx; i++) {
+    const rawLine = lines[i];
+
+    let cleanLine = "";
+    let inSingleQuote = false;
+    let inDoubleQuote = false;
+    let inTemplateString = false;
+
+    for (let j = 0; j < rawLine.length; j++) {
+      const char = rawLine[j];
+      const prevChar = j > 0 ? rawLine[j - 1] : "";
+      const nextChar = j + 1 < rawLine.length ? rawLine[j + 1] : "";
+
+      if (inMultiLineComment) {
+        if (char === "*" && nextChar === "/") {
+          inMultiLineComment = false;
+          j++;
+        }
+        continue;
+      }
+
+      if (!inSingleQuote && !inDoubleQuote && !inTemplateString && char === "/" && nextChar === "*") {
+        inMultiLineComment = true;
+        j++;
+        continue;
+      }
+
+      if (!inSingleQuote && !inDoubleQuote && !inTemplateString && char === "/" && nextChar === "/") {
+        break; // Single line comment: ignore rest of line
+      }
+
+      if (char === "'" && !inDoubleQuote && !inTemplateString && prevChar !== "\\") {
+        inSingleQuote = !inSingleQuote;
+        continue;
+      }
+      if (char === '"' && !inSingleQuote && !inTemplateString && prevChar !== "\\") {
+        inDoubleQuote = !inDoubleQuote;
+        continue;
+      }
+      if (char === "`" && !inSingleQuote && !inDoubleQuote && prevChar !== "\\") {
+        inTemplateString = !inTemplateString;
+        continue;
+      }
+
+      if (inSingleQuote || inDoubleQuote || inTemplateString) {
+        continue;
+      }
+
+      cleanLine += char;
+    }
+
+    const trimmedClean = cleanLine.trim();
+    if (!trimmedClean) continue;
+
+    if (insideBody && controlRegex.test(trimmedClean)) {
+      pendingControl = true;
+    }
+
+    for (let j = 0; j < cleanLine.length; j++) {
+      const char = cleanLine[j];
+      if (char === "{") {
+        braceDepth++;
+        if (!insideBody) {
+          insideBody = true;
+        } else if (pendingControl) {
+          currentDepth++;
+          controlStack.push(braceDepth);
+          if (currentDepth > maxDepth) {
+            maxDepth = currentDepth;
+          }
+          pendingControl = false;
+        }
+      } else if (char === "}") {
+        if (controlStack.length > 0 && controlStack[controlStack.length - 1] === braceDepth) {
+          controlStack.pop();
+          currentDepth = Math.max(1, currentDepth - 1);
+        }
+        braceDepth = Math.max(0, braceDepth - 1);
+      }
+    }
+
+    if (trimmedClean.endsWith(";")) {
+      pendingControl = false;
+    }
+  }
+
+  return maxDepth;
+}
+
+/**
+ * Calculates the maximum control flow nesting depth in indentation-based languages (Python).
+ */
+export function calculatePythonNesting(
+  lines: string[],
+  startLineIndex: number,
+  endLineIndex: number
+): number {
+  if (startLineIndex >= endLineIndex) return 1;
+
+  const startLine = lines[startLineIndex];
+  const baseIndentMatch = startLine.match(/^(\s*)/);
+  const baseIndent = baseIndentMatch ? baseIndentMatch[1].length : 0;
+
+  const controlRegex = /^\s*(if|elif|else|for|while|try|except|finally|match|case)\b/;
+  const indentStack: number[] = [baseIndent];
+  let maxDepth = 1;
+
+  const startIdx = Math.max(0, startLineIndex + 1);
+  const endIdx = Math.min(lines.length - 1, endLineIndex);
+
+  for (let i = startIdx; i <= endIdx; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const currentIndentMatch = line.match(/^(\s*)/);
+    const currentIndent = currentIndentMatch ? currentIndentMatch[1].length : 0;
+
+    while (indentStack.length > 1 && currentIndent <= indentStack[indentStack.length - 1]) {
+      indentStack.pop();
+    }
+
+    if (controlRegex.test(line)) {
+      indentStack.push(currentIndent);
+      if (indentStack.length > maxDepth) {
+        maxDepth = indentStack.length;
+      }
+    }
+  }
+
+  return maxDepth;
+}

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

@@ -29,6 +29,7 @@ export function detectArchetype(filePath: string, archetypesMap: Record<string,
   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("route") || lower.includes("router")) return "route";
   if (lower.includes("util") || lower.includes("helper")) return "util";
 
   return "unknown";