epub-optimizer 0.0.0-stage → 3.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +1434 -2
  3. package/dist/src/batch.d.ts +34 -0
  4. package/dist/src/batch.js +137 -0
  5. package/dist/src/cli.d.ts +7 -0
  6. package/dist/src/cli.js +275 -0
  7. package/dist/src/index.d.ts +23 -0
  8. package/dist/src/index.js +24 -0
  9. package/dist/src/optimization.d.ts +7 -0
  10. package/dist/src/optimization.js +207 -0
  11. package/dist/src/pipeline.d.ts +2 -0
  12. package/dist/src/pipeline.js +48 -0
  13. package/dist/src/processors/archive-processor.d.ts +26 -0
  14. package/dist/src/processors/archive-processor.js +170 -0
  15. package/dist/src/processors/epub-processor.d.ts +17 -0
  16. package/dist/src/processors/epub-processor.js +133 -0
  17. package/dist/src/processors/font-characters.d.ts +2 -0
  18. package/dist/src/processors/font-characters.js +227 -0
  19. package/dist/src/processors/font-engine.d.ts +6 -0
  20. package/dist/src/processors/font-engine.js +101 -0
  21. package/dist/src/processors/font-limits.d.ts +3 -0
  22. package/dist/src/processors/font-limits.js +3 -0
  23. package/dist/src/processors/font-processor.d.ts +4 -0
  24. package/dist/src/processors/font-processor.js +121 -0
  25. package/dist/src/processors/font-runner.d.ts +8 -0
  26. package/dist/src/processors/font-runner.js +94 -0
  27. package/dist/src/processors/font-worker.d.ts +1 -0
  28. package/dist/src/processors/font-worker.js +12 -0
  29. package/dist/src/processors/html-processor.d.ts +22 -0
  30. package/dist/src/processors/html-processor.js +190 -0
  31. package/dist/src/processors/image-converter.d.ts +14 -0
  32. package/dist/src/processors/image-converter.js +481 -0
  33. package/dist/src/processors/image-processor.d.ts +24 -0
  34. package/dist/src/processors/image-processor.js +165 -0
  35. package/dist/src/processors/js-processor.d.ts +7 -0
  36. package/dist/src/processors/js-processor.js +59 -0
  37. package/dist/src/processors/lazy-img.d.ts +5 -0
  38. package/dist/src/processors/lazy-img.js +48 -0
  39. package/dist/src/processors/svg-optimizer.d.ts +5 -0
  40. package/dist/src/processors/svg-optimizer.js +49 -0
  41. package/dist/src/scripts/create-epub.d.ts +2 -0
  42. package/dist/src/scripts/create-epub.js +29 -0
  43. package/dist/src/scripts/fix/fix-span-tags.d.ts +2 -0
  44. package/dist/src/scripts/fix/fix-span-tags.js +36 -0
  45. package/dist/src/scripts/fix/fix-xml.d.ts +3 -0
  46. package/dist/src/scripts/fix/fix-xml.js +59 -0
  47. package/dist/src/scripts/fix/index.d.ts +5 -0
  48. package/dist/src/scripts/fix/index.js +20 -0
  49. package/dist/src/scripts/fix/remove-empty-styles.d.ts +10 -0
  50. package/dist/src/scripts/fix/remove-empty-styles.js +53 -0
  51. package/dist/src/scripts/fix/xhtml-files.d.ts +2 -0
  52. package/dist/src/scripts/fix/xhtml-files.js +34 -0
  53. package/dist/src/scripts/ops/add-chapter-sections-to-toc.d.ts +5 -0
  54. package/dist/src/scripts/ops/add-chapter-sections-to-toc.js +242 -0
  55. package/dist/src/scripts/ops/add-cover-image-property.d.ts +2 -0
  56. package/dist/src/scripts/ops/add-cover-image-property.js +27 -0
  57. package/dist/src/scripts/ops/ncx.d.ts +6 -0
  58. package/dist/src/scripts/ops/ncx.js +19 -0
  59. package/dist/src/scripts/ops/update-cover-linear.d.ts +11 -0
  60. package/dist/src/scripts/ops/update-cover-linear.js +45 -0
  61. package/dist/src/scripts/ops/update-structure.d.ts +5 -0
  62. package/dist/src/scripts/ops/update-structure.js +22 -0
  63. package/dist/src/scripts/ops/update-summary-page.d.ts +2 -0
  64. package/dist/src/scripts/ops/update-summary-page.js +53 -0
  65. package/dist/src/scripts/ops/update-toc-with-cover.d.ts +2 -0
  66. package/dist/src/scripts/ops/update-toc-with-cover.js +140 -0
  67. package/dist/src/scripts/utils.d.ts +53 -0
  68. package/dist/src/scripts/utils.js +92 -0
  69. package/dist/src/scripts/validate-epub.d.ts +12 -0
  70. package/dist/src/scripts/validate-epub.js +185 -0
  71. package/dist/src/storage.d.ts +30 -0
  72. package/dist/src/storage.js +286 -0
  73. package/dist/src/types.d.ts +51 -0
  74. package/dist/src/types.js +1 -0
  75. package/dist/src/utils/author-workflow-config.d.ts +17 -0
  76. package/dist/src/utils/author-workflow-config.js +95 -0
  77. package/dist/src/utils/buffered-process.d.ts +8 -0
  78. package/dist/src/utils/buffered-process.js +36 -0
  79. package/dist/src/utils/cli-config.d.ts +4 -0
  80. package/dist/src/utils/cli-config.js +84 -0
  81. package/dist/src/utils/config.d.ts +49 -0
  82. package/dist/src/utils/config.js +58 -0
  83. package/dist/src/utils/diagnostics.d.ts +11 -0
  84. package/dist/src/utils/diagnostics.js +38 -0
  85. package/dist/src/utils/epub-doctor.d.ts +78 -0
  86. package/dist/src/utils/epub-doctor.js +301 -0
  87. package/dist/src/utils/epub-features.d.ts +20 -0
  88. package/dist/src/utils/epub-features.js +105 -0
  89. package/dist/src/utils/epub-integrity.d.ts +25 -0
  90. package/dist/src/utils/epub-integrity.js +197 -0
  91. package/dist/src/utils/epub-text.d.ts +13 -0
  92. package/dist/src/utils/epub-text.js +106 -0
  93. package/dist/src/utils/epub-utils.d.ts +79 -0
  94. package/dist/src/utils/epub-utils.js +207 -0
  95. package/dist/src/utils/epubcheck-report.d.ts +35 -0
  96. package/dist/src/utils/epubcheck-report.js +68 -0
  97. package/dist/src/utils/file-size.d.ts +13 -0
  98. package/dist/src/utils/file-size.js +40 -0
  99. package/dist/src/utils/files.d.ts +14 -0
  100. package/dist/src/utils/files.js +39 -0
  101. package/dist/src/utils/html-report.d.ts +17 -0
  102. package/dist/src/utils/html-report.js +95 -0
  103. package/dist/src/utils/i18n.d.ts +5 -0
  104. package/dist/src/utils/i18n.js +9 -0
  105. package/dist/src/utils/output-transaction.d.ts +8 -0
  106. package/dist/src/utils/output-transaction.js +146 -0
  107. package/dist/src/utils/package-root.d.ts +2 -0
  108. package/dist/src/utils/package-root.js +15 -0
  109. package/dist/src/utils/path-safety.d.ts +2 -0
  110. package/dist/src/utils/path-safety.js +30 -0
  111. package/dist/src/utils/pipeline-options.d.ts +34 -0
  112. package/dist/src/utils/pipeline-options.js +49 -0
  113. package/dist/src/utils/png-animation.d.ts +7 -0
  114. package/dist/src/utils/png-animation.js +44 -0
  115. package/dist/src/utils/run-report.d.ts +49 -0
  116. package/dist/src/utils/run-report.js +71 -0
  117. package/dist/src/utils/temp-dir.d.ts +11 -0
  118. package/dist/src/utils/temp-dir.js +80 -0
  119. package/dist/src/utils/watch-lock.d.ts +8 -0
  120. package/dist/src/utils/watch-lock.js +100 -0
  121. package/dist/src/utils/watch-summary.d.ts +13 -0
  122. package/dist/src/utils/watch-summary.js +130 -0
  123. package/dist/src/utils/xhtml-structure.d.ts +7 -0
  124. package/dist/src/utils/xhtml-structure.js +53 -0
  125. package/dist/src/utils/xhtml.d.ts +27 -0
  126. package/dist/src/utils/xhtml.js +205 -0
  127. package/dist/src/utils/xml-dtd.d.ts +6 -0
  128. package/dist/src/utils/xml-dtd.js +133 -0
  129. package/dist/src/watch.d.ts +21 -0
  130. package/dist/src/watch.js +328 -0
  131. package/package.json +99 -3
  132. package/scripts/install-epubcheck.sh +44 -0
@@ -0,0 +1,80 @@
1
+ import fs from "fs-extra";
2
+ import os from "node:os";
3
+ import path from "node:path";
4
+ export const TEMP_DIR_MARKER = ".epub-optimizer-temp.json";
5
+ function canonicalPath(filePath) {
6
+ const suffix = [];
7
+ let current = path.resolve(filePath);
8
+ while (!fs.existsSync(current)) {
9
+ suffix.unshift(path.basename(current));
10
+ const parent = path.dirname(current);
11
+ if (parent === current)
12
+ break;
13
+ current = parent;
14
+ }
15
+ return path.join(fs.realpathSync(current), ...suffix);
16
+ }
17
+ function resolveUserPath(filePath, cwd) {
18
+ return path.resolve(cwd, filePath);
19
+ }
20
+ function isSameOrInside(candidate, parent) {
21
+ const relative = path.relative(parent, candidate);
22
+ return (relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative)));
23
+ }
24
+ function assertSafeTempDir(tempDir, options = {}) {
25
+ if (!tempDir || tempDir.trim() === "") {
26
+ throw new Error("Refusing empty temporary directory path.");
27
+ }
28
+ const cwd = path.resolve(options.cwd ?? process.cwd());
29
+ const resolvedTempDir = resolveUserPath(tempDir, cwd);
30
+ const rootDir = path.parse(resolvedTempDir).root;
31
+ const homeDir = path.resolve(options.homeDir ?? os.homedir());
32
+ const canonicalTempDir = canonicalPath(resolvedTempDir);
33
+ if (resolvedTempDir === rootDir) {
34
+ throw new Error(`Refusing unsafe temporary directory: ${resolvedTempDir}`);
35
+ }
36
+ if (isSameOrInside(canonicalPath(cwd), canonicalTempDir)) {
37
+ throw new Error(`Refusing to use the current working directory as temp: ${resolvedTempDir}`);
38
+ }
39
+ if (homeDir !== rootDir && canonicalTempDir === canonicalPath(homeDir)) {
40
+ throw new Error(`Refusing to use the home directory as temp: ${resolvedTempDir}`);
41
+ }
42
+ if (options.inputPath) {
43
+ const inputPath = canonicalPath(resolveUserPath(options.inputPath, cwd));
44
+ if (isSameOrInside(inputPath, canonicalTempDir)) {
45
+ throw new Error(`Refusing temp directory that contains the input EPUB: ${resolvedTempDir}`);
46
+ }
47
+ }
48
+ if (options.outputPath) {
49
+ const outputPath = canonicalPath(resolveUserPath(options.outputPath, cwd));
50
+ if (isSameOrInside(outputPath, canonicalTempDir)) {
51
+ throw new Error(`Refusing temp directory that contains the output EPUB: ${resolvedTempDir}`);
52
+ }
53
+ }
54
+ return resolvedTempDir;
55
+ }
56
+ async function removeTempDir(tempDir, options = {}) {
57
+ const safeTempDir = assertSafeTempDir(tempDir, options);
58
+ const stat = await fs.lstat(safeTempDir);
59
+ if (!stat.isDirectory() || stat.isSymbolicLink()) {
60
+ throw new Error(`Refusing to remove non-directory or symbolic link: ${safeTempDir}`);
61
+ }
62
+ const marker = await fs.readJson(path.join(safeTempDir, TEMP_DIR_MARKER));
63
+ if (marker.version !== 1 || marker.directory !== path.basename(safeTempDir)) {
64
+ throw new Error(`Refusing to remove unowned temporary directory: ${safeTempDir}`);
65
+ }
66
+ await fs.remove(safeTempDir);
67
+ return safeTempDir;
68
+ }
69
+ export async function createManagedTempDir(tempDir, inputPath) {
70
+ const safeTempDir = assertSafeTempDir(tempDir, { inputPath });
71
+ // Atomic mkdir: concurrent runs and existing user data are never overwritten.
72
+ await fs.ensureDir(path.dirname(safeTempDir));
73
+ await fs.mkdir(safeTempDir, { mode: 0o700 });
74
+ await fs.writeJson(path.join(safeTempDir, TEMP_DIR_MARKER), {
75
+ version: 1,
76
+ // Keep the marker usable from both the Docker mount and the host path.
77
+ directory: path.basename(safeTempDir),
78
+ }, { flag: "wx" });
79
+ }
80
+ export { assertSafeTempDir, removeTempDir };
@@ -0,0 +1,8 @@
1
+ export interface KernelWatchLock {
2
+ identity: string;
3
+ release(): Promise<void>;
4
+ }
5
+ /** Linux flock is released by the kernel after process/container death, across PID namespaces. */
6
+ export declare function acquireKernelWatchLock(output: string): Promise<KernelWatchLock | undefined>;
7
+ /** Only modern kernel-backed records can be recovered while holding the same guard. */
8
+ export declare function clearRecoverableWatchRecord(lock: string, guardIdentity: string): Promise<void>;
@@ -0,0 +1,100 @@
1
+ import fs from "fs-extra";
2
+ import path from "node:path";
3
+ import { open } from "node:fs/promises";
4
+ import { constants } from "node:fs";
5
+ import { spawnSync } from "node:child_process";
6
+ /** Linux flock is released by the kernel after process/container death, across PID namespaces. */
7
+ export async function acquireKernelWatchLock(output) {
8
+ if (process.platform !== "linux")
9
+ return undefined;
10
+ const guard = path.join(output, ".epub-watch.guard");
11
+ let file;
12
+ try {
13
+ file = await open(guard, "wx", 0o600);
14
+ }
15
+ catch (error) {
16
+ if (error.code !== "EEXIST")
17
+ throw error;
18
+ file = await open(guard, constants.O_RDWR | constants.O_NOFOLLOW | constants.O_NONBLOCK);
19
+ }
20
+ let retained = false;
21
+ try {
22
+ const owner = await file.stat();
23
+ if (!owner.isFile() || owner.nlink !== 1)
24
+ throw new Error("Refusing unsafe watch guard file");
25
+ // fd 3 is a duplicate of our open file description. Linux keeps the lock
26
+ // on our descriptor after the short-lived flock utility exits.
27
+ // https://man7.org/linux/man-pages/man2/flock.2.html
28
+ const result = spawnSync("/usr/bin/flock", ["--exclusive", "--nonblock", "--conflict-exit-code", "73", "3"], {
29
+ stdio: ["ignore", "pipe", "pipe", file.fd],
30
+ timeout: 5000,
31
+ });
32
+ if (result.error?.code === "ENOENT")
33
+ return undefined;
34
+ if (result.error || result.status !== 0)
35
+ throw new Error(result.status === 73
36
+ ? "Another watcher holds the output guard"
37
+ : "Cannot acquire the Linux watch guard");
38
+ const current = await fs.lstat(guard);
39
+ if (!current.isFile() ||
40
+ current.dev !== owner.dev ||
41
+ current.ino !== owner.ino ||
42
+ current.nlink !== 1)
43
+ throw new Error("Watch guard identity changed");
44
+ // Some shared mounts emulate process-scoped locks. Prove retention via an
45
+ // independently opened descriptor before relying on it for crash recovery.
46
+ const probe = await open(guard, constants.O_RDWR | constants.O_NOFOLLOW | constants.O_NONBLOCK);
47
+ try {
48
+ const check = await probe.stat();
49
+ if (check.dev !== owner.dev || check.ino !== owner.ino)
50
+ throw new Error("Watch guard identity changed");
51
+ const competition = spawnSync("/usr/bin/flock", ["--exclusive", "--nonblock", "--conflict-exit-code", "73", "3"], { stdio: ["ignore", "pipe", "pipe", probe.fd], timeout: 5000 });
52
+ if (competition.error || ![0, 73].includes(competition.status ?? -1))
53
+ throw new Error("Cannot verify retained watch guard");
54
+ if (competition.status === 0)
55
+ return undefined;
56
+ }
57
+ finally {
58
+ await probe.close();
59
+ }
60
+ retained = true;
61
+ return { identity: `${owner.dev}:${owner.ino}`, release: () => file.close() };
62
+ }
63
+ finally {
64
+ if (!retained)
65
+ await file.close();
66
+ }
67
+ }
68
+ /** Only modern kernel-backed records can be recovered while holding the same guard. */
69
+ export async function clearRecoverableWatchRecord(lock, guardIdentity) {
70
+ let handle;
71
+ try {
72
+ handle = await open(lock, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
73
+ const owner = await handle.stat();
74
+ if (!owner.isFile() || owner.size > 65536 || owner.nlink !== 1)
75
+ throw new Error("Unsafe watch lock record");
76
+ const bytes = Buffer.alloc(65537);
77
+ const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
78
+ if (bytesRead > 65536)
79
+ throw new Error("Oversized watch lock record");
80
+ const record = JSON.parse(bytes.subarray(0, bytesRead).toString("utf8"));
81
+ if (!record ||
82
+ typeof record !== "object" ||
83
+ !("method" in record) ||
84
+ record.method !== "linux-flock-v1" ||
85
+ !("guard" in record) ||
86
+ record.guard !== guardIdentity)
87
+ throw new Error("Legacy or unknown watch lock requires manual recovery after confirming inactivity");
88
+ const current = await fs.lstat(lock);
89
+ if (!current.isFile() || current.dev !== owner.dev || current.ino !== owner.ino)
90
+ throw new Error("Watch lock identity changed");
91
+ await fs.unlink(lock);
92
+ }
93
+ catch (error) {
94
+ if (error.code !== "ENOENT")
95
+ throw error;
96
+ }
97
+ finally {
98
+ await handle?.close();
99
+ }
100
+ }
@@ -0,0 +1,13 @@
1
+ export interface WatchSummaryItem {
2
+ name: string;
3
+ job: string;
4
+ success: boolean;
5
+ outputPublished: boolean;
6
+ error?: string;
7
+ reductionPercent?: number;
8
+ }
9
+ export declare function collectWatchSummary(output: string): Promise<WatchSummaryItem[]>;
10
+ export declare function renderWatchSummary(items: WatchSummaryItem[]): string;
11
+ /** Rename a private sibling rather than truncating an existing file or hard-link alias. */
12
+ export declare function writeWatchFile(file: string, content: string): Promise<void>;
13
+ export declare function refreshWatchSummary(output: string): Promise<void>;
@@ -0,0 +1,130 @@
1
+ import fs from "fs-extra";
2
+ import path from "node:path";
3
+ import { open } from "node:fs/promises";
4
+ import { constants } from "node:fs";
5
+ import { randomUUID } from "node:crypto";
6
+ import { escapeHtml, htmlDocument } from "./html-report.js";
7
+ async function readRecord(file) {
8
+ let handle;
9
+ try {
10
+ handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
11
+ const stat = await handle.stat();
12
+ if (!stat.isFile() || stat.size > 1024 * 1024)
13
+ return undefined;
14
+ const buffer = Buffer.alloc(1024 * 1024 + 1);
15
+ let bytesRead = 0;
16
+ while (bytesRead < buffer.length) {
17
+ const chunk = await handle.read(buffer, bytesRead, buffer.length - bytesRead, bytesRead);
18
+ if (!chunk.bytesRead)
19
+ break;
20
+ bytesRead += chunk.bytesRead;
21
+ }
22
+ if (bytesRead > 1024 * 1024)
23
+ return undefined;
24
+ const value = JSON.parse(buffer.subarray(0, bytesRead).toString("utf8"));
25
+ return value !== null && typeof value === "object" && !Array.isArray(value)
26
+ ? value
27
+ : undefined;
28
+ }
29
+ catch {
30
+ return undefined;
31
+ }
32
+ finally {
33
+ await handle?.close();
34
+ }
35
+ }
36
+ export async function collectWatchSummary(output) {
37
+ const items = [];
38
+ for (const entry of await fs.readdir(output, { withFileTypes: true })) {
39
+ if (!entry.isDirectory() ||
40
+ !/^[a-zA-Z0-9_-]+-[a-f0-9]{16}-[a-f0-9]{64}-[a-f0-9]{16}$/.test(entry.name))
41
+ continue;
42
+ const job = path.join(output, entry.name);
43
+ let record = await readRecord(path.join(job, "watch-status.json"));
44
+ if (!record) {
45
+ const report = await readRecord(path.join(job, "report.json"));
46
+ const completion = await readRecord(path.join(job, "completed.json"));
47
+ if (report && typeof report.success === "boolean") {
48
+ const sizes = report.sizes !== null && typeof report.sizes === "object"
49
+ ? report.sizes
50
+ : undefined;
51
+ record = {
52
+ name: typeof completion?.input === "string"
53
+ ? path.basename(completion.input)
54
+ : entry.name.replace(/-[a-f0-9]{16}-[a-f0-9]{64}-[a-f0-9]{16}$/, ""),
55
+ success: report.success,
56
+ error: report.error,
57
+ reductionPercent: sizes?.reductionPercent,
58
+ outputPublished: Array.isArray(report.steps) &&
59
+ report.steps.some((step) => step !== null &&
60
+ typeof step === "object" &&
61
+ "name" in step &&
62
+ step.name === "Publish validated EPUB" &&
63
+ "status" in step &&
64
+ step.status === "success"),
65
+ };
66
+ }
67
+ }
68
+ if (!record || typeof record.name !== "string" || typeof record.success !== "boolean")
69
+ continue;
70
+ items.push({
71
+ name: record.name.slice(0, 1024),
72
+ job: entry.name,
73
+ success: record.success,
74
+ outputPublished: record.outputPublished === true,
75
+ error: typeof record.error === "string" ? record.error.slice(0, 4096) : undefined,
76
+ reductionPercent: typeof record.reductionPercent === "number" && Number.isFinite(record.reductionPercent)
77
+ ? record.reductionPercent
78
+ : undefined,
79
+ });
80
+ }
81
+ return items.sort((a, b) => a.name.localeCompare(b.name) || a.job.localeCompare(b.job));
82
+ }
83
+ export function renderWatchSummary(items) {
84
+ const e = escapeHtml;
85
+ const rows = items
86
+ .map((item) => {
87
+ const link = (file, label) => `<a href="${e(encodeURIComponent(item.job) + "/" + file)}">${label}</a>`;
88
+ return `<tr><td>${e(item.name)}</td><td>${item.success ? "Completed" : "Failed"}</td><td>${item.reductionPercent === undefined ? "—" : `${item.reductionPercent.toFixed(1)}%`}</td><td>${item.outputPublished ? link("optimized.epub", "EPUB") : "—"} · ${link("report.html", "HTML report")} · ${link("report.json", "JSON report")}</td><td>${e(item.error ?? "—")}</td></tr>`;
89
+ })
90
+ .join("");
91
+ return htmlDocument("Watched-folder results", `<header><p>EPUB Optimizer · watched folder</p><h1>Watched-folder results</h1></header><p>${items.filter((i) => i.success).length} completed · ${items.filter((i) => !i.success).length} failed</p><p>Updated ${e(new Date().toISOString())}. Refresh this page after processing. Separate rows can represent different versions or settings of the same book.</p><div class="table"><table><thead><tr><th>Book</th><th>Result</th><th>Reduction</th><th>Files</th><th>Diagnostic</th></tr></thead><tbody>${rows || '<tr><td colspan="5">No recorded results yet.</td></tr>'}</tbody></table></div><p>A failed run may still have published a validated EPUB if a later reporting or cleanup step failed. Inspect the detailed report. An unchanged failure is retried after changing the input or restarting the watcher.</p>`);
92
+ }
93
+ /** Rename a private sibling rather than truncating an existing file or hard-link alias. */
94
+ export async function writeWatchFile(file, content) {
95
+ try {
96
+ const stat = await fs.lstat(file);
97
+ if (!stat.isFile())
98
+ throw new Error("Refusing unsafe watch summary target");
99
+ }
100
+ catch (error) {
101
+ if (error.code !== "ENOENT")
102
+ throw error;
103
+ }
104
+ const temporary = path.join(path.dirname(file), `.watch-summary-${randomUUID()}`);
105
+ const handle = await open(temporary, "wx", 0o644);
106
+ const owner = await handle.stat();
107
+ try {
108
+ await handle.writeFile(content);
109
+ await handle.close();
110
+ await fs.rename(temporary, file);
111
+ }
112
+ finally {
113
+ await handle.close();
114
+ await removeOwnedTemporary(temporary, owner.dev, owner.ino);
115
+ }
116
+ }
117
+ export async function refreshWatchSummary(output) {
118
+ await writeWatchFile(path.join(output, "index.html"), renderWatchSummary(await collectWatchSummary(output)));
119
+ }
120
+ async function removeOwnedTemporary(file, dev, ino) {
121
+ try {
122
+ const current = await fs.lstat(file);
123
+ if (current.dev === dev && current.ino === ino && current.isFile())
124
+ await fs.unlink(file);
125
+ }
126
+ catch (error) {
127
+ if (error.code !== "ENOENT")
128
+ throw error;
129
+ }
130
+ }
@@ -0,0 +1,7 @@
1
+ import type { CheerioAPI } from "cheerio";
2
+ /**
3
+ * Fingerprint the XML tree, identifiers, namespaces and the position of character
4
+ * data. Ignore comments and the CSS/JS values deliberately minified elsewhere.
5
+ * This is a preservation check, not a replacement for EPUBCheck validation.
6
+ */
7
+ export declare function xhtmlStructure($: CheerioAPI): string;
@@ -0,0 +1,53 @@
1
+ import { createHash } from "node:crypto";
2
+ import { decodeXhtmlEntities } from "./xhtml.js";
3
+ /**
4
+ * Fingerprint the XML tree, identifiers, namespaces and the position of character
5
+ * data. Ignore comments and the CSS/JS values deliberately minified elsewhere.
6
+ * This is a preservation check, not a replacement for EPUBCheck validation.
7
+ */
8
+ export function xhtmlStructure($) {
9
+ const hash = createHash("sha256");
10
+ const stack = $.root().children().toArray()
11
+ .reverse()
12
+ .map((node) => ({ node, literal: false }));
13
+ let text = [];
14
+ const flushText = () => {
15
+ if (text.length) {
16
+ hash.update(JSON.stringify(["text", text.join("").replace(/\r\n?/g, "\n")]));
17
+ text = [];
18
+ }
19
+ };
20
+ while (stack.length) {
21
+ const { node, literal, ignoreText, close } = stack.pop();
22
+ if (close) {
23
+ flushText();
24
+ hash.update("]");
25
+ }
26
+ else if (node.type === "text") {
27
+ if (!ignoreText)
28
+ text.push(literal ? (node.data ?? "") : decodeXhtmlEntities(node.data ?? ""));
29
+ }
30
+ else if (node.name && ["tag", "script", "style"].includes(node.type)) {
31
+ flushText();
32
+ const attributes = Object.entries(node.attribs ?? {})
33
+ .filter(([name]) => name === "id" || name === "xml:id" || name === "xmlns" || name.startsWith("xmlns:"))
34
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
35
+ .map(([name, value]) => [name, decodeXhtmlEntities(value)]);
36
+ hash.update(JSON.stringify(["element", node.name, attributes]));
37
+ stack.push({ node, literal, close: true });
38
+ const localName = node.name.split(":").at(-1)?.toLowerCase();
39
+ for (let i = (node.children?.length ?? 0) - 1; i >= 0; i--)
40
+ stack.push({
41
+ node: node.children[i],
42
+ literal,
43
+ ignoreText: ignoreText || localName === "script" || localName === "style",
44
+ });
45
+ }
46
+ else if (node.type === "cdata") {
47
+ for (let i = (node.children?.length ?? 0) - 1; i >= 0; i--)
48
+ stack.push({ node: node.children[i], literal: true, ignoreText });
49
+ }
50
+ }
51
+ flushText();
52
+ return hash.digest("hex");
53
+ }
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Rewrite HTML5-style void elements (`<br>`, `<link rel="…">`, etc.) as
3
+ * self-closing XHTML (`<br />`, `<link rel="…" />`). Already-closed tags
4
+ * are left alone. Only actual markup is changed: quoted attributes, comments,
5
+ * declarations, CDATA, and script/style bodies are preserved byte for byte.
6
+ */
7
+ export declare function normalizeVoidElements(content: string, opts?: {
8
+ removeInvalidBrClosings?: boolean;
9
+ }): string;
10
+ /** Decode one level of XHTML references, preserving XML numeric code points. */
11
+ export declare function decodeXhtmlEntities(text: string): string;
12
+ /**
13
+ * Rewrite HTML named character references (`&nbsp;`, `&eacute;`, …) as numeric
14
+ * ones (`&#xa0;`, `&#xe9;`). XHTML 1.1 documents (EPUB 2) may use them, but an
15
+ * XML parser without the DTD leaves them as literal text and re-escapes the
16
+ * ampersand on output, which would display `&nbsp;` to the reader. Comments,
17
+ * CDATA, processing instructions and declarations are preserved byte for byte;
18
+ * names that are not HTML entities are left for the reader to resolve.
19
+ */
20
+ export declare function normalizeNamedEntities(content: string): string;
21
+ /**
22
+ * Best-effort detection of XHTML content. Returns true if the string contains
23
+ * any of the canonical XHTML markers: an XML declaration, the XHTML namespace,
24
+ * or an XHTML DOCTYPE. We only inspect the first 2KB since these markers live
25
+ * near the top of the file.
26
+ */
27
+ export declare function isXHTMLContent(content: string): boolean;
@@ -0,0 +1,205 @@
1
+ import { decodeHTMLStrict } from "entities";
2
+ // HTML5 void elements — must be self-closed in XHTML.
3
+ // See: https://html.spec.whatwg.org/multipage/syntax.html#void-elements
4
+ const VOID_ELEMENTS = [
5
+ "area",
6
+ "base",
7
+ "br",
8
+ "col",
9
+ "embed",
10
+ "hr",
11
+ "img",
12
+ "input",
13
+ "link",
14
+ "meta",
15
+ "param",
16
+ "source",
17
+ "track",
18
+ "wbr",
19
+ ];
20
+ const VOID_NAMES = new Set(VOID_ELEMENTS);
21
+ /** Find a markup boundary without treating quoted text as markup. */
22
+ function findMarkupEnd(content, start, declaration = false) {
23
+ let quote;
24
+ let subsetDepth = 0;
25
+ for (let i = start; i < content.length; i++) {
26
+ const char = content[i];
27
+ if (declaration && !quote && content.startsWith("<!--", i)) {
28
+ const end = content.indexOf("-->", i + 4);
29
+ if (end === -1)
30
+ return -1;
31
+ i = end + 2;
32
+ }
33
+ else if (quote) {
34
+ if (char === quote)
35
+ quote = undefined;
36
+ }
37
+ else if (char === '"' || char === "'") {
38
+ quote = char;
39
+ }
40
+ else if (declaration && char === "[") {
41
+ subsetDepth++;
42
+ }
43
+ else if (declaration && char === "]") {
44
+ subsetDepth--;
45
+ }
46
+ else if (char === ">" && subsetDepth === 0) {
47
+ return i;
48
+ }
49
+ }
50
+ return -1;
51
+ }
52
+ /**
53
+ * Rewrite HTML5-style void elements (`<br>`, `<link rel="…">`, etc.) as
54
+ * self-closing XHTML (`<br />`, `<link rel="…" />`). Already-closed tags
55
+ * are left alone. Only actual markup is changed: quoted attributes, comments,
56
+ * declarations, CDATA, and script/style bodies are preserved byte for byte.
57
+ */
58
+ export function normalizeVoidElements(content, opts = {}) {
59
+ const tagStart = /<\/?([a-z][\w:.-]*)(?=[\s/>])/giy;
60
+ const parts = [];
61
+ let copiedUntil = 0;
62
+ let position = 0;
63
+ let rawElement;
64
+ while (position < content.length) {
65
+ const start = content.indexOf("<", position);
66
+ if (start === -1)
67
+ break;
68
+ // Skip complete opaque regions, including a DTD's internal subset. Leave
69
+ // an unfinished region unchanged rather than guessing where it ends.
70
+ const terminator = content.startsWith("<!--", start)
71
+ ? "-->"
72
+ : content.startsWith("<![CDATA[", start)
73
+ ? "]]>"
74
+ : !rawElement && content.startsWith("<?", start)
75
+ ? "?>"
76
+ : undefined;
77
+ if (terminator) {
78
+ const end = content.indexOf(terminator, start + 2);
79
+ if (end === -1)
80
+ break;
81
+ position = end + terminator.length;
82
+ continue;
83
+ }
84
+ if (!rawElement && content.startsWith("<!", start)) {
85
+ const end = findMarkupEnd(content, start + 2, true);
86
+ if (end === -1)
87
+ break;
88
+ position = end + 1;
89
+ continue;
90
+ }
91
+ tagStart.lastIndex = start;
92
+ const match = tagStart.exec(content);
93
+ const name = match?.[1]?.toLowerCase();
94
+ const closing = content[start + 1] === "/";
95
+ if (!name || (rawElement && !(closing && name === rawElement))) {
96
+ position = start + 1;
97
+ continue;
98
+ }
99
+ const end = findMarkupEnd(content, tagStart.lastIndex);
100
+ if (end === -1)
101
+ break;
102
+ const selfClosed = content[end - 1] === "/";
103
+ if (rawElement) {
104
+ rawElement = undefined;
105
+ }
106
+ else if (closing && name === "br" && opts.removeInvalidBrClosings) {
107
+ parts.push(content.slice(copiedUntil, start));
108
+ copiedUntil = end + 1;
109
+ }
110
+ else if (!closing && !selfClosed && VOID_NAMES.has(name)) {
111
+ parts.push(content.slice(copiedUntil, end), " />");
112
+ copiedUntil = end + 1;
113
+ }
114
+ else if (!closing &&
115
+ !selfClosed &&
116
+ (name.split(":").at(-1) === "script" || name.split(":").at(-1) === "style")) {
117
+ rawElement = name;
118
+ }
119
+ position = end + 1;
120
+ }
121
+ parts.push(content.slice(copiedUntil));
122
+ return parts.join("");
123
+ }
124
+ // The only named references an XML parser resolves without a DTD.
125
+ const XML_ENTITY_NAMES = new Set(["amp", "lt", "gt", "quot", "apos"]);
126
+ // XHTML 1.x defines these differently from HTML5. All other shared named
127
+ // references have the same values. https://www.w3.org/TR/xhtml1/dtds.html
128
+ const XHTML_ENTITY_OVERRIDES = new Map([
129
+ ["&lang;", "\u2329"],
130
+ ["&rang;", "\u232a"],
131
+ ]);
132
+ /** Decode one level of XHTML references, preserving XML numeric code points. */
133
+ export function decodeXhtmlEntities(text) {
134
+ return text.replace(/&(?:#(?:x[\da-f]+|\d+)|[a-z][a-z\d]*);/gi, (reference) => {
135
+ if (reference.startsWith("&#")) {
136
+ const hexadecimal = reference.charAt(2).toLowerCase() === "x";
137
+ const codePoint = Number.parseInt(reference.slice(hexadecimal ? 3 : 2, -1), hexadecimal ? 16 : 10);
138
+ return codePoint > 0 && codePoint <= 0x10ffff && !(codePoint >= 0xd800 && codePoint <= 0xdfff)
139
+ ? String.fromCodePoint(codePoint)
140
+ : reference;
141
+ }
142
+ return XHTML_ENTITY_OVERRIDES.get(reference) ?? decodeHTMLStrict(reference);
143
+ });
144
+ }
145
+ /**
146
+ * Rewrite HTML named character references (`&nbsp;`, `&eacute;`, …) as numeric
147
+ * ones (`&#xa0;`, `&#xe9;`). XHTML 1.1 documents (EPUB 2) may use them, but an
148
+ * XML parser without the DTD leaves them as literal text and re-escapes the
149
+ * ampersand on output, which would display `&nbsp;` to the reader. Comments,
150
+ * CDATA, processing instructions and declarations are preserved byte for byte;
151
+ * names that are not HTML entities are left for the reader to resolve.
152
+ */
153
+ export function normalizeNamedEntities(content) {
154
+ const next = /<!--|<!\[CDATA\[|<\?|<!|&([a-z][a-z\d]*);/gi;
155
+ const parts = [];
156
+ let copiedUntil = 0;
157
+ let match;
158
+ while ((match = next.exec(content)) !== null) {
159
+ const name = match[1];
160
+ if (name === undefined) {
161
+ // Skip a complete opaque region; leave an unfinished one unchanged.
162
+ const terminator = match[0] === "<!--"
163
+ ? "-->"
164
+ : match[0] === "<![CDATA["
165
+ ? "]]>"
166
+ : match[0] === "<?"
167
+ ? "?>"
168
+ : undefined;
169
+ const end = terminator
170
+ ? content.indexOf(terminator, next.lastIndex)
171
+ : findMarkupEnd(content, next.lastIndex, true);
172
+ if (end === -1)
173
+ break;
174
+ next.lastIndex = end + (terminator?.length ?? 1);
175
+ continue;
176
+ }
177
+ if (XML_ENTITY_NAMES.has(name))
178
+ continue;
179
+ const decoded = decodeXhtmlEntities(match[0]);
180
+ if (decoded === match[0])
181
+ continue;
182
+ parts.push(content.slice(copiedUntil, match.index), Array.from(decoded, (char) => `&#x${char.codePointAt(0)?.toString(16)};`).join(""));
183
+ copiedUntil = next.lastIndex;
184
+ }
185
+ if (copiedUntil === 0)
186
+ return content;
187
+ parts.push(content.slice(copiedUntil));
188
+ return parts.join("");
189
+ }
190
+ /**
191
+ * Best-effort detection of XHTML content. Returns true if the string contains
192
+ * any of the canonical XHTML markers: an XML declaration, the XHTML namespace,
193
+ * or an XHTML DOCTYPE. We only inspect the first 2KB since these markers live
194
+ * near the top of the file.
195
+ */
196
+ export function isXHTMLContent(content) {
197
+ const head = content.slice(0, 2048);
198
+ if (/^\s*<\?xml\b/i.test(head))
199
+ return true;
200
+ if (/\bxmlns(?::[\w.-]+)?\s*=\s*(["'])http:\/\/www\.w3\.org\/1999\/xhtml\1/.test(head))
201
+ return true;
202
+ if (/<!DOCTYPE\s+html\s+PUBLIC\s+["'][^"']*XHTML/i.test(head))
203
+ return true;
204
+ return false;
205
+ }
@@ -0,0 +1,6 @@
1
+ /** Reuse the prolog scanner for already bounded, decoded XML text. */
2
+ export declare function hasInternalDtdInText(text: string): boolean;
3
+ /** List unsupported declarations without parsing XML or resolving entities. */
4
+ export declare function findInternalDtdSubsets(epubDir: string): Promise<string[]>;
5
+ /** Reject unsupported DTD semantics before parsing or changing any EPUB resource. */
6
+ export declare function assertNoInternalDtdSubsets(epubDir: string): Promise<void>;