@veda-hq/pariksha 0.5.7 → 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.7 <check> [flags]
-npx @veda-hq/pariksha@0.5.7 --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
@@ -267,10 +267,26 @@ value it must hold and why:
 { "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 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.
+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
 

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/required-settings.js

@@ -3,11 +3,13 @@
 // 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.
+// 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": "<reason>" }, … }`.
+ * 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) {
@@ -26,14 +28,26 @@ export function parseRequirements(text) {
             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');
+        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"`);
-        out.push({ key, value: spec.value, why: spec.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');
@@ -49,7 +63,25 @@ const lookup = (settings, key) => {
     }
     return { missing: false, value: at };
 };
-/** Every requirement the settings break: a missing key or a different value. */
+/** 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 {
@@ -60,16 +92,21 @@ export function findMissing(settingsText, requirements) {
     }
     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;
+    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:';
@@ -78,9 +115,6 @@ export function formatFindings(findings, count, settingsPath, requirePath) {
     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}.`;
-        }),
+        err: findings.map((f) => `${P} ${settingsPath}: ${describe(f)} (${f.why}). Put it back; to change the requirement, edit ${requirePath}.`),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veda-hq/pariksha",
-  "version": "0.5.7",
+  "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",
@@ -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 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');\"",
+    "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"
   }
 }