@zxyycom/vibe-check 0.0.1

package/src/package-checks/function-metrics/lizard/parser.ts

@@ -0,0 +1,179 @@
+import type { FunctionMetric } from "../measurement-model.ts";
+import type { ExactInputMeasurement } from "../../project-files/exact-input-measurement.ts";
+import { errorMessage } from "../../host-environment/error-message.ts";
+import { parseCsvRows } from "./csv.ts";
+import { normalizeScannerReportedPath } from "../../project-files/reported-path.ts";
+
+export type LizardParseResult =
+  | {
+      readonly measurements: readonly ExactInputMeasurement<FunctionMetric>[];
+      readonly ok: true;
+    }
+  | {
+      readonly error: string;
+      readonly ok: false;
+      readonly reason: "invalid-result";
+    };
+
+const LIZARD_COLUMNS = {
+  nloc: 0,
+  ccn: 1,
+  parameterCount: 3,
+  filePath: 6,
+  functionName: 7,
+  startLine: 9,
+  endLine: 10
+} as const;
+
+/**
+ * 将 Lizard CSV 输出解析为 FunctionMetric 数组。
+ *
+ * Lizard 1.23 CSV 列（--csv）：
+ * NLOC,CCN,token count,parameter count,length,location,file path,function name,long name,start line,end line
+ */
+export function parseLizardCSV(csv: string, cwd: string): LizardParseResult {
+  try {
+    const measurements: ExactInputMeasurement<FunctionMetric>[] = [];
+
+    for (const [index, row] of lizardDataRows(parseCsvRows(csv)).entries()) {
+      const measurement = functionMetricFromLizardRow(row, cwd);
+      if (!measurement) {
+        throw new Error(`invalid Lizard 1.23 CSV row ${index + 1}`);
+      }
+      measurements.push(measurement);
+    }
+
+    measurements.sort((a, b) => compareFunctionMetrics(a.payload, b.payload));
+
+    return { ok: true, measurements };
+  } catch (error: unknown) {
+    return {
+      ok: false,
+      error: `Failed to parse lizard CSV: ${errorMessage(error)}`,
+      reason: "invalid-result"
+    };
+  }
+}
+
+function lizardDataRows(rows: string[][]): string[][] {
+  const header = rows[0] ?? [];
+  return isLizard123Header(header) ? rows.slice(1) : rows;
+}
+
+function functionMetricFromLizardRow(
+  parts: string[],
+  cwd: string
+): ExactInputMeasurement<FunctionMetric> | null {
+  if (parts.length < 11) {
+    return null;
+  }
+
+  const values = parseLizardMetricValues(parts);
+  if (!values) {
+    return null;
+  }
+
+  const filePath = (parts[LIZARD_COLUMNS.filePath] ?? "").trim();
+  if (filePath.length === 0 || values.endLine < values.startLine) {
+    return null;
+  }
+  const sourcePath = normalizeScannerReportedPath(filePath, cwd);
+
+  return {
+    sourcePaths: [sourcePath],
+    payload: {
+      name: parts[LIZARD_COLUMNS.functionName] || "unknown",
+      file: sourcePath,
+      startLine: values.startLine,
+      endLine: values.endLine,
+      lines: values.nloc,
+      parameterCount: values.parameterCount,
+      cyclomaticComplexity: {
+        value: values.ccn,
+        source: "lizard"
+      }
+    }
+  };
+}
+
+interface LizardMetricValues {
+  readonly ccn: number | null;
+  readonly endLine: number;
+  readonly nloc: number;
+  readonly parameterCount: number;
+  readonly startLine: number;
+}
+
+function parseLizardMetricValues(parts: string[]): LizardMetricValues | null {
+  const ccnText = parts[LIZARD_COLUMNS.ccn].trim();
+  const ccn = ccnText === "" ? null : parseInteger(ccnText, 0);
+  const endLine = parseInteger(parts[LIZARD_COLUMNS.endLine], 1);
+  const nloc = parseInteger(parts[LIZARD_COLUMNS.nloc], 0);
+  const parameterCount = parseInteger(parts[LIZARD_COLUMNS.parameterCount], 0);
+  const startLine = parseInteger(parts[LIZARD_COLUMNS.startLine], 1);
+
+  if (
+    (ccnText !== "" && ccn === null) ||
+    endLine === null ||
+    nloc === null ||
+    parameterCount === null ||
+    startLine === null
+  ) {
+    return null;
+  }
+
+  return {
+    ccn,
+    endLine,
+    nloc,
+    parameterCount,
+    startLine
+  };
+}
+
+function compareFunctionMetrics(a: FunctionMetric, b: FunctionMetric): number {
+  for (const comparison of functionMetricComparisons(a, b)) {
+    if (comparison !== 0) return comparison;
+  }
+  return 0;
+}
+
+function functionMetricComparisons(a: FunctionMetric, b: FunctionMetric): readonly number[] {
+  return [
+    compareText(a.file, b.file),
+    a.startLine - b.startLine,
+    a.endLine - b.endLine,
+    compareText(a.name, b.name),
+    a.lines - b.lines,
+    (a.cyclomaticComplexity.value ?? -1) - (b.cyclomaticComplexity.value ?? -1),
+    a.parameterCount - b.parameterCount
+  ];
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function parseInteger(value: string | undefined, minimum: number): number | null {
+  const text = (value ?? "").trim();
+  if (!/^\d+$/.test(text)) {
+    return null;
+  }
+  const parsed = Number(text);
+  return Number.isSafeInteger(parsed) && parsed >= minimum ? parsed : null;
+}
+
+function isLizard123Header(parts: string[]): boolean {
+  return (
+    parts.length >= 11 &&
+    parts[LIZARD_COLUMNS.nloc] === "NLOC" &&
+    parts[LIZARD_COLUMNS.ccn] === "CCN" &&
+    parts[LIZARD_COLUMNS.parameterCount] === "parameter count" &&
+    parts[LIZARD_COLUMNS.filePath] === "file path" &&
+    parts[LIZARD_COLUMNS.functionName] === "function name" &&
+    parts[LIZARD_COLUMNS.startLine] === "start line" &&
+    parts[LIZARD_COLUMNS.endLine] === "end line"
+  );
+}

package/src/package-checks/function-metrics/lizard/scanner.ts

@@ -0,0 +1,62 @@
+/** 对 approved exact paths 执行 adapter-owned Lizard CSV 协议。 */
+
+import { errorMessage } from "../../host-environment/error-message.ts";
+import { runProcessSync } from "../../host-environment/process/command.ts";
+import type { ResolvedFunctionMetricsScannerOptions } from "../options.ts";
+import { parseLizardCSV, type LizardParseResult } from "./parser.ts";
+
+export type LizardScanResult =
+  | LizardParseResult
+  | Readonly<{
+      error: string;
+      ok: false;
+      reason: "execution";
+    }>;
+
+interface ScanWithLizardOptions {
+  readonly cwd: string;
+  readonly dependency: ResolvedFunctionMetricsScannerOptions;
+  readonly files: readonly string[];
+}
+
+export function scanWithLizard({
+  files,
+  cwd,
+  dependency
+}: ScanWithLizardOptions): LizardScanResult {
+  try {
+    if (files.length === 0) return { ok: true, measurements: [] };
+
+    const child = runProcessSync({
+      args: [...files, "--csv"],
+      command: dependency.executable,
+      cwd,
+      timeout: 300_000
+    });
+
+    if (child.signal !== null) {
+      return failedLizardScan(
+        `lizard signal ${child.signal}: ${(child.stderr || child.stdout || "no output").trim()}`
+      );
+    }
+    if (child.error) {
+      return failedLizardScan(`lizard process error: ${child.error.message}`);
+    }
+
+    if (child.status !== 0) {
+      const stderr = (child.stderr || "").trim();
+      const stdout = (child.stdout || "").trim();
+      return failedLizardScan(
+        `lizard ${child.status === null ? "invalid process state" : `exit ${child.status}`}: ${stderr || stdout || "no output"}`
+      );
+    }
+
+    return parseLizardCSV(child.stdout || "", cwd);
+  } catch (error: unknown) {
+    return failedLizardScan(`lizard adapter error: ${errorMessage(error)}`);
+  }
+}
+
+function failedLizardScan(error: string): LizardScanResult {
+  return Object.freeze({ error, ok: false, reason: "execution" });
+}

package/src/package-checks/function-metrics/measurement-model.ts

@@ -0,0 +1,30 @@
+import type { FindingPolicy } from "../code-quality-findings/policy.ts";
+import type { ResolvedFunctionMetricsLimits } from "./options.ts";
+
+export interface MetricValue {
+  readonly source: "lizard";
+  readonly value: number | null;
+}
+
+export interface FunctionMetric {
+  readonly cyclomaticComplexity: MetricValue;
+  readonly endLine: number;
+  readonly file: string;
+  readonly lines: number;
+  readonly name: string;
+  readonly parameterCount: number;
+  readonly startLine: number;
+}
+
+export interface FunctionMetricsAreaInput {
+  readonly approvedExactPaths: readonly string[];
+  readonly codeArea: string;
+  readonly findingPolicy: FindingPolicy;
+  readonly limits: ResolvedFunctionMetricsLimits;
+}
+
+export interface FunctionMetricsExactInputSet {
+  readonly approvedExactPaths: readonly string[];
+  readonly areas: readonly FunctionMetricsAreaInput[];
+  readonly rootDir: string;
+}

package/src/package-checks/function-metrics/measurement.ts

@@ -0,0 +1,57 @@
+import { acceptExactInputMeasurements } from "../project-files/exact-input-measurement.ts";
+import { checkLizard } from "./lizard/availability.ts";
+import { scanWithLizard } from "./lizard/scanner.ts";
+import type { FunctionMetric, FunctionMetricsExactInputSet } from "./measurement-model.ts";
+import type { ResolvedFunctionMetricsScannerOptions } from "./options.ts";
+
+export type FunctionMeasurementResult = Readonly<
+  | { kind: "cancelled" }
+  | { kind: "complete"; metrics: readonly FunctionMetric[] }
+  | { kind: "execution-failed" }
+  | { kind: "invalid-result" }
+  | { kind: "unavailable" }
+>;
+
+interface FunctionMeasurementInput {
+  readonly dependency: ResolvedFunctionMetricsScannerOptions;
+  readonly input: FunctionMetricsExactInputSet;
+  readonly signal: AbortSignal;
+}
+
+export async function measureFunctionMetrics({
+  dependency,
+  input,
+  signal
+}: FunctionMeasurementInput): Promise<FunctionMeasurementResult> {
+  if (signal.aborted) return Object.freeze({ kind: "cancelled" });
+  if (input.approvedExactPaths.length === 0) {
+    return Object.freeze({ kind: "complete", metrics: Object.freeze([]) });
+  }
+  const availability = await checkLizard(input.rootDir, dependency);
+  if (signal.aborted) return Object.freeze({ kind: "cancelled" });
+  if (!availability.available) {
+    return Object.freeze({ kind: "unavailable" });
+  }
+  const measurement = runFunctionScanner(input, dependency);
+  return signal.aborted ? Object.freeze({ kind: "cancelled" }) : measurement;
+}
+
+function runFunctionScanner(
+  input: FunctionMetricsExactInputSet,
+  dependency: ResolvedFunctionMetricsScannerOptions
+): FunctionMeasurementResult {
+  const result = scanWithLizard({
+    cwd: input.rootDir,
+    dependency,
+    files: input.approvedExactPaths
+  });
+  if (!result.ok) {
+    return Object.freeze({
+      kind: result.reason === "execution" ? "execution-failed" : "invalid-result"
+    });
+  }
+  const accepted = acceptExactInputMeasurements(result.measurements, input.approvedExactPaths);
+  return accepted.ok
+    ? Object.freeze({ kind: "complete", metrics: Object.freeze([...accepted.payloads]) })
+    : Object.freeze({ kind: "invalid-result" });
+}

package/src/package-checks/function-metrics/options-resolution.ts

@@ -0,0 +1,215 @@
+import {
+  hasRequiredAndOptionalRecordKeys,
+  snapshotClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import {
+  defaultProjectFileSelection,
+  resolveProjectFileSelection,
+  snapshotProjectFileSelection
+} from "../project-files/configuration.ts";
+import {
+  DEFAULT_FINDING_POLICY,
+  resolveFindingPolicy,
+  type FindingPolicy
+} from "../code-quality-findings/policy.ts";
+import {
+  type ResolvedFunctionMetricsCodeAreaOptions,
+  type ResolvedFunctionMetricsLimits,
+  type ResolvedFunctionMetricsOptions
+} from "./options.ts";
+import { validResolvedFunctionMetricsOptions } from "./options-validation.ts";
+import { LIZARD_SUPPORTED_FILE_GLOBS } from "./target-files.ts";
+
+const DEFAULT_LIZARD_EXECUTABLE = "lizard";
+const DEFAULT_CODE_LINE_MAXIMUM = 60;
+const DEFAULT_LOW_COMPLEXITY_CODE_LINE_MAXIMUM = 180;
+const DEFAULT_LOW_COMPLEXITY_BELOW = 6;
+const DEFAULT_CYCLOMATIC_COMPLEXITY_MAXIMUM = 12;
+const DEFAULT_PARAMETER_MAXIMUM = 6;
+const DEFAULT_FILES = Object.freeze({
+  exclude: defaultProjectFileSelection.exclude,
+  include: LIZARD_SUPPORTED_FILE_GLOBS,
+  source: defaultProjectFileSelection.source
+});
+
+interface PolicyRecordKeys {
+  readonly optional?: readonly string[];
+  readonly required?: readonly string[];
+}
+
+/** 校验 constructor input，并物化完整、冻结的 function-metrics options。 */
+export function resolveFunctionMetricsOptions(
+  value: unknown
+): ResolvedFunctionMetricsOptions | undefined {
+  const input = snapshotPolicyRecord(value, {
+    optional: ["codeAreas", "findingPolicy", "scanner"]
+  });
+  if (input === undefined) return undefined;
+
+  const findingPolicy = resolveFindingPolicy(input.findingPolicy, DEFAULT_FINDING_POLICY);
+  if (findingPolicy === undefined) return undefined;
+  const codeAreas = resolveCodeAreas(input.codeAreas, findingPolicy);
+  const scanner = resolveScanner(input.scanner);
+  if (codeAreas === undefined || scanner === undefined) return undefined;
+
+  const options = Object.freeze({ codeAreas, scanner });
+  return validResolvedFunctionMetricsOptions(options) ? options : undefined;
+}
+
+function resolveCodeAreas(
+  value: unknown,
+  defaultFindingPolicy: FindingPolicy
+): ResolvedFunctionMetricsOptions["codeAreas"] | undefined {
+  if (value === undefined) {
+    return Object.freeze({ project: defaultCodeArea(defaultFindingPolicy) });
+  }
+  const areas = snapshotClosedRecord(value);
+  if (areas === undefined || Object.keys(areas).length === 0) return undefined;
+
+  const resolvedEntries: Array<readonly [string, ResolvedFunctionMetricsCodeAreaOptions]> = [];
+  for (const [areaId, candidate] of Object.entries(areas)) {
+    if (!nonEmptyString(areaId)) return undefined;
+    const area = resolveCodeArea(candidate, defaultFindingPolicy);
+    if (area === undefined) return undefined;
+    resolvedEntries.push([areaId, area]);
+  }
+  return Object.freeze(Object.fromEntries(resolvedEntries));
+}
+
+function defaultCodeArea(findingPolicy: FindingPolicy): ResolvedFunctionMetricsCodeAreaOptions {
+  return Object.freeze({
+    files: snapshotProjectFileSelection(DEFAULT_FILES),
+    findingPolicy,
+    limits: defaultLimits()
+  });
+}
+
+function resolveCodeArea(
+  value: unknown,
+  defaultFindingPolicy: FindingPolicy
+): ResolvedFunctionMetricsCodeAreaOptions | undefined {
+  const area = snapshotPolicyRecord(value, {
+    optional: ["findingPolicy", "limits"],
+    required: ["files"]
+  });
+  if (area === undefined) return undefined;
+  const files = resolveProjectFileSelection(area.files, DEFAULT_FILES);
+  const findingPolicy = resolveFindingPolicy(area.findingPolicy, defaultFindingPolicy);
+  const limits = resolveLimits(area.limits);
+  return files === undefined || findingPolicy === undefined || limits === undefined
+    ? undefined
+    : Object.freeze({ files, findingPolicy, limits });
+}
+
+function resolveLimits(value: unknown): ResolvedFunctionMetricsLimits | undefined {
+  if (value === undefined) return defaultLimits();
+  const limits = snapshotPolicyRecord(value, {
+    optional: ["codeLines", "cyclomaticComplexity", "parameters"]
+  });
+  if (limits === undefined) return undefined;
+  const codeLines = resolveCodeLineLimits(limits.codeLines);
+  const cyclomaticComplexity = resolveMaximum(
+    limits.cyclomaticComplexity,
+    DEFAULT_CYCLOMATIC_COMPLEXITY_MAXIMUM
+  );
+  const parameters = resolveMaximum(limits.parameters, DEFAULT_PARAMETER_MAXIMUM);
+  if (codeLines === undefined || cyclomaticComplexity === undefined || parameters === undefined) {
+    return undefined;
+  }
+  return Object.freeze({ codeLines, cyclomaticComplexity, parameters });
+}
+
+function resolveCodeLineLimits(
+  value: unknown
+): ResolvedFunctionMetricsLimits["codeLines"] | undefined {
+  if (value === undefined) return defaultLimits().codeLines;
+  const codeLines = snapshotPolicyRecord(value, {
+    optional: ["lowComplexityAllowance", "maximum"]
+  });
+  if (codeLines === undefined) return undefined;
+  const maximum = codeLines.maximum ?? DEFAULT_CODE_LINE_MAXIMUM;
+  const allowance = resolveLowComplexityAllowance(codeLines.lowComplexityAllowance);
+  if (!positiveSafeInteger(maximum) || allowance === undefined || allowance.maximum < maximum) {
+    return undefined;
+  }
+  return Object.freeze({ lowComplexityAllowance: allowance, maximum });
+}
+
+function resolveLowComplexityAllowance(
+  value: unknown
+): ResolvedFunctionMetricsLimits["codeLines"]["lowComplexityAllowance"] | undefined {
+  if (value === undefined) {
+    return Object.freeze({
+      cyclomaticComplexityBelow: DEFAULT_LOW_COMPLEXITY_BELOW,
+      maximum: DEFAULT_LOW_COMPLEXITY_CODE_LINE_MAXIMUM
+    });
+  }
+  const allowance = snapshotPolicyRecord(value, {
+    optional: ["cyclomaticComplexityBelow", "maximum"]
+  });
+  if (allowance === undefined) return undefined;
+  const cyclomaticComplexityBelow =
+    allowance.cyclomaticComplexityBelow ?? DEFAULT_LOW_COMPLEXITY_BELOW;
+  const maximum = allowance.maximum ?? DEFAULT_LOW_COMPLEXITY_CODE_LINE_MAXIMUM;
+  return positiveSafeInteger(cyclomaticComplexityBelow) && positiveSafeInteger(maximum)
+    ? Object.freeze({ cyclomaticComplexityBelow, maximum })
+    : undefined;
+}
+
+function resolveMaximum(
+  value: unknown,
+  fallback: number
+): Readonly<{ readonly maximum: number }> | undefined {
+  if (value === undefined) return Object.freeze({ maximum: fallback });
+  const input = snapshotPolicyRecord(value, { optional: ["maximum"] });
+  if (input === undefined) return undefined;
+  const maximum = input.maximum ?? fallback;
+  return positiveSafeInteger(maximum) ? Object.freeze({ maximum }) : undefined;
+}
+
+function defaultLimits(): ResolvedFunctionMetricsLimits {
+  return Object.freeze({
+    codeLines: Object.freeze({
+      lowComplexityAllowance: Object.freeze({
+        cyclomaticComplexityBelow: DEFAULT_LOW_COMPLEXITY_BELOW,
+        maximum: DEFAULT_LOW_COMPLEXITY_CODE_LINE_MAXIMUM
+      }),
+      maximum: DEFAULT_CODE_LINE_MAXIMUM
+    }),
+    cyclomaticComplexity: Object.freeze({ maximum: DEFAULT_CYCLOMATIC_COMPLEXITY_MAXIMUM }),
+    parameters: Object.freeze({ maximum: DEFAULT_PARAMETER_MAXIMUM })
+  });
+}
+
+function resolveScanner(value: unknown): ResolvedFunctionMetricsOptions["scanner"] | undefined {
+  if (value === undefined) return Object.freeze({ executable: DEFAULT_LIZARD_EXECUTABLE });
+  const scanner = snapshotPolicyRecord(value, { optional: ["executable"] });
+  if (scanner === undefined) return undefined;
+  const executable = scanner.executable ?? DEFAULT_LIZARD_EXECUTABLE;
+  return nonEmptyString(executable) ? Object.freeze({ executable }) : undefined;
+}
+
+function snapshotPolicyRecord(
+  value: unknown,
+  keys: PolicyRecordKeys
+): Readonly<Record<string, unknown>> | undefined {
+  const record = snapshotClosedRecord(value);
+  if (
+    record === undefined ||
+    !hasRequiredAndOptionalRecordKeys(record, {
+      optional: keys.optional ?? [],
+      required: keys.required ?? []
+    })
+  ) {
+    return undefined;
+  }
+  return record;
+}
+
+function positiveSafeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}

package/src/package-checks/function-metrics/options-validation.ts

@@ -0,0 +1,89 @@
+import { snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
+import { validProjectFileSelection } from "../project-files/configuration.ts";
+import { validFindingPolicy } from "../code-quality-findings/policy.ts";
+import type { ResolvedFunctionMetricsOptions } from "./options.ts";
+
+/** 验证 constructor 已物化的完整 function-metrics options。 */
+export function validResolvedFunctionMetricsOptions(
+  value: unknown
+): value is ResolvedFunctionMetricsOptions {
+  const options = exactRecord(value, ["codeAreas", "scanner"]);
+  return (
+    options !== undefined && validCodeAreas(options.codeAreas) && validScanner(options.scanner)
+  );
+}
+
+function validCodeAreas(value: unknown): boolean {
+  const areas = snapshotClosedRecord(value);
+  if (areas === undefined || Object.keys(areas).length === 0) return false;
+  return Object.entries(areas).every(([areaId, candidate]) => {
+    const area = exactRecord(candidate, ["files", "findingPolicy", "limits"]);
+    return (
+      nonEmptyString(areaId) &&
+      area !== undefined &&
+      validProjectFileSelection(area.files) &&
+      validFindingPolicy(area.findingPolicy) &&
+      validLimits(area.limits)
+    );
+  });
+}
+
+function validLimits(value: unknown): boolean {
+  const limits = exactRecord(value, ["codeLines", "cyclomaticComplexity", "parameters"]);
+  if (limits === undefined) return false;
+  const codeLineLimits = codeLineLimitsFrom(limits.codeLines);
+  const cyclomaticComplexity = maximumLimitFrom(limits.cyclomaticComplexity);
+  const parameters = maximumLimitFrom(limits.parameters);
+  return (
+    codeLineLimits !== undefined &&
+    cyclomaticComplexity !== undefined &&
+    parameters !== undefined &&
+    positiveSafeInteger(cyclomaticComplexity.maximum) &&
+    positiveSafeInteger(parameters.maximum)
+  );
+}
+
+function codeLineLimitsFrom(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  const codeLines = exactRecord(value, ["lowComplexityAllowance", "maximum"]);
+  const allowance = exactRecord(codeLines?.lowComplexityAllowance, [
+    "cyclomaticComplexityBelow",
+    "maximum"
+  ]);
+  return codeLines !== undefined &&
+    allowance !== undefined &&
+    positiveSafeInteger(codeLines.maximum) &&
+    positiveSafeInteger(allowance.maximum) &&
+    allowance.maximum >= codeLines.maximum &&
+    positiveSafeInteger(allowance.cyclomaticComplexityBelow)
+    ? codeLines
+    : undefined;
+}
+
+function maximumLimitFrom(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  return exactRecord(value, ["maximum"]);
+}
+
+function validScanner(value: unknown): boolean {
+  const scanner = exactRecord(value, ["executable"]);
+  return scanner !== undefined && nonEmptyString(scanner.executable);
+}
+
+function exactRecord(
+  value: unknown,
+  keys: readonly string[]
+): Readonly<Record<string, unknown>> | undefined {
+  const record = snapshotClosedRecord(value);
+  return record !== undefined &&
+    Object.keys(record).length === keys.length &&
+    keys.every((key) => Object.hasOwn(record, key))
+    ? record
+    : undefined;
+}
+
+function positiveSafeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}