@zxyycom/vibe-check 0.0.1

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

@@ -0,0 +1,84 @@
+import type {
+  ProjectFileSelection,
+  ProjectFileSelectionOptions
+} from "../project-files/configuration.ts";
+import type { FindingPolicy } from "../code-quality-findings/policy.ts";
+
+/** `functionMetrics` 构造函数可省略的文件选择策略。 */
+export type FunctionMetricsFileOptions = ProjectFileSelectionOptions;
+
+/** `functionMetrics` 构造函数可省略的函数指标上限。 */
+export interface FunctionMetricsLimitOptions {
+  readonly codeLines?: Readonly<{
+    /** 省略时为 `60`；函数 NLOC 超过此值时产生 finding。 */
+    readonly maximum?: number;
+    readonly lowComplexityAllowance?: Readonly<{
+      /** 省略时为 `6`；复杂度小于此值时可使用较高 NLOC 上限。 */
+      readonly cyclomaticComplexityBelow?: number;
+      /** 省略时为 `180`；不得小于普通代码行上限。 */
+      readonly maximum?: number;
+    }>;
+  }>;
+  readonly cyclomaticComplexity?: Readonly<{
+    /** 省略时为 `12`。 */
+    readonly maximum?: number;
+  }>;
+  readonly parameters?: Readonly<{
+    /** 省略时为 `6`。 */
+    readonly maximum?: number;
+  }>;
+}
+
+/** 可独立选择文件、指标上限和 finding policy 的 function-metrics 区域。 */
+export interface FunctionMetricsCodeAreaOptions {
+  /** 显式区域必须声明本字段；其中各子字段可省略并使用 package 默认值。 */
+  readonly files: FunctionMetricsFileOptions;
+  /** 省略时继承顶层 `findingPolicy`。 */
+  readonly findingPolicy?: FindingPolicy;
+  /** 省略的嵌套上限使用 package 默认值。 */
+  readonly limits?: FunctionMetricsLimitOptions;
+}
+
+/** `functionMetrics` 构造函数可省略的 Lizard 可执行文件策略。 */
+export interface FunctionMetricsScannerOptions {
+  /** 省略时为 `lizard`；显式命令必须直接接受 adapter 拥有的 Lizard 参数。 */
+  readonly executable?: string;
+}
+
+/** `functionMetrics(options?)` 接受并补齐默认值的公开策略。 */
+export interface FunctionMetricsOptions {
+  /** 省略时建立默认 `project` 区域；显式映射必须非空，且每个区域必须声明 `files`。 */
+  readonly codeAreas?: Readonly<Record<string, FunctionMetricsCodeAreaOptions>>;
+  /** 省略时为 `non-blocking`；区域可局部覆盖。 */
+  readonly findingPolicy?: FindingPolicy;
+  /** 省略时使用 PATH 中的 `lizard`。 */
+  readonly scanner?: FunctionMetricsScannerOptions;
+}
+
+/** 构造函数生成并由 Check preflight/execution 消费的完整 options。 */
+export interface ResolvedFunctionMetricsOptions {
+  readonly codeAreas: Readonly<Record<string, ResolvedFunctionMetricsCodeAreaOptions>>;
+  readonly scanner: ResolvedFunctionMetricsScannerOptions;
+}
+
+export interface ResolvedFunctionMetricsCodeAreaOptions {
+  readonly files: ProjectFileSelection;
+  readonly findingPolicy: FindingPolicy;
+  readonly limits: ResolvedFunctionMetricsLimits;
+}
+
+export interface ResolvedFunctionMetricsLimits {
+  readonly codeLines: Readonly<{
+    readonly maximum: number;
+    readonly lowComplexityAllowance: Readonly<{
+      readonly cyclomaticComplexityBelow: number;
+      readonly maximum: number;
+    }>;
+  }>;
+  readonly cyclomaticComplexity: Readonly<{ readonly maximum: number }>;
+  readonly parameters: Readonly<{ readonly maximum: number }>;
+}
+
+export interface ResolvedFunctionMetricsScannerOptions {
+  readonly executable: string;
+}

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

@@ -0,0 +1,254 @@
+import {
+  isStableFunctionName,
+  type FunctionMetricAnalysis,
+  type FunctionMetricInstance
+} from "./analysis.ts";
+import { isBlockingFinding } from "../code-quality-findings/policy.ts";
+import type { FunctionMetric, FunctionMetricsAreaInput } from "./measurement-model.ts";
+import type { ResolvedFunctionMetricsLimits } from "./options.ts";
+
+type FunctionMetricName = "cyclomatic-complexity" | "function-code-density" | "parameter-count";
+const INPUT_REJECTED_RECORD_ID_PREFIX = "/input-rejected/";
+
+/** 一条超出函数 metric 上限的 supplemental Record data。 */
+export type FunctionMetricsFindingRecordData = Readonly<{
+  readonly blocking: boolean;
+  readonly codeAreas: readonly string[];
+  readonly functionName: string;
+  readonly limit: number;
+  readonly metric: FunctionMetricName;
+  readonly path: string;
+  readonly startLine: number;
+  readonly value: number;
+}>;
+
+/** 一条已被 files policy 选中、但不受 functionMetrics 支持的输入 Finding。 */
+export type FunctionMetricsInputRejectedRecordData = Readonly<{
+  readonly blocking: false;
+  readonly codeAreas: readonly string[];
+  readonly kind: "input-rejected";
+  readonly path: string;
+  readonly reason: "unsupported-file-type";
+}>;
+
+/** functionMetrics 发布的 metric 或 input-rejection Record data。 */
+export type FunctionMetricsRecordData =
+  | FunctionMetricsFindingRecordData
+  | FunctionMetricsInputRejectedRecordData;
+
+export interface FunctionRecordCandidate {
+  readonly data: FunctionMetricsFindingRecordData;
+  readonly id: string;
+}
+
+export interface FunctionInputRejectedCandidate {
+  readonly data: FunctionMetricsInputRejectedRecordData;
+  readonly id: string;
+}
+
+/** 为每个 rejected path 构造一条 area-aware、固定 non-blocking 的 Finding。 */
+export function buildFunctionInputRejectedCandidates(
+  codeAreasByPath: ReadonlyMap<string, readonly string[]>
+): readonly FunctionInputRejectedCandidate[] {
+  return Object.freeze(
+    [...codeAreasByPath]
+      .sort(([left], [right]) => compareText(left, right))
+      .map(([path, codeAreas]) =>
+        Object.freeze({
+          data: Object.freeze({
+            blocking: false as const,
+            codeAreas: Object.freeze(uniqueSorted(codeAreas)),
+            kind: "input-rejected" as const,
+            path,
+            reason: "unsupported-file-type" as const
+          }),
+          id: `${INPUT_REJECTED_RECORD_ID_PREFIX}${path}`
+        })
+      )
+  );
+}
+
+type MatchingFunctionMetricAreas = readonly [
+  FunctionMetricsAreaInput,
+  ...FunctionMetricsAreaInput[]
+];
+
+interface FunctionPolicyContext {
+  readonly blocking: boolean;
+  readonly codeAreas: readonly string[];
+  readonly functionName: string;
+}
+
+interface FunctionMetricEvaluation {
+  readonly blocking: boolean;
+  readonly codeAreas: readonly string[];
+  readonly functionName: string;
+  readonly limit: number;
+  readonly metric: FunctionMetricName;
+  readonly path: string;
+  readonly startLine: number;
+  readonly subject: string;
+  readonly value: number;
+}
+
+/** 为每个超过 matching-area 最严格阈值的 metric 构造 supplemental fact。 */
+export function buildFunctionRecordCandidates(
+  analysis: FunctionMetricAnalysis,
+  areas: readonly FunctionMetricsAreaInput[]
+): readonly FunctionRecordCandidate[] | undefined {
+  const areasByPath = indexAreasByPath(areas);
+  const candidates: FunctionRecordCandidate[] = [];
+  for (const instance of analysis.instances) {
+    const [firstArea, ...remainingAreas] = areasByPath.get(instance.metric.file) ?? [];
+    if (firstArea === undefined) return undefined;
+    const matchingAreas = [firstArea, ...remainingAreas] as const;
+    const policyContext = resolveFunctionPolicyContext(instance, matchingAreas);
+    for (const evaluation of metricEvaluations(instance, policyContext, matchingAreas)) {
+      appendFindingCandidate(candidates, evaluation);
+    }
+  }
+  candidates.sort((left, right) => compareText(left.id, right.id));
+  return Object.freeze(candidates);
+}
+
+function indexAreasByPath(
+  areas: readonly FunctionMetricsAreaInput[]
+): ReadonlyMap<string, readonly FunctionMetricsAreaInput[]> {
+  const mutableAreas = new Map<string, FunctionMetricsAreaInput[]>();
+  for (const area of areas) {
+    for (const path of area.approvedExactPaths) {
+      const matchingAreas = mutableAreas.get(path) ?? [];
+      matchingAreas.push(area);
+      mutableAreas.set(path, matchingAreas);
+    }
+  }
+  return new Map(
+    Array.from(mutableAreas, ([path, matchingAreas]) => [path, Object.freeze(matchingAreas)])
+  );
+}
+
+function resolveFunctionPolicyContext(
+  instance: FunctionMetricInstance,
+  matchingAreas: MatchingFunctionMetricAreas
+): Readonly<FunctionPolicyContext> {
+  return Object.freeze({
+    blocking: isBlockingFinding(matchingAreas.map((area) => area.findingPolicy)),
+    codeAreas: Object.freeze(uniqueSorted(matchingAreas.map((area) => area.codeArea))),
+    functionName: isStableFunctionName(instance.metric.name) ? instance.metric.name : "<anonymous>"
+  });
+}
+
+function metricEvaluations(
+  instance: FunctionMetricInstance,
+  policyContext: FunctionPolicyContext,
+  matchingAreas: MatchingFunctionMetricAreas
+): FunctionMetricEvaluation[] {
+  const evaluations: FunctionMetricEvaluation[] = [];
+  const complexityEvaluation = complexityMetricEvaluation(instance, policyContext, matchingAreas);
+  if (complexityEvaluation !== null) evaluations.push(complexityEvaluation);
+  evaluations.push(
+    codeLinesMetricEvaluation(instance, policyContext, matchingAreas),
+    parameterMetricEvaluation(instance, policyContext, matchingAreas)
+  );
+  return evaluations;
+}
+
+function sharedMetricEvaluation(
+  instance: FunctionMetricInstance,
+  policyContext: FunctionPolicyContext
+) {
+  return {
+    blocking: policyContext.blocking,
+    codeAreas: policyContext.codeAreas,
+    functionName: policyContext.functionName,
+    path: instance.metric.file,
+    startLine: instance.metric.startLine,
+    subject: instance.semanticSubject
+  } as const;
+}
+
+function complexityMetricEvaluation(
+  instance: FunctionMetricInstance,
+  policyContext: FunctionPolicyContext,
+  matchingAreas: MatchingFunctionMetricAreas
+): FunctionMetricEvaluation | null {
+  const value = instance.metric.cyclomaticComplexity.value;
+  if (value === null) return null;
+  return {
+    ...sharedMetricEvaluation(instance, policyContext),
+    limit: Math.min(...matchingAreas.map((area) => area.limits.cyclomaticComplexity.maximum)),
+    metric: "cyclomatic-complexity",
+    value
+  };
+}
+
+function codeLinesMetricEvaluation(
+  instance: FunctionMetricInstance,
+  policyContext: FunctionPolicyContext,
+  matchingAreas: MatchingFunctionMetricAreas
+): FunctionMetricEvaluation {
+  return {
+    ...sharedMetricEvaluation(instance, policyContext),
+    limit: Math.min(
+      ...matchingAreas.map((area) => functionCodeLineMaximum(instance.metric, area.limits))
+    ),
+    metric: "function-code-density",
+    value: instance.metric.lines
+  };
+}
+
+function parameterMetricEvaluation(
+  instance: FunctionMetricInstance,
+  policyContext: FunctionPolicyContext,
+  matchingAreas: MatchingFunctionMetricAreas
+): FunctionMetricEvaluation {
+  return {
+    ...sharedMetricEvaluation(instance, policyContext),
+    limit: Math.min(...matchingAreas.map((area) => area.limits.parameters.maximum)),
+    metric: "parameter-count",
+    value: instance.metric.parameterCount
+  };
+}
+
+function appendFindingCandidate(
+  candidates: FunctionRecordCandidate[],
+  evaluation: FunctionMetricEvaluation
+): void {
+  if (evaluation.value <= evaluation.limit) return;
+  candidates.push(
+    Object.freeze({
+      id: `${evaluation.subject}:${evaluation.metric}`,
+      data: Object.freeze({
+        blocking: evaluation.blocking,
+        codeAreas: evaluation.codeAreas,
+        functionName: evaluation.functionName,
+        limit: evaluation.limit,
+        metric: evaluation.metric,
+        path: evaluation.path,
+        startLine: evaluation.startLine,
+        value: evaluation.value
+      })
+    })
+  );
+}
+
+function functionCodeLineMaximum(
+  metric: FunctionMetric,
+  limits: ResolvedFunctionMetricsLimits
+): number {
+  const allowance = limits.codeLines.lowComplexityAllowance;
+  const complexity = metric.cyclomaticComplexity.value;
+  return complexity !== null && complexity < allowance.cyclomaticComplexityBelow
+    ? allowance.maximum
+    : limits.codeLines.maximum;
+}
+
+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/target-files.ts

@@ -0,0 +1,85 @@
+/** Lizard 1.23.0 官方 language readers 支持的 exact input 扩展名。 */
+const LIZARD_SUPPORTED_FILE_EXTENSIONS = Object.freeze([
+  "c",
+  "cc",
+  "cjs",
+  "cpp",
+  "cs",
+  "cxx",
+  "erl",
+  "es",
+  "escript",
+  "f",
+  "f03",
+  "f08",
+  "f70",
+  "f90",
+  "f95",
+  "for",
+  "fpp",
+  "ftn",
+  "gd",
+  "go",
+  "h",
+  "hpp",
+  "hrl",
+  "java",
+  "js",
+  "jsx",
+  "kt",
+  "kts",
+  "lua",
+  "m",
+  "mjs",
+  "mm",
+  "pck",
+  "php",
+  "pkb",
+  "pks",
+  "pl",
+  "plb",
+  "pls",
+  "pm",
+  "py",
+  "r",
+  "rb",
+  "rs",
+  "scala",
+  "sol",
+  "sql",
+  "st",
+  "swift",
+  "ts",
+  "ttcn",
+  "ttcnpp",
+  "tsx",
+  "vue",
+  "zig"
+] as const);
+
+const LIZARD_SUPPORTED_FILE_EXTENSION_SET: ReadonlySet<string> = new Set(
+  LIZARD_SUPPORTED_FILE_EXTENSIONS
+);
+
+/** functionMetrics 默认 files.include 使用的 case-insensitive extension globs。 */
+export const LIZARD_SUPPORTED_FILE_GLOBS = Object.freeze(
+  LIZARD_SUPPORTED_FILE_EXTENSIONS.map(
+    (extension) => `**/*.${caseInsensitiveExtensionPattern(extension)}`
+  )
+);
+
+export function isLizardTarget(filePath: string): boolean {
+  const extensionSeparator = filePath.lastIndexOf(".");
+  if (extensionSeparator < 0) return false;
+  const extension = filePath.slice(extensionSeparator + 1).toLowerCase();
+  return LIZARD_SUPPORTED_FILE_EXTENSION_SET.has(extension);
+}
+
+function caseInsensitiveExtensionPattern(extension: string): string {
+  return extension
+    .split("")
+    .map((character) =>
+      /[a-z]/u.test(character) ? `[${character}${character.toUpperCase()}]` : character
+    )
+    .join("");
+}

package/src/package-checks/host-environment/error-message.ts

@@ -0,0 +1,3 @@
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/package-checks/host-environment/filesystem.ts

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { errorMessage } from "./error-message.ts";
+import { toSlashPath } from "./path.ts";
+
+export type WriteTextFileInput = {
+  readonly content: string;
+  readonly filePath: string;
+};
+
+export type WriteJsonFileInput = {
+  readonly filePath: string;
+  readonly trailingNewline?: boolean;
+  readonly value: unknown;
+};
+
+export type WalkFilesInput = {
+  readonly ignoredDirs?: Iterable<string>;
+  readonly rootDir: string;
+};
+
+export function ensureDirForFile(filePath: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+export function readTextFile(filePath: string): string {
+  return fs.readFileSync(filePath, "utf8");
+}
+
+export function writeTextFile({ content, filePath }: WriteTextFileInput): void {
+  ensureDirForFile(filePath);
+  fs.writeFileSync(filePath, content, "utf8");
+}
+
+export function readJsonFile(filePath: string): unknown {
+  let source: string;
+  try {
+    source = readTextFile(filePath);
+  } catch (error: unknown) {
+    throw new Error(`could not read JSON file ${filePath}: ${errorMessage(error)}`, {
+      cause: error
+    });
+  }
+
+  try {
+    return JSON.parse(source);
+  } catch (error: unknown) {
+    throw new Error(`could not parse JSON file ${filePath}: ${errorMessage(error)}`, {
+      cause: error
+    });
+  }
+}
+
+export function writeJsonFile({
+  filePath,
+  trailingNewline = true,
+  value
+}: WriteJsonFileInput): void {
+  const content = serializeJsonFile(value, filePath);
+  writeTextFile({ content: trailingNewline ? `${content}\n` : content, filePath });
+}
+
+export function walkFiles({
+  ignoredDirs: ignoredDirectoryNames,
+  rootDir
+}: WalkFilesInput): readonly string[] {
+  const ignoredDirs = new Set(ignoredDirectoryNames ?? []);
+  const results: string[] = [];
+
+  const visit = (subDir: string) => {
+    const currentDir = subDir ? path.join(rootDir, subDir) : rootDir;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch (error: unknown) {
+      throw new Error(`could not read directory ${currentDir}: ${errorMessage(error)}`, {
+        cause: error
+      });
+    }
+
+    for (const entry of entries) {
+      const relPath = subDir ? `${subDir}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (!ignoredDirs.has(entry.name)) {
+          visit(relPath);
+        }
+      } else if (entry.isFile()) {
+        results.push(toSlashPath(relPath));
+      }
+    }
+  };
+
+  visit("");
+  return Object.freeze(results.sort());
+}
+
+function serializeJsonFile(value: unknown, filePath: string): string {
+  try {
+    const content = JSON.stringify(value, null, 2);
+    if (content === undefined) {
+      throw new TypeError("value is not JSON-serializable");
+    }
+    return content;
+  } catch (error: unknown) {
+    throw new Error(`could not serialize JSON file ${filePath}: ${errorMessage(error)}`, {
+      cause: error
+    });
+  }
+}

package/src/package-checks/host-environment/git.ts

@@ -0,0 +1,68 @@
+import { processFailed, runProcessSync } from "./process/command.ts";
+import type { ProcessResult, RunProcessSyncOptions } from "./process/command.ts";
+import { toSlashPath } from "./path.ts";
+
+export type RunGitOptions = Omit<RunProcessSyncOptions, "command">;
+
+export type GitCommitOptions = {
+  readonly cwd: string;
+  readonly sha: string;
+};
+
+type GitLogFieldOptions = GitCommitOptions & {
+  readonly format: string;
+};
+
+export function runGit(options: RunGitOptions): ProcessResult {
+  return runProcessSync({ command: "git", ...options });
+}
+
+export function gitHeadSha(cwd: string): string | null {
+  const result = runGit({ args: ["rev-parse", "HEAD"], cwd });
+  if (processFailed(result)) return null;
+  return result.stdout.trim() || null;
+}
+
+export function gitCommitDate(options: GitCommitOptions): string | null {
+  return gitLogField({ format: "%aI", ...options });
+}
+
+export function gitCommitTitle(options: GitCommitOptions): string | null {
+  return gitLogField({ format: "%s", ...options });
+}
+
+export function splitGitFileList(stdout: string): string[] {
+  return stdout.trim().split(/\r?\n/).filter(Boolean).map(toSlashPath);
+}
+
+export function splitNulDelimitedGitFileList(stdout: string): string[] {
+  return stdout
+    .split("\0")
+    .filter((filePath) => filePath.length > 0)
+    .map(toSlashPath);
+}
+
+export function parseGitStatusPaths(stdout: string): string[] {
+  return stdout
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter(Boolean)
+    .map((line) => {
+      const rawPath = line.slice(3).trim();
+      const renameMarker = " -> ";
+      return rawPath.includes(renameMarker)
+        ? rawPath.slice(rawPath.indexOf(renameMarker) + renameMarker.length)
+        : rawPath;
+    })
+    .filter(Boolean)
+    .map(toSlashPath);
+}
+
+function gitLogField({ format, ...options }: GitLogFieldOptions): string | null {
+  const result = runGit({
+    args: ["log", `--format=${format}`, "--max-count=1", options.sha],
+    cwd: options.cwd
+  });
+  if (processFailed(result)) return null;
+  return result.stdout.trim() || null;
+}

package/src/package-checks/host-environment/path.ts

@@ -0,0 +1,20 @@
+export function toSlashPath(filePath: string): string {
+  return filePath.replace(/\\/g, "/");
+}
+
+/** 判断值是否已是跨平台可稳定发布的 project-root-relative slash path。 */
+export function isNormalizedProjectRelativePath(value: unknown): value is string {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.startsWith("/") ||
+    value.includes("\\") ||
+    value.includes("\u0000") ||
+    /^[A-Za-z]:/u.test(value)
+  ) {
+    return false;
+  }
+  return value
+    .split("/")
+    .every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}

package/src/package-checks/host-environment/process/command.ts

@@ -0,0 +1,21 @@
+import type { ProcessResult } from "./contract.ts";
+
+export { processFailure, processFailureFromResult, processFailed } from "./failure.ts";
+export { PLAIN_TEXT_PROCESS_ENV, plainTextProcessEnv } from "./env.ts";
+export { runProcess, runProcessSync } from "./runner.ts";
+export { DEFAULT_PROCESS_MAX_BUFFER_BYTES } from "./contract.ts";
+export type {
+  ProcessFailure,
+  ProcessResult,
+  RunProcessOptions,
+  RunProcessSyncOptions
+} from "./contract.ts";
+
+export function writeProcessOutput(result: Pick<ProcessResult, "stderr" | "stdout">): void {
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+}