hdoc-tools 0.57.2 → 0.57.3

package/hdoc-spell.js

@@ -0,0 +1,61 @@
+// Dialect spell-check: flags British spellings and suggests the US form, using
+// the same `american-british-english-translator` the build uses (hdoc-validate),
+// so the editor and `hdoc validate` agree. Returns character-offset findings
+// suitable for editor underlines.
+
+let translator = null;
+
+function line_starts(text) {
+	const starts = [0];
+	for (let i = 0; i < text.length; i++) {
+		if (text[i] === "\n") starts.push(i + 1);
+	}
+	return starts;
+}
+
+function escape_regex(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// Returns [{ from, to, word, suggestion, type: 'dialect' }] for British spellings,
+// skipping any word in `ignore` (case-insensitive).
+function dialect_findings(text, ignore = []) {
+	if (!translator) translator = require("american-british-english-translator");
+	const out = translator.translate(text, { british: true, spelling: true });
+	const ignore_set = new Set(ignore.map((w) => String(w).toLowerCase()));
+	const starts = line_starts(text);
+	const findings = [];
+
+	for (const line_key of Object.keys(out)) {
+		const line_no = Number.parseInt(line_key, 10);
+		if (!line_no) continue;
+		const line_start = starts[line_no - 1];
+		if (line_start === undefined) continue;
+		const line_end = line_no < starts.length ? starts[line_no] : text.length;
+		const line_text = text.slice(line_start, line_end);
+
+		for (const entry of out[line_key]) {
+			for (const word of Object.keys(entry)) {
+				if (ignore_set.has(word.toLowerCase())) continue;
+				const suggestion = entry[word]?.details;
+				if (!suggestion) continue;
+				const re = new RegExp(`\\b${escape_regex(word)}\\b`, "gi");
+				let m;
+				// eslint-disable-next-line no-cond-assign
+				while ((m = re.exec(line_text)) !== null) {
+					const from = line_start + m.index;
+					findings.push({
+						from,
+						to: from + m[0].length,
+						word: m[0],
+						suggestion,
+						type: "dialect",
+					});
+				}
+			}
+		}
+	}
+	return findings;
+}
+
+exports.dialect_findings = dialect_findings;

package/hdoc-toc.js

@@ -0,0 +1,442 @@
+// In-memory TOC working model for `hdoc edit`.
+//
+// Owns the book's navigation tree (hdocbook.json -> navigation.items) and the
+// node-identity scheme. Each node gets a permanent, opaque, per-book-unique id
+// (see README of the editor effort): identity is separated from location
+// (link/slug) and from order (1.2.3 numbering is derived at render time only).
+//
+// Identity strategy (Phase 1): on load we assign an id to every node that lacks
+// one, in memory. The model is the single source of truth for the editing
+// session, so ids stay stable across /api/toc reads. The first structural save
+// persists these ids back into hdocbook.json (lazy one-time migration).
+//
+// hdocbook.json is read with fs.readFileSync + JSON.parse (never require) because
+// the editor mutates it and require() would cache a stale copy.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+// Lowercase, URL-safe, no look-alike characters (drops 0/o/1/l/i). 30 symbols.
+const ID_ALPHABET = "23456789abcdefghjkmnpqrstvwxyz";
+const ID_LENGTH = 8;
+// Largest multiple of the alphabet size that fits in a byte, for unbiased
+// rejection sampling (256 -> 240 = 8 * 30).
+const ID_REJECT_THRESHOLD =
+	Math.floor(256 / ID_ALPHABET.length) * ID_ALPHABET.length;
+
+// Recognised image/asset extensions (for the Files browser + uploads).
+const IMAGE_EXTS = [
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".svg",
+	".webp",
+	".bmp",
+	".ico",
+	".avif",
+];
+
+// Classify a file by name for the Files tree: page (.md), image, or other.
+function kind_of(name) {
+	const lower = name.toLowerCase();
+	if (lower.endsWith(".md")) return "page";
+	if (IMAGE_EXTS.some((e) => lower.endsWith(e))) return "image";
+	return "other";
+}
+
+function random_id_char() {
+	// Rejection-sample a byte to avoid modulo bias across the 30-symbol alphabet.
+	for (;;) {
+		const b = crypto.randomBytes(1)[0];
+		if (b < ID_REJECT_THRESHOLD) return ID_ALPHABET[b % ID_ALPHABET.length];
+	}
+}
+
+// Generate an opaque id not present in `used` (a Set), and reserve it.
+function generate_id(used) {
+	for (let attempt = 0; attempt < 10000; attempt++) {
+		let id = "";
+		for (let i = 0; i < ID_LENGTH; i++) id += random_id_char();
+		if (!used.has(id)) {
+			used.add(id);
+			return id;
+		}
+	}
+	throw new Error("Unable to generate a unique node id");
+}
+
+class TocModel {
+	constructor(source_path, docId) {
+		this.source_path = source_path;
+		this.docId = docId;
+		this.hdocbook_path = path.join(source_path, docId, "hdocbook.json");
+		// True when we assigned ids that are not yet written to disk. The first
+		// save will persist them (handled by a future write endpoint).
+		this.ids_pending_persist = false;
+		// Optional hook: called as (absPath, content) after we write hdocbook.json,
+		// so a file watcher can suppress our own writes.
+		this.on_persist = null;
+		this.load();
+	}
+
+	// Re-read hdocbook.json from disk (e.g. after an external edit), keeping any
+	// existing ids and assigning ids to new nodes.
+	reload() {
+		this.load();
+	}
+
+	load() {
+		const raw = JSON.parse(fs.readFileSync(this.hdocbook_path, "utf8"));
+		this.raw = raw;
+		const nav =
+			raw.navigation && Array.isArray(raw.navigation.items)
+				? raw.navigation.items
+				: [];
+		this.items = nav;
+
+		// Pass 1: collect ids already present so generated ones never collide.
+		this.used_ids = new Set();
+		this._walk(nav, (n) => {
+			if (typeof n.id === "string" && n.id) this.used_ids.add(n.id);
+		});
+		// Pass 2: assign opaque ids to any node that lacks one.
+		this._walk(nav, (n) => {
+			if (!(typeof n.id === "string" && n.id)) {
+				n.id = generate_id(this.used_ids);
+				this.ids_pending_persist = true;
+			}
+		});
+	}
+
+	_walk(nodes, fn) {
+		for (const n of nodes) {
+			fn(n);
+			if (Array.isArray(n.items)) this._walk(n.items, fn);
+		}
+	}
+
+	// Resolve a leaf link (path without extension) to a source-relative file.
+	_resolve_file(link) {
+		const rel = `${link}.md`;
+		if (fs.existsSync(path.join(this.source_path, rel))) {
+			return { file: rel, fileExists: true };
+		}
+		const rel_index = path.join(link, "index.md");
+		if (fs.existsSync(path.join(this.source_path, rel_index))) {
+			return { file: rel_index, fileExists: true };
+		}
+		// Report the expected path even when missing, so the UI can flag it.
+		return { file: rel, fileExists: false };
+	}
+
+	// Find a node anywhere in the tree by its opaque id (or null).
+	find_node(id) {
+		let found = null;
+		this._walk(this.items, (n) => {
+			if (n.id === id) found = n;
+		});
+		return found;
+	}
+
+	// Resolve a node id to its source file. Returns null if the id is unknown.
+	// For a branch (or a leaf with no link) abs/file are null and exists is false.
+	resolve_file(id) {
+		const node = this.find_node(id);
+		if (!node) return null;
+		const link = typeof node.link === "string" ? node.link : null;
+		if (!link) {
+			return { node, link: null, file: null, abs: null, exists: false };
+		}
+		const r = this._resolve_file(link);
+		return {
+			node,
+			link,
+			file: r.file,
+			abs: path.join(this.source_path, r.file),
+			exists: r.fileExists,
+		};
+	}
+
+	// --- structural mutations (Phase 1b: nav-only — links/files never move) ---
+
+	// Locate a node by id: returns { node, parent (array), index } or null.
+	_locate(id) {
+		const search = (arr) => {
+			for (let i = 0; i < arr.length; i++) {
+				if (arr[i].id === id) return { node: arr[i], parent: arr, index: i };
+				if (Array.isArray(arr[i].items)) {
+					const found = search(arr[i].items);
+					if (found) return found;
+				}
+			}
+			return null;
+		};
+		return search(this.items);
+	}
+
+	// Is targetId the node itself or one of its descendants?
+	_contains(node, targetId) {
+		if (node.id === targetId) return true;
+		if (Array.isArray(node.items)) {
+			return node.items.some((c) => this._contains(c, targetId));
+		}
+		return false;
+	}
+
+	// Reorder/reparent a node. parentId null => top level. index is the insertion
+	// position in the destination AFTER the node has been removed from its old
+	// spot. Only navigation order/nesting changes; link/items/draft are preserved.
+	move(id, parentId, index) {
+		const loc = this._locate(id);
+		if (!loc) throw new Error(`Unknown node id: ${id}`);
+
+		let dest;
+		if (parentId === null || parentId === undefined) {
+			dest = this.items;
+		} else {
+			const parent = this.find_node(parentId);
+			if (!parent) throw new Error(`Unknown parent id: ${parentId}`);
+			if (!Array.isArray(parent.items)) {
+				throw new Error("Target node is a leaf and cannot contain children");
+			}
+			if (this._contains(loc.node, parentId)) {
+				throw new Error("Cannot move a node into its own subtree");
+			}
+			dest = parent.items;
+		}
+
+		loc.parent.splice(loc.index, 1);
+		let idx = typeof index === "number" ? index : dest.length;
+		idx = Math.max(0, Math.min(idx, dest.length));
+		dest.splice(idx, 0, loc.node);
+		this.persist();
+	}
+
+	// Rename a node's display label (text). No effect on link/slug or file.
+	rename(id, text) {
+		const node = this.find_node(id);
+		if (!node) throw new Error(`Unknown node id: ${id}`);
+		node.text = text;
+		this.persist();
+	}
+
+	// Set a node's draft flag.
+	set_draft(id, draft) {
+		const node = this.find_node(id);
+		if (!node) throw new Error(`Unknown node id: ${id}`);
+		node.draft = !!draft;
+		this.persist();
+	}
+
+	// Write the working model back to hdocbook.json in its native format
+	// (2-space indent, LF, no trailing newline). This is also where in-memory
+	// opaque ids first land on disk (the lazy one-time migration).
+	persist() {
+		if (!this.raw.navigation) this.raw.navigation = {};
+		this.raw.navigation.items = this.items;
+		const json = JSON.stringify(this.raw, null, 2);
+		fs.writeFileSync(this.hdocbook_path, json, "utf8");
+		this.ids_pending_persist = false;
+		if (this.on_persist) this.on_persist(this.hdocbook_path, json);
+	}
+
+	// --- pages on disk (decoupled from nav) ---
+
+	// Validate a source-relative path: it must live inside the book's docId
+	// folder, not traverse upward, and not touch special "_" folders/files.
+	// `exts` limits the allowed file extension (default .md for pages; pass null
+	// to allow any, or a list for assets). Returns { rel (normalised), abs }.
+	_safe_rel(rel, { dir = false, exts = [".md"] } = {}) {
+		if (typeof rel !== "string" || !rel.trim()) throw new Error("Missing path");
+		const norm = rel.split("\\").join("/").replace(/^\/+/, "");
+		const segs = norm.split("/").filter((s) => s.length > 0);
+		if (segs[0] !== this.docId) {
+			throw new Error(`Path must be inside the book folder: ${this.docId}`);
+		}
+		if (segs.includes("..") || segs.includes(".")) {
+			throw new Error("Invalid path");
+		}
+		if (segs.some((s) => s.startsWith("_"))) {
+			throw new Error("Cannot operate inside special (_) folders");
+		}
+		if (!dir && exts) {
+			const lower = norm.toLowerCase();
+			if (!exts.some((e) => lower.endsWith(e))) {
+				throw new Error(`File type not allowed (expected: ${exts.join(", ")})`);
+			}
+		}
+		const root = path.join(this.source_path, this.docId);
+		const abs = path.join(this.source_path, norm);
+		const within = path.relative(root, abs);
+		if (within.startsWith("..") || path.isAbsolute(within)) {
+			throw new Error("Path escapes the book");
+		}
+		return { rel: norm, abs };
+	}
+
+	// Source-relative files referenced by some nav leaf's link.
+	linked_files() {
+		const set = new Set();
+		this._walk(this.items, (n) => {
+			if (typeof n.link === "string" && n.link) {
+				const r = this._resolve_file(n.link);
+				if (r.file) set.add(r.file);
+			}
+		});
+		return set;
+	}
+
+	// Every file on disk under the book (excluding "_" folders), each tagged with
+	// its kind (page/image/other). Pages also carry a linked flag (in nav or not).
+	list_files() {
+		const linked = this.linked_files();
+		const root = path.join(this.source_path, this.docId);
+		const files = [];
+		const dirs = [];
+		const walk = (absDir) => {
+			for (const e of fs.readdirSync(absDir, { withFileTypes: true })) {
+				if (e.name.startsWith("_")) continue; // skip special folders/files
+				const abs = path.join(absDir, e.name);
+				const rel = path.relative(this.source_path, abs).split(path.sep).join("/");
+				if (e.isDirectory()) {
+					dirs.push(rel);
+					walk(abs);
+				} else {
+					const kind = kind_of(e.name);
+					files.push({
+						file: rel,
+						kind,
+						linked: kind === "page" ? linked.has(rel) : false,
+					});
+				}
+			}
+		};
+		if (fs.existsSync(root)) walk(root);
+		files.sort((a, b) => a.file.localeCompare(b.file));
+		dirs.sort((a, b) => a.localeCompare(b));
+		return { docId: this.docId, dirs, files };
+	}
+
+	create_file(rel, content = "") {
+		const { abs, rel: r } = this._safe_rel(rel, { dir: false });
+		if (fs.existsSync(abs)) throw new Error("A file already exists at that path");
+		fs.mkdirSync(path.dirname(abs), { recursive: true });
+		fs.writeFileSync(abs, content, "utf8");
+		return r;
+	}
+
+	create_folder(rel) {
+		const { abs, rel: r } = this._safe_rel(rel, { dir: true });
+		fs.mkdirSync(abs, { recursive: true });
+		return r;
+	}
+
+	// Delete any file (page, image, or other asset) inside the book.
+	delete_file(rel) {
+		const { abs, rel: r } = this._safe_rel(rel, { dir: false, exts: null });
+		if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+			throw new Error("File not found");
+		}
+		fs.unlinkSync(abs);
+		return r;
+	}
+
+	// Validate + return the absolute path for an uploaded image/asset.
+	resolve_upload(rel) {
+		return this._safe_rel(rel, { dir: false, exts: IMAGE_EXTS });
+	}
+
+	// --- nav create / remove (Phase 1c) ---
+
+	_dest_array(parentId) {
+		if (parentId === null || parentId === undefined) return this.items;
+		const parent = this.find_node(parentId);
+		if (!parent) throw new Error(`Unknown parent id: ${parentId}`);
+		if (!Array.isArray(parent.items)) {
+			throw new Error("Target node is a leaf and cannot contain children");
+		}
+		return parent.items;
+	}
+
+	_insert(dest, index, node) {
+		let idx = typeof index === "number" ? index : dest.length;
+		idx = Math.max(0, Math.min(idx, dest.length));
+		dest.splice(idx, 0, node);
+	}
+
+	// Add a nav leaf that links to an existing page.
+	create_leaf(parentId, index, text, link) {
+		const dest = this._dest_array(parentId);
+		const node = { id: generate_id(this.used_ids), text: text || "", link };
+		this._insert(dest, index, node);
+		this.persist();
+		return node.id;
+	}
+
+	// Add an empty nav section (branch container).
+	add_section(parentId, index, text) {
+		const dest = this._dest_array(parentId);
+		const node = { id: generate_id(this.used_ids), text: text || "", items: [] };
+		this._insert(dest, index, node);
+		this.persist();
+		return node.id;
+	}
+
+	// Remove a nav node (unlink). Returns the removed node so the caller can
+	// optionally delete its backing file.
+	remove_node(id) {
+		const loc = this._locate(id);
+		if (!loc) throw new Error(`Unknown node id: ${id}`);
+		loc.parent.splice(loc.index, 1);
+		this.persist();
+		return loc.node;
+	}
+
+	// Normalized tree for the editor UI. Numbering is derived from sibling
+	// position (1, 1.1, 1.2, 2, ...) and never stored.
+	to_dto() {
+		const walk = (nodes, prefix) =>
+			nodes.map((n, i) => {
+				const number = prefix ? `${prefix}.${i + 1}` : `${i + 1}`;
+				const base = {
+					id: n.id,
+					text: typeof n.text === "string" ? n.text : "",
+					number,
+					draft: n.draft === true,
+				};
+				if (Array.isArray(n.items)) {
+					return {
+						...base,
+						type: "branch",
+						expand: n.expand === true,
+						children: walk(n.items, number),
+					};
+				}
+				const link = typeof n.link === "string" ? n.link : null;
+				const resolved = link
+					? this._resolve_file(link)
+					: { file: null, fileExists: false };
+				return {
+					...base,
+					type: "leaf",
+					link,
+					file: resolved.file,
+					fileExists: resolved.fileExists,
+				};
+			});
+
+		return {
+			docId: this.docId,
+			title: typeof this.raw.title === "string" ? this.raw.title : "",
+			idsPendingPersist: this.ids_pending_persist,
+			tree: walk(this.items, ""),
+		};
+	}
+}
+
+exports.TocModel = TocModel;
+exports.generate_id = generate_id;
+exports.ID_ALPHABET = ID_ALPHABET;
+exports.ID_LENGTH = ID_LENGTH;

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
 	"name": "hdoc-tools",
-	"version": "0.57.2",
+	"version": "0.57.3",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "hdoc-tools",
-			"version": "0.57.2",
+			"version": "0.57.3",
 			"hasInstallScript": true,
 			"license": "ISC",
 			"dependencies": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "hdoc-tools",
-	"version": "0.57.2",
+	"version": "0.57.3",
 	"description": "Hornbill HDocBook Development Support Tool",
 	"main": "hdoc.js",
 	"bin": {
@@ -23,7 +23,9 @@
 		"hdoc-mermaid.js",
 		"hdoc-module.js",
 		"hdoc-serve.js",
+		"hdoc-spell.js",
 		"hdoc-stats.js",
+		"hdoc-toc.js",
 		"hdoc-validate.js",
 		"hdoc-validate-config.js",
 		"hdoc-ver.js",