nnw-theme 0.0.0 → 1.0.0

package/dist/plist.js

@@ -0,0 +1,175 @@
+// XML property lists, read and written the way Python's plistlib does, so an
+// Info.plist that init or bump rewrites is byte-identical to the Python tool's.
+import { Parser } from "htmlparser2";
+/** A <real>, kept apart from <integer> so a Version of 1.0 is still rejected. */
+export class PlistReal {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+}
+function tree(text) {
+    const root = { name: "#root", children: [], text: "" };
+    const stack = [root];
+    let failure;
+    const parser = new Parser({
+        onopentag(name) {
+            const node = { name, children: [], text: "" };
+            stack.at(-1)?.children.push(node);
+            stack.push(node);
+        },
+        ontext(data) {
+            const node = stack.at(-1);
+            if (node)
+                node.text += data;
+        },
+        onclosetag(name) {
+            if (stack.at(-1)?.name !== name)
+                failure ??= new Error(`mismatched tag </${name}>`);
+            stack.pop();
+        },
+        onerror(error) {
+            failure ??= error;
+        },
+    }, { xmlMode: true, decodeEntities: true });
+    parser.end(text);
+    if (failure)
+        throw failure;
+    if (stack.length !== 1)
+        throw new Error("unclosed element");
+    return root;
+}
+function value(node) {
+    switch (node.name) {
+        case "dict": {
+            const result = {};
+            const children = node.children;
+            for (let index = 0; index < children.length; index += 2) {
+                const key = children[index];
+                const item = children[index + 1];
+                if (key?.name !== "key" || !item)
+                    throw new Error("dict keys and values must alternate");
+                result[key.text] = value(item);
+            }
+            return result;
+        }
+        case "array":
+            return node.children.map(value);
+        case "string":
+            return node.text;
+        case "integer": {
+            const text = node.text.trim();
+            const parsed = /^[+-]?0x/i.test(text) ? Number.parseInt(text, 16) : Number(text);
+            if (!/^[+-]?(0x[0-9a-f]+|\d+)$/i.test(text) || !Number.isSafeInteger(parsed)) {
+                throw new Error(`invalid integer ${JSON.stringify(text)}`);
+            }
+            return parsed;
+        }
+        case "real": {
+            const parsed = Number(node.text.trim());
+            if (Number.isNaN(parsed) && !/nan/i.test(node.text)) {
+                throw new Error(`invalid real ${JSON.stringify(node.text)}`);
+            }
+            return new PlistReal(parsed);
+        }
+        case "true":
+            return true;
+        case "false":
+            return false;
+        case "date":
+            return new Date(node.text.trim());
+        case "data":
+            return Uint8Array.from(Buffer.from(node.text.replace(/\s+/g, ""), "base64"));
+        default:
+            throw new Error(`unknown element <${node.name}>`);
+    }
+}
+/** Parse an XML property list; throws an Error describing what is invalid. */
+export function parsePlist(text) {
+    const plist = tree(text).children.find((node) => node.name === "plist");
+    const [content, ...rest] = plist?.children ?? [];
+    if (!content || rest.length)
+        throw new Error("expected one value inside <plist>");
+    return value(content);
+}
+function escapeText(text) {
+    if (/[\0-\x08\x0b\x0c\x0e-\x1f]/.test(text)) {
+        throw new Error("strings can't contain control characters; use bytes instead");
+    }
+    return text
+        .replaceAll("\r\n", "\n")
+        .replaceAll("\r", "\n")
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+function realText(value) {
+    if (Number.isNaN(value))
+        return "nan";
+    if (!Number.isFinite(value))
+        return value > 0 ? "inf" : "-inf";
+    const text = String(value);
+    if (text.includes("e"))
+        return text.replace(/e([+-])(\d)$/, "e$10$2");
+    return Number.isInteger(value) ? `${text}.0` : text;
+}
+function lines(item, depth, out) {
+    const indent = "\t".repeat(depth);
+    if (typeof item === "string")
+        out.push(`${indent}<string>${escapeText(item)}</string>`);
+    else if (typeof item === "boolean")
+        out.push(`${indent}<${item}/>`);
+    else if (typeof item === "number") {
+        if (!Number.isInteger(item))
+            throw new Error("integers must be whole numbers");
+        out.push(`${indent}<integer>${item}</integer>`);
+    }
+    else if (item instanceof PlistReal)
+        out.push(`${indent}<real>${realText(item.value)}</real>`);
+    else if (item instanceof Date) {
+        out.push(`${indent}<date>${item.toISOString().replace(/\.\d{3}Z$/, "Z")}</date>`);
+    }
+    else if (item instanceof Uint8Array) {
+        const encoded = Buffer.from(item).toString("base64");
+        const width = Math.max(16, 76 - indent.replaceAll("\t", " ".repeat(8)).length);
+        const wrapped = encoded.match(new RegExp(`.{1,${(Math.floor(width / 4) * 3 * 4) / 3}}`, "g"));
+        out.push(`${indent}<data>`);
+        for (const line of wrapped ?? [])
+            out.push(`${indent}${line}`);
+        out.push(`${indent}</data>`);
+    }
+    else if (Array.isArray(item)) {
+        if (!item.length)
+            out.push(`${indent}<array/>`);
+        else {
+            out.push(`${indent}<array>`);
+            for (const child of item)
+                lines(child, depth + 1, out);
+            out.push(`${indent}</array>`);
+        }
+    }
+    else {
+        const entries = Object.entries(item);
+        if (!entries.length)
+            out.push(`${indent}<dict/>`);
+        else {
+            out.push(`${indent}<dict>`);
+            for (const [key, child] of entries) {
+                out.push(`${indent}\t<key>${escapeText(key)}</key>`);
+                lines(child, depth + 1, out);
+            }
+            out.push(`${indent}</dict>`);
+        }
+    }
+}
+/** plistlib.dumps(value, fmt=FMT_XML, sort_keys=False). */
+export function buildPlist(item) {
+    const out = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+    ];
+    lines(item, 0, out);
+    out.push("</plist>", "");
+    return out.join("\n");
+}

package/dist/project.js

@@ -0,0 +1,195 @@
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseToml } from "smol-toml";
+import { BUILT_IN_FIXTURE_NAMES } from "./commands.js";
+import { buildPlist, parsePlist } from "./plist.js";
+export const REQUIRED_THEME_FILES = ["Info.plist", "template.html", "stylesheet.css"];
+export const PLACEHOLDER_MARKER = ".nnw-theme-uninitialized";
+export const IDENTITY_START = "<!-- nnw-theme-identity:start -->";
+export const IDENTITY_END = "<!-- nnw-theme-identity:end -->";
+/** The fixtures that ship in the package; a repository's own copy of one wins. */
+export const BUILT_IN_FIXTURES = BUILT_IN_FIXTURE_NAMES;
+/** A user-actionable theme project error. */
+export class ThemeError extends Error {
+    name = "ThemeError";
+}
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+/** A path inside the installed package (src/ in a checkout, dist/ when published). */
+export function packagePath(...parts) {
+    return join(PACKAGE_ROOT, ...parts);
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function themeDirectories(root) {
+    let names;
+    try {
+        names = readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((name) => name.endsWith(".nnwtheme") && isDirectory(join(root, name)))
+        .sort()
+        .map((name) => join(root, name));
+}
+/** The nearest directory, from start upward, that holds a root *.nnwtheme bundle. */
+export function findRoot(start = process.cwd()) {
+    let current = resolve(start);
+    if (isFile(current))
+        current = dirname(current);
+    for (;;) {
+        if (themeDirectories(current).length)
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    throw new ThemeError("run this command inside the theme repository");
+}
+export function findTheme(root) {
+    const themes = themeDirectories(root);
+    const [theme] = themes;
+    if (themes.length !== 1 || !theme) {
+        const names = themes.map((path) => path.slice(root.length + 1)).join(", ") || "none";
+        throw new ThemeError(`expected one .nnwtheme directory at the repository root; found ${names}`);
+    }
+    return theme;
+}
+/** A bundle's name without .nnwtheme, as Python's Path.stem gives it. */
+export function themeStem(theme) {
+    const name = theme.split("/").at(-1) ?? "";
+    return name.slice(0, -".nnwtheme".length);
+}
+export function readPlistFile(path) {
+    let value;
+    try {
+        value = parsePlist(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new ThemeError(`${path}: invalid property list: ${error.message}`);
+    }
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        value.constructor !== Object) {
+        throw new ThemeError(`${path}: the top-level value must be a dictionary`);
+    }
+    return value;
+}
+export function readPlist(theme) {
+    return readPlistFile(join(theme, "Info.plist"));
+}
+export function writePlist(path, metadata) {
+    writeFileSync(path, buildPlist(metadata), "utf8");
+}
+export function parseFixture(text, name) {
+    let value;
+    try {
+        value = parseToml(text);
+    }
+    catch (error) {
+        throw new ThemeError(`${name}: invalid fixture: ${error.message}`);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ThemeError(`${name}: fixture must be a table`);
+    }
+    return value;
+}
+export function readFixture(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        throw new ThemeError(`${path}: invalid fixture: ${error.message}`);
+    }
+    return parseFixture(text, path);
+}
+/** The repository's fixture names (fixtures/*.toml), sorted. */
+export function repositoryFixtures(root) {
+    let names;
+    try {
+        names = readdirSync(join(root, "fixtures"));
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((name) => name.endsWith(".toml") && isFile(join(root, "fixtures", name)))
+        .map((name) => name.slice(0, -".toml".length))
+        .sort();
+}
+/** Where a fixture lives: the repository's copy, else the package's built-in one. */
+export function fixturePath(root, name) {
+    const own = join(root, "fixtures", `${name}.toml`);
+    if (existsSync(own))
+        return own;
+    if (BUILT_IN_FIXTURES.includes(name)) {
+        return packagePath("assets", "fixtures", `${name}.toml`);
+    }
+    throw new ThemeError(`fixture not found: ${own}`);
+}
+function isTable(value) {
+    return (!!value && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date));
+}
+/**
+ * A fixture's optional [expect.footnotes] table, validated for the browser check.
+ *
+ * notes maps each footnote marker's rendered text to the note text its popover must
+ * show; plain_links lists CSS selectors for links that must not become footnotes;
+ * keep_with_word requires markers written against a word to stay on its line.
+ */
+export function footnoteExpectations(fixture, name) {
+    const expect = fixture.expect ?? {};
+    const footnotes = isTable(expect) ? (expect.footnotes ?? {}) : undefined;
+    if (!isTable(expect) ||
+        !isTable(footnotes) ||
+        Object.keys(expect).some((key) => key !== "footnotes")) {
+        throw new ThemeError(`${name}: [expect] may contain only a [expect.footnotes] table`);
+    }
+    const unknown = Object.keys(footnotes)
+        .filter((key) => !["notes", "plain_links", "keep_with_word"].includes(key))
+        .sort();
+    if (unknown.length) {
+        throw new ThemeError(`${name}: unknown [expect.footnotes] key(s): ${unknown.join(", ")}`);
+    }
+    const result = {};
+    if ("notes" in footnotes) {
+        const notes = footnotes.notes;
+        if (!isTable(notes) || !Object.values(notes).every((value) => typeof value === "string")) {
+            throw new ThemeError(`${name}: [expect.footnotes.notes] must map markers to text`);
+        }
+        result.notes = notes;
+    }
+    if ("plain_links" in footnotes) {
+        const links = footnotes.plain_links;
+        if (!Array.isArray(links) || !links.every((link) => typeof link === "string")) {
+            throw new ThemeError(`${name}: expect.footnotes.plain_links must be CSS selectors`);
+        }
+        result.plain_links = links;
+    }
+    if ("keep_with_word" in footnotes) {
+        if (typeof footnotes.keep_with_word !== "boolean") {
+            throw new ThemeError(`${name}: expect.footnotes.keep_with_word must be true or false`);
+        }
+        result.keep_with_word = footnotes.keep_with_word;
+    }
+    return result;
+}

package/dist/pyformat.js

@@ -0,0 +1,82 @@
+// Python's formatting of values that appear in messages and pages, so the port's
+// output matches the Python tool's text exactly.
+const NON_PRINTABLE = /[\p{C}\p{Zl}\p{Zp}]|(?! )\p{Zs}/u;
+/** repr() of a str. */
+export function pyRepr(value) {
+    const quote = value.includes("'") && !value.includes('"') ? '"' : "'";
+    let result = quote;
+    for (const character of value) {
+        const code = character.codePointAt(0) ?? 0;
+        if (character === "\\")
+            result += "\\\\";
+        else if (character === quote)
+            result += `\\${quote}`;
+        else if (character === "\n")
+            result += "\\n";
+        else if (character === "\r")
+            result += "\\r";
+        else if (character === "\t")
+            result += "\\t";
+        else if (NON_PRINTABLE.test(character)) {
+            if (code < 0x100)
+                result += `\\x${code.toString(16).padStart(2, "0")}`;
+            else if (code < 0x10000)
+                result += `\\u${code.toString(16).padStart(4, "0")}`;
+            else
+                result += `\\U${code.toString(16).padStart(8, "0")}`;
+        }
+        else
+            result += character;
+    }
+    return result + quote;
+}
+/** repr() of a list of str. */
+export function pyReprList(values) {
+    return `[${values.map(pyRepr).join(", ")}]`;
+}
+/** Python's shortest round-tripping float text: 17.0 -> "17.0", 1e16 -> "1e+16". */
+function floatRepr(value) {
+    if (Number.isNaN(value))
+        return "nan";
+    if (!Number.isFinite(value))
+        return value > 0 ? "inf" : "-inf";
+    const text = String(value);
+    if (/e/.test(text))
+        return text.replace(/e([+-])(\d)$/, "e$10$2");
+    if (Math.abs(value) >= 1e16)
+        return value.toExponential().replace(/e([+-])(\d)$/, "e$10$2");
+    return Number.isInteger(value) ? `${text}.0` : text;
+}
+/**
+ * str() of a TOML value. Integers and floats are indistinguishable once parsed, so
+ * callers that need Python's float text use formatG instead.
+ */
+export function pyStr(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "boolean")
+        return value ? "True" : "False";
+    if (typeof value === "number" || typeof value === "bigint")
+        return String(value);
+    if (value === null || value === undefined)
+        return "None";
+    if (value instanceof Date)
+        return value.toISOString();
+    return String(value);
+}
+/** format(value, "g"): six significant digits, trailing zeros dropped. */
+export function formatG(value) {
+    if (!Number.isFinite(value))
+        return floatRepr(value);
+    if (value === 0)
+        return Object.is(value, -0) ? "-0" : "0";
+    const exponent = Math.floor(Math.log10(Math.abs(Number(value.toPrecision(6)))));
+    if (exponent < -4 || exponent >= 6) {
+        const [mantissa = "", power = "0"] = value.toExponential(5).split("e");
+        const trimmed = mantissa.includes(".") ? mantissa.replace(/\.?0+$/, "") : mantissa;
+        const sign = power.startsWith("-") ? "-" : "+";
+        return `${trimmed}e${sign}${power.replace(/^[+-]/, "").padStart(2, "0")}`;
+    }
+    const fixed = value.toFixed(Math.max(0, 5 - exponent));
+    return fixed.includes(".") ? fixed.replace(/\.?0+$/, "") : fixed;
+}