@contractspec/lib.contracts 1.52.0 → 1.54.0

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_schema321 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_schema321.FieldType<string, string>;
+    isOptional: true;
+  };
+  outputDir: {
+    type: _contractspec_lib_schema321.FieldType<string, string>;
+    isOptional: true;
+  };
+  version: {
+    type: _contractspec_lib_schema321.FieldType<string, string>;
+    isOptional: true;
+  };
+  formats: {
+    type: _contractspec_lib_schema321.FieldType<string, string>;
+    isOptional: true;
+    isArray: true;
+  };
+  includeInternal: {
+    type: _contractspec_lib_schema321.FieldType<boolean, boolean>;
+    isOptional: true;
+  };
+  includeExperimental: {
+    type: _contractspec_lib_schema321.FieldType<boolean, boolean>;
+    isOptional: true;
+  };
+  contractFilter: {
+    type: _contractspec_lib_schema321.FieldType<string, string>;
+    isOptional: true;
+  };
+  docblockFilter: {
+    type: _contractspec_lib_schema321.FieldType<string, string>;
+    isOptional: true;
+  };
+  dryRun: {
+    type: _contractspec_lib_schema321.FieldType<boolean, boolean>;
+    isOptional: true;
+  };
+}>, SchemaModel<{
+  buildId: {
+    type: _contractspec_lib_schema321.FieldType<string, string>;
+    isOptional: false;
+  };
+  version: {
+    type: _contractspec_lib_schema321.FieldType<string, string>;
+    isOptional: true;
+  };
+  generatedAt: {
+    type: _contractspec_lib_schema321.FieldType<Date, string>;
+    isOptional: false;
+  };
+  outputDir: {
+    type: _contractspec_lib_schema321.FieldType<string, string>;
+    isOptional: true;
+  };
+  artifacts: {
+    type: SchemaModel<{
+      path: {
+        type: _contractspec_lib_schema321.FieldType<string, string>;
+        isOptional: false;
+      };
+      format: {
+        type: _contractspec_lib_schema321.FieldType<string, string>;
+        isOptional: true;
+      };
+      bytes: {
+        type: _contractspec_lib_schema321.FieldType<number, number>;
+        isOptional: true;
+      };
+      kind: {
+        type: _contractspec_lib_schema321.FieldType<string, string>;
+        isOptional: true;
+      };
+    }>;
+    isOptional: true;
+    isArray: true;
+  };
+  warnings: {
+    type: _contractspec_lib_schema321.FieldType<string, string>;
+    isOptional: true;
+    isArray: true;
+  };
+}>, {
+  ref: EventSpecMeta;
+  when: string;
+}[]>;
+//#endregion
+export { DocsGenerateCommand };

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

@@ -0,0 +1,142 @@
+import { defineCommand } from "../../operations/operation.js";
+import "../../operations/index.js";
+import { 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: {
+		key: "docs.system",
+		version: "1.0.0"
+	},
+	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_schema339 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_schema339.FieldType<string, string>;
+    isOptional: false;
+  };
+  version: {
+    type: _contractspec_lib_schema339.FieldType<string, string>;
+    isOptional: true;
+  };
+  environment: {
+    type: _contractspec_lib_schema339.FieldType<string, string>;
+    isOptional: true;
+  };
+  deployTarget: {
+    type: _contractspec_lib_schema339.FieldType<string, string>;
+    isOptional: true;
+  };
+  artifactPath: {
+    type: _contractspec_lib_schema339.FieldType<string, string>;
+    isOptional: true;
+  };
+  dryRun: {
+    type: _contractspec_lib_schema339.FieldType<boolean, boolean>;
+    isOptional: true;
+  };
+  notes: {
+    type: _contractspec_lib_schema339.FieldType<string, string>;
+    isOptional: true;
+  };
+}>, SchemaModel<{
+  publishId: {
+    type: _contractspec_lib_schema339.FieldType<string, string>;
+    isOptional: false;
+  };
+  publishedAt: {
+    type: _contractspec_lib_schema339.FieldType<Date, string>;
+    isOptional: false;
+  };
+  url: {
+    type: _contractspec_lib_schema339.FieldType<string, string>;
+    isOptional: true;
+  };
+  status: {
+    type: _contractspec_lib_schema339.FieldType<string, string>;
+    isOptional: true;
+  };
+  warnings: {
+    type: _contractspec_lib_schema339.FieldType<string, string>;
+    isOptional: true;
+    isArray: true;
+  };
+}>, {
+  ref: EventSpecMeta;
+  when: string;
+}[]>;
+//#endregion
+export { DocsPublishCommand };

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

@@ -0,0 +1,107 @@
+import { defineCommand } from "../../operations/operation.js";
+import "../../operations/index.js";
+import { 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: {
+		key: "docs.system",
+		version: "1.0.0"
+	},
+	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,7 @@
+//#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";
+//#endregion
+export { DOCS_DOMAIN, DOCS_OWNERS, DOCS_STABILITY, DOCS_TAGS };

package/dist/docs/constants.js

@@ -0,0 +1,10 @@
+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;
+
+//#endregion
+export { DOCS_DOMAIN, DOCS_OWNERS, DOCS_STABILITY, DOCS_TAGS };