@graphty/graph-io 0.3.42 → 0.3.44

package/src/styles/canon/enums.ts

@@ -0,0 +1,211 @@
+/**
+ * Canonical enumeration values: each dialect's spellings matched against an alias table without regard to case,
+ * spaces or underscores. An unknown value of an open enumeration (shapes, border and line styles, arrows) is kept as
+ * `other:<raw>` and noted; an unknown value of a closed one (weights, positions) gives no value and is noted.
+ */
+
+import { STYLE_ISSUE } from "../codes.js";
+import type { StyleDialect } from "../types.js";
+import { type CanonSite, noteAt, scalarText } from "./site.js";
+
+/**
+ * The enumerations a style value can belong to.
+ * @category Styles
+ */
+export type StyleEnumKind = "shape" | "borderStyle" | "lineStyle" | "arrow" | "weight" | "position";
+
+type Aliases = Readonly<Record<string, readonly string[]>>;
+
+const SHAPES: Aliases = {
+    ellipse: [
+        "ellipse",
+        "oval",
+        "circle",
+        "disc",
+        "disk",
+        "point",
+        "doublecircle",
+        "mcircle",
+        "dot",
+        "sphere",
+        "circular",
+    ],
+    rectangle: [
+        "rectangle",
+        "rect",
+        "box",
+        "square",
+        "plaintext",
+        "plain",
+        "record",
+        "msquare",
+        "box3d",
+        "rectangle3d",
+        "component",
+        "tab",
+        "folder",
+        "note",
+        "underline",
+    ],
+    "round-rectangle": [
+        "round-rectangle",
+        "roundrectangle",
+        "roundrect",
+        "rounded",
+        "roundedrectangle",
+        "round-rect",
+        "mrecord",
+        "cut-rectangle",
+        "round-tag",
+        "bottom-round-rectangle",
+    ],
+    triangle: ["triangle", "invtriangle", "round-triangle", "tag"],
+    diamond: ["diamond", "rhombus", "mdiamond", "round-diamond"],
+    pentagon: ["pentagon", "round-pentagon"],
+    hexagon: ["hexagon", "hexagon2", "round-hexagon", "concave-hexagon", "septagon", "heptagon", "round-heptagon"],
+    octagon: ["octagon", "doubleoctagon", "tripleoctagon", "round-octagon", "octagon2"],
+    parallelogram: ["parallelogram", "parallelogram2", "rhomboid", "fat-arrow", "fatarrow"],
+    trapezoid: ["trapezoid", "trapezoid2", "invtrapezoid", "trapezium", "round-trapezoid"],
+    star: ["star", "star5", "star6", "star8", "polygon"],
+    vee: ["vee", "v"],
+    none: ["none", "empty", "invis"],
+};
+
+const BORDER_STYLES: Aliases = {
+    solid: ["solid", "line"],
+    dashed: ["dashed", "dash", "equal-dash"],
+    dotted: ["dotted", "dot", "dots"],
+    "dash-dot": ["dash-dot", "dashdot", "dashed-dotted"],
+    double: ["double", "parallel-lines"],
+};
+
+const LINE_STYLES: Aliases = {
+    solid: ["solid", "line", "continuous", "separate-arrow"],
+    dashed: ["dashed", "dash", "dashed-line", "equal-dash"],
+    dotted: ["dotted", "dot", "dots", "dotted-line"],
+    "dash-dot": ["dash-dot", "dashdot", "dashed-dotted", "dash-dot-dot"],
+    "long-dash": ["long-dash", "longdash"],
+    double: ["double", "parallel", "parallel-lines"],
+    zigzag: ["zigzag"],
+    sinewave: ["sinewave", "sine-wave"],
+};
+
+const ARROWS: Aliases = {
+    none: ["none", "no-arrow", "noarrow", "0"],
+    triangle: [
+        "triangle",
+        "normal",
+        "delta",
+        "standard",
+        "arrow",
+        "triangle-backcurve",
+        "white-delta-inverted",
+        "simple",
+        "short",
+        "plain",
+        "convex",
+        "a",
+    ],
+    "triangle-open": ["triangle-open", "onormal", "empty", "white-delta", "transparent-circle-inverted", "open-delta"],
+    vee: ["vee", "open", "chevron", "concave", "triangle-cross", "b"],
+    tee: ["tee", "t", "t-shape", "half-bottom", "half-top", "bar"],
+    diamond: ["diamond", "white-diamond-inverted"],
+    "diamond-open": ["diamond-open", "odiamond", "white-diamond", "ediamond", "open-diamond"],
+    circle: ["circle", "dot", "transparent-circle", "white-circle-inverted"],
+    "circle-open": ["circle-open", "odot", "white-circle", "open-circle"],
+    square: ["square", "box", "skewed-dash"],
+    // An X-shaped "cross" (yEd, yFiles) is not a crow's foot: it stays other:cross.
+    crow: ["crow", "crows-foot", "crows-foot-many"],
+    half: ["half", "half-top-arrow", "half-open", "lnormal", "rnormal", "halfopen"],
+    inverted: ["inverted", "inv", "inverted-triangle", "inv-triangle"],
+};
+
+const WEIGHTS: Aliases = {
+    normal: ["normal", "regular", "plain", "lighter", "100", "200", "300", "400", "500"],
+    bold: ["bold", "bolder", "600", "700", "800", "900"],
+};
+
+const POSITIONS: Aliases = {
+    center: ["center", "centre", "middle", "c"],
+    top: ["top", "north", "t"],
+    bottom: ["bottom", "south", "b"],
+    left: ["left", "west", "l"],
+    right: ["right", "east", "r"],
+    "top-left": ["top-left", "north-west", "northwest"],
+    "top-right": ["top-right", "north-east", "northeast"],
+    "bottom-left": ["bottom-left", "south-west", "southwest"],
+    "bottom-right": ["bottom-right", "south-east", "southeast"],
+};
+
+/** vis-network draws these spellings differently from the common reading. */
+const VIS: Partial<Record<StyleEnumKind, Aliases>> = {
+    shape: {
+        "round-rectangle": ["box"],
+        ellipse: ["dot"],
+        triangle: ["triangledown"],
+        none: ["text"],
+    },
+    arrow: { inverted: ["inv-triangle"], square: ["box"] },
+};
+
+/** Per-dialect overrides; a dialect not listed reads the common table alone. */
+const OVERRIDES: ReadonlyMap<string, Partial<Record<StyleEnumKind, Aliases>>> = new Map([["vis", VIS]]);
+
+const OPEN: ReadonlySet<StyleEnumKind> = new Set<StyleEnumKind>(["shape", "borderStyle", "lineStyle", "arrow"]);
+
+/**
+ * Builds an alias lookup.
+ * @param aliases - canonical value to spellings
+ * @returns spelling to canonical value
+ */
+function lookup(aliases: Aliases): ReadonlyMap<string, string> {
+    const map = new Map<string, string>();
+    for (const [value, spellings] of Object.entries(aliases)) {
+        for (const spelling of spellings) {
+            map.set(spelling, value);
+        }
+    }
+    return map;
+}
+
+const COMMON: ReadonlyMap<StyleEnumKind, ReadonlyMap<string, string>> = new Map([
+    ["shape", lookup(SHAPES)],
+    ["borderStyle", lookup(BORDER_STYLES)],
+    ["lineStyle", lookup(LINE_STYLES)],
+    ["arrow", lookup(ARROWS)],
+    ["weight", lookup(WEIGHTS)],
+    ["position", lookup(POSITIONS)],
+]);
+
+const DIALECT: ReadonlyMap<string, ReadonlyMap<StyleEnumKind, ReadonlyMap<string, string>>> = new Map(
+    Array.from(OVERRIDES, ([dialect, kinds]) => [
+        dialect,
+        new Map(Object.entries(kinds).map(([kind, aliases]) => [kind as StyleEnumKind, lookup(aliases)])),
+    ]),
+);
+
+/**
+ * A canonical enumeration value: the dialect's spelling matched without regard to case, with spaces and underscores
+ * read as hyphens (Cytoscape's `ROUND_RECTANGLE` is `round-rectangle`). An unknown value is `other:<raw>` for an
+ * open enumeration and null for a closed one, noted as `W_STYLE_UNKNOWN_VALUE` either way.
+ * @param kind - the enumeration
+ * @param raw - the file's value
+ * @param dialect - the file's dialect
+ * @param site - where it was read
+ * @returns the canonical value, or null
+ * @category Styles
+ */
+export function canonEnum(kind: StyleEnumKind, raw: unknown, dialect: StyleDialect, site: CanonSite): string | null {
+    const text = scalarText(raw, site);
+    if (text === null) {
+        return null;
+    }
+    const trimmed = text.trim();
+    const key = trimmed.toLowerCase().replaceAll(/[\s_]+/g, "-");
+    const value = DIALECT.get(dialect)?.get(kind)?.get(key) ?? COMMON.get(kind)?.get(key);
+    if (value !== undefined) {
+        return value;
+    }
+    noteAt(site, STYLE_ISSUE.UNKNOWN_VALUE, trimmed);
+    return OPEN.has(kind) ? `other:${trimmed}` : null;
+}

package/src/styles/canon/graphviz.ts

@@ -0,0 +1,189 @@
+/**
+ * Graphviz's own color resolution, measured against `dot` 2.43 with `-Txdot`:
+ *
+ * - Leading blanks are skipped and trailing ones are not (`"red  "` is unknown); names match without regard to case
+ *   and keep their inner spaces (`Light Grey` is unknown).
+ * - `#rrggbb` and `#rrggbbaa` only, with anything after the digits ignored; there is no 3-digit form.
+ * - Three numbers starting with a digit or a point (`.5 .5 .5`, `0.5,0.5,0.5`) are hue, saturation and value, each
+ *   clamped to 0..1 and truncated to a byte; a fourth number and anything after it are ignored. A leading sign makes
+ *   the value a name, so `-0.5 0.5 0.5` is unknown.
+ * - `/scheme/name` names a scheme for one value and `//name` means the object's scheme; scheme names ignore case. A
+ *   scheme other than `x11` is searched INSTEAD of X11: `colorscheme=blues9` makes `red` unknown, and an unknown
+ *   scheme knows no names at all.
+ * - `transparent`, `none` and `invis` are `#fffffe` with alpha 0, whatever the scheme.
+ * - An unknown color is drawn BLACK.
+ * - A color list (`red:blue`, `red;0.3:blue`): an outline or a font color draws the text before the first `:` as one
+ *   color, so `red:blue` is red and `red;0.3:blue` is black (`red;0.3` is not a color). A fill draws a gradient and
+ *   an edge draws one line per color; both start with the first entry's color, its `;fraction` dropped. A value
+ *   with a `;` and no `:` is not a list: it is one unknown color, drawn black.
+ */
+
+import { BREWER_SCHEMES, CSS_COLORS, X11_COLORS } from "./color-tables.js";
+
+/**
+ * How Graphviz draws a color value, which decides how a color list is read.
+ * @category Styles
+ */
+export type GraphvizColorUse = "line" | "fill" | "edge";
+
+/**
+ * A resolved Graphviz color, with how it was read.
+ * @category Styles
+ */
+export interface GraphvizColor {
+    /** `#rrggbb`. */
+    readonly hex: string;
+    /** 0..1. */
+    readonly alpha: number;
+    /** The value did not resolve, so Graphviz draws black. */
+    readonly unknown: boolean;
+    /** The value is a list read as its first color: a gradient for a fill, parallel lines for an edge. */
+    readonly list: "gradient" | "lines" | null;
+}
+
+const TRANSPARENT = new Set(["transparent", "none", "invis"]);
+const HSV_PART = /^(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+
+/**
+ * A byte as two hex digits.
+ * @param v - 0..255
+ * @returns two lowercase hex digits
+ */
+function hex2(v: number): string {
+    return v.toString(16).padStart(2, "0");
+}
+
+/**
+ * Graphviz's HSV to RGB, channels truncated to bytes.
+ * @param h - hue 0..1
+ * @param s - saturation 0..1
+ * @param v - value 0..1
+ * @returns `#rrggbb`
+ */
+function hsvHex(h: number, s: number, v: number): string {
+    const i = Math.floor(h * 6);
+    const f = h * 6 - i;
+    const p = v * (1 - s);
+    const q = v * (1 - f * s);
+    const t = v * (1 - (1 - f) * s);
+    const rgb = [
+        [v, t, p],
+        [q, v, p],
+        [p, v, t],
+        [p, q, v],
+        [t, p, v],
+        [v, p, q],
+    ][i % 6];
+    return `#${rgb.map((c) => hex2(Math.trunc(c * 255))).join("")}`;
+}
+
+/**
+ * Resolves one Graphviz color (no list), or null when Graphviz does not know it.
+ * @param text - the color, leading blanks already skipped
+ * @param scheme - the object's color scheme, lowercase, `x11` when unset
+ * @returns hex and alpha, or null
+ */
+function resolveOne(text: string, scheme: string): { hex: string; alpha: number } | null {
+    if (text.startsWith("#")) {
+        const m = /^#([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{1,2})?/.exec(text);
+        if (m === null) {
+            return null;
+        }
+        return {
+            hex: `#${m[1]}${m[2]}${m[3]}`.toLowerCase(),
+            alpha: m[4] === undefined ? 1 : Number.parseInt(m[4], 16) / 255,
+        };
+    }
+    const hsv = /^[.\d]/.test(text) ? hsvColor(text) : null;
+    if (hsv !== null) {
+        return { hex: hsv, alpha: 1 };
+    }
+    const named = schemedName(text.toLowerCase(), scheme);
+    if (named === null) {
+        return null;
+    }
+    if (TRANSPARENT.has(named.name)) {
+        return { hex: "#fffffe", alpha: 0 };
+    }
+    const hex = schemeColor(named.name, named.scheme);
+    return hex === undefined ? null : { hex, alpha: 1 };
+}
+
+/**
+ * An HSV color: three numbers 0..1 separated by blanks or commas, clamped.
+ * @param text - the color
+ * @returns `#rrggbb`, or null when it is not one
+ */
+function hsvColor(text: string): string | null {
+    const parts = text.split(/[ ,]+/);
+    if (parts.length < 3 || !parts.slice(0, 3).every((p) => HSV_PART.test(p))) {
+        return null;
+    }
+    const [h, s, v] = parts.slice(0, 3).map((p) => Math.min(1, Math.max(0, Number(p))));
+    return hsvHex(h, s, v);
+}
+
+/**
+ * A color name and the scheme it is looked up in: `/scheme/name` names its own scheme, `//name` the object's.
+ * @param name - the name, lowercase
+ * @param scheme - the object's color scheme
+ * @returns the name and scheme, or null for a malformed `/scheme/name`
+ */
+function schemedName(name: string, scheme: string): { name: string; scheme: string } | null {
+    if (!name.startsWith("/")) {
+        return { name, scheme };
+    }
+    const slash = name.indexOf("/", 1);
+    if (slash < 0) {
+        return null;
+    }
+    const prefix = name.slice(1, slash);
+    return { name: name.slice(slash + 1), scheme: prefix === "" ? scheme : prefix };
+}
+
+/**
+ * A color in a scheme: X11's or SVG's names, or a Brewer scheme's colors by their 1-based index.
+ * @param name - the name or index
+ * @param scheme - the scheme
+ * @returns `#rrggbb`, or undefined when the scheme has no such color
+ */
+function schemeColor(name: string, scheme: string): string | undefined {
+    if (scheme === "x11") {
+        return X11_COLORS.get(name);
+    }
+    if (scheme === "svg") {
+        return CSS_COLORS.get(name);
+    }
+    const colors = BREWER_SCHEMES.get(scheme);
+    const index = /^\d{1,3}$/.test(name) ? Number(name) : 0;
+    return colors !== undefined && index >= 1 ? colors[index - 1] : undefined;
+}
+
+/**
+ * Resolves a Graphviz color value the way Graphviz draws it for a use; an unknown color is black.
+ * @param raw - the value, at most 256 characters
+ * @param scheme - the object's `colorscheme`, or null
+ * @param use - an outline or font color (`line`), a fill, or an edge's line color
+ * @returns the color and how it was read
+ * @category Styles
+ */
+export function graphvizColor(raw: string, scheme: string | null, use: GraphvizColorUse): GraphvizColor {
+    let text = raw.replace(/^[ \t\r\n]+/, "");
+    let list: GraphvizColor["list"] = null;
+    const colon = text.indexOf(":");
+    if (colon >= 0) {
+        text = text.slice(0, colon);
+        if (use !== "line") {
+            const semi = text.indexOf(";");
+            if (semi >= 0) {
+                text = text.slice(0, semi);
+            }
+            list = use === "fill" ? "gradient" : "lines";
+        }
+    }
+    const sc = scheme === null || scheme.trim() === "" ? "x11" : scheme.toLowerCase();
+    const resolved = text === "" ? null : resolveOne(text, sc);
+    return resolved === null
+        ? { hex: "#000000", alpha: 1, unknown: true, list }
+        : { hex: resolved.hex, alpha: resolved.alpha, unknown: false, list };
+}

package/src/styles/canon/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Canonical style values: every reader turns a file's raw value into one spelling per property before anything
+ * compares values. Colors are `#rrggbb` with the alpha moved to an opacity, numbers have 6 significant digits,
+ * enumerations come from the neutral vocabulary, and text is what the tool draws.
+ */
+
+export * from "./bends.js";
+export * from "./color.js";
+export * from "./enums.js";
+export { type GraphvizColor, graphvizColor, type GraphvizColorUse } from "./graphviz.js";
+export * from "./number.js";
+export { type CanonSite, MAX_STYLE_VALUE_LENGTH } from "./site.js";
+export * from "./text.js";

package/src/styles/canon/number.ts

@@ -0,0 +1,152 @@
+/**
+ * Canonical numbers, lengths, opacities and booleans: 6 significant digits, never negative, never NaN or Infinity.
+ */
+
+import { STYLE_ISSUE } from "../codes.js";
+import type { StyleDialect } from "../types.js";
+import { type CanonSite, noteAt, scalarText, spendAt } from "./site.js";
+
+/**
+ * The largest length or factor a file may give; a larger one is noted as `W_STYLE_BAD_VALUE` and gives no value.
+ * @category Styles
+ */
+export const MAX_STYLE_NUMBER = 1e6;
+
+/**
+ * Points per inch: DOT gives node sizes in inches, and a canonical length is in points (pixels at 72 dpi).
+ * @category Styles
+ */
+export const DOT_POINTS_PER_INCH = 72;
+
+/** One way to read a decimal number, so a long run of digits fails or passes in one pass. */
+const DECIMAL = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+
+/**
+ * A number at 6 significant digits, with `-0` as `0`.
+ * @param value - a finite number
+ * @returns the canonical number
+ * @category Styles
+ */
+export function num6(value: number): number {
+    return Number(value.toPrecision(6)) + 0;
+}
+
+/**
+ * A finite number from a number or a decimal string, or null with a note.
+ * @param raw - the file's value
+ * @param site - where it was read
+ * @returns the number, or null
+ */
+function finite(raw: unknown, site: CanonSite): number | null {
+    if (typeof raw === "boolean") {
+        noteAt(site, STYLE_ISSUE.BAD_VALUE, raw);
+        return null;
+    }
+    const text = scalarText(raw, site);
+    if (text === null) {
+        return null;
+    }
+    const trimmed = text.trim();
+    let value = Number.NaN;
+    if (typeof raw === "number") {
+        value = raw;
+    } else if (DECIMAL.test(trimmed)) {
+        value = Number(trimmed);
+    }
+    if (!Number.isFinite(value)) {
+        noteAt(site, STYLE_ISSUE.BAD_VALUE, text);
+        return null;
+    }
+    return value;
+}
+
+/**
+ * A length or factor: a finite number at least 0 and at most `MAX_STYLE_NUMBER` after multiplying by `factor`, at 6
+ * significant digits. Anything else is null with a `W_STYLE_BAD_VALUE` note.
+ * @param raw - the file's value: a number or a decimal string
+ * @param site - where it was read
+ * @param factor - multiplies the value first (`DOT_POINTS_PER_INCH` for DOT sizes); defaults to 1
+ * @returns the canonical number, or null
+ * @category Styles
+ */
+export function canonNumber(raw: unknown, site: CanonSite, factor = 1): number | null {
+    const value = finite(raw, site);
+    if (value === null) {
+        return null;
+    }
+    const scaled = value * factor;
+    if (!(scaled >= 0 && scaled <= MAX_STYLE_NUMBER)) {
+        noteAt(site, STYLE_ISSUE.BAD_VALUE, typeof raw === "string" ? raw : String(raw));
+        return null;
+    }
+    return num6(scaled);
+}
+
+/**
+ * An opacity from 0 to 1. Cytoscape desktop states opacities from 0 to 255 and is divided by 255; every other
+ * dialect states 0 to 1. A value outside the dialect's range is null with a `W_STYLE_BAD_VALUE` note.
+ * @param raw - the file's value
+ * @param dialect - the file's dialect
+ * @param site - where it was read
+ * @returns the canonical opacity, or null
+ * @category Styles
+ */
+export function canonOpacity(raw: unknown, dialect: StyleDialect, site: CanonSite): number | null {
+    const value = finite(raw, site);
+    if (value === null) {
+        return null;
+    }
+    const top = dialect === "cytoscape" ? 255 : 1;
+    if (!(value >= 0 && value <= top)) {
+        noteAt(site, STYLE_ISSUE.BAD_VALUE, typeof raw === "string" ? raw : String(raw));
+        return null;
+    }
+    return num6(value / top);
+}
+
+/** Boolean spellings, lowercase. */
+const BOOLEANS: ReadonlyMap<string, boolean> = new Map([
+    ["true", true],
+    ["yes", true],
+    ["on", true],
+    ["1", true],
+    ["false", false],
+    ["no", false],
+    ["off", false],
+    ["0", false],
+]);
+
+/**
+ * A boolean from `true`/`false`, `yes`/`no`, `on`/`off` or `1`/`0` in any case; anything else is null with a note.
+ * @param raw - the file's value
+ * @param site - where it was read
+ * @returns the boolean, or null
+ * @category Styles
+ */
+export function canonBoolean(raw: unknown, site: CanonSite): boolean | null {
+    if (typeof raw === "boolean") {
+        spendAt(site, 1);
+        return raw;
+    }
+    const text = scalarText(raw, site);
+    if (text === null) {
+        return null;
+    }
+    const value = BOOLEANS.get(text.trim().toLowerCase());
+    if (value === undefined) {
+        noteAt(site, STYLE_ISSUE.BAD_VALUE, text);
+        return null;
+    }
+    return value;
+}
+
+/**
+ * The unit of a dialect's lengths: GEXF and Pajek give size factors relative to their tool's normal size, every
+ * other dialect gives pixels (after DOT's inches are converted).
+ * @param dialect - the file's dialect
+ * @returns `"relative"` or `"px"`
+ * @category Styles
+ */
+export function styleLengthUnit(dialect: StyleDialect): "px" | "relative" {
+    return dialect === "gexf" || dialect === "dvips" ? "relative" : "px";
+}

package/src/styles/canon/site.ts

@@ -0,0 +1,87 @@
+/**
+ * Where a raw value came from, so a canonicalizer can note a problem against the right target, property and element
+ * and spend the work it costs from the extraction's one budget.
+ */
+
+import { STYLE_ISSUE } from "../codes.js";
+import type { StyleNotes } from "../notes.js";
+import type { StyleNoteCode, StyleTarget, StyleWorkBudget } from "../types.js";
+
+/**
+ * A number, color, enumeration or mapper expression longer than this many characters is not parsed: it is noted as
+ * `W_STYLE_VALUE_TOO_LONG` and gives no value. Text is copied whatever its length.
+ * @category Styles
+ */
+export const MAX_STYLE_VALUE_LENGTH = 256;
+
+/**
+ * Where a raw value is read: the notes it reports to, the target and property it is for, the element it belongs to
+ * and the budget its work is spent from.
+ * @category Styles
+ */
+export interface CanonSite {
+    /** Where problems are noted. */
+    readonly notes: StyleNotes;
+    /** Nodes, edges or the graph. */
+    readonly target: StyleTarget | "graph";
+    /** The neutral property the value is for. */
+    readonly property: string;
+    /** The element the value belongs to, by index; absent for a rule's value. */
+    readonly element?: number;
+    /** The work budget; each value spends one operation plus one per character it reads. */
+    readonly budget?: StyleWorkBudget;
+}
+
+/**
+ * Notes a problem with a value at its site.
+ * @param site - where the value was read
+ * @param code - the condition
+ * @param sample - the offending value
+ */
+export function noteAt(site: CanonSite, code: StyleNoteCode, sample: unknown): void {
+    site.notes.add(code, site.target, site.property, { sample, element: site.element });
+}
+
+/**
+ * Spends operations from the site's budget; graph values count as node work.
+ * @param site - where the value was read
+ * @param operations - the work
+ */
+export function spendAt(site: CanonSite, operations: number): void {
+    site.budget?.spend(site.target === "graph" ? "node" : site.target, operations);
+}
+
+/**
+ * The text of a raw scalar, untrimmed, after the length limit: null for an absent value (no note), and null with a
+ * note for a value that is empty, too long, not finite or not a scalar. Spends at most 257 operations.
+ * @param raw - the file's value
+ * @param site - where it was read
+ * @returns the value's text, or null
+ */
+export function scalarText(raw: unknown, site: CanonSite): string | null {
+    spendAt(site, 1);
+    if (raw === null || raw === undefined) {
+        return null;
+    }
+    if (typeof raw === "number") {
+        if (Number.isFinite(raw)) {
+            return String(raw);
+        }
+        noteAt(site, STYLE_ISSUE.BAD_VALUE, String(raw));
+        return null;
+    }
+    if (typeof raw !== "string") {
+        noteAt(site, STYLE_ISSUE.BAD_VALUE, typeof raw);
+        return null;
+    }
+    if (raw.length > MAX_STYLE_VALUE_LENGTH) {
+        noteAt(site, STYLE_ISSUE.VALUE_TOO_LONG, `${raw.length} characters`);
+        return null;
+    }
+    spendAt(site, raw.length);
+    if (raw.trim() === "") {
+        noteAt(site, STYLE_ISSUE.BAD_VALUE, raw);
+        return null;
+    }
+    return raw;
+}