pr-checkmate 3.0.3 → 3.1.0

package/dist/esm/core/checks/quality/spellcheck.js

@@ -0,0 +1,296 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getPackageConfigPath, hasLocalConfig, IGNORE_PATTERNS, getSourcePaths, } from '../../../config/index.js';
+import { execa } from '../../../utils/execa.js';
+import { logger, cleanupTempFile, matchesAnyGlob, resolvePackageBin, } from '../../../utils/index.js';
+import { resolveScopedTargetFiles } from '../../targets.js';
+import { pass, warn, skip } from '../../types.js';
+function loadUserCspellConfig(cwd) {
+    const configPath = path.join(cwd, 'pr-checkmate.json');
+    if (!fs.existsSync(configPath))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(configPath, 'utf-8')).cspell || {};
+    }
+    catch (err) {
+        logger.warn(`[Spellcheck]: ⚠️ Failed to read cspell config: ${err}`);
+        return {};
+    }
+}
+/**
+ * Anchors an ignore glob to the repository root.
+ *
+ * cspell matches `ignorePaths` against each file's ABSOLUTE path, so an unanchored
+ * `**\/build/**` also matches every ancestor directory of the workspace. On Bitbucket
+ * Pipelines the clone lives in `/opt/atlassian/pipelines/agent/build`, so that one
+ * pattern excluded the entire repository and the check silently spellchecked nothing.
+ * A leading `/` anchors the pattern to the config's directory (the repo root) while
+ * `/**\/dir/**` still matches at any depth INSIDE the repo — verified against cspell 10.
+ *
+ * Patterns that are already anchored (`/…`) or plainly relative (`dir/**`,
+ * `CHANGELOG.md`) are left untouched: they cannot match an ancestor.
+ */
+export function anchorIgnoreGlob(pattern) {
+    return pattern.startsWith('**/') ? `/${pattern}` : pattern;
+}
+/**
+ * Folds the client's `cspell` block from pr-checkmate.json into the bundled
+ * defaults. `enabled` is deliberately not carried over — it gates the check
+ * itself (see `applies`) and is not a cspell setting.
+ *
+ * Lists are appended so a client extends the curated vocabulary instead of
+ * replacing it; `language` is the one exception and replaces the default, because
+ * a client writing `"en"` means exactly that and appending would be meaningless.
+ */
+export function mergeCspellConfig(defaultConfig, userConfig) {
+    const dictionaries = [...(defaultConfig.dictionaries ?? []), ...(userConfig.dictionaries ?? [])];
+    return {
+        ...defaultConfig,
+        language: userConfig.language || defaultConfig.language,
+        // Appended, so a client can point at a dictionary they installed themselves
+        // without losing the bundled ones. Anything that does not resolve is dropped
+        // later rather than passed to cspell, which would abort the whole run.
+        import: [...(defaultConfig.import ?? []), ...(userConfig.import ?? [])],
+        words: [...defaultConfig.words, ...(userConfig.words || [])],
+        // Client globs are anchored too — a repo's own pattern is meant to be relative
+        // to that repo, never to whatever directories sit above the checkout.
+        ignorePaths: [...defaultConfig.ignorePaths, ...(userConfig.ignorePaths || [])].map(anchorIgnoreGlob),
+        ignoreRegExpList: [...defaultConfig.ignoreRegExpList, ...(userConfig.ignoreRegExpList || [])],
+        // The bundled dictionaries arrive through `import`, so there is nothing to
+        // override here. cspell ignores names it cannot resolve, so a client typo
+        // costs coverage but never fails the run.
+        ...(dictionaries.length > 0 ? { dictionaries } : {}),
+    };
+}
+/**
+ * Non-English dictionaries the package no longer installs, and the language code
+ * each one serves.
+ *
+ * They used to be hard dependencies and cost every client ~9 MB on every install,
+ * to spellcheck languages almost none of them write. They are still *supported*:
+ * {@link availableDictionaries} enables one the moment it resolves, so a client
+ * who wants Russian back runs `npm i -D @cspell/dict-ru_ru` and edits no config.
+ *
+ * They are added at runtime rather than left in the bundled `cspell.json`,
+ * because a config that references an uninstalled dictionary is not a degraded
+ * config — see {@link resolveImports} — it is a broken one.
+ */
+const OPTIONAL_DICTIONARIES = [
+    { pkg: '@cspell/dict-ru_ru/cspell-ext.json', lang: 'ru', script: 'Cyrillic' },
+    { pkg: '@cspell/dict-uk-ua/cspell-ext.json', lang: 'uk', script: 'Cyrillic' },
+    { pkg: '@cspell/dict-he/cspell-ext.json', lang: 'he', script: 'Hebrew' },
+    { pkg: '@cspell/dict-fr-fr/cspell-ext.json', lang: 'fr' },
+    { pkg: '@cspell/dict-es-es/cspell-ext.json', lang: 'es' },
+];
+/**
+ * The optional dictionaries this installation actually has — and what to do
+ * about the ones it does not.
+ *
+ * Dropping a dictionary must not turn into a flood of warnings: a repository
+ * with Russian comments would report every Russian word as a misspelling, which
+ * is worse than the ~9 MB the dictionaries cost. So for the languages written in
+ * a script of their own, absence suppresses that script instead: cspell cannot
+ * judge those words, and reporting words it cannot judge is noise, not coverage.
+ *
+ * Latin-script languages (French, Spanish) have no such escape — their words are
+ * indistinguishable from misspelled English — so their absence is only logged,
+ * with the command that restores them.
+ *
+ * @returns imports and language codes to enable, ignore patterns for scripts left
+ *   without a dictionary, and the packages a client may want to install.
+ */
+export function availableDictionaries(resolve = require.resolve) {
+    const imports = [];
+    const languages = [];
+    const scripts = new Set();
+    const absent = [];
+    for (const { pkg, lang, script } of OPTIONAL_DICTIONARIES) {
+        try {
+            imports.push(resolve(pkg));
+            languages.push(lang);
+        }
+        catch {
+            absent.push(pkg.split('/cspell-ext.json')[0]);
+            if (script)
+                scripts.add(script);
+        }
+    }
+    // A script is only suppressed when NO dictionary covering it survived: with
+    // Russian installed and Ukrainian missing, Cyrillic is still checked.
+    const covered = new Set(OPTIONAL_DICTIONARIES.filter(d => d.script && languages.includes(d.lang)).map(d => d.script));
+    return {
+        imports,
+        languages,
+        ignoreRegExpList: [...scripts]
+            .filter(script => !covered.has(script))
+            .map(script => `/\\p{Script=${script}}+/gu`),
+        absent,
+    };
+}
+/**
+ * Turn config imports into absolute paths, dropping the ones that are not installed.
+ *
+ * An unresolvable `import` is not a soft failure in cspell: it aborts config
+ * loading, checks **zero files**, and exits 1 — which this check would then have
+ * reported as "spelling issues found", a warning about problems that do not exist
+ * on a run that examined nothing. Passing the raw string through and hoping cspell
+ * copes is therefore the one thing that must not happen.
+ *
+ * @returns the imports that resolved, plus the language codes left without a
+ *   dictionary so the caller can drop them from `language`.
+ */
+export function resolveImports(imports, baseDir, resolve = require.resolve) {
+    const resolvedPaths = [];
+    const missing = [];
+    for (const entry of imports) {
+        // A relative path comes from our own bundled config; it ships with the
+        // package and is resolved against it, not against the client's cwd.
+        if (entry.startsWith('.')) {
+            resolvedPaths.push(path.resolve(baseDir, entry));
+            continue;
+        }
+        try {
+            resolvedPaths.push(resolve(entry));
+        }
+        catch {
+            missing.push({
+                pkg: entry,
+                lang: OPTIONAL_DICTIONARIES.find(d => entry.startsWith(d.pkg))?.lang,
+            });
+        }
+    }
+    return { resolved: resolvedPaths, missing };
+}
+/**
+ * Drop language codes whose dictionary is absent.
+ *
+ * Leaving `ru` in `language` with no Russian dictionary does not spellcheck
+ * Russian — it reports every Russian word as a misspelling. Having no opinion is
+ * the honest outcome when the dictionary that would form one is not installed.
+ */
+export function dropMissingLanguages(language, missing) {
+    const kept = language
+        .split(',')
+        .map(code => code.trim())
+        .filter(code => code && !missing.includes(code));
+    // `en` is the floor: a config with an empty `language` makes cspell fall back
+    // to its own default, which is not necessarily what was configured here.
+    return kept.length > 0 ? kept.join(',') : 'en';
+}
+/**
+ * Resolve a package id from the repository under review first, then from our own
+ * tree.
+ *
+ * The default `require.resolve` searches from THIS module, which is only the
+ * client's tree by accident. Installed as a dependency we sit in their
+ * `node_modules` and npm hoists `@cspell/dict-*` above us, so walking up finds
+ * it. Run through `npx` we sit in the npx cache and their `node_modules` is not
+ * on the path at all — so `npm i -D @cspell/dict-ru_ru`, which this file's own
+ * docstring promises is all it takes, did nothing and said nothing (ticket 081).
+ *
+ * Same policy as tool resolution for binaries: the client's copy first, ours as
+ * the fallback.
+ */
+function resolveFrom(cwd) {
+    return id => {
+        try {
+            return require.resolve(id, { paths: [cwd] });
+        }
+        catch {
+            return require.resolve(id);
+        }
+    };
+}
+function createTempCspellConfig(cwd) {
+    const packageConfigPath = getPackageConfigPath('cspell.json');
+    const packageConfigDir = path.dirname(packageConfigPath);
+    const defaultConfig = JSON.parse(fs.readFileSync(packageConfigPath, 'utf-8'));
+    const userConfig = loadUserCspellConfig(cwd);
+    const merged = mergeCspellConfig(defaultConfig, userConfig);
+    const resolve = resolveFrom(cwd);
+    const { resolved, missing } = resolveImports(merged.import ?? [], packageConfigDir, resolve);
+    const available = availableDictionaries(resolve);
+    for (const { pkg } of missing) {
+        logger.info(`[Spellcheck]: dictionary ${pkg} is not installed and was skipped. Add it with \`npm i -D ${pkg}\`.`);
+    }
+    if (available.absent.length > 0) {
+        // `info`, not `debug`. A client who installed a dictionary and saw no change
+        // had nothing to read: the one line that would have explained it was behind a
+        // flag. Which dictionaries are in play decides which findings appear, so it
+        // belongs in the ordinary log (ticket 081).
+        logger.info(`[Spellcheck]: optional dictionaries not installed: ${available.absent.join(', ')}. ` +
+            `Install any of them to spellcheck that language (\`npm i -D ${available.absent[0]}\`).`);
+    }
+    // A language the client asked for whose dictionary is absent is dropped rather
+    // than left in place: without the dictionary, "ru" does not spellcheck Russian,
+    // it reports every Russian word as a misspelling.
+    const requested = dropMissingLanguages(merged.language, OPTIONAL_DICTIONARIES.map(d => d.lang).filter(lang => !available.languages.includes(lang)));
+    const mergedConfig = {
+        ...merged,
+        language: [...new Set([...requested.split(','), ...available.languages])].join(','),
+        import: [...resolved, ...available.imports],
+        ignoreRegExpList: [...merged.ignoreRegExpList, ...available.ignoreRegExpList],
+    };
+    const tempConfigPath = path.join(cwd, '.cspell.temp.json');
+    fs.writeFileSync(tempConfigPath, JSON.stringify(mergedConfig, null, 2));
+    return tempConfigPath;
+}
+export const spellcheckCheck = {
+    name: 'Spellcheck',
+    phase: 'informational',
+    weight: 'heavy',
+    /**
+     * Clients turn the check off with `cspell.enabled: false` (or the `spellcheck`
+     * alias the config interface uses). The universal `severity: { Spellcheck: "off" }`
+     * switch keeps working too — this is the per-check flag every other check exposes.
+     */
+    applies(ctx) {
+        return ctx.config.cspell?.enabled !== false && ctx.config.spellcheck?.enabled !== false;
+    },
+    async run(ctx) {
+        const targets = await resolveScopedTargetFiles(ctx, ['*.ts', '*.tsx', '*.js', '*.jsx', '*.md', '*.mdx', '*.json'], getSourcePaths(ctx.cwd));
+        if (targets === null)
+            return skip('git unavailable');
+        // Committed build output and test reports are dropped here, in JS, against
+        // repo-RELATIVE paths — a client cannot fix a typo in a generated file, so
+        // reporting one is noise that buries the real findings. Neither cspell
+        // mechanism can do this safely: `--exclude` ignores glob anchoring outright
+        // (`--exclude=/**/build/**` still matches an ancestor `build` dir, which on
+        // Bitbucket Pipelines is the checkout itself), and `ignorePaths` only reaches
+        // repos that have no cspell config of their own. Filtering the list keeps one
+        // rule for every repo. `ignoreDirs` already covers plain directory names via
+        // `resolveTargetFiles`; this adds the composite globs it cannot express
+        // (`**/cypress/videos/**`, `**/jest-html-reporters-*/**`).
+        const files = targets.filter(f => !matchesAnyGlob(f, IGNORE_PATTERNS));
+        if (files.length === 0)
+            return pass('no files to spellcheck');
+        const hasLocal = hasLocalConfig(['cspell.json', '.cspell.json', 'cspell.config.json'], ctx.cwd);
+        let tempConfigPath = null;
+        const cspellBin = resolvePackageBin('cspell', 'bin.mjs');
+        // `--no-must-find-files`: cspell exits 1 when it checked nothing, which the
+        // exit-code mapping below would report as "spelling issues found" — a warning
+        // about problems that do not exist. Every file being excluded is a pass, not a
+        // finding.
+        const baseArgs = [...files, '--no-progress', '--no-must-find-files'];
+        let args;
+        if (hasLocal) {
+            args = baseArgs;
+        }
+        else {
+            tempConfigPath = createTempCspellConfig(ctx.cwd);
+            args = [...baseArgs, '--config', tempConfigPath];
+        }
+        try {
+            const result = await execa(process.execPath, [cspellBin, ...args], {
+                cwd: ctx.cwd,
+                reject: false,
+                stdio: 'inherit',
+            });
+            return result.exitCode === 0 ? pass() : warn('spelling issues found');
+        }
+        finally {
+            if (tempConfigPath)
+                cleanupTempFile(tempConfigPath);
+        }
+    },
+};

package/dist/esm/core/checks/quality/symlinks.d.ts

@@ -0,0 +1,16 @@
+import { Check } from '../../types.js';
+/** True when `fullPath` is a symlink whose target does not exist. */
+export declare function isBrokenSymlink(fullPath: string): boolean;
+/**
+ * Flags tracked symlinks whose target does not exist. `fs.existsSync` follows a
+ * symlink to its target, so it returns `false` for exactly the broken case while
+ * the link itself is still a real, tracked file — that's what makes a plain
+ * existence check (as used by `resolveTargetFiles`) unusable here and requires
+ * the dedicated `isBrokenSymlink` pass over `fs.lstatSync` above.
+ *
+ * Whole-repo scan (not delta), like Case Collision: a broken link fails a
+ * checkout or build regardless of which PR introduced it, so it's worth
+ * catching even when this run's diff never touched it. Informational and warns
+ * by default — promote to a gate per repo with `symlinks.severity`.
+ */
+export declare const symlinksCheck: Check;

package/dist/esm/core/checks/quality/symlinks.js

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { matchesAnyGlob } from '../../../utils/index.js';
+import { resolveTargets } from '../../targets.js';
+import { pass } from '../../types.js';
+import { severityEmitter } from '../findings.js';
+/** True when `fullPath` is a symlink whose target does not exist. */
+export function isBrokenSymlink(fullPath) {
+    let stat;
+    try {
+        stat = fs.lstatSync(fullPath);
+    }
+    catch {
+        return false; // gone between listing and stat
+    }
+    return stat.isSymbolicLink() && !fs.existsSync(fullPath);
+}
+/**
+ * Flags tracked symlinks whose target does not exist. `fs.existsSync` follows a
+ * symlink to its target, so it returns `false` for exactly the broken case while
+ * the link itself is still a real, tracked file — that's what makes a plain
+ * existence check (as used by `resolveTargetFiles`) unusable here and requires
+ * the dedicated `isBrokenSymlink` pass over `fs.lstatSync` above.
+ *
+ * Whole-repo scan (not delta), like Case Collision: a broken link fails a
+ * checkout or build regardless of which PR introduced it, so it's worth
+ * catching even when this run's diff never touched it. Informational and warns
+ * by default — promote to a gate per repo with `symlinks.severity`.
+ */
+export const symlinksCheck = {
+    name: 'Broken Symlinks',
+    phase: 'informational',
+    applies(ctx) {
+        return ctx.config.symlinks?.enabled !== false;
+    },
+    async run(ctx) {
+        const files = await resolveTargets(ctx, ['*'], {
+            wholeTree: true,
+            onEmpty: { skip: 'no tracked files' },
+        });
+        if (!Array.isArray(files))
+            return files;
+        const ignore = ctx.config.symlinks?.ignore ?? [];
+        const broken = [];
+        for (const file of files) {
+            if (ignore.length > 0 && matchesAnyGlob(file, ignore))
+                continue;
+            if (isBrokenSymlink(path.join(ctx.cwd, file)))
+                broken.push(file);
+        }
+        if (broken.length === 0)
+            return pass();
+        const sev = severityEmitter(ctx.config.symlinks?.severity, 'warn');
+        broken.forEach(f => sev.log(`[Broken Symlinks]: ${sev.icon} ${f} — target does not exist`));
+        return sev.emit(`${broken.length} broken symlink(s)`);
+    },
+};

package/dist/esm/core/checks/quality/yaml-lint.d.ts

@@ -0,0 +1,20 @@
+import { Check } from '../../types.js';
+/**
+ * True when a parser problem describes something actually wrong with the file —
+ * a syntax error, a duplicate key, a tab used for indentation.
+ */
+export declare function isFileDefect(problem: {
+    code?: string;
+}): boolean;
+/**
+ * Bundled YAML linter (the `yaml` package — no runner dependency, always
+ * available like Markdown/Spellcheck). Parses every changed `.yml`/`.yaml` file
+ * and reports the parser's own errors and warnings: syntax errors, duplicate map
+ * keys, tabs used as indentation, and other structural problems. Multi-document
+ * files (`---`-separated) are each parsed. ON by default — runs unless
+ * `yamlLint.enabled` is explicitly `false`. Findings are a hard error by default
+ * (a YAML problem fails the run); downgrade to advisory with
+ * `yamlLint.severity: "warn"`. Clients can exclude paths with `yamlLint.ignore`
+ * (glob patterns) in pr-checkmate.json.
+ */
+export declare const yamlLintCheck: Check;

package/dist/esm/core/checks/quality/yaml-lint.js

@@ -0,0 +1,116 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseAllDocuments } from 'yaml';
+import { logger, matchesAnyGlob } from '../../../utils/index.js';
+import { resolveTargetFiles } from '../../targets.js';
+import { pass, skip } from '../../types.js';
+import { severityEmitter } from '../findings.js';
+/** First line of a `yaml` error/warning message, stripped of its source excerpt. */
+function shortMessage(message) {
+    return message.split('\n')[0].trim();
+}
+/**
+ * Parser problems that are not defects in the file.
+ *
+ * `TAG_RESOLVE_FAILED` means the parser met an application-specific tag it has no
+ * schema for. YAML is explicitly extensible there, so the document is valid and the
+ * parser simply is not the application that defines the tag: `!Ref`, `!Sub`,
+ * `!GetAtt`, `!Equals` in CloudFormation and SAM templates, `!include` in Home
+ * Assistant, `!vault` in Ansible. Reporting those calls a whole ecosystem's valid
+ * files broken — one CloudFormation template produced **557 blocking findings** for
+ * a client, none of which was a real problem.
+ *
+ * Matched on the parser's `code`, not on message text, so a wording change upstream
+ * cannot silently re-enable it.
+ */
+const NON_DEFECT_CODES = new Set(['TAG_RESOLVE_FAILED']);
+/**
+ * True when a parser problem describes something actually wrong with the file —
+ * a syntax error, a duplicate key, a tab used for indentation.
+ */
+export function isFileDefect(problem) {
+    return problem.code === undefined || !NON_DEFECT_CODES.has(problem.code);
+}
+/**
+ * Bundled YAML linter (the `yaml` package — no runner dependency, always
+ * available like Markdown/Spellcheck). Parses every changed `.yml`/`.yaml` file
+ * and reports the parser's own errors and warnings: syntax errors, duplicate map
+ * keys, tabs used as indentation, and other structural problems. Multi-document
+ * files (`---`-separated) are each parsed. ON by default — runs unless
+ * `yamlLint.enabled` is explicitly `false`. Findings are a hard error by default
+ * (a YAML problem fails the run); downgrade to advisory with
+ * `yamlLint.severity: "warn"`. Clients can exclude paths with `yamlLint.ignore`
+ * (glob patterns) in pr-checkmate.json.
+ */
+export const yamlLintCheck = {
+    name: 'YAML Lint',
+    phase: 'blocking',
+    applies(ctx) {
+        return ctx.config.yamlLint?.enabled !== false;
+    },
+    async run(ctx) {
+        // Keep the CI/workflow dirs that are globally ignored: they hold the very
+        // YAML (GitHub Actions, GitLab CI, CircleCI) a YAML linter most needs to see.
+        const allTargets = await resolveTargetFiles(ctx, ['*.yml', '*.yaml'], {
+            keepDirs: ['.github', '.gitlab', '.circleci'],
+        });
+        if (allTargets === null)
+            return skip('git unavailable');
+        if (allTargets.length === 0)
+            return skip('no YAML files');
+        const ignore = ctx.config.yamlLint?.ignore ?? [];
+        const targets = ignore.length > 0 ? allTargets.filter(f => !matchesAnyGlob(f, ignore)) : allTargets;
+        if (targets.length === 0)
+            return skip('all YAML files ignored');
+        const issues = [];
+        for (const file of targets) {
+            let source;
+            try {
+                source = fs.readFileSync(path.join(ctx.cwd, file), 'utf-8');
+            }
+            catch (err) {
+                logger.warn(`[YAML Lint]: ⚠️ Could not read ${file}: ${err}`);
+                continue;
+            }
+            // parseAllDocuments never throws — it collects problems on each document,
+            // so a single malformed file cannot abort the whole check.
+            const docs = parseAllDocuments(source, { prettyErrors: true });
+            for (const doc of docs) {
+                const problems = [
+                    ...doc.errors.map(p => ({ problem: p, blocking: true })),
+                    ...doc.warnings.map(p => ({ problem: p, blocking: false })),
+                ].filter(({ problem }) => isFileDefect(problem));
+                for (const { problem, blocking } of problems) {
+                    const pos = problem.linePos?.[0];
+                    issues.push({
+                        file,
+                        blocking,
+                        line: pos?.line,
+                        col: pos?.col,
+                        message: shortMessage(problem.message),
+                    });
+                }
+            }
+        }
+        if (issues.length === 0)
+            return pass();
+        // A file that does not parse blocks; a file that parses and merely worries
+        // the parser does not. Treating both as blocking is what made this check
+        // feel like an obstacle rather than a gate — and a check people switch off
+        // protects nobody. `yamlLint.severity` still overrides both at once.
+        const configured = ctx.config.yamlLint?.severity;
+        const broken = issues.filter(i => i.blocking);
+        const questionable = issues.filter(i => !i.blocking);
+        const describe = (i) => `${i.file}${i.line ? `:${i.line}${i.col ? `:${i.col}` : ''}` : ''} — ${i.message}`;
+        const sev = severityEmitter(configured, broken.length > 0 ? 'error' : 'warn');
+        [...broken, ...questionable]
+            .slice(0, 10)
+            .forEach(i => sev.log(`[YAML Lint]: ${sev.icon} ${describe(i)}`));
+        if (issues.length > 10)
+            sev.log(`[YAML Lint]:   ... and ${issues.length - 10} more`);
+        const summary = broken.length > 0 && questionable.length > 0
+            ? `${broken.length} unparseable, ${questionable.length} questionable YAML issue(s)`
+            : `${issues.length} YAML issue(s) found`;
+        return sev.emit(summary);
+    },
+};

package/dist/esm/core/checks/security/diff-security.d.ts

@@ -0,0 +1,2 @@
+import { Check } from '../../types.js';
+export declare const diffSecurityCheck: Check;