@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9e4c545

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

@@ -1,7 +1,7 @@
 // @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').FunctionDoc} FunctionDoc */
+/** @typedef {import('../types.js').FunctionDoc} FunctionDoc */
 /**
  * Validate an unknown value as a stamped function doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {FunctionDoc}
  */
 export function parseFunction(input: unknown, label?: string): FunctionDoc;
-export type FunctionDoc = import("../types").FunctionDoc;
+export type FunctionDoc = import("../types.js").FunctionDoc;

package/authoring/doctypes/function/parse.mjs

@@ -14,7 +14,7 @@
 
 import {parseHook} from '../hook/parse.mjs';
 
-/** @typedef {import('../types').FunctionDoc} FunctionDoc */
+/** @typedef {import('../types.js').FunctionDoc} FunctionDoc */
 
 /**
  * Validate an unknown value as a stamped function doc, or throw.

package/authoring/doctypes/function/type.ts

@@ -14,7 +14,7 @@ import type {
   AuthoredDocGraphFields,
   HookParamDoc,
   UsageDoc,
-} from '../base/type';
+} from '../base/type.js';
 
 /**
  * A documented return. Hooks list named return fields (`name` set); CLI/API

package/authoring/doctypes/hook/hook.doc.mjs

@@ -200,6 +200,10 @@ export const docs = {
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: 'When it loads, a hook doc may leave out `displayName`, and its `usage` is not checked. Write to the type anyway; it is the contract.',
+    },
     {
       type: 'prose',
       text: "A hook's discriminant is `type: 'function'`: HookDoc and FunctionDoc share the generalized function kind. HookDoc is the hook-flavored view: named `returns` fields and a required `usage` block.",

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

@@ -1,7 +1,7 @@
 // @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').HookDoc} HookDoc */
+/** @typedef {import('../types.js').HookDoc} HookDoc */
 /**
  * Validate an unknown value as a stamped function/hook doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {HookDoc}
  */
 export function parseHook(input: unknown, label?: string): HookDoc;
-export type HookDoc = import("../types").HookDoc;
+export type HookDoc = import("../types.js").HookDoc;

package/authoring/doctypes/hook/parse.mjs

@@ -8,7 +8,7 @@
 import {FunctionDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').HookDoc} HookDoc */
+/** @typedef {import('../types.js').HookDoc} HookDoc */
 
 /**
  * Validate an unknown value as a stamped function/hook doc, or throw.

package/authoring/doctypes/hook/type.ts

@@ -12,7 +12,7 @@ import type {
   HookReturnDoc,
   RegistryDocIdentity,
   UsageDoc,
-} from '../base/type';
+} from '../base/type.js';
 
 /**
  * Documentation for a standalone hook's .doc.mjs file.

package/authoring/doctypes/legacy.d.mts

@@ -1,9 +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.
 
-/** @typedef {import('./types').ComponentDoc} ComponentDoc */
-/** @typedef {import('./types').HookDoc} HookDoc */
-/** @typedef {import('./types').ReferenceDoc} ReferenceDoc */
+/** @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.
  *
@@ -12,6 +12,6 @@
  * @returns {ComponentDoc | HookDoc | ReferenceDoc}
  */
 export function parseLegacyDoc(input: unknown, label?: string): ComponentDoc | HookDoc | ReferenceDoc;
-export type ComponentDoc = import("./types").ComponentDoc;
-export type HookDoc = import("./types").HookDoc;
-export type ReferenceDoc = import("./types").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,9 +10,9 @@
 import {LegacyDocSchema} from './_schema.mjs';
 import {formatZodError} from '../_shared/errors.mjs';
 
-/** @typedef {import('./types').ComponentDoc} ComponentDoc */
-/** @typedef {import('./types').HookDoc} HookDoc */
-/** @typedef {import('./types').ReferenceDoc} ReferenceDoc */
+/** @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.

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

@@ -0,0 +1,207 @@
+// 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']
+      .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',
+    ];
+    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(
+      /unsupported type "widget"/,
+    );
+  });
+});
+
+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 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.mjs

@@ -12,7 +12,7 @@ export const doc = {
   displayName: 'NamespaceDoc',
   namespace: 'authoring',
   description:
-    'Declares named navigation slots and renderer-neutral layout blocks for already-discovered docs. It never scans folders or copies child documents.',
+    "Declares named navigation slots and renderer-neutral layout blocks for already-discovered docs. It never scans folders or copies child documents. Not loaded yet: only the docs graph reads namespace docs, and it is not built, so keep them out of an integration's docs directory for now.",
   appliesTo: '<namespace>.doc.mjs',
   fields: [
     {
@@ -44,13 +44,13 @@ export const doc = {
       name: 'placement',
       type: 'DocPlacement',
       description:
-        'Optional canonical parent request: {parent, slot?, order?}. Invalid explicit placement fails compilation instead of falling back.',
+        'Optional canonical parent request: {parent, slot?, order?}. Invalid explicit placement will fail compilation instead of falling back.',
     },
     {
       name: 'aliases',
       type: 'string[]',
       description:
-        'Prior names or routes that must keep resolving to this doc.',
+        'Prior names or routes the docs graph will keep resolving to this doc.',
     },
     {
       name: 'audience',
@@ -111,6 +111,10 @@ export const docs = {
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: "Namespace docs are not loaded yet. Only the docs graph reads them, and it is not built. A namespace doc in an integration's docs directory fails to load as a topic, and with it every topic that package contributes, until the file is removed.",
+    },
     {
       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.',

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

@@ -1,7 +1,7 @@
 // @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').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('../types.js').NamespaceDoc} NamespaceDoc */
 /**
  * Validate an unknown value as a NamespaceDoc, or throw a readable error.
  * @param {unknown} input
@@ -9,4 +9,4 @@
  * @returns {NamespaceDoc}
  */
 export function parseNamespace(input: unknown, label?: string): NamespaceDoc;
-export type NamespaceDoc = import("../types").NamespaceDoc;
+export type NamespaceDoc = import("../types.js").NamespaceDoc;

package/authoring/doctypes/namespace/parse.mjs

@@ -8,7 +8,7 @@
 import {NamespaceDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('../types.js').NamespaceDoc} NamespaceDoc */
 
 /**
  * Validate an unknown value as a NamespaceDoc, or throw a readable error.

package/authoring/doctypes/namespace/type.ts

@@ -6,8 +6,8 @@
  * or copies child documents.
  */
 
-import type {AuthoredDocGraphFields, AuthoredDocKind} from '../base/type';
-import type {ReferenceContentBlock} from '../reference/type';
+import type {AuthoredDocGraphFields, AuthoredDocKind} from '../base/type.js';
+import type {ReferenceContentBlock} from '../reference/type.js';
 
 /** Which providers may contribute appearances to a namespace slot. */
 export type NamespaceProviderScope = 'same' | 'configured';

package/authoring/doctypes/parse.d.mts

@@ -1,15 +1,15 @@
 // @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').FunctionDoc} FunctionDoc */
-/** @typedef {import('./types').ReferenceDoc} ReferenceDoc */
-/** @typedef {import('./types').TemplateDoc} TemplateDoc */
-/** @typedef {import('./types').SchemaDoc} SchemaDoc */
-/** @typedef {import('./types').CommandDoc} CommandDoc */
-/** @typedef {import('./types').EnumDoc} EnumDoc */
-/** @typedef {import('./types').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('./types.js').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types.js').HookDoc} HookDoc */
+/** @typedef {import('./types.js').FunctionDoc} FunctionDoc */
+/** @typedef {import('./types.js').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('./types.js').TemplateDoc} TemplateDoc */
+/** @typedef {import('./types.js').SchemaDoc} SchemaDoc */
+/** @typedef {import('./types.js').CommandDoc} CommandDoc */
+/** @typedef {import('./types.js').EnumDoc} EnumDoc */
+/** @typedef {import('./types.js').NamespaceDoc} NamespaceDoc */
 /**
  * Validate an unknown loaded doc value into its typed shape, or throw.
  * Dispatches on the stamped `type`; unstamped docs fall back to
@@ -21,12 +21,12 @@
  * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc}
  */
 export function parseDoc(input: unknown, label?: string): ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc;
-export type ComponentDoc = import("./types").ComponentDoc;
-export type HookDoc = import("./types").HookDoc;
-export type FunctionDoc = import("./types").FunctionDoc;
-export type ReferenceDoc = import("./types").ReferenceDoc;
-export type TemplateDoc = import("./types").TemplateDoc;
-export type SchemaDoc = import("./types").SchemaDoc;
-export type CommandDoc = import("./types").CommandDoc;
-export type EnumDoc = import("./types").EnumDoc;
-export type NamespaceDoc = import("./types").NamespaceDoc;
+export type ComponentDoc = import("./types.js").ComponentDoc;
+export type HookDoc = import("./types.js").HookDoc;
+export type FunctionDoc = import("./types.js").FunctionDoc;
+export type ReferenceDoc = import("./types.js").ReferenceDoc;
+export type TemplateDoc = import("./types.js").TemplateDoc;
+export type SchemaDoc = import("./types.js").SchemaDoc;
+export type CommandDoc = import("./types.js").CommandDoc;
+export type EnumDoc = import("./types.js").EnumDoc;
+export type NamespaceDoc = import("./types.js").NamespaceDoc;

package/authoring/doctypes/parse.mjs

@@ -18,15 +18,15 @@ import {parseEnum} from './enum/parse.mjs';
 import {parseNamespace} from './namespace/parse.mjs';
 import {parseLegacyDoc} from './legacy.mjs';
 
-/** @typedef {import('./types').ComponentDoc} ComponentDoc */
-/** @typedef {import('./types').HookDoc} HookDoc */
-/** @typedef {import('./types').FunctionDoc} FunctionDoc */
-/** @typedef {import('./types').ReferenceDoc} ReferenceDoc */
-/** @typedef {import('./types').TemplateDoc} TemplateDoc */
-/** @typedef {import('./types').SchemaDoc} SchemaDoc */
-/** @typedef {import('./types').CommandDoc} CommandDoc */
-/** @typedef {import('./types').EnumDoc} EnumDoc */
-/** @typedef {import('./types').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('./types.js').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types.js').HookDoc} HookDoc */
+/** @typedef {import('./types.js').FunctionDoc} FunctionDoc */
+/** @typedef {import('./types.js').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('./types.js').TemplateDoc} TemplateDoc */
+/** @typedef {import('./types.js').SchemaDoc} SchemaDoc */
+/** @typedef {import('./types.js').CommandDoc} CommandDoc */
+/** @typedef {import('./types.js').EnumDoc} EnumDoc */
+/** @typedef {import('./types.js').NamespaceDoc} NamespaceDoc */
 
 /**
  * Validate an unknown loaded doc value into its typed shape, or throw.

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

@@ -1,7 +1,7 @@
 // @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').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('../types.js').ReferenceDoc} ReferenceDoc */
 /**
  * Validate an unknown value as a stamped reference/topic doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {ReferenceDoc}
  */
 export function parseReference(input: unknown, label?: string): ReferenceDoc;
-export type ReferenceDoc = import("../types").ReferenceDoc;
+export type ReferenceDoc = import("../types.js").ReferenceDoc;

package/authoring/doctypes/reference/parse.mjs

@@ -9,7 +9,7 @@
 import {GenericDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('../types.js').ReferenceDoc} ReferenceDoc */
 
 /**
  * Validate an unknown value as a stamped reference/topic doc, or throw.

package/authoring/doctypes/reference/reference.doc.mjs

@@ -95,7 +95,7 @@ export const doc = {
           name: 'sections[].content',
           type: 'ReferenceContentBlock[]',
           description:
-            'Ordered content blocks. Existing prose, heading, code, table, list, and token-ref blocks remain; V1 adds workflow, collection, and reference.',
+            'Ordered content blocks: prose, heading, code, table, list, and token-ref. workflow, collection, and reference are declared for the docs graph and parse, but a topic that uses one fails to load until the docs graph ships.',
           required: true,
         },
         {
@@ -140,7 +140,11 @@ export const docs = {
   notes: [
     {
       type: 'prose',
-      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, a discriminated union. V1 adds only workflow, collection, and reference; choice, callout, and checklist remain invalid. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
+      text: 'A stamped generic doc without `title`, `description` or `sections` still loads, as older codemod output does; its title falls back to `displayName` or `name`. Without a description and sections it is not a usable topic, and `astryx doctor` reports it.',
+    },
+    {
+      type: 'prose',
+      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, a discriminated union. workflow, collection, and reference are declared for the docs graph: they parse, but topic loading rejects them until the docs graph ships. choice, callout, and checklist remain invalid. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
     },
     {
       type: 'code',

package/authoring/doctypes/reference/type.ts

@@ -4,7 +4,7 @@
  * @file Reference/topic doc types.
  */
 
-import type {AuthoredDocGraphFields} from '../base/type';
+import type {AuthoredDocGraphFields} from '../base/type.js';
 
 /** One step in a renderer-neutral workflow. */
 export interface WorkflowStep {

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

@@ -1,7 +1,7 @@
 // @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').SchemaDoc} SchemaDoc */
+/** @typedef {import('../types.js').SchemaDoc} SchemaDoc */
 /**
  * Validate an unknown value as a stamped schema doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {SchemaDoc}
  */
 export function parseSchema(input: unknown, label?: string): SchemaDoc;
-export type SchemaDoc = import("../types").SchemaDoc;
+export type SchemaDoc = import("../types.js").SchemaDoc;

package/authoring/doctypes/schema/parse.mjs

@@ -8,7 +8,7 @@
 import {SchemaDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').SchemaDoc} SchemaDoc */
+/** @typedef {import('../types.js').SchemaDoc} SchemaDoc */
 
 /**
  * Validate an unknown value as a stamped schema doc, or throw.

package/authoring/doctypes/schema/type.ts

@@ -6,8 +6,8 @@
  * response envelope). Colocated as a `.doc.mjs` next to the schema it describes.
  */
 
-import type {AuthoredDocGraphFields} from '../base/type';
-import type {ReferenceContentBlock} from '../reference/type';
+import type {AuthoredDocGraphFields} from '../base/type.js';
+import type {ReferenceContentBlock} from '../reference/type.js';
 
 /**
  * One documented field of a schema. Object fields nest via `fields`, so a whole