@ploaness/governance 1.0.0

package/dist/toolchain-pins.d.ts

@@ -0,0 +1,42 @@
+/** An analyzer ploaness runs in a container rather than installing from the registry. */
+export type ContainerTool = 'gitleaks' | 'hadolint' | 'actionlint' | 'shellcheck';
+/** The exact image each containerised analyzer runs, by digest. */
+export declare const CONTAINER_IMAGES: Readonly<Record<ContainerTool, string>>;
+/** Matches a reference that names image bytes AND the release they are, and only such a reference. */
+export declare const DIGEST_PINNED: RegExp;
+/**
+ * Report every containerised analyzer whose image is not pinned to an exact digest.
+ * @param images the image reference declared for each tool.
+ * @returns one message per unpinned tool; empty means every verdict is reproducible.
+ */
+export declare const findUnpinnedImages: (images: Readonly<Record<string, string>>) => readonly string[];
+/**
+ * The lowest Node major an engines range admits.
+ * @param enginesNode the declared range, such as `>=26`.
+ * @returns the major version, or undefined when the range names none.
+ */
+export declare const minimumNodeMajor: (enginesNode: string | undefined) => number | undefined;
+/**
+ * The exact pnpm version a `packageManager` specifier names.
+ *
+ * The version has one source - the `packageManager` pin - and everything else that states it is
+ * derived from here. `engines.pnpm` was pinned separately at `>=11` while `packageManager` said
+ * `pnpm@11.9.0`, which is the range ban applied to every dependency except the tool that resolves
+ * them: it told a reader that any pnpm 11 would build the same tree.
+ * @param packageManager the declared specifier, such as `pnpm@11.9.0`.
+ * @returns the version, or undefined when the specifier names another manager or no version.
+ */
+export declare const pinnedPnpmVersion: (packageManager: string | undefined) => string | undefined;
+/**
+ * Report the pnpm actually running this command when it is not the pinned one.
+ *
+ * `packageManager` is a declaration, and Corepack obeys it only where Corepack is enabled. Without
+ * this the pin was a comment: a project could declare `pnpm@11.9.0`, pass the wiring gate, and resolve
+ * its whole tree with another pnpm - which is the one difference that changes what every other pin
+ * means, because the lockfile it produces is the input to every gate that follows.
+ * @param userAgent the `npm_config_user_agent` of the running process.
+ * @param required the pinned version, from {@link pinnedPnpmVersion}.
+ * @returns one finding when the running pnpm disagrees; empty when it agrees or cannot be observed.
+ */
+export declare const findPnpmRuntimeViolations: (userAgent: string | undefined, required: string | undefined) => readonly string[];
+//# sourceMappingURL=toolchain-pins.d.ts.map

package/dist/toolchain-pins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolchain-pins.d.ts","sourceRoot":"","sources":["../src/toolchain-pins.ts"],"names":[],"mappings":"AAoBA,yFAAyF;AACzF,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,CAAA;AAEjF,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAWpE,CAAA;AAED,sGAAsG;AACtG,eAAO,MAAM,aAAa,EAAE,MACsC,CAAA;AAElE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAG,SAAS,MAAM,EAOxF,CAAA;AAOL;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,aAAa,MAAM,GAAG,SAAS,KAAG,MAAM,GAAG,SAG3E,CAAA;AAOD;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,gBAAgB,MAAM,GAAG,SAAS,KAAG,MAAM,GAAG,SAG/E,CAAA;AAMD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,GACpC,WAAW,MAAM,GAAG,SAAS,EAC7B,UAAU,MAAM,GAAG,SAAS,KAC3B,SAAS,MAAM,EAajB,CAAA"}

package/dist/toolchain-pins.js

@@ -0,0 +1,99 @@
+// The container images the gates run their analyzers in.
+//
+// Pinned by digest rather than by tag. A tag - `latest` most obviously, but a version tag too - is a
+// mutable reference: the registry can repoint it at new bytes, and the same repository would then reach
+// a different verdict on a different day. A digest names the bytes, so it is the only form that makes
+// "an upstream release cannot change a verdict while the repository does not change" literally true.
+//
+// The tag is written too, and it is not decoration. A digest alone says nothing about which release it
+// is, so the version used to live in a comment beside it - unreadable to anything but a person, which
+// is why nothing reported when a newer image existed. `<repo>:<tag>@sha256:<digest>` states both: docker
+// resolves the digest and ignores the tag, and the freshness check reads the tag to ask the registry
+// what is newer. A bare tag is still rejected; the spec requires both halves.
+//
+// To move a pin, read the new digest with `docker buildx imagetools inspect <repo>:<tag>`.
+//
+// Two of the four tags below are not the versions their comments used to claim. The hadolint pin was
+// commented `2.14.0` and is the bytes of `v2.15.1`; the actionlint pin was commented `1.7.7` and is
+// `1.7.12`. Nothing could have caught that while the version was prose, which is the whole argument for
+// writing it where a check can read it.
+/** The exact image each containerised analyzer runs, by digest. */
+export const CONTAINER_IMAGES = {
+    gitleaks: 'zricethezav/gitleaks:v8.30.1@sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9ab65d25e6bc8abbb7f',
+    hadolint: 'hadolint/hadolint:v2.15.1@sha256:32dac94127fd60b7b7e3fbfc65e1383b9b5e25c9bfd7b8536de7a539fe68a12d',
+    actionlint: 'rhysd/actionlint:1.7.12@sha256:b1934ee5f1c509618f2508e6eb47ee0d3520686341fec936f3b79331f9315667',
+    // The standard makes a check a repository implements itself into its source code, and the ploaness
+    // verification command is a shell script that no analyzer read.
+    shellcheck: 'koalaman/shellcheck:v0.11.0@sha256:61862eba1fcf09a484ebcc6feea46f1782532571a34ed51fedf90dd25f925a8d',
+};
+/** Matches a reference that names image bytes AND the release they are, and only such a reference. */
+export const DIGEST_PINNED = /^[a-z0-9][a-z0-9._/-]*:[A-Za-z0-9][\w.-]*@sha256:[0-9a-f]{64}$/;
+/**
+ * Report every containerised analyzer whose image is not pinned to an exact digest.
+ * @param images the image reference declared for each tool.
+ * @returns one message per unpinned tool; empty means every verdict is reproducible.
+ */
+export const findUnpinnedImages = (images) => Object.entries(images)
+    .filter(([, reference]) => !DIGEST_PINNED.test(reference))
+    .map(([tool, reference]) => `${tool} runs "${reference}", which does not name both the release and its bytes; ` +
+    'pin it as <repo>:<tag>@sha256:<digest>');
+// The major version an `engines.node` range admits at its lowest. The CLI carried its own
+// `MINIMUM_NODE_MAJOR = 26` and decided the verdict with it, which put a rule in the I/O layer and made
+// a fourth copy of a number `pins.json` already states - and the copy that decided was the loose one.
+const LEADING_MAJOR = /(\d+)/;
+/**
+ * The lowest Node major an engines range admits.
+ * @param enginesNode the declared range, such as `>=26`.
+ * @returns the major version, or undefined when the range names none.
+ */
+export const minimumNodeMajor = (enginesNode) => {
+    const found = LEADING_MAJOR.exec(enginesNode ?? '');
+    return found === null ? undefined : Number(found[1]);
+};
+// Corepack permits an integrity suffix - `pnpm@11.9.0+sha512.<hash>` - and that specifier names the
+// same version as the bare one. Reading up to the `+` keeps a project that pasted Corepack's own
+// output from failing a rule about a number it got right.
+const PNPM_SPECIFIER = /^pnpm@([^+\s]+)(?:\+\S+)?$/;
+/**
+ * The exact pnpm version a `packageManager` specifier names.
+ *
+ * The version has one source - the `packageManager` pin - and everything else that states it is
+ * derived from here. `engines.pnpm` was pinned separately at `>=11` while `packageManager` said
+ * `pnpm@11.9.0`, which is the range ban applied to every dependency except the tool that resolves
+ * them: it told a reader that any pnpm 11 would build the same tree.
+ * @param packageManager the declared specifier, such as `pnpm@11.9.0`.
+ * @returns the version, or undefined when the specifier names another manager or no version.
+ */
+export const pinnedPnpmVersion = (packageManager) => {
+    const found = PNPM_SPECIFIER.exec(packageManager ?? '');
+    return found?.[1];
+};
+// pnpm identifies itself to every script it runs: `pnpm/11.9.0 npm/? node/v26.2.0 darwin arm64`. The
+// prefix is anchored at a word boundary because `@pnpm/exe/11.9.0` would otherwise match as `pnpm`.
+const PNPM_USER_AGENT = /(?:^|\s)pnpm\/(\S+)/;
+/**
+ * Report the pnpm actually running this command when it is not the pinned one.
+ *
+ * `packageManager` is a declaration, and Corepack obeys it only where Corepack is enabled. Without
+ * this the pin was a comment: a project could declare `pnpm@11.9.0`, pass the wiring gate, and resolve
+ * its whole tree with another pnpm - which is the one difference that changes what every other pin
+ * means, because the lockfile it produces is the input to every gate that follows.
+ * @param userAgent the `npm_config_user_agent` of the running process.
+ * @param required the pinned version, from {@link pinnedPnpmVersion}.
+ * @returns one finding when the running pnpm disagrees; empty when it agrees or cannot be observed.
+ */
+export const findPnpmRuntimeViolations = (userAgent, required) => {
+    const found = PNPM_USER_AGENT.exec(userAgent ?? '');
+    const running = found?.[1];
+    // An absent or non-pnpm user agent means this command was not started by pnpm at all - `npx`, a
+    // direct `node` invocation, a CI step calling the binary. There is no version to disagree with, and
+    // inventing a failure there would report a project for how its operator launched one command.
+    if (required === undefined || running === undefined || running === required) {
+        return [];
+    }
+    return [
+        `pnpm ${running} is running this command but ploaness pins pnpm@${required}; ` +
+            'enable Corepack, because the package manager resolves the tree every other pin describes',
+    ];
+};
+//# sourceMappingURL=toolchain-pins.js.map

package/dist/toolchain-pins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolchain-pins.js","sourceRoot":"","sources":["../src/toolchain-pins.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,EAAE;AACF,qGAAqG;AACrG,wGAAwG;AACxG,sGAAsG;AACtG,qGAAqG;AACrG,EAAE;AACF,uGAAuG;AACvG,sGAAsG;AACtG,yGAAyG;AACzG,qGAAqG;AACrG,8EAA8E;AAC9E,EAAE;AACF,2FAA2F;AAC3F,EAAE;AACF,qGAAqG;AACrG,oGAAoG;AACpG,wGAAwG;AACxG,wCAAwC;AAKxC,mEAAmE;AACnE,MAAM,CAAC,MAAM,gBAAgB,GAA4C;IACvE,QAAQ,EACN,sGAAsG;IACxG,QAAQ,EACN,mGAAmG;IACrG,UAAU,EACR,iGAAiG;IACnG,mGAAmG;IACnG,gEAAgE;IAChE,UAAU,EACR,qGAAqG;CACxG,CAAA;AAED,sGAAsG;AACtG,MAAM,CAAC,MAAM,aAAa,GACxB,gEAAgE,CAAA;AAElE;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAwC,EAAqB,EAAE,CAChG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;KACnB,MAAM,CAAC,CAAC,CAAC,EAAE,SAAS,CAA4B,EAAW,EAAE,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;KAC7F,GAAG,CACF,CAAC,CAAC,IAAI,EAAE,SAAS,CAA4B,EAAU,EAAE,CACvD,GAAG,IAAI,UAAU,SAAS,yDAAyD;IACnF,wCAAwC,CAC3C,CAAA;AAEL,0FAA0F;AAC1F,wGAAwG;AACxG,sGAAsG;AACtG,MAAM,aAAa,GAAW,OAAO,CAAA;AAErC;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,WAA+B,EAAsB,EAAE;IACtF,MAAM,KAAK,GAA2B,aAAa,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAA;IAC3E,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;AACtD,CAAC,CAAA;AAED,oGAAoG;AACpG,iGAAiG;AACjG,0DAA0D;AAC1D,MAAM,cAAc,GAAW,4BAA4B,CAAA;AAE3D;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,cAAkC,EAAsB,EAAE;IAC1F,MAAM,KAAK,GAA2B,cAAc,CAAC,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC,CAAA;IAC/E,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAA;AACnB,CAAC,CAAA;AAED,qGAAqG;AACrG,oGAAoG;AACpG,MAAM,eAAe,GAAW,qBAAqB,CAAA;AAErD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,SAA6B,EAC7B,QAA4B,EACT,EAAE;IACrB,MAAM,KAAK,GAA2B,eAAe,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAA;IAC3E,MAAM,OAAO,GAAuB,KAAK,EAAE,CAAC,CAAC,CAAC,CAAA;IAC9C,gGAAgG;IAChG,oGAAoG;IACpG,8FAA8F;IAC9F,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC5E,OAAO,EAAE,CAAA;IACX,CAAC;IACD,OAAO;QACL,QAAQ,OAAO,mDAAmD,QAAQ,IAAI;YAC5E,0FAA0F;KAC7F,CAAA;AACH,CAAC,CAAA"}

package/dist/url-safety.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Neutralise an untrusted href so a stored `javascript:`, `data:`, or `vbscript:` URL cannot execute
+ * when it is rendered into an anchor.
+ *
+ * Returning {@link NEUTRAL} is this function doing its job rather than falling back silently: the
+ * caller asked for an href safe to render, and a link that goes nowhere is that answer for an unsafe
+ * input. A caller that must know the input was rejected compares the result against what it passed in.
+ * @param href the raw href, typically authored in a CMS field.
+ * @returns the href unchanged when its scheme is safe or absent, and `#` when it is neither.
+ */
+export declare const safeHref: (href: string) => string;
+//# sourceMappingURL=url-safety.d.ts.map

package/dist/url-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-safety.d.ts","sourceRoot":"","sources":["../src/url-safety.ts"],"names":[],"mappings":"AAqCA;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,KAAG,MAevC,CAAA"}

package/dist/url-safety.js

@@ -0,0 +1,58 @@
+// The first inhabitant of this package that a consumer's application calls rather than a rule the
+// harness applies, and the placement is deliberate rather than convenient. It is a pure function over a
+// string, which is what this package holds and what its coverage floor measures; a package of its own
+// for one function would be a versioning surface bought for nothing. A reader who expects only rules
+// here should take this comment as the reason rather than as an accident.
+//
+// It exists because React does not cover this and every content-managed site needs it. React escapes
+// text content, so an editor cannot inject markup through a field - but an href is an attribute, and
+// `javascript:alert(1)` in a link field executes as the site the moment a visitor clicks it. Nothing in
+// the framework, the type system, or a linter reports that: the value is a string and it is rendered as
+// a string. Every project mapping a CMS field into an anchor has this problem, so the harness owns the
+// answer rather than leaving each project to rediscover it.
+/** The schemes safe to render into an anchor. A URL carrying no scheme at all is relative, and safe. */
+const SAFE_SCHEMES = new Set(['http', 'https', 'mailto', 'tel']);
+// A well-formed scheme, anchored at both ends so a relative path that merely contains a colon later -
+// `/schedule:today` - is not read as declaring one.
+const SCHEME_SHAPE = /^[a-z][a-z\d+.-]*$/;
+// Whitespace and control characters are removed before the scheme is read, because a browser removes
+// them too: a `javascript:` URL with a tab inside the scheme is still a javascript URL by the time it
+// is navigated, and reading the raw string would classify it as relative and pass it straight through.
+// Stripping more than a browser does can only move an input from relative to scheme-bearing, which is
+// the direction that neutralises rather than admits, so the wider strip is the conservative choice.
+//
+// `\p{Cc}` rather than the code points themselves: a class naming them is a control character inside a
+// regular expression, which the lint pass rejects and is right to, since the literal bytes would then
+// sit in this file invisibly. The property escape names the category in the open, and it leaves every
+// ordinary character - a hyphen in a host, for one - untouched.
+const IGNORED_BY_BROWSERS = /[\s\p{Cc}]+/gu;
+/** What an unsafe href is replaced with: a link that goes nowhere rather than one that runs. */
+const NEUTRAL = '#';
+const NO_COLON = -1;
+/**
+ * Neutralise an untrusted href so a stored `javascript:`, `data:`, or `vbscript:` URL cannot execute
+ * when it is rendered into an anchor.
+ *
+ * Returning {@link NEUTRAL} is this function doing its job rather than falling back silently: the
+ * caller asked for an href safe to render, and a link that goes nowhere is that answer for an unsafe
+ * input. A caller that must know the input was rejected compares the result against what it passed in.
+ * @param href the raw href, typically authored in a CMS field.
+ * @returns the href unchanged when its scheme is safe or absent, and `#` when it is neither.
+ */
+export const safeHref = (href) => {
+    const trimmed = href.trim();
+    if (trimmed.length === 0) {
+        return NEUTRAL;
+    }
+    const readable = trimmed.replaceAll(IGNORED_BY_BROWSERS, '').toLowerCase();
+    const colon = readable.indexOf(':');
+    if (colon === NO_COLON) {
+        return trimmed;
+    }
+    const scheme = readable.slice(0, colon);
+    if (!SCHEME_SHAPE.test(scheme)) {
+        return trimmed;
+    }
+    return SAFE_SCHEMES.has(scheme) ? trimmed : NEUTRAL;
+};
+//# sourceMappingURL=url-safety.js.map

package/dist/url-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-safety.js","sourceRoot":"","sources":["../src/url-safety.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,wGAAwG;AACxG,sGAAsG;AACtG,qGAAqG;AACrG,0EAA0E;AAC1E,EAAE;AACF,qGAAqG;AACrG,qGAAqG;AACrG,wGAAwG;AACxG,wGAAwG;AACxG,uGAAuG;AACvG,4DAA4D;AAE5D,wGAAwG;AACxG,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAS,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAA;AAE7F,sGAAsG;AACtG,oDAAoD;AACpD,MAAM,YAAY,GAAW,oBAAoB,CAAA;AAEjD,qGAAqG;AACrG,sGAAsG;AACtG,uGAAuG;AACvG,sGAAsG;AACtG,oGAAoG;AACpG,EAAE;AACF,uGAAuG;AACvG,sGAAsG;AACtG,sGAAsG;AACtG,gEAAgE;AAChE,MAAM,mBAAmB,GAAW,eAAe,CAAA;AAEnD,gGAAgG;AAChG,MAAM,OAAO,GAAW,GAAG,CAAA;AAE3B,MAAM,QAAQ,GAAW,CAAC,CAAC,CAAA;AAE3B;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAU,EAAE;IAC/C,MAAM,OAAO,GAAW,IAAI,CAAC,IAAI,EAAE,CAAA;IACnC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,OAAO,CAAA;IAChB,CAAC;IACD,MAAM,QAAQ,GAAW,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;IAClF,MAAM,KAAK,GAAW,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC3C,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,OAAO,OAAO,CAAA;IAChB,CAAC;IACD,MAAM,MAAM,GAAW,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;IAC/C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,OAAO,OAAO,CAAA;IAChB,CAAC;IACD,OAAO,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAA;AACrD,CAAC,CAAA"}

package/dist/version-policy.d.ts

@@ -0,0 +1,99 @@
+import type { WiringViolation } from './wiring-violation.js';
+/**
+ * How a finding names what it actually found.
+ *
+ * Exported because `wiring-policy.ts` reported the same thing in the same words with its own copy of
+ * this function, and the two modules already share this direction of import.
+ * @param found the declared value, or undefined when the key is absent.
+ * @returns `missing`, or the value in quotes.
+ */
+export declare const describeFound: (found: string | undefined) => string;
+/** The meta package a governed project declares, and the root of everything it inherits from ploaness. */
+export declare const HARNESS_PACKAGE: string;
+/**
+ * Whether a package name is one of ploaness's own.
+ *
+ * Exported because the `deps` gate asks the same question when it walks the manifests a project
+ * inherits, and it had no way to ask it but a second copy of the two literals above - which is the
+ * shape of drift this repository refuses everywhere else.
+ * @param packageName the declared name.
+ * @returns true for `ploaness` and for anything under its scope.
+ */
+export declare const isHarnessPackage: (packageName: string) => boolean;
+/**
+ * The package whose presence makes a project a Payload application.
+ *
+ * Exported because `preflight` and `workspace-policy` both ask the question and both wrote the literal
+ * themselves. The name decides which scope's gates a member receives, so it is not a string to keep
+ * three copies of.
+ */
+export declare const PAYLOAD_PACKAGE: string;
+/**
+ * The package whose presence makes a member a Next application.
+ *
+ * Read for the same reason as {@link PAYLOAD_PACKAGE}: it decides which shipped configuration a member
+ * receives. A Next application that is not a Payload one still has a build, a client bundle and a
+ * browser suite to govern.
+ */
+export declare const NEXT_PACKAGE: string;
+/** What the repository as a whole must declare, and the invariants those declarations imply. */
+export interface RepositoryVersionInputs {
+    /** Every pinned package, mapped to the exact version ploaness owns for it. */
+    readonly expected: Readonly<Record<string, string>>;
+    /** The exact `packageManager` field, or undefined when ploaness pins none. */
+    readonly requiredPackageManager: string | undefined;
+    /** The `engines` block the repository must declare. */
+    readonly requiredEngines: Readonly<Record<string, string>>;
+    /** The contents of pnpm-workspace.yaml, read at the repository root and nowhere else. */
+    readonly workspaceFile: string;
+    /** Every dependency any member declares, because a root override shadows all of them. */
+    readonly declaredAcrossMembers: Readonly<Record<string, string>>;
+}
+/** What one member must declare, judged against that member's own manifest. */
+export interface PackageVersionInputs {
+    readonly expected: Readonly<Record<string, string>>;
+    /** The subset this member must declare rather than merely match when present. */
+    readonly required: ReadonlySet<string>;
+    /** The version every `@payloadcms/*` package must carry, which is the pinned `payload` version. */
+    readonly payloadVersion: string | undefined;
+}
+/**
+ * Return every way the repository has changed, or could change, a version ploaness owns.
+ *
+ * These are the declarations pnpm honours at the workspace root and nowhere else. Read from a member's
+ * directory they described a file that was not there: the overrides check found none and reported no
+ * violation, vouching for pins that the root had already replaced.
+ * @param packageJson the repository root's parsed package.json.
+ * @param inputs the pinned versions and the invariants they imply.
+ * @returns one violation per defect, in a stable order.
+ */
+export declare const findRepositoryVersionViolations: (packageJson: Record<string, unknown>, inputs: RepositoryVersionInputs) => readonly WiringViolation[];
+/**
+ * Return every way one member has changed, or could change, a version ploaness owns.
+ * @param packageJson the member's parsed package.json.
+ * @param inputs the pinned versions this member is held to.
+ * @returns one violation per defect, in a stable order.
+ */
+export declare const findPackageVersionViolations: (packageJson: Record<string, unknown>, inputs: PackageVersionInputs) => readonly WiringViolation[];
+/** What a single-package project must declare, which is both scopes over one manifest. */
+export interface VersionInputs {
+    readonly expected: Readonly<Record<string, string>>;
+    readonly required: ReadonlySet<string>;
+    readonly payloadVersion: string | undefined;
+    readonly requiredPackageManager: string | undefined;
+    readonly requiredEngines: Readonly<Record<string, string>>;
+    readonly workspaceFile: string;
+}
+/**
+ * Every version violation for a repository holding exactly one package.
+ *
+ * Composes the two halves the way that case actually is: the sole member's manifest is also the
+ * repository's, so an override at the root and a declaration in the package are the same file. Kept as
+ * an entry point because the spec that pins this behaviour predates the split, and its passing
+ * unchanged is what shows nothing was lost in it.
+ * @param packageJson the project's parsed package.json.
+ * @param inputs the pinned versions and the invariants they imply.
+ * @returns one violation per defect, in a stable order.
+ */
+export declare const findVersionViolations: (packageJson: Record<string, unknown>, inputs: VersionInputs) => readonly WiringViolation[];
+//# sourceMappingURL=version-policy.d.ts.map

package/dist/version-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-policy.d.ts","sourceRoot":"","sources":["../src/version-policy.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAc5D;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,MACV,CAAA;AAWhD,0GAA0G;AAC1G,eAAO,MAAM,eAAe,EAAE,MAAmB,CAAA;AAEjD;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,aAAa,MAAM,KAAG,OACmB,CAAA;AA+M1E;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,MAAkB,CAAA;AAEhD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,MAAe,CAAA;AA8D1C,gGAAgG;AAChG,MAAM,WAAW,uBAAuB;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACnD,8EAA8E;IAC9E,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,SAAS,CAAA;IACnD,uDAAuD;IACvD,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC1D,yFAAyF;IACzF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,yFAAyF;IACzF,QAAQ,CAAC,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACjE;AAED,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACnD,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACtC,mGAAmG;IACnG,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5C;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,GAC1C,aAAa,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,QAAQ,uBAAuB,KAC9B,SAAS,eAAe,EAc1B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,GACvC,aAAa,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,QAAQ,oBAAoB,KAC3B,SAAS,eAAe,EAK1B,CAAA;AAED,0FAA0F;AAC1F,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACnD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3C,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,SAAS,CAAA;IACnD,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC1D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GAChC,aAAa,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,QAAQ,aAAa,KACpB,SAAS,eAAe,EAa1B,CAAA"}

package/dist/version-policy.js

@@ -0,0 +1,306 @@
+// The versions a governed project declares, and every way it could change one without saying so.
+//
+// This is the wiring module's other half. `wiring-policy.ts` judges the files a project points at
+// ploaness with; this judges the numbers beside its dependencies. The two were one file until it passed
+// the size cap, which is the cap doing its job: they answer different questions and share only the
+// helpers below.
+import { findOverrides, OVERRIDE_KEYS } from './install-policy.js';
+import { asOptionalText, asRecord, asStringRecord, declaredDependencies } from './json-shapes.js';
+import { pinnedPnpmVersion } from './toolchain-pins.js';
+// Which block a package is actually declared in. A finding that named `devDependencies` for a package
+// sitting in `dependencies` sent the reader to the wrong half of the file - and the framework pins,
+// which are runtime dependencies, are exactly the ones that would be misreported.
+const blockOf = (packageJson, name) => {
+    if (Object.hasOwn(asStringRecord(packageJson['dependencies']), name)) {
+        return 'dependencies';
+    }
+    return Object.hasOwn(asStringRecord(packageJson['devDependencies']), name)
+        ? 'devDependencies'
+        : undefined;
+};
+/**
+ * How a finding names what it actually found.
+ *
+ * Exported because `wiring-policy.ts` reported the same thing in the same words with its own copy of
+ * this function, and the two modules already share this direction of import.
+ * @param found the declared value, or undefined when the key is absent.
+ * @returns `missing`, or the value in quotes.
+ */
+export const describeFound = (found) => found === undefined ? 'missing' : `"${found}"`;
+// The harness's own packages, pointed at a local artefact. A consumer verifying ploaness before it is
+// published resolves them from a tarball, and that is the arrangement `it/verify.sh` exists to exercise
+// - so the rule has to permit it deliberately. It permitted it by accident until now: the override
+// reader split the line at its LAST colon, so `ploaness: "file:../ploaness-1.0.0.tgz"` parsed as a
+// package called `ploaness: "file` and matched nothing. Repairing the reader turned an accident into a
+// finding, which is the right time to say what was actually intended.
+const HARNESS_SCOPE = '@ploaness/';
+const LOCAL_ARTEFACT = /^(?:file|link|workspace):/;
+/** The meta package a governed project declares, and the root of everything it inherits from ploaness. */
+export const HARNESS_PACKAGE = 'ploaness';
+/**
+ * Whether a package name is one of ploaness's own.
+ *
+ * Exported because the `deps` gate asks the same question when it walks the manifests a project
+ * inherits, and it had no way to ask it but a second copy of the two literals above - which is the
+ * shape of drift this repository refuses everywhere else.
+ * @param packageName the declared name.
+ * @returns true for `ploaness` and for anything under its scope.
+ */
+export const isHarnessPackage = (packageName) => packageName === HARNESS_PACKAGE || packageName.startsWith(HARNESS_SCOPE);
+const isHarnessTarball = (entry) => isHarnessPackage(entry.packageName) && LOCAL_ARTEFACT.test(entry.specifier);
+const overrideViolation = (entry, expected, declared) => {
+    if (isHarnessTarball(entry)) {
+        return [];
+    }
+    const location = `pnpm-workspace.yaml ${entry.key}.${entry.packageName}`;
+    if (Object.hasOwn(expected, entry.packageName)) {
+        return [
+            {
+                location,
+                reason: 'redefines a version ploaness pins; remove it, because the pin decides what the ' +
+                    'gates run against',
+            },
+        ];
+    }
+    const own = declared[entry.packageName];
+    return own === undefined
+        ? []
+        : [
+            {
+                location,
+                reason: `overrides a package the project declares at "${own}"; change the declaration ` +
+                    'instead, or the installed version is not the declared one',
+            },
+        ];
+};
+// A project may override what it does not declare, and may not override what it does. The permitted
+// case is a transitive package carrying an advisory with no upgrade path above it, which the project
+// can reach no other way and which the standard says to resolve by upgrading rather than excusing. The
+// forbidden case is a package whose version the project already wrote down: two declarations of one
+// version will not stay equal, and the one that loses is the one every reader believes. The ploaness
+// packages are neither, so a pre-publication consumer may still point them at a local tarball.
+// The declared set is the union across members rather than the root's own, because a root override
+// shadows a version ANY member wrote down - and in a workspace the package that declared it is usually
+// not the root at all.
+const checkPinnedOverridesAcross = (workspaceFile, expected, declaredAcrossMembers) => findOverrides(workspaceFile).flatMap((entry) => overrideViolation(entry, expected, { ...declaredAcrossMembers }));
+// Corepack reads `packageManager` and runs exactly that version, so it decides how every other pinned
+// version is resolved. A project on a different pnpm can produce a different tree from the same
+// lockfile, which makes every pin above it a statement about a graph nobody built.
+const checkPackageManager = (packageJson, required) => {
+    if (required === undefined) {
+        return [];
+    }
+    const declared = packageJson['packageManager'];
+    return declared === required
+        ? []
+        : [
+            {
+                location: 'package.json packageManager',
+                reason: `is ${describeFound(asOptionalText(declared))} but ploaness requires "${required}"`,
+            },
+        ];
+};
+// The `engines.pnpm` entry is DERIVED from the `packageManager` pin rather than pinned beside it.
+// Corepack reads one field and an installer reads the other, so two literals would be two statements
+// about a single version - and this was the pair that had already drifted apart in meaning: an exact
+// `pnpm@11.9.0` beside a `>=11` floor told a reader that any pnpm 11 would resolve the same tree.
+const enginesRequiredBy = (inputs) => {
+    const pnpm = pinnedPnpmVersion(inputs.requiredPackageManager);
+    return pnpm === undefined ? inputs.requiredEngines : { ...inputs.requiredEngines, pnpm };
+};
+// `preflight` checks the Node that is actually running, which is the version a gate is executed by.
+// The `engines` block is a different statement: it is what the project tells an installer, a CI image
+// and a reader to use. Leaving it unchecked let a project declare a runtime ploaness refuses.
+const checkEngines = (packageJson, required) => {
+    const declared = asStringRecord(packageJson['engines']);
+    return Object.entries(required).flatMap(([name, range]) => declared[name] === range
+        ? []
+        : [
+            {
+                location: `package.json engines.${name}`,
+                reason: `is ${describeFound(declared[name])} but ploaness requires "${range}"`,
+            },
+        ]);
+};
+// The same four keys `install-policy.ts` reads out of the workspace file, read here out of package.json
+// instead: an override or resolution declared locally; a patch, which swaps a package's code while its
+// version says otherwise; and a package extension, which rewrites a manifest the resolver then obeys.
+// None is visible in the dependency block a reader checks, which is what makes them worth naming - and
+// the list is imported rather than restated, because two copies of it in one gate will not stay equal.
+// A patch is keyed by `name@version`, and a scoped name begins with the same character, so the split is
+// on the last `@` rather than the first.
+const packageNameOf = (key) => {
+    const at = key.lastIndexOf('@');
+    return at > 0 ? key.slice(0, at) : key;
+};
+const escapeEntries = (packageJson) => OVERRIDE_KEYS.flatMap((key) => [packageJson, asRecord(packageJson['pnpm'])].flatMap((holder) => Object.keys(asRecord(holder[key])).map((entry) => [key, entry])));
+const checkVersionEscapes = (packageJson, expected) => escapeEntries(packageJson)
+    .filter(([, entry]) => Object.hasOwn(expected, packageNameOf(entry ?? '')))
+    .map(([key, entry]) => ({
+    location: `package.json ${key ?? ''}.${entry ?? ''}`,
+    reason: 'changes what a version ploaness pins installs; the pin decides what the gates run ' +
+        'against, and a project cannot answer for a version it did not choose',
+}));
+// A specifier that is not a registry version at all: a local tarball, a workspace link, a git or npm
+// alias. None of them is a range, and a pre-publication consumer resolves the ploaness packages this
+// way, so the range ban must read past them rather than through them.
+const NON_REGISTRY = /^(?:file|link|workspace|catalog|git\+[a-z]+|git|github|npm|https?):/;
+// Anything that resolves to "whichever version is newest at install time". The standard pins the
+// toolchain so an upstream release cannot change a verdict while the project stays unchanged, and a
+// range on an application dependency is the same hole one layer down: the build, the suite and the
+// end-to-end run all execute against something nobody wrote down. `*` and an empty specifier are the
+// widest ranges of all rather than exceptions to the rule.
+const RANGE_OPERATOR = /^\s*(?:[\^~><=*]|$)/;
+// A union, a hyphen range, or an `x` standing in for a whole version component. Each `x` form is
+// anchored at a component boundary: written unanchored, `.x` also matched a legitimate exact
+// prerelease such as `1.0.0-canary.x1` and reported it as a range.
+const RANGE_UNION = /\|\||\s-\s|(?:^|[.\s])x(?:[.\s]|$)/;
+// An exact version begins with a digit. Everything else that is neither a range operator nor a
+// non-registry specifier is a DIST TAG - `latest`, `next`, `beta` - which is the widest range of all:
+// it resolves to whatever the publisher moved the tag to since the project last installed. The rule
+// used to test only for range syntax, so every dist tag passed as though it were a pinned version.
+const EXACT_VERSION = /^\d/;
+// An `npm:` alias names a registry package like any other declaration - `npm:preact@^10` carries a
+// range, and reading past the whole prefix let it through. Only the version half is judged, by the same
+// rule; the alias itself is a naming decision the project is entitled to make.
+const NPM_ALIAS = 'npm:';
+const isExactVersion = (specifier) => {
+    if (specifier.startsWith(NPM_ALIAS)) {
+        const aliased = specifier.slice(NPM_ALIAS.length);
+        const at = aliased.lastIndexOf('@');
+        return at > 0 && isExactVersion(aliased.slice(at + 1));
+    }
+    if (NON_REGISTRY.test(specifier)) {
+        return true;
+    }
+    if (RANGE_OPERATOR.test(specifier) || RANGE_UNION.test(specifier)) {
+        return false;
+    }
+    return EXACT_VERSION.test(specifier);
+};
+const checkExactVersions = (packageJson) => Object.entries(declaredDependencies(packageJson))
+    .filter(([, specifier]) => !isExactVersion(specifier))
+    .map(([name, specifier]) => ({
+    location: `package.json ${name}`,
+    reason: `is "${specifier}", which is a range; declare one exact version, because a range ` +
+        'lets an upstream release change what the gates run against',
+}));
+// Payload refuses to boot, or fails in ways that read as application defects, when its own packages
+// disagree about their version. The rule is derived from the pinned `payload` rather than written as a
+// list, so a project adding `@payloadcms/plugin-form-builder` is covered by the rule that already
+// exists instead of by an entry somebody has to remember.
+const PAYLOAD_SCOPE = '@payloadcms/';
+/**
+ * The package whose presence makes a project a Payload application.
+ *
+ * Exported because `preflight` and `workspace-policy` both ask the question and both wrote the literal
+ * themselves. The name decides which scope's gates a member receives, so it is not a string to keep
+ * three copies of.
+ */
+export const PAYLOAD_PACKAGE = 'payload';
+/**
+ * The package whose presence makes a member a Next application.
+ *
+ * Read for the same reason as {@link PAYLOAD_PACKAGE}: it decides which shipped configuration a member
+ * receives. A Next application that is not a Payload one still has a build, a client bundle and a
+ * browser suite to govern.
+ */
+export const NEXT_PACKAGE = 'next';
+const checkPayloadFamily = (packageJson, payloadVersion) => {
+    if (payloadVersion === undefined) {
+        return [];
+    }
+    return Object.entries(declaredDependencies(packageJson))
+        .filter(([name, version]) => name.startsWith(PAYLOAD_SCOPE) && version !== payloadVersion)
+        .map(([name, version]) => ({
+        location: `package.json ${name}`,
+        reason: `is "${version}" but payload is pinned at "${payloadVersion}"; ` +
+            'Payload fails at runtime when its own packages disagree',
+    }));
+};
+// Two obligations, not one. A project must DECLARE the few packages every project uses, because under
+// the strict pnpm layout its own specs could not resolve them otherwise. Every other pinned package
+// must MATCH when the project declares it, but is not forced on a project that has no use for it -
+// requiring a declaration there would manufacture a dependency the dead-code gate then reports as
+// unused. Either way no pinned version can float, which is the point.
+const checkTestLibraries = (packageJson, expected, required) => {
+    const declared = declaredDependencies(packageJson);
+    return Object.entries(expected).flatMap(([name, version]) => {
+        const found = declared[name];
+        if (found === undefined) {
+            return required.has(name)
+                ? [
+                    {
+                        location: `package.json ${name}`,
+                        reason: `missing; ploaness pins it, so the project must declare it at ${version}`,
+                    },
+                ]
+                : [];
+        }
+        return found === version
+            ? []
+            : [
+                {
+                    location: `package.json ${blockOf(packageJson, name) ?? ''}.${name}`,
+                    reason: `is "${found}" but ploaness pins it at "${version}"; ` +
+                        'a range lets an upstream release change a verdict',
+                },
+            ];
+    });
+};
+/**
+ * Return every way the repository has changed, or could change, a version ploaness owns.
+ *
+ * These are the declarations pnpm honours at the workspace root and nowhere else. Read from a member's
+ * directory they described a file that was not there: the overrides check found none and reported no
+ * violation, vouching for pins that the root had already replaced.
+ * @param packageJson the repository root's parsed package.json.
+ * @param inputs the pinned versions and the invariants they imply.
+ * @returns one violation per defect, in a stable order.
+ */
+export const findRepositoryVersionViolations = (packageJson, inputs) => [
+    ...checkPackageManager(packageJson, inputs.requiredPackageManager),
+    ...checkEngines(packageJson, enginesRequiredBy({
+        requiredEngines: inputs.requiredEngines,
+        requiredPackageManager: inputs.requiredPackageManager,
+    })),
+    ...checkPinnedOverridesAcross(inputs.workspaceFile, inputs.expected, inputs.declaredAcrossMembers),
+];
+/**
+ * Return every way one member has changed, or could change, a version ploaness owns.
+ * @param packageJson the member's parsed package.json.
+ * @param inputs the pinned versions this member is held to.
+ * @returns one violation per defect, in a stable order.
+ */
+export const findPackageVersionViolations = (packageJson, inputs) => [
+    ...checkTestLibraries(packageJson, inputs.expected, inputs.required),
+    ...checkExactVersions(packageJson),
+    ...checkPayloadFamily(packageJson, inputs.payloadVersion),
+    ...checkVersionEscapes(packageJson, inputs.expected),
+];
+/**
+ * Every version violation for a repository holding exactly one package.
+ *
+ * Composes the two halves the way that case actually is: the sole member's manifest is also the
+ * repository's, so an override at the root and a declaration in the package are the same file. Kept as
+ * an entry point because the spec that pins this behaviour predates the split, and its passing
+ * unchanged is what shows nothing was lost in it.
+ * @param packageJson the project's parsed package.json.
+ * @param inputs the pinned versions and the invariants they imply.
+ * @returns one violation per defect, in a stable order.
+ */
+export const findVersionViolations = (packageJson, inputs) => [
+    ...findPackageVersionViolations(packageJson, {
+        expected: inputs.expected,
+        required: inputs.required,
+        payloadVersion: inputs.payloadVersion,
+    }),
+    ...findRepositoryVersionViolations(packageJson, {
+        expected: inputs.expected,
+        requiredPackageManager: inputs.requiredPackageManager,
+        requiredEngines: inputs.requiredEngines,
+        workspaceFile: inputs.workspaceFile,
+        declaredAcrossMembers: declaredDependencies(packageJson),
+    }),
+];
+//# sourceMappingURL=version-policy.js.map