epub-optimizer 0.0.0-stage → 3.16.1
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,301 @@
|
|
|
1
|
+
import { reportInfo } from "./diagnostics.js";
|
|
2
|
+
import fs from "fs-extra";
|
|
3
|
+
import os from "node:os";
|
|
4
|
+
import path from "node:path";
|
|
5
|
+
import sharp from "sharp";
|
|
6
|
+
import unzipper from "unzipper";
|
|
7
|
+
import { detectEpubFeatures } from "./epub-features.js";
|
|
8
|
+
import { findInternalDtdSubsets } from "./xml-dtd.js";
|
|
9
|
+
import * as cheerio from "cheerio";
|
|
10
|
+
import { extractEPUB } from "../processors/archive-processor.js";
|
|
11
|
+
import { collectEpubContentMetrics } from "./epub-integrity.js";
|
|
12
|
+
import { getContentPath, getOPFPath, getTOCFiles, parseOPF } from "./epub-utils.js";
|
|
13
|
+
import { resolvePathInside } from "./path-safety.js";
|
|
14
|
+
function toPosixPath(filePath) {
|
|
15
|
+
return filePath.split(path.sep).join("/");
|
|
16
|
+
}
|
|
17
|
+
function formatBytes(bytes) {
|
|
18
|
+
if (bytes === 0)
|
|
19
|
+
return "0 B";
|
|
20
|
+
const units = ["B", "KB", "MB", "GB"];
|
|
21
|
+
let value = bytes;
|
|
22
|
+
let unitIndex = 0;
|
|
23
|
+
while (value >= 1024 && unitIndex < units.length - 1) {
|
|
24
|
+
value /= 1024;
|
|
25
|
+
unitIndex++;
|
|
26
|
+
}
|
|
27
|
+
return `${value.toFixed(value >= 10 || unitIndex === 0 ? 0 : 1)} ${units[unitIndex]}`;
|
|
28
|
+
}
|
|
29
|
+
function basenameFromHref(href) {
|
|
30
|
+
const pathPart = href.split(/[?#]/, 1)[0] ?? "";
|
|
31
|
+
try {
|
|
32
|
+
return path.posix.basename(decodeURI(pathPart));
|
|
33
|
+
}
|
|
34
|
+
catch {
|
|
35
|
+
return path.posix.basename(pathPart);
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
function addRisk(risks, level, code, message) {
|
|
39
|
+
risks.push({ level, code, message });
|
|
40
|
+
}
|
|
41
|
+
async function readImageDetails(item) {
|
|
42
|
+
if (!item.filePath || !(await fs.pathExists(item.filePath))) {
|
|
43
|
+
return {
|
|
44
|
+
href: item.href,
|
|
45
|
+
mediaType: item.mediaType,
|
|
46
|
+
bytes: 0,
|
|
47
|
+
exists: false,
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
const stats = await fs.stat(item.filePath);
|
|
51
|
+
const image = {
|
|
52
|
+
href: item.href,
|
|
53
|
+
mediaType: item.mediaType,
|
|
54
|
+
bytes: stats.size,
|
|
55
|
+
exists: true,
|
|
56
|
+
};
|
|
57
|
+
if (item.mediaType !== "image/svg+xml") {
|
|
58
|
+
try {
|
|
59
|
+
const metadata = await sharp(item.filePath).metadata();
|
|
60
|
+
image.width = metadata.width;
|
|
61
|
+
image.height = metadata.height;
|
|
62
|
+
image.hasAlpha = metadata.hasAlpha;
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
// Keep the byte-level report even when image metadata cannot be decoded.
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
return image;
|
|
69
|
+
}
|
|
70
|
+
async function collectManifestImages(epubDir, opfPath, $opf, archiveEntries) {
|
|
71
|
+
const opfDir = path.dirname(opfPath);
|
|
72
|
+
const items = [];
|
|
73
|
+
for (const element of $opf("manifest item").toArray()) {
|
|
74
|
+
const item = $opf(element);
|
|
75
|
+
const mediaType = item.attr("media-type") ?? "";
|
|
76
|
+
const href = item.attr("href") ?? "";
|
|
77
|
+
if (!href || !mediaType.startsWith("image/"))
|
|
78
|
+
continue;
|
|
79
|
+
try {
|
|
80
|
+
items.push({
|
|
81
|
+
href,
|
|
82
|
+
mediaType,
|
|
83
|
+
filePath: resolvePathInside(epubDir, opfDir, href, "image manifest href"),
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
catch {
|
|
87
|
+
items.push({ href, mediaType });
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
const images = await Promise.all(items.map((item) => readImageDetails(item)));
|
|
91
|
+
const imagePaths = new Set(items.flatMap((item, index) => item.filePath && images[index]?.exists
|
|
92
|
+
? [toPosixPath(path.relative(epubDir, item.filePath))]
|
|
93
|
+
: []));
|
|
94
|
+
const sizes = archiveEntries ? [...imagePaths].map((file) => archiveEntries.get(file)) : [];
|
|
95
|
+
const compressedBytes = archiveEntries && sizes.every((size) => size !== undefined)
|
|
96
|
+
? sizes.reduce((sum, size) => sum + (size ?? 0), 0)
|
|
97
|
+
: undefined;
|
|
98
|
+
return { images, compressedBytes };
|
|
99
|
+
}
|
|
100
|
+
function summarizeImages(images, archiveBytes, compressedBytes) {
|
|
101
|
+
const byMediaType = {};
|
|
102
|
+
const basenameGroups = new Map();
|
|
103
|
+
const totalBytes = images.reduce((sum, image) => sum + image.bytes, 0);
|
|
104
|
+
for (const image of images) {
|
|
105
|
+
const typeSummary = byMediaType[image.mediaType] ?? { count: 0, bytes: 0 };
|
|
106
|
+
typeSummary.count++;
|
|
107
|
+
typeSummary.bytes += image.bytes;
|
|
108
|
+
byMediaType[image.mediaType] = typeSummary;
|
|
109
|
+
const basename = basenameFromHref(image.href);
|
|
110
|
+
basenameGroups.set(basename, [...(basenameGroups.get(basename) ?? []), image.href]);
|
|
111
|
+
}
|
|
112
|
+
return {
|
|
113
|
+
count: images.length,
|
|
114
|
+
totalBytes,
|
|
115
|
+
compressedBytes: compressedBytes ?? null,
|
|
116
|
+
archivePercent: compressedBytes !== undefined && archiveBytes > 0 && compressedBytes <= archiveBytes
|
|
117
|
+
? (compressedBytes / archiveBytes) * 100
|
|
118
|
+
: null,
|
|
119
|
+
byMediaType,
|
|
120
|
+
largest: [...images].sort((a, b) => b.bytes - a.bytes).slice(0, 5),
|
|
121
|
+
duplicateBasenames: Array.from(basenameGroups.entries())
|
|
122
|
+
.filter(([, hrefs]) => hrefs.length > 1)
|
|
123
|
+
.map(([basename, hrefs]) => ({ basename, hrefs })),
|
|
124
|
+
largeRasterImages: images.filter((image) => image.mediaType !== "image/svg+xml" &&
|
|
125
|
+
((image.width ?? 0) > 1600 || (image.height ?? 0) > 1600)),
|
|
126
|
+
opaquePngCandidates: images.filter((image) => image.mediaType === "image/png" && image.bytes >= 200 * 1024 && image.hasAlpha === false),
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
function buildRisks(report) {
|
|
130
|
+
const risks = [];
|
|
131
|
+
if (report.references.missing > 0) {
|
|
132
|
+
addRisk(risks, "warning", "missing-references", `${report.references.missing} internal reference(s) are missing.`);
|
|
133
|
+
}
|
|
134
|
+
if (!report.navigation.hasEpub3Nav) {
|
|
135
|
+
addRisk(risks, "warning", "missing-epub3-nav", "No EPUB3 navigation document was found.");
|
|
136
|
+
}
|
|
137
|
+
if (!report.navigation.hasNcx) {
|
|
138
|
+
addRisk(risks, "info", "missing-ncx", "No legacy NCX navigation file was found; this is acceptable for EPUB3-only books.");
|
|
139
|
+
}
|
|
140
|
+
if (report.images.archivePercent !== null && report.images.archivePercent >= 60) {
|
|
141
|
+
addRisk(risks, "info", "image-heavy", `Manifest images account for ${report.images.archivePercent.toFixed(1)}% of the archive.`);
|
|
142
|
+
}
|
|
143
|
+
if (report.images.largeRasterImages.length > 0) {
|
|
144
|
+
addRisk(risks, "info", "large-raster-images", `${report.images.largeRasterImages.length} raster image(s) exceed 1600 px on at least one axis.`);
|
|
145
|
+
}
|
|
146
|
+
if (report.images.opaquePngCandidates.length > 0) {
|
|
147
|
+
addRisk(risks, "info", "png-conversion-candidates", `${report.images.opaquePngCandidates.length} large opaque PNG image(s) may benefit from JPEG conversion.`);
|
|
148
|
+
}
|
|
149
|
+
if (report.images.duplicateBasenames.length > 0) {
|
|
150
|
+
addRisk(risks, "info", "duplicate-image-basenames", `${report.images.duplicateBasenames.length} image basename(s) appear in multiple directories.`);
|
|
151
|
+
}
|
|
152
|
+
return risks;
|
|
153
|
+
}
|
|
154
|
+
export async function inspectExtractedEpub(epubDir, options) {
|
|
155
|
+
const internalDtdFiles = await findInternalDtdSubsets(epubDir);
|
|
156
|
+
const blockers = [];
|
|
157
|
+
if (internalDtdFiles.length > 0) {
|
|
158
|
+
blockers.push({
|
|
159
|
+
level: "error",
|
|
160
|
+
code: "internal-dtd",
|
|
161
|
+
message: `Internal DTD subsets prevent optimization: ${internalDtdFiles.map((file) => JSON.stringify(file)).join(", ")}. Replace internal declarations with literal text or numeric references before retrying.`,
|
|
162
|
+
});
|
|
163
|
+
}
|
|
164
|
+
else {
|
|
165
|
+
// Never parse an OPF or other XML while its DTD semantics are unsupported.
|
|
166
|
+
const features = await detectEpubFeatures(epubDir);
|
|
167
|
+
if (features.encryptionKind === "drm") {
|
|
168
|
+
blockers.push({
|
|
169
|
+
level: "error",
|
|
170
|
+
code: "drm",
|
|
171
|
+
message: "Encrypted/DRM-protected resources prevent optimization (META-INF/encryption.xml).",
|
|
172
|
+
});
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
if (blockers.length > 0) {
|
|
176
|
+
return {
|
|
177
|
+
input: options.input,
|
|
178
|
+
archiveBytes: options.archiveBytes,
|
|
179
|
+
analysisComplete: false,
|
|
180
|
+
optimization: { blocked: true, blockers },
|
|
181
|
+
risks: blockers,
|
|
182
|
+
};
|
|
183
|
+
}
|
|
184
|
+
const opfPath = await getOPFPath(epubDir);
|
|
185
|
+
const $opf = await parseOPF(opfPath);
|
|
186
|
+
const contentPath = await getContentPath(epubDir);
|
|
187
|
+
const tocFiles = await getTOCFiles(epubDir);
|
|
188
|
+
const content = await collectEpubContentMetrics(epubDir);
|
|
189
|
+
const manifestImages = await collectManifestImages(epubDir, opfPath, $opf, options.archiveEntries);
|
|
190
|
+
const images = summarizeImages(manifestImages.images, options.archiveBytes, manifestImages.compressedBytes);
|
|
191
|
+
const reportWithoutRisks = {
|
|
192
|
+
analysisComplete: true,
|
|
193
|
+
optimization: { blocked: false, blockers: [] },
|
|
194
|
+
input: options.input,
|
|
195
|
+
archiveBytes: options.archiveBytes,
|
|
196
|
+
opf: {
|
|
197
|
+
path: toPosixPath(path.relative(epubDir, opfPath)),
|
|
198
|
+
version: $opf("package").first().attr("version"),
|
|
199
|
+
manifestItems: content.manifestItems,
|
|
200
|
+
spineItems: content.spineItems,
|
|
201
|
+
contentDirectory: toPosixPath(path.relative(epubDir, contentPath)) || ".",
|
|
202
|
+
},
|
|
203
|
+
navigation: {
|
|
204
|
+
hasEpub3Nav: tocFiles.epub3Nav !== undefined,
|
|
205
|
+
hasNcx: tocFiles.epub2Ncx !== undefined,
|
|
206
|
+
entries: content.navigationEntries,
|
|
207
|
+
},
|
|
208
|
+
references: {
|
|
209
|
+
internal: content.internalReferences,
|
|
210
|
+
missing: content.missingReferences,
|
|
211
|
+
missingTargets: content.missingReferenceTargets,
|
|
212
|
+
},
|
|
213
|
+
images,
|
|
214
|
+
content,
|
|
215
|
+
};
|
|
216
|
+
return {
|
|
217
|
+
...reportWithoutRisks,
|
|
218
|
+
risks: buildRisks(reportWithoutRisks),
|
|
219
|
+
};
|
|
220
|
+
}
|
|
221
|
+
export function printDoctorReport(report) {
|
|
222
|
+
reportInfo("\n=== EPUB Doctor ===");
|
|
223
|
+
reportInfo(`Input: ${report.input}`);
|
|
224
|
+
reportInfo(`Archive: ${formatBytes(report.archiveBytes)}`);
|
|
225
|
+
if (!report.analysisComplete) {
|
|
226
|
+
reportInfo("Optimization is blocked:");
|
|
227
|
+
for (const blocker of report.optimization.blockers)
|
|
228
|
+
reportInfo(`- ${blocker.message}`);
|
|
229
|
+
reportInfo("Detailed content metrics are unavailable for this unsupported EPUB.\n");
|
|
230
|
+
return;
|
|
231
|
+
}
|
|
232
|
+
reportInfo(`OPF: ${report.opf.path} (${report.opf.version ? `EPUB ${report.opf.version}` : "version unknown"}), manifest ${report.opf.manifestItems}, spine ${report.opf.spineItems}`);
|
|
233
|
+
reportInfo(`Navigation: EPUB3 nav ${report.navigation.hasEpub3Nav ? "yes" : "no"}, NCX ${report.navigation.hasNcx ? "yes" : "no"}, entries ${report.navigation.entries}`);
|
|
234
|
+
reportInfo(`Internal refs: ${report.references.internal} checked, ${report.references.missing} missing`);
|
|
235
|
+
const compressedShare = report.images.archivePercent === null
|
|
236
|
+
? "compressed archive share unavailable"
|
|
237
|
+
: `${report.images.archivePercent.toFixed(1)}% of compressed archive`;
|
|
238
|
+
reportInfo(`Images: ${report.images.count} manifest item(s), ${formatBytes(report.images.totalBytes)} uncompressed (${compressedShare})`);
|
|
239
|
+
if (report.images.largest.length > 0) {
|
|
240
|
+
reportInfo("Largest images:");
|
|
241
|
+
for (const image of report.images.largest) {
|
|
242
|
+
const dimensions = image.width && image.height ? `, ${image.width}x${image.height}` : "";
|
|
243
|
+
reportInfo(`- ${image.href}: ${formatBytes(image.bytes)}${dimensions}`);
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
if (report.references.missingTargets.length > 0) {
|
|
247
|
+
reportInfo("Missing references:");
|
|
248
|
+
for (const reference of report.references.missingTargets.slice(0, 10)) {
|
|
249
|
+
reportInfo(`- ${reference}`);
|
|
250
|
+
}
|
|
251
|
+
if (report.references.missingTargets.length > 10) {
|
|
252
|
+
reportInfo(`- ... ${report.references.missingTargets.length - 10} more`);
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
reportInfo("Optimization risks:");
|
|
256
|
+
if (report.risks.length === 0) {
|
|
257
|
+
reportInfo("- No obvious optimization risks found.");
|
|
258
|
+
}
|
|
259
|
+
else {
|
|
260
|
+
for (const risk of report.risks) {
|
|
261
|
+
reportInfo(`- [${risk.level}] ${risk.message}`);
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
reportInfo("");
|
|
265
|
+
}
|
|
266
|
+
export async function runDoctor(options) {
|
|
267
|
+
if (!(await fs.pathExists(options.input))) {
|
|
268
|
+
throw new Error(`Input file not found: ${options.input}`);
|
|
269
|
+
}
|
|
270
|
+
if (!(await fs.stat(options.input)).isFile()) {
|
|
271
|
+
throw new Error(`Input path must point to a regular file: ${options.input}`);
|
|
272
|
+
}
|
|
273
|
+
const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "epub-optimizer-doctor-"));
|
|
274
|
+
try {
|
|
275
|
+
const extractedDir = path.join(tempDir, "content");
|
|
276
|
+
await extractEPUB(options.input, extractedDir);
|
|
277
|
+
const archive = await unzipper.Open.file(options.input);
|
|
278
|
+
const archiveEntries = new Map(archive.files
|
|
279
|
+
.filter((entry) => entry.type !== "Directory")
|
|
280
|
+
.map((entry) => [
|
|
281
|
+
toPosixPath(path.relative(extractedDir, path.resolve(extractedDir, entry.path.replace(/\\/g, "/")))),
|
|
282
|
+
entry.compressedSize,
|
|
283
|
+
]));
|
|
284
|
+
const report = await inspectExtractedEpub(extractedDir, {
|
|
285
|
+
archiveEntries,
|
|
286
|
+
input: options.input,
|
|
287
|
+
archiveBytes: (await fs.stat(options.input)).size,
|
|
288
|
+
});
|
|
289
|
+
printDoctorReport(report);
|
|
290
|
+
if (options.reportJson) {
|
|
291
|
+
const absolutePath = path.resolve(options.reportJson);
|
|
292
|
+
await fs.ensureDir(path.dirname(absolutePath));
|
|
293
|
+
await fs.writeJson(absolutePath, report, { spaces: 2 });
|
|
294
|
+
reportInfo(`Wrote JSON report: ${absolutePath}`);
|
|
295
|
+
}
|
|
296
|
+
return report;
|
|
297
|
+
}
|
|
298
|
+
finally {
|
|
299
|
+
await fs.remove(tempDir);
|
|
300
|
+
}
|
|
301
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* - `none`: no `META-INF/encryption.xml`.
|
|
3
|
+
* - `obfuscation`: every encrypted entry uses a known font-obfuscation
|
|
4
|
+
* algorithm — safe to optimize everything else, leave the fonts untouched.
|
|
5
|
+
* - `drm`: real content encryption (or an unrecognized scheme) — refuse, since
|
|
6
|
+
* re-encoding/repacking would corrupt protected resources.
|
|
7
|
+
*/
|
|
8
|
+
export type EncryptionKind = "none" | "obfuscation" | "drm";
|
|
9
|
+
export interface EpubFeatures {
|
|
10
|
+
encryptionKind: EncryptionKind;
|
|
11
|
+
/** Resource URIs listed in encryption.xml (decoded, as written). */
|
|
12
|
+
encryptedHrefs: string[];
|
|
13
|
+
/** True when the package declares a pre-paginated (fixed-layout) rendition. */
|
|
14
|
+
fixedLayout: boolean;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Inspects an extracted EPUB for shapes that need special handling before any
|
|
18
|
+
* optimization runs: encrypted/DRM/obfuscated resources and fixed-layout.
|
|
19
|
+
*/
|
|
20
|
+
export declare function detectEpubFeatures(epubDir: string): Promise<EpubFeatures>;
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
import fs from "fs-extra";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
import * as cheerio from "cheerio";
|
|
4
|
+
import { getOPFPath, parseOPF } from "./epub-utils.js";
|
|
5
|
+
/**
|
|
6
|
+
* XML Encryption algorithm URIs used for EPUB *font obfuscation* (not DRM).
|
|
7
|
+
* These scramble embedded fonts so they only render inside their own book; the
|
|
8
|
+
* rest of the publication is plain and safe to optimize.
|
|
9
|
+
*/
|
|
10
|
+
const FONT_OBFUSCATION_ALGORITHMS = new Set([
|
|
11
|
+
"http://www.idpf.org/2008/embedding", // IDPF / EPUB font obfuscation
|
|
12
|
+
"http://ns.adobe.com/pdf/enc#RC", // Adobe font obfuscation
|
|
13
|
+
]);
|
|
14
|
+
const FONT_EXTENSIONS = new Set([".ttf", ".otf", ".woff", ".woff2", ".ttc", ".dfont"]);
|
|
15
|
+
function isFontHref(href) {
|
|
16
|
+
const clean = href.split(/[?#]/, 1)[0] ?? href;
|
|
17
|
+
const dot = clean.lastIndexOf(".");
|
|
18
|
+
return dot >= 0 && FONT_EXTENSIONS.has(clean.slice(dot).toLowerCase());
|
|
19
|
+
}
|
|
20
|
+
function safeDecodeURIComponent(value) {
|
|
21
|
+
try {
|
|
22
|
+
return decodeURIComponent(value);
|
|
23
|
+
}
|
|
24
|
+
catch {
|
|
25
|
+
return value;
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
/** Reads `META-INF/encryption.xml` (if any) and classifies it. */
|
|
29
|
+
async function detectEncryption(epubDir) {
|
|
30
|
+
const encPath = path.join(epubDir, "META-INF", "encryption.xml");
|
|
31
|
+
if (!(await fs.pathExists(encPath))) {
|
|
32
|
+
return { kind: "none", hrefs: [] };
|
|
33
|
+
}
|
|
34
|
+
let $;
|
|
35
|
+
try {
|
|
36
|
+
const content = await fs.readFile(encPath, "utf-8");
|
|
37
|
+
$ = cheerio.load(content, { xmlMode: true });
|
|
38
|
+
}
|
|
39
|
+
catch {
|
|
40
|
+
// Present but unreadable/malformed → treat as encrypted and refuse.
|
|
41
|
+
return { kind: "drm", hrefs: [] };
|
|
42
|
+
}
|
|
43
|
+
// Attribute selectors are prefix-agnostic (`enc:EncryptionMethod` and
|
|
44
|
+
// `EncryptionMethod` both carry an `Algorithm` attribute), so we avoid the
|
|
45
|
+
// XML-namespace-prefix matching problem entirely.
|
|
46
|
+
const algorithms = [];
|
|
47
|
+
$("[Algorithm]").each((_, el) => {
|
|
48
|
+
const algorithm = $(el).attr("Algorithm");
|
|
49
|
+
if (algorithm)
|
|
50
|
+
algorithms.push(algorithm);
|
|
51
|
+
});
|
|
52
|
+
const hrefs = [];
|
|
53
|
+
$("[URI]").each((_, el) => {
|
|
54
|
+
const uri = $(el).attr("URI");
|
|
55
|
+
if (uri)
|
|
56
|
+
hrefs.push(safeDecodeURIComponent(uri));
|
|
57
|
+
});
|
|
58
|
+
// encryption.xml exists but we couldn't read any algorithm or resource → be
|
|
59
|
+
// conservative and treat it as DRM rather than risk corrupting content.
|
|
60
|
+
if (algorithms.length === 0 && hrefs.length === 0) {
|
|
61
|
+
return { kind: "drm", hrefs };
|
|
62
|
+
}
|
|
63
|
+
// Font obfuscation is safe to skip-and-optimize-the-rest. We classify it as
|
|
64
|
+
// obfuscation when every encrypted entry is either a known obfuscation
|
|
65
|
+
// algorithm OR a font file (covers producers like Pages that encrypt only the
|
|
66
|
+
// embedded fonts). Anything else encrypted means real content DRM → refuse.
|
|
67
|
+
const allObfuscationAlgorithms = algorithms.length > 0 && algorithms.every((a) => FONT_OBFUSCATION_ALGORITHMS.has(a));
|
|
68
|
+
const allEncryptedAreFonts = hrefs.length > 0 && hrefs.every(isFontHref);
|
|
69
|
+
if (allObfuscationAlgorithms || allEncryptedAreFonts) {
|
|
70
|
+
return { kind: "obfuscation", hrefs };
|
|
71
|
+
}
|
|
72
|
+
return { kind: "drm", hrefs };
|
|
73
|
+
}
|
|
74
|
+
/** Reads the OPF and detects a pre-paginated (fixed-layout) rendition. */
|
|
75
|
+
async function detectFixedLayout(epubDir) {
|
|
76
|
+
try {
|
|
77
|
+
const opfPath = await getOPFPath(epubDir);
|
|
78
|
+
const $ = await parseOPF(opfPath);
|
|
79
|
+
// EPUB3 global rendition: <meta property="rendition:layout">pre-paginated</meta>
|
|
80
|
+
const globalLayout = $('meta[property="rendition:layout"]').first().text().trim().toLowerCase();
|
|
81
|
+
if (globalLayout === "pre-paginated") {
|
|
82
|
+
return true;
|
|
83
|
+
}
|
|
84
|
+
// Per-spine override: <itemref properties="rendition:layout-pre-paginated"/>
|
|
85
|
+
return $('itemref[properties~="rendition:layout-pre-paginated"]').length > 0;
|
|
86
|
+
}
|
|
87
|
+
catch {
|
|
88
|
+
return false;
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Inspects an extracted EPUB for shapes that need special handling before any
|
|
93
|
+
* optimization runs: encrypted/DRM/obfuscated resources and fixed-layout.
|
|
94
|
+
*/
|
|
95
|
+
export async function detectEpubFeatures(epubDir) {
|
|
96
|
+
const [encryption, fixedLayout] = await Promise.all([
|
|
97
|
+
detectEncryption(epubDir),
|
|
98
|
+
detectFixedLayout(epubDir),
|
|
99
|
+
]);
|
|
100
|
+
return {
|
|
101
|
+
encryptionKind: encryption.kind,
|
|
102
|
+
encryptedHrefs: encryption.hrefs,
|
|
103
|
+
fixedLayout,
|
|
104
|
+
};
|
|
105
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
export interface EpubContentMetrics {
|
|
2
|
+
manifestItems: number;
|
|
3
|
+
spineItems: number;
|
|
4
|
+
contentDocuments: number;
|
|
5
|
+
images: number;
|
|
6
|
+
navigationEntries: number;
|
|
7
|
+
internalReferences: number;
|
|
8
|
+
missingReferences: number;
|
|
9
|
+
missingReferenceTargets: string[];
|
|
10
|
+
}
|
|
11
|
+
export interface IntegrityCheck {
|
|
12
|
+
name: "manifestItems" | "spineItems" | "contentDocuments" | "images" | "navigationEntries";
|
|
13
|
+
before: number;
|
|
14
|
+
after: number;
|
|
15
|
+
passed: boolean;
|
|
16
|
+
}
|
|
17
|
+
export interface EpubIntegrityComparison {
|
|
18
|
+
valid: boolean;
|
|
19
|
+
checks: IntegrityCheck[];
|
|
20
|
+
newMissingReferences: string[];
|
|
21
|
+
issues: string[];
|
|
22
|
+
}
|
|
23
|
+
export declare function collectEpubContentMetrics(epubDir: string): Promise<EpubContentMetrics>;
|
|
24
|
+
export declare function compareEpubContentMetrics(before: EpubContentMetrics, after: EpubContentMetrics): EpubIntegrityComparison;
|
|
25
|
+
export declare function assertEpubContentIntegrity(comparison: EpubIntegrityComparison): void;
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
import fs from "fs-extra";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
import * as cheerio from "cheerio";
|
|
4
|
+
import { getOPFPath, getTOCFiles, parseOPF } from "./epub-utils.js";
|
|
5
|
+
import { resolvePathInside } from "./path-safety.js";
|
|
6
|
+
const SCANNED_MEDIA_TYPES = new Set([
|
|
7
|
+
"application/xhtml+xml",
|
|
8
|
+
"text/html",
|
|
9
|
+
"text/css",
|
|
10
|
+
"image/svg+xml",
|
|
11
|
+
"application/x-dtbncx+xml",
|
|
12
|
+
]);
|
|
13
|
+
function isExternalReference(reference) {
|
|
14
|
+
return (reference === "" ||
|
|
15
|
+
reference.startsWith("#") ||
|
|
16
|
+
reference.startsWith("//") ||
|
|
17
|
+
/^[a-z][a-z0-9+.-]*:/i.test(reference));
|
|
18
|
+
}
|
|
19
|
+
function normalizeReference(reference) {
|
|
20
|
+
let normalized = reference.trim().replace(/&/gi, "&");
|
|
21
|
+
const quotePairs = [
|
|
22
|
+
["'", "'"],
|
|
23
|
+
['"', '"'],
|
|
24
|
+
["'", "'"],
|
|
25
|
+
["'", "'"],
|
|
26
|
+
["'", "'"],
|
|
27
|
+
[""", """],
|
|
28
|
+
[""", """],
|
|
29
|
+
[""", """],
|
|
30
|
+
];
|
|
31
|
+
for (const [open, close] of quotePairs) {
|
|
32
|
+
if (normalized.length >= open.length + close.length &&
|
|
33
|
+
normalized.slice(0, open.length).toLowerCase() === open.toLowerCase() &&
|
|
34
|
+
normalized.slice(-close.length).toLowerCase() === close.toLowerCase()) {
|
|
35
|
+
normalized = normalized.slice(open.length, -close.length);
|
|
36
|
+
break;
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
return normalized;
|
|
40
|
+
}
|
|
41
|
+
function collectMarkupReferences(content) {
|
|
42
|
+
const references = [];
|
|
43
|
+
const attributeRegex = /\b(?:src|href|xlink:href|poster)\s*=\s*(["'])(.*?)\1/gis;
|
|
44
|
+
const srcsetRegex = /\bsrcset\s*=\s*(["'])(.*?)\1/gis;
|
|
45
|
+
let match;
|
|
46
|
+
while ((match = attributeRegex.exec(content)) !== null) {
|
|
47
|
+
if (match[2] !== undefined)
|
|
48
|
+
references.push(match[2]);
|
|
49
|
+
}
|
|
50
|
+
while ((match = srcsetRegex.exec(content)) !== null) {
|
|
51
|
+
const srcset = match[2];
|
|
52
|
+
if (srcset === undefined)
|
|
53
|
+
continue;
|
|
54
|
+
for (const candidate of srcset.split(",")) {
|
|
55
|
+
const reference = candidate.trim().split(/\s+/, 1)[0];
|
|
56
|
+
if (reference)
|
|
57
|
+
references.push(reference);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
return references;
|
|
61
|
+
}
|
|
62
|
+
function collectCssReferences(content) {
|
|
63
|
+
const references = [];
|
|
64
|
+
const urlRegex = /url\(\s*(?:(["'])(.*?)\1|([^'")\s]+))\s*\)/gis;
|
|
65
|
+
const importRegex = /@import\s+(?:url\(\s*)?(["'])(.*?)\1\s*\)?/gis;
|
|
66
|
+
let match;
|
|
67
|
+
while ((match = urlRegex.exec(content)) !== null) {
|
|
68
|
+
const reference = match[2] ?? match[3];
|
|
69
|
+
if (reference !== undefined)
|
|
70
|
+
references.push(reference);
|
|
71
|
+
}
|
|
72
|
+
while ((match = importRegex.exec(content)) !== null) {
|
|
73
|
+
if (match[2] !== undefined)
|
|
74
|
+
references.push(match[2]);
|
|
75
|
+
}
|
|
76
|
+
return references;
|
|
77
|
+
}
|
|
78
|
+
async function collectNavigationEntries(epubDir) {
|
|
79
|
+
const tocFiles = await getTOCFiles(epubDir);
|
|
80
|
+
let entries = 0;
|
|
81
|
+
if (tocFiles.epub3Nav) {
|
|
82
|
+
const content = await fs.readFile(tocFiles.epub3Nav, "utf8");
|
|
83
|
+
const $ = cheerio.load(content, { xmlMode: true });
|
|
84
|
+
entries += $("nav a[href]").length;
|
|
85
|
+
}
|
|
86
|
+
if (tocFiles.epub2Ncx) {
|
|
87
|
+
const content = await fs.readFile(tocFiles.epub2Ncx, "utf8");
|
|
88
|
+
const $ = cheerio.load(content, { xmlMode: true });
|
|
89
|
+
entries += $("navMap navPoint").length;
|
|
90
|
+
}
|
|
91
|
+
return entries;
|
|
92
|
+
}
|
|
93
|
+
export async function collectEpubContentMetrics(epubDir) {
|
|
94
|
+
const opfPath = await getOPFPath(epubDir);
|
|
95
|
+
const opfDir = path.dirname(opfPath);
|
|
96
|
+
const $opf = await parseOPF(opfPath);
|
|
97
|
+
const manifest = new Map();
|
|
98
|
+
const missingReferences = new Set();
|
|
99
|
+
let internalReferences = 0;
|
|
100
|
+
for (const element of $opf("manifest item").toArray()) {
|
|
101
|
+
const item = $opf(element);
|
|
102
|
+
const id = item.attr("id") ?? "";
|
|
103
|
+
const href = item.attr("href") ?? "";
|
|
104
|
+
const mediaType = item.attr("media-type") ?? "";
|
|
105
|
+
const manifestItem = { id, mediaType };
|
|
106
|
+
if (href) {
|
|
107
|
+
internalReferences++;
|
|
108
|
+
try {
|
|
109
|
+
manifestItem.filePath = resolvePathInside(epubDir, opfDir, href, "manifest href");
|
|
110
|
+
if (!(await fs.pathExists(manifestItem.filePath))) {
|
|
111
|
+
missingReferences.add(`${path.relative(epubDir, opfPath)} -> ${href}`);
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
catch {
|
|
115
|
+
missingReferences.add(`${path.relative(epubDir, opfPath)} -> ${href} (unsafe)`);
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
manifest.set(id, manifestItem);
|
|
119
|
+
}
|
|
120
|
+
const spineElements = $opf("spine itemref").toArray();
|
|
121
|
+
for (const element of spineElements) {
|
|
122
|
+
const idref = $opf(element).attr("idref") ?? "";
|
|
123
|
+
const item = manifest.get(idref);
|
|
124
|
+
if (!item?.filePath || !(await fs.pathExists(item.filePath))) {
|
|
125
|
+
missingReferences.add(`${path.relative(epubDir, opfPath)} spine -> ${idref || "(missing idref)"}`);
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
for (const item of manifest.values()) {
|
|
129
|
+
if (!item.filePath || !SCANNED_MEDIA_TYPES.has(item.mediaType))
|
|
130
|
+
continue;
|
|
131
|
+
if (!(await fs.pathExists(item.filePath)))
|
|
132
|
+
continue;
|
|
133
|
+
const content = await fs.readFile(item.filePath, "utf8");
|
|
134
|
+
const references = [...collectMarkupReferences(content), ...collectCssReferences(content)];
|
|
135
|
+
for (const rawReference of references) {
|
|
136
|
+
const reference = normalizeReference(rawReference);
|
|
137
|
+
if (isExternalReference(reference))
|
|
138
|
+
continue;
|
|
139
|
+
internalReferences++;
|
|
140
|
+
try {
|
|
141
|
+
const target = resolvePathInside(epubDir, path.dirname(item.filePath), reference, "content reference");
|
|
142
|
+
if (!(await fs.pathExists(target))) {
|
|
143
|
+
missingReferences.add(`${path.relative(epubDir, item.filePath)} -> ${reference}`);
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
catch {
|
|
147
|
+
missingReferences.add(`${path.relative(epubDir, item.filePath)} -> ${reference} (unsafe)`);
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
const manifestItems = Array.from(manifest.values());
|
|
152
|
+
const missingReferenceTargets = Array.from(missingReferences).sort();
|
|
153
|
+
return {
|
|
154
|
+
manifestItems: manifestItems.length,
|
|
155
|
+
spineItems: spineElements.length,
|
|
156
|
+
contentDocuments: manifestItems.filter(({ mediaType }) => mediaType === "application/xhtml+xml" || mediaType === "text/html").length,
|
|
157
|
+
images: manifestItems.filter(({ mediaType }) => mediaType.startsWith("image/")).length,
|
|
158
|
+
navigationEntries: await collectNavigationEntries(epubDir),
|
|
159
|
+
internalReferences,
|
|
160
|
+
missingReferences: missingReferenceTargets.length,
|
|
161
|
+
missingReferenceTargets,
|
|
162
|
+
};
|
|
163
|
+
}
|
|
164
|
+
export function compareEpubContentMetrics(before, after) {
|
|
165
|
+
const metricNames = [
|
|
166
|
+
"manifestItems",
|
|
167
|
+
"spineItems",
|
|
168
|
+
"contentDocuments",
|
|
169
|
+
"images",
|
|
170
|
+
"navigationEntries",
|
|
171
|
+
];
|
|
172
|
+
const checks = metricNames.map((name) => ({
|
|
173
|
+
name,
|
|
174
|
+
before: before[name],
|
|
175
|
+
after: after[name],
|
|
176
|
+
passed: after[name] >= before[name],
|
|
177
|
+
}));
|
|
178
|
+
const previousMissing = new Set(before.missingReferenceTargets);
|
|
179
|
+
const newMissingReferences = after.missingReferenceTargets.filter((reference) => !previousMissing.has(reference));
|
|
180
|
+
const issues = checks
|
|
181
|
+
.filter(({ passed }) => !passed)
|
|
182
|
+
.map(({ name, before: previous, after: current }) => `${name} decreased from ${previous} to ${current}.`);
|
|
183
|
+
for (const reference of newMissingReferences) {
|
|
184
|
+
issues.push(`New missing internal reference: ${reference}`);
|
|
185
|
+
}
|
|
186
|
+
return {
|
|
187
|
+
valid: issues.length === 0,
|
|
188
|
+
checks,
|
|
189
|
+
newMissingReferences,
|
|
190
|
+
issues,
|
|
191
|
+
};
|
|
192
|
+
}
|
|
193
|
+
export function assertEpubContentIntegrity(comparison) {
|
|
194
|
+
if (!comparison.valid) {
|
|
195
|
+
throw new Error(`Content integrity validation failed:\n- ${comparison.issues.join("\n- ")}`);
|
|
196
|
+
}
|
|
197
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/** SHA-256 of each document's reader-visible text, keyed by its EPUB path. */
|
|
2
|
+
export type EpubTextSnapshot = Map<string, string>;
|
|
3
|
+
/**
|
|
4
|
+
* Extract the text a reader sees in a content document: the character data of
|
|
5
|
+
* `<body>` with references resolved, excluding scripts, styles and comments.
|
|
6
|
+
* SVG documents include text, accessibility descriptions and foreign objects,
|
|
7
|
+
* excluding metadata and formatting between graphical elements.
|
|
8
|
+
*/
|
|
9
|
+
export declare function extractDocumentText(content: string, filePath?: string): string;
|
|
10
|
+
export declare function collectEpubTextSnapshot(epubDir: string): Promise<EpubTextSnapshot>;
|
|
11
|
+
/** @returns One message per document whose text was lost or altered. */
|
|
12
|
+
export declare function compareEpubTextSnapshots(before: EpubTextSnapshot, after: EpubTextSnapshot): string[];
|
|
13
|
+
export declare function assertEpubTextPreserved(before: EpubTextSnapshot, after: EpubTextSnapshot): void;
|