@zxyycom/vibe-check 0.0.1

package/src/package-checks/json-schema-validation/schema-engine.ts

@@ -0,0 +1,263 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import type { ErrorObject, ValidateFunction } from "ajv";
+
+import type { ResolvedJsonSchemaValidationOptions } from "./options.ts";
+import { prepareSchema, rejectDuplicateEngineIds, type PreparedSchema } from "./schema-policy.ts";
+import {
+  ControlledReferenceResolver,
+  ReferenceResolutionFailure,
+  ReferenceTransportFailure
+} from "./reference-resolver.ts";
+import type { StrictJsonValue } from "../json-document/strict-document.ts";
+
+export type SchemaCompileReason =
+  | "duplicate-engine-id"
+  | "invalid-document-id"
+  | "invalid-schema"
+  | "missing-schema-id"
+  | "schema-id-mismatch"
+  | "unapproved-reference"
+  | "unsupported-reference"
+  | "remote-document-invalid"
+  | "remote-schema-id-mismatch";
+
+export interface LoadedSchema {
+  readonly id: string;
+  readonly documentValue: StrictJsonValue;
+}
+
+export interface CompiledSchemaSet {
+  readonly failures: ReadonlyMap<string, SchemaCompileReason>;
+  readonly validators: ReadonlyMap<string, ValidateFunction>;
+}
+
+/** The only validation fields that may cross from the Ajv adapter to Check-owned Record settlement. */
+export interface NormalizedValidationError {
+  readonly keyword: string;
+  readonly pointer: string;
+}
+
+export type CompileSchemaSetResult =
+  | Readonly<{ readonly compiledSchemaSet: CompiledSchemaSet; readonly kind: "settled" }>
+  | Readonly<{
+      readonly kind: "unavailable";
+      readonly reason:
+        | "engine-unavailable"
+        | "execution-cancelled"
+        | "reference-transport-unavailable";
+    }>;
+
+/** Compiles a closed set without exposing Ajv objects, errors, or resolved remote material to callers. */
+export async function compileSchemaSet(input: {
+  readonly referenceResolution: ResolvedJsonSchemaValidationOptions["referenceResolution"];
+  readonly schemaIdentity: ResolvedJsonSchemaValidationOptions["schemaIdentity"];
+  readonly schemas: readonly LoadedSchema[];
+  readonly signal: AbortSignal;
+}): Promise<CompileSchemaSetResult> {
+  if (input.signal.aborted) return unavailable("execution-cancelled");
+  const prepared = prepareSchemas(input);
+  const resolver = new ControlledReferenceResolver({
+    referenceResolution: input.referenceResolution,
+    signal: input.signal
+  });
+  const ajv = createSchemaEngine(resolver);
+  if (ajv === undefined) return unavailable("engine-unavailable");
+  const registered = registerSchemas(ajv, prepared, input.signal);
+  if (registered === undefined) return unavailable("execution-cancelled");
+  const validators = await compileRegisteredSchemas(ajv, prepared, registered, input.signal);
+  if (validators === "cancelled") return unavailable("execution-cancelled");
+  if (validators === "transport-failed") return unavailable("reference-transport-unavailable");
+
+  return Object.freeze({
+    compiledSchemaSet: Object.freeze({
+      failures: new Map(prepared.failures),
+      validators: new Map(validators)
+    }),
+    kind: "settled"
+  });
+}
+
+interface PreparedSchemaSet {
+  readonly failures: Map<string, SchemaCompileReason>;
+  readonly schemas: Map<string, PreparedSchema>;
+}
+
+function prepareSchemas(input: {
+  readonly schemaIdentity: ResolvedJsonSchemaValidationOptions["schemaIdentity"];
+  readonly schemas: readonly LoadedSchema[];
+}): PreparedSchemaSet {
+  const failures = new Map<string, SchemaCompileReason>();
+  const schemas = new Map<string, PreparedSchema>();
+  for (const loadedSchema of input.schemas) {
+    const preparation = prepareSchema(loadedSchema, input.schemaIdentity.mode);
+    if (typeof preparation === "string") failures.set(loadedSchema.id, preparation);
+    else schemas.set(loadedSchema.id, preparation);
+  }
+  rejectDuplicateEngineIds(schemas, failures);
+  return { failures, schemas };
+}
+
+function createSchemaEngine(resolver: ControlledReferenceResolver): Ajv2020 | undefined {
+  try {
+    return new Ajv2020({
+      allErrors: true,
+      coerceTypes: false,
+      loadSchema: (uri) => resolver.load(uri),
+      logger: false,
+      messages: false,
+      removeAdditional: false,
+      strict: false,
+      strictNumbers: true,
+      strictRequired: false,
+      strictSchema: true,
+      strictTuples: false,
+      strictTypes: false,
+      useDefaults: false,
+      validateFormats: false
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+function registerSchemas(
+  ajv: Ajv2020,
+  prepared: PreparedSchemaSet,
+  signal: AbortSignal
+): ReadonlySet<string> | undefined {
+  const registered = new Set<string>();
+  for (const schema of prepared.schemas.values()) {
+    if (signal.aborted) return undefined;
+    try {
+      ajv.addSchema(schema.engineSchema, schema.engineId);
+      registered.add(schema.authoringId);
+    } catch {
+      prepared.failures.set(schema.authoringId, "invalid-schema");
+    }
+  }
+  return registered;
+}
+
+async function compileRegisteredSchemas(
+  ajv: Ajv2020,
+  prepared: PreparedSchemaSet,
+  registered: ReadonlySet<string>,
+  signal: AbortSignal
+): Promise<ReadonlyMap<string, ValidateFunction> | "cancelled" | "transport-failed"> {
+  const validators = new Map<string, ValidateFunction>();
+  for (const schema of prepared.schemas.values()) {
+    const outcome = await compilePreparedSchema(ajv, schema, registered, signal);
+    if (outcome === "cancelled" || outcome === "transport-failed") return outcome;
+    if (outcome instanceof ReferenceResolutionFailure)
+      prepared.failures.set(schema.authoringId, outcome.reason);
+    else if (outcome === "invalid") prepared.failures.set(schema.authoringId, "invalid-schema");
+    else if (outcome !== undefined) validators.set(schema.authoringId, outcome);
+  }
+  return validators;
+}
+
+async function compilePreparedSchema(
+  ajv: Ajv2020,
+  schema: PreparedSchema,
+  registered: ReadonlySet<string>,
+  signal: AbortSignal
+): Promise<
+  | ValidateFunction
+  | ReferenceResolutionFailure
+  | "cancelled"
+  | "invalid"
+  | "transport-failed"
+  | undefined
+> {
+  if (!registered.has(schema.authoringId)) return undefined;
+  if (signal.aborted) return "cancelled";
+  try {
+    return typeof schema.engineSchema === "boolean"
+      ? ajv.compile(schema.engineSchema)
+      : await ajv.compileAsync(schema.engineSchema);
+  } catch (error) {
+    if (signal.aborted) return "cancelled";
+    if (error instanceof ReferenceTransportFailure) return "transport-failed";
+    return error instanceof ReferenceResolutionFailure ? error : "invalid";
+  }
+}
+
+/** Converts the only engine-visible error fields into fixed safe validation facts. */
+export function normalizeValidationErrors(
+  errors: readonly ErrorObject[] | null | undefined
+): readonly NormalizedValidationError[] {
+  if (errors === null || errors === undefined) return Object.freeze([]);
+  const normalized = errors.map((error) =>
+    Object.freeze({
+      keyword: normalizeKeyword(error.keyword),
+      pointer: normalizePointer(error.instancePath)
+    })
+  );
+  normalized.sort((left, right) => {
+    const leftKey = `${left.pointer}\n${left.keyword}`;
+    const rightKey = `${right.pointer}\n${right.keyword}`;
+    if (leftKey < rightKey) return -1;
+    if (leftKey > rightKey) return 1;
+    return 0;
+  });
+  return Object.freeze(normalized);
+}
+
+function normalizeKeyword(candidateKeyword: unknown): string {
+  return typeof candidateKeyword === "string" && KNOWN_KEYWORDS.has(candidateKeyword)
+    ? candidateKeyword
+    : "other";
+}
+
+function normalizePointer(candidatePointer: unknown): string {
+  if (typeof candidatePointer !== "string") return "/<redacted>";
+  if (candidatePointer === "") return "";
+  if (candidatePointer.length > 256 || !candidatePointer.startsWith("/")) {
+    return "/<redacted>";
+  }
+  const segments = candidatePointer.slice(1).split("/");
+  return segments.every((segment) => /^[A-Za-z0-9_.-]{1,64}$/u.test(segment))
+    ? candidatePointer
+    : "/<redacted>";
+}
+
+const KNOWN_KEYWORDS: ReadonlySet<string> = new Set([
+  "additionalProperties",
+  "allOf",
+  "anyOf",
+  "const",
+  "contains",
+  "dependentRequired",
+  "enum",
+  "exclusiveMaximum",
+  "exclusiveMinimum",
+  "format",
+  "if",
+  "maxContains",
+  "maxItems",
+  "maxLength",
+  "maxProperties",
+  "maximum",
+  "minContains",
+  "minItems",
+  "minLength",
+  "minProperties",
+  "minimum",
+  "multipleOf",
+  "not",
+  "oneOf",
+  "pattern",
+  "patternProperties",
+  "propertyNames",
+  "required",
+  "type",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+  "uniqueItems"
+]);
+
+function unavailable(
+  reason: Extract<CompileSchemaSetResult, { readonly kind: "unavailable" }>["reason"]
+): CompileSchemaSetResult {
+  return Object.freeze({ kind: "unavailable", reason });
+}

package/src/package-checks/json-schema-validation/schema-policy.ts

@@ -0,0 +1,275 @@
+import type { AnySchema } from "ajv";
+
+import type { ResolvedJsonSchemaValidationOptions } from "./options.ts";
+import type { LoadedSchema, SchemaCompileReason } from "./schema-engine.ts";
+import type { StrictJsonValue } from "../json-document/strict-document.ts";
+
+export interface PreparedSchema {
+  readonly authoringId: string;
+  readonly engineId: string;
+  readonly engineSchema: AnySchema;
+}
+
+export function prepareSchema(
+  loadedSchema: LoadedSchema,
+  mode: ResolvedJsonSchemaValidationOptions["schemaIdentity"]["mode"]
+): PreparedSchema | SchemaCompileReason {
+  if (mode === "configuration-authoritative") {
+    const documentValue = withConfigurationIdentity(loadedSchema.documentValue, loadedSchema.id);
+    const engineSchema = toAjvSchema(documentValue);
+    if (engineSchema === undefined) return "invalid-schema";
+    const referenceReason = inspectSchemaPolicy(documentValue);
+    if (referenceReason !== undefined) return referenceReason;
+    return Object.freeze({
+      authoringId: loadedSchema.id,
+      engineId: loadedSchema.id,
+      engineSchema
+    });
+  }
+
+  if (!isJsonObject(loadedSchema.documentValue)) return "missing-schema-id";
+  const documentId = loadedSchema.documentValue.$id;
+  if (typeof documentId !== "string") return "missing-schema-id";
+  if (!safeSchemaIdentifier(documentId)) return "invalid-document-id";
+  if (mode === "require-match" && documentId !== loadedSchema.id) return "schema-id-mismatch";
+  const referenceReason = inspectSchemaPolicy(loadedSchema.documentValue);
+  if (referenceReason !== undefined) return referenceReason;
+  return Object.freeze({
+    authoringId: loadedSchema.id,
+    engineId: documentId,
+    engineSchema: loadedSchema.documentValue
+  });
+}
+
+export function rejectDuplicateEngineIds(
+  preparedSchemas: Map<string, PreparedSchema>,
+  failures: Map<string, SchemaCompileReason>
+): void {
+  const byEngineId = new Map<string, string[]>();
+  for (const preparedSchema of preparedSchemas.values()) {
+    const authoringIds = byEngineId.get(preparedSchema.engineId) ?? [];
+    authoringIds.push(preparedSchema.authoringId);
+    byEngineId.set(preparedSchema.engineId, authoringIds);
+  }
+  for (const authoringIds of byEngineId.values()) {
+    if (authoringIds.length < 2) continue;
+    for (const authoringId of authoringIds) {
+      preparedSchemas.delete(authoringId);
+      failures.set(authoringId, "duplicate-engine-id");
+    }
+  }
+}
+
+function withConfigurationIdentity(
+  documentValue: StrictJsonValue,
+  configuredSchemaId: string
+): StrictJsonValue {
+  if (!isJsonObject(documentValue)) return documentValue;
+  const copy: Record<string, StrictJsonValue> = {};
+  Object.setPrototypeOf(copy, null);
+  for (const [key, nested] of Object.entries(documentValue)) {
+    Object.defineProperty(copy, key, {
+      configurable: false,
+      enumerable: true,
+      value: key === "$id" ? configuredSchemaId : nested,
+      writable: false
+    });
+  }
+  if (!Object.hasOwn(copy, "$id")) {
+    Object.defineProperty(copy, "$id", {
+      configurable: false,
+      enumerable: true,
+      value: configuredSchemaId,
+      writable: false
+    });
+  }
+  return Object.freeze(copy);
+}
+
+/**
+ * Inspects only JSON Schema-bearing locations. Annotation payloads and property names are data, not keywords,
+ * so they must not be mistaken for `$ref`, `$dynamicRef`, or an Ajv extension.
+ */
+export function inspectSchemaPolicy(schemaValue: StrictJsonValue): SchemaCompileReason | undefined {
+  if (!isJsonObject(schemaValue)) return undefined;
+  return inspectSchemaObject(schemaValue);
+}
+
+function inspectSchemaObject(
+  schemaObject: Readonly<Record<string, StrictJsonValue>>
+): SchemaCompileReason | undefined {
+  const directReason = inspectDirectSchemaPolicy(schemaObject);
+  if (directReason !== undefined) return directReason;
+  return inspectNestedSchemaPolicies(schemaObject);
+}
+
+function inspectDirectSchemaPolicy(
+  schemaObject: Readonly<Record<string, StrictJsonValue>>
+): SchemaCompileReason | undefined {
+  if (Object.hasOwn(schemaObject, "$async")) return "invalid-schema";
+  if (hasUnsupportedReferenceKeyword(schemaObject)) return "unsupported-reference";
+  if (Object.hasOwn(schemaObject, "$id") && !permittedNestedIdentifier(schemaObject.$id)) {
+    return "unsupported-reference";
+  }
+  return hasInvalidReferenceValue(schemaObject) ? "unsupported-reference" : undefined;
+}
+
+function hasUnsupportedReferenceKeyword(
+  schemaObject: Readonly<Record<string, StrictJsonValue>>
+): boolean {
+  return Object.hasOwn(schemaObject, "$dynamicRef") || Object.hasOwn(schemaObject, "$recursiveRef");
+}
+
+function hasInvalidReferenceValue(
+  schemaObject: Readonly<Record<string, StrictJsonValue>>
+): boolean {
+  return ["$ref", "$schema"].some(
+    (key) => Object.hasOwn(schemaObject, key) && !permittedReference(schemaObject[key])
+  );
+}
+
+function inspectNestedSchemaPolicies(
+  schemaObject: Readonly<Record<string, StrictJsonValue>>
+): SchemaCompileReason | undefined {
+  for (const [keyword, keywordValue] of Object.entries(schemaObject)) {
+    const reason = inspectNestedSchemaPolicy(keyword, keywordValue);
+    if (reason !== undefined) return reason;
+  }
+  return undefined;
+}
+
+function inspectNestedSchemaPolicy(
+  keyword: string,
+  keywordValue: StrictJsonValue
+): SchemaCompileReason | undefined {
+  if (SCHEMA_MAP_KEYWORDS.has(keyword)) return inspectSchemaMap(keywordValue);
+  if (SCHEMA_VALUE_KEYWORDS.has(keyword)) return inspectSchemaValue(keywordValue);
+  if (SCHEMA_ARRAY_KEYWORDS.has(keyword)) return inspectSchemaArray(keywordValue);
+  if (keyword === "dependencies") return inspectLegacyDependencies(keywordValue);
+  return undefined;
+}
+
+function inspectSchemaMap(schemaMap: StrictJsonValue): SchemaCompileReason | undefined {
+  if (!isJsonObject(schemaMap)) return undefined;
+  for (const nestedSchema of Object.values(schemaMap)) {
+    const reason = inspectSchemaValue(nestedSchema);
+    if (reason !== undefined) return reason;
+  }
+  return undefined;
+}
+
+function inspectSchemaValue(candidateSchema: StrictJsonValue): SchemaCompileReason | undefined {
+  if (!isJsonObject(candidateSchema)) return undefined;
+  return inspectSchemaObject(candidateSchema);
+}
+
+function inspectSchemaArray(schemaArray: StrictJsonValue): SchemaCompileReason | undefined {
+  if (!isStrictJsonArray(schemaArray)) return undefined;
+  for (const nestedSchema of schemaArray) {
+    const reason = inspectSchemaValue(nestedSchema);
+    if (reason !== undefined) return reason;
+  }
+  return undefined;
+}
+
+function inspectLegacyDependencies(
+  dependencyMap: StrictJsonValue
+): SchemaCompileReason | undefined {
+  if (!isJsonObject(dependencyMap)) return undefined;
+  for (const dependencySchema of Object.values(dependencyMap)) {
+    const reason = inspectSchemaValue(dependencySchema);
+    if (reason !== undefined) return reason;
+  }
+  return undefined;
+}
+
+const SCHEMA_MAP_KEYWORDS: ReadonlySet<string> = new Set([
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  "patternProperties",
+  "properties"
+]);
+
+const SCHEMA_VALUE_KEYWORDS: ReadonlySet<string> = new Set([
+  "additionalItems",
+  "additionalProperties",
+  "contains",
+  "contentSchema",
+  "else",
+  "if",
+  "items",
+  "not",
+  "propertyNames",
+  "then",
+  "unevaluatedItems",
+  "unevaluatedProperties"
+]);
+
+const SCHEMA_ARRAY_KEYWORDS: ReadonlySet<string> = new Set([
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "prefixItems"
+]);
+
+function permittedReference(referenceValue: StrictJsonValue): boolean {
+  if (typeof referenceValue !== "string") return false;
+  if (referenceValue.startsWith("#")) return true;
+  try {
+    const url = new URL(referenceValue);
+    return (
+      (url.protocol === "https:" || url.protocol === "urn:") &&
+      url.username.length === 0 &&
+      url.password.length === 0 &&
+      url.search.length === 0
+    );
+  } catch {
+    return false;
+  }
+}
+
+function permittedNestedIdentifier(identifierValue: StrictJsonValue): boolean {
+  return (
+    typeof identifierValue === "string" &&
+    (identifierValue.startsWith("#") || safeSchemaIdentifier(identifierValue))
+  );
+}
+
+function safeSchemaIdentifier(identifier: string): boolean {
+  try {
+    const url = new URL(identifier);
+    return (
+      (url.protocol === "https:" || url.protocol === "urn:") &&
+      url.username.length === 0 &&
+      url.password.length === 0 &&
+      url.search.length === 0 &&
+      url.hash.length === 0 &&
+      url.href === identifier
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function isJsonObject(
+  candidateValue: StrictJsonValue
+): candidateValue is Readonly<Record<string, StrictJsonValue>> {
+  return (
+    typeof candidateValue === "object" &&
+    candidateValue !== null &&
+    !isStrictJsonArray(candidateValue)
+  );
+}
+
+function isStrictJsonArray(
+  candidateValue: StrictJsonValue
+): candidateValue is readonly StrictJsonValue[] {
+  return Array.isArray(candidateValue);
+}
+
+function toAjvSchema(documentValue: StrictJsonValue): AnySchema | undefined {
+  if (typeof documentValue === "boolean") return documentValue;
+  if (!isJsonObject(documentValue)) return undefined;
+  return documentValue;
+}

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

@@ -0,0 +1,48 @@
+import { defineCheck, type TypedCheckWithOptions } from "../../check/check.ts";
+import { JSON_VALIDATION_CHECK_DEFINITION, executeJsonValidation } from "./json-validation.ts";
+import { parseJsonValidationData } from "./final-data.ts";
+import type { JsonValidationOptions, ResolvedJsonValidationOptions } from "./options.ts";
+import { resolveJsonValidationOptions } from "./options-resolution.ts";
+import { validJsonValidationOptions } from "./options-validation.ts";
+
+/**
+ * 使用可省略的文件范围与 byte limit 构造严格 JSON document Check。
+ *
+ * @param options - 省略字段由 package 补齐；显式 files 数组作为对应字段的完整替换值。
+ * @returns 固定 `json-validation` identity、完整冻结 options、final-data parser 与执行逻辑。
+ * @throws {TypeError} input 含未知字段、非法文件选择或非法 byte limit 时抛出。
+ */
+export function jsonValidation(
+  options: JsonValidationOptions = {}
+): TypedCheckWithOptions<
+  "json-validation",
+  ResolvedJsonValidationOptions,
+  typeof parseJsonValidationData
+> {
+  const resolvedOptions = resolveJsonValidationOptions(options);
+  if (resolvedOptions === undefined) {
+    throw new TypeError("jsonValidation options must match the documented closed policy");
+  }
+  return defineCheck({
+    ...JSON_VALIDATION_CHECK_DEFINITION,
+    execution: executeJsonValidation,
+    parseData: parseJsonValidationData,
+    preflight: (preparedOptions) =>
+      validJsonValidationOptions(preparedOptions)
+        ? { status: "success", preparedOptions }
+        : {
+            status: "failure",
+            action: "block",
+            reason: { code: "invalid-options" },
+            messages: [
+              {
+                code: "invalid-options",
+                level: "error",
+                message:
+                  "jsonValidation options are invalid; recreate the Check with jsonValidation(options) or restore its complete resolved options."
+              }
+            ]
+          },
+    options: resolvedOptions
+  });
+}

package/src/package-checks/json-validation/final-data.ts

@@ -0,0 +1,46 @@
+import {
+  exactFinalDataRecord,
+  invalidFinalData,
+  nonNegativeSafeInteger
+} from "../final-data-parsing.ts";
+
+/** `json-validation` 在 passed/failed outcome 中发布的主数据。 */
+export interface JsonValidationFinalData {
+  readonly scannedFileCount: number;
+  readonly validFileCount: number;
+  readonly invalidFileCount: number;
+  readonly issueCount: number;
+  readonly rejectedInputCount: number;
+}
+
+/** 验证计数不变量并脱离一份 `json-validation` canonical final-data object。 */
+export function parseJsonValidationData(data: unknown): JsonValidationFinalData {
+  const value = exactFinalDataRecord(
+    data,
+    ["scannedFileCount", "validFileCount", "invalidFileCount", "issueCount", "rejectedInputCount"],
+    "jsonValidation"
+  );
+  const scannedFileCount = nonNegativeSafeInteger(value.scannedFileCount);
+  const validFileCount = nonNegativeSafeInteger(value.validFileCount);
+  const invalidFileCount = nonNegativeSafeInteger(value.invalidFileCount);
+  const issueCount = nonNegativeSafeInteger(value.issueCount);
+  const rejectedInputCount = nonNegativeSafeInteger(value.rejectedInputCount);
+  if (
+    scannedFileCount === undefined ||
+    validFileCount === undefined ||
+    invalidFileCount === undefined ||
+    issueCount === undefined ||
+    rejectedInputCount === undefined ||
+    scannedFileCount !== validFileCount + invalidFileCount ||
+    issueCount !== invalidFileCount + rejectedInputCount
+  ) {
+    throw invalidFinalData("jsonValidation");
+  }
+  return Object.freeze({
+    scannedFileCount,
+    validFileCount,
+    invalidFileCount,
+    issueCount,
+    rejectedInputCount
+  });
+}