@likecoin/epubcheck-ts 0.2.3 → 0.2.4

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 (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!
+> **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 (467 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!
 
 ## 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 ~65% of EPUBCheck feature parity
+- **Partial EPUB validation**: Currently ~70% 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 ~65% 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 ~70% coverage of Java EPUBCheck features. For complete EPUB 3 conformance testing, use the [official Java EPUBCheck](https://github.com/w3c/epubcheck).
 
 ### ES Modules (recommended)
 
@@ -268,16 +268,16 @@ This library is a TypeScript port of the Java-based [EPUBCheck](https://github.c
 | 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 |
+| 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 |
-| Accessibility Checks | 🟡 Partial | ~75% | Empty links, image alt, SVG titles, MathML alttext |
+| 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: ~65% of Java EPUBCheck features**
+**Overall Progress: ~70% of Java EPUBCheck features**
 
 See [PROJECT_STATUS.md](./PROJECT_STATUS.md) for detailed comparison.
 
@@ -357,8 +357,8 @@ Legend: ✅ Implemented
 | Aspect | epubcheck-ts | EPUBCheck (Java) |
 |--------|--------------|------------------|
 | Runtime | Node.js / Browser | JVM |
-| Feature Parity | ~65% | 100% |
-| Bundle Size | ~55KB JS + ~1.5MB WASM | ~15MB |
+| Feature Parity | ~70% | 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 |

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.2.3";
+const VERSION = "0.2.4";
 const { values, positionals } = parseArgs({
   options: {
     json: { type: "string", short: "j" },
@@ -21,7 +21,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 ~65% feature-complete compared to Java EPUBCheck.");
+  console.log("Note: This is ~70% feature-complete compared to Java EPUBCheck.");
   console.log("For production validation: https://github.com/w3c/epubcheck");
   process.exit(0);
 }
@@ -53,7 +53,7 @@ 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 ~65% coverage of Java EPUBCheck features.
+Note: This tool provides ~70% 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
 
@@ -153,7 +153,7 @@ async function main() {
       console.log();
       if (result.errorCount === 0 && result.fatalCount === 0) {
         console.log(
-          "\x1B[90mNote: This validator provides ~65% coverage of Java EPUBCheck.\x1B[0m"
+          "\x1B[90mNote: This validator provides ~70% 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

@@ -14,7 +14,7 @@ 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.3';
+const VERSION = '0.2.4';
 
 // Parse command line arguments
 const { values, positionals } = parseArgs({
@@ -36,7 +36,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 ~65% feature-complete compared to Java EPUBCheck.');
+  console.log('Note: This is ~70% feature-complete compared to Java EPUBCheck.');
   console.log('For production validation: https://github.com/w3c/epubcheck');
   process.exit(0);
 }
@@ -70,7 +70,7 @@ 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 ~65% coverage of Java EPUBCheck features.
+Note: This tool provides ~70% 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
 
@@ -204,7 +204,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 ~65% coverage of Java EPUBCheck.\x1b[0m',
+          '\x1b[90mNote: This validator provides ~70% coverage of Java EPUBCheck.\x1b[0m',
         );
         console.log('\x1b[90mFor complete validation: https://github.com/w3c/epubcheck\x1b[0m');
         console.log();

package/dist/index.cjs

@@ -64,8 +64,61 @@ var CSSValidator = class {
     this.checkDiscouragedProperties(context, ast, resourcePath);
     this.checkAtRules(context, ast, resourcePath, result);
     this.checkMediaOverlayClasses(context, ast, resourcePath);
+    this.extractUrlReferences(context, ast, resourcePath, result);
     return result;
   }
+  extractUrlReferences(context, ast, resourcePath, result) {
+    cssTree.walk(ast, (node) => {
+      if (node.type === "Atrule") {
+        const atRule = node;
+        if (atRule.name === "font-face") {
+          return;
+        }
+        if (atRule.block) {
+          cssTree.walk(atRule.block, (blockNode) => {
+            if (blockNode.type === "Declaration") {
+              this.processDeclarationForUrl(blockNode, resourcePath, result);
+            }
+          });
+        }
+      } else if (node.type === "Rule") {
+        const rule = node;
+        cssTree.walk(rule.block, (blockNode) => {
+          if (blockNode.type === "Declaration") {
+            this.processDeclarationForUrl(blockNode, resourcePath, result);
+          }
+        });
+      }
+    });
+  }
+  processDeclarationForUrl(declaration, resourcePath, result) {
+    const property = declaration.property.toLowerCase();
+    cssTree.walk(declaration.value, (valueNode) => {
+      if (valueNode.type === "Url") {
+        const urlValue = this.extractUrlValue(valueNode);
+        if (urlValue && !urlValue.startsWith("data:")) {
+          const loc = valueNode.loc;
+          const start = loc?.start;
+          if (start) {
+            start.line;
+            start.column;
+          }
+          let refType = "resource";
+          if (property.includes("font")) {
+            refType = "font";
+          } else if (property.includes("background") || property.includes("list-style") || property.includes("content") || property.includes("border-image") || property.includes("mask")) {
+            refType = "image";
+          }
+          result.references.push({
+            url: urlValue,
+            type: refType,
+            line: start?.line,
+            column: start?.column
+          });
+        }
+      }
+    });
+  }
   /**
    * Check for forbidden and discouraged CSS properties in EPUB
    */
@@ -434,6 +487,104 @@ function isPublicationResourceReference(type) {
 
 // src/content/validator.ts
 var DISCOURAGED_ELEMENTS = /* @__PURE__ */ new Set(["base", "embed"]);
+var HTML_ENTITIES = /* @__PURE__ */ new Set([
+  "nbsp",
+  "iexcl",
+  "cent",
+  "pound",
+  "curren",
+  "yen",
+  "brvbar",
+  "sect",
+  "uml",
+  "copy",
+  "ordf",
+  "laquo",
+  "not",
+  "shy",
+  "reg",
+  "macr",
+  "deg",
+  "plusmn",
+  "sup2",
+  "sup3",
+  "acute",
+  "micro",
+  "para",
+  "middot",
+  "cedil",
+  "sup1",
+  "ordm",
+  "raquo",
+  "frac14",
+  "frac12",
+  "frac34",
+  "iquest",
+  "Agrave",
+  "Aacute",
+  "Acirc",
+  "Atilde",
+  "Auml",
+  "Aring",
+  "AElig",
+  "Ccedil",
+  "Egrave",
+  "Eacute",
+  "Ecirc",
+  "Euml",
+  "Igrave",
+  "Iacute",
+  "Icirc",
+  "Iuml",
+  "ETH",
+  "Ntilde",
+  "Ograve",
+  "Oacute",
+  "Ocirc",
+  "Otilde",
+  "Ouml",
+  "times",
+  "Oslash",
+  "Ugrave",
+  "Uacute",
+  "Ucirc",
+  "Uuml",
+  "Yacute",
+  "THORN",
+  "szlig",
+  "agrave",
+  "aacute",
+  "acirc",
+  "atilde",
+  "auml",
+  "aring",
+  "aelig",
+  "ccedil",
+  "egrave",
+  "eacute",
+  "ecirc",
+  "euml",
+  "igrave",
+  "iacute",
+  "icirc",
+  "iuml",
+  "eth",
+  "ntilde",
+  "ograve",
+  "oacute",
+  "ocirc",
+  "otilde",
+  "ouml",
+  "divide",
+  "oslash",
+  "ugrave",
+  "uacute",
+  "ucirc",
+  "uuml",
+  "yacute",
+  "thorn",
+  "yuml"
+]);
 var ContentValidator = class {
   validate(context, registry, refValidator) {
     const packageDoc = context.packageDocument;
@@ -459,7 +610,31 @@ var ContentValidator = class {
     }
     const cssContent = new TextDecoder().decode(cssData);
     const cssValidator = new CSSValidator();
-    cssValidator.validate(context, cssContent, path);
+    const result = cssValidator.validate(context, cssContent, path);
+    const cssDir = path.includes("/") ? path.substring(0, path.lastIndexOf("/")) : "";
+    for (const ref of result.references) {
+      if (ref.type === "font") {
+        const resolvedPath = this.resolveRelativePath(cssDir, ref.url, opfDir);
+        const hashIndex = resolvedPath.indexOf("#");
+        const targetResource = hashIndex >= 0 ? resolvedPath.slice(0, hashIndex) : resolvedPath;
+        refValidator.addReference({
+          url: ref.url,
+          targetResource,
+          type: "font" /* FONT */,
+          location: { path }
+        });
+      } else if (ref.type === "image") {
+        const resolvedPath = this.resolveRelativePath(cssDir, ref.url, opfDir);
+        const hashIndex = resolvedPath.indexOf("#");
+        const targetResource = hashIndex >= 0 ? resolvedPath.slice(0, hashIndex) : resolvedPath;
+        refValidator.addReference({
+          url: ref.url,
+          targetResource,
+          type: "image" /* IMAGE */,
+          location: { path }
+        });
+      }
+    }
     this.extractCSSImports(path, cssContent, opfDir, refValidator);
   }
   validateXHTMLDocument(context, path, itemId, opfDir, registry, refValidator) {
@@ -479,19 +654,26 @@ var ContentValidator = class {
     } catch (error) {
       if (error instanceof Error) {
         const { message, line, column } = this.parseLibxmlError(error.message);
-        const location = { path };
-        if (line !== void 0) {
-          location.line = line;
-        }
-        if (column !== void 0) {
-          location.column = column;
+        const entityPattern = /Entity '(\w+)' not defined/;
+        const entityExec = entityPattern.exec(error.message);
+        const entityName = entityExec?.[1];
+        const isKnownHtmlEntity = entityName !== void 0 && HTML_ENTITIES.has(entityName);
+        const isEpub2 = context.version === "2.0";
+        if (!isEpub2 || !isKnownHtmlEntity) {
+          const location = { path };
+          if (line !== void 0) {
+            location.line = line;
+          }
+          if (column !== void 0) {
+            location.column = column;
+          }
+          context.messages.push({
+            id: "HTM-004",
+            severity: "error",
+            message,
+            location
+          });
         }
-        context.messages.push({
-          id: "HTM-004",
-          severity: "error",
-          message,
-          location
-        });
       }
       return;
     }
@@ -2558,6 +2740,7 @@ var OPFValidator = class {
     context.packageDocument = this.packageDoc;
     this.validatePackageAttributes(context, opfPath);
     this.validateMetadata(context, opfPath);
+    this.validateLinkElements(context, opfPath);
     this.validateManifest(context, opfPath);
     this.validateSpine(context, opfPath);
     this.validateFallbackChains(context, opfPath);
@@ -2809,6 +2992,34 @@ var OPFValidator = class {
       }
     }
   }
+  /**
+   * Validate EPUB 3 link elements in metadata
+   */
+  validateLinkElements(context, opfPath) {
+    if (!this.packageDoc) return;
+    const opfDir = opfPath.includes("/") ? opfPath.substring(0, opfPath.lastIndexOf("/")) : "";
+    for (const link of this.packageDoc.linkElements) {
+      const href = link.href;
+      const decodedHref = tryDecodeUriComponent(href);
+      const basePath = href.includes("#") ? href.substring(0, href.indexOf("#")) : href;
+      const basePathDecoded = decodedHref.includes("#") ? decodedHref.substring(0, decodedHref.indexOf("#")) : decodedHref;
+      if (href.startsWith("#")) {
+        continue;
+      }
+      const resolvedPath = resolvePath(opfDir, basePath);
+      const resolvedPathDecoded = basePathDecoded !== basePath ? resolvePath(opfDir, basePathDecoded) : resolvedPath;
+      const fileExists = context.files.has(resolvedPath) || context.files.has(resolvedPathDecoded);
+      const inManifest = this.manifestByHref.has(basePath) || this.manifestByHref.has(basePathDecoded);
+      if (!fileExists && !inManifest) {
+        context.messages.push({
+          id: "RSC-007",
+          severity: "warning",
+          message: `Referenced resource "${resolvedPath}" could not be found in the EPUB`,
+          location: { path: opfPath }
+        });
+      }
+    }
+  }
   /**
    * Validate manifest section
    */
@@ -2836,7 +3047,28 @@ var OPFValidator = class {
       }
       seenHrefs.add(item.href);
       const fullPath = resolvePath(opfPath, item.href);
-      if (!context.files.has(fullPath) && !item.href.startsWith("http")) {
+      if (fullPath === opfPath) {
+        context.messages.push({
+          id: "OPF-099",
+          severity: "error",
+          message: "The manifest must not list the package document",
+          location: { path: opfPath }
+        });
+      }
+      if (!item.href.startsWith("http") && !item.href.startsWith("mailto:")) {
+        const leaked = checkUrlLeaking(item.href);
+        if (leaked) {
+          context.messages.push({
+            id: "RSC-026",
+            severity: "error",
+            message: `URL "${item.href}" leaks outside the container (it is not a valid-relative-ocf-URL-with-fragment string)`,
+            location: { path: opfPath }
+          });
+        }
+      }
+      const decodedHref = tryDecodeUriComponent(item.href);
+      const fullPathDecoded = decodedHref !== item.href ? resolvePath(opfPath, decodedHref) : fullPath;
+      if (!context.files.has(fullPath) && !context.files.has(fullPathDecoded) && !item.href.startsWith("http")) {
         context.messages.push({
           id: "RSC-001",
           severity: "error",
@@ -3188,6 +3420,24 @@ function resolvePath(basePath, relativePath) {
   }
   return parts.join("/");
 }
+function tryDecodeUriComponent(encoded) {
+  try {
+    return decodeURIComponent(encoded);
+  } catch {
+    return encoded;
+  }
+}
+function checkUrlLeaking(href) {
+  const TEST_BASE_A = "https://a.example.org/A/";
+  const TEST_BASE_B = "https://b.example.org/B/";
+  try {
+    const urlA = new URL(href, TEST_BASE_A).toString();
+    const urlB = new URL(href, TEST_BASE_B).toString();
+    return !urlA.startsWith(TEST_BASE_A) || !urlB.startsWith(TEST_BASE_B);
+  } catch {
+    return false;
+  }
+}
 function isValidMimeType(mediaType) {
   const mimeTypePattern = /^[a-zA-Z][a-zA-Z0-9!#$&\-^_.]*\/[a-zA-Z0-9][a-zA-Z0-9!#$&\-^_.+]*(?:\s*;\s*[a-zA-Z0-9-]+=[^;]+)?$/;
   if (!mimeTypePattern.test(mediaType)) {
@@ -4168,6 +4418,7 @@ var MessageId = /* @__PURE__ */ ((MessageId2) => {
   MessageId2["OPF_013"] = "OPF-013";
   MessageId2["OPF_014"] = "OPF-014";
   MessageId2["OPF_097"] = "OPF-097";
+  MessageId2["OPF_099"] = "OPF-099";
   MessageId2["OPF_015"] = "OPF-015";
   MessageId2["RSC_001"] = "RSC-001";
   MessageId2["RSC_002"] = "RSC-002";