structured-context 0.17.0 → 0.18.0

package/README.md

@@ -79,10 +79,10 @@ claude plugin install structured-context
 
 Ask Claude to set up a space (or run `/setup-space`) in the folder that holds your notes. The plugin's hooks need Bun.
 
-Skills can also be installed standalone without the plugin:
+Skills can also be installed standalone without the plugin, and kept current with `npx skills update`:
 
 ```
-npx skills add https://github.com/mindsocket/structured-context/tree/main/plugin/skills/structured-context
+npx skills add https://github.com/mindsocket/structured-context/tree/main/plugin/skills
 ```
 
 ## Concepts

package/dist/commands/validate.js

@@ -5,7 +5,7 @@ import { judgeForRun } from '../judge/factory';
 import { resolveSpacePluginSchemas } from '../plugins/util';
 import { parseRuleFilter } from '../schema/rule-filter';
 import { bundledSchemasDir } from '../schema/schema';
-import { formatErrors, ruleViolationMessage, validateSpace } from '../validate';
+import { formatErrors, formatSource, ruleViolationMessage, validateSpace } from '../validate';
 export async function validate(context, options = {}) {
     const { schema, schemaRefRegistry } = context;
     const result = await validateSpace(context, {
@@ -25,29 +25,27 @@ export async function validate(context, options = {}) {
                 errorsByFile[file] = {};
             errorsByFile[file][key] = severity ? { kind, message, severity } : { kind, message };
         };
-        for (const { file, errors: ajvErrors, nodeData } of result.nodeErrors) {
+        for (const { nodeId, errors: ajvErrors, nodeData } of result.nodeErrors) {
             const formatted = formatErrors(ajvErrors, schema, schemaRefRegistry, nodeData);
             for (const { message, dedupeKey } of formatted) {
-                addError(file, `schema:${dedupeKey}`, 'schema', message);
+                addError(nodeId, `schema:${dedupeKey}`, 'schema', message);
             }
         }
-        for (const { file, parent, error } of result.refErrors) {
-            addError(file, `broken-link:${parent}`, 'broken-link', `${parent} → ${error}`);
+        for (const { nodeId, parent, error } of result.refErrors) {
+            addError(nodeId, `broken-link:${parent}`, 'broken-link', `${parent} → ${error}`);
         }
-        for (const { id, files } of result.duplicateErrors) {
-            for (const file of files) {
-                const others = files.filter((f) => f !== file);
-                addError(file, `duplicate:${id}`, 'duplicate', `Duplicate id "${id}" also exists in: ${others.join(', ')}`);
-            }
+        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.file && v.severity === 'error') {
-                addError(v.file, `rule:${v.ruleId}`, 'rule', ruleViolationMessage(v), v.severity);
+            if (v.nodeId && v.severity === 'error') {
+                addError(v.nodeId, `rule:${v.ruleId}`, 'rule', ruleViolationMessage(v), v.severity);
             }
         }
-        const globalRuleErrorCount = result.ruleViolations.filter((v) => !v.file && v.severity === 'error').length;
+        const globalRuleErrorCount = result.ruleViolations.filter((v) => !v.nodeId && v.severity === 'error').length;
         for (const v of result.hierarchyViolations) {
-            addError(v.file, `hierarchy:${v.description}`, 'hierarchy', v.description);
+            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) +
@@ -100,13 +98,13 @@ export async function validate(context, options = {}) {
     if (result.unresolvedContentLinks.length > 0) {
         console.log(`\nUnresolved content links (may be outside-space or broken):`);
         const byFile = new Map();
-        for (const { file, target } of result.unresolvedContentLinks) {
-            if (!byFile.has(file))
-                byFile.set(file, []);
-            byFile.get(file).push(target);
+        for (const { nodeId, target } of result.unresolvedContentLinks) {
+            if (!byFile.has(nodeId))
+                byFile.set(nodeId, []);
+            byFile.get(nodeId).push(target);
         }
-        for (const [file, targets] of byFile) {
-            console.log(`   ${file}:`);
+        for (const [nodeId, targets] of byFile) {
+            console.log(`   ${nodeId}:`);
             for (const target of targets)
                 console.log(`      ${target}`);
         }
@@ -121,9 +119,8 @@ export async function validate(context, options = {}) {
     }
     if (result.nodeErrors.length > 0) {
         console.log(`\nSchema validation errors:`);
-        result.nodeErrors.forEach(({ file, line, errors, nodeData }) => {
-            const loc = line !== undefined ? `:${line}` : '';
-            console.log(`\n   ${file}${loc}:`);
+        result.nodeErrors.forEach(({ nodeId, source, errors, nodeData }) => {
+            console.log(`\n   ${source ? formatSource(source) : nodeId}:`);
             const formatted = formatErrors(errors, schema, schemaRefRegistry, nodeData);
             formatted.forEach(({ message }) => {
                 console.log(`      ${message}`);
@@ -132,17 +129,16 @@ export async function validate(context, options = {}) {
     }
     if (result.refErrors.length > 0) {
         console.log(`\nBroken links:`);
-        result.refErrors.forEach(({ file, line, parent, error }) => {
-            const loc = line !== undefined ? `:${line}` : '';
-            console.log(`   ${file}${loc}: ${parent} → ${error}`);
+        result.refErrors.forEach(({ nodeId, source, parent, error }) => {
+            console.log(`   ${source ? formatSource(source) : nodeId}: ${parent} → ${error}`);
         });
     }
     if (result.duplicateErrors.length > 0) {
         console.log(`\nDuplicate ids (same id on multiple nodes):`);
-        result.duplicateErrors.forEach(({ id, files }) => {
+        result.duplicateErrors.forEach(({ id, sources }) => {
             console.log(`   "${id}":`);
-            for (const f of files) {
-                console.log(`      ${f}`);
+            for (const source of sources) {
+                console.log(`      ${formatSource(source)}`);
             }
         });
     }
@@ -155,7 +151,7 @@ export async function validate(context, options = {}) {
                 continue;
             console.log(`  ${severityColor[severity]}${severity.toUpperCase()}${reset} (${violations.length}):`);
             for (const v of violations) {
-                console.log(`    ${v.file ? `${v.file}: ` : ''}${v.description} [${v.category}: ${v.ruleId}]`);
+                console.log(`    ${v.nodeId ? `${v.nodeId}: ` : ''}${v.description} [${v.category}: ${v.ruleId}]`);
                 if (v.evidence) {
                     console.log(`      Evidence: ${v.evidence}`);
                 }
@@ -168,22 +164,22 @@ export async function validate(context, options = {}) {
     if (result.hierarchyViolations.length > 0) {
         console.log(`\nHierarchy violations:`);
         for (const v of result.hierarchyViolations) {
-            console.log(`   ${v.file}: ${v.description}`);
+            console.log(`   ${v.nodeId}: ${v.description}`);
         }
     }
     if (result.coverageGates.length > 0) {
         console.log(`\nCoverage — rule checks gated by cascade (use --include-gated to evaluate anyway):`);
         for (const gate of result.coverageGates) {
             const cause = gate.reason === 'rule' ? `blocking rule "${gate.ruleId}"` : `${gate.reason} failure`;
-            console.log(`   ${gate.file} (${gate.nodeId}) — ${cause} gated ${gate.gatedFiles.length} node(s):`);
-            for (const file of gate.gatedFiles)
-                console.log(`      ${file}`);
+            console.log(`   ${gate.nodeId} — ${cause} gated ${gate.gatedNodeIds.length} node(s):`);
+            for (const nodeId of gate.gatedNodeIds)
+                console.log(`      ${nodeId}`);
         }
     }
     if (result.skippedByDepth.length > 0) {
         console.log(`\nSkipped by depth limit (--depth ${result.depthLimit}):`);
-        for (const { file } of result.skippedByDepth)
-            console.log(`   ${file}`);
+        for (const { nodeId } of result.skippedByDepth)
+            console.log(`   ${nodeId}`);
     }
     if (result.contextTrimmed.nodeCount > 0) {
         console.log(`\nContext trimmed for ${result.contextTrimmed.nodeCount} node(s) across rules ${result.contextTrimmed.ruleIds.join(', ')}.`);
@@ -206,7 +202,7 @@ export async function validate(context, options = {}) {
     if (result.depthLimit !== undefined) {
         console.log(fmt('  Skipped by depth limit', result.skippedByDepth.length, true, true));
     }
-    const gatedFileCount = result.coverageGates.reduce((sum, g) => sum + g.gatedFiles.length, 0);
+    const gatedFileCount = result.coverageGates.reduce((sum, g) => sum + g.gatedNodeIds.length, 0);
     console.log(fmt('  Rule checks gated (cascade)', gatedFileCount, true, true));
     console.log(`\n`);
     if (result.nodeErrorCount > 0 ||

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

@@ -442,8 +442,15 @@ export function extractEmbeddedNodes(body, options) {
         }
         return undefined;
     }
+    // Ids must be unique, but headings on one page may repeat: the second and later get a ` (2)`, ` (3)` suffix.
+    const usedIds = new Set();
     function makeId(title) {
-        return (page ? `${page.id}#${title}` : title);
+        const base = page ? `${page.id}#${title}` : title;
+        let id = base;
+        for (let n = 2; usedIds.has(id); n++)
+            id = `${base} (${n})`;
+        usedIds.add(id);
+        return id;
     }
     /**
      * Walk the stack backwards to find the deepest typed node entry (nodeType !== '').

package/dist/schema/evaluate-rule.d.ts

@@ -42,7 +42,7 @@ export declare function tryEvaluateExpression(expr: string, context: EvalContext
  */
 export declare function buildEvalContext(node: SpaceNode, allNodes: SpaceNode[], nodeIndex: Map<NodeId, SpaceNode>): EvalContext;
 /** The violation reported when a rule's `expression` or `when` cannot be evaluated: an authoring error, so always `error`. */
-export declare function expressionErrorViolation(rule: Rule, file: string, error: string): RuleViolation;
+export declare function expressionErrorViolation(rule: Rule, nodeId: NodeId | null, error: string): RuleViolation;
 /** The outcome of a rule's `expression` on one node. */
 export type ExpressionRuleResult = {
     passed: true;
@@ -54,8 +54,8 @@ export type ExpressionRuleResult = {
     failed: boolean;
 };
 /**
- * Evaluate a rule's `expression` against a node (`file` empty and `node` a sentinel for a global rule). A failure
+ * Evaluate a rule's `expression` against a node (`nodeId` null and `node` a sentinel for a global rule). A failure
  * reports the rule's severity; a rule with a semantic part names the expression in the evidence, so the
  * violation is not mistaken for a verdict. An evaluation error reports `error` and is not a `failed` result.
  */
-export declare function evaluateRuleExpression(rule: Rule, node: SpaceNode, allNodes: SpaceNode[], nodeIndex: Map<NodeId, SpaceNode>, file?: string): Promise<ExpressionRuleResult>;
+export declare function evaluateRuleExpression(rule: Rule, node: SpaceNode, allNodes: SpaceNode[], nodeIndex: Map<NodeId, SpaceNode>, nodeId?: NodeId | null): Promise<ExpressionRuleResult>;

package/dist/schema/evaluate-rule.js

@@ -104,9 +104,9 @@ export function buildEvalContext(node, allNodes, nodeIndex) {
     };
 }
 /** The violation reported when a rule's `expression` or `when` cannot be evaluated: an authoring error, so always `error`. */
-export function expressionErrorViolation(rule, file, error) {
+export function expressionErrorViolation(rule, nodeId, error) {
     return {
-        file,
+        ...(nodeId !== null && { nodeId }),
         ruleId: rule.id,
         category: rule.category,
         severity: 'error',
@@ -114,15 +114,15 @@ export function expressionErrorViolation(rule, file, error) {
     };
 }
 /**
- * Evaluate a rule's `expression` against a node (`file` empty and `node` a sentinel for a global rule). A failure
+ * Evaluate a rule's `expression` against a node (`nodeId` null and `node` a sentinel for a global rule). A failure
  * reports the rule's severity; a rule with a semantic part names the expression in the evidence, so the
  * violation is not mistaken for a verdict. An evaluation error reports `error` and is not a `failed` result.
  */
-export async function evaluateRuleExpression(rule, node, allNodes, nodeIndex, file = node.id) {
+export async function evaluateRuleExpression(rule, node, allNodes, nodeIndex, nodeId = node.id) {
     const expression = rule.expression;
     const outcome = await tryEvaluateExpression(expression, buildEvalContext(node, allNodes, nodeIndex));
     if ('error' in outcome) {
-        return { passed: false, failed: false, violation: expressionErrorViolation(rule, file, outcome.error) };
+        return { passed: false, failed: false, violation: expressionErrorViolation(rule, nodeId, outcome.error) };
     }
     if (outcome.value === true)
         return { passed: true };
@@ -130,7 +130,7 @@ export async function evaluateRuleExpression(rule, node, allNodes, nodeIndex, fi
         passed: false,
         failed: true,
         violation: {
-            file,
+            ...(nodeId !== null && { nodeId }),
             ruleId: rule.id,
             category: rule.category,
             severity: ruleSeverity(rule),

package/dist/schema/gating.d.ts

@@ -12,8 +12,6 @@ export declare function ruleGatesDescendants(rule: Rule, severity?: RuleSeverity
  * (schema validation or hierarchy structure) that failed on a specific node.
  */
 export type GatingSeed = {
-    /** Id (file) of the failing node. */
-    file: string;
     /** Id of the failing node. */
     id: NodeId;
     /** Which always-run layer produced the failure. */
@@ -24,16 +22,14 @@ export type GatingSeed = {
  * rule evaluation for itself (if schema/hierarchy caused it) and/or its hierarchy subtree.
  */
 export type CoverageGate = {
-    /** Id (file) of the node whose failure triggered this gate. */
-    file: string;
     /** Id of the blocking node. */
     nodeId: NodeId;
     /** What kind of check triggered the gate. */
     reason: 'schema' | 'hierarchy' | 'rule';
     /** Rule id responsible, when `reason` is `'rule'`. */
     ruleId?: string;
-    /** Labels of nodes whose rule evaluation was suppressed as a result of this gate. */
-    gatedFiles: string[];
+    /** Ids of nodes whose rule evaluation was suppressed as a result of this gate. */
+    gatedNodeIds: NodeId[];
 };
 export type GatedRuleEvaluation = {
     violations: RuleViolation[];

package/dist/schema/gating.js

@@ -64,7 +64,7 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
     function originFor(id, seed) {
         let origin = gateOrigins.get(id);
         if (!origin) {
-            origin = { file: seed.file, nodeId: id, reason: seed.reason, ruleId: seed.ruleId, gatedFiles: [] };
+            origin = { nodeId: id, reason: seed.reason, ruleId: seed.ruleId, gatedNodeIds: [] };
             gateOrigins.set(id, origin);
         }
         return origin;
@@ -73,7 +73,7 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
     const sentinel = nodes[0];
     if (sentinel) {
         for (const rule of globalRules) {
-            const result = await evaluateRuleExpression(rule, sentinel, nodes, nodeIndex, '');
+            const result = await evaluateRuleExpression(rule, sentinel, nodes, nodeIndex, null);
             if (!result.passed)
                 violations.push(result.violation);
         }
@@ -129,7 +129,7 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
         function report(rule, detail = {}) {
             const severity = detail.severity ?? ruleSeverities(rule)[0] ?? ruleSeverity(rule);
             local.push({
-                file: node.id,
+                nodeId: node.id,
                 ruleId: rule.id,
                 category: rule.category,
                 severity,
@@ -227,15 +227,15 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
             const blockingRuleId = blockingById.get(node.id);
             let childOrigin = ancestorOrigin;
             if (isGatedByAncestor) {
-                gateOrigins.get(ancestorOrigin).gatedFiles.push(node.id);
+                gateOrigins.get(ancestorOrigin).gatedNodeIds.push(node.id);
             }
             else if (isSelfBlocked) {
-                const origin = originFor(node.id, { file: selfSeed.file, reason: selfSeed.reason });
-                origin.gatedFiles.push(node.id);
+                const origin = originFor(node.id, { reason: selfSeed.reason });
+                origin.gatedNodeIds.push(node.id);
                 childOrigin = node.id;
             }
             else if (blockingRuleId) {
-                originFor(node.id, { file: node.id, reason: 'rule', ruleId: blockingRuleId });
+                originFor(node.id, { reason: 'rule', ruleId: blockingRuleId });
                 childOrigin = node.id;
             }
             else {
@@ -249,6 +249,6 @@ export async function evaluateRulesWithGating(nodes, rules, graph, seeds, option
     }
     return {
         violations,
-        gates: [...gateOrigins.values()].filter((g) => g.gatedFiles.length > 0),
+        gates: [...gateOrigins.values()].filter((g) => g.gatedNodeIds.length > 0),
     };
 }

package/dist/schema/validate-graph.d.ts

@@ -1,9 +1,9 @@
-import type { GraphViolation, SchemaMetadata, SpaceNode, UnresolvedRef } from '../types';
+import type { GraphViolation, NodeId, SchemaMetadata, SourceLocation, SpaceNode, UnresolvedRef } from '../types';
 export interface GraphValidationResult {
     violations: GraphViolation[];
     refErrors: Array<{
-        file: string;
-        line?: number;
+        nodeId: NodeId;
+        source?: SourceLocation;
         parent: string;
         error: string;
     }>;

package/dist/schema/validate-graph.js

@@ -5,8 +5,8 @@ import { resolveNodeType } from '../schema/schema';
  */
 export function validateGraph(nodes, metadata, unresolvedRefs = []) {
     const refErrors = unresolvedRefs.map((u) => ({
-        file: u.source?.file ?? u.id,
-        ...(u.source?.line !== undefined ? { line: u.source.line } : {}),
+        nodeId: u.id,
+        ...(u.source !== undefined && { source: u.source }),
         parent: u.ref,
         error: u.message,
     }));
@@ -87,7 +87,7 @@ export function validateHierarchyStructure(nodes, metadata) {
                 if (allowedChildTypes && !allowedChildTypes.has(nodeType)) {
                     const expected = [...allowedChildTypes].join(' or ');
                     violations.push({
-                        file: parentNode.id,
+                        nodeId: parentNode.id,
                         nodeType: parentType,
                         nodeTitle: parentTitle,
                         parentType: nodeType,
@@ -102,7 +102,7 @@ export function validateHierarchyStructure(nodes, metadata) {
                 if (allowedTypes && !allowedTypes.has(parentType)) {
                     const expected = [...allowedTypes].join(' or ');
                     violations.push({
-                        file: node.id,
+                        nodeId: node.id,
                         nodeType,
                         nodeTitle,
                         parentType,
@@ -140,7 +140,7 @@ export function validateHierarchyStructure(nodes, metadata) {
                 }
                 if (!isValidHierarchy) {
                     violations.push({
-                        file: node.id,
+                        nodeId: node.id,
                         nodeType,
                         nodeTitle,
                         parentType,

package/dist/schema/validate-rules.js

@@ -55,7 +55,7 @@ export async function validateRules(nodes, rules, options = {}) {
         if (rule.global) {
             if (!sentinel)
                 continue;
-            const result = await evaluateRuleExpression(rule, sentinel, nodes, nodeIndex, '');
+            const result = await evaluateRuleExpression(rule, sentinel, nodes, nodeIndex, null);
             if (!result.passed)
                 violations.push(result.violation);
             continue;
@@ -93,7 +93,7 @@ export async function validateRules(nodes, rules, options = {}) {
                 if (!j.violated)
                     continue;
                 found.push({
-                    file: node.id,
+                    nodeId: node.id,
                     ruleId: j.rule.id,
                     category: j.rule.category,
                     severity: j.severity ?? ruleSeverities(j.rule)[0] ?? ruleSeverity(j.rule),

package/dist/types.d.ts

@@ -178,8 +178,8 @@ export type RuleSeverity = 'error' | 'warning' | 'info';
 export type { CoverageGate, GatingSeed } from './schema/gating';
 export type { Rule } from './schema/metadata-contract';
 export type RuleViolation = {
-    /** Node id, or empty string for global-scope rules. */
-    file: string;
+    /** Id of the violating node. Absent for global-scope rules. */
+    nodeId?: NodeId;
     ruleId: string;
     category: RuleCategory;
     severity: RuleSeverity;
@@ -192,7 +192,8 @@ export type RuleViolation = {
     guidance?: string;
 };
 export type GraphViolation = {
-    file: string;
+    /** Id of the node whose parent link breaks the hierarchy. */
+    nodeId: NodeId;
     nodeType: string;
     nodeTitle: string;
     parentType: string;

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, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
+import type { CoverageGate, FileNotInSpaceResult, FileValidationResult, GraphViolation, NodeId, ParseIssue, ReadSpaceResult, RuleViolation, SchemaWithMetadata, SourceLocation, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
 export interface FormattedError {
     message: string;
     dedupeKey: string;
@@ -12,20 +12,21 @@ export interface ValidationResult {
     validCount: number;
     nodeErrorCount: number;
     nodeErrors: Array<{
-        file: string;
-        line?: number;
+        nodeId: NodeId;
+        source?: SourceLocation;
         errors: ErrorObject[];
         nodeData: Record<string, unknown>;
     }>;
     refErrors: Array<{
-        file: string;
-        line?: number;
+        nodeId: NodeId;
+        source?: SourceLocation;
         parent: string;
         error: string;
     }>;
+    /** Nodes that share an id; `sources` lists where each is defined (a node without a source adds no entry). */
     duplicateErrors: Array<{
         id: NodeId;
-        files: string[];
+        sources: SourceLocation[];
     }>;
     /** All rule violations with their effective severity. Only `error` severity fails validation. */
     ruleViolations: RuleViolation[];
@@ -34,7 +35,7 @@ export interface ValidationResult {
     parseIssues: ParseIssue[];
     /** Content links that could not be resolved to a space node. Warning only — not counted in errors. */
     unresolvedContentLinks: Array<{
-        file: string;
+        nodeId: NodeId;
         target: string;
     }>;
     /**
@@ -50,7 +51,7 @@ export interface ValidationResult {
     };
     /** Nodes excluded from validation entirely by a `depth` limit (breadth-first from hierarchy roots). */
     skippedByDepth: Array<{
-        file: string;
+        nodeId: NodeId;
         title: string;
     }>;
     /** The depth limit applied, if any (undefined means the full space was validated). */
@@ -72,8 +73,15 @@ export interface ValidateSpaceOptions {
     /** Evaluates `semantic` rules. Without one, a rule runs only its `expression`, and a semantic-only rule is skipped. */
     judge?: SemanticJudgeProvider;
 }
+/** `file`, `file:line` or `file:line:column`, for messages. */
+export declare function formatSource({ file, line, column }: SourceLocation): string;
 /** One-line text for a rule violation: rule, description, and any evidence and verdict guidance. */
 export declare function ruleViolationMessage(v: RuleViolation): string;
+/**
+ * Nodes that share an id, with where each is defined. A plugin should keep ids unique, so this guards that contract.
+ * Display titles may repeat.
+ */
+export declare function findDuplicateIds(nodes: SpaceNode[]): ValidationResult['duplicateErrors'];
 /**
  * Run full validation on a space and return a structured result.
  * Does not output to console or call process.exit.

package/dist/validate.js

@@ -94,6 +94,10 @@ export function formatErrors(errors, schema, schemaRefRegistry, nodeData) {
     }
     return formatted;
 }
+/** `file`, `file:line` or `file:line:column`, for messages. */
+export function formatSource({ file, line, column }) {
+    return line === undefined ? file : `${file}:${line}${column === undefined ? '' : `:${column}`}`;
+}
 /** One-line text for a rule violation: rule, description, and any evidence and verdict guidance. */
 export function ruleViolationMessage(v) {
     const evidence = v.evidence ? ` (Evidence: ${v.evidence})` : '';
@@ -131,6 +135,24 @@ async function evaluateSpaceRules(nodes, metadata, seeds, options = {}) {
         trimReport: options.trimReport,
     });
 }
+/**
+ * Nodes that share an id, with where each is defined. A plugin should keep ids unique, so this guards that contract.
+ * Display titles may repeat.
+ */
+export function findDuplicateIds(nodes) {
+    const idToNodes = new Map();
+    for (const node of nodes) {
+        if (!idToNodes.has(node.id))
+            idToNodes.set(node.id, []);
+        idToNodes.get(node.id).push(node);
+    }
+    const duplicates = [];
+    for (const [id, sameId] of idToNodes) {
+        if (sameId.length > 1)
+            duplicates.push({ id, sources: sameId.flatMap((n) => (n.source ? [n.source] : [])) });
+    }
+    return duplicates;
+}
 /**
  * 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`
@@ -182,19 +204,7 @@ async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
             result.nodeFailures.push({ node, errors: schemaValidator.errors || [] });
         }
     }
-    // Detect duplicate node ids. Display titles may repeat.
-    const idToFiles = new Map();
-    for (const node of nodes) {
-        if (!idToFiles.has(node.id)) {
-            idToFiles.set(node.id, []);
-        }
-        idToFiles.get(node.id).push(node.id);
-    }
-    for (const [id, files] of idToFiles) {
-        if (files.length > 1) {
-            result.duplicateErrors.push({ id, files });
-        }
-    }
+    result.duplicateErrors.push(...findDuplicateIds(nodes));
     // Validate all hierarchy constraints (field references and structure)
     const hierarchyValidation = validateGraph(nodes, metadata, unresolvedRefs);
     result.refErrors.push(...hierarchyValidation.refErrors);
@@ -207,9 +217,9 @@ async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
     if (metadata.rules) {
         const seeds = [
             ...result.nodeFailures.map(({ node }) => {
-                return { file: node.source?.file ?? node.id, id: node.id, reason: 'schema' };
+                return { id: node.id, reason: 'schema' };
             }),
-            ...result.hierarchyViolations.map((v) => ({ file: v.file, id: v.file, reason: 'hierarchy' })),
+            ...result.hierarchyViolations.map((v) => ({ id: v.nodeId, reason: 'hierarchy' })),
         ];
         const trimReport = { nodes: new Set(), ruleIds: new Set() };
         const { violations, gates } = await evaluateSpaceRules(nodes, metadata, seeds, { ...options, trimReport });
@@ -225,7 +235,7 @@ async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
                 const key = `${node.id}::${link.target}`;
                 if (!seen.has(key)) {
                     seen.add(key);
-                    result.unresolvedContentLinks.push({ file: node.id, target: link.target });
+                    result.unresolvedContentLinks.push({ nodeId: node.id, target: link.target });
                 }
             }
         }
@@ -250,7 +260,7 @@ export async function validateSpace(context, options = {}) {
         for (const node of nodes) {
             const nodeDepth = depths.get(node.id);
             if (nodeDepth !== undefined && nodeDepth > options.depth) {
-                skippedByDepth.push({ file: node.id, title: node.title });
+                skippedByDepth.push({ nodeId: node.id, title: node.title });
             }
             else {
                 included.push(node);
@@ -267,8 +277,8 @@ export async function validateSpace(context, options = {}) {
         validCount: result.validCount,
         nodeErrorCount: result.nodeFailures.length,
         nodeErrors: result.nodeFailures.map(({ node, errors }) => ({
-            file: node.source?.file ?? node.id,
-            ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
+            nodeId: node.id,
+            ...(node.source !== undefined && { source: node.source }),
             errors,
             nodeData: node.schemaData,
         })),
@@ -326,30 +336,29 @@ function issuesForFile(result, label, context, includeGated) {
             errors[`schema:${dedupeKey}`] = { kind: 'schema', message, ...position };
         }
     }
-    // Duplicate key errors — include if this file is one of the duplicates
-    for (const { id, files } of result.duplicateErrors) {
-        if (!files.includes(label))
+    // Duplicate id errors — include if this node's id is duplicated
+    for (const { id, sources } of result.duplicateErrors) {
+        if (id !== label)
             continue;
-        const others = files.filter((f) => f !== label);
         errors[`duplicate:${id}`] = {
             kind: 'duplicate',
-            message: `Duplicate id "${id}" also exists in: ${others.join(', ')}`,
+            message: `Duplicate id "${id}" is used by ${sources.length} nodes${sources.length > 0 ? `: ${sources.map(formatSource).join(', ')}` : ''}`,
         };
     }
     // Broken links and hierarchy violations from this file
-    for (const { file, parent, error } of result.refErrors) {
-        if (file === label) {
+    for (const { nodeId, parent, error } of result.refErrors) {
+        if (nodeId === label) {
             errors[`broken-link:${parent}`] = { kind: 'broken-link', message: `${parent} → ${error}` };
         }
     }
     for (const v of result.hierarchyViolations) {
-        if (v.file === label) {
+        if (v.nodeId === label) {
             errors[`hierarchy:${v.description}`] = { kind: 'hierarchy', message: v.description };
         }
     }
     // Rule violations — only error severity counts as an error.
     for (const v of result.ruleViolations) {
-        if (v.file === label) {
+        if (v.nodeId === label) {
             const target = v.severity === 'error' ? errors : warnings;
             target[`rule:${v.ruleId}`] = {
                 kind: 'rule',
@@ -360,18 +369,18 @@ function issuesForFile(result, label, context, includeGated) {
     }
     // A gated file with no violations would otherwise look clean — say that its rules were not checked.
     for (const gate of result.coverageGates) {
-        if (!gate.gatedFiles.includes(label))
+        if (!gate.gatedNodeIds.some((id) => id === label))
             continue;
         const cause = gate.reason === 'rule' ? `blocking rule "${gate.ruleId}"` : `${gate.reason} failure`;
-        warnings[`gated:${gate.file}`] = {
+        warnings[`gated:${gate.nodeId}`] = {
             kind: 'gated',
-            message: `Rule checks ${includeGated ? 'evaluated anyway' : 'not evaluated'}: gated by ${cause} on ${gate.file}`,
+            message: `Rule checks ${includeGated ? 'evaluated anyway' : 'not evaluated'}: gated by ${cause} on ${gate.nodeId}`,
             severity: 'info',
         };
     }
     // Unresolved content links (warnings — do not affect errorCount)
     for (const link of result.unresolvedContentLinks) {
-        if (link.file === label) {
+        if (link.nodeId === label) {
             warnings[`content-link:${link.target}`] = {
                 kind: 'content-link',
                 message: `Unresolved content link: ${link.target}`,

package/docs/concepts.md

@@ -111,12 +111,18 @@ Three values on every node do separate jobs:
 
 | Value | Job | Unique? | Markdown source |
 |---|---|---|---|
-| `id` | Identifies the node: graph key, parent lookup, gating, duplicate detection, and the file shown in messages | Yes. Two nodes with the same `id` are a duplicate error | Path relative to the space root, with extension (`projects/alpha/Overview.md`). Embedded nodes use `<page id>#<heading>` |
+| `id` | Identifies the node: graph key, parent lookup, gating, duplicate detection, and the file shown in messages | Yes. Two nodes with the same `id` are a duplicate error | Path relative to the space root, with extension (`projects/alpha/Overview.md`). Embedded nodes use `<page id>#<heading>`, with ` (2)`, ` (3)` added to repeated headings on one page |
 | `title` | Display name in `show`, rendered output and judge prompts | No | `title:` frontmatter, else the containing folder's name for a [folder index](#folder-index), else the file's basename |
 | `linkTargets` | The names a wikilink may use to reach the node | Per name. A name shared by several nodes is reported as ambiguous where a link uses it | The explicit `title:`, the basename, and every path suffix without `.md` |
 
 A wikilink is looked up in `linkTargets`, and the result is stored as the target node's `id`. Other values hold the rest of the picture: `source` is where the node is defined, `resolvedParents` lists parents by `id`, and `resolvedLinks` classifies content links. A parent field resolves exactly as a link does.
 
+### 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`.
+
 ### Folder index
 
 A **folder index** is a page that stands for its folder: `Overview.md` or `index.md` inside `projects/alpha/`. Obsidian has no container pages, so a node with child pages is a folder plus an index page. Listing the index basenames in the markdown plugin's [`folderIndex`](config.md#folderindex) config gives each folder index the folder's name as its `title`. The derived title is for display only and never a link target.

package/docs/rules.md

@@ -193,7 +193,7 @@ A rule has one `gatesDescendants` setting. It applies to whichever part reported
 ### Coverage output
 
 `sctx validate` reports gating as **coverage gates**: which node's violation (schema,
-hierarchy, or a specific `ruleId`) suppressed rule evaluation, and the list of files gated
+hierarchy, or a specific `ruleId`) suppressed rule evaluation, and the ids of the nodes gated
 as a result. This makes the validation "edge" visible — e.g. "this blocked goal means all
 opportunities beneath it were not evaluated" — for both human reading and agent consumption
 (JSON output via `--json`, under `coverageGates`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structured-context",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Keep your content clean and your thinking clear with assistive tools for structured knowledge",
   "module": "./dist/index.js",
   "type": "module",
@@ -61,7 +61,6 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.310",
     "@biomejs/biome": "^2.5.15",
     "@types/bun": "^1.4.4",
-    "json-schema-to-ts": "^3.1.1",
     "lefthook": "^2.2.2"
   },
   "peerDependencies": {
@@ -74,6 +73,7 @@
     "fast-glob": "^3.3.3",
     "gray-matter": "^4.0.3",
     "js-yaml": "^5.4.3",
+    "json-schema-to-ts": "^3.1.1",
     "json5": "^2.2.3",
     "jsonata": "^2.2.1",
     "mdast-util-to-string": "^4.0.0",