@penpair/core 0.2.0 → 0.3.0

package/dist/audit-rules.js

@@ -1,99 +1,227 @@
 import { validateDesignInspection } from "./design-spec.js";
 import { observationHash } from "./journal.js";
 export function validateAuditRules(raw) {
-    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
         throw new Error("audit must be an object");
+    }
     const v = raw;
-    const keys = ["contrast", "library", "touchTargets", "names", "blankText", "interactiveIds", "allowBlank", "nameSegments", "suppressions"];
-    if (Object.keys(v).some(k => !keys.includes(k)))
+    const keys = [
+        "contrast",
+        "library",
+        "touchTargets",
+        "names",
+        "blankText",
+        "interactiveIds",
+        "allowBlank",
+        "nameSegments",
+        "suppressions",
+    ];
+    if (Object.keys(v).some((k) => !keys.includes(k))) {
         throw new Error("Unknown audit setting");
-    for (const key of ["contrast", "library", "touchTargets", "names", "blankText"])
-        if (v[key] !== undefined && typeof v[key] !== "boolean")
+    }
+    for (const key of [
+        "contrast",
+        "library",
+        "touchTargets",
+        "names",
+        "blankText",
+    ]) {
+        if (v[key] !== undefined && typeof v[key] !== "boolean") {
             throw new Error("Audit rule toggles must be booleans");
-    for (const entries of [v.interactiveIds, v.allowBlank])
-        if (entries !== undefined && (!Array.isArray(entries) || entries.length > 1000 || entries.some(s => typeof s !== "string" || !s || s.length > 200)))
+        }
+    }
+    for (const entries of [
+        v.interactiveIds,
+        v.allowBlank,
+    ]) {
+        if (entries !== undefined &&
+            (!Array.isArray(entries) ||
+                entries.length > 1000 ||
+                entries.some((s) => typeof s !== "string" || !s || s.length > 200))) {
             throw new Error("Audit ID lists must have at most 1000 explicit IDs");
-    if (v.nameSegments !== undefined && (!Number.isInteger(v.nameSegments) || v.nameSegments < 1 || v.nameSegments > 10))
+        }
+    }
+    if (v.nameSegments !== undefined &&
+        (!Number.isInteger(v.nameSegments) || v.nameSegments < 1 || v.nameSegments > 10)) {
         throw new Error("Audit nameSegments must be 1–10");
-    if (v.suppressions !== undefined && (!Array.isArray(v.suppressions) || v.suppressions.length > 1000 || v.suppressions.some(s => !s || !["contrast", "library", "touch-target", "names", "blank-text"].includes(s.rule) || typeof s.nodeId !== "string" || !s.nodeId || typeof s.reason !== "string" || !s.reason.trim() || s.reason.length > 1000)))
+    }
+    if (v.suppressions !== undefined &&
+        (!Array.isArray(v.suppressions) ||
+            v.suppressions.length > 1000 ||
+            v.suppressions.some((s) => !s ||
+                ![
+                    "contrast",
+                    "library",
+                    "touch-target",
+                    "names",
+                    "blank-text",
+                ].includes(s.rule) ||
+                typeof s.nodeId !== "string" ||
+                !s.nodeId ||
+                typeof s.reason !== "string" ||
+                !s.reason.trim() ||
+                s.reason.length > 1000))) {
         throw new Error("Audit suppressions require exact rule/node ID and reason");
+    }
     return structuredClone(v);
 }
 /** Opaque sRGB subset only. Alpha/multiple paints/images require a richer compositing model. */
 export function opaqueRgb(raw) {
-    if (typeof raw !== "string")
+    if (typeof raw !== "string") {
         return;
+    }
     const match = /^#([a-f0-9]{6})(ff)?$/i.exec(raw);
-    if (!match)
+    if (!match) {
         return;
-    return [0, 2, 4].map(i => parseInt(match[1].slice(i, i + 2), 16) / 255);
+    }
+    return [
+        0,
+        2,
+        4,
+    ].map((i) => parseInt(match[1].slice(i, i + 2), 16) / 255);
 }
 export function contrastRatio(a, b) {
-    const luminance = (rgb) => rgb.map(c => c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4).reduce((n, c, i) => n + c * [0.2126, 0.7152, 0.0722][i], 0);
-    const x = luminance(a), y = luminance(b);
+    const luminance = (rgb) => rgb
+        .map((c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4))
+        .reduce((n, c, i) => n +
+        c *
+            [
+                0.2126,
+                0.7152,
+                0.0722,
+            ][i], 0);
+    const x = luminance(a);
+    const y = luminance(b);
     return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05);
 }
 function resolvedColors(tokens, shapes) {
     const result = new Map();
-    if (!tokens || tokens.schemaVersion !== 1 || tokens.kind !== "token-inspection" || tokens.complete !== true || tokens.redacted === true || tokens.fileId !== shapes.fileId || tokens.revision !== shapes.revision || !Array.isArray(tokens.sets))
+    if (!tokens ||
+        tokens.schemaVersion !== 1 ||
+        tokens.kind !== "token-inspection" ||
+        tokens.complete !== true ||
+        tokens.redacted === true ||
+        tokens.fileId !== shapes.fileId ||
+        tokens.revision !== shapes.revision ||
+        !Array.isArray(tokens.sets)) {
         return result;
-    for (const set of [...tokens.sets].sort((a, b) => Number(a.order) - Number(b.order))) {
-        if (set.active !== true || !Array.isArray(set.tokens))
+    }
+    for (const set of [
+        ...tokens.sets,
+    ].sort((a, b) => Number(a.order) - Number(b.order))) {
+        if (set.active !== true || !Array.isArray(set.tokens)) {
             continue;
+        }
         for (const token of set.tokens) {
-            if (typeof token.name !== "string")
+            if (typeof token.name !== "string") {
                 continue;
+            }
             result.delete(token.name);
-            if (token.type === "color" && (!Array.isArray(token.unknowns) || !token.unknowns.some(k => k === "resolvedValue" || k === "type"))) {
+            if (token.type === "color" &&
+                (!Array.isArray(token.unknowns) ||
+                    !token.unknowns.some((k) => k === "resolvedValue" || k === "type"))) {
                 const rgb = opaqueRgb(token.resolvedValue);
-                if (rgb)
+                if (rgb) {
                     result.set(token.name, rgb);
+                }
             }
         }
     }
     return result;
 }
 export function auditDesignRules(raw, rawRules, tokenInspection, limit = 1000) {
-    const source = validateDesignInspection(raw), rules = validateAuditRules(rawRules);
-    if (!Number.isInteger(limit) || limit < 1 || limit > 10000)
+    const source = validateDesignInspection(raw);
+    const rules = validateAuditRules(rawRules);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 10000) {
         throw new Error("Audit finding limit must be 1–10000");
+    }
     const findings = [];
-    let totalFindings = 0, suppressed = 0, contrastMeasured = 0, contrastUnknown = 0, copies = 0, knownComponents = 0, unknownComponents = 0;
-    const rows = new Map(source.nodes.map(n => [String(n.id), n])), colors = resolvedColors(tokenInspection, source);
+    let totalFindings = 0;
+    let suppressed = 0;
+    let contrastMeasured = 0;
+    let contrastUnknown = 0;
+    let copies = 0;
+    let knownComponents = 0;
+    let unknownComponents = 0;
+    const rows = new Map(source.nodes.map((n) => [
+        String(n.id),
+        n,
+    ]));
+    const colors = resolvedColors(tokenInspection, source);
     const add = (finding) => {
         totalFindings++;
-        const suppression = rules.suppressions?.find(s => s.rule === finding.rule && s.nodeId === finding.nodeId);
-        if (suppression)
+        const suppression = rules.suppressions?.find((s) => s.rule === finding.rule && s.nodeId === finding.nodeId);
+        if (suppression) {
             suppressed++;
-        if (findings.length < limit)
-            findings.push({ ...finding, ...(suppression ? { suppression: suppression.reason } : {}) });
+        }
+        if (findings.length < limit) {
+            findings.push({
+                ...finding,
+                ...(suppression
+                    ? {
+                        suppression: suppression.reason,
+                    }
+                    : {}),
+            });
+        }
     };
     const paint = (node) => {
-        const style = node.style, bindings = node.tokens;
-        if (!style || style.opacity !== 1 && style.opacity !== undefined || style.blendMode !== "normal" && style.blendMode !== undefined)
-            return { reason: "Unknown/transparent/blended node style" };
+        const style = node.style;
+        const bindings = node.tokens;
+        if (!style ||
+            (style.opacity !== 1 && style.opacity !== undefined) ||
+            (style.blendMode !== "normal" && style.blendMode !== undefined)) {
+            return {
+                reason: "Unknown/transparent/blended node style",
+            };
+        }
         const fills = style.fills;
-        if (!Array.isArray(fills))
-            return { reason: "Fill observation unavailable" };
-        if (!fills.length)
-            return { absent: true };
-        if (fills.length !== 1 || !fills[0] || typeof fills[0] !== "object")
-            return { reason: "Multiple or unsupported paints" };
+        if (!Array.isArray(fills)) {
+            return {
+                reason: "Fill observation unavailable",
+            };
+        }
+        if (!fills.length) {
+            return {
+                absent: true,
+            };
+        }
+        if (fills.length !== 1 || !fills[0] || typeof fills[0] !== "object") {
+            return {
+                reason: "Multiple or unsupported paints",
+            };
+        }
         const fill = fills[0];
-        if (fill.fillOpacity !== undefined && fill.fillOpacity !== 1 || fill.fillColorGradient || fill.fillImage || fill.fillType && fill.fillType !== "solid")
-            return { reason: "Gradient/image/alpha paint" };
+        if ((fill.fillOpacity !== undefined && fill.fillOpacity !== 1) ||
+            fill.fillColorGradient ||
+            fill.fillImage ||
+            (fill.fillType && fill.fillType !== "solid")) {
+            return {
+                reason: "Gradient/image/alpha paint",
+            };
+        }
         const name = bindings?.fill;
-        if (typeof name !== "string" || !colors.has(name))
-            return { reason: "No independently resolved opaque bound color" };
+        if (typeof name !== "string" || !colors.has(name)) {
+            return {
+                reason: "No independently resolved opaque bound color",
+            };
+        }
         const actual = opaqueRgb(fill.fillColor);
-        if (!actual || observationHash(actual) !== observationHash(colors.get(name)))
-            return { reason: "Observed paint differs from resolved bound color" };
-        return { rgb: colors.get(name) };
+        if (!actual || observationHash(actual) !== observationHash(colors.get(name))) {
+            return {
+                reason: "Observed paint differs from resolved bound color",
+            };
+        }
+        return {
+            rgb: colors.get(name),
+        };
     };
     const backgroundCache = new Map();
     const backgroundFor = (parent) => {
         const visited = [];
-        let result = { reason: "No opaque ancestor background" };
+        let result = {
+            reason: "No opaque ancestor background",
+        };
         while (typeof parent === "string") {
             if (backgroundCache.has(parent)) {
                 result = backgroundCache.get(parent);
@@ -102,76 +230,214 @@ export function auditDesignRules(raw, rawRules, tokenInspection, limit = 1000) {
             const ancestor = rows.get(parent);
             result = paint(ancestor);
             visited.push(parent);
-            if (!result.absent)
+            if (!result.absent) {
                 break;
+            }
             parent = ancestor.parentId;
         }
-        if (result.absent)
-            result = { reason: "No opaque ancestor background" };
-        for (const id of visited)
+        if (result.absent) {
+            result = {
+                reason: "No opaque ancestor background",
+            };
+        }
+        for (const id of visited) {
             backgroundCache.set(id, result);
+        }
         return result;
     };
-    const rootId = source.nodes.find(n => n.parentId === null)?.id;
+    const rootId = source.nodes.find((n) => n.parentId === null)?.id;
     const largest = [];
-    const considered = source.nodes.filter(n => n.parentId !== null && n.geometry?.hidden !== true);
+    const considered = source.nodes.filter((n) => n.parentId !== null &&
+        n.geometry?.hidden !== true);
     for (const node of considered) {
-        const id = String(node.id), geometry = node.geometry;
+        const id = String(node.id);
+        const geometry = node.geometry;
         if (rules.names) {
-            if (["Board", "Rectangle", "Group"].includes(String(node.name)))
-                add({ rule: "names", nodeId: id, severity: "info", state: "finding", detail: "Default layer name" });
-            if (node.type === "board" && node.parentId === rootId && (String(node.name).split("/").length !== (rules.nameSegments ?? 3) || String(node.name).split("/").some(s => !s.trim())))
-                add({ rule: "names", nodeId: id, severity: "info", state: "finding", detail: "Frame name differs from declared slash-separated page/state/device convention" });
+            if ([
+                "Board",
+                "Rectangle",
+                "Group",
+            ].includes(String(node.name))) {
+                add({
+                    rule: "names",
+                    nodeId: id,
+                    severity: "info",
+                    state: "finding",
+                    detail: "Default layer name",
+                });
+            }
+            if (node.type === "board" &&
+                node.parentId === rootId &&
+                (String(node.name).split("/").length !== (rules.nameSegments ?? 3) ||
+                    String(node.name)
+                        .split("/")
+                        .some((s) => !s.trim()))) {
+                add({
+                    rule: "names",
+                    nodeId: id,
+                    severity: "info",
+                    state: "finding",
+                    detail: "Frame name differs from declared slash-separated page/state/device convention",
+                });
+            }
         }
         if (rules.blankText && node.type === "text" && !rules.allowBlank?.includes(id)) {
             const text = node.text?.characters;
-            if (typeof text !== "string")
-                add({ rule: "blank-text", nodeId: id, severity: "info", state: "unknown", detail: "Text not observed" });
-            else if (!text.trim() || /^(?:lorem ipsum|placeholder|todo)(?:\b|$)/i.test(text.trim()))
-                add({ rule: "blank-text", nodeId: id, severity: "info", state: "finding", detail: "Blank or placeholder text" });
+            if (typeof text !== "string") {
+                add({
+                    rule: "blank-text",
+                    nodeId: id,
+                    severity: "info",
+                    state: "unknown",
+                    detail: "Text not observed",
+                });
+            }
+            else if (!text.trim() || /^(?:lorem ipsum|placeholder|todo)(?:\b|$)/i.test(text.trim())) {
+                add({
+                    rule: "blank-text",
+                    nodeId: id,
+                    severity: "info",
+                    state: "finding",
+                    detail: "Blank or placeholder text",
+                });
+            }
         }
         if (rules.library) {
             const component = node.component;
-            if (typeof component?.isComponentCopyInstance !== "boolean")
+            if (typeof component?.isComponentCopyInstance !== "boolean") {
                 unknownComponents++;
+            }
             else {
                 knownComponents++;
-                if (component.isComponentCopyInstance)
+                if (component.isComponentCopyInstance) {
                     copies++;
-                else if (["board", "group"].includes(String(node.type)) && typeof geometry?.width === "number" && typeof geometry?.height === "number")
-                    largest.push({ id, area: geometry.width * geometry.height });
+                }
+                else if ([
+                    "board",
+                    "group",
+                ].includes(String(node.type)) &&
+                    typeof geometry?.width === "number" &&
+                    typeof geometry?.height === "number") {
+                    largest.push({
+                        id,
+                        area: geometry.width * geometry.height,
+                    });
+                }
             }
         }
         if (rules.contrast && node.type === "text") {
             let foreground = paint(node);
             const background = backgroundFor(node.parentId);
             const unknowns = node.unknowns;
-            if (unknowns?.includes("text.mixedRangeStyles"))
-                foreground = { reason: "Mixed text range styles" };
+            if (unknowns?.includes("text.mixedRangeStyles")) {
+                foreground = {
+                    reason: "Mixed text range styles",
+                };
+            }
             if (!foreground.rgb || !background.rgb) {
                 contrastUnknown++;
-                add({ rule: "contrast", nodeId: id, severity: "info", state: "unknown", detail: foreground.reason ?? background.reason ?? "Opaque bound colors unavailable" });
+                add({
+                    rule: "contrast",
+                    nodeId: id,
+                    severity: "info",
+                    state: "unknown",
+                    detail: foreground.reason ?? background.reason ?? "Opaque bound colors unavailable",
+                });
             }
             else {
                 contrastMeasured++;
                 const typography = node.text?.typography;
-                const size = Number(typography?.fontSize), weight = Number(typography?.fontWeight), threshold = Number.isFinite(size) && (size >= 24 || size >= 56 / 3 && weight >= 700) ? 3 : 4.5;
+                const size = Number(typography?.fontSize);
+                const weight = Number(typography?.fontWeight);
+                const threshold = Number.isFinite(size) && (size >= 24 || (size >= 56 / 3 && weight >= 700)) ? 3 : 4.5;
                 const ratio = contrastRatio(foreground.rgb, background.rgb);
-                if (ratio < threshold)
-                    add({ rule: "contrast", nodeId: id, severity: "warning", state: "finding", detail: "Observed opaque text/background contrast below the review threshold", evidence: { ratio, threshold, assumption: "Design units treated as CSS px; exceptions and implementation rendering unassessed" } });
+                if (ratio < threshold) {
+                    add({
+                        rule: "contrast",
+                        nodeId: id,
+                        severity: "warning",
+                        state: "finding",
+                        detail: "Observed opaque text/background contrast below the review threshold",
+                        evidence: {
+                            ratio,
+                            threshold,
+                            assumption: "Design units treated as CSS px; exceptions and implementation rendering unassessed",
+                        },
+                    });
+                }
             }
         }
     }
-    if (rules.touchTargets)
+    if (rules.touchTargets) {
         for (const id of rules.interactiveIds ?? []) {
-            const node = rows.get(id), g = node?.geometry;
-            if (!node || typeof g?.width !== "number" || typeof g.height !== "number" || !Number.isFinite(g.width) || !Number.isFinite(g.height) || g.width < 0 || g.height < 0)
-                add({ rule: "touch-target", nodeId: id, severity: "info", state: "unknown", detail: "Explicit interactive target dimensions unavailable" });
-            else if (g.width < 44 || g.height < 44)
-                add({ rule: "touch-target", nodeId: id, severity: g.width < 24 || g.height < 24 ? "warning" : "info", state: "finding", detail: g.width < 24 || g.height < 24 ? "Below 24-unit size signal" : "Below 44-unit preference", evidence: { width: g.width, height: g.height, assessment: "size-signal-only; spacing, exceptions, input semantics and CSS scale unassessed" } });
+            const node = rows.get(id);
+            const g = node?.geometry;
+            if (!node ||
+                typeof g?.width !== "number" ||
+                typeof g.height !== "number" ||
+                !Number.isFinite(g.width) ||
+                !Number.isFinite(g.height) ||
+                g.width < 0 ||
+                g.height < 0) {
+                add({
+                    rule: "touch-target",
+                    nodeId: id,
+                    severity: "info",
+                    state: "unknown",
+                    detail: "Explicit interactive target dimensions unavailable",
+                });
+            }
+            else if (g.width < 44 || g.height < 44) {
+                add({
+                    rule: "touch-target",
+                    nodeId: id,
+                    severity: g.width < 24 || g.height < 24 ? "warning" : "info",
+                    state: "finding",
+                    detail: g.width < 24 || g.height < 24
+                        ? "Below 24-unit size signal"
+                        : "Below 44-unit preference",
+                    evidence: {
+                        width: g.width,
+                        height: g.height,
+                        assessment: "size-signal-only; spacing, exceptions, input semantics and CSS scale unassessed",
+                    },
+                });
+            }
         }
+    }
     largest.sort((a, b) => b.area - a.area || a.id.localeCompare(b.id));
-    return { schemaVersion: 1, kind: "design-audit", source: { fileId: source.fileId, pageId: source.pageId, revision: source.revision, hash: observationHash(source.nodes) }, advisory: true, accessibilityCompliance: "not-assessed", complete: totalFindings <= limit, totalFindings, suppressed, findings,
-        contrast: { measured: contrastMeasured, unknown: contrastUnknown }, library: rules.library ? { instances: copies, knownNodes: knownComponents, unknownNodes: unknownComponents, shareOfKnown: knownComponents ? copies / knownComponents : null, largestPrimitiveGroups: largest.slice(0, 10) } : null,
-        assumptions: ["Complete captured subtree only; hidden ancestors and overlapping/composited paints need independent review.", "Interactive IDs are explicit declarations, not inferred clickability or WCAG compliance.", "Unavailable resolved colors and mixed styles remain unknown; rules never mutate or block by default."] };
+    return {
+        schemaVersion: 1,
+        kind: "design-audit",
+        source: {
+            fileId: source.fileId,
+            pageId: source.pageId,
+            revision: source.revision,
+            hash: observationHash(source.nodes),
+        },
+        advisory: true,
+        accessibilityCompliance: "not-assessed",
+        complete: totalFindings <= limit,
+        totalFindings,
+        suppressed,
+        findings,
+        contrast: {
+            measured: contrastMeasured,
+            unknown: contrastUnknown,
+        },
+        library: rules.library
+            ? {
+                instances: copies,
+                knownNodes: knownComponents,
+                unknownNodes: unknownComponents,
+                shareOfKnown: knownComponents ? copies / knownComponents : null,
+                largestPrimitiveGroups: largest.slice(0, 10),
+            }
+            : null,
+        assumptions: [
+            "Complete captured subtree only; hidden ancestors and overlapping/composited paints need independent review.",
+            "Interactive IDs are explicit declarations, not inferred clickability or WCAG compliance.",
+            "Unavailable resolved colors and mixed styles remain unknown; rules never mutate or block by default.",
+        ],
+    };
 }

package/dist/backup-note.js

@@ -2,9 +2,16 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 /** An optional advisory record, not proof that an archive can be restored. Disabled unless configured. */
 export async function backupNoteCheck(root, config, now = new Date()) {
-    if (!config.backup)
+    if (!config.backup) {
         return undefined;
-    const warn = (detail) => ({ check: "backup note", ok: true, warning: true, detail, remedy: "Export a current archive, restore it into scratch, then update the backup note; see docs/backup.md." });
+    }
+    const warn = (detail) => ({
+        check: "backup note",
+        ok: true,
+        warning: true,
+        detail,
+        remedy: "Export a current archive, restore it into scratch, then update the backup note; see docs/backup.md.",
+    });
     let note;
     try {
         note = JSON.parse(await readFile(path.join(root, config.backup.noteFile), "utf8"));
@@ -12,17 +19,31 @@ export async function backupNoteCheck(root, config, now = new Date()) {
     catch {
         return warn("No readable backup note; archive/restore status is unknown");
     }
-    if (!note || note.schemaVersion !== 1 || typeof note.fileId !== "string" || typeof note.recordedAt !== "string" || typeof note.archiveSha256 !== "string" || !/^[a-f0-9]{64}$/i.test(note.archiveSha256))
+    if (!note ||
+        note.schemaVersion !== 1 ||
+        typeof note.fileId !== "string" ||
+        typeof note.recordedAt !== "string" ||
+        typeof note.archiveSha256 !== "string" ||
+        !/^[a-f0-9]{64}$/i.test(note.archiveSha256)) {
         return warn("Backup note is incomplete or invalid; archive/restore status is unknown");
-    if (!config.file || note.fileId !== config.file.id)
+    }
+    if (!config.file || note.fileId !== config.file.id) {
         return warn("Backup note does not match a pinned project file");
+    }
     const timestamp = Date.parse(note.recordedAt);
     const age = now.getTime() - timestamp;
-    if (!Number.isFinite(timestamp) || age < 0)
+    if (!Number.isFinite(timestamp) || age < 0) {
         return warn("Backup note has an invalid or future date");
-    if (age >= config.backup.remindAfterDays * 86_400_000)
+    }
+    if (age >= config.backup.remindAfterDays * 86_400_000) {
         return warn(`Backup note is ${Math.floor(age / 86_400_000)} days old; refresh the archive and restore evidence`);
-    if (note.restoreVerified !== true)
+    }
+    if (note.restoreVerified !== true) {
         return warn("Archive recorded recently, but its restore is not recorded as verified");
-    return { check: "backup note", ok: true, detail: "Recent owner-maintained backup/restore note matches the pinned file (a note is not independent restore proof)" };
+    }
+    return {
+        check: "backup note",
+        ok: true,
+        detail: "Recent owner-maintained backup/restore note matches the pinned file (a note is not independent restore proof)",
+    };
 }