structured-context 0.11.0 → 0.13.0

package/dist/schema/metadata-contract.js

@@ -1,4 +1,13 @@
-export const SCHEMA_META_ID = 'https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json';
+/** The JSON Schema dialect the structured-context dialect extends. */
+export const JSON_SCHEMA_DIALECT = 'https://json-schema.org/draft/2020-12/schema';
+export const SCHEMA_META_BASE_URL = 'https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated';
+export const SCHEMA_META_FILE = '_structured_context_schema_meta.json';
+/** Meta-schema `$id` for a dialect version folder, e.g. `.../generated/0.12.0/_structured_context_schema_meta.json`. */
+export function schemaMetaId(folder) {
+    return `${SCHEMA_META_BASE_URL}/${folder}/${SCHEMA_META_FILE}`;
+}
+/** The URL schemas set as `$schema` to follow the newest dialect. Resolves to the newest versioned meta-schema. */
+export const SCHEMA_META_ID = schemaMetaId('latest');
 /** Graph edge routing fields shared by hierarchy levels and relationships. */
 const EDGE_PROPS = {
     field: { type: 'string', minLength: 1 },
@@ -34,21 +43,128 @@ const HIERARCHY_LEVEL_SCHEMA = {
     required: ['type'],
     additionalProperties: false,
 };
+const SEVERITY_SCHEMA = { enum: ['error', 'warning', 'info'] };
+/** The verdicts the evaluation reserves besides a rule's own; a verdict map may set a severity for them. */
+export const RESERVED_VERDICTS = ['missing-context'];
+/** Related-node kinds a semantic rule's `scope` can add: main-hierarchy edges only. `branch` is ancestors plus descendants. */
+export const SEMANTIC_SCOPES = ['parent', 'siblings', 'children', 'ancestors', 'descendants', 'branch'];
+const VERDICT_SEVERITY_SCHEMA = { enum: ['error', 'warning', 'info', 'ignore'] };
+/** The semantic part of a rule: a model evaluates the node against a rubric and returns a verdict. */
+const SEMANTIC_SCHEMA = {
+    type: 'object',
+    properties: {
+        /** What the model judges the node against. Falls back to the rule's `description`. */
+        rubric: { type: 'string', minLength: 1 },
+        /**
+         * The closed set of verdicts the model may return. Each is a description (what the verdict means, for the
+         * model) or `{ description, guidance }`, where `guidance` is shown to the user when it fires.
+         * Defaults to `pass`/`fail`.
+         */
+        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 per verdict in effect (declared, default or reserved). A verdict mapped to `ignore` is judged but
+         * not reported, and a verdict left out passes. Required with `verdicts`; with the default verdicts, `fail`
+         * takes the rule's own `severity` instead.
+         */
+        severity: {
+            type: 'object',
+            additionalProperties: VERDICT_SEVERITY_SCHEMA,
+            minProperties: 1,
+        },
+        /**
+         * Related nodes, along main-hierarchy edges, sent with the evaluated node. Additive; left out or empty means
+         * the evaluated node alone.
+         */
+        scope: {
+            type: 'array',
+            items: { enum: SEMANTIC_SCOPES },
+            uniqueItems: true,
+        },
+        /**
+         * Which node bodies are sent: `nodeOnly` (the evaluated node's), `fullScope` (it and every related node's),
+         * or `true` for `fullScope`. Left out: no bodies.
+         */
+        includeContent: { enum: ['nodeOnly', 'fullScope', true] },
+    },
+    additionalProperties: false,
+};
 const RULE_SCHEMA = {
     type: 'object',
     properties: {
         id: { type: 'string', minLength: 1 },
         category: { enum: ['validation', 'coherence', 'workflow', 'best-practice'] },
+        /**
+         * Severity of a failed `expression` and of the default `fail` verdict. Defaults from the category.
+         */
+        severity: SEVERITY_SCHEMA,
         description: { type: 'string', minLength: 1 },
-        check: { type: 'string', minLength: 1 },
+        /** JSONata test a node must pass. When the rule also has `semantic`, a failing node is reported without being evaluated by the model. */
+        expression: { type: 'string', minLength: 1 },
+        /** Optional JSONata applicability condition, evaluated per node before the rule runs. The rule applies only when it returns true. */
+        when: { type: 'string', minLength: 1 },
+        /** A model evaluates the node against a rubric. `{}` takes every default; `true` means the same. */
+        semantic: { oneOf: [{ const: true }, SEMANTIC_SCHEMA] },
         type: { type: 'string', minLength: 1 },
-        scope: { enum: ['global'] },
+        /** Run once for the whole space instead of once per node. */
+        global: { type: 'boolean' },
         override: { type: 'boolean' },
+        /** Whether a failure of this rule gates (suppresses) downstream rules on the node's hierarchy subtree. Defaults to true when the failure's severity is `error`. */
+        gatesDescendants: { type: 'boolean' },
     },
-    required: ['id', 'category', 'description', 'check'],
+    required: ['id', 'category', 'description'],
     additionalProperties: false,
+    allOf: [
+        // A rule has an expression, a semantic part, or both.
+        { anyOf: [{ required: ['expression'] }, { required: ['semantic'] }] },
+        // A global rule has no node to apply to or to evaluate.
+        {
+            if: { required: ['global'], properties: { global: { const: true } } },
+            // biome-ignore lint/suspicious/noThenProperty: JSON Schema `if`/`then` keyword, not a thenable
+            then: { not: { anyOf: [{ required: ['when'] }, { required: ['type'] }, { required: ['semantic'] }] } },
+        },
+        // Custom verdicts need a severity for each failing verdict.
+        {
+            if: { required: ['semantic'], properties: { semantic: { type: 'object', required: ['verdicts'] } } },
+            // biome-ignore lint/suspicious/noThenProperty: JSON Schema `if`/`then` keyword, not a thenable
+            then: { properties: { semantic: { type: 'object', required: ['severity'] } } },
+        },
+        // With the default verdicts, `fail` takes the rule's severity.
+        {
+            if: { required: ['semantic'], properties: { semantic: { type: 'object', not: { required: ['verdicts'] } } } },
+            // biome-ignore lint/suspicious/noThenProperty: JSON Schema `if`/`then` keyword, not a thenable
+            then: {
+                properties: {
+                    semantic: { type: 'object', properties: { severity: { type: 'object', not: { required: ['fail'] } } } },
+                },
+            },
+        },
+        // A rule with custom verdicts and no expression has no failure for the top-level severity to describe.
+        {
+            if: {
+                required: ['semantic'],
+                properties: { semantic: { type: 'object', required: ['verdicts'] } },
+                not: { required: ['expression'] },
+            },
+            // biome-ignore lint/suspicious/noThenProperty: JSON Schema `if`/`then` keyword, not a thenable
+            then: { not: { required: ['severity'] } },
+        },
+    ],
 };
-const RULE_REF_SCHEMA = {
+const REF_SCHEMA = {
     type: 'object',
     properties: {
         $ref: { type: 'string', minLength: 1 },
@@ -56,6 +172,23 @@ const RULE_REF_SCHEMA = {
     required: ['$ref'],
     additionalProperties: false,
 };
+const HIERARCHY_SCHEMA = {
+    type: 'object',
+    properties: {
+        name: { type: 'string', minLength: 1 },
+        override: { type: 'boolean' },
+        levels: {
+            type: 'array',
+            minItems: 1,
+            items: {
+                oneOf: [{ type: 'string', minLength: 1 }, HIERARCHY_LEVEL_SCHEMA],
+            },
+        },
+        allowSkipLevels: { type: 'boolean' },
+    },
+    required: ['levels'],
+    additionalProperties: false,
+};
 const RELATIONSHIP_SCHEMA = {
     type: 'object',
     properties: {
@@ -63,53 +196,64 @@ const RELATIONSHIP_SCHEMA = {
         type: { type: 'string', minLength: 1 },
         ...EDGE_PROPS,
         ...EMBEDDING_PROPS,
+        override: { type: 'boolean' },
     },
     required: ['parent', 'type'],
     additionalProperties: false,
 };
-export const METADATA_SCHEMA = {
-    type: 'object',
-    properties: {
-        hierarchy: {
+/** An alias target: a type name, or `{ type, override: true }` to replace an imported alias. */
+const ALIAS_SCHEMA = {
+    oneOf: [
+        { type: 'string', minLength: 1 },
+        {
             type: 'object',
             properties: {
-                levels: {
-                    type: 'array',
-                    minItems: 1,
-                    items: {
-                        oneOf: [{ type: 'string', minLength: 1 }, HIERARCHY_LEVEL_SCHEMA],
-                    },
-                },
-                allowSkipLevels: { type: 'boolean' },
+                type: { type: 'string', minLength: 1 },
+                override: { type: 'boolean' },
             },
-            required: ['levels'],
+            required: ['type'],
             additionalProperties: false,
         },
+    ],
+};
+export const METADATA_SCHEMA = {
+    type: 'object',
+    properties: {
+        // $ids of schemas whose metadata (and their imports' metadata) is merged into this schema's.
+        imports: {
+            type: 'array',
+            items: { type: 'string', minLength: 1 },
+        },
+        // Either declares this schema's hierarchy, or (root schema only) selects an imported one via $ref.
+        hierarchy: {
+            oneOf: [HIERARCHY_SCHEMA, REF_SCHEMA],
+        },
         relationships: {
             type: 'array',
             items: RELATIONSHIP_SCHEMA,
         },
         aliases: {
             type: 'object',
-            additionalProperties: { type: 'string', minLength: 1 },
+            additionalProperties: ALIAS_SCHEMA,
         },
         rules: {
             type: 'array',
-            items: {
-                oneOf: [RULE_SCHEMA, RULE_REF_SCHEMA],
-            },
+            items: RULE_SCHEMA,
         },
     },
     additionalProperties: false,
 };
-export const DIALECT_META_SCHEMA = {
-    $schema: 'http://json-schema.org/draft-07/schema#',
-    $id: SCHEMA_META_ID,
-    title: 'structured-context schema dialect',
-    description: 'Extends JSON Schema Draft-07 with top-level $metadata for hierarchy and rule metadata.',
-    type: 'object',
-    allOf: [{ $ref: 'http://json-schema.org/draft-07/schema#' }],
-    properties: {
-        $metadata: METADATA_SCHEMA,
-    },
-};
+/** The dialect meta-schema, published under `$id`. */
+export function buildDialectMetaSchema(id) {
+    return {
+        $schema: JSON_SCHEMA_DIALECT,
+        $id: id,
+        title: 'structured-context schema dialect',
+        description: 'Extends JSON Schema 2020-12 with top-level $metadata for imports, hierarchy, relationships, aliases and rules.',
+        type: 'object',
+        allOf: [{ $ref: JSON_SCHEMA_DIALECT }],
+        properties: {
+            $metadata: METADATA_SCHEMA,
+        },
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { Rule } from '../types';
+export declare const RULE_FILTER_DIMENSIONS: readonly ["category", "severity", "type", "id"];
+export type RuleFilterDimension = (typeof RULE_FILTER_DIMENSIONS)[number];
+/** Narrows which rules are evaluated. Dimensions combine with AND; values within a dimension with OR. */
+export type RuleFilter = Partial<Record<RuleFilterDimension, string[]>>;
+/** Parse `dimension=value[,value]` specs (e.g. from repeated `--rule-filter` flags); repeats of a dimension merge. */
+export declare function parseRuleFilter(specs: string[]): RuleFilter;
+/**
+ * Keep the rules matching every dimension of the filter. A rule with no `type` never matches a `type` filter,
+ * and a rule with a verdict map matches a `severity` filter on any severity it can report.
+ */
+export declare function filterRules(rules: Rule[], filter?: RuleFilter): Rule[];

package/dist/schema/rule-filter.js

@@ -0,0 +1,46 @@
+import { ruleSeverities } from './rule-severity';
+export const RULE_FILTER_DIMENSIONS = ['category', 'severity', 'type', 'id'];
+/** Parse `dimension=value[,value]` specs (e.g. from repeated `--rule-filter` flags); repeats of a dimension merge. */
+export function parseRuleFilter(specs) {
+    const filter = {};
+    for (const spec of specs) {
+        const eq = spec.indexOf('=');
+        const dimension = spec.slice(0, eq);
+        const values = spec
+            .slice(eq + 1)
+            .split(',')
+            .map((v) => v.trim())
+            .filter(Boolean);
+        if (eq < 0 || values.length === 0 || !RULE_FILTER_DIMENSIONS.includes(dimension)) {
+            throw new Error(`Invalid rule filter "${spec}". Use <${RULE_FILTER_DIMENSIONS.join('|')}>=<value>[,<value>...].`);
+        }
+        filter[dimension] = [...(filter[dimension] ?? []), ...values];
+    }
+    return filter;
+}
+function dimensionValues(rule, dimension) {
+    switch (dimension) {
+        case 'severity':
+            return ruleSeverities(rule);
+        case 'category':
+            return [rule.category];
+        case 'type':
+            return rule.type ? [rule.type] : [];
+        case 'id':
+            return [rule.id];
+    }
+}
+/**
+ * Keep the rules matching every dimension of the filter. A rule with no `type` never matches a `type` filter,
+ * and a rule with a verdict map matches a `severity` filter on any severity it can report.
+ */
+export function filterRules(rules, filter) {
+    if (!filter)
+        return rules;
+    return rules.filter((rule) => RULE_FILTER_DIMENSIONS.every((dim) => {
+        const wanted = filter[dim];
+        if (!wanted)
+            return true;
+        return dimensionValues(rule, dim).some((value) => wanted.includes(value));
+    }));
+}

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

@@ -0,0 +1,13 @@
+import type { Rule, RuleCategory, RuleSeverity } from '../types';
+import type { RuleSemantic } from './metadata-contract';
+/** Default severity for each rule category. A rule's own `severity` field overrides this. */
+export declare const DEFAULT_SEVERITY_BY_CATEGORY: Record<RuleCategory, RuleSeverity>;
+/** The rule's semantic part as an object (`semantic: true` means `{}`), or undefined for a rule without one. */
+export declare function ruleSemantic(rule: Rule): RuleSemantic | undefined;
+/** Severity of a failed `expression` and of the default `fail` verdict: the rule's `severity`, else its category default. */
+export declare function ruleSeverity(rule: Rule): RuleSeverity;
+/**
+ * Every severity this rule can report: that of its failed `expression` (or default `fail` verdict), plus those
+ * its semantic verdict map sets. `ignore` entries report nothing. Most severe first.
+ */
+export declare function ruleSeverities(rule: Rule): RuleSeverity[];

package/dist/schema/rule-severity.js

@@ -0,0 +1,33 @@
+/** Default severity for each rule category. A rule's own `severity` field overrides this. */
+export const DEFAULT_SEVERITY_BY_CATEGORY = {
+    validation: 'error',
+    coherence: 'warning',
+    workflow: 'warning',
+    'best-practice': 'info',
+};
+const SEVERITY_ORDER = ['error', 'warning', 'info'];
+/** The rule's semantic part as an object (`semantic: true` means `{}`), or undefined for a rule without one. */
+export function ruleSemantic(rule) {
+    if (rule.semantic === undefined)
+        return undefined;
+    return rule.semantic === true ? {} : rule.semantic;
+}
+/** Severity of a failed `expression` and of the default `fail` verdict: the rule's `severity`, else its category default. */
+export function ruleSeverity(rule) {
+    return rule.severity ?? DEFAULT_SEVERITY_BY_CATEGORY[rule.category];
+}
+/**
+ * Every severity this rule can report: that of its failed `expression` (or default `fail` verdict), plus those
+ * its semantic verdict map sets. `ignore` entries report nothing. Most severe first.
+ */
+export function ruleSeverities(rule) {
+    const semantic = ruleSemantic(rule);
+    const found = new Set();
+    if (rule.expression !== undefined || (semantic && !semantic.verdicts))
+        found.add(ruleSeverity(rule));
+    for (const severity of Object.values(semantic?.severity ?? {})) {
+        if (severity !== 'ignore')
+            found.add(severity);
+    }
+    return SEVERITY_ORDER.filter((s) => found.has(s));
+}

package/dist/schema/schema.d.ts

@@ -1,17 +1,23 @@
-import { type AnySchemaObject, type ValidateFunction } from 'ajv';
+import type { AnySchemaObject, ValidateFunction } from 'ajv';
 import type { SchemaMetadata, SchemaWithMetadata } from '../types';
 export declare let bundledSchemasDir: string;
 /** Override the bundled schemas directory (e.g. when running in a bundled context). */
 export declare function setBundledSchemasDir(dir: string): void;
 export declare function readRawSchema(schemaPath: string): AnySchemaObject;
+export declare const CORE_SCHEMA_PREFIX = "sctx://core/";
+export type PluginSchemaSource = {
+    pluginName: string;
+    schemasDir: string;
+};
 /**
- * Build the full two-layer registry for a schema path:
+ * Build the full multi-layer registry for a schema path:
  * - Layer 1: bundled schemas/ dir (partials only, as fallback)
- * - Layer 2: schema's own dir (partials + target file) — overrides layer 1
- * Does not throw on $id collision; layer 2 silently wins.
+ * - Layer 2: plugin schema dirs (partials + target file if schemaPath is in this plugin's schemasDir)
+ * - Layer 3: schema's own dir (partials + target file)
+ * Throws if a lower-precedence schema collides with a reserved $id or violates namespace rules.
  */
-export declare function buildFullRegistry(schemaPath: string): Map<string, AnySchemaObject>;
-export declare function createValidator(schemaPath: string): ValidateFunction;
+export declare function buildFullRegistry(schemaPath: string, pluginSchemas?: PluginSchemaSource[]): Map<string, AnySchemaObject>;
+export declare function createValidator(schemaPath: string, pluginSchemas?: PluginSchemaSource[]): ValidateFunction;
 export declare function resolveNodeType(type: string, typeAliases: Record<string, string> | undefined): string;
 export interface EntityInfo {
     type: string;
@@ -20,10 +26,10 @@ export interface EntityInfo {
 }
 export declare function extractEntityInfo(schema: SchemaWithMetadata, schemaRefRegistry: Map<string, AnySchemaObject>): EntityInfo[];
 export declare function extractSchemaTypeNames(schema: SchemaWithMetadata, schemaRefRegistry: Map<string, AnySchemaObject>): Set<string>;
-export declare function loadMetadata(schemaPath: string): SchemaMetadata;
+export declare function loadMetadata(schemaPath: string, pluginSchemas?: PluginSchemaSource[]): SchemaMetadata;
 export interface LoadedSchema {
     schema: SchemaWithMetadata;
     schemaRefRegistry: Map<string, AnySchemaObject>;
     schemaValidator: ValidateFunction;
 }
-export declare function loadSchema(schemaPath: string): LoadedSchema;
+export declare function loadSchema(schemaPath: string, pluginSchemas?: PluginSchemaSource[]): LoadedSchema;