constant-docs 0.4.0__py3-none-any.whl

constant_docs/prompts/errors.md

@@ -0,0 +1,50 @@
+Read the source files this document covers, then write its body.
+
+An error catalogue answers *"the tool said this; what now"*. Its reader has a
+message in front of them and no interest in how the code is arranged.
+
+Output the body only: three H2 sections, in this order, nothing before or
+after, no code fences around the whole thing. Do not write an H1 — the
+document's title is a frontmatter key, not a heading.
+
+## Purpose
+
+What raises, in one paragraph: which exception types exist, what each means as
+a class of problem, and which exit code a reader will have seen. Three to five
+sentences.
+
+## The catalogue
+
+A table: message, cause, what to do. One row per message the tool can emit.
+
+**The first cell is a verbatim fragment of the message, in backticks.** It is
+checked against the source in both directions — every message raised must be
+carried by some row, and every row must match a message that is still raised —
+so choose a fragment that is literal rather than interpolated:
+
+    | `is already declared` | A module of that name exists | Edit its entry |
+
+Not `` `Module 'src/api' is already declared` ``: the name is substituted at
+runtime and no such string exists in the source. Take the longest run of
+literal words you can, and no more.
+
+Group rows under H3 subheadings when there are many — by exception type, or by
+the command a reader was running. The check reads the first column of every
+table wherever it sits.
+
+## What is not an error
+
+The places the tool deliberately says nothing: silent exits, refusals that are
+not failures, warnings that do not change an exit code. A reader who cannot
+tell "nothing happened" from "nothing was wrong" will conclude the tool is
+broken, and this section is the only place that distinction is written down.
+
+Rules:
+
+- Every row's fragment must appear verbatim in the files given. A row that
+  matches nothing is refused, and so is a message no row carries.
+- Write the cause as what the *user* did, not as which branch was taken.
+- "What to do" must be an action. "Fix the configuration" is not one.
+- When a previous body is supplied, edit it. Most changes add or remove one
+  row.
+- Plain British English. No preamble, no summary of what you did.

constant_docs/prompts/log.md

@@ -0,0 +1,22 @@
+Read the files this log covers, then write **one entry** describing what
+changed since the last one.
+
+A log is not regenerable. Everything already written stays exactly as it is,
+and you are adding to the end. Write the entry body only — no heading, no
+frontmatter, no restatement of earlier entries. The tool adds the heading:
+entries sit inside the `## Entries` section, so each is an H3.
+
+What an entry carries:
+
+- What changed, in the terms someone reading it in six months would use.
+- Why, when the reason is not obvious from the change itself.
+- What it breaks, if anything, and what a reader must do about it.
+
+Rules:
+
+- The previous entries are supplied for context. Do not repeat them, do not
+  summarise them, and do not correct them — a correction is a new entry.
+- Only changes you can locate in the files given. An entry that describes work
+  that did not happen is worse than no entry.
+- Two to six sentences, or a short list. Length is not thoroughness.
+- Plain British English. No preamble, no summary of what you did.

constant_docs/prompts/module.md

@@ -0,0 +1,39 @@
+Read the module's source files, then write its document body.
+
+Write for someone who did not write this code and has to decide whether to
+trust it. An agent will also load it, so keep sections short and independently
+readable. Where the two conflict, favour the person.
+
+Output the body only: three H2 sections, in this order, nothing before or
+after, no code fences around the whole thing. Do not write an H1 — the
+document's title is a frontmatter key, not a heading.
+
+## Purpose
+
+What the module owns and what callers get from it. Name what is deliberately
+hidden behind the interface. Two to five sentences. Do not list functions.
+
+## Correctness pillars
+
+Rules a caller must follow that a signature does not express. EARS form, one
+per paragraph, so that each maps to a test:
+
+    WHEN <trigger>, the module SHALL <required behaviour>.
+
+Only rules you can point to in the source. Three to six is typical.
+
+## Known failure modes
+
+A table of symptom, cause, and fix. Only failures visible in this code:
+unhandled edge cases, ordering assumptions, silent truncation, retries that
+lose data. Leave the table empty rather than inventing entries.
+
+Rules:
+
+- Never restate a signature, a parameter list, or an import. The reader has
+  the source. A section that paraphrases the code is a defect.
+- Never claim behaviour you cannot locate in the files given. Uncertainty is
+  omitted, not hedged.
+- When a previous body is supplied, edit it. Keep wording that is still
+  accurate and change only what the source change affected.
+- Plain British English. No preamble, no summary of what you did.

constant_docs/prompts/spec.md

@@ -0,0 +1,68 @@
+Read the files this specification covers, then write its document body.
+
+A specification states what a subsystem promises and why, for a reader
+deciding whether to depend on it. It is not a description of the code as
+written — where the two disagree, say so rather than documenting the drift
+into permanence.
+
+Output the body only: three H2 sections, in this order, nothing before or
+after, no code fences around the whole thing. Do not write an H1 — the
+document's title is a frontmatter key, not a heading.
+
+## Purpose
+
+What this subsystem promises and to whom. Name the boundary: what is inside
+it, what is deliberately outside, and what a caller may rely on. Three to six
+sentences.
+
+## Design decisions
+
+Choices that are settled, each with the reason it was settled that way. A
+table of decision and rationale, or one short paragraph each. Record the
+reason, not the mechanism — a reader who disagrees with a decision needs to
+know what it bought.
+
+Every decision carries a stable identifier, written as an HTML comment at the
+start of the decision so it renders as nothing:
+
+    | <!-- decision: no-model-client --> Never call a model | The harness … |
+
+**Carry every identifier the previous body had.** The tool compares the two
+and refuses a body that drops one, naming it. Rewording, reordering,
+sharpening and merging the *prose* are all free — the identifier is what has
+to survive, not the sentence.
+
+Three ways to lose one by accident, each of which is refused:
+
+- renaming an identifier, even to a better name. Keep the old slug; it is a
+  key, not a title
+- keeping the identifier and emptying the decision, which a table row gutted
+  to `| | |` does
+- merging two decisions into one, which drops the identifier of whichever was
+  absorbed
+
+If a decision genuinely no longer holds, say so and stop rather than deleting
+it. Retiring one is a deliberate act recorded in the document, and it is the
+caller's to make, not yours.
+
+Give a new decision an identifier too: lowercase, hyphenated, naming the
+decision rather than its rationale.
+
+## Acceptance criteria
+
+Numbered statements in EARS form, each mapping to at least one test:
+
+    WHEN <trigger>, the system SHALL <required behaviour>.
+
+Only criteria you can point to in the files given. Number them, because they
+are cited by number elsewhere.
+
+Rules:
+
+- When a previous body is supplied, edit it. A specification accumulates
+  authority; rewriting it from scratch discards the decisions it records.
+- Never claim behaviour you cannot locate in the files given. Uncertainty is
+  omitted, not hedged.
+- If the source contradicts a decision already written down, say so plainly in
+  the relevant section rather than quietly rewording it.
+- Plain British English. No preamble, no summary of what you did.

constant_docs/state.py

@@ -0,0 +1,273 @@
+"""The dirty set: which modules were touched, surviving a crash.
+
+The harness marks modules dirty on write and settles at quiescence. This
+module owns the file that carries the set between those two moments, at
+`.constant-docs/dirty.json`, which is gitignored.
+
+## When the set clears, and why it matters
+
+The tempting design is for `settle` to clear the set as it reports it. That is
+a silent hole: if the agent reads the plan and then fails to generate, the
+staleness is gone and nothing ever notices again — which is the one guarantee
+this tool sells.
+
+So the set clears in exactly two places:
+
+- On the `apply` or `append` that satisfies a module. Precise, per module, and
+  needs no cooperation: a harness that never heard of `settle` still leaves
+  the set consistent, and a partial generation clears only what it wrote
+- On a `settle` that finds a module **provably fresh**. A file edited and
+  edited back is dirty by the mark and fresh by the hash, and dropping it
+  loses nothing because there is demonstrably no work to do
+
+Nothing else clears it. A stale module that was read and not generated is
+still there on the next run, which is the crash-recovery case.
+
+## What this does not solve
+
+Two Claude Code sessions in one repository share this file and will race. The
+recovery reasoning above covers a dead session, not two live ones.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from contextlib import suppress
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from constant_docs.config import Declarations, declarations, effective_globs
+from constant_docs.document import replace_preserving_mode
+from constant_docs.globs import matches as glob_matches
+
+STATE_DIR = ".constant-docs"
+DIRTY_FILE = "dirty.json"
+FORMAT_VERSION = 1
+
+# How many times `settle` will block a Stop hook on an unchanged set before
+# getting out of the way. Claude Code documents no loop guard for `Stop`, so
+# an unguarded blocking hook is a hang. One retry, then step aside.
+MAX_BLOCKS = 2
+
+
+@dataclass
+class Dirty:
+    """The persisted set, plus what `settle` needs to avoid looping."""
+
+    modules: list[str] = field(default_factory=list)
+    # Signature of the last set `settle` blocked on, and how many times.
+    blocked_signature: str | None = None
+    blocked_count: int = 0
+
+
+def state_path(repo_root: Path) -> Path:
+    """Return the state file's path. Gitignored; see `.gitignore`."""
+    return repo_root / STATE_DIR / DIRTY_FILE
+
+
+def read(repo_root: Path) -> Dirty:
+    """Return the persisted set, or an empty one.
+
+    A file that cannot be read or parsed yields an empty set rather than an
+    error. This is recovery state, not a source of truth: `verify` still sees
+    every stale module whatever this file says, so losing it costs a turn of
+    automatic regeneration and nothing more.
+    """
+    path = state_path(repo_root)
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return Dirty()
+    if not isinstance(payload, dict) or payload.get("version") != FORMAT_VERSION:
+        return Dirty()
+    modules = payload.get("modules")
+    if not isinstance(modules, list):
+        return Dirty()
+    signature = payload.get("blocked_signature")
+    count = payload.get("blocked_count")
+    return Dirty(
+        modules=sorted({str(m) for m in modules}),
+        blocked_signature=str(signature) if isinstance(signature, str) else None,
+        blocked_count=count if isinstance(count, int) else 0,
+    )
+
+
+def write(repo_root: Path, dirty: Dirty) -> None:
+    """Persist the set atomically, in the same temp-then-rename discipline
+    documents use. A half-written state file would be read as empty on the
+    next run, which loses the turn's marks."""
+    path = state_path(repo_root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "version": FORMAT_VERSION,
+        "modules": sorted(set(dirty.modules)),
+        "blocked_signature": dirty.blocked_signature,
+        "blocked_count": dirty.blocked_count,
+    }
+    content = json.dumps(payload, indent=2) + "\n"
+
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=f".{DIRTY_FILE}.tmp.")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(content)
+        replace_preserving_mode(tmp, path)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+
+
+def modules_for_path(
+    decl: Declarations,
+    rel_posix: str,
+    patterns: dict[str, list[str]] | None = None,
+) -> list[str]:
+    """Return every module key whose glob covers *rel_posix*.
+
+    Pure string work: no filesystem access, so a file that has just been
+    deleted still marks the module that used to hold it.
+
+    Patterns come from `effective_globs`, the same function the resolver uses,
+    so a module that declares `covers` is marked when a file belonging to what
+    it covers is written. Without that, a cross-cutting document would go stale
+    and the hook would never say so — `verify` would still catch it in CI,
+    which is precisely the outcome the harness integration exists to avoid.
+
+    *patterns* lets a caller with many paths resolve `covers` once rather than
+    per path; it is the same mapping this computes when given none.
+    """
+    if _is_tool_output(decl, rel_posix) or _is_derived(rel_posix):
+        return []
+    if patterns is None:
+        patterns = effective_globs(decl.modules)
+    return [
+        mod.key
+        for mod in decl.modules
+        if any(glob_matches(pattern, rel_posix) for pattern in patterns[mod.key])
+    ]
+
+
+def mark(config_path: Path, paths: list[str]) -> list[str]:
+    """Add every module the given paths belong to, and return those keys.
+
+    Silent and empty when a path matches nothing. Most edits in a repository
+    touch no module, and a hook that errors on those is a hook someone
+    disables.
+    """
+    config_path = Path(config_path)
+    repo_root = config_path.resolve().parent
+    decl = declarations(config_path)
+
+    patterns = effective_globs(decl.modules)
+    hit: set[str] = set()
+    for raw in paths:
+        rel = _relative(repo_root, raw)
+        if rel is None:
+            continue
+        hit.update(modules_for_path(decl, rel, patterns))
+
+    if not hit:
+        return []
+
+    dirty = read(repo_root)
+    before = set(dirty.modules)
+    dirty.modules = sorted(before | hit)
+    if set(dirty.modules) != before:
+        write(repo_root, dirty)
+    return sorted(hit)
+
+
+def discard(repo_root: Path, module_key: str) -> None:
+    """Drop one module from the set, if it is there.
+
+    Called by the write that satisfies it. A module that was not dirty is not
+    an error: a caller may regenerate anything at any time.
+    """
+    dirty = read(repo_root)
+    if module_key not in dirty.modules:
+        return
+    dirty.modules = [m for m in dirty.modules if m != module_key]
+    write(repo_root, dirty)
+
+
+def clear(repo_root: Path) -> None:
+    """Empty the set, keeping the block counter intact."""
+    dirty = read(repo_root)
+    if not dirty.modules:
+        return
+    dirty.modules = []
+    write(repo_root, dirty)
+
+
+def _relative(repo_root: Path, raw: str) -> str | None:
+    """Return *raw* as a repository-relative POSIX path, or None if outside.
+
+    Accepts absolute and relative paths, because a hook is handed an absolute
+    one and a person at a shell types a relative one.
+    """
+    p = Path(raw)
+    if p.is_absolute():
+        try:
+            return p.resolve().relative_to(repo_root).as_posix()
+        except ValueError:
+            return None
+    # A relative path has two honest readings and the caller does not say
+    # which. A person at a shell means it relative to where they are, so from
+    # a subdirectory `mark core.py` must reach `src/payments/core.py`; a
+    # library caller and an agent writing a `file_path` mean it relative to the
+    # repository root, so `src/ledger/entries.py` must reach that and not
+    # `<cwd>/src/ledger/entries.py`. Preferring either one unconditionally gets
+    # the other wrong, and getting it wrong is silent: `mark` says nothing when
+    # nothing matches, and marks the wrong module when something else does.
+    from_cwd: str | None = None
+    with suppress(ValueError):
+        from_cwd = (Path.cwd() / p).resolve().relative_to(repo_root).as_posix()
+
+    normalised = Path(os.path.normpath(p.as_posix())).as_posix()
+    from_root: str | None = None if normalised.startswith("..") else normalised
+
+    if from_cwd is None or from_cwd == from_root:
+        return from_root
+    if from_root is None:
+        return from_cwd
+    # Both readings land inside the repository and disagree. One stat each
+    # settles it, and only here — the common cases above never touch the disk,
+    # so a hook handed an absolute path still costs nothing and a path that
+    # exists under neither reading still marks the module that used to hold it.
+    if (repo_root / from_cwd).exists():
+        return from_cwd
+    if (repo_root / from_root).exists():
+        return from_root
+    # Neither exists: the file was deleted, which is a case `mark` is required
+    # to handle. The repository-relative reading is the one a hook and a
+    # library caller give, and they are the high-volume callers.
+    return from_root
+
+
+def _is_tool_output(decl: Declarations, rel_posix: str) -> bool:
+    """True for anything this tool writes — its own output.
+
+    Without this, writing a document marks the module that document covers,
+    and the set never empties.
+
+    Everything under the docs root qualifies, and so does any document a
+    module declares outside it. The second is named rather than pruned by
+    prefix: a declared document is one file, not a directory, and the whole
+    point of declaring one is that it sits among files the tool does track.
+    """
+    parts = Path(rel_posix).parts
+    root = decl.docs_root.parts
+    if parts[: len(root)] == root:
+        return True
+    return any(mod.document == rel_posix for mod in decl.modules)
+
+
+# Kept in step with `config.DENIED_DIRS`; imported rather than restated so a
+# directory added there is refused here too.
+def _is_derived(rel_posix: str) -> bool:
+    from constant_docs.config import DENIED_DIRS, _is_denied
+
+    path = Path(rel_posix)
+    return bool(DENIED_DIRS.intersection(path.parts)) or _is_denied(path)