@acme-skunkworks/eslint-config 1.0.3 → 1.0.4

package/dist/infrastructure/scripts/add-links-changelog.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Rewrite bare Linear IDs in a markdown body to links, masking code/links.
+ */
+export declare function rewriteBody(body: string): string;
+/**
+ * Split leading YAML frontmatter from the body, preserving the fence bytes.
+ */
+export declare function splitFrontmatter(raw: string): {
+    body: string;
+    fm: string;
+};
+//# sourceMappingURL=add-links-changelog.d.ts.map

package/dist/infrastructure/scripts/add-links-changelog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-links-changelog.d.ts","sourceRoot":"","sources":["../../../infrastructure/scripts/add-links-changelog.ts"],"names":[],"mappings":"AAwBA;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAgBhD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAe1E"}

package/dist/infrastructure/scripts/add-links-changelog.js

@@ -0,0 +1,56 @@
+// Pure helper: rewrite bare Linear issue IDs (e.g. ASW-123) in changelog entry
+// bodies into markdown links, masking code fences / inline code / already-linked
+// IDs first so they're left untouched. Ported from octavo's add-links.mjs,
+// adapted to this workspace (acme-skunkworks).
+//
+// Library module (no CLI): the release-time orchestrator finalise-changelog.ts
+// applies it. Kept pure so it's trivially unit-testable.
+const WORKSPACE = "acme-skunkworks";
+const TEAM_KEYS = ["ASW", "AKW"];
+const ISSUE_RE = new RegExp(`\\b(?:${TEAM_KEYS.join("|")})-\\d+\\b`, "g");
+const FENCE_RE = /```[\s\S]*?```/g;
+const INLINE_CODE_RE = /`[^`]*`/g;
+const ALREADY_LINKED_RE = /\[[^\]]*\]\([^)]*\)/g;
+// Private-Use-Area sentinel wrapping each masked span, so a placeholder can
+// never collide with literal body text (e.g. a code sample containing the
+// string "FENCE0"). U+E000 cannot appear in a markdown source file.
+const SENTINEL = "\u{E000}";
+const PLACEHOLDER_RE = /\u{E000}(?:FENCE|INLINE|LINK)(\d+)\u{E000}/gu;
+function buildUrl(id) {
+    return `https://linear.app/${WORKSPACE}/issue/${id}`;
+}
+/**
+ * Rewrite bare Linear IDs in a markdown body to links, masking code/links.
+ */
+export function rewriteBody(body) {
+    const masks = [];
+    function mask(label) {
+        return (matched) => {
+            masks.push(matched);
+            return `${SENTINEL}${label}${masks.length - 1}${SENTINEL}`;
+        };
+    }
+    const masked = body
+        .replaceAll(FENCE_RE, mask("FENCE"))
+        .replaceAll(INLINE_CODE_RE, mask("INLINE"))
+        .replaceAll(ALREADY_LINKED_RE, mask("LINK"))
+        .replaceAll(ISSUE_RE, (id) => `[${id}](${buildUrl(id)})`);
+    return masked.replaceAll(PLACEHOLDER_RE, (_, index) => masks[Number(index)]);
+}
+/**
+ * Split leading YAML frontmatter from the body, preserving the fence bytes.
+ */
+export function splitFrontmatter(raw) {
+    if (!raw.startsWith("---\n")) {
+        return { body: raw, fm: "" };
+    }
+    // Search from index 3: the opening "---\n" is exactly 4 bytes, so the
+    // earliest a closing "\n---\n" can start is index 3 (the newline ending the
+    // opening fence). Starting at 4 would miss the close of an empty frontmatter
+    // ("---\n---\n").
+    const end = raw.indexOf("\n---\n", 3);
+    if (end === -1) {
+        return { body: raw, fm: "" };
+    }
+    return { body: raw.slice(end + 5), fm: raw.slice(0, end + 5) };
+}

package/dist/infrastructure/scripts/enrich-changelog.d.ts

@@ -0,0 +1,26 @@
+export type EnrichInput = {
+    additions?: null | string;
+    /**
+     * Feature branch name — the stable lookup key.
+     */
+    branch: string;
+    changedFiles?: null | string;
+    deletions?: null | string;
+    /**
+     * PR merged_at timestamp (ISO 8601 UTC).
+     */
+    mergedAt: string;
+    /**
+     * Merge commit SHA (full or short); only the first 7 chars are stored.
+     */
+    mergeSha: string;
+    mergeStrategy?: null | string;
+    prNumber?: null | string;
+};
+/**
+ * Apply enrichment to a single entry's raw markdown and return the rewritten
+ * markdown. Fill-once for merged_at/commit/merge_strategy/pr; authoritative
+ * overwrite for stats. created_at is never touched.
+ */
+export declare function enrichFrontmatter(raw: string, input: EnrichInput): string;
+//# sourceMappingURL=enrich-changelog.d.ts.map

package/dist/infrastructure/scripts/enrich-changelog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrich-changelog.d.ts","sourceRoot":"","sources":["../../../infrastructure/scripts/enrich-changelog.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAC1B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAC7B,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAC1B;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;CAC1B,CAAC;AASF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAkDzE"}

package/dist/infrastructure/scripts/enrich-changelog.js

@@ -0,0 +1,60 @@
+// Pure enrichment of a changelog entry's frontmatter — fills the fields that
+// are only knowable once the PR has merged (merged_at / commit / merge_strategy
+// / pr) plus authoritative stats. `version` is filled separately by
+// stamp-changelog-version. created_at is never touched.
+//
+// This is a library module (no CLI): the release-time orchestrator
+// finalise-changelog.ts composes it with the PR data it resolves from `gh`.
+// Ported from octavo's enrich-changelog.mjs, minus affected_packages (single
+// package). Kept pure so it's trivially unit-testable.
+import matter from "gray-matter";
+/**
+ * True when a value is unset (null/undefined/"").
+ */
+function blank(value) {
+    return value === null || value === undefined || value === "";
+}
+/**
+ * Apply enrichment to a single entry's raw markdown and return the rewritten
+ * markdown. Fill-once for merged_at/commit/merge_strategy/pr; authoritative
+ * overwrite for stats. created_at is never touched.
+ */
+export function enrichFrontmatter(raw, input) {
+    const parsed = matter(raw);
+    const fm = { ...parsed.data };
+    if (!fm.created_at) {
+        throw new Error("entry has no created_at; refusing to enrich");
+    }
+    const shortSha = input.mergeSha.slice(0, 7);
+    if (blank(fm.merged_at)) {
+        fm.merged_at = input.mergedAt;
+    }
+    if (blank(fm.commit)) {
+        fm.commit = shortSha;
+    }
+    if (blank(fm.merge_strategy) && input.mergeStrategy) {
+        fm.merge_strategy = input.mergeStrategy;
+    }
+    if (blank(fm.pr) && input.prNumber) {
+        fm.pr = Number.parseInt(input.prNumber, 10);
+    }
+    // Authoritative overwrites from the GH API, always under stats: { ... }.
+    const stats = typeof fm.stats === "object" &&
+        fm.stats !== null &&
+        !Array.isArray(fm.stats)
+        ? { ...fm.stats }
+        : {};
+    // Guard with blank() (not just null/undefined): an empty string would slip
+    // through and Number.parseInt("", 10) is NaN, which the validator rejects.
+    if (!blank(input.additions)) {
+        stats.loc_added = Number.parseInt(input.additions, 10);
+    }
+    if (!blank(input.deletions)) {
+        stats.loc_removed = Number.parseInt(input.deletions, 10);
+    }
+    if (!blank(input.changedFiles)) {
+        stats.files_changed = Number.parseInt(input.changedFiles, 10);
+    }
+    fm.stats = stats;
+    return matter.stringify(parsed.content, fm);
+}

package/dist/infrastructure/scripts/finalise-changelog.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env -S npx tsx
+export declare const CHANGELOG_DIR = "changelog";
+export type ResolvedPr = {
+    additions: null | string;
+    changedFiles: null | string;
+    deletions: null | string;
+    mergedAt: string;
+    mergeSha: string;
+    mergeStrategy: null | string;
+    prNumber: string;
+};
+/**
+ * Resolve the merged PR for a branch, or null when none is found.
+ */
+export type PrResolver = (branch: string) => null | ResolvedPr;
+export type Runner = (cmd: string, args: readonly string[]) => string;
+/**
+ * Finalise one entry's raw markdown for release. Returns the rewritten markdown,
+ * or null when nothing changed (already finalised).
+ */
+export declare function finaliseEntry(raw: string, version: string, resolvePr: PrResolver): null | string;
+/**
+ * Build a PR resolver backed by `gh` + `git` (injectable runner for tests).
+ */
+export declare function makeResolver(run: Runner): PrResolver;
+//# sourceMappingURL=finalise-changelog.d.ts.map

package/dist/infrastructure/scripts/finalise-changelog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalise-changelog.d.ts","sourceRoot":"","sources":["../../../infrastructure/scripts/finalise-changelog.ts"],"names":[],"mappings":";AAuBA,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,IAAI,GAAG,MAAM,CAAC;IACzB,YAAY,EAAE,IAAI,GAAG,MAAM,CAAC;IAC5B,SAAS,EAAE,IAAI,GAAG,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,IAAI,GAAG,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,UAAU,CAAC;AAE/D,MAAM,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AAMtE;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,UAAU,GACpB,IAAI,GAAG,MAAM,CAgCf;AAaD;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CA4EpD"}

package/dist/infrastructure/scripts/finalise-changelog.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env -S npx tsx
+// Release-time finalisation of changelog entries — run by changesets/action's
+// `version:` command, right after `changeset version`, so the result is
+// committed into the "release: version packages" PR (no separate workflow, no
+// bot push to main).
+//
+// For every entry that isn't finalised yet (empty `version`):
+//   1. resolve its merged PR from the `branch` field via `gh` and enrich
+//      (merged_at / commit / pr / merge_strategy / stats);
+//   2. stamp `version` with the just-bumped package.json version;
+//   3. rewrite bare Linear IDs to links.
+//
+// The pure `finaliseEntry(raw, version, resolvePr)` is unit-testable with a fake
+// resolver; main() wires the real `gh`/`git` resolver and walks the directory.
+import { rewriteBody, splitFrontmatter } from "./add-links-changelog.js";
+import { enrichFrontmatter } from "./enrich-changelog.js";
+import { readPackageVersion, stampVersion } from "./stamp-changelog-version.js";
+import matter from "gray-matter";
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const CHANGELOG_DIR = "changelog";
+function blank(value) {
+    return value === null || value === undefined || value === "";
+}
+/**
+ * Finalise one entry's raw markdown for release. Returns the rewritten markdown,
+ * or null when nothing changed (already finalised).
+ */
+export function finaliseEntry(raw, version, resolvePr) {
+    const fm = matter(raw).data;
+    if (!blank(fm.version)) {
+        return null; // already shipped in a release
+    }
+    let next = raw;
+    const branch = typeof fm.branch === "string" ? fm.branch : "";
+    const needsEnrich = blank(fm.merged_at) || blank(fm.commit) || blank(fm.pr);
+    if (branch && needsEnrich) {
+        const pr = resolvePr(branch);
+        if (pr) {
+            next = enrichFrontmatter(next, {
+                additions: pr.additions,
+                branch,
+                changedFiles: pr.changedFiles,
+                deletions: pr.deletions,
+                mergedAt: pr.mergedAt,
+                mergeSha: pr.mergeSha,
+                mergeStrategy: pr.mergeStrategy,
+                prNumber: pr.prNumber,
+            });
+        }
+    }
+    next = stampVersion(next, version) ?? next;
+    const { body, fm: fmText } = splitFrontmatter(next);
+    next = fmText + rewriteBody(body);
+    return next === raw ? null : next;
+}
+function realRunner(cmd, args) {
+    return execFileSync(cmd, args, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "inherit"],
+        // Fail fast if gh/git stalls (network/auth). Enrichment is best-effort, so
+        // a timeout throws → makeResolver's try/catch falls back to null rather
+        // than hanging the release until the whole job times out.
+        timeout: 30_000,
+    });
+}
+/**
+ * Build a PR resolver backed by `gh` + `git` (injectable runner for tests).
+ */
+export function makeResolver(run) {
+    function resolve(branch) {
+        const json = run("gh", [
+            "pr",
+            "list",
+            "--head",
+            branch,
+            "--state",
+            "merged",
+            "--limit",
+            "1",
+            "--json",
+            "number,mergedAt,additions,deletions,changedFiles,mergeCommit,headRefOid",
+        ]);
+        const list = JSON.parse(json);
+        if (list.length === 0) {
+            return null;
+        }
+        const pr = list[0];
+        const mergeSha = pr.mergeCommit?.oid ?? "";
+        // Infer merge strategy from the merge commit shape (GitHub doesn't expose
+        // it directly): 2+ parents -> merge; otherwise squash.
+        // NOTE: rebase merges are also reported as "squash" — GitHub replays them
+        // with fresh SHAs, so mergeCommit.oid never equals headRefOid and the
+        // "rebase" branch below is effectively unreachable. This repo squash-merges
+        // anyway, and merge_strategy is only record-keeping metadata, so the
+        // imprecision is harmless.
+        let mergeStrategy = null;
+        if (mergeSha) {
+            const parents = (run("git", ["cat-file", "-p", mergeSha]).match(/^parent /gm) ?? []).length;
+            if (parents >= 2) {
+                mergeStrategy = "merge";
+            }
+            else {
+                mergeStrategy = mergeSha === pr.headRefOid ? "rebase" : "squash";
+            }
+        }
+        // Absent numeric fields stay null (not ""), so the enrich guard skips them
+        // rather than parsing "" into NaN.
+        return {
+            additions: pr.additions === undefined ? null : String(pr.additions),
+            changedFiles: pr.changedFiles === undefined ? null : String(pr.changedFiles),
+            deletions: pr.deletions === undefined ? null : String(pr.deletions),
+            mergedAt: pr.mergedAt ?? "",
+            mergeSha,
+            mergeStrategy,
+            prNumber: String(pr.number ?? ""),
+        };
+    }
+    return (branch) => {
+        // Enrichment is best-effort metadata: a gh/git failure here must NOT abort
+        // `changeset version` and block the release. On any error, warn and return
+        // null — the entry still gets version-stamped, just without PR metadata.
+        try {
+            return resolve(branch);
+        }
+        catch (error) {
+            console.warn(`⚠️  Could not resolve PR for branch ${branch}: ${error.message}`);
+            return null;
+        }
+    };
+}
+function main() {
+    const version = readPackageVersion(readFileSync("package.json", "utf8"));
+    const resolvePr = makeResolver(realRunner);
+    const files = readdirSync(CHANGELOG_DIR)
+        .filter((name) => name.endsWith(".md") && name !== "README.md")
+        .map((name) => join(CHANGELOG_DIR, name));
+    let finalised = 0;
+    for (const file of files) {
+        const next = finaliseEntry(readFileSync(file, "utf8"), version, resolvePr);
+        if (next !== null) {
+            writeFileSync(file, next);
+            finalised++;
+            console.log(`finalised ${version}: ${file}`);
+        }
+    }
+    console.log(`Changelog finalisation complete. ${finalised} entr${finalised === 1 ? "y" : "ies"} finalised with ${version}.`);
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main();
+}

package/dist/infrastructure/scripts/stamp-changelog-version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Stamp `version` onto an entry if it has none. Returns the rewritten markdown,
+ * or null when the entry already has a version (no write needed).
+ */
+export declare function stampVersion(raw: string, version: string): null | string;
+/**
+ * Read the `version` field from a package.json string.
+ */
+export declare function readPackageVersion(packageJsonRaw: string): string;
+//# sourceMappingURL=stamp-changelog-version.d.ts.map

package/dist/infrastructure/scripts/stamp-changelog-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stamp-changelog-version.d.ts","sourceRoot":"","sources":["../../../infrastructure/scripts/stamp-changelog-version.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CASxE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAOjE"}

package/dist/infrastructure/scripts/stamp-changelog-version.js

@@ -0,0 +1,35 @@
+// Pure helpers for release-time version stamping: set `version` on an entry
+// that doesn't have one, and read the version from package.json.
+//
+// Library module (no CLI): the release-time orchestrator finalise-changelog.ts
+// composes these. Kept pure so they're trivially unit-testable.
+import matter from "gray-matter";
+/**
+ * True when a value is unset (null/undefined/"").
+ */
+function blank(value) {
+    return value === null || value === undefined || value === "";
+}
+/**
+ * Stamp `version` onto an entry if it has none. Returns the rewritten markdown,
+ * or null when the entry already has a version (no write needed).
+ */
+export function stampVersion(raw, version) {
+    const parsed = matter(raw);
+    const fm = { ...parsed.data };
+    if (!blank(fm.version)) {
+        return null;
+    }
+    fm.version = version;
+    return matter.stringify(parsed.content, fm);
+}
+/**
+ * Read the `version` field from a package.json string.
+ */
+export function readPackageVersion(packageJsonRaw) {
+    const pkg = JSON.parse(packageJsonRaw);
+    if (typeof pkg.version !== "string" || pkg.version.length === 0) {
+        throw new Error("package.json is missing a string `version`");
+    }
+    return pkg.version;
+}

package/dist/infrastructure/scripts/validate-changelog.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env -S npx tsx
+export declare const CHANGELOG_DIR = "changelog";
+/**
+ * Validate one entry. Returns an array of human-readable error strings.
+ */
+export declare function validateEntry(name: string, raw: string): string[];
+//# sourceMappingURL=validate-changelog.d.ts.map

package/dist/infrastructure/scripts/validate-changelog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-changelog.d.ts","sourceRoot":"","sources":["../../../infrastructure/scripts/validate-changelog.ts"],"names":[],"mappings":";AAoBA,eAAO,MAAM,aAAa,cAAc,CAAC;AA0DzC;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CA0JjE"}

package/dist/infrastructure/scripts/validate-changelog.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env -S npx tsx
+// Validates the individual dated changelog entries under `changelog/`.
+//
+// Ported from octavo's scripts/validate-changelog.mjs and adapted for this
+// repo (single, semver'd npm package):
+//   - `version` is accepted (typed-when-present semver string); octavo has none.
+//   - `affected_packages` is dropped (one package, not a monorepo).
+//   - the REQUIRED set is relaxed to title/created_at/category/breaking so that
+//     both backfilled historical entries (no branch/author/stats) and in-flight
+//     entries (no version/merged_at/pr/commit/stats until enriched) validate.
+//     /send-it is the guarantee that new entries get branch/author/co_authors;
+//     validation is the safety net, not the sole guard.
+//
+// The pure `validateEntry(name, raw)` returns an array of error strings (empty
+// means valid), so it's trivially unit-testable; main() walks the directory.
+import matter from "gray-matter";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+export const CHANGELOG_DIR = "changelog";
+const FILENAME_RE = /^(\d{8})-(\d{6})-([a-z0-9-]+)\.md$/;
+const ISO_UTC_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+// SemVer 2.0.0: prerelease and build identifiers are dot-separated and may
+// contain ASCII alphanumerics and hyphens (e.g. 1.2.3-rc-1, 1.2.3+build-45).
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const SHA7_RE = /^[0-9a-f]{7}$/;
+const ISSUE_RE = /^[A-Z]{2,}-\d+$/;
+const CATEGORIES = new Set([
+    "chore",
+    "docs",
+    "feature",
+    "fix",
+    "perf",
+    "refactor",
+]);
+const MERGE_STRATEGIES = new Set(["merge", "rebase", "squash"]);
+const SECTION_RE = /^##\s+(Breaking|Added|Changed|Fixed)\b/m;
+const REQUIRED = ["title", "created_at", "category", "breaking"];
+/**
+ * True when a value is set to something meaningful (not null/undefined/"").
+ */
+function present(value) {
+    return value !== null && value !== undefined && value !== "";
+}
+function isInt(value) {
+    return typeof value === "number" && Number.isInteger(value);
+}
+function isNonNegInt(value) {
+    return isInt(value) && value >= 0;
+}
+function isStringArray(value) {
+    return (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+function asIso(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    return "";
+}
+/**
+ * Validate one entry. Returns an array of human-readable error strings.
+ */
+export function validateEntry(name, raw) {
+    const errors = [];
+    function fail(message) {
+        errors.push(`${name}: ${message}`);
+    }
+    if (!FILENAME_RE.test(name)) {
+        fail("filename must match YYYYMMDD-HHMMSS-<slug>.md (slug: [a-z0-9-]+)");
+        return errors;
+    }
+    let parsed;
+    try {
+        parsed = matter(raw);
+    }
+    catch (error) {
+        fail(`frontmatter unparseable: ${error.message}`);
+        return errors;
+    }
+    const fm = (parsed.data ?? {});
+    const body = parsed.content ?? "";
+    for (const key of REQUIRED) {
+        if (!(key in fm)) {
+            fail(`missing required field: ${key}`);
+        }
+    }
+    if ("title" in fm &&
+        (typeof fm.title !== "string" || fm.title.trim() === "")) {
+        fail("title must be a non-empty string");
+    }
+    if ("release_note" in fm &&
+        fm.release_note !== null &&
+        typeof fm.release_note !== "string") {
+        fail("release_note must be a string or null when present");
+    }
+    if (present(fm.version) &&
+        (typeof fm.version !== "string" || !SEMVER_RE.test(fm.version))) {
+        fail(`version must be a semver string when set (got ${JSON.stringify(fm.version)})`);
+    }
+    if ("created_at" in fm && !ISO_UTC_RE.test(asIso(fm.created_at))) {
+        fail(`created_at must be ISO 8601 UTC with Z suffix (got ${JSON.stringify(fm.created_at)})`);
+    }
+    if (present(fm.merged_at) && !ISO_UTC_RE.test(asIso(fm.merged_at))) {
+        fail("merged_at must be ISO 8601 UTC with Z suffix when set");
+    }
+    if ("branch" in fm &&
+        (typeof fm.branch !== "string" || fm.branch.trim() === "")) {
+        fail("branch must be a non-empty string when present");
+    }
+    if (present(fm.pr) && !isInt(fm.pr)) {
+        fail("pr must be an integer when set");
+    }
+    if (present(fm.commit) && !SHA7_RE.test(String(fm.commit))) {
+        fail("commit must be a 7-char hex SHA when set");
+    }
+    if (present(fm.merge_strategy) &&
+        !MERGE_STRATEGIES.has(String(fm.merge_strategy))) {
+        fail(`merge_strategy must be one of: ${[...MERGE_STRATEGIES].join(", ")}`);
+    }
+    if ("author" in fm &&
+        (typeof fm.author !== "string" || fm.author.trim() === "")) {
+        fail("author must be a non-empty string when present");
+    }
+    if ("co_authors" in fm && !isStringArray(fm.co_authors)) {
+        fail("co_authors must be an array of strings (use [] when none)");
+    }
+    if ("category" in fm && !CATEGORIES.has(String(fm.category))) {
+        fail(`category must be one of: ${[...CATEGORIES].join(", ")}`);
+    }
+    if ("breaking" in fm && typeof fm.breaking !== "boolean") {
+        fail("breaking must be a boolean");
+    }
+    if ("issues" in fm) {
+        if (isStringArray(fm.issues)) {
+            for (const id of fm.issues) {
+                if (!ISSUE_RE.test(id)) {
+                    fail(`issues entry ${JSON.stringify(id)} must match [A-Z]{2,}-\\d+`);
+                }
+            }
+        }
+        else {
+            fail("issues must be an array of strings when present");
+        }
+    }
+    // PR stats live under stats: { files_changed, loc_added, loc_removed }.
+    const statKeys = ["files_changed", "loc_added", "loc_removed"];
+    for (const key of statKeys) {
+        if (key in fm) {
+            fail(`${key} must be under stats, not top-level`);
+        }
+    }
+    // stats is optional (filled by enrichment), but must be a well-formed object
+    // with non-negative integer values when present.
+    if (present(fm.stats)) {
+        if (typeof fm.stats !== "object" || Array.isArray(fm.stats)) {
+            fail("stats must be an object");
+        }
+        else {
+            const stats = fm.stats;
+            for (const key of statKeys) {
+                if (key in stats && present(stats[key]) && !isNonNegInt(stats[key])) {
+                    fail(`stats.${key} must be a non-negative integer when set`);
+                }
+            }
+        }
+    }
+    // The schema (changelog/README.md) requires "## Breaking" to be the FIRST
+    // body section when breaking: true — not merely present somewhere.
+    if (fm.breaking === true) {
+        const firstSection = body.match(/^##\s+([A-Za-z]+)\b/m)?.[1];
+        if (firstSection !== "Breaking") {
+            fail('breaking: true requires "## Breaking" as the first body section');
+        }
+    }
+    if (!SECTION_RE.test(body)) {
+        fail("body must contain at least one of: ## Breaking | ## Added | ## Changed | ## Fixed");
+    }
+    return errors;
+}
+function listEntries(directory) {
+    let stat;
+    try {
+        stat = statSync(directory);
+    }
+    catch {
+        console.error(`changelog directory not found: ${directory}`);
+        process.exit(2);
+    }
+    if (!stat.isDirectory()) {
+        console.error(`${directory} is not a directory`);
+        process.exit(2);
+    }
+    return readdirSync(directory)
+        .filter((name) => name.endsWith(".md") && name !== "README.md")
+        .map((name) => join(directory, name));
+}
+function main() {
+    const files = listEntries(CHANGELOG_DIR);
+    const errors = [];
+    for (const file of files) {
+        errors.push(...validateEntry(basename(file), readFileSync(file, "utf8")));
+    }
+    if (errors.length > 0) {
+        console.error(`Changelog validation failed with ${errors.length} error(s):\n`);
+        for (const message of errors) {
+            console.error(`  - ${message}`);
+        }
+        process.exit(1);
+    }
+    console.log(`Changelog validation passed (${files.length} entr${files.length === 1 ? "y" : "ies"} checked).`);
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main();
+}

package/dist/rules/sanity.d.ts

@@ -6,7 +6,7 @@
  * Combined Sanity ESLint configuration. Exports an array of two configs
  * documented inline above: schema property ordering for `*.schema.ts` (a
  * perfectionist `sort-objects` rule with custom groups so identity → fields
- * → behavior → validation appear in a deterministic, readable order) and
+ * → behaviour → validation appear in a deterministic, readable order) and
  * structure-file exceptions (allows the `S => S.list()` arrow-function
  * pattern and the canonical single-letter `S` parameter that Sanity's docs
  * universally use for the StructureBuilder).

package/dist/rules/sanity.js

@@ -7,8 +7,8 @@
  * Property ordering follows a logical grouping:
  * 1. Identity: name, title, type, icon
  * 2. Fields: fields (placed early so document content stays visually prominent)
- * 3. Organization: fieldset, group, groups, fieldsets
- * 4. Behavior: hidden, readOnly
+ * 3. Organisation: fieldset, group, groups, fieldsets
+ * 4. Behaviour: hidden, readOnly
  * 5. Type-specific: options, rows, to, of, marks, styles
  * 6. Content defaults: initialValue, description
  * 7. Validation: validation
@@ -33,12 +33,12 @@ const sanitySchemaPropertyOrdering = {
                     { elementNamePattern: "^icon$", groupName: "icon" },
                     // 2. Fields array (placed early so the schema's content stays visually prominent)
                     { elementNamePattern: "^fields$", groupName: "fields" },
-                    // 3. Organization - where does it go?
+                    // 3. Organisation - where does it go?
                     { elementNamePattern: "^fieldset$", groupName: "fieldset" },
                     { elementNamePattern: "^group$", groupName: "group" },
                     { elementNamePattern: "^groups$", groupName: "groups" },
                     { elementNamePattern: "^fieldsets$", groupName: "fieldsets" },
-                    // 4. Behavior - how does it behave?
+                    // 4. Behaviour - how does it behave?
                     { elementNamePattern: "^hidden$", groupName: "hidden" },
                     { elementNamePattern: "^readOnly$", groupName: "readOnly" },
                     // 5. Type-specific options
@@ -65,12 +65,12 @@ const sanitySchemaPropertyOrdering = {
                     "icon",
                     // Fields
                     "fields",
-                    // Organization
+                    // Organisation
                     "fieldset",
                     "group",
                     "groups",
                     "fieldsets",
-                    // Behavior
+                    // Behaviour
                     "hidden",
                     "readOnly",
                     // Type-specific
@@ -135,7 +135,7 @@ const sanityStructure = {
  * Combined Sanity ESLint configuration. Exports an array of two configs
  * documented inline above: schema property ordering for `*.schema.ts` (a
  * perfectionist `sort-objects` rule with custom groups so identity → fields
- * → behavior → validation appear in a deterministic, readable order) and
+ * → behaviour → validation appear in a deterministic, readable order) and
  * structure-file exceptions (allows the `S => S.list()` arrow-function
  * pattern and the canonical single-letter `S` parameter that Sanity's docs
  * universally use for the StructureBuilder).

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@acme-skunkworks/eslint-config",
-  "version": "1.0.3",
-  "description": "Shared ESLint configuration with TypeScript and React support",
+  "version": "1.0.4",
+  "description": "Shared ESLint flat-config preset with TypeScript, React, Astro, Sanity, and Storybook support",
   "keywords": [
     "eslint",
     "eslint-config",
     "linting",
     "typescript",
+    "react",
     "astro",
+    "sanity",
+    "storybook",
     "code-quality"
   ],
   "homepage": "https://github.com/acme-skunkworks/eslint-config#readme",
@@ -42,6 +45,8 @@
     "act:list": "act --list",
     "act:release:dry": "act push -W .github/workflows/release.yml",
     "build": "tsc",
+    "changelog:finalise": "tsx infrastructure/scripts/finalise-changelog.ts",
+    "changeset:version": "changeset version && pnpm changelog:finalise",
     "ci:list": "gh run list --limit 10",
     "ci:view": "gh run view",
     "ci:watch": "gh run watch $(gh run list -L 1 --json databaseId -q '.[0].databaseId // empty')",
@@ -49,8 +54,8 @@
     "format": "npx prettier --write .",
     "lint": "eslint 'index.ts' 'rules/**/*.ts' 'infrastructure/scripts/**/*.ts' 'infrastructure/send-it/**/*.ts' --cache --cache-location ./.eslintcache",
     "lint:fix": "eslint 'index.ts' 'rules/**/*.ts' 'infrastructure/scripts/**/*.ts' 'infrastructure/send-it/**/*.ts' --fix --cache --cache-location ./.eslintcache",
-    "lint:md": "markdownlint-cli2 '**/*.{md,mdx}' '!**/node_modules/**' '!**/dist/**' '!**/.turbo/**' '!**/.astro/**'",
-    "lint:md:fix": "markdownlint-cli2 --fix '**/*.{md,mdx}' '!**/node_modules/**' '!**/dist/**' '!**/.turbo/**' '!**/.astro/**'",
+    "lint:md": "markdownlint-cli2 '**/*.{md,mdx}' '!**/node_modules/**' '!**/dist/**' '!**/.turbo/**' '!**/.astro/**' '!**/CHANGELOG.md'",
+    "lint:md:fix": "markdownlint-cli2 --fix '**/*.{md,mdx}' '!**/node_modules/**' '!**/dist/**' '!**/.turbo/**' '!**/.astro/**' '!**/CHANGELOG.md'",
     "lint:sh": "bash -c 'if command -v shellcheck >/dev/null 2>&1; then shellcheck infrastructure/scripts/*.sh .husky/pre-commit .husky/pre-push .husky/commit-msg; elif [ \"$(uname -s)\" = \"Darwin\" ]; then echo \"⚠️  shellcheck not installed — skipping. Install: brew install shellcheck\"; else echo \"⚠️  shellcheck not installed — skipping. Install: apt-get install shellcheck\"; fi'",
     "lint:workflows": "actionlint",
     "lint:yaml": "yamllint .",
@@ -64,6 +69,7 @@
     "test:sh": "bash -c 'if command -v bats >/dev/null 2>&1; then bats infrastructure/tests/*.bats; elif [ \"$(uname -s)\" = \"Darwin\" ]; then echo \"⚠️  bats not installed — skipping. Install: brew install bats-core\"; else echo \"⚠️  bats not installed — skipping. Install: apt-get install bats\"; fi'",
     "test:watch": "vitest",
     "tsc": "tsc --noEmit",
+    "validate:changelog": "tsx infrastructure/scripts/validate-changelog.ts",
     "version": "changeset version"
   },
   "lint-staged": {
@@ -111,6 +117,7 @@
     "@changesets/cli": "^2.31.0",
     "@types/eslint": "^9.6.1",
     "@types/node": "^25.6.0",
+    "gray-matter": "^4.0.3",
     "husky": "^9.1.7",
     "lint-staged": "^16.3.2",
     "markdownlint-cli2": "^0.18.1",
@@ -131,10 +138,5 @@
   "publishConfig": {
     "access": "public",
     "provenance": true
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "unrs-resolver"
-    ]
   }
 }

package/dist/infrastructure/scripts/retitle-release-pr.d.ts

@@ -1,11 +0,0 @@
-#!/usr/bin/env -S npx tsx
-export type Runner = (cmd: string, args: readonly string[]) => string;
-export type RetitleResult = {
-    reason: string;
-    status: "skipped";
-} | {
-    status: "ok";
-    title: string;
-};
-export declare function retitleReleasePr(environment: Record<string, string | undefined>, run: Runner): RetitleResult;
-//# sourceMappingURL=retitle-release-pr.d.ts.map

package/dist/infrastructure/scripts/retitle-release-pr.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"retitle-release-pr.d.ts","sourceRoot":"","sources":["../../../infrastructure/scripts/retitle-release-pr.ts"],"names":[],"mappings":";AAgBA,MAAM,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AAEtE,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AASpC,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAC/C,GAAG,EAAE,MAAM,GACV,aAAa,CAwBf"}

package/dist/infrastructure/scripts/retitle-release-pr.js

@@ -1,50 +0,0 @@
-#!/usr/bin/env -S npx tsx
-// Rewrites the Changesets-opened "Version Packages" PR title from the static
-// `release: version packages` (set in release.yml) to `<name>@<version>` after
-// the action has bumped package.json on the changeset-release/main branch.
-//
-// Inputs are read from env, not argv, so the script is trivially mockable in
-// tests and we don't have to think about shell quoting in YAML:
-//
-//   PR_NUMBER  — the changesets/action output `pullRequestNumber`. Empty means
-//                the action either published (no PR) or had nothing to do; in
-//                that case we exit cleanly. The workflow's `if:` should gate
-//                this already, but the guard is here for direct invocations.
-//   GH_TOKEN   — passed through to `gh` via the subprocess env.
-import { execFileSync } from "node:child_process";
-function realRunner(cmd, args) {
-    return execFileSync(cmd, args, {
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "inherit"],
-    });
-}
-export function retitleReleasePr(environment, run) {
-    const prNumber = environment.PR_NUMBER?.trim();
-    if (!prNumber) {
-        return { reason: "PR_NUMBER is empty", status: "skipped" };
-    }
-    run("git", ["fetch", "origin", "changeset-release/main"]);
-    const packageJsonRaw = run("git", ["show", "FETCH_HEAD:package.json"]);
-    const pkg = JSON.parse(packageJsonRaw);
-    if (typeof pkg.name !== "string" || pkg.name.length === 0) {
-        throw new Error("package.json is missing a string `name`");
-    }
-    if (typeof pkg.version !== "string" || pkg.version.length === 0) {
-        throw new Error("package.json is missing a string `version`");
-    }
-    const title = `${pkg.name}@${pkg.version}`;
-    run("gh", ["pr", "edit", prNumber, "--title", title]);
-    return { status: "ok", title };
-}
-function main() {
-    const result = retitleReleasePr(process.env, realRunner);
-    if (result.status === "skipped") {
-        console.log(`retitle-release-pr: skipped (${result.reason})`);
-    }
-    else {
-        console.log(`retitle-release-pr: set title to ${result.title}`);
-    }
-}
-if (import.meta.url === `file://${process.argv[1]}`) {
-    main();
-}