@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db7b338

package/foundation/config/project.mjs

@@ -15,7 +15,9 @@
  *     async). It does what loadConfig did — find the config sibling-of
  *     package.json, import + validate it, load the configured integrations —
  *     plus autolink the installed ones no config names, and self-resolve the
- *     package being authored when it carries a manifest. Discovery is LAZY.
+ *     package being authored when it carries a manifest. Provider identity is
+ *     resolved once over all three (see integrations/provider-resolution), and
+ *     the ledger is kept for {@link providerLedgerOf}. Discovery is LAZY.
  *   - Discovery methods (components/templates/codemods/docs/themes) are MEMOIZED per
  *     instance (via the pluggable cache) and orchestrate the EXISTING discovery
  *     functions — Project never reimplements discovery.
@@ -38,10 +40,10 @@ import {parseConfig} from '../../authoring/config/parse.mjs';
 import {
   loadIntegrations,
   loadLocalIntegration,
-  markProviderConflicts,
   resolvePackageDir,
 } from '../integrations/integrations.mjs';
-import {autolinkIntegrations} from '../integrations/autolink.mjs';
+import {loadAutolinkCandidates} from '../integrations/autolink.mjs';
+import {resolveProviders} from '../integrations/provider-resolution.mjs';
 import {
   setProject as setDebugProject,
   setEventHandler as setDebugEventHandler,
@@ -297,6 +299,24 @@ export function findConfigPath(startDir = process.cwd()) {
   return present.length === 1 ? present[0] : null;
 }
 
+/**
+ * The provider ledger each loaded Project resolved, kept off the class so it
+ * is not part of the Project API.
+ * @type {WeakMap<Project, import('../integrations/provider-resolution.mjs').ProviderLedger>}
+ */
+const PROVIDER_LEDGERS = new WeakMap();
+
+/**
+ * The provider ledger a Project resolved at load: one outcome for every
+ * package directory configured, autolinked, or authored. Internal: upgrade
+ * resolves on top of it, and tests account for every candidate with it.
+ * @param {Project} project
+ * @returns {import('../integrations/provider-resolution.mjs').ProviderLedger}
+ */
+export function providerLedgerOf(project) {
+  return PROVIDER_LEDGERS.get(project) ?? new Map();
+}
+
 /**
  * The single API for reading resolved project configuration. Construct via the
  * async {@link Project.load} factory.
@@ -402,17 +422,14 @@ export class Project {
     // This runs whether or not a config exists, because the projects it reaches
     // are overwhelmingly the ones with no astryx.config at all: a scaffold adds
     // the dependency and writes no config, and the integration then contributes
-    // nothing for want of a line nobody knew to write. Appended AFTER the
+    // nothing for want of a line nobody knew to write. Resolved AFTER the
     // configured ones so an explicit entry keeps its position and its
     // precedence in every discovery order.
-    loadedIntegrations = [
-      ...loadedIntegrations,
-      ...(await autolinkIntegrations({
-        projectDir,
-        loaded: loadedIntegrations,
-        fresh,
-      })),
-    ];
+    const autolinked = await loadAutolinkCandidates({
+      projectDir,
+      loaded: loadedIntegrations,
+      fresh,
+    });
 
     // The package being authored is the one package that cannot install itself.
     // When it carries a manifest, resolve its working bytes directly so every
@@ -420,17 +437,27 @@ export class Project {
     // replaces the same installed package in place, preserving configured
     // precedence while making the source being edited authoritative.
     const localIntegration = await loadLocalIntegrationSafely(projectDir, fresh);
-    if (localIntegration) {
-      const existing = loadedIntegrations.findIndex(
-        integration => integration.name === localIntegration.name,
-      );
-      if (existing === -1) loadedIntegrations.push(localIntegration);
-      else loadedIntegrations[existing] = localIntegration;
-    }
 
     // Autolinked and local packages can claim a provider ID that a configured
     // package already holds, so identity is resolved once over the final set.
-    loadedIntegrations = markProviderConflicts(loadedIntegrations);
+    const resolution = resolveProviders([
+      ...loadedIntegrations.map(integration => ({
+        source: /** @type {const} */ ('configured'),
+        integration,
+        spec: integration.__spec,
+      })),
+      ...autolinked,
+      ...(localIntegration
+        ? [
+            {
+              source: /** @type {const} */ ('local'),
+              integration: localIntegration,
+              spec: localIntegration.__spec,
+            },
+          ]
+        : []),
+    ]);
+    loadedIntegrations = resolution.integrations;
 
     // The debug recorder resolves its settings synchronously, long before any
     // command gets here, so this is where a project's `debug` block gets a
@@ -461,7 +488,7 @@ export class Project {
       // Never let recording break config loading.
     }
 
-    return new Project({
+    const project = new Project({
       cwd,
       configPath,
       config,
@@ -470,6 +497,8 @@ export class Project {
       cache: resolvedCache,
       hash,
     });
+    PROVIDER_LEDGERS.set(project, resolution.ledger);
+    return project;
   }
 
   /**

package/foundation/config/project.test.mjs

@@ -163,7 +163,7 @@ function scaffoldLocalPackage({name = '@acme/local'} = {}) {
 
   fs.mkdirSync(path.join(tmpDir, 'templates'));
   fs.writeFileSync(
-    path.join(tmpDir, 'templates', 'local-page.template.mjs'),
+    path.join(tmpDir, 'templates', 'local-page.doc.mjs'),
     `export default {type: 'page', name: 'Local page', description: 'Local page.'};\n`,
   );
   fs.writeFileSync(
@@ -181,21 +181,8 @@ function scaffoldLocalPackage({name = '@acme/local'} = {}) {
 
   fs.mkdirSync(path.join(tmpDir, 'themes', 'ocean'), {recursive: true});
   fs.writeFileSync(
-    path.join(tmpDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug: 'ocean',
-          displayName: 'Ocean',
-          description: 'Ocean theme.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts'],
-        },
-      ],
-    }),
+    path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.doc.mjs'),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {type: 'theme', name: 'ocean', displayName: 'Ocean', description: 'Ocean theme.', maintained: true};\n`,
   );
   fs.writeFileSync(
     path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.ts'),

package/foundation/discovery/authoring-self-docs.d.mts

@@ -24,6 +24,12 @@ export function loadAuthoringSelfDocs(sources?: string[], root?: string): Promis
         error: string;
     }[];
 }>;
+/**
+ * One self-doc as a topic section, keyed by the doc's own name.
+ * @param {any} doc
+ * @returns {import('../../authoring/doctypes/reference/type').ReferenceSection}
+ */
+export function selfDocSection(doc: any): import("../../authoring/doctypes/reference/type").ReferenceSection;
 /**
  * The `authoring` topic: one section per self-doc, in the order given.
  * @param {any[]} docs

package/foundation/discovery/authoring-self-docs.mjs

@@ -17,8 +17,8 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {pathToFileURL} from 'node:url';
 import {CLI_ROOT} from '../fs/paths.mjs';
+import {readDocView} from '../doc-compiler/read.mjs';
 import {
   DOC_OUTPUT_BUDGET_BYTES,
   oversizedDocSections,
@@ -31,6 +31,8 @@ export const AUTHORING_ROOT = path.join(CLI_ROOT, 'authoring');
 export const AUTHORING_SELF_DOCS = [
   'integration/integration.doc.mjs',
   'config/config.doc.mjs',
+  'debug/debug.doc.mjs',
+  'gap-report/gap-report.doc.mjs',
   'codemod/codemod.doc.mjs',
   'identity/identity.doc.mjs',
   'doctypes/base/graph-fields.doc.mjs',
@@ -43,6 +45,7 @@ export const AUTHORING_SELF_DOCS = [
   'doctypes/reference/reference.doc.mjs',
   'doctypes/schema/schema.doc.mjs',
   'doctypes/template/template.doc.mjs',
+  'doctypes/theme/theme.doc.mjs',
 ];
 
 /** Blocks a self-doc note may carry that a topic section can render. */
@@ -59,7 +62,8 @@ export function discoverAuthoringSelfDocSources(root = AUTHORING_ROOT) {
   /** @param {string} dir */
   const walk = dir => {
     for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
-      if (entry.name === 'node_modules' || entry.name.startsWith('__')) continue;
+      if (entry.name === 'node_modules' || entry.name.startsWith('__'))
+        continue;
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) walk(full);
       else if (entry.name.endsWith('.doc.mjs')) {
@@ -86,9 +90,14 @@ export async function loadAuthoringSelfDocs(
   const failed = [];
   for (const source of sources) {
     try {
-      const mod = await import(pathToFileURL(path.join(root, source)).href);
-      const doc = mod.doc ?? mod.docs ?? mod.default;
-      if (typeof doc?.name !== 'string' || typeof doc?.description !== 'string') {
+      const doc = await readDocView(path.join(root, source), {
+        root: 'self-docs',
+        loader: 'native',
+      });
+      if (
+        typeof doc?.name !== 'string' ||
+        typeof doc?.description !== 'string'
+      ) {
         throw new Error('exports no doc with a name and a description');
       }
       loaded.push({source, doc});
@@ -129,7 +138,7 @@ function fieldRows(fields) {
  * @param {any} doc
  * @returns {import('../../authoring/doctypes/reference/type').ReferenceSection}
  */
-function selfDocSection(doc) {
+export function selfDocSection(doc) {
   /** @type {any[]} */
   const content = [{type: 'prose', text: doc.description}];
   if (doc.appliesTo) {
@@ -144,7 +153,8 @@ function selfDocSection(doc) {
     });
   }
   for (const example of doc.examples ?? []) {
-    if (typeof example?.code !== 'string' || example.code.trim() === '') continue;
+    if (typeof example?.code !== 'string' || example.code.trim() === '')
+      continue;
     content.push({
       type: 'code',
       lang: example.lang ?? 'js',

package/foundation/discovery/authoring-self-docs.test.mjs

@@ -74,14 +74,15 @@ describe('what the authoring docs say about the unbuilt docs graph', () => {
     expect(graphFieldsDoc.description).toMatch(/not built yet/);
   });
 
-  it('says a topic using a graph block fails to load', () => {
+  it('keeps graph blocks behind the separate GraphContentBlock type', () => {
     const content = referenceDoc.fields
       .flatMap(field => [field, ...(field.fields ?? [])])
       .find(field => field.name === 'sections[].content');
+    expect(content.type).toBe('ReferenceContentBlock[]');
+    expect(content.description).toContain('GraphContentBlock');
     for (const type of GRAPH_BLOCK_TYPES) {
       expect(content.description).toContain(type);
     }
-    expect(content.description).toMatch(/fails to load/);
   });
 
   it('says namespace docs are not loaded yet', () => {

package/foundation/discovery/authoring-surface.d.mts

@@ -0,0 +1,74 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Every type `@astryxdesign/cli/authoring` exports, in the order index.d.ts
+ * lists them, each traced to the module that declares it. A value export that
+ * traces to a JavaScript module (a parser) is not a type and is left out;
+ * anything else that cannot be traced is reported, never dropped.
+ * @param {string} [root]
+ * @returns {{
+ *   types: {name: string, module: string}[],
+ *   untraced: {name: string, reason: string}[],
+ * }} `module` is relative to `root`
+ */
+export function tracePublicAuthoringTypes(root?: string): {
+    types: {
+        name: string;
+        module: string;
+    }[];
+    untraced: {
+        name: string;
+        reason: string;
+    }[];
+};
+/**
+ * What stands between each type `@astryxdesign/cli/authoring` exports and a
+ * reader of `astryx docs authoring`. A type is readable when a self-doc beside
+ * the module that declares it is listed in AUTHORING_SELF_DOCS, loads, and
+ * renders a section the topic's index lists. A registered self-doc must
+ * document something public: a public type declared beside it, and, when its
+ * title is the name of a type declared beside it, that type.
+ * @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
+ *   `topicKeys` are the keys `astryx docs authoring --index` lists; null skips
+ *   that comparison.
+ * @returns {Promise<{
+ *   types: number,
+ *   unreadable: {module: string, names: string[], reason: UnreadableReason, source?: string, key?: string}[],
+ *   untraced: {name: string, reason: string}[],
+ *   unmatched: {source: string, key?: string, subject?: string}[],
+ * }>}
+ */
+export function auditAuthoringSurface({ root, sources, topicKeys, }?: {
+    root?: string;
+    sources?: string[];
+    topicKeys?: Set<string> | null;
+}): Promise<{
+    types: number;
+    unreadable: {
+        module: string;
+        names: string[];
+        reason: UnreadableReason;
+        source?: string;
+        key?: string;
+    }[];
+    untraced: {
+        name: string;
+        reason: string;
+    }[];
+    unmatched: {
+        source: string;
+        key?: string;
+        subject?: string;
+    }[];
+}>;
+/** The barrel the `types` condition of `@astryxdesign/cli/authoring` names. */
+export const AUTHORING_SURFACE: "index.d.ts";
+export type Tracer = {
+    root: string;
+    /**
+     * top-level statements by absolute path
+     */
+    parsed: Map<string, any[]>;
+};
+export type UnreadableReason = "no-self-doc" | "unregistered" | "failed" | "missing-section";