carto-md 1.1.3 → 1.1.4

package/CONTRIBUTING.md

@@ -20,13 +20,13 @@ Framework-specific route and model extraction lives in `src/extractors/`. Each f
 
 Currently supported:
 - **JS/TS**: Express, Next.js (App + Pages Router), tRPC, Drizzle, Zod
-- **Python**: FastAPI, Pydantic, SQLAlchemy, Django (models + URLs)
-- **Go**: Gin, Echo, Chi, net/http
+- **Python**: FastAPI, Flask, Pydantic, SQLAlchemy, Django (models + URLs)
+- **Go**: Gin, Echo, Chi, Fiber, net/http — routes, structs, import graph
 - **Schema**: Prisma
 - **Frontend**: HTML fetch()
 - **R**: Plumber, Shiny, R6, S7
 
-Wanted: Rails, Laravel, NestJS, Hono, Spring, Flask, Fastify.
+Wanted: Rails, Laravel, NestJS, Hono, Spring, Fastify.
 
 ### Tier 3 — Core (review carefully before merging)
 
@@ -83,12 +83,27 @@ module.exports = {
 
 ## How to add a domain keyword
 
-Domain clustering lives in `src/agents/domains.js`. The `DOMAIN_MAP` array maps keywords to domain names. If your framework creates a new domain category, add it:
+Domain clustering lives in `src/agents/domains.js`. The `DEFAULT_DOMAIN_MAP` array maps keywords to domain names. If your framework creates a new domain category, add it:
 
 ```js
 { keywords: ['graphql', 'resolver', 'mutation'], domain: 'GRAPHQL' },
 ```
 
+### Project-level custom domains
+
+For non-web repos (CLIs, desktop apps, compilers), users can define their own domains in `carto.config.json` at the project root without touching `domains.js`:
+
+```json
+{
+  "domains": {
+    "EDITOR": ["editor", "monaco", "text"],
+    "PLATFORM": ["platform", "service", "registry"]
+  }
+}
+```
+
+Custom config overrides the default domain map entirely for that project.
+
 ---
 
 ## Ground rules

package/README.md

@@ -138,11 +138,11 @@ File saved → re-parse 1 file → update graph → ~130ms
 
 | Category | What Carto finds |
 |----------|-----------------|
-| **Routes** | FastAPI, Express, Next.js App/Pages Router, React Router (JSX + createBrowserRouter), tRPC procedures, Django URLs, Gin/Echo (Go) |
-| **Models** | Prisma, Pydantic, SQLAlchemy, Django ORM, TypeScript interfaces/types, Zod schemas, Drizzle tables |
-| **Graph** | Full import graph: who imports what, transitive dependencies up to 5 hops |
+| **Routes** | FastAPI, Flask, Express, Next.js App/Pages Router, React Router (JSX + createBrowserRouter), tRPC procedures, Django URLs, Gin/Echo/Chi/Fiber (Go) |
+| **Models** | Prisma, Pydantic, SQLAlchemy, Django ORM, TypeScript interfaces/types, Zod schemas, Drizzle tables, Go structs |
+| **Graph** | Full import graph: who imports what, transitive dependencies up to 5 hops — JS/TS, Python, Go, R |
 | **Blast radius** | Risk level (HIGH/MEDIUM/LOW) per file and per route |
-| **Domains** | AUTH, PAYMENTS, DATABASE, EVENTS, TRPC, NOTIFICATIONS, CORE, auto-clustered from imports |
+| **Domains** | AUTO-clustered from imports. Defaults: AUTH, PAYMENTS, DATABASE, EVENTS, TRPC, NOTIFICATIONS, CORE. Custom domains via `carto.config.json`. |
 | **Events** | EventEmitter listeners, webhook handlers, queue jobs, cron schedules |
 | **Env vars** | Every `process.env` / `os.Getenv` call (names only, never values) |
 | **Functions** | Signatures with param names and return types |
@@ -154,8 +154,8 @@ File saved → re-parse 1 file → update graph → ~130ms
 | Language | Frameworks |
 |----------|------------|
 | TypeScript / JavaScript | Express, Next.js (App + Pages Router), React Router, tRPC, Drizzle, Zod |
-| Python | FastAPI, Pydantic, SQLAlchemy, Django |
-| Go | Gin, Echo, Chi, net/http |
+| Python | FastAPI, Flask, Pydantic, SQLAlchemy, Django |
+| Go | Gin, Echo, Chi, Fiber, net/http — including full import graph |
 | R | Plumber, Shiny, R6, S7 |
 | Schema | Prisma |
 | HTML | fetch() calls |
@@ -164,6 +164,25 @@ More via community. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ---
 
+## Custom domains (`carto.config.json`)
+
+By default Carto clusters into web-app domains (AUTH, PAYMENTS, etc.). For any other architecture — desktop apps, CLIs, compilers, monorepos — define your own:
+
+```json
+{
+  "domains": {
+    "EDITOR": ["editor", "monaco", "text", "cursor"],
+    "WORKBENCH": ["workbench", "layout", "panel", "sidebar"],
+    "PLATFORM": ["platform", "service", "registry"],
+    "BASE": ["base", "common", "util"]
+  }
+}
+```
+
+Drop `carto.config.json` in your project root. Carto picks it up on the next `carto init` or `carto sync`. The import graph and blast radius always work regardless — custom domains only affect how files are clustered and labeled.
+
+---
+
 ## Commands
 
 | Command | What it does |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carto-md",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "The context layer for AI-native development.",
   "bin": {
     "carto": "src/cli/index.js"

package/src/agents/domains.js

@@ -1,6 +1,6 @@
 const path = require('path');
 
-const DOMAIN_MAP = [
+const DEFAULT_DOMAIN_MAP = [
   { keywords: ['auth', 'login', 'session', 'oauth', 'token', 'jwt', 'password', 'credential'], domain: 'AUTH' },
   { keywords: ['payment', 'billing', 'stripe', 'invoice', 'charge', 'subscription', 'checkout'], domain: 'PAYMENTS' },
   { keywords: ['trpc', 'router', 'routers', 'procedure'], domain: 'TRPC' },
@@ -9,6 +9,29 @@ const DOMAIN_MAP = [
   { keywords: ['email', 'notification', 'mail', 'sms', 'alert'], domain: 'NOTIFICATIONS' },
 ];
 
+// Active domain map — replaced by setDomainMap() when carto.config.json is present
+let DOMAIN_MAP = DEFAULT_DOMAIN_MAP;
+
+/**
+ * setDomainMap(customDomains)
+ * Override the domain map from carto.config.json.
+ *
+ * customDomains format:
+ *   { "EDITOR": ["editor", "monaco"], "WORKBENCH": ["workbench", "panel"] }
+ *
+ * Pass null to reset to defaults.
+ */
+function setDomainMap(customDomains) {
+  if (!customDomains || typeof customDomains !== 'object' || Array.isArray(customDomains)) {
+    DOMAIN_MAP = DEFAULT_DOMAIN_MAP;
+    return;
+  }
+  DOMAIN_MAP = Object.entries(customDomains).map(([domain, keywords]) => ({
+    domain: domain.toUpperCase(),
+    keywords: keywords.map(k => String(k).toLowerCase()),
+  }));
+}
+
 /**
  * getDomainForFile(relPath) → domain string or null
  * Returns domain if path matches a keyword, null if no match.
@@ -112,7 +135,7 @@ function clusterByDomain(data) {
 
   function getCluster(domain) {
     if (!clusters[domain]) {
-      clusters[domain] = { routes: [], models: [], functions: {}, envVars: [], dbTables: [], fileMap: [] };
+      clusters[domain] = { routes: [], models: [], functions: {}, envVars: [], dbTables: [], fileMap: [], files: [] };
     }
     return clusters[domain];
   }
@@ -182,7 +205,12 @@ function clusterByDomain(data) {
     getCluster(domain).fileMap.push(entry);
   }
 
+  // Files — populate from assignments so cluster.files is always set
+  for (const [file, domain] of assignments.entries()) {
+    getCluster(domain).files.push(file);
+  }
+
   return clusters;
 }
 
-module.exports = { clusterByDomain, getDomainForFile, buildFileAssignments };
+module.exports = { clusterByDomain, getDomainForFile, buildFileAssignments, setDomainMap };

package/src/detector/framework.js

@@ -7,6 +7,7 @@ const IGNORE_DIRS = new Set(['node_modules', '.git', '__pycache__', '.venv', 've
 const PYTHON_PRIORITY = ['fastapi', 'django', 'flask', 'python-generic'];
 const JS_PRIORITY = ['nextjs', 'express', 'react', 'node-generic'];
 const R_PRIORITY = ['plumber', 'shiny', 'r-generic'];
+const GO_PRIORITY = ['gin', 'echo', 'chi', 'fiber', 'go-generic'];
 
 /**
  * detectFramework(projectRoot) → { framework, language, confidence, secondaryFramework?, secondaryLanguage? }
@@ -17,7 +18,7 @@ const R_PRIORITY = ['plumber', 'shiny', 'r-generic'];
  * (primary = highest priority overall, secondary = the other language).
  */
 function detectFramework(projectRoot) {
-  const candidates = findFile(projectRoot, ['requirements.txt', 'package.json', 'pyproject.toml', 'DESCRIPTION'], 3);
+  const candidates = findFile(projectRoot, ['requirements.txt', 'package.json', 'pyproject.toml', 'DESCRIPTION', 'go.mod'], 3);
 
   const pythonDetections = new Set();
   const jsDetections = new Set();
@@ -43,9 +44,15 @@ function detectFramework(projectRoot) {
     for (const r of detectAllFromRFiles(projectRoot)) rDetections.add(r);
   }
 
+  const goDetections = new Set();
+  for (const f of candidates.filter(f => path.basename(f) === 'go.mod')) {
+    for (const r of detectAllFromGoMod(f)) goDetections.add(r);
+  }
+
   const bestPython = PYTHON_PRIORITY.find(fw => pythonDetections.has(fw)) || null;
   const bestJS = JS_PRIORITY.find(fw => jsDetections.has(fw)) || null;
   const bestR = R_PRIORITY.find(fw => rDetections.has(fw)) || null;
+  const bestGo = GO_PRIORITY.find(fw => goDetections.has(fw)) || null;
 
   if (bestPython && bestJS) {
     return {
@@ -57,17 +64,10 @@ function detectFramework(projectRoot) {
     };
   }
 
-  if (bestPython) {
-    return { framework: bestPython, language: 'python', confidence: 'high' };
-  }
-
-  if (bestJS) {
-    return { framework: bestJS, language: 'javascript', confidence: 'high' };
-  }
-
-  if (bestR) {
-    return { framework: bestR, language: 'r', confidence: 'high' };
-  }
+  if (bestPython) return { framework: bestPython, language: 'python', confidence: 'high' };
+  if (bestJS)     return { framework: bestJS, language: 'javascript', confidence: 'high' };
+  if (bestGo)     return { framework: bestGo, language: 'go', confidence: 'high' };
+  if (bestR)      return { framework: bestR, language: 'r', confidence: 'high' };
 
   return { framework: 'unknown', language: 'unknown', confidence: 'none' };
 }
@@ -141,6 +141,18 @@ function detectAllFromPackageJson(filePath) {
   return detected;
 }
 
+function detectAllFromGoMod(filePath) {
+  const detected = [];
+  let content;
+  try { content = fs.readFileSync(filePath, 'utf-8').toLowerCase(); } catch { return detected; }
+  if (content.includes('gin-gonic/gin'))   detected.push('gin');
+  if (content.includes('labstack/echo'))   detected.push('echo');
+  if (content.includes('go-chi/chi'))      detected.push('chi');
+  if (content.includes('gofiber/fiber'))   detected.push('fiber');
+  if (!detected.length)                    detected.push('go-generic');
+  return detected;
+}
+
 function detectAllFromRDescription(filePath) {
   const detected = [];
   let content;

package/src/engine/carto.js

@@ -11,7 +11,7 @@ const { WorkerPool } = require('./worker-pool');
 const { loadLanguagePlugins, getPluginForFile } = require('../extractors/loader');
 const { buildImportGraph } = require('../extractors/imports');
 const { buildStackLine } = require('../extractors/stack');
-const { getDomainForFile, buildFileAssignments } = require('../agents/domains');
+const { getDomainForFile, buildFileAssignments, setDomainMap } = require('../agents/domains');
 const { extractImports } = require('../extractors/imports');
 
 const plugins = loadLanguagePlugins();
@@ -39,6 +39,7 @@ class Carto extends EventEmitter {
     this._cache = null;
     this._projectRoot = null;
     this._pool = null;
+    this._domainByFile = null; // reverse map: relPath → domainName
   }
 
   // ─── Indexing ────────────────────────────────────────────────────────────
@@ -54,6 +55,14 @@ class Carto extends EventEmitter {
 
     this.emit('status', { state: 'indexing', progress: 0 });
 
+    // Load custom domain config if present
+    try {
+      const config = JSON.parse(fs.readFileSync(path.join(projectRoot, 'carto.config.json'), 'utf-8'));
+      setDomainMap(config.domains || null);
+    } catch {
+      setDomainMap(null); // reset to defaults
+    }
+
     const cartoDir = path.join(projectRoot, '.carto');
     try { fs.mkdirSync(cartoDir, { recursive: true }); } catch {}
 
@@ -146,6 +155,7 @@ class Carto extends EventEmitter {
     }
 
     recomputeGraphMetrics(this._cache);
+    this._buildDomainMap();
     this._cache.meta.indexDuration = Date.now() - start;
     this._cache.meta.lastIndexed = new Date().toISOString();
     this._cache.generated = new Date().toISOString();
@@ -185,6 +195,7 @@ class Carto extends EventEmitter {
     updateFileHash(this._projectRoot, relPath, content);
     saveGraphCache(this._projectRoot, this._cache);
 
+    this._buildDomainMap();
     const blastRadius = this.getBlastRadius(relPath);
     this.emit('status', { state: 'ready' });
     this.emit('updated', { file: relPath, blastRadius });
@@ -555,12 +566,17 @@ class Carto extends EventEmitter {
     return null;
   }
 
-  _getDomainForFile(relPath) {
-    const domains = this._cache.domains || {};
-    for (const [name, cluster] of Object.entries(domains)) {
-      if ((cluster.files || []).includes(relPath)) return name;
+  _buildDomainMap() {
+    this._domainByFile = {};
+    for (const [name, cluster] of Object.entries(this._cache.domains || {})) {
+      for (const file of (cluster.files || [])) {
+        this._domainByFile[file] = name;
+      }
     }
-    return null;
+  }
+
+  _getDomainForFile(relPath) {
+    return this._domainByFile ? (this._domainByFile[relPath] || null) : null;
   }
 
   _discoverFiles(projectRoot) {

package/src/extractors/imports.js

@@ -39,6 +39,8 @@ function extractImports(content, filePath, projectRoot) {
     rawImports = extractPythonImports(content, filePath, projectRoot);
   } else if (ext === '.r') {
     return extractRImports(content, filePath, projectRoot);
+  } else if (ext === '.go') {
+    return extractGoImports(content, filePath, projectRoot);
   }
 
   // Resolve and deduplicate
@@ -220,6 +222,79 @@ function resolveImportPath(importPath, fileDir, projectRoot, sourceExt) {
   return null;
 }
 
+// ─── Go imports ──────────────────────────────────────────────────────────────
+
+// Cache go.mod module name per projectRoot — read once, reuse
+const _goModCache = new Map();
+
+function _getGoModuleName(projectRoot) {
+  if (_goModCache.has(projectRoot)) return _goModCache.get(projectRoot);
+  try {
+    const content = fs.readFileSync(path.join(projectRoot, 'go.mod'), 'utf-8');
+    const m = content.match(/^module\s+(\S+)/m);
+    const name = m ? m[1] : null;
+    _goModCache.set(projectRoot, name);
+    return name;
+  } catch {
+    _goModCache.set(projectRoot, null);
+    return null;
+  }
+}
+
+/**
+ * extractGoImports(content, filePath, projectRoot) → Array<string>
+ *
+ * Resolves local Go imports (same module) to actual .go files.
+ * Requires go.mod at projectRoot to determine the module name.
+ *
+ * Handles:
+ *   import "module/path/pkg"
+ *   import ( "module/path/pkg1" \n "module/path/pkg2" )
+ *   import alias "module/path/pkg"
+ */
+function extractGoImports(content, filePath, projectRoot) {
+  const moduleName = _getGoModuleName(projectRoot);
+  if (!moduleName) return [];
+
+  const results = new Set();
+
+  // Collect all import paths from both single and block imports
+  const importPaths = [];
+
+  // Single-line: import "path" or import alias "path"
+  const singleRe = /^import\s+(?:\w+\s+)?"([^"]+)"/gm;
+  let m;
+  while ((m = singleRe.exec(content)) !== null) importPaths.push(m[1]);
+
+  // Block: import ( ... )
+  const blockRe = /import\s*\(([^)]+)\)/g;
+  while ((m = blockRe.exec(content)) !== null) {
+    const block = m[1];
+    const lineRe = /"([^"]+)"/g;
+    let lm;
+    while ((lm = lineRe.exec(block)) !== null) importPaths.push(lm[1]);
+  }
+
+  // Resolve local imports only (starts with this module's name)
+  const prefix = moduleName + '/';
+  for (const imp of importPaths) {
+    if (!imp.startsWith(prefix)) continue;
+    const localPkg = imp.slice(prefix.length); // e.g. "internal/auth"
+    const pkgDir = path.join(projectRoot, localPkg);
+
+    // Find first non-test .go file in the package directory
+    try {
+      const entries = fs.readdirSync(pkgDir);
+      const goFile = entries.find(e => e.endsWith('.go') && !e.endsWith('_test.go'));
+      if (goFile) {
+        results.add(path.relative(projectRoot, path.join(pkgDir, goFile)));
+      }
+    } catch { /* directory doesn't exist or can't be read */ }
+  }
+
+  return [...results].sort();
+}
+
 /**
  * buildImportGraph(fileContents, projectRoot) → { 'relative/path.js': ['relative/dep.js', ...] }
  *

package/src/extractors/routes.js

@@ -25,11 +25,12 @@ function collapseMultilineDecorators(content) {
 }
 
 /**
- * Extracts HTTP routes from FastAPI and Django files.
+ * Extracts HTTP routes from FastAPI, Flask, and Django files.
  */
 function extractRoutes(content) {
   return [
     ...extractFastAPIRoutes(content),
+    ...extractFlaskRoutes(content),
     ...extractDjangoRoutes(content),
   ];
 }
@@ -61,6 +62,45 @@ function extractFastAPIRoutes(content) {
   return routes;
 }
 
+// ─── Flask ───────────────────────────────────────────────────────────────────
+
+function extractFlaskRoutes(content) {
+  const routes = [];
+
+  if (!content.includes('.route(') && !content.includes('from flask')) return routes;
+
+  // @app.route('/path') or @bp.route('/path', methods=['GET', 'POST'])
+  // Also handles: @api.route, @blueprint.route, any @x.route pattern
+  const decoratorRe = /@\w+\.route\s*\(\s*['"]([^'"]+)['"]\s*(?:,\s*methods\s*=\s*\[([^\]]+)\])?\s*\)/g;
+  const funcRe = /(?:async\s+)?def\s+(\w+)/;
+
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    decoratorRe.lastIndex = 0;
+    const match = decoratorRe.exec(lines[i]);
+    if (!match) continue;
+
+    const routePath = match[1];
+    const methodsRaw = match[2];
+    const methods = methodsRaw
+      ? methodsRaw.split(',').map(m => m.trim().replace(/['"]/g, '').toUpperCase()).filter(Boolean)
+      : ['GET'];
+
+    let functionName = '[anonymous]';
+    for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {
+      const fm = lines[j].match(funcRe);
+      if (fm) { functionName = fm[1]; break; }
+    }
+
+    for (const method of methods) {
+      routes.push({ method, path: routePath, functionName });
+    }
+  }
+
+  return routes;
+}
+
 // ─── Django ───────────────────────────────────────────────────────────────────
 
 function extractDjangoRoutes(content) {