@veda-hq/pariksha 0.5.13 → 0.5.17

package/dist/doc-commands.js

@@ -0,0 +1,187 @@
+// The commands a Markdown document shows (DOC-DRIFT-02): each simple command
+// in a shell fence or an inline code span, read into the words bash would
+// hand the program. doc-command-rules.ts judges them.
+import { posix } from 'node:path';
+import { codeSpans, isShellFence, scanMarkdown } from "./doc-references.js";
+import { maskQuoted, stripComment } from "./shell-text.js";
+/** A command word: what makes a code span or a bare fence line a command. */
+const COMMAND_HEAD = /^(?:cd\s+\S+\s*&&\s*)?(?:[A-Z_][A-Z0-9_]*=\S*\s+)*(?:pnpm|npx|node|tsx|python3?|bash|sh)\s/;
+/**
+ * In a fence declared as shell, a script path may itself be the command
+ * (`./scripts/x.ts --flag`). Elsewhere a lone path is a mention.
+ */
+const SCRIPT_HEAD = /^(?:[A-Z_][A-Z0-9_]*=\S*\s+)*\.{0,2}\/?[\w./-]+\.(?:ts|mjs|js|sh|py)(?:[\s;&|]|$)/;
+/** Fence info strings that declare a block as shell (a bare fence only may be). */
+const DECLARED_SHELL = new Set(['bash', 'sh', 'shell', 'zsh', 'console', 'terminal']);
+/** The value of digits a pattern already matched in base `radix`. */
+const digitsValue = (digits, radix) => {
+    let value = 0;
+    for (const digit of digits.toLowerCase())
+        value = value * radix + '0123456789abcdef'.indexOf(digit);
+    return value;
+};
+/** The named escapes of ANSI-C quoting. */
+const ANSI_C_NAMED = { a: '\u0007', b: '\b', e: '\u001b', E: '\u001b', f: '\f', n: '\n', r: '\r', t: '\t', v: '\v', '\\': '\\', "'": "'", '"': '"', '?': '?' };
+/**
+ * The value of a `$'…'` body, as bash decodes it: the named escapes, octal
+ * `\N` to `\NNN` (low eight bits), `\xH`/`\xHH`, `\uHHHH`, `\UHHHHHHHH` and
+ * `\cX` (X's low five bits); an unknown escape keeps its backslash, and the
+ * value ends at its first NUL.
+ */
+const ansiC = (body) => String(body
+    .replace(/\\(?:([0-7]{1,3})|x([\da-fA-F]{1,2})|u([\da-fA-F]{1,4})|U([\da-fA-F]{1,8})|c([^])|[^])/g, (escape, octal, x, u, bigU, control) => {
+    if (octal !== undefined)
+        return String.fromCharCode(digitsValue(octal, 8) & 0xff);
+    const hex = x ?? u ?? bigU;
+    if (hex !== undefined) {
+        const code = digitsValue(hex, 16);
+        // Past Unicode bash writes no character; keep the escape.
+        return code > 0x10ffff ? escape : String.fromCodePoint(code);
+    }
+    if (control !== undefined)
+        return String.fromCharCode(control.charCodeAt(0) & 0x1f);
+    return ANSI_C_NAMED[escape.slice(1)] ?? escape;
+})
+    .split('\0')[0]);
+/**
+ * Shell words of one simple command, as bash hands them to the program. A
+ * word runs to unquoted whitespace and joins its parts (`--mode="a b"` is one
+ * word): single quotes keep every character, double quotes every character
+ * but a backslash before `$`, `` ` ``, `"` or `\`, and outside quotes a
+ * backslash keeps the character after it. `$'…'` is ANSI-C quoting, its
+ * escapes decoded, and `$"…"` a double-quoted string. A quote that never
+ * closes stays a character (bash refuses the line). Expansions, operators and
+ * line continuations are the callers' or out of reach.
+ */
+export const shellWords = (text) => Array.from(text.matchAll(/(?:\$'(?:[^'\\]|\\[^])*'|'[^']*'|\$?"(?:[^"\\]|\\[^])*"|\\[^]|[^\s'"\\]|['"\\])+/g), ([word]) => Array.from(word.matchAll(/\$'((?:[^'\\]|\\[^])*)'|'([^']*)'|\$?"((?:[^"\\]|\\[^])*)"|\\([^])|([^])/g), (part) => (part[1] === undefined ? undefined : ansiC(part[1])) ?? part[2] ?? part[3]?.replace(/\\([$`"\\])/g, '$1') ?? part[4] ?? String(part[5])).join(''));
+/** Whether code ends in a backslash that escapes what follows: an odd run of them. */
+const continues = (code) => /(?:^|[^\\])(?:\\\\)*\\$/.test(code);
+const withoutCr = (line) => (line.endsWith('\r') ? line.slice(0, -1) : line);
+/** `code` without its outer blanks, but one a backslash escapes (`a\ `). */
+const trimCode = (code) => {
+    const trimmed = code.trim();
+    if (!continues(trimmed))
+        return trimmed;
+    const end = code.length - code.trimStart().length + trimmed.length;
+    return `${trimmed}${code.charAt(end)}`;
+};
+/**
+ * The simple commands of one shell line, as written: split at `&&`, `||`, `;`
+ * and `|` outside quotes and escapes (found in the quote-masked line, which
+ * keeps every index).
+ */
+export const simpleCommands = (line) => {
+    const masked = maskQuoted(line);
+    const commands = [];
+    let start = 0;
+    for (const match of masked.matchAll(/&&|\|\||;|\|/g)) {
+        commands.push(trimCode(line.slice(start, match.index)));
+        start = match.index + match[0].length;
+    }
+    commands.push(trimCode(line.slice(start)));
+    return commands;
+};
+/** Words after any leading `NAME=value` environment assignments. */
+export const withoutAssignments = (words) => {
+    const first = words.findIndex((word) => !/^[A-Z_][A-Z0-9_]*=/.test(word));
+    return first === -1 ? [] : words.slice(first);
+};
+/** The directory a `cd` command's words name: after bash's own options (`-L`, `-P`, `-e`, `-@`) and a `--`. `cd -` is no option. */
+const cdOperand = (words) => {
+    let at = 1;
+    while (/^-[LPe@]+$/.test(String(words[at])))
+        at += 1;
+    if (words[at] === '--')
+        at += 1;
+    return words[at];
+};
+/** Options of npx (npm exec) whose value is the next word, `-c`/`--call` among them. */
+export const NPX_VALUE_OPTIONS = new Set(['--package', '-p', '--cache', '--userconfig', '--shell', '--call', '-c', '--workspace', '-w']);
+/**
+ * The shell command an `npx -c '…'` runs, if `words` are one: the value of
+ * `-c`/`--call` after npx's other options. npm refuses a call with words
+ * after it, so `npx -c tsx x.ts` runs nothing.
+ */
+export const npxCall = (words) => {
+    if (words[0] !== 'npx')
+        return undefined;
+    let at = 1;
+    for (let word = words[at]; word?.startsWith('-') === true; word = words[at]) {
+        const [name, inline] = word.split(/=(.*)/s);
+        if (name === '--call' || name === '-c') {
+            const call = inline ?? words[at + 1];
+            const next = at + (inline === undefined ? 2 : 1);
+            // npm reads an empty call as none: its words run.
+            return call === '' || next < words.length ? undefined : call;
+        }
+        at += NPX_VALUE_OPTIONS.has(word) ? 2 : 1;
+    }
+    return undefined;
+};
+/** Every simple command shown in a Markdown document. */
+export const documentedCommands = (file, content, exemptMarker) => {
+    const commands = [];
+    /** Reads `text` from directory `from`, recording its commands when `shown`; returns the directory its `cd`s leave the shell in. */
+    const read = (line, text, fenced, from, shown) => {
+        let cwd = from;
+        for (const part of simpleCommands(text)) {
+            const words = withoutAssignments(shellWords(part));
+            const dir = words[0] === 'cd' ? cdOperand(words) : undefined;
+            if (dir !== undefined) {
+                // An absolute operand replaces the directory.
+                cwd = posix.normalize(posix.isAbsolute(dir) ? dir : posix.join(cwd, dir)).replace(/^\.$/, '');
+                continue;
+            }
+            // `npx -c '…'` runs its call's commands, each one judged; npm runs the
+            // call in a shell of its own, so a `cd` in it moves only the call's later commands.
+            const call = npxCall(words);
+            if (call !== undefined) {
+                read(line, call, fenced, cwd, shown);
+                continue;
+            }
+            if (shown && words.length > 0)
+                commands.push({ file, line, words, text: part, cwd, fenced });
+        }
+        return cwd;
+    };
+    const lines = scanMarkdown(content, exemptMarker);
+    // A fence's lines are one shell session: a `cd` on its own line moves the
+    // lines after it. The next fence starts from the root again.
+    let fenceCwd = '';
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line === undefined)
+            break;
+        if (line.fence === null) {
+            if (line.exempt || line.frontmatter)
+                continue;
+            // An inline span is a command of its own, run from the root.
+            for (const span of codeSpans(line.text)) {
+                if (COMMAND_HEAD.test(`${span.content} `))
+                    read(line.number, span.content, false, '', true);
+            }
+            continue;
+        }
+        if (isShellFence(line.fence)) {
+            // A `#` outside quotes starts a comment, and a backslash inside one
+            // continues nothing, so the comment goes before a trailing backslash is
+            // read. That backslash joins the next line as bash joins it, and the
+            // joined text is read for a comment again. A CRLF line's CR is its line break.
+            let text = stripComment(withoutCr(line.text).replace(/^\s*\$\s+/, ''));
+            const start = line.number;
+            // Only a line of the same fence continues it.
+            for (let next = lines[index + 1]; continues(text) && next?.block === line.block; next = lines[index + 1]) {
+                index += 1;
+                text = stripComment(`${text.slice(0, -1)}${withoutCr(next.text)}`);
+            }
+            text = trimCode(text);
+            // Every line's `cd` counts, an exempt line's included (the shell still
+            // runs it); only a line that runs something, unexempt, is judged.
+            fenceCwd = read(start, text, true, fenceCwd, !line.exempt && (COMMAND_HEAD.test(`${text} `) || (DECLARED_SHELL.has(line.fence) && SCRIPT_HEAD.test(text))));
+        }
+        // The fence's last line: the next fence starts from the root.
+        if (lines[index + 1]?.block !== line.block)
+            fenceCwd = '';
+    }
+    return commands;
+};

package/dist/doc-files.js

@@ -0,0 +1,74 @@
+// The documents absolute-paths and non-synced-resources read, and the config
+// both take. A product's hook hands them its own list (`--files-from`); with
+// none, they read every file git tracks.
+import { readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { entries } from "./coverage-by-type.js";
+import { gitAt, must } from "./git.js";
+/** Markdown and MDX. */
+export const DEFAULT_INCLUDE = '\\.(md|mdx)$';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * `{ "include"?: "<regex>", "guidance"?: ["<line>", …] }`; absent keys take
+ * the defaults. Throws on anything else, so a mistyped key never passes as
+ * the default.
+ */
+export const parseDocConfig = (text, defaultGuidance) => {
+    if (text === undefined)
+        return { include: new RegExp(DEFAULT_INCLUDE), guidance: defaultGuidance };
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`not JSON: ${e.message}`);
+    }
+    if (!isRecord(raw))
+        throw new Error('the config must be a JSON object');
+    const unknown = Object.keys(raw).find((k) => k !== 'include' && k !== 'guidance');
+    if (unknown !== undefined)
+        throw new Error(`unknown key "${unknown}"`);
+    // Absent takes the default; a present `null` is refused like any other wrong value.
+    const include = 'include' in raw ? raw['include'] : DEFAULT_INCLUDE;
+    if (typeof include !== 'string' || include === '')
+        throw new Error('"include" must be a non-empty regex string');
+    let pattern;
+    try {
+        pattern = new RegExp(include);
+    }
+    catch (e) {
+        throw new Error(`"include" is not a regex: ${e.message}`);
+    }
+    const guidance = 'guidance' in raw ? raw['guidance'] : defaultGuidance;
+    if (!Array.isArray(guidance) || guidance.some((line) => typeof line !== 'string'))
+        throw new Error('"guidance" must be a list of lines');
+    return { include: pattern, guidance: guidance };
+};
+/** Whether `path` (under `base` when relative) names a regular file, a symlink to one included. */
+export const isFileAt = (base, path) => {
+    try {
+        return statSync(resolve(base, path)).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * The documents to check, as listed: each entry of `listed` that names a
+ * regular file under `base` and matches `include`, in order; a named path
+ * that is not a file is dropped. With no list, every file git tracks under
+ * `base`, as git names it.
+ */
+export const selectDocs = (base, listed, include) => {
+    const paths = listed === undefined ? must(gitAt(base), ['ls-files', '-z']).split('\0').filter(Boolean) : entries(listed);
+    return paths.filter((path) => isFileAt(base, path) && include.test(path));
+};
+/** A document's lines as a shell `read` loop sees them: split on newlines, a last line without one included. */
+export const linesOf = (text) => {
+    const lines = text.split('\n');
+    if (lines.at(-1) === '')
+        lines.pop();
+    return lines;
+};
+/** A listed document's text. */
+export const readDoc = (base, path) => readFileSync(resolve(base, path), 'utf8');

package/dist/doc-flag-spec.js

@@ -0,0 +1,87 @@
+// What a script's own source declares about its flags (DOC-DRIFT-02): whether
+// it reads its own argv, which flags it knows, the values an enum-valued flag
+// takes, its required flags and its first positional's choices.
+// doc-command-rules.ts holds a documented command to them.
+/** argparse actions that take no value: the flag alone is the input. */
+const FLAG_ONLY_ACTIONS = ['store_true', 'store_false', 'store_const', 'append_const', 'count', 'help', 'version'];
+/** The keyword arguments in an `add_argument` call's text, each value unquoted. A string is read whole, so `help="nargs=0"` is one argument. */
+const keywordArguments = (text) => {
+    const out = new Map();
+    for (const match of text.matchAll(/"[^"]*"|'[^']*'|(\w+)\s*=\s*("[^"]*"|'[^']*'|[^,"']*)/g)) {
+        if (match[1] !== undefined)
+            out.set(match[1], String(match[2]).trim().replace(/^["']|["']$/g, ''));
+    }
+    return out;
+};
+/** Words an argparse option with these keyword arguments takes. */
+const argparseValueCount = (kwargs) => {
+    const action = kwargs.get('action');
+    if (action !== undefined && (FLAG_ONLY_ACTIONS.includes(action) || action.endsWith('BooleanOptionalAction')))
+        return 0;
+    const nargs = kwargs.get('nargs');
+    if (nargs === undefined || nargs === '?')
+        return 1;
+    return /^\d+$/.test(nargs) ? Number(nargs) : Infinity;
+};
+const quotedValues = (text) => new Set([...text.matchAll(/["']([^"']+)["']/g)].map((m) => String(m[1])));
+/** What a script's own source declares about its flags. */
+export const flagSpec = (source, path) => {
+    const shell = /\.(sh|bash)$/.test(path) || !/\.\w+$/.test(path);
+    const python = path.endsWith('.py');
+    // A script that hands its arguments on cannot be judged from its own text.
+    // Nor can a shell script that sources a file: the file runs with the
+    // script's own arguments, so its flags may be read there.
+    const forwards = shell
+        ? /"\$@"|\$\*|"\$\{@\}"|\$@|^\s*(?:source|\.)\s/m.test(source)
+        : python
+            ? /parse_known_args|sys\.argv\[1:\]\s*\)/.test(source) && !/add_argument/.test(source)
+            : /strict:\s*false/.test(source);
+    const values = (flag) => {
+        const usage = new RegExp(`${flag}[ =]<([\\w.:-]+(?:\\|[\\w.:-]+)+)>`).exec(source);
+        if (usage !== null)
+            return new Set(String(usage[1]).split('|'));
+        const braces = new RegExp(`${flag}[ =]\\{([\\w.:-]+(?:,[\\w.:-]+)+)\\}`).exec(source);
+        if (braces !== null)
+            return new Set(String(braces[1]).split(','));
+        const choices = new RegExp(`add_argument\\(\\s*["']${flag}["'][^)]*?choices\\s*=\\s*[[(]([^\\])]*)[\\])]`).exec(source);
+        return choices === null ? undefined : quotedValues(String(choices[1]));
+    };
+    // With subparsers, an argument a subcommand's parser adds (`x =
+    // subs.add_parser(…)`, or chained on one) is that subcommand's: not
+    // required of every invocation, and not the first word.
+    const subcommands = /add_subparsers/.test(source);
+    const local = new Set([...source.matchAll(/(\w+)\s*=\s*[\w.]+\.add_parser\(/g)].map((m) => String(m[1])));
+    const calls = python
+        ? [...source.matchAll(/(?:(\w+)|\))\.add_argument\(\s*["']([\w-]+)["']((?:\s*,\s*["'][\w-]+["'])*)([^)]*)/g)]
+            .filter((match) => !subcommands || (match[1] !== undefined && !local.has(match[1])))
+            .map((match) => ({
+            name: String(match[2]),
+            // Every option string: `add_argument("-o", "--out")` is both.
+            aliases: [String(match[2]), ...Array.from(String(match[3]).matchAll(/["']([\w-]+)["']/g), (m) => String(m[1]))],
+            rest: String(match[4]),
+        }))
+        : [];
+    const required = calls.filter((call) => call.name.startsWith('--') && /required\s*=\s*True/.test(call.rest)).map((call) => call.name);
+    // The first positional's own choices. A call's text ends at its first `)`, so a tuple of choices runs to the end of it.
+    const first = calls.find((call) => !call.name.startsWith('-'));
+    const choices = first === undefined ? null : /choices\s*=\s*[[(]([^\])]*)/.exec(first.rest);
+    return {
+        closed: !forwards,
+        known: (flag) => {
+            if (flag === '--help' || flag === '-h')
+                return true;
+            if (new RegExp(`${flag}(?![\\w-])`).test(source))
+                return true;
+            // node:util parseArgs declares `name: { type: … }` without dashes.
+            const key = flag.replace(/^--/, '');
+            return new RegExp(`(?:^|[\\s{,])['"]?${key}['"]?\\s*:\\s*\\{[^}]*\\btype\\s*:`).test(source);
+        },
+        values,
+        required,
+        valueCount: (flag) => {
+            const call = calls.find((each) => each.aliases.includes(flag));
+            return call === undefined ? 0 : argparseValueCount(keywordArguments(call.rest));
+        },
+        positional: choices === null ? undefined : quotedValues(String(choices[1])),
+    };
+};