@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/authoring/doctypes/hook/type.ts

@@ -5,13 +5,14 @@
  */
 
 import type {
+  AuthoredDocGraphFields,
   ComponentAccessibilityRequirement,
   ComponentBestPractice,
   HookParamDoc,
   HookReturnDoc,
   RegistryDocIdentity,
   UsageDoc,
-} from '../base/type';
+} from '../base/type.js';
 
 /**
  * Documentation for a standalone hook's .doc.mjs file.
@@ -22,12 +23,12 @@ import type {
  * Standalone hooks (e.g. useMediaQuery, useFocusTrap, useOverflow) get
  * their own {hookName}.doc.mjs file and use this type.
  *
- * Every hook .doc.mjs must export a single `docs` constant:
+ * Every new hook .doc.mjs default-exports a stamped object:
  *
  *   /\*\* @type {import('@astryxdesign/cli/authoring').HookDoc} \*\/
- *   export const docs = { ... };
+ *   export default { type: 'function', ... };
  */
-export interface HookDoc {
+export interface HookDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant for the stamped default-export format
    *  (`export default { type: 'function', ... }`). Optional: legacy
    *  `export const docs = {...}` docs omit it. */

package/authoring/doctypes/legacy.d.mts

@@ -1,15 +1,17 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('./types').ComponentDoc} ComponentDoc */
-/** @typedef {import('./types').HookDoc} HookDoc */
+/** @typedef {import('./types.js').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types.js').HookDoc} HookDoc */
+/** @typedef {import('./types.js').ReferenceDoc} ReferenceDoc */
 /**
  * Validate an unknown value as a legacy (unstamped) doc, or throw.
  *
  * @param {unknown} input
  * @param {string} [label]
- * @returns {ComponentDoc | HookDoc}
+ * @returns {ComponentDoc | HookDoc | ReferenceDoc}
  */
-export function parseLegacyDoc(input: unknown, label?: string): ComponentDoc | HookDoc;
-export type ComponentDoc = import("./types").ComponentDoc;
-export type HookDoc = import("./types").HookDoc;
+export function parseLegacyDoc(input: unknown, label?: string): ComponentDoc | HookDoc | ReferenceDoc;
+export type ComponentDoc = import("./types.js").ComponentDoc;
+export type HookDoc = import("./types.js").HookDoc;
+export type ReferenceDoc = import("./types.js").ReferenceDoc;

package/authoring/doctypes/legacy.mjs

@@ -10,20 +10,21 @@
 import {LegacyDocSchema} from './_schema.mjs';
 import {formatZodError} from '../_shared/errors.mjs';
 
-/** @typedef {import('./types').ComponentDoc} ComponentDoc */
-/** @typedef {import('./types').HookDoc} HookDoc */
+/** @typedef {import('./types.js').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types.js').HookDoc} HookDoc */
+/** @typedef {import('./types.js').ReferenceDoc} ReferenceDoc */
 
 /**
  * Validate an unknown value as a legacy (unstamped) doc, or throw.
  *
  * @param {unknown} input
  * @param {string} [label]
- * @returns {ComponentDoc | HookDoc}
+ * @returns {ComponentDoc | HookDoc | ReferenceDoc}
  */
 export function parseLegacyDoc(input, label = 'doc') {
   const result = LegacyDocSchema.safeParse(input);
   if (!result.success) {
     throw new Error(formatZodError(label, result.error));
   }
-  return /** @type {ComponentDoc | HookDoc} */ (result.data);
+  return /** @type {ComponentDoc | HookDoc | ReferenceDoc} */ (result.data);
 }

package/authoring/doctypes/load-contract.test.mjs

@@ -0,0 +1,233 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every authored doc kind has a compile-time lock between its load check
+ * and its published type: the `_*DriftLock` typedefs in `_schema.mjs` and
+ * `template/parse.mjs`, which the strict typecheck evaluates. A lock names each
+ * place the loader is deliberately looser than the type. These tests pin that
+ * looser behavior and the published unknown-field policy, so tightening a load
+ * check is a reviewed change rather than a silent one.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {describe, expect, it} from 'vitest';
+import {parseDoc} from './parse.mjs';
+import {AuthoredDocKindSchema} from './_schema.mjs';
+import {doc as graphFieldsDoc} from './base/graph-fields.doc.mjs';
+import {problemsInTopic} from '../../foundation/discovery/docs-discovery.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const KINDS = AuthoredDocKindSchema.options;
+
+/** The lock that pins each kind's load check to its published type. */
+const LOCKS = {
+  component: '_ComponentDocDriftLock',
+  function: '_FunctionDocDriftLock',
+  generic: '_ReferenceDocDriftLock',
+  page: '_PageTemplateDocDriftLock',
+  block: '_BlockTemplateDocDriftLock',
+  schema: '_SchemaDocDriftLock',
+  command: '_CommandDocDriftLock',
+  enum: '_EnumDocDriftLock',
+  namespace: '_NamespaceDocDriftLock',
+};
+
+/** One valid example doc per kind, from the typed examples. */
+const EXAMPLES = Object.fromEntries(
+  await Promise.all(
+    KINDS.map(async kind => {
+      const file = {generic: 'reference', function: 'function'}[kind] ?? kind;
+      const url = pathToFileURL(
+        path.join(HERE, '../../test/authoring-types', `${file}.doc.mjs`),
+      );
+      return [kind, (await import(url.href)).docs];
+    }),
+  ),
+);
+
+describe('load check vs published type', () => {
+  it('locks every doc kind', () => {
+    const source = ['_schema.mjs', 'template/parse.mjs', 'theme/parse.mjs']
+      .map(file => fs.readFileSync(path.join(HERE, file), 'utf8'))
+      .join('\n');
+    expect(Object.keys(LOCKS).sort()).toEqual([...KINDS].sort());
+    const locks = [
+      ...Object.values(LOCKS),
+      '_AuthoredDocKindDriftLock',
+      '_HookDocIsFunctionDocLock',
+      '_ThemeDocDriftLock',
+    ];
+    for (const lock of locks) {
+      expect(source, `${lock} is missing`).toMatch(
+        new RegExp(`\\}\\s*${lock}\\b`),
+      );
+    }
+  });
+
+  it('dispatches every doc kind and refuses any other', () => {
+    for (const kind of KINDS) {
+      expect(() => parseDoc(EXAMPLES[kind], `${kind}.doc.mjs`)).not.toThrow();
+    }
+    expect(() => parseDoc({type: 'widget', name: 'x'}, 'x.doc.mjs')).toThrow(
+      /x\.doc\.mjs is invalid/u,
+    );
+  });
+});
+
+describe('where loading is deliberately looser than the type', () => {
+  it('a stamped component needs no displayName; usage, theming and examples are unchecked', () => {
+    expect(() =>
+      parseDoc(
+        {
+          type: 'component',
+          name: 'Badge',
+          category: 'badges',
+          props: [],
+          usage: 'free text',
+          theming: 5,
+          examples: [{title: 'Basic'}],
+        },
+        'Badge.doc.mjs',
+      ),
+    ).not.toThrow();
+  });
+
+  it('each entry of a stamped group doc needs a name, and nothing more', () => {
+    const group = (/** @type {unknown[]} */ components) => ({
+      type: 'component',
+      name: 'Tabs',
+      components,
+    });
+    expect(() =>
+      parseDoc(
+        group([{name: 'Tab'}, {name: 'TabPanel', description: 'x'}]),
+        'Tabs.doc.mjs',
+      ),
+    ).not.toThrow();
+    for (const bad of [null, 5, 'Tab', {}, {name: ''}, {displayName: 'Tab'}]) {
+      expect(() => parseDoc(group([bad]), 'Tabs.doc.mjs')).toThrow(
+        /components\.0/,
+      );
+    }
+  });
+
+  it('a stamped function needs no displayName; usage is unchecked', () => {
+    expect(() =>
+      parseDoc(
+        {type: 'function', name: 'useX', params: [], returns: [], usage: 5},
+        'useX.doc.mjs',
+      ),
+    ).not.toThrow();
+  });
+
+  it('a stamped generic doc loads without title, description or sections, but is no topic', () => {
+    const doc = parseDoc({type: 'generic', name: 'notes'}, 'notes.doc.mjs');
+    expect(doc.title).toBe('notes');
+    expect(problemsInTopic(doc)).toEqual([
+      'description: expected a non-empty string',
+      'sections: expected at least one section',
+    ]);
+  });
+
+  it('a template needs no displayName or aspectRatio and may use its own category', () => {
+    expect(() =>
+      parseDoc(
+        {type: 'block', name: 'widget-demo', category: 'components/Widget'},
+        'widget-demo.doc.mjs',
+      ),
+    ).not.toThrow();
+    expect(() =>
+      parseDoc(
+        {type: 'page', name: 'widget-page', category: 'Widgets'},
+        'widget-page.doc.mjs',
+      ),
+    ).not.toThrow();
+  });
+
+  it('schema, command and enum docs load only as their type allows', () => {
+    const {fields, ...schemaDoc} = EXAMPLES.schema;
+    const {summary, ...commandDoc} = EXAMPLES.command;
+    const {members, ...enumDoc} = EXAMPLES.enum;
+    expect(() => parseDoc(schemaDoc, 's.doc.mjs')).toThrow(/fields/);
+    expect(() => parseDoc(commandDoc, 'c.doc.mjs')).toThrow(/summary/);
+    expect(() => parseDoc(enumDoc, 'e.doc.mjs')).toThrow(/members/);
+  });
+});
+
+describe('unknown fields', () => {
+  const keeps = KINDS.filter(kind => {
+    try {
+      parseDoc({...EXAMPLES[kind], notAField: true}, `${kind}.doc.mjs`);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+
+  it('match the published policy', () => {
+    const policy = graphFieldsDoc.notes
+      .map(note => ('text' in note ? note.text : ''))
+      .find(text => text.startsWith('Unknown fields'));
+    expect(policy, 'graph-fields.doc.mjs states the policy').toBeDefined();
+    const [kept, refused] = /** @type {string} */ (policy).split(
+      ' docs accept',
+    );
+    const named = (/** @type {string} */ text) =>
+      [...text.matchAll(/`([a-z]+)`/g)].map(match => match[1]).sort();
+    expect(named(kept)).toEqual([...keeps].sort());
+    expect(named(refused).filter(kind => KINDS.includes(kind))).toEqual(
+      KINDS.filter(kind => !keeps.includes(kind)).sort(),
+    );
+  });
+
+  it("are refused inside a section's reference block, which a section takes", () => {
+    const [section] = EXAMPLES.generic.sections;
+    const reference = {
+      type: 'reference',
+      target: '@astryxdesign/cli:schema:integration',
+      projection: {fields: ['docs']},
+      presentation: 'compact',
+    };
+    /** @param {object} block */
+    const withBlock = block =>
+      parseDoc(
+        {...EXAMPLES.generic, sections: [{...section, content: [block]}]},
+        'r.doc.mjs',
+      );
+    expect(() => withBlock(reference)).not.toThrow();
+    expect(() => withBlock({...reference, notAField: true})).toThrow();
+    expect(() =>
+      withBlock({...reference, projection: {fields: ['docs'], rows: []}}),
+    ).toThrow();
+    // Workflow and collection blocks belong to a namespace doc.
+    expect(() =>
+      withBlock({type: 'collection', source: {slot: 'guides'}}),
+    ).toThrow();
+  });
+
+  it('are refused inside sections and content blocks', () => {
+    const [section] = EXAMPLES.generic.sections;
+    expect(() =>
+      parseDoc(
+        {...EXAMPLES.generic, sections: [{...section, notAField: true}]},
+        'r.doc.mjs',
+      ),
+    ).toThrow();
+    expect(() =>
+      parseDoc(
+        {
+          ...EXAMPLES.generic,
+          sections: [
+            {
+              ...section,
+              content: [{type: 'prose', text: 'x', notAField: true}],
+            },
+          ],
+        },
+        'r.doc.mjs',
+      ),
+    ).toThrow();
+  });
+});

package/authoring/doctypes/namespace/namespace.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 NamespaceDoc, the authored hierarchy and layout owner.
+ * @position packages/cli/authoring/doctypes/namespace — doc-type documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

package/authoring/doctypes/namespace/namespace.doc.mjs

@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for NamespaceDoc, the authored hierarchy and layout owner.
+ * @position packages/cli/authoring/doctypes/namespace — doc-type documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+  type: 'schema',
+  name: 'namespace-doc',
+  displayName: 'NamespaceDoc',
+  namespace: 'authoring',
+  description:
+    "Declares one level of the docs tree: named slots, and adoption rules for already-discovered docs. It never scans folders, lists its children, or copies child documents: a child names its parent with `placement`, or a namespace adopts a discovery group. `astryx docs <route>` lists each slot's children one level down. The CLI keeps its namespace docs in its docs tree directory; an integration ships its own in its docs directory, and they appear in `astryx docs` beside the CLI's.",
+  appliesTo: '<namespace>.doc.mjs',
+  fields: [
+    {
+      name: 'type',
+      type: "'namespace'",
+      description: 'Doc-kind discriminant.',
+      required: true,
+    },
+    {
+      name: 'name',
+      type: 'string',
+      description:
+        'Stable provider-local identity. Moving the namespace does not change this value.',
+      required: true,
+    },
+    {
+      name: 'title',
+      type: 'string',
+      description: 'Human-readable page title.',
+      required: true,
+    },
+    {
+      name: 'summary',
+      type: 'string',
+      description: 'One-line summary used in listings and search results.',
+      required: true,
+    },
+    {
+      name: 'placement',
+      type: 'DocPlacement',
+      description:
+        'Optional canonical parent: {parent, slot?, order?}. `parent` names a namespace of the same package as `namespace:<name>`. An invalid placement withdraws the namespace with a diagnostic; it never falls back.',
+    },
+    {
+      name: 'aliases',
+      type: 'string[]',
+      description:
+        'Prior names or routes the docs tree will keep resolving to this doc. Not read yet.',
+    },
+    {
+      name: 'audience',
+      type: "'public' | 'internal'",
+      description: "Bundle audience. Defaults to 'public'.",
+      default: "'public'",
+    },
+    {
+      name: 'keywords',
+      type: 'string[]',
+      description: 'Search terms not already present in the title or summary.',
+    },
+    {
+      name: 'slots',
+      type: 'Record<string, NamespaceSlot>',
+      description:
+        'Named placement and collection targets. Each slot declares a title and accepted doc kinds; configured providers require an explicit extension slot.',
+      required: true,
+    },
+    {
+      name: 'adopts',
+      type: 'NamespaceAdoptionRule[]',
+      description:
+        'Provider-local rules that adopt otherwise-unplaced docs from a logical discovery group. They never scan a folder.',
+    },
+    {
+      name: 'blocks',
+      type: '(ReferenceContentBlock | GraphContentBlock)[]',
+      description:
+        'Ordered layout content for the namespace page. Graph-only workflow, collection, and reference blocks are available here without widening the stable ReferenceContentBlock union used by existing topic renderers. Not rendered yet: `astryx docs <route>` lists every slot and its children in order.',
+    },
+  ],
+  examples: [
+    {
+      label: 'A CLI namespace with one adopted source group',
+      code: `/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'cli',
+  title: 'Astryx CLI',
+  summary: 'Commands, APIs, and integration authoring.',
+  slots: {
+    guides: {title: 'Guides', accepts: {kinds: ['namespace', 'generic']}},
+    reference: {
+      title: 'Reference',
+      accepts: {kinds: ['namespace', 'command']},
+    },
+  },
+  adopts: [{
+    source: {group: 'cli-commands', kinds: ['command']},
+    into: 'reference',
+  }],
+};`,
+    },
+  ],
+  notes: [
+    {
+      type: 'prose',
+      text: "The docs tree reads namespace docs from the CLI and from every configured integration. An integration's namespace doc is a top-level level of the tree, and its guides name it with `placement`; a doc can be placed only in a namespace of its own package. When two packages claim one route, the CLI's own docs win, then integrations in configured order, and `astryx doctor` names the loser.",
+    },
+    {
+      type: 'prose',
+      text: 'Child docs request one canonical home with placement. Collections store and render stable references to those docs; they never create a second identity or parent.',
+    },
+    {
+      type: 'list',
+      style: 'dont',
+      items: [
+        'Use a directory as implicit navigation.',
+        'Put JSX, HTML, ANSI, callbacks, or custom renderer code in a doc.',
+        'Use choice, callout, or checklist blocks before the full block-extension contract exists.',
+      ],
+    },
+  ],
+};

package/authoring/doctypes/namespace/parse.d.mts

@@ -0,0 +1,12 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/** @typedef {import('../types.js').NamespaceDoc} NamespaceDoc */
+/**
+ * Validate an unknown value as a NamespaceDoc, or throw a readable error.
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {NamespaceDoc}
+ */
+export function parseNamespace(input: unknown, label?: string): NamespaceDoc;
+export type NamespaceDoc = import("../types.js").NamespaceDoc;

package/authoring/doctypes/namespace/parse.mjs

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Namespace doc parser. Zod is sealed in `../_schema.mjs`; consumers call
+ * `parseNamespace` or use `parseDoc`.
+ */
+
+import {NamespaceDocKindSchema} from '../_schema.mjs';
+import {formatZodError} from '../../_shared/errors.mjs';
+
+/** @typedef {import('../types.js').NamespaceDoc} NamespaceDoc */
+
+/**
+ * Validate an unknown value as a NamespaceDoc, or throw a readable error.
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {NamespaceDoc}
+ */
+export function parseNamespace(input, label = 'namespace doc') {
+  const result = NamespaceDocKindSchema.safeParse(input);
+  if (!result.success) {
+    throw new Error(formatZodError(label, result.error));
+  }
+  return result.data;
+}

package/authoring/doctypes/namespace/parse.test.mjs

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {parseDoc, parseNamespace, parseReference} from '../../index.mjs';
+
+const namespaceDoc = {
+  type: 'namespace',
+  name: 'integrations',
+  title: 'Author integrations',
+  summary: 'Publish reusable Astryx packages.',
+  aliases: ['cli-integrations'],
+  placement: {parent: 'namespace:cli', slot: 'guides', order: 10},
+  slots: {
+    contributions: {
+      title: 'What do you want to publish?',
+      accepts: {kinds: ['namespace']},
+    },
+    providerGuides: {
+      title: 'Provider guidance',
+      accepts: {providers: 'configured', kinds: ['generic', 'schema']},
+    },
+  },
+  adopts: [
+    {
+      source: {group: 'cli-api', kinds: ['function', 'schema', 'enum']},
+      into: 'contributions',
+      groupBy: 'kind',
+    },
+  ],
+  blocks: [
+    {
+      type: 'workflow',
+      title: 'Package lifecycle',
+      steps: [
+        {title: 'Add', references: ['command:integration-add']},
+        {
+          title: 'Validate',
+          references: ['command:doctor-integration-validate'],
+        },
+      ],
+    },
+    {
+      type: 'collection',
+      source: {slot: 'contributions'},
+      presentation: 'cards',
+    },
+    {
+      type: 'reference',
+      target: 'schema:integration',
+      projection: {fields: ['components', 'docs']},
+    },
+  ],
+};
+
+describe('NamespaceDoc', () => {
+  it('accepts the reviewed plain-object shape through both parsers', () => {
+    expect(parseNamespace(namespaceDoc)).toEqual(namespaceDoc);
+    expect(parseDoc(namespaceDoc)).toEqual(namespaceDoc);
+  });
+
+  it('reports stable nested field paths', () => {
+    expect(() =>
+      parseNamespace({
+        ...namespaceDoc,
+        blocks: [{type: 'workflow', steps: [{title: ''}]}],
+      }),
+    ).toThrow(/blocks\.0\.steps\.0\.title/u);
+  });
+
+  it.each(['choice', 'callout', 'checklist'])(
+    'rejects unsupported %s blocks',
+    type => {
+      expect(() => parseNamespace({...namespaceDoc, blocks: [{type}]})).toThrow(
+        /blocks\.0\.type/u,
+      );
+    },
+  );
+
+  it('rejects misspelled fields instead of silently dropping them', () => {
+    expect(() =>
+      parseNamespace({...namespaceDoc, summmary: 'misspelled'}),
+    ).toThrow(/summmary/u);
+  });
+
+  it('requires at least one declared slot', () => {
+    expect(() => parseNamespace({...namespaceDoc, slots: {}})).toThrow(
+      /at least one slot is required/u,
+    );
+  });
+
+  it('rejects a collection that names an undeclared slot', () => {
+    expect(() =>
+      parseNamespace({
+        ...namespaceDoc,
+        blocks: [{type: 'collection', source: {slot: 'missing'}}],
+      }),
+    ).toThrow(/blocks\.0\.source\.slot.*declared slot/u);
+  });
+
+  it('rejects an adoption rule that names an undeclared slot', () => {
+    expect(() =>
+      parseNamespace({
+        ...namespaceDoc,
+        adopts: [{source: {group: 'cli-api'}, into: 'missing'}],
+      }),
+    ).toThrow(/adopts\.0\.into.*declared slot/u);
+  });
+
+  it('rejects an adoption rule whose generated kind is not accepted', () => {
+    expect(() =>
+      parseNamespace({
+        ...namespaceDoc,
+        adopts: [
+          {
+            source: {group: 'cli-api', kinds: ['command']},
+            into: 'providerGuides',
+            groupBy: 'kind',
+          },
+        ],
+      }),
+    ).toThrow(/does not accept adopted kind "namespace"/u);
+
+    expect(() =>
+      parseNamespace({
+        ...namespaceDoc,
+        adopts: [
+          {
+            source: {group: 'cli-api', kinds: ['command']},
+            into: 'providerGuides',
+          },
+        ],
+      }),
+    ).toThrow(/does not accept adopted kind "command"/u);
+  });
+});
+
+describe('semantic graph blocks', () => {
+  it('keeps graph-only blocks out of the stable ReferenceDoc section union', () => {
+    expect(() =>
+      parseReference({
+        type: 'generic',
+        name: 'publishing',
+        title: 'Publishing',
+        description: 'Publish an integration.',
+        sections: [
+          {
+            id: 'start',
+            title: 'Start',
+            content: namespaceDoc.blocks,
+          },
+        ],
+      }),
+    ).toThrow(/Invalid discriminator value/u);
+  });
+
+  it('keeps shape-sniffing an unknown stamp for 0.6.x compatibility', () => {
+    expect(parseDoc({type: 'choice', name: 'x', props: []})).toMatchObject({
+      type: 'choice',
+      name: 'x',
+      props: [],
+    });
+  });
+});