pi-filler 0.2.0 → 0.4.0

package/README.md

@@ -10,11 +10,11 @@ version](https://img.shields.io/npm/v/pi-filler.svg)](https://www.npmjs.com/pack
 downloads](https://img.shields.io/npm/dt/pi-filler.svg)](https://www.npmjs.com/package/pi-filler)
 [![license](https://img.shields.io/npm/l/pi-filler.svg)](https://gitlab.com/Joao-O-Santos/pi-filler/-/blob/main/LICENSE)
 
-**Deterministic DOCX, PDF, and XLSX tooling for Pi.**
+**Deterministic DOCX, PDF, PPTX, and XLSX tooling for Pi.**
 
 `pi-filler` covers document tasks that do not fit an ordinary Markdown
 workflow. It delegates conversion and PDF extraction to mature
-command-line tools while keeping DOCX and XLSX mutations narrow,
+command-line tools while keeping DOCX, PPTX, and XLSX mutations narrow,
 transactional, and inspectable.
 
 The project is experimental and pre-1.0. The README documents the
@@ -45,28 +45,35 @@ Node.js and do not require an office suite.
 The extension exposes one `filler` tool:
 
 ``` text
-format: docx | pdf | xlsx
+format: docx | pdf | pptx | xlsx
 action: read | search | write | patch
-view: text | formatting | image | structure
+view: text | formatting | image | structure | review
 ```
 
-`format` names the document or target format, not every input: DOCX
-writes take Markdown at `path`, and XLSX writes take a workbook template
-at `path` plus CSV at `source_csv`. Choose a supported combination and
-supply only its relevant fields:
+`format` names the document or target format, not every input: DOCX and
+PPTX writes take Markdown at `path`, and XLSX writes take a workbook
+template at `path` plus CSV at `source_csv`. Choose a supported
+combination and supply only its relevant fields:
 
 | Format | Action | View | Required additional fields |
 |---------------|---------------|---------------|---------------------------|
-| DOCX | `read` | `text` or `formatting` | none |
+| DOCX | `read` | `text` | optional `track_changes` |
+| DOCX | `read` | `formatting` | none |
+| DOCX | `read` | `review` | optional `review_offset`, `review_limit` |
 | DOCX | `read` | `image` | `output`; optional `first_page`, `last_page` |
-| DOCX | `search` | `text` or omitted | `query`; optional `ignore_case` |
+| DOCX | `search` | `text` or omitted | `query`; optional `ignore_case`, `track_changes` |
 | DOCX | `write` | omitted | Markdown `path`, `output`; optional `reference_docx` |
 | DOCX | `patch` | omitted | `output`, `patches`; optional `dry_run` |
+| PPTX | `read` | `text` or `formatting` | none |
+| PPTX | `read` | `image` | `output`; optional `first_page`, `last_page` |
+| PPTX | `search` | `text` or omitted | `query`; optional `ignore_case` |
+| PPTX | `write` | omitted | Markdown `path`, `output`; optional `reference_pptx` |
+| PPTX | `patch` | omitted | `output`, `pptx_patches`; optional `dry_run` |
 | PDF | `read` | `text` | optional `first_page`, `last_page` |
 | PDF | `read` | `image` | `output`; optional `first_page`, `last_page` |
 | PDF | `search` | `text` or omitted | `query`; optional `first_page`, `last_page`, `literal`, `ignore_case` |
 | XLSX | `read` | `structure` | none |
-| XLSX | `read` | `image` | `output`; optional `first_page`, `last_page`; all workbook print pages |
+| XLSX | `read` | `image` | `output`; optional `first_page`, `last_page` select resulting workbook print pages |
 | XLSX | `write` | omitted | template `path`, `source_csv`, `sheet`, A1 `start_cell`, `output`; optional `column_map` |
 | XLSX | `patch` | omitted | `sheet`, A1 `range`, `xlsx_patches`, `output` |
 
@@ -115,8 +122,9 @@ filler({
 ```
 
 Results may be truncated. For a truncated PDF text read, use a page
-range; for PDF or DOCX search, narrow the query. PDF search can also use
-a page range. Dry runs still read and validate all local inputs.
+range; for PDF, DOCX, or PPTX search, narrow the query. PDF search can
+also use a page range. Dry runs still read and validate all local
+inputs.
 
 ## PDF operations
 
@@ -130,17 +138,40 @@ a page range. Dry runs still read and validate all local inputs.
 
 ## DOCX operations
 
-- Text reads and search convert DOCX through Pandoc.
+- Text reads and search use Pandoc Markdown, not GFM. `track_changes`
+  defaults to `accept`; choose `reject` for pre-edit text or `all` for
+  insertion/deletion spans and comments. This selects an extraction
+  view; it does not perform native Word acceptance or rejection.
 - Image reads convert DOCX through LibreOffice and then render the
   resulting PDF pages.
-- Writes convert a Markdown input into a validated DOCX, optionally
-  using a reference DOCX for styles and layout.
+- Writes convert Pandoc Markdown into a validated DOCX, including
+  supported native review spans and anchored comments. Smart typography
+  is disabled, preserving literal quotes and dashes. An optional
+  reference DOCX supplies styles and layout defaults; conversion is not
+  a lossless round trip of existing Word layout, comment threads, or
+  every revision type.
 - Formatting reads inspect page setup, margins, sections, line and page
   numbering, comments, inserted/deleted tracked-change markers, and
   common core metadata.
+- Review reads return comment IDs, bounded text/author/date fields,
+  main-document anchor excerpts, and supported legacy reply/resolution
+  metadata. They never edit comments or resolve threads.
 - Patches change first-section page setup, margins, line numbering, page
   numbering, and common core metadata.
 
+Review pagination uses zero-based `review_offset` (default 0) and
+`review_limit` (default 20, maximum 50). A byte budget may return fewer
+records; follow `nextOffset` until it is null. Comment text is capped at
+1,000 Unicode code points and anchor excerpts at 200, with truncation
+flags; author/date fields are bounded to 128/64 UTF-16 code units.
+Ranges include insertion and deletion text, not an accepted-view
+projection. Point anchors show paragraph context. A missing anchor means
+not found in the main document, not necessarily a damaged comment.
+Legacy `commentsExtended` metadata supports resolution and reply-parent
+reporting where matched; additional modern thread features may be
+unsupported and are reported as warnings. This is not native Word
+acceptance/rejection or a complete review-history export.
+
 DOCX page dimensions and margins use twips (twentieths of a point); 1
 inch is 1,440 twips. Page setup, margins, line numbering, and page
 numbering patches apply to the first section only. Core-metadata patches
@@ -156,17 +187,20 @@ or element ordering may change.
 
 ## XLSX operations and privacy
 
-Spreadsheet cell values, CSV fields, formulas, comments, and other
-workbook text are processed locally and are not returned to the model.
-Structural results contain sheet names, ranges, dimensions, counts,
+Spreadsheet cell values, CSV fields, formula contents, and comments are
+processed locally and are not returned to the model. When a
+deterministic XLSX write or patch does not require inspection, do not
+read CSV or cell contents into model context merely to perform it.
+Structural results may contain sheet names, ranges, dimensions, counts,
 merged-range addresses, hidden row and column ranges, changed package
-parts, and write status---not workbook or CSV contents. Layout-range
-arrays are capped and report whether they were truncated; this metadata
-can reveal limited layout and occupancy information.
+parts, and write status---not cell or CSV contents. Layout-range arrays
+are capped and report whether they were truncated; this metadata can
+reveal limited layout and occupancy information.
 
 - `read` with `view: "structure"` reports workbook and worksheet shape.
-- `read` with `view: "image"` renders all workbook print pages through
+- `read` with `view: "image"` renders workbook print pages through
   LibreOffice to numbered PNG files; it does not select a sheet.
+  `first_page` and `last_page` select resulting print pages.
 - `write` fills an existing workbook template from CSV.
 - `patch` changes formatting or layout while preserving cell contents.
 
@@ -189,12 +223,31 @@ calculation or generation, spreadsheet scripting, or manipulation of
 charts, pivots, macros, comments, named ranges, tables, data validation,
 conditional formatting, or external data.
 
+## PPTX operations
+
+- Text reads and search convert PPTX through Pandoc to GFM Markdown.
+- Writes convert GFM Markdown into a validated PPTX; an optional
+  reference PPTX supplies Pandoc presentation styles.
+- Formatting reads report slide dimensions, slide count, and common core
+  metadata.
+- Patches change slide dimensions, common core metadata, and targeted
+  text in slide text paragraphs. Text replacements may target one
+  1-based slide or all slides. They can span formatted text runs, with
+  replacement text inheriting the first run's formatting.
+- PPTX-to-Markdown extraction is semantic and lossy: it is not a
+  reversible representation of positions, animations, themes, or all
+  presentation objects.
+
+Slide dimensions use EMUs (English Metric Units); 914,400 EMUs equal one
+inch. PPTX image reads convert slides through LibreOffice to PDF and
+render numbered PNG files; `first_page` and `last_page` select slides.
+
 ## Output and mutation behavior
 
-DOCX and XLSX writes and patches use temporary sibling files, validate
-the result, and rename it into place only after success. Source files
-are not modified. PDF image rendering similarly protects prior output
-until the new render succeeds.
+DOCX, PPTX, and XLSX writes and patches use temporary sibling files,
+validate the result, and rename it into place only after success. Source
+files are not modified. PDF and office image rendering similarly
+protects prior output until the new render succeeds.
 
 `dry_run` validates the requested operation and inputs without creating
 or replacing output; its required `output` path is still validated.
@@ -203,10 +256,11 @@ or replacing output; its required `output` path is still validated.
 
 Required for the corresponding operations:
 
-- `pandoc` for DOCX text conversion, search, and generation;
-- `libreoffice` for DOCX and XLSX image rendering;
+- `pandoc` for DOCX/PPTX text conversion, search, and generation;
+- `libreoffice` for DOCX, PPTX, and XLSX image rendering (each
+  conversion uses a private temporary profile, removed on completion);
 - `pdftotext` for PDF text extraction;
-- `pdftocairo` for PDF, DOCX, and XLSX page rendering; and
+- `pdftocairo` for PDF, DOCX, PPTX, and XLSX page rendering; and
 - `pdfgrep` for page-aware PDF search.
 
 A missing executable produces an explicit error naming the unavailable
@@ -221,8 +275,9 @@ make site
 ```
 
 `make verify` runs typechecking, lint and formatting checks,
-deterministic tests, and `npm pack --dry-run`. `make site` regenerates
-the tracked static site after documentation changes.
+deterministic tests, project-wide line/function coverage checks, and
+`npm pack --dry-run`. `make site` regenerates the tracked static site
+after documentation changes.
 
 Dependencies and CI actions follow current upstream releases rather than
 being pinned. GitLab is canonical and the only release authority. GitHub

package/package.json

@@ -1,11 +1,12 @@
 {
 	"name": "pi-filler",
-	"version": "0.2.0",
+	"version": "0.4.0",
 	"description": "Deterministic DOCX, PDF, and XLSX tooling for Pi",
 	"keywords": [
 		"pi-package",
 		"pi-extension",
 		"docx",
+		"pptx",
 		"pdf",
 		"xlsx",
 		"pandoc",
@@ -32,6 +33,7 @@
 	],
 	"scripts": {
 		"test": "node --import tsx --test test/*.test.ts",
+		"test:coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-include=src/**/*.ts --test-coverage-lines=90 --test-coverage-functions=90 test/*.test.ts",
 		"typecheck": "tsc --noEmit",
 		"lint": "biome lint src test scripts",
 		"format:check": "biome ci --linter-enabled=false --assist-enabled=false src test scripts biome.json package.json tsconfig.json",
@@ -39,7 +41,7 @@
 		"markdown:check": "node scripts/format-markdown.mjs",
 		"markdown:fix": "node scripts/format-markdown.mjs --write",
 		"style": "npm run lint && npm run format:check && npm run markdown:check",
-		"check": "npm run typecheck && npm run style && npm test",
+		"check": "npm run typecheck && npm run style && npm test && npm run test:coverage",
 		"site": "make site"
 	},
 	"pi": {