@everystack/mcp 0.2.0

package/src/tools/schema-analyze.ts

@@ -0,0 +1,410 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+interface ColumnInfo {
+  name: string;
+  dbName: string;
+  type: string;
+  modifiers: string[];
+}
+
+interface TableInfo {
+  name: string;
+  exportName: string;
+  columns: ColumnInfo[];
+  file: string;
+}
+
+interface RelationInfo {
+  name: string;
+  table: string;
+  type: 'one' | 'many';
+  fields: string[];
+  references: string[];
+  relationName?: string;
+}
+
+interface HandlerConfig {
+  exposedTables: string[];
+  hiddenColumns: Record<string, string[]>;
+  protectedFields: Record<string, string[]>;
+  rowOwnership: Record<string, { column: string; userField: string }>;
+  softDelete: { tables: string[] };
+  pgSettings: boolean;
+  relations: Record<string, Record<string, unknown>>;
+  publicRoutes: string[];
+  publicRpc: string[];
+}
+
+interface SchemaAnalysis {
+  tables: TableInfo[];
+  relations: RelationInfo[];
+  handlerConfig: Partial<HandlerConfig> | null;
+  issues: string[];
+  suggestions: string[];
+}
+
+/**
+ * Extract a brace-balanced block starting from an opening brace.
+ */
+function extractBraceBlock(source: string, openIndex: number): string {
+  let depth = 0;
+  for (let i = openIndex; i < source.length; i++) {
+    if (source[i] === '{') depth++;
+    if (source[i] === '}') depth--;
+    if (depth === 0) return source.slice(openIndex + 1, i);
+  }
+  return source.slice(openIndex + 1);
+}
+
+/**
+ * Parse pgTable declarations from a TypeScript source file.
+ * Uses regex + brace-depth extraction to handle nested objects (e.g., { withTimezone: true }).
+ */
+function parseTables(source: string, file: string): TableInfo[] {
+  const tables: TableInfo[] = [];
+
+  // Find each pgTable declaration
+  const headerRegex = /export\s+const\s+(\w+)\s*=\s*pgTable\(\s*['"]([^'"]+)['"]\s*,\s*\{/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = headerRegex.exec(source)) !== null) {
+    const exportName = match[1];
+    const dbName = match[2];
+    // The opening brace position is at the end of the match minus 1
+    const openBrace = match.index + match[0].length - 1;
+    const columnsBlock = extractBraceBlock(source, openBrace);
+
+    const columns = parseColumns(columnsBlock);
+    tables.push({ name: dbName, exportName, columns, file });
+  }
+
+  return tables;
+}
+
+function parseColumns(block: string): ColumnInfo[] {
+  const columns: ColumnInfo[] = [];
+  // Match: columnName: type('db_name', ...optional args...)...chain...
+  // The type call may have extra args after the string (e.g., timestamp('x', { withTimezone: true }))
+  const colRegex = /(\w+)\s*:\s*(\w+)\(\s*['"]([^'"]+)['"][^)]*\)([\s\S]*?)(?=\n\s*\w+\s*:|$)/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = colRegex.exec(block)) !== null) {
+    const name = match[1];
+    const type = match[2];
+    const dbName = match[3];
+    const rest = match[4];
+
+    const modifiers: string[] = [];
+    if (rest.includes('.primaryKey()')) modifiers.push('primaryKey');
+    if (rest.includes('.notNull()')) modifiers.push('notNull');
+    if (rest.includes('.unique()')) modifiers.push('unique');
+    if (rest.includes('.defaultNow()')) modifiers.push('defaultNow');
+    if (rest.includes('.defaultRandom()')) modifiers.push('defaultRandom');
+    if (rest.includes('.default(')) modifiers.push('default');
+    if (rest.includes('.references(')) modifiers.push('references');
+
+    columns.push({ name, dbName, type, modifiers });
+  }
+
+  return columns;
+}
+
+/**
+ * Parse relations() declarations from source.
+ */
+function parseRelations(source: string): RelationInfo[] {
+  const relations: RelationInfo[] = [];
+
+  // Match: export const nameRelations = relations(tableName, ({ one, many }) => ({
+  const relBlockRegex = /export\s+const\s+\w+\s*=\s*relations\(\s*(\w+)\s*,\s*\(\s*\{[^}]*\}\s*\)\s*=>\s*\(\{([\s\S]*?)\}\)\s*\)/g;
+  let blockMatch: RegExpExecArray | null;
+
+  while ((blockMatch = relBlockRegex.exec(source)) !== null) {
+    const table = blockMatch[1];
+    const body = blockMatch[2];
+
+    // Match individual relations: name: one(target, { fields: [...], references: [...] })
+    const relRegex = /(\w+)\s*:\s*(one|many)\(\s*(\w+)(?:\s*,\s*\{([^}]*)\})?\s*\)/g;
+    let relMatch: RegExpExecArray | null;
+
+    while ((relMatch = relRegex.exec(body)) !== null) {
+      const name = relMatch[1];
+      const type = relMatch[2] as 'one' | 'many';
+      const target = relMatch[3];
+      const opts = relMatch[4] || '';
+
+      const fields: string[] = [];
+      const references: string[] = [];
+
+      // Parse fields: [table.column]
+      const fieldsMatch = opts.match(/fields:\s*\[([^\]]+)\]/);
+      if (fieldsMatch) {
+        fields.push(...fieldsMatch[1].split(',').map((f) => f.trim().replace(/.*\./, '')));
+      }
+
+      const refsMatch = opts.match(/references:\s*\[([^\]]+)\]/);
+      if (refsMatch) {
+        references.push(...refsMatch[1].split(',').map((r) => r.trim().replace(/.*\./, '')));
+      }
+
+      const nameMatch = opts.match(/relationName:\s*['"]([^'"]+)['"]/);
+
+      relations.push({
+        name,
+        table: target,
+        type,
+        fields,
+        references,
+        ...(nameMatch ? { relationName: nameMatch[1] } : {}),
+      });
+    }
+  }
+
+  return relations;
+}
+
+/**
+ * Parse handler configuration from the server handler/plugin file.
+ */
+function parseHandlerConfig(source: string): Partial<HandlerConfig> {
+  const config: Partial<HandlerConfig> = {};
+
+  // exposedTables
+  const exposedMatch = source.match(/exposedTables:\s*\[([\s\S]*?)\]/);
+  if (exposedMatch) {
+    config.exposedTables = exposedMatch[1]
+      .match(/['"]([^'"]+)['"]/g)
+      ?.map((s) => s.replace(/['"]/g, '')) ?? [];
+  }
+
+  // hiddenColumns
+  const hiddenMatch = source.match(/hiddenColumns:\s*\{([\s\S]*?)\}/);
+  if (hiddenMatch) {
+    config.hiddenColumns = {};
+    const entries = hiddenMatch[1].matchAll(/(\w+):\s*\[([\s\S]*?)\]/g);
+    for (const entry of entries) {
+      config.hiddenColumns[entry[1]] = entry[2]
+        .match(/['"]([^'"]+)['"]/g)
+        ?.map((s) => s.replace(/['"]/g, '')) ?? [];
+    }
+  }
+
+  // protectedFields
+  const protectedMatch = source.match(/protectedFields:\s*\{([\s\S]*?)\}/);
+  if (protectedMatch) {
+    config.protectedFields = {};
+    const entries = protectedMatch[1].matchAll(/(\w+):\s*\[([\s\S]*?)\]/g);
+    for (const entry of entries) {
+      config.protectedFields[entry[1]] = entry[2]
+        .match(/['"]([^'"]+)['"]/g)
+        ?.map((s) => s.replace(/['"]/g, '')) ?? [];
+    }
+  }
+
+  // rowOwnership — scan for entries after the rowOwnership key
+  if (/rowOwnership\s*:/.test(source)) {
+    config.rowOwnership = {};
+    // Extract everything from rowOwnership: { to the matching closing }
+    const startIdx = source.indexOf('rowOwnership');
+    if (startIdx !== -1) {
+      // Find the opening brace
+      const braceStart = source.indexOf('{', startIdx);
+      if (braceStart !== -1) {
+        // Find the matching closing brace (handle one level of nesting)
+        let depth = 0;
+        let braceEnd = braceStart;
+        for (let i = braceStart; i < source.length; i++) {
+          if (source[i] === '{') depth++;
+          if (source[i] === '}') depth--;
+          if (depth === 0) { braceEnd = i; break; }
+        }
+        const block = source.slice(braceStart + 1, braceEnd);
+        const entryRegex = /(\w+):\s*\{\s*column:\s*['"]([^'"]+)['"]\s*,\s*userField:\s*['"]([^'"]+)['"]\s*\}/g;
+        const entries = block.matchAll(entryRegex);
+        for (const entry of entries) {
+          config.rowOwnership[entry[1]] = { column: entry[2], userField: entry[3] };
+        }
+      }
+    }
+  }
+
+  // softDelete
+  const softDeleteMatch = source.match(/softDelete:\s*\{[\s\S]*?tables:\s*\[([\s\S]*?)\]/);
+  if (softDeleteMatch) {
+    config.softDelete = {
+      tables: softDeleteMatch[1]
+        .match(/['"]([^'"]+)['"]/g)
+        ?.map((s) => s.replace(/['"]/g, '')) ?? [],
+    };
+  }
+
+  // pgSettings
+  config.pgSettings = /pgSettings\s*:/.test(source);
+
+  // publicRoutes
+  const publicRoutesMatch = source.match(/publicRoutes:\s*\[([\s\S]*?)\]/);
+  if (publicRoutesMatch) {
+    config.publicRoutes = publicRoutesMatch[1]
+      .match(/['"]([^'"]+)['"]/g)
+      ?.map((s) => s.replace(/['"]/g, '')) ?? [];
+  }
+
+  // publicRpc
+  const publicRpcMatch = source.match(/publicRpc:\s*\[([\s\S]*?)\]/);
+  if (publicRpcMatch) {
+    config.publicRpc = publicRpcMatch[1]
+      .match(/['"]([^'"]+)['"]/g)
+      ?.map((s) => s.replace(/['"]/g, '')) ?? [];
+  }
+
+  return config;
+}
+
+export function analyzeSchema(projectPath: string): SchemaAnalysis {
+  const issues: string[] = [];
+  const suggestions: string[] = [];
+  const allTables: TableInfo[] = [];
+  const allRelations: RelationInfo[] = [];
+
+  // Find schema files
+  const dbDir = join(projectPath, 'db');
+  const schemaFiles: string[] = [];
+
+  if (existsSync(dbDir)) {
+    try {
+      const files = readdirSync(dbDir);
+      for (const f of files) {
+        if (f.endsWith('.ts') && !f.endsWith('.test.ts') && !f.startsWith('seed')) {
+          schemaFiles.push(join(dbDir, f));
+        }
+      }
+    } catch {
+      // ignore read errors
+    }
+  }
+
+  if (schemaFiles.length === 0) {
+    return {
+      tables: [],
+      relations: [],
+      handlerConfig: null,
+      issues: ['No schema files found in db/ directory'],
+      suggestions: ['Create db/schema.ts with your Drizzle pgTable definitions'],
+    };
+  }
+
+  // Parse each schema file
+  for (const file of schemaFiles) {
+    try {
+      const source = readFileSync(file, 'utf-8');
+      const relativePath = file.replace(projectPath + '/', '');
+      allTables.push(...parseTables(source, relativePath));
+      allRelations.push(...parseRelations(source));
+    } catch {
+      issues.push(`Failed to read ${file}`);
+    }
+  }
+
+  // Find and parse handler config
+  let handlerConfig: Partial<HandlerConfig> | null = null;
+  const handlerCandidates = [
+    'server/plugins/api.ts',
+    'server/api.ts',
+    'server/handler.ts',
+    'server/index.ts',
+  ];
+
+  for (const candidate of handlerCandidates) {
+    const fullPath = join(projectPath, candidate);
+    if (existsSync(fullPath)) {
+      try {
+        const source = readFileSync(fullPath, 'utf-8');
+        if (source.includes('createHandler')) {
+          handlerConfig = parseHandlerConfig(source);
+          break;
+        }
+      } catch {
+        // continue to next candidate
+      }
+    }
+  }
+
+  // Cross-reference analysis
+  if (handlerConfig?.exposedTables) {
+    const tableNames = allTables.map((t) => t.name);
+    for (const exposed of handlerConfig.exposedTables) {
+      // Check both db name and export name
+      const found = allTables.some((t) => t.name === exposed || t.exportName === exposed);
+      if (!found) {
+        issues.push(`exposedTables includes '${exposed}' but no matching pgTable definition found in schema`);
+      }
+    }
+
+    // Tables defined but not exposed
+    for (const table of allTables) {
+      if (!handlerConfig.exposedTables.includes(table.name) &&
+          !handlerConfig.exposedTables.includes(table.exportName)) {
+        suggestions.push(`Table '${table.name}' is defined in schema but not in exposedTables — intentional?`);
+      }
+    }
+  }
+
+  // Check for soft delete columns
+  if (handlerConfig?.softDelete?.tables) {
+    for (const tableName of handlerConfig.softDelete.tables) {
+      const table = allTables.find((t) => t.name === tableName || t.exportName === tableName);
+      if (table) {
+        const hasDeletedAt = table.columns.some((c) => c.name === 'deletedAt' || c.dbName === 'deleted_at');
+        if (!hasDeletedAt) {
+          issues.push(`Table '${tableName}' is in softDelete.tables but has no deletedAt column`);
+        }
+      }
+    }
+  }
+
+  // Check for rowOwnership references
+  if (handlerConfig?.rowOwnership) {
+    for (const [tableName, ownership] of Object.entries(handlerConfig.rowOwnership)) {
+      const table = allTables.find((t) => t.name === tableName || t.exportName === tableName);
+      if (table) {
+        const hasCol = table.columns.some(
+          (c) => c.name === ownership.column || c.dbName === ownership.column,
+        );
+        if (!hasCol) {
+          issues.push(`rowOwnership for '${tableName}' references column '${ownership.column}' which doesn't exist`);
+        }
+      }
+    }
+  }
+
+  // pgSettings check
+  if (!handlerConfig?.pgSettings && allTables.length > 0) {
+    suggestions.push('No pgSettings configured — RLS policies cannot read JWT claims without it');
+  }
+
+  // Tables without primary keys
+  for (const table of allTables) {
+    const hasPk = table.columns.some((c) => c.modifiers.includes('primaryKey'));
+    if (!hasPk) {
+      // Could be a composite primary key (defined in table config, not column)
+      suggestions.push(`Table '${table.name}' — no single-column primaryKey() detected (may use composite key)`);
+    }
+  }
+
+  // Tables with timestamps
+  for (const table of allTables) {
+    const hasCreatedAt = table.columns.some((c) => c.dbName === 'created_at');
+    if (!hasCreatedAt) {
+      suggestions.push(`Table '${table.name}' has no created_at column — recommended for audit`);
+    }
+  }
+
+  return {
+    tables: allTables,
+    relations: allRelations,
+    handlerConfig,
+    issues,
+    suggestions,
+  };
+}