carto-md 1.0.0

package/src/extractors/languages/prisma.js

@@ -0,0 +1,80 @@
+/**
+ * Prisma schema plugin — handles .prisma files.
+ * Pure regex — Prisma schema is simple enough.
+ */
+module.exports = {
+  name: 'prisma',
+  extensions: ['.prisma'],
+  extract(content, filename) {
+    try {
+      const models = extractPrismaModels(content);
+      const dbTables = extractPrismaDBTables(content);
+      return {
+        routes:      [],
+        models:      models,
+        functions:   [],
+        envVars:     [],
+        dbTables:    dbTables,
+        fetches:     [],
+        storageKeys: [],
+      };
+    } catch (err) {
+      console.warn(`[CARTO] prisma plugin error on ${filename}: ${err.message}`);
+      return { routes: [], models: [], functions: [], envVars: [], dbTables: [], fetches: [], storageKeys: [] };
+    }
+  }
+};
+
+function extractPrismaModels(content) {
+  const models = [];
+  const modelPattern = /^model\s+(\w+)\s*\{([^}]+)\}/gm;
+
+  let match;
+  while ((match = modelPattern.exec(content)) !== null) {
+    const className = match[1];
+    const body = match[2];
+    const fields = [];
+
+    const lines = body.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      // Skip empty lines, comments, and @@directives
+      if (!trimmed || trimmed.startsWith('//') || trimmed.startsWith('@@')) continue;
+
+      const fieldMatch = trimmed.match(/^(\w+)\s+(\w+[\[\]?]*)/);
+      if (fieldMatch) {
+        fields.push({ name: fieldMatch[1], type: fieldMatch[2] });
+      }
+    }
+
+    models.push({ className, fields });
+  }
+
+  return models;
+}
+
+function extractPrismaDBTables(content) {
+  const tables = [];
+  const modelPattern = /^model\s+(\w+)\s*\{([^}]+)\}/gm;
+
+  let match;
+  while ((match = modelPattern.exec(content)) !== null) {
+    const modelName = match[1];
+    const body = match[2];
+
+    // Check for @@map('table_name')
+    const mapMatch = body.match(/@@map\s*\(\s*['"]([^'"]+)['"]\s*\)/);
+    const tableName = mapMatch ? mapMatch[1] : toSnakeCase(modelName);
+
+    tables.push({ tableName, modelName });
+  }
+
+  return tables;
+}
+
+function toSnakeCase(str) {
+  return str
+    .replace(/([A-Z])/g, '_$1')
+    .toLowerCase()
+    .replace(/^_/, '');
+}

package/src/extractors/languages/python.js

@@ -0,0 +1,26 @@
+const { extractRoutes } = require('../routes');
+const { extractModels } = require('../models');
+const { extractFunctions } = require('../functions');
+const { extractEnvVars } = require('../envvars');
+const { extractDBTables } = require('../dbtables');
+
+module.exports = {
+  name: 'python',
+  extensions: ['.py'],
+  extract(content, filename) {
+    try {
+      return {
+        routes:      extractRoutes(content),
+        models:      extractModels(content),
+        functions:   extractFunctions(content, filename),
+        envVars:     extractEnvVars(content),
+        dbTables:    extractDBTables(content),
+        fetches:     [],
+        storageKeys: [],
+      };
+    } catch (err) {
+      console.warn(`[CARTO] python plugin error on ${filename}: ${err.message}`);
+      return { routes: [], models: [], functions: [], envVars: [], dbTables: [], fetches: [], storageKeys: [] };
+    }
+  }
+};

package/src/extractors/languages/typescript.js

@@ -0,0 +1,235 @@
+const parser = require('@babel/parser');
+const jsPlugin = require('./javascript');
+
+const TS_PARSE_OPTIONS = {
+  sourceType: 'module',
+  allowImportExportEverywhere: true,
+  allowReturnOutsideFunction: true,
+  plugins: ['typescript', 'jsx', 'decorators-legacy', 'classProperties', 'optionalChaining', 'nullishCoalescingOperator']
+};
+
+module.exports = {
+  name: 'typescript',
+  extensions: ['.ts', '.tsx'],
+  extract(content, filename) {
+    let ast;
+    try {
+      ast = parser.parse(content, TS_PARSE_OPTIONS);
+    } catch (err) {
+      console.warn(`[CARTO] TS parse failed on ${filename}: ${err.message} — skipping`);
+      return { routes: [], models: [], functions: [], envVars: [], dbTables: [], fetches: [], storageKeys: [] };
+    }
+
+    return {
+      routes:      jsPlugin._extractExpressRoutes(ast, filename),
+      models:      extractTSInterfaces(ast),
+      functions:   extractTSFunctions(ast),
+      envVars:     jsPlugin._extractProcessEnv(ast),
+      dbTables:    [],
+      fetches:     jsPlugin._extractJSFetches(ast),
+      storageKeys: [],
+    };
+  }
+};
+
+// ---------------------------------------------------------------------------
+// AST traversal helper
+// ---------------------------------------------------------------------------
+
+function walk(node, visitor) {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node)) {
+    for (const child of node) walk(child, visitor);
+    return;
+  }
+  if (node.type) {
+    visitor(node);
+  }
+  for (const key of Object.keys(node)) {
+    if (key === 'leadingComments' || key === 'trailingComments' || key === 'innerComments') continue;
+    const child = node[key];
+    if (child && typeof child === 'object') {
+      walk(child, visitor);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// TS function extraction (with return types)
+// ---------------------------------------------------------------------------
+
+function extractTSFunctions(ast) {
+  const functions = [];
+
+  if (!ast.program || !ast.program.body) return functions;
+
+  for (const node of ast.program.body) {
+    extractFuncFromNode(node, functions);
+  }
+
+  return functions;
+}
+
+function extractFuncFromNode(node, functions) {
+  // FunctionDeclaration
+  if (node.type === 'FunctionDeclaration' && node.id) {
+    const name = node.id.name;
+    if (shouldSkip(name, node.params)) return;
+    functions.push({
+      name,
+      params: extractTSParams(node.params),
+      returnType: extractReturnType(node)
+    });
+  }
+
+  // VariableDeclaration
+  if (node.type === 'VariableDeclaration') {
+    for (const decl of node.declarations) {
+      if (!decl.id || !decl.id.name || !decl.init) continue;
+      if (decl.init.type === 'ArrowFunctionExpression' || decl.init.type === 'FunctionExpression') {
+        const name = decl.id.name;
+        if (shouldSkip(name, decl.init.params)) continue;
+        functions.push({
+          name,
+          params: extractTSParams(decl.init.params),
+          returnType: extractReturnType(decl.init)
+        });
+      }
+    }
+  }
+
+  // ExportDefaultDeclaration
+  if (node.type === 'ExportDefaultDeclaration' && node.declaration) {
+    extractFuncFromNode(node.declaration, functions);
+  }
+
+  // ExportNamedDeclaration
+  if (node.type === 'ExportNamedDeclaration' && node.declaration) {
+    extractFuncFromNode(node.declaration, functions);
+  }
+}
+
+function shouldSkip(name, params) {
+  if (name.startsWith('_') && (!params || params.length === 0)) return true;
+  return false;
+}
+
+function extractTSParams(params) {
+  if (!params || params.length === 0) return '\u2014';
+  const names = [];
+  for (const p of params) {
+    if (p.type === 'Identifier') {
+      names.push(p.name);
+    } else if (p.type === 'AssignmentPattern' && p.left && p.left.type === 'Identifier') {
+      names.push(p.left.name);
+    } else if (p.type === 'RestElement' && p.argument && p.argument.type === 'Identifier') {
+      continue; // skip ...args
+    } else if (p.type === 'ObjectPattern') {
+      names.push('{...}');
+    } else if (p.type === 'ArrayPattern') {
+      names.push('[...]');
+    }
+  }
+  return names.length > 0 ? names.join(', ') : '\u2014';
+}
+
+function extractReturnType(funcNode) {
+  // Check for TSTypeAnnotation on the function's returnType
+  if (funcNode.returnType && funcNode.returnType.typeAnnotation) {
+    return typeToString(funcNode.returnType.typeAnnotation);
+  }
+  return '\u2014';
+}
+
+function typeToString(typeNode) {
+  if (!typeNode) return '\u2014';
+
+  switch (typeNode.type) {
+    case 'TSStringKeyword': return 'string';
+    case 'TSNumberKeyword': return 'number';
+    case 'TSBooleanKeyword': return 'boolean';
+    case 'TSVoidKeyword': return 'void';
+    case 'TSAnyKeyword': return 'any';
+    case 'TSNullKeyword': return 'null';
+    case 'TSUndefinedKeyword': return 'undefined';
+    case 'TSNeverKeyword': return 'never';
+    case 'TSObjectKeyword': return 'object';
+    case 'TSUnknownKeyword': return 'unknown';
+    case 'TSTypeReference':
+      if (typeNode.typeName && typeNode.typeName.name) {
+        const generics = typeNode.typeParameters
+          ? `<${typeNode.typeParameters.params.map(typeToString).join(', ')}>`
+          : '';
+        return typeNode.typeName.name + generics;
+      }
+      return '\u2014';
+    case 'TSArrayType':
+      return typeToString(typeNode.elementType) + '[]';
+    case 'TSUnionType':
+      return typeNode.types.map(typeToString).join(' | ');
+    case 'TSIntersectionType':
+      return typeNode.types.map(typeToString).join(' & ');
+    case 'TSTypeLiteral':
+      return 'object';
+    case 'TSFunctionType':
+      return 'Function';
+    default:
+      return '\u2014';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// TS interface/type extraction → same shape as Pydantic models
+// ---------------------------------------------------------------------------
+
+function extractTSInterfaces(ast) {
+  const models = [];
+
+  if (!ast.program || !ast.program.body) return models;
+
+  for (const node of ast.program.body) {
+    let target = node;
+    // Unwrap exports
+    if (node.type === 'ExportNamedDeclaration' && node.declaration) {
+      target = node.declaration;
+    }
+
+    // TSInterfaceDeclaration
+    if (target.type === 'TSInterfaceDeclaration' && target.id) {
+      const className = target.id.name;
+      const fields = [];
+      if (target.body && target.body.body) {
+        for (const member of target.body.body) {
+          if (member.type === 'TSPropertySignature' && member.key) {
+            const name = member.key.name || member.key.value;
+            const type = member.typeAnnotation
+              ? typeToString(member.typeAnnotation.typeAnnotation)
+              : '\u2014';
+            if (name) fields.push({ name, type });
+          }
+        }
+      }
+      models.push({ className, fields });
+    }
+
+    // TSTypeAliasDeclaration with TSTypeLiteral
+    if (target.type === 'TSTypeAliasDeclaration' && target.id && target.typeAnnotation) {
+      if (target.typeAnnotation.type === 'TSTypeLiteral') {
+        const className = target.id.name;
+        const fields = [];
+        for (const member of target.typeAnnotation.members) {
+          if (member.type === 'TSPropertySignature' && member.key) {
+            const name = member.key.name || member.key.value;
+            const type = member.typeAnnotation
+              ? typeToString(member.typeAnnotation.typeAnnotation)
+              : '\u2014';
+            if (name) fields.push({ name, type });
+          }
+        }
+        models.push({ className, fields });
+      }
+    }
+  }
+
+  return models;
+}

package/src/extractors/loader.js

@@ -0,0 +1,67 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * loadLanguagePlugins() → Array<plugin>
+ *
+ * Auto-discovers all .js files in src/extractors/languages/
+ * Validates each has: name (string), extensions (array), extract (function)
+ * Logs a warning and skips any plugin that fails validation or throws on require()
+ */
+function loadLanguagePlugins() {
+  const pluginsDir = path.join(__dirname, 'languages');
+  const plugins = [];
+
+  let files;
+  try {
+    files = fs.readdirSync(pluginsDir).filter(f => f.endsWith('.js'));
+  } catch (err) {
+    console.warn(`[CARTO] Warning: Could not read plugins directory: ${err.message}`);
+    return plugins;
+  }
+
+  for (const file of files) {
+    const fullPath = path.join(pluginsDir, file);
+    try {
+      const plugin = require(fullPath);
+
+      // Validate plugin shape
+      if (typeof plugin.name !== 'string') {
+        console.warn(`[CARTO] Warning: Plugin ${file} missing 'name' (string) — skipping`);
+        continue;
+      }
+      if (!Array.isArray(plugin.extensions)) {
+        console.warn(`[CARTO] Warning: Plugin ${file} missing 'extensions' (array) — skipping`);
+        continue;
+      }
+      if (typeof plugin.extract !== 'function') {
+        console.warn(`[CARTO] Warning: Plugin ${file} missing 'extract' (function) — skipping`);
+        continue;
+      }
+
+      plugins.push(plugin);
+    } catch (err) {
+      console.warn(`[CARTO] Warning: Failed to load plugin ${file}: ${err.message} — skipping`);
+    }
+  }
+
+  return plugins;
+}
+
+/**
+ * getPluginForFile(plugins, filePath) → plugin | null
+ *
+ * Returns the first plugin whose extensions array includes the file's extension.
+ * Returns null if no plugin handles this file type.
+ */
+function getPluginForFile(plugins, filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  for (const plugin of plugins) {
+    if (plugin.extensions.includes(ext)) {
+      return plugin;
+    }
+  }
+  return null;
+}
+
+module.exports = { loadLanguagePlugins, getPluginForFile };

package/src/extractors/models.js

@@ -0,0 +1,40 @@
+/**
+ * Extracts Pydantic model class definitions — class name + fields with types.
+ * Skips method definitions (def ...) to avoid false positives.
+ * Strips inline # comments from field types.
+ */
+function extractModels(content) {
+  const models = [];
+  const classPattern = /^class\s+(\w+)\s*\(.*BaseModel.*\)\s*:/gm;
+  const fieldPattern = /^\s{4}(\w+)\s*:\s*(.+?)(?:\s*=.*)?$/;
+
+  let classMatch;
+  while ((classMatch = classPattern.exec(content)) !== null) {
+    const className = classMatch[1];
+    const classStart = classMatch.index + classMatch[0].length;
+    const fields = [];
+
+    const remaining = content.substring(classStart);
+    const bodyLines = remaining.split('\n');
+
+    for (const line of bodyLines) {
+      // Stop at next top-level definition
+      if (/^class\s/.test(line) || (/^\S/.test(line) && line.trim() !== '')) {
+        break;
+      }
+      // Skip method definitions — prevents false-positive on `def validate_...(self):`
+      if (/^\s{4}def\s/.test(line)) {
+        continue;
+      }
+      const fieldMatch = line.match(fieldPattern);
+      if (fieldMatch) {
+        fields.push({ name: fieldMatch[1], type: fieldMatch[2].replace(/#.*$/, '').trim() });
+      }
+    }
+
+    models.push({ className, fields });
+  }
+  return models;
+}
+
+module.exports = { extractModels };

package/src/extractors/routes.js

@@ -0,0 +1,66 @@
+const fs = require('fs');
+
+/**
+ * Joins multiline decorator expressions into single lines.
+ * Scans for lines starting with @ and, if parentheses are unbalanced,
+ * appends subsequent lines until they balance.
+ */
+function collapseMultilineDecorators(content) {
+  const lines = content.split('\n');
+  const result = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*@/.test(lines[i])) {
+      let combined = lines[i];
+      let openParens = (combined.match(/\(/g) || []).length;
+      let closeParens = (combined.match(/\)/g) || []).length;
+
+      while (openParens > closeParens && i + 1 < lines.length) {
+        i++;
+        combined += ' ' + lines[i].trim();
+        openParens = (combined.match(/\(/g) || []).length;
+        closeParens = (combined.match(/\)/g) || []).length;
+      }
+      result.push(combined);
+    } else {
+      result.push(lines[i]);
+    }
+  }
+  return result.join('\n');
+}
+
+/**
+ * Extracts HTTP route definitions from FastAPI Python files.
+ * Handles @app.get/post/put/delete/patch and @router.get/post/put/delete/patch,
+ * including multiline decorators.
+ */
+function extractRoutes(content) {
+  const routes = [];
+  const decoratorPattern = /@(?:app|router)\.(get|post|put|delete|patch)\s*\(\s*["']([^"']+)["']/gi;
+  const funcPattern = /(?:async\s+)?def\s+(\w+)/;
+
+  const collapsed = collapseMultilineDecorators(content);
+  const lines = collapsed.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const match = decoratorPattern.exec(lines[i]);
+    if (match) {
+      // Look ahead up to 5 lines for the function definition
+      for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {
+        const funcMatch = lines[j].match(funcPattern);
+        if (funcMatch) {
+          routes.push({
+            method: match[1].toUpperCase(),
+            path: match[2],
+            functionName: funcMatch[1]
+          });
+          break;
+        }
+      }
+    }
+    decoratorPattern.lastIndex = 0;
+  }
+  return routes;
+}
+
+module.exports = { extractRoutes, collapseMultilineDecorators };

package/src/security/ignore.js

@@ -0,0 +1,66 @@
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_IGNORE_PATTERNS = [
+  '.env',
+  '.env.*',
+  '*secret*',
+  '*SECRET*',
+  '*password*',
+  '*PASSWORD*',
+  '*credential*',
+  '*CREDENTIAL*',
+  '*private_key*',
+  '*PRIVATE_KEY*',
+  '*.pem',
+  '*.key'
+];
+
+/**
+ * parseCartoIgnore(projectRoot) → isIgnored(filePath) → boolean
+ *
+ * Reads .cartoignore from the project root (if it exists) and merges with defaults.
+ * Returns a function that checks if a file path matches any ignore pattern.
+ */
+function parseCartoIgnore(projectRoot) {
+  let userPatterns = [];
+
+  const ignoreFile = path.join(projectRoot, '.cartoignore');
+  try {
+    const content = fs.readFileSync(ignoreFile, 'utf-8');
+    userPatterns = content
+      .split('\n')
+      .map(line => line.trim())
+      .filter(line => line && !line.startsWith('#'));
+  } catch {
+    // No .cartoignore file — that's fine, use defaults only
+  }
+
+  const allPatterns = [...DEFAULT_IGNORE_PATTERNS, ...userPatterns];
+
+  return function isIgnored(filePath) {
+    const basename = path.basename(filePath);
+    const relativePath = filePath; // can be absolute or relative
+
+    for (const pattern of allPatterns) {
+      if (matchPattern(basename, pattern) || matchPattern(relativePath, pattern)) {
+        return true;
+      }
+    }
+    return false;
+  };
+}
+
+/**
+ * Simple glob matching supporting * as wildcard.
+ */
+function matchPattern(str, pattern) {
+  // Escape regex special chars except *
+  const regexStr = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*');
+  const regex = new RegExp(`^${regexStr}$`, 'i');
+  return regex.test(str);
+}
+
+module.exports = { parseCartoIgnore, DEFAULT_IGNORE_PATTERNS };