@zxyycom/vibe-check 0.0.1 → 0.0.3

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];
+}

package/src/package-checks/project-files/collection.ts

@@ -3,11 +3,11 @@
 import { lstatSync } from "node:fs";
 import { resolve } from "node:path";
 
-import { matchesAnyConfigGlob } from "./config-glob.ts";
+import { matchesAnyConfigGlob } from "../../data-boundary/config-glob.ts";
 import { collectSubmoduleWorktreeFiles } from "./revision-worktree-files.ts";
 import { errorMessage } from "../host-environment/error-message.ts";
-import { processFailed } from "../host-environment/process/command.ts";
-import { runGit, splitNulDelimitedGitFileList } from "../host-environment/git.ts";
+import { processFailed } from "../host-environment/process.ts";
+import { gitFailureDetail, runGit, splitNulDelimitedGitFileList } from "../host-environment/git.ts";
 import { toSlashPath } from "../host-environment/path.ts";
 import { walkFiles } from "../host-environment/filesystem.ts";
 import type { ProjectFileSelection, ProjectFileSource } from "./configuration.ts";
@@ -17,6 +17,16 @@ type NamedProjectFileSelection = Readonly<{
   readonly selection: ProjectFileSelection;
 }>;
 
+type SourceCandidateCollector = (
+  rootDir: string,
+  selections: readonly NamedProjectFileSelection[]
+) => readonly string[];
+
+const sourceCandidateCollectors = Object.freeze({
+  filesystem: collectFilesystemCandidates,
+  "git-worktree": collectGitWorktreeCandidates
+}) satisfies Readonly<Partial<Record<ProjectFileSource, SourceCandidateCollector>>>;
+
 const CONFIG_GLOB_MAGIC = /[\\*?[\]{}()!+@]/u;
 
 /**
@@ -77,21 +87,29 @@ function collectSourceCandidates(
   source: ProjectFileSource,
   selections: readonly NamedProjectFileSelection[]
 ): readonly string[] {
-  switch (source) {
-    case "filesystem":
-      return uniqueSorted(
-        walkFiles({
-          ignoredDirs: commonExcludedDirectoryNames(selections),
-          rootDir
-        }).map(toSlashPath)
-      );
-    case "git-worktree":
-      return collectGitWorktreeCandidates(rootDir, selections);
-    default: {
-      const unsupportedSource: never = source;
-      throw new TypeError(`unsupported project file source: ${String(unsupportedSource)}`);
-    }
-  }
+  return sourceCandidateCollectorFor(source)(rootDir, selections);
+}
+
+function sourceCandidateCollectorFor(source: ProjectFileSource): SourceCandidateCollector {
+  const collector = sourceCandidateCollectors[source];
+  if (collector === undefined) return unsupportedProjectFileSource(source);
+  return collector;
+}
+
+function unsupportedProjectFileSource(source: ProjectFileSource): never {
+  throw new TypeError(`unsupported project file source: ${source}`);
+}
+
+function collectFilesystemCandidates(
+  rootDir: string,
+  selections: readonly NamedProjectFileSelection[]
+): readonly string[] {
+  return uniqueSorted(
+    walkFiles({
+      ignoredDirs: commonExcludedDirectoryNames(selections),
+      rootDir
+    }).map(toSlashPath)
+  );
 }
 
 function collectGitWorktreeCandidates(
@@ -103,11 +121,9 @@ function collectGitWorktreeCandidates(
     cwd: rootDir
   });
   if (processFailed(result)) {
-    const detail =
-      result.stderr.trim() ||
-      result.error?.message ||
-      (result.signal === null ? `exit status ${result.status}` : `signal ${result.signal}`);
-    throw new Error(`could not enumerate git-worktree files in ${rootDir}: ${detail}`);
+    throw new Error(
+      `could not enumerate git-worktree files in ${rootDir}: ${gitFailureDetail(result)}`
+    );
   }
 
   const include = uniqueSorted(selections.flatMap(({ selection }) => [...selection.include]));

package/src/package-checks/project-files/config-glob.ts

@@ -1,17 +1 @@
-import { minimatch } from "minimatch";
-
-import { toSlashPath } from "../host-environment/path.ts";
-
-/**
- * Product config glob 的唯一 matcher boundary。
- * Candidate 使用 slash form；dot path 只由显式 glob 决定，不附加隐式忽略规则。
- */
-export function matchesAnyConfigGlob(
-  candidatePath: string,
-  configGlobs: readonly string[]
-): boolean {
-  const normalizedCandidatePath = toSlashPath(candidatePath);
-  return configGlobs.some((configGlob) =>
-    minimatch(normalizedCandidatePath, configGlob, { dot: true })
-  );
-}
+export { matchesAnyConfigGlob } from "../../data-boundary/config-glob.ts";

package/src/package-checks/project-files/configuration.ts

@@ -1,7 +1,8 @@
 import {
   hasRequiredAndOptionalRecordKeys,
   snapshotClosedArray,
-  snapshotClosedRecord
+  snapshotClosedRecord,
+  snapshotExactClosedRecord
 } from "../../data-boundary/closed-values.ts";
 
 export const PROJECT_FILE_SOURCES = Object.freeze(["filesystem", "git-worktree"] as const);
@@ -101,7 +102,7 @@ export function snapshotProjectFileSelection(
 }
 
 export function validProjectFileSelection(value: unknown): value is ProjectFileSelection {
-  const selection = exactRecord(value, ["exclude", "include", "source"]);
+  const selection = snapshotExactClosedRecord(value, ["exclude", "include", "source"]);
   return (
     selection !== undefined &&
     validStringArray(selection.exclude) &&
@@ -126,25 +127,13 @@ function resolveStringArray(
 
 function validStringArray(value: unknown): boolean {
   const items = snapshotClosedArray(value);
-  return items !== undefined && items.every(isString);
+  return items?.every(isString) === true;
 }
 
 function isString(value: unknown): value is string {
   return typeof value === "string";
 }
 
-function exactRecord(
-  value: unknown,
-  keys: readonly string[]
-): Readonly<Record<string, unknown>> | undefined {
-  const record = snapshotClosedRecord(value);
-  return record !== undefined &&
-    Object.keys(record).length === keys.length &&
-    keys.every((key) => Object.hasOwn(record, key))
-    ? record
-    : undefined;
-}
-
 function deepFreeze<T>(value: T): T {
   if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
   for (const nested of Object.values(value)) deepFreeze(nested);

package/src/package-checks/project-files/gitlink-revision.ts

@@ -1,7 +1,7 @@
 /** Reads canonical gitlink entries from a named Git tree revision. */
 
-import { processFailed } from "../host-environment/process/command.ts";
-import { runGit } from "../host-environment/git.ts";
+import { processFailed } from "../host-environment/process.ts";
+import { gitFailureDetail, runGit } from "../host-environment/git.ts";
 import { toSlashPath } from "../host-environment/path.ts";
 
 export type Gitlink = Readonly<{
@@ -21,11 +21,9 @@ export function gitlinksAtRevision({
     cwd: repository
   });
   if (processFailed(result)) {
-    const detail =
-      result.stderr.trim() ||
-      result.error?.message ||
-      (result.signal === null ? `exit status ${result.status}` : `signal ${result.signal}`);
-    throw new Error(`could not inspect gitlinks at ${revision} in ${repository}: ${detail}`);
+    throw new Error(
+      `could not inspect gitlinks at ${revision} in ${repository}: ${gitFailureDetail(result)}`
+    );
   }
 
   const gitlinks: Gitlink[] = [];

package/src/package-checks/project-files/gitlink-worktree.ts

@@ -4,7 +4,7 @@ import { realpathSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 
 import { errorMessage } from "../host-environment/error-message.ts";
-import { processFailed } from "../host-environment/process/command.ts";
+import { processFailed } from "../host-environment/process.ts";
 import { runGit } from "../host-environment/git.ts";
 
 export type GitlinkWorktreeInspection =
@@ -24,26 +24,54 @@ export function inspectGitlinkWorktree({
   readonly gitlinkPath: string;
   readonly repository: string;
 }>): GitlinkWorktreeInspection {
+  const localWorktree = inspectLocalGitlinkWorktree({ gitlinkPath, repository });
+  if (localWorktree.kind !== "found") return localWorktree;
+  return inspectGitRepositoryRoot({
+    gitlinkPath,
+    canonicalSubmoduleRepository: localWorktree.repository
+  });
+}
+
+type LocalGitlinkWorktree = Readonly<{ readonly kind: "found"; readonly repository: string }>;
+
+function inspectLocalGitlinkWorktree({
+  gitlinkPath,
+  repository
+}: Readonly<{
+  readonly gitlinkPath: string;
+  readonly repository: string;
+}>): GitlinkWorktreeInspection | LocalGitlinkWorktree {
   const submoduleRepository = resolve(repository, gitlinkPath);
-  let canonicalSubmoduleRepository: string;
   try {
     if (!statSync(submoduleRepository).isDirectory()) return { kind: "missing" };
-    canonicalSubmoduleRepository = canonicalRepositoryPath(submoduleRepository);
+    return { kind: "found", repository: canonicalRepositoryPath(submoduleRepository) };
   } catch (error: unknown) {
     return missingPath(error)
       ? { kind: "missing" }
       : inspectionFailure(`could not inspect submodule worktree ${gitlinkPath}`, error);
   }
+}
 
+function inspectGitRepositoryRoot({
+  gitlinkPath,
+  canonicalSubmoduleRepository
+}: Readonly<{
+  readonly gitlinkPath: string;
+  readonly canonicalSubmoduleRepository: string;
+}>): GitlinkWorktreeInspection {
   const topLevelResult = runGit({
     args: ["rev-parse", "--show-toplevel"],
     cwd: canonicalSubmoduleRepository
   });
   if (processFailed(topLevelResult)) {
-    const topLevelFailureDetail =
-      topLevelResult.error?.message ||
-      topLevelResult.stderr.trim() ||
-      `exit ${topLevelResult.status}`;
+    const processErrorMessage = topLevelResult.error?.message;
+    const stderr = topLevelResult.stderr.trim();
+    let topLevelFailureDetail = `exit ${topLevelResult.status}`;
+    if (processErrorMessage !== undefined && processErrorMessage.length > 0) {
+      topLevelFailureDetail = processErrorMessage;
+    } else if (stderr.length > 0) {
+      topLevelFailureDetail = stderr;
+    }
     return {
       kind: "inspection-failed",
       error: `git rev-parse --show-toplevel failed while inspecting submodule ${gitlinkPath}: ${topLevelFailureDetail}`
@@ -51,7 +79,7 @@ export function inspectGitlinkWorktree({
   }
 
   const topLevel = topLevelResult.stdout.trim();
-  if (!topLevel) {
+  if (topLevel.length === 0) {
     return {
       kind: "inspection-failed",
       error: `git rev-parse --show-toplevel returned no repository path for submodule ${gitlinkPath}`

package/src/package-checks/project-files/public-collection.ts

@@ -0,0 +1,92 @@
+/** Public validation and immutable snapshot boundary for one project-file selection. */
+
+import { resolve } from "node:path";
+
+import {
+  snapshotClosedArray,
+  snapshotExactClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import { collectProjectFiles as collectTrustedProjectFiles } from "./collection.ts";
+import { PROJECT_FILE_SOURCES } from "./configuration.ts";
+import type { ProjectFileSelection, ProjectFileSource } from "./configuration.ts";
+
+/** 调用方请求一次项目文件收集时必须完整提供的 root 与 selection。 */
+export interface CollectProjectFilesOptions {
+  /** 显式 project root；relative path 相对当前工作目录解析，不能为空或含 U+0000。 */
+  readonly projectRoot: string;
+  /** 完整的显式 selection；本工具不推断任何 Check 默认值。 */
+  readonly selection: ProjectFileSelection;
+}
+
+type ResolvedCollectProjectFilesOptions = Readonly<{
+  readonly projectRoot: string;
+  readonly selection: ProjectFileSelection;
+}>;
+
+/**
+ * 按一份完整的显式 selection 同步收集 project-root-relative slash paths。
+ *
+ * 成功结果是冻结的稳定去重排序快照，空数组表示没有匹配路径。非法参数同步抛出
+ * `TypeError`；选定 filesystem 或 Git source 的收集失败继续抛出普通 `Error`，不会回退来源。
+ */
+export function collectProjectFiles(
+  authoredOptions: CollectProjectFilesOptions
+): readonly string[] {
+  const options = parseOptions(authoredOptions);
+  return Object.freeze([...collectTrustedProjectFiles(options.projectRoot, options.selection)]);
+}
+
+function parseOptions(value: unknown): ResolvedCollectProjectFilesOptions {
+  const options = snapshotExactClosedRecord(value, ["projectRoot", "selection"]);
+  if (options === undefined) {
+    throw new TypeError(
+      "collectProjectFiles requires an options record with exactly projectRoot and selection"
+    );
+  }
+
+  const projectRoot = parseProjectRoot(options.projectRoot);
+  if (projectRoot === undefined) {
+    throw new TypeError(
+      "collectProjectFiles projectRoot must be a non-empty string without U+0000"
+    );
+  }
+
+  const selection = parseSelection(options.selection);
+  if (selection === undefined) {
+    throw new TypeError(
+      "collectProjectFiles selection must be a complete record with source, include, and exclude"
+    );
+  }
+
+  return Object.freeze({ projectRoot, selection });
+}
+
+function parseProjectRoot(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 && !value.includes("\0")
+    ? resolve(value)
+    : undefined;
+}
+
+function parseSelection(value: unknown): ProjectFileSelection | undefined {
+  const selection = snapshotExactClosedRecord(value, ["source", "include", "exclude"]);
+  if (selection === undefined) return undefined;
+
+  const include = snapshotStringArray(selection.include);
+  const exclude = snapshotStringArray(selection.exclude);
+  if (include === undefined || exclude === undefined || !isProjectFileSource(selection.source)) {
+    return undefined;
+  }
+
+  return Object.freeze({ exclude, include, source: selection.source });
+}
+
+function snapshotStringArray(value: unknown): readonly string[] | undefined {
+  const items = snapshotClosedArray(value);
+  return items?.every((item): item is string => typeof item === "string") === true
+    ? Object.freeze([...items])
+    : undefined;
+}
+
+function isProjectFileSource(value: unknown): value is ProjectFileSource {
+  return PROJECT_FILE_SOURCES.some((source) => source === value);
+}

package/src/package-checks/project-files/revision-paths.ts

@@ -1,7 +1,7 @@
 /** Path and Git-output projections shared by revision traversal helpers. */
 
 import { toSlashPath } from "../host-environment/path.ts";
-import { matchesAnyConfigGlob } from "./config-glob.ts";
+import { matchesAnyConfigGlob } from "../../data-boundary/config-glob.ts";
 
 export function uniqueSortedPaths(files: readonly string[]): string[] {
   return [...new Set(files.map(toSlashPath))].sort();
@@ -29,6 +29,6 @@ export function joinSlash({
 }
 
 export function nonEmptyGitOutput(stdout: string | null | undefined): string | null {
-  const value = (stdout || "").trim();
-  return value || null;
+  const value = (stdout ?? "").trim();
+  return value.length > 0 ? value : null;
 }