carto-md 1.0.8 → 1.0.10

package/CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contributing to Carto
+
+Carto is free, open source, and community-maintained. The core team owns the merger logic, AST engine, and CLI. The community owns language and framework extractors.
+
+---
+
+## What to contribute
+
+### Tier 1 — Languages (safe to add, easy to review)
+
+New language support lives in `src/ast/languages/`. Each language is an isolated module.
+
+Currently supported: JavaScript/TypeScript, Python.
+
+Wanted: Go, Rust, Ruby, Java, PHP, C#.
+
+### Tier 2 — Framework extractors (safe to add, easy to review)
+
+Framework-specific route and model extraction lives in `src/extractors/`. Each framework is an isolated module.
+
+Currently supported: FastAPI, Express, Next.js App Router, Prisma, HTML fetch().
+
+Wanted: Django, Rails, Laravel, NestJS, Hono, Gin, Spring.
+
+### Tier 3 — Core (review carefully before merging)
+
+- `src/agents/merger.js` — merger logic. One bad merge = developer loses manual notes = project dies. Changes here need strong justification and full test coverage.
+- `src/ast/` — AST engine. Wrong extraction = wrong AGENTS.md = AI gets confident with wrong facts. Worse than no AGENTS.md.
+- `src/detector/` — framework detection logic.
+- `src/cli/` — CLI commands.
+
+---
+
+## How to add a language
+
+1. Create `src/ast/languages/yourlanguage.js`
+2. Export a single function: `extractFromFile(filePath, fileContent)`
+3. Return:
+```js
+{
+  functions: [{ name, params, returns }],
+  classes: [{ name, fields }],
+  imports: [{ from, symbols }],
+  exports: [{ name }]
+}
+```
+4. Add it to `src/ast/parser.js` language map
+5. Test on at least 3 real open-source projects
+6. Open a PR with before/after AGENTS.md examples
+
+---
+
+## How to add a framework extractor
+
+1. Create `src/extractors/yourframework.js`
+2. Export:
+```js
+{
+  detect(projectRoot, files) → boolean,
+  extractRoutes(filePath, fileContent) → [{ method, path, functionName }],
+  extractModels(filePath, fileContent) → [{ name, fields: [{ name, type }] }]
+}
+```
+3. Add detection logic to `src/detector/framework.js`
+4. Test on at least 2 real projects using that framework
+5. Open a PR with before/after AGENTS.md examples
+
+---
+
+## Ground rules
+
+- **Never break the merger.** Manual sections in AGENTS.md are sacred. If your change could corrupt them, it needs a full merger test suite pass.
+- **Wrong output is worse than no output.** If your extractor produces incorrect routes or models, AI gets confident with wrong facts. Only ship when accurate on real projects.
+- **Test on unknown repos.** Don't just test on projects you wrote. Find a real open-source repo using the framework and verify the output is correct.
+- **No cloud, no telemetry, no tracking.** Carto is local only. Forever. Don't add any network calls.
+- **No paid features.** Free forever. MIT. Don't propose monetization.
+
+---
+
+## Development setup
+
+```bash
+git clone https://github.com/anshsonkar/carto-ansh
+cd carto-ansh
+npm install
+node src/cli/index.js init   # test in any project
+```
+
+---
+
+## PR checklist
+
+- [ ] Tested on at least 2-3 real open-source projects
+- [ ] Before/after AGENTS.md included in PR description
+- [ ] No changes to merger logic (unless explicitly fixing a merger bug)
+- [ ] No network calls added
+- [ ] `carto --version` still works
+- [ ] Existing tests pass
+
+---
+
+## Issues
+
+- **Bug**: Open an issue with the project type, command run, and what AGENTS.md produced vs what you expected.
+- **Language request**: Open an issue titled "Language: [name]" — someone from the community will pick it up.
+- **Framework request**: Open an issue titled "Framework: [name]".
+
+All issues acknowledged within 24 hours.

package/README.md

@@ -0,0 +1,267 @@
+# carto
+
+[![npm version](https://img.shields.io/npm/v/carto-md)](https://www.npmjs.com/package/carto-md)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![npm downloads](https://img.shields.io/npm/dm/carto-md)](https://www.npmjs.com/package/carto-md)
+
+**Your code changes. AGENTS.md updates. Every AI always knows.**
+
+Carto auto-generates and auto-maintains your `AGENTS.md` file. Every time you save, your routes, models, functions, and dependencies are extracted and written into the standard file every AI coding tool already reads.
+
+---
+
+## Origin
+
+I was building [Emfirge](https://emfirge.com) — a cloud security advisor for AWS.
+
+To make the AI inside Emfirge understand infrastructure, I wrote a module called `cartography.py`. It scanned AWS resources, built a graph of how they connected, and wrote it into a structured map. The AI stopped hallucinating. It worked with accurate facts about the actual infrastructure — not guesses.
+
+Halfway through, I switched AI tools. Opened a new session. Had to explain everything again from scratch.
+
+I thought: *I just built a cartography system so AI can understand infrastructure. Why doesn't this exist for codebases?*
+
+Carto is that thing. Same insight, different domain. Map your codebase once. Every AI session starts with accurate facts. You never explain your project again.
+
+---
+
+## The problem
+
+AI coding tools are blind to your actual project. Every session starts from zero.
+
+- Claude hallucinates your schema
+- Copilot suggests the wrong field names
+- Kiro asks what framework you're using
+- You rebuild context manually, every time
+
+`AGENTS.md` is the standard that fixes this — a file in your project root that every AI tool reads for project context. But it's static. You write it manually. It gets stale the moment your code changes.
+
+**Carto makes it live.**
+
+---
+
+## Why not just paste your code?
+
+Context windows are large now. But pasting code means:
+
+- You decide what's relevant — you're often wrong
+- AI sees a snapshot, not your live state
+- Bigger context ≠ better context
+
+Carto gives AI the map. You give AI the problem. Different jobs.
+
+---
+
+## How it works
+
+```
+You save a file
+      ↓
+Carto extracts routes, models, functions, env vars
+      ↓
+AGENTS.md updated in 300ms
+      ↓
+Cursor, Copilot, Kiro, Codex, Claude — all read current truth
+```
+
+---
+
+## Install
+
+```bash
+npm install -g carto-md
+```
+
+Or run without installing:
+
+```bash
+npx carto-md init
+```
+
+---
+
+## Usage
+
+```bash
+# 1. Go to your project
+cd your-project
+
+# 2. Generate AGENTS.md (run once)
+carto init
+
+# 3. Keep it live while you work
+carto watch
+```
+
+Leave `carto watch` running in a background terminal. Every file save updates AGENTS.md automatically.
+
+---
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `carto init` | Detect stack, generate AGENTS.md, install git hook |
+| `carto watch` | Watch files, update AGENTS.md on every save |
+| `carto sync` | One-time refresh, no watcher |
+| `carto impact <file>` | Show blast radius before touching a file |
+| `carto --version` | Show version |
+
+**When to use each:**
+- `init` — once, when you add Carto to a project
+- `watch` — every work session, leave it running
+- `sync` — if you skipped watch and just want a fresh snapshot
+- `impact` — before editing anything critical
+
+---
+
+## What gets extracted automatically
+
+- API routes — FastAPI, Express, Next.js App Router
+- Data models — Pydantic, Prisma
+- Function signatures — across all files
+- Dependencies — from `package.json` / `requirements.txt`
+- Environment variable names — never values
+- Frontend API calls — from `fetch()` patterns
+- Import graph — which files depend on which
+- Database tables
+
+---
+
+## What Carto never touches
+
+The manual sections you write directly into `AGENTS.md` — architecture decisions, active bugs, business rules, coding conventions — stay yours forever. Carto only rewrites content between its own markers:
+
+```
+<!-- CARTO:AUTO:START -->
+... auto-generated content ...
+<!-- CARTO:AUTO:END -->
+
+Your manual notes here. Never touched.
+```
+
+---
+
+## carto impact
+
+Before touching any file, know the blast radius:
+
+```bash
+carto impact app/models.py
+
+# Impact analysis: app/models.py
+#
+# Imported by:
+#   → app/main.py
+#   → app/rules.py
+#   → app/scoring.py
+#   → app/aws_collector.py
+#   → tests/conftest.py
+#
+# Routes affected:
+#   → POST /analyze
+#   → GET /history
+#   → POST /simulate
+#   → ... 12 more
+#
+# Risk: HIGH — 5 files depend on this
+```
+
+Most production bugs aren't logic errors. They're *"I didn't know X depended on Y."* Carto makes that invisible knowledge visible before you break something.
+
+---
+
+## What Carto fixes
+
+Carto fixes **factual hallucination about your own project**:
+
+- AI guessing wrong routes → fixed
+- AI guessing wrong field names → fixed
+- AI assuming wrong framework → fixed
+- AI guessing wrong DB schema → fixed
+
+What Carto does not fix: AI reasoning badly, wrong implementation logic, misunderstanding what you want. Carto makes AI **accurate** about your project. Not smarter. Accurate. Different thing.
+
+---
+
+## Real test — cal.com (800k lines)
+
+We ran the same task in two Claude sessions: *"Add a `notes` field to the booking model."*
+
+**Without AGENTS.md:**
+- Wrong API route: suggested `POST /api/bookings` → actual is `POST /v2/bookings`
+- Wrong handler: suggested `handleNewBooking.ts` → not the creation path
+- Wrong file paths: pointed to v1 API (`apps/api/v1/...`) → v1 is legacy
+- Wrong tRPC file: `bookings.tsx` → actual is `bookings/_router.tsx`
+- Field list: ~15 fields guessed → missing 20+ real fields
+- Couldn't proceed without follow-up: *"Want me to write the exact diffs once you confirm the codebase location?"*
+
+**With AGENTS.md (generated by Carto):**
+- Correct API route: `POST /v2/bookings` ✅
+- Correct controller path ✅
+- Correct tRPC file ✅
+- All 35+ booking fields returned accurately ✅
+- Answered in one shot. No follow-up needed.
+
+**4 wrong file paths → 0. 20 missing fields → 0. Zero follow-up clarifications.**
+
+This is what Carto does. Not smarter AI. The same AI with accurate facts.
+
+---
+
+## AI tools that read AGENTS.md
+
+Drop the file in your project root. Each tool picks it up via its own context config:
+
+- **Cursor** — via context rules
+- **GitHub Copilot** — via workspace instructions
+- **Kiro** — natively
+- **Codex** — natively
+- **VS Code** — via workspace context
+- **Gemini CLI** — natively
+- **Devin** — natively
+- **Jules** — natively
+
+---
+
+## Tested on
+
+- FastAPI + Python projects
+- Next.js App Router
+- Next.js + Prisma
+- React + FastAPI monorepos
+- Large monorepos (5000+ files — tested on Supabase and cal.com for stability, caps at 50 most important files on projects this scale)
+
+---
+
+## What it does NOT do
+
+- No cloud. No servers. No telemetry. No tracking.
+- Your code never leaves your machine.
+- No paid tiers. Free forever. MIT license.
+
+---
+
+## Security
+
+Carto never writes secrets into AGENTS.md. `.cartoignore` blocks `.env` files, secret files, key files, and credential files by default. The sanitizer strips API key patterns from extracted code.
+
+---
+
+## Contributing
+
+Python and JS/TS are supported today. Community adds more.
+
+- **Add a language**: `src/ast/languages/`
+- **Add a framework**: `src/extractors/`
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT — free forever.
+
+---
+
+*Built because AGENTS.md won. Someone had to keep it alive.*

package/package.json

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

package/src/cli/init.js

@@ -40,6 +40,7 @@ async function run(projectRoot) {
     version: '1',
     framework: detection.framework,
     language: detection.language,
+    projectRoot: projectRoot,
     watch: {
       routeFiles: relRouteFiles,
       modelFiles: relModelFiles,

package/src/sync.js

@@ -56,30 +56,21 @@ async function scanStructure(basePath) {
  */
 async function runFullSync(config) {
   const warnings = [];
+  const projectRoot = config.projectRoot || process.cwd();
 
   const allRouteFiles = config.watch.routeFiles || [];
   const allModelFiles = config.watch.modelFiles || [];
   const allFrontendFiles = config.watch.frontendFiles || [];
 
-  // Aggregate data
   let allRoutes = [];
   let allModels = [];
   let allFetches = [];
   let allStorageKeys = [];
-
-  // Functions: { filename: [{ name, params, returnType }] }
   const functionsMap = {};
-  // Routes per file for file map
   const routeCountMap = {};
-  // Env vars: { varName: Set([filename, ...]) }
   const envVarMap = new Map();
-  // DB tables: [{ tableName, modelName, file }]
   const dbTableList = [];
-
-  // Deduplicate files
   const processedFiles = new Set();
-
-  // Process all code files (route + model files, deduplicated)
   const allCodeFiles = [...new Set([...allRouteFiles, ...allModelFiles])];
 
   for (const filePath of allCodeFiles) {
@@ -90,45 +81,35 @@ async function runFullSync(config) {
     if (!content) continue;
 
     const basename = path.basename(filePath);
-    const relPath = path.relative(config.projectRoot, filePath);
+    const relPath = path.relative(projectRoot, filePath);
     const plugin = getPluginForFile(plugins, filePath);
 
-    if (!plugin) {
-      // No plugin for this file type — skip silently
-      continue;
-    }
+    if (!plugin) continue;
 
     const result = plugin.extract(content, relPath);
 
-    // Routes
     allRoutes = allRoutes.concat(result.routes);
     routeCountMap[filePath] = result.routes.length;
 
-    // Models
     allModels = allModels.concat(result.models);
 
-    // Functions
     if (result.functions.length > 0 && basename !== '__init__.py') {
       functionsMap[basename] = result.functions;
     }
 
-    // Env vars
     for (const varName of result.envVars) {
       if (!envVarMap.has(varName)) envVarMap.set(varName, new Set());
       envVarMap.get(varName).add(basename);
     }
 
-    // DB tables
     for (const t of result.dbTables) {
       dbTableList.push({ tableName: t.tableName, modelName: t.modelName, file: basename });
     }
 
-    // Fetches and storage keys (from JS/HTML plugins)
     allFetches = allFetches.concat(result.fetches);
     allStorageKeys = allStorageKeys.concat(result.storageKeys);
   }
 
-  // Process frontend files separately (may overlap with code files)
   for (const filePath of allFrontendFiles) {
     if (processedFiles.has(filePath)) continue;
     processedFiles.add(filePath);
@@ -146,12 +127,10 @@ async function runFullSync(config) {
     allStorageKeys = allStorageKeys.concat(result.storageKeys);
   }
 
-  // Global dedup: collapse dynamic fetches across all files into one summary row
   const staticFetches = allFetches.filter(f => f.url !== '[dynamic]' && !f.url.startsWith('dynamic calls detected'));
   let totalDynamic = 0;
   for (const f of allFetches) {
     if (f.url === '[dynamic]') totalDynamic++;
-    // Also count already-collapsed per-file rows
     const m = f.url.match(/^dynamic calls detected \((\d+) unresolved\)$/);
     if (m) totalDynamic += parseInt(m[1], 10);
   }
@@ -160,7 +139,6 @@ async function runFullSync(config) {
   }
   allFetches = staticFetches;
 
-  // Global dedup: storage keys across all files
   const skSeen = new Set();
   allStorageKeys = allStorageKeys.filter(({ operation, key }) => {
     const id = `${operation}::${key}`;
@@ -169,10 +147,8 @@ 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');
@@ -181,21 +157,17 @@ async function runFullSync(config) {
       // skip — already warned during extraction
     }
   }
-  const importGraph = buildImportGraph(fileContentsForImports, config.projectRoot);
+  const importGraph = buildImportGraph(fileContentsForImports, projectRoot);
 
-  // Detect tech stack from watched files + manifests
-  const stackItems = buildStackLine(fileContentsForImports, config.projectRoot);
+  const stackItems = buildStackLine(fileContentsForImports, projectRoot);
 
-  // Compute entry points and high impact files from import graph
   const allValues = new Set();
   for (const deps of Object.values(importGraph)) {
     for (const dep of deps) allValues.add(dep);
   }
-  // Entry points: files that import 3+ others but nothing imports them
   const entryPoints = Object.keys(importGraph)
     .filter(f => !allValues.has(f) && importGraph[f].length >= 3)
     .sort();
-  // High impact: files imported by 3+ others, sorted descending by count
   const depCount = {};
   for (const deps of Object.values(importGraph)) {
     for (const dep of deps) {
@@ -207,11 +179,10 @@ async function runFullSync(config) {
     .sort((a, b) => b[1] - a[1])
     .map(([file, count]) => ({ file, count }));
 
-  // Build file map
   const fileMap = [];
   for (const filePath of allCodeFiles) {
     const basename = path.basename(filePath);
-    const relPath = path.relative(config.projectRoot, filePath);
+    const relPath = path.relative(projectRoot, filePath);
     const funcCount = (functionsMap[basename] || []).length;
     const routeCount = routeCountMap[filePath] || 0;
     const responsibility = inferResponsibility(basename, funcCount, routeCount);
@@ -220,15 +191,12 @@ async function runFullSync(config) {
     }
   }
 
-  // Aggregate env vars into sorted array
   const envVars = [...envVarMap.keys()]
     .sort()
     .map(name => ({ name, files: [...envVarMap.get(name)].sort() }));
 
-  // Scan project structure
-  const structure = await scanStructure(config.projectRoot);
+  const structure = await scanStructure(projectRoot);
 
-  // Validate extracted data — drop anything malformed
   const validated = validateExtracted({
     routes: allRoutes,
     models: allModels,
@@ -255,8 +223,7 @@ async function runFullSync(config) {
 
   mergeIntoAgentsMd(config.output, autoContent);
 
-  // Save graph to .carto/map.json (atomic write)
-  const cartoDir = path.join(config.projectRoot, '.carto');
+  const cartoDir = path.join(projectRoot, '.carto');
   const mapData = {
     version: '1',
     generated: new Date().toISOString(),