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

package/README.md

@@ -62,6 +62,32 @@ 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.
+
+### `parseCatalogs(text)`
+
+The `catalog:` and `catalogs:` blocks of a `pnpm-workspace.yaml` as `{ default: {...}, <name>: {...} }`, package name to range. A line-based read of the flat format pnpm writes; entries outside a catalog are ignored.
+
+### `addWorkspaceMember(workspaceYaml, member)`
+
+Adds `member` (for example `"."`) as the first quoted entry of the `packages:` list and returns `{ content, changed }`. A line-based edit that only adds a line, so the `catalog:` and `overrides:` blocks after it keep their formatting. Nothing changes when the member is already listed, or when there is no plain block-list `packages:`.
+
+### `bumpCatalogPins(content, fetchLatest, options?)`
+
+Rewrites the pins of every catalog entry to the latest version `fetchLatest(name)` returns, keeping the range prefix (`^`, `~`) and the quoting. It never downgrades, leaves a package with no answer alone, and asks once per package. `options.include` limits which packages are looked up. Returns `{ content, bumps }`. `gt(a, b)` is the comparison it uses for `x.y.z` release versions.
+
 ### `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`,
@@ -78,6 +135,54 @@ export declare function listWorkspacePackagesSync(repoRoot: string, options?: Li
  * string-valued entries. Every other field passes through untouched.
  */
 export declare function parsePackageJson(text: string): PackageJson | undefined;
+/** The `catalog:` and `catalogs:` of a `pnpm-workspace.yaml`: the default one under `default`, the named ones under their names. */
+export type Catalogs = Record<string, Record<string, string>>;
+/** The `packages:` key of a `pnpm-workspace.yaml`, as a line. */
+export declare const PACKAGES_KEY: RegExp;
+/** What an edit of a `pnpm-workspace.yaml` gives back: the new text, and whether it differs from what was passed in. */
+export interface WorkspaceYamlEdit {
+  /** The file's text after the edit; the text passed in when nothing changed. */
+  content: string;
+  /** Whether `content` differs from the text passed in. */
+  changed: boolean;
+}
+/** A catalog pin rewritten by {@link bumpCatalogPins}. */
+export interface CatalogBump {
+  /** The package whose pin was rewritten. */
+  pkg: string;
+  /** The version it was pinned to. */
+  from: string;
+  /** The version it is pinned to now. */
+  to: string;
+}
+/** Resolves a package's latest published version, or `null` when there is no answer. */
+export type FetchLatest = (pkg: string) => Promise<string | null>;
+/** What {@link bumpCatalogPins} may be told. */
+export interface BumpCatalogPinsOptions {
+  /** Which pinned packages to look up. Default: all of them. */
+  include?: (pkg: string) => boolean;
+}
+/** Parse the `catalog:` and `catalogs:` blocks of `pnpm-workspace.yaml` (the generated, flat format). */
+export declare function parseCatalogs(text: string): Catalogs;
+/**
+ * Add `member` as the first entry of the `packages:` list, unless the list already has it. A targeted
+ * line-based edit, not a YAML round-trip: the file routinely carries a `catalog:`/`catalogs:`/`overrides:`
+ * block after `packages:`, and a parser would reformat content nobody asked to touch. It only ever adds a
+ * line, quoted like `"docs"`, and changes nothing when there is no `packages:` key or it is not the plain
+ * block-list form.
+ */
+export declare function addWorkspaceMember(workspaceYaml: string, member: string): WorkspaceYamlEdit;
+/** `a > b` for `x.y.z` release versions (prerelease tags are ignored). */
+export declare function gt(a: string, b: string): boolean;
+/**
+ * Rewrite the pins of the `catalog:` and every named `catalogs.*` entry to the latest published version,
+ * keeping the range prefix (`^`, `~`). Never downgrades; a package with no answer from `fetchLatest` is left
+ * alone. `fetchLatest` is called once per package.
+ */
+export declare function bumpCatalogPins(content: string, fetchLatest: FetchLatest, options?: BumpCatalogPinsOptions): Promise<{
+  content: string;
+  bumps: CatalogBump[];
+}>;
 export interface ReadPackageJsonOptions {
   /** Replaces the file read — for callers with an injected or in-memory filesystem. */
   readFile?: (path: string) => string;

package/dist/index.mjs

@@ -158,6 +158,252 @@ function listWorkspacePackagesSync(repoRoot, options = {}) {
 	}
 	return entries;
 }
+// src/pnpm-workspace.ts
+/** The `packages:` key of a `pnpm-workspace.yaml`, as a line. */
+const PACKAGES_KEY = /^packages:\s*(#.*)?$/;
+/** Parse the `catalog:` and `catalogs:` blocks of `pnpm-workspace.yaml` (the generated, flat format). */
+function parseCatalogs(text) {
+	const catalogs = { default: {} };
+	let current = null;
+	let inCatalogs = false;
+	for (const raw of text.split("\n")) {
+		if (raw.trim() === "" || raw.trimStart().startsWith("#")) continue;
+		if (/^catalog:\s*$/.test(raw)) {
+			current = "default";
+			inCatalogs = false;
+			continue;
+		}
+		if (/^catalogs:\s*$/.test(raw)) {
+			current = null;
+			inCatalogs = true;
+			continue;
+		}
+		if (/^\S/.test(raw)) {
+			current = null;
+			inCatalogs = false;
+			continue;
+		}
+		const named = inCatalogs ? raw.match(/^ {2}([A-Za-z0-9_-]+):\s*$/) : null;
+		if (named?.[1]) {
+			current = named[1];
+			catalogs[current] ??= {};
+			continue;
+		}
+		const entry = raw.match(/^\s+("[^"]+"|[^\s:][^:]*?):\s*(.+?)\s*$/);
+		if (entry?.[1] && entry[2] && current) (catalogs[current] ??= {})[entry[1].replace(/^"|"$/g, "")] = entry[2].replace(/^"|"$/g, "");
+	}
+	return catalogs;
+}
+/**
+* Add `member` as the first entry of the `packages:` list, unless the list already has it. A targeted
+* line-based edit, not a YAML round-trip: the file routinely carries a `catalog:`/`catalogs:`/`overrides:`
+* block after `packages:`, and a parser would reformat content nobody asked to touch. It only ever adds a
+* line, quoted like `"docs"`, and changes nothing when there is no `packages:` key or it is not the plain
+* block-list form.
+*/
+function addWorkspaceMember(workspaceYaml, member) {
+	const lines = workspaceYaml.split("\n");
+	const packagesLineIdx = lines.findIndex((l) => PACKAGES_KEY.test(l));
+	if (packagesLineIdx === -1) return {
+		content: workspaceYaml,
+		changed: false
+	};
+	const items = [];
+	let cursor = packagesLineIdx + 1;
+	while (cursor < lines.length && /^\s*-\s*/.test(lines[cursor])) {
+		items.push(lines[cursor]);
+		cursor++;
+	}
+	if (items.some((item) => {
+		const value = item.replace(/^\s*-\s*/, "").replace(/^["']|["']$/g, "").trim();
+		return value === member || member === "." && value === "";
+	})) return {
+		content: workspaceYaml,
+		changed: false
+	};
+	const indent = items[0]?.match(/^(\s*-\s*)/)?.[1] ?? "  - ";
+	return {
+		content: [
+			...lines.slice(0, packagesLineIdx + 1),
+			`${indent}"${member}"`,
+			...lines.slice(packagesLineIdx + 1)
+		].join("\n"),
+		changed: true
+	};
+}
+/** `a > b` for `x.y.z` release versions (prerelease tags are ignored). */
+function gt(a, b) {
+	const pa = a.split(".").map((n) => parseInt(n, 10));
+	const pb = b.split(".").map((n) => parseInt(n, 10));
+	for (let i = 0; i < 3; i++) {
+		const x = pa[i] ?? 0;
+		const y = pb[i] ?? 0;
+		if (x !== y) return x > y;
+	}
+	return false;
+}
+const CATALOG_LINE = /^(\s*['"]?)((?:@[a-z0-9._-]+\/)?[a-z0-9._-]+)(['"]?\s*:\s*['"]?)([~^]?)(\d+\.\d+\.\d+[\w.-]*)(['"]?\s*)$/;
+/**
+* Rewrite the pins of the `catalog:` and every named `catalogs.*` entry to the latest published version,
+* keeping the range prefix (`^`, `~`). Never downgrades; a package with no answer from `fetchLatest` is left
+* alone. `fetchLatest` is called once per package.
+*/
+async function bumpCatalogPins(content, fetchLatest, options = {}) {
+	const include = options.include ?? (() => true);
+	const lines = content.split("\n");
+	const wanted = /* @__PURE__ */ new Set();
+	for (const line of lines) {
+		const m = CATALOG_LINE.exec(line);
+		if (m && include(m[2])) wanted.add(m[2]);
+	}
+	const latest = /* @__PURE__ */ new Map();
+	await Promise.all([...wanted].map(async (pkg) => {
+		latest.set(pkg, await fetchLatest(pkg));
+	}));
+	const bumps = [];
+	return {
+		content: lines.map((line) => {
+			const m = CATALOG_LINE.exec(line);
+			if (!m) return line;
+			const [, pre, pkg, mid, prefix, current, post] = m;
+			const next = latest.get(pkg);
+			if (!next || next === current || !gt(next, current)) return line;
+			bumps.push({
+				pkg,
+				from: current,
+				to: next
+			});
+			return `${pre}${pkg}${mid}${prefix}${next}${post}`;
+		}).join("\n"),
+		bumps
+	};
+}
+// 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_KEY.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 +425,4 @@ function readPackageJsonSync(dir, options = {}) {
 		return;
 	}
 }
-export { dependencyNames, detectPackageManager, listWorkspacePackagesSync, parsePackageJson, readPackageJson, readPackageJsonSync };
+export { DEFAULT_WORKSPACE_ROOTS, PACKAGES_KEY, addWorkspaceMember, bumpCatalogPins, dependencyNames, detectPackageManager, discoverWorkspacePackages, gt, listWorkspacePackagesSync, parseCatalogs, 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.3",
   "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/tsdown-config": "^8.9.0-alpha.3",
+    "@theholocron/vitest-config": "^8.9.0-alpha.3",
+    "@theholocron/eslint-config": "^8.9.0-alpha.3"
   },
   "engines": {
     "node": ">=22"