@ploaness/governance 1.0.0 → 1.2.0

package/dist/editorconfig-policy.js

@@ -1,15 +1,5 @@
-// Conformance to the committed `.editorconfig`, plus the standard's line cap.
-//
-// The `.editorconfig` is a pinned managed file, so every project holds the same one - and until now
-// nothing checked a single file against it. The formatter covers only the globs it owns, which leaves
-// Markdown, YAML, shell scripts, and Dockerfiles free to carry a CRLF, a tab, a trailing space, or a
-// missing final newline.
-//
-// The expectations are read from the `.editorconfig` itself rather than restated here, so editing the
-// pinned file moves the gate with it and the gate cannot contradict the file it checks against. The one
-// value that does NOT come from there is the line cap: `max_line_length` is an editor hint that tells a
-// ruler where to sit, while the standard's 120 characters is a cap that binds as an error. A project's
-// formatter may aim shorter, and frequently does.
+// Judge committed formatting and the authored-code line cap independently of filesystem access.
+import { CODE_EXTENSIONS, hasExtension, matchesGlob } from './file-roles.js';
 /** The standard's line cap. Not configurable: a cap is never raised. */
 export const MAX_LINE_LENGTH = 120;
 const FIRST_LINE = 1;
@@ -80,6 +70,23 @@ const lineViolations = (content, rules, isLineLengthEnforced) => {
         });
     });
 };
+/**
+ * Decide whether the standard's line cap binds for one file.
+ * @param filePath the repo-relative path.
+ * @param generatedArtefacts the globs the project declares generated.
+ * @returns true for an authored code file; false for prose and for generated output.
+ */
+// A cap is a rule about how a person writes code, so it reaches code roles only - and only where a
+// person wrote it. A generator emits what it emits: Payload renders each migration statement as one SQL
+// string, and no formatter setting and no edit shortens it, because the file is frozen once applied.
+// Holding a project to a cap it cannot satisfy would teach it to exclude the path from this gate
+// altogether, which would cost the encoding and whitespace rules too - and those a generated file does
+// satisfy, because the project runs its own formatter over the output.
+// Matched as globs, not through `isGovernedCode`: `generatedArtefacts` is declared as globs and reaches
+// ESLint's ignore list as globs, and `src/migrations/**` is not merely a different pattern under regex
+// rules - `new RegExp` rejects it outright, so the gate would have thrown rather than reported.
+export const isLineCapEnforced = (filePath, generatedArtefacts) => hasExtension(filePath, CODE_EXTENSIONS) &&
+    !generatedArtefacts.some((pattern) => matchesGlob(pattern, filePath));
 /**
  * Check one file against the committed configuration.
  * @param content the file's decoded content.

package/dist/editorconfig-policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"editorconfig-policy.js","sourceRoot":"","sources":["../src/editorconfig-policy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"editorconfig-policy.js","sourceRoot":"","sources":["../src/editorconfig-policy.ts"],"names":[],"mappings":"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"}

package/dist/environment-coherence.d.ts

@@ -0,0 +1,87 @@
+/** Where a variable was declared, for a message that names the two places rather than one. */
+export type EnvironmentOrigin = 'application' | 'compose';
+/** An environment variable declared in one place and absent from another it has to reach. */
+export interface EnvironmentViolation {
+    readonly name: string;
+    readonly origin: EnvironmentOrigin;
+    readonly reason: string;
+}
+/** A workflow, as the rule needs it: what to call it in a finding, and what it says. */
+export interface WorkflowFile {
+    readonly file: string;
+    readonly content: string;
+}
+/** Inputs for {@link findEnvironmentViolations}, already read so the core stays pure. */
+export interface EnvironmentInputs {
+    /** The contents of every validated environment module the repository holds, one per member. */
+    readonly applicationSources: readonly string[];
+    /** The contents of the example file, or undefined when the repository ships none. */
+    readonly example: string | undefined;
+    /** The contents of every compose file. */
+    readonly composeSources: readonly string[];
+    /** Every workflow the repository ships. Only the verifying ones are judged. */
+    readonly workflows: readonly WorkflowFile[];
+}
+/**
+ * The module a Payload project reads `process.env` in, which is the only module ploaness exempts from
+ * the ban and therefore the only one this rule can read a variable name out of.
+ */
+export declare const VALIDATED_ENVIRONMENT_MODULE: string;
+/**
+ * Every module exempt from the `process.env` ban.
+ *
+ * `src/proxy.ts` is exempt for a structural reason rather than a convenience one - Next mandates the
+ * file and runs it in the edge runtime, where the validated module is not reachable - and what it reads
+ * there is `NODE_ENV`, which the framework sets. So it is exempt from the LINT rule and is deliberately
+ * not read by this one: it holds no project configuration to document.
+ */
+export declare const ENVIRONMENT_READ_EXEMPTIONS: readonly string[];
+/**
+ * The example files a repository may document its environment in, most conventional first.
+ *
+ * A list rather than one name because the convention is not universal, and a project using
+ * `.env.sample` has documented its variables just as well as one using `.env.example`.
+ */
+export declare const ENVIRONMENT_EXAMPLE_FILES: readonly string[];
+/**
+ * The variables an application reads out of its validated environment module.
+ * @param source the contents of that module.
+ * @returns each name once, sorted, so a finding list is deterministic.
+ */
+export declare const readEnvironmentNames: (source: string) => readonly string[];
+/**
+ * The variables an example file documents.
+ * @param example the contents of the example file.
+ * @returns each name once, sorted.
+ */
+export declare const documentedEnvironmentNames: (example: string) => readonly string[];
+/**
+ * The variables a compose file interpolates without supplying a default.
+ * @param compose the contents of the compose file.
+ * @returns each name once, sorted.
+ */
+export declare const interpolatedEnvironmentNames: (compose: string) => readonly string[];
+/**
+ * The variables a workflow supplies, by any means and at any nesting depth.
+ * @param workflow the contents of the workflow file.
+ * @returns each name once, sorted.
+ */
+export declare const workflowSuppliedNames: (workflow: string) => readonly string[];
+/**
+ * Whether a workflow runs a ploaness verification, and therefore evaluates the compose files.
+ * @param workflow the contents of the workflow file.
+ * @returns true when the workflow invokes verification or a single gate.
+ */
+export declare const isVerifyingWorkflow: (workflow: string) => boolean;
+/**
+ * Every environment variable declared in one place and absent from another it has to reach.
+ *
+ * Three containments, each one-directional. What the application reads must be documented. What a
+ * compose file interpolates must be documented, because `docker compose config` reads the example file
+ * a developer copied. And what a compose file interpolates must be supplied by every workflow that
+ * verifies, because a workflow has no copied file to interpolate from.
+ * @param inputs the files, already read.
+ * @returns the violations, sorted by name within each rule. An empty array means the four places agree.
+ */
+export declare const findEnvironmentViolations: (inputs: EnvironmentInputs) => readonly EnvironmentViolation[];
+//# sourceMappingURL=environment-coherence.d.ts.map

package/dist/environment-coherence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-coherence.d.ts","sourceRoot":"","sources":["../src/environment-coherence.ts"],"names":[],"mappings":"AAEA,8FAA8F;AAC9F,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,SAAS,CAAA;AAEzD,6FAA6F;AAC7F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IAChC,+FAA+F;IAC/F,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,0CAA0C;IAC1C,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,SAAS,YAAY,EAAE,CAAA;CAC5C;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAAiC,CAAA;AAE5E;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAGxD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAItD,CAAA;AA4CD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,MAAM,KAAG,SAAS,MAAM,EAChB,CAAA;AAErD;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,GAAI,SAAS,MAAM,KAAG,SAAS,MAAM,EAClB,CAAA;AAE1D;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,MAAM,KAAG,SAAS,MAAM,EACjB,CAAA;AAE7D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,UAAU,MAAM,KAAG,SAAS,MAAM,EAIpE,CAAA;AAEJ;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,MAAM,KAAG,OAC4B,CAAA;AA+BnF;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GACpC,QAAQ,iBAAiB,KACxB,SAAS,oBAAoB,EAkC/B,CAAA"}

package/dist/environment-coherence.js

@@ -0,0 +1,128 @@
+// Require environment reads, example declarations, compose interpolation, and verifying workflows to agree.
+/**
+ * The module a Payload project reads `process.env` in, which is the only module ploaness exempts from
+ * the ban and therefore the only one this rule can read a variable name out of.
+ */
+export const VALIDATED_ENVIRONMENT_MODULE = 'src/lib/environment.ts';
+/**
+ * Every module exempt from the `process.env` ban.
+ *
+ * `src/proxy.ts` is exempt for a structural reason rather than a convenience one - Next mandates the
+ * file and runs it in the edge runtime, where the validated module is not reachable - and what it reads
+ * there is `NODE_ENV`, which the framework sets. So it is exempt from the LINT rule and is deliberately
+ * not read by this one: it holds no project configuration to document.
+ */
+export const ENVIRONMENT_READ_EXEMPTIONS = [
+    VALIDATED_ENVIRONMENT_MODULE,
+    'src/proxy.ts',
+];
+/**
+ * The example files a repository may document its environment in, most conventional first.
+ *
+ * A list rather than one name because the convention is not universal, and a project using
+ * `.env.sample` has documented its variables just as well as one using `.env.example`.
+ */
+export const ENVIRONMENT_EXAMPLE_FILES = [
+    '.env.example',
+    '.env.sample',
+    '.env.template',
+];
+// BRACKET ACCESS ONLY, and that is the rule rather than a shortcut. `process.env` is an index
+// signature, so a variable this project invented can only be read with brackets; a variable node or the
+// framework DECLARES - `NODE_ENV` above all - is a known property and is read with a dot. The two forms
+// therefore separate project configuration, which `.env.example` owes a reader, from the ambient
+// variables a runtime sets and no example file should claim to document.
+const BRACKETED_READ = /process\.env\[\s*(?<quote>['"])(?<name>[A-Za-z_]\w*)\k<quote>\s*\]/g;
+// A dotenv assignment: a name at the start of a line, optionally exported, followed by `=`. A comment
+// line cannot match, because `#` is not a name character.
+const EXAMPLE_ASSIGNMENT = /^[ \t]*(?:export[ \t]+)?(?<name>[A-Za-z_]\w*)[ \t]*=/gm;
+// A compose interpolation with NO default. `${NAME}` must be supplied; `${NAME:-5432}` and `${NAME-x}`
+// supply themselves, and `${NAME:?message}` declares its own failure, so none of the three is this
+// gate's business. The braced form alone is read: `$NAME` is legal in compose and rare in practice, and
+// telling it apart from a `$$` escape or a shell fragment inside a `command:` is guesswork.
+const COMPOSE_INTERPOLATION = /\$\{(?<name>[A-Z_]\w*)\}/gi;
+// A name a workflow supplies: a mapping key in SCREAMING_SNAKE, or a reference to a secret, a variable,
+// or the job environment. The key form is matched at any indentation, for the reason the header states.
+const WORKFLOW_KEY = /^[ \t]*(?<name>[A-Z_][A-Z0-9_]*)[ \t]*:/gm;
+const WORKFLOW_CONTEXT_REFERENCE = /\$\{\{[^}]*?\b(?:secrets|vars|env)\.(?<name>[A-Za-z_]\w*)/g;
+// What makes a workflow one whose job environment has to carry the compose variables: it runs a
+// ploaness verification, and verification validates every compose file the repository ships. A workflow
+// that publishes a release or labels an issue evaluates no compose file and is owed nothing.
+const VERIFYING_COMMANDS = ['ploaness verify', 'ploaness gate', 'run verify'];
+// Read through a NAMED group rather than a positional one. The bracketed-read pattern needs a
+// back-reference to match a quote with its own kind, which puts the name in the second group and the
+// quote in the first - a number that says nothing at the call site and that the magic-number rule is
+// right to refuse. Every pattern here therefore captures into `name`.
+const namesMatching = (source, pattern) => [...source.matchAll(pattern)].map((match) => String(match.groups?.['name']));
+const uniqueSorted = (names) => [...new Set(names)].sort((left, right) => left.localeCompare(right));
+/**
+ * The variables an application reads out of its validated environment module.
+ * @param source the contents of that module.
+ * @returns each name once, sorted, so a finding list is deterministic.
+ */
+export const readEnvironmentNames = (source) => uniqueSorted(namesMatching(source, BRACKETED_READ));
+/**
+ * The variables an example file documents.
+ * @param example the contents of the example file.
+ * @returns each name once, sorted.
+ */
+export const documentedEnvironmentNames = (example) => uniqueSorted(namesMatching(example, EXAMPLE_ASSIGNMENT));
+/**
+ * The variables a compose file interpolates without supplying a default.
+ * @param compose the contents of the compose file.
+ * @returns each name once, sorted.
+ */
+export const interpolatedEnvironmentNames = (compose) => uniqueSorted(namesMatching(compose, COMPOSE_INTERPOLATION));
+/**
+ * The variables a workflow supplies, by any means and at any nesting depth.
+ * @param workflow the contents of the workflow file.
+ * @returns each name once, sorted.
+ */
+export const workflowSuppliedNames = (workflow) => uniqueSorted([
+    ...namesMatching(workflow, WORKFLOW_KEY),
+    ...namesMatching(workflow, WORKFLOW_CONTEXT_REFERENCE),
+]);
+/**
+ * Whether a workflow runs a ploaness verification, and therefore evaluates the compose files.
+ * @param workflow the contents of the workflow file.
+ * @returns true when the workflow invokes verification or a single gate.
+ */
+export const isVerifyingWorkflow = (workflow) => VERIFYING_COMMANDS.some((command) => workflow.includes(command));
+const undocumented = (names, documented, origin, reason) => names
+    .filter((name) => !documented.has(name))
+    .map((name) => ({ name, origin, reason }));
+const missingFromWorkflow = (names, workflow) => {
+    const supplied = new Set(workflowSuppliedNames(workflow.content));
+    return names
+        .filter((name) => !supplied.has(name))
+        .map((name) => ({
+        name,
+        origin: 'compose',
+        reason: [
+            'interpolated by a compose file but not supplied by',
+            `${workflow.file}, where verification will evaluate it`,
+        ].join(' '),
+    }));
+};
+/**
+ * Every environment variable declared in one place and absent from another it has to reach.
+ *
+ * Three containments, each one-directional. What the application reads must be documented. What a
+ * compose file interpolates must be documented, because `docker compose config` reads the example file
+ * a developer copied. And what a compose file interpolates must be supplied by every workflow that
+ * verifies, because a workflow has no copied file to interpolate from.
+ * @param inputs the files, already read.
+ * @returns the violations, sorted by name within each rule. An empty array means the four places agree.
+ */
+export const findEnvironmentViolations = (inputs) => {
+    const documented = new Set(inputs.example === undefined ? [] : documentedEnvironmentNames(inputs.example));
+    const read = uniqueSorted(inputs.applicationSources.flatMap((source) => readEnvironmentNames(source)));
+    const interpolated = uniqueSorted(inputs.composeSources.flatMap((source) => interpolatedEnvironmentNames(source)));
+    const verifying = inputs.workflows.filter((workflow) => isVerifyingWorkflow(workflow.content));
+    return [
+        ...undocumented(read, documented, 'application', 'read by the validated environment module but documented in no example file'),
+        ...undocumented(interpolated, documented, 'compose', 'interpolated by a compose file but documented in no example file'),
+        ...verifying.flatMap((workflow) => missingFromWorkflow(interpolated, workflow)),
+    ];
+};
+//# sourceMappingURL=environment-coherence.js.map

package/dist/environment-coherence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-coherence.js","sourceRoot":"","sources":["../src/environment-coherence.ts"],"names":[],"mappings":"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"}

package/dist/environment-files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"environment-files.d.ts","sourceRoot":"","sources":["../src/environment-files.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAA2B,CAAA;AAE9E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC9B,gBAAgB,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,KAChD,SAAS,MAAM,EAC6D,CAAA;AAE/E;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM,GAAI,WAAW,MAAM,KAAG,MAAM,GAAG,SASnD,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EACrD,aAAa,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,KACnE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAe/B,CAAA"}
+{"version":3,"file":"environment-files.d.ts","sourceRoot":"","sources":["../src/environment-files.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAA2B,CAAA;AAE9E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC9B,gBAAgB,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,KAChD,SAAS,MAAM,EAC6D,CAAA;AAE/E;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM,GAAI,WAAW,MAAM,KAAG,MAAM,GAAG,SASnD,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EACrD,aAAa,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,KACnE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAe/B,CAAA"}

package/dist/environment-files.js

@@ -1,22 +1,4 @@
-// The environment files a run of the project reads into its own process.
-//
-// A Payload config validates `process.env` at module scope, so anything that boots the project boots
-// its configuration first. Next reads these files itself, which is why the application under test never
-// had a problem - but a test runner does not, and the runner ploaness ships a Playwright config for
-// boots the project in its OWN process: an end-to-end helper that seeds a user through `getPayload`
-// evaluates `payload.config.ts` at spec-collection time, before a browser or a server is involved.
-//
-// The project used to load them from its own `playwright.config.ts`. The wiring gate now requires that
-// file to be a bare re-export, which removes the only seam it had, so the harness that took the seam
-// away owes the load. Vitest is the other half of the same shape and keeps its own answer: a project
-// writes `vitest.setup.ts` and ploaness loads it, which is a seam the project still owns.
-//
-// The order is the part that carries meaning, and it is stated here rather than at the call site so
-// that it is measured: `packages/config` is an analyzer configuration that no coverage floor reads,
-// while everything in this package is unit-tested. Nothing loaded later may replace a value already
-// set, so the file that must win is read first, and a variable the real environment already carries -
-// a CI secret, a `DATABASE_URL` exported by a service container - outranks every file, because it was
-// there before any of them was read.
+// Declare environment file precedence shared by analysis, tests, and application startup.
 /**
  * The environment files a run reads, highest precedence first. `.env.local` leads because it is the
  * personal, untracked override of `.env`; the managed `.gitignore` ignores both, which is what makes

package/dist/environment-files.js.map

@@ -1 +1 @@
-{"version":3,"file":"environment-files.js","sourceRoot":"","sources":["../src/environment-files.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,EAAE;AACF,qGAAqG;AACrG,wGAAwG;AACxG,oGAAoG;AACpG,oGAAoG;AACpG,mGAAmG;AACnG,EAAE;AACF,uGAAuG;AACvG,qGAAqG;AACrG,qGAAqG;AACrG,0FAA0F;AAC1F,EAAE;AACF,oGAAoG;AACpG,oGAAoG;AACpG,oGAAoG;AACpG,sGAAsG;AACtG,sGAAsG;AACtG,qCAAqC;AAErC;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB,CAAC,YAAY,EAAE,MAAM,CAAC,CAAA;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,cAAiD,EAC9B,EAAE,CACrB,qBAAqB,CAAC,MAAM,CAAC,CAAC,IAAY,EAAW,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAA;AAE/E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,SAAiB,EAAsB,EAAE;IAC9D,IAAI,CAAC;QACH,MAAM,IAAI,GAAW,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAA;QAC5C,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,+FAA+F;QAC/F,kFAAkF;QAClF,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,OAAqD,EACrD,WAAoE,EAClC,EAAE,CACpC,MAAM,CAAC,WAAW,CAChB,WAAW;KACR,OAAO,CACN,CACE,IAAkD,EACT,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CACnE;KACA,MAAM,CACL,CAAC,KAA4C,EAA6B,EAAE,CAC1E,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAC5D;IACD,kGAAkG;IAClG,mEAAmE;KAClE,UAAU,EAAE,CAChB,CAAA"}
+{"version":3,"file":"environment-files.js","sourceRoot":"","sources":["../src/environment-files.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAE1F;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB,CAAC,YAAY,EAAE,MAAM,CAAC,CAAA;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,cAAiD,EAC9B,EAAE,CACrB,qBAAqB,CAAC,MAAM,CAAC,CAAC,IAAY,EAAW,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAA;AAE/E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,SAAiB,EAAsB,EAAE;IAC9D,IAAI,CAAC;QACH,MAAM,IAAI,GAAW,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAA;QAC5C,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,+FAA+F;QAC/F,kFAAkF;QAClF,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,OAAqD,EACrD,WAAoE,EAClC,EAAE,CACpC,MAAM,CAAC,WAAW,CAChB,WAAW;KACR,OAAO,CACN,CACE,IAAkD,EACT,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CACnE;KACA,MAAM,CACL,CAAC,KAA4C,EAA6B,EAAE,CAC1E,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAC5D;IACD,kGAAkG;IAClG,mEAAmE;KAClE,UAAU,EAAE,CAChB,CAAA"}

package/dist/file-roles.d.ts

@@ -15,13 +15,18 @@ export declare const isBinary: (bytes: Uint8Array) => boolean;
  * @returns true when the path ends with one of them.
  */
 export declare const hasExtension: (filePath: string, extensions: readonly string[]) => boolean;
+/** A role regex evaluated either at the repository root or inside its declaring member. */
+export type RolePattern = string | {
+    readonly memberPath: string;
+    readonly pattern: string;
+};
 /**
  * Decide whether a path is excluded by a declared role pattern.
  * @param filePath the repo-relative path.
  * @param patterns the declared exclusion patterns.
  * @returns true when any pattern matches.
  */
-export declare const matchesRole: (filePath: string, patterns: readonly string[]) => boolean;
+export declare const matchesRole: (filePath: string, patterns: readonly RolePattern[]) => boolean;
 /**
  * Whether a repo-relative path matches a glob pattern of the kind the coverage settings carry.
  * @param pattern the glob, such as `src/app/**` or `src/**\/*.tsx`.
@@ -35,5 +40,5 @@ export declare const matchesGlob: (pattern: string, filePath: string) => boolean
  * @param excluded the declared generated-role patterns.
  * @returns true when the file is code and no declared role excludes it.
  */
-export declare const isGovernedCode: (filePath: string, excluded: readonly string[]) => boolean;
+export declare const isGovernedCode: (filePath: string, excluded: readonly RolePattern[]) => boolean;
 //# sourceMappingURL=file-roles.d.ts.map

package/dist/file-roles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-roles.d.ts","sourceRoot":"","sources":["../src/file-roles.ts"],"names":[],"mappings":"AAYA,sGAAsG;AACtG,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAU5C,CAAA;AAED,kGAAkG;AAClG,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAA6B,CAAA;AAE3E;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,UAAU,KAAG,OACM,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,UAAU,MAAM,EAAE,YAAY,SAAS,MAAM,EAAE,KAAG,OACA,CAAA;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,MAAM,EAAE,UAAU,SAAS,MAAM,EAAE,KAAG,OACK,CAAA;AA2BjF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG,OAG9C,CAAA;AAElB;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,EAAE,UAAU,SAAS,MAAM,EAAE,KAAG,OACF,CAAA"}
+{"version":3,"file":"file-roles.d.ts","sourceRoot":"","sources":["../src/file-roles.ts"],"names":[],"mappings":"AAKA,sGAAsG;AACtG,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAW5C,CAAA;AAED,kGAAkG;AAClG,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAA6B,CAAA;AAE3E;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,UAAU,KAAG,OACM,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,UAAU,MAAM,EAAE,YAAY,SAAS,MAAM,EAAE,KAAG,OACA,CAAA;AAE/E,2FAA2F;AAC3F,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAY5F;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,MAAM,EAAE,UAAU,SAAS,WAAW,EAAE,KAAG,OACI,CAAA;AA2BrF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG,OAG9C,CAAA;AAElB;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,EAAE,UAAU,SAAS,WAAW,EAAE,KAAG,OACP,CAAA"}

package/dist/file-roles.js

@@ -1,17 +1,11 @@
-// File roles: the categories a repository can determine from a file itself and uses to include or
-// exclude it from a check.
-//
-// The typography ban used to carry its own allowlist of ten extensions, which is the wrong shape for a
-// rule that reaches "every tracked file the repository does not exclude by role": a `.css`, a `.adoc`,
-// a shell script, or a Dockerfile went unscanned, and every new text format arrived unscanned until
-// someone remembered to extend the list. A role predicate is default-safe in the opposite direction -
-// a new format is covered by construction, and exclusion is the thing that must be stated.
+// Identify source, generated, binary, and prose roles so exclusions follow file meaning rather than tool defaults.
 /** How much of a file is inspected before deciding it is text. Enough to reach any real header. */
 const BINARY_PROBE_BYTES = 8192;
 /** Extensions the Code Rules apply to, used where a rule is about code rather than about any text. */
 export const CODE_EXTENSIONS = [
     '.ts',
     '.tsx',
+    '.jsx',
     '.mts',
     '.cts',
     '.js',
@@ -35,13 +29,20 @@ export const isBinary = (bytes) => bytes.subarray(0, BINARY_PROBE_BYTES).include
  * @returns true when the path ends with one of them.
  */
 export const hasExtension = (filePath, extensions) => extensions.some((extension) => filePath.endsWith(extension));
+const matchesPattern = (filePath, pattern) => {
+    if (typeof pattern === 'string') {
+        return new RegExp(pattern).test(filePath);
+    }
+    const prefix = `${pattern.memberPath}/`;
+    return (filePath.startsWith(prefix) && new RegExp(pattern.pattern).test(filePath.slice(prefix.length)));
+};
 /**
  * Decide whether a path is excluded by a declared role pattern.
  * @param filePath the repo-relative path.
  * @param patterns the declared exclusion patterns.
  * @returns true when any pattern matches.
  */
-export const matchesRole = (filePath, patterns) => patterns.some((pattern) => new RegExp(pattern).test(filePath));
+export const matchesRole = (filePath, patterns) => patterns.some((pattern) => matchesPattern(filePath, pattern));
 // The glob dialect the coverage settings are written in, which is not the regex dialect `matchesRole`
 // reads. `**/` crosses directory boundaries and `*` does not, which is the whole distinction between
 // `src/**/*.tsx` and `src/*.tsx`; collapsing the two would silently widen every pattern that uses one.

package/dist/file-roles.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-roles.js","sourceRoot":"","sources":["../src/file-roles.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,2BAA2B;AAC3B,EAAE;AACF,uGAAuG;AACvG,uGAAuG;AACvG,oGAAoG;AACpG,sGAAsG;AACtG,2FAA2F;AAE3F,mGAAmG;AACnG,MAAM,kBAAkB,GAAW,IAAI,CAAA;AAEvC,sGAAsG;AACtG,MAAM,CAAC,MAAM,eAAe,GAAsB;IAChD,KAAK;IACL,MAAM;IACN,MAAM;IACN,MAAM;IACN,KAAK;IACL,MAAM;IACN,MAAM;IACN,MAAM;IACN,OAAO;CACR,CAAA;AAED,kGAAkG;AAClG,MAAM,CAAC,MAAM,gBAAgB,GAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;AAE3E;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAiB,EAAW,EAAE,CACrD,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;AAEnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,QAAgB,EAAE,UAA6B,EAAW,EAAE,CACvF,UAAU,CAAC,IAAI,CAAC,CAAC,SAAiB,EAAW,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAA;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAgB,EAAE,QAA2B,EAAW,EAAE,CACpF,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAe,EAAW,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAA;AAEjF,sGAAsG;AACtG,qGAAqG;AACrG,uGAAuG;AACvG,MAAM,UAAU,GAAW,iCAAiC,CAAA;AAE5D,MAAM,YAAY,GAAG,CAAC,KAAa,EAAU,EAAE;IAC7C,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,OAAO,aAAa,CAAA;QACtB,CAAC;QACD,KAAK,IAAI,CAAC,CAAC,CAAC;YACV,OAAO,IAAI,CAAA;QACb,CAAC;QACD,KAAK,GAAG,CAAC,CAAC,CAAC;YACT,OAAO,OAAO,CAAA;QAChB,CAAC;QACD,KAAK,GAAG,CAAC,CAAC,CAAC;YACT,OAAO,MAAM,CAAA;QACf,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACR,OAAO,KAAK,KAAK,EAAE,CAAA;QACrB,CAAC;IACH,CAAC;AACH,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAe,EAAE,QAAgB,EAAW,EAAE,CACxE,IAAI,MAAM,CACR,IAAI,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,KAAa,EAAU,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,GAAG,CACtF,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;AAElB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,QAAgB,EAAE,QAA2B,EAAW,EAAE,CACvF,YAAY,CAAC,QAAQ,EAAE,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA"}
+{"version":3,"file":"file-roles.js","sourceRoot":"","sources":["../src/file-roles.ts"],"names":[],"mappings":"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"}

package/dist/freshness-repair.d.ts

@@ -0,0 +1,82 @@
+import type { DeclaredCoordinate, FreshnessFinding, ManifestSource } from './dependency-freshness.js';
+/**
+ * Who can act on a freshness finding.
+ *
+ * - `project`: declared by this repository at a version it chooses. Change the declaration.
+ * - `pin`: declared by this repository at a version ploaness decides. The wiring gate holds the
+ *   declaration to the pin, so the repair is a ploaness release that carries the newer one.
+ * - `inherited`: declared in a manifest this repository inherits from ploaness. The same repair, with
+ *   no line in the project to edit at all.
+ */
+export type FreshnessRepair = 'project' | 'pin' | 'inherited';
+/** The order the groups print in: what the reader can act on first. */
+export declare const REPAIR_ORDER: readonly FreshnessRepair[];
+/** What the report needs to know about whose version a name is. */
+export interface FreshnessOwnership {
+    /** Every name whose exact version ploaness pins for a project that declares it. */
+    readonly pinnedByHarness: ReadonlySet<string>;
+    /**
+     * True when the repository under judgement is ploaness itself. Its pins are a file it tracks, so a
+     * pinned coordinate there is the project's to change like any other.
+     */
+    readonly isHarnessItself: boolean;
+}
+/** One group of the report: the findings that share a repair, under the line that states it. */
+export interface FreshnessSection {
+    readonly repair: FreshnessRepair;
+    /** The action for every finding beneath it, stated once. */
+    readonly heading: string;
+    readonly findings: readonly FreshnessFinding[];
+}
+/**
+ * Whether this repository is ploaness: it tracks the manifest of the package called `ploaness`.
+ *
+ * Decided from what the tree contains rather than from a flag, for the reason a member's kind is
+ * derived from what it declares: nothing can describe itself into a weaker reading. Read from the
+ * project's own manifests only, because in a consumer the same name arrives as an INHERITED manifest,
+ * and that is exactly the case this must answer `false` for.
+ * @param manifests every manifest the gate read, the project's own and the inherited ones.
+ * @returns true when a manifest the project tracks is ploaness's own.
+ */
+export declare const isHarnessRepository: (manifests: readonly ManifestSource[]) => boolean;
+/**
+ * Whether ploaness decides the version a project declares a name at.
+ *
+ * Three rules, each one the wiring gate already enforces and each derived from it rather than restated:
+ * a pinned name must match the pin, a `@payloadcms/*` package must match the pinned `payload`, and a
+ * `@ploaness/*` package must match the declared `ploaness`. `ploaness` itself is the one exception,
+ * and it proves the third rule: the release is the single version a project is entitled to choose,
+ * and upgrading it is the repair every line in the two harness groups names.
+ * @param name the declared name.
+ * @param pinnedByHarness every name ploaness pins.
+ * @returns true when the project may not change the version on its own.
+ */
+export declare const isVersionDecidedByHarness: (name: string, pinnedByHarness: ReadonlySet<string>) => boolean;
+/**
+ * Whose repair one coordinate is.
+ * @param coordinate the declared coordinate, with the manifest that declares it.
+ * @param ownership whose version each name is.
+ * @returns the group the finding belongs in.
+ */
+export declare const repairOf: (coordinate: DeclaredCoordinate, ownership: FreshnessOwnership) => FreshnessRepair;
+/**
+ * Whether a finding is the harness release itself, in the project's own manifest.
+ *
+ * It is the one line in the project group whose repair is every harness line's repair, so the report
+ * says so on it.
+ * @param finding the finding to classify.
+ * @returns true for `ploaness` declared by the project.
+ */
+export declare const isHarnessRelease: (finding: DeclaredCoordinate) => boolean;
+/**
+ * Sort the report's findings into the three repair groups, in the order they print.
+ *
+ * Every group is returned, empty or not, so the caller decides what an empty one prints as; the
+ * order within a group is the order the findings arrived in, which is manifest order, so the same tree
+ * yields the same report.
+ * @param findings every finding the report will print.
+ * @param ownership whose version each name is.
+ * @returns the three groups, each under its heading.
+ */
+export declare const sectionFreshnessReport: (findings: readonly FreshnessFinding[], ownership: FreshnessOwnership) => readonly FreshnessSection[];
+//# sourceMappingURL=freshness-repair.d.ts.map

package/dist/freshness-repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness-repair.d.ts","sourceRoot":"","sources":["../src/freshness-repair.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACf,MAAM,2BAA2B,CAAA;AAKlC;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,KAAK,GAAG,WAAW,CAAA;AAE7D,uEAAuE;AACvE,eAAO,MAAM,YAAY,EAAE,SAAS,eAAe,EAAoC,CAAA;AAEvF,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC7C;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAClC;AAED,gGAAgG;AAChG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAC/C;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAAI,WAAW,SAAS,cAAc,EAAE,KAAG,OAIxE,CAAA;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,GACpC,MAAM,MAAM,EACZ,iBAAiB,WAAW,CAAC,MAAM,CAAC,KACnC,OAEoF,CAAA;AAEvF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GACnB,YAAY,kBAAkB,EAC9B,WAAW,kBAAkB,KAC5B,eAQF,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,kBAAkB,KAAG,OACL,CAAA;AAwB1D;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,GACjC,UAAU,SAAS,gBAAgB,EAAE,EACrC,WAAW,kBAAkB,KAC5B,SAAS,gBAAgB,EAa3B,CAAA"}

package/dist/freshness-repair.js

@@ -0,0 +1,91 @@
+// Assign each update to the project or harness that owns its version, using the wiring policy as authority.
+import { HARNESS_PACKAGE, isHarnessPackage } from './harness-package.js';
+import { asRecord, asText } from './json-shapes.js';
+import { isPayloadFamilyPackage } from './version-policy.js';
+/** The order the groups print in: what the reader can act on first. */
+export const REPAIR_ORDER = ['project', 'pin', 'inherited'];
+/**
+ * Whether this repository is ploaness: it tracks the manifest of the package called `ploaness`.
+ *
+ * Decided from what the tree contains rather than from a flag, for the reason a member's kind is
+ * derived from what it declares: nothing can describe itself into a weaker reading. Read from the
+ * project's own manifests only, because in a consumer the same name arrives as an INHERITED manifest,
+ * and that is exactly the case this must answer `false` for.
+ * @param manifests every manifest the gate read, the project's own and the inherited ones.
+ * @returns true when a manifest the project tracks is ploaness's own.
+ */
+export const isHarnessRepository = (manifests) => manifests.some((manifest) => !manifest.isInherited && asText(asRecord(manifest.packageJson)['name']) === HARNESS_PACKAGE);
+/**
+ * Whether ploaness decides the version a project declares a name at.
+ *
+ * Three rules, each one the wiring gate already enforces and each derived from it rather than restated:
+ * a pinned name must match the pin, a `@payloadcms/*` package must match the pinned `payload`, and a
+ * `@ploaness/*` package must match the declared `ploaness`. `ploaness` itself is the one exception,
+ * and it proves the third rule: the release is the single version a project is entitled to choose,
+ * and upgrading it is the repair every line in the two harness groups names.
+ * @param name the declared name.
+ * @param pinnedByHarness every name ploaness pins.
+ * @returns true when the project may not change the version on its own.
+ */
+export const isVersionDecidedByHarness = (name, pinnedByHarness) => name !== HARNESS_PACKAGE &&
+    (pinnedByHarness.has(name) || isPayloadFamilyPackage(name) || isHarnessPackage(name));
+/**
+ * Whose repair one coordinate is.
+ * @param coordinate the declared coordinate, with the manifest that declares it.
+ * @param ownership whose version each name is.
+ * @returns the group the finding belongs in.
+ */
+export const repairOf = (coordinate, ownership) => {
+    if (coordinate.isInherited) {
+        return 'inherited';
+    }
+    return !ownership.isHarnessItself &&
+        isVersionDecidedByHarness(coordinate.name, ownership.pinnedByHarness)
+        ? 'pin'
+        : 'project';
+};
+/**
+ * Whether a finding is the harness release itself, in the project's own manifest.
+ *
+ * It is the one line in the project group whose repair is every harness line's repair, so the report
+ * says so on it.
+ * @param finding the finding to classify.
+ * @returns true for `ploaness` declared by the project.
+ */
+export const isHarnessRelease = (finding) => !finding.isInherited && finding.name === HARNESS_PACKAGE;
+// The two harness groups name one repair, and which one depends on whether there is a release to take.
+// A heading that said "upgrade ploaness" over a project already on the latest release would send the
+// reader to an upgrade that does not exist; the honest statement then is that the wait is on ploaness.
+const harnessRepair = (hasNewerHarness) => hasNewerHarness
+    ? `upgrading ${HARNESS_PACKAGE} is the repair`
+    : `no newer ${HARNESS_PACKAGE} release is published yet, so the repair is to report a version ` +
+        'that matters';
+const headingOf = (repair, hasNewerHarness) => {
+    const headings = {
+        project: 'yours to change: declared by this project at a version it chooses',
+        pin: `pinned by ${HARNESS_PACKAGE}: declared by this project at a version ${HARNESS_PACKAGE} ` +
+            `decides, and the wiring gate holds it there; ${harnessRepair(hasNewerHarness)}`,
+        inherited: `declared by ${HARNESS_PACKAGE}: in manifests this project inherits, so there is nothing ` +
+            `here to edit; ${harnessRepair(hasNewerHarness)}`,
+    };
+    return headings[repair];
+};
+/**
+ * Sort the report's findings into the three repair groups, in the order they print.
+ *
+ * Every group is returned, empty or not, so the caller decides what an empty one prints as; the
+ * order within a group is the order the findings arrived in, which is manifest order, so the same tree
+ * yields the same report.
+ * @param findings every finding the report will print.
+ * @param ownership whose version each name is.
+ * @returns the three groups, each under its heading.
+ */
+export const sectionFreshnessReport = (findings, ownership) => {
+    const hasNewerHarness = findings.some((finding) => isHarnessRelease(finding));
+    return REPAIR_ORDER.map((repair) => ({
+        repair,
+        heading: headingOf(repair, hasNewerHarness),
+        findings: findings.filter((finding) => repairOf(finding, ownership) === repair),
+    }));
+};
+//# sourceMappingURL=freshness-repair.js.map

package/dist/freshness-repair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness-repair.js","sourceRoot":"","sources":["../src/freshness-repair.ts"],"names":[],"mappings":"AAAA,4GAA4G;AAO5G,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AAa5D,uEAAuE;AACvE,MAAM,CAAC,MAAM,YAAY,GAA+B,CAAC,SAAS,EAAE,KAAK,EAAE,WAAW,CAAC,CAAA;AAqBvF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,SAAoC,EAAW,EAAE,CACnF,SAAS,CAAC,IAAI,CACZ,CAAC,QAAwB,EAAW,EAAE,CACpC,CAAC,QAAQ,CAAC,WAAW,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,eAAe,CAC9F,CAAA;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,IAAY,EACZ,eAAoC,EAC3B,EAAE,CACX,IAAI,KAAK,eAAe;IACxB,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAA;AAEvF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,UAA8B,EAC9B,SAA6B,EACZ,EAAE;IACnB,IAAI,UAAU,CAAC,WAAW,EAAE,CAAC;QAC3B,OAAO,WAAW,CAAA;IACpB,CAAC;IACD,OAAO,CAAC,SAAS,CAAC,eAAe;QAC/B,yBAAyB,CAAC,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,eAAe,CAAC;QACrE,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,SAAS,CAAA;AACf,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAA2B,EAAW,EAAE,CACvE,CAAC,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,IAAI,KAAK,eAAe,CAAA;AAE1D,uGAAuG;AACvG,qGAAqG;AACrG,uGAAuG;AACvG,MAAM,aAAa,GAAG,CAAC,eAAwB,EAAU,EAAE,CACzD,eAAe;IACb,CAAC,CAAC,aAAa,eAAe,gBAAgB;IAC9C,CAAC,CAAC,YAAY,eAAe,kEAAkE;QAC7F,cAAc,CAAA;AAEpB,MAAM,SAAS,GAAG,CAAC,MAAuB,EAAE,eAAwB,EAAU,EAAE;IAC9E,MAAM,QAAQ,GAA8C;QAC1D,OAAO,EAAE,mEAAmE;QAC5E,GAAG,EACD,aAAa,eAAe,2CAA2C,eAAe,GAAG;YACzF,gDAAgD,aAAa,CAAC,eAAe,CAAC,EAAE;QAClF,SAAS,EACP,eAAe,eAAe,4DAA4D;YAC1F,iBAAiB,aAAa,CAAC,eAAe,CAAC,EAAE;KACpD,CAAA;IACD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAA;AACzB,CAAC,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,QAAqC,EACrC,SAA6B,EACA,EAAE;IAC/B,MAAM,eAAe,GAAY,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAyB,EAAW,EAAE,CACpF,gBAAgB,CAAC,OAAO,CAAC,CAC1B,CAAA;IACD,OAAO,YAAY,CAAC,GAAG,CACrB,CAAC,MAAuB,EAAoB,EAAE,CAAC,CAAC;QAC9C,MAAM;QACN,OAAO,EAAE,SAAS,CAAC,MAAM,EAAE,eAAe,CAAC;QAC3C,QAAQ,EAAE,QAAQ,CAAC,MAAM,CACvB,CAAC,OAAyB,EAAW,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,KAAK,MAAM,CAChF;KACF,CAAC,CACH,CAAA;AACH,CAAC,CAAA"}

package/dist/generated-denial.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generated-denial.d.ts","sourceRoot":"","sources":["../src/generated-denial.ts"],"names":[],"mappings":"AAWA,sGAAsG;AACtG,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAIhD,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,WAAW,SAAS,MAAM,EAAE,KAAG,SAAS,MAAM,EAI5E,CAAA;AASJ;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GACzB,UAAU,OAAO,EACjB,WAAW,SAAS,MAAM,EAAE,KAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CASxB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC/B,UAAU,OAAO,EACjB,eAAe,OAAO,EACtB,WAAW,SAAS,MAAM,EAAE,KAC3B,SAAS,MAAM,EAgBjB,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,GACzB,aAAa,SAAS,MAAM,EAAE,EAC9B,WAAW,SAAS,MAAM,EAAE,KAC3B,SAAS,MAAM,EAKf,CAAA"}
+{"version":3,"file":"generated-denial.d.ts","sourceRoot":"","sources":["../src/generated-denial.ts"],"names":[],"mappings":"AAGA,sGAAsG;AACtG,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAIhD,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,WAAW,SAAS,MAAM,EAAE,KAAG,SAAS,MAAM,EAI5E,CAAA;AASJ;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GACzB,UAAU,OAAO,EACjB,WAAW,SAAS,MAAM,EAAE,KAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CASxB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC/B,UAAU,OAAO,EACjB,eAAe,OAAO,EACtB,WAAW,SAAS,MAAM,EAAE,KAC3B,SAAS,MAAM,EAgBjB,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,GACzB,aAAa,SAAS,MAAM,EAAE,EAC9B,WAAW,SAAS,MAAM,EAAE,KAC3B,SAAS,MAAM,EAKf,CAAA"}