@theholocron/pkg-utils 1.12.0 → 1.13.0

package/README.md

@@ -45,6 +45,23 @@ pnpm, npm, yarn or bun, else the first lockfile found (`pnpm-lock.yaml`,
 (default `"pnpm"`). `options.readFile` and `options.fileExists` replace the disk
 access.
 
+### `listWorkspacePackagesSync(repoRoot, options?)`
+
+Every package directly under the workspace roots of `repoRoot` that has a
+readable `package.json` holding a JSON object, as `{ name, dir, relativeDir,
+manifest }` — roots in the order given, packages within a root sorted by
+directory name. A missing root, and a directory without a usable manifest,
+contribute nothing. Nothing is filtered by `name`, `version` or `private`: that
+is the caller's call. `options.roots` (default `["packages", "plugins"]`) names
+the directories to scan, each inside `repoRoot` (a `TypeError` otherwise); `options.readFile` and `options.listDirs` replace the
+disk access. A listing error other than "not there" throws. `dir` is always absolute. A single-package repo has no roots — use `readPackageJson` on it.
+
+```typescript
+import { listWorkspacePackagesSync } from "@theholocron/pkg-utils";
+
+const publishable = listWorkspacePackagesSync(repoRoot).filter((p) => !p.manifest.private && p.name);
+```
+
 ### `PackageJson`
 
 The fields these helpers read, typed; any other field passes through untyped.

package/dist/index.d.mts

@@ -39,6 +39,43 @@ export interface DetectPackageManagerOptions {
  */
 export declare function detectPackageManager(dir: string, options?: DetectPackageManagerOptions): PackageManager;
 //#endregion
+//#region src/workspace-package.type.d.ts
+/** One workspace package found by {@link listWorkspacePackagesSync}. */
+interface WorkspacePackageEntry {
+  /** The manifest's `name`, when it has one. */
+  name: string | undefined;
+  /** Absolute path to the package directory. */
+  dir: string;
+  /** The directory relative to the repo root, `/`-separated (`packages/cli`). */
+  relativeDir: string;
+  manifest: PackageJson;
+}
+//#endregion
+//#region src/list-workspace-packages.d.ts
+export interface ListWorkspacePackagesOptions {
+  /** Directories under the repo root whose children are packages; each must stay inside it. Defaults to `packages` and `plugins`. */
+  roots?: readonly string[];
+  /** Replaces the `package.json` read — for callers with an injected or in-memory filesystem. */
+  readFile?: (path: string) => string;
+  /** Replaces the directory listing: the names of the subdirectories of `dir`. Throws an `ENOENT` error when `dir` is absent. */
+  listDirs?: (dir: string) => string[];
+}
+/**
+ * Every package directly under the workspace `roots` of `repoRoot` that has a
+ * readable `package.json` holding a JSON object — roots in the order given,
+ * packages within a root sorted by directory name. A missing root, and a
+ * directory without a usable manifest, contribute nothing.
+ *
+ * Nothing is filtered by `name`, `version` or `private`: that is the caller's
+ * call (publishing wants public packages, version bumping wants all of them).
+ * `repoRoot` is resolved against the working directory, so `dir` is always
+ * absolute. A root that is absolute or climbs out of `repoRoot` throws a
+ * `TypeError`, and so does any listing error other than "not there"
+ * (`ENOENT`/`ENOTDIR`). A single-package repo has no roots; read its root manifest with
+ * `readPackageJson` instead.
+ */
+export declare function listWorkspacePackagesSync(repoRoot: string, options?: ListWorkspacePackagesOptions): WorkspacePackageEntry[];
+//#endregion
 //#region src/parse-package-json.d.ts
 /**
  * Parses `package.json` text. Returns `undefined` for anything that isn't a
@@ -66,4 +103,4 @@ export declare function readPackageJson(dir: string): Promise<PackageJson | unde
 /** Synchronous twin of {@link readPackageJson}, with an injectable `readFile`. */
 export declare function readPackageJsonSync(dir: string, options?: ReadPackageJsonOptions): PackageJson | undefined;
 //#endregion
-export type { PackageJson };
+export type { PackageJson, WorkspacePackageEntry };

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { readFile } from "node:fs/promises";
 //#region src/dependency-names.ts
 /**
@@ -99,6 +99,69 @@ function detectPackageManager(dir, options = {}) {
 	return options.fallback ?? "pnpm";
 }
 //#endregion
+//#region src/list-workspace-packages.ts
+function isAbsent(error) {
+	const code = error?.code;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+const DEFAULT_ROOTS = ["packages", "plugins"];
+function defaultListDirs(dir) {
+	return readdirSync(dir).filter((name) => {
+		try {
+			return statSync(join(dir, name)).isDirectory();
+		} catch {
+			return false;
+		}
+	});
+}
+/**
+* Every package directly under the workspace `roots` of `repoRoot` that has a
+* readable `package.json` holding a JSON object — roots in the order given,
+* packages within a root sorted by directory name. A missing root, and a
+* directory without a usable manifest, contribute nothing.
+*
+* Nothing is filtered by `name`, `version` or `private`: that is the caller's
+* call (publishing wants public packages, version bumping wants all of them).
+* `repoRoot` is resolved against the working directory, so `dir` is always
+* absolute. A root that is absolute or climbs out of `repoRoot` throws a
+* `TypeError`, and so does any listing error other than "not there"
+* (`ENOENT`/`ENOTDIR`). A single-package repo has no roots; read its root manifest with
+* `readPackageJson` instead.
+*/
+function listWorkspacePackagesSync(repoRoot, options = {}) {
+	const { roots = DEFAULT_ROOTS, listDirs = defaultListDirs } = options;
+	const base = resolve(repoRoot);
+	const readFile = options.readFile ?? ((path) => readFileSync(path, "utf8"));
+	const entries = [];
+	for (const root of roots) {
+		const rel = relative(base, resolve(base, root));
+		if (isAbsolute(root) || rel === "" || rel === ".." || rel.startsWith(`..${sep}`)) throw new TypeError(`workspace root must be a directory inside the repo, got ${JSON.stringify(root)}`);
+		let folders;
+		try {
+			folders = [...listDirs(join(base, root))].sort();
+		} catch (error) {
+			if (isAbsent(error)) continue;
+			throw error;
+		}
+		for (const folder of folders) {
+			const dir = join(base, root, folder);
+			let manifest;
+			try {
+				manifest = parsePackageJson(readFile(join(dir, "package.json")));
+			} catch {
+				continue;
+			}
+			if (manifest) entries.push({
+				name: manifest.name,
+				dir,
+				relativeDir: `${root}/${folder}`,
+				manifest
+			});
+		}
+	}
+	return entries;
+}
+//#endregion
 //#region src/read-package-json.ts
 /**
 * The parsed `<dir>/package.json`, or `undefined` when it is missing,
@@ -121,4 +184,4 @@ function readPackageJsonSync(dir, options = {}) {
 	}
 }
 //#endregion
-export { dependencyNames, detectPackageManager, parsePackageJson, readPackageJson, readPackageJsonSync };
+export { dependencyNames, detectPackageManager, listWorkspacePackagesSync, parsePackageJson, readPackageJson, readPackageJsonSync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/pkg-utils",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Read package.json, list its dependencies and detect the package manager.",
   "keywords": [
     "package.json",