@dragon708/docmind-markdown 1.1.2 → 1.2.0

package/dist/index.d.ts

@@ -304,7 +304,7 @@ interface ConvertDocxToMarkdownResult {
 /**
  * **Node only.** Primary API: `.docx` bytes → semantic HTML (Mammoth) → LLM-friendly Markdown (Turndown + optional GFM).
  *
- * Optional peers: `mammoth`, `turndown`. Runtime dependency: `turndown-plugin-gfm` (declared on this package) when
+ * Dependencies: `mammoth`, `turndown`, and `turndown-plugin-gfm` (all declared on this package). GFM is loaded when
  * {@link ConvertDocxToMarkdownOptions.includeTables} is true.
  *
  * @see {@link convertDocxBufferToMarkdown} for a thin wrapper that only returns `markdown` and `messages`.
@@ -366,7 +366,11 @@ type ConvertPdfToMarkdownOptions = OpenDataLoaderPdfConvertOptions & {
 /** Input for {@link convertPdfToMarkdown}: filesystem path (Node) or PDF bytes. */
 type PdfToMarkdownInput = string | Buffer | Uint8Array | ArrayBuffer;
 /** Which pipeline produced {@link ConvertPdfToMarkdownResult.markdown}. */
-type PdfToMarkdownSource = "opendataloader" | "structured-fallback" | "unsupported-runtime";
+type PdfToMarkdownSource = "opendataloader" | "structured-fallback" | "unsupported-runtime"
+/** `@opendataloader/pdf` missing or failed to load (install dep; check bundler externals). */
+ | "opendataloader-unavailable"
+/** Engine ran or was attempted but produced no usable Markdown (Java error, empty stdout, missing file, etc.). */
+ | "opendataloader-failed";
 type PdfToMarkdownFallbackReason = "unsupported-runtime" | "error" | "empty" | "module-not-found";
 interface ConvertPdfToMarkdownResult {
     readonly markdown: string;
@@ -434,7 +438,11 @@ type ExtractMarkdownOptions = ConvertStructuredToMarkdownOptions & {
     readonly pdf?: ConvertPdfToMarkdownOptions;
 };
 /** Which branch produced {@link ExtractMarkdownResult.markdown}. */
-type ExtractMarkdownStrategy = "structured" | "docx-mammoth" | "docx-structured-fallback" | "pdf-opendataloader" | "pdf-structured-fallback" | "pdf-unsupported-runtime" | "docx-requires-node" | "path-requires-node" | "binary-unidentified" | "binary-unidentified-structured-fallback";
+type ExtractMarkdownStrategy = "structured" | "docx-mammoth" | "docx-structured-fallback" | "pdf-opendataloader"
+/** `@opendataloader/pdf` not loadable (missing package, bundler, etc.). */
+ | "pdf-opendataloader-unavailable"
+/** Engine failed or returned empty Markdown; no structured fallback or fallback also failed. */
+ | "pdf-opendataloader-failed" | "pdf-structured-fallback" | "pdf-unsupported-runtime" | "docx-requires-node" | "path-requires-node" | "binary-unidentified" | "binary-unidentified-structured-fallback";
 interface ExtractMarkdownResult {
     readonly markdown: string;
     /** Merged pipeline warnings (conversion, runtime, and optional {@link StructuredDocumentResult.warnings}). */

package/dist/index.js

@@ -999,6 +999,23 @@ function normalizePdfMarkdown(markdown, clean) {
   if (!clean) return t;
   return t.replace(/\n{3,}/g, "\n\n");
 }
+function normalizeConvertStdout(out) {
+  if (typeof out === "string") return out;
+  if (typeof Buffer !== "undefined" && Buffer.isBuffer(out)) {
+    return out.toString("utf8");
+  }
+  if (out instanceof Uint8Array) {
+    return typeof Buffer !== "undefined" ? Buffer.from(out).toString("utf8") : new TextDecoder("utf8", { fatal: false }).decode(out);
+  }
+  if (out == null) return "";
+  return String(out);
+}
+var FALLBACK_WARN_PREFIX = "[docmind-markdown:pdf] structured-fallback: serializing StructuredDocumentResult to Markdown because";
+function structuredFallbackWarnings(reason, detail) {
+  const tail = reason === "module-not-found" ? "@opendataloader/pdf could not be loaded." : reason === "error" ? "the specialized PDF engine raised an error or rejected the input." : reason === "empty" ? "the specialized engine returned empty Markdown." : "the specialized path is unavailable in this runtime.";
+  const extra = detail ? ` (${detail})` : "";
+  return [`${FALLBACK_WARN_PREFIX} ${tail}${extra}`];
+}
 function engineOptions(options) {
   if (!options) return {};
   const {
@@ -1065,7 +1082,10 @@ async function convertPdfToMarkdown(input, options) {
           );
           return {
             markdown: md,
-            warnings,
+            warnings: [
+              ...structuredFallbackWarnings("module-not-found"),
+              ...warnings
+            ],
             source: "structured-fallback",
             fallbackReason: "module-not-found"
           };
@@ -1078,20 +1098,22 @@ async function convertPdfToMarkdown(input, options) {
       return {
         markdown: "",
         warnings,
-        source: "opendataloader",
+        source: "opendataloader-unavailable",
         fallbackReason: "module-not-found"
       };
     }
     let rawMarkdown;
     try {
-      rawMarkdown = await convert(inputPath, {
+      const out = await convert(inputPath, {
         ...eng,
         format: "markdown",
         toStdout: true,
         quiet: eng.quiet !== false
-      }).then((s) => String(s));
+      });
+      rawMarkdown = normalizeConvertStdout(out);
     } catch (e) {
-      warnings.push(`PDF conversion failed: ${e instanceof Error ? e.message : String(e)}`);
+      const msg = e instanceof Error ? e.message : String(e);
+      warnings.push(`PDF conversion failed (@opendataloader/pdf): ${msg}`);
       if (resolveStructured) {
         try {
           const structured = await resolveStructured();
@@ -1101,7 +1123,10 @@ async function convertPdfToMarkdown(input, options) {
           );
           return {
             markdown: md,
-            warnings,
+            warnings: [
+              ...structuredFallbackWarnings("error", msg.slice(0, 500)),
+              ...warnings
+            ],
             source: "structured-fallback",
             fallbackReason: "error"
           };
@@ -1114,13 +1139,15 @@ async function convertPdfToMarkdown(input, options) {
       return {
         markdown: "",
         warnings,
-        source: "opendataloader",
+        source: "opendataloader-failed",
         fallbackReason: "error"
       };
     }
     let markdown = normalizePdfMarkdown(rawMarkdown, clean);
     if (markdown.length === 0) {
-      warnings.push("OpenDataLoader returned empty Markdown for this PDF.");
+      warnings.push(
+        "OpenDataLoader returned empty Markdown for this PDF (stdout empty or whitespace-only after normalize)."
+      );
       if (resolveStructured) {
         try {
           const structured = await resolveStructured();
@@ -1130,7 +1157,7 @@ async function convertPdfToMarkdown(input, options) {
           );
           return {
             markdown,
-            warnings,
+            warnings: [...structuredFallbackWarnings("empty"), ...warnings],
             source: "structured-fallback",
             fallbackReason: "empty"
           };
@@ -1143,7 +1170,7 @@ async function convertPdfToMarkdown(input, options) {
       return {
         markdown: "",
         warnings,
-        source: "opendataloader",
+        source: "opendataloader-failed",
         fallbackReason: "empty"
       };
     }
@@ -1241,9 +1268,19 @@ function docxStrategyFromSource(source) {
   return source === "structured-fallback" ? "docx-structured-fallback" : "docx-mammoth";
 }
 function pdfStrategyFromResult(r) {
-  if (r.source === "structured-fallback") return "pdf-structured-fallback";
-  if (r.source === "unsupported-runtime") return "pdf-unsupported-runtime";
-  return "pdf-opendataloader";
+  switch (r.source) {
+    case "structured-fallback":
+      return "pdf-structured-fallback";
+    case "unsupported-runtime":
+      return "pdf-unsupported-runtime";
+    case "opendataloader-unavailable":
+      return "pdf-opendataloader-unavailable";
+    case "opendataloader-failed":
+      return "pdf-opendataloader-failed";
+    case "opendataloader":
+    default:
+      return "pdf-opendataloader";
+  }
 }
 function mergeWarnings(base, ...more) {
   const out = [...base];
@@ -1342,7 +1379,7 @@ async function extractMarkdown(input, options) {
       return {
         markdown: convertStructuredToMarkdown(fb, smOpts),
         warnings: mergeWarnings(w, fb.warnings, [
-          "extractMarkdown: PDF route unavailable in this runtime; used structuredFallback."
+          "extractMarkdown: PDF specialized pipeline is unavailable in this runtime; used structuredFallback (same envelope as extractStructuredData)."
         ]),
         strategy: "pdf-structured-fallback"
       };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dragon708/docmind-markdown",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "StructuredDocumentResult → Markdown and LLM-oriented plain text for DocMind.",
   "type": "module",
   "sideEffects": false,
@@ -37,26 +37,14 @@
   "dependencies": {
     "@dragon708/docmind-shared": "^1.2.0",
     "@opendataloader/pdf": "^2.2.1",
-    "turndown-plugin-gfm": "^1.0.2"
-  },
-  "peerDependencies": {
     "mammoth": "^1.6.0",
-    "turndown": "^7.0.0"
-  },
-  "peerDependenciesMeta": {
-    "mammoth": {
-      "optional": true
-    },
-    "turndown": {
-      "optional": true
-    }
+    "turndown": "^7.0.0",
+    "turndown-plugin-gfm": "^1.0.2"
   },
   "devDependencies": {
     "@types/node": "^20.19.37",
     "jszip": "^3.10.1",
-    "mammoth": "^1.12.0",
     "tsup": "^8.5.1",
-    "turndown": "^7.2.4",
     "typescript": "^5.9.3",
     "vitest": "^1.6.1"
   }