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
9 changes: 2 additions & 7 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,18 +22,13 @@ see [architecture.md](architecture.md#information-flow) for that flow.
| `spaceGraphFrom(data, options?)` | Build a `SpaceGraph` from that JSON. `options.hierarchy` names the hierarchy that structures it (default: the main hierarchy). |
| `validateSpace(context, options?)` | Run full validation (schema, references, rules, duplicates) over a space. Semantic rules run only when `semantic` is passed; it takes the same values as `sctx validate --semantic`, with the provider coming from config and the environment. |
| `validateFile(filePath, config)` | Validate a single file within its space. |
| `nodeIssues(result, options?)` | Each node's issues from a `ValidationResult`, by node id: the per-node view `validateFile` and `sctx validate --json` give. |
| `listSchemas(options?)` | List the schemas available to a config: bundled, plugin-contributed and configured. |
| `formatWikilink(target, alias?)` | Format a target into an Obsidian wikilink (`[[target]]` or `[[target|alias]]`). |
| `parseWikilink(link)` | Parse a wikilink or target string into `{ target, anchor?, displayText? }`. |
| `wikilinkToTarget(link)` | Extract the plain target lookup key from a wikilink string. |
| `buildTargetIndex(nodes)` | Build a fast lookup index mapping link target strings to nodes (marking ambiguous targets as `null`). |

`ValidationResult.ruleViolations` carries each violation's effective `severity` (`error`, `warning` or `info`). Only `error` severity violations should be treated as failures.

`nodeIssues(result)` gathers every result about a node into one map per node: schema, duplicate id, broken link, hierarchy, rule, gated and unresolved content link issues, each keyed by a composite id such as `rule:<id>` and carrying its `kind`, `message` and `severity`. `kind` is a `ValidationIssueKind`, and `VALIDATION_ISSUE_KINDS` lists every kind at runtime. Read `severity` rather than deriving it from `kind`. Pass `{ includeGated }` as validation ran, so a gated node's note says whether its rules were evaluated. Rule violations without a node and parse issues stay in their own parts of the result. `validateFile` returns one node's map as `issues`.

Each `ValidationResult` entry about a node carries its `nodeId`, and, where the entry is tied to a location, an optional `source` (`{ file, line?, column? }`). `duplicateErrors` lists a `sources` location for each node that shares the `id`. See [Validation results and nodes](concepts.md#validation-results-and-nodes).
`ValidationResult.issues` lists every [validation issue](concepts.md#validation-results-and-nodes) the run found, and `validateFile` returns one node's issues. Only `error` issues are failures. Read each issue's `severity` rather than deriving it from `kind`. `VALIDATION_ISSUE_KINDS` lists the kinds at runtime.

A `SpaceGraph` classifies nodes against one hierarchy, and indexes child nodes and typed edges in both
directions.
Expand Down Expand Up @@ -112,7 +107,7 @@ const validation = await validateSpace(context, { readResult });
`loadSpaceGraph` keeps every node whose type the schema defines, including nodes with field errors
such as an invalid enum value. Nodes of an unknown type are left out. The graph is *not* a validation
pass: use `validateSpace` (or `validateFile`) for field errors, broken references, rule violations and
duplicates. Each entry in its `nodeErrors` lists the node's `issues`, one formatted message per problem.
duplicates.

## Hand-assembled config

Expand Down
4 changes: 1 addition & 3 deletions docs/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,9 +119,7 @@ A wikilink is looked up in `linkTargets`, and the result is stored as the target

### Validation results and nodes

A validation result refers to a node by its `id`, in a `nodeId` field. Where the node is defined is a separate `source` (`file`, and `line` / `column` where available). A result may copy a node's identity and location, but not its content. A node can lack a `source` (for example when a plugin reads from a service rather than files), so treat `source` as optional.

Rule violations on a global rule have no `nodeId`.
A validation run reports a list of **validation issues**. Each has a **kind**, the check that found it, and a **severity**. An issue about a node refers to it by `nodeId`. A node can lack a `source`, for example when a plugin reads from a service rather than files.

### Folder index

Expand Down
4 changes: 2 additions & 2 deletions docs/rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -235,8 +235,8 @@ the next). Excluded nodes are reported under `skippedByDepth`, separate from gat
## 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`** — `issues` holds each node's issues of every severity, keyed by node id and then by a composite id such as `rule:<id>`. Each issue has a `kind`, `message` and `severity`. A `ruleViolations` array lists every violation with `file`, `ruleId`, `category`, `severity` and `description` (`file` is empty for global rules). A violation from a failed `expression` has the evidence `expression failed: <expression>` when the rule also has a `semantic` part, and no verdict.
- **`sctx validate-file --json`** — `issues` holds the file's issues of every severity, each with a `severity` field. `errorCount` counts the `error` ones.
- **`sctx validate --json`** — prints the run's [`ValidationResult`](api.md#main-building-blocks), with `space`, `valid` and `errorCount`. A violation from a failed `expression` has the evidence `expression failed: <expression>` when the rule also has a `semantic` part, and no verdict.
- **`sctx validate-file --json`** — prints the file's issues, with `errorCount`.

Gated files: see [Single-file validation](#single-file-validation).

17 changes: 10 additions & 7 deletions hook-test/unit/mod-bridge.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -88,28 +88,31 @@ describe('paneData', () => {
const dir = resultsDirPath(stateFilePath(sessionId, opts()));
const kept = loadResult(dir, 'test-space')!;
const marker = {
kind: 'rule',
key: 'rule:kept',
message: '[kept] from the kept result',
nodeId: 'valid.md',
ruleId: 'kept',
category: 'coherence',
severity: 'warning',
description: 'from the kept result',
} as PaneData['validation']['ruleViolations'][number];
saveResult({ dir, hash: kept.hash }, 'test-space', { ruleViolations: [marker] });
} as PaneData['validation']['issues'][number];
saveResult({ dir, hash: kept.hash }, 'test-space', { issues: [marker] });

const reused = await paneData(sessionId, 'test-space', { ...opts(), cwd: fixtures.fixtureDir });
expect(reused.validation).toEqual({ issues: {}, ruleViolations: [marker], parseIssues: [] });
expect(reused.validation).toEqual({ issues: [marker] });
expect(reused.graph.nodes.length).toBeGreaterThan(0);
expect(reused.graph.nodes.every((node) => !('content' in (node as object)))).toBe(true);

writeFileSync(join(fixtures.vaultDir, 'valid.md'), '---\ntype: mission\nstatus: identified\n---\n\n# Changed\n');
const fresh = await paneData(sessionId, 'test-space', { ...opts(), cwd: fixtures.fixtureDir });
expect(fresh.validation.ruleViolations).not.toContainEqual(marker);
expect(fresh.validation.issues).not.toContainEqual(marker);

writeFileSync(join(fixtures.vaultDir, 'valid.md'), '---\ntype: mission\n---\n\n# No status\n');
const failing = await paneData(sessionId, 'test-space', { ...opts(), cwd: fixtures.fixtureDir });
const kinds = Object.values(failing.validation.issues['valid.md'] ?? {}).map(
({ kind, severity }) => `${kind}:${severity}`,
);
const kinds = failing.validation.issues
.filter((issue) => issue.nodeId === 'valid.md')
.map(({ kind, severity }) => `${kind}:${severity}`);
expect(kinds).toContain('schema:error');
expect(loadResult(dir, 'test-space')!.hash).not.toBe(kept.hash);
});
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.22.5",
"version": "0.22.7",
"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
36 changes: 28 additions & 8 deletions plugin/hooks/map-pane.test.tsx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import type { On } from 'claude-code';
import { type Engine, expect, test } from 'claude-code/testing';

import type { CwdContext, ModStatus, PaneData } from '../types';
import type { CwdContext, ModStatus, NodeId, PaneData } from '../types';
import { fit } from './map-pane';

const level = (type: string) => ({ type, field: 'parent', fieldOn: 'child', multiple: false, selfRef: false });
Expand Down Expand Up @@ -36,13 +36,33 @@ const DATA: PaneData = {
],
},
validation: {
issues: {
'Broken.md': { 'schema:type': { kind: 'schema', message: 'type is not allowed', severity: 'error' } },
'Opp A.md': { 'rule:summary': { kind: 'rule', message: '[summary] missing summary', severity: 'warning' } },
},
// Rule results on a node are in `issues`; `ruleViolations` adds only those without one
ruleViolations: [],
parseIssues: [{ file: 'Bad.md', severity: 'error', type: 'yaml', message: 'bad frontmatter' }],
issues: [
{
kind: 'parse',
key: 'parse:yaml',
severity: 'error',
message: 'bad frontmatter',
source: { file: 'Bad.md' },
type: 'yaml',
},
{
kind: 'schema',
key: 'schema:type',
severity: 'error',
message: 'type is not allowed',
nodeId: 'Broken.md' as NodeId,
},
{
kind: 'rule',
key: 'rule:summary',
severity: 'warning',
message: '[summary] missing summary',
nodeId: 'Opp A.md' as NodeId,
ruleId: 'summary',
category: 'coherence',
description: 'missing summary',
},
],
},
};

Expand Down
30 changes: 26 additions & 4 deletions plugin/hooks/map-pane.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -126,11 +126,33 @@ function findOccurrence(occurrences: Occurrence[], key: string): Occurrence | un
return undefined;
}

type Issue = PaneData['validation']['issues'][number];

// PROTOTYPE: structured-context-map-views 0.5 takes issues by node plus the global rule violations.
// Drop this once a map-views release takes the issue list itself.
function byNode(list: Issue[]): Parameters<typeof annotationsFrom>[0] {
const issues: Record<
string,
Record<string, Pick<Issue, 'kind' | 'message' | 'severity'> & { line?: number; column?: number }>
> = {};
const ruleViolations: { ruleId: string; severity: Issue['severity']; description: string }[] = [];
for (const issue of list) {
if (issue.kind === 'parse') continue;
if (issue.nodeId === undefined) {
if (issue.kind === 'rule') ruleViolations.push(issue);
continue;
}
const { kind, message, severity, source } = issue;
issues[issue.nodeId] ??= {};
issues[issue.nodeId]![issue.key] = { kind, message, severity, line: source?.line, column: source?.column };
}
return { issues, ruleViolations } as Parameters<typeof annotationsFrom>[0];
}

function project(data: PaneData, hierarchy?: string): { graph: Graph; tree: Tree; annotations: Annotations } {
const graph = spaceGraphFrom(data.graph as Parameters<typeof spaceGraphFrom>[0], { hierarchy });
const tree = buildTree(graph, 'pane');
const { issues, ruleViolations } = data.validation;
const annotations = annotationsFrom({ issues, ruleViolations }, graph);
const annotations = annotationsFrom(byNode(data.validation.issues), graph);
return { graph, tree, annotations };
}

Expand Down Expand Up @@ -244,7 +266,7 @@ export function registerMapPane(on: On): void {
const counts = { error: 0, warning: 0, info: 0 };
for (const results of annotations.annotations.values()) for (const a of results) counts[a.severity]++;
for (const a of annotations.unattached) counts[a.severity]++;
const parseIssues = data.validation.parseIssues;
const parseIssues = data.validation.issues.filter((issue) => issue.kind === 'parse');
for (const issue of parseIssues) counts[issue.severity]++;

const toggle = (key: string) =>
Expand Down Expand Up @@ -355,7 +377,7 @@ export function registerMapPane(on: On): void {
{parseIssues.slice(0, UNATTACHED_LIMIT).map((issue) => (
<Text color={SEVERITY_COLOR[issue.severity]}>
{' '}
{issue.file}: {issue.severity}: {issue.message ?? issue.type}
{issue.source?.file}: {issue.severity}: {issue.message}
</Text>
))}
{parseIssues.length > UNATTACHED_LIMIT && (
Expand Down
6 changes: 1 addition & 5 deletions plugin/scripts/mod-bridge.ts
Original file line number Diff line number Diff line change
Expand Up @@ -107,11 +107,7 @@ export async function paneData(sessionId: string, space: string, options: HookOp
space,
path: info.path,
graph: { ...graph, nodes },
validation: {
issues: output.issues ?? {},
ruleViolations: output.ruleViolations ?? [],
parseIssues: output.parseIssues ?? [],
},
validation: { issues: output.issues ?? [] },
};
}

Expand Down
29 changes: 8 additions & 21 deletions plugin/scripts/state.ts
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ export interface SpacesOutput {
}

/** The parts of `validate --json` the hooks read */
type ValidateOutput = Partial<Pick<ValidateJsonOutput, 'issues' | 'ruleViolations' | 'parseIssues'>>;
type ValidateOutput = Partial<Pick<ValidateJsonOutput, 'issues'>>;

export function stateFilePath(sessionId: string | undefined, options?: HookOptions): string {
const dir = options?.stateDir ?? process.env.SCTX_STATE_DIR ?? '/tmp';
Expand Down Expand Up @@ -289,26 +289,13 @@ export async function validateSpace(
return byFile[label];
};

for (const [label, issues] of Object.entries(output.issues ?? {})) {
for (const [key, issue] of Object.entries(issues)) {
if (issue.severity === 'error') issuesFor(label).errors[key] = issue;
else if (issue.severity === 'warning') issuesFor(label).warnings[key] = issue;
}
}
for (const issue of output.parseIssues ?? []) {
if (issue.severity === 'error') {
issuesFor(issue.file).errors[`parse:${issue.type}`] = {
kind: 'parse',
message: issue.message ?? `Could not parse (${issue.type})`,
};
}
}
// Rule violations without a node aren't in `issues`
for (const v of output.ruleViolations ?? []) {
if (v.nodeId || v.severity === 'info') continue;
const issue = { kind: 'rule', message: `[${v.ruleId}] ${v.description}`, severity: v.severity };
const bucket = v.severity === 'error' ? issuesFor('').errors : issuesFor('').warnings;
bucket[`rule:${v.ruleId}`] = issue;
for (const issue of output.issues ?? []) {
// A file excluded from the space without a parse failure (such as a note with no type) is not worth a turn
if (issue.kind === 'parse' && issue.severity !== 'error') continue;
const label = issue.nodeId ?? (issue.kind === 'parse' ? issue.source.file : '');
const { kind, message, severity } = issue;
if (severity === 'error') issuesFor(label).errors[issue.key] = { kind, message, severity };
else if (severity === 'warning') issuesFor(label).warnings[issue.key] = { kind, message, severity };
}
return byFile;
}
Expand Down
4 changes: 2 additions & 2 deletions plugin/skills/structured-context/references/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ sctx dump <space> [--filter <view-or-expression>] [--hierarchy <name>] [--graph]
```

Outputs `{ nodes, source, diagnostics }` as strict JSON. Each node includes resolved fields:
- `id` — unique node key; for a page it is the path `validate --json` uses for its `issues` map
- `id` — unique node key (for a page, its path); `validate --json` issues name it as `nodeId`
- `title`, `resolvedType` — display title and type after alias resolution
- `resolvedParents` — parent refs after link resolution, with the edge field and kind

Expand All @@ -134,7 +134,7 @@ sctx dump <space> | jq '.nodes[] | select(.title == "My Node Title")'

# Join nodes with their validation errors
sctx validate <space> --json > v.json
sctx dump <space> | jq --slurpfile v v.json '.nodes[] | {id, resolvedType, issues: $v[0].issues[.id]}'
sctx dump <space> | jq --slurpfile v v.json '.nodes[] | .id as $id | {id, resolvedType, issues: [$v[0].issues[] | select(.nodeId == $id)]}'
```

## diagram
Expand Down
Loading
Loading