@veda-hq/pariksha 0.5.13 → 0.5.17

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/non-synced-resources.js

@@ -0,0 +1,164 @@
+// non-synced-resources: every relative Markdown link in a document names a
+// file or folder the repository holds, under the same case.
+//
+// A link to a file that was never committed, or to one outside the checkout,
+// works for its writer and for nobody else. Each `[text](dest)` and
+// `![alt](dest)` on a line (in code blocks too) is read; `http(s)://`,
+// `mailto:` and `#anchor` links are not. Its `#fragment` and `?query` go, then
+// its destination is the text inside `<…>`, or the text before a space (a
+// title). A destination starting with `/` is read from the repository's top.
+// It is refused when its folder does not exist, when it lands outside the
+// repository, when nothing is there, or when the name on disk differs in case
+// (macOS opens `./README.MD` as `./readme.md`; Linux and CI do not). An image
+// over 1 MiB is warned about, never refused.
+//
+// Ported from a shell check unchanged: paths are joined and split as the shell
+// joined them (dirname, basename, `cd && pwd`), so a link's text decides what
+// counts as inside the repository exactly as before.
+import { lstatSync, readdirSync, statSync } from 'node:fs';
+import { posix } from 'node:path';
+import { linesOf } from "./doc-files.js";
+/** A Markdown link or image, as the shell check's `grep -oE` matched it. */
+const LINK = /!?\[[^\]]*\]\([^)]+\)/g;
+const SKIPPED = /^(https?:\/\/|mailto:|#)/;
+const IMAGE = /\.(png|jpg|jpeg|gif|webp)$/;
+const LARGE_IMAGE_BYTES = 1_048_576;
+export const DEFAULT_GUIDANCE = ['Please ensure all referenced files exist in the repository.'];
+/** The destination of each link on each line of `text`, as written, http(s), mailto and anchor links dropped. */
+export const linkTargets = (text) => linesOf(text)
+    .flatMap((line) => [...line.matchAll(LINK)].map((m) => m[0].slice(m[0].indexOf('](') + 2, -1)))
+    .filter((dest) => !SKIPPED.test(dest));
+/** A destination without its fragment, query or title, and out of its angle brackets; '' when nothing is left. */
+export const linkPath = (dest) => {
+    let link = dest;
+    const hash = link.indexOf('#');
+    if (hash !== -1)
+        link = link.slice(0, hash);
+    const query = link.indexOf('?');
+    if (query !== -1)
+        link = link.slice(0, query);
+    if (link.startsWith('<') && link.indexOf('>', 1) !== -1)
+        return link.slice(1, link.indexOf('>'));
+    const space = link.indexOf(' ');
+    return space === -1 ? link : link.slice(0, space);
+};
+const stripTrailingSlashes = (path) => {
+    const stripped = path.replace(/\/+$/, '');
+    return stripped === '' && path !== '' ? '/' : stripped;
+};
+/** POSIX `dirname`. */
+export const dirnameOf = (path) => {
+    const trimmed = stripTrailingSlashes(path);
+    const slash = trimmed.lastIndexOf('/');
+    if (slash === -1)
+        return '.';
+    const head = trimmed.slice(0, slash).replace(/\/+$/, '');
+    return head === '' ? '/' : head;
+};
+/** POSIX `basename`. */
+export const basenameOf = (path) => {
+    const trimmed = stripTrailingSlashes(path);
+    return trimmed === '/' ? '/' : trimmed.slice(trimmed.lastIndexOf('/') + 1);
+};
+const isDir = (path) => {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const exists = (path) => {
+    try {
+        const s = statSync(path);
+        return s.isFile() || s.isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+/** Whether folder `dir` holds an entry named exactly `name`; `.` and `..` always. */
+export const nameOnDisk = (dir, name) => {
+    if (name === '.' || name === '..')
+        return true;
+    try {
+        return readdirSync(dir).includes(name);
+    }
+    catch {
+        return false;
+    }
+};
+/** A regular file's size in bytes, the link itself for a symlink (as `stat` without `-L` reads it). */
+const sizeOf = (path) => {
+    try {
+        const s = lstatSync(path);
+        return statSync(path).isFile() ? s.size : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The lines for one document's links, and whether any was refused. `file` is
+ * as listed; a relative one is read from `top`, the repository's top folder.
+ */
+export const checkDoc = (top, file, text) => {
+    const out = [];
+    let refused = false;
+    const fileDir = dirnameOf(file);
+    const under = (path) => path.startsWith(`${top}/`);
+    const relativeOf = (path) => (under(path) ? path.slice(top.length + 1) : path);
+    for (const dest of linkTargets(text)) {
+        const link = linkPath(dest);
+        if (link === '')
+            continue;
+        let target = link.startsWith('/') ? `${top}${link}` : fileDir.startsWith('/') ? `${fileDir}/${link}` : `${top}/${fileDir}/${link}`;
+        const parent = dirnameOf(target);
+        if (!isDir(parent) && under(target)) {
+            out.push(`❌ Error: Reference to file in non-existent directory in ${file}:`, `   Link: ${link}`, `   Expected path: ${relativeOf(target)}`, '   Parent directory does not exist', '');
+            refused = true;
+            continue;
+        }
+        // `cd "$parent" && pwd`: the folder with `.` and `..` resolved by name.
+        target = `${isDir(parent) ? posix.resolve(parent) : parent}/${basenameOf(target)}`;
+        if (!under(target)) {
+            out.push(`❌ Error: Reference to file outside repository in ${file}:`, `   Link: ${link}`, `   Resolved path: ${target}`, '   All references must be within the repository', '');
+            refused = true;
+            continue;
+        }
+        const relative = relativeOf(target);
+        if (!exists(target)) {
+            out.push(`❌ Error: Reference to non-existent file in ${file}:`, `   Link: ${link}`, `   Expected path: ${relative}`, '');
+            refused = true;
+        }
+        else if (!nameOnDisk(dirnameOf(target), basenameOf(target))) {
+            out.push(`❌ Error: Reference whose case differs from the file on disk in ${file}:`, `   Link: ${link}`, `   Expected path: ${relative}`, '');
+            refused = true;
+        }
+        const size = IMAGE.test(target) ? sizeOf(target) : undefined;
+        if (size !== undefined && size > LARGE_IMAGE_BYTES) {
+            out.push(`⚠️  Warning: Large image referenced in ${file}:`, `   Image: ${relative}`, `   Size: ~${Math.floor(size / 1024 / 1024)} MB (${Math.floor(size / 1024)} KB)`, '   Consider compressing images to keep repository size small.', '');
+        }
+    }
+    return { refused, out };
+};
+/**
+ * The report for `docs` (path and text, in order), printed as the shell check
+ * printed it. `top` is asked for only when there is a document to read.
+ */
+export const checkNonSyncedResources = (docs, top, config) => {
+    const out = ['→ Checking for non-synced resource references...'];
+    if (docs.length === 0)
+        return { ok: true, out: [...out, '✅ No documentation files to check.'] };
+    out.push(`   Checking ${docs.length} documentation file(s)...`);
+    const root = top();
+    let refused = false;
+    for (const doc of docs) {
+        const result = checkDoc(root, doc.file, doc.text());
+        out.push(...result.out);
+        refused ||= result.refused;
+    }
+    if (refused)
+        return { ok: false, out: [...out, '', ...config.guidance] };
+    return { ok: true, out: [...out, '✅ All resource references are valid'] };
+};