@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/foundation/integrations/autolink.mjs

@@ -29,8 +29,9 @@
  *     package's own package.json `name` (see loadIntegrations), so an aliased
  *     dependency reports the package it actually is.
  *
- * An explicit config entry always wins: candidates already loaded from config
- * are dropped before anything here is imported.
+ * An explicit config entry always wins: a dependency whose directory is
+ * already loaded from config is never imported again, and comes back as a
+ * repeat so the provider ledger still records it.
  *
  * @position lib — sits between config/project (the caller) and
  *   integrations/integrations (the loader); contributes no discovery of its own.
@@ -39,6 +40,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {findManifestPaths, loadIntegrations} from './integrations.mjs';
+import {resolveProviders} from './provider-resolution.mjs';
 
 /**
  * package.json fields whose keys name a dependency this project installs.
@@ -164,36 +166,44 @@ function realPath(target) {
 }
 
 /**
- * Declared dependencies that ship an integration manifest and are not already
- * loaded, in declaration order.
- *
- * A candidate must have EXACTLY ONE root manifest. Zero is the ordinary case
- * (almost every dependency), and more than one is a packaging mistake the
- * loader treats as a hard error — an error the project did not ask for and
- * cannot fix, so an ambiguous package is passed over here rather than allowed
- * to fail the load of a project that merely depends on it.
+ * @typedef {object} AutolinkCandidate
+ * @property {string} spec
+ * @property {string} field
+ * @property {string} packageDir
+ * @property {string} hostDir
+ * @property {boolean} [repeat] the directory is already loaded or already a
+ *   candidate under another dependency key; it is not loaded again
+ */
+
+/**
+ * Every declared dependency that ships exactly one root manifest, in
+ * declaration order, including the ones whose directory is already loaded or
+ * already a candidate (`repeat`), so a caller can account for each of them.
  *
  * @param {string} projectDir directory holding the project's package.json
  * @param {{exclude?: Iterable<string>}} [options] `exclude` — package
  *   directories already loaded (from config); matched through symlinks
- * @returns {Array<{spec: string, field: string, packageDir: string, hostDir: string}>}
+ * @returns {AutolinkCandidate[]}
  */
-export function findAutolinkCandidates(projectDir, {exclude = []} = {}) {
+export function scanAutolinkCandidates(projectDir, {exclude = []} = {}) {
   const taken = new Set([...exclude].map(realPath));
-  /** @type {Array<{spec: string, field: string, packageDir: string, hostDir: string}>} */
+  /** @type {AutolinkCandidate[]} */
   const candidates = [];
 
   for (const {name, field} of readDeclaredDependencies(projectDir)) {
     const resolved = resolveInstalledPackageDir(name, projectDir);
     if (!resolved) continue;
 
+    if (findManifestPaths(resolved.packageDir).length !== 1) continue;
+
     // Two dependency keys can name one installed package — an npm alias beside
     // the package it aliases, or the two spellings of a package mid-rename
     // resolving through one store entry. Load it once.
     const identity = realPath(resolved.packageDir);
-    if (taken.has(identity)) continue;
-
-    if (findManifestPaths(resolved.packageDir).length !== 1) continue;
+    if (taken.has(identity)) {
+      candidates.push({spec: name, field, ...resolved, repeat: true});
+      continue;
+    }
 
     taken.add(identity);
     candidates.push({spec: name, field, ...resolved});
@@ -202,6 +212,100 @@ export function findAutolinkCandidates(projectDir, {exclude = []} = {}) {
   return candidates;
 }
 
+/**
+ * Declared dependencies that ship an integration manifest and are not already
+ * loaded, in declaration order.
+ *
+ * A candidate must have EXACTLY ONE root manifest. Zero is the ordinary case
+ * (almost every dependency), and more than one is a packaging mistake the
+ * loader treats as a hard error — an error the project did not ask for and
+ * cannot fix, so an ambiguous package is passed over here rather than allowed
+ * to fail the load of a project that merely depends on it.
+ *
+ * @param {string} projectDir directory holding the project's package.json
+ * @param {{exclude?: Iterable<string>}} [options] `exclude` — package
+ *   directories already loaded (from config); matched through symlinks
+ * @returns {Array<{spec: string, field: string, packageDir: string, hostDir: string}>}
+ */
+export function findAutolinkCandidates(projectDir, options) {
+  return scanAutolinkCandidates(projectDir, options)
+    .filter(candidate => !candidate.repeat)
+    .map(({spec, field, packageDir, hostDir}) => ({
+      spec,
+      field,
+      packageDir,
+      hostDir,
+    }));
+}
+
+/**
+ * Load every autolink candidate, each in isolation, as provider candidates for
+ * {@link resolveProviders}. Nothing is filtered here: a candidate whose load
+ * throws or whose manifest fails comes back with its error, and a repeated
+ * directory comes back unloaded, so the resolver records each one.
+ *
+ * @param {object} options
+ * @param {string} options.projectDir directory holding the project's package.json
+ * @param {import('./integrations.mjs').LoadedIntegration[]} [options.loaded]
+ *   integrations already loaded from config
+ * @param {boolean} [options.fresh]
+ * @returns {Promise<import('./provider-resolution.mjs').ProviderCandidate[]>}
+ */
+export async function loadAutolinkCandidates({
+  projectDir,
+  loaded = [],
+  fresh = false,
+}) {
+  const scanned = scanAutolinkCandidates(projectDir, {
+    // A configured entry that never resolved to a directory has none to exclude.
+    exclude: loaded.flatMap(integration =>
+      typeof integration.__packageDir === 'string'
+        ? [integration.__packageDir]
+        : [],
+    ),
+  });
+
+  /** @type {import('./provider-resolution.mjs').ProviderCandidate[]} */
+  const candidates = [];
+  for (const candidate of scanned) {
+    const {spec, packageDir} = candidate;
+    if (candidate.repeat) {
+      candidates.push({source: 'autolinked', spec, packageDir, repeat: true});
+      continue;
+    }
+    try {
+      // Resolve from the directory whose node_modules actually holds the
+      // package, so a hoisted dependency resolves the same way Node found it.
+      const [integration] = await loadIntegrations([spec], {
+        cwd: candidate.hostDir,
+        fresh,
+      });
+      candidates.push({
+        source: 'autolinked',
+        spec,
+        packageDir,
+        ...(integration == null
+          ? {}
+          : {
+              integration: {
+                ...integration,
+                __autolinked: true,
+                __dependencyField: candidate.field,
+              },
+            }),
+      });
+    } catch (error) {
+      candidates.push({
+        source: 'autolinked',
+        spec,
+        packageDir,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  return candidates;
+}
+
 /**
  * Load every declared dependency that ships an integration manifest and is not
  * already loaded from config.
@@ -216,6 +320,12 @@ export function findAutolinkCandidates(projectDir, {exclude = []} = {}) {
  * consuming project can neither fix nor silence, and which
  * `astryx doctor integration validate <package>` reports on demand.
  *
+ * One package reached twice (an alias beside the package it aliases, at the
+ * same version) loads once. The same name at another version is kept, so the
+ * provider pass reports it instead of dropping it. Project.load does not call
+ * this; it hands {@link loadAutolinkCandidates} to the resolver, whose ledger
+ * records every candidate dropped here.
+ *
  * @param {object} options
  * @param {string} options.projectDir directory holding the project's package.json
  * @param {import('./integrations.mjs').LoadedIntegration[]} [options.loaded]
@@ -228,38 +338,26 @@ export async function autolinkIntegrations({
   loaded = [],
   fresh = false,
 }) {
-  const candidates = findAutolinkCandidates(projectDir, {
-    exclude: loaded.map(integration => integration.__packageDir),
-  });
-
+  const candidates = await loadAutolinkCandidates({projectDir, loaded, fresh});
+  const {ledger} = resolveProviders([
+    ...loaded.map(integration => ({
+      source: /** @type {const} */ ('configured'),
+      integration,
+      spec: integration.__spec,
+    })),
+    ...candidates,
+  ]);
   /** @type {import('./integrations.mjs').LoadedIntegration[]} */
   const autolinked = [];
-  const names = new Set(loaded.map(integration => integration.name));
-
-  for (const candidate of candidates) {
-    /** @type {import('./integrations.mjs').LoadedIntegration|undefined} */
-    let integration;
-    try {
-      // Resolve from the directory whose node_modules actually holds the
-      // package, so a hoisted dependency resolves the same way Node found it.
-      [integration] = await loadIntegrations([candidate.spec], {
-        cwd: candidate.hostDir,
-        fresh,
-      });
-    } catch {
-      continue;
+  for (const entry of ledger.values()) {
+    const {candidate} = entry;
+    if (
+      candidate.source === 'autolinked' &&
+      candidate.integration != null &&
+      (entry.outcome === 'contributes' || entry.outcome === 'set-aside')
+    ) {
+      autolinked.push(candidate.integration);
     }
-    if (!integration || integration.__loadError) continue;
-    // Identity is the resolved package's own name, so an alias and the package
-    // it aliases collapse here even when they are two directories on disk.
-    if (names.has(integration.name)) continue;
-    names.add(integration.name);
-    autolinked.push({
-      ...integration,
-      __autolinked: true,
-      __dependencyField: candidate.field,
-    });
   }
-
   return autolinked;
 }

package/foundation/integrations/autolink.test.mjs

@@ -87,7 +87,7 @@ function installPackage(
     fs.mkdirSync(componentsDir, {recursive: true});
     fs.writeFileSync(
       path.join(componentsDir, `${componentName}.doc.mjs`),
-      `export const docs = {name: '${componentName}', usage: {description: 'A widget'}};\n`,
+      `export default {type: 'component', name: '${componentName}', usage: {description: 'A widget'}, props: []};\n`,
     );
     fs.writeFileSync(
       path.join(componentsDir, `${componentName}.tsx`),

package/foundation/integrations/cli-requirement.d.mts

@@ -0,0 +1,65 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The lowest version a semver range admits: the least of its `||`
+ * alternatives. Null when an alternative has no lower bound, or the range is
+ * not one this can read, so the caller treats it as admitting every version.
+ * @param {unknown} range
+ * @returns {string | null}
+ */
+export function lowestAdmitted(range: unknown): string | null;
+/**
+ * Why a package that ships a namespace doc or a placed guide would lose its
+ * docs on an older CLI, or null when its declared CLI range admits only CLIs
+ * that read the docs tree. Published 0.6.3 hides every topic of a package
+ * with a namespace doc; builds of main before the docs tree also do so for a
+ * placed guide.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function docsTreeCliProblem(pkg: any): string | null;
+/**
+ * Why a package with a template that sets `replaces` would lose templates and
+ * doc topics on an older CLI (spec:AST-035), or null when its declared CLI
+ * range admits only CLIs that read the field.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function replacesCliProblem(pkg: any): string | null;
+/**
+ * Why a package with a doc section that sets `id` would lose its doc topics on
+ * an older CLI, or null when its declared CLI range admits only CLIs that read
+ * the field. Published 0.6.3 rejects a section `id` and hides every doc topic
+ * the package ships.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function sectionIdsCliProblem(pkg: any): string | null;
+/**
+ * Why a package that ships a theme would lose its themes and doc topics on an
+ * older CLI, or null when its declared CLI range admits only CLIs that read
+ * typed theme descriptors. Published 0.6.3 rejects a themes root with no
+ * `manifest.json` catalog, which `integration add theme` no longer writes.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function themesCliProblem(pkg: any): string | null;
+/**
+ * The package.json with a CLI peer that reads namespace docs: optional, unless
+ * the package already says otherwise.
+ * @param {any} pkg package.json
+ * @returns {any}
+ */
+export function withDocsTreeCli(pkg: any): any;
+export const CLI_PACKAGE: "@astryxdesign/cli";
+/**
+ * The first CLI release that reads an integration's docs tree (namespace docs
+ * and placed guides), its templates' `replaces`, and its typed theme
+ * descriptors. A release before it can hide every doc topic a package with a
+ * namespace doc or a placed guide ships, with no warning; it rejects
+ * `replaces`, drops that template, and hides the package's doc topics; and it
+ * rejects a themes root without the `manifest.json` catalog the CLI no longer
+ * writes, withholding the package's themes and doc topics.
+ */
+export const DOCS_TREE_CLI: "0.7.0";

package/foundation/integrations/cli-requirement.mjs

@@ -0,0 +1,189 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The CLI an integration's namespace docs need (spec:AST-046 FR11).
+ *
+ * @input A package.json object.
+ * @output Whether its `peerDependencies` range for `@astryxdesign/cli` admits
+ *   only CLIs that read namespace docs, and the package.json that declares it.
+ * @position foundation/integrations; read by `integration add doc --parent`
+ *   and `integration add theme`, which declare the peer, and
+ *   `integration verify`, which requires it.
+ */
+
+import {semverCompare} from '../env/semver.mjs';
+
+export const CLI_PACKAGE = '@astryxdesign/cli';
+
+/**
+ * The first CLI release that reads an integration's docs tree (namespace docs
+ * and placed guides), its templates' `replaces`, and its typed theme
+ * descriptors. A release before it can hide every doc topic a package with a
+ * namespace doc or a placed guide ships, with no warning; it rejects
+ * `replaces`, drops that template, and hides the package's doc topics; and it
+ * rejects a themes root without the `manifest.json` catalog the CLI no longer
+ * writes, withholding the package's themes and doc topics.
+ */
+export const DOCS_TREE_CLI = '0.7.0';
+
+const VERSION_RE = /^v?(\d+|[xX*])(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/**
+ * A version or partial version as MAJOR.MINOR.PATCH, a wildcard part as 0.
+ * @param {string} text
+ * @returns {string | null}
+ */
+function lowerVersion(text) {
+  const m = VERSION_RE.exec(text.trim());
+  if (!m) return null;
+  return [m[1], m[2], m[3]]
+    .map(part => (part == null || /^[xX*]$/.test(part) ? '0' : part))
+    .join('.');
+}
+
+/**
+ * The lowest version one space-joined comparator set admits, or null when it
+ * has no lower bound this can read.
+ * @param {string} set
+ * @returns {string | null}
+ */
+function lowestOfSet(set) {
+  if (set === '' || set === '*' || /^[xX]$/.test(set)) return null;
+  const hyphen = /^(\S+)\s+-\s+\S+$/.exec(set);
+  if (hyphen) return lowerVersion(hyphen[1]);
+  /** @type {string | null} */
+  let lowest = null;
+  for (const comparator of set.split(/\s+/)) {
+    const m = /^(>=|<=|>|<|=|\^|~)?(.+)$/.exec(comparator);
+    if (!m) return null;
+    if (m[1] === '<' || m[1] === '<=') continue;
+    const version = lowerVersion(m[2]);
+    if (version == null) return null;
+    if (lowest == null || semverCompare(version, lowest) > 0) lowest = version;
+  }
+  return lowest;
+}
+
+/**
+ * The lowest version a semver range admits: the least of its `||`
+ * alternatives. Null when an alternative has no lower bound, or the range is
+ * not one this can read, so the caller treats it as admitting every version.
+ * @param {unknown} range
+ * @returns {string | null}
+ */
+export function lowestAdmitted(range) {
+  if (typeof range !== 'string') return null;
+  /** @type {string | null} */
+  let lowest = null;
+  for (const alternative of range.split('||')) {
+    const low = lowestOfSet(alternative.trim());
+    if (low == null) return null;
+    if (lowest == null || semverCompare(low, lowest) < 0) lowest = low;
+  }
+  return lowest;
+}
+
+/**
+ * Why a package that uses a feature an older CLI cannot read would lose it,
+ * or null when its declared CLI range admits only CLIs that read it.
+ * @param {any} pkg package.json
+ * @param {string} feature what the package does, e.g. "ships a namespace doc"
+ * @param {string} loss what an older CLI does with it
+ * @returns {string | null}
+ */
+function cliRangeProblem(pkg, feature, loss) {
+  const range = pkg?.peerDependencies?.[CLI_PACKAGE];
+  const fix = `"${CLI_PACKAGE}": ">=${DOCS_TREE_CLI}" in peerDependencies (optional in peerDependenciesMeta, if the CLI is not required)`;
+  if (typeof range !== 'string') {
+    return `The package ${feature} but declares no ${CLI_PACKAGE} peer. A stable CLI before ${DOCS_TREE_CLI} ${loss}. Declare ${fix}.`;
+  }
+  const lowest = lowestAdmitted(range);
+  if (lowest == null || semverCompare(lowest, DOCS_TREE_CLI) < 0) {
+    return `The package ${feature}, but its ${CLI_PACKAGE} peer range "${range}" admits a stable CLI before ${DOCS_TREE_CLI}, which ${loss}. Declare ${fix}.`;
+  }
+  return null;
+}
+
+/**
+ * Why a package that ships a namespace doc or a placed guide would lose its
+ * docs on an older CLI, or null when its declared CLI range admits only CLIs
+ * that read the docs tree. Published 0.6.3 hides every topic of a package
+ * with a namespace doc; builds of main before the docs tree also do so for a
+ * placed guide.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function docsTreeCliProblem(pkg) {
+  return cliRangeProblem(
+    pkg,
+    'ships a namespace doc or a placed guide',
+    'does not read the docs tree, and can hide every doc topic the package ships',
+  );
+}
+
+/**
+ * Why a package with a template that sets `replaces` would lose templates and
+ * doc topics on an older CLI (spec:AST-035), or null when its declared CLI
+ * range admits only CLIs that read the field.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function replacesCliProblem(pkg) {
+  return cliRangeProblem(
+    pkg,
+    'has a template that sets `replaces`',
+    "rejects the field, drops that template, and hides the package's doc topics",
+  );
+}
+
+/**
+ * Why a package with a doc section that sets `id` would lose its doc topics on
+ * an older CLI, or null when its declared CLI range admits only CLIs that read
+ * the field. Published 0.6.3 rejects a section `id` and hides every doc topic
+ * the package ships.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function sectionIdsCliProblem(pkg) {
+  return cliRangeProblem(
+    pkg,
+    'has a doc section that sets `id`',
+    'rejects the field, and can hide every doc topic the package ships',
+  );
+}
+
+/**
+ * Why a package that ships a theme would lose its themes and doc topics on an
+ * older CLI, or null when its declared CLI range admits only CLIs that read
+ * typed theme descriptors. Published 0.6.3 rejects a themes root with no
+ * `manifest.json` catalog, which `integration add theme` no longer writes.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function themesCliProblem(pkg) {
+  return cliRangeProblem(
+    pkg,
+    'ships a theme',
+    "cannot read typed theme descriptors, and can drop the package's themes and hide its doc topics",
+  );
+}
+
+/**
+ * The package.json with a CLI peer that reads namespace docs: optional, unless
+ * the package already says otherwise.
+ * @param {any} pkg package.json
+ * @returns {any}
+ */
+export function withDocsTreeCli(pkg) {
+  const meta = pkg.peerDependenciesMeta ?? {};
+  return {
+    ...pkg,
+    peerDependencies: {
+      ...(pkg.peerDependencies ?? {}),
+      [CLI_PACKAGE]: `>=${DOCS_TREE_CLI}`,
+    },
+    peerDependenciesMeta: meta[CLI_PACKAGE]
+      ? meta
+      : {...meta, [CLI_PACKAGE]: {optional: true}},
+  };
+}

package/foundation/integrations/cli-requirement.test.mjs

@@ -0,0 +1,89 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {
+  DOCS_TREE_CLI,
+  lowestAdmitted,
+  docsTreeCliProblem,
+  replacesCliProblem,
+  withDocsTreeCli,
+} from './cli-requirement.mjs';
+
+describe('lowestAdmitted', () => {
+  it.each([
+    ['>=0.7.0', '0.7.0'],
+    ['^0.6.0', '0.6.0'],
+    ['~0.7.1', '0.7.1'],
+    ['0.7.x', '0.7.0'],
+    ['>=0.7.0 <0.8.0', '0.7.0'],
+    ['^0.6.0 || >=0.7.0', '0.6.0'],
+    ['0.8.0 - 0.9.0', '0.8.0'],
+    ['*', null],
+    ['<1.0.0', null],
+    ['latest', null],
+    ['workspace:*', null],
+  ])('%s admits %s at the lowest', (range, lowest) => {
+    expect(lowestAdmitted(range)).toBe(lowest);
+  });
+});
+
+describe('docsTreeCliProblem', () => {
+  it('asks for a CLI peer when there is none', () => {
+    expect(docsTreeCliProblem({name: '@acme/kit'})).toContain(
+      'declares no @astryxdesign/cli peer',
+    );
+    // Stable releases: a canary built from main before its release reports
+    // the older version and reads every feature.
+    expect(docsTreeCliProblem({name: '@acme/kit'})).toContain(
+      'A stable CLI before 0.7.0 does not read the docs tree',
+    );
+  });
+
+  it.each(['^0.6.0', '^0.6.0 || >=0.7.0', '*', '>=0.6.3'])(
+    'refuses %s, which admits a CLI that cannot read a namespace doc',
+    range => {
+      expect(
+        docsTreeCliProblem({peerDependencies: {'@astryxdesign/cli': range}}),
+      ).toContain('admits a stable CLI before');
+    },
+  );
+
+  it.each(['>=0.7.0', '^0.7.2', '>=0.7.0 <2'])('accepts %s', range => {
+    expect(
+      docsTreeCliProblem({peerDependencies: {'@astryxdesign/cli': range}}),
+    ).toBeNull();
+  });
+
+  it('declares the peer as optional, and keeps what the package says of it', () => {
+    const declared = withDocsTreeCli({name: '@acme/kit'});
+    expect(declared.peerDependencies).toEqual({
+      '@astryxdesign/cli': `>=${DOCS_TREE_CLI}`,
+    });
+    expect(declared.peerDependenciesMeta).toEqual({
+      '@astryxdesign/cli': {optional: true},
+    });
+    expect(docsTreeCliProblem(declared)).toBeNull();
+    const required = withDocsTreeCli({
+      peerDependencies: {react: '^19.0.0', '@astryxdesign/cli': '^0.6.0'},
+      peerDependenciesMeta: {'@astryxdesign/cli': {optional: false}},
+    });
+    expect(required.peerDependencies.react).toBe('^19.0.0');
+    expect(required.peerDependenciesMeta['@astryxdesign/cli']).toEqual({
+      optional: false,
+    });
+  });
+});
+
+describe('replacesCliProblem', () => {
+  it('asks a package that sets replaces for a CLI that reads the field', () => {
+    expect(replacesCliProblem({name: '@acme/kit'})).toContain(
+      'sets `replaces`',
+    );
+    expect(
+      replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '^0.6.0'}}),
+    ).toContain('admits a stable CLI before');
+    expect(
+      replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '>=0.7.0'}}),
+    ).toBeNull();
+  });
+});