From 84368defebdcfa29f3f1a6f434be7fbbbeb4fb40 Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Sat, 26 Sep 2026 09:35:57 +1000 Subject: [PATCH 1/3] feat: rule severity levels with category defaults (#60) Rule violations now carry a severity of error, warning or info. Each rule category supplies a default (validation -> error, coherence and workflow -> warning, best-practice -> info), and a rule may set an optional `severity` field to override it. Only error severity violations fail validation: `validate` and `validate-file` exit non-zero and JSON output reports `valid: false` only for errors. Warning and info violations are still reported. - Add `severity` to the rule metadata contract and generated metaschema - Attach effective severity to RuleViolation; export severity types from the API - validate: per-severity summary counts, details grouped by severity, `ruleViolations` array in JSON output - validate-file: warning/info rule violations go under `warnings` - schemas show: list category default severity and per-rule overrides - Update docs, README and plugin skill references Claude-Session: https://claude.ai/code/session_01EJgagmpxDYVYr7fp9C6cZi --- README.md | 19 ++-- docs/api.md | 2 + docs/concepts.md | 2 + docs/rules.md | 50 ++++++++-- plugin/.claude-plugin/plugin.json | 2 +- .../structured-context/references/commands.md | 4 +- .../references/schema-authoring.md | 2 +- .../references/schema-design.md | 2 +- .../_structured_context_schema_meta.json | 3 + src/api.ts | 4 + src/commands/schemas.ts | 16 +-- src/commands/validate-file.ts | 14 ++- src/commands/validate.ts | 41 ++++---- src/schema/metadata-contract.ts | 1 + src/schema/schema.ts | 6 +- src/schema/validate-rules.ts | 25 ++++- src/types.ts | 24 ++++- src/validate.ts | 11 ++- .../rule-severity/clean/Clean goal.md | 4 + .../rule-severity/failing/Blocked goal.md | 4 + tests/fixtures/rule-severity/schema.json | 41 ++++++++ .../invalid-rule-severity.json | 23 +++++ tests/schema/schema-metadata.test.ts | 5 + tests/schema/validate-rules.test.ts | 43 +++++++- tests/validate/rule-severity.test.ts | 99 +++++++++++++++++++ 25 files changed, 385 insertions(+), 62 deletions(-) create mode 100644 tests/fixtures/rule-severity/clean/Clean goal.md create mode 100644 tests/fixtures/rule-severity/failing/Blocked goal.md create mode 100644 tests/fixtures/rule-severity/schema.json create mode 100644 tests/fixtures/schema-metadata/invalid-rule-severity.json create mode 100644 tests/validate/rule-severity.test.ts diff --git a/README.md b/README.md index ea65b88..d167fd9 100644 --- a/README.md +++ b/README.md @@ -28,10 +28,13 @@ Content and structure Schema validation errors 0 Broken links 1 Duplicate keys 0 - Rule violations 2 + Rule violations (error) 0 + Rule violations (warning) 1 + Rule violations (info) 1 Hierarchy violations 0 Orphans (hierarchy nodes - no parent) 1 - Ignored during parsing 0 + Unresolved content links 0 + Excluded during parsing 0 Orphans (hierarchy nodes - no parent): Solution looking for a problem.md @@ -40,13 +43,14 @@ Broken links: Steal underpants.md: [[Gnome goals]] → Link target "Gnome goals" in field "related" not found Rule violations: - workflow (1): - Build Death Star.md: Opportunities should contribute to at least one Outcome - - best-practice (1): - High tech juice press.md: Explore multiple candidate solutions (aim for at least three) for an active target opportunity + WARNING (1): + Build Death Star.md: Opportunities should contribute to at least one Outcome [workflow: opportunity-has-outcome] + INFO (1): + High tech juice press.md: Explore multiple candidate solutions (aim for at least three) for the target opportunity [best-practice: solution-quantity] ``` +Rule violations carry a severity (`error`, `warning` or `info`) that defaults from the rule's category. Only errors fail validation — see [docs/rules.md](docs/rules.md#categories-and-severity). + ## Installation Requires [Bun](https://bun.sh) runtime. @@ -183,6 +187,7 @@ Metadata is composable across `$ref` graphs: - `hierarchy`: multiple schema files may define a hierarchy; **last one wins** (root schema overrides partials) - `aliases` are shallow-merged (later wins) - `rules` merge by `id`; conflicts error unless the later rule sets `override: true` +- each rule's `category` supplies its default severity (`validation` → `error`, `coherence`/`workflow` → `warning`, `best-practice` → `info`); an optional `severity` field overrides it - `$metadata.rules` supports `$ref` imports for reusable rule packs - `relationships` are collected from all files diff --git a/docs/api.md b/docs/api.md index ed2d152..fcc2297 100644 --- a/docs/api.md +++ b/docs/api.md @@ -16,6 +16,8 @@ see [architecture.md](architecture.md#information-flow) for that flow. | `validateSpace(context, options?)` | Run full validation (schema, references, rules, duplicates) over a space. | | `validateFile(filePath, config)` | Validate a single file within its space. | +`ValidationResult.ruleViolations` carries each violation's effective `severity` (`error`, `warning` or `info`). Only `error` severity violations should be treated as failures; `validateFile` reports `warning` and `info` rule violations under `warnings` rather than `errors`. + ## Usage ```ts diff --git a/docs/concepts.md b/docs/concepts.md index 9336237..721849b 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -141,6 +141,8 @@ Rules may be: Rules are distinct from schema validation: the schema checks structure; rules check meaning and quality. +Each executable rule has a **category** (`validation`, `coherence`, `workflow`, `best-practice`) that supplies its default **severity** (`error`, `warning`, `info`). A rule may override its category's severity, but categories are the preferred grouping. Only `error` severity violations fail validation. + See [docs/rules.md](rules.md) for the rules reference, including JSONata expression syntax and the full `$metadata` field reference. --- diff --git a/docs/rules.md b/docs/rules.md index a620fa7..4019e07 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -24,22 +24,56 @@ Rules are a flat array. |---|---|---| | `id` | yes | Unique rule identifier | | `category` | yes | `validation` \| `coherence` \| `workflow` \| `best-practice` | +| `severity` | no | `error` \| `warning` \| `info`; overrides the category default (see [Severity](#severity)) | | `description` | yes | Human-readable rule intent | | `check` | yes | JSONata expression; must evaluate to `true` | | `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 | -## Categories +## Categories and severity -Categories label violations for reporting. They do not change expression execution semantics. +Categories describe a rule's intent and supply its default severity. They do not change expression execution semantics. -| Category | Typical use | -|---|---| -| `validation` | Hard correctness constraints | -| `coherence` | Cross-node consistency checks | -| `workflow` | Process/operating-discipline checks | -| `best-practice` | Advisory quality checks | +| Category | Typical use | Default severity | +|---|---|---| +| `validation` | Hard correctness constraints | `error` | +| `coherence` | Cross-node consistency checks | `warning` | +| `workflow` | Process/operating-discipline checks | `warning` | +| `best-practice` | Advisory quality checks | `info` | + +### Severity + +Every rule violation is reported with a severity: + +| Severity | Meaning | Fails validation | +|---|---|---| +| `error` | Content is wrong | yes | +| `warning` | Content is likely inconsistent or incomplete | no | +| `info` | Content could be better | no | + +Only `error` violations fail validation: `sctx validate` and `sctx validate-file` exit non-zero, and JSON output reports `valid: false`. Warnings and info violations are reported but don't fail, so a work-in-progress space can still pass while advisory checks remain visible. + +Prefer choosing the right category and relying on its default. Set `severity` on an individual rule only when that rule genuinely differs from the rest of its category: + +```json5 +{ + "id": "goal-not-blocked", + "category": "workflow", + "severity": "error", + "description": "Goals must not be left blocked", + "type": "goal", + "check": "current.status != 'blocked'" +} +``` + +`sctx schemas show` lists each category with its default severity and marks rules that override it. + +### Output + +- **`sctx validate`** — the summary counts rule violations per severity, and details are grouped by severity with each line showing the rule's category and id. +- **`sctx validate --json`** — `errors` includes only `error` severity rule violations (keyed `rule:`, with a `severity` field). A `ruleViolations` array lists every violation with `file`, `ruleId`, `category`, `severity` and `description` (`file` is empty for global rules). +- **`sctx validate-file`** — `error` severity violations appear under `errors`; `warning` and `info` violations appear under `warnings`. Rule entries carry a `severity` field. ## Evaluation model diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 07dd0b0..475d121 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "structured-context", - "version": "0.11.0", + "version": "0.11.1", "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 8216d7f..22ef32d 100644 --- a/plugin/skills/structured-context/references/commands.md +++ b/plugin/skills/structured-context/references/commands.md @@ -19,10 +19,10 @@ 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`) +- Runs executable rules (JSONata expressions in `$metadata.rules`), reporting each violation with a severity (`error`, `warning`, `info`) - Checks hierarchy ordering -Exit codes: `0` = clean, `1` = validation issues found. +Exit codes: `0` = clean (warning and info rule violations don't fail), `1` = validation errors found. **Scenarios:** diff --git a/plugin/skills/structured-context/references/schema-authoring.md b/plugin/skills/structured-context/references/schema-authoring.md index e0714cf..9e9498a 100644 --- a/plugin/skills/structured-context/references/schema-authoring.md +++ b/plugin/skills/structured-context/references/schema-authoring.md @@ -64,7 +64,7 @@ Relationships define how sub-entities (nodes inside other files) are parsed and **`fieldOn: "parent"` pattern** — use when the content model lists children on the parent (e.g. `activity.tasks: ["[[Task A]]"]`). Embedded parsing appends child wikilinks to the parent's `field` array rather than setting a `parent` field on each child. Validation checks each array entry resolves to a node of `type`. -Rules are a flat array. Categories are labels only (`validation`, `coherence`, `workflow`, `best-practice`). +Rules are a flat array. Each rule's `category` (`validation`, `coherence`, `workflow`, `best-practice`) supplies its default severity: `validation` → `error`, `coherence` and `workflow` → `warning`, `best-practice` → `info`. Only `error` violations fail validation; warnings and info are reported only. An optional per-rule `severity` (`error` | `warning` | `info`) overrides the category default — prefer picking the right category over overriding. ## Metadata composition semantics diff --git a/plugin/skills/structured-context/references/schema-design.md b/plugin/skills/structured-context/references/schema-design.md index fda8403..cc5544a 100644 --- a/plugin/skills/structured-context/references/schema-design.md +++ b/plugin/skills/structured-context/references/schema-design.md @@ -125,7 +125,7 @@ Write an initial schema, run validation, and treat the output as a specification - **All files as "Non-space (no type field)"** → `fieldMap` not configured, or wrong field name - **0 rule violations on suspicious content** → rules may not be evaluating (check `type` filter matches `resolvedType`; use `dump` to inspect) -- **Rule violations on every node of a type** → rule may be too strict; recategorise or remove +- **Rule violations on every node of a type** → rule may be too strict; recategorise (which changes its default severity) or remove - **Rule violations on a handful of nodes** → likely genuine content gaps worth flagging Expected iteration: 2–4 rounds of validation before all genuine issues are resolved. diff --git a/schemas/generated/_structured_context_schema_meta.json b/schemas/generated/_structured_context_schema_meta.json index e4c9d27..cdd0ddb 100644 --- a/schemas/generated/_structured_context_schema_meta.json +++ b/schemas/generated/_structured_context_schema_meta.json @@ -148,6 +148,9 @@ "category": { "enum": ["validation", "coherence", "workflow", "best-practice"] }, + "severity": { + "enum": ["error", "warning", "info"] + }, "description": { "type": "string", "minLength": 1 diff --git a/src/api.ts b/src/api.ts index 89d80ec..b532e8b 100644 --- a/src/api.ts +++ b/src/api.ts @@ -44,12 +44,16 @@ export type { ContentLink, EdgeDefinition, FileNotInSpaceResult, + FileValidationIssue, FileValidationResult, HierarchyLevel, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, + RuleCategory, + RuleSeverity, + RuleViolation, SchemaMetadata, SchemaWithMetadata, SpaceContext, diff --git a/src/commands/schemas.ts b/src/commands/schemas.ts index b678a6b..8d0ef24 100644 --- a/src/commands/schemas.ts +++ b/src/commands/schemas.ts @@ -4,7 +4,8 @@ import type { AnySchemaObject } from 'ajv'; import { loadConfig, resolveSchema } from '../config'; import { bundledSchemasDir, type EntityInfo, extractEntityInfo, loadSchema, readRawSchema } from '../schema/schema'; import { mergeVariantProperties, resolveRef } from '../schema/schema-refs'; -import type { SchemaMetadata, SchemaWithMetadata } from '../types'; +import { DEFAULT_SEVERITY_BY_CATEGORY } from '../schema/validate-rules'; +import type { Rule, RuleCategory, SchemaMetadata, SchemaWithMetadata } from '../types'; function isBundledPath(schemaPath: string): boolean { return dirname(schemaPath) === bundledSchemasDir; @@ -103,19 +104,20 @@ function showMetadata(metadata: SchemaMetadata): void { } if (metadata.rules) { - const groups = new Map>(); + const groups = new Map(); for (const rule of metadata.rules) { const rules = groups.get(rule.category) ?? []; - rules.push({ id: rule.id, description: rule.description }); + rules.push(rule); groups.set(rule.category, rules); } if (groups.size > 0) { console.log('\nRules:'); - for (const [group, items] of groups) { - console.log(` ${group}:`); - for (const item of items) { - console.log(` ${item.id}: ${item.description}`); + for (const [category, rules] of groups) { + console.log(` ${category} (default severity: ${DEFAULT_SEVERITY_BY_CATEGORY[category]}):`); + for (const rule of rules) { + const override = rule.severity ? ` [severity: ${rule.severity}]` : ''; + console.log(` ${rule.id}: ${rule.description}${override}`); } } } diff --git a/src/commands/validate-file.ts b/src/commands/validate-file.ts index c207430..2aa62c8 100644 --- a/src/commands/validate-file.ts +++ b/src/commands/validate-file.ts @@ -1,5 +1,5 @@ import { loadConfig } from '../config'; -import type { FileValidationResult } from '../types'; +import type { FileValidationIssue, FileValidationResult } from '../types'; import { validateFile } from '../validate'; export { validateFile } from '../validate'; @@ -42,8 +42,8 @@ function printHumanReadable(result: FileValidationResult): void { if (result.errorCount > 0) { console.log(`\n${red}✗${reset} ${result.label} (space: ${result.space}) — ${result.errorCount} error(s)\n`); - for (const { kind, message } of Object.values(result.errors)) { - console.log(` [${kind}] ${message}`); + for (const issue of Object.values(result.errors)) { + console.log(` [${issueLabel(issue)}] ${issue.message}`); } } else { console.log(`\n${green}✓${reset} ${result.label} (space: ${result.space})`); @@ -51,10 +51,14 @@ function printHumanReadable(result: FileValidationResult): void { if (result.warningCount > 0) { console.log(`\n ${yellow}${result.warningCount} warning(s):${reset}`); - for (const { kind, message } of Object.values(result.warnings)) { - console.log(` ${yellow}[${kind}]${reset} ${message}`); + for (const issue of Object.values(result.warnings)) { + console.log(` ${yellow}[${issueLabel(issue)}]${reset} ${issue.message}`); } } console.log(''); } + +function issueLabel({ kind, severity }: FileValidationIssue): string { + return severity ? `${kind}:${severity}` : kind; +} diff --git a/src/commands/validate.ts b/src/commands/validate.ts index cf0543d..b4b9344 100644 --- a/src/commands/validate.ts +++ b/src/commands/validate.ts @@ -2,20 +2,22 @@ import { dirname } from 'node:path'; import chokidar from 'chokidar'; import { getConfigSourceFiles } from '../config'; import { bundledSchemasDir } from '../schema/schema'; -import type { SpaceContext } from '../types'; +import type { FileValidationIssue, RuleSeverity, SpaceContext } from '../types'; import { formatErrors, validateSpace } from '../validate'; export async function validate(context: SpaceContext, options: { json?: boolean } = {}): Promise { const { schema, schemaRefRegistry } = context; const result = await validateSpace(context); + const ruleCounts: Record = { error: 0, warning: 0, info: 0 }; + for (const v of result.ruleViolations) ruleCounts[v.severity]++; // JSON output mode if (options.json) { - const errorsByFile: Record> = {}; + const errorsByFile: Record> = {}; - const addError = (file: string, key: string, kind: string, message: string) => { + const addError = (file: string, key: string, kind: string, message: string, severity?: RuleSeverity) => { if (!errorsByFile[file]) errorsByFile[file] = {}; - errorsByFile[file]![key] = { kind, message }; + errorsByFile[file]![key] = severity ? { kind, message, severity } : { kind, message }; }; for (const { file, errors: ajvErrors, nodeData } of result.nodeErrors) { @@ -39,17 +41,20 @@ export async function validate(context: SpaceContext, options: { json?: boolean } } for (const v of result.ruleViolations) { - if (v.file) { - addError(v.file, `rule:${v.ruleId}`, 'rule', `[${v.ruleId}] ${v.description}`); + if (v.file && v.severity === 'error') { + addError(v.file, `rule:${v.ruleId}`, 'rule', `[${v.ruleId}] ${v.description}`, v.severity); } } + const globalRuleErrorCount = result.ruleViolations.filter((v) => !v.file && v.severity === 'error').length; for (const v of result.hierarchyViolations) { addError(v.file, `hierarchy:${v.description}`, 'hierarchy', v.description); } const parseErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length; const errorCount = - Object.values(errorsByFile).reduce((sum, errs) => sum + Object.keys(errs).length, 0) + parseErrorCount; + Object.values(errorsByFile).reduce((sum, errs) => sum + Object.keys(errs).length, 0) + + parseErrorCount + + globalRuleErrorCount; console.log( JSON.stringify( { @@ -58,6 +63,7 @@ export async function validate(context: SpaceContext, options: { json?: boolean validCount: result.validCount, errorCount, errors: errorsByFile, + ruleViolations: result.ruleViolations, orphanCount: result.orphans.length, parseIssues: result.parseIssues, unresolvedContentLinks: result.unresolvedContentLinks, @@ -98,7 +104,9 @@ export async function validate(context: SpaceContext, options: { json?: boolean console.log(fmt(' Schema validation errors', result.nodeErrorCount, true)); console.log(fmt(' Broken links', result.refErrors.length, true)); console.log(fmt(' Duplicate keys', result.duplicateErrors.length, true)); - console.log(fmt(' Rule violations', result.ruleViolations.length, true)); + console.log(fmt(' Rule violations (error)', ruleCounts.error, true)); + console.log(fmt(' Rule violations (warning)', ruleCounts.warning, true, true)); + console.log(fmt(' Rule violations (info)', ruleCounts.info, true, true)); console.log(fmt(' Hierarchy violations', result.hierarchyViolations.length, true)); console.log(fmt(' Orphans (hierarchy nodes - no parent)', result.orphans.length, true, true)); console.log(fmt(' Unresolved content links', result.unresolvedContentLinks.length, true, true)); @@ -162,16 +170,13 @@ export async function validate(context: SpaceContext, options: { json?: boolean if (result.ruleViolations.length > 0) { console.log(`\nRule violations:`); - const byCategory = new Map(); - for (const v of result.ruleViolations) { - if (!byCategory.has(v.category)) byCategory.set(v.category, []); - byCategory.get(v.category)!.push(v); - } - - for (const [category, violations] of byCategory) { - console.log(` ${category.toUpperCase()} (${violations.length}):`); + const severityColor: Record = { error: red, warning: yellow, info: reset }; + for (const severity of ['error', 'warning', 'info'] as const) { + const violations = result.ruleViolations.filter((v) => v.severity === severity); + if (violations.length === 0) continue; + console.log(` ${severityColor[severity]}${severity.toUpperCase()}${reset} (${violations.length}):`); for (const v of violations) { - console.log(` ${v.file ? `${v.file}: ` : ''}${v.description}`); + console.log(` ${v.file ? `${v.file}: ` : ''}${v.description} [${v.category}: ${v.ruleId}]`); } } } @@ -189,7 +194,7 @@ export async function validate(context: SpaceContext, options: { json?: boolean result.nodeErrorCount > 0 || result.refErrors.length > 0 || result.duplicateErrors.length > 0 || - result.ruleViolations.length > 0 || + ruleCounts.error > 0 || result.hierarchyViolations.length > 0 || parseIssueErrorCount > 0 ) { diff --git a/src/schema/metadata-contract.ts b/src/schema/metadata-contract.ts index 67f06f9..9a97101 100644 --- a/src/schema/metadata-contract.ts +++ b/src/schema/metadata-contract.ts @@ -48,6 +48,7 @@ const RULE_SCHEMA = { properties: { id: { type: 'string', minLength: 1 }, category: { enum: ['validation', 'coherence', 'workflow', 'best-practice'] }, + severity: { enum: ['error', 'warning', 'info'] }, description: { type: 'string', minLength: 1 }, check: { type: 'string', minLength: 1 }, type: { type: 'string', minLength: 1 }, diff --git a/src/schema/schema.ts b/src/schema/schema.ts index e3adc06..46f62f5 100644 --- a/src/schema/schema.ts +++ b/src/schema/schema.ts @@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url'; import { isDeepStrictEqual } from 'node:util'; import Ajv, { type AnySchemaObject, type ValidateFunction } from 'ajv'; import JSON5 from 'json5'; -import type { HierarchyLevel, RuleCategory, SchemaMetadata, SchemaWithMetadata } from '../types'; +import type { HierarchyLevel, RuleCategory, RuleSeverity, SchemaMetadata, SchemaWithMetadata } from '../types'; import { DIALECT_META_SCHEMA, METADATA_SCHEMA, @@ -126,7 +126,8 @@ interface MetadataProvider { } const RULE_CATEGORIES = new Set(['validation', 'coherence', 'workflow', 'best-practice']); -const RULE_ALLOWED_KEYS = new Set(['id', 'category', 'description', 'check', 'type', 'scope', 'override']); +const RULE_SEVERITIES = new Set(['error', 'warning', 'info']); +const RULE_ALLOWED_KEYS = new Set(['id', 'category', 'severity', 'description', 'check', 'type', 'scope', 'override']); function readTopLevelMetadata(schema: AnySchemaObject): MetadataContract | undefined { const metadata = schema.$metadata; @@ -245,6 +246,7 @@ function isMetadataRule(value: unknown): value is Rule { if (typeof record.check !== 'string' || record.check.length === 0) return false; if ('type' in record && (typeof record.type !== 'string' || record.type.length === 0)) return false; + if ('severity' in record && !RULE_SEVERITIES.has(record.severity as RuleSeverity)) return false; if ('scope' in record && record.scope !== 'global') return false; if ('override' in record && typeof record.override !== 'boolean') return false; diff --git a/src/schema/validate-rules.ts b/src/schema/validate-rules.ts index a118c6c..25c0786 100644 --- a/src/schema/validate-rules.ts +++ b/src/schema/validate-rules.ts @@ -1,6 +1,19 @@ -import type { Rule, RuleViolation, SpaceNode } from '../types'; +import type { Rule, RuleCategory, RuleSeverity, RuleViolation, SpaceNode } from '../types'; import { buildEvalContext, evaluateExpression } from './evaluate-rule'; +/** Default severity for each rule category. A rule's own `severity` field overrides this. */ +export const DEFAULT_SEVERITY_BY_CATEGORY: Record = { + validation: 'error', + coherence: 'warning', + workflow: 'warning', + 'best-practice': 'info', +}; + +/** Effective severity of a rule: its explicit `severity`, else its category default. */ +export function ruleSeverity(rule: Rule): RuleSeverity { + return rule.severity ?? DEFAULT_SEVERITY_BY_CATEGORY[rule.category]; +} + /** * Validate nodes against rules metadata. * Returns a list of rule violations found. @@ -23,6 +36,7 @@ export async function validateRules(nodes: SpaceNode[], rules: Rule[]): Promise< // Evaluate each rule against applicable nodes for (const rule of rules) { + const severity = ruleSeverity(rule); if (rule.scope === 'global') { // Global rules are evaluated once against the full node set. // A sentinel node provides the evaluation context (nodes array is what matters). @@ -31,7 +45,13 @@ export async function validateRules(nodes: SpaceNode[], rules: Rule[]): Promise< 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, description: rule.description }); + violations.push({ + file: '', + ruleId: rule.id, + category: rule.category, + severity, + description: rule.description, + }); } } } else { @@ -44,6 +64,7 @@ export async function validateRules(nodes: SpaceNode[], rules: Rule[]): Promise< file: node.label, ruleId: rule.id, category: rule.category, + severity, description: rule.description, }); } diff --git a/src/types.ts b/src/types.ts index 3ab45b1..25eecd1 100644 --- a/src/types.ts +++ b/src/types.ts @@ -164,12 +164,20 @@ export type ParseIssue = { /** Rule categories for organizing executable validation rules */ export type RuleCategory = 'validation' | 'coherence' | 'workflow' | 'best-practice'; +/** + * Rule violation severity. Only `error` fails validation; `warning` and `info` are reported only. + * A rule's severity defaults from its category and may be overridden per rule. + */ +export type RuleSeverity = 'error' | 'warning' | 'info'; + export type { Rule } from './schema/metadata-contract'; export type RuleViolation = { + /** Node label, or empty string for global-scope rules. */ file: string; ruleId: string; category: RuleCategory; + severity: RuleSeverity; description: string; }; @@ -226,15 +234,25 @@ export type SpaceContext = { configDir: string; }; +export interface FileValidationIssue { + kind: string; + message: string; + /** Present for rule violations (`kind: 'rule'`). */ + severity?: RuleSeverity; +} + export interface FileValidationResult { file: string; label: string; space: string; /** Errors keyed by composite id (e.g. `schema:/status:enum:active`, `rule:my-rule-id`). */ - errors: Record; + errors: Record; errorCount: number; - /** Warnings keyed by composite id. Do not affect exit code or errorCount. */ - warnings: Record; + /** + * Warnings keyed by composite id, including `warning` and `info` severity rule violations. + * Do not affect exit code or errorCount. + */ + warnings: Record; warningCount: number; inSpace: true; } diff --git a/src/validate.ts b/src/validate.ts index af48bee..4f34657 100644 --- a/src/validate.ts +++ b/src/validate.ts @@ -9,6 +9,7 @@ import { createSpaceContext } from './space-context'; import { buildSpaceGraph } from './space-graph'; import type { FileNotInSpaceResult, + FileValidationIssue, FileValidationResult, GraphViolation, ParseIssue, @@ -31,6 +32,7 @@ export interface ValidationResult { nodeErrors: Array<{ file: string; errors: ErrorObject[]; nodeData: Record }>; refErrors: Array<{ file: string; parent: string; error: string }>; duplicateErrors: Array<{ title: string; files: string[] }>; + /** All rule violations with their effective severity. Only `error` severity fails validation. */ ruleViolations: RuleViolation[]; hierarchyViolations: GraphViolation[]; orphans: SpaceNode[]; @@ -307,7 +309,8 @@ export async function validateFile( // Pre-extract valid types for early type validation const validTypes = Array.isArray(schema.oneOf) ? extractEntityInfo(schema, schemaRefRegistry).map((e) => e.type) : []; - const errors: Record = {}; + const errors: Record = {}; + const warnings: Record = {}; // Schema validation errors for this node for (const node of nodes) { @@ -366,18 +369,18 @@ export async function validateFile( } } - // Rule violations for this node + // Rule violations for this node — only error severity counts as an error if (metadata.rules) { const ruleViolations = await validateRules(nodes, metadata.rules); for (const v of ruleViolations) { if (v.file === label) { - errors[`rule:${v.ruleId}`] = { kind: 'rule', message: `[${v.ruleId}] ${v.description}` }; + const target = v.severity === 'error' ? errors : warnings; + target[`rule:${v.ruleId}`] = { kind: 'rule', message: `[${v.ruleId}] ${v.description}`, severity: v.severity }; } } } // Unresolved content links for this node (warnings — do not affect errorCount) - const warnings: Record = {}; const targetNode = nodes.find((n) => n.label === label); if (targetNode) { const seen = new Set(); diff --git a/tests/fixtures/rule-severity/clean/Clean goal.md b/tests/fixtures/rule-severity/clean/Clean goal.md new file mode 100644 index 0000000..548e021 --- /dev/null +++ b/tests/fixtures/rule-severity/clean/Clean goal.md @@ -0,0 +1,4 @@ +--- +type: goal +status: active +--- diff --git a/tests/fixtures/rule-severity/failing/Blocked goal.md b/tests/fixtures/rule-severity/failing/Blocked goal.md new file mode 100644 index 0000000..89ad94c --- /dev/null +++ b/tests/fixtures/rule-severity/failing/Blocked goal.md @@ -0,0 +1,4 @@ +--- +type: goal +status: blocked +--- diff --git a/tests/fixtures/rule-severity/schema.json b/tests/fixtures/rule-severity/schema.json new file mode 100644 index 0000000..57bffee --- /dev/null +++ b/tests/fixtures/rule-severity/schema.json @@ -0,0 +1,41 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://rule-severity/schema", + "$metadata": { + "hierarchy": { + "levels": ["goal"] + }, + "rules": [ + { + "id": "always-info", + "category": "best-practice", + "description": "Best-practice rule that always fails (default severity: info)", + "type": "goal", + "check": "false" + }, + { + "id": "always-warning", + "category": "coherence", + "description": "Coherence rule that always fails (default severity: warning)", + "type": "goal", + "check": "false" + }, + { + "id": "not-blocked", + "category": "workflow", + "severity": "error", + "description": "Goals must not be blocked (workflow rule overridden to error)", + "type": "goal", + "check": "current.status != 'blocked'" + } + ] + }, + "type": "object", + "properties": { + "type": { "const": "goal" }, + "title": { "type": "string" }, + "status": { "type": "string" } + }, + "required": ["type"], + "additionalProperties": true +} diff --git a/tests/fixtures/schema-metadata/invalid-rule-severity.json b/tests/fixtures/schema-metadata/invalid-rule-severity.json new file mode 100644 index 0000000..1ecd44e --- /dev/null +++ b/tests/fixtures/schema-metadata/invalid-rule-severity.json @@ -0,0 +1,23 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json", + "$id": "sctx-test://schema-metadata/invalid-rule-severity", + "$metadata": { + "rules": [ + { + "id": "invalid-severity", + "category": "workflow", + "severity": "critical", + "description": "Invalid severity should fail schema validation", + "check": "true" + } + ] + }, + "type": "object", + "properties": { + "type": { + "const": "goal" + } + }, + "required": ["type"], + "additionalProperties": true +} diff --git a/tests/schema/schema-metadata.test.ts b/tests/schema/schema-metadata.test.ts index 14a4a65..1e56eb8 100644 --- a/tests/schema/schema-metadata.test.ts +++ b/tests/schema/schema-metadata.test.ts @@ -9,6 +9,7 @@ const GENERAL_SCHEMA_PATH = join(bundledSchemasDir, 'strategy_general.json'); const VALID_SCHEMA_PATH = join(FIXTURES_DIR, 'valid.json'); const ALIAS_ONLY_SCHEMA_PATH = join(FIXTURES_DIR, 'alias-only.json'); const INVALID_SCHEMA_PATH = join(FIXTURES_DIR, 'invalid-metadata.json'); +const INVALID_RULE_SEVERITY_SCHEMA_PATH = join(FIXTURES_DIR, 'invalid-rule-severity.json'); const INVALID_TYPE_REF_SCHEMA_PATH = join(FIXTURES_DIR, 'invalid-type-reference.json'); const PARTIALLY_INVALID_RELATIONSHIPS_SCHEMA_PATH = join(FIXTURES_DIR, 'partially-invalid-relationships.json'); const ON_A_PAGE_FIXTURE_PATH = join(import.meta.dir, '..', 'fixtures/general/on-a-page-valid.md'); @@ -49,6 +50,10 @@ describe('schema metadata', () => { expect(() => createValidator(INVALID_SCHEMA_PATH)).toThrow(); }); + it('rejects a rule with an unknown severity', () => { + expect(() => createValidator(INVALID_RULE_SEVERITY_SCHEMA_PATH)).toThrow(); + }); + it('rejects metadata that references types not in oneOf', () => { expect(() => loadMetadata(INVALID_TYPE_REF_SCHEMA_PATH)).toThrow('Schema metadata validation failed'); }); diff --git a/tests/schema/validate-rules.test.ts b/tests/schema/validate-rules.test.ts index dd00b53..9c60aba 100644 --- a/tests/schema/validate-rules.test.ts +++ b/tests/schema/validate-rules.test.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from 'bun:test'; -import { validateRules } from '../../src/schema/validate-rules'; +import { DEFAULT_SEVERITY_BY_CATEGORY, ruleSeverity, validateRules } from '../../src/schema/validate-rules'; import type { Rule, SpaceNode } from '../../src/types'; import { makeParentRef } from '../test-helpers'; @@ -454,5 +454,46 @@ describe('validate-rules', () => { expect(workflowViolations.length).toBeGreaterThan(0); }); }); + + describe('severity', () => { + const failingRule = (overrides: Partial): Rule => ({ + id: 'always-fails', + category: 'workflow', + description: 'Always fails', + check: 'false', + ...overrides, + }); + + it('defaults severity from category', () => { + expect(DEFAULT_SEVERITY_BY_CATEGORY).toEqual({ + validation: 'error', + coherence: 'warning', + workflow: 'warning', + 'best-practice': 'info', + }); + expect(ruleSeverity(failingRule({ category: 'validation' }))).toBe('error'); + expect(ruleSeverity(failingRule({ category: 'best-practice' }))).toBe('info'); + }); + + it('uses an explicit rule severity over the category default', () => { + expect(ruleSeverity(failingRule({ category: 'validation', severity: 'info' }))).toBe('info'); + expect(ruleSeverity(failingRule({ category: 'best-practice', severity: 'error' }))).toBe('error'); + }); + + it('attaches effective severity to node and global violations', async () => { + const node = mockNodes[0]!; + const violations = await validateRules( + [node], + [ + failingRule({ id: 'node-default', category: 'coherence' }), + failingRule({ id: 'global-override', scope: 'global', severity: 'error' }), + ], + ); + expect(violations.map((v) => [v.ruleId, v.severity])).toEqual([ + ['node-default', 'warning'], + ['global-override', 'error'], + ]); + }); + }); }); }); diff --git a/tests/validate/rule-severity.test.ts b/tests/validate/rule-severity.test.ts new file mode 100644 index 0000000..b8c9cf6 --- /dev/null +++ b/tests/validate/rule-severity.test.ts @@ -0,0 +1,99 @@ +import { describe, expect, it, spyOn } from 'bun:test'; +import { join } from 'node:path'; +import { validate } from '../../src/commands/validate'; +import type { Config } from '../../src/config'; +import { validateFile, validateSpace } from '../../src/validate'; +import { makeSpaceContext } from '../helpers/context'; + +const FIXTURES_DIR = join(import.meta.dir, '..', 'fixtures/rule-severity'); +const SCHEMA_PATH = join(FIXTURES_DIR, 'schema.json'); +const CLEAN_DIR = join(FIXTURES_DIR, 'clean'); +const FAILING_DIR = join(FIXTURES_DIR, 'failing'); + +/** Run the validate command with console output captured. */ +async function runValidate(dir: string, json: boolean): Promise<{ exitCode: number; output: string }> { + const logSpy = spyOn(console, 'log').mockImplementation(() => {}); + try { + const exitCode = await validate(makeSpaceContext(dir, SCHEMA_PATH), { json }); + const output = logSpy.mock.calls.map((args) => args.join(' ')).join('\n'); + return { exitCode, output }; + } finally { + logSpy.mockRestore(); + } +} + +describe('rule severity', () => { + describe('validateSpace', () => { + it('reports the effective severity of each violation', async () => { + const result = await validateSpace(makeSpaceContext(FAILING_DIR, SCHEMA_PATH)); + const severities = Object.fromEntries(result.ruleViolations.map((v) => [v.ruleId, v.severity])); + expect(severities).toEqual({ 'always-info': 'info', 'always-warning': 'warning', 'not-blocked': 'error' }); + }); + }); + + describe('validate command', () => { + it('exits 0 when only warning and info rule violations are present', async () => { + const { exitCode, output } = await runValidate(CLEAN_DIR, false); + expect(exitCode).toBe(0); + expect(output).toContain('WARNING'); + expect(output).toContain('INFO'); + expect(output).not.toContain('ERROR'); + }); + + it('exits 1 when an error severity rule violation is present', async () => { + const { exitCode, output } = await runValidate(FAILING_DIR, false); + expect(exitCode).toBe(1); + expect(output).toContain('ERROR'); + }); + + it('JSON output counts only error severity rules as errors and includes severity', async () => { + const clean = JSON.parse((await runValidate(CLEAN_DIR, true)).output); + expect(clean.valid).toBe(true); + expect(clean.errorCount).toBe(0); + expect(clean.ruleViolations).toHaveLength(2); + + const { exitCode, output } = await runValidate(FAILING_DIR, true); + const failing = JSON.parse(output); + expect(exitCode).toBe(1); + expect(failing.valid).toBe(false); + expect(failing.errorCount).toBe(1); + expect(failing.errors['Blocked goal.md']['rule:not-blocked'].severity).toBe('error'); + expect(failing.errors['Blocked goal.md']['rule:always-warning']).toBeUndefined(); + expect(failing.ruleViolations).toContainEqual({ + file: 'Blocked goal.md', + ruleId: 'not-blocked', + category: 'workflow', + severity: 'error', + description: 'Goals must not be blocked (workflow rule overridden to error)', + }); + }); + }); + + describe('validateFile', () => { + const config: Config = { + spaces: [ + { name: 'clean', path: CLEAN_DIR, schema: SCHEMA_PATH }, + { name: 'failing', path: FAILING_DIR, schema: SCHEMA_PATH }, + ], + }; + + it('reports warning and info rule violations as warnings, not errors', async () => { + const result = await validateFile(join(CLEAN_DIR, 'Clean goal.md'), config, { configDir: FIXTURES_DIR }); + if (!result.inSpace) throw new Error('expected file to be in space'); + expect(result.errorCount).toBe(0); + expect(result.warnings['rule:always-info']?.severity).toBe('info'); + expect(result.warnings['rule:always-warning']?.severity).toBe('warning'); + }); + + it('reports error severity rule violations as errors', async () => { + const result = await validateFile(join(FAILING_DIR, 'Blocked goal.md'), config, { configDir: FIXTURES_DIR }); + if (!result.inSpace) throw new Error('expected file to be in space'); + expect(result.errorCount).toBe(1); + expect(result.errors['rule:not-blocked']).toEqual({ + kind: 'rule', + message: '[not-blocked] Goals must not be blocked (workflow rule overridden to error)', + severity: 'error', + }); + }); + }); +}); From f0c30734663f72df67a648a15aa5a7f95c6e0fbd Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Sun, 27 Sep 2026 12:15:56 +1000 Subject: [PATCH 2/3] Report new warnings from the Stop hook without blocking With rule severity levels, rule violations below 'error' go to `warnings`, which the hooks ignored. The pre-edit hook now also records a warnings baseline. The Stop hook still blocks with exit 2 for new errors. For new warnings (except info-level), it returns them as hookSpecificOutput.additionalContext, so Claude sees them without a hook error. Also set a schema in the hook-test fixture config: the hook tests failed after the default schema fallback was removed. Claude-Session: https://claude.ai/code/session_01EJgagmpxDYVYr7fp9C6cZi --- hook-test/unit/on-stop.test.ts | 41 ++++++++++++++ hook-test/unit/pre-edit.test.ts | 19 ++++++- plugin/.claude-plugin/plugin.json | 9 +++- plugin/scripts/on-stop.ts | 90 +++++++++++++++++++------------ plugin/scripts/pre-edit.ts | 9 ++-- 5 files changed, 127 insertions(+), 41 deletions(-) diff --git a/hook-test/unit/on-stop.test.ts b/hook-test/unit/on-stop.test.ts index 352b369..a1e7f1f 100644 --- a/hook-test/unit/on-stop.test.ts +++ b/hook-test/unit/on-stop.test.ts @@ -177,3 +177,44 @@ describe('State file lifecycle', () => { expect(result.hasNewErrors).toBe(false); }); }); + +describe('Warnings', () => { + const validWithContentLink = + '---\ntype: mission\nparent: "[[Root]]"\nstatus: identified\n---\n\n# Test Title\n\nSee [[Missing Note]].\n'; + const contentLinkWarning = { 'content-link:Missing Note': { kind: 'content-link', message: 'test' } }; + + it('reports a new warning without blocking', async () => { + const sessionId = crypto.randomUUID(); + const validPath = join(fixtures.vaultDir, 'valid.md'); + writeStateFile(sessionId, [{ ...stateEntry(validPath, 'Edit', {}), warnings: {} }]); + writeFileSync(validPath, validWithContentLink); + + const result = await runOnStop({ session_id: sessionId }, opts()); + expect(result.hasNewErrors).toBe(false); + expect(result.errorMessage).toBeUndefined(); + expect(result.warningMessage).toContain('structured-context: new validation warnings'); + expect(result.warningMessage).toContain('Missing Note'); + }); + + it('does not report warnings already present in the baseline', async () => { + const sessionId = crypto.randomUUID(); + const validPath = join(fixtures.vaultDir, 'valid.md'); + writeFileSync(validPath, validWithContentLink); + writeStateFile(sessionId, [{ ...stateEntry(validPath, 'Edit', {}), warnings: contentLinkWarning }]); + + const result = await runOnStop({ session_id: sessionId }, opts()); + expect(result).toEqual({ hasNewErrors: false }); + }); + + it('reports both errors and warnings when both are new', async () => { + const sessionId = crypto.randomUUID(); + const validPath = join(fixtures.vaultDir, 'valid.md'); + writeStateFile(sessionId, [stateEntry(validPath, 'Write', null)]); + writeFileSync(validPath, validWithContentLink.replace('[[Root]]', '[[Ghost Node]]')); + + const result = await runOnStop({ session_id: sessionId }, opts()); + expect(result.hasNewErrors).toBe(true); + expect(result.errorMessage).toContain('Ghost Node'); + expect(result.warningMessage).toContain('Missing Note'); + }); +}); diff --git a/hook-test/unit/pre-edit.test.ts b/hook-test/unit/pre-edit.test.ts index b469d58..7c26155 100644 --- a/hook-test/unit/pre-edit.test.ts +++ b/hook-test/unit/pre-edit.test.ts @@ -5,7 +5,7 @@ */ import { afterEach, beforeEach, describe, expect, it } from 'bun:test'; -import { existsSync, readFileSync, rmSync } from 'node:fs'; +import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { runPreEdit } from '../../plugin/scripts/pre-edit'; @@ -92,6 +92,23 @@ describe('Edit operations', () => { expect(Object.keys(errors)).toContain('broken-link:[[Nonexistent Node]]'); }); + it('records pre-existing warnings as a separate baseline', async () => { + const sessionId = crypto.randomUUID(); + const filePath = join(fixtures.vaultDir, 'valid.md'); + writeFileSync( + filePath, + '---\ntype: mission\nparent: "[[Root]]"\nstatus: identified\n---\n\n# Test Title\n\nSee [[Missing Note]].\n', + ); + + await runPreEdit({ tool_name: 'Edit', tool_input: { file_path: filePath }, session_id: sessionId }, opts()); + + const entries = readState(sessionId); + expect(entries).toHaveLength(1); + expect((entries[0] as { errors: object }).errors).toEqual({}); + const warnings = (entries[0] as { warnings: Record }).warnings; + expect(Object.keys(warnings)).toContain('content-link:Missing Note'); + }); + it('does not write a state entry for a .md file not in any space', async () => { const sessionId = crypto.randomUUID(); // File outside the fixture vault — not registered in any space diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 475d121..4ff0a77 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,9 +1,14 @@ { "name": "structured-context", - "version": "0.11.1", + "version": "0.11.2", "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", "license": "MIT", - "keywords": ["structured-context", "validation", "markdown", "schema"] + "keywords": [ + "structured-context", + "validation", + "markdown", + "schema" + ] } diff --git a/plugin/scripts/on-stop.ts b/plugin/scripts/on-stop.ts index a0f8df5..a5cad54 100755 --- a/plugin/scripts/on-stop.ts +++ b/plugin/scripts/on-stop.ts @@ -18,6 +18,8 @@ export interface OnStopResult { hasNewErrors: boolean; /** Present when hasNewErrors is true */ errorMessage?: string; + /** Present when new warnings were introduced. Reported to Claude without blocking as an error. */ + warningMessage?: string; } interface HookState { @@ -26,18 +28,39 @@ interface HookState { tool: 'Write' | 'Edit'; file: string; errors: object | null; + /** Absent in state written by older versions of the pre-edit hook */ + warnings?: object | null; } -interface ValidationError { +interface ValidationIssue { kind: string; message: string; + severity?: 'error' | 'warning' | 'info'; } interface ValidationResult { inSpace?: boolean; label?: string; space?: string; - errors?: Record; + errors?: Record; + warnings?: Record; +} + +/** Issues in `fresh` that are not in the baseline. A Write has no baseline, so every issue is new. */ +function newIssues( + tool: HookState['tool'], + fresh: Record, + baseline: object | null | undefined, +): ValidationIssue[] { + const baselineKeys = tool === 'Write' ? new Set() : new Set(Object.keys(baseline ?? {})); + return Object.entries(fresh) + .filter(([key]) => !baselineKeys.has(key)) + .map(([, issue]) => issue); +} + +function formatIssues(header: string, issues: ValidationIssue[], noun: string): string { + const lines = issues.map((issue) => ` [${issue.kind}] ${issue.message}`).join('\n'); + return ` ${header} — ${issues.length} new ${noun}(s):\n${lines}`; } export async function runOnStop(input: OnStopInput, options?: OnStopOptions): Promise { @@ -59,7 +82,7 @@ export async function runOnStop(input: OnStopInput, options?: OnStopOptions): Pr } const newErrors: string[] = []; - let hasNewErrors = false; + const newWarnings: string[] = []; // Read all entries and keep only the latest per file (by timestamp) const lines = (await stateFile.text()) @@ -84,7 +107,7 @@ export async function runOnStop(input: OnStopInput, options?: OnStopOptions): Pr } for (const [FILE, entry] of latestByFile) { - const { tool, errors: BASELINE } = entry; + const { tool } = entry; const fileExists = await Bun.file(FILE).exists(); if (!fileExists) { @@ -102,47 +125,36 @@ export async function runOnStop(input: OnStopInput, options?: OnStopOptions): Pr continue; } - const FRESH_ERRORS = result.errors ?? {}; - - let newErrorsForFile: Record; - - if (tool === 'Write') { - // New file — all errors are new - newErrorsForFile = FRESH_ERRORS; - } else { - // Edit — only errors absent from the baseline are new - const baselineKeys = new Set(Object.keys(BASELINE ?? {})); - const freshEntries = Object.entries(FRESH_ERRORS); - newErrorsForFile = Object.fromEntries(freshEntries.filter(([key]) => !baselineKeys.has(key))) as Record< - string, - ValidationError - >; - } - - const newCount = Object.keys(newErrorsForFile).length; + const HEADER = `${result.label ?? FILE} (space: ${result.space ?? 'unknown'})`; - if (newCount > 0) { - const LABEL = result.label ?? FILE; - const SPACE = result.space ?? 'unknown'; - - const errorLines = Object.values(newErrorsForFile) - .map((val) => ` [${val.kind}] ${val.message}`) - .join('\n'); + const fileErrors = newIssues(tool, result.errors ?? {}, entry.errors); + if (fileErrors.length > 0) { + newErrors.push(formatIssues(HEADER, fileErrors, 'error')); + } - newErrors.push(` ${LABEL} (space: ${SPACE}) — ${newCount} new error(s):\n${errorLines}`); - hasNewErrors = true; + // Info-level rule violations are not worth another turn from Claude + const fileWarnings = newIssues(tool, result.warnings ?? {}, entry.warnings).filter( + (issue) => issue.severity !== 'info', + ); + if (fileWarnings.length > 0) { + newWarnings.push(formatIssues(HEADER, fileWarnings, 'warning')); } } // Clean up state file await Bun.$`rm -f ${STATE_FILE}`; - if (hasNewErrors) { + const warningMessage = + newWarnings.length > 0 + ? `structured-context: new validation warnings introduced this session - fix them with the structured-context skill if appropriate, otherwise mention them to the user:\n${newWarnings.join('\n')}` + : undefined; + + if (newErrors.length > 0) { const errorMessage = `structured-context: new validation errors introduced this session - use structured-context skill to resolve:\n${newErrors.join('\n')}`; - return { hasNewErrors: true, errorMessage }; + return { hasNewErrors: true, errorMessage, ...(warningMessage && { warningMessage }) }; } - return { hasNewErrors: false }; + return { hasNewErrors: false, ...(warningMessage && { warningMessage }) }; } async function main() { @@ -151,9 +163,17 @@ async function main() { const result = await runOnStop(INPUT); if (result.hasNewErrors) { - console.error(result.errorMessage); + // Exit 2 blocks the stop; stderr is fed back to Claude as the reason + console.error([result.errorMessage, result.warningMessage].filter(Boolean).join('\n\n')); process.exit(2); } + + if (result.warningMessage) { + // Non-error feedback: Claude gets another turn, but it isn't flagged as a hook error + console.log( + JSON.stringify({ hookSpecificOutput: { hookEventName: 'Stop', additionalContext: result.warningMessage } }), + ); + } } if (import.meta.main) { diff --git a/plugin/scripts/pre-edit.ts b/plugin/scripts/pre-edit.ts index 326a68c..5eee7d1 100755 --- a/plugin/scripts/pre-edit.ts +++ b/plugin/scripts/pre-edit.ts @@ -2,7 +2,7 @@ /** * PreToolUse hook for Write and Edit on *.md files. * Write (new files): records the filename with no baseline errors. - * Edit (existing files): validates before the edit and records baseline errors. + * Edit (existing files): validates before the edit and records baseline errors and warnings. * Appends one JSONL line to a per-session state file for the Stop hook to analyse. */ @@ -31,11 +31,13 @@ interface HookState { tool: 'Write' | 'Edit'; file: string; errors: object | null; + warnings: object | null; } interface ValidationResult { inSpace?: boolean; errors?: object; + warnings?: object; } export async function runPreEdit(input: PreEditInput, options?: PreEditOptions): Promise { @@ -58,6 +60,7 @@ export async function runPreEdit(input: PreEditInput, options?: PreEditOptions): tool: 'Write', file: FILE_PATH, errors: null, + warnings: null, }; mkdirSync(STATE_DIR, { recursive: true }); appendFileSync(STATE_FILE, `${JSON.stringify(entry)}\n`); @@ -83,13 +86,13 @@ export async function runPreEdit(input: PreEditInput, options?: PreEditOptions): return; } - const ERRORS = result.errors ?? {}; const entry: HookState = { session_id: SESSION_ID, timestamp: TIMESTAMP, tool: 'Edit', file: FILE_PATH, - errors: ERRORS, + errors: result.errors ?? {}, + warnings: result.warnings ?? {}, }; mkdirSync(STATE_DIR, { recursive: true }); appendFileSync(STATE_FILE, `${JSON.stringify(entry)}\n`); From 14802df7de5a8675b0dacf52f2aae0be32dc1b5c Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Sun, 27 Sep 2026 12:16:10 +1000 Subject: [PATCH 3/3] Format plugin.json after version sync Claude-Session: https://claude.ai/code/session_01EJgagmpxDYVYr7fp9C6cZi --- plugin/.claude-plugin/plugin.json | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 4ff0a77..40e36b0 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -5,10 +5,5 @@ "homepage": "https://github.com/mindsocket/structured-context", "repository": "https://github.com/mindsocket/structured-context", "license": "MIT", - "keywords": [ - "structured-context", - "validation", - "markdown", - "schema" - ] + "keywords": ["structured-context", "validation", "markdown", "schema"] }