@dragon708/docmind-node 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -1,11 +1,16 @@
-import { DetectFileKindInput, NamedInput, AnalysisResult } from '@dragon708/docmind-shared';
-export { AnalysisAnalyzer, AnalysisResult, DetectFileKindInput, DocxAnalysisCoreResult, FileKind, FileKindMetadata, GenericAnalysisResult, ImageAnalysisCoreResult, PdfAnalysisCoreResult, TextAnalysisResult } from '@dragon708/docmind-shared';
+import { DocMindAnalyzeOptions, DetectFileKindInput, NamedInput, AnalysisResult, FileKind, RuntimeDescriptor, DocMindPublicIntent, AnalysisAnalyzer, ProcessingPlanDescriptor, ExplainAnalysisPlanOptions, GetCapabilitiesOptions } from '@dragon708/docmind-shared';
+export { AnalysisAnalyzer, AnalysisResult, CapabilityDescriptor, DetectFileKindInput, DocMindPublicIntent, DocxAnalysisCoreResult, ExplainAnalysisPlanOptions, ExplainAnalysisPlanResult, FileKind, FileKindMetadata, GenericAnalysisResult, GetCapabilitiesOptions, GetCapabilitiesResult, ImageAnalysisCoreResult, PdfAnalysisCoreResult, TextAnalysisResult, detectFileKind } from '@dragon708/docmind-shared';
 import { OcrOptions } from '@dragon708/docmind-ocr';
 import { PdfAnalyzeOptions } from '@dragon708/docmind-pdf';
 
-/** Options for {@link analyzeFile} in the Node entry (`pdf` / `ocr` forwarded to format packages). */
-interface NodeAnalyzeOptions {
-    readonly signal?: AbortSignal;
+/**
+ * Options for Node public APIs (`analyzeFile`, intent methods).
+ *
+ * - **`pdf`**: forwarded to `@dragon708/docmind-pdf`. `analyzeFile` defaults `pdf.ocr` to `"auto"` when omitted.
+ *   {@link extractText} / {@link convertToHtml} merge a default of `ocr: "off"` unless you set `pdf.ocr` explicitly.
+ * - **`ocr`**: forwarded to `@dragon708/docmind-ocr` for raster images; language string also feeds PDF OCR when `pdf.ocrLangs` is unset.
+ */
+interface NodeAnalyzeOptions extends DocMindAnalyzeOptions {
     readonly pdf?: PdfAnalyzeOptions;
     readonly ocr?: OcrOptions;
 }
@@ -27,8 +32,91 @@ declare function bufferToInput(buffer: Buffer, name?: string): NamedInput<Buffer
 declare function resolveNodeAnalyzeInput(input: NodeAnalyzeInput): Promise<DetectFileKindInput>;
 
 /**
- * Node router: PDF, DOCX, images (OCR), and text. Paths and `file:` URLs are read via `fs`.
+ * Resolves {@link NodeAnalyzeInput} (paths read from disk), classifies with {@link detectFileKind}, then runs
+ * the PDF, DOCX, image, or text pipeline. PDF OCR defaults to `"auto"` when `options.pdf.ocr` is omitted.
  */
 declare function analyzeFile(input: NodeAnalyzeInput, options?: NodeAnalyzeOptions): Promise<AnalysisResult>;
 
-export { type NodeAnalyzeInput, type NodeAnalyzeOptions, analyzeFile, bufferToInput, readFileToInput, resolveNodeAnalyzeInput };
+/**
+ * Plain-text extraction using {@link analyzeFile} routing. PDFs default to **text layer only**
+ * (`pdf.ocr: "off"`) unless you set `options.pdf.ocr` explicitly.
+ */
+declare function extractText(input: NodeAnalyzeInput, options?: NodeAnalyzeOptions): Promise<AnalysisResult>;
+/**
+ * Metadata: PDF uses lightweight metadata extraction; DOCX/images return stubs; plain text uses the same
+ * router as {@link extractText} (`analyzeFile` with PDF OCR off by default).
+ */
+declare function extractMetadata(input: NodeAnalyzeInput, options?: NodeAnalyzeOptions): Promise<AnalysisResult>;
+/**
+ * HTML: DOCX and plain text go through {@link analyzeFile} (then `<pre>` for text). PDF uses the text layer
+ * only wrapped in `<pre>` (no OCR). Images return a stub without running OCR.
+ */
+declare function convertToHtml(input: NodeAnalyzeInput, options?: NodeAnalyzeOptions): Promise<AnalysisResult>;
+/**
+ * OCR intent: PDF always runs {@link analyzePdf} with `ocr: "force"` (merged with `options.pdf`).
+ * Raster images run Tesseract via `options.ocr`. DOCX returns structured extract with a notice.
+ */
+declare function runOcr(input: NodeAnalyzeInput, options?: NodeAnalyzeOptions): Promise<AnalysisResult>;
+
+/**
+ * Whether DocMind will try a non-OCR text/HTML path (e.g. Mammoth, pdf-parse text layer, UTF-8).
+ */
+interface NativeExtractionPlan {
+    readonly willAttempt: boolean;
+    readonly description: string;
+}
+/** Whether OCR (raster or PDF pipeline) may run for this intent + kind. */
+interface OcrPlan {
+    readonly mayUse: boolean;
+    readonly description: string;
+}
+/**
+ * Structured explanation of what DocMind would do for a public intent in Node (no heavy I/O).
+ */
+interface ExplainAnalysisPlanReport {
+    readonly kind: FileKind;
+    readonly detectedKind: FileKind;
+    readonly runtime: RuntimeDescriptor;
+    readonly intent: DocMindPublicIntent | (string & {});
+    readonly primaryAnalyzer: AnalysisAnalyzer;
+    readonly nativeExtraction: NativeExtractionPlan;
+    readonly ocr: OcrPlan;
+    readonly limitations: readonly string[];
+    readonly plan: ProcessingPlanDescriptor;
+    readonly warnings?: readonly string[];
+}
+
+/** High-level features the user can ask DocMind for (per input kind and runtime). */
+type PublicCapabilityId = "text" | "metadata" | "html" | "ocr" | "pages";
+/** Whether a {@link PublicCapabilityId} applies to the detected file in this runtime. */
+interface PublicCapabilitySupport {
+    readonly id: PublicCapabilityId;
+    readonly supported: boolean;
+    readonly warnings?: readonly string[];
+}
+/**
+ * Result of {@link getCapabilities}: detected kind, runtime id, per-feature support for this input, and optional global warnings.
+ */
+interface GetCapabilitiesReport {
+    readonly kind: FileKind;
+    readonly runtime: RuntimeDescriptor;
+    readonly capabilities: readonly PublicCapabilitySupport[];
+    readonly warnings?: readonly string[];
+}
+
+/** Options for {@link explainAnalysisPlan} including PDF/OCR hints for accurate planning. */
+type NodeExplainAnalysisPlanOptions = ExplainAnalysisPlanOptions & Pick<NodeAnalyzeOptions, "pdf" | "ocr">;
+
+/**
+ * Epic 1 — **Capabilities:** after resolving {@link NodeAnalyzeInput}, lists which of
+ * `text` | `metadata` | `html` | `ocr` | `pages` apply for that kind in Node (PDF fully supported).
+ * Does not run Mammoth/Tesseract/PDF bodies beyond path resolution.
+ */
+declare function getCapabilities(input: NodeAnalyzeInput, options?: GetCapabilitiesOptions): Promise<GetCapabilitiesReport>;
+/**
+ * Epic 1 — **Plan preview:** same shape as browser; PDF branches include `pdf.ocr` from options (`off` | `auto` | `force`).
+ * No full document parse unless resolving a path reads the file.
+ */
+declare function explainAnalysisPlan(input: NodeAnalyzeInput, options?: NodeExplainAnalysisPlanOptions): Promise<ExplainAnalysisPlanReport>;
+
+export { type ExplainAnalysisPlanReport, type GetCapabilitiesReport, type NativeExtractionPlan, type NodeAnalyzeInput, type NodeAnalyzeOptions, type NodeExplainAnalysisPlanOptions, type OcrPlan, type PublicCapabilityId, type PublicCapabilitySupport, analyzeFile, bufferToInput, convertToHtml, explainAnalysisPlan, extractMetadata, extractText, getCapabilities, readFileToInput, resolveNodeAnalyzeInput, runOcr };

package/dist/index.js

@@ -1,7 +1,8 @@
 import { assertValidAnalyzeFileInput, detectFileKind, notImplementedResult, UNKNOWN_FORMAT_WARNING, analyzeText, toUint8Array, isNamedInput, isBinaryInput, isBlob, isFile } from '@dragon708/docmind-shared';
+export { detectFileKind } from '@dragon708/docmind-shared';
 import { analyzeDocx } from '@dragon708/docmind-docx';
 import { ocr } from '@dragon708/docmind-ocr';
-import { analyzePdf } from '@dragon708/docmind-pdf';
+import { extractPdfMetadata, extractTextFromPdf, analyzePdf } from '@dragon708/docmind-pdf';
 import { readFile } from 'fs/promises';
 import { basename } from 'path';
 import { fileURLToPath } from 'url';
@@ -169,6 +170,723 @@ async function analyzeFile(input, options) {
   }
 }
 
-export { analyzeFile, bufferToInput, readFileToInput, resolveNodeAnalyzeInput };
+// src/intentPdfOptions.ts
+function withPdfOcrDefaultOff(options) {
+  return {
+    ...options,
+    pdf: {
+      ...options?.pdf,
+      ocr: options?.pdf?.ocr ?? "off"
+    }
+  };
+}
+
+// src/internal/abort.ts
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    const err = new Error("The operation was aborted");
+    err.name = "AbortError";
+    throw err;
+  }
+}
+
+// src/publicActions.ts
+var DOCX_METADATA_STUB = "Structured document metadata for DOCX is not exposed as a separate API; use extractText or analyzeFile.";
+var IMAGE_METADATA_NOTE = "Raster images have no document metadata bundle in this API.";
+var RUN_OCR_PDF_FORCE_SEMANTICS = 'runOcr: PDF pipeline ran with `ocr: "force"` so text may include raster OCR output even when a text layer exists.';
+function escapeHtmlMinimal(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+async function prepare(input) {
+  const resolved = await resolveNodeAnalyzeInput(input);
+  assertValidAnalyzeFileInput(resolved);
+  return resolved;
+}
+function toExtractTextResult(full) {
+  if (full.status !== "ok") return full;
+  if (full.fileKind === "docx") {
+    return { ...full, html: "" };
+  }
+  return full;
+}
+async function extractText(input, options) {
+  throwIfAborted(options?.signal);
+  const full = await analyzeFile(input, withPdfOcrDefaultOff(options));
+  return toExtractTextResult(full);
+}
+async function extractMetadata(input, options) {
+  throwIfAborted(options?.signal);
+  const resolved = await prepare(input);
+  const kind = detectFileKind(resolved);
+  options?.signal;
+  switch (kind) {
+    case "pdf": {
+      const data = await bytesFromDetectInput(resolved);
+      if (data.byteLength === 0) {
+        return {
+          fileKind: "pdf",
+          analyzer: "pdf",
+          status: "ok",
+          kind: "pdf",
+          text: "",
+          pages: 0,
+          metadata: { info: {} },
+          warnings: ["No document bytes were provided for analysis."],
+          needsOCR: false,
+          ocrUsed: false
+        };
+      }
+      const r = await extractPdfMetadata(data);
+      return {
+        fileKind: "pdf",
+        analyzer: "pdf",
+        status: "ok",
+        kind: "pdf",
+        text: "",
+        pages: 0,
+        metadata: r.metadata,
+        warnings: r.warnings,
+        needsOCR: false,
+        ocrUsed: false
+      };
+    }
+    case "docx":
+      return {
+        fileKind: "docx",
+        analyzer: "docx",
+        status: "ok",
+        kind: "docx",
+        text: "",
+        html: "",
+        warnings: [DOCX_METADATA_STUB]
+      };
+    case "image":
+      return {
+        fileKind: "image",
+        analyzer: "image",
+        status: "ok",
+        kind: "image",
+        text: "",
+        confidence: 0,
+        ocrUsed: true,
+        warnings: [IMAGE_METADATA_NOTE]
+      };
+    case "text":
+      return analyzeFile(input, withPdfOcrDefaultOff(options));
+    default:
+      return notImplementedResult(kind, "none", [UNKNOWN_FORMAT_WARNING]);
+  }
+}
+async function convertToHtml(input, options) {
+  throwIfAborted(options?.signal);
+  const resolved = await prepare(input);
+  const kind = detectFileKind(resolved);
+  options?.signal;
+  if (kind === "docx") {
+    return analyzeFile(input, withPdfOcrDefaultOff(options));
+  }
+  if (kind === "text") {
+    const r = await analyzeFile(input, withPdfOcrDefaultOff(options));
+    if (r.status !== "ok") return r;
+    if (r.fileKind !== "text") return r;
+    const html = `<pre>${escapeHtmlMinimal(r.text)}</pre>`;
+    return {
+      ...r,
+      html,
+      warnings: [
+        ...r.warnings,
+        "HTML for plain text is a <pre> wrapper around decoded UTF-8 content."
+      ]
+    };
+  }
+  if (kind === "pdf") {
+    const data = await bytesFromDetectInput(resolved);
+    if (data.byteLength === 0) {
+      return {
+        fileKind: "pdf",
+        analyzer: "pdf",
+        status: "ok",
+        kind: "pdf",
+        text: "",
+        pages: 0,
+        metadata: { info: {} },
+        warnings: ["No document bytes were provided for analysis."],
+        needsOCR: false,
+        ocrUsed: false
+      };
+    }
+    const r = await extractTextFromPdf(data);
+    const html = `<pre>${escapeHtmlMinimal(r.text)}</pre>`;
+    return {
+      fileKind: "pdf",
+      analyzer: "pdf",
+      status: "ok",
+      kind: "pdf",
+      text: r.text,
+      pages: r.pages,
+      metadata: { info: {} },
+      html,
+      warnings: [
+        ...r.warnings,
+        "PDF HTML is a plain-text preview wrapped in <pre> (not a visual layout)."
+      ],
+      needsOCR: false,
+      ocrUsed: false
+    };
+  }
+  if (kind === "image") {
+    return {
+      fileKind: "image",
+      analyzer: "image",
+      status: "ok",
+      kind: "image",
+      text: "",
+      confidence: 0,
+      ocrUsed: true,
+      warnings: ["No HTML representation for raster images; use extractText / runOcr."]
+    };
+  }
+  return notImplementedResult(kind, "none", [UNKNOWN_FORMAT_WARNING]);
+}
+async function runOcr(input, options) {
+  throwIfAborted(options?.signal);
+  const resolved = await prepare(input);
+  const kind = detectFileKind(resolved);
+  const signal = options?.signal;
+  const lang = options?.ocr?.langs ?? options?.pdf?.ocrLangs;
+  switch (kind) {
+    case "pdf": {
+      const data = await bytesFromDetectInput(resolved);
+      if (data.byteLength === 0) {
+        return {
+          fileKind: "pdf",
+          analyzer: "pdf",
+          status: "ok",
+          kind: "pdf",
+          text: "",
+          pages: 0,
+          metadata: { info: {} },
+          warnings: ["No document bytes were provided for analysis."],
+          needsOCR: false,
+          ocrUsed: false
+        };
+      }
+      const r = await analyzePdf(data, {
+        ...options?.pdf,
+        ocr: "force",
+        ocrLangs: lang ?? options?.pdf?.ocrLangs,
+        signal: options?.pdf?.signal ?? signal
+      });
+      return {
+        fileKind: "pdf",
+        analyzer: "pdf",
+        status: "ok",
+        kind: "pdf",
+        text: r.text,
+        pages: r.pages,
+        metadata: r.metadata,
+        warnings: [RUN_OCR_PDF_FORCE_SEMANTICS, ...r.warnings],
+        needsOCR: r.needsOCR,
+        ocrUsed: r.ocrUsed
+      };
+    }
+    case "image": {
+      const data = await bytesFromDetectInput(resolved);
+      if (data.byteLength === 0) {
+        return {
+          fileKind: "image",
+          analyzer: "image",
+          status: "ok",
+          kind: "image",
+          text: "",
+          confidence: 0,
+          ocrUsed: true,
+          warnings: ["No image bytes were provided for analysis."]
+        };
+      }
+      const ocrOpts = {
+        ...options?.ocr ?? {},
+        signal: options?.ocr?.signal ?? signal
+      };
+      const r = await ocr(data, ocrOpts);
+      return {
+        fileKind: "image",
+        analyzer: "image",
+        status: "ok",
+        kind: "image",
+        text: r.text,
+        confidence: r.confidence,
+        ocrUsed: r.ocrUsed,
+        warnings: []
+      };
+    }
+    case "docx": {
+      const data = await bytesFromDetectInput(resolved);
+      if (data.byteLength === 0) {
+        return {
+          fileKind: "docx",
+          analyzer: "docx",
+          status: "ok",
+          kind: "docx",
+          text: "",
+          html: "",
+          warnings: ["No document bytes were provided for analysis."]
+        };
+      }
+      const r = await analyzeDocx(data);
+      return {
+        fileKind: "docx",
+        analyzer: "docx",
+        status: "ok",
+        kind: "docx",
+        text: r.text,
+        html: r.html,
+        warnings: [
+          ...r.warnings,
+          "OCR does not apply to DOCX; returned structured text/HTML extract."
+        ]
+      };
+    }
+    case "text":
+      return analyzeText(resolved, { signal });
+    default:
+      return notImplementedResult(kind, "none", [UNKNOWN_FORMAT_WARNING]);
+  }
+}
+
+// src/analysisPlanReport.ts
+function lim(...items) {
+  return items.filter(Boolean);
+}
+function buildNodeExplainReport(kind, intent, pdfOcr, plan) {
+  const runtime = { id: "node" };
+  const primaryAnalyzer = kind === "pdf" ? "pdf" : kind === "docx" ? "docx" : kind === "image" ? "image" : kind === "text" ? "text" : "none";
+  let nativeExtraction;
+  let ocr3;
+  let limitations = [];
+  if (kind === "unknown") {
+    limitations = lim(
+      "Could not classify the file from name, MIME, or bytes; analysis will return not_implemented until hints improve."
+    );
+    return {
+      kind,
+      detectedKind: kind,
+      runtime,
+      intent,
+      primaryAnalyzer: "none",
+      nativeExtraction: { willAttempt: false, description: "No analyzer without a known file kind." },
+      ocr: { mayUse: false, description: "OCR is not used for unknown kinds." },
+      limitations,
+      plan
+    };
+  }
+  switch (intent) {
+    case "analyzeFile":
+      if (kind === "pdf") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "pdf-parse extracts embedded text and page count first."
+        };
+        ocr3 = {
+          mayUse: pdfOcr !== "off",
+          description: pdfOcr === "off" ? "Raster OCR pipeline is off (pdf.ocr: off)." : pdfOcr === "force" ? "Raster OCR may run on all pages when pdf.ocr is force." : "Raster OCR may run when the text layer is empty (pdf.ocr: auto)."
+        };
+      } else if (kind === "docx") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "Mammoth extracts text and HTML from OOXML."
+        };
+        ocr3 = { mayUse: false, description: "DOCX does not use OCR in DocMind." };
+      } else if (kind === "image") {
+        nativeExtraction = {
+          willAttempt: false,
+          description: "Images have no native text layer; text comes from OCR only."
+        };
+        ocr3 = { mayUse: true, description: "Tesseract runs on supported raster formats." };
+      } else {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "UTF-8 decode with BOM handling for plain text."
+        };
+        ocr3 = { mayUse: false, description: "OCR does not apply to text files." };
+      }
+      break;
+    case "extractText":
+      if (kind === "pdf") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "Text layer via pdf-parse; defaults to pdf.ocr off unless you override."
+        };
+        ocr3 = {
+          mayUse: false,
+          description: "extractText merges pdf.ocr default off \u2014 no raster OCR unless you set pdf.ocr explicitly."
+        };
+      } else if (kind === "docx") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "Mammoth plain text; HTML cleared in the extractText response."
+        };
+        ocr3 = { mayUse: false, description: "DOCX does not use OCR." };
+      } else if (kind === "image") {
+        nativeExtraction = { willAttempt: false, description: "No embedded text layer." };
+        ocr3 = { mayUse: true, description: "OCR produces text for images." };
+      } else {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "UTF-8 decode only."
+        };
+        ocr3 = { mayUse: false, description: "OCR does not apply." };
+      }
+      break;
+    case "extractMetadata":
+      if (kind === "pdf") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "Lightweight PDF info/XMP normalization without full OCR."
+        };
+        ocr3 = { mayUse: false, description: "extractMetadata does not run the OCR pipeline." };
+      } else if (kind === "docx" || kind === "image") {
+        nativeExtraction = {
+          willAttempt: false,
+          description: "Stub response; no heavy extractor."
+        };
+        ocr3 = { mayUse: false, description: "OCR not used for this metadata path." };
+        limitations = lim(
+          kind === "docx" ? "Structured DOCX metadata is not exposed separately." : "Raster images have no document metadata bundle."
+        );
+      } else {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "Decoded text only; no structured document metadata."
+        };
+        ocr3 = { mayUse: false, description: "OCR does not apply." };
+        limitations = lim("Plain text has no structured document metadata.");
+      }
+      break;
+    case "convertToHtml":
+      if (kind === "pdf") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "Text layer extracted then wrapped in <pre> (not visual layout)."
+        };
+        ocr3 = { mayUse: false, description: "convertToHtml does not run PDF OCR." };
+        limitations = lim("PDF HTML is a plain-text preview, not page layout.");
+      } else if (kind === "docx") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "Mammoth HTML output via analyzeFile routing."
+        };
+        ocr3 = { mayUse: false, description: "DOCX path does not use OCR." };
+      } else if (kind === "text") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "UTF-8 decode then <pre> wrapper."
+        };
+        ocr3 = { mayUse: false, description: "OCR does not apply." };
+      } else {
+        nativeExtraction = {
+          willAttempt: false,
+          description: "No HTML path for raster images."
+        };
+        ocr3 = { mayUse: false, description: "OCR does not emit layout HTML here." };
+        limitations = lim("Use extractText or runOcr for image text.");
+      }
+      break;
+    case "runOcr":
+      if (kind === "pdf") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "pdf-parse runs first; text may be replaced by raster OCR output."
+        };
+        ocr3 = {
+          mayUse: true,
+          description: 'runOcr always sets pdf.ocr to "force" for PDFs.'
+        };
+        limitations = lim("Forced OCR may run even when a text layer exists.");
+      } else if (kind === "image") {
+        nativeExtraction = { willAttempt: false, description: "No native text layer." };
+        ocr3 = { mayUse: true, description: "Tesseract OCR on the image bytes." };
+      } else if (kind === "docx") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "Full Mammoth extract (text + HTML); not OCR."
+        };
+        ocr3 = { mayUse: false, description: "DOCX is not OCR'd." };
+        limitations = lim("Result is structured extract, not OCR output.");
+      } else {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "UTF-8 decode only."
+        };
+        ocr3 = { mayUse: false, description: "OCR does not apply to text files." };
+      }
+      break;
+    default:
+      nativeExtraction = { willAttempt: false, description: "Generic intent; see plan." };
+      ocr3 = { mayUse: false, description: "See plan steps." };
+  }
+  return {
+    kind,
+    detectedKind: kind,
+    runtime,
+    intent,
+    primaryAnalyzer,
+    nativeExtraction,
+    ocr: ocr3,
+    limitations,
+    plan
+  };
+}
+
+// src/capabilityReport.ts
+var DOCX_META = "Structured document metadata is not exposed separately; extractMetadata returns a stub for DOCX.";
+var IMAGE_META = "Raster images have no document metadata bundle; extractMetadata returns a stub.";
+var IMAGE_HTML = "No layout HTML for raster images; use extractText or runOcr for text.";
+var TEXT_META_NOTE = "Plain text has no structured document metadata; extractMetadata still returns decoded content.";
+var UNKNOWN_KIND = "Could not determine file kind from name, MIME, or bytes; all features are reported as unsupported until the kind is known.";
+function slot(id, supported, warnings) {
+  return warnings?.length ? { id, supported, warnings } : { id, supported };
+}
+function buildNodeCapabilityReport(kind) {
+  const runtime = { id: "node" };
+  let capabilities;
+  const topWarnings = [];
+  switch (kind) {
+    case "pdf":
+      capabilities = [
+        slot("text", true, ["Includes text layer extraction; use extractText options to avoid PDF OCR."]),
+        slot("metadata", true),
+        slot("html", true, ["HTML is a <pre> preview of extracted text, not visual layout."]),
+        slot("ocr", true, ["Raster OCR is available (e.g. analyzeFile with pdf.ocr auto/force, or runOcr)."]),
+        slot("pages", true)
+      ];
+      break;
+    case "docx":
+      capabilities = [
+        slot("text", true),
+        slot("metadata", false, [DOCX_META]),
+        slot("html", true),
+        slot("ocr", false, ["OCR does not apply to DOCX in DocMind."]),
+        slot("pages", false)
+      ];
+      break;
+    case "image":
+      capabilities = [
+        slot("text", true, ["Text is obtained via OCR."]),
+        slot("metadata", false, [IMAGE_META]),
+        slot("html", false, [IMAGE_HTML]),
+        slot("ocr", true),
+        slot("pages", false)
+      ];
+      break;
+    case "text":
+      capabilities = [
+        slot("text", true),
+        slot("metadata", true, [TEXT_META_NOTE]),
+        slot("html", true),
+        slot("ocr", false, ["OCR does not apply to plain text files."]),
+        slot("pages", false)
+      ];
+      break;
+    default:
+      topWarnings.push(UNKNOWN_KIND);
+      capabilities = [
+        slot("text", false),
+        slot("metadata", false),
+        slot("html", false),
+        slot("ocr", false),
+        slot("pages", false)
+      ];
+  }
+  return {
+    kind,
+    runtime,
+    capabilities,
+    warnings: topWarnings.length > 0 ? topWarnings : void 0
+  };
+}
+
+// src/introspection.ts
+function resolvePdfOcrMode(pdf) {
+  return pdf?.ocr ?? "auto";
+}
+function planAnalyzeFile(kind, pdfOcr) {
+  switch (kind) {
+    case "pdf":
+      return {
+        intent: "analyzeFile",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "pdf_parse", status: "planned" },
+          {
+            id: "pdf_ocr",
+            status: pdfOcr === "off" ? "skipped" : "planned"
+          }
+        ]
+      };
+    case "docx":
+      return {
+        intent: "analyzeFile",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "docx_mammoth", status: "planned" }
+        ]
+      };
+    case "image":
+      return {
+        intent: "analyzeFile",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "image_ocr", status: "planned" }
+        ]
+      };
+    case "text":
+      return {
+        intent: "analyzeFile",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "utf8_decode", status: "planned" }
+        ]
+      };
+    default:
+      return {
+        intent: "analyzeFile",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "route", status: "failed" }
+        ]
+      };
+  }
+}
+function planForIntent(intentOpt, kind, pdfOcrForAnalyze) {
+  const intent = intentOpt ?? "analyzeFile";
+  if (intent === "analyzeFile") return planAnalyzeFile(kind, pdfOcrForAnalyze);
+  if (intent === "extractText") {
+    const p = planAnalyzeFile(kind, "off");
+    return { ...p, intent: "extractText" };
+  }
+  if (intent === "extractMetadata") {
+    if (kind === "pdf") {
+      return {
+        intent: "extractMetadata",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "pdf_metadata", status: "planned" }
+        ]
+      };
+    }
+    if (kind === "text") {
+      return {
+        intent: "extractMetadata",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "utf8_decode", status: "planned" }
+        ]
+      };
+    }
+    return {
+      intent: "extractMetadata",
+      steps: [
+        { id: "detect_kind", status: "done" },
+        { id: "metadata_stub", status: kind === "docx" || kind === "image" ? "planned" : "skipped" }
+      ]
+    };
+  }
+  if (intent === "convertToHtml") {
+    if (kind === "docx") {
+      return {
+        intent: "convertToHtml",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "docx_mammoth_html", status: "planned" }
+        ]
+      };
+    }
+    if (kind === "text") {
+      return {
+        intent: "convertToHtml",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "utf8_decode", status: "planned" },
+          { id: "wrap_pre", status: "planned" }
+        ]
+      };
+    }
+    if (kind === "pdf") {
+      return {
+        intent: "convertToHtml",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "pdf_text_layer", status: "planned" },
+          { id: "wrap_pre", status: "planned" }
+        ]
+      };
+    }
+    return {
+      intent: "convertToHtml",
+      steps: [
+        { id: "detect_kind", status: "done" },
+        { id: "rich_html", status: "skipped" }
+      ]
+    };
+  }
+  if (intent === "runOcr") {
+    if (kind === "pdf") {
+      return {
+        intent: "runOcr",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "pdf_parse", status: "planned" },
+          { id: "pdf_ocr_forced", status: "planned" }
+        ]
+      };
+    }
+    if (kind === "image") {
+      return {
+        intent: "runOcr",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "tesseract_ocr", status: "planned" }
+        ]
+      };
+    }
+    if (kind === "docx") {
+      return {
+        intent: "runOcr",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "docx_structured_extract", status: "planned" }
+        ]
+      };
+    }
+    return {
+      intent: "runOcr",
+      steps: [
+        { id: "detect_kind", status: "done" },
+        { id: "ocr", status: "skipped" }
+      ]
+    };
+  }
+  return planAnalyzeFile(kind, pdfOcrForAnalyze);
+}
+async function getCapabilities(input, options) {
+  throwIfAborted(options?.signal);
+  const resolved = await resolveNodeAnalyzeInput(input);
+  assertValidAnalyzeFileInput(resolved);
+  const kind = detectFileKind(resolved);
+  return buildNodeCapabilityReport(kind);
+}
+async function explainAnalysisPlan(input, options) {
+  throwIfAborted(options?.signal);
+  const resolved = await resolveNodeAnalyzeInput(input);
+  assertValidAnalyzeFileInput(resolved);
+  const kind = detectFileKind(resolved);
+  const intent = options?.intent ?? "analyzeFile";
+  const pdfOcrAnalyze = resolvePdfOcrMode(options?.pdf);
+  const plan = planForIntent(intent, kind, pdfOcrAnalyze);
+  return buildNodeExplainReport(kind, intent, pdfOcrAnalyze, plan);
+}
+
+export { analyzeFile, bufferToInput, convertToHtml, explainAnalysisPlan, extractMetadata, extractText, getCapabilities, readFileToInput, resolveNodeAnalyzeInput, runOcr };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dragon708/docmind-node",
-  "version": "1.0.0",
-  "description": "Node.js DocMind entry: PDF, DOCX, OCR, text, and fs helpers.",
+  "version": "1.2.0",
+  "description": "Official DocMind Node facade: analyzeFile, intent APIs, PDF/DOCX/OCR, and fs helpers.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -14,7 +14,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
   ],
   "publishConfig": {
     "access": "public"
@@ -34,7 +35,7 @@
     "@dragon708/docmind-docx": "^1.0.0",
     "@dragon708/docmind-ocr": "^1.0.0",
     "@dragon708/docmind-pdf": "^1.0.0",
-    "@dragon708/docmind-shared": "^1.0.0"
+    "@dragon708/docmind-shared": "^1.1.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.37",

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/inputBytes.ts","../src/analyzers/docx.ts","../src/analyzers/image.ts","../src/analyzers/pdf.ts","../src/resolveNodeInput.ts","../src/analyze.ts"],"names":["extractDocx","runPdf"],"mappings":"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","file":"index.js","sourcesContent":["import type { DetectFileKindInput, FileLikeInput } from \"@dragon708/docmind-shared\";\nimport {\n  isBinaryInput,\n  isBlob,\n  isFile,\n  isNamedInput,\n  toUint8Array,\n} from \"@dragon708/docmind-shared\";\n\nexport function isByteBackedInput(input: DetectFileKindInput): input is FileLikeInput {\n  return isNamedInput(input) || isBinaryInput(input) || isBlob(input) || isFile(input);\n}\n\n/** Resolves bytes when the input carries a body; otherwise an empty `Uint8Array`. */\nexport async function bytesFromDetectInput(input: DetectFileKindInput): Promise<Uint8Array> {\n  if (!isByteBackedInput(input)) {\n    return new Uint8Array(0);\n  }\n  return toUint8Array(input);\n}\n","import { analyzeDocx as extractDocx } from \"@dragon708/docmind-docx\";\nimport type { AnalysisResult, DetectFileKindInput } from \"@dragon708/docmind-shared\";\nimport { bytesFromDetectInput } from \"../inputBytes.js\";\n\n/**\n * DOCX → `@dragon708/docmind-docx`.\n */\nexport async function analyzeDocxForNode(\n  input: DetectFileKindInput,\n  signal?: AbortSignal,\n): Promise<AnalysisResult> {\n  if (signal?.aborted) {\n    const err = new Error(\"The operation was aborted\");\n    err.name = \"AbortError\";\n    throw err;\n  }\n\n  const data = await bytesFromDetectInput(input);\n  if (data.byteLength === 0) {\n    return {\n      fileKind: \"docx\",\n      analyzer: \"docx\",\n      status: \"ok\",\n      kind: \"docx\",\n      text: \"\",\n      html: \"\",\n      warnings: [\"No document bytes were provided for analysis.\"],\n    };\n  }\n\n  const r = await extractDocx(data);\n  return {\n    fileKind: \"docx\",\n    analyzer: \"docx\",\n    status: \"ok\",\n    kind: \"docx\",\n    text: r.text,\n    html: r.html,\n    warnings: [...r.warnings],\n  };\n}\n","import { ocr } from \"@dragon708/docmind-ocr\";\nimport type { AnalysisResult, DetectFileKindInput } from \"@dragon708/docmind-shared\";\nimport type { NodeAnalyzeOptions } from \"../nodeAnalyzeOptions.js\";\nimport { bytesFromDetectInput } from \"../inputBytes.js\";\n\n/**\n * Image → `@dragon708/docmind-ocr`.\n */\nexport async function analyzeImageForNode(\n  input: DetectFileKindInput,\n  options?: NodeAnalyzeOptions,\n): Promise<AnalysisResult> {\n  if (options?.signal?.aborted) {\n    const err = new Error(\"The operation was aborted\");\n    err.name = \"AbortError\";\n    throw err;\n  }\n\n  const data = await bytesFromDetectInput(input);\n  if (data.byteLength === 0) {\n    return {\n      fileKind: \"image\",\n      analyzer: \"image\",\n      status: \"ok\",\n      kind: \"image\",\n      text: \"\",\n      confidence: 0,\n      ocrUsed: true,\n      warnings: [\"No image bytes were provided for analysis.\"],\n    };\n  }\n\n  const ocrOpts = {\n    ...(options?.ocr ?? {}),\n    signal: options?.ocr?.signal ?? options?.signal,\n  };\n\n  const r = await ocr(data, ocrOpts);\n  return {\n    fileKind: \"image\",\n    analyzer: \"image\",\n    status: \"ok\",\n    kind: \"image\",\n    text: r.text,\n    confidence: r.confidence,\n    ocrUsed: r.ocrUsed,\n    warnings: [],\n  };\n}\n","import { analyzePdf as runPdf } from \"@dragon708/docmind-pdf\";\nimport type { PdfAnalyzeOptions } from \"@dragon708/docmind-pdf\";\nimport type { AnalysisResult, DetectFileKindInput } from \"@dragon708/docmind-shared\";\nimport type { NodeAnalyzeOptions } from \"../nodeAnalyzeOptions.js\";\nimport { bytesFromDetectInput } from \"../inputBytes.js\";\n\n/**\n * PDF → `@dragon708/docmind-pdf` (Node / pdf-parse + OCR).\n *\n * Unlike `analyzePdf` from `@dragon708/docmind-pdf` (OCR off unless set), `analyzeFile` defaults\n * to `pdf.ocr: \"auto\"`: when the PDF has\n * pages but almost no extractable text (typical scan), the raster OCR pipeline runs. Pass\n * `pdf: { ocr: \"off\" }` to skip OCR for speed.\n */\nexport async function analyzePdfForNode(\n  input: DetectFileKindInput,\n  options?: NodeAnalyzeOptions,\n): Promise<AnalysisResult> {\n  if (options?.signal?.aborted) {\n    const err = new Error(\"The operation was aborted\");\n    err.name = \"AbortError\";\n    throw err;\n  }\n\n  const data = await bytesFromDetectInput(input);\n  if (data.byteLength === 0) {\n    return {\n      fileKind: \"pdf\",\n      analyzer: \"pdf\",\n      status: \"ok\",\n      kind: \"pdf\",\n      text: \"\",\n      pages: 0,\n      metadata: { info: {} },\n      warnings: [\"No document bytes were provided for analysis.\"],\n      needsOCR: false,\n      ocrUsed: false,\n    };\n  }\n\n  const userPdf = options?.pdf;\n  const pdfOpts: PdfAnalyzeOptions = {\n    ...userPdf,\n    ocr: userPdf?.ocr ?? \"auto\",\n    ocrLangs: userPdf?.ocrLangs ?? options?.ocr?.langs,\n    signal: userPdf?.signal ?? options?.signal,\n  };\n\n  const r = await runPdf(data, pdfOpts);\n  return {\n    fileKind: \"pdf\",\n    analyzer: \"pdf\",\n    status: \"ok\",\n    kind: \"pdf\",\n    text: r.text,\n    pages: r.pages,\n    metadata: r.metadata,\n    warnings: [...r.warnings],\n    needsOCR: r.needsOCR,\n    ocrUsed: r.ocrUsed,\n  };\n}\n","import type { DetectFileKindInput, NamedInput } from \"@dragon708/docmind-shared\";\nimport { readFile } from \"node:fs/promises\";\nimport { basename } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\n/**\n * Inputs accepted by {@link analyzeFile} in this package.\n * Paths and `file:` URLs are read with `fs`; other values pass through as {@link DetectFileKindInput}.\n */\nexport type NodeAnalyzeInput = string | URL | DetectFileKindInput;\n\nfunction toPathString(pathOrUrl: string | URL): string {\n  return pathOrUrl instanceof URL ? fileURLToPath(pathOrUrl) : pathOrUrl;\n}\n\n/**\n * Reads a file from disk into a {@link NamedInput} (binary `Buffer`, basename as `name` for hints).\n */\nexport async function readFileToInput(path: string | URL): Promise<NamedInput<Buffer>> {\n  const fsPath = toPathString(path);\n  const data = await readFile(fsPath);\n  return {\n    data,\n    name: basename(fsPath),\n  };\n}\n\n/** Wraps a `Buffer` as a named payload when you already know the filename. */\nexport function bufferToInput(buffer: Buffer, name?: string): NamedInput<Buffer> {\n  return name !== undefined ? { data: buffer, name } : { data: buffer };\n}\n\n/**\n * Resolves paths / `file:` URLs to a {@link DetectFileKindInput}; leaves other values untouched.\n */\nexport async function resolveNodeAnalyzeInput(input: NodeAnalyzeInput): Promise<DetectFileKindInput> {\n  if (typeof input === \"string\" || input instanceof URL) {\n    return readFileToInput(input);\n  }\n  return input;\n}\n","import type { AnalysisResult, DetectFileKindInput } from \"@dragon708/docmind-shared\";\nimport {\n  analyzeText,\n  assertValidAnalyzeFileInput,\n  detectFileKind,\n  notImplementedResult,\n  UNKNOWN_FORMAT_WARNING,\n} from \"@dragon708/docmind-shared\";\nimport { analyzeDocxForNode } from \"./analyzers/docx.js\";\nimport { analyzeImageForNode } from \"./analyzers/image.js\";\nimport { analyzePdfForNode } from \"./analyzers/pdf.js\";\nimport type { NodeAnalyzeOptions } from \"./nodeAnalyzeOptions.js\";\nimport { resolveNodeAnalyzeInput, type NodeAnalyzeInput } from \"./resolveNodeInput.js\";\n\n/**\n * Node router: PDF, DOCX, images (OCR), and text. Paths and `file:` URLs are read via `fs`.\n */\nexport async function analyzeFile(\n  input: NodeAnalyzeInput,\n  options?: NodeAnalyzeOptions,\n): Promise<AnalysisResult> {\n  if (options?.signal?.aborted) {\n    const err = new Error(\"The operation was aborted\");\n    err.name = \"AbortError\";\n    throw err;\n  }\n\n  const resolved = await resolveNodeAnalyzeInput(input);\n  assertValidAnalyzeFileInput(resolved);\n\n  const fileKind = detectFileKind(resolved);\n\n  switch (fileKind) {\n    case \"pdf\":\n      return analyzePdfForNode(resolved as DetectFileKindInput, options);\n    case \"docx\":\n      return analyzeDocxForNode(resolved as DetectFileKindInput, options?.signal);\n    case \"image\":\n      return analyzeImageForNode(resolved as DetectFileKindInput, options);\n    case \"text\":\n      return analyzeText(resolved as DetectFileKindInput, { signal: options?.signal });\n    default:\n      return notImplementedResult(fileKind, \"none\", [UNKNOWN_FORMAT_WARNING]);\n  }\n}\n"]}