@veda-hq/pariksha 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Veda Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @veda-hq/pariksha
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+परीक्षा, examination. Repository checks: doc drift, rule enforcement,
+test-quality ratchets. Part of [Veda](https://github.com/veda-hq/veda).
+
+## v0.1: `pariksha boundary`
+
+Refuses any file git tracks, by its path or its text, that names a word on
+the repository's deny list.
+
+```sh
+npx @veda-hq/pariksha@0.1.0 boundary [--root <dir>] [--deny <file>]
+npx @veda-hq/pariksha@0.1.0 hash <word>
+npx @veda-hq/pariksha@0.1.0 --version
+```
+
+- The deny list (default `.veda/deny.sha256`, relative to the root) holds one
+  SHA-256 hash of a lowercase word per line; blank lines and `#` comments are
+  ignored. `pariksha hash <word>` prints the line for a word.
+- Words are runs of ASCII letters and digits, compared case-insensitively:
+  `foo-bar`, `foo_bar` and `@Foo/bar` all contain the word `foo`.
+- Binary files (any NUL byte) are skipped. Untracked files are not read.
+- Exit codes: 0 clean, 1 a denied word was found (each is listed with its file
+  and line; line 0 is the file's path), 2 a usage or deny-list error.
+
+Node 24 or later. MIT.

package/dist/boundary.js

@@ -0,0 +1,44 @@
+// The boundary check: no tracked file names a denied name. The deny list holds
+// SHA-256 hashes of lowercase words, so a repository can refuse a name without
+// writing it down.
+import { createHash } from 'node:crypto';
+export const hash = (word) => createHash('sha256').update(word.toLowerCase()).digest('hex');
+/** The deny list's hashes: one per line; blank lines and # comments ignored. */
+export const parseDenyList = (text) => {
+    const hashes = new Set();
+    for (const raw of text.split('\n')) {
+        const line = raw.replace(/#.*/, '').trim().toLowerCase();
+        if (line === '')
+            continue;
+        if (!/^[0-9a-f]{64}$/.test(line))
+            throw new Error(`not a SHA-256 hash: "${line}"`);
+        hashes.add(line);
+    }
+    return hashes;
+};
+/** A file is text unless it holds a NUL byte. */
+export const isText = (bytes) => !bytes.includes(0);
+/** Every word of every file whose hash is denied, by file and line. */
+export const findDenied = (files, deny) => {
+    const hits = [];
+    const seen = new Map();
+    const denied = (word) => {
+        let d = seen.get(word);
+        if (d === undefined) {
+            d = deny.has(hash(word));
+            seen.set(word, d);
+        }
+        return d;
+    };
+    for (const file of files) {
+        // A path names things too: a file called after a denied name is refused.
+        const lines = [file.path, ...file.text.split('\n')];
+        lines.forEach((text, i) => {
+            for (const word of text.toLowerCase().match(/[a-z0-9]+/g) ?? []) {
+                if (denied(word))
+                    hits.push({ file: file.path, line: i, word });
+            }
+        });
+    }
+    return hits;
+};

package/dist/cli.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// pariksha: repository checks. v0.1 has one, `boundary`.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findDenied, hash, isText, parseDenyList } from './boundary.js';
+export const DENY_FILE = '.veda/deny.sha256';
+const USAGE = [
+    'usage: pariksha boundary [--root <dir>] [--deny <file>]',
+    '       pariksha hash <word>',
+    '       pariksha --version',
+].join('\n');
+export const ownVersion = () => {
+    const pkg = join(import.meta.dirname, '..', 'package.json');
+    return JSON.parse(readFileSync(pkg, 'utf8')).version;
+};
+/** The files git tracks under root, text ones only. */
+export const trackedFiles = (root) => {
+    const names = execFileSync('git', ['ls-files', '-z'], { cwd: root, encoding: 'utf8' }).split('\0').filter(Boolean);
+    const files = [];
+    for (const path of names) {
+        const full = join(root, path);
+        if (!existsSync(full))
+            continue; // deleted in the working tree, not yet committed
+        const bytes = readFileSync(full);
+        if (isText(bytes))
+            files.push({ path, text: bytes.toString('utf8') });
+    }
+    return files;
+};
+const flags = (rest) => {
+    const out = new Map();
+    for (let i = 0; i < rest.length; i += 2) {
+        const name = rest[i];
+        const value = rest[i + 1];
+        if ((name !== '--root' && name !== '--deny') || !value || out.has(name))
+            return undefined;
+        out.set(name, value);
+    }
+    return out;
+};
+const boundary = (rest, io) => {
+    const f = flags(rest);
+    if (!f) {
+        io.err(USAGE);
+        return 2;
+    }
+    const root = resolve(f.get('--root') ?? '.');
+    const denyPath = resolve(root, f.get('--deny') ?? DENY_FILE);
+    if (!existsSync(denyPath)) {
+        io.err(`pariksha boundary: no deny list at ${denyPath}`);
+        return 2;
+    }
+    let deny;
+    try {
+        deny = parseDenyList(readFileSync(denyPath, 'utf8'));
+    }
+    catch (e) {
+        io.err(`pariksha boundary: ${denyPath}: ${e.message}`);
+        return 2;
+    }
+    const files = trackedFiles(root);
+    const hits = findDenied(files, deny);
+    if (hits.length > 0) {
+        for (const h of hits) {
+            const at = h.line === 0 ? `${h.file} (its path)` : `${h.file}:${h.line}`;
+            io.err(`pariksha boundary: ${at}: "${h.word}" is on the deny list`);
+        }
+        return 1;
+    }
+    io.out(`pariksha boundary: ${files.length} files, none names a denied word (${deny.size} on the list)`);
+    return 0;
+};
+export const run = (args, io, version = ownVersion()) => {
+    const [command, ...rest] = args;
+    if (command === '--version' && rest.length === 0) {
+        io.out(version);
+        return 0;
+    }
+    if (command === 'hash' && rest.length === 1 && rest[0]) {
+        io.out(hash(rest[0]));
+        return 0;
+    }
+    if (command === 'boundary')
+        return boundary(rest, io);
+    io.err(USAGE);
+    return 2;
+};
+const isMain = () => {
+    const entry = process.argv[1];
+    return entry !== undefined && realpathSync(entry) === fileURLToPath(import.meta.url);
+};
+if (isMain()) {
+    process.exitCode = run(process.argv.slice(2), {
+        out: (line) => console.info(line),
+        err: (line) => console.error(line),
+    });
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@veda-hq/pariksha",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. v0.1: the boundary check, which refuses any tracked file naming a denied word.",
+  "keywords": [
+    "repository checks",
+    "lint",
+    "boundary",
+    "ci",
+    "coding agents"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24.15"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/veda-hq/veda.git",
+    "directory": "packages/pariksha"
+  },
+  "homepage": "https://github.com/veda-hq/veda/tree/main/packages/pariksha#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "pariksha": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "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 ../..",
+    "check": "pnpm typecheck && pnpm test && pnpm build && pnpm smoke"
+  }
 }