Partial rendering with spec change detection

change_detection.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from plain_modules import PlainModule
+
+MODULE_FUNCTIONALITIES_KEY = "functionalities"
+NON_FUNCTIONAL_SOURCE_HASH_KEY = "non_functional_source_hash"
+
+
+@dataclass
+class FunctionalityChange:
+    module: str
+    frid: str
+    change_type: Literal["added", "removed", "edited", "moved"]
+    detail: str | None = None
+
+
+@dataclass
+class PartialRenderStart:
+    module: "PlainModule"
+    frid: str
+
+
+def determine_partial_render_start(plain_module: "PlainModule") -> PartialRenderStart | None:
+    """Determine where to start partial rendering based on spec changes.
+
+    Returns None (only full render is safe) if non-FR sections changed
+    (e.g. definitions, implementation reqs) since previously-rendered FRs
+    were generated without that context, if no changes are found, or if
+    all changes are trailing removals that don't require rendering.
+    """
+    all_modules = plain_module.all_required_modules + [plain_module]
+
+    for module in all_modules:
+        if _non_functional_content_changed(module):
+            return None
+
+        changes = _detect_module_changes(module)
+        if not changes:
+            continue
+
+        current_fr_count = len(module._get_module_functional_requirements())
+        earliest_frid = _get_earliest_affected_frid(changes, current_fr_count)
+        if earliest_frid is None:
+            continue
+        return PartialRenderStart(module=module, frid=earliest_frid)
+
+    return None
+
+
+def _non_functional_content_changed(module: "PlainModule") -> bool:
+    """Check whether anything outside functional specs changed since last render.
+
+    A missing stored hash (older builds) is treated as changed — partial rendering
+    is unsafe without a known baseline.
+    """
+    metadata = module.load_module_metadata()
+    if not metadata:
+        return False
+    stored_hash = metadata.get(NON_FUNCTIONAL_SOURCE_HASH_KEY)
+    if stored_hash is None:
+        return True
+    return stored_hash != module.get_module_non_functional_source_hash()
+
+
+def _get_earliest_affected_frid(changes: list[FunctionalityChange], current_fr_count: int) -> str | None:
+    """Earliest FRID (in current spec numbering) that must be re-rendered.
+
+    Returns the minimum position across all changes:
+    - added / edited: the FRID itself.
+    - removed: the position the removal opened up (now occupied by the next FR).
+    - moved: the FR's old position.
+
+    Correctness does not rely on any single change type's position being individually
+    "the" earliest (in particular, a move's old position is *not* always its earliest
+    touched position once moves mix with adds/removes). The guarantee is structural:
+    the first index at which the new spec diverges from the old is always emitted as
+    some change anchored at that index — a move with that old position, or an
+    edit/removal/addition there — so the minimum over all change FRIDs lands at or
+    before the true first divergence. Rendering runs from this FRID to the end of the
+    module, so an at-or-before start point is always safe (it can re-render unchanged
+    trailing FRs, but never skips a changed one).
+
+    Returns None when every change is a removal beyond the current spec length
+    (only trailing FRs were removed, so nothing needs rendering).
+    """
+    earliest = None
+    for change in changes:
+        frid_int = int(change.frid)
+        if change.change_type == "removed" and frid_int > current_fr_count:
+            continue
+        if earliest is None or frid_int < earliest:
+            earliest = frid_int
+    if earliest is None:
+        return None
+    return str(earliest)
+
+
+def _detect_module_changes(module: "PlainModule") -> list[FunctionalityChange]:
+    metadata = module.load_module_metadata()
+    old_frs: list[str] = metadata.get(MODULE_FUNCTIONALITIES_KEY, []) if metadata else []
+    new_frs: list[str] = module._get_module_functional_requirements()
+
+    if old_frs == new_frs:
+        return []
+
+    moves, edits, removed, added = _classify_changes(old_frs, new_frs)
+
+    changes: list[FunctionalityChange] = []
+    name = module.module_name
+
+    for old_idx, new_idx in moves:
+        old_frid = _frid_from_index(old_idx)
+        new_frid = _frid_from_index(new_idx)
+        changes.append(FunctionalityChange(module=name, frid=old_frid, change_type="moved", detail=new_frid))
+
+    for idx in edits:
+        changes.append(FunctionalityChange(module=name, frid=_frid_from_index(idx), change_type="edited"))
+
+    for idx in removed:
+        changes.append(FunctionalityChange(module=name, frid=_frid_from_index(idx), change_type="removed"))
+
+    for idx in added:
+        changes.append(FunctionalityChange(module=name, frid=_frid_from_index(idx), change_type="added"))
+
+    return changes
+
+
+def _classify_changes(
+    old_frs: list[str], new_frs: list[str]
+) -> tuple[list[tuple[int, int]], list[int], list[int], list[int]]:
+    matched_old: set[int] = set()
+    matched_new: set[int] = set()
+
+    for i in range(min(len(old_frs), len(new_frs))):
+        if old_frs[i] == new_frs[i]:
+            matched_old.add(i)
+            matched_new.add(i)
+
+    content_matches: list[tuple[int, int]] = []
+    for old_idx in range(len(old_frs)):
+        if old_idx in matched_old:
+            continue
+        for new_idx in range(len(new_frs)):
+            if new_idx in matched_new:
+                continue
+            if old_frs[old_idx] == new_frs[new_idx]:
+                content_matches.append((old_idx, new_idx))
+                matched_old.add(old_idx)
+                matched_new.add(new_idx)
+                break
+
+    moves: list[tuple[int, int]] = []
+    if content_matches and _has_relative_order_change(content_matches):
+        moves = content_matches
+
+    edits: list[int] = []
+    for i in range(min(len(old_frs), len(new_frs))):
+        if i not in matched_old and i not in matched_new:
+            edits.append(i)
+            matched_old.add(i)
+            matched_new.add(i)
+
+    removed = [i for i in range(len(old_frs)) if i not in matched_old]
+    added = [i for i in range(len(new_frs)) if i not in matched_new]
+
+    return moves, edits, removed, added
+
+
+def _has_relative_order_change(matches: list[tuple[int, int]]) -> bool:
+    """Check if content matches represent a true reorder (relative order changed).
+
+    If all matches preserve relative order (sorted by old_idx gives same ordering
+    as sorted by new_idx), it's just a positional shift from insertions/removals.
+    """
+    if len(matches) <= 1:
+        return False
+    sorted_by_old = sorted(matches, key=lambda m: m[0])
+    new_indices = [m[1] for m in sorted_by_old]
+    for i in range(len(new_indices) - 1):
+        if new_indices[i] > new_indices[i + 1]:
+            return True
+    return False
+
+
+def _frid_from_index(index: int) -> str:
+    return str(index + 1)