@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/foundation/discovery/docs-discovery.d.mts

@@ -39,6 +39,13 @@
  * @returns {Record<string, string>} topic name → absolute doc path
  */
 export function discoverBuiltinTopics(): Record<string, string>;
+/**
+ * The CLI's own guide files: every flat topic and every doc in its docs tree,
+ * without the dense, translated, and draft variants.
+ *
+ * @returns {string[]}
+ */
+export function builtinGuideFiles(): string[];
 /**
  * Load a topic doc from disk. A `.ts` doc is loaded through jiti, the rest
  * natively; both the historical `export const docs` and the stamped
@@ -132,6 +139,35 @@ export const GRAPH_BLOCK_TYPES: Set<string>;
  * load; a guide the tree places may set `placement` (spec:AST-046).
  */
 export const GRAPH_ONLY_FIELDS: string[];
+/**
+ * A component a link can name: its owner's provider id, package, and name,
+ * and the doc file that describes it.
+ * @typedef {object} LinkableComponent
+ * @property {string} providerId
+ * @property {string} package
+ * @property {string} name
+ * @property {string | null} docPath
+ * @property {string} [replaces] the Core component whose name it answers to
+ *   in unqualified lookups (spec:AST-035 FR11)
+ */
+/**
+ * A page or block template a link can name, by the id `astryx template` takes.
+ * @typedef {object} LinkableTemplate
+ * @property {string} providerId
+ * @property {string} package
+ * @property {'page' | 'block'} type
+ * @property {string} id
+ * @property {string} name
+ * @property {string} [displayName]
+ * @property {string} [description]
+ * @property {string} [replaces] the Core template id it answers to in
+ *   unqualified lookups
+ */
+/**
+ * The component and template docs links can name (spec:AST-047 FR9). No docs
+ * tree holds them, so a catalog carries the records the project reads.
+ * @typedef {{components: LinkableComponent[], templates: LinkableTemplate[]}} LinkableContributions
+ */
 /**
  * Every topic a project can read, and the relationships between them.
  *
@@ -181,6 +217,18 @@ export class DocsCatalog {
         namespaces: import("../doc-compiler/tree.mjs").TreeNamespaceInput[];
         guides: import("../doc-compiler/tree.mjs").TreeDocInput[];
     }>;
+    /**
+     * Say where links find component, page, and block docs: the records
+     * `astryx component` and `astryx template` read, loaded on first use.
+     * @param {() => Promise<LinkableContributions>} load
+     */
+    setContributions(load: () => Promise<LinkableContributions>): void;
+    /**
+     * The component and template docs links can name, or null when nothing set
+     * them, so no link to one resolves.
+     * @returns {Promise<LinkableContributions | null>}
+     */
+    contributions(): Promise<LinkableContributions | null>;
     /**
      * Add one integration-contributed doc, honoring what it declares. Returns
      * the issue it caused, or null when it applied cleanly — the caller owns
@@ -290,4 +338,44 @@ export type DocsTopicEntry = {
      */
     tree?: boolean | undefined;
 };
+/**
+ * A component a link can name: its owner's provider id, package, and name,
+ * and the doc file that describes it.
+ */
+export type LinkableComponent = {
+    providerId: string;
+    package: string;
+    name: string;
+    docPath: string | null;
+    /**
+     * the Core component whose name it answers to
+     * in unqualified lookups (spec:AST-035 FR11)
+     */
+    replaces?: string | undefined;
+};
+/**
+ * A page or block template a link can name, by the id `astryx template` takes.
+ */
+export type LinkableTemplate = {
+    providerId: string;
+    package: string;
+    type: "page" | "block";
+    id: string;
+    name: string;
+    displayName?: string | undefined;
+    description?: string | undefined;
+    /**
+     * the Core template id it answers to in
+     * unqualified lookups
+     */
+    replaces?: string | undefined;
+};
+/**
+ * The component and template docs links can name (spec:AST-047 FR9). No docs
+ * tree holds them, so a catalog carries the records the project reads.
+ */
+export type LinkableContributions = {
+    components: LinkableComponent[];
+    templates: LinkableTemplate[];
+};
 import { withSourceTitle } from './docs-section-key.mjs';

package/foundation/discovery/docs-discovery.mjs

@@ -117,6 +117,23 @@ export function discoverBuiltinTopics() {
   return topics;
 }
 
+/**
+ * The CLI's own guide files: every flat topic and every doc in its docs tree,
+ * without the dense, translated, and draft variants.
+ *
+ * @returns {string[]}
+ */
+export function builtinGuideFiles() {
+  const files = Object.values(discoverBuiltinTopics());
+  const tree = path.join(BUILTIN_DOCS_DIR, 'tree');
+  if (fs.existsSync(tree)) {
+    for (const file of fs.readdirSync(tree).sort()) {
+      if (BUILTIN_TOPIC_FILE_RE.test(file)) files.push(path.join(tree, file));
+    }
+  }
+  return files;
+}
+
 /**
  * Load a topic doc from disk. A `.ts` doc is loaded through jiti, the rest
  * natively; both the historical `export const docs` and the stamped
@@ -384,7 +401,11 @@ export function problemsInNamespace(doc) {
     }
   }
   const slots = doc?.slots;
-  if (slots == null || typeof slots !== 'object' || Object.keys(slots).length === 0) {
+  if (
+    slots == null ||
+    typeof slots !== 'object' ||
+    Object.keys(slots).length === 0
+  ) {
     problems.push('slots: expected at least one slot');
     return problems;
   }
@@ -392,13 +413,29 @@ export function problemsInNamespace(doc) {
     if (typeof slot?.title !== 'string' || slot.title === '') {
       problems.push(`slots.${name}.title: expected a non-empty string`);
     }
-    if (!Array.isArray(slot?.accepts?.kinds) || slot.accepts.kinds.length === 0) {
+    if (
+      !Array.isArray(slot?.accepts?.kinds) ||
+      slot.accepts.kinds.length === 0
+    ) {
       problems.push(`slots.${name}.accepts.kinds: expected at least one kind`);
     }
   }
   return problems;
 }
 
+/**
+ * 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;
+  }
+}
+
 /**
  * Discover the topics contributed by a single loaded integration. Mirrors
  * `discoverIntegrationComponents`: walk the resolved root, take every
@@ -426,7 +463,7 @@ export async function discoverIntegrationDocs(integration) {
   const namespaces = [];
   /** @type {import('../doc-compiler/tree.mjs').TreeDocInput[]} */
   const guides = [];
-  if (!docsDir || !fs.existsSync(docsDir)) {
+  if (!docsDir || !isFolder(docsDir)) {
     return {records, errors, namespaces, guides};
   }
   const providerId = integration.providerId ?? integration.name;
@@ -633,6 +670,38 @@ function findMergeTarget(sections, section) {
   return sections.findIndex(candidate => candidate.id === key);
 }
 
+/**
+ * A component a link can name: its owner's provider id, package, and name,
+ * and the doc file that describes it.
+ * @typedef {object} LinkableComponent
+ * @property {string} providerId
+ * @property {string} package
+ * @property {string} name
+ * @property {string | null} docPath
+ * @property {string} [replaces] the Core component whose name it answers to
+ *   in unqualified lookups (spec:AST-035 FR11)
+ */
+
+/**
+ * A page or block template a link can name, by the id `astryx template` takes.
+ * @typedef {object} LinkableTemplate
+ * @property {string} providerId
+ * @property {string} package
+ * @property {'page' | 'block'} type
+ * @property {string} id
+ * @property {string} name
+ * @property {string} [displayName]
+ * @property {string} [description]
+ * @property {string} [replaces] the Core template id it answers to in
+ *   unqualified lookups
+ */
+
+/**
+ * The component and template docs links can name (spec:AST-047 FR9). No docs
+ * tree holds them, so a catalog carries the records the project reads.
+ * @typedef {{components: LinkableComponent[], templates: LinkableTemplate[]}} LinkableContributions
+ */
+
 /**
  * Every topic a project can read, and the relationships between them.
  *
@@ -644,6 +713,10 @@ function findMergeTarget(sections, section) {
 export class DocsCatalog {
   /** @type {Map<string, DocsTopicEntry>} */
   #topics = new Map();
+  /** @type {(() => Promise<LinkableContributions>) | null} */
+  #contributions = null;
+  /** @type {Promise<LinkableContributions> | null} */
+  #contributionsLoaded = null;
   /** @type {Map<string, string>} old topic name → the name that replaced it */
   #aliases = new Map();
   /** @type {Array<{namespaces: import('../doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../doc-compiler/tree.mjs').TreeDocInput[]}>} */
@@ -687,6 +760,27 @@ export class DocsCatalog {
     return this.#treeInputs;
   }
 
+  /**
+   * Say where links find component, page, and block docs: the records
+   * `astryx component` and `astryx template` read, loaded on first use.
+   * @param {() => Promise<LinkableContributions>} load
+   */
+  setContributions(load) {
+    this.#contributions = load;
+    this.#contributionsLoaded = null;
+  }
+
+  /**
+   * The component and template docs links can name, or null when nothing set
+   * them, so no link to one resolves.
+   * @returns {Promise<LinkableContributions | null>}
+   */
+  contributions() {
+    if (!this.#contributions) return Promise.resolve(null);
+    this.#contributionsLoaded ??= this.#contributions();
+    return this.#contributionsLoaded;
+  }
+
   /**
    * Seed a catalog with the CLI's own topics.
    * @param {Record<string, string>} [builtins] topic name → absolute path

package/foundation/discovery/integration-doc-files.d.mts

@@ -0,0 +1,22 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/** @typedef {import('./doc-types.mjs').DocFile} DocFile */
+/** @typedef {import('./doc-types.mjs').DocRoot} DocRoot */
+/**
+ * Every doc file an integration's roots hold, each assigned to the deepest
+ * root that holds it, each root a reader could not read, and how many test
+ * fixtures no reader serves.
+ * @param {any} integration a loaded integration
+ * @returns {Promise<{files: DocFile[], unread: Array<{path: string, reason: string}>, fixtures: number}>}
+ */
+export function integrationDocFiles(integration: any): Promise<{
+    files: DocFile[];
+    unread: Array<{
+        path: string;
+        reason: string;
+    }>;
+    fixtures: number;
+}>;
+export type DocFile = import("./doc-types.mjs").DocFile;
+export type DocRoot = import("./doc-types.mjs").DocRoot;

package/foundation/discovery/integration-doc-files.mjs

@@ -0,0 +1,231 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The doc files an integration package ships, by root: every doc its
+ * roots hold, so the doc type check covers each one an agent can open.
+ *
+ * Each root's reader names the docs it serves, with the kind it reads each
+ * as:
+ * - components: the doc each component discovery records;
+ * - templates: the doc of each template template discovery serves;
+ * - docs: the file of each topic, namespace and placed guide docs discovery
+ *   serves, and each topic's and guide's `zh` and `dense` overlay that a docs
+ *   read applies;
+ * - themes: each theme's descriptor, as theme discovery resolves it. A themes
+ *   root that discovery cannot read serves no theme, and is listed with the
+ *   reason.
+ * A doc no reader serves still ships: a `hidden` one, a second doc for one
+ * name, an overlay without its topic. It goes to its root's kind. A test
+ * fixture does not ship as a doc, and is only counted: a doc under
+ * `__tests__` in the components or docs root, which those readers skip.
+ * A file two roots hold goes to the deepest.
+ *
+ * @input A loaded integration and its resolved roots.
+ * @output DocFile entries for checkDocTypes, each with the root it belongs to,
+ *   the roots a reader could not read, and how many test fixtures it left
+ *   out.
+ * @position Read by `astryx doctor integration validate` before it checks
+ *   each doc against its authoring type.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {OVERLAY_LANGUAGES, overlayPath} from '../doc-compiler/read.mjs';
+import {discoverIntegrationComponents} from './component-discovery.mjs';
+import {discoverIntegrationDocs} from './docs-discovery.mjs';
+import {discoverIntegrationTemplatesForOne} from './template-adapter.mjs';
+import {discoverThemeDirectory} from './theme-discovery.mjs';
+import {rootProblem} from '../integrations/validate-contributions.mjs';
+
+/** @typedef {import('./doc-types.mjs').DocFile} DocFile */
+/** @typedef {import('./doc-types.mjs').DocRoot} DocRoot */
+
+/**
+ * Every doc file an integration's roots hold, each assigned to the deepest
+ * root that holds it, each root a reader could not read, and how many test
+ * fixtures no reader serves.
+ * @param {any} integration a loaded integration
+ * @returns {Promise<{files: DocFile[], unread: Array<{path: string, reason: string}>, fixtures: number}>}
+ */
+export async function integrationDocFiles(integration) {
+  const {components, templates, docs, themes} = integration ?? {};
+  /** @type {Array<[DocRoot, string, string[]]>} */
+  const read = [];
+  /** @type {Array<{path: string, reason: string}>} */
+  const unread = [];
+  // A root `validate` already reports (missing, a file, unreadable) is left
+  // to that issue. A reader that fails inside a root, such as on a folder it
+  // cannot read, leaves the root listed with the reason.
+  /** @type {(root: string | undefined, label: string, files: () => Promise<Array<[DocRoot, string[]]>>) => Promise<void>} */
+  const take = async (root, label, files) => {
+    if (!root || rootProblem(root)) return;
+    try {
+      for (const [kind, list] of await files()) read.push([kind, root, list]);
+    } catch (err) {
+      unread.push({
+        path: root,
+        reason: `the ${label} root does not load, so no doc in it was checked: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+  };
+  await take(components, 'components', async () => [
+    [
+      'components',
+      discoverIntegrationComponents(integration).map(c => c.docPath),
+    ],
+  ]);
+  await take(templates, 'templates', async () => [
+    [
+      'templates',
+      (await discoverIntegrationTemplatesForOne(integration)).templates.map(
+        t => t.docPath,
+      ),
+    ],
+  ]);
+  await take(docs, 'docs', async () => {
+    const found = await discoverIntegrationDocs(integration);
+    // Topics and placed guides are read with their overlays; a namespace
+    // names its file `<package name>/<path in the root>`.
+    const withOverlays = [
+      ...found.records.map(record => record.path),
+      ...found.guides.map(guide => guide.ref.topicFile),
+    ];
+    const prefix = `${integration.name}/`;
+    const namespaces = found.namespaces.map(entry =>
+      path.join(
+        /** @type {string} */ (docs),
+        ...(entry.source.startsWith(prefix)
+          ? entry.source.slice(prefix.length)
+          : entry.source
+        ).split('/'),
+      ),
+    );
+    return [
+      ['docs', [...withOverlays, ...namespaces]],
+      [
+        'docs-overlay',
+        withOverlays.flatMap(file =>
+          OVERLAY_LANGUAGES.map(lang => overlayPath(file, lang)).filter(
+            overlay => fs.existsSync(overlay),
+          ),
+        ),
+      ],
+    ];
+  });
+  await take(themes, 'themes', async () => [
+    [
+      'themes',
+      discoverThemeDirectory(
+        /** @type {string} */ (themes),
+        integration?.name ?? 'the package',
+      ).map(theme => theme.docPath),
+    ],
+  ]);
+  /** @type {Map<string, {root: DocRoot, dir: string}>} */
+  const owners = new Map();
+  /** @type {(table: Map<string, {root: DocRoot, dir: string}>, root: DocRoot, dir: string, file: string) => void} */
+  const own = (table, root, dir, file) => {
+    const owner = table.get(file);
+    if (!owner || dir.length > owner.dir.length) table.set(file, {root, dir});
+  };
+  for (const [root, dir, files] of read) {
+    for (const file of files) own(owners, root, dir, file);
+  }
+  // The docs no reader serves, in each root a reader could read.
+  /** @type {Map<string, {root: DocRoot, dir: string}>} */
+  const shipped = new Map();
+  const readable = new Set(read.map(([, dir]) => dir));
+  for (const [
+    kind,
+    dir,
+  ] of /** @type {Array<[DocRoot, string | undefined]>} */ ([
+    ['components', components],
+    ['templates', templates],
+    ['docs', docs],
+    ['themes', themes],
+  ])) {
+    if (!dir || !readable.has(dir)) continue;
+    for (const file of docFilesUnder(dir)) {
+      const overlay = OVERLAY_LANGUAGES.some(lang =>
+        file.endsWith(`.doc.${lang}.mjs`),
+      );
+      if (overlay && kind !== 'docs') continue;
+      own(shipped, overlay ? 'docs-overlay' : kind, dir, file);
+    }
+  }
+  let fixtures = 0;
+  for (const [file, owner] of shipped) {
+    if (owners.has(file)) continue;
+    if (isFixture(path.relative(owner.dir, file), owner.root)) fixtures++;
+    else owners.set(file, owner);
+  }
+  return {
+    files: [...owners]
+      .map(([file, {root}]) => ({path: file, root}))
+      .sort((a, b) => a.path.localeCompare(b.path)),
+    unread,
+    fixtures,
+  };
+}
+
+/**
+ * Whether a doc file is a test fixture: under `__tests__` in a root whose
+ * reader skips that folder (components and docs). The template reader reads
+ * it, so a template doc there is the package's like any other.
+ * @param {string} file its path relative to its root
+ * @param {DocRoot} root
+ */
+function isFixture(file, root) {
+  return (
+    root !== 'templates' &&
+    root !== 'themes' &&
+    file.split(path.sep).includes('__tests__')
+  );
+}
+
+/**
+ * Every doc file under a folder: a `.doc.ts`, `.doc.mjs` or `.doc.js` file,
+ * or a `zh` or `dense` overlay, through its folders and linked files, but not
+ * `node_modules`, `.git` or a linked folder.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function docFilesUnder(dir) {
+  /** @type {string[]} */
+  const found = [];
+  /** @type {(folder: string) => void} */
+  const walk = folder => {
+    /** @type {fs.Dirent[]} */
+    let entries;
+    try {
+      entries = fs.readdirSync(folder, {withFileTypes: true});
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+      const full = path.join(folder, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        try {
+          if (!fs.statSync(full).isFile()) continue;
+        } catch {
+          continue;
+        }
+      } else if (!entry.isFile()) {
+        continue;
+      }
+      if (
+        /\.doc\.(ts|mjs|js)$/.test(entry.name) ||
+        OVERLAY_LANGUAGES.some(lang => entry.name.endsWith(`.doc.${lang}.mjs`))
+      ) {
+        found.push(full);
+      }
+    }
+  };
+  walk(dir);
+  return found;
+}