@theholocron/pkg-utils 1.11.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

@@ -0,0 +1,106 @@
+//#region src/package-json.type.d.ts
+/** The `package.json` fields these utils and their callers read; any other field passes through untyped. */
+interface PackageJson {
+  name?: string;
+  version?: string;
+  private?: boolean;
+  packageManager?: string;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  [field: string]: unknown;
+}
+//#endregion
+//#region src/dependency-names.d.ts
+export type DependencyField = "dependencies" | "devDependencies" | "peerDependencies" | "optionalDependencies";
+/**
+ * Every package name declared in `pkg`'s dependency maps — `dependencies` and
+ * `devDependencies` unless `fields` says otherwise. An absent `pkg`, a missing
+ * map, an array or any other non-object contributes nothing.
+ */
+export declare function dependencyNames(pkg: PackageJson | undefined, fields?: readonly DependencyField[]): ReadonlySet<string>;
+//#endregion
+//#region src/detect-package-manager.d.ts
+export type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
+export interface DetectPackageManagerOptions {
+  /** Replaces the `package.json` read — for callers with an injected or in-memory filesystem. */
+  readFile?: (path: string) => string;
+  /** Replaces the lockfile existence check. */
+  fileExists?: (path: string) => boolean;
+  /** Returned when neither `package.json` nor a lockfile says. Defaults to `"pnpm"`. */
+  fallback?: PackageManager;
+}
+/**
+ * The package manager `dir` uses: the name in `package.json#packageManager`
+ * (`pnpm@10.0.0` → `pnpm`) when it's one of pnpm, npm, yarn or bun, else the
+ * first lockfile found, else `options.fallback`.
+ */
+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
+ * JSON object — invalid JSON, or valid JSON of another type (an array, `null`,
+ * a string) — rather than throwing. A leading byte-order mark is ignored, as
+ * npm does.
+ *
+ * The fields {@link PackageJson} types are checked, so the result honours its
+ * type: a recognized field of the wrong type (a numeric `name`, an array
+ * `dependencies`) is left out, and the string-map fields keep only their
+ * string-valued entries. Every other field passes through untouched.
+ */
+export declare function parsePackageJson(text: string): PackageJson | undefined;
+//#endregion
+//#region src/read-package-json.d.ts
+export interface ReadPackageJsonOptions {
+  /** Replaces the file read — for callers with an injected or in-memory filesystem. */
+  readFile?: (path: string) => string;
+}
+/**
+ * The parsed `<dir>/package.json`, or `undefined` when it is missing,
+ * unreadable or not a JSON object.
+ */
+export declare function readPackageJson(dir: string): Promise<PackageJson | undefined>;
+/** Synchronous twin of {@link readPackageJson}, with an injectable `readFile`. */
+export declare function readPackageJsonSync(dir: string, options?: ReadPackageJsonOptions): PackageJson | undefined;
+//#endregion
+export type { PackageJson, WorkspacePackageEntry };

package/dist/index.mjs

@@ -0,0 +1,187 @@
+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
+/**
+* Every package name declared in `pkg`'s dependency maps — `dependencies` and
+* `devDependencies` unless `fields` says otherwise. An absent `pkg`, a missing
+* map, an array or any other non-object contributes nothing.
+*/
+function dependencyNames(pkg, fields = ["dependencies", "devDependencies"]) {
+	const names = /* @__PURE__ */ new Set();
+	for (const field of fields) {
+		const map = pkg?.[field];
+		if (typeof map === "object" && map !== null && !Array.isArray(map)) for (const name of Object.keys(map)) names.add(name);
+	}
+	return names;
+}
+//#endregion
+//#region src/parse-package-json.ts
+const STRING_FIELDS = [
+	"name",
+	"version",
+	"packageManager"
+];
+const MAP_FIELDS = [
+	"scripts",
+	"dependencies",
+	"devDependencies",
+	"peerDependencies",
+	"optionalDependencies"
+];
+/** A plain object's string-valued entries; `undefined` for anything that isn't a plain object. */
+function stringMap(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string"));
+}
+/**
+* Parses `package.json` text. Returns `undefined` for anything that isn't a
+* JSON object — invalid JSON, or valid JSON of another type (an array, `null`,
+* a string) — rather than throwing. A leading byte-order mark is ignored, as
+* npm does.
+*
+* The fields {@link PackageJson} types are checked, so the result honours its
+* type: a recognized field of the wrong type (a numeric `name`, an array
+* `dependencies`) is left out, and the string-map fields keep only their
+* string-valued entries. Every other field passes through untouched.
+*/
+function parsePackageJson(text) {
+	let value;
+	try {
+		value = JSON.parse(text.charCodeAt(0) === 65279 ? text.slice(1) : text);
+	} catch {
+		return;
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	const raw = value;
+	const pkg = { ...raw };
+	for (const field of STRING_FIELDS) if (typeof raw[field] !== "string") delete pkg[field];
+	if (typeof raw["private"] !== "boolean") delete pkg["private"];
+	for (const field of MAP_FIELDS) {
+		const map = stringMap(raw[field]);
+		if (map) pkg[field] = map;
+		else delete pkg[field];
+	}
+	return pkg;
+}
+//#endregion
+//#region src/detect-package-manager.ts
+const MANAGERS = [
+	"pnpm",
+	"npm",
+	"yarn",
+	"bun"
+];
+/** Checked in this order; the first lockfile present wins. */
+const LOCKFILES = [
+	["pnpm-lock.yaml", "pnpm"],
+	["bun.lockb", "bun"],
+	["bun.lock", "bun"],
+	["yarn.lock", "yarn"],
+	["npm-shrinkwrap.json", "npm"],
+	["package-lock.json", "npm"]
+];
+/**
+* The package manager `dir` uses: the name in `package.json#packageManager`
+* (`pnpm@10.0.0` → `pnpm`) when it's one of pnpm, npm, yarn or bun, else the
+* first lockfile found, else `options.fallback`.
+*/
+function detectPackageManager(dir, options = {}) {
+	const read = options.readFile ?? ((path) => readFileSync(path, "utf8"));
+	const exists = options.fileExists ?? existsSync;
+	let declared;
+	try {
+		const field = parsePackageJson(read(join(dir, "package.json")))?.packageManager;
+		declared = typeof field === "string" ? field.split("@")[0] : void 0;
+	} catch {}
+	if (declared && MANAGERS.includes(declared)) return declared;
+	for (const [file, manager] of LOCKFILES) if (exists(join(dir, file))) return manager;
+	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,
+* unreadable or not a JSON object.
+*/
+async function readPackageJson(dir) {
+	try {
+		return parsePackageJson(await readFile(join(dir, "package.json"), "utf8"));
+	} catch {
+		return;
+	}
+}
+/** Synchronous twin of {@link readPackageJson}, with an injectable `readFile`. */
+function readPackageJsonSync(dir, options = {}) {
+	const read = options.readFile ?? ((path) => readFileSync(path, "utf8"));
+	try {
+		return parsePackageJson(read(join(dir, "package.json")));
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { dependencyNames, detectPackageManager, listWorkspacePackagesSync, parsePackageJson, readPackageJson, readPackageJsonSync };

package/package.json

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