You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**Upstream** skill and rules in this repo (e.g. `codemap`) stay **generic** — placeholder SQL and triggers, no product-specific paths. Consumer projects should **copy or symlink**, then **edit their copy** for team aliases and queries. A future `codemap` CLI may scaffold these files; customization always belongs in the **consumer** repo.
38
+
**Upstream** skill and rules in this repo (e.g. `codemap`) stay **generic** — placeholder SQL and triggers, no product-specific paths. Consumer projects can run **`codemap agents init`** (ships **`templates/agents`** on npm) or **copy/symlink** manually, then **edit their copy** for team aliases and queries. Customization always belongs in the **consumer** repo.
39
39
40
40
Rules live under **`.agents/rules/`**; skills under **`.agents/skills/<name>/SKILL.md`**. Symlink each into **`.cursor/`** (see [agents-first-convention.mdc](../.agents/rules/agents-first-convention.mdc)):
# Re-index only given paths (relative to project root)
49
49
codemap --files src/a.ts src/b.tsx
50
+
51
+
# Scaffold .agents/ rules and skills from bundled templates (see CONTRIBUTING)
52
+
codemap agents init
53
+
codemap agents init --force
50
54
```
51
55
52
56
**Environment / flags:**`--root` overrides **`CODEMAP_ROOT`** / **`CODEMAP_TEST_BENCH`**, then **`process.cwd()`**. Using a separate app as a QA target: [docs/bench-repo.md](docs/bench-repo.md).
|[extraction.md](./extraction.md)| Extraction history → layout in [architecture § Key Files](./architecture.md#key-files)|
12
12
|[packaging.md](./packaging.md)|`dist/`, npm entry, Node vs Bun, [Changesets](https://github.com/changesets/changesets)|
13
-
|[roadmap.md](./roadmap.md)|Planned work / backlog (not a `src/` inventory)|
13
+
|[roadmap.md](./roadmap.md)|Forward-looking backlog (not a `src/` inventory) |
14
14
|[why-codemap.md](./why-codemap.md)| Why index + SQL for agents |
15
15
16
16
**Conventions:** one topic per file; link with relative paths; no hardcoded symbol/file counts (use `codemap query` / `bun run dev query`); no source line numbers. **Contributors:** keep public API JSDoc useful; run `bun run check` — see [CONTRIBUTING](../.github/CONTRIBUTING.md).
@@ -79,6 +79,10 @@ A local SQLite database (`.codemap.db`) indexes the project tree and stores stru
79
79
└──────────────┘
80
80
```
81
81
82
+
### Language adapters
83
+
84
+
**`src/adapters/types.ts`** defines **`LanguageAdapter`**: `id`, `extensions`, and **`parse(ctx)`** returning structured rows for the SQLite schema. **`src/adapters/builtin.ts`** registers **TS/JS** (oxc), **CSS** (Lightning CSS), and **text** (markers + configured extensions). **`getAdapterForExtension(ext)`** selects the first matching adapter; unknown extensions fall back to **markers-only** text indexing. Future optional packages can add adapters once a registration API exists (see [roadmap.md](./roadmap.md)).
85
+
82
86
## Key Files
83
87
84
88
| File | Purpose |
@@ -95,6 +99,9 @@ A local SQLite database (`.codemap.db`) indexes the project tree and stores stru
95
99
|`constants.ts`| Shared constants — e.g. `LANG_MAP`|
96
100
|`markers.ts`| Shared marker extraction (`TODO`/`FIXME`/`HACK`/`NOTE`) — used by all parsers |
97
101
|`parse-worker.ts`| Worker thread entry point — reads, parses, and extracts file data in parallel |
102
+
|`adapters/`|`LanguageAdapter` types and built-in TS/CSS/text implementations |
103
+
|`parsed-types.ts`| Shared `ParsedFile` shape for workers and adapters |
Copy file name to clipboardExpand all lines: docs/benchmark.md
+13-16Lines changed: 13 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ Compares two approaches to answering common code-discovery questions:
9
9
10
10
The benchmark script lives at `src/benchmark.ts`.
11
11
12
-
**OSS note:**Scenario names and paths in the tables below came from **historical snapshots**of a large application. For reproducible numbers, we plan **fixture apps** under `fixtures/` — see [Fixtures (planned)](#fixtures-planned).
12
+
**OSS note:**For **repeatable** numbers, use **`fixtures/minimal/`**([Fixtures](#fixtures)) or index your own app with **`CODEMAP_ROOT`**. Tables below may still use historical labels; methodology is the same.
13
13
14
14
## Prerequisites
15
15
@@ -126,25 +126,22 @@ The benchmark also measures the cost of keeping the index fresh (3 runs each, sa
126
126
-**Full-text search** — the index doesn't store source code, so you still need grep/read for content-level queries (e.g. "find all usages of `console.log`")
127
127
-**Questions about code logic** — the index captures structure (names, types, locations), not semantics (what the code does)
128
128
129
-
## Fixtures (planned)
129
+
## Fixtures
130
130
131
-
### Problem
131
+
### `fixtures/minimal/`
132
132
133
-
Historical benchmark scenarios used paths and labels tied to a **specific product tree**. In this OSS repo, those paths are **not canonical** — the [Results](#results) tables above are **illustrative** methodology from snapshots, not guaranteed reproducible numbers across machines.
133
+
Small **private** package (not published) with intentional:
134
134
135
-
### Direction
135
+
-`usePermissions`, `~/api/client` import, `components/shop/*`, `utils/date`, CSS variables, and a TODO marker.
136
136
137
-
Introduce **one or more small example / test apps** under this repo (e.g. `fixtures/minimal-react/`, `fixtures/monorepo-ts/`) that:
137
+
**Local:**
138
138
139
-
- Include **stable, intentional** symbols, imports, CSS tokens, and markers.
140
-
- Are indexed with a **pinned `codemap.config`** so `src/benchmark.ts` runs against a **known layout**, not whatever `cwd` happens to be.
141
-
- Allow CI to run **deterministic** index + benchmark steps in isolation.
142
-
143
-
### Work items
139
+
```bash
140
+
export CODEMAP_ROOT="$(pwd)/fixtures/minimal"
141
+
bun run dev --full
142
+
bun run benchmark
143
+
```
144
144
145
-
-[ ] Add `fixtures/<name>/` with minimal TS/React components, sample pages, and CSS/markers.
146
-
-[ ] Point CI / docs at `CODEMAP_ROOT=$PWD/fixtures/<name>` (or `--root`) for benchmark runs.
147
-
-[ ] Rename benchmark scenario titles to match fixture semantics (e.g. paths under `fixtures/...`) or neutral names (“scoped component subtree”).
148
-
-[ ] Optionally vendor **two** fixtures (small vs medium) to show scale without depending on a private app.
145
+
**CI:** the workflow **Benchmark (fixture)** runs the same steps with `CODEMAP_ROOT=$GITHUB_WORKSPACE/fixtures/minimal`.
149
146
150
-
Until fixtures exist, treat the [Results](#results) tables as **illustrative** methodology only.
147
+
Scenario **titles** in `src/benchmark.ts` are still generic (historical names); **indexed row counts** on the fixture are stable for a given schema. A second, larger fixture is optional — see [roadmap.md](./ROADMAP.md).
|**CLI**|`package.json` → `"bin": { "codemap": "./dist/index.mjs" }` — same file as the library entry; **shebang** prepended at build time (tsdown `banner`) for `npx` / `node_modules/.bin`. |
16
16
|**Library**|`"exports"` / `"main"` / `"types"` → **`./dist/index.mjs`** and **`./dist/index.d.mts`** — `createCodemap`, `Codemap`, `defineConfig`, config types, `runCodemapIndex`, etc. |
17
-
|**Published files**|`package.json` → `"files": ["dist"]` — `src/` is not published. |
17
+
|**Published files**|`package.json` → `"files": ["dist", "templates"]` — `src/` is not published; **`templates/agents`** supports `codemap agents init`.|
Copy file name to clipboardExpand all lines: docs/roadmap.md
+3-24Lines changed: 3 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,34 +1,13 @@
1
1
# Roadmap
2
2
3
-
Forward-looking plans only — **not** a mirror of `src/`. **Where things live:**`package.json`, `src/`, `.github/workflows/`; **design:**[README.md](./README.md) (index),[architecture.md](./architecture.md), [packaging.md](./packaging.md).
3
+
Forward-looking plans only — **not** a mirror of `src/`. **Index:**[README.md](./README.md); **design:**[architecture.md](./architecture.md), [packaging.md](./packaging.md). **Shipped features** (adapters, fixtures, `codemap agents init`) live in `src/` and linked docs — not enumerated here.
4
4
5
5
---
6
6
7
7
## Next
8
8
9
-
### Pluggable language adapters
10
-
11
-
**TypeScript/JavaScript**, **CSS**, and **text/markers** are implemented under **`src/`** (oxc, lightningcss, etc.). **Not** done: a stable **`LanguageAdapter`-style** boundary so more languages ship as add-ons:
12
-
13
-
```text
14
-
LanguageAdapter
15
-
id: string
16
-
extensions: string[]
17
-
parseFile(path, content, ctx): ParsedFileFragment
18
-
```
19
-
20
-
-[ ] Define and document the internal adapter boundary (even if only one implementation ships in-repo at first).
21
-
-[ ] Optional community packages (e.g. Tree-sitter-based) with a **peerDependency** on `@stainless-code/codemap`.
22
-
23
-
### Benchmarks & fixtures
24
-
25
-
-[ ]**Fixture tree(s)** under `fixtures/` — [benchmark.md § Fixtures (planned)](./benchmark.md#fixtures-planned)
26
-
-[ ] Point **`CODEMAP_ROOT`** / **`--root`** at a fixture in CI for **repeatable** benchmark numbers
27
-
28
-
### Agent tooling
29
-
30
-
-[ ]**`codemap`** subcommands or a small companion CLI to **generate/sync** agent files (Cursor rules, `AGENTS.md`, `.agents/skills/` stubs) — org layout TBD
31
-
-[ ] Evaluate **[TanStack Intent](https://tanstack.com/intent/latest/docs/overview)** for versioned skills in `node_modules` (optional; generator remains fallback)
9
+
-**Community language adapters** — optional packages (e.g. Tree-sitter) with a **peerDependency** on `@stainless-code/codemap` and a public **registration** API beyond built-ins in [`src/adapters/`](../src/adapters/).
10
+
-**Agent tooling** — evaluate [TanStack Intent](https://tanstack.com/intent/latest/docs/overview) for versioned skills in `node_modules` (optional; **`codemap agents init`** remains the default).
0 commit comments