@comity-dev/schemas 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Filippo Bovo and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @comity-dev/schemas
+
+## Purpose
+
+Canonical, machine-readable JSON Schema definitions for Comity package metadata, the ADR-008 register, and `comity.config.json`. These schemas are the authoritative source for Comity-wide metadata policy.
+
+## Scope
+
+- `package-metadata.v1.json` — required fields and types for every `@comity/*` package's `package.json` (`name`, `version`, `type`, `license`, `engines`, `exports`, `comity.layer`, `comity.implements`).
+- ADR-008 register schema — machine-readable composition exception register.
+- `comity-config.json` schema — repository-level configuration shape.
+
+## Ownership
+
+Owned by `comity-development`. Consumed by `@comity-dev/validate` (in-process) and indirectly by every Comity repository via the validator.
+
+## Public API
+
+```ts
+import {
+  packageMetadataSchema,
+  validatePackageMetadata,
+  comityConfigSchema,
+  validateComityConfig,
+  adr008RegisterSchema,
+  validateAdr008Register,
+  createAjvInstance,
+  PACKAGE_NAME_PATTERN,
+  VALID_LAYERS,
+  MIN_NODE_VERSION,
+} from "@comity-dev/schemas";
+```
+
+A consolidated subpath exposes every schema and its validator for
+finer-grained consumers:
+
+```ts
+import {
+  packageMetadataSchema,
+  validatePackageMetadata,
+  comityConfigSchema,
+  validateComityConfig,
+  adr008RegisterSchema,
+  validateAdr008Register,
+} from "@comity-dev/schemas";
+```
+
+## Relationship to Comity Standards
+
+- `layering-policy.md` §2.1 — layer enum source.
+- `ADR-026` — authoritative package classification.
+- `architecture-validation.md` §8 — package metadata, naming, engines.
+
+## Development
+
+```bash
+pnpm build
+pnpm test
+```

package/dist/ajv-instance.d.ts

@@ -0,0 +1,7 @@
+import Ajv from "ajv";
+/**
+ * Creates a fresh Ajv instance with strict settings and standard formats.
+ *
+ * @returns Configured Ajv instance
+ */
+export declare function createAjvInstance(): Ajv;

package/dist/ajv-instance.js

@@ -0,0 +1,17 @@
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+/**
+ * Creates a fresh Ajv instance with strict settings and standard formats.
+ *
+ * @returns Configured Ajv instance
+ */
+export function createAjvInstance() {
+    const ajv = new Ajv({
+        allErrors: true,
+        strict: false,
+        strictTypes: false,
+        verbose: true,
+    });
+    addFormats(ajv);
+    return ajv;
+}

package/dist/constants.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Canonical Comity constants.
+ *
+ * These values are derived from the authoritative Comity Standards
+ * (layering-policy.md, ADR-026). They MUST be kept in sync with those
+ * documents; updating them here implies updating the standards.
+ *
+ * @see layering-policy.md §2.1 / ADR-026 (package classification)
+ *
+ * ADR-026 defines `comity.layer` as the architecture classification of
+ * Comity RUNTIME packages (`@comity/*`). The six runtime layers are:
+ *
+ *   primitives, kernel, composition, core,
+ *   technology-adapter, integration-adapter
+ *
+ * `dev-tooling` is a reserved Development-side extension for
+ * `@comity-dev/*` packages only. It is NOT a seventh runtime layer
+ * and MUST NOT be used by `@comity/*` packages. The name-scope ↔
+ * layer boundary is enforced by the package-metadata JSON Schema
+ * (`schemas/package-metadata.ts`).
+ *
+ * Rationale for the extension: Development tooling packages
+ * legitimately use Node APIs, `process.env`, and other patterns that
+ * the runtime Semgrep and ESLint rules forbid. Declaring `dev-tooling`
+ * on these packages lets the validator engines (semgrep, depcruise,
+ * eslint, adapter-peers) scope those rules away from them. The
+ * runtime six-layer model is unchanged.
+ */
+export declare const RUNTIME_LAYERS: readonly string[];
+/**
+ * All layer values accepted by `comity.layer`. The boundary between
+ * runtime and development layers is enforced by the schema, not by
+ * this list alone.
+ */
+export declare const VALID_LAYERS: readonly string[];
+/**
+ * @see ADR-026 (package naming)
+ *      architecture-validation.md §8
+ */
+export declare const PACKAGE_NAME_PATTERN = "^@comity(-dev)?/[a-z0-9]+(?:-[a-z0-9]+)*$";
+/**
+ * @see architecture-validation.md §8 (metadata — engines.node minimum)
+ */
+export declare const MIN_NODE_VERSION = "24.0.0";

package/dist/constants.js

@@ -0,0 +1,54 @@
+/**
+ * Canonical Comity constants.
+ *
+ * These values are derived from the authoritative Comity Standards
+ * (layering-policy.md, ADR-026). They MUST be kept in sync with those
+ * documents; updating them here implies updating the standards.
+ *
+ * @see layering-policy.md §2.1 / ADR-026 (package classification)
+ *
+ * ADR-026 defines `comity.layer` as the architecture classification of
+ * Comity RUNTIME packages (`@comity/*`). The six runtime layers are:
+ *
+ *   primitives, kernel, composition, core,
+ *   technology-adapter, integration-adapter
+ *
+ * `dev-tooling` is a reserved Development-side extension for
+ * `@comity-dev/*` packages only. It is NOT a seventh runtime layer
+ * and MUST NOT be used by `@comity/*` packages. The name-scope ↔
+ * layer boundary is enforced by the package-metadata JSON Schema
+ * (`schemas/package-metadata.ts`).
+ *
+ * Rationale for the extension: Development tooling packages
+ * legitimately use Node APIs, `process.env`, and other patterns that
+ * the runtime Semgrep and ESLint rules forbid. Declaring `dev-tooling`
+ * on these packages lets the validator engines (semgrep, depcruise,
+ * eslint, adapter-peers) scope those rules away from them. The
+ * runtime six-layer model is unchanged.
+ */
+export const RUNTIME_LAYERS = Object.freeze([
+    "primitives",
+    "kernel",
+    "composition",
+    "core",
+    "technology-adapter",
+    "integration-adapter",
+]);
+/**
+ * All layer values accepted by `comity.layer`. The boundary between
+ * runtime and development layers is enforced by the schema, not by
+ * this list alone.
+ */
+export const VALID_LAYERS = Object.freeze([
+    ...RUNTIME_LAYERS,
+    "dev-tooling",
+]);
+/**
+ * @see ADR-026 (package naming)
+ *      architecture-validation.md §8
+ */
+export const PACKAGE_NAME_PATTERN = "^@comity(-dev)?/[a-z0-9]+(?:-[a-z0-9]+)*$";
+/**
+ * @see architecture-validation.md §8 (metadata — engines.node minimum)
+ */
+export const MIN_NODE_VERSION = "24.0.0";

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type { Adr008Register } from "./schemas/adr-008-register.js";
+export type { ComityConfig } from "./schemas/comity-config.js";
+export type { PackageMetadata, ValidationResult, } from "./schemas/package-metadata.js";
+export { createAjvInstance } from "./ajv-instance.js";
+export { MIN_NODE_VERSION, PACKAGE_NAME_PATTERN, RUNTIME_LAYERS, VALID_LAYERS, } from "./constants.js";
+export { adr008CoreExceptionRegister, } from "./schemas/adr-008-register-data.js";
+export { adr008RegisterSchema, validateAdr008Register, } from "./schemas/adr-008-register.js";
+export { comityConfigSchema, validateComityConfig, } from "./schemas/comity-config.js";
+export { packageMetadataSchema, validatePackageMetadata, } from "./schemas/package-metadata.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createAjvInstance } from "./ajv-instance.js";
+export { MIN_NODE_VERSION, PACKAGE_NAME_PATTERN, RUNTIME_LAYERS, VALID_LAYERS, } from "./constants.js";
+export { adr008CoreExceptionRegister, } from "./schemas/adr-008-register-data.js";
+export { adr008RegisterSchema, validateAdr008Register, } from "./schemas/adr-008-register.js";
+export { comityConfigSchema, validateComityConfig, } from "./schemas/comity-config.js";
+export { packageMetadataSchema, validatePackageMetadata, } from "./schemas/package-metadata.js";

package/dist/schemas/adr-008-register-data.d.ts

@@ -0,0 +1,11 @@
+import type { Adr008Register } from "./adr-008-register.js";
+/**
+ * Canonical ADR-008 Core Exception Register.
+ *
+ * This is the authoritative machine-readable representation of the
+ * ADR-008 closed register of Core-to-Core dependency exceptions.
+ *
+ * @see ADR-008 — Explicit Core Module Composition Exceptions
+ * @see ADR-009 — Machine-Readable Core Exception Register
+ */
+export declare const adr008CoreExceptionRegister: Adr008Register;

package/dist/schemas/adr-008-register-data.js

@@ -0,0 +1,184 @@
+/**
+ * Canonical ADR-008 Core Exception Register.
+ *
+ * This is the authoritative machine-readable representation of the
+ * ADR-008 closed register of Core-to-Core dependency exceptions.
+ *
+ * @see ADR-008 — Explicit Core Module Composition Exceptions
+ * @see ADR-009 — Machine-Readable Core Exception Register
+ */
+export const adr008CoreExceptionRegister = {
+    version: "1",
+    edges: [
+        {
+            from: "@comity/storefront",
+            to: "@comity/catalog",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Storefront page composition references catalog domain contracts and models.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+        {
+            from: "@comity/storefront",
+            to: "@comity/taxonomy",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Storefront category page composition references taxonomy domain contracts and models.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+        {
+            from: "@comity/storefront",
+            to: "@comity/content",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Storefront content page composer references content domain models.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+        {
+            from: "@comity/storefront",
+            to: "@comity/search",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Storefront search page contract references SearchResultModel.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+        {
+            from: "@comity/catalog",
+            to: "@comity/media",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Catalog projections reference MediaModel for product/brand media.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+        {
+            from: "@comity/content",
+            to: "@comity/media",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Content blocks/pages reference MediaModel.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+        {
+            from: "@comity/content",
+            to: "@comity/seo",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Content pages reference SeoModel.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+        {
+            from: "@comity/taxonomy",
+            to: "@comity/media",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Taxonomy models reference MediaModel for category image.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+        {
+            from: "@comity/order",
+            to: "@comity/pricing",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Order items reference Price / PriceModifier.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+        {
+            from: "@comity/order",
+            to: "@comity/organization",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Order contracts reference ChannelId for commercial channel scoping.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+        {
+            from: "@comity/customer",
+            to: "@comity/validation",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Customer validator consumes the shared Validator contract.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+        {
+            from: "@comity/customer",
+            to: "@comity/organization",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Customer repository requires TenantId for multi-tenant isolation.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+        {
+            from: "@comity/address",
+            to: "@comity/validation",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Address validator consumes the shared Validator contract.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+        {
+            from: "@comity/identity",
+            to: "@comity/validation",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Identity validator consumes the shared Validator contract.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+        {
+            from: "@comity/auth-tokens",
+            to: "@comity/auth",
+            layer: "core-to-core",
+            categories: ["value-import"],
+            importKind: "mixed",
+            lifecycle: "approved",
+            justification: "Token facade error surface normalizes AuthError at runtime. @comity/auth owns authentication error semantics; direction is intentional and non-cyclic.",
+            adrReference: "ADR-008 — Dependency Register, Value-Import Exceptions",
+        },
+        {
+            from: "@comity/router",
+            to: "@comity/http",
+            layer: "core-to-core",
+            categories: ["infrastructure-contract"],
+            importKind: "type-only",
+            lifecycle: "deprecated",
+            justification: "Router contracts reference HttpContext, HttpHandler, HttpMethod. Compatibility exception; extraction candidate.",
+            adrReference: "ADR-008 — Dependency Register, Infrastructure Contract Exceptions",
+        },
+        {
+            from: "@comity/payment",
+            to: "@comity/pricing",
+            layer: "core-to-core",
+            categories: ["capability"],
+            importKind: "type-only",
+            lifecycle: "approved",
+            justification: "Payment module uses Money value object from pricing for amount representation in PaymentRequest and PaymentOutcome.",
+            adrReference: "ADR-008 — Dependency Register, Capability Exceptions",
+        },
+    ],
+};

package/dist/schemas/adr-008-register.d.ts

@@ -0,0 +1,79 @@
+import type { Ajv, ErrorObject } from "ajv";
+/**
+ * Canonical schema for the ADR-008 Core Exception Register.
+ *
+ * @see ADR-008 — Explicit Core Module Composition Exceptions
+ * @see ADR-009 — Machine-Readable Core Exception Register
+ *
+ * Each repository owns its own register instance; the schema is shared
+ * Development tooling. The register enumerates Core-to-Core dependency
+ * edges that are explicitly permitted despite the default prohibition.
+ */
+export declare const adr008RegisterSchema: {
+    $id: string;
+    type: string;
+    required: string[];
+    additionalProperties: boolean;
+    properties: {
+        version: {
+            type: string;
+            const: string;
+            description: string;
+        };
+        edges: {
+            type: string;
+            uniqueItems: boolean;
+            items: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    from: {
+                        type: string;
+                        pattern: string;
+                        description: string;
+                    };
+                    to: {
+                        type: string;
+                        pattern: string;
+                        description: string;
+                    };
+                    adr: {
+                        type: string;
+                        pattern: string;
+                        description: string;
+                    };
+                    rationale: {
+                        type: string;
+                        minLength: number;
+                        description: string;
+                    };
+                };
+            };
+        };
+    };
+};
+/**
+ * Validates a parsed ADR-008 register document.
+ *
+ * @param document — parsed ADR-008 register
+ * @param ajv — optional pre-built Ajv instance
+ * @returns validation result
+ */
+export declare function validateAdr008Register(document: unknown, ajv?: Ajv): {
+    valid: boolean;
+    errors: ErrorObject[];
+};
+export interface Adr008Register {
+    version: "1";
+    edges: Array<{
+        from: string;
+        to: string;
+        layer: string;
+        categories: string[];
+        importKind: string;
+        lifecycle: string;
+        justification: string;
+        adrReference: string;
+    }>;
+}

package/dist/schemas/adr-008-register.js

@@ -0,0 +1,71 @@
+import { createAjvInstance } from "../ajv-instance.js";
+import { PACKAGE_NAME_PATTERN } from "../constants.js";
+/**
+ * Canonical schema for the ADR-008 Core Exception Register.
+ *
+ * @see ADR-008 — Explicit Core Module Composition Exceptions
+ * @see ADR-009 — Machine-Readable Core Exception Register
+ *
+ * Each repository owns its own register instance; the schema is shared
+ * Development tooling. The register enumerates Core-to-Core dependency
+ * edges that are explicitly permitted despite the default prohibition.
+ */
+export const adr008RegisterSchema = {
+    $id: "https://comityjs.dev/schemas/adr-008-register.v1.json",
+    type: "object",
+    required: ["version", "edges"],
+    additionalProperties: false,
+    properties: {
+        version: {
+            type: "string",
+            const: "1",
+            description: "Schema version of the register document.",
+        },
+        edges: {
+            type: "array",
+            uniqueItems: true,
+            items: {
+                type: "object",
+                required: ["from", "to", "adr", "rationale"],
+                additionalProperties: false,
+                properties: {
+                    from: {
+                        type: "string",
+                        pattern: PACKAGE_NAME_PATTERN,
+                        description: "Source Core Module package name.",
+                    },
+                    to: {
+                        type: "string",
+                        pattern: PACKAGE_NAME_PATTERN,
+                        description: "Target Core Module package name.",
+                    },
+                    adr: {
+                        type: "string",
+                        pattern: "^ADR-[0-9]{3,4}.*$",
+                        description: "ADR reference approving this exception.",
+                    },
+                    rationale: {
+                        type: "string",
+                        minLength: 1,
+                        description: "Why this Core-to-Core edge is permitted.",
+                    },
+                },
+            },
+        },
+    },
+};
+/**
+ * Validates a parsed ADR-008 register document.
+ *
+ * @param document — parsed ADR-008 register
+ * @param ajv — optional pre-built Ajv instance
+ * @returns validation result
+ */
+export function validateAdr008Register(document, ajv = createAjvInstance()) {
+    const validate = ajv.compile(adr008RegisterSchema);
+    const valid = validate(document);
+    return {
+        valid: Boolean(valid),
+        errors: valid ? [] : (validate.errors ?? []),
+    };
+}

package/dist/schemas/comity-config.d.ts

@@ -0,0 +1,163 @@
+import type { Ajv, ErrorObject } from "ajv";
+/**
+ * Canonical schema for repository `comity.config.json`.
+ *
+ * The configuration holds REPOSITORY FACTS — package locations, repository
+ * type, declared exceptions. It MUST NOT silently redefine Comity-wide
+ * policy; policy belongs in the Standards and is enforced by shared tools.
+ *
+ * @see layering-policy.md (policy owner)
+ * @see ADR-007 (integration-adapter vs technology-adapter categorization)
+ */
+export declare const comityConfigSchema: {
+    $id: string;
+    type: string;
+    additionalProperties: boolean;
+    required: string[];
+    properties: {
+        repository: {
+            type: string;
+            required: string[];
+            additionalProperties: boolean;
+            properties: {
+                name: {
+                    type: string;
+                    minLength: number;
+                    description: string;
+                };
+                type: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+            };
+        };
+        packages: {
+            type: string;
+            required: string[];
+            additionalProperties: boolean;
+            properties: {
+                roots: {
+                    type: string;
+                    items: {
+                        type: string;
+                        minLength: number;
+                    };
+                    minItems: number;
+                    description: string;
+                };
+                exclude: {
+                    type: string;
+                    items: {
+                        type: string;
+                        minLength: number;
+                    };
+                    description: string;
+                };
+            };
+        };
+        validation: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                rules: {
+                    type: string;
+                    description: string;
+                    additionalProperties: {
+                        type: string;
+                    };
+                };
+                exceptions: {
+                    type: string;
+                    additionalProperties: boolean;
+                    properties: {
+                        dependencyEdges: {
+                            type: string;
+                            description: string;
+                            items: {
+                                type: string;
+                                required: string[];
+                                properties: {
+                                    from: {
+                                        type: string;
+                                    };
+                                    to: {
+                                        type: string;
+                                    };
+                                    adr: {
+                                        type: string;
+                                    };
+                                    rationale: {
+                                        type: string;
+                                    };
+                                };
+                                additionalProperties: boolean;
+                            };
+                        };
+                        layerOverrides: {
+                            type: string;
+                            description: string;
+                            items: {
+                                type: string;
+                                required: string[];
+                                properties: {
+                                    package: {
+                                        type: string;
+                                    };
+                                    layer: {
+                                        type: string;
+                                    };
+                                    adr: {
+                                        type: string;
+                                    };
+                                    rationale: {
+                                        type: string;
+                                    };
+                                };
+                                additionalProperties: boolean;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+/**
+ * Validates a parsed comity.config.json document.
+ *
+ * @param document — parsed comity.config.json
+ * @param ajv — optional pre-built Ajv instance
+ * @returns validation result
+ */
+export declare function validateComityConfig(document: unknown, ajv?: Ajv): {
+    valid: boolean;
+    errors: ErrorObject[];
+};
+export interface ComityConfig {
+    repository: {
+        name: string;
+        type: string;
+    };
+    packages: {
+        roots: string[];
+        exclude?: string[];
+    };
+    validation?: {
+        rules?: Record<string, boolean>;
+        exceptions?: {
+            dependencyEdges?: Array<{
+                from: string;
+                to: string;
+                adr: string;
+                rationale?: string;
+            }>;
+            layerOverrides?: Array<{
+                package: string;
+                layer: string;
+                adr: string;
+                rationale?: string;
+            }>;
+        };
+    };
+}

package/dist/schemas/comity-config.js

@@ -0,0 +1,122 @@
+import { createAjvInstance } from "../ajv-instance.js";
+/**
+ * Canonical schema for repository `comity.config.json`.
+ *
+ * The configuration holds REPOSITORY FACTS — package locations, repository
+ * type, declared exceptions. It MUST NOT silently redefine Comity-wide
+ * policy; policy belongs in the Standards and is enforced by shared tools.
+ *
+ * @see layering-policy.md (policy owner)
+ * @see ADR-007 (integration-adapter vs technology-adapter categorization)
+ */
+export const comityConfigSchema = {
+    $id: "https://comityjs.dev/schemas/comity-config.v1.json",
+    type: "object",
+    additionalProperties: false,
+    required: ["repository", "packages"],
+    properties: {
+        repository: {
+            type: "object",
+            required: ["name", "type"],
+            additionalProperties: false,
+            properties: {
+                name: {
+                    type: "string",
+                    minLength: 1,
+                    description: "Logical name of the repository.",
+                },
+                type: {
+                    type: "string",
+                    enum: [
+                        "development",
+                        "community",
+                        "enterprise",
+                        "third-party",
+                        "fixture",
+                    ],
+                    description: "Repository category.",
+                },
+            },
+        },
+        packages: {
+            type: "object",
+            required: ["roots"],
+            additionalProperties: false,
+            properties: {
+                roots: {
+                    type: "array",
+                    items: { type: "string", minLength: 1 },
+                    minItems: 1,
+                    description: "Workspace package roots, relative to the repository root.",
+                },
+                exclude: {
+                    type: "array",
+                    items: { type: "string", minLength: 1 },
+                    description: "Package path patterns to exclude from validation.",
+                },
+            },
+        },
+        validation: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                rules: {
+                    type: "object",
+                    description: "Repository-specific rule selection. Allowed keys: metadata, dependencies, eslint, semgrep, orchestrator.",
+                    additionalProperties: { type: "boolean" },
+                },
+                exceptions: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        dependencyEdges: {
+                            type: "array",
+                            description: "Locally-permitted dependency edges. Each entry MUST reference an ADR.",
+                            items: {
+                                type: "object",
+                                required: ["from", "to", "adr"],
+                                properties: {
+                                    from: { type: "string" },
+                                    to: { type: "string" },
+                                    adr: { type: "string" },
+                                    rationale: { type: "string" },
+                                },
+                                additionalProperties: false,
+                            },
+                        },
+                        layerOverrides: {
+                            type: "array",
+                            description: "Layer classification overrides — for transitional packages only.",
+                            items: {
+                                type: "object",
+                                required: ["package", "layer", "adr"],
+                                properties: {
+                                    package: { type: "string" },
+                                    layer: { type: "string" },
+                                    adr: { type: "string" },
+                                    rationale: { type: "string" },
+                                },
+                                additionalProperties: false,
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};
+/**
+ * Validates a parsed comity.config.json document.
+ *
+ * @param document — parsed comity.config.json
+ * @param ajv — optional pre-built Ajv instance
+ * @returns validation result
+ */
+export function validateComityConfig(document, ajv = createAjvInstance()) {
+    const validate = ajv.compile(comityConfigSchema);
+    const valid = validate(document);
+    return {
+        valid: Boolean(valid),
+        errors: valid ? [] : (validate.errors ?? []),
+    };
+}

package/dist/schemas/index.d.ts

@@ -0,0 +1,6 @@
+export type { Adr008Register } from "./adr-008-register.js";
+export type { ComityConfig } from "./comity-config.js";
+export type { PackageMetadata, ValidationResult } from "./package-metadata.js";
+export { adr008RegisterSchema, validateAdr008Register, } from "./adr-008-register.js";
+export { comityConfigSchema, validateComityConfig } from "./comity-config.js";
+export { packageMetadataSchema, validatePackageMetadata, } from "./package-metadata.js";

package/dist/schemas/index.js

@@ -0,0 +1,3 @@
+export { adr008RegisterSchema, validateAdr008Register, } from "./adr-008-register.js";
+export { comityConfigSchema, validateComityConfig } from "./comity-config.js";
+export { packageMetadataSchema, validatePackageMetadata, } from "./package-metadata.js";

package/dist/schemas/package-metadata.d.ts

@@ -0,0 +1,157 @@
+import type { Ajv, ErrorObject } from "ajv";
+/**
+ * Canonical schema for Comity package metadata.
+ *
+ * Covers both namespaces, with a name-scope ↔ layer boundary:
+ *   - `@comity/*` (runtime)     → `comity.layer` MUST be one of the six
+ *                                 runtime layers (ADR-026).
+ *   - `@comity-dev/*` (tooling) → `comity.layer` MUST be `dev-tooling`.
+ *
+ * The boundary is enforced by the `if/then/else` clause on `comity.layer`.
+ *
+ * @see ADR-026 — Architecture Validator Authoritative Classification
+ * @see layering-policy.md §2.1
+ * @see architecture-validation.md §8 (package naming, type, engines.node)
+ * @see public-api.md §3 (exports subpath rules)
+ *
+ * This schema is the authoritative machine-readable definition of what every
+ * Comity package manifest MUST contain. Repositories consume this schema via
+ * the shared `comity-validate` orchestrator; they do not redefine it.
+ */
+export declare const packageMetadataSchema: {
+    $id: string;
+    type: string;
+    required: string[];
+    additionalProperties: boolean;
+    properties: {
+        name: {
+            type: string;
+            pattern: string;
+            description: string;
+        };
+        version: {
+            type: string;
+            pattern: string;
+            description: string;
+        };
+        type: {
+            const: string;
+            description: string;
+        };
+        license: {
+            type: string;
+            minLength: number;
+            description: string;
+        };
+        engines: {
+            type: string;
+            required: string[];
+            properties: {
+                node: {
+                    type: string;
+                    pattern: string;
+                    description: string;
+                };
+            };
+            additionalProperties: boolean;
+        };
+        comity: {
+            type: string;
+            description: string;
+            required: string[];
+            properties: {
+                layer: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                implements: {
+                    type: string;
+                    pattern: string;
+                    description: string;
+                };
+            };
+            additionalProperties: boolean;
+        };
+        exports: {
+            type: string;
+            description: string;
+            additionalProperties: boolean;
+        };
+        typesVersions: {
+            type: string;
+            description: string;
+            additionalProperties: boolean;
+        };
+    };
+    allOf: ({
+        if: {
+            properties: {
+                name: {
+                    pattern: string;
+                };
+            };
+            required: string[];
+        };
+        then: {
+            properties: {
+                comity: {
+                    properties: {
+                        layer: {
+                            enum: string[];
+                            const?: never;
+                        };
+                    };
+                };
+            };
+        };
+    } | {
+        if: {
+            properties: {
+                name: {
+                    pattern: string;
+                };
+            };
+            required: string[];
+        };
+        then: {
+            properties: {
+                comity: {
+                    properties: {
+                        layer: {
+                            const: string;
+                            enum?: never;
+                        };
+                    };
+                };
+            };
+        };
+    })[];
+};
+/**
+ * Validates a parsed package.json against the canonical schema.
+ *
+ * @param manifest — parsed package.json object
+ * @param ajv — optional pre-built Ajv instance
+ * @returns validation result
+ */
+export declare function validatePackageMetadata(manifest: unknown, ajv?: Ajv): ValidationResult;
+export interface PackageMetadata {
+    name: string;
+    version: string;
+    type: "module";
+    license: string;
+    engines: {
+        node: string;
+    };
+    comity?: {
+        layer: string;
+        implements?: string;
+    };
+    exports: Record<string, unknown>;
+    typesVersions?: Record<string, unknown>;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ErrorObject[];
+}

package/dist/schemas/package-metadata.js

@@ -0,0 +1,147 @@
+import { createAjvInstance } from "../ajv-instance.js";
+import { MIN_NODE_VERSION, PACKAGE_NAME_PATTERN, RUNTIME_LAYERS, VALID_LAYERS, } from "../constants.js";
+/**
+ * Canonical schema for Comity package metadata.
+ *
+ * Covers both namespaces, with a name-scope ↔ layer boundary:
+ *   - `@comity/*` (runtime)     → `comity.layer` MUST be one of the six
+ *                                 runtime layers (ADR-026).
+ *   - `@comity-dev/*` (tooling) → `comity.layer` MUST be `dev-tooling`.
+ *
+ * The boundary is enforced by the `if/then/else` clause on `comity.layer`.
+ *
+ * @see ADR-026 — Architecture Validator Authoritative Classification
+ * @see layering-policy.md §2.1
+ * @see architecture-validation.md §8 (package naming, type, engines.node)
+ * @see public-api.md §3 (exports subpath rules)
+ *
+ * This schema is the authoritative machine-readable definition of what every
+ * Comity package manifest MUST contain. Repositories consume this schema via
+ * the shared `comity-validate` orchestrator; they do not redefine it.
+ */
+export const packageMetadataSchema = {
+    $id: "https://comityjs.dev/schemas/package-metadata.v1.json",
+    type: "object",
+    required: ["name", "version", "type", "license", "engines", "exports"],
+    additionalProperties: true,
+    properties: {
+        name: {
+            type: "string",
+            pattern: PACKAGE_NAME_PATTERN,
+            description: "Package name MUST follow the `@comity/<kebab-case-name>` or `@comity-dev/<kebab-case-name>` convention.",
+        },
+        version: {
+            type: "string",
+            pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+",
+            description: "Semantic version of the package.",
+        },
+        type: {
+            const: "module",
+            description: "Package type MUST be `module` (ESM).",
+        },
+        license: {
+            type: "string",
+            minLength: 1,
+            description: "Package license MUST be declared.",
+        },
+        engines: {
+            type: "object",
+            required: ["node"],
+            properties: {
+                node: {
+                    type: "string",
+                    pattern: `>=${MIN_NODE_VERSION}`,
+                    description: `Node.js engine MUST be >= ${MIN_NODE_VERSION}.`,
+                },
+            },
+            additionalProperties: true,
+        },
+        comity: {
+            type: "object",
+            description: "Comity metadata — authoritative source of package classification.",
+            required: ["layer"],
+            properties: {
+                layer: {
+                    type: "string",
+                    enum: [...VALID_LAYERS],
+                    description: "Architectural layer. Runtime `@comity/*` packages MUST use one of the six runtime layers (primitives, kernel, composition, core, technology-adapter, integration-adapter). Development `@comity-dev/*` packages MUST use `dev-tooling`.",
+                },
+                implements: {
+                    // Per ADR-026, `implements` is a single Core Module name. The
+                    // legacy validator reports a violation when this is an array;
+                    // we keep the schema strict and surface the violation through
+                    // the metadata check.
+                    type: "string",
+                    pattern: PACKAGE_NAME_PATTERN,
+                    description: "Single Core Module that this Adapter implements (technology-adapter and integration-adapter).",
+                },
+            },
+            additionalProperties: false,
+        },
+        exports: {
+            type: "object",
+            description: "Declared public subpaths. Forbidden subpaths (utils, helpers, shared, internal, lazy) are validated by ESLint.",
+            additionalProperties: true,
+        },
+        typesVersions: {
+            type: "object",
+            description: "TypeScript typesVersions MUST be consistent with declared exports.",
+            additionalProperties: true,
+        },
+    },
+    // Name-scope ↔ layer boundary. The runtime six-layer model is
+    // preserved; `dev-tooling` is reserved for `@comity-dev/*`.
+    // Implemented at the manifest level so `name` and `comity.layer`
+    // can be evaluated as siblings.
+    allOf: [
+        {
+            if: {
+                properties: {
+                    name: { pattern: "^@comity/" },
+                },
+                required: ["name"],
+            },
+            then: {
+                properties: {
+                    comity: {
+                        properties: {
+                            layer: { enum: [...RUNTIME_LAYERS] },
+                        },
+                    },
+                },
+            },
+        },
+        {
+            if: {
+                properties: {
+                    name: { pattern: "^@comity-dev/" },
+                },
+                required: ["name"],
+            },
+            then: {
+                properties: {
+                    comity: {
+                        properties: {
+                            layer: { const: "dev-tooling" },
+                        },
+                    },
+                },
+            },
+        },
+    ],
+};
+/**
+ * Validates a parsed package.json against the canonical schema.
+ *
+ * @param manifest — parsed package.json object
+ * @param ajv — optional pre-built Ajv instance
+ * @returns validation result
+ */
+export function validatePackageMetadata(manifest, ajv = createAjvInstance()) {
+    const validate = ajv.compile(packageMetadataSchema);
+    const valid = validate(manifest);
+    return {
+        valid: Boolean(valid),
+        errors: valid ? [] : (validate.errors ?? []),
+    };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@comity-dev/schemas",
+  "version": "0.1.0",
+  "description": "Reusable JSON Schema definitions for Comity package metadata, ADR-008 register, and repository configuration. Development tooling.",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "comity": {
+    "layer": "dev-tooling"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "default": "./dist/schemas/index.js"
+    }
+  },
+  "files": [
+    "./dist"
+  ],
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}