From 0a8a2e598af8443c8053420a3744a893a91b0d49 Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Tue, 13 Oct 2026 18:00:47 +1100 Subject: [PATCH 1/2] feat(rules): cascade gating for rule evaluation (#115) Schema failures, hierarchy violations and gating rule violations suppress rule evaluation for a node's main-hierarchy subtree, avoiding wasted downstream checks on inputs already known to be bad. Gated coverage is reported in validate output (human and --json) so callers can see what wasn't evaluated and why. Rules gain `gatesDescendants`, defaulting to true for error severity and false for warning/info. `sctx validate-file` applies the same gating, so a file's rule results match its entry in a full validate run, and reports a `gated` info entry when its rules were skipped. Adds `--depth ` to scope validation to a breadth-first hierarchy depth, and `--include-gated` to evaluate gated rules while still reporting them. --- AGENTS.md | 1 + README.md | 5 +- docs/concepts.md | 6 + docs/rules.md | 47 ++++ plugin/.claude-plugin/plugin.json | 2 +- .../structured-context/references/commands.md | 12 +- .../_structured_context_schema_meta.json | 3 + src/commands/validate-file.ts | 7 +- src/commands/validate.ts | 29 ++- src/index.ts | 21 +- src/schema/gating.ts | 203 ++++++++++++++++++ src/schema/metadata-contract.ts | 2 + src/types.ts | 1 + src/validate.ts | 107 ++++++++- tests/fixtures/depth-relationship/Assume.md | 5 + tests/fixtures/depth-relationship/Goal.md | 4 + tests/fixtures/depth-relationship/Opp.md | 5 + .../gating-directory/Bad Outcome.md | 6 + .../gating-directory/Child Opportunity.md | 8 + .../gating-directory/Only Solution.md | 7 + tests/schema/gating.test.ts | 188 ++++++++++++++++ tests/validate/gating.test.ts | 142 ++++++++++++ 22 files changed, 793 insertions(+), 18 deletions(-) create mode 100644 src/schema/gating.ts create mode 100644 tests/fixtures/depth-relationship/Assume.md create mode 100644 tests/fixtures/depth-relationship/Goal.md create mode 100644 tests/fixtures/depth-relationship/Opp.md create mode 100644 tests/fixtures/strict_ost/gating-directory/Bad Outcome.md create mode 100644 tests/fixtures/strict_ost/gating-directory/Child Opportunity.md create mode 100644 tests/fixtures/strict_ost/gating-directory/Only Solution.md create mode 100644 tests/schema/gating.test.ts create mode 100644 tests/validate/gating.test.ts diff --git a/AGENTS.md b/AGENTS.md index 7cccb01..2b9f439 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,6 +45,7 @@ There are several places that need reviewing and updating with any new feature o - `schemas/` — Bundled default schema files (JSON5) using the structured-context schema dialect and top-level `$metadata`. Files starting with `_` are "partials" (fragments for `$ref`). - `src/schema/metadata-contract.ts` — Single source of truth for the `$metadata` contract - `schemas/generated/latest/_structured_context_schema_meta.json` — Generated metaschema for the newest dialect (generated on build or with `bun run generate:schema-meta`). `schemas/generated//` folders are frozen copies, created by the `version` script (`generate:schema-meta --release`) only when a release changes the dialect; never edit them. `src/schema/meta-schemas.ts` loads them at runtime. +- `src/schema/gating.ts` — Cascade gating: computes hierarchy depth and evaluates rules with subtree gating (schema/hierarchy/blocking-rule failures suppress downstream rule checks). See [docs/rules.md](docs/rules.md#cascade-gating). ## Testing For most development only the main unit tests need re-running regularly. diff --git a/README.md b/README.md index 32f1e8d..efb867a 100644 --- a/README.md +++ b/README.md @@ -131,13 +131,16 @@ See [docs/schemas.md](docs/schemas.md) (`sctx docs schema`) for the dialect, com ### Validate nodes ```bash -sctx validate [--watch] +sctx validate [--watch] [--depth ] [--include-gated] ``` Validates markdown files against the JSON schema: - Extracts YAML frontmatter from each `.md` file - Skips files without frontmatter or without a `type` field - Reports validation results with counts and per-file errors +- Runs executable rules (`$metadata.rules`) with **cascade gating**: a schema, hierarchy, or blocking-rule failure on a node suppresses rule evaluation for that node's hierarchy subtree. Gated checks are reported in a Coverage section so you know what wasn't evaluated and why. See [docs/rules.md](docs/rules.md#cascade-gating) for details. +- `--depth ` limits evaluation to hierarchy nodes within `n` breadth-first levels from the top — useful for staged agentic fix loops (fix the top level, then request the next). +- `--include-gated` evaluates rules even on gated nodes (still reported as gated) — for surfacing cheap bottom-up checks on request. ### Render space diff --git a/docs/concepts.md b/docs/concepts.md index 0ef2256..324fbee 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -147,6 +147,12 @@ Each executable rule has a **category** (`validation`, `coherence`, `workflow`, See [docs/rules.md](rules.md) for the rules reference, including JSONata expression syntax and the full `$metadata` field reference. +### Cascade gating + +**Cascade gating** is the mechanism by which a schema failure, hierarchy structure violation, or blocking rule violation on a node suppresses rule evaluation for that node's `hierarchy` subtree. It exists so downstream checks — especially future evaluative or LLM-judged layers — aren't run against inputs already known to be invalid. + +A **coverage gate** records one instance of this: the gating node, what kind of failure triggered it (`schema`, `hierarchy`, or a specific rule `id`), and the set of nodes whose rule checks were suppressed as a result. `sctx validate` reports coverage gates so both humans and agents can see the validation "edge" — where evaluation stopped and why. See [docs/rules.md](rules.md#cascade-gating) for the full model, including the per-rule `gatesDescendants` field and the `--include-gated` / `--depth` CLI options. + --- ## Tooling types diff --git a/docs/rules.md b/docs/rules.md index 2bea839..ca48f91 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -30,6 +30,7 @@ Rules are a flat array. | `type` | no | Restrict rule to nodes of this `resolvedType` | | `scope` | no | Use `"global"` to evaluate once for the whole space | | `override` | no | Only for merge conflicts: allows later duplicate `id` to replace earlier | +| `gatesDescendants` | no | Whether a violation gates downstream checks on the node's hierarchy subtree. Defaults to `true` for rules with `error` severity, `false` for `warning` and `info`. Set explicitly to override either way. | ## Categories and severity @@ -137,6 +138,52 @@ Example override: } ``` +## Cascade gating + +When a schema uses `$metadata.hierarchy`, rule evaluation cascades top-down through the +hierarchy tree (breadth-first from roots and orphans). A **gate** occurs when a node fails +in a way that makes its descendants' checks untrustworthy or wasteful to run: + +- **Schema validation failure** on a node — always gates. The node's own rule checks are + suppressed too, since its data is structurally invalid. +- **Hierarchy structure violation** on a node (e.g. an invalid parent) — always gates the + node's subtree, though the node's own rules still run. +- **A rule violation with `gatesDescendants: true`** (the default for `error`-severity rules; `warning` and `info` rules don't gate unless they set `gatesDescendants: true`) — gates the node's subtree. The + violating node's own other rules still run (they're the same cheap deterministic layer). + +Gating is per-subtree: once a node is gated, its descendants inherit the same gate (the +original blocker), rather than each generating a new one. Non-hierarchy nodes and +`scope: "global"` rules are never gated — cascade gating only applies within the hierarchy +DAG. + +This exists so that expensive or semantic downstream checks (see #114) aren't wasted +evaluating nodes whose ancestors are already known-bad, and so noise doesn't drown out the +actionable failure. Set `gatesDescendants: false` on an error-severity rule whose violations shouldn't suppress +checks further down the tree, or `gatesDescendants: true` on a warning/info rule that should. + +### Coverage output + +`sctx validate` reports gating as **coverage gates**: which node's failure (schema, +hierarchy, or a specific `ruleId`) suppressed rule evaluation, and the list of files gated +as a result. This makes the validation "edge" visible — e.g. "this blocked goal means all +opportunities beneath it were not evaluated" — for both human reading and agent consumption +(JSON output via `--json`, under `coverageGates`). + +Use `--include-gated` to evaluate rules on gated nodes anyway (still reported as gated) — +useful for surfacing cheap, bottom-up checks (e.g. orphan detection, content quality) that +don't depend on an ancestor being valid. + +### Single-file validation + +`sctx validate-file ` applies the same gating as `sctx validate`, so a file's rule results match its entry in a full run. Rules are evaluated for the whole space and the output is restricted to the file. If the file is gated, its rule checks are skipped and a `gated:` entry (kind `gated`, severity `info`) under `warnings` names the blocker, so a gated file doesn't read as clean. `--include-gated` evaluates the file's rules anyway. `--depth` is not supported. + +### Depth-limited evaluation + +`--depth ` restricts validation to hierarchy nodes within `n` breadth-first levels from +the top (roots and orphans are depth 1). This is a manual, coarser control than cascade +gating — intended for staged workflows (e.g. an agent fixes the top level, then requests +the next). Excluded nodes are reported under `skippedByDepth`, separate from gated nodes. + ## Common patterns ```jsonata diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index c937904..037f46f 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "structured-context", - "version": "0.12.4", + "version": "0.12.6", "description": "Structured content authoring for Obsidian — automatic validation hooks, slash commands, and agent skills to keep markdown files compliant with your schema.", "homepage": "https://github.com/mindsocket/structured-context", "repository": "https://github.com/mindsocket/structured-context", diff --git a/plugin/skills/structured-context/references/commands.md b/plugin/skills/structured-context/references/commands.md index b7c2847..f2bd438 100644 --- a/plugin/skills/structured-context/references/commands.md +++ b/plugin/skills/structured-context/references/commands.md @@ -11,7 +11,7 @@ Then use the `sctx` command for all operations. Always pass `--config ` wh ## validate ```bash -sctx validate [--watch] [--config ] +sctx validate [--watch] [--config ] [--depth ] [--include-gated] ``` Validates all `.md` files in the space against the JSON schema. For each file: @@ -19,9 +19,17 @@ Validates all `.md` files in the space against the JSON schema. For each file: - Skips files with no frontmatter or no `type` field (after `fieldMap` remapping) - Runs JSON schema validation - Runs reference checks (wikilinks → known node titles) -- Runs executable rules (JSONata expressions in `$metadata.rules`), reporting each violation with a severity (`error`, `warning`, `info`) +- Runs executable rules (JSONata expressions in `$metadata.rules`), with cascade gating: a + schema, hierarchy, or blocking-rule failure on a node suppresses rule evaluation for its + hierarchy subtree. Gated nodes are reported in a coverage section (and `coverageGates` in + `--json` output) so you know what wasn't checked and why. - Checks hierarchy ordering +`--depth ` restricts evaluation to hierarchy nodes within `n` breadth-first levels from +the top — useful for fixing a space level by level (fix the top, re-run with a deeper +`--depth`, repeat). `--include-gated` evaluates rules on gated nodes anyway, still reporting +them as gated — use it to surface cheap bottom-up checks even when an upstream blocker fired. + Exit codes: `0` = clean (warning and info rule violations don't fail), `1` = validation errors found. **Scenarios:** diff --git a/schemas/generated/latest/_structured_context_schema_meta.json b/schemas/generated/latest/_structured_context_schema_meta.json index 77660a5..02d47c2 100644 --- a/schemas/generated/latest/_structured_context_schema_meta.json +++ b/schemas/generated/latest/_structured_context_schema_meta.json @@ -216,6 +216,9 @@ }, "override": { "type": "boolean" + }, + "gatesDescendants": { + "type": "boolean" } }, "required": ["id", "category", "description", "check"], diff --git a/src/commands/validate-file.ts b/src/commands/validate-file.ts index 2aa62c8..e69eef5 100644 --- a/src/commands/validate-file.ts +++ b/src/commands/validate-file.ts @@ -9,9 +9,12 @@ export { validateFile } from '../validate'; * Loads config automatically from the environment, outputs human-readable or JSON, * and returns an exit code (0 = valid, 1 = errors found). */ -export async function validateFileCommand(filePath: string, options: { json?: boolean } = {}): Promise { +export async function validateFileCommand( + filePath: string, + options: { json?: boolean; includeGated?: boolean } = {}, +): Promise { const config = loadConfig(); - const result = await validateFile(filePath, config); + const result = await validateFile(filePath, config, { includeGated: options.includeGated }); if (!result.inSpace) { if (options.json) { diff --git a/src/commands/validate.ts b/src/commands/validate.ts index d3e2535..ac9953a 100644 --- a/src/commands/validate.ts +++ b/src/commands/validate.ts @@ -6,9 +6,12 @@ import { bundledSchemasDir } from '../schema/schema'; import type { FileValidationIssue, RuleSeverity, SpaceContext } from '../types'; import { formatErrors, validateSpace } from '../validate'; -export async function validate(context: SpaceContext, options: { json?: boolean } = {}): Promise { +export async function validate( + context: SpaceContext, + options: { json?: boolean; depth?: number; includeGated?: boolean } = {}, +): Promise { const { schema, schemaRefRegistry } = context; - const result = await validateSpace(context); + const result = await validateSpace(context, { depth: options.depth, includeGated: options.includeGated }); const ruleCounts: Record = { error: 0, warning: 0, info: 0 }; for (const v of result.ruleViolations) ruleCounts[v.severity]++; @@ -68,6 +71,9 @@ export async function validate(context: SpaceContext, options: { json?: boolean orphanCount: result.orphans.length, parseIssues: result.parseIssues, unresolvedContentLinks: result.unresolvedContentLinks, + coverageGates: result.coverageGates, + skippedByDepth: result.skippedByDepth, + depthLimit: result.depthLimit, }, null, 2, @@ -113,6 +119,11 @@ export async function validate(context: SpaceContext, options: { json?: boolean console.log(fmt(' Unresolved content links', result.unresolvedContentLinks.length, true, true)); const parseIssueErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length; console.log(fmt(' Excluded during parsing', result.parseIssues.length, true, parseIssueErrorCount === 0)); + if (result.depthLimit !== undefined) { + console.log(fmt(' Skipped by depth limit', result.skippedByDepth.length, true, true)); + } + const gatedFileCount = result.coverageGates.reduce((sum, g) => sum + g.gatedFiles.length, 0); + console.log(fmt(' Rule checks gated (cascade)', gatedFileCount, true, true)); if (result.orphans.length > 0) { console.log(`\nOrphans (hierarchy nodes - no parent):`); @@ -193,6 +204,20 @@ export async function validate(context: SpaceContext, options: { json?: boolean } } + if (result.coverageGates.length > 0) { + console.log(`\nCoverage — rule checks gated by cascade (use --include-gated to evaluate anyway):`); + for (const gate of result.coverageGates) { + const cause = gate.reason === 'rule' ? `blocking rule "${gate.ruleId}"` : `${gate.reason} failure`; + console.log(` ${gate.file} (${gate.nodeTitle}) — ${cause} gated ${gate.gatedFiles.length} node(s):`); + for (const file of gate.gatedFiles) console.log(` ${file}`); + } + } + + if (result.skippedByDepth.length > 0) { + console.log(`\nSkipped by depth limit (--depth ${result.depthLimit}):`); + for (const { file } of result.skippedByDepth) console.log(` ${file}`); + } + console.log(`\n`); if ( diff --git a/src/index.ts b/src/index.ts index 1e484f4..fbe3229 100755 --- a/src/index.ts +++ b/src/index.ts @@ -57,8 +57,12 @@ program .description('Validate a single file within its space') .argument('', 'Path to the file to validate') .option('--json', 'Output results as JSON (machine-readable, for hooks)') + .option( + '--include-gated', + 'Evaluate rules even when the file is gated by an upstream schema/hierarchy/rule failure (still reported as gated)', + ) .action(async (filePath, options) => { - process.exitCode = await validateFileCommand(filePath, { json: options.json }); + process.exitCode = await validateFileCommand(filePath, { json: options.json, includeGated: options.includeGated }); }); program @@ -67,13 +71,26 @@ program .argument('', 'Space name') .option('-w, --watch', 'Watch for changes and re-run validation') .option('--json', 'Output results as JSON') + .option( + '--depth ', + 'Evaluate only hierarchy nodes within N breadth-first levels from the top (e.g. 1 = root level only)', + (v) => parseInt(v, 10), + ) + .option( + '--include-gated', + 'Evaluate rules even on nodes gated by an upstream schema/hierarchy/rule failure (still reported as gated)', + ) .action(async (spaceName, options) => { const context = buildSpaceContext(spaceName); if (options.watch) { await watchValidate(context); } else { // exitCode rather than process.exit(): exiting straight away can cut off large piped output - process.exitCode = await validate(context, { json: options.json }); + process.exitCode = await validate(context, { + json: options.json, + depth: options.depth, + includeGated: options.includeGated, + }); } }); diff --git a/src/schema/gating.ts b/src/schema/gating.ts new file mode 100644 index 0000000..3bb416a --- /dev/null +++ b/src/schema/gating.ts @@ -0,0 +1,203 @@ +import type { SpaceGraph } from '../space-graph'; +import type { Rule, RuleViolation, SpaceNode } from '../types'; +import { buildEvalContext, evaluateExpression } from './evaluate-rule'; +import { ruleSeverity } from './validate-rules'; + +/** Whether a violation of this rule gates its subtree: explicit `gatesDescendants`, else true only for `error` severity. */ +export function ruleGatesDescendants(rule: Rule): boolean { + return rule.gatesDescendants ?? ruleSeverity(rule) === 'error'; +} + +/** + * A node-level failure that seeds cascade gating: a deterministic, always-run check + * (schema validation or hierarchy structure) that failed on a specific node. + */ +export type GatingSeed = { + /** Label (file) of the failing node. */ + file: string; + /** Title of the failing node. */ + title: string; + /** Which always-run layer produced the failure. */ + reason: 'schema' | 'hierarchy'; +}; + +/** + * Records one cascade: a node whose failure or blocking rule violation suppressed + * rule evaluation for itself (if schema/hierarchy caused it) and/or its hierarchy subtree. + */ +export type CoverageGate = { + /** Label (file) of the node whose failure triggered this gate. */ + file: string; + /** Title of the blocking node. */ + nodeTitle: string; + /** What kind of check triggered the gate. */ + reason: 'schema' | 'hierarchy' | 'rule'; + /** Rule id responsible, when `reason` is `'rule'`. */ + ruleId?: string; + /** Labels of nodes whose rule evaluation was suppressed as a result of this gate. */ + gatedFiles: string[]; +}; + +export type GatedRuleEvaluation = { + violations: RuleViolation[]; + gates: CoverageGate[]; +}; + +/** + * Compute breadth-first depth (1-based, from hierarchy roots and orphans) for every + * hierarchy-typed node in the graph. Non-hierarchy nodes are not included. + */ +export function computeHierarchyDepths(graph: SpaceGraph): Map { + const depths = new Map(); + const queue: Array<{ title: string; depth: number }> = []; + for (const node of [...graph.hierarchyRoots, ...graph.orphans]) { + queue.push({ title: node.title, depth: 1 }); + } + + let i = 0; + while (i < queue.length) { + const { title, depth } = queue[i++]!; + if (depths.has(title)) continue; + depths.set(title, depth); + for (const child of graph.hierarchyChildren.get(title) ?? []) { + if (!depths.has(child.title)) queue.push({ title: child.title, depth: depth + 1 }); + } + } + + return depths; +} + +/** + * Evaluate executable rules with cascade gating: a schema, hierarchy, or blocking-rule + * failure on a node suppresses rule evaluation for that node (when the failure is + * schema/hierarchy) and its hierarchy subtree, unless `includeGated` is set. + * + * Traversal is breadth-first from hierarchy roots and orphans. Non-hierarchy nodes + * (not part of the hierarchy DAG) are always evaluated — cascade gating only applies + * within hierarchy subtrees. Global-scope rules always run, unaffected by gating. + */ +export async function evaluateRulesWithGating( + nodes: SpaceNode[], + rules: Rule[], + graph: SpaceGraph, + seeds: GatingSeed[], + options: { includeGated?: boolean } = {}, +): Promise { + const includeGated = options.includeGated ?? false; + + const nodeIndex = new Map(); + for (const node of nodes) { + if (node.title) nodeIndex.set(node.title, node); + } + + // When a node has both a schema and hierarchy failure, report schema as the reason. + const seedByTitle = new Map(); + for (const seed of seeds) { + if (!seedByTitle.has(seed.title) || seed.reason === 'schema') { + seedByTitle.set(seed.title, seed); + } + } + + const violations: RuleViolation[] = []; + const gateOrigins = new Map(); + + function originFor( + title: string, + seed: { file: string; reason: CoverageGate['reason']; ruleId?: string }, + ): CoverageGate { + let origin = gateOrigins.get(title); + if (!origin) { + origin = { file: seed.file, nodeTitle: title, reason: seed.reason, ruleId: seed.ruleId, gatedFiles: [] }; + gateOrigins.set(title, origin); + } + return origin; + } + + const globalRules = rules.filter((r) => r.scope === 'global'); + const sentinel = nodes[0]; + if (sentinel) { + for (const rule of globalRules) { + const context = buildEvalContext(sentinel, nodes, nodeIndex); + const result = await evaluateExpression(rule.check, context); + if (result !== true) { + violations.push({ + file: '', + ruleId: rule.id, + category: rule.category, + severity: ruleSeverity(rule), + description: rule.description, + }); + } + } + } + + const perNodeRules = rules.filter((r) => r.scope !== 'global'); + + async function evaluateApplicableRules(node: SpaceNode): Promise<{ blockingRuleId?: string }> { + let blockingRuleId: string | undefined; + const applicable = perNodeRules.filter((r) => !r.type || r.type === node.resolvedType); + for (const rule of applicable) { + const context = buildEvalContext(node, nodes, nodeIndex); + const result = await evaluateExpression(rule.check, context); + if (result !== true) { + violations.push({ + file: node.label, + ruleId: rule.id, + category: rule.category, + severity: ruleSeverity(rule), + description: rule.description, + }); + if (ruleGatesDescendants(rule) && !blockingRuleId) { + blockingRuleId = rule.id; + } + } + } + return { blockingRuleId }; + } + + // Non-hierarchy nodes sit outside the subtree cascade — always evaluated, never gated. + for (const node of graph.nonHierarchy) { + await evaluateApplicableRules(node); + } + + const visited = new Set(); + const queue: Array<{ node: SpaceNode; ancestorOrigin?: string }> = []; + for (const node of [...graph.hierarchyRoots, ...graph.orphans]) { + queue.push({ node, ancestorOrigin: undefined }); + } + + let qi = 0; + while (qi < queue.length) { + const { node, ancestorOrigin } = queue[qi++]!; + if (visited.has(node.title)) continue; + visited.add(node.title); + + const selfSeed = seedByTitle.get(node.title); + const isGatedByAncestor = ancestorOrigin !== undefined; + const isSelfBlocked = selfSeed !== undefined; + const isGated = isGatedByAncestor || isSelfBlocked; + const shouldEvaluate = !isGated || includeGated; + + const { blockingRuleId } = shouldEvaluate ? await evaluateApplicableRules(node) : {}; + + let childOrigin: string | undefined = ancestorOrigin; + if (isGatedByAncestor) { + gateOrigins.get(ancestorOrigin!)!.gatedFiles.push(node.label); + } else if (isSelfBlocked) { + const origin = originFor(node.title, { file: selfSeed!.file, reason: selfSeed!.reason }); + origin.gatedFiles.push(node.label); + childOrigin = node.title; + } else if (blockingRuleId) { + originFor(node.title, { file: node.label, reason: 'rule', ruleId: blockingRuleId }); + childOrigin = node.title; + } else { + childOrigin = undefined; + } + + for (const child of graph.hierarchyChildren.get(node.title) ?? []) { + queue.push({ node: child, ancestorOrigin: childOrigin }); + } + } + + return { violations, gates: [...gateOrigins.values()].filter((g) => g.gatedFiles.length > 0) }; +} diff --git a/src/schema/metadata-contract.ts b/src/schema/metadata-contract.ts index 2f78beb..41cc0db 100644 --- a/src/schema/metadata-contract.ts +++ b/src/schema/metadata-contract.ts @@ -66,6 +66,8 @@ const RULE_SCHEMA = { type: { type: 'string', minLength: 1 }, scope: { enum: ['global'] }, override: { type: 'boolean' }, + /** Whether a violation of this rule gates (suppresses) downstream checks on the node's hierarchy subtree. Defaults to true for `error` severity rules and false otherwise. */ + gatesDescendants: { type: 'boolean' }, }, required: ['id', 'category', 'description', 'check'], additionalProperties: false, diff --git a/src/types.ts b/src/types.ts index 6d8bdc8..2401a6c 100644 --- a/src/types.ts +++ b/src/types.ts @@ -191,6 +191,7 @@ export type RuleCategory = 'validation' | 'coherence' | 'workflow' | 'best-pract */ export type RuleSeverity = 'error' | 'warning' | 'info'; +export type { CoverageGate, GatingSeed } from './schema/gating'; export type { Rule } from './schema/metadata-contract'; export type RuleViolation = { diff --git a/src/validate.ts b/src/validate.ts index bd38039..26bdc62 100644 --- a/src/validate.ts +++ b/src/validate.ts @@ -2,12 +2,14 @@ import { isAbsolute, relative, resolve } from 'node:path'; import type { ErrorObject } from 'ajv'; import type { Config, SpaceConfig } from './config'; import { readSpace } from './read/read-space'; +import { computeHierarchyDepths, evaluateRulesWithGating, type GatingSeed } from './schema/gating'; import { extractEntityInfo } from './schema/schema'; import { validateGraph } from './schema/validate-graph'; import { validateRules } from './schema/validate-rules'; import { createSpaceContext } from './space-context'; import { buildSpaceGraph } from './space-graph'; import type { + CoverageGate, FileNotInSpaceResult, FileValidationIssue, FileValidationResult, @@ -15,6 +17,7 @@ import type { ParseIssue, ReadSpaceResult, RuleViolation, + SchemaMetadata, SchemaWithMetadata, SpaceContext, SpaceNode, @@ -39,6 +42,16 @@ export interface ValidationResult { parseIssues: ParseIssue[]; /** Content links that could not be resolved to a space node. Warning only — not counted in errors. */ unresolvedContentLinks: Array<{ file: string; target: string }>; + /** + * Cascade gates: nodes whose schema/hierarchy failure or blocking rule violation + * suppressed rule evaluation for themselves and/or their hierarchy subtree. + * See docs/rules.md for gating semantics. + */ + coverageGates: CoverageGate[]; + /** Nodes excluded from validation entirely by a `depth` limit (breadth-first from hierarchy roots). */ + skippedByDepth: Array<{ file: string; title: string }>; + /** The depth limit applied, if any (undefined means the full space was validated). */ + depthLimit?: number; } /** @@ -146,19 +159,55 @@ export function formatErrors( return formatted; } +/** + * Evaluate a space's executable rules. With a main hierarchy, evaluation cascades: schema, hierarchy + * and gating-rule failures (the `seeds`) suppress rule evaluation for the failing node's subtree. + * Shared by `validateSpace` and `validateFile` so both report identical rule results for a node. + */ +async function evaluateSpaceRules( + nodes: SpaceNode[], + metadata: SchemaMetadata, + seeds: GatingSeed[], + options: { includeGated?: boolean } = {}, +): Promise<{ violations: RuleViolation[]; gates: CoverageGate[] }> { + if (!metadata.rules) return { violations: [], gates: [] }; + if (!metadata.hierarchy) return { violations: await validateRules(nodes, metadata.rules), gates: [] }; + const graph = buildSpaceGraph(nodes, metadata.hierarchy); + return evaluateRulesWithGating(nodes, metadata.rules, graph, seeds, options); +} + /** * Run full validation on a space and return a structured result. * Does not output to console or call process.exit. */ export async function validateSpace( context: SpaceContext, - options: { readResult?: ReadSpaceResult } = {}, + options: { readResult?: ReadSpaceResult; depth?: number; includeGated?: boolean } = {}, ): Promise { const { schema, schemaRefRegistry, schemaValidator } = context; const metadata = schema.metadata; const readResult = options.readResult ?? (await readSpace(context)); - const { nodes, parseIssues } = readResult; + const { parseIssues } = readResult; + let nodes = readResult.nodes; + + // Depth limiting: evaluate only hierarchy nodes within N breadth-first levels from the + // top. Non-hierarchy nodes are unaffected — depth scoping only applies to the hierarchy DAG. + const skippedByDepth: Array<{ file: string; title: string }> = []; + if (options.depth !== undefined && metadata.hierarchy) { + const fullGraph = buildSpaceGraph(nodes, metadata.hierarchy); + const depths = computeHierarchyDepths(fullGraph); + const included: SpaceNode[] = []; + for (const node of nodes) { + const nodeDepth = depths.get(node.title); + if (nodeDepth !== undefined && nodeDepth > options.depth) { + skippedByDepth.push({ file: node.label, title: node.title }); + } else { + included.push(node); + } + } + nodes = included; + } // Pre-extract valid types for early type validation const validTypes = Array.isArray(schema.oneOf) ? extractEntityInfo(schema, schemaRefRegistry).map((e) => e.type) : []; @@ -174,6 +223,9 @@ export async function validateSpace( orphans: [], parseIssues, unresolvedContentLinks: [], + coverageGates: [], + skippedByDepth, + depthLimit: options.depth, }; for (const node of nodes) { @@ -239,9 +291,19 @@ export async function validateSpace( result.orphans.push(...buildSpaceGraph(nodes, hierarchy).orphans); } - // Load and execute rules validation if schema defines rules + // Load and execute rules validation if schema defines rules (with cascade gating, see docs/rules.md). if (metadata.rules) { - result.ruleViolations = await validateRules(nodes, metadata.rules); + const seeds: GatingSeed[] = [ + ...result.nodeErrors.map( + (e): GatingSeed => ({ file: e.file, title: String(e.nodeData.title ?? e.file), reason: 'schema' }), + ), + ...result.hierarchyViolations.map((v): GatingSeed => ({ file: v.file, title: v.nodeTitle, reason: 'hierarchy' })), + ]; + const { violations, gates } = await evaluateSpaceRules(nodes, metadata, seeds, { + includeGated: options.includeGated, + }); + result.ruleViolations = violations; + result.coverageGates = gates; } // Collect unresolved content links (warnings — not errors) @@ -288,7 +350,7 @@ function resolveFileSpace(filePath: string, config: Config): { space: SpaceConfi export async function validateFile( filePath: string, config: Config, - options: { configDir?: string } = {}, + options: { configDir?: string; includeGated?: boolean } = {}, ): Promise { const resolved = resolveFileSpace(filePath, config); @@ -378,15 +440,44 @@ export async function validateFile( } } - // Rule violations for this node — only error severity counts as an error + // Rule violations for this node — only error severity counts as an error. + // Rules are evaluated for the whole space with the same cascade gating as `validateSpace`, then + // restricted to this file, so a file's rule results match its entry in a full `validate` run. if (metadata.rules) { - const ruleViolations = await validateRules(nodes, metadata.rules); - for (const v of ruleViolations) { + const seeds: GatingSeed[] = [ + ...nodes + .filter((node) => { + const nodeType = (node.schemaData as Record).type as string | undefined; + const invalidType = nodeType !== undefined && validTypes.length > 0 && !validTypes.includes(nodeType); + return invalidType || !schemaValidator(node.schemaData); + }) + .map((node): GatingSeed => { + const file = node.source?.file ?? node.label; + return { file, title: String(node.schemaData.title ?? file), reason: 'schema' }; + }), + ...hierarchyValidation.violations.map( + (v): GatingSeed => ({ file: v.file, title: v.nodeTitle, reason: 'hierarchy' }), + ), + ]; + const { violations, gates } = await evaluateSpaceRules(nodes, metadata, seeds, { + includeGated: options.includeGated, + }); + for (const v of violations) { if (v.file === label) { const target = v.severity === 'error' ? errors : warnings; target[`rule:${v.ruleId}`] = { kind: 'rule', message: `[${v.ruleId}] ${v.description}`, severity: v.severity }; } } + // A gated file with no violations would otherwise look clean — say that its rules were not checked. + for (const gate of gates) { + if (!gate.gatedFiles.includes(label)) continue; + const cause = gate.reason === 'rule' ? `blocking rule "${gate.ruleId}"` : `${gate.reason} failure`; + warnings[`gated:${gate.file}`] = { + kind: 'gated', + message: `Rule checks ${options.includeGated ? 'evaluated anyway' : 'not evaluated'}: gated by ${cause} on ${gate.file}`, + severity: 'info', + }; + } } // Unresolved content links for this node (warnings — do not affect errorCount) diff --git a/tests/fixtures/depth-relationship/Assume.md b/tests/fixtures/depth-relationship/Assume.md new file mode 100644 index 0000000..fac22d9 --- /dev/null +++ b/tests/fixtures/depth-relationship/Assume.md @@ -0,0 +1,5 @@ +--- +type: assumption +title: Assume A +parent: ["[[Opp A]]"] +--- diff --git a/tests/fixtures/depth-relationship/Goal.md b/tests/fixtures/depth-relationship/Goal.md new file mode 100644 index 0000000..2a5a9b6 --- /dev/null +++ b/tests/fixtures/depth-relationship/Goal.md @@ -0,0 +1,4 @@ +--- +type: goal +title: Goal A +--- diff --git a/tests/fixtures/depth-relationship/Opp.md b/tests/fixtures/depth-relationship/Opp.md new file mode 100644 index 0000000..e4542a6 --- /dev/null +++ b/tests/fixtures/depth-relationship/Opp.md @@ -0,0 +1,5 @@ +--- +type: opportunity +title: Opp A +parent: "[[Goal A]]" +--- diff --git a/tests/fixtures/strict_ost/gating-directory/Bad Outcome.md b/tests/fixtures/strict_ost/gating-directory/Bad Outcome.md new file mode 100644 index 0000000..a424e19 --- /dev/null +++ b/tests/fixtures/strict_ost/gating-directory/Bad Outcome.md @@ -0,0 +1,6 @@ +--- +type: outcome +status: active +--- + +Missing the required "metric" field — fails schema validation. diff --git a/tests/fixtures/strict_ost/gating-directory/Child Opportunity.md b/tests/fixtures/strict_ost/gating-directory/Child Opportunity.md new file mode 100644 index 0000000..7f66c80 --- /dev/null +++ b/tests/fixtures/strict_ost/gating-directory/Child Opportunity.md @@ -0,0 +1,8 @@ +--- +type: opportunity +status: active +parent: "[[Bad Outcome]]" +source: Interview with Sam, 2024-05-01 +--- + +Only one solution is explored below — would violate the solution-quantity rule if evaluated. diff --git a/tests/fixtures/strict_ost/gating-directory/Only Solution.md b/tests/fixtures/strict_ost/gating-directory/Only Solution.md new file mode 100644 index 0000000..c64d2c4 --- /dev/null +++ b/tests/fixtures/strict_ost/gating-directory/Only Solution.md @@ -0,0 +1,7 @@ +--- +type: solution +status: exploring +parent: "[[Child Opportunity]]" +--- + +A single candidate solution. diff --git a/tests/schema/gating.test.ts b/tests/schema/gating.test.ts new file mode 100644 index 0000000..515e164 --- /dev/null +++ b/tests/schema/gating.test.ts @@ -0,0 +1,188 @@ +import { describe, expect, it } from 'bun:test'; +import { + computeHierarchyDepths, + evaluateRulesWithGating, + type GatingSeed, + ruleGatesDescendants, +} from '../../src/schema/gating'; +import { buildSpaceGraph } from '../../src/space-graph'; +import type { Rule, SpaceNode } from '../../src/types'; +import { makeHierarchy, makeLevel, makeParentRef } from '../test-helpers'; + +const hierarchy = makeHierarchy([makeLevel('goal'), makeLevel('opportunity'), makeLevel('solution')]); + +function makeSpaceNode(title: string, type: string, parent?: string): SpaceNode { + return { + label: `${title}.md`, + title, + type, + schemaData: { title, type, status: 'active' }, + linkTargets: [title], + resolvedType: type, + resolvedParents: parent ? [makeParentRef(parent)] : [], + resolvedLinks: [], + }; +} + +describe('computeHierarchyDepths', () => { + it('assigns depth 1 to roots and orphans, incrementing per hierarchy level', () => { + const goal = makeSpaceNode('Goal', 'goal'); + const opp = makeSpaceNode('Opp', 'opportunity', 'Goal'); + const sol = makeSpaceNode('Sol', 'solution', 'Opp'); + const orphanOpp = makeSpaceNode('Orphan Opp', 'opportunity'); + const graph = buildSpaceGraph([goal, opp, sol, orphanOpp], hierarchy); + + const depths = computeHierarchyDepths(graph); + expect(depths.get('Goal')).toBe(1); + expect(depths.get('Opp')).toBe(2); + expect(depths.get('Sol')).toBe(3); + expect(depths.get('Orphan Opp')).toBe(1); + }); +}); + +describe('evaluateRulesWithGating', () => { + const alwaysFailRule: Rule = { + id: 'always-fail', + category: 'validation', + description: 'always fails', + check: 'false', + }; + const nonBlockingFailRule: Rule = { + id: 'non-gating', + category: 'validation', + description: 'fails but does not block', + check: 'false', + gatesDescendants: false, + }; + const passRule: Rule = { + id: 'always-pass', + category: 'validation', + description: 'always passes', + check: 'true', + }; + + function buildTree() { + const goal = makeSpaceNode('Goal', 'goal'); + const opp = makeSpaceNode('Opp', 'opportunity', 'Goal'); + const sol = makeSpaceNode('Sol', 'solution', 'Opp'); + const nodes = [goal, opp, sol]; + const graph = buildSpaceGraph(nodes, hierarchy); + return { goal, opp, sol, nodes, graph }; + } + + it('gates a node and its subtree when the node has a schema failure', async () => { + const { goal, nodes, graph } = buildTree(); + const seeds: GatingSeed[] = [{ file: goal.label, title: goal.title, reason: 'schema' }]; + + const { violations, gates } = await evaluateRulesWithGating(nodes, [alwaysFailRule], graph, seeds); + + // Goal itself is gated (schema failure suppresses its own rule layer) — no violation recorded for it. + expect(violations.find((v) => v.file === 'Goal.md')).toBeUndefined(); + expect(violations.find((v) => v.file === 'Opp.md')).toBeUndefined(); + expect(violations.find((v) => v.file === 'Sol.md')).toBeUndefined(); + + expect(gates).toHaveLength(1); + expect(gates[0]).toMatchObject({ file: 'Goal.md', nodeTitle: 'Goal', reason: 'schema' }); + expect(gates[0]!.gatedFiles).toEqual(['Goal.md', 'Opp.md', 'Sol.md']); + }); + + it('gates a subtree when a hierarchy violation is seeded, but not the node itself', async () => { + const { nodes, graph, opp } = buildTree(); + const seeds: GatingSeed[] = [{ file: opp.label, title: opp.title, reason: 'hierarchy' }]; + + const { violations, gates } = await evaluateRulesWithGating(nodes, [passRule], graph, seeds); + + expect(violations).toHaveLength(0); + expect(violations.find((v) => v.file === 'Opp.md')).toBeUndefined(); + expect(violations.find((v) => v.file === 'Sol.md')).toBeUndefined(); + + expect(gates).toHaveLength(1); + expect(gates[0]).toMatchObject({ file: 'Opp.md', nodeTitle: 'Opp', reason: 'hierarchy' }); + expect(gates[0]!.gatedFiles).toEqual(['Opp.md', 'Sol.md']); + }); + + it('a blocking rule violation gates descendants but not the violating node itself', async () => { + const { nodes, graph } = buildTree(); + + const { violations, gates } = await evaluateRulesWithGating(nodes, [alwaysFailRule], graph, []); + + // All three nodes are evaluated (nothing gates the root); goal's failure then gates its subtree. + expect(violations.map((v) => v.file)).toEqual(['Goal.md']); + expect(gates).toHaveLength(1); + expect(gates[0]).toMatchObject({ file: 'Goal.md', nodeTitle: 'Goal', reason: 'rule', ruleId: 'always-fail' }); + expect(gates[0]!.gatedFiles).toEqual(['Opp.md', 'Sol.md']); + }); + + it('a rule with gatesDescendants:false fails without gating descendants', async () => { + const { nodes, graph } = buildTree(); + + const { violations, gates } = await evaluateRulesWithGating(nodes, [nonBlockingFailRule], graph, []); + + // All nodes evaluated and all fail, since nothing gates. + expect(violations.map((v) => v.file)).toEqual(['Goal.md', 'Opp.md', 'Sol.md']); + expect(gates).toHaveLength(0); + }); + + it('gatesDescendants defaults from severity: error gates, warning and info do not, explicit value overrides', async () => { + const advisory: Rule = { id: 'advisory', category: 'best-practice', description: 'info', check: 'false' }; + const warning: Rule = { id: 'warn', category: 'coherence', description: 'warning', check: 'false' }; + expect(ruleGatesDescendants(alwaysFailRule)).toBe(true); + expect(ruleGatesDescendants(advisory)).toBe(false); + expect(ruleGatesDescendants(warning)).toBe(false); + expect(ruleGatesDescendants({ ...advisory, gatesDescendants: true })).toBe(true); + expect(ruleGatesDescendants({ ...alwaysFailRule, gatesDescendants: false })).toBe(false); + expect(ruleGatesDescendants({ ...alwaysFailRule, severity: 'warning' })).toBe(false); + + const { nodes, graph } = buildTree(); + const advisoryRun = await evaluateRulesWithGating(nodes, [advisory], graph, []); + expect(advisoryRun.violations.map((v) => v.file)).toEqual(['Goal.md', 'Opp.md', 'Sol.md']); + expect(advisoryRun.gates).toHaveLength(0); + + const forcedRun = await evaluateRulesWithGating(nodes, [{ ...advisory, gatesDescendants: true }], graph, []); + expect(forcedRun.violations.map((v) => v.file)).toEqual(['Goal.md']); + expect(forcedRun.gates).toHaveLength(1); + }); + + it('includeGated evaluates rules on gated nodes but still reports the gate', async () => { + const { goal, nodes, graph } = buildTree(); + const seeds: GatingSeed[] = [{ file: goal.label, title: goal.title, reason: 'schema' }]; + + const { violations, gates } = await evaluateRulesWithGating(nodes, [passRule], graph, seeds, { + includeGated: true, + }); + + // passRule succeeds everywhere, so no violations — but the gate is still recorded because + // Goal's schema failure would have suppressed evaluation by default. + expect(violations).toHaveLength(0); + expect(gates).toHaveLength(1); + expect(gates[0]!.gatedFiles).toEqual(['Goal.md', 'Opp.md', 'Sol.md']); + }); + + it('never gates non-hierarchy nodes', async () => { + const { goal, nodes } = buildTree(); + const standalone = makeSpaceNode('Standalone', 'note'); + const allNodes = [...nodes, standalone]; + const fullGraph = buildSpaceGraph(allNodes, hierarchy); + const seeds: GatingSeed[] = [{ file: goal.label, title: goal.title, reason: 'schema' }]; + + const { violations } = await evaluateRulesWithGating(allNodes, [alwaysFailRule], fullGraph, seeds); + + expect(violations.find((v) => v.file === 'Standalone.md')).toBeDefined(); + }); + + it('always evaluates global-scope rules regardless of gating', async () => { + const { goal, nodes, graph } = buildTree(); + const globalRule: Rule = { + id: 'global-fail', + category: 'workflow', + description: 'fails globally', + check: 'false', + scope: 'global', + }; + const seeds: GatingSeed[] = [{ file: goal.label, title: goal.title, reason: 'schema' }]; + + const { violations } = await evaluateRulesWithGating(nodes, [globalRule], graph, seeds); + + expect(violations.find((v) => v.ruleId === 'global-fail')).toBeDefined(); + }); +}); diff --git a/tests/validate/gating.test.ts b/tests/validate/gating.test.ts new file mode 100644 index 0000000..01a48e2 --- /dev/null +++ b/tests/validate/gating.test.ts @@ -0,0 +1,142 @@ +import { describe, expect, it } from 'bun:test'; +import { readdirSync } from 'node:fs'; +import { join } from 'node:path'; +import type { Config } from '../../src/config'; +import { bundledSchemasDir } from '../../src/schema/schema'; +import { validateFile, validateSpace } from '../../src/validate'; +import { makeSpaceContext } from '../helpers/context'; + +const SCHEMA_PATH = join(bundledSchemasDir, 'strict_ost.json'); +const VALID_DIR = join(import.meta.dir, '../fixtures/strict_ost/valid-directory'); +const GATING_DIR = join(import.meta.dir, '../fixtures/strict_ost/gating-directory'); + +describe('validateSpace cascade gating', () => { + it('gates rule evaluation on the subtree beneath a schema-failing node by default', async () => { + const context = makeSpaceContext(GATING_DIR, SCHEMA_PATH); + const result = await validateSpace(context); + + // Bad Outcome fails schema validation (missing required "metric"). + expect(result.nodeErrors.some((e) => e.file === 'Bad Outcome.md')).toBe(true); + + // Child Opportunity would otherwise violate solution-quantity (only one solution below), + // but its rule evaluation is gated by the ancestor's schema failure. + expect(result.ruleViolations.some((v) => v.file === 'Child Opportunity.md')).toBe(false); + + const gate = result.coverageGates.find((g) => g.file === 'Bad Outcome.md'); + expect(gate).toBeDefined(); + expect(gate!.reason).toBe('schema'); + expect(gate!.gatedFiles).toEqual( + expect.arrayContaining(['Bad Outcome.md', 'Child Opportunity.md', 'Only Solution.md']), + ); + }); + + it('evaluates gated rules anyway when includeGated is set, while still reporting the gate', async () => { + const context = makeSpaceContext(GATING_DIR, SCHEMA_PATH); + const result = await validateSpace(context, { includeGated: true }); + + expect( + result.ruleViolations.some((v) => v.file === 'Child Opportunity.md' && v.ruleId === 'solution-quantity'), + ).toBe(true); + + const gate = result.coverageGates.find((g) => g.file === 'Bad Outcome.md'); + expect(gate).toBeDefined(); + expect(gate!.gatedFiles).toContain('Child Opportunity.md'); + }); + + it('does not gate on a non-error rule violation by default (solution-quantity is best-practice)', async () => { + // The fixture opportunity has only one solution below it, violating solution-quantity. + // That rule is info severity, so it doesn't block and the solution's own rules still run. + const context = makeSpaceContext(VALID_DIR, SCHEMA_PATH); + const result = await validateSpace(context); + + expect(result.nodeErrorCount).toBe(0); + expect(result.ruleViolations.some((v) => v.ruleId === 'solution-quantity')).toBe(true); + expect(result.coverageGates).toEqual([]); + }); +}); + +describe('validateSpace depth limiting', () => { + it('excludes nodes beyond the requested breadth-first depth', async () => { + const context = makeSpaceContext(VALID_DIR, SCHEMA_PATH); + const full = await validateSpace(context); + const shallow = await validateSpace(context, { depth: 1 }); + + expect(shallow.skippedByDepth.length).toBeGreaterThan(0); + expect(shallow.skippedByDepth.length + shallow.validCount + shallow.nodeErrorCount).toBe( + full.validCount + full.nodeErrorCount, + ); + expect(shallow.depthLimit).toBe(1); + // Only the outcome (root) node remains. + expect(shallow.skippedByDepth.map((s) => s.title)).toEqual( + expect.arrayContaining(['Sign-up is too complex', 'Simplify sign-up flow', 'Usability test']), + ); + }); + + it('does not report broken links for relationship children of a depth-excluded hierarchy node', async () => { + // Assume A is a relationship child (non-hierarchy) of Opp A, which depth 1 excludes. + const context = makeSpaceContext( + join(import.meta.dir, '../fixtures/depth-relationship'), + join(bundledSchemasDir, 'strategy_general.json'), + ); + const result = await validateSpace(context, { depth: 1 }); + expect(result.skippedByDepth.map((s) => s.title)).toEqual(['Opp A']); + expect(result.refErrors).toEqual([]); + expect(result.hierarchyViolations).toEqual([]); + }); + + it('does not affect validation when depth is unset', async () => { + const context = makeSpaceContext(VALID_DIR, SCHEMA_PATH); + const result = await validateSpace(context); + expect(result.depthLimit).toBeUndefined(); + expect(result.skippedByDepth).toEqual([]); + }); +}); + +describe('validateFile matches validateSpace', () => { + for (const [name, dir] of [ + ['gating-directory', GATING_DIR], + ['valid-directory', VALID_DIR], + ] as const) { + for (const includeGated of [false, true]) { + it(`reports each file's rule results and gating as the full run does (${name}, includeGated=${includeGated})`, async () => { + const config: Config = { spaces: [{ name: 'space', path: dir, schema: SCHEMA_PATH }] }; + const space = await validateSpace(makeSpaceContext(dir, SCHEMA_PATH), { includeGated }); + + for (const file of readdirSync(dir).filter((f) => f.endsWith('.md'))) { + const result = await validateFile(join(dir, file), config, { includeGated, configDir: import.meta.dir }); + if (!result.inSpace) throw new Error(`expected ${file} to be in space`); + + const fileRules = Object.keys({ ...result.errors, ...result.warnings }) + .filter((k) => k.startsWith('rule:')) + .map((k) => k.slice('rule:'.length)) + .sort(); + const spaceRules = space.ruleViolations + .filter((v) => v.file === file) + .map((v) => v.ruleId) + .sort(); + expect(fileRules).toEqual(spaceRules); + + const fileGated = Object.keys(result.warnings).some((k) => k.startsWith('gated:')); + const spaceGated = space.coverageGates.some((g) => g.gatedFiles.includes(file)); + expect(fileGated).toBe(spaceGated); + } + }); + } + } + + it('reports a gated file as not evaluated rather than clean', async () => { + const config: Config = { spaces: [{ name: 'space', path: GATING_DIR, schema: SCHEMA_PATH }] }; + const result = await validateFile(join(GATING_DIR, 'Child Opportunity.md'), config, { configDir: import.meta.dir }); + if (!result.inSpace) throw new Error('expected file to be in space'); + expect(result.warnings['gated:Bad Outcome.md']?.message).toContain('not evaluated'); + expect(result.warnings['rule:solution-quantity']).toBeUndefined(); + + const forced = await validateFile(join(GATING_DIR, 'Child Opportunity.md'), config, { + includeGated: true, + configDir: import.meta.dir, + }); + if (!forced.inSpace) throw new Error('expected file to be in space'); + expect(forced.warnings['gated:Bad Outcome.md']?.message).toContain('evaluated anyway'); + expect(forced.warnings['rule:solution-quantity']).toBeDefined(); + }); +}); From c76e802feee8e6068636be41aac3952d04a1b029 Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Tue, 13 Oct 2026 18:00:49 +1100 Subject: [PATCH 2/2] chore: update biome to 2.5.15 and fix lint error in schema-composition test --- biome.json | 2 +- bun.lock | 20 ++++++++++---------- package.json | 2 +- tests/schema/schema-composition.test.ts | 2 +- tests/validate/dates.test.ts | 13 ++++++------- 5 files changed, 19 insertions(+), 20 deletions(-) diff --git a/biome.json b/biome.json index bfd6a34..5d26166 100644 --- a/biome.json +++ b/biome.json @@ -1,5 +1,5 @@ { - "$schema": "https://biomejs.dev/schemas/2.5.1/schema.json", + "$schema": "https://biomejs.dev/schemas/2.5.15/schema.json", "vcs": { "enabled": true, "clientKind": "git", diff --git a/bun.lock b/bun.lock index 918b65b..7de6dc9 100644 --- a/bun.lock +++ b/bun.lock @@ -21,7 +21,7 @@ }, "devDependencies": { "@anthropic-ai/claude-agent-sdk": "^0.3.191", - "@biomejs/biome": "^2.5.1", + "@biomejs/biome": "^2.5.15", "@types/bun": "latest", "@types/js-yaml": "^4.0.9", "json-schema-to-ts": "^3.1.1", @@ -56,23 +56,23 @@ "@babel/runtime": ["@babel/runtime@7.28.6", "", {}, "sha512-05WQkdpL9COIMz4LjTxGpPNCdlpyimKppYNoJ5Di5EUObifl8t4tuLuUBBZEpoLYOmfvIWrsp9fCl0HoPRVTdA=="], - "@biomejs/biome": ["@biomejs/biome@2.5.1", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.5.1", "@biomejs/cli-darwin-x64": "2.5.1", "@biomejs/cli-linux-arm64": "2.5.1", "@biomejs/cli-linux-arm64-musl": "2.5.1", "@biomejs/cli-linux-x64": "2.5.1", "@biomejs/cli-linux-x64-musl": "2.5.1", "@biomejs/cli-win32-arm64": "2.5.1", "@biomejs/cli-win32-x64": "2.5.1" }, "bin": { "biome": "bin/biome" } }, "sha512-IXWLCxKmae+rI7LOHS1B3EbVisQ6GRAWbhN9msa6KjNCyFWrvKZWR4oUdinaNssrV852OrSHuSPa95h1GPJc7Q=="], + "@biomejs/biome": ["@biomejs/biome@2.5.15", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.5.15", "@biomejs/cli-darwin-x64": "2.5.15", "@biomejs/cli-linux-arm64": "2.5.15", "@biomejs/cli-linux-arm64-musl": "2.5.15", "@biomejs/cli-linux-x64": "2.5.15", "@biomejs/cli-linux-x64-musl": "2.5.15", "@biomejs/cli-win32-arm64": "2.5.15", "@biomejs/cli-win32-x64": "2.5.15" }, "bin": { "biome": "bin/biome" } }, "sha512-WZTW4slm/pdkh92K6t/3aEN++44JD1PQ7squ7RCMLI1flHGl43DVOIGXvCjHiZgBMO1V4uYxoFNtqrIA4qGuIQ=="], - "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.5.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-npqDzvqv7vFaWRiNN1Te71siRgPaqS9MpqgYCdP/CrUbkJ7ApezaeaKjueKHRN/JH/6lRjJQAHi8acQDCAz22w=="], + "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.5.15", "", { "os": "darwin", "cpu": "arm64" }, "sha512-BZVzFhJ/mUvTLMYbc9x6el0o2Uv5zP7bACYyhFb6fSc1giroXm7PL0a5KqMJ9F+/BnkYRjagD/ROSDVOZ6eapg=="], - "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.5.1", "", { "os": "darwin", "cpu": "x64" }, "sha512-RgwTqPAM8g2tn1j+b5oRjF/DbSBX8a4gwojtuG9XuhfK7GgomvZ9+T+tqjXiVbjLEeGJOoL6VEk8mvRTVeSybw=="], + "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.5.15", "", { "os": "darwin", "cpu": "x64" }, "sha512-V5Kw63V+fVGNFhFrizDxMbGXAzZCh8kYzJpy3GI6gTapWDg7bZK9oYC9CbVgQSEdTnupz0U5Efz8Ev+5vdBBXw=="], - "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.5.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-yhV35CzZh38VyMvTEXi3JTjxZBs++oCKK9KG8vB6VI5+uvQvZNR3BFWEKKzuOmx9DJJj7sQpZ4LQJcmbGTs3+Q=="], + "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.5.15", "", { "os": "linux", "cpu": "arm64" }, "sha512-XaG7P7eeSLYETD3K9grfB0mQmpLQZjygdbsxekWBJAg4am79fGAtRpfRyNnTvXB2fZFNnJZG3nXm7HBat0+VUw=="], - "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.5.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-WMcvMLgByyTqVxGlq918NBBYliq9FRR9GAQVETHb+VjGVqXCZFfHlZHC1FX4ibuYY/Hg6TJE3rHU0xVrdJXNRw=="], + "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.5.15", "", { "os": "linux", "cpu": "arm64" }, "sha512-tGzZUTcJCV7tj5Adh/Gn6nR4MycqA3iohq2LEcrarAgRBkU0h0OKd2UzCRkOsOYOuUGaUJb4YmqRqyy2feGGSw=="], - "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.5.1", "", { "os": "linux", "cpu": "x64" }, "sha512-J/7uHSX7NfoYDI7HijAkd8lnQIOrRb2W7j3X+tw4R+N5ExvXGsyXFiGdQcfcxfOmNQmZVSQOCDk757fwpzqQcg=="], + "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.5.15", "", { "os": "linux", "cpu": "x64" }, "sha512-xE4iEW/3LqlYj9GFgGrFsFSH51dEEpUbYWBfeOv0q87WkUDxK2o/HhreSb7qMJqck70RVM6Lg96hgedcAYcOkA=="], - "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.5.1", "", { "os": "linux", "cpu": "x64" }, "sha512-ANTowtlLmPYm5yeMckWY8Xzb9Ix+JJP3tgHR/n6xRj1VWyIzzWtfRfih9hv9VmClwadpBvZduISZIbBsIlYG3A=="], + "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.5.15", "", { "os": "linux", "cpu": "x64" }, "sha512-IlxUcyxilVGPsE008x13pWdkTbU3nQpP2i9b5UrbOYj6goBkKsRX1XB7yJLcV+O1H9LBchIIm4adOaVLZBX0ZQ=="], - "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.5.1", "", { "os": "win32", "cpu": "arm64" }, "sha512-zgXnKNgWPC4iPF7Y1lR3STUeCUuZRpD6IiOrC7TZTlh0Lx6FiVUT05myuMQHQ9D+1cc7uyMldi4forE6lp0ivQ=="], + "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.5.15", "", { "os": "win32", "cpu": "arm64" }, "sha512-2kPKzhNlm8C+Ru3GcO0Me2ODkCBLrVOUNuyi84RJyWDVKAA4+Kjj3jMjL938lF6BRfvltC4vB2nPY9SvN51Ovg=="], - "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.1", "", { "os": "win32", "cpu": "x64" }, "sha512-6uxpR9hvaglANkZemeSiN/FhYgkGasrEGn267eXIWvjrjJ2LhDlk251IhjVJq6MXzkV2/bcXwLwSroLyPtqRZg=="], + "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.15", "", { "os": "win32", "cpu": "x64" }, "sha512-yAzh4UqEImV6Hcy0zjUqNfJAsUhoD64FBQCdTG8Md/Z2wQeVP/ZmJ3XRYAs1g8J9fjTFyl2fCtc5FB5til47+g=="], "@hono/node-server": ["@hono/node-server@1.19.12", "", { "peerDependencies": { "hono": "^4" } }, "sha512-txsUW4SQ1iilgE0l9/e9VQWmELXifEFvmdA1j6WFh/aFPj99hIntrSsq/if0UWyGVkmrRPKA1wCeP+UCr1B9Uw=="], diff --git a/package.json b/package.json index b9eff78..9915c6a 100644 --- a/package.json +++ b/package.json @@ -52,7 +52,7 @@ }, "devDependencies": { "@anthropic-ai/claude-agent-sdk": "^0.3.191", - "@biomejs/biome": "^2.5.1", + "@biomejs/biome": "^2.5.15", "@types/bun": "latest", "@types/js-yaml": "^4.0.9", "json-schema-to-ts": "^3.1.1", diff --git a/tests/schema/schema-composition.test.ts b/tests/schema/schema-composition.test.ts index 2863e1c..b267b00 100644 --- a/tests/schema/schema-composition.test.ts +++ b/tests/schema/schema-composition.test.ts @@ -70,7 +70,7 @@ describe('schema composition metadata', () => { id: 'active-outcome-count', check: "$count(nodes[resolvedType='outcome' and status='active']) = 1", }); - expect((metadata.rules?.[0] as Record).override).toBeUndefined(); + expect((metadata.rules?.[0] as Record | undefined)?.override).toBeUndefined(); }); it('compiles schemas that import metadata', () => { diff --git a/tests/validate/dates.test.ts b/tests/validate/dates.test.ts index 2e1d5f2..dc11f9c 100644 --- a/tests/validate/dates.test.ts +++ b/tests/validate/dates.test.ts @@ -54,13 +54,12 @@ describe('dates and format validation', () => { }); describe('format: "date-time" schema validation', () => { - it.each([ - '2026-03-31T09:15:00Z', - '2026-03-31T09:15:00.250Z', - '2026-03-31T09:15:00+10:00', - ])('accepts %s', (value) => { - expect(validateNode({ type: 'note', title: 'Test', updated: value })).toBe(true); - }); + it.each(['2026-03-31T09:15:00Z', '2026-03-31T09:15:00.250Z', '2026-03-31T09:15:00+10:00'])( + 'accepts %s', + (value) => { + expect(validateNode({ type: 'note', title: 'Test', updated: value })).toBe(true); + }, + ); it.each([ '2026-03-31',