fast-publicodes 0.0.0 → 1.0.0

package/dist/index.js

@@ -0,0 +1,22 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import * as wasm from "../wasm/fast_publicodes.js";
+import { useBinding } from "./binding.js";
+useBinding(loadAddon() ?? loadWasm());
+/** The addon built for this platform, if one is installed. */
+function loadAddon() {
+    try {
+        return createRequire(import.meta.url)("../native/index.cjs");
+    }
+    catch {
+        return undefined;
+    }
+}
+function loadWasm() {
+    wasm.initSync({
+        module: readFileSync(new URL("../wasm/fast_publicodes_bg.wasm", import.meta.url)),
+    });
+    return wasm;
+}
+export * from "./api.js";
+export { default } from "./api.js";

package/dist/options.d.ts

@@ -0,0 +1,22 @@
+import type { EngineOptions } from "./types.js";
+/** The options as `publicodes` resolves them, then reads them as conditions. */
+export declare function resolveOptions(options: EngineOptions): {
+    strict: {
+        situation: boolean;
+        noOrphanRule: boolean;
+        noCycleRuntime: boolean;
+        checkPossibleValues: boolean;
+    };
+    warn: {
+        cyclicReferences: boolean;
+        experimentalRules: boolean;
+        unitConversion: boolean;
+        deprecatedSyntax: boolean;
+        situationIssues: boolean;
+    };
+    flag: {
+        filterNotApplicablePossibilities: boolean;
+        automaticNamespaceDisabling: boolean;
+    };
+    inversionMaxIterations: number | null;
+};

package/dist/options.js

@@ -0,0 +1,58 @@
+/** The options as `publicodes` resolves them, then reads them as conditions. */
+export function resolveOptions(options) {
+    const { strict, warn, flag } = options;
+    const strictOptions = {
+        situation: true,
+        noOrphanRule: true,
+        noCycleRuntime: false,
+        checkPossibleValues: false,
+        ...(typeof strict === "boolean"
+            ? {
+                situation: strict,
+                noOrphanRule: options.allowOrphanRules === true ? false : strict,
+                checkPossibleValues: strict,
+                noCycleRuntime: strict,
+            }
+            : typeof strict === "object"
+                ? strict
+                : {}),
+    };
+    const warnOptions = {
+        cyclicReferences: true,
+        experimentalRules: true,
+        unitConversion: true,
+        deprecatedSyntax: true,
+        situationIssues: true,
+        ...(typeof warn === "boolean"
+            ? {
+                cyclicReferences: warn,
+                experimentalRules: warn,
+                unitConversion: warn,
+            }
+            : typeof warn === "object"
+                ? warn
+                : {}),
+    };
+    const iterations = options
+        .inversionMaxIterations;
+    return {
+        strict: {
+            situation: Boolean(strictOptions.situation),
+            noOrphanRule: Boolean(strictOptions.noOrphanRule),
+            noCycleRuntime: Boolean(strictOptions.noCycleRuntime),
+            checkPossibleValues: Boolean(strictOptions.checkPossibleValues),
+        },
+        warn: {
+            cyclicReferences: Boolean(warnOptions.cyclicReferences),
+            experimentalRules: Boolean(warnOptions.experimentalRules),
+            unitConversion: Boolean(warnOptions.unitConversion),
+            deprecatedSyntax: Boolean(warnOptions.deprecatedSyntax),
+            situationIssues: Boolean(warnOptions.situationIssues),
+        },
+        flag: {
+            filterNotApplicablePossibilities: Boolean(flag?.filterNotApplicablePossibilities ?? false),
+            automaticNamespaceDisabling: Boolean(flag?.automaticNamespaceDisabling ?? true),
+        },
+        inversionMaxIterations: iterations == null ? null : Number(iterations),
+    };
+}

package/dist/ruleUtils.d.ts

@@ -0,0 +1,19 @@
+import type { RuleNode } from "./types.js";
+type Rules = Record<string, Pick<RuleNode, "private" | "rawNode" | "title"> | undefined>;
+export declare const nameLeaf: (dottedName: string) => string | undefined;
+export declare const encodeRuleName: (dottedName: string) => string;
+export declare const decodeRuleName: (dottedName: string) => string;
+export declare const ruleParent: (dottedName: string) => string;
+export declare const contextNameToDottedName: (contextName: string) => string;
+/** The ancestors of a rule, nearest first. */
+export declare function ruleParents(dottedName: string): string[];
+export declare const getChildrenRules: (rules: Rules, dottedName: string) => string[];
+export declare function findCommonAncestor(dottedName1: string, dottedName2: string): string;
+export declare function isAccessible(rules: Rules, contextName: string, name: string): boolean;
+export declare function isExperimental(rules: Rules, name: string): boolean;
+export declare function disambiguateReference(rules: Rules, referencedFrom: string | undefined, partialName: string): string;
+export declare function ruleWithDedicatedDocumentationPage(rule: {
+    virtualRule?: boolean;
+    type?: string;
+}): boolean;
+export {};

package/dist/ruleUtils.js

@@ -0,0 +1,78 @@
+import { PublicodesError } from "./error.js";
+const splitName = (name) => name.split(" . ");
+const joinName = (parts) => parts.join(" . ");
+export const nameLeaf = (dottedName) => splitName(dottedName).at(-1);
+export const encodeRuleName = (dottedName) => dottedName
+    ?.replace(/\s\.\s/g, "/")
+    .replace(/-/g, "‑")
+    .replace(/\s/g, "-");
+export const decodeRuleName = (dottedName) => dottedName.replace(/\//g, " . ").replace(/-/g, " ").replace(/‑/g, "-");
+export const ruleParent = (dottedName) => joinName(splitName(dottedName).slice(0, -1));
+export const contextNameToDottedName = (contextName) => contextName.endsWith("$SITUATION") ? ruleParent(contextName) : contextName;
+/** The ancestors of a rule, nearest first. */
+export function ruleParents(dottedName) {
+    const parts = splitName(dottedName).slice(0, -1);
+    return parts.map((_, i) => joinName(parts.slice(0, i + 1))).reverse();
+}
+export const getChildrenRules = (rules, dottedName) => Object.keys(rules).filter((name) => name.startsWith(dottedName) &&
+    splitName(name).length === splitName(dottedName).length + 1);
+export function findCommonAncestor(dottedName1, dottedName2) {
+    const parts1 = splitName(dottedName1);
+    const parts2 = splitName(dottedName2);
+    const index = parts1.findIndex((part, i) => parts2[i] !== part);
+    return index === -1 ? dottedName1 : joinName(parts1.slice(0, index));
+}
+function exists(rules, name) {
+    if (!(name in rules)) {
+        throw new PublicodesError("InternalError", `La règle "${name}" n'existe pas`, {
+            dottedName: name,
+        });
+    }
+}
+export function isAccessible(rules, contextName, name) {
+    exists(rules, name);
+    const commonAncestor = findCommonAncestor(contextName, name);
+    const parents = [name, ...ruleParents(name), ""];
+    const checked = parents.slice(0, Math.max(parents.indexOf(commonAncestor) - 1, 0));
+    return checked.every((parent) => !(parent in rules) || rules[parent]?.private === false);
+}
+export function isExperimental(rules, name) {
+    exists(rules, name);
+    return [name, ...ruleParents(name)].some((parent) => parent in rules && rules[parent]?.rawNode?.experimental === "oui");
+}
+const withContext = (context, name) => context ? `${context} . ${name}` : name;
+export function disambiguateReference(rules, referencedFrom = "", partialName) {
+    const contexts = ruleParents(referencedFrom);
+    contexts.push(referencedFrom);
+    let name = partialName;
+    if (name.startsWith("^ . ")) {
+        const prefix = name.match(/^(\^ \. )+/)?.[0] ?? "";
+        name = name.slice(prefix.length);
+        contexts.splice(-(prefix.length / 4));
+    }
+    const root = contexts.pop();
+    contexts.unshift(root);
+    contexts.push("");
+    const context = contexts.find((context) => {
+        const dottedName = withContext(context, name);
+        return (dottedName in rules &&
+            dottedName !== referencedFrom &&
+            isAccessible(rules, referencedFrom, dottedName));
+    });
+    if (context !== undefined)
+        return withContext(context, name);
+    if (referencedFrom.endsWith(name))
+        return referencedFrom;
+    const candidates = contexts.map((context) => withContext(context, name));
+    const existing = candidates.find((candidate) => candidate in rules);
+    throw new PublicodesError("SyntaxError", existing === undefined
+        ? `La référence "${name}" est introuvable.\nVérifiez que l'orthographe et l'espace de nom sont corrects`
+        : `La règle "${existing}" n'est pas accessible depuis "${referencedFrom}".\n\tCela vient du fait qu'elle est privée ou qu'un de ses parent est privé`, { dottedName: contextNameToDottedName(referencedFrom) });
+}
+export function ruleWithDedicatedDocumentationPage(rule) {
+    return (rule.virtualRule !== true &&
+        rule.type !== "groupe" &&
+        rule.type !== "texte" &&
+        rule.type !== "paragraphe" &&
+        rule.type !== "notification");
+}

package/dist/types.d.ts

@@ -0,0 +1,111 @@
+import type { GetUnitKey, Unit } from "./units.js";
+export type PublicodesExpression = string | number | Record<string, unknown>;
+export type Rule = Record<string, unknown> & {
+    titre?: string;
+    question?: string;
+    experimental?: "oui";
+    privé?: "oui";
+};
+export type RawRule = Omit<Rule, "nom"> | PublicodesExpression | null;
+export type RawPublicodes<RuleNames extends string = string> = Partial<Record<RuleNames, RawRule>>;
+export type Situation<RuleNames extends string = string> = Partial<Record<RuleNames, PublicodesExpression>>;
+export type Evaluation = number | string | boolean | null | undefined;
+export interface EvaluatedNode {
+    nodeValue: Evaluation;
+    unit?: Unit;
+    missingVariables: Record<string, number>;
+}
+/** One of the values a rule with `une possibilité` takes. */
+export interface Possibility {
+    type: "number" | "string" | "reference";
+    nodeValue: string | number;
+    publicodesValue: string;
+    notApplicable: {
+        nodeKind: string;
+        nodeValue: Evaluation;
+    };
+    unit?: Unit;
+    dottedName?: string;
+    title?: string;
+}
+/** A parsed rule, without its explanation tree. */
+export interface RuleNode<Name extends string = string> {
+    dottedName: Name;
+    title: string;
+    nodeKind: "rule";
+    private: boolean;
+    virtualRule: boolean;
+    rawNode: Rule;
+    possibilities: {
+        nodeKind: "une possibilité";
+        type: "number" | "string" | "reference";
+        unit?: Unit;
+        explanation: Possibility[];
+    } | null;
+}
+export type ParsedRules<RuleNames extends string = string> = Record<RuleNames, RuleNode<RuleNames>>;
+export interface Logger {
+    log(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+export interface StrictOptions {
+    situation?: boolean;
+    noOrphanRule?: boolean;
+    noCycleRuntime?: boolean;
+    checkPossibleValues?: boolean;
+}
+export interface FlagOptions {
+    filterNotApplicablePossibilities?: boolean;
+    automaticNamespaceDisabling?: boolean;
+}
+export interface WarnOptions {
+    experimentalRules?: boolean;
+    unitConversion?: boolean;
+    cyclicReferences?: boolean;
+    deprecatedSyntax?: boolean;
+    situationIssues?: boolean;
+}
+export interface EngineOptions {
+    allowOrphanRules?: boolean;
+    strict?: boolean | StrictOptions;
+    logger?: Logger;
+    flag?: FlagOptions;
+    warn?: boolean | WarnOptions;
+    getUnitKey?: GetUnitKey;
+}
+type BinaryOperator = "+" | "-" | "*" | "/" | "**" | ">" | "<" | ">=" | "<=" | "=" | "!=";
+export type BinaryOp = {
+    [Operator in BinaryOperator]: {
+        [Key in Operator]: [ExprAST, ExprAST];
+    };
+}[BinaryOperator];
+export type UnaryOp = {
+    "-": [{
+        constant: {
+            type: "number";
+            nodeValue: 0;
+        };
+    }, ExprAST];
+};
+/** The tree of a publicodes expression. */
+export type ExprAST = BinaryOp | UnaryOp | {
+    variable: string;
+} | {
+    constant: {
+        type: "number";
+        nodeValue: number;
+        rawUnit?: string;
+    };
+} | {
+    constant: {
+        type: "boolean";
+        nodeValue: boolean;
+    };
+} | {
+    constant: {
+        type: "string" | "date";
+        nodeValue: string;
+    };
+};
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/units.d.ts

@@ -0,0 +1,10 @@
+export interface Unit {
+    numerators: string[];
+    denominators: string[];
+}
+export type FormatUnit = (unit: string, count: number) => string;
+export type GetUnitKey = (writtenUnit: string) => string;
+export declare function parseUnit(text: string, getUnitKey?: GetUnitKey): Unit;
+export declare function serializeUnit(rawUnit: Unit | undefined | string, count?: number, formatUnit?: FormatUnit): string | undefined;
+export declare function simplifyUnit(unit: Unit): Unit;
+export declare function convertUnit<Value extends number | undefined | null>(from: Unit | undefined, to: Unit | undefined, value: Value): Value;

package/dist/units.js

@@ -0,0 +1,165 @@
+import { PublicodesError } from "./error.js";
+/** Each base unit with its power, the power written as trailing digits. */
+function unitCounts(units) {
+    const counts = new Map();
+    for (const unit of units) {
+        const power = unit.match(/(\d+)(?!.*[A-Za-z])/g)?.[0];
+        const base = power === undefined ? unit : (unit.split(power)[0] ?? "");
+        counts.set(base, (counts.get(base) ?? 0) + (power === undefined ? 1 : +power));
+    }
+    return counts;
+}
+export function parseUnit(text, getUnitKey = (x) => x) {
+    if (text.includes("/ ")) {
+        throw new Error(`L'unité "${text}" ne doit pas contenir d'espace après "/"`);
+    }
+    const [numerators = "", ...denominators] = text.split("/");
+    const split = (part) => [
+        ...unitCounts(part.trim().split(".").filter(Boolean).map(getUnitKey)).entries(),
+    ].flatMap(([unit, power]) => Array(power).fill(unit));
+    return {
+        numerators: split(numerators),
+        denominators: denominators.flatMap(split),
+    };
+}
+/**
+ * Cancels the units found both as numerator and denominator, except the empty unit, which
+ * `publicodes` finds but reads as false.
+ */
+function simplify(unit, same) {
+    let { numerators, denominators } = unit;
+    const removeOnce = (list, item) => {
+        const index = list.findIndex((e) => same(e, item));
+        return list.filter((_, i) => i !== index);
+    };
+    for (const next of [...unit.numerators, ...unit.denominators]) {
+        if (numerators.find((u) => same(next, u)) &&
+            denominators.find((u) => same(next, u))) {
+            numerators = removeOnce(numerators, next);
+            denominators = removeOnce(denominators, next);
+        }
+    }
+    return { numerators, denominators };
+}
+const plural = 2;
+export function serializeUnit(rawUnit, count = plural, formatUnit = (x) => x) {
+    if (rawUnit === null || typeof rawUnit !== "object") {
+        return typeof rawUnit === "string" ? formatUnit(rawUnit, count) : rawUnit;
+    }
+    const { numerators = [], denominators = [] } = simplify(rawUnit, (a, b) => a === b);
+    const print = (units, n) => [...unitCounts(units.map((unit) => formatUnit(unit, n))).entries()]
+        .map(([unit, power]) => (power > 1 ? `${unit}${power}` : unit))
+        .join(".");
+    if (!numerators.length && !denominators.length)
+        return "";
+    if (!denominators.length)
+        return print(numerators, count);
+    if (!numerators.length)
+        return `/${print(denominators, 1)}`;
+    return `${print(numerators, plural)}/${print(denominators, 1)}`;
+}
+const conversions = {
+    "mois/an": 12,
+    "jour/an": 365,
+    "jour/mois": 365 / 12,
+    "trimestre/an": 4,
+    "mois/trimestre": 3,
+    "jour/trimestre": (365 / 12) * 3,
+    "€/k€": 10 ** 3,
+    "g/kg": 10 ** 3,
+    "mg/g": 10 ** 3,
+    "mg/kg": 10 ** 6,
+    "m/km": 10 ** 3,
+    "cm/m": 10 ** 2,
+    "mm/cm": 10 ** 1,
+    "mm/m": 10 ** 3,
+    "cm/km": 10 ** 5,
+    "mm/km": 10 ** 6,
+};
+/** Units that convert into one another. */
+const classes = [];
+for (const ratio of Object.keys(conversions)) {
+    const [a, b] = ratio.split("/");
+    const withA = classes.find((c) => c.has(a));
+    const withB = classes.find((c) => c.has(b));
+    if (!withA && !withB)
+        classes.push(new Set([a, b]));
+    else
+        (withA ?? withB)?.add(withA ? b : a);
+}
+const sameClass = (a, b) => a === b || classes.some((c) => c.has(a) && c.has(b));
+const removePercentages = (unit) => ({
+    numerators: unit.numerators.filter((u) => u !== "%"),
+    denominators: unit.denominators.filter((u) => u !== "%"),
+});
+export function simplifyUnit(unit) {
+    const { numerators, denominators } = simplify(unit, sameClass);
+    if (numerators.length && numerators.every((u) => u === "%")) {
+        return { numerators: ["%"], denominators };
+    }
+    return removePercentages({ numerators, denominators });
+}
+const round = (value) => +value.toFixed(16);
+function factor(from, to) {
+    const direct = conversions[`${to}/${from}`];
+    if (direct)
+        return direct;
+    const inverse = conversions[`${from}/${to}`];
+    return inverse && 1 / inverse;
+}
+function conversionFactor(from, to) {
+    const percents = (units) => units.filter((u) => u === "%").length;
+    let result = 100 ** (percents(to) - percents(from));
+    for (const unit of from) {
+        const target = to.find((t) => factor(unit, t) !== undefined);
+        result *= (target !== undefined && factor(unit, target)) || 1;
+    }
+    return result;
+}
+function convertible(a, b) {
+    if (a == null || b == null)
+        return true;
+    const countByClass = (units) => {
+        const counts = {};
+        for (const unit of units) {
+            const index = classes.findIndex((c) => c.has(unit));
+            const key = index === -1 ? unit : `${index}`;
+            counts[key] = (counts[key] ?? 0) + 1;
+        }
+        return counts;
+    };
+    const [numA, denA, numB, denB] = [
+        a.numerators,
+        a.denominators,
+        b.numerators,
+        b.denominators,
+    ].map(countByClass);
+    const keys = new Set([numA, denA, numB, denB].flatMap((counts) => Object.keys(counts)));
+    return [...keys].every((key) => key === "%" ||
+        (numA[key] ?? 0) - (denA[key] ?? 0) ===
+            (numB[key] ?? 0) - (denB[key] ?? 0));
+}
+const equivalents = { "kW.h": "kWh", "mn/h": "noeud" };
+export function convertUnit(from, to, value) {
+    const serializedFrom = serializeUnit(from);
+    const serializedTo = serializeUnit(to);
+    const equivalent = !!serializedFrom &&
+        !!serializedTo &&
+        (serializedFrom === serializedTo ||
+            serializedFrom === equivalents[serializedTo] ||
+            serializedTo === equivalents[serializedFrom]);
+    if (!equivalent && !convertible(from, to)) {
+        throw new PublicodesError("EngineError", `Impossible de convertir l'unité '${serializedFrom}' en '${serializedTo}'`, {});
+    }
+    if (!value || from === undefined)
+        return value;
+    const simplified = (unit) => [
+        simplify(removePercentages(unit), sameClass),
+        round(conversionFactor(unit.numerators, unit.denominators)),
+    ];
+    const [fromSimplified, factorTo] = simplified(from);
+    const [toSimplified, factorFrom] = simplified(to ?? { numerators: [], denominators: [] });
+    return round(((value * factorTo) / factorFrom) *
+        conversionFactor(fromSimplified.numerators, toSimplified.numerators) *
+        conversionFactor(toSimplified.denominators, fromSimplified.denominators));
+}

package/dist/web.d.ts

@@ -0,0 +1,2 @@
+export * from "./api.js";
+export { default } from "./api.js";

package/dist/web.js

@@ -0,0 +1,6 @@
+import init, * as module from "../wasm/fast_publicodes.js";
+import { useBinding } from "./binding.js";
+await init();
+useBinding(module);
+export * from "./api.js";
+export { default } from "./api.js";