@theholocron/pkg-utils 1.16.1-alpha.1 → 1.16.1-alpha.2

package/README.md

@@ -62,6 +62,20 @@ import { listWorkspacePackagesSync } from "@theholocron/pkg-utils";
 const publishable = listWorkspacePackagesSync(repoRoot).filter((p) => !p.manifest.private && p.name);
 ```
 
+### `discoverWorkspacePackages(repoRoot, options?)`
+
+Every package the repo's `pnpm-workspace.yaml` declares, as `listWorkspacePackagesSync()` entries — in glob order, packages within a `<dir>/*` glob sorted by name. Two glob forms are understood: `<dir>/*` (each child of `<dir>` with a `package.json`) and a literal directory (that directory is the package). `!pattern` entries drop matching packages, the repo root (`.`) is skipped, and any other glob throws. Without a `pnpm-workspace.yaml`, or one with no `packages:`, `DEFAULT_WORKSPACE_ROOTS` (`packages`, `apps`, `plugins`) are scanned. `options.group` keeps one version group's folder, `options.excludeGroups` leaves some out, and `options.readText`, `options.readFile` and `options.listDirs` replace the disk access.
+
+```typescript
+import { discoverWorkspacePackages } from "@theholocron/pkg-utils";
+
+const names = discoverWorkspacePackages(repoRoot, { group: "clients" }).map((p) => p.name);
+```
+
+### `resolveWorkspaceGlobs(repoRoot, options?)` and `readWorkspaceGlobs(yaml)`
+
+`readWorkspaceGlobs` reads the `packages:` list of a `pnpm-workspace.yaml` text into `{ include, exclude }` (a line-based read, not a YAML parse; quotes and trailing comments are stripped). `resolveWorkspaceGlobs` reads the file in `repoRoot` and falls back to the default roots as `<root>/*` when it lists none.
+
 ### `PackageJson`
 
 The fields these helpers read, typed; any other field passes through untyped.

package/dist/index.d.mts

@@ -66,6 +66,63 @@ export interface ListWorkspacePackagesOptions {
  * `readPackageJson` instead.
  */
 export declare function listWorkspacePackagesSync(repoRoot: string, options?: ListWorkspacePackagesOptions): WorkspacePackageEntry[];
+/** The `packages:` entries of a `pnpm-workspace.yaml`, split by whether they include or exclude (`!pattern`) packages. */
+export interface WorkspaceGlobs {
+  include: string[];
+  exclude: string[];
+}
+/**
+ * The `packages:` list of a `pnpm-workspace.yaml`. A line-based read of the
+ * plain block-list form, not a YAML parse -- the same approach (and for the
+ * same reason) as `ensureRootWorkspaceMember()`: the file routinely carries a
+ * `catalog:`/`catalogs:`/`overrides:` block after `packages:` that nothing
+ * here should have to round-trip. Quotes and trailing comments are stripped;
+ * a missing `packages:` key, or the inline `packages: [a, b]` form, reads as no
+ * globs (callers fall back to the default roots).
+ */
+export declare function readWorkspaceGlobs(workspaceYaml: string): WorkspaceGlobs;
+/** Where packages live when there is no `pnpm-workspace.yaml` (or it lists none): the layout before globs were read. */
+export declare const DEFAULT_WORKSPACE_ROOTS: readonly string[];
+export interface DiscoverWorkspacePackagesOptions extends Pick<ListWorkspacePackagesOptions, "listDirs" | "readFile"> {
+  /** Replaces the read of `pnpm-workspace.yaml`. Throw (`ENOENT`) when it is absent -- or leave it out to read the real file. */
+  readText?: (path: string) => string;
+  /**
+   * Only the packages of one version group: a folder of the repo (`clients`,
+   * `observability`). A package belongs when it is that folder or sits under it.
+   */
+  group?: string;
+  /**
+   * Leave out the packages of these version groups. A repo that releases some folders on
+   * their own line releases everything else together, and that release must not sweep the
+   * independent groups in.
+   */
+  excludeGroups?: readonly string[];
+}
+/**
+ * Every package the repo's `pnpm-workspace.yaml` declares, as
+ * `listWorkspacePackagesSync()` entries -- in glob order, packages within a
+ * `<dir>/*` glob sorted by name. Two forms of glob are understood:
+ *
+ * - `<dir>/*`: each child of `<dir>` that has a `package.json` (`clients/*`).
+ * - a literal directory: that directory is the package (`observability`,
+ *   `docs/theme`).
+ *
+ * `!pattern` entries drop matching packages. The repo root (`.`) is not a
+ * workspace child and is skipped; callers that treat a root-only repo as a
+ * single package read the root manifest themselves. Any other glob throws
+ * rather than being silently skipped. Without a `pnpm-workspace.yaml`, or one
+ * with no `packages:`, the default roots are scanned.
+ *
+ * Nothing is filtered by `name`, `version` or `private`; that is the caller's
+ * call, as for `listWorkspacePackagesSync()`.
+ */
+export declare function discoverWorkspacePackages(repoRoot: string, options?: DiscoverWorkspacePackagesOptions): WorkspacePackageEntry[];
+/**
+ * The globs {@link discoverWorkspacePackages} scans: the repo's
+ * `pnpm-workspace.yaml` `packages:` list, or the {@link DEFAULT_WORKSPACE_ROOTS}
+ * as `<root>/*` when there is no such file or it lists none.
+ */
+export declare function resolveWorkspaceGlobs(repoRoot: string, options?: Pick<DiscoverWorkspacePackagesOptions, "readText">): WorkspaceGlobs;
 /**
  * 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`,

package/dist/index.mjs

@@ -158,6 +158,132 @@ function listWorkspacePackagesSync(repoRoot, options = {}) {
 	}
 	return entries;
 }
+// src/workspace-globs.ts
+/**
+* The `packages:` list of a `pnpm-workspace.yaml`. A line-based read of the
+* plain block-list form, not a YAML parse -- the same approach (and for the
+* same reason) as `ensureRootWorkspaceMember()`: the file routinely carries a
+* `catalog:`/`catalogs:`/`overrides:` block after `packages:` that nothing
+* here should have to round-trip. Quotes and trailing comments are stripped;
+* a missing `packages:` key, or the inline `packages: [a, b]` form, reads as no
+* globs (callers fall back to the default roots).
+*/
+function readWorkspaceGlobs(workspaceYaml) {
+	const lines = workspaceYaml.split("\n");
+	const start = lines.findIndex((line) => /^packages:\s*(#.*)?$/.test(line));
+	const globs = {
+		include: [],
+		exclude: []
+	};
+	if (start === -1) return globs;
+	for (const line of lines.slice(start + 1)) {
+		if (line.trim() === "" || /^\s*#/.test(line)) continue;
+		const item = /^\s*-\s*(.*)$/.exec(line);
+		if (!item) break;
+		const value = item[1].replace(/(^|\s)#.*$/, "").trim().replace(/^["']|["']$/g, "").trim();
+		if (value === "") continue;
+		if (value.startsWith("!")) globs.exclude.push(normalizeGlob(value.slice(1)));
+		else globs.include.push(normalizeGlob(value));
+	}
+	return globs;
+}
+/** `./a/b/` -> `a/b`: the form {@link discoverWorkspacePackages} matches against `relativeDir`. */
+function normalizeGlob(glob) {
+	return glob.replace(/^\.\//, "").replace(/\/+$/, "");
+}
+// src/discover-workspace-packages.ts
+/** Where packages live when there is no `pnpm-workspace.yaml` (or it lists none): the layout before globs were read. */
+const DEFAULT_WORKSPACE_ROOTS = [
+	"packages",
+	"apps",
+	"plugins"
+];
+/** Characters pnpm globs treat specially. A literal directory has none of them. */
+const GLOB_CHARS = /[*?[\]{}!]/;
+/**
+* Every package the repo's `pnpm-workspace.yaml` declares, as
+* `listWorkspacePackagesSync()` entries -- in glob order, packages within a
+* `<dir>/*` glob sorted by name. Two forms of glob are understood:
+*
+* - `<dir>/*`: each child of `<dir>` that has a `package.json` (`clients/*`).
+* - a literal directory: that directory is the package (`observability`,
+*   `docs/theme`).
+*
+* `!pattern` entries drop matching packages. The repo root (`.`) is not a
+* workspace child and is skipped; callers that treat a root-only repo as a
+* single package read the root manifest themselves. Any other glob throws
+* rather than being silently skipped. Without a `pnpm-workspace.yaml`, or one
+* with no `packages:`, the default roots are scanned.
+*
+* Nothing is filtered by `name`, `version` or `private`; that is the caller's
+* call, as for `listWorkspacePackagesSync()`.
+*/
+function discoverWorkspacePackages(repoRoot, options = {}) {
+	const base = resolve(repoRoot);
+	const readFile = options.readFile ?? ((path) => readFileSync(path, "utf8"));
+	const { include, exclude } = resolveWorkspaceGlobs(base, options);
+	const entries = /* @__PURE__ */ new Map();
+	for (const glob of include) {
+		if (glob === "." || glob === "") continue;
+		for (const entry of expandGlob(base, glob, {
+			readFile,
+			listDirs: options.listDirs
+		})) if (!exclude.some((pattern) => matches(entry.relativeDir, pattern))) entries.set(entry.relativeDir, entry);
+	}
+	const { group, excludeGroups = [] } = options;
+	return [...entries.values()].filter(({ relativeDir }) => (group === void 0 || inGroup(relativeDir, group)) && !excludeGroups.some((excluded) => inGroup(relativeDir, excluded)));
+}
+/** `relativeDir` is the group's folder, or is under it. `clients` holds `clients/http`, not `clients-old/x`. */
+function inGroup(relativeDir, group) {
+	const folder = group.replace(/^\.\//, "").replace(/\/+$/, "");
+	return relativeDir === folder || relativeDir.startsWith(`${folder}/`);
+}
+/**
+* The globs {@link discoverWorkspacePackages} scans: the repo's
+* `pnpm-workspace.yaml` `packages:` list, or the {@link DEFAULT_WORKSPACE_ROOTS}
+* as `<root>/*` when there is no such file or it lists none.
+*/
+function resolveWorkspaceGlobs(repoRoot, options = {}) {
+	const readText = options.readText ?? ((path) => readFileSync(path, "utf8"));
+	let workspaceYaml = "";
+	try {
+		workspaceYaml = readText(join(resolve(repoRoot), "pnpm-workspace.yaml"));
+	} catch {}
+	const { include, exclude } = readWorkspaceGlobs(workspaceYaml);
+	return {
+		include: include.length > 0 ? include : DEFAULT_WORKSPACE_ROOTS.map((root) => `${root}/*`),
+		exclude
+	};
+}
+function expandGlob(base, glob, options) {
+	if (glob.endsWith("/*") && !GLOB_CHARS.test(glob.slice(0, -2))) return listWorkspacePackagesSync(base, {
+		...options,
+		roots: [glob.slice(0, -2)]
+	});
+	if (GLOB_CHARS.test(glob)) throw new TypeError(`unsupported workspace pattern ${JSON.stringify(glob)}: only "<dir>/*" and literal directories are supported`);
+	const rel = relative(base, resolve(base, glob));
+	if (isAbsolute(glob) || rel === ".." || rel.startsWith(`..${sep}`)) throw new TypeError(`workspace directory must be inside the repo, got ${JSON.stringify(glob)}`);
+	const dir = join(base, glob);
+	try {
+		const manifest = parsePackageJson(options.readFile(join(dir, "package.json")));
+		return manifest ? [{
+			name: manifest.name,
+			dir,
+			relativeDir: glob,
+			manifest
+		}] : [];
+	} catch {
+		return [];
+	}
+}
+/** `relativeDir` against an exclusion: the same directory, or a child of `<dir>/*`. */
+function matches(relativeDir, pattern) {
+	if (pattern.endsWith("/*")) {
+		const parent = pattern.slice(0, -2);
+		return relativeDir.startsWith(`${parent}/`) && !relativeDir.slice(parent.length + 1).includes("/");
+	}
+	return relativeDir === pattern;
+}
 // src/read-package-json.ts
 /**
 * The parsed `<dir>/package.json`, or `undefined` when it is missing,
@@ -179,4 +305,4 @@ function readPackageJsonSync(dir, options = {}) {
 		return;
 	}
 }
-export { dependencyNames, detectPackageManager, listWorkspacePackagesSync, parsePackageJson, readPackageJson, readPackageJsonSync };
+export { DEFAULT_WORKSPACE_ROOTS, dependencyNames, detectPackageManager, discoverWorkspacePackages, listWorkspacePackagesSync, parsePackageJson, readPackageJson, readPackageJsonSync, readWorkspaceGlobs, resolveWorkspaceGlobs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/pkg-utils",
-  "version": "1.16.1-alpha.1",
+  "version": "1.16.1-alpha.2",
   "description": "Read package.json, list its dependencies and detect the package manager.",
   "keywords": [
     "package.json",
@@ -31,9 +31,6 @@
     "dist"
   ],
   "devDependencies": {
-    "@theholocron/eslint-config": "^8.8.2",
-    "@theholocron/tsdown-config": "^8.8.2",
-    "@theholocron/vitest-config": "^8.8.2",
     "@tsconfig/node-lts": "^24.0.1",
     "@types/node": "^26",
     "@vitest/coverage-v8": "^5.0.5",
@@ -43,7 +40,10 @@
     "globals": "^17.11.0",
     "tsdown": "^0.23.3",
     "typescript": "^5.9.3",
-    "vitest": "^5.0.5"
+    "vitest": "^5.0.5",
+    "@theholocron/eslint-config": "^8.9.0-alpha.3",
+    "@theholocron/vitest-config": "^8.9.0-alpha.3",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.3"
   },
   "engines": {
     "node": ">=22"