codesight 1.1.1 → 1.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 ### Your AI assistant wastes thousands of tokens every conversation just figuring out your project. codesight fixes that in one command.
 
-**Zero dependencies. 25+ framework detectors. 4 ORM parsers. MCP server. One `npx` call.**
+**Zero dependencies. AST precision. 25+ framework detectors. 8 ORM parsers. 8 MCP tools. Blast radius analysis. One `npx` call.**
 
 [![npm version](https://img.shields.io/npm/v/codesight?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/codesight)
 [![npm downloads](https://img.shields.io/npm/dm/codesight?style=for-the-badge&logo=npm&color=blue&label=Monthly%20Downloads)](https://www.npmjs.com/package/codesight)
@@ -26,7 +26,7 @@
 ---
 
 ```
-0 dependencies · Node.js >= 18 · 27 tests · MIT
+0 dependencies · Node.js >= 18 · 27 tests · 8 MCP tools · MIT
 ```
 
 ## Works With
@@ -42,10 +42,12 @@ npx codesight
 That's it. Run it in any project root. No config, no setup, no API keys.
 
 ```bash
-npx codesight --init       # Also generate CLAUDE.md, .cursorrules, codex.md, AGENTS.md
-npx codesight --open       # Also open interactive HTML report in browser
-npx codesight --mcp        # Start as MCP server for Claude Code / Cursor
-npx codesight --benchmark  # Show detailed token savings breakdown
+npx codesight --init                # Generate CLAUDE.md, .cursorrules, codex.md, AGENTS.md
+npx codesight --open                # Open interactive HTML report in browser
+npx codesight --mcp                 # Start as MCP server (8 tools) for Claude Code / Cursor
+npx codesight --blast src/lib/db.ts # Show blast radius for a file
+npx codesight --profile claude-code # Generate optimized config for a specific AI tool
+npx codesight --benchmark           # Show detailed token savings breakdown
 ```
 
 ## What It Does
@@ -54,6 +56,8 @@ Every AI coding conversation starts the same way. Your assistant reads files, gr
 
 codesight scans your codebase once and generates a structured context map. Routes, database schema, components, dependencies, environment variables, middleware, all condensed into ~3,000 to 5,000 tokens of structured markdown. Your AI reads one file and knows the entire project.
 
+**v1.3.0: AST-level precision.** When TypeScript is available in your project, codesight uses the TypeScript compiler API for structural parsing instead of regex. This gives exact route paths, proper controller prefix combining (NestJS), accurate tRPC procedure nesting, precise Drizzle field types, and React prop extraction from type annotations. Zero new dependencies — borrows TypeScript from your project's node_modules. Falls back to regex when TypeScript is not available.
+
 ```
 Output size:      ~3,200 tokens
 Exploration cost: ~52,000 tokens (without codesight)
@@ -75,6 +79,27 @@ Saved:            ~48,800 tokens per conversation
   report.html      Interactive visual dashboard (with --html or --open)
 ```
 
+## AST Precision
+
+When TypeScript is installed in the project being scanned, codesight uses the actual TypeScript compiler API to parse your code structurally. No regex guessing.
+
+| What AST enables | Regex alone |
+|---|---|
+| Follows `router.use('/prefix', subRouter)` chains | Misses nested routers |
+| Combines `@Controller('users')` + `@Get(':id')` into `/users/:id` | May miss prefix |
+| Parses `router({ users: userRouter })` tRPC nesting | Line-by-line matching |
+| Extracts exact Drizzle field types from `.primaryKey().notNull()` chains | Pattern matching |
+| Gets React props from TypeScript interfaces and destructuring | Regex on `{ prop }` |
+| Detects middleware in route chains: `app.get('/path', auth, handler)` | Not captured |
+
+AST detection is indicated in the output:
+
+```
+Analyzing... done (AST: 65 routes, 18 models, 16 components)
+```
+
+No configuration needed. If TypeScript is in your `node_modules`, AST kicks in automatically. Works with npm, yarn, and pnpm (including strict mode). Falls back to regex for non-TypeScript projects or frameworks without AST support.
+
 ## Routes
 
 Not just paths. Methods, URL parameters, what each route touches (auth, database, cache, payments, AI, email, queues), and where the handler lives. Detects routes across 25+ frameworks automatically.
@@ -117,6 +142,35 @@ The files imported the most are the ones that break the most things when changed
 - `apps/api/src/lib/auth.ts` — imported by **7** files
 ```
 
+## Blast Radius
+
+See exactly what breaks if you change a file. BFS through the import graph finds all transitively affected files, routes, models, and middleware.
+
+```bash
+npx codesight --blast src/lib/db.ts
+```
+
+```
+  Blast Radius: src/lib/db.ts
+  Depth: 3 hops
+
+  Affected files (10):
+    src/routes/users.ts
+    src/routes/projects.ts
+    src/routes/billing.ts
+    ...
+
+  Affected routes (33):
+    POST /auth/login — src/routes/auth.ts
+    GET /api/users — src/routes/users.ts
+    ...
+
+  Affected models: users, projects, subscriptions
+  Affected middleware: authMiddleware
+```
+
+Your AI can also query blast radius through the MCP server before making changes.
+
 ## Environment Audit
 
 Every env var across your codebase, flagged as required or has default, with the exact file where it is referenced.
@@ -157,7 +211,7 @@ npx codesight --benchmark
 | Category | Supported |
 |---|---|
 | **Routes** | Hono, Express, Fastify, Next.js (App + Pages), Koa, NestJS, tRPC, Elysia, AdonisJS, SvelteKit, Remix, Nuxt, FastAPI, Flask, Django, Go (net/http, Gin, Fiber, Echo, Chi), Rails, Phoenix, Spring Boot, Actix, Axum, raw http.createServer |
-| **Schema** | Drizzle, Prisma, TypeORM, Mongoose, Sequelize, SQLAlchemy, ActiveRecord, Ecto |
+| **Schema** | Drizzle, Prisma, TypeORM, Mongoose, Sequelize, SQLAlchemy, ActiveRecord, Ecto (8 ORMs) |
 | **Components** | React, Vue, Svelte (auto-filters shadcn/ui and Radix primitives) |
 | **Libraries** | TypeScript, JavaScript, Python, Go, Ruby, Elixir, Java, Kotlin, Rust (exports with function signatures) |
 | **Middleware** | Auth, rate limiting, CORS, validation, logging, error handlers |
@@ -184,7 +238,7 @@ Generates ready-to-use instruction files for every major AI coding tool at once:
 
 Each file is pre-filled with your project's stack, architecture, high-impact files, and required env vars. Your AI reads it on startup and starts with full context from the first message.
 
-## MCP Server
+## MCP Server (8 Tools)
 
 ```bash
 npx codesight --mcp
@@ -203,7 +257,32 @@ Runs as a Model Context Protocol server. Claude Code and Cursor call it directly
 }
 ```
 
-Exposes one tool: `codesight_scan`. Your AI calls it whenever it needs to understand the project.
+Exposes 8 specialized tools, each returning only what your AI needs:
+
+| Tool | What it does |
+|---|---|
+| `codesight_scan` | Full project scan (~3K-5K tokens) |
+| `codesight_get_summary` | Compact overview (~500 tokens) |
+| `codesight_get_routes` | Routes filtered by prefix, tag, or method |
+| `codesight_get_schema` | Schema filtered by model name |
+| `codesight_get_blast_radius` | Impact analysis before changing a file |
+| `codesight_get_env` | Environment variables (filter: required only) |
+| `codesight_get_hot_files` | Most imported files with configurable limit |
+| `codesight_refresh` | Force re-scan (results are cached per session) |
+
+Your AI asks for exactly what it needs instead of loading the entire context map. Session caching means the first call scans, subsequent calls return instantly.
+
+## AI Tool Profiles
+
+```bash
+npx codesight --profile claude-code
+npx codesight --profile cursor
+npx codesight --profile codex
+npx codesight --profile copilot
+npx codesight --profile windsurf
+```
+
+Generates an optimized config file for a specific AI tool. Each profile includes your project summary, stack info, high-impact files, required env vars, and tool-specific instructions on how to use codesight outputs. For Claude Code, this includes MCP tool usage instructions. For Cursor, it points to the right codesight files. Each profile writes to the correct file for that tool.
 
 ## Visual Report
 
@@ -254,34 +333,38 @@ Context stays fresh without thinking about it.
 ## All Options
 
 ```bash
-npx codesight                       # Scan current directory
-npx codesight ./my-project          # Scan specific directory
-npx codesight --init                # Generate AI config files
-npx codesight --open                # Open visual HTML report
-npx codesight --html                # Generate HTML report without opening
-npx codesight --mcp                 # Start MCP server
-npx codesight --watch               # Watch mode
-npx codesight --hook                # Install git pre-commit hook
-npx codesight --benchmark           # Detailed token savings breakdown
-npx codesight --json                # Output as JSON
-npx codesight -o .ai-context        # Custom output directory
-npx codesight -d 5                  # Limit directory depth
+npx codesight                              # Scan current directory
+npx codesight ./my-project                 # Scan specific directory
+npx codesight --init                       # Generate AI config files
+npx codesight --open                       # Open visual HTML report
+npx codesight --html                       # Generate HTML report without opening
+npx codesight --mcp                        # Start MCP server (8 tools)
+npx codesight --blast src/lib/db.ts        # Show blast radius for a file
+npx codesight --profile claude-code        # Optimized config for specific tool
+npx codesight --watch                      # Watch mode
+npx codesight --hook                       # Install git pre-commit hook
+npx codesight --benchmark                  # Detailed token savings breakdown
+npx codesight --json                       # Output as JSON
+npx codesight -o .ai-context              # Custom output directory
+npx codesight -d 5                         # Limit directory depth
 ```
 
 ## How It Compares
 
 Most AI context tools dump your entire codebase into one file. codesight takes a different approach: it **parses** your code to extract structured information.
 
-| | codesight | File concatenation tools |
-|---|---|---|
-| **Output** | Structured routes, schema, components, deps | Raw file contents |
-| **Token cost** | ~3,000-5,000 tokens | 50,000-500,000+ tokens |
-| **Route detection** | 25+ frameworks auto-detected | None |
-| **Schema parsing** | ORM-aware with relations | None |
-| **Dependency graph** | Hot file detection | None |
-| **AI config generation** | CLAUDE.md, .cursorrules, etc. | None |
-| **MCP server** | Built-in | Varies |
-| **Dependencies** | Zero | Varies |
+| | codesight | File concatenation tools | AST-based tools |
+|---|---|---|---|
+| **Parsing** | AST when available, regex fallback | None | Tree-sitter / custom |
+| **Output** | Structured routes, schema, components, deps | Raw file contents | Call graphs, class diagrams |
+| **Token cost** | ~3,000-5,000 tokens | 50,000-500,000+ tokens | Varies |
+| **Route detection** | 25+ frameworks auto-detected | None | Limited |
+| **Schema parsing** | 8 ORMs with relations | None | Varies |
+| **Blast radius** | BFS through import graph | None | Some |
+| **AI tool profiles** | 5 tools (Claude, Cursor, Codex, Copilot, Windsurf) | None | None |
+| **MCP server** | 8 specialized tools with session caching | None | Some |
+| **Setup** | `npx codesight` (zero deps, zero config) | Copy/paste | Install compilers, runtimes |
+| **Dependencies** | Zero (borrows TS from your project) | Varies | Tree-sitter, SQLite, etc. |
 
 ## Contributing
 

package/dist/ast/extract-components.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AST-based component extraction for React.
+ * Provides higher accuracy than regex for:
+ * - Component name detection from function/arrow function declarations
+ * - Prop extraction from destructured parameters and Props interface/type
+ * - Distinguishes client/server components via directive detection
+ */
+import type { ComponentInfo } from "../types.js";
+/**
+ * Extract React components from a file using AST.
+ */
+export declare function extractReactComponentsAST(ts: any, filePath: string, content: string, relPath: string): ComponentInfo[];

package/dist/ast/extract-components.js

@@ -0,0 +1,180 @@
+import { parseSourceFile, getText } from "./loader.js";
+/**
+ * Extract React components from a file using AST.
+ */
+export function extractReactComponentsAST(ts, filePath, content, relPath) {
+    try {
+        const sf = parseSourceFile(ts, filePath, content);
+        return extractComponents(ts, sf, content, relPath);
+    }
+    catch {
+        return [];
+    }
+}
+function extractComponents(ts, sf, content, relPath) {
+    const components = [];
+    const SK = ts.SyntaxKind;
+    const isClient = content.slice(0, 80).includes("use client");
+    const isServer = content.slice(0, 80).includes("use server");
+    // Collect all Props interfaces/types in the file
+    const propsTypes = new Map(); // type name -> prop names
+    function collectPropsTypes(node) {
+        // interface FooProps { ... } or type FooProps = { ... }
+        if (node.kind === SK.InterfaceDeclaration || node.kind === SK.TypeAliasDeclaration) {
+            const name = node.name ? getText(sf, node.name) : "";
+            if (!name.includes("Props") && !name.includes("props")) {
+                ts.forEachChild(node, collectPropsTypes);
+                return;
+            }
+            const props = [];
+            // For interfaces: node.members
+            if (node.members) {
+                for (const member of node.members) {
+                    if (member.kind === SK.PropertySignature && member.name) {
+                        const propName = getText(sf, member.name);
+                        if (propName !== "children")
+                            props.push(propName);
+                    }
+                }
+            }
+            // For type aliases: node.type might be TypeLiteral
+            if (node.type?.kind === SK.TypeLiteral && node.type.members) {
+                for (const member of node.type.members) {
+                    if (member.kind === SK.PropertySignature && member.name) {
+                        const propName = getText(sf, member.name);
+                        if (propName !== "children")
+                            props.push(propName);
+                    }
+                }
+            }
+            if (props.length > 0)
+                propsTypes.set(name, props);
+        }
+        ts.forEachChild(node, collectPropsTypes);
+    }
+    collectPropsTypes(sf);
+    // Find exported functions/consts that start with uppercase (components)
+    function findComponents(node) {
+        // export function ComponentName(...) or export default function ComponentName(...)
+        if (node.kind === SK.FunctionDeclaration) {
+            const name = node.name ? getText(sf, node.name) : "";
+            if (!name || !/^[A-Z]/.test(name)) {
+                ts.forEachChild(node, findComponents);
+                return;
+            }
+            // Check if exported
+            const isExported = node.modifiers?.some((m) => m.kind === SK.ExportKeyword || m.kind === SK.DefaultKeyword);
+            if (!isExported) {
+                ts.forEachChild(node, findComponents);
+                return;
+            }
+            const props = extractPropsFromParams(ts, sf, node.parameters, propsTypes);
+            components.push({
+                name,
+                file: relPath,
+                props: props.slice(0, 10),
+                isClient,
+                isServer,
+                confidence: "ast",
+            });
+        }
+        // export const ComponentName = (...) => { ... }
+        if (node.kind === SK.VariableStatement) {
+            const isExported = node.modifiers?.some((m) => m.kind === SK.ExportKeyword);
+            if (!isExported) {
+                ts.forEachChild(node, findComponents);
+                return;
+            }
+            for (const decl of node.declarationList?.declarations || []) {
+                if (decl.kind !== SK.VariableDeclaration)
+                    continue;
+                const name = decl.name ? getText(sf, decl.name) : "";
+                if (!name || !/^[A-Z]/.test(name))
+                    continue;
+                // Check if the initializer is an arrow function or function expression
+                const init = decl.initializer;
+                if (!init)
+                    continue;
+                let params = null;
+                if (init.kind === SK.ArrowFunction || init.kind === SK.FunctionExpression) {
+                    params = init.parameters;
+                }
+                // React.forwardRef((...) => { ... })
+                if (init.kind === SK.CallExpression) {
+                    const callee = init.expression;
+                    const calleeName = callee?.kind === SK.PropertyAccessExpression
+                        ? getText(sf, callee.name)
+                        : callee?.kind === SK.Identifier ? getText(sf, callee) : "";
+                    if (calleeName === "forwardRef" || calleeName === "memo") {
+                        const innerFn = init.arguments?.[0];
+                        if (innerFn && (innerFn.kind === SK.ArrowFunction || innerFn.kind === SK.FunctionExpression)) {
+                            params = innerFn.parameters;
+                        }
+                    }
+                }
+                if (params) {
+                    const props = extractPropsFromParams(ts, sf, params, propsTypes);
+                    components.push({
+                        name,
+                        file: relPath,
+                        props: props.slice(0, 10),
+                        isClient,
+                        isServer,
+                        confidence: "ast",
+                    });
+                }
+            }
+        }
+        ts.forEachChild(node, findComponents);
+    }
+    findComponents(sf);
+    return components;
+}
+/**
+ * Extract prop names from function parameters.
+ * Handles: ({ prop1, prop2 }: Props) and (props: Props)
+ */
+function extractPropsFromParams(ts, sf, params, propsTypes) {
+    if (!params || params.length === 0)
+        return [];
+    const SK = ts.SyntaxKind;
+    const firstParam = params[0];
+    // Destructured: ({ prop1, prop2, ...rest }: Props)
+    if (firstParam.name?.kind === SK.ObjectBindingPattern) {
+        const props = [];
+        for (const element of firstParam.name.elements || []) {
+            if (element.dotDotDotToken)
+                continue; // skip ...rest
+            const propName = element.name ? getText(sf, element.name) : "";
+            if (propName && propName !== "children")
+                props.push(propName);
+        }
+        // If we got props from destructuring, great
+        if (props.length > 0)
+            return props;
+        // Fall back to type annotation if destructuring is empty
+    }
+    // Type annotation: (props: FooProps) or ({ ... }: FooProps)
+    if (firstParam.type) {
+        // TypeReference: FooProps
+        if (firstParam.type.kind === SK.TypeReference) {
+            const typeName = firstParam.type.typeName ? getText(sf, firstParam.type.typeName) : "";
+            const typeProps = propsTypes.get(typeName);
+            if (typeProps)
+                return typeProps;
+        }
+        // TypeLiteral: { prop1: string; prop2: number }
+        if (firstParam.type.kind === SK.TypeLiteral) {
+            const props = [];
+            for (const member of firstParam.type.members || []) {
+                if (member.kind === SK.PropertySignature && member.name) {
+                    const propName = getText(sf, member.name);
+                    if (propName !== "children")
+                        props.push(propName);
+                }
+            }
+            return props;
+        }
+    }
+    return [];
+}

package/dist/ast/extract-routes.d.ts

@@ -0,0 +1,13 @@
+/**
+ * AST-based route extraction for TypeScript/JavaScript frameworks.
+ * Provides higher accuracy than regex for:
+ * - Express/Hono/Fastify/Koa/Elysia: method calls with path strings
+ * - NestJS: decorator-based routes with controller prefix combining
+ * - tRPC: router object with procedure chains and nesting
+ */
+import type { RouteInfo, Framework } from "../types.js";
+/**
+ * Try AST-based route extraction for a single file.
+ * Returns routes with confidence: 'ast', or empty array if AST cannot handle this file.
+ */
+export declare function extractRoutesAST(ts: any, filePath: string, content: string, framework: Framework, tags: string[]): RouteInfo[];