@effortlessmotion/pdf-to-md 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/dist/cjs/analyze.js.map +1 -1
  2. package/dist/cjs/audit.js.map +1 -1
  3. package/dist/cjs/cli/audit.js.map +1 -1
  4. package/dist/cjs/cli/extract.js.map +1 -1
  5. package/dist/cjs/cli/index.js.map +1 -1
  6. package/dist/cjs/cli/render.js.map +1 -1
  7. package/dist/cjs/cli/types.js.map +1 -1
  8. package/dist/cjs/cli.js.map +1 -1
  9. package/dist/cjs/collect.js.map +1 -1
  10. package/dist/cjs/dict.js.map +1 -1
  11. package/dist/cjs/emit.js.map +1 -1
  12. package/dist/cjs/engines/tesseract.js.map +1 -1
  13. package/dist/cjs/errors.js.map +1 -1
  14. package/dist/cjs/extract.js.map +1 -1
  15. package/dist/cjs/geometry.js.map +1 -1
  16. package/dist/cjs/index.js.map +1 -1
  17. package/dist/cjs/lines.js.map +1 -1
  18. package/dist/cjs/markdown.js.map +1 -1
  19. package/dist/cjs/page-marker.js.map +1 -1
  20. package/dist/cjs/pdf-open.js.map +1 -1
  21. package/dist/cjs/raster.js.map +1 -1
  22. package/dist/cjs/render-analysis.js.map +1 -1
  23. package/dist/cjs/report.js.map +1 -1
  24. package/dist/cjs/resolve.js.map +1 -1
  25. package/dist/cjs/text-analysis.js.map +1 -1
  26. package/dist/cjs/types.js.map +1 -1
  27. package/dist/cjs/validate.js.map +1 -1
  28. package/dist/esm/analyze.js.map +1 -1
  29. package/dist/esm/audit.js.map +1 -1
  30. package/dist/esm/cli/audit.js.map +1 -1
  31. package/dist/esm/cli/extract.js.map +1 -1
  32. package/dist/esm/cli/index.js.map +1 -1
  33. package/dist/esm/cli/render.js.map +1 -1
  34. package/dist/esm/cli/types.js.map +1 -1
  35. package/dist/esm/cli.js.map +1 -1
  36. package/dist/esm/collect.js.map +1 -1
  37. package/dist/esm/dict.js.map +1 -1
  38. package/dist/esm/emit.js.map +1 -1
  39. package/dist/esm/engines/tesseract.js.map +1 -1
  40. package/dist/esm/errors.js.map +1 -1
  41. package/dist/esm/extract.js.map +1 -1
  42. package/dist/esm/geometry.js.map +1 -1
  43. package/dist/esm/index.js.map +1 -1
  44. package/dist/esm/lines.js.map +1 -1
  45. package/dist/esm/markdown.js.map +1 -1
  46. package/dist/esm/page-marker.js.map +1 -1
  47. package/dist/esm/pdf-open.js.map +1 -1
  48. package/dist/esm/raster.js.map +1 -1
  49. package/dist/esm/render-analysis.js.map +1 -1
  50. package/dist/esm/report.js.map +1 -1
  51. package/dist/esm/resolve.js.map +1 -1
  52. package/dist/esm/text-analysis.js.map +1 -1
  53. package/dist/esm/types.js.map +1 -1
  54. package/dist/esm/validate.js.map +1 -1
  55. package/package.json +2 -3
  56. package/skills/pdf-to-md/SKILL.md +0 -75
@@ -1 +1 @@
1
- {"version":3,"sources":["/Users/kevin/Dev/OpenSource/formats/pdf-to-md/src/types.ts"],"sourcesContent":["// Shared shapes threaded through the collect -> lines -> markdown -> report\n// pipeline; kept in one place since every downstream stage uses at least one.\n\n/** Viewport-point AABB for a source text run's transformed advance by\n * font-height box. This is a run box, not fabricated per-token geometry. */\nexport interface GlyphBounds {\n x: number;\n y: number;\n w: number;\n h: number;\n}\n\n// A positioned glyph run from the PDF's text layer: `s` may be more than one\n// character. x/y are the transformed baseline origin in viewport points;\n// w/h are its advance and font height, and bounds is their viewport AABB.\nexport interface Glyph {\n s: string;\n x: number;\n y: number;\n w: number;\n h: number;\n bounds: GlyphBounds;\n}\n\n// One page's worth of collected glyphs plus the geometry collect.ts needs\n// downstream (lines.ts's two-column detection, report.ts's hybrid-page flag).\nexport interface CollectedPage {\n page: number;\n glyphs: Glyph[];\n width: number;\n height: number;\n textChars: number;\n /** any painted image operator, independent of text-layer density */\n hasImage: boolean;\n largeImage: boolean;\n}\n\n// collect.ts's return value: selected pages plus the char-weighted\n// font-height histogram, built ONLY from those pages (matters for a `--pages` re-extraction — see collect.ts).\nexport interface CollectResult {\n numPages: number;\n pages: CollectedPage[];\n heightChars: Map<number, number>;\n}\n\n// A visual line assembled from glyphs (lines.ts's `toLines`): `h` is the\n// char-weighted dominant height (not max); `col` is 0 (left/only) or 1 (right, de-braided page).\nexport interface Line {\n text: string;\n x: number;\n y: number;\n h: number;\n col: number;\n /** indexes of the collected PDF text runs that produced this line, in\n * display order. OCR has its own source-word linkage. */\n wordIndexes: number[];\n}\n\n// One page's lines, as src/extract.ts assembles them for buildMarkdown.\nexport interface PageLines {\n page: number;\n lines: Line[];\n}\n\nexport interface BuildMarkdownOptions {\n pageMarkers?: boolean;\n}\n\n// Running counters src/markdown.ts accumulates while building the output,\n// surfaced in the QA report (src/report.ts's buildReport).\nexport interface MarkdownStats {\n headings: number;\n listItems: number;\n paragraphs: number;\n joinedPairs: number;\n reflowed: number;\n callouts: number;\n closedHyphens: number;\n}\n\nexport interface MarkdownResult {\n md: string;\n stats: MarkdownStats;\n bodyH: number;\n headingSizes: number[];\n /** The structural blocks that produced `md`, grouped by source page.\n * Markers are rendering provenance and are deliberately not blocks. */\n pages: MarkdownPage[];\n}\n\n/** One row of the per-page QA breakdown (\"### pN\" blocks) — used to decide\n * which pages are worth rendering and re-checking (README's \"Design contract\"). */\nexport interface PageStatsRow {\n page: number;\n /** producer retained for this page, including in a mixed result */\n path: 'text' | 'ocr';\n chars: number;\n headings: number;\n junkHeadings: number;\n floats: number;\n paragraphs: number;\n danglingLong: number;\n danglingShort: number;\n /** count of `> [review: ...]` lines — blocks the geometry could not order\n * and labeled instead of guessing (README's \"Design contract\"). */\n reviewBlocks: number;\n /** present only on the text path's rows; omitted (not `false`) on the OCR\n * path, which has no per-page hybrid-image signal. */\n largeImages?: boolean;\n /** count of words below `report.ts`'s LOW_CONFIDENCE_THRESHOLD; omitted (not\n * 0) when the page had no confidence data at all, so \"measured 0\" and \"nothing to measure\" stay distinct. */\n lowConfidenceWords?: number;\n /** the suspect tokens behind `lowConfidenceWords`, worst-confidence first\n * and capped (`report.ts`'s LOW_CONFIDENCE_SAMPLE_CAP) so a chart-heavy page can't bloat the JSON. */\n lowConfidenceSample?: string[];\n}\n\n// buildReport's params (src/report.ts) — everything the text (default) path\n// hands over after running collect -> lines -> markdown.\nexport interface BuildReportInput {\n numPages: number;\n md: string;\n /** identical to `md` but always carries \"### pN\" markers, so pageStats is\n * measured independent of the caller's `--page-markers` choice; same string as `md` when markers were requested. */\n statsMd: string;\n stats: MarkdownStats;\n bodyH: number;\n headingSizes: number[];\n hybridPages?: number[];\n}\n\n/** One recognized word's page/text/confidence — `report.ts`'s low-confidence\n * detector input; a structural subset of OcrWordInput kept here so `types.ts` doesn't import the library-layer module that depends on it. */\nexport interface WordConfidenceInput {\n page: number;\n text: string;\n confidence?: number;\n}\n\nexport interface BuildOcrReportInput {\n md: string;\n fallback?: boolean;\n /** Per-page producer map for a mixed result. Omit for OCR-only output. */\n pagePaths?: Map<number, 'text' | 'ocr'>;\n /** text pages retaining a large embedded image, for mixed per-page QA */\n hybridPages?: number[];\n /** every recognized word, for `report.ts`'s low-confidence detector.\n * Defaults to [] (a pre-confidence --words-json replay), reporting the detector absent, never wrong. */\n words?: WordConfidenceInput[];\n}\n\n/** Per-document and per-page QA metrics returned by every extraction entry\n * point, discriminated by `path`; OCR-only and text-only fields are grouped below. */\nexport interface Report {\n /** manually-bumped integer (not the npm package version) — see\n * `report.ts`'s OUTPUT_VERSION for the bump rule; present on every Report so a frozen baseline's staleness is self-announcing. */\n outputVersion: number;\n path: 'text' | 'ocr' | 'mixed';\n pages: number;\n chars: number;\n charsPerPage: number;\n sparse: boolean;\n headings: number;\n junkHeadings: number;\n paragraphs: number;\n callouts: number;\n danglingLong: number;\n danglingShort: number;\n /** total `> [review: ...]` blocks across all pages (sum of pageStats'\n * reviewBlocks); always 0 on the text path — only the OCR path emits review markers. */\n reviewBlocks: number;\n /** document-level sum of pageStats' `lowConfidenceWords` — see that\n * field for why 0 can mean \"measured 0\" or \"nothing to measure\". */\n lowConfidenceWords: number;\n pageStats: PageStatsRow[];\n\n // --- OCR-only ---\n floats?: number;\n ocrFallback?: boolean;\n\n // --- text-only ---\n bodyFontHeight?: number;\n headingSizes?: number[];\n listItems?: number;\n joinedPairs?: number;\n closedHyphens?: number;\n hybridPages?: number[];\n}\n\n// --- Analysis: the raw-mode IR (analyze() produces it; toMarkdown()/toText()\n// in render-analysis.ts render it — see toMarkdown's doc comment for the fail-fast validation contract) ---\n\n/** One recognized/collected word, page-relative; `box` is always present.\n * See `AnalysisPage.words` for the coordinate contract and per-path granularity difference. */\nexport interface AnalysisWord {\n text: string;\n box: { x: number; y: number; w: number; h: number };\n confidence?: number;\n}\n\n/** One structural block; `wordIndexes` links it to its page's `words` list (blocks -> words only).\n * `text` is bare content for `'heading'` (level separate), else the LITERAL markdown line (decoration included, round-trippable) — a pull-quote is `'paragraph'`, not a 5th type. */\nexport interface AnalysisBlock {\n type: 'heading' | 'paragraph' | 'float' | 'review';\n text: string;\n /** Heading level (integer 1-6); REQUIRED when `type` is `'heading'`,\n * FORBIDDEN otherwise — toMarkdown()/toText() validate this fail-fast (throws PdfToMdError/'ANALYSIS_INPUT'), never silently ignored. */\n level?: number;\n /** adjacent Markdown line with no blank separator, used for list items */\n tight?: boolean;\n wordIndexes: number[];\n}\n\n/** One page's flat words plus its structural blocks. */\nexport interface AnalysisPage {\n page: number;\n /** producer retained for this page; `Analysis.report.path` is `'mixed'`\n * when the document has more than one page producer. */\n path: 'text' | 'ocr';\n /** Flat, page-relative source items; `AnalysisBlock.wordIndexes` indexes\n * into it. OCR boxes are normalized [0,1]. Text-run boxes are page\n * fractions and may extend outside that range when the PDF run extends past\n * the viewport. Both use a bottom-left origin with y up. */\n words: AnalysisWord[];\n blocks: AnalysisBlock[];\n}\n\n/** analyze()'s output: plain, JSON-serializable per-page words/blocks plus\n * the same QA `report` the other entry points return. */\nexport interface Analysis {\n /** manually-bumped integer — see `Report.outputVersion` / `report.ts`'s OUTPUT_VERSION. */\n outputVersion: number;\n /** the same QA report extractText/extractOcr/pdfToMarkdown return, always\n * measured off real markdown (OCR: the shared core's output; TEXT: buildMarkdown's reflowed output, not this coarser IR) — never stale relative to the IR. */\n report: Report;\n pages: AnalysisPage[];\n}\n\n/** One page's blocks from the text Markdown builder. This is internal\n * rendering evidence, but it is declared here because the shared text\n * analysis consumes it without parsing Markdown back into structure. */\nexport interface MarkdownPage {\n page: number;\n blocks: AnalysisBlock[];\n}\n"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,8EAA8E;AAE9E;0EAC0E,GA0O1E;;sEAEsE,GACtE,WAGC"}
1
+ {"version":3,"sources":["/Users/kevin/Dev/open-source/formats/pdf-to-md/src/types.ts"],"sourcesContent":["// Shared shapes threaded through the collect -> lines -> markdown -> report\n// pipeline; kept in one place since every downstream stage uses at least one.\n\n/** Viewport-point AABB for a source text run's transformed advance by\n * font-height box. This is a run box, not fabricated per-token geometry. */\nexport interface GlyphBounds {\n x: number;\n y: number;\n w: number;\n h: number;\n}\n\n// A positioned glyph run from the PDF's text layer: `s` may be more than one\n// character. x/y are the transformed baseline origin in viewport points;\n// w/h are its advance and font height, and bounds is their viewport AABB.\nexport interface Glyph {\n s: string;\n x: number;\n y: number;\n w: number;\n h: number;\n bounds: GlyphBounds;\n}\n\n// One page's worth of collected glyphs plus the geometry collect.ts needs\n// downstream (lines.ts's two-column detection, report.ts's hybrid-page flag).\nexport interface CollectedPage {\n page: number;\n glyphs: Glyph[];\n width: number;\n height: number;\n textChars: number;\n /** any painted image operator, independent of text-layer density */\n hasImage: boolean;\n largeImage: boolean;\n}\n\n// collect.ts's return value: selected pages plus the char-weighted\n// font-height histogram, built ONLY from those pages (matters for a `--pages` re-extraction — see collect.ts).\nexport interface CollectResult {\n numPages: number;\n pages: CollectedPage[];\n heightChars: Map<number, number>;\n}\n\n// A visual line assembled from glyphs (lines.ts's `toLines`): `h` is the\n// char-weighted dominant height (not max); `col` is 0 (left/only) or 1 (right, de-braided page).\nexport interface Line {\n text: string;\n x: number;\n y: number;\n h: number;\n col: number;\n /** indexes of the collected PDF text runs that produced this line, in\n * display order. OCR has its own source-word linkage. */\n wordIndexes: number[];\n}\n\n// One page's lines, as src/extract.ts assembles them for buildMarkdown.\nexport interface PageLines {\n page: number;\n lines: Line[];\n}\n\nexport interface BuildMarkdownOptions {\n pageMarkers?: boolean;\n}\n\n// Running counters src/markdown.ts accumulates while building the output,\n// surfaced in the QA report (src/report.ts's buildReport).\nexport interface MarkdownStats {\n headings: number;\n listItems: number;\n paragraphs: number;\n joinedPairs: number;\n reflowed: number;\n callouts: number;\n closedHyphens: number;\n}\n\nexport interface MarkdownResult {\n md: string;\n stats: MarkdownStats;\n bodyH: number;\n headingSizes: number[];\n /** The structural blocks that produced `md`, grouped by source page.\n * Markers are rendering provenance and are deliberately not blocks. */\n pages: MarkdownPage[];\n}\n\n/** One row of the per-page QA breakdown (\"### pN\" blocks) — used to decide\n * which pages are worth rendering and re-checking (README's \"Design contract\"). */\nexport interface PageStatsRow {\n page: number;\n /** producer retained for this page, including in a mixed result */\n path: 'text' | 'ocr';\n chars: number;\n headings: number;\n junkHeadings: number;\n floats: number;\n paragraphs: number;\n danglingLong: number;\n danglingShort: number;\n /** count of `> [review: ...]` lines — blocks the geometry could not order\n * and labeled instead of guessing (README's \"Design contract\"). */\n reviewBlocks: number;\n /** present only on the text path's rows; omitted (not `false`) on the OCR\n * path, which has no per-page hybrid-image signal. */\n largeImages?: boolean;\n /** count of words below `report.ts`'s LOW_CONFIDENCE_THRESHOLD; omitted (not\n * 0) when the page had no confidence data at all, so \"measured 0\" and \"nothing to measure\" stay distinct. */\n lowConfidenceWords?: number;\n /** the suspect tokens behind `lowConfidenceWords`, worst-confidence first\n * and capped (`report.ts`'s LOW_CONFIDENCE_SAMPLE_CAP) so a chart-heavy page can't bloat the JSON. */\n lowConfidenceSample?: string[];\n}\n\n// buildReport's params (src/report.ts) — everything the text (default) path\n// hands over after running collect -> lines -> markdown.\nexport interface BuildReportInput {\n numPages: number;\n md: string;\n /** identical to `md` but always carries \"### pN\" markers, so pageStats is\n * measured independent of the caller's `--page-markers` choice; same string as `md` when markers were requested. */\n statsMd: string;\n stats: MarkdownStats;\n bodyH: number;\n headingSizes: number[];\n hybridPages?: number[];\n}\n\n/** One recognized word's page/text/confidence — `report.ts`'s low-confidence\n * detector input; a structural subset of OcrWordInput kept here so `types.ts` doesn't import the library-layer module that depends on it. */\nexport interface WordConfidenceInput {\n page: number;\n text: string;\n confidence?: number;\n}\n\nexport interface BuildOcrReportInput {\n md: string;\n fallback?: boolean;\n /** Per-page producer map for a mixed result. Omit for OCR-only output. */\n pagePaths?: Map<number, 'text' | 'ocr'>;\n /** text pages retaining a large embedded image, for mixed per-page QA */\n hybridPages?: number[];\n /** every recognized word, for `report.ts`'s low-confidence detector.\n * Defaults to [] (a pre-confidence --words-json replay), reporting the detector absent, never wrong. */\n words?: WordConfidenceInput[];\n}\n\n/** Per-document and per-page QA metrics returned by every extraction entry\n * point, discriminated by `path`; OCR-only and text-only fields are grouped below. */\nexport interface Report {\n /** manually-bumped integer (not the npm package version) — see\n * `report.ts`'s OUTPUT_VERSION for the bump rule; present on every Report so a frozen baseline's staleness is self-announcing. */\n outputVersion: number;\n path: 'text' | 'ocr' | 'mixed';\n pages: number;\n chars: number;\n charsPerPage: number;\n sparse: boolean;\n headings: number;\n junkHeadings: number;\n paragraphs: number;\n callouts: number;\n danglingLong: number;\n danglingShort: number;\n /** total `> [review: ...]` blocks across all pages (sum of pageStats'\n * reviewBlocks); always 0 on the text path — only the OCR path emits review markers. */\n reviewBlocks: number;\n /** document-level sum of pageStats' `lowConfidenceWords` — see that\n * field for why 0 can mean \"measured 0\" or \"nothing to measure\". */\n lowConfidenceWords: number;\n pageStats: PageStatsRow[];\n\n // --- OCR-only ---\n floats?: number;\n ocrFallback?: boolean;\n\n // --- text-only ---\n bodyFontHeight?: number;\n headingSizes?: number[];\n listItems?: number;\n joinedPairs?: number;\n closedHyphens?: number;\n hybridPages?: number[];\n}\n\n// --- Analysis: the raw-mode IR (analyze() produces it; toMarkdown()/toText()\n// in render-analysis.ts render it — see toMarkdown's doc comment for the fail-fast validation contract) ---\n\n/** One recognized/collected word, page-relative; `box` is always present.\n * See `AnalysisPage.words` for the coordinate contract and per-path granularity difference. */\nexport interface AnalysisWord {\n text: string;\n box: { x: number; y: number; w: number; h: number };\n confidence?: number;\n}\n\n/** One structural block; `wordIndexes` links it to its page's `words` list (blocks -> words only).\n * `text` is bare content for `'heading'` (level separate), else the LITERAL markdown line (decoration included, round-trippable) — a pull-quote is `'paragraph'`, not a 5th type. */\nexport interface AnalysisBlock {\n type: 'heading' | 'paragraph' | 'float' | 'review';\n text: string;\n /** Heading level (integer 1-6); REQUIRED when `type` is `'heading'`,\n * FORBIDDEN otherwise — toMarkdown()/toText() validate this fail-fast (throws PdfToMdError/'ANALYSIS_INPUT'), never silently ignored. */\n level?: number;\n /** adjacent Markdown line with no blank separator, used for list items */\n tight?: boolean;\n wordIndexes: number[];\n}\n\n/** One page's flat words plus its structural blocks. */\nexport interface AnalysisPage {\n page: number;\n /** producer retained for this page; `Analysis.report.path` is `'mixed'`\n * when the document has more than one page producer. */\n path: 'text' | 'ocr';\n /** Flat, page-relative source items; `AnalysisBlock.wordIndexes` indexes\n * into it. OCR boxes are normalized [0,1]. Text-run boxes are page\n * fractions and may extend outside that range when the PDF run extends past\n * the viewport. Both use a bottom-left origin with y up. */\n words: AnalysisWord[];\n blocks: AnalysisBlock[];\n}\n\n/** analyze()'s output: plain, JSON-serializable per-page words/blocks plus\n * the same QA `report` the other entry points return. */\nexport interface Analysis {\n /** manually-bumped integer — see `Report.outputVersion` / `report.ts`'s OUTPUT_VERSION. */\n outputVersion: number;\n /** the same QA report extractText/extractOcr/pdfToMarkdown return, always\n * measured off real markdown (OCR: the shared core's output; TEXT: buildMarkdown's reflowed output, not this coarser IR) — never stale relative to the IR. */\n report: Report;\n pages: AnalysisPage[];\n}\n\n/** One page's blocks from the text Markdown builder. This is internal\n * rendering evidence, but it is declared here because the shared text\n * analysis consumes it without parsing Markdown back into structure. */\nexport interface MarkdownPage {\n page: number;\n blocks: AnalysisBlock[];\n}\n"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,8EAA8E;AAE9E;0EAC0E,GA0O1E;;sEAEsE,GACtE,WAGC"}
@@ -1 +1 @@
1
- {"version":3,"sources":["/Users/kevin/Dev/OpenSource/formats/pdf-to-md/src/validate.ts"],"sourcesContent":["// validate.ts — input-shape validation shared by analyze.ts and extract.ts,\n// kept out of both to dodge their value-level import cycle (extract.ts imports analyze.ts's buildOcrAnalysisPages; both need this).\nimport { PdfToMdError } from './errors.ts';\nimport type { OcrWordInput } from './extract.ts';\n\n/** Validates the one option every entry point accepts before touching the\n * PDF. Type-only import from `extract.ts` keeps this cycle-free. */\nexport function validatePages(pages: unknown): void {\n if (pages === undefined) return;\n const isRecord = typeof pages === 'object' && pages !== null;\n const first = isRecord ? (pages as Record<string, unknown>).first : undefined;\n const last = isRecord ? (pages as Record<string, unknown>).last : undefined;\n const firstOk = typeof first === 'number' && Number.isFinite(first) && first >= 1;\n const lastOk = last === undefined || (typeof last === 'number' && Number.isFinite(last) && last >= (first as number));\n if (!isRecord || !firstOk || !lastOk) {\n throw new PdfToMdError('PAGE_RANGE', `pages option must be { first: number, last?: number } with first >= 1 and last >= first (got ${JSON.stringify(pages)})`);\n }\n}\n\n/** Validates analyze()'s non-string `input` branch (`{ words }`) before\n * `.words` is read, so a plain-JS mistake like `analyze(null)` throws PdfToMdError/WORDS_INPUT instead of a raw TypeError. */\nexport function validateWordsInput(input: unknown): OcrWordInput[] {\n const isRecord = typeof input === 'object' && input !== null;\n const words = isRecord ? (input as Record<string, unknown>).words : undefined;\n if (!Array.isArray(words)) {\n throw new PdfToMdError('WORDS_INPUT', `analyze() input must be a pdf path (string) or { words: OcrWordInput[] } (got ${isRecord ? JSON.stringify(input) : String(input)})`);\n }\n return words as OcrWordInput[];\n}\n\n/** Runtime shape guard for `buildOcrAnalysisPages`'s input: a plain-JS\n * caller bypasses the TS union, so this turns a raw TypeError into PdfToMdError before any property is read off it. */\nexport function validateOcrAnalysisInput(input: unknown): { pdfPath: string } | { words: OcrWordInput[] } {\n if (typeof input === 'string') {\n throw new PdfToMdError('PDF_OPEN', `extractOcr/analyze input must be { pdfPath: string } or { words: OcrWordInput[] }, not a bare path string (got ${JSON.stringify(input)}) — did you mean { pdfPath: ${JSON.stringify(input)} }?`);\n }\n const isRecord = typeof input === 'object' && input !== null;\n const rawPdfPath = isRecord ? (input as Record<string, unknown>).pdfPath : undefined;\n const rawWords = isRecord ? (input as Record<string, unknown>).words : undefined;\n if (!isRecord || (rawPdfPath === undefined && rawWords === undefined)) {\n throw new PdfToMdError('WORDS_INPUT', `extractOcr/analyze input must be { pdfPath: string } or { words: OcrWordInput[] } (got ${isRecord ? JSON.stringify(input) : String(input)})`);\n }\n if (rawWords !== undefined && !Array.isArray(rawWords)) {\n throw new PdfToMdError('WORDS_INPUT', `extractOcr/analyze { words } input must be an array (got ${JSON.stringify(rawWords)})`);\n }\n if (rawPdfPath !== undefined && typeof rawPdfPath !== 'string') {\n throw new PdfToMdError('PDF_OPEN', `extractOcr/analyze { pdfPath } input must be a string (got ${JSON.stringify(rawPdfPath)})`);\n }\n if (rawWords !== undefined) {\n for (const w of rawWords as unknown[]) {\n const rec = w as Record<string, unknown>;\n if (typeof rec.page !== 'number' || typeof rec.text !== 'string' || typeof rec.x !== 'number' || typeof rec.y !== 'number' || typeof rec.w !== 'number' || typeof rec.h !== 'number') {\n throw new PdfToMdError('WORDS_INPUT', `malformed word entry (need {page, text, x, y, w, h}): ${JSON.stringify(w)}`);\n }\n }\n return { words: rawWords as OcrWordInput[] };\n }\n return { pdfPath: rawPdfPath as string };\n}\n"],"names":["PdfToMdError","validatePages","pages","undefined","isRecord","first","last","firstOk","Number","isFinite","lastOk","JSON","stringify","validateWordsInput","input","words","Array","isArray","String","validateOcrAnalysisInput","rawPdfPath","pdfPath","rawWords","w","rec","page","text","x","y","h"],"mappings":"AAAA,4EAA4E;AAC5E,oIAAoI;AACpI,SAASA,YAAY,QAAQ,cAAc;AAG3C;kEACkE,GAClE,OAAO,SAASC,cAAcC,KAAc;IAC1C,IAAIA,UAAUC,WAAW;IACzB,MAAMC,WAAW,OAAOF,UAAU,YAAYA,UAAU;IACxD,MAAMG,QAAQD,WAAW,AAACF,MAAkCG,KAAK,GAAGF;IACpE,MAAMG,OAAOF,WAAW,AAACF,MAAkCI,IAAI,GAAGH;IAClE,MAAMI,UAAU,OAAOF,UAAU,YAAYG,OAAOC,QAAQ,CAACJ,UAAUA,SAAS;IAChF,MAAMK,SAASJ,SAASH,aAAc,OAAOG,SAAS,YAAYE,OAAOC,QAAQ,CAACH,SAASA,QAASD;IACpG,IAAI,CAACD,YAAY,CAACG,WAAW,CAACG,QAAQ;QACpC,MAAM,IAAIV,aAAa,cAAc,CAAC,6FAA6F,EAAEW,KAAKC,SAAS,CAACV,OAAO,CAAC,CAAC;IAC/J;AACF;AAEA;4HAC4H,GAC5H,OAAO,SAASW,mBAAmBC,KAAc;IAC/C,MAAMV,WAAW,OAAOU,UAAU,YAAYA,UAAU;IACxD,MAAMC,QAAQX,WAAW,AAACU,MAAkCC,KAAK,GAAGZ;IACpE,IAAI,CAACa,MAAMC,OAAO,CAACF,QAAQ;QACzB,MAAM,IAAIf,aAAa,eAAe,CAAC,8EAA8E,EAAEI,WAAWO,KAAKC,SAAS,CAACE,SAASI,OAAOJ,OAAO,CAAC,CAAC;IAC5K;IACA,OAAOC;AACT;AAEA;qHACqH,GACrH,OAAO,SAASI,yBAAyBL,KAAc;IACrD,IAAI,OAAOA,UAAU,UAAU;QAC7B,MAAM,IAAId,aAAa,YAAY,CAAC,+GAA+G,EAAEW,KAAKC,SAAS,CAACE,OAAO,4BAA4B,EAAEH,KAAKC,SAAS,CAACE,OAAO,GAAG,CAAC;IACrO;IACA,MAAMV,WAAW,OAAOU,UAAU,YAAYA,UAAU;IACxD,MAAMM,aAAahB,WAAW,AAACU,MAAkCO,OAAO,GAAGlB;IAC3E,MAAMmB,WAAWlB,WAAW,AAACU,MAAkCC,KAAK,GAAGZ;IACvE,IAAI,CAACC,YAAagB,eAAejB,aAAamB,aAAanB,WAAY;QACrE,MAAM,IAAIH,aAAa,eAAe,CAAC,uFAAuF,EAAEI,WAAWO,KAAKC,SAAS,CAACE,SAASI,OAAOJ,OAAO,CAAC,CAAC;IACrL;IACA,IAAIQ,aAAanB,aAAa,CAACa,MAAMC,OAAO,CAACK,WAAW;QACtD,MAAM,IAAItB,aAAa,eAAe,CAAC,yDAAyD,EAAEW,KAAKC,SAAS,CAACU,UAAU,CAAC,CAAC;IAC/H;IACA,IAAIF,eAAejB,aAAa,OAAOiB,eAAe,UAAU;QAC9D,MAAM,IAAIpB,aAAa,YAAY,CAAC,2DAA2D,EAAEW,KAAKC,SAAS,CAACQ,YAAY,CAAC,CAAC;IAChI;IACA,IAAIE,aAAanB,WAAW;QAC1B,KAAK,MAAMoB,KAAKD,SAAuB;YACrC,MAAME,MAAMD;YACZ,IAAI,OAAOC,IAAIC,IAAI,KAAK,YAAY,OAAOD,IAAIE,IAAI,KAAK,YAAY,OAAOF,IAAIG,CAAC,KAAK,YAAY,OAAOH,IAAII,CAAC,KAAK,YAAY,OAAOJ,IAAID,CAAC,KAAK,YAAY,OAAOC,IAAIK,CAAC,KAAK,UAAU;gBACpL,MAAM,IAAI7B,aAAa,eAAe,CAAC,sDAAsD,EAAEW,KAAKC,SAAS,CAACW,IAAI;YACpH;QACF;QACA,OAAO;YAAER,OAAOO;QAA2B;IAC7C;IACA,OAAO;QAAED,SAASD;IAAqB;AACzC"}
1
+ {"version":3,"sources":["/Users/kevin/Dev/open-source/formats/pdf-to-md/src/validate.ts"],"sourcesContent":["// validate.ts — input-shape validation shared by analyze.ts and extract.ts,\n// kept out of both to dodge their value-level import cycle (extract.ts imports analyze.ts's buildOcrAnalysisPages; both need this).\nimport { PdfToMdError } from './errors.ts';\nimport type { OcrWordInput } from './extract.ts';\n\n/** Validates the one option every entry point accepts before touching the\n * PDF. Type-only import from `extract.ts` keeps this cycle-free. */\nexport function validatePages(pages: unknown): void {\n if (pages === undefined) return;\n const isRecord = typeof pages === 'object' && pages !== null;\n const first = isRecord ? (pages as Record<string, unknown>).first : undefined;\n const last = isRecord ? (pages as Record<string, unknown>).last : undefined;\n const firstOk = typeof first === 'number' && Number.isFinite(first) && first >= 1;\n const lastOk = last === undefined || (typeof last === 'number' && Number.isFinite(last) && last >= (first as number));\n if (!isRecord || !firstOk || !lastOk) {\n throw new PdfToMdError('PAGE_RANGE', `pages option must be { first: number, last?: number } with first >= 1 and last >= first (got ${JSON.stringify(pages)})`);\n }\n}\n\n/** Validates analyze()'s non-string `input` branch (`{ words }`) before\n * `.words` is read, so a plain-JS mistake like `analyze(null)` throws PdfToMdError/WORDS_INPUT instead of a raw TypeError. */\nexport function validateWordsInput(input: unknown): OcrWordInput[] {\n const isRecord = typeof input === 'object' && input !== null;\n const words = isRecord ? (input as Record<string, unknown>).words : undefined;\n if (!Array.isArray(words)) {\n throw new PdfToMdError('WORDS_INPUT', `analyze() input must be a pdf path (string) or { words: OcrWordInput[] } (got ${isRecord ? JSON.stringify(input) : String(input)})`);\n }\n return words as OcrWordInput[];\n}\n\n/** Runtime shape guard for `buildOcrAnalysisPages`'s input: a plain-JS\n * caller bypasses the TS union, so this turns a raw TypeError into PdfToMdError before any property is read off it. */\nexport function validateOcrAnalysisInput(input: unknown): { pdfPath: string } | { words: OcrWordInput[] } {\n if (typeof input === 'string') {\n throw new PdfToMdError('PDF_OPEN', `extractOcr/analyze input must be { pdfPath: string } or { words: OcrWordInput[] }, not a bare path string (got ${JSON.stringify(input)}) — did you mean { pdfPath: ${JSON.stringify(input)} }?`);\n }\n const isRecord = typeof input === 'object' && input !== null;\n const rawPdfPath = isRecord ? (input as Record<string, unknown>).pdfPath : undefined;\n const rawWords = isRecord ? (input as Record<string, unknown>).words : undefined;\n if (!isRecord || (rawPdfPath === undefined && rawWords === undefined)) {\n throw new PdfToMdError('WORDS_INPUT', `extractOcr/analyze input must be { pdfPath: string } or { words: OcrWordInput[] } (got ${isRecord ? JSON.stringify(input) : String(input)})`);\n }\n if (rawWords !== undefined && !Array.isArray(rawWords)) {\n throw new PdfToMdError('WORDS_INPUT', `extractOcr/analyze { words } input must be an array (got ${JSON.stringify(rawWords)})`);\n }\n if (rawPdfPath !== undefined && typeof rawPdfPath !== 'string') {\n throw new PdfToMdError('PDF_OPEN', `extractOcr/analyze { pdfPath } input must be a string (got ${JSON.stringify(rawPdfPath)})`);\n }\n if (rawWords !== undefined) {\n for (const w of rawWords as unknown[]) {\n const rec = w as Record<string, unknown>;\n if (typeof rec.page !== 'number' || typeof rec.text !== 'string' || typeof rec.x !== 'number' || typeof rec.y !== 'number' || typeof rec.w !== 'number' || typeof rec.h !== 'number') {\n throw new PdfToMdError('WORDS_INPUT', `malformed word entry (need {page, text, x, y, w, h}): ${JSON.stringify(w)}`);\n }\n }\n return { words: rawWords as OcrWordInput[] };\n }\n return { pdfPath: rawPdfPath as string };\n}\n"],"names":["PdfToMdError","validatePages","pages","undefined","isRecord","first","last","firstOk","Number","isFinite","lastOk","JSON","stringify","validateWordsInput","input","words","Array","isArray","String","validateOcrAnalysisInput","rawPdfPath","pdfPath","rawWords","w","rec","page","text","x","y","h"],"mappings":"AAAA,4EAA4E;AAC5E,oIAAoI;AACpI,SAASA,YAAY,QAAQ,cAAc;AAG3C;kEACkE,GAClE,OAAO,SAASC,cAAcC,KAAc;IAC1C,IAAIA,UAAUC,WAAW;IACzB,MAAMC,WAAW,OAAOF,UAAU,YAAYA,UAAU;IACxD,MAAMG,QAAQD,WAAW,AAACF,MAAkCG,KAAK,GAAGF;IACpE,MAAMG,OAAOF,WAAW,AAACF,MAAkCI,IAAI,GAAGH;IAClE,MAAMI,UAAU,OAAOF,UAAU,YAAYG,OAAOC,QAAQ,CAACJ,UAAUA,SAAS;IAChF,MAAMK,SAASJ,SAASH,aAAc,OAAOG,SAAS,YAAYE,OAAOC,QAAQ,CAACH,SAASA,QAASD;IACpG,IAAI,CAACD,YAAY,CAACG,WAAW,CAACG,QAAQ;QACpC,MAAM,IAAIV,aAAa,cAAc,CAAC,6FAA6F,EAAEW,KAAKC,SAAS,CAACV,OAAO,CAAC,CAAC;IAC/J;AACF;AAEA;4HAC4H,GAC5H,OAAO,SAASW,mBAAmBC,KAAc;IAC/C,MAAMV,WAAW,OAAOU,UAAU,YAAYA,UAAU;IACxD,MAAMC,QAAQX,WAAW,AAACU,MAAkCC,KAAK,GAAGZ;IACpE,IAAI,CAACa,MAAMC,OAAO,CAACF,QAAQ;QACzB,MAAM,IAAIf,aAAa,eAAe,CAAC,8EAA8E,EAAEI,WAAWO,KAAKC,SAAS,CAACE,SAASI,OAAOJ,OAAO,CAAC,CAAC;IAC5K;IACA,OAAOC;AACT;AAEA;qHACqH,GACrH,OAAO,SAASI,yBAAyBL,KAAc;IACrD,IAAI,OAAOA,UAAU,UAAU;QAC7B,MAAM,IAAId,aAAa,YAAY,CAAC,+GAA+G,EAAEW,KAAKC,SAAS,CAACE,OAAO,4BAA4B,EAAEH,KAAKC,SAAS,CAACE,OAAO,GAAG,CAAC;IACrO;IACA,MAAMV,WAAW,OAAOU,UAAU,YAAYA,UAAU;IACxD,MAAMM,aAAahB,WAAW,AAACU,MAAkCO,OAAO,GAAGlB;IAC3E,MAAMmB,WAAWlB,WAAW,AAACU,MAAkCC,KAAK,GAAGZ;IACvE,IAAI,CAACC,YAAagB,eAAejB,aAAamB,aAAanB,WAAY;QACrE,MAAM,IAAIH,aAAa,eAAe,CAAC,uFAAuF,EAAEI,WAAWO,KAAKC,SAAS,CAACE,SAASI,OAAOJ,OAAO,CAAC,CAAC;IACrL;IACA,IAAIQ,aAAanB,aAAa,CAACa,MAAMC,OAAO,CAACK,WAAW;QACtD,MAAM,IAAItB,aAAa,eAAe,CAAC,yDAAyD,EAAEW,KAAKC,SAAS,CAACU,UAAU,CAAC,CAAC;IAC/H;IACA,IAAIF,eAAejB,aAAa,OAAOiB,eAAe,UAAU;QAC9D,MAAM,IAAIpB,aAAa,YAAY,CAAC,2DAA2D,EAAEW,KAAKC,SAAS,CAACQ,YAAY,CAAC,CAAC;IAChI;IACA,IAAIE,aAAanB,WAAW;QAC1B,KAAK,MAAMoB,KAAKD,SAAuB;YACrC,MAAME,MAAMD;YACZ,IAAI,OAAOC,IAAIC,IAAI,KAAK,YAAY,OAAOD,IAAIE,IAAI,KAAK,YAAY,OAAOF,IAAIG,CAAC,KAAK,YAAY,OAAOH,IAAII,CAAC,KAAK,YAAY,OAAOJ,IAAID,CAAC,KAAK,YAAY,OAAOC,IAAIK,CAAC,KAAK,UAAU;gBACpL,MAAM,IAAI7B,aAAa,eAAe,CAAC,sDAAsD,EAAEW,KAAKC,SAAS,CAACW,IAAI;YACpH;QACF;QACA,OAAO;YAAER,OAAOO;QAA2B;IAC7C;IACA,OAAO;QAAED,SAASD;IAAqB;AACzC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@effortlessmotion/pdf-to-md",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "description": "Extract PDFs to structured markdown: text layer via pdf.js, OCR fallback for image-only pages, pure npm and cross-platform",
5
5
  "keywords": [
6
6
  "pdf",
@@ -32,8 +32,7 @@
32
32
  "pdf-to-md": "bin/cli.js"
33
33
  },
34
34
  "files": [
35
- "dist",
36
- "skills"
35
+ "dist"
37
36
  ],
38
37
  "scripts": {
39
38
  "build": "tsds build",
@@ -1,75 +0,0 @@
1
- ---
2
- name: pdf-to-md
3
- description: "Convert PDFs to Markdown with pdf-to-md, investigate missing or misordered text, and verify conversions against source pages and extraction evidence. Use for conversion, targeted re-extraction, or quality checks of pdf-to-md output."
4
- ---
5
-
6
- # pdf-to-md
7
-
8
- pdf-to-md reads embedded text and uses local OCR where needed. A preservation audit checks extracted text against Markdown. Recognition accuracy, reading order, tables and diagrams require comparison with rendered source pages.
9
-
10
- ## Convert with evidence
11
-
12
- ```sh
13
- pdf-to-md file.pdf out.md --json --page-markers --debug-words=words.jsonl
14
- ```
15
-
16
- Page markers connect the output to its source pages. `--debug-words` captures text-layer items or recognized OCR words before layout reconstruction. Text items can contain multiple words. Parse the dump as JSON Lines; key order is not fixed.
17
-
18
- `--ocr` forces recognition and `--no-ocr` retains the text path. `--pages N[-M]` selects source pages. A mixed document can use different extraction paths per page. Keep the input identity, tool version, effective options, report and dump with the run's working artifacts so later corrections use matching evidence.
19
-
20
- ## Find pages to inspect
21
-
22
- Read `report.pageStats` and warnings:
23
-
24
- - `danglingLong` identifies prose that may have broken at the wrong place.
25
- - `reviewBlocks` counts OCR blocks whose structure could not be recovered. The text path does not provide this detector; zero is not a layout guarantee.
26
- - `lowConfidenceWords` and `lowConfidenceSample` identify uncertain OCR tokens. Missing confidence data is not a high-confidence result.
27
- - `junkHeadings` identifies possible font-size classification errors.
28
- - `largeImages` on text pages identifies images that may contain additional text. Compare a targeted OCR pass before replacing usable embedded text.
29
-
30
- Also inspect sparse or empty pages and any layout the detectors do not cover. An unflagged page can still have incorrect columns, character mappings, tables or missing visual material.
31
-
32
- ## Compare against the page
33
-
34
- ```sh
35
- pdf-to-md render file.pdf N
36
- ```
37
-
38
- The default render is 288 DPI; use `--out DIR` for its destination. Compare the rendered page with the output, including item numbers, captions, symbols and reading order. Word presence alone does not validate these relationships.
39
-
40
- For an OCR comparison or tuning experiment:
41
-
42
- ```sh
43
- pdf-to-md file.pdf page-N.md --pages N --ocr --dpi 400 --debug-words=page-N.words.jsonl
44
- ```
45
-
46
- OCR can recover image text and also damage correct embedded text. Higher DPI can improve small labels and worsen ordinary prose. Compare the result before accepting it. Read the package's `QUALITY.md` for tuning controls; their effects apply to OCR geometry.
47
-
48
- If a page needs manual repair, retain its source dump and page number. An image can preserve a diagram visually but does not recover editable text. Record unresolved character mappings or flattened tables alongside the affected content.
49
-
50
- ## Audit the final Markdown
51
-
52
- ```sh
53
- pdf-to-md audit words.jsonl out.md
54
- ```
55
-
56
- A successful audit with `MISSING=0` means the supplied extracted text was accounted for under the auditor's matching rules. Empty or malformed evidence is an error. It does not prove that the dump captured every visible word or that the result is an accurate transcription.
57
-
58
- The auditor accepts `### pN` headings and `<!-- pN -->` comments. Audit the final file after edits and marker changes. Use the matching extraction dump for any pages replaced with a different extraction. Keep editorial additions separate while checking preservation, because added text can satisfy a missing occurrence.
59
-
60
- Report preservation results, visual/structural checks, and unresolved issues separately. Avoid a blanket "lossless" claim based on a word audit.
61
-
62
- ## Programmatic repair
63
-
64
- `--format raw` returns an `Analysis` with per-page source items, blocks and a report. Text pages contain PDF text runs; OCR pages contain recognized words. Boxes use page-normalized coordinates, origin bottom-left, y increasing upward. Block `wordIndexes` link to the page's source list. Preserve that evidence when reordering blocks; rebuilding the source list from corrected output would make the audit circular.
65
-
66
- OCR uncertainty markers remain visible in Markdown:
67
-
68
- ```text
69
- > [floats] ...
70
- > [review: reason] ...
71
- ```
72
-
73
- Moving or deleting these blocks can remove real content. Check their source pages before changing them.
74
-
75
- PDF compression is a separate operation. If requested, retain an identifiable original and verify text and visual material independently before replacing it. Lossy image compression can affect subsequent OCR and diagram checks even when extracted text stays identical.