@packall/core 0.5.2 → 0.5.3

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@packall/core",
-  "version": "0.5.2",
-  "description": "Registry-agnostic engine for bundling npm packages and their full dependency closure for offline import.",
+  "version": "0.5.3",
+  "description": "Registry-agnostic engine that resolves, downloads, verifies and packages an npm dependency closure for offline import.",
+  "keywords": [
+    "airgap",
+    "bundle",
+    "dependencies",
+    "effect",
+    "integrity",
+    "npm",
+    "offline",
+    "tarball"
+  ],
   "homepage": "https://packall.vercel.app",
   "bugs": {
     "url": "https://gitlab.com/yelev/packall/-/issues"

package/src/archive.ts

@@ -1,20 +1,3 @@
-/**
- * Turning a staged directory tree into a gzipped tarball.
- *
- * A service rather than a function, because packing is the one step that has
- * to be implemented differently per platform. Everywhere else the engine
- * reaches the disk through `effect/FileSystem`, which is what lets an in-memory
- * filesystem carry the whole pipeline — but a tar writer is not filesystem
- * access, it is a format, and `node-tar` reads the paths it is given with
- * Node's own `fs` rather than through the injected service. Left as a direct
- * call, packing would quietly bypass the abstraction the rest of the engine
- * depends on, which stays invisible until something other than Node provides
- * the filesystem.
- *
- * The implementations live outside this module — `@packall/core/node` for
- * Node, a Web Streams writer in the browser — so nothing platform-specific is
- * reachable from the engine's own graph.
- */
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import type * as FileSystem from "effect/FileSystem";
@@ -56,7 +39,15 @@ export declare namespace Archiver {
 	};
 }
 
-/** Service tag for archive creation. */
+/**
+ * Service tag for archive creation.
+ *
+ * Packing is a service rather than a plain function because it is the one step
+ * that cannot go through `effect/FileSystem`: a tar writer reads the paths it
+ * is handed with the host's own file APIs, so a direct call would bypass the
+ * injected filesystem the rest of the engine runs on. Provide `layerArchiver`
+ * from `@packall/core/node`, or an implementation of your own.
+ */
 export class Archiver extends Context.Service<Archiver, Archiver.Service>()(
 	"@packall/core/Archiver",
 ) {}

package/src/bundle.ts

@@ -1,21 +1,3 @@
-/**
- * End-to-end orchestration: specs in, tarballs out.
- *
- * Two properties this module is responsible for — see `notes/requirements.md`
- * § FR-5 and § NFR-9 for why they are requirements, and the mechanisms below
- * for why the code reads as it does:
- *
- * 1. **Nothing is written outside the output directory.** Every intermediate
- *    file lives in a scoped temp directory obtained from
- *    `makeTempDirectoryScoped`, so the scope closing — on success, on failure,
- *    or on Ctrl-C — takes the whole staging tree with it. The working
- *    directory is never touched.
- *
- * 2. **Each package is downloaded exactly once**, no matter how many bundles
- *    it ends up in. Per-spec archives are assembled by hard-linking out of one
- *    shared download tree, so `per-spec` costs extra disk in the *output*, not
- *    extra network.
- */
 import type * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
@@ -320,6 +302,9 @@ const runBundle = (
 
 		yield* prepareOutputDir(resolution, options);
 
+		// Scoped, not just temporary: the scope closing — on success, on failure,
+		// or on Ctrl-C — takes the whole staging tree with it, which is what keeps
+		// a crashed run from leaving half a bundle beside the user's own files.
 		const staging = yield* fs.makeTempDirectoryScoped({ prefix: "packall-" });
 		const packagesDir = path.join(staging, "packages");
 		yield* fs.makeDirectory(packagesDir, { recursive: true });

package/src/dependency-range.ts

@@ -1,14 +1,3 @@
-/**
- * Classification of the right-hand side of a dependency entry.
- *
- * `"dependencies": { "x": "^1.0.0" }` is the easy case. Real package.json files
- * also contain aliases, git URLs, tarball URLs, `file:` links and
- * `workspace:` protocols — none of which can be fetched from a registry.
- *
- * Rather than crashing or silently producing a bundle that will not install,
- * we classify each edge and let the caller report precisely what was skipped
- * and why.
- */
 import semver from "semver";
 
 import type { Selector } from "./spec.js";

package/src/download.ts

@@ -1,10 +1,3 @@
-/**
- * Fetching tarballs into the staging tree.
- *
- * Downloads run concurrently, every one is checksum-verified before it is
- * written, and the destination is always the scoped temp directory — nothing
- * lands next to the user's own files.
- */
 import type * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";

package/src/errors.ts

@@ -1,16 +1,3 @@
-/**
- * Failure types for the bundler.
- *
- * These are deliberately plain classes carrying a literal `_tag` rather than
- * `Data.TaggedError`. They work with `Effect.catchTag` / `Effect.catchTags`
- * exactly the same way, and they keep the public error surface independent of
- * any single Effect release — useful while Effect v4 is still in beta.
- *
- * Every error carries enough context to be actionable without a stack trace,
- * because the primary consumer is somebody staring at a terminal on a
- * locked-down network trying to work out why a download did not happen.
- */
-
 /** Discriminant union of every failure the bundler can produce. */
 export type BundlerError =
 	| InvalidSpecError
@@ -29,6 +16,9 @@ export type BundlerError =
 	| ArchiveError
 	| OutputError;
 
+// Plain classes with a literal `_tag` rather than `Data.TaggedError`. They work
+// with `catchTag` / `catchTags` identically, and this keeps the public error
+// surface off a helper that may still move while Effect v4 is in beta.
 abstract class BundlerErrorBase extends Error {
 	abstract readonly _tag: string;
 	constructor(message: string, options?: ErrorOptions) {

package/src/index.ts

@@ -1,14 +1,3 @@
-/**
- * `@packall/core` — the registry-agnostic bundling engine.
- *
- * Nothing in here knows about npm specifically. Point it at any implementation
- * of the `Registry` service and it will resolve, download, verify and package
- * a dependency closure.
- *
- * This is the package's whole public API. Everything not named here is an
- * implementation detail, including modules that happen to be reachable.
- */
-
 export type * from "./errors.js";
 export {
 	ArchiveError,
@@ -88,9 +77,8 @@ export type { IntegrityAlgorithm, IntegrityHash, VerificationResult } from "./in
 export { digestOf, hexDigestOf, parseIntegrity, verify as verifyIntegrity } from "./integrity.js";
 
 // The packing backend. The Node implementation is deliberately *not* re-exported
-// here — it lives behind `@packall/core/node`, because it pulls in `node-tar` and
-// reaching it has to be an explicit act so importing the engine stays safe in a
-// browser.
+// here — it pulls in `node-tar`, so reaching it has to be an explicit import of
+// `@packall/core/node`.
 export type { ArchiveResult, CreateArchiveOptions } from "./archive.js";
 export { Archiver, createArchive } from "./archive.js";
 

package/src/input-file.ts

@@ -1,18 +1,3 @@
-/**
- * `--file` handling.
- *
- * One flag, three accepted shapes, detected from the content rather than the
- * extension so that `--file deps.json` and `--file my-packages` both do the
- * obvious thing:
- *
- * - a **package.json** — bundle everything it depends on
- * - a **lockfile** — npm, pnpm or bun; bundle the exact versions it pins
- * - a **newline-delimited list** — one spec per line, `#` and `//` comments
- *   allowed, blank lines ignored
- *
- * A lockfile is checked for first, because `package-lock.json` and
- * `package.json` are both JSON objects and only the content tells them apart.
- */
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Option from "effect/Option";

package/src/integrity.ts

@@ -1,17 +1,3 @@
-/**
- * Checksum verification for downloaded tarballs.
- *
- * A failed check discards the download rather than warning and carrying on —
- * see `notes/requirements.md` § FR-9 for why that strictness is a requirement
- * rather than a preference.
- *
- * Built on Effect's `Crypto` service rather than `node:crypto` directly. The
- * four digests `Crypto` offers — SHA-1, SHA-256, SHA-384, SHA-512 — are exactly
- * the four npm publishes, so nothing is given up, and the same verification
- * then runs unchanged against WebCrypto in a browser. Parsing stays here
- * because the subset of Subresource Integrity npm actually emits is small and
- * entirely mechanical; `ssri` would be a dependency for a regex.
- */
 import * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
 import * as Encoding from "effect/Encoding";

package/src/layout.ts

@@ -1,23 +1,3 @@
-/**
- * The on-disk shape of a bundle.
- *
- * Under every layout but `flat`, everything is laid out exactly the way a
- * registry serves it:
- *
- *     lodash/-/lodash-4.17.21.tgz
- *     @babel/core/-/core-7.24.0.tgz
- *
- * That is not an Artifactory convention — it is the path structure in every
- * `dist.tarball` URL npm publishes. See `notes/requirements.md` § FR-12 for
- * what that buys.
- *
- * The one shape worth noticing before editing anything here: a scoped
- * package's file name drops the scope, so `@babel/core` becomes
- * `core-7.24.0.tgz` under an `@babel/core/-/` directory.
- *
- * `flat` layout is the exception; `bundlePath` is where the two part company.
- */
-
 import { Layout } from "./enums/layout.js";
 
 /** Splits `@scope/name` into its parts. `scope` is undefined when unscoped. */
@@ -30,7 +10,12 @@ export const splitName = (
 	return { scope: name.slice(0, slash), bare: name.slice(slash + 1) };
 };
 
-/** `@babel/core` + `7.24.0` -> `core-7.24.0.tgz` */
+/**
+ * `@babel/core` + `7.24.0` -> `core-7.24.0.tgz`
+ *
+ * The scope is dropped, because that is what the registry serves. It is also
+ * why a flat directory of tarballs cannot use this name — see {@link flatName}.
+ */
 export const tarballFileName = (name: string, version: string): string => {
 	const { bare } = splitName(name);
 	return `${bare}-${version}.tgz`;
@@ -51,43 +36,22 @@ export const MANIFEST_FILE = "bundle-manifest.json";
 export const README_FILE = "IMPORT.md";
 
 /**
- * A flat, collision-free file name for one `name@version`.
- *
- * It is the spec, with the one character a file name cannot hold taken out:
- * `@types/react@19.2.18` becomes `@types-react@19.2.18.tgz`. So the name of the
- * file answers the question somebody has when they are looking at a directory
- * of them — which package, and which version — in the notation they would have
- * typed to ask for it.
- *
- * The version is joined with `@` rather than `-` for the same reason. A
- * hyphen made `foo-bar-1.0.0` ambiguous by eye: package `foo` at `bar-1.0.0`,
- * or `foo-bar` at `1.0.0`? npm's own syntax has no such problem, because a
- * package name may not contain `@` beyond its scope.
- *
- * **The scope's `@` stays**, and it is the difference between a correct bundle
- * and a quietly incomplete one.
- *
- * Dropping it — which this did, matching what `npm pack` produces — meant
- * `@something/somewhat` and `something-somewhat` were both
- * `something-somewhat-1.0.0.tgz`. Two different packages, one path: the second
- * landed on the first, and the run reported two artifacts for the one file that
- * survived. A bundle short a package, called complete, found at the far end of
- * an air gap.
- *
- * Keeping the `@` makes that impossible by construction rather than by a check,
- * because an unscoped npm name may not begin with one. It is also the more
- * honest name: the scope is part of what the package *is*, and a directory of
- * archives that has forgotten which ones were scoped is a directory somebody
- * has to cross-reference against a manifest.
- *
- * It does not make every collision impossible — `@a/b-c` and `@a-b/c` still
- * meet — so the run still checks before downloading anything. That pair is
- * pathological; the scoped-against-unscoped one is `@babel/core` beside
- * `babel-core`, which is a real migration somebody could be bundling.
- *
- * The leading `@` is safe here in a way it is not inside the archive: tar's
- * splice convention applies to the *file list* it is given, which is what
- * `archive.ts` guards with `./`. These are output paths, not entries.
+ * A flat, collision-free file name for one `name@version`:
+ * `@types/react@19.2.18` becomes `@types-react@19.2.18.tgz`.
+ *
+ * **The scope's `@` stays.** Dropping it — which this did, matching `npm pack`
+ * — put `@something/somewhat` and `something-somewhat` on the same file name,
+ * and the run reported two artifacts for the one file that survived. Keeping it
+ * makes that impossible by construction rather than by a check, because an
+ * unscoped npm name may not begin with `@`.
+ *
+ * The version joins with `@` rather than `-` because `foo-bar-1.0.0` is
+ * ambiguous by eye: `foo` at `bar-1.0.0`, or `foo-bar` at `1.0.0`?
+ *
+ * `@a/b-c` against `@a-b/c` still collides, so callers check before
+ * downloading. The leading `@` is safe here in a way it is not inside an
+ * archive: tar's splice convention applies to the entry list, which the
+ * archiver guards with `./`. These are output paths, not entries.
  */
 export const flatName = (name: string, version: string): string => {
 	const { scope, bare } = splitName(name);

package/src/locked-resolve.ts

@@ -1,22 +1,3 @@
-/**
- * Resolution driven by a lockfile instead of by semver.
- *
- * The distinction matters more than it first looks. Feeding a lockfile's
- * versions in as exact root specs and letting the ordinary walk run would still
- * produce the wrong bundle: every *transitive* edge is a range, and
- * `Resolve.walk` answers a range with whatever is newest today. Lock `tslib` at
- * 2.6.0 and let something depending on `tslib@^2` be re-resolved, and the
- * bundle grows a second copy at 2.8.1 that CI never installed.
- *
- * So the lockfile is treated as the graph, not as a set of hints. The package
- * set *is* what the file pins, and every edge is satisfied from inside it.
- * Nothing here calls `selectVersions`; the only thing the registry is asked for
- * is the metadata that a lockfile does not record — `dist`, and the `os`/`cpu`
- * constraints that `--platform` narrows on.
- *
- * The result is an ordinary `Resolution`, so layout, archiving, the manifest
- * and the summary cannot tell which path produced it.
- */
 import * as Effect from "effect/Effect";
 import semver from "semver";
 
@@ -78,6 +59,11 @@ export const resolveLocked = (
 		// Everything the lockfile can reach, before the platform filter has had a
 		// say. Cheap — no network at all — and it is what decides the fetch list.
 		const reachable = reachableKeys(lock, roots, options);
+		// Nothing here re-resolves a range. Handing these versions to `Resolve.walk`
+		// instead would answer every *transitive* range with whatever is newest
+		// today, so a lockfile pinning `tslib@2.6.0` would still gain a 2.8.1 that
+		// CI never installed. The registry is asked only for what a lockfile does
+		// not record.
 		const manifests = yield* fetchManifests(lock, reachable, options);
 
 		const warnings: Array<ResolutionWarning> = lock.warnings.map((message) => ({ message }));

package/src/lockfile/bun.ts

@@ -1,11 +1,3 @@
-/**
- * `bun.lock`.
- *
- * Like npm, bun records ranges on its edges and resolves them through the
- * install-path nesting — but it nests with a plain `/`, and package names
- * contain `/` too, so the parent of a key can only be found by asking which
- * prefixes are themselves entries.
- */
 import { EdgeKind, LockedRootKind } from "../enums/edge-kind.js";
 import { LockfileFormat } from "../enums/lockfile-format.js";
 import { isRecord } from "../utils/is-record.js";

package/src/lockfile/detect.ts

@@ -1,10 +1,3 @@
-/**
- * Working out which lockfile — if any — some content is.
- *
- * Detection is by content, matching how `--file` treats everything else: a
- * lockfile renamed to `deps.txt` still parses, and a `package-lock.json` that
- * is actually a package.json still gets read as one.
- */
 import { LockfileFormat } from "../enums/lockfile-format.js";
 import { isRecord } from "../utils/is-record.js";
 import { tryParseJsonc } from "./json.js";

package/src/lockfile/json.ts

@@ -1,12 +1,3 @@
-/**
- * Narrowing helpers for the untyped JSON and YAML a lockfile parses into.
- *
- * Everything here takes `unknown` and hands back something narrowed, which is
- * what keeps the parsers free of casts against files nobody controls. The
- * shape-level narrowing is Effect Schema — the same decoders the registry
- * response boundary uses — so "tolerated" means one thing across the codebase
- * rather than being re-decided per parser.
- */
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 

package/src/lockfile/npm.ts

@@ -1,11 +1,3 @@
-/**
- * `package-lock.json` / `npm-shrinkwrap.json`.
- *
- * npm records *ranges* on its edges and relies on the directory nesting to say
- * which copy of a package a range resolved to, so the node resolution walk-up —
- * look beside me, then in my parent, then my grandparent — is reimplemented
- * here.
- */
 import { EdgeKind, LockedRootKind } from "../enums/edge-kind.js";
 import { LockfileFormat } from "../enums/lockfile-format.js";
 import { isRecord } from "../utils/is-record.js";

package/src/lockfile/parse.ts

@@ -1,17 +1,3 @@
-/**
- * Lockfile parsing — npm, pnpm and bun.
- *
- * `--file package.json` reads *ranges*, and a range resolves to whatever is
- * newest at the moment the command runs. That is the right answer for "bundle
- * me something installable" and the wrong one for "bundle exactly what CI
- * installed" — which is what a lockfile records and what this module reads.
- *
- * Three formats, one output shape. Each parser's real job is the same: turn a
- * manager-specific encoding of "package X at path P depends on Y" into a flat
- * graph keyed by `name@version`, with every edge already pointing at a concrete
- * version. Once that is done, nothing downstream has to know which manager
- * wrote the file.
- */
 import { LockfileFormat } from "../enums/lockfile-format.js";
 import { LockfileError } from "../errors.js";
 import { parseBunLockfile } from "./bun.js";

package/src/lockfile/pnpm.ts

@@ -1,10 +1,3 @@
-/**
- * `pnpm-lock.yaml`.
- *
- * The easy one: pnpm's snapshots already name exact versions, so there is no
- * nesting walk-up to reimplement. The fiddly parts are the three package-key
- * encodings still in the wild and the parenthesised peer-resolution suffix.
- */
 import semver from "semver";
 import { parse as parseYaml } from "yaml";
 

package/src/lockfile/tree-builder.ts

@@ -1,9 +1,3 @@
-/**
- * The bookkeeping every lockfile parser shares.
- *
- * Packages, edges and skip warnings accumulate here while a parser walks a
- * file, which is what lets each parser stay focused on its own encoding.
- */
 import semver from "semver";
 
 import { parseDependencyTarget } from "../dependency-range.js";

package/src/lockfile/types.ts

@@ -1,10 +1,3 @@
-/**
- * The one output shape every lockfile parser produces.
- *
- * npm, pnpm and bun encode "package X at path P depends on Y" in three
- * different ways; once flattened into this graph, nothing downstream has to
- * know which manager wrote the file.
- */
 import type { EdgeKind, LockedRootKind } from "../enums/edge-kind.js";
 import type { LockfileFormat } from "../enums/lockfile-format.js";
 

package/src/manifest.ts

@@ -1,7 +1,3 @@
-/**
- * The manifest written into every bundle — the audit trail, answerable without
- * unpacking a single tarball. See `notes/requirements.md` § FR-10.
- */
 import { bundlePath } from "./layout.js";
 import type { BundleOptions } from "./options.js";
 import { formatPlatformFilter } from "./platform.js";

package/src/node/archiver.ts

@@ -1,15 +1,3 @@
-/**
- * The Node `Archiver`, backed by `node-tar`.
- *
- * Behind `@packall/core/node` rather than the main barrel: importing
- * `@packall/core` must not drag `node-tar` — and through it `node:fs` — into a
- * browser bundle. Anything running on Node reaches for this explicitly.
- *
- * Uses `node-tar`, the same library npm itself packs with. Writing a USTAR
- * encoder by hand would be a fun afternoon and a bad idea: scoped package
- * paths routinely exceed the 100-byte name field, so correctness depends on
- * prefix-splitting and PAX headers that `tar` already gets right.
- */
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
@@ -20,6 +8,10 @@ import type { ArchiveResult, CreateArchiveOptions } from "../archive.js";
 import { Archiver } from "../archive.js";
 import { ArchiveError } from "../errors.js";
 
+// node-tar is what npm itself packs with, and the dependency is load-bearing
+// rather than convenient: scoped package paths routinely exceed tar's 100-byte
+// name field, so anything hand-written here would have to get prefix-splitting
+// and PAX headers right before npm could read the result.
 const createArchive = (
 	options: CreateArchiveOptions,
 ): Effect.Effect<ArchiveResult, ArchiveError | PlatformError, FileSystem.FileSystem> =>

package/src/node/index.ts

@@ -1,14 +1,2 @@
-/**
- * `@packall/core/node` — the engine's Node-specific layers.
- *
- * Everything here is separated from the main barrel for one reason: importing
- * `@packall/core` must stay safe in a browser. The engine itself reaches the
- * outside world only through services — `Registry`, `Progress`, `Archiver`,
- * `FileSystem`, `Path`, `Crypto` — so the platform lives at the edges, and this
- * is the Node edge. A browser supplies its own.
- *
- * This is the entry point's whole public API.
- */
-
 export { layerArchiver } from "./archiver.js";
 export { currentPlatform } from "./platform.js";

package/src/node/platform.ts

@@ -1,13 +1,3 @@
-/**
- * The machine we are currently running on.
- *
- * One function, in its own file, for the reason the whole `/node` subpath
- * exists: it reads `process`, and importing `@packall/core` has to stay safe in
- * a browser. Everything else in `platform.ts` is string work over what a
- * manifest declares — it has no host and needs none, so it stays on the main
- * entry where the engine can reach it.
- */
-
 import type { PlatformTarget } from "../platform.js";
 
 /** The machine we are currently running on. */

package/src/options.ts

@@ -1,10 +1,3 @@
-/**
- * Option types shared by the resolver and the bundler, plus their defaults.
- *
- * The rule the defaults below are derived from is stated once, beside the flags
- * that expose them — see `descriptors.ts` in `@packall/cli`, and
- * `notes/requirements.md` § FR-13.
- */
 import { Layout } from "./enums/layout.js";
 import type { PlatformFilter } from "./platform.js";
 import { allPlatforms } from "./platform.js";

package/src/platform.ts

@@ -1,14 +1,3 @@
-/**
- * Platform matching for optional dependencies.
- *
- * The default is "keep every platform" and narrowing is opt-in — see
- * `notes/requirements.md` § FR-13 for the failure mode that decides it.
- *
- * The mechanics that decision rests on are here rather than there: a package
- * declares `os`, `cpu` and `libc` in its own manifest, and this module keeps a
- * package when the filter *could* install it, not when it matches exactly.
- */
-
 /** A target to keep, e.g. `linux-x64`, `linux-x64-musl`, or just `linux`. */
 export type PlatformTarget = {
 	readonly os: string;

package/src/progress.ts

@@ -1,11 +1,3 @@
-/**
- * Progress reporting.
- *
- * The engine emits structured events; it never writes to a terminal. That
- * separation is what lets the CLI draw a live TTY view, CI print plain lines,
- * and the test suite assert on an array of events without any of them
- * interfering with each other.
- */
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";

package/src/registry.ts

@@ -1,15 +1,3 @@
-/**
- * The registry seam.
- *
- * This is the **only** place in the engine that knows a registry exists.
- * Everything downstream — range resolution, the dependency walk, layout,
- * archiving — is expressed against these three operations, so swapping npm for
- * something else means implementing this interface and nothing more.
- *
- * `@packall/registry-npm` provides the implementation that speaks the plain
- * npm registry protocol, which is what Artifactory, Nexus, Verdaccio, GitHub
- * Packages and registry.npmjs.org all serve.
- */
 import * as Context from "effect/Context";
 import type * as Effect from "effect/Effect";
 
@@ -100,6 +88,11 @@ export declare namespace Registry {
 /**
  * Service tag for the registry backend.
  *
+ * The engine's only route to a registry. Version selection, the dependency
+ * walk, layout and archiving are all written against these four operations, so
+ * backing a registry that does not speak the npm protocol means implementing
+ * this interface and nothing else.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"

package/src/resolve.ts

@@ -1,21 +1,3 @@
-/**
- * Version selection and the dependency closure walk.
- *
- * This is the part that decides *what* ends up in a bundle. Its only side
- * effect is asking the `Registry` service for metadata, which makes the whole
- * of it testable against a fake registry with no network at all.
- *
- * The walk is breadth-first in waves: resolve the current frontier
- * concurrently, collect the newly discovered edges, repeat. Wave-based BFS
- * gives real parallelism without a dynamic worker pool, and because each wave
- * merges its results serially there is no shared mutable state being written
- * from more than one fiber.
- *
- * One subtlety worth calling out: metadata is cached across walks, but each
- * walk still traverses the full graph. That is what lets `per-spec` layout ask
- * "what does *this* root version depend on" many times over while the network
- * is touched exactly once per package.
- */
 import * as Effect from "effect/Effect";
 import semver from "semver";
 
@@ -352,6 +334,10 @@ const walk = (
 			}
 			if (wave.length === 0) break;
 
+			// A wave resolves concurrently and then merges serially below. That is
+			// what gives real parallelism without a worker pool, and it is why
+			// nothing writes to `state` from more than one fiber — moving the merge
+			// inside `resolveTask` would reintroduce exactly that.
 			const results = yield* Effect.forEach(
 				wave,
 				(task) => resolveTask(state, task, options),

package/src/schemas/lenient.ts

@@ -1,18 +1,3 @@
-/**
- * Schemas for JSON nobody controls.
- *
- * Registry responses, lockfiles and hand-edited package.json files all arrive
- * as untyped JSON, and the rule at every one of those boundaries is the same:
- * drop what cannot be understood, keep the rest. A bundler that rejects a
- * packument because one published version carries a field it has never seen is
- * useless against exactly the private registries it exists to serve.
- *
- * Effect Schema does the narrowing, which is what keeps those boundaries free
- * of casts and hand-rolled `typeof` ladders. What this module adds on top of
- * the stock combinators is that tolerance: `Schema.Record(String, String)`
- * fails the whole record over one numeric value, where the wire format wants
- * that entry skipped and its neighbours kept.
- */
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";