@notedge/panduck 0.0.0

package/src/cli/report.ts

@@ -0,0 +1,110 @@
+import type { CapabilityState } from "./format-registry.js";
+
+export const REPORT_SCHEMA_VERSION = "panduck.report/v1";
+
+export type ReportStatus =
+    | "success"
+    | "success_with_loss"
+    | "partial"
+    | "blocked"
+    | "failed";
+
+export type LossPolicy = "allow" | "warn" | "deny";
+
+export type PanduckReport = {
+    schema_version: string;
+    tool: {
+        name: string;
+        version: string;
+    };
+    operation: string;
+    status: ReportStatus;
+    inputs: Array<{ path: string; format?: string }>;
+    detection?: {
+        outer?: string;
+        inner?: string;
+        format?: string;
+        confidence?: "hint" | "verified" | "ambiguous";
+        hints?: string[];
+    };
+    pipeline?: {
+        reader?: string;
+        writer?: string;
+        stages?: string[];
+        blocked_reason?: string;
+    };
+    parts?: string[];
+    decoded_parts?: Array<{
+        path: string;
+        compression_method: number;
+        compressed_size: number;
+        uncompressed_size: number;
+        decoded_size: number;
+    }>;
+    coverage?: {
+        state: CapabilityState;
+        read?: number;
+        write?: number;
+    };
+    losses?: Array<{
+        code: string;
+        owner: string;
+        severity: string;
+        message: string;
+        action?: string;
+    }>;
+    diagnostics?: Array<{
+        owner: string;
+        severity: string;
+        message: string;
+        code?: string;
+    }>;
+    outputs?: Array<{ path: string; published: boolean }>;
+    budgets?: Record<string, number>;
+    determinism?: {
+        profile?: string;
+        config?: string | null;
+    };
+    status_policy?: {
+        loss: LossPolicy;
+        strict: boolean;
+        exit_code: number;
+    };
+};
+
+export function createReport(input: {
+    operation: string;
+    toolVersion: string;
+    status: ReportStatus;
+    inputs: PanduckReport["inputs"];
+    detection?: PanduckReport["detection"];
+    pipeline?: PanduckReport["pipeline"];
+    parts?: PanduckReport["parts"];
+    decodedParts?: PanduckReport["decoded_parts"];
+    coverage?: PanduckReport["coverage"];
+    losses?: PanduckReport["losses"];
+    diagnostics?: PanduckReport["diagnostics"];
+    outputs?: PanduckReport["outputs"];
+    budgets?: PanduckReport["budgets"];
+    determinism?: PanduckReport["determinism"];
+    statusPolicy?: PanduckReport["status_policy"];
+}): PanduckReport {
+    return {
+        schema_version: REPORT_SCHEMA_VERSION,
+        tool: { name: "panduck", version: input.toolVersion },
+        operation: input.operation,
+        status: input.status,
+        inputs: input.inputs,
+        detection: input.detection,
+        pipeline: input.pipeline,
+        parts: input.parts,
+        decoded_parts: input.decodedParts,
+        coverage: input.coverage,
+        losses: input.losses ?? [],
+        diagnostics: input.diagnostics ?? [],
+        outputs: input.outputs ?? [],
+        budgets: input.budgets ?? {},
+        determinism: input.determinism,
+        status_policy: input.statusPolicy,
+    };
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export type { PanduckBindings, PanduckWasmOptions } from "./types.js";
+export { loadPanduckNative, loadPanduckNode } from "./node/index.js";
+export { loadPanduckWasm } from "./wasm/index.js";
+export { buildPanduckCli, runCli, getFormatRegistry, ExitCode, REPORT_SCHEMA_VERSION } from "./cli/index.js";
+export type { FormatRecord, PanduckReport, CapabilityState } from "./cli/index.js";
+
+/** @deprecated Use `loadPanduckNode` or `loadPanduckNative`. */
+export type PanduckNative = import("./types.js").PanduckBindings;

package/src/node/index.ts

@@ -0,0 +1,14 @@
+import { loadPanduckNode } from "./load.js";
+
+export type { PanduckBindings } from "../types.js";
+export { loadPanduckNode } from "./load.js";
+
+let cached: import("../types.js").PanduckBindings | undefined;
+
+/** Cached Node-API binding loader. */
+export function loadPanduckNative(): import("../types.js").PanduckBindings {
+    if (!cached) {
+        cached = loadPanduckNode();
+    }
+    return cached;
+}

package/src/node/load.ts

@@ -0,0 +1,120 @@
+import { createRequire } from "node:module";
+
+import type { PanduckBindings } from "../types.js";
+
+type NativeBinding = {
+    panduckVersion: () => string;
+    supportedFormats: () => string[];
+    isSupportedFormat: (name: string) => boolean;
+    supportsConversion?: (from: string, to: string) => boolean;
+    supportedConversions?: () => string[];
+    convertDocument?: (from: string, to: string, inputPath: string) => {
+        exitCode: number;
+        markdown?: string;
+        binary?: Uint8Array;
+        reportJson: string;
+    };
+    inspectIndex?: (inputPath: string) => {
+        format: string;
+        outer: string;
+        inner: string;
+        parts: string[];
+        reportJson: string;
+    };
+    installConsoleLogFile?: (path: string) => void;
+    installLoggerLogFile?: (path: string) => void;
+    inspectDecode?: (inputPath: string, partPath?: string) => {
+        format: string;
+        outer: string;
+        inner: string;
+        parts: Array<{
+            path: string;
+            compressionMethod: number;
+            compressedSize: number;
+            uncompressedSize: number;
+            decodedSize: number;
+        }>;
+        reportJson: string;
+    };
+};
+
+const PLATFORM_PACKAGES: Record<string, string> = {
+    "win32-x64": "@notedge/panduck-win32-x64",
+    "linux-x64": "@notedge/panduck-linux-x64",
+    "linux-arm64": "@notedge/panduck-linux-arm64",
+    "darwin-x64": "@notedge/panduck-darwin-x64",
+    "darwin-arm64": "@notedge/panduck-darwin-arm64",
+};
+
+/** Load the platform-specific Node-API binary from `@notedge/panduck-<platform>`. */
+export function loadPanduckNode(): PanduckBindings {
+    const key = `${process.platform}-${process.arch}`;
+    const pkg = PLATFORM_PACKAGES[key];
+    if (!pkg) {
+        throw new Error(`Unsupported platform for Panduck native bindings: ${key}`);
+    }
+    const require = createRequire(import.meta.url);
+    const binding = require(pkg).default as NativeBinding;
+    return {
+        panduckVersion: () => binding.panduckVersion(),
+        supportedFormats: () => binding.supportedFormats(),
+        isSupportedFormat: (name) => binding.isSupportedFormat(name),
+        supportsConversion: binding.supportsConversion
+            ? (from, to) => binding.supportsConversion!(from, to)
+            : undefined,
+        supportedConversions: binding.supportedConversions
+            ? () => binding.supportedConversions!()
+            : undefined,
+        convertDocument: binding.convertDocument
+            ? (from, to, inputPath) => {
+                  const response = binding.convertDocument!(from, to, inputPath);
+                  return {
+                      exitCode: response.exitCode,
+                      markdown: response.markdown,
+                      binary: response.binary
+                          ? new Uint8Array(response.binary)
+                          : undefined,
+                      reportJson: response.reportJson,
+                  };
+              }
+            : undefined,
+        inspectIndex: binding.inspectIndex
+            ? (inputPath) => {
+                  const response = binding.inspectIndex!(inputPath);
+                  return {
+                      format: response.format,
+                      outer: response.outer,
+                      inner: response.inner,
+                      parts: response.parts,
+                      reportJson: response.reportJson,
+                  };
+              }
+            : undefined,
+        inspectDecode: binding.inspectDecode
+            ? (inputPath, partPath) => {
+                  const response = binding.inspectDecode!(inputPath, partPath);
+                  return {
+                      format: response.format,
+                      outer: response.outer,
+                      inner: response.inner,
+                      parts: response.parts,
+                      reportJson: response.reportJson,
+                  };
+              }
+            : undefined,
+        installLoggerLogFile: binding.installLoggerLogFile
+            ? (path) => {
+                  binding.installLoggerLogFile!(path);
+              }
+            : binding.installConsoleLogFile
+              ? (path) => {
+                    binding.installConsoleLogFile!(path);
+                }
+              : undefined,
+        installConsoleLogFile: binding.installConsoleLogFile
+            ? (path) => {
+                  binding.installConsoleLogFile!(path);
+              }
+            : undefined,
+    };
+}

package/src/types.ts

@@ -0,0 +1,49 @@
+export type ConvertResponse = {
+    exitCode: number;
+    markdown?: string;
+    binary?: Uint8Array;
+    reportJson: string;
+};
+
+export type InspectIndexResponse = {
+    format: string;
+    outer: string;
+    inner: string;
+    parts: string[];
+    reportJson: string;
+};
+
+export type InspectDecodedPart = {
+    path: string;
+    compressionMethod: number;
+    compressedSize: number;
+    uncompressedSize: number;
+    decodedSize: number;
+};
+
+export type InspectDecodeResponse = {
+    format: string;
+    outer: string;
+    inner: string;
+    parts: InspectDecodedPart[];
+    reportJson: string;
+};
+
+/** Shared Panduck binding surface for Node-API and WebAssembly backends. */
+export type PanduckBindings = {
+    panduckVersion: () => string;
+    supportedFormats: () => string[];
+    isSupportedFormat: (name: string) => boolean;
+    supportsConversion?: (from: string, to: string) => boolean;
+    supportedConversions?: () => string[];
+    convertDocument?: (from: string, to: string, inputPath: string) => ConvertResponse;
+    inspectIndex?: (inputPath: string) => InspectIndexResponse;
+    inspectDecode?: (inputPath: string, partPath?: string) => InspectDecodeResponse;
+    installLoggerLogFile?: (path: string) => void;
+    installConsoleLogFile?: (path: string) => void;
+};
+
+export type PanduckWasmOptions = {
+    /** Browser URL for `panduck_wasm_bg.wasm` when not using the default package layout. */
+    url?: string | URL;
+};

package/src/wasm/index.ts

@@ -0,0 +1,2 @@
+export type { PanduckBindings, PanduckWasmOptions } from "../types.js";
+export { loadPanduckWasm } from "./load.js";

package/src/wasm/load.ts

@@ -0,0 +1,23 @@
+import type { PanduckBindings, PanduckWasmOptions } from "../types.js";
+
+type WasmModule = {
+    default: (input?: { module_or_path?: string | URL }) => Promise<unknown>;
+    panduckVersion: () => string;
+    supportedFormats: () => string[];
+    isSupportedFormat: (name: string) => boolean;
+};
+
+/** Load `@notedge/panduck-unknown-wasm32` and return the Panduck binding surface. */
+export async function loadPanduckWasm(options: PanduckWasmOptions = {}): Promise<PanduckBindings> {
+    const wasm = (await import("@notedge/panduck-unknown-wasm32/pkg/panduck_wasm.js")) as WasmModule;
+    if (options.url) {
+        await wasm.default({ module_or_path: options.url });
+    } else {
+        await wasm.default();
+    }
+    return {
+        panduckVersion: () => wasm.panduckVersion(),
+        supportedFormats: () => wasm.supportedFormats(),
+        isSupportedFormat: (name) => wasm.isSupportedFormat(name),
+    };
+}

package/src/wasm/panduck_wasm.d.ts

@@ -0,0 +1,6 @@
+declare module '@notedge/panduck-unknown-wasm32/pkg/panduck_wasm.js' {
+    export default function init(input?: { module_or_path?: string | URL }): Promise<unknown>;
+    export function panduckVersion(): string;
+    export function supportedFormats(): string[];
+    export function isSupportedFormat(name: string): boolean;
+}