@stainless-code/codemap 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @stainless-code/codemap
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release (**0.1.0**): structural SQLite index, CLI (`codemap`, `query`), programmatic API, Zod-validated `codemap.config`, Bun and Node support.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stainless-code contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# Codemap
+
+**Query your codebase.** Codemap builds a **local SQLite index** of structural metadata (symbols, imports, exports, components, dependencies, CSS tokens, markers, and more) so **AI agents and tools** can answer “where / what / who” questions with **SQL** instead of scanning the whole tree.
+
+- **Not** full-text search or grep on arbitrary strings — use those when you need raw file-body search.
+- **Is** a fast, token-efficient way to navigate **structure**: definitions, imports, dependency direction, components, and other extracted facts.
+
+**Documentation:** [docs/README.md](docs/README.md) is the index for technical docs (architecture, packaging, roadmap, benchmarks). **AI / editor agents:** [`.agents/rules/`](.agents/rules/), [`.agents/skills/codemap/SKILL.md`](.agents/skills/codemap/SKILL.md); Cursor uses `.cursor/` symlinks — [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md).
+
+---
+
+## Install
+
+```bash
+bun add @stainless-code/codemap
+# or: npm install @stainless-code/codemap
+```
+
+**Engines:** Node **`^20.19.0 || >=22.12.0`** and/or Bun **`>=1.0.0`** — see `package.json` and [docs/packaging.md](docs/packaging.md).
+
+---
+
+## CLI
+
+- **Installed package:** `codemap`, `bunx @stainless-code/codemap`, or `node node_modules/@stainless-code/codemap/dist/index.mjs`
+- **This repo (dev):** `bun src/index.ts` (same flags)
+
+```bash
+# Index project root (optional codemap.config.ts / codemap.config.json)
+codemap
+
+# Version (also: codemap --version, codemap -V)
+codemap version
+
+# Full rebuild
+codemap --full
+
+# SQL against the index (after at least one index run)
+codemap query "SELECT name, file_path FROM symbols LIMIT 10"
+
+# Another project
+codemap --root /path/to/repo --full
+
+# Explicit config
+codemap --config /path/to/codemap.config.json --full
+
+# Re-index only given paths (relative to project root)
+codemap --files src/a.ts src/b.tsx
+
+# Scaffold .agents/ rules and skills from bundled templates (see CONTRIBUTING)
+codemap agents init
+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). 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.
+
+---
+
+## Programmatic API (ESM)
+
+```ts
+import { createCodemap } from "@stainless-code/codemap";
+
+const cm = await createCodemap({ root: "/path/to/repo" });
+await cm.index({ mode: "incremental" });
+await cm.index({ mode: "full" });
+await cm.index({ mode: "files", files: ["src/a.ts"] });
+await cm.index({ quiet: true });
+
+const rows = cm.query("SELECT name FROM symbols LIMIT 5");
+```
+
+`createCodemap` configures a process-global runtime (`initCodemap`); only **one active project per process** is supported. Advanced: `runCodemapIndex` for an open DB handle. **Module layout:** [docs/architecture.md § Layering](docs/architecture.md#layering).
+
+---
+
+## Development
+
+Tooling: **Oxfmt**, **Oxlint**, **tsgo** (`@typescript/native-preview`).
+
+| Command                              | Purpose                                                          |
+| ------------------------------------ | ---------------------------------------------------------------- |
+| `bun run dev`                        | Run the CLI from source (same as `bun src/index.ts`)             |
+| `bun run check`                      | Build, format check, lint, tests, typecheck — run before pushing |
+| `bun run fix`                        | Apply lint fixes, then format                                    |
+| `bun run test` / `bun run typecheck` | Focused checks                                                   |
+
+```bash
+bun install
+bun run check    # build + format:check + lint + test + typecheck
+bun run fix      # oxlint --fix, then oxfmt
+```
+
+**Readability & DX:** Prefer clear names and small functions; keep **JSDoc** on public exports. [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md) has contributor workflow and conventions.
+
+---
+
+## Benchmark
+
+```bash
+CODEMAP_ROOT=/path/to/indexed-repo bun src/benchmark.ts
+```
+
+Details: [docs/benchmark.md](docs/benchmark.md).
+
+---
+
+## Organization
+
+Developed under **[stainless-code](https://github.com/stainless-code)** on GitHub.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/builtin-CQ_e97VT.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+import { i as extractMarkers, r as extractCssData, t as extractFileData } from "./parser-VtP0EJiw.mjs";
+//#region src/adapters/builtin.ts
+const TS_JS_EXT = new Set([
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs"
+]);
+function parseTsJs(ctx) {
+	const data = extractFileData(ctx.absPath, ctx.source, ctx.relPath);
+	return {
+		category: "ts",
+		symbols: data.symbols,
+		imports: data.imports,
+		exports: data.exports,
+		components: data.components,
+		markers: data.markers
+	};
+}
+function parseCss(ctx) {
+	const cssData = extractCssData(ctx.absPath, ctx.source, ctx.relPath);
+	return {
+		category: "css",
+		cssVariables: cssData.variables,
+		cssClasses: cssData.classes,
+		cssKeyframes: cssData.keyframes,
+		markers: cssData.markers,
+		cssImportSources: cssData.importSources
+	};
+}
+function parseText(ctx) {
+	return {
+		category: "text",
+		markers: extractMarkers(ctx.source, ctx.relPath)
+	};
+}
+/** Built-in adapters (oxc TS/JS, Lightning CSS, text/markers). Order matters for the first match. */
+const BUILTIN_ADAPTERS = [
+	{
+		id: "builtin.ts-js",
+		extensions: [...TS_JS_EXT],
+		parse: parseTsJs
+	},
+	{
+		id: "builtin.css",
+		extensions: [".css"],
+		parse: parseCss
+	},
+	{
+		id: "builtin.text",
+		extensions: [
+			".md",
+			".mdx",
+			".mdc",
+			".yml",
+			".yaml",
+			".txt",
+			".json",
+			".sh"
+		],
+		parse: parseText
+	}
+];
+function getAdapterForExtension(ext, adapters = BUILTIN_ADAPTERS) {
+	for (const a of adapters) if (a.extensions.includes(ext)) return a;
+}
+//#endregion
+export { getAdapterForExtension as n, BUILTIN_ADAPTERS as t };

package/dist/cmd-agents-BJPx1vGG.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { cpSync, existsSync, mkdirSync } from "node:fs";
+//#region src/agents-init.ts
+/**
+* Directory containing `rules/` and `skills/` (next to `dist/` in published packages).
+*/
+function resolveAgentsTemplateDir() {
+	return join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "agents");
+}
+/**
+* Copy bundled rules and skills into `<projectRoot>/.agents/`.
+* @returns `false` when `.agents/` exists and `--force` was not used.
+*/
+function runAgentsInit(options) {
+	const templateRoot = resolveAgentsTemplateDir();
+	if (!existsSync(templateRoot)) throw new Error(`Codemap: agent templates not found at ${templateRoot} (expected npm package layout: templates/agents next to dist/)`);
+	const destRoot = join(options.projectRoot, ".agents");
+	if (existsSync(destRoot) && !options.force) {
+		console.error(`  .agents/ already exists at ${destRoot}. Re-run with --force to overwrite, or remove the directory.`);
+		return false;
+	}
+	mkdirSync(destRoot, { recursive: true });
+	cpSync(join(templateRoot, "rules"), join(destRoot, "rules"), { recursive: true });
+	cpSync(join(templateRoot, "skills"), join(destRoot, "skills"), { recursive: true });
+	console.log(`  Wrote agent templates to ${destRoot}`);
+	console.log(`  Symlink into .cursor/ if needed — see https://github.com/stainless-code/codemap/blob/main/.github/CONTRIBUTING.md`);
+	return true;
+}
+//#endregion
+//#region src/cli/cmd-agents.ts
+function runAgentsInitCmd(opts) {
+	return runAgentsInit(opts);
+}
+//#endregion
+export { runAgentsInitCmd };

package/dist/cmd-index-oyoHr0c4.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { C as getTsconfigPath, S as getProjectRoot, a as resolveCodemapConfig, g as closeDb, h as configureResolver, o as VALID_EXTENSIONS, r as loadUserConfig, w as initCodemap, y as openDb } from "./config-CsPgQWSX.mjs";
+import { t as runCodemapIndex } from "./run-index-DQD5afqQ.mjs";
+import { extname } from "node:path";
+//#region src/cli/cmd-index.ts
+async function runIndexCmd(opts) {
+	const user = await loadUserConfig(opts.root, opts.configFile);
+	initCodemap(resolveCodemapConfig(opts.root, user));
+	configureResolver(getProjectRoot(), getTsconfigPath());
+	const args = opts.rest;
+	const db = openDb();
+	try {
+		if (args[0] === "--files" && args.length > 1) {
+			const targetFiles = args.slice(1).filter((f) => {
+				const ext = extname(f);
+				if (!VALID_EXTENSIONS.has(ext)) {
+					console.warn(`  Skipping ${f}: unsupported extension "${ext}"`);
+					return false;
+				}
+				return true;
+			});
+			if (targetFiles.length > 0) await runCodemapIndex(db, {
+				mode: "files",
+				files: targetFiles
+			});
+		} else await runCodemapIndex(db, { mode: args.includes("--full") ? "full" : "incremental" });
+	} finally {
+		closeDb(db);
+	}
+}
+//#endregion
+export { runIndexCmd };

package/dist/cmd-query-D3zXZu7K.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import { C as getTsconfigPath, S as getProjectRoot, a as resolveCodemapConfig, f as printQueryResult, h as configureResolver, r as loadUserConfig, w as initCodemap } from "./config-CsPgQWSX.mjs";
+//#region src/cli/cmd-query.ts
+async function runQueryCmd(opts) {
+	const user = await loadUserConfig(opts.root, opts.configFile);
+	initCodemap(resolveCodemapConfig(opts.root, user));
+	configureResolver(getProjectRoot(), getTsconfigPath());
+	printQueryResult(opts.sql);
+}
+//#endregion
+export { runQueryCmd };