structured-context 0.22.0 → 0.23.0

package/README.md

@@ -70,7 +70,7 @@ bunx structured-context --help
 
 ## Setup for AI Agents
 
-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 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, opens a map of a space's hierarchy with each node's issues (`/sctx-map`), adds the session's schemas to the system prompt, and gives Claude sctx tools. Install it with:
 
 ```
 claude plugin marketplace add mindsocket/structured-context
@@ -264,11 +264,11 @@ bun link
 
 ### Releasing
 ```bash
-npm login             # authenticate with npm registry if needed
-bun pm version patch  # or minor / major — runs lint, tests, then pushes with tags
-npm publish
+bun pm version patch  # or minor / major — runs lint and tests, then pushes the commit and tag
 ```
 
+Pushing the `v<version>` tag runs the Release workflow (`.github/workflows/release.yml`). It reruns the checks and publishes to npm through trusted publishing, with provenance. It also attests the tarball and attaches it to a GitHub release.
+
 ## License
 
 MIT

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, FileValidationResult, Hierarchy, HierarchyLevel, ParseIssue, ReadSpaceResult, Relationship, ResolvedContentLink, RuleCategory, RuleSeverity, RuleViolation, SchemaMetadata, SchemaWithMetadata, SourceLocation, SpaceContext, UnresolvedRef, ValidateFileOutput, ValidationIssue, ValidationIssueKind, } from './types';
+export { VALIDATION_ISSUE_KINDS } from './types';
 export type { ValidationResult } from './validate';
-export { nodeIssues, validateFile, validateSpace } from './validate';
+export { 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 { nodeIssues, validateFile, validateSpace } from './validate';
+export { VALIDATION_ISSUE_KINDS } from './types';
+export { 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.issues).filter((i) => i.severity === 'error')) {
+        for (const issue of result.issues.filter((i) => i.severity === 'error')) {
             console.log(`  [${issueLabel(issue)}] ${issue.message}`);
         }
     }
@@ -51,7 +51,7 @@ function printHumanReadable(result) {
     }
     if (result.warningCount > 0) {
         console.log(`\n  ${yellow}${result.warningCount} warning(s):${reset}`);
-        for (const issue of Object.values(result.issues).filter((i) => i.severity !== 'error')) {
+        for (const issue of result.issues.filter((i) => i.severity !== 'error')) {
             console.log(`  ${yellow}[${issueLabel(issue)}]${reset} ${issue.message}`);
         }
     }

package/dist/commands/validate.d.ts

@@ -1,6 +1,30 @@
-import type { SpaceContext } from '../types';
-import { type ValidateSpaceOptions } from '../validate';
+import type { SpaceContext, ValidationIssue } from '../types';
+import { type ValidateSpaceOptions, type ValidationResult } from '../validate';
+/** What `validate --json` prints: the run's `ValidationResult` and a summary. The Claude Code plugin's scripts read it by this type. */
+export type ValidateJsonOutput = ReturnType<typeof validateJson>;
+declare function validateJson(context: SpaceContext, result: ValidationResult): {
+    issues: ValidationIssue[];
+    validCount: number;
+    orphans: Array<{
+        nodeId: import("../types").NodeId;
+        title: string;
+    }>;
+    coverageGates: import("../types").CoverageGate[];
+    contextTrimmed: {
+        nodeCount: number;
+        ruleIds: string[];
+    };
+    skippedByDepth: Array<{
+        nodeId: import("../types").NodeId;
+        title: string;
+    }>;
+    depthLimit?: number;
+    space: string;
+    valid: boolean;
+    errorCount: number;
+};
 export declare function validate(context: SpaceContext, options?: {
     json?: boolean;
 } & ValidateSpaceOptions): Promise<number>;
 export declare function watchValidate(context: SpaceContext): Promise<never>;
+export {};

package/dist/commands/validate.js

@@ -3,37 +3,21 @@ import chokidar from 'chokidar';
 import { getConfigSourceFiles } from '../config';
 import { resolveSpacePluginSchemas } from '../plugins/util';
 import { bundledSchemasDir } from '../schema/schema';
-import { formatSource, nodeIssues, validateSpace } from '../validate';
+import { formatSource, validateSpace } from '../validate';
+function validateJson(context, result) {
+    const errorCount = result.issues.filter((issue) => issue.severity === 'error').length;
+    return { space: context.space.name, valid: errorCount === 0, errorCount, ...result };
+}
+/** The issues of one kind, narrowed to that kind's fields */
+function ofKind(result, kind) {
+    return result.issues.filter((issue) => issue.kind === kind);
+}
 export async function validate(context, options = {}) {
     const result = await validateSpace(context, options);
-    const ruleCounts = { error: 0, warning: 0, info: 0 };
-    for (const v of result.ruleViolations)
-        ruleCounts[v.severity]++;
-    // JSON output mode
+    const errorCount = result.issues.filter((issue) => issue.severity === 'error').length;
     if (options.json) {
-        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;
-        const parseErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length;
-        const errorCount = nodeErrorCount + parseErrorCount + globalRuleErrorCount;
-        console.log(JSON.stringify({
-            space: context.space.name,
-            valid: errorCount === 0,
-            validCount: result.validCount,
-            errorCount,
-            issues,
-            ruleViolations: result.ruleViolations,
-            orphanCount: result.orphans.length,
-            parseIssues: result.parseIssues,
-            unresolvedContentLinks: result.unresolvedContentLinks,
-            coverageGates: result.coverageGates,
-            contextTrimmed: result.contextTrimmed,
-            skippedByDepth: result.skippedByDepth,
-            depthLimit: result.depthLimit,
-        }, null, 2));
-        return errorCount > 0 ? 1 : 0;
+        console.log(JSON.stringify(validateJson(context, result), null, 2));
+        return errorCount === 0 ? 0 : 1;
     }
     // Human-readable output
     const reset = '\x1b[0m';
@@ -56,63 +40,63 @@ export async function validate(context, options = {}) {
         const countStr = String(count).padStart(3);
         return `${label.padEnd(40)} ${color}${countStr}${reset}`;
     };
-    const parseIssueErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length;
+    const where = (issue) => (issue.source ? formatSource(issue.source) : (issue.nodeId ?? ''));
+    const parseIssues = ofKind(result, 'parse');
+    const schemaIssues = ofKind(result, 'schema');
+    const brokenLinks = ofKind(result, 'broken-link');
+    const duplicates = ofKind(result, 'duplicate');
+    const ruleViolations = ofKind(result, 'rule');
+    const hierarchyViolations = ofKind(result, 'hierarchy');
+    const contentLinks = ofKind(result, 'content-link');
+    const ruleCounts = { error: 0, warning: 0, info: 0 };
+    for (const v of ruleViolations)
+        ruleCounts[v.severity]++;
     if (result.orphans.length > 0) {
         console.log(`\nOrphans (hierarchy nodes - no parent):`);
-        for (const node of result.orphans)
-            console.log(`   ${node.id}`);
+        for (const { nodeId } of result.orphans)
+            console.log(`   ${nodeId}`);
     }
-    if (result.unresolvedContentLinks.length > 0) {
+    if (contentLinks.length > 0) {
         console.log(`\nUnresolved content links (may be outside-space or broken):`);
-        const byFile = new Map();
-        for (const { nodeId, target } of result.unresolvedContentLinks) {
-            if (!byFile.has(nodeId))
-                byFile.set(nodeId, []);
-            byFile.get(nodeId).push(target);
-        }
-        for (const [nodeId, targets] of byFile) {
+        const byNode = Map.groupBy(contentLinks, (link) => link.nodeId);
+        for (const [nodeId, links] of byNode) {
             console.log(`   ${nodeId}:`);
-            for (const target of targets)
+            for (const { target } of links)
                 console.log(`      ${target}`);
         }
     }
-    if (result.parseIssues.length > 0) {
+    if (parseIssues.length > 0) {
         console.log(`\nExcluded during parsing:`);
-        for (const issue of result.parseIssues) {
-            const loc = issue.line !== undefined ? `:${issue.line}${issue.column !== undefined ? `:${issue.column}` : ''}` : '';
-            const detail = issue.message ? ` - ${issue.message}` : '';
-            console.log(`   ${issue.file}${loc}: ${issue.severity} - ${issue.type}${detail}`);
+        for (const issue of parseIssues) {
+            console.log(`   ${formatSource(issue.source)}: ${issue.severity} - ${issue.type} - ${issue.message}`);
         }
     }
-    if (result.nodeErrors.length > 0) {
+    if (schemaIssues.length > 0) {
         console.log(`\nSchema validation errors:`);
-        result.nodeErrors.forEach(({ nodeId, source, issues }) => {
-            console.log(`\n   ${source ? formatSource(source) : nodeId}:`);
-            issues.forEach(({ message }) => {
+        for (const [, issues] of Map.groupBy(schemaIssues, (issue) => issue.nodeId)) {
+            console.log(`\n   ${where(issues[0])}:`);
+            for (const { message } of issues)
                 console.log(`      ${message}`);
-            });
-        });
+        }
     }
-    if (result.refErrors.length > 0) {
+    if (brokenLinks.length > 0) {
         console.log(`\nBroken links:`);
-        result.refErrors.forEach(({ nodeId, source, parent, error }) => {
-            console.log(`   ${source ? formatSource(source) : nodeId}: ${parent} → ${error}`);
-        });
+        for (const issue of brokenLinks)
+            console.log(`   ${where(issue)}: ${issue.message}`);
     }
-    if (result.duplicateErrors.length > 0) {
+    if (duplicates.length > 0) {
         console.log(`\nDuplicate ids (same id on multiple nodes):`);
-        result.duplicateErrors.forEach(({ id, sources }) => {
-            console.log(`   "${id}":`);
-            for (const source of sources) {
+        for (const { nodeId, sources } of duplicates) {
+            console.log(`   "${nodeId}":`);
+            for (const source of sources)
                 console.log(`      ${formatSource(source)}`);
-            }
-        });
+        }
     }
-    if (result.ruleViolations.length > 0) {
+    if (ruleViolations.length > 0) {
         console.log(`\nRule violations:`);
         const severityColor = { error: red, warning: yellow, info: reset };
         for (const severity of ['error', 'warning', 'info']) {
-            const violations = result.ruleViolations.filter((v) => v.severity === severity);
+            const violations = ruleViolations.filter((v) => v.severity === severity);
             if (violations.length === 0)
                 continue;
             console.log(`  ${severityColor[severity]}${severity.toUpperCase()}${reset} (${violations.length}):`);
@@ -127,10 +111,10 @@ export async function validate(context, options = {}) {
             }
         }
     }
-    if (result.hierarchyViolations.length > 0) {
+    if (hierarchyViolations.length > 0) {
         console.log(`\nHierarchy violations:`);
-        for (const v of result.hierarchyViolations) {
-            console.log(`   ${v.nodeId}: ${v.description}`);
+        for (const v of hierarchyViolations) {
+            console.log(`   ${v.nodeId}: ${v.message}`);
         }
     }
     if (result.coverageGates.length > 0) {
@@ -155,31 +139,24 @@ export async function validate(context, options = {}) {
     console.log(`━`.repeat(45));
     console.log('Content and structure');
     console.log(fmt('  Valid', result.validCount));
-    console.log(fmt('  Schema validation errors', result.nodeErrorCount, true));
-    console.log(fmt('  Broken links', result.refErrors.length, true));
-    console.log(fmt('  Duplicate ids', result.duplicateErrors.length, true));
+    console.log(fmt('  Schema validation errors', new Set(schemaIssues.map((issue) => issue.nodeId)).size, true));
+    console.log(fmt('  Broken links', brokenLinks.length, true));
+    console.log(fmt('  Duplicate ids', duplicates.length, true));
     console.log(fmt('  Rule violations (error)', ruleCounts.error, true));
     console.log(fmt('  Rule violations (warning)', ruleCounts.warning, true, true));
     console.log(fmt('  Rule violations (info)', ruleCounts.info, true, true));
-    console.log(fmt('  Hierarchy violations', result.hierarchyViolations.length, true));
+    console.log(fmt('  Hierarchy violations', hierarchyViolations.length, true));
     console.log(fmt('  Orphans (hierarchy nodes - no parent)', result.orphans.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));
+    console.log(fmt('  Unresolved content links (info)', contentLinks.length, true, true));
+    const parseErrors = parseIssues.filter((issue) => issue.severity === 'error').length;
+    console.log(fmt('  Excluded during parsing', parseIssues.length, true, parseErrors === 0));
     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.gatedNodeIds.length, 0);
     console.log(fmt('  Rule checks gated (cascade)', gatedFileCount, true, true));
     console.log(`\n`);
-    if (result.nodeErrorCount > 0 ||
-        result.refErrors.length > 0 ||
-        result.duplicateErrors.length > 0 ||
-        ruleCounts.error > 0 ||
-        result.hierarchyViolations.length > 0 ||
-        parseIssueErrorCount > 0) {
-        return 1;
-    }
-    return 0;
+    return errorCount === 0 ? 0 : 1;
 }
 export async function watchValidate(context) {
     const spacePath = context.space.path;

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv';
 import type { Config, SpaceConfig } from './config';
+import type { CoverageGate } from './schema/gating';
 import type { MetadataContractHierarchyLevel, MetadataContractRelationship, Rule, SharedEdgeFields } from './schema/metadata-contract';
 /**
  * Minimal normalized edge for graph resolution.
@@ -247,23 +248,68 @@ export type SpaceContext = {
     /** Directory of the config file that defines this space. Used for resolving relative paths in plugin configs. */
     configDir: string;
 };
-export interface FileValidationIssue {
-    /** The check it came from: `schema`, `duplicate`, `broken-link`, `hierarchy`, `rule`, `gated` or `content-link`. */
-    kind: string;
-    message: string;
-    /** How serious the issue is; consumers read it rather than infer it from `kind`. */
+/** The checks a validation issue can come from. */
+export declare const VALIDATION_ISSUE_KINDS: readonly ["parse", "schema", "duplicate", "broken-link", "hierarchy", "rule", "gated", "content-link"];
+export type ValidationIssueKind = (typeof VALIDATION_ISSUE_KINDS)[number];
+/** What every validation issue has, whatever its kind. */
+type IssueBase<K extends ValidationIssueKind> = {
+    /** The check it came from. */
+    kind: K;
+    /** Names the issue within its node (or file, or space), stably across runs, e.g. `rule:<ruleId>`. */
+    key: string;
+    /** How serious the issue is; only `error` fails validation. 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. */
-    column?: number;
-}
+    message: string;
+    /** The node the issue is about. Absent for parse issues and global rules. */
+    nodeId?: NodeId;
+    /** The node's source, or the file a parse issue is about. */
+    source?: SourceLocation;
+};
+/** One finding of a validation run. `kind` also selects the fields the issue carries. */
+export type ValidationIssue = 
+/** A file that produced no nodes; `type` is the plugin's reason, such as `no-type` or `parse`. */
+(IssueBase<'parse'> & {
+    source: SourceLocation;
+    type: ParseIssue['type'];
+})
+/** A node that failed its type or its schema, one issue per field problem. */
+ | (IssueBase<'schema'> & {
+    nodeId: NodeId;
+})
+/** An id used by more than one node; `sources` lists where each is defined. */
+ | (IssueBase<'duplicate'> & {
+    nodeId: NodeId;
+    sources: SourceLocation[];
+})
+/** A link in a field that does not resolve to a node; `ref` is the link as written. */
+ | (IssueBase<'broken-link'> & {
+    nodeId: NodeId;
+    ref: string;
+    reason: string;
+})
+/** A parent link that breaks the hierarchy. */
+ | (IssueBase<'hierarchy'> & Omit<GraphViolation, 'description'>)
+/** A rule violation; `nodeId` is absent for a global rule. */
+ | (IssueBase<'rule'> & RuleViolation)
+/** A node whose rules a coverage gate suppressed (or, with `includeGated`, evaluated anyway). */
+ | (IssueBase<'gated'> & {
+    nodeId: NodeId;
+    /** The node whose failure gated this one. */
+    gatedBy: NodeId;
+    reason: CoverageGate['reason'];
+    ruleId?: string;
+})
+/** A content link to a target outside the space's nodes. */
+ | (IssueBase<'content-link'> & {
+    nodeId: NodeId;
+    target: string;
+});
 export interface FileValidationResult {
     file: string;
     label: string;
     space: string;
-    /** 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>;
+    /** The file's node's issues of every severity. */
+    issues: ValidationIssue[];
     /** Issues at `error` severity: only these fail validation. */
     errorCount: number;
     /** Issues at `warning` or `info` severity. */

package/dist/types.js

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

package/dist/validate.d.ts

@@ -3,41 +3,20 @@ 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, FileValidationIssue, FileValidationResult, GraphViolation, NodeId, ParseIssue, ReadSpaceResult, RuleViolation, SchemaWithMetadata, SourceLocation, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
+import type { CoverageGate, FileNotInSpaceResult, FileValidationResult, GraphViolation, NodeId, ParseIssue, ReadSpaceResult, RuleViolation, SchemaWithMetadata, SourceLocation, SpaceContext, SpaceNode, ValidateFileOutput, ValidationIssue } from './types';
 export interface FormattedError {
     message: string;
     dedupeKey: string;
 }
 export interface ValidationResult {
+    /** Every issue the run found, of every severity. Only `error` issues fail validation. */
+    issues: ValidationIssue[];
+    /** Nodes that passed their type and schema checks. */
     validCount: number;
-    nodeErrorCount: number;
-    nodeErrors: Array<{
+    /** Hierarchy nodes without a parent: informational, not issues. */
+    orphans: Array<{
         nodeId: NodeId;
-        source?: SourceLocation;
-        /** Formatted, deduplicated schema problems for the node, one per field problem. */
-        issues: FormattedError[];
-    }>;
-    refErrors: Array<{
-        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;
-        sources: SourceLocation[];
-    }>;
-    /** All rule violations with their effective severity. Only `error` severity fails validation. */
-    ruleViolations: RuleViolation[];
-    hierarchyViolations: GraphViolation[];
-    orphans: SpaceNode[];
-    parseIssues: ParseIssue[];
-    /** 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';
+        title: string;
     }>;
     /**
      * Cascade gates: nodes whose schema/hierarchy failure or blocking rule violation
@@ -100,20 +79,34 @@ interface NodeValidationFailure {
 export interface SpaceValidationResult {
     validCount: number;
     nodeFailures: NodeValidationFailure[];
-    refErrors: ValidationResult['refErrors'];
-    duplicateErrors: ValidationResult['duplicateErrors'];
+    refErrors: Array<{
+        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: DuplicateId[];
     ruleViolations: RuleViolation[];
     hierarchyViolations: GraphViolation[];
     orphans: SpaceNode[];
-    unresolvedContentLinks: ValidationResult['unresolvedContentLinks'];
+    /** Content links that could not be resolved to a space node. */
+    unresolvedContentLinks: Array<{
+        nodeId: NodeId;
+        target: string;
+    }>;
     coverageGates: CoverageGate[];
     contextTrimmed: ValidationResult['contextTrimmed'];
 }
+type DuplicateId = {
+    id: NodeId;
+    sources: SourceLocation[];
+};
 /**
  * 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'];
+export declare function findDuplicateIds(nodes: SpaceNode[]): DuplicateId[];
 /**
  * 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`
@@ -134,17 +127,13 @@ 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.
+ * The run's findings as issues, each with its severity. This is the one place severity is decided for
+ * the checks that have no severity of their own. An issue repeated within its node (or file) is kept once.
  */
-export declare function nodeIssues(result: NodeIssueSources, options?: {
+export declare function issuesOf(result: SpaceValidationResult, parseIssues: ParseIssue[], options: {
     includeGated?: boolean;
-}): Record<string, Record<string, FileValidationIssue>>;
+}): ValidationIssue[];
 /** The result for a file that belongs to no configured space. */
 export declare function fileNotInSpace(filePath: string): FileNotInSpaceResult;
 /**

package/dist/validate.js

@@ -259,7 +259,7 @@ export async function validateNodes(context, nodes, read, options = {}) {
                 const key = `${node.id}::${link.target}`;
                 if (!seen.has(key)) {
                     seen.add(key);
-                    result.unresolvedContentLinks.push({ nodeId: node.id, target: link.target, severity: 'info' });
+                    result.unresolvedContentLinks.push({ nodeId: node.id, target: link.target });
                 }
             }
         }
@@ -295,16 +295,9 @@ export async function validateSpace(context, options = {}) {
     }
     const result = await validateNodes(context, nodes, readResult, runOptions);
     return {
+        issues: issuesOf(result, readResult.parseIssues, runOptions),
         validCount: result.validCount,
-        nodeErrorCount: result.nodeFailures.length,
-        nodeErrors: toNodeErrors(result.nodeFailures),
-        refErrors: result.refErrors,
-        duplicateErrors: result.duplicateErrors,
-        ruleViolations: result.ruleViolations,
-        hierarchyViolations: result.hierarchyViolations,
-        orphans: result.orphans,
-        parseIssues: readResult.parseIssues,
-        unresolvedContentLinks: result.unresolvedContentLinks,
+        orphans: result.orphans.map((node) => ({ nodeId: node.id, title: node.title })),
         coverageGates: result.coverageGates,
         contextTrimmed: result.contextTrimmed,
         skippedByDepth,
@@ -325,67 +318,96 @@ export function resolveFileSpace(filePath, config) {
     return null;
 }
 /**
- * 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.
+ * The run's findings as issues, each with its severity. This is the one place severity is decided for
+ * the checks that have no severity of their own. An issue repeated within its node (or file) is kept once.
  */
-export function nodeIssues(result, options = {}) {
-    const byNode = {};
-    const add = (nodeId, key, issue) => {
-        byNode[nodeId] ??= {};
-        byNode[nodeId][key] = issue;
+export function issuesOf(result, parseIssues, options) {
+    const issues = new Map();
+    const add = (issue) => {
+        const scope = issue.nodeId ?? (issue.kind === 'parse' ? issue.source.file : '');
+        issues.set(`${scope}\0${issue.key}`, issue);
     };
-    for (const { nodeId, source, issues } of result.nodeErrors) {
-        const position = {
-            ...(source?.line !== undefined ? { line: source.line } : {}),
-            ...(source?.column !== undefined ? { column: source.column } : {}),
-        };
-        for (const { message, dedupeKey } of issues) {
-            add(nodeId, `schema:${dedupeKey}`, { kind: 'schema', message, severity: 'error', ...position });
+    const at = (source) => (source ? { source } : {});
+    for (const { file, severity, type, message, line, column } of parseIssues) {
+        add({
+            kind: 'parse',
+            key: `parse:${type}`,
+            severity,
+            message: message ?? (type === 'no-type' ? 'No type field' : `Excluded during parsing (${type})`),
+            source: { file, ...(line !== undefined && { line }), ...(column !== undefined && { column }) },
+            type,
+        });
+    }
+    for (const { node, issues: problems } of result.nodeFailures) {
+        for (const { message, dedupeKey } of problems) {
+            add({
+                kind: 'schema',
+                key: `schema:${dedupeKey}`,
+                severity: 'error',
+                message,
+                nodeId: node.id,
+                ...at(node.source),
+            });
         }
     }
     for (const { id, sources } of result.duplicateErrors) {
         const where = sources.length > 0 ? `: ${sources.map(formatSource).join(', ')}` : '';
-        add(id, `duplicate:${id}`, {
+        add({
             kind: 'duplicate',
-            message: `Duplicate id "${id}" is used by ${sources.length} nodes${where}`,
+            key: `duplicate:${id}`,
             severity: 'error',
+            message: `Duplicate id "${id}" is used by ${sources.length} nodes${where}`,
+            nodeId: id,
+            sources,
         });
     }
-    for (const { nodeId, parent, error } of result.refErrors) {
-        add(nodeId, `broken-link:${parent}`, { kind: 'broken-link', message: `${parent} → ${error}`, severity: 'error' });
+    for (const { nodeId, source, parent, error } of result.refErrors) {
+        add({
+            kind: 'broken-link',
+            key: `broken-link:${parent}`,
+            severity: 'error',
+            message: `${parent} → ${error}`,
+            nodeId,
+            ...at(source),
+            ref: parent,
+            reason: error,
+        });
     }
-    for (const { nodeId, description } of result.hierarchyViolations) {
-        add(nodeId, `hierarchy:${description}`, { kind: 'hierarchy', message: description, severity: 'error' });
+    for (const { description, ...violation } of result.hierarchyViolations) {
+        add({ kind: 'hierarchy', key: `hierarchy:${description}`, severity: 'error', message: description, ...violation });
     }
     for (const v of result.ruleViolations) {
-        if (v.nodeId)
-            add(v.nodeId, `rule:${v.ruleId}`, { kind: 'rule', message: ruleViolationMessage(v), severity: v.severity });
+        add({ kind: 'rule', key: `rule:${v.ruleId}`, message: ruleViolationMessage(v), ...v });
     }
     // A gated node with no violations would otherwise look clean: say that its rules were not checked
     for (const gate of result.coverageGates) {
         const cause = gate.reason === 'rule' ? `blocking rule "${gate.ruleId}"` : `${gate.reason} failure`;
         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' });
+        for (const nodeId of gate.gatedNodeIds) {
+            add({
+                kind: 'gated',
+                key: `gated:${gate.nodeId}`,
+                severity: 'info',
+                message,
+                nodeId,
+                gatedBy: gate.nodeId,
+                reason: gate.reason,
+                ...(gate.ruleId !== undefined && { ruleId: gate.ruleId }),
+            });
+        }
     }
-    for (const { nodeId, target, severity } of result.unresolvedContentLinks) {
-        add(nodeId, `content-link:${target}`, {
+    for (const { nodeId, target } of result.unresolvedContentLinks) {
+        // Info: a target outside the space is often valid elsewhere
+        add({
             kind: 'content-link',
+            key: `content-link:${target}`,
+            severity: 'info',
             message: `Unresolved content link: ${target}`,
-            severity,
+            nodeId,
+            target,
         });
     }
-    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,
-    }));
+    return [...issues.values()];
 }
 /** The result for a file that belongs to no configured space. */
 export function fileNotInSpace(filePath) {
@@ -409,16 +431,15 @@ export async function validateResolvedFileWith(filePath, label, context, runOpti
         ...runOptions,
         judgeTarget: label,
     });
-    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;
+    const issues = issuesOf(result, [], runOptions).filter((issue) => issue.nodeId === label);
+    const errorCount = issues.filter((issue) => issue.severity === 'error').length;
     return {
         file: isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath),
         label,
         space: context.space.name,
         issues,
         errorCount,
-        warningCount: Object.keys(issues).length - errorCount,
+        warningCount: issues.length - errorCount,
         inSpace: true,
     };
 }

package/docs/concepts.md

@@ -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
 

package/docs/rules.md

@@ -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).
 

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "structured-context",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Keep your content clean and your thinking clear with assistive tools for structured knowledge",
   "module": "./dist/index.js",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mindsocket/structured-context.git"
+  },
   "bin": {
     "sctx": "dist/index.js"
   },
@@ -38,6 +42,7 @@
   "scripts": {
     "clean": "rm -rf dist",
     "generate:schema-meta": "bun run scripts/generate-schema-meta.ts",
+    "build:mod-projection": "bun run scripts/build-mod-projection.ts",
     "typecheck": "tsc --noEmit",
     "build": "bun run clean && bun run generate:schema-meta && tsc -p tsconfig.build.json && cp -r schemas dist/ && chmod +x dist/index.js",
     "prepublishOnly": "bun run build",
@@ -62,7 +67,10 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.310",
     "@biomejs/biome": "^2.5.15",
     "@types/bun": "^1.4.4",
-    "lefthook": "^2.2.2"
+    "dts-bundle-generator": "9.5.1",
+    "esbuild": "0.28.2",
+    "lefthook": "^2.2.2",
+    "structured-context-map-views": "^0.5.0"
   },
   "peerDependencies": {
     "typescript": "^5"