@mandujs/core 0.54.31 → 0.55.0-beta.1

package/src/testing/db.ts

@@ -1,157 +1,157 @@
-/**
- * @mandujs/core/testing/db
- *
- * In-memory / file-backed SQLite fixture for integration tests.
- *
- * Wraps `@mandujs/core/db` so callers do not have to learn Bun.SQL's URL
- * conventions just to stand up a throwaway database. The default is
- * `sqlite::memory:` — fully isolated, survives exactly one test, zero
- * filesystem footprint.
- *
- * ```ts
- * import { createTestDb } from "@mandujs/core/testing";
- *
- * const db = await createTestDb({
- *   schema: `
- *     CREATE TABLE users (id TEXT PRIMARY KEY, email TEXT NOT NULL);
- *     CREATE INDEX users_email ON users(email);
- *   `,
- * });
- * afterEach(async () => await db.close());
- *
- * await db.db`INSERT INTO users (id, email) VALUES (${"u1"}, ${"a@b.c"})`;
- * const rows = await db.db<{ id: string; email: string }>`SELECT * FROM users`;
- * expect(rows).toHaveLength(1);
- * ```
- *
- * ## Design
- *
- * - **Isolation first**: each call to `createTestDb()` returns a fresh
- *   `Db` handle. SQLite in-memory dbs are scoped to the connection, so
- *   there is no cross-fixture leakage.
- * - **DDL delivered as plain SQL**: callers pass schema as a string (or an
- *   array of statements). No dependency on the resource migration runner —
- *   that's a Phase 12.3 concern.
- * - **Transaction helper**: `transaction(fn)` is just a re-export of the
- *   underlying `Db.transaction` — convenient to avoid threading `db.db.*`.
- * - **Async-dispose**: `using db = await createTestDb(...)` works via
- *   `Symbol.asyncDispose` (ES2023 Explicit Resource Management). Pair with
- *   Bun.test's per-test cleanup for maximum terseness.
- *
- * ## SQLite caveats
- *
- * Bun.SQL's SQLite adapter requires non-null columns to be typed.
- * Tests that want rich schemas should use `TEXT`, `INTEGER`, `REAL`,
- * `BLOB`. Higher-level typed schemas come with the Phase 12.3 resource
- * migration fixture.
- *
- * @module testing/db
- */
-
-import { createDb, type Db } from "../db/index";
-
-/** Options for {@link createTestDb}. */
-export interface CreateTestDbOptions {
-  /**
-   * Connection URL. Default: `"sqlite::memory:"`.
-   *
-   * Any `sqlite:` URL is accepted — `sqlite:./fixture.db` for a file-backed
-   * fixture that survives across fixture instances, for example. Non-sqlite
-   * providers are accepted but not recommended for unit tests (you lose
-   * isolation across fixtures).
-   */
-  url?: string;
-  /**
-   * DDL to apply on open. Accepts a multi-statement SQL string or an array
-   * of pre-split statements. Statements are run sequentially — if any
-   * fails, subsequent ones are skipped and the error re-throws.
-   */
-  schema?: string | string[];
-  /** Optional seed block to run after `schema` — convenient for row-level setup. */
-  seed?: (db: Db) => Promise<void> | void;
-}
-
-/** Handle returned by {@link createTestDb}. */
-export interface TestDb {
-  /** The underlying Db handle — use as a tagged-template query function. */
-  readonly db: Db;
-  /** Re-export of `db.transaction`. */
-  transaction: Db["transaction"];
-  /**
-   * Apply additional DDL after the fixture has been created. Useful when the
-   * schema depends on per-test parameters (e.g., random suffixes to avoid
-   * SQLite's reserved-words).
-   */
-  apply(ddl: string | string[]): Promise<void>;
-  /** Idempotent cleanup — safe to call multiple times. */
-  close(): Promise<void>;
-  /** `using db = await createTestDb(...)` support. */
-  [Symbol.asyncDispose](): Promise<void>;
-}
-
-/** Split a multi-statement SQL string into individual statements. */
-function splitSql(source: string): string[] {
-  // Naïve splitter: works for vanilla DDL without embedded `;` inside quoted
-  // strings — the realistic shape of test fixtures. A full lexer lives in
-  // `db/migrations/runner.ts`; we intentionally do not re-use it here to
-  // avoid coupling the testing fixture to migration-runner internals.
-  return source
-    .split(";")
-    .map((s) => s.trim())
-    .filter((s) => s.length > 0);
-}
-
-async function applyDdl(db: Db, ddl: string | string[]): Promise<void> {
-  const statements = Array.isArray(ddl) ? ddl : splitSql(ddl);
-  for (const stmt of statements) {
-    // Bun.SQL's tagged-template form does not support raw DDL composition —
-    // but a 1-argument template with no placeholders is safe. The value
-    // inside `strings.raw[0]` is the literal SQL, never an interpolated value.
-    const raw = stmt.trim();
-    if (raw.length === 0) continue;
-    const strings = Object.assign([raw], { raw: [raw] }) as TemplateStringsArray;
-    await db(strings);
-  }
-}
-
-/**
- * Boot a fixture-scoped database handle.
- *
- * The default URL (`sqlite::memory:`) creates a per-connection in-memory
- * database — ideal for per-test isolation.
- *
- * @throws if `url` is non-empty but Bun.SQL rejects it on the first query.
- *   Validation is lazy — construction never throws on unreachable targets.
- */
-export async function createTestDb(
-  options: CreateTestDbOptions = {},
-): Promise<TestDb> {
-  const url = options.url ?? "sqlite::memory:";
-  const db = createDb({ url });
-
-  if (options.schema !== undefined) {
-    await applyDdl(db, options.schema);
-  }
-  if (options.seed) {
-    await options.seed(db);
-  }
-
-  let closed = false;
-  const close = async (): Promise<void> => {
-    if (closed) return;
-    closed = true;
-    await db.close();
-  };
-
-  return {
-    db,
-    transaction: db.transaction.bind(db),
-    async apply(ddl) {
-      await applyDdl(db, ddl);
-    },
-    close,
-    async [Symbol.asyncDispose]() {
-      await close();
-    },
-  };
-}
+/**
+ * @mandujs/core/testing/db
+ *
+ * In-memory / file-backed SQLite fixture for integration tests.
+ *
+ * Wraps `@mandujs/core/db` so callers do not have to learn Bun.SQL's URL
+ * conventions just to stand up a throwaway database. The default is
+ * `sqlite::memory:` — fully isolated, survives exactly one test, zero
+ * filesystem footprint.
+ *
+ * ```ts
+ * import { createTestDb } from "@mandujs/core/testing";
+ *
+ * const db = await createTestDb({
+ *   schema: `
+ *     CREATE TABLE users (id TEXT PRIMARY KEY, email TEXT NOT NULL);
+ *     CREATE INDEX users_email ON users(email);
+ *   `,
+ * });
+ * afterEach(async () => await db.close());
+ *
+ * await db.db`INSERT INTO users (id, email) VALUES (${"u1"}, ${"a@b.c"})`;
+ * const rows = await db.db<{ id: string; email: string }>`SELECT * FROM users`;
+ * expect(rows).toHaveLength(1);
+ * ```
+ *
+ * ## Design
+ *
+ * - **Isolation first**: each call to `createTestDb()` returns a fresh
+ *   `Db` handle. SQLite in-memory dbs are scoped to the connection, so
+ *   there is no cross-fixture leakage.
+ * - **DDL delivered as plain SQL**: callers pass schema as a string (or an
+ *   array of statements). No dependency on the resource migration runner —
+ *   that's a Phase 12.3 concern.
+ * - **Transaction helper**: `transaction(fn)` is just a re-export of the
+ *   underlying `Db.transaction` — convenient to avoid threading `db.db.*`.
+ * - **Async-dispose**: `using db = await createTestDb(...)` works via
+ *   `Symbol.asyncDispose` (ES2023 Explicit Resource Management). Pair with
+ *   Bun.test's per-test cleanup for maximum terseness.
+ *
+ * ## SQLite caveats
+ *
+ * Bun.SQL's SQLite adapter requires non-null columns to be typed.
+ * Tests that want rich schemas should use `TEXT`, `INTEGER`, `REAL`,
+ * `BLOB`. Higher-level typed schemas come with the Phase 12.3 resource
+ * migration fixture.
+ *
+ * @module testing/db
+ */
+
+import { createDb, type Db } from "../db/index";
+
+/** Options for {@link createTestDb}. */
+export interface CreateTestDbOptions {
+  /**
+   * Connection URL. Default: `"sqlite::memory:"`.
+   *
+   * Any `sqlite:` URL is accepted — `sqlite:./fixture.db` for a file-backed
+   * fixture that survives across fixture instances, for example. Non-sqlite
+   * providers are accepted but not recommended for unit tests (you lose
+   * isolation across fixtures).
+   */
+  url?: string;
+  /**
+   * DDL to apply on open. Accepts a multi-statement SQL string or an array
+   * of pre-split statements. Statements are run sequentially — if any
+   * fails, subsequent ones are skipped and the error re-throws.
+   */
+  schema?: string | string[];
+  /** Optional seed block to run after `schema` — convenient for row-level setup. */
+  seed?: (db: Db) => Promise<void> | void;
+}
+
+/** Handle returned by {@link createTestDb}. */
+export interface TestDb {
+  /** The underlying Db handle — use as a tagged-template query function. */
+  readonly db: Db;
+  /** Re-export of `db.transaction`. */
+  transaction: Db["transaction"];
+  /**
+   * Apply additional DDL after the fixture has been created. Useful when the
+   * schema depends on per-test parameters (e.g., random suffixes to avoid
+   * SQLite's reserved-words).
+   */
+  apply(ddl: string | string[]): Promise<void>;
+  /** Idempotent cleanup — safe to call multiple times. */
+  close(): Promise<void>;
+  /** `using db = await createTestDb(...)` support. */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+/** Split a multi-statement SQL string into individual statements. */
+function splitSql(source: string): string[] {
+  // Naïve splitter: works for vanilla DDL without embedded `;` inside quoted
+  // strings — the realistic shape of test fixtures. A full lexer lives in
+  // `db/migrations/runner.ts`; we intentionally do not re-use it here to
+  // avoid coupling the testing fixture to migration-runner internals.
+  return source
+    .split(";")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+async function applyDdl(db: Db, ddl: string | string[]): Promise<void> {
+  const statements = Array.isArray(ddl) ? ddl : splitSql(ddl);
+  for (const stmt of statements) {
+    // Bun.SQL's tagged-template form does not support raw DDL composition —
+    // but a 1-argument template with no placeholders is safe. The value
+    // inside `strings.raw[0]` is the literal SQL, never an interpolated value.
+    const raw = stmt.trim();
+    if (raw.length === 0) continue;
+    const strings = Object.assign([raw], { raw: [raw] }) as TemplateStringsArray;
+    await db(strings);
+  }
+}
+
+/**
+ * Boot a fixture-scoped database handle.
+ *
+ * The default URL (`sqlite::memory:`) creates a per-connection in-memory
+ * database — ideal for per-test isolation.
+ *
+ * @throws if `url` is non-empty but Bun.SQL rejects it on the first query.
+ *   Validation is lazy — construction never throws on unreachable targets.
+ */
+export async function createTestDb(
+  options: CreateTestDbOptions = {},
+): Promise<TestDb> {
+  const url = options.url ?? "sqlite::memory:";
+  const db = createDb({ url });
+
+  if (options.schema !== undefined) {
+    await applyDdl(db, options.schema);
+  }
+  if (options.seed) {
+    await options.seed(db);
+  }
+
+  let closed = false;
+  const close = async (): Promise<void> => {
+    if (closed) return;
+    closed = true;
+    await db.close();
+  };
+
+  return {
+    db,
+    transaction: db.transaction.bind(db),
+    async apply(ddl) {
+      await applyDdl(db, ddl);
+    },
+    close,
+    async [Symbol.asyncDispose]() {
+      await close();
+    },
+  };
+}

package/src/testing/index.ts

@@ -337,8 +337,8 @@ export {
 
 // ========== Phase 18.σ — Unified reporter ==========
 
-export {
-  formatReport,
+export {
+  formatReport,
   formatHuman,
   formatJson,
   formatJunit,
@@ -362,4 +362,10 @@ export {
   type ReporterFormat,
   type ReportSummary,
   type FormatOptions,
-} from "./reporter";
+} from "./reporter";
+
+export {
+  mergeAndWriteLcov,
+  type LcovMergeInput,
+  type LcovMergeSummary,
+} from "./lcov";

package/src/testing/lcov.ts

@@ -0,0 +1,192 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export interface LcovMergeInput {
+  label: string;
+  source: { kind: "file"; path: string } | { kind: "text"; body: string };
+}
+
+interface LcovRecord {
+  sourceFile: string;
+  lines: Map<number, number>;
+  functions: Map<string, number>;
+  functionLines: Map<string, number>;
+  branches: Map<string, number>;
+}
+
+export interface LcovMergeSummary {
+  files: number;
+  linesFound: number;
+  linesHit: number;
+  branchesFound: number;
+  branchesHit: number;
+  functionsFound: number;
+  functionsHit: number;
+}
+
+function createRecord(sourceFile: string): LcovRecord {
+  return {
+    sourceFile,
+    lines: new Map(),
+    functions: new Map(),
+    functionLines: new Map(),
+    branches: new Map(),
+  };
+}
+
+function add(map: Map<number, number>, key: number, value: number): void;
+function add(map: Map<string, number>, key: string, value: number): void;
+function add(
+  map: Map<number, number> | Map<string, number>,
+  key: number | string,
+  value: number,
+): void {
+  const target = map as Map<number | string, number>;
+  target.set(key, (target.get(key) ?? 0) + value);
+}
+
+function ingestLcov(body: string, records: Map<string, LcovRecord>): void {
+  let current: LcovRecord | null = null;
+
+  for (const rawLine of body.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.startsWith("SF:")) {
+      const sourceFile = line.slice(3);
+      current = records.get(sourceFile) ?? createRecord(sourceFile);
+      records.set(sourceFile, current);
+      continue;
+    }
+    if (!current) continue;
+    if (line === "end_of_record") {
+      current = null;
+      continue;
+    }
+    if (line.startsWith("DA:")) {
+      const [lineNumber, hits] = line.slice(3).split(",").map(Number);
+      if (Number.isFinite(lineNumber) && Number.isFinite(hits)) {
+        add(current.lines, lineNumber!, hits!);
+      }
+      continue;
+    }
+    if (line.startsWith("FN:")) {
+      const separator = line.indexOf(",", 3);
+      if (separator > 3) {
+        const lineNumber = Number(line.slice(3, separator));
+        const name = line.slice(separator + 1);
+        if (Number.isFinite(lineNumber) && name) current.functionLines.set(name, lineNumber);
+      }
+      continue;
+    }
+    if (line.startsWith("FNDA:")) {
+      const separator = line.indexOf(",", 5);
+      if (separator > 5) {
+        const hits = Number(line.slice(5, separator));
+        const name = line.slice(separator + 1);
+        if (Number.isFinite(hits) && name) add(current.functions, name, hits);
+      }
+      continue;
+    }
+    if (line.startsWith("BRDA:")) {
+      const parts = line.slice(5).split(",");
+      if (parts.length >= 4) {
+        const key = parts.slice(0, 3).join(",");
+        const hits = parts[3] === "-" ? 0 : Number(parts[3]);
+        if (Number.isFinite(hits)) add(current.branches, key, hits);
+      }
+    }
+  }
+}
+
+function renderRecord(record: LcovRecord): string {
+  const lines = [`SF:${record.sourceFile}`];
+  const functionNames = new Set([
+    ...record.functionLines.keys(),
+    ...record.functions.keys(),
+  ]);
+
+  for (const name of [...functionNames].sort()) {
+    const line = record.functionLines.get(name);
+    if (line !== undefined) lines.push(`FN:${line},${name}`);
+  }
+  for (const name of [...functionNames].sort()) {
+    lines.push(`FNDA:${record.functions.get(name) ?? 0},${name}`);
+  }
+  lines.push(`FNF:${functionNames.size}`);
+  lines.push(`FNH:${[...functionNames].filter((name) => (record.functions.get(name) ?? 0) > 0).length}`);
+
+  for (const key of [...record.branches.keys()].sort()) {
+    lines.push(`BRDA:${key},${record.branches.get(key) ?? 0}`);
+  }
+  lines.push(`BRF:${record.branches.size}`);
+  lines.push(`BRH:${[...record.branches.values()].filter((hits) => hits > 0).length}`);
+
+  for (const lineNumber of [...record.lines.keys()].sort((left, right) => left - right)) {
+    lines.push(`DA:${lineNumber},${record.lines.get(lineNumber) ?? 0}`);
+  }
+  lines.push(`LF:${record.lines.size}`);
+  lines.push(`LH:${[...record.lines.values()].filter((hits) => hits > 0).length}`);
+  lines.push("end_of_record");
+  return lines.join("\n");
+}
+
+function summarize(records: Map<string, LcovRecord>): LcovMergeSummary {
+  const summary: LcovMergeSummary = {
+    files: records.size,
+    linesFound: 0,
+    linesHit: 0,
+    branchesFound: 0,
+    branchesHit: 0,
+    functionsFound: 0,
+    functionsHit: 0,
+  };
+
+  for (const record of records.values()) {
+    const functionNames = new Set([
+      ...record.functionLines.keys(),
+      ...record.functions.keys(),
+    ]);
+    summary.linesFound += record.lines.size;
+    summary.linesHit += [...record.lines.values()].filter((hits) => hits > 0).length;
+    summary.branchesFound += record.branches.size;
+    summary.branchesHit += [...record.branches.values()].filter((hits) => hits > 0).length;
+    summary.functionsFound += functionNames.size;
+    summary.functionsHit += [...functionNames].filter((name) => (record.functions.get(name) ?? 0) > 0).length;
+  }
+
+  return summary;
+}
+
+/**
+ * Merge LCOV sources into the canonical Mandu coverage artifact. This lives
+ * in Core so the product CLI does not need the optional ATE Labs package for
+ * ordinary unit/integration coverage.
+ */
+export function mergeAndWriteLcov(params: {
+  repoRoot: string;
+  inputs: LcovMergeInput[];
+  outputPath?: string;
+}): { summary: LcovMergeSummary; outputPath: string | null } {
+  const records = new Map<string, LcovRecord>();
+
+  for (const input of params.inputs) {
+    if (input.source.kind === "file" && !fs.existsSync(input.source.path)) continue;
+    const body = input.source.kind === "file"
+      ? fs.readFileSync(input.source.path, "utf8")
+      : input.source.body;
+    ingestLcov(body, records);
+  }
+
+  const summary = summarize(records);
+  if (records.size === 0) return { summary, outputPath: null };
+
+  const outputPath = path.resolve(
+    params.outputPath ?? path.join(params.repoRoot, ".mandu", "coverage", "lcov.info"),
+  );
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  const body = [...records.values()]
+    .sort((left, right) => left.sourceFile.localeCompare(right.sourceFile))
+    .map(renderRecord)
+    .join("\n");
+  fs.writeFileSync(outputPath, `${body}\n`, "utf8");
+  return { summary, outputPath };
+}