@clementine-solutions/jane-io 1.0.0 → 1.0.2

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.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ----------------------------------------------------------------------------
+ * 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 type { BoundaryRule } from '../shapes';
+/**
+ * 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 declare function atMostOne(...keys: string[]): BoundaryRule;

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.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ----------------------------------------------------------------------------
+ * 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 type { BoundaryRule } from '../shapes';
+/**
+ * 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 declare function conditionallyRequired(typeKey: string, typeValue: unknown, ...required: string[]): BoundaryRule;

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.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ----------------------------------------------------------------------------
+ * 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 type { BoundaryRule } from '../shapes';
+/**
+ * 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 declare function dateRange(startKey: string, endKey: string): BoundaryRule;

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.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ----------------------------------------------------------------------------
+ *  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
+ * ----------------------------------------------------------------------------
+ */
+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/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.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ----------------------------------------------------------------------------
+ * 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 type { BoundaryRule } from '../shapes';
+/**
+ * Enforces mutual exclusion between two fields. If both fields are accepted,
+ * a boundary‑level error is emitted indicating the conflict.
+ */
+export declare function mutuallyExclusive(a: string, b: string): BoundaryRule;

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.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ----------------------------------------------------------------------------
+ * 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 type { BoundaryRule } from '../shapes';
+/**
+ * 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 declare function noUnknownFields(...allowed: string[]): BoundaryRule;

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 };
+    };
+}

package/dist/core/boundary-rules/require-all.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | Require All
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Requires that all specified fields be present and accepted.
+ *                  Missing or rejected fields each produce a boundary error.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { BoundaryRule } from '../shapes';
+/**
+ * Requires that all specified fields be present and accepted. Any missing or
+ * rejected field results in a boundary‑level error for that key.
+ */
+export declare function requireAll(...keys: string[]): BoundaryRule;

package/dist/core/boundary-rules/require-all.js

@@ -0,0 +1,39 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | Require All
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Requires that all specified fields be present and accepted.
+ *                  Missing or rejected fields each produce a boundary error.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { rootPath } from '../field-path';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Requires that all specified fields be present and accepted. Any missing or
+ * rejected field results in a boundary‑level error for that key.
+ */
+export function requireAll(...keys) {
+    return ({ fields }) => {
+        const events = [];
+        const issues = [];
+        for (const key of keys) {
+            const r = fields[key];
+            if (!r || r.decision?.code !== 'accept') {
+                const ev = {
+                    phase: 'decide',
+                    kind: 'error',
+                    code: 'boundary.does.require-all',
+                    message: `Field "${key}" is required`,
+                    path: rootPath(key),
+                };
+                events.push(ev);
+                issues.push(ev);
+            }
+        }
+        return { events, issues };
+    };
+}

package/dist/core/boundary-rules/require-one.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | Require One
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Requires that at least one of the specified fields be
+ *                  accepted. If none are present, a single boundary error is
+ *                  emitted.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { BoundaryRule } from '../shapes';
+/**
+ * Requires that at least one of the specified fields be present and accepted.
+ * If none are provided, a single boundary‑level error is emitted.
+ */
+export declare function requireOne(...keys: string[]): BoundaryRule;

package/dist/core/boundary-rules/require-one.js

@@ -0,0 +1,41 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | Require One
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Requires that at least one of the specified fields be
+ *                  accepted. If none are present, a single boundary error is
+ *                  emitted.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { rootPath } from '../field-path';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Requires that at least one of the specified fields be present and accepted.
+ * If none are provided, a single boundary‑level error is emitted.
+ */
+export function requireOne(...keys) {
+    return ({ fields }) => {
+        const events = [];
+        const issues = [];
+        const ok = keys.some((key) => {
+            const r = fields[key];
+            return r && r.decision?.code === 'accept';
+        });
+        if (!ok) {
+            const ev = {
+                phase: 'decide',
+                kind: 'error',
+                code: 'boundary.does.require-one',
+                message: `At least one of [${keys.join(', ')}] is required`,
+                path: rootPath(),
+            };
+            events.push(ev);
+            issues.push(ev);
+        }
+        return { events, issues };
+    };
+}

package/dist/core/common/events.d.ts

@@ -0,0 +1,37 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Common | Events
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shared event types, factories, and helpers used across all
+ *                  pipeline stages. These modules define how Jane records and
+ *                  communicates observable facts during execution.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { EventCode, EventKind, FieldPath, JaneEvent, PipelinePhase } from '../shapes';
+/**
+ * Creates a frozen JaneEvent with consistent metadata.
+ *
+ * This factory centralizes event construction so all stages emit the same
+ * shape: stable identifiers, optional context, and a metadata block that
+ * tooling can rely on. Callers provide only the facts; the factory attaches
+ * timestamps and prepares the object for safe sharing across the pipeline.
+ *
+ * The returned event is immutable to prevent accidental mutation during
+ * scan, parse, normalize, validate, boundary, or policy execution.
+ */
+export declare function createEvent(phase: PipelinePhase, kind: EventKind, code: EventCode, path?: FieldPath, message?: string, userMessage?: string, meta?: Record<string, unknown>): JaneEvent;
+/**
+ * Structural type guard for JaneEvent.
+ *
+ * This check verifies that a value has the minimal shape required for an
+ * event: a valid phase, kind, code, and optional context fields. It does not
+ * validate semantics or metadata—only that the object is structurally safe to
+ * treat as a JaneEvent inside the pipeline.
+ *
+ * The guard is intentionally strict and literal. It accepts only the phases
+ * and kinds defined here, ensuring that stray or misspelled values cannot
+ * enter policy, explain, or replay logic.
+ */
+export declare function isJaneEvent(value: unknown): value is JaneEvent;