fancy-last-word 0.1.0__tar.gz

fancy_last_word-0.1.0/.gitattributes

@@ -0,0 +1,23 @@
+# Line endings are part of the contract here, so they are pinned rather than
+# left to a clone's `core.autocrlf`.
+#
+# Two reasons, both concrete:
+#
+#  1. The writers are string builders and the OOXML they emit is compared
+#     byte-for-byte against the PHP reference. A source file checked out with
+#     CRLF changes the bytes of any multi-line literal in it.
+#  2. `holy-sheet`'s tool-definition JSON is pinned by a cross-repo SHA-256
+#     that is taken over CRLF-NORMALISED text. A Windows checkout hashes
+#     differently from the same file on Linux, which reads as a drifted schema
+#     when nothing has drifted at all. It has already cost one investigation.
+#
+# The markdown fixtures matter for the same reason: `last-word`'s markdown
+# bridge is asserted byte-exact with LF newlines.
+* text=auto eol=lf
+
+*.docx binary
+*.xlsx binary
+*.pptx binary
+*.png  binary
+*.jpg  binary
+*.jpeg binary

fancy_last_word-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Least-privilege: CI only reads the repo.
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      # Third-party dependency allowlist. Cheap, and failing here is cheap --
+      # the same check gates the release, so a PR that adds an unapproved or
+      # abandoned dependency finds out now rather than at tag time.
+      # The allowlist is FETCHED, never vendored: one source, no copies to drift.
+      - name: Fetch the third-party allowlist
+        uses: actions/checkout@v4
+        with:
+          repository: Particle-Academy/.github
+          path: .third-party-allowlist
+          persist-credentials: false
+
+      - name: Third-party dependency allowlist
+        run: |
+          node .third-party-allowlist/third-party/check.mjs --repo .
+          # Delete it. A fetched checkout left lying in the workspace is not
+          # inert: vitest globbed the checker's own tests out of it and failed
+          # a package whose code was fine. Removed with node, not rm -rf,
+          # because some of these matrices run on windows-latest where a
+          # multi-line run: block is PowerShell and rm -rf is not a command.
+          node -e "require('node:fs').rmSync('.third-party-allowlist',{recursive:true,force:true})"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # PHP is REQUIRED, not optional. tests/test_parity_php.py is the
+      # cross-runtime writer guarantee and it FAILS when php is absent rather
+      # than skipping - a skip here is a green build with zero parity coverage,
+      # which is exactly how two suites in this org reported success over
+      # nothing for months.
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.4"
+          coverage: none
+          extensions: mbstring, zip
+
+      - name: Check out the PHP last-word
+        uses: actions/checkout@v4
+        with:
+          repository: Particle-Academy/last-word
+          path: .php-last-word
+
+      - name: Check out fancy-conformance
+        uses: actions/checkout@v4
+        with:
+          repository: Particle-Academy/fancy-conformance
+          path: .fancy-conformance
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Test
+        run: python -m pytest
+        env:
+          LAST_WORD_PHP_SRC: ${{ github.workspace }}/.php-last-word/src
+          FANCY_CONFORMANCE_ROOT: ${{ github.workspace }}/.fancy-conformance

fancy_last_word-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,87 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+jobs:
+  # Build and publish are separate jobs so `id-token: write` is never held by
+  # the job that executes build code.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      # The one documentation failure that cannot be repaired later: once the
+      # sdist is on PyPI, whoever upgraded into it has no way to learn what
+      # changed. Checked before anything is built.
+      - name: Require a CHANGELOG entry for this tag
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          grep -q "^## \[${version}\]" CHANGELOG.md || {
+            echo "No CHANGELOG.md entry for ${version}."
+            exit 1
+          }
+
+      # Release gate: third-party dependencies must be approved and still
+      # maintained BEFORE the tarball reaches the registry. Once it is
+      # published, an unapproved or abandoned dependency has already shipped
+      # to everyone who upgrades -- the same reason the changelog gate sits
+      # here. The allowlist is FETCHED, never vendored: one source of truth,
+      # so there is no per-repo copy that can drift out of agreement with it.
+      - name: Fetch the third-party allowlist
+        uses: actions/checkout@v4
+        with:
+          repository: Particle-Academy/.github
+          path: .third-party-allowlist
+          persist-credentials: false
+
+      - name: Third-party dependency allowlist
+        run: |
+          node .third-party-allowlist/third-party/check.mjs --repo .
+          # Delete it. A fetched checkout left lying in the workspace is not
+          # inert: vitest globbed the checker's own tests out of it and failed
+          # a package whose code was fine. Removed with node, not rm -rf,
+          # because some of these matrices run on windows-latest where a
+          # multi-line run: block is PowerShell and rm -rf is not a command.
+          node -e "require('node:fs').rmSync('.third-party-allowlist',{recursive:true,force:true})"
+
+      - name: Require the version to match the tag
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          grep -q "^version = \"${version}\"$" pyproject.toml || {
+            echo "pyproject.toml version does not match tag ${GITHUB_REF_NAME}."
+            exit 1
+          }
+
+      - run: python -m pip install --upgrade build && python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dists
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fancy-flow
+    permissions:
+      id-token: write        # mandatory for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dists
+          path: dist/
+      # Pinned by SHA, not by tag: a mutable reference in exactly this position
+      # is what the April 2026 supply-chain compromises exploited.
+      # v1.14.2 -- no `password:` (that is the point) and attestations default
+      # to true.
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33

fancy_last_word-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+.coverage
+htmlcov/
+.DS_Store

fancy_last_word-0.1.0/AGENTS.md

@@ -0,0 +1,170 @@
+# AGENTS.md — last-word-py
+
+The Python mirror of PHP `particle-academy/last-word` and Node
+`@particle-academy/last-word`: a zero-dependency `.docx` writer + reader over a
+JSON document model, plus markdown bridges.
+
+This file describes **this repository's code**. Process — releases, version
+policy, backports, cross-repo conventions — lives in the envelope's `AGENTS.md`
+and must not be copied here.
+
+## Layout
+
+```
+src/last_word/__init__.py        public façade re-exports
+src/last_word/agent.py           the Agent surface, as module-level functions
+src/last_word/exceptions.py      SchemaException
+src/last_word/schema/schema.py   Schema (VERSION, json_schema())
+src/last_word/schema/validator.py
+src/last_word/schema/repairer.py
+src/last_word/schema/types.py    TypedDicts — editor hints only
+src/last_word/writer/docx_writer.py
+src/last_word/reader/docx_reader.py
+src/last_word/markdown/to_markdown.py
+src/last_word/markdown/from_markdown.py
+src/last_word/helpers/xml.py     escaping + the XML declaration
+src/last_word/helpers/image_size.py
+src/last_word/helpers/php.py     PHP semantics Python does not share
+```
+
+The layout mirrors the two peers file-for-file on purpose: a reviewer moving
+between the three should recognise where they are. If you add a module here that
+has no counterpart there, say why in its docstring.
+
+## The one thing that decides everything: PHP parity
+
+**`tests/test_parity_php.py` runs the PHP writer as a subprocess and requires
+byte-identical OOXML parts.** That is the acceptance test for the writer, and it
+is why several things in here look un-Pythonic. Before changing any byte the
+writer emits, understand that you are changing the contract with two other
+engines.
+
+Run the suite with an interpreter it can actually spawn:
+
+```sh
+PHP_BIN='C:/Users/.../php.exe' python -m pytest
+```
+
+`pythonpath = ["src"]` is set, so a bare checkout with nothing but pytest runs
+everything — no install step.
+
+### Never cast the deciding vote on an open ruling
+
+`.ai/plans/polyglot/parity/documents.md` §1.2 holds a ruling table for ~40
+places where the PHP and Node engines already disagree. **That reconciliation
+has not happened**, and the shipped PHP engine is the only executable oracle, so
+this port follows **PHP everywhere**, including where the ruling table has
+already decided against it. Doing otherwise would turn a documented 2-way
+disagreement into an undocumented 3-way one.
+
+Every such site carries a `# RULING PENDING:` comment naming what the ruling
+says. `grep -rn "RULING PENDING" src/` is the whole worklist for when U3 lands.
+Do not "fix" one of them in isolation — the reconciliation is a coordinated
+change across all three engines in one release train.
+
+## Invariants
+
+**XML is built by string concatenation, never `ElementTree.tostring`.** Attribute
+order, self-closing style, namespace prefixes and the escaped character set are
+all part of the byte contract, and the serialiser reproduces none of them
+faithfully. `helpers/xml.py` mirrors PHP's `Helpers\Xml` exactly:
+`text()` escapes `& " < >` (ENT_COMPAT — **not** the apostrophe), `attr()` adds
+`'` → `&apos;` (XML1, not HTML's `&#039;`).
+
+**Never call the builtin `round()`.** Python's is banker's rounding, PHP's is
+half away from zero — `round(0.5)` is `0` here and `1` there. Image extents and
+the read-back `widthPx`/`heightPx` both round, so the builtin is a one-pixel
+disagreement with the reference on exactly the values a fixture picks. Use
+`helpers.php.php_round` / `php_int_round`. `intdiv` is plain truncation, which is
+`//` for the positive values this code uses.
+
+**The rest of `helpers/php.py` exists for the same reason.** `php_truthy` is
+`!empty()` — the string `"0"` is empty in PHP and truthy in Python. `is_numeric`
+rejects booleans and accepts `" 12 "` and `"1e5"`. `php_str` casts `True` to
+`"1"` and `None` to `""`. Reach for them wherever the reference leans on a PHP
+primitive; do not open-code the shim at the call site.
+
+**The zip is deterministic and platform-independent.** Fixed part order, a fixed
+`date_time=(1980, 1, 1, 0, 0, 0)`, and a pinned `create_system = 0` — without
+that last one `ZipInfo` picks the host platform and the same document produces
+different bytes on Windows and Linux. Nothing writes a temp file: the archive is
+built in a `BytesIO`, unlike PHP, whose `ZipArchive` needs a real path.
+
+**The reader refuses a DOCTYPE before parsing.** A `.docx` never legitimately
+carries one, and it is the entry point for entity-expansion attacks. A part
+carrying one is treated as unparsable rather than trusted to a parser flag.
+
+**The reader's deep walks use explicit stacks.** `_parse_inline_container`,
+`_block_children` and `_first_descendant_by_name` are all driven by
+attacker-supplied nesting, and Python's ~1000-frame limit is hit far sooner than
+the peers' would be. Block containers still recurse (much clearer) but carry
+`MAX_CONTAINER_DEPTH`, so a hostile file degrades instead of raising
+`RecursionError` — the reader's contract is that it never throws on strange XML.
+That cap is Python-only; the peers have no equivalent.
+
+**The Repairer copies before it edits.** PHP arrays are values and JS objects are
+spread; Python dicts are references, so a repairer that edited in place would
+silently rewrite the agent's own document. `test_round_trip.py` pins it.
+
+**The document model is plain `dict`s.** `schema/types.py` is TypedDicts for
+editors and type checkers only — nothing constructs, isinstance-checks or
+coerces to them. Making the model a dataclass would move the validation gate
+into a constructor and reject exactly the loose JSON `validate_and_repair()`
+exists to fix.
+
+**Markdown indexes by codepoint, and that is fine.** PHP indexes by byte, but
+every delimiter the inline parser scans for is ASCII, and no ASCII byte occurs
+inside a UTF-8 multi-byte sequence — the offsets agree wherever they are
+compared. The regexes carry `re.ASCII` because their PHP originals have no `/u`
+modifier; dropping it would quietly make a non-breaking space a valid heading
+separator here and nowhere else. The table-cell split is a hand-written scanner
+even though `re` has lookbehind, because that is the algorithm the Rust and Go
+ports must implement without lookaround.
+
+## Testing
+
+TDD, vectors first. The suite is pytest, and the vector numbering matches the
+peers' (`.ai/knowledge/last-word-spec.md`, and `documents.md` §5.4 for 9–11):
+
+| File | What it pins |
+| --- | --- |
+| `test_parity_php.py` | byte-identical parts vs PHP for the shared fixture table |
+| `test_parity_extra.py` | the same, for the writer paths that table misses |
+| `test_package_validity.py` | the container is a well-formed OPC package — the half parity cannot prove, since two engines emitting the same broken package still agree |
+| `test_determinism.py` | two `to_bytes` calls are byte-equal |
+| `test_round_trip.py` | vector 1 — canonical doc survives `to_bytes → read` |
+| `test_markdown.py` | vectors 2–4 — fixpoint, byte identity, and through-docx |
+| `test_validator.py` | vector 4 — errors and repairs, `path`/`message` verbatim |
+| `test_reader_tolerance.py` | vector 5 — Word-authored files, plus the DOCTYPE and depth guards |
+| `test_describe.py` | vector 6 |
+| `test_images.py` | vector 7 — sniffing and the 6.5in cap, asserted on the MODEL |
+| `test_cross_read.py` | a frozen Node-written `.docx` read back |
+| `test_php_helpers.py` | the shims, `php_round` above all |
+| `tests/conformance/` | the shared `fancy-conformance` fixture tables |
+
+`tests/fixtures.py` owns `DOCS` (ported verbatim from the Node suite — do not
+"improve" an entry), `EXTRA_DOCS` (this port's additions) and `normalize_doc`
+(the PHP suite's `lwNormalizeDoc`). `tests/data/` holds the frozen fixtures,
+copied from the PHP repo rather than read across a sibling checkout: a
+cross-read vector that only runs when the neighbouring repo happens to be cloned
+is a vector that stops running.
+
+Assert image sizing on the **read-back model**, not on EMU — a rounding-order
+difference then surfaces as a model diff instead of hiding inside an extent
+nobody compares.
+
+## Known non-fixpoints
+
+`md → docx → md` is **not** byte-identical when the document has a table header
+row. The writer forces `bold` into each header-cell run's `rPr` rather than
+leaving it to a style, because style-only bold does not survive a read-back into
+the model — so the header returns emphasised and markdown renders
+`| **Name** | **Value** |`. PHP does exactly the same for the same input. The
+chain settles after one application, which is what `test_markdown.py` asserts.
+
+## No runtime dependencies. Permanently.
+
+If you think you need one, you have found something worth reporting, not
+installing. `python-docx`, `lxml` and every all-in-one office library are out —
+they would own the document model, and the document model is the product. Test
+dependencies are a different question and need no ceremony.

fancy_last_word-0.1.0/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+**Pre-1.0, breaking changes land in MINOR releases.** Until `1.0.0` the version
+number cannot promise what semver promises; read this file before upgrading a
+minor.
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- First release: the Python mirror of PHP `particle-academy/last-word` and Node
+  `@particle-academy/last-word`. Same JSON document model, same `.docx` on
+  disk — a file written by any of the three opens in the other two.
+- **Agent surface** as module-level functions: `validate`,
+  `validate_and_repair`, `to_bytes`, `write`, `read`, `from_bytes`,
+  `to_markdown`, `from_markdown`, `describe`, `json_schema`, `version`.
+  Reachable as `last_word.to_bytes(doc)` or `last_word.agent.to_bytes(doc)`.
+  `write()` is **synchronous** — Node's is async only because browsers have no
+  synchronous filesystem, and that constraint does not exist here.
+- **DOCX writer** producing the minimal viable OOXML part set in a fixed order,
+  with the title in `docProps/core.xml` (`dc:title`) and code/quote metadata in
+  `lastword:code[:{lang}]` / `lastword:quote` content-control tags — the
+  cross-language slots both mirrors already use.
+- **DOCX reader** that round-trips this writer's own output and tolerates
+  Word-authored files: `outlineLvl` headings, `Heading9` clamped to 6, named
+  `w:highlight` colours, hyperlinks through the rels part, `numPr` lists with
+  `ilvl` nesting, tables, images, page breaks. Unknown constructs degrade to
+  paragraphs; it does not throw on strange XML. Pre-0.2.0 legacy slots (a
+  `Title`-styled paragraph, a `LastWordCode_{lang}` bookmark) still read.
+- **Markdown bridges** (`to_markdown` / `from_markdown`), hand-rolled over the
+  same GFM subset as the peers, including the `<!-- pagebreak -->` convention.
+- **Validator + Repairer** returning the peers' `{path, message}` error list
+  verbatim. The repairer never mutates the document it is given — Python dicts
+  are references where PHP arrays are values, so this needed saying and pinning.
+- **`TypedDict` definitions** in `last_word.schema.types` for editor and
+  type-checker support. The runtime model stays plain `dict`s on purpose: the
+  Validator is the gate, and a dataclass would reject exactly the loose agent
+  JSON `validate_and_repair()` exists to fix.
+- **Cross-runtime parity suite.** `tests/test_parity_php.py` drives the PHP
+  writer as a subprocess and asserts **byte-identical OOXML parts** for every
+  fixture — the shared table ported from the Node suite, plus this port's own
+  additions for adjacent tables, ragged rows, per-list numbering, relationship
+  allocation, XML escaping, hard breaks, alignment, the four image-extent paths
+  and astral-plane text. `tests/test_cross_read.py` reads a frozen `.docx`
+  written by the Node engine. A missing PHP interpreter fails under `CI` rather
+  than skipping.
+- **Deterministic output**: no timestamps in any XML part, fixed part order, a
+  fixed 1980-01-01 zip date and a pinned `create_system`, so the same document
+  yields the same bytes on any platform.
+- Zero runtime dependencies, permanently — `zipfile` and
+  `xml.etree.ElementTree` only.
+
+### Security
+
+- The reader **refuses a DOCTYPE before parsing** any part. A `.docx` never
+  legitimately contains one, and entity expansion on untrusted input is a real
+  hazard (billion laughs, external entity reads); the construct is rejected
+  outright rather than trusted to a parser flag.
+- The reader's inline and descendant walks are iterative, and its block walk
+  carries a depth cap, so deeply nested hostile XML degrades instead of raising
+  `RecursionError`. Python's frame limit is reached long before either peer's
+  stack would be, so this is a Python-specific guard with no counterpart there.
+
+[Unreleased]: https://github.com/Particle-Academy/last-word-py/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Particle-Academy/last-word-py/releases/tag/v0.1.0

fancy_last_word-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

fancy_last_word-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.