structured-context 0.11.0 → 0.13.0

package/dist/testing.d.ts

@@ -0,0 +1,33 @@
+import type { BaseNode, Hierarchy, HierarchyLevel, Relationship, ResolvedParentRef, SpaceNode } from './types.js';
+/**
+ * Creates a ResolvedParentRef with sensible defaults for use in tests.
+ * Override any field to represent specific edge contexts.
+ */
+export declare const makeParentRef: (title: string, overrides?: Partial<ResolvedParentRef>) => ResolvedParentRef;
+/**
+ * Creates a HierarchyLevel with defaults matching schema metadata normalization.
+ */
+export declare const makeLevel: (type: string, overrides?: Partial<HierarchyLevel>) => HierarchyLevel;
+/**
+ * Creates a named Hierarchy (default name 'main') from normalized levels.
+ */
+export declare const makeHierarchy: (levels: HierarchyLevel[], overrides?: Partial<Hierarchy>) => Hierarchy;
+/**
+ * SchemaMetadata fields for a schema whose only hierarchy is its main hierarchy.
+ */
+export declare const withHierarchy: (levels: HierarchyLevel[], overrides?: Partial<Hierarchy>) => {
+    hierarchy: Hierarchy;
+    hierarchies: Hierarchy[];
+};
+/**
+ * Creates a Relationship with defaults matching schema metadata normalization.
+ */
+export declare const makeRelationship: (parent: string, type: string, overrides?: Partial<Relationship>) => Relationship;
+/**
+ * Creates a BaseNode with sensible defaults for use in tests.
+ */
+export declare const makeNode: (title: string, type: string, extra?: Record<string, unknown>, linkTargets?: string[]) => BaseNode;
+/**
+ * Creates a SpaceNode with sensible defaults for use in tests.
+ */
+export declare const makeSpaceNode: (title: string, type: string, extra?: Record<string, unknown>, linkTargets?: string[], resolvedParents?: ResolvedParentRef[], resolvedLinks?: SpaceNode["resolvedLinks"]) => SpaceNode;

package/dist/testing.js

@@ -0,0 +1,72 @@
+/**
+ * Creates a ResolvedParentRef with sensible defaults for use in tests.
+ * Override any field to represent specific edge contexts.
+ */
+export const makeParentRef = (title, overrides = {}) => {
+    const source = overrides.source ?? 'hierarchy';
+    return {
+        title,
+        field: 'parent',
+        source,
+        ...(source === 'hierarchy' ? { hierarchy: 'main' } : {}),
+        selfRef: false,
+        fieldOn: 'child',
+        ...overrides,
+    };
+};
+/**
+ * Creates a HierarchyLevel with defaults matching schema metadata normalization.
+ */
+export const makeLevel = (type, overrides = {}) => ({
+    type,
+    field: 'parent',
+    fieldOn: 'child',
+    multiple: false,
+    selfRef: false,
+    ...overrides,
+});
+/**
+ * Creates a named Hierarchy (default name 'main') from normalized levels.
+ */
+export const makeHierarchy = (levels, overrides = {}) => ({
+    name: 'main',
+    levels,
+    ...overrides,
+});
+/**
+ * SchemaMetadata fields for a schema whose only hierarchy is its main hierarchy.
+ */
+export const withHierarchy = (levels, overrides = {}) => {
+    const hierarchy = makeHierarchy(levels, overrides);
+    return { hierarchy, hierarchies: [hierarchy] };
+};
+/**
+ * Creates a Relationship with defaults matching schema metadata normalization.
+ */
+export const makeRelationship = (parent, type, overrides = {}) => ({
+    parent,
+    type,
+    field: 'parent',
+    fieldOn: 'child',
+    multiple: false,
+    ...overrides,
+});
+/**
+ * Creates a BaseNode with sensible defaults for use in tests.
+ */
+export const makeNode = (title, type, extra = {}, linkTargets) => ({
+    label: `${title}.md`,
+    title,
+    schemaData: { title, type, ...extra },
+    linkTargets: linkTargets ?? [title],
+    type,
+});
+/**
+ * Creates a SpaceNode with sensible defaults for use in tests.
+ */
+export const makeSpaceNode = (title, type, extra = {}, linkTargets, resolvedParents = [], resolvedLinks = []) => ({
+    ...makeNode(title, type, extra, linkTargets),
+    resolvedType: type,
+    resolvedParents,
+    resolvedLinks,
+});

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv';
-import type { Config, SpaceConfig } from './config';
-import type { MetadataContractHierarchyLevel, MetadataContractRelationship, Rule, SharedEdgeFields } from './schema/metadata-contract';
+import type { Config, SpaceConfig } from './config.js';
+import type { MetadataContractHierarchyLevel, MetadataContractRelationship, Rule, SharedEdgeFields } from './schema/metadata-contract.js';
 /**
  * Minimal normalized edge for graph resolution.
  * Derives routing fields from SharedEdgeFields to stay in sync with the schema.
@@ -40,11 +40,21 @@ export type ResolvedParentRef = {
     field: string;
     /** Whether this edge originates from a hierarchy level or a relationship definition. */
     source: 'hierarchy' | 'relationship';
+    /** Name of the hierarchy the edge belongs to. Set only when source is 'hierarchy'. */
+    hierarchy?: string;
     /** Whether the parent and child are the same node type (self-referential edge). */
     selfRef: boolean;
     /** Whether the edge field is on the child node (default) or on the parent node (fieldOn:'parent' edges). */
     fieldOn: 'child' | 'parent';
 };
+export type SourceLocation = {
+    /** File path relative to the space root. */
+    file: string;
+    /** 1-indexed starting line number in the source file, if available. */
+    line?: number;
+    /** 1-indexed starting column number in the source file, if available. */
+    column?: number;
+};
 export type UnresolvedRef = {
     /** Source identifier of the node containing the broken link. */
     label: string;
@@ -55,6 +65,8 @@ export type UnresolvedRef = {
     reason: 'not_found' | 'ambiguous' | 'invalid_shape';
     /** Human-readable message matching validate-graph output format. */
     message: string;
+    /** Source location of the node containing the broken link, if available. */
+    source?: SourceLocation;
 };
 /**
  * Shared fields for all content link variants.
@@ -107,11 +119,15 @@ export type BaseNode = {
     linkTargets: string[];
     /** Raw type string from content, as written by the user. */
     type: string;
+    /** Markdown source of the node's body, if any. First-class accessor mirroring schemaData.content. */
+    content?: string;
     /**
      * Links extracted from content body and non-edge string fields at parse time.
      * Populated by plugins that support content link extraction; absent if not populated.
      */
     contentLinks?: ContentLink[];
+    /** Source location of the node definition in the filesystem. */
+    source?: SourceLocation;
 };
 /**
  * A fully resolved node — enriched by core after plugin parsing.
@@ -143,15 +159,33 @@ export type ParseIssue = {
     type: 'no-type' | 'parse' | string;
     /** Human-readable detail. */
     message?: string;
+    /** 1-indexed line number in source file, if available. */
+    line?: number;
+    /** 1-indexed column number in source file, if available. */
+    column?: number;
 };
 /** Rule categories for organizing executable validation rules */
 export type RuleCategory = 'validation' | 'coherence' | 'workflow' | 'best-practice';
-export type { Rule } from './schema/metadata-contract';
+/**
+ * Rule violation severity. Only `error` fails validation; `warning` and `info` are reported only.
+ * A rule's severity defaults from its category and may be overridden per rule.
+ */
+export type RuleSeverity = 'error' | 'warning' | 'info';
+export type { CoverageGate, GatingSeed } from './schema/gating.js';
+export type { Rule } from './schema/metadata-contract.js';
 export type RuleViolation = {
+    /** Node label, or empty string for global-scope rules. */
     file: string;
     ruleId: string;
     category: RuleCategory;
+    severity: RuleSeverity;
     description: string;
+    /** Cited evidence or reasoning from evaluation (for semantic judge rules). */
+    evidence?: string;
+    /** The verdict that failed the rule (semantic rules). */
+    verdict?: string;
+    /** User-facing guidance declared for that verdict (semantic rules). */
+    guidance?: string;
 };
 export type GraphViolation = {
     file: string;
@@ -161,11 +195,18 @@ export type GraphViolation = {
     parentTitle: string;
     description: string;
 };
+/** A named hierarchy, normalized from a schema's `$metadata.hierarchy`. */
+export type Hierarchy = {
+    /** Declared short name, defaulting to the declaring schema's file stem. */
+    name: string;
+    levels: HierarchyLevel[];
+    allowSkipLevels?: boolean;
+};
 export type SchemaMetadata = {
-    hierarchy?: {
-        levels: HierarchyLevel[];
-        allowSkipLevels?: boolean;
-    };
+    /** Main hierarchy: used for space_on_a_page parsing, embedding, template-sync and default rendering. */
+    hierarchy?: Hierarchy;
+    /** Every hierarchy in the composed schema (main included), in composition order. Each type belongs to at most one. */
+    hierarchies?: Hierarchy[];
     typeAliases?: Record<string, string>;
     rules?: Rule[];
     relationships?: Relationship[];
@@ -201,21 +242,28 @@ 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 {
+    kind: string;
+    message: string;
+    /** Present for rule violations (`kind: 'rule'`). */
+    severity?: RuleSeverity;
+    /** 1-indexed line number in source file, if available. */
+    line?: number;
+    /** 1-indexed column number in source file, if available. */
+    column?: number;
+}
 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, {
-        kind: string;
-        message: string;
-    }>;
+    errors: Record<string, FileValidationIssue>;
     errorCount: number;
-    /** Warnings keyed by composite id. Do not affect exit code or errorCount. */
-    warnings: Record<string, {
-        kind: string;
-        message: string;
-    }>;
+    /**
+     * Warnings keyed by composite id, including `warning` and `info` severity rule violations.
+     * Do not affect exit code or errorCount.
+     */
+    warnings: Record<string, FileValidationIssue>;
     warningCount: number;
     inSpace: true;
 }

package/dist/validate.d.ts

@@ -1,7 +1,9 @@
 import type { ErrorObject } from 'ajv';
-import type { Config } from './config';
-import { extractEntityInfo } from './schema/schema';
-import type { GraphViolation, ParseIssue, ReadSpaceResult, RuleViolation, SchemaWithMetadata, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
+import type { Config, SpaceConfig } from './config.js';
+import type { SemanticJudgeProvider } from './judge/types.js';
+import { type RuleFilter } from './schema/rule-filter.js';
+import { extractEntityInfo } from './schema/schema.js';
+import type { CoverageGate, FileNotInSpaceResult, FileValidationResult, GraphViolation, ParseIssue, ReadSpaceResult, RuleViolation, SchemaWithMetadata, SpaceContext, SpaceNode, ValidateFileOutput } from './types.js';
 export interface FormattedError {
     message: string;
     dedupeKey: string;
@@ -11,11 +13,13 @@ export interface ValidationResult {
     nodeErrorCount: number;
     nodeErrors: Array<{
         file: string;
+        line?: number;
         errors: ErrorObject[];
         nodeData: Record<string, unknown>;
     }>;
     refErrors: Array<{
         file: string;
+        line?: number;
         parent: string;
         error: string;
     }>;
@@ -23,6 +27,7 @@ export interface ValidationResult {
         title: string;
         files: string[];
     }>;
+    /** All rule violations with their effective severity. Only `error` severity fails validation. */
     ruleViolations: RuleViolation[];
     hierarchyViolations: GraphViolation[];
     orphans: SpaceNode[];
@@ -32,19 +37,69 @@ export interface ValidationResult {
         file: string;
         target: string;
     }>;
+    /**
+     * Cascade gates: nodes whose schema/hierarchy failure or blocking rule violation
+     * suppressed rule evaluation for themselves and/or their hierarchy subtree.
+     * See docs/rules.md for gating semantics.
+     */
+    coverageGates: CoverageGate[];
+    /** Semantic rule input that had content trimmed to fit the per-node input cap: the node count and the rule ids. */
+    contextTrimmed: {
+        nodeCount: number;
+        ruleIds: string[];
+    };
+    /** Nodes excluded from validation entirely by a `depth` limit (breadth-first from hierarchy roots). */
+    skippedByDepth: Array<{
+        file: string;
+        title: string;
+    }>;
+    /** The depth limit applied, if any (undefined means the full space was validated). */
+    depthLimit?: number;
 }
 /**
  * Format AJV errors for better readability.
  * Groups related errors and extracts helpful context like allowed values.
  */
 export declare function formatErrors(errors: ErrorObject[], schema: SchemaWithMetadata, schemaRefRegistry: Parameters<typeof extractEntityInfo>[1], nodeData: Record<string, unknown>): FormattedError[];
+export interface ValidateSpaceOptions {
+    readResult?: ReadSpaceResult;
+    /** Limit validation to hierarchy nodes within N breadth-first levels from the top. */
+    depth?: number;
+    /** Evaluate rules on gated nodes anyway (gates are still reported). */
+    includeGated?: boolean;
+    /** Evaluate only rules matching this filter (see `parseRuleFilter`). */
+    ruleFilter?: RuleFilter;
+    /** Evaluates `semantic` rules. Without one, a rule runs only its `expression`, and a semantic-only rule is skipped. */
+    judge?: SemanticJudgeProvider;
+}
+/** One-line text for a rule violation: rule, description, and any evidence and verdict guidance. */
+export declare function ruleViolationMessage(v: RuleViolation): string;
 /**
  * Run full validation on a space and return a structured result.
  * Does not output to console or call process.exit.
  */
-export declare function validateSpace(context: SpaceContext, options?: {
-    readResult?: ReadSpaceResult;
-}): Promise<ValidationResult>;
+export declare function validateSpace(context: SpaceContext, options?: ValidateSpaceOptions): Promise<ValidationResult>;
+/** Find which space a file belongs to by checking directory containment. */
+export declare function resolveFileSpace(filePath: string, config: Config): {
+    space: SpaceConfig;
+    label: string;
+} | null;
+export interface ValidateFileOptions {
+    configDir?: string;
+    /** Evaluate rules on gated nodes anyway (gates are still reported). */
+    includeGated?: boolean;
+    /** Evaluate only rules matching this filter (see `parseRuleFilter`). */
+    ruleFilter?: RuleFilter;
+    /** Evaluates `semantic` rules. Without one, a rule runs only its `expression`, and a semantic-only rule is skipped. */
+    judge?: SemanticJudgeProvider;
+}
+/** The result for a file that belongs to no configured space. */
+export declare function fileNotInSpace(filePath: string): FileNotInSpaceResult;
+/**
+ * Validate a file in an already-resolved space. Checks the whole space (required for graph
+ * correctness), judging only the file, then selects the file's issues from the result.
+ */
+export declare function validateResolvedFile(filePath: string, label: string, context: SpaceContext, options?: Omit<ValidateFileOptions, 'configDir'>): Promise<FileValidationResult>;
 /**
  * Validate a single file within its space.
  *
@@ -54,6 +109,4 @@ export declare function validateSpace(context: SpaceContext, options?: {
  * Returns a result object — does not output to console or call process.exit.
  * If the file is not in any configured space, returns a result with `inSpace: false`.
  */
-export declare function validateFile(filePath: string, config: Config, options?: {
-    configDir?: string;
-}): Promise<ValidateFileOutput>;
+export declare function validateFile(filePath: string, config: Config, options?: ValidateFileOptions): Promise<ValidateFileOutput>;