backspec 0.0.1__py3-none-any.whl

backspec/modules/requirements/use_cases.py

@@ -0,0 +1,135 @@
+"""Synthesise requirements capability by capability, then challenge each one."""
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+
+from backspec.kernel import prompts
+from backspec.kernel.llm import LLMError, LLMPort, LLMRequest, ask
+from backspec.kernel.text import short_hash
+from backspec.modules.capabilities.facade import Capability
+from backspec.modules.evidence.facade import Observation
+from backspec.modules.requirements.domain import (AssessReply, ConsolidateReply, Requirement, SynthReply, assess_block,
+                                              build_requirement, consolidate_input, merge_requirements, settle, synth_input)
+
+SYNTH_BATCH = 180    # observations per synthesis call
+CONSOLIDATE_MIN = 8  # a capability with more requirements than max(this, a third of its observations) is consolidated
+ASSESS_BATCH = 12    # requirements per support call
+
+
+def fingerprint() -> str:
+    """Changes whenever the way requirements are written, merged or judged does. Requirements an
+    earlier run made another way are not reused."""
+    return short_hash(prompts.load("synthesise"), prompts.load("consolidate"), prompts.load("assess"),
+                      SYNTH_BATCH, CONSOLIDATE_MIN, ASSESS_BATCH)
+
+
+@dataclass
+class Synthesis:
+    requirements: list[Requirement] = field(default_factory=list)
+    open_questions: dict[str, list[str]] = field(default_factory=dict)
+    failed: dict[str, str] = field(default_factory=dict)   # capability -> why
+    unconsolidated: dict[str, str] = field(default_factory=dict)   # capability -> why the merge pass failed
+    dropped_scenarios: int = 0   # scenarios left out: a part missing, or no real observation cited
+
+
+def synthesise(capabilities: list[Capability], by_capability: dict[str, list[Observation]],
+               llm: LLMPort, workers: int = 4) -> Synthesis:
+    instructions = prompts.load("synthesise")
+    jobs = []
+    for capability in capabilities:
+        observations = by_capability.get(capability.id, [])
+        for start in range(0, len(observations), SYNTH_BATCH):
+            jobs.append((capability, observations[start:start + SYNTH_BATCH]))
+
+    def run(job: tuple[Capability, list[Observation]]) -> SynthReply | LLMError:
+        capability, observations = job
+        prompt = (f"{instructions}\n\n# The capability\n\nCAPABILITY: {capability.id}\nNAME: {capability.name}\n"
+                  f"SUMMARY: {capability.summary}\n\n# The observations\n\n{synth_input(observations)}")
+        try:
+            return ask(llm, LLMRequest("synthesise", prompt, "strong"), SynthReply)
+        except LLMError as error:
+            return error
+
+    with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
+        replies = list(pool.map(run, jobs))
+    result = Synthesis()
+    seen: set[str] = set()
+    for (capability, observations), reply in zip(jobs, replies):
+        if isinstance(reply, LLMError):
+            result.failed[capability.id] = str(reply)[:300]
+            continue
+        known = {o.id: o for o in observations}
+        for raw in reply.requirements:
+            requirement, dropped = build_requirement(raw, capability.id, known)
+            result.dropped_scenarios += dropped
+            if requirement and requirement.id not in seen:
+                seen.add(requirement.id)
+                result.requirements.append(requirement)
+        if reply.open_questions:
+            result.open_questions.setdefault(capability.id, []).extend(reply.open_questions)
+    consolidate(result, capabilities, by_capability, {c for c, _ in jobs_by_cap(jobs, True)}, llm, workers)
+    return result
+
+
+def jobs_by_cap(jobs: list[tuple[Capability, list[Observation]]], multi_only: bool) -> list[tuple[str, int]]:
+    """(capability id, number of batches) for each capability; with multi_only, only those
+    synthesised in more than one batch."""
+    counts: dict[str, int] = {}
+    for capability, _ in jobs:
+        counts[capability.id] = counts.get(capability.id, 0) + 1
+    return [(c, n) for c, n in counts.items() if n > 1 or not multi_only]
+
+
+def consolidate(result: Synthesis, capabilities: list[Capability], by_capability: dict[str, list[Observation]],
+                batched: set[str], llm: LLMPort, workers: int = 4) -> None:
+    """Merge requirements that state the same behaviour, for each capability that was synthesised
+    in more than one batch or came out too fine. Failure keeps the originals and is recorded."""
+    by_id = {c.id: c for c in capabilities}
+    own: dict[str, list[Requirement]] = {}
+    for requirement in result.requirements:
+        own.setdefault(requirement.capability, []).append(requirement)
+    due = [cid for cid, reqs in own.items()
+           if cid in by_id and len(reqs) > 1
+           and (cid in batched or len(reqs) > max(CONSOLIDATE_MIN, len(by_capability.get(cid, [])) / 3))]
+    if not due:
+        return
+    instructions = prompts.load("consolidate")
+
+    def run(cid: str) -> ConsolidateReply | LLMError:
+        prompt = (f"{instructions}\n\n# The capability\n\nCAPABILITY: {cid}\nNAME: {by_id[cid].name}\n"
+                  f"SUMMARY: {by_id[cid].summary}\n\n# The requirements\n\n{consolidate_input(own[cid])}")
+        try:
+            return ask(llm, LLMRequest("consolidate", prompt, "strong"), ConsolidateReply)
+        except LLMError as error:
+            return error
+
+    with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
+        replies = list(pool.map(run, due))
+    for cid, reply in zip(due, replies):
+        if isinstance(reply, LLMError):
+            result.unconsolidated[cid] = str(reply)[:300]
+        else:
+            own[cid] = merge_requirements(own[cid], reply.groups)
+    order = list(own)
+    result.requirements = [r for cid in order for r in own[cid]]
+
+
+def assess(requirements: list[Requirement], file_lines: dict[str, list[str]], llm: LLMPort,
+           workers: int = 4) -> list[Requirement]:
+    """Each requirement with a support verdict, keyed by id. One left without a verdict stays
+    `not_assessed`; it is never assumed to be supported."""
+    instructions = prompts.load("assess")
+    batches = [requirements[start:start + ASSESS_BATCH] for start in range(0, len(requirements), ASSESS_BATCH)]
+
+    def run(batch: list[Requirement]) -> AssessReply:
+        blocks = "\n".join(assess_block(r, file_lines) for r in batch)
+        try:
+            return ask(llm, LLMRequest("assess", f"{instructions}\n\n# The requirements\n\n{blocks}", "strong"), AssessReply)
+        except LLMError:
+            return AssessReply()
+
+    with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
+        replies = list(pool.map(run, batches))
+    verdicts = {v.id: v for reply in replies for v in reply.verdicts}
+    return [settle(requirement, verdicts.get(requirement.id)) for requirement in requirements]

backspec/modules/review/domain.py

@@ -0,0 +1,129 @@
+"""Review: a person's decisions about requirements, and ids that survive a re-run.
+
+A requirement's id is a hash of its wording, so it changes whenever the wording does. What
+stays put between runs is the code it rests on. Its anchors are the set of (path, quote with
+whitespace squashed) over its evidence, and ids are carried from the previous run by how much
+two requirements' anchors overlap. Capability ids are never used: they can be renamed.
+
+Pure logic, no I/O.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Literal, Sequence
+
+from pydantic import BaseModel, Field
+
+from backspec.kernel.text import squash
+
+MATCH_THRESHOLD = 0.5
+
+Anchors = frozenset  # frozenset[tuple[str, str]]
+Decision = Literal["confirm", "edit", "reject"]
+Outcome = Literal["confirmed", "edited", "rejected", "needs_review"]
+
+
+class ReviewFileError(ValueError):
+    """The review file exists but cannot be read as review entries."""
+
+
+class UnknownRequirement(LookupError):
+    """A requirement id that is not in the result it was looked up in."""
+
+
+class ReviewEntry(BaseModel):
+    id: str
+    decision: Decision
+    statement: str | None = None              # for edit; absent keeps the statement
+    conditions: list[str] | None = None       # for edit; absent keeps the conditions
+    reviewer: str
+    date: str
+    note: str | None = None
+    anchors: list[tuple[str, str]] = Field(default_factory=list)   # written by the tool
+
+
+class ReviewSummary(BaseModel):
+    carried: int = 0
+    new: int = 0
+    confirmed: int = 0
+    edited: int = 0
+    rejected_hidden: int = 0
+    needs_review: int = 0
+    stale_entries: list[str] = Field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class Known:
+    """A requirement from before: its id, its anchors, and whether a person had looked at it."""
+    id: str
+    anchors: frozenset
+    reviewed: bool
+
+
+@dataclass(frozen=True)
+class Carry:
+    id: str                     # the id this requirement ends with, unique among the run
+    carried: bool               # it took a previous id
+    ambiguous_reviewed: bool    # the match was ambiguous and a candidate had been reviewed
+
+
+def anchors_of(evidence: Iterable[tuple[str, str]]) -> frozenset:
+    return frozenset((path, squash(quote)) for path, quote in evidence)
+
+
+def overlap(a: frozenset, b: frozenset) -> float:
+    union = len(a | b)
+    return len(a & b) / union if union else 0.0
+
+
+def _single_best(scores: Sequence[float]) -> int | None:
+    """The index of the one highest score, if it reaches the threshold and nothing ties it."""
+    top = max(scores, default=0.0)
+    if top < MATCH_THRESHOLD:
+        return None
+    winners = [index for index, score in enumerate(scores) if score == top]
+    return winners[0] if len(winners) == 1 else None
+
+
+def carry_ids(new: Sequence[tuple[str, frozenset]], previous: Sequence[Known]) -> list[Carry]:
+    """For each new requirement (its own id, its anchors), the id it ends with.
+
+    It takes a previous id only when that previous requirement is its single best match and it
+    is that one's single best match too. Otherwise it keeps its own id, flagged when the match
+    was ambiguous and any candidate had been reviewed. Ids in the result are unique."""
+    scores = [[overlap(anchors, old.anchors) for old in previous] for _, anchors in new]
+    chosen: list[int | None] = []
+    flagged: list[bool] = []
+    for row in scores:
+        best = _single_best(row)
+        mutual = best is not None and _single_best([other[best] for other in scores]) == len(chosen)
+        chosen.append(best if mutual else None)
+        candidates = [k for k, score in enumerate(row) if score >= MATCH_THRESHOLD]
+        flagged.append(not mutual and any(previous[k].reviewed for k in candidates))
+    used: set[str] = set()
+    ids: list[str | None] = [None] * len(new)
+    for index, match in enumerate(chosen):          # carried ids claim their place first
+        if match is not None:
+            ids[index] = _free(previous[match].id, used)
+    for index, (own, _) in enumerate(new):
+        if ids[index] is None:
+            ids[index] = _free(own, used)
+    return [Carry(id=ids[i], carried=chosen[i] is not None, ambiguous_reviewed=flagged[i])  # type: ignore[arg-type]
+            for i in range(len(new))]
+
+
+def _free(wanted: str, used: set[str]) -> str:
+    candidate, number = wanted, 1
+    while candidate in used:
+        number += 1
+        candidate = f"{wanted}-{number}"
+    used.add(candidate)
+    return candidate
+
+
+def decide(entry: ReviewEntry, current: frozenset) -> Outcome:
+    """What an entry does to a requirement. If the evidence is not what the person saw, the
+    requirement stays as it is and needs another look, whatever they decided."""
+    if frozenset(map(tuple, entry.anchors)) != current:
+        return "needs_review"
+    return {"confirm": "confirmed", "edit": "edited", "reject": "rejected"}[entry.decision]  # type: ignore[return-value]

backspec/modules/review/facade.py

@@ -0,0 +1,32 @@
+"""Review, as the rest of backspec sees it."""
+from __future__ import annotations
+
+from backspec.modules.requirements.facade import Requirement
+from backspec.modules.review.domain import (Decision, ReviewEntry, ReviewFileError, ReviewSummary,
+                                        UnknownRequirement)
+from backspec.modules.review.ports import ReviewStorePort
+from backspec.modules.review.use_cases import ReviewOutcome, apply_review, record
+
+__all__ = ["Decision", "ReviewEntry", "ReviewFacade", "ReviewFileError", "ReviewOutcome", "ReviewStorePort",
+           "ReviewSummary", "UnknownRequirement"]
+
+
+class ReviewFacade:
+    def __init__(self, store: ReviewStorePort | None = None):
+        self._store = store
+
+    def applies(self, previous: list[Requirement] | None) -> bool:
+        """The step runs only when there is a previous result or a review file to work from."""
+        return previous is not None or self._store is not None
+
+    def apply(self, requirements: list[Requirement], previous: list[Requirement] | None) -> ReviewOutcome:
+        entries = self._store.load() if self._store else []
+        return apply_review(requirements, previous or [], entries)
+
+    def record(self, requirements: list[Requirement], requirement_id: str, decision: Decision, *,
+               statement: str | None = None, conditions: list[str] | None = None, reviewer: str, date: str,
+               note: str | None = None) -> ReviewEntry:
+        if self._store is None:
+            raise ValueError("no review file to write to")
+        return record(self._store, requirements, requirement_id, decision, statement=statement,
+                      conditions=conditions, reviewer=reviewer, date=date, note=note)

backspec/modules/review/ports.py

@@ -0,0 +1,15 @@
+"""What review needs from the outside world."""
+from __future__ import annotations
+
+from typing import Protocol
+
+from backspec.modules.review.domain import ReviewEntry
+
+
+class ReviewStorePort(Protocol):
+    def load(self) -> list[ReviewEntry]:
+        """Every entry, in file order. No file means no entries."""
+        ...
+
+    def save(self, entries: list[ReviewEntry]) -> None:
+        ...

backspec/modules/review/use_cases.py

@@ -0,0 +1,89 @@
+"""Carry ids forward, apply a person's decisions, and record new ones."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from backspec.modules.requirements.facade import Requirement
+from backspec.modules.review.domain import (Decision, Known, ReviewEntry, ReviewSummary, UnknownRequirement,
+                                        anchors_of, carry_ids, decide)
+from backspec.modules.review.ports import ReviewStorePort
+
+
+@dataclass
+class ReviewOutcome:
+    requirements: list[Requirement]
+    summary: ReviewSummary
+    hidden: list[Requirement] = field(default_factory=list)   # rejected by a person; kept, not shown
+
+
+def requirement_anchors(requirement: Requirement) -> frozenset:
+    return anchors_of((e.path, e.quote) for e in requirement.evidence)
+
+
+def _known(previous: list[Requirement], entries: list[ReviewEntry]) -> list[Known]:
+    """What the last run knew. A rejected requirement is not in the last result, but its entry
+    holds its anchors, so it can still be recognised."""
+    by_id = {e.id: e for e in entries}
+    known = [Known(r.id, requirement_anchors(r), r.review != "unreviewed" or r.id in by_id) for r in previous]
+    seen = {k.id for k in known}
+    return known + [Known(e.id, frozenset(map(tuple, e.anchors)), True) for e in entries if e.id not in seen]
+
+
+def apply_review(requirements: list[Requirement], previous: list[Requirement],
+                 entries: list[ReviewEntry]) -> ReviewOutcome:
+    carries = carry_ids([(r.id, requirement_anchors(r)) for r in requirements], _known(previous, entries))
+    by_id = {e.id: e for e in entries}              # a later entry for the same id wins
+    summary = ReviewSummary(carried=sum(c.carried for c in carries))
+    summary.new = len(requirements) - summary.carried
+    matched: set[str] = set()
+    out: list[Requirement] = []
+    hidden: list[Requirement] = []
+    for requirement, carry in zip(requirements, carries):
+        requirement = requirement.model_copy(update={"id": carry.id})
+        entry = by_id.get(carry.id)
+        if entry is not None:
+            matched.add(entry.id)
+        if carry.ambiguous_reviewed:
+            out.append(requirement.model_copy(update={"review": "needs_review"}))
+        elif entry is None:
+            out.append(requirement)
+        else:
+            outcome = decide(entry, requirement_anchors(requirement))
+            if outcome == "rejected":
+                summary.rejected_hidden += 1
+                hidden.append(requirement)
+            elif outcome == "needs_review":
+                out.append(requirement.model_copy(update={"review": "needs_review"}))
+            elif outcome == "confirmed":
+                out.append(requirement.model_copy(update={"review": "confirmed"}))
+            else:
+                update: dict = {"review": "edited"}
+                if entry.statement is not None:
+                    update["statement"] = entry.statement
+                if entry.conditions is not None:
+                    update["conditions"] = list(entry.conditions)
+                out.append(requirement.model_copy(update=update))
+    summary.confirmed = sum(r.review == "confirmed" for r in out)
+    summary.edited = sum(r.review == "edited" for r in out)
+    summary.needs_review = sum(r.review == "needs_review" for r in out)
+    summary.stale_entries = list(dict.fromkeys(e.id for e in entries if e.id not in matched))
+    return ReviewOutcome(out, summary, hidden)
+
+
+def record(store: ReviewStorePort, requirements: list[Requirement], requirement_id: str, decision: Decision, *,
+           statement: str | None, conditions: list[str] | None, reviewer: str, date: str,
+           note: str | None) -> ReviewEntry:
+    """Write or replace the entry for a requirement, copying its anchors from `requirements`."""
+    found = next((r for r in requirements if r.id == requirement_id), None)
+    if found is None:
+        raise UnknownRequirement(requirement_id)
+    entry = ReviewEntry(id=requirement_id, decision=decision, statement=statement, conditions=conditions,
+                        reviewer=reviewer, date=date, note=note,
+                        anchors=sorted(requirement_anchors(found)))
+    entries = store.load()
+    if any(e.id == requirement_id for e in entries):
+        entries = [entry if e.id == requirement_id else e for e in entries]
+    else:
+        entries.append(entry)
+    store.save(entries)
+    return entry

backspec/modules/staleness/domain.py

@@ -0,0 +1,75 @@
+"""Staleness: whether the files a result rests on are still what was read.
+
+A file is `unchanged`, `changed` or `missing`. A requirement is `current` when every file it
+cites is unchanged, `source_missing` when any is missing, and otherwise `stale`. No model is
+involved: it is a comparison of hashes.
+"""
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from backspec.kernel.text import sha256
+
+FileState = Literal["unchanged", "changed", "missing"]
+RequirementState = Literal["current", "stale", "source_missing"]
+
+
+def hash_of(data: bytes) -> str | None:
+    """The hash of a file as discovery takes it: of the decoded text. None when the file can no
+    longer be read as text."""
+    if b"\x00" in data[:8192]:
+        return None
+    try:
+        return sha256(data.decode("utf-8"))
+    except UnicodeDecodeError:
+        return None
+
+
+def classify_file(recorded: str | None, current: str | None) -> FileState:
+    if current is None:
+        return "missing"
+    return "unchanged" if recorded == current else "changed"
+
+
+def classify_requirement(states: dict[str, FileState]) -> RequirementState:
+    values = set(states.values())
+    if "missing" in values:
+        return "source_missing"
+    return "stale" if "changed" in values else "current"
+
+
+class RequirementStatus(BaseModel):
+    id: str
+    capability: str
+    statement: str
+    status: RequirementState
+    changed: list[str] = Field(default_factory=list)
+    missing: list[str] = Field(default_factory=list)
+
+
+class StatusReport(BaseModel):
+    counts: dict[str, int]
+    changed_files: list[str] = Field(default_factory=list)
+    missing_files: list[str] = Field(default_factory=list)
+    requirements: list[RequirementStatus] = Field(default_factory=list)
+
+    @property
+    def all_current(self) -> bool:
+        return not self.changed_files and not self.missing_files and \
+            all(r.status == "current" for r in self.requirements)
+
+
+def summary(report: StatusReport) -> str:
+    """The short human form: a line of counts, then each requirement that is not current."""
+    counts = report.counts
+    lines = [f"{counts.get('current', 0)} current, {counts.get('stale', 0)} stale, "
+             f"{counts.get('source_missing', 0)} source_missing"]
+    for item in report.requirements:
+        if item.status == "current":
+            continue
+        lines.append(f"{item.status}  {item.id}  {item.statement}")
+        lines += [f"    changed  {path}" for path in item.changed]
+        lines += [f"    missing  {path}" for path in item.missing]
+    return "\n".join(lines)

backspec/modules/staleness/facade.py

@@ -0,0 +1,17 @@
+"""Staleness, as the rest of backspec sees it."""
+from __future__ import annotations
+
+from backspec.modules.report.facade import ExtractionResult
+from backspec.modules.staleness.domain import RequirementStatus, StatusReport, summary
+from backspec.modules.staleness.ports import RepoPort
+from backspec.modules.staleness.use_cases import check
+
+__all__ = ["RepoPort", "RequirementStatus", "StalenessFacade", "StatusReport", "summary"]
+
+
+class StalenessFacade:
+    def __init__(self, repo: RepoPort):
+        self._repo = repo
+
+    def check(self, result: ExtractionResult) -> StatusReport:
+        return check(result, self._repo)

backspec/modules/staleness/ports.py

@@ -0,0 +1,7 @@
+"""What staleness needs from the outside world: reading a file by relative path. This is
+discovery's `RepoPort`; only its `read` is used."""
+from __future__ import annotations
+
+from backspec.modules.discovery.facade import RepoPort
+
+__all__ = ["RepoPort"]

backspec/modules/staleness/use_cases.py

@@ -0,0 +1,39 @@
+"""Compare a saved result with the repository as it is now."""
+from __future__ import annotations
+
+from backspec.modules.report.facade import ExtractionResult
+from backspec.modules.staleness.domain import (FileState, RequirementStatus, StatusReport, classify_file,
+                                           classify_requirement, hash_of)
+from backspec.modules.staleness.ports import RepoPort
+
+
+def _current_hash(repo: RepoPort, path: str) -> str | None:
+    try:
+        return hash_of(repo.read(path))
+    except (OSError, ValueError):
+        return None
+
+
+def check(result: ExtractionResult, repo: RepoPort) -> StatusReport:
+    recorded: dict[str, str] = {}
+    for observation in sorted(result.observations, key=lambda o: (o.path, o.id)):
+        recorded.setdefault(observation.path, observation.source_hash)
+    states: dict[str, FileState] = {
+        path: classify_file(recorded[path], _current_hash(repo, path)) for path in sorted(recorded)}
+
+    items: list[RequirementStatus] = []
+    for requirement in result.requirements:
+        cited = sorted({e.path for e in requirement.evidence})
+        # evidence that names a path no observation recorded cannot be confirmed: it counts as changed
+        mine = {path: states.get(path, "changed") for path in cited}
+        items.append(RequirementStatus(
+            id=requirement.id, capability=requirement.capability, statement=requirement.statement,
+            status=classify_requirement(mine),
+            changed=[p for p, s in mine.items() if s == "changed"],
+            missing=[p for p, s in mine.items() if s == "missing"]))
+    items.sort(key=lambda r: (r.capability, r.id))
+    counts = {name: sum(1 for r in items if r.status == name) for name in ("current", "stale", "source_missing")}
+    return StatusReport(counts=counts,
+                        changed_files=[p for p, s in states.items() if s == "changed"],
+                        missing_files=[p for p, s in states.items() if s == "missing"],
+                        requirements=items)