@contractspec/lib.contracts-spec 2.0.0

package/dist/tests/runner.d.ts

@@ -0,0 +1,38 @@
+import { OperationSpecRegistry } from '../index';
+import type { HandlerCtx } from '../types';
+import type { Assertion, TestScenario, TestSpec } from './spec';
+export interface ScenarioRunResult {
+    scenario: TestScenario;
+    status: 'passed' | 'failed';
+    error?: Error;
+    assertionResults: AssertionResult[];
+}
+export interface AssertionResult {
+    assertion: Assertion;
+    status: 'passed' | 'failed';
+    message?: string;
+}
+export interface TestRunResult {
+    spec: TestSpec;
+    scenarios: ScenarioRunResult[];
+    passed: number;
+    failed: number;
+}
+export interface TestRunnerConfig {
+    registry: OperationSpecRegistry;
+    createContext?: () => HandlerCtx | Promise<HandlerCtx>;
+    beforeEach?: (scenario: TestScenario) => void | Promise<void>;
+    afterEach?: (scenario: TestScenario, result: ScenarioRunResult) => void | Promise<void>;
+}
+export declare class TestRunner {
+    private readonly config;
+    constructor(config: TestRunnerConfig);
+    run(spec: TestSpec): Promise<TestRunResult>;
+    private runScenario;
+    private createContext;
+    private executeOperation;
+    private evaluateAssertion;
+    private evaluateOutputAssertion;
+    private evaluateErrorAssertion;
+    private evaluateEventsAssertion;
+}

package/dist/tests/runner.js

@@ -0,0 +1,189 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/tests/runner.ts
+import { deepStrictEqual } from "assert";
+
+class TestRunner {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  async run(spec) {
+    const scenarios = [];
+    let passed = 0;
+    let failed = 0;
+    for (const scenario of spec.scenarios) {
+      await this.config.beforeEach?.(scenario);
+      const result = await this.runScenario(spec, scenario);
+      scenarios.push(result);
+      if (result.status === "passed")
+        passed += 1;
+      else
+        failed += 1;
+      await this.config.afterEach?.(scenario, result);
+    }
+    return {
+      spec,
+      scenarios,
+      passed,
+      failed
+    };
+  }
+  async runScenario(spec, scenario) {
+    const assertionResults = [];
+    try {
+      const context = await this.createContext();
+      const fixtures = [...spec.fixtures ?? [], ...scenario.given ?? []];
+      const events = [];
+      for (const fixture of fixtures) {
+        await this.executeOperation(fixture, context, events);
+      }
+      const actionResult = await this.executeOperation(scenario.when, context, events);
+      const assertions = scenario.then ?? [];
+      for (const assertion of assertions) {
+        const assertionResult = this.evaluateAssertion(assertion, actionResult, events);
+        assertionResults.push(assertionResult);
+      }
+      const hasFailure = assertionResults.some((assertion) => assertion.status === "failed");
+      return {
+        scenario,
+        status: hasFailure ? "failed" : "passed",
+        assertionResults
+      };
+    } catch (error) {
+      return {
+        scenario,
+        status: "failed",
+        error,
+        assertionResults
+      };
+    }
+  }
+  async createContext() {
+    const baseCtx = await this.config.createContext?.() ?? {};
+    return { ...baseCtx };
+  }
+  async executeOperation(action, baseCtx, recordedEvents) {
+    const ctx = {
+      ...baseCtx,
+      eventPublisher: async (event) => {
+        recordedEvents.push({
+          key: event.key,
+          version: event.version,
+          payload: event.payload
+        });
+        await baseCtx.eventPublisher?.(event);
+      }
+    };
+    try {
+      const output = await this.config.registry.execute(action.operation.key, action.operation.version, action.input ?? null, ctx);
+      return { output, events: recordedEvents };
+    } catch (error) {
+      return { error, events: recordedEvents };
+    }
+  }
+  evaluateAssertion(assertion, result, events) {
+    switch (assertion.type) {
+      case "expectOutput":
+        return this.evaluateOutputAssertion(assertion, result);
+      case "expectError":
+        return this.evaluateErrorAssertion(assertion, result);
+      case "expectEvents":
+        return this.evaluateEventsAssertion(assertion, events);
+      default:
+        return {
+          assertion,
+          status: "failed",
+          message: `Unknown assertion type ${assertion.type}`
+        };
+    }
+  }
+  evaluateOutputAssertion(assertion, result) {
+    if (result.error) {
+      return {
+        assertion,
+        status: "failed",
+        message: `Expected output but operation threw error: ${result.error.message}`
+      };
+    }
+    try {
+      deepStrictEqual(result.output, assertion.match);
+      return { assertion, status: "passed" };
+    } catch (error) {
+      return {
+        assertion,
+        status: "failed",
+        message: error instanceof Error ? error.message : "Output assertion failed"
+      };
+    }
+  }
+  evaluateErrorAssertion(assertion, result) {
+    if (!result.error) {
+      return {
+        assertion,
+        status: "failed",
+        message: "Expected an error but operation completed successfully"
+      };
+    }
+    if (assertion.messageIncludes && !result.error.message.includes(assertion.messageIncludes)) {
+      return {
+        assertion,
+        status: "failed",
+        message: `Error message "${result.error.message}" did not include expected substring "${assertion.messageIncludes}"`
+      };
+    }
+    return { assertion, status: "passed" };
+  }
+  evaluateEventsAssertion(assertion, events) {
+    const failures = [];
+    for (const expected of assertion.events) {
+      const matches = events.filter((event) => event.key === expected.key && event.version === expected.version);
+      const count = matches.length;
+      if (typeof expected.min === "number" && count < expected.min || typeof expected.max === "number" && count > expected.max) {
+        failures.push(`Event ${expected.key}.v${expected.version} occurred ${count} times (expected ${expected.min ?? 0} - ${expected.max ?? "\u221E"})`);
+      } else if (typeof expected.min === "undefined" && typeof expected.max === "undefined" && count === 0) {
+        failures.push(`Event ${expected.key}.v${expected.version} did not occur`);
+      }
+    }
+    if (failures.length > 0) {
+      return {
+        assertion,
+        status: "failed",
+        message: failures.join("; ")
+      };
+    }
+    return { assertion, status: "passed" };
+  }
+}
+export {
+  TestRunner
+};

package/dist/tests/runner.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/spec.d.ts

@@ -0,0 +1,82 @@
+import type { OwnerShipMeta } from '../ownership';
+import type { OptionalVersionedSpecRef } from '../versioning';
+/**
+ * Reference to an operation to be tested.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+export type OperationTargetRef = OptionalVersionedSpecRef;
+/**
+ * Reference to a workflow to be tested.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+export type WorkflowTargetRef = OptionalVersionedSpecRef;
+export type TestTarget = {
+    type: 'operation';
+    operation: OperationTargetRef;
+} | {
+    type: 'workflow';
+    workflow: WorkflowTargetRef;
+};
+export interface Fixture {
+    description?: string;
+    operation: OperationTargetRef;
+    input?: unknown;
+}
+export interface Action {
+    operation: OperationTargetRef;
+    input?: unknown;
+}
+export interface ExpectOutputAssertion {
+    type: 'expectOutput';
+    match: unknown;
+}
+export interface ExpectErrorAssertion {
+    type: 'expectError';
+    messageIncludes?: string;
+}
+export interface ExpectedEvent {
+    key: string;
+    version: string;
+    min?: number;
+    max?: number;
+}
+export interface ExpectEventsAssertion {
+    type: 'expectEvents';
+    events: ExpectedEvent[];
+}
+export type Assertion = ExpectOutputAssertion | ExpectErrorAssertion | ExpectEventsAssertion;
+export interface TestScenario {
+    key: string;
+    description?: string;
+    given?: Fixture[];
+    when: Action;
+    then?: Assertion[];
+}
+export interface CoverageRequirement {
+    statements?: number;
+    branches?: number;
+    functions?: number;
+    lines?: number;
+    mutations?: number;
+}
+export type TestSpecMeta = OwnerShipMeta;
+export interface TestSpec {
+    meta: TestSpecMeta;
+    target: TestTarget;
+    fixtures?: Fixture[];
+    scenarios: TestScenario[];
+    coverage?: CoverageRequirement;
+}
+/**
+ * Reference to a test spec.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+export type TestSpecRef = OptionalVersionedSpecRef;
+export declare class TestRegistry {
+    private readonly items;
+    register(spec: TestSpec): this;
+    list(): TestSpec[];
+    get(name: string, version?: string): TestSpec | undefined;
+}
+export declare function makeTestKey(meta: TestSpecMeta): string;
+export declare function defineTestSpec(spec: TestSpec): TestSpec;

package/dist/tests/spec.js

@@ -0,0 +1,74 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/tests/spec.ts
+import { compareVersions } from "compare-versions";
+var testKey = (meta) => `${meta.key}.v${meta.version}`;
+
+class TestRegistry {
+  items = new Map;
+  register(spec) {
+    const key = testKey(spec.meta);
+    if (this.items.has(key)) {
+      throw new Error(`Duplicate TestSpec registration for ${key}`);
+    }
+    this.items.set(key, spec);
+    return this;
+  }
+  list() {
+    return [...this.items.values()];
+  }
+  get(name, version) {
+    if (version != null) {
+      return this.items.get(`${name}.v${version}`);
+    }
+    let latest;
+    for (const spec of this.items.values()) {
+      if (spec.meta.key !== name)
+        continue;
+      if (!latest || compareVersions(spec.meta.version, latest.meta.version) > 0) {
+        latest = spec;
+      }
+    }
+    return latest;
+  }
+}
+function makeTestKey(meta) {
+  return testKey(meta);
+}
+function defineTestSpec(spec) {
+  return spec;
+}
+export {
+  makeTestKey,
+  defineTestSpec,
+  TestRegistry
+};

package/dist/tests/spec.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/themes.d.ts

@@ -0,0 +1,50 @@
+import type { OwnerShipMeta } from './ownership';
+import { SpecContractRegistry } from './registry';
+import type { VersionedSpecRef } from './versioning';
+/** Scope at which a theme can be applied. */
+export type ThemeScope = 'global' | 'tenant' | 'user';
+export interface ThemeToken<T> {
+    value: T;
+    description?: string;
+}
+export interface ThemeTokens {
+    colors?: Record<string, ThemeToken<string>>;
+    radii?: Record<string, ThemeToken<number>>;
+    space?: Record<string, ThemeToken<number>>;
+    typography?: Record<string, ThemeToken<number>>;
+    shadows?: Record<string, ThemeToken<string>>;
+    motion?: Record<string, ThemeToken<string>>;
+}
+export interface ComponentVariantDefinition {
+    props?: Record<string, unknown>;
+    tokens?: ThemeTokens;
+}
+export interface ComponentVariantSpec {
+    component: string;
+    variants: Record<string, ComponentVariantDefinition>;
+}
+export interface ThemeOverride {
+    scope: ThemeScope;
+    target: string;
+    tokens?: ThemeTokens;
+    components?: ComponentVariantSpec[];
+}
+export interface ThemeMeta extends OwnerShipMeta {
+    extends?: ThemeRef;
+    scopes?: ThemeScope[];
+}
+export interface ThemeSpec {
+    meta: ThemeMeta;
+    tokens: ThemeTokens;
+    components?: ComponentVariantSpec[];
+    overrides?: ThemeOverride[];
+}
+/**
+ * Reference to a theme spec.
+ * Uses key and version to identify a specific theme.
+ */
+export type ThemeRef = VersionedSpecRef;
+export declare class ThemeRegistry extends SpecContractRegistry<'theme', ThemeSpec> {
+    constructor(items?: ThemeSpec[]);
+}
+export declare function makeThemeRef(spec: ThemeSpec): ThemeRef;

package/dist/themes.js

@@ -0,0 +1,225 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/registry-utils.ts
+var exports_registry_utils = {};
+__export(exports_registry_utils, {
+  groupByToArray: () => groupByToArray,
+  groupByMultiple: () => groupByMultiple,
+  groupBy: () => groupBy,
+  getUniqueTags: () => getUniqueTags,
+  getUniqueOwners: () => getUniqueOwners,
+  getUniqueDomains: () => getUniqueDomains,
+  filterBy: () => filterBy,
+  GroupingStrategies: () => GroupingStrategies
+});
+function filterBy(items, filter) {
+  return items.filter((item) => {
+    if (filter.tags?.length) {
+      const hasMatchingTag = filter.tags.some((tag) => item.meta.tags?.includes(tag));
+      if (!hasMatchingTag)
+        return false;
+    }
+    if (filter.owners?.length) {
+      const hasMatchingOwner = filter.owners.some((owner) => item.meta.owners?.includes(owner));
+      if (!hasMatchingOwner)
+        return false;
+    }
+    if (filter.stability?.length) {
+      if (!filter.stability.includes(item.meta.stability ?? "stable")) {
+        return false;
+      }
+    }
+    if (filter.domain) {
+      const itemDomain = GroupingStrategies.byDomain(item);
+      if (itemDomain !== filter.domain)
+        return false;
+    }
+    if (filter.keyPattern) {
+      const name = item.meta.key ?? item.meta.key ?? "";
+      const pattern = filter.keyPattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+      const regex = new RegExp(`^${pattern}$`, "i");
+      if (!regex.test(name))
+        return false;
+    }
+    return true;
+  });
+}
+function groupBy(items, keyFn) {
+  const groups = new Map;
+  for (const item of items) {
+    const key = keyFn(item);
+    const existing = groups.get(key);
+    if (existing) {
+      existing.push(item);
+    } else {
+      groups.set(key, [item]);
+    }
+  }
+  return groups;
+}
+function groupByToArray(items, keyFn) {
+  const map = groupBy(items, keyFn);
+  return Array.from(map.entries()).map(([key, items2]) => ({ key, items: items2 }));
+}
+function groupByMultiple(items, keysFn) {
+  const groups = new Map;
+  for (const item of items) {
+    const keys = keysFn(item);
+    for (const key of keys) {
+      const existing = groups.get(key);
+      if (existing) {
+        existing.push(item);
+      } else {
+        groups.set(key, [item]);
+      }
+    }
+  }
+  return groups;
+}
+function getUniqueTags(items) {
+  const tags = new Set;
+  for (const item of items) {
+    for (const tag of item.meta.tags ?? []) {
+      tags.add(tag);
+    }
+  }
+  return Array.from(tags).sort();
+}
+function getUniqueOwners(items) {
+  const owners = new Set;
+  for (const item of items) {
+    for (const owner of item.meta.owners ?? []) {
+      owners.add(owner);
+    }
+  }
+  return Array.from(owners).sort();
+}
+function getUniqueDomains(items) {
+  const domains = new Set;
+  for (const item of items) {
+    domains.add(GroupingStrategies.byDomain(item));
+  }
+  return Array.from(domains).sort();
+}
+var GroupingStrategies;
+var init_registry_utils = __esm(() => {
+  GroupingStrategies = {
+    byTag: (item) => item.meta.tags?.[0] ?? "untagged",
+    byAllTags: (item) => item.meta.tags?.length ? item.meta.tags : ["untagged"],
+    byOwner: (item) => item.meta.owners?.[0] ?? "unowned",
+    byDomain: (item) => {
+      const name = item.meta.key ?? item.meta.key ?? "";
+      return name.split(".")[0] ?? "default";
+    },
+    byStability: (item) => item.meta.stability ?? "stable",
+    byUrlPath: (level) => (item) => {
+      if (!item.path)
+        return "root";
+      const segments = item.path.split("/").filter(Boolean);
+      return segments.slice(0, level).join("/") || "root";
+    }
+  };
+});
+
+// src/registry.ts
+init_registry_utils();
+import { compareVersions } from "compare-versions";
+var keyOfSpecContract = (spec) => `${spec.meta.key}.v${spec.meta.version}`;
+
+class SpecContractRegistry {
+  contractType;
+  items = new Map;
+  constructor(contractType, items) {
+    this.contractType = contractType;
+    if (items) {
+      items.forEach((p) => this.register(p));
+    }
+  }
+  register(p) {
+    const key = keyOfSpecContract(p);
+    if (this.items.has(key))
+      throw new Error(`Duplicate contract \`${this.contractType}\` ${key}`);
+    this.items.set(key, p);
+    return this;
+  }
+  count() {
+    return this.items.size;
+  }
+  list() {
+    return [...this.items.values()];
+  }
+  get(key, version) {
+    if (version != null)
+      return this.items.get(`${key}.v${version}`);
+    let candidate;
+    for (const [k, p] of this.items.entries()) {
+      if (!k.startsWith(`${key}.v`))
+        continue;
+      if (!candidate || compareVersions(p.meta.version, candidate.meta.version) > 0) {
+        candidate = p;
+      }
+    }
+    return candidate;
+  }
+  has(key, version) {
+    return !!this.get(key, version);
+  }
+  filter(criteria) {
+    return filterBy(this.list(), criteria);
+  }
+  listByTag(tag) {
+    return this.list().filter((p) => p.meta.tags?.includes(tag));
+  }
+  listByOwner(owner) {
+    return this.list().filter((p) => p.meta.owners?.includes(owner));
+  }
+  groupBy(keyFn) {
+    return groupBy(this.list(), keyFn);
+  }
+  getUniqueTags() {
+    return getUniqueTags(this.list());
+  }
+}
+
+// src/themes.ts
+class ThemeRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("theme", items);
+  }
+}
+function makeThemeRef(spec) {
+  return { key: spec.meta.key, version: spec.meta.version };
+}
+export {
+  makeThemeRef,
+  ThemeRegistry
+};

package/dist/themes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/translations/catalog.d.ts

@@ -0,0 +1,25 @@
+export type Locale = string;
+export type MessageKey = string;
+export interface TranslationEntry {
+    key: MessageKey;
+    locale: Locale;
+    value: string;
+    context?: string;
+}
+export interface TranslationCatalogMeta {
+    key: string;
+    version: string;
+    description?: string;
+}
+export interface PlatformTranslationCatalog {
+    meta: TranslationCatalogMeta;
+    defaultLocale: Locale;
+    supportedLocales: Locale[];
+    entries: TranslationEntry[];
+}
+export interface BlueprintTranslationCatalog {
+    meta: TranslationCatalogMeta;
+    defaultLocale: Locale;
+    supportedLocales: Locale[];
+    entries: TranslationEntry[];
+}

package/dist/translations/catalog.js

@@ -0,0 +1 @@
+// @bun