@ploaness/cli 1.0.0

package/dist/checks/containers.js

@@ -0,0 +1,194 @@
+// The gates that run their tool inside Docker. A Payload project already needs Docker for its database,
+// so this costs nothing extra and makes the gates behave identically on every machine: no local install
+// of gitleaks, hadolint, or actionlint, and no version skew between developers and CI.
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { CONTAINER_IMAGES, classifyContainerExit, classifyImageFailure, composeProjectsIn, dockerfilesIn, renderGitleaksConfig, } from '@ploaness/governance';
+import { trackedFiles } from '../context.js';
+import { asFindings, failed, fromRun, passed, run, } from '../exec.js';
+// Pinned by digest in the governance layer, where a spec rejects a mutable reference. These were three
+// `:latest` literals, which let an upstream release change a verdict without the repository changing.
+const GITLEAKS_IMAGE = CONTAINER_IMAGES.gitleaks;
+const HADOLINT_IMAGE = CONTAINER_IMAGES.hadolint;
+const ACTIONLINT_IMAGE = CONTAINER_IMAGES.actionlint;
+const describeFailure = (failure) => failed(failure.summary, failure.remedies);
+// The image is acquired as a step of its own, BEFORE any analyzer runs, and that ordering is the repair
+// rather than an optimisation. It puts "the analyzer could not be obtained" on a command whose output
+// docker wrote in full, so the failure can be read honestly; leaving the pull implicit in `docker run`
+// left one exit code carrying two questions, and a rate-limited pull answered the wrong one - the secret
+// scan reported a secret in the git history because gitleaks had never started.
+//
+// `docker image inspect` is local and costs nothing on a machine that has already pulled, which is every
+// machine after the first run.
+const acquireImage = (context, image, gate) => {
+    const present = run('docker', ['image', 'inspect', '--format', '{{.Id}}', image], {
+        cwd: context.root,
+    });
+    if (present.code === 0) {
+        return undefined;
+    }
+    const pulled = run('docker', ['pull', image], { cwd: context.root });
+    const failure = classifyImageFailure(gate, pulled);
+    return failure === undefined ? undefined : describeFailure(failure);
+};
+// Asked only when a run failed, and answered by docker rather than by the analyzer's output. The reserved
+// exit codes settle it outright; otherwise the question is whether docker is STILL well, which closes the
+// narrow window where the daemon dies between the pull and the run without letting a commit message the
+// scanner quoted decide whether a finding is real.
+const dockerFault = (context, image, gate, result) => {
+    if (result.code === 0) {
+        return undefined;
+    }
+    const reserved = classifyContainerExit(gate, result);
+    return reserved === undefined ? acquireImage(context, image, gate) : describeFailure(reserved);
+};
+// The scanner's configuration is rendered outside the working tree and mounted read-only. A copy in the
+// tree is a forbidden path, because it could shadow or weaken the tool's own rules; rendering it here
+// means the project supplies data - which fixture credential, and why - while ploaness keeps the rules.
+//
+// Rendered under the home directory rather than the system temporary directory: a macOS Docker daemon
+// shares the home directory and need not share /tmp, and an unshared source mounts as an empty
+// directory rather than as an error. `it/verify.sh` records the same constraint for the same reason.
+const withRenderedConfig = (context, use) => {
+    const directory = mkdtempSync(path.join(homedir(), '.ploaness-secrets-'));
+    try {
+        writeFileSync(path.join(directory, 'gitleaks.toml'), renderGitleaksConfig(context.settings.secretAllowlist));
+        return use(directory);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+};
+const scanSecrets = (context, configDirectory, target) => run('docker', [
+    'run',
+    '--rm',
+    '-v',
+    `${context.root}:/repo`,
+    '-v',
+    `${configDirectory}:/ploaness:ro`,
+    GITLEAKS_IMAGE,
+    target,
+    '/repo',
+    '--config',
+    '/ploaness/gitleaks.toml',
+    '--no-banner',
+    '--redact',
+], { cwd: context.root });
+/** Scan the commit history for committed secrets. */
+export const secrets = (context) => acquireImage(context, GITLEAKS_IMAGE, 'the secret scan') ??
+    withRenderedConfig(context, (configDirectory) => {
+        // `git` mode, not `dir`. The standard asks for the tracked content and the commit history, and
+        // history mode covers both: every tracked file's content is in some commit. `dir` mode has no git
+        // awareness at all - it reads `node_modules`, the build output, and a local `.env`, none of which
+        // the repository tracks or owns. On a real Payload project that was 1.09 GB against 2 MB, sixty
+        // times slower, and every finding it added came from a dependency rather than from this project.
+        const history = scanSecrets(context, configDirectory, 'git');
+        return (dockerFault(context, GITLEAKS_IMAGE, 'the secret scan', history) ??
+            fromRun(history, 'no secret found in the git history', 'the scanner found a secret in the git history'));
+    });
+// Both kinds are discovered from the tracked tree, by the rules in `governance`. The compose half used to
+// look at the repository root alone, so a project keeping its application - and its compose file - in a
+// member directory had that file validated by nothing, while the Dockerfile beside it was linted.
+const dockerfiles = (context) => dockerfilesIn(trackedFiles(context.root));
+const composeProjects = (context) => composeProjectsIn(trackedFiles(context.root));
+// Compose ships both as a `docker` subcommand and as a standalone binary, and which one a machine has is
+// not a property of the project. Try the modern form first and accept the legacy one, failing only when
+// neither can validate the file.
+//
+// Run from the project's own directory rather than from the repository root, because that is what decides
+// what compose reads: the override files beside it, the `.env` it interpolates from, and the build
+// contexts its relative paths name.
+const validateCompose = (directory) => {
+    const modern = run('sh', ['-c', 'docker compose config > /dev/null'], {
+        cwd: directory,
+    });
+    return modern.code === 0
+        ? modern
+        : run('sh', ['-c', 'docker-compose config > /dev/null'], { cwd: directory });
+};
+const validateComposeProjects = (context, projects) => projects.map((project) => ({
+    project,
+    result: validateCompose(path.join(context.root, project.directory)),
+}));
+const CONTAINER_GATE = 'the container gate';
+const firstReserved = (results) => {
+    const reserved = results
+        .map((result) => classifyContainerExit(CONTAINER_GATE, result))
+        .find((entry) => entry !== undefined);
+    return reserved === undefined ? undefined : describeFailure(reserved);
+};
+const lintResults = (linted) => linted.map((entry) => entry.result);
+// The file is fed on stdin through the argv form rather than through a shell redirection. It used to be
+// interpolated into an `sh -c` string with `JSON.stringify` around it, which is JSON quoting and not
+// shell quoting: inside double quotes `sh` still expands `$`, a backtick, and a backslash, so a tracked
+// file named `Dockerfile.$(...)` ran its own contents on every verification.
+const lintDockerfile = (context, target) => run('docker', ['run', '--rm', '-i', HADOLINT_IMAGE], {
+    cwd: context.root,
+    input: readFileSync(path.join(context.root, target), 'utf8'),
+});
+// Compose is judged on its exit code alone: it needs no analyzer image, so there is nothing to re-check
+// and its output quotes the project's own YAML. The Dockerfile half asks the further question, once for
+// the whole run rather than once per file - the answer cannot differ between two files linted seconds
+// apart, and asking per file would re-pull an image on every genuine finding.
+const containerFault = (context, linted, validated) => firstReserved([
+    ...lintResults(linted),
+    ...validated.map((entry) => entry.result),
+]) ??
+    (lintResults(linted).some((result) => result.code !== 0)
+        ? acquireImage(context, HADOLINT_IMAGE, CONTAINER_GATE)
+        : undefined);
+// What the gate actually looked at, so a pass never claims more than it checked. The summary read
+// "N Dockerfile(s) and the compose file are valid" whether or not a compose file existed.
+const describeTargets = (dockerfileCount, composeCount) => {
+    const parts = [
+        ...(dockerfileCount > 0 ? [`${String(dockerfileCount)} Dockerfile(s)`] : []),
+        ...(composeCount > 0 ? [`${String(composeCount)} compose project(s)`] : []),
+    ];
+    return parts.length === 0
+        ? 'the project ships no container definition'
+        : `${parts.join(' and ')} are valid`;
+};
+/** Lint every Dockerfile and validate every compose project. */
+export const containers = (context) => {
+    const targets = dockerfiles(context);
+    const projects = composeProjects(context);
+    // A project whose database comes from compose and whose app is built by Next ships no Dockerfile at
+    // all - the common Payload layout. Returning here on that count alone meant its compose file was
+    // never validated, and the gate reported a pass having read nothing.
+    if (projects.length === 0 && targets.length === 0) {
+        return passed('the project ships no container definition');
+    }
+    const unavailable = targets.length > 0 ? acquireImage(context, HADOLINT_IMAGE, CONTAINER_GATE) : undefined;
+    if (unavailable !== undefined) {
+        return unavailable;
+    }
+    // Run every tool first, then judge.
+    const linted = targets.map((target) => ({ target, result: lintDockerfile(context, target) }));
+    const validated = validateComposeProjects(context, projects);
+    const faulted = containerFault(context, linted, validated);
+    if (faulted !== undefined) {
+        return faulted;
+    }
+    const findings = [
+        ...linted.flatMap((entry) => entry.result.code === 0 ? [] : [`${entry.target}:`, ...asFindings(entry.result.output)]),
+        ...validated.flatMap((entry) => entry.result.code === 0 ? [] : [`${entry.project.file}:`, ...asFindings(entry.result.output)]),
+    ];
+    return findings.length > 0
+        ? failed('container definitions have defects', findings)
+        : passed(describeTargets(targets.length, projects.length));
+};
+/** Lint the GitHub Actions workflows. */
+export const actions = (context) => {
+    if (!existsSync(path.join(context.root, '.github', 'workflows'))) {
+        return passed('the project ships no workflows');
+    }
+    const unavailable = acquireImage(context, ACTIONLINT_IMAGE, 'the workflow gate');
+    if (unavailable !== undefined) {
+        return unavailable;
+    }
+    const result = run('docker', ['run', '--rm', '-v', `${context.root}:/repo`, '--workdir', '/repo', ACTIONLINT_IMAGE], { cwd: context.root });
+    return (dockerFault(context, ACTIONLINT_IMAGE, 'the workflow gate', result) ??
+        fromRun(result, 'workflows pass actionlint', 'a workflow does not pass actionlint'));
+};
+//# sourceMappingURL=containers.js.map

package/dist/checks/containers.js.map

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

package/dist/checks/conventions.d.ts

@@ -0,0 +1,8 @@
+import { type Context } from '../context.js';
+import { type GateResult } from '../exec.js';
+/**
+ * Scan every tracked file for banned typography, stray hand-written JavaScript, and documenting
+ * comments left above another comment rather than above what they document.
+ */
+export declare const conventions: (context: Context) => GateResult;
+//# sourceMappingURL=conventions.d.ts.map

package/dist/checks/conventions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.d.ts","sourceRoot":"","sources":["../../src/checks/conventions.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,KAAK,OAAO,EAAgB,MAAM,eAAe,CAAA;AAC1D,OAAO,EAAU,KAAK,UAAU,EAAU,MAAM,YAAY,CAAA;AAqF5D;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,OAAO,KAAG,UAY9C,CAAA"}

package/dist/checks/conventions.js

@@ -0,0 +1,77 @@
+// Source conventions: the AI-typography ban and the preference for TypeScript over hand-written
+// JavaScript. Both are scanned across every tracked file rather than a chosen subtree, because the
+// characters a model emits appear in documentation and configuration as readily as in code.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { DOCUMENTED_EXTENSIONS, findOrphanedDocBlocks, findTypographyViolations, hasExtension, isBinary, matchesRole, } from '@ploaness/governance';
+import { trackedFiles } from '../context.js';
+import { failed, passed } from '../exec.js';
+// The typography ban used to carry an allowlist of ten extensions here, which is the wrong shape for a
+// rule that reaches "every tracked file the repository does not exclude by file role": `.css`, `.adoc`,
+// a shell script, and a Dockerfile all went unscanned, and every new text format arrived unscanned
+// until someone remembered this list. The role predicate is default-safe in the other direction - a
+// binary asset is recognised from its own bytes, and everything else is text that gets scanned.
+const JAVASCRIPT_EXTENSIONS = ['.js', '.mjs', '.cjs'];
+// Regions a tool rewrites byte for byte on every run, so a local edit is reverted rather than kept and
+// the ban has nothing to enforce against. `next dev` upserts its agent-rules block into AGENTS.md
+// whenever it detects an AI agent, em dashes included. Only the span between the markers is skipped;
+// every line the project itself authors in the same file is still scanned.
+const VENDOR_MANAGED_REGIONS = [
+    /<!-- BEGIN:nextjs-agent-rules -->.*?<!-- END:nextjs-agent-rules -->/gs,
+];
+// Blank a managed region to spaces rather than delete it, so the line and column numbers reported for
+// the rest of the file still point at real source positions.
+const blankVendorRegions = (text) => VENDOR_MANAGED_REGIONS.reduce((content, region) => content.replaceAll(region, (match) => match.replaceAll(/[^\n]/g, ' ')), text);
+const typographyFindings = (context, tracked) => tracked
+    .filter((file) => !matchesRole(file, context.settings.typographyExclusions))
+    .flatMap((file) => {
+    const bytes = readFileSync(path.join(context.root, file));
+    if (isBinary(bytes)) {
+        return [];
+    }
+    const content = blankVendorRegions(bytes.toString('utf8'));
+    return findTypographyViolations(content).map((violation) => `${file}:${String(violation.line)}:${String(violation.column)} ` +
+        `banned ${violation.label}; use ${violation.replacement}`);
+});
+const javascriptFindings = (context, tracked) => tracked
+    .filter((file) => hasExtension(file, JAVASCRIPT_EXTENSIONS) &&
+    !matchesRole(file, context.settings.javascriptAllowlist))
+    .map((file) => `${file} hand-written JavaScript is banned; write TypeScript instead`);
+// A documenting comment stranded above another one documents nothing, and the symbol it was written
+// for is left with no doc at all. It is scanned here rather than by the lint pass because
+// eslint-plugin-jsdoc structurally cannot see it: every rule that plugin ships visits the block
+// ATTACHED to a syntax node, and the parser hands a declaration only the LAST block before it.
+//
+// The role exclusions are the ones `isGovernedCode` already reads, which is how the suppressions gate
+// scopes the same question: a generated file carries comments its generator wrote, and a project
+// cannot be asked to repair them.
+const orphanedDocFindings = (context, tracked) => tracked
+    .filter((file) => hasExtension(file, DOCUMENTED_EXTENSIONS) &&
+    !matchesRole(file, context.settings.typographyExclusions))
+    .flatMap((file) => {
+    const content = readFileSync(path.join(context.root, file), 'utf8');
+    return findOrphanedDocBlocks(content).map((block) => `${file}:${String(block.line)} the doc block ending on line ${String(block.endLine)} ` +
+        `is followed by another doc block rather than by what it documents`);
+});
+// A tracked path is not always a regular file. `git ls-files` reports a symlink and a submodule
+// gitlink too, and reading either throws rather than yielding text.
+const isRegularFile = (root, file) => {
+    const full = path.join(root, file);
+    return existsSync(full) && statSync(full).isFile();
+};
+/**
+ * Scan every tracked file for banned typography, stray hand-written JavaScript, and documenting
+ * comments left above another comment rather than above what they document.
+ */
+export const conventions = (context) => {
+    const tracked = trackedFiles(context.root).filter((file) => isRegularFile(context.root, file));
+    const findings = [
+        ...typographyFindings(context, tracked),
+        ...javascriptFindings(context, tracked),
+        ...orphanedDocFindings(context, tracked),
+    ];
+    return findings.length > 0
+        ? failed(`${String(findings.length)} convention violation(s)`, findings)
+        : passed(`${String(tracked.length)} tracked file(s) follow the source conventions`);
+};
+//# sourceMappingURL=conventions.js.map

package/dist/checks/conventions.js.map

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

package/dist/checks/dependencies.d.ts

@@ -0,0 +1,11 @@
+import { type Context } from '../context.js';
+import { type GateResult } from '../exec.js';
+export declare const licenses: (context: Context) => GateResult;
+export declare const dependencyFreshness: (context: Context) => Promise<GateResult>;
+/**
+ * Read every package in the resolved set against the public advisory database.
+ * @param context the resolved project environment.
+ * @returns a failure for any finding at or above the declared severity, or for a stale exception.
+ */
+export declare const vulnerabilities: (context: Context) => GateResult;
+//# sourceMappingURL=dependencies.d.ts.map

package/dist/checks/dependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.d.ts","sourceRoot":"","sources":["../../src/checks/dependencies.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAE,KAAK,OAAO,EAA4C,MAAM,eAAe,CAAA;AACtF,OAAO,EAEL,KAAK,UAAU,EAMhB,MAAM,YAAY,CAAA;AAgBnB,eAAO,MAAM,QAAQ,GAAI,SAAS,OAAO,KAAG,UAkC3C,CAAA;AAgVD,eAAO,MAAM,mBAAmB,GAAU,SAAS,OAAO,KAAG,OAAO,CAAC,UAAU,CA+C9E,CAAA;AA6CD;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,OAAO,KAAG,UAiDlD,CAAA"}