@plures/praxis 1.4.0 → 2.0.0

package/dist/browser/chunk-ZEW4LJAJ.js

@@ -0,0 +1,353 @@
+// src/expectations/expectations.ts
+var Expectation = class {
+  name;
+  _conditions = [];
+  constructor(name) {
+    this.name = name;
+  }
+  /**
+   * Declare that this behavior should ONLY occur when a condition is true.
+   * If the condition is false, the behavior should NOT occur.
+   */
+  onlyWhen(condition) {
+    this._conditions.push({ description: condition, type: "onlyWhen" });
+    return this;
+  }
+  /**
+   * Declare that this behavior should NEVER occur under a given condition.
+   */
+  never(condition) {
+    this._conditions.push({ description: condition, type: "never" });
+    return this;
+  }
+  /**
+   * Declare that this behavior should ALWAYS have a certain property.
+   */
+  always(condition) {
+    this._conditions.push({ description: condition, type: "always" });
+    return this;
+  }
+  /** Get all declared conditions. */
+  get conditions() {
+    return this._conditions;
+  }
+};
+var ExpectationSet = class {
+  name;
+  description;
+  _expectations = [];
+  constructor(options) {
+    this.name = options.name;
+    this.description = options.description ?? "";
+  }
+  /** Add an expectation to the set. */
+  add(expectation) {
+    this._expectations.push(expectation);
+    return this;
+  }
+  /** Get all expectations in this set. */
+  get expectations() {
+    return this._expectations;
+  }
+  /** Number of expectations. */
+  get size() {
+    return this._expectations.length;
+  }
+};
+function expectBehavior(name) {
+  return new Expectation(name);
+}
+function verify(registry, expectations) {
+  const rules = registry.getAllRules();
+  const constraints = registry.getAllConstraints();
+  const ruleIds = registry.getRuleIds();
+  const constraintIds = registry.getConstraintIds();
+  const allDescriptors = [...rules, ...constraints];
+  const expectationResults = [];
+  for (const exp of expectations.expectations) {
+    const result = verifyExpectation(exp, allDescriptors, ruleIds, constraintIds);
+    expectationResults.push(result);
+  }
+  const satisfied = expectationResults.filter((r) => r.status === "satisfied").length;
+  const violated = expectationResults.filter((r) => r.status === "violated").length;
+  const partial = expectationResults.filter((r) => r.status === "partial").length;
+  const allEdgeCases = expectationResults.flatMap((r) => r.edgeCases);
+  const allMitigations = expectationResults.flatMap((r) => r.mitigations);
+  return {
+    setName: expectations.name,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    status: violated > 0 ? "violated" : partial > 0 ? "partial" : "satisfied",
+    expectations: expectationResults,
+    summary: {
+      total: expectationResults.length,
+      satisfied,
+      violated,
+      partial
+    },
+    allEdgeCases,
+    allMitigations
+  };
+}
+function verifyExpectation(expectation, descriptors, ruleIds, _constraintIds) {
+  const conditionResults = [];
+  const edgeCases = [];
+  const mitigations = [];
+  const related = findRelatedDescriptors(expectation.name, descriptors);
+  for (const condition of expectation.conditions) {
+    const result = verifyCondition(condition, expectation.name, related, ruleIds);
+    conditionResults.push(result);
+    if (result.status === "unverifiable") {
+      edgeCases.push(`Cannot verify "${condition.description}" for "${expectation.name}" \u2014 no covering rule/contract found`);
+      mitigations.push(`Add a rule or constraint that explicitly covers: ${condition.description}`);
+    } else if (result.status === "violated") {
+      edgeCases.push(`"${expectation.name}" may fire incorrectly: ${condition.description}`);
+      mitigations.push(`Review rule logic for "${expectation.name}" regarding: ${condition.description}`);
+    }
+  }
+  const satisfiedCount = conditionResults.filter((r) => r.status === "satisfied").length;
+  const violatedCount = conditionResults.filter((r) => r.status === "violated").length;
+  const total = conditionResults.length;
+  let status;
+  if (total === 0) {
+    status = "satisfied";
+  } else if (violatedCount > 0) {
+    status = "violated";
+  } else if (satisfiedCount === total) {
+    status = "satisfied";
+  } else {
+    status = "partial";
+  }
+  return {
+    name: expectation.name,
+    status,
+    conditions: conditionResults,
+    edgeCases,
+    mitigations
+  };
+}
+function textOverlaps(a, b) {
+  const stopWords = /* @__PURE__ */ new Set([
+    "the",
+    "a",
+    "an",
+    "is",
+    "are",
+    "was",
+    "were",
+    "be",
+    "been",
+    "being",
+    "have",
+    "has",
+    "had",
+    "do",
+    "does",
+    "did",
+    "will",
+    "would",
+    "could",
+    "should",
+    "may",
+    "might",
+    "shall",
+    "can",
+    "to",
+    "of",
+    "in",
+    "for",
+    "on",
+    "with",
+    "at",
+    "by",
+    "from",
+    "as",
+    "into",
+    "through",
+    "during",
+    "before",
+    "after",
+    "when",
+    "that",
+    "this",
+    "it",
+    "its",
+    "and",
+    "or",
+    "but",
+    "not",
+    "no",
+    "if",
+    "then",
+    "than",
+    "so",
+    "up",
+    "out",
+    "about",
+    "just",
+    "must"
+  ]);
+  const wordsA = a.toLowerCase().replace(/[^a-z0-9\s]/g, "").split(/\s+/).filter((w) => w.length > 2 && !stopWords.has(w));
+  const wordsB = b.toLowerCase().replace(/[^a-z0-9\s]/g, "").split(/\s+/).filter((w) => w.length > 2 && !stopWords.has(w));
+  if (wordsA.length === 0 || wordsB.length === 0) return false;
+  const matches = wordsA.filter(
+    (wa) => wordsB.some((wb) => wa.startsWith(wb.slice(0, 4)) || wb.startsWith(wa.slice(0, 4)))
+  );
+  const minWords = Math.min(wordsA.length, wordsB.length);
+  return matches.length >= Math.max(1, Math.ceil(minWords * 0.5));
+}
+function verifyCondition(condition, expectationName, relatedDescriptors, _ruleIds) {
+  if (relatedDescriptors.length === 0) {
+    return {
+      condition,
+      status: "unverifiable",
+      explanation: `No rules or constraints found related to "${expectationName}"`,
+      relatedRules: []
+    };
+  }
+  const relatedIds = relatedDescriptors.map((d) => d.id);
+  const condLower = condition.description.toLowerCase();
+  const matches = (target) => target.toLowerCase().includes(condLower) || condLower.includes(target.toLowerCase()) || textOverlaps(condLower, target);
+  switch (condition.type) {
+    case "onlyWhen": {
+      const coveringRule = relatedDescriptors.find(
+        (d) => d.contract?.examples.some(
+          (ex) => matches(ex.given) || matches(ex.when)
+        ) || d.contract?.invariants.some((inv) => matches(inv))
+      );
+      if (coveringRule) {
+        return {
+          condition,
+          status: "satisfied",
+          explanation: `Rule "${coveringRule.id}" contract covers precondition: ${condition.description}`,
+          relatedRules: relatedIds
+        };
+      }
+      const descMatch = relatedDescriptors.find((d) => matches(d.description));
+      if (descMatch) {
+        return {
+          condition,
+          status: "satisfied",
+          explanation: `Rule "${descMatch.id}" description addresses: ${condition.description}`,
+          relatedRules: relatedIds
+        };
+      }
+      return {
+        condition,
+        status: "unverifiable",
+        explanation: `No rule contract explicitly covers the precondition: ${condition.description}`,
+        relatedRules: relatedIds
+      };
+    }
+    case "never": {
+      const preventingDescriptor = relatedDescriptors.find(
+        (d) => d.contract?.invariants.some((inv) => matches(inv)) || d.contract?.examples.some(
+          (ex) => (matches(ex.given) || matches(ex.when)) && (ex.then.toLowerCase().includes("retract") || ex.then.toLowerCase().includes("fail") || ex.then.toLowerCase().includes("violation") || ex.then.toLowerCase().includes("skip") || ex.then.toLowerCase().includes("block") || ex.then.toLowerCase().includes("no "))
+        ) || d.contract?.behavior.toLowerCase().includes("block") || d.contract?.behavior.toLowerCase().includes("prevent")
+      );
+      if (preventingDescriptor) {
+        return {
+          condition,
+          status: "satisfied",
+          explanation: `Constraint/rule "${preventingDescriptor.id}" prevents: ${condition.description}`,
+          relatedRules: relatedIds
+        };
+      }
+      return {
+        condition,
+        status: "unverifiable",
+        explanation: `No rule or constraint explicitly prevents: ${condition.description}`,
+        relatedRules: relatedIds
+      };
+    }
+    case "always": {
+      const guaranteeing = relatedDescriptors.find(
+        (d) => d.contract?.invariants.some((inv) => matches(inv)) || d.contract?.behavior && matches(d.contract.behavior)
+      );
+      if (guaranteeing) {
+        return {
+          condition,
+          status: "satisfied",
+          explanation: `Rule "${guaranteeing.id}" guarantees: ${condition.description}`,
+          relatedRules: relatedIds
+        };
+      }
+      const exampleMatch = relatedDescriptors.find(
+        (d) => d.contract?.examples.some((ex) => matches(ex.then))
+      );
+      if (exampleMatch) {
+        return {
+          condition,
+          status: "satisfied",
+          explanation: `Rule "${exampleMatch.id}" example demonstrates: ${condition.description}`,
+          relatedRules: relatedIds
+        };
+      }
+      return {
+        condition,
+        status: "unverifiable",
+        explanation: `No rule contract guarantees: ${condition.description}`,
+        relatedRules: relatedIds
+      };
+    }
+  }
+}
+function findRelatedDescriptors(expectationName, descriptors) {
+  const nameLower = expectationName.toLowerCase();
+  const nameParts = nameLower.split(/[-_./\s]+/);
+  return descriptors.filter((d) => {
+    const idLower = d.id.toLowerCase();
+    const descLower = d.description.toLowerCase();
+    const behaviorLower = d.contract?.behavior?.toLowerCase() ?? "";
+    if (idLower.includes(nameLower) || nameLower.includes(idLower)) return true;
+    if (descLower.includes(nameLower)) return true;
+    if (behaviorLower.includes(nameLower)) return true;
+    const minParts = Math.min(2, nameParts.length);
+    const matchingParts = nameParts.filter(
+      (part) => part.length > 2 && (idLower.includes(part) || descLower.includes(part) || behaviorLower.includes(part))
+    );
+    if (matchingParts.length >= minParts) return true;
+    if (d.eventTypes) {
+      const eventStr = Array.isArray(d.eventTypes) ? d.eventTypes.join(" ") : d.eventTypes;
+      if (eventStr.toLowerCase().includes(nameLower)) return true;
+    }
+    return false;
+  });
+}
+function formatVerificationReport(report) {
+  const lines = [];
+  const icon = report.status === "satisfied" ? "\u2705" : report.status === "partial" ? "\u{1F7E1}" : "\u{1F534}";
+  lines.push(`${icon} Expectations: ${report.setName} \u2014 ${report.status.toUpperCase()}`);
+  lines.push(`   ${report.summary.satisfied}/${report.summary.total} satisfied, ${report.summary.violated} violated, ${report.summary.partial} partial`);
+  lines.push("");
+  for (const exp of report.expectations) {
+    const expIcon = exp.status === "satisfied" ? "\u2705" : exp.status === "partial" ? "\u{1F7E1}" : "\u{1F534}";
+    lines.push(`${expIcon} ${exp.name}`);
+    for (const cond of exp.conditions) {
+      const condIcon = cond.status === "satisfied" ? "  \u2713" : cond.status === "violated" ? "  \u2717" : "  ?";
+      lines.push(`${condIcon} [${cond.condition.type}] ${cond.condition.description}`);
+      lines.push(`      ${cond.explanation}`);
+    }
+    if (exp.edgeCases.length > 0) {
+      lines.push("  Edge cases:");
+      for (const ec of exp.edgeCases) {
+        lines.push(`    \u26A0\uFE0F ${ec}`);
+      }
+    }
+    lines.push("");
+  }
+  if (report.allMitigations.length > 0) {
+    lines.push("Suggested mitigations:");
+    for (const m of report.allMitigations) {
+      lines.push(`  \u{1F4A1} ${m}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export {
+  Expectation,
+  ExpectationSet,
+  expectBehavior,
+  verify,
+  formatVerificationReport
+};

package/dist/browser/{engine-YIEGSX7U.js → engine-3B5WJPGT.js}

@@ -1,7 +1,8 @@
 import {
   LogicEngine,
   createPraxisEngine
-} from "./chunk-MJK3IYTJ.js";
+} from "./chunk-JZDJU2DO.js";
+import "./chunk-IG5BJ2MT.js";
 export {
   LogicEngine,
   createPraxisEngine

package/dist/browser/expectations/index.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Expectations DSL — Types
+ *
+ * Types for declaring behavioral expectations about rules.
+ * Expectations replace traditional tests with behavioral declarations.
+ */
+/** A condition under which a behavior should or should not occur. */
+interface ExpectationCondition {
+    /** Human-readable condition description */
+    description: string;
+    /** Type of expectation */
+    type: 'onlyWhen' | 'never' | 'always';
+}
+/** Verification status for a single expectation condition. */
+type ConditionStatus = 'satisfied' | 'violated' | 'unverifiable';
+/** Detailed result for a single condition check. */
+interface ConditionResult {
+    condition: ExpectationCondition;
+    status: ConditionStatus;
+    /** Explanation of how the condition was verified or why it couldn't be */
+    explanation: string;
+    /** Related rule IDs that informed this check */
+    relatedRules: string[];
+}
+/** Verification result for a single Expectation. */
+interface ExpectationResult {
+    /** The expectation name/ID */
+    name: string;
+    /** Overall status: satisfied if ALL conditions pass */
+    status: 'satisfied' | 'violated' | 'partial';
+    /** Per-condition results */
+    conditions: ConditionResult[];
+    /** Edge cases discovered */
+    edgeCases: string[];
+    /** Suggested mitigations for violated/partial expectations */
+    mitigations: string[];
+}
+/** Full verification report for an ExpectationSet. */
+interface VerificationReport {
+    /** Set name */
+    setName: string;
+    /** Timestamp of verification */
+    timestamp: string;
+    /** Overall status: satisfied if ALL expectations are satisfied */
+    status: 'satisfied' | 'violated' | 'partial';
+    /** Per-expectation results */
+    expectations: ExpectationResult[];
+    /** Summary stats */
+    summary: {
+        total: number;
+        satisfied: number;
+        violated: number;
+        partial: number;
+    };
+    /** All edge cases found across all expectations */
+    allEdgeCases: string[];
+    /** All mitigations suggested */
+    allMitigations: string[];
+}
+/** Options for creating an ExpectationSet */
+interface ExpectationSetOptions {
+    /** Name/domain for this set of expectations */
+    name: string;
+    /** Optional description */
+    description?: string;
+}
+/** Interface describing a rule or constraint for verification */
+interface VerifiableDescriptor {
+    id: string;
+    description: string;
+    eventTypes?: string | string[];
+    contract?: {
+        behavior: string;
+        examples: Array<{
+            given: string;
+            when: string;
+            then: string;
+        }>;
+        invariants: string[];
+        ruleId: string;
+    };
+}
+/** Registry-like interface for verification */
+interface VerifiableRegistry {
+    getAllRules(): VerifiableDescriptor[];
+    getAllConstraints(): VerifiableDescriptor[];
+    getRuleIds(): string[];
+    getConstraintIds(): string[];
+}
+
+/**
+ * Expectations DSL — Core
+ *
+ * Behavioral declarations for Praxis rules. Instead of writing test
+ * assertions, you declare what behaviors you expect from your system.
+ *
+ * @example
+ * ```ts
+ * import { expectBehavior, ExpectationSet, verify } from '@plures/praxis/expectations';
+ *
+ * const expectations = new ExpectationSet({ name: 'settings' });
+ *
+ * expectations.add(
+ *   expectBehavior('settings-saved-toast')
+ *     .onlyWhen('settings.diff is non-empty')
+ *     .never('when settings panel opens without changes')
+ *     .never('when save fails')
+ *     .always('includes which settings changed')
+ * );
+ *
+ * const report = verify(registry, expectations);
+ * ```
+ */
+
+/**
+ * A behavioral expectation declaration.
+ *
+ * Chainable API for declaring conditions under which a behavior
+ * should or should not occur.
+ */
+declare class Expectation {
+    readonly name: string;
+    private _conditions;
+    constructor(name: string);
+    /**
+     * Declare that this behavior should ONLY occur when a condition is true.
+     * If the condition is false, the behavior should NOT occur.
+     */
+    onlyWhen(condition: string): this;
+    /**
+     * Declare that this behavior should NEVER occur under a given condition.
+     */
+    never(condition: string): this;
+    /**
+     * Declare that this behavior should ALWAYS have a certain property.
+     */
+    always(condition: string): this;
+    /** Get all declared conditions. */
+    get conditions(): ReadonlyArray<ExpectationCondition>;
+}
+/**
+ * A collection of expectations for a specific domain.
+ */
+declare class ExpectationSet {
+    readonly name: string;
+    readonly description: string;
+    private _expectations;
+    constructor(options: ExpectationSetOptions);
+    /** Add an expectation to the set. */
+    add(expectation: Expectation): this;
+    /** Get all expectations in this set. */
+    get expectations(): ReadonlyArray<Expectation>;
+    /** Number of expectations. */
+    get size(): number;
+}
+/**
+ * Create a new behavioral expectation.
+ *
+ * @example
+ * ```ts
+ * expectBehavior('settings-saved-toast')
+ *   .onlyWhen('settings.diff is non-empty')
+ *   .never('when save fails')
+ *   .always('includes which settings changed');
+ * ```
+ */
+declare function expectBehavior(name: string): Expectation;
+/**
+ * Verify expectations against a rule registry.
+ *
+ * Walks the rule graph to determine if expectations are satisfied,
+ * violated, or unverifiable given the registered rules and contracts.
+ */
+declare function verify(registry: VerifiableRegistry, expectations: ExpectationSet): VerificationReport;
+/**
+ * Format a verification report as human-readable text.
+ */
+declare function formatVerificationReport(report: VerificationReport): string;
+
+export { type ConditionResult, type ConditionStatus, Expectation, type ExpectationCondition, type ExpectationResult, ExpectationSet, type ExpectationSetOptions, type VerifiableDescriptor, type VerifiableRegistry, type VerificationReport, expectBehavior, formatVerificationReport, verify };

package/dist/browser/expectations/index.js

@@ -0,0 +1,14 @@
+import {
+  Expectation,
+  ExpectationSet,
+  expectBehavior,
+  formatVerificationReport,
+  verify
+} from "../chunk-ZEW4LJAJ.js";
+export {
+  Expectation,
+  ExpectationSet,
+  expectBehavior,
+  formatVerificationReport,
+  verify
+};

package/dist/browser/factory/index.d.ts

@@ -0,0 +1,150 @@
+import { d as PraxisModule } from '../rules-BaWMqxuG.js';
+import '../rule-result-DcXWe9tn.js';
+
+/**
+ * Praxis Rules Factory — Types
+ *
+ * Configuration types for predefined rule module factories.
+ */
+type SanitizationType = 'sql-injection' | 'xss' | 'path-traversal' | 'command-injection';
+interface InputRulesConfig {
+    /** Sanitization checks to apply */
+    sanitize?: SanitizationType[];
+    /** Maximum input length (0 = unlimited) */
+    maxLength?: number;
+    /** Whether the input is required (non-empty) */
+    required?: boolean;
+    /** Custom field name for facts/events (default: 'input') */
+    fieldName?: string;
+}
+interface ToastRulesConfig {
+    /** Only show toast if there's a meaningful diff */
+    requireDiff?: boolean;
+    /** Auto-dismiss after N milliseconds (0 = no auto-dismiss) */
+    autoDismissMs?: number;
+    /** Prevent duplicate toasts with same message */
+    deduplicate?: boolean;
+}
+interface FormRulesConfig {
+    /** Validate fields on blur */
+    validateOnBlur?: boolean;
+    /** Gate form submission on validation passing */
+    submitGate?: boolean;
+    /** Custom form name for namespacing facts */
+    formName?: string;
+}
+interface NavigationRulesConfig {
+    /** Warn/block navigation when form has unsaved changes */
+    dirtyGuard?: boolean;
+    /** Require authentication for navigation */
+    authRequired?: boolean;
+}
+interface DataRulesConfig {
+    /** Enable optimistic UI updates */
+    optimisticUpdate?: boolean;
+    /** Rollback optimistic updates on error */
+    rollbackOnError?: boolean;
+    /** Invalidate relevant caches on data change */
+    cacheInvalidation?: boolean;
+    /** Custom entity name for facts */
+    entityName?: string;
+}
+
+/**
+ * Praxis Rules Factory
+ *
+ * Predefined rule modules for common application patterns.
+ * Each factory returns a PraxisModule with rules, constraints, and contracts.
+ *
+ * @example
+ * ```ts
+ * import { inputRules, toastRules, formRules } from '@plures/praxis/factory';
+ *
+ * const registry = new PraxisRegistry();
+ * registry.registerModule(inputRules({ sanitize: ['xss', 'sql-injection'], required: true }));
+ * registry.registerModule(toastRules({ requireDiff: true, deduplicate: true }));
+ * registry.registerModule(formRules({ validateOnBlur: true, submitGate: true }));
+ * ```
+ */
+
+/** Context type for input rules. */
+interface InputContext {
+    input?: {
+        value?: string;
+        field?: string;
+    };
+}
+/**
+ * Create input validation rules module.
+ *
+ * Generates rules for sanitizing user input, enforcing length limits,
+ * and requiring non-empty values.
+ */
+declare function inputRules(config?: InputRulesConfig): PraxisModule<InputContext>;
+/** Context type for toast rules. */
+interface ToastContext {
+    diff?: Record<string, unknown> | null;
+    toasts?: Array<{
+        message: string;
+        id: string;
+    }>;
+}
+/**
+ * Create truthful toast notification rules.
+ *
+ * Generates rules that ensure toasts only appear with meaningful content,
+ * auto-dismiss after a timeout, and avoid duplicates.
+ */
+declare function toastRules(config?: ToastRulesConfig): PraxisModule<ToastContext>;
+/** Context type for form rules. */
+interface FormContext {
+    form?: {
+        fields?: Record<string, {
+            value: unknown;
+            error?: string;
+            touched?: boolean;
+        }>;
+        valid?: boolean;
+        dirty?: boolean;
+        submitting?: boolean;
+    };
+}
+/**
+ * Create form lifecycle rules.
+ *
+ * Generates rules for field validation on blur, submit gating,
+ * and form state management.
+ */
+declare function formRules(config?: FormRulesConfig): PraxisModule<FormContext>;
+/** Context type for navigation rules. */
+interface NavigationContext {
+    dirty?: boolean;
+    authenticated?: boolean;
+    route?: string;
+}
+/**
+ * Create route protection rules.
+ *
+ * Generates rules for dirty-data navigation guards and
+ * authentication-required route protection.
+ */
+declare function navigationRules(config?: NavigationRulesConfig): PraxisModule<NavigationContext>;
+/** Context type for data rules. */
+interface DataContext {
+    pending?: Record<string, {
+        original: unknown;
+        optimistic: unknown;
+    }>;
+    cache?: Record<string, {
+        data: unknown;
+        timestamp: number;
+    }>;
+}
+/**
+ * Create data lifecycle rules.
+ *
+ * Generates rules for optimistic updates, error rollback, and cache invalidation.
+ */
+declare function dataRules(config?: DataRulesConfig): PraxisModule<DataContext>;
+
+export { type DataRulesConfig, type FormRulesConfig, type InputRulesConfig, type NavigationRulesConfig, type SanitizationType, type ToastRulesConfig, dataRules, formRules, inputRules, navigationRules, toastRules };