@zxyycom/vibe-check 0.0.1

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

@@ -0,0 +1,199 @@
+/** Project-root file discovery and selection helpers. */
+
+import { lstatSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { matchesAnyConfigGlob } from "./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 { toSlashPath } from "../host-environment/path.ts";
+import { walkFiles } from "../host-environment/filesystem.ts";
+import type { ProjectFileSelection, ProjectFileSource } from "./configuration.ts";
+
+type NamedProjectFileSelection = Readonly<{
+  readonly id: string;
+  readonly selection: ProjectFileSelection;
+}>;
+
+const CONFIG_GLOB_MAGIC = /[\\*?[\]{}()!+@]/u;
+
+/**
+ * Resolves multiple named file sets while enumerating each distinct candidate source once.
+ */
+export function collectProjectFileSets(
+  rootDir: string,
+  selections: Readonly<Record<string, ProjectFileSelection>>
+): ReadonlyMap<string, readonly string[]> {
+  const bySource = groupSelectionsBySource(selections);
+  const selectedFiles = new Map<string, readonly string[]>();
+
+  for (const [source, sourceSelections] of bySource) {
+    const candidates = collectSourceCandidates(rootDir, source, sourceSelections);
+    for (const { id, selection } of sourceSelections) {
+      selectedFiles.set(id, Object.freeze(filterProjectFiles(candidates, selection)));
+    }
+  }
+
+  return selectedFiles;
+}
+
+export function collectProjectFiles(rootDir: string, selection: ProjectFileSelection): string[] {
+  return [...requireProjectFileSet(collectProjectFileSets(rootDir, { selection }), "selection")];
+}
+
+/** 返回已收集的命名文件集合；缺失表示收集完整性失效，不能解释为空集合。 */
+export function requireProjectFileSet(
+  fileSets: ReadonlyMap<string, readonly string[]>,
+  selectionId: string
+): readonly string[] {
+  const selectedFiles = fileSets.get(selectionId);
+  if (selectedFiles === undefined) {
+    throw new Error(`project file collection did not produce selection ${selectionId}`);
+  }
+  return selectedFiles;
+}
+
+function groupSelectionsBySource(
+  selections: Readonly<Record<string, ProjectFileSelection>>
+): ReadonlyMap<ProjectFileSource, readonly NamedProjectFileSelection[]> {
+  const mutableGroups = new Map<ProjectFileSource, NamedProjectFileSelection[]>();
+  const entries = Object.entries(selections).sort(([left], [right]) => compareText(left, right));
+
+  for (const [id, selection] of entries) {
+    const group = mutableGroups.get(selection.source) ?? [];
+    group.push({ id, selection });
+    mutableGroups.set(selection.source, group);
+  }
+
+  return new Map(
+    [...mutableGroups].map(([source, group]) => [source, Object.freeze(group)] as const)
+  );
+}
+
+function collectSourceCandidates(
+  rootDir: string,
+  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)}`);
+    }
+  }
+}
+
+function collectGitWorktreeCandidates(
+  rootDir: string,
+  selections: readonly NamedProjectFileSelection[]
+): readonly string[] {
+  const result = runGit({
+    args: ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--"],
+    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}`);
+  }
+
+  const include = uniqueSorted(selections.flatMap(({ selection }) => [...selection.include]));
+  return uniqueSorted(
+    [
+      ...splitNulDelimitedGitFileList(result.stdout),
+      ...collectSubmoduleWorktreeFiles({ repository: rootDir, scanInputPaths: include })
+    ]
+      .map(toSlashPath)
+      .filter((filePath) => isGitWorktreeFile({ filePath, rootDir }))
+  );
+}
+
+function isGitWorktreeFile({
+  filePath,
+  rootDir
+}: Readonly<{ readonly filePath: string; readonly rootDir: string }>): boolean {
+  try {
+    const stats = lstatSync(resolve(rootDir, filePath));
+    return stats.isFile() || stats.isSymbolicLink();
+  } catch (error: unknown) {
+    if (missingPath(error)) return false;
+    throw new Error(
+      `could not inspect git-worktree candidate ${filePath} in ${rootDir}: ${errorMessage(error)}`,
+      { cause: error }
+    );
+  }
+}
+
+function missingPath(error: unknown): boolean {
+  const code = error instanceof Error && "code" in error ? error.code : undefined;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+
+function filterProjectFiles(
+  candidates: readonly string[],
+  selection: ProjectFileSelection
+): string[] {
+  return uniqueSorted(candidates.filter((filePath) => isProjectFile(filePath, selection)));
+}
+
+function isProjectFile(filePath: string, selection: ProjectFileSelection): boolean {
+  const normalized = toSlashPath(filePath);
+  return (
+    matchesAnyConfigGlob(normalized, selection.include) &&
+    !matchesAnyConfigGlob(normalized, selection.exclude)
+  );
+}
+
+/**
+ * Recognizes only whole-directory exclusions with one literal directory segment. The
+ * intersection is a traversal optimization; public semantics remain in `isProjectFile`.
+ */
+function commonExcludedDirectoryNames(
+  selections: readonly NamedProjectFileSelection[]
+): readonly string[] {
+  let common: Set<string> | undefined;
+  for (const { selection } of selections) {
+    const names = new Set(selection.exclude.map(literalExcludedDirectoryName).filter(isString));
+    common =
+      common === undefined
+        ? names
+        : new Set([...common].filter((directoryName) => names.has(directoryName)));
+  }
+  return common === undefined ? [] : [...common].sort();
+}
+
+function literalExcludedDirectoryName(configGlob: string): string | undefined {
+  const prefix = "**/";
+  const suffix = "/**";
+  if (!configGlob.startsWith(prefix) || !configGlob.endsWith(suffix)) return undefined;
+  const directoryName = configGlob.slice(prefix.length, -suffix.length);
+  if (directoryName.length === 0 || directoryName.includes("/")) return undefined;
+  return CONFIG_GLOB_MAGIC.test(directoryName) ? undefined : directoryName;
+}
+
+function isString(value: string | undefined): value is string {
+  return value !== undefined;
+}
+
+function uniqueSorted(files: readonly string[]): string[] {
+  return [...new Set(files)].sort(compareText);
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}

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

@@ -0,0 +1,17 @@
+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 })
+  );
+}

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

@@ -0,0 +1,152 @@
+import {
+  hasRequiredAndOptionalRecordKeys,
+  snapshotClosedArray,
+  snapshotClosedRecord
+} from "../../data-boundary/closed-values.ts";
+
+export const PROJECT_FILE_SOURCES = Object.freeze(["filesystem", "git-worktree"] as const);
+
+/** 文件选择可使用的显式候选来源。 */
+export type ProjectFileSource = (typeof PROJECT_FILE_SOURCES)[number];
+
+/** 读取项目文件的 Check 所拥有的文件选择输入。 */
+export interface ProjectFileSelectionOptions {
+  /** 候选文件来源；省略时使用 owning Check 的来源默认值，当前随包 Check 均为 `filesystem`。 */
+  readonly source?: ProjectFileSource;
+  /** 相对项目根目录且使用 `/` 的 glob；省略时使用 owning Check 的 include 默认值，显式数组完整替换。 */
+  readonly include?: readonly string[];
+  /** 优先于 `include` 的 glob；省略时使用 owning Check 的 exclude 默认值，显式数组完整替换。 */
+  readonly exclude?: readonly string[];
+}
+
+/** Check execution 消费的完整项目文件选择。 */
+export interface ProjectFileSelection {
+  readonly exclude: readonly string[];
+  readonly include: readonly string[];
+  readonly source: ProjectFileSource;
+}
+
+/**
+ * Package-provided Checks 共用的通用文件选择基线。
+ *
+ * 对象与数组均不可变；需要保留默认排除并追加项目规则时，使用对象与数组 spread 建立新值。
+ * 个别 Check 会从此 baseline 派生更精准的默认 include；显式组合此 value 仍表示通配全部路径。
+ */
+export const defaultProjectFileSelection: ProjectFileSelection = deepFreeze({
+  exclude: [
+    "**/.cache/**",
+    "**/.git",
+    "**/.git/**",
+    "**/.log/**",
+    "**/.pytest_cache/**",
+    "**/.tmp/**",
+    "**/.venv/**",
+    "**/.vibe-check/**",
+    "**/__pycache__/**",
+    "**/artifacts/**",
+    "**/build/**",
+    "**/coverage/**",
+    "**/dist/**",
+    "**/generated/**",
+    "**/*.generated.*",
+    "**/node_modules/**",
+    "**/target/**",
+    "**/tmp/**",
+    "**/vendor/**",
+    "**/venv/**"
+  ],
+  include: ["**/*"],
+  source: "filesystem"
+});
+
+/** 按 owning Check 提供的可信完整 defaults 解析并冻结一份 authoring selection。 */
+export function resolveProjectFileSelection(
+  value: unknown,
+  defaults: ProjectFileSelection = defaultProjectFileSelection
+): ProjectFileSelection | undefined {
+  const selection = snapshotClosedRecord(value);
+  if (
+    selection === undefined ||
+    !hasRequiredAndOptionalRecordKeys(selection, {
+      optional: ["exclude", "include", "source"],
+      required: []
+    })
+  ) {
+    return undefined;
+  }
+
+  const exclude = resolveStringArray(selection.exclude, defaults.exclude);
+  const include = resolveStringArray(selection.include, defaults.include);
+  const source = selection.source ?? defaults.source;
+  if (exclude === undefined || include === undefined || !isProjectFileSource(source)) {
+    return undefined;
+  }
+
+  return Object.freeze({ exclude, include, source });
+}
+
+export function snapshotDefaultProjectFileSelection(): ProjectFileSelection {
+  return snapshotProjectFileSelection(defaultProjectFileSelection);
+}
+
+/** 为 owning Check 对可信的完整 selection 建立 detached、冻结快照。 */
+export function snapshotProjectFileSelection(
+  selection: ProjectFileSelection
+): ProjectFileSelection {
+  return Object.freeze({
+    exclude: Object.freeze([...selection.exclude]),
+    include: Object.freeze([...selection.include]),
+    source: selection.source
+  });
+}
+
+export function validProjectFileSelection(value: unknown): value is ProjectFileSelection {
+  const selection = exactRecord(value, ["exclude", "include", "source"]);
+  return (
+    selection !== undefined &&
+    validStringArray(selection.exclude) &&
+    validStringArray(selection.include) &&
+    isProjectFileSource(selection.source)
+  );
+}
+
+function isProjectFileSource(value: unknown): value is ProjectFileSource {
+  return PROJECT_FILE_SOURCES.some((source) => source === value);
+}
+
+function resolveStringArray(
+  value: unknown,
+  fallback: readonly string[]
+): readonly string[] | undefined {
+  if (value === undefined) return Object.freeze([...fallback]);
+  const items = snapshotClosedArray(value);
+  if (items === undefined || !items.every(isString)) return undefined;
+  return Object.freeze([...items]);
+}
+
+function validStringArray(value: unknown): boolean {
+  const items = snapshotClosedArray(value);
+  return items !== undefined && items.every(isString);
+}
+
+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);
+  return Object.freeze(value);
+}

package/src/package-checks/project-files/exact-input-measurement.ts

@@ -0,0 +1,38 @@
+export type ExactInputMeasurement<T> = {
+  readonly payload: T;
+  readonly sourcePaths: readonly string[];
+};
+
+export type ExactInputMeasurementAcceptance<T> =
+  | { readonly ok: true; readonly payloads: readonly T[] }
+  | { readonly error: string; readonly ok: false };
+
+export function acceptExactInputMeasurements<T>(
+  measurements: readonly ExactInputMeasurement<T>[],
+  approvedExactPaths: readonly string[]
+): ExactInputMeasurementAcceptance<T> {
+  const approvedPathSet = new Set(approvedExactPaths);
+
+  for (const [index, measurement] of measurements.entries()) {
+    if (measurement.sourcePaths.length === 0) {
+      return {
+        error: `scanner measurement #${index + 1} did not declare a source path`,
+        ok: false
+      };
+    }
+
+    for (const sourcePath of measurement.sourcePaths) {
+      if (!approvedPathSet.has(sourcePath)) {
+        return {
+          error: `scanner measurement #${index + 1} references unapproved input path ${JSON.stringify(sourcePath)}`,
+          ok: false
+        };
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    payloads: measurements.map((measurement) => measurement.payload)
+  };
+}

package/src/package-checks/project-files/file-fingerprint.ts

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export interface FileInputFingerprint {
+  readonly fileCount: number;
+  readonly fileList: readonly string[];
+  readonly fingerprint: string;
+}
+
+/** Fingerprints one exact path set from stable path order and normalized current file content. */
+export function fingerprintProjectFiles(
+  rootDir: string,
+  paths: readonly string[]
+): FileInputFingerprint {
+  const sortedPaths = [...paths].sort(compareText);
+  const inputDigest = createHash("sha256");
+
+  for (const path of sortedPaths) {
+    inputDigest.update(path, "utf8");
+    inputDigest.update("\0");
+    inputDigest.update(fileContentFingerprint(rootDir, path), "utf8");
+    inputDigest.update("\n");
+  }
+
+  return Object.freeze({
+    fileCount: sortedPaths.length,
+    fileList: Object.freeze(sortedPaths.slice(0, 200)),
+    fingerprint: `sha256:${inputDigest.digest("hex")}:${sortedPaths.length}`
+  });
+}
+
+function fileContentFingerprint(rootDir: string, path: string): string {
+  try {
+    const content = readFileSync(resolve(rootDir, path), "utf8").replace(/\r\n?/g, "\n");
+    return createHash("sha256").update(content).digest("hex");
+  } catch {
+    return "file-not-readable";
+  }
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}

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

@@ -0,0 +1,82 @@
+/** 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 { toSlashPath } from "../host-environment/path.ts";
+
+export type Gitlink = Readonly<{
+  readonly path: string;
+  readonly sha: string;
+}>;
+
+export function gitlinksAtRevision({
+  repository,
+  revision
+}: Readonly<{
+  readonly repository: string;
+  readonly revision: string;
+}>): readonly Gitlink[] {
+  const result = runGit({
+    args: ["ls-tree", "-r", "-z", revision],
+    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}`);
+  }
+
+  const gitlinks: Gitlink[] = [];
+  for (const entry of result.stdout.split("\0")) {
+    if (!entry) continue;
+    const gitlink = parseGitlinkEntry({ entry, repository, revision });
+    if (gitlink !== null) gitlinks.push(gitlink);
+  }
+  return Object.freeze(gitlinks);
+}
+
+function parseGitlinkEntry({
+  entry,
+  repository,
+  revision
+}: Readonly<{
+  readonly entry: string;
+  readonly repository: string;
+  readonly revision: string;
+}>): Gitlink | null {
+  const parsed = gitTreeEntryParts(entry);
+  if (parsed === undefined) throw invalidTreeOutput(revision, repository);
+  const [mode, type, sha] = parsed.metadata;
+  if (!validGitTreeMetadata(mode, type, sha)) throw invalidTreeOutput(revision, repository);
+  if (mode !== "160000") return null;
+  if (type !== "commit") {
+    throw new Error(`invalid gitlink output at ${revision} in ${repository}`);
+  }
+  return Object.freeze({ path: toSlashPath(parsed.path), sha });
+}
+
+function gitTreeEntryParts(entry: string): { metadata: string[]; path: string } | undefined {
+  const separator = entry.indexOf("\t");
+  if (separator < 0) return undefined;
+  const metadata = entry.slice(0, separator).split(/\s+/u);
+  const path = entry.slice(separator + 1);
+  return metadata.length === 3 && path.length > 0 ? { metadata, path } : undefined;
+}
+
+function validGitTreeMetadata(
+  mode: string | undefined,
+  type: string | undefined,
+  sha: string | undefined
+): sha is string {
+  return mode !== undefined && type !== undefined && sha !== undefined && isFullGitObjectId(sha);
+}
+
+function invalidTreeOutput(revision: string, repository: string): Error {
+  return new Error(`invalid git tree output at ${revision} in ${repository}`);
+}
+
+function isFullGitObjectId(value: string): boolean {
+  return /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(value);
+}

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

@@ -0,0 +1,106 @@
+/** Canonical Git worktree checks for gitlink traversal. */
+
+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 { runGit } from "../host-environment/git.ts";
+
+export type GitlinkWorktreeInspection =
+  | { readonly kind: "initialized"; readonly repository: string }
+  | { readonly kind: "inspection-failed"; readonly error: string }
+  | { readonly kind: "missing" }
+  | { readonly kind: "not-independent" };
+
+export function canonicalRepositoryPath(repository: string): string {
+  return realpathSync(resolve(repository));
+}
+
+export function inspectGitlinkWorktree({
+  gitlinkPath,
+  repository
+}: Readonly<{
+  readonly gitlinkPath: string;
+  readonly repository: string;
+}>): GitlinkWorktreeInspection {
+  const submoduleRepository = resolve(repository, gitlinkPath);
+  let canonicalSubmoduleRepository: string;
+  try {
+    if (!statSync(submoduleRepository).isDirectory()) return { kind: "missing" };
+    canonicalSubmoduleRepository = canonicalRepositoryPath(submoduleRepository);
+  } catch (error: unknown) {
+    return missingPath(error)
+      ? { kind: "missing" }
+      : inspectionFailure(`could not inspect submodule worktree ${gitlinkPath}`, error);
+  }
+
+  const topLevelResult = runGit({
+    args: ["rev-parse", "--show-toplevel"],
+    cwd: canonicalSubmoduleRepository
+  });
+  if (processFailed(topLevelResult)) {
+    const topLevelFailureDetail =
+      topLevelResult.error?.message ||
+      topLevelResult.stderr.trim() ||
+      `exit ${topLevelResult.status}`;
+    return {
+      kind: "inspection-failed",
+      error: `git rev-parse --show-toplevel failed while inspecting submodule ${gitlinkPath}: ${topLevelFailureDetail}`
+    };
+  }
+
+  const topLevel = topLevelResult.stdout.trim();
+  if (!topLevel) {
+    return {
+      kind: "inspection-failed",
+      error: `git rev-parse --show-toplevel returned no repository path for submodule ${gitlinkPath}`
+    };
+  }
+
+  try {
+    return canonicalRepositoryPath(resolve(canonicalSubmoduleRepository, topLevel)) ===
+      canonicalSubmoduleRepository
+      ? { kind: "initialized", repository: canonicalSubmoduleRepository }
+      : { kind: "not-independent" };
+  } catch (error: unknown) {
+    return inspectionFailure(`could not resolve Git top-level for submodule ${gitlinkPath}`, error);
+  }
+}
+
+export function resolveDescendableGitlinkRepository({
+  gitlinkPath,
+  repository,
+  visitedRepositories
+}: Readonly<{
+  readonly gitlinkPath: string;
+  readonly repository: string;
+  readonly visitedRepositories: ReadonlySet<string>;
+}>): string | null {
+  const inspection = inspectGitlinkWorktree({ gitlinkPath, repository });
+  if (inspection.kind === "inspection-failed") {
+    throw new Error(inspection.error);
+  }
+  return inspection.kind === "initialized" && !visitedRepositories.has(inspection.repository)
+    ? inspection.repository
+    : null;
+}
+
+export function visitRepository({
+  repository,
+  visitedRepositories
+}: Readonly<{
+  readonly repository: string;
+  readonly visitedRepositories: ReadonlySet<string>;
+}>): ReadonlySet<string> {
+  return new Set([...visitedRepositories, repository]);
+}
+
+function missingPath(error: unknown): boolean {
+  const code = error instanceof Error && "code" in error ? error.code : undefined;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+
+function inspectionFailure(message: string, error: unknown): GitlinkWorktreeInspection {
+  return { kind: "inspection-failed", error: `${message}: ${errorMessage(error)}` };
+}

package/src/package-checks/project-files/input-eligibility.ts

@@ -0,0 +1,21 @@
+/** 一个 Check 对完整 selected path set 做 eligibility 分类后的结果。 */
+export interface ProjectFileEligibilityPartition {
+  readonly acceptedPaths: readonly string[];
+  readonly rejectedPaths: readonly string[];
+}
+
+/** 保持输入顺序，将每个 selected path 恰好分配给 accepted 或 rejected。 */
+export function partitionProjectFilesByEligibility(
+  selectedPaths: readonly string[],
+  accepts: (path: string) => boolean
+): ProjectFileEligibilityPartition {
+  const acceptedPaths: string[] = [];
+  const rejectedPaths: string[] = [];
+  for (const path of selectedPaths) {
+    (accepts(path) ? acceptedPaths : rejectedPaths).push(path);
+  }
+  return Object.freeze({
+    acceptedPaths: Object.freeze(acceptedPaths),
+    rejectedPaths: Object.freeze(rejectedPaths)
+  });
+}