@stainless-code/codemap 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,198 @@
+
+import { n as CodemapDatabase, t as ParsedFile } from "./parsed-types-udxNyD9e.mjs";
+import { z } from "zod";
+
+//#region src/application/types.d.ts
+/**
+ * Row counts per table after an index run (mirrors CLI summary output).
+ */
+interface IndexTableStats extends Record<string, number> {
+  files: number;
+  symbols: number;
+  imports: number;
+  exports: number;
+  components: number;
+  dependencies: number;
+  markers: number;
+  css_vars: number;
+  css_classes: number;
+  css_keyframes: number;
+}
+/** Per-run counters; see {@link IndexResult} for the public shape returned from indexing APIs. */
+interface IndexRunStats {
+  indexed: number;
+  skipped: number;
+  elapsedMs: number;
+  fullRebuild: boolean;
+  stats: IndexTableStats;
+}
+/**
+ * Outcome of `Codemap#index` or `runCodemapIndex` (CLI and programmatic index runs).
+ */
+interface IndexResult {
+  /** How the index was updated. */
+  mode: "full" | "incremental" | "files";
+  /** Files written or re-indexed in this run. */
+  indexed: number;
+  /** Files skipped (unchanged hash). */
+  skipped: number;
+  elapsedMs: number;
+  stats: IndexTableStats;
+  /**
+   * Set when no file bodies were indexed (already fresh, empty `files` list, or deletions-only pass).
+   */
+  idle?: boolean;
+}
+//#endregion
+//#region src/application/run-index.d.ts
+/**
+ * - `incremental` — git-based diff vs last indexed commit (default).
+ * - `full` — re-glob and re-index everything.
+ * - `files` — only `options.files` (paths relative to project root).
+ */
+type IndexMode = "incremental" | "full" | "files";
+interface RunIndexOptions {
+  /** Defaults to `incremental`. */
+  mode?: IndexMode;
+  /**
+   * Paths relative to the project root; used only when `mode === "files"`.
+   * Non-indexable extensions are filtered out.
+   */
+  files?: string[];
+  /** Suppresses progress logs; parse failures may still be printed. Defaults to `false`. */
+  quiet?: boolean;
+}
+/**
+ * Core indexing pipeline (CLI and `Codemap#index`).
+ *
+ * @param db - Open database; caller owns the connection lifecycle.
+ * @param options - Index mode, optional targeted paths, and logging.
+ * @returns Row counts and timing; see {@link IndexResult}.
+ *
+ * @remarks
+ * Call `initCodemap()` and `configureResolver()` for this project before invoking (same as CLI bootstrap).
+ */
+declare function runCodemapIndex(db: CodemapDatabase, options?: RunIndexOptions): Promise<IndexResult>;
+//#endregion
+//#region src/config.d.ts
+/**
+ * Zod schema for user config (`codemap.config.*`, `defineConfig`, API).
+ * Unknown keys are rejected (`.strict()`).
+ */
+declare const codemapUserConfigSchema: z.ZodObject<{
+  root: z.ZodOptional<z.ZodString>;
+  databasePath: z.ZodOptional<z.ZodString>;
+  include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  excludeDirNames: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  tsconfigPath: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+}, z.core.$strict>;
+/** Inferred from {@link codemapUserConfigSchema}. */
+type CodemapUserConfig = z.infer<typeof codemapUserConfigSchema>;
+/**
+ * Fully resolved configuration after {@link resolveCodemapConfig}.
+ */
+interface ResolvedCodemapConfig {
+  readonly root: string;
+  readonly databasePath: string;
+  readonly include: readonly string[];
+  readonly excludeDirNames: ReadonlySet<string>;
+  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.
+ */
+declare function parseCodemapUserConfig(config: unknown): CodemapUserConfig;
+/**
+ * Helper for `export default defineConfig({ ... })` in `codemap.config.ts`.
+ */
+declare function defineConfig(config: CodemapUserConfig): CodemapUserConfig;
+//#endregion
+//#region src/api.d.ts
+/**
+ * Options for {@link createCodemap}.
+ *
+ * @property root - Project root. When omitted: `CODEMAP_ROOT` or `CODEMAP_TEST_BENCH`, then `process.cwd()`.
+ * @property configFile - Explicit path to `codemap.config.ts` or `codemap.config.json` (same as CLI `--config`).
+ * @property config - Inline overrides merged on top of the file-based config from the project root.
+ */
+interface CodemapInitOptions {
+  root?: string;
+  configFile?: string;
+  config?: CodemapUserConfig;
+}
+/**
+ * Programmatic entry point: loads config, calls {@link initCodemap}, configures the import resolver,
+ * and returns a {@link Codemap} handle.
+ *
+ * @remarks
+ * Only one Codemap project per process: `initCodemap` is global; the last `createCodemap()` wins.
+ */
+declare function createCodemap(options?: CodemapInitOptions): Promise<Codemap>;
+/**
+ * Handle for SQL queries and index runs after {@link createCodemap}.
+ *
+ * Each {@link query} opens the database for that call; {@link index} manages its own open/close lifecycle.
+ */
+declare class Codemap {
+  /** Absolute project root (from resolved config). */
+  get root(): string;
+  /** Absolute path to the SQLite index file (e.g. `.codemap.db`). */
+  get databasePath(): string;
+  /**
+   * Run a read-only SQL statement against the index (same semantics as the CLI `query` subcommand).
+   *
+   * @param sql - Valid SQLite for the Codemap schema.
+   * @returns Result rows from `better-sqlite3`-style `.all()`.
+   * @throws On invalid SQL or database errors (same as `better-sqlite3`).
+   */
+  query(sql: string): unknown[];
+  /**
+   * Refresh the index: incremental (git-based), full, or targeted file list.
+   *
+   * @param options - See {@link RunIndexOptions}.
+   */
+  index(options?: RunIndexOptions): Promise<IndexResult>;
+}
+//#endregion
+//#region src/adapters/types.d.ts
+/**
+ * Input for a {@link LanguageAdapter}. Paths are absolute / project-relative as noted.
+ */
+interface ParseContext {
+  /** Absolute path on disk (for parsers that need a real `filename`). */
+  absPath: string;
+  /** Path relative to project root (stored in DB rows). */
+  relPath: string;
+  source: string;
+}
+/**
+ * Partial parse result merged into {@link ParsedFile} after `fileRow` is built.
+ * Set `parseError` when extraction fails but the file should still be indexed.
+ */
+type ParsedFilePayload = Pick<ParsedFile, "category" | "symbols" | "imports" | "exports" | "components" | "markers" | "cssVariables" | "cssClasses" | "cssKeyframes" | "cssImportSources" | "parseError">;
+/**
+ * Pluggable extractor for a set of file extensions.
+ *
+ * @remarks
+ * Built-in adapters live in {@link ./builtin.ts}. Future optional packages can register
+ * additional adapters (or replace built-ins) once a public registration API exists.
+ */
+interface LanguageAdapter {
+  readonly id: string;
+  /** Extensions with leading dot, e.g. `.ts`, `.tsx`. */
+  readonly extensions: readonly string[];
+  parse(ctx: ParseContext): ParsedFilePayload;
+}
+//#endregion
+//#region src/adapters/builtin.d.ts
+/** Built-in adapters (oxc TS/JS, Lightning CSS, text/markers). Order matters for the first match. */
+declare const BUILTIN_ADAPTERS: readonly LanguageAdapter[];
+declare function getAdapterForExtension(ext: string, adapters?: readonly LanguageAdapter[]): LanguageAdapter | undefined;
+//#endregion
+//#region src/version.d.ts
+/** Package version from `package.json` (inlined at build time). */
+declare const CODEMAP_VERSION: string;
+//#endregion
+export { BUILTIN_ADAPTERS, CODEMAP_VERSION, Codemap, type CodemapDatabase, CodemapInitOptions, type CodemapUserConfig, type RunIndexOptions as IndexOptions, type IndexResult, type IndexRunStats, type IndexTableStats, type LanguageAdapter, type ParseContext, type ParsedFile, type ParsedFilePayload, type ResolvedCodemapConfig, codemapUserConfigSchema, createCodemap, defineConfig, getAdapterForExtension, parseCodemapUserConfig, runCodemapIndex };

package/dist/index.mjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+
+import { C as getTsconfigPath, S as getProjectRoot, a as resolveCodemapConfig, g as closeDb, h as configureResolver, i as parseCodemapUserConfig, n as defineConfig, p as queryRows, r as loadUserConfig, t as codemapUserConfigSchema, w as initCodemap, x as getDatabasePath, y as openDb } from "./config-CsPgQWSX.mjs";
+import { t as runCodemapIndex } from "./run-index-DQD5afqQ.mjs";
+import { n as getAdapterForExtension, t as BUILTIN_ADAPTERS } from "./builtin-CQ_e97VT.mjs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+//#endregion
+//#region src/version.ts
+/** Package version from `package.json` (inlined at build time). */
+const CODEMAP_VERSION = "0.1.0";
+//#endregion
+//#region src/cli/bootstrap.ts
+/** Printed for `codemap --help` / `-h` (must run before config or DB access). */
+function printCliUsage() {
+	console.log(`Usage: codemap [options] [command]
+
+Index (default): update .codemap.db for the project root (\`--root\` or cwd).
+  codemap [--root DIR] [--config FILE] [--full]
+  codemap [--root DIR] [--config FILE] --files <paths...>
+
+Query:
+  codemap query "<SQL>"
+
+Agents:
+  codemap agents init [--force]
+
+Other:
+  codemap version
+  codemap --version, -V
+
+Environment: CODEMAP_ROOT (same as --root)
+
+Options:
+  --full          Full rebuild
+  --help, -h      Show this help
+`);
+}
+function printVersion() {
+	console.log(CODEMAP_VERSION);
+}
+/**
+* Reject unknown flags/args for index mode before config or DB access.
+* Prevents typos like `--versiond` from falling through to incremental index.
+*/
+function validateIndexModeArgs(rest) {
+	if (rest.length === 0) return;
+	if (rest[0] === "query") return;
+	if (rest[0] === "agents") {
+		if (rest[1] === "init") return;
+		console.error(`codemap: unknown agents command "${rest[1] ?? "(missing)"}". Expected: codemap agents init [--force]`);
+		process.exit(1);
+	}
+	let i = 0;
+	while (i < rest.length) {
+		const a = rest[i];
+		if (a === "--full") {
+			i++;
+			continue;
+		}
+		if (a === "--files") {
+			i++;
+			while (i < rest.length && !rest[i].startsWith("-")) i++;
+			continue;
+		}
+		if (a.startsWith("-")) {
+			console.error(`codemap: unknown option "${a}"`);
+			console.error("Run codemap --help for usage.");
+			process.exit(1);
+		}
+		console.error(`codemap: unexpected argument "${a}"`);
+		console.error("Run codemap --help for usage.");
+		process.exit(1);
+	}
+}
+function parseBootstrapArgs(argv) {
+	const envRoot = process.env.CODEMAP_ROOT ?? process.env.CODEMAP_TEST_BENCH;
+	let root = envRoot ? resolve(envRoot) : void 0;
+	let configFile;
+	const rest = [];
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--root" && argv[i + 1]) {
+			root = resolve(argv[++i]);
+			continue;
+		}
+		if (a === "--config" && argv[i + 1]) {
+			configFile = resolve(argv[++i]);
+			continue;
+		}
+		rest.push(a);
+	}
+	if (!root) root = process.cwd();
+	return {
+		root,
+		configFile,
+		rest
+	};
+}
+//#endregion
+//#region src/cli/main.ts
+/**
+* CLI entry — only `./bootstrap` is loaded eagerly. Command bodies are
+* dynamically imported so `codemap --help` / `version` / `agents init` avoid
+* pulling in the indexer, parser, and workers.
+*/
+async function main() {
+	const { root, configFile, rest } = parseBootstrapArgs(process.argv.slice(2));
+	if (rest[0] === "--help" || rest[0] === "-h") {
+		printCliUsage();
+		return;
+	}
+	if (rest[0] === "--version" || rest[0] === "-V" || rest[0] === "version") {
+		printVersion();
+		return;
+	}
+	if (rest[0] === "agents" && rest[1] === "init") {
+		if (rest.includes("--help") || rest.includes("-h")) {
+			console.log(`Usage: codemap agents init [--force]
+
+Copies bundled agent templates into .agents/ under the project root.
+Use --force to overwrite an existing .agents/ directory.
+`);
+			return;
+		}
+		const { runAgentsInitCmd } = await import("./cmd-agents-BJPx1vGG.mjs");
+		if (!runAgentsInitCmd({
+			projectRoot: root,
+			force: rest.includes("--force")
+		})) process.exit(1);
+		return;
+	}
+	validateIndexModeArgs(rest);
+	if (rest[0] === "query" && rest[1]) {
+		if (rest[1] === "--help" || rest[1] === "-h") {
+			console.log(`Usage: codemap query "<SQL>"
+
+Runs read-only SQL against .codemap.db (after at least one successful index run).
+Example: codemap query "SELECT name, file_path FROM symbols LIMIT 10"
+`);
+			return;
+		}
+		const { runQueryCmd } = await import("./cmd-query-D3zXZu7K.mjs");
+		await runQueryCmd({
+			root,
+			configFile,
+			sql: rest.slice(1).join(" ")
+		});
+		return;
+	}
+	const { runIndexCmd } = await import("./cmd-index-oyoHr0c4.mjs");
+	await runIndexCmd({
+		root,
+		configFile,
+		rest
+	});
+}
+//#endregion
+//#region src/api.ts
+/**
+* Programmatic entry point: loads config, calls {@link initCodemap}, configures the import resolver,
+* and returns a {@link Codemap} handle.
+*
+* @remarks
+* Only one Codemap project per process: `initCodemap` is global; the last `createCodemap()` wins.
+*/
+async function createCodemap(options = {}) {
+	const envRoot = process.env.CODEMAP_ROOT ?? process.env.CODEMAP_TEST_BENCH;
+	const root = options.root !== void 0 ? resolve(options.root) : envRoot ? resolve(envRoot) : process.cwd();
+	initCodemap(resolveCodemapConfig(root, {
+		...await loadUserConfig(root, options.configFile),
+		...options.config
+	}));
+	configureResolver(getProjectRoot(), getTsconfigPath());
+	return new Codemap();
+}
+/**
+* Handle for SQL queries and index runs after {@link createCodemap}.
+*
+* Each {@link query} opens the database for that call; {@link index} manages its own open/close lifecycle.
+*/
+var Codemap = class {
+	/** Absolute project root (from resolved config). */
+	get root() {
+		return getProjectRoot();
+	}
+	/** Absolute path to the SQLite index file (e.g. `.codemap.db`). */
+	get databasePath() {
+		return getDatabasePath();
+	}
+	/**
+	* Run a read-only SQL statement against the index (same semantics as the CLI `query` subcommand).
+	*
+	* @param sql - Valid SQLite for the Codemap schema.
+	* @returns Result rows from `better-sqlite3`-style `.all()`.
+	* @throws On invalid SQL or database errors (same as `better-sqlite3`).
+	*/
+	query(sql) {
+		return queryRows(sql);
+	}
+	/**
+	* Refresh the index: incremental (git-based), full, or targeted file list.
+	*
+	* @param options - See {@link RunIndexOptions}.
+	*/
+	async index(options = {}) {
+		const db = openDb();
+		try {
+			return await runCodemapIndex(db, options);
+		} finally {
+			closeDb(db);
+		}
+	}
+};
+//#endregion
+//#region src/index.ts
+function isMainModule() {
+	if (typeof import.meta !== "undefined" && import.meta.main) return true;
+	const arg1 = process.argv[1];
+	if (!arg1) return false;
+	try {
+		return fileURLToPath(import.meta.url) === resolve(arg1);
+	} catch {
+		return false;
+	}
+}
+if (isMainModule()) main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});
+//#endregion
+export { BUILTIN_ADAPTERS, CODEMAP_VERSION, Codemap, codemapUserConfigSchema, createCodemap, defineConfig, getAdapterForExtension, parseCodemapUserConfig, runCodemapIndex };

package/dist/parse-worker-core-DFFbs70b.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+import { a as LANG_MAP, i as extractMarkers, n as hashContent } from "./parser-VtP0EJiw.mjs";
+import { n as getAdapterForExtension } from "./builtin-CQ_e97VT.mjs";
+import { extname, join } from "node:path";
+import { readFileSync, statSync } from "node:fs";
+//#region src/parse-worker-core.ts
+function parseAsTextFallback(source, relPath) {
+	return {
+		category: "text",
+		markers: extractMarkers(source, relPath)
+	};
+}
+function parseWorkerInput(input) {
+	const { files, projectRoot } = input;
+	const results = [];
+	for (const relPath of files) {
+		const absPath = join(projectRoot, relPath);
+		let source;
+		try {
+			source = readFileSync(absPath, "utf-8");
+		} catch {
+			results.push({
+				relPath,
+				error: true,
+				fileRow: {},
+				category: "text"
+			});
+			continue;
+		}
+		const hash = hashContent(source);
+		const stat = statSync(absPath);
+		let lineCount = 1;
+		for (let i = 0; i < source.length; i++) if (source.charCodeAt(i) === 10) lineCount++;
+		const ext = extname(relPath);
+		const language = LANG_MAP[ext] ?? "text";
+		const parsed = {
+			relPath,
+			fileRow: {
+				path: relPath,
+				content_hash: hash,
+				size: stat.size,
+				line_count: lineCount,
+				language,
+				last_modified: Math.floor(stat.mtimeMs),
+				indexed_at: Date.now()
+			},
+			category: "text"
+		};
+		const ctx = {
+			absPath,
+			relPath,
+			source
+		};
+		try {
+			const adapter = getAdapterForExtension(ext);
+			const payload = adapter ? adapter.parse(ctx) : parseAsTextFallback(source, relPath);
+			Object.assign(parsed, payload);
+		} catch (err) {
+			parsed.parseError = err instanceof Error ? err.message : String(err);
+		}
+		results.push(parsed);
+	}
+	return { results };
+}
+//#endregion
+export { parseWorkerInput as t };

package/dist/parse-worker-node.d.mts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/parse-worker-node.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { t as parseWorkerInput } from "./parse-worker-core-DFFbs70b.mjs";
+import { parentPort } from "node:worker_threads";
+//#region src/parse-worker-node.ts
+if (!parentPort) throw new Error("parse-worker-node must run in a worker thread");
+parentPort.on("message", (data) => {
+	parentPort.postMessage(parseWorkerInput(data));
+});
+//#endregion
+export {};

package/dist/parse-worker.d.mts

@@ -0,0 +1,13 @@
+
+import { t as ParsedFile } from "./parsed-types-udxNyD9e.mjs";
+
+//#region src/parse-worker-core.d.ts
+interface WorkerInput {
+  files: string[];
+  projectRoot: string;
+}
+interface WorkerOutput {
+  results: ParsedFile[];
+}
+//#endregion
+export { type ParsedFile, type WorkerInput, type WorkerOutput };

package/dist/parse-worker.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { t as parseWorkerInput } from "./parse-worker-core-DFFbs70b.mjs";
+//#region src/parse-worker.ts
+self.onmessage = (event) => {
+	self.postMessage(parseWorkerInput(event.data));
+};
+//#endregion
+export {};

package/dist/parsed-types-udxNyD9e.d.mts

@@ -0,0 +1,108 @@
+
+//#region src/sqlite-db.d.ts
+/** Values accepted by SQLite bindings for bound parameters. */
+type BindValues = (string | number | null)[];
+/**
+ * Minimal SQLite surface used by Codemap — implemented for `bun:sqlite` and
+ * `better-sqlite3` (sync APIs, transactions, PRAGMAs).
+ */
+interface CodemapDatabase {
+  run(sql: string, params?: BindValues): void;
+  query<T>(sql: string): {
+    get(...params: unknown[]): T | undefined;
+    all(...params: unknown[]): T[];
+  };
+  /** Returns a function that runs the transaction when invoked (Bun / better-sqlite3 semantics). */
+  transaction<T>(fn: () => T): () => T;
+  close(): void;
+}
+//#endregion
+//#region src/db.d.ts
+interface FileRow {
+  path: string;
+  content_hash: string;
+  size: number;
+  line_count: number;
+  language: string;
+  last_modified: number;
+  indexed_at: number;
+}
+interface SymbolRow {
+  file_path: string;
+  name: string;
+  kind: string;
+  line_start: number;
+  line_end: number;
+  signature: string;
+  is_exported: number;
+  is_default_export: number;
+}
+interface ImportRow {
+  file_path: string;
+  source: string;
+  resolved_path: string | null;
+  specifiers: string;
+  is_type_only: number;
+  line_number: number;
+}
+interface ExportRow {
+  file_path: string;
+  name: string;
+  kind: string;
+  is_default: number;
+  re_export_source: string | null;
+}
+interface ComponentRow {
+  file_path: string;
+  name: string;
+  props_type: string | null;
+  hooks_used: string;
+  is_default_export: number;
+}
+interface MarkerRow {
+  file_path: string;
+  line_number: number;
+  kind: string;
+  content: string;
+}
+interface CssVariableRow {
+  file_path: string;
+  name: string;
+  value: string | null;
+  scope: string;
+  line_number: number;
+}
+interface CssClassRow {
+  file_path: string;
+  name: string;
+  is_module: number;
+  line_number: number;
+}
+interface CssKeyframeRow {
+  file_path: string;
+  name: string;
+  line_number: number;
+}
+//#endregion
+//#region src/parsed-types.d.ts
+/**
+ * One indexed file’s extracted data (workers return arrays of these).
+ */
+interface ParsedFile {
+  relPath: string;
+  error?: boolean;
+  parseError?: string;
+  fileRow: FileRow;
+  category: "ts" | "css" | "text";
+  symbols?: SymbolRow[];
+  imports?: ImportRow[];
+  exports?: ExportRow[];
+  components?: ComponentRow[];
+  markers?: MarkerRow[];
+  cssVariables?: CssVariableRow[];
+  cssClasses?: CssClassRow[];
+  cssKeyframes?: CssKeyframeRow[];
+  cssImportSources?: string[];
+}
+//#endregion
+export { CodemapDatabase as n, ParsedFile as t };