@stealthscale/tool-workspace 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# @stealthscale/tool-workspace
+
+A **kit**: another repository takes it at development time.
+
+Reads a workspace off its manifests. It answers which packages the root names, what each one
+declares, and the order their dependencies put them in, so a release, a guard and a Storybook
+all work from one reading of the tree rather than a list somebody keeps in step.
+
+```ts
+import { dependencyClosure, workspaceManifests, workspaceRoot } from '@stealthscale/tool-workspace'
+
+const root = workspaceRoot(process.cwd())
+const manifests = workspaceManifests(root)
+const { missing, ordered } = dependencyClosure(['@acme/web'], manifests)
+```
+
+`workspaceRoot` walks up until a manifest names workspaces; `packageRoot` walks up until a
+manifest names anything, which is how a module reads its own package's version whatever depth
+it was emitted at. `workspacePatterns` and `expandWorkspacePattern` turn the root's globs into
+directories, and `readManifest` narrows one manifest to the fields the toolchain reads.
+`dependencyClosure` orders a set of roots so a list walked front to back never meets a package
+before what it needs. `Manifest.exports` carries the exports map as written, so a consumer
+that needs one entry of a package reads it off the manifest rather than resolving the package
+by name, which only works from a directory that depends on it.
+
+## What a package registers
+
+`Manifest.contributions` carries a package's `stealth` field exactly as written, unread. A
+consumer reads one kind of contribution out of it by naming the key and handing over the
+schema for what sits under that key:
+
+```ts
+import { contributions, workspaceManifests } from '@stealthscale/tool-workspace'
+import { THEME_CONTRIBUTION, THEME_KEY } from '@stealthscale/core-theme'
+
+const read = contributions(workspaceManifests(root), THEME_KEY, THEME_CONTRIBUTION)
+```
+
+Every package that registered that kind comes back in workspace order, each beside the
+manifest that declared it, so a relative path inside the contribution resolves against the
+package it came from. A field that does not fit the schema is a refusal rather than a throw,
+and every malformed package is reported at once, each issue pointing at
+`@scope/pkg.stealth.theme.title`.
+
+This package knows the field exists and nothing about what a package may put in it. The words
+a theme, an appearance or a set of messages is declared with belong to whatever owns those
+words, and adding a kind of contribution changes nothing here.
+
+## Install
+
+```sh
+bun add -d @stealthscale/tool-workspace
+```

package/dist/index.d.mts

@@ -0,0 +1,185 @@
+import { Collected } from "@stealthscale/core-result";
+import { FieldIssue, SchemaOf } from "@stealthscale/core-schema";
+//#region src/manifests.d.ts
+/**
+ * @fileoverview Reads the manifests of a workspace: which packages the root names, what each
+ * declares, and the order their dependencies put them in. The `stealth` field comes back
+ * unread: this reader carries what a package registers with the toolchain without knowing
+ * what any of it means, and the consumer that owns those words holds the field to a schema.
+ */
+/**
+ * Describes what the tool reads off a package's manifest.
+ */
+interface Manifest {
+  /**
+   * Carries `publishConfig.access`, when the manifest states one. Npm reads it from the
+   * tarball, so the tool never passes it.
+   */
+  access: string | undefined;
+  /**
+   * Maps each command the package installs to the file that runs it. The string form of
+   * `bin` names one command after the package, which is what npm does with it.
+   */
+  bin: Readonly<Record<string, string>>;
+  /**
+   * Carries the `build` script, when the package has one.
+   */
+  build: string | undefined;
+  /**
+   * Carries the `stealth` field as it is written, unread. It is what the package registers
+   * with the toolchain, and the consumer that owns those words parses it. `undefined` means
+   * the package registers nothing.
+   */
+  contributions: unknown;
+  /**
+   * Maps each dependency to its range. A tarball's manifest makes a consumer install these.
+   */
+  dependencies: Readonly<Record<string, string>>;
+  /**
+   * Carries the one line that says what the package is for, when the manifest states it.
+   */
+  description: string | undefined;
+  /**
+   * Names the package's directory, absolute.
+   */
+  directory: string;
+  /**
+   * Carries the `exports` field as it is written, unread. A consumer that needs one entry
+   * reads it from here rather than resolving the package by name, which only works from a
+   * directory that depends on it. `undefined` means the manifest declares none.
+   */
+  exports: unknown;
+  /**
+   * Lists the `files` a tarball carries, when the manifest declares them.
+   */
+  files: readonly string[] | undefined;
+  /**
+   * Names the package.
+   */
+  name: string;
+  /**
+   * Marks a package that refuses to be published.
+   */
+  private: boolean;
+  /**
+   * Carries `publishConfig.registry`, when the manifest states one.
+   */
+  registry: string | undefined;
+  /**
+   * Carries the version.
+   */
+  version: string;
+}
+/**
+ * Describes what the closure of some roots came to.
+ */
+interface Closure {
+  /**
+   * Lists the roots that are not packages in the workspace.
+   */
+  missing: string[];
+  /**
+   * Lists every package reachable from a root, dependencies before their dependents.
+   */
+  ordered: Manifest[];
+}
+/**
+ * Finds the workspace root: the nearest directory, from `start` upwards, whose manifest
+ * names workspaces.
+ *
+ * @param {string} start - The directory to start from, absolute.
+ * @returns {string} The root, absolute.
+ * @throws {Error} When no manifest above `start` names workspaces.
+ */
+declare function workspaceRoot(start: string): string;
+/**
+ * Finds the package a file belongs to: the nearest directory, from `start` upwards, that
+ * holds a manifest. A module reads its own package's version this way, whatever depth the
+ * build emitted it at.
+ *
+ * @param {string} start - The directory to start from, absolute.
+ * @returns {string} The package's directory, absolute.
+ * @throws {Error} When no directory above `start` holds a manifest.
+ */
+declare function packageRoot(start: string): string;
+/**
+ * Reads the workspace patterns the root manifest names, in either form bun accepts.
+ *
+ * @param {string} root - The directory whose manifest names them.
+ * @returns {readonly string[]} The patterns. Empty when the manifest names no workspaces.
+ */
+declare function workspacePatterns(root: string): readonly string[];
+/**
+ * Expands a workspace pattern into the directories it names. A segment is a literal or `*`,
+ * which stands for every subdirectory. A literal that does not exist is still returned, so
+ * the caller decides what a missing directory means.
+ *
+ * @param {string} root - The directory the pattern is relative to.
+ * @param {string} pattern - The pattern: `core/*`, `plugins/*\/*`, `lone`.
+ * @returns {string[]} The directories, absolute.
+ */
+declare function expandWorkspacePattern(root: string, pattern: string): string[];
+/**
+ * Reads a package's manifest from its directory.
+ *
+ * @param {string} directory - The package's directory, absolute.
+ * @returns {Manifest} The fields the tool reads, with the directory beside them.
+ * @throws {Error} When the manifest has no name or no version. Nothing can be packed from it.
+ */
+declare function readManifest(directory: string): Manifest;
+/**
+ * Lists every package in the workspace: each directory a pattern names that holds a
+ * manifest.
+ *
+ * @param {string} root - The directory whose manifest names the patterns.
+ * @returns {Manifest[]} The manifests, in pattern order.
+ */
+declare function workspaceManifests(root: string): Manifest[];
+/**
+ * Collects each root and every workspace package reachable from it through `dependencies`,
+ * dependencies before their dependents, so a list walked front to back never meets a
+ * package before what it needs. A dependency outside the workspace is the registry's
+ * business and stays out.
+ *
+ * @param {readonly string[]} roots - The package names to start from.
+ * @param {readonly Manifest[]} manifests - The workspace's manifests.
+ * @returns {Closure} The ordered closure, and the roots the workspace does not have.
+ */
+declare function dependencyClosure(roots: readonly string[], manifests: readonly Manifest[]): Closure;
+//#endregion
+//#region src/contributions.d.ts
+/**
+ * Holds one package's contribution beside the manifest that declared it.
+ *
+ * @template Value - What the caller's schema parses the contribution to.
+ */
+interface Registered<Value> {
+  /**
+   * Carries the manifest of the package that registered it. Its `directory` is what turns a
+   * path inside the contribution into an absolute one.
+   */
+  manifest: Manifest;
+  /**
+   * Carries the contribution, as the caller's schema parsed it.
+   */
+  value: Value;
+}
+/**
+ * Reads one kind of contribution out of every manifest of a workspace.
+ *
+ * Every malformed field is reported at once rather than the first, because somebody fixing
+ * manifests wants the whole list. A package that registers nothing, or registers only other
+ * kinds, is absent from the result rather than being an entry with nothing in it.
+ *
+ * @template Value - What the schema parses the contribution to.
+ * @param {readonly Manifest[]} manifests - The workspace's manifests, as `workspaceManifests`
+ *     read them. Their order is the result's order.
+ * @param {string} key - The key inside the `stealth` field: `theme`, `appearance`, `messages`.
+ * @param {SchemaOf<Value>} schema - The schema for what sits under that key. It belongs to the
+ *     package that owns those words.
+ * @returns {Collected<Registered<Value>, FieldIssue>} Every package that registered this kind,
+ *     in workspace order, or every refusal with the package on each path.
+ */
+declare function contributions<Value>(manifests: readonly Manifest[], key: string, schema: SchemaOf<Value>): Collected<Registered<Value>, FieldIssue>;
+//#endregion
+export { type Closure, type Manifest, type Registered, contributions, dependencyClosure, expandWorkspacePattern, packageRoot, readManifest, workspaceManifests, workspacePatterns, workspaceRoot };

package/dist/index.mjs

@@ -0,0 +1,286 @@
+import { collect, refused, succeeded } from "@stealthscale/core-result";
+import { array, boolean, looseObject, optional, record, safeParse, string, union, unknown } from "@stealthscale/core-schema";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+//#region src/manifests.ts
+/**
+* @fileoverview Reads the manifests of a workspace: which packages the root names, what each
+* declares, and the order their dependencies put them in. The `stealth` field comes back
+* unread: this reader carries what a package registers with the toolchain without knowing
+* what any of it means, and the consumer that owns those words holds the field to a schema.
+*/
+/**
+* Accepts what npm reads off `publishConfig` when it publishes: the access and the registry.
+*/
+const PUBLISH_CONFIG = looseObject({
+	access: optional(string()),
+	registry: optional(string())
+});
+/**
+* Accepts `workspaces` in either form bun reads: a list of patterns, or an object naming them.
+*/
+const WORKSPACES = union([array(string()), looseObject({ packages: optional(array(string())) })]);
+/**
+* Accepts a manifest as it is on disk, in the fields the tool reads. Anything else passes
+* through unread.
+*/
+const RAW_MANIFEST = looseObject({
+	bin: optional(union([record(string(), string()), string()])),
+	dependencies: optional(record(string(), string())),
+	description: optional(string()),
+	exports: optional(unknown()),
+	files: optional(array(string())),
+	name: optional(string()),
+	private: optional(boolean()),
+	publishConfig: optional(PUBLISH_CONFIG),
+	scripts: optional(record(string(), string())),
+	stealth: optional(unknown()),
+	version: optional(string()),
+	workspaces: optional(WORKSPACES)
+});
+/**
+* Parses one manifest file.
+*
+* @param {string} file - The manifest's path.
+* @returns {RawManifest} The manifest as written.
+* @throws {Error} When the file is not a manifest: a field the tool reads has the wrong shape.
+*/
+function read(file) {
+	const result = safeParse(RAW_MANIFEST, JSON.parse(readFileSync(file, "utf8")));
+	if (result.ok) return result.value;
+	const reasons = result.failure.map((issue) => `${issue.path}: ${issue.reason}`).join("; ");
+	throw new Error(`${file} is not a manifest: ${reasons}`);
+}
+/**
+* Reads the commands a manifest installs. Npm names the one command of the string form
+* after the package, without its scope.
+*
+* @param {string} name - The package's name, scope and all.
+* @param {Readonly<Record<string, string>> | string} [bin] - The manifest's `bin`. Default:
+*     nothing, giving a package that installs no command.
+* @returns {Readonly<Record<string, string>>} Each command mapped to the file that runs it.
+*/
+function binOf(name, bin) {
+	if (bin === void 0) return {};
+	if (typeof bin === "string") return { [name.slice(name.indexOf("/") + 1)]: bin };
+	return bin;
+}
+/**
+* Finds the workspace root: the nearest directory, from `start` upwards, whose manifest
+* names workspaces.
+*
+* @param {string} start - The directory to start from, absolute.
+* @returns {string} The root, absolute.
+* @throws {Error} When no manifest above `start` names workspaces.
+*/
+function workspaceRoot(start) {
+	let directory = start;
+	while (true) {
+		const file = join(directory, "package.json");
+		if (existsSync(file) && read(file).workspaces !== void 0) return directory;
+		const parent = dirname(directory);
+		if (parent === directory) throw new Error(`No manifest above ${start} names workspaces`);
+		directory = parent;
+	}
+}
+/**
+* Finds the package a file belongs to: the nearest directory, from `start` upwards, that
+* holds a manifest. A module reads its own package's version this way, whatever depth the
+* build emitted it at.
+*
+* @param {string} start - The directory to start from, absolute.
+* @returns {string} The package's directory, absolute.
+* @throws {Error} When no directory above `start` holds a manifest.
+*/
+function packageRoot(start) {
+	let directory = start;
+	while (true) {
+		if (existsSync(join(directory, "package.json"))) return directory;
+		const parent = dirname(directory);
+		if (parent === directory) throw new Error(`No directory above ${start} holds a manifest`);
+		directory = parent;
+	}
+}
+/**
+* Reads the workspace patterns the root manifest names, in either form bun accepts.
+*
+* @param {string} root - The directory whose manifest names them.
+* @returns {readonly string[]} The patterns. Empty when the manifest names no workspaces.
+*/
+function workspacePatterns(root) {
+	const { workspaces } = read(join(root, "package.json"));
+	if (Array.isArray(workspaces)) return workspaces;
+	return workspaces?.packages ?? [];
+}
+/**
+* Lists the subdirectories of a directory.
+*
+* @param {string} directory - The directory to list.
+* @returns {string[]} The names, sorted. Empty when the directory does not exist.
+*/
+function subdirectories(directory) {
+	if (!existsSync(directory)) return [];
+	return readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).toSorted();
+}
+/**
+* Expands a workspace pattern into the directories it names. A segment is a literal or `*`,
+* which stands for every subdirectory. A literal that does not exist is still returned, so
+* the caller decides what a missing directory means.
+*
+* @param {string} root - The directory the pattern is relative to.
+* @param {string} pattern - The pattern: `core/*`, `plugins/*\/*`, `lone`.
+* @returns {string[]} The directories, absolute.
+*/
+function expandWorkspacePattern(root, pattern) {
+	return pattern.split("/").reduce((directories, segment) => directories.flatMap((directory) => segment === "*" ? subdirectories(directory).map((name) => join(directory, name)) : [join(directory, segment)]), [root]);
+}
+/**
+* Reads a package's manifest from its directory.
+*
+* @param {string} directory - The package's directory, absolute.
+* @returns {Manifest} The fields the tool reads, with the directory beside them.
+* @throws {Error} When the manifest has no name or no version. Nothing can be packed from it.
+*/
+function readManifest(directory) {
+	const raw = read(join(directory, "package.json"));
+	if (raw.name === void 0 || raw.version === void 0) throw new Error(`${join(directory, "package.json")} has no name or no version`);
+	return {
+		access: raw.publishConfig?.access,
+		bin: binOf(raw.name, raw.bin),
+		build: raw.scripts?.["build"],
+		contributions: raw.stealth,
+		dependencies: raw.dependencies ?? {},
+		description: raw.description,
+		directory,
+		exports: raw.exports,
+		files: raw.files,
+		name: raw.name,
+		private: raw.private === true,
+		registry: raw.publishConfig?.registry,
+		version: raw.version
+	};
+}
+/**
+* Lists every package in the workspace: each directory a pattern names that holds a
+* manifest.
+*
+* @param {string} root - The directory whose manifest names the patterns.
+* @returns {Manifest[]} The manifests, in pattern order.
+*/
+function workspaceManifests(root) {
+	return workspacePatterns(root).flatMap((pattern) => expandWorkspacePattern(root, pattern)).filter((directory) => existsSync(join(directory, "package.json"))).map((directory) => readManifest(directory));
+}
+/**
+* Collects each root and every workspace package reachable from it through `dependencies`,
+* dependencies before their dependents, so a list walked front to back never meets a
+* package before what it needs. A dependency outside the workspace is the registry's
+* business and stays out.
+*
+* @param {readonly string[]} roots - The package names to start from.
+* @param {readonly Manifest[]} manifests - The workspace's manifests.
+* @returns {Closure} The ordered closure, and the roots the workspace does not have.
+*/
+function dependencyClosure(roots, manifests) {
+	const byName = new Map(manifests.map((manifest) => [manifest.name, manifest]));
+	const found = {
+		missing: [],
+		ordered: []
+	};
+	const seen = /* @__PURE__ */ new Set();
+	/**
+	* Adds a package after everything it depends on, once.
+	*
+	* @param {Manifest} manifest - The package to add.
+	*/
+	const visit = (manifest) => {
+		if (seen.has(manifest.name)) return;
+		seen.add(manifest.name);
+		for (const name of Object.keys(manifest.dependencies)) {
+			const dependency = byName.get(name);
+			if (dependency !== void 0) visit(dependency);
+		}
+		found.ordered.push(manifest);
+	};
+	for (const root of roots) {
+		const manifest = byName.get(root);
+		if (manifest === void 0) found.missing.push(root);
+		else visit(manifest);
+	}
+	return found;
+}
+//#endregion
+//#region src/contributions.ts
+/**
+* @fileoverview Reads one kind of contribution out of the `stealth` field of every manifest.
+* The caller names the key and hands over the schema for what it expects under it, so nothing
+* here learns what a theme, an appearance or a set of words is: it finds the field, checks it is
+* an object, and holds one key of it to somebody else's schema. A kind of contribution is
+* therefore added by the package that owns those words, and this module does not change.
+*/
+/**
+* Accepts the `stealth` field itself: an object keyed by the kind of contribution. Every
+* value stays unread, because the caller's schema reads the one key it asked for.
+*/
+const FIELD = record(string(), unknown());
+/**
+* Points every issue at the field inside the package that wrote it, so a reading of the whole
+* workspace names both the package and the field.
+*
+* @param {readonly FieldIssue[]} issues - The refusals a schema reported.
+* @param {string} prefix - The path of the field being read: `@scope/pkg.stealth.theme`.
+* @returns {FieldIssue[]} The same refusals, each path prefixed. An issue on the field itself
+*     carries the prefix alone.
+*/
+function prefixed(issues, prefix) {
+	return issues.map((issue) => ({
+		...issue,
+		path: issue.path === "" ? prefix : `${prefix}.${issue.path}`
+	}));
+}
+/**
+* Reads one package's contribution of one kind.
+*
+* @template Value - What the schema parses the contribution to.
+* @param {Manifest} manifest - The package's manifest.
+* @param {string} key - The key inside the `stealth` field: `theme`, `appearance`, `messages`.
+* @param {SchemaOf<Value>} schema - The schema for what sits under that key.
+* @returns {Collected<Registered<Value>, FieldIssue>} One entry when the package registered
+*     this kind, and none when it registered nothing or registered another kind. A `stealth`
+*     field that is not an object is a refusal, whatever key was asked for.
+*/
+function contributionOf(manifest, key, schema) {
+	if (manifest.contributions === void 0) return succeeded([]);
+	const field = safeParse(FIELD, manifest.contributions);
+	if (!field.ok) return refused(prefixed(field.failure, `${manifest.name}.stealth`));
+	const declared = field.value[key];
+	if (declared === void 0) return succeeded([]);
+	const read = safeParse(schema, declared);
+	if (!read.ok) return refused(prefixed(read.failure, `${manifest.name}.stealth.${key}`));
+	return succeeded([{
+		manifest,
+		value: read.value
+	}]);
+}
+/**
+* Reads one kind of contribution out of every manifest of a workspace.
+*
+* Every malformed field is reported at once rather than the first, because somebody fixing
+* manifests wants the whole list. A package that registers nothing, or registers only other
+* kinds, is absent from the result rather than being an entry with nothing in it.
+*
+* @template Value - What the schema parses the contribution to.
+* @param {readonly Manifest[]} manifests - The workspace's manifests, as `workspaceManifests`
+*     read them. Their order is the result's order.
+* @param {string} key - The key inside the `stealth` field: `theme`, `appearance`, `messages`.
+* @param {SchemaOf<Value>} schema - The schema for what sits under that key. It belongs to the
+*     package that owns those words.
+* @returns {Collected<Registered<Value>, FieldIssue>} Every package that registered this kind,
+*     in workspace order, or every refusal with the package on each path.
+*/
+function contributions(manifests, key, schema) {
+	const read = collect(manifests.map((manifest) => contributionOf(manifest, key, schema)));
+	if (!read.ok) return refused(read.failure.flat());
+	return succeeded(read.value.flat());
+}
+//#endregion
+export { contributions, dependencyClosure, expandWorkspacePattern, packageRoot, readManifest, workspaceManifests, workspacePatterns, workspaceRoot };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@stealthscale/tool-workspace",
+  "version": "0.1.0",
+  "description": "Reads a workspace off its manifests: which packages the root names, what each declares, and the order their dependencies put them in.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stealth-scale/tooling.git",
+    "directory": "tools/workspace"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#*": "./src/*"
+  },
+  "exports": {
+    ".": {
+      "tooling-source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./package.json": "./package.json"
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack src/index.ts"
+  },
+  "dependencies": {
+    "@stealthscale/core-result": "^0.1.0",
+    "@stealthscale/core-schema": "^0.1.0"
+  },
+  "devDependencies": {
+    "@stealthscale/tool-config": "^0.1.0",
+    "@stealthscale/tool-testing": "^0.1.0"
+  }
+}