feat(scripts): one Sieve generator, and the preview now comes from it (#61)

* feat(scripts): one Sieve generator, and the preview now comes from it

`previewRule` in scriptDocument.js was a second implementation of
SieveGenerator. Both modules said so in a comment — "it is a second
implementation of the backend generator and the two must agree",
"it must agree with the backend generator" — and nothing checked it.
Five divergences had shipped:

  1. dropped `negate`, so a NOT condition previewed as its opposite
  2. no quote escaping
  3. a disabled rule shown live, with no ## anywhere
  4. no `# --- name ---` line, the only place a Rule's name is stored
  5. NOTHING at all for a Rule whose last Condition was deleted, while
     a save writes `if anyof ( ) {` — Sieve a real server refuses

The fifth is the worst: the editor showed an empty preview for the one
state where the user most needed to be told something was wrong.

POST /api/scripts/preview renders one Rule and answers. It depends on
get_session and NOT on get_script_store, so it authenticates without
opening a ManageSieve connection — the editor calls it on a keystroke
timer, and a connection per keystroke is a denial of service aimed at
the user's own mail server. That guard is a test, and the test is
mutation-checked: swapping the dependency makes it fail, and a second
test proves the sabotage bites on a route that DOES take the store.

Save and preview now go through one function. `generate` used to inline
the `## `-prefixing for a disabled Rule; that is `SieveGenerator
.generate_entry` now, and both callers use it. `generate_rule` and
`rule_from_json` are the module-level rule-sized entry points.

THE TEST THAT COULD NOT EXIST BEFORE: preview a Rule, save that same
Rule, and require the preview to be a literal substring of what the
store then holds — across nine shapes including all five divergences.
An agreement test needs one side to be authoritative; there was no such
side while there were two generators.

previewRule, renderTest, renderAction and the frontend `quote` are
deleted, with their 93 lines of tests. Deleting the duplicate beats
testing it. In their place scriptDocument exports `entryToWire`, which
`toWire` now maps over — the preview must post the SAME projection a
save posts, or it is previewing something else again.

The editor debounces at 200ms and carries a sequence number, so a slow
answer for an older Rule cannot overwrite a newer one, and it says
"preview unavailable" rather than leaving the previous rule's Sieve on
screen next to the rule being edited.

Route inventory updated in both of its lists. A script may still be
CALLED "preview" — pinned, because `POST /{name}` does not exist today
and the day it does the shadowing would be silent.

1017 backend tests, 54 frontend, svelte-check 0/0, ruff clean.

Refs areyousievious-8fg.17

* style(frontend): the blank lines the review counted

Cosmetic only — doubled blank lines either side of the entryToWire block.

Refs areyousievious-8fg.17

* perf(frontend): preview only when the selected rule actually changed

Raised in review of #61, and my comment was the weaker claim: it said the
trigger fires on each keystroke, when it fires on ANY document mutation.
`rules` is rebuilt whenever `script` is reassigned, so adding, deleting or
reordering some OTHER rule rescheduled a preview of the selected one and
spent a request to be told the same bytes it was already showing.

Comparing the wire payload rather than the array reference makes those
free, and covers the keystroke that leaves wire content unchanged too. The
payload compared is the one that gets posted, so the two cannot drift.

An error clears the remembered payload, so the next mutation retries
rather than matching it and leaving the message up for good.

The comment now says what actually happens.

Not unit-tested: the logic is inside a .svelte file and this repo has no
component test harness. svelte-check, vitest and the build are clean.

Refs areyousievious-8fg.17

Author: derekslenk

CHANGELOG.md

@@ -19,6 +19,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- `POST /api/scripts/preview` renders one Rule through the backend generator, and the SPA's duplicate generator (`previewRule`) is deleted. The preview is now the bytes a save writes, asserted as such; the duplicate had diverged five ways, including showing nothing for a Rule whose last Condition was deleted while a save wrote invalid Sieve (areyousievious-8fg.17)
+
 - GitHub Actions CI workflow (`.github/workflows/ci.yml`): runs pytest and frontend build on every push and pull request (P1)
 - Sieve parser regression test suite (`backend/tests/`) covering round-trip stability, else/elsif handling, address-part/`:comparator` parsing, and ReDoS budget (Phase CP1)
 - Sieve fixture corpus (`backend/test_scripts/`): twelve hand-written one-construct fixtures plus sievelib's parser corpus vendored under MIT in `vendor/`, with a per-fixture recognition census and a pinned recogniser-reach total (areyousievious-8fg.3)

backend/AGENTS.md

@@ -30,7 +30,7 @@ FastAPI application that serves the Svelte SPA as static files and provides a RE
 ## Subdirectories
 | Directory | Purpose |
 |-----------|---------|
-| `routers/` | One module per URL area: `auth`, `scripts`, `folders`, `health`, `static`. Do NOT cross-import between routers — shared helpers belong in `dependencies.py` |
+| `routers/` | One module per URL area: `auth`, `scripts`, `folders`, `health`, `static`. Do NOT cross-import between routers — shared helpers belong in `dependencies.py`. `POST /api/scripts/preview` is the one script route that takes `get_session` and NOT `get_script_store`: it renders a Rule through `generate_rule` without dialling, because the editor calls it on a keystroke timer |
 | `tests/` | 30 pytest files plus a shared conftest.py and `fakes.py` (in-memory ScriptStore/FolderStore), mostly regression locks tied to a bead id in the module docstring |
 | `test_scripts/` | The Sieve fixture corpus: three captured real-world scripts, twelve hand-written one-construct files, and `vendor/` — sievelib's own parser corpus under MIT, regenerated by `tools/vendor-sievelib-corpus.py` (see `test_scripts/AGENTS.md`) |
 

backend/api_models.py

@@ -179,6 +179,19 @@ class CreateFolderRequest(BaseModel):
     name: str = Field(min_length=1, max_length=200)
 
 
+class PreviewRequest(BaseModel):
+    """One Rule to render as Sieve (areyousievious-8fg.18 vocabularies apply).
+
+    Deliberately one Rule and not a whole script: the editor previews the rule
+    the user is looking at, and asking for a script would make the endpoint
+    need `requires`, which is a property of the script rather than of any Rule.
+    """
+
+    model_config = _STRICT
+
+    rule: RuleDTO
+
+
 # ── Response models ──
 
 
@@ -224,3 +237,10 @@ class ScriptResponse(BaseModel):
 class ScriptRawResponse(BaseModel):
     name: str
     content: str
+
+
+class PreviewResponse(BaseModel):
+    """POST /api/scripts/preview — the exact bytes a save would write for this
+    Rule, minus the script-level `require` line."""
+
+    sieve: str

backend/routers/scripts.py

@@ -1,9 +1,14 @@
 """
 Sieve script router (areyousievious-u40 split from app.py).
 
-Owns the nine /api/scripts/* endpoints that read, write, import,
+Owns the ten /api/scripts/* endpoints that read, write, import,
 export, activate, and delete Sieve scripts via ManageSieve.
 
+`preview` is the one that does not touch ManageSieve at all: it renders a
+Rule with the same generator a save uses and answers. It exists so the SPA
+does not have to carry a second implementation of that generator, which it
+did, and which had diverged five ways (areyousievious-8fg.17).
+
 The import size cap comes from `request.app.state.settings.max_body_bytes`,
 the same value the body-size middleware uses. It was a local constant here,
 which meant raising AYS_MAX_BODY_BYTES moved one limit and not the other.
@@ -15,20 +20,25 @@
 
 from api_models import (
     OkResponse,
+    PreviewRequest,
+    PreviewResponse,
     SaveRawRequest,
     SaveScriptRequest,
     ScriptListItem,
     ScriptRawResponse,
     ScriptResponse,
 )
+from auth import Session
 from config import Settings
-from dependencies import get_script_store, get_settings
+from dependencies import get_script_store, get_session, get_settings
 from fastapi import APIRouter, Depends, File, Form, HTTPException, Response, UploadFile
 from mail_stores import ScriptStore
 from sieve_transform import (
+    generate_rule,
     generate_sieve,
     json_to_script,
     parse_sieve,
+    rule_from_json,
     script_to_json,
 )
 
@@ -90,6 +100,23 @@ def import_script(
     return {"ok": True, "name": name}
 
 
+@router.post("/preview", response_model=PreviewResponse)
+def preview_rule(req: PreviewRequest, _session: Session = Depends(get_session)):
+    """Render one Rule as the Sieve a save would write.
+
+    NO MAIL-SERVER DIAL. It depends on `get_session` and not on
+    `get_script_store`, so it authenticates without opening a ManageSieve
+    connection — this runs on every keystroke behind a debounce, and a
+    connection per keystroke would be a self-inflicted denial of service
+    against the user's own mail server.
+
+    It replaces `previewRule` in the SPA, which was a second implementation of
+    `SieveGenerator` that had already diverged five ways. Declared BEFORE the
+    `/{name}` routes so `preview` is read as a literal path segment.
+    """
+    return {"sieve": generate_rule(rule_from_json(req.rule.model_dump()))}
+
+
 @router.put("/{name}", response_model=OkResponse, response_model_exclude_none=True)
 def save_script(name: str, req: SaveScriptRequest, store: ScriptStore = Depends(get_script_store)):
     """Save script from JSON rules (generates Sieve)."""

backend/sieve_transform.py

@@ -486,12 +486,7 @@ def generate(self, script: SieveScript) -> str:
         # Generate in order — position in `entries` IS the order
         for entry in script.entries:
             if isinstance(entry, Rule):
-                rule_text = self._generate_rule(entry)
-                if not entry.enabled:
-                    rule_text = "\n".join(
-                        "## " + line if line.strip() else "##" for line in rule_text.split("\n")
-                    )
-                parts.append(rule_text)
+                parts.append(self.generate_entry(entry))
                 parts.append("")
             else:
                 if entry.comment:
@@ -501,6 +496,25 @@ def generate(self, script: SieveScript) -> str:
 
         return "\n".join(parts).rstrip() + "\n"
 
+    def generate_entry(self, rule: Rule) -> str:
+        """The exact bytes one Rule contributes to a script.
+
+        Public because the preview endpoint calls it (areyousievious-8fg.17),
+        and `generate` calls it too. That sharing is the point: the SPA used to
+        carry `previewRule`, a SECOND implementation of this generator, and
+        both modules said in a comment that the two "must agree" while nothing
+        checked it. Five divergences shipped — dropped `negate`, no quote
+        escaping, a disabled rule shown live, the missing `# --- name ---`
+        line, and a conditionless Rule previewing as nothing while a save
+        wrote `if anyof ( ) {`. There is now one implementation to diverge
+        from.
+        """
+        text = self._generate_rule(rule)
+        if rule.enabled:
+            return text
+        # A disabled Rule is stored commented out.
+        return "\n".join("## " + line if line.strip() else "##" for line in text.split("\n"))
+
     def _compute_requires(self, script: SieveScript) -> list[str]:
         """Compute required extensions from rules."""
         requires = set(script.requires)
@@ -704,3 +718,23 @@ def parse_sieve(text: str) -> SieveScript:
 def generate_sieve(script: SieveScript) -> str:
     """Generate Sieve text from a SieveScript."""
     return SieveGenerator().generate(script)
+
+
+def rule_from_json(data: dict) -> Rule:
+    """Build a single Rule from its wire dict.
+
+    The rule-sized counterpart to `json_to_script`, for the preview endpoint —
+    which has one Rule and no script to put it in.
+    """
+    return _rule_from_json(data)
+
+
+def generate_rule(rule: Rule) -> str:
+    """The Sieve one Rule contributes to a script, byte for byte.
+
+    Goes through the same `SieveGenerator.generate_entry` a save does, so a
+    preview cannot say one thing and a save write another. Note what this does
+    NOT include: the `require [...]` line, which is a property of the whole
+    script rather than of any one Rule.
+    """
+    return SieveGenerator().generate_entry(rule)