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

package/foundation/integrations/cli-requirement.mjs

@@ -0,0 +1,154 @@
+// 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`,
+ *   which declares the peer, and `integration pack --check`, 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) and its templates' `replaces`. A release before it can
+ * hide every doc topic a package with a namespace doc or a placed guide
+ * ships, with no warning, and it rejects `replaces` and withholds the
+ * package's templates 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 CLI older than ${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 CLI older than ${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 its 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, and withholds the package's templates and 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,84 @@
+// 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',
+    );
+  });
+
+  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 CLI older than');
+    },
+  );
+
+  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 CLI older than');
+    expect(
+      replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '>=0.7.0'}}),
+    ).toBeNull();
+  });
+});

package/foundation/integrations/contribution-fixes.d.mts

@@ -0,0 +1,145 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Identify contribution metadata without importing it. Doctor scans files that
+ * the manifest does not declare, so executing those files would run code the
+ * package never asked Astryx to load.
+ *
+ * @param {string} file
+ * @param {boolean} templateOnly
+ * @returns {ContributionStamp | null} null when it is not contribution metadata
+ */
+export function readContributionStamp(file: string, templateOnly: boolean): ContributionStamp | null;
+/** @param {string} candidate @param {string} root */
+export function pathIsInside(candidate: string, root: string): boolean;
+/**
+ * @param {string} packageDir
+ * @param {{components?: string, templates?: string, codemods?: string, docs?: string, themes?: string, __manifestFile?: string}} integration
+ * @returns {FixContext}
+ */
+export function createFixContext(packageDir: string, integration: {
+    components?: string;
+    templates?: string;
+    codemods?: string;
+    docs?: string;
+    themes?: string;
+    __manifestFile?: string;
+}): FixContext;
+/**
+ * The static stamp of a candidate metadata file, read once per context.
+ * @param {FixContext} context
+ * @param {string} file
+ * @returns {ContributionStamp | null}
+ */
+export function stampOf(context: FixContext, file: string): ContributionStamp | null;
+/**
+ * The fix for every codemods entry when the codemods root also holds the rest
+ * of the package: it is the package root, or it holds another root. No
+ * per-entry move or rename helps then.
+ * @param {FixContext} context
+ * @param {string} [stray] a stray file's name, which may itself be a codemod
+ * @returns {string | null}
+ */
+export function sharedCodemodsRootFix(context: FixContext, stray?: string): string | null;
+/**
+ * The fix for a codemods folder that holds another root, which a rename would
+ * break.
+ * @param {FixContext} context
+ * @param {string} folder
+ * @returns {string | null}
+ */
+export function heldRootFix(context: FixContext, folder: string): string | null;
+/**
+ * The fix for contribution metadata that sits outside every declared root.
+ * @param {FixContext} context
+ * @param {string} file
+ * @param {ContributionStamp} stamp
+ * @returns {string}
+ */
+export function unreachableFix(context: FixContext, file: string, stamp: ContributionStamp): string;
+/**
+ * The step a component doc added to the components root also needs when
+ * another root reads that folder too, and would read the new doc as its own.
+ * @param {FixContext} context
+ * @returns {string} a sentence with a leading space, or ''
+ */
+export function newComponentDocNote(context: FixContext): string;
+/**
+ * The theme beside \`file\` whose source imports it, if any: such a file is
+ * part of that theme, not a codemod.
+ * @param {FixContext} context
+ * @param {string} file
+ * @returns {{doc: string, stamp: ContributionStamp, source: string} | null}
+ */
+export function themeImporting(context: FixContext, file: string): {
+    doc: string;
+    stamp: ContributionStamp;
+    source: string;
+} | null;
+/**
+ * The fix for contribution metadata at the top of the codemods root, which
+ * the codemod checks read as a stray codemod. `source` names that doc's theme
+ * source when the stray file is the source rather than the doc.
+ * @param {FixContext} context
+ * @param {string} file the metadata doc
+ * @param {ContributionStamp} stamp
+ * @param {string} [source]
+ * @param {string} [stray] a file that source imports, when the stray file is
+ *   that one
+ * @returns {string}
+ */
+export function notACodemodFix(context: FixContext, file: string, stamp: ContributionStamp, source?: string, stray?: string): string;
+/**
+ * The fix for a doc that the components root reads although its type says it
+ * is another kind of metadata.
+ * @param {FixContext} context
+ * @param {string} file
+ * @param {ContributionStamp} stamp a stamp whose type is not `component`
+ * @returns {string}
+ */
+export function notAComponentFix(context: FixContext, file: string, stamp: ContributionStamp): string;
+/** @typedef {'components' | 'templates' | 'docs' | 'themes'} MetadataRoot */
+/**
+ * @typedef {object} ContributionStamp
+ * @property {string} type
+ * @property {string | null} name the static `name`, when it has one
+ */
+/**
+ * @typedef {object} FixContext
+ * @property {string} packageDir
+ * @property {string} manifest file name of the package's manifest
+ * @property {Partial<Record<MetadataRoot | 'codemods', string>>} roots
+ *   declared roots, absolute
+ * @property {Map<string, ContributionStamp | null>} stamps
+ * @property {Map<string, string[] | null>} candidates
+ */
+export const DOC_CANDIDATE_RE: RegExp;
+export const TEMPLATE_CANDIDATE_RE: RegExp;
+/** Stray-codemod and version-folder rules, shared with the codemod checks. */
+export const CODEMOD_FILE_RE: RegExp;
+export const CODEMOD_TEST_RE: RegExp;
+export const CODEMOD_SKIP_DIRS: Set<string>;
+/** The manifest root that reads each kind of contribution metadata. */
+export const ROOT_FOR_TYPE: Record<string, MetadataRoot>;
+export type MetadataRoot = "components" | "templates" | "docs" | "themes";
+export type ContributionStamp = {
+    type: string;
+    /**
+     * the static `name`, when it has one
+     */
+    name: string | null;
+};
+export type FixContext = {
+    packageDir: string;
+    /**
+     * file name of the package's manifest
+     */
+    manifest: string;
+    /**
+     *   declared roots, absolute
+     */
+    roots: Partial<Record<MetadataRoot | "codemods", string>>;
+    stamps: Map<string, ContributionStamp | null>;
+    candidates: Map<string, string[] | null>;
+};