@cosmicdrift/kumiko-guards 0.1.0

package/src/_lib/security-baseline.ts

@@ -0,0 +1,325 @@
+/**
+ * Fail-closed per-repo baseline for `security: true` guards: missing or
+ * unparseable baseline file means zero tolerance — every finding blocks.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { compareToBaseline, findRepoRootFor } from "./baseline-compare";
+import type { GuardViolation } from "./guard-kit";
+
+export const SECURITY_BASELINE_FORMAT = 1;
+export const SECURITY_BASELINE_FILE = ".kumiko-security-baseline.json";
+
+export type SecurityBaseline = {
+  readonly format: number;
+  readonly repo: string;
+  readonly generated: string;
+  readonly total: number;
+  /** Guard names "fertig migriert" for this repo: no baseline tolerance, every finding blocks. */
+  readonly hardFail?: readonly string[];
+  /** guardName -> repo-relative path -> frozen finding count. */
+  readonly findings: Readonly<Record<string, Readonly<Record<string, number>>>>;
+};
+
+export type SecurityBaselineLoad =
+  | {
+      readonly kind: "ok";
+      readonly findings: SecurityBaseline["findings"];
+      readonly hardFail: readonly string[];
+    }
+  | { readonly kind: "invalid"; readonly file: string; readonly reason: string };
+
+// Compared only against the baseline file's `repo` field — a scoped npm
+// package name (`@x/y`) is no longer a path segment, so it needs no
+// path-traversal-safe validation, just a sanity check on shape.
+const REPO_NAME_RE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+
+export function securityBaselinePath(repoDir: string): string {
+  return join(repoDir, SECURITY_BASELINE_FILE);
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+function isStringArrayNoDuplicates(value: unknown): value is string[] {
+  if (!Array.isArray(value)) return false;
+  if (!value.every((entry): entry is string => typeof entry === "string")) return false;
+  return new Set(value).size === value.length;
+}
+
+function isFindingsShape(value: unknown): value is SecurityBaseline["findings"] {
+  if (typeof value !== "object" || value === null) return false;
+  return Object.values(value).every((perFile) => {
+    if (typeof perFile !== "object" || perFile === null) return false;
+    return Object.values(perFile).every(isNonNegativeInteger);
+  });
+}
+
+export function parseSecurityBaseline(raw: unknown): SecurityBaseline | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined;
+  if (!("format" in raw) || raw.format !== SECURITY_BASELINE_FORMAT) return undefined;
+  if (!("repo" in raw) || typeof raw.repo !== "string") return undefined;
+  if (!("generated" in raw) || typeof raw.generated !== "string") return undefined;
+  if (!("total" in raw) || typeof raw.total !== "number") return undefined;
+  if (!("findings" in raw) || !isFindingsShape(raw.findings)) return undefined;
+
+  let hardFail: readonly string[] | undefined;
+  if ("hardFail" in raw && raw.hardFail !== undefined) {
+    if (!isStringArrayNoDuplicates(raw.hardFail)) return undefined;
+    for (const guardName of raw.hardFail) {
+      const perFile = raw.findings[guardName];
+      // {} is allowed (guard has no current findings); any entry means it isn't done migrating yet.
+      if (perFile && Object.keys(perFile).length > 0) return undefined;
+    }
+    hardFail = raw.hardFail;
+  }
+
+  return {
+    format: raw.format,
+    repo: raw.repo,
+    generated: raw.generated,
+    total: raw.total,
+    hardFail,
+    findings: raw.findings,
+  };
+}
+
+export function loadSecurityBaseline(repo: string, repoDir: string): SecurityBaselineLoad {
+  if (!REPO_NAME_RE.test(repo)) {
+    throw new Error(`loadSecurityBaseline: invalid repo name "${repo}"`);
+  }
+  const file = securityBaselinePath(repoDir);
+  if (!existsSync(file)) return { kind: "ok", findings: {}, hardFail: [] };
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(file, "utf-8"));
+  } catch (e) {
+    return {
+      kind: "invalid",
+      file,
+      reason: `kaputtes JSON: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+  const parsed = parseSecurityBaseline(raw);
+  if (!parsed) {
+    return { kind: "invalid", file, reason: "unerwartetes Baseline-Format (format/repo/findings)" };
+  }
+  if (parsed.repo !== repo) {
+    return {
+      kind: "invalid",
+      file,
+      reason: `repo-Feld "${parsed.repo}" passt nicht zum Dateinamen "${repo}"`,
+    };
+  }
+  return { kind: "ok", findings: parsed.findings, hardFail: parsed.hardFail ?? [] };
+}
+
+export function locateFinding(
+  file: string,
+  roots: readonly { readonly name: string; readonly absPath: string }[],
+  cwd: string,
+): { readonly repo: string; readonly relPath: string } | undefined {
+  const abs = isAbsolute(file) ? file : resolve(cwd, file);
+  // Pseudo files like "<scan>" must stay unlocatable — existsSync guards
+  // against resolve() placing them under cwd.
+  if (!existsSync(abs)) return undefined;
+  const root = findRepoRootFor(abs, roots);
+  if (!root) return undefined;
+  return { repo: root.name, relPath: relative(root.absPath, abs).split(sep).join("/") };
+}
+
+export function applySecurityBaseline(args: {
+  readonly guardName: string;
+  readonly violations: readonly GuardViolation[];
+  readonly roots: readonly { readonly name: string; readonly absPath: string }[];
+  readonly cwd: string;
+  readonly load: (repo: string) => SecurityBaselineLoad;
+  /** Also fail on baseline headroom (current < baseline) across every root, not just repos with current findings. */
+  readonly strict?: boolean;
+}): { readonly blocking: GuardViolation[]; readonly frozen: number; readonly reduced: number } {
+  const { guardName, violations, roots, cwd, load, strict } = args;
+
+  type Located = {
+    readonly relPath: string;
+    readonly index: number;
+    readonly violation: GuardViolation;
+  };
+  const byRepo = new Map<string, Map<string, Located[]>>();
+  // (sortKey, violation) so the final blocking list preserves the original
+  // violation order even after synthetic baseline-file entries are spliced in.
+  const blockingEntries: Array<[number, GuardViolation]> = [];
+
+  violations.forEach((violation, index) => {
+    if (violation.neverFrozen) {
+      blockingEntries.push([index, violation]);
+      return;
+    }
+    const located = locateFinding(violation.file, roots, cwd);
+    if (!located) {
+      blockingEntries.push([index, violation]);
+      return;
+    }
+    let perRepo = byRepo.get(located.repo);
+    if (!perRepo) {
+      perRepo = new Map();
+      byRepo.set(located.repo, perRepo);
+    }
+    const bucket = perRepo.get(located.relPath) ?? [];
+    bucket.push({ relPath: located.relPath, index, violation });
+    perRepo.set(located.relPath, bucket);
+  });
+
+  const loadCache = new Map<string, SecurityBaselineLoad>();
+  const loadOnce = (repo: string): SecurityBaselineLoad => {
+    const cached = loadCache.get(repo);
+    if (cached) return cached;
+    const result = load(repo);
+    loadCache.set(repo, result);
+    return result;
+  };
+
+  let frozen = 0;
+  let reduced = 0;
+
+  for (const [repo, byPath] of byRepo) {
+    const baseline = loadOnce(repo);
+    const allEntries = [...byPath.values()].flat();
+    if (baseline.kind === "invalid") {
+      const minIndex = Math.min(...allEntries.map((e) => e.index));
+      blockingEntries.push([
+        minIndex - 0.5,
+        {
+          file: baseline.file,
+          line: 1,
+          message: `Security-Baseline unlesbar oder ungültig: ${baseline.reason}. Datei reparieren; ein kaputter Baseline-Stand darf keine Funde freigeben.`,
+        },
+      ]);
+      for (const e of allEntries) blockingEntries.push([e.index, e.violation]);
+      continue;
+    }
+    if (baseline.hardFail.includes(guardName)) {
+      for (const e of allEntries) {
+        blockingEntries.push([
+          e.index,
+          {
+            ...e.violation,
+            message: `${e.violation.message} (Security-Baseline ${repo}: ${guardName} ist fertig migriert — keine Baseline-Toleranz)`,
+          },
+        ]);
+      }
+      continue;
+    }
+    const current: Record<string, number> = {};
+    for (const [relPath, entries] of byPath) current[relPath] = entries.length;
+    const baselineForGuard = baseline.findings[guardName] ?? {};
+    const { regressions, reduced: repoReduced } = compareToBaseline(current, baselineForGuard);
+    reduced += repoReduced;
+    const regressionByPath = new Map(regressions.map((r) => [r.file, r]));
+    for (const [relPath, entries] of byPath) {
+      const regression = regressionByPath.get(relPath);
+      if (regression) {
+        for (const e of entries) {
+          blockingEntries.push([
+            e.index,
+            {
+              ...e.violation,
+              message: `${e.violation.message} (Security-Baseline ${repo}: erlaubt=${regression.baseline}, aktuell=${regression.current})`,
+            },
+          ]);
+        }
+      } else {
+        frozen += entries.length;
+      }
+    }
+  }
+
+  if (strict === true) {
+    let strictIndex = 0;
+    for (const root of roots) {
+      const baseline = loadOnce(root.name);
+      const byPath = byRepo.get(root.name);
+      if (baseline.kind === "invalid") {
+        // Repos with current findings already got this entry in the loop above.
+        if (byPath) continue;
+        blockingEntries.push([
+          violations.length + strictIndex++,
+          {
+            file: baseline.file,
+            line: 1,
+            message: `Security-Baseline unlesbar oder ungültig: ${baseline.reason}. Datei reparieren; ein kaputter Baseline-Stand darf keine Funde freigeben.`,
+          },
+        ]);
+        continue;
+      }
+      const current: Record<string, number> = {};
+      if (byPath) {
+        for (const [relPath, entries] of byPath) current[relPath] = entries.length;
+      }
+      const baselineForGuard = baseline.findings[guardName] ?? {};
+      const { reductions } = compareToBaseline(current, baselineForGuard);
+      if (!byPath) {
+        reduced += reductions.reduce((sum, r) => sum + (r.baseline - r.current), 0);
+      }
+      for (const r of reductions) {
+        blockingEntries.push([
+          violations.length + strictIndex++,
+          {
+            file: join(root.absPath, r.file),
+            line: 1,
+            message: `Security-Baseline veraltet: ${root.name}/${r.file} erlaubt ${r.baseline}, gefunden ${r.current} — \`--write-security-baseline\` ausführen und committen, sonst deckt der Headroom neue Funde.`,
+          },
+        ]);
+      }
+    }
+  }
+
+  blockingEntries.sort((a, b) => a[0] - b[0]);
+  return { blocking: blockingEntries.map(([, v]) => v), frozen, reduced };
+}
+
+export function buildSecurityBaseline(
+  repo: string,
+  guardViolations: ReadonlyArray<{
+    readonly guardName: string;
+    readonly violations: readonly GuardViolation[];
+  }>,
+  roots: readonly { readonly name: string; readonly absPath: string }[],
+  cwd: string,
+  hardFail: readonly string[] = [],
+): SecurityBaseline {
+  const findings: Record<string, Record<string, number>> = {};
+  let total = 0;
+  for (const { guardName, violations } of guardViolations) {
+    // hardFail guards are "fertig migriert" — nothing of theirs freezes into headroom.
+    if (hardFail.includes(guardName)) continue;
+    const perFile: Record<string, number> = {};
+    for (const v of violations) {
+      if (v.neverFrozen) continue;
+      const located = locateFinding(v.file, roots, cwd);
+      if (!located || located.repo !== repo) continue;
+      perFile[located.relPath] = (perFile[located.relPath] ?? 0) + 1;
+      total++;
+    }
+    if (Object.keys(perFile).length === 0) continue;
+    findings[guardName] = Object.fromEntries(
+      Object.entries(perFile).sort(([a], [b]) => a.localeCompare(b)),
+    );
+  }
+  const sortedHardFail = [...hardFail].sort();
+  return {
+    format: SECURITY_BASELINE_FORMAT,
+    repo,
+    generated: new Date().toISOString().slice(0, 10),
+    total,
+    ...(sortedHardFail.length > 0 ? { hardFail: sortedHardFail } : {}),
+    findings: Object.fromEntries(Object.entries(findings).sort(([a], [b]) => a.localeCompare(b))),
+  };
+}
+
+export function writeSecurityBaseline(baseline: SecurityBaseline, repoDir: string): string {
+  mkdirSync(repoDir, { recursive: true });
+  const path = securityBaselinePath(repoDir);
+  writeFileSync(path, `${JSON.stringify(baseline, null, 2)}\n`);
+  return path;
+}

package/src/_lib/sql-inventory.ts

@@ -0,0 +1,267 @@
+/**
+ * Raw-SQL inventory — shared allowlist + scanner for `guard-raw-sql`.
+ * Scans TypeScript sources for escape-hatch patterns (`.unsafe()`,
+ * `asRawClient()`, `DELETE FROM`, `.execute()`).
+ *
+ * Escape hatch for a justified raw-SQL call:
+ *   // kumiko-lint-ignore raw-sql <reason>
+ * on the call's own line or the line directly above. A bare tag with no
+ * reason text after it does NOT suppress the finding.
+ *
+ * I/O: Bun.Glob + Bun.file; directoryExists uses node:fs (same as roots.ts).
+ */
+import { existsSync, statSync } from "node:fs";
+import type { RepoRoot } from "./roots";
+
+/** POSIX path join without Node path module. */
+function joinPath(base: string, ...segments: string[]): string {
+  return [base, ...segments]
+    .join("/")
+    .replace(/\/+/g, "/")
+    .replace(/\/\.\//g, "/");
+}
+
+export type SqlInventoryKind = "unsafe" | "asRawClient" | "delete_from" | "execute";
+
+export type SqlInventoryHit = {
+  readonly file: string;
+  readonly line: number;
+  readonly kind: SqlInventoryKind;
+  readonly allowed: boolean;
+  /** True when a `kumiko-lint-ignore raw-sql <reason>` marker suppresses this hit. */
+  readonly markerSuppressed: boolean;
+  readonly snippet: string;
+};
+
+export type SqlInventoryReport = {
+  readonly scannedAt: string;
+  readonly root: string;
+  readonly hits: readonly SqlInventoryHit[];
+  /** Total files scanned across this repo's scan dirs — feeds the vacuity check. */
+  readonly scannedFiles: number;
+  readonly summary: {
+    readonly total: number;
+    readonly disallowed: number;
+    readonly byKind: Readonly<Record<SqlInventoryKind, number>>;
+    readonly byBucket: {
+      readonly allowed: number;
+      readonly tests: number;
+      readonly marker: number;
+      readonly disallowed: number;
+    };
+  };
+};
+
+/** Paths where `.unsafe()` / `asRawClient()` are permitted (Phase 5 guard). */
+export const RAW_SQL_ALLOWLIST: ReadonlyArray<RegExp> = [
+  // Layout-agnostic: framework packages/... AND flat app src/... AND enterprise packages/<pkg>/...
+  /(^|\/)(packages\/[^/]+\/)?src\/db\/queries\//,
+  /(^|\/)(packages\/[^/]+\/)?src\/db\/migrate-runner\.ts$/,
+  /(^|\/)(packages\/[^/]+\/)?src\/db\/schema-inspection\.ts$/,
+  /(^|\/)(packages\/[^/]+\/)?src\/db\/render-ddl\.ts$/,
+  /(^|\/)(packages\/[^/]+\/)?src\/bun-db\/query\.ts$/,
+  /(^|\/)(packages\/[^/]+\/)?src\/testing\//,
+  // ponytail: explicit enumeration — a blanket regex would auto-allow any new .unsafe()
+  /\/bundled-features\/src\/billing-foundation\/db\/queries\/subscription-projection\.ts$/,
+  /\/bundled-features\/src\/config\/db\/queries\/resolver\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/field-access\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/projection\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/quota\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/retention\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/user-data-rights\.ts$/,
+  /\/bundled-features\/src\/delivery\/db\/queries\/preferences\.ts$/,
+  /\/bundled-features\/src\/form-draft\/db\/queries\/cleanup\.ts$/,
+  /\/bundled-features\/src\/form-draft\/db\/queries\/draft-count\.ts$/,
+  /\/bundled-features\/src\/form-draft\/db\/queries\/owned-file-refs\.ts$/,
+  /\/bundled-features\/src\/inbound-mail-foundation\/db\/queries\/inbound-projections\.ts$/,
+  /\/bundled-features\/src\/secrets\/db\/queries\/read\.ts$/,
+  /\/bundled-features\/src\/sessions\/db\/queries\/cleanup\.ts$/,
+  /\/bundled-features\/src\/user\/db\/queries\/stream-tenant-backfill\.ts$/,
+  /\/packages\/framework\/src\/engine\/steps\/unsafe-projection-/,
+  /(^|\/)samples\/(apps|recipes)\/[^/]+\/src\/db\/queries\//,
+  /\/bin\/commands\//,
+  /\/scripts\/codemod-/,
+  /\/__tests__\//,
+  /\/bin\/_lib\//,
+];
+
+/** Escape-hatch tag. Must be followed by whitespace + a non-empty reason to suppress. */
+const MARKER_TAG = "kumiko-lint-ignore raw-sql";
+// Marker must appear in a // comment — string literals describing the hatch must not suppress.
+const MARKER_WITH_REASON_RE = /(^|\s)\/\/\s*kumiko-lint-ignore raw-sql\s+\S/;
+
+const SKIP_PATH_PARTS = ["/node_modules/", "/dist/", "/.kumiko/"] as const;
+
+const PATTERNS: ReadonlyArray<{
+  readonly kind: SqlInventoryKind;
+  readonly re: RegExp;
+}> = [
+  { kind: "unsafe", re: /\.unsafe\s*[<(]/ },
+  { kind: "asRawClient", re: /asRawClient\s*\(/ },
+  { kind: "delete_from", re: /DELETE\s+FROM/i },
+  { kind: "execute", re: /\.execute\s*\(/ },
+];
+
+/** Only these kinds fail CI; delete_from/execute stay inventory-only (infra#610). */
+export const BLOCKING_SQL_KINDS: ReadonlyArray<SqlInventoryKind> = ["unsafe", "asRawClient"];
+
+const TS_GLOB = new Bun.Glob("**/*.{ts,tsx}");
+
+export type SqlScanLayout = "multi-package" | "flat" | "none";
+
+// kumiko-platform deliberately returns "none" (0 files) — its docs-samples tree needs its own allowlist review before this guard scans it (follow-up issue).
+export function sqlScanLayoutFor(root: Pick<RepoRoot, "name" | "kind">): SqlScanLayout {
+  if (root.name === "kumiko-platform") return "none";
+  if (root.kind === "framework" || root.kind === "library") return "multi-package";
+  return "flat";
+}
+
+/** Scan dirs per repo layout — multi-package keeps the packages/samples/scripts/bin layout, flat is a bare src/ + bin/. */
+function scanDirsFor(layout: SqlScanLayout): readonly string[] {
+  if (layout === "multi-package") return ["packages", "samples", "scripts", "bin"];
+  if (layout === "none") return [];
+  return ["src", "bin"];
+}
+
+function normalizePathForMatch(filePath: string): string {
+  return filePath.startsWith("/") ? filePath : `/${filePath}`;
+}
+
+export function isRawSqlAllowed(filePath: string): boolean {
+  const normalized = normalizePathForMatch(filePath);
+  return RAW_SQL_ALLOWLIST.some((re) => re.test(normalized));
+}
+
+function isTestPath(filePath: string): boolean {
+  return /\/__tests__\//.test(normalizePathForMatch(filePath));
+}
+
+function bucketFor(hit: SqlInventoryHit): "allowed" | "tests" | "marker" | "disallowed" {
+  if (isTestPath(hit.file)) return "tests";
+  if (hit.allowed) return "allowed";
+  if (hit.markerSuppressed) return "marker";
+  return "disallowed";
+}
+
+function shouldSkipRelativePath(rel: string): boolean {
+  return SKIP_PATH_PARTS.some((part) => rel.includes(part));
+}
+
+function directoryExists(path: string): boolean {
+  try {
+    return existsSync(path) && statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function collectTsFiles(repoRoot: string, layout: SqlScanLayout): Promise<string[]> {
+  const out: string[] = [];
+  for (const sub of scanDirsFor(layout)) {
+    const cwd = joinPath(repoRoot, sub);
+    if (!directoryExists(cwd)) continue;
+    for await (const rel of TS_GLOB.scan({ cwd, onlyFiles: true })) {
+      const normalized = rel.replace(/\0/g, "");
+      if (!normalized || shouldSkipRelativePath(normalized)) continue;
+      out.push(joinPath(sub, normalized));
+    }
+  }
+  return out;
+}
+
+/** Strip a trailing/leading ignore-marker comment out of a reported snippet. */
+function stripMarker(trimmed: string): string {
+  const idx = trimmed.indexOf(MARKER_TAG);
+  if (idx < 0) return trimmed;
+  return trimmed.slice(0, idx).trimEnd();
+}
+
+function scanFileText(relPath: string, text: string, hits: SqlInventoryHit[]): void {
+  const lines = text.split("\n");
+  const consumedMarkers = new Set<number>();
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const trimmed = line.trim();
+
+    // Lookback happens independently of the comment-only-line skip below —
+    // a marker placed on its own comment line (the common case: the line
+    // ABOVE the offending call) must still be seen even though that line
+    // itself never reaches the pattern loop.
+    //
+    // Documented hatch: marker on the call line or the line directly above.
+    // Each marker line suppresses at most one subsequent hit (consumed), so a
+    // second `.unsafe()` under the same comment is not silently covered.
+    let suppressed = false;
+    if (MARKER_WITH_REASON_RE.test(line)) {
+      suppressed = true;
+    } else if (i > 0 && MARKER_WITH_REASON_RE.test(lines[i - 1] ?? "")) {
+      const markerIdx = i - 1;
+      if (!consumedMarkers.has(markerIdx)) {
+        suppressed = true;
+        consumedMarkers.add(markerIdx);
+      }
+    }
+
+    if (
+      trimmed.startsWith("//") ||
+      trimmed.startsWith("*") ||
+      trimmed.startsWith("/**") ||
+      trimmed.startsWith("/*")
+    ) {
+      continue;
+    }
+    for (const { kind, re } of PATTERNS) {
+      if (!re.test(line)) continue;
+      hits.push({
+        file: relPath,
+        line: i + 1,
+        kind,
+        allowed: isRawSqlAllowed(relPath),
+        markerSuppressed: suppressed,
+        snippet: stripMarker(trimmed).slice(0, 120),
+      });
+    }
+  }
+}
+
+export async function scanRepo(
+  repoRoot: string,
+  layout: SqlScanLayout,
+): Promise<SqlInventoryReport> {
+  const relFiles = await collectTsFiles(repoRoot, layout);
+  const hits: SqlInventoryHit[] = [];
+
+  for (const rel of relFiles) {
+    const abs = joinPath(repoRoot, rel);
+    const text = await Bun.file(abs).text();
+    scanFileText(rel, text, hits);
+  }
+
+  const byKind: Record<SqlInventoryKind, number> = {
+    unsafe: 0,
+    asRawClient: 0,
+    delete_from: 0,
+    execute: 0,
+  };
+  let disallowed = 0;
+  const byBucket = { allowed: 0, tests: 0, marker: 0, disallowed: 0 };
+  for (const h of hits) {
+    byKind[h.kind]++;
+    const b = bucketFor(h);
+    byBucket[b]++;
+    if (b === "disallowed") disallowed++;
+  }
+
+  return {
+    scannedAt: new Date().toISOString(),
+    root: repoRoot,
+    hits,
+    scannedFiles: relFiles.length,
+    summary: {
+      total: hits.length,
+      disallowed,
+      byKind,
+      byBucket,
+    },
+  };
+}