pr-checkmate 3.0.3 → 3.1.0

package/dist/esm/init.js

@@ -0,0 +1,421 @@
+import { fileURLToPath as __fileURLToPath } from 'node:url';
+import { dirname as __dirnameFn } from 'node:path';
+const __dirname = __dirnameFn(__fileURLToPath(import.meta.url));
+import fs from 'fs';
+import path from 'path';
+import inquirer from 'inquirer';
+import { DEAD_CODE_IGNORE_DEFAULTS, DEFAULT_COMMANDS, DIFF_SECURITY_IGNORE_DEFAULTS, documentation, DOCS_URL, DUPLICATE_IGNORE_DEFAULTS, FULL_CONFIG_URL, GENERATED_DOC_FILES, IGNORED_DIRS, } from './config/index.js';
+import { DEFAULT_DATAFLOW_WINDOW } from './core/checks/findings.js';
+import { logger, detectLanguages, findOwnPackageRoot } from './utils/index.js';
+const CONFIG_FILE = path.resolve(process.cwd(), 'pr-checkmate.json');
+/**
+ * Points editors at the bundled JSON schema. With the generated config reduced
+ * to the client's own decisions, this line is what makes every other option
+ * discoverable: the editor autocompletes each key and shows its description.
+ */
+const SCHEMA_PATH = './node_modules/pr-checkmate/pr-checkmate.schema.json';
+const MANUAL_ENTRY = 'Enter manually';
+/** Prompt the user for the project source path, allowing a manual entry. */
+async function promptSourcePath() {
+    const answers = await inquirer.prompt([
+        {
+            // inquirer v14 renamed the classic `list` prompt to `select`.
+            type: 'select',
+            name: 'sourcePath',
+            message: 'Where is your project source code?',
+            default: '.',
+            choices: [{ name: '. (entire repo — recommended)', value: '.' }, 'src', 'app', MANUAL_ENTRY],
+        },
+        {
+            type: 'input',
+            name: 'manualPath',
+            message: 'Enter path:',
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            when: (a) => a.sourcePath === MANUAL_ENTRY,
+            validate: (input) => input.trim().length > 0 || 'Cannot be empty',
+        },
+    ]);
+    return answers.sourcePath === MANUAL_ENTRY ? answers.manualPath : answers.sourcePath;
+}
+/**
+ * Ask whether the generated workflow should block merges.
+ *
+ * Two levers decide strictness and they are not interchangeable: this one says
+ * whether a failed run means anything to GitHub at all, while `severity` in
+ * pr-checkmate.json says which findings count as a failure. The recommended way
+ * into an existing codebase is a strict workflow plus a permissive config — the
+ * gate is real from day one, and checks are promoted one at a time.
+ */
+async function promptGateMode() {
+    const { mode } = await inquirer.prompt([
+        {
+            type: 'select',
+            name: 'mode',
+            message: 'Should a failed check block the pull request?',
+            default: 'strict',
+            choices: [
+                { name: 'Yes — block the merge (recommended)', value: 'strict' },
+                { name: 'No — report only, never block', value: 'advisory' },
+            ],
+        },
+    ]);
+    return mode;
+}
+/** The banner an advisory workflow carries, so it reads as a decision, not an accident. */
+const ADVISORY_NOTICE = [
+    '      # ADVISORY MODE — this run cannot block a merge.',
+    '      #',
+    '      # Chosen at `pr-checkmate init`. Reasonable while adopting the tool on an',
+    '      # existing codebase, but it also means a detected secret does not stop the',
+    '      # PR. To make this a real gate, delete the `continue-on-error` line below.',
+    '      #',
+    '      # Prefer the opposite arrangement: keep the gate real and relax individual',
+    '      # checks in pr-checkmate.json instead —',
+    '      #   "severityDefaults": { "failOn": "warn" }   everything advisory',
+    '      #   "severity": { "Security Scan": "error" }   promote one back to a gate',
+    '      # That way whatever you have already made clean stays enforced.',
+].join('\n');
+/** Indented to sit inside the step, not beside it — YAML is unforgiving here. */
+const ADVISORY_FLAG = '        continue-on-error: true';
+/**
+ * Write the bundled GitHub Actions workflow into the consumer repo.
+ *
+ * Never overwrites an existing file. `init` is not a one-time command — the
+ * update notice asks people to re-run it after every upgrade — so clobbering
+ * would quietly discard whatever they had tuned, including the gate setting they
+ * were just asked about.
+ */
+export function setupWorkflow(root, mode) {
+    // We can't know for sure whether a repo will end up depending on the npm
+    // package by the time this workflow first runs (that's a decision the client
+    // makes after `init`, e.g. by running `npm install pr-checkmate`), so instead
+    // of guessing we scaffold both variants and let them keep the one that
+    // matches, deleting the other:
+    //
+    //  - the npm variant: `npx pr-checkmate` runs the copy the lockfile pins,
+    //    which is fast and reproducible, but assumes the install happens;
+    //  - the docker variant: works with no install, but `npx` (nothing to run
+    //    locally) resolves to the newest release and downloads it on every job —
+    //    547 MB, about five minutes, and a major version can land without anyone
+    //    changing a line.
+    const candidates = [
+        { source: 'pr-checkmate-workflow.yml', dest: 'pr-checkmate.yml', label: 'npm package' },
+        {
+            source: 'pr-checkmate-workflow-docker.yml',
+            dest: 'pr-checkmate-docker.yml',
+            label: 'Docker image',
+        },
+    ];
+    const workflowDir = path.join(root, '.github', 'workflows');
+    const recommended = installsPackage(root) ? candidates[0] : candidates[1];
+    for (const { source, dest, label } of candidates) {
+        const workflowSource = path.join(__dirname, 'config', source);
+        const workflowDest = path.join(workflowDir, dest);
+        if (!fs.existsSync(workflowSource)) {
+            logger.warn(`[init]: ⚠️ Workflow template ${source} not found, skipping`);
+            continue;
+        }
+        if (fs.existsSync(workflowDest)) {
+            logger.info(`[init]: ⏭️ .github/workflows/${dest} already exists — left untouched`);
+            continue;
+        }
+        if (!fs.existsSync(workflowDir)) {
+            fs.mkdirSync(workflowDir, { recursive: true });
+        }
+        const template = fs.readFileSync(workflowSource, 'utf-8').replace(/__IMAGE_TAG__/g, imageTag());
+        const workflow = mode === 'advisory'
+            ? template.replace(RUN_STEP_ANCHOR, `${ADVISORY_NOTICE}\n${RUN_STEP_ANCHOR}\n${ADVISORY_FLAG}`)
+            : template;
+        fs.writeFileSync(workflowDest, workflow);
+        const recommendedNote = dest === recommended.dest ? ', recommended for this repo' : '';
+        logger.info(`[init]: ✅ Created .github/workflows/${dest} (${label}${recommendedNote})`);
+    }
+    logger.info('[init]: ℹ️ Both workflow variants were created — keep the one that fits and delete the other, ' +
+        'otherwise checks run twice on every PR.');
+}
+/**
+ * Whether this repository installs pr-checkmate rather than reaching for it on
+ * the pipeline. A missing or unreadable package.json answers "no", which is the
+ * safe way round: the container variant works either way, while the npm variant
+ * assumes an install that may not happen.
+ */
+function installsPackage(root) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8'));
+        return Boolean(pkg.dependencies?.['pr-checkmate'] ?? pkg.devDependencies?.['pr-checkmate']);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The image tag written into the generated workflow: our own major.
+ *
+ * Pinned to a major rather than to `latest`, so patches and features arrive on
+ * their own while a change that can start failing builds does not. Pinned to a
+ * major rather than an exact version, so a client is not left on a release with
+ * a known problem because nobody remembered to bump a YAML file.
+ */
+function imageTag() {
+    try {
+        const manifest = path.join(findOwnPackageRoot() ?? path.resolve(__dirname, '..'), 'package.json');
+        const version = JSON.parse(fs.readFileSync(manifest, 'utf-8')).version;
+        return version.split('.')[0] || 'latest';
+    }
+    catch {
+        return 'latest';
+    }
+}
+/** Where the advisory banner is spliced in — the step that runs the checks. */
+const RUN_STEP_ANCHOR = '      - name: Run PR CheckMate';
+/** Create a tsconfig.json scaffold if the consumer repo lacks one. */
+function setupTsConfig(root, sourcePath) {
+    const tsconfigPath = path.join(root, 'tsconfig.json');
+    if (fs.existsSync(tsconfigPath))
+        return;
+    const newTsConfig = {
+        compilerOptions: {
+            target: 'ES2020',
+            module: 'NodeNext',
+            outDir: 'dist',
+            strict: true,
+            rootDir: sourcePath,
+            moduleResolution: 'NodeNext',
+            esModuleInterop: true,
+            resolveJsonModule: true,
+            forceConsistentCasingInFileNames: true,
+            skipLibCheck: true,
+            types: ['node'],
+        },
+        include: [`${sourcePath}/**/*.ts`],
+        exclude: ['node_modules', 'dist'],
+    };
+    fs.writeFileSync(tsconfigPath, JSON.stringify(newTsConfig, null, 2));
+    logger.info('[init]: ✅ Created tsconfig.json using your sourcePath');
+}
+/**
+ * The file `init` writes for a new project — the client's decisions, nothing else.
+ *
+ * Every other setting is deliberately absent. The config is deep-merged over the
+ * built-in defaults when it is loaded, so a key that repeats a default changes
+ * nothing: it only lengthens the file and freezes today's value in someone
+ * else's repository. Three hundred generated lines also read as a wall of
+ * settings to maintain, when there is nothing to maintain.
+ *
+ * Discoverability moves to two places that cannot go stale — `$schema`, which
+ * makes an editor autocomplete every option with its description, and the
+ * annotated reference shipped inside the package.
+ */
+/** The one-line answer to "how do I change this" — see {@link buildInitialConfig}. */
+const REPORTING_HINT = [
+    'Results post to the PR/MR automatically.',
+    'GitHub: keep `permissions: pull-requests: write` AND pass the token to the step',
+    '(`env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}`) — Actions does not provide it',
+    'on its own, and without it the comment is silently skipped. The generated',
+    'workflow already does both.',
+    'GitLab: create a token (Project → Settings → Access Tokens, scope `api`) and add',
+    'it as CI/CD variable GITLAB_TOKEN.',
+    'Bitbucket: create a token (Repo → Settings → Access tokens, scope',
+    'pull-requests:write) and add it as repo variable BITBUCKET_TOKEN.',
+    'The token lives in YOUR CI variables, never in this file. Without it checks',
+    'still run and print to the log — only the comment is skipped.',
+].join(' ');
+/**
+ * Every check that fails the run out of the box, written into the generated
+ * config at its real default.
+ *
+ * Not a copy of a default for its own sake — this one is the gate's teeth, and
+ * the client is entitled to see which checks can stop their merge without
+ * reading our source or discovering it from a red pipeline. Written as `"error"`
+ * so the edit is in place: change the value, or delete the line to inherit
+ * whatever we ship next.
+ *
+ * Two things are deliberately absent. `Custom Rules` and `Banned Imports` can
+ * block too, but only for rules the client writes themselves, so listing them
+ * would suggest a gate that is inert until they act. And `Dockerfile Security`
+ * looks like it belongs here and does not: every one of its patterns is rated
+ * `warn`, so it never fails on its own.
+ *
+ * Keep in step with the checks' own defaults — `blocking-checks.test.ts` pins
+ * every name here to the registry, which catches a rename but not a change of
+ * heart about what should block.
+ */
+export const BLOCKING_BY_DEFAULT = [
+    'Security Scan',
+    'Sensitive Files',
+    'Diff Security',
+    'Workflow Security',
+    'Merge Conflict',
+    'NPM Audit',
+    'License Check',
+    'Dependencies',
+    'TypeScript',
+    'ESLint',
+    'YAML Lint',
+];
+const HOW_TO = [
+    'Only what differs from the defaults belongs here — everything else is implicit',
+    'and stays current on upgrade, so this file stays short.',
+    'Turn a check off:      "severity": { "Spellcheck": "off" }',
+    'Make one advisory:     "severity": { "Sensitive Files": "warn" }',
+    'Make everything advisory while adopting: "severityDefaults": { "failOn": "warn" }',
+    'Skip a file or folder: "excludePaths": ["src/generated/**", "vendor/legacy.ts"]',
+    'Check names are the ones printed in the report.',
+    `Every option, annotated, with its default: ${FULL_CONFIG_URL}`,
+    `Docs: ${DOCS_URL}`,
+].join(' ');
+export function buildInitialConfig(sourcePath, languages) {
+    return {
+        $schema: SCHEMA_PATH,
+        '// how-to': HOW_TO,
+        commands: DEFAULT_COMMANDS,
+        '// reporting': REPORTING_HINT,
+        sourcePath,
+        // Which checks can stop a merge — named, but NOT written as values.
+        //
+        // Writing `"Workflow Security": "error"` reads like a statement of the
+        // default and is not one: the map promotes as well as demotes, so an entry
+        // of "error" turns that check's ADVISORY findings into failures too. On a
+        // real client repository that flipped 54 warnings into a red build. The
+        // names belong in a comment; the map stays empty until the client means
+        // something by it.
+        '// severity': [
+            `These checks fail a run by default: ${BLOCKING_BY_DEFAULT.join(', ')}.`,
+            'To stand one down, add it below with "warn" (stays in the report, stops',
+            'blocking) or "off" (does not run at all).',
+            'Adding a check with "error" is not a restatement of the default — it also',
+            "PROMOTES that check's advisory findings to failures, which is stricter.",
+        ].join(' '),
+        severity: {},
+        // The knobs people reach for first.
+        //
+        // Two shapes appear here, and the difference is not cosmetic. A list whose
+        // values are APPENDED to the defaults is seeded empty: empty changes nothing,
+        // so it cannot freeze today's default in someone else's repository. A list
+        // that REPLACES its default is written out in full instead — seeded empty it
+        // would silently switch the default off, and left out entirely it would be
+        // invisible, which is how a repository ends up spellchecking its own
+        // CHANGELOG and reporting every test fixture as duplication.
+        //
+        // Written-out lists are a deliberate trade: they stop tracking the package,
+        // so a later release that adds a directory to the defaults will not reach a
+        // config that already spells the list out. That is the price of being able
+        // to see and edit the value, and it is the one people asked for.
+        excludePaths: [],
+        // REPLACES the default. Copied out so the list is editable in place —
+        // note that ESLint does not read it; ESLint honours `eslint.ignorePatterns`.
+        ignoreDirs: [...IGNORED_DIRS],
+        // Spelling: `words` and `ignorePaths` are both APPENDED to the bundled lists,
+        // so both stay empty. What the bundled list already skips is spelled out in
+        // the sibling comment rather than duplicated here.
+        '// cspell': `Already skipped by default: ${GENERATED_DOC_FILES.join(', ')}, test and mock paths, lockfiles, minified bundles, and every directory in "ignoreDirs". Anything listed below is ADDED to that.`,
+        cspell: { words: [], ignorePaths: [] },
+        // `max-len` is written out at its default rather than left implicit: it is
+        // the rule people hit first and tune first, and a line limit is a house
+        // style, not a defect — arguing with it through documentation wastes
+        // everyone's time when the number could just be sitting here, editable.
+        eslint: { rules: { 'max-len': ['warn', { code: 300 }] }, ignorePatterns: [] },
+        markdownlint: { ignores: [] },
+        dependency: { ignore: [] },
+        circularDeps: { ignore: [] },
+        yamlLint: { ignore: [] },
+        // The three lists that REPLACE their defaults, written out. Each one exists
+        // because test code trips a check that production code does not: suites
+        // repeat their setup, the runner is the only consumer of what they export,
+        // and a security test's whole job may be to call the dangerous function.
+        // Delete an entry to have that check start reporting on tests again.
+        duplicate: { ignore: [...DUPLICATE_IGNORE_DEFAULTS] },
+        deadCode: { ignoreFiles: [...DEAD_CODE_IGNORE_DEFAULTS] },
+        // `dataflowWindow` is written out at its default for the same reason as
+        // `max-len`: it is a number people will want to change, and a number nobody
+        // can see is a number nobody can change. It is also the one finding in this
+        // check produced by a heuristic rather than a pattern, so the caveat belongs
+        // next to the value — including the part that surprises people, which is what
+        // promoting the whole check to `error` does to it.
+        '// diffSecurity': [
+            '"ignorePaths" REPLACES the test-path defaults below — they are there because a security',
+            "test's job is to contain the exact constructs this check hunts for.",
+            '"dataflowWindow" is how many added lines a value stays tainted for, so an interpolated',
+            'string assigned on one line and passed to a query on the next are still connected.',
+            'It is a heuristic — no scopes, no reassignment tracking — so it only ever warns.',
+            'Set it to 0 to switch it off. Note that "severity": { "Diff Security": "error" } promotes',
+            'this warning to a failure along with the rest, so a repository that makes this check a',
+            'gate and does not want the heuristic blocking should set dataflowWindow to 0.',
+        ].join(' '),
+        diffSecurity: {
+            dataflowWindow: DEFAULT_DATAFLOW_WINDOW,
+            ignorePaths: [...DIFF_SECURITY_IGNORE_DEFAULTS],
+        },
+        documentation,
+        languages,
+    };
+}
+/** First-run setup: prompt, write config, and scaffold workflow + tsconfig. */
+async function createConfig(root) {
+    const sourcePath = await promptSourcePath();
+    const gateMode = await promptGateMode();
+    const languages = await detectLanguages(root);
+    logger.info(`[init]: 🔍 Detected languages: ${languages.length ? languages.join(', ') : 'none'}`);
+    const config = buildInitialConfig(sourcePath, languages);
+    fs.writeFileSync(CONFIG_FILE, `${JSON.stringify(config, null, 2)}\n`);
+    logger.info(`[init]: ✅ Created pr-checkmate.json with sourcePath: ${sourcePath}`);
+    logger.info(`[init]: 💡 You can now customize ESLint rules, Prettier settings,
+      and cspell words in pr-checkmate.json`);
+    setupWorkflow(root, gateMode);
+    setupTsConfig(root, sourcePath);
+}
+/**
+ * Re-run setup: refresh the detected languages and leave everything else alone.
+ *
+ * It used to merge current defaults into the client's file, which is why the
+ * update notice insisted `init` must not be skipped after an upgrade. Defaults
+ * now apply when the config is loaded, so there is nothing to top up.
+ */
+async function updateConfig(root) {
+    logger.info('[init]: pr-checkmate.json already exists — updating it.');
+    try {
+        const raw = fs.readFileSync(CONFIG_FILE, 'utf-8');
+        const json = JSON.parse(raw);
+        // Re-detection has to obey the config it is about to rewrite: a client who
+        // tuned `detect` (or `ignoreDirs`) precisely because detection was wrong
+        // would otherwise get the wrong answer written back over the right one on
+        // the next `init`.
+        const languages = await detectLanguages(root, json.ignoreDirs, json.detect);
+        logger.info(`[init]: 🔍 Detected languages: ${languages.length ? languages.join(', ') : 'none'}`);
+        // The client's file is left exactly as they wrote it. Defaults are no longer
+        // copied into it, because they never needed to be: they are merged in when
+        // the config is loaded, so a new default reaches every repository on upgrade
+        // without anyone editing anything. Writing them here only grew the file and
+        // made `init` a step nobody could safely skip after a release.
+        //
+        // `languages` is still refreshed — it is a fact about the repository, not a
+        // preference. `$schema` and the how-to hint are added when missing, because
+        // an existing config is exactly the case where nobody has seen them: the
+        // people who most need to know how to switch a check off are the ones whose
+        // file predates the advice.
+        const updated = {
+            $schema: json.$schema ?? SCHEMA_PATH,
+            '// how-to': json['// how-to'] ?? HOW_TO,
+            ...json,
+            languages,
+        };
+        fs.writeFileSync(CONFIG_FILE, `${JSON.stringify(updated, null, 2)}\n`);
+        logger.info('[init]: 🔧 Refreshed the detected languages in pr-checkmate.json.');
+        logger.info(`[init]: 💡 Everything else is left as you wrote it — defaults apply on their own. Options: ${DOCS_URL}`);
+    }
+    catch (e) {
+        logger.error(`[init]: ❌ Failed to update pr-checkmate.json: ${e}`);
+    }
+}
+/**
+ * Initialize (or refresh) pr-checkmate configuration in the current project.
+ */
+export async function init() {
+    const root = process.cwd();
+    if (fs.existsSync(CONFIG_FILE)) {
+        await updateConfig(root);
+    }
+    else {
+        await createConfig(root);
+    }
+}