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,106 @@
1
+ import fs from "fs-extra";
2
+ import path from "node:path";
3
+ import { createHash } from "node:crypto";
4
+ import * as cheerio from "cheerio";
5
+ import { collectManifestResources } from "./epub-utils.js";
6
+ import { collectFiles, hasExtension } from "./files.js";
7
+ import { decodeXhtmlEntities, isXHTMLContent, normalizeVoidElements } from "./xhtml.js";
8
+ const DOCUMENT_QUERY = {
9
+ mediaTypes: new Set(["application/xhtml+xml", "text/html", "image/svg+xml"]),
10
+ extensions: new Set([".xhtml", ".html", ".svg"]),
11
+ };
12
+ const RAW_TEXT_ELEMENTS = new Set(["script", "style"]);
13
+ const SVG_TEXT_ELEMENTS = new Set(["text", "title", "desc", "foreignobject"]);
14
+ function collectSvgText(node, parts) {
15
+ const name = node.name?.split(":").at(-1)?.toLowerCase();
16
+ if (name === "metadata" || (name && RAW_TEXT_ELEMENTS.has(name)))
17
+ return;
18
+ if (name && SVG_TEXT_ELEMENTS.has(name)) {
19
+ collectText(node, true, parts);
20
+ return;
21
+ }
22
+ // Whitespace between graphical elements is formatting, not displayed text.
23
+ for (const child of node.children ?? [])
24
+ collectSvgText(child, parts);
25
+ }
26
+ function collectText(node, decodeReferences, parts) {
27
+ if (node.type === "text") {
28
+ const data = node.data ?? "";
29
+ parts.push(decodeReferences ? decodeXhtmlEntities(data) : data);
30
+ return;
31
+ }
32
+ if (node.type === "comment" || node.type === "directive")
33
+ return;
34
+ if (node.name && RAW_TEXT_ELEMENTS.has(node.name.split(":").at(-1)?.toLowerCase() ?? "")) {
35
+ return;
36
+ }
37
+ // CDATA content is literal: no reference inside it is resolved.
38
+ const decodeChildren = decodeReferences && node.type !== "cdata";
39
+ for (const child of node.children ?? []) {
40
+ collectText(child, decodeChildren, parts);
41
+ }
42
+ }
43
+ /**
44
+ * Extract the text a reader sees in a content document: the character data of
45
+ * `<body>` with references resolved, excluding scripts, styles and comments.
46
+ * SVG documents include text, accessibility descriptions and foreign objects,
47
+ * excluding metadata and formatting between graphical elements.
48
+ */
49
+ export function extractDocumentText(content, filePath = "") {
50
+ // Same detection as the HTML processor, so both read the document alike.
51
+ const isXML = isXHTMLContent(content) ||
52
+ /\.(?:xhtml|svg)$/i.test(filePath) ||
53
+ /^(?:\s|<!--[\s\S]*?-->)*<(?:[\w.-]+:)?svg(?:\s|>)/i.test(content);
54
+ const $ = isXML
55
+ ? cheerio.load(normalizeVoidElements(content), { xml: { decodeEntities: false } })
56
+ : cheerio.load(content);
57
+ const body = $("body").first();
58
+ const documentRoot = $.root()[0];
59
+ const documentElement = documentRoot.children?.find((child) => child.type === "tag");
60
+ const isSVG = documentElement?.name?.split(":").at(-1)?.toLowerCase() === "svg";
61
+ const root = (body.length > 0 ? body[0] : documentRoot);
62
+ const parts = [];
63
+ if (isSVG)
64
+ collectSvgText(documentRoot, parts);
65
+ else if (root)
66
+ collectText(root, isXML, parts);
67
+ return parts.join("").replace(/\r\n?/g, "\n");
68
+ }
69
+ export async function collectEpubTextSnapshot(epubDir) {
70
+ const snapshot = new Map();
71
+ // The manifest also covers atypical file extensions. HTML processing walks
72
+ // the whole archive, so include its documents even in secondary renditions.
73
+ const [manifestDocuments, archiveDocuments] = await Promise.all([
74
+ collectManifestResources(epubDir, DOCUMENT_QUERY),
75
+ collectFiles(epubDir, (filePath) => hasExtension(filePath, DOCUMENT_QUERY.extensions)),
76
+ ]);
77
+ const documents = [...new Set([...manifestDocuments, ...archiveDocuments])];
78
+ for (const filePath of documents.sort()) {
79
+ const content = await fs.readFile(filePath, "utf8");
80
+ const document = path.relative(epubDir, filePath).split(path.sep).join("/");
81
+ // Retain a fixed-size digest per document, not the complete text of the book.
82
+ snapshot.set(document, createHash("sha256").update(extractDocumentText(content, filePath)).digest("hex"));
83
+ }
84
+ return snapshot;
85
+ }
86
+ /** @returns One message per document whose text was lost or altered. */
87
+ export function compareEpubTextSnapshots(before, after) {
88
+ const issues = [];
89
+ for (const [document, expected] of before) {
90
+ const actual = after.get(document);
91
+ if (actual === undefined) {
92
+ issues.push(`${document}: document is missing after processing.`);
93
+ continue;
94
+ }
95
+ if (actual === expected)
96
+ continue;
97
+ issues.push(`${document}: text differs after processing.`);
98
+ }
99
+ return issues;
100
+ }
101
+ export function assertEpubTextPreserved(before, after) {
102
+ const issues = compareEpubTextSnapshots(before, after);
103
+ if (issues.length > 0) {
104
+ throw new Error(`Text preservation check failed:\n- ${issues.join("\n- ")}`);
105
+ }
106
+ }
@@ -0,0 +1,79 @@
1
+ import * as cheerio from "cheerio";
2
+ /**
3
+ * Dynamically reads the OPF file path from META-INF/container.xml
4
+ * This follows the EPUB specification instead of hardcoding filenames
5
+ * @param epubDir Path to the extracted EPUB directory
6
+ * @returns Full path to the OPF file
7
+ * @throws Error if container.xml is not found or OPF path cannot be determined
8
+ */
9
+ export declare function getOPFPath(epubDir: string): Promise<string>;
10
+ /**
11
+ * Determines the content directory used by the EPUB
12
+ * Checks for standard directory conventions: OPS (modern) and OEBPS (legacy)
13
+ * @param epubDir Path to the extracted EPUB directory
14
+ * @returns The content directory name (e.g., "OPS", "OEBPS") or empty string if content is in root
15
+ */
16
+ export declare function getContentDir(epubDir: string): Promise<string>;
17
+ /**
18
+ * Gets the full path to the content directory
19
+ * @param epubDir Path to the extracted EPUB directory
20
+ * @returns Full path to the content directory
21
+ */
22
+ export declare function getContentPath(epubDir: string): Promise<string>;
23
+ /**
24
+ * Safely parses an OPF file with error handling
25
+ * @param opfPath Path to the OPF file
26
+ * @returns Cheerio document object for the OPF file
27
+ * @throws Error if OPF file cannot be read or parsed
28
+ */
29
+ export declare function parseOPF(opfPath: string): Promise<cheerio.CheerioAPI>;
30
+ /**
31
+ * Interface for TOC file information
32
+ */
33
+ export interface TOCFiles {
34
+ /** EPUB3 navigation file (modern readers) */
35
+ epub3Nav?: string;
36
+ /** EPUB2 NCX file (legacy/Kindle readers) */
37
+ epub2Ncx?: string;
38
+ }
39
+ /**
40
+ * Dynamically discovers TOC files from the OPF manifest
41
+ * Follows EPUB specification instead of hardcoding filenames
42
+ * @param epubDir Path to the extracted EPUB directory
43
+ * @returns Object containing paths to discovered TOC files
44
+ * @throws Error if OPF file cannot be read or parsed
45
+ */
46
+ export declare function getTOCFiles(epubDir: string): Promise<TOCFiles>;
47
+ /**
48
+ * Gets the EPUB3 navigation file path from OPF manifest
49
+ * @param epubDir Path to the extracted EPUB directory
50
+ * @returns Full path to EPUB3 navigation file, or null if not found
51
+ */
52
+ export declare function getEPUB3NavPath(epubDir: string): Promise<string | null>;
53
+ /**
54
+ * Gets the EPUB2 NCX file path from OPF manifest
55
+ * @param epubDir Path to the extracted EPUB directory
56
+ * @returns Full path to EPUB2 NCX file, or null if not found
57
+ */
58
+ export declare function getEPUB2NCXPath(epubDir: string): Promise<string | null>;
59
+ export interface ManifestResourceQuery {
60
+ /** OPF manifest `media-type` values to match (compared case-insensitively). */
61
+ mediaTypes: ReadonlySet<string>;
62
+ /** File extensions to match (lowercase, with dot), e.g. `.svg`. */
63
+ extensions: ReadonlySet<string>;
64
+ }
65
+ /**
66
+ * Discovers resources of given media-types/extensions in a **producer-agnostic**
67
+ * way — independent of folder name or case. The EPUB spec mandates no folder
68
+ * layout and treats paths as case-sensitive, so resources cannot be located by a
69
+ * hardcoded folder like `images/` or `fonts/` (e.g. Sigil/EDRLab use capitalized
70
+ * `Images/`/`Fonts/`).
71
+ *
72
+ * Primary path: enumerate the OPF manifest (the authoritative resource index),
73
+ * matching items by `media-type` or by href extension, resolving each href
74
+ * relative to the OPF. Fallback: recursive extension scan over the content
75
+ * directory if the manifest is unusable.
76
+ *
77
+ * @returns Absolute paths to matching resources that exist on disk.
78
+ */
79
+ export declare function collectManifestResources(epubDir: string, query: ManifestResourceQuery): Promise<string[]>;
@@ -0,0 +1,207 @@
1
+ import fs from "fs-extra";
2
+ import path from "node:path";
3
+ import * as cheerio from "cheerio";
4
+ import { resolvePathInside } from "./path-safety.js";
5
+ import { collectFiles } from "./files.js";
6
+ /**
7
+ * Dynamically reads the OPF file path from META-INF/container.xml
8
+ * This follows the EPUB specification instead of hardcoding filenames
9
+ * @param epubDir Path to the extracted EPUB directory
10
+ * @returns Full path to the OPF file
11
+ * @throws Error if container.xml is not found or OPF path cannot be determined
12
+ */
13
+ export async function getOPFPath(epubDir) {
14
+ const containerPath = path.join(epubDir, "META-INF", "container.xml");
15
+ if (!(await fs.pathExists(containerPath))) {
16
+ throw new Error(`Container file not found: ${containerPath}`);
17
+ }
18
+ try {
19
+ const content = await fs.readFile(containerPath, "utf-8");
20
+ const $ = cheerio.load(content, { xmlMode: true });
21
+ const rootfile = $("rootfile").first();
22
+ const fullPath = rootfile.attr("full-path");
23
+ if (!fullPath) {
24
+ throw new Error("No OPF path found in container.xml");
25
+ }
26
+ const opfPath = resolvePathInside(epubDir, epubDir, fullPath, "OPF rootfile path");
27
+ if (!(await fs.pathExists(opfPath))) {
28
+ throw new Error(`OPF file not found: ${opfPath}`);
29
+ }
30
+ return opfPath;
31
+ }
32
+ catch (error) {
33
+ throw new Error(`Failed to parse container.xml: ${error}`, { cause: error });
34
+ }
35
+ }
36
+ /**
37
+ * Determines the content directory used by the EPUB
38
+ * Checks for standard directory conventions: OPS (modern) and OEBPS (legacy)
39
+ * @param epubDir Path to the extracted EPUB directory
40
+ * @returns The content directory name (e.g., "OPS", "OEBPS") or empty string if content is in root
41
+ */
42
+ export async function getContentDir(epubDir) {
43
+ const opfPath = await getOPFPath(epubDir);
44
+ const opfDir = path.dirname(path.relative(epubDir, opfPath));
45
+ if (opfDir === "." || opfDir === "") {
46
+ return "";
47
+ }
48
+ return opfDir;
49
+ }
50
+ /**
51
+ * Gets the full path to the content directory
52
+ * @param epubDir Path to the extracted EPUB directory
53
+ * @returns Full path to the content directory
54
+ */
55
+ export async function getContentPath(epubDir) {
56
+ const contentDir = await getContentDir(epubDir);
57
+ return contentDir ? path.join(epubDir, contentDir) : epubDir;
58
+ }
59
+ /**
60
+ * Safely parses an OPF file with error handling
61
+ * @param opfPath Path to the OPF file
62
+ * @returns Cheerio document object for the OPF file
63
+ * @throws Error if OPF file cannot be read or parsed
64
+ */
65
+ export async function parseOPF(opfPath) {
66
+ if (!(await fs.pathExists(opfPath))) {
67
+ throw new Error(`OPF file not found: ${opfPath}`);
68
+ }
69
+ try {
70
+ const content = await fs.readFile(opfPath, "utf-8");
71
+ return cheerio.load(content, { xmlMode: true });
72
+ }
73
+ catch (error) {
74
+ throw new Error(`Failed to parse OPF file ${opfPath}: ${error}`, { cause: error });
75
+ }
76
+ }
77
+ /**
78
+ * Dynamically discovers TOC files from the OPF manifest
79
+ * Follows EPUB specification instead of hardcoding filenames
80
+ * @param epubDir Path to the extracted EPUB directory
81
+ * @returns Object containing paths to discovered TOC files
82
+ * @throws Error if OPF file cannot be read or parsed
83
+ */
84
+ export async function getTOCFiles(epubDir) {
85
+ try {
86
+ const opfPath = await getOPFPath(epubDir);
87
+ const $ = await parseOPF(opfPath);
88
+ const opfDir = path.dirname(opfPath);
89
+ const tocFiles = {};
90
+ // Find EPUB3 navigation file (properties="nav")
91
+ const navItem = $('item[properties*="nav"]').first();
92
+ if (navItem.length) {
93
+ const href = navItem.attr("href");
94
+ if (href) {
95
+ const navPath = resolvePathInside(epubDir, opfDir, href, "EPUB3 navigation href");
96
+ if (await fs.pathExists(navPath)) {
97
+ tocFiles.epub3Nav = navPath;
98
+ }
99
+ }
100
+ }
101
+ // Find EPUB2 NCX file (media-type="application/x-dtbncx+xml")
102
+ const ncxItem = $('item[media-type="application/x-dtbncx+xml"]').first();
103
+ if (ncxItem.length) {
104
+ const href = ncxItem.attr("href");
105
+ if (href) {
106
+ const ncxPath = resolvePathInside(epubDir, opfDir, href, "EPUB2 NCX href");
107
+ if (await fs.pathExists(ncxPath)) {
108
+ tocFiles.epub2Ncx = ncxPath;
109
+ }
110
+ }
111
+ }
112
+ return tocFiles;
113
+ }
114
+ catch (error) {
115
+ throw new Error(`Failed to discover TOC files: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
116
+ }
117
+ }
118
+ /**
119
+ * Gets the EPUB3 navigation file path from OPF manifest
120
+ * @param epubDir Path to the extracted EPUB directory
121
+ * @returns Full path to EPUB3 navigation file, or null if not found
122
+ */
123
+ export async function getEPUB3NavPath(epubDir) {
124
+ try {
125
+ const tocFiles = await getTOCFiles(epubDir);
126
+ return tocFiles.epub3Nav || null;
127
+ }
128
+ catch {
129
+ return null;
130
+ }
131
+ }
132
+ /**
133
+ * Gets the EPUB2 NCX file path from OPF manifest
134
+ * @param epubDir Path to the extracted EPUB directory
135
+ * @returns Full path to EPUB2 NCX file, or null if not found
136
+ */
137
+ export async function getEPUB2NCXPath(epubDir) {
138
+ try {
139
+ const tocFiles = await getTOCFiles(epubDir);
140
+ return tocFiles.epub2Ncx || null;
141
+ }
142
+ catch {
143
+ return null;
144
+ }
145
+ }
146
+ /**
147
+ * Discovers resources of given media-types/extensions in a **producer-agnostic**
148
+ * way — independent of folder name or case. The EPUB spec mandates no folder
149
+ * layout and treats paths as case-sensitive, so resources cannot be located by a
150
+ * hardcoded folder like `images/` or `fonts/` (e.g. Sigil/EDRLab use capitalized
151
+ * `Images/`/`Fonts/`).
152
+ *
153
+ * Primary path: enumerate the OPF manifest (the authoritative resource index),
154
+ * matching items by `media-type` or by href extension, resolving each href
155
+ * relative to the OPF. Fallback: recursive extension scan over the content
156
+ * directory if the manifest is unusable.
157
+ *
158
+ * @returns Absolute paths to matching resources that exist on disk.
159
+ */
160
+ export async function collectManifestResources(epubDir, query) {
161
+ // Primary: the OPF manifest, resolved relative to the OPF location.
162
+ try {
163
+ const opfPath = await getOPFPath(epubDir);
164
+ const $ = await parseOPF(opfPath);
165
+ const opfDir = path.dirname(opfPath);
166
+ const found = [];
167
+ const seen = new Set();
168
+ for (const el of $("manifest item").toArray()) {
169
+ const href = $(el).attr("href");
170
+ if (!href)
171
+ continue;
172
+ const mediaType = ($(el).attr("media-type") ?? "").trim().toLowerCase();
173
+ const hrefPath = href.split(/[?#]/, 1)[0] ?? href;
174
+ const ext = path.extname(hrefPath).toLowerCase();
175
+ if (!query.mediaTypes.has(mediaType) && !query.extensions.has(ext))
176
+ continue;
177
+ let resolved;
178
+ try {
179
+ resolved = resolvePathInside(epubDir, opfDir, href, "manifest item href");
180
+ }
181
+ catch {
182
+ continue;
183
+ }
184
+ if (seen.has(resolved))
185
+ continue;
186
+ seen.add(resolved);
187
+ if (await fs.pathExists(resolved))
188
+ found.push(resolved);
189
+ }
190
+ if (found.length > 0)
191
+ return found;
192
+ }
193
+ catch {
194
+ // Manifest unreadable → fall back to a recursive extension scan.
195
+ }
196
+ // Fallback: walk the whole content directory by extension (still folder/case
197
+ // agnostic, just without media-type awareness).
198
+ try {
199
+ const contentDir = await getContentPath(epubDir);
200
+ if (!(await fs.pathExists(contentDir)))
201
+ return [];
202
+ return await collectFiles(contentDir, (filePath) => query.extensions.has(path.extname(filePath).toLowerCase()));
203
+ }
204
+ catch {
205
+ return [];
206
+ }
207
+ }
@@ -0,0 +1,35 @@
1
+ export interface EpubCheckTotals {
2
+ fatals: number;
3
+ errors: number;
4
+ warnings: number;
5
+ infos: number;
6
+ }
7
+ export interface EpubCheckLocation {
8
+ path: string;
9
+ line?: number;
10
+ column?: number;
11
+ context?: string;
12
+ }
13
+ export interface EpubCheckMessage {
14
+ code: string;
15
+ severity: "FATAL" | "ERROR" | "WARNING" | "INFO" | "USAGE";
16
+ message: string;
17
+ locations: EpubCheckLocation[];
18
+ additionalLocations: number;
19
+ suggestion?: string;
20
+ }
21
+ export interface EpubCheckDiagnostics {
22
+ checkerVersion: string;
23
+ totals: EpubCheckTotals;
24
+ messages: EpubCheckMessage[];
25
+ }
26
+ export interface EpubCheckReport {
27
+ source: "json" | "text" | "unavailable";
28
+ exitCode: number | null;
29
+ checkerVersion?: string;
30
+ totals?: EpubCheckTotals;
31
+ messages: EpubCheckMessage[];
32
+ diagnosticsError?: string;
33
+ }
34
+ /** Normalize only documented diagnostics, without copying publication metadata. */
35
+ export declare function parseEpubCheckJson(input: string): EpubCheckDiagnostics;
@@ -0,0 +1,68 @@
1
+ function object(value, field) {
2
+ if (!value || typeof value !== "object" || Array.isArray(value))
3
+ throw new Error(`Invalid EPUBCheck JSON field: ${field}.`);
4
+ return value;
5
+ }
6
+ function string(value, field) {
7
+ if (typeof value !== "string")
8
+ throw new Error(`Invalid EPUBCheck JSON field: ${field}.`);
9
+ return value;
10
+ }
11
+ function count(value, field) {
12
+ if (!Number.isSafeInteger(value) || value < 0)
13
+ throw new Error(`Invalid EPUBCheck JSON count: ${field}.`);
14
+ return value;
15
+ }
16
+ function coordinate(value, field) {
17
+ if (value === undefined || value === null || value === -1 || value === 0)
18
+ return undefined;
19
+ const result = count(value, field);
20
+ return result;
21
+ }
22
+ /** Normalize only documented diagnostics, without copying publication metadata. */
23
+ export function parseEpubCheckJson(input) {
24
+ const report = object(JSON.parse(input), "report");
25
+ const checker = object(report.checker, "checker");
26
+ const totals = {
27
+ fatals: count(checker.nFatal, "checker.nFatal"),
28
+ errors: count(checker.nError, "checker.nError"),
29
+ warnings: count(checker.nWarning, "checker.nWarning"),
30
+ infos: count(checker.nUsage, "checker.nUsage"),
31
+ };
32
+ if (!Array.isArray(report.messages))
33
+ throw new Error("Invalid EPUBCheck JSON messages.");
34
+ const messages = report.messages.map((entry) => {
35
+ const message = object(entry, "message");
36
+ const severity = string(message.severity, "message.severity");
37
+ if (!["FATAL", "ERROR", "WARNING", "INFO", "USAGE"].includes(severity))
38
+ throw new Error("Invalid EPUBCheck JSON severity.");
39
+ if (!Array.isArray(message.locations))
40
+ throw new Error("Invalid EPUBCheck JSON locations.");
41
+ const locations = message.locations.map((entry) => {
42
+ const location = object(entry, "location");
43
+ return {
44
+ path: string(location.path, "location.path"),
45
+ line: coordinate(location.line, "location.line"),
46
+ column: coordinate(location.column, "location.column"),
47
+ ...(location.context == null
48
+ ? {}
49
+ : { context: string(location.context, "location.context") }),
50
+ };
51
+ });
52
+ return {
53
+ code: string(message.ID, "message.ID"),
54
+ severity: severity,
55
+ message: string(message.message, "message.message"),
56
+ locations,
57
+ additionalLocations: count(message.additionalLocations ?? 0, "message.additionalLocations"),
58
+ ...(message.suggestion == null
59
+ ? {}
60
+ : { suggestion: string(message.suggestion, "message.suggestion") }),
61
+ };
62
+ });
63
+ return {
64
+ checkerVersion: string(checker.checkerVersion, "checker.checkerVersion"),
65
+ totals,
66
+ messages,
67
+ };
68
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Compare and report original vs optimized file sizes
3
+ * @param originalPath Path to original file
4
+ * @param optimizedPath Path to optimized file
5
+ */
6
+ declare function reportFileSizeComparison(originalPath: string, optimizedPath: string): Promise<void>;
7
+ /**
8
+ * Format file size in human readable format
9
+ * @param bytes File size in bytes
10
+ * @returns Formatted file size
11
+ */
12
+ declare function formatFileSize(bytes: number): string;
13
+ export { formatFileSize, reportFileSizeComparison };
@@ -0,0 +1,40 @@
1
+ import { reportError, reportInfo } from "./diagnostics.js";
2
+ import fs from "fs-extra";
3
+ /**
4
+ * Compare and report original vs optimized file sizes
5
+ * @param originalPath Path to original file
6
+ * @param optimizedPath Path to optimized file
7
+ */
8
+ async function reportFileSizeComparison(originalPath, optimizedPath) {
9
+ try {
10
+ const originalSize = (await fs.stat(originalPath)).size;
11
+ const optimizedSize = (await fs.stat(optimizedPath)).size;
12
+ const reduction = ((originalSize - optimizedSize) / originalSize) * 100;
13
+ const bytesSaved = originalSize - optimizedSize;
14
+ reportInfo(`
15
+ 📊 File Size Comparison:
16
+ Original: ${formatFileSize(originalSize)}
17
+ Optimized: ${formatFileSize(optimizedSize)}
18
+ Reduction: ${reduction.toFixed(2)}% (${formatFileSize(bytesSaved)} saved)
19
+ `);
20
+ }
21
+ catch {
22
+ reportError("⚠️ Could not generate file size comparison");
23
+ }
24
+ }
25
+ /**
26
+ * Format file size in human readable format
27
+ * @param bytes File size in bytes
28
+ * @returns Formatted file size
29
+ */
30
+ function formatFileSize(bytes) {
31
+ const units = ["B", "KB", "MB", "GB"];
32
+ let size = bytes;
33
+ let unitIndex = 0;
34
+ while (size >= 1024 && unitIndex < units.length - 1) {
35
+ size /= 1024;
36
+ unitIndex++;
37
+ }
38
+ return `${size.toFixed(2)} ${units[unitIndex]}`;
39
+ }
40
+ export { formatFileSize, reportFileSizeComparison };
@@ -0,0 +1,14 @@
1
+ declare function collectFiles(dir: string, shouldInclude: (filePath: string) => boolean): Promise<string[]>;
2
+ declare function hasExtension(filePath: string, extensions: ReadonlySet<string>): boolean;
3
+ /**
4
+ * Default bound for CPU-bound per-file work (HTML/CSS/JS/SVG minification).
5
+ * Keeps parallel processing from oversubscribing cores on small machines.
6
+ */
7
+ export declare const DEFAULT_FILE_CONCURRENCY: number;
8
+ /**
9
+ * Runs `worker` over `items` with bounded concurrency. Rejects on the first
10
+ * worker rejection (fail-fast for callers that re-throw); workers that catch
11
+ * their own errors keep it lenient.
12
+ */
13
+ declare function forEachFileLimited<T>(items: readonly T[], worker: (item: T) => Promise<void>, concurrency?: number): Promise<void>;
14
+ export { collectFiles, hasExtension, forEachFileLimited };
@@ -0,0 +1,39 @@
1
+ import fs from "fs-extra";
2
+ import path from "node:path";
3
+ import os from "node:os";
4
+ import pLimit from "p-limit";
5
+ async function collectFiles(dir, shouldInclude) {
6
+ if (!(await fs.pathExists(dir))) {
7
+ return [];
8
+ }
9
+ const out = [];
10
+ const entries = await fs.readdir(dir, { withFileTypes: true });
11
+ await Promise.all(entries.map(async (entry) => {
12
+ const fullPath = path.join(dir, entry.name);
13
+ if (entry.isDirectory()) {
14
+ out.push(...(await collectFiles(fullPath, shouldInclude)));
15
+ }
16
+ else if (shouldInclude(fullPath)) {
17
+ out.push(fullPath);
18
+ }
19
+ }));
20
+ return out;
21
+ }
22
+ function hasExtension(filePath, extensions) {
23
+ return extensions.has(path.extname(filePath).toLowerCase());
24
+ }
25
+ /**
26
+ * Default bound for CPU-bound per-file work (HTML/CSS/JS/SVG minification).
27
+ * Keeps parallel processing from oversubscribing cores on small machines.
28
+ */
29
+ export const DEFAULT_FILE_CONCURRENCY = Math.max(1, Math.min(8, os.availableParallelism()));
30
+ /**
31
+ * Runs `worker` over `items` with bounded concurrency. Rejects on the first
32
+ * worker rejection (fail-fast for callers that re-throw); workers that catch
33
+ * their own errors keep it lenient.
34
+ */
35
+ async function forEachFileLimited(items, worker, concurrency = DEFAULT_FILE_CONCURRENCY) {
36
+ const limit = pLimit(concurrency);
37
+ await Promise.all(items.map((item) => limit(() => worker(item))));
38
+ }
39
+ export { collectFiles, hasExtension, forEachFileLimited };
@@ -0,0 +1,17 @@
1
+ import type { PipelineReport } from "./run-report.js";
2
+ export interface ResourceSnapshot {
3
+ bytes: number;
4
+ digest: string;
5
+ }
6
+ export interface ResourceChange {
7
+ path: string;
8
+ status: "unchanged" | "modified" | "added" | "removed";
9
+ beforeBytes?: number;
10
+ afterBytes?: number;
11
+ }
12
+ export declare function snapshotResources(root: string): Promise<Map<string, ResourceSnapshot>>;
13
+ export declare function compareResources(before: Map<string, ResourceSnapshot>, after: Map<string, ResourceSnapshot>): ResourceChange[];
14
+ export declare function escapeHtml(value: unknown): string;
15
+ export declare function htmlDocument(title: string, content: string): string;
16
+ export declare function renderHtmlReport(report: PipelineReport): string;
17
+ export declare function writeHtmlReport(report: PipelineReport, target: string): Promise<void>;