@zxyycom/vibe-check 0.0.1

package/src/package-checks/project-files/reported-path.ts

@@ -0,0 +1,35 @@
+import path from "node:path";
+
+import { toSlashPath } from "../host-environment/path.ts";
+
+export function normalizeScannerReportedPath(reportedPath: string, projectRoot: string): string {
+  const normalizedReportedPath = stripWindowsExtendedPathPrefix(reportedPath);
+  const normalizedProjectRoot = stripWindowsExtendedPathPrefix(projectRoot);
+  const pathApi = pathApiForScannerPath(normalizedReportedPath, normalizedProjectRoot);
+  const nativePath = pathApi.normalize(normalizedReportedPath);
+  const projectRelativePath = pathApi.isAbsolute(nativePath)
+    ? pathApi.relative(pathApi.normalize(normalizedProjectRoot), nativePath)
+    : nativePath;
+
+  return toSlashPath(projectRelativePath);
+}
+
+function stripWindowsExtendedPathPrefix(filePath: string): string {
+  if (filePath.startsWith("\\\\?\\UNC\\")) {
+    return `\\\\${filePath.slice(8)}`;
+  }
+  if (filePath.startsWith("\\\\?\\")) {
+    return filePath.slice(4);
+  }
+  return filePath;
+}
+
+function pathApiForScannerPath(reportedPath: string, projectRoot: string): path.PlatformPath {
+  return isWindowsAbsolutePath(reportedPath) || isWindowsAbsolutePath(projectRoot)
+    ? path.win32
+    : path;
+}
+
+function isWindowsAbsolutePath(filePath: string): boolean {
+  return /^[A-Za-z]:[\\/]/u.test(filePath) || filePath.startsWith("\\\\");
+}

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

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

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

@@ -0,0 +1,148 @@
+/** Enumerates files from initialized, non-cyclic submodule working trees. */
+
+import { processFailed } from "../host-environment/process/command.ts";
+import { runGit, splitNulDelimitedGitFileList } from "../host-environment/git.ts";
+import {
+  canonicalRepositoryPath,
+  resolveDescendableGitlinkRepository,
+  visitRepository
+} from "./gitlink-worktree.ts";
+import { gitlinksAtRevision } from "./gitlink-revision.ts";
+import {
+  joinSlash,
+  nonEmptyGitOutput,
+  prefixAndFilter,
+  uniqueSortedPaths
+} from "./revision-paths.ts";
+
+export function collectSubmoduleWorktreeFiles({
+  repository,
+  scanInputPaths
+}: Readonly<{
+  readonly repository: string;
+  readonly scanInputPaths: readonly string[];
+}>): string[] {
+  const files: string[] = [];
+  const visitedRepositories = new Set([canonicalRepositoryPath(repository)]);
+  const revision = worktreeRevision(repository);
+  if (revision === null) return files;
+
+  for (const gitlink of gitlinksAtRevision({ repository, revision })) {
+    const submoduleRepository = resolveDescendableGitlinkRepository({
+      gitlinkPath: gitlink.path,
+      repository,
+      visitedRepositories
+    });
+    if (!submoduleRepository) continue;
+    files.push(
+      ...collectWorktreeFiles({
+        prefix: gitlink.path,
+        repository: submoduleRepository,
+        scanInputPaths,
+        visitedRepositories: visitRepository({
+          repository: submoduleRepository,
+          visitedRepositories
+        })
+      })
+    );
+  }
+  return uniqueSortedPaths(files);
+}
+
+function collectWorktreeFiles({
+  prefix,
+  repository,
+  scanInputPaths,
+  visitedRepositories
+}: Readonly<{
+  readonly prefix: string;
+  readonly repository: string;
+  readonly scanInputPaths: readonly string[];
+  readonly visitedRepositories: ReadonlySet<string>;
+}>): string[] {
+  const result = runGit({
+    args: ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--"],
+    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 enumerate git-worktree files in ${repository}: ${detail}`);
+  }
+
+  const files = prefixAndFilter({
+    files: splitNulDelimitedGitFileList(result.stdout),
+    prefix,
+    scanInputPaths
+  });
+  const revision = worktreeRevision(repository);
+  if (revision === null) return uniqueSortedPaths(files);
+  files.push(
+    ...collectNestedWorktreeFiles({
+      prefix,
+      repository,
+      revision,
+      scanInputPaths,
+      visitedRepositories
+    })
+  );
+  return uniqueSortedPaths(files);
+}
+
+function collectNestedWorktreeFiles({
+  prefix,
+  repository,
+  revision,
+  scanInputPaths,
+  visitedRepositories
+}: Readonly<{
+  readonly prefix: string;
+  readonly repository: string;
+  readonly revision: string;
+  readonly scanInputPaths: readonly string[];
+  readonly visitedRepositories: ReadonlySet<string>;
+}>): string[] {
+  const files: string[] = [];
+  for (const gitlink of gitlinksAtRevision({ repository, revision })) {
+    const submoduleRepository = resolveDescendableGitlinkRepository({
+      gitlinkPath: gitlink.path,
+      repository,
+      visitedRepositories
+    });
+    if (!submoduleRepository) continue;
+    files.push(
+      ...collectWorktreeFiles({
+        prefix: joinSlash({ path: gitlink.path, prefix }),
+        repository: submoduleRepository,
+        scanInputPaths,
+        visitedRepositories: visitRepository({
+          repository: submoduleRepository,
+          visitedRepositories
+        })
+      })
+    );
+  }
+  return files;
+}
+
+function worktreeRevision(repository: string): string | null {
+  const result = runGit({ args: ["rev-parse", "--verify", "--quiet", "HEAD"], cwd: repository });
+  if (!processFailed(result)) {
+    const revision = nonEmptyGitOutput(result.stdout);
+    if (revision !== null) return revision;
+    throw new Error(`git-worktree revision inspection returned no revision in ${repository}`);
+  }
+  const headDoesNotExist =
+    result.error === undefined &&
+    result.signal === null &&
+    result.status === 1 &&
+    result.stderr.trim() === "";
+  if (headDoesNotExist) return null;
+  const detail =
+    result.stderr.trim() ||
+    result.error?.message ||
+    (result.signal === null ? `exit status ${result.status}` : `signal ${result.signal}`);
+  throw new Error(`could not inspect git-worktree revision in ${repository}: ${detail}`);
+}

package/src/project-definition/check-tree/authoring.ts

@@ -0,0 +1,332 @@
+import type { CheckDescriptor } from "../../check/descriptor.ts";
+import {
+  isInheritedCheckCollection,
+  snapshotInheritedCheckCollection,
+  type CheckVisibility,
+  type CheckExecution,
+  type CheckPreflight,
+  type InheritedCheckCollection
+} from "../../check/check.ts";
+import { snapshotClosedArray, snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
+import { validateCheckDescriptor } from "../../check/descriptor-validation.ts";
+import { snapshotJsonObject } from "../../check/options-snapshot.ts";
+
+type TrustedDataParser = (this: void, ...parameters: never[]) => unknown;
+
+export type ParsedCheckCollection = Readonly<
+  | { readonly kind: "exact"; readonly values: readonly string[] }
+  | {
+      readonly kind: "inherit";
+      readonly add: readonly string[];
+      readonly remove: readonly string[];
+    }
+>;
+
+export interface ParsedCheck {
+  readonly checkId: string;
+  readonly checks: readonly ParsedCheck[];
+  readonly definition: CheckDescriptor | null;
+  readonly dependsOn: ParsedCheckCollection | undefined;
+  readonly displayName: string;
+  readonly execution: CheckExecution | null;
+  readonly maxParallel: number | undefined;
+  readonly mutex: ParsedCheckCollection | undefined;
+  readonly options: object | null;
+  readonly path: string;
+  readonly parseData: TrustedDataParser | null;
+  readonly preflight: CheckPreflight | null;
+  readonly visibility: CheckVisibility | null;
+}
+
+export interface ParsedCheckTree {
+  readonly checks: readonly ParsedCheck[];
+  readonly warnings: readonly MeaninglessCheckWarning[];
+}
+
+export interface MeaninglessCheckWarning {
+  readonly code: "meaningless-check";
+  readonly path: string;
+  readonly checkId: string;
+}
+
+interface ParseState {
+  readonly warnings: MeaninglessCheckWarning[];
+}
+
+interface CheckAuthoringData extends Readonly<Record<string, unknown>> {
+  readonly checkId: string;
+  readonly displayName: string;
+}
+
+interface ParsedCheckFields {
+  readonly definition: CheckDescriptor | null;
+  readonly execution: CheckExecution | null;
+  readonly options: object | null;
+  readonly parseData: TrustedDataParser | null;
+  readonly preflight: CheckPreflight | null;
+  readonly visibility: CheckVisibility | null;
+}
+
+const CHECK_KEYS = [
+  "checkId",
+  "checks",
+  "dependsOn",
+  "displayName",
+  "execution",
+  "maxParallel",
+  "mutex",
+  "options",
+  "parseData",
+  "preflight",
+  "visibility"
+] as const;
+
+const CONTAINER_CHECK_FIELDS: ParsedCheckFields = Object.freeze({
+  definition: null,
+  execution: null,
+  options: null,
+  parseData: null,
+  preflight: null,
+  visibility: null
+});
+
+/**
+ * Parses only the closed recursive authoring grammar. Execution callbacks are
+ * trusted project code, while every declarative field is copied and validated.
+ */
+export function parseCheckTreeAuthoring(value: unknown): ParsedCheckTree | undefined {
+  const roots = snapshotClosedArray(value);
+  if (roots === undefined) return undefined;
+  const state: ParseState = { warnings: [] };
+  const checks: ParsedCheck[] = [];
+  for (let index = 0; index < roots.length; index += 1) {
+    const check = parseCheck(roots[index], `definition.checks[${index}]`, state);
+    if (check === undefined) return undefined;
+    checks.push(check);
+  }
+  return Object.freeze({
+    checks: Object.freeze(checks),
+    warnings: Object.freeze(state.warnings)
+  });
+}
+
+function parseCheck(value: unknown, path: string, state: ParseState): ParsedCheck | undefined {
+  const data = parseCheckData(value);
+  if (data === undefined) return undefined;
+  const execution = parseExecution(data);
+  if (execution === undefined) return undefined;
+  const parseData = parseDataParser(data);
+  if (parseData === undefined) return undefined;
+  const preflight = parsePreflight(data);
+  if (preflight === undefined) return undefined;
+  const checks = parseChildren(data, path, state);
+  if (checks === undefined) return undefined;
+  const scheduling = parseScheduling(data);
+  if (scheduling === undefined) return undefined;
+  const fields = parseCheckFields(data, execution, parseData, preflight);
+  if (fields === undefined) return undefined;
+  warnForMeaninglessCheck(data, checks, fields, path, state);
+
+  return Object.freeze({
+    checkId: data.checkId,
+    checks,
+    definition: fields.definition,
+    dependsOn: scheduling.dependsOn,
+    displayName: data.displayName,
+    execution: fields.execution,
+    maxParallel: scheduling.maxParallel,
+    mutex: scheduling.mutex,
+    options: fields.options,
+    path,
+    parseData: fields.parseData,
+    preflight: fields.preflight,
+    visibility: fields.visibility
+  });
+}
+
+function parseCheckData(value: unknown): CheckAuthoringData | undefined {
+  const data = snapshotClosedRecord(value);
+  if (data === undefined) return undefined;
+  return hasValidCheckIdentity(data) ? data : undefined;
+}
+
+function hasValidCheckIdentity(
+  data: Readonly<Record<string, unknown>>
+): data is CheckAuthoringData {
+  return (
+    hasOnlyCheckKeys(data) &&
+    typeof data.checkId === "string" &&
+    data.checkId.length > 0 &&
+    typeof data.displayName === "string" &&
+    data.displayName.length > 0
+  );
+}
+
+function hasOnlyCheckKeys(data: Readonly<Record<string, unknown>>): boolean {
+  return Object.keys(data).every((key) => CHECK_KEYS.some((checkKey) => checkKey === key));
+}
+
+function parseExecution(data: CheckAuthoringData): CheckExecution | null | undefined {
+  if (!Object.hasOwn(data, "execution")) return null;
+  return isTrustedFunction<CheckExecution>(data.execution) ? data.execution : undefined;
+}
+
+function parseDataParser(data: CheckAuthoringData): TrustedDataParser | null | undefined {
+  if (!Object.hasOwn(data, "parseData") || data.parseData === undefined) return null;
+  return isTrustedFunction<TrustedDataParser>(data.parseData) ? data.parseData : undefined;
+}
+
+function parsePreflight(data: CheckAuthoringData): CheckPreflight | null | undefined {
+  if (!Object.hasOwn(data, "preflight")) return null;
+  return isTrustedFunction<CheckPreflight>(data.preflight) ? data.preflight : undefined;
+}
+
+function isTrustedFunction<FunctionType extends (...parameters: never[]) => unknown>(
+  value: unknown
+): value is FunctionType {
+  return typeof value === "function";
+}
+
+function parseChildren(
+  data: CheckAuthoringData,
+  path: string,
+  state: ParseState
+): readonly ParsedCheck[] | undefined {
+  if (!Object.hasOwn(data, "checks")) return Object.freeze([]);
+  const values = snapshotClosedArray(data.checks);
+  if (values === undefined) return undefined;
+  const checks: ParsedCheck[] = [];
+  for (let index = 0; index < values.length; index += 1) {
+    const check = parseCheck(values[index], `${path}.checks[${index}]`, state);
+    if (check === undefined) return undefined;
+    checks.push(check);
+  }
+  return Object.freeze(checks);
+}
+
+function parseDefinition(data: CheckAuthoringData): CheckDescriptor | undefined {
+  const definition = validateCheckDescriptor({
+    checkId: data.checkId,
+    displayName: data.displayName
+  });
+  return definition.ok ? definition.value : undefined;
+}
+
+function parseOptions(data: CheckAuthoringData): object | undefined {
+  if (!Object.hasOwn(data, "options")) return Object.freeze({});
+  const options = snapshotClosedRecord(data.options);
+  if (options === undefined) return undefined;
+  return snapshotJsonObject(options);
+}
+
+function parseCheckFields(
+  data: CheckAuthoringData,
+  execution: CheckExecution | null,
+  parseData: TrustedDataParser | null,
+  preflight: CheckPreflight | null
+): ParsedCheckFields | undefined {
+  if (execution === null) {
+    return Object.hasOwn(data, "options") ||
+      Object.hasOwn(data, "visibility") ||
+      parseData !== null ||
+      preflight !== null
+      ? undefined
+      : CONTAINER_CHECK_FIELDS;
+  }
+  const definition = parseDefinition(data);
+  if (definition === undefined) return undefined;
+  const options = parseOptions(data);
+  if (options === undefined) return undefined;
+  const visibility = parseVisibility(data);
+  if (visibility === undefined) return undefined;
+  return Object.freeze({
+    definition,
+    execution,
+    options,
+    parseData,
+    preflight,
+    visibility
+  });
+}
+
+function parseVisibility(data: CheckAuthoringData): CheckVisibility | undefined {
+  if (!Object.hasOwn(data, "visibility")) return "always";
+  const visibility = data.visibility;
+  return visibility === undefined || visibility === "always" || visibility === "attention"
+    ? (visibility ?? "always")
+    : undefined;
+}
+
+function warnForMeaninglessCheck(
+  data: CheckAuthoringData,
+  checks: readonly ParsedCheck[],
+  fields: ParsedCheckFields,
+  path: string,
+  state: ParseState
+): void {
+  if (fields.execution !== null || checks.length > 0) return;
+  state.warnings.push(Object.freeze({ code: "meaningless-check", path, checkId: data.checkId }));
+}
+
+function parseScheduling(data: CheckAuthoringData):
+  | Readonly<{
+      readonly dependsOn: ParsedCheckCollection | undefined;
+      readonly maxParallel: number | undefined;
+      readonly mutex: ParsedCheckCollection | undefined;
+    }>
+  | undefined {
+  const dependsOn = parseCollection(data, "dependsOn");
+  const mutex = parseCollection(data, "mutex");
+  const maxParallel = data.maxParallel;
+  if (
+    dependsOn === null ||
+    mutex === null ||
+    (maxParallel !== undefined &&
+      (typeof maxParallel !== "number" || !Number.isSafeInteger(maxParallel) || maxParallel <= 0))
+  )
+    return undefined;
+  return Object.freeze({
+    dependsOn: dependsOn ?? undefined,
+    maxParallel,
+    mutex: mutex ?? undefined
+  });
+}
+
+function parseCollection(
+  data: CheckAuthoringData,
+  field: "dependsOn" | "mutex"
+): ParsedCheckCollection | null | undefined {
+  if (!Object.hasOwn(data, field)) return undefined;
+  const value = data[field];
+  if (isInheritedCheckCollection(value)) return parseInheritedCollection(value);
+  const values = parseCollectionItems(value);
+  return values === undefined ? null : Object.freeze({ kind: "exact", values });
+}
+
+function parseInheritedCollection(
+  value: InheritedCheckCollection<unknown>
+): ParsedCheckCollection | null {
+  const data = snapshotInheritedCheckCollection(value);
+  if (data === undefined || !hasExactInheritedKeys(data)) return null;
+  const add = data.add === undefined ? Object.freeze([]) : parseCollectionItems(data.add);
+  const remove = data.remove === undefined ? Object.freeze([]) : parseCollectionItems(data.remove);
+  if (add === undefined || remove === undefined) return null;
+  return Object.freeze({ kind: "inherit", add, remove });
+}
+
+function hasExactInheritedKeys(data: Readonly<Record<string, unknown>>): boolean {
+  const keys = Object.keys(data);
+  return keys.length > 0 && keys.every((key) => key === "add" || key === "remove");
+}
+
+function parseCollectionItems(value: unknown): readonly string[] | undefined {
+  const items = snapshotClosedArray(value);
+  if (items === undefined) return undefined;
+  const values: string[] = [];
+  for (const item of items) {
+    const valid = typeof item === "string" && item.length > 0;
+    if (!valid) return undefined;
+    if (!values.includes(item)) values.push(item);
+  }
+  return Object.freeze(values);
+}

package/src/project-definition/check-tree/materialization.ts

@@ -0,0 +1,56 @@
+import { inherit, type Check, type InheritableCheckCollection } from "../../check/check.ts";
+import type { ParsedCheck, ParsedCheckCollection, ParsedCheckTree } from "./authoring.ts";
+
+/** Rebuilds the validated public authoring shape without retaining untyped input. */
+export function materializeCheckTreeAuthoring(parsed: ParsedCheckTree): readonly Check[] {
+  return materializeChecks(parsed.checks);
+}
+
+function materializeChecks(checks: readonly ParsedCheck[]): readonly Check[] {
+  return Object.freeze(checks.map((check) => materializeCheck(check)));
+}
+
+function materializeCheck(check: ParsedCheck): Check {
+  const checks = materializeChecks(check.checks);
+  const dependsOn = materializeCollection(check.dependsOn);
+  const mutex = materializeCollection(check.mutex);
+  const visibility = check.visibility;
+  const preflight = check.preflight;
+  const scheduling = {
+    ...(dependsOn === undefined ? {} : { dependsOn }),
+    ...(check.maxParallel === undefined ? {} : { maxParallel: check.maxParallel }),
+    ...(mutex === undefined ? {} : { mutex })
+  };
+  if (
+    check.definition === null ||
+    check.execution === null ||
+    check.options === null ||
+    visibility === null
+  ) {
+    return Object.freeze({
+      checkId: check.checkId,
+      checks,
+      displayName: check.displayName,
+      ...scheduling
+    });
+  }
+  return Object.freeze({
+    checkId: check.checkId,
+    checks,
+    displayName: check.displayName,
+    execution: check.execution,
+    ...(check.parseData === null ? {} : { parseData: check.parseData }),
+    options: check.options,
+    ...(preflight === null ? {} : { preflight }),
+    ...scheduling,
+    visibility
+  });
+}
+
+function materializeCollection(
+  collection: ParsedCheckCollection | undefined
+): InheritableCheckCollection<string> | undefined {
+  if (collection === undefined) return undefined;
+  if (collection.kind === "exact") return collection.values;
+  return inherit({ add: collection.add, remove: collection.remove });
+}