@contractspec/lib.contracts 0.0.0-canary-20260119224949 → 0.0.0-canary-20260128200020

package/dist/capabilities/validation.js

@@ -0,0 +1,141 @@
+//#region src/capabilities/validation.ts
+/**
+* Validates bidirectional consistency between capabilities and their surfaces.
+*
+* Checks:
+* 1. Forward validation: Every surface ref in capability `provides` exists
+* 2. Reverse validation: Every spec with `capability` field is in that capability's `provides`
+*
+* @param deps - Registries to validate against
+* @returns Validation result with errors and warnings
+*
+* @example
+* ```typescript
+* const result = validateCapabilityConsistency({
+*   capabilities: capabilityRegistry,
+*   operations: operationRegistry,
+*   events: eventRegistry,
+* });
+*
+* if (!result.valid) {
+*   console.error('Capability validation failed:', result.errors);
+* }
+* ```
+*/
+function validateCapabilityConsistency(deps) {
+	const errors = [];
+	const warnings = [];
+	for (const capability of deps.capabilities.list()) {
+		const capKey = `${capability.meta.key}.v${capability.meta.version}`;
+		for (const surface of capability.provides ?? []) if (!checkSurfaceExists(deps, surface.surface, surface.key)) errors.push({
+			type: "missing_surface_spec",
+			message: `Capability "${capKey}" provides ${surface.surface} "${surface.key}" but spec not found`,
+			capabilityKey: capKey,
+			surface: surface.surface,
+			specKey: surface.key
+		});
+	}
+	if (deps.operations) {
+		for (const op of deps.operations.list()) if (op.capability) {
+			const capSpec = deps.capabilities.get(op.capability.key, op.capability.version);
+			if (!capSpec) errors.push({
+				type: "capability_not_found",
+				message: `Operation "${op.meta.key}" references capability "${op.capability.key}.v${op.capability.version}" but capability not found`,
+				specKey: op.meta.key,
+				capabilityKey: `${op.capability.key}.v${op.capability.version}`,
+				surface: "operation"
+			});
+			else if (!capSpec.provides?.some((p) => p.surface === "operation" && p.key === op.meta.key)) errors.push({
+				type: "surface_not_in_provides",
+				message: `Operation "${op.meta.key}" claims capability "${op.capability.key}.v${op.capability.version}" but not in capability's provides`,
+				specKey: op.meta.key,
+				capabilityKey: `${op.capability.key}.v${op.capability.version}`,
+				surface: "operation"
+			});
+		}
+	}
+	if (deps.events) {
+		for (const event of deps.events.list()) if (event.capability) {
+			const capSpec = deps.capabilities.get(event.capability.key, event.capability.version);
+			if (!capSpec) errors.push({
+				type: "capability_not_found",
+				message: `Event "${event.meta.key}" references capability "${event.capability.key}.v${event.capability.version}" but capability not found`,
+				specKey: event.meta.key,
+				capabilityKey: `${event.capability.key}.v${event.capability.version}`,
+				surface: "event"
+			});
+			else if (!capSpec.provides?.some((p) => p.surface === "event" && p.key === event.meta.key)) errors.push({
+				type: "surface_not_in_provides",
+				message: `Event "${event.meta.key}" claims capability "${event.capability.key}.v${event.capability.version}" but not in capability's provides`,
+				specKey: event.meta.key,
+				capabilityKey: `${event.capability.key}.v${event.capability.version}`,
+				surface: "event"
+			});
+		}
+	}
+	if (deps.presentations) {
+		for (const pres of deps.presentations.list()) if (pres.capability) {
+			const capSpec = deps.capabilities.get(pres.capability.key, pres.capability.version);
+			if (!capSpec) errors.push({
+				type: "capability_not_found",
+				message: `Presentation "${pres.meta.key}" references capability "${pres.capability.key}.v${pres.capability.version}" but capability not found`,
+				specKey: pres.meta.key,
+				capabilityKey: `${pres.capability.key}.v${pres.capability.version}`,
+				surface: "presentation"
+			});
+			else if (!capSpec.provides?.some((p) => p.surface === "presentation" && p.key === pres.meta.key)) errors.push({
+				type: "surface_not_in_provides",
+				message: `Presentation "${pres.meta.key}" claims capability "${pres.capability.key}.v${pres.capability.version}" but not in capability's provides`,
+				specKey: pres.meta.key,
+				capabilityKey: `${pres.capability.key}.v${pres.capability.version}`,
+				surface: "presentation"
+			});
+		}
+	}
+	return {
+		valid: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+/**
+* Check if a spec exists for a given surface type and key.
+*/
+function checkSurfaceExists(deps, surface, key) {
+	switch (surface) {
+		case "operation": return deps.operations?.has(key) ?? true;
+		case "event": return deps.events?.has(key) ?? true;
+		case "presentation": return deps.presentations?.has(key) ?? true;
+		case "workflow":
+		case "resource": return true;
+		default: return true;
+	}
+}
+/**
+* Finds specs that have no capability assignment (orphan specs).
+* This is informational - orphan specs are allowed but may indicate
+* incomplete capability modeling.
+*
+* @param deps - Registries to check
+* @returns List of spec keys without capability assignment
+*/
+function findOrphanSpecs(deps) {
+	const result = {
+		operations: [],
+		events: [],
+		presentations: []
+	};
+	if (deps.operations) {
+		for (const op of deps.operations.list()) if (!op.capability) result.operations.push(op.meta.key);
+	}
+	if (deps.events) {
+		for (const event of deps.events.list()) if (!event.capability) result.events.push(event.meta.key);
+	}
+	if (deps.presentations) {
+		for (const pres of deps.presentations.list()) if (!pres.capability) result.presentations.push(pres.meta.key);
+	}
+	return result;
+}
+
+//#endregion
+export { findOrphanSpecs, validateCapabilityConsistency };

package/dist/client/react/feature-render.d.ts

@@ -1,8 +1,8 @@
 import { PresentationSpec, PresentationTarget } from "../../presentations/presentations.js";
-import { FeatureModuleSpec } from "../../features/types.js";
-import { FeatureRegistry } from "../../features/registry.js";
 import { ComponentMap, TransformEngine } from "../../presentations/transform-engine.js";
 import "../../presentations/index.js";
+import { FeatureModuleSpec } from "../../features/types.js";
+import { FeatureRegistry } from "../../features/registry.js";
 import "../../features/index.js";
 import React from "react";
 import { BlockConfig } from "@blocknote/core";

package/dist/contract-registry/schemas.d.ts

@@ -46,12 +46,12 @@ declare const ContractRegistryItemSchema: z.ZodObject<{
   description: z.ZodString;
   meta: z.ZodObject<{
     stability: z.ZodEnum<{
-      deprecated: "deprecated";
       idea: "idea";
       in_creation: "in_creation";
       experimental: "experimental";
       beta: "beta";
       stable: "stable";
+      deprecated: "deprecated";
     }>;
     owners: z.ZodDefault<z.ZodArray<z.ZodString>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -95,12 +95,12 @@ declare const ContractRegistryManifestSchema: z.ZodObject<{
     description: z.ZodString;
     meta: z.ZodObject<{
       stability: z.ZodEnum<{
-        deprecated: "deprecated";
         idea: "idea";
         in_creation: "in_creation";
         experimental: "experimental";
         beta: "beta";
         stable: "stable";
+        deprecated: "deprecated";
       }>;
       owners: z.ZodDefault<z.ZodArray<z.ZodString>>;
       tags: z.ZodDefault<z.ZodArray<z.ZodString>>;

package/dist/data-views/data-views.d.ts

@@ -1,5 +1,6 @@
+import { DataViewRef } from "../features/types.js";
 import { DataViewAction, DataViewBaseConfig, DataViewConfig, DataViewDetailConfig, DataViewField, DataViewFieldFormat, DataViewFilter, DataViewGridConfig, DataViewKind, DataViewListConfig, DataViewMeta, DataViewSections, DataViewSource, DataViewStates, DataViewTableColumn, DataViewTableConfig } from "./types.js";
-import { DataViewRef, DataViewSpec, defineDataView } from "./spec.js";
+import { DataViewSpec, defineDataView } from "./spec.js";
 import { DataViewRegistry, dataViewKey } from "./registry.js";
 import "./index.js";
 export { DataViewAction, DataViewBaseConfig, DataViewConfig, DataViewDetailConfig, DataViewField, DataViewFieldFormat, DataViewFilter, DataViewGridConfig, DataViewKind, DataViewListConfig, DataViewMeta, DataViewRef, DataViewRegistry, DataViewSections, DataViewSource, DataViewSpec, DataViewStates, DataViewTableColumn, DataViewTableConfig, dataViewKey, defineDataView };

package/dist/data-views/index.d.ts

@@ -1,4 +1,5 @@
+import { DataViewRef } from "../features/types.js";
 import { DataViewAction, DataViewBaseConfig, DataViewConfig, DataViewDetailConfig, DataViewField, DataViewFieldFormat, DataViewFilter, DataViewGridConfig, DataViewKind, DataViewListConfig, DataViewMeta, DataViewSections, DataViewSource, DataViewStates, DataViewTableColumn, DataViewTableConfig } from "./types.js";
-import { DataViewRef, DataViewSpec, defineDataView } from "./spec.js";
+import { DataViewSpec, defineDataView } from "./spec.js";
 import { DataViewRegistry, dataViewKey } from "./registry.js";
 export { type DataViewAction, type DataViewBaseConfig, type DataViewConfig, type DataViewDetailConfig, type DataViewField, type DataViewFieldFormat, type DataViewFilter, type DataViewGridConfig, type DataViewKind, type DataViewListConfig, type DataViewMeta, type DataViewRef, DataViewRegistry, type DataViewSections, type DataViewSource, type DataViewSpec, type DataViewStates, type DataViewTableColumn, type DataViewTableConfig, dataViewKey, defineDataView };

package/dist/data-views/registry.d.ts

@@ -1,5 +1,5 @@
-import { DataViewSpec } from "./spec.js";
 import { SpecContractRegistry } from "../registry.js";
+import { DataViewSpec } from "./spec.js";
 
 //#region src/data-views/registry.d.ts
 

package/dist/data-views/runtime.d.ts

@@ -1,9 +1,9 @@
-import { OperationSpecRegistry } from "../operations/registry.js";
 import "../operations/index.js";
 import { DataViewSpec } from "./spec.js";
 import { DataViewRegistry } from "./registry.js";
 import "./index.js";
 import { HandlerCtx } from "../types.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
 
 //#region src/data-views/runtime.d.ts
 interface DataViewRuntimeConfig {

package/dist/data-views/spec.d.ts

@@ -1,4 +1,5 @@
 import { ExperimentRef } from "../experiments/spec.js";
+import { DataViewRef } from "../features/types.js";
 import { DataViewConfig, DataViewMeta, DataViewSource, DataViewStates } from "./types.js";
 
 //#region src/data-views/spec.d.ts
@@ -17,16 +18,9 @@ interface DataViewSpec {
   };
   experiments?: ExperimentRef[];
 }
-/**
- * Reference to a data view spec.
- */
-interface DataViewRef {
-  key: string;
-  version: string;
-}
 /**
  * Helper to define a data view spec with type safety.
  */
 declare function defineDataView(spec: DataViewSpec): DataViewSpec;
 //#endregion
-export { DataViewRef, DataViewSpec, defineDataView };
+export { type DataViewRef, DataViewSpec, defineDataView };

package/dist/data-views/types.d.ts

@@ -1,6 +1,6 @@
-import { OwnerShipMeta } from "../ownership.js";
 import { EventRef, OpRef, PresentationRef } from "../features/types.js";
 import "../features/index.js";
+import { OwnerShipMeta } from "../ownership.js";
 
 //#region src/data-views/types.d.ts
 /**

package/dist/docs/capabilities/documentationSystem.capability.d.ts

@@ -0,0 +1,7 @@
+import { CapabilitySpec } from "../../capabilities/capabilities.js";
+import "../../index.js";
+
+//#region src/docs/capabilities/documentationSystem.capability.d.ts
+declare const DocumentationSystemCapability: CapabilitySpec;
+//#endregion
+export { DocumentationSystemCapability };

package/dist/docs/capabilities/documentationSystem.capability.js

@@ -0,0 +1,71 @@
+import { defineCapability } from "../../capabilities/capabilities.js";
+import "../../capabilities/index.js";
+import { DOCS_CAPABILITY_KEY, DOCS_CAPABILITY_VERSION, DOCS_DOMAIN, DOCS_LAYOUT_PRESENTATION_KEY, DOCS_OWNERS, DOCS_REFERENCE_PRESENTATION_KEY, DOCS_STABILITY, DOCS_TAGS } from "../constants.js";
+
+//#region src/docs/capabilities/documentationSystem.capability.ts
+const DocumentationSystemCapability = defineCapability({
+	meta: {
+		key: DOCS_CAPABILITY_KEY,
+		version: DOCS_CAPABILITY_VERSION,
+		kind: "ui",
+		title: "Documentation System",
+		description: "End-to-end docs generation, indexing, and presentation.",
+		domain: DOCS_DOMAIN,
+		owners: DOCS_OWNERS,
+		tags: [...DOCS_TAGS, "system"],
+		stability: DOCS_STABILITY
+	},
+	provides: [
+		{
+			surface: "operation",
+			key: "docs.generate",
+			version: "1.0.0",
+			description: "Generate documentation artifacts."
+		},
+		{
+			surface: "operation",
+			key: "docs.publish",
+			version: "1.0.0",
+			description: "Publish documentation artifacts."
+		},
+		{
+			surface: "operation",
+			key: "docs.search",
+			version: "1.0.0",
+			description: "Index and search DocBlocks."
+		},
+		{
+			surface: "operation",
+			key: "docs.contract.reference",
+			version: "1.0.0",
+			description: "Resolve contract references for docs."
+		},
+		{
+			surface: "event",
+			key: "docs.generated",
+			version: "1.0.0",
+			description: "Docs generation completed."
+		},
+		{
+			surface: "event",
+			key: "docs.published",
+			version: "1.0.0",
+			description: "Docs publish completed."
+		},
+		{
+			surface: "presentation",
+			key: DOCS_LAYOUT_PRESENTATION_KEY,
+			version: "1.0.0",
+			description: "Docs layout presentation."
+		},
+		{
+			surface: "presentation",
+			key: DOCS_REFERENCE_PRESENTATION_KEY,
+			version: "1.0.0",
+			description: "Docs reference page presentation."
+		}
+	]
+});
+
+//#endregion
+export { DocumentationSystemCapability };

package/dist/docs/capabilities/index.d.ts

@@ -0,0 +1,2 @@
+import { DocumentationSystemCapability } from "./documentationSystem.capability.js";
+export { DocumentationSystemCapability };

package/dist/docs/capabilities/index.js

@@ -0,0 +1,3 @@
+import { DocumentationSystemCapability } from "./documentationSystem.capability.js";
+
+export { DocumentationSystemCapability };

package/dist/docs/commands/docsGenerate.command.d.ts

@@ -0,0 +1,95 @@
+import { OperationSpec } from "../../operations/operation.js";
+import { EventSpecMeta } from "../../events.js";
+import "../../index.js";
+import * as _contractspec_lib_schema267 from "@contractspec/lib.schema";
+import { SchemaModel } from "@contractspec/lib.schema";
+
+//#region src/docs/commands/docsGenerate.command.d.ts
+declare const DocsGenerateCommand: OperationSpec<SchemaModel<{
+  workspaceRoot: {
+    type: _contractspec_lib_schema267.FieldType<string, string>;
+    isOptional: true;
+  };
+  outputDir: {
+    type: _contractspec_lib_schema267.FieldType<string, string>;
+    isOptional: true;
+  };
+  version: {
+    type: _contractspec_lib_schema267.FieldType<string, string>;
+    isOptional: true;
+  };
+  formats: {
+    type: _contractspec_lib_schema267.FieldType<string, string>;
+    isOptional: true;
+    isArray: true;
+  };
+  includeInternal: {
+    type: _contractspec_lib_schema267.FieldType<boolean, boolean>;
+    isOptional: true;
+  };
+  includeExperimental: {
+    type: _contractspec_lib_schema267.FieldType<boolean, boolean>;
+    isOptional: true;
+  };
+  contractFilter: {
+    type: _contractspec_lib_schema267.FieldType<string, string>;
+    isOptional: true;
+  };
+  docblockFilter: {
+    type: _contractspec_lib_schema267.FieldType<string, string>;
+    isOptional: true;
+  };
+  dryRun: {
+    type: _contractspec_lib_schema267.FieldType<boolean, boolean>;
+    isOptional: true;
+  };
+}>, SchemaModel<{
+  buildId: {
+    type: _contractspec_lib_schema267.FieldType<string, string>;
+    isOptional: false;
+  };
+  version: {
+    type: _contractspec_lib_schema267.FieldType<string, string>;
+    isOptional: true;
+  };
+  generatedAt: {
+    type: _contractspec_lib_schema267.FieldType<Date, string>;
+    isOptional: false;
+  };
+  outputDir: {
+    type: _contractspec_lib_schema267.FieldType<string, string>;
+    isOptional: true;
+  };
+  artifacts: {
+    type: SchemaModel<{
+      path: {
+        type: _contractspec_lib_schema267.FieldType<string, string>;
+        isOptional: false;
+      };
+      format: {
+        type: _contractspec_lib_schema267.FieldType<string, string>;
+        isOptional: true;
+      };
+      bytes: {
+        type: _contractspec_lib_schema267.FieldType<number, number>;
+        isOptional: true;
+      };
+      kind: {
+        type: _contractspec_lib_schema267.FieldType<string, string>;
+        isOptional: true;
+      };
+    }>;
+    isOptional: true;
+    isArray: true;
+  };
+  warnings: {
+    type: _contractspec_lib_schema267.FieldType<string, string>;
+    isOptional: true;
+    isArray: true;
+  };
+}>, {
+  ref: EventSpecMeta;
+  when: string;
+}[]>;
+//#endregion
+export { DocsGenerateCommand };

package/dist/docs/commands/docsGenerate.command.js

@@ -0,0 +1,139 @@
+import { defineCommand } from "../../operations/operation.js";
+import "../../operations/index.js";
+import { DOCS_CAPABILITY_REF, DOCS_DOMAIN, DOCS_OWNERS, DOCS_STABILITY, DOCS_TAGS } from "../constants.js";
+import { docId } from "../registry.js";
+import "../ensure-docblocks.js";
+import { DocsGeneratedEvent } from "../events/docsGenerated.event.js";
+import { ScalarTypeEnum, SchemaModel } from "@contractspec/lib.schema";
+
+//#region src/docs/commands/docsGenerate.command.ts
+const DocsArtifactModel = new SchemaModel({
+	name: "DocsArtifact",
+	fields: {
+		path: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		format: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		bytes: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		kind: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const DocsGenerateInput = new SchemaModel({
+	name: "DocsGenerateInput",
+	fields: {
+		workspaceRoot: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		outputDir: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		version: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		formats: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true,
+			isArray: true
+		},
+		includeInternal: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		},
+		includeExperimental: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		},
+		contractFilter: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		docblockFilter: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		dryRun: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		}
+	}
+});
+const DocsGenerateOutput = new SchemaModel({
+	name: "DocsGenerateOutput",
+	fields: {
+		buildId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		version: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		generatedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: false
+		},
+		outputDir: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		artifacts: {
+			type: DocsArtifactModel,
+			isOptional: true,
+			isArray: true
+		},
+		warnings: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true,
+			isArray: true
+		}
+	}
+});
+const DocsGenerateCommand = defineCommand({
+	meta: {
+		key: "docs.generate",
+		title: "Generate Documentation",
+		version: "1.0.0",
+		description: "Generate documentation artifacts from ContractSpecs.",
+		goal: "Produce up-to-date reference docs and guides from specs and DocBlocks.",
+		context: "Used by CLI and CI to keep docs in sync with contract definitions.",
+		domain: DOCS_DOMAIN,
+		owners: DOCS_OWNERS,
+		tags: [...DOCS_TAGS, "generation"],
+		stability: DOCS_STABILITY,
+		docId: [docId("docs.tech.docs-generator")]
+	},
+	capability: DOCS_CAPABILITY_REF,
+	io: {
+		input: DocsGenerateInput,
+		output: DocsGenerateOutput,
+		errors: { OUTPUT_WRITE_FAILED: {
+			description: "Failed to write generated docs output.",
+			http: 500,
+			when: "The generator cannot persist artifacts to the output path."
+		} }
+	},
+	policy: {
+		auth: "admin",
+		pii: []
+	},
+	sideEffects: { emits: [{
+		ref: DocsGeneratedEvent.meta,
+		when: "Docs generation completes successfully."
+	}] }
+});
+
+//#endregion
+export { DocsGenerateCommand };

package/dist/docs/commands/docsPublish.command.d.ts

@@ -0,0 +1,64 @@
+import { OperationSpec } from "../../operations/operation.js";
+import { EventSpecMeta } from "../../events.js";
+import "../../index.js";
+import * as _contractspec_lib_schema285 from "@contractspec/lib.schema";
+import { SchemaModel } from "@contractspec/lib.schema";
+
+//#region src/docs/commands/docsPublish.command.d.ts
+declare const DocsPublishCommand: OperationSpec<SchemaModel<{
+  buildId: {
+    type: _contractspec_lib_schema285.FieldType<string, string>;
+    isOptional: false;
+  };
+  version: {
+    type: _contractspec_lib_schema285.FieldType<string, string>;
+    isOptional: true;
+  };
+  environment: {
+    type: _contractspec_lib_schema285.FieldType<string, string>;
+    isOptional: true;
+  };
+  deployTarget: {
+    type: _contractspec_lib_schema285.FieldType<string, string>;
+    isOptional: true;
+  };
+  artifactPath: {
+    type: _contractspec_lib_schema285.FieldType<string, string>;
+    isOptional: true;
+  };
+  dryRun: {
+    type: _contractspec_lib_schema285.FieldType<boolean, boolean>;
+    isOptional: true;
+  };
+  notes: {
+    type: _contractspec_lib_schema285.FieldType<string, string>;
+    isOptional: true;
+  };
+}>, SchemaModel<{
+  publishId: {
+    type: _contractspec_lib_schema285.FieldType<string, string>;
+    isOptional: false;
+  };
+  publishedAt: {
+    type: _contractspec_lib_schema285.FieldType<Date, string>;
+    isOptional: false;
+  };
+  url: {
+    type: _contractspec_lib_schema285.FieldType<string, string>;
+    isOptional: true;
+  };
+  status: {
+    type: _contractspec_lib_schema285.FieldType<string, string>;
+    isOptional: true;
+  };
+  warnings: {
+    type: _contractspec_lib_schema285.FieldType<string, string>;
+    isOptional: true;
+    isArray: true;
+  };
+}>, {
+  ref: EventSpecMeta;
+  when: string;
+}[]>;
+//#endregion
+export { DocsPublishCommand };