@likecoin/epubcheck-ts 0.4.0 → 0.5.0

package/bin/epubcheck.js

@@ -1,27 +1,55 @@
 #!/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.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 },
-    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");
@@ -39,62 +67,115 @@ 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)
   -f, --fatal              Show only fatal errors
   -e, --error              Show fatal errors and errors
-      --warn               Show fatal errors, errors, and warnings
+  -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)
-  -w, --fail-on-warnings   Exit with code 1 if warnings are found
+      --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 ~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
 `);
   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;
     }
@@ -103,7 +184,28 @@ async function main() {
       const cmContent = await readFile(values.customMessages, "utf-8");
       options.customMessages = parseCustomMessages(cmContent);
     }
-    const result = await EpubCheck.validate(epubData, options);
+    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,
@@ -116,7 +218,8 @@ async function main() {
     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;
+    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
     );
@@ -194,7 +297,8 @@ async function main() {
         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));

package/bin/epubcheck.ts

@@ -7,35 +7,88 @@
  * https://github.com/w3c/epubcheck
  */
 
-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';
-import type { EpubCheckOptions, EPUBProfile, Severity, ValidationMessage } from '../src/types.js';
+import { basename, join, relative, sep } from 'node:path';
+import type {
+  EpubCheckOptions,
+  EPUBProfile,
+  EPUBVersion,
+  Severity,
+  ValidationMessage,
+  ValidationMode,
+} from '../src/types.js';
 
 // Dynamic import to support both ESM and CJS builds
-const { EpubCheck, toJSONReport } = await import('../dist/index.js');
-
-const VERSION = '0.4.0';
-
-// 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 },
-    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 },
-    listChecks: { type: 'boolean', short: 'l', default: false },
-  },
-  allowPositionals: true,
-  strict: false,
-});
+const { EpubCheck, EPUB_VERSIONS, toJSONReport } = await import('../dist/index.js');
+
+const VERSION = '0.5.0';
+const VALID_MODES: ReadonlySet<ValidationMode> = new Set([
+  'exp',
+  'opf',
+  'xhtml',
+  'svg',
+  'nav',
+  'mo',
+]);
+
+interface CliValues {
+  json?: string;
+  quiet: boolean;
+  profile?: string;
+  mode?: string;
+  'epub-version'?: string;
+  usage: boolean;
+  fatal: boolean;
+  error: boolean;
+  warn: boolean;
+  info: boolean;
+  customMessages?: string;
+  version: boolean;
+  help: boolean;
+  'fail-on-warnings': boolean;
+  failonwarnings: boolean;
+  listChecks: boolean;
+}
+
+let values: CliValues;
+let positionals: string[];
+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,
+  }) as unknown as { values: CliValues; positionals: string[] });
+} 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);
+}
 
 // Show version
 if (values.version) {
@@ -59,70 +112,131 @@ 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)
   -f, --fatal              Show only fatal errors
   -e, --error              Show fatal errors and errors
-      --warn               Show fatal errors, errors, and warnings
+  -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)
-  -w, --fail-on-warnings   Exit with code 1 if warnings are found
+      --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 ~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
 `);
   process.exit(0);
 }
 
+/**
+ * Recursively read all files in a directory into a Map
+ */
+async function readDirectoryFiles(dirPath: string): Promise<Map<string, Uint8Array>> {
+  const files = new Map<string, Uint8Array>();
+
+  async function walk(dir: string): Promise<void> {
+    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;
+}
+
 // Main validation logic
 async function main(): Promise<void> {
   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 as ValidationMode | undefined;
+  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 as readonly string[]).includes(epubVersion)) {
+    console.error(
+      `Error: Invalid EPUB version "${epubVersion}". Valid versions: ${EPUB_VERSIONS.join(', ')}`,
+    );
+    process.exit(2);
+  }
+
+  // Single-file modes require a version
+  if (mode && mode !== 'exp' && !epubVersion) {
+    console.error(`Error: --epub-version (-v) is required when using --mode ${mode}`);
+    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();
+    // Build options
     const options: EpubCheckOptions = {};
     if (values.profile) {
       options.profile = values.profile as EPUBProfile;
     }
+    if (epubVersion) {
+      options.version = epubVersion as EPUBVersion;
+    }
+    if (mode) {
+      options.mode = mode;
+    }
     if (values.usage) {
       options.includeUsage = true;
     }
@@ -131,10 +245,41 @@ async function main(): Promise<void> {
       const cmContent = await readFile(values.customMessages, 'utf-8');
       options.customMessages = parseCustomMessages(cmContent);
     }
-    const result = await EpubCheck.validate(epubData, options);
+
+    const startTime = Date.now();
+    let result;
+
+    // Determine effective mode (auto-detect directory as expanded)
+    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;
 
-    // Most restrictive severity flag wins (--fatal overrides --error overrides --warn)
+    // Most restrictive severity flag wins (--fatal > --error > --warn > --info)
     const severityRank: Record<Severity, number> = {
       fatal: 0,
       error: 1,
@@ -146,7 +291,8 @@ async function main(): Promise<void> {
     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;
+    else if (values.info) maxRank = 3;
+    const isFiltered = values.fatal || values.error || values.warn || values.info;
     const displayMessages = result.messages.filter(
       (m: ValidationMessage) => severityRank[m.severity] <= maxRank,
     );
@@ -248,10 +394,9 @@ async function main(): Promise<void> {
     }
 
     // Determine exit code
+    const failOnWarnings = values['fail-on-warnings'] || values.failonwarnings;
     const shouldFail =
-      result.errorCount > 0 ||
-      result.fatalCount > 0 ||
-      (values['fail-on-warnings'] && result.warningCount > 0);
+      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));