feat(config): validate user config with Zod; document in architecture

- Add zod dependency; codemapUserConfigSchema + parseCodemapUserConfig via strict object schema.
- Export codemapUserConfigSchema from the package entry.
- docs: User config section in architecture.md; index table + cross-cutting in docs/README.md;
  packaging.md notes zod; README links to User config anchor.
- Tests: adjust assertions for Zod error messages.

Author: SutuSebastian

README.md

@@ -16,8 +16,6 @@ bun add @stainless-code/codemap
 # or: npm install @stainless-code/codemap
 ```
 
-The package exposes a **`codemap`** binary, a **library** entry (`import` / `exports`), compiled **`dist/`**, and **`templates/agents`** for **`codemap agents init`** — see [docs/packaging.md](docs/packaging.md).
-
 **Engines:** Node **`^20.19.0 || >=22.12.0`** and/or Bun **`>=1.0.0`** — see `package.json` and [docs/packaging.md](docs/packaging.md).
 
 ---
@@ -56,7 +54,7 @@ codemap agents init --force
 
 **Environment / flags:** `--root` overrides **`CODEMAP_ROOT`** / **`CODEMAP_TEST_BENCH`**, then **`process.cwd()`**. Indexing a project outside this clone: [docs/benchmark.md § Indexing another project](docs/benchmark.md#indexing-another-project).
 
-**Configuration:** optional **`codemap.config.ts`** (default export object or async factory) or **`codemap.config.json`**. Shape: [codemap.config.example.json](codemap.config.example.json). When developing inside this repo you can use `defineConfig` from `@stainless-code/codemap` or `./src/config`. If you set **`include`**, it **replaces** the default glob list entirely.
+**Configuration:** optional **`codemap.config.ts`** (default export object or async factory) or **`codemap.config.json`**. Shape: [codemap.config.example.json](codemap.config.example.json). Runtime validation (**Zod**, strict keys) and API surface: [docs/architecture.md § User config](docs/architecture.md#user-config). When developing inside this repo you can use `defineConfig` from `@stainless-code/codemap` or `./src/config`. If you set **`include`**, it **replaces** the default glob list entirely.
 
 ---
 

bun.lock

@@ -4,12 +4,12 @@ Technical docs for **[@stainless-code/codemap](https://github.com/stainless-code
 
 | File                                 | Topic                                                                                                                                                                                                                          |
 | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| [architecture.md](./architecture.md) | Schema, layering, CLI, programmatic API, parsers, [Key Files](./architecture.md#key-files)                                                                                                                                     |
+| [architecture.md](./architecture.md) | Schema, layering, CLI, programmatic API, [**User config**](./architecture.md#user-config) (Zod), parsers, [Key Files](./architecture.md#key-files)                                                                             |
 | [benchmark.md](./benchmark.md)       | **[Indexing another project](./benchmark.md#indexing-another-project)** (`CODEMAP_*`, `.env`) · **[benchmark script](./benchmark.md#the-benchmark-script)** (`src/benchmark.ts`) · [`fixtures/minimal/`](../fixtures/minimal/) |
 | [packaging.md](./packaging.md)       | `dist/`, npm **`files`**, **engines**, **[Node vs Bun](./packaging.md#node-vs-bun)**, **[Releases](./packaging.md#releases)** (Changesets)                                                                                     |
 | [roadmap.md](./roadmap.md)           | Forward-looking backlog (not a `src/` inventory)                                                                                                                                                                               |
 | [why-codemap.md](./why-codemap.md)   | Why index + SQL for agents (speed, tokens, accuracy)                                                                                                                                                                           |
 
-**Cross-cutting:** SQLite, workers, include globs, and JSON config use Bun when available — **[packaging.md § Node vs Bun](./packaging.md#node-vs-bun)** (single table; don’t duplicate elsewhere).
+**Cross-cutting:** SQLite, workers, include globs, and **JSON config I/O** use Bun when available — **[packaging.md § Node vs Bun](./packaging.md#node-vs-bun)** (single table; don’t duplicate elsewhere). **Config shape / validation** (Zod, strict keys) lives only in **[architecture.md § User config](./architecture.md#user-config)**.
 
 **Conventions:** one topic per file; relative links; no symbol/file counts or source line numbers (use `codemap query` / `bun run dev query` after indexing). **This repo:** `bun run dev` → `bun src/index.ts`; **`bun run build`** → tsdown → `dist/`. **Contributors:** `bun run check`, JSDoc on public API — [.github/CONTRIBUTING.md](../.github/CONTRIBUTING.md).

docs/README.md

@@ -10,7 +10,7 @@ A local SQLite database (`.codemap.db`) indexes the project tree and stores stru
 
 **`src/sqlite-db.ts`:** Node uses **`better-sqlite3`**; Bun uses **`bun:sqlite`**. Same schema everywhere. **`better-sqlite3`** allows **one SQL statement per `prepare()`**; **`bun:sqlite`** accepts **multiple statements** in one `run()`. On Node, **`runSql()`** splits multi-statement strings on **`;`** and runs each fragment. Do **not** put **`;`** inside **`--` line comments** in **`db.ts`** DDL strings (naive split would break). Details: [packaging.md § Node vs Bun](./packaging.md#node-vs-bun).
 
-**`src/worker-pool.ts`:** Bun `Worker` or Node `worker_threads`. **`src/glob-sync.ts`:** Bun **`Glob`** or **`fast-glob`** for include patterns. **`src/config.ts`:** JSON user config via **`Bun.file`** on Bun, **`readFile` + `JSON.parse`** on Node. Full table: [packaging.md § Node vs Bun](./packaging.md#node-vs-bun).
+**`src/worker-pool.ts`:** Bun `Worker` or Node `worker_threads`. **`src/glob-sync.ts`:** Bun **`Glob`** or **`fast-glob`** for include patterns. **`src/config.ts`:** loads **`codemap.config.json`** / **`codemap.config.ts`** (JSON read path: **`Bun.file`** on Bun, **`readFile` + `JSON.parse`** on Node — [packaging.md § Node vs Bun](./packaging.md#node-vs-bun)), then validates with **Zod** (`codemapUserConfigSchema`). Details: [User config](#user-config).
 
 **Shipped artifact:** **`dist/`** — `package.json` **`bin`** and **`exports`** both point at **`dist/index.mjs`** ([packaging.md](./packaging.md)); tsdown also emits **lazy CLI chunks** (`cmd-index`, `cmd-query`, `cmd-agents`, …) loaded via **`import()`** from **`src/cli/main.ts`**.
 
@@ -111,6 +111,7 @@ A local SQLite database (`.codemap.db`) indexes the project tree and stores stru
 | `parsed-types.ts` | Shared `ParsedFile` shape for workers and adapters                                                                |
 | `agents-init.ts`  | `codemap agents init` — copies `templates/agents` → `.agents/`                                                    |
 | `benchmark.ts`    | SQL vs traditional timing script — see [benchmark.md § The benchmark script](./benchmark.md#the-benchmark-script) |
+| `config.ts`       | `codemap.config.*` load path, **Zod** user schema (`codemapUserConfigSchema`), `resolveCodemapConfig`             |
 
 ## CLI usage
 
@@ -142,14 +143,22 @@ When specific file paths are passed via `--files`, the indexer skips git diff, g
 
 ## Programmatic usage
 
-The npm package exports **`createCodemap`**, **`Codemap`** (`query`, `index`), **`runCodemapIndex`** (advanced), config helpers, **`CodemapDatabase`** (type), adapter types (`LanguageAdapter`, `getAdapterForExtension`, …), and **`ParsedFile`** — see **`src/api.ts`** / **`src/index.ts`** and **`dist/index.d.mts`**. Typical flow:
+The npm package exports **`createCodemap`**, **`Codemap`** (`query`, `index`), **`runCodemapIndex`** (advanced), **`codemapUserConfigSchema`**, **`parseCodemapUserConfig`**, **`defineConfig`**, **`CodemapDatabase`** (type), adapter types (`LanguageAdapter`, `getAdapterForExtension`, …), and **`ParsedFile`** — see **`src/api.ts`** / **`src/index.ts`** and **`dist/index.d.mts`**. Typical flow:
 
 1. **`await createCodemap({ root, configFile?, config? })`** — loads `codemap.config.*`, calls **`initCodemap`** and **`configureResolver`**.
 2. **`await cm.index({ mode, files?, quiet? })`** — same pipeline as the CLI (incremental / full / targeted).
 3. **`cm.query(sql)`** — read-only SQL against `.codemap.db` (opens the DB per call).
 
 **Constraint:** `initCodemap` is global to the process; only one active indexed project at a time.
 
+### User config
+
+Optional **`codemap.config.ts`** (default export: object or async factory) or **`codemap.config.json`** at the project root; **`--config`** points at either. Example shape: [`codemap.config.example.json`](../codemap.config.example.json).
+
+**Validation:** **`codemapUserConfigSchema`** ([Zod](https://zod.dev)) — strict object (unknown keys are rejected). **`defineConfig({ ... })`**, **`parseCodemapUserConfig`**, and **`resolveCodemapConfig`** (CLI and merged `createCodemap({ config })`) all go through the same schema. Invalid config throws **`TypeError`** with a short path/message list.
+
+**Exports:** `codemapUserConfigSchema`, `parseCodemapUserConfig`, `defineConfig`, and **`CodemapUserConfig`** (inferred type) from the package entry — see **`src/config.ts`** / **`dist/index.d.mts`**.
+
 ## Schema
 
 **Fingerprints:** incremental runs compare **`files.content_hash`** — SHA-256 hex of raw file bytes from [`src/hash.ts`](../src/hash.ts) (same on Node and Bun). Details in the **`files`** table below.

docs/architecture.md

@@ -11,7 +11,7 @@ How **@stainless-code/codemap** is built and published. Hub: [README.md](./READM
 
 Tarballs contain **`dist/`** + **`templates/`** only. **`bun run pack`**, then point the consumer at **`file:…/stainless-code-codemap-*.tgz`**, or use **`file:/path/to/repo`** after build, or **`bun link`**. If **`better-sqlite3`** fails in the consumer, **`npm rebuild better-sqlite3`** (native addon must match that Node).
 
-**Engines** (`package.json`): **Node** `^20.19.0 || >=22.12.0` (matches **`oxc-parser`**; **`better-sqlite3`** is prebuilt for current Node majors only). **Bun** `>=1.0.0`. **Native bindings:** `better-sqlite3`, `lightningcss`, `oxc-parser`, `oxc-resolver` (NAPI); **`fast-glob`** is JS-only.
+**Engines** (`package.json`): **Node** `^20.19.0 || >=22.12.0` (matches **`oxc-parser`**; **`better-sqlite3`** is prebuilt for current Node majors only). **Bun** `>=1.0.0`. **Native bindings:** `better-sqlite3`, `lightningcss`, `oxc-parser`, `oxc-resolver` (NAPI); **`fast-glob`** and **`zod`** are JS-only. **`zod`** validates `codemap.config.*` at runtime (**`codemapUserConfigSchema`** in **`src/config.ts`**); see [architecture.md § User config](./architecture.md#user-config).
 
 ## Node vs Bun
 

docs/packaging.md

@@ -67,7 +67,8 @@
     "fast-glob": "^3.3.3",
     "lightningcss": "^1.32.0",
     "oxc-parser": "^0.123.0",
-    "oxc-resolver": "^11.19.1"
+    "oxc-resolver": "^11.19.1",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.6.0",

package.json

@@ -5,11 +5,46 @@ import { join } from "node:path";
 
 import {
   DEFAULT_INCLUDE_PATTERNS,
+  defineConfig,
   loadUserConfig,
+  parseCodemapUserConfig,
   resolveCodemapConfig,
   type CodemapUserConfig,
 } from "./config";
 
+describe("parseCodemapUserConfig / defineConfig", () => {
+  it("accepts an empty object", () => {
+    expect(parseCodemapUserConfig({})).toEqual({});
+  });
+
+  it("rejects non-objects", () => {
+    expect(() => parseCodemapUserConfig(null)).toThrow(TypeError);
+    expect(() => parseCodemapUserConfig([])).toThrow(TypeError);
+    expect(() => parseCodemapUserConfig("x")).toThrow(TypeError);
+  });
+
+  it("rejects unknown keys", () => {
+    expect(() =>
+      parseCodemapUserConfig({ include: ["**/*.ts"], extra: 1 }),
+    ).toThrow(/Unrecognized key|extra/i);
+  });
+
+  it("rejects wrong array element types", () => {
+    expect(() =>
+      parseCodemapUserConfig({ include: ["**/*.ts", 1 as unknown as string] }),
+    ).toThrow(/include/);
+  });
+
+  it("defineConfig validates like parseCodemapUserConfig", () => {
+    expect(defineConfig({ databasePath: "db.sqlite" })).toEqual({
+      databasePath: "db.sqlite",
+    });
+    expect(() => defineConfig({ bad: true } as CodemapUserConfig)).toThrow(
+      /Unrecognized key|bad/i,
+    );
+  });
+});
+
 describe("resolveCodemapConfig", () => {
   let dir: string;
   beforeEach(() => {
@@ -99,4 +134,13 @@ describe("loadUserConfig", () => {
     const cfg = await loadUserConfig(dir, join(dir, "nope.json"));
     expect(cfg).toBeUndefined();
   });
+
+  it("invalid JSON config throws when resolved", async () => {
+    writeFileSync(
+      join(dir, "codemap.config.json"),
+      JSON.stringify({ include: [1, 2] }),
+    );
+    const cfg = await loadUserConfig(dir);
+    expect(() => resolveCodemapConfig(dir, cfg)).toThrow(/include/);
+  });
 });

src/config.test.ts

@@ -3,6 +3,8 @@ import { readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
+import { z } from "zod";
+
 async function readJsonFile(filePath: string): Promise<unknown> {
   if (typeof Bun !== "undefined") {
     return Bun.file(filePath).json();
@@ -43,22 +45,53 @@ export const DEFAULT_EXCLUDE_DIR_NAMES = [
 ] as const;
 
 /**
- * User configuration from `codemap.config.ts` / `.json`, CLI, or `createCodemap({ config })`.
+ * Zod schema for user config (`codemap.config.*`, `defineConfig`, API).
+ * Unknown keys are rejected (`.strict()`).
  */
-export interface CodemapUserConfig {
-  /** Project root. Defaults via CLI `--root` or `process.cwd()`. */
-  root?: string;
-  /** SQLite database path, relative to root or absolute. Default: `<root>/.codemap.db`. */
-  databasePath?: string;
-  /** Glob patterns relative to root; replaces {@link DEFAULT_INCLUDE_PATTERNS} when set. */
-  include?: string[];
-  /** Directory name segments to skip; replaces {@link DEFAULT_EXCLUDE_DIR_NAMES} when set. */
-  excludeDirNames?: string[];
-  /**
-   * Path to `tsconfig.json` for import alias resolution (oxc-resolver).
-   * Use `null` to disable. Default: `<root>/tsconfig.json` if the file exists.
-   */
-  tsconfigPath?: string | null;
+export const codemapUserConfigSchema = z
+  .object({
+    root: z
+      .string()
+      .optional()
+      .describe("Project root. Defaults via CLI `--root` or `process.cwd()`."),
+    databasePath: z
+      .string()
+      .optional()
+      .describe(
+        "SQLite database path, relative to root or absolute. Default: `<root>/.codemap.db`.",
+      ),
+    include: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "Glob patterns relative to root; replaces default include list when set.",
+      ),
+    excludeDirNames: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "Directory name segments to skip; replaces default exclude list when set.",
+      ),
+    tsconfigPath: z
+      .union([z.string(), z.null()])
+      .optional()
+      .describe(
+        "Path to `tsconfig.json` for import alias resolution. Use `null` to disable.",
+      ),
+  })
+  .strict();
+
+/** Inferred from {@link codemapUserConfigSchema}. */
+export type CodemapUserConfig = z.infer<typeof codemapUserConfigSchema>;
+
+function formatCodemapConfigError(error: z.ZodError): string {
+  return error.issues
+    .map((issue) => {
+      const path =
+        issue.path.length > 0 ? issue.path.map(String).join(".") : "(root)";
+      return `${path}: ${issue.message}`;
+    })
+    .join("; ");
 }
 
 /**
@@ -72,11 +105,26 @@ export interface ResolvedCodemapConfig {
   readonly tsconfigPath: string | null;
 }
 
+/**
+ * Runtime validation for {@link CodemapUserConfig} (from JSON, `defineConfig`, or API).
+ *
+ * @throws TypeError when the shape is invalid or unknown keys are present.
+ */
+export function parseCodemapUserConfig(config: unknown): CodemapUserConfig {
+  const result = codemapUserConfigSchema.safeParse(config);
+  if (!result.success) {
+    throw new TypeError(
+      `Codemap config: ${formatCodemapConfigError(result.error)}`,
+    );
+  }
+  return result.data;
+}
+
 /**
  * Helper for `export default defineConfig({ ... })` in `codemap.config.ts`.
  */
 export function defineConfig(config: CodemapUserConfig): CodemapUserConfig {
-  return config;
+  return parseCodemapUserConfig(config);
 }
 
 /**
@@ -86,23 +134,24 @@ export function resolveCodemapConfig(
   root: string,
   user: CodemapUserConfig | undefined,
 ): ResolvedCodemapConfig {
+  const parsed = user !== undefined ? parseCodemapUserConfig(user) : undefined;
   const absRoot = resolve(root);
-  const databasePath = user?.databasePath
-    ? resolve(absRoot, user.databasePath)
+  const databasePath = parsed?.databasePath
+    ? resolve(absRoot, parsed.databasePath)
     : join(absRoot, ".codemap.db");
-  const include = user?.include?.length
-    ? [...user.include]
+  const include = parsed?.include?.length
+    ? [...parsed.include]
     : [...DEFAULT_INCLUDE_PATTERNS];
   const excludeDirNames = new Set<string>(
-    user?.excludeDirNames?.length
-      ? user.excludeDirNames
+    parsed?.excludeDirNames?.length
+      ? parsed.excludeDirNames
       : DEFAULT_EXCLUDE_DIR_NAMES,
   );
   let tsconfigPath: string | null;
-  if (user?.tsconfigPath === null) {
+  if (parsed?.tsconfigPath === null) {
     tsconfigPath = null;
-  } else if (user?.tsconfigPath) {
-    tsconfigPath = resolve(absRoot, user.tsconfigPath);
+  } else if (parsed?.tsconfigPath) {
+    tsconfigPath = resolve(absRoot, parsed.tsconfigPath);
   } else {
     const d = join(absRoot, "tsconfig.json");
     tsconfigPath = existsSync(d) ? d : null;

src/config.ts

@@ -11,7 +11,9 @@ export type {
   ParseContext,
 } from "./adapters/types";
 export {
+  codemapUserConfigSchema,
   defineConfig,
+  parseCodemapUserConfig,
   type CodemapUserConfig,
   type ResolvedCodemapConfig,
 } from "./config";