@veda-hq/pariksha 0.5.13 → 0.5.14

package/dist/doc-scripts.js

@@ -0,0 +1,224 @@
+// DOC-DRIFT-02, documented scripts: a `pnpm <script>` a doc shows exists, in
+// the scope the doc runs it from, and a verification step does not run a
+// script that changes the tree it is meant to check (`lint` auto-fixes:
+// `lint:ci` is the check). A step that names a missing script looks like a
+// check and runs nothing.
+import { readdirSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { codeSpans as markdownCodeSpans } from "./doc-references.js";
+import { isRecord } from "./registry-ratchet.js";
+import { maskQuoted, stripComment } from "./shell-text.js";
+/**
+ * Executables in `node_modules/.bin`. THROWS rather than returning a
+ * wildcard: a missing install that let every name pass would print a pass
+ * while scanning nothing.
+ */
+export const binNames = (root) => {
+    const dir = join(root, 'node_modules', '.bin');
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        throw new Error(`cannot read ${dir}; install the dependencies before this check`);
+    }
+};
+/**
+ * Every manifest the config lists that exists. One that does not parse would
+ * silently shrink the known-script set, so it fails loud instead.
+ */
+const readManifests = (manifests, read) => manifests.flatMap((path) => {
+    const text = read(path);
+    if (text === undefined)
+        return [];
+    let pkg;
+    try {
+        pkg = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${path} is not valid JSON — cannot determine which scripts exist`);
+    }
+    const name = isRecord(pkg) && typeof pkg['name'] === 'string' ? pkg['name'] : undefined;
+    const raw = isRecord(pkg) ? pkg['scripts'] : undefined;
+    const scripts = {};
+    if (isRecord(raw))
+        for (const [key, body] of Object.entries(raw))
+            scripts[key] = String(body);
+    return [{ scope: posix.dirname(path), name, scripts }];
+});
+/** A manifest's scope keys: its directory, and its package name if any. */
+const scopeKeys = (manifest) => (manifest.name === undefined ? [manifest.scope] : [manifest.scope, manifest.name]);
+/** Every name `pnpm <name>` can resolve to: a script in any listed manifest, or an executable in `node_modules/.bin`. */
+export const definedScripts = (root, manifests, read) => new Set([...binNames(root), ...readManifests(manifests, read).flatMap((manifest) => Object.keys(manifest.scripts))]);
+/**
+ * Scripts per scope, because `pnpm foo` does not resolve `foo` from a
+ * workspace. Keyed by both the workspace directory and the package name, as
+ * `--filter` takes either. Bins resolve in every scope: pnpm puts the same
+ * hoisted `.bin` on PATH for a filtered command.
+ */
+export const scriptScopes = (root, manifests, read) => {
+    const scopes = new Map();
+    const bins = binNames(root);
+    for (const manifest of readManifests(manifests, read)) {
+        const names = new Set([...Object.keys(manifest.scripts), ...bins]);
+        for (const key of scopeKeys(manifest))
+            scopes.set(key, names);
+    }
+    return scopes;
+};
+export const scriptBodies = (manifests, read) => {
+    const scripts = new Map();
+    const scopeDirs = new Map();
+    for (const manifest of readManifests(manifests, read)) {
+        const bodies = new Map(Object.entries(manifest.scripts));
+        for (const key of scopeKeys(manifest)) {
+            scripts.set(key, bodies);
+            scopeDirs.set(key, manifest.scope);
+        }
+    }
+    return { scripts, scopeDirs };
+};
+/** Half-open [start, end) ranges of every inline code span on a line, between its delimiters. */
+export const spanRanges = (line) => markdownCodeSpans(line).map((span) => [span.start, span.end]);
+const FENCE_OPEN = /^( {0,3})(`{3,}|~{3,})(.*)$/;
+/**
+ * Each line's place relative to fenced code blocks, by CommonMark's rule: an
+ * opening fence is three or more backticks or tildes indented at most three
+ * spaces (a backtick fence's info string has no backtick); it closes at a
+ * fence of the same character, at least as long, with nothing after it but
+ * spaces; an unclosed fence runs to the end.
+ */
+export const fenceRoles = (lines) => {
+    const roles = [];
+    let fence = null;
+    for (const raw of lines) {
+        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+        if (fence === null) {
+            const open = FENCE_OPEN.exec(line);
+            const marker = open?.[2] ?? '';
+            if (open !== null && !(marker.startsWith('`') && String(open[3]).includes('`'))) {
+                fence = { char: marker.charAt(0), length: marker.length };
+                roles.push('fence');
+            }
+            else {
+                roles.push('prose');
+            }
+            continue;
+        }
+        const close = /^ {0,3}(`+|~+)[ \t]*$/.exec(line)?.[1];
+        if (close !== undefined && close.charAt(0) === fence.char && close.length >= fence.length) {
+            fence = null;
+            roles.push('fence');
+        }
+        else {
+            roles.push('code');
+        }
+    }
+    return roles;
+};
+/** pnpm's own subcommands, which are not package scripts. */
+const BUILTIN = new Set([
+    'install',
+    'add',
+    'remove',
+    'exec',
+    'dlx',
+    'why',
+    'audit',
+    'list',
+    'outdated',
+    'update',
+    'publish',
+    'pack',
+    'link',
+    'patch',
+    'store',
+    'config',
+    'approve-builds',
+    'rebuild',
+    'prune',
+    'setup',
+    'licenses',
+    'deploy',
+    'env',
+    'init',
+    'create',
+    'run',
+    'help',
+    'self-update',
+    'doctor',
+    'root',
+    'bin',
+    'fetch',
+    'import',
+    'unlink',
+    'dedupe',
+    'cache',
+]);
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** What may precede `pnpm` for it to start a command: nothing, a separator, a prompt, env assignments, or a wrapper. */
+export const commandStart = (wrappers) => new RegExp(`(?:^|&&|\\|\\||;|\\||\\$|\\(|\\b(?:${['exec', ...wrappers.map(escapeRegExp), 'time', 'env', 'then', 'do'].join('|')})|\\s--)\\s*(?:[A-Z_][A-Z0-9_]*=\\S*\\s+)*$`);
+/** The documented-script rules over `files`; `scopes` judges where each resolves. */
+export const findScriptProblems = (config, files, defined, scopes, read) => {
+    const problems = [];
+    const start = commandStart(config.scripts.wrappers);
+    // `pnpm run foo`, `pnpm foo`, `pnpm --filter x foo`; not `npx`, which
+    // resolves from the registry. The `--filter` target is captured: a filtered
+    // command resolves in another scope.
+    const invocation = /\bpnpm\s+(?:run\s+)?(?:--filter[= ](\S+)\s+)?([a-z][a-z0-9:-]*)/g;
+    for (const relative of files) {
+        const content = read(relative);
+        if (content === undefined)
+            continue;
+        const lines = content.split('\n');
+        const roles = fenceRoles(lines);
+        lines.forEach((line, index) => {
+            const role = roles[index];
+            // A fence line itself carries no command; its info string is a label.
+            if (role === 'fence' || config.exemptMarker.test(line))
+                return;
+            const inFence = role === 'code';
+            const spans = inFence ? null : spanRanges(line);
+            // A shell comment in a fence is prose; a `#` inside quotes or escaped starts none.
+            const text = inFence ? stripComment(line) : line;
+            // A fence line is shell: a quoted separator starts no command, so the
+            // start is judged in the quote-masked line. Prose is not shell.
+            const code = inFence ? maskQuoted(text) : text;
+            for (const match of text.matchAll(invocation)) {
+                const filter = match[1];
+                const script = String(match[2]);
+                if (BUILTIN.has(script))
+                    continue;
+                // Only text the author marked as code counts, and all of the invocation must be in it.
+                const span = spans === null ? [0, text.length] : spans.find(([a, b]) => match.index >= a && match.index + match[0].length <= b);
+                if (span === undefined)
+                    continue;
+                // `pnpm dev:*` and `pnpm <script>` name a family, not a script.
+                if (/^[*<]/.test(text.slice(match.index + match[0].length)))
+                    continue;
+                // Only a command's start runs anything: `using pnpm v11` in a quoted log line is output.
+                if (!start.test(code.slice(span[0], match.index)))
+                    continue;
+                const report = (reason) => {
+                    problems.push({ file: relative, line: index + 1, script, reason });
+                };
+                if (!defined.has(script)) {
+                    report(`no workspace defines a \`${script}\` script — this step runs nothing`);
+                    continue;
+                }
+                // Existing somewhere is not resolving where the doc runs it: an unknown
+                // --filter target is not this check's to adjudicate.
+                const scope = scopes.get(filter ?? '.');
+                if (scope !== undefined && !scope.has(script)) {
+                    report(filter === undefined
+                        ? `\`${script}\` is not a root script — \`pnpm ${script}\` resolves the root manifest, so this needs \`--filter\``
+                        : `\`${script}\` is not a script of \`${filter}\` — the filter names a workspace that does not define it`);
+                    continue;
+                }
+                const safer = config.scripts.mutating.get(script);
+                if (safer !== undefined && config.scripts.verification.test(line))
+                    report(`\`${script}\` MUTATES the tree (it auto-fixes) — a verification step must use \`${safer}\``);
+            }
+        });
+    }
+    return problems;
+};

package/dist/shell-text.js

@@ -0,0 +1,193 @@
+// Just enough shell lexing for the commands a doc shows: a `#` comment cut
+// off, and quoted text masked so an operator inside a string splits nothing.
+// Not a parser; each caller says what it reads.
+/**
+ * The characters of `code` from `start`, each with its index. Every scanner
+ * walks this bounded sequence, skipping indexes below the point a token it
+ * consumed ends at, so no scan runs past the end or loops forever. Lazy: a
+ * scan that stops early never builds the rest.
+ */
+function* charsFrom(code, start) {
+    for (let index = start; index < code.length; index += 1)
+        yield [index, code.charAt(index)];
+}
+/** A line continued by backslash-newline: an odd run of trailing backslashes. */
+const CONTINUATION = /(?:^|[^\\])(?:\\\\)*\\$/;
+/**
+ * Whether `#` at `at` starts a word (a comment), not `$#`, `a#b`, `${#x}` or
+ * `{#a,b}`: the line starts there, or a blank, `;` or `(` precedes it.
+ */
+const startsWord = (line, at) => /(?:^|[\s;(])$/.test(line.slice(0, at));
+/**
+ * Where an unquoted `#` comment starts in `line` (-1 if none). A `$(…)`
+ * inside double quotes has its own quotes, so `"$(printf "%s" " #")"` holds
+ * no comment.
+ */
+const commentAt = (line) => {
+    const stack = [];
+    let resume = 0;
+    for (const [at, char] of charsFrom(line, 0)) {
+        if (at < resume)
+            continue;
+        const top = stack.at(-1);
+        if (top === "'") {
+            if (char === "'")
+                stack.pop();
+        }
+        else if (char === '\\') {
+            resume = at + 2;
+        }
+        else if (top === '"') {
+            if (char === '"')
+                stack.pop();
+            if (line.startsWith('$(', at)) {
+                stack.push(')');
+                resume = at + 2;
+            }
+        }
+        else if (char === '#' && startsWord(line, at)) {
+            // At top level or inside a quoted `$(…)` body, the rest is a comment.
+            return at;
+        }
+        else if (char === '"' || char === "'") {
+            stack.push(char);
+        }
+        else if (top === ')' && char === '(') {
+            stack.push(')');
+        }
+        else if (top === ')' && char === ')') {
+            stack.pop();
+        }
+    }
+    return -1;
+};
+/**
+ * `line` without a `#` comment that starts a word outside quotes, trailing
+ * blanks trimmed, except an escaped one: `echo ok \ # note` keeps `\ `,
+ * which is no continuation.
+ */
+export const stripComment = (line) => {
+    const at = commentAt(line);
+    if (at === -1)
+        return line;
+    const trimmed = line.slice(0, at).trimEnd();
+    return CONTINUATION.test(trimmed) ? `${trimmed} ` : trimmed;
+};
+/** Whether `$(` at `at` opens a command substitution (`$((` is arithmetic). */
+const opensSubstitution = (code, at) => code.startsWith('$(', at) && !code.startsWith('$((', at);
+/**
+ * Outside quotes, `\` makes the next character literal. An escaped operator,
+ * quote, `$` or backtick is blanked with its backslash; any other stays as
+ * written. Returns the index past the escape.
+ */
+const maskEscape = (code, at, out) => {
+    if (/^\\[;&|()<>`$"']/.test(code.slice(at)))
+        out.fill(' ', at, at + 2);
+    return at + 2;
+};
+/** Blanks a single-quoted body from `start`; returns the index past its close. */
+const maskSingle = (code, start, out) => {
+    const close = code.indexOf("'", start);
+    const end = close === -1 ? code.length : close;
+    out.fill(' ', start, end);
+    return end + 1;
+};
+/** What the substitution skippers return when the body never closes. */
+const NEVER_CLOSES = Number.POSITIVE_INFINITY;
+/** A case pattern just before its `)`: after `in`, `;;` or a line start. */
+const CASE_PATTERN_BEFORE = /(?:^|\bin|;;|\n)\s*[^\s;&|()]+(?:\s*\|\s*[^\s;&|()]+)*\s*$/;
+/** Whether a `)` after `before` ends a pattern of a `case` open in `before`. */
+const closesCasePattern = (before) => {
+    const cases = before.match(/\bcase\b/g)?.length ?? 0;
+    const ends = before.match(/\besac\b/g)?.length ?? 0;
+    return cases > ends && CASE_PATTERN_BEFORE.test(before);
+};
+/** Leaves a backtick substitution's body as code, masking the strings inside it; `open` is the opening backtick. */
+const skipBacktick = (code, open, out) => {
+    let resume = open;
+    for (const [at, char] of charsFrom(code, open + 1)) {
+        if (at < resume)
+            continue;
+        if (char === '`')
+            return at + 1;
+        if (char === '\\')
+            resume = maskEscape(code, at, out);
+        else if (char === "'")
+            resume = maskSingle(code, at + 1, out);
+        else if (char === '"')
+            resume = maskDouble(code, at + 1, out);
+    }
+    return NEVER_CLOSES;
+};
+/** Leaves a `$( … )` body as code, masking strings inside it; returns the index past `)`. */
+const skipSubstitution = (code, start, out) => {
+    let depth = 1;
+    let resume = start;
+    for (const [at, char] of charsFrom(code, start)) {
+        if (at < resume)
+            continue;
+        if (char === '\\')
+            resume = maskEscape(code, at, out);
+        else if (char === "'")
+            resume = maskSingle(code, at + 1, out);
+        else if (char === '"')
+            resume = maskDouble(code, at + 1, out);
+        else if (char === '(')
+            depth += 1;
+        else if (char === ')' && !closesCasePattern(code.slice(start, at))) {
+            // A case arm's `)` (`$(case $x in a) …; esac)`) closes nothing.
+            depth -= 1;
+            if (depth === 0)
+                return at + 1;
+        }
+    }
+    return NEVER_CLOSES;
+};
+/**
+ * Blanks a double-quoted body from `start`, leaving `$(…)` and backtick
+ * substitutions as code; returns the index past the closing quote.
+ */
+function maskDouble(code, start, out) {
+    let resume = start;
+    for (const [at, char] of charsFrom(code, start)) {
+        if (at < resume)
+            continue;
+        if (char === '"')
+            return at + 1;
+        if (char === '\\') {
+            out.fill(' ', at, at + 2);
+            resume = at + 2;
+        }
+        else if (opensSubstitution(code, at)) {
+            resume = skipSubstitution(code, at + 2, out);
+        }
+        else if (char === '`') {
+            resume = skipBacktick(code, at, out);
+        }
+        else {
+            out[at] = ' ';
+        }
+    }
+    return code.length;
+}
+/**
+ * Blanks the contents of quoted strings, keeping every index in place so a
+ * position found in the masked text is the same position in `code`:
+ * `"a b"` → `"   "`. A command substitution inside double quotes runs, so
+ * it stays visible; an escaped operator or quote is blanked too.
+ */
+export const maskQuoted = (code) => {
+    const out = code.split('');
+    let resume = 0;
+    for (const [index, char] of charsFrom(code, 0)) {
+        if (index < resume)
+            continue;
+        if (char === '\\')
+            resume = maskEscape(code, index, out);
+        else if (char === "'")
+            resume = maskSingle(code, index + 1, out);
+        else if (char === '"')
+            resume = maskDouble(code, index + 1, out);
+    }
+    return out.join('');
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@veda-hq/pariksha",
-  "version": "0.5.13",
-  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. Checks: authority-citations, boundary, codec-registry, coverage-by-type, coverage-exemptions, doc-budgets, enforcement-claims, env-gate-switches, export-deletions, fault-injection-registry, required-settings. Also markdownlint rules for Markdown that renders mangled: @veda-hq/pariksha/markdownlint.",
+  "version": "0.5.14",
+  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. Checks: authority-citations, boundary, codec-registry, coverage-by-type, coverage-exemptions, doc-budgets, doc-references, enforcement-claims, env-gate-switches, export-deletions, fault-injection-registry, required-settings. Also markdownlint rules for Markdown that renders mangled: @veda-hq/pariksha/markdownlint.",
   "keywords": [
     "repository checks",
     "lint",
@@ -56,6 +56,7 @@
   "devDependencies": {
     "@types/node": "24.19.2",
     "eslint": "9.39.1",
+    "mdast-util-from-markdown": "2.0.3",
     "typescript": "5.9.3"
   },
   "scripts": {