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

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,9 +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,
@@ -95,6 +98,118 @@ function errorMessage(err) {
   return message == null ? String(err) : String(message);
 }
 
+/**
+ * Load the configured integrations one at a time, so a package that cannot
+ * load at all (not installed, no manifest, more than one manifest, not a bare
+ * name) becomes that entry's load-error marker instead of failing the project.
+ * @param {string[]} specs
+ * @param {{cwd: string, fresh: boolean}} options
+ * @returns {Promise<import('../integrations/integrations.mjs').LoadedIntegration[]>}
+ */
+async function loadConfiguredIntegrations(specs, {cwd, fresh}) {
+  /** @type {import('../integrations/integrations.mjs').LoadedIntegration[]} */
+  const loaded = [];
+  const seen = new Set();
+  for (const spec of specs) {
+    if (!spec || seen.has(spec)) continue;
+    seen.add(spec);
+    try {
+      loaded.push(
+        ...(await loadIntegrations([spec], {
+          cwd,
+          fresh,
+          resolveProviders: false,
+        })),
+      );
+    } catch (err) {
+      /** @type {string|undefined} */
+      let packageDir;
+      try {
+        packageDir = resolvePackageDir(spec, cwd);
+      } catch {
+        // Not a bare package name: there is no install location to record.
+      }
+      const pkg = packageDir ? readPackageJson(packageDir) : null;
+      loaded.push(
+        loadErrorMarker({
+          name: packageName(pkg) ?? spec,
+          version: pkg?.version,
+          spec,
+          packageDir,
+          err,
+        }),
+      );
+    }
+  }
+  return loaded;
+}
+
+/**
+ * Resolve the package being authored. Every failure, including an unreadable
+ * package.json or more than one manifest, becomes its load-error marker.
+ * @param {string} projectDir
+ * @param {boolean} fresh
+ * @returns {Promise<import('../integrations/integrations.mjs').LoadedIntegration|null>}
+ */
+async function loadLocalIntegrationSafely(projectDir, fresh) {
+  try {
+    return await loadLocalIntegration(projectDir, {fresh});
+  } catch (err) {
+    const pkg = readPackageJson(projectDir);
+    const name = packageName(pkg) ?? '(local integration)';
+    return {
+      ...loadErrorMarker({
+        name,
+        version: pkg?.version,
+        spec: name,
+        packageDir: projectDir,
+        err,
+      }),
+      __local: true,
+    };
+  }
+}
+
+/**
+ * An inert entry for an integration that could not be loaded. It contributes
+ * nothing; Project reports its `__loadError` as the package's issue.
+ * @param {{name: string, version?: unknown, spec: string, packageDir?: string, err: unknown}} input
+ * @returns {import('../integrations/integrations.mjs').LoadedIntegration}
+ */
+function loadErrorMarker({name, version, spec, packageDir, err}) {
+  return /** @type {import('../integrations/integrations.mjs').LoadedIntegration} */ ({
+    name,
+    ...(typeof version === 'string' ? {version} : {}),
+    __spec: spec,
+    ...(packageDir ? {__packageDir: packageDir} : {}),
+    __loadError: errorMessage(err),
+  });
+}
+
+/**
+ * @param {Record<string, unknown>|null} pkg
+ * @returns {string|undefined}
+ */
+function packageName(pkg) {
+  const name = pkg?.name;
+  return typeof name === 'string' && name.length > 0 ? name : undefined;
+}
+
+/**
+ * @param {string} dir
+ * @returns {Record<string, unknown>|null}
+ */
+function readPackageJson(dir) {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'),
+    );
+    return pkg && typeof pkg === 'object' ? pkg : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * An integration issue tagged with the owner package. The base
  * {@link import('../integrations/issue').AstryxIntegrationIssue} fields plus the
@@ -147,13 +262,15 @@ function findPackageRoot(startDir) {
  *
  * This governs INHERITED handlers only. A project's own `debug` always runs.
  *
- * @param {string|null} configPath
+ * Read from the project root whether or not an astryx.config exists: an
+ * autolinked integration contributes a handler with no config at all.
+ *
+ * @param {string} projectDir directory holding the project's package.json
  * @returns {boolean}
  */
-function inheritsIntegrationDebug(configPath) {
-  if (!configPath) return true;
+function inheritsIntegrationDebug(projectDir) {
   try {
-    const pkgPath = path.join(path.dirname(configPath), 'package.json');
+    const pkgPath = path.join(projectDir, 'package.json');
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
     return pkg?.astryx?.inheritDebug !== false;
   } catch {
@@ -182,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.
@@ -276,11 +411,10 @@ export class Project {
         fresh,
       });
       integrations = config.integrations ?? [];
-      loadedIntegrations = await loadIntegrations(integrations, {
+      // Provider identity is resolved once, below, over the final set.
+      loadedIntegrations = await loadConfiguredIntegrations(integrations, {
         cwd: projectDir,
         fresh,
-        // Provider identity is resolved once, below, over the final set.
-        resolveProviders: false,
       });
     }
 
@@ -288,35 +422,42 @@ 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
     // existing consumer command doubles as the author's preview. A local copy
     // replaces the same installed package in place, preserving configured
     // precedence while making the source being edited authoritative.
-    const localIntegration = await loadLocalIntegration(projectDir, {fresh});
-    if (localIntegration) {
-      const existing = loadedIntegrations.findIndex(
-        integration => integration.name === localIntegration.name,
-      );
-      if (existing === -1) loadedIntegrations.push(localIntegration);
-      else loadedIntegrations[existing] = localIntegration;
-    }
+    const localIntegration = await loadLocalIntegrationSafely(projectDir, fresh);
 
     // 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
@@ -335,7 +476,7 @@ export class Project {
       // because Project.load can run more than once in a process and appending
       // would deliver twice.
       setDebugIntegrationEventHandlers(
-        inheritsIntegrationDebug(configPath)
+        inheritsIntegrationDebug(projectDir)
           ? loadedIntegrations.map(integration => integration.__debug)
           : [],
       );
@@ -347,7 +488,7 @@ export class Project {
       // Never let recording break config loading.
     }
 
-    return new Project({
+    const project = new Project({
       cwd,
       configPath,
       config,
@@ -356,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'),
@@ -515,6 +502,132 @@ describe('Project issues (skip + warn)', () => {
   });
 });
 
+describe('Project loads each integration in isolation', () => {
+  /**
+   * Install a package under node_modules with the given root files.
+   * @param {string} name
+   * @param {string[]} manifests manifest basenames to write
+   */
+  function installPackage(name, manifests) {
+    const dir = path.join(tmpDir, 'node_modules', ...name.split('/'));
+    fs.mkdirSync(dir, {recursive: true});
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      JSON.stringify({name, version: '1.0.0'}),
+    );
+    for (const file of manifests) {
+      fs.writeFileSync(path.join(dir, file), 'export default {};\n');
+    }
+  }
+
+  /** @param {string[]} integrations */
+  function writeConfig(integrations) {
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      `export default ${JSON.stringify({integrations})};\n`,
+    );
+  }
+
+  /** @param {Project} project */
+  async function widgetComponents(project) {
+    return (await project.components())
+      .filter(component => component.package === '@acme/widgets')
+      .map(component => component.name);
+  }
+
+  it.each([
+    ['is not installed', '@acme/broken', () => {}, /Install it first/],
+    [
+      'has no root manifest',
+      '@acme/broken',
+      () => installPackage('@acme/broken', []),
+      /no conventional root manifest/,
+    ],
+    [
+      'has two root manifests',
+      '@acme/broken',
+      () =>
+        installPackage('@acme/broken', [
+          'astryx.integration.mjs',
+          'astryx.integration.js',
+        ]),
+      /multiple root manifests/,
+    ],
+    [
+      'is not a bare package name',
+      '../escape',
+      () => {},
+      /Invalid integration package name/,
+    ],
+  ])(
+    'keeps the others when a configured package %s',
+    async (_label, spec, install, message) => {
+      scaffold();
+      install();
+      writeConfig([spec, '@acme/widgets']);
+
+      const project = await Project.load(tmpDir);
+
+      expect(await widgetComponents(project)).toEqual(['Widget']);
+      expect(await project.issues()).toContainEqual(
+        expect.objectContaining({
+          package: spec,
+          code: 'integration_error',
+          message: expect.stringMatching(message),
+        }),
+      );
+    },
+  );
+
+  it('keeps configured integrations when the package being authored has two root manifests', async () => {
+    scaffold();
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/local', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.js'),
+      'export default {};\n',
+    );
+
+    const project = await Project.load(tmpDir);
+
+    expect(await widgetComponents(project)).toEqual(['Widget']);
+    expect(await project.issues()).toContainEqual(
+      expect.objectContaining({
+        package: '@acme/local',
+        code: 'integration_error',
+        message: expect.stringMatching(/multiple root manifests/),
+      }),
+    );
+  });
+
+  it('puts the package being authored at its configured position when the config names it', async () => {
+    scaffold();
+    scaffoldLocalPackage({name: '@acme/local'});
+    writeConfig(['@acme/local', '@acme/widgets']);
+
+    const project = await Project.load(tmpDir);
+
+    expect(
+      project.loadedIntegrations.map(integration => [
+        integration.name,
+        Boolean(integration.__local),
+      ]),
+    ).toEqual([
+      ['@acme/local', true],
+      ['@acme/widgets', false],
+    ]);
+    expect(await project.issues()).not.toContainEqual(
+      expect.objectContaining({package: '@acme/local', code: 'integration_error'}),
+    );
+  });
+});
+
 describe('Project.issuesUrl routing', () => {
   it('routes core to config.issuesUrl, falling back to the default', async () => {
     scaffold({issuesUrl: 'https://example.com/core'});

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

@@ -9,7 +9,14 @@ import {
   buildAuthoringTopic,
   discoverAuthoringSelfDocSources,
 } from './authoring-self-docs.mjs';
-import {problemsInTopic} from './docs-discovery.mjs';
+import {
+  GRAPH_BLOCK_TYPES,
+  GRAPH_ONLY_FIELDS,
+  problemsInTopic,
+} from './docs-discovery.mjs';
+import {doc as graphFieldsDoc} from '../../authoring/doctypes/base/graph-fields.doc.mjs';
+import {doc as namespaceDoc} from '../../authoring/doctypes/namespace/namespace.doc.mjs';
+import {doc as referenceDoc} from '../../authoring/doctypes/reference/reference.doc.mjs';
 import {docs} from '../../api/docs/docs.mjs';
 
 const SLOW = 60_000;
@@ -37,14 +44,58 @@ describe('authoring self-docs', () => {
     expect(topic.sections).toHaveLength(AUTHORING_SELF_DOCS.length);
   });
 
-  it('is readable progressively through the docs API', async () => {
-    const index = await docs('authoring', undefined, {index: true});
-    expect(index.type).toBe('docs.index');
-    expect(index.data.sections.map(s => s.id)).toContain('integration');
-    const section = await docs('authoring', 'integration');
-    expect(section.data.title).toBe('Astryx Integration');
-    expect(section.data.content.some(block => block.type === 'table')).toBe(true);
-  }, SLOW);
+  it(
+    'is readable progressively through the docs API',
+    async () => {
+      const index = await docs('authoring', undefined, {index: true});
+      expect(index.type).toBe('docs.index');
+      expect(index.data.sections.map(s => s.id)).toContain('integration');
+      const section = await docs('authoring', 'integration');
+      expect(section.data.title).toBe('Astryx Integration');
+      expect(section.data.content.some(block => block.type === 'table')).toBe(
+        true,
+      );
+    },
+    SLOW,
+  );
+});
+
+describe('what the authoring docs say about the unbuilt docs graph', () => {
+  it('marks exactly the fields topic loading rejects as not read yet', () => {
+    const notReadYet = graphFieldsDoc.fields
+      .filter(field => /Not read yet/.test(field.description))
+      .map(field => field.name);
+    expect(notReadYet.sort()).toEqual([...GRAPH_ONLY_FIELDS].sort());
+    for (const field of graphFieldsDoc.fields) {
+      if (notReadYet.includes(field.name)) {
+        expect(field.description).toMatch(/fails to load/);
+      }
+    }
+    expect(graphFieldsDoc.description).toMatch(/not built yet/);
+  });
+
+  it('says a topic using a graph block fails to load', () => {
+    const content = referenceDoc.fields
+      .flatMap(field => [field, ...(field.fields ?? [])])
+      .find(field => field.name === 'sections[].content');
+    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', () => {
+    expect(namespaceDoc.description).toMatch(/Not loaded yet/);
+    expect(
+      problemsInTopic({
+        ...namespaceDoc.examples?.[0],
+        type: 'namespace',
+        name: 'x',
+      }),
+    ).toEqual([
+      '"x" is a namespace doc. Only the docs graph reads namespace docs, and it is not built yet; remove this file from the docs directory.',
+    ]);
+  });
 });
 
 describe('auditAuthoringSelfDocs', () => {
@@ -68,17 +119,25 @@ describe('auditAuthoringSelfDocs', () => {
       path.join(root, 'kept', 'forgotten.doc.mjs'),
       "export const doc = {name: 'forgotten', description: 'Not listed.'};\n",
     );
-    const audit = await auditAuthoringSelfDocs({root, sources: ['kept/kept.doc.mjs']});
+    const audit = await auditAuthoringSelfDocs({
+      root,
+      sources: ['kept/kept.doc.mjs'],
+    });
     expect(audit.unreachable).toEqual(['kept/forgotten.doc.mjs']);
   });
 
   it('reports a self-doc that fails to load instead of throwing', async () => {
-    fs.writeFileSync(path.join(root, 'kept', 'broken.doc.mjs'), 'export const doc = {;\n');
+    fs.writeFileSync(
+      path.join(root, 'kept', 'broken.doc.mjs'),
+      'export const doc = {;\n',
+    );
     const audit = await auditAuthoringSelfDocs({
       root,
       sources: ['kept/kept.doc.mjs', 'kept/broken.doc.mjs'],
     });
-    expect(audit.failed.map(entry => entry.source)).toEqual(['kept/broken.doc.mjs']);
+    expect(audit.failed.map(entry => entry.source)).toEqual([
+      'kept/broken.doc.mjs',
+    ]);
     expect(audit.sections).toBe(1);
   });