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

package/foundation/fs/file-protection.test.mjs

@@ -0,0 +1,250 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+  createFileProtectionResolver,
+  ProtectionSourceError,
+} from './file-protection.mjs';
+
+let root;
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-protection-'));
+});
+
+afterEach(() => {
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+function write(relative, contents = '') {
+  const file = path.join(root, relative);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, contents);
+  return file;
+}
+
+function declarations(relative) {
+  return createFileProtectionResolver(root)
+    .classify(path.join(root, relative))
+    .map(item => item.declaration);
+}
+
+describe('working-tree .gitattributes', () => {
+  it('honors nested later rules and explicit false or unset values', () => {
+    write(
+      '.gitattributes',
+      [
+        '*.css linguist-generated=true',
+        'vendor/** linguist-vendored',
+        'authored.css -linguist-generated',
+        'unset.css !linguist-generated',
+        '',
+      ].join('\n'),
+    );
+    write('generated.css', 'body {}');
+    write('authored.css', 'body {}');
+    write('unset.css', 'body {}');
+    write('nested/keep.css', 'body {}');
+    write('nested/.gitattributes', 'keep.css linguist-generated=false\n');
+    write('vendor/pkg/index.js', 'export {};');
+
+    expect(declarations('generated.css')).toContain(
+      'linguist-generated in .gitattributes:1',
+    );
+    expect(declarations('authored.css')).toEqual([]);
+    expect(declarations('unset.css')).toEqual([]);
+    expect(declarations('nested/keep.css')).toEqual([]);
+    expect(declarations('vendor/pkg/index.js')).toContain(
+      'linguist-vendored in .gitattributes:2',
+    );
+  });
+
+  it('expands top-level attribute macros, including forward definitions', () => {
+    write(
+      '.gitattributes',
+      'via-macro/** outer\n[attr]outer generated\n[attr]generated linguist-generated\n',
+    );
+    write('via-macro/output.js', 'export {};');
+    expect(declarations('via-macro/output.js')).toContain(
+      'linguist-generated in .gitattributes:1',
+    );
+  });
+
+  it('preserves escaped wildcards as literal path characters', () => {
+    write('.gitattributes', 'literal\\*.js linguist-generated\n');
+    write('literal*.js', 'export {};');
+    write('literalX.js', 'export {};');
+    expect(declarations('literal*.js')).toHaveLength(1);
+    expect(declarations('literalX.js')).toEqual([]);
+  });
+
+  it('supports quoted attribute patterns with spaces', () => {
+    write('.gitattributes', '"generated output/*.js" linguist-generated\n');
+    write('generated output/theme.js', 'export {};');
+    expect(declarations('generated output/theme.js')).toHaveLength(1);
+  });
+
+  it('matches basename patterns below the declaring directory', () => {
+    write('.gitattributes', '*.gen.ts linguist-generated\n');
+    write('src/deep/theme.gen.ts', 'export {};');
+    expect(declarations('src/deep/theme.gen.ts')).toHaveLength(1);
+  });
+});
+
+describe('working-tree ignore rules', () => {
+  it('honors gitignore negation and nested precedence', () => {
+    write('.gitignore', ['src/**/*.js', '!src/keep.js', ''].join('\n'));
+    write('src/drop.js', 'drop');
+    write('src/keep.js', 'keep');
+    write('src/deep/drop.js', 'drop');
+    write('src/.gitignore', '!deep/keep.js\n');
+    write('src/deep/keep.js', 'keep');
+
+    expect(declarations('src/drop.js')[0]).toBe('excluded by .gitignore');
+    expect(declarations('src/deep/drop.js')[0]).toBe('excluded by .gitignore');
+    expect(declarations('src/keep.js')).toEqual([]);
+    expect(declarations('src/deep/keep.js')).toEqual([]);
+  });
+
+  it('uses case-sensitive Git matching on case-sensitive platforms', () => {
+    write('.gitignore', 'FOO\n');
+    write('FOO', 'x');
+    write('foo', 'x');
+
+    expect(declarations('FOO')[0]).toBe('excluded by .gitignore');
+    expect(declarations('foo')).toEqual([]);
+  });
+
+  it('does not let a nested ignore file re-include beneath an excluded parent', () => {
+    write('.gitignore', 'ignored/\n');
+    write('ignored/.gitignore', '!keep.js\n');
+    write('ignored/keep.js', 'keep');
+
+    expect(declarations('ignored/keep.js')[0]).toBe('excluded by .gitignore');
+  });
+
+  it('ignores nested .hgignore files unless the root file includes them', () => {
+    write('sub/.hgignore', 'syntax: glob\n*.tmp\n');
+    write('sub/file.tmp', 'x');
+    expect(declarations('sub/file.tmp')).toEqual([]);
+  });
+
+  it('reads Mercurial glob and regexp syntax without a repository process', () => {
+    write(
+      '.hgignore',
+      ['syntax: glob', '**/*.generated.css', 're:^legacy/.+\\.js$', ''].join(
+        '\n',
+      ),
+    );
+    write('src/theme.generated.css', 'x');
+    write('legacy/file.js', 'x');
+    write('src/file.js', 'x');
+
+    expect(declarations('src/theme.generated.css')[0]).toMatch(/\.hgignore:2/);
+    expect(declarations('legacy/file.js')[0]).toMatch(/\.hgignore:3/);
+    expect(declarations('src/file.js')).toEqual([]);
+  });
+});
+
+describe('leading generated comments', () => {
+  it.each([
+    ['// @generated\nexport const x = 1;\n', '@generated'],
+    [
+      '/* @partially-generated */\nexport const x = 1;\n',
+      '@partially-generated',
+    ],
+    [
+      '// Code generated by Acme. DO NOT EDIT.\nconst x = 1;\n',
+      'Code generated',
+    ],
+    ['#!/usr/bin/env node\n// @generated\nconsole.log(1);\n', '@generated'],
+  ])('protects a recognized leading marker', (source, expected) => {
+    write('file.js', source);
+    expect(declarations('file.js')[0]).toContain(expected);
+  });
+
+  it('recognizes hash comments after a shebang in an extensionless file', () => {
+    write('script', '#!/bin/sh\n# @generated\necho hi\n');
+    expect(declarations('script')[0]).toContain('@generated');
+  });
+
+  it('does not treat a marker after authored code as protection', () => {
+    write('file.js', 'export const authored = true;\n// @generated\n');
+    expect(declarations('file.js')).toEqual([]);
+  });
+
+  it('does not accept longer generated-like annotations', () => {
+    write('file.js', '// @generated-code\nexport const authored = true;\n');
+    expect(declarations('file.js')).toEqual([]);
+  });
+
+  it('does not mistake a leading CSS id selector for a comment', () => {
+    write('file.css', '#root { color: red; }\n/* @generated */\n');
+    expect(declarations('file.css')).toEqual([]);
+  });
+
+  it('extracts an exact regeneration command from a generated header', () => {
+    const file = write(
+      'theme.css',
+      '/*\n * @generated\n * Command: pnpm astryx theme build src/theme.ts\n */\n',
+    );
+    const protection = createFileProtectionResolver(root).classify(file)[0];
+    expect(protection.command).toBe('pnpm astryx theme build src/theme.ts');
+  });
+});
+
+describe('hard boundaries and fail-closed parsing', () => {
+  it('protects dependency metadata, VCS metadata leaves, symlinks, and paths outside root', () => {
+    const dependency = write('node_modules/pkg/index.js', 'x');
+    const yarnDependency = write('.yarn/unplugged/pkg/index.js', 'x');
+    const yarnVirtual = write('.yarn/__virtual__/pkg/index.js', 'x');
+    const yarnInstallState = write('.yarn/install-state.gz', 'x');
+    const yarnPatch = write('.yarn/patches/pkg.patch', 'x');
+    const pnp = write('.pnp.cjs', 'x');
+    const pnpData = write('.pnp.data.json', '{}');
+    const metadata = write('.git', 'gitdir: elsewhere\n');
+    const target = write('target.js', 'x');
+    const link = path.join(root, 'link.js');
+    fs.symlinkSync(target, link);
+    const resolver = createFileProtectionResolver(root);
+
+    expect(resolver.classify(dependency)[0].reason).toBe('dependency');
+    expect(resolver.classify(yarnDependency)[0].reason).toBe('dependency');
+    expect(resolver.classify(yarnVirtual)[0].reason).toBe('dependency');
+    expect(resolver.classify(yarnInstallState)[0].reason).toBe('dependency');
+    expect(resolver.classify(yarnPatch)).toEqual([]);
+    expect(resolver.classify(pnp)[0].reason).toBe('dependency');
+    expect(resolver.classify(pnpData)[0].reason).toBe('dependency');
+    expect(resolver.classify(metadata)[0].reason).toBe('vcs');
+    expect(resolver.classify(link)[0].reason).toBe('symlink');
+    expect(
+      resolver.classify(path.join(root, '..', 'outside.js'))[0].reason,
+    ).toBe('outside-root');
+  });
+
+  it('rejects an .hgignore include reached through a symlink', () => {
+    const outside = path.join(
+      os.tmpdir(),
+      `astryx-ignore-${process.pid}-${Date.now()}`,
+    );
+    fs.writeFileSync(outside, 'syntax: glob\n*.generated\n');
+    try {
+      fs.symlinkSync(outside, path.join(root, 'rules'));
+      write('.hgignore', 'include:rules\n');
+      expect(() => createFileProtectionResolver(root)).toThrow(/symbolic link/);
+    } finally {
+      fs.rmSync(outside, {force: true});
+    }
+  });
+
+  it('fails before use when a protection source cannot be parsed', () => {
+    write('.hgignore', 'syntax: regexp\n[unterminated\n');
+    expect(() => createFileProtectionResolver(root)).toThrow(
+      ProtectionSourceError,
+    );
+    expect(() => createFileProtectionResolver(root)).toThrow(/\.hgignore/);
+  });
+});

package/foundation/integrations/autolink.d.mts

@@ -35,6 +35,28 @@ export function resolveInstalledPackageDir(name: string, fromDir: string): {
     packageDir: string;
     hostDir: string;
 } | null;
+/**
+ * @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 {AutolinkCandidate[]}
+ */
+export function scanAutolinkCandidates(projectDir: string, { exclude }?: {
+    exclude?: Iterable<string>;
+}): AutolinkCandidate[];
 /**
  * Declared dependencies that ship an integration manifest and are not already
  * loaded, in declaration order.
@@ -50,7 +72,7 @@ export function resolveInstalledPackageDir(name: string, fromDir: string): {
  *   directories already loaded (from config); matched through symlinks
  * @returns {Array<{spec: string, field: string, packageDir: string, hostDir: string}>}
  */
-export function findAutolinkCandidates(projectDir: string, { exclude }?: {
+export function findAutolinkCandidates(projectDir: string, options?: {
     exclude?: Iterable<string>;
 }): Array<{
     spec: string;
@@ -58,6 +80,24 @@ export function findAutolinkCandidates(projectDir: string, { exclude }?: {
     packageDir: string;
     hostDir: string;
 }>;
+/**
+ * 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 function loadAutolinkCandidates({ projectDir, loaded, fresh, }: {
+    projectDir: string;
+    loaded?: import("./integrations.mjs").LoadedIntegration[] | undefined;
+    fresh?: boolean | undefined;
+}): Promise<import("./provider-resolution.mjs").ProviderCandidate[]>;
 /**
  * Load every declared dependency that ships an integration manifest and is not
  * already loaded from config.
@@ -72,6 +112,12 @@ export function findAutolinkCandidates(projectDir: string, { 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]
@@ -94,3 +140,14 @@ export function autolinkIntegrations({ projectDir, loaded, fresh, }: {
  * @type {readonly string[]}
  */
 export const DEPENDENCY_FIELDS: readonly string[];
+export type AutolinkCandidate = {
+    spec: string;
+    field: string;
+    packageDir: string;
+    hostDir: string;
+    /**
+     * the directory is already loaded or already a
+     * candidate under another dependency key; it is not loaded again
+     */
+    repeat?: boolean | undefined;
+};

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,50 +338,26 @@ export async function autolinkIntegrations({
   loaded = [],
   fresh = false,
 }) {
-  const candidates = findAutolinkCandidates(projectDir, {
-    // A configured entry that never resolved to a directory has none to exclude.
-    exclude: loaded.flatMap(integration =>
-      typeof integration.__packageDir === 'string'
-        ? [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 = [];
-  // 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-identity pass in Project.load reports it instead of dropping it.
-  /** @param {{name: string, version?: string}} integration */
-  const identity = integration =>
-    `${integration.name}\u0000${integration.version ?? ''}`;
-  const seen = new Set(loaded.map(identity));
-
-  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 and version, so an alias and
-    // the package it aliases collapse here even when they are two directories
-    // on disk.
-    if (seen.has(identity(integration))) continue;
-    seen.add(identity(integration));
-    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,45 @@
+// @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 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: 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) 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";