@effortlessmotion/pdf-to-md 0.1.0
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.
- package/LICENSE +21 -0
- package/README.md +157 -0
- package/bin/cli.js +9 -0
- package/dist/cjs/analyze.d.cts +35 -0
- package/dist/cjs/analyze.d.ts +35 -0
- package/dist/cjs/analyze.js +620 -0
- package/dist/cjs/analyze.js.map +1 -0
- package/dist/cjs/audit.d.cts +38 -0
- package/dist/cjs/audit.d.ts +38 -0
- package/dist/cjs/audit.js +252 -0
- package/dist/cjs/audit.js.map +1 -0
- package/dist/cjs/cli/audit.d.cts +3 -0
- package/dist/cjs/cli/audit.d.ts +3 -0
- package/dist/cjs/cli/audit.js +269 -0
- package/dist/cjs/cli/audit.js.map +1 -0
- package/dist/cjs/cli/extract.d.cts +3 -0
- package/dist/cjs/cli/extract.d.ts +3 -0
- package/dist/cjs/cli/extract.js +704 -0
- package/dist/cjs/cli/extract.js.map +1 -0
- package/dist/cjs/cli/index.d.cts +5 -0
- package/dist/cjs/cli/index.d.ts +5 -0
- package/dist/cjs/cli/index.js +58 -0
- package/dist/cjs/cli/index.js.map +1 -0
- package/dist/cjs/cli/render.d.cts +3 -0
- package/dist/cjs/cli/render.d.ts +3 -0
- package/dist/cjs/cli/render.js +361 -0
- package/dist/cjs/cli/render.js.map +1 -0
- package/dist/cjs/cli/types.d.cts +10 -0
- package/dist/cjs/cli/types.d.ts +10 -0
- package/dist/cjs/cli/types.js +7 -0
- package/dist/cjs/cli/types.js.map +1 -0
- package/dist/cjs/cli.d.cts +2 -0
- package/dist/cjs/cli.d.ts +2 -0
- package/dist/cjs/cli.js +345 -0
- package/dist/cjs/cli.js.map +1 -0
- package/dist/cjs/collect.d.cts +6 -0
- package/dist/cjs/collect.d.ts +6 -0
- package/dist/cjs/collect.js +370 -0
- package/dist/cjs/collect.js.map +1 -0
- package/dist/cjs/dict.d.cts +8 -0
- package/dist/cjs/dict.d.ts +8 -0
- package/dist/cjs/dict.js +55 -0
- package/dist/cjs/dict.js.map +1 -0
- package/dist/cjs/emit.d.cts +27 -0
- package/dist/cjs/emit.d.ts +27 -0
- package/dist/cjs/emit.js +187 -0
- package/dist/cjs/emit.js.map +1 -0
- package/dist/cjs/engines/tesseract.d.cts +30 -0
- package/dist/cjs/engines/tesseract.d.ts +30 -0
- package/dist/cjs/engines/tesseract.js +650 -0
- package/dist/cjs/engines/tesseract.js.map +1 -0
- package/dist/cjs/errors.d.cts +21 -0
- package/dist/cjs/errors.d.ts +21 -0
- package/dist/cjs/errors.js +124 -0
- package/dist/cjs/errors.js.map +1 -0
- package/dist/cjs/extract.d.cts +88 -0
- package/dist/cjs/extract.d.ts +88 -0
- package/dist/cjs/extract.js +436 -0
- package/dist/cjs/extract.js.map +1 -0
- package/dist/cjs/geometry.d.cts +63 -0
- package/dist/cjs/geometry.d.ts +63 -0
- package/dist/cjs/geometry.js +521 -0
- package/dist/cjs/geometry.js.map +1 -0
- package/dist/cjs/index.d.cts +15 -0
- package/dist/cjs/index.d.ts +15 -0
- package/dist/cjs/index.js +56 -0
- package/dist/cjs/index.js.map +1 -0
- package/dist/cjs/lines.d.cts +3 -0
- package/dist/cjs/lines.d.ts +3 -0
- package/dist/cjs/lines.js +181 -0
- package/dist/cjs/lines.js.map +1 -0
- package/dist/cjs/markdown.d.cts +2 -0
- package/dist/cjs/markdown.d.ts +2 -0
- package/dist/cjs/markdown.js +222 -0
- package/dist/cjs/markdown.js.map +1 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/page-marker.d.cts +16 -0
- package/dist/cjs/page-marker.d.ts +16 -0
- package/dist/cjs/page-marker.js +85 -0
- package/dist/cjs/page-marker.js.map +1 -0
- package/dist/cjs/pdf-open.d.cts +12 -0
- package/dist/cjs/pdf-open.d.ts +12 -0
- package/dist/cjs/pdf-open.js +257 -0
- package/dist/cjs/pdf-open.js.map +1 -0
- package/dist/cjs/raster.d.cts +26 -0
- package/dist/cjs/raster.d.ts +26 -0
- package/dist/cjs/raster.js +262 -0
- package/dist/cjs/raster.js.map +1 -0
- package/dist/cjs/render-analysis.d.cts +25 -0
- package/dist/cjs/render-analysis.d.ts +25 -0
- package/dist/cjs/render-analysis.js +319 -0
- package/dist/cjs/render-analysis.js.map +1 -0
- package/dist/cjs/report.d.cts +12 -0
- package/dist/cjs/report.d.ts +12 -0
- package/dist/cjs/report.js +392 -0
- package/dist/cjs/report.js.map +1 -0
- package/dist/cjs/resolve.d.cts +1 -0
- package/dist/cjs/resolve.d.ts +1 -0
- package/dist/cjs/resolve.js +18 -0
- package/dist/cjs/resolve.js.map +1 -0
- package/dist/cjs/types.d.cts +171 -0
- package/dist/cjs/types.d.ts +171 -0
- package/dist/cjs/types.js +9 -0
- package/dist/cjs/types.js.map +1 -0
- package/dist/cjs/validate.d.cts +14 -0
- package/dist/cjs/validate.d.ts +14 -0
- package/dist/cjs/validate.js +96 -0
- package/dist/cjs/validate.js.map +1 -0
- package/dist/esm/analyze.d.ts +35 -0
- package/dist/esm/analyze.js +270 -0
- package/dist/esm/analyze.js.map +1 -0
- package/dist/esm/audit.d.ts +38 -0
- package/dist/esm/audit.js +113 -0
- package/dist/esm/audit.js.map +1 -0
- package/dist/esm/cli/audit.d.ts +3 -0
- package/dist/esm/cli/audit.js +20 -0
- package/dist/esm/cli/audit.js.map +1 -0
- package/dist/esm/cli/extract.d.ts +3 -0
- package/dist/esm/cli/extract.js +313 -0
- package/dist/esm/cli/extract.js.map +1 -0
- package/dist/esm/cli/index.d.ts +5 -0
- package/dist/esm/cli/index.js +7 -0
- package/dist/esm/cli/index.js.map +1 -0
- package/dist/esm/cli/render.d.ts +3 -0
- package/dist/esm/cli/render.js +77 -0
- package/dist/esm/cli/render.js.map +1 -0
- package/dist/esm/cli/types.d.ts +10 -0
- package/dist/esm/cli/types.js +3 -0
- package/dist/esm/cli/types.js.map +1 -0
- package/dist/esm/cli.d.ts +2 -0
- package/dist/esm/cli.js +90 -0
- package/dist/esm/cli.js.map +1 -0
- package/dist/esm/collect.d.ts +6 -0
- package/dist/esm/collect.js +80 -0
- package/dist/esm/collect.js.map +1 -0
- package/dist/esm/dict.d.ts +8 -0
- package/dist/esm/dict.js +28 -0
- package/dist/esm/dict.js.map +1 -0
- package/dist/esm/emit.d.ts +27 -0
- package/dist/esm/emit.js +131 -0
- package/dist/esm/emit.js.map +1 -0
- package/dist/esm/engines/tesseract.d.ts +30 -0
- package/dist/esm/engines/tesseract.js +190 -0
- package/dist/esm/engines/tesseract.js.map +1 -0
- package/dist/esm/errors.d.ts +21 -0
- package/dist/esm/errors.js +9 -0
- package/dist/esm/errors.js.map +1 -0
- package/dist/esm/extract.d.ts +88 -0
- package/dist/esm/extract.js +147 -0
- package/dist/esm/extract.js.map +1 -0
- package/dist/esm/geometry.d.ts +63 -0
- package/dist/esm/geometry.js +279 -0
- package/dist/esm/geometry.js.map +1 -0
- package/dist/esm/index.d.ts +15 -0
- package/dist/esm/index.js +10 -0
- package/dist/esm/index.js.map +1 -0
- package/dist/esm/lines.d.ts +3 -0
- package/dist/esm/lines.js +67 -0
- package/dist/esm/lines.js.map +1 -0
- package/dist/esm/markdown.d.ts +2 -0
- package/dist/esm/markdown.js +153 -0
- package/dist/esm/markdown.js.map +1 -0
- package/dist/esm/package.json +1 -0
- package/dist/esm/page-marker.d.ts +16 -0
- package/dist/esm/page-marker.js +40 -0
- package/dist/esm/page-marker.js.map +1 -0
- package/dist/esm/pdf-open.d.ts +12 -0
- package/dist/esm/pdf-open.js +61 -0
- package/dist/esm/pdf-open.js.map +1 -0
- package/dist/esm/raster.d.ts +26 -0
- package/dist/esm/raster.js +60 -0
- package/dist/esm/raster.js.map +1 -0
- package/dist/esm/render-analysis.d.ts +25 -0
- package/dist/esm/render-analysis.js +115 -0
- package/dist/esm/render-analysis.js.map +1 -0
- package/dist/esm/report.d.ts +12 -0
- package/dist/esm/report.js +182 -0
- package/dist/esm/report.js.map +1 -0
- package/dist/esm/resolve.d.ts +1 -0
- package/dist/esm/resolve.js +7 -0
- package/dist/esm/resolve.js.map +1 -0
- package/dist/esm/types.d.ts +171 -0
- package/dist/esm/types.js +6 -0
- package/dist/esm/types.js.map +1 -0
- package/dist/esm/validate.d.ts +14 -0
- package/dist/esm/validate.js +56 -0
- package/dist/esm/validate.js.map +1 -0
- package/package.json +67 -0
- package/skills/pdf-to-md/SKILL.md +102 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kevin Malakoff
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# pdf-to-md
|
|
2
|
+
|
|
3
|
+
> Convert PDFs — born-digital or scanned — into markdown you can trust, under an explicit
|
|
4
|
+
> contract: recognized text is never silently lost, unrecoverable structure is marked rather
|
|
5
|
+
> than guessed, and every claim the output makes is mechanically checkable. When the defaults
|
|
6
|
+
> misread your document, you get the measured knobs, the detectors that point at exactly what to
|
|
7
|
+
> distrust, and the raw analysis to converge on a lossless conversion yourself.
|
|
8
|
+
|
|
9
|
+
Pure TypeScript, runs anywhere `npm install` works. No system dependencies, no cloud calls: the
|
|
10
|
+
OCR engine ([tesseract.js](https://www.npmjs.com/package/tesseract.js)) and its recognition model
|
|
11
|
+
install with the package and run fully offline.
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install pdf-to-md
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Requires Node >=22.13.0 — below that, the OCR path silently finds no words instead of
|
|
18
|
+
erroring (see Development for the measured reason).
|
|
19
|
+
|
|
20
|
+
## CLI
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npx pdf-to-md book.pdf # text layer -> book.md (auto-OCR if pages are images)
|
|
24
|
+
npx pdf-to-md scan.pdf out.md --ocr # force the OCR path
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
pdf-to-md <file.pdf> [out.md] [flags...] convert (implicit `extract`)
|
|
29
|
+
pdf-to-md render <file.pdf> <page>[-<page>] render a page to PNG for eyeballing
|
|
30
|
+
pdf-to-md audit <words.jsonl> <file.md> severity-1 check: every recognized word present?
|
|
31
|
+
pdf-to-md --help | --version
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Everyday flags: `--ocr`, `--no-ocr`, `--pages N[-M]`, `--stdout`, `--json` (QA report),
|
|
35
|
+
`--format md|txt|raw` (default `md`; `raw` = the full `Analysis` as JSON, report included; `txt` =
|
|
36
|
+
reading-order plain text — line-granular on the text path with no paragraph reflow, block-granular
|
|
37
|
+
on the OCR path), `--debug-words=FILE` (severity-1 audit input, see below), `--dpi=N`
|
|
38
|
+
(OCR render resolution). Usage errors exit 2; runtime errors exit 1.
|
|
39
|
+
|
|
40
|
+
## Library
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
import { pdfToMarkdown } from 'pdf-to-md';
|
|
44
|
+
|
|
45
|
+
const { markdown, report, warnings } = await pdfToMarkdown('book.pdf');
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
`pdfToMarkdown` is the headline API: text layer first, falling back to OCR on its own when the
|
|
49
|
+
pages are images of text. For explicit control over which path runs (hybrid pages — a real text
|
|
50
|
+
layer plus a large embedded image — are a class the tool itself flags, and reading both requires
|
|
51
|
+
naming the path), the engine-agnostic word-input seam, and the `analyze`/`toMarkdown`/`toText`
|
|
52
|
+
raw-analysis API described below, every exported function and option is documented at its
|
|
53
|
+
declaration — `extractText`, `extractOcr`, `analyze`, `toMarkdown`, `toText`, `auditWords`,
|
|
54
|
+
`DEFAULT_TUNING`, and the rest — visible in editor hover and in the [API Docs](https://kmalakoff.github.io/pdf-to-md/).
|
|
55
|
+
TSDoc is the source of truth for per-option prose; this file stays a map, not a mirror.
|
|
56
|
+
|
|
57
|
+
All library functions throw a typed `PdfToMdError` (`code: 'PDF_OPEN' | 'PAGE_RANGE' |
|
|
58
|
+
'PAGE_RENDER' | 'OCR_PAGE_FAILED' | 'WORDS_INPUT' | 'ANALYSIS_INPUT'`) and never write to
|
|
59
|
+
stdout/stderr or exit the process; warnings are returned data (plus an `onWarning` callback for
|
|
60
|
+
streaming them).
|
|
61
|
+
|
|
62
|
+
## Design contract
|
|
63
|
+
|
|
64
|
+
What this tool promises about errors, in severity order — each with the instrument that enforces it:
|
|
65
|
+
|
|
66
|
+
1. **Silent text loss is forbidden.** Every word the engine recognizes lands in the output — body,
|
|
67
|
+
heading, or a visible `> [floats]` aside. **Enforced by:** `--debug-words=FILE` dumps every
|
|
68
|
+
recognized word as clean JSON lines (`{page, text, x, y, w, h, confidence?}`); the shipped
|
|
69
|
+
`auditWords()` (or `pdf-to-md audit words.jsonl out.md`) checks the dump against the markdown
|
|
70
|
+
and exits 1 on any loss (`MISSING > 0`) — a first-class part of the product, usable as a CI
|
|
71
|
+
gate, not a path into the source tree.
|
|
72
|
+
2. **Invisible corruption is minimized and made detectable.** Right-words-wrong-order failures
|
|
73
|
+
(column braiding, mid-sentence splits) are what the geometry works hardest to prevent; a second
|
|
74
|
+
class — right order, WRONG VALUE (an OCR misread spliced into otherwise word-like prose) — is
|
|
75
|
+
what confidence scoring catches. **Enforced by:** `report.danglingLong` (the order-failure
|
|
76
|
+
detector no output-only check can prove), `report.reviewBlocks` (blocks the geometry couldn't
|
|
77
|
+
order, labeled rather than guessed at), and `report.lowConfidenceWords` /
|
|
78
|
+
`pageStats[].lowConfidenceSample` (words the engine itself scored below confidence 60 — see
|
|
79
|
+
`LOW_CONFIDENCE_THRESHOLD`'s test in `test/unit/review-blocks.test.ts` for the measured derivation).
|
|
80
|
+
3. **Visible misplacement is acceptable.** A fragment in the floats aside, a `> [review: ...]`
|
|
81
|
+
block, or an odd paragraph break is something a caller can see and edit; the two classes above
|
|
82
|
+
are not. **Enforced by:** the `> [floats]` / `> [review: reason]` markers themselves — regular
|
|
83
|
+
enough (`^> \[(floats|review: [^\]]+)\] (.*)$`) for a downstream agent to find and handle
|
|
84
|
+
without guessing — surfaced in `--json` as `report.floats` / `report.reviewBlocks`.
|
|
85
|
+
|
|
86
|
+
The QA report (`--json`) exists to make 2 and 3 reviewable: per-page stats flag suspect pages, and
|
|
87
|
+
`pdf-to-md render` shows you the page as printed — the only real ground truth.
|
|
88
|
+
|
|
89
|
+
**Why there's no `--floats=drop`:** an earlier version offered one, filtering `> [floats]` lines
|
|
90
|
+
out of the output. Measured against a real 100-page document, floats held real sentence tails on
|
|
91
|
+
pages 29, 48, and 94 — "drop" invited exactly the silent loss rule 1 forbids, so the knob was cut.
|
|
92
|
+
Filtering them back out downstream is one line (`^> \[floats\]`) a caller can write when floats
|
|
93
|
+
truly are noise for their document; the tool won't make that call for you.
|
|
94
|
+
|
|
95
|
+
**`closedHyphens` as a cross-check, not a target:** the text path's `report.closedHyphens` counts
|
|
96
|
+
line-final hyphens closed against a dictionary (e.g. "creat-" + "ive" → "creative"). It exists to
|
|
97
|
+
explain the auditor's `strict_deficits` count, not to be optimized directly: a strict deficit is
|
|
98
|
+
usually a hyphen-rejoin firing (a word split across two lines, correctly closed into one), not lost
|
|
99
|
+
text — `MISSING` is the loss signal, and `closedHyphens` is what explains the difference.
|
|
100
|
+
|
|
101
|
+
## Tuning
|
|
102
|
+
|
|
103
|
+
OCR-path heuristics run on constants measured against real documents — the derivation for each
|
|
104
|
+
lives beside its value in `src/geometry.ts`'s `DEFAULT_TUNING` (the canonical source; typedoc
|
|
105
|
+
renders it). Override per run instead of editing source:
|
|
106
|
+
|
|
107
|
+
| flag | controls | default |
|
|
108
|
+
|---|---|---|
|
|
109
|
+
| `--float-max-words` | fragments with more words than this are body text, not decoration | `3` |
|
|
110
|
+
| `--float-max-width` | fraction of page width above which a fragment is too wide to be decoration | `0.15` |
|
|
111
|
+
| `--float-margin` | how far a fragment's left edge must sit from its column edge to be decoration | `0.008` |
|
|
112
|
+
| `--para-gap` | a vertical gap this many times the line pitch is a paragraph break | `1.6` |
|
|
113
|
+
| `--heading-scale` | lines taller than this times body height are headings | `2.0` |
|
|
114
|
+
| `--col-max-width` | boxes wider than this are excluded from gutter detection | `0.55` |
|
|
115
|
+
| `--col-split` | fractional x of the two-column midpoint | `0.5` |
|
|
116
|
+
| `--line-y-tol` | vertical distance within which two boxes are the same line | `0.006` |
|
|
117
|
+
| `--line-height-ratio` | same-line boxes with a larger height ratio don't merge | `2.4` |
|
|
118
|
+
| `--dpi` | OCR page-render resolution; raise for tiny print or chart/label pages, `>~400` measured worse on ordinary prose pages (`test/unit/sparse-retry.test.ts`) | `288` |
|
|
119
|
+
|
|
120
|
+
**Hybrid pages:** raising `--dpi` fixes chart/label corruption but can make scattered numerals on
|
|
121
|
+
the same page WORSE, not better (measured: a chart page's numerals recognized at `288` dpi, then
|
|
122
|
+
none at `600`, while the page's own text layer already had them all) — `--dpi` is a chart-LABEL
|
|
123
|
+
fix, not a scattered-numeral fix. For hybrid pages, compare (or merge, via `analyze()`) the
|
|
124
|
+
text-layer and OCR readings rather than trusting one dpi setting to fix everything on the page.
|
|
125
|
+
|
|
126
|
+
Typical loop: run with `--json`, find suspect pages in `pageStats`, `pdf-to-md render` them, then
|
|
127
|
+
re-extract just those pages with `--pages` and an adjusted flag — or use `--format=raw` to get the
|
|
128
|
+
full `Analysis` (words + blocks + report) and converge programmatically.
|
|
129
|
+
|
|
130
|
+
## For AI agents
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
npx skills add kmalakoff/pdf-to-md # -g for global, -a claude-code to target
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
One skill: `pdf-to-md` for driving the QA loop above (reading `pageStats`, rendering pages as
|
|
137
|
+
ground truth, targeted re-extraction, the severity-1 audit, and the `> [floats]` / `> [review:
|
|
138
|
+
...]` markers) instead of trusting the first conversion.
|
|
139
|
+
|
|
140
|
+
## Development
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
npm run build # tsds build -> dist/cjs + dist/esm (pretest step; plain `npm test` builds first)
|
|
144
|
+
npm test # synthetic fixtures (ground truth by construction), a fetched+sha256-pinned
|
|
145
|
+
# public corpus (skips offline), real engine runs, plus self-skipping
|
|
146
|
+
# private-document extras when available locally
|
|
147
|
+
npm run prepublishOnly # tsds validate: build + biome + depcheck + docs
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Source is TypeScript; the published package ships a built `dist/` (dual CJS + ESM via `tsds
|
|
151
|
+
build`) because Node's native type-stripping refuses to run `.ts` files once they're under
|
|
152
|
+
`node_modules`. Tests still run directly against source; the CLI test helper spawns the built
|
|
153
|
+
`bin/cli.js`, which is why a build has to happen first.
|
|
154
|
+
|
|
155
|
+
`engines.node` is `>=22.13.0`, measured (not assumed): `pdfjs-dist`'s CJS build needs Node's
|
|
156
|
+
stable synchronous `require(esm)`, and its rendering path uses a V8 `ArrayBuffer` API missing
|
|
157
|
+
before Node 22. Don't lower this floor without re-running that measurement.
|
package/bin/cli.js
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
// biome-ignore lint/security/noGlobalEval: dual esm and cjs
|
|
4
|
+
if (typeof require === 'undefined') eval("import('../dist/esm/cli.js').then((cli) => cli.default(process.argv.slice(2), 'pdf-to-md')).catch((err) => { console.error(err); process.exit(-1); });");
|
|
5
|
+
else
|
|
6
|
+
require('../dist/cjs/cli.js')(process.argv.slice(2), 'pdf-to-md').catch((err) => {
|
|
7
|
+
console.error(err);
|
|
8
|
+
process.exit(-1);
|
|
9
|
+
});
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import type { ExtractOcrOptions, ExtractTextOptions, OcrWordInput } from './extract.js';
|
|
2
|
+
import type { Analysis, AnalysisPage } from './types.js';
|
|
3
|
+
/** analyze(pdf) with the default/'text' path — OCR-only fields don't exist
|
|
4
|
+
* on this branch, so passing e.g. `tuning` without `path: 'ocr'` is a compile error. */
|
|
5
|
+
export type AnalyzeTextOptions = ExtractTextOptions & {
|
|
6
|
+
path?: 'text';
|
|
7
|
+
};
|
|
8
|
+
/** analyze(pdf, {path:'ocr'}) — same fields as {@link ExtractOcrOptions},
|
|
9
|
+
* unlocked only once `path: 'ocr'` is set. */
|
|
10
|
+
export type AnalyzeOcrOptions = ExtractOcrOptions & {
|
|
11
|
+
path: 'ocr';
|
|
12
|
+
};
|
|
13
|
+
/** Options for {@link analyze}: which fields type-check depends on `path`
|
|
14
|
+
* (ignored, forced 'ocr', when `input` is a `{ words }` replay). */
|
|
15
|
+
export type AnalyzeOptions = AnalyzeTextOptions | AnalyzeOcrOptions;
|
|
16
|
+
/** The OCR-path core shared by extractOcr and analyze(..., {path:'ocr'}):
|
|
17
|
+
* recognizes (or replays) words and runs the unchanged buildPageOCR/emitPage pipeline. Word IDENTITY (object reference), not value, carries indices through into the emitted blocks — see `geometry.ts`'s OcrLine.words. */
|
|
18
|
+
export declare function buildOcrAnalysisPages(input: {
|
|
19
|
+
pdfPath: string;
|
|
20
|
+
} | {
|
|
21
|
+
words: OcrWordInput[];
|
|
22
|
+
}, opts: ExtractOcrOptions, warn: (m: string) => void): Promise<{
|
|
23
|
+
pages: AnalysisPage[];
|
|
24
|
+
words: OcrWordInput[];
|
|
25
|
+
}>;
|
|
26
|
+
/**
|
|
27
|
+
* Analyze a PDF (or replay an already-recognized OCR word dump) into
|
|
28
|
+
* `Analysis`: plain, JSON-serializable per-page `words`/`blocks` plus the same QA `report` the other entry points return. Render with toMarkdown()/toText(), or hand-edit/splice it (no merge API — see toMarkdown's doc comment).
|
|
29
|
+
*
|
|
30
|
+
* @param input a bare pdf path, or `{ words }` to replay a dump (always analyzed as OCR) — unlike extractOcr, never `{ pdfPath }`
|
|
31
|
+
* @param opts see {@link AnalyzeOptions}; for a pdf path, `opts.path` picks 'text' (default) or 'ocr' — analyze() makes no auto-fallback decision (that's pdfToMarkdown's job)
|
|
32
|
+
*/
|
|
33
|
+
export declare function analyze(input: string | {
|
|
34
|
+
words: OcrWordInput[];
|
|
35
|
+
}, opts?: AnalyzeOptions): Promise<Analysis>;
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import type { ExtractOcrOptions, ExtractTextOptions, OcrWordInput } from './extract.js';
|
|
2
|
+
import type { Analysis, AnalysisPage } from './types.js';
|
|
3
|
+
/** analyze(pdf) with the default/'text' path — OCR-only fields don't exist
|
|
4
|
+
* on this branch, so passing e.g. `tuning` without `path: 'ocr'` is a compile error. */
|
|
5
|
+
export type AnalyzeTextOptions = ExtractTextOptions & {
|
|
6
|
+
path?: 'text';
|
|
7
|
+
};
|
|
8
|
+
/** analyze(pdf, {path:'ocr'}) — same fields as {@link ExtractOcrOptions},
|
|
9
|
+
* unlocked only once `path: 'ocr'` is set. */
|
|
10
|
+
export type AnalyzeOcrOptions = ExtractOcrOptions & {
|
|
11
|
+
path: 'ocr';
|
|
12
|
+
};
|
|
13
|
+
/** Options for {@link analyze}: which fields type-check depends on `path`
|
|
14
|
+
* (ignored, forced 'ocr', when `input` is a `{ words }` replay). */
|
|
15
|
+
export type AnalyzeOptions = AnalyzeTextOptions | AnalyzeOcrOptions;
|
|
16
|
+
/** The OCR-path core shared by extractOcr and analyze(..., {path:'ocr'}):
|
|
17
|
+
* recognizes (or replays) words and runs the unchanged buildPageOCR/emitPage pipeline. Word IDENTITY (object reference), not value, carries indices through into the emitted blocks — see `geometry.ts`'s OcrLine.words. */
|
|
18
|
+
export declare function buildOcrAnalysisPages(input: {
|
|
19
|
+
pdfPath: string;
|
|
20
|
+
} | {
|
|
21
|
+
words: OcrWordInput[];
|
|
22
|
+
}, opts: ExtractOcrOptions, warn: (m: string) => void): Promise<{
|
|
23
|
+
pages: AnalysisPage[];
|
|
24
|
+
words: OcrWordInput[];
|
|
25
|
+
}>;
|
|
26
|
+
/**
|
|
27
|
+
* Analyze a PDF (or replay an already-recognized OCR word dump) into
|
|
28
|
+
* `Analysis`: plain, JSON-serializable per-page `words`/`blocks` plus the same QA `report` the other entry points return. Render with toMarkdown()/toText(), or hand-edit/splice it (no merge API — see toMarkdown's doc comment).
|
|
29
|
+
*
|
|
30
|
+
* @param input a bare pdf path, or `{ words }` to replay a dump (always analyzed as OCR) — unlike extractOcr, never `{ pdfPath }`
|
|
31
|
+
* @param opts see {@link AnalyzeOptions}; for a pdf path, `opts.path` picks 'text' (default) or 'ocr' — analyze() makes no auto-fallback decision (that's pdfToMarkdown's job)
|
|
32
|
+
*/
|
|
33
|
+
export declare function analyze(input: string | {
|
|
34
|
+
words: OcrWordInput[];
|
|
35
|
+
}, opts?: AnalyzeOptions): Promise<Analysis>;
|