@zxyycom/vibe-check 0.0.1

package/src/package-checks/final-data-parsing.ts

@@ -0,0 +1,49 @@
+import {
+  hasExactPlainRecordKeys,
+  snapshotClosedArray,
+  snapshotClosedRecord
+} from "../data-boundary/closed-values.ts";
+import type { FindingSummary } from "./code-quality-findings/policy.ts";
+
+/** Parses the final-data shape shared by the three area-based quality Checks. */
+export function parseFindingSummaryData(data: unknown, checkName: string): FindingSummary {
+  const summary = exactFinalDataRecord(data, ["blockingFindingCount", "findingCount"], checkName);
+  const blockingFindingCount = nonNegativeSafeInteger(summary.blockingFindingCount);
+  const findingCount = nonNegativeSafeInteger(summary.findingCount);
+  if (
+    blockingFindingCount === undefined ||
+    findingCount === undefined ||
+    blockingFindingCount > findingCount
+  ) {
+    throw invalidFinalData(checkName);
+  }
+  return Object.freeze({ blockingFindingCount, findingCount });
+}
+
+/** Returns a detached exact record or rejects an unsupported final-data shape. */
+export function exactFinalDataRecord(
+  data: unknown,
+  keys: readonly string[],
+  checkName: string
+): Readonly<Record<string, unknown>> {
+  const record = snapshotClosedRecord(data);
+  if (record === undefined || !hasExactPlainRecordKeys(record, keys)) {
+    throw invalidFinalData(checkName);
+  }
+  return record;
+}
+
+/** Returns a detached closed array or rejects an unsupported final-data shape. */
+export function finalDataArray(data: unknown, checkName: string): readonly unknown[] {
+  const items = snapshotClosedArray(data);
+  if (items === undefined) throw invalidFinalData(checkName);
+  return items;
+}
+
+export function nonNegativeSafeInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+export function invalidFinalData(checkName: string): TypeError {
+  return new TypeError(`${checkName} final data does not match the supported package contract`);
+}

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

@@ -0,0 +1,138 @@
+import type { FunctionMetric } from "./measurement-model.ts";
+import { canonicalJsonBytes } from "../../data-boundary/canonical-data.ts";
+
+export interface FunctionMetricInstance {
+  readonly metric: FunctionMetric;
+  readonly semanticSubject: string;
+}
+
+export interface FunctionMetricAnalysis {
+  readonly instances: readonly FunctionMetricInstance[];
+}
+
+export function analyzeFunctionMetrics(
+  metrics: readonly FunctionMetric[]
+): FunctionMetricAnalysis | undefined {
+  const metricsByIdentity = groupValidMetrics(metrics);
+  if (metricsByIdentity === undefined) {
+    return undefined;
+  }
+  const instances: FunctionMetricInstance[] = [];
+  for (const group of metricsByIdentity.values()) {
+    const sortedGroup = [...group].sort(compareFunctionInstances);
+    instances.push(...createFunctionInstances(sortedGroup));
+  }
+  instances.sort((left, right) => compareText(left.semanticSubject, right.semanticSubject));
+  return Object.freeze({ instances: Object.freeze(instances) });
+}
+
+function groupValidMetrics(
+  metrics: readonly FunctionMetric[]
+): Map<string, FunctionMetric[]> | undefined {
+  const groups = new Map<string, FunctionMetric[]>();
+  for (const metric of metrics) {
+    if (!isValidFunctionMetric(metric)) {
+      return undefined;
+    }
+    const key = functionIdentityKey(metric);
+    const group = groups.get(key) ?? [];
+    group.push(metric);
+    groups.set(key, group);
+  }
+  return groups;
+}
+
+function createFunctionInstances(sortedGroup: readonly FunctionMetric[]): FunctionMetricInstance[] {
+  return sortedGroup.map((metric, index) =>
+    Object.freeze({
+      metric,
+      semanticSubject:
+        isStableFunctionName(metric.name) && sortedGroup.length === 1
+          ? functionSubject(metric)
+          : ambiguousFunctionSubject(metric, index + 1)
+    })
+  );
+}
+
+function isValidFunctionMetric(metric: FunctionMetric): boolean {
+  return (
+    typeof metric.file === "string" &&
+    metric.file.length > 0 &&
+    typeof metric.name === "string" &&
+    metric.name.length > 0 &&
+    hasValidFunctionLocation(metric) &&
+    hasValidFunctionMeasurements(metric)
+  );
+}
+
+function hasValidFunctionLocation(metric: FunctionMetric): boolean {
+  return (
+    Number.isSafeInteger(metric.startLine) &&
+    metric.startLine >= 1 &&
+    Number.isSafeInteger(metric.endLine) &&
+    metric.endLine >= metric.startLine
+  );
+}
+
+function hasValidFunctionMeasurements(metric: FunctionMetric): boolean {
+  const complexity = metric.cyclomaticComplexity.value;
+  return (
+    Number.isSafeInteger(metric.lines) &&
+    metric.lines >= 0 &&
+    Number.isSafeInteger(metric.parameterCount) &&
+    metric.parameterCount >= 0 &&
+    (complexity === null || isValidComplexity(complexity))
+  );
+}
+
+function isValidComplexity(complexity: number): boolean {
+  return Number.isSafeInteger(complexity) && complexity >= 0;
+}
+
+function functionSubject(metric: Pick<FunctionMetric, "file" | "name">): string {
+  const identity = new TextDecoder().decode(
+    canonicalJsonBytes({
+      file: metric.file,
+      name: metric.name
+    })
+  );
+  return `function:${identity}`;
+}
+
+function ambiguousFunctionSubject(
+  metric: Pick<FunctionMetric, "file" | "name">,
+  occurrence: number
+): string {
+  const identity = new TextDecoder().decode(
+    canonicalJsonBytes({
+      file: metric.file,
+      name: metric.name,
+      occurrence
+    })
+  );
+  return `function-instance:${identity}`;
+}
+
+function functionIdentityKey(metric: Pick<FunctionMetric, "file" | "name">): string {
+  return `${metric.file}\u0000${metric.name}`;
+}
+
+function compareFunctionInstances(left: FunctionMetric, right: FunctionMetric): number {
+  return (
+    left.startLine - right.startLine ||
+    left.endLine - right.endLine ||
+    left.lines - right.lines ||
+    (left.cyclomaticComplexity.value ?? -1) - (right.cyclomaticComplexity.value ?? -1) ||
+    left.parameterCount - right.parameterCount
+  );
+}
+
+export function isStableFunctionName(name: string): boolean {
+  return name.trim() !== "" && name !== "(anonymous)" && name !== "unknown";
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}

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

@@ -0,0 +1,55 @@
+import { defineCheck, type TypedCheckWithOptions } from "../../check/check.ts";
+import { executeFunctionMetrics } from "./execution.ts";
+import { parseFunctionMetricsData } from "./final-data.ts";
+import type { FunctionMetricsOptions, ResolvedFunctionMetricsOptions } from "./options.ts";
+import { resolveFunctionMetricsOptions } from "./options-resolution.ts";
+import { validResolvedFunctionMetricsOptions } from "./options-validation.ts";
+
+const FUNCTION_METRICS_CHECK_DEFINITION = {
+  checkId: "function-metrics",
+  displayName: "Function metrics"
+} as const;
+
+/**
+ * 使用可省略的区域、阈值与 finding policy 构造一个完整 function-metrics Check。
+ *
+ * @param options - 省略字段由 package 补齐；显式 files 数组完整替换对应字段的默认数组。
+ * @returns 固定 `function-metrics` identity、完整冻结 options、preflight 与 execution。
+ * @throws {TypeError} input 含未知字段、空 area、非法 finding policy、非法 limit 或空 executable 时抛出。
+ */
+export function functionMetrics(
+  options: FunctionMetricsOptions = {}
+): TypedCheckWithOptions<
+  "function-metrics",
+  ResolvedFunctionMetricsOptions,
+  typeof parseFunctionMetricsData
+> {
+  const resolvedOptions = resolveFunctionMetricsOptions(options);
+  if (resolvedOptions === undefined) {
+    throw new TypeError(
+      "functionMetrics options must use the documented closed policy: a non-empty area map, recognized finding policies, positive safe-integer limits, and a non-empty scanner executable"
+    );
+  }
+  return defineCheck({
+    ...FUNCTION_METRICS_CHECK_DEFINITION,
+    execution: executeFunctionMetrics,
+    parseData: parseFunctionMetricsData,
+    preflight: (preparedOptions) =>
+      validResolvedFunctionMetricsOptions(preparedOptions)
+        ? { status: "success", preparedOptions }
+        : {
+            status: "failure",
+            action: "block",
+            reason: { code: "invalid-options" },
+            messages: [
+              {
+                code: "invalid-options",
+                level: "error",
+                message:
+                  "functionMetrics options are invalid; recreate the Check with functionMetrics(options) or restore its complete resolved options."
+              }
+            ]
+          },
+    options: resolvedOptions
+  });
+}

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

@@ -0,0 +1,263 @@
+import type { CheckExecutionContext, CheckMessage, CheckResult } from "../../check/check.ts";
+import { collectProjectFileSets, requireProjectFileSet } from "../project-files/collection.ts";
+import { partitionProjectFilesByEligibility } from "../project-files/input-eligibility.ts";
+import { settleFindings } from "../code-quality-findings/policy.ts";
+import { analyzeFunctionMetrics } from "./analysis.ts";
+import { measureFunctionMetrics, type FunctionMeasurementResult } from "./measurement.ts";
+import type {
+  FunctionMetricsAreaInput,
+  FunctionMetricsExactInputSet
+} from "./measurement-model.ts";
+import type {
+  ResolvedFunctionMetricsCodeAreaOptions,
+  ResolvedFunctionMetricsOptions
+} from "./options.ts";
+import { validResolvedFunctionMetricsOptions } from "./options-validation.ts";
+import {
+  buildFunctionInputRejectedCandidates,
+  buildFunctionRecordCandidates,
+  type FunctionInputRejectedCandidate,
+  type FunctionRecordCandidate
+} from "./records.ts";
+import { isLizardTarget } from "./target-files.ts";
+import type { FunctionMetricsFinalData } from "./final-data.ts";
+
+/** `function-metrics` whole-Check unavailable outcome 的稳定 reason code。 */
+export type FunctionMetricsUnavailableReasonCode =
+  | "cancelled"
+  | "external-dependency-unavailable"
+  | "external-execution-failed"
+  | "external-result-invalid"
+  | "invalid-options"
+  | "source-unavailable";
+
+/** Default Check callback；一次扫描完整 area exact-input union。 */
+export async function executeFunctionMetrics(
+  context: CheckExecutionContext<ResolvedFunctionMetricsOptions>
+): Promise<CheckResult<FunctionMetricsFinalData>> {
+  if (!validResolvedFunctionMetricsOptions(context.options)) return unavailable("invalid-options");
+  if (context.signal.aborted) return unavailable("cancelled");
+
+  let prepared: PreparedFunctionInputs;
+  try {
+    prepared = prepareFunctionInputs(context.project.root, context.options.codeAreas);
+  } catch {
+    return unavailable("source-unavailable");
+  }
+  if (context.signal.aborted) return unavailable("cancelled");
+  return executePreparedFunctionMetrics(context, prepared);
+}
+
+async function executePreparedFunctionMetrics(
+  context: CheckExecutionContext<ResolvedFunctionMetricsOptions>,
+  prepared: PreparedFunctionInputs
+): Promise<CheckResult<FunctionMetricsFinalData>> {
+  if (prepared.selectedPathCount === 0) {
+    return Object.freeze({ status: "not-applicable", reason: { code: "no-eligible-input" } });
+  }
+  reportInputRejections(context, prepared.rejectedCandidates);
+  if (prepared.exactInput.approvedExactPaths.length === 0) {
+    return settleFunctionFindings([], prepared.rejectedCandidates);
+  }
+  const measurement = await measureFunctionMetrics({
+    dependency: context.options.scanner,
+    input: prepared.exactInput,
+    signal: context.signal
+  });
+  if (measurement.kind !== "complete") {
+    return appendInputRejectedMessage(
+      directMeasurementFailure(measurement),
+      prepared.rejectedCandidates.length
+    );
+  }
+  const analysis = analyzeFunctionMetrics(measurement.metrics);
+  if (analysis === undefined) {
+    return appendInputRejectedMessage(
+      unavailable("external-result-invalid"),
+      prepared.rejectedCandidates.length
+    );
+  }
+  const candidates = buildFunctionRecordCandidates(analysis, prepared.exactInput.areas);
+  if (candidates === undefined) {
+    return appendInputRejectedMessage(
+      unavailable("external-result-invalid"),
+      prepared.rejectedCandidates.length
+    );
+  }
+  for (const candidate of candidates) {
+    context.records.report({ id: candidate.id }, candidate.data);
+  }
+  return settleFunctionFindings(candidates, prepared.rejectedCandidates);
+}
+
+interface PreparedFunctionInputs {
+  readonly exactInput: FunctionMetricsExactInputSet;
+  readonly rejectedCandidates: readonly FunctionInputRejectedCandidate[];
+  readonly selectedPathCount: number;
+}
+
+function prepareFunctionInputs(
+  rootDir: string,
+  codeAreas: ResolvedFunctionMetricsOptions["codeAreas"]
+): PreparedFunctionInputs {
+  const collected = collectAreaInputs(rootDir, codeAreas);
+  return Object.freeze({
+    exactInput: Object.freeze({
+      approvedExactPaths: Object.freeze(
+        uniqueSorted(collected.areas.flatMap((area) => area.approvedExactPaths))
+      ),
+      areas: collected.areas,
+      rootDir
+    }),
+    rejectedCandidates: buildFunctionInputRejectedCandidates(
+      new Map(
+        [...collected.rejectedCodeAreasByPath].map(([path, matchingAreas]) => [
+          path,
+          Object.freeze(matchingAreas)
+        ])
+      )
+    ),
+    selectedPathCount: collected.selectedPaths.size
+  });
+}
+
+interface CollectedFunctionAreaInputs {
+  readonly areas: readonly FunctionMetricsAreaInput[];
+  readonly rejectedCodeAreasByPath: ReadonlyMap<string, readonly string[]>;
+  readonly selectedPaths: ReadonlySet<string>;
+}
+
+function collectAreaInputs(
+  rootDir: string,
+  codeAreas: Readonly<Record<string, ResolvedFunctionMetricsCodeAreaOptions>>
+): CollectedFunctionAreaInputs {
+  const areas: FunctionMetricsAreaInput[] = [];
+  const rejectedCodeAreasByPath = new Map<string, string[]>();
+  const selectedPaths = new Set<string>();
+  const orderedPolicies = Object.entries(codeAreas).sort(([left], [right]) =>
+    compareText(left, right)
+  );
+  const filesByArea = collectProjectFileSets(
+    rootDir,
+    Object.fromEntries(orderedPolicies.map(([areaId, policy]) => [areaId, policy.files]))
+  );
+  for (const [codeArea, policy] of orderedPolicies) {
+    const selectedForArea = requireProjectFileSet(filesByArea, codeArea);
+    for (const path of selectedForArea) selectedPaths.add(path);
+    const partition = partitionProjectFilesByEligibility(selectedForArea, isLizardTarget);
+    for (const path of partition.rejectedPaths) {
+      const matchingAreas = rejectedCodeAreasByPath.get(path) ?? [];
+      matchingAreas.push(codeArea);
+      rejectedCodeAreasByPath.set(path, matchingAreas);
+    }
+    if (partition.acceptedPaths.length === 0) continue;
+    areas.push(
+      Object.freeze({
+        approvedExactPaths: partition.acceptedPaths,
+        codeArea,
+        findingPolicy: policy.findingPolicy,
+        limits: policy.limits
+      })
+    );
+  }
+  return Object.freeze({
+    areas: Object.freeze(areas),
+    rejectedCodeAreasByPath,
+    selectedPaths
+  });
+}
+
+function reportInputRejections(
+  context: CheckExecutionContext<ResolvedFunctionMetricsOptions>,
+  candidates: readonly FunctionInputRejectedCandidate[]
+): void {
+  for (const candidate of candidates) {
+    context.records.report({ id: candidate.id }, candidate.data);
+  }
+}
+
+function settleFunctionFindings(
+  metricCandidates: readonly FunctionRecordCandidate[],
+  rejectedCandidates: readonly FunctionInputRejectedCandidate[]
+): CheckResult<FunctionMetricsFinalData> {
+  const settlement = settleFindings([
+    ...metricCandidates.map((candidate) => ({
+      actionable: true,
+      blocking: candidate.data.blocking
+    })),
+    ...rejectedCandidates.map(() => ({ actionable: false, blocking: false }))
+  ]);
+  return appendInputRejectedMessage(settlement, rejectedCandidates.length);
+}
+
+function appendInputRejectedMessage(
+  result: CheckResult<FunctionMetricsFinalData>,
+  rejectedInputCount: number
+): CheckResult<FunctionMetricsFinalData> {
+  if (rejectedInputCount === 0) return result;
+  const message: CheckMessage = Object.freeze({
+    code: "input-rejected",
+    level: "warning",
+    message: `${rejectedInputCount} selected functionMetrics input file(s) were rejected because their file type is unsupported; inspect this Check's Records and narrow files.include/exclude.`
+  });
+  return Object.freeze({
+    ...result,
+    messages: Object.freeze([...(result.messages ?? []), message])
+  });
+}
+
+function directMeasurementFailure(
+  measurement: Exclude<FunctionMeasurementResult, { kind: "complete" }>
+): CheckResult<FunctionMetricsFinalData> {
+  switch (measurement.kind) {
+    case "cancelled":
+      return unavailable("cancelled");
+    case "execution-failed":
+      return unavailable("external-execution-failed");
+    case "invalid-result":
+      return unavailable("external-result-invalid");
+    case "unavailable":
+      return unavailable("external-dependency-unavailable");
+  }
+  const exhaustiveMeasurement: never = measurement;
+  return exhaustiveMeasurement;
+}
+
+function unavailable(
+  code: FunctionMetricsUnavailableReasonCode
+): CheckResult<FunctionMetricsFinalData> {
+  return Object.freeze({
+    status: "unavailable",
+    reason: { code },
+    messages: Object.freeze([
+      Object.freeze({ code, level: "error" as const, message: unavailableMessage(code) })
+    ])
+  });
+}
+
+function unavailableMessage(code: FunctionMetricsUnavailableReasonCode): string {
+  switch (code) {
+    case "invalid-options":
+      return "functionMetrics options are invalid; recreate the Check with functionMetrics(options) or restore its complete resolved options.";
+    case "cancelled":
+      return "Function metrics was cancelled before it could form a complete result; inspect the caller's cancellation reason and retry if appropriate.";
+    case "source-unavailable":
+      return "Function metrics could not collect its configured project files; check the project root, file permissions, and selected file source.";
+    case "external-dependency-unavailable":
+      return "The configured Lizard command is unavailable or incompatible; install Lizard 1.23.0 or configure a compatible executable.";
+    case "external-execution-failed":
+      return "Lizard did not complete successfully; run the configured command directly and inspect its environment.";
+    case "external-result-invalid":
+      return "Lizard output could not form a trusted complete result; check the executable version and CSV compatibility.";
+  }
+}
+
+function uniqueSorted(values: readonly string[]): string[] {
+  return [...new Set(values)].sort(compareText);
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}

package/src/package-checks/function-metrics/final-data.ts

@@ -0,0 +1,10 @@
+import type { FindingSummary } from "../code-quality-findings/policy.ts";
+import { parseFindingSummaryData } from "../final-data-parsing.ts";
+
+/** `function-metrics` 在 passed/failed outcome 中发布的主数据。 */
+export type FunctionMetricsFinalData = FindingSummary;
+
+/** 验证并脱离一份 `function-metrics` canonical final-data object。 */
+export function parseFunctionMetricsData(data: unknown): FunctionMetricsFinalData {
+  return parseFindingSummaryData(data, "functionMetrics");
+}

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

@@ -0,0 +1,90 @@
+import { errorMessage } from "../../host-environment/error-message.ts";
+import { runProcess } from "../../host-environment/process/command.ts";
+import type { ResolvedFunctionMetricsScannerOptions } from "../options.ts";
+
+type LizardAvailability = Readonly<
+  | {
+      readonly available: true;
+      readonly version: string;
+    }
+  | {
+      readonly available: false;
+      readonly error: string;
+      readonly reason: "contract-error" | "execution-error" | "tool-unavailable";
+    }
+>;
+
+interface UnavailableLizardInput {
+  readonly error: string;
+  readonly reason: Extract<LizardAvailability, { available: false }>["reason"];
+}
+
+type ToolCommandResult = Awaited<ReturnType<typeof runProcess>>;
+
+export async function checkLizard(
+  rootDir: string,
+  dependency: ResolvedFunctionMetricsScannerOptions
+): Promise<LizardAvailability> {
+  try {
+    const result = await runProcess({
+      args: ["--version"],
+      command: dependency.executable,
+      cwd: rootDir
+    });
+    return availabilityFromVersionResult(result);
+  } catch (error: unknown) {
+    return unavailableLizard({
+      error: `lizard version error: ${errorMessage(error)}`,
+      reason: "execution-error"
+    });
+  }
+}
+
+function availabilityFromVersionResult(result: ToolCommandResult): LizardAvailability {
+  if (result.signal !== null) {
+    const output = commandOutput(result);
+    return unavailableLizard({
+      error: `lizard --version failed, signal ${result.signal}${output ? `: ${output}` : ""}`,
+      reason: "execution-error"
+    });
+  }
+  if (result.error) return processErrorAvailability(result.error);
+  const output = commandOutput(result);
+  if (result.status !== 0) {
+    return unavailableLizard({
+      error: `lizard --version failed, ${processTermination(result)}${output ? `: ${output}` : ""}`,
+      reason: "execution-error"
+    });
+  }
+  if (output === "") {
+    return unavailableLizard({
+      error: "lizard --version returned empty output",
+      reason: "contract-error"
+    });
+  }
+  return Object.freeze({ available: true, version: output });
+}
+
+function processErrorAvailability(error: Error): LizardAvailability {
+  const isMissingTool = Object.hasOwn(error, "code") && Reflect.get(error, "code") === "ENOENT";
+  return unavailableLizard({
+    error: isMissingTool
+      ? `lizard command unavailable: ${error.message}`
+      : `lizard version error: ${error.message}`,
+    reason: isMissingTool ? "tool-unavailable" : "execution-error"
+  });
+}
+
+function unavailableLizard({ error, reason }: UnavailableLizardInput): LizardAvailability {
+  return Object.freeze({ available: false, error, reason });
+}
+
+function commandOutput(result: ToolCommandResult): string {
+  return (result.stdout || "").trim() || (result.stderr || "").trim();
+}
+
+function processTermination(result: ToolCommandResult): string {
+  return typeof result.status === "number"
+    ? `exit ${result.status}`
+    : `signal ${result.signal || "unknown"}`;
+}

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

@@ -0,0 +1,20 @@
+import { parse } from "csv-parse/sync";
+
+export function parseCsvRows(csv: string): string[][] {
+  const records: unknown = parse(csv, {
+    bom: true,
+    relax_column_count: true,
+    skip_empty_lines: true,
+    trim: true
+  });
+
+  if (!Array.isArray(records) || !records.every(isStringRow)) {
+    throw new Error("CSV parser returned non-string rows");
+  }
+
+  return records;
+}
+
+function isStringRow(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}