structured-context 0.19.0 → 0.21.0

package/dist/api.d.ts

@@ -23,6 +23,7 @@ export type { Config, SpaceConfig } from './config';
 export { loadConfig, resolveConfigPath, resolveSchema, resolveSchemaPath, setConfigPath } from './config';
 export { addSpace } from './config/write';
 export { LOCAL_CONFIG_FILE, PLUGIN_PREFIX } from './constants';
+export { SctxError, type SctxErrorCode } from './errors';
 export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
 export type { ParseHook, ParseResult, PluginContext, RenderFileOutput, RenderFormat, RenderHook, RenderMultiFileOutput, RenderOptions, RenderResult, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util';
 export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util';
@@ -31,7 +32,7 @@ export { buildTargetIndex, formatWikilink, type ParsedWikilink, parseWikilink, w
 export { listSchemas } from './schema/list-schemas';
 export type { SharedEmbeddingFields } from './schema/metadata-contract';
 export { bundledSchemasDir, loadSchema, type PluginSchemaSource, setBundledSchemasDir } from './schema/schema';
-export { createSpaceContext, SpaceNotFoundError } from './space-context';
+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';

package/dist/api.js

@@ -22,13 +22,14 @@ export { spaceGraphFrom } from './browser';
 export { loadConfig, resolveConfigPath, resolveSchema, resolveSchemaPath, setConfigPath } from './config';
 export { addSpace } from './config/write';
 export { LOCAL_CONFIG_FILE, PLUGIN_PREFIX } from './constants';
+export { SctxError } from './errors';
 export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
 export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util';
 export { readSpace } from './read/read-space';
 export { buildTargetIndex, formatWikilink, parseWikilink, wikilinkToTarget, } from './read/wikilink-utils';
 export { listSchemas } from './schema/list-schemas';
 export { bundledSchemasDir, loadSchema, setBundledSchemasDir } from './schema/schema';
-export { createSpaceContext, SpaceNotFoundError } from './space-context';
+export { createSpaceContext } from './space-context';
 export { buildSpaceGraph } from './space-graph';
 export { exportSpaceGraph } from './space-graph-data';
 export { validateFile, validateSpace } from './validate';

package/dist/commands/validate-file.d.ts

@@ -1,3 +1,4 @@
+import { type ValidateFileOptions } from '../validate';
 export { validateFile } from '../validate';
 /**
  * CLI command: validate a file and print results to stdout.
@@ -6,7 +7,4 @@ export { validateFile } from '../validate';
  */
 export declare function validateFileCommand(filePath: string, options?: {
     json?: boolean;
-    includeGated?: boolean;
-    semantic?: boolean | string;
-    ruleFilter?: string[];
-}): Promise<number>;
+} & Omit<ValidateFileOptions, 'configDir'>): Promise<number>;

package/dist/commands/validate-file.js

@@ -1,6 +1,4 @@
 import { loadConfig } from '../config';
-import { judgeForRun } from '../judge/factory';
-import { parseRuleFilter } from '../schema/rule-filter';
 import { createSpaceContext } from '../space-context';
 import { fileNotInSpace, resolveFileSpace, validateResolvedFile } from '../validate';
 export { validateFile } from '../validate';
@@ -14,12 +12,7 @@ export async function validateFileCommand(filePath, options = {}) {
     const resolved = resolveFileSpace(filePath, config);
     let result;
     if (resolved) {
-        const judge = judgeForRun(config, resolved.space, options.semantic);
-        result = await validateResolvedFile(filePath, resolved.label, createSpaceContext(resolved.space.name, config), {
-            includeGated: options.includeGated,
-            judge,
-            ruleFilter: options.ruleFilter && parseRuleFilter(options.ruleFilter),
-        });
+        result = await validateResolvedFile(filePath, resolved.label, createSpaceContext(resolved.space.name, config), options);
     }
     else {
         result = fileNotInSpace(filePath);

package/dist/commands/validate.d.ts

@@ -1,9 +1,6 @@
 import type { SpaceContext } from '../types';
+import { type ValidateSpaceOptions } from '../validate';
 export declare function validate(context: SpaceContext, options?: {
     json?: boolean;
-    depth?: number;
-    includeGated?: boolean;
-    semantic?: boolean | string;
-    ruleFilter?: string[];
-}): Promise<number>;
+} & ValidateSpaceOptions): Promise<number>;
 export declare function watchValidate(context: SpaceContext): Promise<never>;

package/dist/commands/validate.js

@@ -1,18 +1,11 @@
 import { dirname } from 'node:path';
 import chokidar from 'chokidar';
 import { getConfigSourceFiles } from '../config';
-import { judgeForRun } from '../judge/factory';
 import { resolveSpacePluginSchemas } from '../plugins/util';
-import { parseRuleFilter } from '../schema/rule-filter';
 import { bundledSchemasDir } from '../schema/schema';
 import { formatSource, ruleViolationMessage, validateSpace } from '../validate';
 export async function validate(context, options = {}) {
-    const result = await validateSpace(context, {
-        depth: options.depth,
-        includeGated: options.includeGated,
-        judge: judgeForRun(context.config, context.space, options.semantic),
-        ruleFilter: options.ruleFilter && parseRuleFilter(options.ruleFilter),
-    });
+    const result = await validateSpace(context, options);
     const ruleCounts = { error: 0, warning: 0, info: 0 };
     for (const v of result.ruleViolations)
         ruleCounts[v.severity]++;

package/dist/errors.d.ts

@@ -2,7 +2,7 @@
  * Stable codes for configuration and environment problems. Hooks and agent skills map a code to a
  * fix, so the message wording can change without breaking them.
  */
-export type SctxErrorCode = 'E_CONFIG_NOT_FOUND' | 'E_CONFIG_INVALID' | 'E_INCLUDE_NOT_FOUND' | 'E_NO_SPACES' | 'E_SPACE_PATH_MISSING' | 'E_SCHEMA_MISSING' | 'E_SCHEMA_NOT_FOUND' | 'E_SCHEMA_INVALID' | 'E_SPACE_EXISTS' | 'E_TARGET_REQUIRED' | 'E_CONFIG_NEEDS_MANUAL_EDIT';
+export type SctxErrorCode = 'E_CONFIG_NOT_FOUND' | 'E_CONFIG_INVALID' | 'E_INCLUDE_NOT_FOUND' | 'E_NO_SPACES' | 'E_SPACE_PATH_MISSING' | 'E_SCHEMA_MISSING' | 'E_SCHEMA_NOT_FOUND' | 'E_SCHEMA_INVALID' | 'E_SPACE_EXISTS' | 'E_SPACE_NOT_FOUND' | 'E_TARGET_REQUIRED' | 'E_CONFIG_NEEDS_MANUAL_EDIT' | 'E_MODEL_PROVIDER_INVALID';
 export declare class SctxError extends Error {
     readonly code: SctxErrorCode;
     constructor(code: SctxErrorCode, message: string);

package/dist/index.js

@@ -17,36 +17,14 @@ import { validateFileCommand } from './commands/validate-file';
 import { loadConfig, setConfigPath } from './config';
 import { CLI_NAME } from './constants';
 import { SctxError } from './errors';
-import { JudgeConfigError } from './judge/factory';
-import { createSpaceContext, SpaceNotFoundError } from './space-context';
+import { createSpaceContext } from './space-context';
 // Once node:process is loaded (vfile, via unified, loads it), Bun's console.log drops piped output
 // past 64KB when the reader is slow. process.stdout.write delivers all of it before exit.
 console.log = (...args) => {
     process.stdout.write(`${format(...args)}\n`);
 };
 export function buildSpaceContext(spaceName) {
-    try {
-        return createSpaceContext(spaceName, loadConfig());
-    }
-    catch (err) {
-        if (err instanceof SpaceNotFoundError) {
-            console.error(`Error: ${err.message}`);
-            process.exit(1);
-        }
-        throw err;
-    }
-}
-/** Run a validate command, reporting a misconfigured model provider as a plain error rather than a stack trace. */
-async function reportJudgeConfigErrors(run) {
-    try {
-        return await run();
-    }
-    catch (err) {
-        if (!(err instanceof JudgeConfigError))
-            throw err;
-        console.error(`Error: ${err.message}`);
-        return 1;
-    }
+    return createSpaceContext(spaceName, loadConfig());
 }
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
@@ -68,12 +46,12 @@ program
     .option('--rule-filter <dimension=values>', 'Evaluate only matching rules; dimensions: category, severity, type, id (repeatable, e.g. severity=error)', (v, prev = []) => [...prev, v])
     .option('--semantic [provider]', 'Evaluate semantic rules, with the configured model provider or the one named')
     .action(async (filePath, options) => {
-    process.exitCode = await reportJudgeConfigErrors(() => validateFileCommand(filePath, {
+    process.exitCode = await validateFileCommand(filePath, {
         json: options.json,
         includeGated: options.includeGated,
         semantic: options.semantic,
         ruleFilter: options.ruleFilter,
-    }));
+    });
 });
 program
     .command('validate')
@@ -92,13 +70,13 @@ program
     }
     else {
         // exitCode rather than process.exit(): exiting straight away can cut off large piped output
-        process.exitCode = await reportJudgeConfigErrors(() => validate(context, {
+        process.exitCode = await validate(context, {
             json: options.json,
             depth: options.depth,
             includeGated: options.includeGated,
             semantic: options.semantic,
             ruleFilter: options.ruleFilter,
-        }));
+        });
     }
 });
 program

package/dist/judge/factory.d.ts

@@ -7,8 +7,6 @@ type Env = Record<string, string | undefined>;
  */
 export declare const BUNDLED_PROVIDERS: Record<string, ModelProviderConfig>;
 /** Semantic evaluation is misconfigured (no provider, unknown provider, missing key). Reported as a plain CLI error. */
-export declare class JudgeConfigError extends Error {
-}
 /**
  * Hydrate a provider definition into concrete values, in one place. Per field: the explicit value
  * wins, then the named environment variable if it is set (a set-but-empty variable is an error, not
@@ -29,7 +27,7 @@ export declare function judgeForRun(config: Parameters<typeof createJudge>[0], s
 /**
  * The provider for a run: the one named by `name` (the `--semantic <provider>` override), else the space's
  * `semantic.provider`, else the top-level one. The name resolves against `modelProviders` first, then
- * the bundled providers. Throws {@link JudgeConfigError} when it cannot be built.
+ * the bundled providers. Throws {@link SctxError} `E_MODEL_PROVIDER_INVALID` when it cannot be built.
  */
 export declare function createJudge(config: {
     modelProviders?: Record<string, ModelProviderConfig>;

package/dist/judge/factory.js

@@ -1,3 +1,4 @@
+import { SctxError } from '../errors';
 import { AnthropicJudgeProvider, RECOMMENDED_ANTHROPIC_MODEL } from './provider/anthropic';
 import { FakeJudgeProvider } from './provider/fake';
 import { JEV_LATEST, JevJudgeProvider } from './provider/jev';
@@ -66,8 +67,6 @@ const DEFAULT_KEY_ENV = {
     'typesafe-systemone': 'TYPESAFE_API_KEY',
 };
 /** Semantic evaluation is misconfigured (no provider, unknown provider, missing key). Reported as a plain CLI error. */
-export class JudgeConfigError extends Error {
-}
 /**
  * Hydrate a provider definition into concrete values, in one place. Per field: the explicit value
  * wins, then the named environment variable if it is set (a set-but-empty variable is an error, not
@@ -75,7 +74,7 @@ export class JudgeConfigError extends Error {
  */
 export function hydrateProvider(name, def, env = process.env) {
     if (!MODEL_PROVIDER_APIS.includes(def.api)) {
-        throw new JudgeConfigError(`Model provider "${name}" has unknown api "${def.api}". Use one of: ${MODEL_PROVIDER_APIS.join(', ')}.`);
+        throw new SctxError('E_MODEL_PROVIDER_INVALID', `Model provider "${name}" has unknown api "${def.api}". Use one of: ${MODEL_PROVIDER_APIS.join(', ')}.`);
     }
     const fromEnv = (value, envName) => {
         if (value !== undefined)
@@ -84,7 +83,7 @@ export function hydrateProvider(name, def, env = process.env) {
             return undefined;
         const envValue = env[envName];
         if (envValue !== undefined && envValue.trim() === '') {
-            throw new JudgeConfigError(`Model provider "${name}" has ${envName} set but empty; set a value or unset the variable.`);
+            throw new SctxError('E_MODEL_PROVIDER_INVALID', `Model provider "${name}" has ${envName} set but empty; set a value or unset the variable.`);
         }
         return envValue;
     };
@@ -104,7 +103,7 @@ export function createModelProvider(name, def, env = process.env) {
     // OpenAI-compatible endpoints (Ollama, vLLM, ...) may need no key; the others must resolve one.
     // A key never borrows another provider's variable: only the named apiKeyEnv (or literal apiKey) counts.
     if (!h.apiKey && h.api !== 'openai-completions' && h.api !== 'fake') {
-        throw new JudgeConfigError(`Model provider "${name}" (${h.api}) has no API key. Set ${h.keyEnv} in the environment, or "apiKey" / "apiKeyEnv" on the provider.`);
+        throw new SctxError('E_MODEL_PROVIDER_INVALID', `Model provider "${name}" (${h.api}) has no API key. Set ${h.keyEnv} in the environment, or "apiKey" / "apiKeyEnv" on the provider.`);
     }
     switch (h.api) {
         case 'fake':
@@ -132,17 +131,17 @@ export function judgeForRun(config, space, semantic) {
 /**
  * The provider for a run: the one named by `name` (the `--semantic <provider>` override), else the space's
  * `semantic.provider`, else the top-level one. The name resolves against `modelProviders` first, then
- * the bundled providers. Throws {@link JudgeConfigError} when it cannot be built.
+ * the bundled providers. Throws {@link SctxError} `E_MODEL_PROVIDER_INVALID` when it cannot be built.
  */
 export function createJudge(config, space = {}, name, env = process.env) {
     const chosen = name ?? space.semantic?.provider ?? config.semantic?.provider;
     if (!chosen) {
-        throw new JudgeConfigError('--semantic needs a model provider. Set "semantic.provider" in config.json, or pass --semantic <provider>.');
+        throw new SctxError('E_MODEL_PROVIDER_INVALID', '--semantic needs a model provider. Set "semantic.provider" in config.json, or pass --semantic <provider>.');
     }
     const def = config.modelProviders?.[chosen] ?? BUNDLED_PROVIDERS[chosen];
     if (!def) {
         const known = [...Object.keys(BUNDLED_PROVIDERS), ...Object.keys(config.modelProviders ?? {})];
-        throw new JudgeConfigError(`Model provider "${chosen}" is not configured.${known.length ? ` Known providers: ${known.join(', ')}.` : ''}`);
+        throw new SctxError('E_MODEL_PROVIDER_INVALID', `Model provider "${chosen}" is not configured.${known.length ? ` Known providers: ${known.join(', ')}.` : ''}`);
     }
     return createModelProvider(chosen, def, env);
 }

package/dist/space-context.d.ts

@@ -1,10 +1,5 @@
 import { type Config } from './config';
 import type { SpaceContext } from './types';
-/** Thrown by createSpaceContext when no space matches the given name. */
-export declare class SpaceNotFoundError extends Error {
-    readonly spaceName: string;
-    constructor(spaceName: string);
-}
 export interface CreateSpaceContextOptions {
     /**
      * Directory to anchor relative plugin-config paths against. Defaults to the source
@@ -20,8 +15,7 @@ export interface CreateSpaceContextOptions {
  * Synchronously resolves schemas (including plugin-contributed schemas),
  * indexes partials into the registry, and compiles the schema validator.
  *
- * Library-safe: throws {@link SpaceNotFoundError} on an unknown space rather than
- * writing to the console or exiting the process. CLI callers that want the
- * exit-on-error behaviour should wrap this (see buildSpaceContext in index.ts).
+ * Library-safe: throws SctxError (E_SPACE_NOT_FOUND) on an unknown space rather than
+ * writing to the console or exiting the process.
  */
 export declare function createSpaceContext(spaceName: string, config: Config, options?: CreateSpaceContextOptions): SpaceContext;

package/dist/space-context.js

@@ -2,29 +2,19 @@ import { resolveSchema } from './config';
 import { SctxError } from './errors';
 import { resolveSpacePluginSchemas } from './plugins/util';
 import { loadSchema } from './schema/schema';
-/** Thrown by createSpaceContext when no space matches the given name. */
-export class SpaceNotFoundError extends Error {
-    spaceName;
-    constructor(spaceName) {
-        super(`Unknown space "${spaceName}"`);
-        this.spaceName = spaceName;
-        this.name = 'SpaceNotFoundError';
-    }
-}
 /**
  * Build a SpaceContext for a named space from an already-loaded config.
  *
  * Synchronously resolves schemas (including plugin-contributed schemas),
  * indexes partials into the registry, and compiles the schema validator.
  *
- * Library-safe: throws {@link SpaceNotFoundError} on an unknown space rather than
- * writing to the console or exiting the process. CLI callers that want the
- * exit-on-error behaviour should wrap this (see buildSpaceContext in index.ts).
+ * Library-safe: throws SctxError (E_SPACE_NOT_FOUND) on an unknown space rather than
+ * writing to the console or exiting the process.
  */
 export function createSpaceContext(spaceName, config, options = {}) {
     const space = config.spaces.find((s) => s.name === spaceName);
     if (!space) {
-        throw new SpaceNotFoundError(spaceName);
+        throw new SctxError('E_SPACE_NOT_FOUND', `Unknown space "${spaceName}"`);
     }
     const configDir = options.configDir ?? space.sourceDir;
     if (configDir === undefined) {

package/dist/validate.d.ts

@@ -62,26 +62,64 @@ export interface ValidationResult {
  * 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;
+interface CommonValidateOptions {
     /** Evaluate rules on gated nodes anyway (gates are still reported). */
     includeGated?: boolean;
-    /** Evaluate only rules matching this filter (see `parseRuleFilter`). */
+    /** Evaluate only rules matching these `dimension=values` filters (category, severity, type, id). */
+    ruleFilter?: string[];
+    /**
+     * Evaluate `semantic` rules with the model provider named here, or with the configured one for `true`.
+     * Without it, a rule runs only its `expression`, and a semantic-only rule is skipped.
+     */
+    semantic?: boolean | string;
+}
+/** What a run evaluates with: the public options after the filter is parsed and the judge is built. */
+export interface RunOptions {
+    includeGated?: boolean;
     ruleFilter?: RuleFilter;
-    /** Evaluates `semantic` rules. Without one, a rule runs only its `expression`, and a semantic-only rule is skipped. */
     judge?: SemanticJudgeProvider;
+    /** Limit judging to one file (and the ancestors that can gate it). */
+    judgeTarget?: string;
+}
+export interface ValidateSpaceOptions extends CommonValidateOptions {
+    readResult?: ReadSpaceResult;
+    /** Limit validation to hierarchy nodes within N breadth-first levels from the top. */
+    depth?: number;
 }
 /** `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;
+/** A node that failed type or schema validation. */
+interface NodeValidationFailure {
+    node: SpaceNode;
+    issues: FormattedError[];
+}
+/** The outcome of validating a set of nodes, before either view shapes it. */
+export interface SpaceValidationResult {
+    validCount: number;
+    nodeFailures: NodeValidationFailure[];
+    refErrors: ValidationResult['refErrors'];
+    duplicateErrors: ValidationResult['duplicateErrors'];
+    ruleViolations: RuleViolation[];
+    hierarchyViolations: GraphViolation[];
+    orphans: SpaceNode[];
+    unresolvedContentLinks: ValidationResult['unresolvedContentLinks'];
+    coverageGates: CoverageGate[];
+    contextTrimmed: ValidationResult['contextTrimmed'];
+}
 /**
  * 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'];
+/**
+ * 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`
+ * and `validateFile` are views over it, so a file's results match its entry in a full run.
+ * `judgeTarget` limits judging to one file (and the ancestors that can gate it).
+ */
+export declare function validateNodes(context: SpaceContext, nodes: SpaceNode[], unresolvedRefs: ReadSpaceResult['unresolvedRefs'], options?: RunOptions): Promise<SpaceValidationResult>;
 /**
  * Run full validation on a space and return a structured result.
  * Does not output to console or call process.exit.
@@ -92,14 +130,8 @@ export declare function resolveFileSpace(filePath: string, config: Config): {
     space: SpaceConfig;
     label: string;
 } | null;
-export interface ValidateFileOptions {
+export interface ValidateFileOptions extends CommonValidateOptions {
     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;
@@ -108,6 +140,8 @@ export declare function fileNotInSpace(filePath: string): FileNotInSpaceResult;
  * 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>;
+/** `validateResolvedFile` with the options already resolved, so a caller can supply its own judge. */
+export declare function validateResolvedFileWith(filePath: string, label: string, context: SpaceContext, runOptions: RunOptions): Promise<FileValidationResult>;
 /**
  * Validate a single file within its space.
  *
@@ -118,3 +152,4 @@ export declare function validateResolvedFile(filePath: string, label: string, co
  * If the file is not in any configured space, returns a result with `inSpace: false`.
  */
 export declare function validateFile(filePath: string, config: Config, options?: ValidateFileOptions): Promise<ValidateFileOutput>;
+export {};

package/dist/validate.js

@@ -1,7 +1,8 @@
 import { isAbsolute, relative, resolve } from 'node:path';
+import { judgeForRun } from './judge/factory';
 import { readSpace } from './read/read-space';
 import { computeHierarchyDepths, evaluateRulesWithGating } from './schema/gating';
-import { filterRules } from './schema/rule-filter';
+import { filterRules, parseRuleFilter } from './schema/rule-filter';
 import { extractEntityInfo, typeValidatorFor } from './schema/schema';
 import { validateGraph } from './schema/validate-graph';
 import { validateRules } from './schema/validate-rules';
@@ -94,6 +95,14 @@ export function formatErrors(errors, schema, schemaRefRegistry, nodeData) {
     }
     return formatted;
 }
+/** Throws `SctxError` `E_MODEL_PROVIDER_INVALID` when `semantic` names a provider that cannot be built. */
+function runOptionsFrom(context, options) {
+    return {
+        includeGated: options.includeGated,
+        ruleFilter: options.ruleFilter && parseRuleFilter(options.ruleFilter),
+        judge: judgeForRun(context.config, context.space, options.semantic),
+    };
+}
 /** `file`, `file:line` or `file:line:column`, for messages. */
 export function formatSource({ file, line, column }) {
     return line === undefined ? file : `${file}:${line}${column === undefined ? '' : `:${column}`}`;
@@ -159,7 +168,7 @@ export function findDuplicateIds(nodes) {
  * and `validateFile` are views over it, so a file's results match its entry in a full run.
  * `judgeTarget` limits judging to one file (and the ancestors that can gate it).
  */
-async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
+export async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
     const { schema, schemaRefRegistry, schemaValidator } = context;
     const metadata = schema.metadata;
     // Pre-extract valid types for early type validation
@@ -248,6 +257,7 @@ async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
  */
 export async function validateSpace(context, options = {}) {
     const metadata = context.schema.metadata;
+    const runOptions = runOptionsFrom(context, options);
     const readResult = options.readResult ?? (await readSpace(context));
     let nodes = readResult.nodes;
     // Depth limiting: evaluate only hierarchy nodes within N breadth-first levels from the
@@ -268,11 +278,7 @@ export async function validateSpace(context, options = {}) {
         }
         nodes = included;
     }
-    const result = await validateNodes(context, nodes, readResult.unresolvedRefs, {
-        includeGated: options.includeGated,
-        ruleFilter: options.ruleFilter,
-        judge: options.judge,
-    });
+    const result = await validateNodes(context, nodes, readResult.unresolvedRefs, runOptions);
     return {
         validCount: result.validCount,
         nodeErrorCount: result.nodeFailures.length,
@@ -390,15 +396,17 @@ export function fileNotInSpace(filePath) {
  * 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 async function validateResolvedFile(filePath, label, context, options = {}) {
+export function validateResolvedFile(filePath, label, context, options = {}) {
+    return validateResolvedFileWith(filePath, label, context, runOptionsFrom(context, options));
+}
+/** `validateResolvedFile` with the options already resolved, so a caller can supply its own judge. */
+export async function validateResolvedFileWith(filePath, label, context, runOptions) {
     const readResult = await readSpace(context);
     const result = await validateNodes(context, readResult.nodes, readResult.unresolvedRefs, {
-        includeGated: options.includeGated,
-        ruleFilter: options.ruleFilter,
-        judge: options.judge,
+        ...runOptions,
         judgeTarget: label,
     });
-    const { errors, warnings } = issuesForFile(result, label, options.includeGated);
+    const { errors, warnings } = issuesForFile(result, label, runOptions.includeGated);
     return {
         file: isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath),
         label,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structured-context",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Keep your content clean and your thinking clear with assistive tools for structured knowledge",
   "module": "./dist/index.js",
   "type": "module",

package/dist/judge/index.d.ts

@@ -1,13 +0,0 @@
-export { createJudge, createModelProvider, JudgeConfigError } from './factory';
-export { buildJudgeSystemPrompt, buildJudgeUserPrompt, parseJudgeResponse } from './prompt';
-export type { AnthropicJudgeProviderOptions } from './provider/anthropic';
-export { AnthropicJudgeProvider } from './provider/anthropic';
-export type { FakeAnswer, FakeJudgeHandler } from './provider/fake';
-export { FakeJudgeProvider } from './provider/fake';
-export type { JevJudgeProviderOptions } from './provider/jev';
-export { JevJudgeProvider } from './provider/jev';
-export type { OpenAIJudgeProviderOptions } from './provider/openai';
-export { OpenAIJudgeProvider } from './provider/openai';
-export { PerRuleJudgeProvider } from './provider/per-rule';
-export type { JudgeConfig, ModelProviderConfig, SemanticJudgeInput, SemanticJudgeProvider, SemanticJudgeResult, SemanticJudgeVerdict, SemanticRuleSpec, } from './types';
-export { DEFAULT_VERDICTS, isJudgeError, semanticRuleSpec } from './verdicts';

package/dist/judge/index.js

@@ -1,8 +0,0 @@
-export { createJudge, createModelProvider, JudgeConfigError } from './factory';
-export { buildJudgeSystemPrompt, buildJudgeUserPrompt, parseJudgeResponse } from './prompt';
-export { AnthropicJudgeProvider } from './provider/anthropic';
-export { FakeJudgeProvider } from './provider/fake';
-export { JevJudgeProvider } from './provider/jev';
-export { OpenAIJudgeProvider } from './provider/openai';
-export { PerRuleJudgeProvider } from './provider/per-rule';
-export { DEFAULT_VERDICTS, isJudgeError, semanticRuleSpec } from './verdicts';