@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ebaebc4

package/foundation/integrations/integrations.d.mts

@@ -1,6 +1,23 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * Resolve provider identity across loaded integrations, in precedence order.
+ *
+ * Artifact and document IDs are provider-scoped, so two packages cannot both
+ * contribute under one provider ID. The same package reached twice (an npm
+ * alias beside the package it aliases, with the same name and version) loads
+ * once. Any other later claimant, including the same package at another
+ * version, stays as an inert entry that carries the conflict. The package being
+ * authored claims its ID before precedence order is considered, because the
+ * source being edited is authoritative. The winner still contributes; Project
+ * issues, Doctor, and the per-command warning name the one set aside instead of
+ * dropping it without a word.
+ *
+ * @param {LoadedIntegration[]} integrations in precedence order
+ * @returns {LoadedIntegration[]}
+ */
+export function markProviderConflicts(integrations: LoadedIntegration[]): LoadedIntegration[];
 /**
  * Return the conventional root manifest paths present in `dir`, in
  * load-precedence order. Unlike {@link resolveManifestPath} this never throws —
@@ -75,12 +92,15 @@ export function loadLocalIntegration(packageDir: string, { fresh }?: {
  * Load configured integrations.
  *
  * @param {string[]} [specs] package names
- * @param {{cwd?: string, fresh?: boolean}} [options]
+ * @param {{cwd?: string, fresh?: boolean, resolveProviders?: boolean}} [options]
+ *   `resolveProviders: false` leaves provider identity to a caller that
+ *   resolves it once over a larger set (Project.load)
  * @returns {Promise<LoadedIntegration[]>}
  */
-export function loadIntegrations(specs?: string[], { cwd, fresh }?: {
+export function loadIntegrations(specs?: string[], { cwd, fresh, resolveProviders }?: {
     cwd?: string;
     fresh?: boolean;
+    resolveProviders?: boolean;
 }): Promise<LoadedIntegration[]>;
 /**
  * A fully-resolved, loaded integration. Identity (`name`, `version`) comes from
@@ -89,6 +109,10 @@ export function loadIntegrations(specs?: string[], { cwd, fresh }?: {
  * are internal bookkeeping used by Doctor integration validation and Project.
  * @typedef {object} LoadedIntegration
  * @property {string} name
+ * @property {import('../../authoring/identity/type').ProviderId} [providerId]
+ *   normalized stable provider identity; absent only for a legacy unnamed local
+ *   package. Unique among contributing integrations: a later claimant is kept
+ *   inert with `__providerConflict` (see {@link markProviderConflicts})
  * @property {string} [version]
  * @property {string} [components]
  * @property {string} [templates]
@@ -107,6 +131,10 @@ export function loadIntegrations(specs?: string[], { cwd, fresh }?: {
  * @property {string} __manifestFile
  * @property {string} [__loadError] set when the manifest failed to load/validate;
  *   such an integration contributes nothing and is surfaced via Project.issues()
+ * @property {{providerId: import('../../authoring/identity/type').ProviderId, claimedBy: string, message: string}} [__providerConflict]
+ *   set on a package whose provider ID an earlier-loaded package already
+ *   claims; it contributes nothing and is reported as a `duplicate_provider`
+ *   warning
  * @property {string[]} [__unknownKeys] manifest keys this CLI does not know —
  *   surfaced as a warning; the rest of the manifest still contributes
  * @property {boolean} [__autolinked] loaded because the project declares the
@@ -134,6 +162,12 @@ export const MANIFEST_BASENAMES: string[];
  */
 export type LoadedIntegration = {
     name: string;
+    /**
+     * normalized stable provider identity; absent only for a legacy unnamed local
+     * package. Unique among contributing integrations: a later claimant is kept
+     * inert with `__providerConflict` (see {@link markProviderConflicts})
+     */
+    providerId?: import("../../authoring/identity/type").ProviderId | undefined;
     version?: string | undefined;
     components?: string | undefined;
     templates?: string | undefined;
@@ -163,6 +197,16 @@ export type LoadedIntegration = {
      * such an integration contributes nothing and is surfaced via Project.issues()
      */
     __loadError?: string | undefined;
+    /**
+     * set on a package whose provider ID an earlier-loaded package already
+     * claims; it contributes nothing and is reported as a `duplicate_provider`
+     * warning
+     */
+    __providerConflict?: {
+        providerId: import("../../authoring/identity/type").ProviderId;
+        claimedBy: string;
+        message: string;
+    } | undefined;
     /**
      * manifest keys this CLI does not know —
      * surfaced as a warning; the rest of the manifest still contributes

package/foundation/integrations/integrations.mjs

@@ -6,13 +6,19 @@
  * Integrations are PACKAGE NAMES listed in astryx.config.{ts,mjs,js}. Each
  * package declares a single conventional root manifest sibling to its
  * package.json — astryx.integration.{ts,mjs,js} — which contributes
- * components/templates/codemods/docs/themes roots and an optional issuesUrl. Identity
- * (name, version) comes from the package's package.json, not the manifest.
+ * components/templates/codemods/docs/themes roots and an optional issuesUrl.
+ * Stable provider identity and package metadata come from package.json, not the
+ * manifest.
+ *
+ * @input Integration package names, package.json files, and root manifests.
+ * @output LoadedIntegration records with normalized provider identity and roots.
+ * @position foundation/integrations — package contribution loading boundary.
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {assertWithin} from '../fs/path-safety.mjs';
+import {normalizeProviderId} from '../identity/provider-identity.mjs';
 // The key census and contribution parsers are internal to the schema module on
 // purpose: the public parser still validates the complete authored type, while
 // the loader can isolate an invalid optional contribution from valid roots.
@@ -31,6 +37,10 @@ import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
  * are internal bookkeeping used by Doctor integration validation and Project.
  * @typedef {object} LoadedIntegration
  * @property {string} name
+ * @property {import('../../authoring/identity/type').ProviderId} [providerId]
+ *   normalized stable provider identity; absent only for a legacy unnamed local
+ *   package. Unique among contributing integrations: a later claimant is kept
+ *   inert with `__providerConflict` (see {@link markProviderConflicts})
  * @property {string} [version]
  * @property {string} [components]
  * @property {string} [templates]
@@ -49,6 +59,10 @@ import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
  * @property {string} __manifestFile
  * @property {string} [__loadError] set when the manifest failed to load/validate;
  *   such an integration contributes nothing and is surfaced via Project.issues()
+ * @property {{providerId: import('../../authoring/identity/type').ProviderId, claimedBy: string, message: string}} [__providerConflict]
+ *   set on a package whose provider ID an earlier-loaded package already
+ *   claims; it contributes nothing and is reported as a `duplicate_provider`
+ *   warning
  * @property {string[]} [__unknownKeys] manifest keys this CLI does not know —
  *   surfaced as a warning; the rest of the manifest still contributes
  * @property {boolean} [__autolinked] loaded because the project declares the
@@ -74,6 +88,137 @@ export const MANIFEST_BASENAMES = [
   'astryx.integration.js',
 ];
 
+/**
+ * Normalize a package-owned provider ID without rejecting legacy unnamed local
+ * packages at this compatibility boundary.
+ * @param {unknown} name
+ * @returns {import('../../authoring/identity/type').ProviderId | undefined}
+ */
+function providerIdForPackage(name) {
+  if (typeof name !== 'string' || name.length === 0) return undefined;
+  try {
+    return normalizeProviderId(name);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve provider identity across loaded integrations, in precedence order.
+ *
+ * Artifact and document IDs are provider-scoped, so two packages cannot both
+ * contribute under one provider ID. The same package reached twice (an npm
+ * alias beside the package it aliases, with the same name and version) loads
+ * once. Any other later claimant, including the same package at another
+ * version, stays as an inert entry that carries the conflict. The package being
+ * authored claims its ID before precedence order is considered, because the
+ * source being edited is authoritative. The winner still contributes; Project
+ * issues, Doctor, and the per-command warning name the one set aside instead of
+ * dropping it without a word.
+ *
+ * @param {LoadedIntegration[]} integrations in precedence order
+ * @returns {LoadedIntegration[]}
+ */
+export function markProviderConflicts(integrations) {
+  /** @type {Map<string, LoadedIntegration>} */
+  const claims = new Map();
+  for (const integration of integrations) {
+    if (integration?.__local && claimsProvider(integration)) {
+      const providerId = /** @type {string} */ (integration.providerId);
+      if (!claims.has(providerId)) claims.set(providerId, integration);
+    }
+  }
+  /** @type {LoadedIntegration[]} */
+  const resolved = [];
+  for (const integration of integrations) {
+    if (!claimsProvider(integration)) {
+      resolved.push(integration);
+      continue;
+    }
+    const providerId = /** @type {string} */ (integration.providerId);
+    const claimant = claims.get(providerId);
+    if (claimant == null) {
+      claims.set(providerId, integration);
+      resolved.push(integration);
+    } else if (claimant === integration) {
+      resolved.push(integration);
+    } else if (
+      claimant.name !== integration.name ||
+      claimant.version !== integration.version
+    ) {
+      resolved.push(providerConflict(integration, claimant));
+    }
+  }
+  return resolved;
+}
+
+/**
+ * Whether an entry contributes under its provider ID: it has one, its manifest
+ * loaded, and it has not already been set aside.
+ * @param {LoadedIntegration | undefined} integration
+ * @returns {boolean}
+ */
+function claimsProvider(integration) {
+  return (
+    integration?.providerId != null &&
+    integration.__loadError == null &&
+    integration.__providerConflict == null
+  );
+}
+
+/**
+ * @param {LoadedIntegration} integration
+ * @returns {string}
+ */
+function describeIntegration(integration) {
+  const id = integration.version
+    ? `${integration.name}@${integration.version}`
+    : integration.name;
+  return integration.__spec && integration.__spec !== integration.name
+    ? `${id} (from "${integration.__spec}")`
+    : id;
+}
+
+/**
+ * An inert record for a package whose provider ID is already claimed. It keeps
+ * the package's identity and location for reporting, and drops every
+ * contribution root and handler.
+ * @param {LoadedIntegration} integration
+ * @param {LoadedIntegration} claimant
+ * @returns {LoadedIntegration}
+ */
+function providerConflict(integration, claimant) {
+  const providerId =
+    /** @type {import('../../authoring/identity/type').ProviderId} */ (
+      integration.providerId
+    );
+  const winner = describeIntegration(claimant);
+  const setAside = describeIntegration(integration);
+  const reason = claimant.__local
+    ? 'is the package being authored, so it is used'
+    : 'loads first and is used';
+  return {
+    name: integration.name,
+    providerId,
+    version: integration.version,
+    __spec: integration.__spec,
+    __packageDir: integration.__packageDir,
+    __manifestFile: integration.__manifestFile,
+    ...(integration.__local ? {__local: true} : {}),
+    ...(integration.__autolinked
+      ? {__autolinked: true, __dependencyField: integration.__dependencyField}
+      : {}),
+    __providerConflict: {
+      providerId,
+      claimedBy: claimant.name,
+      message:
+        `${setAside} and ${winner} both claim provider ID "${providerId}". ` +
+        `${winner} ${reason}; ${setAside} contributes nothing ` +
+        'until one package changes its providerId.',
+    },
+  };
+}
+
 /**
  * Return the conventional root manifest paths present in `dir`, in
  * load-precedence order. Unlike {@link resolveManifestPath} this never throws —
@@ -274,6 +419,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     typeof pkg.name === 'string' && pkg.name.length > 0
       ? pkg.name
       : '(local integration)';
+  const packageProviderId = providerIdForPackage(pkg.name);
   const manifestFile = resolveManifestPath(packageDir, spec);
 
   let manifest;
@@ -299,6 +445,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
   } catch (err) {
     return {
       name: spec,
+      ...(packageProviderId == null ? {} : {providerId: packageProviderId}),
       version: pkg.version,
       __spec: spec,
       __packageDir: packageDir,
@@ -308,6 +455,8 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     };
   }
 
+  const providerId = providerIdForPackage(manifest.providerId ?? pkg.name);
+
   /** @param {string | null | undefined} value */
   const resolveRoot = value => {
     if (value == null) return undefined;
@@ -320,6 +469,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
 
   return {
     name: spec,
+    ...(providerId == null ? {} : {providerId}),
     version: pkg.version,
     components: resolveRoot(manifest.components),
     templates: resolveRoot(manifest.templates),
@@ -345,20 +495,22 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
  * Load configured integrations.
  *
  * @param {string[]} [specs] package names
- * @param {{cwd?: string, fresh?: boolean}} [options]
+ * @param {{cwd?: string, fresh?: boolean, resolveProviders?: boolean}} [options]
+ *   `resolveProviders: false` leaves provider identity to a caller that
+ *   resolves it once over a larger set (Project.load)
  * @returns {Promise<LoadedIntegration[]>}
  */
 export async function loadIntegrations(
   specs = [],
-  {cwd = process.cwd(), fresh = false} = {},
+  {cwd = process.cwd(), fresh = false, resolveProviders = true} = {},
 ) {
   /** @type {LoadedIntegration[]} */
   const integrations = [];
-  const seen = new Set();
+  const seenSpecs = new Set();
 
   for (const spec of specs) {
-    if (!spec || seen.has(spec)) continue;
-    seen.add(spec);
+    if (!spec || seenSpecs.has(spec)) continue;
+    seenSpecs.add(spec);
 
     const packageDir = resolvePackageDir(spec, cwd);
     const pkgPath = path.join(packageDir, 'package.json');
@@ -371,6 +523,7 @@ export async function loadIntegrations(
       );
     }
 
+    const packageProviderId = providerIdForPackage(pkg.name ?? spec);
     const manifestFile = resolveManifestPath(packageDir, spec);
     let manifest;
     /** @type {string[]} */
@@ -399,6 +552,7 @@ export async function loadIntegrations(
       // discovery loops naturally skip it (no components/templates/codemods).
       integrations.push({
         name: pkg.name ?? spec,
+        ...(packageProviderId == null ? {} : {providerId: packageProviderId}),
         version: pkg.version,
         __spec: spec,
         __packageDir: packageDir,
@@ -408,6 +562,10 @@ export async function loadIntegrations(
       continue;
     }
 
+    const providerId = providerIdForPackage(
+      manifest.providerId ?? pkg.name ?? spec,
+    );
+
     /** @param {string | null | undefined} value */
     const resolveRoot = value => {
       if (value == null) return undefined;
@@ -421,6 +579,7 @@ export async function loadIntegrations(
 
     integrations.push({
       name: pkg.name ?? spec,
+      ...(providerId == null ? {} : {providerId}),
       version: pkg.version,
       components: resolveRoot(manifest.components),
       templates: resolveRoot(manifest.templates),
@@ -441,5 +600,5 @@ export async function loadIntegrations(
     });
   }
 
-  return integrations;
+  return resolveProviders ? markProviderConflicts(integrations) : integrations;
 }