@graphty/graph-io 0.3.42 → 0.3.44

package/src/styles/notes.ts

@@ -0,0 +1,165 @@
+/**
+ * Style notes are aggregated, never one per element: one note per (code, target, property), with up to 8 distinct
+ * samples, a total count and the element indexes the note covers.
+ */
+
+import type { StyleNote, StyleNoteCode, StyleTarget } from "./types.js";
+
+/** At most this many samples per note. */
+const MAX_SAMPLES = 8;
+/** A sample is cut to this many characters. */
+const MAX_SAMPLE_LENGTH = 80;
+
+/** graph-io's English for each note, used only in its own report. */
+const PHRASES: ReadonlyMap<StyleNoteCode, string> = new Map<StyleNoteCode, string>([
+    ["W_STYLE_VALUE_TOO_LONG", "values longer than 256 characters were not parsed"],
+    ["W_STYLE_BAD_VALUE", "values do not parse"],
+    ["W_STYLE_UNKNOWN_VALUE", "values have no name in the vocabulary and are kept as other:<value>"],
+    ["W_STYLE_ALPHA_DROPPED", "color alpha was dropped"],
+    ["W_STYLE_COLOR_LIST", "color lists are not read as one color"],
+    ["W_STYLE_GRADIENT", "gradients are read as their first color"],
+    ["W_STYLE_UNFILLED", "nodes with a fill color are drawn unfilled"],
+    ["W_STYLE_NO_FILL", "fills are marked transparent"],
+    ["W_STYLE_NO_STROKE", "strokes are marked absent"],
+    ["W_STYLE_SIZE_MINIMUM", "node sizes are minimums: the node grows to fit its label"],
+    ["W_STYLE_HTML_LABEL", "HTML-like labels keep their text; markup was dropped"],
+    ["W_STYLE_RECORD_LABEL", "record label fields were joined"],
+    ["W_STYLE_EXTRA_LABELS", "elements have more than one label; the first was kept"],
+    ["W_STYLE_INHERIT_COLOR", "inherited colors cannot be expressed"],
+    ["W_STYLE_NOT_CARRIED", "style properties have no counterpart and were not carried"],
+    ["W_STYLE_BAD_MAPPING", "mappings cannot be read"],
+    ["W_STYLE_MAPPING_COLUMN_MISSING", "mappings read a column the file does not have"],
+    ["W_STYLE_REFERENCE_CYCLE", "style references are circular or too deep"],
+    ["W_STYLE_UNRESOLVED", "style references name nothing"],
+    ["W_STYLE_NESTING", "style structures are nested too deep"],
+    ["W_STYLE_UNREADABLE", "a style section cannot be read"],
+    ["W_STYLE_NO_VIZMAP", "the session holds no visual styles"],
+    ["W_STYLE_VIEW_STYLE_MISSING", "the view names a style the file does not hold"],
+    ["W_STYLE_OTHER_STYLES", "other visual styles were not read"],
+    ["W_STYLE_OTHER_VIEWS", "other views were not read"],
+    ["W_STYLE_SELECTOR", "invalid selectors match every element"],
+    ["W_STYLE_SELECTOR_AS_COLUMN", "selectors were evaluated into per-element values"],
+    ["W_STYLE_STATE_ASSUMED", "selector states were evaluated as at load"],
+    ["W_STYLE_RAMP_ROUNDED", "continuous mappings match within the tool's rounding"],
+    ["W_STYLE_LAYER_CAP", "rules were folded into per-element copies"],
+    ["W_STYLE_BUDGET", "the work budget ran out; values were copied per element"],
+    ["W_STYLE_BLOCK_IGNORED", "the graphty.styles block was ignored"],
+    ["W_STYLE_NOT_WRITTEN", "the format cannot hold this style"],
+    ["W_STYLE_APPROXIMATED", "written as the nearest value the format allows"],
+    ["W_STYLE_RULES_NOT_KEPT", "per-element values were written but not the rules"],
+    ["W_STYLE_LAYER_FLATTENED", "a style was written as per-element values"],
+]);
+
+/** One note being collected. */
+interface Collecting {
+    readonly code: StyleNoteCode;
+    readonly target: StyleTarget | "graph" | null;
+    readonly property: string | null;
+    count: number;
+    readonly samples: string[];
+    readonly elements: Set<number>;
+    unindexed: boolean;
+}
+
+/**
+ * Options of one report to `StyleNotes.add()`.
+ * @category Styles
+ */
+export interface StyleNoteReport {
+    /** An example of the offending value; kept while the note has fewer than 8 distinct samples. */
+    readonly sample?: unknown;
+    /** The element the report is about, by index. */
+    readonly element?: number;
+    /** How many occurrences the report stands for; defaults to 1. */
+    readonly count?: number;
+}
+
+/**
+ * Collects style notes, aggregated per (code, target, property).
+ * @category Styles
+ */
+export class StyleNotes {
+    readonly #notes = new Map<string, Collecting>();
+
+    /**
+     * Records one occurrence (or `count` occurrences) of a condition.
+     * @param code - the condition
+     * @param target - nodes, edges, the graph, or null for the file as a whole
+     * @param property - the property or the file's name for the construct, or null
+     * @param report - a sample, the element index and a count
+     */
+    add(
+        code: StyleNoteCode,
+        target: StyleTarget | "graph" | null,
+        property: string | null,
+        report: StyleNoteReport = {},
+    ): void {
+        const key = `${code}\u0000${target ?? ""}\u0000${property ?? ""}`;
+        let note = this.#notes.get(key);
+        if (note === undefined) {
+            note = { code, target, property, count: 0, samples: [], elements: new Set(), unindexed: false };
+            this.#notes.set(key, note);
+        }
+        note.count += report.count ?? 1;
+        if (report.element === undefined) {
+            note.unindexed = true;
+        } else {
+            note.elements.add(report.element);
+        }
+        if (report.sample !== undefined && note.samples.length < MAX_SAMPLES) {
+            const sample = sampleText(report.sample);
+            if (!note.samples.includes(sample)) {
+                note.samples.push(sample);
+            }
+        }
+    }
+
+    /**
+     * Whether a note with this code, target and property covers an element.
+     * @param code - the condition
+     * @param target - nodes or edges
+     * @param property - the property
+     * @param element - the element index
+     * @returns true when such a note named the element
+     */
+    covers(code: StyleNoteCode, target: StyleTarget, property: string | null, element: number): boolean {
+        return this.#notes.get(`${code}\u0000${target}\u0000${property ?? ""}`)?.elements.has(element) === true;
+    }
+
+    /**
+     * The collected notes, in the order their conditions first occurred.
+     * @returns one note per (code, target, property)
+     */
+    list(): StyleNote[] {
+        const out: StyleNote[] = [];
+        for (const n of this.#notes.values()) {
+            const where = n.property === null ? (n.target ?? "file") : `${n.target ?? "file"} ${n.property}`;
+            out.push({
+                code: n.code,
+                params: { property: n.property, target: n.target, count: n.count, samples: [...n.samples] },
+                elements: n.unindexed ? { count: n.count } : Array.from(n.elements).sort((a, b) => a - b),
+                message: `${where}: ${PHRASES.get(n.code) ?? n.code} (${n.count})`,
+            });
+        }
+        return out;
+    }
+}
+
+/**
+ * A sample as at most 80 characters of text.
+ * @param value - the sample
+ * @returns its text
+ */
+function sampleText(value: unknown): string {
+    let text: string;
+    if (typeof value === "string") {
+        text = value;
+    } else {
+        try {
+            text = JSON.stringify(value) ?? typeof value;
+        } catch {
+            text = typeof value;
+        }
+    }
+    return text.slice(0, MAX_SAMPLE_LENGTH);
+}

package/src/styles/plan/classes.ts

@@ -0,0 +1,166 @@
+/**
+ * The opaque pool: the families nothing explains. Over their non-text, non-size properties each distinct joint tuple
+ * of values is a style class, numbered 1..k by frequency in the style column `class`; a few classes become one group
+ * rule each, more become one table keyed by the class. What is left is copied per element.
+ */
+
+import type { StyleRule, StyleTarget, StyleValue } from "../types.js";
+import { STYLE_PROPERTIES } from "../vocabulary.js";
+import { MIN_MAPPED } from "./discrete.js";
+import { valueKey } from "./families.js";
+
+/** The most style classes; more distinct tuples are copied per element. */
+const MAX_CLASSES = 64;
+/** At most this many classes become one group rule each. */
+const MAX_CLASS_RULES = 4;
+/** Sizes vary per element by nature and are never joined into a class. */
+const SIZES: ReadonlySet<string> = new Set(["width", "height"]);
+/** The style column holding each element's class. */
+export const CLASS_COLUMN = "class";
+
+/**
+ * The style classes of an opaque pool.
+ */
+interface StyleClasses {
+    /** The properties the classes explain. */
+    readonly classed: readonly string[];
+    /** The class of each element, 1..k, or null. */
+    readonly column: (number | null)[];
+    /** One group rule per class, or one mapping rule keyed by the class. */
+    readonly rules: StyleRule[];
+}
+
+/**
+ * Whether a property's values have few enough distinct values to be part of a class.
+ * @param values - the values
+ * @returns true when they do
+ */
+function fewValues(values: readonly (StyleValue | null)[]): boolean {
+    const seen = new Set<string>();
+    for (const v of values) {
+        seen.add(valueKey(v));
+        if (seen.size > MAX_CLASSES + 1) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * One element's combination of values of the classable properties, as a key; null when it has none.
+ * @param classable - the properties
+ * @param truth - the values per property
+ * @param i - the element
+ * @returns the key
+ */
+function tupleKey(
+    classable: readonly string[],
+    truth: ReadonlyMap<string, readonly (StyleValue | null)[]>,
+    i: number,
+): string | null {
+    let key = "";
+    let any = false;
+    for (const p of classable) {
+        const v = (truth.get(p) ?? [])[i] ?? null;
+        any ||= v !== null;
+        key += `${valueKey(v)}\u0001`;
+    }
+    return any ? key : null;
+}
+
+/**
+ * Finds the style classes of the opaque properties.
+ * @param target - nodes or edges
+ * @param props - the opaque properties
+ * @param truth - the values per property
+ * @param n - the element count
+ * @param spend - spends work from the budget
+ * @returns the classes, or null when the values have too many combinations
+ */
+export function styleClasses(
+    target: StyleTarget,
+    props: readonly string[],
+    truth: ReadonlyMap<string, readonly (StyleValue | null)[]>,
+    n: number,
+    spend: (ops: number) => void,
+): StyleClasses | null {
+    const classable = props.filter(
+        (p) => STYLE_PROPERTIES[target].get(p) !== "text" && !SIZES.has(p) && fewValues(truth.get(p) ?? []),
+    );
+    if (classable.length === 0) {
+        return null;
+    }
+    spend(n * (classable.length + 1));
+    const counts = new Map<string, { count: number; rep: number }>();
+    const tupleOf = new Array<string | null>(n).fill(null);
+    let withTuple = 0;
+    for (let i = 0; i < n; i++) {
+        const key = tupleKey(classable, truth, i);
+        if (key === null) {
+            continue;
+        }
+        withTuple++;
+        tupleOf[i] = key;
+        const c = counts.get(key);
+        if (c === undefined) {
+            counts.set(key, { count: 1, rep: i });
+            if (counts.size > MAX_CLASSES) {
+                return null;
+            }
+        } else {
+            c.count++;
+        }
+    }
+    if (counts.size === 0 || withTuple < MIN_MAPPED || counts.size * 2 > withTuple) {
+        return null;
+    }
+    // classes by frequency, ties by first appearance (a stable sort)
+    const order = Array.from(counts.entries()).sort((a, b) => b[1].count - a[1].count);
+    const rank = new Map(order.map(([key], j) => [key, j + 1]));
+    const column = tupleOf.map((t) => (t === null ? null : (rank.get(t) ?? null)));
+    const ref = { style: CLASS_COLUMN };
+    const valueOf = (p: string, rep: number): StyleValue | null => (truth.get(p) ?? [])[rep] ?? null;
+    const rules: StyleRule[] = [];
+    if (order.length <= Math.min(MAX_CLASS_RULES, Math.floor(withTuple / 4))) {
+        order.forEach(([, { count, rep }], j) => {
+            const set: Record<string, StyleValue> = {};
+            for (const p of classable) {
+                const v = valueOf(p, rep);
+                if (v !== null) {
+                    set[p] = v;
+                }
+            }
+            rules.push({
+                id: `${target}.class.${String(j + 1)}`,
+                target,
+                role: "group",
+                origin: "inferred",
+                where: { eq: [ref, j + 1] },
+                set,
+                facts: { elements: count, reason: "STYLE_CLASS" },
+            });
+        });
+    } else {
+        const map: Record<string, { kind: "discrete"; by: { style: string }; table: [number, StyleValue][] }> = {};
+        for (const p of classable) {
+            const table: [number, StyleValue][] = [];
+            order.forEach(([, { rep }], j) => {
+                const v = valueOf(p, rep);
+                if (v !== null) {
+                    table.push([j + 1, v]);
+                }
+            });
+            map[p] = { kind: "discrete", by: ref, table };
+        }
+        rules.push({
+            id: `${target}.classes`,
+            target,
+            role: "mapping",
+            origin: "inferred",
+            where: { all: true },
+            map,
+            facts: { classes: order.length, elements: withTuple, reason: "STYLE_CLASS" },
+        });
+    }
+    return { classed: classable, column, rules };
+}

package/src/styles/plan/continuous.ts

@@ -0,0 +1,218 @@
+/**
+ * A continuous mapping on one numeric feature: the fewest linear pieces (at most 8, each explaining at least 3
+ * distinct inputs), exact first, else within the rounding the writing tool did per element.
+ */
+
+import type { ContinuousPoint, StyleValue } from "../types.js";
+import { MIN_MAPPED } from "./discrete.js";
+import type { Family } from "./families.js";
+import type { FeatureInfo } from "./features.js";
+import { interpolate, within } from "./resolve.js";
+
+/** The most linear pieces a ramp may have. */
+const MAX_PIECES = 8;
+/** The most distinct inputs a ramp is fitted over. */
+const MAX_DISTINCT_X = 4096;
+const HEX6 = /^#[0-9a-f]{6}$/;
+
+/**
+ * A continuous mapping that explains a family.
+ */
+export interface ContinuousCandidate {
+    /** The kind of candidate. */
+    readonly type: "continuous";
+    /** The feature the ramp reads. */
+    readonly info: FeatureInfo;
+    /** The points per property. */
+    readonly points: ReadonlyMap<string, ContinuousPoint[]>;
+    /** Whether the ramp matches only within the tool's rounding. */
+    readonly tolerant: boolean;
+    /** The description cost. */
+    readonly cost: number;
+}
+
+/**
+ * Whether a value can be interpolated: a number or a canonical color.
+ * @param v - the value
+ * @returns true when it can
+ */
+function interpolable(v: StyleValue | null): v is number | string {
+    return typeof v === "number" || (typeof v === "string" && HEX6.test(v));
+}
+
+/**
+ * The fewest linear pieces over sorted distinct points, or null when more than `MAX_PIECES` are needed.
+ * @param xs - the inputs, ascending
+ * @param ys - the outputs
+ * @param tolerant - whether a piece may miss a point by the tool's rounding
+ * @param spend - spends work from the budget
+ * @returns each piece's first and last point index, or null
+ */
+function fitPieces(
+    xs: readonly number[],
+    ys: readonly StyleValue[],
+    tolerant: boolean,
+    spend: (ops: number) => void,
+): [number, number][] | null {
+    const pieces: [number, number][] = [];
+    let a = 0;
+    while (a < xs.length) {
+        let b = a;
+        // extend while the line from a to b + 1 reproduces every point between
+        while (b + 1 < xs.length) {
+            const ok = lineFits(xs, ys, a, b + 1, tolerant);
+            spend(b + 1 - a);
+            if (!ok) {
+                break;
+            }
+            b++;
+        }
+        pieces.push([a, b]);
+        if (pieces.length > MAX_PIECES) {
+            return null;
+        }
+        a = b + 1;
+    }
+    return pieces;
+}
+
+/**
+ * Whether the line from point a to point c reproduces every point between.
+ * @param xs - the inputs, ascending
+ * @param ys - the outputs
+ * @param a - the first point
+ * @param c - the last point
+ * @param tolerant - whether the line may miss a point by the tool's rounding
+ * @returns true when it does
+ */
+function lineFits(xs: readonly number[], ys: readonly StyleValue[], a: number, c: number, tolerant: boolean): boolean {
+    for (let j = a + 1; j < c; j++) {
+        const v = interpolate(ys[a], ys[c], (xs[j] - xs[a]) / (xs[c] - xs[a]));
+        if (tolerant ? !within(v, ys[j]) : v !== ys[j]) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * The points of a fitted ramp.
+ * @param xs - the inputs
+ * @param ys - the outputs
+ * @param pieces - the pieces
+ * @returns the points, ascending
+ */
+function piecesToPoints(
+    xs: readonly number[],
+    ys: readonly StyleValue[],
+    pieces: [number, number][],
+): ContinuousPoint[] {
+    const out: ContinuousPoint[] = [];
+    for (const [a, b] of pieces) {
+        out.push({ at: xs[a], below: ys[a], value: ys[a], above: ys[a] });
+        if (b !== a) {
+            out.push({ at: xs[b], below: ys[b], value: ys[b], above: ys[b] });
+        }
+    }
+    return out;
+}
+
+/**
+ * Tests a continuous mapping on one feature.
+ * @param fam - the family
+ * @param info - the feature
+ * @param truth - the values per property
+ * @param spend - spends work from the budget
+ * @returns the candidate, or null when the feature does not explain the family
+ */
+export function continuousCandidate(
+    fam: Family,
+    info: FeatureInfo,
+    truth: ReadonlyMap<string, readonly (StyleValue | null)[]>,
+    spend: (ops: number) => void,
+): ContinuousCandidate | null {
+    if (!info.numeric || info.raw || fam.styled.length < MIN_MAPPED) {
+        return null;
+    }
+    const { values } = info.feature;
+    spend(values.length);
+    // the feature must be a number exactly where the family has a value
+    if (values.some((v, i) => (fam.blocks[i] === 0) === (typeof v === "number"))) {
+        return null;
+    }
+    for (const tolerant of [false, true]) {
+        const points = rampsOf(fam, values, truth, tolerant, spend);
+        if (points !== null) {
+            const entries = Array.from(points.values()).reduce((sum, pts) => sum + pts.length, 0);
+            return { type: "continuous", info, points, tolerant, cost: 50 + entries + (tolerant ? 10 : 0) };
+        }
+    }
+    return null;
+}
+
+/**
+ * The ramp of every property of the family over the feature, or null when one has none.
+ * @param fam - the family
+ * @param values - the feature's values
+ * @param truth - the values per property
+ * @param tolerant - whether a ramp may miss a value by the tool's rounding
+ * @param spend - spends work from the budget
+ * @returns the points per property, or null
+ */
+function rampsOf(
+    fam: Family,
+    values: readonly unknown[],
+    truth: ReadonlyMap<string, readonly (StyleValue | null)[]>,
+    tolerant: boolean,
+    spend: (ops: number) => void,
+): Map<string, ContinuousPoint[]> | null {
+    const points = new Map<string, ContinuousPoint[]>();
+    for (const p of fam.props) {
+        const pts = rampOf(fam, values, truth.get(p) ?? [], tolerant, spend);
+        if (pts === null) {
+            return null;
+        }
+        points.set(p, pts);
+    }
+    return points;
+}
+
+/**
+ * The ramp of one property over the feature, or null when none explains it.
+ * @param fam - the family
+ * @param values - the feature's values
+ * @param ys0 - the property's values
+ * @param tolerant - whether the ramp may miss a value by the tool's rounding
+ * @param spend - spends work from the budget
+ * @returns the points, or null
+ */
+function rampOf(
+    fam: Family,
+    values: readonly unknown[],
+    ys0: readonly (StyleValue | null)[],
+    tolerant: boolean,
+    spend: (ops: number) => void,
+): ContinuousPoint[] | null {
+    const byX = new Map<number, StyleValue>();
+    let good = true;
+    for (const i of fam.styled) {
+        const y = ys0[i];
+        const x = values[i] as number;
+        const seen = byX.get(x);
+        if (!interpolable(y) || (seen !== undefined && seen !== y)) {
+            good = false;
+            break;
+        }
+        byX.set(x, y);
+    }
+    spend(fam.styled.length);
+    // a ramp needs at least 3 distinct outputs: two values over a number are a threshold, not a mapping
+    if (!good || byX.size < 2 || byX.size > MAX_DISTINCT_X || new Set(byX.values()).size < 3) {
+        return null;
+    }
+    const xs = Array.from(byX.keys()).sort((a, b) => a - b);
+    const ys = xs.map((x) => byX.get(x) as StyleValue);
+    const pieces = fitPieces(xs, ys, tolerant, spend);
+    // every piece must explain at least 3 distinct inputs, or a few points fit anything
+    return pieces === null || pieces.length * 3 > xs.length ? null : piecesToPoints(xs, ys, pieces);
+}