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

package/api/docs/detail/section/section.mjs

@@ -4,14 +4,15 @@
  * @file docs.detail.section leaf — load a single section of a topic.
  *
  * @input A topic name, a section query, and optional {lang, zh, dense}. Resolves
- *   and loads the topic via the shared adapter, then finds the section by its
- *   stable key, then by exact title, then by a title that contains the query.
+ *   the topic via the shared adapter, finds the section in its lowered compiled
+ *   node by its stable key, then by exact title, then by a title that contains
+ *   the query, and links only that section.
  * @output { type: 'docs.detail.section', data: ReferenceSection } with any
  *   token-ref blocks inlined — matching `astryx --json docs <topic> <section>`.
  *   Throws ERR_UNKNOWN_SECTION when nothing matches, or when the query matches
  *   more than one section (the candidates come back as suggestions).
- * @position Leaf nested under api/docs/detail. Shares discovery/loading/
- *   topic-resolution with the detail leaf via _adapter.mjs.
+ * @position Leaf nested under api/docs/detail. Shares topic resolution with the
+ *   detail leaf via _adapter.mjs and reads through the compiler's lenses.
  */
 
 import {AstryxError} from '../../../error.mjs';
@@ -20,8 +21,12 @@ import {
   findDocSection,
   sectionKey,
 } from '../../../../foundation/discovery/docs-section-key.mjs';
-import {resolveTopicDocs} from '../../_adapter.mjs';
-import {resolveTokenRefs} from '../detail.mjs';
+import {linkReferenceSection} from '../../../../foundation/doc-compiler/compile.mjs';
+import {
+  readerSections,
+  sectionView,
+} from '../../../../foundation/doc-compiler/lenses.mjs';
+import {referenceTargets, resolveTopicDocs} from '../../_adapter.mjs';
 
 /**
  * @param {string} topic
@@ -44,31 +49,30 @@ export async function section(topic, sectionName, options = {}) {
       ERROR_CODES.ERR_UNKNOWN_SECTION,
     );
   }
-  const {catalog, docsData, lang} = await resolveTopicDocs(topic, options);
 
-  const {section: match, candidates} = findDocSection(
-    docsData.sections,
-    sectionName,
-  );
+  const {catalog, node, lang} = await resolveTopicDocs(topic, options);
+  const sections = readerSections(node);
+  const {section: match, candidates} = findDocSection(sections, sectionName);
   if (!match) {
     const ambiguous = candidates.length > 1;
     throw new AstryxError(
       ambiguous
         ? `Section "${sectionName}" matches ${candidates.length} sections in "${topic}". Read one by its key.`
         : `Section "${sectionName}" not found in "${topic}"`,
-      (ambiguous ? candidates : docsData.sections).map(s => ({
+      (ambiguous ? candidates : sections).map(s => ({
         name: sectionKey(s),
         reason: s.title,
       })),
       ERROR_CODES.ERR_UNKNOWN_SECTION,
     );
   }
+
   // A section read on its own inlines its token refs, as the whole topic does;
-  // otherwise a section that is only a token-ref prints blank.
-  const {sections} = await resolveTokenRefs(
-    {...docsData, sections: [match]},
-    catalog,
-    {lang},
+  // otherwise a section that is only a token-ref prints blank. Only this
+  // section is linked, so a broken reference elsewhere cannot fail the read.
+  const linked = await linkReferenceSection(
+    match,
+    referenceTargets(catalog, lang),
   );
-  return {type: 'docs.detail.section', data: sections[0]};
+  return {type: 'docs.detail.section', data: sectionView(node, linked)};
 }

package/api/docs/detail/section/section.test.mjs

@@ -10,7 +10,7 @@
 import {describe, it, expect} from 'vitest';
 import {section} from './section.mjs';
 import {AstryxError} from '../../../error.mjs';
-import {loadDocsCatalog, loadTopicDoc} from '../../_adapter.mjs';
+import {loadDocsCatalog, lowerTopic} from '../../_adapter.mjs';
 
 const SLOW = 30_000;
 
@@ -42,7 +42,8 @@ describe('docs.detail.section leaf', () => {
   }, SLOW);
 
   it('reads a section by its stable key', async () => {
-    const doc = await loadTopicDoc((await loadDocsCatalog()).resolve('theme'));
+    const catalog = await loadDocsCatalog();
+    const {doc} = await lowerTopic(catalog, catalog.resolve('theme'));
     const target = doc.sections[doc.sections.length - 1];
     const res = await section('theme', target.id);
     expect(res.data.title).toBe(target.title);
@@ -63,7 +64,7 @@ describe('docs.detail.section leaf', () => {
       const catalog = await loadDocsCatalog();
       let checked = 0;
       for (const entry of catalog.entries()) {
-        const doc = await loadTopicDoc(entry);
+        const {doc} = await lowerTopic(catalog, entry);
         for (const own of doc.sections) {
           if (!own.content.some(block => block.type === 'token-ref')) continue;
           const res = await section(entry.name, own.id, lang ? {lang} : {});

package/api/docs/index/index.mjs

@@ -3,8 +3,9 @@
 /**
  * @file docs.index leaf — the section index of one topic.
  *
- * @input A topic name plus optional {lang, zh, dense, cwd}. Resolves and loads
- *   the topic via the shared adapter.
+ * @input A topic name plus optional {lang, zh, dense, cwd}. Resolves the topic
+ *   via the shared adapter and reads its lowered compiled node; nothing is
+ *   linked, since the index never inlines a token reference.
  * @output { type: 'docs.index', data: DocsIndex } — the topic's name, title and
  *   description and, for each section, the key it is read by, its title, and a
  *   one-line summary. Matches `astryx --json docs <topic> --index`.
@@ -13,7 +14,7 @@
  *   read, is the detail leaf.
  */
 
-import {buildDocsIndexData} from '../../../foundation/discovery/docs-section-key.mjs';
+import {indexView} from '../../../foundation/doc-compiler/lenses.mjs';
 import {resolveTopicDocs} from '../_adapter.mjs';
 
 /**
@@ -26,6 +27,6 @@ import {resolveTopicDocs} from '../_adapter.mjs';
  * @returns {Promise<import('../docs.type.mjs').DocsIndexResponse>}
  */
 export async function index(topic, options = {}) {
-  const {docsData} = await resolveTopicDocs(topic, options);
-  return {type: 'docs.index', data: buildDocsIndexData(docsData)};
+  const {node} = await resolveTopicDocs(topic, options);
+  return {type: 'docs.index', data: indexView(node)};
 }

package/api/doctor/doctor.mjs

@@ -34,8 +34,8 @@ import {
   docsIndexBytes,
   oversizedDocSections,
 } from '../../foundation/discovery/docs-output-budget.mjs';
-import {loadTopicDoc, overlayLanguages} from '../docs/_adapter.mjs';
-import {resolveTokenRefs} from '../docs/detail/detail.mjs';
+import {compileTopic, overlayLanguages} from '../docs/_adapter.mjs';
+import {detailView} from '../../foundation/doc-compiler/lenses.mjs';
 import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env/semver.mjs';
 
 /**
@@ -798,11 +798,7 @@ export async function checkDocsProgressiveDisclosure(ctx) {
       for (const lang of [null, ...overlayLanguages(entry)]) {
         const where = lang ? `${entry.name} [${lang}]` : entry.name;
         try {
-          const doc = await resolveTokenRefs(
-            await loadTopicDoc(entry, {lang}),
-            catalog,
-            {lang},
-          );
+          const doc = detailView(await compileTopic(catalog, entry, lang));
           if (lang == null) topics += 1;
           const indexBytes = docsIndexBytes(buildDocsIndexData(doc));
           if (indexBytes > DOC_OUTPUT_BUDGET_BYTES) {

package/api/search/search.mjs

@@ -66,7 +66,7 @@ import {
 import {loadIntegrationsSafely} from '../component/_adapter.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {discoverTemplates, extractComponents} from '../template/template.mjs';
-import {loadDocsCatalog, loadTopicDoc} from '../docs/_adapter.mjs';
+import {loadDocsCatalog, lowerTopic} from '../docs/_adapter.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {setResultCoverage} from './coverage.mjs';
@@ -732,16 +732,16 @@ async function gatherHooks(coreDir) {
 async function gatherDocs(cwd) {
   /** @type {Candidate[]} */
   const candidates = [];
-  let entries;
+  let catalog;
   try {
-    entries = (await loadDocsCatalog(cwd)).entries();
+    catalog = await loadDocsCatalog(cwd);
   } catch {
     return candidates;
   }
-  for (const entry of entries) {
+  for (const entry of catalog.entries()) {
     let doc = null;
     try {
-      doc = await loadTopicDoc(entry);
+      doc = (await lowerTopic(catalog, entry)).doc;
     } catch {
       // A topic that cannot be loaded is reported by the commands that own
       // integration issues; search just cannot index it.

package/assets/codemods/transforms/v0.3.0/__tests__/unwrap-authoring-factories.test.mjs

@@ -3,7 +3,8 @@
 import {describe, it, expect} from 'vitest';
 
 async function applyTransform(source, path = 'test.ts') {
-  const {default: transform} = await import('../unwrap-authoring-factories.mjs');
+  const {default: transform} =
+    await import('../unwrap-authoring-factories.mjs');
   const jscodeshift = (await import('jscodeshift')).default;
   const j = jscodeshift.withParser('tsx');
   const api = {jscodeshift: j, stats: () => {}, report: () => {}};
@@ -18,7 +19,7 @@ export default createConfig({integrations: ['@acme/widgets']});
 `;
     const output = await applyTransform(input);
     expect(output).not.toContain('createConfig');
-    expect(output).toContain("export default {");
+    expect(output).toContain('export default {');
     expect(output).toContain("integrations: ['@acme/widgets']");
     expect(output).not.toContain('type:');
   });
@@ -132,13 +133,34 @@ export default createComponentDoc();
     expect(output).toContain("type: 'component'");
   });
 
+  it('leaves same-named factories from unrelated packages unchanged', async () => {
+    const input = `import {createConfig} from '@acme/eslint';
+export default createConfig({strict: true});
+`;
+    expect(await applyTransform(input)).toBe(input);
+  });
+
+  it('keeps an unrelated same-named import when another factory is migrated', async () => {
+    const input = `import {createConfig as createLintConfig} from '@acme/eslint';
+import {createDoc} from '@astryxdesign/cli/doc';
+export const lintConfig = createLintConfig({strict: true});
+export const doc = createDoc({name: 'Theming', description: 'How theming works.'});
+`;
+    const output = await applyTransform(input);
+    expect(output).toContain(
+      "import {createConfig as createLintConfig} from '@acme/eslint'",
+    );
+    expect(output).toContain('createLintConfig({strict: true})');
+    expect(output).not.toContain('createDoc');
+    expect(output).toContain("type: 'generic'");
+  });
+
   it('is a no-op when no authoring factory is imported', async () => {
     const input = `import {Button} from '@astryxdesign/core';
 export default Button;
 `;
-    const {default: transform} = await import(
-      '../unwrap-authoring-factories.mjs'
-    );
+    const {default: transform} =
+      await import('../unwrap-authoring-factories.mjs');
     const jscodeshift = (await import('jscodeshift')).default;
     const j = jscodeshift.withParser('tsx');
     const api = {jscodeshift: j, stats: () => {}, report: () => {}};

package/assets/codemods/transforms/v0.3.0/unwrap-authoring-factories.mjs

@@ -5,8 +5,9 @@
  *
  * v0.3.0 removes the authoring factories. Authoring is now types + parsers: an
  * author writes a plain object and stamps its `type` directly. This transform
- * rewrites every factory call to the plain object the factory used to return,
- * then drops the now-dead factory imports:
+ * rewrites factory calls imported from the retired Astryx authoring entrypoints
+ * to the plain object the factory used to return, then drops the now-dead
+ * factory imports:
  *
  *   createConfig(o) / createIntegration(o)        -> o        (no discriminant)
  *   createComponentDoc(o)                         -> { ...o, type: 'component' }
@@ -25,8 +26,9 @@
  *
  * Import aliases are followed (`import {createDoc as mk}` → calls to `mk`), and
  * the factory specifiers are removed afterward (the whole import statement goes
- * if nothing else was imported from it). Run this BEFORE
- * `migrate-authoring-imports`, which repoints the surviving type imports.
+ * if nothing else was imported from it). Same-named imports from other packages
+ * remain untouched. Run this BEFORE `migrate-authoring-imports`, which repoints
+ * the surviving type imports.
  */
 
 export const meta = {
@@ -35,13 +37,24 @@ export const meta = {
     'Rewrites createConfig/createIntegration/createComponentDoc/' +
     'createFunctionDoc/createDoc/createPageTemplate/createBlockTemplate/' +
     'createCodemod/createConfigCodemod calls to the plain object they returned ' +
-    "(stamping the doc/template/codemod `type` discriminant), and removes the " +
+    '(stamping the doc/template/codemod `type` discriminant), and removes the ' +
     'now-dead factory imports. Authoring is types + parsers in v0.3.0 — there ' +
     'are no factories.',
   pr: '#4612',
   fileExtensions: ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'],
 };
 
+/** Legacy Astryx authoring entrypoints that exported the removed factories. */
+const AUTHORING_SOURCES = new Set([
+  '@astryxdesign/cli/config',
+  '@astryxdesign/cli/doc',
+  '@astryxdesign/cli/integration',
+  '@astryxdesign/cli/template',
+  '@astryxdesign/cli/codemod',
+  '@astryxdesign/core/authoring',
+  '@astryxdesign/core/config',
+]);
+
 /**
  * Factory name → the `type` discriminant it stamped, or `null` for the config /
  * integration factories, which were pure typed-identity (no discriminant).
@@ -108,6 +121,7 @@ export default function transformer(file, api) {
   /** @type {Map<string, string>} */
   const localToFactory = new Map();
   root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    if (!AUTHORING_SOURCES.has(path.node.source.value)) return;
     for (const spec of path.node.specifiers ?? []) {
       if (spec.type !== 'ImportSpecifier') continue;
       const importedName = spec.imported?.name;
@@ -163,6 +177,7 @@ export default function transformer(file, api) {
   // Drop the now-dead factory import specifiers; remove any import statement
   // left empty.
   root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    if (!AUTHORING_SOURCES.has(path.node.source.value)) return;
     const specs = path.node.specifiers ?? [];
     const kept = specs.filter(
       (/** @type {any} */ spec) =>

package/authoring/_shared/contract.ts

@@ -28,5 +28,27 @@ export type MutuallyAssignable<A, B> = [A] extends [B]
     : false
   : false;
 
+/**
+ * `T` without string or number index signatures, at every depth. A
+ * `.passthrough()` schema infers one and a hand-written interface never has
+ * one, so a lock drops them before comparing named fields. Recursive fields
+ * that a schema casts to their public type compare equal by construction.
+ */
+export type NamedFields<T> = T extends readonly (infer U)[]
+  ? NamedFields<U>[]
+  : T extends (...args: never[]) => unknown
+    ? T
+    : T extends object
+      ? {
+          [
+            K in keyof T as string extends K
+              ? never
+              : number extends K
+                ? never
+                : K
+          ]: NamedFields<T[K]>;
+        }
+      : T;
+
 /** Compiles only when `T` is exactly `true`; otherwise a type error. */
 export type Expect<T extends true> = T;

package/authoring/codemod/codemod.doc.mjs

@@ -63,11 +63,13 @@ export const doc = {
               name: 'file.path',
               type: 'string',
               description: 'Absolute path to the file being transformed.',
+              required: true,
             },
             {
               name: 'file.source',
               type: 'string',
               description: 'The current source contents of the file.',
+              required: true,
             },
           ],
         },
@@ -81,18 +83,21 @@ export const doc = {
               type: 'unknown',
               description:
                 'A jscodeshift instance configured with a parser for the file.',
+              required: true,
             },
             {
               name: 'api.stats',
               type: '(...args: unknown[]) => void',
               description:
                 'Report a statistic (no-op-friendly; provided for jscodeshift parity).',
+              required: true,
             },
             {
               name: 'api.report',
               type: '(...args: unknown[]) => void',
               description:
                 'Report progress (no-op-friendly; provided for jscodeshift parity).',
+              required: true,
             },
           ],
         },
@@ -100,7 +105,7 @@ export const doc = {
     },
     {
       name: 'type',
-      type: "'code'",
+      type: "'code' | 'config'",
       description:
         "Discriminant for the file-transforming variant. Use 'config' for a " +
         'codemod that rewrites astryx.config.* instead (see notes).',

package/authoring/codemod/parse.d.mts

@@ -5,8 +5,8 @@
  * Compile-time drift-lock: sealed envelope must infer exactly the public
  * stamped-codemod union.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').Equal<
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<
  *     z.infer<typeof codemodEnvelopeSchema>,
  *     AstryxCodemod | AstryxConfigCodemod
  *   >
@@ -24,10 +24,10 @@ export function parseCodemod(input: unknown, label?: string): AstryxCodemod | As
  * Compile-time drift-lock: sealed envelope must infer exactly the public
  * stamped-codemod union.
  */
-export type _CodemodDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").Equal<z.infer<typeof codemodEnvelopeSchema>, AstryxCodemod | AstryxConfigCodemod>>;
-export type AstryxCodemod = import("./type").AstryxCodemod;
-export type AstryxConfigCodemod = import("./type").AstryxConfigCodemod;
-export type AstryxCodemodTransform = import("./type").AstryxCodemodTransform;
+export type _CodemodDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof codemodEnvelopeSchema>, AstryxCodemod | AstryxConfigCodemod>>;
+export type AstryxCodemod = import("./type.js").AstryxCodemod;
+export type AstryxConfigCodemod = import("./type.js").AstryxConfigCodemod;
+export type AstryxCodemodTransform = import("./type.js").AstryxCodemodTransform;
 import { z } from 'zod';
 /**
  * The load-boundary contract: a stamped codemod default export, discriminated
@@ -38,13 +38,13 @@ declare const codemodEnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     isOptional: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     fileExtensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    transform: z.ZodType<import("./type").AstryxCodemodTransform, any, z.core.$ZodTypeInternals<import("./type").AstryxCodemodTransform, any>>;
+    transform: z.ZodType<import("./type.js").AstryxCodemodTransform, any, z.core.$ZodTypeInternals<import("./type.js").AstryxCodemodTransform, any>>;
     type: z.ZodLiteral<"code">;
 }, z.core.$strict>, z.ZodObject<{
     title: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     isOptional: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    transform: z.ZodType<import("./type").AstryxCodemodTransform, any, z.core.$ZodTypeInternals<import("./type").AstryxCodemodTransform, any>>;
+    transform: z.ZodType<import("./type.js").AstryxCodemodTransform, any, z.core.$ZodTypeInternals<import("./type.js").AstryxCodemodTransform, any>>;
     type: z.ZodLiteral<"config">;
 }, z.core.$strict>], "type">;
 export {};

package/authoring/codemod/parse.mjs

@@ -10,12 +10,14 @@
 import {z} from 'zod';
 import {formatZodError} from '../_shared/errors.mjs';
 
-/** @typedef {import('./type').AstryxCodemod} AstryxCodemod */
-/** @typedef {import('./type').AstryxConfigCodemod} AstryxConfigCodemod */
-/** @typedef {import('./type').AstryxCodemodTransform} AstryxCodemodTransform */
+/** @typedef {import('./type.js').AstryxCodemod} AstryxCodemod */
+/** @typedef {import('./type.js').AstryxConfigCodemod} AstryxConfigCodemod */
+/** @typedef {import('./type.js').AstryxCodemodTransform} AstryxCodemodTransform */
 
 const transform = /** @type {z.ZodType<AstryxCodemodTransform>} */ (
-  z.custom(value => typeof value === 'function', {message: 'Expected a function'})
+  z.custom(value => typeof value === 'function', {
+    message: 'Expected a function',
+  })
 );
 
 const codeCodemodSchema = z
@@ -52,8 +54,8 @@ const codemodEnvelopeSchema = z.discriminatedUnion('type', [
  * Compile-time drift-lock: sealed envelope must infer exactly the public
  * stamped-codemod union.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').Equal<
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<
  *     z.infer<typeof codemodEnvelopeSchema>,
  *     AstryxCodemod | AstryxConfigCodemod
  *   >

package/authoring/config/parse.d.mts

@@ -6,8 +6,8 @@
  * {@link AstryxConfig} type. If they drift, `Equal` becomes `false` and
  * `Expect<false>` fails the `tsconfig.authoring-contract.json` typecheck.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof configSchema>, AstryxConfig>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof configSchema>, AstryxConfig>
  * >} _ConfigDriftLock
  */
 /**
@@ -23,13 +23,13 @@ export function parseConfig(input: unknown, label?: string): AstryxConfig;
  * {@link AstryxConfig} type. If they drift, `Equal` becomes `false` and
  * `Expect<false>` fails the `tsconfig.authoring-contract.json` typecheck.
  */
-export type _ConfigDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").MutuallyAssignable<z.infer<typeof configSchema>, AstryxConfig>>;
-export type AstryxConfig = import("./type").AstryxConfig;
-export type PostCodemodHook = import("./type").PostCodemodHook;
-export type XleComponent = import("./type").XleComponent;
-export type DebugConfig = import("./type").DebugConfig;
-export type DebugEventHandler = import("../debug/type").DebugEventHandler;
-export type GapReportHandler = import("../gap-report/type").GapReportHandler;
+export type _ConfigDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<z.infer<typeof configSchema>, AstryxConfig>>;
+export type AstryxConfig = import("./type.js").AstryxConfig;
+export type PostCodemodHook = import("./type.js").PostCodemodHook;
+export type XleComponent = import("./type.js").XleComponent;
+export type DebugConfig = import("./type.js").DebugConfig;
+export type DebugEventHandler = import("../debug/type.js").DebugEventHandler;
+export type GapReportHandler = import("../gap-report/type.js").GapReportHandler;
 import { z } from 'zod';
 declare const configSchema: z.ZodObject<{
     integrations: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -40,14 +40,14 @@ declare const configSchema: z.ZodObject<{
             buildCommand: z.ZodType<(ctx: {
                 packageDir: string;
                 files: string[];
-            }) => import("./type").PostCodemodCommand | null | undefined | Promise<import("./type").PostCodemodCommand | null | undefined>, any, z.core.$ZodTypeInternals<(ctx: {
+            }) => import("./type.js").PostCodemodCommand | null | undefined | Promise<import("./type.js").PostCodemodCommand | null | undefined>, any, z.core.$ZodTypeInternals<(ctx: {
                 packageDir: string;
                 files: string[];
-            }) => import("./type").PostCodemodCommand | null | undefined | Promise<import("./type").PostCodemodCommand | null | undefined>, any>>;
+            }) => import("./type.js").PostCodemodCommand | null | undefined | Promise<import("./type.js").PostCodemodCommand | null | undefined>, any>>;
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
-    debug: z.ZodOptional<z.ZodType<import("../debug/type").DebugEventHandler, any, z.core.$ZodTypeInternals<import("../debug/type").DebugEventHandler, any>>>;
-    gapReport: z.ZodOptional<z.ZodType<import("../gap-report/type").GapReportHandler, any, z.core.$ZodTypeInternals<import("../gap-report/type").GapReportHandler, any>>>;
+    debug: z.ZodOptional<z.ZodType<import("../debug/type.js").DebugEventHandler, any, z.core.$ZodTypeInternals<import("../debug/type.js").DebugEventHandler, any>>>;
+    gapReport: z.ZodOptional<z.ZodType<import("../gap-report/type.js").GapReportHandler, any, z.core.$ZodTypeInternals<import("../gap-report/type.js").GapReportHandler, any>>>;
     experimental: z.ZodOptional<z.ZodObject<{
         xle: z.ZodOptional<z.ZodObject<{
             components: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{

package/authoring/config/parse.mjs

@@ -13,12 +13,12 @@ import {z} from 'zod';
 import {formatZodError} from '../_shared/errors.mjs';
 import {parseGapReportHandler} from '../gap-report/parse.mjs';
 
-/** @typedef {import('./type').AstryxConfig} AstryxConfig */
-/** @typedef {import('./type').PostCodemodHook} PostCodemodHook */
-/** @typedef {import('./type').XleComponent} XleComponent */
-/** @typedef {import('./type').DebugConfig} DebugConfig */
-/** @typedef {import('../debug/type').DebugEventHandler} DebugEventHandler */
-/** @typedef {import('../gap-report/type').GapReportHandler} GapReportHandler */
+/** @typedef {import('./type.js').AstryxConfig} AstryxConfig */
+/** @typedef {import('./type.js').PostCodemodHook} PostCodemodHook */
+/** @typedef {import('./type.js').XleComponent} XleComponent */
+/** @typedef {import('./type.js').DebugConfig} DebugConfig */
+/** @typedef {import('../debug/type.js').DebugEventHandler} DebugEventHandler */
+/** @typedef {import('../gap-report/type.js').GapReportHandler} GapReportHandler */
 
 // Typed `z.custom` so `z.infer` reproduces the real function type (not `unknown`).
 const buildCommand = /** @type {z.ZodType<PostCodemodHook['buildCommand']>} */ (
@@ -95,8 +95,8 @@ const configSchema = z
  * {@link AstryxConfig} type. If they drift, `Equal` becomes `false` and
  * `Expect<false>` fails the `tsconfig.authoring-contract.json` typecheck.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof configSchema>, AstryxConfig>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof configSchema>, AstryxConfig>
  * >} _ConfigDriftLock
  */
 

package/authoring/config/type.ts

@@ -9,8 +9,8 @@
  * boundary; there is no factory to call.
  */
 
-import type {DebugEventHandler} from '../debug/type';
-import type {GapReportHandler} from '../gap-report/type';
+import type {DebugEventHandler} from '../debug/type.js';
+import type {GapReportHandler} from '../gap-report/type.js';
 
 /**
  * A command to run as part of a post-codemod hook. Returned by a hook's
@@ -21,7 +21,7 @@ export interface PostCodemodCommand {
   args?: string[];
   options?: {
     cwd?: string;
-    env?: NodeJS.ProcessEnv;
+    env?: Record<string, string | undefined>;
     timeout?: number;
   };
 }

package/authoring/debug/parse.d.mts

@@ -7,8 +7,8 @@
  * `Expect<false>` fails the `tsconfig.authoring-contract.json` typecheck —
  * so a field added to the recorder without being published here breaks CI.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof eventSchema>, DebugEvent>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof eventSchema>, DebugEvent>
  * >} _DebugEventDriftLock
  */
 /**
@@ -29,8 +29,8 @@ export function parseDebugEvent(input: unknown, label?: string): DebugEvent;
  * `Expect<false>` fails the `tsconfig.authoring-contract.json` typecheck —
  * so a field added to the recorder without being published here breaks CI.
  */
-export type _DebugEventDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").MutuallyAssignable<z.infer<typeof eventSchema>, DebugEvent>>;
-export type DebugEvent = import("./type").DebugEvent;
+export type _DebugEventDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<z.infer<typeof eventSchema>, DebugEvent>>;
+export type DebugEvent = import("./type.js").DebugEvent;
 import { z } from 'zod';
 declare const eventSchema: z.ZodObject<{
     schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;

package/authoring/debug/parse.mjs

@@ -22,7 +22,7 @@
 import {z} from 'zod';
 import {formatZodError} from '../_shared/errors.mjs';
 
-/** @typedef {import('./type').DebugEvent} DebugEvent */
+/** @typedef {import('./type.js').DebugEvent} DebugEvent */
 
 const outcomeSchema = z.enum([
   'ok',
@@ -169,8 +169,8 @@ const eventSchema = z
  * `Expect<false>` fails the `tsconfig.authoring-contract.json` typecheck —
  * so a field added to the recorder without being published here breaks CI.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof eventSchema>, DebugEvent>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof eventSchema>, DebugEvent>
  * >} _DebugEventDriftLock
  */