@veda-hq/pariksha 0.5.2 → 0.5.5

package/README.md

@@ -4,8 +4,8 @@
 test-quality ratchets. Part of [Veda](https://github.com/veda-hq/veda).
 
 ```sh
-npx @veda-hq/pariksha@0.5.2 <check> [flags]
-npx @veda-hq/pariksha@0.5.2 --version
+npx @veda-hq/pariksha@0.5.5 <check> [flags]
+npx @veda-hq/pariksha@0.5.5 --version
 ```
 
 Every check exits 0 when the repository passes, 1 when it refuses something
@@ -155,6 +155,72 @@ row that is not `` | `path` | bytes | ``, since nothing would enforce it.
 The table file is read on every check too, so it must budget itself: a row
 for its own path (relative to `--root`) is required.
 
+## `env-gate-switches`
+
+```sh
+pariksha env-gate-switches --config <file> [--mode staged|tree] [--root <dir>]
+```
+
+A hook that reads `PUSH_SKIP` from the environment has a bypass anyone can
+type: `PUSH_SKIP=1 git push`. This check refuses gate code that READS an
+environment variable whose name has a switch word (`X_SKIP`, `SKIP_X`,
+`X_PROBE_Y`): writing or deleting one is not a read. The JSON `--config`
+(relative to the root) says where gate code is:
+
+```json
+{
+  "gatePaths": ["^\\.husky/", "^scripts/", "^\\.github/workflows/"],
+  "notGateCode": ["\\.test\\.[cm]?[jt]sx?$", "(?:^|/)fixtures?/", "\\.md$"],
+  "notAGate": {
+    "SETUP_SKIP_MOBILE": { "files": ["scripts/setup.sh"], "reason": "installs no mobile toolchain; checks nothing" }
+  },
+  "words": ["SKIP", "PROBE"]
+}
+```
+
+- `gatePaths` (required) and `notGateCode` are path regexes: a file is gate
+  code when a gate path matches it and no `notGateCode` entry does.
+- `notAGate` allows a switch that turns off something other than a check,
+  in the files listed only, with the reason a reviewer reads; the same name
+  anywhere else is still refused.
+- `words` (default `SKIP` and `PROBE`) are upper-case words; a name made of
+  `_`-joined words, one of them a switch word, is a switch.
+- Shell (`.sh`, and every file under `.husky/`) is read as bash reads it:
+  single quotes, escapes, comments and quoted heredoc bodies expand nothing,
+  and a bare name bash reads is a read: in arithmetic (`(( X_SKIP ))`,
+  `let`, `-eq`, a subscript), `printenv X_SKIP`, and `-v X_SKIP` in `[ ]`,
+  `[[ ]]` or `test`. A variable the file initialises at the top level before
+  reading it is the script's own decision, not a read; one initialised in a
+  branch, loop, function, group, subshell, pipeline or the end of a `&&`
+  list, or self-defaulted (`X_SKIP="${X_SKIP:-0}"`), is.
+- TypeScript and JavaScript are read as a syntax tree, with a type checker
+  over the one file: dotted, bracketed, optional, destructured (nested too:
+  `const { env: { X_SKIP } } = process`) and `in` reads count, through
+  `process`, `globalThis.process`, `node:process` and any local bound to the
+  environment, with constant keys resolved (`env['X_' + 'SKIP']`); a mention
+  in a comment or string does not.
+- Python reads are `os.environ[…]`, `.get(…)`, `.setdefault(…)`, `.pop(…)`,
+  `'X' in` / `'X' not in os.environ`, the same on `os.environ.copy()` or
+  `dict(os.environ)`, and `os.getenv(…)`, with the bytes forms (`environb`,
+  `getenvb`): under `os` by any name, through `from os import environ as e`
+  / `getenv as g`, and through a name assigned one (`env = os.environ`,
+  `read = os.getenv`), outside strings and comments (f-string fields are
+  code). A key held in a variable is not resolved. Workflow YAML reads are
+  `$X`, `env.X` and `env['X']` outside comments.
+
+`tree` (the default) reads every tracked file in the working tree, skipping
+one deleted there; when every tracked gate file is deleted, nothing was read
+and it exits 2. `staged` (for a pre-commit hook) reads the files the index
+adds, copies, modifies, renames or changes the type of (a symlink replaced
+by a file), as the index holds them. In either mode, a repository with no
+tracked gate code exits 2, since the config would check nothing, and a gate
+file that is a symlink (in the index for staged, in the working tree for
+tree) exits 2: its text is a path, and its target goes unchecked. A gate
+file that cannot be read (one under a folder the check cannot open
+included), a git call that fails, or a failure while reading a file's code
+exits 2: an unread gate is never clean. Needs `typescript` only when a
+TypeScript or JavaScript file is gate code.
+
 ## `export-deletions`
 
 ```sh
@@ -185,3 +251,78 @@ renames, colour, external diff tools and textconv in a user's git config
 do not change what it reads. With no base, or when git cannot read the
 range (no merge base, a shallow clone), it exits 2: nothing was checked,
 so it is not a pass.
+
+## markdownlint rules
+
+```jsonc
+// .markdownlint-cli2.jsonc
+{
+  "customRules": ["@veda-hq/pariksha/markdownlint"],
+  "config": { "default": false, "pariksha-markdown": true }
+}
+```
+
+Not a check but a module: markdownlint custom rules for Markdown that reads
+fine as source and renders mangled, where no built-in rule fails it for that
+reason. `@veda-hq/pariksha/markdownlint` is an ES module whose default export
+is the rules array, which markdownlint-cli2's `customRules` loads by package
+name; `require()` of it returns the array too. Every rule carries the tag
+`pariksha-markdown`, so the config above turns on these rules and nothing
+else. They run on markdownlint's micromark tokens (`parser: "micromark"`)
+and import nothing. Most read prose only, skipping code blocks, HTML blocks
+and code spans; the fence and code-span rules read those,
+`pariksha-replacement-character` reads every line, and
+`pariksha-duplicate-adjacent-line` skips code and HTML blocks but compares
+whole lines, code spans included.
+
+| Rule | Fails |
+| ---- | ----- |
+| `pariksha-alert-marker-inline` | `> [!NOTE] body` on one line: GitHub renders the callout only with the marker alone |
+| `pariksha-link-space-before-paren` | `[text] (./a.md)`: the space renders the link as text (targets that look like a URL, path, anchor or file only; task boxes `[ ]` and `[x]` pass) |
+| `pariksha-code-span-crosses-line` | a code span that closes on a later line, or a path span ending in `/` continued in the next line's span |
+| `pariksha-fence-unclosed` | a code fence that never closes |
+| `pariksha-fence-empty` | a fence with nothing but blank lines in it |
+| `pariksha-fence-swallows-heading` | a `# Heading` inside a fence of a language where it cannot be code: the fence above lost its close |
+| `pariksha-table-row-orphaned` | a paragraph made only of `\| … \|` rows: a blank line cut them off their table |
+| `pariksha-duplicate-adjacent-line` | a line of ten or more characters, with a letter, repeating the previous non-blank prose line (table rows may repeat) |
+| `pariksha-replacement-character` | U+FFFD, bytes lost in an encoding round-trip |
+| `pariksha-emphasis-mangle` | `store*id`: a single `*` between letters, where `_` was re-read as emphasis |
+| `pariksha-dunder-mangle` | `**DEV**`: a formatter rewrote `__DEV__` as bold |
+| `pariksha-lettered-step-indent` | `b.` indented unlike the `a.` above it, so it renders under another parent |
+
+Options are lists, each replacing its default:
+
+| Option | Rule | Default |
+| ------ | ---- | ------- |
+| `alert_types` | `pariksha-alert-marker-inline` | `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION` (matched case-insensitively) |
+| `link_target_extensions` | `pariksha-link-space-before-paren` | `md`, `mdx`, `html`, `htm`, `ts`, `tsx`, `js`, `json`, `yaml`, `yml`, `png`, `svg`, `jpg`, `jpeg`, `pdf` |
+| `dunder_words` | `pariksha-dunder-mangle` | `DEV`, `proto`, `esModule`, `typename`: names never an English word in bold |
+| `no_hash_languages` | `pariksha-fence-swallows-heading` | `ts`, `tsx`, `typescript`, `js`, `jsx`, `javascript`, `json`, `jsonc`, `sql`, `css`, `swift`, `kotlin`, `java`, `go`, `rust`, `prisma` (matched case-insensitively; not `graphql` or `html`, where a `# ` line is a comment or text) |
+
+```jsonc
+{
+  "config": {
+    "default": false,
+    "pariksha-markdown": { "dunder_words": ["DEV", "proto", "esModule", "typename", "dirname"] },
+    "pariksha-fence-swallows-heading": { "no_hash_languages": ["ts", "py"] }
+  },
+  "customRules": ["@veda-hq/pariksha/markdownlint"]
+}
+```
+
+Options set under the tag reach every rule, so every rule accepts all four
+names. A rule's own key replaces the tag's object for that rule (markdownlint
+takes the last key that names a rule, whole), so above
+`pariksha-fence-swallows-heading` keeps the default `dunder_words`, which it
+does not read. The same goes for an option of one rule set under another
+rule's key: a rule cannot tell its own object from the tag's, so it accepts
+every name some rule reads. Otherwise a configuration markdownlint cannot have
+meant is refused, not ignored: an option name no rule reads (an array set as
+the configuration reaches the rules as its indexes, `"0"`, and is refused as
+such), a list option that is not a non-empty array of strings (to turn a rule
+off, set it to `false`), or an entry that could never match (an extension with
+its dot, a dunder word with its underscores, a language with a space). Each
+rule that reads the bad configuration throws, naming itself and the option, so
+markdownlint-cli2 reports up to twelve errors on line 1 of each file and the
+run fails; with `"severity": "warning"` in the configuration they are reported
+as warnings instead.

package/dist/cli.js

@@ -9,6 +9,7 @@ import { findDenied, hash, isText, parseDenyList } from "./boundary.js";
 import { DEFAULT_CONFIG, findGaps, formatGaps, listedPaths, parseConfig, treePaths } from "./coverage-by-type.js";
 import { checkBuild, checkPackage, checkVitest, formatViolations, loaderFailure, loadVitestExclude, missingConfigs, ownedBy, parseConfig as parseExemptions } from "./coverage-exemptions.js";
 import { checkBudgets } from "./doc-budgets.js";
+import { diskReads, formatReads, listFiles, needsTypescript, parseConfig as parseGateConfig, readerFor, readGate } from "./env-gate-switches.js";
 import { loadTypescript, typescriptLoaders } from "./typescript.js";
 import { checkExportDeletions, formatReport } from "./export-deletions.js";
 import { BASE_CANDIDATES, gitAt, gitAtTop, must, resolveBase, topOf } from "./git.js";
@@ -19,6 +20,7 @@ const USAGE = [
     '       pariksha coverage-by-type [--config <file>] [--files-from <file>|-] [--root <dir>]',
     '       pariksha coverage-exemptions --config <file> [--package <dir>] [--root <dir>]',
     '       pariksha doc-budgets --table <file> [--section <name>] [--root <dir>]',
+    '       pariksha env-gate-switches --config <file> [--mode staged|tree] [--root <dir>]',
     '       pariksha export-deletions [--base <ref>] [--root <dir>]',
     '       pariksha hash <word>',
     '       pariksha --version',
@@ -254,12 +256,73 @@ const coverageExemptions = (f, io) => {
         return 2;
     }
 };
+const envGateSwitches = (f, io) => {
+    const P = 'pariksha env-gate-switches:';
+    const configPath = f.get('--config');
+    const mode = f.get('--mode') ?? 'tree';
+    if (configPath === undefined || (mode !== 'staged' && mode !== 'tree')) {
+        io.err(USAGE);
+        return 2;
+    }
+    const dir = resolve(f.get('--root') ?? '.');
+    const root = topOf(dir);
+    if (root === undefined) {
+        io.err(`${P} ${dir} is not in a git repository`);
+        return 2;
+    }
+    let reader;
+    let words;
+    try {
+        const config = parseGateConfig(readFileSync(resolve(root, configPath), 'utf8'));
+        reader = readerFor(config);
+        words = config.words;
+    }
+    catch (e) {
+        io.err(`${P} ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+    const reads = (io.gateReads ?? diskReads)(root);
+    let result;
+    try {
+        const listed = listFiles(reads, mode).filter((l) => reader.isGateCode(l.file));
+        // A tree with no gate code is a config whose gatePaths match nothing (a
+        // typo): staged mode would pass every commit under it, so both refuse.
+        if (!(mode === 'tree' ? listed.length > 0 : listFiles(reads, 'tree').some((l) => reader.isGateCode(l.file)))) {
+            io.err(`${P} no tracked file is gate code under the config's gatePaths; nothing was checked, so this is not a pass`);
+            return 2;
+        }
+        const sources = listed.flatMap((entry) => {
+            const text = readGate(reads, mode, entry);
+            return text === undefined ? [] : [{ file: entry.file, text }];
+        });
+        if (mode === 'tree' && sources.length === 0) {
+            // Staged mode reads the index, which holds every file it lists.
+            io.err(`${P} every tracked gate file (${listed.length}) is gone from the working tree; nothing was checked, so this is not a pass`);
+            return 2;
+        }
+        const ts = sources.some((s) => needsTypescript(s.file)) ? (io.typescript ?? (() => loadTypescript(typescriptLoaders(root))))() : undefined;
+        if (typeof ts === 'string') {
+            io.err(`${P} ${ts}`);
+            return 2;
+        }
+        result = formatReads(sources.flatMap((s) => reader.findSwitchReads(s.file, s.text, ts)), words, sources.length, configPath);
+    }
+    catch (e) {
+        // An unread gate, or one the reader failed on, is unchecked, never clean.
+        io.err(`${P} could not read gate code, so it is unchecked: ${e.message}`);
+        return 2;
+    }
+    result.out.forEach(io.out);
+    result.err.forEach(io.err);
+    return result.ok ? 0 : 1;
+};
 const COMMANDS = {
     'coverage-exemptions': { allowed: ['--config', '--package', '--root'], run: coverageExemptions },
     'authority-citations': { allowed: ['--mode', '--authority', '--issue-prefix', '--adr-dir', '--root'], run: authorityCitations },
     boundary: { allowed: ['--root', '--deny'], run: boundary },
     'coverage-by-type': { allowed: ['--config', '--files-from', '--root'], run: coverageByType },
     'doc-budgets': { allowed: ['--table', '--section', '--root'], run: docBudgets },
+    'env-gate-switches': { allowed: ['--config', '--mode', '--root'], run: envGateSwitches },
     'export-deletions': { allowed: ['--base', '--root'], run: exportDeletions },
 };
 export const run = (args, io, version = ownVersion(), env = process.env) => {