septum 0.1.2 → 0.1.4

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

@@ -28,6 +28,8 @@ 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("route") || lower.includes("router")) return "route";
   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;
+  }
+}

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

@@ -1,5 +1,5 @@
 import type { ExtractedDependency, ExtractedSymbol, ParsedFileAST, Visibility } from "../../../types/index.ts";
-import { findBraceBlockEnd } from "../boundary-tracker.ts";
+import { findBraceBlockEnd, calculateControlFlowNesting } from "../boundary-tracker.ts";
 import type { CodeExtractor } from "./base.ts";
 
 const GO_STDLIB_PREFIXES = new Set([
@@ -131,6 +131,7 @@ export class GoExtractor implements CodeExtractor {
         const methodName = methodMatch[1];
         const visibility: Visibility = /^[A-Z]/.test(methodName) ? "public" : "private";
         const endLine = findBraceBlockEnd(lines, i);
+        const nestingDepth = calculateControlFlowNesting(lines, i, endLine - 1);
 
         symbols.push({
           name: methodName,
@@ -140,6 +141,7 @@ export class GoExtractor implements CodeExtractor {
           line_start: lineNum,
           line_end: endLine,
           line_count: Math.max(1, endLine - lineNum + 1),
+          nesting_depth: nestingDepth,
         });
         continue;
       }
@@ -150,6 +152,7 @@ export class GoExtractor implements CodeExtractor {
         const funcName = funcMatch[1];
         const visibility: Visibility = /^[A-Z]/.test(funcName) ? "public" : "private";
         const endLine = findBraceBlockEnd(lines, i);
+        const nestingDepth = calculateControlFlowNesting(lines, i, endLine - 1);
 
         symbols.push({
           name: funcName,
@@ -159,6 +162,7 @@ export class GoExtractor implements CodeExtractor {
           line_start: lineNum,
           line_end: endLine,
           line_count: Math.max(1, endLine - lineNum + 1),
+          nesting_depth: nestingDepth,
         });
       }
     }