@clementine-solutions/jane-io 1.0.0 → 1.0.2

package/dist/core/common/index.js

@@ -0,0 +1,31 @@
+/**
+ * ----------------------------------------------------------------------------
+ *  Common | Barrel File
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Re‑exports shared common modules to provide a stable,
+ *                  minimal entry point for internal consumers. This file
+ *                  exposes no logic of its own.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Events                                                                    *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { createEvent, isJaneEvent } from './events';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Fluent                                                                    *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { attachFluentParsers, attachFluentValidators, createJane, toJaneBoundaryResult, toJaneResult, } from './fluent';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Policy                                                                    *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { applyEscalate, applyOverride, boundaryPolicyDefault, boundaryPolicyLax, boundaryPolicyStrict, clampSeverityIndex, compileSeverityMap, decideEvent, defaultPolicy, laxPolicy, normalizePolicy, mergeBoundaryPolicies, policyDecision, resolveLevel, resolvePolicy, severityIndex, SEVERITY_ORDER, strictPolicy, } from './policy';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Utilities                                                                 *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { deepEqual, generateRunId, isObject, isPlainObject, isPrimitive, safeStringify, } from './utilities';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Wildcard                                                                  *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+export { compileWildcard, getCompiledWildcard, matchesWildcard } from './wildcard';

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

@@ -0,0 +1,170 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Common | Policy
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Core types and helpers for defining, normalizing, and
+ *                  resolving policies that guide how Jane interprets events
+ *                  across all pipeline stages.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { EventCode, EventKind, FieldPath, Policy, PolicyContext, PolicyOverrides, PipelineResult, PipelineMetadata, BoundaryDecideConfig } from '../shapes';
+import type { PolicyInput } from '../shapes/policy';
+/**
+ * Raises an event’s severity by the given number of levels.
+ *
+ * Escalation moves the severity index upward and clamps it to the valid
+ * range. This helper is used by policy transforms to harden events without
+ * altering their underlying meaning or code.
+ */
+export declare function applyEscalate(kind: EventKind, levels: number): EventKind;
+/**
+ * Lowers an event’s severity by the given number of levels.
+ *
+ * Override moves the severity index downward and clamps it to the valid
+ * range. This helper is used by policy transforms to soften events without
+ * changing their underlying meaning or code.
+ */
+export declare function applyOverride(kind: EventKind, levels: number): EventKind;
+/**
+ * Clamps a severity index to the valid range.
+ *
+ * Severity levels are stored as an ordered list. This helper ensures that
+ * arithmetic on the index—such as escalation or override—never produces an
+ * out‑of‑bounds value. No interpretation occurs here; it simply enforces the
+ * valid numeric range.
+ */
+export declare function clampSeverityIndex(i: number): number;
+/**
+ * Compiles a user‑supplied severity map into override/escalation deltas.
+ *
+ * Each entry expresses a desired target severity for an event code. This
+ * helper compares the target against the baseline severity (“error”) and
+ * converts the difference into numeric levels suitable for the override and
+ * escalate policy transforms.
+ *
+ * Negative deltas become override levels; positive deltas become escalation
+ * levels. No interpretation occurs here—this function only computes the
+ * distance between severities.
+ */
+export declare function compileSeverityMap(severity: Readonly<Partial<Record<EventCode, EventKind>>>): {
+    override: Readonly<Partial<Record<EventCode, number>>>;
+    escalate: Readonly<Partial<Record<EventCode, number>>>;
+};
+/**
+ * Creates a `decide`‑phase event.
+ *
+ * Decision events are emitted after validation when policy logic evaluates
+ * severity, overrides, escalation, and boundary rules. This helper ensures
+ * all decision events share a consistent shape and metadata.
+ */
+export declare const decideEvent: (kind: EventKind, code: EventCode, path: FieldPath, message?: string, userMessage?: string, meta?: Record<string, unknown>) => import("../shapes").JaneEvent;
+/**
+ * The baseline policy used when no user configuration is provided.
+ *
+ * Moderate mode applies no automatic rejects, reviews, or severity transforms.
+ * Scan and analysis features are disabled, and no structural exceptions are
+ * granted. This preset defines Jane’s neutral, predictable behavior and serves
+ * as the foundation for all policy merging.
+ */
+export declare const defaultPolicy: Policy;
+/**
+ * A permissive policy preset optimized for developer‑friendly behavior.
+ *
+ * Lax mode applies no rejects or reviews, downgrades all severities by one
+ * level via a wildcard override, disables scan and analysis features, and
+ * allows structural exceptions for bigint, map, and set. This preset favors
+ * flexibility and forgiveness during development and experimentation.
+ */
+export declare const laxPolicy: Policy;
+/**
+ * A strict boundary preset that rejects on any issue.
+ *
+ * This configuration forces boundary acceptance to “strict”, applies a
+ * wildcard reject to treat every issue as fatal, and hides nothing from the
+ * event or issue streams. It provides the most conservative, compliance‑grade
+ * boundary behavior.
+ */
+export declare const boundaryPolicyStrict: BoundaryDecideConfig;
+/**
+ * The neutral boundary preset used when no boundary configuration is supplied.
+ *
+ * Default mode requires all fields to be accepted, applies no reject or review
+ * patterns, and hides nothing from the event or issue streams. It provides a
+ * transparent, assumption‑free baseline for boundary evaluation.
+ */
+export declare const boundaryPolicyDefault: BoundaryDecideConfig;
+/**
+ * A permissive boundary preset that accepts if any field succeeds.
+ *
+ * Lax mode ignores all boundary‑level events, hides both events and issues
+ * from the result, and applies no reject or review patterns. It provides a
+ * forgiving, low‑visibility boundary configuration suited for exploratory or
+ * developer‑focused workflows.
+ */
+export declare const boundaryPolicyLax: BoundaryDecideConfig;
+/**
+ * A maximum‑scrutiny policy preset for safety‑critical pipelines.
+ *
+ * Strict mode enables scan, rejects high‑risk conditions outright, escalates
+ * all severities by one level, and requires review for large or complex
+ * structures. All analysis features are enabled, and no structural exceptions
+ * are granted. This preset enforces the most conservative, defensive behavior.
+ */
+export declare const strictPolicy: Policy;
+export declare function mergeBoundaryPolicies(base: Partial<BoundaryDecideConfig> | undefined, ...overrides: Array<Partial<BoundaryDecideConfig> | undefined>): BoundaryDecideConfig;
+/**
+ * Merges a base policy with user‑supplied input into a final, normalized policy.
+ *
+ * This function applies field‑by‑field overrides, compiles public severity
+ * settings into internal override/escalation maps, and merges reject/review/warn
+ * patterns in a predictable order. It preserves all unspecified fields from the
+ * base policy and never introduces defaults beyond those already present.
+ */
+export declare function normalizePolicy(base: Policy, input?: PolicyInput): Policy;
+/**
+ * Resolves a numeric level for an event code from a sparse lookup table.
+ *
+ * Exact matches take priority. If none exist, wildcard patterns in the table
+ * are tested in insertion order using their compiled regular expressions.
+ * Returns the matched level or `undefined` when no pattern applies.
+ */
+export declare function resolveLevel(code: EventCode, table: Readonly<Partial<Record<string, number>>>): number | undefined;
+/**
+ * Applies policy transforms to events and produces the final pipeline decision.
+ *
+ * This function reshapes events using override, escalation, and warn rules,
+ * derives issues from the resulting severities, and evaluates reject/review
+ * patterns according to the active policy mode. It returns the full pipeline
+ * result with shaped events, extracted issues, and a final accept/review/reject
+ * decision. No data is modified—only event interpretation changes.
+ */
+export declare function policyDecision<T>(ctx: PolicyContext<T>, metadata: PipelineMetadata): PipelineResult<T>;
+/**
+ * Resolves the effective policy by merging defaults, explicit policy, and
+ * fluent‑API overrides.
+ *
+ * The default and explicit policies are combined first, then builder overrides
+ * are applied field‑by‑field with strict precedence. Only fields exposed to the
+ * fluent API are overrideable; all other structure is taken directly from the
+ * merged base. No inference or normalization occurs here—this function performs
+ * a final, literal merge for pipeline execution.
+ */
+export declare function resolvePolicy(defaultPolicy: Policy, janePolicy: Policy | undefined, overrides: PolicyOverrides | undefined): Policy;
+/**
+ * Returns the numeric index for a severity kind.
+ *
+ * Event kinds are stored in a fixed ordered list. Unknown kinds fall back to
+ * index 0 to guarantee a safe, deterministic baseline for all severity math.
+ * No interpretation occurs here—this is a simple lookup with a fallback.
+ */
+export declare function severityIndex(kind: EventKind): number;
+/**
+ * Fixed severity ladder from least to most severe.
+ *
+ * Policies, escalation math, and explain output rely on this exact ordering.
+ * Changing it is a breaking change because severity indices are used
+ * throughout the pipeline.
+ */
+export declare const SEVERITY_ORDER: readonly EventKind[];