@zxyycom/vibe-check 0.0.1 → 0.0.2

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

@@ -1,15 +1,27 @@
 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;
 }

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

@@ -1,21 +1,36 @@
+import { type FunctionMetricsWorkerPort } from "./analyzer-worker-port.ts";
 import type { FunctionMetric, FunctionMetricsExactInputSet } from "./measurement-model.ts";
-import type { ResolvedFunctionMetricsScannerOptions } from "./options.ts";
 export type FunctionMeasurementResult = Readonly<{
+    kind: "analysis-failed";
+} | {
     kind: "cancelled";
 } | {
     kind: "complete";
     metrics: readonly FunctionMetric[];
 } | {
-    kind: "execution-failed";
-} | {
-    kind: "invalid-result";
+    kind: "resource-limit-exceeded";
 } | {
-    kind: "unavailable";
+    kind: "source-unavailable";
 }>;
 interface FunctionMeasurementInput {
-    readonly dependency: ResolvedFunctionMetricsScannerOptions;
     readonly input: FunctionMetricsExactInputSet;
     readonly signal: AbortSignal;
 }
-export declare function measureFunctionMetrics({ dependency, input, signal }: FunctionMeasurementInput): Promise<FunctionMeasurementResult>;
+export interface FunctionMeasurementDependencies {
+    readonly createWorker: () => FunctionMetricsWorkerPort;
+    readonly yieldAdmission: () => Promise<void>;
+}
+/**
+ * The Check parent admits exactly its selected sources and bounds their bytes;
+ * one Worker only analyzes those source texts and never discovers or reads paths.
+ */
+export declare function measureFunctionMetrics({ input, signal }: FunctionMeasurementInput, dependencies?: Partial<FunctionMeasurementDependencies>): Promise<FunctionMeasurementResult>;
+/**
+ * Product-owned replacement for Lizard 1.24 `auto_open.auto_read` at the
+ * admitted-source boundary. A valid initial UTF-8 BOM is `utf-8-sig` and text
+ * newlines are universal; a decoding failure retries the complete byte sequence
+ * with Python's `errors="ignore"`, which deliberately retains an initial BOM
+ * and raw newlines on that retry.
+ */
+export declare function decodeLizardAutoRead(bytes: Uint8Array): string;
 export {};

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

@@ -1,5 +1,6 @@
 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";
 /** `functionMetrics` 构造函数可省略的文件选择策略。 */
 export type FunctionMetricsFileOptions = ProjectFileSelectionOptions;
 /** `functionMetrics` 构造函数可省略的函数指标上限。 */
@@ -18,6 +19,10 @@ export interface FunctionMetricsLimitOptions {
         /** 省略时为 `12`。 */
         readonly maximum?: number;
     }>;
+    readonly nestingDepth?: Readonly<{
+        /** 省略时为 `7`。 */
+        readonly maximum?: number;
+    }>;
     readonly parameters?: Readonly<{
         /** 省略时为 `6`。 */
         readonly maximum?: number;
@@ -32,24 +37,32 @@ export interface FunctionMetricsCodeAreaOptions {
     /** 省略的嵌套上限使用 package 默认值。 */
     readonly limits?: FunctionMetricsLimitOptions;
 }
-/** `functionMetrics` 构造函数可省略的 Lizard 可执行文件策略。 */
-export interface FunctionMetricsScannerOptions {
-    /** 省略时为 `lizard`；显式命令必须直接接受 adapter 拥有的 Lizard 参数。 */
-    readonly executable?: string;
+/** function-metrics 可形成 Finding 的封闭 metric 名称。 */
+export type FunctionMetricsFindingMetric = "cyclomatic-complexity" | "function-code-density" | "nesting-depth" | "parameter-count";
+/** function-metrics 用于精确识别一条可豁免 metric finding 的稳定字段。 */
+export interface FunctionMetricsFindingIdentity {
+    readonly functionName: string;
+    readonly metric: FunctionMetricsFindingMetric;
+    /** 已 normalized 的 project-root-relative slash path。 */
+    readonly path: string;
+    /** 该次 finding 中函数起始位置的一基行号；位置变化会让旧 waiver 进入 unused audit。 */
+    readonly startLine: number;
 }
+/** 一项 function-metrics metric finding 的声明式豁免。 */
+export type FunctionMetricsFindingWaiver = FindingWaiver<FunctionMetricsFindingIdentity>;
 /** `functionMetrics(options?)` 接受并补齐默认值的公开策略。 */
 export interface FunctionMetricsOptions {
     /** 省略时建立默认 `project` 区域；显式映射必须非空，且每个区域必须声明 `files`。 */
     readonly codeAreas?: Readonly<Record<string, FunctionMetricsCodeAreaOptions>>;
     /** 省略时为 `non-blocking`；区域可局部覆盖。 */
     readonly findingPolicy?: FindingPolicy;
-    /** 省略时使用 PATH 中的 `lizard`。 */
-    readonly scanner?: FunctionMetricsScannerOptions;
+    /** 省略时没有豁免；只匹配 normal metric finding，不匹配 input rejection。 */
+    readonly findingWaivers?: readonly FunctionMetricsFindingWaiver[];
 }
 /** 构造函数生成并由 Check preflight/execution 消费的完整 options。 */
 export interface ResolvedFunctionMetricsOptions {
     readonly codeAreas: Readonly<Record<string, ResolvedFunctionMetricsCodeAreaOptions>>;
-    readonly scanner: ResolvedFunctionMetricsScannerOptions;
+    readonly findingWaivers: readonly FunctionMetricsFindingWaiver[];
 }
 export interface ResolvedFunctionMetricsCodeAreaOptions {
     readonly files: ProjectFileSelection;
@@ -67,10 +80,10 @@ export interface ResolvedFunctionMetricsLimits {
     readonly cyclomaticComplexity: Readonly<{
         readonly maximum: number;
     }>;
+    readonly nestingDepth: 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

@@ -1,17 +1,30 @@
 import { type FunctionMetricAnalysis } from "./analysis.ts";
+import type { MaterializedFindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import { type FindingWaiverAuditRecordData, type FindingWaiverRecordAudit } from "../code-quality-findings/finding-waiver-evidence.ts";
 import type { FunctionMetricsAreaInput } from "./measurement-model.ts";
-type FunctionMetricName = "cyclomatic-complexity" | "function-code-density" | "parameter-count";
+import type { FunctionMetricsFindingIdentity, FunctionMetricsFindingMetric } from "./options.ts";
 /** 一条超出函数 metric 上限的 supplemental Record data。 */
 export type FunctionMetricsFindingRecordData = Readonly<{
     readonly blocking: boolean;
     readonly codeAreas: readonly string[];
+    /** Complete source-ordered CCN contributors; present only for CCN findings. */
+    readonly complexityContributors?: readonly Readonly<{
+        readonly line: number;
+        readonly token: string;
+    }>[];
     readonly functionName: string;
     readonly limit: number;
-    readonly metric: FunctionMetricName;
+    readonly metric: FunctionMetricsFindingMetric;
     readonly path: string;
     readonly startLine: number;
     readonly value: number;
+    /** 精确匹配 waiver 时保留理由，并令该 finding 不再参与 actionable settlement。 */
+    readonly waiver?: Readonly<{
+        readonly reason: string;
+    }>;
 }>;
+/** 未使用或过宽 function-metrics waiver 的 supplemental audit Record data。 */
+export type FunctionMetricsFindingWaiverAuditRecordData = FindingWaiverAuditRecordData<FunctionMetricsFindingIdentity>;
 /** 一条已被 files policy 选中、但不受 functionMetrics 支持的输入 Finding。 */
 export type FunctionMetricsInputRejectedRecordData = Readonly<{
     readonly blocking: false;
@@ -20,8 +33,8 @@ export type FunctionMetricsInputRejectedRecordData = Readonly<{
     readonly path: string;
     readonly reason: "unsupported-file-type";
 }>;
-/** functionMetrics 发布的 metric 或 input-rejection Record data。 */
-export type FunctionMetricsRecordData = FunctionMetricsFindingRecordData | FunctionMetricsInputRejectedRecordData;
+/** functionMetrics 发布的 metric、input-rejection 或 finding-waiver audit Record data。 */
+export type FunctionMetricsRecordData = FunctionMetricsFindingRecordData | FunctionMetricsInputRejectedRecordData | FunctionMetricsFindingWaiverAuditRecordData;
 export interface FunctionRecordCandidate {
     readonly data: FunctionMetricsFindingRecordData;
     readonly id: string;
@@ -32,6 +45,12 @@ export interface FunctionInputRejectedCandidate {
 }
 /** 为每个 rejected path 构造一条 area-aware、固定 non-blocking 的 Finding。 */
 export declare function buildFunctionInputRejectedCandidates(codeAreasByPath: ReadonlyMap<string, readonly string[]>): readonly FunctionInputRejectedCandidate[];
+export declare function functionMetricsFindingIdentity(candidate: FunctionRecordCandidate): FunctionMetricsFindingIdentity;
+export declare function functionMetricsWaiverIdentity(waiver: MaterializedFindingWaiver): FunctionMetricsFindingIdentity;
+/** 为一项未使用或过宽 waiver 构造 Check-owned audit Record。 */
+export declare function functionMetricsWaiverAuditRecord(audit: FindingWaiverRecordAudit): Readonly<{
+    readonly data: FunctionMetricsFindingWaiverAuditRecordData;
+    readonly id: string;
+}>;
 /** 为每个超过 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

@@ -1,3 +1,4 @@
-/** functionMetrics 默认 files.include 使用的 case-insensitive extension globs。 */
-export declare const LIZARD_SUPPORTED_FILE_GLOBS: readonly string[];
-export declare function isLizardTarget(filePath: string): boolean;
+/** functionMetrics default files.include uses the adapter's case-insensitive suffix capability. */
+export declare const FUNCTION_METRICS_SUPPORTED_FILE_GLOBS: readonly string[];
+/** Whether an exact project-relative path has a translated analyzer reader. */
+export declare function isFunctionMetricsTarget(filePath: string): boolean;

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

@@ -0,0 +1,2 @@
+/** Parses untrusted scanner CSV into a complete matrix of strings. */
+export declare function parseCsvRows(csv: string): string[][];

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

@@ -1,4 +1,4 @@
-import type { ProcessResult, RunProcessSyncOptions } from "./process/command.ts";
+import type { ProcessResult, RunProcessSyncOptions } from "./process.ts";
 export type RunGitOptions = Omit<RunProcessSyncOptions, "command">;
 export type GitCommitOptions = {
     readonly cwd: string;

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

@@ -0,0 +1,5 @@
+export { processFailure, processFailureFromResult, processFailed } from "./process/failure.ts";
+export { PLAIN_TEXT_PROCESS_ENV, plainTextProcessEnv } from "./process/env.ts";
+export { runProcess, runProcessSync } from "./process/runner.ts";
+export { DEFAULT_PROCESS_MAX_BUFFER_BYTES } from "./process/contract.ts";
+export type { ProcessFailure, ProcessResult, RunProcessOptions, RunProcessSyncOptions } from "./process/contract.ts";

package/types/package-checks/json-schema-validation/final-data.d.ts

@@ -2,13 +2,21 @@
 export declare const MAX_REPORTED_JSON_SCHEMA_ISSUES = 100;
 /** `json-schema-validation` 在 passed/failed outcome 中发布的主数据。 */
 export interface JsonSchemaValidationFinalData {
+    /** Definition 中已声明的 binding 总数。 */
     readonly bindingCount: number;
+    /** 因所引用 schema 存在 document 或 compile issue 而未验证 instance 的 binding 数。 */
     readonly blockedBindingCount: number;
+    /** instance out-of-scope、document invalid 或不符合对应 schema 的 binding 数。 */
     readonly invalidBindingCount: number;
+    /** schema document、compile、instance 与 keyword issue 的总数。 */
     readonly issueCount: number;
+    /** 是否因发布上限而省略了一个或多个 issue Record。 */
     readonly issuesTruncated: boolean;
+    /** 实际发布为 Record 的 issue 数。 */
     readonly reportedIssueCount: number;
+    /** Definition 中声明的不同 schema identity 数。 */
     readonly schemaCount: number;
+    /** input 符合对应 schema 的 binding 数。 */
     readonly validBindingCount: number;
 }
 /** 验证计数与截断不变量并脱离 canonical final data。 */

package/types/package-checks/json-schema-validation/options.d.ts

@@ -1,30 +1,58 @@
 import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
-export type JsonSchemaIdentityMode = "require-match" | "configuration-authoritative" | "document-authoritative";
+/** 已注册 schema 的 root `$id` 与配置 identity 之间的全 Check 统一规则。 */
+export type JsonSchemaIdentityMode = 
+/** root `$id` 必须等于 `schemas[].id`，该配置 ID 也是 engine identity。 */
+"require-match"
+/** 配置 ID 是 engine identity；object schema 的 invocation-local compile copy 使用该 `$id`。 */
+ | "configuration-authoritative"
+/** 安全的 root `$id` 是 engine identity；配置 ID 仍是 binding 与公开事实的标签。 */
+ | "document-authoritative";
+/** 整个 Check 共用、不能按单个 schema 混用的 root schema identity policy。 */
 export interface JsonSchemaIdentity {
+    /** root `$id` 与配置 `schemas[].id` 的关系。 */
     readonly mode: JsonSchemaIdentityMode;
 }
-export type JsonSchemaReferenceSource = Readonly<{
+/** allowlisted 引用解析可读取的单一 Schema 来源及其固定边界。 */
+export type JsonSchemaReferenceSource = 
+/** Package 固定的 JSON Schema catalog；它不授权网络请求。 */
+Readonly<{
     readonly kind: "bundled";
     readonly catalog: "json-schema-2020-12";
 }> | Readonly<{
+    /** 只允许本 source 明确限定的 HTTPS reference scope。 */
     readonly kind: "https";
+    /** 调用方为本 source 选择的安全稳定 identity，不是请求 URL。 */
     readonly id: string;
+    /** 精确 HTTPS origin；不含 path、credentials、query 或 fragment。 */
     readonly origin: string;
+    /** 已授权 URL path 的边界；从 `/` 开始，非 root prefix 必须以 `/` 结束。 */
     readonly pathPrefix: string;
 }>;
-export type JsonSchemaReferenceResolution = Readonly<{
+/** 本次 Check 解析 local、bundled 与 allowlisted Schema 引用的封闭策略。 */
+export type JsonSchemaReferenceResolution = 
+/** 只使用 local schemas 和允许的 bundled catalog，不读取额外 HTTPS schema。 */
+Readonly<{
     readonly mode: "offline";
 }> | Readonly<{
+    /** 只从 `sources` 的精确 scope 读取额外 schema；没有 implicit registry、headers 或 redirects。 */
     readonly mode: "allowlisted";
+    /** 完整替换的明确 source 集合；每项决定自身可读取的 reference scope。 */
     readonly sources: readonly JsonSchemaReferenceSource[];
 }>;
+/** 调用方注册的一份 local schema resource；注册表不自动发现 schema。 */
 export interface RegisteredJsonSchema {
+    /** binding 与公开 facts 使用的安全 schema identity。 */
     readonly id: string;
+    /** 已由 `files` selection 批准的 normalized project-relative `.json` path。 */
     readonly path: string;
 }
+/** 调用方将一个已批准 local JSON instance 明确绑定到已注册 schema 的关系。 */
 export interface JsonSchemaInstanceBinding {
+    /** 本次 Check 内唯一、用于公开 facts 的 binding identity。 */
     readonly id: string;
+    /** 已由 `files` selection 批准的 normalized project-relative `.json` instance path。 */
     readonly instancePath: string;
+    /** 必须引用 `schemas` 中已注册 schema 的 identity。 */
     readonly schemaId: string;
 }
 /** `jsonSchemaValidation(options?)` 接受的可省略 authoring policy。 */

package/types/package-checks/json-validation/final-data.d.ts

@@ -1,9 +1,14 @@
 /** `json-validation` 在 passed/failed outcome 中发布的主数据。 */
 export interface JsonValidationFinalData {
+    /** 已完成 JSON parse 判定的文件数，恒等于 validFileCount 与 invalidFileCount 之和。 */
     readonly scannedFileCount: number;
+    /** 被 bounded strict-document boundary 接受为有效 JSON 的文件数。 */
     readonly validFileCount: number;
+    /** 形成 `too-large`、encoding、syntax 或 duplicate-key document issue 的文件数。 */
     readonly invalidFileCount: number;
+    /** 全部 invalid file 与 rejected input 的合计问题数。 */
     readonly issueCount: number;
+    /** files policy 已选中、但因不是 lower-case `.json` path 而被拒绝的输入数。 */
     readonly rejectedInputCount: number;
 }
 /** 验证计数不变量并脱离一份 `json-validation` canonical final-data object。 */

package/types/package-checks/maintenance-reminders/final-data.d.ts

@@ -17,30 +17,48 @@ export declare function isMaintenanceReminderId(value: unknown): value is string
 /** 判断 unknown value 是否为 Git 的完整 SHA-1 或 SHA-256 commit ID。 */
 export declare function isMaintenanceCommitId(value: unknown): value is string;
 export type MeasuredMaintenanceReminderAssessment = Readonly<{
+    /** 未超过任何阈值时为 clear；至少严格超过一个阈值时为 due。 */
     readonly assessment: "clear" | "due";
+    /** reminder 配置锁定的完整基线 commit ID。 */
     readonly baseCommit: string;
+    /** first-parent 区间内 numstat additions 与 deletions 的总和。 */
     readonly changedLines: number;
+    /** 从 HEAD 沿 first-parent 到 baseCommit 的 commit 数。 */
     readonly commitCount: number;
+    /** 实际值严格超过配置上限的维度；clear assessment 时为空。 */
     readonly exceeded: readonly ("commits" | "changed-lines")[];
+    /** 测量时 HEAD 的完整 commit ID。 */
     readonly headCommit: string;
+    /** Definition 中该 reminder 的稳定局部 ID。 */
     readonly id: string;
+    /** due 或 unavailable 是否阻断 Check 的配置模式。 */
     readonly mode: MaintenanceReminderMode;
 }>;
 export type UnavailableMaintenanceReminderAssessment = Readonly<{
+    /** 表示该 reminder 未能形成计数测量。 */
     readonly assessment: "unavailable";
+    /** reminder 配置锁定的完整基线 commit ID。 */
     readonly baseCommit: string;
+    /** unavailable assessment 不发布 partial changed-line count。 */
     readonly changedLines: null;
+    /** unavailable assessment 不发布 partial commit count。 */
     readonly commitCount: null;
+    /** unavailable assessment 不判定任何阈值已超过。 */
     readonly exceeded: readonly [];
+    /** 已成功解析时的完整 HEAD commit ID；解析 HEAD 失败时为 null。 */
     readonly headCommit: string | null;
+    /** Definition 中该 reminder 的稳定局部 ID。 */
     readonly id: string;
+    /** due 或 unavailable 是否阻断 Check 的配置模式。 */
     readonly mode: MaintenanceReminderMode;
+    /** 未能测量的稳定机器可读原因。 */
     readonly reason: MaintenanceReminderUnavailableReason;
 }>;
 /** 单条维护提醒的 measured 或 unavailable discriminated assessment。 */
 export type MaintenanceReminderAssessment = MeasuredMaintenanceReminderAssessment | UnavailableMaintenanceReminderAssessment;
 /** `maintenance-reminders` 在 passed/failed outcome 中发布的主数据。 */
 export interface MaintenanceRemindersFinalData {
+    /** 每个已配置 reminder 的唯一 assessment，按 Definition 顺序发布。 */
     readonly entries: readonly MaintenanceReminderAssessment[];
 }
 /** 验证 discriminated entry assessments 并脱离 canonical final data。 */

package/types/package-checks/markdown-link-validation/default-check.d.ts

@@ -4,15 +4,21 @@ import type { MarkdownLinkValidationOptions, ResolvedMarkdownLinkValidationOptio
 /**
  * 使用可省略的 source、target 与 work-limit policy 构造离线 Markdown 引用 Check。
  *
- * @param options - 省略字段由 package 补齐；files 数组是完整替换值，limits fields 可分别省略。
+ * @param options - 省略字段由 package 补齐；files 数组是完整替换值，limits fields 可分别省略；cache 省略时关闭，启用时由调用方提供 absolute、可信且可删除的 directory，其中本 Check 只维护一个 source-derived JSONL local state；调用方负责容量和删除，cache 不可用不改变 Check 结果。
  * @returns 固定 `markdown-link-validation` identity、完整冻结 options、parser 与执行逻辑。
- * @throws {TypeError} input 含未知字段、非法 target policy 或非法 work limit 时抛出。
+ * @throws {TypeError} input 含未知字段、非法 target policy、cache branch/directory 或非法 work limit 时抛出。
  * @example 离线 Markdown 本地链接完整性
  * ```ts
  * import { defineConfig, markdownLinkValidation, run } from "@zxyycom/vibe-check";
  *
+ * // 此调用方自有目录是 absolute、可删除的，并且可能保存 source-derived parse facts。
+ * const cacheDirectory = new URL(".vibe-check/markdown-link-parse-cache", import.meta.url).pathname;
  * const definition = defineConfig({
- *   checks: [markdownLinkValidation()],
+ *   checks: [
+ *     markdownLinkValidation({
+ *       cache: { enabled: true, directory: cacheDirectory }
+ *     })
+ *   ],
  *   outputs: {
  *     diagnosticLogging: { enabled: false },
  *     machinePublication: { enabled: false },

package/types/package-checks/markdown-link-validation/execution.d.ts

@@ -1,12 +1,10 @@
 import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
 import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
-import { type MarkdownLocalResolutionReason, type MarkdownSourceReadFailureReason } from "./local-resolver.ts";
 import type { MarkdownLinkValidationFinalData } from "./final-data.ts";
+export type { MarkdownLinkValidationUnavailableReason } from "./unavailable-reasons.ts";
 export declare const MARKDOWN_LINK_VALIDATION_CHECK_DEFINITION: {
     readonly checkId: "markdown-link-validation";
     readonly displayName: "Markdown link validation";
 };
-/** `markdown-link-validation` whole-Check unavailable outcome 的稳定 reason code。 */
-export type MarkdownLinkValidationUnavailableReason = "invalid-options" | "cancelled" | "occurrence-limit-exceeded" | "project-root-unavailable" | MarkdownLocalResolutionReason | MarkdownSourceReadFailureReason;
 /** 验证本 Check 选中的 Markdown source 的离线本地链接完整性。 */
 export declare function executeMarkdownLinkValidation(context: CheckExecutionContext<ResolvedMarkdownLinkValidationOptions>): Promise<CheckResult<MarkdownLinkValidationFinalData>>;

package/types/package-checks/markdown-link-validation/final-data.d.ts

@@ -1,9 +1,14 @@
 /** `markdown-link-validation` 在 passed/failed outcome 中发布的主数据。 */
 export interface MarkdownLinkValidationFinalData {
+    /** 已成功读取并完成 Markdown link occurrence 提取的 source 文件数。 */
     readonly sourceFileCount: number;
+    /** 从已处理 source 中提取的 semantic link occurrence 数。 */
     readonly occurrenceCount: number;
+    /** 进入 direct endpoint validation 的 logical occurrence 数，包括 target memo hit。 */
     readonly targetReadCount: number;
+    /** occurrence finding 与 rejected input 的合计数。 */
     readonly findingCount: number;
+    /** files policy 已选中、但因不是 `.md`/`.markdown` path 而被拒绝的输入数。 */
     readonly rejectedInputCount: number;
 }
 /** 验证计数不变量并脱离一份 canonical final-data object。 */

package/types/package-checks/markdown-link-validation/finding-messages.d.ts

@@ -0,0 +1,4 @@
+import type { CheckMessage } from "../../check/check.ts";
+import type { MarkdownLinkRecordCandidate } from "./records.ts";
+/** Projects completed Link findings without copying raw destinations into presentation. */
+export declare function markdownFindingMessages(candidates: readonly MarkdownLinkRecordCandidate[], rejectedPaths: readonly string[], blocking: boolean): readonly CheckMessage[];

package/types/package-checks/markdown-link-validation/local-resolution.d.ts

@@ -11,6 +11,7 @@ interface MarkdownLinkSource {
 interface MarkdownLocalResolver {
     readSource(rootRelativePath: string, maxMarkdownBytes: number): Promise<MarkdownSourceReadResult>;
     resolve(request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution>;
+    finalize(): Promise<void>;
     readonly targetReadCount: number;
 }
 interface MarkdownLocalResolutionRequest {
@@ -62,18 +63,23 @@ interface ParsedLocalDestination {
     readonly fragment: string | null;
     readonly isAbsolute: boolean;
 }
-interface RootContainedPath {
-    readonly kind: "contained" | "missing";
+type RootProbe = Readonly<{
+    readonly kind: "contained";
     readonly absolutePath: string;
-}
-type RootProbe = RootContainedPath | Readonly<{
+    /** The final component observation is present when containment walked it. */
+    readonly endpoint?: ExistingEndpointProbe;
+}> | Readonly<{
+    readonly kind: "missing";
+    readonly absolutePath: string;
+}> | Readonly<{
     readonly kind: "outside";
 }> | Readonly<{
     readonly kind: "unavailable";
 }>;
 type EndpointProbe = Readonly<{
     readonly kind: "missing";
-}> | Readonly<{
+}> | ExistingEndpointProbe;
+type ExistingEndpointProbe = Readonly<{
     readonly kind: "directory" | "file" | "unsupported" | "unavailable";
 }>;
 export declare function parseLocalDestination(rawDestination: string): ParsedLocalDestination | "not-local" | null;
@@ -89,4 +95,4 @@ export declare function sourceUnavailable(): MarkdownSourceReadResult;
 export declare function valid(target: MarkdownSafeTargetDescriptor): MarkdownLocalResolution;
 export declare function finding(reason: MarkdownLinkFindingReason, target: MarkdownSafeTargetDescriptor): MarkdownLocalResolution;
 export declare function unavailable(reason: MarkdownLocalResolutionReason): MarkdownLocalResolution;
-export type { MarkdownLinkSource, MarkdownLocalResolution, MarkdownLocalResolutionReason, MarkdownLocalResolver, MarkdownLocalResolverCreation, MarkdownLocalResolutionRequest, MarkdownSafeTargetDescriptor, MarkdownSourceReadResult, MarkdownSourceReadFailureReason, RootProbe, EndpointProbe, RootExternalTargetMode };
+export type { MarkdownLinkSource, MarkdownLocalResolution, MarkdownLocalResolutionReason, MarkdownLocalResolver, MarkdownLocalResolverCreation, MarkdownLocalResolutionRequest, MarkdownSafeTargetDescriptor, MarkdownSourceReadResult, MarkdownSourceReadFailureReason, RootProbe, EndpointProbe, ExistingEndpointProbe, RootExternalTargetMode };

package/types/package-checks/markdown-link-validation/local-resolver.d.ts

@@ -1,5 +1,6 @@
 import type { MarkdownLocalResolverCreation } from "./local-resolution.ts";
+import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
 /** Link-private, per-invocation state for source reads and direct local targets. */
-export declare function createMarkdownLocalResolver(projectRoot: string, maxTargetReads: number): Promise<MarkdownLocalResolverCreation>;
+export declare function createMarkdownLocalResolver(projectRoot: string, maxTargetReads: number, cache: ResolvedMarkdownLinkValidationOptions["cache"], signal: AbortSignal): Promise<MarkdownLocalResolverCreation>;
 export { anchorResolution, finding, isMarkdownPath, isNotFound, isRootRelativePath, isWithinRoot, parseLocalDestination, relativeSegments, sameRootRelativePath, sourceUnavailable, toSlashPath, unavailable, valid } from "./local-resolution.ts";
 export type { EndpointProbe, MarkdownLinkFindingReason, MarkdownLinkSource, MarkdownLocalResolution, MarkdownLocalResolutionReason, MarkdownLocalResolutionRequest, MarkdownLocalResolver, MarkdownLocalResolverCreation, MarkdownSafeTargetDescriptor, MarkdownSourceReadFailureReason, MarkdownSourceReadResult, RootExternalTargetMode, RootProbe } from "./local-resolution.ts";

package/types/package-checks/markdown-link-validation/options.d.ts

@@ -1,6 +1,13 @@
 import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
 import type { FindingPolicy } from "../code-quality-findings/policy.ts";
 export type MarkdownRootExternalTargetMode = "ignore" | "report" | "validate";
+/** 调用方显式拥有的 Link-private parse-facts local cache policy。 */
+type MarkdownLinkValidationCacheOptions = Readonly<{
+    readonly enabled: false;
+}> | Readonly<{
+    readonly enabled: true;
+    readonly directory: string;
+}>;
 /** 可省略的 Markdown validation work limits。 */
 export interface MarkdownLinkValidationLimitOptions {
     readonly maxMarkdownBytes?: number;
@@ -25,6 +32,12 @@ export interface MarkdownLinkValidationOptions {
     readonly requireNonEmptyDirectories?: boolean;
     /** 每次运行的 Markdown 内容、occurrence 和 direct target work 上限。 */
     readonly limits?: MarkdownLinkValidationLimitOptions;
+    /**
+     * 显式启用的、调用方拥有的 Link parse-facts persistent cache。省略时关闭；enabled directory 必须 absolute、可信且可删除。
+     * 本 Check 只在其中使用 `markdown-link-parse-facts-v1.jsonl` 保存 source-derived facts；调用方负责容量和删除，且不提供
+     * confidentiality、automatic cleanup、concurrency 或 durability guarantees。cache 不可用时 fresh-parse，Check 结果不变。
+     */
+    readonly cache?: MarkdownLinkValidationCacheOptions;
 }
 /** `markdown-link-validation` execution 消费的完整、冻结 options。 */
 export interface ResolvedMarkdownLinkValidationOptions {
@@ -35,9 +48,11 @@ export interface ResolvedMarkdownLinkValidationOptions {
     readonly validateCrossDocumentAnchors: boolean;
     readonly rootExternalTargetMode: MarkdownRootExternalTargetMode;
     readonly requireNonEmptyDirectories: boolean;
+    readonly cache: MarkdownLinkValidationCacheOptions;
     readonly limits: Readonly<{
         readonly maxMarkdownBytes: number;
         readonly maxOccurrences: number;
         readonly maxTargetReads: number;
     }>;
 }
+export {};

package/types/package-checks/markdown-link-validation/parse-facts-cache-payload.d.ts

@@ -0,0 +1,24 @@
+import type { MarkdownHeading, MarkdownLinkOccurrence, ParsedMarkdownLinkFacts } from "./markdown-parser.ts";
+/** Version the resolver memo and persistent identity share when parser facts change. */
+export declare const MARKDOWN_LINK_PARSE_FACTS_PARSER_CONTRACT_VERSION = "mdast-gfm-frontmatter-github-slug-v1";
+type MarkdownLinkParseFactsPayload = Readonly<{
+    readonly occurrences: readonly MarkdownLinkOccurrence[];
+    readonly headings: readonly MarkdownHeading[];
+}>;
+/**
+ * Serializes one complete Link-private JSONL envelope from immutable parser facts.
+ * The session owns when this line is appended; this codec owns its shape and identity.
+ */
+export declare function cacheEnvelopeLine(identityDigest: string, facts: ParsedMarkdownLinkFacts): string;
+/** Restores one complete, current-version JSONL envelope or rejects it as a cache miss. */
+export declare function parseCacheEnvelopeLine(line: string): Readonly<{
+    readonly identityDigest: string;
+    readonly facts: ParsedMarkdownLinkFacts;
+}> | undefined;
+/** SHA-256 identity over the current, exact authorized Markdown bytes. */
+export declare function markdownBytesDigest(bytes: Uint8Array): string;
+/** Converts parser-owned immutable facts to the closed persistent JSON payload. */
+export declare function projectMarkdownLinkParseFactsPayload(facts: ParsedMarkdownLinkFacts): MarkdownLinkParseFactsPayload;
+/** Strictly restores the Link-private persistent JSON payload to immutable parser facts. */
+export declare function parseMarkdownLinkParseFactsPayload(value: unknown): ParsedMarkdownLinkFacts;
+export {};

package/types/package-checks/markdown-link-validation/parse-facts-cache.d.ts

@@ -0,0 +1,13 @@
+import { type MarkdownLinkParseResult } from "./markdown-parser.ts";
+import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
+/**
+ * Link-private state for one resolver invocation's parse-facts cache lifecycle.
+ * It restores at most once, collects successful fresh facts by identity, and
+ * publishes at the execution terminal boundary.
+ */
+export declare class MarkdownLinkParseFactsSession {
+    #private;
+    constructor(cache: ResolvedMarkdownLinkValidationOptions["cache"]);
+    parse(bytes: Uint8Array, signal: AbortSignal): Promise<MarkdownLinkParseResult | undefined>;
+    finalize(signal: AbortSignal): Promise<void>;
+}

package/types/package-checks/markdown-link-validation/resolver-engine.d.ts

@@ -1,13 +1,15 @@
-import { type MarkdownLocalResolution, type MarkdownLocalResolutionRequest, type MarkdownLocalResolver, type MarkdownSafeTargetDescriptor, type MarkdownSourceReadResult } from "./local-resolution.ts";
+import { type MarkdownLocalResolution, type MarkdownLocalResolutionRequest, type MarkdownLocalResolver, type MarkdownSafeTargetDescriptor, type EndpointProbe } from "./local-resolution.ts";
+import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
 export declare class LinkLocalResolver implements MarkdownLocalResolver {
     #private;
-    constructor(canonicalProjectRoot: string, maxTargetReads: number);
+    constructor(canonicalProjectRoot: string, maxTargetReads: number, cache: ResolvedMarkdownLinkValidationOptions["cache"], signal: AbortSignal);
     get targetReadCount(): number;
-    readSource(rootRelativePath: string, maxMarkdownBytes: number): Promise<MarkdownSourceReadResult>;
+    finalize(): Promise<void>;
+    readSource(rootRelativePath: string, maxMarkdownBytes: number): Promise<import("./local-resolution.ts").MarkdownSourceReadResult>;
     resolve(request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution>;
     resolveRootContainedTarget(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution>;
     resolveExternalTarget(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution>;
-    resolveEndpoint(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest, target: MarkdownSafeTargetDescriptor): Promise<MarkdownLocalResolution>;
+    resolveEndpoint(endpoint: EndpointProbe, targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest, target: MarkdownSafeTargetDescriptor): Promise<MarkdownLocalResolution>;
     resolveFile(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest, target: MarkdownSafeTargetDescriptor): Promise<MarkdownLocalResolution>;
     resolveDirectory(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest, target: MarkdownSafeTargetDescriptor): Promise<MarkdownLocalResolution>;
     beginTargetValidation(): boolean;

package/types/package-checks/markdown-link-validation/source-reader.d.ts

@@ -0,0 +1,11 @@
+import type { MarkdownLinkParseResult } from "./markdown-parser.ts";
+import { type MarkdownSourceReadResult } from "./local-resolution.ts";
+export interface RootContainedMarkdownSourceReadRequest {
+    readonly canonicalProjectRoot: string;
+    readonly maxMarkdownBytes: number;
+    readonly parseMarkdownBytes: (bytes: Uint8Array) => Promise<MarkdownLinkParseResult | undefined>;
+    readonly rootRelativePath: string;
+    readonly signal: AbortSignal;
+}
+/** Reads one authorized Markdown source without granting target-resolution behavior. */
+export declare function readRootContainedMarkdownSource(request: RootContainedMarkdownSourceReadRequest): Promise<MarkdownSourceReadResult>;

package/types/package-checks/markdown-link-validation/unavailable-reasons.d.ts

@@ -0,0 +1,4 @@
+import type { MarkdownLocalResolutionReason, MarkdownSourceReadFailureReason } from "./local-resolver.ts";
+/** `markdown-link-validation` whole-Check unavailable outcome 的稳定 reason code。 */
+export type MarkdownLinkValidationUnavailableReason = "invalid-options" | "cancelled" | "occurrence-limit-exceeded" | "project-root-unavailable" | MarkdownLocalResolutionReason | MarkdownSourceReadFailureReason;
+export declare function markdownLinkUnavailableMessage(reason: MarkdownLinkValidationUnavailableReason): string;