pilcrow-docx 0.1.1__py3-none-any.whl

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.
pilcrow/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """DOCX stays authoritative; companions are for review only."""
2
+
3
+ __version__ = "0.1.1"
pilcrow/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())
pilcrow/cli.py ADDED
@@ -0,0 +1,79 @@
1
+ """Refresh files only. Git mutations intentionally do not exist here."""
2
+
3
+ import argparse
4
+ from pathlib import Path
5
+ import sys
6
+
7
+ from . import __version__
8
+ from .extract import DocumentError, extract
9
+ from .files import companions, no_symlinks, orphaned, select, setup, write_if_changed
10
+
11
+
12
+ def parser():
13
+ result = argparse.ArgumentParser(description="Generate readable DOCX companions for GitHub Desktop.")
14
+ result.add_argument("--version", action="version", version=__version__)
15
+ commands = result.add_subparsers(dest="command", required=True)
16
+ for name in ("export", "check"):
17
+ command = commands.add_parser(name, help="refresh companions" if name == "export" else "read-only freshness check")
18
+ command.add_argument("paths", nargs="*", help="DOCX paths, relative to current directory")
19
+ command.add_argument("--root", type=Path, default=Path.cwd(), help="scope and output root (default: current directory)")
20
+ command.add_argument("--all", action="store_true", help="discover DOCX files recursively within --root")
21
+ command = commands.add_parser("setup", help="opt in to LF text and conservative merge rules in .gitattributes")
22
+ command.add_argument("--root", type=Path, default=Path.cwd())
23
+ return result
24
+
25
+
26
+ def main(argv=None):
27
+ args = parser().parse_args(argv)
28
+ root = args.root.resolve()
29
+ if not root.is_dir():
30
+ print(f"error: --root is not an existing directory: {root}", file=sys.stderr)
31
+ return 2
32
+ try:
33
+ if args.command == "setup":
34
+ changed = setup(root)
35
+ print(f"{'Updated' if changed else 'Unchanged'} {root / '.gitattributes'}; review and commit through Git.")
36
+ return 0
37
+ if bool(args.paths) == args.all:
38
+ raise ValueError("specify DOCX paths OR --all; use --root to choose discovery/output scope")
39
+ sources = select(root, args.paths, args.all)
40
+ status = 0
41
+ for source in sources:
42
+ label = source.relative_to(root).as_posix()
43
+ try:
44
+ no_symlinks(source, root)
45
+ result = extract(source)
46
+ changed = []
47
+ for path, content in zip(companions(root, source), result.outputs().values()):
48
+ no_symlinks(path, root)
49
+ if args.command == "export":
50
+ if write_if_changed(path, content, root):
51
+ changed.append(path.name)
52
+ elif not path.exists() or path.read_bytes() != content:
53
+ changed.append(path.name)
54
+ if args.command == "check" and changed:
55
+ print(f"STALE/MISSING {label}: {', '.join(changed)}; run pilcrow export with the same scope")
56
+ status = max(status, 1)
57
+ elif changed:
58
+ print(f"EXPORTED {label}: {', '.join(changed)}")
59
+ else:
60
+ print(f"FRESH {label}: no normalized prose/review changes detected (not a complete document comparison)")
61
+ for warning in result.metadata["warnings"]:
62
+ print(f"warning: {label}: {warning}", file=sys.stderr)
63
+ except (OSError, ValueError, DocumentError) as exc:
64
+ print(f"error: {label}: {exc}", file=sys.stderr)
65
+ status = 2
66
+ if args.all:
67
+ for path in orphaned(root):
68
+ print(f"ORPHAN {path.relative_to(root)}: source deleted or renamed; remove this companion manually if intentional", file=sys.stderr)
69
+ status = max(status, 1)
70
+ if not sources:
71
+ print("No DOCX documents selected within this scope.")
72
+ return status
73
+ except (OSError, ValueError) as exc:
74
+ print(f"error: {exc}", file=sys.stderr)
75
+ return 2
76
+
77
+
78
+ if __name__ == "__main__":
79
+ raise SystemExit(main())
pilcrow/extract.py ADDED
@@ -0,0 +1,365 @@
1
+ """Read WordprocessingML without modifying the package or requiring Word.
2
+
3
+ This is a prose view, not a Word renderer. All omissions are reported in metadata.
4
+ """
5
+
6
+ from collections import Counter
7
+ from dataclasses import dataclass
8
+ import hashlib
9
+ import json
10
+ from pathlib import Path
11
+ import posixpath
12
+ import re
13
+ from zipfile import BadZipFile, ZipFile
14
+
15
+ from defusedxml import ElementTree as ET
16
+
17
+ from .prose import normalize, sentences
18
+
19
+ W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
20
+ R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
21
+ NS = {"w": W}
22
+
23
+
24
+ def w(name):
25
+ return f"{{{W}}}{name}"
26
+
27
+
28
+ def attr(node, name, default=""):
29
+ return node.get(w(name), default)
30
+
31
+
32
+ class DocumentError(ValueError):
33
+ """An input is unavailable or cannot be safely interpreted."""
34
+
35
+
36
+ @dataclass
37
+ class Extraction:
38
+ prose: str
39
+ metadata: dict
40
+
41
+ def outputs(self):
42
+ return {
43
+ ".prose.md": self.prose.encode("utf-8"),
44
+ ".meta.json": (json.dumps(self.metadata, ensure_ascii=False, indent=2,
45
+ sort_keys=True) + "\n").encode("utf-8"),
46
+ }
47
+
48
+
49
+ class Reader:
50
+ def __init__(self, package):
51
+ self.package = package
52
+ self.names = set(package.namelist())
53
+ self.warnings = {
54
+ "Formatting and page layout are not compared; unchanged prose is not an identical document."
55
+ }
56
+ self.review = []
57
+ self.links = []
58
+ self.fields = []
59
+ self.styles = {}
60
+ self.field_stack = []
61
+ self.part = "word/document.xml"
62
+ self.rels = {}
63
+ self.features = Counter()
64
+
65
+ def xml(self, name):
66
+ try:
67
+ return ET.fromstring(self.package.read(name))
68
+ except Exception as exc:
69
+ raise DocumentError(f"cannot parse {name}: {exc}") from exc
70
+
71
+ def relationships(self, part):
72
+ path = posixpath.join(posixpath.dirname(part), "_rels", posixpath.basename(part) + ".rels")
73
+ result = {}
74
+ if path not in self.names:
75
+ return result
76
+ for rel in self.xml(path):
77
+ target = rel.get("Target", "")
78
+ external = rel.get("TargetMode") == "External"
79
+ if not external:
80
+ target = posixpath.normpath(posixpath.join(posixpath.dirname(part), target))
81
+ target = target.lstrip("/")
82
+ if target.startswith("../"):
83
+ raise DocumentError(f"relationship escapes package: {path}")
84
+ result[rel.get("Id")] = (rel.get("Type", "").rsplit("/", 1)[-1], target, external)
85
+ return result
86
+
87
+ def warn(self, message):
88
+ self.warnings.add(message)
89
+
90
+ def raw_text(self, node):
91
+ return normalize("".join(
92
+ (n.text or "") if n.tag in {w("t"), w("delText")} else " "
93
+ for n in node.iter() if n.tag in {w("t"), w("delText"), w("tab"), w("br"), w("cr")}
94
+ ))
95
+
96
+ def inline(self, node):
97
+ tag = node.tag
98
+ local = tag.rsplit("}", 1)[-1]
99
+ if tag in {w("del"), w("ins"), w("moveFrom"), w("moveTo")}:
100
+ self.review.append({"kind": local, "author": attr(node, "author"),
101
+ "text": self.raw_text(node), "part": self.part})
102
+ if local in {"del", "moveFrom"}:
103
+ return ""
104
+ if tag == w("t"):
105
+ # XML source line wrapping is whitespace, unlike Word's explicit w:br.
106
+ return re.sub(r"\s", " ", node.text or "")
107
+ if tag == w("delText"):
108
+ return ""
109
+ if tag in {w("br"), w("cr")}:
110
+ return "\n"
111
+ if tag == w("tab"):
112
+ return " "
113
+ if tag == w("noBreakHyphen"):
114
+ return "\u2011"
115
+ if tag == w("softHyphen"):
116
+ return "\u00ad"
117
+ if tag in {w("footnoteReference"), w("endnoteReference")}:
118
+ kind = "footnote" if tag == w("footnoteReference") else "endnote"
119
+ self.features[kind + " references"] += 1
120
+ return f"[^{kind}-{attr(node, 'id')}]"
121
+ if tag == w("hyperlink"):
122
+ rid = node.get(f"{{{R}}}id")
123
+ rel = self.rels.get(rid)
124
+ target = rel[1] if rel else "#" + attr(node, "anchor")
125
+ if rid and not rel:
126
+ self.warn("Some hyperlink relationships are missing; destinations may be incomplete.")
127
+ visible = "".join(self.inline(child) for child in node)
128
+ self.links.append({"text": normalize(visible), "target": target, "part": self.part})
129
+ return visible
130
+ if tag == w("fldChar"):
131
+ kind = attr(node, "fldCharType")
132
+ if kind == "begin":
133
+ self.field_stack.append([])
134
+ elif kind == "end" and self.field_stack:
135
+ self.record_field("".join(self.field_stack.pop()))
136
+ self.warn("Fields use saved display text, which can be stale; codes are fingerprinted, not evaluated (including Zotero).")
137
+ return ""
138
+ if tag == w("instrText"):
139
+ if self.field_stack:
140
+ self.field_stack[-1].append(node.text or "")
141
+ else:
142
+ self.record_field(node.text or "")
143
+ return ""
144
+ if tag == w("fldSimple"):
145
+ self.record_field(attr(node, "instr"))
146
+ self.warn("Fields use saved display text, which can be stale; codes are fingerprinted, not evaluated (including Zotero).")
147
+ if local in {"drawing", "pict", "object", "txbxContent", "oMath", "oMathPara", "AlternateContent", "altChunk", "sym"}:
148
+ self.warn(f"Unsupported {local}: content is not rendered in prose; inspect the DOCX in Word.")
149
+ self.features[local] += 1
150
+ return f"[Unsupported {local}]"
151
+ if tag in {w("pPr"), w("rPr"), w("sdtPr"), w("sdtEndPr")}:
152
+ return ""
153
+ return "".join(self.inline(child) for child in node)
154
+
155
+ def record_field(self, instruction):
156
+ value = normalize(instruction)
157
+ self.fields.append({"command": value.split(" ", 1)[0],
158
+ "sha256": hashlib.sha256(value.encode()).hexdigest(), "part": self.part})
159
+
160
+ def properties(self, paragraph):
161
+ direct = paragraph.find("w:pPr", NS)
162
+ style = direct.find("w:pStyle", NS) if direct is not None else None
163
+ style_id = attr(style, "val") if style is not None else ""
164
+ properties = []
165
+ if direct is not None:
166
+ properties.append(direct)
167
+ seen = set()
168
+ while style_id in self.styles and style_id not in seen:
169
+ seen.add(style_id)
170
+ current = self.styles[style_id]
171
+ prop = current.find("w:pPr", NS)
172
+ if prop is not None:
173
+ properties.append(prop)
174
+ based = current.find("w:basedOn", NS)
175
+ style_id = attr(based, "val") if based is not None else ""
176
+ return properties, attr(style, "val") if style is not None else ""
177
+
178
+ def paragraph(self, node):
179
+ text = self.inline(node)
180
+ lines = sentences(text)
181
+ if not lines:
182
+ return ""
183
+ props, style_id = self.properties(node)
184
+ outline = next((p.find("w:outlineLvl", NS) for p in props
185
+ if p.find("w:outlineLvl", NS) is not None), None)
186
+ heading = re.fullmatch(r"Heading([1-9])", style_id, flags=re.I)
187
+ if outline is not None and attr(outline, "val").isdigit() and int(attr(outline, "val")) < 9:
188
+ level = min(6, int(attr(outline, "val")) + 1)
189
+ else:
190
+ level = min(6, int(heading[1])) if heading else 0
191
+ num = next((p.find("w:numPr", NS) for p in props if p.find("w:numPr", NS) is not None), None)
192
+ if level:
193
+ return "#" * level + " " + normalize(text)
194
+ if num is not None:
195
+ num_id = num.find("w:numId", NS)
196
+ if num_id is None or attr(num_id, "val") != "0":
197
+ self.warn("List boundaries and indentation are retained; automatic numbering and bullet glyphs are not reconstructed.")
198
+ ilvl = num.find("w:ilvl", NS)
199
+ depth = attr(ilvl, "val", "0") if ilvl is not None else "0"
200
+ indent = " " * min(20, int(depth)) if depth.isdigit() else ""
201
+ return indent + "- " + ("\n" + indent + " ").join(lines)
202
+ return "\n".join(lines)
203
+
204
+ def blocks(self, node):
205
+ parts = []
206
+ for child in node:
207
+ if child.tag == w("p"):
208
+ value = self.paragraph(child)
209
+ elif child.tag == w("tbl"):
210
+ value = self.table(child)
211
+ elif child.tag in {w("sectPr"), w("tcPr"), w("trPr"), w("tblPr"), w("tblGrid"), w("sdtPr"), w("sdtEndPr")}:
212
+ continue
213
+ elif child.tag in {w("del"), w("moveFrom")}:
214
+ self.inline(child) # record review, omit deleted blocks
215
+ continue
216
+ elif child.tag in {w("altChunk"), w("drawing"), w("pict"), w("object")}:
217
+ value = self.inline(child)
218
+ else:
219
+ if child.tag in {w("ins"), w("moveTo")}:
220
+ self.review.append({"kind": child.tag.rsplit("}", 1)[-1], "author": attr(child, "author"),
221
+ "text": self.raw_text(child), "part": self.part})
222
+ value = self.blocks(child)
223
+ if value:
224
+ parts.append(value)
225
+ return "\n\n".join(parts)
226
+
227
+ def table_items(self, node, tag):
228
+ """Unwrap content controls without descending into nested tables."""
229
+ for child in node:
230
+ if child.tag == w(tag):
231
+ yield child
232
+ elif child.tag in {w("sdt"), w("sdtContent"), w("customXml"), w("ins"), w("moveTo")}:
233
+ if child.tag in {w("ins"), w("moveTo")}:
234
+ self.warn("Tracked table structure changes are only partially represented; inspect the DOCX.")
235
+ yield from self.table_items(child, tag)
236
+ elif child.tag in {w("del"), w("moveFrom")}:
237
+ self.inline(child)
238
+
239
+ def table(self, node):
240
+ self.features["tables"] += 1
241
+ lines = ["[Table]"]
242
+ # Explicit cells avoid Markdown pipe escaping and ambiguity for multi-paragraph cells.
243
+ for row in self.table_items(node, "tr"):
244
+ if row.find("w:trPr/w:del", NS) is not None:
245
+ self.warn("Tracked table structure changes are only partially represented; inspect the DOCX.")
246
+ continue
247
+ lines.append("[Row]")
248
+ for cell in self.table_items(row, "tc"):
249
+ span = cell.find("w:tcPr/w:gridSpan", NS)
250
+ merge = cell.find("w:tcPr/w:vMerge", NS)
251
+ label = "[Cell"
252
+ if span is not None:
253
+ label += " span=" + attr(span, "val")
254
+ if merge is not None:
255
+ label += " vertical-merge=" + attr(merge, "val", "continue")
256
+ lines.extend([label + "]", self.blocks(cell) or "(empty)"])
257
+ lines.append("[/Row]")
258
+ lines.append("[/Table]")
259
+ return "\n\n".join(lines)
260
+
261
+ def audit(self, tree):
262
+ # This small allowlist is intentionally conservative: unknown constructs warn.
263
+ known = set("document body p r t delText tab br cr noBreakHyphen softHyphen pPr rPr sectPr tbl tr tc tblPr trPr tcPr tblGrid gridCol sdt sdtContent sdtPr sdtEndPr customXml smartTag ins del moveFrom moveTo hyperlink bookmarkStart bookmarkEnd proofErr permStart permEnd commentRangeStart commentRangeEnd commentReference footnoteReference endnoteReference footnotes footnote endnotes endnote footnoteRef endnoteRef comments comment hdr ftr fldChar instrText fldSimple lastRenderedPageBreak moveFromRangeStart moveFromRangeEnd moveToRangeStart moveToRangeEnd".split())
264
+ def visit(node):
265
+ local = node.tag.rsplit("}", 1)[-1]
266
+ if node.tag.startswith("{" + W + "}") and local not in known:
267
+ self.warn(f"Unsupported Word construct {local}; its semantics are not fully compared.")
268
+ if local.endswith("Pr") or local in {"tblGrid", "sdtEndPr"}:
269
+ for descendant in node.iter():
270
+ name = descendant.tag.rsplit("}", 1)[-1]
271
+ if name in {"vanish", "webHidden", "specVanish"}:
272
+ self.warn("Hidden text is included; visibility formatting is not applied.")
273
+ if name.endswith("Change") or name in {"ins", "del", "cellIns", "cellDel", "cellMerge"}:
274
+ self.warn("Tracked formatting or structure changes are not fully represented; inspect the DOCX.")
275
+ return
276
+ if not node.tag.startswith("{" + W + "}"):
277
+ self.warn(f"Unsupported XML construct {local}; content may be omitted or approximate.")
278
+ for child in node:
279
+ visit(child)
280
+ visit(tree)
281
+
282
+ def render_part(self, part, tree):
283
+ self.part, self.rels = part, self.relationships(part)
284
+ self.audit(tree)
285
+ value = self.blocks(tree)
286
+ if self.field_stack:
287
+ self.warn("Unclosed field codes found; saved display text may be incomplete.")
288
+ while self.field_stack:
289
+ self.record_field("".join(self.field_stack.pop()))
290
+ return value
291
+
292
+ def extract(self):
293
+ if "word/document.xml" not in self.names:
294
+ raise DocumentError("missing word/document.xml; expected a standard DOCX package")
295
+ main = self.xml("word/document.xml")
296
+ if main.tag != w("document") or main.find("w:body", NS) is None:
297
+ raise DocumentError("unsupported Word XML dialect or missing document body (Strict OOXML is not supported)")
298
+ main_rels = self.relationships("word/document.xml")
299
+ supported = {"word/document.xml"}
300
+ for kind, target, external in main_rels.values():
301
+ if kind == "styles" and not external:
302
+ if target not in self.names:
303
+ raise DocumentError(f"missing related part {target}")
304
+ self.styles = {attr(s, "styleId"): s for s in self.xml(target)}
305
+ supported.add(target)
306
+ prose = [self.render_part("word/document.xml", main.find("w:body", NS))]
307
+ # All supported related stories are distinct; never combine headers with body prose.
308
+ stories = sorted({(kind, target) for kind, target, external in main_rels.values()
309
+ if kind in {"footnotes", "endnotes", "comments", "header", "footer"} and not external})
310
+ for kind, part in stories:
311
+ if part not in self.names:
312
+ raise DocumentError(f"missing related part {part}")
313
+ supported.add(part)
314
+ tree = self.xml(part)
315
+ if kind == "comments":
316
+ self.audit(tree)
317
+ for comment in tree:
318
+ self.review.append({"kind": "comment", "author": attr(comment, "author"),
319
+ "text": self.raw_text(comment), "part": part})
320
+ self.warn("Comment text and authors are recorded; anchors, threads, dates, and resolution status are not compared.")
321
+ elif kind in {"footnotes", "endnotes"}:
322
+ for note in tree:
323
+ if attr(note, "type") in {"separator", "continuationSeparator", "continuationNotice"}:
324
+ continue
325
+ singular = kind[:-1]
326
+ prose.append(f"[^{singular}-{attr(note, 'id')}]:\n\n" + self.render_part(part, note))
327
+ else:
328
+ prose.append(f"## {kind.title()} ({part})\n\n" + self.render_part(part, tree))
329
+ self.warn("Headers and footers are shown by part; page/section placement is not reconstructed.")
330
+ for name in sorted(self.names):
331
+ if name in supported or name.endswith("/") or name.endswith(".rels") or name == "[Content_Types].xml" or name.startswith("docProps/"):
332
+ continue
333
+ if name in {"word/settings.xml", "word/webSettings.xml", "word/fontTable.xml", "word/numbering.xml"} or name.startswith("word/theme/"):
334
+ continue
335
+ self.warn(f"Unrendered package part: {name}; changes to its content are not compared.")
336
+ if self.features["footnote references"] and not any(k == "footnotes" for k, _ in stories):
337
+ self.warn("Footnote references have no related footnotes part.")
338
+ if self.features["endnote references"] and not any(k == "endnotes" for k, _ in stories):
339
+ self.warn("Endnote references have no related endnotes part.")
340
+ metadata = {"schema": 1, "view": "accept-insertions-omit-deletions",
341
+ "coverage": "partial-prose", "warnings": sorted(self.warnings),
342
+ "review": self.review, "hyperlinks": self.links, "fields": self.fields}
343
+ return Extraction("\n\n".join(p for p in prose if p).rstrip() + "\n", metadata)
344
+
345
+
346
+ def extract(path: Path) -> Extraction:
347
+ try:
348
+ before = path.stat()
349
+ with ZipFile(path) as package:
350
+ infos = package.infolist()
351
+ if len(infos) > 4096 or sum(i.file_size for i in infos) > 64 * 1024 * 1024:
352
+ raise DocumentError("package exceeds safety limits (4096 entries / 64 MiB uncompressed)")
353
+ if any(i.file_size > 16 * 1024 * 1024 for i in infos):
354
+ raise DocumentError("package part exceeds 16 MiB safety limit")
355
+ if len({i.filename for i in infos}) != len(infos):
356
+ raise DocumentError("duplicate ZIP entries")
357
+ result = Reader(package).extract()
358
+ after = path.stat()
359
+ if (before.st_ino, before.st_size, before.st_mtime_ns) != (after.st_ino, after.st_size, after.st_mtime_ns):
360
+ raise DocumentError("document changed while reading; finish saving and retry")
361
+ return result
362
+ except (OSError, BadZipFile, RuntimeError, ValueError) as exc:
363
+ if isinstance(exc, DocumentError):
364
+ raise
365
+ raise DocumentError(f"cannot read DOCX: {exc}; finish saving, check permissions, and retry") from exc
pilcrow/files.py ADDED
@@ -0,0 +1,152 @@
1
+ """Explicit scope, Git-aware discovery, and atomic companion writes."""
2
+
3
+ import os
4
+ from pathlib import Path
5
+ import subprocess
6
+ import tempfile
7
+
8
+ OUTPUT = ".pilcrow"
9
+ EXCLUDED = {OUTPUT, ".git", ".venv", "venv", "env", "node_modules", "__pycache__", ".tox", ".nox", "build", "dist"}
10
+ SUFFIXES = (".prose.md", ".meta.json")
11
+
12
+
13
+ def git(root, *args):
14
+ try:
15
+ return subprocess.run(["git", "-C", str(root), *args], capture_output=True, check=False)
16
+ except FileNotFoundError:
17
+ return None
18
+
19
+
20
+ def eligible(path):
21
+ return (path.suffix.lower() == ".docx" and not path.name.startswith("~$")
22
+ and not any(p in EXCLUDED for p in path.parts))
23
+
24
+
25
+ def no_symlinks(path, root):
26
+ """Do not follow inputs or outputs outside scope through symlink components."""
27
+ relative = path.relative_to(root)
28
+ current = root
29
+ for component in relative.parts:
30
+ current = current / component
31
+ if current.is_symlink():
32
+ raise ValueError(f"symlink paths are not supported: {current}")
33
+
34
+
35
+ def discover(root):
36
+ probe = git(root, "rev-parse", "--is-inside-work-tree")
37
+ has_git = any((p / ".git").exists() for p in (root, *root.parents))
38
+ if has_git and (probe is None or probe.returncode != 0):
39
+ raise ValueError("Git discovery unavailable in this repository; install/check Git or select explicit paths")
40
+ if probe and probe.returncode == 0 and probe.stdout.strip() == b"true":
41
+ listing = git(root, "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", ".")
42
+ if listing.returncode:
43
+ raise ValueError("Git discovery failed: " + os.fsdecode(listing.stderr).strip())
44
+ paths = {Path(os.fsdecode(p)) for p in listing.stdout.split(b"\0") if p}
45
+ # Deleted tracked inputs are handled by the orphan scan, not resurrected.
46
+ selected = []
47
+ for path in sorted(paths):
48
+ if not eligible(path):
49
+ continue
50
+ source = root / path
51
+ no_symlinks(source, root)
52
+ try:
53
+ source.stat()
54
+ except FileNotFoundError:
55
+ continue
56
+ selected.append(source)
57
+ return selected
58
+ paths = []
59
+ def onerror(error):
60
+ raise error
61
+ for directory, dirs, files in os.walk(root, onerror=onerror, followlinks=False):
62
+ dirs[:] = sorted(d for d in dirs if d not in EXCLUDED and not (Path(directory) / d).is_symlink())
63
+ paths.extend(Path(directory) / f for f in files if eligible(Path(f)))
64
+ return sorted(paths, key=str)
65
+
66
+
67
+ def select(root, paths, all_documents):
68
+ if all_documents:
69
+ return discover(root)
70
+ selected = []
71
+ for raw in paths:
72
+ path = Path(os.path.abspath(raw)) # lexical path: do not resolve a hidden symlink
73
+ try:
74
+ relative = path.relative_to(root)
75
+ except ValueError as exc:
76
+ raise ValueError(f"{raw}: outside --root {root}") from exc
77
+ if not eligible(relative):
78
+ raise ValueError(f"{raw}: expected a DOCX outside lock/output/environment paths")
79
+ selected.append(path)
80
+ return sorted(set(selected), key=str)
81
+
82
+
83
+ def companions(root, source):
84
+ stem = root / OUTPUT / source.relative_to(root)
85
+ return [Path(str(stem) + suffix) for suffix in SUFFIXES]
86
+
87
+
88
+ def orphaned(root):
89
+ base = root / OUTPUT
90
+ no_symlinks(base, root)
91
+ if not base.exists():
92
+ return []
93
+ result = []
94
+ for directory, dirs, files in os.walk(base, followlinks=False):
95
+ for name in dirs:
96
+ no_symlinks(Path(directory) / name, root)
97
+ for name in files:
98
+ path = Path(directory) / name
99
+ for suffix in SUFFIXES:
100
+ if name.endswith(suffix):
101
+ source = root / str(path.relative_to(base))[:-len(suffix)]
102
+ if not source.exists():
103
+ result.append(path)
104
+ return sorted(result, key=str)
105
+
106
+
107
+ def write_if_changed(path, content, root):
108
+ no_symlinks(path, root)
109
+ if path.exists() and path.read_bytes() == content:
110
+ return False
111
+ path.parent.mkdir(parents=True, exist_ok=True)
112
+ temporary = None
113
+ try:
114
+ with tempfile.NamedTemporaryFile(dir=path.parent, prefix=".pilcrow-tmp-", delete=False) as handle:
115
+ temporary = Path(handle.name)
116
+ handle.write(content)
117
+ handle.flush()
118
+ os.fsync(handle.fileno())
119
+ os.replace(temporary, path)
120
+ finally:
121
+ if temporary is not None:
122
+ temporary.unlink(missing_ok=True)
123
+ return True
124
+
125
+
126
+ START = b"# BEGIN Pilcrow generated review rules"
127
+ END = b"# END Pilcrow generated review rules"
128
+ RULES = b"\n".join([
129
+ START,
130
+ b"*.[dD][oO][cC][xX] -merge",
131
+ b".pilcrow/** text eol=lf -merge",
132
+ END,
133
+ ]) + b"\n"
134
+
135
+
136
+ def setup(root):
137
+ path = root / ".gitattributes"
138
+ no_symlinks(path, root)
139
+ old = path.read_bytes() if path.exists() else b""
140
+ if START in old or END in old:
141
+ if old.count(START) != 1 or old.count(END) != 1 or old.index(END) < old.index(START):
142
+ raise ValueError("malformed Pilcrow block in .gitattributes; repair it before setup")
143
+ start = old.index(START)
144
+ end = old.index(END) + len(END)
145
+ if old[end:end+2] == b"\r\n":
146
+ end += 2
147
+ elif old[end:end+1] == b"\n":
148
+ end += 1
149
+ new = old[:start] + RULES + old[end:]
150
+ else:
151
+ new = old + (b"\n" if old and not old.endswith(b"\n") else b"") + RULES
152
+ return write_if_changed(path, new, root)
pilcrow/prose.py ADDED
@@ -0,0 +1,34 @@
1
+ """Deliberately small English-oriented sentence segmentation, not an NLP model."""
2
+
3
+ import re
4
+
5
+ ABBREVIATIONS = frozenset(
6
+ "mr mrs ms dr prof sr jr st vs etc e.g i.e fig figs eq eqs ref refs vol no pp al".split()
7
+ )
8
+ # Split only after terminal punctuation followed by whitespace. Keep closing quotes
9
+ # and reference brackets with the sentence. Decimal points have no following space.
10
+ BOUNDARY = re.compile(r'''[.!?]+[”’"')\]]*\s+''')
11
+
12
+
13
+ def normalize(text: str) -> str:
14
+ return " ".join(text.split())
15
+
16
+
17
+ def sentences(text: str) -> list[str]:
18
+ """Keep explicit Word line breaks; normalize other whitespace after joining runs."""
19
+ result = []
20
+ for line in text.split("\n"):
21
+ line = normalize(line)
22
+ start = 0
23
+ for match in BOUNDARY.finditer(line):
24
+ end = match.end()
25
+ prefix = line[:match.start() + 1]
26
+ token = re.search(r"([\w.]+)\.$", prefix)
27
+ if token and (token[1].lower() in ABBREVIATIONS
28
+ or re.fullmatch(r"(?:[A-Za-z]\.)*[A-Za-z]", token[1])):
29
+ continue
30
+ result.append(line[start: end].strip())
31
+ start = end
32
+ if line[start:]:
33
+ result.append(line[start:])
34
+ return result
@@ -0,0 +1,218 @@
1
+ Metadata-Version: 2.4
2
+ Name: pilcrow-docx
3
+ Version: 0.1.1
4
+ Summary: Readable DOCX companion diffs for ordinary Git workflows
5
+ Requires-Python: >=3.10
6
+ Description-Content-Type: text/markdown
7
+ Requires-Dist: defusedxml<1,>=0.7.1
8
+
9
+ # Pilcrow
10
+
11
+ Pilcrow makes Word text changes reviewable in GitHub Desktop. Keep editing the
12
+ `.docx`; export readable companion files and commit both through your normal Git
13
+ workflow. **The DOCX is authoritative.** The prose is a generated review artifact,
14
+ not an editable replacement or a round-trip format.
15
+
16
+ This is an independent, small Python implementation, conceptually inspired by the
17
+ companion-file approach of stet. No source or tests were copied from that project.
18
+
19
+ ## Install locally
20
+
21
+ Requires Python 3.10 or later. Git is needed for repository discovery and the Git
22
+ workflow. Word is not required to export. From this project's directory:
23
+
24
+ ```sh
25
+ python -m pip install .
26
+ pilcrow --help
27
+ ```
28
+
29
+ Use `python3` instead of `python` on systems where needed. A virtual environment
30
+ is recommended (`python -m venv .venv`); activate it before installing:
31
+
32
+ - macOS/Linux: `source .venv/bin/activate`
33
+ - Windows PowerShell: `.venv\Scripts\Activate.ps1`
34
+ - Windows Command Prompt: `.venv\Scripts\activate.bat`
35
+
36
+ If activation is unavailable, invoke `.venv/bin/python` or
37
+ `.venv\Scripts\python.exe` directly with `-m pip install .`, then `-m pilcrow`.
38
+ For development, use `python -m pip install -e .`.
39
+
40
+ Pilcrow uses Python's ZIP reader and `defusedxml` for XML parsing. There is no Word
41
+ process, cloud service, AI connection, watcher, or background service. Extraction
42
+ never writes to the DOCX.
43
+
44
+ ## Baseline, then review a change
45
+
46
+ In **your document repository**, choose an explicit scope. For example:
47
+
48
+ ```sh
49
+ pilcrow export --all --root .
50
+ pilcrow check --all --root .
51
+ ```
52
+
53
+ Or select documents (paths are relative to your current directory):
54
+
55
+ ```sh
56
+ pilcrow export "report.docx" "chapters/Methods and results.docx" --root .
57
+ ```
58
+
59
+ Outputs retain the complete source-relative filename:
60
+
61
+ ```text
62
+ report.docx
63
+ chapters/Methods and results.docx
64
+ .pilcrow/report.docx.prose.md
65
+ .pilcrow/report.docx.meta.json
66
+ .pilcrow/chapters/Methods and results.docx.prose.md
67
+ .pilcrow/chapters/Methods and results.docx.meta.json
68
+ ```
69
+
70
+ 1. Export a baseline. In GitHub Desktop, review and commit the DOCX and its two
71
+ companion files together. Do not put `.pilcrow/` in `.gitignore`.
72
+ 2. Edit and save the DOCX in Word, or use a separate document-editing tool.
73
+ 3. Run the same `pilcrow export` command again.
74
+ 4. In Desktop's **Changes** view, select the `.prose.md` file to read the text diff;
75
+ inspect `.meta.json` for review/coverage changes. The DOCX may still say binary
76
+ changed. Review formatting/images in Word when relevant.
77
+ 5. Commit the DOCX and both companions together through Desktop, then push and
78
+ branch normally. Desktop's **History** view can show committed companion diffs.
79
+
80
+ Pilcrow never stages, commits, pushes, switches branches, or merges. No direct
81
+ DOCX text converter is installed. The CLI and an ordinary Git diff have been
82
+ tested; **the Microsoft Word / GitHub Desktop GUI workflow has not been tested in
83
+ this Linux environment**. See [manual validation](docs/manual-validation.md).
84
+ See an [actual generated prose and Git diff example](docs/example.md).
85
+ Old commits without companions will not gain prose diffs automatically; there is
86
+ no backfill or history rewriting.
87
+
88
+ ## Scope and discovery
89
+
90
+ - `--root` defaults to the **current directory**, never an automatically detected
91
+ repository top. It controls both discovery and the location of `.pilcrow/`.
92
+ Use the same root each time. From a subdirectory, pass `--root ..` deliberately
93
+ if the output belongs at the parent. Explicit paths remain relative to the
94
+ current directory, not to `--root`.
95
+ - Supply paths **or** `--all`. No arguments does not silently scan the machine.
96
+ Passing a directory as a document is an error; use `--all --root directory`.
97
+ - Inside Git, `--all` uses `git ls-files` for tracked and nonignored untracked
98
+ files within the selected root. Tracked files remain included even if an ignore
99
+ rule matches. An explicitly selected ignored DOCX is allowed.
100
+ - Outside Git, `--all` recursively walks the selected directory. Git ignore rules
101
+ only apply inside a Git worktree; there is no separate ignore syntax.
102
+ - Both modes exclude Word lock files (`~$…`), `.pilcrow`, `.git`, `.venv`, `venv`,
103
+ `env`, `node_modules`, `__pycache__`, `.tox`, `.nox`, `build`, and `dist`.
104
+ Extension matching is case-insensitive. Unicode and spaces are supported.
105
+ - Symlink files/paths are rejected; directory walking does not follow symlink
106
+ directories. Submodule documents are not recursively discovered from the parent
107
+ repository: select a root inside the submodule.
108
+ - `--all` reports orphan companions after source deletion/rename. Remove the old
109
+ companion files manually if the deletion was intentional and commit those
110
+ deletions together. Export never automatically deletes review history files.
111
+ Explicit-file mode checks only selected inputs, not unrelated orphans.
112
+
113
+ ## Check before committing
114
+
115
+ ```sh
116
+ pilcrow check --all --root .
117
+ ```
118
+
119
+ `check` is read-only, even when files are missing. It recomputes expected prose and
120
+ metadata and compares bytes, tolerating ZIP order/compression, run boundaries,
121
+ save timestamps, and other ignored Word metadata. It does not use a DOCX-byte hash.
122
+
123
+ | Exit | Meaning |
124
+ | --- | --- |
125
+ | 0 | Successful export, or companions match the supported normalized view |
126
+ | 1 | Missing/stale companions in `check`, or orphan companions in either command |
127
+ | 2 | Invalid selection, unreadable/malformed input, unsafe path, or write failure |
128
+
129
+ Errors identify the file; remaining selected documents are processed after a
130
+ per-document error. Retry after Word has finished saving if a file is temporarily
131
+ unreadable or changes during extraction. A fresh result means **no supported
132
+ prose/review changes detected**, never that the complete document is identical.
133
+ Warnings appear on stderr and in metadata even for fresh results. Known coverage
134
+ limitations do not themselves cause a nonzero exit.
135
+
136
+ Writes use a temporary file and atomic replacement in the destination directory.
137
+ Byte-identical outputs keep their existing modification times. Each file is
138
+ atomic, **not the whole pair or batch**: if interrupted between files, run `check`
139
+ and export again. Avoid concurrent exports into the same root.
140
+
141
+ ## Branches and conflicts
142
+
143
+ Opt in to conservative merge rules once, from your document repository root:
144
+
145
+ ```sh
146
+ pilcrow setup --root .
147
+ ```
148
+
149
+ This appends a managed block to `.gitattributes`, preserving other rules. Repeating
150
+ it is harmless. Review and commit the file through Desktop. Rules mark DOCX and
151
+ all `.pilcrow/` files `-merge` (Git's binary merge driver), and companion files as
152
+ `text eol=lf`. Both-sided modifications conflict instead of automatically merging
153
+ prose into a document that never existed. Normal one-sided changes still merge.
154
+ More-specific nested attributes can override these rules; inspect with
155
+ `git check-attr merge -- "report.docx" ".pilcrow/report.docx.prose.md"` if needed.
156
+
157
+ When branches conflict:
158
+
159
+ 1. Preserve copies of both versions of the DOCX outside the conflicted path.
160
+ 2. Choose the authoritative version or reconcile the documents manually in Word.
161
+ If using Git commands to select a side, make sure you understand that side in
162
+ the current merge/rebase. Pilcrow does not make this choice.
163
+ 3. Put the resolved DOCX at its repository path. Regenerate its companions, even
164
+ if Git did not flag them as conflicted. Never independently accept a merged
165
+ prose artifact as the Word document.
166
+ 4. Run `pilcrow check --all --root .`. Inspect the resulting text and Word file,
167
+ then mark resolutions and commit using your normal Git workflow.
168
+
169
+ Git commit identity attributes a snapshot, not every contributor between saves.
170
+ For basic snapshot attribution:
171
+
172
+ ```sh
173
+ git blame -- ".pilcrow/report.docx.prose.md"
174
+ ```
175
+
176
+ Word tracked-change authors (included in review metadata) are separate from Git
177
+ authors. Neither proves an edit came from an AI. Companion metadata can contain
178
+ comment authors and deleted text: review it before sharing, just as you would the
179
+ DOCX. No automatic OOXML merging or sentence-lineage system is provided.
180
+
181
+ ## Coverage and maintenance
182
+
183
+ See [coverage, normalization, and backlog](docs/limitations.md). The prose retains
184
+ common headings, list indentation, tables, notes, headers, and footers. Tracked
185
+ insertions/move destinations are included and deletions/move sources omitted.
186
+ Complex tracked structure/layout is limited and reported. Images, equations,
187
+ text boxes, and embedded objects are not rendered. Formatting-only edits can
188
+ leave both companions unchanged and still matter in Word.
189
+
190
+ Run the generated-fixture suite:
191
+
192
+ ```sh
193
+ python -m unittest discover -s tests -v
194
+ ```
195
+
196
+ The implementation has four small modules: `prose.py` (segmentation), `extract.py`
197
+ (OOXML coverage), `files.py` (scope and writes), and `cli.py` (commands). Tests
198
+ include temporary Git repositories and failure cases. Generated fixtures do not
199
+ establish complete Microsoft Word compatibility. No real/private document corpus
200
+ was available for this implementation.
201
+
202
+ ## Releases
203
+
204
+ Every push to `main` runs `.github/workflows/publish.yml`. Release runs are queued
205
+ and each checks out the current `main`, including previous release version bumps.
206
+ The workflow increments the patch version in `pyproject.toml` and
207
+ `src/pilcrow/__init__.py`, builds and validates the distributions, runs the test
208
+ suite, and verifies the installed CLI version. It then commits the version bump, pushes
209
+ the commit and tag atomically, and creates a GitHub release with the wheel and
210
+ source archive. Release commits use `chore(release): ... [skip ci]` to avoid loops.
211
+ If `main` advances during a build, the push fails safely before publishing; the
212
+ queued run checks out the newer `main`.
213
+
214
+ A separate job uploads those same release files to PyPI using Trusted Publishing.
215
+ Configure the PyPI publisher for owner `omertekin2002`, repository `Pilcrow`,
216
+ workflow `publish.yml`, and GitHub environment `pypi`. No PyPI API token is needed.
217
+ If only the PyPI upload fails, fix its configuration and use **Re-run failed jobs**
218
+ on that workflow run to retry the existing release without bumping the version.
@@ -0,0 +1,11 @@
1
+ pilcrow/__init__.py,sha256=SHxFEmR686sCnhCyRPpfstKSXZgHkZSFE4KLot0OaiU,87
2
+ pilcrow/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
3
+ pilcrow/cli.py,sha256=8D9z4Vze4Uve1-x8yuQUEspXWhvR-8KFDOc2P7VkZQ4,3838
4
+ pilcrow/extract.py,sha256=xHE0FknzDGidJDs-hCZ4x9ArZhCXt6hN-OCev0cgPUk,18015
5
+ pilcrow/files.py,sha256=TwIm_w-l0vEAfWHbASCsHSF3KdKhrciFMpsNPDbDNJ4,5480
6
+ pilcrow/prose.py,sha256=5SwTG5B2Em_QytDSLz2Py1m_vufEIlM1CT7aVLSmxuU,1240
7
+ pilcrow_docx-0.1.1.dist-info/METADATA,sha256=zEv5Ks5du1Mb8WgrGAN94jLzx9VxBAUri3UppPYuw8E,10319
8
+ pilcrow_docx-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
9
+ pilcrow_docx-0.1.1.dist-info/entry_points.txt,sha256=V0Bl0qhFOwa5rlCckMTrPka1c5B7WcIrQn9OFd8bYXY,45
10
+ pilcrow_docx-0.1.1.dist-info/top_level.txt,sha256=QhsgKd8tPgpmf1BAxLKPhxS75oH-GVQAYibYvTbSNn8,8
11
+ pilcrow_docx-0.1.1.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ pilcrow = pilcrow.cli:main
@@ -0,0 +1 @@
1
+ pilcrow