@likecoin/epubcheck-ts 0.3.3 → 0.3.5

package/README.md

@@ -6,13 +6,13 @@ 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 (505 tests) and ~70% 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!
+> **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 (618 tests) and ~75% 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 ~70% of EPUBCheck feature parity
+- **Partial EPUB validation**: Currently ~75% 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
@@ -70,7 +70,7 @@ epubcheck-ts book.epub --quiet --fail-on-warnings
 epubcheck-ts dictionary.epub --profile dict
 ```
 
-**Note:** This CLI provides ~70% coverage of Java EPUBCheck features. For complete EPUB 3 conformance testing, use the [official Java EPUBCheck](https://github.com/w3c/epubcheck).
+**Note:** This CLI provides ~75% coverage of Java EPUBCheck features. For complete EPUB 3 conformance testing, use the [official Java EPUBCheck](https://github.com/w3c/epubcheck).
 
 ### ES Modules (recommended)
 
@@ -133,6 +133,8 @@ fileInput.addEventListener('change', async (event) => {
 
 ## API
 
+> Full API reference: [online](https://likecoin.github.io/epubcheck-ts/docs/) | [markdown](./docs/md/globals.md)
+
 ### `EpubCheck.validate(data, options?)`
 
 Static method to validate an EPUB file.
@@ -264,20 +266,20 @@ This library is a TypeScript port of the Java-based [EPUBCheck](https://github.c
 
 | Component | Status | Completeness | Notes |
 |-----------|--------|--------------|-------|
-| 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 |
+| 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 | ~80% | XHTML structure, CSS url(), @import, SVG, script detection |
+| 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 | ~50% | @font-face, @import, media overlay classes, position warnings |
-| Cross-reference Validation | 🟡 Partial | ~75% | Reference tracking, fragment validation, undeclared resources |
+| CSS | 🟡 Partial | ~70% | @font-face, @import, url() extraction, position, forbidden properties |
+| Cross-reference Validation | 🟡 Partial | ~80% | 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 |
 | Media Validation | ❌ Not Started | 0% | Planned |
 
 Legend: 🟢 Complete | 🟡 Partial | 🔴 Basic | ❌ Not Started
 
-**Overall Progress: ~70% of Java EPUBCheck features**
+**Overall Progress: ~75% of Java EPUBCheck features**
 
 See [PROJECT_STATUS.md](./PROJECT_STATUS.md) for detailed comparison.
 
@@ -319,6 +321,9 @@ npm run build
 | `npm run format` | Format with Biome |
 | `npm run typecheck` | TypeScript type checking |
 | `npm run check` | Run all checks (format + typecheck) |
+| `npm run docs` | Generate API docs (HTML + Markdown) |
+| `npm run docs:html` | Generate HTML API docs to `docs/html/` |
+| `npm run docs:md` | Generate Markdown API docs to `docs/md/` |
 
 ### Project Structure
 
@@ -345,6 +350,8 @@ epubcheck-ts/
 ├── test/
 │   ├── fixtures/          # Test EPUB files
 │   └── integration/       # Integration tests
+├── docs/
+│   └── md/                # Generated API docs (Markdown, checked in)
 ├── examples/
 │   └── web/               # Web demo ✅
 └── dist/                  # Build output
@@ -357,7 +364,7 @@ Legend: ✅ Implemented
 | Aspect | epubcheck-ts | EPUBCheck (Java) |
 |--------|--------------|------------------|
 | Runtime | Node.js / Browser | JVM |
-| Feature Parity | ~70% | 100% |
+| Feature Parity | ~75% | 100% |
 | Bundle Size | ~450KB JS + ~1.6MB WASM | ~15MB |
 | Installation | `npm install` | Download JAR |
 | Integration | Native JS/TS | CLI or Java API |

package/bin/epubcheck.js

@@ -3,7 +3,7 @@ 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.3";
+const VERSION = "0.3.5";
 const { values, positionals } = parseArgs({
   options: {
     json: { type: "string", short: "j" },
@@ -111,9 +111,7 @@ 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 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) => {

package/bin/epubcheck.ts

@@ -10,11 +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';
 
 // Dynamic import to support both ESM and CJS builds
 const { EpubCheck, toJSONReport } = await import('../dist/index.js');
 
-const VERSION = '0.3.3';
+const VERSION = '0.3.5';
 
 // Parse command line arguments
 const { values, positionals } = parseArgs({
@@ -110,12 +111,9 @@ async function main(): Promise<void> {
 
     // Validate
     const startTime = Date.now();
-    const options: {
-      profile?: 'default' | 'dict' | 'edupub' | 'idx' | 'preview';
-      includeUsage?: boolean;
-    } = {};
+    const options: EpubCheckOptions = {};
     if (values.profile) {
-      options.profile = values.profile as 'default' | 'dict' | 'edupub' | 'idx' | 'preview';
+      options.profile = values.profile as EPUBProfile;
     }
     if (values.usage) {
       options.includeUsage = true;
@@ -147,13 +145,11 @@ async function main(): Promise<void> {
     // Console output (unless quiet mode)
     if (!values.quiet) {
       // Group messages by severity
-      const fatal = result.messages.filter((m: { severity: string }) => m.severity === 'fatal');
-      const errors = result.messages.filter((m: { severity: string }) => m.severity === 'error');
-      const warnings = result.messages.filter(
-        (m: { severity: string }) => m.severity === 'warning',
-      );
-      const info = result.messages.filter((m: { severity: string }) => m.severity === 'info');
-      const usage = result.messages.filter((m: { severity: string }) => m.severity === 'usage');
+      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');
 
       // Print messages with colors
       const printMessages = (