@veda-hq/pariksha 0.5.20 → 0.6.4

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.20 <check> [flags]
-npx @veda-hq/pariksha@0.5.20 --version
+npx @veda-hq/pariksha@0.6.4 <check> [flags]
+npx @veda-hq/pariksha@0.6.4 --version
 ```
 
 Every check exits 0 when the repository passes, 1 when it refuses something
@@ -72,19 +72,32 @@ step's `if:`, or any `${{ … }}` in the job, outside quoted literals. Text in
 a `run:` script and an action input named `if` are not reads. A non-gating
 job (a change detector) need not be gated, but must be declared once read.
 
+The same command refuses a workflow that holds a gate and can also be
+dispatched (`workflow_dispatch` in `on:`, as one event, in a list or as a
+key), one line per gate under its own id, `dispatch-on-gate-workflow`. A
+dispatch run from a branch with an open pull request posts every job's check
+on the head commit, the gate among them as skipped, and that replaces the
+pull request run's success: a merge queue requiring the gate reads it as
+failed and dequeues the pull request. Ad-hoc runs belong in a separate
+workflow with no gate-named job.
+
 ```json
-{ "id": "CI-001", "workflowsDir": ".github/workflows", "gateName": "gate$", "nonGating": ["detect-changes"] }
+{ "id": "CI-001", "workflowsDir": ".github/workflows", "gateName": "gate$", "nonGating": ["detect-changes"], "dispatchAllowed": [] }
 ```
 
 - `id` (default `aggregate-gate-needs`) names the check in its messages: a
-  project's rule id, say.
+  project's rule id, say. The dispatch refusal keeps its own id.
 - `workflowsDir` (default `.github/workflows`, relative to the root).
 - `gateName` (default `gate$`) is a regex, matched case-insensitively.
 - `nonGating` (default none) lists job ids that gate nothing.
+- `dispatchAllowed` (default none) lists workflow file names (`release.yml`)
+  that may be dispatched beside a gate: one no merge queue requires, such as
+  an approval gate in a release workflow.
 
 A workflow that does not parse is reported as a gap, never passed. No
 workflow to read exits 1 (`no workflow files found — the lookup failed`),
-as the original did; a bad config exits 2.
+as the original did; a bad config exits 2. The clean line is unchanged: it
+prints only when both refusals find nothing.
 
 ## `authority-citations`
 
@@ -1030,6 +1043,38 @@ Parsing those is the job of a command guard such as kavach's `git_safety`.
 project's settings and then also skips the user's own `defaultMode`, so it
 belongs in user settings only.
 
+## `schema-roots`
+
+```sh
+pariksha schema-roots [--files-from <file>|-] [--root <dir>] [<file>...]
+```
+
+The Anthropic API refuses a tool's `input_schema`, or a structured output's
+schema, with `allOf`, `anyOf` or `oneOf` at its root, answering 400:
+"input_schema does not support oneOf, allOf, or anyOf at the top level". The
+request fails before the first tool call, so an agent built on that schema
+dies at its start every time. This reads the JSON files it is given and refuses each such
+schema:
+
+- the value under `input_schema`, `inputSchema`, `output_schema`,
+  `outputSchema` or `json_schema`, and the `schema` inside a `json_schema`,
+  at any depth, in objects and arrays (a request's `tools` list, say);
+- the `schema` of an object whose `type` is `json_schema`, a structured
+  output format;
+- the root of a file named `*.schema.json`.
+
+A combinator below a schema's root is allowed, and a schema found is not read
+further: a property inside it named `input_schema` is a property. Each
+finding goes to stderr as `<file>: <json path>: top-level <keyword>`, with
+the fix: express the condition in code after the call returns.
+
+The files are the ones named on the command line and the ones `--files-from`
+lists, one path per line (a file, or `-` for stdin); relative paths are read
+from the root. Only `.json` files are read, so a list of changed files can
+hold others; YAML is not read. No file to read passes. The first `.json`
+file that cannot be read or is not plain JSON (one with comments, say) exits
+2, naming it, and no finding is printed; so does a list that cannot be read.
+
 ## `shell-gates`
 
 ```sh

package/dist/aggregate-gate-needs.js

@@ -15,20 +15,32 @@
 // `${{ … }}` in the job. Not read: text in a `run:` script, quoted literals in
 // an expression, and an action input that happens to be called `if`. A
 // workflow that does not parse is reported, never read as having no gaps.
+//
+// The same workflows are also refused a `workflow_dispatch` trigger beside a
+// gate (dispatch-on-gate-workflow): a dispatch run from a branch with an open
+// pull request posts every job's check on the head commit, the gate among
+// them as skipped, and that replaces the pull request run's success. A merge
+// queue requiring the gate then reads it as failed and dequeues the pull
+// request. `dispatchAllowed` names the workflows (by file name) where that
+// cannot happen, for a project with no merge queue on the gate.
 import { readdirSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { load as parseYaml } from 'js-yaml';
 export const DEFAULT_GATE_CONFIG = {
     workflowsDir: '.github/workflows',
     gateName: /gate$/i,
     nonGating: new Set(),
     id: 'aggregate-gate-needs',
+    dispatchAllowed: new Set(),
 };
+/** What the messages call the dispatch refusal: its own rule, not the project's needs rule. */
+export const DISPATCH_ID = 'dispatch-on-gate-workflow';
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 /**
  * `{ "id"?: "<label>", "workflowsDir"?: "<dir>", "gateName"?: "<regex>",
- * "nonGating"?: ["<job id>", …] }`; `gateName` matches case-insensitively.
- * Absent keys take the defaults; anything else throws.
+ * "nonGating"?: ["<job id>", …], "dispatchAllowed"?: ["<file name>", …] }`;
+ * `gateName` matches case-insensitively. Absent keys take the defaults;
+ * anything else throws.
  */
 export const parseGateConfig = (text) => {
     let raw;
@@ -40,7 +52,7 @@ export const parseGateConfig = (text) => {
     }
     if (!isRecord(raw))
         throw new Error('the config must be a JSON object');
-    const unknown = Object.keys(raw).find((k) => !['id', 'workflowsDir', 'gateName', 'nonGating'].includes(k));
+    const unknown = Object.keys(raw).find((k) => !['id', 'workflowsDir', 'gateName', 'nonGating', 'dispatchAllowed'].includes(k));
     if (unknown !== undefined)
         throw new Error(`unknown key "${unknown}"`);
     const text_ = (key, fallback) => {
@@ -60,10 +72,15 @@ export const parseGateConfig = (text) => {
     catch (e) {
         throw new Error(`"gateName" is not a regex: ${e.message}`);
     }
-    const nonGating = 'nonGating' in raw ? raw['nonGating'] : [];
-    if (!Array.isArray(nonGating) || nonGating.some((j) => typeof j !== 'string' || j === ''))
-        throw new Error('"nonGating" must be a list of job ids');
-    return { id, workflowsDir, gateName, nonGating: new Set(nonGating) };
+    const names = (key, what) => {
+        const value = key in raw ? raw[key] : [];
+        if (!Array.isArray(value) || value.some((j) => typeof j !== 'string' || j === ''))
+            throw new Error(`"${key}" must be a list of ${what}`);
+        return new Set(value);
+    };
+    const nonGating = names('nonGating', 'job ids');
+    const dispatchAllowed = names('dispatchAllowed', 'workflow file names');
+    return { id, workflowsDir, gateName, nonGating, dispatchAllowed };
 };
 /** The `.yml` and `.yaml` files in the workflows folder, as root-relative paths; none when it cannot be read. */
 export const workflowFiles = (root, dir) => {
@@ -107,23 +124,31 @@ export const consumedNeeds = (job) => {
     return [...ids];
 };
 const asArray = (needs) => (needs === undefined ? [] : Array.isArray(needs) ? needs : [needs]);
+/** The workflow at `relative`, or undefined when it does not parse; a scalar or null document is no job map, read as empty. */
+const readWorkflow = (root, relative) => {
+    let parsed;
+    try {
+        parsed = parseYaml(readFileSync(join(root, relative), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    return typeof parsed === 'object' && parsed !== null ? parsed : {};
+};
+/** The ids of the workflow's gates: jobs whose `name:` (or id), or id, matches `gateName`. */
+const gatesOf = (jobs, config) => Object.keys(jobs).filter((id) => config.gateName.test(jobs[id]?.name ?? id) || config.gateName.test(id));
 /** Each gate, in each of `files` (root-relative), whose `needs:` leaves out a job it gates or reads. */
 export const findGateGaps = (root, files, config) => {
     const gaps = [];
     for (const relative of files) {
-        let document;
-        try {
-            // A workflow that parses to a scalar or null is no job map: read as empty.
-            const parsed = parseYaml(readFileSync(join(root, relative), 'utf8'));
-            document = typeof parsed === 'object' && parsed !== null ? parsed : {};
-        }
-        catch {
+        const document = readWorkflow(root, relative);
+        if (document === undefined) {
             gaps.push({ workflow: relative, gate: '(unparseable)', missing: ['<file did not parse>'] });
             continue;
         }
         const jobs = document.jobs ?? {};
         const jobIds = Object.keys(jobs);
-        const gateIds = jobIds.filter((id) => config.gateName.test(jobs[id]?.name ?? id) || config.gateName.test(id));
+        const gateIds = gatesOf(jobs, config);
         for (const gateId of gateIds) {
             const declared = new Set(asArray(jobs[gateId]?.needs));
             const missing = jobIds.filter((id) => id !== gateId && !gateIds.includes(id) && !config.nonGating.has(id) && !declared.has(id));
@@ -135,19 +160,53 @@ export const findGateGaps = (root, files, config) => {
     }
     return gaps;
 };
-/** The verdict on the workflows under `root`, worded as the original check worded it. */
+/** Whether the workflow's `on:` (one event, a list, or a map) holds `workflow_dispatch`; a map's value is usually null. */
+export const hasDispatch = (on) => {
+    if (typeof on === 'string')
+        return on === 'workflow_dispatch';
+    if (Array.isArray(on))
+        return on.includes('workflow_dispatch');
+    return isRecord(on) && Object.hasOwn(on, 'workflow_dispatch');
+};
+/**
+ * Each gate, in each of `files` (root-relative), whose workflow can also be
+ * dispatched, outside `dispatchAllowed`. A workflow that does not parse is
+ * left to findGateGaps, which reports it.
+ */
+export const findDispatchedGates = (root, files, config) => {
+    const found = [];
+    for (const relative of files) {
+        if (config.dispatchAllowed.has(basename(relative)))
+            continue;
+        const document = readWorkflow(root, relative);
+        if (document === undefined || !hasDispatch(document.on))
+            continue;
+        for (const gate of gatesOf(document.jobs ?? {}, config))
+            found.push({ workflow: relative, gate });
+    }
+    return found;
+};
+/** The refusal of one dispatched gate, one line. */
+export const dispatchMessage = (found) => `❌ ${DISPATCH_ID}: ${found.workflow}: workflow_dispatch on the workflow holding the required gate ${found.gate}. ` +
+    "A dispatch run posts the gate as skipped on the PR's head commit, which a merge queue reads as failed and dequeues the PR. " +
+    'Move ad-hoc runs to a separate workflow with no gate-named job.';
+/** The verdict on the workflows under `root`: the needs gaps worded as the original check worded them, then each dispatched gate. */
 export const checkGates = (root, config) => {
     const files = workflowFiles(root, config.workflowsDir);
     if (files.length === 0)
         return { ok: false, out: [], err: [`❌ ${config.id}: no workflow files found — the lookup failed`] };
     const gaps = findGateGaps(root, files, config);
-    if (gaps.length === 0)
+    const dispatched = findDispatchedGates(root, files, config).map(dispatchMessage);
+    if (gaps.length === 0 && dispatched.length === 0)
         return { ok: true, out: [`✅ ${config.id}: every aggregate gate depends on all its jobs (${files.length} workflow(s))`], err: [] };
-    const err = [`\n❌ ${config.id}: ${gaps.length} aggregate gate(s) with an incomplete needs list\n`];
-    for (const gap of gaps)
-        err.push(` ${gap.workflow} → job "${gap.gate}"`, `   not depended on: ${gap.missing.join(', ')}\n`);
-    err.push('The merge queue checks only the gate. A job absent from its `needs:` cannot\n' +
-        'block a merge however it fails — and a failure upstream turns into a SKIP\n' +
-        'downstream, which the gate then accepts.\n');
-    return { ok: false, out: [], err };
+    const err = [];
+    if (gaps.length > 0) {
+        err.push(`\n❌ ${config.id}: ${gaps.length} aggregate gate(s) with an incomplete needs list\n`);
+        for (const gap of gaps)
+            err.push(` ${gap.workflow} → job "${gap.gate}"`, `   not depended on: ${gap.missing.join(', ')}\n`);
+        err.push('The merge queue checks only the gate. A job absent from its `needs:` cannot\n' +
+            'block a merge however it fails — and a failure upstream turns into a SKIP\n' +
+            'downstream, which the gate then accepts.\n');
+    }
+    return { ok: false, out: [], err: [...err, ...dispatched] };
 };

package/dist/cli.js

@@ -32,6 +32,7 @@ import { checkClaims, formatOutcome, loadEslint, parseConfig as parseClaimsConfi
 import { parseConfig as parseDuplicateConfig, runDuplicateTests } from "./duplicate-tests.js";
 import { DEFAULT_RUNS, npxVitest, parseConfig as parseFlakyConfig, parseRuns, runFlakyTests } from "./flaky-tests.js";
 import { inheritRunner, runPythonFloor } from "./python-floor.js";
+import { checkSchemaRoots, jsonFiles, readDocuments } from "./schema-roots.js";
 export const DENY_FILE = '.veda/deny.sha256';
 const USAGE = [
     'usage: pariksha authority-citations [--mode staged|tree] [--authority <a,b>] [--issue-prefix <A,B>] [--adr-dir <dir>] [--root <dir>]',
@@ -54,6 +55,7 @@ const USAGE = [
     '       pariksha pnpm-settings [--config <file>] [--root <dir>]',
     '       pariksha python-floor --python <interpreter> --floor-file <path> [--exclude <regex>] [--selector <path>] [--root <dir>]',
     '       pariksha required-settings --require <file> [--settings <file>] [--root <dir>]',
+    '       pariksha schema-roots [--files-from <file>|-] [--root <dir>] [<file>...]',
     '       pariksha shell-gates [--config <file>] [--staged | --all | --base <ref> | --files-from <file>|-] [--only <checks>] [--root <dir>]',
     '       pariksha hash <word>',
     '       pariksha --version',
@@ -791,6 +793,52 @@ const pythonFloor = (f, io) => {
     };
     return runPythonFloor(options, io.python ?? inheritRunner, io.err);
 };
+/** `rest` split into its `--name value` pairs and the bare words around them, the files a command names. */
+export const splitFiles = (rest) => {
+    const flagArgs = [];
+    const files = [];
+    for (let i = 0; i < rest.length; i += 1) {
+        const word = rest[i];
+        if (!word.startsWith('--')) {
+            files.push(word);
+            continue;
+        }
+        flagArgs.push(...rest.slice(i, i + 2));
+        i += 1;
+    }
+    return { flagArgs, files };
+};
+/**
+ * schema-roots: the `.json` files named on the command line and in the
+ * `--files-from` list, relative ones read from the root; other files are
+ * not read, and none at all is a pass. The first file that cannot be read or
+ * parsed exits 2, naming it, with no finding printed.
+ */
+const schemaRoots = (rest, io) => {
+    const P = 'pariksha schema-roots:';
+    const { flagArgs, files: named } = splitFiles(rest);
+    const f = flags(flagArgs, ['--files-from', '--root']);
+    if (!f) {
+        io.err(USAGE);
+        return 2;
+    }
+    const root = resolve(f.get('--root') ?? '.');
+    const from = f.get('--files-from');
+    let documents;
+    try {
+        const listed = [...named, ...(from === undefined ? [] : entries(listFrom(from, io)))];
+        const files = [...new Set(jsonFiles(listed).map((p) => relative(root, resolve(root, p))))];
+        documents = readDocuments(files, (file) => readFileSync(resolve(root, file), 'utf8'));
+    }
+    catch (e) {
+        io.err(`${P} ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+    const result = checkSchemaRoots(documents);
+    result.out.forEach(io.out);
+    result.err.forEach(io.err);
+    return result.ok ? 0 : 1;
+};
 const COMMANDS = {
     'codec-registry': { allowed: ['--config', '--base', '--root'], switches: ['--no-base'], run: codecRegistry },
     'coverage-exemptions': { allowed: ['--config', '--package', '--root'], run: coverageExemptions },
@@ -825,6 +873,9 @@ export const run = (args, io, version = ownVersion(), env = process.env) => {
         io.out(hash(rest[0]));
         return 0;
     }
+    // The one check that takes files as bare words, so not through `flags`.
+    if (command === 'schema-roots')
+        return schemaRoots(rest, io);
     const spec = command !== undefined && Object.hasOwn(COMMANDS, command) ? COMMANDS[command] : undefined;
     const f = spec && flags(rest, spec.allowed, spec.switches);
     if (!spec || !f) {

package/dist/schema-roots.js

@@ -0,0 +1,92 @@
+// schema-roots: no tool or output schema with a combinator at its root.
+//
+// The Anthropic API refuses a tool's `input_schema`, or a structured output's
+// schema, whose root holds `allOf`, `anyOf` or `oneOf` (a 400, "input_schema
+// does not support oneOf, allOf, or anyOf at the top level"). The request
+// fails before the model's first tool call, so an agent built on that schema
+// dies at its start, every time, with nothing wrong in its own code. This
+// reads JSON documents and refuses each such schema it finds:
+//
+// - the value under `input_schema`, `inputSchema`, `output_schema`,
+//   `outputSchema` or `json_schema`, and the `schema` inside a `json_schema`;
+// - the `schema` of an object whose `type` is `json_schema` (a structured
+//   output format: `{ "type": "json_schema", "schema": {…} }`);
+// - the root of a file named `*.schema.json`.
+//
+// A schema found is not read further: a combinator below its root is allowed,
+// and a property inside it that happens to be called `input_schema` is a
+// property, not a tool.
+import { basename } from 'node:path';
+export const COMBINATORS = ['allOf', 'anyOf', 'oneOf'];
+/** The keys whose value is a tool's or an output's schema. */
+export const SCHEMA_KEYS = ['input_schema', 'inputSchema', 'output_schema', 'outputSchema', 'json_schema'];
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** `path` one step further: `[0]`, `.name`, or `["a key"]` for a key that is no identifier. */
+const step = (path, key) => typeof key === 'number' ? `${path}[${key}]` : /^[A-Za-z_$][\w$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+/** Each tool or output schema in `document`, the JSON of `file`, whose root holds a combinator. */
+export const findRootCombinators = (file, document) => {
+    const found = [];
+    const atRoot = (schema, path) => {
+        if (!isRecord(schema))
+            return;
+        for (const keyword of COMBINATORS)
+            if (Object.hasOwn(schema, keyword))
+                found.push({ file, path, keyword });
+    };
+    const walk = (value, path) => {
+        if (Array.isArray(value)) {
+            value.forEach((item, i) => walk(item, step(path, i)));
+            return;
+        }
+        if (!isRecord(value))
+            return;
+        const format = value['type'] === 'json_schema' && isRecord(value['schema']);
+        for (const [key, child] of Object.entries(value)) {
+            const at = step(path, key);
+            if (format && key === 'schema')
+                atRoot(child, at);
+            else if (SCHEMA_KEYS.includes(key)) {
+                atRoot(child, at);
+                if (key === 'json_schema' && isRecord(child))
+                    atRoot(child['schema'], step(at, 'schema'));
+            }
+            else
+                walk(child, at);
+        }
+    };
+    if (basename(file).endsWith('.schema.json'))
+        atRoot(document, '$');
+    else
+        walk(document, '$');
+    return found;
+};
+/** The refusal of one schema, one line. */
+export const rootMessage = (found) => `pariksha schema-roots: ${found.file}: ${found.path}: top-level ${found.keyword}. ` +
+    'The API rejects tool and output schemas with oneOf, allOf or anyOf at the root; express the condition in code after the call returns.';
+/** The JSON files among `paths`: the ones this check reads. */
+export const jsonFiles = (paths) => paths.filter((p) => /\.json$/i.test(p));
+/** A file's text as JSON, a leading byte-order mark dropped; throws `not JSON: …`. */
+export const parseJson = (text) => {
+    try {
+        return JSON.parse(text.startsWith('') ? text.slice(1) : text);
+    }
+    catch (e) {
+        throw new Error(`not JSON: ${e.message}`);
+    }
+};
+/** Each of `files`, read by `read` and parsed; throws on the first that cannot be, naming it. */
+export const readDocuments = (files, read) => files.map((file) => {
+    try {
+        return { file, json: parseJson(read(file)) };
+    }
+    catch (e) {
+        throw new Error(`${file}: ${e.message}`);
+    }
+});
+/** The verdict on `documents`, each a file's path and its parsed JSON. */
+export const checkSchemaRoots = (documents) => {
+    const found = documents.flatMap((d) => findRootCombinators(d.file, d.json));
+    if (found.length > 0)
+        return { ok: false, out: [], err: found.map(rootMessage) };
+    return { ok: true, out: [`pariksha schema-roots: ${documents.length} JSON file(s), no tool or output schema with oneOf, allOf or anyOf at its root`], err: [] };
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@veda-hq/pariksha",
-  "version": "0.5.20",
-  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. Checks: absolute-paths, aggregate-gate-needs, authority-citations, boundary, codec-registry, coverage-by-type, coverage-exemptions, doc-budgets, doc-references, duplicate-tests, enforcement-claims, env-gate-switches, export-deletions, fault-injection-registry, flaky-tests, masked-exit-codes, non-synced-resources, pnpm-settings, python-floor, required-settings, shell-gates. Also markdownlint rules for Markdown that renders mangled: @veda-hq/pariksha/markdownlint.",
+  "version": "0.6.4",
+  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. Checks: absolute-paths, aggregate-gate-needs, authority-citations, boundary, codec-registry, coverage-by-type, coverage-exemptions, doc-budgets, doc-references, duplicate-tests, enforcement-claims, env-gate-switches, export-deletions, fault-injection-registry, flaky-tests, masked-exit-codes, non-synced-resources, pnpm-settings, python-floor, required-settings, schema-roots, shell-gates. Also markdownlint rules for Markdown that renders mangled: @veda-hq/pariksha/markdownlint.",
   "keywords": [
     "repository checks",
     "lint",