@likecoin/epubcheck-ts 0.3.9 → 0.5.0

package/README.md

@@ -1,25 +1,24 @@
 # epubcheck-ts
 
-A TypeScript port of [EPUBCheck](https://github.com/w3c/epubcheck) - the official conformance checker for EPUB publications.
+Validate EPUB files in Node.js and the browser. A TypeScript implementation of [EPUBCheck](https://github.com/w3c/epubcheck).
 
 [![CI](https://github.com/likecoin/epubcheck-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/likecoin/epubcheck-ts/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/%40likecoin%2Fepubcheck-ts)](https://www.npmjs.com/package/@likecoin/epubcheck-ts)
 [![License](https://img.shields.io/npm/l/%40likecoin%2Fepubcheck-ts)](./LICENSE)
 
-> **Note**: This library is primarily developed for internal use at [3ook.com](https://3ook.com/about) and is built with AI-assisted development. While it has comprehensive test coverage (892 passing / 945 total tests) and ~88% feature parity with Java EPUBCheck, it may not be suitable for mission-critical production workloads. For production environments requiring full EPUB validation, consider using the official [Java EPUBCheck](https://github.com/w3c/epubcheck). Contributions and feedback are welcome!
+> **Status**: 93% feature parity with Java EPUBCheck (1061 tests passing, 74 skipped). See [PROJECT_STATUS.md](./PROJECT_STATUS.md) for details. For full EPUB 3 conformance testing, use the official [Java EPUBCheck](https://github.com/w3c/epubcheck).
 
 ## Features
 
-- **CLI and programmatic API**: Use as a command-line tool or integrate into your application
-- **Cross-platform**: Works in Node.js (18+) and modern browsers
-- **Partial EPUB validation**: Currently ~88% of EPUBCheck feature parity
-- **Zero native dependencies**: Pure JavaScript/WebAssembly, no compilation required
-- **TypeScript first**: Full type definitions included
-- **Tree-shakable**: ESM with proper exports for optimal bundling
+- **CLI and API** — Use as a CLI tool (`npx @likecoin/epubcheck-ts book.epub`) or import as a library
+- **Browser support** — Works in Node.js 18+ and modern browsers via pure JS + WASM
+- **No native dependencies** — No Java, no compilation — `npm install` and go
+- **TypeScript** — Full type definitions included
+- **Tree-shakable** — ESM with proper exports for minimal bundle impact
 
 ## Try it Online
 
-Try the live demo at **[likecoin.github.io/epubcheck-ts](https://likecoin.github.io/epubcheck-ts/)** - validate your EPUB files directly in the browser without uploading to any server.
+Live demo at **[likecoin.github.io/epubcheck-ts](https://likecoin.github.io/epubcheck-ts/)** — validate EPUB files in the browser without uploading to any server.
 
 ## Installation
 
@@ -50,7 +49,13 @@ Options:
   -j, --json <file>        Output JSON report to file (use '-' for stdout)
   -q, --quiet              Suppress console output (errors only)
   -p, --profile <name>     Validation profile (default|dict|edupub|idx|preview)
+  -u, --usage              Include usage messages (best practices)
+  -f, --fatal              Show only fatal errors
+  -e, --error              Show fatal errors and errors
+      --warn               Show fatal errors, errors, and warnings
+  -c, --customMessages <file>  Override message severities (TSV: ID<tab>SEVERITY)
   -w, --fail-on-warnings   Exit with code 1 if warnings are found
+  -l, --listChecks         List all message IDs and severities
   -v, --version            Show version information
   -h, --help               Show this help message
 ```
@@ -68,9 +73,14 @@ epubcheck-ts book.epub --quiet --fail-on-warnings
 
 # Validate with specific profile
 epubcheck-ts dictionary.epub --profile dict
-```
 
-**Note:** This CLI provides ~88% coverage of Java EPUBCheck features. For complete EPUB 3 conformance testing, use the [official Java EPUBCheck](https://github.com/w3c/epubcheck).
+# Show only errors (hide warnings/info)
+epubcheck-ts book.epub --error
+
+# Enable suppressed accessibility checks
+printf "ACC-004\tWARNING\nACC-005\tWARNING\n" > overrides.txt
+epubcheck-ts book.epub -c overrides.txt
+```
 
 ### ES Modules (recommended)
 
@@ -181,6 +191,9 @@ interface EpubCheckOptions {
   
   /** Locale for messages (default: 'en') */
   locale?: string;
+  
+  /** Custom message severity overrides (message ID → severity) */
+  customMessages?: Map<string, MessageSeverity>;
 }
 ```
 
@@ -266,20 +279,20 @@ This library is a TypeScript port of the Java-based [EPUBCheck](https://github.c
 
 | Component | Status | Completeness | Notes |
 |-----------|--------|--------------|-------|
-| OCF Container | 🟡 Partial | ~90% | ZIP structure, mimetype, container.xml, encryption.xml obfuscation |
-| Package Document (OPF) | 🟢 Complete | ~90% | Metadata, manifest, spine, collections, Schematron-equivalent checks |
-| Content Documents | 🟡 Partial | ~85% | XHTML structure, CSS url(), @import, SVG, entities, title, SSML, XML version |
-| Navigation Document | 🟢 Complete | ~85% | Nav content model, landmarks, labels, reading order, hidden |
-| Schema Validation | 🟡 Partial | ~50% | RelaxNG for OPF/container; XHTML/SVG disabled (libxml2 limitation) |
-| CSS | 🟡 Partial | ~70% | @font-face, @import, url() extraction, position, forbidden properties |
-| Cross-reference Validation | 🟢 Complete | ~90% | Reference tracking, fragments, fallbacks, remote resources |
-| Accessibility Checks | 🟡 Partial | ~30% | Basic checks only (empty links, image alt, SVG titles) |
-| Media Overlays | ❌ Not Started | 0% | Planned |
+| OCF Container | 🟢 Complete | ~92% | ZIP structure, mimetype, container.xml, encryption.xml obfuscation |
+| Package Document (OPF) | 🟢 Complete | ~92% | Metadata, manifest, spine, collections, Schematron-equivalent checks |
+| Content Documents | 🟢 Complete | ~93% | XHTML structure, CSS url(), @import, SVG, entities, title, SSML, XML version |
+| Navigation Document | 🟢 Complete | ~95% | Nav content model, landmarks, labels, reading order, hidden, nested-ol |
+| Schema Validation | 🟡 Partial | ~55% | RelaxNG for OPF/container; XHTML/SVG disabled (libxml2 limitation) |
+| CSS | 🟡 Partial | ~85% | @font-face, @import, url() extraction, position, forbidden properties, alt style tags |
+| Cross-reference Validation | 🟢 Complete | ~92% | Reference tracking, fragments, fallbacks, remote resources, cross-document features |
+| Accessibility Checks | 🟢 Complete | ~71% | 12/17 ACC checks: table, image alt, hyperlink, MathML, SVG, epub:type, OPF metadata |
+| Media Overlays | 🟡 Partial | ~70% | SMIL structure, timing, audio, OPF metadata, duration validation |
 | Media Validation | ❌ Not Started | 0% | Planned |
 
 Legend: 🟢 Complete | 🟡 Partial | 🔴 Basic | ❌ Not Started
 
-**Overall Progress: ~88% of Java EPUBCheck features**
+**Overall Progress: ~93% of Java EPUBCheck features**
 
 See [PROJECT_STATUS.md](./PROJECT_STATUS.md) for detailed comparison.
 
@@ -364,13 +377,13 @@ Legend: ✅ Implemented
 | Aspect | epubcheck-ts | EPUBCheck (Java) |
 |--------|--------------|------------------|
 | Runtime | Node.js / Browser | JVM |
-| Feature Parity | ~88% | 100% |
+| Feature Parity | ~93% | 100% |
 | Bundle Size | ~450KB JS + ~1.6MB WASM | ~15MB |
 | Installation | `npm install` | Download JAR |
 | Integration | Native JS/TS | CLI or Java API |
 | Performance | Comparable | Baseline |
 
-**Note:** epubcheck-ts is currently in active development. See [PROJECT_STATUS.md](./PROJECT_STATUS.md) for detailed feature comparison.
+See [PROJECT_STATUS.md](./PROJECT_STATUS.md) for detailed feature comparison.
 
 ## Contributing
 

package/bin/epubcheck.js

@@ -1,28 +1,60 @@
 #!/usr/bin/env node
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { parseArgs } from "node:util";
-import { basename } from "node:path";
-const { EpubCheck, toJSONReport } = await import("../dist/index.js");
-const VERSION = "0.3.9";
-const { values, positionals } = parseArgs({
-  options: {
-    json: { type: "string", short: "j" },
-    quiet: { type: "boolean", short: "q", default: false },
-    profile: { type: "string", short: "p" },
-    usage: { type: "boolean", short: "u", default: false },
-    version: { type: "boolean", short: "v", default: false },
-    help: { type: "boolean", short: "h", default: false },
-    "fail-on-warnings": { type: "boolean", short: "w", default: false },
-    listChecks: { type: "boolean", short: "l", default: false }
-  },
-  allowPositionals: true,
-  strict: false
-});
+import { basename, join, relative, sep } from "node:path";
+const { EpubCheck, EPUB_VERSIONS, toJSONReport } = await import("../dist/index.js");
+const VERSION = "0.5.0";
+const VALID_MODES = /* @__PURE__ */ new Set([
+  "exp",
+  "opf",
+  "xhtml",
+  "svg",
+  "nav",
+  "mo"
+]);
+let values;
+let positionals;
+try {
+  ({ values, positionals } = parseArgs({
+    options: {
+      json: { type: "string", short: "j" },
+      quiet: { type: "boolean", short: "q", default: false },
+      profile: { type: "string", short: "p" },
+      mode: { type: "string", short: "m" },
+      "epub-version": { type: "string", short: "v" },
+      usage: { type: "boolean", short: "u", default: false },
+      fatal: { type: "boolean", short: "f", default: false },
+      error: { type: "boolean", short: "e", default: false },
+      warn: { type: "boolean", short: "w", default: false },
+      info: { type: "boolean", short: "i", default: false },
+      customMessages: { type: "string", short: "c" },
+      version: { type: "boolean", short: "V", default: false },
+      help: { type: "boolean", short: "h", default: false },
+      "fail-on-warnings": { type: "boolean", default: false },
+      failonwarnings: { type: "boolean", default: false },
+      listChecks: { type: "boolean", short: "l", default: false }
+    },
+    allowPositionals: true,
+    strict: true
+  }));
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`\x1B[31mError:\x1B[0m ${message}`);
+  const unsupportedJavaFlags = ["--out", "-o", "--xmp", "-x", "--save", "--locale"];
+  const matched = unsupportedJavaFlags.find((f) => message.includes(f));
+  if (matched) {
+    console.error(
+      `\x1B[90mNote: ${matched} is a Java EPUBCheck flag that epubcheck-ts does not yet support.\x1B[0m`
+    );
+  }
+  console.error("Run with --help for usage information");
+  process.exit(2);
+}
 if (values.version) {
   console.log(`EPUBCheck-TS v${VERSION}`);
   console.log("TypeScript EPUB validator for Node.js and browsers");
   console.log();
-  console.log("Note: This is ~88% feature-complete compared to Java EPUBCheck.");
+  console.log("Note: This is ~93% feature-complete compared to Java EPUBCheck.");
   console.log("For production validation: https://github.com/w3c/epubcheck");
   process.exit(0);
 }
@@ -35,65 +67,165 @@ if (values.listChecks) {
 if (values.help || positionals.length === 0) {
   console.log(`EPUBCheck-TS v${VERSION} - EPUB Validator
 
-Usage: epubcheck-ts <file.epub> [options]
+Usage: epubcheck-ts <file> [options]
 
 Arguments:
-  <file.epub>              Path to EPUB file to validate
+  <file>                   Path to EPUB file, directory, or single file to validate
 
 Options:
   -j, --json <file>        Output JSON report to file (use '-' for stdout)
   -q, --quiet              Suppress console output (errors only)
   -p, --profile <name>     Validation profile (default|dict|edupub|idx|preview)
+  -m, --mode <type>        Validation mode: exp (expanded directory), opf, xhtml, svg, nav, mo
+  -v, --epub-version <ver> EPUB version for single-file mode (2|2.0|3|3.0|3.1|3.2|3.3)
   -u, --usage              Include usage messages (best practices)
-  -w, --fail-on-warnings   Exit with code 1 if warnings are found
+  -f, --fatal              Show only fatal errors
+  -e, --error              Show fatal errors and errors
+  -w, --warn               Show fatal errors, errors, and warnings
+  -i, --info               Show fatal, error, warning, and info messages
+  -c, --customMessages <file>  Override message severities (TSV: ID\\tSEVERITY)
+      --fail-on-warnings   Exit with code 1 if warnings are found
+                           (also accepts --failonwarnings for Java compatibility)
   -l, --listChecks         List all message IDs and severities
-  -v, --version            Show version information
+  -V, --version            Show version information
   -h, --help               Show this help message
 
+Modes:
+  --mode exp               Validate an expanded (unpacked) EPUB directory
+  --mode opf -v 3.0        Validate a standalone OPF package document
+  --mode xhtml -v 3.0      Validate a standalone XHTML content document
+  --mode svg -v 3.0        Validate a standalone SVG content document
+  --mode nav -v 3.0        Validate a standalone Navigation Document (EPUB 3 only)
+  --mode mo -v 3.0         Validate a standalone SMIL media overlay document
+
 Examples:
   epubcheck-ts book.epub
   epubcheck-ts book.epub --json report.json
   epubcheck-ts book.epub --quiet --fail-on-warnings
   epubcheck-ts book.epub --profile dict
+  epubcheck-ts ./unpacked-epub/ --mode exp
+  epubcheck-ts chapter.xhtml --mode xhtml -v 3.0
+  epubcheck-ts package.opf --mode opf -v 3.0
+  epubcheck-ts image.svg --mode svg -v 3.0
+  epubcheck-ts nav.xhtml --mode nav -v 3.0
+  epubcheck-ts overlay.smil --mode mo -v 3.0
 
 Exit Codes:
   0  No errors (or only warnings if --fail-on-warnings not set)
   1  Validation errors found (or warnings with --fail-on-warnings)
   2  Runtime error (file not found, invalid arguments, etc.)
 
-Note: This tool provides ~88% coverage of Java EPUBCheck features.
-Missing features: Media Overlays, advanced ARIA checks, encryption/signatures.
-For complete EPUB 3 conformance testing, use: https://github.com/w3c/epubcheck
-
 Report issues: https://github.com/likecoin/epubcheck-ts/issues
 `);
   process.exit(0);
 }
+async function readDirectoryFiles(dirPath) {
+  const files = /* @__PURE__ */ new Map();
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      } else if (entry.isFile()) {
+        const relPath = relative(dirPath, fullPath).split(sep).join("/");
+        const data = await readFile(fullPath);
+        files.set(relPath, data);
+      }
+    }
+  }
+  await walk(dirPath);
+  return files;
+}
 async function main() {
   const filePath = positionals[0];
   if (!filePath) {
-    console.error("Error: No EPUB file specified");
+    console.error("Error: No file specified");
     console.error("Run with --help for usage information");
     process.exit(2);
   }
+  const mode = values.mode;
+  if (mode && !VALID_MODES.has(mode)) {
+    console.error(`Error: Invalid mode "${mode}". Valid modes: ${[...VALID_MODES].join(", ")}`);
+    process.exit(2);
+  }
+  const rawVersion = values["epub-version"];
+  const epubVersion = rawVersion === "2" ? "2.0" : rawVersion === "3" ? "3.0" : rawVersion;
+  if (epubVersion && !EPUB_VERSIONS.includes(epubVersion)) {
+    console.error(
+      `Error: Invalid EPUB version "${epubVersion}". Valid versions: ${EPUB_VERSIONS.join(", ")}`
+    );
+    process.exit(2);
+  }
+  if (mode && mode !== "exp" && !epubVersion) {
+    console.error(`Error: --epub-version (-v) is required when using --mode ${mode}`);
+    process.exit(2);
+  }
   try {
     if (!values.quiet) {
       console.log(`Validating: ${basename(filePath)}`);
       console.log();
     }
-    const epubData = await readFile(filePath);
-    const startTime = Date.now();
     const options = {};
     if (values.profile) {
       options.profile = values.profile;
     }
+    if (epubVersion) {
+      options.version = epubVersion;
+    }
+    if (mode) {
+      options.mode = mode;
+    }
     if (values.usage) {
       options.includeUsage = true;
     }
-    const result = await EpubCheck.validate(epubData, options);
+    if (typeof values.customMessages === "string") {
+      const { parseCustomMessages } = await import("../dist/index.js");
+      const cmContent = await readFile(values.customMessages, "utf-8");
+      options.customMessages = parseCustomMessages(cmContent);
+    }
+    const startTime = Date.now();
+    let result;
+    let effectiveMode = mode;
+    if (!mode || mode === "exp") {
+      const fileStat = await stat(filePath);
+      if (fileStat.isDirectory()) {
+        effectiveMode = "exp";
+      } else if (mode === "exp") {
+        console.error("Error: --mode exp requires a directory path");
+        process.exit(2);
+      }
+    }
+    if (effectiveMode === "exp") {
+      const files = await readDirectoryFiles(filePath);
+      result = await EpubCheck.validateExpanded(files, options);
+    } else if (effectiveMode === "opf" || effectiveMode === "xhtml" || effectiveMode === "svg" || effectiveMode === "nav" || effectiveMode === "mo") {
+      const fileData = await readFile(filePath);
+      result = await EpubCheck.validateSingleFile(fileData, basename(filePath), options);
+    } else {
+      const epubData = await readFile(filePath);
+      result = await EpubCheck.validate(epubData, options, basename(filePath));
+    }
     const elapsedMs = Date.now() - startTime;
+    const severityRank = {
+      fatal: 0,
+      error: 1,
+      warning: 2,
+      info: 3,
+      usage: 4
+    };
+    let maxRank = 4;
+    if (values.fatal) maxRank = 0;
+    else if (values.error) maxRank = 1;
+    else if (values.warn) maxRank = 2;
+    else if (values.info) maxRank = 3;
+    const isFiltered = values.fatal || values.error || values.warn || values.info;
+    const displayMessages = result.messages.filter(
+      (m) => severityRank[m.severity] <= maxRank
+    );
     if (values.json !== void 0) {
-      const jsonContent = toJSONReport(result);
+      const filteredResult = isFiltered ? { ...result, messages: displayMessages } : result;
+      const jsonContent = toJSONReport(filteredResult);
       if (values.json === "-") {
         if (values.quiet) {
           console.log(jsonContent);
@@ -109,11 +241,11 @@ async function main() {
       }
     }
     if (!values.quiet) {
-      const fatal = result.messages.filter((m) => m.severity === "fatal");
-      const errors = result.messages.filter((m) => m.severity === "error");
-      const warnings = result.messages.filter((m) => m.severity === "warning");
-      const info = result.messages.filter((m) => m.severity === "info");
-      const usage = result.messages.filter((m) => m.severity === "usage");
+      const fatal = displayMessages.filter((m) => m.severity === "fatal");
+      const errors = displayMessages.filter((m) => m.severity === "error");
+      const warnings = displayMessages.filter((m) => m.severity === "warning");
+      const info = displayMessages.filter((m) => m.severity === "info");
+      const usage = displayMessages.filter((m) => m.severity === "usage");
       const printMessages = (messages, color, label) => {
         if (messages.length === 0) return;
         for (const msg of messages) {
@@ -134,7 +266,7 @@ async function main() {
       if (warnings.length > 0) {
         printMessages(warnings, "\x1B[33m", "WARNING");
       }
-      if (info.length > 0 && result.messages.length < 20) {
+      if (info.length > 0 && displayMessages.length < 20) {
         printMessages(info, "\x1B[36m", "INFO");
       }
       if (usage.length > 0) {
@@ -159,13 +291,14 @@ async function main() {
       console.log();
       if (result.errorCount === 0 && result.fatalCount === 0) {
         console.log(
-          "\x1B[90mNote: This validator provides ~88% coverage of Java EPUBCheck.\x1B[0m"
+          "\x1B[90mNote: This validator provides ~93% coverage of Java EPUBCheck.\x1B[0m"
         );
         console.log("\x1B[90mFor complete validation: https://github.com/w3c/epubcheck\x1B[0m");
         console.log();
       }
     }
-    const shouldFail = result.errorCount > 0 || result.fatalCount > 0 || values["fail-on-warnings"] && result.warningCount > 0;
+    const failOnWarnings = values["fail-on-warnings"] || values.failonwarnings;
+    const shouldFail = result.errorCount > 0 || result.fatalCount > 0 || failOnWarnings && result.warningCount > 0;
     process.exit(shouldFail ? 1 : 0);
   } catch (error) {
     console.error("\x1B[31mError:\x1B[0m", error instanceof Error ? error.message : String(error));