@zxyycom/vibe-check 0.0.1 → 0.0.2

package/src/package-checks/function-metrics/analyzer-worker.ts

@@ -0,0 +1,31 @@
+import { analyzeFunctionMetricsSources } from "./analyzer-adapter.ts";
+import { parentPort } from "node:worker_threads";
+import type {
+  FunctionMetricsAnalysisWorkerRequest,
+  FunctionMetricsAnalysisWorkerResponse
+} from "./analyzer-worker-contract.ts";
+
+if (parentPort === null) throw new Error("functionMetrics analyzer requires a parent Worker port");
+const workerPort = parentPort;
+
+workerPort.once("message", (value: unknown): void => {
+  workerPort.postMessage(analyzeWorkerRequest(value));
+  workerPort.close();
+});
+
+function analyzeWorkerRequest(value: unknown): FunctionMetricsAnalysisWorkerResponse {
+  if (!isWorkerRequest(value)) return Object.freeze({ kind: "analysis-failed" });
+  return analyzeFunctionMetricsSources(value);
+}
+
+function isWorkerRequest(value: unknown): value is FunctionMetricsAnalysisWorkerRequest {
+  return isRecord(value) && Array.isArray(value.files) && value.files.every(isWorkerFile);
+}
+
+function isWorkerFile(value: unknown): boolean {
+  return isRecord(value) && typeof value.path === "string" && typeof value.source === "string";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

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

@@ -15,7 +15,7 @@ const FUNCTION_METRICS_CHECK_DEFINITION = {
  *
  * @param options - 省略字段由 package 补齐；显式 files 数组完整替换对应字段的默认数组。
  * @returns 固定 `function-metrics` identity、完整冻结 options、preflight 与 execution。
- * @throws {TypeError} input 含未知字段、空 area、非法 finding policy、非法 limit 或空 executable 时抛出。
+ * @throws {TypeError} input 含未知字段、空 area、非法 finding policy/waiver 或非法 limit 时抛出。
  */
 export function functionMetrics(
   options: FunctionMetricsOptions = {}
@@ -27,7 +27,7 @@ export function functionMetrics(
   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"
+      "functionMetrics options must use the documented closed policy: a non-empty area map, recognized finding policies and waivers, and positive safe-integer limits"
     );
   }
   return defineCheck({

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

@@ -1,14 +1,29 @@
 import type { CheckExecutionContext, CheckMessage, CheckResult } from "../../check/check.ts";
+import {
+  reconcileFindingWaivers,
+  type FindingWaiverReconciliation
+} from "../../finding-waivers/reconciliation.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 {
+  reportFindingWaiverAudits,
+  reportReconciledCodeQualityFindingRecords
+} from "../code-quality-findings/finding-waiver-evidence.ts";
+import { appendCheckMessages } from "../../check/finding-presentation.ts";
+import { functionFindingMessages, functionWaiverMessages } from "./finding-messages.ts";
 import { analyzeFunctionMetrics } from "./analysis.ts";
-import { measureFunctionMetrics, type FunctionMeasurementResult } from "./measurement.ts";
+import {
+  measureFunctionMetrics,
+  type FunctionMeasurementDependencies,
+  type FunctionMeasurementResult
+} from "./measurement.ts";
 import type {
   FunctionMetricsAreaInput,
   FunctionMetricsExactInputSet
 } from "./measurement-model.ts";
 import type {
+  FunctionMetricsFindingWaiver,
   ResolvedFunctionMetricsCodeAreaOptions,
   ResolvedFunctionMetricsOptions
 } from "./options.ts";
@@ -16,24 +31,28 @@ import { validResolvedFunctionMetricsOptions } from "./options-validation.ts";
 import {
   buildFunctionInputRejectedCandidates,
   buildFunctionRecordCandidates,
+  functionMetricsFindingIdentity,
+  functionMetricsWaiverAuditRecord,
   type FunctionInputRejectedCandidate,
   type FunctionRecordCandidate
 } from "./records.ts";
-import { isLizardTarget } from "./target-files.ts";
+import { isFunctionMetricsTarget } from "./target-files.ts";
 import type { FunctionMetricsFinalData } from "./final-data.ts";
 
 /** `function-metrics` whole-Check unavailable outcome 的稳定 reason code。 */
 export type FunctionMetricsUnavailableReasonCode =
+  | "analysis-failed"
   | "cancelled"
-  | "external-dependency-unavailable"
-  | "external-execution-failed"
-  | "external-result-invalid"
   | "invalid-options"
+  | "resource-limit-exceeded"
   | "source-unavailable";
 
 /** Default Check callback；一次扫描完整 area exact-input union。 */
 export async function executeFunctionMetrics(
-  context: CheckExecutionContext<ResolvedFunctionMetricsOptions>
+  context: CheckExecutionContext<ResolvedFunctionMetricsOptions>,
+  dependencies: Readonly<{
+    readonly measurement?: Partial<FunctionMeasurementDependencies>;
+  }> = {}
 ): Promise<CheckResult<FunctionMetricsFinalData>> {
   if (!validResolvedFunctionMetricsOptions(context.options)) return unavailable("invalid-options");
   if (context.signal.aborted) return unavailable("cancelled");
@@ -45,25 +64,32 @@ export async function executeFunctionMetrics(
     return unavailable("source-unavailable");
   }
   if (context.signal.aborted) return unavailable("cancelled");
-  return executePreparedFunctionMetrics(context, prepared);
+  return executePreparedFunctionMetrics(context, prepared, dependencies);
 }
 
 async function executePreparedFunctionMetrics(
   context: CheckExecutionContext<ResolvedFunctionMetricsOptions>,
-  prepared: PreparedFunctionInputs
+  prepared: PreparedFunctionInputs,
+  dependencies: Readonly<{
+    readonly measurement?: Partial<FunctionMeasurementDependencies>;
+  }>
 ): Promise<CheckResult<FunctionMetricsFinalData>> {
   if (prepared.selectedPathCount === 0) {
-    return Object.freeze({ status: "not-applicable", reason: { code: "no-eligible-input" } });
+    return noEligibleFunctionInputResult(context);
   }
   reportInputRejections(context, prepared.rejectedCandidates);
   if (prepared.exactInput.approvedExactPaths.length === 0) {
-    return settleFunctionFindings([], prepared.rejectedCandidates);
+    const reconciliation = reconcileFunctionMetricWaivers([], context.options.findingWaivers);
+    reportFindingWaiverAudits(context, reconciliation, functionMetricsWaiverAuditRecord);
+    return settleFunctionFindings(reconciliation, prepared.rejectedCandidates);
   }
-  const measurement = await measureFunctionMetrics({
-    dependency: context.options.scanner,
-    input: prepared.exactInput,
-    signal: context.signal
-  });
+  const measurement = await measureFunctionMetrics(
+    {
+      input: prepared.exactInput,
+      signal: context.signal
+    },
+    dependencies.measurement
+  );
   if (measurement.kind !== "complete") {
     return appendInputRejectedMessage(
       directMeasurementFailure(measurement),
@@ -73,21 +99,43 @@ async function executePreparedFunctionMetrics(
   const analysis = analyzeFunctionMetrics(measurement.metrics);
   if (analysis === undefined) {
     return appendInputRejectedMessage(
-      unavailable("external-result-invalid"),
+      unavailable("analysis-failed"),
       prepared.rejectedCandidates.length
     );
   }
   const candidates = buildFunctionRecordCandidates(analysis, prepared.exactInput.areas);
   if (candidates === undefined) {
     return appendInputRejectedMessage(
-      unavailable("external-result-invalid"),
+      unavailable("analysis-failed"),
       prepared.rejectedCandidates.length
     );
   }
-  for (const candidate of candidates) {
-    context.records.report({ id: candidate.id }, candidate.data);
-  }
-  return settleFunctionFindings(candidates, prepared.rejectedCandidates);
+  const reconciliation = reconcileFunctionMetricWaivers(candidates, context.options.findingWaivers);
+  reportReconciledCodeQualityFindingRecords(context, reconciliation);
+  reportFindingWaiverAudits(context, reconciliation, functionMetricsWaiverAuditRecord);
+  return settleFunctionFindings(reconciliation, prepared.rejectedCandidates);
+}
+
+function noEligibleFunctionInputResult(
+  context: CheckExecutionContext<ResolvedFunctionMetricsOptions>
+): CheckResult<FunctionMetricsFinalData> {
+  const reconciliation = reconcileFunctionMetricWaivers([], context.options.findingWaivers);
+  reportFindingWaiverAudits(context, reconciliation, functionMetricsWaiverAuditRecord);
+  return appendCheckMessages(
+    Object.freeze({ status: "not-applicable", reason: { code: "no-eligible-input" } }),
+    functionWaiverMessages(reconciliation)
+  );
+}
+
+function reconcileFunctionMetricWaivers(
+  candidates: readonly FunctionRecordCandidate[],
+  waivers: readonly FunctionMetricsFindingWaiver[]
+): FindingWaiverReconciliation<FunctionRecordCandidate> {
+  return reconcileFindingWaivers({
+    findings: candidates,
+    identify: functionMetricsFindingIdentity,
+    waivers
+  });
 }
 
 interface PreparedFunctionInputs {
@@ -144,7 +192,7 @@ function collectAreaInputs(
   for (const [codeArea, policy] of orderedPolicies) {
     const selectedForArea = requireProjectFileSet(filesByArea, codeArea);
     for (const path of selectedForArea) selectedPaths.add(path);
-    const partition = partitionProjectFilesByEligibility(selectedForArea, isLizardTarget);
+    const partition = partitionProjectFilesByEligibility(selectedForArea, isFunctionMetricsTarget);
     for (const path of partition.rejectedPaths) {
       const matchingAreas = rejectedCodeAreasByPath.get(path) ?? [];
       matchingAreas.push(codeArea);
@@ -177,17 +225,26 @@ function reportInputRejections(
 }
 
 function settleFunctionFindings(
-  metricCandidates: readonly FunctionRecordCandidate[],
+  reconciliation: FindingWaiverReconciliation<FunctionRecordCandidate>,
   rejectedCandidates: readonly FunctionInputRejectedCandidate[]
 ): CheckResult<FunctionMetricsFinalData> {
   const settlement = settleFindings([
-    ...metricCandidates.map((candidate) => ({
-      actionable: true,
-      blocking: candidate.data.blocking
+    ...reconciliation.findings.map((finding) => ({
+      actionable: finding.disposition !== "waived",
+      blocking: finding.finding.data.blocking
     })),
     ...rejectedCandidates.map(() => ({ actionable: false, blocking: false }))
   ]);
-  return appendInputRejectedMessage(settlement, rejectedCandidates.length);
+  const actionableMetricCandidates = reconciliation.findings
+    .filter(({ disposition }) => disposition !== "waived")
+    .map(({ finding }) => finding);
+  return appendCheckMessages(
+    appendCheckMessages(
+      appendInputRejectedMessage(settlement, rejectedCandidates.length),
+      functionFindingMessages([...actionableMetricCandidates, ...rejectedCandidates])
+    ),
+    functionWaiverMessages(reconciliation)
+  );
 }
 
 function appendInputRejectedMessage(
@@ -212,12 +269,12 @@ function directMeasurementFailure(
   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");
+    case "analysis-failed":
+      return unavailable("analysis-failed");
+    case "resource-limit-exceeded":
+      return unavailable("resource-limit-exceeded");
+    case "source-unavailable":
+      return unavailable("source-unavailable");
   }
   const exhaustiveMeasurement: never = measurement;
   return exhaustiveMeasurement;
@@ -243,12 +300,10 @@ function unavailableMessage(code: FunctionMetricsUnavailableReasonCode): string
       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.";
+    case "analysis-failed":
+      return "Function metrics analysis did not produce a complete trusted result; inspect the selected source and retry after correcting it.";
+    case "resource-limit-exceeded":
+      return "Function metrics input exceeds the per-file or aggregate analysis resource limit; narrow the selected files or reduce their size.";
   }
 }
 

package/src/package-checks/function-metrics/finding-messages.ts

@@ -0,0 +1,95 @@
+import type { CheckMessage } from "../../check/check.ts";
+import { presentCheckFindings } from "../../check/finding-presentation.ts";
+import type {
+  FindingWaiverAudit,
+  FindingWaiverReconciliation
+} from "../../finding-waivers/reconciliation.ts";
+import {
+  functionMetricsWaiverIdentity,
+  type FunctionInputRejectedCandidate,
+  type FunctionMetricsFindingRecordData,
+  type FunctionRecordCandidate
+} from "./records.ts";
+
+const PRESENTED_FINDING_LIMIT = 10;
+const PRESENTED_COMPLEXITY_CONTRIBUTOR_LIMIT = 8;
+
+type FunctionFindingCandidate = FunctionRecordCandidate | FunctionInputRejectedCandidate;
+
+/** Projects metric and rejected-input Records into bounded terminal summaries. */
+export function functionFindingMessages(
+  findings: readonly FunctionFindingCandidate[]
+): readonly CheckMessage[] {
+  return presentCheckFindings({
+    findings,
+    limit: PRESENTED_FINDING_LIMIT,
+    message: ({ data }) => {
+      if ("kind" in data) {
+        return Object.freeze({
+          code: "finding-detail",
+          level: "warning" as const,
+          message: `${data.path}: selected input is not supported by function metrics (areas: ${data.codeAreas.join(", ")}).`
+        });
+      }
+      return Object.freeze({
+        code: "finding-detail",
+        level: data.blocking ? ("error" as const) : ("warning" as const),
+        message: `${data.path}:${data.startLine} ${data.functionName}: ${data.metric} ${data.value} exceeds the ${data.limit} limit (areas: ${data.codeAreas.join(", ")}).${complexityContributorMessage(data)}`
+      });
+    },
+    omittedMessage: ({ omittedCount, omittedFindings }) =>
+      Object.freeze({
+        code: "findings-omitted",
+        level: omittedFindings.some(({ data }) => !("kind" in data) && data.blocking)
+          ? ("error" as const)
+          : ("warning" as const),
+        message: `${omittedCount} additional function metric finding(s) were not shown; inspect this Check's Records for the complete set.`
+      })
+  });
+}
+
+function complexityContributorMessage(data: FunctionMetricsFindingRecordData): string {
+  if (data.metric !== "cyclomatic-complexity" || data.complexityContributors === undefined)
+    return "";
+  const shown = data.complexityContributors.slice(0, PRESENTED_COMPLEXITY_CONTRIBUTOR_LIMIT);
+  if (shown.length === 0) return "";
+  const displayedContributors = shown
+    .map((contributor) => `${contributor.token} at line ${contributor.line}`)
+    .join(", ");
+  const omittedCount = data.complexityContributors.length - shown.length;
+  return omittedCount === 0
+    ? ` Complexity contributors: ${displayedContributors}.`
+    : ` Complexity contributors: ${displayedContributors}; ${omittedCount} additional contributor(s) are in this finding Record.`;
+}
+
+/** 将每项 function-metrics waiver audit 投影为可行动的 terminal message。 */
+export function functionWaiverMessages(
+  reconciliation: FindingWaiverReconciliation<FunctionRecordCandidate>
+): readonly CheckMessage[] {
+  return Object.freeze(reconciliation.waiverAudits.map(functionWaiverMessage));
+}
+
+function functionWaiverMessage(audit: FindingWaiverAudit): CheckMessage {
+  const identity = functionMetricsWaiverIdentity(audit.waiver);
+  const subject = `${identity.path}:${identity.startLine} ${identity.functionName} ${identity.metric}`;
+  switch (audit.status) {
+    case "applied":
+      return Object.freeze({
+        code: "finding-waived",
+        level: "info",
+        message: `Function metric finding for ${subject} was waived: ${audit.waiver.reason}`
+      });
+    case "unused":
+      return Object.freeze({
+        code: "unused-finding-waiver",
+        level: "warning",
+        message: `Configured function-metrics finding waiver for ${subject} matched no finding; remove it or update its identity. Reason: ${audit.waiver.reason}`
+      });
+    case "overmatched":
+      return Object.freeze({
+        code: "overmatched-finding-waiver",
+        level: "warning",
+        message: `Configured function-metrics finding waiver for ${subject} matched ${audit.matchCount} findings and was not applied; narrow its identity. Reason: ${audit.waiver.reason}`
+      });
+  }
+}

package/src/package-checks/function-metrics/finding-waiver-identity.ts

@@ -0,0 +1,36 @@
+import { snapshotClosedPolicyRecord } from "../../data-boundary/closed-values.ts";
+import { isNonEmptyString, isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
+import { isNormalizedProjectRelativePath } from "../host-environment/path.ts";
+import type { FunctionMetricsFindingIdentity, FunctionMetricsFindingMetric } from "./options.ts";
+
+export function resolveFunctionMetricsFindingIdentity(
+  value: unknown
+): FunctionMetricsFindingIdentity | undefined {
+  const identity = snapshotClosedPolicyRecord(value, {
+    required: ["functionName", "metric", "path", "startLine"]
+  });
+  if (
+    identity === undefined ||
+    !isNonEmptyString(identity.functionName) ||
+    !isFunctionMetricsFindingMetric(identity.metric) ||
+    !isNormalizedProjectRelativePath(identity.path) ||
+    !isPositiveSafeInteger(identity.startLine)
+  ) {
+    return undefined;
+  }
+  return Object.freeze({
+    functionName: identity.functionName,
+    metric: identity.metric,
+    path: identity.path,
+    startLine: identity.startLine
+  });
+}
+
+function isFunctionMetricsFindingMetric(value: unknown): value is FunctionMetricsFindingMetric {
+  return (
+    value === "cyclomatic-complexity" ||
+    value === "function-code-density" ||
+    value === "nesting-depth" ||
+    value === "parameter-count"
+  );
+}

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

@@ -2,16 +2,30 @@ import type { FindingPolicy } from "../code-quality-findings/policy.ts";
 import type { ResolvedFunctionMetricsLimits } from "./options.ts";
 
 export interface MetricValue {
-  readonly source: "lizard";
+  readonly source: "typescript-analyzer";
   readonly value: number | null;
 }
 
+/** One CCN-contributing token and its one-based source line. */
+export interface ComplexityContributor {
+  readonly line: number;
+  readonly token: string;
+}
+
+/** A nesting-depth value is complete for every function admitted to this Product metric. */
+export interface NestingDepthMetricValue {
+  readonly source: "typescript-analyzer";
+  readonly value: number;
+}
+
 export interface FunctionMetric {
+  readonly complexityContributors: readonly ComplexityContributor[];
   readonly cyclomaticComplexity: MetricValue;
   readonly endLine: number;
   readonly file: string;
   readonly lines: number;
   readonly name: string;
+  readonly nestingDepth: NestingDepthMetricValue;
   readonly parameterCount: number;
   readonly startLine: number;
 }