Canonical definitions of Codemap terms. Disambiguates pairs that look similar (TS shape vs SQL table, recipe vs query, hub vs barrel) and pins the SQL-table names so cross-references are unambiguous.
When introducing a new domain noun in a PR, add or update its entry here per README § Rules for Agents (Rule 9).
Alphabetical, lowercase. Disambiguation pairs link to each other.
- TS shape = a TypeScript interface or type alias.
- SQLite table = an actual on-disk table in
.codemap.db. - Recipe = a bundled SQL string in
src/cli/query-recipes.ts, exposed viacodemap query --recipe <id>. - Query = any SQL run against the index (recipe or ad-hoc).
Repo-level directory holding rules (.agents/rules/<name>.md) and skills (.agents/skills/<name>/SKILL.md). Source of truth; IDE-agnostic. Mirrored to .cursor/rules/ via per-file symlinks per agents-first-convention.
See language adapter.
A .agents/rules/<name>.md file with YAML frontmatter. Distinct from a skill (longer, scenario-specific). Distinct from a bundled recipe (which is SQL, not Markdown).
In Codemap usage: a file with a high number of exports rows — typically a public-API hub like src/index.ts. Surfaced by the barrel-files recipe. Distinct from hub below — barrel measures exports out, hub measures imports in.
The shared batchInsert<T>() helper in src/db.ts. Splits inserts into multi-row INSERT … VALUES (…),(…) statements of BATCH_SIZE (500) rows each, with pre-computed placeholder strings. Used by every insertX function.
Bun's native SQLite binding. Codemap uses it on Bun; falls back to better-sqlite3 on Node. Both are wrapped by src/sqlite-db.ts so call sites are runtime-agnostic.
Synchronous Node.js SQLite binding. The Node-side counterpart to bun:sqlite. Allows one statement per prepare(), unlike bun:sqlite which accepts multiple — see packaging § Node vs Bun.
Function-scoped call edges, deduped per (caller_scope, callee_name) per file. caller_scope is dot-joined enclosing scope (e.g. UserService.run). Module-level calls are excluded. See CallRow for the TS shape.
TS shape for one row of the calls table. Maps 1:1 to the SQLite columns.
The extraction path a file took during parsing. One of ts, css, or text. Stored on ParsedFile.category, not on a SQLite table. See ParsedFile.
The on-disk SQLite database file at <project_root>/.codemap.db. Always accompanied by .codemap.db-wal and .codemap.db-shm while open (WAL mode). Gitignored via the .codemap.* pattern that codemap agents init ensures.
CLI subcommand emitting a JSON envelope (ContextEnvelope) with project metadata, top hubs, sample markers, recipe catalog, and optional intent classification via --for "<intent>".
CLI subcommand comparing on-disk SHA-256 against files.content_hash. Statuses: stale | missing | unindexed. Exits 1 on any drift.
React components (PascalCase + JSX return or hook usage). PascalCase functions that neither return JSX nor call hooks stay in symbols only — never components. hooks_used is JSON-encoded. See ComponentRow.
Column on the files table. Lowercase SHA-256 hex of file bytes computed by src/hash.ts. Drives incremental staleness detection (getChangedFiles) and powers the files-hashes recipe + codemap validate CLI.
TS shape for the JSON emitted by codemap context. Stable contract; agents can key off field names.
A SQLite index that includes every column needed by a query, so SQLite reads everything from the index B-tree without touching the main table. The query plan shows USING COVERING INDEX. Used heavily for AI agent query patterns — see architecture § Covering indexes.
CSS class names from selectors (no leading .). is_module = 1 for .module.css files. See CssClassRow.
@keyframes <name> declarations. See CssKeyframeRow.
CSS custom properties (--token: value). scope is :root, @theme (Tailwind v4), or the selector text. See CssVariableRow.
Data Definition Language — the CREATE TABLE / CREATE INDEX strings in src/db.ts. Distinct from schema (the conceptual structure) and from SCHEMA_VERSION (the integer that triggers auto-rebuild on mismatch).
Resolved file-to-file edges derived from imports.resolved_path. Composite primary key (from_path, to_path). Self-edges and unresolved imports are excluded. STRICT, WITHOUT ROWID. See DependencyRow.
TS shape for one row of the dependencies table.
The 4-criterion gate for whether a doc earns its place — see README § Existence test. Forces deletion of stale docs.
Named, default, and re-exports. kind is value / type / re-export; re_export_source is non-null only for re-export rows. See ExportRow.
TS shape for one row of the exports table.
Number of edges into a file in the dependencies table — COUNT(*) FROM dependencies WHERE to_path = ?. Surfaces as the fan-in recipe (top files by inbound edges, i.e. hubs).
Number of edges out of a file — COUNT(*) FROM dependencies WHERE from_path = ?. Surfaces as the fan-out recipe.
Header row for every indexed file. path is the primary key; all other tables FK to it with ON DELETE CASCADE. See FileRow.
TS shape for one row of the files table. Distinct from the files SQLite table itself (the table name is lowercase plural; the TS interface is PascalCase singular).
Hand-crafted source tree under fixtures/minimal/ used as the corpus for golden tests. Excluded from oxlint via ignorePatterns: ["fixtures"] so auto-fixes never mutate test corpora.
Index mode that drops every table and rebuilds from scratch — codemap --full or cm.index({ mode: "full" }). Triggers automatically when SCHEMA_VERSION mismatches or when no previous index exists. Optimized via worker threads, deferred index creation, and relaxed PRAGMAs.
Read/write helpers for the meta key-value table. Stores schema_version, last_indexed_commit, indexed_at, etc.
Include patterns (relative to project root) used to find indexable files. Defaults in DEFAULT_INCLUDE_PATTERNS. Implemented via tinyglobby on Node and Bun.Glob on Bun (both emit POSIX paths).
A bun scripts/query-golden.ts regression that compares a query/recipe's output against a checked-in JSON snapshot. Tier A uses fixtures/minimal/; Tier B uses external trees via CODEMAP_*. See golden-queries.md.
SHA-256 hex computed over file bytes via src/hash.ts. Same algorithm on Bun and Node — Bun.hash is not used because it differs across runtimes.
A file with high fan-in — many other files import it. Surfaced by the fan-in recipe (which we historically also called hubs). Distinct from barrel file (high fan-out via exports).
Index mode that diffs against last_indexed_commit (git) and only re-indexes changed files. Default mode (no flag); falls back to full rebuild if commit history is incompatible.
Raw import statements. specifiers is JSON-encoded; resolved_path is non-null only when the resolver could map source to an indexed file. See ImportRow and the resolved view dependencies.
TS shape for one row of the imports table.
TS shape emitted under IndexRunStats.performance when --performance is set. Per-phase timing + top-10 slowest files. Note: total_ms is indexFiles wall-clock and excludes collect_ms.
Public TS shape returned from Codemap#index() and runCodemapIndex(). Wall-clock + row counts + optional performance report.
A LanguageAdapter registered in src/adapters/builtin.ts that maps file extensions to a parser (parse(ctx) → ParsedFilePayload). Currently three built-ins: builtin.ts-js (oxc), builtin.css (lightningcss), builtin.text (markers-only). Future community adapters can register additional ones.
meta key holding the HEAD SHA at the end of the previous successful index run. Used by getChangedFiles to compute the changed set.
Rust-based CSS parser (NAPI bindings). Codemap's src/css-parser.ts uses its visitor pattern to extract custom properties, classes, keyframes, and @import sources. Not a preprocessor — Sass / Less / SCSS are out of scope.
TODO / FIXME / HACK / NOTE comments extracted from any indexed file (TS, CSS, Markdown, JSON, YAML, …). Stored in the markers table; surfaced by the markers-by-kind recipe. See MarkerRow.
TS shape for one row of the markers table.
Key-value metadata table. Holds schema_version, last_indexed_commit, indexed_at, file_count, project_root. STRICT, WITHOUT ROWID.
Rust-based TypeScript / JavaScript parser (NAPI bindings). Codemap's src/parser.ts uses it to extract symbols, imports, exports, components, type members, calls, and markers from .ts / .tsx / .js / .jsx (and .mts / .cts / .mjs / .cjs).
Rust-based import-path resolver (NAPI bindings). Configured with tsconfig.json for alias resolution (~/utils/foo). Produces the dependencies table from imports.resolved_path.
Rust-based linter. Configured in .oxlintrc.json. Auto-fixes most violations via bun run lint:fix.
Rust-based formatter. Run via bun run format / format:check.
TS shape returned by parse workers and built up by language adapters. Header (relPath, fileRow, category, parseMs?) plus optional row arrays per category (TS / CSS / text). Subset that adapters populate is ParsedFilePayload.
Code that turns source bytes into structured rows. Three implementations: parser.ts (oxc), css-parser.ts (lightningcss), markers.ts (regex). Distinct from adapter — an adapter wires a parser to a set of file extensions.
A docs/plans/<feature-name>.md file tracking in-flight work. Created on commit; deleted when the feature ships per README § Rule 3.
A managed root-level file (CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md) with a <!-- codemap-pointer:begin --> / <!-- codemap-pointer:end --> section. Written by codemap agents init. See agents.md § Pointer files.
Any SQL run against .codemap.db — either a recipe (bundled SQL) or ad-hoc. Distinct from query-recipes.ts (the file that holds bundled recipe SQL strings).
See recipe.
A bundled SQL string in src/cli/query-recipes.ts, identified by id (e.g. fan-in, deprecated-symbols, files-hashes). Run via codemap query --recipe <id> (alias -r). Distinct from an ad-hoc query (which is any SQL string the agent composes itself).
A snapshot-style note under docs/research/ capturing a competitive scan or evaluation. Closed per README § Closing research — adopted items are slimmed to a "What shipped" appendix; rejected items keep a status header.
oxc-resolver, configured by src/resolver.ts. Maps import specifiers to absolute file paths using tsconfig aliases.
TS shape after resolveCodemapConfig() fills defaults and absolutifies paths. Stored in process-global runtime by initCodemap. Distinct from CodemapUserConfig (the user-facing input shape with optional fields).
docs/roadmap.md. Forward-looking only; shipped items are removed (see README § Rule 2). Holds the canonical Non-goals (v1) list.
One record in a SQLite table. Each table has a corresponding TS interface (FileRow, SymbolRow, …) so reads via db.query<RowType>(sql).all() are typed.
Conceptually, the structure of the SQLite database — every table, column, constraint, and index. Defined by DDL in src/db.ts. Versioned by SCHEMA_VERSION. Documented in architecture § Schema.
Integer constant in src/db.ts. Bumped whenever the DDL changes. createSchema() reads meta.schema_version and triggers a full rebuild on mismatch.
A .agents/skills/<name>/SKILL.md file with YAML frontmatter. Longer than a rule; describes a complete agent workflow. Distinct from a rule (shorter, normative).
SQLite per-table option enforcing column types at insert time. Every Codemap table uses STRICT.
Functions / consts / classes / interfaces / types / enums, plus class members (method, property, getter, setter). Class members carry parent_name. JSDoc tags in doc_comment power the deprecated-symbols and visibility-tags recipes; members is JSON for enums. See SymbolRow.
TS shape for one row of the symbols table.
Index mode that re-parses only the explicit file paths passed to --files. Skips git diff and the full glob. See targetedReindex in src/application/index-engine.ts.
The templates/agents/ directory shipped with the npm package. Source for codemap agents init, which copies (or symlinks, in interactive mode) the bundled rules and skills into the consumer's .agents/.
The Node-side glob implementation. Returns POSIX-separated paths regardless of OS — same as Bun.Glob and git. Why cmd-validate.ts normalizes its inputs to POSIX.
A small end-to-end vertical slice (see .cursor/rules/tracer-bullets.mdc). Used in PRs to validate the critical path before expanding.
Properties and method signatures on interfaces and object-literal types. symbol_name references the parent symbols.name. type is null when the parser can't reconstruct the annotation. See TypeMemberRow.
TS shape for one row of the type_members table.
A JSDoc tag controlling export visibility — @public, @internal, @private, @alpha, @beta, @deprecated. Stored in symbols.doc_comment. The visibility-tags and deprecated-symbols recipes filter on these.
Write-Ahead Log mode. Set by PRAGMA journal_mode = WAL on every openDb(). Why .codemap.db-wal and .codemap.db-shm files exist alongside .codemap.db. Allows concurrent readers during writes.
SQLite per-table option that stores data directly in the primary key B-tree, eliminating a rowid lookup indirection. Used on dependencies (composite PK) and meta (single-column TEXT PK).
Parallel parse workers in src/worker-pool.ts. Bun Worker on Bun, Node worker_threads on Node. Used during full rebuild only — incremental and targeted indexing run sequentially.