@penpair/marwes-ui 0.1.3 → 0.3.0

package/dist/snapshot-file.js

@@ -1,87 +1,329 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
+import { atomicWriteFile, resolveProjectInput, resolveProjectOutput, validateEditableToken, } from "@penpair/core";
 import { canonical } from "./tokens.js";
 export async function readSnapshot(root, file) {
     try {
-        return JSON.parse(await readFile(path.join(root, file), "utf8"));
+        const snapshot = JSON.parse(await readFile(await resolveProjectInput(root, file), "utf8"));
+        if (![
+            1,
+            2,
+        ].includes(snapshot.schemaVersion) ||
+            !Array.isArray(snapshot.sets) ||
+            !Array.isArray(snapshot.themes) ||
+            typeof snapshot.hash !== "string" ||
+            typeof snapshot.project !== "string") {
+            throw new Error("Unsupported or malformed snapshot; regenerate with tokens snapshot --write");
+        }
+        if (snapshot.schemaVersion === 2 &&
+            (!snapshot.ownership ||
+                Object.keys(snapshot.ownership).length !== snapshot.sets.length ||
+                snapshot.sets.some((set) => ![
+                    "adapter",
+                    "project",
+                ].includes(snapshot.ownership?.[set.name] ?? "")))) {
+            throw new Error("Invalid schema-2 set ownership");
+        }
+        return snapshot;
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (error.code === "ENOENT") {
             return undefined;
+        }
         throw new Error(`${file} is not a readable snapshot: ${String(error.message)}`);
     }
 }
 export async function writeSnapshot(root, file, snapshot) {
-    const target = path.join(root, file);
-    await mkdir(path.dirname(target), { recursive: true });
-    await writeFile(target, `${JSON.stringify(snapshot, null, 2)}\n`);
+    const target = await resolveProjectOutput(root, file);
+    await mkdir(path.dirname(target), {
+        recursive: true,
+    });
+    await atomicWriteFile(target, `${JSON.stringify(snapshot, null, 2)}\n`, {
+        replace: true,
+    });
 }
-const show = (token) => (typeof token.value === "string" ? token.value : canonical(token.value));
+const show = (token) => typeof token.value === "string" ? token.value : canonical(token.value);
 /** What differs between two expectations: the Marwes version, then set by set which tokens were added, removed or changed. */
 export function diffSnapshots(before, after) {
     const sets = [];
-    const previous = new Map((before?.sets ?? []).map((s) => [s.name, s]));
-    const next = new Map(after.sets.map((s) => [s.name, s]));
+    const previous = new Map((before?.sets ?? []).map((s) => [
+        s.name,
+        s,
+    ]));
+    const next = new Map(after.sets.map((s) => [
+        s.name,
+        s,
+    ]));
     for (const [name, set] of next) {
         const old = previous.get(name);
-        const oldTokens = new Map((old?.tokens ?? []).map((t) => [t.name, t]));
-        const newTokens = new Map(set.tokens.map((t) => [t.name, t]));
+        const oldTokens = new Map((old?.tokens ?? []).map((t) => [
+            t.name,
+            t,
+        ]));
+        const newTokens = new Map(set.tokens.map((t) => [
+            t.name,
+            t,
+        ]));
         const change = {
             set: name,
-            ...(old ? {} : { setAdded: true }),
-            added: [...newTokens.keys()].filter((n) => !oldTokens.has(n)),
-            removed: [...oldTokens.keys()].filter((n) => !newTokens.has(n)),
-            changed: [...newTokens.entries()].filter(([n, t]) => oldTokens.has(n) && show(oldTokens.get(n)) !== show(t)).map(([n, t]) => ({ name: n, before: show(oldTokens.get(n)), after: show(t) })),
+            ...(old
+                ? {}
+                : {
+                    setAdded: true,
+                }),
+            added: [
+                ...newTokens.keys(),
+            ].filter((n) => !oldTokens.has(n)),
+            removed: [
+                ...oldTokens.keys(),
+            ].filter((n) => !newTokens.has(n)),
+            changed: [
+                ...newTokens.entries(),
+            ]
+                .filter(([n, t]) => oldTokens.has(n) && show(oldTokens.get(n)) !== show(t))
+                .map(([n, t]) => ({
+                name: n,
+                before: show(oldTokens.get(n)),
+                after: show(t),
+            })),
         };
-        if (change.setAdded || change.added.length || change.removed.length || change.changed.length)
+        if (change.setAdded || change.added.length || change.removed.length || change.changed.length) {
             sets.push(change);
+        }
     }
-    for (const [name, old] of previous)
-        if (!next.has(name))
-            sets.push({ set: name, setRemoved: true, added: [], removed: old.tokens.map((t) => t.name), changed: [] });
-    const oldThemes = new Map((before?.themes ?? []).map((t) => [`${t.group}/${t.name}`, t.sets]));
-    const newThemes = new Map(after.themes.map((t) => [`${t.group}/${t.name}`, t.sets]));
+    for (const [name, old] of previous) {
+        if (!next.has(name)) {
+            sets.push({
+                set: name,
+                setRemoved: true,
+                added: [],
+                removed: old.tokens.map((t) => t.name),
+                changed: [],
+            });
+        }
+    }
+    const oldThemes = new Map((before?.themes ?? []).map((t) => [
+        `${t.group}/${t.name}`,
+        t.sets,
+    ]));
+    const newThemes = new Map(after.themes.map((t) => [
+        `${t.group}/${t.name}`,
+        t.sets,
+    ]));
     const themes = {
-        added: [...newThemes.keys()].filter((k) => !oldThemes.has(k)),
-        removed: [...oldThemes.keys()].filter((k) => !newThemes.has(k)),
-        changed: [...newThemes.entries()].filter(([k, s]) => oldThemes.has(k) && canonical(oldThemes.get(k)) !== canonical(s)).map(([k, s]) => ({ theme: k, before: oldThemes.get(k), after: s })),
+        added: [
+            ...newThemes.keys(),
+        ].filter((k) => !oldThemes.has(k)),
+        removed: [
+            ...oldThemes.keys(),
+        ].filter((k) => !newThemes.has(k)),
+        changed: [
+            ...newThemes.entries(),
+        ]
+            .filter(([k, s]) => oldThemes.has(k) && canonical(oldThemes.get(k)) !== canonical(s))
+            .map(([k, s]) => ({
+            theme: k,
+            before: oldThemes.get(k),
+            after: s,
+        })),
     };
     const wasUnmapped = new Set(before?.unmapped ?? []);
     const isUnmapped = new Set(after.unmapped ?? []);
-    const unmapped = { added: [...isUnmapped].filter((v) => !wasUnmapped.has(v)), removed: [...wasUnmapped].filter((v) => !isUnmapped.has(v)) };
-    const versionChange = before && before.marwesVersion !== after.marwesVersion ? { before: before.marwesVersion, after: after.marwesVersion } : undefined;
-    const identical = !!before && !versionChange && sets.length === 0 && !themes.added.length && !themes.removed.length && !themes.changed.length && !unmapped.added.length && !unmapped.removed.length;
-    return { identical, ...(versionChange ? { versionChange } : {}), sets, themes, unmapped };
+    const unmapped = {
+        added: [
+            ...isUnmapped,
+        ].filter((v) => !wasUnmapped.has(v)),
+        removed: [
+            ...wasUnmapped,
+        ].filter((v) => !isUnmapped.has(v)),
+    };
+    const versionChange = before && before.marwesVersion !== after.marwesVersion
+        ? {
+            before: before.marwesVersion,
+            after: after.marwesVersion,
+        }
+        : undefined;
+    const identical = !!before &&
+        !versionChange &&
+        sets.length === 0 &&
+        !themes.added.length &&
+        !themes.removed.length &&
+        !themes.changed.length &&
+        !unmapped.added.length &&
+        !unmapped.removed.length;
+    return {
+        identical,
+        ...(versionChange
+            ? {
+                versionChange,
+            }
+            : {}),
+        sets,
+        themes,
+        unmapped,
+    };
 }
 /** A short, readable account of a diff for the terminal; long lists are cut with a count. */
 export function formatDiff(diff, limit = 8) {
     const lines = [];
-    if (diff.versionChange)
+    if (diff.versionChange) {
         lines.push(`Marwes ${diff.versionChange.before} -> ${diff.versionChange.after}`);
-    const cut = (items) => (items.length > limit ? `${items.slice(0, limit).join(", ")} and ${items.length - limit} more` : items.join(", "));
+    }
+    const cut = (items) => items.length > limit
+        ? `${items.slice(0, limit).join(", ")} and ${items.length - limit} more`
+        : items.join(", ");
     for (const s of diff.sets) {
-        if (s.setAdded)
+        if (s.setAdded) {
             lines.push(`${s.set}: new set with ${s.added.length} tokens`);
-        else if (s.setRemoved)
+        }
+        else if (s.setRemoved) {
             lines.push(`${s.set}: set no longer expected (${s.removed.length} tokens)`);
+        }
         else {
-            if (s.added.length)
+            if (s.added.length) {
                 lines.push(`${s.set}: ${s.added.length} added: ${cut(s.added)}`);
-            if (s.removed.length)
+            }
+            if (s.removed.length) {
                 lines.push(`${s.set}: ${s.removed.length} removed: ${cut(s.removed)}`);
-            if (s.changed.length)
+            }
+            if (s.changed.length) {
                 lines.push(`${s.set}: ${s.changed.length} changed: ${cut(s.changed.map((c) => `${c.name} ${c.before} -> ${c.after}`))}`);
+            }
         }
     }
-    if (diff.unmapped.added.length)
+    if (diff.unmapped.added.length) {
         lines.push(`NEW Marwes variables that are not tokens (the design file does not know them yet; review, then extend the adapter or accept): ${cut(diff.unmapped.added)}`);
-    if (diff.unmapped.removed.length)
+    }
+    if (diff.unmapped.removed.length) {
         lines.push(`Marwes variables that are no longer provided: ${cut(diff.unmapped.removed)}`);
-    for (const t of diff.themes.added)
+    }
+    for (const t of diff.themes.added) {
         lines.push(`theme ${t}: new`);
-    for (const t of diff.themes.removed)
+    }
+    for (const t of diff.themes.removed) {
         lines.push(`theme ${t}: no longer expected`);
-    for (const t of diff.themes.changed)
+    }
+    for (const t of diff.themes.changed) {
         lines.push(`theme ${t.theme}: sets ${t.before.join(" + ")} -> ${t.after.join(" + ")}`);
+    }
     return lines;
 }
+/** Explicitly classify every legacy set; names cannot establish ownership. Original fields survive migration. */
+export function migrateTokenSnapshot(raw, ownership) {
+    const source = raw;
+    if (!source ||
+        source.schemaVersion !== 1 ||
+        !Array.isArray(source.sets) ||
+        !Array.isArray(source.themes) ||
+        !Array.isArray(source.unmapped) ||
+        typeof source.marwesVersion !== "string" ||
+        typeof source.project !== "string") {
+        throw new Error("Migration requires a readable legacy schema-1 token snapshot; unsupported majors need producer guidance");
+    }
+    if (!ownership ||
+        typeof ownership !== "object" ||
+        Array.isArray(ownership) ||
+        Object.keys(ownership).length !== source.sets.length ||
+        source.sets.some((set) => ![
+            "adapter",
+            "project",
+        ].includes(ownership[set.name] ?? "")) ||
+        new Set(source.sets.map((set) => set.name)).size !== source.sets.length) {
+        throw new Error("Explicit adapter/project ownership is required for every legacy set, with no extra names");
+    }
+    for (const set of source.sets) {
+        if (!set || typeof set.name !== "string" || !Array.isArray(set.tokens)) {
+            throw new Error("Malformed legacy set");
+        }
+        const names = new Set();
+        for (const token of set.tokens) {
+            validateEditableToken(token);
+            if (names.has(token.name)) {
+                throw new Error("Duplicate legacy token");
+            }
+            names.add(token.name);
+        }
+    }
+    if (source.unmapped.some((value) => typeof value !== "string") ||
+        source.themes.some((theme) => !theme ||
+            typeof theme.group !== "string" ||
+            typeof theme.name !== "string" ||
+            !Array.isArray(theme.sets) ||
+            theme.sets.some((name) => !source.sets.some((set) => set.name === name)))) {
+        throw new Error("Malformed legacy themes/unmapped variables");
+    }
+    const migrated = {
+        ...structuredClone(source),
+        schemaVersion: 2,
+        ownership: structuredClone(ownership),
+    };
+    const { marwesVersion, project, sets, themes, unmapped } = migrated;
+    migrated.hash = createHash("sha256")
+        .update(canonical({
+        marwesVersion,
+        project,
+        sets,
+        themes,
+        unmapped,
+        ownership: migrated.ownership,
+    }))
+        .digest("hex");
+    return migrated;
+}
+export const tokenSnapshotSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "urn:penpair:schema:v2:adapter-token-snapshot",
+    type: "object",
+    required: [
+        "schemaVersion",
+        "ownership",
+        "marwesVersion",
+        "generatedBy",
+        "project",
+        "hash",
+        "sets",
+        "themes",
+        "unmapped",
+    ],
+    properties: {
+        schemaVersion: {
+            const: 2,
+        },
+        ownership: {
+            type: "object",
+            additionalProperties: {
+                enum: [
+                    "adapter",
+                    "project",
+                ],
+            },
+        },
+        marwesVersion: {
+            type: "string",
+        },
+        generatedBy: {
+            type: "string",
+        },
+        project: {
+            type: "string",
+        },
+        hash: {
+            type: "string",
+            pattern: "^[a-f0-9]{64}$",
+        },
+        sets: {
+            type: "array",
+        },
+        themes: {
+            type: "array",
+        },
+        unmapped: {
+            type: "array",
+            items: {
+                type: "string",
+            },
+        },
+    },
+    additionalProperties: true,
+};

package/dist/theme-input.js

@@ -1,21 +1,32 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
-import path from "node:path";
+import { resolveProjectInput } from "@penpair/core";
 import { createJiti } from "jiti";
 /** Loads a theme the project already has, as the app itself would: the same file, the same export. */
 export async function loadThemeInput(root, reference) {
-    const file = path.resolve(root, reference.module);
+    let file;
     let source;
     try {
+        file = await resolveProjectInput(root, reference.module);
         source = await readFile(file);
     }
-    catch {
-        throw new Error(`The theme file ${reference.module} does not exist (marwes.themes in penpair.config.json).`);
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`The theme file ${reference.module} does not exist (marwes.themes in penpair.config.json).`);
+        }
+        throw error;
     }
-    const jiti = createJiti(file, { interopDefault: true, moduleCache: false });
+    const jiti = createJiti(file, {
+        interopDefault: true,
+        moduleCache: false,
+    });
     const loaded = (await jiti.import(file));
     const input = loaded[reference.export];
-    if (typeof input !== "object" || input === null)
+    if (typeof input !== "object" || input === null) {
         throw new Error(`${reference.module} has no object export named ${reference.export}.`);
-    return { input: input, fileHash: createHash("sha256").update(source).digest("hex").slice(0, 12) };
+    }
+    return {
+        input: input,
+        fileHash: createHash("sha256").update(source).digest("hex").slice(0, 12),
+    };
 }

package/dist/theme-lint.d.ts

@@ -0,0 +1,31 @@
+import type { TokenSnapshot } from "./tokens.js";
+export interface ThemeLintSettings {
+    hueThresholdDegrees?: number;
+    suppressions?: Array<{
+        theme: "light" | "dark";
+        token: string;
+        reason: string;
+    }>;
+}
+export declare function readThemeLint(value: unknown): ThemeLintSettings;
+export declare function lintThemeFamily(defaults: TokenSnapshot, project: TokenSnapshot, rawSettings?: ThemeLintSettings): {
+    schemaVersion: number;
+    kind: string;
+    advisory: boolean;
+    warnings: {
+        theme: string;
+        token: string;
+        default: unknown;
+        actual: unknown;
+        primary: unknown;
+        hueDistance: number;
+        suppression?: string;
+    }[];
+    unknown: {
+        theme: string;
+        token: string;
+        reason: string;
+    }[];
+    assumptions: string[];
+    changed: boolean;
+};

package/dist/theme-lint.js

@@ -0,0 +1,145 @@
+export function readThemeLint(value) {
+    if (value === undefined) {
+        return {};
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("marwes.themeLint must be an object");
+    }
+    const v = value;
+    if (Object.keys(v).some((k) => ![
+        "hueThresholdDegrees",
+        "suppressions",
+    ].includes(k)) ||
+        (v.hueThresholdDegrees !== undefined &&
+            (!Number.isFinite(v.hueThresholdDegrees) ||
+                v.hueThresholdDegrees < 0 ||
+                v.hueThresholdDegrees > 180))) {
+        throw new Error("Invalid theme lint threshold/settings");
+    }
+    if (v.suppressions !== undefined &&
+        (!Array.isArray(v.suppressions) ||
+            v.suppressions.length > 1000 ||
+            v.suppressions.some((s) => !s ||
+                ![
+                    "light",
+                    "dark",
+                ].includes(s.theme) ||
+                typeof s.token !== "string" ||
+                !s.token ||
+                typeof s.reason !== "string" ||
+                !s.reason.trim() ||
+                s.reason.length > 1000))) {
+        throw new Error("Theme lint suppressions need exact mode/token and a reason");
+    }
+    return structuredClone(v);
+}
+function hue(value) {
+    if (typeof value !== "string" || !/^#[\da-f]{6}(?:ff)?$/i.test(value)) {
+        return;
+    }
+    const [r, g, b] = [
+        1,
+        3,
+        5,
+    ].map((i) => parseInt(value.slice(i, i + 2), 16) / 255);
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const delta = max - min;
+    if (!delta) {
+        return {
+            hue: 0,
+            saturation: 0,
+        };
+    }
+    let h = max === r ? ((g - b) / delta) % 6 : max === g ? (b - r) / delta + 2 : (r - g) / delta + 4;
+    h = (((h * 60) % 360) + 360) % 360;
+    return {
+        hue: h,
+        saturation: max === 0 ? 0 : delta / max,
+    };
+}
+function colors(snapshot, mode) {
+    const result = new Map();
+    const theme = snapshot.themes.find((t) => t.group === "Mode" && t.name.toLowerCase() === mode);
+    for (const name of theme?.sets ?? []) {
+        for (const token of snapshot.sets.find((s) => s.name === name)?.tokens ?? []) {
+            if (token.type === "color") {
+                result.set(token.name, token.value);
+            }
+        }
+    }
+    return result;
+}
+export function lintThemeFamily(defaults, project, rawSettings = {}) {
+    const settings = readThemeLint(rawSettings);
+    const warnings = [];
+    const unknown = [];
+    for (const mode of [
+        "light",
+        "dark",
+    ]) {
+        const base = colors(defaults, mode);
+        const current = colors(project, mode);
+        const anchor = "mw-color-primary-base";
+        const primary = current.get(anchor);
+        const original = base.get(anchor);
+        if (primary === undefined || original === undefined || primary === original) {
+            continue;
+        }
+        const anchorHue = hue(primary);
+        if (!anchorHue || anchorHue.saturation < 0.15) {
+            unknown.push({
+                theme: mode,
+                token: anchor,
+                reason: "Primary is transparent, non-literal or achromatic; hue comparison is not meaningful",
+            });
+            continue;
+        }
+        for (const [token, value] of current) {
+            if (!/^mw-color-(?:border-brand|text-(?:brand|link)|focus(?:-.+)?|surface-brand|secondary(?:-.+)?)$/.test(token) ||
+                value !== base.get(token)) {
+                continue;
+            }
+            const other = hue(value);
+            if (!other || other.saturation < 0.15) {
+                unknown.push({
+                    theme: mode,
+                    token,
+                    reason: "Default sibling hue is unavailable or achromatic",
+                });
+                continue;
+            }
+            const delta = Math.abs(anchorHue.hue - other.hue);
+            const distance = Math.min(delta, 360 - delta);
+            if (distance < (settings.hueThresholdDegrees ?? 30)) {
+                continue;
+            }
+            const suppression = settings.suppressions?.find((s) => s.theme === mode && s.token === token)?.reason;
+            warnings.push({
+                theme: mode,
+                token,
+                default: base.get(token),
+                actual: value,
+                primary,
+                hueDistance: distance,
+                ...(suppression
+                    ? {
+                        suppression,
+                    }
+                    : {}),
+            });
+        }
+    }
+    return {
+        schemaVersion: 1,
+        kind: "theme-family-lint",
+        advisory: true,
+        warnings,
+        unknown,
+        assumptions: [
+            "Hue distance on opaque literal colors is a heuristic, not a brand or accessibility rule.",
+            "Unchanged family defaults may be intentional; retain a reasoned suppression rather than rewriting them automatically.",
+        ],
+        changed: false,
+    };
+}

package/dist/tokens.d.ts

@@ -1,4 +1,5 @@
-export type PenpotTokenType = "color" | "spacing" | "sizing" | "borderRadius" | "fontFamilies" | "typography";
+import { tokenTypes } from "@penpair/core";
+export type PenpotTokenType = (typeof tokenTypes)[number];
 export interface PenpotToken {
     name: string;
     type: PenpotTokenType;
@@ -17,7 +18,9 @@ export interface PenpotTokenTheme {
 }
 /** What the Penpot file is expected to hold: generated from the installed Marwes and the project's theme, committed to the project. */
 export interface TokenSnapshot {
-    schemaVersion: 1;
+    schemaVersion: 1 | 2;
+    /** Version 2 explicitly records ownership. Missing only in legacy v1 inputs. */
+    ownership?: Record<string, "adapter" | "project">;
     /** The Marwes version the values came from. */
     marwesVersion: string;
     /** What produced the file, so a reader knows not to edit it by hand. */
@@ -64,6 +67,7 @@ export interface SnapshotInput {
     /** The project's name, which prefixes its overlay sets. */
     name: string;
     generatedBy: string;
+    extras?: PenpotTokenSet[];
 }
 /**
  * The Penpot token sets for Marwes and for the project, generated from the installed Marwes. Light values live in the core set,