An image was recovered and is in ' + "the file. It is not shown here because the preview would be " + "too large to load.
" + ) + continue + spent += len(b.image.data) + src = ("data:" + b.image.content_type + ";base64," + + base64.b64encode(b.image.data).decode("ascii")) + out.append(f'{_esc(b.text)}
") + return "\n".join(out) diff --git a/use-cases/Priyanshu2425/word-doc-repair/backend/docrepair/engine.py b/use-cases/Priyanshu2425/word-doc-repair/backend/docrepair/engine.py new file mode 100644 index 00000000..1b1bc605 --- /dev/null +++ b/use-cases/Priyanshu2425/word-doc-repair/backend/docrepair/engine.py @@ -0,0 +1,376 @@ +"""The repair, as stages someone can watch, and a report they can read. + +The stages are real branch points, not labels. What happens at each one depends +on what the previous one found, and the report says which path was taken -- +because "we recovered your text but lost your tables" and "we recovered +everything" should not look the same to the person who gets the file back. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import Callable + +from . import docx, media, salvage +from .salvage import plural + +Progress = Callable[[str, str], None] # (stage, human-readable message) + +DOCUMENT_PART = "word/document.xml" +DOC_RELS_PART = "word/_rels/document.xml.rels" + +#: Parts that carry a person's words but are not the body of the document. +#: Each is recovered as text and set down at the end under its own heading, +#: because a rebuild cannot put a footnote back at the foot of the page it +#: belonged to -- and a footnote silently folded into the body would change what +#: the document says. +ASIDE_PARTS: list[tuple[str, str]] = [ + ("word/footnotes.xml", "Footnotes"), + ("word/endnotes.xml", "Endnotes"), + ("word/header", "Page header"), + ("word/footer", "Page footer"), +] + +#: Boilerplate Word writes into every footnotes part whether or not the document +#: has footnotes. Carrying it into the rebuild would invent an aside that never +#: existed. +_EMPTY_ASIDE = {"", "-", "\u2014"} + + +@dataclass +class Repair: + ok: bool = False + output: bytes = b"" + filename: str = "repaired.docx" + recovered: list[str] = field(default_factory=list) + lost: list[str] = field(default_factory=list) + stages: list[tuple[str, str]] = field(default_factory=list) + structure_preserved: bool = True + counts: dict[str, int] = field(default_factory=dict) + #: The rebuilt document rendered for reading, pictures included. Shown + #: before the download, never instead of it. + preview_html: str = "" + #: Whether the file's own index had to be gone around. Carried on the report + #: rather than passed between stages, because the stage that discovers it and + #: the stage that is allowed to say it are not the same one. + container_was_damaged: bool = False + + def as_payload(self, download: str | None = None, + style: str | None = None) -> dict: + """The one shape this result takes on the wire. + + Here rather than in `web.py` because two callers need it — the endpoint + and the pytest that records the page's fixtures — and a hand-copied + second version is how a fixture drifts from the thing it imitates while + still claiming to be captured from it. That is BUG-015's shape, and the + capture's own docstring says *recorded exactly as the web endpoint + streams it*, which nothing was holding it to. + """ + return { + "ok": self.ok, + "summary": self.summary(), + "recovered": self.recovered, + "lost": self.lost, + "counts": self.counts, + "structure_preserved": self.structure_preserved, + "filename": self.filename, + "preview_html": self.preview_html, + "download": download if self.ok else None, + # Where the optional styling pass can be started for this result. + # Null on a failure for the same reason `download` is: there is + # nothing to style, and offering the button would be a claim. + "style": style if self.ok else None, + } + + def summary(self) -> str: + """Plain language. Never claims a complete repair.""" + if not self.ok: + reason = self.lost[0] if self.lost else "no readable content was found inside it" + reason = reason[0].upper() + reason[1:] + if not reason.endswith("."): + reason += "." + return ( + f"This file could not be repaired. {reason} " + "Nothing was invented to fill the gap — if there is another copy, " + "even an older one, that is the better starting point." + ) + head = ( + "Recovered what could be read and rebuilt it as a valid Word file. " + "This is a best-effort recovery, not a complete repair." + ) + if not self.structure_preserved: + head += ( + " The document's structure was too damaged to read, so the text was " + "extracted run by run — you are getting the words back, but the " + "headings, tables and formatting are gone." + ) + return head + + +class _Stop(Exception): + """A stage decided the repair cannot go further. + + Raised rather than returned so each stage can refuse from wherever it + discovers the refusal, and `repair` stays a narrative of the happy path with + the refusals visible in one place. Every one of them has already written its + reason into the report before it raises. + """ + + +def repair(data: bytes, filename: str = "document.docx", + on_progress: Progress | None = None) -> Repair: + """The whole repair, as the sequence of decisions it actually is. + + Each stage is its own function, because each one is a different judgement + about somebody's document and they are worth reading separately. What stays + here is the order, which is the part that has to be right: nothing is + claimed as recovered before it has been read, and nothing is written before + everything that could refuse has had its chance to. + """ + r = Repair(filename=_repaired_name(filename)) + + def stage(name: str, msg: str) -> None: + r.stages.append((name, msg)) + if on_progress: + on_progress(name, msg) + + try: + s = _open_container(data, r, stage) + _take_inventory(s, r, stage) + pictures = media.collect(s.members) + blocks, structure_read = _read_body(s, pictures, r, stage) + unplaced = _place_pictures(blocks, pictures, r, stage) + asides = _read_asides(s.members, stage) + blocks.extend(asides.blocks) + _count_what_came_through(blocks, r, stage, structure_read) + _account_for_pictures(pictures, unplaced, asides, r) + except _Stop: + return r + + stage("write", "Rebuilding a clean Word file…") + r.output = docx.write_docx(blocks) + # What is actually in the file, so somebody can look before they decide + # whether it was worth anything. From the research, on a paid repair tool: + # "It just said 'repair successful'. I didn't know if it had actually got + # anything." A claim with nothing behind it is what breaks trust. + r.preview_html = docx.blocks_to_html(blocks, inline_images=True) + r.ok = True + stage("done", "Done. The rebuilt file is ready to download.") + return r + + +def _open_container(data: bytes, r: Repair, stage: Progress) -> salvage.Salvage: + """Get at the parts, going around the index rather than through it.""" + stage("open", "Opening the file…") + s = salvage.salvage_members(data) + for note in s.notes: + stage("open", _sentence(note)) + # The stage log carries every diagnostic. "What came through" is the list a + # worried person reads, so it gets outcomes -- what happened to their + # content -- and not a narration of how the file was opened. The one line + # about the damaged index is held back until there is recovered content to + # attach it to, because on a total failure it would be an overclaim. + r.container_was_damaged = any("internal index was damaged" in n for n in s.notes) + r.lost.extend(s.unrecovered) + + if not s.members: + stage("open", "No readable parts were found inside the file.") + # `salvage` has already said this if it found nothing; saying it twice + # reads as two separate problems. + if not any("no readable parts" in l for l in r.lost): + r.lost.append("the file contained no readable parts") + raise _Stop + return s + + +def _take_inventory(s: salvage.Salvage, r: Repair, stage: Progress) -> None: + """What is here, what can be rebuilt, and what cannot be done without.""" + stage("inventory", f"Found {plural(len(s.members), 'section')} inside the document.") + missing = [p for p in ("[Content_Types].xml", "_rels/.rels", DOCUMENT_PART) + if p not in s.members] + rebuildable = [p for p in missing if p != DOCUMENT_PART] + if rebuildable: + stage("inventory", + f"Rebuilding {plural(len(rebuildable), 'missing structural part')}…") + r.recovered.append( + "rebuilt the file's internal structure, which was missing or damaged — " + "this is standard plumbing and carries none of your content" + ) + + if DOCUMENT_PART not in s.members: + stage("inventory", "The main document part is missing and cannot be rebuilt.") + r.lost.append( + "the main document part is missing entirely, so there is no text to recover" + ) + raise _Stop + + +def _read_body(s: salvage.Salvage, pictures: dict[str, media.Image], r: Repair, + stage: Progress) -> tuple[list[docx.Block], bool]: + """Repair the body, then read structure out of it — or fall back and say so.""" + stage("xml", "Checking the document body for damage…") + fixed, notes = salvage.repair_xml(s.members[DOCUMENT_PART]) + for n in notes: + stage("xml", _sentence(n)) + r.recovered.extend(notes) + if not notes: + stage("xml", "The document body was well-formed.") + + stage("read", "Reading headings, paragraphs and tables…") + targets = media.relationship_targets(s.members.get(DOC_RELS_PART)) + try: + blocks = docx.read_blocks(fixed, targets, pictures) + r.structure_preserved = True + except Exception: + stage("read", "The document's structure was too damaged to read. " + "Recovering the text on its own instead.") + blocks = [docx.Block("paragraph", t) + for t in salvage.text_runs(fixed) if t.strip()] + r.structure_preserved = False + r.lost.append( + "the document structure was unreadable, so headings, tables and " + "formatting could not be preserved — only the text was recovered" + ) + + if not blocks and not pictures: + stage("read", "No readable content was found in the document body.") + r.lost.append("the document body contained no readable text") + raise _Stop + return blocks, r.structure_preserved + + +def _place_pictures(blocks: list[docx.Block], pictures: dict[str, media.Image], + r: Repair, stage: Progress) -> list[media.Image]: + """Collect at the end the pictures the body could not be shown to reference. + + Either the part naming which file each reference points at did not survive, + or the text fell back to a run-by-run read that carries no positions. They + are still the owner's pictures, so they go at the end — an image silently + placed in the wrong paragraph is worse than one obviously placed last. + """ + placed = {b.image.name for b in docx.image_blocks(blocks)} + unplaced = [img for name, img in sorted(pictures.items()) if name not in placed] + if unplaced: + stage("read", f"Recovered {plural(len(unplaced), 'picture')} " + "whose original position could not be worked out.") + blocks.append(docx.Block("heading", "Pictures recovered from this document", + level=1)) + blocks.extend(docx.Block("image", text=img.name, image=img) for img in unplaced) + return unplaced + + +def _count_what_came_through(blocks: list[docx.Block], r: Repair, stage: Progress, + structure_read: bool) -> None: + r.counts = { + "headings": sum(1 for b in blocks if b.kind == "heading"), + "paragraphs": sum(1 for b in blocks if b.kind == "paragraph"), + "tables": sum(1 for b in blocks if b.kind == "table"), + "pictures": len(docx.image_blocks(blocks)), + } + parts = [plural(r.counts[k], k[:-1]) + for k in ("headings", "paragraphs", "tables", "pictures") + if r.counts[k]] + tally = parts[0] if len(parts) == 1 else ", ".join(parts[:-1]) + f" and {parts[-1]}" + stage("read", f"Recovered {tally}.") + if r.container_was_damaged: + r.recovered.insert(0, "read your content out of a file whose internal index " + "was damaged — the damage Word refuses to open") + if structure_read: + r.recovered.append(f"kept {tally}, with their structure intact") + else: + r.recovered.append(f"recovered the text of {plural(len(blocks), 'paragraph')}") + + +def _account_for_pictures(pictures: dict[str, media.Image], + unplaced: list[media.Image], asides: "Asides", + r: Repair) -> None: + """Say where the pictures and the asides ended up, and where they did not.""" + placed = len(pictures) - len(unplaced) + if placed: + r.recovered.append( + f"carried {plural(placed, 'picture')} back into the document, " + + ("where they were" if placed > 1 else "where it was") + ) + if unplaced: + r.recovered.append( + f"recovered {plural(len(unplaced), 'picture')} and set " + f"{'them' if len(unplaced) > 1 else 'it'} at the end, under a heading" + ) + them = "they are" if len(unplaced) > 1 else "it is" + belonged = "they belonged" if len(unplaced) > 1 else "it belonged" + r.lost.append( + f"the original position of {plural(len(unplaced), 'picture')} could not " + f"be recovered, so {them} collected at the end rather than put back " + f"where {belonged}" + ) + for label, count in asides.recovered: + r.recovered.append( + f"recovered the text of {plural(count, label.lower())}" + if count > 1 else f"recovered the {label.lower()}" + ) + if asides.blocks: + r.lost.append( + "footnotes, headers and footers could not be put back into their " + "original places, so their text is set down at the end of the " + "document under its own heading" + ) + for label in asides.unreadable: + r.lost.append(f"the {label.lower()} could not be read") + + +def _sentence(text: str) -> str: + text = text[0].upper() + text[1:] + return text if text.endswith((".", "…", "!", "?")) else text + "." + + +def _repaired_name(filename: str) -> str: + stem = filename.rsplit("/", 1)[-1] + if stem.lower().endswith(".docx"): + stem = stem[:-5] + return f"{stem}-repaired.docx" + + +@dataclass +class Asides: + """Text that belongs to the document but not to its body.""" + + blocks: list[docx.Block] = field(default_factory=list) + recovered: list[tuple[str, int]] = field(default_factory=list) + unreadable: list[str] = field(default_factory=list) + + +def _read_asides(members: dict[str, bytes], stage: Progress) -> Asides: + """Footnotes, endnotes, headers and footers, as text under their own heading. + + They live in their own parts, so they survive exactly the damage that + destroys the index — the same reason the pictures do. Dropping them was + losing content that was sitting right there. + + What this deliberately does not do is fold them into the body. A footnote + read as a paragraph changes what the document says, and a page header + repeated as body text reads as something the author wrote. They are set + down at the end, labelled, and the report says they are not where they were. + """ + out = Asides() + for prefix, label in ASIDE_PARTS: + names = sorted(n for n in members + if n == prefix or (prefix.endswith(("header", "footer")) + and n.startswith(prefix) + and n.endswith(".xml"))) + texts: list[str] = [] + for name in names: + try: + fixed, _ = salvage.repair_xml(members[name]) + runs = [t.strip() for t in salvage.text_runs(fixed) if t.strip()] + except Exception: + out.unreadable.append(label) + continue + texts.extend(t for t in runs if t not in _EMPTY_ASIDE) + if not texts: + continue + stage("read", f"Recovering the {label.lower()}…") + out.blocks.append(docx.Block("heading", f"{label}, recovered separately", + level=2)) + out.blocks.extend(docx.Block("paragraph", t) for t in texts) + out.recovered.append((label, len(texts))) + return out diff --git a/use-cases/Priyanshu2425/word-doc-repair/backend/docrepair/media.py b/use-cases/Priyanshu2425/word-doc-repair/backend/docrepair/media.py new file mode 100644 index 00000000..ff128cd1 --- /dev/null +++ b/use-cases/Priyanshu2425/word-doc-repair/backend/docrepair/media.py @@ -0,0 +1,243 @@ +"""Getting the pictures back. + +A `.docx` keeps its images as ordinary members of the ZIP — `word/media/image1.png` +and so on — each with its own local file header, entirely separate from +`word/document.xml`. Which means they survive exactly the damage that destroys +the index, and a rebuild that drops them is throwing away bytes that were sitting +right there. + +That mattered to somebody. From the research, describing a report that broke: +*"it was a report with photos and a table of numbers"* — and later, on what the +recovery cost them, *"the photos I got off my phone again — the ones I still +had."* The words came back and the pictures did not, and re-sourcing the +pictures was most of the work. + +Two things this module refuses to do: + +* **Guess at a size.** Word needs an explicit extent in EMUs for an inline + image. The dimensions are read out of the image's own header — PNG, JPEG and + GIF all carry them in the first few bytes — and an image whose header cannot + be read gets a stated default rather than a fabricated measurement, with the + aspect ratio left alone rather than invented. +* **Pretend it knows where a picture went.** A drawing's position is recoverable + only when the relationship part survived to say which file the reference points + at. When it did not, the image is still returned — at the end, under its own + heading, with the report saying plainly that its original position could not be + recovered. An image silently placed in the wrong paragraph is worse than an + image obviously placed at the end. +""" + +from __future__ import annotations + +import re +import struct +from dataclasses import dataclass +from xml.etree import ElementTree as ET + +MEDIA_DIR = "word/media/" + +#: 914400 EMU to the inch, and images are authored at 96 DPI by convention. +EMU_PER_PX = 9525 +#: Six inches. Wider than the text column on A4 with the margins this rebuild +#: writes, so a large photograph is scaled down rather than running off the page. +MAX_WIDTH_EMU = 6 * 914400 +#: What an image gets when its header cannot be read: a square, stated as a +#: default in the code rather than presented as a measurement. +FALLBACK_PX = (480, 360) + +CONTENT_TYPES = { + "png": "image/png", "jpg": "image/jpeg", "jpeg": "image/jpeg", + "gif": "image/gif", "bmp": "image/bmp", "tif": "image/tiff", + "tiff": "image/tiff", "emf": "image/x-emf", "wmf": "image/x-wmf", + "svg": "image/svg+xml", "webp": "image/webp", +} + +_R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships" +_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships" +_A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main" + + +@dataclass(frozen=True) +class Image: + """One recovered picture.""" + + name: str # the member name inside the original, e.g. word/media/image1.png + data: bytes + width_px: int + height_px: int + measured: bool # False when the dimensions are the stated fallback + + @property + def ext(self) -> str: + return self.name.rsplit(".", 1)[-1].lower() if "." in self.name else "png" + + @property + def content_type(self) -> str: + return CONTENT_TYPES.get(self.ext, "application/octet-stream") + + @property + def extent(self) -> tuple[int, int]: + """Width and height in EMUs, scaled to fit the page, aspect preserved.""" + w = max(1, self.width_px) * EMU_PER_PX + h = max(1, self.height_px) * EMU_PER_PX + if w > MAX_WIDTH_EMU: + h = int(h * MAX_WIDTH_EMU / w) + w = MAX_WIDTH_EMU + return w, h + + +# -- reading a size out of the bytes ---------------------------------------- + +def image_size(data: bytes) -> tuple[int, int] | None: + """Width and height from the image's own header, or None. + + Deliberately hand-rolled over the three formats that account for almost + every image in a Word document. A dependency here would be a dependency in a + tool whose whole promise is that it runs offline, in milliseconds, for + somebody who is already having a bad day. + """ + if len(data) < 12: + return None + if data[:8] == b"\x89PNG\r\n\x1a\n" and len(data) >= 24: + w, h = struct.unpack(">II", data[16:24]) + return (w, h) if w and h else None + if data[:3] == b"GIF": + w, h = struct.unpack("
+
+
+
+
+
+
+
+ );
+}
diff --git a/use-cases/Priyanshu2425/word-doc-repair/frontend/src/components/Preview.tsx b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/components/Preview.tsx
new file mode 100644
index 00000000..addfe64e
--- /dev/null
+++ b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/components/Preview.tsx
@@ -0,0 +1,32 @@
+/**
+ * What is actually in the file, before anybody decides whether it was worth it.
+ *
+ * From the research, on a paid repair site: *"It ran for a bit and then wanted
+ * forty dollars to download the result... It just said 'repair successful'. I
+ * didn't know if it had actually got anything."* They did not pay, and they
+ * rewrote the document by hand over a Sunday.
+ *
+ * A verdict is a claim. This is the thing itself — and it is the one part of
+ * this page whose honesty needs no wording at all.
+ *
+ * The markup comes from the engine, which escapes every piece of text it is
+ * given and emits no attribute it did not construct, so what lands here is the
+ * reader's own document and nothing else.
+ */
+export function Preview({ html }: { html: string }) {
+ if (!html.trim()) return null;
+ return (
+ + Salvage. +
+ document recovery +
+
+
+
+
+ {phase === "idle" ? (
+ <>
+
+
+ Your Word file will not open.
++ Hand it over and this page will read whatever is still intact inside it, rebuild + what it can, and tell you plainly what it could not. +
+ + + + {problem ? ( ++ That file was not taken. + {problem} +
+ ) : null} + +-
+
- + + + Your original is never changed. It is read, not written to, and it stays + exactly where it is on your machine. + + +
- + + + Your file is not kept. The repaired copy is held for about thirty minutes + so you can download it, then it is let go. + + +
- + + + No account, and nothing to install. This works in the page you are + looking at. + + +
- + + + It is a best-effort recovery. It will not promise you a complete repair, + and it will name anything it could not bring back. + + +
+ {phase === "working" + ? "Reading your document" + : report?.ok + ? "Your document, as far as it could be read" + : "This file could not be repaired"} +
+
+
+ file {handed.name}
+
+
+ size {readableSize(handed.size)}
+
+
+ docket {docket(handed.name)}
+
+
+
+ {phase === "working" ? (
+ -
+ {stages.map((s, i) => (
+
- + + {s.message} + + ))} +
+ {phase === "working" + ? stages[stages.length - 1]?.message ?? "Working." + : report?.summary ?? ""} +
+ + {phase === "working" ? ( ++ Working + +
+ ) : null} + + {phase === "done" && report ? ( + <> +
+
+
+ ) : null}
+
+ ) : null}
+ What it did, step by step ({stages.length})
+-
+ {stages.map((s, i) => (
+
- + + {s.message} + + ))} +
+ There is a command-line version of the same engine for a folder of damaged files:{" "}
+ python3 backend/cli.py broken.docx
+
+ What is in the file +
++ Read it here before you download it. This is the rebuilt document itself, not a + description of it. +
+
+
+
+ + What happened to your document +
++ + {stamp} + +
+{report.summary}
+ + {report.ok && report.recovered.length > 0 ? ( +
+
+ ) : null}
+
+ {report.lost.length > 0 ? (
+ What came through
+-
+ {report.recovered.map((line) => (
+
- + ✓ + {line} + + ))} +
+
+ ) : null}
+
+ {report.ok ? + {report.ok ? "What did not come through" : "What went wrong"} +
+-
+ {report.lost.map((line) => (
+
- + × + {line} + + ))} +
+
+
+ ) : null}
+
+ {report.ok && report.style ? (
+
+
+ Download the repaired file
+
+
+ + Saved as {report.filename}. You can download it more than once. This page holds + it for about thirty minutes and then lets it go — if the link stops working, repair the + document again. Your original was never changed. +
+
+
+
+ {note}
: null; + } + + const run = async () => { + setPhase("working"); + setStages([]); + setProblem(null); + try { + const result = await styleDocument(url, (s) => setStages((prev) => [...prev, s])); + setStyled(result); + setPhase("done"); + } catch (e) { + setProblem( + e instanceof RepairError + ? e.message + : "Styling did not work. The rebuilt file above is unchanged and still yours.", + ); + setPhase("done"); + } + }; + + const cost = styled + ? `${styled.ops_charged} ${styled.ops_confirmed ? "" : "estimated "}${ + styled.ops_charged === 1 ? "operation" : "operations" + }` + : ""; + + return ( ++ A styled copy, if you want one +
++ The file above is plain on purpose. The fonts and spacing of your original could not be read + out of a damaged file, and this page will not guess at a design you had. SuperDocs can lay + the recovered headings, tables and paragraphs out with consistent styling instead. It is + told to change no words, only how they are set. What comes back is compared against what + went out, word for word, and thrown away if the wording moved at all — a recovered document + that reads well but says something you did not write is worse than a plain one. The plain + file above is untouched whatever happens. +
+ + {phase === "idle" ? ( + <> + ++ This sends the recovered text to SuperDocs. If you would rather it stayed on this + machine, the file above is already yours and nothing more needs to happen. +
+ + ) : null} + + {phase !== "idle" ? ( +-
+ {stages.map((s, i) => (
+
- + + {s.message} + + ))} +
+ Still working. A long document can take a few minutes, and a quiet wait is + normal. + +
+ ) : null} + ++ {phase === "working" + ? (stages[stages.length - 1]?.message ?? "Working.") + : phase === "done" + ? (problem ?? styled?.notes[styled.notes.length - 1] ?? "") + : ""} +
+ + {phase === "done" && styled?.ok && styled.download ? ( +
+
+
+ ) : null}
+
+ {phase === "done" && !styled?.ok ? (
+
+
+ Download the styled file
+
+
+ + Saved as {styled.filename}. It carries the same recovered content as the file + above, laid out with consistent styling — it recovers nothing extra. That cost{" "} + {cost}. The plain file above is untouched and still yours. + {styled.warnings > 0 ? ( + <> + {" "} + The export reported {styled.warnings} non-fatal{" "} + {styled.warnings === 1 ? "warning" : "warnings"}, so compare it against the plain + file before you rely on it. + + ) : null} +
++ {styled?.rejected_for_content ? "Thrown away. " : "No styled copy. "} + {problem ?? styled?.notes[styled.notes.length - 1] ?? ""} +
+ ) : null} +Quarterly Report
\nRevenue rose in Q3 — driven by renewals & upsell.
\nRegional breakdown
\n| Region | Revenue |
| EMEA | 1.2M |
| APAC | 0.8M |
Prepared by the finance team.
", + "download": "/api/download/bad-characters-token", + "style": "/api/style/bad-characters-token" + } +} diff --git a/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/empty-body.json b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/empty-body.json new file mode 100644 index 00000000..65022e7f --- /dev/null +++ b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/empty-body.json @@ -0,0 +1,48 @@ +{ + "name": "empty-body", + "filename": "07-empty-body.docx", + "events": [ + { + "stage": "open", + "message": "Opening the file…" + }, + { + "stage": "open", + "message": "The container opened cleanly." + }, + { + "stage": "inventory", + "message": "Found 5 sections inside the document." + }, + { + "stage": "xml", + "message": "Checking the document body for damage…" + }, + { + "stage": "xml", + "message": "The document body was well-formed." + }, + { + "stage": "read", + "message": "Reading headings, paragraphs and tables…" + }, + { + "stage": "read", + "message": "No readable content was found in the document body." + } + ], + "report": { + "ok": false, + "summary": "This file could not be repaired. The document body contained no readable text. Nothing was invented to fill the gap — if there is another copy, even an older one, that is the better starting point.", + "recovered": [], + "lost": [ + "the document body contained no readable text" + ], + "counts": {}, + "structure_preserved": true, + "filename": "07-empty-body-repaired.docx", + "preview_html": "", + "download": null, + "style": null + } +} diff --git a/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/healthy.json b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/healthy.json new file mode 100644 index 00000000..5262eb14 --- /dev/null +++ b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/healthy.json @@ -0,0 +1,61 @@ +{ + "name": "healthy", + "filename": "00-healthy.docx", + "events": [ + { + "stage": "open", + "message": "Opening the file…" + }, + { + "stage": "open", + "message": "The container opened cleanly." + }, + { + "stage": "inventory", + "message": "Found 5 sections inside the document." + }, + { + "stage": "xml", + "message": "Checking the document body for damage…" + }, + { + "stage": "xml", + "message": "The document body was well-formed." + }, + { + "stage": "read", + "message": "Reading headings, paragraphs and tables…" + }, + { + "stage": "read", + "message": "Recovered 2 headings, 2 paragraphs and 1 table." + }, + { + "stage": "write", + "message": "Rebuilding a clean Word file…" + }, + { + "stage": "done", + "message": "Done. The rebuilt file is ready to download." + } + ], + "report": { + "ok": true, + "summary": "Recovered what could be read and rebuilt it as a valid Word file. This is a best-effort recovery, not a complete repair.", + "recovered": [ + "kept 2 headings, 2 paragraphs and 1 table, with their structure intact" + ], + "lost": [], + "counts": { + "headings": 2, + "paragraphs": 2, + "tables": 1, + "pictures": 0 + }, + "structure_preserved": true, + "filename": "00-healthy-repaired.docx", + "preview_html": "Quarterly Report
\nRevenue rose in Q3 — driven by renewals & upsell.
\nRegional breakdown
\n| Region | Revenue |
| EMEA | 1.2M |
| APAC | 0.8M |
Prepared by the finance team.
", + "download": "/api/download/healthy-token", + "style": "/api/style/healthy-token" + } +} diff --git a/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/illustrated.json b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/illustrated.json new file mode 100644 index 00000000..1dc1984b --- /dev/null +++ b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/illustrated.json @@ -0,0 +1,79 @@ +{ + "name": "illustrated", + "filename": "08-illustrated.docx", + "events": [ + { + "stage": "open", + "message": "Opening the file…" + }, + { + "stage": "open", + "message": "The container opened cleanly." + }, + { + "stage": "inventory", + "message": "Found 9 sections inside the document." + }, + { + "stage": "xml", + "message": "Checking the document body for damage…" + }, + { + "stage": "xml", + "message": "The document body was well-formed." + }, + { + "stage": "read", + "message": "Reading headings, paragraphs and tables…" + }, + { + "stage": "read", + "message": "Recovering the footnotes…" + }, + { + "stage": "read", + "message": "Recovering the page header…" + }, + { + "stage": "read", + "message": "Recovering the page footer…" + }, + { + "stage": "read", + "message": "Recovered 4 headings, 5 paragraphs and 1 picture." + }, + { + "stage": "write", + "message": "Rebuilding a clean Word file…" + }, + { + "stage": "done", + "message": "Done. The rebuilt file is ready to download." + } + ], + "report": { + "ok": true, + "summary": "Recovered what could be read and rebuilt it as a valid Word file. This is a best-effort recovery, not a complete repair.", + "recovered": [ + "kept 4 headings, 5 paragraphs and 1 picture, with their structure intact", + "carried 1 picture back into the document, where it was", + "recovered the footnotes", + "recovered the page header", + "recovered the page footer" + ], + "lost": [ + "footnotes, headers and footers could not be put back into their original places, so their text is set down at the end of the document under its own heading" + ], + "counts": { + "headings": 4, + "paragraphs": 5, + "tables": 0, + "pictures": 1 + }, + "structure_preserved": true, + "filename": "08-illustrated-repaired.docx", + "preview_html": "Site inspection
\nThe east elevation, photographed on arrival:
\nNo further defects were observed.
\nFootnotes, recovered separately
\nMeasurements taken with a laser rangefinder.
\nPage header, recovered separately
\nInspection report — draft
\nPage footer, recovered separately
\nPage 1 of 1
", + "download": "/api/download/illustrated-token", + "style": "/api/style/illustrated-token" + } +} diff --git a/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/index.json b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/index.json new file mode 100644 index 00000000..c3357209 --- /dev/null +++ b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/index.json @@ -0,0 +1,52 @@ +[ + { + "name": "healthy", + "filename": "00-healthy.docx", + "ok": true + }, + { + "name": "truncated", + "filename": "01-truncated-download.docx", + "ok": true + }, + { + "name": "missing-content-types", + "filename": "02-missing-content-types.docx", + "ok": true + }, + { + "name": "unclosed-tags", + "filename": "03-unclosed-tags.docx", + "ok": true + }, + { + "name": "bad-characters", + "filename": "04-bad-characters.docx", + "ok": true + }, + { + "name": "missing-document-part", + "filename": "05-missing-document-part.docx", + "ok": false + }, + { + "name": "not-a-word-file", + "filename": "06-not-a-word-file.docx", + "ok": false + }, + { + "name": "empty-body", + "filename": "07-empty-body.docx", + "ok": false + }, + { + "name": "illustrated", + "filename": "08-illustrated.docx", + "ok": true + }, + { + "name": "truncated-illustrated", + "filename": "09-truncated-illustrated.docx", + "ok": true + } +] diff --git a/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/missing-content-types.json b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/missing-content-types.json new file mode 100644 index 00000000..bf625fc9 --- /dev/null +++ b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/missing-content-types.json @@ -0,0 +1,66 @@ +{ + "name": "missing-content-types", + "filename": "02-missing-content-types.docx", + "events": [ + { + "stage": "open", + "message": "Opening the file…" + }, + { + "stage": "open", + "message": "The container opened cleanly." + }, + { + "stage": "inventory", + "message": "Found 4 sections inside the document." + }, + { + "stage": "inventory", + "message": "Rebuilding 1 missing structural part…" + }, + { + "stage": "xml", + "message": "Checking the document body for damage…" + }, + { + "stage": "xml", + "message": "The document body was well-formed." + }, + { + "stage": "read", + "message": "Reading headings, paragraphs and tables…" + }, + { + "stage": "read", + "message": "Recovered 2 headings, 2 paragraphs and 1 table." + }, + { + "stage": "write", + "message": "Rebuilding a clean Word file…" + }, + { + "stage": "done", + "message": "Done. The rebuilt file is ready to download." + } + ], + "report": { + "ok": true, + "summary": "Recovered what could be read and rebuilt it as a valid Word file. This is a best-effort recovery, not a complete repair.", + "recovered": [ + "rebuilt the file's internal structure, which was missing or damaged — this is standard plumbing and carries none of your content", + "kept 2 headings, 2 paragraphs and 1 table, with their structure intact" + ], + "lost": [], + "counts": { + "headings": 2, + "paragraphs": 2, + "tables": 1, + "pictures": 0 + }, + "structure_preserved": true, + "filename": "02-missing-content-types-repaired.docx", + "preview_html": "Quarterly Report
\nRevenue rose in Q3 — driven by renewals & upsell.
\nRegional breakdown
\n| Region | Revenue |
| EMEA | 1.2M |
| APAC | 0.8M |
Prepared by the finance team.
", + "download": "/api/download/missing-content-types-token", + "style": "/api/style/missing-content-types-token" + } +} diff --git a/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/missing-document-part.json b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/missing-document-part.json new file mode 100644 index 00000000..43bd823f --- /dev/null +++ b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/missing-document-part.json @@ -0,0 +1,36 @@ +{ + "name": "missing-document-part", + "filename": "05-missing-document-part.docx", + "events": [ + { + "stage": "open", + "message": "Opening the file…" + }, + { + "stage": "open", + "message": "The container opened cleanly." + }, + { + "stage": "inventory", + "message": "Found 4 sections inside the document." + }, + { + "stage": "inventory", + "message": "The main document part is missing and cannot be rebuilt." + } + ], + "report": { + "ok": false, + "summary": "This file could not be repaired. The main document part is missing entirely, so there is no text to recover. Nothing was invented to fill the gap — if there is another copy, even an older one, that is the better starting point.", + "recovered": [], + "lost": [ + "the main document part is missing entirely, so there is no text to recover" + ], + "counts": {}, + "structure_preserved": true, + "filename": "05-missing-document-part-repaired.docx", + "preview_html": "", + "download": null, + "style": null + } +} diff --git a/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/not-a-word-file.json b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/not-a-word-file.json new file mode 100644 index 00000000..6269c72b --- /dev/null +++ b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/not-a-word-file.json @@ -0,0 +1,32 @@ +{ + "name": "not-a-word-file", + "filename": "06-not-a-word-file.docx", + "events": [ + { + "stage": "open", + "message": "Opening the file…" + }, + { + "stage": "open", + "message": "The file's internal index was damaged — this is what Word reports as a corrupt document — so the content was read directly from inside it." + }, + { + "stage": "open", + "message": "No readable parts were found inside the file." + } + ], + "report": { + "ok": false, + "summary": "This file could not be repaired. No readable parts could be found inside the file. Nothing was invented to fill the gap — if there is another copy, even an older one, that is the better starting point.", + "recovered": [], + "lost": [ + "no readable parts could be found inside the file" + ], + "counts": {}, + "structure_preserved": true, + "filename": "06-not-a-word-file-repaired.docx", + "preview_html": "", + "download": null, + "style": null + } +} diff --git a/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/truncated-illustrated.json b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/truncated-illustrated.json new file mode 100644 index 00000000..29023275 --- /dev/null +++ b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/truncated-illustrated.json @@ -0,0 +1,84 @@ +{ + "name": "truncated-illustrated", + "filename": "09-truncated-illustrated.docx", + "events": [ + { + "stage": "open", + "message": "Opening the file…" + }, + { + "stage": "open", + "message": "The file's internal index was damaged — this is what Word reports as a corrupt document — so the content was read directly from inside it." + }, + { + "stage": "open", + "message": "Found and read 9 sections of the file this way." + }, + { + "stage": "inventory", + "message": "Found 9 sections inside the document." + }, + { + "stage": "xml", + "message": "Checking the document body for damage…" + }, + { + "stage": "xml", + "message": "The document body was well-formed." + }, + { + "stage": "read", + "message": "Reading headings, paragraphs and tables…" + }, + { + "stage": "read", + "message": "Recovering the footnotes…" + }, + { + "stage": "read", + "message": "Recovering the page header…" + }, + { + "stage": "read", + "message": "Recovering the page footer…" + }, + { + "stage": "read", + "message": "Recovered 4 headings, 5 paragraphs and 1 picture." + }, + { + "stage": "write", + "message": "Rebuilding a clean Word file…" + }, + { + "stage": "done", + "message": "Done. The rebuilt file is ready to download." + } + ], + "report": { + "ok": true, + "summary": "Recovered what could be read and rebuilt it as a valid Word file. This is a best-effort recovery, not a complete repair.", + "recovered": [ + "read your content out of a file whose internal index was damaged — the damage Word refuses to open", + "kept 4 headings, 5 paragraphs and 1 picture, with their structure intact", + "carried 1 picture back into the document, where it was", + "recovered the footnotes", + "recovered the page header", + "recovered the page footer" + ], + "lost": [ + "footnotes, headers and footers could not be put back into their original places, so their text is set down at the end of the document under its own heading" + ], + "counts": { + "headings": 4, + "paragraphs": 5, + "tables": 0, + "pictures": 1 + }, + "structure_preserved": true, + "filename": "09-truncated-illustrated-repaired.docx", + "preview_html": "Site inspection
\nThe east elevation, photographed on arrival:
\nNo further defects were observed.
\nFootnotes, recovered separately
\nMeasurements taken with a laser rangefinder.
\nPage header, recovered separately
\nInspection report — draft
\nPage footer, recovered separately
\nPage 1 of 1
", + "download": "/api/download/truncated-illustrated-token", + "style": "/api/style/truncated-illustrated-token" + } +} diff --git a/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/truncated.json b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/truncated.json new file mode 100644 index 00000000..0f4597e1 --- /dev/null +++ b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/truncated.json @@ -0,0 +1,66 @@ +{ + "name": "truncated", + "filename": "01-truncated-download.docx", + "events": [ + { + "stage": "open", + "message": "Opening the file…" + }, + { + "stage": "open", + "message": "The file's internal index was damaged — this is what Word reports as a corrupt document — so the content was read directly from inside it." + }, + { + "stage": "open", + "message": "Found and read 4 sections of the file this way." + }, + { + "stage": "inventory", + "message": "Found 4 sections inside the document." + }, + { + "stage": "xml", + "message": "Checking the document body for damage…" + }, + { + "stage": "xml", + "message": "The document body was well-formed." + }, + { + "stage": "read", + "message": "Reading headings, paragraphs and tables…" + }, + { + "stage": "read", + "message": "Recovered 2 headings, 2 paragraphs and 1 table." + }, + { + "stage": "write", + "message": "Rebuilding a clean Word file…" + }, + { + "stage": "done", + "message": "Done. The rebuilt file is ready to download." + } + ], + "report": { + "ok": true, + "summary": "Recovered what could be read and rebuilt it as a valid Word file. This is a best-effort recovery, not a complete repair.", + "recovered": [ + "read your content out of a file whose internal index was damaged — the damage Word refuses to open", + "kept 2 headings, 2 paragraphs and 1 table, with their structure intact" + ], + "lost": [], + "counts": { + "headings": 2, + "paragraphs": 2, + "tables": 1, + "pictures": 0 + }, + "structure_preserved": true, + "filename": "01-truncated-download-repaired.docx", + "preview_html": "Quarterly Report
\nRevenue rose in Q3 — driven by renewals & upsell.
\nRegional breakdown
\n| Region | Revenue |
| EMEA | 1.2M |
| APAC | 0.8M |
Prepared by the finance team.
", + "download": "/api/download/truncated-token", + "style": "/api/style/truncated-token" + } +} diff --git a/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/unclosed-tags.json b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/unclosed-tags.json new file mode 100644 index 00000000..c569ee90 --- /dev/null +++ b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/fixtures/unclosed-tags.json @@ -0,0 +1,68 @@ +{ + "name": "unclosed-tags", + "filename": "03-unclosed-tags.docx", + "events": [ + { + "stage": "open", + "message": "Opening the file…" + }, + { + "stage": "open", + "message": "The container opened cleanly." + }, + { + "stage": "inventory", + "message": "Found 5 sections inside the document." + }, + { + "stage": "xml", + "message": "Checking the document body for damage…" + }, + { + "stage": "xml", + "message": "Closed 6 elements that the damage had left open." + }, + { + "stage": "read", + "message": "Reading headings, paragraphs and tables…" + }, + { + "stage": "read", + "message": "The document's structure was too damaged to read. Recovering the text on its own instead." + }, + { + "stage": "read", + "message": "Recovered 6 paragraphs." + }, + { + "stage": "write", + "message": "Rebuilding a clean Word file…" + }, + { + "stage": "done", + "message": "Done. The rebuilt file is ready to download." + } + ], + "report": { + "ok": true, + "summary": "Recovered what could be read and rebuilt it as a valid Word file. This is a best-effort recovery, not a complete repair. The document's structure was too damaged to read, so the text was extracted run by run — you are getting the words back, but the headings, tables and formatting are gone.", + "recovered": [ + "closed 6 elements that the damage had left open", + "recovered the text of 6 paragraphs" + ], + "lost": [ + "the document structure was unreadable, so headings, tables and formatting could not be preserved — only the text was recovered" + ], + "counts": { + "headings": 0, + "paragraphs": 6, + "tables": 0, + "pictures": 0 + }, + "structure_preserved": false, + "filename": "03-unclosed-tags-repaired.docx", + "preview_html": "Quarterly Report
\nRevenue rose in Q3 — driven by renewals & upsell.
\nRegional breakdown
\n<w:tblPr><w:tblStyle w:val=\"TableGrid\"/><w:tblW w:w=\"0\" w:type=\"auto\"/><w:tblBorders><w:top w:val=\"single\" w:sz=\"4\" w:color=\"BFBFBF\"/><w:left w:val=\"single\" w:sz=\"4\" w:color=\"BFBFBF\"/><w:bottom w:val=\"single\" w:sz=\"4\" w:color=\"BFBFBF\"/><w:right w:val=\"single\" w:sz=\"4\" w:color=\"BFBFBF\"/><w:insideH w:val=\"single\" w:sz=\"4\" w:color=\"BFBFBF\"/><w:insideV w:val=\"single\" w:sz=\"4\" w:color=\"BFBFBF\"/></w:tblBorders></w:tblPr><w:tr><w:tc><w:tcPr><w:tcW w:w=\"0\" w:type=\"auto\"/></w:tcPr><w:p><w:r><w:t xml:space=\"preserve\">Region
\n<w:tcPr><w:tcW w:w=\"0\" w:type=\"auto\"/></w:tcPr><w:p><w:r><w:t xml:space=\"preserve\">Revenue
\n<w:tc><w:tcPr><w:tcW w:w=\"0\" w:type=\"auto\"/></w:tcPr><w:p><w:r><w:t xml:space=\"preserve\">EMEA
", + "download": "/api/download/unclosed-tags-token", + "style": "/api/style/unclosed-tags-token" + } +} diff --git a/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/server.ts b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/server.ts new file mode 100644 index 00000000..65cb3b66 --- /dev/null +++ b/use-cases/Priyanshu2425/word-doc-repair/frontend/src/test/server.ts @@ -0,0 +1,125 @@ +/** + * The fake this page is tested against streams real repairs. + * + * Every line it sends was produced by the engine and recorded by + * tests/test_frontend_fixtures.py, which fails if the recording drifts. A page + * that tells somebody what happened to their document must be tested against + * what actually happens to documents. + */ +import { http, HttpResponse } from "msw"; +import { setupServer } from "msw/node"; + +import healthy from "./fixtures/healthy.json"; +import truncated from "./fixtures/truncated.json"; +import missingContentTypes from "./fixtures/missing-content-types.json"; +import unclosedTags from "./fixtures/unclosed-tags.json"; +import badCharacters from "./fixtures/bad-characters.json"; +import missingDocumentPart from "./fixtures/missing-document-part.json"; +import notAWordFile from "./fixtures/not-a-word-file.json"; +import emptyBody from "./fixtures/empty-body.json"; +import illustrated from "./fixtures/illustrated.json"; +import truncatedIllustrated from "./fixtures/truncated-illustrated.json"; + +export interface Capture { + name: string; + filename: string; + events: { stage: string; message: string }[]; + report: Record
+
+
+
+
+
+
+
diff --git a/use-cases/Priyanshu2425/word-doc-repair/manual-test/UI_FLOWS.html b/use-cases/Priyanshu2425/word-doc-repair/manual-test/UI_FLOWS.html
new file mode 100644
index 00000000..13e435e0
--- /dev/null
+++ b/use-cases/Priyanshu2425/word-doc-repair/manual-test/UI_FLOWS.html
@@ -0,0 +1,379 @@
+
+
+
+
+
+Salvage — Manual QA Plan
+Every check below was run on the date stamped here, against a live + server, not against the modules. Where a check could not be run, it says not run rather + than passed. Verdicts are transcribed from the actual output, which is why some of them are worded + awkwardly — that is what the machine said.
+ +Automated coverage at the time of this run: 63 offline Python tests, +76 with the web extra installed, 46 frontend tests. This page +covers what those cannot: whether the downloaded file opens, whether the wait is bearable, and +whether a person who is not an engineer understands what they were handed.
+ +A The engine, through the HTTP surface
+Each fixture in manual-test/fixtures/ posted to POST /api/repair
+and the streamed report read line by line.
+
+
+
+
+| # | What was done | Expected | Actual | Verdict |
|---|---|---|---|---|
| A1 | Post 00-healthy.docx |
+ Repairs, offers a download and a styling link, preview rendered | +9 stages · ok · 2 headings, 2 paragraphs, 1 table · preview 277 chars | PASS |
| A2 | Post 01-truncated-download.docx |
+ Reads past the damaged index, recovers the table intact | +10 stages · ok · 2 headings, 2 paragraphs, 1 table | PASS |
| A3 | Post 02-missing-content-types.docx |
+ Rebuilds the missing structural part, does not list it as lost content | +10 stages · ok · same counts as the healthy original | PASS |
| A4 | Post 03-unclosed-tags.docx |
+ Falls back to a run-by-run read and says the structure is gone | +10 stages · ok · 0 headings, 6 paragraphs, 0 tables — the fallback, reported | PASS |
| A5 | Post 04-bad-characters.docx |
+ Repairs the faults, keeps the content | +10 stages · ok · counts match the healthy original | PASS |
| A6 | Post 05-missing-document-part.docx |
+ Refuses. No download, no styling link, no “what came through” | +4 stages · not ok · download and style both null | PASS |
| A7 | Post 06-not-a-word-file.docx |
+ Refuses without mangling | 3 stages · not ok · both links null | PASS |
| A8 | Post 07-empty-body.docx |
+ A valid-but-empty file is a failure, not a quiet success | +7 stages · not ok · both links null | PASS |
| A9 | Post this README renamed fake.docx |
+ Refuses in plain words | +“This file could not be repaired. No readable parts could be found inside the file…” | PASS |
B The file that comes back
+
+
+
+
+
+| # | What was done | Expected | Actual | Verdict |
|---|---|---|---|---|
| B1 | Download the repaired file and reopen it as an archive | +Valid container, all required parts, body re-parses | +5 parts present, integrity check clean, word/document.xml parses | PASS |
| B2 | Check the response headers | +Word media type and an attachment filename | +…wordprocessingml.document · 01-truncated-download-repaired.docx | PASS |
| B3 | Click the download twice | +Both work — repeat downloads are the most ordinary thing a person does | +200 and 200, byte-identical | PASS |
| B4 | Request a token that was never issued | +404 saying the original was never changed | +404 · “…your original was never changed.” | PASS |
| B5 | Open the downloaded file in Word / Pages | +Opens without a repair prompt; headings and table are styled | +— | JUDGEMENT — needs a human with Word |
C Refusals at the door
+
+
+
+
+
+| # | What was done | Expected | Actual | Verdict |
|---|---|---|---|---|
| C1 | Post an empty file | 400, said plainly | 400 · “That file is empty.” | PASS |
| C2 | Post 22 MB | 413 before it is read | 413 · “That file is larger than 20 MB.” | PASS |
| C3 | Choose a .doc in the page |
+ Refused before anything is sent, with advice that is true | +Refused client-side; the copy now also says what to do when Word will not open it either | PASS |
| C4 | Force an internal error while reading | +No stack trace, no exception class name, no claim anything was saved | +Covered by test_no_engine_vocabulary_or_class_name_reaches_the_page… | PASS (automated) |
D The SuperDocs path — the four calls, live
+Run against the real API with a live key, not a fake. Contract: +upload → chat → approve → export, preceded by a balance read.
+
+
+
+
+
+| # | What was done | Expected | Actual | Verdict |
|---|---|---|---|---|
| D1 | GET /api/capabilities with no key set |
+ Styling off, and the page told why | +{"styling": false, "note": "Styling is switched off on this copy of the page…"} | PASS |
| D2 | Same with a key set | Styling on | {"styling": true, …} | PASS |
| D3 | POST /api/style/{token} with no key |
+ Refused plainly, not a crash | 409 · “…switched off on this copy of the page. The rebuilt file above is unchanged and still yours.” | PASS |
| D4 | Full styling run, live, on the truncated fixture | +Four calls in order, a styled file back, plain rebuild untouched | +27 s · stages streamed · “Approved 5 formatting change(s)” · styled file returned · plain download still 200 | PASS |
| D5 | Reopen the styled file | +A real, styled Word file | +17 parts including theme1.xml, styles.xml, fontTable.xml; body parses | PASS |
| D6 | Compare the styled words against the words sent | +Identical — a formatting pass changes no words | +drift = (0 added, 0 removed) | PASS |
| D7 | Read the balance before spending | +Read in advance, reported | allowance_known: true · remaining: 500, read before the first billable call | PASS |
| D8 | Cost reported to the user | +Never “0 operations” for a billable request; an unconfirmed number marked as an estimate | +ops_charged: 1 · ops_confirmed: false → the page reads “1 estimated operation” | PASS |
| D9 | Exhausted allowance | +Refused before anything is sent | +Covered by test_it_does_not_spend_an_allowance_it_has_already_been_told_is_gone; not reproducible live without burning 500 operations | PASS (automated) |
| D10 | Dead network, no job id, empty export, unexpected error | +Each degrades to the plain rebuild | +Covered by tests/test_styled_export.py, one test per failure | PASS (automated) |
+
+
+The defect this run found — and what was done about it
+The first live styling run came back with the wording rewritten: a four-line recovered + report gained three invented paragraphs, a subtotal row, a “Remarks & Disclaimers” section, a + signature block and a footer — none of it in the document that was sent. It opens cleanly and it + reads better than the plain rebuild, which is exactly why it is the worst output this product could + produce: its owner would not notice.
+Two changes, in this order. The instruction was tightened to forbid additions by name. Then a + guard was added that does not depend on the instruction being obeyed: the words that come back are + compared against the words that went out, and any difference at all throws the styled file away + with the reason said plainly. On the re-run the same document came back word for word identical — + but the instruction is the request and the guard is the promise, and only one of + them is a test.
+
+
+
+
+
+| # | What was done | Expected | Actual | Verdict |
|---|---|---|---|---|
| D11 | Feed the guard the rewritten file from the first live run | +Rejected | drift = (199 added, 0 removed) → thrown away | PASS |
| D12 | Feed the guard an unchanged rebuild | +Accepted — a guard that rejects everything is an off switch | drift = (0, 0) | PASS |
| D13 | A rewritten export, end to end through the page | +No styled download offered; the alert says Thrown away | +Covered at both layers: test_a_styled_file_that_was_rewritten_never_reaches_the_download and the page test | PASS (automated) |
E Judgement calls no test can make
+These need a person. They are listed so that “we did not check” is on the record +rather than implied.
+
+
+
+
+
+| # | The question | Why no test can answer it | Verdict |
|---|---|---|---|
| E1 | Does the repaired file open in Word without a repair prompt? | +Needs Word | NOT RUN |
| E2 | Does the styled file look styled to a person, not just to a parser? | +Needs eyes on a rendered page | NOT RUN |
| E3 | Is a 27-second wait bearable with the stage lines showing? | +Perception, not timing | NOT RUN |
| E4 | Does a non-technical person understand “Recovered in part”? | +Comprehension | NOT RUN |
| E5 | Does anyone read what did not come through, or only the stamp? | +Attention | NOT RUN |
| E6 | Is “Thrown away” frightening in the wrong way? | +Tone. It is meant to be reassuring — their file is safe — and it may not read that way | NOT RUN |
| E0 | Does the page load and behave in a real browser? | +The 46 frontend tests render the whole page and drive it, and every endpoint was exercised + over real HTTP — but no browser was driven end to end in this session. Listed rather than + implied. | NOT RUN |
| E7 | Would somebody send a confidential document to a third party after reading that button’s copy? | +Consent. The copy says what is sent; whether it is understood is the question | NOT RUN |
F How to run this plan again
+cd use-cases/Priyanshu2425/word-doc-repair +python3 -m venv .venv && .venv/bin/pip install -e ".[web,dev]" + +.venv/bin/python -m pytest # 76 with the web extra, 63 without +cd frontend && npm install && npm test # 46 + +# section A–C, with no key set: +PORT=8123 .venv/bin/python -m docrepair.web +curl -s -X POST -F "file=@manual-test/fixtures/01-truncated-download.docx" \ + http://127.0.0.1:8123/api/repair + +# section D, with a key: +SUPERDOCS_API_KEY=sk_... PORT=8123 .venv/bin/python -m docrepair.web +curl -s http://127.0.0.1:8123/api/capabilities +curl -s -N -X POST http://127.0.0.1:8123/api/style/<token>+
-
+
manual-test/index.htmlis the interactive nineteen-item checklist for the + page itself, with verdicts that persist across reloads and export as Markdown. This plan is the + record of a run; that one is the instrument.
+ UI_FLOWS.html, beside this file, is the same territory walked screen by screen.
+
+
+
+
+
+
+
+
diff --git a/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/00-healthy.docx b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/00-healthy.docx
new file mode 100644
index 00000000..7adb1afa
Binary files /dev/null and b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/00-healthy.docx differ
diff --git a/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/01-truncated-download.docx b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/01-truncated-download.docx
new file mode 100644
index 00000000..e87fb4ca
Binary files /dev/null and b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/01-truncated-download.docx differ
diff --git a/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/02-missing-content-types.docx b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/02-missing-content-types.docx
new file mode 100644
index 00000000..835f7639
Binary files /dev/null and b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/02-missing-content-types.docx differ
diff --git a/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/03-unclosed-tags.docx b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/03-unclosed-tags.docx
new file mode 100644
index 00000000..458c3c60
Binary files /dev/null and b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/03-unclosed-tags.docx differ
diff --git a/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/04-bad-characters.docx b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/04-bad-characters.docx
new file mode 100644
index 00000000..6105af71
Binary files /dev/null and b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/04-bad-characters.docx differ
diff --git a/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/05-missing-document-part-SHOULD-FAIL.docx b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/05-missing-document-part-SHOULD-FAIL.docx
new file mode 100644
index 00000000..b78798be
Binary files /dev/null and b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/05-missing-document-part-SHOULD-FAIL.docx differ
diff --git a/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/06-not-a-word-file-SHOULD-FAIL.docx b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/06-not-a-word-file-SHOULD-FAIL.docx
new file mode 100644
index 00000000..ec8f3afe
--- /dev/null
+++ b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/06-not-a-word-file-SHOULD-FAIL.docx
@@ -0,0 +1 @@
+This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.This was never a Word document.
\ No newline at end of file
diff --git a/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/07-empty-body-SHOULD-FAIL.docx b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/07-empty-body-SHOULD-FAIL.docx
new file mode 100644
index 00000000..5e2c8557
Binary files /dev/null and b/use-cases/Priyanshu2425/word-doc-repair/manual-test/fixtures/07-empty-body-SHOULD-FAIL.docx differ
diff --git a/use-cases/Priyanshu2425/word-doc-repair/manual-test/index.html b/use-cases/Priyanshu2425/word-doc-repair/manual-test/index.html
new file mode 100644
index 00000000..1c28f561
--- /dev/null
+++ b/use-cases/Priyanshu2425/word-doc-repair/manual-test/index.html
@@ -0,0 +1,779 @@
+
+
+
+
+
+Salvage — UI Flows
+Every path a person can take through the page, in the order they take it, with the
+ thing to check at each step. The screen sketches are transcribed from the component source and from
+ the engine's real output — every stage line, count, docket and message below was taken from an
+ actual run, not written to look plausible. What they are not is a screenshot: nobody
+ loaded this page in a browser as part of writing them, which is exactly why this document exists
+ as a walkthrough for a person to do. The API-level evidence is in
+ MANUAL_QA_PLAN.html beside this file.
1 Arrive
+Somebody whose only copy will not open lands here, probably frightened, probably from +a search. The first screen has to answer can you help me and will you make it worse +before it asks for anything.
+ +
+
+
+Step 1 · open the page
+In the first viewport, without scrolling: the wordmark, one sentence saying what + this is, the panel that takes the file, and the four custody promises beneath it.
+ Salvage. document recovery
+ ┌─ ▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨ ─┐
+ Your Word file will not open.
+ Hand it over and this page will read whatever is
+ still intact inside it, rebuild what it can, and
+ tell you plainly what it could not.
+
+ ┌──────────────────────────────────┐
+ │ Choose the damaged file │
+ │ or drag it onto this panel │
+ │ Word .docx · up to 20 MB │
+ └──────────────────────────────────┘
+
+ ✓ Your original is never changed.
+ ✓ Your file is not kept.
+ ✓ No account, and nothing to install.
+ ✓ It is a best-effort recovery.
+ └─ ▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨ ─┘
+ Check. No hero, no feature cards, no pricing. The fourth promise says + best-effort before anything is uploaded, not after.
+
+
+
+Step 1a · hand it something it will not take
+A .doc, a 25 MB file, or an empty one. Refused before anything is
+ sent, under the heading That file was not taken.
Check. The .doc message tells you to re-save it in Word
+ and says what to do if Word will not open it either — which is the situation you are
+ actually in. Advice that assumes your Word works is advice for somebody else.
2 Watch it work
+The stages are streamed from the engine as they happen. The one thing this screen may +never do is animate a bar over work that already finished.
+ +
+
+
+Step 2 · the file is taken
+The upload panel is replaced by a record line and a list of stations that grows one + line at a time.
+ Reading your document
+ file 01-truncated-download.docx size 4 KB docket SLV-71981
+
+ ● Opening the file…
+ ● The file's internal index was damaged…
+ ● Found 4 sections inside the document.
+ ● Checking the document body for damage…
+ ○ Reading headings, paragraphs and tables…
+
+ Working ▓▓▓▓▓▓▓░░░░░░░░
+ Check. Lines appear one after another, not all at once at the end. The + record line carries a docket — a receipt, so the page has a name for what it is holding.
+Check. A screen reader hears the latest stage: there is a polite live region + carrying it.
+3 Read the verdict
+Three outcomes, and they must not look alike. The stamp lands once; the working folds +away behind a disclosure, because the answer outranks the working.
+ +
+
+
+
+
+| Outcome | Stamp | What is on screen | Try it with |
|---|---|---|---|
| Everything read | Recovered | +What came through · the sheet · download · the styling offer | +00-healthy.docx, and also 01-truncated-download.docx — a badly
+ damaged container whose content came back whole, which is the point of the build |
| Read, with losses | Recovered in part | +Both lists, set at the same weight · the sheet · download · the styling offer | +03-unclosed-tags.docx — the run-by-run fallback, which loses the structure and says so |
| Could not be read | Could not be repaired | +What went wrong. No “what came through”, no sheet, no download, + no styling offer | +05-missing-document-part.docx |
+
+
+Step 3 · the report
+ Your document, as far as it could be read
+ file 01-truncated-download.docx size 4 KB docket SLV-71981
+
+ ╭──────────────────────╮
+ │ RECOVERED │ ← lands once, small rotation
+ ╰──────────────────────╯
+
+ Recovered what could be read and rebuilt it as a valid
+ Word file. This is a best-effort recovery, not a complete
+ repair.
+
+ What came through
+ ✓ read your content out of a file whose internal index
+ was damaged — the damage Word refuses to open
+ ✓ kept 2 headings, 2 paragraphs and 1 table, with their
+ structure intact
+
+ (no "what did not come through" section: on this file
+ there were no losses, and a heading with nothing under
+ it is a claim)
+
+ ┌ the rebuilt document, rendered for reading ──────────┐
+ │ Quarterly Report │
+ │ Revenue rose in Q3 — driven by renewals & upsell. │
+ │ Regional breakdown │
+ │ ┌────────┬──────────┐ │
+ │ │ Region │ Revenue │ … │
+ └──────────────────────────────────────────────────────┘
+
+ ┌─ ▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨ ─┐
+ [ Download the repaired file ]
+ Saved as …-repaired.docx. You can download it more than
+ once. This page holds it for about thirty minutes…
+ └─ ▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨ ─┘
+
+ ▸ What it did, step by step (10)
+ Check. On a file that did lose something — try
+ 03-unclosed-tags.docx — losses are set at the same weight as recoveries. Styling
+ losses as a footnote would be the overclaim this build refuses, expressed in CSS.
Check. The rebuilt document is on the page, above the download. + “Was any of this worth it” is a question people ask before they act, not after.
+Check. The stage log is behind a disclosure, still complete, still readable.
+
+
+
+Step 3a · the total failure
+Stamp reads Could not be repaired. There is no “what came through” heading at + all, no preview, and no download button.
+Check. This was a real defect once (BUG-012): a failure that still rendered + the heading. A heading with nothing under it is a claim.
+4 The styled copy — the SuperDocs path
+The card this build answers is banded API + export. This is where those four +calls live, and the whole design question is how to offer a second, better-looking file without ever +putting the first one at risk.
+ +
+
+
+Step 4 · the offer, below the download and never above it
+ ─────────────────────────────────────────────────────
+ A styled copy, if you want one
+
+ The file above is plain on purpose. The fonts and spacing
+ of your original could not be read out of a damaged file,
+ and this page will not guess at a design you had.
+ SuperDocs can lay the recovered headings, tables and
+ paragraphs out with consistent styling instead. It is told
+ to change no words, only how they are set. What comes back
+ is compared against what went out, word for word, and
+ thrown away if the wording moved at all…
+
+ [ Send it for styling ]
+
+ This sends the recovered text to SuperDocs. If you would
+ rather it stayed on this machine, the file above is
+ already yours and nothing more needs to happen.
+ Check. Nothing has been sent yet. Somebody whose document just broke should + not have it handed to a third party because a page decided that for them.
+Check. The panel carries no chevron tape. Tape means in our custody, + and there is only one custody.
+
+
+
+Step 4a · with no key configured
+No button at all — one quiet line: “Styling is switched off on this copy of the + page, so the rebuilt file is the plain one. Nothing else is affected.”
+Check. The page asks GET /api/capabilities before it offers
+ anything. A step this copy cannot take is never rendered as a button that fails when pressed — and
+ the sentence says what is not affected, because a person reading a missing feature needs to
+ know their file is not the thing that went wrong.
+
+
+Step 4b · press it and wait
+ ● Sending the recovered content to SuperDocs for styling…
+ ○ Waiting for SuperDocs to finish — large documents can
+ take minutes.
+
+ Still working. A long document can take a few minutes,
+ and a quiet wait is normal. ▓▓▓▓▓▓░░░░░░░░
+ Check. Trap 2 from the docs, answered in the interface: a long silence is + still processing. Measured live at 27 seconds on a four-paragraph document. A page that does not + say this turns a slow success into a suspected crash.
+
+
+
+Step 4c · it worked
+ ● Sending the recovered content to SuperDocs for styling…
+ ● Waiting for SuperDocs to finish…
+ ● Approved 5 formatting change(s).
+ ● SuperDocs returned a styled file.
+
+ ┌─ ▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨ ─┐
+ [ Download the styled file ]
+ Saved as …-repaired-styled.docx. It carries the same
+ recovered content as the file above, laid out with
+ consistent styling — it recovers nothing extra. That
+ cost 1 estimated operation. The plain file above is
+ untouched and still yours.
+ └─ ▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨▨ ─┘
+ Check. Two download buttons are now on the page. The styled copy is + an addition; it never replaces the file the person already had.
+Check. “it recovers nothing extra” — a styled file looks better, and looking + better is easy to mistake for having recovered more.
+Check. The cost is stated, and an unconfirmed number says estimated. + The async endpoints return no usage block, so a zero would mean “not reported”, not “free”.
+
+
+
+Step 4d · it came back rewritten
+ Thrown away. The styled version came back with the wording
+ changed, so it was thrown away rather than handed over.
+ Your document should say what you wrote. The rebuilt file
+ is unchanged and still yours.
+ Check. No styled download is offered. The plain one is still there.
+Why this exists. On the first live run the styled file came back with three + invented paragraphs, a subtotal row, a disclaimer and a signature block. It opened cleanly and read + better than the plain rebuild — which is exactly why it is the worst thing this product could hand + somebody. The wording is Thrown away, not Failed, because nothing failed: a claim was + refused.
+
+
+
+Step 4e · the other ways it can end
+Each ends with the plain file still on the page and one sentence saying why.
+ No styled copy. There is no styling allowance left this
+ month, so nothing was sent and nothing was spent. The
+ rebuilt file is unchanged and still yours.
+
+ No styled copy. Styling did not work. The rebuilt file
+ above is unchanged and still yours.
+
+ No styled copy. The connection dropped. The rebuilt file
+ above is unchanged and still yours.
+ Check. The exhausted-allowance case says nothing was spent. The + balance is read before the first billable call, so this is a refusal to start rather than a failure + halfway through.
+Check. No exception class name, no ZIP, no XML
+ anywhere. Guarded over rendered output for every recorded repair — BUG-014 was fixed in the engine
+ and came straight back as BUG-020 in the page.
5 Leave, and come back
+
+
+Step 5 · repair another document
+The button at the bottom returns the page to its first screen, cleared.
+Check. The file input is genuinely reset — choosing the same file again + starts a new run rather than doing nothing.
+
+
+
+Step 5a · come back to a stale link
+Downloads are held about thirty minutes. After that: + “That repaired file is no longer being held. Repair the document again to get a fresh copy — + your original was never changed.”
+Check. The reassurance is in the error, where it is needed, not only on the + first screen where it has been forgotten.
+6 Cross-cutting
+
+
+
+
+
+
+
+| What | How to check it | Standing |
|---|---|---|
| Keyboard only | Tab through: choose file → download → send for styling → styled download → repair another | Every control is reachable and shows focus |
| Screen reader | The live region announces the current stage while working and the verdict when done | Automated axe pass, idle and reporting, no serious or critical violations |
| 400 px wide | One column throughout; the verdict and the download reachable without a horizontal thought | Designed mobile-first |
| Dark mode | The same notice under a desk lamp | Palette defined for both |
| Reduced motion | The working bar stops animating | prefers-reduced-motion honoured |
| No Node installed | The bundle is committed; a hash guard fails the build if it falls behind its source | bundle-manifest.json |
+
+
+
+
+
+
diff --git a/use-cases/Priyanshu2425/word-doc-repair/manual-test/make_fixtures.py b/use-cases/Priyanshu2425/word-doc-repair/manual-test/make_fixtures.py
new file mode 100644
index 00000000..a95076be
--- /dev/null
+++ b/use-cases/Priyanshu2425/word-doc-repair/manual-test/make_fixtures.py
@@ -0,0 +1,46 @@
+"""Dump the test-suite's broken documents to disk for hands-on testing.
+
+The fixtures are the *same* ones the automated suite uses — `tests/broken.py`
+is the single source of truth, so a file a human tests by hand is byte-for-byte
+the file pytest tests. Run from the build root:
+
+ python3 manual-test/make_fixtures.py
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+from tests import broken # noqa: E402
+
+OUT = Path(__file__).resolve().parent / "fixtures"
+
+# (filename, generator). The names are what a tester reads in a download
+# folder, so they say what the file is for, not what function made it.
+FIXTURES = [
+ ("00-healthy.docx", broken.healthy),
+ ("01-truncated-download.docx", broken.truncated_container),
+ ("02-missing-content-types.docx", broken.missing_content_types),
+ ("03-unclosed-tags.docx", broken.unclosed_tags),
+ ("04-bad-characters.docx", broken.bare_ampersand_and_control_chars),
+ ("05-missing-document-part-SHOULD-FAIL.docx", broken.missing_document_part),
+ ("06-not-a-word-file-SHOULD-FAIL.docx", broken.not_a_zip_at_all),
+ ("07-empty-body-SHOULD-FAIL.docx", broken.empty_body),
+]
+
+
+def main() -> int:
+ OUT.mkdir(parents=True, exist_ok=True)
+ for name, make in FIXTURES:
+ data = make()
+ (OUT / name).write_bytes(data)
+ print(f"{name:46} {len(data):>7,} bytes")
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/use-cases/Priyanshu2425/word-doc-repair/pyproject.toml b/use-cases/Priyanshu2425/word-doc-repair/pyproject.toml
new file mode 100644
index 00000000..9bdbafbe
--- /dev/null
+++ b/use-cases/Priyanshu2425/word-doc-repair/pyproject.toml
@@ -0,0 +1,27 @@
+[project]
+name = "word-doc-repair"
+version = "1.0.0"
+description = "Best-effort recovery for a Word document that will not open."
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+web = ["fastapi", "uvicorn", "python-multipart"]
+# `httpx2` is what `starlette.testclient` drives the app with. It is listed
+# because leaving it out did not skip the endpoint tests -- it interrupted
+# collection, so `pip install -e ".[web,dev]" && pytest` ran *no* tests at all
+# for anybody following the README. See BUG-057.
+dev = ["pytest", "httpx2"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["backend"]
+include = ["docrepair*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["backend"]
+addopts = "-q"
diff --git a/use-cases/Priyanshu2425/word-doc-repair/screenshot.png b/use-cases/Priyanshu2425/word-doc-repair/screenshot.png
new file mode 100644
index 00000000..748ad8ca
Binary files /dev/null and b/use-cases/Priyanshu2425/word-doc-repair/screenshot.png differ
diff --git a/use-cases/Priyanshu2425/word-doc-repair/tests/__init__.py b/use-cases/Priyanshu2425/word-doc-repair/tests/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/use-cases/Priyanshu2425/word-doc-repair/tests/broken.py b/use-cases/Priyanshu2425/word-doc-repair/tests/broken.py
new file mode 100644
index 00000000..9ce81742
--- /dev/null
+++ b/use-cases/Priyanshu2425/word-doc-repair/tests/broken.py
@@ -0,0 +1,160 @@
+"""Deliberately messy DOCX files — the reviewer's stated test.
+
+Each function breaks a *healthy* document in one recognisable way, so a test
+failure names the fault it was meant to survive.
+"""
+
+from __future__ import annotations
+
+import io
+import zipfile
+
+from docrepair import docx
+
+
+def healthy() -> bytes:
+ return docx.write_docx([
+ docx.Block("heading", "Quarterly Report", 1),
+ docx.Block("paragraph", "Revenue rose in Q3 — driven by renewals & upsell."),
+ docx.Block("heading", "Regional breakdown", 2),
+ docx.Block("table", rows=[["Region", "Revenue"], ["EMEA", "1.2M"], ["APAC", "0.8M"]]),
+ docx.Block("paragraph", "Prepared by the finance team."),
+ ])
+
+
+def _rewrite(data: bytes, changes: dict[str, bytes | None]) -> bytes:
+ """Rebuild the archive with parts replaced (or dropped when value is None)."""
+ buf = io.BytesIO()
+ with zipfile.ZipFile(io.BytesIO(data)) as src, \
+ zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as dst:
+ for name in src.namelist():
+ if name in changes:
+ if changes[name] is None:
+ continue
+ dst.writestr(name, changes[name])
+ else:
+ dst.writestr(name, src.read(name))
+ for name, val in changes.items():
+ if val is not None and name not in src.namelist():
+ dst.writestr(name, val)
+ return buf.getvalue()
+
+
+def truncated_container() -> bytes:
+ """A cut-off download. The central directory lives at the end of a ZIP, so
+ this is the classic "Word says the file is corrupt" case."""
+ data = healthy()
+ return data[: int(len(data) * 0.6)]
+
+
+def missing_content_types() -> bytes:
+ return _rewrite(healthy(), {"[Content_Types].xml": None})
+
+
+def unclosed_tags() -> bytes:
+ """document.xml cut mid-element."""
+ with zipfile.ZipFile(io.BytesIO(healthy())) as z:
+ body = z.read("word/document.xml")
+ return _rewrite(healthy(), {"word/document.xml": body[: int(len(body) * 0.7)]})
+
+
+def bare_ampersand_and_control_chars() -> bytes:
+ with zipfile.ZipFile(io.BytesIO(healthy())) as z:
+ body = z.read("word/document.xml")
+ broken = body.replace(b"renewals & upsell", b"renewals & upsell\x07\x00")
+ return _rewrite(healthy(), {"word/document.xml": broken})
+
+
+def missing_document_part() -> bytes:
+ return _rewrite(healthy(), {"word/document.xml": None})
+
+
+def not_a_zip_at_all() -> bytes:
+ return b"This was never a Word document." * 40
+
+
+def empty_body() -> bytes:
+ body = (b'Manual test · Repair my broken Word doc
+Fifteen minutes with a browser, a Word-ish app, and eight deliberately broken + files. The automated suite already proves the engine does the right thing — this sheet is for + the things only a person can judge: whether the page communicates, whether the file it hands + back actually opens, and whether the copy is honest.
+ + +Your browser is blocking local storage, so your
+ answers will not survive a reload. Copy the Markdown before you close the tab.
+
+
+
+
+
+
+
+
+
+ Before you start
+From the build root
+ (builds/use-cases/word-doc-repair/), in a terminal:
pip install -e ".[web]"
+PORT=8077 python3 -m docrepair.webThen open http://127.0.0.1:8077 + and keep this sheet open in a second tab.
+Why 8077 and not 8000: the default is
+ python3 -m docrepair.web on port 8000, but port 8000 is already taken on this
+ machine — so pass PORT. If 8077 is busy too, pick anything free and adjust the
+ URL. If the page does not load, check the terminal: uvicorn prints the address
+ it actually bound to.
You will also need Microsoft Word, Apple Pages, LibreOffice or + Google Docs to open the repaired files — checking that the download opens is half of this + test, and no automated test can do it.
+The eight test files are in
+ manual-test/fixtures/, generated by
+ python3 manual-test/make_fixtures.py from tests/broken.py — the
+ same generators the pytest suite uses, so what you test by hand is byte-for-byte what CI
+ tests. If a download link below 404s, run that script. If your browser opens a fixture
+ instead of saving it, right-click the link and choose Save Link As.
Your answers save automatically to this browser and survive a + reload. When you are done, hit Copy results as Markdown and paste the result back.
+
+
+
+
+ The eight files
+Work top to bottom. Each expected result below was read out of
+ backend/docrepair/engine.py and confirmed against a real run, so the wording quoted is
+ the wording the page should show — near enough, not to the letter.
+
+
+
+
+ 00
+ The healthy control
should succeed +The file
+ + 00-healthy.docx 2.0 KB +What is wrong with it
+Nothing — this is an intact Word file, and it is here so you can tell a real failure + apart from a fixture that was broken on purpose.
+What to do
+-
+
- Download it, then drop it on the page. +
- Download the repaired file and open it in Word / Pages / Google Docs. +
What should happen
+-
+
- Stages, in order: Opening the file… → The container opened cleanly. → + Found 5 sections inside the document. → Checking the document body for + damage… → The document body was well-formed. → Reading headings, + paragraphs and tables… → Recovered 2 headings, 2 paragraphs and 1 table. → + Rebuilding a clean Word file… → Done. +
- Verdict heading “Your file is ready”. Counts row shows + 2 headings, 2 paragraphs, 1 table. +
- Summary still says “best-effort recovery, not a complete repair” — it does not + upgrade its language just because the file was fine. That is deliberate; judge whether + it reads as over-cautious. +
- “What came through”: one line, “Kept 2 headings, 2 paragraphs and 1 table, with + their structure intact.” “What did not” must not appear at all. +
- The downloaded file is named
00-healthy-repaired.docx, opens without a + repair prompt, and contains: Quarterly Report as a heading, Regional + breakdown as a heading, and a real 3-row × 2-column table + (Region/Revenue, EMEA/1.2M, APAC/0.8M) — a table you can click into, not text with + spaces.
+
+
+
+
+
+ 01
+ Truncated download
should succeed +The file
+ + 01-truncated-download.docx 1.2 KB +What is wrong with it
+The download was cut off at 60%, so the index Word needs to find anything is gone — this + is the classic “Word says the file is corrupt” case.
+What to do
+-
+
- Try opening it in Word first, so you have seen the failure this tool exists to + undo. Word should refuse it. +
- Drop it on the page. Download and open the result. +
What should happen
+-
+
- Second stage line reads “The file's internal index was damaged — this is what Word + reports as a corrupt document — so the content was read directly from inside it.” + then “Found and read 4 sections of the file this way.” +
- Succeeds. Counts: 2 headings, 2 paragraphs, 1 table — the same as the healthy + control, because the cut took the index, not the content. +
- “What came through” has two lines: the one about reading content out of a file + whose internal index was damaged, and the one about keeping the headings, paragraphs and + table with their structure intact. +
- “What did not” must not appear. The cut did destroy one of the file's internal + parts (the style sheet), but that part is regenerated and carries none of your writing — + listing it would tell you that you lost something you did not. +
- Nowhere in anything you can see should the words ZIP, XML,
+ central directory or a filename like
document.xml.relsappear.
+ - The downloaded file opens with headings as headings and the table as a table. +
+
+
+
+
+ 02
+ Missing content-types part
should succeed +The file
+ + 02-missing-content-types.docx 1.7 KB +What is wrong with it
+The internal manifest that tells Word what the pieces are has been deleted — the content + is all still there, but nothing can read it.
+What to do
+- Drop it on the page. Download and open the result.
What should happen
+-
+
- Opens cleanly (no “internal index was damaged” line here — the container itself is + fine). Inventory says “Found 4 sections inside the document.” then + “Rebuilding 1 missing structural part…” — singular, not “1 part(s)”. +
- Succeeds. Counts: 2 headings, 2 paragraphs, 1 table. +
- “What came through” leads with “Rebuilt the file's internal structure, which was + missing or damaged — this is standard plumbing and carries none of your content.” + The second half of that sentence is the point: judge whether it actually reassures you + rather than alarming you. +
- “What did not” must not appear. +
- Downloaded file opens with the heading and table structure intact. +
+
+
+
+
+ 03
+ Unclosed tags
should succeed — with a stated loss +The file
+ + 03-unclosed-tags.docx 1.9 KB +What is wrong with it
+The document body itself is chopped off mid-sentence, leaving tags hanging open.
+What to do
+-
+
- Drop it on the page. Read the summary paragraph slowly — this is the case where + the tool has to admit a real loss. +
- Download and open the result. +
What should happen
+This is the most important card on the sheet. It succeeds, but it succeeds + worse than the ones above, and the whole product rests on whether you can tell.
+-
+
- Stage line “Closed 7 elements that the damage had left open.” then + “The document's structure was too damaged to read. Recovering the text on its own + instead.” then “Recovered 6 paragraphs.” No exception name should appear — + it used to read “(ParseError)” here, which this sheet caught and is now + fixed and tested. +
- Verdict heading is still “Your file is ready”, but the summary must carry a + second sentence: +
- “The document's structure was too damaged to read, so the text was + extracted run by run — you are getting the words back, but the headings, tables and + formatting are gone.” +
- Counts row shows 0 headings, 6 paragraphs, 0 tables. Two of those numbers are + zero — check they do not read as a bug or a broken layout. +
- “What came through”: closed 7 elements… and recovered the text of 6 + paragraphs. “What did not” must appear here, saying headings, tables and + formatting could not be preserved. +
- The downloaded file opens and contains the words Quarterly Report, + Regional breakdown, EMEA, APAC — but as plain paragraphs. + No heading styles, no table. That is correct behaviour, not a failure: the test is + whether the page warned you before you opened it. +
- Judgement: would a non-technical person, seeing this screen, understand they + must not treat the result as their document back? Or does “Your file is ready” plus a + green tick swamp the warning? +
+
+
+
+
+ 04
+ Bare ampersand and control characters
should succeed +The file
+ + 04-bad-characters.docx 2.0 KB +What is wrong with it
+A raw & and two invisible control characters have got into the text —
+ one bad byte is enough to make a strict reader reject the whole document.
What to do
+-
+
- Drop it on the page. Download and open the result. +
- Find the line beginning “Revenue rose in Q3” and read it carefully. +
What should happen
+-
+
- Stages: “Removed 2 invalid characters that were breaking the document.” then + “Repaired 1 stray ampersand.” — note “1 stray ampersand”, singular. +
- Succeeds. Counts: 2 headings, 2 paragraphs, 1 table. Structure intact. +
- “What came through” has three lines (invalid characters, ampersand, kept structure). + “What did not” must not appear. +
- In the downloaded file, that sentence reads exactly
+ “Revenue rose in Q3 — driven by renewals & upsell.” — the ampersand is
+ still there as an ampersand. Losing it, or seeing
&printed + literally, is a fail.
+ - The control characters are gone with no visible box or question-mark glyph left + behind. +
+
+
+
+
+ 05
+ Missing document part
must fail honestly +The file
+ + 05-missing-document-part-SHOULD-FAIL.docx 1.4 KB +What is wrong with it
+The part that holds all the actual writing has been deleted — the wrapper survived, the + document did not.
+What to do
+- Drop it on the page and read the whole result screen.
What should happen
+-
+
- It must fail. Heading “This one could not be repaired”, in red. +
- Only four stage lines, stopping at + “The main document part is missing and cannot be rebuilt.” — the run halts there + rather than pretending to carry on. +
- Summary reads: “This file could not be repaired. The main document part is missing + entirely, so there is no text to recover. Nothing was invented to fill the gap — if + there is another copy, even an older one, that is the better starting point.” +
- No download button. If you can download anything here, that is a serious fail — + an empty file that opens fine is the worst possible outcome. +
- “What came through” should be absent. “What did not” has one line about the main + document part being missing. +
- No counts row, no zeros, no stack trace, no error code. +
- Judgement: the advice to go find an older copy is the only useful thing left to + say. Does it land as help, or as a brush-off? +
+
+
+
+
+ 06
+ Not a Word file at all
must fail honestly +The file
+ + 06-not-a-word-file-SHOULD-FAIL.docx 1.2 KB +What is wrong with it
+It is plain text with a .docx name stuck on it — the realistic case of
+ someone who saved, exported or renamed the wrong thing.
What to do
+- Drop it on the page. Read “What came through” especially closely.
What should happen
+-
+
- It must fail. “This one could not be repaired”, no download button. +
- Summary: “This file could not be repaired. No readable parts could be found inside + the file. Nothing was invented to fill the gap — …” +
- There must be no “What came through” section at all. Nothing came through — + the repair failed. Writing this sheet surfaced a real defect here: the failure screen + used to show “Read your content out of a file whose internal index was damaged” + on a screen that recovered nothing, which is exactly the overclaim this build says it + does not make. It is fixed, and a test now pins it. If that line is back, mark + this fail. +
- “What did not” should name the problem once. It previously said both + “No readable parts could be found inside the file” and “The file contained no + readable parts” — one problem stated twice reads as two. Also fixed and tested. +
- Nothing anywhere should mention the file not being a valid archive, or use the word + ZIP. +
+
+
+
+
+ 07
+ Empty body
must fail honestly +The file
+ + 07-empty-body-SHOULD-FAIL.docx 1.6 KB +What is wrong with it
+A structurally perfect Word file with nothing written in it — every part valid, the body + empty.
+What to do
+- Drop it on the page. This one is the trap: everything about it looks healthy.
What should happen
+-
+
- It must fail, even though nothing about the file is technically broken. An + empty valid document is the most dangerous output there is: it opens cleanly, so its + owner may not notice their content is gone for weeks. +
- The stages run further than the other two failures — through “The document body was + well-formed.” and “Reading headings, paragraphs and tables…” — before + “No readable content was found in the document body.” +
- Summary: “This file could not be repaired. The document body contained no readable + text. Nothing was invented to fill the gap — …” +
- No download button. A downloadable, valid, empty
.docxhere is the + single worst failure on this whole sheet.
+ - Judgement: the earlier stages all pass with ticks before it fails at the end. + Does that read as confusing — a run that looks like it is going well and then is not? +
+
+
+ Edge cases
+Things a real person does that the fixtures do not cover.
+
+
+
+ Download the same repaired file twice
+Repair 00-healthy.docx, click the download button, then click
+ it again (or press Back and re-download).
Expected: the file is held for exactly one download and then dropped, + so the second attempt fails. It should fail as a readable sentence — + “That file is no longer available. Please repair it again.” — not as a raw JSON blob, + a FastAPI error page or a browser 404. Note exactly what you saw; this is a plausible thing + for a worried person to do, and a raw error here undoes the whole tone of the product.
+
+
+
+ Drag and drop, not just the file picker
+Drag a fixture onto the drop zone from Finder / Explorer.
+Expected: the zone visibly highlights while the file is over it, and + the repair starts on drop. Then check the click path works too, and that + “Repair another file” returns you to a clean drop zone that accepts a second file + without a page reload.
+
+
+
+ A completely empty file
+Create one — touch empty.docx — and upload it.
Expected: the server rejects it with “That file is empty.” and + the page shows that sentence on the failure screen rather than a generic + “That file could not be read.” or a console error.
+
+
+
+
+ Refresh mid-repair, and repair something large-ish
+Reload the page while a repair is running; then try any real
+ .docx you have lying around (a CV, a report) to see the tool meet a document it
+ was not built against.
Expected: reloading leaves no stuck spinner and no error. A real + document either repairs with sensible counts, or fails with a sentence you can understand — + never a stack trace, and never a summary that mentions something you did not upload.
+
+
+
+ Judgement checks
+No test can make these calls. Answer them after you have run all eight files.
+
+
+
+ Does the downloaded file actually open?
+Open every repaired file you got (cases 00–04) in at least two of + Word, Pages, Google Docs, LibreOffice.
+Pass means: no “Word found unreadable content” prompt, no recovery + dialog. Headings are real heading styles (they show up in the navigation pane / outline, not + just bigger text), and the table is a real table you can click into a cell of — not + tab-separated text. Cases 00, 01, 02 and 04 must all clear this bar. Case 03 must not — it + told you the structure was gone.
+
+
+
+ Is the progress genuinely visible, or does it flash past?
+These files are tiny, so the whole repair takes milliseconds. Watch the + stage list closely on case 01.
+The question: can you actually read the stages as they land, or does + the result screen replace them before your eyes get there? Progress you cannot perceive is + the same as no progress — and worse, it makes the stage log look decorative. Does anything + remain visible afterwards to tell you what was done?
+
+
+
+ Does any wording overclaim?
+Read every screen you saw for anything that promises more than was + delivered: “fixed”, “restored”, “recovered your document”, a green tick next to a partial + result, a success heading over a real loss.
+Specifically: case 03 succeeded while losing every heading and the + table, and case 06 failed while showing a “what came through” line. Does the language hold + up in both, or does the happy-path framing leak into the sad paths?
+
+
+
+ Would a non-technical person understand what they got back?
+Read the case 03 result screen as if you had just lost the only copy of + your dissertation.
+The question: do you know, without asking anyone, (a) whether you + got your document back, (b) what specifically is missing, (c) what to do next? Flag any + phrase you had to read twice, and any word you would not say out loud to a worried + friend.
+
+
+
+ Does it read as a consumer product, not an engineering tool?
+Look for: jargon leaking through (ZIP, XML, + ParseError, part filenames, byte counts), log-style phrasing where a sentence should + be, counts labelled in lowercase plural like a debug dump. Three such leaks were found and + fixed while this sheet was written, and the automated suite now guards the stage log as + well as the summary — so anything you still find here is new.
+Also: does the page look finished — spacing, alignment, the drop + zone, the download button — or does it look like a test harness for the engine?
+
+
+
+ Legible in both dark mode and light mode?
+Switch your OS appearance and reload the product page (not just this + sheet). Check every state: drop zone, drop-zone hover, the stage list mid-run, a success + screen, a failure screen.
+Look for: the red failure heading against the dark panel, the green + ticks, the muted caveat text at the bottom, the blue download button — anything that goes + low-contrast or muddy in one theme. Check this sheet too.
+
+
+
+
+Does it work at phone width?
+Narrow the window to about 360px, or open it on a phone on the same + network.
+Look for: no horizontal scrolling anywhere, the counts row wrapping + rather than squashing, long stage sentences not overflowing their row, the download button + and “Repair another file” not colliding, and the drop zone still tappable.
+Site inspection
" in r.preview_html + assert "No further defects were observed." in r.preview_html + assert 'src="data:image/png;base64,' in r.preview_html + + +def test_a_failure_carries_no_preview_because_there_is_nothing_to_preview(): + r = repair(broken.missing_document_part(), "x.docx") + assert not r.ok and r.preview_html == "" + + +def test_a_preview_too_large_to_load_names_the_picture_instead_of_dropping_it(): + from docrepair import docx as _docx + from docrepair.media import Image + + blocks = [_docx.Block("image", text="word/media/big.png", + image=Image("word/media/big.png", b"x" * 100, + width_px=10, height_px=10, measured=True))] + html = _docx.blocks_to_html(blocks, inline_images=True, image_budget=10) + assert "image-omitted" in html and "is in the file" in html diff --git a/use-cases/Priyanshu2425/word-doc-repair/tests/test_styled_export.py b/use-cases/Priyanshu2425/word-doc-repair/tests/test_styled_export.py new file mode 100644 index 00000000..20b20096 --- /dev/null +++ b/use-cases/Priyanshu2425/word-doc-repair/tests/test_styled_export.py @@ -0,0 +1,316 @@ +"""The SuperDocs path, keyless. The rule under test is that it can fail in any +way at all and the user still ends up with the file the local rebuild made.""" + +import json + +import pytest + +from docrepair import repair +from docrepair.styled_export import styled_export +from docrepair.superdocs_client import Response, SuperDocsClient +from tests import broken + + +class FakeSuperDocs: + def __init__(self, fail_at=None, quota_exhausted=False, no_job=False, no_file=False, + never_settles=False, quota_remaining=None): + self.fail_at, self.no_job, self.no_file = fail_at, no_job, no_file + self.quota_exhausted = quota_exhausted + self.never_settles = never_settles + # None means the balance cannot be read -- which is the ordinary case + # for a personal key, and is not the same as a balance of zero. + self.quota_remaining = quota_remaining + # What the export hands back. A real .docx by default, built from the + # HTML this fake was given, so the content guard has something honest + # to check. Tests that want a rewrite pass their own. + self.exported = None + self.calls, self.approved, self.uploaded_html = [], [], None + self._approved = False + + def request(self, method, path, **kw): + self.calls.append(path) + if self.fail_at and self.fail_at in path: + raise ConnectionError("network went away") + + usage = {"ops_charged": 1, "monthly_remaining": 10, + "quota_exhausted": self.quota_exhausted} + + if path == "/v1/agents/whoami": + if self.quota_remaining is None: + return Response(401, {"detail": "not an agent key"}) + return Response(200, {"quota": {"tier": "free", "monthly_limit": 500, + "used": 500 - self.quota_remaining, + "remaining": self.quota_remaining}}) + if path == "/v1/documents/upload": + self.uploaded_html = kw["files"]["file"][1] + if self.exported is None: + self.exported = docx_of(self.uploaded_html) + return Response(200, {"ok": True}) + if path == "/v1/chat/async": + if self.no_job: + return Response(200, {"usage": usage}) + return Response(200, {"job_id": "j1", "status": "pending", "usage": usage}) + if path.startswith("/v1/jobs/"): + if self._approved: + # Approval is asynchronous on the real API: the job resumes and + # only then reaches completed. Exporting before that returns the + # pre-edit document with a 200. Verified live 2026-08-19. + if self.never_settles: + return Response(200, {"status": "in_progress", "usage": usage}) + return Response(200, {"status": "completed", "usage": usage}) + batch = json.dumps({"changes": [{"change_id": "ch_1"}]}) + return Response(200, {"status": "awaiting_approval", + "metadata": {"pending_changes": {"content": batch}}, + "usage": usage}) + if path.endswith("/approve"): + self.approved.extend(kw["json"]["changes"]) + self._approved = True + return Response(200, {"status": "ok", "usage": usage}) + if path == "/v1/documents/export": + if self.no_file: + return Response(200, {"raw": b""}, {}) + return Response(200, {"raw": self.exported}, {}) + return Response(404, {}) + + +def docx_of(html) -> bytes: + """A .docx saying exactly what the HTML says -- a styling pass that changed + nothing but the styling. The honest answer, which the guard must accept.""" + import re + + from docrepair.docx import Block, write_docx + + text = html.decode("utf-8") if isinstance(html, bytes) else html + words = re.sub(r"<[^>]+>", " ", text) + import html as _html + + return write_docx([Block("paragraph", _html.unescape(words))]) + + +def blocks_of(data=None): + r = repair(data or broken.healthy(), "d.docx") + from docrepair.docx import read_blocks + import io, zipfile + with zipfile.ZipFile(io.BytesIO(r.output)) as z: + return read_blocks(z.read("word/document.xml")) + + +def run(fake, blocks=None): + return styled_export(SuperDocsClient(fake, sleep=lambda s: None), + "sess", blocks or blocks_of()) + + +def test_the_four_calls_happen_in_the_required_order(): + fake = FakeSuperDocs() + r = run(fake) + assert r.ok and r.output + order = [c for c in fake.calls if not c.startswith("/v1/jobs/")] + # The balance read comes first and is not part of the contract -- it is + # trap 3, asked before the work rather than discovered inside it. + assert order == ["/v1/agents/whoami", + "/v1/documents/upload", "/v1/chat/async", + "/v1/chat/sess/approve", "/v1/documents/export"] + # and it waited for the job to settle before exporting + approve_at = fake.calls.index("/v1/chat/sess/approve") + export_at = fake.calls.index("/v1/documents/export") + assert any(c.startswith("/v1/jobs/") for c in fake.calls[approve_at:export_at]), \ + "exported without waiting for the approved change to be applied" + + +def test_it_sends_html_never_raw_word_xml(): + """The docs are explicit that there is no endpoint for raw Word XML.""" + fake = FakeSuperDocs() + run(fake) + sent = fake.uploaded_html.decode() + assert "" in sent and "
| EMEA | " in sent + + +def test_the_proposed_change_is_double_parsed_and_actually_approved(): + fake = FakeSuperDocs() + run(fake) + assert fake.approved == [{"change_id": "ch_1", "approved": True}] + + +@pytest.mark.parametrize("kwargs,expect", [ + ({"fail_at": "/v1/chat/async"}, "did not work"), + ({"fail_at": "/v1/documents/export"}, "did not work"), + ({"quota_exhausted": True}, "allowance is exhausted"), + ({"no_job": True}, "did not start a job"), + ({"no_file": True}, "returned no file"), +]) +def test_every_failure_degrades_to_the_local_rebuild_and_says_why(kwargs, expect): + """The engine has already produced a valid file before this runs. Nothing + here may take that away from the user.""" + r = run(FakeSuperDocs(**kwargs)) + assert not r.ok + assert r.output == b"" + assert any(expect in n for n in r.notes), r.notes + + +def test_it_never_raises_whatever_happens(): + class Exploding: + def request(self, *a, **k): + raise RuntimeError("boom") + + r = styled_export(SuperDocsClient(Exploding(), sleep=lambda s: None), "s", blocks_of()) + assert not r.ok and r.notes + + +def test_it_keeps_the_plain_rebuild_when_the_job_never_finishes_applying(): + """If the job never reaches completed, the styled export would be the + document as it was before the edit — so the local rebuild is kept instead.""" + r = run(FakeSuperDocs(never_settles=True)) + assert not r.ok + assert any("did not finish applying" in n for n in r.notes) + + +def test_the_vendored_client_has_not_drifted(): + """Build B vendors Build A's client so each stands alone in the builds + repository. The multipart fix for BUG-015 landed in the original and not + here, so this build kept sending an empty body and getting a 422 long after + the other one worked. Everything below the docstring must stay identical.""" + import pathlib + + here = (pathlib.Path(__file__).resolve().parents[1] + / "backend/docrepair/superdocs_client.py") + there = (pathlib.Path(__file__).resolve().parents[2] + / "quota-aware-agent/backend/quota_aware_agent/client.py") + origin_build = there.parents[2] + if not origin_build.exists(): # published alone, without its sibling + import pytest + pytest.skip(f"{origin_build.name} is not in this checkout") + assert there.exists(), ( + f"{origin_build.name} is here but {there.name} is not where this guard " + "looks. A guard that skips when its target moves is a guard that has " + "stopped guarding, and nothing fails." + ) + + def body(p): + return p.read_text().split('"""', 2)[2] + + assert body(here) == body(there), ( + "the vendored client has drifted from its origin -- re-copy it, " + "keeping only the docstring different" + ) + + +def test_it_never_reports_zero_operations_for_a_billable_call(): + """The async endpoints return no usage block, so a zero means "not + reported", not "free". Printing "0 operations" about a request that was + billed is the same bluff BUG-017 was about, in a new place.""" + r = run(FakeSuperDocs()) + assert r.ok + assert r.ops_charged >= 1 + + +def test_it_does_not_spend_an_allowance_it_has_already_been_told_is_gone(): + """Trap 3. A styling pass that cannot finish should never be started. + + The failure this prevents is not a wasted call -- it is a person watching a + progress line for work that was refused at the far end, which is exactly the + shape of "it ran for a bit and then wanted money" the README quotes. + """ + fake = FakeSuperDocs(quota_remaining=0) + r = run(fake) + assert not r.ok + assert fake.calls == ["/v1/agents/whoami"], "it sent something anyway" + assert r.ops_charged == 0 + assert r.allowance_known and r.allowance_remaining == 0 + assert any("nothing was spent" in n for n in r.notes) + assert any("still yours" in n for n in r.notes) + + +def test_a_balance_it_cannot_read_is_not_treated_as_a_balance_of_zero(): + """A personal key is not an agent key, and `whoami` answers only the latter. + + Refusing on a number nobody managed to read would be its own bluff, so the + work proceeds and the report says the balance was unknown. + """ + fake = FakeSuperDocs() # whoami answers 401 + r = run(fake) + assert r.ok, "an unreadable balance stopped work it had no business stopping" + assert not r.allowance_known + + +def test_a_balance_that_is_there_is_read_and_reported(): + fake = FakeSuperDocs(quota_remaining=7) + r = run(fake) + assert r.ok + assert r.allowance_known and r.allowance_remaining == 7 + + +def test_a_balance_read_that_blows_up_never_costs_the_caller_the_styling(): + """The preflight is a courtesy, not a gate. If it cannot answer, it gets out + of the way.""" + class Exploding(FakeSuperDocs): + def request(self, method, path, **kw): + if path == "/v1/agents/whoami": + raise ConnectionError("no network for this one call") + return super().request(method, path, **kw) + + r = run(Exploding()) + assert r.ok and not r.allowance_known + + +def test_a_styled_file_that_says_something_else_is_thrown_away(): + """The defect this guard exists for, seen live on 2026-08-20: a four-line + recovered report came back with three invented paragraphs, a subtotal row, + a disclaimer and a signature block. It opens cleanly and it reads better + than the plain rebuild, and it is partly fiction. Handing that to somebody + who came here to get their own words back is the worst thing this product + could do -- worse than returning nothing, because they would not notice. + """ + fake = FakeSuperDocs() + fake.exported = _rewritten() + r = run(fake) + assert not r.ok, "a rewritten document was handed over as a repair" + assert r.rejected_for_content + assert r.output == b"" + assert any("wording changed" in n for n in r.notes) + assert any("still yours" in n for n in r.notes) + + +def _rewritten() -> bytes: + from docrepair.docx import Block, write_docx + + return write_docx([ + Block("heading", "Quarterly Report", level=1), + Block("paragraph", "Revenue rose in Q3."), + Block("paragraph", "This growth reflects a sustained commitment to " + "client retention and successful expansion."), + ]) + + +def test_a_styled_file_that_says_the_same_thing_is_accepted(): + """The guard has to let the good case through, or it is just an off switch.""" + r = run(FakeSuperDocs()) + assert r.ok and not r.rejected_for_content + + +def test_the_drift_check_reads_re_wrapping_and_re_escaping_as_no_change(): + from docrepair.docx import Block, write_docx + from docrepair.styled_export import content_drift + + html = "