@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

package/authoring/gap-report/gap-report.doc.mjs

@@ -0,0 +1,183 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for GapReportHandler, the handler `astryx gap-report` calls.
+ * @input The GapReportHandler type beside it (`type.ts`), which `parse.mjs`
+ *   validates.
+ * @output The `gap-report-handler` section of `astryx docs authoring`.
+ * @position packages/cli/authoring/gap-report — schema documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+  type: 'schema',
+  name: 'gap-report-handler',
+  displayName: 'GapReportHandler',
+  namespace: 'authoring',
+  description:
+    'A handler for `astryx gap-report`: a plain object with an `audience` and a `handle` function. Set it as `gapReport` in astryx.config, or export it as `gapReport` from an integration manifest. Every handler runs: the project handler first, then each integration handler in config order.',
+  appliesTo:
+    '`gapReport` in astryx.config.*, or the `gapReport` named export of astryx.integration.*',
+  fields: [
+    {
+      name: 'audience',
+      type: "'internal' | 'public'",
+      description:
+        'Whether the destination is internal to your organization or public. A public handler runs only when the caller agrees; an internal handler always runs.',
+      required: true,
+    },
+    {
+      name: 'handle',
+      type: '(report: GapReport, context: GapReportHandlerContext) => GapReportHandlerReceipt | Promise<GapReportHandlerReceipt>',
+      description:
+        'Gets the report and returns a receipt. It can be async, and the CLI waits at most 30 seconds for it. A throw, a timeout, or an invalid receipt is a failed delivery, and the other handlers still run.',
+      required: true,
+      fields: [
+        {
+          name: 'report',
+          type: 'GapReport',
+          description: 'The report. Each handler gets its own copy.',
+          required: true,
+          fields: [
+            {
+              name: 'report.schemaVersion',
+              type: '1',
+              description: 'Version of the report shape.',
+              required: true,
+            },
+            {
+              name: 'report.component',
+              type: 'string',
+              description: 'The component the gap is about.',
+              required: true,
+            },
+            {
+              name: 'report.category',
+              type: 'GapReportCategory',
+              description:
+                "The kind of gap: 'missing_component', 'missing_variant', 'layout_gap', 'styling_gap', 'a11y_gap', 'api_friction', 'docs_gap', or 'other'.",
+              required: true,
+            },
+            {
+              name: 'report.categoryLabel',
+              type: 'string',
+              description: 'A readable name for the category.',
+              required: true,
+            },
+            {
+              name: 'report.intention',
+              type: 'string',
+              description: 'What the caller was trying to do.',
+              required: true,
+            },
+            {
+              name: 'report.detail',
+              type: 'string',
+              description: 'More detail, when the caller gave some.',
+            },
+            {
+              name: 'report.source',
+              type: 'DebugInvocationSource',
+              description:
+                "Who sent the report: 'human', 'ai', 'automation', or 'unknown'.",
+              required: true,
+            },
+            {
+              name: 'report.timestamp',
+              type: 'string',
+              description: 'When the report was sent, as ISO 8601.',
+              required: true,
+            },
+            {
+              name: 'report.target',
+              type: 'GapReportTarget',
+              description: 'The package the report is about.',
+              required: true,
+              fields: [
+                {
+                  name: 'report.target.package',
+                  type: 'string',
+                  description: 'The package name.',
+                  required: true,
+                },
+                {
+                  name: 'report.target.version',
+                  type: 'string',
+                  description:
+                    'The installed version. Null when it is not known.',
+                  required: true,
+                },
+                {
+                  name: 'report.target.issuesUrl',
+                  type: 'string',
+                  description:
+                    'Where the package takes issues. Null when it does not say.',
+                  required: true,
+                },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'context',
+          type: 'GapReportHandlerContext',
+          description: 'The context of this call.',
+          required: true,
+          fields: [
+            {
+              name: 'context.signal',
+              type: 'AbortSignal',
+              description: 'Aborted when the handler runs past 30 seconds.',
+              required: true,
+            },
+          ],
+        },
+      ],
+    },
+  ],
+  examples: [
+    {
+      label: 'A project handler in astryx.config',
+      code:
+        'export default {\n' +
+        '  gapReport: {\n' +
+        "    audience: 'internal',\n" +
+        '    async handle(report, {signal}) {\n' +
+        '      const url = await fileIssue(report, {signal});\n' +
+        "      return {status: 'filed', url};\n" +
+        '    },\n' +
+        '  },\n' +
+        '};',
+    },
+  ],
+  notes: [
+    {
+      type: 'table',
+      headers: ['Receipt field', 'Type', 'Required', 'Description'],
+      rows: [
+        [
+          'status',
+          "'filed' | 'routed_only' | 'skipped'",
+          'yes',
+          "'filed': the handler created or queued the report. 'routed_only': it points to a place to file the report, and must return `url`. 'skipped': it chose not to act, for example on a duplicate.",
+        ],
+        [
+          'url',
+          'string',
+          'no',
+          'An http or https URL. Required when status is routed_only.',
+        ],
+        [
+          'message',
+          'string',
+          'no',
+          'A readable message of at most 2000 characters.',
+        ],
+      ],
+    },
+    {
+      type: 'prose',
+      text: 'The receipt is strict: an unknown field, a URL that is not http or https, or a filed or routed_only receipt with neither `url` nor `message` is invalid.',
+    },
+  ],
+};

package/authoring/gap-report/parse.d.mts

@@ -2,8 +2,8 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>
  * >} _GapReportReceiptDriftLock
  */
 /**
@@ -25,23 +25,23 @@ export function parseGapReportHandler(input: unknown, label?: string): GapReport
  * @returns {GapReportHandlerReceipt | null}
  */
 export function parseGapReportReceipt(input: unknown): GapReportHandlerReceipt | null;
-export type _GapReportReceiptDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>>;
-export type GapReportHandler = import("./type").GapReportHandler;
-export type GapReportHandlerReceipt = import("./type").GapReportHandlerReceipt;
+export type _GapReportReceiptDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>>;
+export type GapReportHandler = import("./type.js").GapReportHandler;
+export type GapReportHandlerReceipt = import("./type.js").GapReportHandlerReceipt;
 /**
  * Compile-time drift-lock: the sealed schema must infer EXACTLY the public
  * {@link GapReportHandler} type. If they drift, `MutuallyAssignable` becomes
  * `false` and `Expect<false>` fails `tsconfig.authoring-contract.json`.
  */
-export type _GapReportHandlerDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>>;
+export type _GapReportHandlerDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>>;
 import { z } from 'zod';
 /**
  * Compile-time drift-lock: the sealed schema must infer EXACTLY the public
  * {@link GapReportHandler} type. If they drift, `MutuallyAssignable` becomes
  * `false` and `Expect<false>` fails `tsconfig.authoring-contract.json`.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>
  * >} _GapReportHandlerDriftLock
  */
 declare const receiptSchema: z.ZodObject<{
@@ -55,9 +55,9 @@ declare const receiptSchema: z.ZodObject<{
 }, z.core.$strict>;
 declare const handlerSchema: z.ZodObject<{
     audience: z.ZodEnum<{
-        internal: "internal";
         public: "public";
+        internal: "internal";
     }>;
-    handle: z.ZodType<(report: import("./type").GapReport, context: import("./type").GapReportHandlerContext) => import("./type").GapReportHandlerReceipt | Promise<import("./type").GapReportHandlerReceipt>, any, z.core.$ZodTypeInternals<(report: import("./type").GapReport, context: import("./type").GapReportHandlerContext) => import("./type").GapReportHandlerReceipt | Promise<import("./type").GapReportHandlerReceipt>, any>>;
+    handle: z.ZodType<(report: import("./type.js").GapReport, context: import("./type.js").GapReportHandlerContext) => import("./type.js").GapReportHandlerReceipt | Promise<import("./type.js").GapReportHandlerReceipt>, any, z.core.$ZodTypeInternals<(report: import("./type.js").GapReport, context: import("./type.js").GapReportHandlerContext) => import("./type.js").GapReportHandlerReceipt | Promise<import("./type.js").GapReportHandlerReceipt>, any>>;
 }, z.core.$strict>;
 export {};

package/authoring/gap-report/parse.mjs

@@ -13,8 +13,8 @@
 import {z} from 'zod';
 import {formatZodError} from '../_shared/errors.mjs';
 
-/** @typedef {import('./type').GapReportHandler} GapReportHandler */
-/** @typedef {import('./type').GapReportHandlerReceipt} GapReportHandlerReceipt */
+/** @typedef {import('./type.js').GapReportHandler} GapReportHandler */
+/** @typedef {import('./type.js').GapReportHandlerReceipt} GapReportHandlerReceipt */
 
 // Typed z.custom so z.infer reproduces the real function type, matching the
 // pattern used by the debug handler and post-codemod hook parsers.
@@ -36,8 +36,8 @@ const handlerSchema = z
  * {@link GapReportHandler} type. If they drift, `MutuallyAssignable` becomes
  * `false` and `Expect<false>` fails `tsconfig.authoring-contract.json`.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>
  * >} _GapReportHandlerDriftLock
  */
 
@@ -50,8 +50,8 @@ const receiptSchema = z
   .strict();
 
 /**
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>
  * >} _GapReportReceiptDriftLock
  */
 

package/authoring/gap-report/type.ts

@@ -14,7 +14,7 @@
  * gap-report handlers.
  */
 
-import type {DebugInvocationSource} from '../debug/type';
+import type {DebugInvocationSource} from '../debug/type.js';
 
 /** Supported gap-report categories. */
 export type GapReportCategory =

package/authoring/identity/identity.doc.d.mts

@@ -0,0 +1,9 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for provider, artifact, and immutable instance identity.
+ * @position packages/cli/authoring/identity — identity documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

package/authoring/identity/identity.doc.mjs

@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for provider, artifact, and immutable instance identity.
+ * @position packages/cli/authoring/identity — identity documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+  type: 'schema',
+  name: 'provider-identity',
+  displayName: 'Provider and artifact identity',
+  namespace: 'authoring',
+  description:
+    'Separates stable provider/artifact identity from package instances and runtime lifecycle state. Provider identity names integration manifests and settles provider conflicts. Docs-tree nodes are identified by doc identity; the tree covers the CLI\'s own docs. Artifact, instance, and compiler-input identities are defined for every provider-owned artifact; no command reads them.',
+  appliesTo:
+    'Integration manifests, provider conflicts, and docs-tree node ids.',
+  fields: [
+    {
+      name: 'ProviderId',
+      type: 'string',
+      description:
+        'Canonical logical provider ID. It defaults to the lowercase npm package name; Core uses the same model without publishing an integration manifest.',
+      required: true,
+    },
+    {
+      name: 'ArtifactId',
+      type: 'string',
+      description:
+        'Versioned serialization of provider ID, contribution kind, and stable artifact name. Every segment uses RFC 3986 escaping.',
+      required: true,
+    },
+    {
+      name: 'DocId',
+      type: 'ArtifactId',
+      description:
+        'Artifact ID restricted to one authored doc kind. Navigation changes do not change it.',
+      required: true,
+    },
+    {
+      name: 'ProviderInstance',
+      type: '{ id; providerId; packageName; packageVersion; sourceDigest }',
+      description:
+        'One immutable package version and source/content digest. Installed, configured, loaded, selected, and healthy state is a separate runtime overlay.',
+      required: true,
+    },
+    {
+      name: 'AuthoredDocEntry',
+      type: '{ id; provider; kind; stableName; source; authored }',
+      description:
+        'Normalized compiler input. Discovery supplies stableName independently from the authored display name, source paths remain package-relative, and provider provenance plus the authored snapshot are immutable.',
+      required: true,
+    },
+  ],
+  notes: [
+    {
+      type: 'prose',
+      text: 'Provider package renames require an explicit mapping: a ProviderInstance may retain its stable providerId while packageName changes. Silent identity changes are not inferred.',
+    },
+  ],
+};

package/authoring/identity/type.ts

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Stable provider, artifact, and authored-doc entry contracts.
+ *
+ * Logical IDs exclude installed/configured/loaded/healthy state. A concrete
+ * provider instance adds package version and a content digest, while an
+ * artifact ID stays stable across those instances.
+ */
+
+import type {AuthoredDocKind} from '../doctypes/base/type.js';
+import type {CommandDoc} from '../doctypes/command/type.js';
+import type {ComponentDoc} from '../doctypes/component/type.js';
+import type {EnumDoc} from '../doctypes/enum/type.js';
+import type {FunctionDoc} from '../doctypes/function/type.js';
+import type {HookDoc} from '../doctypes/hook/type.js';
+import type {NamespaceDoc} from '../doctypes/namespace/type.js';
+import type {ReferenceDoc} from '../doctypes/reference/type.js';
+import type {SchemaDoc} from '../doctypes/schema/type.js';
+import type {TemplateDoc} from '../doctypes/template/type.js';
+
+declare const providerIdBrand: unique symbol;
+declare const artifactIdBrand: unique symbol;
+declare const docIdBrand: unique symbol;
+declare const providerInstanceIdBrand: unique symbol;
+declare const contentDigestBrand: unique symbol;
+
+/** Canonical provider identity. It defaults to the normalized npm package name. */
+export type ProviderId = string & {readonly [providerIdBrand]: true};
+
+/** Stable provider + contribution kind + artifact-name identity. */
+export type ArtifactId = string & {readonly [artifactIdBrand]: true};
+
+/** ArtifactId narrowed to an authored documentation kind. */
+export type DocId = ArtifactId & {readonly [docIdBrand]: true};
+
+/** Immutable provider version + source/content digest identity. */
+export type ProviderInstanceId = string & {
+  readonly [providerInstanceIdBrand]: true;
+};
+
+/** Lowercase `sha256:<64 hex characters>` digest. */
+export type ContentDigest = string & {readonly [contentDigestBrand]: true};
+
+/** Every stable artifact kind owned by a provider. */
+export type ContributionKind =
+  AuthoredDocKind | 'theme' | 'codemod' | 'agent-doc';
+
+/** Stable logical identity for one provider-owned artifact. */
+export interface ArtifactIdentity {
+  readonly id: ArtifactId;
+  readonly providerId: ProviderId;
+  readonly kind: ContributionKind;
+  readonly name: string;
+}
+
+/** One immutable package instance. Runtime lifecycle state does not belong here. */
+export interface ProviderInstance {
+  readonly id: ProviderInstanceId;
+  readonly providerId: ProviderId;
+  readonly packageName: string;
+  readonly packageVersion: string;
+  readonly sourceDigest: ContentDigest;
+}
+
+/** Every authored value accepted by the documentation compiler boundary. */
+export type AuthoredDoc =
+  | ComponentDoc
+  | HookDoc
+  | FunctionDoc
+  | ReferenceDoc
+  | TemplateDoc
+  | SchemaDoc
+  | CommandDoc
+  | EnumDoc
+  | NamespaceDoc;
+
+/** Provenance attached by discovery before compilation. */
+export interface AuthoredDocSource {
+  /** Provider-local logical discovery group. */
+  readonly group: string;
+  /** Package-relative source path; excluded from compiled renderer data. */
+  readonly path: string;
+  /** Digest of the authored source bytes. */
+  readonly digest: ContentDigest;
+}
+
+/** Authored kind that corresponds to one public document type. */
+export type AuthoredDocKindOf<TDoc extends AuthoredDoc> =
+  TDoc extends ComponentDoc
+    ? 'component'
+    : TDoc extends HookDoc | FunctionDoc
+      ? 'function'
+      : TDoc extends ReferenceDoc
+        ? 'generic'
+        : TDoc extends TemplateDoc
+          ? TDoc['type']
+          : TDoc extends SchemaDoc
+            ? 'schema'
+            : TDoc extends CommandDoc
+              ? 'command'
+              : TDoc extends EnumDoc
+                ? 'enum'
+                : TDoc extends NamespaceDoc
+                  ? 'namespace'
+                  : never;
+
+type DeepReadonly<Value> = Value extends (...args: never[]) => unknown
+  ? Value
+  : Value extends readonly (infer Item)[]
+    ? readonly DeepReadonly<Item>[]
+    : Value extends object
+      ? {readonly [Key in keyof Value]: DeepReadonly<Value[Key]>}
+      : Value;
+
+/** Immutable authored-data snapshot stored in a compiler entry. */
+export type AuthoredDocSnapshot<TDoc extends AuthoredDoc = AuthoredDoc> =
+  DeepReadonly<TDoc>;
+
+/**
+ * One normalized compiler input. Stable identity is provider + authored kind +
+ * stable name; provider version and source bytes remain explicit provenance.
+ */
+export interface AuthoredDocEntry<TDoc extends AuthoredDoc = AuthoredDoc> {
+  readonly id: DocId;
+  readonly provider: ProviderInstance;
+  readonly kind: AuthoredDocKindOf<TDoc>;
+  /** Stable provider-local key used in the DocId; it need not equal a display name. */
+  readonly stableName: string;
+  readonly source: AuthoredDocSource;
+  readonly authored: AuthoredDocSnapshot<TDoc>;
+}

package/authoring/index.d.mts

@@ -3,6 +3,7 @@
 
 export { parseConfig } from "./config/parse.mjs";
 export { parseIntegration } from "./integration/parse.mjs";
+export { parseDiscoverCatalog } from "./discover/parse.mjs";
 export { parseCodemod } from "./codemod/parse.mjs";
 export { parseDebugEvent } from "./debug/parse.mjs";
 export { parseDoc } from "./doctypes/parse.mjs";
@@ -14,5 +15,7 @@ export { parseTemplate } from "./doctypes/template/parse.mjs";
 export { parseSchema } from "./doctypes/schema/parse.mjs";
 export { parseCommand } from "./doctypes/command/parse.mjs";
 export { parseEnum } from "./doctypes/enum/parse.mjs";
+export { parseNamespace } from "./doctypes/namespace/parse.mjs";
+export { parseTheme } from "./doctypes/theme/parse.mjs";
 export { parseLegacyDoc } from "./doctypes/legacy.mjs";
 export { parseGapReportHandler, parseGapReportReceipt } from "./gap-report/parse.mjs";

package/authoring/index.d.ts

@@ -23,17 +23,19 @@
 // ═══════════════════════════════════════════════════════════════════════
 // AUTHOR THESE — each is the default export of one authored file.
 // ═══════════════════════════════════════════════════════════════════════
-export type {ComponentDoc} from './doctypes/types'; //   Button.doc.{ts,mjs}
-export type {HookDoc} from './doctypes/types'; //         useToast.doc.{ts,mjs}
-export type {FunctionDoc} from './doctypes/types'; //     search.doc.mjs (hook | api)
-export type {ReferenceDoc} from './doctypes/types'; //    theming.doc.{ts,mjs}
-export type {TemplateDoc} from './doctypes/types'; //     Foo.template.{ts,mjs}
-export type {SchemaDoc} from './doctypes/types'; //       config.doc.mjs (object shape)
-export type {CommandDoc} from './doctypes/types'; //      search.doc.mjs (CLI command)
-export type {EnumDoc} from './doctypes/types'; //         error-codes.doc.mjs (vocabulary)
-export type {AstryxConfig} from './config/type'; //       astryx.config.{ts,mjs}
-export type {DebugEvent} from './debug/type'; //          one recorded CLI run
-export type {AstryxIntegration} from './integration/type'; // astryx.integration.{ts,mjs}
+export type {ComponentDoc} from './doctypes/types.js'; //   Button.doc.mjs
+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 {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)
+export type {NamespaceDoc} from './doctypes/types.js'; //    cli.doc.mjs (hierarchy)
+export type {ThemeDoc} from './doctypes/types.js'; //        oceanTheme.doc.mjs
+export type {AstryxConfig} from './config/type.js'; //       astryx.config.{ts,mjs}
+export type {DebugEvent} from './debug/type.js'; //          one recorded CLI run
+export type {AstryxIntegration} from './integration/type.js'; // astryx.integration.{ts,mjs}
 export type {
   GapReportHandler,
   GapReportHandlerContext,
@@ -41,8 +43,17 @@ export type {
   GapReportCategory,
   GapReportTarget,
   GapReportHandlerReceipt,
-} from './gap-report/type'; // gap-report handler contract
-export type {AstryxCodemod, AstryxConfigCodemod} from './codemod/type'; // codemods/*
+} from './gap-report/type.js'; // gap-report handler contract
+export type {
+  DiscoverSource,
+  DiscoverSourceContext,
+  DiscoverCatalog,
+  DiscoverPackage,
+  DiscoverVersion,
+  DiscoverContribution,
+  DiscoverKind,
+} from './discover/type.js'; // discover source contract
+export type {AstryxCodemod, AstryxConfigCodemod} from './codemod/type.js'; // codemods/*
 
 // ═══════════════════════════════════════════════════════════════════════
 // PARSERS — the CLI's load boundary (types come from each parser's JSDoc).
@@ -56,6 +67,8 @@ export {parseTemplate} from './doctypes/template/parse.mjs';
 export {parseSchema} from './doctypes/schema/parse.mjs';
 export {parseCommand} from './doctypes/command/parse.mjs';
 export {parseEnum} from './doctypes/enum/parse.mjs';
+export {parseNamespace} from './doctypes/namespace/parse.mjs';
+export {parseTheme} from './doctypes/theme/parse.mjs';
 export {parseLegacyDoc} from './doctypes/legacy.mjs';
 export {parseConfig} from './config/parse.mjs';
 export {parseIntegration} from './integration/parse.mjs';
@@ -63,6 +76,7 @@ export {
   parseGapReportHandler,
   parseGapReportReceipt,
 } from './gap-report/parse.mjs';
+export {parseDiscoverCatalog} from './discover/parse.mjs';
 export {parseCodemod} from './codemod/parse.mjs';
 export {parseDebugEvent} from './debug/parse.mjs';
 
@@ -72,6 +86,26 @@ export {parseDebugEvent} from './debug/parse.mjs';
 // need them to author. Names carry the doc kind they belong to.
 // ═══════════════════════════════════════════════════════════════════════
 export type {
+  ProviderId,
+  ArtifactId,
+  DocId,
+  ProviderInstanceId,
+  ContentDigest,
+  ContributionKind,
+  ArtifactIdentity,
+  ProviderInstance,
+  AuthoredDoc,
+  AuthoredDocKindOf,
+  AuthoredDocSnapshot,
+  AuthoredDocSource,
+  AuthoredDocEntry,
+} from './identity/type.js';
+export type {
+  // shared graph
+  AuthoredDocKind,
+  DocAudience,
+  DocPlacement,
+  AuthoredDocGraphFields,
   // component
   SingleComponentDoc,
   MultiComponentDoc,
@@ -107,8 +141,19 @@ export type {
   // reference
   ReferenceSection,
   ReferenceContentBlock,
+  GraphContentBlock,
   ReferenceTokenPreviewType,
   ReferenceTranslationDoc,
+  WorkflowStep,
+  WorkflowDocBlock,
+  CollectionDocBlock,
+  ReferenceDocBlock,
+  // namespace
+  NamespaceProviderScope,
+  NamespaceSlotAcceptance,
+  NamespaceSlot,
+  NamespaceAdoptionSource,
+  NamespaceAdoptionRule,
   // template
   TemplateCategory,
   // schema
@@ -119,8 +164,8 @@ export type {
   CommandExampleDoc,
   // enum
   EnumMemberDoc,
-} from './doctypes/types';
-export type {PostCodemodHook, DebugConfig} from './config/type';
+} from './doctypes/types.js';
+export type {PostCodemodHook, DebugConfig} from './config/type.js';
 export type {
   // debug
   DebugSchemaVersion,
@@ -133,11 +178,11 @@ export type {
   DebugEventEnv,
   DebugEventProject,
   DebugEventHandler,
-} from './debug/type';
+} from './debug/type.js';
 export type {
   AstryxCodemodDef,
   AstryxConfigCodemodDef,
   AstryxCodemodFile,
   AstryxCodemodApi,
   AstryxCodemodTransform,
-} from './codemod/type';
+} from './codemod/type.js';

package/authoring/index.mjs

@@ -11,7 +11,7 @@
  * `type` directly.
  *
  * Types (config, integration, codemod, and the doc vocabulary —
- * component/hook/reference/template) are re-exported via `./index.ts`.
+ * component/hook/reference/template/theme) are re-exported via `./index.ts`.
  */
 
 export {parseConfig} from './config/parse.mjs';
@@ -20,6 +20,7 @@ export {
   parseGapReportHandler,
   parseGapReportReceipt,
 } from './gap-report/parse.mjs';
+export {parseDiscoverCatalog} from './discover/parse.mjs';
 export {parseCodemod} from './codemod/parse.mjs';
 export {parseDebugEvent} from './debug/parse.mjs';
 export {parseDoc} from './doctypes/parse.mjs';
@@ -31,4 +32,6 @@ export {parseTemplate} from './doctypes/template/parse.mjs';
 export {parseSchema} from './doctypes/schema/parse.mjs';
 export {parseCommand} from './doctypes/command/parse.mjs';
 export {parseEnum} from './doctypes/enum/parse.mjs';
+export {parseNamespace} from './doctypes/namespace/parse.mjs';
+export {parseTheme} from './doctypes/theme/parse.mjs';
 export {parseLegacyDoc} from './doctypes/legacy.mjs';