@veda-hq/pariksha 0.5.3 → 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.3 <check> [flags]
-npx @veda-hq/pariksha@0.5.3 --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
@@ -251,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/markdownlint-rules.js

@@ -0,0 +1,335 @@
+// markdownlint custom rules for Markdown that reads fine as source and renders
+// mangled: a `> [!NOTE]` alert run onto its body line, a link broken by `] (`,
+// a fence that swallows the next section, a table split by a blank line,
+// `__DEV__` turned into bold "DEV". No markdownlint built-in rule fails these
+// for that reason, so each shape is one rule here, on markdownlint's own
+// micromark tokens. Every rule carries the tag `pariksha-markdown`, so
+//
+//   "config": { "default": false, "pariksha-markdown": true }
+//
+// turns on these rules and nothing else. The module's default export is the
+// rules array, as markdownlint-cli2's `customRules` loads it.
+//
+// The rule API's types are declared here rather than imported, so the package
+// depends on no markdownlint version.
+export const TAG = 'pariksha-markdown';
+/**
+ * The options, each a list, with their defaults. A rule reads its own; since
+ * options set under the tag reach every rule, a rule accepts the others'
+ * names too, and refuses only a name no rule here reads.
+ */
+export const DEFAULT_OPTIONS = {
+    /** `pariksha-alert-marker-inline`: the alert types GitHub renders as callouts. */
+    alert_types: ['NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION'],
+    /** `pariksha-link-space-before-paren`: file extensions that make `] (name.ext)` look like a link target. */
+    link_target_extensions: ['md', 'mdx', 'html', 'htm', 'ts', 'tsx', 'js', 'json', 'yaml', 'yml', 'png', 'svg', 'jpg', 'jpeg', 'pdf'],
+    /** `pariksha-dunder-mangle`: names whose `__name__` a formatter rewrites as `**name**`; never an English word in bold. */
+    dunder_words: ['DEV', 'proto', 'esModule', 'typename'],
+    /** `pariksha-fence-swallows-heading`: fence languages where a `# Heading` line cannot be code. */
+    no_hash_languages: ['ts', 'tsx', 'typescript', 'js', 'jsx', 'javascript', 'json', 'jsonc', 'sql', 'css', 'swift', 'kotlin', 'java', 'go', 'rust', 'prisma'],
+};
+/** What each option's entries must look like, and how the refusal says so. */
+const OPTION_SHAPES = {
+    alert_types: { pattern: /^[A-Za-z]+$/, says: 'letters only' },
+    link_target_extensions: { pattern: /^[A-Za-z0-9]+$/, says: 'letters and digits, without the dot' },
+    dunder_words: { pattern: /^(?!_)[\w$]+(?<!_)$/, says: 'an identifier without its surrounding underscores' },
+    no_hash_languages: { pattern: /^\S+$/, says: 'no whitespace' },
+};
+const isOptionName = (key) => Object.hasOwn(DEFAULT_OPTIONS, key);
+const describe = (value) => {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    return typeof value === 'object' ? 'an object' : `a ${typeof value}`;
+};
+/**
+ * The rule's configuration as markdownlint passes it, checked: an object whose
+ * every key is an option of this module. A key no rule here reads throws,
+ * which fails the lint run with the message. A key another rule reads is
+ * accepted, since options set under the tag reach every rule and a rule
+ * cannot tell the tag's object from its own. markdownlint always passes an
+ * object (a string or number becomes `{}`, an array its indexes as keys); the
+ * non-object refusal is for a caller that runs a rule directly.
+ */
+export const readConfig = (rule, config) => {
+    if (config === undefined)
+        return {};
+    if (typeof config !== 'object' || config === null || Array.isArray(config))
+        throw new Error(`${rule}: its configuration must be true, false or an object of options; got ${describe(config)}`);
+    for (const key of Object.keys(config)) {
+        if (!isOptionName(key))
+            throw new Error(`${rule}: unknown option "${key}"; the options are ${Object.keys(DEFAULT_OPTIONS).join(', ')}`);
+    }
+    return config;
+};
+/** One list option: its default when unset, else a non-empty array of well-formed strings. */
+export const listOption = (rule, config, name) => {
+    const value = readConfig(rule, config)[name];
+    if (value === undefined)
+        return DEFAULT_OPTIONS[name];
+    const shape = OPTION_SHAPES[name];
+    if (!Array.isArray(value) || value.length === 0)
+        throw new Error(`${rule}: option "${name}" must be a non-empty array of strings (to turn the rule off, set it to false); got ${describe(value)}`);
+    for (const entry of value) {
+        if (typeof entry !== 'string' || !shape.pattern.test(entry))
+            throw new Error(`${rule}: option "${name}" holds ${describe(entry)}; each entry must be a string of ${shape.says}`);
+    }
+    return value;
+};
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\/-]/g, '\\$&');
+/** Every token, depth first, in document order. */
+export const walk = (tokens) => {
+    const out = [];
+    const visit = (list) => {
+        for (const token of list) {
+            out.push(token);
+            visit(token.children);
+        }
+    };
+    visit(tokens);
+    return out;
+};
+const CODE_BLOCKS = new Set(['codeFenced', 'codeIndented', 'htmlFlow']);
+/**
+ * The document as rules see prose: lines inside code blocks and HTML blocks
+ * are null, and on every other line each inline code span is blanked out.
+ */
+export const proseLines = (params) => {
+    const lines = [...params.lines];
+    const all = walk(params.parsers.micromark.tokens);
+    for (const token of all) {
+        if (token.type !== 'codeText')
+            continue;
+        for (let line = token.startLine; line <= token.endLine; line += 1) {
+            const text = lines[line - 1] ?? '';
+            const from = line === token.startLine ? token.startColumn - 1 : 0;
+            const to = line === token.endLine ? token.endColumn - 1 : text.length;
+            lines[line - 1] = text.slice(0, from) + ' '.repeat(to - from) + text.slice(to);
+        }
+    }
+    const prose = lines;
+    for (const token of all) {
+        if (!CODE_BLOCKS.has(token.type))
+            continue;
+        for (let line = token.startLine; line <= token.endLine; line += 1)
+            prose[line - 1] = null;
+    }
+    return prose;
+};
+const rule = (name, description, check) => ({
+    names: [`pariksha-${name}`],
+    description,
+    tags: [TAG],
+    parser: 'micromark',
+    function: check,
+});
+/** An alert marker followed, on its own line, by more than whitespace. */
+const alertPattern = (types) => new RegExp(`^\\s*(?:>\\s*)+\\[!(?:${types.map(escapeRegExp).join('|')})\\][ \\t]*\\S`, 'i');
+/**
+ * `[text] (target)`: the space turns a link into literal text. Only targets
+ * that look like a link (URL, path, anchor, file) count, so prose such as
+ * "[1, 2] (sorted)" stays legal.
+ */
+const linkSpacePattern = (extensions) => new RegExp(String.raw `\[[^\]]*\][ \t]+\((?:https?:\/\/|mailto:|\.{0,2}\/|#|[\w./-]+\.(?:${extensions.map(escapeRegExp).join('|')})\b)`, 'g');
+/** A letter, one `*`, a letter: what `store_id` becomes once `_` is re-read as emphasis. */
+const EMPHASIS_MANGLE = /(?<=[A-Za-z])\*(?=[A-Za-z])/;
+/** `**name**` for a dunder name a formatter re-read as `__bold__` and rewrote. */
+const dunderPattern = (words) => new RegExp(`\\*\\*(${words.map(escapeRegExp).join('|')})\\*\\*`, 'g');
+const HEADING = /^#{1,6}\s+\S/;
+const PIPE_ROW = /^\s*\|.*\|\s*$/;
+const LETTERED_STEP = /^(\s*)(?:[-*+]\s+)?([a-z])[.)]\s+\S/;
+const childrenOf = (token, type) => token.children.filter((child) => child.type === type);
+const fences = (params) => walk(params.parsers.micromark.tokens).filter((t) => t.type === 'codeFenced');
+const alertMarkerInline = rule('alert-marker-inline', 'Alert marker shares its line with content', (params, onError) => {
+    const alert = alertPattern(listOption('pariksha-alert-marker-inline', params.config, 'alert_types'));
+    proseLines(params).forEach((line, index) => {
+        if (line !== null && alert.test(line)) {
+            onError({
+                lineNumber: index + 1,
+                detail: 'GitHub renders `> [!TYPE]` as a callout only alone on its line; put the body on the next `>` line',
+            });
+        }
+    });
+});
+const linkSpaceBeforeParen = rule('link-space-before-paren', 'Space between `]` and `(` breaks a link', (params, onError) => {
+    const linkSpace = linkSpacePattern(listOption('pariksha-link-space-before-paren', params.config, 'link_target_extensions'));
+    proseLines(params).forEach((line, index) => {
+        if (line === null)
+            return;
+        for (const match of line.matchAll(linkSpace)) {
+            const label = match[0].slice(1, match[0].indexOf(']')).trim();
+            // `- [ ] (optional)` and `- [x] (done)` are task boxes, not links.
+            if (label === '' || label.toLowerCase() === 'x')
+                continue;
+            onError({ lineNumber: index + 1, detail: 'write `[text](target)`; with the space it renders as text' });
+        }
+    });
+});
+const codeSpanCrossesLine = rule('code-span-crosses-line', 'Code span broken across a line', (params, onError) => {
+    readConfig('pariksha-code-span-crosses-line', params.config);
+    const spans = walk(params.parsers.micromark.tokens).filter((t) => t.type === 'codeText');
+    for (const span of spans) {
+        if (span.endLine !== span.startLine) {
+            onError({
+                lineNumber: span.startLine,
+                detail: `the span closes ${span.endLine - span.startLine} line(s) later; the line break renders as a space inside it`,
+            });
+            continue;
+        }
+        // One path wrapped into two spans, `a/b/` then `c.ts` on the next line,
+        // renders as "a/b/ c.ts": a path nobody can copy.
+        const rest = (params.lines[span.startLine - 1] ?? '').slice(span.endColumn - 1);
+        if (rest.trim() !== '' || !span.text.replace(/`+$/, '').trimEnd().endsWith('/'))
+            continue;
+        // Document order: the first span on the next line is its leftmost.
+        const following = spans.find((t) => t.startLine === span.startLine + 1);
+        if (following !== undefined && (params.lines[following.startLine - 1] ?? '').slice(0, following.startColumn - 1).trim() === '') {
+            onError({
+                lineNumber: span.startLine,
+                detail: "a path span ends in `/` at the line break and goes on in the next line's span; join them",
+            });
+        }
+    }
+});
+const fenceUnclosed = rule('fence-unclosed', 'Code fence never closes', (params, onError) => {
+    readConfig('pariksha-fence-unclosed', params.config);
+    for (const fence of fences(params)) {
+        if (childrenOf(fence, 'codeFencedFence').length < 2)
+            onError({ lineNumber: fence.startLine, detail: 'everything after it renders as code' });
+    }
+});
+const fenceEmpty = rule('fence-empty', 'Empty code fence', (params, onError) => {
+    readConfig('pariksha-fence-empty', params.config);
+    for (const fence of fences(params)) {
+        const body = childrenOf(fence, 'codeFlowValue');
+        if (body.every((value) => value.text.trim() === '')) {
+            onError({ lineNumber: fence.startLine, detail: 'renders as a blank code block: a stray or orphan fence?' });
+        }
+    }
+});
+const fenceSwallowsHeading = rule('fence-swallows-heading', 'Markdown heading inside a code fence', (params, onError) => {
+    const languages = new Set(listOption('pariksha-fence-swallows-heading', params.config, 'no_hash_languages').map((lang) => lang.toLowerCase()));
+    for (const fence of fences(params)) {
+        const open = childrenOf(fence, 'codeFencedFence')[0];
+        const info = open === undefined ? undefined : childrenOf(open, 'codeFencedFenceInfo')[0];
+        if (info === undefined)
+            continue;
+        const lang = info.text.toLowerCase();
+        if (!languages.has(lang))
+            continue;
+        const heading = childrenOf(fence, 'codeFlowValue').find((value) => HEADING.test(value.text));
+        if (heading !== undefined) {
+            onError({
+                lineNumber: heading.startLine,
+                detail: `a ${lang} fence opened ${heading.startLine - fence.startLine} line(s) above holds this heading: it is missing its close`,
+            });
+        }
+    }
+});
+const tableRowOrphaned = rule('table-row-orphaned', 'Table row cut off from its table', (params, onError) => {
+    readConfig('pariksha-table-row-orphaned', params.config);
+    const paragraphs = walk(params.parsers.micromark.tokens).filter((t) => t.type === 'paragraph');
+    for (const paragraph of paragraphs) {
+        if (paragraph.text.split('\n').every((row) => PIPE_ROW.test(row))) {
+            onError({
+                lineNumber: paragraph.startLine,
+                detail: 'pipe rows with no header render as text: a blank line split the table; keep its rows together',
+            });
+        }
+    }
+});
+/** Ten characters and a letter: a line whose repeat is a mistake. */
+const meaningful = (line) => line.length >= 10 && /[A-Za-z]/.test(line);
+const duplicateAdjacentLine = rule('duplicate-adjacent-line', 'Line repeats the one before it', (params, onError) => {
+    readConfig('pariksha-duplicate-adjacent-line', params.config);
+    let previous = null;
+    proseLines(params).forEach((line, index) => {
+        if (line === null) {
+            previous = null;
+            return;
+        }
+        const text = (params.lines[index] ?? '').trim();
+        if (text === '')
+            return;
+        // Table rows repeat by design (templates, matrices).
+        if (!PIPE_ROW.test(text) && meaningful(text) && previous?.text === text) {
+            onError({ lineNumber: index + 1, detail: `identical to the line ${index + 1 - previous.line} above` });
+        }
+        previous = { text, line: index + 1 };
+    });
+});
+const replacementCharacter = rule('replacement-character', 'U+FFFD replacement character', (params, onError) => {
+    readConfig('pariksha-replacement-character', params.config);
+    params.lines.forEach((line, index) => {
+        if (line.includes('�'))
+            onError({ lineNumber: index + 1, detail: 'bytes were lost in an encoding round-trip' });
+    });
+});
+const emphasisMangle = rule('emphasis-mangle', 'Identifier lost its underscore to emphasis', (params, onError) => {
+    readConfig('pariksha-emphasis-mangle', params.config);
+    proseLines(params).forEach((line, index) => {
+        if (line !== null && EMPHASIS_MANGLE.test(line)) {
+            onError({ lineNumber: index + 1, detail: 'a single `*` between two letters (`store*id`): put the identifier in a code span' });
+        }
+    });
+});
+const dunderMangle = rule('dunder-mangle', 'Dunder identifier rewritten as bold', (params, onError) => {
+    const dunder = dunderPattern(listOption('pariksha-dunder-mangle', params.config, 'dunder_words'));
+    proseLines(params).forEach((line, index) => {
+        if (line === null)
+            return;
+        for (const match of line.matchAll(dunder)) {
+            const word = match[1] ?? '';
+            onError({ lineNumber: index + 1, detail: `renders as bold "${word}"; the identifier is \`__${word}__\` in a code span` });
+        }
+    });
+});
+const letteredStepIndent = rule('lettered-step-indent', 'Lettered step indented unlike its sibling', (params, onError) => {
+    readConfig('pariksha-lettered-step-indent', params.config);
+    let last = null;
+    proseLines(params).forEach((line, index) => {
+        if (line === null || HEADING.test(line)) {
+            last = null;
+            return;
+        }
+        const step = LETTERED_STEP.exec(line);
+        if (step === null) {
+            // Text at or left of the last step's indent ends its list, so a later
+            // `b.` belongs to another list; a deeper line continues it.
+            const lead = line.length - line.trimStart().length;
+            if (line.trim() !== '' && last !== null && lead <= last.indent)
+                last = null;
+            return;
+        }
+        const indent = (step[1] ?? '').length;
+        const letter = (step[2] ?? '').charCodeAt(0);
+        if (last !== null && letter === last.letter + 1 && indent !== last.indent) {
+            onError({
+                lineNumber: index + 1,
+                detail: `indented ${indent}, its sibling ${index + 1 - last.line} line(s) above ${last.indent}: it renders under a different parent`,
+            });
+        }
+        last = { letter, indent, line: index + 1 };
+    });
+});
+export const RULES = [
+    alertMarkerInline,
+    linkSpaceBeforeParen,
+    codeSpanCrossesLine,
+    fenceUnclosed,
+    fenceEmpty,
+    fenceSwallowsHeading,
+    tableRowOrphaned,
+    duplicateAdjacentLine,
+    replacementCharacter,
+    emphasisMangle,
+    dunderMangle,
+    letteredStepIndent,
+];
+export default RULES;
+// `require()` of this ES module returns the rules array itself, as a CommonJS
+// rules module would, rather than its namespace.
+export { RULES as 'module.exports' };

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@veda-hq/pariksha",
-  "version": "0.5.3",
-  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. Checks: authority-citations, boundary, coverage-by-type, coverage-exemptions, doc-budgets, env-gate-switches, export-deletions.",
+  "version": "0.5.5",
+  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. Checks: authority-citations, boundary, coverage-by-type, coverage-exemptions, doc-budgets, env-gate-switches, export-deletions. Also markdownlint rules for Markdown that renders mangled: @veda-hq/pariksha/markdownlint.",
   "keywords": [
     "repository checks",
     "lint",
     "boundary",
     "ci",
-    "coding agents"
+    "coding agents",
+    "markdownlint"
   ],
   "license": "MIT",
   "type": "module",
@@ -27,6 +28,11 @@
   "bin": {
     "pariksha": "dist/cli.js"
   },
+  "exports": {
+    "./markdownlint": "./dist/markdownlint-rules.js",
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist"
   ],
@@ -46,7 +52,7 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json",
     "test": "node --test --experimental-test-coverage --test-coverage-lines=95 --test-coverage-functions=95 --test-coverage-branches=90 --test-coverage-exclude=src/**/*.test.ts src/**/*.test.ts",
-    "smoke": "node dist/cli.js --version && node dist/cli.js boundary --root ../..",
+    "smoke": "node dist/cli.js --version && node dist/cli.js boundary --root ../.. && node --input-type=module -e \"import { createRequire } from 'node:module'; import { pathToFileURL } from 'node:url'; const id = '@veda-hq/pariksha/markdownlint'; const req = createRequire(process.cwd() + '/'); const required = req(id); const imported = (await import(pathToFileURL(req.resolve(id, { paths: [process.cwd()] })).href)).default; if (!Array.isArray(required) || required !== imported || required.length !== 12) throw new Error(id + ' does not load as markdownlint-cli2 loads it');\"",
     "check": "pnpm typecheck && pnpm test && pnpm build && pnpm smoke"
   }
 }