@effortlessmotion/pdf-to-md 0.1.6 → 0.1.8
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/README.md +79 -127
- package/dist/cjs/cli/audit.js +2 -2
- package/dist/cjs/cli/audit.js.map +1 -1
- package/dist/cjs/cli/types.d.cts +3 -1
- package/dist/cjs/cli/types.d.ts +3 -1
- package/dist/cjs/cli/types.js.map +1 -1
- package/dist/cjs/cli.js +7 -5
- package/dist/cjs/cli.js.map +1 -1
- package/dist/esm/cli/audit.js +2 -2
- package/dist/esm/cli/audit.js.map +1 -1
- package/dist/esm/cli/types.d.ts +3 -1
- package/dist/esm/cli/types.js.map +1 -1
- package/dist/esm/cli.js +7 -5
- package/dist/esm/cli.js.map +1 -1
- package/package.json +3 -8
package/README.md
CHANGED
|
@@ -1,157 +1,109 @@
|
|
|
1
|
-
# pdf-to-md
|
|
1
|
+
# @effortlessmotion/pdf-to-md
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
|
3
|
+
Convert born-digital and scanned PDFs to Markdown. `pdf-to-md` reads an existing text layer first and falls back to local OCR for image-only pages. It returns a QA report and marks text it cannot place reliably instead of silently dropping it.
|
|
8
4
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
5
|
+
Use it when you need editable Markdown plus evidence about conversion quality. OCR runs locally and makes no cloud calls.
|
|
6
|
+
|
|
7
|
+
## Requirements
|
|
8
|
+
|
|
9
|
+
- Node.js 22.13 or newer
|
|
10
|
+
- English text for the bundled OCR model. Text-layer extraction can preserve other languages.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
12
13
|
|
|
13
14
|
```bash
|
|
14
|
-
npm install pdf-to-md
|
|
15
|
+
npm install @effortlessmotion/pdf-to-md
|
|
15
16
|
```
|
|
16
17
|
|
|
17
|
-
|
|
18
|
-
erroring (see Development for the measured reason).
|
|
18
|
+
## Convert a PDF
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
The package installs the `pdf-to-md` executable:
|
|
21
21
|
|
|
22
22
|
```bash
|
|
23
|
-
npx pdf-to-md book.pdf
|
|
24
|
-
npx pdf-to-md scan.pdf out.md --ocr # force the OCR path
|
|
23
|
+
npx pdf-to-md book.pdf
|
|
25
24
|
```
|
|
26
25
|
|
|
26
|
+
This writes `book.md`. If the PDF has too little embedded text, the command automatically uses OCR and reports that choice on stderr.
|
|
27
|
+
|
|
28
|
+
Specify an output path or force OCR when needed:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
npx pdf-to-md scan.pdf notes.md --ocr
|
|
27
32
|
```
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
33
|
+
|
|
34
|
+
A conversion can produce ordinary Markdown plus visible review markers:
|
|
35
|
+
|
|
36
|
+
```markdown
|
|
37
|
+
## DAILY TALLIES
|
|
38
|
+
|
|
39
|
+
Every skiff was counted at the north pier.
|
|
40
|
+
|
|
41
|
+
> [review: unstructured labels] 12 47 380 5 91
|
|
32
42
|
```
|
|
33
43
|
|
|
34
|
-
|
|
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.
|
|
44
|
+
The excerpt is illustrative. Review markers preserve text whose structure could not be recovered reliably.
|
|
39
45
|
|
|
40
|
-
## Library
|
|
46
|
+
## Library use
|
|
41
47
|
|
|
42
|
-
```
|
|
43
|
-
import { pdfToMarkdown } from 'pdf-to-md';
|
|
48
|
+
```js
|
|
49
|
+
import { pdfToMarkdown } from '@effortlessmotion/pdf-to-md';
|
|
44
50
|
|
|
45
51
|
const { markdown, report, warnings } = await pdfToMarkdown('book.pdf');
|
|
52
|
+
|
|
53
|
+
console.log(markdown);
|
|
54
|
+
console.log(report.path); // "text" or "ocr"
|
|
55
|
+
console.warn(warnings);
|
|
46
56
|
```
|
|
47
57
|
|
|
48
|
-
`pdfToMarkdown`
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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
|
|
58
|
+
`pdfToMarkdown()` uses the same text-first, automatic-OCR behavior as the CLI. It returns data and does not write files or exit the process. Conversion failures use `PdfToMdError` where the library assigns a package error code; native filesystem errors can also surface when inputs cannot be read.
|
|
59
|
+
|
|
60
|
+
Use `extractText()` or `extractOcr()` when you need to choose the path yourself. The [API documentation](https://kmalakoff.github.io/pdf-to-md/) lists the public functions, options and return types.
|
|
61
|
+
|
|
62
|
+
## Know which path ran
|
|
63
|
+
|
|
64
|
+
The QA report identifies the extraction path and highlights output that deserves review. Important cases:
|
|
65
|
+
|
|
66
|
+
- The bundled OCR model recognizes English. Use text-layer extraction for PDFs whose embedded text is in another language.
|
|
67
|
+
- A page can contain both embedded text and a large image with additional text. The text path warns about these hybrid pages so you can compare a targeted OCR pass.
|
|
68
|
+
- `> [floats]` and `> [review: ...]` blocks contain recognized text that the converter could not place confidently. They are intentionally visible.
|
|
69
|
+
- OCR quality depends on the scan. Check low-confidence words and rendered pages before relying on the result.
|
|
70
|
+
|
|
71
|
+
Use `--json` to print the report:
|
|
131
72
|
|
|
132
73
|
```bash
|
|
133
|
-
npx
|
|
74
|
+
npx pdf-to-md book.pdf --json
|
|
134
75
|
```
|
|
135
76
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
77
|
+
See [quality checks and tuning](https://github.com/kmalakoff/pdf-to-md/blob/master/QUALITY.md) for the audit workflow, report fields and OCR controls.
|
|
78
|
+
|
|
79
|
+
## Common CLI options
|
|
80
|
+
|
|
81
|
+
```text
|
|
82
|
+
pdf-to-md <file.pdf> [out.md] [flags]
|
|
83
|
+
pdf-to-md render <file.pdf> <page>[-<page>]
|
|
84
|
+
pdf-to-md audit <words.jsonl> <file.md>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Common flags:
|
|
88
|
+
|
|
89
|
+
- `--ocr` forces OCR; `--no-ocr` disables automatic OCR fallback.
|
|
90
|
+
- `--pages N[-M]` converts a page range.
|
|
91
|
+
- `--stdout` writes the converted content to stdout.
|
|
92
|
+
- `--json` prints the QA report.
|
|
93
|
+
- `--format md|txt|raw` selects Markdown, plain text or analysis JSON.
|
|
94
|
+
- `--debug-words=FILE` writes recognized OCR words for `pdf-to-md audit`.
|
|
95
|
+
- `--dpi=N` changes OCR render resolution. The default is 288; higher values are not always more accurate.
|
|
96
|
+
|
|
97
|
+
Run `npx pdf-to-md --help` for the complete option list.
|
|
98
|
+
|
|
99
|
+
## Agent skill
|
|
139
100
|
|
|
140
|
-
|
|
101
|
+
An optional skill teaches compatible coding agents how to inspect the report, render suspect pages and run targeted conversions:
|
|
141
102
|
|
|
142
103
|
```bash
|
|
143
|
-
|
|
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
|
|
104
|
+
npx skills add kmalakoff/pdf-to-md
|
|
148
105
|
```
|
|
149
106
|
|
|
150
|
-
|
|
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.
|
|
107
|
+
## Support and license
|
|
154
108
|
|
|
155
|
-
|
|
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.
|
|
109
|
+
Report problems through the [GitHub issue tracker](https://github.com/kmalakoff/pdf-to-md/issues). See [CONTRIBUTING.md](https://github.com/kmalakoff/pdf-to-md/blob/master/CONTRIBUTING.md) to work on the package. The package is licensed under the [MIT License](https://github.com/kmalakoff/pdf-to-md/blob/master/LICENSE).
|
package/dist/cjs/cli/audit.js
CHANGED
|
@@ -217,8 +217,8 @@ var audit = function audit(ctx) {
|
|
|
217
217
|
}
|
|
218
218
|
}
|
|
219
219
|
// MISSING>0 is the severity-1 fail signal: a recognized word this markdown
|
|
220
|
-
// lost. Exit
|
|
221
|
-
if (result.missing > 0) process.exitCode =
|
|
220
|
+
// lost. Exit with the CLI's error code so the subcommand is usable as a CI gate; strict_deficits from hyphen-join repairs are reported but not failures.
|
|
221
|
+
if (result.missing > 0) process.exitCode = ctx.errorCode;
|
|
222
222
|
return [
|
|
223
223
|
2
|
|
224
224
|
];
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["/Users/kevin/Dev/OpenSource/formats/pdf-to-md/src/cli/audit.ts"],"sourcesContent":["// audit command — the severity-1 audit instrument (README's \"Design\n// contract\") as a first-class subcommand. Thin wrapper over src/audit.ts's auditWords (the library returns data, only the CLI prints and exits).\nimport { auditWords } from '../audit.ts';\nimport type { Command } from './types.ts';\n\nconst USAGE = 'usage: pdf-to-md audit <words.jsonl> <file.md>';\n\nconst audit: Command = async (ctx) => {\n if (ctx.rest.includes('-h') || ctx.rest.includes('--help')) {\n console.log(USAGE);\n return;\n }\n const [wordsPath, mdPath] = ctx.rest;\n if (!wordsPath || !mdPath) ctx.usageError(USAGE);\n\n const result = auditWords(wordsPath, mdPath);\n for (const line of result.lines) console.log(line);\n\n // MISSING>0 is the severity-1 fail signal: a recognized word this markdown\n // lost. Exit
|
|
1
|
+
{"version":3,"sources":["/Users/kevin/Dev/OpenSource/formats/pdf-to-md/src/cli/audit.ts"],"sourcesContent":["// audit command — the severity-1 audit instrument (README's \"Design\n// contract\") as a first-class subcommand. Thin wrapper over src/audit.ts's auditWords (the library returns data, only the CLI prints and exits).\nimport { auditWords } from '../audit.ts';\nimport type { Command } from './types.ts';\n\nconst USAGE = 'usage: pdf-to-md audit <words.jsonl> <file.md>';\n\nconst audit: Command = async (ctx) => {\n if (ctx.rest.includes('-h') || ctx.rest.includes('--help')) {\n console.log(USAGE);\n return;\n }\n const [wordsPath, mdPath] = ctx.rest;\n if (!wordsPath || !mdPath) ctx.usageError(USAGE);\n\n const result = auditWords(wordsPath, mdPath);\n for (const line of result.lines) console.log(line);\n\n // MISSING>0 is the severity-1 fail signal: a recognized word this markdown\n // lost. Exit with the CLI's error code so the subcommand is usable as a CI gate; strict_deficits from hyphen-join repairs are reported but not failures.\n if (result.missing > 0) process.exitCode = ctx.errorCode;\n};\n\nexport default audit;\n"],"names":["USAGE","audit","ctx","wordsPath","mdPath","result","line","rest","includes","console","log","usageError","auditWords","lines","missing","process","exitCode","errorCode"],"mappings":"AAAA,oEAAoE;AACpE,iJAAiJ;;;;;+BAsBjJ;;;eAAA;;;uBArB2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAG3B,IAAMA,QAAQ;AAEd,IAAMC,QAAiB,eAAOC;;YAKAA,WAArBC,WAAWC,QAGZC,QACD,2BAAA,mBAAA,gBAAA,WAAA,OAAMC;;YARX,IAAIJ,IAAIK,IAAI,CAACC,QAAQ,CAAC,SAASN,IAAIK,IAAI,CAACC,QAAQ,CAAC,WAAW;gBAC1DC,QAAQC,GAAG,CAACV;gBACZ;;;YACF;YAC4BE,6BAAAA,IAAIK,IAAI,MAA7BJ,YAAqBD,cAAVE,SAAUF;YAC5B,IAAI,CAACC,aAAa,CAACC,QAAQF,IAAIS,UAAU,CAACX;YAEpCK,SAASO,IAAAA,mBAAU,EAACT,WAAWC;YAChC,kCAAA,2BAAA;;gBAAL,IAAK,YAAcC,OAAOQ,KAAK,uBAA1B,6BAAA,QAAA,yBAAA;oBAAMP,OAAN;oBAA4BG,QAAQC,GAAG,CAACJ;;;gBAAxC;gBAAA;;;yBAAA,6BAAA;wBAAA;;;wBAAA;8BAAA;;;;YAEL,2EAA2E;YAC3E,yJAAyJ;YACzJ,IAAID,OAAOS,OAAO,GAAG,GAAGC,QAAQC,QAAQ,GAAGd,IAAIe,SAAS;;;;;IAC1D;;IAEA,WAAehB"}
|
package/dist/cjs/cli/types.d.cts
CHANGED
|
@@ -3,7 +3,9 @@ export interface Ctx {
|
|
|
3
3
|
name: string;
|
|
4
4
|
/** argv after the command word */
|
|
5
5
|
rest: string[];
|
|
6
|
-
/**
|
|
6
|
+
/** the CLI's fixed non-zero exit code, for result signals like audit loss */
|
|
7
|
+
readonly errorCode: number;
|
|
8
|
+
/** print the message and exit with the CLI's error code, on every malformed-invocation path.
|
|
7
9
|
* Readonly property (not method) syntax: TS only applies never-return control-flow analysis to readonly property-typed function members. */
|
|
8
10
|
readonly usageError: (message: string) => never;
|
|
9
11
|
}
|
package/dist/cjs/cli/types.d.ts
CHANGED
|
@@ -3,7 +3,9 @@ export interface Ctx {
|
|
|
3
3
|
name: string;
|
|
4
4
|
/** argv after the command word */
|
|
5
5
|
rest: string[];
|
|
6
|
-
/**
|
|
6
|
+
/** the CLI's fixed non-zero exit code, for result signals like audit loss */
|
|
7
|
+
readonly errorCode: number;
|
|
8
|
+
/** print the message and exit with the CLI's error code, on every malformed-invocation path.
|
|
7
9
|
* Readonly property (not method) syntax: TS only applies never-return control-flow analysis to readonly property-typed function members. */
|
|
8
10
|
readonly usageError: (message: string) => never;
|
|
9
11
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["/Users/kevin/Dev/OpenSource/formats/pdf-to-md/src/cli/types.ts"],"sourcesContent":["// Handed to every command; the command word is peeled off in src/cli.ts and\n// each command owns its own parseArgs table over `rest` (our commands' flags are disjoint, so a shared table would let `render --para-gap=2` parse silently as a no-op).\nexport interface Ctx {\n /** binary name, for usage strings */\n name: string;\n /** argv after the command word */\n rest: string[];\n /** print the message and exit
|
|
1
|
+
{"version":3,"sources":["/Users/kevin/Dev/OpenSource/formats/pdf-to-md/src/cli/types.ts"],"sourcesContent":["// Handed to every command; the command word is peeled off in src/cli.ts and\n// each command owns its own parseArgs table over `rest` (our commands' flags are disjoint, so a shared table would let `render --para-gap=2` parse silently as a no-op).\nexport interface Ctx {\n /** binary name, for usage strings */\n name: string;\n /** argv after the command word */\n rest: string[];\n /** the CLI's fixed non-zero exit code, for result signals like audit loss */\n readonly errorCode: number;\n /** print the message and exit with the CLI's error code, on every malformed-invocation path.\n * Readonly property (not method) syntax: TS only applies never-return control-flow analysis to readonly property-typed function members. */\n readonly usageError: (message: string) => never;\n}\n\nexport type Command = (ctx: Ctx) => Promise<void> | void;\n"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,yKAAyK"}
|
package/dist/cjs/cli.js
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
Object.defineProperty(exports, "__esModule", {
|
|
5
5
|
value: true
|
|
6
6
|
});
|
|
7
|
-
Object.defineProperty(exports, //
|
|
7
|
+
Object.defineProperty(exports, // All failures exit ERROR_CODE: usage errors with the usage text, thrown errors with the message verbatim.
|
|
8
8
|
"default", {
|
|
9
9
|
enumerable: true,
|
|
10
10
|
get: function() {
|
|
@@ -148,6 +148,7 @@ function _ts_generator(thisArg, body) {
|
|
|
148
148
|
// __dirname (CJS) or its ESM equivalent, then two fixed hops up to the
|
|
149
149
|
// package root. NOT `import.meta.resolve('pdf-to-md/package.json')` — Node's self-reference lookup throws ERR_MODULE_NOT_FOUND from a file this deep; a location-relative path is stable across both build targets.
|
|
150
150
|
var __dirname = _nodepath.default.dirname(typeof __filename !== 'undefined' ? __filename : (0, _nodeurl.fileURLToPath)(require("url").pathToFileURL(__filename).toString()));
|
|
151
|
+
var ERROR_CODE = 19;
|
|
151
152
|
function packageVersion() {
|
|
152
153
|
try {
|
|
153
154
|
var _pkg_version;
|
|
@@ -178,7 +179,7 @@ function cli(argv, name) {
|
|
|
178
179
|
// for --help is not.
|
|
179
180
|
if (argv.length === 0) {
|
|
180
181
|
console.error(usage(name));
|
|
181
|
-
process.exit(
|
|
182
|
+
process.exit(ERROR_CODE);
|
|
182
183
|
}
|
|
183
184
|
console.log("".concat(name, " v").concat(packageVersion()));
|
|
184
185
|
console.log('');
|
|
@@ -192,8 +193,9 @@ function cli(argv, name) {
|
|
|
192
193
|
rest: argv.slice(1),
|
|
193
194
|
usageError: function usageError(message) {
|
|
194
195
|
console.error(message);
|
|
195
|
-
process.exit(
|
|
196
|
-
}
|
|
196
|
+
process.exit(ERROR_CODE);
|
|
197
|
+
},
|
|
198
|
+
errorCode: ERROR_CODE
|
|
197
199
|
};
|
|
198
200
|
_state.label = 1;
|
|
199
201
|
case 1:
|
|
@@ -247,7 +249,7 @@ function cli(argv, name) {
|
|
|
247
249
|
case 8:
|
|
248
250
|
err = _state.sent();
|
|
249
251
|
console.error(err.message);
|
|
250
|
-
process.exit(
|
|
252
|
+
process.exit(ERROR_CODE);
|
|
251
253
|
return [
|
|
252
254
|
3,
|
|
253
255
|
9
|
package/dist/cjs/cli.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["/Users/kevin/Dev/OpenSource/formats/pdf-to-md/src/cli.ts"],"sourcesContent":["// Parsing and dispatch only. Commands live in src/cli/, one file each,\n// lazy-loaded — nothing tree- or dependency-heavy may be imported at the top of this file (`render` must never load the OCR engine, `--version` must load almost nothing).\nimport { readFileSync } from 'node:fs';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { COMMANDS } from './cli/index.ts';\nimport type { Ctx } from './cli/types.ts';\n\n// __dirname (CJS) or its ESM equivalent, then two fixed hops up to the\n// package root. NOT `import.meta.resolve('pdf-to-md/package.json')` — Node's self-reference lookup throws ERR_MODULE_NOT_FOUND from a file this deep; a location-relative path is stable across both build targets.\nconst __dirname = path.dirname(typeof __filename !== 'undefined' ? __filename : fileURLToPath(import.meta.url));\n\nfunction packageVersion(): string {\n try {\n const pkgPath = path.resolve(__dirname, '..', '..', 'package.json');\n const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { version?: string };\n return pkg.version ?? 'unknown';\n } catch {\n return 'unknown';\n }\n}\n\nfunction usage(name: string): string {\n return (\n `usage: ${name} <file.pdf> [out.md] [flags...] convert a PDF to markdown\\n` +\n ` ${name} extract <file.pdf> [out.md] [flags...] (same, explicit)\\n` +\n ` ${name} render <file.pdf> <page>[-<page>] [--dpi|-d N (default 288)] [--out|-o DIR (default .)]\\n` +\n ` ${name} audit <words.jsonl> <file.md> severity-1 word-loss check\\n` +\n ` ${name} --version | --help\\n` +\n '\\n' +\n 'extract flags:\\n' +\n ' --ocr force the OCR path (image-only/scanned pages)\\n' +\n ' --no-ocr never fall back to OCR; keep sparse text output\\n' +\n ' --pages N[-M] convert only these 1-based source pages\\n' +\n ' --stdout write markdown to stdout instead of a file\\n' +\n ' --json print the full QA report as JSON\\n' +\n ` --page-markers emit a \"### pN\" heading per page\\n` +\n ' --format md|txt|raw output format (default md; raw = Analysis JSON incl. the\\n' +\n ' report; txt = reading-order plain text)\\n' +\n ' --words-json=FILE OCR path from a recognized-word dump (offline replay)\\n' +\n ' --debug-words=FILE dump every recognized word as JSON lines to FILE\\n' +\n ' --dpi=N OCR render resolution (default 288; raise for tiny print or\\n' +\n ' chart/label pages, >~400 measured worse on ordinary prose)\\n' +\n '\\n' +\n `extract tuning (measured defaults; see README's tuning table):\\n` +\n ' --float-max-words=N --float-max-width=F --float-margin=F --para-gap=F\\n' +\n ' --heading-scale=F --col-max-width=F --col-split=F --line-y-tol=F\\n' +\n ' --line-height-ratio=F\\n' +\n '\\n' +\n 'examples:\\n' +\n ` ${name} book.pdf # text layer -> book.md (auto-OCR if scanned)\\n` +\n ` ${name} scan.pdf out.md --ocr --json # force OCR, print the QA report\\n` +\n ` ${name} book.pdf --pages 27-31 --stdout # re-extract a page range to stdout\\n` +\n ` ${name} render book.pdf 27 # render p27 to PNG for eyeballing (288 dpi)\\n` +\n ` ${name} audit words.jsonl book.md # check no recognized word was lost`\n );\n}\n\n//
|
|
1
|
+
{"version":3,"sources":["/Users/kevin/Dev/OpenSource/formats/pdf-to-md/src/cli.ts"],"sourcesContent":["// Parsing and dispatch only. Commands live in src/cli/, one file each,\n// lazy-loaded — nothing tree- or dependency-heavy may be imported at the top of this file (`render` must never load the OCR engine, `--version` must load almost nothing).\nimport { readFileSync } from 'node:fs';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { COMMANDS } from './cli/index.ts';\nimport type { Ctx } from './cli/types.ts';\n\n// __dirname (CJS) or its ESM equivalent, then two fixed hops up to the\n// package root. NOT `import.meta.resolve('pdf-to-md/package.json')` — Node's self-reference lookup throws ERR_MODULE_NOT_FOUND from a file this deep; a location-relative path is stable across both build targets.\nconst __dirname = path.dirname(typeof __filename !== 'undefined' ? __filename : fileURLToPath(import.meta.url));\nconst ERROR_CODE = 19;\n\nfunction packageVersion(): string {\n try {\n const pkgPath = path.resolve(__dirname, '..', '..', 'package.json');\n const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { version?: string };\n return pkg.version ?? 'unknown';\n } catch {\n return 'unknown';\n }\n}\n\nfunction usage(name: string): string {\n return (\n `usage: ${name} <file.pdf> [out.md] [flags...] convert a PDF to markdown\\n` +\n ` ${name} extract <file.pdf> [out.md] [flags...] (same, explicit)\\n` +\n ` ${name} render <file.pdf> <page>[-<page>] [--dpi|-d N (default 288)] [--out|-o DIR (default .)]\\n` +\n ` ${name} audit <words.jsonl> <file.md> severity-1 word-loss check\\n` +\n ` ${name} --version | --help\\n` +\n '\\n' +\n 'extract flags:\\n' +\n ' --ocr force the OCR path (image-only/scanned pages)\\n' +\n ' --no-ocr never fall back to OCR; keep sparse text output\\n' +\n ' --pages N[-M] convert only these 1-based source pages\\n' +\n ' --stdout write markdown to stdout instead of a file\\n' +\n ' --json print the full QA report as JSON\\n' +\n ` --page-markers emit a \"### pN\" heading per page\\n` +\n ' --format md|txt|raw output format (default md; raw = Analysis JSON incl. the\\n' +\n ' report; txt = reading-order plain text)\\n' +\n ' --words-json=FILE OCR path from a recognized-word dump (offline replay)\\n' +\n ' --debug-words=FILE dump every recognized word as JSON lines to FILE\\n' +\n ' --dpi=N OCR render resolution (default 288; raise for tiny print or\\n' +\n ' chart/label pages, >~400 measured worse on ordinary prose)\\n' +\n '\\n' +\n `extract tuning (measured defaults; see README's tuning table):\\n` +\n ' --float-max-words=N --float-max-width=F --float-margin=F --para-gap=F\\n' +\n ' --heading-scale=F --col-max-width=F --col-split=F --line-y-tol=F\\n' +\n ' --line-height-ratio=F\\n' +\n '\\n' +\n 'examples:\\n' +\n ` ${name} book.pdf # text layer -> book.md (auto-OCR if scanned)\\n` +\n ` ${name} scan.pdf out.md --ocr --json # force OCR, print the QA report\\n` +\n ` ${name} book.pdf --pages 27-31 --stdout # re-extract a page range to stdout\\n` +\n ` ${name} render book.pdf 27 # render p27 to PNG for eyeballing (288 dpi)\\n` +\n ` ${name} audit words.jsonl book.md # check no recognized word was lost`\n );\n}\n\n// All failures exit ERROR_CODE: usage errors with the usage text, thrown errors with the message verbatim.\nexport default async function cli(argv: string[], name: string): Promise<void> {\n if (argv[0] === '--version' || argv[0] === '-v') {\n console.log(packageVersion());\n return;\n }\n if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {\n // No args is a usage ERROR (bare `pdf-to-md` can't do anything); asking\n // for --help is not.\n if (argv.length === 0) {\n console.error(usage(name));\n process.exit(ERROR_CODE);\n }\n console.log(`${name} v${packageVersion()}`);\n console.log('');\n console.log(usage(name));\n return;\n }\n\n const ctx: Ctx = {\n name,\n rest: argv.slice(1),\n usageError(message) {\n console.error(message);\n process.exit(ERROR_CODE);\n },\n errorCode: ERROR_CODE,\n };\n\n try {\n const load = COMMANDS[argv[0]];\n if (load) {\n await (await load()).default(ctx);\n } else {\n // Compat shim: `pdf-to-md file.pdf [...]` — any first word that isn't\n // a reserved command is extract's own first argument.\n ctx.rest = argv;\n await (await COMMANDS.extract()).default(ctx);\n }\n } catch (err) {\n console.error((err as Error).message);\n process.exit(ERROR_CODE);\n }\n}\n"],"names":["cli","__dirname","path","dirname","__filename","fileURLToPath","ERROR_CODE","packageVersion","pkg","pkgPath","resolve","JSON","parse","readFileSync","version","usage","name","argv","ctx","load","err","console","log","length","error","process","exit","rest","slice","usageError","message","errorCode","COMMANDS","default","extract"],"mappings":"AAAA,uEAAuE;AACvE,2KAA2K;;;;;+BA0D3K,2GAA2G;AAC3G;;;eAA8BA;;;sBA1DD;+DACZ;uBACa;uBACL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGzB,uEAAuE;AACvE,oNAAoN;AACpN,IAAMC,YAAYC,iBAAI,CAACC,OAAO,CAAC,OAAOC,eAAe,cAAcA,aAAaC,IAAAA,sBAAa,EAAC;AAC9F,IAAMC,aAAa;AAEnB,SAASC;IACP,IAAI;YAGKC;QAFP,IAAMC,UAAUP,iBAAI,CAACQ,OAAO,CAACT,WAAW,MAAM,MAAM;QACpD,IAAMO,MAAMG,KAAKC,KAAK,CAACC,IAAAA,oBAAY,EAACJ,SAAS;QAC7C,QAAOD,eAAAA,IAAIM,OAAO,cAAXN,0BAAAA,eAAe;IACxB,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA,SAASO,MAAMC,IAAY;IACzB,OACE,AAAC,UAAc,OAALA,MAAK,wEACf,AAAC,UAAc,OAALA,MAAK,gEACf,AAAC,UAAc,OAALA,MAAK,gGACf,AAAC,UAAc,OAALA,MAAK,0EACf,AAAC,UAAc,OAALA,MAAK,2BACf,OACA,qBACA,2EACA,6EACA,qEACA,wEACA,8DACA,8DACA,sFACA,qEACA,mFACA,8EACA,yFACA,wFACA,OACA,qEACA,8EACA,yEACA,8BACA,OACA,gBACA,AAAC,KAAS,OAALA,MAAK,sFACV,AAAC,KAAS,OAALA,MAAK,yEACV,AAAC,KAAS,OAALA,MAAK,4EACV,AAAC,KAAS,OAALA,MAAK,qFACV,AAAC,KAAS,OAALA,MAAK;AAEd;AAGe,SAAehB,IAAIiB,IAAc,EAAED,IAAY;;YAkBtDE,KAWEC,MASCC;;;;oBArCT,IAAIH,IAAI,CAAC,EAAE,KAAK,eAAeA,IAAI,CAAC,EAAE,KAAK,MAAM;wBAC/CI,QAAQC,GAAG,CAACf;wBACZ;;;oBACF;oBACA,IAAIU,KAAKM,MAAM,KAAK,KAAKN,IAAI,CAAC,EAAE,KAAK,YAAYA,IAAI,CAAC,EAAE,KAAK,MAAM;wBACjE,wEAAwE;wBACxE,qBAAqB;wBACrB,IAAIA,KAAKM,MAAM,KAAK,GAAG;4BACrBF,QAAQG,KAAK,CAACT,MAAMC;4BACpBS,QAAQC,IAAI,CAACpB;wBACf;wBACAe,QAAQC,GAAG,CAAC,AAAC,GAAWf,OAATS,MAAK,MAAqB,OAAjBT;wBACxBc,QAAQC,GAAG,CAAC;wBACZD,QAAQC,GAAG,CAACP,MAAMC;wBAClB;;;oBACF;oBAEME,MAAW;wBACfF,MAAAA;wBACAW,MAAMV,KAAKW,KAAK,CAAC;wBACjBC,YAAAA,SAAAA,WAAWC,OAAO;4BAChBT,QAAQG,KAAK,CAACM;4BACdL,QAAQC,IAAI,CAACpB;wBACf;wBACAyB,WAAWzB;oBACb;;;;;;;;;oBAGQa,OAAOa,iBAAQ,CAACf,IAAI,CAAC,EAAE,CAAC;yBAC1BE,MAAAA;;;;oBACK;;wBAAMA;;;oBAAb;;wBAAO,cAAcc,OAAO,CAACf;;;oBAA7B;;;;;;oBAEA,sEAAsE;oBACtE,sDAAsD;oBACtDA,IAAIS,IAAI,GAAGV;oBACJ;;wBAAMe,iBAAQ,CAACE,OAAO;;;oBAA7B;;wBAAO,cAA0BD,OAAO,CAACf;;;oBAAzC;;;;;;;;oBAEKE;oBACPC,QAAQG,KAAK,CAAC,AAACJ,IAAcU,OAAO;oBACpCL,QAAQC,IAAI,CAACpB;;;;;;;;;;;IAEjB"}
|
package/dist/esm/cli/audit.js
CHANGED
|
@@ -12,7 +12,7 @@ const audit = async (ctx)=>{
|
|
|
12
12
|
const result = auditWords(wordsPath, mdPath);
|
|
13
13
|
for (const line of result.lines)console.log(line);
|
|
14
14
|
// MISSING>0 is the severity-1 fail signal: a recognized word this markdown
|
|
15
|
-
// lost. Exit
|
|
16
|
-
if (result.missing > 0) process.exitCode =
|
|
15
|
+
// lost. Exit with the CLI's error code so the subcommand is usable as a CI gate; strict_deficits from hyphen-join repairs are reported but not failures.
|
|
16
|
+
if (result.missing > 0) process.exitCode = ctx.errorCode;
|
|
17
17
|
};
|
|
18
18
|
export default audit;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["/Users/kevin/Dev/OpenSource/formats/pdf-to-md/src/cli/audit.ts"],"sourcesContent":["// audit command — the severity-1 audit instrument (README's \"Design\n// contract\") as a first-class subcommand. Thin wrapper over src/audit.ts's auditWords (the library returns data, only the CLI prints and exits).\nimport { auditWords } from '../audit.ts';\nimport type { Command } from './types.ts';\n\nconst USAGE = 'usage: pdf-to-md audit <words.jsonl> <file.md>';\n\nconst audit: Command = async (ctx) => {\n if (ctx.rest.includes('-h') || ctx.rest.includes('--help')) {\n console.log(USAGE);\n return;\n }\n const [wordsPath, mdPath] = ctx.rest;\n if (!wordsPath || !mdPath) ctx.usageError(USAGE);\n\n const result = auditWords(wordsPath, mdPath);\n for (const line of result.lines) console.log(line);\n\n // MISSING>0 is the severity-1 fail signal: a recognized word this markdown\n // lost. Exit
|
|
1
|
+
{"version":3,"sources":["/Users/kevin/Dev/OpenSource/formats/pdf-to-md/src/cli/audit.ts"],"sourcesContent":["// audit command — the severity-1 audit instrument (README's \"Design\n// contract\") as a first-class subcommand. Thin wrapper over src/audit.ts's auditWords (the library returns data, only the CLI prints and exits).\nimport { auditWords } from '../audit.ts';\nimport type { Command } from './types.ts';\n\nconst USAGE = 'usage: pdf-to-md audit <words.jsonl> <file.md>';\n\nconst audit: Command = async (ctx) => {\n if (ctx.rest.includes('-h') || ctx.rest.includes('--help')) {\n console.log(USAGE);\n return;\n }\n const [wordsPath, mdPath] = ctx.rest;\n if (!wordsPath || !mdPath) ctx.usageError(USAGE);\n\n const result = auditWords(wordsPath, mdPath);\n for (const line of result.lines) console.log(line);\n\n // MISSING>0 is the severity-1 fail signal: a recognized word this markdown\n // lost. Exit with the CLI's error code so the subcommand is usable as a CI gate; strict_deficits from hyphen-join repairs are reported but not failures.\n if (result.missing > 0) process.exitCode = ctx.errorCode;\n};\n\nexport default audit;\n"],"names":["auditWords","USAGE","audit","ctx","rest","includes","console","log","wordsPath","mdPath","usageError","result","line","lines","missing","process","exitCode","errorCode"],"mappings":"AAAA,oEAAoE;AACpE,iJAAiJ;AACjJ,SAASA,UAAU,QAAQ,cAAc;AAGzC,MAAMC,QAAQ;AAEd,MAAMC,QAAiB,OAAOC;IAC5B,IAAIA,IAAIC,IAAI,CAACC,QAAQ,CAAC,SAASF,IAAIC,IAAI,CAACC,QAAQ,CAAC,WAAW;QAC1DC,QAAQC,GAAG,CAACN;QACZ;IACF;IACA,MAAM,CAACO,WAAWC,OAAO,GAAGN,IAAIC,IAAI;IACpC,IAAI,CAACI,aAAa,CAACC,QAAQN,IAAIO,UAAU,CAACT;IAE1C,MAAMU,SAASX,WAAWQ,WAAWC;IACrC,KAAK,MAAMG,QAAQD,OAAOE,KAAK,CAAEP,QAAQC,GAAG,CAACK;IAE7C,2EAA2E;IAC3E,yJAAyJ;IACzJ,IAAID,OAAOG,OAAO,GAAG,GAAGC,QAAQC,QAAQ,GAAGb,IAAIc,SAAS;AAC1D;AAEA,eAAef,MAAM"}
|
package/dist/esm/cli/types.d.ts
CHANGED
|
@@ -3,7 +3,9 @@ export interface Ctx {
|
|
|
3
3
|
name: string;
|
|
4
4
|
/** argv after the command word */
|
|
5
5
|
rest: string[];
|
|
6
|
-
/**
|
|
6
|
+
/** the CLI's fixed non-zero exit code, for result signals like audit loss */
|
|
7
|
+
readonly errorCode: number;
|
|
8
|
+
/** print the message and exit with the CLI's error code, on every malformed-invocation path.
|
|
7
9
|
* Readonly property (not method) syntax: TS only applies never-return control-flow analysis to readonly property-typed function members. */
|
|
8
10
|
readonly usageError: (message: string) => never;
|
|
9
11
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["/Users/kevin/Dev/OpenSource/formats/pdf-to-md/src/cli/types.ts"],"sourcesContent":["// Handed to every command; the command word is peeled off in src/cli.ts and\n// each command owns its own parseArgs table over `rest` (our commands' flags are disjoint, so a shared table would let `render --para-gap=2` parse silently as a no-op).\nexport interface Ctx {\n /** binary name, for usage strings */\n name: string;\n /** argv after the command word */\n rest: string[];\n /** print the message and exit
|
|
1
|
+
{"version":3,"sources":["/Users/kevin/Dev/OpenSource/formats/pdf-to-md/src/cli/types.ts"],"sourcesContent":["// Handed to every command; the command word is peeled off in src/cli.ts and\n// each command owns its own parseArgs table over `rest` (our commands' flags are disjoint, so a shared table would let `render --para-gap=2` parse silently as a no-op).\nexport interface Ctx {\n /** binary name, for usage strings */\n name: string;\n /** argv after the command word */\n rest: string[];\n /** the CLI's fixed non-zero exit code, for result signals like audit loss */\n readonly errorCode: number;\n /** print the message and exit with the CLI's error code, on every malformed-invocation path.\n * Readonly property (not method) syntax: TS only applies never-return control-flow analysis to readonly property-typed function members. */\n readonly usageError: (message: string) => never;\n}\n\nexport type Command = (ctx: Ctx) => Promise<void> | void;\n"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,yKAAyK;AAazK,WAAyD"}
|
package/dist/esm/cli.js
CHANGED
|
@@ -7,6 +7,7 @@ import { COMMANDS } from './cli/index.js';
|
|
|
7
7
|
// __dirname (CJS) or its ESM equivalent, then two fixed hops up to the
|
|
8
8
|
// package root. NOT `import.meta.resolve('pdf-to-md/package.json')` — Node's self-reference lookup throws ERR_MODULE_NOT_FOUND from a file this deep; a location-relative path is stable across both build targets.
|
|
9
9
|
const __dirname = path.dirname(typeof __filename !== 'undefined' ? __filename : fileURLToPath(import.meta.url));
|
|
10
|
+
const ERROR_CODE = 19;
|
|
10
11
|
function packageVersion() {
|
|
11
12
|
try {
|
|
12
13
|
var _pkg_version;
|
|
@@ -20,7 +21,7 @@ function packageVersion() {
|
|
|
20
21
|
function usage(name) {
|
|
21
22
|
return `usage: ${name} <file.pdf> [out.md] [flags...] convert a PDF to markdown\n` + ` ${name} extract <file.pdf> [out.md] [flags...] (same, explicit)\n` + ` ${name} render <file.pdf> <page>[-<page>] [--dpi|-d N (default 288)] [--out|-o DIR (default .)]\n` + ` ${name} audit <words.jsonl> <file.md> severity-1 word-loss check\n` + ` ${name} --version | --help\n` + '\n' + 'extract flags:\n' + ' --ocr force the OCR path (image-only/scanned pages)\n' + ' --no-ocr never fall back to OCR; keep sparse text output\n' + ' --pages N[-M] convert only these 1-based source pages\n' + ' --stdout write markdown to stdout instead of a file\n' + ' --json print the full QA report as JSON\n' + ` --page-markers emit a "### pN" heading per page\n` + ' --format md|txt|raw output format (default md; raw = Analysis JSON incl. the\n' + ' report; txt = reading-order plain text)\n' + ' --words-json=FILE OCR path from a recognized-word dump (offline replay)\n' + ' --debug-words=FILE dump every recognized word as JSON lines to FILE\n' + ' --dpi=N OCR render resolution (default 288; raise for tiny print or\n' + ' chart/label pages, >~400 measured worse on ordinary prose)\n' + '\n' + `extract tuning (measured defaults; see README's tuning table):\n` + ' --float-max-words=N --float-max-width=F --float-margin=F --para-gap=F\n' + ' --heading-scale=F --col-max-width=F --col-split=F --line-y-tol=F\n' + ' --line-height-ratio=F\n' + '\n' + 'examples:\n' + ` ${name} book.pdf # text layer -> book.md (auto-OCR if scanned)\n` + ` ${name} scan.pdf out.md --ocr --json # force OCR, print the QA report\n` + ` ${name} book.pdf --pages 27-31 --stdout # re-extract a page range to stdout\n` + ` ${name} render book.pdf 27 # render p27 to PNG for eyeballing (288 dpi)\n` + ` ${name} audit words.jsonl book.md # check no recognized word was lost`;
|
|
22
23
|
}
|
|
23
|
-
//
|
|
24
|
+
// All failures exit ERROR_CODE: usage errors with the usage text, thrown errors with the message verbatim.
|
|
24
25
|
export default async function cli(argv, name) {
|
|
25
26
|
if (argv[0] === '--version' || argv[0] === '-v') {
|
|
26
27
|
console.log(packageVersion());
|
|
@@ -31,7 +32,7 @@ export default async function cli(argv, name) {
|
|
|
31
32
|
// for --help is not.
|
|
32
33
|
if (argv.length === 0) {
|
|
33
34
|
console.error(usage(name));
|
|
34
|
-
process.exit(
|
|
35
|
+
process.exit(ERROR_CODE);
|
|
35
36
|
}
|
|
36
37
|
console.log(`${name} v${packageVersion()}`);
|
|
37
38
|
console.log('');
|
|
@@ -43,8 +44,9 @@ export default async function cli(argv, name) {
|
|
|
43
44
|
rest: argv.slice(1),
|
|
44
45
|
usageError (message) {
|
|
45
46
|
console.error(message);
|
|
46
|
-
process.exit(
|
|
47
|
-
}
|
|
47
|
+
process.exit(ERROR_CODE);
|
|
48
|
+
},
|
|
49
|
+
errorCode: ERROR_CODE
|
|
48
50
|
};
|
|
49
51
|
try {
|
|
50
52
|
const load = COMMANDS[argv[0]];
|
|
@@ -58,6 +60,6 @@ export default async function cli(argv, name) {
|
|
|
58
60
|
}
|
|
59
61
|
} catch (err) {
|
|
60
62
|
console.error(err.message);
|
|
61
|
-
process.exit(
|
|
63
|
+
process.exit(ERROR_CODE);
|
|
62
64
|
}
|
|
63
65
|
}
|
package/dist/esm/cli.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["/Users/kevin/Dev/OpenSource/formats/pdf-to-md/src/cli.ts"],"sourcesContent":["// Parsing and dispatch only. Commands live in src/cli/, one file each,\n// lazy-loaded — nothing tree- or dependency-heavy may be imported at the top of this file (`render` must never load the OCR engine, `--version` must load almost nothing).\nimport { readFileSync } from 'node:fs';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { COMMANDS } from './cli/index.ts';\nimport type { Ctx } from './cli/types.ts';\n\n// __dirname (CJS) or its ESM equivalent, then two fixed hops up to the\n// package root. NOT `import.meta.resolve('pdf-to-md/package.json')` — Node's self-reference lookup throws ERR_MODULE_NOT_FOUND from a file this deep; a location-relative path is stable across both build targets.\nconst __dirname = path.dirname(typeof __filename !== 'undefined' ? __filename : fileURLToPath(import.meta.url));\n\nfunction packageVersion(): string {\n try {\n const pkgPath = path.resolve(__dirname, '..', '..', 'package.json');\n const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { version?: string };\n return pkg.version ?? 'unknown';\n } catch {\n return 'unknown';\n }\n}\n\nfunction usage(name: string): string {\n return (\n `usage: ${name} <file.pdf> [out.md] [flags...] convert a PDF to markdown\\n` +\n ` ${name} extract <file.pdf> [out.md] [flags...] (same, explicit)\\n` +\n ` ${name} render <file.pdf> <page>[-<page>] [--dpi|-d N (default 288)] [--out|-o DIR (default .)]\\n` +\n ` ${name} audit <words.jsonl> <file.md> severity-1 word-loss check\\n` +\n ` ${name} --version | --help\\n` +\n '\\n' +\n 'extract flags:\\n' +\n ' --ocr force the OCR path (image-only/scanned pages)\\n' +\n ' --no-ocr never fall back to OCR; keep sparse text output\\n' +\n ' --pages N[-M] convert only these 1-based source pages\\n' +\n ' --stdout write markdown to stdout instead of a file\\n' +\n ' --json print the full QA report as JSON\\n' +\n ` --page-markers emit a \"### pN\" heading per page\\n` +\n ' --format md|txt|raw output format (default md; raw = Analysis JSON incl. the\\n' +\n ' report; txt = reading-order plain text)\\n' +\n ' --words-json=FILE OCR path from a recognized-word dump (offline replay)\\n' +\n ' --debug-words=FILE dump every recognized word as JSON lines to FILE\\n' +\n ' --dpi=N OCR render resolution (default 288; raise for tiny print or\\n' +\n ' chart/label pages, >~400 measured worse on ordinary prose)\\n' +\n '\\n' +\n `extract tuning (measured defaults; see README's tuning table):\\n` +\n ' --float-max-words=N --float-max-width=F --float-margin=F --para-gap=F\\n' +\n ' --heading-scale=F --col-max-width=F --col-split=F --line-y-tol=F\\n' +\n ' --line-height-ratio=F\\n' +\n '\\n' +\n 'examples:\\n' +\n ` ${name} book.pdf # text layer -> book.md (auto-OCR if scanned)\\n` +\n ` ${name} scan.pdf out.md --ocr --json # force OCR, print the QA report\\n` +\n ` ${name} book.pdf --pages 27-31 --stdout # re-extract a page range to stdout\\n` +\n ` ${name} render book.pdf 27 # render p27 to PNG for eyeballing (288 dpi)\\n` +\n ` ${name} audit words.jsonl book.md # check no recognized word was lost`\n );\n}\n\n//
|
|
1
|
+
{"version":3,"sources":["/Users/kevin/Dev/OpenSource/formats/pdf-to-md/src/cli.ts"],"sourcesContent":["// Parsing and dispatch only. Commands live in src/cli/, one file each,\n// lazy-loaded — nothing tree- or dependency-heavy may be imported at the top of this file (`render` must never load the OCR engine, `--version` must load almost nothing).\nimport { readFileSync } from 'node:fs';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { COMMANDS } from './cli/index.ts';\nimport type { Ctx } from './cli/types.ts';\n\n// __dirname (CJS) or its ESM equivalent, then two fixed hops up to the\n// package root. NOT `import.meta.resolve('pdf-to-md/package.json')` — Node's self-reference lookup throws ERR_MODULE_NOT_FOUND from a file this deep; a location-relative path is stable across both build targets.\nconst __dirname = path.dirname(typeof __filename !== 'undefined' ? __filename : fileURLToPath(import.meta.url));\nconst ERROR_CODE = 19;\n\nfunction packageVersion(): string {\n try {\n const pkgPath = path.resolve(__dirname, '..', '..', 'package.json');\n const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { version?: string };\n return pkg.version ?? 'unknown';\n } catch {\n return 'unknown';\n }\n}\n\nfunction usage(name: string): string {\n return (\n `usage: ${name} <file.pdf> [out.md] [flags...] convert a PDF to markdown\\n` +\n ` ${name} extract <file.pdf> [out.md] [flags...] (same, explicit)\\n` +\n ` ${name} render <file.pdf> <page>[-<page>] [--dpi|-d N (default 288)] [--out|-o DIR (default .)]\\n` +\n ` ${name} audit <words.jsonl> <file.md> severity-1 word-loss check\\n` +\n ` ${name} --version | --help\\n` +\n '\\n' +\n 'extract flags:\\n' +\n ' --ocr force the OCR path (image-only/scanned pages)\\n' +\n ' --no-ocr never fall back to OCR; keep sparse text output\\n' +\n ' --pages N[-M] convert only these 1-based source pages\\n' +\n ' --stdout write markdown to stdout instead of a file\\n' +\n ' --json print the full QA report as JSON\\n' +\n ` --page-markers emit a \"### pN\" heading per page\\n` +\n ' --format md|txt|raw output format (default md; raw = Analysis JSON incl. the\\n' +\n ' report; txt = reading-order plain text)\\n' +\n ' --words-json=FILE OCR path from a recognized-word dump (offline replay)\\n' +\n ' --debug-words=FILE dump every recognized word as JSON lines to FILE\\n' +\n ' --dpi=N OCR render resolution (default 288; raise for tiny print or\\n' +\n ' chart/label pages, >~400 measured worse on ordinary prose)\\n' +\n '\\n' +\n `extract tuning (measured defaults; see README's tuning table):\\n` +\n ' --float-max-words=N --float-max-width=F --float-margin=F --para-gap=F\\n' +\n ' --heading-scale=F --col-max-width=F --col-split=F --line-y-tol=F\\n' +\n ' --line-height-ratio=F\\n' +\n '\\n' +\n 'examples:\\n' +\n ` ${name} book.pdf # text layer -> book.md (auto-OCR if scanned)\\n` +\n ` ${name} scan.pdf out.md --ocr --json # force OCR, print the QA report\\n` +\n ` ${name} book.pdf --pages 27-31 --stdout # re-extract a page range to stdout\\n` +\n ` ${name} render book.pdf 27 # render p27 to PNG for eyeballing (288 dpi)\\n` +\n ` ${name} audit words.jsonl book.md # check no recognized word was lost`\n );\n}\n\n// All failures exit ERROR_CODE: usage errors with the usage text, thrown errors with the message verbatim.\nexport default async function cli(argv: string[], name: string): Promise<void> {\n if (argv[0] === '--version' || argv[0] === '-v') {\n console.log(packageVersion());\n return;\n }\n if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {\n // No args is a usage ERROR (bare `pdf-to-md` can't do anything); asking\n // for --help is not.\n if (argv.length === 0) {\n console.error(usage(name));\n process.exit(ERROR_CODE);\n }\n console.log(`${name} v${packageVersion()}`);\n console.log('');\n console.log(usage(name));\n return;\n }\n\n const ctx: Ctx = {\n name,\n rest: argv.slice(1),\n usageError(message) {\n console.error(message);\n process.exit(ERROR_CODE);\n },\n errorCode: ERROR_CODE,\n };\n\n try {\n const load = COMMANDS[argv[0]];\n if (load) {\n await (await load()).default(ctx);\n } else {\n // Compat shim: `pdf-to-md file.pdf [...]` — any first word that isn't\n // a reserved command is extract's own first argument.\n ctx.rest = argv;\n await (await COMMANDS.extract()).default(ctx);\n }\n } catch (err) {\n console.error((err as Error).message);\n process.exit(ERROR_CODE);\n }\n}\n"],"names":["readFileSync","path","fileURLToPath","COMMANDS","__dirname","dirname","__filename","url","ERROR_CODE","packageVersion","pkg","pkgPath","resolve","JSON","parse","version","usage","name","cli","argv","console","log","length","error","process","exit","ctx","rest","slice","usageError","message","errorCode","load","default","extract","err"],"mappings":"AAAA,uEAAuE;AACvE,2KAA2K;AAC3K,SAASA,YAAY,QAAQ,UAAU;AACvC,OAAOC,UAAU,YAAY;AAC7B,SAASC,aAAa,QAAQ,WAAW;AACzC,SAASC,QAAQ,QAAQ,iBAAiB;AAG1C,uEAAuE;AACvE,oNAAoN;AACpN,MAAMC,YAAYH,KAAKI,OAAO,CAAC,OAAOC,eAAe,cAAcA,aAAaJ,cAAc,YAAYK,GAAG;AAC7G,MAAMC,aAAa;AAEnB,SAASC;IACP,IAAI;YAGKC;QAFP,MAAMC,UAAUV,KAAKW,OAAO,CAACR,WAAW,MAAM,MAAM;QACpD,MAAMM,MAAMG,KAAKC,KAAK,CAACd,aAAaW,SAAS;QAC7C,QAAOD,eAAAA,IAAIK,OAAO,cAAXL,0BAAAA,eAAe;IACxB,EAAE,OAAM;QACN,OAAO;IACT;AACF;AAEA,SAASM,MAAMC,IAAY;IACzB,OACE,CAAC,OAAO,EAAEA,KAAK,kEAAkE,CAAC,GAClF,CAAC,OAAO,EAAEA,KAAK,0DAA0D,CAAC,GAC1E,CAAC,OAAO,EAAEA,KAAK,0FAA0F,CAAC,GAC1G,CAAC,OAAO,EAAEA,KAAK,oEAAoE,CAAC,GACpF,CAAC,OAAO,EAAEA,KAAK,qBAAqB,CAAC,GACrC,OACA,qBACA,2EACA,6EACA,qEACA,wEACA,8DACA,CAAC,yDAAyD,CAAC,GAC3D,sFACA,qEACA,mFACA,8EACA,yFACA,wFACA,OACA,CAAC,gEAAgE,CAAC,GAClE,8EACA,yEACA,8BACA,OACA,gBACA,CAAC,EAAE,EAAEA,KAAK,gFAAgF,CAAC,GAC3F,CAAC,EAAE,EAAEA,KAAK,mEAAmE,CAAC,GAC9E,CAAC,EAAE,EAAEA,KAAK,sEAAsE,CAAC,GACjF,CAAC,EAAE,EAAEA,KAAK,+EAA+E,CAAC,GAC1F,CAAC,EAAE,EAAEA,KAAK,oEAAoE,CAAC;AAEnF;AAEA,2GAA2G;AAC3G,eAAe,eAAeC,IAAIC,IAAc,EAAEF,IAAY;IAC5D,IAAIE,IAAI,CAAC,EAAE,KAAK,eAAeA,IAAI,CAAC,EAAE,KAAK,MAAM;QAC/CC,QAAQC,GAAG,CAACZ;QACZ;IACF;IACA,IAAIU,KAAKG,MAAM,KAAK,KAAKH,IAAI,CAAC,EAAE,KAAK,YAAYA,IAAI,CAAC,EAAE,KAAK,MAAM;QACjE,wEAAwE;QACxE,qBAAqB;QACrB,IAAIA,KAAKG,MAAM,KAAK,GAAG;YACrBF,QAAQG,KAAK,CAACP,MAAMC;YACpBO,QAAQC,IAAI,CAACjB;QACf;QACAY,QAAQC,GAAG,CAAC,GAAGJ,KAAK,EAAE,EAAER,kBAAkB;QAC1CW,QAAQC,GAAG,CAAC;QACZD,QAAQC,GAAG,CAACL,MAAMC;QAClB;IACF;IAEA,MAAMS,MAAW;QACfT;QACAU,MAAMR,KAAKS,KAAK,CAAC;QACjBC,YAAWC,OAAO;YAChBV,QAAQG,KAAK,CAACO;YACdN,QAAQC,IAAI,CAACjB;QACf;QACAuB,WAAWvB;IACb;IAEA,IAAI;QACF,MAAMwB,OAAO7B,QAAQ,CAACgB,IAAI,CAAC,EAAE,CAAC;QAC9B,IAAIa,MAAM;YACR,MAAM,AAAC,CAAA,MAAMA,MAAK,EAAGC,OAAO,CAACP;QAC/B,OAAO;YACL,sEAAsE;YACtE,sDAAsD;YACtDA,IAAIC,IAAI,GAAGR;YACX,MAAM,AAAC,CAAA,MAAMhB,SAAS+B,OAAO,EAAC,EAAGD,OAAO,CAACP;QAC3C;IACF,EAAE,OAAOS,KAAK;QACZf,QAAQG,KAAK,CAAC,AAACY,IAAcL,OAAO;QACpCN,QAAQC,IAAI,CAACjB;IACf;AACF"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@effortlessmotion/pdf-to-md",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.8",
|
|
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",
|
|
@@ -54,6 +54,7 @@
|
|
|
54
54
|
"@types/mocha": "^10.0.10",
|
|
55
55
|
"@types/node": "^26.2.0",
|
|
56
56
|
"cr": "^0.1.0",
|
|
57
|
+
"fs-remove-compat": "^1.0.4",
|
|
57
58
|
"node-version-use": "^2.5.0",
|
|
58
59
|
"pdf-lib": "^1.17.1",
|
|
59
60
|
"ts-dev-stack": "^1.22.3",
|
|
@@ -66,12 +67,6 @@
|
|
|
66
67
|
"access": "public"
|
|
67
68
|
},
|
|
68
69
|
"allowScripts": {
|
|
69
|
-
"tesseract.js": true
|
|
70
|
-
"core-js-pure": true,
|
|
71
|
-
"@swc/core": true,
|
|
72
|
-
"node-filename-to-dist-paths": true,
|
|
73
|
-
"node-semvers": true,
|
|
74
|
-
"node-version-use": true,
|
|
75
|
-
"thread-sleep-compat": true
|
|
70
|
+
"tesseract.js": true
|
|
76
71
|
}
|
|
77
72
|
}
|