septum 0.1.3 → 0.1.4

package/src/core/parser/schema/providers/laravel-migration-provider.ts

@@ -0,0 +1,215 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type {
+  SchemaFieldSummary,
+  SchemaMetadata,
+  StackSchemaProvider,
+} from "../schema-provider.interface.ts";
+
+export class LaravelMigrationSchemaProvider implements StackSchemaProvider {
+  public readonly id = "laravel-migration";
+  public readonly name = "Laravel Migration Schema Provider";
+
+  public canHandle(projectRoot: string): boolean {
+    const migrationsDir = path.join(projectRoot, "database", "migrations");
+    return fs.existsSync(migrationsDir) || fs.existsSync(path.join(projectRoot, "artisan"));
+  }
+
+  public resolveEntitySchema(
+    projectRoot: string,
+    entitySymbol: string,
+    entityFilePath?: string
+  ): SchemaMetadata | null {
+    const migrationsDir = path.join(projectRoot, "database", "migrations");
+    if (!fs.existsSync(migrationsDir)) return null;
+
+    const tableName = this.resolveTableName(projectRoot, entitySymbol, entityFilePath);
+    if (!tableName) return null;
+
+    const migrationFiles = this.findMigrationFilesForTable(migrationsDir, tableName);
+    if (migrationFiles.length === 0) return null;
+
+    const fieldsMap = new Map<string, SchemaFieldSummary>();
+    let primarySourceFile = migrationFiles[0];
+
+    for (const migFile of migrationFiles) {
+      const fullPath = path.join(migrationsDir, migFile);
+      try {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        this.extractColumnsFromMigration(content, tableName, fieldsMap);
+      } catch {
+        // Skip unreadable files
+      }
+    }
+
+    if (fieldsMap.size === 0) return null;
+
+    const relSourceFile = path.relative(projectRoot, path.join(migrationsDir, primarySourceFile));
+
+    return {
+      entityName: entitySymbol,
+      tableName,
+      schemaSourceFile: relSourceFile,
+      fields: Array.from(fieldsMap.values()),
+    };
+  }
+
+  private resolveTableName(
+    projectRoot: string,
+    entitySymbol: string,
+    entityFilePath?: string
+  ): string {
+    // 1. Check if model file defines explicit protected $table = '...';
+    if (entityFilePath) {
+      const fullEntityPath = path.isAbsolute(entityFilePath)
+        ? entityFilePath
+        : path.join(projectRoot, entityFilePath);
+      if (fs.existsSync(fullEntityPath)) {
+        try {
+          const content = fs.readFileSync(fullEntityPath, "utf-8");
+          const tableMatch = /protected\s+\$table\s*=\s*['"]([^'"]+)['"]/.exec(content);
+          if (tableMatch) {
+            return tableMatch[1];
+          }
+        } catch {}
+      }
+    }
+
+    // 2. Derive snake_case plural from entity name (e.g. OrderItem -> order_items)
+    return this.pluralize(this.toSnakeCase(entitySymbol));
+  }
+
+  private toSnakeCase(str: string): string {
+    return str
+      .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+      .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+      .toLowerCase();
+  }
+
+  private pluralize(snake: string): string {
+    if (snake.endsWith("y") && !/[aeiou]y$/i.test(snake)) {
+      return `${snake.slice(0, -1)}ies`;
+    }
+    if (/(?:s|x|z|ch|sh)$/i.test(snake)) {
+      return `${snake}es`;
+    }
+    return `${snake}s`;
+  }
+
+  private findMigrationFilesForTable(migrationsDir: string, tableName: string): string[] {
+    const files = fs.readdirSync(migrationsDir).filter((f) => f.endsWith(".php")).sort();
+    const matched: string[] = [];
+
+    // Priority 1: *_create_${tableName}_table.php
+    const createTarget = `_create_${tableName}_table.php`;
+    for (const f of files) {
+      if (f.endsWith(createTarget)) {
+        matched.push(f);
+      }
+    }
+
+    // Priority 2: Other migration files altering this table
+    for (const f of files) {
+      if (matched.includes(f)) continue;
+      if (f.includes(`_${tableName}_`)) {
+        matched.push(f);
+      }
+    }
+
+    // If still not found by filename, do a lightweight content search
+    if (matched.length === 0) {
+      for (const f of files) {
+        try {
+          const content = fs.readFileSync(path.join(migrationsDir, f), "utf-8");
+          if (
+            content.includes(`Schema::create('${tableName}'`) ||
+            content.includes(`Schema::create("${tableName}"`) ||
+            content.includes(`Schema::table('${tableName}'`) ||
+            content.includes(`Schema::table("${tableName}"`)
+          ) {
+            matched.push(f);
+          }
+        } catch {}
+      }
+    }
+
+    return matched;
+  }
+
+  private extractColumnsFromMigration(
+    content: string,
+    tableName: string,
+    fieldsMap: Map<string, SchemaFieldSummary>
+  ): void {
+    const lines = content.split("\n");
+
+    for (const rawLine of lines) {
+      const line = rawLine.trim();
+      if (!line.includes("$table->")) continue;
+
+      // Special shorthand: $table->id();
+      if (/\$table->id\s*\(\s*\)/.test(line)) {
+        fieldsMap.set("id", { name: "id", type: "id", isPrimary: true });
+        continue;
+      }
+
+      // Special shorthand: $table->id('custom_id');
+      const customIdMatch = /\$table->id\s*\(\s*['"]([^'"]+)['"]\s*\)/.exec(line);
+      if (customIdMatch) {
+        fieldsMap.set(customIdMatch[1], { name: customIdMatch[1], type: "id", isPrimary: true });
+        continue;
+      }
+
+      // Special shorthand: $table->timestamps();
+      if (/\$table->timestamps\s*\(/.test(line)) {
+        if (!fieldsMap.has("created_at")) {
+          fieldsMap.set("created_at", { name: "created_at", type: "timestamp", nullable: true });
+        }
+        if (!fieldsMap.has("updated_at")) {
+          fieldsMap.set("updated_at", { name: "updated_at", type: "timestamp", nullable: true });
+        }
+        continue;
+      }
+
+      // Special shorthand: $table->softDeletes();
+      if (/\$table->softDeletes\s*\(/.test(line)) {
+        if (!fieldsMap.has("deleted_at")) {
+          fieldsMap.set("deleted_at", { name: "deleted_at", type: "timestamp", nullable: true });
+        }
+        continue;
+      }
+
+      // Special shorthand: $table->rememberToken();
+      if (/\$table->rememberToken\s*\(/.test(line)) {
+        if (!fieldsMap.has("remember_token")) {
+          fieldsMap.set("remember_token", { name: "remember_token", type: "string", nullable: true });
+        }
+        continue;
+      }
+
+      // Standard column definitions: $table->type('column_name', ...)
+      const colMatch = /\$table->([a-zA-Z0-9_]+)\s*\(\s*['"]([^'"]+)['"]/.exec(line);
+      if (colMatch) {
+        const type = colMatch[1];
+        const name = colMatch[2];
+
+        // Skip non-column fluent methods like foreign, dropColumn, index, primary
+        if (["index", "unique", "primary", "foreign", "dropColumn", "dropForeign"].includes(type)) {
+          continue;
+        }
+
+        const nullable = line.includes("->nullable()");
+        const isPrimary = type === "increments" || type === "bigIncrements" || line.includes("->primary()");
+        const isForeign = type.startsWith("foreign") || name.endsWith("_id");
+
+        fieldsMap.set(name, {
+          name,
+          type,
+          nullable: nullable || undefined,
+          isPrimary: isPrimary || undefined,
+          isForeign: isForeign || undefined,
+        });
+      }
+    }
+  }
+}

package/src/core/parser/schema/providers/prisma-schema-provider.ts

@@ -0,0 +1,89 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type {
+  SchemaFieldSummary,
+  SchemaMetadata,
+  StackSchemaProvider,
+} from "../schema-provider.interface.ts";
+
+export class PrismaSchemaProvider implements StackSchemaProvider {
+  public readonly id = "prisma";
+  public readonly name = "Prisma Schema Provider";
+
+  public canHandle(projectRoot: string): boolean {
+    return (
+      fs.existsSync(path.join(projectRoot, "prisma", "schema.prisma")) ||
+      fs.existsSync(path.join(projectRoot, "schema.prisma"))
+    );
+  }
+
+  public resolveEntitySchema(
+    projectRoot: string,
+    entitySymbol: string,
+    _entityFilePath?: string
+  ): SchemaMetadata | null {
+    const candidatePaths = [
+      path.join(projectRoot, "prisma", "schema.prisma"),
+      path.join(projectRoot, "schema.prisma"),
+    ];
+
+    let schemaPath: string | null = null;
+    for (const p of candidatePaths) {
+      if (fs.existsSync(p)) {
+        schemaPath = p;
+        break;
+      }
+    }
+
+    if (!schemaPath) return null;
+
+    try {
+      const content = fs.readFileSync(schemaPath, "utf-8");
+      const modelRegex = new RegExp(`model\\s+${entitySymbol}\\s*\\{([^}]+)\\}`, "m");
+      const match = modelRegex.exec(content);
+      if (!match) return null;
+
+      const body = match[1];
+      const lines = body.split("\n");
+      const fields: SchemaFieldSummary[] = [];
+
+      for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("//") || line.startsWith("@@")) continue;
+
+        // Pattern: fieldName FieldType attributes...
+        const parts = line.split(/\s+/);
+        if (parts.length >= 2) {
+          const name = parts[0];
+          let type = parts[1];
+          const nullable = type.endsWith("?");
+          if (nullable) {
+            type = type.slice(0, -1);
+          }
+
+          const isPrimary = line.includes("@id");
+          const isForeign = line.includes("@relation");
+
+          fields.push({
+            name,
+            type,
+            nullable: nullable || undefined,
+            isPrimary: isPrimary || undefined,
+            isForeign: isForeign || undefined,
+          });
+        }
+      }
+
+      if (fields.length === 0) return null;
+
+      return {
+        entityName: entitySymbol,
+        tableName: entitySymbol.toLowerCase(),
+        schemaSourceFile: path.relative(projectRoot, schemaPath),
+        fields,
+      };
+    } catch {
+      return null;
+    }
+  }
+}

package/src/core/parser/schema/schema-provider-registry.ts

@@ -0,0 +1,43 @@
+import type {
+  SchemaMetadata,
+  StackSchemaProvider,
+} from "./schema-provider.interface.ts";
+import { LaravelMigrationSchemaProvider } from "./providers/laravel-migration-provider.ts";
+import { PrismaSchemaProvider } from "./providers/prisma-schema-provider.ts";
+
+export class SchemaProviderRegistry {
+  private static providers: StackSchemaProvider[] = [
+    new LaravelMigrationSchemaProvider(),
+    new PrismaSchemaProvider(),
+  ];
+
+  /**
+   * Registers a custom schema provider.
+   */
+  public static register(provider: StackSchemaProvider): void {
+    this.providers.unshift(provider);
+  }
+
+  /**
+   * Resolves physical schema metadata across all registered providers.
+   */
+  public static resolveSchema(
+    projectRoot: string,
+    entitySymbol: string,
+    entityFilePath?: string
+  ): SchemaMetadata | null {
+    for (const provider of this.providers) {
+      if (provider.canHandle(projectRoot)) {
+        try {
+          const res = provider.resolveEntitySchema(projectRoot, entitySymbol, entityFilePath);
+          if (res && !(res instanceof Promise)) {
+            return res;
+          }
+        } catch {
+          // Graceful fallback
+        }
+      }
+    }
+    return null;
+  }
+}

package/src/core/parser/schema/schema-provider.interface.ts

@@ -0,0 +1,33 @@
+export interface SchemaFieldSummary {
+  name: string;
+  type: string;
+  nullable?: boolean;
+  isPrimary?: boolean;
+  isForeign?: boolean;
+}
+
+export interface SchemaMetadata {
+  entityName: string;
+  tableName: string;
+  schemaSourceFile: string;
+  fields: SchemaFieldSummary[];
+}
+
+export interface StackSchemaProvider {
+  readonly id: string;
+  readonly name: string;
+
+  /**
+   * Determines if this schema provider can handle the project.
+   */
+  canHandle(projectRoot: string): boolean;
+
+  /**
+   * Resolves physical schema metadata (table name, source file, fields) for a given entity symbol.
+   */
+  resolveEntitySchema(
+    projectRoot: string,
+    entitySymbol: string,
+    entityFilePath?: string
+  ): Promise<SchemaMetadata | null> | SchemaMetadata | null;
+}

package/src/core/resolver/path-resolver.ts

@@ -1,147 +1,147 @@
-import { existsSync, statSync } from "node:fs";
-import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
-
-export const PROJECT_ROOT_MARKERS = [
-  "package.json",
-  "composer.json",
-  "go.mod",
-  "pyproject.toml",
-  "Cargo.toml",
-  ".git",
-  ".septum",
-  "pnpm-workspace.yaml",
-  "lerna.json",
-  "tsconfig.json",
-  "jsconfig.json",
-];
-
-let lastKnownProjectRoot: string | undefined;
-
-/**
- * Normalizes and canonicalizes a path for cross-platform consistency.
- * On Windows, uppercases drive letters (e.g. "c:\" -> "C:\") to eliminate map lookup misses.
- */
-export function canonicalizePath(targetPath: string): string {
-  if (!targetPath || typeof targetPath !== "string") {
-    return targetPath;
-  }
-  let abs = normalize(resolve(targetPath));
-  if (process.platform === "win32") {
-    abs = abs.replace(/^[a-zA-Z]:/, (m) => m.toUpperCase());
-  }
-  return abs;
-}
-
-export function setLastKnownProjectRoot(root: string): void {
-  if (root && typeof root === "string") {
-    lastKnownProjectRoot = canonicalizePath(root);
-  }
-}
-
-export function getLastKnownProjectRoot(): string | undefined {
-  return lastKnownProjectRoot;
-}
-
-export function clearLastKnownProjectRoot(): void {
-  lastKnownProjectRoot = undefined;
-}
-
-/**
- * Checks whether a given directory is an MCP host / IDE installation directory
- * (e.g. Antigravity Electron install directory) rather than a user project codebase.
- */
-export function isAppHostDirectory(dirPath: string): boolean {
-  try {
-    const norm = dirPath.toLowerCase().replace(/\\/g, "/");
-    if (norm.includes("/antigravity") || norm.includes("/appdata/local/programs/antigravity")) {
-      // Check if it has Electron app runtime signatures
-      if (
-        existsSync(join(dirPath, "resources", "app.asar")) ||
-        existsSync(join(dirPath, "resources", "app.asar.unpacked")) ||
-        existsSync(join(dirPath, "locales"))
-      ) {
-        return true;
-      }
-    }
-  } catch {
-    // Ignore error
-  }
-  return false;
-}
-
-/**
- * Discovers the project root directory by walking up looking for marker files.
- */
-export function findProjectRoot(fromPath: string): string {
-  try {
-    let dir = resolve(fromPath);
-
-    if (existsSync(dir)) {
-      const stat = statSync(dir);
-      if (!stat.isDirectory()) {
-        dir = dirname(dir);
-      }
-    } else {
-      dir = dirname(dir);
-    }
-
-    let current = dir;
-    while (true) {
-      // Don't treat an app host directory as a project root
-      if (!isAppHostDirectory(current)) {
-        for (const marker of PROJECT_ROOT_MARKERS) {
-          if (existsSync(join(current, marker))) {
-            return canonicalizePath(current);
-          }
-        }
-      }
-
-      const parent = dirname(current);
-      if (parent === current) break;
-      current = parent;
-    }
-  } catch {
-    // Filesystem traversal error fallback
-  }
-
-  return canonicalizePath(dirname(resolve(fromPath)));
-}
-
-/**
- * Ergonomically resolves the active workspace root:
- * 1. Explicit pathHint (if provided and valid).
- * 2. SEPTUM_WORKSPACE_ROOT environment variable.
- * 3. lastKnownProjectRoot (if cached from earlier tool calls).
- * 4. findProjectRoot from process.cwd() (if not an app host directory).
- */
-export function resolveWorkspaceRoot(pathHint?: string): string {
-  if (pathHint && typeof pathHint === "string" && pathHint.trim()) {
-    const trimmed = pathHint.trim().replace(/^['"]|['"]$/g, "");
-    const candidate = findProjectRoot(trimmed);
-    if (candidate && existsSync(candidate) && !isAppHostDirectory(candidate)) {
-      setLastKnownProjectRoot(candidate);
-      return candidate;
-    }
-  }
-
-  const envRoot = process.env.SEPTUM_WORKSPACE_ROOT || process.env.WORKSPACE_ROOT;
-  if (envRoot && existsSync(envRoot) && !isAppHostDirectory(envRoot)) {
-    const candidate = canonicalizePath(envRoot);
-    setLastKnownProjectRoot(candidate);
-    return candidate;
-  }
-
-  if (lastKnownProjectRoot && existsSync(lastKnownProjectRoot)) {
-    return lastKnownProjectRoot;
-  }
-
-  const cwd = process.cwd();
-  if (!isAppHostDirectory(cwd)) {
-    const candidate = findProjectRoot(cwd);
-    setLastKnownProjectRoot(candidate);
-    return candidate;
-  }
-
-  // Fallback if inside app host directory: keep looking in lastKnown or return cwd
-  return canonicalizePath(cwd);
-}
+import { existsSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
+
+export const PROJECT_ROOT_MARKERS = [
+  "package.json",
+  "composer.json",
+  "go.mod",
+  "pyproject.toml",
+  "Cargo.toml",
+  ".git",
+  ".septum",
+  "pnpm-workspace.yaml",
+  "lerna.json",
+  "tsconfig.json",
+  "jsconfig.json",
+];
+
+let lastKnownProjectRoot: string | undefined;
+
+/**
+ * Normalizes and canonicalizes a path for cross-platform consistency.
+ * On Windows, uppercases drive letters (e.g. "c:\" -> "C:\") to eliminate map lookup misses.
+ */
+export function canonicalizePath(targetPath: string): string {
+  if (!targetPath || typeof targetPath !== "string") {
+    return targetPath;
+  }
+  let abs = normalize(resolve(targetPath));
+  if (process.platform === "win32") {
+    abs = abs.replace(/^[a-zA-Z]:/, (m) => m.toUpperCase());
+  }
+  return abs;
+}
+
+export function setLastKnownProjectRoot(root: string): void {
+  if (root && typeof root === "string") {
+    lastKnownProjectRoot = canonicalizePath(root);
+  }
+}
+
+export function getLastKnownProjectRoot(): string | undefined {
+  return lastKnownProjectRoot;
+}
+
+export function clearLastKnownProjectRoot(): void {
+  lastKnownProjectRoot = undefined;
+}
+
+/**
+ * Checks whether a given directory is an MCP host / IDE installation directory
+ * (e.g. Antigravity Electron install directory) rather than a user project codebase.
+ */
+export function isAppHostDirectory(dirPath: string): boolean {
+  try {
+    const norm = dirPath.toLowerCase().replace(/\\/g, "/");
+    if (norm.includes("/antigravity") || norm.includes("/appdata/local/programs/antigravity")) {
+      // Check if it has Electron app runtime signatures
+      if (
+        existsSync(join(dirPath, "resources", "app.asar")) ||
+        existsSync(join(dirPath, "resources", "app.asar.unpacked")) ||
+        existsSync(join(dirPath, "locales"))
+      ) {
+        return true;
+      }
+    }
+  } catch {
+    // Ignore error
+  }
+  return false;
+}
+
+/**
+ * Discovers the project root directory by walking up looking for marker files.
+ */
+export function findProjectRoot(fromPath: string): string {
+  try {
+    let dir = resolve(fromPath);
+
+    if (existsSync(dir)) {
+      const stat = statSync(dir);
+      if (!stat.isDirectory()) {
+        dir = dirname(dir);
+      }
+    } else {
+      dir = dirname(dir);
+    }
+
+    let current = dir;
+    while (true) {
+      // Don't treat an app host directory as a project root
+      if (!isAppHostDirectory(current)) {
+        for (const marker of PROJECT_ROOT_MARKERS) {
+          if (existsSync(join(current, marker))) {
+            return canonicalizePath(current);
+          }
+        }
+      }
+
+      const parent = dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  } catch {
+    // Filesystem traversal error fallback
+  }
+
+  return canonicalizePath(dirname(resolve(fromPath)));
+}
+
+/**
+ * Ergonomically resolves the active workspace root:
+ * 1. Explicit pathHint (if provided and valid).
+ * 2. SEPTUM_WORKSPACE_ROOT environment variable.
+ * 3. lastKnownProjectRoot (if cached from earlier tool calls).
+ * 4. findProjectRoot from process.cwd() (if not an app host directory).
+ */
+export function resolveWorkspaceRoot(pathHint?: string): string {
+  if (pathHint && typeof pathHint === "string" && pathHint.trim()) {
+    const trimmed = pathHint.trim().replace(/^['"]|['"]$/g, "");
+    const candidate = findProjectRoot(trimmed);
+    if (candidate && existsSync(candidate) && !isAppHostDirectory(candidate)) {
+      setLastKnownProjectRoot(candidate);
+      return candidate;
+    }
+  }
+
+  const envRoot = process.env.SEPTUM_WORKSPACE_ROOT || process.env.WORKSPACE_ROOT;
+  if (envRoot && existsSync(envRoot) && !isAppHostDirectory(envRoot)) {
+    const candidate = canonicalizePath(envRoot);
+    setLastKnownProjectRoot(candidate);
+    return candidate;
+  }
+
+  if (lastKnownProjectRoot && existsSync(lastKnownProjectRoot)) {
+    return lastKnownProjectRoot;
+  }
+
+  const cwd = process.cwd();
+  if (!isAppHostDirectory(cwd)) {
+    const candidate = findProjectRoot(cwd);
+    setLastKnownProjectRoot(candidate);
+    return candidate;
+  }
+
+  // Fallback if inside app host directory: keep looking in lastKnown or return cwd
+  return canonicalizePath(cwd);
+}