@zxyycom/vibe-check 0.0.1

package/types/package-checks/file-metrics/constructor.d.ts

@@ -0,0 +1,11 @@
+import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { parseFileMetricsData } from "./final-data.ts";
+import type { FileMetricsOptions, ResolvedFileMetricsOptions } from "./options.ts";
+/**
+ * 使用可省略的区域、代码行与 scanner policy 构造一个完整 file-metrics Check。
+ *
+ * @param options - 省略字段由 package 补齐；显式 files 数组作为对应字段的完整替换值。
+ * @returns 固定 `file-metrics` identity、完整冻结 options、preflight 与 execution。
+ * @throws {TypeError} input 含未知字段、空 area、非法代码行 policy、非法 waiver 或空 executable 时抛出。
+ */
+export declare function fileMetrics(options?: FileMetricsOptions): TypedCheckWithOptions<"file-metrics", ResolvedFileMetricsOptions, typeof parseFileMetricsData>;

package/types/package-checks/file-metrics/execution.d.ts

@@ -0,0 +1,11 @@
+import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
+import type { ResolvedFileMetricsOptions } from "./options.ts";
+import type { FileMetricsFinalData } from "./final-data.ts";
+export declare const FILE_METRICS_CHECK_DEFINITION: {
+    readonly checkId: "file-metrics";
+    readonly displayName: "File metrics";
+};
+/** `file-metrics` whole-Check unavailable outcome 的稳定 reason code。 */
+export type FileMetricsUnavailableReasonCode = "external-dependency-unavailable" | "external-execution-failed" | "external-result-invalid" | "invalid-options" | "source-unavailable";
+/** 使用 resolved area policy 和 scanner selection 执行一次完整的 file-metrics measurement。 */
+export declare function executeFileMetrics(context: CheckExecutionContext<ResolvedFileMetricsOptions>): Promise<CheckResult<FileMetricsFinalData>>;

package/types/package-checks/file-metrics/final-data.d.ts

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

package/types/package-checks/file-metrics/measurement-model.d.ts

@@ -0,0 +1,12 @@
+export interface FileMetric {
+    readonly codeLines: number;
+    readonly decisionTokens: Readonly<{
+        readonly source: "scc";
+        readonly value: number | null;
+    }>;
+    readonly path: string;
+}
+export interface FileMetricsExactInputSet {
+    readonly approvedExactPaths: readonly string[];
+    readonly rootDir: string;
+}

package/types/package-checks/file-metrics/measurement.d.ts

@@ -0,0 +1,13 @@
+import type { FileMetric, FileMetricsExactInputSet } from "./measurement-model.ts";
+import type { ResolvedFileMetricsScannerOptions } from "./options.ts";
+export type FileMeasurementResult = Readonly<{
+    kind: "complete";
+    metrics: readonly FileMetric[];
+} | {
+    kind: "execution-failed";
+} | {
+    kind: "invalid-result";
+} | {
+    kind: "unavailable";
+}>;
+export declare function measureFileMetrics(exactInputs: FileMetricsExactInputSet, scanner: ResolvedFileMetricsScannerOptions): Promise<FileMeasurementResult>;

package/types/package-checks/file-metrics/options-resolution.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedFileMetricsOptions } from "./options.ts";
+/** 校验 constructor input，并将所有可省略 policy 物化为完整、冻结的 Check options。 */
+export declare function resolveFileMetricsOptions(authoredOptions: unknown): ResolvedFileMetricsOptions | undefined;

package/types/package-checks/file-metrics/options-validation.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedFileMetricsOptions } from "./options.ts";
+/** 验证 constructor 产物或普通对象组合形成的完整 file-metrics options。 */
+export declare function isValidResolvedFileMetricsOptions(resolvedOptions: unknown): resolvedOptions is ResolvedFileMetricsOptions;

package/types/package-checks/file-metrics/options.d.ts

@@ -0,0 +1,75 @@
+import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
+import type { FindingPolicy } from "../code-quality-findings/policy.ts";
+import type { FindingWaiver } from "../../finding-waivers/reconciliation.ts";
+/** `fileMetrics` 构造函数可省略的 SCC 可执行文件策略。 */
+export interface FileMetricsScannerOptions {
+    /** 省略时直接执行 `scc`；显式命令必须直接接受 adapter 拥有的 SCC 参数。 */
+    readonly executable?: string;
+}
+/** file-metrics 区域可省略并由构造函数补齐的文件策略。 */
+export type FileMetricsFileOptions = ProjectFileSelectionOptions;
+/** SCC decision-token 数较低的文件可使用的代码行宽限策略。 */
+export interface FileMetricsLowDecisionTokenAllowanceOptions {
+    /** 省略时为 `600`；必须严格大于同一区域的普通代码行上限。 */
+    readonly maximumCodeLines?: number;
+    /** 省略时为 `12`；decision-token measurement 不大于此值时应用宽限上限。 */
+    readonly maximumDecisionTokens?: number;
+}
+/** 一个区域可省略的文件代码行策略。 */
+export interface FileMetricsCodeLineOptions {
+    /** 省略时为 `360`；只有严格超过此值才产生 finding。 */
+    readonly maximum?: number;
+    /** 省略时使用完整默认宽限策略。 */
+    readonly lowDecisionTokenAllowance?: FileMetricsLowDecisionTokenAllowanceOptions;
+}
+/** 可独立选择文件并定义代码行与 finding policy 的 file-metrics 区域。 */
+export interface FileMetricsCodeAreaOptions {
+    /** 显式区域必须声明本字段；其中各子字段可省略并使用 package 默认值。 */
+    readonly files: FileMetricsFileOptions;
+    /** 省略时继承顶层 `findingPolicy`。 */
+    readonly findingPolicy?: FindingPolicy;
+    /** 省略时使用 package 默认代码行策略。 */
+    readonly codeLines?: FileMetricsCodeLineOptions;
+}
+/** file-metrics 用于识别可豁免 finding 的稳定语义字段。 */
+export interface FileMetricsFindingIdentity {
+    /** file-metrics 当前只产生文件代码行 finding。 */
+    readonly metric: "code-lines";
+    /** 已 normalized 的 project-root-relative slash path；不得为绝对、含反斜杠或含 `.`/`..` 的路径。 */
+    readonly path: string;
+}
+/** 一项 file-metrics finding 的声明式豁免；执行时仍会扫描并发布该 finding。 */
+export type FileMetricsFindingWaiver = FindingWaiver<FileMetricsFindingIdentity>;
+/** `fileMetrics(options?)` 接受并补齐默认值的公开策略。 */
+export interface FileMetricsOptions {
+    /** 省略时建立默认 `project` 区域；显式映射必须非空。 */
+    readonly codeAreas?: Readonly<Record<string, FileMetricsCodeAreaOptions>>;
+    /** 省略时为 `non-blocking`；区域可局部覆盖。 */
+    readonly findingPolicy?: FindingPolicy;
+    /** 省略时没有豁免；每项以 `{ metric, path }` 精确匹配，并必须提供非空理由。 */
+    readonly findingWaivers?: readonly FileMetricsFindingWaiver[];
+    /** 省略时直接执行 `scc`；CLI 协议由 owning adapter 固定。 */
+    readonly scanner?: FileMetricsScannerOptions;
+}
+/** 构造函数生成并由 Check preflight/execution 消费的完整 options。 */
+export interface ResolvedFileMetricsOptions {
+    readonly codeAreas: Readonly<Record<string, ResolvedFileMetricsCodeAreaOptions>>;
+    readonly findingWaivers: readonly FileMetricsFindingWaiver[];
+    readonly scanner: ResolvedFileMetricsScannerOptions;
+}
+export interface ResolvedFileMetricsCodeAreaOptions {
+    readonly codeLines: ResolvedFileMetricsCodeLineOptions;
+    readonly files: ProjectFileSelection;
+    readonly findingPolicy: FindingPolicy;
+}
+export interface ResolvedFileMetricsCodeLineOptions {
+    readonly lowDecisionTokenAllowance: ResolvedFileMetricsLowDecisionTokenAllowanceOptions;
+    readonly maximum: number;
+}
+export interface ResolvedFileMetricsLowDecisionTokenAllowanceOptions {
+    readonly maximumCodeLines: number;
+    readonly maximumDecisionTokens: number;
+}
+export interface ResolvedFileMetricsScannerOptions {
+    readonly executable: string;
+}

package/types/package-checks/file-metrics/records.d.ts

@@ -0,0 +1,43 @@
+import type { FileMetric } from "./measurement-model.ts";
+import type { FileMetricsFindingIdentity, ResolvedFileMetricsCodeAreaOptions } from "./options.ts";
+import type { FindingWaiverAudit, MaterializedFindingWaiver } from "../../finding-waivers/reconciliation.ts";
+interface FileMetricsAreaPolicyContext {
+    readonly areaIdsByPath: ReadonlyMap<string, readonly string[]>;
+    readonly codeAreas: Readonly<Record<string, ResolvedFileMetricsCodeAreaOptions>>;
+}
+/** 一条超出文件代码行上限的 supplemental Record data。 */
+export type FileMetricsFindingRecordData = Readonly<{
+    readonly blocking: boolean;
+    readonly codeAreas: readonly string[];
+    readonly codeLines: number;
+    readonly limit: number;
+    readonly metric: "code-lines";
+    readonly path: string;
+    /** 精确匹配 waiver 时保留理由，并令该 finding 不再参与 actionable settlement。 */
+    readonly waiver?: Readonly<{
+        readonly reason: string;
+    }>;
+}>;
+/** 未使用或过宽 file-metrics waiver 的 supplemental audit Record data。 */
+export type FileMetricsFindingWaiverAuditRecordData = Readonly<{
+    readonly identity: FileMetricsFindingIdentity;
+    readonly kind: "finding-waiver-audit";
+    readonly matchCount: number;
+    readonly reason: string;
+    readonly status: "overmatched" | "unused";
+}>;
+/** file-metrics 发布的 finding 或 waiver-audit supplemental Record data。 */
+export type FileMetricsRecordData = FileMetricsFindingRecordData | FileMetricsFindingWaiverAuditRecordData;
+export interface FileRecordCandidate {
+    readonly data: FileMetricsFindingRecordData;
+    readonly id: string;
+}
+/** 仅为未使用和过宽 waiver 构造补充 audit Record；正常 applied waiver 由 finding Record 自己保留。 */
+export declare function fileMetricsWaiverAuditRecord(audit: FindingWaiverAudit): Readonly<{
+    readonly data: FileMetricsFindingWaiverAuditRecordData;
+    readonly id: string;
+}> | undefined;
+export declare function fileMetricsWaiverIdentity(waiver: MaterializedFindingWaiver): FileMetricsFindingIdentity;
+/** Converts trusted scanner metrics into area-policy-owned supplemental facts. */
+export declare function buildFileRecordCandidates(metrics: readonly FileMetric[], areaPolicy: FileMetricsAreaPolicyContext): readonly FileRecordCandidate[] | undefined;
+export {};

package/types/package-checks/file-metrics/scc/availability.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedFileMetricsScannerOptions } from "../options.ts";
+type SccAvailability = Readonly<{
+    readonly available: true;
+    readonly error: null;
+    readonly name: "scc";
+    readonly reason: null;
+    readonly source: "configured command";
+    readonly version: string;
+} | {
+    readonly available: false;
+    readonly error: string;
+    readonly name: "scc";
+    readonly reason: "contract-error" | "execution-error" | "tool-unavailable";
+    readonly source: "configured command";
+    readonly version: null;
+}>;
+export declare function checkScc(rootDir: string, scanner: ResolvedFileMetricsScannerOptions): Promise<SccAvailability>;
+export {};

package/types/package-checks/file-metrics/scc/csv.d.ts

@@ -0,0 +1 @@
+export declare function parseCsvRows(csv: string): string[][];

package/types/package-checks/file-metrics/scc/parser.d.ts

@@ -0,0 +1,25 @@
+import type { ExactInputMeasurement } from "../../project-files/exact-input-measurement.ts";
+import type { FileMetric } from "../measurement-model.ts";
+export declare const SCC_VERSION = "3.7.0";
+export declare const SCC_VERSION_OUTPUT = "scc version 3.7.0";
+export declare const SCC_BY_FILE_CSV_HEADER = "Language,Provider,Filename,Lines,Code,Comments,Blanks,Complexity,Bytes,ULOC";
+export type SccScanResult = {
+    readonly measurements: readonly ExactInputMeasurement<FileMetric>[];
+    readonly ok: true;
+} | {
+    readonly error: string;
+    readonly ok: false;
+    readonly reason: "execution" | "invalid-result";
+};
+/**
+ * 解析 scc CSV 输出。
+ *
+ * scc 3.7.0 `--by-file --format csv` 列：
+ * Language,Provider,Filename,Lines,Code,Comments,Blanks,Complexity,Bytes,ULOC
+ *
+ * - Lines 包含所有行（code + comments + blanks）
+ * - Code 是文件级代码行数，用于 code-line finding
+ * - Complexity 是 scc complexitychecks token 命中数，用于 low-decision-token allowance，不是函数级 CC
+ * - ULOC (Usable Lines of Code) 由 3.7.0 输出，但首期不进入稳定 metrics
+ */
+export declare function parseSccCSV(csv: string, cwd: string): SccScanResult;

package/types/package-checks/file-metrics/scc/scanner.d.ts

@@ -0,0 +1,14 @@
+/**
+ * scc 文件级 code-line 指标 wrapper。
+ *
+ * 封装 adapter-owned CLI 调用，输出 exact-path code lines 与 decision-token count。
+ */
+import type { ResolvedFileMetricsScannerOptions } from "../options.ts";
+import { type SccScanResult } from "./parser.ts";
+interface ScanWithSccOptions {
+    readonly cwd: string;
+    readonly includePaths: readonly string[];
+    readonly scanner: ResolvedFileMetricsScannerOptions;
+}
+export declare function scanWithScc({ cwd, includePaths, scanner }: ScanWithSccOptions): SccScanResult;
+export {};

package/types/package-checks/final-data-parsing.d.ts

@@ -0,0 +1,9 @@
+import type { FindingSummary } from "./code-quality-findings/policy.ts";
+/** Parses the final-data shape shared by the three area-based quality Checks. */
+export declare function parseFindingSummaryData(data: unknown, checkName: string): FindingSummary;
+/** Returns a detached exact record or rejects an unsupported final-data shape. */
+export declare function exactFinalDataRecord(data: unknown, keys: readonly string[], checkName: string): Readonly<Record<string, unknown>>;
+/** Returns a detached closed array or rejects an unsupported final-data shape. */
+export declare function finalDataArray(data: unknown, checkName: string): readonly unknown[];
+export declare function nonNegativeSafeInteger(value: unknown): number | undefined;
+export declare function invalidFinalData(checkName: string): TypeError;

package/types/package-checks/function-metrics/analysis.d.ts

@@ -0,0 +1,10 @@
+import type { FunctionMetric } from "./measurement-model.ts";
+export interface FunctionMetricInstance {
+    readonly metric: FunctionMetric;
+    readonly semanticSubject: string;
+}
+export interface FunctionMetricAnalysis {
+    readonly instances: readonly FunctionMetricInstance[];
+}
+export declare function analyzeFunctionMetrics(metrics: readonly FunctionMetric[]): FunctionMetricAnalysis | undefined;
+export declare function isStableFunctionName(name: string): boolean;

package/types/package-checks/function-metrics/constructor.d.ts

@@ -0,0 +1,11 @@
+import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { parseFunctionMetricsData } from "./final-data.ts";
+import type { FunctionMetricsOptions, ResolvedFunctionMetricsOptions } from "./options.ts";
+/**
+ * 使用可省略的区域、阈值与 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 declare function functionMetrics(options?: FunctionMetricsOptions): TypedCheckWithOptions<"function-metrics", ResolvedFunctionMetricsOptions, typeof parseFunctionMetricsData>;

package/types/package-checks/function-metrics/execution.d.ts

@@ -0,0 +1,7 @@
+import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
+import type { ResolvedFunctionMetricsOptions } from "./options.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 declare function executeFunctionMetrics(context: CheckExecutionContext<ResolvedFunctionMetricsOptions>): Promise<CheckResult<FunctionMetricsFinalData>>;

package/types/package-checks/function-metrics/final-data.d.ts

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

package/types/package-checks/function-metrics/lizard/availability.d.ts

@@ -0,0 +1,11 @@
+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";
+}>;
+export declare function checkLizard(rootDir: string, dependency: ResolvedFunctionMetricsScannerOptions): Promise<LizardAvailability>;
+export {};

package/types/package-checks/function-metrics/lizard/csv.d.ts

@@ -0,0 +1 @@
+export declare function parseCsvRows(csv: string): string[][];

package/types/package-checks/function-metrics/lizard/parser.d.ts

@@ -0,0 +1,17 @@
+import type { FunctionMetric } from "../measurement-model.ts";
+import type { ExactInputMeasurement } from "../../project-files/exact-input-measurement.ts";
+export type LizardParseResult = {
+    readonly measurements: readonly ExactInputMeasurement<FunctionMetric>[];
+    readonly ok: true;
+} | {
+    readonly error: string;
+    readonly ok: false;
+    readonly reason: "invalid-result";
+};
+/**
+ * 将 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 declare function parseLizardCSV(csv: string, cwd: string): LizardParseResult;

package/types/package-checks/function-metrics/lizard/scanner.d.ts

@@ -0,0 +1,15 @@
+/** 对 approved exact paths 执行 adapter-owned Lizard CSV 协议。 */
+import type { ResolvedFunctionMetricsScannerOptions } from "../options.ts";
+import { 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 declare function scanWithLizard({ files, cwd, dependency }: ScanWithLizardOptions): LizardScanResult;
+export {};

package/types/package-checks/function-metrics/measurement-model.d.ts

@@ -0,0 +1,26 @@
+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/types/package-checks/function-metrics/measurement.d.ts

@@ -0,0 +1,21 @@
+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 declare function measureFunctionMetrics({ dependency, input, signal }: FunctionMeasurementInput): Promise<FunctionMeasurementResult>;
+export {};

package/types/package-checks/function-metrics/options-resolution.d.ts

@@ -0,0 +1,3 @@
+import { type ResolvedFunctionMetricsOptions } from "./options.ts";
+/** 校验 constructor input，并物化完整、冻结的 function-metrics options。 */
+export declare function resolveFunctionMetricsOptions(value: unknown): ResolvedFunctionMetricsOptions | undefined;

package/types/package-checks/function-metrics/options-validation.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedFunctionMetricsOptions } from "./options.ts";
+/** 验证 constructor 已物化的完整 function-metrics options。 */
+export declare function validResolvedFunctionMetricsOptions(value: unknown): value is ResolvedFunctionMetricsOptions;

package/types/package-checks/function-metrics/options.d.ts

@@ -0,0 +1,76 @@
+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/types/package-checks/function-metrics/records.d.ts

@@ -0,0 +1,37 @@
+import { type FunctionMetricAnalysis } from "./analysis.ts";
+import type { FunctionMetricsAreaInput } from "./measurement-model.ts";
+type FunctionMetricName = "cyclomatic-complexity" | "function-code-density" | "parameter-count";
+/** 一条超出函数 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 declare function buildFunctionInputRejectedCandidates(codeAreasByPath: ReadonlyMap<string, readonly string[]>): readonly FunctionInputRejectedCandidate[];
+/** 为每个超过 matching-area 最严格阈值的 metric 构造 supplemental fact。 */
+export declare function buildFunctionRecordCandidates(analysis: FunctionMetricAnalysis, areas: readonly FunctionMetricsAreaInput[]): readonly FunctionRecordCandidate[] | undefined;
+export {};

package/types/package-checks/function-metrics/target-files.d.ts

@@ -0,0 +1,3 @@
+/** functionMetrics 默认 files.include 使用的 case-insensitive extension globs。 */
+export declare const LIZARD_SUPPORTED_FILE_GLOBS: readonly string[];
+export declare function isLizardTarget(filePath: string): boolean;

package/types/package-checks/host-environment/error-message.d.ts

@@ -0,0 +1 @@
+export declare function errorMessage(error: unknown): string;

package/types/package-checks/host-environment/filesystem.d.ts

@@ -0,0 +1,19 @@
+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 declare function ensureDirForFile(filePath: string): void;
+export declare function readTextFile(filePath: string): string;
+export declare function writeTextFile({ content, filePath }: WriteTextFileInput): void;
+export declare function readJsonFile(filePath: string): unknown;
+export declare function writeJsonFile({ filePath, trailingNewline, value }: WriteJsonFileInput): void;
+export declare function walkFiles({ ignoredDirs: ignoredDirectoryNames, rootDir }: WalkFilesInput): readonly string[];

package/types/package-checks/host-environment/git.d.ts

@@ -0,0 +1,13 @@
+import type { ProcessResult, RunProcessSyncOptions } from "./process/command.ts";
+export type RunGitOptions = Omit<RunProcessSyncOptions, "command">;
+export type GitCommitOptions = {
+    readonly cwd: string;
+    readonly sha: string;
+};
+export declare function runGit(options: RunGitOptions): ProcessResult;
+export declare function gitHeadSha(cwd: string): string | null;
+export declare function gitCommitDate(options: GitCommitOptions): string | null;
+export declare function gitCommitTitle(options: GitCommitOptions): string | null;
+export declare function splitGitFileList(stdout: string): string[];
+export declare function splitNulDelimitedGitFileList(stdout: string): string[];
+export declare function parseGitStatusPaths(stdout: string): string[];

package/types/package-checks/host-environment/path.d.ts

@@ -0,0 +1,3 @@
+export declare function toSlashPath(filePath: string): string;
+/** 判断值是否已是跨平台可稳定发布的 project-root-relative slash path。 */
+export declare function isNormalizedProjectRelativePath(value: unknown): value is string;

package/types/package-checks/host-environment/process/command.d.ts

@@ -0,0 +1,7 @@
+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 declare function writeProcessOutput(result: Pick<ProcessResult, "stderr" | "stdout">): void;