codesight 1.0.0

package/README.md

@@ -0,0 +1,213 @@
+# codesight
+
+See your codebase clearly. One command gives your AI assistant complete project understanding.
+
+```bash
+npx codesight
+```
+
+**Works with Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Windsurf, Cline, and any AI coding tool.**
+
+## The Problem
+
+Every AI coding conversation starts the same way: your assistant burns thousands of tokens exploring files, grepping for patterns, and reading configs just to understand your project. On a 65-route Hono API with 18 Drizzle models, that costs **~68,000 tokens per conversation** in exploration alone.
+
+codesight pre-generates that understanding into ~4,000 tokens of structured context. **Your AI starts every conversation already knowing your routes, schema, components, dependencies, and architecture.**
+
+## Quick Start
+
+```bash
+npx codesight              # Scan and generate context
+npx codesight --init       # Also generate CLAUDE.md, .cursorrules, codex.md, AGENTS.md
+npx codesight --open       # Also open interactive HTML report in browser
+```
+
+## What It Generates
+
+```
+.codesight/
+  CODESIGHT.md     # Combined AI context map (point your assistant here)
+  routes.md        # API routes with methods, params, request/response types, tags
+  schema.md        # Database models with fields, types, PKs, FKs, relations
+  components.md    # UI components with props (shadcn/radix filtered out)
+  libs.md          # Library exports with function signatures
+  config.md        # Env vars (required vs default), config files, key deps
+  middleware.md    # Auth, rate limiting, CORS, validation, logging
+  graph.md         # Dependency graph: most-imported files + import map
+  report.html      # Interactive visual report (with --html or --open)
+```
+
+## Real Output Example
+
+From a production SaaS monorepo (Hono + Drizzle + React):
+
+```markdown
+# savemrr — AI Context Map
+
+> **Stack:** hono | drizzle | react | typescript
+> **Monorepo:** @savemrr/api, @savemrr/dashboard, @savemrr/widget, @savemrr/shared
+
+> 65 routes | 18 models | 16 components | 36 lib files | 22 env vars | 5 middleware | 53 import links
+> **Token savings:** this file is ~4,041 tokens. Without it, AI exploration would cost ~68,640 tokens.
+> **Saves ~64,599 tokens per conversation.**
+
+---
+
+# Routes
+
+- `POST` `/magic-link` [auth, db, cache, email]
+- `POST` `/verify` [auth, db, cache, email]
+- `GET` `/me` [auth, db, cache, email]
+- `GET` `/overview` [auth, db, queue, payment, ai]
+- `GET` `/shield` [auth, db, queue, payment, ai]
+- `GET` `/rescue` [auth, db, queue, payment, ai]
+- `POST` `/rescue/:id/send-now` params(id) [auth, db, queue, payment, ai]
+...
+
+# Schema
+
+### users
+- id: uuid (pk, default)
+- email: text (unique, required)
+- tier: text (required, default)
+- polarSubId: text (fk)
+- settings: jsonb (required, default)
+
+### stripe_connections
+- id: uuid (pk, default)
+- userId: uuid (fk)
+...
+
+# Dependency Graph
+
+## Most Imported Files (change these carefully)
+- `packages/shared/src/index.ts` — imported by **12** files
+- `apps/api/src/lib/db.ts` — imported by **8** files
+- `apps/api/src/lib/auth.ts` — imported by **6** files
+```
+
+## What It Detects
+
+| Category | Supported |
+|---|---|
+| **Routes** | Hono, Express, Fastify, Next.js (App + Pages), Koa, FastAPI, Flask, Django, Go (net/http, Gin, Fiber) |
+| **Schema** | Drizzle, Prisma, TypeORM, SQLAlchemy |
+| **Components** | React, Vue, Svelte (filters out shadcn/radix primitives) |
+| **Libraries** | TypeScript/JavaScript, Python, Go exports with function signatures |
+| **Config** | Environment variables (required vs defaults), config files, notable dependencies |
+| **Middleware** | Auth, rate limiting, CORS, validation, logging, error handlers |
+| **Dependencies** | Import graph with hot file detection (most imported = highest blast radius) |
+| **Contracts** | URL params, request types, response types extracted from route handlers |
+| **Monorepos** | pnpm, npm, yarn workspaces with cross-workspace detection |
+| **Languages** | TypeScript, JavaScript, Python, Go |
+
+## Auto-Generate AI Config Files
+
+```bash
+npx codesight --init
+```
+
+Generates instruction files for every major AI coding tool:
+
+| File | Tool |
+|---|---|
+| `CLAUDE.md` | Claude Code |
+| `.cursorrules` | Cursor |
+| `.github/copilot-instructions.md` | GitHub Copilot |
+| `codex.md` | OpenAI Codex CLI |
+| `AGENTS.md` | OpenAI Codex |
+
+Each file includes your project's stack, key architecture facts, hot files, and required env vars so your AI assistant knows the project from the first message.
+
+## Interactive HTML Report
+
+```bash
+npx codesight --open
+```
+
+Generates a visual dashboard with:
+- Token savings hero metric
+- Route table with methods, contracts, and tags
+- Schema cards with fields and relations
+- Dependency hot files with impact bars
+- Environment variables (required vs defaults)
+- Full middleware map
+
+Screenshots of this report are what go viral on Twitter.
+
+## MCP Server
+
+```bash
+npx codesight --mcp
+```
+
+Runs as a Model Context Protocol server that Claude Code and Cursor can connect to. Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "codesight": {
+      "command": "npx",
+      "args": ["codesight", "--mcp"]
+    }
+  }
+}
+```
+
+Your AI assistant can then call the `codesight_scan` tool to get full project context on demand.
+
+## Watch Mode
+
+```bash
+npx codesight --watch
+```
+
+Re-scans automatically when files change. Keeps context fresh during development.
+
+## Git Pre-Commit Hook
+
+```bash
+npx codesight --hook
+```
+
+Installs a git pre-commit hook that regenerates context on every commit. Context stays up to date automatically.
+
+## 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 interactive HTML report
+npx codesight --html                # Generate HTML report (no open)
+npx codesight --mcp                 # Start MCP server
+npx codesight --watch               # Watch mode
+npx codesight --hook                # Install git pre-commit hook
+npx codesight --json                # Output JSON
+npx codesight -o .ai-context        # Custom output directory
+npx codesight -d 5                  # Limit directory depth
+```
+
+## Why Not Repomix?
+
+Repomix dumps your entire codebase into one file. codesight maps your architecture.
+
+| | Repomix | codesight |
+|---|---|---|
+| **Approach** | Raw code dump | Structured intelligence |
+| **Output** | One giant text blob | Semantic context files |
+| **AI gets** | "Here is all the code" | "Here is the architecture" |
+| **Token cost** | Huge (entire codebase) | Tiny (~4K tokens for full map) |
+| **Route discovery** | Read every file | Instant from routes.md |
+| **Schema understanding** | Read every migration | Instant from schema.md |
+| **Change blast radius** | Unknown | Visible in dependency graph |
+| **AI config generation** | No | CLAUDE.md, .cursorrules, codex.md, AGENTS.md |
+| **Runtime deps** | 26 | **Zero** |
+
+## Zero Dependencies
+
+codesight has zero runtime dependencies. Just Node.js built-ins. Fast, portable, no supply chain risk.
+
+## License
+
+MIT

package/dist/detectors/components.d.ts

@@ -0,0 +1,2 @@
+import type { ComponentInfo, ProjectInfo } from "../types.js";
+export declare function detectComponents(files: string[], project: ProjectInfo): Promise<ComponentInfo[]>;

package/dist/detectors/components.js

@@ -0,0 +1,237 @@
+import { relative, basename, extname } from "node:path";
+import { readFileSafe } from "../scanner.js";
+// shadcn/ui + radix primitives to filter out
+const UI_PRIMITIVES = new Set([
+    "accordion",
+    "alert",
+    "alert-dialog",
+    "aspect-ratio",
+    "avatar",
+    "badge",
+    "breadcrumb",
+    "button",
+    "calendar",
+    "card",
+    "carousel",
+    "chart",
+    "checkbox",
+    "collapsible",
+    "command",
+    "context-menu",
+    "data-table",
+    "date-picker",
+    "dialog",
+    "drawer",
+    "dropdown-menu",
+    "form",
+    "hover-card",
+    "input",
+    "input-otp",
+    "label",
+    "menubar",
+    "navigation-menu",
+    "pagination",
+    "popover",
+    "progress",
+    "radio-group",
+    "resizable",
+    "scroll-area",
+    "select",
+    "separator",
+    "sheet",
+    "sidebar",
+    "skeleton",
+    "slider",
+    "sonner",
+    "switch",
+    "table",
+    "tabs",
+    "textarea",
+    "toast",
+    "toaster",
+    "toggle",
+    "toggle-group",
+    "tooltip",
+]);
+function isUIPrimitive(filePath) {
+    const name = basename(filePath, extname(filePath)).toLowerCase();
+    return (UI_PRIMITIVES.has(name) ||
+        filePath.includes("/ui/") ||
+        filePath.includes("/components/ui/") ||
+        filePath.includes("@radix-ui") ||
+        filePath.includes("@shadcn"));
+}
+export async function detectComponents(files, project) {
+    switch (project.componentFramework) {
+        case "react":
+            return detectReactComponents(files, project);
+        case "vue":
+            return detectVueComponents(files, project);
+        case "svelte":
+            return detectSvelteComponents(files, project);
+        default:
+            return [];
+    }
+}
+// --- React ---
+async function detectReactComponents(files, project) {
+    const componentFiles = files.filter((f) => (f.endsWith(".tsx") || f.endsWith(".jsx")) &&
+        !f.includes("node_modules") &&
+        !f.endsWith(".test.tsx") &&
+        !f.endsWith(".test.jsx") &&
+        !f.endsWith(".spec.tsx") &&
+        !f.endsWith(".spec.jsx") &&
+        !f.endsWith(".stories.tsx") &&
+        !f.endsWith(".stories.jsx"));
+    const components = [];
+    for (const file of componentFiles) {
+        if (isUIPrimitive(file))
+            continue;
+        const content = await readFileSafe(file);
+        if (!content)
+            continue;
+        const rel = relative(project.root, file);
+        // Detect component name from export
+        let name = "";
+        // export default function ComponentName
+        const defaultFnMatch = content.match(/export\s+default\s+function\s+(\w+)/);
+        if (defaultFnMatch) {
+            name = defaultFnMatch[1];
+        }
+        // export function ComponentName (starts with uppercase)
+        if (!name) {
+            const namedFnMatch = content.match(/export\s+(?:async\s+)?function\s+([A-Z]\w+)/);
+            if (namedFnMatch)
+                name = namedFnMatch[1];
+        }
+        // const ComponentName = ... (with export)
+        if (!name) {
+            const constMatch = content.match(/export\s+const\s+([A-Z]\w+)\s*(?::\s*\w+)?\s*=/);
+            if (constMatch)
+                name = constMatch[1];
+        }
+        // Fallback: any function starting with uppercase that returns JSX
+        if (!name) {
+            const anyComponent = content.match(/(?:function|const)\s+([A-Z]\w+)/);
+            if (anyComponent && (content.includes("<") || content.includes("jsx"))) {
+                name = anyComponent[1];
+            }
+        }
+        if (!name)
+            continue;
+        // Detect props
+        const props = [];
+        // interface/type Props { ... }
+        const propsPattern = /(?:interface|type)\s+(?:\w*Props\w*)\s*(?:=\s*)?\{([^}]*)}/;
+        const propsMatch = content.match(propsPattern);
+        if (propsMatch) {
+            const propsBody = propsMatch[1];
+            for (const line of propsBody.split("\n")) {
+                const propMatch = line.match(/^\s*(\w+)\s*[?]?\s*:/);
+                if (propMatch && propMatch[1] !== "children") {
+                    props.push(propMatch[1]);
+                }
+            }
+        }
+        // Destructured props: function Component({ prop1, prop2 }: Props)
+        if (props.length === 0) {
+            const destructuredMatch = content.match(new RegExp(`function\\s+${name}\\s*\\(\\s*\\{([^}]*)\\}`));
+            if (destructuredMatch) {
+                for (const prop of destructuredMatch[1].split(",")) {
+                    const trimmed = prop.trim().split(/[=:]/)[0].trim();
+                    if (trimmed && trimmed !== "children" && !trimmed.startsWith("...")) {
+                        props.push(trimmed);
+                    }
+                }
+            }
+        }
+        const isClient = content.slice(0, 50).includes("use client");
+        const isServer = content.slice(0, 50).includes("use server");
+        components.push({
+            name,
+            file: rel,
+            props: props.slice(0, 10), // limit to 10 props
+            isClient,
+            isServer,
+        });
+    }
+    return components;
+}
+// --- Vue ---
+async function detectVueComponents(files, project) {
+    const vueFiles = files.filter((f) => f.endsWith(".vue") && !f.includes("node_modules"));
+    const components = [];
+    for (const file of vueFiles) {
+        if (isUIPrimitive(file))
+            continue;
+        const content = await readFileSafe(file);
+        const rel = relative(project.root, file);
+        const name = basename(file, ".vue");
+        const props = [];
+        // defineProps<{ ... }>() or defineProps({ ... })
+        const definePropsMatch = content.match(/defineProps\s*[<(]\s*\{([^}]*)\}/);
+        if (definePropsMatch) {
+            for (const line of definePropsMatch[1].split("\n")) {
+                const propMatch = line.match(/^\s*(\w+)\s*[?]?\s*:/);
+                if (propMatch)
+                    props.push(propMatch[1]);
+            }
+        }
+        // props: { ... } in Options API
+        if (props.length === 0) {
+            const optionsPropsMatch = content.match(/props\s*:\s*\{([^}]*)\}/);
+            if (optionsPropsMatch) {
+                for (const line of optionsPropsMatch[1].split("\n")) {
+                    const propMatch = line.match(/^\s*(\w+)\s*[?]?\s*:/);
+                    if (propMatch)
+                        props.push(propMatch[1]);
+                }
+            }
+        }
+        components.push({
+            name,
+            file: rel,
+            props: props.slice(0, 10),
+            isClient: true,
+            isServer: false,
+        });
+    }
+    return components;
+}
+// --- Svelte ---
+async function detectSvelteComponents(files, project) {
+    const svelteFiles = files.filter((f) => f.endsWith(".svelte") && !f.includes("node_modules"));
+    const components = [];
+    for (const file of svelteFiles) {
+        if (isUIPrimitive(file))
+            continue;
+        const content = await readFileSafe(file);
+        const rel = relative(project.root, file);
+        const name = basename(file, ".svelte");
+        const props = [];
+        // export let propName (Svelte 4)
+        const exportLetPattern = /export\s+let\s+(\w+)/g;
+        let match;
+        while ((match = exportLetPattern.exec(content)) !== null) {
+            props.push(match[1]);
+        }
+        // $props() (Svelte 5)
+        const propsMatch = content.match(/let\s+\{([^}]*)\}\s*=\s*\$props\(\)/);
+        if (propsMatch) {
+            for (const prop of propsMatch[1].split(",")) {
+                const trimmed = prop.trim().split(/[=:]/)[0].trim();
+                if (trimmed && !trimmed.startsWith("...")) {
+                    props.push(trimmed);
+                }
+            }
+        }
+        components.push({
+            name,
+            file: rel,
+            props: props.slice(0, 10),
+            isClient: true,
+            isServer: false,
+        });
+    }
+    return components;
+}

package/dist/detectors/config.d.ts

@@ -0,0 +1,2 @@
+import type { ConfigInfo, ProjectInfo } from "../types.js";
+export declare function detectConfig(files: string[], project: ProjectInfo): Promise<ConfigInfo>;

package/dist/detectors/config.js

@@ -0,0 +1,142 @@
+import { readFile } from "node:fs/promises";
+import { relative, join, basename } from "node:path";
+import { readFileSafe } from "../scanner.js";
+const CONFIG_FILES = [
+    "tsconfig.json",
+    "next.config.js",
+    "next.config.mjs",
+    "next.config.ts",
+    "vite.config.ts",
+    "vite.config.js",
+    "tailwind.config.ts",
+    "tailwind.config.js",
+    "drizzle.config.ts",
+    "wrangler.toml",
+    "docker-compose.yml",
+    "docker-compose.yaml",
+    "Dockerfile",
+    ".env.example",
+    "pyproject.toml",
+    "go.mod",
+    "Cargo.toml",
+    "railway.json",
+    "vercel.json",
+    "fly.toml",
+    "render.yaml",
+];
+export async function detectConfig(files, project) {
+    // Find config files
+    const configFiles = files
+        .filter((f) => {
+        const name = basename(f);
+        return CONFIG_FILES.includes(name);
+    })
+        .map((f) => relative(project.root, f));
+    // Also check root for config files that might not have code extensions
+    for (const cf of CONFIG_FILES) {
+        const content = await readFileSafe(join(project.root, cf));
+        if (content) {
+            const rel = cf;
+            if (!configFiles.includes(rel))
+                configFiles.push(rel);
+        }
+    }
+    // Detect env vars
+    const envVars = await detectEnvVars(files, project);
+    // Detect dependencies
+    let dependencies = {};
+    let devDependencies = {};
+    try {
+        const pkg = JSON.parse(await readFile(join(project.root, "package.json"), "utf-8"));
+        dependencies = pkg.dependencies || {};
+        devDependencies = pkg.devDependencies || {};
+    }
+    catch { }
+    return {
+        envVars,
+        configFiles: configFiles.sort(),
+        dependencies,
+        devDependencies,
+    };
+}
+async function detectEnvVars(files, project) {
+    const envMap = new Map();
+    // Parse .env.example and .env files for declarations
+    const envFiles = files.filter((f) => basename(f) === ".env" ||
+        basename(f) === ".env.example" ||
+        basename(f) === ".env.local");
+    for (const file of envFiles) {
+        const content = await readFileSafe(file);
+        for (const line of content.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const match = trimmed.match(/^([A-Z_][A-Z0-9_]*)\s*=/);
+            if (match) {
+                const name = match[1];
+                const hasDefault = trimmed.includes("=") && trimmed.split("=")[1].trim().length > 0;
+                envMap.set(name, {
+                    name,
+                    source: relative(project.root, file),
+                    hasDefault,
+                });
+            }
+        }
+    }
+    // Scan code for process.env.VAR_NAME or os.environ["VAR_NAME"] or os.Getenv("VAR_NAME")
+    const codeFiles = files.filter((f) => f.match(/\.(ts|js|tsx|jsx|mjs|cjs|py|go)$/) &&
+        !f.includes("node_modules"));
+    for (const file of codeFiles) {
+        const content = await readFileSafe(file);
+        const rel = relative(project.root, file);
+        // process.env.VAR_NAME or process.env["VAR_NAME"]
+        const nodeEnvPattern = /process\.env\.([A-Z_][A-Z0-9_]*)/g;
+        let match;
+        while ((match = nodeEnvPattern.exec(content)) !== null) {
+            const name = match[1];
+            if (!envMap.has(name)) {
+                envMap.set(name, { name, source: rel, hasDefault: false });
+            }
+        }
+        const nodeEnvBracket = /process\.env\[['"]([A-Z_][A-Z0-9_]*)['"]\]/g;
+        while ((match = nodeEnvBracket.exec(content)) !== null) {
+            const name = match[1];
+            if (!envMap.has(name)) {
+                envMap.set(name, { name, source: rel, hasDefault: false });
+            }
+        }
+        // Bun.env.VAR_NAME
+        const bunEnvPattern = /Bun\.env\.([A-Z_][A-Z0-9_]*)/g;
+        while ((match = bunEnvPattern.exec(content)) !== null) {
+            const name = match[1];
+            if (!envMap.has(name)) {
+                envMap.set(name, { name, source: rel, hasDefault: false });
+            }
+        }
+        // import.meta.env.VITE_VAR_NAME
+        const viteEnvPattern = /import\.meta\.env\.([A-Z_][A-Z0-9_]*)/g;
+        while ((match = viteEnvPattern.exec(content)) !== null) {
+            const name = match[1];
+            if (!envMap.has(name)) {
+                envMap.set(name, { name, source: rel, hasDefault: false });
+            }
+        }
+        // Python: os.environ["VAR"] or os.environ.get("VAR") or os.getenv("VAR")
+        const pyEnvPattern = /os\.(?:environ\[['"]|environ\.get\s*\(['"]|getenv\s*\(['"])([A-Z_][A-Z0-9_]*)['"]/g;
+        while ((match = pyEnvPattern.exec(content)) !== null) {
+            const name = match[1];
+            if (!envMap.has(name)) {
+                envMap.set(name, { name, source: rel, hasDefault: false });
+            }
+        }
+        // Go: os.Getenv("VAR")
+        const goEnvPattern = /os\.Getenv\(["']([A-Z_][A-Z0-9_]*)["']\)/g;
+        while ((match = goEnvPattern.exec(content)) !== null) {
+            const name = match[1];
+            if (!envMap.has(name)) {
+                envMap.set(name, { name, source: rel, hasDefault: false });
+            }
+        }
+    }
+    return Array.from(envMap.values()).sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/detectors/contracts.d.ts

@@ -0,0 +1,6 @@
+import type { RouteInfo, ProjectInfo } from "../types.js";
+/**
+ * Enhances route info with request/response type information
+ * by scanning the route handler files for type annotations
+ */
+export declare function enrichRouteContracts(routes: RouteInfo[], project: ProjectInfo): Promise<RouteInfo[]>;