@zxyycom/vibe-check 0.0.1

package/src/package-checks/host-environment/process/contract.ts

@@ -0,0 +1,56 @@
+import type { SyncOptions } from "execa";
+
+export const DEFAULT_PROCESS_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+
+export interface ProcessFailure extends Error {
+  code?: number | string | null;
+  signal?: NodeJS.Signals | null;
+  status?: number | null;
+  stderr?: Buffer | string;
+  stdout?: Buffer | string;
+}
+
+export type ProcessResult = {
+  readonly error?: Error;
+  readonly signal: NodeJS.Signals | null;
+  readonly status: number | null;
+  readonly stderr: string;
+  readonly stdout: string;
+};
+
+export type RunProcessSyncOptions = {
+  readonly args: readonly string[];
+  readonly command: string;
+  readonly cwd?: string | URL;
+  readonly encoding?: SyncOptions["encoding"];
+  readonly env?: NodeJS.ProcessEnv;
+  readonly maxBuffer?: number;
+  readonly stdio?: SyncOptions["stdio"];
+  readonly timeout?: number;
+  readonly windowsHide?: boolean;
+};
+
+export type RunProcessOptions = {
+  readonly args?: readonly string[];
+  readonly command: string;
+  readonly cwd?: string | URL;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly label?: string;
+  readonly maxBuffer?: number;
+  readonly timeout?: number;
+  readonly windowsHide?: boolean;
+};
+
+export type ExecaResultLike = {
+  readonly code?: string;
+  readonly exitCode?: number;
+  readonly failed?: boolean;
+  readonly isMaxBuffer?: boolean;
+  readonly message?: string;
+  readonly originalMessage?: string;
+  readonly shortMessage?: string;
+  readonly signal?: NodeJS.Signals;
+  readonly stderr?: unknown;
+  readonly stdout?: unknown;
+  readonly timedOut?: boolean;
+};

package/src/package-checks/host-environment/process/env.ts

@@ -0,0 +1,25 @@
+export const PLAIN_TEXT_PROCESS_ENV = Object.freeze({
+  CARGO_TERM_COLOR: "never",
+  CLICOLOR: "0",
+  CLICOLOR_FORCE: "0",
+  FORCE_COLOR: "0",
+  NO_COLOR: "1",
+  PNPM_CONFIG_COLOR: "false",
+  PY_COLORS: "0",
+  TERM: "dumb",
+  UV_NO_COLOR: "1",
+  npm_config_color: "false"
+} satisfies NodeJS.ProcessEnv);
+
+export type PlainTextProcessEnvInput = {
+  readonly env?: NodeJS.ProcessEnv;
+};
+
+export function plainTextProcessEnv({
+  env = process.env
+}: PlainTextProcessEnvInput = {}): NodeJS.ProcessEnv {
+  return {
+    ...env,
+    ...PLAIN_TEXT_PROCESS_ENV
+  };
+}

package/src/package-checks/host-environment/process/failure.ts

@@ -0,0 +1,40 @@
+import type { ProcessFailure, ProcessResult } from "./contract.ts";
+
+export function processFailure(error: unknown): ProcessFailure {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+export function processFailureFromResult(result: ProcessResult): ProcessFailure | null {
+  if (result.error) {
+    return attachProcessResult(processFailure(result.error), result);
+  }
+  if (result.status === 0) {
+    return null;
+  }
+  return attachProcessResult(createExitFailure(result), result);
+}
+
+export function processFailed(result: Pick<ProcessResult, "error" | "status">): boolean {
+  return result.error !== undefined || result.status !== 0;
+}
+
+function attachProcessResult(failure: ProcessFailure, result: ProcessResult): ProcessFailure {
+  failure.stdout = result.stdout;
+  failure.stderr = result.stderr;
+  failure.signal = result.signal;
+  failure.status = result.status;
+  return failure;
+}
+
+function createExitFailure(result: ProcessResult): ProcessFailure {
+  const failure: ProcessFailure = new Error(exitFailureMessage(result));
+  failure.code = result.status ?? 1;
+  return failure;
+}
+
+function exitFailureMessage(result: ProcessResult): string {
+  if (result.status === null) {
+    return `process terminated by signal ${result.signal ?? "unknown"}`;
+  }
+  return `process exited with status ${result.status}`;
+}

package/src/package-checks/host-environment/process/result.ts

@@ -0,0 +1,39 @@
+import type { ExecaResultLike, ProcessResult } from "./contract.ts";
+
+export function toProcessResult(result: ExecaResultLike, label: string): ProcessResult {
+  return {
+    error: processErrorFor(result, label),
+    signal: result.signal ?? null,
+    status: result.exitCode ?? null,
+    stderr: outputString(result.stderr),
+    stdout: outputString(result.stdout)
+  };
+}
+
+function outputString(output: unknown): string {
+  return typeof output === "string" ? output : "";
+}
+
+function processErrorFor(result: ExecaResultLike, label = "process"): Error | undefined {
+  if (!isExecutionError(result)) {
+    return undefined;
+  }
+
+  const message =
+    result.originalMessage ?? result.shortMessage ?? result.message ?? `${label} failed`;
+  const error: NodeJS.ErrnoException = new Error(message);
+  if (result.code) {
+    error.code = result.code;
+  }
+  return error;
+}
+
+function isExecutionError(result: ExecaResultLike): boolean {
+  if (!result.failed) {
+    return false;
+  }
+  if (typeof result.exitCode === "number") {
+    return false;
+  }
+  return Boolean(result.code || result.timedOut || result.isMaxBuffer || result.signal);
+}

package/src/package-checks/host-environment/process/runner.ts

@@ -0,0 +1,47 @@
+import { execa, execaSync } from "execa";
+
+import { plainTextProcessEnv } from "./env.ts";
+import { toProcessResult } from "./result.ts";
+import {
+  DEFAULT_PROCESS_MAX_BUFFER_BYTES,
+  type ProcessResult,
+  type RunProcessOptions,
+  type RunProcessSyncOptions
+} from "./contract.ts";
+
+export function runProcessSync(options: RunProcessSyncOptions): ProcessResult {
+  const { args, command, ...processOptions } = options;
+  const result = execaSync(command, args, {
+    ...processOptions,
+    encoding: processOptions.encoding ?? "utf8",
+    env: plainTextProcessEnv({ env: processOptions.env }),
+    maxBuffer: processOptions.maxBuffer ?? DEFAULT_PROCESS_MAX_BUFFER_BYTES,
+    reject: false,
+    stripFinalNewline: false,
+    windowsHide: processOptions.windowsHide ?? true
+  });
+  return toProcessResult(result, command);
+}
+
+export function runProcess(options: RunProcessOptions): Promise<ProcessResult> {
+  const {
+    args = [],
+    command,
+    cwd,
+    env,
+    label = command,
+    maxBuffer = DEFAULT_PROCESS_MAX_BUFFER_BYTES,
+    timeout,
+    windowsHide = true
+  } = options;
+
+  return execa(command, args, {
+    cwd,
+    env: plainTextProcessEnv({ env }),
+    maxBuffer,
+    reject: false,
+    stripFinalNewline: false,
+    timeout,
+    windowsHide
+  }).then((result) => toProcessResult(result, label));
+}

package/src/package-checks/json-document/strict-document.ts

@@ -0,0 +1,209 @@
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+
+import { parse, type ValueNode } from "@humanwhocodes/momoa";
+
+export type JsonDocumentIssue =
+  | "too-large"
+  | "bom"
+  | "invalid-utf8"
+  | "invalid-json"
+  | "duplicate-key";
+
+/**
+ * A strict JSON value retained only inside Product source boundaries.
+ * Objects have a null prototype and every aggregate is frozen, so document keys cannot affect ambient prototypes.
+ */
+export type StrictJsonArray = readonly StrictJsonValue[];
+
+export interface StrictJsonObject {
+  readonly [key: string]: StrictJsonValue;
+}
+
+export type StrictJsonValue = null | boolean | number | string | StrictJsonArray | StrictJsonObject;
+
+export type StrictJsonDocumentResult =
+  | Readonly<{ readonly kind: "valid"; readonly jsonValue: StrictJsonValue }>
+  | Readonly<{ readonly kind: "issue"; readonly reason: JsonDocumentIssue }>
+  | Readonly<{ readonly kind: "unavailable" }>;
+
+interface StrictJsonDocumentReadInput {
+  readonly filePath: string;
+  /** Normally validated at the Check options boundary; malformed private input becomes unavailable. */
+  readonly maximumBytes: number;
+}
+
+const UTF8_BOM = [0xef, 0xbb, 0xbf] as const;
+const UNAVAILABLE_DOCUMENT = Object.freeze({ kind: "unavailable" } as const);
+
+function isPositiveSafeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+/**
+ * Reads one approved file with a byte limit, then applies the strict JSON document contract.
+ * The caller owns exact-input authorization and maps `unavailable` to its Check outcome.
+ */
+export function readStrictJsonDocument(
+  input: StrictJsonDocumentReadInput
+): StrictJsonDocumentResult {
+  if (!isPositiveSafeInteger(input.maximumBytes)) return UNAVAILABLE_DOCUMENT;
+
+  const bytes = readBoundedFile(input.filePath, input.maximumBytes);
+  if (bytes === undefined) return UNAVAILABLE_DOCUMENT;
+  if (bytes === "too-large") return issue("too-large");
+  return inspectStrictJsonBytes(bytes);
+}
+
+function readBoundedFile(
+  filePath: string,
+  maximumBytes: number
+): Uint8Array | "too-large" | undefined {
+  let descriptor: number | undefined;
+  try {
+    descriptor = openSync(filePath, "r");
+    const before = fstatSync(descriptor);
+    if (!before.isFile() || !Number.isSafeInteger(before.size)) return undefined;
+    if (before.size > maximumBytes) return "too-large";
+
+    const bytes = new Uint8Array(before.size);
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+      const bytesRead = readSync(descriptor, bytes, offset, bytes.byteLength - offset, null);
+      if (bytesRead === 0) return undefined;
+      offset += bytesRead;
+    }
+
+    const after = fstatSync(descriptor);
+    return after.size === before.size ? bytes : undefined;
+  } catch {
+    return undefined;
+  } finally {
+    if (descriptor !== undefined) {
+      try {
+        closeSync(descriptor);
+      } catch {
+        // The read result is already fully normalized; closing cannot expose a native failure.
+      }
+    }
+  }
+}
+
+/**
+ * Applies strict JSON grammar and duplicate-key semantics to already bounded bytes.
+ * This is package-private so controlled remote schema bytes use the same boundary as local files.
+ */
+export function inspectStrictJsonBytes(bytes: Uint8Array): StrictJsonDocumentResult {
+  if (hasUtf8Bom(bytes)) return issue("bom");
+
+  let source: string;
+  try {
+    source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return issue("invalid-utf8");
+  }
+
+  let document: ReturnType<typeof parse>;
+  try {
+    document = parse(source, { allowTrailingCommas: false, mode: "json" });
+  } catch (error) {
+    return isMomoaSyntaxError(error) ? issue("invalid-json") : UNAVAILABLE_DOCUMENT;
+  }
+
+  try {
+    if (hasDuplicateKey(document.body)) return issue("duplicate-key");
+    return valid(toStrictJsonValue(document.body));
+  } catch {
+    return UNAVAILABLE_DOCUMENT;
+  }
+}
+
+function isMomoaSyntaxError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    hasNumericOwnProperty(error, "line") &&
+    hasNumericOwnProperty(error, "column") &&
+    hasNumericOwnProperty(error, "offset")
+  );
+}
+
+function hasNumericOwnProperty(error: object, propertyName: string): boolean {
+  return typeof Object.getOwnPropertyDescriptor(error, propertyName)?.value === "number";
+}
+
+function hasUtf8Bom(bytes: Uint8Array): boolean {
+  return UTF8_BOM.every((byte, index) => bytes[index] === byte);
+}
+
+function hasDuplicateKey(node: ValueNode): boolean {
+  if (node.type === "Array") {
+    return node.elements.some((element) => hasDuplicateKey(element.value));
+  }
+  if (node.type !== "Object") return false;
+
+  const names = new Set<string>();
+  for (const member of node.members) {
+    if (member.name.type !== "String")
+      throw new TypeError("strict JSON object member must be a string");
+    if (names.has(member.name.value)) return true;
+    names.add(member.name.value);
+    if (hasDuplicateKey(member.value)) return true;
+  }
+  return false;
+}
+
+function toStrictJsonValue(node: ValueNode): StrictJsonValue {
+  switch (node.type) {
+    case "Null":
+      return null;
+    case "Boolean":
+    case "Number":
+    case "String":
+      return node.value;
+    case "Array":
+      return strictJsonArray(node);
+    case "Object":
+      return strictJsonObject(node);
+    case "Infinity":
+    case "NaN":
+      throw new TypeError("strict JSON value node must not be a non-finite number");
+    default:
+      throw new TypeError("strict JSON value node must be a standard JSON node");
+  }
+}
+
+function strictJsonArray(node: Extract<ValueNode, { type: "Array" }>): StrictJsonArray {
+  return Object.freeze(node.elements.map((element) => toStrictJsonValue(element.value)));
+}
+
+function strictJsonObject(node: Extract<ValueNode, { type: "Object" }>): StrictJsonObject {
+  const strictObject: Record<string, StrictJsonValue> = {};
+  Object.setPrototypeOf(strictObject, null);
+  for (const member of node.members) {
+    defineStrictJsonProperty(strictObject, member.name, member.value);
+  }
+  return Object.freeze(strictObject);
+}
+
+function defineStrictJsonProperty(
+  target: Record<string, StrictJsonValue>,
+  name: { readonly type: string; readonly value?: string },
+  value: ValueNode
+): void {
+  if (name.type !== "String" || name.value === undefined) {
+    throw new TypeError("strict JSON object member must be a string");
+  }
+  Object.defineProperty(target, name.value, {
+    configurable: false,
+    enumerable: true,
+    value: toStrictJsonValue(value),
+    writable: false
+  });
+}
+
+function issue(reason: JsonDocumentIssue): StrictJsonDocumentResult {
+  return Object.freeze({ kind: "issue", reason });
+}
+
+function valid(jsonValue: StrictJsonValue): StrictJsonDocumentResult {
+  return Object.freeze({ kind: "valid", jsonValue });
+}

package/src/package-checks/json-schema-validation/default-check.ts

@@ -0,0 +1,54 @@
+import { defineCheck, type TypedCheckWithOptions } from "../../check/check.ts";
+import {
+  JSON_SCHEMA_VALIDATION_CHECK_DEFINITION,
+  executeJsonSchemaValidation
+} from "./json-schema-validation.ts";
+import { parseJsonSchemaValidationData } from "./final-data.ts";
+import type {
+  JsonSchemaValidationOptions,
+  ResolvedJsonSchemaValidationOptions
+} from "./options.ts";
+import { resolveJsonSchemaValidationOptions } from "./options-resolution.ts";
+import { validJsonSchemaValidationOptions } from "./options-validation.ts";
+
+/**
+ * 使用可省略的 file、identity、reference、schema 与 binding policy 构造 Check。
+ *
+ * @param options - 省略顶层字段和 file fields 使用 package defaults；显式数组是完整替换值。
+ * @returns 固定 `json-schema-validation` identity、完整冻结 options、parser 与执行逻辑。
+ * @throws {TypeError} input 不符合 closed authoring policy、identity 或 binding 不变量时抛出。
+ */
+export function jsonSchemaValidation(
+  options: JsonSchemaValidationOptions = {}
+): TypedCheckWithOptions<
+  "json-schema-validation",
+  ResolvedJsonSchemaValidationOptions,
+  typeof parseJsonSchemaValidationData
+> {
+  const resolvedOptions = resolveJsonSchemaValidationOptions(options);
+  if (resolvedOptions === undefined) {
+    throw new TypeError("jsonSchemaValidation options must match the documented closed policy");
+  }
+  return defineCheck({
+    ...JSON_SCHEMA_VALIDATION_CHECK_DEFINITION,
+    execution: executeJsonSchemaValidation,
+    parseData: parseJsonSchemaValidationData,
+    preflight: (preparedOptions) =>
+      validJsonSchemaValidationOptions(preparedOptions)
+        ? { status: "success", preparedOptions }
+        : {
+            status: "failure",
+            action: "block",
+            reason: { code: "invalid-options" },
+            messages: [
+              {
+                code: "invalid-options",
+                level: "error",
+                message:
+                  "jsonSchemaValidation options are invalid; recreate the Check with jsonSchemaValidation(options) or restore its complete resolved options."
+              }
+            ]
+          },
+    options: resolvedOptions
+  });
+}