@manya-os/contracts 1.0.0

package/dist/types/types.d.ts

@@ -0,0 +1,215 @@
+/**
+ * @manya-os/contracts — shared type definitions.
+ *
+ * Defines every public type used across the contracts package: schema
+ * primitives, manifests, semver versions, API contracts, schema diffs,
+ * boundary policies, and validation reports.
+ *
+ * Copyright 2024 Manya Hael Foundation. All rights reserved.
+ * Licensed under the Apache License, Version 2.0.
+ */
+/**
+ * The set of schema type names supported by the contracts schema language.
+ *
+ * - `string` / `number` / `boolean` — JSON primitives.
+ * - `null` — the explicit null value.
+ * - `object` — a nested record (use `fields` on the `SchemaField`).
+ * - `array` — a homogeneous list (use `of` on the `SchemaField`).
+ * - `enum` — one of a fixed set of values (use `enum` on the `SchemaField`).
+ * - `ref` — a reference to another `InterfaceSchema` by name (use `ref`).
+ * - `union` — one of several types (use `oneOf`).
+ * - `intersection` — all of several types (use `allOf`).
+ */
+export type SchemaType = 'string' | 'number' | 'boolean' | 'null' | 'object' | 'array' | 'enum' | 'ref' | 'union' | 'intersection';
+/**
+ * A single field on an `InterfaceSchema`. The base shape matches the public
+ * spec; the extension fields (`of`, `ref`, `oneOf`, `allOf`, `fields`) are
+ * used to express composite types and are ignored when not applicable.
+ */
+export interface SchemaField {
+    /** Field name. */
+    name: string;
+    /** Field type discriminator. */
+    type: SchemaType;
+    /** Whether the field must be present (and non-`undefined`). */
+    required: boolean;
+    /** Human-readable description. */
+    description?: string;
+    /** Default value applied when the field is missing and not required. */
+    default?: unknown;
+    /** Allowed values for `enum` fields. */
+    enum?: unknown[];
+    /** Element type for `array` fields. */
+    of?: SchemaField;
+    /** Referenced schema name for `ref` fields. */
+    ref?: string;
+    /** Member types for `union` fields. */
+    oneOf?: SchemaField[];
+    /** Member types for `intersection` fields. */
+    allOf?: SchemaField[];
+    /** Nested fields for `object` fields. */
+    fields?: SchemaField[];
+}
+/** A named, versioned interface schema. */
+export interface InterfaceSchema {
+    /** Schema name (PascalCase by convention). */
+    name: string;
+    /** Schema version (semver). */
+    version: string;
+    /** Field list. */
+    fields: SchemaField[];
+    /** Human-readable description. */
+    description?: string;
+}
+/**
+ * A parsed semantic version. Follows semver.org: `MAJOR.MINOR.PATCH` with an
+ * optional `-prerelease` suffix.
+ */
+export interface SemverVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease?: string;
+}
+/** A package manifest describing name, version, dependencies, and surface. */
+export interface Manifest {
+    /** Package name (lowercase, scoped or unscoped). */
+    name: string;
+    /** Semver version string. */
+    version: string;
+    /** Map of dependency name → version range. */
+    dependencies?: Record<string, string>;
+    /** Exported symbols or paths. */
+    exports?: string[];
+    /** Imported symbols or paths. */
+    imports?: string[];
+    /** Declared capabilities (e.g. `crypto`, `network`, `filesystem`). */
+    capabilities?: string[];
+}
+/** A single validation error with a stable `code` for programmatic handling. */
+export interface ValidationError {
+    /** Dotted path to the offending field (e.g. `user.address.zip`). */
+    path: string;
+    /** Human-readable error message. */
+    message: string;
+    /** Stable machine code (often an `*Error` code from `errors.ts`). */
+    code: string;
+    /** Expected type or shape. */
+    expected?: string;
+    /** Actual type or value observed. */
+    actual?: string;
+}
+/** The result of any validation routine. */
+export interface ValidationResult {
+    /** Whether validation succeeded. */
+    valid: boolean;
+    /** Errors produced during validation (empty iff `valid === true`). */
+    errors: ValidationError[];
+}
+/**
+ * A breaking change detected by `checkBackwardCompat`.
+ *
+ * - `field_removed` — a field that existed in the old schema is gone.
+ * - `type_changed` — a field's type changed incompatibly.
+ * - `required_added` — a new required field was added (callers can't satisfy it).
+ * - `enum_value_removed` — an `enum` field lost a value.
+ */
+export interface BreakingChange {
+    type: 'field_removed' | 'type_changed' | 'required_added' | 'enum_value_removed';
+    /** Field path the change applies to. */
+    field?: string;
+    /** Previous value/type description. */
+    from?: string;
+    /** New value/type description. */
+    to?: string;
+}
+/**
+ * An API endpoint contract.
+ */
+export interface ApiEndpoint {
+    /** HTTP method. */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** Route path (e.g. `/users/:id`). */
+    path: string;
+    /** Optional request body schema. */
+    requestSchema?: InterfaceSchema;
+    /** Response body schema (required). */
+    responseSchema: InterfaceSchema;
+}
+/** A named, versioned collection of API endpoints. */
+export interface ApiContract {
+    /** Contract name. */
+    name: string;
+    /** Contract version (semver). */
+    version: string;
+    /** Endpoint list. */
+    endpoints: ApiEndpoint[];
+}
+/**
+ * A diff between two schemas. `removed` is a list of field names; `added` and
+ * `changed` carry full field descriptors.
+ */
+export interface SchemaDiff {
+    /** Fields present in `newSchema` but not `oldSchema`. */
+    added: SchemaField[];
+    /** Field names present in `oldSchema` but not `newSchema`. */
+    removed: string[];
+    /** Fields present in both whose definition changed. */
+    changed: Array<{
+        field: string;
+        from: SchemaField;
+        to: SchemaField;
+    }>;
+}
+/** A conflict between two schema versions of the same field. */
+export interface SchemaConflict {
+    /** Field path that conflicts. */
+    field: string;
+    /** Local field type name. */
+    localType: string;
+    /** Remote field type name. */
+    remoteType: string;
+    /** How the conflict was (or should be) resolved. */
+    resolution: 'local' | 'remote' | 'manual';
+}
+/** A single boundary rule: `from` may call `to` iff `allowed === true`. */
+export interface BoundaryRule {
+    /** Caller module name. */
+    from: string;
+    /** Callee module name. */
+    to: string;
+    /** Whether the call is allowed. */
+    allowed: boolean;
+    /** Optional human-readable reason. */
+    reason?: string;
+}
+/** A named boundary policy: a list of rules plus a default-allow flag. */
+export interface BoundaryPolicy {
+    /** Policy name. */
+    name: string;
+    /** Rule list. */
+    rules: BoundaryRule[];
+    /** Default action when no rule matches. */
+    defaultAllow: boolean;
+}
+/** A single section in a `ValidationReport`. */
+export interface ValidationReportSection {
+    /** Section name (e.g. `manifest`, `schema`, `compatibility`). */
+    name: string;
+    /** Whether this section passed. */
+    passed: boolean;
+    /** Errors produced by this section. */
+    errors: ValidationError[];
+}
+/** A complete validation report. */
+export interface ValidationReport {
+    /** Report name (typically the artifact under validation). */
+    name: string;
+    /** Overall pass/fail (true iff every section passed). */
+    passed: boolean;
+    /** Per-section results. */
+    sections: ValidationReportSection[];
+    /** ISO 8601 timestamp. */
+    generatedAt: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@manya-os/contracts",
+  "version": "1.0.0",
+  "description": "Universal contract and schema validation for the MANYA Intelligence OS — interface schemas, manifests, semver compatibility, API contracts, schema sync, boundary enforcement, and validation reports.",
+  "main": "dist/cjs/index.js",
+  "types": "dist/types/index.d.ts",
+  "scripts": {
+    "build": "node ../../scripts/build-package.js contracts",
+    "test": "jest",
+    "clean": "rm -rf dist build node_modules",
+    "build:types": "node ../../scripts/build-types.js contracts",
+    "build:bundle": "node ../../scripts/build-package.js contracts --no-types && node ../../scripts/build-types.js contracts"
+  },
+  "keywords": [
+    "manya",
+    "contracts",
+    "schema",
+    "validation",
+    "manifest",
+    "semver",
+    "compatibility",
+    "api",
+    "boundaries",
+    "interface"
+  ],
+  "author": "Uviwe Menyiwe (Azura Daemon) <foundation@manyahael.org>",
+  "license": "Apache-2.0",
+  "dependencies": {},
+  "devDependencies": {},
+  "module": "dist/esm/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "require": "./dist/cjs/index.js",
+      "import": "./dist/esm/index.mjs",
+      "default": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ]
+}