seendiff 0.0.2

package/src/walkthrough.js

@@ -0,0 +1,338 @@
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+
+export const MAX_STEPS = 40;
+export const MAX_ALSO = 3;
+export const MAX_DEPTH = 1;
+
+export class WalkthroughError extends Error {
+    constructor(problems) {
+        super(problems.join("; "));
+        this.problems = problems;
+    }
+}
+
+function refToJson(ref) {
+    const d = { path: ref.path, lines: [ref.lines[0], ref.lines[1]] };
+    if (ref.hunkId) d.hunk_id = ref.hunkId;
+    if (ref.note) d.note = ref.note;
+    return d;
+}
+
+function stepToJson(s) {
+    return {
+        id: s.id,
+        act: s.act,
+        depth: s.depth,
+        title: s.title,
+        text: s.text,
+        ref: refToJson(s.ref),
+        also: s.also.map(refToJson),
+        forward: s.forward,
+    };
+}
+
+export function walkthroughPaths(wt) {
+    const out = new Set();
+    for (const s of wt.steps) {
+        out.add(s.ref.path);
+        for (const r of s.also) out.add(r.path);
+    }
+    return out;
+}
+
+export function walkthroughToJson(wt) {
+    return {
+        title: wt.title,
+        intro: wt.intro,
+        acts: wt.acts.map((a) => ({ id: a.id, title: a.title })),
+        steps: wt.steps.map(stepToJson),
+        digest: wt.digest,
+        mtime: wt.mtime,
+    };
+}
+
+export function fileLineCount(repo, filePath) {
+    let raw;
+    try {
+        raw = readFileSync(path.join(repo, filePath));
+    } catch {
+        return null;
+    }
+    if (raw.subarray(0, 8192).includes(0)) return null;
+    const lines = raw.toString("utf8").split("\n");
+    if (lines.length && lines[lines.length - 1] === "") lines.pop();
+    return lines.length;
+}
+
+function checkRef(ref, repo, where, hunkIds) {
+    const probs = [];
+    const p = ref.path;
+    if (typeof p !== "string" || !p) {
+        return [null, [`${where}: ref needs a string 'path'`]];
+    }
+    const root = path.resolve(repo);
+    const resolved = path.resolve(root, p);
+    const rel = path.relative(root, resolved);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        return [null, [`${where}: ${p} resolves outside the repository`]];
+    }
+    let st;
+    try {
+        st = statSync(resolved);
+    } catch {
+        return [null, [`${where}: ${p} does not exist`]];
+    }
+    if (!st.isFile()) {
+        return [null, [`${where}: ${p} does not exist`]];
+    }
+
+    const lines = ref.lines;
+    const validLines =
+        Array.isArray(lines) &&
+        lines.length === 2 &&
+        lines.every((n) => Number.isInteger(n));
+    if (!validLines) {
+        return [null, [`${where}: 'lines' must be [start, end] integers`]];
+    }
+    const [a, b] = lines;
+    const n = fileLineCount(repo, p);
+    if (n === null) {
+        probs.push(`${where}: ${p} is binary or unreadable`);
+    } else if (!(1 <= a && a <= b && b <= n)) {
+        probs.push(
+            a <= b
+                ? `${where}: ${p}:${a}-${b} out of range (file has ${n} lines)`
+                : `${where}: ${p}:${a}-${b} is inverted`
+        );
+    }
+
+    const hunkId = ref.hunk_id;
+    let outHunkId = null;
+    if (hunkId !== undefined && hunkId !== null) {
+        if (typeof hunkId !== "string") {
+            probs.push(`${where}: 'hunk_id' must be a string`);
+        } else {
+            outHunkId = hunkId;
+            if (hunkIds != null) {
+                const set = hunkIds[p];
+                if (!set || !set.has(hunkId)) {
+                    probs.push(`${where}: hunk_id '${hunkId}' not in the diff of ${p}`);
+                }
+            }
+        }
+    }
+
+    let note = ref.note;
+    if (note !== undefined && note !== null && typeof note !== "string") {
+        probs.push(`${where}: 'note' must be a string`);
+        note = null;
+    }
+    if (probs.length) return [null, probs];
+    return [{ path: p, lines: [a, b], hunkId: outHunkId, note: note ?? null }, []];
+}
+
+function parseWalkthrough(data, repo, hunkIds) {
+    const probs = [];
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        return [null, ["top level must be a JSON object"]];
+    }
+    if (data.version !== 1) {
+        probs.push(`version must be 1 (got ${JSON.stringify(data.version)})`);
+    }
+    let title = data.title;
+    if (typeof title !== "string" || !title) {
+        probs.push("'title' is required");
+        title = "";
+    }
+    const intro = data.intro || "";
+
+    const acts = [];
+    const actIds = new Map();
+    let rawActs = data.acts;
+    if (!Array.isArray(rawActs) || !rawActs.length) {
+        probs.push("'acts' must be a non-empty list");
+        rawActs = [];
+    }
+    rawActs.forEach((a, i) => {
+        if (typeof a !== "object" || a === null || typeof a.id !== "string" || typeof a.title !== "string") {
+            probs.push(`acts[${i}]: needs string 'id' and 'title'`);
+            return;
+        }
+        if (actIds.has(a.id)) {
+            probs.push(`acts[${i}]: duplicate act id '${a.id}'`);
+            return;
+        }
+        actIds.set(a.id, acts.length);
+        acts.push({ id: a.id, title: a.title });
+    });
+
+    let rawSteps = data.steps;
+    if (!Array.isArray(rawSteps) || !rawSteps.length) {
+        probs.push("'steps' must be a non-empty list");
+        rawSteps = [];
+    }
+    if (rawSteps.length > MAX_STEPS) {
+        probs.push(`${rawSteps.length} steps — cap is ${MAX_STEPS}; the scope was too big`);
+    }
+
+    const steps = [];
+    const stepIndex = new Map();
+    let lastAct = -1;
+    rawSteps.forEach((s, i) => {
+        const w = `steps[${i}]`;
+        if (typeof s !== "object" || s === null || Array.isArray(s)) {
+            probs.push(`${w}: must be an object`);
+            return;
+        }
+        let sid = s.id;
+        if (typeof sid !== "string" || !sid) {
+            probs.push(`${w}: needs a string 'id'`);
+            sid = `#${i}`;
+        } else if (stepIndex.has(sid)) {
+            probs.push(`${w}: duplicate step id '${sid}'`);
+        }
+        const act = s.act;
+        if (!actIds.has(act)) {
+            probs.push(`${w}: unknown act ${JSON.stringify(act)}`);
+        } else {
+            const ai = actIds.get(act);
+            if (ai < lastAct) {
+                probs.push(`${w}: act '${act}' interleaved — steps must be grouped in act order`);
+            }
+            lastAct = Math.max(lastAct, ai);
+        }
+        let depth = s.depth ?? 0;
+        if (!Number.isInteger(depth) || !(depth >= 0 && depth <= MAX_DEPTH)) {
+            probs.push(`${w}: depth must be 0 or 1 (got ${JSON.stringify(depth)}); three levels of nesting needs its own act`);
+            depth = 0;
+        }
+        let stTitle = s.title;
+        if (typeof stTitle !== "string" || !stTitle) {
+            probs.push(`${w}: needs a string 'title'`);
+            stTitle = "";
+        }
+        let text = s.text;
+        if (typeof text !== "string" || !text) {
+            probs.push(`${w}: needs a string 'text'`);
+            text = "";
+        }
+        if (typeof s.ref !== "object" || s.ref === null || Array.isArray(s.ref)) {
+            probs.push(`${w}: needs a 'ref' object`);
+            return;
+        }
+        const [ref, rp] = checkRef(s.ref, repo, `${w}.ref`, hunkIds);
+        probs.push(...rp);
+        const also = [];
+        let rawAlso = s.also || [];
+        if (!Array.isArray(rawAlso)) {
+            probs.push(`${w}: 'also' must be a list`);
+            rawAlso = [];
+        }
+        if (rawAlso.length > MAX_ALSO) {
+            probs.push(`${w}: ${rawAlso.length} also-refs — cap is ${MAX_ALSO}`);
+        }
+        rawAlso.forEach((ar, j) => {
+            const [aref, ap] = checkRef(
+                typeof ar === "object" && ar !== null ? ar : {},
+                repo,
+                `${w}.also[${j}]`,
+                hunkIds
+            );
+            probs.push(...ap);
+            if (aref) also.push(aref);
+        });
+        let forward = s.forward;
+        if (forward !== undefined && forward !== null && typeof forward !== "string") {
+            probs.push(`${w}: 'forward' must be a step id`);
+            forward = null;
+        }
+        if (!ref) return;
+        if (!stepIndex.has(sid)) stepIndex.set(sid, steps.length);
+        steps.push({
+            id: sid,
+            act: actIds.has(act) ? act : "",
+            depth,
+            title: stTitle,
+            text,
+            ref,
+            also,
+            forward: forward ?? null,
+        });
+    });
+
+    steps.forEach((st, i) => {
+        if (st.forward == null) return;
+        const j = stepIndex.get(st.forward);
+        if (j === undefined) {
+            probs.push(`steps[${i}]: forward '${st.forward}' names no step`);
+        } else if (j <= i) {
+            probs.push(`steps[${i}]: forward '${st.forward}' must point to a later step`);
+        }
+    });
+
+    if (probs.length) return [null, probs];
+    return [
+        { title, intro, acts, steps, path: "", mtime: 0.0, digest: "" },
+        [],
+    ];
+}
+
+export function isEmpty(raw) {
+    if (raw === null || !raw.toString("utf8").trim()) return true;
+    let data;
+    try {
+        data = JSON.parse(raw.toString("utf8"));
+    } catch {
+        return false;
+    }
+    if (data === null) return true;
+    if (typeof data === "object" && !Array.isArray(data) && Object.keys(data).length === 0) return true;
+    return typeof data === "object" && data !== null && !Array.isArray(data) && !data.steps;
+}
+
+export function check(filePath, repo, hunkIds = null) {
+    const name = path.basename(filePath);
+    let raw;
+    try {
+        raw = readFileSync(filePath);
+    } catch (e) {
+        if (e.code === "ENOENT") return [];
+        return [`${name}: cannot read: ${e.message}`];
+    }
+    if (isEmpty(raw)) return [];
+    let data;
+    try {
+        data = JSON.parse(raw.toString("utf8"));
+    } catch (e) {
+        return [`${name}: invalid JSON: ${e.message}`];
+    }
+    const [, probs] = parseWalkthrough(data, repo, hunkIds);
+    return probs.map((p) => `${name}: ${p}`);
+}
+
+export function load(filePath, repo, hunkIds = null) {
+    let raw;
+    let mtime;
+    try {
+        raw = readFileSync(filePath);
+        mtime = statSync(filePath).mtimeMs / 1000;
+    } catch (e) {
+        if (e.code === "ENOENT") return null;
+        throw new WalkthroughError([`cannot read ${filePath}: ${e.message}`]);
+    }
+    if (isEmpty(raw)) return null;
+    let data;
+    try {
+        data = JSON.parse(raw.toString("utf8"));
+    } catch (e) {
+        throw new WalkthroughError([`invalid JSON: ${e.message}`]);
+    }
+    const [wt, probs] = parseWalkthrough(data, repo, hunkIds);
+    if (!wt) throw new WalkthroughError(probs);
+    wt.path = filePath;
+    wt.mtime = mtime;
+    wt.digest = createHash("sha256").update(raw).digest("hex").slice(0, 16);
+    return wt;
+}

package/static/fonts/LICENCE-UbuntuSansMono.txt

@@ -0,0 +1,96 @@
+-------------------------------
+UBUNTU FONT LICENCE Version 1.0
+-------------------------------
+
+PREAMBLE
+This licence allows the licensed fonts to be used, studied, modified and
+redistributed freely. The fonts, including any derivative works, can be
+bundled, embedded, and redistributed provided the terms of this licence
+are met. The fonts and derivatives, however, cannot be released under
+any other licence. The requirement for fonts to remain under this
+licence does not require any document created using the fonts or their
+derivatives to be published under this licence, as long as the primary
+purpose of the document is not to be a vehicle for the distribution of
+the fonts.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this licence and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Original Version" refers to the collection of Font Software components
+as received under this licence.
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to
+a new environment.
+
+"Copyright Holder(s)" refers to all individuals and companies who have a
+copyright ownership of the Font Software.
+
+"Substantially Changed" refers to Modified Versions which can be easily
+identified as dissimilar to the Font Software by users of the Font
+Software comparing the Original Version with the Modified Version.
+
+To "Propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy. Propagation includes copying,
+distribution (with or without modification and with or without charging
+a redistribution fee), making available to the public, and in some
+countries other activities as well.
+
+PERMISSION & CONDITIONS
+This licence does not grant any rights under trademark law and all such
+rights are reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of the Font Software, to propagate the Font Software, subject to
+the below conditions:
+
+1) Each copy of the Font Software must contain the above copyright
+notice and this licence. These can be included either as stand-alone
+text files, human-readable headers or in the appropriate machine-
+readable metadata fields within text or binary files as long as those
+fields can be easily viewed by the user.
+
+2) The font name complies with the following:
+(a) The Original Version must retain its name, unmodified.
+(b) Modified Versions which are Substantially Changed must be renamed to
+avoid use of the name of the Original Version or similar names entirely.
+(c) Modified Versions which are not Substantially Changed must be
+renamed to both (i) retain the name of the Original Version and (ii) add
+additional naming elements to distinguish the Modified Version from the
+Original Version. The name of such Modified Versions must be the name of
+the Original Version, with "derivative X" where X represents the name of
+the new work, appended to that name.
+
+3) The name(s) of the Copyright Holder(s) and any contributor to the
+Font Software shall not be used to promote, endorse or advertise any
+Modified Version, except (i) as required by this licence, (ii) to
+acknowledge the contribution(s) of the Copyright Holder(s) or (iii) with
+their explicit written permission.
+
+4) The Font Software, modified or unmodified, in part or in whole, must
+be distributed entirely under this licence, and must not be distributed
+under any other licence. The requirement for fonts to remain under this
+licence does not affect any document created using the Font Software,
+except any version of the Font Software extracted from a document
+created using the Font Software may only be distributed under this
+licence.
+
+TERMINATION
+This licence becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
+COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER
+DEALINGS IN THE FONT SOFTWARE.

package/static/fonts/LICENSE-JetBrainsMono.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/static/fonts/README.md

@@ -0,0 +1,29 @@
+# Bundled fonts
+
+seendiff ships two monospace webfonts so the UI renders identically without a
+network fetch. Both are subsetted and converted to woff2; neither is the
+upstream file byte-for-byte.
+
+| File | Font | Version | Licence |
+|---|---|---|---|
+| `JetBrainsMono.woff2` | JetBrains Mono Regular | 2.211 | SIL Open Font License 1.1 — [`LICENSE-JetBrainsMono.txt`](LICENSE-JetBrainsMono.txt) |
+| `UbuntuSansMono.woff2` | Ubuntu Sans Mono Regular | 1.006 | Ubuntu Font Licence 1.0 — [`LICENCE-UbuntuSansMono.txt`](LICENCE-UbuntuSansMono.txt) |
+
+Upstream sources:
+
+- JetBrains Mono — <https://github.com/JetBrains/JetBrainsMono>
+- Ubuntu Sans Mono — <https://github.com/canonical/Ubuntu-Sans-fonts>
+
+## Modifications
+
+Both files were reduced to the glyphs seendiff actually renders and converted
+to woff2 (394 glyphs / 229 codepoints for JetBrains Mono, 259 / 227 for Ubuntu
+Sans Mono). No outlines, metrics, or hinting were altered.
+
+The JetBrains Mono copyright declares no Reserved Font Name, so the subset is
+redistributable under the OFL as-is, provided this licence text travels with
+it.
+
+The Ubuntu Font Licence treats a format conversion as a Modified Version
+(clause 2), which carries a naming requirement — see the licence text for the
+exact terms.