@venn-lang/project 0.1.0

package/dist/index.js

@@ -0,0 +1,970 @@
+import { BIN_DIR, LIB_ROOT, MAIN_ROOT, createTomlManifest } from "@venn-lang/contracts";
+//#region src/paths/paths.ts
+/**
+* Path arithmetic on manifest paths, with no `node:path`.
+*
+* This package runs in a Web Worker as well as in the CLI, so paths are handled
+* as text with forward slashes. A Windows path arrives with backslashes and is
+* normalised on the way in, which is the one place the difference is allowed to
+* exist.
+*/
+/**
+* One path, written the one way the rest of this package understands.
+*
+* @returns The path with backslashes turned into forward slashes, runs of
+* separators collapsed, and any trailing separator dropped. `"/"` stays `"/"`.
+*/
+function normalise(path) {
+	const flat = path.replaceAll("\\", "/").replace(/\/+/g, "/");
+	return flat.length > 1 ? flat.replace(/\/$/, "") : flat;
+}
+/**
+* Joins path segments, ignoring empty ones.
+*
+* @returns The joined path, normalised. No `..` is resolved: these are manifest
+* paths, and what a manifest wrote is what gets written down.
+*/
+function join(...parts) {
+	return normalise(parts.filter((part) => part !== "").join("/"));
+}
+/**
+* The directory holding this path.
+*
+* @returns The parent, or `undefined` when there is nothing above. A relative
+* path with one segment has the empty string as its parent, which is the
+* directory it was written against; stopping short of it would leave a walk up
+* from `packages/api` never reaching the workspace root beside it.
+*/
+function parentOf(path) {
+	const flat = normalise(path);
+	if (flat === "" || flat === "/") return void 0;
+	const slash = flat.lastIndexOf("/");
+	if (slash < 0) return "";
+	return slash === 0 ? "/" : flat.slice(0, slash);
+}
+/** The last segment of a path, which is the file or directory's own name. */
+function baseName(path) {
+	const flat = normalise(path);
+	return flat.slice(flat.lastIndexOf("/") + 1);
+}
+/**
+* Every directory from `path` up to the top, `path` itself first.
+*
+* @returns The chain, ending in `""` for a relative path and `"/"` for an
+* absolute one.
+*/
+function ancestors(path) {
+	const found = [];
+	for (let at = normalise(path); at !== void 0; at = parentOf(at)) found.push(at);
+	return found;
+}
+/** Whether `path` is `base` or sits inside it. */
+function isInside(path, base) {
+	const one = normalise(path);
+	const other = normalise(base);
+	return one === other || one.startsWith(`${other}/`);
+}
+/** `path` written relative to `base`, or the path itself when it is not inside. */
+function relativeTo(path, base) {
+	const one = normalise(path);
+	const other = normalise(base);
+	return one.startsWith(`${other}/`) ? one.slice(other.length + 1) : one;
+}
+/**
+* A relative path written in one directory, rewritten to mean the same thing
+* from another inside it.
+*
+* A workspace root writes `"#shared" = "./shared"` once and every member uses
+* it, but a member reads it from further down, where `./shared` is somewhere
+* else entirely.
+*
+* @param args.declaredIn Where the path was written.
+* @param args.usedIn Where it will be read.
+* @returns The path with one `../` per directory of depth. An absolute path is
+* returned unchanged: it already means the same thing everywhere.
+*/
+function reanchor(args) {
+	if (!args.path.startsWith(".")) return args.path;
+	const down = relativeTo(args.usedIn, args.declaredIn);
+	const depth = down === normalise(args.usedIn) ? 0 : down.split("/").filter(Boolean).length;
+	if (depth === 0) return args.path;
+	return `${"../".repeat(depth)}${args.path.replace(/^\.\//, "")}`;
+}
+//#endregion
+//#region src/discover/conventional-targets.ts
+/**
+* What a package builds when its manifest does not say.
+*
+* `src/lib.vn` is a library, `src/main.vn` is a program, and each file in
+* `src/bin/` is another program. A package that builds the obvious thing should
+* not have to write it down. A declared target always wins, matched by kind and
+* name, so writing `[lib]` with a different `path` moves the library rather
+* than adding a second one.
+*
+* @param args.declared What the manifest spelled out.
+* @param args.packageName Names the `lib` and the `src/main.vn` program.
+* @returns The declared targets, followed by every convention found on disk.
+*/
+async function conventionalTargets(args) {
+	const found = [...args.declared];
+	const add = async (target) => {
+		if (found.some((one) => one.kind === target.kind && one.name === target.name)) return;
+		if (await args.fs.exists(join(args.dir, target.path))) found.push(target);
+	};
+	await add({
+		kind: "lib",
+		name: args.packageName,
+		path: LIB_ROOT
+	});
+	await add({
+		kind: "bin",
+		name: args.packageName,
+		path: MAIN_ROOT
+	});
+	for (const name of await binNames(args.fs, args.dir)) await add({
+		kind: "bin",
+		name,
+		path: `${BIN_DIR}/${name}.vn`
+	});
+	return found;
+}
+/** Each `.vn` in `src/bin/` is a program named after the file. */
+async function binNames(fs, dir) {
+	return (await fs.list(join(dir, BIN_DIR))).filter((entry) => !entry.directory && entry.name.endsWith(".vn")).map((entry) => entry.name.slice(0, -3)).sort();
+}
+//#endregion
+//#region src/workspace/inherit.ts
+/**
+* A member manifest with what the workspace root supplies filled in.
+*
+* Two things are inherited and they work differently. `[workspace.package]` is
+* a default: the member's own value wins wherever it wrote one. A dependency
+* marked `{ workspace = true }` is a request, so the root's answer replaces
+* whatever was there. Writing both a version and `workspace = true` is a
+* contradiction, and the request is the deliberate half.
+*
+* @param args.from The workspace root's manifest. A root with no `[workspace]`
+* table supplies nothing, and the member is returned untouched.
+* @returns The merged manifest. The member's own `name` always survives.
+*/
+function inherit(args) {
+	const shared = args.from.workspace;
+	if (!shared) return args.manifest;
+	const pkg = withDefaults(args.manifest.package, shared.package);
+	return {
+		...args.manifest,
+		name: pkg.name,
+		version: pkg.version ?? args.manifest.version,
+		package: pkg,
+		dependencies: pinned(args.manifest.dependencies, shared.dependencies),
+		devDependencies: pinned(args.manifest.devDependencies, shared.dependencies),
+		...settings(args.manifest, args.from)
+	};
+}
+/**
+* The environments and path aliases a member gets from its root.
+*
+* A workspace almost always wants `[env.staging]` and `#shared` written once.
+* The alternative, every member repeating every variable, drifts silently until
+* two members disagree about a URL. A member that writes its own key wins, per
+* key rather than per table.
+*/
+function settings(own, root) {
+	const env = { ...root.env };
+	for (const [name, vars] of Object.entries(own.env)) env[name] = {
+		...env[name],
+		...vars
+	};
+	return {
+		env,
+		paths: {
+			...root.paths,
+			...own.paths
+		}
+	};
+}
+/** The member's own value wins; the root fills only what was left unsaid. */
+function withDefaults(own, shared) {
+	const merged = { ...own };
+	for (const [key, value] of Object.entries(shared)) if (merged[key] === void 0 || merged[key] === "") merged[key] = value;
+	return {
+		...merged,
+		name: own.name
+	};
+}
+function pinned(deps, shared) {
+	return deps.map((dep) => {
+		if (!dep.fromWorkspace) return dep;
+		const found = shared.find((one) => one.name === dep.name);
+		return found ? {
+			...found,
+			optional: dep.optional,
+			fromWorkspace: true
+		} : dep;
+	});
+}
+//#endregion
+//#region src/glob/expand-members.ts
+/**
+* Expands a workspace's `members` patterns against the disk.
+*
+* `*` stands for one path segment, the way Cargo reads it, so `packages/*` is
+* every package one level down and nothing deeper. `**` is deliberately not
+* read: a member list that can reach arbitrarily far is one nobody can predict.
+*
+* @param args.root The workspace root the patterns are written against.
+* @returns The directories matched, duplicates dropped, in pattern order with
+* names sorted inside each pattern, so two machines list a workspace alike.
+*/
+async function expandMembers(args) {
+	const found = [];
+	for (const pattern of args.patterns) for (const dir of await expandOne(args.fs, args.root, pattern)) if (!found.includes(dir)) found.push(dir);
+	return found;
+}
+async function expandOne(fs, root, pattern) {
+	let at = [root];
+	for (const segment of pattern.split("/").filter((part) => part !== "")) at = segment === "*" ? await childrenOf(fs, at) : at.map((dir) => join(dir, segment));
+	return at;
+}
+async function childrenOf(fs, dirs) {
+	const found = [];
+	for (const dir of dirs) {
+		const names = (await fs.list(dir)).filter((entry) => entry.directory).map((entry) => entry.name);
+		for (const name of names.sort()) found.push(join(dir, name));
+	}
+	return found;
+}
+//#endregion
+//#region src/glob/matches-member.ts
+/**
+* Whether a path would be caught by a workspace's `members`, without looking at
+* the disk.
+*
+* Needed before the directory exists: creating `packages/api` inside a
+* workspace should produce a manifest that inherits, and expanding the globs
+* cannot answer that yet because there is nothing there to find.
+*
+* @returns `true` when some pattern matches segment for segment, `*` standing
+* for exactly one segment.
+*/
+function matchesMember(args) {
+	const parts = segmentsOf(args.path);
+	return args.patterns.some((pattern) => matchesOne(parts, segmentsOf(pattern)));
+}
+function matchesOne(path, pattern) {
+	if (path.length !== pattern.length) return false;
+	return pattern.every((part, index) => part === "*" || part === path[index]);
+}
+function segmentsOf(path) {
+	return normalise(path).split("/").filter((part) => part !== "" && part !== ".");
+}
+//#endregion
+//#region src/workspace/member-dirs.ts
+/**
+* The directories a workspace's members occupy, exclusions already applied.
+*
+* @returns The member directories, normalised. One holding no `venn.toml` is
+* dropped rather than reported: a glob describes a shape, and `packages/*`
+* catching a `dist` folder on the way past is the glob working, not the
+* workspace being wrong.
+*/
+async function memberDirs(args) {
+	const matched = await expandMembers({
+		fs: args.fs,
+		root: args.root,
+		patterns: args.workspace.members
+	});
+	const excluded = args.workspace.exclude.map((path) => normalise(join(args.root, path)));
+	const kept = matched.filter((dir) => !excluded.some((one) => isInside(dir, one)));
+	return withManifest(args.fs, kept);
+}
+async function withManifest(fs, dirs) {
+	const found = [];
+	for (const dir of dirs) if (await fs.exists(join(dir, "venn.toml"))) found.push(normalise(dir));
+	return found;
+}
+//#endregion
+//#region src/discover/read-manifest.ts
+/** The file that makes a directory a package or a workspace root. */
+const MANIFEST_FILE = "venn.toml";
+/**
+* Reads and parses the `venn.toml` in one directory.
+*
+* @returns The manifest, or `undefined` when the file is absent or unreadable.
+* A directory that cannot be read is a directory without a manifest, so the
+* caller keeps walking instead of failing.
+*/
+async function readManifest(args) {
+	const path = join(args.dir, MANIFEST_FILE);
+	if (!await args.fs.exists(path)) return void 0;
+	const bytes = await args.fs.read(path).catch(() => void 0);
+	if (!bytes) return void 0;
+	return createTomlManifest({ content: new TextDecoder().decode(bytes) }).load();
+}
+//#endregion
+//#region src/discover/load-package.ts
+/**
+* One package: its manifest, whatever it inherits, and what it builds.
+*
+* Inheritance is applied here rather than at the point of use, so nothing
+* downstream ever holds a manifest that is only half the answer.
+*
+* @param args.dir The directory holding the `venn.toml`.
+* @returns The package, or `undefined` when that directory has no manifest.
+*/
+async function loadPackage(args) {
+	const own = await readManifest({
+		fs: args.fs,
+		dir: args.dir
+	});
+	if (!own) return void 0;
+	const manifest = anchorPaths({
+		manifest: args.workspace ? inherit({
+			manifest: own,
+			from: args.workspace
+		}) : own,
+		own,
+		args
+	});
+	const targets = await conventionalTargets({
+		fs: args.fs,
+		dir: args.dir,
+		declared: manifest.targets,
+		packageName: manifest.name
+	});
+	return {
+		dir: args.dir,
+		manifest,
+		targets
+	};
+}
+/**
+* Inherited path aliases, rewritten to mean the same place from down here.
+*
+* An alias the member wrote itself is already anchored where it will be read,
+* so only the ones that came from above move. Hence the member's own table is
+* consulted rather than the merged one.
+*/
+function anchorPaths(input) {
+	const root = input.args.workspaceDir;
+	if (root === void 0 || root === input.args.dir) return input.manifest;
+	const paths = {};
+	for (const [alias, value] of Object.entries(input.manifest.paths)) paths[alias] = input.own.paths[alias] !== void 0 ? value : reanchor({
+		path: value,
+		declaredIn: root,
+		usedIn: input.args.dir
+	});
+	return {
+		...input.manifest,
+		paths
+	};
+}
+//#endregion
+//#region src/discover/find-project.ts
+/**
+* The project a path belongs to: the nearest package, and the root that owns it.
+*
+* Walking up is what lets a command run from anywhere inside a project, the way
+* `cargo` and `git` do. A package is claimed by an ancestor workspace only when
+* that workspace's members name it, so a project checked out inside another
+* never joins it by accident.
+*
+* @param args.fs Where the manifests are read from.
+* @param args.from Any path inside the project; the walk starts here.
+* @returns The project with its members loaded and inheritance applied, or one
+* `VN2101` problem when no `venn.toml` sits here or above. Reading a project
+* never throws: a failure comes back as a problem.
+*/
+async function findProject(args) {
+	const nearest = await nearestManifest(args.fs, args.from);
+	if (!nearest) return { problems: [noManifest(args.from)] };
+	if (nearest.manifest.workspace) return workspaceAt(args.fs, nearest.dir, nearest.manifest);
+	const owner = await owningWorkspace(args.fs, nearest.dir);
+	return owner ? workspaceAt(args.fs, owner.dir, owner.manifest) : lonePackage(args.fs, nearest.dir);
+}
+async function nearestManifest(fs, from) {
+	for (const dir of ancestors(from)) {
+		const manifest = await readManifest({
+			fs,
+			dir
+		});
+		if (manifest) return {
+			dir,
+			manifest
+		};
+	}
+}
+/** The nearest workspace above this package that lists it among its members. */
+async function owningWorkspace(fs, dir) {
+	for (const above of ancestors(dir).slice(1)) {
+		const manifest = await readManifest({
+			fs,
+			dir: above
+		});
+		if (!manifest?.workspace) continue;
+		if ((await memberDirs({
+			fs,
+			root: above,
+			workspace: manifest.workspace
+		})).includes(normalise(dir))) return {
+			dir: above,
+			manifest
+		};
+	}
+}
+async function lonePackage(fs, dir) {
+	const found = await loadPackage({
+		fs,
+		dir
+	});
+	if (!found) return { problems: [noManifest(dir)] };
+	return {
+		project: {
+			root: dir,
+			isWorkspace: false,
+			rootManifest: found.manifest,
+			packages: [found],
+			defaultPackages: [found]
+		},
+		problems: []
+	};
+}
+async function workspaceAt(fs, root, manifest) {
+	const settings = manifest.workspace;
+	if (!settings) return lonePackage(fs, root);
+	const packages = await loadEach({
+		fs,
+		dirs: await memberDirs({
+			fs,
+			root,
+			workspace: settings
+		}),
+		workspace: manifest,
+		workspaceDir: root
+	});
+	const rootPackage = manifest.name === "" ? void 0 : await loadPackage({
+		fs,
+		dir: root
+	});
+	const all = rootPackage ? [rootPackage, ...packages] : packages;
+	return {
+		project: {
+			root,
+			isWorkspace: true,
+			rootManifest: manifest,
+			packages: all,
+			defaultPackages: defaults(all, settings.defaultMembers, root)
+		},
+		problems: []
+	};
+}
+async function loadEach(args) {
+	const found = [];
+	for (const dir of args.dirs) {
+		const one = await loadPackage({
+			fs: args.fs,
+			dir,
+			workspace: args.workspace,
+			workspaceDir: args.workspaceDir
+		});
+		if (one) found.push(one);
+	}
+	return found;
+}
+/** `default-members`, or every member when the root did not narrow it. */
+function defaults(all, names, root) {
+	if (names.length === 0) return [...all];
+	const wanted = new Set(names.map((name) => join(root, name)));
+	return all.filter((one) => wanted.has(one.dir) || wanted.has(one.manifest.name));
+}
+function noManifest(path) {
+	return {
+		code: "VN2101",
+		title: "No venn.toml here, or in any folder above it.",
+		path: normalise(path)
+	};
+}
+//#endregion
+//#region src/npm/hash-package.ts
+/** Directories inside a package that are not part of it. */
+const SKIP = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	".bin"
+]);
+/**
+* A hash of everything a package installed.
+*
+* Not the registry's integrity hash, which lives in each manager's own lock in
+* each manager's format. This is computed from what landed on disk, which every
+* manager produces the same way. The guarantee differs: the registry's hash
+* says "this is the tarball that was served", this one says "this is the tree
+* that was installed when the lock was written". Trust on first use, and any
+* divergence after that is caught.
+*
+* A hash of hashes rather than of the concatenated bytes, because a package can
+* hold tens of megabytes and digesting it in one buffer costs more than the
+* answer is worth.
+*
+* @param args.dir The installed package directory.
+* @returns `sha256-…` over every file under `dir`, sorted by path, with
+* `node_modules`, `.git` and `.bin` skipped. A file that cannot be read is left
+* out rather than raising.
+*/
+async function hashPackage(args) {
+	const files = (await filesUnder(args.fs, args.dir, "")).sort();
+	const lines = [];
+	for (const path of files) {
+		const bytes = await args.fs.read(join(args.dir, path));
+		lines.push(`${path}\t${await digest(bytes)}`);
+	}
+	return `sha256-${await digest(new TextEncoder().encode(lines.join("\n")))}`;
+}
+async function filesUnder(fs, root, at) {
+	const found = [];
+	for (const entry of await fs.list(join(root, at))) {
+		const path = at === "" ? entry.name : `${at}/${entry.name}`;
+		if (!entry.directory) found.push(path);
+		else if (!SKIP.has(entry.name)) found.push(...await filesUnder(fs, root, path));
+	}
+	return found;
+}
+/**
+* Web Crypto, so this runs wherever the rest of this package runs.
+*
+* The assertion narrows which buffer backs the array rather than claiming the
+* array is a buffer: `BufferSource` wants a view onto an `ArrayBuffer`, and
+* these come from a file read and from `TextEncoder`, both of which give one.
+*/
+async function digest(bytes) {
+	const hashed = await crypto.subtle.digest("SHA-256", bytes);
+	return base64(new Uint8Array(hashed));
+}
+function base64(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary);
+}
+//#endregion
+//#region src/npm/lockfile.types.ts
+/** The lock file's name, at the project root beside the manifest. */
+const LOCK_FILE = "venn.lock";
+/** The format version written into every lock. */
+const LOCK_VERSION = 1;
+//#endregion
+//#region src/target/layout.ts
+/**
+* Where everything a build produces or fetches goes.
+*
+* One directory at the workspace root holds every derived thing, the way
+* Cargo's `target/` does, so deleting it costs time and nothing else.
+*
+* The dependencies live inside it, and that placement is load-bearing rather
+* than tidiness: Node resolves a package by walking up from the importing file
+* looking for `node_modules`, and built output sits in `target/debug` or
+* `target/release`, one level below `target/node_modules`. The ordinary
+* resolver finds them with no loader and no symlink. Moving the output out of
+* `target/` breaks that quietly.
+*/
+const TARGET_DIR = "target";
+/** The names inside `target/`. */
+const TARGET_LAYOUT = {
+	/** What the package manager installs, and what Node's resolver will find. */
+	modules: "node_modules",
+	/** Compiled addons, kept apart because they are per-platform, not per-project. */
+	native: "native_modules",
+	/** Built output, one directory per profile. */
+	debug: "debug",
+	release: "release"
+};
+/** The `target/` of a project, given its root. */
+function targetDir(root) {
+	return join(root, TARGET_DIR);
+}
+/** Where the package manager installs, and where Node's resolver will look. */
+function modulesDir(root) {
+	return join(targetDir(root), TARGET_LAYOUT.modules);
+}
+/** Where compiled addons go, kept apart because they are per-platform. */
+function nativeModulesDir(root) {
+	return join(targetDir(root), TARGET_LAYOUT.native);
+}
+/** Where a build of this profile is written. */
+function outputDir(args) {
+	return join(targetDir(args.root), TARGET_LAYOUT[args.profile]);
+}
+//#endregion
+//#region src/target/build-record.ts
+/** The record's name, inside the profile's output directory. */
+const RECORD_FILE = "build.json";
+/**
+* Writes what a build produced, where that build's outputs go.
+*
+* It answers "what does this project build, and did it hold together", and it
+* is what an incremental build compares against once there is generated code to
+* skip.
+*
+* @returns The path written.
+* @throws Whatever the file system raises when the write fails.
+*/
+async function writeBuildRecord(args) {
+	const path = join(outputDir({
+		root: args.root,
+		profile: args.record.profile
+	}), RECORD_FILE);
+	const text = `${JSON.stringify(args.record, null, 2)}\n`;
+	await args.fs.write(path, new TextEncoder().encode(text));
+	return path;
+}
+//#endregion
+//#region src/npm/read-installed.ts
+/**
+* Every package installed, read from `target/node_modules`.
+*
+* The installed tree is the strongest statement there is about what a project
+* resolved to: it is what will actually be imported, whichever tool put it
+* there and whatever that tool's own lock says. One walk, the same for every
+* manager. A scope is a directory of packages rather than a package, so
+* `@types/node` is found one level further down.
+*
+* @param args.root The project root, not the modules directory.
+* @returns Every package with its version and content hash, in name order.
+* Dot-directories and anything without a readable `package.json` are skipped,
+* because a directory that is not a package is not a package.
+*/
+async function readInstalled(args) {
+	const modules = modulesDir(args.root);
+	const found = [];
+	for (const entry of await args.fs.list(modules)) {
+		if (!entry.directory || entry.name.startsWith(".")) continue;
+		if (entry.name.startsWith("@")) found.push(...await scoped(args.fs, modules, entry.name));
+		else pushIf(found, await readPackage(args.fs, join(modules, entry.name)));
+	}
+	return found.sort((a, b) => a.name.localeCompare(b.name));
+}
+async function scoped(fs, modules, scope) {
+	const found = [];
+	for (const entry of await fs.list(join(modules, scope))) if (entry.directory) pushIf(found, await readPackage(fs, join(modules, scope, entry.name)));
+	return found;
+}
+function pushIf(into, one) {
+	if (one) into.push(one);
+}
+async function readPackage(fs, dir) {
+	const bytes = await fs.read(join(dir, "package.json")).catch(() => void 0);
+	if (!bytes) return void 0;
+	const data = parse(new TextDecoder().decode(bytes));
+	if (typeof data?.name !== "string" || typeof data.version !== "string") return void 0;
+	return {
+		name: data.name,
+		version: data.version,
+		integrity: await hashPackage({
+			fs,
+			dir
+		}),
+		...deps(data.dependencies)
+	};
+}
+function deps(value) {
+	if (typeof value !== "object" || value === null) return {};
+	const entries = Object.entries(value).map(([k, v]) => [k, String(v)]);
+	return entries.length > 0 ? { dependencies: Object.fromEntries(entries) } : {};
+}
+function parse(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/npm/lockfile.ts
+/**
+* Writes `venn.lock` from what is installed.
+*
+* It goes at the project root, beside the manifest, and is meant to be
+* committed. The manager's own lock stays inside `target/`, which is derived
+* and thrown away.
+*
+* @param args.manager Which tool did the resolving, recorded in the file.
+* @returns The lock as written.
+* @throws Whatever the file system raises when the write fails.
+*/
+async function writeLockfile(args) {
+	const lock = {
+		version: 1,
+		manager: args.manager,
+		packages: await readInstalled({
+			fs: args.fs,
+			root: args.root
+		})
+	};
+	const text = `${JSON.stringify(lock, null, 2)}\n`;
+	await args.fs.write(join(args.root, LOCK_FILE), new TextEncoder().encode(text));
+	return lock;
+}
+/**
+* Reads the lock this project committed.
+*
+* @returns The lock, or `undefined` when the file is absent or will not parse.
+* A lock nobody can read is a project without one, which `install` can fix.
+*/
+async function readLockfile(args) {
+	const bytes = await args.fs.read(join(args.root, LOCK_FILE)).catch(() => void 0);
+	if (!bytes) return void 0;
+	try {
+		return JSON.parse(new TextDecoder().decode(bytes));
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/npm/manager-command.ts
+/**
+* The command a verb becomes, in the manager this project chose.
+*
+* The interface is ours, the resolution is not: working out which versions
+* satisfy which ranges is years of work against three moving targets, so the
+* four verbs are spelled once here and handed to the tool the project named.
+*
+* @param args.packages Specifiers to act on. Pass each through
+* {@link isSafeSpec} first when `shell` comes back `true`.
+* @returns The command, its arguments, and whether a shell is required.
+*/
+function managerCommand(args) {
+	const dev = args.dev ? ["-D"] : [];
+	return {
+		command: args.manager,
+		args: [
+			verbFor(args),
+			...dev,
+			...args.packages ?? []
+		],
+		shell: args.platform === "win32"
+	};
+}
+/** npm spells `add` and `remove` its own way; every other manager agrees. */
+function verbFor(args) {
+	return args.manager === "npm" ? NPM[args.verb] : NON_NPM[args.verb];
+}
+const NON_NPM = {
+	add: "add",
+	remove: "remove",
+	update: "update",
+	install: "install"
+};
+const NPM = {
+	add: "install",
+	remove: "uninstall",
+	update: "update",
+	install: "install"
+};
+/** A package name, optionally scoped, optionally with a version range. */
+const SPEC = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*(@[A-Za-z0-9.^~><=*-]+)?$/;
+/**
+* Whether a string is a package specifier and nothing else.
+*
+* The command goes through a shell on Windows, and a shell reads `&`, `|` and
+* `>` as instructions rather than text, so `venn add "x & del /q ."` would
+* delete a directory while looking like an install. A real package name holds
+* none of those characters, so checking costs nothing and closes the hole
+* instead of documenting it.
+*
+* @returns `true` when the string is safe to hand to a shell.
+*/
+function isSafeSpec(spec) {
+	return SPEC.test(spec);
+}
+//#endregion
+//#region src/npm/package-json.ts
+/**
+* The `package.json` a package manager is shown, generated from `venn.toml`.
+*
+* Nobody edits it and nobody commits it: the manifest is the source, this is
+* what the tool underneath happens to read. It is written into `target/`, and
+* that placement is the whole trick: a manager writes `node_modules` beside the
+* `package.json` it was pointed at, so the modules land in
+* `target/node_modules` with nothing fighting anything.
+*
+* @param args.members Their dependencies are merged in too, when the root is a
+* workspace.
+* @returns The file's text, marked private, with path dependencies left out and
+* `[patch]` turned into `overrides`.
+*/
+function packageJsonFor(args) {
+	const all = [args.manifest, ...args.members ?? []];
+	const body = {
+		name: `${args.manifest.name || "venn-project"}-target`,
+		private: true,
+		type: "module",
+		dependencies: merged(all.flatMap((one) => one.dependencies)),
+		devDependencies: merged(all.flatMap((one) => one.devDependencies)),
+		...overrides(args.manifest.patch)
+	};
+	return `${JSON.stringify(body, null, 2)}\n`;
+}
+/**
+* The versions asked for, by name.
+*
+* A dependency on a path is not the package manager's business: it is another
+* package in this workspace, resolved by the language, and handing it over as a
+* version range would send the tool looking for it in the registry.
+*/
+function merged(deps) {
+	const out = {};
+	for (const dep of deps) {
+		if (dep.path !== void 0) continue;
+		out[dep.name] = dep.version ?? "*";
+	}
+	return sorted(out);
+}
+/** `[patch]`: the version this project insists on, wherever it is asked for. */
+function overrides(patch) {
+	const found = merged(patch);
+	return Object.keys(found).length > 0 ? { overrides: found } : {};
+}
+/** Written in name order, so regenerating it produces no diff of its own. */
+function sorted(entries) {
+	return Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)));
+}
+//#endregion
+//#region src/npm/verify-lock.ts
+/**
+* Checks what is installed against what the lock says should be.
+*
+* This is what the hashes are for. Checked, they turn a registry that answered
+* differently today, or a file edited by hand inside `node_modules`, into
+* something a build refuses to start with rather than something found in
+* production.
+*
+* @returns One `Drift` per difference, empty when the tree matches. A lock
+* entry carrying no `integrity` is not checked for contents, so a lock written
+* before hashes existed still passes.
+*/
+async function verifyLock(args) {
+	const installed = await readInstalled({
+		fs: args.fs,
+		root: args.root
+	});
+	const byName = new Map(installed.map((one) => [one.name, one]));
+	const drift = args.lock.packages.flatMap((locked) => compare(locked, byName.get(locked.name)));
+	const expected = new Set(args.lock.packages.map((one) => one.name));
+	const extra = installed.filter((one) => !expected.has(one.name));
+	return [...drift, ...extra.map((one) => ({
+		name: one.name,
+		kind: "unexpected"
+	}))];
+}
+function compare(locked, found) {
+	if (!found) return [{
+		name: locked.name,
+		kind: "missing",
+		expected: locked.version
+	}];
+	if (found.version !== locked.version) return [{
+		name: locked.name,
+		kind: "version",
+		expected: locked.version,
+		found: found.version
+	}];
+	if (locked.integrity && found.integrity !== locked.integrity) return [{
+		name: locked.name,
+		kind: "contents",
+		expected: locked.integrity
+	}];
+	return [];
+}
+/**
+* Renders drift for a person to read.
+*
+* @returns One indented line per package that differs, in the voice of what
+* went wrong. Empty for an empty list.
+*/
+function describeDrift(drift) {
+	return drift.map(lineFor).join("\n");
+}
+const LINES = {
+	missing: (one) => `  ${one.name}@${one.expected} is in the lock but not installed`,
+	unexpected: (one) => `  ${one.name} is installed but not in the lock`,
+	version: (one) => `  ${one.name}: lock says ${one.expected}, installed is ${one.found}`,
+	contents: (one) => `  ${one.name}: installed files differ from what was locked`
+};
+function lineFor(one) {
+	return LINES[one.kind](one);
+}
+//#endregion
+//#region src/scaffold/scaffold.ts
+/**
+* The files a new project starts as.
+*
+* Pure: it says what should exist and the caller writes it, so `--dry-run`, the
+* tests and the disk all see one answer. What is generated is deliberately
+* small, because a starting point that has to be deleted before it can be used
+* is worse than one that is missing something.
+*
+* @returns The manifest, a source file for anything that is not a workspace,
+* and a `.gitignore` unless a workspace above already owns one.
+*/
+function scaffold(request) {
+	const files = [{
+		path: "venn.toml",
+		content: manifestFor(request)
+	}];
+	if (request.kind !== "workspace") files.push(sourceFor(request));
+	if (!request.insideWorkspace) files.push(ignoreFile());
+	return files;
+}
+/** A member leaves out what it inherits; writing it down would only shadow it. */
+function manifestFor(request) {
+	if (request.kind === "workspace") return workspaceManifest();
+	const version = request.insideWorkspace ? [] : ["version = \"0.1.0\""];
+	return [
+		"[package]",
+		`name = "${request.name}"`,
+		...version,
+		"",
+		"[dependencies]",
+		""
+	].join("\n");
+}
+function workspaceManifest() {
+	return [
+		"[workspace]",
+		"members = [\"packages/*\"]",
+		"",
+		"# Metadata a member inherits by leaving it out.",
+		"[workspace.package]",
+		"version = \"0.1.0\"",
+		"",
+		"# Versions a member takes with `dep = { workspace = true }`.",
+		"[workspace.dependencies]",
+		""
+	].join("\n");
+}
+/** A library exports; a program runs. Each starts as the smallest of itself. */
+function sourceFor(request) {
+	if (request.kind === "lib") return {
+		path: "src/lib.vn",
+		content: [
+			"pub fn greet(name: string) -> string {",
+			"  \"Hello, ${name}\"",
+			"}",
+			""
+		].join("\n")
+	};
+	return {
+		path: "src/main.vn",
+		content: `print "Hello from ${request.name}"\n`
+	};
+}
+/** Everything derived lives in one directory, so ignoring it is one line. */
+function ignoreFile() {
+	return {
+		path: ".gitignore",
+		content: `${TARGET_DIR}/\n`
+	};
+}
+//#endregion
+export { LOCK_FILE, LOCK_VERSION, MANIFEST_FILE, RECORD_FILE, TARGET_DIR, TARGET_LAYOUT, ancestors, baseName, conventionalTargets, describeDrift, expandMembers, findProject, hashPackage, inherit, isInside, isSafeSpec, join, loadPackage, managerCommand, matchesMember, memberDirs, modulesDir, nativeModulesDir, normalise, outputDir, packageJsonFor, parentOf, readInstalled, readLockfile, readManifest, reanchor, relativeTo, scaffold, targetDir, verifyLock, writeBuildRecord, writeLockfile };
+
+//# sourceMappingURL=index.js.map