@veda-hq/pariksha 0.5.5 → 0.5.8

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.8 <check> [flags]
+npx @veda-hq/pariksha@0.5.8 --version
 ```
 
 Every check exits 0 when the repository passes, 1 when it refuses something
@@ -252,6 +252,42 @@ 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" } }
+```
+
+A list the project only adds to, such as a permission list, takes
+`"includes"` instead of `"value"`: the key must be a list holding each entry,
+among any others.
+
+The check refuses a settings file (default `.claude/settings.json`) that lacks
+a key, holds another value, or lacks a required list entry, compared as JSON,
+naming the key, what is wrong 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.
+
+`baselines/claude-settings.json` (`@veda-hq/pariksha/baselines/claude-settings.json`)
+is the permission baseline every repository agents work in keeps: allow
+`mcp__ccd_pr__set_monitor`, deny `Bash(*--no-verify*)`, ask
+`Bash(*git push*--force*)` and `Bash(*git push* -f*)`. Point `--require` at it
+in the package's install. Permission globs are a coarse backstop: they cannot
+tell `git commit -n` from `git log -n 5`, nor see `git -C dir push --force`.
+Parsing those is the job of a command guard such as kavach's `git_safety`.
+`permissions.defaultMode: "auto"` is not in it: Claude Code ignores `auto` in a
+project's settings and then also skips the user's own `defaultMode`, so it
+belongs in user settings only.
+
 ## markdownlint rules
 
 ```jsonc

package/baselines/claude-settings.json

@@ -0,0 +1,14 @@
+{
+  "permissions.allow": {
+    "includes": ["mcp__ccd_pr__set_monitor"],
+    "why": "an agent turns on the desktop app's CI monitor for the pull request it opens without a prompt"
+  },
+  "permissions.deny": {
+    "includes": ["Bash(*--no-verify*)"],
+    "why": "no git command skips the repository's hooks"
+  },
+  "permissions.ask": {
+    "includes": ["Bash(*git push*--force*)", "Bash(*git push* -f*)"],
+    "why": "a force push rewrites published history, so a person approves each one"
+  }
+}

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,120 @@
+// 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, holds another value, or drops an entry from a list
+// (a permission rule, say) the project requires.
+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": "…" } | { "includes": [<any JSON>, …], "why": "…" }, … }`.
+ * 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`);
+        const shape = `"${key}" needs { "value": …, "why": "…" } or { "includes": […], "why": "…" }`;
+        if (!isRecord(spec))
+            throw new Error(shape);
+        const hasValue = Object.hasOwn(spec, 'value');
+        const hasIncludes = Object.hasOwn(spec, 'includes');
+        if (hasValue === hasIncludes)
+            throw new Error(shape);
+        const extra = Object.keys(spec).filter((k) => k !== 'value' && k !== 'includes' && 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"`);
+        if (!hasIncludes) {
+            out.push({ key, kind: 'value', expected: spec.value, why: spec.why });
+            continue;
+        }
+        const includes = spec.includes;
+        if (!Array.isArray(includes) || includes.length === 0)
+            throw new Error(`"${key}": "includes" must list at least one entry`);
+        out.push({ key, kind: 'includes', expected: includes, 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 };
+};
+/** The finding for one requirement, or undefined when the settings meet it. */
+const judge = (settings, r) => {
+    const got = lookup(settings, r.key);
+    const base = { key: r.key, kind: r.kind, why: r.why };
+    if (r.kind === 'value') {
+        if (got.missing)
+            return { ...base, expected: r.expected };
+        return isDeepStrictEqual(got.value, r.expected) ? undefined : { ...base, expected: r.expected, found: got.value };
+    }
+    const wanted = r.expected;
+    if (got.missing)
+        return { ...base, expected: wanted };
+    if (!Array.isArray(got.value))
+        return { ...base, expected: wanted, found: got.value };
+    const list = got.value;
+    const lacking = wanted.filter((entry) => !list.some((have) => isDeepStrictEqual(have, entry)));
+    return lacking.length === 0 ? undefined : { ...base, expected: lacking, found: got.value };
+};
+/** Every requirement the settings break: a missing key, a different value, or a list without a required entry. */
+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');
+    return requirements.flatMap((r) => judge(settings, r) ?? []);
+}
+/** One finding as a line: what is wrong and how to fix it. */
+const describe = (f) => {
+    if (f.kind === 'value') {
+        const has = Object.hasOwn(f, 'found') ? `holds ${JSON.stringify(f.found)}` : 'is missing';
+        return `"${f.key}" ${has}; it must be ${JSON.stringify(f.expected)}`;
+    }
+    const entries = f.expected.map((e) => JSON.stringify(e)).join(', ');
+    if (!Object.hasOwn(f, 'found'))
+        return `"${f.key}" is missing; it must be a list holding ${entries}`;
+    if (!Array.isArray(f.found))
+        return `"${f.key}" holds ${JSON.stringify(f.found)}, not a list; it must be a list holding ${entries}`;
+    return `"${f.key}" lacks ${entries}`;
+};
+/** 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) => `${P} ${settingsPath}: ${describe(f)} (${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.8",
+  "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",
@@ -31,10 +31,12 @@
   "exports": {
     "./markdownlint": "./dist/markdownlint-rules.js",
     "./dist/*": "./dist/*",
+    "./baselines/*": "./baselines/*",
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "baselines"
   ],
   "peerDependencies": {
     "typescript": ">=5.4 <6"
@@ -52,7 +54,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 dist/cli.js required-settings --require packages/pariksha/baselines/claude-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"
   }
 }