Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 12 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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

Expand Down
2 changes: 2 additions & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---
Expand Down
50 changes: 42 additions & 8 deletions docs/rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:<id>`, 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

Expand Down
41 changes: 41 additions & 0 deletions hook-test/unit/on-stop.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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');
});
});
19 changes: 18 additions & 1 deletion hook-test/unit/pre-edit.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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<string, unknown> }).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
Expand Down
2 changes: 1 addition & 1 deletion plugin/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "structured-context",
"version": "0.11.0",
"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",
Expand Down
90 changes: 55 additions & 35 deletions plugin/scripts/on-stop.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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<string, ValidationError>;
errors?: Record<string, ValidationIssue>;
warnings?: Record<string, ValidationIssue>;
}

/** 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<string, ValidationIssue>,
baseline: object | null | undefined,
): ValidationIssue[] {
const baselineKeys = tool === 'Write' ? new Set<string>() : 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<OnStopResult> {
Expand All @@ -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())
Expand All @@ -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) {
Expand All @@ -102,47 +125,36 @@ export async function runOnStop(input: OnStopInput, options?: OnStopOptions): Pr
continue;
}

const FRESH_ERRORS = result.errors ?? {};

let newErrorsForFile: Record<string, ValidationError>;

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() {
Expand All @@ -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) {
Expand Down
Loading
Loading