@clementine-solutions/jane-io 1.0.1 → 1.0.3

package/dist/core/analysis/diff.js

@@ -0,0 +1,88 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Diff
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Structural diff utilities used to compare safe and
+ *                  normalized values.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { isObject, isPlainObject } from '../common';
+import { appendSegment, rootPath, setIndex, setKey } from '../field-path';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Diff                                                                      *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Computes a structural diff between two JSON‑compatible values.
+ *
+ * Delegates all traversal to `walkDiff`, collecting every change into a flat
+ * list of diff entries rooted at the top‑level path. Always returns a stable
+ * `{ entries }` object with no filtering or interpretation.
+ */
+export const diff = (before, after) => {
+    const entries = [];
+    walkDiff(before, after, rootPath(), entries);
+    return { entries };
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Walk Diff                                                                 *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Recursively walks two JSON‑compatible values and records structural changes.
+ *
+ * Compares primitives, arrays, and plain objects by shape and content, emitting
+ * diff entries at each divergent path. Keys and indices are traversed in a
+ * stable order, and non‑object mismatches are treated as direct value changes.
+ * All entries are appended to `out`; no filtering or interpretation occurs here.
+ */
+export function walkDiff(before, after, path, out) {
+    if (before === after)
+        return;
+    if (!isObject(before) || !isObject(after)) {
+        out.push({
+            path,
+            kind: before === undefined ? 'added' : after === undefined ? 'removed' : 'changed',
+            before,
+            after,
+        });
+        return;
+    }
+    if (Array.isArray(before) && Array.isArray(after)) {
+        const max = Math.max(before.length, after.length);
+        for (let i = 0; i < max; i++) {
+            const childPath = appendSegment(path, setIndex(i));
+            walkDiff(before[i], after[i], childPath, out);
+        }
+        return;
+    }
+    if (isPlainObject(before) && isPlainObject(after)) {
+        const beforeKeys = Object.keys(before);
+        const afterKeys = Object.keys(after);
+        const allKeys = new Set([...beforeKeys, ...afterKeys]);
+        for (const key of allKeys) {
+            const childPath = appendSegment(path, setKey(key));
+            walkDiff(before[key], after[key], childPath, out);
+        }
+        return;
+    }
+    out.push({
+        path,
+        kind: 'changed',
+        before,
+        after,
+    });
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Run Diff                                                                  *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Runs the pipeline and returns its computed diff.
+ *
+ * Delegates execution to the provided builder and exposes only the diff
+ * portion of the result. No additional processing or filtering occurs here.
+ */
+export async function runDiff(builder) {
+    const result = await builder.run();
+    return result.diff;
+}

package/dist/core/analysis/explain.js

@@ -0,0 +1,117 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Explain
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Builds a human‑readable narrative of all pipeline events in
+ *                  order.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Explain                                                                   *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Builds a linear explanation of all pipeline events.
+ *
+ * Emits scan hazards, normalization events, diff entries, parse changes, and
+ * validation errors in pipeline order. Each event is mapped to a stable
+ * ExplainStep with its path, stage, kind, code, and message. No filtering or
+ * interpretation occurs; this is a direct narrative of what the pipeline saw.
+ */
+export const explain = ({ scanEvents, normalizationEvents, parseEvents, validationEvents, diff, }) => {
+    const steps = [];
+    for (const ev of scanEvents) {
+        steps.push({
+            path: ev.path,
+            stage: 'scan',
+            kind: 'hazard',
+            code: ev.code,
+            message: ev.message,
+        });
+    }
+    for (const ev of normalizationEvents) {
+        steps.push({
+            path: ev.path,
+            stage: 'normalize',
+            kind: ev.kind === 'fatal' ? 'hazard' : 'change',
+            code: ev.code,
+            message: ev.message,
+        });
+    }
+    if (diff) {
+        for (const entry of diff.entries) {
+            const message = entry.kind === 'added'
+                ? `Added value: ${format(entry.after)}`
+                : entry.kind === 'removed'
+                    ? `Removed value: ${format(entry.before)}`
+                    : `Changed from ${format(entry.before)} to ${format(entry.after)}`;
+            steps.push({
+                path: entry.path,
+                stage: 'normalize',
+                kind: 'change',
+                code: `normalize.${entry.kind}`,
+                message,
+            });
+        }
+    }
+    for (const ev of parseEvents) {
+        steps.push({
+            path: ev.path,
+            stage: 'parse',
+            kind: 'change',
+            code: ev.code,
+            message: ev.message,
+        });
+    }
+    for (const ev of validationEvents) {
+        steps.push({
+            path: ev.path,
+            stage: 'validate',
+            kind: 'error',
+            code: ev.code,
+            message: ev.message,
+        });
+    }
+    return { steps };
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Format                                                                    *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Formats a value for human‑readable explain output.
+ *
+ * Produces stable string representations for primitives and falls back to
+ * compact JSON for objects. Never throws; errors during formatting degrade
+ * gracefully to `String(value)`.
+ */
+export function format(value) {
+    try {
+        if (value === undefined)
+            return 'undefined';
+        if (value === null)
+            return 'null';
+        if (typeof value === 'string')
+            return JSON.stringify(value);
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            return String(value);
+        }
+        return JSON.stringify(value, null, 0);
+    }
+    catch {
+        return String(value);
+    }
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Run Explain                                                               *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Runs the pipeline and returns its explain output.
+ *
+ * Delegates execution to the provided builder and exposes only the explain
+ * portion of the result. No additional processing or reshaping occurs here.
+ */
+export async function runExplain(builder) {
+    const result = await builder.run();
+    return result.explain;
+}

package/dist/core/analysis/index.js

@@ -0,0 +1,26 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Barrel File
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Re‑exports the public Analysis modules (Diff, Explain,
+ *                  Replay, Telemetry).
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Diff                                                                      *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { diff, walkDiff, runDiff } from './diff';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Explain                                                                   *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { explain, format, runExplain } from './explain';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Replay                                                                    *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { applyEntry, replay, runReplay } from './replay';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Telemetry                                                                 *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { runTelemetry, telemetry } from './telemetry';

package/dist/core/analysis/replay.js

@@ -0,0 +1,68 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Replay
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Reconstructs intermediate states by applying diff entries
+ *                  in order.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { setAtPath } from '../field-path';
+import { deepClone } from '../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Apply Entry                                                               *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Applies a single diff entry to an internal JSON value.
+ *
+ * Clones the current state, then sets or clears the value at the entry’s path
+ * according to its kind. Used by Replay to advance state one change at a time.
+ * Never mutates the original state.
+ */
+export function applyEntry(state, entry) {
+    const clone = deepClone(state);
+    switch (entry.kind) {
+        case 'added':
+        case 'changed':
+            return setAtPath(clone, entry.path, entry.after);
+        case 'removed':
+            return setAtPath(clone, entry.path, undefined);
+    }
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Replay                                                                    *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Replays a diff step‑by‑step to reconstruct intermediate states.
+ *
+ * Clones the initial value, applies each diff entry in order, and records a
+ * snapshot after every application. Produces a stable sequence of ReplayStep
+ * objects with index, entry, and resulting state. Never mutates inputs.
+ */
+export const replay = ({ before, diff }) => {
+    const steps = [];
+    let current = deepClone(before);
+    diff.forEach((entry, index) => {
+        current = applyEntry(current, entry);
+        steps.push({
+            index,
+            entry,
+            state: deepClone(current),
+        });
+    });
+    return { steps };
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Run Replay                                                                *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Runs the pipeline and returns its replay output.
+ *
+ * Delegates execution to the provided builder and exposes only the replay
+ * portion of the result. No additional processing or transformation occurs.
+ */
+export async function runReplay(builder) {
+    const result = await builder.run();
+    return result.replay;
+}

package/dist/core/analysis/telemetry.js

@@ -0,0 +1,123 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Telemetry
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Emits structured records for each pipeline stage for
+ *                  auditing and observability.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { defaultPolicy } from '../common';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Telemetry                                                                 *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Collects flat telemetry records for each pipeline stage.
+ *
+ * Emits one record per stage with boundary, pipeline, timestamp, and the
+ * stage‑specific payload (events, diff, explain, replay). Stages are reported
+ * in pipeline order, and a final `decide` record captures the policy outcome.
+ * No aggregation, filtering, or interpretation occurs here.
+ */
+export function telemetry(ctx) {
+    const { boundaryName, pipelineName, result } = ctx;
+    const timestamp = new Date().toISOString();
+    const records = [];
+    if (result.scanEvents?.length) {
+        records.push({
+            boundary: boundaryName,
+            pipeline: pipelineName,
+            timestamp,
+            stage: 'scan',
+            events: result.scanEvents,
+        });
+    }
+    if (result.normalizeEvents?.length) {
+        records.push({
+            boundary: boundaryName,
+            pipeline: pipelineName,
+            timestamp,
+            stage: 'normalize',
+            events: result.normalizeEvents,
+        });
+    }
+    if (result.parseEvents?.length) {
+        records.push({
+            boundary: boundaryName,
+            pipeline: pipelineName,
+            timestamp,
+            stage: 'parse',
+            events: result.parseEvents,
+        });
+    }
+    if (result.validateEvents?.length) {
+        records.push({
+            boundary: boundaryName,
+            pipeline: pipelineName,
+            timestamp,
+            stage: 'validate',
+            events: result.validateEvents,
+        });
+    }
+    if (result.diff) {
+        records.push({
+            boundary: boundaryName,
+            pipeline: pipelineName,
+            timestamp,
+            stage: 'diff',
+            diff: result.diff,
+        });
+    }
+    if (result.explain) {
+        records.push({
+            boundary: boundaryName,
+            pipeline: pipelineName,
+            timestamp,
+            stage: 'explain',
+            explain: result.explain,
+        });
+    }
+    if (result.replay) {
+        records.push({
+            boundary: boundaryName,
+            pipeline: pipelineName,
+            timestamp,
+            stage: 'replay',
+            replay: result.replay,
+        });
+    }
+    records.push({
+        boundary: boundaryName,
+        pipeline: pipelineName,
+        timestamp,
+        stage: 'decide',
+        decision: result.decision.code,
+        mode: result.policy.mode,
+        eventCount: result.events.length,
+    });
+    return { records };
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Run With Telemetry                                                        *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Runs the pipeline and emits telemetry if enabled by policy.
+ *
+ * Delegates execution to the builder, collects stage records through the
+ * telemetry helper, and forwards them to the provided sink. Returns the full
+ * pipeline result unchanged.
+ */
+export async function runTelemetry(builder, sink) {
+    const result = await builder.run();
+    const policy = builder.policy ?? defaultPolicy;
+    if (policy.analysis?.telemetry) {
+        const tel = telemetry({
+            boundaryName: policy.boundaryName ?? 'unknown-boundary',
+            pipelineName: policy.pipelineName ?? 'unknown-pipeline',
+            result,
+        });
+        sink(tel.records);
+    }
+    return result;
+}

package/dist/core/boundary-rules/at-most-one.js

@@ -0,0 +1,38 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | At Most One
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures that no more than one of the specified fields is
+ *                  accepted. If multiple fields are present, a boundary error
+ *                  is emitted.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { rootPath } from '../field-path';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Ensures that at most one of the specified fields is accepted. If more than
+ * one field is present, a boundary‑level error is emitted.
+ */
+export function atMostOne(...keys) {
+    return ({ fields }) => {
+        const events = [];
+        const issues = [];
+        const present = keys.filter((k) => fields[k]?.decision?.code === 'accept');
+        if (present.length > 1) {
+            const ev = {
+                phase: 'decide',
+                kind: 'error',
+                code: 'boundary.does.at-most-one',
+                message: `At most one of [${keys.join(', ')}] may be present`,
+                path: rootPath(),
+            };
+            events.push(ev);
+            issues.push(ev);
+        }
+        return { events, issues };
+    };
+}

package/dist/core/boundary-rules/conditionally-required.js

@@ -0,0 +1,44 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | Conditionally Required
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Requires a set of fields when a controlling field matches a
+ *                  specific value. Missing or rejected fields trigger
+ *                  boundary‑level errors.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { rootPath } from '../field-path';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Requires a set of fields when a controlling field matches a specific value.
+ * If the condition is met and any required field is missing or rejected, an
+ * error is emitted for each missing field.
+ */
+export function conditionallyRequired(typeKey, typeValue, ...required) {
+    return ({ fields }) => {
+        const events = [];
+        const issues = [];
+        const type = fields[typeKey]?.final;
+        if (type === typeValue) {
+            for (const key of required) {
+                const r = fields[key];
+                if (!r || r.decision?.code !== 'accept') {
+                    const ev = {
+                        phase: 'decide',
+                        kind: 'error',
+                        code: 'boundary.does.require-field',
+                        message: `Field "${key}" is required when "${typeKey}" = "${typeValue}"`,
+                        path: rootPath(key),
+                    };
+                    events.push(ev);
+                    issues.push(ev);
+                }
+            }
+        }
+        return { events, issues };
+    };
+}

package/dist/core/boundary-rules/date-range.js

@@ -0,0 +1,39 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | Date Range
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates that a start and end date form a proper
+ *                  chronological range. Emits an error when the start occurs
+ *                  after the end.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { rootPath } from '../field-path';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Validates that a start/end date pair forms a proper chronological range.
+ * Emits an error when both fields are dates and the start occurs after the end.
+ */
+export function dateRange(startKey, endKey) {
+    return ({ fields }) => {
+        const events = [];
+        const issues = [];
+        const start = fields[startKey]?.final;
+        const end = fields[endKey]?.final;
+        if (start instanceof Date && end instanceof Date && start > end) {
+            const ev = {
+                phase: 'decide',
+                kind: 'error',
+                code: 'boundary.does.require-date-range',
+                message: `"${startKey}" must be before "${endKey}"`,
+                path: rootPath(),
+            };
+            events.push(ev);
+            issues.push(ev);
+        }
+        return { events, issues };
+    };
+}

package/dist/core/boundary-rules/index.js

@@ -0,0 +1,21 @@
+/**
+ * ----------------------------------------------------------------------------
+ *  Boundary Rules | Barrel File
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Re‑exports shared boundary rules to provide a stable,
+ *                  minimal entry point for internal consumers. This file
+ *                  exposes no logic of its own.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Boundary Rules                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { atMostOne } from './at-most-one';
+export { conditionallyRequired } from './conditionally-required';
+export { dateRange } from './date-range';
+export { mutuallyExclusive } from './mutually-exclusive';
+export { noUnknownFields } from './no-unknown-fields';
+export { requireAll } from './require-all';
+export { requireOne } from './require-one';

package/dist/core/boundary-rules/mutually-exclusive.js

@@ -0,0 +1,38 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | Mutually Exclusive
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Enforces that two fields cannot both be accepted. If both
+ *                  appear, a mutual‑exclusion boundary error is produced.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { rootPath } from '../field-path';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Enforces mutual exclusion between two fields. If both fields are accepted,
+ * a boundary‑level error is emitted indicating the conflict.
+ */
+export function mutuallyExclusive(a, b) {
+    return ({ fields }) => {
+        const events = [];
+        const issues = [];
+        const ra = fields[a];
+        const rb = fields[b];
+        if (ra?.decision?.code === 'accept' && rb?.decision?.code === 'accept') {
+            const ev = {
+                phase: 'decide',
+                kind: 'error',
+                code: 'boundary.does.mutual-exclusion',
+                message: `Fields "${a}" and "${b}" cannot both be present`,
+                path: rootPath(),
+            };
+            events.push(ev);
+            issues.push(ev);
+        }
+        return { events, issues };
+    };
+}

package/dist/core/boundary-rules/no-unknown-fields.js

@@ -0,0 +1,39 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | No Unknown Fields
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures that only explicitly allowed fields appear in the
+ *                  boundary input. Any unknown key results in a boundary error.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { rootPath } from '../field-path';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Ensures that only the explicitly allowed fields appear in the boundary
+ * input. Any field not listed is treated as an unknown key and produces a
+ * boundary‑level error.
+ */
+export function noUnknownFields(...allowed) {
+    return ({ fields }) => {
+        const events = [];
+        const issues = [];
+        for (const key of Object.keys(fields)) {
+            if (!allowed.includes(key)) {
+                const ev = {
+                    phase: 'decide',
+                    kind: 'error',
+                    code: 'boundary.cannot.allow-unknown',
+                    message: `Unknown field "${key}"`,
+                    path: rootPath(key),
+                };
+                events.push(ev);
+                issues.push(ev);
+            }
+        }
+        return { events, issues };
+    };
+}