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.
- package/LICENSE +21 -0
- package/README.md +1434 -2
- package/dist/src/batch.d.ts +34 -0
- package/dist/src/batch.js +137 -0
- package/dist/src/cli.d.ts +7 -0
- package/dist/src/cli.js +275 -0
- package/dist/src/index.d.ts +23 -0
- package/dist/src/index.js +24 -0
- package/dist/src/optimization.d.ts +7 -0
- package/dist/src/optimization.js +207 -0
- package/dist/src/pipeline.d.ts +2 -0
- package/dist/src/pipeline.js +48 -0
- package/dist/src/processors/archive-processor.d.ts +26 -0
- package/dist/src/processors/archive-processor.js +170 -0
- package/dist/src/processors/epub-processor.d.ts +17 -0
- package/dist/src/processors/epub-processor.js +133 -0
- package/dist/src/processors/font-characters.d.ts +2 -0
- package/dist/src/processors/font-characters.js +227 -0
- package/dist/src/processors/font-engine.d.ts +6 -0
- package/dist/src/processors/font-engine.js +101 -0
- package/dist/src/processors/font-limits.d.ts +3 -0
- package/dist/src/processors/font-limits.js +3 -0
- package/dist/src/processors/font-processor.d.ts +4 -0
- package/dist/src/processors/font-processor.js +121 -0
- package/dist/src/processors/font-runner.d.ts +8 -0
- package/dist/src/processors/font-runner.js +94 -0
- package/dist/src/processors/font-worker.d.ts +1 -0
- package/dist/src/processors/font-worker.js +12 -0
- package/dist/src/processors/html-processor.d.ts +22 -0
- package/dist/src/processors/html-processor.js +190 -0
- package/dist/src/processors/image-converter.d.ts +14 -0
- package/dist/src/processors/image-converter.js +481 -0
- package/dist/src/processors/image-processor.d.ts +24 -0
- package/dist/src/processors/image-processor.js +165 -0
- package/dist/src/processors/js-processor.d.ts +7 -0
- package/dist/src/processors/js-processor.js +59 -0
- package/dist/src/processors/lazy-img.d.ts +5 -0
- package/dist/src/processors/lazy-img.js +48 -0
- package/dist/src/processors/svg-optimizer.d.ts +5 -0
- package/dist/src/processors/svg-optimizer.js +49 -0
- package/dist/src/scripts/create-epub.d.ts +2 -0
- package/dist/src/scripts/create-epub.js +29 -0
- package/dist/src/scripts/fix/fix-span-tags.d.ts +2 -0
- package/dist/src/scripts/fix/fix-span-tags.js +36 -0
- package/dist/src/scripts/fix/fix-xml.d.ts +3 -0
- package/dist/src/scripts/fix/fix-xml.js +59 -0
- package/dist/src/scripts/fix/index.d.ts +5 -0
- package/dist/src/scripts/fix/index.js +20 -0
- package/dist/src/scripts/fix/remove-empty-styles.d.ts +10 -0
- package/dist/src/scripts/fix/remove-empty-styles.js +53 -0
- package/dist/src/scripts/fix/xhtml-files.d.ts +2 -0
- package/dist/src/scripts/fix/xhtml-files.js +34 -0
- package/dist/src/scripts/ops/add-chapter-sections-to-toc.d.ts +5 -0
- package/dist/src/scripts/ops/add-chapter-sections-to-toc.js +242 -0
- package/dist/src/scripts/ops/add-cover-image-property.d.ts +2 -0
- package/dist/src/scripts/ops/add-cover-image-property.js +27 -0
- package/dist/src/scripts/ops/ncx.d.ts +6 -0
- package/dist/src/scripts/ops/ncx.js +19 -0
- package/dist/src/scripts/ops/update-cover-linear.d.ts +11 -0
- package/dist/src/scripts/ops/update-cover-linear.js +45 -0
- package/dist/src/scripts/ops/update-structure.d.ts +5 -0
- package/dist/src/scripts/ops/update-structure.js +22 -0
- package/dist/src/scripts/ops/update-summary-page.d.ts +2 -0
- package/dist/src/scripts/ops/update-summary-page.js +53 -0
- package/dist/src/scripts/ops/update-toc-with-cover.d.ts +2 -0
- package/dist/src/scripts/ops/update-toc-with-cover.js +140 -0
- package/dist/src/scripts/utils.d.ts +53 -0
- package/dist/src/scripts/utils.js +92 -0
- package/dist/src/scripts/validate-epub.d.ts +12 -0
- package/dist/src/scripts/validate-epub.js +185 -0
- package/dist/src/storage.d.ts +30 -0
- package/dist/src/storage.js +286 -0
- package/dist/src/types.d.ts +51 -0
- package/dist/src/types.js +1 -0
- package/dist/src/utils/author-workflow-config.d.ts +17 -0
- package/dist/src/utils/author-workflow-config.js +95 -0
- package/dist/src/utils/buffered-process.d.ts +8 -0
- package/dist/src/utils/buffered-process.js +36 -0
- package/dist/src/utils/cli-config.d.ts +4 -0
- package/dist/src/utils/cli-config.js +84 -0
- package/dist/src/utils/config.d.ts +49 -0
- package/dist/src/utils/config.js +58 -0
- package/dist/src/utils/diagnostics.d.ts +11 -0
- package/dist/src/utils/diagnostics.js +38 -0
- package/dist/src/utils/epub-doctor.d.ts +78 -0
- package/dist/src/utils/epub-doctor.js +301 -0
- package/dist/src/utils/epub-features.d.ts +20 -0
- package/dist/src/utils/epub-features.js +105 -0
- package/dist/src/utils/epub-integrity.d.ts +25 -0
- package/dist/src/utils/epub-integrity.js +197 -0
- package/dist/src/utils/epub-text.d.ts +13 -0
- package/dist/src/utils/epub-text.js +106 -0
- package/dist/src/utils/epub-utils.d.ts +79 -0
- package/dist/src/utils/epub-utils.js +207 -0
- package/dist/src/utils/epubcheck-report.d.ts +35 -0
- package/dist/src/utils/epubcheck-report.js +68 -0
- package/dist/src/utils/file-size.d.ts +13 -0
- package/dist/src/utils/file-size.js +40 -0
- package/dist/src/utils/files.d.ts +14 -0
- package/dist/src/utils/files.js +39 -0
- package/dist/src/utils/html-report.d.ts +17 -0
- package/dist/src/utils/html-report.js +95 -0
- package/dist/src/utils/i18n.d.ts +5 -0
- package/dist/src/utils/i18n.js +9 -0
- package/dist/src/utils/output-transaction.d.ts +8 -0
- package/dist/src/utils/output-transaction.js +146 -0
- package/dist/src/utils/package-root.d.ts +2 -0
- package/dist/src/utils/package-root.js +15 -0
- package/dist/src/utils/path-safety.d.ts +2 -0
- package/dist/src/utils/path-safety.js +30 -0
- package/dist/src/utils/pipeline-options.d.ts +34 -0
- package/dist/src/utils/pipeline-options.js +49 -0
- package/dist/src/utils/png-animation.d.ts +7 -0
- package/dist/src/utils/png-animation.js +44 -0
- package/dist/src/utils/run-report.d.ts +49 -0
- package/dist/src/utils/run-report.js +71 -0
- package/dist/src/utils/temp-dir.d.ts +11 -0
- package/dist/src/utils/temp-dir.js +80 -0
- package/dist/src/utils/watch-lock.d.ts +8 -0
- package/dist/src/utils/watch-lock.js +100 -0
- package/dist/src/utils/watch-summary.d.ts +13 -0
- package/dist/src/utils/watch-summary.js +130 -0
- package/dist/src/utils/xhtml-structure.d.ts +7 -0
- package/dist/src/utils/xhtml-structure.js +53 -0
- package/dist/src/utils/xhtml.d.ts +27 -0
- package/dist/src/utils/xhtml.js +205 -0
- package/dist/src/utils/xml-dtd.d.ts +6 -0
- package/dist/src/utils/xml-dtd.js +133 -0
- package/dist/src/watch.d.ts +21 -0
- package/dist/src/watch.js +328 -0
- package/package.json +99 -3
- 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>;
|