@likecoin/epubcheck-ts 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -1649,6 +1649,8 @@ interface ManifestItem {
     mediaType: string;
     /** Fallback item ID for non-standard media types */
     fallback?: string;
+    /** Fallback stylesheet item ID (EPUB 2 only) */
+    fallbackStyle?: string;
     /** Media overlay ID */
     mediaOverlay?: string;
     /** Item properties (EPUB 3) - e.g., 'nav', 'scripted', 'svg', 'remote-resources' */
@@ -1731,6 +1733,8 @@ interface LinkElement {
 interface PackageDocument {
     /** EPUB version from package@version */
     version: EPUBVersion;
+    /** Whether the package@version attribute was present in the source (omitted = true) */
+    versionDeclared?: boolean;
     /** Unique identifier reference (package@unique-identifier) */
     uniqueIdentifier: string;
     /** Package prefix declarations (EPUB 3) */
@@ -1772,6 +1776,10 @@ interface Collection {
     name?: string;
     /** Resource hrefs in this collection (from link elements) */
     links: string[];
+    /** Nested sub-collections (EPUB 3) */
+    children: Collection[];
+    /** Raw XML inside this collection's tags (used for targeted sub-checks) */
+    innerXml?: string;
 }
 
 /**
@@ -1781,11 +1789,16 @@ type Severity = 'fatal' | 'error' | 'warning' | 'info' | 'usage';
 /**
  * Supported EPUB versions
  */
-type EPUBVersion = '2.0' | '3.0' | '3.1' | '3.2' | '3.3';
+declare const EPUB_VERSIONS: readonly ["2.0", "3.0", "3.1", "3.2", "3.3"];
+type EPUBVersion = (typeof EPUB_VERSIONS)[number];
 /**
  * EPUB validation profiles
  */
 type EPUBProfile = 'default' | 'edupub' | 'idx' | 'dict' | 'preview';
+/**
+ * Validation modes for single-file and expanded directory validation
+ */
+type ValidationMode = 'exp' | 'opf' | 'xhtml' | 'svg' | 'nav' | 'mo';
 /**
  * Location within an EPUB file
  */
@@ -1845,6 +1858,8 @@ interface EpubCheckOptions {
     version?: EPUBVersion;
     /** Validation profile */
     profile?: EPUBProfile;
+    /** Validation mode for single-file or expanded directory validation */
+    mode?: ValidationMode;
     /** Whether to include usage messages */
     includeUsage?: boolean;
     /** Whether to include info messages */
@@ -1856,6 +1871,10 @@ interface EpubCheckOptions {
     /** Custom message severity overrides (message ID → severity) */
     customMessages?: Map<string, MessageSeverity>;
 }
+/**
+ * EpubCheckOptions with all fields required except mode (which is inherently optional)
+ */
+type ResolvedEpubCheckOptions = Required<Omit<EpubCheckOptions, 'mode'>> & Pick<EpubCheckOptions, 'mode'>;
 /**
  * Internal validation context passed through the validation pipeline
  */
@@ -1863,7 +1882,7 @@ interface ValidationContext {
     /** EPUB file data */
     data: Uint8Array;
     /** Validation options */
-    options: Required<EpubCheckOptions>;
+    options: ResolvedEpubCheckOptions;
     /** Detected EPUB version */
     version: EPUBVersion;
     /** Validation messages collected so far */
@@ -1954,17 +1973,42 @@ declare class EpubCheck {
      * Validate an EPUB file
      *
      * @param data - The EPUB file as a Uint8Array
+     * @param filename - Optional filename, used for file-extension checks (PKG-016/017/024)
+     * @returns Validation result
+     */
+    check(data: Uint8Array, filename?: string): Promise<EpubCheckResult>;
+    /**
+     * Validate an expanded EPUB directory (pre-read file map)
+     *
+     * @param files - Map of relative file paths to their content
      * @returns Validation result
      */
-    check(data: Uint8Array): Promise<EpubCheckResult>;
+    checkExpanded(files: Map<string, Uint8Array>): Promise<EpubCheckResult>;
+    /**
+     * Validate a single file (OPF, XHTML, etc.) without a full EPUB container
+     *
+     * @param data - The file content
+     * @param filename - The filename (used for path in messages)
+     * @returns Validation result
+     */
+    checkSingleFile(data: Uint8Array, filename: string): Promise<EpubCheckResult>;
     /**
      * Static method to validate an EPUB file with default options
      *
      * @param data - The EPUB file as a Uint8Array
      * @param options - Optional validation options
+     * @param filename - Optional filename, used for file-extension checks
      * @returns Validation result
      */
-    static validate(data: Uint8Array, options?: EpubCheckOptions): Promise<EpubCheckResult>;
+    static validate(data: Uint8Array, options?: EpubCheckOptions, filename?: string): Promise<EpubCheckResult>;
+    /**
+     * Static method to validate an expanded EPUB (pre-read file map)
+     */
+    static validateExpanded(files: Map<string, Uint8Array>, options?: EpubCheckOptions): Promise<EpubCheckResult>;
+    /**
+     * Static method to validate a single file
+     */
+    static validateSingleFile(data: Uint8Array, filename: string, options?: EpubCheckOptions): Promise<EpubCheckResult>;
     /**
      * Get the current EPUB version being validated against
      */
@@ -1993,6 +2037,42 @@ declare class EpubCheck {
      * Check if a manifest item has a fallback chain reaching a Core Media Type
      */
     private hasCMTFallback;
+    /**
+     * Shared validation pipeline (Steps 2-7) used by both check() and checkExpanded()
+     */
+    private runPipeline;
+    /**
+     * Check DOCTYPE external identifiers (OPF-073).
+     *
+     * Mirrors Java's DeclarationHandler: external identifiers (PUBLIC/SYSTEM)
+     * must not appear in DOCTYPE declarations except for specific media-type
+     * combinations (SVG 1.1, MathML 3.0, NCX 2005-1).
+     */
+    private checkExternalIdentifiers;
+    /**
+     * Check file extension for EPUB naming conventions.
+     *
+     * Mirrors Java's OCFExtensionChecker (src/main/java/com/adobe/epubcheck/ocf/OCFExtensionChecker.java):
+     * - PKG-016 (warning): case-variant of "epub" (e.g. ".ePub", ".EPUB")
+     * - PKG-017 (EPUB 2) / PKG-024 (EPUB 3): non-epub extension
+     */
+    private checkFilenameExtension;
+    /**
+     * Build a filtered report from validation context
+     */
+    private buildFilteredReport;
+    /**
+     * Validate mimetype file content for expanded EPUB (no ZIP-specific checks)
+     */
+    private validateExpandedMimetype;
+    /**
+     * Parse container.xml from context.files to find rootfiles and opfPath
+     */
+    private parseContainerXml;
+    /**
+     * Validate filenames for expanded EPUB
+     */
+    private validateExpandedFilenames;
 }
 
 /**
@@ -2038,4 +2118,4 @@ interface SchemaValidator {
     dispose(): void;
 }
 
-export { type CreateMessageOptions, type EPUBProfile, type EPUBVersion, EpubCheck, type EpubCheckOptions, type EpubCheckResult, MessageId, type MessageInfo, type MessageSeverity, type SchemaValidator, type Severity, type ValidationContext, type ValidationMessage, buildReport, countBySeverity, createMessage, filterByPath, filterBySeverity, formatMessageList, formatMessages, getAllMessages, getDefaultSeverity, getMessageInfo, parseCustomMessages, pushMessage, toJSONReport };
+export { type CreateMessageOptions, type EPUBProfile, type EPUBVersion, EPUB_VERSIONS, EpubCheck, type EpubCheckOptions, type EpubCheckResult, MessageId, type MessageInfo, type MessageSeverity, type ResolvedEpubCheckOptions, type SchemaValidator, type Severity, type ValidationContext, type ValidationMessage, type ValidationMode, buildReport, countBySeverity, createMessage, filterByPath, filterBySeverity, formatMessageList, formatMessages, getAllMessages, getDefaultSeverity, getMessageInfo, parseCustomMessages, pushMessage, toJSONReport };

package/dist/index.d.ts

@@ -1649,6 +1649,8 @@ interface ManifestItem {
     mediaType: string;
     /** Fallback item ID for non-standard media types */
     fallback?: string;
+    /** Fallback stylesheet item ID (EPUB 2 only) */
+    fallbackStyle?: string;
     /** Media overlay ID */
     mediaOverlay?: string;
     /** Item properties (EPUB 3) - e.g., 'nav', 'scripted', 'svg', 'remote-resources' */
@@ -1731,6 +1733,8 @@ interface LinkElement {
 interface PackageDocument {
     /** EPUB version from package@version */
     version: EPUBVersion;
+    /** Whether the package@version attribute was present in the source (omitted = true) */
+    versionDeclared?: boolean;
     /** Unique identifier reference (package@unique-identifier) */
     uniqueIdentifier: string;
     /** Package prefix declarations (EPUB 3) */
@@ -1772,6 +1776,10 @@ interface Collection {
     name?: string;
     /** Resource hrefs in this collection (from link elements) */
     links: string[];
+    /** Nested sub-collections (EPUB 3) */
+    children: Collection[];
+    /** Raw XML inside this collection's tags (used for targeted sub-checks) */
+    innerXml?: string;
 }
 
 /**
@@ -1781,11 +1789,16 @@ type Severity = 'fatal' | 'error' | 'warning' | 'info' | 'usage';
 /**
  * Supported EPUB versions
  */
-type EPUBVersion = '2.0' | '3.0' | '3.1' | '3.2' | '3.3';
+declare const EPUB_VERSIONS: readonly ["2.0", "3.0", "3.1", "3.2", "3.3"];
+type EPUBVersion = (typeof EPUB_VERSIONS)[number];
 /**
  * EPUB validation profiles
  */
 type EPUBProfile = 'default' | 'edupub' | 'idx' | 'dict' | 'preview';
+/**
+ * Validation modes for single-file and expanded directory validation
+ */
+type ValidationMode = 'exp' | 'opf' | 'xhtml' | 'svg' | 'nav' | 'mo';
 /**
  * Location within an EPUB file
  */
@@ -1845,6 +1858,8 @@ interface EpubCheckOptions {
     version?: EPUBVersion;
     /** Validation profile */
     profile?: EPUBProfile;
+    /** Validation mode for single-file or expanded directory validation */
+    mode?: ValidationMode;
     /** Whether to include usage messages */
     includeUsage?: boolean;
     /** Whether to include info messages */
@@ -1856,6 +1871,10 @@ interface EpubCheckOptions {
     /** Custom message severity overrides (message ID → severity) */
     customMessages?: Map<string, MessageSeverity>;
 }
+/**
+ * EpubCheckOptions with all fields required except mode (which is inherently optional)
+ */
+type ResolvedEpubCheckOptions = Required<Omit<EpubCheckOptions, 'mode'>> & Pick<EpubCheckOptions, 'mode'>;
 /**
  * Internal validation context passed through the validation pipeline
  */
@@ -1863,7 +1882,7 @@ interface ValidationContext {
     /** EPUB file data */
     data: Uint8Array;
     /** Validation options */
-    options: Required<EpubCheckOptions>;
+    options: ResolvedEpubCheckOptions;
     /** Detected EPUB version */
     version: EPUBVersion;
     /** Validation messages collected so far */
@@ -1954,17 +1973,42 @@ declare class EpubCheck {
      * Validate an EPUB file
      *
      * @param data - The EPUB file as a Uint8Array
+     * @param filename - Optional filename, used for file-extension checks (PKG-016/017/024)
+     * @returns Validation result
+     */
+    check(data: Uint8Array, filename?: string): Promise<EpubCheckResult>;
+    /**
+     * Validate an expanded EPUB directory (pre-read file map)
+     *
+     * @param files - Map of relative file paths to their content
      * @returns Validation result
      */
-    check(data: Uint8Array): Promise<EpubCheckResult>;
+    checkExpanded(files: Map<string, Uint8Array>): Promise<EpubCheckResult>;
+    /**
+     * Validate a single file (OPF, XHTML, etc.) without a full EPUB container
+     *
+     * @param data - The file content
+     * @param filename - The filename (used for path in messages)
+     * @returns Validation result
+     */
+    checkSingleFile(data: Uint8Array, filename: string): Promise<EpubCheckResult>;
     /**
      * Static method to validate an EPUB file with default options
      *
      * @param data - The EPUB file as a Uint8Array
      * @param options - Optional validation options
+     * @param filename - Optional filename, used for file-extension checks
      * @returns Validation result
      */
-    static validate(data: Uint8Array, options?: EpubCheckOptions): Promise<EpubCheckResult>;
+    static validate(data: Uint8Array, options?: EpubCheckOptions, filename?: string): Promise<EpubCheckResult>;
+    /**
+     * Static method to validate an expanded EPUB (pre-read file map)
+     */
+    static validateExpanded(files: Map<string, Uint8Array>, options?: EpubCheckOptions): Promise<EpubCheckResult>;
+    /**
+     * Static method to validate a single file
+     */
+    static validateSingleFile(data: Uint8Array, filename: string, options?: EpubCheckOptions): Promise<EpubCheckResult>;
     /**
      * Get the current EPUB version being validated against
      */
@@ -1993,6 +2037,42 @@ declare class EpubCheck {
      * Check if a manifest item has a fallback chain reaching a Core Media Type
      */
     private hasCMTFallback;
+    /**
+     * Shared validation pipeline (Steps 2-7) used by both check() and checkExpanded()
+     */
+    private runPipeline;
+    /**
+     * Check DOCTYPE external identifiers (OPF-073).
+     *
+     * Mirrors Java's DeclarationHandler: external identifiers (PUBLIC/SYSTEM)
+     * must not appear in DOCTYPE declarations except for specific media-type
+     * combinations (SVG 1.1, MathML 3.0, NCX 2005-1).
+     */
+    private checkExternalIdentifiers;
+    /**
+     * Check file extension for EPUB naming conventions.
+     *
+     * Mirrors Java's OCFExtensionChecker (src/main/java/com/adobe/epubcheck/ocf/OCFExtensionChecker.java):
+     * - PKG-016 (warning): case-variant of "epub" (e.g. ".ePub", ".EPUB")
+     * - PKG-017 (EPUB 2) / PKG-024 (EPUB 3): non-epub extension
+     */
+    private checkFilenameExtension;
+    /**
+     * Build a filtered report from validation context
+     */
+    private buildFilteredReport;
+    /**
+     * Validate mimetype file content for expanded EPUB (no ZIP-specific checks)
+     */
+    private validateExpandedMimetype;
+    /**
+     * Parse container.xml from context.files to find rootfiles and opfPath
+     */
+    private parseContainerXml;
+    /**
+     * Validate filenames for expanded EPUB
+     */
+    private validateExpandedFilenames;
 }
 
 /**
@@ -2038,4 +2118,4 @@ interface SchemaValidator {
     dispose(): void;
 }
 
-export { type CreateMessageOptions, type EPUBProfile, type EPUBVersion, EpubCheck, type EpubCheckOptions, type EpubCheckResult, MessageId, type MessageInfo, type MessageSeverity, type SchemaValidator, type Severity, type ValidationContext, type ValidationMessage, buildReport, countBySeverity, createMessage, filterByPath, filterBySeverity, formatMessageList, formatMessages, getAllMessages, getDefaultSeverity, getMessageInfo, parseCustomMessages, pushMessage, toJSONReport };
+export { type CreateMessageOptions, type EPUBProfile, type EPUBVersion, EPUB_VERSIONS, EpubCheck, type EpubCheckOptions, type EpubCheckResult, MessageId, type MessageInfo, type MessageSeverity, type ResolvedEpubCheckOptions, type SchemaValidator, type Severity, type ValidationContext, type ValidationMessage, type ValidationMode, buildReport, countBySeverity, createMessage, filterByPath, filterBySeverity, formatMessageList, formatMessages, getAllMessages, getDefaultSeverity, getMessageInfo, parseCustomMessages, pushMessage, toJSONReport };