structured-context 0.21.0 → 0.22.1

package/README.md

@@ -45,7 +45,7 @@ Content and structure
   Rule violations (info)                   1
   Hierarchy violations                     0
   Orphans (hierarchy nodes - no parent)    1
-  Unresolved content links                 0
+  Unresolved content links (info)          0
   Excluded during parsing                  0
 ```
 
@@ -70,7 +70,7 @@ bunx structured-context --help
 
 ## Setup for AI Agents
 
-Claude Code plugin, providing validation hooks, slash commands, and agent skills. Install it with:
+Claude Code plugin, providing validation hooks, slash commands, and agent skills. In Claude Code versions with mods, it also shows each turn's new issues beside the chat, adds the session's schemas to the system prompt, and gives Claude sctx tools. Install it with:
 
 ```
 claude plugin marketplace add mindsocket/structured-context

package/dist/api.d.ts

@@ -35,6 +35,7 @@ export { bundledSchemasDir, loadSchema, type PluginSchemaSource, setBundledSchem
 export { createSpaceContext } from './space-context';
 export { buildSpaceGraph } from './space-graph';
 export { exportSpaceGraph } from './space-graph-data';
-export type { BaseNode, ContentLink, EdgeDefinition, FileNotInSpaceResult, FileValidationIssue, FileValidationResult, Hierarchy, HierarchyLevel, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, RuleCategory, RuleSeverity, RuleViolation, SchemaMetadata, SchemaWithMetadata, SourceLocation, SpaceContext, UnresolvedRef, ValidateFileOutput, } from './types';
+export type { BaseNode, ContentLink, EdgeDefinition, FileNotInSpaceResult, FileValidationIssue, FileValidationResult, Hierarchy, HierarchyLevel, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, RuleCategory, RuleSeverity, RuleViolation, SchemaMetadata, SchemaWithMetadata, SourceLocation, SpaceContext, UnresolvedRef, ValidateFileOutput, ValidationIssueKind, } from './types';
+export { VALIDATION_ISSUE_KINDS } from './types';
 export type { ValidationResult } from './validate';
-export { validateFile, validateSpace } from './validate';
+export { nodeIssues, validateFile, validateSpace } from './validate';

package/dist/api.js

@@ -32,4 +32,5 @@ export { bundledSchemasDir, loadSchema, setBundledSchemasDir } from './schema/sc
 export { createSpaceContext } from './space-context';
 export { buildSpaceGraph } from './space-graph';
 export { exportSpaceGraph } from './space-graph-data';
-export { validateFile, validateSpace } from './validate';
+export { VALIDATION_ISSUE_KINDS } from './types';
+export { nodeIssues, validateFile, validateSpace } from './validate';

package/dist/commands/validate-file.js

@@ -42,7 +42,7 @@ function printHumanReadable(result) {
     }
     if (result.errorCount > 0) {
         console.log(`\n${red}✗${reset} ${result.label} (space: ${result.space}) — ${result.errorCount} error(s)\n`);
-        for (const issue of Object.values(result.errors)) {
+        for (const issue of Object.values(result.issues).filter((i) => i.severity === 'error')) {
             console.log(`  [${issueLabel(issue)}] ${issue.message}`);
         }
     }
@@ -51,12 +51,13 @@ function printHumanReadable(result) {
     }
     if (result.warningCount > 0) {
         console.log(`\n  ${yellow}${result.warningCount} warning(s):${reset}`);
-        for (const issue of Object.values(result.warnings)) {
+        for (const issue of Object.values(result.issues).filter((i) => i.severity !== 'error')) {
             console.log(`  ${yellow}[${issueLabel(issue)}]${reset} ${issue.message}`);
         }
     }
     console.log('');
 }
+// A structural error (schema, hierarchy, broken link) is always an error, so its label leaves the severity out
 function issueLabel({ kind, severity }) {
-    return severity ? `${kind}:${severity}` : kind;
+    return severity === 'error' && kind !== 'rule' ? kind : `${kind}:${severity}`;
 }

package/dist/commands/validate.js

@@ -3,7 +3,7 @@ import chokidar from 'chokidar';
 import { getConfigSourceFiles } from '../config';
 import { resolveSpacePluginSchemas } from '../plugins/util';
 import { bundledSchemasDir } from '../schema/schema';
-import { formatSource, ruleViolationMessage, validateSpace } from '../validate';
+import { formatSource, nodeIssues, validateSpace } from '../validate';
 export async function validate(context, options = {}) {
     const result = await validateSpace(context, options);
     const ruleCounts = { error: 0, warning: 0, info: 0 };
@@ -11,43 +11,19 @@ export async function validate(context, options = {}) {
         ruleCounts[v.severity]++;
     // JSON output mode
     if (options.json) {
-        const errorsByFile = {};
-        const addError = (file, key, kind, message, severity) => {
-            if (!errorsByFile[file])
-                errorsByFile[file] = {};
-            errorsByFile[file][key] = severity ? { kind, message, severity } : { kind, message };
-        };
-        for (const { nodeId, issues } of result.nodeErrors) {
-            for (const { message, dedupeKey } of issues) {
-                addError(nodeId, `schema:${dedupeKey}`, 'schema', message);
-            }
-        }
-        for (const { nodeId, parent, error } of result.refErrors) {
-            addError(nodeId, `broken-link:${parent}`, 'broken-link', `${parent} → ${error}`);
-        }
-        for (const { id, sources } of result.duplicateErrors) {
-            const where = sources.length > 0 ? `: ${sources.map(formatSource).join(', ')}` : '';
-            addError(id, `duplicate:${id}`, 'duplicate', `Duplicate id "${id}" is used by ${sources.length} nodes${where}`);
-        }
-        for (const v of result.ruleViolations) {
-            if (v.nodeId && v.severity === 'error') {
-                addError(v.nodeId, `rule:${v.ruleId}`, 'rule', ruleViolationMessage(v), v.severity);
-            }
-        }
+        const issues = nodeIssues(result, options);
+        const nodeErrorCount = Object.values(issues)
+            .flatMap((byKey) => Object.values(byKey))
+            .filter((issue) => issue.severity === 'error').length;
         const globalRuleErrorCount = result.ruleViolations.filter((v) => !v.nodeId && v.severity === 'error').length;
-        for (const v of result.hierarchyViolations) {
-            addError(v.nodeId, `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 +
-            globalRuleErrorCount;
+        const errorCount = nodeErrorCount + parseErrorCount + globalRuleErrorCount;
         console.log(JSON.stringify({
             space: context.space.name,
             valid: errorCount === 0,
             validCount: result.validCount,
             errorCount,
-            errors: errorsByFile,
+            issues,
             ruleViolations: result.ruleViolations,
             orphanCount: result.orphans.length,
             parseIssues: result.parseIssues,
@@ -187,7 +163,7 @@ export async function validate(context, options = {}) {
     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));
+    console.log(fmt('  Unresolved content links (info)', result.unresolvedContentLinks.length, true, true));
     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));

package/dist/plugins/builtin-names.d.ts

@@ -0,0 +1,8 @@
+/** Names of the plugins bundled with structured-context. Each built-in plugin takes its `name` from here. */
+export declare const BUILTIN_PLUGIN_NAMES: {
+    readonly markdown: "sctx-markdown";
+    readonly mermaid: "sctx-mermaid";
+    readonly miro: "sctx-miro";
+};
+/** Whether a plugin name, with or without the prefix, names a built-in plugin. */
+export declare function isBuiltinPluginName(name: string): boolean;

package/dist/plugins/builtin-names.js

@@ -0,0 +1,13 @@
+import { PLUGIN_PREFIX } from '../constants';
+import { normalizePluginName } from './util';
+/** Names of the plugins bundled with structured-context. Each built-in plugin takes its `name` from here. */
+export const BUILTIN_PLUGIN_NAMES = {
+    markdown: `${PLUGIN_PREFIX}markdown`,
+    mermaid: `${PLUGIN_PREFIX}mermaid`,
+    miro: `${PLUGIN_PREFIX}miro`,
+};
+const builtinNames = new Set(Object.values(BUILTIN_PLUGIN_NAMES));
+/** Whether a plugin name, with or without the prefix, names a built-in plugin. */
+export function isBuiltinPluginName(name) {
+    return builtinNames.has(normalizePluginName(name));
+}

package/dist/plugins/loader.js

@@ -3,6 +3,7 @@ import { dirname, isAbsolute, join, resolve } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020';
 import { getConfigSourceFiles } from '../config';
 import { builtinPlugins } from '.';
+import { isBuiltinPluginName } from './builtin-names';
 import { CONFIG_PLUGINS_DIR, normalizePluginName, PLUGIN_PREFIX, shortenPluginName, } from './util';
 /**
  * Walk a plugin's configSchema and resolve any string fields annotated with
@@ -70,14 +71,13 @@ export async function discoverPlugins() {
  * relative to configDir.
  */
 export async function loadPlugins(pluginMap, configDir) {
-    const builtinsByName = new Map(builtinPlugins.map((p) => [p.name, p]));
     const ajv = new Ajv2020();
     ajv.addFormat('path', (value) => value.length > 0 && !value.includes('\0'));
     const loaded = [];
     // External plugins: entries in the map that are not built-in names
     for (const [rawName, rawConfig] of Object.entries(pluginMap)) {
         const name = normalizePluginName(rawName);
-        if (builtinsByName.has(name))
+        if (isBuiltinPluginName(name))
             continue;
         if (!name.startsWith(PLUGIN_PREFIX)) {
             throw new Error(`Plugin name must start with "${PLUGIN_PREFIX}" (got "${rawName}")`);

package/dist/plugins/markdown/extract-content-links.js

@@ -1,8 +1,6 @@
 import { toString as mdastToString } from 'mdast-util-to-string';
-import remarkGfm from 'remark-gfm';
-import remarkParse from 'remark-parse';
-import { unified } from 'unified';
 import { parseWikilink } from '../../read/wikilink-utils';
+import { parseMarkdown } from './parse-markdown';
 /**
  * Extract wikilinks (and Obsidian embed wikilinks) from a plain text string.
  * Matches [[target]], ![[target]], [[target#anchor]], [[target|alias]], etc.
@@ -77,8 +75,7 @@ export function extractLinksFromAstNode(node) {
  * Parses the full document and collects links from every node in the tree.
  */
 export function extractLinksFromBody(body) {
-    const tree = unified().use(remarkParse).use(remarkGfm).parse(body);
-    return extractLinksFromAstNode(tree);
+    return extractLinksFromAstNode(parseMarkdown(body));
 }
 /**
  * Build the set of field names that serve as graph edges (hierarchy + relationship fields).

package/dist/plugins/markdown/index.js

@@ -1,5 +1,5 @@
 import { statSync } from 'node:fs';
-import { PLUGIN_PREFIX } from '../util';
+import { BUILTIN_PLUGIN_NAMES } from '../builtin-names';
 import { readSpaceDirectory, readSpaceOnAPage } from './read-space';
 import { renderBullets } from './render-bullets';
 import { renderMarkdownDirectory } from './render-directory';
@@ -24,7 +24,7 @@ export const MARKDOWN_CONFIG_SCHEMA = {
     additionalProperties: false,
 };
 export function getMarkdownConfig(plugins) {
-    return (plugins?.[`${PLUGIN_PREFIX}markdown`] ?? {});
+    return (plugins?.[BUILTIN_PLUGIN_NAMES.markdown] ?? {});
 }
 async function parse(context) {
     if (statSync(context.space.path).isFile()) {
@@ -33,7 +33,7 @@ async function parse(context) {
     return await readSpaceDirectory(context);
 }
 export const markdownPlugin = {
-    name: `${PLUGIN_PREFIX}markdown`,
+    name: BUILTIN_PLUGIN_NAMES.markdown,
     configSchema: MARKDOWN_CONFIG_SCHEMA,
     parse,
     templateSync,

package/dist/plugins/markdown/parse-embedded.d.ts

@@ -1,3 +1,4 @@
+import type { Root } from 'mdast';
 import type { BaseNode, Relationship, SchemaMetadata } from '../../api';
 /** Type values that identify a space_on_a_page container (not themselves space nodes). */
 export declare const ON_A_PAGE_TYPES: string[];
@@ -85,11 +86,17 @@ export interface ExtractEmbeddedOptions {
     file?: string;
     /** Line offset of the body within the source file (e.g. frontmatter lines). */
     lineOffset?: number;
+    /** The tree of `body`, when the caller has already parsed it. */
+    tree?: Root;
 }
 export interface ExtractEmbeddedResult {
     nodes: BaseNode[];
     preambleNodeCount: number;
-    terminatedHeadings: string[];
+    /** Headings below a horizontal rule that would otherwise have become nodes. */
+    terminatedHeadings: {
+        title: string;
+        line?: number;
+    }[];
     preambleContent?: string;
     preambleFields?: Record<string, unknown>;
 }

package/dist/plugins/markdown/parse-embedded.js

@@ -1,8 +1,6 @@
 import { toString as mdastToString } from 'mdast-util-to-string';
-import remarkGfm from 'remark-gfm';
-import remarkParse from 'remark-parse';
-import { unified } from 'unified';
 import { extractLinksFromAstNode } from './extract-content-links';
+import { parseMarkdown } from './parse-markdown';
 import { applyFieldMap, parseYaml } from './util';
 /** Type values that identify a space_on_a_page container (not themselves space nodes). */
 export const ON_A_PAGE_TYPES = ['ost_on_a_page', 'space_on_a_page'];
@@ -332,7 +330,7 @@ export function extractEmbeddedNodes(body, options) {
         type: 'space_on_a_page',
         contentLinks: [],
     };
-    const tree = unified().use(remarkParse).use(remarkGfm).parse(body);
+    const tree = options.tree ?? parseMarkdown(body);
     // In typed-page mode: stack starts with the page's own virtual entry (depth 0).
     // In space_on_a_page mode: stack starts empty (first heading has no parent).
     const stack = !isOnAPageMode && page !== undefined
@@ -543,11 +541,18 @@ export function extractEmbeddedNodes(body, options) {
         /** Take this whole block out of a node's content, keeping the blank lines before it. */
         const consumeBlock = (node) => consume(claims, node, spanStart, blockStart);
         if (parseState === 'done') {
-            if (child.type === 'heading') {
-                const rawTitle = mdastToString(child);
-                const { cleanText: afterBracketed } = extractBracketedFields(rawTitle);
-                const { cleanText: title } = extractAnchor(afterBracketed);
-                terminatedHeadings.push(title);
+            if (child.type === 'heading' && child.depth <= 5) {
+                const { cleanText: afterBracketed, fields } = extractBracketedFields(mdastToString(child));
+                const { cleanText: title, anchor } = extractAnchor(afterBracketed);
+                // On a typed page, a plain heading is body text, so losing it below the rule loses no node.
+                const wouldBeNode = isOnAPageMode ||
+                    !!applyFieldMap(fields, fieldMap).type ||
+                    (!!anchor && !!anchorToNodeType(anchor, hierarchy, relationships)) ||
+                    !!matchEmbedding(title, getParentContextType(child.depth));
+                if (wouldBeNode) {
+                    const line = child.position ? child.position.start.line + (options.lineOffset ?? 0) : undefined;
+                    terminatedHeadings.push({ title, ...(line !== undefined ? { line } : {}) });
+                }
             }
             continue;
         }

package/dist/plugins/markdown/parse-markdown.d.ts

@@ -0,0 +1,3 @@
+import type { Root } from 'mdast';
+/** Parse markdown (with GFM) into an mdast tree. */
+export declare function parseMarkdown(markdown: string): Root;

package/dist/plugins/markdown/parse-markdown.js

@@ -0,0 +1,9 @@
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+// Built once: a frozen processor parses any number of documents.
+const processor = unified().use(remarkParse).use(remarkGfm).freeze();
+/** Parse markdown (with GFM) into an mdast tree. */
+export function parseMarkdown(markdown) {
+    return processor.parse(markdown);
+}

package/dist/plugins/markdown/read-space.js

@@ -3,9 +3,24 @@ import { basename, join, resolve } from 'node:path';
 import fg from 'fast-glob';
 import matter from 'gray-matter';
 import { extractSchemaTypeNames } from '../../schema/schema';
-import { extractLinksFromBody, extractLinksFromFrontmatter, getEdgeFieldNames } from './extract-content-links';
+import { extractLinksFromAstNode, extractLinksFromFrontmatter, getEdgeFieldNames } from './extract-content-links';
 import { extractEmbeddedNodes, ON_A_PAGE_TYPES } from './parse-embedded';
+import { parseMarkdown } from './parse-markdown';
 import { applyFieldMap, defaultPageTitle, inferTypeFromPath, MATTER_OPTIONS, pathLinkTargets } from './util';
+/** One warning per file for the headings a horizontal rule cut off, at the first of them. */
+function terminatedIssue(file, headings) {
+    const [first] = headings;
+    if (!first)
+        return undefined;
+    const more = headings.length > 1 ? ` and ${headings.length - 1} more` : '';
+    return {
+        file,
+        severity: 'warning',
+        type: 'terminated',
+        message: `Ignored heading "${first.title}"${more} below a horizontal rule (---).`,
+        ...(first.line !== undefined ? { line: first.line } : {}),
+    };
+}
 export function readSpaceOnAPage(context) {
     const { space, resolvedSchemaPath, schema: { metadata }, } = context;
     const filePath = resolve(space.path);
@@ -30,12 +45,8 @@ export function readSpaceOnAPage(context) {
         file: fileName,
         lineOffset,
     });
-    const parseIssues = terminatedHeadings.map((heading) => ({
-        file: heading,
-        severity: 'warning',
-        type: 'terminated',
-        message: 'Ignored headings detected beyond end of hierarchy.',
-    }));
+    const terminated = terminatedIssue(fileName, terminatedHeadings);
+    const parseIssues = terminated ? [terminated] : [];
     return { nodes, parseIssues, diagnostics: { kind: 'page', preambleNodeCount } };
 }
 export async function readSpaceDirectory(context, options) {
@@ -103,6 +114,8 @@ export async function readSpaceDirectory(context, options) {
         const pathTargets = pathLinkTargets(file);
         const fmMatch = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
         const lineOffset = fmMatch ? (fmMatch[0].match(/\n/g) || []).length : 0;
+        // The page's links come from the whole body; embedded nodes take theirs from their own blocks of the same tree.
+        const tree = parseMarkdown(parsed.content);
         const pageNode = {
             id: file,
             title,
@@ -112,7 +125,7 @@ export async function readSpaceDirectory(context, options) {
             type: pageType,
             source: { file, line: 1 },
             ...(data.content !== undefined ? { content: data.content } : {}),
-            contentLinks: [...extractLinksFromFrontmatter(data, edgeFields), ...extractLinksFromBody(parsed.content)],
+            contentLinks: [...extractLinksFromFrontmatter(data, edgeFields), ...extractLinksFromAstNode(tree)],
         };
         if (!ON_A_PAGE_TYPES.includes(pageType)) {
             const { nodes: embedded, preambleContent, preambleFields, terminatedHeadings, } = extractEmbeddedNodes(parsed.content, {
@@ -122,6 +135,7 @@ export async function readSpaceDirectory(context, options) {
                 fieldMap,
                 file,
                 lineOffset,
+                tree,
             });
             if (preambleFields) {
                 Object.assign(pageNode.schemaData, preambleFields);
@@ -132,14 +146,9 @@ export async function readSpaceDirectory(context, options) {
             }
             nodes.push(pageNode);
             nodes.push(...embedded);
-            for (const heading of terminatedHeadings) {
-                parseIssues.push({
-                    file: `${file} > ${heading}`,
-                    severity: 'warning',
-                    type: 'terminated',
-                    message: 'Ignored headings detected beyond end of hierarchy.',
-                });
-            }
+            const terminated = terminatedIssue(file, terminatedHeadings);
+            if (terminated)
+                parseIssues.push(terminated);
         }
         else {
             nodes.push(pageNode);

package/dist/plugins/mermaid/index.js

@@ -1,7 +1,7 @@
-import { PLUGIN_PREFIX } from '../util';
+import { BUILTIN_PLUGIN_NAMES } from '../builtin-names';
 import { renderMermaid } from './render-mermaid';
 export const mermaidPlugin = {
-    name: `${PLUGIN_PREFIX}mermaid`,
+    name: BUILTIN_PLUGIN_NAMES.mermaid,
     configSchema: { type: 'object', additionalProperties: false },
     render: {
         formats: [{ name: 'graph', description: 'Mermaid graph TD diagram' }],

package/dist/plugins/miro/index.d.ts

@@ -1,2 +1,2 @@
-import { type StructuredContextPlugin } from '../../api';
+import type { StructuredContextPlugin } from '../../api';
 export declare const miroPlugin: StructuredContextPlugin;

package/dist/plugins/miro/index.js

@@ -1,7 +1,7 @@
-import { PLUGIN_PREFIX } from '../../api';
+import { BUILTIN_PLUGIN_NAMES } from '../builtin-names';
 import { miroSync } from './sync';
 export const miroPlugin = {
-    name: `${PLUGIN_PREFIX}miro`,
+    name: BUILTIN_PLUGIN_NAMES.miro,
     configSchema: {
         type: 'object',
         properties: {

package/dist/plugins/util.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { PLUGIN_PREFIX as _PLUGIN_PREFIX } from '../constants';
+import { isBuiltinPluginName } from './builtin-names';
 export const PLUGIN_PREFIX = _PLUGIN_PREFIX;
 export const CONFIG_PLUGINS_DIR = 'plugins';
 /** Normalize a plugin name to its canonical prefixed form. */
@@ -111,6 +112,10 @@ export function resolveSpacePluginSchemas(space, config, configDir) {
     const pluginSources = [];
     const seenPlugins = new Set();
     const maybeAddPlugin = (name) => {
+        // Built-in plugins ship no schemas. Resolving one as a package can query the npm registry or find an unrelated
+        // package of the same short name (such as `markdown`).
+        if (isBuiltinPluginName(name))
+            return;
         const shortName = shortenPluginName(name);
         if (seenPlugins.has(shortName))
             return;

package/dist/read/resolve-graph-edges.js

@@ -131,13 +131,18 @@ function resolveEdge(nodesByType, targetIndex, edge, kind, hierarchy, selfRef, u
         }
     }
 }
+/**
+ * An RFC 3986 scheme (`mailto:`, `tel:`, `https://`), which need not be followed by `//`.
+ * Two characters at least, so a Windows drive letter (`C:\`) is not a scheme.
+ */
+const URL_SCHEME = /^([a-zA-Z][a-zA-Z0-9+.-]+):/;
 /**
  * Classify a ContentLink into a ResolvedContentLink by determining its location.
  *
  * Wikilinks are resolved against the target index: if found, location is 'node',
  * otherwise 'internal' (in the source system but not a space node).
  * Markdown links are classified by URL scheme: external (http/https), system (file://),
- * protocol (other scheme), or internal (relative path / no scheme).
+ * protocol (any other scheme, such as mailto: or obsidian://), or internal (relative path / no scheme).
  */
 function classifyContentLink(link, targetIndex) {
     const { linkSyntax, target, text, action, anchor } = link;
@@ -149,9 +154,8 @@ function classifyContentLink(link, targetIndex) {
         return { ...base, location: inIndex ? 'node' : 'internal' };
     }
     // Markdown link: classify by URL scheme.
-    const colonIdx = target.indexOf('://');
-    if (colonIdx > 0) {
-        const scheme = target.slice(0, colonIdx).toLowerCase();
+    const scheme = URL_SCHEME.exec(target)?.[1]?.toLowerCase();
+    if (scheme) {
         const location = scheme === 'https' || scheme === 'http' ? 'external' : scheme === 'file' ? 'system' : 'protocol';
         return { ...base, location };
     }

package/dist/types.d.ts

@@ -104,7 +104,7 @@ export type ResolvedContentLink = ContentLinkBase & {
      * - 'internal' — wikilink or relative path, in the source system but not a space node
      * - 'external' — http/https URL
      * - 'system'   — file:// URL
-     * - 'protocol' — other scheme (e.g. obsidian://)
+     * - 'protocol' — other scheme (e.g. obsidian://, mailto:)
      */
     location: 'node' | 'internal' | 'external' | 'system' | 'protocol';
 };
@@ -247,11 +247,15 @@ export type SpaceContext = {
     /** Directory of the config file that defines this space. Used for resolving relative paths in plugin configs. */
     configDir: string;
 };
+/** The checks a validation issue can come from. */
+export declare const VALIDATION_ISSUE_KINDS: readonly ["schema", "duplicate", "broken-link", "hierarchy", "rule", "gated", "content-link"];
+export type ValidationIssueKind = (typeof VALIDATION_ISSUE_KINDS)[number];
 export interface FileValidationIssue {
-    kind: string;
+    /** The check it came from. */
+    kind: ValidationIssueKind;
     message: string;
-    /** Present for rule violations (`kind: 'rule'`). */
-    severity?: RuleSeverity;
+    /** How serious the issue is; consumers read it rather than infer it from `kind`. */
+    severity: RuleSeverity;
     /** 1-indexed line number in source file, if available. */
     line?: number;
     /** 1-indexed column number in source file, if available. */
@@ -261,14 +265,11 @@ 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<string, FileValidationIssue>;
+    /** The file's issues of every severity, keyed by composite id (e.g. `schema:/status:enum:active`, `rule:my-rule-id`). */
+    issues: Record<string, FileValidationIssue>;
+    /** Issues at `error` severity: only these fail validation. */
     errorCount: number;
-    /**
-     * Warnings keyed by composite id, including `warning` and `info` severity rule violations.
-     * Do not affect exit code or errorCount.
-     */
-    warnings: Record<string, FileValidationIssue>;
+    /** Issues at `warning` or `info` severity. */
     warningCount: number;
     inSpace: true;
 }

package/dist/types.js

@@ -0,0 +1,10 @@
+/** The checks a validation issue can come from. */
+export const VALIDATION_ISSUE_KINDS = [
+    'schema',
+    'duplicate',
+    'broken-link',
+    'hierarchy',
+    'rule',
+    'gated',
+    'content-link',
+];

package/dist/validate.d.ts

@@ -3,7 +3,7 @@ import type { Config, SpaceConfig } from './config';
 import type { SemanticJudgeProvider } from './judge/types';
 import { type RuleFilter } from './schema/rule-filter';
 import { extractEntityInfo } from './schema/schema';
-import type { CoverageGate, FileNotInSpaceResult, FileValidationResult, GraphViolation, NodeId, ParseIssue, ReadSpaceResult, RuleViolation, SchemaWithMetadata, SourceLocation, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
+import type { CoverageGate, FileNotInSpaceResult, FileValidationIssue, FileValidationResult, GraphViolation, NodeId, ParseIssue, ReadSpaceResult, RuleViolation, SchemaWithMetadata, SourceLocation, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
 export interface FormattedError {
     message: string;
     dedupeKey: string;
@@ -33,10 +33,11 @@ export interface ValidationResult {
     hierarchyViolations: GraphViolation[];
     orphans: SpaceNode[];
     parseIssues: ParseIssue[];
-    /** Content links that could not be resolved to a space node. Warning only — not counted in errors. */
+    /** Content links that could not be resolved to a space node, at `info` severity: not counted in errors. */
     unresolvedContentLinks: Array<{
         nodeId: NodeId;
         target: string;
+        severity: 'info';
     }>;
     /**
      * Cascade gates: nodes whose schema/hierarchy failure or blocking rule violation
@@ -119,7 +120,7 @@ export declare function findDuplicateIds(nodes: SpaceNode[]): ValidationResult['
  * and `validateFile` are views over it, so a file's results match its entry in a full run.
  * `judgeTarget` limits judging to one file (and the ancestors that can gate it).
  */
-export declare function validateNodes(context: SpaceContext, nodes: SpaceNode[], unresolvedRefs: ReadSpaceResult['unresolvedRefs'], options?: RunOptions): Promise<SpaceValidationResult>;
+export declare function validateNodes(context: SpaceContext, nodes: SpaceNode[], read: Pick<ReadSpaceResult, 'unresolvedRefs' | 'parseIssues'>, options?: RunOptions): Promise<SpaceValidationResult>;
 /**
  * Run full validation on a space and return a structured result.
  * Does not output to console or call process.exit.
@@ -133,6 +134,17 @@ export declare function resolveFileSpace(filePath: string, config: Config): {
 export interface ValidateFileOptions extends CommonValidateOptions {
     configDir?: string;
 }
+/** The parts of a validation result that `nodeIssues` reads. */
+type NodeIssueSources = Pick<ValidationResult, 'nodeErrors' | 'refErrors' | 'duplicateErrors' | 'hierarchyViolations' | 'ruleViolations' | 'coverageGates' | 'unresolvedContentLinks'>;
+/**
+ * Every result that belongs to a node, by node id, each keyed by a composite id (e.g.
+ * `schema:/status:enum:active`, `rule:my-rule-id`) and carrying its severity. Rule violations without
+ * a node (global scope) and parse issues are not per node, so they stay in their own parts of the result.
+ * `includeGated` words the note on a gated node as it was validated.
+ */
+export declare function nodeIssues(result: NodeIssueSources, options?: {
+    includeGated?: boolean;
+}): Record<string, Record<string, FileValidationIssue>>;
 /** The result for a file that belongs to no configured space. */
 export declare function fileNotInSpace(filePath: string): FileNotInSpaceResult;
 /**

package/dist/validate.js

@@ -1,5 +1,6 @@
 import { isAbsolute, relative, resolve } from 'node:path';
 import { judgeForRun } from './judge/factory';
+import { pathLinkTargets } from './plugins/markdown/util';
 import { readSpace } from './read/read-space';
 import { computeHierarchyDepths, evaluateRulesWithGating } from './schema/gating';
 import { filterRules, parseRuleFilter } from './schema/rule-filter';
@@ -162,13 +163,25 @@ export function findDuplicateIds(nodes) {
     }
     return duplicates;
 }
+/** Link targets of the files a parse excluded but read, such as notes without a type. */
+function excludedFileTargets(parseIssues) {
+    const targets = new Set();
+    for (const issue of parseIssues) {
+        if (issue.type !== 'no-type' && issue.type !== 'parse')
+            continue;
+        for (const target of pathLinkTargets(issue.file))
+            targets.add(target);
+    }
+    return targets;
+}
 /**
  * The one validation pipeline: type and schema checks, duplicate titles, reference and hierarchy
  * checks, cascade-gated rules, and unresolved content links. Returns every entry; `validateSpace`
  * and `validateFile` are views over it, so a file's results match its entry in a full run.
  * `judgeTarget` limits judging to one file (and the ancestors that can gate it).
  */
-export async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
+export async function validateNodes(context, nodes, read, options = {}) {
+    const { unresolvedRefs } = read;
     const { schema, schemaRefRegistry, schemaValidator } = context;
     const metadata = schema.metadata;
     // Pre-extract valid types for early type validation
@@ -236,15 +249,17 @@ export async function validateNodes(context, nodes, unresolvedRefs, options = {}
         result.coverageGates = gates;
         result.contextTrimmed = summariseTrim(trimReport);
     }
-    // Collect unresolved content links (warnings — not errors)
+    // Collect unresolved content links (info — not errors). A link to a file the parser read but
+    // excluded (e.g. no type) resolves; that file's own parse issue already says why it is not a node.
+    const excludedTargets = excludedFileTargets(read.parseIssues);
     const seen = new Set();
     for (const node of nodes) {
         for (const link of node.resolvedLinks) {
-            if (link.location === 'internal') {
+            if (link.location === 'internal' && !excludedTargets.has(link.target)) {
                 const key = `${node.id}::${link.target}`;
                 if (!seen.has(key)) {
                     seen.add(key);
-                    result.unresolvedContentLinks.push({ nodeId: node.id, target: link.target });
+                    result.unresolvedContentLinks.push({ nodeId: node.id, target: link.target, severity: 'info' });
                 }
             }
         }
@@ -278,15 +293,11 @@ export async function validateSpace(context, options = {}) {
         }
         nodes = included;
     }
-    const result = await validateNodes(context, nodes, readResult.unresolvedRefs, runOptions);
+    const result = await validateNodes(context, nodes, readResult, runOptions);
     return {
         validCount: result.validCount,
         nodeErrorCount: result.nodeFailures.length,
-        nodeErrors: result.nodeFailures.map(({ node, issues }) => ({
-            nodeId: node.id,
-            ...(node.source !== undefined && { source: node.source }),
-            issues,
-        })),
+        nodeErrors: toNodeErrors(result.nodeFailures),
         refErrors: result.refErrors,
         duplicateErrors: result.duplicateErrors,
         ruleViolations: result.ruleViolations,
@@ -314,75 +325,67 @@ export function resolveFileSpace(filePath, config) {
     return null;
 }
 /**
- * Select one file's entries from a space's validation result: issues keyed and formatted, errors split from warnings.
- * Pure — a file's entries are exactly its slice of the result.
+ * Every result that belongs to a node, by node id, each keyed by a composite id (e.g.
+ * `schema:/status:enum:active`, `rule:my-rule-id`) and carrying its severity. Rule violations without
+ * a node (global scope) and parse issues are not per node, so they stay in their own parts of the result.
+ * `includeGated` words the note on a gated node as it was validated.
  */
-function issuesForFile(result, label, includeGated) {
-    const errors = {};
-    const warnings = {};
-    for (const { node, issues } of result.nodeFailures) {
-        if (node.id !== label)
-            continue;
+export function nodeIssues(result, options = {}) {
+    const byNode = {};
+    const add = (nodeId, key, issue) => {
+        byNode[nodeId] ??= {};
+        byNode[nodeId][key] = issue;
+    };
+    for (const { nodeId, source, issues } of result.nodeErrors) {
         const position = {
-            ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
-            ...(node.source?.column !== undefined ? { column: node.source.column } : {}),
+            ...(source?.line !== undefined ? { line: source.line } : {}),
+            ...(source?.column !== undefined ? { column: source.column } : {}),
         };
         for (const { message, dedupeKey } of issues) {
-            errors[`schema:${dedupeKey}`] = { kind: 'schema', message, ...position };
+            add(nodeId, `schema:${dedupeKey}`, { kind: 'schema', message, severity: 'error', ...position });
         }
     }
-    // Duplicate id errors — include if this node's id is duplicated
     for (const { id, sources } of result.duplicateErrors) {
-        if (id !== label)
-            continue;
-        errors[`duplicate:${id}`] = {
+        const where = sources.length > 0 ? `: ${sources.map(formatSource).join(', ')}` : '';
+        add(id, `duplicate:${id}`, {
             kind: 'duplicate',
-            message: `Duplicate id "${id}" is used by ${sources.length} nodes${sources.length > 0 ? `: ${sources.map(formatSource).join(', ')}` : ''}`,
-        };
+            message: `Duplicate id "${id}" is used by ${sources.length} nodes${where}`,
+            severity: 'error',
+        });
     }
-    // Broken links and hierarchy violations from this file
     for (const { nodeId, parent, error } of result.refErrors) {
-        if (nodeId === label) {
-            errors[`broken-link:${parent}`] = { kind: 'broken-link', message: `${parent} → ${error}` };
-        }
+        add(nodeId, `broken-link:${parent}`, { kind: 'broken-link', message: `${parent} → ${error}`, severity: 'error' });
     }
-    for (const v of result.hierarchyViolations) {
-        if (v.nodeId === label) {
-            errors[`hierarchy:${v.description}`] = { kind: 'hierarchy', message: v.description };
-        }
+    for (const { nodeId, description } of result.hierarchyViolations) {
+        add(nodeId, `hierarchy:${description}`, { kind: 'hierarchy', message: description, severity: 'error' });
     }
-    // Rule violations — only error severity counts as an error.
     for (const v of result.ruleViolations) {
-        if (v.nodeId === label) {
-            const target = v.severity === 'error' ? errors : warnings;
-            target[`rule:${v.ruleId}`] = {
-                kind: 'rule',
-                message: ruleViolationMessage(v),
-                severity: v.severity,
-            };
-        }
+        if (v.nodeId)
+            add(v.nodeId, `rule:${v.ruleId}`, { kind: 'rule', message: ruleViolationMessage(v), severity: v.severity });
     }
-    // A gated file with no violations would otherwise look clean — say that its rules were not checked.
+    // A gated node with no violations would otherwise look clean: say that its rules were not checked
     for (const gate of result.coverageGates) {
-        if (!gate.gatedNodeIds.some((id) => id === label))
-            continue;
         const cause = gate.reason === 'rule' ? `blocking rule "${gate.ruleId}"` : `${gate.reason} failure`;
-        warnings[`gated:${gate.nodeId}`] = {
-            kind: 'gated',
-            message: `Rule checks ${includeGated ? 'evaluated anyway' : 'not evaluated'}: gated by ${cause} on ${gate.nodeId}`,
-            severity: 'info',
-        };
+        const message = `Rule checks ${options.includeGated ? 'evaluated anyway' : 'not evaluated'}: gated by ${cause} on ${gate.nodeId}`;
+        for (const id of gate.gatedNodeIds)
+            add(id, `gated:${gate.nodeId}`, { kind: 'gated', message, severity: 'info' });
     }
-    // Unresolved content links (warnings — do not affect errorCount)
-    for (const link of result.unresolvedContentLinks) {
-        if (link.nodeId === label) {
-            warnings[`content-link:${link.target}`] = {
-                kind: 'content-link',
-                message: `Unresolved content link: ${link.target}`,
-            };
-        }
+    for (const { nodeId, target, severity } of result.unresolvedContentLinks) {
+        add(nodeId, `content-link:${target}`, {
+            kind: 'content-link',
+            message: `Unresolved content link: ${target}`,
+            severity,
+        });
     }
-    return { errors, warnings };
+    return byNode;
+}
+/** `ValidationResult['nodeErrors']` from the failures `validateNodes` collects */
+function toNodeErrors(failures) {
+    return failures.map(({ node, issues }) => ({
+        nodeId: node.id,
+        ...(node.source !== undefined && { source: node.source }),
+        issues,
+    }));
 }
 /** The result for a file that belongs to no configured space. */
 export function fileNotInSpace(filePath) {
@@ -402,19 +405,20 @@ export function validateResolvedFile(filePath, label, context, options = {}) {
 /** `validateResolvedFile` with the options already resolved, so a caller can supply its own judge. */
 export async function validateResolvedFileWith(filePath, label, context, runOptions) {
     const readResult = await readSpace(context);
-    const result = await validateNodes(context, readResult.nodes, readResult.unresolvedRefs, {
+    const result = await validateNodes(context, readResult.nodes, readResult, {
         ...runOptions,
         judgeTarget: label,
     });
-    const { errors, warnings } = issuesForFile(result, label, runOptions.includeGated);
+    const byNode = nodeIssues({ ...result, nodeErrors: toNodeErrors(result.nodeFailures) }, { includeGated: runOptions.includeGated });
+    const issues = byNode[label] ?? {};
+    const errorCount = Object.values(issues).filter((issue) => issue.severity === 'error').length;
     return {
         file: isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath),
         label,
         space: context.space.name,
-        errors,
-        errorCount: Object.keys(errors).length,
-        warnings,
-        warningCount: Object.keys(warnings).length,
+        issues,
+        errorCount,
+        warningCount: Object.keys(issues).length - errorCount,
         inSpace: true,
     };
 }

package/docs/concepts.md

@@ -83,7 +83,7 @@ Key properties:
 - Heading hierarchy determines node depth and infers `space node` type (depth-based type inference).
 - Heading levels must not skip — each level must be exactly one deeper than its parent.
 - Typed bullets work the same as in typed pages.
-- A horizontal rule (`---`) terminates parsing; headings below it are ignored.
+- A horizontal rule (`---`) terminates parsing; headings below it are ignored, with one warning for the file.
 
 #### Preamble
 
@@ -133,6 +133,8 @@ An **embedded node** is a `space node` defined *within* a containing document ra
 
 A `typed page` may contain embedded nodes in its body. Those nodes become full members of the parsed node set, with `parent references` wired to their containing page or enclosing heading.
 
+A horizontal rule (`---`) ends parsing for embedded nodes; headings below it do not become nodes. Validation warns once per file, at the first ignored heading that would have been a node. In a `space_on_a_page` file, that is every heading below the rule.
+
 ### Node content
 
 A node's `content` is the markdown of its body, copied unchanged from the file: blank lines, list looseness, line endings and code fences all stay as written. The content of a list item node is dedented by the item's content indent, so it reads as markdown on its own. Leading blank lines and trailing whitespace are trimmed.
@@ -354,7 +356,9 @@ Each entry is a `ResolvedContentLink` object:
 - `internal` — wikilink or relative path to an in-source target that is not a space node
 - `external` — `http://` or `https://` URL
 - `system` — `file://` URL
-- `protocol` — any other scheme (e.g. `obsidian://`)
+- `protocol` — any other scheme (e.g. `obsidian://`, `mailto:`, `tel:`). A bare email address is a `mailto:` link.
+
+`validate` reports each `internal` link as an unresolved content link, at `info` severity, because a target outside the space is often valid elsewhere. A link to a file the space read but did not make a node, such as a note without a `type`, is not reported. That file's own parse warning says why it is not a node.
 
 **Sources:** Both wikilink syntax (`[[Target]]`, `![[Image]]`) and markdown link syntax (`[text](url)`, `![alt](url)`) are extracted. Bare URLs in frontmatter string fields are also captured. Graph edge fields (hierarchy `parent`, relationship fields) are excluded — those are graph edges, not content links.
 

package/docs/rules.md

@@ -208,7 +208,7 @@ don't depend on an ancestor being valid.
 
 - Expressions are evaluated for the whole space; the output is restricted to the file.
 - Semantic parts are evaluated only for the file and its gating ancestors (see [Semantic rules](semantic-rules.md#how-semantic-evaluation-works)).
-- If the file is gated, its rules are skipped and a `gated:<file>` entry under `warnings` names the blocker, so a gated file doesn't read as clean. `--include-gated` evaluates the file's rules anyway.
+- If the file is gated, its rules are skipped and a `gated:<file>` issue at `info` severity names the blocker, so a gated file doesn't read as clean. `--include-gated` evaluates the file's rules anyway.
 
 ## Controlling validation runs
 
@@ -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`** — `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). 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`** — `error` severity violations appear under `errors`; `warning` and `info` violations appear under `warnings`. Rule entries carry a `severity` field.
+- **`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.
 
 Gated files: see [Single-file validation](#single-file-validation).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structured-context",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "Keep your content clean and your thinking clear with assistive tools for structured knowledge",
   "module": "./dist/index.js",
   "type": "module",
@@ -49,6 +49,7 @@
     "test:judge": "SCTX_LIVE_JUDGE_TESTS=1 bun test tests/judge/live.test.ts",
     "test:models": "SCTX_MODEL_VALIDATION=1 bun test tests/judge/model-validation.test.ts",
     "test:hook": "bun test hook-test/unit/",
+    "test:mod": "claude plugin test plugin",
     "test:hook:e2e": "bun test hook-test/hooks.test.ts",
     "test:all": "bun test",
     "lint": "biome check",