carto-md 1.0.2 → 1.0.4

package/package.json

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

package/src/agents/formatter.js

@@ -9,10 +9,11 @@
  *   5. Functions (auto)
  *   6. Database Tables (auto)
  *   7. Environment Variables (auto)
- *   8. Frontend API Calls (auto)
- *   9. Frontend Storage Keys (auto)
+ *   8. File Relationships (auto)
+ *   9. Frontend API Calls (auto)
+ *   10. Frontend Storage Keys (auto)
  */
-function formatSections({ routes, models, frontend, structure, warnings, fileMap, functions, dbTables, envVars }) {
+function formatSections({ routes, models, frontend, structure, warnings, fileMap, functions, dbTables, envVars, importGraph }) {
   const sections = [];
 
   // 1. Project Structure
@@ -114,7 +115,21 @@ function formatSections({ routes, models, frontend, structure, warnings, fileMap
     sections.push('_No environment variables detected._');
   }
 
-  // 8. Frontend API Calls
+  // 8. File Relationships
+  sections.push('\n## File Relationships (auto)\n');
+  if (importGraph && Object.keys(importGraph).length > 0) {
+    const sortedFiles = Object.keys(importGraph).sort();
+    for (const file of sortedFiles) {
+      const deps = importGraph[file];
+      if (deps.length > 0) {
+        sections.push(`${file} \u2192 ${deps.join(', ')}`);
+      }
+    }
+  } else {
+    sections.push('_No file relationships detected._');
+  }
+
+  // 9. Frontend API Calls
   sections.push('\n## Frontend API Calls (auto)\n');
   if (frontend.fetches.length > 0) {
     sections.push('| Method | URL |');
@@ -126,7 +141,7 @@ function formatSections({ routes, models, frontend, structure, warnings, fileMap
     sections.push('_No fetch calls found._');
   }
 
-  // 9. Frontend Storage Keys
+  // 10. Frontend Storage Keys
   sections.push('\n## Frontend Storage Keys (auto)\n');
   if (frontend.storageKeys.length > 0) {
     sections.push('| Operation | Key |');

package/src/cli/init.js

@@ -55,11 +55,14 @@ async function run(projectRoot) {
     'utf-8'
   );
 
+  // Install pre-commit hook
+  installGitHook(projectRoot);
+
   // Run first sync
   const syncConfig = resolveConfig(projectRoot, config);
   await runFullSync(syncConfig);
 
-  console.log('[CARTO] AGENTS.md generated. Run "carto watch" to keep it live.');
+  console.log('[CARTO] AGENTS.md generated. Carto will sync on every git commit.');
 }
 
 /**
@@ -77,4 +80,29 @@ function resolveConfig(projectRoot, config) {
   };
 }
 
+function installGitHook(projectRoot) {
+  const gitDir = path.join(projectRoot, '.git');
+  if (!fs.existsSync(gitDir)) return;
+
+  const hooksDir = path.join(gitDir, 'hooks');
+  if (!fs.existsSync(hooksDir)) fs.mkdirSync(hooksDir, { recursive: true });
+
+  const hookPath = path.join(hooksDir, 'pre-commit');
+  const hookLine = 'carto sync\n';
+
+  if (fs.existsSync(hookPath)) {
+    const existing = fs.readFileSync(hookPath, 'utf-8');
+    if (existing.includes('carto sync')) {
+      console.log('[CARTO] Git hook already installed.');
+      return;
+    }
+    fs.appendFileSync(hookPath, '\n' + hookLine);
+  } else {
+    fs.writeFileSync(hookPath, '#!/bin/sh\n' + hookLine);
+  }
+
+  fs.chmodSync(hookPath, '755');
+  console.log('[CARTO] Git pre-commit hook installed.');
+}
+
 module.exports = { run, resolveConfig };

package/src/extractors/imports.js

@@ -0,0 +1,212 @@
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * extractImports(content, filePath, projectRoot) → Array<string>
+ *
+ * Extracts relative import paths from a source file.
+ * Returns resolved relative paths (from project root) of local dependencies.
+ *
+ * JS/TS patterns:
+ *   import X from './Y'
+ *   import { X } from './Y'
+ *   import './Y'
+ *   const X = require('./Y')
+ *   require('./Y')
+ *
+ * Python patterns:
+ *   from .module import X        (relative)
+ *   from ..module import X       (relative)
+ *   from app.module import X     (local package — resolved if file exists)
+ *   import .module               (relative)
+ *
+ * Only includes paths that resolve to actual files in the project.
+ * Skips: node_modules, non-code files, anything that doesn't resolve.
+ */
+function extractImports(content, filePath, projectRoot) {
+  const ext = path.extname(filePath).toLowerCase();
+  const fileDir = path.dirname(filePath);
+
+  let rawImports = [];
+
+  if (['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'].includes(ext)) {
+    rawImports = extractJSImports(content);
+  } else if (ext === '.py') {
+    rawImports = extractPythonImports(content, filePath, projectRoot);
+  }
+
+  // Resolve and deduplicate
+  const resolved = new Set();
+
+  for (const imp of rawImports) {
+    const resolvedPath = resolveImportPath(imp, fileDir, projectRoot, ext);
+    if (resolvedPath) {
+      // Store as relative to project root
+      const rel = path.relative(projectRoot, resolvedPath);
+      resolved.add(rel);
+    }
+  }
+
+  return [...resolved].sort();
+}
+
+/**
+ * Extract import paths from JS/TS content. Relative paths only.
+ */
+function extractJSImports(content) {
+  const imports = [];
+
+  // import ... from './path'  or  import './path'
+  const importPattern = /import\s+(?:[\s\S]*?\s+from\s+)?['"](\.[^'"]+)['"]/g;
+  let match;
+  while ((match = importPattern.exec(content)) !== null) {
+    imports.push(match[1]);
+  }
+
+  // require('./path')
+  const requirePattern = /require\s*\(\s*['"](\.[^'"]+)['"]\s*\)/g;
+  while ((match = requirePattern.exec(content)) !== null) {
+    imports.push(match[1]);
+  }
+
+  return imports;
+}
+
+/**
+ * Extract import paths from Python content. Relative imports only.
+ */
+function extractPythonImports(content, filePath, projectRoot) {
+  const imports = [];
+  const fileDir = path.dirname(filePath);
+
+  // from .module import X  or  from ..module import X
+  const fromRelPattern = /^from\s+(\.+\w*(?:\.\w+)*)\s+import/gm;
+  let match;
+  while ((match = fromRelPattern.exec(content)) !== null) {
+    const resolved = resolvePythonRelativeImport(match[1], fileDir);
+    if (resolved) imports.push(resolved);
+  }
+
+  // from app.module import X — try to resolve as local file
+  const fromAbsPattern = /^from\s+(\w+(?:\.\w+)+)\s+import/gm;
+  while ((match = fromAbsPattern.exec(content)) !== null) {
+    const modulePath = match[1].replace(/\./g, path.sep);
+    // Try from project root
+    const resolved = tryResolvePythonModule(modulePath, projectRoot);
+    if (resolved) {
+      imports.push(resolved);
+      continue;
+    }
+    // Try from file's directory (for cases like `from app.models` when inside aws-risk-agent/)
+    const fromFileDir = tryResolvePythonModule(modulePath, fileDir);
+    if (fromFileDir) {
+      imports.push(fromFileDir);
+      continue;
+    }
+    // Try from parent directories up to project root
+    let searchDir = path.dirname(fileDir);
+    while (searchDir.startsWith(projectRoot) && searchDir !== projectRoot) {
+      const fromParent = tryResolvePythonModule(modulePath, searchDir);
+      if (fromParent) {
+        imports.push(fromParent);
+        break;
+      }
+      searchDir = path.dirname(searchDir);
+    }
+  }
+
+  return imports;
+}
+
+/**
+ * Try to resolve a dotted Python module path from a base directory.
+ */
+function tryResolvePythonModule(modulePath, baseDir) {
+  const asFile = path.join(baseDir, modulePath + '.py');
+  if (fs.existsSync(asFile)) return asFile;
+  const asInit = path.join(baseDir, modulePath, '__init__.py');
+  if (fs.existsSync(asInit)) return asInit;
+  return null;
+}
+
+/**
+ * Resolve a Python relative import like '.models' or '..utils' to an absolute path.
+ */
+function resolvePythonRelativeImport(importStr, fileDir) {
+  // Count leading dots
+  let dots = 0;
+  while (dots < importStr.length && importStr[dots] === '.') dots++;
+
+  const modulePart = importStr.substring(dots);
+
+  // Go up (dots - 1) directories from fileDir
+  let baseDir = fileDir;
+  for (let i = 1; i < dots; i++) {
+    baseDir = path.dirname(baseDir);
+  }
+
+  if (!modulePart) return null;
+
+  const modulePath = modulePart.replace(/\./g, path.sep);
+  const asFile = path.join(baseDir, modulePath + '.py');
+  if (fs.existsSync(asFile)) return asFile;
+
+  const asInit = path.join(baseDir, modulePath, '__init__.py');
+  if (fs.existsSync(asInit)) return asInit;
+
+  return null;
+}
+
+/**
+ * Resolve a JS/TS import path to an actual file.
+ * Tries: exact, .js, .ts, .jsx, .tsx, /index.js, /index.ts
+ */
+function resolveImportPath(importPath, fileDir, projectRoot, sourceExt) {
+  // For Python, importPath is already absolute
+  if (path.isAbsolute(importPath)) {
+    return fs.existsSync(importPath) ? importPath : null;
+  }
+
+  const base = path.resolve(fileDir, importPath);
+
+  // Try exact
+  if (fs.existsSync(base) && fs.statSync(base).isFile()) return base;
+
+  // Try extensions
+  const extensions = ['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs'];
+  for (const ext of extensions) {
+    const withExt = base + ext;
+    if (fs.existsSync(withExt)) return withExt;
+  }
+
+  // Try index files
+  for (const ext of extensions) {
+    const indexFile = path.join(base, 'index' + ext);
+    if (fs.existsSync(indexFile)) return indexFile;
+  }
+
+  return null;
+}
+
+/**
+ * buildImportGraph(fileContents, projectRoot) → { 'relative/path.js': ['relative/dep.js', ...] }
+ *
+ * fileContents: Array of { filePath, content } (absolute paths)
+ * Returns a map of relative file paths to their relative dependencies.
+ * Only includes files that have at least one resolved dependency.
+ */
+function buildImportGraph(fileContents, projectRoot) {
+  const graph = {};
+
+  for (const { filePath, content } of fileContents) {
+    const deps = extractImports(content, filePath, projectRoot);
+    if (deps.length > 0) {
+      const relPath = path.relative(projectRoot, filePath);
+      graph[relPath] = deps;
+    }
+  }
+
+  return graph;
+}
+
+module.exports = { extractImports, buildImportGraph };

package/src/sync.js

@@ -5,6 +5,7 @@ const { formatSections } = require('./agents/formatter');
 const { mergeIntoAgentsMd } = require('./agents/merger');
 const { inferResponsibility } = require('./extractors/filemap');
 const { validateExtracted } = require('./agents/validator');
+const { buildImportGraph } = require('./extractors/imports');
 
 const IGNORE_DIRS = new Set(['node_modules', '.git', '__pycache__', '.venv', 'venv', '.idea', '.vscode', '.carto', 'AGENTS.md']);
 
@@ -166,6 +167,20 @@ async function runFullSync(config) {
     return true;
   });
 
+  // Build import graph from all processed files
+  const fileContentsForImports = [];
+  const allProcessedPaths = [...new Set([...allCodeFiles, ...allFrontendFiles])];
+  // Re-read is avoided — collect during processing. Use a second pass for simplicity.
+  for (const filePath of allProcessedPaths) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      fileContentsForImports.push({ filePath, content });
+    } catch {
+      // skip — already warned during extraction
+    }
+  }
+  const importGraph = buildImportGraph(fileContentsForImports, config.projectRoot);
+
   // Build file map
   const fileMap = [];
   for (const filePath of allCodeFiles) {
@@ -204,7 +219,8 @@ async function runFullSync(config) {
     fileMap,
     functions: validated.functions,
     dbTables: validated.dbTables,
-    envVars: validated.envVars
+    envVars: validated.envVars,
+    importGraph
   });
 
   mergeIntoAgentsMd(config.output, autoContent);