luria 0.1.0__py3-none-any.whl

luria/__init__.py

@@ -0,0 +1,11 @@
+"""Luria — a project's memory, kept where the next collaborator will find it.
+
+The four layers (design principles, decisions, changelog, devlog), the fragment
+convention that keeps them conflict-free, the generated views, and the lint that
+stops all of it from drifting.
+
+Public surface is the CLI (`luria --help`); the modules are importable for
+projects that want to extend a check rather than replace it.
+"""
+
+__version__ = "0.1.0"

luria/adr_index.py

@@ -0,0 +1,400 @@
+#!/usr/bin/env python3
+"""`luria index` — render every scheme's view from its fragments.
+
+    luria index            # write the views
+    luria index --check    # exit 1 if any of them is stale
+
+A scheme's view used to be hand-maintained: every decision-bearing branch
+appended a row to the same table and a link to the same category list. That
+makes it the shared-file lock [DP-2](../docs/design-principles.md#dp-2) names,
+and it *drifts*, because the row duplicates data the document already owns — in
+the corpus this was extracted from, 45 of 155 rows disagreed with their own
+decision's status (ADR-004).
+
+So the view is generated. Each document carries YAML frontmatter, and a scheme
+declares how its documents are rendered (ADR-012):
+
+  render = "index"      the browsable shape — a table plus per-tag pages
+      docs/decisions/README.md        stub prose + category lists + the table
+      docs/decisions/tags/<tag>.md    one page per tag
+      (sources in record/decisions.d/ — the view directory holds only what
+       this generator wrote, which is what lets the lint call anything else
+       in it an error, ADR-021)
+
+  render = "document"   the read-as-a-whole shape — bodies concatenated
+      docs/design-principles.md       stub prose + every principle in order
+
+Adding a document means adding ONE file. Adding a *tag* means using it in one;
+`tags.yaml` only supplies ordering and a blurb, so an unlisted tag still renders.
+
+`--check` is what makes idempotency enforceable: `luria lint` runs it, so a stale
+view is a lint failure rather than a silent divergence — which only works because
+a generated view's sources persist, unlike a collected one's (ADR-012).
+
+The stub/placeholder shape is borrowed from dmarx/bench-warmers, which solved
+the same problem for a brainstorming repo: prose lives in a `.stub`, the
+generator substitutes `{placeholders}`, and tags get their own generated pages.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os.path
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+from .config import current
+
+TITLE_RE = re.compile(r"^#\s*[A-Z]+-\d+\s*(?::|—|-)\s*")
+TABLE_HEAD = "| # | Title | Status |\n|---|---|---|\n"
+
+# Used when a project has no `README.stub`. The stub exists so prose lives in
+# markdown rather than in this generator; not having written one yet shouldn't
+# stop the index from building.
+DEFAULT_DOCUMENT_STUB = """# Design principles
+
+<!-- GENERATED by `luria index` — edit the fragments, not this file. -->
+
+{principles}
+"""
+
+DEFAULT_STUB = """# Architecture decision records
+
+<!-- GENERATED below this line by `luria index` — edit README.stub instead. -->
+
+{categories}
+
+{table}
+"""
+
+# A markdown link with a *relative* target: not an anchor, not root-relative,
+# not a URL scheme. Those are the only ones a change of output directory moves.
+RELATIVE_LINK_RE = re.compile(r"(?<=\]\()(?![#/]|[A-Za-z][A-Za-z0-9+.-]*:)([^)\s]+)")
+
+
+def rebase_links(text: str, prefix: str) -> str:
+    """Rewrite relative link targets in `text` for an output `prefix` away.
+
+    Summaries are authored relative to the scheme's *source* directory — the
+    same base as the ADR body they were lifted from — and this index renders
+    them into the view directory and again one level down in `tags/<tag>.md`.
+    Owning the rendering is what lets a summary carry links at all: without
+    this, no single relative target could be correct everywhere (ADR-005)."""
+    if not prefix:
+        return text
+    return RELATIVE_LINK_RE.sub(lambda m: prefix + m.group(1), text)
+
+
+def prefix_for(scheme, out_dir: Path) -> str:
+    """The rebase prefix for text authored in `scheme.dir`, rendered into
+    `out_dir`. "" when they are the same place — the collocated layout — so
+    the old output is byte-identical where nothing moved."""
+    rel = os.path.relpath(scheme.dir, out_dir)
+    return "" if rel == "." else rel + "/"
+
+
+def parse_frontmatter(text: str) -> tuple[dict, str]:
+    """Split leading `---` YAML frontmatter from the body. Missing frontmatter
+    yields an empty dict so a half-migrated tree still renders — lint reports
+    the omission rather than the build crashing on it."""
+    if not text.startswith("---\n"):
+        return {}, text
+    end = text.find("\n---\n", 3)
+    if end == -1:
+        return {}, text
+    return yaml.safe_load(text[4 : end + 1]) or {}, text[end + 5 :]
+
+
+class Adr:
+    def __init__(self, path: Path, scheme=None):
+        scheme = scheme or current().schemes["ADR"]
+        self.path = path
+        self.scheme = scheme
+        self.prefix = scheme.prefix
+        self.number = scheme.number_of(path)
+        self.meta, body = parse_frontmatter(path.read_text())
+        # `title:` is the source of truth; the body's H1 is the fallback, so a
+        # document written before the field existed — or in a project that
+        # hasn't adopted it — still renders a title rather than a blank cell
+        # (ADR-013).
+        first = next((ln for ln in body.splitlines() if ln.startswith("#")), "")
+        self.heading = TITLE_RE.sub("", first).strip()
+        self.title = str(self.meta.get("title") or "").strip() or self.heading
+
+    @property
+    def code(self) -> str:
+        return f"{self.prefix}-{self.number:03d}"
+
+    @property
+    def status(self) -> str:
+        return str(self.meta.get("status", "")).strip()
+
+    @property
+    def tags(self) -> list[str]:
+        return [str(t).strip().lower() for t in (self.meta.get("tags") or [])]
+
+    def cell(self, prefix: str = "") -> str:
+        """The table's middle column: the summary when there is one, else the
+        title. A row has always been one blob, not a title plus a description —
+        keeping that shape is what made the migration byte-identical.
+
+        A summary may carry relative links, written — like the ADR's body —
+        relative to the scheme's source directory. `prefix` rebases them for
+        output that renders somewhere else (ADR-005); it is the same prefix
+        the row's own ADR link already took."""
+        return rebase_links(str(self.meta.get("summary") or self.title).strip(), prefix)
+
+    @property
+    def version(self) -> int:
+        """Which revision of this document's claim you are reading.
+
+        Standard frontmatter for every scheme (ADR-016), not just principles.
+        A decision is superseded rather than rewritten, so its version moves
+        rarely — but "rarely" is not "never": a decision whose *scope* widens
+        without its choice changing is a revision, and that is exactly the case
+        a reader needs told apart from a fresh decision."""
+        return int(self.meta.get("version", 1) or 1)
+
+    @property
+    def influenced_by(self) -> list[str]:
+        raw = self.meta.get("influenced_by") or []
+        return [str(x).strip() for x in raw]
+
+    def row(self, prefix: str = "") -> str:
+        # unresolved-ok-block: ADR-100 — a stand-in number in the example below
+        # Every rendered field is rebased, not just the ADR's own link: a
+        # "Superseded — by [ADR-100](…)" note is prose too, and its link was
+        # silently broken on the tag pages (four of them) until this existed.
+        #
+        # The version is shown only when it isn't 1. A column of 1s teaches
+        # nothing; the field exists so a document that HAS been revised says so
+        # where it is read (ADR-016).
+        version = f" v{self.version}" if self.version > 1 else ""
+        return (f"| [{self.code}]({prefix}{self.path.name}){version} "
+                f"| {self.cell(prefix)} | {rebase_links(self.status, prefix)} |")
+
+
+def load_adrs() -> list[Adr]:
+    """The ADR scheme's documents. Kept as its own name because the pending
+    report is about decisions specifically, not about every scheme."""
+    return load_scheme(current().schemes["ADR"])
+
+
+def load_scheme(scheme) -> list[Adr]:
+    return [Adr(p, scheme) for p in scheme.documents().values()]
+
+
+def tag_order(adrs: list[Adr], scheme=None) -> list[tuple[str, dict]]:
+    """Declared tags first, in tags.yaml order; then any undeclared tag an ADR
+    actually uses, alphabetically. Using a new tag must never require a code
+    change — that's the whole point of pushing categories down onto the ADRs."""
+    tags_file = scheme.tags_yaml if scheme else current().tags_yaml
+    declared = yaml.safe_load(tags_file.read_text()) if tags_file.exists() else {}
+    declared = declared or {}
+    used = {t for a in adrs for t in a.tags}
+    ordered = [(t, declared[t] or {}) for t in declared if t in used]
+    ordered += [(t, {}) for t in sorted(used - set(declared))]
+    return ordered
+
+
+def render_categories(adrs: list[Adr], tags: list[tuple[str, dict]],
+                      prefix: str = "") -> str:
+    blocks = []
+    for tag, meta in tags:
+        listed = [a for a in adrs if tag in a.tags]
+        label = meta.get("label", tag.title())
+        blurb = f" — {meta['blurb']}" if meta.get("blurb") else ""
+        links = " · ".join(f"[{a.number:03d}]({prefix}{a.path.name})" for a in listed)
+        blocks.append(f"**[{label}](tags/{tag}.md)** ({len(listed)}){blurb}:\n{links}")
+    return "\n\n".join(blocks)
+
+
+def render_index(adrs: list[Adr], tags: list[tuple[str, dict]],
+                 scheme=None) -> str:
+    scheme = scheme or current().schemes["ADR"]
+    prefix = prefix_for(scheme, scheme.view)
+    table = TABLE_HEAD + "\n".join(a.row(prefix) for a in adrs) + "\n"
+    stub = scheme.stub
+    prose = stub.read_text() if stub.exists() else DEFAULT_STUB
+    return (prose.replace("{categories}", render_categories(adrs, tags, prefix))
+                 .replace("{table}", table))
+
+
+def render_tag_page(tag: str, meta: dict, adrs: list[Adr],
+                    scheme=None) -> str:
+    scheme = scheme or current().schemes["ADR"]
+    prefix = prefix_for(scheme, scheme.tag_dir)
+    label = meta.get("label", tag.title())
+    listed = [a for a in adrs if tag in a.tags]
+    blurb = f"\n{meta['blurb'].capitalize()}.\n" if meta.get("blurb") else ""
+    return (
+        f"<!-- GENERATED by `luria index` — do not edit. -->\n\n"
+        f"# ADRs tagged `{tag}`\n"
+        f"{blurb}\n"
+        f"{len(listed)} of {len(adrs)} decisions. Back to the [full index](../README.md).\n\n"
+        + TABLE_HEAD
+        + "\n".join(a.row(prefix=prefix) for a in listed)
+        + "\n"
+    )
+
+
+def render_document(scheme, docs: list[Adr]) -> str:
+    """Every document's body, in number order, as one page.
+
+    The right shape when the set is read *as a whole* rather than browsed one at
+    a time — which is what a principles document is: people cite "DP-3" and then
+    read it in the context of its neighbours. The metadata line is what the
+    fragment frontmatter buys: a version, so a revised principle says so
+    (ADR-012), and the decisions whose experience produced it."""
+    stub = scheme.stub
+    head = stub.read_text() if stub.exists() else DEFAULT_DOCUMENT_STUB
+    base = scheme.output.parent if scheme.output else scheme.dir
+    parts = []
+    for doc in docs:
+        body = parse_frontmatter(doc.path.read_text())[1].strip()
+        # Demote the fragment's own H1 to the assembled document's H2, and
+        # renumber it into the reader's numbering rather than the file's code.
+        body = re.sub(r"^#\s*[A-Z]+-\d+\s*(?::|—|-)\s*",
+                      f"## {doc.number}. ", body, count=1)
+        # A stable anchor, because the heading is not one. A principle is a
+        # living document — two of the eight here have been reworded already —
+        # and a heading-derived anchor stops resolving the moment the wording
+        # moves, silently, which is the fail-stale polarity DP-3 rules out.
+        # This one is keyed to the number, which is the thing that never moves.
+        body = f'<a name="{doc.prefix.lower()}-{doc.number}"></a>\n\n{body}'
+        meta = [f"*v{doc.version}"]
+        if doc.influenced_by:
+            meta.append("shaped by " + ", ".join(
+                f"[{code}]({target})" if (target := _link(code, base)) else code
+                for code in doc.influenced_by))
+        if doc.status != scheme.active:
+            meta.append(f"**{doc.status}**")
+        if origin := str(doc.meta.get("origin", "")).strip():
+            meta.append(f"origin: {origin.rstrip('.')}")
+        parts.append(f"{body}\n\n{' · '.join(meta)}*")
+    return head.replace("{principles}", "\n\n".join(parts))
+
+
+def _link(code: str, base: Path) -> str:
+    """`ADR-004` → a link to that decision, relative to `base`.
+
+    Relative to *where the text renders*, not where the fragment lives — the
+    same rule the reference fixer follows for anything assembled elsewhere
+    (ADR-005). An unresolvable code yields "", and the caller renders the bare
+    code rather than a link to nothing (DP-1: say what you can, don't invent)."""
+    try:
+        prefix, number = code.split("-")
+        path = current().schemes[prefix.upper()].documents().get(int(number))
+    except (ValueError, KeyError):
+        return ""
+    return os.path.relpath(path, base) if path else ""
+
+
+def view_dirs() -> list[Path]:
+    """Every directory the generator owns outright. Anything in one of these
+    it didn't render is an orphan — a stale tag page, a book from an old
+    granularity, or a hand-written file that will read as generated (ADR-021).
+    A collocated scheme (no separate `output`) contributes only its tag dir,
+    because its view directory also holds the sources."""
+    cfg = current()
+    dirs: list[Path] = []
+    for s in cfg.schemes.values():
+        if s.render != "index":
+            continue
+        dirs.append(s.tag_dir)
+        if s.view != s.dir:
+            dirs.append(s.view)
+    dirs += [j.output for j in cfg.journals.values()]
+    return dirs
+
+
+def orphans(rendered: dict[Path, str]) -> list[Path]:
+    return [p for d in view_dirs() if d.is_dir()
+            for p in sorted(d.glob("*.md")) if p not in rendered]
+
+
+def _render_scheme(scheme) -> dict[Path, str]:
+    docs = load_scheme(scheme)
+    if scheme.render == "document":
+        return {scheme.output: render_document(scheme, docs)} if scheme.output else {}
+    tags = tag_order(docs, scheme)
+    out = {scheme.index_path: render_index(docs, tags, scheme)}
+    for tag, meta in tags:
+        out[scheme.tag_dir / f"{tag}.md"] = render_tag_page(tag, meta, docs, scheme)
+    return out
+
+
+def outputs() -> dict[Path, str]:
+    """Every generated view, across every scheme — one place, so the lint's
+    staleness check covers a new scheme the moment it is configured.
+
+    Rendered wide (ADR-026): each scheme and each journal is an independent
+    pure function of the tree, so they run as parallel units. `pmap` returns
+    in input order, which is what keeps the merged dict — and therefore the
+    staleness diff — deterministic."""
+    from . import journal
+    from .parallel import pmap
+    cfg = current()
+    units = [lambda s=s: _render_scheme(s) for s in cfg.schemes.values()]
+    units += [lambda j=j: journal.outputs_for(j) for j in cfg.journals.values()]
+    out: dict[Path, str] = {}
+    for rendered in pmap(lambda u: u(), units):
+        out.update(rendered)
+    return out
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--check", action="store_true", help="exit 1 if anything is stale")
+    args = ap.parse_args()
+
+    rendered = outputs()
+    if args.check:
+        stale = [p for p, text in rendered.items()
+                 if not p.exists() or p.read_text() != text]
+        # Anything in a view directory the generator didn't render is stale
+        # too — a tag page whose tag is gone, a book from an old granularity.
+        stale += orphans(rendered)
+        from . import badges
+        readme = badges.readme()
+        if readme.exists() and badges.OPEN in (text := readme.read_text()) \
+                and badges.rewrite(text) != text:
+            stale.append(readme)
+        if stale:
+            print("stale (run `luria index`):", file=sys.stderr)
+            for p in sorted(stale):
+                print(f"  {current().rel(p)}", file=sys.stderr)
+            return 1
+        print("luria index: current")
+        return 0
+
+    cfg = current()
+    for stale_file in orphans(rendered):
+        stale_file.unlink()
+    for p, text in rendered.items():
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(text)
+    # Name every scheme, not just the decisions: a project that adds one wants
+    # to see it counted, and a scheme silently rendering nothing is the failure
+    # this line exists to make visible (DP-1).
+    from . import journal
+    filed = {n: len(journal.entries(j)) for n, j in sorted(cfg.journals.items())}
+    counted = ", ".join(
+        [f"{len(load_scheme(s))} {p}s" for p, s in sorted(cfg.schemes.items())]
+        + [f"{c} {n} entr{'y' if c == 1 else 'ies'}" for n, c in filed.items()])
+    print(f"Wrote {len(rendered)} file(s) from {counted}.")
+    # The README's badge counts are derived from the same frontmatter, so they
+    # are regenerated here rather than by a command someone has to remember
+    # (ADR-018). A project with no badge region is left alone.
+    from . import badges
+    readme = badges.readme()
+    if readme.exists() and badges.OPEN in (text := readme.read_text()):
+        readme.write_text(badges.rewrite(text))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

luria/adr_pending.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""Report ADRs still awaiting a decision, oldest first (ADR-007).
+
+    luria pending                     # the table
+    luria pending --stale-days 30     # a tighter "overdue" line
+    luria pending --as-of 2026-08-03  # fixed clock, for tests
+
+`Proposed` and `Deferred` are the two statuses that describe an *open* question:
+"we haven't decided" and "we decided not to decide yet". Both are legitimate —
+[ADR-003](../record/decisions.d/ADR-003.md) added `Deferred` precisely
+so postponement could be stated rather than faked. What neither status records is
+*how long*, and that is the whole signal: a decision proposed a week ago is
+pending, the same one a year later is either overdue or was quietly settled in
+code and never written down. The status field can't drift toward the truth on its
+own, because nothing about "still Proposed" ever fails.
+
+So the report supplies the missing axis — age — and one more that turns a list
+into a priority: how often the ADR is cited. An old proposal nothing references
+is a stalled idea; an old proposal 32 files cite is a decision the codebase has
+already made without saying so.
+
+The count here is every citation, acknowledged or not, because an acknowledged
+one still means the codebase depends on the answer. `make ref-status` lists only
+the unacknowledged ones, so its total is smaller — the headline names both so
+the two reports visibly reconcile.
+
+Like the non-Active reference report this ships beside, it warns and never
+fails. An ADR can be legitimately open for a long time; only a human can say
+which of these is overdue.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import adr_index as builder
+from . import ref_status
+from .config import current
+
+UNDECIDED = ("Proposed", "Deferred")
+DEFAULT_STALE_DAYS = 90
+
+
+@dataclass(frozen=True)
+class Pending:
+    code: str                # `ADR-012`, `DP-004` — every scheme, not just one
+    number: int
+    status: str
+    title: str
+    date: dt.date | None
+    cites: int
+    unacknowledged: int      # of those, the ones `make ref-status` still lists
+    path: Path
+
+    def age(self, today: dt.date) -> int | None:
+        return None if self.date is None else (today - self.date).days
+
+    def is_stale(self, today: dt.date, stale_days: int) -> bool:
+        age = self.age(today)
+        return age is not None and age >= stale_days
+
+
+def _date(meta: dict) -> dt.date | None:
+    raw = meta.get("date")
+    if isinstance(raw, dt.date):
+        return raw
+    try:
+        return dt.date.fromisoformat(str(raw))
+    except (TypeError, ValueError):
+        return None
+
+
+def pending() -> list[Pending]:
+    """Every undecided document in every scheme, oldest first; undated ones
+    last — a document with no `date:` can't be aged, which is itself worth
+    seeing.
+
+    Not just decisions. A `Proposed` principle is an open question in exactly
+    the same way, and a report that covered one scheme would go quietly blind
+    the day a project configured a second (ADR-018)."""
+    cited = ref_status.scan().cited
+    rows = []
+    for scheme in current().schemes.values():
+        for doc in builder.load_scheme(scheme):
+            status = re.split(r"\s+—\s+", doc.status, maxsplit=1)[0]
+            if status not in UNDECIDED:
+                continue
+            sites = cited.get(doc.code, [])
+            rows.append(Pending(doc.code, doc.number, status, doc.title,
+                                _date(doc.meta), len(sites),
+                                sum(1 for c in sites if c.excused_by is None),
+                                doc.path))
+    return sorted(rows, key=lambda r: (r.date is None, r.date, -r.cites, r.code))
+
+
+def table(rows: list[Pending], today: dt.date, stale_days: int) -> list[str]:
+    if not rows:
+        return []
+    width = max(len(r.title) for r in rows)
+    code_width = max(len(r.code) for r in rows)
+    lines = [f"{'age':>6}  {'status':<8}  {'code':<{code_width}}  "
+             f"{'cites':>5}  title"]
+    for r in rows:
+        age = r.age(today)
+        mark = "!" if r.is_stale(today, stale_days) else " "
+        lines.append(
+            f"{(f'{age}d' if age is not None else '?'):>6}{mark} {r.status:<8}  "
+            f"{r.code:<{code_width}}  {r.cites:>5}  {r.title[:width]}"
+        )
+    return lines
+
+
+def headline(rows: list[Pending], today: dt.date, stale_days: int) -> str:
+    if not rows:
+        return "pending decisions: none — every document is decided"
+    ages = [a for a in (r.age(today) for r in rows) if a is not None]
+    stale = sum(1 for r in rows if r.is_stale(today, stale_days))
+    undated = sum(1 for r in rows if r.date is None)
+    loud = sum(1 for r in rows if r.unacknowledged)
+    parts = [f"{len(rows)} undecided document(s)"]
+    if ages:
+        parts.append(f"oldest {max(ages)} days")
+    if stale:
+        parts.append(f"{stale} over {stale_days} days")
+    if undated:
+        parts.append(f"{undated} undated")
+    # Printed next to the reference report's count, these two look like an
+    # off-by-one and are not: that report only lists documents with an
+    # UNACKNOWLEDGED citation, which is exactly this number.
+    if loud != len(rows):
+        parts.append(f"{loud} with unacknowledged references")
+    return "pending decisions: " + ", ".join(parts)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--stale-days", type=int, default=current().stale_days,
+                    help="flag rows at least this old")
+    ap.add_argument("--as-of", help="treat this ISO date as today")
+    args = ap.parse_args()
+
+    today = dt.date.fromisoformat(args.as_of) if args.as_of else dt.date.today()
+    rows = pending()
+    print(headline(rows, today, args.stale_days), file=sys.stderr)
+    for line in table(rows, today, args.stale_days):
+        print(f"  {line}", file=sys.stderr)
+    return 0            # a report, not a gate
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())