@avi2dg/checks 0.22.0 → 0.24.0

package/docs/gates/checks-repetition.md

@@ -16,6 +16,7 @@ A file that repeats lines without a rise is advisory.
 ## What it reads
 
 jscpd reads the head's `.jscpd.json` at both ends, so its `path` and `ignore` globs select the files to measure.
+A `path` entry the base revision lacks reads as empty there, so a newly measured folder never fails the scan.
 
 ```json
 { "path": ["src"], "format": ["typescript"], "ignore": ["**/*.d.ts"] }

package/docs/gates/checks-vendor.md

@@ -16,9 +16,12 @@ The clone is staged beside its cache entry and moves into place only once it is
 Every later run verifies the link rather than trusting it, and does so without contacting the remote.
 It confirms the tree sits on the recorded commit.
 It confirms the manifest inside the tree still names the installed version.
-It confirms no write bit came back and no write landed outside the recorded commit.
+It confirms no write bit is left once it has frozen the tree and no write landed outside the recorded commit.
 It never follows a link inside the tree, so no mode outside the cache is touched.
-Any failed confirmation fails the run.
+A tool that clears the read only mode of `repos/<name>` changes the tree's top directory through the link, as the GitHub Actions runner does when it empties `$RUNNER_TEMP`.
+A run that finds an owner write bit strips it from the tree again, then confirms no write landed outside the recorded commit.
+A group or other write bit is never stripped, and fails the run before it reads the tree's status.
+Any other failed confirmation fails the run, and so does a write the tree still holds once it is read only again.
 A failed library drops its `repos/<name>` link, so a reader falls back to `node_modules/<package>` rather than a tree the run could not vouch for.
 A missing tag, an unknown installed version or a manifest naming another version fails it too.
 A tag moved upstream after the first fetch is not followed, since a cached tree stays on its recorded commit.
@@ -68,6 +71,12 @@ checks-vendor: repos/effect still holds effect@4.0.0-rc.115, verified against it
 
 A later run reports the link it kept.
 
+```
+checks-vendor: found 1 path writable by its owner, starting with /home/runner/.cache/avi2dg-checks/repos/github.com/Effect-TS/effect/effect@4.0.0-rc.115, and froze the tree again, so repos/effect still holds effect@4.0.0-rc.115, verified against its recorded commit
+```
+
+A run that found an owner write bit reports how many paths carried one and the first of them.
+
 ## Wiring
 
 A consuming repository runs it from its `prepare` script, so every install pins and verifies the trees.

package/oxlintrc.json

@@ -1,6 +1,6 @@
 {
   "plugins": ["typescript", "oxc", "eslint", "import"],
-  "jsPlugins": ["./dist/index.js"],
+  "jsPlugins": ["./dist/effect-channel/index.js", "./dist/readability/index.js"],
   "categories": { "correctness": "error", "suspicious": "error" },
   "rules": {
     "effect-channel/no-error-channel-escape": "error",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -25,6 +25,10 @@
     "scripts/git.ts",
     "scripts/gates.ts",
     "scripts/lint.ts",
+    "scripts/changelog.ts",
+    "scripts/changelog-write.ts",
+    "scripts/release-notes.ts",
+    "scripts/release-report.ts",
     "scripts/test-layout.ts",
     "scripts/test.ts",
     "scripts/test-skips.ts",
@@ -47,6 +51,7 @@
     "scripts/quarantine-clock.ts",
     "scripts/docs.ts",
     "scripts/vendor.ts",
+    "scripts/vendor-args.ts",
     "scripts/doc-outline.ts",
     "scripts/doc-rules.ts",
     "scripts/doc-references.ts",
@@ -58,7 +63,8 @@
     "oxlintrc.json",
     "stryker.preset.js",
     "tsconfig.effect.json",
-    "dist/index.js"
+    "dist/effect-channel/index.js",
+    "dist/readability/index.js"
   ],
   "exports": {
     "./bunfig.toml": "./bunfig.toml",
@@ -66,6 +72,10 @@
     "./dependency-cruiser.config.js": "./dependency-cruiser.config.js",
     "./scripts/lint-coverage.sh": "./scripts/lint-coverage.sh",
     "./scripts/lint.ts": "./scripts/lint.ts",
+    "./scripts/changelog.ts": "./scripts/changelog.ts",
+    "./scripts/changelog-write.ts": "./scripts/changelog-write.ts",
+    "./scripts/release-notes.ts": "./scripts/release-notes.ts",
+    "./scripts/release-report.ts": "./scripts/release-report.ts",
     "./scripts/test-layout.ts": "./scripts/test-layout.ts",
     "./scripts/test.ts": "./scripts/test.ts",
     "./scripts/test-skips.ts": "./scripts/test-skips.ts",
@@ -98,10 +108,14 @@
     "./oxlintrc.json": "./oxlintrc.json",
     "./stryker.preset.js": "./stryker.preset.js",
     "./tsconfig.effect.json": "./tsconfig.effect.json",
-    "./dist/index.js": "./dist/index.js"
+    "./dist/effect-channel/index.js": "./dist/effect-channel/index.js",
+    "./dist/readability/index.js": "./dist/readability/index.js"
   },
   "bin": {
     "checks-lint": "scripts/lint.ts",
+    "checks-changelog": "scripts/changelog-write.ts",
+    "checks-release-notes": "scripts/release-notes.ts",
+    "checks-release-report": "scripts/release-report.ts",
     "checks-lint-coverage": "scripts/lint-coverage.sh",
     "checks-test-layout": "scripts/test-layout.ts",
     "checks-test": "scripts/test.ts",
@@ -120,7 +134,7 @@
   },
   "scripts": {
     "prepare": "bun scripts/vendor.ts --library effect --package effect --repository https://github.com/Effect-TS/effect.git --tag 'effect@{version}' --path packages/effect/package.json",
-    "build": "bun build effect-channel/index.ts --outdir dist --target node --format esm && bun scripts/doc-templates-write.ts && bun scripts/changelog-write.ts && bun scripts/doc-blocks-write.ts",
+    "build": "bun build effect-channel/index.ts --outdir dist/effect-channel --target node --format esm && bun build readability/index.ts --outdir dist/readability --target node --format esm && bun scripts/doc-templates-write.ts && bun scripts/changelog-write.ts && bun scripts/doc-blocks-write.ts",
     "lint": "oxlint --type-aware && bun scripts/lint.ts && depcruise --config .dependency-cruiser.cjs .",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
     "test": "bun scripts/test.ts"

package/scripts/changelog-write.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env bun
+import { Console, DateTime, Effect, FileSystem, Path, Schema } from "effect";
+import { cuts, releaseDates, renderChangelog, type Bump, type Cut, type Release } from "./changelog.ts";
+import { git } from "./git.ts";
+import { runMain } from "./main.ts";
+
+const NAME = "checks-changelog";
+const CHANGELOG = "CHANGELOG.md";
+const MANIFEST = "package.json";
+const FIELD = "\x1f";
+const TAG_PREFIX = "v";
+
+class ChangelogUnreadable extends Schema.TaggedError<ChangelogUnreadable>()("ChangelogUnreadable", {
+  message: Schema.String,
+}) {}
+
+const decodeManifestJson = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(
+    Schema.Struct({
+      name: Schema.String,
+      version: Schema.String,
+      repository: Schema.optional(Schema.Union([Schema.String, Schema.Struct({ url: Schema.optional(Schema.String) })])),
+    }),
+  ),
+);
+
+const decodeManifest = (text: string, source: string) =>
+  decodeManifestJson(text).pipe(Effect.mapError((cause) => new ChangelogUnreadable({ message: `${source}: ${cause.message}` })));
+
+const today = DateTime.nowInCurrentZone.pipe(DateTime.withCurrentZoneLocal, Effect.map(DateTime.formatIsoDate));
+
+function repositoryWebUrl(repository: string): string | undefined {
+  const url = repository
+    .replace(/^git\+/, "")
+    .replace(/\/$/, "")
+    .replace(/\.git$/, "");
+  return url.startsWith("https://") ? url : undefined;
+}
+
+const versionAt = Effect.fn("versionAt")(function* (root: string, sha: string) {
+  return (yield* decodeManifest(yield* git(["show", `${sha}:${MANIFEST}`], root), `${MANIFEST} at ${sha}`)).version;
+});
+
+const readBumps = Effect.fn("readBumps")(function* (root: string) {
+  const log = yield* git(
+    ["log", "--topo-order", "--reverse", "--full-history", "--no-merges", '-G"version"', "--format=%H%x1f%as%x1f%P", "HEAD", "--", MANIFEST],
+    root,
+  );
+  const bumps: Bump[] = [];
+  for (const line of log.split("\n")) {
+    const [sha, date, parent] = line.split(FIELD);
+    if (sha === undefined || date === undefined || parent === undefined) continue;
+    const version = yield* versionAt(root, sha);
+    if (parent === "" || (yield* versionAt(root, parent)) !== version) bumps.push({ sha, version, date });
+  }
+  return bumps;
+});
+
+const readPublished = Effect.fn("readPublished")(function* (root: string) {
+  const tags = yield* git(["for-each-ref", "--format=%(refname:strip=2)", `refs/tags/${TAG_PREFIX}*`], root);
+  return new Set(tags.split("\n").flatMap((tag) => (tag.startsWith(TAG_PREFIX) ? [tag.slice(TAG_PREFIX.length)] : [])));
+});
+
+const subjectsOf = Effect.fn("subjectsOf")(function* (root: string, { version, date, through, after }: Cut) {
+  const log = yield* git(["log", "--topo-order", "--format=%s", through, "--not", ...after], root);
+  return { version, date, subjects: log.split("\n").filter((subject) => subject !== "") } satisfies Release;
+});
+
+const write = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  if ((yield* git(["rev-parse", "--is-shallow-repository"], root)).trim() === "true") {
+    return yield* new ChangelogUnreadable({ message: "the checkout is shallow, so the releases reach back past its history; fetch all of it" });
+  }
+  const target = path.join(root, CHANGELOG);
+  const { name, version, repository } = yield* decodeManifest(yield* fs.readFileString(path.join(root, MANIFEST)), MANIFEST);
+  const url = typeof repository === "string" ? repository : repository?.url;
+  if (url === undefined) {
+    return yield* new ChangelogUnreadable({ message: `${MANIFEST} has no repository.url, which the changelog links each pull request under` });
+  }
+  const repositoryUrl = repositoryWebUrl(url);
+  if (repositoryUrl === undefined) {
+    return yield* new ChangelogUnreadable({ message: `${MANIFEST} repository ${url} is no https address, which the changelog links each pull request under` });
+  }
+  const recorded = (yield* fs.exists(target)) ? releaseDates(yield* fs.readFileString(target)) : new Map<string, string>();
+  const pending = version === (yield* versionAt(root, "HEAD")) ? undefined : { sha: "HEAD", version, date: yield* today };
+  const released = cuts(yield* readBumps(root), recorded, yield* readPublished(root), pending);
+  const found = (yield* Effect.forEach(released, (cut) => subjectsOf(root, cut))).toReversed();
+  yield* fs.writeFileString(target, renderChangelog(name, found, repositoryUrl));
+  yield* Console.log(`${NAME}: wrote ${found.length} release(s) to ${CHANGELOG}`);
+  return true;
+});
+
+if (import.meta.main) runMain(NAME, write);

package/scripts/changelog.ts

@@ -0,0 +1,110 @@
+import { firstText, parseOutline, VERSION } from "./doc-outline.ts";
+import { RELEASED } from "./doc-rules.ts";
+import { CHANGE_GROUPS, type ChangeGroup } from "./doc-templates.ts";
+
+export type Bump = {
+  readonly sha: string;
+  readonly version: string;
+  readonly date: string;
+};
+
+export type Cut = {
+  readonly version: string;
+  readonly date: string;
+  readonly through: string;
+  readonly after: readonly string[];
+};
+
+export type Release = {
+  readonly version: string;
+  readonly date: string;
+  readonly subjects: readonly string[];
+};
+
+type Entry = {
+  readonly group: ChangeGroup;
+  readonly text: string;
+};
+
+const CONVENTIONAL = /^([a-z]+)(?:\(([^()]*)\))?(!)?: (\S.*)$/;
+
+const GROUP_OF_TYPE = new Map<string, ChangeGroup>([
+  ["feat", "Features"],
+  ["fix", "Fixes"],
+  ["perf", "Performance"],
+  ["revert", "Reverts"],
+]);
+
+// Only the subject is linted, and a squash merge's body is its branch's commit messages,
+// so a breaking change is read from the subject's `!` and never from a footer.
+export function groupOf(subject: string): ChangeGroup | undefined {
+  const [, type = "", , breaking] = CONVENTIONAL.exec(subject) ?? [];
+  return breaking === "!" ? "Breaking changes" : GROUP_OF_TYPE.get(type);
+}
+
+function entryOf(subject: string, repositoryUrl: string): Entry | undefined {
+  const group = groupOf(subject);
+  if (group === undefined) return undefined;
+  const [, , scope = "", , description = ""] = CONVENTIONAL.exec(subject) ?? [];
+  const linkedDescription = description.replace(/ \(#(\d+)\)$/, (_, number: string) => ` [#${number}](${repositoryUrl}/pull/${number})`);
+  return { group, text: scope === "" ? linkedDescription : `**${scope}:** ${linkedDescription}` };
+}
+
+// A bump not newer than the release before it is a revert: it cancels every release above the version it
+// returns to, except a published one.
+function standing(bumps: readonly Bump[], published: ReadonlySet<string>): readonly Bump[] {
+  return bumps.reduce<readonly Bump[]>((kept, bump) => {
+    const before = kept.at(-1);
+    if (before === undefined || Bun.semver.order(bump.version, before.version) === 1) return [...kept, bump];
+    return kept.filter(({ version }) => published.has(version) || Bun.semver.order(version, bump.version) !== 1);
+  }, []);
+}
+
+// The changelog records what was released: a version older than the newest it lists and absent from it
+// was never published, so its commits roll into the next release.
+export function cuts(
+  bumps: readonly Bump[],
+  recorded: ReadonlyMap<string, string>,
+  published: ReadonlySet<string>,
+  pending: Bump | undefined,
+): readonly Cut[] {
+  const newest = [...recorded.keys()].toSorted(Bun.semver.order).at(-1);
+  const candidates = standing(pending === undefined ? bumps : [...bumps, pending], published);
+  const released = candidates.filter(
+    ({ version }, index) =>
+      index === candidates.length - 1 || newest === undefined || recorded.has(version) || Bun.semver.order(version, newest) !== -1,
+  );
+  return released.map(({ sha, version, date }, index) => ({
+    version,
+    date: recorded.get(version) ?? date,
+    through: sha,
+    after: released.slice(0, index).map((earlier) => earlier.sha),
+  }));
+}
+
+function renderRelease({ version, date, subjects }: Release, repositoryUrl: string): readonly string[] {
+  const entries = subjects.flatMap((subject) => entryOf(subject, repositoryUrl) ?? []);
+  const groups = CHANGE_GROUPS.flatMap((group) => {
+    const listed = entries.filter((entry) => entry.group === group).map(({ text }) => `- ${text}`);
+    return listed.length === 0 ? [] : [`### ${group}`, listed.join("\n")];
+  });
+  return [`## ${version}`, `Released ${date}.`, ...groups];
+}
+
+export function renderChangelog(name: string, found: readonly Release[], repositoryUrl: string): string {
+  const blocks = [
+    "# Changelog",
+    `Every release of \`${name}\`, newest first, written by the release from its conventional commits.`,
+    ...found.flatMap((release) => renderRelease(release, repositoryUrl)),
+  ];
+  return `${blocks.join("\n\n")}\n`;
+}
+
+export function releaseDates(text: string): ReadonlyMap<string, string> {
+  return new Map(
+    parseOutline(text).sections.flatMap(({ heading, body }) => {
+      const date = RELEASED.exec(firstText(body)?.text.trim() ?? "")?.[1];
+      return VERSION.test(heading.title) && date !== undefined ? [[heading.title, date] as const] : [];
+    }),
+  );
+}

package/scripts/release-notes.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env bun
+import { Effect, FileSystem, Schema } from "effect";
+import { runMain, Usage } from "./main.ts";
+
+export class ReleaseSectionUnavailable extends Schema.TaggedError<ReleaseSectionUnavailable>()("ReleaseSectionUnavailable", {
+  message: Schema.String,
+}) {}
+
+export function extractReleaseNotes(changelog: string, version: string): Effect.Effect<string, ReleaseSectionUnavailable> {
+  const lines = changelog.split(/\r?\n/);
+  const heading = lines.indexOf(`## ${version}`);
+  if (heading === -1) return Effect.fail(new ReleaseSectionUnavailable({ message: `CHANGELOG.md has no section for ${version}` }));
+
+  const next = lines.findIndex((line, index) => index > heading && line.startsWith("## "));
+  const body = lines.slice(heading + 1, next === -1 ? lines.length : next);
+  let start = 0;
+  let end = body.length;
+  while (start < end && body[start]?.trim() === "") start += 1;
+  while (end > start && body[end - 1]?.trim() === "") end -= 1;
+  const notes = body.slice(start, end).join("\n");
+  return notes === ""
+    ? Effect.fail(new ReleaseSectionUnavailable({ message: `CHANGELOG.md has an empty section for ${version}` }))
+    : Effect.succeed(notes);
+}
+
+const USAGE = "usage: release-notes.ts <version> <output>";
+
+const releaseNotes = Effect.gen(function* () {
+  const [version, output, ...extra] = process.argv.slice(2);
+  if (version === undefined || output === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
+  const fs = yield* FileSystem.FileSystem;
+  const notes = yield* extractReleaseNotes(yield* fs.readFileString("CHANGELOG.md"), version);
+  yield* fs.writeFileString(output, notes);
+  return true;
+});
+
+if (import.meta.main) runMain("checks-release-notes", releaseNotes);

package/scripts/release-report.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env bun
+import { Console, Effect, Schema } from "effect";
+import { groupOf } from "./changelog.ts";
+import { git } from "./git.ts";
+import { runMain, Usage } from "./main.ts";
+
+export class ReleaseReportUnreadable extends Schema.TaggedError<ReleaseReportUnreadable>()("ReleaseReportUnreadable", {
+  message: Schema.String,
+}) {}
+
+const USAGE = "usage: release-report.ts";
+const RELEASE_TAG = "v[0-9]*.[0-9]*.[0-9]*";
+
+export function unreleasedOf(subjects: readonly string[]): readonly string[] {
+  return subjects.filter((subject) => groupOf(subject) !== undefined);
+}
+
+export function formatReport(unreleased: readonly string[], since: string | undefined): string {
+  const where = since === undefined ? "with no tag yet" : `since ${since}`;
+  if (unreleased.length === 0) return `release-report: no unreleased changes ${where}`;
+  return [`release-report: ${unreleased.length} unreleased change(s) ${where}:`, ...unreleased.map((subject) => `  ${subject}`)].join("\n");
+}
+
+const lastTag = Effect.fn("lastTag")(function* (root: string) {
+  const described = yield* git(["describe", "--tags", "--abbrev=0", `--match=${RELEASE_TAG}`, "HEAD"], root).pipe(
+    Effect.map((tag) => tag.trim()),
+    Effect.catchTag("GitFailure", () => Effect.succeed("")),
+  );
+  return described === "" ? undefined : described;
+});
+
+const subjectsSince = Effect.fn("subjectsSince")(function* (root: string, since: string | undefined) {
+  const range = since === undefined ? "HEAD" : `${since}..HEAD`;
+  const log = yield* git(["log", "--topo-order", "--no-merges", "--format=%s", range], root);
+  return log.split("\n").filter((subject) => subject !== "");
+});
+
+const report = Effect.gen(function* () {
+  if (process.argv.slice(2).length > 0) return yield* new Usage({ message: USAGE });
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  if ((yield* git(["rev-parse", "--is-shallow-repository"], root)).trim() === "true") {
+    return yield* new ReleaseReportUnreadable({ message: "the checkout is shallow, so the tag it sees may not be the last one; fetch all of it" });
+  }
+  const since = yield* lastTag(root);
+  const unreleased = unreleasedOf(yield* subjectsSince(root, since));
+  yield* Console.log(formatReport(unreleased, since));
+  return unreleased.length === 0;
+});
+
+if (import.meta.main) runMain("checks-release-report", report);

package/scripts/repetition.ts

@@ -48,6 +48,10 @@ const decodeReport = Schema.decodeUnknownEffect(
   ),
 );
 
+const decodeConfigPaths = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(Schema.Struct({ path: Schema.optional(Schema.Array(Schema.String)) })),
+);
+
 type Scan = { readonly sources: number; readonly clones: readonly Clone[] };
 
 function fragmentOf(file: (name: string) => string, { name, start, end }: typeof Location.Type): Fragment {
@@ -66,8 +70,9 @@ export function repeatedLines(clones: readonly Clone[]): ReadonlyMap<string, num
 
 // jscpd reads files from disk, and the working tree need not hold the revision: a merge checkout or an uncommitted edit.
 // Both ends scan under the head's config, so a changed file set never reads as a change in repetition.
+// jscpd refuses a missing path, so a path in `emptied` the revision lacks is created empty.
 const scan = Effect.fn("scan")(
-  function* (root: string, rev: string, config: string) {
+  function* (root: string, rev: string, config: string, emptied: readonly string[]) {
     const files = yield* pathsAt(rev, [], root);
     if (files.length === 0) return { sources: 0, clones: [] } satisfies Scan;
     const fs = yield* FileSystem.FileSystem;
@@ -75,6 +80,9 @@ const scan = Effect.fn("scan")(
     const scratch = yield* fs.makeTempDirectoryScoped({ prefix: "checks-repetition-" });
     const tree = yield* checkoutFiles(rev, files, scratch, root);
     yield* fs.writeFileString(path.join(tree, CONFIG), config);
+    for (const absent of emptied.map((entry) => path.join(tree, entry))) {
+      if (!(yield* fs.exists(absent))) yield* fs.makeDirectory(absent, { recursive: true });
+    }
     const output = path.join(scratch, "report");
     const flags = ["--silent", "--no-tips", "--no-gitignore", "--absolute", "--reporters", "json", "--output", output];
     const thresholds = ["--min-tokens", `${MIN_TOKENS}`, "--min-lines", `${MIN_LINES}`];
@@ -137,8 +145,11 @@ const runHold = Effect.fn("runHold")(function* (root: string, config: string, ba
   const formerPath = new Map(
     (yield* changedPaths(base, head, [], root)).flatMap((change) => (change.kind === "renamed" ? [[change.path, change.from]] : [])),
   );
-  const before = repeatedLines((yield* scan(root, base, config)).clones);
-  const { sources, clones } = yield* scan(root, head, config);
+  const { path: configPaths = [] } = yield* decodeConfigPaths(config).pipe(
+    Effect.mapError((cause) => new JscpdUnreadable({ message: `cannot read ${CONFIG}: ${cause.message}` })),
+  );
+  const before = repeatedLines((yield* scan(root, base, config, configPaths)).clones);
+  const { sources, clones } = yield* scan(root, head, config, []);
   const after = repeatedLines(clones);
   const rises = risesOf([...after.keys()], before, after, formerPath, clones);
   return heldOf(sources, rises, after) satisfies Held;

package/scripts/vendor-args.ts

@@ -0,0 +1,54 @@
+import { Effect, Schema } from "effect";
+import { Usage } from "./main.ts";
+
+export const NAME = "checks-vendor";
+export const OPENER = "--library";
+const USAGE = `usage: ${NAME} [--library <name> --package <package> --repository <remote> --tag <template> [--path <manifest>]]...`;
+
+const Library = Schema.Struct({
+  name: Schema.String.check(Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)),
+  package: Schema.NonEmptyString,
+  repository: Schema.NonEmptyString,
+  tag: Schema.String.check(Schema.isPattern(/\{version\}/)),
+  path: Schema.optionalKey(Schema.String.check(Schema.isPattern(/^(?:[\w.@+-]+\/)*[\w.@+-]+\.\w+$/))),
+});
+export type Library = typeof Library.Type;
+
+const Libraries = Schema.Array(Library).check(
+  Schema.makeFilter((libraries) => {
+    const names = libraries.map(({ name }) => name);
+    const repeated = names.find((name, index) => names.indexOf(name) !== index);
+    return repeated === undefined || `--library ${repeated} appears more than once`;
+  }),
+);
+
+const FIELDS = new Map<string, keyof Library>([
+  ["--package", "package"],
+  ["--repository", "repository"],
+  ["--tag", "tag"],
+  ["--path", "path"],
+]);
+
+function misuse(message: string): Usage {
+  return new Usage({ message: `${message}\n${USAGE}` });
+}
+
+export const librariesFrom = Effect.fn("librariesFrom")(function* (args: readonly string[]) {
+  const groups: Record<string, string>[] = [];
+  for (let index = 0; index < args.length; index += 2) {
+    const flag = args[index] ?? "";
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) return yield* misuse(`${flag} takes a value`);
+    if (flag === OPENER) {
+      groups.push({ name: value });
+      continue;
+    }
+    const field = FIELDS.get(flag);
+    const current = groups.at(-1);
+    if (field === undefined) return yield* misuse(`${flag} is not an argument`);
+    if (current === undefined) return yield* misuse(`${flag} comes before any ${OPENER}`);
+    if (field in current) return yield* misuse(`${flag} appears twice for ${OPENER} ${current["name"]}`);
+    current[field] = value;
+  }
+  return yield* Schema.decodeUnknownEffect(Libraries)(groups).pipe(Effect.mapError((cause) => misuse(cause.message)));
+});