@likecoin/epubcheck-ts 0.1.0 → 0.2.1

package/README.md

@@ -6,14 +6,21 @@ A TypeScript port of [EPUBCheck](https://github.com/w3c/epubcheck) - the officia
 [![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 (208 tests) and ~65% 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!
+
 ## 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 ~35% of EPUBCheck feature parity
+- **Partial EPUB validation**: Currently ~65% 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
 
+## 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.
+
 ## Installation
 
 ```bash
@@ -22,6 +29,49 @@ npm install @likecoin/epubcheck-ts
 
 ## Quick Start
 
+### Command Line Interface (CLI)
+
+**Quick validation:**
+```bash
+npx @likecoin/epubcheck-ts book.epub
+```
+
+**Or install globally:**
+```bash
+npm install -g @likecoin/epubcheck-ts
+epubcheck-ts book.epub
+```
+
+**CLI Options:**
+```bash
+epubcheck-ts <file.epub> [options]
+
+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)
+  -w, --fail-on-warnings   Exit with code 1 if warnings are found
+  -v, --version            Show version information
+  -h, --help               Show this help message
+```
+
+**Examples:**
+```bash
+# Basic validation
+epubcheck-ts book.epub
+
+# Generate JSON report
+epubcheck-ts book.epub --json report.json
+
+# Quiet mode for CI/CD
+epubcheck-ts book.epub --quiet --fail-on-warnings
+
+# Validate with specific profile
+epubcheck-ts dictionary.epub --profile dict
+```
+
+**Note:** This CLI provides ~65% coverage of Java EPUBCheck features. For complete EPUB 3 conformance testing, use the [official Java EPUBCheck](https://github.com/w3c/epubcheck).
+
 ### ES Modules (recommended)
 
 ```typescript
@@ -214,19 +264,20 @@ This library is a TypeScript port of the Java-based [EPUBCheck](https://github.c
 
 | Component | Status | Completeness | Notes |
 |-----------|--------|--------------|-------|
-| OCF Container | 🟡 Partial | ~40% | ZIP structure, mimetype, container.xml |
-| Package Document (OPF) | 🟡 Partial | ~40% | Metadata, manifest, spine, fallback chains |
-| Content Documents | 🟡 Partial | ~25% | XML well-formedness, XHTML structure |
-| Navigation Document | 🟡 Partial | ~30% | Nav structure, NCX validation |
+| OCF Container | 🟡 Partial | ~70% | ZIP structure, mimetype (uncompressed check), container.xml |
+| Package Document (OPF) | 🟡 Partial | ~70% | Metadata, manifest, spine, collections, version/date validation |
+| Content Documents | 🟡 Partial | ~70% | XHTML structure, script/MathML/SVG detection, link validation |
+| Navigation Document | 🟡 Partial | ~40% | Nav structure, NCX validation, remote link validation |
 | Schema Validation | 🟡 Partial | ~70% | RelaxNG, XSD, Schematron working |
-| CSS | 🔴 Basic | ~5% | Parser available, validation minimal |
+| CSS | 🟡 Partial | ~50% | @font-face, @import, media overlay classes, position warnings |
+| Cross-reference Validation | 🟡 Partial | ~75% | Reference tracking, fragment validation, undeclared resources |
+| Accessibility Checks | 🟡 Partial | ~75% | Empty links, image alt, SVG titles, MathML alttext |
 | Media Overlays | ❌ Not Started | 0% | Planned |
-| Cross-reference Validation | 🔴 Basic | ~15% | Basic reference tracking |
-| Accessibility Checks | ❌ Not Started | 0% | Alt text, etc. |
+| Media Validation | ❌ Not Started | 0% | Planned |
 
 Legend: 🟢 Complete | 🟡 Partial | 🔴 Basic | ❌ Not Started
 
-**Overall Progress: ~35% of Java EPUBCheck features**
+**Overall Progress: ~65% of Java EPUBCheck features**
 
 See [PROJECT_STATUS.md](./PROJECT_STATUS.md) for detailed comparison.
 
@@ -306,7 +357,7 @@ Legend: ✅ Implemented
 | Aspect | epubcheck-ts | EPUBCheck (Java) |
 |--------|--------------|------------------|
 | Runtime | Node.js / Browser | JVM |
-| Feature Parity | ~35% | 100% |
+| Feature Parity | ~65% | 100% |
 | Bundle Size | ~55KB JS + ~1.5MB WASM | ~15MB |
 | Installation | `npm install` | Download JAR |
 | Integration | Native JS/TS | CLI or Java API |
@@ -332,6 +383,10 @@ This is an independent TypeScript implementation inspired by the Java-based [EPU
 - [DAISY Consortium](https://daisy.org/) - Maintainers of EPUBCheck
 - [libxml2-wasm](https://github.com/jameslan/libxml2-wasm) - WebAssembly XML processing
 
+## Built by 3ook.com
+
+This project is built and maintained by the [3ook.com](https://3ook.com/about) team. 3ook is a Web3 eBook platform where authors can publish EPUB ebooks and readers can collect them as digital assets. If you're an author looking to publish your ebook, check out [3ook.com](https://3ook.com/about).
+
 ## Related Projects
 
 - [EPUBCheck](https://github.com/w3c/epubcheck) - Official Java validator

package/bin/epubcheck.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+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.2.1";
+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 }
+  },
+  allowPositionals: true,
+  strict: false
+});
+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 ~65% feature-complete compared to Java EPUBCheck.");
+  console.log("For production validation: https://github.com/w3c/epubcheck");
+  process.exit(0);
+}
+if (values.help || positionals.length === 0) {
+  console.log(`EPUBCheck-TS v${VERSION} - EPUB Validator
+
+Usage: epubcheck-ts <file.epub> [options]
+
+Arguments:
+  <file.epub>              Path to EPUB 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)
+  -u, --usage              Include usage messages (best practices)
+  -w, --fail-on-warnings   Exit with code 1 if warnings are found
+  -v, --version            Show version information
+  -h, --help               Show this help message
+
+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
+
+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 ~65% 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 main() {
+  const filePath = positionals[0];
+  if (!filePath) {
+    console.error("Error: No EPUB file specified");
+    console.error("Run with --help for usage information");
+    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 (values.usage) {
+      options.includeUsage = true;
+    }
+    const result = await EpubCheck.validate(epubData, options);
+    const elapsedMs = Date.now() - startTime;
+    if (values.json !== void 0) {
+      const jsonContent = toJSONReport(result);
+      if (values.json === "-") {
+        if (values.quiet) {
+          console.log(jsonContent);
+        } else {
+          console.log("\nJSON Report:");
+          console.log(jsonContent);
+        }
+      } else if (typeof values.json === "string") {
+        await writeFile(values.json, jsonContent, "utf-8");
+        if (!values.quiet) {
+          console.log(`JSON report written to: ${values.json}`);
+        }
+      }
+    }
+    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 printMessages = (messages, color, label) => {
+        if (messages.length === 0) return;
+        for (const msg of messages) {
+          const locationStr = msg.location ? ` (${msg.location.path}${msg.location.line !== void 0 ? `:${String(msg.location.line)}` : ""})` : "";
+          console.log(`${color}${label}${locationStr}: ${msg.message}\x1B[0m`);
+          if (msg.id) {
+            console.log(`  \x1B[90mID: ${msg.id}\x1B[0m`);
+          }
+        }
+        console.log();
+      };
+      if (fatal.length > 0) {
+        printMessages(fatal, "\x1B[31m\x1B[1m", "FATAL");
+      }
+      if (errors.length > 0) {
+        printMessages(errors, "\x1B[31m", "ERROR");
+      }
+      if (warnings.length > 0) {
+        printMessages(warnings, "\x1B[33m", "WARNING");
+      }
+      if (info.length > 0 && result.messages.length < 20) {
+        printMessages(info, "\x1B[36m", "INFO");
+      }
+      if (usage.length > 0) {
+        printMessages(usage, "\x1B[90m", "USAGE");
+      }
+      console.log("\u2500".repeat(60));
+      const summaryColor = result.valid ? "\x1B[32m" : "\x1B[31m";
+      const summaryIcon = result.valid ? "\u2713" : "\u2717";
+      console.log(
+        `${summaryColor}${summaryIcon} ${result.valid ? "Valid EPUB" : "Invalid EPUB"}\x1B[0m`
+      );
+      console.log();
+      console.log(`  Errors:   ${String(result.errorCount + result.fatalCount)}`);
+      console.log(`  Warnings: ${String(result.warningCount)}`);
+      if (info.length > 0) {
+        console.log(`  Info:     ${String(result.infoCount)}`);
+      }
+      if (usage.length > 0) {
+        console.log(`  Usages:   ${String(result.usageCount)}`);
+      }
+      console.log(`  Time:     ${String(elapsedMs)}ms`);
+      console.log();
+      if (result.errorCount === 0 && result.fatalCount === 0) {
+        console.log(
+          "\x1B[90mNote: This validator provides ~65% 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;
+    process.exit(shouldFail ? 1 : 0);
+  } catch (error) {
+    console.error("\x1B[31mError:\x1B[0m", error instanceof Error ? error.message : String(error));
+    if (error instanceof Error && error.stack && !values.quiet) {
+      console.error("\x1B[90m" + error.stack + "\x1B[0m");
+    }
+    process.exit(2);
+  }
+}
+void main();

package/bin/epubcheck.ts

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * EPUBCheck-TS CLI
+ *
+ * A minimalist command-line interface for EPUB validation.
+ * For full EPUBCheck features, use the official Java version:
+ * https://github.com/w3c/epubcheck
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import { basename } from 'node:path';
+
+// Dynamic import to support both ESM and CJS builds
+const { EpubCheck, toJSONReport } = await import('../dist/index.js');
+
+const VERSION = '0.2.1';
+
+// Parse command line arguments
+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 },
+  },
+  allowPositionals: true,
+  strict: false,
+});
+
+// Show version
+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 ~65% feature-complete compared to Java EPUBCheck.');
+  console.log('For production validation: https://github.com/w3c/epubcheck');
+  process.exit(0);
+}
+
+// Show help
+if (values.help || positionals.length === 0) {
+  console.log(`EPUBCheck-TS v${VERSION} - EPUB Validator
+
+Usage: epubcheck-ts <file.epub> [options]
+
+Arguments:
+  <file.epub>              Path to EPUB 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)
+  -u, --usage              Include usage messages (best practices)
+  -w, --fail-on-warnings   Exit with code 1 if warnings are found
+  -v, --version            Show version information
+  -h, --help               Show this help message
+
+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
+
+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 ~65% 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);
+}
+
+// Main validation logic
+async function main(): Promise<void> {
+  const filePath = positionals[0];
+
+  if (!filePath) {
+    console.error('Error: No EPUB file specified');
+    console.error('Run with --help for usage information');
+    process.exit(2);
+  }
+
+  try {
+    // Read EPUB file
+    if (!values.quiet) {
+      console.log(`Validating: ${basename(filePath)}`);
+      console.log();
+    }
+
+    const epubData = await readFile(filePath);
+
+    // Validate
+    const startTime = Date.now();
+    const options: {
+      profile?: 'default' | 'dict' | 'edupub' | 'idx' | 'preview';
+      includeUsage?: boolean;
+    } = {};
+    if (values.profile) {
+      options.profile = values.profile as 'default' | 'dict' | 'edupub' | 'idx' | 'preview';
+    }
+    if (values.usage) {
+      options.includeUsage = true;
+    }
+    const result = await EpubCheck.validate(epubData, options);
+    const elapsedMs = Date.now() - startTime;
+
+    // Output JSON report if requested
+    if (values.json !== undefined) {
+      const jsonContent = toJSONReport(result); // Already stringified
+
+      if (values.json === '-') {
+        // Output to stdout - suppress other output
+        if (values.quiet) {
+          console.log(jsonContent);
+        } else {
+          // If not quiet, output after other messages
+          console.log('\nJSON Report:');
+          console.log(jsonContent);
+        }
+      } else if (typeof values.json === 'string') {
+        await writeFile(values.json, jsonContent, 'utf-8');
+        if (!values.quiet) {
+          console.log(`JSON report written to: ${values.json}`);
+        }
+      }
+    }
+
+    // Console output (unless quiet mode)
+    if (!values.quiet) {
+      // Group messages by severity
+      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');
+
+      // Print messages with colors
+      const printMessages = (
+        messages: typeof result.messages,
+        color: string,
+        label: string,
+      ): void => {
+        if (messages.length === 0) return;
+
+        for (const msg of messages) {
+          const locationStr = msg.location
+            ? ` (${msg.location.path}${msg.location.line !== undefined ? `:${String(msg.location.line)}` : ''})`
+            : '';
+          console.log(`${color}${label}${locationStr}: ${msg.message}\x1b[0m`);
+          if (msg.id) {
+            console.log(`  \x1b[90mID: ${msg.id}\x1b[0m`);
+          }
+        }
+        console.log();
+      };
+
+      if (fatal.length > 0) {
+        printMessages(fatal, '\x1b[31m\x1b[1m', 'FATAL');
+      }
+      if (errors.length > 0) {
+        printMessages(errors, '\x1b[31m', 'ERROR');
+      }
+      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
+        printMessages(info, '\x1b[36m', 'INFO');
+      }
+      if (usage.length > 0) {
+        printMessages(usage, '\x1b[90m', 'USAGE');
+      }
+
+      // Summary
+      console.log('─'.repeat(60));
+      const summaryColor = result.valid ? '\x1b[32m' : '\x1b[31m';
+      const summaryIcon = result.valid ? '✓' : '✗';
+      console.log(
+        `${summaryColor}${summaryIcon} ${result.valid ? 'Valid EPUB' : 'Invalid EPUB'}\x1b[0m`,
+      );
+      console.log();
+      console.log(`  Errors:   ${String(result.errorCount + result.fatalCount)}`);
+      console.log(`  Warnings: ${String(result.warningCount)}`);
+      if (info.length > 0) {
+        console.log(`  Info:     ${String(result.infoCount)}`);
+      }
+      if (usage.length > 0) {
+        console.log(`  Usages:   ${String(result.usageCount)}`);
+      }
+      console.log(`  Time:     ${String(elapsedMs)}ms`);
+      console.log();
+
+      // Show limitation notice if there were no major errors
+      if (result.errorCount === 0 && result.fatalCount === 0) {
+        console.log(
+          '\x1b[90mNote: This validator provides ~65% coverage of Java EPUBCheck.\x1b[0m',
+        );
+        console.log('\x1b[90mFor complete validation: https://github.com/w3c/epubcheck\x1b[0m');
+        console.log();
+      }
+    }
+
+    // Determine exit code
+    const shouldFail =
+      result.errorCount > 0 ||
+      result.fatalCount > 0 ||
+      (values['fail-on-warnings'] && result.warningCount > 0);
+    process.exit(shouldFail ? 1 : 0);
+  } catch (error) {
+    console.error('\x1b[31mError:\x1b[0m', error instanceof Error ? error.message : String(error));
+    if (error instanceof Error && error.stack && !values.quiet) {
+      console.error('\x1b[90m' + error.stack + '\x1b[0m');
+    }
+    process.exit(2);
+  }
+}
+
+void main();