@clementine-solutions/jane-io 1.0.0 → 1.0.2

package/dist/core/pipeline/pipeline.js

@@ -0,0 +1,418 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Pipeline | Pipeline
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Orchestrates all pipeline stages into a unified execution
+ *                  lifecycle.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { attachFluentParsers, attachFluentValidators, createEvent, defaultPolicy, policyDecision, resolvePolicy, } from '../common';
+import { rootPath } from '../field-path';
+import { deepClone, detectStructuralType, normalizationRunner, scanRunner, selectNormalizationRules, selectScanRules, validationRunner, } from '../pipeline';
+import { janeRegistry } from '../fluent-registry';
+import { diff, explain, replay, telemetry } from '../analysis';
+import { parseRunner } from '.';
+import { isFluentValidator, isValidationFactory } from './validate';
+import { isFluentParser, isParseFactory } from '../pipeline';
+import { normalizePolicy } from '../common/policy';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Pipeline Runner                                                           *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Runs the configured pipeline through all enabled stages and assembles the
+ * complete result. Coordinates scan, normalize, parse, validate, analysis,
+ * and policy decision into a single execution flow.
+ */
+export async function pipelineRunner(input) {
+    const startedAt = new Date();
+    const { raw, path: inputPath, policy, scanRules, parseRules, validationRules, inputName, userMessageOverride, telemetrySink, } = input;
+    const path = inputPath ?? rootPath();
+    const allEvents = [];
+    let scanEvents = [];
+    let normalizeEvents = [];
+    let parseEvents = [];
+    let validateEvents = [];
+    // ----------------------------------------
+    // 1. Scan (optional, fail-fast on fatal)
+    // ----------------------------------------
+    let safe = deepClone(raw);
+    if (policy.scan) {
+        const scanResult = await scanRunner({
+            raw,
+            path,
+            rules: scanRules,
+            policy,
+        });
+        safe = scanResult.safe;
+        scanEvents = scanResult.events;
+        allEvents.push(...scanResult.events);
+        const fatalEvent = scanResult.events.find((e) => e.kind === 'fatal');
+        if (fatalEvent) {
+            const finishedAt = new Date();
+            const metadata = {
+                runId: crypto.randomUUID(),
+                startedAt: startedAt.toISOString(),
+                finishedAt: finishedAt.toISOString(),
+                boundaryName: policy.boundaryName,
+                pipelineName: policy.pipelineName,
+                durationMs: finishedAt.getTime() - startedAt.getTime(),
+                inputName,
+                analysis: {
+                    diff: policy.analysis?.diff,
+                    explain: policy.analysis?.explain,
+                    replay: policy.analysis?.replay,
+                    telemetry: policy.analysis?.telemetry,
+                },
+            };
+            const policyResult = policyDecision({
+                policy,
+                raw,
+                safe,
+                normalized: undefined,
+                final: undefined,
+                path,
+                rawType: detectStructuralType(raw),
+                safeType: detectStructuralType(safe),
+                normalizedType: detectStructuralType(undefined),
+                finalType: detectStructuralType(undefined),
+                events: allEvents,
+                issues: scanEvents,
+                scanEvents,
+                normalizeEvents: [],
+                parseEvents: [],
+                validateEvents: [],
+                diff: undefined,
+                explain: undefined,
+                replay: undefined,
+            }, metadata);
+            if (policy.analysis?.telemetry && telemetrySink) {
+                const tel = telemetry({
+                    boundaryName: policy.boundaryName ?? 'unknown-boundary',
+                    pipelineName: policy.pipelineName ?? 'unknown-pipeline',
+                    result: policyResult,
+                });
+                telemetrySink(tel.records);
+            }
+            return policyResult;
+        }
+    }
+    else {
+        safe = deepClone(raw);
+        const event = createEvent('scan', 'info', 'scan.is.disabled', path, 'Scan stage was skipped because policy.scan is false.', undefined, { scan: false, mode: policy.mode });
+        scanEvents = [event];
+        allEvents.push(event);
+    }
+    // ----------------------------------------
+    // 2. Normalize (mode-aware)
+    // ----------------------------------------
+    let normalized = safe;
+    let finalValue = safe;
+    if (policy.mode !== 'strict') {
+        const normalizationRules = selectNormalizationRules(safe);
+        const normalizationResult = await normalizationRunner({
+            safe,
+            path,
+            rules: normalizationRules,
+            mode: policy.mode,
+        });
+        normalized = normalizationResult.normalized;
+        finalValue = normalizationResult.normalized;
+        normalizeEvents = normalizationResult.events;
+        allEvents.push(...normalizationResult.events);
+    }
+    // ----------------------------------------
+    // 3. Parse (explicit rules only)
+    // ----------------------------------------
+    if (parseRules.length > 0) {
+        if (policy.mode === 'strict') {
+            const warn = createEvent('parse', 'warn', 'policy.is.strict', path, 'Parse stage was skipped in strict mode.', undefined, { mode: policy.mode, rules: parseRules.length });
+            parseEvents = [warn];
+            allEvents.push(warn);
+        }
+        else {
+            const parseResult = await parseRunner({
+                value: normalized,
+                path,
+                rules: parseRules,
+            });
+            finalValue = parseResult.parsed;
+            parseEvents = parseResult.events;
+            allEvents.push(...parseResult.events);
+        }
+    }
+    // ----------------------------------------
+    // 4. Diff (lazy)
+    // ----------------------------------------
+    const diffResult = policy.analysis?.diff
+        ? await diff(safe, normalized)
+        : undefined;
+    // ----------------------------------------
+    // 5. Validate
+    // ----------------------------------------
+    const validateResult = await validationRunner({
+        value: finalValue,
+        path,
+        rules: validationRules,
+    });
+    validateEvents = validateResult.events;
+    if (userMessageOverride) {
+        validateEvents = validateEvents.map((event) => ({
+            ...event,
+            userMessage: userMessageOverride,
+        }));
+    }
+    allEvents.push(...validateEvents);
+    if (inputName) {
+        for (let i = 0; i < allEvents.length; i++) {
+            allEvents[i] = {
+                ...allEvents[i],
+                inputName,
+            };
+        }
+    }
+    // ----------------------------------------
+    // 6. Explain (lazy)
+    // ----------------------------------------
+    const explanation = policy.analysis?.explain
+        ? explain({
+            scanEvents,
+            normalizationEvents: normalizeEvents,
+            parseEvents,
+            validationEvents: validateEvents,
+            diff: diffResult,
+        })
+        : undefined;
+    // ----------------------------------------
+    // 7. Replay (lazy)
+    // ----------------------------------------
+    const replayResult = policy.analysis?.replay
+        ? replay({
+            before: safe,
+            diff: diffResult?.entries ?? [],
+        })
+        : undefined;
+    // ----------------------------------------
+    // 8. Decide (policy reducer)
+    // ----------------------------------------
+    const finishedAt = new Date();
+    const metadata = {
+        runId: crypto.randomUUID(),
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        inputName,
+    };
+    const policyResult = policyDecision({
+        policy,
+        raw,
+        safe,
+        normalized,
+        final: finalValue,
+        path,
+        rawType: detectStructuralType(raw),
+        safeType: detectStructuralType(safe),
+        normalizedType: detectStructuralType(normalized),
+        finalType: detectStructuralType(finalValue),
+        events: allEvents,
+        issues: [],
+        scanEvents,
+        normalizeEvents,
+        parseEvents,
+        validateEvents,
+        diff: diffResult,
+        explain: explanation,
+        replay: replayResult,
+    }, metadata);
+    const pipelineResult = {
+        decision: policyResult.decision,
+        policy,
+        raw,
+        safe,
+        normalized,
+        final: finalValue,
+        path,
+        rawType: detectStructuralType(raw),
+        safeType: detectStructuralType(safe),
+        normalizedType: detectStructuralType(normalized),
+        finalType: detectStructuralType(finalValue),
+        events: allEvents,
+        issues: policyResult.issues,
+        scanEvents,
+        normalizeEvents,
+        parseEvents,
+        validateEvents,
+        diff: diffResult,
+        explain: explanation,
+        replay: replayResult,
+        metadata,
+    };
+    // ----------------------------------------
+    // 9. Telemetry (after result is complete)
+    // ----------------------------------------
+    if (policy.analysis?.telemetry && telemetrySink) {
+        const tel = telemetry({
+            boundaryName: policy.boundaryName ?? 'unknown-boundary',
+            pipelineName: policy.pipelineName ?? 'unknown-pipeline',
+            result: pipelineResult,
+        });
+        telemetrySink(tel.records);
+    }
+    return pipelineResult;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Create Pipeline                                                           *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Creates a new pipeline builder rooted at the given raw value and path.
+ * Establishes the initial rule sets, policy state, and override surface,
+ * returning a fluent interface for assembling and running a complete pipeline.
+ */
+export function createPipeline(raw, path = rootPath(), scanRules = [], parseRules = [], validationRules = [], policy, overrides = {}) {
+    const base = {
+        raw,
+        path,
+        scanRules,
+        parseRules,
+        validationRules,
+        policy,
+        overrides,
+        async run() {
+            const effectivePolicy = resolvePolicy(defaultPolicy, this.policy, this.overrides);
+            return pipelineRunner({
+                raw: this.raw,
+                path: this.path,
+                policy: effectivePolicy,
+                scanRules: [...this.scanRules],
+                parseRules: [...this.parseRules],
+                validationRules: [...this.validationRules],
+                inputName: this.overrides.inputName,
+                userMessageOverride: this.overrides.userMessageOverride,
+                telemetrySink: this.overrides.telemetrySink,
+            });
+        },
+    };
+    const core = {
+        ...base,
+        scan() {
+            return createPipeline(this.raw, this.path, selectScanRules(this.raw), this.parseRules, this.validationRules, this.policy, { ...this.overrides, scan: true });
+        },
+        parse(ruleOrName, ...args) {
+            let rule;
+            if (typeof ruleOrName === 'string') {
+                const entry = janeRegistry.parsers[ruleOrName];
+                if (isParseFactory(entry)) {
+                    // entry is the factory — NOT ruleOrName
+                    const factory = entry;
+                    rule = factory(...args);
+                }
+                else if (isFluentParser(entry)) {
+                    rule = entry;
+                }
+                else {
+                    throw new Error('Invalid parser entry');
+                }
+            }
+            else {
+                rule = ruleOrName;
+            }
+            return createPipeline(this.raw, this.path, this.scanRules, [...this.parseRules, rule], this.validationRules, this.policy, this.overrides);
+        },
+        validate(ruleOrName, ...args) {
+            let rule;
+            if (typeof ruleOrName === 'string') {
+                const entry = janeRegistry.validators[ruleOrName];
+                if (isValidationFactory(entry)) {
+                    const factory = entry;
+                    rule = factory(...args);
+                }
+                else if (isFluentValidator(entry)) {
+                    rule = entry;
+                }
+                else {
+                    throw new Error('Invalid validator entry');
+                }
+            }
+            else {
+                rule = ruleOrName;
+            }
+            return createPipeline(this.raw, this.path, this.scanRules, this.parseRules, [...this.validationRules, rule], this.policy, this.overrides);
+        },
+        named(name) {
+            return createPipeline(this.raw, this.path, this.scanRules, this.parseRules, this.validationRules, this.policy, {
+                ...this.overrides,
+                inputName: name,
+            });
+        },
+        userMessage(message) {
+            return createPipeline(this.raw, this.path, this.scanRules, this.parseRules, this.validationRules, this.policy, {
+                ...this.overrides,
+                userMessageOverride: message,
+            });
+        },
+        strict() {
+            return createPipeline(this.raw, this.path, this.scanRules, this.parseRules, this.validationRules, this.policy, { ...this.overrides, mode: 'strict' });
+        },
+        moderate() {
+            return createPipeline(this.raw, this.path, this.scanRules, this.parseRules, this.validationRules, this.policy, { ...this.overrides, mode: 'moderate' });
+        },
+        lax() {
+            return createPipeline(this.raw, this.path, this.scanRules, this.parseRules, this.validationRules, this.policy, { ...this.overrides, mode: 'lax' });
+        },
+        withDiff() {
+            return createPipeline(this.raw, this.path, this.scanRules, this.parseRules, this.validationRules, this.policy, {
+                ...this.overrides,
+                analysis: {
+                    ...(this.overrides.analysis ?? {}),
+                    diff: true,
+                },
+            });
+        },
+        withExplain() {
+            return createPipeline(this.raw, this.path, this.scanRules, this.parseRules, this.validationRules, this.policy, {
+                ...this.overrides,
+                analysis: {
+                    ...(this.overrides.analysis ?? {}),
+                    explain: true,
+                },
+            });
+        },
+        withReplay() {
+            return createPipeline(this.raw, this.path, this.scanRules, this.parseRules, this.validationRules, this.policy, {
+                ...this.overrides,
+                analysis: {
+                    ...(this.overrides.analysis ?? {}),
+                    replay: true,
+                },
+            });
+        },
+        withTelemetry(sink) {
+            return createPipeline(this.raw, this.path, this.scanRules, this.parseRules, this.validationRules, this.policy, {
+                ...this.overrides,
+                telemetrySink: sink,
+                analysis: {
+                    ...(this.overrides.analysis ?? {}),
+                    telemetry: true,
+                },
+            });
+        },
+        withPolicy(input) {
+            const merged = normalizePolicy(this.policy ?? defaultPolicy, input);
+            return createPipeline(this.raw, this.path, this.scanRules, this.parseRules, this.validationRules, merged, this.overrides);
+        },
+        allowBigint() {
+            return createPipeline(this.raw, this.path, this.scanRules, this.parseRules, this.validationRules, this.policy, {
+                ...this.overrides,
+                exception: {
+                    ...this.overrides.exception,
+                    bigint: true,
+                },
+            });
+        },
+    };
+    const builder = core;
+    attachFluentValidators(builder);
+    attachFluentParsers(builder);
+    return builder;
+}

package/dist/core/pipeline/scan.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Pipeline | Scan
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Inspects the contained value and emits structural
+ *                  observations for later stages.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { EventCode, EventKind, FieldPath, JaneEvent, ScanRule, ScanRunner, StructuralType } from '../shapes';
+/**
+ * Classifies a raw value into one of Jane’s structural types.
+ *
+ * Used by the scanner to select appropriate rules without relying on
+ * user‑defined schemas or runtime shape assumptions.
+ */
+export declare function detectStructuralType(input: unknown): StructuralType;
+/**
+ * Computes the maximum nesting depth of a JSON‑like structure.
+ *
+ * Traverses objects recursively and returns the deepest level encountered,
+ * ignoring non‑object values and null.
+ */
+export declare function measureDepth(value: unknown, current?: number): number;
+/**
+ * Creates a scan‑stage event.
+ *
+ * Wraps createEvent with the 'scan' stage tag, producing structured
+ * observations emitted during the scan pipeline phase.
+ */
+export declare const scanEvent: (kind: EventKind, code: EventCode, path: FieldPath, message: string, userMessage?: string, meta?: Record<string, unknown>) => JaneEvent;
+/**
+ * Executes the scan stage for a single value.
+ *
+ * Produces a safe contained value, applies all scan rules, collects
+ * emitted events, and performs a structural walk to ensure full coverage.
+ */
+export declare const scanRunner: ScanRunner;
+/**
+ * Selects scan rules based on the structural type of the raw value.
+ *
+ * Returns the union of universal rules and the rules specific to the
+ * detected type, ensuring consistent and predictable scan behavior.
+ */
+export declare function selectScanRules(raw: unknown): readonly ScanRule[];

package/dist/core/pipeline/scan.js

@@ -0,0 +1,115 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Pipeline | Scan
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Inspects the contained value and emits structural
+ *                  observations for later stages.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { createEvent } from '../common';
+import { rootPath, walk } from '../field-path';
+import { scanRuleRegistry } from '../scanners';
+import { containValue, defaultContainmentOptions } from '.';
+import { makeFieldPath } from '../field-path/construct';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Detect Structural Type                                                    *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Classifies a raw value into one of Jane’s structural types.
+ *
+ * Used by the scanner to select appropriate rules without relying on
+ * user‑defined schemas or runtime shape assumptions.
+ */
+export function detectStructuralType(input) {
+    if (typeof input === 'string')
+        return 'string';
+    if (typeof input === 'number')
+        return 'number';
+    if (typeof input === 'boolean')
+        return 'boolean';
+    if (typeof input === 'bigint')
+        return 'bigint';
+    if (input === null)
+        return 'unknown';
+    if (Array.isArray(input))
+        return 'array';
+    if (input instanceof Date)
+        return 'date';
+    if (typeof input === 'object')
+        return 'object';
+    return 'unknown';
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Measure Depth                                                             *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Computes the maximum nesting depth of a JSON‑like structure.
+ *
+ * Traverses objects recursively and returns the deepest level encountered,
+ * ignoring non‑object values and null.
+ */
+export function measureDepth(value, current = 0) {
+    if (typeof value !== 'object' || value === null)
+        return current;
+    let max = current;
+    for (const key of Object.keys(value)) {
+        const child = value[key];
+        const depth = measureDepth(child, current + 1);
+        if (depth > max)
+            max = depth;
+    }
+    return max;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Scan Event                                                                *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Creates a scan‑stage event.
+ *
+ * Wraps createEvent with the 'scan' stage tag, producing structured
+ * observations emitted during the scan pipeline phase.
+ */
+export const scanEvent = (kind, code, path, message, userMessage, meta) => createEvent('scan', kind, code, path, message, userMessage, meta);
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Scan Runner                                                               *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Executes the scan stage for a single value.
+ *
+ * Produces a safe contained value, applies all scan rules, collects
+ * emitted events, and performs a structural walk to ensure full coverage.
+ */
+export const scanRunner = async (input) => {
+    const { raw, path: inputPath, rules, policy } = input;
+    const path = inputPath ? makeFieldPath([...inputPath.segments]) : rootPath();
+    const events = [];
+    const safe = containValue(raw, path, defaultContainmentOptions, policy);
+    for (const rule of rules) {
+        try {
+            const emitted = await rule(raw, path);
+            if (emitted && emitted.length > 0) {
+                events.push(...emitted);
+            }
+        }
+        catch (err) {
+            events.push(createEvent('scan', 'fatal', 'error.while.scanning', path, String(err)));
+        }
+    }
+    await walk(raw, path, async () => { });
+    return { events, safe: safe };
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Select Scan Rules                                                         *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Selects scan rules based on the structural type of the raw value.
+ *
+ * Returns the union of universal rules and the rules specific to the
+ * detected type, ensuring consistent and predictable scan behavior.
+ */
+export function selectScanRules(raw) {
+    const type = detectStructuralType(raw);
+    return [...scanRuleRegistry.all, ...scanRuleRegistry[type]];
+}

package/dist/core/pipeline/validate.d.ts

@@ -0,0 +1,40 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Pipeline | Validate
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Evaluates the normalized value and emits rule‑driven
+ *                  correctness events.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { EventCode, EventKind, FieldPath, JaneEvent, ValidatorFactory, ValidationStageContext, ValidationStageOutput, ValidatorFluentRule, ValidationRule } from '../shapes';
+/**
+ * Determines whether a fluent validator entry is a factory.
+ *
+ * Factories accept arbitrary parameters and return a ValidationRule,
+ * distinguishing them from fixed‑signature fluent validators.
+ */
+export declare function isValidationFactory(fn: ValidatorFluentRule): fn is ValidatorFactory;
+/**
+ * Determines whether a fluent validator entry is a direct validation rule.
+ *
+ * Fluent validators always expose a two‑argument signature—value and path—
+ * making them distinguishable from parameterized factories.
+ */
+export declare function isFluentValidator(fn: ValidatorFluentRule): fn is ValidationRule;
+/**
+ * Creates a validation‑stage event.
+ *
+ * Wraps createEvent with the 'validate' phase tag, producing correctness‑
+ * focused messages emitted during rule evaluation.
+ */
+export declare const validationEvent: (kind: EventKind, code: EventCode, path: FieldPath, message?: string, userMessage?: string, meta?: Record<string, unknown>) => JaneEvent;
+/**
+ * Executes the validation stage.
+ *
+ * Applies each validation rule to the value, collects all emitted events,
+ * and records fatal errors when rules throw. Produces the complete set of
+ * correctness observations for the stage.
+ */
+export declare const validationRunner: (input: ValidationStageContext) => Promise<ValidationStageOutput>;