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

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.