@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

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,8 +40,10 @@ import {parseConfig} from '../../authoring/config/parse.mjs';
 import {
   loadIntegrations,
   loadLocalIntegration,
+  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,
@@ -48,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 {
@@ -68,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,
@@ -94,6 +97,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
@@ -146,13 +261,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 {
@@ -181,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.
@@ -203,12 +338,15 @@ export class Project {
   /** @type {ProjectIntegrationIssue[]} */
   #issues = [];
   /**
-   * Package names of integrations whose issues have already been collected
-   * (via a discovery method or a direct issues() validation), so issues() can
-   * fill in only the ones not yet visited and never double-collect.
-   * @type {Set<string>}
+   * Loaded integrations whose issues have already been collected (via a
+   * discovery method or a direct issues() validation), so issues() can fill in
+   * only the ones not yet visited and never double-collect. Keyed by entry, not
+   * label: two entries can share a package name (an alias at another version).
+   * @type {Set<object>}
    */
   #visitedIssues = new Set();
+  /** @type {Promise<Array<object>> | null} */
+  #templatesPromise = null;
 
   /**
    * @param {object} init
@@ -274,7 +412,8 @@ 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,
       });
@@ -284,31 +423,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.
+    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
@@ -327,7 +477,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)
           : [],
       );
@@ -339,7 +489,7 @@ export class Project {
       // Never let recording break config loading.
     }
 
-    return new Project({
+    const project = new Project({
       cwd,
       configPath,
       config,
@@ -348,6 +498,8 @@ export class Project {
       cache: resolvedCache,
       hash,
     });
+    PROVIDER_LEDGERS.set(project, resolution.ledger);
+    return project;
   }
 
   /**
@@ -436,25 +588,16 @@ export class Project {
    * @returns {string}
    */
   #pkgLabel(integration) {
+    // A set-aside package is labelled name@version, so its issue never reads as
+    // the winner's, even when both share a package name.
+    if (integration?.__providerConflict) {
+      return integration.version
+        ? `${integration.name}@${integration.version}`
+        : (integration.__spec ?? integration.name);
+    }
     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
@@ -463,8 +606,8 @@ export class Project {
    */
   async #collectIssues(integration) {
     const pkg = this.#pkgLabel(integration);
-    if (this.#visitedIssues.has(pkg)) return;
-    this.#visitedIssues.add(pkg);
+    if (this.#visitedIssues.has(integration)) return;
+    this.#visitedIssues.add(integration);
     // A manifest that failed to load (throwing import / invalid shape) is
     // recorded as a marker by loadIntegrations — surface it as an issue and
     // skip validation (there's no manifest to validate).
@@ -491,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}>>}
    */
@@ -513,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',
@@ -539,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
@@ -570,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',
@@ -593,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[]>}
    */
@@ -612,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)));
@@ -646,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',
@@ -665,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',
@@ -686,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
@@ -705,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
@@ -760,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);
     }