Skip to content
Codemap
Esc
↑↓navigate↵open⌘Jpreview
On this page

Modules

Classes

Codemap

Handle for SQL queries and index runs after createCodemap.

Each query opens the database for that call; index manages its own open/close lifecycle.

Constructors

Constructor
new Codemap(): Codemap;
Returns

Codemap

Accessors

root
Get Signature
get root(): string;

Absolute project root (from resolved config).

Returns

string

databasePath
Get Signature
get databasePath(): string;

Absolute path to the SQLite index file (e.g. .codemap/index.db).

Returns

string

Methods

query()
query(sql): unknown[];

Run a read-only SQL statement against the index (same semantics as the CLI query subcommand).

Parameters
Parameter Type Description
sql string Valid SQLite for the Codemap schema.
Returns

unknown[]

Result rows from better-sqlite3-style .all().

Throws

On invalid SQL or database errors (same as better-sqlite3).

index()
index(options?): Promise<IndexResult>;

Refresh the index: incremental (git-based), full, or targeted file list.

Parameters
Parameter Type Description
options IndexOptions See RunIndexOptions.
Returns

Promise<IndexResult>

Interfaces

ParseContext

Input for a LanguageAdapter. Paths are absolute / project-relative as noted.

Properties

Property Type Description
absPath string Absolute path on disk (for parsers that need a real filename).
relPath string Path relative to project root (stored in DB rows).
source string -

LanguageAdapter

Pluggable extractor for a set of file extensions.

Remarks

Built-ins: BUILTIN_ADAPTERS. Future optional packages can register additional adapters (or replace built-ins) once a public registration API exists.

Properties

Property Modifier Type Description
id readonly string -
extensions readonly readonly string[] Extensions with leading dot, e.g. .ts, .tsx.

Methods

parse()
parse(ctx): ParsedFilePayload;
Parameters
Parameter Type
ctx ParseContext
Returns

ParsedFilePayload

CodemapInitOptions

Options for createCodemap.

Properties

Property Type Description
root? string Project root. When omitted: CODEMAP_ROOT or CODEMAP_TEST_BENCH, then process.cwd().
configFile? string Explicit path to .codemap/config.{ts,js,json} (same as CLI --config).
config? object Inline overrides merged on top of the file-based config from the project root.
config.root? string -
config.databasePath? string -
config.include? string[] -
config.excludeDirNames? string[] -
config.tsconfigPath? string | null -
config.fts5? boolean -
config.recipeRecency? boolean -
config.churn? object -
config.churn.halfLifeDays? number -
config.churn.since? string -
config.churn.file? string -
config.synthesis? object -
config.synthesis.heuristicCalls? boolean -
config.apply? object -
config.apply.autoApplyRecipes? string[] -
config.boundaries? object[] -

IndexOptions

Properties

Property Type Description
mode? IndexMode Defaults to incremental.
files? string[] Paths relative to the project root; used only when mode === "files". All paths are forwarded as-is; non-standard extensions are indexed as text.
quiet? boolean Suppresses progress logs; parse failures may still be printed. Defaults to false.
performance? boolean Emits a per-phase timing breakdown and the top-10 slowest files (full rebuild only). Off by default — wired by the CLI’s --performance flag.
commit? string Explicit sha for meta.last_indexed_commit — skips git rev-parse HEAD. Audit-cache reindex uses this: the cache dir has no .git so the shell-out would emit fatal: not a git repository and stamp an empty string.

IndexTableStats

Row counts per table after an index run (mirrors CLI summary output). Keys use the SQLite table names (snake_case: type_members, css_vars, css_classes, css_keyframes) so the same identifiers work directly in SELECT … FROM <key> queries.

Extends

  • Record<string, number>

Indexable

[key: string]: number

Properties

Property Type
files number
symbols number
imports number
exports number
components number
dependencies number
markers number
type_members number
type_heritage number
calls number
css_vars number
css_classes number
css_keyframes number
scopes number
references number
bindings number
import_specifiers number
function_params number
runtime_markers number
test_suites number
re_export_chains number
module_cycles number
dynamic_imports number
file_metrics number
file_churn number

IndexRunStats

Per-run counters; see IndexResult for the public shape returned from indexing APIs.

Properties

Property Type Description
indexed number Number of files written or re-indexed in this run.
skipped number Files whose content_hash matched the index (no work done).
elapsedMs number Wall-clock time for the indexing pipeline, in milliseconds.
fullRebuild boolean true if this run dropped and rebuilt all tables; false for incremental / targeted.
stats IndexTableStats Row counts per table after the run completed.
performance? IndexPerformanceReport Set only when --performance (or RunIndexOptions.performance) is on.

IndexResult

Outcome of Codemap#index or runCodemapIndex (CLI and programmatic index runs).

Properties

Property Type Description
mode "files" | "full" | "incremental" How the index was updated.
indexed number Files written or re-indexed in this run.
skipped number Files skipped (unchanged hash).
elapsedMs number Wall-clock time for the indexing pipeline, in milliseconds.
stats IndexTableStats Row counts per table after the run completed.
idle? boolean Set when no file bodies were indexed (already fresh, empty files list, or deletions-only pass).

ResolvedCodemapConfig

Fully resolved config (defaults filled, paths absolute) — stored in the process-global runtime after init and read for indexing / query / serve.

Properties

Property Modifier Type Description
root readonly string Absolute project root (from CLI --root, env, or process.cwd()).
stateDir readonly string Absolute path to the codemap state directory (<root>/.codemap by default). Overridable via --state-dir <path> or CODEMAP_STATE_DIR. Holds every codemap-managed file: index.db (+ WAL/SHM), audit-cache/, recipes/, config.{ts,js,json}, .gitignore (self-managed).
databasePath readonly string Absolute path to the SQLite database file (default <stateDir>/index.db).
include readonly readonly string[] Glob patterns relative to root; either user-supplied or DEFAULT_INCLUDE_PATTERNS.
excludeDirNames readonly ReadonlySet<string> Directory names (any segment) to skip — either user-supplied or DEFAULT_EXCLUDE_DIR_NAMES.
tsconfigPath readonly string | null Absolute path to tsconfig.json for alias resolution, or null to disable.
fts5 readonly boolean FTS5 full-text indexing toggle. true populates the source_fts virtual table at index time; false (default) leaves it empty. Resolved from .codemap/config.ts fts5 plus the --with-fts CLI flag; CLI wins.
recipeRecency readonly boolean Recipe-recency tracking toggle. true (default) populates the recipe_recency table on every successful recipe run and inlines last_run_at / run_count on --recipes-json reads. false short-circuits every write — no rows ever land. Local-only — no upload primitive.
boundaries readonly readonly object[] Reconciled into the boundary_rules table on every index pass. The bundled boundary-violations recipe joins this against dependencies via SQLite GLOB.
churn readonly object Git churn ingest tuning for file_churn.
churn.halfLifeDays readonly number -
churn.since readonly string | null When set, only commits after this git ref are counted.
churn.file readonly string | null Optional JSON churn import when git is unavailable.
synthesis readonly object When heuristicCalls is true, runs callback-synthesis after resolveCalls.
synthesis.heuristicCalls readonly boolean -
applyAutoApplyRecipes readonly readonly string[] | undefined When non-empty, codemap apply --yes <recipe> requires the recipe id to appear here unless --force is passed.

ParsedFile

One indexed file’s extracted data; workers return arrays of these and LanguageAdapters populate a ParsedFilePayload subset.

Properties

Property Type Description
relPath string Path relative to project root.
error? boolean true when the file couldn’t be read from disk (distinct from parseError).
parseError? string Parser threw but the file was read; the files row is still inserted.
fileRow FileRow -
category "ts" | "css" | "text" Extraction path: ts (oxc), css (lightningcss), or text (markers-only).
parseMs? number Worker-side parse wall-clock; surfaced by --performance.
symbols? SymbolRow[] -
imports? ImportRow[] -
importSpecifiers? ImportSpecifierRow[] -
exports? ExportRow[] -
components? ComponentRow[] -
markers? MarkerRow[] -
suppressions? SuppressionRow[] -
typeMembers? TypeMemberRow[] -
typeHeritage? TypeHeritageRow[] -
calls? CallRow[] -
scopes? ScopeRow[] -
references? ReferenceRow[] -
fileMetrics? FileMetricsRow -
functionParams? FunctionParamRow[] -
runtimeMarkers? RuntimeMarkerRow[] -
testSuites? TestSuiteRow[] -
dynamicImports? DynamicImportRow[] -
jsxElements? ParsedJsxElement[] -
jsxAttributes? ParsedJsxAttribute[] -
asyncCalls? ParsedAsyncCall[] -
tryCatchRows? ParsedTryCatch[] -
decorators? ParsedDecorator[] -
jsdocTags? ParsedJsdocTag[] -
hasSideEffects? number -
cssVariables? CssVariableRow[] CSS-only fields (populated when category === "css").
cssClasses? CssClassRow[] -
cssKeyframes? CssKeyframeRow[] -
cssImportSources? string[] Raw @import strings; main thread converts these to imports rows.
content? string Verbatim file source — populated by the worker only when WorkerInput.fts5Enabled; indexer writes to source_fts. Default-OFF keeps worker→main serialization cost zero.

CodemapDatabase

Minimal SQLite surface used by Codemap — implemented for bun:sqlite and better-sqlite3 (sync APIs, transactions, PRAGMAs).

Methods

run()
run(sql, params?): void;
Parameters
Parameter Type
sql string
params? BindValues
Returns

void

query()
query<T>(sql): object;
Type Parameters
Type Parameter
T
Parameters
Parameter Type
sql string
Returns

object

Name Type
get() (…params) => T | undefined
all() (…params) => T[]
transaction()
transaction<T>(fn): () => T;

Returns a function that runs the transaction when invoked (Bun / better-sqlite3 semantics).

Type Parameters
Type Parameter
T
Parameters
Parameter Type
fn () => T
Returns

() => T

close()
close(): void;
Returns

void

Type Aliases

ParsedFilePayload

type ParsedFilePayload = Pick<ParsedFile, 
  | "category"
  | "symbols"
  | "imports"
  | "exports"
  | "components"
  | "markers"
  | "suppressions"
  | "typeMembers"
  | "typeHeritage"
  | "calls"
  | "importSpecifiers"
  | "scopes"
  | "references"
  | "fileMetrics"
  | "functionParams"
  | "runtimeMarkers"
  | "testSuites"
  | "dynamicImports"
  | "hasSideEffects"
  | "jsxElements"
  | "jsxAttributes"
  | "asyncCalls"
  | "tryCatchRows"
  | "decorators"
  | "jsdocTags"
  | "cssVariables"
  | "cssClasses"
  | "cssKeyframes"
  | "cssImportSources"
| "parseError">;

Partial parse result merged into ParsedFile after fileRow is built. Set parseError when extraction fails but the file should still be indexed.

CodemapUserConfig

type CodemapUserConfig = z.infer<typeof codemapUserConfigSchema>;

Inferred from codemapUserConfigSchema.

Variables

BUILTIN_ADAPTERS

const BUILTIN_ADAPTERS: readonly LanguageAdapter[];

Built-in adapters (oxc TS/JS, Lightning CSS, text/markers). Order matters for the first match.

codemapUserConfigSchema

const codemapUserConfigSchema: ZodObject<{
  root: ZodOptional<ZodString>;
  databasePath: ZodOptional<ZodString>;
  include: ZodOptional<ZodArray<ZodString>>;
  excludeDirNames: ZodOptional<ZodArray<ZodString>>;
  tsconfigPath: ZodOptional<ZodUnion<readonly [ZodString, ZodNull]>>;
  fts5: ZodOptional<ZodBoolean>;
  recipeRecency: ZodOptional<ZodBoolean>;
  churn: ZodOptional<ZodObject<{
     halfLifeDays: ZodOptional<ZodNumber>;
     since: ZodOptional<ZodString>;
     file: ZodOptional<ZodString>;
  }, $strict>>;
  synthesis: ZodOptional<ZodObject<{
     heuristicCalls: ZodOptional<ZodBoolean>;
  }, $strict>>;
  apply: ZodOptional<ZodObject<{
     autoApplyRecipes: ZodOptional<ZodArray<ZodString>>;
  }, $strict>>;
  boundaries: ZodOptional<ZodArray<ZodObject<{
     name: ZodString;
     from_glob: ZodString;
     to_glob: ZodString;
     action: ZodOptional<ZodEnum<{
        allow: "allow";
        deny: "deny";
     }>>;
  }, $strict>>>;
}, $strict>;

Zod schema for user config (<state-dir>/config.{ts,js,json}, defineConfig, API). Unknown keys are rejected (.strict()).

CODEMAP_VERSION

const CODEMAP_VERSION: string = packageJson.version;

Package version from package.json (inlined at build time).

Functions

getAdapterForExtension()

function getAdapterForExtension(ext, adapters?): 
  | LanguageAdapter
  | undefined;

First-match adapter lookup by file extension. ext must include the leading dot (.tsx); returns undefined when nothing matches (the indexer then falls back to markers-only text).

Parameters

Parameter Type Default value
ext string undefined
adapters readonly LanguageAdapter[] BUILTIN_ADAPTERS

Returns

| LanguageAdapter | undefined

createCodemap()

function createCodemap(options?): Promise<Codemap>;

Programmatic entry point: loads config, initializes the process runtime, configures the import resolver, and returns a Codemap handle.

Parameters

Parameter Type
options CodemapInitOptions

Returns

Promise<Codemap>

Remarks

One project root per process: a second createCodemap() with a different root throws. Re-initializing the same root is allowed. Audit --base worktree reindex is the only production path that may temporarily switch roots.

Invalid project config (unknown keys, wrong types) throws at load time via the same schema as parseCodemapUserConfig.

runCodemapIndex()

function runCodemapIndex(db, options?): Promise<IndexResult>;

Parameters

Parameter Type
db CodemapDatabase
options IndexOptions

Returns

Promise<IndexResult>

parseCodemapUserConfig()

function parseCodemapUserConfig(config): object;

Runtime validation for CodemapUserConfig (from JSON, defineConfig, or API).

Parameters

Parameter Type
config unknown

Returns

object

Name Type
root? string
databasePath? string
include? string[]
excludeDirNames? string[]
tsconfigPath? string | null
fts5? boolean
recipeRecency? boolean
churn? object
churn.halfLifeDays? number
churn.since? string
churn.file? string
synthesis? object
synthesis.heuristicCalls? boolean
apply? object
apply.autoApplyRecipes? string[]
boundaries? object[]

Throws

TypeError when the shape is invalid or unknown keys are present.

defineConfig()

function defineConfig(config): object;

Helper for export default defineConfig({ ... }) in .codemap/config.ts.

Parameters

Parameter Type
config { root?: string; databasePath?: string; include?: string[]; excludeDirNames?: string[]; tsconfigPath?: string | null; fts5?: boolean; recipeRecency?: boolean; churn?: { halfLifeDays?: number; since?: string; file?: string; }; synthesis?: { heuristicCalls?: boolean; }; apply?: { autoApplyRecipes?: string[]; }; boundaries?: object[]; }
config.root? string
config.databasePath? string
config.include? string[]
config.excludeDirNames? string[]
config.tsconfigPath? string | null
config.fts5? boolean
config.recipeRecency? boolean
config.churn? { halfLifeDays?: number; since?: string; file?: string; }
config.churn.halfLifeDays? number
config.churn.since? string
config.churn.file? string
config.synthesis? { heuristicCalls?: boolean; }
config.synthesis.heuristicCalls? boolean
config.apply? { autoApplyRecipes?: string[]; }
config.apply.autoApplyRecipes? string[]
config.boundaries? object[]

Returns

object

Name Type
root? string
databasePath? string
include? string[]
excludeDirNames? string[]
tsconfigPath? string | null
fts5? boolean
recipeRecency? boolean
churn? object
churn.halfLifeDays? number
churn.since? string
churn.file? string
synthesis? object
synthesis.heuristicCalls? boolean
apply? object
apply.autoApplyRecipes? string[]
boundaries? object[]

Was this page helpful?