@likecoin/epubcheck-ts 0.3.9 → 0.4.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

@@ -3,13 +3,17 @@ import { readFile, 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 VERSION = "0.4.0";
 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 },
+    fatal: { type: "boolean", short: "f", default: false },
+    error: { type: "boolean", short: "e", default: false },
+    warn: { type: "boolean", 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", short: "w", default: false },
@@ -22,7 +26,7 @@ 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);
 }
@@ -45,6 +49,10 @@ Options:
   -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\\tSEVERITY)
   -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
@@ -61,8 +69,8 @@ Exit Codes:
   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.
+Note: This tool provides ~93% coverage of Java EPUBCheck features.
+Missing features: single-file/directory validation, advanced ARIA, XHTML/SVG schema.
 For complete EPUB 3 conformance testing, use: https://github.com/w3c/epubcheck
 
 Report issues: https://github.com/likecoin/epubcheck-ts/issues
@@ -90,10 +98,31 @@ async function main() {
     if (values.usage) {
       options.includeUsage = true;
     }
+    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 result = await EpubCheck.validate(epubData, options);
     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;
+    const isFiltered = values.fatal || values.error || values.warn;
+    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 +138,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 +163,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,7 +188,7 @@ 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();

package/bin/epubcheck.ts

@@ -10,12 +10,12 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
 import { basename } from 'node:path';
-import type { EpubCheckOptions, EPUBProfile, ValidationMessage } from '../src/types.js';
+import type { EpubCheckOptions, EPUBProfile, Severity, ValidationMessage } from '../src/types.js';
 
 // Dynamic import to support both ESM and CJS builds
 const { EpubCheck, toJSONReport } = await import('../dist/index.js');
 
-const VERSION = '0.3.9';
+const VERSION = '0.4.0';
 
 // Parse command line arguments
 const { values, positionals } = parseArgs({
@@ -24,6 +24,10 @@ const { values, positionals } = parseArgs({
     quiet: { type: 'boolean', short: 'q', default: false },
     profile: { type: 'string', short: 'p' },
     usage: { type: 'boolean', short: 'u', default: false },
+    fatal: { type: 'boolean', short: 'f', default: false },
+    error: { type: 'boolean', short: 'e', default: false },
+    warn: { type: 'boolean', 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', short: 'w', default: false },
@@ -38,7 +42,7 @@ 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);
 }
@@ -65,6 +69,10 @@ Options:
   -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\\tSEVERITY)
   -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
@@ -81,8 +89,8 @@ Exit Codes:
   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.
+Note: This tool provides ~93% coverage of Java EPUBCheck features.
+Missing features: single-file/directory validation, advanced ARIA, XHTML/SVG schema.
 For complete EPUB 3 conformance testing, use: https://github.com/w3c/epubcheck
 
 Report issues: https://github.com/likecoin/epubcheck-ts/issues
@@ -118,12 +126,35 @@ async function main(): Promise<void> {
     if (values.usage) {
       options.includeUsage = true;
     }
+    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 result = await EpubCheck.validate(epubData, options);
     const elapsedMs = Date.now() - startTime;
 
+    // Most restrictive severity flag wins (--fatal overrides --error overrides --warn)
+    const severityRank: Record<Severity, number> = {
+      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;
+    const isFiltered = values.fatal || values.error || values.warn;
+    const displayMessages = result.messages.filter(
+      (m: ValidationMessage) => severityRank[m.severity] <= maxRank,
+    );
+
     // Output JSON report if requested
     if (values.json !== undefined) {
-      const jsonContent = toJSONReport(result); // Already stringified
+      const filteredResult = isFiltered ? { ...result, messages: displayMessages } : result;
+      const jsonContent = toJSONReport(filteredResult); // Already stringified
 
       if (values.json === '-') {
         // Output to stdout - suppress other output
@@ -145,11 +176,11 @@ async function main(): Promise<void> {
     // Console output (unless quiet mode)
     if (!values.quiet) {
       // Group messages by severity
-      const fatal = result.messages.filter((m: ValidationMessage) => m.severity === 'fatal');
-      const errors = result.messages.filter((m: ValidationMessage) => m.severity === 'error');
-      const warnings = result.messages.filter((m: ValidationMessage) => m.severity === 'warning');
-      const info = result.messages.filter((m: ValidationMessage) => m.severity === 'info');
-      const usage = result.messages.filter((m: ValidationMessage) => m.severity === 'usage');
+      const fatal = displayMessages.filter((m: ValidationMessage) => m.severity === 'fatal');
+      const errors = displayMessages.filter((m: ValidationMessage) => m.severity === 'error');
+      const warnings = displayMessages.filter((m: ValidationMessage) => m.severity === 'warning');
+      const info = displayMessages.filter((m: ValidationMessage) => m.severity === 'info');
+      const usage = displayMessages.filter((m: ValidationMessage) => m.severity === 'usage');
 
       // Print messages with colors
       const printMessages = (
@@ -180,8 +211,7 @@ async function main(): Promise<void> {
       if (warnings.length > 0) {
         printMessages(warnings, '\x1b[33m', 'WARNING');
       }
-      if (info.length > 0 && result.messages.length < 20) {
-        // Only show info if total messages is small
+      if (info.length > 0 && displayMessages.length < 20) {
         printMessages(info, '\x1b[36m', 'INFO');
       }
       if (usage.length > 0) {
@@ -210,7 +240,7 @@ async function main(): Promise<void> {
       // Show limitation notice if there were no major errors
       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();