quirework 0.1.0__py3-none-any.whl

quirework/core/checks.py

@@ -0,0 +1,235 @@
+"""Run an explicitly configured project check suite."""
+
+import argparse
+import ast
+import contextlib
+import io
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from quirework.project import current_project, extension
+from quirework.text import mdwrap
+
+
+SUITE = (
+    ("Python source checks", "every selected .py file parses"),
+    ("Formatting", "`ruff format` would leave the tree unchanged"),
+    ("Markdown wrapping", "`quirework text wrap` would leave the tree unchanged"),
+)
+
+# What `text wrap` reads. Selecting by suffix before asking the project's
+# rules keeps a binary file away from a classifier written for prose.
+MARKDOWN = (".md", ".qmd")
+
+
+def default_checks(argv=None):
+    parser = argparse.ArgumentParser(prog="quirework dev check")
+    parser.add_argument("--staged", action="store_true")
+    # The dispatcher offers --list for any suite, so the default one has to
+    # answer it too. It reached this parser and was rejected as unknown,
+    # which made the option unusable in exactly the projects that have no
+    # configured suite to describe.
+    parser.add_argument("--list", action="store_true")
+    args = parser.parse_args(argv)
+    if args.list:
+        print("Default suite:")
+        for name, description in SUITE:
+            print(f"  {name:22} {description}")
+        return 0
+    root = current_project().root
+    # Both listings name files from the project's root and stop at its edge.
+    # `ls-files` does that on its own; `diff` names them from the repository's
+    # top unless told otherwise, which for a book kept inside a larger
+    # repository pointed every path at a file that was not there.
+    if args.staged:
+        staged = _git(
+            root, "diff", "--cached", "--name-only", "--diff-filter=ACMR", "--relative"
+        )
+        return _suite(root, staged)
+    # Tracked files, which include a new one the moment it is added, so
+    # nothing reaches a commit unjudged. A file nobody added is the author's
+    # scratch until then, and a red that only means "you keep notes here"
+    # teaches people to ignore red.
+    status = _suite(root, _git(root, "ls-files", "--cached"))
+    _advise(root, _git(root, "ls-files", "--others", "--exclude-standard"))
+    return status
+
+
+def _git(root, *args):
+    command = ["git", "-C", str(root), *args]
+    result = subprocess.run(command, capture_output=True, text=True, check=True)
+    return result.stdout.splitlines()
+
+
+def _suite(root, files):
+    """Run every check over ``files``, relative to ``root``; 1 if any fails."""
+    failed, sources, markdown = [], [], []
+    for rel in files:
+        path = root / rel
+        if path.suffix in MARKDOWN and path.is_file() and _own(root, rel):
+            markdown.append(rel)
+        if path.suffix == ".py" and path.is_file():
+            sources.append(rel)
+            try:
+                ast.parse(path.read_text(), filename=rel)
+            except SyntaxError as exc:
+                failed.append(str(exc))
+    for message in failed:
+        print(message)
+    print(f"Python source checks: {'failed' if failed else 'passed'}")
+    return (
+        int(bool(failed))
+        | formatting_check(root, sources)
+        | wrapping_check(root, markdown)
+    )
+
+
+def _advise(root, files):
+    """Judge untracked files, and say what would fail, without failing.
+
+    The same checks as the suite, so a new chapter not yet added is warned
+    about early; only the files they name are shown, under a heading that
+    says they are not counted.
+    """
+    if not files:
+        return
+    report = io.StringIO()
+    try:
+        with contextlib.redirect_stdout(report):
+            status = _suite(root, files)
+    except SystemExit as exc:  # the wrapper refusing a file it cannot reflow
+        status = 1
+        report.write(f"{exc}\n")
+    if not status:
+        return
+    print("Untracked, so not counted until `git add` (or ignore them):")
+    for line in report.getvalue().splitlines():
+        if not any(line.startswith(f"{name}:") for name, _ in SUITE):
+            print(f"  {line}")
+
+
+def _own(root, rel):
+    """Whether a file belongs to this project rather than to one inside it.
+
+    A directory holding its own `quirework.toml` is a project of its own, as
+    an example book inside this repository is, and its configuration chooses
+    how its Markdown wraps. Judged by the outer project's rules, a book that
+    keeps its chapters one sentence per line would be told to hard-wrap
+    them. It answers to its own check instead.
+    """
+    return not any(
+        (root / folder / "quirework.toml").is_file()
+        for folder in Path(rel).parents[:-1]
+    )
+
+
+def formatting_check(root, paths):
+    """Whether the formatter would still change any of these files.
+
+    Not a style opinion. It asserts the tree already sits at the formatter's
+    fixed point, so a contributor who runs the formatter out of tidiness gets
+    an empty diff instead of reformatting a neighbour's code inside a commit
+    about something else. That drift is how this repository came to hold
+    ninety-five formatted files and ten that were not, and the stray hunks it
+    produces are invisible in review because they look like the change they
+    are hiding in.
+
+    Tolerant of an absent formatter, because a project that does not use one
+    has nothing here to be wrong about, and a check that fails on a missing
+    tool teaches people to ignore it. It says so rather than saying nothing:
+    printing no line at all is indistinguishable from passing, which is how a
+    machine without the formatter reports a clean tree over a drifted one.
+    """
+    if not paths:
+        return 0
+    if not shutil.which("ruff"):
+        print("Formatting: skipped, no formatter installed")
+        return 0
+    # The report is read as JSON, never as the text a person would see. That
+    # text follows the caller's environment: FORCE_COLOR puts escape codes
+    # between a label and the file it names, and outranks NO_COLOR, so a
+    # session that forced colour got a check naming "\x1b[0mdrifted.py".
+    # RUFF_OUTPUT_FORMAT can change the layout altogether. The flag outranks
+    # both, and JSON carries no colour.
+    result = subprocess.run(
+        ["ruff", "format", "--check", "--output-format", "json", *paths],
+        cwd=root,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode == 0:
+        print("Formatting: passed")
+        return 0
+    try:
+        diagnostics = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        # No report at all: the formatter refused the invocation itself (an
+        # unreadable configuration, or a ruff too old for --output-format).
+        # Its own words are the only diagnosis there is.
+        print(result.stderr.strip())
+        print("Formatting: failed; the formatter did not run")
+        return 1
+    base = Path(root).resolve()
+    for item in sorted(diagnostics, key=lambda d: (d["filename"], d["code"])):
+        path = Path(item["filename"])
+        rel = path.relative_to(base) if path.is_relative_to(base) else path
+        if item["code"] == "unformatted":
+            print(f"unformatted: {rel}")
+        else:
+            print(f"{item['code']}: {rel}: {item['message']}")
+    print("Formatting: failed; run `ruff format` and commit that on its own")
+    return 1
+
+
+def wrapping_check(root, paths):
+    """Whether `text wrap` would still change any of these Markdown files.
+
+    The same fixed point as `formatting_check`, held for prose. A guide off
+    it is reflowed whole the first time somebody wraps it to fit a
+    one-paragraph edit, so a change made with the project's own tool
+    carries hundreds of lines that are not the change. The project's
+    `text.modes` or `text.classifier` chooses each file's convention, and
+    a file inside a saved run record is never asked to move.
+
+    That exemption reaches only the records a project declares. A room's
+    prompts and replies, saved where the project never said, are named here
+    like any guide, and wrapping them would rewrite what a model was sent
+    and what it said. So the failure says where such a file belongs before
+    it says how to wrap one.
+
+    Unlike the formatter, the wrapper ships with Quirework, so there is no
+    missing tool to tolerate and no reason to say "skipped".
+    """
+    if not paths:
+        return 0
+    drifted = [rel for rel in paths if not mdwrap.at_fixed_point(str(root / rel))]
+    for rel in drifted:
+        print(f"needs wrapping: {rel}")
+    if drifted:
+        print(
+            "Markdown wrapping: failed; a saved run record belongs under "
+            "`runs.evidence_roots`, and anything else wants `quirework text "
+            "wrap`, committed on its own"
+        )
+        return 1
+    print("Markdown wrapping: passed")
+    return 0
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="quirework dev check", description=__doc__)
+    parser.add_argument(
+        "--staged", action="store_true", help="check the paths selected for commit"
+    )
+    parser.add_argument("--list", action="store_true", help="list the configured suite")
+    if argv is not None and any(a in ("-h", "--help") for a in argv):
+        parser.parse_args(argv)
+        return 0
+    reference = current_project().get("checks.command")
+    if reference is None:
+        return default_checks(argv)
+    if reference == "quirework.core.checks:main":
+        raise ValueError("checks.command recursively selects its own dispatcher")
+    return extension(reference)(argv)

quirework/core/frontmatter.py

@@ -0,0 +1,83 @@
+"""A page's frontmatter, in either Markdown convention.
+
+A page opens with TOML between `+++` lines, which is Hugo's default, or YAML
+between `---` lines, which is what Quarto, Jekyll and most other generators
+write. The manuscript reads a few top-level scalars from it (`title`, `date`,
+`draft`) and never writes it, and a reader copy made for delivery drops the
+block whole, since a reader of the rendered page never sees it.
+
+TOML is parsed with the standard library. YAML is not in it, and Quirework's
+core takes no third-party dependency, so YAML is read for top-level scalar
+keys only: a quoted or bare string, or a boolean. A nested map, a list or a
+block scalar under a key is skipped rather than guessed at, which is enough
+for the three fields the manuscript uses and wrong for nothing it reads.
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from datetime import date, datetime
+
+# Either block, anchored at the very start of the file. The closing fence may
+# end the file. Offsets into the text are what callers mask with, so both
+# patterns keep the fences inside the match.
+TOML = re.compile(r"(?s)\A\+\+\+[ \t]*\n(.*?)\n\+\+\+[ \t]*(?:\n|\Z)")
+YAML = re.compile(r"(?s)\A---[ \t]*\n(.*?)\n---[ \t]*(?:\n|\Z)")
+
+_YAML_SCALAR = re.compile(r"^([A-Za-z_][\w-]*):[ \t]*(.*?)[ \t]*$")
+
+
+def block(text: str) -> re.Match | None:
+    """The frontmatter block opening ``text``, fences included, if any."""
+    return TOML.match(text) or YAML.match(text)
+
+
+def _yaml_value(raw: str):
+    if not raw or raw[0] in "[{|>&*!":
+        return None
+    if len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in "\"'":
+        return raw[1:-1]
+    raw = re.sub(r"\s+#.*$", "", raw)
+    lowered = raw.lower()
+    if lowered in ("true", "yes"):
+        return True
+    if lowered in ("false", "no"):
+        return False
+    return raw
+
+
+def fields(text: str) -> dict:
+    """Top-level frontmatter fields; empty when the page has none.
+
+    A TOML block that does not parse raises ``ValueError`` naming the problem:
+    a page whose metadata cannot be read is not one to silently call untitled.
+    """
+    m = TOML.match(text)
+    if m:
+        try:
+            return tomllib.loads(m.group(1))
+        except tomllib.TOMLDecodeError as exc:
+            raise ValueError(f"frontmatter is not valid TOML: {exc}") from exc
+    m = YAML.match(text)
+    if not m:
+        return {}
+    out = {}
+    for line in m.group(1).splitlines():
+        if not line or line[0] in " \t#-":
+            continue  # nested content, a comment, or a list item
+        found = _YAML_SCALAR.match(line)
+        if found:
+            value = _yaml_value(found.group(2))
+            if value is not None:
+                out[found.group(1)] = value
+    return out
+
+
+def as_text(value) -> str | None:
+    """A frontmatter date or string as the text a listing prints."""
+    if value is None:
+        return None
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    return str(value)

quirework/core/globs.py

@@ -0,0 +1,45 @@
+"""Path globs over project-relative POSIX paths.
+
+One dialect for every setting that names files by pattern (`text.modes`, a
+work's footprint), so a pattern means the same thing wherever it is written.
+`**/` matches any number of directories, including none, and a trailing `**`
+matches everything below; `*` and `?` stay inside one path segment. `fnmatch`
+lets `*` cross a slash, which would make `content/*.md` claim every file
+under `content/`.
+"""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+
+
+@lru_cache(maxsize=256)
+def regex(pattern: str) -> re.Pattern:
+    """A path glob as a compiled regex that must match the whole path."""
+    out, i = [], 0
+    while i < len(pattern):
+        if pattern.startswith("**/", i):
+            out.append("(?:[^/]+/)*")
+            i += 3
+        elif pattern.startswith("**", i):
+            out.append(".*")
+            i += 2
+        elif pattern[i] == "*":
+            out.append("[^/]*")
+            i += 1
+        elif pattern[i] == "?":
+            out.append("[^/]")
+            i += 1
+        else:
+            out.append(re.escape(pattern[i]))
+            i += 1
+    return re.compile("".join(out) + r"\Z")
+
+
+def matches(path: str, pattern: str) -> bool:
+    return regex(pattern).match(path) is not None
+
+
+def any_match(path: str, patterns) -> bool:
+    return any(matches(path, p) for p in patterns)

quirework/core/pinned.py

@@ -0,0 +1,169 @@
+"""Fetch a pinned third-party tool into the cache, verified before it unpacks.
+
+Some jobs need a program this package has no business vendoring: an EPUB
+validator is 32 MB of jars, an e-reader renderer is 29 MB of Lua, and neither
+belongs in a prose repository. They are downloaded instead, and a download is
+a supply-chain hole unless it is pinned and checked, so every caller supplies
+a version, a URL and a SHA-256.
+
+The order of operations is the point, and it is why this lives in one place
+rather than once per tool: the archive's bytes are hashed BEFORE anything is
+unpacked, so an archive that was corrupted or substituted never reaches the
+filesystem as an executable. A second copy of that reasoning is a second
+chance to get it wrong.
+
+Everything lands under the cache root, one directory per tool and version, so
+a clone shares the download and `quirework config template tmpfiles` collects
+it when it stops being used.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import sys
+import tarfile
+import tempfile
+import urllib.request
+import zipfile
+from pathlib import Path
+
+
+class PinnedToolError(RuntimeError):
+    """The tool could not be made available; the message is operator-facing."""
+
+
+def cache_root() -> Path:
+    """Where pinned tools live. XDG, so it is shared across clones."""
+    base = os.environ.get("XDG_CACHE_HOME") or (Path.home() / ".cache")
+    return Path(base) / "quirework"
+
+
+def tool_root(name: str, version: str) -> Path:
+    return cache_root() / f"{name}-{version}"
+
+
+def find(name, version, member, *, env_override=None) -> Path | None:
+    """The tool, by explicit override, then by cache. Never by PATH guess.
+
+    An override is honored first so a distribution package or a CI image can
+    supply its own copy. A PATH lookup is deliberately not a fallback: an
+    unpinned binary of the right name is exactly what the pin exists to
+    exclude.
+    """
+    if env_override:
+        supplied = os.environ.get(env_override)
+        if supplied:
+            path = Path(supplied).expanduser()
+            return path if path.exists() else None
+    path = tool_root(name, version) / member
+    return path if path.exists() else None
+
+
+def _unpack(archive: Path, into: Path, member: str) -> None:
+    """Extract, stripping the archive's own root directory if it has one.
+
+    Some releases wrap everything in a `tool-1.2.3/` directory and some
+    unpack straight into place, and the caller should not have to know which.
+    The wanted member decides it rather than a shape heuristic: a tarball
+    whose only top-level entry happens to be `bin/` is not wrapped, and
+    guessing from the shape alone would strip exactly the directory the
+    member is named against.
+
+    Extracting to a staging directory and renaming is both simpler and safer
+    than rewriting member names by hand: it keeps the standard library's own
+    traversal guards and its handling of modes, so the executable bit
+    survives.
+    """
+    staging = Path(tempfile.mkdtemp(prefix=f".{into.name}.", dir=into.parent))
+    try:
+        if archive.suffix == ".zip":
+            with zipfile.ZipFile(archive) as bundle:
+                bundle.extractall(staging)
+        else:
+            with tarfile.open(archive) as bundle:
+                bundle.extractall(staging, filter="data")
+        root = staging
+        if not (staging / member).exists():
+            entries = list(staging.iterdir())
+            if len(entries) == 1 and entries[0].is_dir():
+                root = entries[0]
+        if into.exists():
+            shutil.rmtree(into)
+        # The tool appears at its final path complete or not at all, so an
+        # interrupted unpack cannot be mistaken for an installed tool.
+        os.replace(root, into)
+    finally:
+        shutil.rmtree(staging, ignore_errors=True)
+
+
+def ensure(
+    name,
+    version,
+    url,
+    sha256,
+    member,
+    *,
+    label=None,
+    force=False,
+    timeout=120,
+    log=None,
+) -> Path:
+    """Make the pinned tool available and return the path to `member`.
+
+    Raises `PinnedToolError` with an operator-facing message on any failure.
+    """
+    label = label or name
+    log = log if log is not None else (lambda message: print(message))
+    target = tool_root(name, version) / member
+    if target.exists() and not force:
+        return target
+
+    root = cache_root()
+    root.mkdir(parents=True, exist_ok=True)
+    archive = root / url.rsplit("/", 1)[-1]
+
+    if not archive.exists() or force:
+        log(f"fetching {label} {version} ...")
+        try:
+            with urllib.request.urlopen(url, timeout=timeout) as response:  # noqa: S310
+                archive.write_bytes(response.read())
+        except KeyboardInterrupt:
+            # A half-written archive would be SKIPPED by the exists() test on
+            # the next run and then fail its checksum, costing a second run to
+            # recover from one ctrl-c.
+            archive.unlink(missing_ok=True)
+            raise
+        except Exception as exc:  # network, TLS, 404
+            archive.unlink(missing_ok=True)
+            raise PinnedToolError(f"{name}: download failed: {exc}") from exc
+
+    got = hashlib.sha256(archive.read_bytes()).hexdigest()
+    if got != sha256:
+        archive.unlink(missing_ok=True)
+        raise PinnedToolError(
+            f"{name}: checksum mismatch for {url}\n"
+            f"  expected {sha256}\n  got      {got}\n"
+            f"  the download was discarded."
+        )
+
+    _unpack(archive, tool_root(name, version), member)
+    if not target.exists():
+        raise PinnedToolError(f"{name}: {target} missing after unpack.")
+    log(f"{name} {version} installed: {target}")
+    return target
+
+
+def install(name, version, url, sha256, member, *, label=None, force=False) -> int:
+    """`ensure` as a command: prints, and returns a process exit status."""
+    target = tool_root(name, version) / member
+    if target.exists() and not force:
+        print(f"{name} {version} already installed: {target}")
+        return 0
+    try:
+        ensure(name, version, url, sha256, member, label=label, force=force)
+    except PinnedToolError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    return 0