quirework 0.1.0__py3-none-any.whl

quirework/manuscript/editions.py

@@ -0,0 +1,111 @@
+"""Derived editions as the spec layer sees them: more units that answer to the spec.
+
+An edition is a directory under `publish.variants`, one per kind. Its
+documents sit at its top level, and each may keep a marks sidecar,
+`_marks/STEM.md` beside it, as a chapter does. A sidecar's `@bind` marks
+name the spec sections its document carries, and its `@omit` marks name
+the ones the edition leaves out and why. So one commitment can be followed
+from the chapter that states it to every edition that retells it.
+
+An edition's unit is named `KIND/STEM`. The poems' `otto` is then never
+taken for the canon's chapter `otto`, and nothing that maps the canon's
+chapters to the spec, such as a trail or a backfill menu, hears of it.
+
+This is layout only. The publisher renders an edition from the same
+directories, and imports this module for where they are; the spec layer
+never imports the publisher.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from quirework.manuscript import quarto
+from quirework.manuscript.quarto import BOOK_CONFIG, MARKS_DIR
+from quirework.project import current_project
+
+# Every way an edition document can be written, in the order a sidecar's
+# document is looked for.
+_SUFFIXES = (".qmd", ".md")
+
+
+def root() -> Path | None:
+    """The configured editions root, or None for a project with no editions."""
+    if current_project().get("publish.variants") is None:
+        return None
+    return current_project().path("publish.variants")
+
+
+def kinds() -> list[str]:
+    """Every edition directory, composed or not, by kind, sorted."""
+    base = root()
+    if base is None or not base.is_dir():
+        return []
+    return sorted(
+        folder.name
+        for folder in base.iterdir()
+        if folder.is_dir() and not folder.name.startswith(("_", "."))
+    )
+
+
+def composed() -> list[str]:
+    """Every edition that has a Quarto file of its own, by kind, sorted."""
+    return [kind for kind in kinds() if (root() / kind / BOOK_CONFIG).is_file()]
+
+
+def documents(kind: str) -> list[Path]:
+    """The documents a composed edition renders, as they are on disk.
+
+    Raises ValueError when its Quarto file is not a shape the parser reads.
+    """
+    folder = root() / kind
+    return [
+        folder / rel for rel in quarto.documents(folder) if (folder / rel).is_file()
+    ]
+
+
+def sidecars() -> list[Path]:
+    """Every edition's marks sidecars, by kind, then by name."""
+    base = root()
+    return [
+        path
+        for kind in kinds()
+        for path in sorted((base / kind / MARKS_DIR).glob("*.md"))
+        if path.is_file()
+    ]
+
+
+def _kind_and_stem(path: Path) -> tuple[str, str] | None:
+    """(kind, stem) for an edition's document or sidecar, else None."""
+    base = root()
+    if base is None:
+        return None
+    path = Path(path)
+    if not path.is_absolute():
+        path = current_project().root / path
+    try:
+        parts = path.resolve().relative_to(base).parts
+    except ValueError:
+        return None
+    if len(parts) == 2 and Path(parts[1]).suffix in _SUFFIXES:
+        return parts[0], Path(parts[1]).stem
+    if len(parts) == 3 and parts[1] == MARKS_DIR and parts[2].endswith(".md"):
+        return parts[0], Path(parts[2]).stem
+    return None
+
+
+def unit_of(path: Path | str) -> str | None:
+    """`KIND/STEM` for an edition's document or sidecar, else None."""
+    found = _kind_and_stem(Path(path))
+    return f"{found[0]}/{found[1]}" if found else None
+
+
+def is_sidecar(path: Path) -> bool:
+    return unit_of(path) is not None and Path(path).parent.name == MARKS_DIR
+
+
+def prose_for(sidecar: Path) -> Path:
+    """The document an edition sidecar describes, or where it would be."""
+    sidecar = Path(sidecar)
+    candidates = [sidecar.parent.parent / f"{sidecar.stem}{s}" for s in _SUFFIXES]
+    return next((c for c in candidates if c.is_file()), candidates[0])

quirework/manuscript/footprint.py

@@ -0,0 +1,95 @@
+"""Where the work lives: which files are the written work, in any format.
+
+Several tools ask the same question in different words. Did this session edit
+the work or the tooling around it? Is this commit one a reviewer must see?
+Which paths does the history of the prose run through? Each used to answer it
+for itself, from `manuscript.source` and the companion directories, which is
+right for a book whose spec and marks sit inside its source and wrong for a
+site that keeps them outside the tree its generator renders. This module is
+the one answer, and it is built from what the project already declares:
+
+- the units and their marks, as the format lays them out;
+- the register: the shared spec files, each unit's own spec, the sources,
+  the references and the review notes;
+- the companion collections;
+- and, kept apart, the working roots (`manuscript.noncanonical_roots`), which
+  are writing without authority. A caller measuring effort counts them; a
+  caller deciding what a reviewer must see does not.
+
+Every entry is a glob over project-relative POSIX paths in the `core.globs`
+dialect. A project without a manuscript has an empty footprint.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from quirework.core import globs
+from quirework.manuscript import formats
+from quirework.project import Project, current_project
+
+
+@dataclass(frozen=True)
+class Footprint:
+    units: tuple[str, ...]  # the prose and its marks, as the format lays them out
+    register: tuple[str, ...]  # spec files, references, review notes
+    companions: tuple[str, ...]  # reader-facing collections beside the work
+    working: tuple[str, ...]  # working material: writing, but no authority
+
+    def patterns(self, working: bool = False) -> tuple[str, ...]:
+        out = self.units + self.register + self.companions
+        return out + self.working if working else out
+
+    def covers(self, path: str, working: bool = False) -> bool:
+        """Whether a project-relative path is part of the work."""
+        path = path[2:] if path.startswith("./") else path
+        return globs.any_match(path, self.patterns(working))
+
+
+def _directories(project: Project, key: str) -> tuple[str, ...]:
+    """A configured list of directories, each as a glob for everything under it."""
+    out = []
+    for value in project.get(key, ()) or ():
+        if not value:
+            continue
+        text = str(value).strip("/")
+        out.append("**" if text in ("", ".") else f"{text}/**")
+    return tuple(out)
+
+
+def _spec_files(project: Project) -> tuple[str, ...]:
+    """The shared spec files, one or a list, as project-relative globs; one
+    outside the project has no such name and is left out, as `relative` does."""
+    if project.get("manuscript.spec") is None:
+        return ()
+    out = []
+    for path in project.paths("manuscript.spec"):
+        try:
+            out.append(path.relative_to(project.root).as_posix())
+        except ValueError:
+            continue
+    return tuple(out)
+
+
+def footprint(project: Project | None = None) -> Footprint:
+    project = project or current_project()
+    if not project.get("manuscript"):
+        return Footprint((), (), (), ())
+    units = formats.get(project.get("manuscript.format", "quarto")).footprint(project)
+    register = _spec_files(project) + tuple(
+        found
+        for key in ("manuscript.references", "manuscript.review_notes")
+        if (found := formats.relative(project, key)) is not None
+    )
+    unit_spec = project.get("manuscript.unit_spec")
+    if unit_spec:
+        register += (str(unit_spec).replace("{slug}", "*"),)
+    from quirework.manuscript import sources
+
+    register += sources.footprint_patterns(project)
+    return Footprint(
+        units,
+        register,
+        _directories(project, "manuscript.companion_dirs"),
+        _directories(project, "manuscript.noncanonical_roots"),
+    )

quirework/manuscript/formats.py

@@ -0,0 +1,208 @@
+"""What a manuscript format is, and how one is selected.
+
+A format answers every question the spec layer asks about the written work's
+layout: which files are its units and in what order, which files are prose,
+where a unit's marks sidecar lives, and which unit a sidecar belongs to. The
+spec, marks, quotations and trail are written once against this interface, so
+a new layout is one new `Format` and no change to them.
+
+`manuscript.format` names one. The two built in are `quarto` (a Quarto book's
+chapters, in `_quarto.yml` order) and `pages` (a site's Markdown pages). A
+project can select a format of its own as an installed extension,
+`module:function`, where the function returns a `Format`; like every
+extension, it is loaded only when the project names it.
+"""
+
+from __future__ import annotations
+
+import importlib
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from quirework.core import frontmatter
+from quirework.project import ConfigurationError, Project, current_project, extension
+
+# The formats Quirework ships, by module. Imported on first use, so a project
+# that never names a format pays for neither.
+BUILTIN = {
+    "quarto": "quirework.manuscript.quarto",
+    "pages": "quirework.manuscript.pages",
+}
+
+# A slug is lowercase words joined by hyphens: the one shape a reference, a
+# path pattern and a spec binding can all carry without quoting.
+SLUG_OK = re.compile(r"\A[a-z0-9]+(-[a-z0-9]+)*\Z")
+
+# Developer-guide files carry annotation *examples* in prose, not content.
+SKIP_NAMES = {"AGENTS.md", "CLAUDE.md", "GEMINI.md"}
+
+
+@dataclass(frozen=True)
+class Unit:
+    slug: str  # the durable identity: sidecar, anchor, @unit(), binding key
+    rel: str  # path to the prose file, relative to the project root
+    title: str  # the H1 or frontmatter title, which may drift from the slug
+    number: int | None = None  # a printed chapter number, from position
+    date: str | None = None  # a page's frontmatter date
+    # Whether a page is a draft. None where the format has no publication
+    # state, as a book's chapters have none of their own.
+    draft: bool | None = None
+    lastmod: str | None = None  # when a published page was last revised
+    weight: int | None = None  # a page's frontmatter weight, for ordering
+    collection: str | None = None  # the named collection a page belongs to
+
+
+class Format:
+    """One way of laying out a manuscript. Subclasses answer for their layout.
+
+    Every method that reads the tree takes ``docs``, the source directory,
+    which is `manuscript.source` in normal use and a temporary tree when a
+    check reads the work as it stood at a revision.
+    """
+
+    name: str = ""
+    # What one unit is called in messages, unless `manuscript.unit_name` says.
+    noun: str = "unit"
+
+    def validate(self, project: Project) -> None:
+        """Refuse a configuration this format cannot read. Called by
+        `Project.require("manuscript")` inside the project's scope."""
+
+    def registry(self, docs: Path) -> list[Unit]:
+        """Every unit in reading order."""
+        raise NotImplementedError
+
+    def order_problems(self, docs: Path) -> list[str]:
+        """What stops the units on disk from being the manuscript's units."""
+        raise NotImplementedError
+
+    def prose_files(self, docs: Path) -> list[Path]:
+        """Every prose file on disk, whether or not a reading order lists it."""
+        raise NotImplementedError
+
+    def slug_of(self, path: Path) -> str:
+        """The unit slug a prose file carries."""
+        raise NotImplementedError
+
+    def marks_path(self, slug: str, docs: Path) -> Path | None:
+        """Where the unit's marks sidecar lives, or would; None if it has none."""
+        raise NotImplementedError
+
+    def sidecars(self, docs: Path) -> list[Path]:
+        """Every marks sidecar on disk."""
+        raise NotImplementedError
+
+    def sidecar_slug(self, path: Path) -> str | None:
+        """The unit a sidecar belongs to, or None if the file is no sidecar."""
+        raise NotImplementedError
+
+    def prose_for_sidecar(self, path: Path, docs: Path) -> Path | None:
+        """The prose file a sidecar's marks describe; None when it has none."""
+        raise NotImplementedError
+
+    def harvest(self, docs: Path) -> list[Path]:
+        """The files and directories `notes.scan` reads by default."""
+        raise NotImplementedError
+
+    def default_layers(self, project: Project) -> tuple[str, ...]:
+        """Where the metadata sidecars are, as globs relative to the root."""
+        raise NotImplementedError
+
+    def prose_token(self, token: str) -> str | None:
+        """The slug a token names when it is written as a prose file's path
+        (`the-sidecar.qmd`, `posts/the-kettle/index.md`), else None. A run of
+        prose that cites units reads such a token as a pointer."""
+        return None
+
+    def listing(self, units: list[Unit]) -> list[str]:
+        """The rows `spec units` prints, one per unit."""
+        return [f"  {u.slug:34} {u.title}" for u in units]
+
+    def footprint(self, project: Project) -> tuple[str, ...]:
+        """Where the units and their marks live, as globs over project-relative
+        paths (`core.globs`). Everything else in a work's footprint, its spec
+        and companions, is the project's to declare and `footprint` adds it."""
+        return ()
+
+
+def get(name: str) -> Format:
+    """The format ``name`` names: a built-in, or an extension's."""
+    if name in BUILTIN:
+        return importlib.import_module(BUILTIN[name]).FORMAT
+    if ":" in name:
+        made = extension(name)()
+        if not isinstance(made, Format):
+            raise ConfigurationError(
+                f"manuscript.format {name} must return a quirework Format"
+            )
+        return made
+    raise ConfigurationError(
+        f"manuscript.format must be one of {', '.join(BUILTIN)} or an installed "
+        f"module:function, not {name!r}"
+    )
+
+
+def current() -> Format:
+    """The selected project's format; `quarto` when it declares none."""
+    return get(current_project().get("manuscript.format", "quarto"))
+
+
+# --------------------------------------------------------------------------- #
+# helpers the built-in formats share
+# --------------------------------------------------------------------------- #
+def base(docs: Path) -> Path:
+    """What a unit's `rel` is measured from: the project root when the source
+    is inside it, else the directory holding the source. The second case is a
+    tree outside any project, which is what a test hands the registry."""
+    root = current_project().root
+    return root if docs.resolve().is_relative_to(root) else docs.parent
+
+
+def rel(path: Path) -> str:
+    root = current_project().root
+    path = Path(path)
+    return str(path.relative_to(root)) if path.is_relative_to(root) else str(path)
+
+
+_H1 = re.compile(r"^#\s+(.*?)\s*(?:\{(.*?)\})?\s*$")
+
+
+def h1(text: str) -> tuple[str, str]:
+    """(title, attribute block) of the first H1 after any frontmatter."""
+    found = frontmatter.block(text)
+    body = text[found.end() :] if found else text
+    for line in body.splitlines():
+        m = _H1.match(line)
+        if m:
+            return m.group(1).strip(), (m.group(2) or "")
+    return "", ""
+
+
+def relative(project: Project, key: str) -> str | None:
+    """A configured path as a project-relative POSIX path; None when it is
+    unset or lies outside the project, where no project-relative glob can
+    name it."""
+    if project.get(key) is None:
+        return None
+    try:
+        return project.path(key).relative_to(project.root).as_posix()
+    except ValueError:
+        return None
+
+
+def slug_pattern(key: str) -> str | None:
+    """A configured path pattern that must carry `{slug}`, or None if unset."""
+    pattern = current_project().get(key)
+    if pattern is not None and "{slug}" not in str(pattern):
+        raise ConfigurationError(
+            f"{key} must contain {{slug}}, e.g. 'specs/{{slug}}/"
+            f"{'spec' if key.endswith('spec') else 'marks'}.md'"
+        )
+    return pattern
+
+
+def pattern_regex(pattern: str) -> re.Pattern:
+    """A `{slug}` path pattern as a regex capturing the slug."""
+    head, _, tail = pattern.partition("{slug}")
+    return re.compile(re.escape(head) + r"(?P<slug>[^/]+)" + re.escape(tail) + r"\Z")

quirework/manuscript/lifecycle.py

@@ -0,0 +1,191 @@
+"""Where each unit of the work stands: an idea, planned, a draft, published.
+
+A book's chapters are written and revised together and carry no state of
+their own. A site's posts each live a life: a brief in working material, a
+spec before a word is drafted, a draft, a publication, and for an explainer
+years of revisions after it. The layers already hold every stage but the
+first, so this module only reads them:
+
+- an **idea** is a file `manuscript.ideas` matches that no unit has taken up
+  yet: none carries its name, and no mark or spec names where it lives (its
+  directory, when it is named by one), which is how a post's @genesis
+  points at the brief it grew from
+- a unit is **planned** while it has a spec and no page
+- a page is a **draft** or **published** by its own frontmatter
+
+Two advisories follow from the published stage, because what an author
+promised a reader is at stake there and nowhere earlier. A published unit
+with an open @todo is waiting on something its readers cannot see. And a
+published unit whose own spec changed after the page was last dated says
+something it no longer holds, or holds something it no longer says, until the
+page is revised and its revision field (`lastmod` unless
+`manuscript.revision_field` names another) records it. The second reads the
+history, so it needs the project in git; each page is compared with the
+commit that last touched its spec, not with a clock.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from quirework.manuscript import notes, units
+from quirework.project import ConfigurationError, current_project
+
+
+@dataclass(frozen=True)
+class Idea:
+    slug: str
+    rel: str  # the file the ideas glob matched, relative to the root
+    home: str  # its directory when the idea is named by one, else rel
+
+
+def revision_field() -> str:
+    return str(current_project().get("manuscript.revision_field", "lastmod"))
+
+
+def ideas() -> list[Idea]:
+    """Every file `manuscript.ideas` matches, named as a unit would be: by its
+    directory when the glob names a fixed file (`ideas/*/brief.md`), else by
+    its stem."""
+    project = current_project()
+    pattern = project.get("manuscript.ideas")
+    if not pattern:
+        return []
+    by_directory = not any(c in pattern.rpartition("/")[2] for c in "*?[")
+    out = []
+    for path in sorted(project.root.glob(pattern)):
+        if not path.is_file() or path.name.startswith("_") or path.name == "README.md":
+            continue
+        rel = path.relative_to(project.root).as_posix()
+        if by_directory:
+            home = path.parent.relative_to(project.root).as_posix()
+            out.append(Idea(path.parent.name, rel, home))
+        else:
+            out.append(Idea(path.stem, rel, rel))
+    return out
+
+
+def _names_path(said: str, path: str) -> bool:
+    """Whether prose names `path` as a whole path: `ideas/lamp` is named by
+    "in ideas/lamp," and by "ideas/lamp/brief.md", not by "ideas/lamp-two".
+    A trailing period ends a sentence; one followed by a letter starts an
+    extension, and so names another file."""
+    return re.search(rf"(?<![\w./-]){re.escape(path)}(?![\w-]|\.\w)", said) is not None
+
+
+def planned() -> list[tuple[str, Path]]:
+    """(slug, spec file) for each unit spec whose unit has no page yet."""
+    if notes._unit_spec_pattern() is None:
+        return []
+    present = units.names()
+    return [
+        (owner, f)
+        for f in notes.spec_files()
+        if (owner := notes.spec_owner(f)) is not None and owner not in present
+    ]
+
+
+def open_ideas() -> list[Idea]:
+    """The ideas no unit has taken up yet."""
+    found = ideas()
+    if not found:
+        return []
+    taken = units.names() | {slug for slug, _ in planned()}
+    # A mark or a spec that names the idea's path has taken it up: a post's
+    # @genesis points at the brief it grew from. An idea named by its
+    # directory is its directory, so naming that is enough; an idea that is
+    # one file among others in a directory is named only by its own path.
+    try:
+        specs = notes.spec_files()
+    except ConfigurationError:
+        specs = []
+    said = "\n".join(
+        [a.body for a in notes.scan() if a.body]
+        + [f.read_text(encoding="utf-8") for f in specs]
+    )
+    return [
+        idea
+        for idea in found
+        if idea.slug not in taken and not _names_path(said, idea.home)
+    ]
+
+
+def published() -> list[units.Unit]:
+    return [u for u in units.registry() if u.draft is False]
+
+
+def open_todos() -> list[str]:
+    """Advisory lines: an open @todo on a published unit."""
+    live = {u.rel for u in published()}
+    if not live:
+        return []
+    return [
+        f"  {a.source or a.file}:{a.line}: @todo {a.body}".rstrip()
+        for a in notes.scan()
+        if a.kind == "todo" and a.file in live
+    ]
+
+
+def _git(root, *args):
+    return subprocess.run(
+        ["git", "-C", str(root), *args], capture_output=True, text=True
+    )
+
+
+def _claims(text: str) -> str:
+    """A spec's text as its claims: without comments, anchors or the spacing
+    a reflow changes. Renaming an anchor or rewrapping a paragraph revises
+    nothing a reader was told."""
+    text = re.sub(r"(?s)<!--.*?-->", " ", text)
+    text = re.sub(r"\{[^{}\n]*\}", " ", text)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def unrevised() -> list[str] | None:
+    """Advisory lines: a published unit whose own spec's claims changed after
+    the page was last dated. None when the project has no git history.
+
+    The spec is compared as it stood at the commit that last dated the page,
+    or, for a spec written after that, as it was first committed: writing a
+    spec for a post already published describes it, and only a change after
+    that revises it. The comparison is of claims, not bytes (`_claims`), and
+    of the working file, so an uncommitted revision is named before it is
+    committed and a page being redated in the same change is not.
+    """
+    project = current_project()
+    root = project.root
+    if _git(root, "rev-parse", "--verify", "--quiet", "HEAD").returncode:
+        return None
+    field = revision_field()
+    dated = rf"^(date|{re.escape(field)})[[:space:]]*[:=]"
+    redating = re.compile(rf"(?m)^[+-](date|{re.escape(field)})\s*[:=]")
+    out = []
+    for u in published():
+        spec = notes.unit_spec_path(u.slug)
+        if spec is None or not spec.is_file():
+            continue
+        spec_rel = spec.relative_to(root).as_posix()
+        if redating.search(_git(root, "diff", "HEAD", "-U0", "--", u.rel).stdout):
+            continue  # being redated now
+        last_dated = _git(
+            root, "log", "-1", "--format=%H", "-G", dated, "--", u.rel
+        ).stdout.strip()
+        if not last_dated:
+            continue  # the page has no dated history yet
+        then = _git(root, "show", f"{last_dated}:./{spec_rel}")
+        if then.returncode:
+            first = _git(
+                root, "log", "--diff-filter=A", "--format=%H", "--", spec_rel
+            ).stdout.split()
+            if not first:
+                continue  # being written, not revised
+            then = _git(root, "show", f"{first[-1]}:./{spec_rel}")
+        if _claims(then.stdout) != _claims(spec.read_text(encoding="utf-8")):
+            out.append(
+                f"  {u.rel}: {spec_rel} changed after the {units.noun()} was last "
+                f"dated; revise it, set {field}, and tell a reader what changed"
+            )
+    return out