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

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

@@ -0,0 +1,104 @@
+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 { DocsPublishedEvent } from "../events/docsPublished.event.js";
+import { ScalarTypeEnum, SchemaModel } from "@contractspec/lib.schema";
+
+//#region src/docs/commands/docsPublish.command.ts
+const DocsPublishInput = new SchemaModel({
+	name: "DocsPublishInput",
+	fields: {
+		buildId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		version: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		environment: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		deployTarget: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		artifactPath: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		dryRun: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		},
+		notes: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const DocsPublishOutput = new SchemaModel({
+	name: "DocsPublishOutput",
+	fields: {
+		publishId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		publishedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: false
+		},
+		url: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		status: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		warnings: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true,
+			isArray: true
+		}
+	}
+});
+const DocsPublishCommand = defineCommand({
+	meta: {
+		key: "docs.publish",
+		title: "Publish Documentation",
+		version: "1.0.0",
+		description: "Publish generated documentation artifacts.",
+		goal: "Deploy docs to the public docs surface with consistent versioning.",
+		context: "Used by release pipelines to push generated docs to hosting targets.",
+		domain: DOCS_DOMAIN,
+		owners: DOCS_OWNERS,
+		tags: [...DOCS_TAGS, "publish"],
+		stability: DOCS_STABILITY,
+		docId: [docId("docs.tech.docs-publish")]
+	},
+	capability: DOCS_CAPABILITY_REF,
+	io: {
+		input: DocsPublishInput,
+		output: DocsPublishOutput,
+		errors: { DEPLOY_FAILED: {
+			description: "Failed to deploy documentation artifacts.",
+			http: 500,
+			when: "The docs publish step fails to deploy to the target host."
+		} }
+	},
+	policy: {
+		auth: "admin",
+		pii: []
+	},
+	sideEffects: { emits: [{
+		ref: DocsPublishedEvent.meta,
+		when: "Docs publish completes successfully."
+	}] }
+});
+
+//#endregion
+export { DocsPublishCommand };

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

@@ -0,0 +1,3 @@
+import { DocsGenerateCommand } from "./docsGenerate.command.js";
+import { DocsPublishCommand } from "./docsPublish.command.js";
+export { DocsGenerateCommand, DocsPublishCommand };

package/dist/docs/commands/index.js

@@ -0,0 +1,4 @@
+import { DocsGenerateCommand } from "./docsGenerate.command.js";
+import { DocsPublishCommand } from "./docsPublish.command.js";
+
+export { DocsGenerateCommand, DocsPublishCommand };

package/dist/docs/constants.d.ts

@@ -0,0 +1,15 @@
+//#region src/docs/constants.d.ts
+declare const DOCS_DOMAIN = "docs";
+declare const DOCS_OWNERS: string[];
+declare const DOCS_TAGS: string[];
+declare const DOCS_STABILITY: "experimental";
+declare const DOCS_CAPABILITY_KEY = "docs.system";
+declare const DOCS_CAPABILITY_VERSION = "1.0.0";
+declare const DOCS_CAPABILITY_REF: {
+  key: string;
+  version: string;
+};
+declare const DOCS_LAYOUT_PRESENTATION_KEY = "docs.layout";
+declare const DOCS_REFERENCE_PRESENTATION_KEY = "docs.reference.page";
+//#endregion
+export { DOCS_CAPABILITY_KEY, DOCS_CAPABILITY_REF, DOCS_CAPABILITY_VERSION, DOCS_DOMAIN, DOCS_LAYOUT_PRESENTATION_KEY, DOCS_OWNERS, DOCS_REFERENCE_PRESENTATION_KEY, DOCS_STABILITY, DOCS_TAGS };

package/dist/docs/constants.js

@@ -0,0 +1,18 @@
+import { StabilityEnum } from "../ownership.js";
+
+//#region src/docs/constants.ts
+const DOCS_DOMAIN = "docs";
+const DOCS_OWNERS = ["docs-platform"];
+const DOCS_TAGS = ["docs", "documentation"];
+const DOCS_STABILITY = StabilityEnum.Experimental;
+const DOCS_CAPABILITY_KEY = "docs.system";
+const DOCS_CAPABILITY_VERSION = "1.0.0";
+const DOCS_CAPABILITY_REF = {
+	key: DOCS_CAPABILITY_KEY,
+	version: DOCS_CAPABILITY_VERSION
+};
+const DOCS_LAYOUT_PRESENTATION_KEY = "docs.layout";
+const DOCS_REFERENCE_PRESENTATION_KEY = "docs.reference.page";
+
+//#endregion
+export { DOCS_CAPABILITY_KEY, DOCS_CAPABILITY_REF, DOCS_CAPABILITY_VERSION, DOCS_DOMAIN, DOCS_LAYOUT_PRESENTATION_KEY, DOCS_OWNERS, DOCS_REFERENCE_PRESENTATION_KEY, DOCS_STABILITY, DOCS_TAGS };

package/dist/docs/contracts.d.ts

@@ -0,0 +1,442 @@
+import { OperationSpec } from "../operations/operation.js";
+import { PresentationSpec } from "../presentations/presentations.js";
+import { PresentationRegistry } from "../presentations/registry.js";
+import "../presentations/index.js";
+import { DataViewSpec } from "../data-views/spec.js";
+import { DataViewRegistry } from "../data-views/registry.js";
+import "../data-views/index.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
+import { FormRegistry, FormSpec } from "../forms/forms.js";
+import "../forms/index.js";
+import { EventRegistry, EventSpec, EventSpecMeta } from "../events.js";
+import "../index.js";
+import * as _contractspec_lib_schema0 from "@contractspec/lib.schema";
+
+//#region src/docs/contracts.d.ts
+declare const docsOperationContracts: {
+  DocsIndexQuery: OperationSpec<_contractspec_lib_schema0.SchemaModel<{
+    query: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    tag: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+      isArray: true;
+    };
+    visibility: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    kind: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    limit: {
+      type: _contractspec_lib_schema0.FieldType<number, number>;
+      isOptional: true;
+    };
+    offset: {
+      type: _contractspec_lib_schema0.FieldType<number, number>;
+      isOptional: true;
+    };
+  }>, _contractspec_lib_schema0.SchemaModel<{
+    items: {
+      type: _contractspec_lib_schema0.SchemaModel<{
+        id: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: false;
+        };
+        title: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: false;
+        };
+        summary: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        route: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        visibility: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        kind: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        version: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        tags: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+          isArray: true;
+        };
+      }>;
+      isOptional: true;
+      isArray: true;
+    };
+    docs: {
+      type: _contractspec_lib_schema0.SchemaModel<{
+        id: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: false;
+        };
+        title: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: false;
+        };
+        summary: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        route: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        visibility: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        kind: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        version: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        tags: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+          isArray: true;
+        };
+      }>;
+      isOptional: false;
+      isArray: true;
+    };
+    total: {
+      type: _contractspec_lib_schema0.FieldType<number, number>;
+      isOptional: true;
+    };
+    nextOffset: {
+      type: _contractspec_lib_schema0.FieldType<number, number>;
+      isOptional: true;
+    };
+  }>, undefined>;
+  ContractReferenceQuery: OperationSpec<_contractspec_lib_schema0.SchemaModel<{
+    key: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: false;
+    };
+    version: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    type: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    format: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    includeSchema: {
+      type: _contractspec_lib_schema0.FieldType<boolean, boolean>;
+      isOptional: true;
+    };
+  }>, _contractspec_lib_schema0.SchemaModel<{
+    reference: {
+      type: _contractspec_lib_schema0.SchemaModel<{
+        key: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: false;
+        };
+        version: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: false;
+        };
+        type: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: false;
+        };
+        title: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        description: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        markdown: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        route: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        schema: {
+          type: _contractspec_lib_schema0.FieldType<Record<string, unknown>, Record<string, unknown>>;
+          isOptional: true;
+        };
+        policy: {
+          type: _contractspec_lib_schema0.FieldType<Record<string, unknown>, Record<string, unknown>>;
+          isOptional: true;
+        };
+        tags: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+          isArray: true;
+        };
+        owners: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+          isArray: true;
+        };
+        stability: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+      }>;
+      isOptional: false;
+    };
+  }>, undefined>;
+  DocsGenerateCommand: OperationSpec<_contractspec_lib_schema0.SchemaModel<{
+    workspaceRoot: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    outputDir: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    version: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    formats: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+      isArray: true;
+    };
+    includeInternal: {
+      type: _contractspec_lib_schema0.FieldType<boolean, boolean>;
+      isOptional: true;
+    };
+    includeExperimental: {
+      type: _contractspec_lib_schema0.FieldType<boolean, boolean>;
+      isOptional: true;
+    };
+    contractFilter: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    docblockFilter: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    dryRun: {
+      type: _contractspec_lib_schema0.FieldType<boolean, boolean>;
+      isOptional: true;
+    };
+  }>, _contractspec_lib_schema0.SchemaModel<{
+    buildId: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: false;
+    };
+    version: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    generatedAt: {
+      type: _contractspec_lib_schema0.FieldType<Date, string>;
+      isOptional: false;
+    };
+    outputDir: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    artifacts: {
+      type: _contractspec_lib_schema0.SchemaModel<{
+        path: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: false;
+        };
+        format: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+        bytes: {
+          type: _contractspec_lib_schema0.FieldType<number, number>;
+          isOptional: true;
+        };
+        kind: {
+          type: _contractspec_lib_schema0.FieldType<string, string>;
+          isOptional: true;
+        };
+      }>;
+      isOptional: true;
+      isArray: true;
+    };
+    warnings: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+      isArray: true;
+    };
+  }>, {
+    ref: EventSpecMeta;
+    when: string;
+  }[]>;
+  DocsPublishCommand: OperationSpec<_contractspec_lib_schema0.SchemaModel<{
+    buildId: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: false;
+    };
+    version: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    environment: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    deployTarget: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    artifactPath: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    dryRun: {
+      type: _contractspec_lib_schema0.FieldType<boolean, boolean>;
+      isOptional: true;
+    };
+    notes: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+  }>, _contractspec_lib_schema0.SchemaModel<{
+    publishId: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: false;
+    };
+    publishedAt: {
+      type: _contractspec_lib_schema0.FieldType<Date, string>;
+      isOptional: false;
+    };
+    url: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    status: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    warnings: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+      isArray: true;
+    };
+  }>, {
+    ref: EventSpecMeta;
+    when: string;
+  }[]>;
+};
+declare const docsEventContracts: {
+  DocsGeneratedEvent: EventSpec<_contractspec_lib_schema0.SchemaModel<{
+    buildId: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: false;
+    };
+    version: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    generatedAt: {
+      type: _contractspec_lib_schema0.FieldType<Date, string>;
+      isOptional: false;
+    };
+    outputDir: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    artifactCount: {
+      type: _contractspec_lib_schema0.FieldType<number, number>;
+      isOptional: true;
+    };
+    warnings: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+      isArray: true;
+    };
+  }>>;
+  DocsPublishedEvent: EventSpec<_contractspec_lib_schema0.SchemaModel<{
+    publishId: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: false;
+    };
+    version: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    environment: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    url: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    publishedAt: {
+      type: _contractspec_lib_schema0.FieldType<Date, string>;
+      isOptional: false;
+    };
+    status: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    warnings: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+      isArray: true;
+    };
+  }>>;
+};
+declare const docsPresentationContracts: {
+  DocsLayoutPresentation: PresentationSpec;
+  DocsReferencePagePresentation: PresentationSpec;
+};
+declare const docsFormContracts: {
+  DocsSearchForm: FormSpec<_contractspec_lib_schema0.SchemaModel<{
+    query: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    visibility: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+    kind: {
+      type: _contractspec_lib_schema0.FieldType<string, string>;
+      isOptional: true;
+    };
+  }>>;
+};
+declare const docsDataViewContracts: {
+  DocsIndexDataView: DataViewSpec;
+  ContractReferenceDataView: DataViewSpec;
+  ExampleCatalogDataView: DataViewSpec;
+};
+declare function registerDocsOperations(registry: OperationSpecRegistry): OperationSpecRegistry;
+declare function registerDocsEvents(registry: EventRegistry): EventRegistry;
+declare function registerDocsPresentations(registry: PresentationRegistry): PresentationRegistry;
+declare function registerDocsForms(registry: FormRegistry): FormRegistry;
+declare function registerDocsDataViews(registry: DataViewRegistry): DataViewRegistry;
+//#endregion
+export { docsDataViewContracts, docsEventContracts, docsFormContracts, docsOperationContracts, docsPresentationContracts, registerDocsDataViews, registerDocsEvents, registerDocsForms, registerDocsOperations, registerDocsPresentations };

package/dist/docs/contracts.js

@@ -0,0 +1,58 @@
+import { DocsGeneratedEvent } from "./events/docsGenerated.event.js";
+import { DocsGenerateCommand } from "./commands/docsGenerate.command.js";
+import { DocsPublishedEvent } from "./events/docsPublished.event.js";
+import { DocsPublishCommand } from "./commands/docsPublish.command.js";
+import "./commands/index.js";
+import { DocsIndexQuery } from "./queries/docsIndex.query.js";
+import { ContractReferenceQuery } from "./queries/contractReference.query.js";
+import "./queries/index.js";
+import "./events/index.js";
+import { DocsLayoutPresentation } from "./presentations/docsLayout.presentation.js";
+import { DocsReferencePagePresentation } from "./presentations/docsReferencePage.presentation.js";
+import "./presentations/index.js";
+import { DocsSearchForm } from "./forms/docsSearch.form.js";
+import "./forms/index.js";
+import { DocsIndexDataView } from "./views/docsIndex.dataView.js";
+import { ContractReferenceDataView } from "./views/contractReference.dataView.js";
+import { ExampleCatalogDataView } from "./views/exampleCatalog.dataView.js";
+import "./views/index.js";
+
+//#region src/docs/contracts.ts
+const docsOperationContracts = {
+	DocsIndexQuery,
+	ContractReferenceQuery,
+	DocsGenerateCommand,
+	DocsPublishCommand
+};
+const docsEventContracts = {
+	DocsGeneratedEvent,
+	DocsPublishedEvent
+};
+const docsPresentationContracts = {
+	DocsLayoutPresentation,
+	DocsReferencePagePresentation
+};
+const docsFormContracts = { DocsSearchForm };
+const docsDataViewContracts = {
+	DocsIndexDataView,
+	ContractReferenceDataView,
+	ExampleCatalogDataView
+};
+function registerDocsOperations(registry) {
+	return registry.register(DocsIndexQuery).register(ContractReferenceQuery).register(DocsGenerateCommand).register(DocsPublishCommand);
+}
+function registerDocsEvents(registry) {
+	return registry.register(DocsGeneratedEvent).register(DocsPublishedEvent);
+}
+function registerDocsPresentations(registry) {
+	return registry.register(DocsLayoutPresentation).register(DocsReferencePagePresentation);
+}
+function registerDocsForms(registry) {
+	return registry.register(DocsSearchForm);
+}
+function registerDocsDataViews(registry) {
+	return registry.register(DocsIndexDataView).register(ContractReferenceDataView).register(ExampleCatalogDataView);
+}
+
+//#endregion
+export { docsDataViewContracts, docsEventContracts, docsFormContracts, docsOperationContracts, docsPresentationContracts, registerDocsDataViews, registerDocsEvents, registerDocsForms, registerDocsOperations, registerDocsPresentations };

package/dist/docs/ensure-docblocks.d.ts

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

package/dist/docs/ensure-docblocks.js

@@ -0,0 +1 @@
+import "./tech/docs-system.docblock.js";