@stainless-code/codemap 0.1.0

package/templates/agents/rules/agents-first-convention.mdc

@@ -0,0 +1,37 @@
+---
+description: When creating or moving rules/skills, always store the source file in .agents/ and symlink from .cursor/
+alwaysApply: true
+---
+
+# Agents-First File Convention
+
+When creating **any** new rule or skill, follow this convention:
+
+## Rules (`.mdc` files)
+
+1. Create the file in `.agents/rules/<name>.mdc`
+2. Create a symlink in `.cursor/rules/`:
+
+   ```bash
+   ln -s ../../.agents/rules/<name>.mdc .cursor/rules/<name>.mdc
+   ```
+
+## Skills (`SKILL.md` files)
+
+1. Create the directory and file in `.agents/skills/<name>/SKILL.md`
+2. Create a symlink in `.cursor/skills/`:
+
+   ```bash
+   ln -s ../../.agents/skills/<name> .cursor/skills/<name>
+   ```
+
+## Why
+
+- `.agents/` is the **source of truth** — it is IDE-agnostic and works across different AI coding tools.
+- `.cursor/` only contains **symlinks** pointing back to `.agents/`.
+- This keeps configuration portable and avoids duplication.
+
+## Never
+
+- Never place original rule/skill content directly in `.cursor/rules/` or `.cursor/skills/`.
+- Never create a rule or skill without both the `.agents/` file and the `.cursor/` symlink.

package/templates/agents/rules/codemap.mdc

@@ -0,0 +1,110 @@
+---
+alwaysApply: true
+---
+
+# Codemap (structural codebase index)
+
+> **STOP.** Before you call Grep, Glob, SemanticSearch, or Read to answer a **structural** question about this repository — query the Codemap SQLite index first. This is not optional when the question matches a trigger pattern below.
+
+A local database (default **`.codemap.db`**) indexes structure: symbols, imports, exports, components, dependencies, markers, CSS variables, CSS classes, CSS keyframes.
+
+**Generic defaults:** This rule is **project-agnostic**. After you vendor or symlink it (or use a future `codemap` CLI that writes agent files), **edit your copy** to add app-specific triggers and SQL — upstream text is only a baseline.
+
+## CLI (this repo vs installed package)
+
+| Context | Incremental index | Query |
+| ------- | ----------------- | ----- |
+| Developing in this repo | `bun src/index.ts` | `bun src/index.ts query "<SQL>"` |
+| After `bun link` / global `codemap` | `codemap` | `codemap query "<SQL>"` |
+| Published package (when available) | `bunx @stainless-code/codemap` | `bunx @stainless-code/codemap query "<SQL>"` |
+
+Index another project: **`--root /path/to/repo`**, or set **`CODEMAP_ROOT`** or **`CODEMAP_TEST_BENCH`** (e.g. in **`.env`** in this repo — see [docs/benchmark.md § Indexing another project](../../docs/benchmark.md#indexing-another-project)). Full rebuild: **`--full`**. Targeted re-index: **`--files path/to/a.ts path/to/b.tsx`**.
+
+## Session start (do this ONCE per conversation)
+
+Run incremental indexing to catch changes made outside this session:
+
+```bash
+bun src/index.ts
+```
+
+## Pre-flight check (do this EVERY time before searching)
+
+1. **Does the question match a trigger pattern below?**
+2. **If yes → query the index.** Do NOT use Grep/Glob/SemanticSearch/Read.
+3. **If the index result is incomplete → THEN fall back** to other tools, but always try the index first.
+
+Violating this order is wrong even if you get the right answer — it wastes time and ignores the tool purpose-built for this.
+
+## Trigger patterns
+
+If the question looks like any of these → use the index:
+
+| Question shape | Table(s) |
+| --- | --- |
+| "What/which files import X?" | `imports` (by `source`) or `dependencies` (by `to_path`) |
+| "Where is X defined?" | `symbols` |
+| "What does file X export?" | `exports` |
+| "What hooks does component X use?" / "List React components" | `components` |
+| "What are the CSS variables/tokens for X?" | `css_variables` |
+| "Find all TODOs/FIXMEs" | `markers` |
+| "Who depends on file X?" / "What does file X depend on?" | `dependencies` |
+| "How many files/symbols/components are there?" | any table with `COUNT(*)` |
+| "What are the CSS classes in X?" | `css_classes` |
+| "What keyframe animations exist?" | `css_keyframes` |
+
+## When Grep / Read IS appropriate
+
+- Reading implementation details you need to edit
+- Reviewing logic, control flow, or business rules
+- Searching for patterns the index doesn't capture (string literals, inline logic, etc.)
+
+## How to query
+
+```bash
+bun src/index.ts query "<SQL>"
+```
+
+## Quick reference queries
+
+| I need to... | Query |
+| --- | --- |
+| Find a symbol | `SELECT name, kind, file_path, line_start, line_end, signature FROM symbols WHERE name = '...'` |
+| Find a symbol (fuzzy) | `SELECT name, kind, file_path, line_start FROM symbols WHERE name LIKE '%...%'` |
+| See file exports | `SELECT name, kind, is_default FROM exports WHERE file_path LIKE '%...'` |
+| See file imports | `SELECT source, specifiers, is_type_only FROM imports WHERE file_path LIKE '%...'` |
+| Who imports this module? | `SELECT DISTINCT file_path FROM imports WHERE source LIKE '~/some/module%'` |
+| Who imports this file? | `SELECT DISTINCT from_path FROM dependencies WHERE to_path LIKE '%...'` |
+| What does this depend on? | `SELECT DISTINCT to_path FROM dependencies WHERE from_path LIKE '%...'` |
+| Component info | `SELECT name, props_type, hooks_used FROM components WHERE name = '...'` |
+| All components | `SELECT name, file_path, props_type, hooks_used FROM components ORDER BY name` |
+| TODOs in a file | `SELECT line_number, content FROM markers WHERE file_path LIKE '%...' AND kind = 'TODO'` |
+| Most complex files | `SELECT from_path, COUNT(*) as deps FROM dependencies GROUP BY from_path ORDER BY deps DESC LIMIT 10` |
+| CSS design tokens | `SELECT name, value, scope FROM css_variables WHERE name LIKE '--%...'` |
+| CSS module classes | `SELECT name, file_path FROM css_classes WHERE is_module = 1` |
+| CSS keyframes | `SELECT name, file_path FROM css_keyframes` |
+
+**Use `DISTINCT`** on dependency and import queries — a file importing multiple specifiers from the same module produces duplicate rows.
+
+For the full schema, advanced query patterns, and troubleshooting, read the skill at `.agents/skills/codemap/SKILL.md`.
+
+## Keeping it fresh
+
+**After completing a step that modified source files, re-index before making any further queries.** The index only reflects the state at the time it was last built — edits you just made won't appear until you re-index.
+
+```bash
+# Targeted — re-index only the files you just touched
+bun src/index.ts --files path/to/file1.tsx path/to/file2.ts
+
+# Incremental — auto-detects changed files via git
+bun src/index.ts
+
+# Full rebuild — after rebase, branch switch, or stale index
+bun src/index.ts --full
+```
+
+### When to re-index
+
+- **After editing files** — use `--files` with the paths you modified (fastest). Deleted files are auto-detected and removed from the index
+- **After switching branches or rebasing** — run `--full`
+- **When unsure which files changed** — run without flags to auto-detect via git

package/templates/agents/skills/codemap/SKILL.md

@@ -0,0 +1,312 @@
+# Codemap — full reference
+
+Query codebase structure via SQLite instead of scanning files. Use when exploring code, finding symbols, tracing dependencies, or auditing a project indexed by **Codemap**.
+
+## Bundled content (stay generic)
+
+Examples below use **placeholders** (`'...'`, `getConfig`, `~/lib/api`, etc.) — not a real product tree. **Shipped skill and rules stay generic** so they apply to any repo.
+
+**In your project:** copy or symlink these files into `.agents/` / `.cursor/` (see **`.github/CONTRIBUTING.md`**), or use a future **`codemap` CLI** that vendors agent files. Then **edit your copy** to add your team’s tsconfig aliases, directory conventions, and SQL snippets you reuse. Treat upstream updates as a reference; merge deliberately.
+
+**Run queries**
+
+```bash
+bun src/index.ts query "<SQL>"
+```
+
+When the package is installed globally or via `bunx`: `codemap query "<SQL>"` or `bunx @stainless-code/codemap query "<SQL>"`. Use **`--root`** to point at another project.
+
+## Schema
+
+### `files` — Every indexed file
+
+| Column        | Type    | Description                                                                      |
+| ------------- | ------- | -------------------------------------------------------------------------------- |
+| path          | TEXT PK | Relative path from project root                                                  |
+| content_hash  | TEXT    | Wyhash fingerprint (base-36)                                                     |
+| size          | INTEGER | File size in bytes                                                               |
+| line_count    | INTEGER | Number of lines                                                                  |
+| language      | TEXT    | `ts`, `tsx`, `js`, `jsx`, `css`, `md`, `mdx`, `mdc`, `json`, `yaml`, `sh`, `txt` |
+| last_modified | INTEGER | Unix timestamp (ms)                                                              |
+| indexed_at    | INTEGER | When this file was last indexed                                                  |
+
+### `symbols` — Functions, types, interfaces, enums, constants, classes
+
+| Column            | Type       | Description                                                           |
+| ----------------- | ---------- | --------------------------------------------------------------------- |
+| id                | INTEGER PK | Auto-increment ID                                                     |
+| file_path         | TEXT FK    | References `files(path)`                                              |
+| name              | TEXT       | Symbol name                                                           |
+| kind              | TEXT       | `function`, `class`, `type`, `interface`, `enum`, `const`, `variable` |
+| line_start        | INTEGER    | Start line (1-based)                                                  |
+| line_end          | INTEGER    | End line (1-based)                                                    |
+| signature         | TEXT       | e.g. `createHandler()`, `type UserProps`                              |
+| is_exported       | INTEGER    | 1 if exported                                                         |
+| is_default_export | INTEGER    | 1 if default export                                                   |
+
+### `imports` — Import statements
+
+| Column        | Type    | Description                                     |
+| ------------- | ------- | ----------------------------------------------- |
+| file_path     | TEXT FK | The importing file                              |
+| source        | TEXT    | Raw import source (e.g. `~/lib/utils`, `react`) |
+| resolved_path | TEXT    | Resolved file path, NULL for external packages  |
+| specifiers    | TEXT    | JSON array of imported names                    |
+| is_type_only  | INTEGER | 1 if `import type`                              |
+| line_number   | INTEGER | Line of the import statement                    |
+
+### `exports` — Export manifest
+
+| Column           | Type    | Description                                   |
+| ---------------- | ------- | --------------------------------------------- |
+| file_path        | TEXT FK | The exporting file                            |
+| name             | TEXT    | Exported name (`default` for default exports) |
+| kind             | TEXT    | `value`, `type`, `re-export`                  |
+| is_default       | INTEGER | 1 if default export                           |
+| re_export_source | TEXT    | Source module for re-exports                  |
+
+### `components` — React components (TSX files)
+
+| Column            | Type    | Description                                                  |
+| ----------------- | ------- | ------------------------------------------------------------ |
+| file_path         | TEXT FK | Component file                                               |
+| name              | TEXT    | Component name (PascalCase)                                  |
+| props_type        | TEXT    | Props type/interface name, if detected                       |
+| hooks_used        | TEXT    | JSON array of hooks called (e.g. `["useState", "useQuery"]`) |
+| is_default_export | INTEGER | 1 if default export                                          |
+
+### `dependencies` — File-to-file dependency graph
+
+| Column    | Type    | Description             |
+| --------- | ------- | ----------------------- |
+| from_path | TEXT FK | The file that imports   |
+| to_path   | TEXT    | The file being imported |
+
+### `markers` — TODO/FIXME/HACK/NOTE comments
+
+| Column      | Type    | Description                     |
+| ----------- | ------- | ------------------------------- |
+| file_path   | TEXT FK | File containing the marker      |
+| line_number | INTEGER | Line number (1-based)           |
+| kind        | TEXT    | `TODO`, `FIXME`, `HACK`, `NOTE` |
+| content     | TEXT    | The marker text                 |
+
+### `css_variables` — CSS custom properties (design tokens)
+
+| Column      | Type    | Description                                         |
+| ----------- | ------- | --------------------------------------------------- |
+| file_path   | TEXT FK | CSS file containing the variable                    |
+| name        | TEXT    | Variable name (e.g. `--blue-50`, `--text-h1`)       |
+| value       | TEXT    | Parsed value (e.g. `rgb(215, 225, 242)`, `3rem`)    |
+| scope       | TEXT    | Where defined: `:root`, `@theme`, or selector scope |
+| line_number | INTEGER | Line number (1-based)                               |
+
+### `css_classes` — CSS class definitions
+
+| Column      | Type    | Description                     |
+| ----------- | ------- | ------------------------------- |
+| file_path   | TEXT FK | CSS file containing the class   |
+| name        | TEXT    | Class name (without `.` prefix) |
+| is_module   | INTEGER | 1 if from a `.module.css` file  |
+| line_number | INTEGER | Line number (1-based)           |
+
+### `css_keyframes` — @keyframes animation definitions
+
+| Column      | Type    | Description                       |
+| ----------- | ------- | --------------------------------- |
+| file_path   | TEXT FK | CSS file containing the keyframes |
+| name        | TEXT    | Animation name                    |
+| line_number | INTEGER | Line number (1-based)             |
+
+### `meta` — Index metadata
+
+| Key                   | Value                             |
+| --------------------- | --------------------------------- |
+| `last_indexed_commit` | Git SHA of HEAD when last indexed |
+| `indexed_at`          | ISO timestamp of last index       |
+| `file_count`          | Total files indexed               |
+| `project_root`        | Absolute path to project          |
+| `schema_version`      | Schema version number             |
+
+## Query patterns
+
+### Basic lookups
+
+```sql
+-- Find a symbol definition
+SELECT name, kind, file_path, line_start, line_end, signature
+FROM symbols WHERE name = 'getConfig';
+
+-- Fuzzy symbol search
+SELECT name, kind, file_path, line_start
+FROM symbols WHERE name LIKE '%Config%' ORDER BY name;
+
+-- All exported symbols from a file
+SELECT name, kind, signature
+FROM symbols WHERE file_path LIKE '%settings-provider%' AND is_exported = 1;
+
+-- File overview (imports + exports)
+SELECT 'import' as dir, source as name, specifiers as detail
+FROM imports WHERE file_path LIKE '%OrderRow%'
+UNION ALL
+SELECT 'export', name, kind FROM exports WHERE file_path LIKE '%OrderRow%';
+```
+
+### Dependency analysis
+
+**Use `DISTINCT`** on dependency and import queries — a file importing multiple specifiers from the same module produces duplicate rows.
+
+```sql
+-- Who imports a module by its alias? (matches raw import source string)
+SELECT DISTINCT file_path FROM imports WHERE source LIKE '~/lib/api%';
+
+-- Direct dependents (who imports this file? uses resolved paths)
+SELECT DISTINCT from_path FROM dependencies WHERE to_path LIKE '%format-date%';
+
+-- Direct dependencies (what does this file import?)
+SELECT DISTINCT to_path FROM dependencies WHERE from_path LIKE '%OrderRow%';
+
+-- Most-imported files (hotspots)
+SELECT to_path, COUNT(*) as importers
+FROM dependencies GROUP BY to_path ORDER BY importers DESC LIMIT 15;
+
+-- Most complex files (most dependencies)
+SELECT from_path, COUNT(*) as dep_count
+FROM dependencies GROUP BY from_path ORDER BY dep_count DESC LIMIT 15;
+
+-- Circular dependencies (1-hop)
+SELECT a.from_path, a.to_path
+FROM dependencies a
+JOIN dependencies b ON a.to_path = b.from_path AND b.to_path = a.from_path;
+
+-- Orphan files (no one imports them, excluding test and story files)
+SELECT f.path FROM files f
+LEFT JOIN dependencies d ON d.to_path = f.path
+WHERE d.from_path IS NULL
+  AND f.path NOT LIKE '%.test.%'
+  AND f.path NOT LIKE '%.stories.%'
+ORDER BY f.path;
+```
+
+### Component analysis
+
+```sql
+-- Components using a specific hook
+SELECT name, file_path, hooks_used
+FROM components WHERE hooks_used LIKE '%useTheme%';
+
+-- Components with most hooks (complexity indicator)
+SELECT name, file_path,
+  json_array_length(hooks_used) as hook_count
+FROM components ORDER BY hook_count DESC LIMIT 15;
+
+-- Components with props types
+SELECT name, file_path, props_type
+FROM components WHERE props_type IS NOT NULL ORDER BY name;
+```
+
+### CSS analysis
+
+```sql
+-- All design tokens (color palette)
+SELECT name, value, scope FROM css_variables
+WHERE name LIKE '--blue%' OR name LIKE '--gray%' ORDER BY name;
+
+-- Tailwind theme tokens
+SELECT name, value FROM css_variables WHERE scope = '@theme' LIMIT 20;
+
+-- All CSS module classes in a file
+SELECT name FROM css_classes
+WHERE file_path LIKE '%ProductCard%' AND is_module = 1;
+
+-- All keyframe animations
+SELECT name, file_path FROM css_keyframes;
+
+-- Token categories (grouped by prefix)
+SELECT
+  substr(name, 1, instr(substr(name, 3), '-') + 2) as prefix,
+  COUNT(*) as count
+FROM css_variables
+GROUP BY prefix ORDER BY count DESC;
+```
+
+### Efficient pagination (cursor-based)
+
+For large result sets, avoid `OFFSET` — use cursor-based pagination with the last-seen value:
+
+```sql
+-- First page
+SELECT name, kind, file_path, line_start FROM symbols
+WHERE is_exported = 1
+ORDER BY name LIMIT 50;
+
+-- Next page (use last name from previous result as cursor)
+SELECT name, kind, file_path, line_start FROM symbols
+WHERE is_exported = 1 AND name > 'lastSeenName'
+ORDER BY name LIMIT 50;
+```
+
+### Conditional aggregation (single query for multiple counts)
+
+```sql
+-- Instead of multiple COUNT(*) queries, use conditional aggregation:
+SELECT
+  (SELECT COUNT(*) FROM files) as files,
+  (SELECT COUNT(*) FROM symbols) as symbols,
+  (SELECT COUNT(*) FROM imports) as imports,
+  (SELECT COUNT(*) FROM components) as components,
+  (SELECT COUNT(*) FROM dependencies) as dependencies;
+```
+
+### Codebase statistics
+
+```sql
+-- Files by language
+SELECT language, COUNT(*) as count FROM files GROUP BY language;
+
+-- Symbols by kind
+SELECT kind, COUNT(*) as count FROM symbols GROUP BY kind ORDER BY count DESC;
+
+-- Exported vs internal symbols
+SELECT
+  SUM(is_exported) as exported,
+  COUNT(*) - SUM(is_exported) as internal
+FROM symbols;
+
+-- Largest files
+SELECT path, line_count, size FROM files ORDER BY line_count DESC LIMIT 15;
+
+-- All TODO/FIXME markers
+SELECT kind, COUNT(*) as count FROM markers GROUP BY kind;
+```
+
+## Maintenance
+
+From this repository:
+
+```bash
+# Targeted — re-index only specific files you just modified
+bun src/index.ts --files path/to/file.tsx path/to/other.ts
+
+# Incremental — auto-detects changes via git
+bun src/index.ts
+
+# Full rebuild — after rebase, branch switch, or stale index
+bun src/index.ts --full
+
+# Check index freshness
+bun src/index.ts query "SELECT key, value FROM meta"
+```
+
+**Prefer `--files`** when you know which files you changed — it skips git diff and filesystem scanning for the rest of the tree. Deleted files passed to `--files` are auto-removed from the index.
+
+When Codemap is installed as a package: `codemap`, `codemap --root /path/to/project`, or `bunx @stainless-code/codemap …` (same flags).
+
+## Troubleshooting
+
+| Problem                    | Solution                                                                                                               |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Stale results after rebase | Run `bun src/index.ts --full` (or `codemap --full` when installed)                                                     |
+| Missing file in results    | Check exclude / include globs in **`codemap.config.ts`**, **`codemap.config.json`**, or defaults in **`src/index.ts`** |
+| `resolved_path` is NULL    | Import is an external package (not in project)                                                                         |
+| Resolver errors            | Verify `tsconfig.json` paths (or **`tsconfigPath`** in config) when resolving aliases                                  |