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

package/foundation/agent-docs/agent-docs.test.mjs

@@ -55,6 +55,15 @@ describe('generateCompressedIndex', () => {
     expect(frameRule).not.toMatch(/https?:/);
   });
 
+  it('starts every page from a template before any component', () => {
+    const lines = generateCompressedIndex('1.0.0').split('\n');
+    const workflow = lines.findIndex(l => l.startsWith('WORKFLOW'));
+    expect(lines[workflow]).toMatch(/start every page from a template/);
+    expect(lines[workflow + 1]).toMatch(/^1\. `astryx build /);
+    expect(lines[workflow + 2]).toMatch(/^2\. `astryx template <name> <path>`/);
+    expect(lines.join('\n')).not.toMatch(/reference code/);
+  });
+
   it('includes the post-generation self-check rule', () => {
     const result = generateCompressedIndex('1.0.0');
     expect(result).toContain('SELF-CHECK before you finish');
@@ -134,7 +143,6 @@ describe('generateCompressedIndex', () => {
     const line = topicLine(generateCompressedIndex('1.0.0'));
     for (const topic of [
       'getting-started',
-      'cli-integrations',
       'browser-support',
       'styling-libraries',
       'working-with-ai',
@@ -143,6 +151,16 @@ describe('generateCompressedIndex', () => {
     }
   });
 
+  it('points to the CLI docs tree on a line of its own', () => {
+    // The integration guide lives in the docs tree now (cli/integrations), so
+    // the topic line no longer names it; the tree's entry point does.
+    const block = generateCompressedIndex('1.0.0');
+    expect(block).toContain(
+      '  docs cli           commands, API reference, integration authoring (one level at a time)',
+    );
+    expect(topicLine(block)).not.toContain('cli-integrations');
+  });
+
   it('lists the topics it is given, so an integration’s reach the agent', () => {
     const line = topicLine(
       generateCompressedIndex('1.0.0', {topics: ['tokens', 'deploying']}),

package/foundation/config/project-themes.test.mjs

@@ -15,6 +15,7 @@ function installThemeIntegration(packageName, slug) {
     ...packageName.split('/'),
   );
   const themeDir = path.join(packageDir, 'themes', slug);
+  const stem = `${slug.replace(/-([a-z0-9])/gu, (_, character) => character.toUpperCase())}Theme`;
   fs.mkdirSync(themeDir, {recursive: true});
   fs.writeFileSync(
     path.join(packageDir, 'package.json'),
@@ -22,28 +23,19 @@ function installThemeIntegration(packageName, slug) {
   );
   fs.writeFileSync(
     path.join(packageDir, 'astryx.integration.mjs'),
-    `export default {themes: './themes'};\n`,
+    `export default {themes: './themes'};
+`,
   );
   fs.writeFileSync(
-    path.join(packageDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug,
-          displayName: 'Ocean',
-          description: 'Blue and calm.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts'],
-        },
-      ],
-    }),
+    path.join(themeDir, `${stem}.doc.mjs`),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: '${slug}', displayName: 'Ocean', description: 'Blue and calm.', maintained: true};
+`,
   );
   fs.writeFileSync(
-    path.join(themeDir, 'oceanTheme.ts'),
-    `export const oceanTheme = {};\n`,
+    path.join(themeDir, `${stem}.ts`),
+    `export const ${stem} = {};
+`,
   );
 }
 
@@ -99,7 +91,7 @@ describe('Project themes', () => {
     ]);
   });
 
-  it('records an invalid integration theme catalog as an issue', async () => {
+  it('records an invalid integration theme descriptor as an issue', async () => {
     installThemeIntegration('@acme/themes', 'ocean');
     fs.rmSync(
       path.join(

package/foundation/config/project.d.mts

@@ -9,6 +9,14 @@
  * @returns {string|null}
  */
 export function findConfigPath(startDir?: string): string | null;
+/**
+ * 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: Project): import("../integrations/provider-resolution.mjs").ProviderLedger;
 /**
  * An integration issue tagged with the owner package. The base
  * {@link import('../integrations/issue').AstryxIntegrationIssue} fields plus the
@@ -87,9 +95,9 @@ export class Project {
     /**
      * Core + integration component ownership records. Wraps
      * discoverOwnedComponents for core and discoverIntegrationComponents (via
-     * discoverOwnedComponents) for integrations, but applies the skip+warn
-     * policy per integration: a broken integration's components are skipped and
-     * its issues collected, never thrown. Memoized per instance.
+     * discoverOwnedComponents) for integrations. Invalid component records are
+     * omitted and reported; valid component siblings and other contribution kinds
+     * remain available. Memoized per instance.
      *
      * @returns {Promise<Array<{name: string, package: string, group: string|null, docPath: string|null, sourcePath: string|null, issuesUrl: string|undefined}>>}
      */
@@ -102,10 +110,11 @@ export class Project {
         issuesUrl: string | undefined;
     }>>;
     /**
-     * Core + integration templates, type-tagged. Wraps discoverTemplates (core +
-     * external blocks) and discoverIntegrationTemplatesForOne per integration so
-     * a broken integration's templates are skipped and its issues collected.
-     * Memoized per instance.
+     * Core + integration templates, type-tagged, with valid integration
+     * replacements projected over their Core targets. Wraps raw template discovery
+     * (Core + external blocks) and discoverIntegrationTemplatesForOne per integration
+     * so unusable template files are reported and omitted while valid siblings
+     * remain available. Memoized per instance.
      *
      * @returns {Promise<Array<object>>}
      */
@@ -113,8 +122,8 @@ export class Project {
     /**
      * Bundled source themes plus themes contributed by installed integrations.
      * Each record keeps its package owner and source directory so callers can
-     * both list and copy it without reconstructing paths. A broken integration's
-     * themes are skipped under the same issue policy as every other kind.
+     * both list and copy it without reconstructing paths. A broken theme
+     * contribution is reported without hiding the package's other valid kinds.
      *
      * @returns {Promise<import('../discovery/theme-discovery.mjs').DiscoveredTheme[]>}
      */
@@ -137,8 +146,8 @@ export class Project {
     /**
      * Core registry transforms + integration codemods for an upgrade range.
      * Wraps getTransformsBetween (core) and discoverIntegrationCodemods /
-     * selectIntegrationCodemods (integrations). A broken integration's codemods
-     * are skipped (issue collected) rather than failing the whole resolution.
+     * selectIntegrationCodemods (integrations). An invalid codemod contribution
+     * is reported and omitted without hiding other valid contribution kinds.
      * Memoized per (from, to) key.
      *
      * @param {string} fromVersion exclusive lower bound

package/foundation/config/project.mjs

@@ -15,14 +15,16 @@
  *     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.
- *   - SKIP + WARN policy: as a discovery method runs, per-integration work is
- *     guarded so one broken integration never throws out of discovery. Any
- *     AstryxIntegrationIssue encountered is collected into a private set and
- *     that integration's contributions are skipped.
+ *   - SKIP + WARN policy: discovery records each integration issue. Other valid
+ *     contribution kinds remain available; invalid template and component files
+ *     do not hide valid siblings. A manifest load failure still withdraws the
+ *     package because its roots cannot be trusted.
  *   - `issues()` returns the deduped accumulated set, and (when called
  *     directly) fills in validation for any configured integration not yet
  *     visited by a discovery call, so it is always complete on demand.
@@ -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,
@@ -50,11 +52,13 @@ import {
 import {
   CORE_PACKAGE,
   discoverOwnedComponents,
-  discoverIntegrationComponents,
+  discoverValidIntegrationComponents,
 } from '../discovery/component-discovery.mjs';
 import {findCoreDir} from '../fs/paths.mjs';
 import {
-  discoverAll as discoverTemplates,
+  applyTemplateReplacements,
+  effectiveTemplateDiscovery,
+  discoverAllUnresolved as discoverTemplates,
   discoverIntegrationTemplatesForOne,
 } from '../discovery/template-adapter.mjs';
 import {
@@ -70,10 +74,7 @@ import {
   discoverIntegrationCodemods,
   selectIntegrationCodemods,
 } from '../../assets/codemods/integration-discovery.mjs';
-import {
-  INVALID_AGENT_DOCS,
-  validateLoadedIntegration,
-} from '../integrations/validate-contributions.mjs';
+import {validateLoadedIntegration} from '../integrations/validate-contributions.mjs';
 import {
   InMemoryConfigCache,
   cacheKey,
@@ -297,6 +298,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.
@@ -326,6 +345,8 @@ export class Project {
    * @type {Set<object>}
    */
   #visitedIssues = new Set();
+  /** @type {Promise<Array<object>> | null} */
+  #templatesPromise = null;
 
   /**
    * @param {object} init
@@ -402,17 +423,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 +438,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 +489,7 @@ export class Project {
       // Never let recording break config loading.
     }
 
-    return new Project({
+    const project = new Project({
       cwd,
       configPath,
       config,
@@ -470,6 +498,8 @@ export class Project {
       cache: resolvedCache,
       hash,
     });
+    PROVIDER_LEDGERS.set(project, resolution.ledger);
+    return project;
   }
 
   /**
@@ -568,22 +598,6 @@ export class Project {
     return integration?.name ?? integration?.__spec ?? '(integration)';
   }
 
-  /**
-   * Whether this package has an error that invalidates its regular manifest
-   * contributions. Invalid `agentDocs` blocks agent-doc writes only; it must not
-   * withdraw components, templates, docs, or codemods.
-   * @param {string} pkg
-   * @returns {boolean}
-   */
-  #hasBlockingContributionIssue(pkg) {
-    return this.#issues.some(
-      issue =>
-        issue.package === pkg &&
-        issue.severity === 'error' &&
-        issue.code !== INVALID_AGENT_DOCS,
-    );
-  }
-
   /**
    * Validate one loaded integration and collect any issues. Marks the
    * integration visited so issues() won't redo the work. Best-effort: a
@@ -620,9 +634,9 @@ export class Project {
   /**
    * Core + integration component ownership records. Wraps
    * discoverOwnedComponents for core and discoverIntegrationComponents (via
-   * discoverOwnedComponents) for integrations, but applies the skip+warn
-   * policy per integration: a broken integration's components are skipped and
-   * its issues collected, never thrown. Memoized per instance.
+   * discoverOwnedComponents) for integrations. Invalid component records are
+   * omitted and reported; valid component siblings and other contribution kinds
+   * remain available. Memoized per instance.
    *
    * @returns {Promise<Array<{name: string, package: string, group: string|null, docPath: string|null, sourcePath: string|null, issuesUrl: string|undefined}>>}
    */
@@ -642,18 +656,17 @@ export class Project {
         }
       }
 
-      // Each integration in isolation so one broken integration is skipped.
+      // Each integration is discovered independently. Invalid records are
+      // omitted below without hiding valid siblings or other contribution kinds.
       for (const integration of this.#loadedIntegrations) {
         await this.#collectIssues(integration);
         const pkg = this.#pkgLabel(integration);
-        if (this.#hasBlockingContributionIssue(pkg)) continue;
         try {
-          // discoverOwnedComponents owns the core+integration record shape;
-          // here we add only this integration's records (core is handled
-          // above) so a single broken integration can be skipped in isolation.
-          for (const rec of discoverIntegrationComponents(integration)) {
-            records.push(rec);
-          }
+          // #collectIssues (above) already reported each withdrawn record,
+          // with its fix, through the same discovery.
+          const {components} =
+            await discoverValidIntegrationComponents(integration);
+          records.push(...components);
         } catch (err) {
           this.#pushIssue(pkg, {
             code: 'invalid_component',
@@ -668,17 +681,21 @@ export class Project {
   }
 
   /**
-   * Core + integration templates, type-tagged. Wraps discoverTemplates (core +
-   * external blocks) and discoverIntegrationTemplatesForOne per integration so
-   * a broken integration's templates are skipped and its issues collected.
-   * Memoized per instance.
+   * Core + integration templates, type-tagged, with valid integration
+   * replacements projected over their Core targets. Wraps raw template discovery
+   * (Core + external blocks) and discoverIntegrationTemplatesForOne per integration
+   * so unusable template files are reported and omitted while valid siblings
+   * remain available. Memoized per instance.
    *
    * @returns {Promise<Array<object>>}
    */
   async templates() {
-    return this.#memo('templates', async () => {
+    if (this.#templatesPromise) return this.#templatesPromise;
+    this.#templatesPromise = (async () => {
       /** @type {any[]} */
       const templates = [];
+      /** @type {import('../discovery/template-adapter.mjs').TemplateDiscoveryError[]} */
+      const replacementErrors = [];
 
       // Core + external-package templates (discoverTemplates internally also
       // loads integration templates via loadConfig today; we intentionally
@@ -699,20 +716,24 @@ export class Project {
       for (const integration of this.#loadedIntegrations) {
         await this.#collectIssues(integration);
         const pkg = this.#pkgLabel(integration);
-        if (this.#hasBlockingContributionIssue(pkg)) continue;
+        // Template discovery already isolates invalid template files and returns
+        // every valid sibling. Do not withdraw templates because another
+        // contribution kind in this package is broken.
         try {
           const {templates: ts, errors} =
             await discoverIntegrationTemplatesForOne(integration);
           for (const e of errors) {
             this.#pushIssue(pkg, {
-              code: 'invalid_template',
-              severity: 'error',
+              code: e.code ?? 'invalid_template',
+              severity: e.severity ?? 'error',
               message: e.message,
             });
+            if (e.replacementTarget != null) replacementErrors.push(e);
           }
-          // Only contribute templates when the integration had no per-template
-          // errors (skip the whole integration's templates on any error).
-          if (errors.length === 0) templates.push(...ts);
+          // Discovery already omits each unusable template from `ts`. Keep all
+          // valid siblings, while the collected errors remain visible through
+          // issues() and replacement errors disable only their own targets.
+          templates.push(...ts);
         } catch (err) {
           this.#pushIssue(pkg, {
             code: 'invalid_template',
@@ -722,15 +743,24 @@ export class Project {
         }
       }
 
-      return templates.sort((a, b) => a.name.localeCompare(b.name));
-    });
+      const resolved = applyTemplateReplacements(templates, replacementErrors);
+      for (const error of resolved.errors) {
+        this.#pushIssue(error.package, {
+          code: error.code,
+          severity: error.severity,
+          message: error.message,
+        });
+      }
+      return effectiveTemplateDiscovery(resolved.templates);
+    })();
+    return this.#templatesPromise;
   }
 
   /**
    * Bundled source themes plus themes contributed by installed integrations.
    * Each record keeps its package owner and source directory so callers can
-   * both list and copy it without reconstructing paths. A broken integration's
-   * themes are skipped under the same issue policy as every other kind.
+   * both list and copy it without reconstructing paths. A broken theme
+   * contribution is reported without hiding the package's other valid kinds.
    *
    * @returns {Promise<import('../discovery/theme-discovery.mjs').DiscoveredTheme[]>}
    */
@@ -741,7 +771,6 @@ export class Project {
       for (const integration of this.#loadedIntegrations) {
         await this.#collectIssues(integration);
         const pkg = this.#pkgLabel(integration);
-        if (this.#hasBlockingContributionIssue(pkg)) continue;
         if (!integration?.themes) continue;
         try {
           themes.push(...(await discoverIntegrationThemes(integration)));
@@ -775,14 +804,16 @@ export class Project {
   async docs() {
     return this.#memo('docs', async () => {
       const catalog = DocsCatalog.fromBuiltins();
+      let rank = 0;
 
       for (const integration of this.#loadedIntegrations) {
+        rank += 1;
         await this.#collectIssues(integration);
         const pkg = this.#pkgLabel(integration);
-        if (this.#hasBlockingContributionIssue(pkg)) continue;
         if (!integration?.docs) continue;
         try {
-          const {records, errors} = await discoverIntegrationDocs(integration);
+          const {records, errors, namespaces, guides} =
+            await discoverIntegrationDocs(integration);
           for (const e of errors) {
             this.#pushIssue(pkg, {
               code: 'invalid_doc',
@@ -794,11 +825,20 @@ export class Project {
           // how a bad template withdraws its package's templates: a partial
           // docs contribution is the state where a `replaces` silently does
           // nothing and a reader gets the topic it was meant to replace.
-          if (errors.length > 0) continue;
+          if (errors.length > 0) {
+            for (const e of errors) {
+              catalog.addIssue({package: integration.name ?? pkg, message: e.message});
+            }
+            continue;
+          }
           for (const record of records) {
             const issue = catalog.add(record);
             if (issue) this.#pushIssue(pkg, issue);
           }
+          catalog.addTreeInputs({
+            namespaces: namespaces.map(input => ({...input, rank})),
+            guides: guides.map(input => ({...input, rank})),
+          });
         } catch (err) {
           this.#pushIssue(pkg, {
             code: 'invalid_doc',
@@ -815,8 +855,8 @@ export class Project {
   /**
    * Core registry transforms + integration codemods for an upgrade range.
    * Wraps getTransformsBetween (core) and discoverIntegrationCodemods /
-   * selectIntegrationCodemods (integrations). A broken integration's codemods
-   * are skipped (issue collected) rather than failing the whole resolution.
+   * selectIntegrationCodemods (integrations). An invalid codemod contribution
+   * is reported and omitted without hiding other valid contribution kinds.
    * Memoized per (from, to) key.
    *
    * @param {string} fromVersion exclusive lower bound
@@ -834,7 +874,6 @@ export class Project {
       for (const integration of this.#loadedIntegrations) {
         await this.#collectIssues(integration);
         const pkg = this.#pkgLabel(integration);
-        if (this.#hasBlockingContributionIssue(pkg)) continue;
         if (!integration?.codemods) continue;
         try {
           // Validate this integration's codemods discover cleanly in
@@ -889,6 +928,10 @@ export class Project {
    * @returns {Promise<ProjectIntegrationIssue[]>}
    */
   async issues() {
+    // Template replacement validity depends on the combined Core + integration
+    // catalog. Resolve it first so issue results never depend on which discovery
+    // method the caller happened to invoke earlier.
+    await this.templates();
     for (const integration of this.#loadedIntegrations) {
       await this.#collectIssues(integration);
     }