structured-context 0.12.0 → 0.13.0

package/dist/schemas/generated/latest/_structured_context_schema_meta.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/0.12.0/_structured_context_schema_meta.json",
+  "$id": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/0.13.0/_structured_context_schema_meta.json",
   "title": "structured-context schema dialect",
   "description": "Extends JSON Schema 2020-12 with top-level $metadata for imports, hierarchy, relationships, aliases and rules.",
   "type": "object",
@@ -203,23 +203,194 @@
                 "type": "string",
                 "minLength": 1
               },
-              "check": {
+              "expression": {
                 "type": "string",
                 "minLength": 1
               },
+              "when": {
+                "type": "string",
+                "minLength": 1
+              },
+              "semantic": {
+                "oneOf": [
+                  {
+                    "const": true
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "rubric": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "verdicts": {
+                        "type": "object",
+                        "additionalProperties": {
+                          "oneOf": [
+                            {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            {
+                              "type": "object",
+                              "properties": {
+                                "description": {
+                                  "type": "string",
+                                  "minLength": 1
+                                },
+                                "guidance": {
+                                  "type": "string",
+                                  "minLength": 1
+                                }
+                              },
+                              "required": ["description"],
+                              "additionalProperties": false
+                            }
+                          ]
+                        },
+                        "minProperties": 2
+                      },
+                      "severity": {
+                        "type": "object",
+                        "additionalProperties": {
+                          "enum": ["error", "warning", "info", "ignore"]
+                        },
+                        "minProperties": 1
+                      },
+                      "scope": {
+                        "type": "array",
+                        "items": {
+                          "enum": ["parent", "siblings", "children", "ancestors", "descendants", "branch"]
+                        },
+                        "uniqueItems": true
+                      },
+                      "includeContent": {
+                        "enum": ["nodeOnly", "fullScope", true]
+                      }
+                    },
+                    "additionalProperties": false
+                  }
+                ]
+              },
               "type": {
                 "type": "string",
                 "minLength": 1
               },
-              "scope": {
-                "enum": ["global"]
+              "global": {
+                "type": "boolean"
               },
               "override": {
                 "type": "boolean"
+              },
+              "gatesDescendants": {
+                "type": "boolean"
               }
             },
-            "required": ["id", "category", "description", "check"],
-            "additionalProperties": false
+            "required": ["id", "category", "description"],
+            "additionalProperties": false,
+            "allOf": [
+              {
+                "anyOf": [
+                  {
+                    "required": ["expression"]
+                  },
+                  {
+                    "required": ["semantic"]
+                  }
+                ]
+              },
+              {
+                "if": {
+                  "required": ["global"],
+                  "properties": {
+                    "global": {
+                      "const": true
+                    }
+                  }
+                },
+                "then": {
+                  "not": {
+                    "anyOf": [
+                      {
+                        "required": ["when"]
+                      },
+                      {
+                        "required": ["type"]
+                      },
+                      {
+                        "required": ["semantic"]
+                      }
+                    ]
+                  }
+                }
+              },
+              {
+                "if": {
+                  "required": ["semantic"],
+                  "properties": {
+                    "semantic": {
+                      "type": "object",
+                      "required": ["verdicts"]
+                    }
+                  }
+                },
+                "then": {
+                  "properties": {
+                    "semantic": {
+                      "type": "object",
+                      "required": ["severity"]
+                    }
+                  }
+                }
+              },
+              {
+                "if": {
+                  "required": ["semantic"],
+                  "properties": {
+                    "semantic": {
+                      "type": "object",
+                      "not": {
+                        "required": ["verdicts"]
+                      }
+                    }
+                  }
+                },
+                "then": {
+                  "properties": {
+                    "semantic": {
+                      "type": "object",
+                      "properties": {
+                        "severity": {
+                          "type": "object",
+                          "not": {
+                            "required": ["fail"]
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "if": {
+                  "required": ["semantic"],
+                  "properties": {
+                    "semantic": {
+                      "type": "object",
+                      "required": ["verdicts"]
+                    }
+                  },
+                  "not": {
+                    "required": ["expression"]
+                  }
+                },
+                "then": {
+                  "not": {
+                    "required": ["severity"]
+                  }
+                }
+              }
+            ]
           }
         }
       },

package/dist/schemas/okf.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/latest/_structured_context_schema_meta.json",
+  "$id": "sctx://core/okf",
+  "title": "Open Knowledge Format",
+  "description": "Validates the frontmatter of Open Knowledge Format (OKF v0.2) concept documents in a bundle. Any `type` is accepted and unknown fields are tolerated; `Attested Computation` concepts additionally carry the computation contract.\n\nSpecification: https://github.com/GoogleCloudPlatform/open-knowledge-format",
+  "$metadata": { "imports": ["sctx://core/_okf"] },
+  "allOf": [{ "$ref": "sctx://core/_okf" }, { "$ref": "sctx://core/_okf#/$defs/concept" }]
+}

package/dist/space-context.d.ts

@@ -1,5 +1,5 @@
-import { type Config } from './config';
-import type { SpaceContext } from './types';
+import { type Config } from './config.js';
+import type { SpaceContext } from './types.js';
 /** Thrown by createSpaceContext when no space matches the given name. */
 export declare class SpaceNotFoundError extends Error {
     readonly spaceName: string;

package/dist/space-context.js

@@ -1,6 +1,6 @@
-import { resolveSchema } from './config';
-import { resolveSpacePluginSchemas } from './plugins/util';
-import { loadSchema } from './schema/schema';
+import { resolveSchema } from './config.js';
+import { resolveSpacePluginSchemas } from './plugins/util.js';
+import { loadSchema } from './schema/schema.js';
 /** Thrown by createSpaceContext when no space matches the given name. */
 export class SpaceNotFoundError extends Error {
     spaceName;

package/dist/space-graph.d.ts

@@ -1,4 +1,4 @@
-import type { Hierarchy, SpaceNode } from './types';
+import type { Hierarchy, SpaceNode } from './types.js';
 /**
  * A navigable graph over a set of SpaceNodes.
  *

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import type { BaseNode, Hierarchy, HierarchyLevel, Relationship, ResolvedParentRef, SpaceNode } from './types';
+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.

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.
@@ -119,7 +119,7 @@ export type BaseNode = {
     linkTargets: string[];
     /** Raw type string from content, as written by the user. */
     type: string;
-    /** Body content of the node, if any. First-class accessor mirroring schemaData.content. */
+    /** 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.
@@ -171,7 +171,8 @@ export type RuleCategory = 'validation' | 'coherence' | 'workflow' | 'best-pract
  * A rule's severity defaults from its category and may be overridden per rule.
  */
 export type RuleSeverity = 'error' | 'warning' | 'info';
-export type { Rule } from './schema/metadata-contract';
+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;
@@ -179,6 +180,12 @@ export type RuleViolation = {
     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;

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;
@@ -35,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.
  *
@@ -57,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>;