@ploaness/governance 1.0.0

package/dist/settings-layering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-layering.d.ts","sourceRoot":"","sources":["../src/settings-layering.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,KAAK,iBAAiB,EAAmB,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAA;AA8DtF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAUxB,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,GAC1B,YAAY,MAAM,EAClB,OAAO,iBAAiB,KACvB,iBAaF,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB,GAC7B,iBAAiB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAChC,QAGD,CAAA"}

package/dist/settings-layering.js

@@ -0,0 +1,134 @@
+// How a member's settings sit on top of the repository's.
+//
+// A workspace declares some facts once and some per package. Which is which is not uniform, and reading
+// it wrong is silent either way: concatenating two `pretest` commands would run a mangled argv, while
+// letting a member REPLACE `sourceRoots` would narrow the scope the harness refuses to narrow.
+//
+// Layering happens on the RAW blocks, before any default is applied. Merging defaulted objects instead
+// would make "declared nothing" indistinguishable from "declared exactly the default", so a repository
+// that declared a stricter bundle budget would be silently overwritten by every member that declared
+// none.
+import { asRecord, isArray } from './json-shapes.js';
+import { readRawSettings } from './settings.js';
+/** Keys where a member ADDS to what the repository declared, the way `sourceRoots` always has. */
+const ADDITIVE = new Set([
+    'sourceRoots',
+    'unmanagedAssets',
+    'typographyExclusions',
+    'javascriptAllowlist',
+    'coverageExclude',
+    'vulnerabilityAllowlist',
+    'secretAllowlist',
+    'publicAccess',
+    'auxiliaryServers',
+    'accessibilitySkipRoutes',
+    'frameworkGlue',
+    'pureLogicRoots',
+]);
+// Keys where only a smaller number is honoured. A member may hold itself to more than the repository
+// asked for and never to less, which is the same direction `readSettings` already clamps the shipped
+// defaults in.
+const STRICTEST_NUMBER = new Set([
+    'accessibilityRouteBudget',
+    'bundleBudgetBytes',
+    'maxSuppressions',
+]);
+/** Keys that are one value describing one package, where the member's answer replaces the repository's. */
+const REPLACED = new Set([
+    'pretest',
+    'testWrapper',
+    'serverUrl',
+    'vulnerabilitySeverity',
+]);
+const mergeArrays = (base, overlay) => [
+    ...(isArray(base) ? base : []),
+    ...(isArray(overlay) ? overlay : []),
+];
+const smaller = (base, overlay) => {
+    if (typeof base !== 'number') {
+        return overlay;
+    }
+    return typeof overlay === 'number' ? Math.min(base, overlay) : base;
+};
+const mergeValue = (key, base, overlay) => {
+    if (ADDITIVE.has(key)) {
+        return mergeArrays(base, overlay);
+    }
+    if (STRICTEST_NUMBER.has(key)) {
+        return smaller(base, overlay);
+    }
+    if (REPLACED.has(key)) {
+        return overlay ?? base;
+    }
+    // Everything else is a record of independent entries - `analysisEnv` is the only one today - where a
+    // member naming a variable the repository did not should keep both.
+    return { ...asRecord(base), ...asRecord(overlay) };
+};
+/**
+ * Fold a member's raw settings block onto the repository's.
+ * @param base the repository's raw block.
+ * @param overlay the member's raw block.
+ * @returns one raw block, still undefaulted.
+ */
+export const layerSettingBlocks = (base, overlay) => {
+    const keys = new Set([...Object.keys(base), ...Object.keys(overlay)]);
+    return Object.fromEntries([...keys].map((key) => [
+        key,
+        Object.hasOwn(base, key) && Object.hasOwn(overlay, key)
+            ? mergeValue(key, base[key], overlay[key])
+            : (base[key] ?? overlay[key]),
+    ]));
+};
+/**
+ * Move a member's exclusion into the repository's path space.
+ *
+ * The gates that walk the tracked tree run once, at the repository root, while a member declares its
+ * exclusions relative to itself. `^src/generated/` written inside `apps/web` therefore matches nothing
+ * when the repository-scope gate walks past `apps/web/src/generated/`, and a generated directory a
+ * project correctly excused starts failing the typography ban.
+ *
+ * An UNANCHORED pattern is left alone, deliberately. `importMap\.js$` already matches at any depth, and
+ * prefixing it would narrow it to one member - so the rule errs toward a pattern that matches too much
+ * at repository scope rather than one that silently stops matching. Too wide is the safe direction here:
+ * a repository-scope gate that skips one extra path reports one fewer finding, while a narrowed pattern
+ * reports a project for a file it had already accounted for.
+ * @param memberPath the member's repo-relative path, `.` for the member at the root.
+ * @param entry the exclusion as the member declared it.
+ * @returns the exclusion as the repository-scope gates must read it.
+ */
+export const rebaseExclusion = (memberPath, entry) => {
+    if (memberPath === '.') {
+        return entry;
+    }
+    if (entry.kind === 'route') {
+        return entry;
+    }
+    if (entry.kind === 'glob') {
+        return { ...entry, pattern: `${memberPath}/${entry.pattern}` };
+    }
+    return entry.pattern.startsWith('^')
+        ? { ...entry, pattern: `^${memberPath}/${entry.pattern.slice(1)}` }
+        : entry;
+};
+/**
+ * The settings one member runs under.
+ *
+ * Effective VALUES are layered - a member inherits the repository's source roots, its typography
+ * exclusions, its floor. `declaredExclusions` is not, and that asymmetry is the point: it is the list of
+ * decisions THIS package made, and every consumer of it judges the declarer. Layering it made a member
+ * answer for the repository's declarations, so a workspace root that correctly excused its Vale detector
+ * definitions - whose content IS the character the ban detects - had every member report that exclusion
+ * as reaching nothing, because no member contains the file. One correct declaration, two gates failed,
+ * and nothing a member could edit would have fixed it.
+ *
+ * The mirror direction was already handled: `rebaseExclusion` moves a member's exclusion up into the
+ * repository's path space. This is the same seam read downward.
+ * @param repositoryBlock the raw `ploaness` block of the repository root.
+ * @param ownBlock the raw `ploaness` block of the member itself.
+ * @returns the member's settings, inheriting values and owning declarations.
+ */
+export const readMemberSettings = (repositoryBlock, ownBlock) => ({
+    ...readRawSettings(layerSettingBlocks(repositoryBlock, ownBlock)),
+    declaredExclusions: readRawSettings(ownBlock).declaredExclusions,
+});
+//# sourceMappingURL=settings-layering.js.map

package/dist/settings-layering.js.map

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

package/dist/settings.d.ts

@@ -0,0 +1,238 @@
+import type { SecretException } from './secret-policy.js';
+import type { VulnerabilityException } from './vulnerability-policy.js';
+/**
+ * How a declared exclusion's pattern is matched against a path. The settings that carry each kind know
+ * it at the point they are read, which is the only place the answer is not a guess: `^\.vale/styles/`
+ * and `src/app/**` are both plausible-looking strings and neither matches under the other's rules.
+ */
+export type ExclusionKind = 'regex' | 'glob' | 'route';
+/** One exclusion a project declared, and the file role it claims. */
+export interface DeclaredExclusion {
+    /** Which setting it came from, so a finding can name it. */
+    readonly setting: string;
+    readonly pattern: string;
+    readonly reason: string;
+    readonly kind: ExclusionKind;
+}
+/**
+ * One anonymous permission a project grants on purpose, with the reason it does.
+ *
+ * The managed access-boundary sweep asks the running application what it grants an unauthenticated
+ * caller and fails on what it finds. Some grants are the point of the site - a published page a
+ * stranger must be able to read, a contact form a stranger must be able to submit - so a project
+ * records those here and the sweep passes them. An entry missing any field is dropped, which restores
+ * the finding rather than widening the sweep, which is the safe direction to fail in.
+ */
+export interface PublicAccess {
+    /** The collection or global slug, as Payload itself reports it. */
+    readonly entity: string;
+    /** The operation granted: create, read, update, or delete. */
+    readonly operation: string;
+    readonly reason: string;
+}
+/** A managed path a project has taken over from the catalogue, with the reason it did so. */
+export interface UnmanagedAsset {
+    readonly path: string;
+    readonly reason: string;
+}
+/**
+ * A server the project's own end-to-end specs need beside the application under test.
+ *
+ * It carries no `reason`, unlike an exclusion. An exclusion without one is dropped because a dropped
+ * exclusion widens what a gate judges, which is the safe direction to fail in; a dropped server would
+ * instead leave a spec failing against a port nothing is listening on, which is a confusing failure
+ * rather than a strict one. This is a fact ploaness cannot know, like {@link Settings.serverUrl}, not a
+ * carve-out the project has to justify.
+ */
+export interface AuxiliaryServer {
+    /** The command that starts it, as Playwright takes it: one string rather than an argv list. */
+    readonly command: string;
+    /** The origin Playwright waits for before the suite starts. */
+    readonly url: string;
+    /**
+     * The directory to start it in, relative to the member under test.
+     *
+     * A sibling application is started from its own package, not from the one being tested. Without this
+     * the only way to say so was a `cd` inside the command, which then resolves the framework binary from
+     * the wrong package's `.bin` - correct exactly while the two packages pin the same version.
+     */
+    readonly cwd?: string;
+}
+/** The parameters a consuming project may declare under the `ploaness` key of its package.json. */
+export interface Settings {
+    /** Directories holding first-party source, used by the convention and coverage gates. */
+    readonly sourceRoots: readonly string[];
+    /** Managed paths the project owns instead, each with a recorded reason. */
+    readonly unmanagedAssets: readonly UnmanagedAsset[];
+    /** Repo-relative path patterns exempt from the typography ban (generated files only). */
+    readonly typographyExclusions: readonly string[];
+    /**
+     * Paths holding framework-generated scaffolding, which the lint pass relaxes rather than judges.
+     *
+     * The relaxation set is real and correct; expressing it only as `src/app/(payload)/**` made it
+     * unreachable for anything else. A Next application that is not a Payload one has route handlers and
+     * layouts with exactly the same property - written by a framework to a shape a project does not
+     * choose - and no way to say so. Additive to the Payload paths, so declaring nothing keeps the
+     * contract a Payload project already had.
+     */
+    readonly frameworkGlue: readonly string[];
+    /**
+     * Paths a generator owns, which no rule may judge and no agent may edit.
+     *
+     * The default names where Payload puts them in a stock installation. Payload lets a project mount its
+     * admin panel elsewhere, and one that does had every one of these rules miss: the import map was
+     * denied to nobody, diffed by nothing, handed to the formatter, and then linted as hand-written
+     * source - which is how a generated file full of hash-suffixed identifiers came to be told to rename
+     * them. Additive, so a stock installation declares nothing.
+     */
+    readonly generatedArtefacts: readonly string[];
+    /**
+     * Directories that form the pure-logic floor: they may depend on nothing else under the source root.
+     *
+     * The architecture contract calls the layer map "the one genuinely project-shaped part" and then
+     * hard-coded it to `src/access` and `src/lib`. A project placing pure logic elsewhere had no way to
+     * state that without owning a forbidden file. Additive, so the shipped floor still holds.
+     */
+    readonly pureLogicRoots: readonly string[];
+    /** Every exclusion the project declared, honoured or not, so a gate can judge them. */
+    readonly declaredExclusions: readonly DeclaredExclusion[];
+    /** Repo-relative path patterns exempt from the hand-written-JavaScript ban. */
+    readonly javascriptAllowlist: readonly string[];
+    /** Glob patterns excluded from coverage measurement, by role rather than by convenience. */
+    readonly coverageExclude: readonly string[];
+    /** Ceiling for total gzipped client JavaScript, in bytes. */
+    readonly bundleBudgetBytes: number;
+    /** A stricter suppression ceiling than the earned one, or undefined to accept the earned ceiling. */
+    readonly maxSuppressions: number | undefined;
+    /** A stricter advisory severity than the shipped one, or undefined to accept the shipped one. */
+    readonly vulnerabilitySeverity: string | undefined;
+    /** Recorded exceptions for advisories the project cannot reach. */
+    readonly vulnerabilityAllowlist: readonly VulnerabilityException[];
+    /** Committed fake credentials the secret scan excuses, each with the reason it is committed. */
+    readonly secretAllowlist: readonly SecretException[];
+    /** Anonymous permissions the project grants deliberately, each with the reason it does. */
+    readonly publicAccess: readonly PublicAccess[];
+    /**
+     * A command run once before the test and end-to-end gates, as argv. A Payload project needs a database
+     * before its suite can boot, and how it obtains one (a compose service, a managed instance, an
+     * ephemeral schema) is a fact ploaness cannot know. Declaring it does not weaken a rule: the gates and
+     * their thresholds are unchanged, only the way the project reaches its database.
+     */
+    readonly pretest: readonly string[];
+    /** An argv prefix wrapping the test runner, for a project that runs its suite against a scratch database. */
+    readonly testWrapper: readonly string[];
+    /**
+     * The origin the end-to-end suite drives. The port a project serves on is a fact ploaness cannot
+     * know, and naming it weakens no rule: the suite, its browser and its assertions are unchanged.
+     */
+    readonly serverUrl: string;
+    /**
+     * Servers the end-to-end run starts beside the application, for a project whose own specs drive one.
+     * The application under test is unchanged, and so is every rule applied to it: a declared server is
+     * added to the run rather than substituted for it, and the pinned accessibility sweep still drives
+     * {@link Settings.serverUrl}. Which auxiliary process a project's specs need is a fact ploaness
+     * cannot know, and the re-exported Playwright config leaves the project no other way to say so.
+     */
+    readonly auxiliaryServers: readonly AuxiliaryServer[];
+    /**
+     * Route prefixes the accessibility crawl must not follow, on top of the ones every Payload project
+     * carries. A project that mounts its admin panel elsewhere has to say so or the crawl walks into it.
+     */
+    readonly accessibilitySkipRoutes: readonly string[];
+    /**
+     * How many routes the accessibility sweep may discover before it stops and fails.
+     *
+     * A ceiling on the sweep's cost, not a statement about the site. It is honoured only downward: a
+     * project may hold itself to a smaller crawl, and none may buy a pass by declaring a larger one.
+     */
+    readonly accessibilityRouteBudget: number;
+    /**
+     * Placeholder environment supplied to the gates that must IMPORT the project to analyse it. A Payload
+     * config validates `process.env` at module scope, so a purely static analyser cannot load it in a bare
+     * shell. These values are never connected to and never read as real configuration; they only let the
+     * module evaluate. Declaring one weakens no rule, and a gate that actually runs the application
+     * (`build`, `tests`, `e2e`) ignores this and uses the real environment.
+     */
+    readonly analysisEnv: Readonly<Record<string, string>>;
+}
+/**
+ * The directories a project holds first-party source in unless it says otherwise.
+ *
+ * Exported because `config-references.ts` built its own alternation out of the same names, and a
+ * project that declared an extra source root got its config carve-outs left unchecked while the two
+ * lists drifted apart in silence.
+ */
+export declare const DEFAULT_SOURCE_ROOTS: readonly string[];
+/**
+ * The files the coverage report measures. Declared here rather than in the Vitest config because two
+ * things need to agree about it: the config that produces the report, and the rule that judges whether
+ * a declared exclusion reaches anything the report measured. Two literals that must stay equal will not.
+ */
+export declare const COVERAGE_INCLUDE: readonly string[];
+/**
+ * Read the `ploaness` key of a parsed package.json into a fully defaulted settings object. A malformed
+ * value falls back to the strict default rather than failing the read, so a typo can never widen a rule.
+ * @param packageJson the parsed package.json of the consuming project.
+ * @returns the effective settings, with every field populated.
+ */
+export declare const readSettings: (packageJson: unknown) => Settings;
+/** The raw `ploaness` block of a manifest, before any default is applied. */
+export declare const ploanessBlock: (packageJson: unknown) => Record<string, unknown>;
+/**
+ * Read an already-layered raw settings block into a fully defaulted settings object.
+ * @param raw the raw block, after any layering.
+ * @returns the effective settings, with every field populated.
+ */
+export declare const readRawSettings: (raw: Record<string, unknown>) => Settings;
+/**
+ * Report every declared exclusion the harness cannot honour.
+ *
+ * This once also refused an entry whose pattern named a single existing file, on the reading that one
+ * path is not a role. The governing standard now judges an exclusion by what it REACHES rather than by
+ * how specific it looks, and `findUnreachedExclusions` below is that rule. A named file the report
+ * measured excludes something; the defect the standard names is an entry that excludes nothing.
+ * @param entries the exclusions the project declared.
+ * @returns one message per entry that states no role.
+ */
+export declare const findConvenienceExclusions: (entries: readonly DeclaredExclusion[]) => readonly string[];
+/**
+ * Report every declared exclusion that matches none of the paths it could have excluded.
+ *
+ * An exclusion that reaches nothing leaves the report reading exactly as it would have read without it,
+ * so it records a decision nobody can see the effect of - and it outlives the file it was written for,
+ * which is how a stale carve-out survives the rename that made it meaningless. A route exclusion is
+ * skipped: it names a URL the crawl must not follow, and no path in the repository can confirm it.
+ * @param entries the exclusions the project declared.
+ * @param candidates the repo-relative paths the corresponding gate would otherwise have judged.
+ * @returns one message per entry that reaches nothing.
+ */
+export declare const findUnreachedExclusions: (entries: readonly DeclaredExclusion[], candidates: readonly string[]) => readonly string[];
+/**
+ * A directory path without its trailing slashes.
+ *
+ * Written as a recursion rather than as `/\/+$/`, which backtracks super-linearly on a pathological
+ * input - a rule this repository holds itself to.
+ * @param value the declared path.
+ * @returns the same path with every trailing slash removed.
+ */
+export declare const withoutTrailingSlash: (value: string) => string;
+/**
+ * Every directory that holds a tracked file, at every depth.
+ *
+ * Derived from the file list rather than read from disk, so the answer covers exactly what is committed:
+ * a directory that exists only in a working tree is not part of the repository a gate judges.
+ * @param tracked the repo-relative paths of the tracked files.
+ * @returns each containing directory once, without a trailing slash.
+ */
+export declare const trackedDirectories: (tracked: readonly string[]) => readonly string[];
+/**
+ * Report every declared exclusion that reaches none of the paths ITS OWN setting could have excluded.
+ *
+ * A composition over `findUnreachedExclusions`: it groups the entries by setting and hands each group
+ * the candidate set that setting governs, so a caller supplies the tracked file list and nothing else.
+ * @param entries the exclusions the project declared, across every setting.
+ * @param tracked the repo-relative paths of the tracked files.
+ * @returns one message per entry that reaches nothing.
+ */
+export declare const findUnreachedExclusionsBySetting: (entries: readonly DeclaredExclusion[], tracked: readonly string[]) => readonly string[];
+//# sourceMappingURL=settings.d.ts.map

package/dist/settings.d.ts.map

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