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

package/README.md

@@ -76,6 +76,18 @@ const names = discoverWorkspacePackages(repoRoot, { group: "clients" }).map((p)
 
 `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

@@ -135,6 +135,54 @@ export declare function resolveWorkspaceGlobs(repoRoot: string, options?: Pick<D
  * 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,126 @@ 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
@@ -170,7 +290,7 @@ function listWorkspacePackagesSync(repoRoot, options = {}) {
 */
 function readWorkspaceGlobs(workspaceYaml) {
 	const lines = workspaceYaml.split("\n");
-	const start = lines.findIndex((line) => /^packages:\s*(#.*)?$/.test(line));
+	const start = lines.findIndex((line) => PACKAGES_KEY.test(line));
 	const globs = {
 		include: [],
 		exclude: []
@@ -305,4 +425,4 @@ function readPackageJsonSync(dir, options = {}) {
 		return;
 	}
 }
-export { DEFAULT_WORKSPACE_ROOTS, dependencyNames, detectPackageManager, discoverWorkspacePackages, listWorkspacePackagesSync, parsePackageJson, readPackageJson, readPackageJsonSync, readWorkspaceGlobs, resolveWorkspaceGlobs };
+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.2",
+  "version": "1.16.1-alpha.3",
   "description": "Read package.json, list its dependencies and detect the package manager.",
   "keywords": [
     "package.json",
@@ -41,9 +41,9 @@
     "tsdown": "^0.23.3",
     "typescript": "^5.9.3",
     "vitest": "^5.0.5",
-    "@theholocron/eslint-config": "^8.9.0-alpha.3",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.3",
     "@theholocron/vitest-config": "^8.9.0-alpha.3",
-    "@theholocron/tsdown-config": "^8.9.0-alpha.3"
+    "@theholocron/eslint-config": "^8.9.0-alpha.3"
   },
   "engines": {
     "node": ">=22"