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
After **`bun run build`**, **`node dist/index.mjs`** matches the published **`codemap`** binary (same flags). **`bun link`** / global **`codemap`** also work when testing the packaged CLI.
21
24
@@ -66,6 +69,10 @@ If the question looks like any of these → use the index:
66
69
bun src/index.ts query "<SQL>"
67
70
```
68
71
72
+
**Row count:** The CLI does **not** impose a maximum number of rows. Add **`LIMIT`** (and **`ORDER BY`**) in SQL when you need a bounded list. For automation and multi-row answers, prefer **`bun src/index.ts query --json`** — stdout is a JSON array; on failure, stdout is **`{"error":"<message>"}`** and the process exits **1**.
73
+
74
+
**Verbatim answers:** When the user asks for lists, counts, or enumerated structural data from the index, **paste or summarize from the query output without inventing rows** — do not substitute a prose “summary” that omits rows the user asked to see. Prefer **`--json`** so the full result set is unambiguous.
Copy file name to clipboardExpand all lines: .agents/skills/codemap/SKILL.md
+40Lines changed: 40 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,6 +16,44 @@ bun src/index.ts query "<SQL>"
16
16
17
17
After **`bun run build`**, **`node dist/index.mjs query …`** or a linked **`codemap`** binary matches the published CLI. Use **`--root`** / **`CODEMAP_ROOT`** to index another tree.
18
18
19
+
## Query output and agents
20
+
21
+
-**`bun src/index.ts query --json`** prints a **JSON array** of row objects to stdout. On SQL error, stdout is **`{"error":"<message>"}`** and the process exits **1**.
22
+
- The CLI **does not cap** how many rows SQLite returns — add **`LIMIT`** and **`ORDER BY`** in SQL when you need a bounded list.
23
+
- When answering with structural facts from the index (lists of paths, symbols, dependency edges), **ground the answer in the query rows** — do not invent or silently drop rows. Prefer **`--json`** for large or multi-column results.
24
+
25
+
## Agent-friendly SQL recipes
26
+
27
+
Replace placeholders (`'...'`) with your module path, file glob, or symbol name.
28
+
29
+
**CLI shortcuts:****`bun src/index.ts query --recipe <id>`** runs bundled SQL (optional **`--json`**). **`bun src/index.ts query --recipes-json`** prints every bundled recipe (**`id`**, **`description`**, **`sql`**) as JSON (no index / DB required). **`bun src/index.ts query --print-sql <id>`** prints one recipe’s SQL only. Ids include **`fan-out`**, **`fan-out-sample`** (**`GROUP_CONCAT`** samples), **`fan-out-sample-json`** (same, but **`json_group_array`** — needs SQLite JSON1), **`fan-in`**, **`index-summary`**, **`files-largest`**, **`components-by-hooks`**, **`markers-by-kind`** — see **`bun src/index.ts query --help`**. The fan-out rows match the SQL below; others align with “Conditional aggregation”, “Codebase statistics”, and component sections later in this skill.
30
+
31
+
**Top files by dependency fan-out:**
32
+
33
+
```sql
34
+
SELECT from_path, COUNT(*) AS deps
35
+
FROM dependencies
36
+
GROUP BY from_path
37
+
ORDER BY deps DESC
38
+
LIMIT10;
39
+
```
40
+
41
+
**Same ranking, plus up to five sample targets per file** (uses a correlated subquery; adjust **`LIMIT 5`** as needed):
42
+
43
+
```sql
44
+
SELECTd.from_path,
45
+
COUNT(*) AS deps,
46
+
(SELECT GROUP_CONCAT(to_path, ' | ')
47
+
FROM (SELECT to_path FROM dependencies d2 WHEREd2.from_path=d.from_pathLIMIT5))
48
+
AS sample_targets
49
+
FROM dependencies d
50
+
GROUP BYd.from_path
51
+
ORDER BY deps DESC
52
+
LIMIT10;
53
+
```
54
+
55
+
**JSON array samples (JSON1):** replace **`GROUP_CONCAT`** with **`json_group_array(to_path)`** in that subquery if your SQLite build has JSON1 — or use **`bun src/index.ts query --recipe fan-out-sample-json`**.
-**`codemap query --json`**: print a JSON array of result rows to stdout (and **`{"error":"…"}`** on SQL errors) for agents and automation. Document that the query subcommand does **not** cap rows — use SQL **`LIMIT`** for bounded results. Update bundled agent rule and skill with **`--json`** preference, verbatim structural answers, and generic SQL recipes (fan-out + sample targets).
8
+
9
+
-**`codemap query --recipe <id>`** for bundled read-only SQL so agents can run common structural queries without embedding SQL on the command line. **`--json`** works with recipes the same way as ad-hoc SQL. Bundled ids include dependency **`fan-out`** / **`fan-out-sample`** / **`fan-out-sample-json`** (JSON1 **`json_group_array`**) / **`fan-in`**, index **`index-summary`**, **`files-largest`**, React **`components-by-hooks`** (comma-based hook count, no JSON1), and **`markers-by-kind`**. The benchmark suite uses the **`fan-out`** recipe SQL for an indexed-path scenario; docs clarify that recipes add no extra query cost vs pasting the same SQL.
10
+
11
+
-**Recipe discovery (no index / DB):****`codemap query --recipes-json`** prints all bundled recipes (**`id`**, **`description`**, **`sql`**) as JSON. **`codemap query --print-sql <id>`** prints one recipe’s SQL. **`listQueryRecipeCatalog()`** in **`src/cli/query-recipes.ts`** is the single derived view of **`QUERY_RECIPES`** for the JSON output.
12
+
13
+
**Golden tests**
14
+
15
+
-**`bun run test:golden`**: index **`fixtures/minimal`**, run scenarios from **`fixtures/golden/scenarios.json`**, and compare query JSON to **`fixtures/golden/minimal/`**. Use **`bun scripts/query-golden.ts --update`** after intentional fixture or schema changes. Documented in **benchmark.md** and **CONTRIBUTING**.
16
+
17
+
**Query robustness**
18
+
19
+
- With **`--json`**, **`{"error":"…"}`** is printed for invalid SQL, database open failures, and **`codemap query`** bootstrap failures (config / resolver setup), not only bad SQL. The CLI sets **`process.exitCode`** instead of **`process.exit`** so piped stdout is not cut off mid-stream.
20
+
21
+
**Benchmark & `CODEMAP_BENCHMARK_CONFIG`**
22
+
23
+
- Each **`indexedSql`** in custom scenario JSON is validated as a single read-only **`SELECT`** (or **`WITH` … `SELECT`**) — DDL/DML and **`RETURNING`** are rejected before execution.
24
+
- Config file paths are resolved from **`process.cwd()`** (see **benchmark.md**). **`traditional.regex`** strings are developer-controlled (local JSON); **`files`** mode compiles the regex once per scenario.
25
+
- Overlapping **globs** in the traditional path are **deduplicated** so **Files read** / **Bytes read** count each path once.
26
+
- The default **components in `shop/`** scenario uses a **`LIKE`** filter aligned with the traditional globs under **`components/shop/`** (**\*.tsx** and **\*.jsx**, matching **`components`** rows from the parser) and avoids unrelated paths such as **`workshop`**.
27
+
28
+
**Recipes (determinism)**
29
+
30
+
- Bundled recipe SQL adds stable secondary **`ORDER BY`** columns (and orders inner **`LIMIT`** samples) so **`--recipe`** / **`--json`** output does not vary on aggregate ties.
31
+
32
+
**External QA**
33
+
34
+
-**`bun run qa:external`**: **`--max-files`** and **`--max-symbols`** must be positive integers (invalid values throw before indexing).
Copy file name to clipboardExpand all lines: .github/CONTRIBUTING.md
+7-1Lines changed: 7 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,9 @@ Codemap is in **bootstrap / extraction** phase. Before large PRs, please open an
11
11
bun install # runs `prepare` → Husky git hooks
12
12
bun run dev # same as `bun src/index.ts` — CLI from source
13
13
bun test
14
-
bun run check # format + lint + tests + typecheck + build
14
+
bun run test:golden # golden SQL vs fixtures/minimal (also runs at end of `bun run check`)
15
+
bun run test:golden:external # Tier B: local tree via CODEMAP_ROOT / --root (not in CI)
16
+
bun run check # format + lint + tests + typecheck + build + test:golden
15
17
bun run clean # remove untracked/ignored build artifacts (keeps `.env`, `.codemap.db*`)
16
18
bun run check-updates # interactive dependency updates (`bun update -i --latest`)
17
19
```
@@ -36,6 +38,8 @@ Then open a PR on GitHub into **`main`**.
36
38
-**Public API** — Anything exported from the package entry (`src/index.ts` → `src/api.ts`, `config.ts`, shared types) should have **JSDoc** that reads well in hovers and in published typings.
37
39
-**Layers** — Keep boundaries clear: [architecture.md](../docs/architecture.md) (`cli` → `application` → infrastructure). Don’t let CLI concerns leak into parsers or the DB layer.
38
40
-**Before you open / update a PR** — `bun run check` (or at least `bun run test` + `bun run typecheck` while iterating).
41
+
-**Golden queries (Tier A)** — If you change `fixtures/minimal/` or schema/query behavior expected by [fixtures/golden/](../fixtures/golden/), run `bun scripts/query-golden.ts --update`, review diffs, and commit updated JSON under `fixtures/golden/minimal/`. Prefer **fixing the indexer** when output changes for the wrong reason; only refresh goldens when the new rows are correct. See [docs/golden-queries.md](../docs/golden-queries.md).
42
+
-**Golden queries (Tier B)** — Against a **local** clone, use `bun run test:golden:external` with `CODEMAP_ROOT` / `--root`. Copy [fixtures/golden/scenarios.external.example.json](../fixtures/golden/scenarios.external.example.json) to `scenarios.external.json` if you need custom scenarios; goldens under `fixtures/golden/external/` are gitignored — do not commit snapshots from proprietary trees.
39
43
-**Style** — Match Oxfmt/Oxlint; prefer **straight-line code** and extracted helpers over long nested blocks.
40
44
41
45
**Editor (VS Code):**[`.vscode/extensions.json`](../.vscode/extensions.json) lists recommended extensions (Bun, Oxc, TypeScript native preview, etc.). [`.vscode/settings.json`](../.vscode/settings.json) enables Oxc format on save and `tsgo`. Formatting and lint rules live in [`.oxfmtrc.json`](../.oxfmtrc.json) and [`.oxlintrc.json`](../.oxlintrc.json) (no framework-specific options beyond defaults).
@@ -46,6 +50,8 @@ Then open a PR on GitHub into **`main`**.
46
50
47
51
Do **not** add Codemap as a dependency to the bench repo. In **this** repo, copy `.env.example` to `.env` and set **`CODEMAP_TEST_BENCH`** to an **absolute path** to the other clone, then run `bun src/index.ts` as usual. See [docs/benchmark.md § Indexing another project](../docs/benchmark.md#indexing-another-project).
48
52
53
+
**One-shot QA (index + disk checks + benchmark):**`CODEMAP_ROOT=/absolute/path/to/app bun run qa:external` (or set **`CODEMAP_TEST_BENCH`** in `.env`; optional `--root` overrides). Optional **`--max-files`** / **`--max-symbols`** (positive integers; default caps sampling). Validates indexed paths exist, spot-checks symbol lines vs files, prints sample SQL rows, then runs `src/benchmark.ts`. Do **not** add external app source into this repository.
54
+
49
55
Releases: **[@changesets/cli](https://github.com/changesets/changesets)** — run **`bun run changeset`** when your PR should bump the version; see [docs/packaging.md § Releases](../docs/packaging.md#releases).
50
56
51
57
**Issues:** use [GitHub issue templates](https://github.com/stainless-code/codemap/issues/new/choose) — **Core bug** vs **Adapter proposal** (see `.github/ISSUE_TEMPLATE/`).
|`bun run dev`| Run the CLI from source (same as `bun src/index.ts`) |
97
+
|`bun run check`| Build, format check, lint, tests, typecheck — run before pushing |
98
+
|`bun run fix`| Apply lint fixes, then format |
99
+
|`bun run test` / `bun run typecheck`| Focused checks |
100
+
|`bun run test:golden`| SQL snapshot regression on `fixtures/minimal` (included in `check`) |
101
+
|`bun run test:golden:external`| Tier B: local tree via `CODEMAP_*` / `--root` (not in default `check`) |
102
+
|`bun run qa:external`| Index + sanity checks + benchmark on `CODEMAP_ROOT` / `CODEMAP_TEST_BENCH`|
90
103
91
104
```bash
92
105
bun install
@@ -100,11 +113,13 @@ bun run fix # oxlint --fix, then oxfmt
100
113
101
114
## Benchmark
102
115
116
+
Use a **real** project path (the repo must exist on disk). See [docs/benchmark.md § Indexing another project](docs/benchmark.md#indexing-another-project).
117
+
103
118
```bash
104
-
CODEMAP_ROOT=/path/to/indexed-repo bun src/benchmark.ts
119
+
CODEMAP_ROOT=/absolute/path/to/indexed-repo bun src/benchmark.ts
105
120
```
106
121
107
-
Details: [docs/benchmark.md](docs/benchmark.md).
122
+
Optional **`CODEMAP_BENCHMARK_CONFIG`** for repo-specific scenarios: [docs/benchmark.md § Custom scenarios](docs/benchmark.md#custom-scenarios-codemap_benchmark_config).
0 commit comments