@veda-hq/pariksha 0.5.5 → 0.5.7

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.5 <check> [flags]
-npx @veda-hq/pariksha@0.5.5 --version
+npx @veda-hq/pariksha@0.5.7 <check> [flags]
+npx @veda-hq/pariksha@0.5.7 --version
 ```
 
 Every check exits 0 when the repository passes, 1 when it refuses something
@@ -252,6 +252,26 @@ 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.
 
+## `required-settings`
+
+```sh
+pariksha required-settings --require <file> [--settings <file>] [--root <dir>]
+```
+
+A setting a project depends on, such as Claude Code's `advisorModel`, is one
+committed line, and one edit deletes it without any test noticing. The
+requirements file lists each key (a dotted path for a nested one) with the
+value it must hold and why:
+
+```json
+{ "advisorModel": { "value": "fable", "why": "sessions work with the advisor on" } }
+```
+
+The check refuses a settings file (default `.claude/settings.json`) that lacks
+a key or holds another value, compared as JSON, naming the key, the value and
+the reason. A missing settings file is a refusal; a requirements file it cannot
+read or parse, or one listing no key, exits 2.
+
 ## markdownlint rules
 
 ```jsonc

package/dist/cli.js

@@ -12,6 +12,7 @@ import { checkBudgets } from "./doc-budgets.js";
 import { diskReads, formatReads, listFiles, needsTypescript, parseConfig as parseGateConfig, readerFor, readGate } from "./env-gate-switches.js";
 import { loadTypescript, typescriptLoaders } from "./typescript.js";
 import { checkExportDeletions, formatReport } from "./export-deletions.js";
+import { findMissing, formatFindings, parseRequirements } from "./required-settings.js";
 import { BASE_CANDIDATES, gitAt, gitAtTop, must, resolveBase, topOf } from "./git.js";
 export const DENY_FILE = '.veda/deny.sha256';
 const USAGE = [
@@ -22,6 +23,7 @@ const USAGE = [
     '       pariksha doc-budgets --table <file> [--section <name>] [--root <dir>]',
     '       pariksha env-gate-switches --config <file> [--mode staged|tree] [--root <dir>]',
     '       pariksha export-deletions [--base <ref>] [--root <dir>]',
+    '       pariksha required-settings --require <file> [--settings <file>] [--root <dir>]',
     '       pariksha hash <word>',
     '       pariksha --version',
 ].join('\n');
@@ -316,6 +318,53 @@ const envGateSwitches = (f, io) => {
     result.err.forEach(io.err);
     return result.ok ? 0 : 1;
 };
+export const DEFAULT_SETTINGS = '.claude/settings.json';
+const requiredSettings = (f, io) => {
+    const P = 'pariksha required-settings:';
+    const requirePath = f.get('--require');
+    if (requirePath === undefined) {
+        io.err(USAGE);
+        return 2;
+    }
+    const root = resolve(f.get('--root') ?? '.');
+    const settingsPath = f.get('--settings') ?? DEFAULT_SETTINGS;
+    const read = (path, what) => {
+        try {
+            return readFileSync(resolve(root, path), 'utf8');
+        }
+        catch {
+            io.err(`${P} cannot read the ${what} ${resolve(root, path)}; nothing was checked, so this is not a pass`);
+            return undefined;
+        }
+    };
+    const requireText = read(requirePath, 'requirements');
+    if (requireText === undefined)
+        return 2;
+    let requirements;
+    try {
+        requirements = parseRequirements(requireText);
+    }
+    catch (e) {
+        io.err(`${P} ${requirePath}: ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+    const settingsText = read(settingsPath, 'settings');
+    // A missing settings file lacks every required key: a refusal, not a usage error.
+    if (settingsText === undefined)
+        return 1;
+    let findings;
+    try {
+        findings = findMissing(settingsText, requirements);
+    }
+    catch (e) {
+        io.err(`${P} ${settingsPath}: ${e.message}`);
+        return 1;
+    }
+    const result = formatFindings(findings, requirements.length, settingsPath, requirePath);
+    result.out.forEach(io.out);
+    result.err.forEach(io.err);
+    return result.ok ? 0 : 1;
+};
 const COMMANDS = {
     'coverage-exemptions': { allowed: ['--config', '--package', '--root'], run: coverageExemptions },
     'authority-citations': { allowed: ['--mode', '--authority', '--issue-prefix', '--adr-dir', '--root'], run: authorityCitations },
@@ -324,6 +373,7 @@ const COMMANDS = {
     'doc-budgets': { allowed: ['--table', '--section', '--root'], run: docBudgets },
     'env-gate-switches': { allowed: ['--config', '--mode', '--root'], run: envGateSwitches },
     'export-deletions': { allowed: ['--base', '--root'], run: exportDeletions },
+    'required-settings': { allowed: ['--require', '--settings', '--root'], run: requiredSettings },
 };
 export const run = (args, io, version = ownVersion(), env = process.env) => {
     const [command, ...rest] = args;

package/dist/required-settings.js

@@ -0,0 +1,86 @@
+// required-settings: a settings file carries every value a project requires of it.
+//
+// A setting a project depends on (Claude Code's `advisorModel`, say) lives in
+// one committed line, and one edit deletes it without any test noticing. The
+// project lists what it requires, with why, and this check refuses a settings
+// file that lacks a key or holds another value.
+import { isDeepStrictEqual } from 'node:util';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Parses the requirements file: `{ "<key>": { "value": <any JSON>, "why": "<reason>" }, … }`.
+ * Throws on anything else, so a malformed list never passes as an empty one.
+ */
+export function parseRequirements(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`the requirements are not JSON (${e.message})`);
+    }
+    if (!isRecord(raw))
+        throw new Error('the requirements must be an object of keys');
+    const out = [];
+    for (const [key, spec] of Object.entries(raw)) {
+        if (key === '$schema')
+            continue;
+        if (key === '' || key.split('.').some((part) => part === ''))
+            throw new Error(`"${key}" is not a key or dotted path`);
+        if (!isRecord(spec) || !Object.hasOwn(spec, 'value'))
+            throw new Error(`"${key}" needs { "value": …, "why": "…" }`);
+        const extra = Object.keys(spec).filter((k) => k !== 'value' && k !== 'why');
+        if (extra.length > 0)
+            throw new Error(`"${key}": unknown key ${extra.map((k) => `"${k}"`).join(', ')}`);
+        if (typeof spec.why !== 'string' || spec.why.trim() === '')
+            throw new Error(`"${key}" needs a "why"`);
+        out.push({ key, value: spec.value, why: spec.why });
+    }
+    if (out.length === 0)
+        throw new Error('the requirements list no key');
+    return out;
+}
+/** The value at a dotted path, or `{ missing: true }`. */
+const lookup = (settings, key) => {
+    let at = settings;
+    for (const part of key.split('.')) {
+        if (!isRecord(at) || !Object.hasOwn(at, part))
+            return { missing: true };
+        at = at[part];
+    }
+    return { missing: false, value: at };
+};
+/** Every requirement the settings break: a missing key or a different value. */
+export function findMissing(settingsText, requirements) {
+    let settings;
+    try {
+        settings = JSON.parse(settingsText);
+    }
+    catch (e) {
+        throw new Error(`the settings are not JSON (${e.message})`);
+    }
+    if (!isRecord(settings))
+        throw new Error('the settings must hold an object');
+    const findings = [];
+    for (const r of requirements) {
+        const got = lookup(settings, r.key);
+        if (got.missing)
+            findings.push({ key: r.key, expected: r.value, why: r.why });
+        else if (!isDeepStrictEqual(got.value, r.value))
+            findings.push({ key: r.key, expected: r.value, found: got.value, why: r.why });
+    }
+    return findings;
+}
+/** The check's lines: one per finding on err, or one pass line on out. */
+export function formatFindings(findings, count, settingsPath, requirePath) {
+    const P = 'pariksha required-settings:';
+    if (findings.length === 0)
+        return { ok: true, out: [`${P} ${settingsPath} carries all ${count} required settings (${requirePath})`], err: [] };
+    return {
+        ok: false,
+        out: [],
+        err: findings.map((f) => {
+            const has = Object.hasOwn(f, 'found') ? `holds ${JSON.stringify(f.found)}` : 'is missing';
+            return `${P} ${settingsPath}: "${f.key}" ${has}; it must be ${JSON.stringify(f.expected)} (${f.why}). Put it back; to change the requirement, edit ${requirePath}.`;
+        }),
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@veda-hq/pariksha",
-  "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.",
+  "version": "0.5.7",
+  "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, required-settings. Also markdownlint rules for Markdown that renders mangled: @veda-hq/pariksha/markdownlint.",
   "keywords": [
     "repository checks",
     "lint",
@@ -52,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 ../.. && 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');\"",
+    "smoke": "node dist/cli.js --version && node dist/cli.js boundary --root ../.. && node dist/cli.js required-settings --require .veda/required-settings.json --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"
   }
 }