formatferry 1.0.28 → 1.0.30
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 +39 -5
- package/dist/index.js +34312 -298
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -44,11 +44,44 @@ already have real text. It is deliberately absent here — the CLI ships no WASM
|
|
|
44
44
|
OCR engine, which keeps the install small and the conversion fully offline.
|
|
45
45
|
|
|
46
46
|
For a PDF that mixes real text pages with scanned inserts, the conversion
|
|
47
|
-
**succeeds**
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
47
|
+
still **succeeds** with exit code 0 — the document has enough text elsewhere
|
|
48
|
+
to avoid the `IMAGE_ONLY` error above — and the scanned pages come through
|
|
49
|
+
empty. That loss is no longer silent: stderr carries one warning naming the
|
|
50
|
+
pages that could not be fully read:
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
Warning: Page(s) 3 could not be fully read: they have little or no extractable text and OCR is not available in this environment, so their content may be missing or incomplete.
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Pipelines that would rather fail than accept a warned conversion can pass
|
|
57
|
+
`--strict`. The complete output is still written (to stdout or the `-o`
|
|
58
|
+
file), and the process then exits 1 after a summary line:
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
$ formatferry -i mixed.pdf --strict; echo "exit=$?"
|
|
62
|
+
Warning: Page(s) 3 could not be fully read: they have little or no extractable text and OCR is not available in this environment, so their content may be missing or incomplete.
|
|
63
|
+
Error: --strict: conversion produced 1 warning(s) [pdf.warnings.ocrUnavailablePages].
|
|
64
|
+
exit=1
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The summary names the machine-readable warning code(s) in brackets, so
|
|
68
|
+
pipelines can triage without parsing prose.
|
|
69
|
+
|
|
70
|
+
Be aware that **any** warning trips `--strict`, not only page-loss warnings:
|
|
71
|
+
advisory notices count too. For example, the xlsx warning "This spreadsheet
|
|
72
|
+
has many columns" fires on wide-but-ordinary spreadsheets and would exit 1
|
|
73
|
+
under `--strict`. This any-warning meaning of bare `--strict` is the permanent
|
|
74
|
+
contract: if a curated data-loss-only mode is ever added, it will be a
|
|
75
|
+
separate additive spelling (for example `--strict=loss`) — bare `--strict`
|
|
76
|
+
will not change meaning underneath existing pipelines.
|
|
77
|
+
|
|
78
|
+
Under `--batch`, each file's warnings are printed to stderr as
|
|
79
|
+
`Warning (<file>): <message>`, and `--strict` exits 1 after the batch
|
|
80
|
+
completes (all outputs still written) if any file warned.
|
|
81
|
+
|
|
82
|
+
One caveat for MCP users: whether the external `formatferry-mcp` wrapper
|
|
83
|
+
forwards `--strict` to the CLI has not been verified; if it filters unknown
|
|
84
|
+
flags, the flag is inert there.
|
|
52
85
|
|
|
53
86
|
Conversion warnings that *are* produced (for example unusual table structures)
|
|
54
87
|
are written to stderr, never stdout, so `formatferry -i doc.pdf > out.md` keeps
|
|
@@ -72,6 +105,7 @@ formatferry [options]
|
|
|
72
105
|
| `--url <url>` | Fetch and convert a web article (requires API key) |
|
|
73
106
|
| `--batch <glob>` | Batch convert files matching a glob pattern (Premium) |
|
|
74
107
|
| `--output-dir <dir>` | Output directory for batch mode |
|
|
108
|
+
| `--strict` | Exit with code 1 if the conversion produced any warnings (including advisory ones) |
|
|
75
109
|
|
|
76
110
|
#### Input Modes
|
|
77
111
|
|