@figulus/validator-core 0.5.0-alpha-dev-01

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@figulus/validator-core",
+  "version": "0.5.0-alpha-dev-01",
+  "description": "Zod schemas for the Figulus engine API",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@figulus/schema": "^0.5.0-alpha-dev-8",
+    "strip-json-comments": "^5.0.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "prettier": "^3.8.2",
+    "typescript": "^5.7.2"
+  }
+}

package/src/changed-file.ts

@@ -0,0 +1,191 @@
+import z from "zod";
+import { parseJSON } from "./lib/parse.js";
+import { validateBlob } from "./lib/validate-file/blob.js";
+import { validateEntity } from "./lib/validate-file/entity.js";
+import { validateNamespaceMetadata } from "./lib/validate-file/namespace-metadata.js";
+import { validateNamespaceOverrides } from "./lib/validate-file/namespace-overrides.js";
+import { PR } from "./pr.js";
+import {
+  figParserMetadataSchema,
+  figSpecMetadataSchema,
+  figStackMetadataSchema,
+  namespaceVerificationsSchema,
+  pushLimitOverridesSchema,
+} from "@figulus/schema/registry";
+import { FileValidationResult, SchemaObject } from "./types.js";
+import {
+  ERROR_CODES,
+  ValidationResult,
+  createError,
+} from "./validation-result.js";
+
+//
+// Entity metadata files
+//
+
+const fileTypeEntitySchema = z.enum(["spec", "stack", "parser"]);
+export type FileTypeEntity = z.infer<typeof fileTypeEntitySchema>;
+
+const entityFileMap: {
+  [Id in FileTypeEntity]: {
+    id: Id;
+    metadataSchema: SchemaObject;
+    extension: string;
+  };
+} = {
+  spec: {
+    id: "spec",
+    metadataSchema: figSpecMetadataSchema,
+    extension: "figspec",
+  },
+  stack: {
+    id: "stack",
+    metadataSchema: figStackMetadataSchema,
+    extension: "figstack",
+  },
+  parser: {
+    id: "parser",
+    metadataSchema: figParserMetadataSchema,
+    extension: "js",
+  },
+};
+
+export function getExtensionFromFileTypeEntity(
+  entityType: FileTypeEntity,
+): string {
+  return entityFileMap[entityType].extension;
+}
+
+export function getSchemaFromFileTypeEntity(
+  entityType: FileTypeEntity,
+): SchemaObject {
+  return entityFileMap[entityType].metadataSchema;
+}
+
+export function getFileTypeEntityFromExtension(
+  extension: string,
+): FileTypeEntity | null {
+  return (
+    Object.values(entityFileMap).find((e) => e.extension === extension)?.id ||
+    null
+  );
+}
+
+//
+// Namespace overrides files
+//
+
+const fileTypeNamespaceOverridesSchema = z.enum(["verified", "limits"]);
+export type FileTypeNamespaceOverrides = z.infer<
+  typeof fileTypeNamespaceOverridesSchema
+>;
+
+const namespaceOverridesFileMap: {
+  [Id in FileTypeNamespaceOverrides]: {
+    schema: SchemaObject;
+  };
+} = {
+  verified: {
+    schema: namespaceVerificationsSchema,
+  },
+  limits: {
+    schema: pushLimitOverridesSchema,
+  },
+};
+
+export function getSchemaFromFileTypeNamespaceOverrides(
+  overridesFileType: FileTypeNamespaceOverrides,
+): SchemaObject {
+  return namespaceOverridesFileMap[overridesFileType].schema;
+}
+
+//
+// All file types
+//
+
+type FileType =
+  | FileTypeEntity
+  | "blob"
+  | "namespace"
+  | FileTypeNamespaceOverrides;
+
+//
+// Main ChangedFile class
+//
+
+export class ChangedFile {
+  constructor(
+    public path: string,
+    public pr: PR,
+  ) {}
+
+  public getFileType(): FileType | null {
+    if (this.path.startsWith("specs/")) return "spec";
+    if (this.path.startsWith("stacks/")) return "stack";
+    if (this.path.startsWith("parsers/")) return "parser";
+    if (this.path.startsWith("blobs/")) return "blob";
+    if (this.path.startsWith("namespaces/") && this.path.endsWith(".json")) {
+      if (this.path === "namespaces/verified.json") return "verified";
+      if (this.path === "namespaces/push-limit-overrides.json") return "limits";
+      return "namespace";
+    }
+    return null;
+  }
+
+  public getNamespace(type: FileTypeEntity | "namespace"): string {
+    const base = this.pr.registry.helpers.fs.splitPath(this.path)[1];
+    if (type === "namespace") return base.replace(".json", "");
+    return base;
+  }
+
+  public parseJson(): any {
+    const { settings, helpers } = this.pr.registry;
+    const { fs } = helpers;
+
+    const fullPath = fs.resolvePath(settings.repoRoot, this.path);
+    const content = fs.readFileAsUtf8(fullPath);
+
+    return parseJSON(content);
+  }
+
+  public validate(): FileValidationResult {
+    const fileType = this.getFileType();
+
+    if (!fileType) {
+      return {
+        file: this.path,
+        type: "unknown",
+        result: {
+          success: false,
+          errors: [
+            createError(
+              "File path does not match any known registry structure",
+              ERROR_CODES.FILE_TYPE_UNKNOWN,
+            ),
+          ],
+        },
+      };
+    }
+
+    let result: ValidationResult;
+    switch (fileType) {
+      case "spec":
+      case "stack":
+      case "parser":
+        result = validateEntity(this, fileType);
+        break;
+      case "blob":
+        result = validateBlob(this);
+        break;
+      case "namespace":
+        result = validateNamespaceMetadata(this);
+        break;
+      case "verified":
+      case "limits":
+        result = validateNamespaceOverrides(this, fileType);
+        break;
+    }
+
+    return { file: this.path, type: fileType, result };
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { Helpers, RegistryValidator } from "./registry-validator.js";
+export { settingsSchema } from "./settings.js";
+export type { Settings } from "./settings.js";

package/src/lib/check-push-limit.ts

@@ -0,0 +1,91 @@
+import { Helpers } from "../registry-validator.js";
+import { getNamespaceEditorEntry } from "./namespace.js";
+import {
+  getNamespaceMetadataFromHead,
+  getPushLimitOverridesFromHead,
+} from "./git-head.js";
+import {
+  ValidationError,
+  ERROR_CODES,
+  createError,
+} from "../validation-result.js";
+import { Settings } from "../settings.js";
+
+export function checkPushLimit(
+  prAuthor: string,
+  namespace: string,
+  helpers: Helpers,
+  settings: Settings,
+): ValidationError | null {
+  const namespaceMetadata = getNamespaceMetadataFromHead(namespace, helpers);
+  if (!namespaceMetadata) return null;
+
+  const editorEntry = getNamespaceEditorEntry(prAuthor, namespaceMetadata);
+  if (!editorEntry) return null;
+
+  let editorLimit = editorEntry.pushLimit || {
+    unit: settings.pushLimits.default.unit,
+    value: settings.pushLimits.default.pushes,
+  };
+
+  const overrides = getPushLimitOverridesFromHead(helpers);
+  const override = overrides
+    ? overrides.find((o) => o.namespace === namespace)
+    : undefined;
+
+  let effectiveLimit = editorLimit;
+  let limitSource = "editor settings";
+
+  if (override) {
+    const overrideValue = override.pushLimit.value;
+    const editorValue = editorLimit.value;
+
+    if (overrideValue < editorValue) {
+      effectiveLimit = override.pushLimit;
+      limitSource = "namespace override";
+    }
+  } else if (!editorEntry.pushLimit) {
+    limitSource = "default (10/day)";
+  }
+
+  try {
+    const now = new Date();
+    const msInDay = 24 * 60 * 60 * 1000;
+    const msInUnit = effectiveLimit.unit === "daily" ? msInDay : msInDay * 7;
+    const startDate = new Date(now.getTime() - msInUnit);
+
+    const filePrefixes = [
+      `specs/${namespace}/`,
+      `stacks/${namespace}/`,
+      `parsers/${namespace}/`,
+      `blobs/${namespace}/`,
+    ];
+
+    const prs = helpers.git
+      .getAllPRs()
+      .filter(
+        (pr) => pr.user.id === prAuthor && new Date(pr.createdAt) >= startDate,
+      );
+
+    let count = 0;
+    for (const pr of prs) {
+      const files = helpers.git.getPRFiles(pr.url);
+
+      const touchesNamespace = files.some((f: any) =>
+        filePrefixes.some((prefix) => f.filename.startsWith(prefix)),
+      );
+
+      if (touchesNamespace) count++;
+    }
+
+    if (count >= effectiveLimit.value)
+      return createError(
+        `Push limit exceeded for namespace "${namespace}": ${count}/${effectiveLimit.value} ${effectiveLimit.unit} pushes used. Limit set by ${limitSource}.`,
+        ERROR_CODES.PUSH_LIMIT_EXCEEDED,
+      );
+
+    return null;
+  } catch (error) {
+    return null;
+  }
+}

package/src/lib/git-head.ts

@@ -0,0 +1,45 @@
+import { SchemaObject } from "../types.js";
+import { Helpers } from "../registry-validator.js";
+import {
+  NamespaceMetadata,
+  namespaceMetadataSchema,
+  PushLimitOverrides,
+  pushLimitOverridesSchema,
+} from "@figulus/schema/registry";
+import { parseJSON } from "./parse.js";
+
+function getFileFromHeadAndParse(
+  filePath: string,
+  schema: SchemaObject,
+  helpers: Helpers,
+) {
+  try {
+    const headContent = helpers.git.showHead(filePath);
+    const data = parseJSON(headContent);
+    const result = schema.safeParse(data);
+    return result.success ? data : null;
+  } catch (error) {
+    return null;
+  }
+}
+
+export function getPushLimitOverridesFromHead(
+  helpers: Helpers,
+): PushLimitOverrides | null {
+  return getFileFromHeadAndParse(
+    "namespaces/push-limit-overrides.json",
+    pushLimitOverridesSchema,
+    helpers,
+  );
+}
+
+export function getNamespaceMetadataFromHead(
+  namespace: string,
+  helpers: Helpers,
+): NamespaceMetadata | null {
+  return getFileFromHeadAndParse(
+    `namespaces/${namespace}.json`,
+    namespaceMetadataSchema,
+    helpers,
+  );
+}

package/src/lib/namespace.ts

@@ -0,0 +1,21 @@
+import { ChangedFile, FileTypeEntity } from "../changed-file.js";
+import {
+  NamespaceMetadata,
+  NamespaceMetadataEditorEntry,
+} from "@figulus/schema/registry";
+
+export function getNamespaceFromFilePath(
+  file: ChangedFile,
+  type: FileTypeEntity | "namespace",
+): string {
+  const base = file.pr.registry.helpers.fs.splitPath(file.path)[1];
+  if (type === "namespace") return base.replace(".json", "");
+  return base;
+}
+
+export function getNamespaceEditorEntry(
+  user: string,
+  namespaceMetadata: NamespaceMetadata,
+): NamespaceMetadataEditorEntry | undefined {
+  return namespaceMetadata.editors.find((e) => e.username === user);
+}

package/src/lib/parse.ts

@@ -0,0 +1,47 @@
+import stripComments from "strip-json-comments";
+import z from "zod";
+import { ChangedFile } from "../changed-file.js";
+import {
+  ValidationResult,
+  ERROR_CODES,
+  createError,
+  success,
+} from "../validation-result.js";
+
+export function parseJSON(data: string): any {
+  return JSON.parse(stripComments(data));
+}
+
+export function parseSchema(
+  data: any,
+  schema: z.ZodType<any>,
+): ValidationResult {
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    const errors = result.error.issues.map((err) => {
+      const path = err.path.length > 0 ? err.path.join(".") : "root";
+      return createError(
+        `${path}: ${err.message}`,
+        ERROR_CODES.ENTITY_SCHEMA_INVALID,
+      );
+    });
+    return { success: false, errors };
+  }
+  return success();
+}
+
+export function parseFileJson(file: ChangedFile): any {
+  try {
+    const { settings, helpers } = file.pr.registry;
+    const { fs } = helpers;
+
+    const fullPath = fs.resolvePath(settings.repoRoot, file.path);
+    const content = fs.readFileAsUtf8(fullPath);
+
+    return parseJSON(content);
+  } catch (error) {
+    throw new Error(
+      `Failed to parse JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}

package/src/lib/permissions.ts

@@ -0,0 +1,17 @@
+import { RegistryValidator } from "../registry-validator.js";
+
+export function isRegistryMaintainer(
+  user: string,
+  registry: RegistryValidator,
+): boolean {
+  const { registryMaintainers } = registry.settings;
+  return registryMaintainers.includes(user);
+}
+
+export function isReservedNamespace(
+  namespace: string,
+  registry: RegistryValidator,
+): boolean {
+  const { restrictedNamespaces } = registry.settings;
+  return restrictedNamespaces.includes(namespace);
+}

package/src/lib/validate-blob-references.ts

@@ -0,0 +1,47 @@
+import {
+  FileTypeEntity,
+  getExtensionFromFileTypeEntity,
+} from "../changed-file.js";
+import { RegistryValidator } from "../registry-validator.js";
+import {
+  ValidationResult,
+  ERROR_CODES,
+  createError,
+  success,
+} from "../validation-result.js";
+
+export function validateBlobReferences(
+  data: any,
+  namespace: string,
+  type: FileTypeEntity,
+  registry: RegistryValidator,
+): ValidationResult {
+  const errors = [];
+
+  const variants = data.variants || [];
+  if (!Array.isArray(variants)) return success();
+
+  for (const variant of variants) {
+    const blob = variant.blob || {};
+    const contentHash = blob.contentHash;
+    const extension = getExtensionFromFileTypeEntity(type);
+
+    if (!contentHash || !extension) continue;
+
+    const blobPath = registry.helpers.fs.resolvePath(
+      registry.settings.repoRoot,
+      `blobs/${namespace}/${contentHash}.${extension}`,
+    );
+
+    if (!registry.helpers.fs.fileOrDirExists(blobPath)) {
+      errors.push(
+        createError(
+          `Variant references blob ${contentHash} but blobs/${namespace}/${contentHash}.${extension} does not exist in the repository`,
+          ERROR_CODES.BLOB_REFERENCE_NOT_FOUND,
+        ),
+      );
+    }
+  }
+
+  return errors.length > 0 ? { success: false, errors } : success();
+}

package/src/lib/validate-file/blob.ts

@@ -0,0 +1,84 @@
+import {
+  ChangedFile,
+  getFileTypeEntityFromExtension,
+} from "../../changed-file.js";
+import {
+  ValidationResult,
+  ERROR_CODES,
+  createError,
+  success,
+} from "../../validation-result.js";
+
+export function validateBlob(file: ChangedFile): ValidationResult {
+  const { helpers, settings } = file.pr.registry;
+
+  const fileName = helpers.fs.splitPath(file.path).pop();
+  if (!fileName) {
+    return {
+      success: false,
+      errors: [
+        createError("Invalid blob filename", ERROR_CODES.BLOB_INVALID_FILENAME),
+      ],
+    };
+  }
+
+  const parts = fileName.split(".");
+  if (parts.length < 2) {
+    return {
+      success: false,
+      errors: [
+        createError(
+          "Blob filename must have extension",
+          ERROR_CODES.BLOB_MISSING_EXTENSION,
+        ),
+      ],
+    };
+  }
+
+  const expectedHash = parts[0];
+  const extension = parts.slice(1).join(".");
+
+  const entityType = getFileTypeEntityFromExtension(extension);
+
+  if (!entityType) {
+    return {
+      success: false,
+      errors: [
+        createError(
+          `Invalid blob extension: ${extension} (must be js, figspec, or figstack)`,
+          ERROR_CODES.BLOB_INVALID_EXTENSION,
+        ),
+      ],
+    };
+  }
+
+  try {
+    const path = helpers.fs.resolvePath(settings.repoRoot, file.path);
+    const content = helpers.fs.readFileAsUtf8(path);
+    const actualHash = helpers.crypto.createSha256HexHash(content);
+
+    if (actualHash !== expectedHash) {
+      return {
+        success: false,
+        errors: [
+          createError(
+            `Hash mismatch: filename hash ${expectedHash} does not match content hash ${actualHash}`,
+            ERROR_CODES.BLOB_HASH_MISMATCH,
+          ),
+        ],
+      };
+    }
+  } catch (error) {
+    return {
+      success: false,
+      errors: [
+        createError(
+          `Failed to verify blob: ${error instanceof Error ? error.message : String(error)}`,
+          ERROR_CODES.BLOB_VERIFICATION_FAILED,
+        ),
+      ],
+    };
+  }
+
+  return success();
+}

package/src/lib/validate-file/entity.ts

@@ -0,0 +1,111 @@
+import {
+  ChangedFile,
+  FileTypeEntity,
+  getSchemaFromFileTypeEntity,
+} from "../../changed-file.js";
+import { getNamespaceEditorEntry } from "../namespace.js";
+import { parseSchema } from "../parse.js";
+import { checkPushLimit } from "../check-push-limit.js";
+import { getNamespaceMetadataFromHead } from "../git-head.js";
+import { validateBlobReferences } from "../validate-blob-references.js";
+import {
+  ValidationResult,
+  ERROR_CODES,
+  createError,
+  success,
+} from "../../validation-result.js";
+
+export function validateEntity(
+  file: ChangedFile,
+  type: FileTypeEntity,
+): ValidationResult {
+  const { registry, prInfo } = file.pr;
+  const { settings, helpers } = registry;
+  const { fs } = helpers;
+
+  const namespace = file.getNamespace(type);
+
+  const isAllowedToChangeEntityFile = () => {
+    if (registry.isNamespaceRestricted(namespace)) {
+      if (!registry.isMaintainer(prInfo.author)) {
+        return {
+          success: false,
+          errors: [
+            createError(
+              `The ${namespace}/ namespace is reserved. Changes require maintainer approval.`,
+              ERROR_CODES.NAMESPACE_RESERVED,
+            ),
+          ],
+        };
+      }
+    } else {
+      const namespaceMetadata = getNamespaceMetadataFromHead(
+        namespace,
+        registry.helpers,
+      );
+      if (namespaceMetadata === null) {
+        return {
+          success: false,
+          errors: [
+            createError(
+              `Namespace "${namespace}" does not exist. Run \`figulus registry claim ${namespace}\` to claim it before publishing.`,
+              ERROR_CODES.NAMESPACE_NOT_FOUND,
+            ),
+          ],
+        };
+      }
+
+      if (!getNamespaceEditorEntry(prInfo.author, namespaceMetadata)) {
+        return {
+          success: false,
+          errors: [
+            createError(
+              `PR author "${prInfo.author}" is not listed as an editor for namespace "${namespace}"`,
+              ERROR_CODES.NAMESPACE_NOT_EDITOR,
+            ),
+          ],
+        };
+      }
+
+      const pushLimitError = checkPushLimit(
+        prInfo.author,
+        namespace,
+        helpers,
+        settings,
+      );
+      if (pushLimitError) {
+        return {
+          success: false,
+          errors: [pushLimitError],
+        };
+      }
+    }
+
+    return success();
+  };
+
+  const permissionResult = isAllowedToChangeEntityFile();
+  if (!permissionResult.success) return permissionResult;
+
+  try {
+    const data = file.parseJson();
+
+    const schemaResult = parseSchema(data, getSchemaFromFileTypeEntity(type));
+    if (!schemaResult.success) return schemaResult;
+
+    const blobResult = validateBlobReferences(data, namespace, type, registry);
+    if (!blobResult.success) return blobResult;
+
+    return success();
+  } catch (error) {
+    return {
+      success: false,
+      errors: [
+        createError(
+          `Failed to parse ${type}: ${error instanceof Error ? error.message : String(error)}`,
+          ERROR_CODES.ENTITY_PARSE_ERROR,
+        ),
+      ],
+    };
+  }
+}

package/src/lib/validate-file/namespace-metadata.ts

@@ -0,0 +1,179 @@
+import { ChangedFile } from "../../changed-file.js";
+import { namespaceMetadataSchema } from "@figulus/schema";
+import { parseJSON, parseSchema } from "../parse.js";
+import { validateOwnershipTransfer } from "../validate-ownership-transfer.js";
+import {
+  ValidationResult,
+  ValidationError,
+  ERROR_CODES,
+  createError,
+  success,
+} from "../../validation-result.js";
+import {
+  validatePushLimitConstraints,
+  getPushLimitConstraintsForEditor,
+} from "../validate-push-limit-constraints.js";
+
+export function validateNamespaceMetadata(file: ChangedFile): ValidationResult {
+  const { registry, prInfo } = file.pr;
+  const { git } = registry.helpers;
+
+  const namespace = file.getNamespace("namespace");
+
+  if (registry.isNamespaceRestricted(namespace)) {
+    if (!registry.isMaintainer(prInfo.author))
+      return {
+        success: false,
+        errors: [
+          createError(
+            `Cannot create namespace "${namespace}": this name is reserved. You must be a registry maintainer to claim this namespace.`,
+            ERROR_CODES.NAMESPACE_RESERVED,
+          ),
+        ],
+      };
+  }
+
+  const prAuthor = file.pr.prInfo.author;
+
+  const validatePushLimitsInMetadata = (data: any): ValidationError[] => {
+    const errors: ValidationError[] = [];
+    const editors = data.editors || [];
+
+    for (const editor of editors) {
+      if (editor.pushLimit) {
+        const constraints = getPushLimitConstraintsForEditor(
+          registry.settings,
+          editor.pushLimit.unit,
+        );
+        const error = validatePushLimitConstraints(
+          editor.pushLimit,
+          constraints,
+          `Editor ${editor.username}`,
+        );
+        if (error) errors.push(error);
+      }
+    }
+
+    return errors;
+  };
+
+  if (namespace) {
+    try {
+      try {
+        const headContent = git.showHead(file.path);
+        const headData = parseJSON(headContent);
+
+        const headEditors = headData.editors || [];
+        const isEditorInHead = headEditors.some(
+          (e: any) => e.username === prAuthor,
+        );
+        if (!isEditorInHead)
+          return {
+            success: false,
+            errors: [
+              createError(
+                `PR author "${prAuthor}" is not listed as an editor in the existing namespace metadata`,
+                ERROR_CODES.NAMESPACE_NOT_EDITOR,
+              ),
+            ],
+          };
+
+        try {
+          const submittedData = file.parseJson();
+          const headOwner = headData.owner?.username;
+          const submittedOwner = submittedData.owner?.username;
+
+          const ownershipResult = validateOwnershipTransfer(
+            headOwner,
+            submittedOwner,
+            prAuthor,
+          );
+          if (!ownershipResult.success) {
+            return ownershipResult;
+          }
+        } catch {
+          // Continue - this error will be caught again during full validation
+        }
+
+        // Namespace exists in HEAD and author is a valid editor with no ownership violations
+        // Validate the submitted file against the schema
+        try {
+          const data = file.parseJson();
+          const schemaResult = parseSchema(data, namespaceMetadataSchema);
+          if (!schemaResult.success) return schemaResult;
+
+          const pushLimitErrors = validatePushLimitsInMetadata(data);
+          if (pushLimitErrors.length > 0) {
+            return { success: false, errors: pushLimitErrors };
+          }
+
+          return success();
+        } catch (error) {
+          return {
+            success: false,
+            errors: [
+              createError(
+                `Failed to parse namespace metadata: ${error instanceof Error ? error.message : String(error)}`,
+                ERROR_CODES.NAMESPACE_PARSE_ERROR,
+              ),
+            ],
+          };
+        }
+      } catch (parseError) {
+        return {
+          success: false,
+          errors: [
+            createError(
+              `Failed to parse HEAD version of namespace metadata: ${parseError instanceof Error ? parseError.message : String(parseError)}`,
+              ERROR_CODES.NAMESPACE_PARSE_ERROR,
+            ),
+          ],
+        };
+      }
+    } catch {
+      // File doesn't exist in HEAD - this is a new namespace claim
+      // Fall through to validate the new submission
+    }
+  }
+
+  // If we reach here, the namespace doesn't exist in HEAD (new namespace claim)
+  try {
+    const data = file.parseJson();
+    const schemaResult = parseSchema(data, namespaceMetadataSchema);
+
+    if (!schemaResult.success) return schemaResult;
+
+    // Check push limit constraints
+    const pushLimitErrors = validatePushLimitsInMetadata(data);
+    if (pushLimitErrors.length > 0) {
+      return { success: false, errors: pushLimitErrors };
+    }
+
+    // For new namespaces, check that PR author is in editors
+    const editors = data.editors || [];
+    const isEditor = editors.some((e: any) => e.username === prAuthor);
+    if (!isEditor) {
+      return {
+        success: false,
+        errors: [
+          createError(
+            `PR author "${prAuthor}" is not listed as an editor in the namespace`,
+            ERROR_CODES.NAMESPACE_NOT_EDITOR,
+          ),
+        ],
+      };
+    }
+
+    return success();
+  } catch (error) {
+    return {
+      success: false,
+      errors: [
+        createError(
+          `Failed to parse namespace metadata: ${error instanceof Error ? error.message : String(error)}`,
+          ERROR_CODES.NAMESPACE_PARSE_ERROR,
+        ),
+      ],
+    };
+  }
+}

package/src/lib/validate-file/namespace-overrides.ts

@@ -0,0 +1,80 @@
+import {
+  ChangedFile,
+  FileTypeNamespaceOverrides,
+  getSchemaFromFileTypeNamespaceOverrides,
+} from "../../changed-file.js";
+import { parseSchema } from "../parse.js";
+import {
+  ValidationResult,
+  ERROR_CODES,
+  createError,
+} from "../../validation-result.js";
+import {
+  validatePushLimitConstraints,
+  getPushLimitConstraintsForMaintainer,
+} from "../validate-push-limit-constraints.js";
+
+export function validateNamespaceOverrides(
+  file: ChangedFile,
+  fileType: FileTypeNamespaceOverrides,
+): ValidationResult {
+  const { registry, prInfo } = file.pr;
+  if (!registry.isMaintainer(prInfo.author)) {
+    return {
+      success: false,
+      errors: [
+        createError(
+          `Only registry maintainers can modify ${file.path}`,
+          ERROR_CODES.PERMISSION_DENIED_MAINTAINER_ONLY,
+        ),
+      ],
+    };
+  }
+
+  try {
+    const data = file.parseJson();
+    const schemaResult = parseSchema(
+      data,
+      getSchemaFromFileTypeNamespaceOverrides(fileType),
+    );
+
+    if (!schemaResult.success) return schemaResult;
+
+    // For limits overrides, validate push limit constraints
+    if (fileType === "limits") {
+      const errors = [];
+      const overrides = data || [];
+
+      for (const override of overrides) {
+        if (override.pushLimit) {
+          const constraints = getPushLimitConstraintsForMaintainer(
+            registry.settings,
+            override.pushLimit.unit,
+          );
+          const error = validatePushLimitConstraints(
+            override.pushLimit,
+            constraints,
+            `Namespace ${override.namespace}`,
+          );
+          if (error) errors.push(error);
+        }
+      }
+
+      if (errors.length > 0) {
+        return { success: false, errors };
+      }
+    }
+
+    return schemaResult;
+  } catch (error) {
+    return {
+      success: false,
+      errors: [
+        createError(
+          `Failed to parse ${file.path}: ${error instanceof Error ? error.message : String(error)}`,
+          ERROR_CODES.NAMESPACE_PARSE_ERROR,
+        ),
+      ],
+    };
+  }
+}

package/src/lib/validate-ownership-transfer.ts

@@ -0,0 +1,26 @@
+import {
+  ValidationResult,
+  ERROR_CODES,
+  createError,
+  success,
+} from "../validation-result.js";
+
+export function validateOwnershipTransfer(
+  headOwner: string | undefined,
+  submittedOwner: string | undefined,
+  prAuthor: string,
+): ValidationResult {
+  if (submittedOwner !== headOwner && prAuthor !== headOwner) {
+    return {
+      success: false,
+      errors: [
+        createError(
+          `Only the namespace owner ("${headOwner}") can transfer ownership`,
+          ERROR_CODES.NAMESPACE_OWNERSHIP_TRANSFER_DENIED,
+        ),
+      ],
+    };
+  }
+
+  return success();
+}

package/src/lib/validate-push-limit-constraints.ts

@@ -0,0 +1,39 @@
+import { Settings } from "../settings.js";
+import {
+  ValidationError,
+  ERROR_CODES,
+  createError,
+} from "../validation-result.js";
+
+export interface PushLimitValue {
+  unit: "daily" | "weekly";
+  value: number;
+}
+
+export function validatePushLimitConstraints(
+  pushLimit: PushLimitValue,
+  constraints: { min: number; max: number },
+  context: string,
+): ValidationError | null {
+  if (pushLimit.value < constraints.min || pushLimit.value > constraints.max) {
+    return createError(
+      `${context} push limit ${pushLimit.value}/${pushLimit.unit} is outside allowed range: ${constraints.min}-${constraints.max}`,
+      ERROR_CODES.PUSH_LIMIT_EXCEEDED,
+    );
+  }
+  return null;
+}
+
+export function getPushLimitConstraintsForEditor(
+  settings: Settings,
+  unit: "daily" | "weekly",
+): { min: number; max: number } {
+  return settings.pushLimits.overridesSetBy.namespaceOwners[unit];
+}
+
+export function getPushLimitConstraintsForMaintainer(
+  settings: Settings,
+  unit: "daily" | "weekly",
+): { min: number; max: number } {
+  return settings.pushLimits.overridesSetBy.registryMaintainers[unit];
+}

package/src/pr.ts

@@ -0,0 +1,96 @@
+import { RegistryValidator, Helpers } from "./registry-validator";
+import {
+  PullRequestInfo,
+  ValidationSummary,
+  FileValidationResult,
+} from "./types.js";
+import { ChangedFile } from "./changed-file.js";
+import { Settings } from "./settings.js";
+
+export class PR {
+  constructor(
+    public prInfo: PullRequestInfo,
+    public registry: RegistryValidator,
+  ) {}
+
+  public getAuthor(): string {
+    return this.prInfo.author;
+  }
+
+  public getSettings(): Settings {
+    return this.registry.settings;
+  }
+
+  public getHelpers(): Helpers {
+    return this.registry.helpers;
+  }
+
+  public validate(): ValidationSummary {
+    const { prInfo, registry } = this;
+    const { helpers } = registry;
+
+    const results: FileValidationResult[] = [];
+    let filesWithErrors = 0;
+    let filesWithWarnings = 0;
+
+    if (prInfo.changedFiles.length === 0) {
+      helpers.console.log("No changed files to validate");
+      return {
+        success: true,
+        totalFiles: 0,
+        filesWithErrors: 0,
+        filesWithWarnings: 0,
+        results: [],
+      };
+    }
+
+    for (const file of prInfo.changedFiles) {
+      const result = new ChangedFile(file, this).validate();
+      results.push(result);
+
+      if (!result.result.success) {
+        filesWithErrors++;
+      } else if (result.result.warnings?.length) {
+        filesWithWarnings++;
+      }
+    }
+
+    // Output results
+    const hasErrors = filesWithErrors > 0;
+    if (hasErrors) {
+      helpers.console.error("\n❌ Validation failed:\n");
+      for (const result of results) {
+        if (!result.result.success) {
+          helpers.console.error(`📄 ${result.file}:`);
+          result.result.errors.forEach((err) => {
+            helpers.console.error(`   • [${err.code}] ${err.message}`);
+          });
+        }
+      }
+    } else {
+      helpers.console.log("✅ All validations passed!");
+    }
+
+    if (filesWithWarnings > 0) {
+      helpers.console.log(
+        `\n⚠️  ${filesWithWarnings} file(s) with warnings:\n`,
+      );
+      for (const result of results) {
+        if (result.result.success && result.result.warnings?.length) {
+          helpers.console.log(`📄 ${result.file}:`);
+          result.result.warnings.forEach((warn) => {
+            helpers.console.log(`   • [${warn.code}] ${warn.message}`);
+          });
+        }
+      }
+    }
+
+    return {
+      success: !hasErrors,
+      totalFiles: prInfo.changedFiles.length,
+      filesWithErrors,
+      filesWithWarnings,
+      results,
+    };
+  }
+}

package/src/registry-validator.ts

@@ -0,0 +1,49 @@
+import { PR } from "./pr.js";
+import { Settings } from "./settings.js";
+import { PullRequestInfo } from "./types.js";
+
+export interface Helpers {
+  console: {
+    log: (...data: any[]) => void;
+    error: (...data: any[]) => void;
+  };
+  crypto: {
+    createSha256HexHash: (data: string) => string;
+  };
+  fs: {
+    resolvePath: (...paths: string[]) => string;
+    splitPath: (path: string) => string[];
+    fileOrDirExists: (path: string) => boolean;
+    readFileAsUtf8: (path: string) => string;
+  };
+  git: {
+    showHead: (filePath: string) => string;
+    getAllPRs: () => {
+      url: string;
+      createdAt: string;
+      user: { id: string };
+    }[];
+    getPRFiles: (url: string) => {
+      filename: string;
+    }[];
+  };
+}
+
+export class RegistryValidator {
+  constructor(
+    public helpers: Helpers,
+    public settings: Settings,
+  ) {}
+
+  public validatePr(prInfo: PullRequestInfo) {
+    return new PR(prInfo, this);
+  }
+
+  public isMaintainer(user: string): boolean {
+    return this.settings.registryMaintainers.includes(user);
+  }
+
+  public isNamespaceRestricted(namespace: string): boolean {
+    return this.settings.restrictedNamespaces.includes(namespace);
+  }
+}

package/src/settings.ts

@@ -0,0 +1,59 @@
+import z from "zod";
+
+const pushLimitOverridesSetBySchema = z.object({
+  daily: z.object({
+    max: z.int(),
+    min: z.int(),
+  }),
+  weekly: z.object({
+    max: z.int(),
+    min: z.int(),
+  }),
+});
+
+export const settingsSchema = z.object({
+  repoRoot: z.string(),
+  registryMaintainers: z
+    .string()
+    .array()
+    .optional()
+    .default(["figulusproject"]),
+  restrictedNamespaces: z
+    .string()
+    .array()
+    .optional()
+    .default([
+      "examples",
+      "figulus",
+      "official",
+      "push-limit-overrides",
+      "verified",
+    ]),
+  pushLimits: z
+    .object({
+      default: z.object({
+        unit: z.enum(["daily", "weekly"]),
+        pushes: z.int(),
+      }),
+      overridesSetBy: z.object({
+        namespaceOwners: pushLimitOverridesSetBySchema,
+        registryMaintainers: pushLimitOverridesSetBySchema,
+      }),
+    })
+    .optional()
+    .default({
+      default: { unit: "daily", pushes: 10 },
+      overridesSetBy: {
+        namespaceOwners: {
+          daily: { min: 1, max: 10 },
+          weekly: { min: 1, max: 10 * 7 },
+        },
+        registryMaintainers: {
+          daily: { min: 0, max: 30 },
+          weekly: { min: 0, max: 30 * 7 },
+        },
+      },
+    }),
+});
+
+export type Settings = z.infer<typeof settingsSchema>;

package/src/types.ts

@@ -0,0 +1,23 @@
+import { ZodArray, ZodObject } from "zod";
+import { ValidationResult } from "./validation-result.js";
+
+export type SchemaObject = ZodObject | ZodArray;
+
+export interface PullRequestInfo {
+  changedFiles: string[];
+  author: string;
+}
+
+export interface FileValidationResult {
+  file: string;
+  type: string;
+  result: ValidationResult;
+}
+
+export interface ValidationSummary {
+  success: boolean;
+  totalFiles: number;
+  filesWithErrors: number;
+  filesWithWarnings: number;
+  results: FileValidationResult[];
+}

package/src/validation-result.ts

@@ -0,0 +1,78 @@
+export const ERROR_CODES = {
+  // File type errors
+  FILE_TYPE_UNKNOWN: "FILE_TYPE_UNKNOWN",
+
+  // Blob errors
+  BLOB_INVALID_FILENAME: "BLOB_INVALID_FILENAME",
+  BLOB_MISSING_EXTENSION: "BLOB_MISSING_EXTENSION",
+  BLOB_INVALID_EXTENSION: "BLOB_INVALID_EXTENSION",
+  BLOB_HASH_MISMATCH: "BLOB_HASH_MISMATCH",
+  BLOB_VERIFICATION_FAILED: "BLOB_VERIFICATION_FAILED",
+  BLOB_REFERENCE_NOT_FOUND: "BLOB_REFERENCE_NOT_FOUND",
+
+  // Entity errors
+  ENTITY_PARSE_ERROR: "ENTITY_PARSE_ERROR",
+  ENTITY_SCHEMA_INVALID: "ENTITY_SCHEMA_INVALID",
+
+  // Namespace errors
+  NAMESPACE_RESERVED: "NAMESPACE_RESERVED",
+  NAMESPACE_NOT_FOUND: "NAMESPACE_NOT_FOUND",
+  NAMESPACE_NOT_EDITOR: "NAMESPACE_NOT_EDITOR",
+  NAMESPACE_PARSE_ERROR: "NAMESPACE_PARSE_ERROR",
+  NAMESPACE_SCHEMA_INVALID: "NAMESPACE_SCHEMA_INVALID",
+  NAMESPACE_OWNERSHIP_TRANSFER_DENIED: "NAMESPACE_OWNERSHIP_TRANSFER_DENIED",
+
+  // Permissions
+  PERMISSION_DENIED_MAINTAINER_ONLY: "PERMISSION_DENIED_MAINTAINER_ONLY",
+
+  // Push limit
+  PUSH_LIMIT_EXCEEDED: "PUSH_LIMIT_EXCEEDED",
+} as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+
+export interface ValidationError {
+  message: string;
+  code: ErrorCode;
+}
+
+export interface SuccessResult {
+  success: true;
+  warnings?: ValidationError[];
+}
+
+export interface FailureResult {
+  success: false;
+  errors: ValidationError[];
+}
+
+export type ValidationResult = SuccessResult | FailureResult;
+
+export function createError(message: string, code: ErrorCode): ValidationError {
+  return { message, code };
+}
+
+export function createWarning(
+  message: string,
+  code: ErrorCode,
+): ValidationError {
+  return { message, code };
+}
+
+export function success(warnings: ValidationError[] = []): SuccessResult {
+  return warnings.length > 0 ? { success: true, warnings } : { success: true };
+}
+
+export function failure(errors: ValidationError[]): FailureResult {
+  return { success: false, errors };
+}
+
+export function failureFromStrings(
+  messages: string[],
+  code: ErrorCode,
+): FailureResult {
+  return {
+    success: false,
+    errors: messages.map((msg) => createError(msg, code)),
+  };
+}

package/tsconfig.build.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}