carto-md 1.0.9 → 1.0.12

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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ansh Sonkar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+# 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.**
+
+```bash
+npm install -g carto-md
+```
+
+Carto auto-generates and maintains your `AGENTS.md` — the standard file every AI coding tool reads for project context. Every time you save, your routes, models, functions, and dependencies are extracted and kept current.
+
+---
+
+## 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` fixes this — a file in your project root that every AI tool reads. But it's static. You write it manually. It gets stale the moment your code changes.
+
+**Carto makes it live.**
+
+---
+
+## Proof — cal.com (800k lines)
+
+Same task, 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.**
+
+Not smarter AI. The same AI with accurate facts.
+
+---
+
+## Know what breaks before you break it
+
+Most production bugs aren't logic errors. They're *"I didn't know X depended on Y."*
+
+`carto impact` makes that invisible knowledge visible — before you touch anything.
+
+```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
+```
+
+No AI. No cloud. Runs in under a second. Locally, from your import graph.
+
+Make it a habit: before touching any file, run `carto impact` first. 10 seconds. Could save hours.
+
+---
+
+## 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` — skipped watch and need a fresh snapshot
+- `impact` — before editing anything critical
+
+---
+
+## Works with
+
+| Language | Frameworks |
+|----------|------------|
+| Python | FastAPI, Pydantic |
+| JavaScript | Express, Next.js |
+| TypeScript | Express, Next.js, Prisma |
+| HTML | fetch() calls |
+
+More languages via community — open an issue or see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## 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
+
+Your manual sections — architecture decisions, active bugs, business rules, coding conventions — stay yours forever. Carto only rewrites between its own markers:
+
+```
+<!-- CARTO:AUTO:START -->
+... auto-generated content ...
+<!-- CARTO:AUTO:END -->
+
+Your manual notes here. Never touched.
+```
+
+---
+
+## 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.
+
+---
+
+## 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
+
+---
+
+## 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 today. Want Go, Ruby, Django, Rails? Open an issue — or read [CONTRIBUTING.md](CONTRIBUTING.md) to add it yourself.
+
+---
+
+## Origin
+
+I was building [Emfirge](https://emfirge.cloud) — a cloud security agent for AWS.
+
+To make the AI inside Emfirge understand infrastructure, I wrote a module called `cartography.py`. It mapped 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 — 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. Same insight, different domain.
+
+---
+
+## 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.9",
+  "version": "1.0.12",
   "description": "The context layer for AI-native development.",
   "bin": {
     "carto": "src/cli/index.js"

package/src/sync.js

@@ -62,25 +62,15 @@ async function runFullSync(config) {
   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) {
@@ -94,42 +84,32 @@ async function runFullSync(config) {
     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);
@@ -147,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);
   }
@@ -161,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}`;
@@ -170,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');
@@ -184,19 +159,15 @@ async function runFullSync(config) {
   }
   const importGraph = buildImportGraph(fileContentsForImports, projectRoot);
 
-  // Detect tech stack from watched files + manifests
   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) {
@@ -208,7 +179,6 @@ 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);
@@ -221,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(projectRoot);
 
-  // Validate extracted data — drop anything malformed
   const validated = validateExtracted({
     routes: allRoutes,
     models: allModels,
@@ -256,7 +223,6 @@ async function runFullSync(config) {
 
   mergeIntoAgentsMd(config.output, autoContent);
 
-  // Save graph to .carto/map.json (atomic write)
   const cartoDir = path.join(projectRoot, '.carto');
   const mapData = {
     version: '1',