@zxyycom/vibe-check 0.0.1 → 0.0.3

package/dist/esm/package-checks/markdown-link-validation/options-validation.mjs

@@ -1,18 +1,13 @@
-import { hasExactPlainRecordKeys, snapshotClosedRecord } from "../../data-boundary/closed-values.mjs";
+import { snapshotExactClosedRecord } from "../../data-boundary/closed-values.mjs";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.mjs";
 import { validProjectFileSelection } from "../project-files/configuration.mjs";
 import { validFindingPolicy } from "../code-quality-findings/policy.mjs";
-function exactRecord(value, keys) {
-    const record = snapshotClosedRecord(value);
-    return record !== undefined && hasExactPlainRecordKeys(record, keys) ? record : undefined;
-}
-function positiveSafeInteger(value) {
-    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
-}
+import { validLocalCacheOptions } from "../local-cache-options.mjs";
 function boundedPositiveSafeInteger(value, maximum) {
-    return positiveSafeInteger(value) && value <= maximum;
+    return isPositiveSafeInteger(value) && value <= maximum;
 }
 export function validMarkdownLinkValidationOptions(value) {
-    const options = exactRecord(value, [
+    const options = snapshotExactClosedRecord(value, [
         "files",
         "findingPolicy",
         "requireExistingTargets",
@@ -20,6 +15,7 @@ export function validMarkdownLinkValidationOptions(value) {
         "validateCrossDocumentAnchors",
         "rootExternalTargetMode",
         "requireNonEmptyDirectories",
+        "cache",
         "limits"
     ]);
     return options !== undefined && validOptionFields(options);
@@ -28,6 +24,7 @@ function validOptionFields(options) {
     return (validProjectFileSelection(options.files) &&
         validFindingPolicy(options.findingPolicy) &&
         validAnchorValidationOptions(options) &&
+        validLocalCacheOptions(options.cache) &&
         validMarkdownLinkLimits(options.limits));
 }
 function validAnchorValidationOptions(options) {
@@ -41,7 +38,11 @@ function validRootExternalTargetMode(value) {
     return value === "ignore" || value === "report" || value === "validate";
 }
 function validMarkdownLinkLimits(value) {
-    const limits = exactRecord(value, ["maxMarkdownBytes", "maxOccurrences", "maxTargetReads"]);
+    const limits = snapshotExactClosedRecord(value, [
+        "maxMarkdownBytes",
+        "maxOccurrences",
+        "maxTargetReads"
+    ]);
     return (limits !== undefined &&
         boundedPositiveSafeInteger(limits.maxMarkdownBytes, 16_777_216) &&
         boundedPositiveSafeInteger(limits.maxOccurrences, 100_000) &&

package/dist/esm/package-checks/markdown-link-validation/options-validation.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"options-validation.mjs","sourceRoot":"","sources":["../../../../src/package-checks/markdown-link-validation/options-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAGxE,SAAS,WAAW,CAClB,KAAc,EACd,IAAuB;IAEvB,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO,MAAM,KAAK,SAAS,IAAI,uBAAuB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5F,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAc;IACzC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;AAC/E,CAAC;AAED,SAAS,0BAA0B,CAAC,KAAc,EAAE,OAAe;IACjE,OAAO,mBAAmB,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,OAAO,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,kCAAkC,CAChD,KAAc;IAEd,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,EAAE;QACjC,OAAO;QACP,eAAe;QACf,wBAAwB;QACxB,6BAA6B;QAC7B,8BAA8B;QAC9B,wBAAwB;QACxB,4BAA4B;QAC5B,QAAQ;KACT,CAAC,CAAC;IACH,OAAO,OAAO,KAAK,SAAS,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAC7D,CAAC;AAED,SAAS,iBAAiB,CAAC,OAA0C;IACnE,OAAO,CACL,yBAAyB,CAAC,OAAO,CAAC,KAAK,CAAC;QACxC,kBAAkB,CAAC,OAAO,CAAC,aAAa,CAAC;QACzC,4BAA4B,CAAC,OAAO,CAAC;QACrC,uBAAuB,CAAC,OAAO,CAAC,MAAM,CAAC,CACxC,CAAC;AACJ,CAAC;AAED,SAAS,4BAA4B,CAAC,OAA0C;IAC9E,OAAO,CACL,OAAO,OAAO,CAAC,sBAAsB,KAAK,SAAS;QACnD,OAAO,OAAO,CAAC,2BAA2B,KAAK,SAAS;QACxD,OAAO,OAAO,CAAC,4BAA4B,KAAK,SAAS;QACzD,2BAA2B,CAAC,OAAO,CAAC,sBAAsB,CAAC;QAC3D,OAAO,OAAO,CAAC,0BAA0B,KAAK,SAAS,CACxD,CAAC;AACJ,CAAC;AAED,SAAS,2BAA2B,CAAC,KAAc;IACjD,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,UAAU,CAAC;AAC1E,CAAC;AAED,SAAS,uBAAuB,CAAC,KAAc;IAC7C,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,EAAE,CAAC,kBAAkB,EAAE,gBAAgB,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAC5F,OAAO,CACL,MAAM,KAAK,SAAS;QACpB,0BAA0B,CAAC,MAAM,CAAC,gBAAgB,EAAE,UAAU,CAAC;QAC/D,0BAA0B,CAAC,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC;QAC1D,0BAA0B,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAC1D,CAAC;AACJ,CAAC","sourcesContent":["import {\n  hasExactPlainRecordKeys,\n  snapshotClosedRecord\n} from \"../../data-boundary/closed-values.ts\";\nimport { validProjectFileSelection } from \"../project-files/configuration.ts\";\nimport { validFindingPolicy } from \"../code-quality-findings/policy.ts\";\nimport type { ResolvedMarkdownLinkValidationOptions } from \"./options.ts\";\n\nfunction exactRecord(\n  value: unknown,\n  keys: readonly string[]\n): Readonly<Record<string, unknown>> | undefined {\n  const record = snapshotClosedRecord(value);\n  return record !== undefined && hasExactPlainRecordKeys(record, keys) ? record : undefined;\n}\n\nfunction positiveSafeInteger(value: unknown): value is number {\n  return typeof value === \"number\" && Number.isSafeInteger(value) && value > 0;\n}\n\nfunction boundedPositiveSafeInteger(value: unknown, maximum: number): value is number {\n  return positiveSafeInteger(value) && value <= maximum;\n}\n\nexport function validMarkdownLinkValidationOptions(\n  value: unknown\n): value is ResolvedMarkdownLinkValidationOptions {\n  const options = exactRecord(value, [\n    \"files\",\n    \"findingPolicy\",\n    \"requireExistingTargets\",\n    \"validateSameDocumentAnchors\",\n    \"validateCrossDocumentAnchors\",\n    \"rootExternalTargetMode\",\n    \"requireNonEmptyDirectories\",\n    \"limits\"\n  ]);\n  return options !== undefined && validOptionFields(options);\n}\n\nfunction validOptionFields(options: Readonly<Record<string, unknown>>): boolean {\n  return (\n    validProjectFileSelection(options.files) &&\n    validFindingPolicy(options.findingPolicy) &&\n    validAnchorValidationOptions(options) &&\n    validMarkdownLinkLimits(options.limits)\n  );\n}\n\nfunction validAnchorValidationOptions(options: Readonly<Record<string, unknown>>): boolean {\n  return (\n    typeof options.requireExistingTargets === \"boolean\" &&\n    typeof options.validateSameDocumentAnchors === \"boolean\" &&\n    typeof options.validateCrossDocumentAnchors === \"boolean\" &&\n    validRootExternalTargetMode(options.rootExternalTargetMode) &&\n    typeof options.requireNonEmptyDirectories === \"boolean\"\n  );\n}\n\nfunction validRootExternalTargetMode(value: unknown): boolean {\n  return value === \"ignore\" || value === \"report\" || value === \"validate\";\n}\n\nfunction validMarkdownLinkLimits(value: unknown): boolean {\n  const limits = exactRecord(value, [\"maxMarkdownBytes\", \"maxOccurrences\", \"maxTargetReads\"]);\n  return (\n    limits !== undefined &&\n    boundedPositiveSafeInteger(limits.maxMarkdownBytes, 16_777_216) &&\n    boundedPositiveSafeInteger(limits.maxOccurrences, 100_000) &&\n    boundedPositiveSafeInteger(limits.maxTargetReads, 10_000)\n  );\n}\n"]}
+{"version":3,"file":"options-validation.mjs","sourceRoot":"","sources":["../../../../src/package-checks/markdown-link-validation/options-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAGnE,SAAS,0BAA0B,CAAC,KAAc,EAAE,OAAe;IACjE,OAAO,qBAAqB,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,OAAO,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,kCAAkC,CAChD,KAAc;IAEd,MAAM,OAAO,GAAG,yBAAyB,CAAC,KAAK,EAAE;QAC/C,OAAO;QACP,eAAe;QACf,wBAAwB;QACxB,6BAA6B;QAC7B,8BAA8B;QAC9B,wBAAwB;QACxB,4BAA4B;QAC5B,OAAO;QACP,QAAQ;KACT,CAAC,CAAC;IACH,OAAO,OAAO,KAAK,SAAS,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAC7D,CAAC;AAED,SAAS,iBAAiB,CAAC,OAA0C;IACnE,OAAO,CACL,yBAAyB,CAAC,OAAO,CAAC,KAAK,CAAC;QACxC,kBAAkB,CAAC,OAAO,CAAC,aAAa,CAAC;QACzC,4BAA4B,CAAC,OAAO,CAAC;QACrC,sBAAsB,CAAC,OAAO,CAAC,KAAK,CAAC;QACrC,uBAAuB,CAAC,OAAO,CAAC,MAAM,CAAC,CACxC,CAAC;AACJ,CAAC;AAED,SAAS,4BAA4B,CAAC,OAA0C;IAC9E,OAAO,CACL,OAAO,OAAO,CAAC,sBAAsB,KAAK,SAAS;QACnD,OAAO,OAAO,CAAC,2BAA2B,KAAK,SAAS;QACxD,OAAO,OAAO,CAAC,4BAA4B,KAAK,SAAS;QACzD,2BAA2B,CAAC,OAAO,CAAC,sBAAsB,CAAC;QAC3D,OAAO,OAAO,CAAC,0BAA0B,KAAK,SAAS,CACxD,CAAC;AACJ,CAAC;AAED,SAAS,2BAA2B,CAAC,KAAc;IACjD,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,UAAU,CAAC;AAC1E,CAAC;AAED,SAAS,uBAAuB,CAAC,KAAc;IAC7C,MAAM,MAAM,GAAG,yBAAyB,CAAC,KAAK,EAAE;QAC9C,kBAAkB;QAClB,gBAAgB;QAChB,gBAAgB;KACjB,CAAC,CAAC;IACH,OAAO,CACL,MAAM,KAAK,SAAS;QACpB,0BAA0B,CAAC,MAAM,CAAC,gBAAgB,EAAE,UAAU,CAAC;QAC/D,0BAA0B,CAAC,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC;QAC1D,0BAA0B,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAC1D,CAAC;AACJ,CAAC","sourcesContent":["import { snapshotExactClosedRecord } from \"../../data-boundary/closed-values.ts\";\nimport { isPositiveSafeInteger } from \"../../data-boundary/value-shapes.ts\";\nimport { validProjectFileSelection } from \"../project-files/configuration.ts\";\nimport { validFindingPolicy } from \"../code-quality-findings/policy.ts\";\nimport { validLocalCacheOptions } from \"../local-cache-options.ts\";\nimport type { ResolvedMarkdownLinkValidationOptions } from \"./options.ts\";\n\nfunction boundedPositiveSafeInteger(value: unknown, maximum: number): value is number {\n  return isPositiveSafeInteger(value) && value <= maximum;\n}\n\nexport function validMarkdownLinkValidationOptions(\n  value: unknown\n): value is ResolvedMarkdownLinkValidationOptions {\n  const options = snapshotExactClosedRecord(value, [\n    \"files\",\n    \"findingPolicy\",\n    \"requireExistingTargets\",\n    \"validateSameDocumentAnchors\",\n    \"validateCrossDocumentAnchors\",\n    \"rootExternalTargetMode\",\n    \"requireNonEmptyDirectories\",\n    \"cache\",\n    \"limits\"\n  ]);\n  return options !== undefined && validOptionFields(options);\n}\n\nfunction validOptionFields(options: Readonly<Record<string, unknown>>): boolean {\n  return (\n    validProjectFileSelection(options.files) &&\n    validFindingPolicy(options.findingPolicy) &&\n    validAnchorValidationOptions(options) &&\n    validLocalCacheOptions(options.cache) &&\n    validMarkdownLinkLimits(options.limits)\n  );\n}\n\nfunction validAnchorValidationOptions(options: Readonly<Record<string, unknown>>): boolean {\n  return (\n    typeof options.requireExistingTargets === \"boolean\" &&\n    typeof options.validateSameDocumentAnchors === \"boolean\" &&\n    typeof options.validateCrossDocumentAnchors === \"boolean\" &&\n    validRootExternalTargetMode(options.rootExternalTargetMode) &&\n    typeof options.requireNonEmptyDirectories === \"boolean\"\n  );\n}\n\nfunction validRootExternalTargetMode(value: unknown): boolean {\n  return value === \"ignore\" || value === \"report\" || value === \"validate\";\n}\n\nfunction validMarkdownLinkLimits(value: unknown): boolean {\n  const limits = snapshotExactClosedRecord(value, [\n    \"maxMarkdownBytes\",\n    \"maxOccurrences\",\n    \"maxTargetReads\"\n  ]);\n  return (\n    limits !== undefined &&\n    boundedPositiveSafeInteger(limits.maxMarkdownBytes, 16_777_216) &&\n    boundedPositiveSafeInteger(limits.maxOccurrences, 100_000) &&\n    boundedPositiveSafeInteger(limits.maxTargetReads, 10_000)\n  );\n}\n"]}

package/dist/esm/package-checks/markdown-link-validation/options.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"options.mjs","sourceRoot":"","sources":["../../../../src/package-checks/markdown-link-validation/options.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  ProjectFileSelection,\n  ProjectFileSelectionOptions\n} from \"../project-files/configuration.ts\";\nimport type { FindingPolicy } from \"../code-quality-findings/policy.ts\";\n\nexport type MarkdownRootExternalTargetMode = \"ignore\" | \"report\" | \"validate\";\n\n/** 可省略的 Markdown validation work limits。 */\nexport interface MarkdownLinkValidationLimitOptions {\n  readonly maxMarkdownBytes?: number;\n  readonly maxOccurrences?: number;\n  readonly maxTargetReads?: number;\n}\n\n/** `markdownLinkValidation(options?)` 接受的可省略 authoring policy。 */\nexport interface MarkdownLinkValidationOptions {\n  /** 参与本 Check 的 Markdown source selection；省略字段使用 package defaults。 */\n  readonly files?: ProjectFileSelectionOptions;\n  /** local-reference finding 是否使本 Check failed；省略时为 non-blocking。 */\n  readonly findingPolicy?: FindingPolicy;\n  /** `false` 时缺失的本地文件或目录不构成 finding。 */\n  readonly requireExistingTargets?: boolean;\n  /** 是否检查 `#anchor` 对当前 Markdown 文档标题的引用。 */\n  readonly validateSameDocumentAnchors?: boolean;\n  /** 是否检查直接指向的 Markdown 文件中的 `#anchor`。 */\n  readonly validateCrossDocumentAnchors?: boolean;\n  /** root 外本机目标的授权模式；不授权网络请求。 */\n  readonly rootExternalTargetMode?: MarkdownRootExternalTargetMode;\n  /** 是否将空目录目标视为 finding。 */\n  readonly requireNonEmptyDirectories?: boolean;\n  /** 每次运行的 Markdown 内容、occurrence 和 direct target work 上限。 */\n  readonly limits?: MarkdownLinkValidationLimitOptions;\n}\n\n/** `markdown-link-validation` execution 消费的完整、冻结 options。 */\nexport interface ResolvedMarkdownLinkValidationOptions {\n  readonly files: ProjectFileSelection;\n  readonly findingPolicy: FindingPolicy;\n  readonly requireExistingTargets: boolean;\n  readonly validateSameDocumentAnchors: boolean;\n  readonly validateCrossDocumentAnchors: boolean;\n  readonly rootExternalTargetMode: MarkdownRootExternalTargetMode;\n  readonly requireNonEmptyDirectories: boolean;\n  readonly limits: Readonly<{\n    readonly maxMarkdownBytes: number;\n    readonly maxOccurrences: number;\n    readonly maxTargetReads: number;\n  }>;\n}\n"]}
+{"version":3,"file":"options.mjs","sourceRoot":"","sources":["../../../../src/package-checks/markdown-link-validation/options.ts"],"names":[],"mappings":"","sourcesContent":["import type { PackageCheckAuthoringOptions } from \"../check-authoring.ts\";\nimport type {\n  ProjectFileSelection,\n  ProjectFileSelectionOptions\n} from \"../project-files/configuration.ts\";\nimport type { FindingPolicy } from \"../code-quality-findings/policy.ts\";\nimport type { LocalCacheOptions } from \"../local-cache-options.ts\";\n\nexport type MarkdownRootExternalTargetMode = \"ignore\" | \"report\" | \"validate\";\n\n/** 调用方显式拥有的 Link-private parse-facts local cache policy。 */\ntype MarkdownLinkValidationCacheOptions = LocalCacheOptions;\n\n/** 可省略的 Markdown validation work limits。 */\nexport interface MarkdownLinkValidationLimitOptions {\n  readonly maxMarkdownBytes?: number;\n  readonly maxOccurrences?: number;\n  readonly maxTargetReads?: number;\n}\n\n/** `markdownLinkValidation(options?)` 接受的可省略 authoring policy。 */\nexport interface MarkdownLinkValidationOptions<\n  Id extends string = string\n> extends PackageCheckAuthoringOptions<Id> {\n  /** 参与本 Check 的 Markdown source selection；省略字段使用 package defaults。 */\n  readonly files?: ProjectFileSelectionOptions;\n  /** local-reference finding 是否使本 Check failed；省略时为 non-blocking。 */\n  readonly findingPolicy?: FindingPolicy;\n  /** `false` 时缺失的本地文件或目录不构成 finding。 */\n  readonly requireExistingTargets?: boolean;\n  /** 是否检查 `#anchor` 对当前 Markdown 文档标题的引用。 */\n  readonly validateSameDocumentAnchors?: boolean;\n  /** 是否检查直接指向的 Markdown 文件中的 `#anchor`。 */\n  readonly validateCrossDocumentAnchors?: boolean;\n  /** root 外本机目标的授权模式；不授权网络请求。 */\n  readonly rootExternalTargetMode?: MarkdownRootExternalTargetMode;\n  /** 是否将空目录目标视为 finding。 */\n  readonly requireNonEmptyDirectories?: boolean;\n  /** 每次运行的 Markdown 内容、occurrence 和 direct target work 上限。 */\n  readonly limits?: MarkdownLinkValidationLimitOptions;\n  /**\n   * 显式启用的、调用方拥有的 Link parse-facts persistent cache。省略时关闭；enabled directory 必须 absolute、可信且可删除。\n   * 本 Check 只在其中使用 `markdown-link-parse-facts-v1.jsonl` 保存 source-derived facts；调用方负责容量和删除，且不提供\n   * confidentiality、automatic cleanup、concurrency 或 durability guarantees。cache 不可用时 fresh-parse，Check 结果不变。\n   */\n  readonly cache?: MarkdownLinkValidationCacheOptions;\n}\n\n/** `markdown-link-validation` execution 消费的完整、冻结 options。 */\nexport interface ResolvedMarkdownLinkValidationOptions {\n  readonly files: ProjectFileSelection;\n  readonly findingPolicy: FindingPolicy;\n  readonly requireExistingTargets: boolean;\n  readonly validateSameDocumentAnchors: boolean;\n  readonly validateCrossDocumentAnchors: boolean;\n  readonly rootExternalTargetMode: MarkdownRootExternalTargetMode;\n  readonly requireNonEmptyDirectories: boolean;\n  readonly cache: MarkdownLinkValidationCacheOptions;\n  readonly limits: Readonly<{\n    readonly maxMarkdownBytes: number;\n    readonly maxOccurrences: number;\n    readonly maxTargetReads: number;\n  }>;\n}\n"]}

package/dist/esm/package-checks/markdown-link-validation/parse-facts-cache-payload.mjs

@@ -0,0 +1,184 @@
+import { createHash } from "node:crypto";
+import { snapshotClosedArray, snapshotExactClosedRecord } from "../../data-boundary/closed-values.mjs";
+import { canonicalJsonText } from "../../data-boundary/canonical-data.mjs";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.mjs";
+const CACHE_FORMAT_VERSION = "markdown-link-parse-facts-jsonl-v1";
+const CACHE_PAYLOAD_VERSION = "1";
+/** Version the resolver memo and persistent identity share when parser facts change. */
+export const MARKDOWN_LINK_PARSE_FACTS_PARSER_CONTRACT_VERSION = "mdast-gfm-frontmatter-github-slug-v1";
+const MAX_FACTS_PER_DOCUMENT = 100_000;
+const MAX_FACT_STRING_LENGTH = 16_777_216;
+/**
+ * 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 function cacheEnvelopeLine(identityDigest, facts) {
+    return `${canonicalJsonText({
+        cacheFormatVersion: CACHE_FORMAT_VERSION,
+        identityDigest,
+        parserContractVersion: MARKDOWN_LINK_PARSE_FACTS_PARSER_CONTRACT_VERSION,
+        payloadVersion: CACHE_PAYLOAD_VERSION,
+        payload: projectMarkdownLinkParseFactsPayload(facts)
+    })}\n`;
+}
+/** Restores one complete, current-version JSONL envelope or rejects it as a cache miss. */
+export function parseCacheEnvelopeLine(line) {
+    try {
+        const envelope = snapshotExactClosedRecord(JSON.parse(line), [
+            "cacheFormatVersion",
+            "identityDigest",
+            "parserContractVersion",
+            "payloadVersion",
+            "payload"
+        ]);
+        if (!isCurrentCacheEnvelope(envelope))
+            return undefined;
+        return Object.freeze({
+            identityDigest: envelope.identityDigest,
+            facts: parseMarkdownLinkParseFactsPayload(envelope.payload)
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+/** SHA-256 identity over the current, exact authorized Markdown bytes. */
+export function markdownBytesDigest(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Converts parser-owned immutable facts to the closed persistent JSON payload. */
+export function projectMarkdownLinkParseFactsPayload(facts) {
+    return Object.freeze({
+        occurrences: Object.freeze(facts.occurrences.map((occurrence) => Object.freeze({
+            kind: occurrence.kind,
+            rawDestination: occurrence.rawDestination,
+            range: projectSourceRange(occurrence.range)
+        }))),
+        headings: Object.freeze(facts.headings.map((heading) => Object.freeze({ slug: heading.slug, range: projectSourceRange(heading.range) })))
+    });
+}
+/** Strictly restores the Link-private persistent JSON payload to immutable parser facts. */
+export function parseMarkdownLinkParseFactsPayload(value) {
+    const payload = snapshotExactClosedRecord(value, ["occurrences", "headings"]);
+    if (payload === undefined)
+        throw new TypeError("Markdown Link cache payload must be closed");
+    const occurrences = parseOccurrences(payload.occurrences);
+    const headings = parseHeadings(payload.headings);
+    if (occurrences === undefined || headings === undefined) {
+        throw new TypeError("Markdown Link cache payload contains invalid parse facts");
+    }
+    return Object.freeze({ occurrences, headings });
+}
+function isCurrentCacheEnvelope(envelope) {
+    return (envelope?.cacheFormatVersion === CACHE_FORMAT_VERSION &&
+        validIdentityDigest(envelope?.identityDigest) &&
+        envelope?.parserContractVersion === MARKDOWN_LINK_PARSE_FACTS_PARSER_CONTRACT_VERSION &&
+        envelope?.payloadVersion === CACHE_PAYLOAD_VERSION);
+}
+function validIdentityDigest(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
+}
+function parseOccurrences(value) {
+    const values = boundedPayloadArray(value);
+    if (values === undefined)
+        return undefined;
+    const occurrences = [];
+    for (const candidate of values) {
+        const occurrence = snapshotExactClosedRecord(candidate, ["kind", "rawDestination", "range"]);
+        if (occurrence === undefined ||
+            (occurrence.kind !== "image" && occurrence.kind !== "link") ||
+            !validFactString(occurrence.rawDestination)) {
+            return undefined;
+        }
+        const range = parseSourceRange(occurrence.range);
+        if (range === undefined)
+            return undefined;
+        occurrences.push(Object.freeze({ kind: occurrence.kind, rawDestination: occurrence.rawDestination, range }));
+    }
+    return Object.freeze(occurrences);
+}
+function parseHeadings(value) {
+    const values = boundedPayloadArray(value);
+    if (values === undefined)
+        return undefined;
+    const headings = [];
+    for (const candidate of values) {
+        const heading = snapshotExactClosedRecord(candidate, ["slug", "range"]);
+        if (heading === undefined || !validFactString(heading.slug))
+            return undefined;
+        const range = parseSourceRange(heading.range);
+        if (range === undefined)
+            return undefined;
+        headings.push(Object.freeze({ slug: heading.slug, range }));
+    }
+    return Object.freeze(headings);
+}
+function boundedPayloadArray(value) {
+    const values = snapshotClosedArray(value);
+    return values !== undefined && values.length <= MAX_FACTS_PER_DOCUMENT ? values : undefined;
+}
+function validFactString(value) {
+    return (typeof value === "string" &&
+        value.length <= MAX_FACT_STRING_LENGTH &&
+        !hasUnpairedSurrogate(value));
+}
+function parseSourceRange(value) {
+    const range = snapshotExactClosedRecord(value, ["startOffset", "endOffset", "start", "end"]);
+    if (range === undefined ||
+        !boundedNonNegativeSafeInteger(range.startOffset) ||
+        !boundedNonNegativeSafeInteger(range.endOffset) ||
+        range.endOffset < range.startOffset) {
+        return undefined;
+    }
+    const start = parseSourcePosition(range.start);
+    const end = parseSourcePosition(range.end);
+    if (start === undefined || end === undefined || !sourcePositionFollows(end, start)) {
+        return undefined;
+    }
+    return Object.freeze({ startOffset: range.startOffset, endOffset: range.endOffset, start, end });
+}
+function sourcePositionFollows(end, start) {
+    return end.line > start.line || (end.line === start.line && end.column >= start.column);
+}
+function parseSourcePosition(value) {
+    const position = snapshotExactClosedRecord(value, ["line", "column"]);
+    if (position === undefined ||
+        !boundedPositiveSafeInteger(position.line) ||
+        !boundedPositiveSafeInteger(position.column)) {
+        return undefined;
+    }
+    return Object.freeze({ line: position.line, column: position.column });
+}
+function projectSourceRange(range) {
+    return Object.freeze({
+        startOffset: range.startOffset,
+        endOffset: range.endOffset,
+        start: Object.freeze({ line: range.start.line, column: range.start.column }),
+        end: Object.freeze({ line: range.end.line, column: range.end.column })
+    });
+}
+function boundedNonNegativeSafeInteger(value) {
+    return (typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value >= 0 &&
+        value <= MAX_FACT_STRING_LENGTH);
+}
+function boundedPositiveSafeInteger(value) {
+    return isPositiveSafeInteger(value) && value <= MAX_FACT_STRING_LENGTH + 1;
+}
+function hasUnpairedSurrogate(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+            const nextCodeUnit = value.charCodeAt(index + 1);
+            if (!(nextCodeUnit >= 0xdc00 && nextCodeUnit <= 0xdfff))
+                return true;
+            index += 1;
+            continue;
+        }
+        if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=parse-facts-cache-payload.mjs.map

package/dist/esm/package-checks/markdown-link-validation/parse-facts-cache-payload.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-facts-cache-payload.mjs","sourceRoot":"","sources":["../../../../src/package-checks/markdown-link-validation/parse-facts-cache-payload.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\n\nimport {\n  snapshotClosedArray,\n  snapshotExactClosedRecord\n} from \"../../data-boundary/closed-values.ts\";\nimport { canonicalJsonText } from \"../../data-boundary/canonical-data.ts\";\nimport { isPositiveSafeInteger } from \"../../data-boundary/value-shapes.ts\";\nimport type {\n  MarkdownHeading,\n  MarkdownLinkOccurrence,\n  MarkdownSourcePosition,\n  MarkdownSourceRange,\n  ParsedMarkdownLinkFacts\n} from \"./markdown-parser.ts\";\n\nconst CACHE_FORMAT_VERSION = \"markdown-link-parse-facts-jsonl-v1\";\nconst CACHE_PAYLOAD_VERSION = \"1\";\n/** Version the resolver memo and persistent identity share when parser facts change. */\nexport const MARKDOWN_LINK_PARSE_FACTS_PARSER_CONTRACT_VERSION =\n  \"mdast-gfm-frontmatter-github-slug-v1\";\nconst MAX_FACTS_PER_DOCUMENT = 100_000;\nconst MAX_FACT_STRING_LENGTH = 16_777_216;\n\ntype MarkdownLinkParseFactsPayload = Readonly<{\n  readonly occurrences: readonly MarkdownLinkOccurrence[];\n  readonly headings: readonly MarkdownHeading[];\n}>;\n\n/**\n * Serializes one complete Link-private JSONL envelope from immutable parser facts.\n * The session owns when this line is appended; this codec owns its shape and identity.\n */\nexport function cacheEnvelopeLine(identityDigest: string, facts: ParsedMarkdownLinkFacts): string {\n  return `${canonicalJsonText({\n    cacheFormatVersion: CACHE_FORMAT_VERSION,\n    identityDigest,\n    parserContractVersion: MARKDOWN_LINK_PARSE_FACTS_PARSER_CONTRACT_VERSION,\n    payloadVersion: CACHE_PAYLOAD_VERSION,\n    payload: projectMarkdownLinkParseFactsPayload(facts)\n  })}\\n`;\n}\n\n/** Restores one complete, current-version JSONL envelope or rejects it as a cache miss. */\nexport function parseCacheEnvelopeLine(\n  line: string\n):\n  | Readonly<{ readonly identityDigest: string; readonly facts: ParsedMarkdownLinkFacts }>\n  | undefined {\n  try {\n    const envelope = snapshotExactClosedRecord(JSON.parse(line), [\n      \"cacheFormatVersion\",\n      \"identityDigest\",\n      \"parserContractVersion\",\n      \"payloadVersion\",\n      \"payload\"\n    ]);\n    if (!isCurrentCacheEnvelope(envelope)) return undefined;\n    return Object.freeze({\n      identityDigest: envelope.identityDigest,\n      facts: parseMarkdownLinkParseFactsPayload(envelope.payload)\n    });\n  } catch {\n    return undefined;\n  }\n}\n\n/** SHA-256 identity over the current, exact authorized Markdown bytes. */\nexport function markdownBytesDigest(bytes: Uint8Array): string {\n  return createHash(\"sha256\").update(bytes).digest(\"hex\");\n}\n\n/** Converts parser-owned immutable facts to the closed persistent JSON payload. */\nexport function projectMarkdownLinkParseFactsPayload(\n  facts: ParsedMarkdownLinkFacts\n): MarkdownLinkParseFactsPayload {\n  return Object.freeze({\n    occurrences: Object.freeze(\n      facts.occurrences.map((occurrence) =>\n        Object.freeze({\n          kind: occurrence.kind,\n          rawDestination: occurrence.rawDestination,\n          range: projectSourceRange(occurrence.range)\n        })\n      )\n    ),\n    headings: Object.freeze(\n      facts.headings.map((heading) =>\n        Object.freeze({ slug: heading.slug, range: projectSourceRange(heading.range) })\n      )\n    )\n  });\n}\n\n/** Strictly restores the Link-private persistent JSON payload to immutable parser facts. */\nexport function parseMarkdownLinkParseFactsPayload(value: unknown): ParsedMarkdownLinkFacts {\n  const payload = snapshotExactClosedRecord(value, [\"occurrences\", \"headings\"]);\n  if (payload === undefined) throw new TypeError(\"Markdown Link cache payload must be closed\");\n  const occurrences = parseOccurrences(payload.occurrences);\n  const headings = parseHeadings(payload.headings);\n  if (occurrences === undefined || headings === undefined) {\n    throw new TypeError(\"Markdown Link cache payload contains invalid parse facts\");\n  }\n  return Object.freeze({ occurrences, headings });\n}\n\nfunction isCurrentCacheEnvelope(\n  envelope: Readonly<Record<string, unknown>> | undefined\n): envelope is Readonly<{\n  readonly identityDigest: string;\n  readonly payload: unknown;\n}> {\n  return (\n    envelope?.cacheFormatVersion === CACHE_FORMAT_VERSION &&\n    validIdentityDigest(envelope?.identityDigest) &&\n    envelope?.parserContractVersion === MARKDOWN_LINK_PARSE_FACTS_PARSER_CONTRACT_VERSION &&\n    envelope?.payloadVersion === CACHE_PAYLOAD_VERSION\n  );\n}\n\nfunction validIdentityDigest(value: unknown): value is string {\n  return typeof value === \"string\" && /^[a-f0-9]{64}$/u.test(value);\n}\n\nfunction parseOccurrences(value: unknown): readonly MarkdownLinkOccurrence[] | undefined {\n  const values = boundedPayloadArray(value);\n  if (values === undefined) return undefined;\n  const occurrences: MarkdownLinkOccurrence[] = [];\n  for (const candidate of values) {\n    const occurrence = snapshotExactClosedRecord(candidate, [\"kind\", \"rawDestination\", \"range\"]);\n    if (\n      occurrence === undefined ||\n      (occurrence.kind !== \"image\" && occurrence.kind !== \"link\") ||\n      !validFactString(occurrence.rawDestination)\n    ) {\n      return undefined;\n    }\n    const range = parseSourceRange(occurrence.range);\n    if (range === undefined) return undefined;\n    occurrences.push(\n      Object.freeze({ kind: occurrence.kind, rawDestination: occurrence.rawDestination, range })\n    );\n  }\n  return Object.freeze(occurrences);\n}\n\nfunction parseHeadings(value: unknown): readonly MarkdownHeading[] | undefined {\n  const values = boundedPayloadArray(value);\n  if (values === undefined) return undefined;\n  const headings: MarkdownHeading[] = [];\n  for (const candidate of values) {\n    const heading = snapshotExactClosedRecord(candidate, [\"slug\", \"range\"]);\n    if (heading === undefined || !validFactString(heading.slug)) return undefined;\n    const range = parseSourceRange(heading.range);\n    if (range === undefined) return undefined;\n    headings.push(Object.freeze({ slug: heading.slug, range }));\n  }\n  return Object.freeze(headings);\n}\n\nfunction boundedPayloadArray(value: unknown): readonly unknown[] | undefined {\n  const values = snapshotClosedArray(value);\n  return values !== undefined && values.length <= MAX_FACTS_PER_DOCUMENT ? values : undefined;\n}\n\nfunction validFactString(value: unknown): value is string {\n  return (\n    typeof value === \"string\" &&\n    value.length <= MAX_FACT_STRING_LENGTH &&\n    !hasUnpairedSurrogate(value)\n  );\n}\n\nfunction parseSourceRange(value: unknown): MarkdownSourceRange | undefined {\n  const range = snapshotExactClosedRecord(value, [\"startOffset\", \"endOffset\", \"start\", \"end\"]);\n  if (\n    range === undefined ||\n    !boundedNonNegativeSafeInteger(range.startOffset) ||\n    !boundedNonNegativeSafeInteger(range.endOffset) ||\n    range.endOffset < range.startOffset\n  ) {\n    return undefined;\n  }\n  const start = parseSourcePosition(range.start);\n  const end = parseSourcePosition(range.end);\n  if (start === undefined || end === undefined || !sourcePositionFollows(end, start)) {\n    return undefined;\n  }\n  return Object.freeze({ startOffset: range.startOffset, endOffset: range.endOffset, start, end });\n}\n\nfunction sourcePositionFollows(\n  end: MarkdownSourcePosition,\n  start: MarkdownSourcePosition\n): boolean {\n  return end.line > start.line || (end.line === start.line && end.column >= start.column);\n}\n\nfunction parseSourcePosition(value: unknown): MarkdownSourcePosition | undefined {\n  const position = snapshotExactClosedRecord(value, [\"line\", \"column\"]);\n  if (\n    position === undefined ||\n    !boundedPositiveSafeInteger(position.line) ||\n    !boundedPositiveSafeInteger(position.column)\n  ) {\n    return undefined;\n  }\n  return Object.freeze({ line: position.line, column: position.column });\n}\n\nfunction projectSourceRange(range: MarkdownSourceRange): MarkdownSourceRange {\n  return Object.freeze({\n    startOffset: range.startOffset,\n    endOffset: range.endOffset,\n    start: Object.freeze({ line: range.start.line, column: range.start.column }),\n    end: Object.freeze({ line: range.end.line, column: range.end.column })\n  });\n}\n\nfunction boundedNonNegativeSafeInteger(value: unknown): value is number {\n  return (\n    typeof value === \"number\" &&\n    Number.isSafeInteger(value) &&\n    value >= 0 &&\n    value <= MAX_FACT_STRING_LENGTH\n  );\n}\n\nfunction boundedPositiveSafeInteger(value: unknown): value is number {\n  return isPositiveSafeInteger(value) && value <= MAX_FACT_STRING_LENGTH + 1;\n}\n\nfunction hasUnpairedSurrogate(value: string): boolean {\n  for (let index = 0; index < value.length; index += 1) {\n    const codeUnit = value.charCodeAt(index);\n    if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {\n      const nextCodeUnit = value.charCodeAt(index + 1);\n      if (!(nextCodeUnit >= 0xdc00 && nextCodeUnit <= 0xdfff)) return true;\n      index += 1;\n      continue;\n    }\n    if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) return true;\n  }\n  return false;\n}\n"]}

package/dist/esm/package-checks/markdown-link-validation/parse-facts-cache.mjs

@@ -0,0 +1,131 @@
+import { isUtf8 } from "node:buffer";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { cacheEnvelopeLine, markdownBytesDigest, parseCacheEnvelopeLine } from "./parse-facts-cache-payload.mjs";
+import { parseMarkdownLinkFacts } from "./markdown-parser.mjs";
+const CACHE_FILE_NAME = "markdown-link-parse-facts-v1.jsonl";
+/**
+ * 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 class MarkdownLinkParseFactsSession {
+    #cache;
+    #restored = new Map();
+    #dirty = new Map();
+    #initialRead;
+    #canPublish = true;
+    #needsPartialTailIsolation = false;
+    #finalization;
+    constructor(cache) {
+        this.#cache = cache;
+    }
+    async parse(bytes, signal) {
+        if (signal.aborted || !isUtf8(bytes))
+            return undefined;
+        if (!this.#cache.enabled)
+            return parseCurrentMarkdownBytes(bytes, signal);
+        await this.#restoreOnce();
+        if (signal.aborted)
+            return undefined;
+        const identityDigest = markdownBytesDigest(bytes);
+        const cachedFacts = this.#cachedFacts(identityDigest);
+        if (cachedFacts !== undefined)
+            return parsedFacts(cachedFacts);
+        return this.#parseFreshFacts(bytes, identityDigest, signal);
+    }
+    finalize(signal) {
+        this.#finalization ??= this.#publish(signal);
+        return this.#finalization;
+    }
+    #cachedFacts(identityDigest) {
+        return this.#restored.get(identityDigest) ?? this.#dirty.get(identityDigest);
+    }
+    async #parseFreshFacts(bytes, identityDigest, signal) {
+        const parsed = parseCurrentMarkdownBytes(bytes, signal);
+        if (parsed === undefined || !parsed.ok)
+            return parsed;
+        if (signal.aborted)
+            return undefined;
+        this.#dirty.set(identityDigest, parsed.facts);
+        return parsed;
+    }
+    async #restoreOnce() {
+        this.#initialRead ??= this.#restore();
+        await this.#initialRead;
+    }
+    async #restore() {
+        if (!this.#cache.enabled)
+            return;
+        let contents;
+        try {
+            contents = await readFile(cacheFilePath(this.#cache.directory));
+        }
+        catch (error) {
+            if (isMissingFile(error))
+                return;
+            this.#canPublish = false;
+            return;
+        }
+        this.#needsPartialTailIsolation =
+            contents.length > 0 && contents[contents.length - 1] !== "\n".charCodeAt(0);
+        let text;
+        try {
+            text = new TextDecoder("utf-8", { fatal: true }).decode(contents);
+        }
+        catch {
+            this.#canPublish = false;
+            return;
+        }
+        const lastNewline = text.lastIndexOf("\n");
+        if (lastNewline < 0)
+            return;
+        for (const line of text.slice(0, lastNewline).split("\n")) {
+            const restored = parseCacheEnvelopeLine(line);
+            if (restored !== undefined)
+                this.#restored.set(restored.identityDigest, restored.facts);
+        }
+    }
+    async #publish(signal) {
+        if (signal.aborted || !this.#cache.enabled || !this.#canPublish || this.#dirty.size === 0)
+            return;
+        try {
+            await mkdir(this.#cache.directory, { recursive: true });
+            if (signal.aborted)
+                return;
+            const block = `${this.#needsPartialTailIsolation ? "\n" : ""}${[...this.#dirty.entries()]
+                .map(([identityDigest, facts]) => cacheEnvelopeLine(identityDigest, facts))
+                .join("")}`;
+            // appendFile both creates a missing file and appends the invocation's one complete block.
+            await appendFile(cacheFilePath(this.#cache.directory), block);
+        }
+        catch {
+            // Cache publication is best effort and never changes Check settlement.
+        }
+    }
+}
+function parseCurrentMarkdownBytes(bytes, signal) {
+    const markdown = decodeMarkdownBytes(bytes);
+    return markdown === undefined || signal.aborted ? undefined : parseMarkdownLinkFacts(markdown);
+}
+function parsedFacts(facts) {
+    return Object.freeze({ ok: true, facts });
+}
+function decodeMarkdownBytes(bytes) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+function cacheFilePath(directory) {
+    return path.join(directory, CACHE_FILE_NAME);
+}
+function isMissingFile(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+//# sourceMappingURL=parse-facts-cache.mjs.map

package/dist/esm/package-checks/markdown-link-validation/parse-facts-cache.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-facts-cache.mjs","sourceRoot":"","sources":["../../../../src/package-checks/markdown-link-validation/parse-facts-cache.ts"],"names":[],"mappings":"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","sourcesContent":["import { isUtf8 } from \"node:buffer\";\nimport { appendFile, mkdir, readFile } from \"node:fs/promises\";\nimport path from \"node:path\";\n\nimport {\n  cacheEnvelopeLine,\n  markdownBytesDigest,\n  parseCacheEnvelopeLine\n} from \"./parse-facts-cache-payload.ts\";\nimport {\n  parseMarkdownLinkFacts,\n  type MarkdownLinkParseResult,\n  type ParsedMarkdownLinkFacts\n} from \"./markdown-parser.ts\";\nimport type { ResolvedMarkdownLinkValidationOptions } from \"./options.ts\";\n\nconst CACHE_FILE_NAME = \"markdown-link-parse-facts-v1.jsonl\";\n\n/**\n * Link-private state for one resolver invocation's parse-facts cache lifecycle.\n * It restores at most once, collects successful fresh facts by identity, and\n * publishes at the execution terminal boundary.\n */\nexport class MarkdownLinkParseFactsSession {\n  readonly #cache: ResolvedMarkdownLinkValidationOptions[\"cache\"];\n  readonly #restored = new Map<string, ParsedMarkdownLinkFacts>();\n  readonly #dirty = new Map<string, ParsedMarkdownLinkFacts>();\n  #initialRead: Promise<void> | undefined;\n  #canPublish = true;\n  #needsPartialTailIsolation = false;\n  #finalization: Promise<void> | undefined;\n\n  constructor(cache: ResolvedMarkdownLinkValidationOptions[\"cache\"]) {\n    this.#cache = cache;\n  }\n\n  async parse(\n    bytes: Uint8Array,\n    signal: AbortSignal\n  ): Promise<MarkdownLinkParseResult | undefined> {\n    if (signal.aborted || !isUtf8(bytes)) return undefined;\n    if (!this.#cache.enabled) return parseCurrentMarkdownBytes(bytes, signal);\n\n    await this.#restoreOnce();\n    if (signal.aborted) return undefined;\n    const identityDigest = markdownBytesDigest(bytes);\n    const cachedFacts = this.#cachedFacts(identityDigest);\n    if (cachedFacts !== undefined) return parsedFacts(cachedFacts);\n    return this.#parseFreshFacts(bytes, identityDigest, signal);\n  }\n\n  finalize(signal: AbortSignal): Promise<void> {\n    this.#finalization ??= this.#publish(signal);\n    return this.#finalization;\n  }\n\n  #cachedFacts(identityDigest: string): ParsedMarkdownLinkFacts | undefined {\n    return this.#restored.get(identityDigest) ?? this.#dirty.get(identityDigest);\n  }\n\n  async #parseFreshFacts(\n    bytes: Uint8Array,\n    identityDigest: string,\n    signal: AbortSignal\n  ): Promise<MarkdownLinkParseResult | undefined> {\n    const parsed = parseCurrentMarkdownBytes(bytes, signal);\n    if (parsed === undefined || !parsed.ok) return parsed;\n    if (signal.aborted) return undefined;\n    this.#dirty.set(identityDigest, parsed.facts);\n    return parsed;\n  }\n\n  async #restoreOnce(): Promise<void> {\n    this.#initialRead ??= this.#restore();\n    await this.#initialRead;\n  }\n\n  async #restore(): Promise<void> {\n    if (!this.#cache.enabled) return;\n    let contents: Uint8Array;\n    try {\n      contents = await readFile(cacheFilePath(this.#cache.directory));\n    } catch (error) {\n      if (isMissingFile(error)) return;\n      this.#canPublish = false;\n      return;\n    }\n\n    this.#needsPartialTailIsolation =\n      contents.length > 0 && contents[contents.length - 1] !== \"\\n\".charCodeAt(0);\n    let text: string;\n    try {\n      text = new TextDecoder(\"utf-8\", { fatal: true }).decode(contents);\n    } catch {\n      this.#canPublish = false;\n      return;\n    }\n    const lastNewline = text.lastIndexOf(\"\\n\");\n    if (lastNewline < 0) return;\n    for (const line of text.slice(0, lastNewline).split(\"\\n\")) {\n      const restored = parseCacheEnvelopeLine(line);\n      if (restored !== undefined) this.#restored.set(restored.identityDigest, restored.facts);\n    }\n  }\n\n  async #publish(signal: AbortSignal): Promise<void> {\n    if (signal.aborted || !this.#cache.enabled || !this.#canPublish || this.#dirty.size === 0)\n      return;\n    try {\n      await mkdir(this.#cache.directory, { recursive: true });\n      if (signal.aborted) return;\n      const block = `${this.#needsPartialTailIsolation ? \"\\n\" : \"\"}${[...this.#dirty.entries()]\n        .map(([identityDigest, facts]) => cacheEnvelopeLine(identityDigest, facts))\n        .join(\"\")}`;\n      // appendFile both creates a missing file and appends the invocation's one complete block.\n      await appendFile(cacheFilePath(this.#cache.directory), block);\n    } catch {\n      // Cache publication is best effort and never changes Check settlement.\n    }\n  }\n}\n\nfunction parseCurrentMarkdownBytes(\n  bytes: Uint8Array,\n  signal: AbortSignal\n): MarkdownLinkParseResult | undefined {\n  const markdown = decodeMarkdownBytes(bytes);\n  return markdown === undefined || signal.aborted ? undefined : parseMarkdownLinkFacts(markdown);\n}\n\nfunction parsedFacts(facts: ParsedMarkdownLinkFacts): MarkdownLinkParseResult {\n  return Object.freeze({ ok: true as const, facts });\n}\n\nfunction decodeMarkdownBytes(bytes: Uint8Array): string | undefined {\n  try {\n    return new TextDecoder(\"utf-8\", { fatal: true }).decode(bytes);\n  } catch {\n    return undefined;\n  }\n}\n\nfunction cacheFilePath(directory: string): string {\n  return path.join(directory, CACHE_FILE_NAME);\n}\n\nfunction isMissingFile(error: unknown): boolean {\n  return (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"code\" in error &&\n    (error as Readonly<{ readonly code?: unknown }>).code === \"ENOENT\"\n  );\n}\n"]}

package/dist/esm/package-checks/markdown-link-validation/resolver-engine.mjs

@@ -1,57 +1,41 @@
 import { opendir } from "node:fs/promises";
 import path from "node:path";
-import { parseMarkdownLinkFacts } from "./markdown-parser.mjs";
+import { MarkdownLinkParseFactsSession } from "./parse-facts-cache.mjs";
 import { directoryTarget, fileTargetDescriptor, outsideProjectRootTarget, projectTarget } from "./target-descriptor.mjs";
 import { probeEndpoint, probeRootContainedPath, readRegularFile } from "./filesystem-probes.mjs";
-import { anchorResolution, finding, isMarkdownPath, isRootRelativePath, isWithinRoot, parseLocalDestination, sameRootRelativePath, sourceUnavailable, toSlashPath, unavailable, valid } from "./local-resolution.mjs";
+import { readRootContainedMarkdownSource } from "./source-reader.mjs";
+import { anchorResolution, finding, isMarkdownPath, isWithinRoot, parseLocalDestination, sameRootRelativePath, unavailable, valid } from "./local-resolution.mjs";
 export class LinkLocalResolver {
     #targetReadCount = 0;
     #canonicalProjectRoot;
+    #parseFactsCache;
     #maxTargetReads;
-    constructor(canonicalProjectRoot, maxTargetReads) {
+    #signal;
+    #targetFactMemo = new Map();
+    constructor(canonicalProjectRoot, maxTargetReads, cache, signal) {
         this.#canonicalProjectRoot = canonicalProjectRoot;
         this.#maxTargetReads = maxTargetReads;
+        this.#parseFactsCache = new MarkdownLinkParseFactsSession(cache);
+        this.#signal = signal;
     }
     get targetReadCount() {
         return this.#targetReadCount;
     }
-    async readSource(rootRelativePath, maxMarkdownBytes) {
-        if (!isRootRelativePath(this.#canonicalProjectRoot, rootRelativePath)) {
-            return sourceUnavailable();
-        }
-        const sourcePath = path.resolve(this.#canonicalProjectRoot, rootRelativePath);
-        const rootProbe = await probeRootContainedPath(this.#canonicalProjectRoot, sourcePath);
-        if (rootProbe.kind === "outside" ||
-            rootProbe.kind === "unavailable" ||
-            rootProbe.kind === "missing") {
-            return sourceUnavailable();
-        }
-        const sourceBytes = await readRegularFile(rootProbe.absolutePath, maxMarkdownBytes);
-        if (!sourceBytes.ok) {
-            return sourceBytes.reason === "too-large"
-                ? Object.freeze({ ok: false, reason: "source-too-large" })
-                : sourceUnavailable();
-        }
-        let markdown;
-        try {
-            markdown = new TextDecoder("utf-8", { fatal: true }).decode(sourceBytes.bytes);
-        }
-        catch {
-            return sourceUnavailable();
-        }
-        const parsed = parseMarkdownLinkFacts(markdown);
-        if (!parsed.ok) {
-            return Object.freeze({ ok: false, reason: "markdown-parse-failed" });
-        }
-        return Object.freeze({
-            ok: true,
-            source: Object.freeze({
-                path: toSlashPath(path.relative(this.#canonicalProjectRoot, sourcePath)),
-                facts: parsed.facts
-            })
+    finalize() {
+        return this.#parseFactsCache.finalize(this.#signal);
+    }
+    readSource(rootRelativePath, maxMarkdownBytes) {
+        return readRootContainedMarkdownSource({
+            canonicalProjectRoot: this.#canonicalProjectRoot,
+            maxMarkdownBytes,
+            parseMarkdownBytes: (bytes) => this.#parseMarkdownBytes(bytes),
+            rootRelativePath,
+            signal: this.#signal
         });
     }
     async resolve(request) {
+        if (this.#signal.aborted)
+            return unavailable("target-unavailable");
         const destination = parseLocalDestination(request.rawDestination);
         if (destination === "not-local") {
             return Object.freeze({ kind: "not-local" });
@@ -98,7 +82,7 @@ export class LinkLocalResolver {
         if (!this.beginTargetValidation()) {
             return unavailable("target-read-limit-exceeded");
         }
-        return this.resolveEndpoint(rootProbe.absolutePath, fragment, request, projectTarget(this.#canonicalProjectRoot, targetPath, fragment));
+        return this.resolveEndpoint(rootProbe.endpoint ?? (await probeEndpoint(rootProbe.absolutePath)), rootProbe.absolutePath, fragment, request, projectTarget(this.#canonicalProjectRoot, targetPath, fragment));
     }
     async resolveExternalTarget(targetPath, fragment, request) {
         if (request.rootExternalTargetMode === "ignore") {
@@ -110,10 +94,9 @@ export class LinkLocalResolver {
         if (!this.beginTargetValidation()) {
             return unavailable("target-read-limit-exceeded");
         }
-        return this.resolveEndpoint(targetPath, fragment, request, outsideProjectRootTarget());
+        return this.resolveEndpoint(await probeEndpoint(targetPath), targetPath, fragment, request, outsideProjectRootTarget());
     }
-    async resolveEndpoint(targetPath, fragment, request, target) {
-        const endpoint = await probeEndpoint(targetPath);
+    async resolveEndpoint(endpoint, targetPath, fragment, request, target) {
         if (endpoint.kind === "missing") {
             return request.requireExistingTargets ? finding("missing-target", target) : valid(target);
         }
@@ -135,24 +118,14 @@ export class LinkLocalResolver {
         if (!isMarkdownPath(targetPath)) {
             return finding("anchor-target-not-markdown", target);
         }
-        const targetMarkdown = await readRegularFile(targetPath, request.maxMarkdownBytes);
-        if (!targetMarkdown.ok) {
-            return unavailable("target-unavailable");
-        }
-        let decodedTarget;
-        try {
-            decodedTarget = new TextDecoder("utf-8", { fatal: true }).decode(targetMarkdown.bytes);
-        }
-        catch {
-            return unavailable("target-unavailable");
-        }
-        const parsedTarget = parseMarkdownLinkFacts(decodedTarget);
-        if (!parsedTarget.ok) {
-            return unavailable("target-unavailable");
-        }
-        return anchorResolution(parsedTarget.facts.headings, fragment, target);
+        const facts = await this.#targetFacts(targetPath, request.maxMarkdownBytes);
+        return facts === undefined
+            ? unavailable("target-unavailable")
+            : anchorResolution(facts.headings, fragment, target);
     }
     async resolveDirectory(targetPath, fragment, request, target) {
+        if (this.#signal.aborted)
+            return unavailable("target-unavailable");
         if (fragment !== null) {
             return finding("anchor-on-directory", target);
         }
@@ -181,6 +154,34 @@ export class LinkLocalResolver {
         this.#targetReadCount += 1;
         return true;
     }
+    async #targetFacts(targetPath, maxMarkdownBytes) {
+        if (this.#signal.aborted)
+            return undefined;
+        const key = JSON.stringify([targetPath, maxMarkdownBytes]);
+        const existing = this.#targetFactMemo.get(key);
+        if (existing !== undefined)
+            return existing;
+        const pending = this.#readTargetFacts(targetPath, maxMarkdownBytes);
+        this.#targetFactMemo.set(key, pending);
+        const facts = await pending;
+        if (facts === undefined && this.#targetFactMemo.get(key) === pending) {
+            this.#targetFactMemo.delete(key);
+        }
+        return facts;
+    }
+    async #readTargetFacts(targetPath, maxMarkdownBytes) {
+        const targetMarkdown = await readRegularFile(targetPath, maxMarkdownBytes);
+        if (!targetMarkdown.ok || this.#signal.aborted)
+            return undefined;
+        const parsed = await this.#parseMarkdownBytes(targetMarkdown.bytes);
+        return this.#signal.aborted || parsed === undefined || !parsed.ok ? undefined : parsed.facts;
+    }
+    async #parseMarkdownBytes(bytes) {
+        if (this.#signal.aborted)
+            return undefined;
+        const parsed = await this.#parseFactsCache.parse(bytes, this.#signal);
+        return this.#signal.aborted ? undefined : parsed;
+    }
     resolveSameDocument(fragment, request) {
         const target = Object.freeze({
             kind: "same-document",