@astryxdesign/cli 0.7.2 → 0.7.3-canary.06872b4

package/foundation/integrations/computer-integrations.mjs

@@ -225,12 +225,19 @@ export function peerProblem(pkg, release) {
 
 /**
  * The computer-level integrations installed beside the CLI at `cliRoot`, in
- * name order (declaration order when the root declares them). Reads
+ * name order (declaration order when the root declares them), then each
+ * integration a host approves (`approved`, architecture:cli-surface INV30),
+ * resolved by name from the package set that holds that CLI alone. Reads
  * package.json files only.
- * @param {{cliRoot: string, release: string, cacheDir?: string}} options
+ * @param {{cliRoot: string, release: string, cacheDir?: string, approved?: readonly string[]}} options
  * @returns {ComputerIntegrationCandidate[]}
  */
-export function scanComputerIntegrations({cliRoot, release, cacheDir}) {
+export function scanComputerIntegrations({
+  cliRoot,
+  release,
+  cacheDir,
+  approved = [],
+}) {
   const self = real(cliRoot);
   /** @type {ComputerIntegrationCandidate[]} */
   const found = [];
@@ -238,21 +245,43 @@ export function scanComputerIntegrations({cliRoot, release, cacheDir}) {
   for (const root of computerInstallRoots(cliRoot, {cacheDir})) {
     scanRoot(root, {self, release, found, seen});
   }
+  const owner = approved.length > 0 ? installPlaceOf(self).owner : null;
+  if (owner) scanRoot(owner, {self, release, found, seen}, approved);
   return found;
 }
 
 /**
- * Add the integrations installed in one install root.
+ * `name` as installed in `root`'s own `node_modules`, never in a folder above.
+ * @param {string} name
+ * @param {string} root
+ * @returns {{packageDir: string, hostDir: string} | null}
+ */
+function ownPackageDir(name, root) {
+  const packageDir = path.join(root, 'node_modules', ...name.split('/'));
+  return fs.existsSync(path.join(packageDir, 'package.json'))
+    ? {packageDir, hostDir: root}
+    : null;
+}
+
+/**
+ * Add the integrations installed in one install root: those it declares or
+ * installs, or, given `approved`, those names installed in its own
+ * `node_modules`.
  * @param {string} root
  * @param {{self: string, release: string, found: ComputerIntegrationCandidate[], seen: Set<string>}} into
+ * @param {readonly string[] | null} [approved]
  */
-function scanRoot(root, {self, release, found, seen}) {
-  const declared = readPackage(root)
-    ? readDeclaredDependencies(root).map(d => d.name)
-    : installedNames(root);
+function scanRoot(root, {self, release, found, seen}, approved = null) {
+  const declared =
+    approved ??
+    (readPackage(root)
+      ? readDeclaredDependencies(root).map(d => d.name)
+      : installedNames(root));
   for (const name of declared) {
     if (NOT_INTEGRATIONS.has(name)) continue;
-    const resolved = resolveInstalledPackageDir(name, root);
+    const resolved = approved
+      ? ownPackageDir(name, root)
+      : resolveInstalledPackageDir(name, root);
     if (!resolved) continue;
     const identity = real(resolved.packageDir);
     if (identity === self || seen.has(identity)) continue;

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

@@ -1,6 +1,21 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * The contribution files readers read under each declared root that is a
+ * readable folder, package-relative, without importing anything. A folder
+ * inside a root that cannot be listed is skipped.
+ * @param {{components?: string, templates?: string, codemods?: string, docs?: string, themes?: string}} loaded
+ * @param {string} pkgDir
+ * @returns {string[]}
+ */
+export function contributionFiles(loaded: {
+    components?: string;
+    templates?: string;
+    codemods?: string;
+    docs?: string;
+    themes?: string;
+}, pkgDir: string): string[];
 /**
  * @typedef {object} FileInventoryRoot
  * @property {'themes'|'components'|'templates'|'codemods'|'docs'} kind
@@ -22,26 +37,6 @@
  * @returns {FileInventory}
  */
 export function computeRequiredFiles(loaded: import("./integrations.mjs").LoadedIntegration): FileInventory;
-/**
- * @typedef {object} ContributionIdentities
- * @property {{slug: string, exportName: string}[]} themes
- * @property {string[]} components
- * @property {{id: string, type: string, name: string, replaces?: string}[]} templates
- * @property {{version: string, id: string}[]} codemods
- * @property {string[]} docs
- * @property {string[]} agentDocsAppend
- */
-/**
- * The resolved fields needed to discover contribution identities.
- * @typedef {object} IdentitySource
- * @property {string} name
- * @property {string} [themes]
- * @property {string} [components]
- * @property {string} [templates]
- * @property {string} [codemods]
- * @property {string} [docs]
- * @property {{append?: readonly string[]}} [agentDocs]
- */
 /**
  * Run the same discovery functions a consumer uses to collect every
  * contribution identity from a loaded integration.

package/foundation/integrations/contribution-inventory.mjs

@@ -137,6 +137,29 @@ const ROOT_KINDS = /** @type {const} */ ([
   'docs',
 ]);
 
+/**
+ * The contribution files readers read under each declared root that is a
+ * readable folder, package-relative, without importing anything. A folder
+ * inside a root that cannot be listed is skipped.
+ * @param {{components?: string, templates?: string, codemods?: string, docs?: string, themes?: string}} loaded
+ * @param {string} pkgDir
+ * @returns {string[]}
+ */
+export function contributionFiles(loaded, pkgDir) {
+  /** @type {Set<string>} */
+  const files = new Set();
+  for (const kind of ROOT_KINDS) {
+    const root = loaded[kind];
+    if (!root || !isFolder(root)) continue;
+    try {
+      for (const file of ENUMERATORS[kind](root, pkgDir)) files.add(file);
+    } catch {
+      // An unreadable folder inside the root.
+    }
+  }
+  return [...files].sort();
+}
+
 // ── Public: static file inventory ────────────────────────────────
 
 /**
@@ -207,6 +230,19 @@ export function computeRequiredFiles(loaded) {
  * @property {{append?: readonly string[]}} [agentDocs]
  */
 
+/**
+ * Whether `dir` is a folder to list. A declared root that is a file is
+ * reported by the root check; discovery finds nothing in it.
+ * @param {string} dir
+ */
+function isFolder(dir) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Run the same discovery functions a consumer uses to collect every
  * contribution identity from a loaded integration.
@@ -229,7 +265,7 @@ export async function collectIdentities(loaded) {
   /** @type {Array<{kind: string, message: string}>} */
   const errors = [];
 
-  if (loaded.themes && fs.existsSync(loaded.themes)) {
+  if (loaded.themes && isFolder(loaded.themes)) {
     try {
       const themes = await discoverIntegrationThemes(
         /** @type {import('./integrations.mjs').LoadedIntegration} */ (loaded),
@@ -245,7 +281,7 @@ export async function collectIdentities(loaded) {
     }
   }
 
-  if (loaded.components && fs.existsSync(loaded.components)) {
+  if (loaded.components && isFolder(loaded.components)) {
     try {
       const records = discoverIntegrationComponents(loaded) ?? [];
       // A family doc backs several records: load it, and report it, once.
@@ -275,7 +311,7 @@ export async function collectIdentities(loaded) {
     }
   }
 
-  if (loaded.templates && fs.existsSync(loaded.templates)) {
+  if (loaded.templates && isFolder(loaded.templates)) {
     try {
       const {templates, errors: templateErrors} =
         await discoverIntegrationTemplatesForOne(loaded);
@@ -298,7 +334,7 @@ export async function collectIdentities(loaded) {
     }
   }
 
-  if (loaded.codemods && fs.existsSync(loaded.codemods)) {
+  if (loaded.codemods && isFolder(loaded.codemods)) {
     try {
       const byVersion = await discoverIntegrationCodemods([loaded]);
       /** @type {{version: string, id: string}[]} */
@@ -317,7 +353,7 @@ export async function collectIdentities(loaded) {
     }
   }
 
-  if (loaded.docs && fs.existsSync(loaded.docs)) {
+  if (loaded.docs && isFolder(loaded.docs)) {
     try {
       const {
         records,

package/foundation/integrations/integrations.d.mts

@@ -45,13 +45,14 @@ export function findManifestPaths(dir: string): string[];
  * @param {string} file absolute manifest path
  * @param {string} [label] used in error messages
  * @param {{fresh?: boolean}} [options]
- * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string, cliCommandError?: string}>}
+ * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], declaredKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string, cliCommandError?: string}>}
  */
 export function loadManifest(file: string, label?: string, { fresh }?: {
     fresh?: boolean;
 }): Promise<{
     manifest: import("../../authoring/integration/type").AstryxIntegration;
     unknownKeys: string[];
+    declaredKeys: string[];
     debug?: import("../../authoring/debug/type").DebugEventHandler;
     gapReport?: import("../../authoring/gap-report/type").GapReportHandler;
     gapReportError?: string;
@@ -79,6 +80,17 @@ export function loadManifestObject(file: string, label?: string, options?: {
  * @param {string} [cwd]
  */
 export function resolvePackageDir(packageName: string, cwd?: string): string;
+/**
+ * Where an integration named in astryx.config is installed: the nearest
+ * `node_modules/<name>` at or above `cwd`, found the way an autolinked
+ * dependency is, so a package a workspace hoists to its root loads in every
+ * member. When it is installed nowhere, `cwd`'s own `node_modules/<name>`,
+ * which the caller reports as not installed.
+ * @param {string} packageName
+ * @param {string} [cwd]
+ * @returns {string}
+ */
+export function resolveInstalledIntegrationDir(packageName: string, cwd?: string): string;
 /**
  * Load the integration package rooted at `packageDir` directly, without first
  * installing or publishing it. This is the self-resolution seam: an author in
@@ -134,6 +146,8 @@ export function loadIntegrations(specs?: string[], { cwd, fresh, resolveProvider
  * @property {string} [__agentDocsError] contribution-specific validation
  *   failure; other manifest contributions remain available
  * @property {string} __spec
+ * @property {string} [__declaredProviderId] the manifest's `providerId` as
+ *   written, kept by validation so it can tell whether the package has one
  * @property {string} __packageDir
  * @property {Record<string, unknown>|null} [__packageExports] the owning
  *   package's `exports` map, kept from the package.json this loader already
@@ -145,6 +159,8 @@ export function loadIntegrations(specs?: string[], { cwd, fresh, resolveProvider
  *   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[]} [__declaredKeys] the keys the manifest object itself
+ *   declares, before any is filled in (providerId from the package name)
  * @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
@@ -210,6 +226,11 @@ export type LoadedIntegration = {
      */
     __agentDocsError?: string | undefined;
     __spec: string;
+    /**
+     * the manifest's `providerId` as
+     * written, kept by validation so it can tell whether the package has one
+     */
+    __declaredProviderId?: string | undefined;
     __packageDir: string;
     /**
      * the owning
@@ -233,6 +254,11 @@ export type LoadedIntegration = {
         claimedBy: string;
         message: string;
     } | undefined;
+    /**
+     * the keys the manifest object itself
+     * declares, before any is filled in (providerId from the package name)
+     */
+    __declaredKeys?: 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

@@ -19,6 +19,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {assertWithin} from '../fs/path-safety.mjs';
+import {findNodeModulesPackage} from '../fs/paths.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
@@ -60,6 +61,8 @@ import {resolveProviders} from './provider-resolution.mjs';
  * @property {string} [__agentDocsError] contribution-specific validation
  *   failure; other manifest contributions remain available
  * @property {string} __spec
+ * @property {string} [__declaredProviderId] the manifest's `providerId` as
+ *   written, kept by validation so it can tell whether the package has one
  * @property {string} __packageDir
  * @property {Record<string, unknown>|null} [__packageExports] the owning
  *   package's `exports` map, kept from the package.json this loader already
@@ -71,6 +74,8 @@ import {resolveProviders} from './provider-resolution.mjs';
  *   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[]} [__declaredKeys] the keys the manifest object itself
+ *   declares, before any is filled in (providerId from the package name)
  * @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
@@ -213,7 +218,7 @@ function parseDiscoverSourceExport(value, label) {
  * @param {string} file absolute manifest path
  * @param {string} [label] used in error messages
  * @param {{fresh?: boolean}} [options]
- * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string, cliCommandError?: string}>}
+ * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], declaredKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string, cliCommandError?: string}>}
  */
 export async function loadManifest(
   file,
@@ -222,6 +227,7 @@ export async function loadManifest(
 ) {
   const mod = await importUserModule(file, {fresh});
   const raw = mod?.default;
+  if (raw === undefined) throw new Error(noDefaultExportMessage(file, label, mod));
   const baseManifest = parseIntegrationBase(raw, label);
   const gapReport = parseGapReportHandlerExport(mod?.gapReport, label);
   const discover = parseDiscoverSourceExport(mod?.discover, label);
@@ -274,6 +280,8 @@ export async function loadManifest(
       ...(cliCommand == null ? {} : {cliCommand}),
     },
     unknownKeys: unknownIntegrationKeys(raw),
+    declaredKeys:
+      raw != null && typeof raw === 'object' ? Object.keys(raw) : [],
     debug:
       typeof mod?.debug === 'function'
         ? /** @type {import('../../authoring/debug/type').DebugEventHandler} */ (
@@ -289,6 +297,30 @@ export async function loadManifest(
   };
 }
 
+/**
+ * Why a manifest has no default export, said plainly instead of as a schema
+ * failure on `undefined`: the file is empty, or it exports other names.
+ * @param {string} file
+ * @param {string} label
+ * @param {Record<string, unknown> | undefined} mod
+ */
+function noDefaultExportMessage(file, label, mod) {
+  const fix = `Fix: export the manifest object as the default export: \`export default {components: './components'}\`, naming the roots the package has.`;
+  let text = '';
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    // Unreadable now: say only what is missing.
+  }
+  const names = Object.keys(mod ?? {}).filter(name => name !== 'default');
+  if (text.trim() === '') return `${label} is empty. ${fix}`;
+  const found =
+    names.length > 0
+      ? ` (it exports ${names.map(name => `\`${name}\``).join(', ')})`
+      : '';
+  return `${label} has no default export${found}. ${fix}`;
+}
+
 /**
  * Load and validate a manifest module's default export against the integration
  * schema. Throws if the default export is missing or invalid. Exposed for
@@ -337,6 +369,25 @@ export function resolvePackageDir(packageName, cwd = process.cwd()) {
   return dir;
 }
 
+/**
+ * Where an integration named in astryx.config is installed: the nearest
+ * `node_modules/<name>` at or above `cwd`, found the way an autolinked
+ * dependency is, so a package a workspace hoists to its root loads in every
+ * member. When it is installed nowhere, `cwd`'s own `node_modules/<name>`,
+ * which the caller reports as not installed.
+ * @param {string} packageName
+ * @param {string} [cwd]
+ * @returns {string}
+ */
+export function resolveInstalledIntegrationDir(
+  packageName,
+  cwd = process.cwd(),
+) {
+  // Validates the name first: it throws on a spec with path segments.
+  const ownDir = resolvePackageDir(packageName, cwd);
+  return findNodeModulesPackage(cwd, packageName)?.packageDir ?? ownDir;
+}
+
 /**
  * Find the single conventional root manifest sibling of the package's
  * package.json. Multiple present is a hard error; missing is a hard error.
@@ -396,6 +447,8 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
   let manifest;
   /** @type {string[]} */
   let unknownKeys;
+  /** @type {string[]} */
+  let declaredKeys;
   /** @type {import('../../authoring/debug/type').DebugEventHandler | undefined} */
   let debugHandler;
   /** @type {import('../../authoring/gap-report/type').GapReportHandler | undefined} */
@@ -414,6 +467,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     ({
       manifest,
       unknownKeys,
+      declaredKeys,
       debug: debugHandler,
       gapReport: gapReportHandler,
       gapReportError,
@@ -462,6 +516,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     __cliCommandError: cliCommandError,
     __agentDocsError: agentDocsError,
     __unknownKeys: unknownKeys,
+    __declaredKeys: declaredKeys,
     __debug: debugHandler,
     __gapReport: gapReportHandler,
     __gapReportError: gapReportError,
@@ -496,7 +551,7 @@ export async function loadIntegrations(
     if (!spec || seenSpecs.has(spec)) continue;
     seenSpecs.add(spec);
 
-    const packageDir = resolvePackageDir(spec, cwd);
+    const packageDir = resolveInstalledIntegrationDir(spec, cwd);
     const pkgPath = path.join(packageDir, 'package.json');
     let pkg;
     try {
@@ -512,6 +567,8 @@ export async function loadIntegrations(
     let manifest;
     /** @type {string[]} */
     let unknownKeys;
+    /** @type {string[]} */
+    let declaredKeys;
     /** @type {import('../../authoring/debug/type').DebugEventHandler | undefined} */
     let debugHandler;
     /** @type {import('../../authoring/gap-report/type').GapReportHandler | undefined} */
@@ -530,6 +587,7 @@ export async function loadIntegrations(
       ({
         manifest,
         unknownKeys,
+        declaredKeys,
         debug: debugHandler,
         gapReport: gapReportHandler,
         gapReportError,
@@ -585,6 +643,7 @@ export async function loadIntegrations(
       __cliCommandError: cliCommandError,
       __agentDocsError: agentDocsError,
       __unknownKeys: unknownKeys,
+      __declaredKeys: declaredKeys,
       __debug: debugHandler,
       __gapReport: gapReportHandler,
       __gapReportError: gapReportError,

package/foundation/integrations/validate-contributions.d.mts

@@ -5,6 +5,29 @@
 export function issueError(code: string, message: string): Issue;
 /** @param {string} code @param {string} message @returns {Issue} */
 export function issueWarning(code: string, message: string): Issue;
+/**
+ * A layout finding added after the last minor release: validate lists it, in
+ * its `layout` report, but it is never an issue, so nothing counts it and
+ * `integration check --strict` does not fail on it. A new failing finding
+ * joins only in a minor release (architecture:cli-surface INV35).
+ * @param {string} code
+ * @param {string} message
+ * @returns {Issue}
+ */
+export function issueListed(code: string, message: string): Issue;
+/**
+ * Whether `issueListed` made this issue.
+ * @param {Issue} issue
+ */
+export function isListedIssue(issue: Issue): boolean;
+/**
+ * The known manifest key `key` is a near miss of: a different letter case, or
+ * at most two letters added, dropped or changed (`component`, `doc`,
+ * `tempaltes`). Null when no known key is that close, or two are.
+ * @param {string} key
+ * @returns {string | null}
+ */
+export function nearestKnownKey(key: string): string | null;
 /**
  * Why a declared root cannot be read as a folder, or null when it can.
  * A missing root keeps its own issue; a root that is a file or that the
@@ -21,6 +44,79 @@ export function rootProblem(root: string): {
     kind: "unreadable";
     code: string;
 } | null;
+/**
+ * The first folder on the way from the package to `root` (the root itself
+ * included) that is a symlink, with where it points, or null.
+ * @param {string} root absolute
+ * @param {string} packageDir absolute
+ * @returns {{path: string, target: string} | null}
+ */
+export function symlinkedFolder(root: string, packageDir: string): {
+    path: string;
+    target: string;
+} | null;
+/**
+ * The block component names this check could not judge, shaped like the
+ * doc type report so `integration check` counts them as not compared: each
+ * name a template gives in `exampleFor` or `componentsUsed` that neither the
+ * package nor Core has, when the template reaches components through
+ * anything but named imports and re-exports from the package, Core, or
+ * helpers read in full (see importedNames), or when Core is not installed to
+ * look it up in; its findings are always empty. A name judged unknown is an
+ * `unknown_block_component` note, with its fix in the message: validate
+ * lists notes beside its issues, and nothing counts them, so `--strict` does
+ * not fail on it until the next minor release (architecture:cli-surface
+ * INV35).
+ * @param {LoadedIntegration} integration
+ * @returns {Promise<{report: {status: 'checked', findings: [], unchecked: Array<{file: string, name: string, reason: string}>}, notes: Note[]}>}
+ */
+export function blockComponentsCheck(integration: LoadedIntegration): Promise<{
+    report: {
+        status: "checked";
+        findings: [];
+        unchecked: Array<{
+            file: string;
+            name: string;
+            reason: string;
+        }>;
+    };
+    notes: Note[];
+}>;
+/**
+ * The component doc names the check could not judge, shaped like the doc type
+ * report so `integration check` counts them as not compared: each doc whose
+ * `name` differs from the name it is listed under and whose source's exports
+ * cannot all be read without running it; its findings are always empty. A
+ * name the module its printed import names provably lacks is a
+ * `doc_name_mismatch` note, with its fix in the message: validate lists
+ * notes beside its issues, and nothing counts them, so `--strict` does not
+ * fail on it until the next minor release (architecture:cli-surface INV35).
+ * @param {LoadedIntegration} integration
+ * @returns {Promise<{report: {status: 'checked', findings: [], unchecked: Array<{file: string, name: string, reason: string}>}, notes: Note[]}>}
+ */
+export function componentDocNamesCheck(integration: LoadedIntegration): Promise<{
+    report: {
+        status: "checked";
+        findings: [];
+        unchecked: Array<{
+            file: string;
+            name: string;
+            reason: string;
+        }>;
+    };
+    notes: Note[];
+}>;
+/**
+ * The `name` a theme source passes to defineTheme for its exported theme,
+ * when the file says it as a string literal: `export const oceanTheme =
+ * defineTheme({name: 'ocean', ...})`. Null whenever only running the module
+ * could tell (a variable, a factory, a spread after the name, `extends`
+ * alone), so nothing is judged that a build would decide.
+ * @param {string} file
+ * @param {string} exportName
+ * @returns {string | null}
+ */
+export function literalThemeName(file: string, exportName: string): string | null;
 /**
  * Validate an already-LOADED integration (as produced by `loadIntegrations` —
  * absolute contribution roots plus identity) and return its issues. This is the
@@ -32,6 +128,17 @@ export function rootProblem(root: string): {
  * @returns {Promise<Issue[]>}
  */
 export function validateLoadedIntegration(loaded: LoadedIntegration): Promise<Issue[]>;
+/**
+ * Every contribution check, split: `issues` as validateLoadedIntegration
+ * returns them, and `listed`, the layout findings validate lists in its
+ * `layout` report without counting them.
+ * @param {LoadedIntegration} loaded
+ * @returns {Promise<{issues: Issue[], listed: Issue[]}>}
+ */
+export function validateLoadedIntegrationListed(loaded: LoadedIntegration): Promise<{
+    issues: Issue[];
+    listed: Issue[];
+}>;
 /**
  * @typedef {import('./issue').AstryxIntegrationIssue} Issue
  * @typedef {import('./integrations.mjs').LoadedIntegration} LoadedIntegration
@@ -42,5 +149,13 @@ export const INVALID_AGENT_DOCS: "invalid_agent_docs";
 export const INVALID_CLI_COMMAND: "invalid_cli_command";
 /** Stable issue code for a package whose provider ID is already claimed. */
 export const DUPLICATE_PROVIDER: "duplicate_provider";
+/**
+ * A note: information beside validate's issues that fails nothing, with the
+ * fix in its message.
+ */
+export type Note = {
+    code: string;
+    message: string;
+};
 export type Issue = import("./issue").AstryxIntegrationIssue;
 export type LoadedIntegration = import("./integrations.mjs").LoadedIntegration;