carto-md 1.0.10 → 1.0.13

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

@@ -6,21 +6,11 @@
 
 **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?*
+```bash
+npm install -g carto-md
+```
 
-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.
+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.
 
 ---
 
@@ -33,12 +23,70 @@ AI coding tools are blind to your actual project. Every session starts from zero
 - 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.
+`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:
@@ -109,11 +157,24 @@ Leave `carto watch` running in a background terminal. Every file save updates AG
 **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
+- `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
@@ -129,7 +190,7 @@ Leave `carto watch` running in a background terminal. Every file save updates AG
 
 ## 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:
+Your manual sections — architecture decisions, active bugs, business rules, coding conventions — stay yours forever. Carto only rewrites between its own markers:
 
 ```
 <!-- CARTO:AUTO:START -->
@@ -141,35 +202,6 @@ 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**:
@@ -183,31 +215,6 @@ What Carto does not fix: AI reasoning badly, wrong implementation logic, misunde
 
 ---
 
-## 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:
@@ -223,16 +230,6 @@ Drop the file in your project root. Each tool picks it up via its own context co
 
 ---
 
-## 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.
@@ -249,12 +246,21 @@ Carto never writes secrets into AGENTS.md. `.cartoignore` blocks `.env` files, s
 
 ## Contributing
 
-Python and JS/TS are supported today. Community adds more.
+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.
 
-- **Add a language**: `src/ast/languages/`
-- **Add a framework**: `src/extractors/`
+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?*
 
-See [CONTRIBUTING.md](CONTRIBUTING.md).
+Carto is that. Same insight, different domain.
 
 ---
 

package/package.json

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

package/src/cli/impact.js

@@ -137,7 +137,6 @@ function run(projectRoot, fileArg) {
  * Matches by basename or partial path suffix.
  */
 function resolveFile(fileArg, imports) {
-  // Collect all known files (keys + all values)
   const allFiles = new Set();
   for (const [file, deps] of Object.entries(imports)) {
     allFiles.add(file);
@@ -145,6 +144,7 @@ function resolveFile(fileArg, imports) {
   }
 
   const normalized = fileArg.replace(/\\/g, '/');
+  const hasPathSeparator = normalized.includes('/');
 
   // Exact match
   if (allFiles.has(normalized)) return normalized;
@@ -153,16 +153,17 @@ function resolveFile(fileArg, imports) {
   const matches = [...allFiles].filter(f => f.endsWith('/' + normalized) || f === normalized);
   if (matches.length === 1) return matches[0];
 
-  // Match by basename
+  // If input was a path (contains /), don't fall back to basename — it's ambiguous
+  if (hasPathSeparator) {
+    if (matches.length > 1) return null;
+    return null;
+  }
+
+  // Input is just a filename — fall back to basename matching
   const byBasename = [...allFiles].filter(f => path.basename(f) === path.basename(normalized));
   if (byBasename.length === 1) return byBasename[0];
 
-  // If multiple basename matches, prefer shortest path
-  if (byBasename.length > 1) {
-    byBasename.sort((a, b) => a.length - b.length);
-    return byBasename[0];
-  }
-
+  // Multiple basename matches — ambiguous, don't guess
   return null;
 }