feat(cli): check each authored doc against its published authoring type

.changeset/integration-template-doc.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] Three new published types describe an integration package's templates: `IntegrationPageTemplateDoc` and `IntegrationBlockTemplateDoc`, each with every field of its `TemplateDoc` member but `category` as the package's own string instead of a `TemplateCategory` value, and their union, `IntegrationTemplateDoc`. `@astryxdesign/cli/authoring` exports `IntegrationTemplateDoc`; `@astryxdesign/cli/doc` and `@astryxdesign/cli/template` export all three. `TemplateDoc` is unchanged.
+
+@josephfarina

packages/cli/authoring/doctypes/template/integration-template.doc.mjs

@@ -0,0 +1,49 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for the `IntegrationTemplateDoc` doc-type — the template
+ * metadata an integration package ships: TemplateDoc, with the package's own
+ * `category`. Colocated with the type it describes (`type.ts`).
+ * @position packages/cli/authoring/doctypes/template — doc-type documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+  type: 'schema',
+  name: 'integration-template-doc',
+  displayName: 'IntegrationTemplateDoc',
+  namespace: 'authoring',
+  description:
+    "The doc-type for an integration package's template metadata. It has every " +
+    "TemplateDoc field and rule, except that `category` is the package's own " +
+    'string instead of a TemplateCategory value.',
+  appliesTo: '<Name>.doc.mjs',
+  fields: [
+    {
+      name: 'category',
+      type: 'string',
+      description:
+        "The package's own category. Bare `astryx template` groups the package's templates by it.",
+    },
+  ],
+  examples: [
+    {
+      label: 'Block template in an integration package',
+      code: `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */
+export default {
+  type: 'block',
+  name: 'acme-pricing-table',
+  displayName: 'Pricing Table',
+  description: 'Plans side by side, with the chosen plan highlighted.',
+  aspectRatio: 16 / 9,
+  category: 'Acme - Commerce',
+};`,
+    },
+  ],
+  notes: [
+    {
+      type: 'prose',
+      text: "Every other field, and the page and block variants, are TemplateDoc's. Core's own templates use TemplateDoc, whose `category` is a TemplateCategory value.",
+    },
+  ],
+};

packages/cli/authoring/doctypes/template/parse.mjs

@@ -78,7 +78,9 @@ const blockTemplateSchema = z
  * Templates as they load. Integration templates already published omit
  * `displayName` and `aspectRatio` and group themselves under their own
  * `category`, so the loader accepts those (template discovery falls back to an
- * aspect ratio of 1). The published types keep asking authors for all three.
+ * aspect ratio of 1). The published `TemplateDoc` keeps asking authors for all
+ * three; `IntegrationTemplateDoc`, for an integration package's templates,
+ * takes the package's own `category`.
  *
  * @typedef {Omit<PageTemplateDoc, 'displayName' | 'category'>
  *   & {displayName?: string, category?: string}} LoadedPageTemplateDoc

packages/cli/authoring/doctypes/template/type.ts

@@ -201,3 +201,25 @@ export type TemplateCategory =
   | 'Shell - Blank';
 
 export type TemplateDoc = PageTemplateDoc | BlockTemplateDoc;
+
+/** A page template an integration package ships, with its own `category`. */
+export interface IntegrationPageTemplateDoc extends Omit<
+  PageTemplateDoc,
+  'category'
+> {
+  category?: string;
+}
+
+/** A block template an integration package ships, with its own `category`. */
+export interface IntegrationBlockTemplateDoc extends Omit<
+  BlockTemplateDoc,
+  'category'
+> {
+  category?: string;
+}
+
+/** The doc-type for an integration package's template metadata: TemplateDoc,
+ *  with `category` the package's own string (bare `astryx template` groups
+ *  the package's templates by it) instead of a TemplateCategory value. */
+export type IntegrationTemplateDoc =
+  IntegrationPageTemplateDoc | IntegrationBlockTemplateDoc;

packages/cli/authoring/index.d.ts

@@ -28,6 +28,7 @@ export type {HookDoc} from './doctypes/types.js'; //         useToast.doc.mjs
 export type {FunctionDoc} from './doctypes/types.js'; //     search.doc.mjs (hook | api)
 export type {ReferenceDoc} from './doctypes/types.js'; //    theming.doc.mjs
 export type {TemplateDoc} from './doctypes/types.js'; //     Foo.doc.mjs
+export type {IntegrationTemplateDoc} from './doctypes/types.js'; // an integration's Foo.doc.mjs
 export type {SchemaDoc} from './doctypes/types.js'; //       config.doc.mjs (object shape)
 export type {CommandDoc} from './doctypes/types.js'; //      search.doc.mjs (CLI command)
 export type {EnumDoc} from './doctypes/types.js'; //         error-codes.doc.mjs (vocabulary)

packages/cli/foundation/discovery/authoring-self-docs.mjs

@@ -46,6 +46,7 @@ export const AUTHORING_SELF_DOCS = [
   'doctypes/reference/reference.doc.mjs',
   'doctypes/schema/schema.doc.mjs',
   'doctypes/template/template.doc.mjs',
+  'doctypes/template/integration-template.doc.mjs',
   'doctypes/theme/theme.doc.mjs',
 ];