@ploaness/cli 1.0.0

package/dist/commands/verify.d.ts

@@ -0,0 +1,18 @@
+import type { Repository as Repo } from '../context.js';
+import { type PlannedGate } from '../gates.js';
+/**
+ * Run Default or Extended verification.
+ * @param repository the resolved repository environment.
+ * @param isExtended whether to include the history, build, bundle, and end-to-end gates.
+ * @returns the process exit code.
+ */
+export declare const verify: (repository: Repo, isExtended: boolean) => Promise<number>;
+/**
+ * Run one gate by identifier. A single gate is a debugging aid, never a verdict.
+ * @param repository the resolved repository environment.
+ * @param planned the gate to run, with the member it is about.
+ * @param isVerbose whether to print what the gate's tool wrote, not only the verdict it produced.
+ * @returns the process exit code.
+ */
+export declare const verifyOne: (repository: Repo, planned: PlannedGate, isVerbose?: boolean) => Promise<number>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/commands/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/commands/verify.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAU,UAAU,IAAI,IAAI,EAAE,MAAM,eAAe,CAAA;AAE/D,OAAO,EAAE,KAAK,WAAW,EAAW,MAAM,aAAa,CAAA;AAsFvD;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAU,YAAY,IAAI,EAAE,YAAY,OAAO,KAAG,OAAO,CAAC,MAAM,CAOlF,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GACpB,YAAY,IAAI,EAChB,SAAS,WAAW,EACpB,YAAW,OAAe,KACzB,OAAO,CAAC,MAAM,CAQhB,CAAA"}

package/dist/commands/verify.js

@@ -0,0 +1,96 @@
+// Verification: run the gates in order and report one verdict. A gate that throws is a failed gate, not
+// a crashed run, because a tool that cannot start is indistinguishable from a tool that found a defect:
+// either way the project is not verified.
+import { endsRun } from '@ploaness/governance';
+import { failed } from '../exec.js';
+import { planFor } from '../gates.js';
+import { beginGate, reportGate, reportHalt, reportHeader, reportNote, reportOutput, reportVerdict, } from '../report.js';
+const asMessage = (error) => error instanceof Error ? error.message : String(error);
+// The union is narrowed exactly here, once. Everywhere else a gate is a gate; this is the one place
+// that has to know a repository-scope gate is handed the repository and a member-scope gate its member.
+const invoke = async (planned, repo) => {
+    if (planned.gate.scope === 'repository') {
+        return await planned.gate.run(repo);
+    }
+    const member = planned.member;
+    if (member === undefined) {
+        return failed(`the ${planned.gate.id} gate was planned without a member`, [
+            'this is a ploaness defect; the run plan and the registry disagree about this gate',
+        ]);
+    }
+    return await planned.gate.run(member);
+};
+const runGate = async (planned, repo) => {
+    try {
+        return await invoke(planned, repo);
+    }
+    catch (error) {
+        return failed(`the ${planned.gate.id} gate could not run`, [asMessage(error)]);
+    }
+};
+/** Time one gate and package it as the outcome the report layer prints. */
+const timeGate = async (planned, repo) => {
+    const started = Date.now();
+    const result = await runGate(planned, repo);
+    return {
+        gate: planned.gate,
+        result,
+        durationMs: Date.now() - started,
+        member: planned.member?.path,
+    };
+};
+// The identifier column is sized to the widest gate in this run rather than to a fixed constant, so
+// adding a longer gate identifier cannot silently push the summaries out of alignment.
+const identifierWidth = (planned) => planned.reduce((widest, step) => Math.max(widest, step.gate.id.length), 0);
+// A sequence with an exit rather than a plain map, because a run does not always reach the end. The
+// rule that decides is `endsRun`, in governance; this supplies the outcome and the mode.
+const runPlan = async (planned, repo, width) => {
+    const [step, ...rest] = planned;
+    if (step === undefined) {
+        return [];
+    }
+    beginGate(step.gate, width);
+    const outcome = await timeGate(step, repo);
+    reportGate(outcome, width);
+    const isPrecondition = step.gate.isPrecondition === true;
+    if (endsRun({
+        isFailure: !outcome.result.ok,
+        isPrecondition,
+        isEnforced: repo.isEnforced,
+    })) {
+        reportHalt(step.gate, rest.length, isPrecondition);
+        return [outcome];
+    }
+    return [outcome, ...(await runPlan(rest, repo, width))];
+};
+/**
+ * Run Default or Extended verification.
+ * @param repository the resolved repository environment.
+ * @param isExtended whether to include the history, build, bundle, and end-to-end gates.
+ * @returns the process exit code.
+ */
+export const verify = async (repository, isExtended) => {
+    const started = Date.now();
+    const planned = planFor(repository, isExtended);
+    const width = identifierWidth(planned);
+    reportHeader(isExtended, planned.length);
+    const outcomes = await runPlan(planned, repository, width);
+    return reportVerdict(outcomes, isExtended, repository.isEnforced, Date.now() - started);
+};
+/**
+ * Run one gate by identifier. A single gate is a debugging aid, never a verdict.
+ * @param repository the resolved repository environment.
+ * @param planned the gate to run, with the member it is about.
+ * @param isVerbose whether to print what the gate's tool wrote, not only the verdict it produced.
+ * @returns the process exit code.
+ */
+export const verifyOne = async (repository, planned, isVerbose = false) => {
+    const outcome = await timeGate(planned, repository);
+    reportGate(outcome, planned.gate.id.length);
+    if (isVerbose) {
+        reportOutput(outcome);
+    }
+    reportNote('A single gate is a debugging aid. Run `ploaness verify` for a verdict.');
+    return outcome.result.ok || !repository.isEnforced ? 0 : 1;
+};
+//# sourceMappingURL=verify.js.map

package/dist/commands/verify.js.map

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

package/dist/context.d.ts

@@ -0,0 +1,157 @@
+import { type ProjectManifest, type Settings } from '@ploaness/governance';
+/** The resolved environment of one ploaness run. */
+export interface Context {
+    /** The consuming project's repository root. */
+    readonly root: string;
+    /** The project's parsed package.json, or undefined when it has none. */
+    readonly packageJson: unknown;
+    /** The effective settings the project declared. */
+    readonly settings: Settings;
+    /** False in report-only mode, where findings print but the run still exits 0. */
+    readonly isEnforced: boolean;
+}
+/**
+ * One governed package.
+ *
+ * `root` is the member's own directory, which is why every check that joins a path onto it kept working
+ * unchanged when members arrived: for a single-package repository the member root IS the repository
+ * root, so the field means exactly what it always meant.
+ */
+export interface Member extends Context {
+    /** Repo-relative, `.` for the member at the repository root. */
+    readonly path: string;
+    /** Whether this member declares Payload, which decides if the Payload-scope gates ask about it. */
+    readonly isPayload: boolean;
+    /**
+     * The other members' paths, relative to THIS member's directory.
+     *
+     * An analyzer that walks everything below where it runs has to be told where this package stops. At
+     * a workspace root every sibling sits underneath, and without this each sibling's entry point is
+     * reported as an unused file by a run that was never analysing it.
+     */
+    readonly siblingPaths: readonly string[];
+}
+/**
+ * The repository a run judges, and every member inside it.
+ *
+ * The distinction this type exists to make is the one ploaness did not have: an install-script
+ * allowlist, an overrides block and a managed dotfile are facts about the REPOSITORY, and reading them
+ * from a member's directory produced a verdict about a file that was never there.
+ */
+export interface Repository extends Context {
+    /** The workspace file at the repository root - the only place pnpm honours these keys. */
+    readonly workspaceFile: string;
+    readonly members: readonly Member[];
+    /** Every pnpm project the workspace selects, governed or not, for the anti-bypass rule. */
+    readonly projects: readonly ProjectManifest[];
+}
+/**
+ * Read a JSON file, returning undefined when it is absent or unparseable.
+ *
+ * Comments and trailing commas are tolerated, because the files this reads - a tsconfig, a Biome
+ * config, a runtime settings file - legally carry them, and a reader that refused them would report the
+ * project as malformed for writing what its own tools accept.
+ * @param file the absolute path.
+ * @returns the parsed value, or undefined.
+ */
+export declare const readJson: (file: string) => unknown;
+/** Read a text file, returning undefined when it is absent. */
+export declare const readText: (file: string) => string | undefined;
+/** Build the run context for a project root. */
+export declare const createContext: (root: string, isEnforced: boolean) => Context;
+/**
+ * Resolve an executable script from a package, independent of hoisting. pnpm keeps a package's own
+ * dependencies out of the consumer's `.bin`, so a bare tool name is not reliably on PATH; reading the
+ * tool's manifest finds its entry point wherever the store put it.
+ * @param packageName the npm package providing the tool.
+ * @param binName the bin entry to resolve, defaulting to the package name.
+ * @param resolveFrom the require used to locate the package; defaults to the ploaness install.
+ * @returns the absolute path to the tool's JavaScript entry point.
+ */
+export declare const resolveTool: (packageName: string, binName?: string, resolveFrom?: NodeJS.Require) => string;
+/**
+ * Whether this member has a server of its own, and so a build, a client bundle and a browser to drive.
+ *
+ * Asked of the MANIFEST rather than of the install. `next` resolves from a workspace root that declares
+ * nothing at all, because pnpm keeps a compatibility hoist at `node_modules/.pnpm/node_modules` that
+ * node's resolution walks into - so "is the tool reachable" answers yes for every member of a repository
+ * where any one member is an application. That is what sent `next build` at a root holding no `app`
+ * directory, and the failure named the missing directory rather than the member that should never have
+ * been built.
+ * @param context the member to judge.
+ * @returns true for a Payload or Next application, false for a library.
+ */
+export declare const hasOwnRuntime: (context: Context) => boolean;
+/**
+ * Resolve a tool from the CONSUMER's install rather than the harness's. Vitest, Playwright, Next, and
+ * the Payload CLI must be the project's own instance: the project's specs and config import those
+ * packages directly, and a second copy would load a different module registry.
+ */
+export declare const resolveProjectTool: (context: Context, packageName: string, binName?: string) => string;
+/**
+ * Locate a package's manifest as the package at `fromManifest` resolves it.
+ *
+ * Resolution root matters here rather than being an implementation detail: under pnpm's strict layout
+ * `@ploaness/config` is reachable from `ploaness` and from nowhere else, so walking the manifests a
+ * project inherits has to re-root at each step. Undefined rather than a throw, because a package that
+ * does not resolve is a fact the caller reports rather than a broken run.
+ * @param packageName the package to locate.
+ * @param fromManifest the manifest whose resolution rules apply.
+ * @returns the absolute path to the package's own manifest, or undefined.
+ */
+export declare const manifestPathFrom: (packageName: string, fromManifest: string) => string | undefined;
+/** Locate a directory inside a package ploaness depends on, for shipped configs and assets. */
+export declare const shippedDirectory: (packageName: string) => string;
+/** Locate this module's own package directory, used to report the running harness version. */
+export declare const cliDirectory: () => string;
+/** List the repository's tracked files, NUL-delimited so paths with spaces survive intact. */
+export declare const trackedFiles: (root: string) => readonly string[];
+/** Run a git command in the project and return its trimmed stdout. */
+export declare const git: (context: Context, commandArguments: readonly string[]) => string;
+/**
+ * The pinned versions ploaness owns, read from the shipped `pins.json`.
+ *
+ * One reader rather than one per gate: `preflight` decided the Node floor from a constant of its own,
+ * which is a rule living in the I/O layer AND a second copy of what this file already states.
+ * @returns the parsed pins, or an empty record when the file cannot be read.
+ */
+export declare const readPins: () => Record<string, unknown>;
+/**
+ * Build the run context for a repository, discovering its governed members.
+ * @param cwd the directory ploaness was invoked from, which need not be the repository root.
+ * @param isEnforced false in report-only mode.
+ * @returns the repository, with one member for a single-package project.
+ */
+export declare const createRepository: (cwd: string, isEnforced: boolean) => Repository;
+/**
+ * The member a single-gate invocation is about.
+ *
+ * `ploaness gate <id>` names no member, so it acts on the package containing the working directory. It
+ * resolves against every pnpm project rather than only the governed members, because a single gate is
+ * the tool an UNGOVERNED repository is surveyed with: before `ploaness` is declared anywhere there are
+ * no governed members but the root, and resolving to the root would silently measure the wrong package
+ * - reporting the repository's suppression ceiling to someone standing in an application asking about
+ * that application. A whole `verify` run still judges only what the repository actually governs.
+ * @param repository the repository being judged.
+ * @param cwd the directory ploaness was invoked from.
+ * @returns the member for the innermost project containing cwd, or the first governed member.
+ */
+export declare const memberAt: (repository: Repository, cwd: string) => Member | undefined;
+/**
+ * The environment variables a gate must hand a child process that BOOTS the project.
+ *
+ * A Payload configuration validates `process.env` at module scope, so a tool that evaluates it needs
+ * the project's own environment before it can run at all - and the Payload CLI, unlike Next, reads no
+ * `.env` itself. The other three gates that boot the project were each covered by something that does:
+ * `next build` reads them, and the runners ploaness ships load them from `vitest-setup.ts` and
+ * `playwright.ts`. The generator was the one path with nothing on it, so it evaluated the
+ * configuration with those variables absent and produced the artefacts of a project that does not
+ * exist.
+ *
+ * Parsing is `node:util`'s, which is the parser `process.loadEnvFile` uses, so a file read here and the
+ * same file read by the runners cannot be read two different ways.
+ * @param context the member whose environment files are read.
+ * @returns the variables to add, already narrowed to those the run does not carry.
+ */
+export declare const runEnvironment: (context: Context) => Readonly<Record<string, string>>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAOA,OAAO,EAUL,KAAK,eAAe,EAWpB,KAAK,QAAQ,EAEd,MAAM,sBAAsB,CAAA;AAS7B,oDAAoD;AACpD,MAAM,WAAW,OAAO;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,MAAO,SAAQ,OAAO;IACrC,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mGAAmG;IACnG,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CACzC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAW,SAAQ,OAAO;IACzC,0FAA0F;IAC1F,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;CAC9C;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,KAAG,OACqC,CAAA;AAE7E,+DAA+D;AAC/D,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,SACU,CAAA;AAE3D,gDAAgD;AAChD,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,EAAE,YAAY,OAAO,KAAG,OAGjE,CAAA;AA0CD;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GACtB,aAAa,MAAM,EACnB,UAAU,MAAM,EAChB,cAAa,MAAM,CAAC,OAAqB,KACxC,MAoBF,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,OAAO,KAAG,OACF,CAAA;AAE/C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,OAAO,EAChB,aAAa,MAAM,EACnB,UAAU,MAAM,KACf,MACwF,CAAA;AAE3F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,aAAa,MAAM,EAAE,cAAc,MAAM,KAAG,MAAM,GAAG,SAMrF,CAAA;AAED,+FAA+F;AAC/F,eAAO,MAAM,gBAAgB,GAAI,aAAa,MAAM,KAAG,MACX,CAAA;AAE5C,8FAA8F;AAC9F,eAAO,MAAM,YAAY,QAAO,MACkC,CAAA;AAElE,8FAA8F;AAC9F,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,SAAS,MAAM,EASR,CAAA;AAEnD,sEAAsE;AACtE,eAAO,MAAM,GAAG,GAAI,SAAS,OAAO,EAAE,kBAAkB,SAAS,MAAM,EAAE,KAAG,MAQjE,CAAA;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,QAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAGjD,CAAA;AAsHD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,EAAE,YAAY,OAAO,KAAG,UAiCnE,CAAA;AAuBD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ,GAAI,YAAY,UAAU,EAAE,KAAK,MAAM,KAAG,MAAM,GAAG,SAyBvE,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,OAAO,KAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS9E,CAAA"}

package/dist/context.js

@@ -0,0 +1,345 @@
+// Everything a gate needs to know about the project it is judging, resolved once per run.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseEnv } from 'node:util';
+import { asRecord, asStringRecord, findGovernedMembers, findRepositoryRoot, hasRuntime, isPayloadProject, memberKindOf, parseJsonc, ploanessBlock, ROOT_MEMBER_PATH, readKey, readMemberSettings, readSettings, readWorkspacePackages, rebaseExclusion, runEnvironmentFiles, runEnvironmentOverrides, selectProjects, } from '@ploaness/governance';
+const nodeRequire = createRequire(import.meta.url);
+const BYTES_PER_KIB = 1024;
+const KIB_PER_MIB = 1024;
+// Large enough that no analyzer's output is truncated before it can be reported.
+const MAX_OUTPUT_MIB = 64;
+const MAX_OUTPUT_BYTES = MAX_OUTPUT_MIB * KIB_PER_MIB * BYTES_PER_KIB;
+/**
+ * Read a JSON file, returning undefined when it is absent or unparseable.
+ *
+ * Comments and trailing commas are tolerated, because the files this reads - a tsconfig, a Biome
+ * config, a runtime settings file - legally carry them, and a reader that refused them would report the
+ * project as malformed for writing what its own tools accept.
+ * @param file the absolute path.
+ * @returns the parsed value, or undefined.
+ */
+export const readJson = (file) => existsSync(file) ? parseJsonc(readFileSync(file, 'utf8')).value : undefined;
+/** Read a text file, returning undefined when it is absent. */
+export const readText = (file) => existsSync(file) ? readFileSync(file, 'utf8') : undefined;
+/** Build the run context for a project root. */
+export const createContext = (root, isEnforced) => {
+    const packageJson = readJson(path.join(root, 'package.json'));
+    return { root, packageJson, settings: readSettings(packageJson), isEnforced };
+};
+// Locating a tool is harder than it looks. A package may restrict its `exports` so `pkg/package.json` is
+// not addressable (dependency-cruiser), and it may publish an `import` condition only, so CJS resolution
+// of its entry point fails too. Three routes are tried in turn, and the last one is the one that always
+// works: find the entry point through ESM resolution and walk up to the manifest beside it.
+const manifestFrom = (directory) => {
+    const candidate = path.join(directory, 'package.json');
+    if (existsSync(candidate)) {
+        return candidate;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+        throw new Error(`no package.json found above ${directory}`);
+    }
+    return manifestFrom(parent);
+};
+const manifestBeside = (entry) => manifestFrom(path.dirname(entry));
+const manifestOf = (packageName, resolveFrom) => {
+    try {
+        return resolveFrom.resolve(`${packageName}/package.json`);
+    }
+    catch {
+        // fall through
+    }
+    try {
+        return manifestBeside(resolveFrom.resolve(packageName));
+    }
+    catch {
+        // fall through
+    }
+    try {
+        return manifestBeside(fileURLToPath(import.meta.resolve(packageName)));
+    }
+    catch (error) {
+        throw new Error(`ploaness could not locate the manifest of ${packageName}`, { cause: error });
+    }
+};
+/** Resolve a path inside a package, from a chosen resolution root. */
+const packageDirectory = (packageName, resolveFrom) => path.dirname(manifestOf(packageName, resolveFrom));
+/**
+ * Resolve an executable script from a package, independent of hoisting. pnpm keeps a package's own
+ * dependencies out of the consumer's `.bin`, so a bare tool name is not reliably on PATH; reading the
+ * tool's manifest finds its entry point wherever the store put it.
+ * @param packageName the npm package providing the tool.
+ * @param binName the bin entry to resolve, defaulting to the package name.
+ * @param resolveFrom the require used to locate the package; defaults to the ploaness install.
+ * @returns the absolute path to the tool's JavaScript entry point.
+ */
+export const resolveTool = (packageName, binName, resolveFrom = nodeRequire) => {
+    const manifestPath = manifestOf(packageName, resolveFrom);
+    // A tool's own manifest, so an unreadable one is the installation being broken rather than the
+    // project being wrong. `format` resolves a tool outside any gate, where a raw SyntaxError would reach
+    // the user as a stack trace with no mention of which package it came from.
+    const read = parseJsonc(readFileSync(manifestPath, 'utf8'));
+    if (read.problem !== undefined) {
+        throw new Error(`ploaness could not read ${manifestPath}: ${read.problem}`);
+    }
+    // Narrowed through the governance guards rather than asserted. `bin` is either a path or a map of
+    // names to paths, and both cases are read here as what they are: an assertion would be a claim the
+    // compiler cannot check, and `type-coverage --strict` counts every one as untyped.
+    const declaredBin = readKey(read.value, 'bin');
+    const wanted = binName ?? packageName;
+    const bin = typeof declaredBin === 'string' ? declaredBin : asStringRecord(declaredBin)[wanted];
+    if (bin === undefined) {
+        throw new Error(`ploaness could not resolve the "${wanted}" executable from ${packageName}`);
+    }
+    return path.join(path.dirname(manifestPath), bin);
+};
+/**
+ * Whether this member has a server of its own, and so a build, a client bundle and a browser to drive.
+ *
+ * Asked of the MANIFEST rather than of the install. `next` resolves from a workspace root that declares
+ * nothing at all, because pnpm keeps a compatibility hoist at `node_modules/.pnpm/node_modules` that
+ * node's resolution walks into - so "is the tool reachable" answers yes for every member of a repository
+ * where any one member is an application. That is what sent `next build` at a root holding no `app`
+ * directory, and the failure named the missing directory rather than the member that should never have
+ * been built.
+ * @param context the member to judge.
+ * @returns true for a Payload or Next application, false for a library.
+ */
+export const hasOwnRuntime = (context) => hasRuntime(memberKindOf(context.packageJson));
+/**
+ * Resolve a tool from the CONSUMER's install rather than the harness's. Vitest, Playwright, Next, and
+ * the Payload CLI must be the project's own instance: the project's specs and config import those
+ * packages directly, and a second copy would load a different module registry.
+ */
+export const resolveProjectTool = (context, packageName, binName) => resolveTool(packageName, binName, createRequire(path.join(context.root, 'package.json')));
+/**
+ * Locate a package's manifest as the package at `fromManifest` resolves it.
+ *
+ * Resolution root matters here rather than being an implementation detail: under pnpm's strict layout
+ * `@ploaness/config` is reachable from `ploaness` and from nowhere else, so walking the manifests a
+ * project inherits has to re-root at each step. Undefined rather than a throw, because a package that
+ * does not resolve is a fact the caller reports rather than a broken run.
+ * @param packageName the package to locate.
+ * @param fromManifest the manifest whose resolution rules apply.
+ * @returns the absolute path to the package's own manifest, or undefined.
+ */
+export const manifestPathFrom = (packageName, fromManifest) => {
+    try {
+        return manifestOf(packageName, createRequire(fromManifest));
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Locate a directory inside a package ploaness depends on, for shipped configs and assets. */
+export const shippedDirectory = (packageName) => packageDirectory(packageName, nodeRequire);
+/** Locate this module's own package directory, used to report the running harness version. */
+export const cliDirectory = () => path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+/** List the repository's tracked files, NUL-delimited so paths with spaces survive intact. */
+export const trackedFiles = (root) => execFileSync('git', ['ls-files', '-z'], {
+    cwd: root,
+    encoding: 'utf8',
+    maxBuffer: MAX_OUTPUT_BYTES,
+    // A directory that is not a repository is a case the caller handles, not a diagnosis to print.
+    stdio: ['ignore', 'pipe', 'ignore'],
+})
+    .split('\0')
+    .filter((file) => file !== '');
+/** Run a git command in the project and return its trimmed stdout. */
+export const git = (context, commandArguments) => execFileSync('git', [...commandArguments], {
+    cwd: context.root,
+    encoding: 'utf8',
+    // git writes its own diagnosis to stderr, which for a directory that is not a repository is not a
+    // finding but noise around one the caller reports itself.
+    stdio: ['ignore', 'pipe', 'ignore'],
+    maxBuffer: MAX_OUTPUT_BYTES,
+}).trim();
+/**
+ * The pinned versions ploaness owns, read from the shipped `pins.json`.
+ *
+ * One reader rather than one per gate: `preflight` decided the Node floor from a constant of its own,
+ * which is a rule living in the I/O layer AND a second copy of what this file already states.
+ * @returns the parsed pins, or an empty record when the file cannot be read.
+ */
+export const readPins = () => {
+    const pinsFile = path.join(shippedDirectory('@ploaness/config'), 'pins.json');
+    return asRecord(readJson(pinsFile));
+};
+const MANIFEST = 'package.json';
+const WORKSPACE_FILE = 'pnpm-workspace.yaml';
+// Every directory from the working directory up to the filesystem root, nearest first, which is the
+// order `findRepositoryRoot` searches.
+const ancestorsOf = (directory) => {
+    const parent = path.dirname(directory);
+    return parent === directory ? [directory] : [directory, ...ancestorsOf(parent)];
+};
+const hasEntry = (directory, entry) => existsSync(path.join(directory, entry));
+// Candidate project directories come from the tracked tree rather than from a filesystem walk, so a
+// directory git does not know about - a build output, an ignored scratch copy, an uninstalled example -
+// can never become a governed member.
+// Candidate project directories come from the tracked tree rather than a filesystem walk, so a
+// directory git does not know about - a build output, an ignored scratch copy - can never become a
+// governed member. A directory that is not a repository at all has exactly one project, itself: the
+// integration fixtures install into such a directory before any commit exists, and asking git there
+// fails rather than answering.
+const manifestDirectories = (root) => {
+    try {
+        return trackedManifestDirectories(root);
+    }
+    catch {
+        // Not a repository yet. `ploaness init` is run on exactly such a tree - a fresh checkout, or a
+        // workspace being adopted before its first commit - and answering "one project, the root" there
+        // would scaffold the root and silently leave every other package unwired.
+        return walkManifestDirectories(root);
+    }
+};
+// Bounded and exclusionary on purpose. A full walk of a workspace would descend into every dependency's
+// own dependencies; nothing ploaness governs is nested deeper than a couple of directories, and neither
+// an installed package nor a tool's cache is a project this repository owns.
+const WALK_DEPTH = 3;
+const isSkipped = (name) => name.startsWith('.') || name === 'node_modules';
+const walkManifestDirectories = (root, relative = ROOT_MEMBER_PATH, depth = 0) => {
+    const absolute = relative === ROOT_MEMBER_PATH ? root : path.join(root, relative);
+    const here = existsSync(path.join(absolute, MANIFEST)) ? [relative] : [];
+    if (depth >= WALK_DEPTH) {
+        return here;
+    }
+    const children = readdirSync(absolute, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !isSkipped(entry.name))
+        .flatMap((entry) => walkManifestDirectories(root, relative === ROOT_MEMBER_PATH ? entry.name : path.join(relative, entry.name), depth + 1));
+    return [...here, ...children];
+};
+const trackedManifestDirectories = (root) => trackedFiles(root)
+    .filter((file) => path.basename(file) === MANIFEST)
+    .map((file) => {
+    const directory = path.dirname(file);
+    return directory === '' ? ROOT_MEMBER_PATH : directory;
+});
+const readManifest = (root, projectPath) => readJson(path.join(root, projectPath, MANIFEST));
+// A member's settings sit on top of the repository's rather than replacing them, so a fact declared
+// once at the root - a generated directory the typography ban must skip, a stricter bundle budget -
+// reaches every package without being restated in each.
+// The members that sit INSIDE this one, named relative to it. A member elsewhere in the tree is not
+// below the directory an analyzer walks, so naming it would ignore a path that never appears; and one
+// that is below must be named the way the walk will see it, from here rather than from the root.
+const nestedWithin = (memberPath, every) => {
+    if (memberPath === ROOT_MEMBER_PATH) {
+        return every.filter((other) => other !== ROOT_MEMBER_PATH);
+    }
+    const prefix = `${memberPath}/`;
+    return every
+        .filter((other) => other.startsWith(prefix))
+        .map((other) => other.slice(prefix.length));
+};
+const createMember = ({ root, projectPath, isEnforced, repositoryBlock = {}, siblings = [], }) => {
+    const packageJson = readManifest(root, projectPath);
+    return {
+        root: projectPath === ROOT_MEMBER_PATH ? root : path.join(root, projectPath),
+        packageJson,
+        settings: readMemberSettings(repositoryBlock, ploanessBlock(packageJson)),
+        isEnforced,
+        path: projectPath,
+        isPayload: isPayloadProject(packageJson),
+        siblingPaths: siblings,
+    };
+};
+/**
+ * Build the run context for a repository, discovering its governed members.
+ * @param cwd the directory ploaness was invoked from, which need not be the repository root.
+ * @param isEnforced false in report-only mode.
+ * @returns the repository, with one member for a single-package project.
+ */
+export const createRepository = (cwd, isEnforced) => {
+    const root = findRepositoryRoot(ancestorsOf(path.resolve(cwd)), hasEntry);
+    const workspaceFile = readText(path.join(root, WORKSPACE_FILE)) ?? '';
+    const projects = selectProjects(readWorkspacePackages(workspaceFile), manifestDirectories(root)).map((projectPath) => ({
+        path: projectPath,
+        packageJson: readManifest(root, projectPath),
+    }));
+    const packageJson = readManifest(root, ROOT_MEMBER_PATH);
+    const memberPaths = findGovernedMembers(projects);
+    const members = memberPaths.map((projectPath) => createMember({
+        root,
+        projectPath,
+        isEnforced,
+        repositoryBlock: ploanessBlock(packageJson),
+        siblings: nestedWithin(projectPath, memberPaths),
+    }));
+    return {
+        root,
+        packageJson,
+        settings: withMemberExclusions(readSettings(packageJson), members),
+        isEnforced,
+        workspaceFile,
+        projects,
+        members,
+    };
+};
+// The gates that walk the tracked tree run once, at the root, while a member declares its exclusions
+// relative to itself. Without this a generated directory a member correctly excused starts failing
+// them, because the pattern it wrote is anchored one directory above where the gate is looking.
+const withMemberExclusions = (base, members) => {
+    const rebased = members.flatMap((member) => member.settings.declaredExclusions.map((entry) => rebaseExclusion(member.path, entry)));
+    const patternsFor = (setting) => rebased
+        .filter((entry) => entry.setting === setting)
+        .map((entry) => entry.pattern);
+    return {
+        ...base,
+        typographyExclusions: [...base.typographyExclusions, ...patternsFor('typographyExclusions')],
+        javascriptAllowlist: [...base.javascriptAllowlist, ...patternsFor('javascriptAllowlist')],
+    };
+};
+/**
+ * The member a single-gate invocation is about.
+ *
+ * `ploaness gate <id>` names no member, so it acts on the package containing the working directory. It
+ * resolves against every pnpm project rather than only the governed members, because a single gate is
+ * the tool an UNGOVERNED repository is surveyed with: before `ploaness` is declared anywhere there are
+ * no governed members but the root, and resolving to the root would silently measure the wrong package
+ * - reporting the repository's suppression ceiling to someone standing in an application asking about
+ * that application. A whole `verify` run still judges only what the repository actually governs.
+ * @param repository the repository being judged.
+ * @param cwd the directory ploaness was invoked from.
+ * @returns the member for the innermost project containing cwd, or the first governed member.
+ */
+export const memberAt = (repository, cwd) => {
+    const resolved = path.resolve(cwd);
+    const containsCwd = (projectPath) => {
+        const full = projectPath === ROOT_MEMBER_PATH ? repository.root : path.join(repository.root, projectPath);
+        return resolved === full || resolved.startsWith(`${full}${path.sep}`);
+    };
+    // The deepest match, so a nested project wins over the root that also contains it.
+    const innermost = [...repository.projects]
+        .filter((project) => containsCwd(project.path))
+        .sort((left, right) => right.path.length - left.path.length)[0];
+    if (innermost === undefined) {
+        return repository.members[0];
+    }
+    return (repository.members.find((member) => member.path === innermost.path) ??
+        createMember({
+            root: repository.root,
+            projectPath: innermost.path,
+            isEnforced: repository.isEnforced,
+        }));
+};
+/**
+ * The environment variables a gate must hand a child process that BOOTS the project.
+ *
+ * A Payload configuration validates `process.env` at module scope, so a tool that evaluates it needs
+ * the project's own environment before it can run at all - and the Payload CLI, unlike Next, reads no
+ * `.env` itself. The other three gates that boot the project were each covered by something that does:
+ * `next build` reads them, and the runners ploaness ships load them from `vitest-setup.ts` and
+ * `playwright.ts`. The generator was the one path with nothing on it, so it evaluated the
+ * configuration with those variables absent and produced the artefacts of a project that does not
+ * exist.
+ *
+ * Parsing is `node:util`'s, which is the parser `process.loadEnvFile` uses, so a file read here and the
+ * same file read by the runners cannot be read two different ways.
+ * @param context the member whose environment files are read.
+ * @returns the variables to add, already narrowed to those the run does not carry.
+ */
+export const runEnvironment = (context) => runEnvironmentOverrides(process.env, runEnvironmentFiles((relativePath) => existsSync(path.join(context.root, relativePath))).map((file) => parseEnv(readFileSync(path.join(context.root, file), 'utf8'))));
+//# sourceMappingURL=context.js.map