@zxyycom/vibe-check 0.0.2 → 0.0.3

package/src/package-checks/markdown-lint/finding-waiver-identity.ts

@@ -0,0 +1,54 @@
+import { snapshotExactClosedRecord } from "../../data-boundary/closed-values.ts";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
+import { isNormalizedProjectRelativePath } from "../host-environment/path.ts";
+import {
+  MARKDOWN_LINT_RULE_NAMES,
+  type MarkdownLintFindingIdentity,
+  type MarkdownLintRuleName
+} from "./options.ts";
+
+/** Validates and detaches the complete public location used for exact waiver matching. */
+export function resolveMarkdownLintFindingIdentity(
+  value: unknown
+): MarkdownLintFindingIdentity | undefined {
+  const identity = snapshotExactClosedRecord(value, ["path", "rule", "range"]);
+  if (
+    identity === undefined ||
+    !isNormalizedProjectRelativePath(identity.path) ||
+    !isMarkdownLintRuleName(identity.rule)
+  ) {
+    return undefined;
+  }
+  const range = snapshotExactClosedRecord(identity.range, ["start", "end"]);
+  if (range === undefined) return undefined;
+  const start = resolvePosition(range.start);
+  const end = resolvePosition(range.end);
+  if (
+    start === undefined ||
+    end === undefined ||
+    start.line !== end.line ||
+    end.column < start.column
+  ) {
+    return undefined;
+  }
+  return Object.freeze({
+    path: identity.path,
+    rule: identity.rule,
+    range: Object.freeze({ start, end })
+  });
+}
+
+function resolvePosition(
+  value: unknown
+): MarkdownLintFindingIdentity["range"]["start"] | undefined {
+  const position = snapshotExactClosedRecord(value, ["line", "column"]);
+  return position !== undefined &&
+    isPositiveSafeInteger(position.line) &&
+    isPositiveSafeInteger(position.column)
+    ? Object.freeze({ line: position.line, column: position.column })
+    : undefined;
+}
+
+function isMarkdownLintRuleName(value: unknown): value is MarkdownLintRuleName {
+  return typeof value === "string" && MARKDOWN_LINT_RULE_NAMES.some((rule) => rule === value);
+}

package/src/package-checks/markdown-lint/findings-cache.ts

@@ -0,0 +1,141 @@
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+
+import {
+  snapshotClosedRecord,
+  snapshotExactClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import { cacheJsonByKey } from "../../package-tools/cache/cache-json-by-key.ts";
+import {
+  lintMarkdownString,
+  parseMarkdownLintRange,
+  type MarkdownLintBackendFinding
+} from "./adapter.ts";
+import {
+  MARKDOWN_LINT_RULE_NAMES,
+  type MarkdownLintCacheOptions,
+  type MarkdownLintRuleName
+} from "./options.ts";
+import type { MarkdownLintUnavailableReason } from "./unavailable-reasons.ts";
+
+type LintFacts = Readonly<{ readonly findings: readonly MarkdownLintBackendFinding[] }>;
+type MarkdownLintCacheInput = Readonly<{
+  readonly sourcePath: string;
+  readonly sourceText: string;
+  readonly rules: readonly MarkdownLintRuleName[];
+  readonly cache: MarkdownLintCacheOptions;
+  readonly signal: AbortSignal;
+}>;
+export type MarkdownLintFactsResult =
+  | Readonly<{
+      readonly findings: readonly MarkdownLintBackendFinding[];
+      readonly source: "cache" | "computed" | "uncached";
+    }>
+  | MarkdownLintUnavailableReason;
+
+/** Bump when adapter configuration or finding interpretation changes without a backend version change. */
+const CACHE_FORMAT_VERSION = "markdown-lint-findings-v1";
+const backendVersion = installedMarkdownlintVersion();
+
+class LintComputationUnavailable extends Error {
+  readonly reason: MarkdownLintUnavailableReason;
+
+  constructor(reason: MarkdownLintUnavailableReason) {
+    super(`Markdown lint unavailable: ${reason}`);
+    this.reason = reason;
+  }
+}
+
+/** Reuses only validated per-source findings; all source reads and Check settlement remain live. */
+export async function lintMarkdownWithCache(
+  input: MarkdownLintCacheInput
+): Promise<MarkdownLintFactsResult> {
+  const { sourcePath, sourceText, rules, cache, signal } = input;
+  if (signal.aborted) return "cancelled";
+  if (!cache.enabled || backendVersion === undefined) return lintFresh(input);
+
+  try {
+    const result = await cacheJsonByKey({
+      directory: cache.directory,
+      key: JSON.stringify({
+        path: sourcePath,
+        sourceDigest: createHash("sha256").update(sourceText, "utf8").digest("hex"),
+        rules
+      }),
+      namespace: "markdown-lint-findings",
+      version: `${CACHE_FORMAT_VERSION}:${backendVersion}`,
+      compute: async () => {
+        if (signal.aborted) throw new LintComputationUnavailable("cancelled");
+        const findings = await lintMarkdownString(sourcePath, sourceText, rules);
+        if (typeof findings === "string") throw new LintComputationUnavailable(findings);
+        if (signal.aborted) throw new LintComputationUnavailable("cancelled");
+        return { findings };
+      },
+      parse: (value) => parseLintFacts(value, sourceText, rules)
+    });
+    if (signal.aborted) return "cancelled";
+    return Object.freeze({ findings: result.value.findings, source: result.source });
+  } catch (error: unknown) {
+    if (signal.aborted) return "cancelled";
+    if (error instanceof LintComputationUnavailable) return error.reason;
+    throw error;
+  }
+}
+
+async function lintFresh(input: MarkdownLintCacheInput): Promise<MarkdownLintFactsResult> {
+  const findings = await lintMarkdownString(input.sourcePath, input.sourceText, input.rules);
+  if (input.signal.aborted) return "cancelled";
+  return typeof findings === "string"
+    ? findings
+    : Object.freeze({ findings, source: "uncached" as const });
+}
+
+function parseLintFacts(
+  value: unknown,
+  sourceText: string,
+  rules: readonly MarkdownLintRuleName[]
+): LintFacts {
+  const payload = snapshotExactClosedRecord(value, ["findings"]);
+  if (payload === undefined || !Array.isArray(payload.findings))
+    throw new TypeError("Invalid Markdown lint cache payload");
+  const lines = sourceText.split(/\r\n|\r|\n/u);
+  const findings = payload.findings.map((rawFinding: unknown) => {
+    const finding = snapshotExactClosedRecord(rawFinding, ["lineNumber", "range", "rule"]);
+    if (
+      finding === undefined ||
+      !isMarkdownLintRuleName(finding.rule) ||
+      !rules.includes(finding.rule) ||
+      typeof finding.lineNumber !== "number" ||
+      !Number.isSafeInteger(finding.lineNumber) ||
+      finding.lineNumber < 1 ||
+      finding.lineNumber > lines.length
+    )
+      throw new TypeError("Invalid Markdown lint cached finding");
+    const line = lines[finding.lineNumber - 1];
+    if (line === undefined) throw new TypeError("Invalid Markdown lint cached line");
+    const range = parseMarkdownLintRange(finding.range, line);
+    if (range === undefined) throw new TypeError("Invalid Markdown lint cached range");
+    return Object.freeze({
+      lineNumber: finding.lineNumber,
+      range,
+      rule: finding.rule
+    });
+  });
+  return Object.freeze({ findings: Object.freeze(findings) });
+}
+
+function isMarkdownLintRuleName(value: unknown): value is MarkdownLintRuleName {
+  return typeof value === "string" && MARKDOWN_LINT_RULE_NAMES.some((rule) => rule === value);
+}
+
+function installedMarkdownlintVersion(): string | undefined {
+  try {
+    const packageJson: unknown = createRequire(import.meta.url)("markdownlint/package.json");
+    const metadata = snapshotClosedRecord(packageJson);
+    return typeof metadata?.version === "string" && metadata.version.length > 0
+      ? metadata.version
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/package-checks/markdown-lint/options-resolution.ts

@@ -0,0 +1,102 @@
+import {
+  hasRequiredAndOptionalRecordKeys,
+  snapshotClosedArray,
+  snapshotClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import {
+  defaultProjectFileSelection,
+  resolveProjectFileSelection,
+  snapshotProjectFileSelection
+} from "../project-files/configuration.ts";
+import { DEFAULT_FINDING_POLICY, resolveFindingPolicy } from "../code-quality-findings/policy.ts";
+import { resolveFindingWaiverAuthoring } from "../code-quality-findings/finding-waiver-authoring.ts";
+import { resolveOptionalLocalCacheOptions } from "../local-cache-options.ts";
+import { resolveMarkdownLintFindingIdentity } from "./finding-waiver-identity.ts";
+import {
+  MARKDOWN_LINT_RULE_NAMES,
+  type MarkdownLintRuleName,
+  type ResolvedMarkdownLintOptions
+} from "./options.ts";
+import { validMarkdownLintOptions } from "./options-validation.ts";
+
+const DEFAULT_FILES = Object.freeze({
+  exclude: defaultProjectFileSelection.exclude,
+  include: Object.freeze(["**/*.[mM][dD]", "**/*.[mM][aA][rR][kK][dD][oO][wW][nN]"]),
+  source: defaultProjectFileSelection.source
+});
+const DEFAULT_LIMITS = Object.freeze({ maxMarkdownBytes: 1_048_576, maxFindings: 10_000 });
+const DEFAULT_RULES = Object.freeze(
+  MARKDOWN_LINT_RULE_NAMES.filter((rule) => rule !== "link-fragments")
+);
+const KNOWN_RULES = new Set<string>(MARKDOWN_LINT_RULE_NAMES);
+
+/** Resolves closed partial authoring options into an immutable complete policy. */
+export function resolveMarkdownLintOptions(
+  value: unknown
+): ResolvedMarkdownLintOptions | undefined {
+  const input = snapshotClosedRecord(value);
+  if (
+    input === undefined ||
+    !hasRequiredAndOptionalRecordKeys(input, {
+      optional: ["files", "findingPolicy", "findingWaivers", "rules", "limits", "cache"],
+      required: []
+    })
+  ) {
+    return undefined;
+  }
+  const files =
+    input.files === undefined
+      ? snapshotProjectFileSelection(DEFAULT_FILES)
+      : resolveProjectFileSelection(input.files, DEFAULT_FILES);
+  const findingPolicy = resolveFindingPolicy(input.findingPolicy, DEFAULT_FINDING_POLICY);
+  const findingWaivers = resolveFindingWaiverAuthoring(
+    input.findingWaivers,
+    resolveMarkdownLintFindingIdentity
+  );
+  const rules = resolveRules(input.rules);
+  const limits = resolveLimits(input.limits);
+  const cache = resolveOptionalLocalCacheOptions(input.cache);
+  const candidate = Object.freeze({
+    files,
+    findingPolicy,
+    findingWaivers,
+    rules,
+    limits,
+    cache
+  });
+  return validMarkdownLintOptions(candidate) ? candidate : undefined;
+}
+
+function resolveRules(value: unknown): readonly MarkdownLintRuleName[] | undefined {
+  if (value === undefined) return DEFAULT_RULES;
+  const rules = snapshotClosedArray(value);
+  if (
+    rules === undefined ||
+    rules.length === 0 ||
+    !rules.every((rule) => typeof rule === "string" && KNOWN_RULES.has(rule)) ||
+    new Set(rules).size !== rules.length
+  ) {
+    return undefined;
+  }
+  return Object.freeze(
+    MARKDOWN_LINT_RULE_NAMES.filter((catalogRule) => rules.includes(catalogRule))
+  );
+}
+
+function resolveLimits(value: unknown): ResolvedMarkdownLintOptions["limits"] | undefined {
+  if (value === undefined) return DEFAULT_LIMITS;
+  const limits = snapshotClosedRecord(value);
+  if (
+    limits === undefined ||
+    !hasRequiredAndOptionalRecordKeys(limits, {
+      optional: ["maxMarkdownBytes", "maxFindings"],
+      required: []
+    })
+  ) {
+    return undefined;
+  }
+  const maxMarkdownBytes = limits.maxMarkdownBytes ?? DEFAULT_LIMITS.maxMarkdownBytes;
+  const maxFindings = limits.maxFindings ?? DEFAULT_LIMITS.maxFindings;
+  if (typeof maxMarkdownBytes !== "number" || typeof maxFindings !== "number") return undefined;
+  return Object.freeze({ maxMarkdownBytes, maxFindings });
+}

package/src/package-checks/markdown-lint/options-validation.ts

@@ -0,0 +1,50 @@
+import { snapshotExactClosedRecord } from "../../data-boundary/closed-values.ts";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
+import { validFindingPolicy } from "../code-quality-findings/policy.ts";
+import { validResolvedFindingWaivers } from "../code-quality-findings/finding-waiver-authoring.ts";
+import { validLocalCacheOptions } from "../local-cache-options.ts";
+import { validProjectFileSelection } from "../project-files/configuration.ts";
+import { MARKDOWN_LINT_RULE_NAMES, type ResolvedMarkdownLintOptions } from "./options.ts";
+import { resolveMarkdownLintFindingIdentity } from "./finding-waiver-identity.ts";
+
+const KNOWN_RULES = new Set<string>(MARKDOWN_LINT_RULE_NAMES);
+
+export function validMarkdownLintOptions(value: unknown): value is ResolvedMarkdownLintOptions {
+  const options = snapshotExactClosedRecord(value, [
+    "files",
+    "findingPolicy",
+    "findingWaivers",
+    "rules",
+    "limits",
+    "cache"
+  ]);
+  if (
+    options === undefined ||
+    !validProjectFileSelection(options.files) ||
+    !validFindingPolicy(options.findingPolicy) ||
+    !validResolvedFindingWaivers(options.findingWaivers, resolveMarkdownLintFindingIdentity) ||
+    !validRules(options.rules) ||
+    !validLocalCacheOptions(options.cache)
+  ) {
+    return false;
+  }
+  const limits = snapshotExactClosedRecord(options.limits, ["maxMarkdownBytes", "maxFindings"]);
+  return (
+    limits !== undefined &&
+    isBoundedPositiveInteger(limits.maxMarkdownBytes, 16_777_216) &&
+    isBoundedPositiveInteger(limits.maxFindings, 100_000)
+  );
+}
+
+function validRules(value: unknown): value is readonly string[] {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((rule) => typeof rule === "string" && KNOWN_RULES.has(rule)) &&
+    new Set(value).size === value.length
+  );
+}
+
+function isBoundedPositiveInteger(value: unknown, maximum: number): value is number {
+  return isPositiveSafeInteger(value) && value <= maximum;
+}

package/src/package-checks/markdown-lint/options.ts

@@ -0,0 +1,82 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
+import type { LocalCacheOptions } from "../local-cache-options.ts";
+import type { FindingPolicy } from "../code-quality-findings/policy.ts";
+import type { FindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
+import type {
+  ProjectFileSelection,
+  ProjectFileSelectionOptions
+} from "../project-files/configuration.ts";
+
+/** 由 Product 拥有且独立于 backend 名称的闭合 Markdown lint 规则目录。 */
+export const MARKDOWN_LINT_RULE_NAMES = Object.freeze([
+  "heading-increment",
+  "no-reversed-links",
+  "no-missing-space-atx",
+  "fenced-code-language",
+  "no-empty-links",
+  "no-alt-text",
+  "link-fragments",
+  "reference-links-images",
+  "table-column-count"
+] as const);
+
+/** `markdownLint` 支持的稳定 Product-owned 规则名称。 */
+export type MarkdownLintRuleName = (typeof MARKDOWN_LINT_RULE_NAMES)[number];
+
+/** 可直接从 lint Record 复制的精确身份；完整 range 相同的多个 Finding 不可唯一豁免。 */
+export interface MarkdownLintFindingIdentity {
+  /** 规范化的 project-root-relative `/` 路径。 */
+  readonly path: string;
+  /** 闭合 Product catalog 中的规则名称。 */
+  readonly rule: MarkdownLintRuleName;
+  /** 一基 UTF-16 正安全整数位置；必须同行，end-exclusive column 不小于 start column。 */
+  readonly range: Readonly<{
+    readonly start: Readonly<{ readonly line: number; readonly column: number }>;
+    readonly end: Readonly<{ readonly line: number; readonly column: number }>;
+  }>;
+}
+
+/** 完整 traversal 后唯一匹配才应用的精确豁免；reason 会公开发布，不得包含秘密。 */
+export type MarkdownLintFindingWaiver = FindingWaiver<MarkdownLintFindingIdentity>;
+
+/** `markdownLint(options?)` 可接受的可省略 work limits。 */
+export interface MarkdownLintLimitOptions {
+  /** 单个 accepted Markdown source 的 UTF-8 字节上限。 */
+  readonly maxMarkdownBytes?: number;
+  /** 一次完整 traversal 中可积累的 lint finding 上限。 */
+  readonly maxFindings?: number;
+}
+
+/** 调用方拥有的逐文件 lint findings 本地缓存；省略时关闭。 */
+export type MarkdownLintCacheOptions = LocalCacheOptions;
+
+/** `markdownLint(options?)` 可接受的闭合 authoring policy。 */
+export interface MarkdownLintOptions<
+  Id extends string = string
+> extends PackageCheckAuthoringOptions<Id> {
+  /** 参与本 Check 的 source selection；省略时使用 package defaults。 */
+  readonly files?: ProjectFileSelectionOptions;
+  /** 未豁免 lint finding 是否使本 Check failed；省略时为 non-blocking。 */
+  readonly findingPolicy?: FindingPolicy;
+  /** 闭合的精确 Finding 豁免；保留原始证据，不改变输入、limits 或缓存 facts。 */
+  readonly findingWaivers?: readonly MarkdownLintFindingWaiver[];
+  /** 非空数组完整替换 recommended rule set。 */
+  readonly rules?: readonly MarkdownLintRuleName[];
+  /** 每次 execution 的 Markdown 内容与 finding work 上限。 */
+  readonly limits?: MarkdownLintLimitOptions;
+  /** 可删除、可信 absolute directory；只缓存由当前 bytes 和规则计算的逐文件 findings。 */
+  readonly cache?: MarkdownLintCacheOptions;
+}
+
+/** `markdown-lint` execution 消费的完整冻结 policy。 */
+export interface ResolvedMarkdownLintOptions {
+  readonly files: ProjectFileSelection;
+  readonly findingPolicy: FindingPolicy;
+  readonly findingWaivers: readonly MarkdownLintFindingWaiver[];
+  readonly rules: readonly MarkdownLintRuleName[];
+  readonly cache: MarkdownLintCacheOptions;
+  readonly limits: Readonly<{
+    readonly maxMarkdownBytes: number;
+    readonly maxFindings: number;
+  }>;
+}

package/src/package-checks/markdown-lint/records.ts

@@ -0,0 +1,132 @@
+import type { MaterializedFindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
+import {
+  buildHashedFindingWaiverAuditRecord,
+  type FindingWaiverAuditRecordData,
+  type FindingWaiverRecordAudit
+} from "../code-quality-findings/finding-waiver-evidence.ts";
+import type { MarkdownLintBackendFinding } from "./adapter.ts";
+import { resolveMarkdownLintFindingIdentity } from "./finding-waiver-identity.ts";
+import type { MarkdownLintFindingIdentity, MarkdownLintRuleName } from "./options.ts";
+
+/** 一条保留原位置的 lint Finding；唯一命中 waiver 时仅附加公开理由。 */
+export type MarkdownLintFindingRecordData = Readonly<
+  MarkdownLintFindingIdentity & {
+    readonly kind: "lint-finding";
+    readonly waiver?: Readonly<{ readonly reason: string }>;
+  }
+>;
+
+/** 未使用或匹配多个 Markdown lint Findings 的精确 waiver audit Record data。 */
+export type MarkdownLintFindingWaiverAuditRecordData =
+  FindingWaiverAuditRecordData<MarkdownLintFindingIdentity>;
+
+export type MarkdownLintInputRejectedRecordData = Readonly<{
+  readonly kind: "input-rejected";
+  readonly blocking: false;
+  readonly path: string;
+  readonly reason: "unsupported-file-type";
+}>;
+
+/** Markdown lint 发布的 Finding、input-rejection 或 finding-waiver audit Record data。 */
+export type MarkdownLintRecordData =
+  | MarkdownLintFindingRecordData
+  | MarkdownLintInputRejectedRecordData
+  | MarkdownLintFindingWaiverAuditRecordData;
+
+export interface MarkdownLintRecordCandidate {
+  readonly id: string;
+  readonly data: MarkdownLintFindingRecordData;
+}
+
+export function markdownLintFindingIdentity(
+  candidate: MarkdownLintRecordCandidate
+): MarkdownLintFindingIdentity {
+  const { path, rule, range } = candidate.data;
+  return Object.freeze({ path, rule, range });
+}
+
+export function markdownLintWaiverIdentity(
+  waiver: MaterializedFindingWaiver
+): MarkdownLintFindingIdentity {
+  const identity = resolveMarkdownLintFindingIdentity(waiver.identity);
+  if (identity === undefined) {
+    throw new TypeError("markdownLint waiver identity must retain a valid public finding location");
+  }
+  return identity;
+}
+
+export function markdownLintWaiverAuditRecord(audit: FindingWaiverRecordAudit): Readonly<{
+  readonly id: string;
+  readonly data: MarkdownLintFindingWaiverAuditRecordData;
+}> {
+  return buildHashedFindingWaiverAuditRecord(markdownLintWaiverIdentity(audit.waiver), audit);
+}
+
+export function orderedMarkdownLintCandidates(
+  values: readonly Readonly<{
+    readonly path: string;
+    readonly finding: MarkdownLintBackendFinding;
+  }>[],
+  catalog: readonly MarkdownLintRuleName[]
+): readonly MarkdownLintRecordCandidate[] {
+  const rank = new Map(catalog.map((rule, index) => [rule, index]));
+  const sorted = [...values].sort((left, right) => compareFindings(left, right, rank));
+  const occurrences = new Map<string, number>();
+  return Object.freeze(
+    sorted.map(({ path, finding }) => {
+      const range = publicRange(finding);
+      const key = `${path}\u0000${finding.rule}\u0000${range.start.line}\u0000${range.start.column}`;
+      const ordinal = (occurrences.get(key) ?? 0) + 1;
+      occurrences.set(key, ordinal);
+      const data = Object.freeze({
+        kind: "lint-finding" as const,
+        path,
+        rule: finding.rule,
+        range
+      });
+      return Object.freeze({
+        id: `path:${encodeURIComponent(path)}:rule:${finding.rule}:line:${range.start.line}:column:${range.start.column}:ordinal:${ordinal}`,
+        data
+      });
+    })
+  );
+}
+
+export function buildMarkdownLintInputRejectedRecord(path: string): Readonly<{
+  readonly id: string;
+  readonly data: MarkdownLintInputRejectedRecordData;
+}> {
+  return Object.freeze({
+    id: `/input-rejected/${path}`,
+    data: Object.freeze({
+      kind: "input-rejected",
+      blocking: false,
+      path,
+      reason: "unsupported-file-type"
+    })
+  });
+}
+
+function compareFindings(
+  left: Readonly<{ readonly path: string; readonly finding: MarkdownLintBackendFinding }>,
+  right: Readonly<{ readonly path: string; readonly finding: MarkdownLintBackendFinding }>,
+  rank: ReadonlyMap<MarkdownLintRuleName, number>
+): number {
+  const leftRange = publicRange(left.finding);
+  const rightRange = publicRange(right.finding);
+  return (
+    left.path.localeCompare(right.path) ||
+    leftRange.start.line - rightRange.start.line ||
+    leftRange.start.column - rightRange.start.column ||
+    (rank.get(left.finding.rule) ?? 0) - (rank.get(right.finding.rule) ?? 0)
+  );
+}
+
+function publicRange(finding: MarkdownLintBackendFinding): MarkdownLintFindingRecordData["range"] {
+  const column = finding.range?.[0] ?? 1;
+  const endColumn = finding.range === null ? column : column + finding.range[1];
+  return Object.freeze({
+    start: Object.freeze({ line: finding.lineNumber, column }),
+    end: Object.freeze({ line: finding.lineNumber, column: endColumn })
+  });
+}

package/src/package-checks/markdown-lint/unavailable-reasons.ts

@@ -0,0 +1,33 @@
+/** Markdown lint complete Check 的稳定 unavailable 原因。 */
+export type MarkdownLintUnavailableReason =
+  | "backend-failed"
+  | "backend-protocol-invalid"
+  | "cancelled"
+  | "finding-limit-exceeded"
+  | "invalid-options"
+  | "project-root-unavailable"
+  | "source-too-large"
+  | "source-unavailable";
+
+const MESSAGES: Readonly<Record<MarkdownLintUnavailableReason, string>> = {
+  "backend-failed":
+    "Markdown lint could not complete its private backend operation; retry after checking the installed package.",
+  "backend-protocol-invalid":
+    "Markdown lint received an invalid private backend response and did not publish partial findings.",
+  cancelled:
+    "Markdown lint was cancelled before it could form a complete result; retry after cancellation is resolved.",
+  "finding-limit-exceeded":
+    "Markdown lint exceeded maxFindings; narrow the file selection or raise the bounded limit.",
+  "invalid-options":
+    "markdownLint options are invalid; recreate the Check with markdownLint(options) or restore its complete resolved options.",
+  "project-root-unavailable":
+    "Markdown lint could not resolve the project root; check that the path exists and is accessible.",
+  "source-too-large":
+    "A selected Markdown source exceeds maxMarkdownBytes; narrow the file selection or raise the bounded limit.",
+  "source-unavailable":
+    "A selected Markdown source could not be read, decoded, or contained safely; check the file source and permissions."
+};
+
+export function markdownLintUnavailableMessage(reason: MarkdownLintUnavailableReason): string {
+  return MESSAGES[reason];
+}