@likecoin/epubcheck-ts 0.3.9 → 0.5.0

package/dist/index.d.cts

@@ -1,363 +1,3 @@
-/**
- * Represents a manifest item in the OPF
- */
-interface ManifestItem {
-    /** Unique identifier for this item */
-    id: string;
-    /** Path relative to the OPF file */
-    href: string;
-    /** MIME media type */
-    mediaType: string;
-    /** Fallback item ID for non-standard media types */
-    fallback?: string;
-    /** Media overlay ID */
-    mediaOverlay?: string;
-    /** Item properties (EPUB 3) - e.g., 'nav', 'scripted', 'svg', 'remote-resources' */
-    properties?: string[];
-}
-/**
- * Represents a spine itemref in the OPF
- */
-interface SpineItemRef {
-    /** Optional ID attribute on the itemref element */
-    id?: string;
-    /** Reference to manifest item ID */
-    idref: string;
-    /** Whether this item is part of the linear reading order */
-    linear: boolean;
-    /** Itemref properties (EPUB 3) - e.g., 'page-spread-left', 'page-spread-right' */
-    properties?: string[];
-}
-/**
- * Represents a guide reference (EPUB 2)
- */
-interface GuideReference {
-    /** Type of reference (cover, toc, etc.) */
-    type: string;
-    /** Title for display */
-    title?: string;
-    /** Path to the referenced item */
-    href: string;
-}
-/**
- * Dublin Core metadata element
- */
-interface DCElement {
-    /** The element name (title, creator, identifier, etc.) */
-    name: string;
-    /** The text content */
-    value: string;
-    /** The id attribute, if any */
-    id?: string;
-    /** Additional attributes */
-    attributes?: Record<string, string>;
-}
-/**
- * EPUB 3 meta element
- */
-interface MetaElement {
-    /** Property name (with optional prefix) */
-    property: string;
-    /** The text content */
-    value: string;
-    /** ID of the element this meta refines */
-    refines?: string;
-    /** Scheme for the value */
-    scheme?: string;
-    /** The id attribute, if any */
-    id?: string;
-}
-/**
- * EPUB 3 link element
- */
-interface LinkElement {
-    /** Relationship type */
-    rel: string;
-    /** URL to the linked resource */
-    href: string;
-    /** Media type of the linked resource */
-    mediaType?: string;
-    /** ID of the element this link refines */
-    refines?: string;
-    /** Link properties */
-    properties?: string[];
-    /** The id attribute, if any */
-    id?: string;
-    /** Language tag for the linked resource */
-    hreflang?: string;
-}
-/**
- * Parsed OPF package document
- */
-interface PackageDocument {
-    /** EPUB version from package@version */
-    version: EPUBVersion;
-    /** Unique identifier reference (package@unique-identifier) */
-    uniqueIdentifier: string;
-    /** Package prefix declarations (EPUB 3) */
-    prefixes?: Record<string, string>;
-    /** Package direction (rtl, ltr, auto) */
-    dir?: string;
-    /** Dublin Core metadata elements */
-    dcElements: DCElement[];
-    /** EPUB 3 meta elements */
-    metaElements: MetaElement[];
-    /** EPUB 3 link elements */
-    linkElements: LinkElement[];
-    /** Manifest items */
-    manifest: ManifestItem[];
-    /** Spine item references */
-    spine: SpineItemRef[];
-    /** Spine toc attribute (NCX reference for EPUB 2) */
-    spineToc?: string;
-    /** Spine page-progression-direction */
-    pageProgressionDirection?: 'ltr' | 'rtl' | 'default';
-    /** Guide references (EPUB 2) */
-    guide: GuideReference[];
-    /** Collections (EPUB 3) */
-    collections: Collection[];
-    /** Whether the bindings element is present (deprecated in EPUB 3.3) */
-    hasBindings?: boolean;
-    /** xml:lang attribute on elements (for validation) */
-    xmlLangs?: string[];
-}
-/**
- * Represents a collection in the OPF (EPUB 3)
- */
-interface Collection {
-    /** Collection role (dictionary, index, preview, etc.) */
-    role: string;
-    /** Collection identifier */
-    id?: string;
-    /** Collection name/label */
-    name?: string;
-    /** Resource hrefs in this collection (from link elements) */
-    links: string[];
-}
-
-/**
- * Severity levels for validation messages
- */
-type Severity = 'fatal' | 'error' | 'warning' | 'info' | 'usage';
-/**
- * Supported EPUB versions
- */
-type EPUBVersion = '2.0' | '3.0' | '3.1' | '3.2' | '3.3';
-/**
- * EPUB validation profiles
- */
-type EPUBProfile = 'default' | 'edupub' | 'idx' | 'dict' | 'preview';
-/**
- * Location within an EPUB file
- */
-interface EPUBLocation {
-    /** Path to the file within the EPUB container */
-    path: string;
-    /** Line number (1-based), if applicable */
-    line?: number;
-    /** Column number (1-based), if applicable */
-    column?: number;
-    /** Additional context about the location */
-    context?: string;
-}
-/**
- * A validation message (error, warning, etc.)
- */
-interface ValidationMessage {
-    /** Unique message identifier */
-    id: string;
-    /** Severity level */
-    severity: Severity;
-    /** Human-readable message */
-    message: string;
-    /** Location where the issue was found */
-    location?: EPUBLocation;
-    /** Suggestion for fixing the issue */
-    suggestion?: string;
-}
-/**
- * Result of EPUB validation
- */
-interface EpubCheckResult {
-    /** Whether the EPUB is valid (no errors or fatal errors) */
-    valid: boolean;
-    /** All validation messages */
-    messages: ValidationMessage[];
-    /** Count of fatal errors */
-    fatalCount: number;
-    /** Count of errors */
-    errorCount: number;
-    /** Count of warnings */
-    warningCount: number;
-    /** Count of info messages */
-    infoCount: number;
-    /** Count of usage messages */
-    usageCount: number;
-    /** Detected EPUB version */
-    version?: EPUBVersion | undefined;
-    /** Time taken for validation in milliseconds */
-    elapsedMs: number;
-}
-/**
- * Options for EpubCheck
- */
-interface EpubCheckOptions {
-    /** EPUB version to validate against (auto-detected if not specified) */
-    version?: EPUBVersion;
-    /** Validation profile */
-    profile?: EPUBProfile;
-    /** Whether to include usage messages */
-    includeUsage?: boolean;
-    /** Whether to include info messages */
-    includeInfo?: boolean;
-    /** Maximum number of errors before stopping (0 = unlimited) */
-    maxErrors?: number;
-    /** Locale for messages (e.g., 'en', 'de', 'fr') */
-    locale?: string;
-}
-/**
- * Internal validation context passed through the validation pipeline
- */
-interface ValidationContext {
-    /** EPUB file data */
-    data: Uint8Array;
-    /** Validation options */
-    options: Required<EpubCheckOptions>;
-    /** Detected EPUB version */
-    version: EPUBVersion;
-    /** Validation messages collected so far */
-    messages: ValidationMessage[];
-    /** Files extracted from EPUB container */
-    files: Map<string, Uint8Array>;
-    /** Rootfiles found in container.xml */
-    rootfiles: Rootfile[];
-    /** Path to the package document (OPF) */
-    opfPath?: string;
-    /** Parsed package document */
-    packageDocument?: PackageDocument;
-    /** NCX UID for validation against OPF identifier */
-    ncxUid?: string;
-    /** Resources referenced in content but not declared in manifest */
-    referencedUndeclaredResources?: Set<string>;
-    /** TOC navigation link targets in order, for reading order validation (NAV-011) */
-    tocLinks?: {
-        targetResource: string;
-        fragment?: string;
-        location: EPUBLocation;
-    }[];
-    /** Media overlay text link targets in order, for reading order validation (MED-015) */
-    overlayTextLinks?: {
-        targetResource: string;
-        fragment?: string;
-        location: EPUBLocation;
-    }[];
-    /** OPF media:active-class value (if declared) */
-    mediaActiveClass?: string;
-    /** OPF media:playback-active-class value (if declared) */
-    mediaPlaybackActiveClass?: string;
-    /** Resources marked with IDPF font obfuscation in encryption.xml */
-    obfuscatedResources?: Set<string>;
-}
-/**
- * Rootfile reference from container.xml
- */
-interface Rootfile {
-    path: string;
-    mediaType: string;
-}
-
-/**
- * Main EPUB validation class
- *
- * @example
- * ```typescript
- * import { EpubCheck } from 'epubcheck-ts';
- *
- * // Validate from a Uint8Array (works in Node.js and browsers)
- * const result = await EpubCheck.validate(epubData);
- *
- * if (result.valid) {
- *   console.log('EPUB is valid!');
- * } else {
- *   console.log(`Found ${result.errorCount} errors`);
- *   for (const msg of result.messages) {
- *     console.log(`${msg.severity}: ${msg.message}`);
- *   }
- * }
- * ```
- */
-declare class EpubCheck {
-    private readonly options;
-    /**
-     * Create a new EpubCheck instance with custom options
-     */
-    constructor(options?: EpubCheckOptions);
-    /**
-     * Validate an EPUB file
-     *
-     * @param data - The EPUB file as a Uint8Array
-     * @returns Validation result
-     */
-    check(data: Uint8Array): 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
-     * @returns Validation result
-     */
-    static validate(data: Uint8Array, options?: EpubCheckOptions): Promise<EpubCheckResult>;
-    /**
-     * Get the current EPUB version being validated against
-     */
-    get version(): EPUBVersion;
-    /**
-     * Validate NCX navigation document (EPUB 2 always, EPUB 3 when NCX present)
-     */
-    private validateNCX;
-    /**
-     * Add a validation message to the context
-     */
-    protected addMessage(messages: ValidationMessage[], message: ValidationMessage): void;
-    /**
-     * Validate that obfuscated resources are blessed font types (PKG-026)
-     */
-    private validateObfuscatedResources;
-    /**
-     * Populate resource registry from package document manifest
-     */
-    private populateRegistry;
-    /**
-     * Check if a manifest item has a fallback chain reaching a Core Media Type
-     */
-    private hasCMTFallback;
-}
-
-/**
- * Build a validation result from messages
- */
-declare function buildReport(messages: ValidationMessage[], version: EPUBVersion | undefined, elapsedMs: number): EpubCheckResult;
-/**
- * Count messages by severity
- */
-declare function countBySeverity(messages: ValidationMessage[]): Record<Severity, number>;
-/**
- * Filter messages by severity
- */
-declare function filterBySeverity(messages: ValidationMessage[], severity: Severity): ValidationMessage[];
-/**
- * Filter messages by path
- */
-declare function filterByPath(messages: ValidationMessage[], path: string): ValidationMessage[];
-/**
- * Format messages as a string for display
- */
-declare function formatMessages(messages: ValidationMessage[]): string;
-/**
- * Convert result to JSON report format (compatible with EPUBCheck JSON output)
- */
-declare function toJSONReport(result: EpubCheckResult): string;
-
 /**
  * Message Definitions for EPUB validation errors and warnings
  *
@@ -1926,62 +1566,539 @@ interface MessageInfo {
 /**
  * Get message info by ID
  */
-declare function getMessageInfo(id: string): MessageInfo | undefined;
+declare function getMessageInfo(id: string): MessageInfo | undefined;
+/**
+ * Get default severity for a message ID
+ */
+declare function getDefaultSeverity(id: string): MessageSeverity;
+/**
+ * Get all message definitions as an array (for iteration/display)
+ */
+declare function getAllMessages(): readonly MessageInfo[];
+/**
+ * Format message list for console output
+ */
+declare function formatMessageList(): string;
+/**
+ * Options for creating a validation message
+ */
+interface CreateMessageOptions {
+    /** Message ID from MessageId enum */
+    id: MessageId;
+    /** Human-readable message */
+    message: string;
+    /** Location where the issue was found */
+    location?: EPUBLocation;
+    /** Suggestion for fixing the issue */
+    suggestion?: string;
+    /** Override the default severity (use sparingly) */
+    severityOverride?: Severity;
+}
+/**
+ * Create a validation message with automatic severity lookup
+ *
+ * @example
+ * ```typescript
+ * const msg = createMessage({
+ *   id: MessageId.PKG_006,
+ *   message: 'Missing mimetype file',
+ *   location: { path: 'mimetype' },
+ * });
+ * if (msg) context.messages.push(msg);
+ * ```
+ */
+declare function createMessage(options: CreateMessageOptions): ValidationMessage | null;
+/**
+ * Create and push a validation message to the messages array.
+ * Automatically handles suppressed messages by not pushing them.
+ *
+ * @example
+ * ```typescript
+ * pushMessage(context.messages, {
+ *   id: MessageId.PKG_006,
+ *   message: 'Missing mimetype file',
+ *   location: { path: 'mimetype' },
+ * });
+ * ```
+ */
+declare function pushMessage(messages: ValidationMessage[], options: CreateMessageOptions): void;
+/**
+ * Parse a custom messages file (TSV format compatible with Java EPUBCheck).
+ *
+ * Format: one override per line, tab-separated: `ID\tSEVERITY`
+ * Lines starting with # are comments. A header line starting with "id" is skipped.
+ *
+ * @example
+ * ```
+ * ACC-004\tWARNING
+ * ACC-005\tWARNING
+ * RSC-008\tSUPPRESSED
+ * ```
+ */
+declare function parseCustomMessages(content: string): Map<string, MessageSeverity>;
+
+/**
+ * Represents a manifest item in the OPF
+ */
+interface ManifestItem {
+    /** Unique identifier for this item */
+    id: string;
+    /** Path relative to the OPF file */
+    href: string;
+    /** MIME media type */
+    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' */
+    properties?: string[];
+}
+/**
+ * Represents a spine itemref in the OPF
+ */
+interface SpineItemRef {
+    /** Optional ID attribute on the itemref element */
+    id?: string;
+    /** Reference to manifest item ID */
+    idref: string;
+    /** Whether this item is part of the linear reading order */
+    linear: boolean;
+    /** Itemref properties (EPUB 3) - e.g., 'page-spread-left', 'page-spread-right' */
+    properties?: string[];
+}
+/**
+ * Represents a guide reference (EPUB 2)
+ */
+interface GuideReference {
+    /** Type of reference (cover, toc, etc.) */
+    type: string;
+    /** Title for display */
+    title?: string;
+    /** Path to the referenced item */
+    href: string;
+}
+/**
+ * Dublin Core metadata element
+ */
+interface DCElement {
+    /** The element name (title, creator, identifier, etc.) */
+    name: string;
+    /** The text content */
+    value: string;
+    /** The id attribute, if any */
+    id?: string;
+    /** Additional attributes */
+    attributes?: Record<string, string>;
+}
+/**
+ * EPUB 3 meta element
+ */
+interface MetaElement {
+    /** Property name (with optional prefix) */
+    property: string;
+    /** The text content */
+    value: string;
+    /** ID of the element this meta refines */
+    refines?: string;
+    /** Scheme for the value */
+    scheme?: string;
+    /** The id attribute, if any */
+    id?: string;
+}
+/**
+ * EPUB 3 link element
+ */
+interface LinkElement {
+    /** Relationship type */
+    rel: string;
+    /** URL to the linked resource */
+    href: string;
+    /** Media type of the linked resource */
+    mediaType?: string;
+    /** ID of the element this link refines */
+    refines?: string;
+    /** Link properties */
+    properties?: string[];
+    /** The id attribute, if any */
+    id?: string;
+    /** Language tag for the linked resource */
+    hreflang?: string;
+}
+/**
+ * Parsed OPF package document
+ */
+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) */
+    prefixes?: Record<string, string>;
+    /** Package direction (rtl, ltr, auto) */
+    dir?: string;
+    /** Dublin Core metadata elements */
+    dcElements: DCElement[];
+    /** EPUB 3 meta elements */
+    metaElements: MetaElement[];
+    /** EPUB 3 link elements */
+    linkElements: LinkElement[];
+    /** Manifest items */
+    manifest: ManifestItem[];
+    /** Spine item references */
+    spine: SpineItemRef[];
+    /** Spine toc attribute (NCX reference for EPUB 2) */
+    spineToc?: string;
+    /** Spine page-progression-direction */
+    pageProgressionDirection?: 'ltr' | 'rtl' | 'default';
+    /** Guide references (EPUB 2) */
+    guide: GuideReference[];
+    /** Collections (EPUB 3) */
+    collections: Collection[];
+    /** Whether the bindings element is present (deprecated in EPUB 3.3) */
+    hasBindings?: boolean;
+    /** xml:lang attribute on elements (for validation) */
+    xmlLangs?: string[];
+}
+/**
+ * Represents a collection in the OPF (EPUB 3)
+ */
+interface Collection {
+    /** Collection role (dictionary, index, preview, etc.) */
+    role: string;
+    /** Collection identifier */
+    id?: string;
+    /** Collection name/label */
+    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;
+}
+
+/**
+ * Severity levels for validation messages
+ */
+type Severity = 'fatal' | 'error' | 'warning' | 'info' | 'usage';
+/**
+ * Supported EPUB versions
+ */
+declare const EPUB_VERSIONS: readonly ["2.0", "3.0", "3.1", "3.2", "3.3"];
+type EPUBVersion = (typeof EPUB_VERSIONS)[number];
 /**
- * Get default severity for a message ID
+ * EPUB validation profiles
  */
-declare function getDefaultSeverity(id: string): MessageSeverity;
+type EPUBProfile = 'default' | 'edupub' | 'idx' | 'dict' | 'preview';
 /**
- * Get all message definitions as an array (for iteration/display)
+ * Validation modes for single-file and expanded directory validation
  */
-declare function getAllMessages(): readonly MessageInfo[];
+type ValidationMode = 'exp' | 'opf' | 'xhtml' | 'svg' | 'nav' | 'mo';
 /**
- * Format message list for console output
+ * Location within an EPUB file
  */
-declare function formatMessageList(): string;
+interface EPUBLocation {
+    /** Path to the file within the EPUB container */
+    path: string;
+    /** Line number (1-based), if applicable */
+    line?: number;
+    /** Column number (1-based), if applicable */
+    column?: number;
+    /** Additional context about the location */
+    context?: string;
+}
 /**
- * Options for creating a validation message
+ * A validation message (error, warning, etc.)
  */
-interface CreateMessageOptions {
-    /** Message ID from MessageId enum */
-    id: MessageId;
+interface ValidationMessage {
+    /** Unique message identifier */
+    id: string;
+    /** Severity level */
+    severity: Severity;
     /** Human-readable message */
     message: string;
     /** Location where the issue was found */
     location?: EPUBLocation;
     /** Suggestion for fixing the issue */
     suggestion?: string;
-    /** Override the default severity (use sparingly) */
-    severityOverride?: Severity;
 }
 /**
- * Create a validation message with automatic severity lookup
- *
- * @example
- * ```typescript
- * const msg = createMessage({
- *   id: MessageId.PKG_006,
- *   message: 'Missing mimetype file',
- *   location: { path: 'mimetype' },
- * });
- * if (msg) context.messages.push(msg);
- * ```
+ * Result of EPUB validation
  */
-declare function createMessage(options: CreateMessageOptions): ValidationMessage | null;
+interface EpubCheckResult {
+    /** Whether the EPUB is valid (no errors or fatal errors) */
+    valid: boolean;
+    /** All validation messages */
+    messages: ValidationMessage[];
+    /** Count of fatal errors */
+    fatalCount: number;
+    /** Count of errors */
+    errorCount: number;
+    /** Count of warnings */
+    warningCount: number;
+    /** Count of info messages */
+    infoCount: number;
+    /** Count of usage messages */
+    usageCount: number;
+    /** Detected EPUB version */
+    version?: EPUBVersion | undefined;
+    /** Time taken for validation in milliseconds */
+    elapsedMs: number;
+}
 /**
- * Create and push a validation message to the messages array.
- * Automatically handles suppressed messages by not pushing them.
+ * Options for EpubCheck
+ */
+interface EpubCheckOptions {
+    /** EPUB version to validate against (auto-detected if not specified) */
+    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 */
+    includeInfo?: boolean;
+    /** Maximum number of errors before stopping (0 = unlimited) */
+    maxErrors?: number;
+    /** Locale for messages (e.g., 'en', 'de', 'fr') */
+    locale?: string;
+    /** 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
+ */
+interface ValidationContext {
+    /** EPUB file data */
+    data: Uint8Array;
+    /** Validation options */
+    options: ResolvedEpubCheckOptions;
+    /** Detected EPUB version */
+    version: EPUBVersion;
+    /** Validation messages collected so far */
+    messages: ValidationMessage[];
+    /** Files extracted from EPUB container */
+    files: Map<string, Uint8Array>;
+    /** Rootfiles found in container.xml */
+    rootfiles: Rootfile[];
+    /** Path to the package document (OPF) */
+    opfPath?: string;
+    /** Parsed package document */
+    packageDocument?: PackageDocument;
+    /** NCX UID for validation against OPF identifier */
+    ncxUid?: string;
+    /** Resources referenced in content but not declared in manifest */
+    referencedUndeclaredResources?: Set<string>;
+    /** TOC navigation link targets in order, for reading order validation (NAV-011) */
+    tocLinks?: {
+        targetResource: string;
+        fragment?: string;
+        location: EPUBLocation;
+    }[];
+    /** Media overlay text link targets in order, for reading order validation (MED-015) */
+    overlayTextLinks?: {
+        targetResource: string;
+        fragment?: string;
+        location: EPUBLocation;
+    }[];
+    /** OPF media:active-class value (if declared) */
+    mediaActiveClass?: string;
+    /** OPF media:playback-active-class value (if declared) */
+    mediaPlaybackActiveClass?: string;
+    /** Resources marked with IDPF font obfuscation in encryption.xml */
+    obfuscatedResources?: Set<string>;
+    /** Feature flags collected during content validation for cross-document checks */
+    contentFeatures?: {
+        hasPageBreak?: boolean;
+        hasPageList?: boolean;
+        hasTable?: boolean;
+        hasFigure?: boolean;
+        hasAudio?: boolean;
+        hasVideo?: boolean;
+        hasDictionary?: boolean;
+        hasIndex?: boolean;
+        hasLOI?: boolean;
+        hasLOT?: boolean;
+        hasLOA?: boolean;
+        hasLOV?: boolean;
+        hasMicrodata?: boolean;
+        hasRDFa?: boolean;
+    };
+}
+/**
+ * Rootfile reference from container.xml
+ */
+interface Rootfile {
+    path: string;
+    mediaType: string;
+}
+
+/**
+ * Main EPUB validation class
  *
  * @example
  * ```typescript
- * pushMessage(context.messages, {
- *   id: MessageId.PKG_006,
- *   message: 'Missing mimetype file',
- *   location: { path: 'mimetype' },
- * });
+ * import { EpubCheck } from 'epubcheck-ts';
+ *
+ * // Validate from a Uint8Array (works in Node.js and browsers)
+ * const result = await EpubCheck.validate(epubData);
+ *
+ * if (result.valid) {
+ *   console.log('EPUB is valid!');
+ * } else {
+ *   console.log(`Found ${result.errorCount} errors`);
+ *   for (const msg of result.messages) {
+ *     console.log(`${msg.severity}: ${msg.message}`);
+ *   }
+ * }
  * ```
  */
-declare function pushMessage(messages: ValidationMessage[], options: CreateMessageOptions): void;
+declare class EpubCheck {
+    private readonly options;
+    /**
+     * Create a new EpubCheck instance with custom options
+     */
+    constructor(options?: EpubCheckOptions);
+    /**
+     * 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
+     */
+    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, 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
+     */
+    get version(): EPUBVersion;
+    /**
+     * Cross-document feature validation (Pattern B from Java EPUBCheck)
+     */
+    private validateCrossDocumentFeatures;
+    /**
+     * Validate NCX navigation document (EPUB 2 always, EPUB 3 when NCX present)
+     */
+    private validateNCX;
+    /**
+     * Add a validation message to the context
+     */
+    protected addMessage(messages: ValidationMessage[], message: ValidationMessage): void;
+    /**
+     * Validate that obfuscated resources are blessed font types (PKG-026)
+     */
+    private validateObfuscatedResources;
+    /**
+     * Populate resource registry from package document manifest
+     */
+    private populateRegistry;
+    /**
+     * 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;
+}
+
+/**
+ * Build a validation result from messages
+ */
+declare function buildReport(messages: ValidationMessage[], version: EPUBVersion | undefined, elapsedMs: number): EpubCheckResult;
+/**
+ * Count messages by severity
+ */
+declare function countBySeverity(messages: ValidationMessage[]): Record<Severity, number>;
+/**
+ * Filter messages by severity
+ */
+declare function filterBySeverity(messages: ValidationMessage[], severity: Severity): ValidationMessage[];
+/**
+ * Filter messages by path
+ */
+declare function filterByPath(messages: ValidationMessage[], path: string): ValidationMessage[];
+/**
+ * Format messages as a string for display
+ */
+declare function formatMessages(messages: ValidationMessage[]): string;
+/**
+ * Convert result to JSON report format (compatible with EPUBCheck JSON output)
+ */
+declare function toJSONReport(result: EpubCheckResult): string;
 
 /**
  * Interface for schema validators
@@ -2001,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, 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 };