septum 0.1.0

package/src/core/parser/extractors/nestjs-semantic.ts

@@ -0,0 +1,119 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { SemanticSliceExtractor, VerticalSliceCandidate } from "./semantic-extractor.interface.ts";
+
+export class NestJsSemanticExtractor implements SemanticSliceExtractor {
+  public readonly id = "nestjs";
+  public readonly name = "NestJS Modular Semantic Extractor";
+
+  public canHandle(projectRoot: string, framework?: string): boolean {
+    if (framework === "nestjs") return true;
+
+    if (fs.existsSync(path.join(projectRoot, "nest-cli.json"))) return true;
+
+    const pkgPath = path.join(projectRoot, "package.json");
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (deps["@nestjs/core"]) return true;
+      } catch {}
+    }
+
+    return false;
+  }
+
+  public extractSlices(projectRoot: string, domainId?: number): VerticalSliceCandidate[] {
+    const slices: VerticalSliceCandidate[] = [];
+    const srcDir = path.join(projectRoot, "src");
+    if (!fs.existsSync(srcDir)) return slices;
+
+    const controllerFiles = this.findFilesRecursively(srcDir, /\.controller\.(ts|js)$/);
+
+    for (const file of controllerFiles) {
+      const relPath = path.relative(projectRoot, file);
+      const content = fs.readFileSync(file, "utf-8");
+
+      // Extract @Controller('prefix')
+      const controllerMatch = content.match(/@Controller\s*\(\s*['"]?([^'")]*)['"]?\s*\)\s*export\s+class\s+([A-Za-z0-9_]+)/);
+      if (!controllerMatch) continue;
+
+      const routePrefix = controllerMatch[1] ? `/${controllerMatch[1].replace(/^\/+|\/+$/g, "")}` : "";
+      const controllerClass = controllerMatch[2];
+
+      // Extract methods: @Get('path'), @Post('path'), etc.
+      const methodRegex = /@(Get|Post|Put|Patch|Delete)\s*\(\s*['"]?([^'")]*)['"]?\s*\)\s*(?:@[A-Za-z0-9_]+\s*\([^)]*\)\s*)*\s*(?:async\s+)?([a-zA-Z0-9_]+)\s*\(([^)]*)\)/g;
+      let match: RegExpExecArray | null;
+
+      while ((match = methodRegex.exec(content)) !== null) {
+        const httpMethod = match[1].toUpperCase();
+        const subPath = match[2] ? `/${match[2].replace(/^\/+|\/+$/g, "")}` : "";
+        const fullUri = `${routePrefix}${subPath}` || "/";
+        const actionName = match[3];
+        const params = match[4];
+
+        // Extract DTO from parameters: e.g. @Body() createDto: CreateUserDto
+        const dtoMatch = params.match(/@Body\s*\([^)]*\)\s*[a-zA-Z0-9_]+\s*:\s*([A-Za-z0-9_]+Dto)/);
+        const formRequestClass = dtoMatch ? dtoMatch[1] : null;
+
+        const chain: Array<{ stage: string; symbol: string; file?: string; line?: number; description?: string }> = [
+          {
+            stage: "ingress",
+            symbol: `${httpMethod} ${fullUri}`,
+            file: relPath,
+            description: `NestJS Route: ${httpMethod} ${fullUri}`,
+          },
+        ];
+
+        if (formRequestClass) {
+          chain.push({
+            stage: "validation",
+            symbol: formRequestClass,
+            description: "DTO Validation",
+          });
+        }
+
+        chain.push({
+          stage: "controller",
+          symbol: `${controllerClass}::${actionName}`,
+          file: relPath,
+          line: 1,
+          description: `NestJS Controller Action`,
+        });
+
+        slices.push({
+          domain_id: domainId ?? null,
+          feature_key: `nest.${controllerClass.toLowerCase().replace("controller", "")}.${actionName}`,
+          http_method: httpMethod,
+          route_uri: fullUri,
+          route_name: `${controllerClass}.${actionName}`,
+          controller_class: controllerClass,
+          action_name: actionName,
+          controller_file: relPath,
+          controller_line: 1,
+          architecture_style: "mvc",
+          entry_kind: "http_route",
+          execution_chain_json: JSON.stringify(chain),
+        });
+      }
+    }
+
+    return slices;
+  }
+
+  private findFilesRecursively(dir: string, pattern: RegExp): string[] {
+    const results: string[] = [];
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+          results.push(...this.findFilesRecursively(full, pattern));
+        } else if (entry.isFile() && pattern.test(entry.name)) {
+          results.push(full);
+        }
+      }
+    } catch {}
+    return results;
+  }
+}

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

@@ -0,0 +1,149 @@
+import type { ExtractedDependency, ExtractedSymbol, ParsedFileAST, Visibility } from "../../../types/index.ts";
+import { findBraceBlockEnd } from "../boundary-tracker.ts";
+import type { CodeExtractor } from "./base.ts";
+
+export class PHPExtractor implements CodeExtractor {
+  public canHandle(filePath: string): boolean {
+    return /\.php$/i.test(filePath);
+  }
+
+  public async extract(filePath: string, content: string): Promise<ParsedFileAST> {
+    const symbols: ExtractedSymbol[] = [];
+    const dependencies: ExtractedDependency[] = [];
+
+    const lines = content.split("\n");
+
+    // 1. Extract PHP use / import statements
+    const useRegex = /^\s*use\s+([^;]+);/;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const match = useRegex.exec(line);
+      if (match) {
+        const fullTarget = match[1].trim();
+        // Remove 'function ' or 'const ' prefix if any
+        const cleaned = fullTarget.replace(/^(function|const)\s+/, "");
+        const isExternal =
+          cleaned.startsWith("Illuminate\\") ||
+          cleaned.startsWith("Symfony\\") ||
+          cleaned.startsWith("Psr\\") ||
+          cleaned.startsWith("Composer\\");
+
+        dependencies.push({
+          target: cleaned,
+          statement: line.trim(),
+          line_number: i + 1,
+          is_external: isExternal,
+        });
+      }
+    }
+
+    // 2. Extract PHP Class / Interface / Trait / Enum
+    let currentContainer: string | null = null;
+    let currentContainerEndLine = 0;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+      const lineNum = i + 1;
+
+      if (currentContainer && lineNum > currentContainerEndLine) {
+        currentContainer = null;
+        currentContainerEndLine = 0;
+      }
+
+      // Class / Interface / Trait / Enum header
+      const classMatch = /^(?:abstract\s+|final\s+|readonly\s+)*(class|interface|trait|enum)\s+([A-Za-z0-9_]+)/.exec(trimmed);
+      if (classMatch) {
+        currentContainer = classMatch[2];
+        const endLine = findBraceBlockEnd(lines, i);
+        currentContainerEndLine = endLine;
+        symbols.push({
+          name: classMatch[2],
+          kind: classMatch[1] as any,
+          signature: trimmed.replace(/\{$/, "").trim(),
+          visibility: "public",
+          line_start: lineNum,
+          line_end: endLine,
+          line_count: Math.max(1, endLine - lineNum + 1),
+        });
+        continue;
+      }
+
+      // Methods or Properties in class/interface/trait/enum
+      if (currentContainer) {
+        // PHP Constant: const STATUS_ACTIVE = 'active';
+        const constMatch = /^(?:(public|protected|private)\s+)?const\s+([A-Za-z0-9_]+)\s*=/.exec(trimmed);
+        if (constMatch) {
+          const vis = (constMatch[1] as Visibility) || "public";
+          const constName = constMatch[2];
+          symbols.push({
+            name: `${currentContainer}::${constName}`,
+            kind: "property",
+            signature: `${vis} const ${constName}`,
+            visibility: vis,
+            line_start: lineNum,
+            line_end: lineNum,
+            line_count: 1,
+          });
+          continue;
+        }
+
+        // PHP Property: public ?string $foo = null; or private readonly Bar $bar;
+        const propMatch = /^(?:(public|protected|private)\s+)?(?:readonly\s+)?(?:static\s+)?(?:\??[A-Za-z0-9_\\\\]+\s+)?\$([A-Za-z0-9_]+)(?:\s*=[^;]+)?;\s*$/.exec(trimmed);
+        if (propMatch && !trimmed.includes("function ")) {
+          const vis = (propMatch[1] as Visibility) || "public";
+          const propName = `$${propMatch[2]}`;
+          symbols.push({
+            name: `${currentContainer}::${propName}`,
+            kind: "property",
+            signature: `${vis} ${trimmed.replace(/;\s*$/, "")}`,
+            visibility: vis,
+            line_start: lineNum,
+            line_end: lineNum,
+            line_count: 1,
+          });
+          continue;
+        }
+
+        const methodMatch = /^(?:(public|protected|private)\s+)?(?:static\s+)?(?:final\s+)?function\s+([A-Za-z0-9_]+)\s*\(([^)]*)\)(?:\s*:\s*([^;{]+))?/.exec(trimmed);
+        if (methodMatch) {
+          const vis = (methodMatch[1] as Visibility) || "public";
+          const name = methodMatch[2];
+          const params = methodMatch[3].trim();
+          const retType = methodMatch[4] ? `: ${methodMatch[4].trim()}` : "";
+          const endLine = findBraceBlockEnd(lines, i);
+          symbols.push({
+            name: `${currentContainer}::${name}`,
+            kind: "method",
+            signature: `${vis} function ${name}(${params})${retType}`,
+            visibility: vis,
+            line_start: lineNum,
+            line_end: endLine,
+            line_count: Math.max(1, endLine - lineNum + 1),
+          });
+          continue;
+        }
+      }
+
+      // Standalone Global Function in PHP
+      const funcMatch = /^(?:final\s+)?function\s+([A-Za-z0-9_]+)\s*\(([^)]*)\)(?:\s*:\s*([^;{]+))?/.exec(trimmed);
+      if (funcMatch && !currentContainer) {
+        const name = funcMatch[1];
+        const params = funcMatch[2].trim();
+        const retType = funcMatch[3] ? `: ${funcMatch[3].trim()}` : "";
+        const endLine = findBraceBlockEnd(lines, i);
+        symbols.push({
+          name,
+          kind: "function",
+          signature: `function ${name}(${params})${retType}`,
+          visibility: "public",
+          line_start: lineNum,
+          line_end: endLine,
+          line_count: Math.max(1, endLine - lineNum + 1),
+        });
+      }
+    }
+
+    return { symbols, dependencies };
+  }
+}

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

@@ -0,0 +1,226 @@
+import type { ExtractedDependency, ExtractedSymbol, ParsedFileAST, Visibility } from "../../../types/index.ts";
+import { findPythonBlockEnd } from "../boundary-tracker.ts";
+import type { CodeExtractor } from "./base.ts";
+
+const PYTHON_STDLIB_AND_EXTERNALS = new Set([
+  "os",
+  "sys",
+  "json",
+  "math",
+  "typing",
+  "re",
+  "datetime",
+  "time",
+  "collections",
+  "itertools",
+  "functools",
+  "pathlib",
+  "io",
+  "logging",
+  "subprocess",
+  "threading",
+  "multiprocessing",
+  "asyncio",
+  "abc",
+  "copy",
+  "enum",
+  "dataclasses",
+  "uuid",
+  "hashlib",
+  "random",
+  "socket",
+  "unittest",
+  // Common 3rd party frameworks
+  "pydantic",
+  "fastapi",
+  "django",
+  "flask",
+  "sqlalchemy",
+  "celery",
+  "numpy",
+  "pandas",
+  "requests",
+  "httpx",
+  "pytest",
+  "starlette",
+  "alembic",
+  "redis",
+]);
+
+export class PythonExtractor implements CodeExtractor {
+  public canHandle(filePath: string): boolean {
+    return /\.py$/i.test(filePath);
+  }
+
+  public async extract(filePath: string, content: string): Promise<ParsedFileAST> {
+    const symbols: ExtractedSymbol[] = [];
+    const dependencies: ExtractedDependency[] = [];
+
+    const lines = content.split("\n");
+
+    // 1. Extract Python Imports
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+      const lineNum = i + 1;
+
+      // Skip comments
+      if (trimmed.startsWith("#")) continue;
+
+      // Pattern A: from <module> import <symbols>
+      const fromMatch = /^from\s+([.\w]+)\s+import\s+([*\w\s,()]+)/.exec(trimmed);
+      if (fromMatch) {
+        const modulePath = fromMatch[1];
+        const isRelative = modulePath.startsWith(".");
+        const topPackage = isRelative ? "" : modulePath.split(".")[0];
+        const isExternal = !isRelative && PYTHON_STDLIB_AND_EXTERNALS.has(topPackage);
+
+        dependencies.push({
+          target: modulePath,
+          statement: trimmed,
+          line_number: lineNum,
+          is_external: isExternal,
+        });
+        continue;
+      }
+
+      // Pattern B: import <module> [as <alias>]
+      const importMatch = /^import\s+([.\w]+)(?:\s+as\s+\w+)?/.exec(trimmed);
+      if (importMatch) {
+        const modulePath = importMatch[1];
+        const topPackage = modulePath.split(".")[0];
+        const isExternal = PYTHON_STDLIB_AND_EXTERNALS.has(topPackage);
+
+        dependencies.push({
+          target: modulePath,
+          statement: trimmed,
+          line_number: lineNum,
+          is_external: isExternal,
+        });
+      }
+    }
+
+    // 2. Extract Python Classes and Functions
+    let currentClass: string | null = null;
+    let currentClassIndent = -1;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+      const lineNum = i + 1;
+
+      if (!trimmed || trimmed.startsWith("#")) continue;
+
+      const indentMatch = /^(\s*)/.exec(line);
+      const indent = indentMatch ? indentMatch[1].length : 0;
+
+      // Check if we exited current class scope
+      if (currentClass !== null && indent <= currentClassIndent) {
+        currentClass = null;
+        currentClassIndent = -1;
+      }
+
+      // Class Definition
+      const classMatch = /^class\s+([A-Za-z0-9_]+)(?:\s*\([^)]*\))?\s*:/.exec(trimmed);
+      if (classMatch) {
+        const className = classMatch[1];
+        currentClass = className;
+        currentClassIndent = indent;
+
+        const visibility: Visibility = className.startsWith("__")
+          ? "private"
+          : className.startsWith("_")
+          ? "protected"
+          : "public";
+
+        const endLine = findPythonBlockEnd(lines, i);
+        symbols.push({
+          name: className,
+          kind: "class",
+          signature: trimmed.replace(/:$/, "").trim(),
+          visibility,
+          line_start: lineNum,
+          line_end: endLine,
+          line_count: Math.max(1, endLine - lineNum + 1),
+        });
+        continue;
+      }
+
+      // Class Attributes or Pydantic fields inside class
+      if (currentClass !== null && indent > currentClassIndent) {
+        const attrMatch = /^([A-Za-z0-9_]+)\s*(?::\s*([^=]+))?(?:\s*=\s*(.+))?$/.exec(trimmed);
+        if (
+          attrMatch &&
+          !trimmed.startsWith("def ") &&
+          !trimmed.startsWith("async def ") &&
+          !["return", "pass", "raise", "assert", "import", "from", "yield"].includes(attrMatch[1])
+        ) {
+          const attrName = attrMatch[1];
+          const visibility: Visibility = attrName.startsWith("__")
+            ? "private"
+            : attrName.startsWith("_")
+            ? "protected"
+            : "public";
+
+          symbols.push({
+            name: `${currentClass}::${attrName}`,
+            kind: "property",
+            signature: trimmed,
+            visibility,
+            line_start: lineNum,
+            line_end: lineNum,
+            line_count: 1,
+          });
+          continue;
+        }
+      }
+
+      // Module-level UPPERCASE constants: MAX_RETRIES = 5
+      if (currentClass === null && indent === 0) {
+        const constMatch = /^([A-Z][A-Z0-9_]*)\s*(?::\s*([^=]+))?\s*=\s*(.+)$/.exec(trimmed);
+        if (constMatch) {
+          const constName = constMatch[1];
+          symbols.push({
+            name: constName,
+            kind: "property",
+            signature: trimmed,
+            visibility: "public",
+            line_start: lineNum,
+            line_end: lineNum,
+            line_count: 1,
+          });
+          continue;
+        }
+      }
+
+      // Function or Method Definition
+      const funcMatch = /^(?:async\s+)?def\s+([A-Za-z0-9_]+)\s*\(([^)]*)\)(?:\s*->\s*[^:]+)?\s*:/.exec(trimmed);
+      if (funcMatch) {
+        const funcName = funcMatch[1];
+        const isMethod = currentClass !== null && indent > currentClassIndent;
+
+        const visibility: Visibility = funcName.startsWith("__")
+          ? "private"
+          : funcName.startsWith("_")
+          ? "protected"
+          : "public";
+
+        const endLine = findPythonBlockEnd(lines, i);
+        symbols.push({
+          name: isMethod ? `${currentClass}::${funcName}` : funcName,
+          kind: isMethod ? "method" : "function",
+          signature: trimmed.replace(/:$/, "").trim(),
+          visibility,
+          line_start: lineNum,
+          line_end: endLine,
+          line_count: Math.max(1, endLine - lineNum + 1),
+        });
+      }
+    }
+
+    return {
+      symbols,
+      dependencies,
+    };
+  }
+}

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

@@ -0,0 +1,49 @@
+import type {
+  SemanticSliceExtractor,
+  VerticalSliceCandidate,
+} from "./semantic-extractor.interface.ts";
+import { LaravelSemanticExtractor } from "./laravel-semantic.ts";
+import { McpCliSemanticExtractor } from "./mcp-cli-semantic.ts";
+import { NestJsSemanticExtractor } from "./nestjs-semantic.ts";
+
+export class SemanticSliceExtractorRegistry {
+  private static extractors: SemanticSliceExtractor[] = [
+    new LaravelSemanticExtractor(),
+    new McpCliSemanticExtractor(),
+    new NestJsSemanticExtractor(),
+  ];
+
+  /**
+   * Registers a new semantic slice extractor strategy.
+   * Prepends to the list to give higher priority to custom extractors.
+   */
+  public static register(extractor: SemanticSliceExtractor): void {
+    this.extractors.unshift(extractor);
+  }
+
+  /**
+   * Returns all extractors capable of handling the specified project topology.
+   */
+  public static getExtractors(projectRoot: string, framework?: string): SemanticSliceExtractor[] {
+    return this.extractors.filter((extractor) => extractor.canHandle(projectRoot, framework));
+  }
+
+  /**
+   * Executes all matched extractors and combines their vertical slices.
+   */
+  public static async extractAllSlices(
+    projectRoot: string,
+    framework?: string,
+    domainId?: number
+  ): Promise<VerticalSliceCandidate[]> {
+    const matched = this.getExtractors(projectRoot, framework);
+    const combinedSlices: VerticalSliceCandidate[] = [];
+
+    for (const extractor of matched) {
+      const slices = await extractor.extractSlices(projectRoot, domainId);
+      combinedSlices.push(...slices);
+    }
+
+    return combinedSlices;
+  }
+}

package/src/core/parser/extractors/semantic-extractor.interface.ts

@@ -0,0 +1,21 @@
+import type { VerticalSliceRecord } from "../../../types/index.ts";
+
+export type VerticalSliceCandidate = Omit<VerticalSliceRecord, "id" | "created_at">;
+
+export interface SemanticSliceExtractor {
+  readonly id: string;
+  readonly name: string;
+
+  /**
+   * Determines if this extractor can handle the project topology.
+   */
+  canHandle(projectRoot: string, framework?: string): boolean;
+
+  /**
+   * Extracts vertical slices from the codebase.
+   */
+  extractSlices(
+    projectRoot: string,
+    domainId?: number
+  ): Promise<VerticalSliceCandidate[]> | VerticalSliceCandidate[];
+}