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

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.