@astryxdesign/cli 0.7.2 → 0.7.3-canary.0bf23bd

package/foundation/doc-compiler/tree.d.mts

@@ -9,7 +9,7 @@
  * the one adoption rule in its package that matches its group and kind. A
  * placement that fails withdraws the doc; it never falls back to adoption. A
  * doc with neither is a flat topic: it keeps its flat name as its route, and its
- * home is the generated Unorganized level. The CLI keeps its own routes: an
+ * home is the generated level for its category. The CLI keeps its own routes: an
  * integration's node that would take one is withdrawn with a diagnostic.
  *
  * @param {{namespaces: TreeNamespaceInput[], docs: TreeDocInput[], topics?: TreeTopicInput[]}} inputs
@@ -117,19 +117,39 @@ export const KIND_GROUPS: Readonly<Record<string, {
  */
 /**
  * A flat topic: a reference topic that no namespace places. The tree gives it
- * a home in the generated Unorganized level, under its own name.
+ * a home in the generated level for its category (Guides or Foundations),
+ * under its own name.
  * @typedef {object} TreeTopicInput
  * @property {string} provider the package that owns the topic
  * @property {string} providerId the provider's ProviderId
  * @property {string} name the topic's name, which stays its route
  * @property {string} title
  * @property {string} summary
+ * @property {string | null} [category] the topic's sidebar group:
+ *   `foundations` puts it in Foundations; anything else, in Guides
  * @property {string} source where the topic comes from, for diagnostics
  * @property {string[]} [aliases] every other name the topic answers to: the
  *   topics it replaced, directly or through a chain
  */
-/** The route of the generated level that holds every flat topic. */
-export const UNORGANIZED: "unorganized";
+/**
+ * The generated levels that hold the flat topics, by category
+ * (spec:AST-046 FR12). A topic keeps its own name as its route; its level is
+ * only where it sits. Readers see these titles in a topic's path, so each is
+ * a plain name for what the topics are.
+ */
+export const TOPIC_LEVELS: Readonly<{
+    guides: Readonly<{
+        route: "guides";
+        title: "Guides";
+        summary: "Guides that stand on their own: getting started, principles, theming, and working with AI. Each topic keeps its own name; open one by it.";
+    }>;
+    foundations: Readonly<{
+        route: "foundations";
+        title: "Foundations";
+        summary: "Color, elevation, icons, illustrations, motion, shape, and spacing: the visual foundations every component builds on. Each topic keeps its own name; open one by it.";
+    }>;
+}>;
+export function topicLevel(category: string | null | undefined): "guides" | "foundations";
 export type NamespaceDoc = import("../../authoring/doctypes/namespace/type").NamespaceDoc;
 export type DocPlacement = import("../../authoring/doctypes/base/type").DocPlacement;
 export type CompilerDiagnostic = import("./diagnostics.mjs").CompilerDiagnostic;
@@ -200,7 +220,8 @@ export type TreeSlot = {
 };
 /**
  * A flat topic: a reference topic that no namespace places. The tree gives it
- * a home in the generated Unorganized level, under its own name.
+ * a home in the generated level for its category (Guides or Foundations),
+ * under its own name.
  */
 export type TreeTopicInput = {
     /**
@@ -217,6 +238,11 @@ export type TreeTopicInput = {
     name: string;
     title: string;
     summary: string;
+    /**
+     * the topic's sidebar group:
+     * `foundations` puts it in Foundations; anything else, in Guides
+     */
+    category?: string | null | undefined;
     /**
      * where the topic comes from, for diagnostics
      */
@@ -265,7 +291,7 @@ export type TreeNode = {
     order: number | null;
     /**
      * made by the compiler (a `groupBy: 'kind'`
-     * level, or the Unorganized level), not authored
+     * level, or a flat topics' level), not authored
      */
     generated: boolean;
     /**

package/foundation/doc-compiler/tree.mjs

@@ -12,7 +12,7 @@
  * @position Between discovery and the readers: `astryx docs <route>`,
  *   `astryx doctor`, and the docsite build all read this tree. The CLI's docs
  *   and each integration's have a home here, and a flat topic's home is the
- *   generated Unorganized level.
+ *   generated level for its category: Guides or Foundations.
  *   A namespace never scans files and never lists its children: a child names
  *   its parent, or a namespace adopts a discovery group.
  */
@@ -113,20 +113,49 @@ export const KIND_GROUPS = Object.freeze({
 
 /**
  * A flat topic: a reference topic that no namespace places. The tree gives it
- * a home in the generated Unorganized level, under its own name.
+ * a home in the generated level for its category (Guides or Foundations),
+ * under its own name.
  * @typedef {object} TreeTopicInput
  * @property {string} provider the package that owns the topic
  * @property {string} providerId the provider's ProviderId
  * @property {string} name the topic's name, which stays its route
  * @property {string} title
  * @property {string} summary
+ * @property {string | null} [category] the topic's sidebar group:
+ *   `foundations` puts it in Foundations; anything else, in Guides
  * @property {string} source where the topic comes from, for diagnostics
  * @property {string[]} [aliases] every other name the topic answers to: the
  *   topics it replaced, directly or through a chain
  */
 
-/** The route of the generated level that holds every flat topic. */
-export const UNORGANIZED = 'unorganized';
+/**
+ * The generated levels that hold the flat topics, by category
+ * (spec:AST-046 FR12). A topic keeps its own name as its route; its level is
+ * only where it sits. Readers see these titles in a topic's path, so each is
+ * a plain name for what the topics are.
+ */
+export const TOPIC_LEVELS = Object.freeze({
+  guides: Object.freeze({
+    route: 'guides',
+    title: 'Guides',
+    summary:
+      'Guides that stand on their own: getting started, principles, theming, and working with AI. Each topic keeps its own name; open one by it.',
+  }),
+  foundations: Object.freeze({
+    route: 'foundations',
+    title: 'Foundations',
+    summary:
+      'Color, elevation, icons, illustrations, motion, shape, and spacing: the visual foundations every component builds on. Each topic keeps its own name; open one by it.',
+  }),
+});
+
+/**
+ * The generated level a flat topic sits in.
+ * @param {string | null | undefined} category
+ * @returns {'guides' | 'foundations'}
+ */
+export const topicLevel = category =>
+  category === 'foundations' ? 'foundations' : 'guides';
 
 /**
  * @typedef {object} TreeNode
@@ -145,7 +174,7 @@ export const UNORGANIZED = 'unorganized';
  * @property {string | null} slot the parent slot this node sits in
  * @property {number | null} order
  * @property {boolean} generated made by the compiler (a `groupBy: 'kind'`
- *   level, or the Unorganized level), not authored
+ *   level, or a flat topics' level), not authored
  * @property {TreeSlot[]} slots a namespace's slots; empty for a leaf
  * @property {string} source
  * @property {any} [ref]
@@ -216,7 +245,7 @@ function resolveParent(parent, provider, declared) {
  * the one adoption rule in its package that matches its group and kind. A
  * placement that fails withdraws the doc; it never falls back to adoption. A
  * doc with neither is a flat topic: it keeps its flat name as its route, and its
- * home is the generated Unorganized level. The CLI keeps its own routes: an
+ * home is the generated level for its category. The CLI keeps its own routes: an
  * integration's node that would take one is withdrawn with a diagnostic.
  *
  * @param {{namespaces: TreeNamespaceInput[], docs: TreeDocInput[], topics?: TreeTopicInput[]}} inputs
@@ -237,10 +266,15 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
     );
 
   // Routes the CLI's own docs keep (spec:AST-046 FR11): the name of each of
-  // its flat topics, and the generated Unorganized level. Its namespaces keep
-  // theirs by rank, because they go into the tree first. Routes compare
-  // without case, as topic names do, so `CLI` claims `cli`.
-  const cliRoutes = new Set(topics.length > 0 ? [UNORGANIZED] : []);
+  // its flat topics, and the generated levels that hold flat topics. Its
+  // namespaces keep theirs by rank, because they go into the tree first.
+  // Routes compare without case, as topic names do, so `CLI` claims `cli`.
+  /** @type {Set<string>} */
+  const cliRoutes = new Set(
+    topics.length > 0
+      ? Object.values(TOPIC_LEVELS).map(level => level.route)
+      : [],
+  );
   for (const topic of topics) {
     if (topic.provider === CLI_PROVIDER)
       cliRoutes.add(topic.name.toLowerCase());
@@ -592,20 +626,21 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
     );
   }
 
-  // The generated Unorganized level (spec:AST-046 FR12): every flat topic sits
-  // here, in the order the topic list reads, so every doc has a home in the
-  // tree. A topic keeps its own name as its route.
-  if (topics.length > 0) {
+  // The generated levels (spec:AST-046 FR12): every flat topic sits in the
+  // level for its category, in the order the topic list reads, so every doc
+  // has a named home in the tree. A topic keeps its own name as its route.
+  for (const [key, level] of Object.entries(TOPIC_LEVELS)) {
+    const members = topics.filter(topic => topicLevel(topic.category) === key);
+    if (members.length === 0) continue;
     const home = {
       id: null,
-      route: UNORGANIZED,
+      route: level.route,
       kind: 'namespace',
       provider: CLI_PROVIDER,
       providerId: CLI_PROVIDER_ID,
-      name: UNORGANIZED,
-      title: 'Unorganized',
-      summary:
-        'Every topic that no section places yet. Each keeps its own name; open one by it.',
+      name: level.route,
+      title: level.title,
+      summary: level.summary,
       parent: null,
       slot: null,
       order: null,
@@ -613,30 +648,29 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
       slots: [{name: 'topics', title: 'Topics', children: []}],
       source: 'generated',
     };
-    if (addNode(home, {provider: CLI_PROVIDER, source: 'generated'})) {
-      topics.forEach((topic, i) => {
-        addNode(
-          {
-            id: createDocId(topic.providerId, 'generic', topic.name),
-            route: topic.name,
-            kind: 'generic',
-            provider: topic.provider,
-            providerId: topic.providerId,
-            name: topic.name,
-            title: topic.title,
-            summary: topic.summary,
-            parent: UNORGANIZED,
-            slot: 'topics',
-            order: i,
-            generated: false,
-            slots: [],
-            source: topic.source,
-            ref: {flatTopic: topic.name},
-          },
-          topic,
-        );
-      });
-    }
+    if (!addNode(home, {provider: CLI_PROVIDER, source: 'generated'})) continue;
+    members.forEach((topic, i) => {
+      addNode(
+        {
+          id: createDocId(topic.providerId, 'generic', topic.name),
+          route: topic.name,
+          kind: 'generic',
+          provider: topic.provider,
+          providerId: topic.providerId,
+          name: topic.name,
+          title: topic.title,
+          summary: topic.summary,
+          parent: level.route,
+          slot: 'topics',
+          order: i,
+          generated: false,
+          slots: [],
+          source: topic.source,
+          ref: {flatTopic: topic.name},
+        },
+        topic,
+      );
+    });
   }
 
   // Children, per slot, in reading order: order, then title, then id.

package/foundation/doc-compiler/tree.test.mjs

@@ -154,21 +154,21 @@ describe('buildDocsTree', () => {
       source: `${provider}/${name}.doc.mjs`,
     });
     const cliNs = {...ns('cli'), provider: CLI, providerId: CLI, source: `${CLI}/tree/cli.doc.mjs`};
-    // An integration's topics named `CLI` and `UNORGANIZED` claim the CLI's
-    // namespace and the generated level; both are withdrawn.
+    // An integration's topics named `CLI` and `GUIDES` claim the CLI's
+    // namespace and a generated level; both are withdrawn.
     const tree = buildDocsTree({
       namespaces: [cliNs],
       docs: [],
-      topics: [topic('theme', CLI), topic('CLI'), topic('UNORGANIZED')],
+      topics: [topic('theme', CLI), topic('CLI'), topic('GUIDES')],
     });
     expect(tree.get('cli')?.provider).toBe(CLI);
-    expect(tree.get('unorganized')?.provider).toBe(CLI);
+    expect(tree.get('guides')?.provider).toBe(CLI);
     expect(routes(tree)).not.toContain('CLI');
-    expect(routes(tree)).not.toContain('UNORGANIZED');
+    expect(routes(tree)).not.toContain('GUIDES');
     expect(problems(tree)).toEqual(
       expect.arrayContaining([
         ['duplicate_route', expect.stringContaining('both have the route "CLI"')],
-        ['duplicate_route', expect.stringContaining('takes the route "UNORGANIZED", which the CLI\'s own docs keep')],
+        ['duplicate_route', expect.stringContaining('takes the route "GUIDES", which the CLI\'s own docs keep')],
       ]),
     );
     // It names both docs as their authors know them, never by artifact id,
@@ -502,7 +502,7 @@ describe("the CLI's own docs tree", () => {
     async () => {
       const tree = await loadDocsTree({fresh: true});
       expect(tree.diagnostics).toEqual([]);
-      expect(tree.roots().map(node => node.route)).toEqual(['cli', 'global', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography']);
+      expect(tree.roots().map(node => node.route)).toEqual(['authoring', 'cli', 'global', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography']);
       // Every slot child is a node one level below the namespace that places
       // it, and every node but the root is placed. Read from the tree, so a
       // restructure of the guides does not need this test edited.

package/foundation/fs/paths.d.mts

@@ -51,17 +51,58 @@ export function findCarriedCoreDir(startDir: string, { fetch }?: {
     fetch?: boolean;
 }): string | null;
 /**
- * Find packages/core directory by walking up from startDir.
- * Also checks node_modules/@astryxdesign/core for installed usage.
- *
- * The project's Core only: in the folder or four above it, the reach every
- * released version used, else from the folder of the package.json that makes
- * the folder part of a project, however deep the folder is.
+ * The project's own @astryxdesign/core, never a carried one: found from the
+ * folder (see {@link findNearbyCoreDir}), else from the folder of the
+ * package.json that makes the folder part of a project, however deep the
+ * folder is.
  *
  * @param {string} [startDir]
  * @returns {string | null}
  */
 export function findProjectCoreDir(startDir?: string): string | null;
+/**
+ * The project root: the directory of the nearest package.json at or above
+ * `startDir`, or null when there is none.
+ *
+ * @param {string} startDir
+ * @returns {string|null}
+ */
+export function findPackageRoot(startDir: string): string | null;
+/**
+ * The Astryx project `startDir` belongs to: the nearest folder at or above it
+ * whose package.json declares an Astryx package (`@astryxdesign/*`, or the
+ * legacy `@xds/*`), or that a workspace whose root declares one lists as a
+ * member. The search stops at a repository root, and it ends at the home
+ * folder without counting it. Returns null when no folder qualifies.
+ *
+ * @param {string} startDir
+ * @returns {string|null}
+ */
+export function findAstryxProject(startDir: string): string | null;
+/**
+ * The workspace root (`spec:AST-048` FR15): the nearest directory at or above
+ * `startDir` that declares a workspace, by a `pnpm-workspace.yaml` or a
+ * package.json `workspaces` field; outside a workspace, the directory of the
+ * nearest package.json; with no package.json, `startDir` itself.
+ *
+ * @param {string} startDir
+ * @returns {string}
+ */
+export function findWorkspaceRoot(startDir: string): string;
+/**
+ * The nearest `node_modules/<name>` at or above `startDir`, found the way
+ * Node's resolver finds a package, and the folder whose node_modules holds it.
+ * It searches every folder up to the filesystem root and does not ask
+ * Plug'n'Play.
+ *
+ * @param {string} startDir
+ * @param {string} name bare package name; callers reject path segments first
+ * @returns {{packageDir: string, hostDir: string}|null}
+ */
+export function findNodeModulesPackage(startDir: string, name: string): {
+    packageDir: string;
+    hostDir: string;
+} | null;
 /**
  * Locate a package the project at `startDir` actually installed.
  *
@@ -73,14 +114,35 @@ export function findProjectCoreDir(startDir?: string): string | null;
  * Reading package.json off disk also sidesteps packages that don't export it,
  * so the version is always available to range-check.
  *
- * Walks the node_modules chain first, then asks PnP, which covers the Yarn
- * default layout where that chain does not exist.
+ * Searches the node_modules of `startDir` and the five folders above it, as
+ * released versions did, then on up to the workspace root of the Astryx
+ * project it belongs to. Then it asks PnP, which covers the Yarn default
+ * layout where that chain does not exist.
  *
  * @param {string} startDir
  * @param {string} name
  * @returns {string|null} the package directory, or null when not installed
  */
 export function findInstalledPackage(startDir: string, name: string): string | null;
+/**
+ * The first of `names` the Astryx project of `startDir` installed, for a
+ * command that writes to the project (`upgrade`).
+ *
+ * It searches the node_modules of the project root, nearest name first. For
+ * a member its workspace lists, it then searches each folder above the
+ * project up to the workspace root, where the workspace installs the packages
+ * its members share; otherwise the search stops at the project root. Then it
+ * asks Plug'n'Play, in name order. With no Astryx project it looks only in the
+ * node_modules of `startDir` itself, as released versions did.
+ *
+ * @param {string} startDir
+ * @param {readonly string[]} names in order of preference
+ * @returns {{name: string, packageDir: string}|null}
+ */
+export function findProjectPackageOf(startDir: string, names: readonly string[]): {
+    name: string;
+    packageDir: string;
+} | null;
 /**
  * Find the monorepo root by looking for the root package.json
  * that has workspaces defined.