Skip to content

livery.workshop._provenance

livery.workshop._provenance

Provenance: which channel owns a file, and where to edit it.

One classifier answers for any path; everything else serialises its answer. fm explain <path> prints it. The fragment engine and the emitters open every file they write with a header, so the answer rides the file wherever comments are possible. Materialised copies are never injected: override detection depends on the copy staying byte-identical to its source, so those files, and comment-hostile ones, are explain's territory alone. Shipped extension content carries its header through the provenance lint, whose --fix writes the computed text.

Functions:

Name Description
comment_style

The comment leader for path: #, //, html, or empty.

format_header

The header lines as one comment block in style.

generated_header

The provenance header a generated file opens with, as a comment block.

content_header

The header shipped extension content carries, lint-enforced.

inject

Open path with header, replacing a stale machine header.

has_header

Whether path already opens with header (shebang-tolerant).

strip_header

text with a machine-written header removed, everything after it kept.

emitted_paths

The paths the workshop emitters write for root, the owners file included.

classify

The provenance of relative inside root; "yours" when no channel claims it.

explain

Name a file's owning channel, its source and its edit path; or what a step runs.

describe

The lines fm explain prints for relative: category, channel, claims.

unit_of

The package path belongs to and the path inside it, or the root's unit.

owned_lines

What a managed file carries that the repository owns, one line each.

content_lint

Extension content files missing their computed header; fix writes it.

provenance_check

Check shipped extension content opens with its provenance header.

check_content

The provenance check over the content files in scope; refuses a missing header.

comment_style

comment_style(path: Path) -> str

The comment leader for path: #, //, html, or empty.

The editor's .vscode/settings.json is JSON with comments, the one JSON the render owns; every other JSON carries no header.

Source code in packages/workshop/src/livery/workshop/_provenance.py
def comment_style(path: Path) -> str:
    """The comment leader for *path*: ``#``, ``//``, ``html``, or empty.

    The editor's ``.vscode/settings.json`` is JSON with comments, the
    one JSON the render owns; every other JSON carries no header.
    """
    if path.name == "settings.json" and path.parent.name == ".vscode":
        return "//"
    return _BY_NAME.get(path.name, _BY_SUFFIX.get(path.suffix, ""))

format_header

format_header(lines: tuple[str, ...], style: str) -> str

The header lines as one comment block in style.

Source code in packages/workshop/src/livery/workshop/_provenance.py
def format_header(lines: tuple[str, ...], style: str) -> str:
    """The header *lines* as one comment block in *style*."""
    if style == "html":
        body = "".join(f"     {line}\n" for line in lines[1:])
        return f"<!-- {lines[0]}\n{body}-->\n"
    return "".join(f"{style} {line}\n" for line in lines)

generated_header

generated_header(style: str, lines: tuple[str, ...] = ()) -> str

The provenance header a generated file opens with, as a comment block.

style is the file's comment marker (# or //), or html for a <!-- --> block. lines say what writes the file and how a reader changes it, for a file an extension writes outside the engine; without them, the header says what every artifact the engine emits says: the contract is the source, and an edit here is drift.

Source code in packages/workshop/src/livery/workshop/_provenance.py
def generated_header(style: str, lines: tuple[str, ...] = ()) -> str:
    """The provenance header a generated file opens with, as a comment block.

    *style* is the file's comment marker (``#`` or ``//``), or ``html``
    for a ``<!-- -->`` block. *lines* say what writes the file and how
    a reader changes it, for a file an extension writes outside the
    engine; without them, the header says what every artifact the
    engine emits says: the contract is the source, and an edit here is
    drift.
    """
    if not lines:
        prog = footman.prog()
        lines = (
            "Generated by the workshop from workshop.toml; the gate keeps",
            "it matching. Edit the contract (or the emitters) and run",
            f"`{prog} sync`; an edit here is drift.",
        )
    return format_header(lines, style)

content_header

content_header(extension: str, style: str) -> str

The header shipped extension content carries, lint-enforced.

Source code in packages/workshop/src/livery/workshop/_provenance.py
def content_header(extension: str, style: str) -> str:
    """The header shipped extension content carries, lint-enforced."""
    lines = (
        f"Shipped as {extension} extension content, delivered to the workspace",
        "by the sync verb. Edit this copy in the extension and release it;",
        "an edited delivered copy is a local override, kept and named.",
    )
    return format_header(lines, style)

inject

inject(path: Path, header: str) -> None

Open path with header, replacing a stale machine header.

Source code in packages/workshop/src/livery/workshop/_provenance.py
def inject(path: Path, header: str) -> None:
    """Open *path* with *header*, replacing a stale machine header."""
    text = path.read_text(encoding="utf-8")
    text = strip_header(text, path, size=len(header.splitlines()))
    at = _insertion_point(text, path)
    path.write_text(text[:at] + header + text[at:], encoding="utf-8", newline="\n")

has_header

has_header(path: Path, header: str) -> bool

Whether path already opens with header (shebang-tolerant).

Source code in packages/workshop/src/livery/workshop/_provenance.py
def has_header(path: Path, header: str) -> bool:
    """Whether *path* already opens with *header* (shebang-tolerant)."""
    text = path.read_text(encoding="utf-8")
    at = _insertion_point(text, path)
    return text[at:].startswith(header)

strip_header

strip_header(text: str, path: Path, *, size: int = 3) -> str

text with a machine-written header removed, everything after it kept.

An HTML header is its <!-- --> block. A line-comment header is its first size lines, the length every machine header is written at, when the first carries a marker: the comment lines below it are the file's own and stay, and so does a blank line after either.

Source code in packages/workshop/src/livery/workshop/_provenance.py
def strip_header(text: str, path: Path, *, size: int = 3) -> str:
    """*text* with a machine-written header removed, everything after it kept.

    An HTML header is its ``<!-- -->`` block. A line-comment header is
    its first *size* lines, the length every machine header is written
    at, when the first carries a marker: the comment lines below it are
    the file's own and stay, and so does a blank line after either.
    """
    at = _insertion_point(text, path)
    head, tail = text[:at], text[at:]
    style = comment_style(path)
    if style == "html":
        if tail.startswith("<!--") and "-->" in tail:
            block, _, rest = tail.partition("-->\n")
            if any(marker in block for marker in _MARKERS):
                return head + rest
        return text
    lines = tail.splitlines(keepends=True)
    first = lines[:size]
    leader = style or "#"
    if (
        len(first) == size
        and all(line.startswith(leader) for line in first)
        and any(marker in first[0] for marker in _MARKERS)
    ):
        return head + "".join(lines[size:])
    return text

emitted_paths

emitted_paths(root: Path) -> frozenset[str]

The paths the workshop emitters write for root, the owners file included.

One emission is a full render of every workflow, the site configuration, and the entry script; a caller classifying many paths computes this once and hands it to livery.workshop._provenance.classify.

Source code in packages/workshop/src/livery/workshop/_provenance.py
def emitted_paths(root: Path) -> frozenset[str]:
    """The paths the workshop emitters write for *root*, the owners file included.

    One emission is a full render of every workflow, the site
    configuration, and the entry script; a caller classifying many
    paths computes this once and hands it to
    [livery.workshop._provenance.classify][].
    """
    from livery.workshop._ci_generate import generate
    from livery.workshop._governance import codeowners_file

    generated = set(generate(root))
    owners = codeowners_file(root)
    if owners is not None:
        generated.add(owners.path)
    return frozenset(generated)

classify

classify(root: Path, relative: Path, *, emitted: frozenset[str] | None = None) -> Provenance

The provenance of relative inside root; "yours" when no channel claims it.

relative is taken lexically, never resolved: a materialised link classifies as the delivered entry it is, not as the wheel path it points into. emitted is the emitters' path set from livery.workshop._provenance.emitted_paths; a caller with many paths passes one set rather than paying an emission per path. The answer comes from the channel registry, the builtin ladder below and whatever an extension registered beside it, highest rank first.

Source code in packages/workshop/src/livery/workshop/_provenance.py
def classify(
    root: Path, relative: Path, *, emitted: frozenset[str] | None = None
) -> Provenance:
    """The provenance of *relative* inside *root*; "yours" when no channel claims it.

    *relative* is taken lexically, never resolved: a materialised
    link classifies as the delivered entry it is, not as the wheel
    path it points into. *emitted* is the emitters' path set from
    [livery.workshop._provenance.emitted_paths][]; a caller with many
    paths passes one set rather than paying an emission per path.
    The answer comes from the channel registry, the builtin ladder
    below and whatever an extension registered beside it, highest rank
    first.
    """
    found = channel_of(root, relative, emitted=emitted)
    if found is not None:
        return found.provenance
    return Provenance("yours", "this repository", "edit directly")

explain

explain(path: Annotated[Arg[str], ask(), suggest(_tracked_paths, strict=False), doc("the file to explain, relative to the workspace root, or a step's name")] = '') -> None

Name a file's owning channel, its source and its edit path; or what a step runs.

Every answer for a file has the same three lines; a file no channel claims is yours, which is the honest default, not an error. A step's name, typecheck.mypy, prints the command the step runs and what the engine appends to it.

Source code in packages/workshop/src/livery/workshop/_provenance.py
@task
def explain(
    path: Annotated[
        Arg[str],
        ask(),
        suggest(_tracked_paths, strict=False),
        doc("the file to explain, relative to the workspace root, or a step's name"),
    ] = "",
) -> None:
    """Name a file's owning channel, its source and its edit path; or what a step runs.

    Every answer for a file has the same three lines; a file no channel
    claims is yours, which is the honest default, not an error. A
    step's name, ``typecheck.mypy``, prints the command the step runs
    and what the engine appends to it.
    """
    if not path:
        fail(f"name a file: `{footman.prog()} explain pyproject.toml`")
    root = workspace_root()
    if root is None:
        fail("no workspace: no workshop.toml above the working directory")
    from livery.workshop._steps import steps_by_name

    record = steps_by_name().get(path)
    if record is not None:
        from livery.workshop._words import explained

        for line in explained(record):
            print(line)
        return
    raw = Path(path)
    if raw.is_absolute():
        try:
            raw = raw.relative_to(root)
        except ValueError:
            fail(f"{path} is outside this workspace")
    relative = Path(os.path.normpath(str(raw)))
    if not relative.parts or relative.parts[0] == "..":
        fail(f"{path} is outside this workspace")
    for line in describe(root, relative):
        print(line)

describe

describe(root: Path, relative: Path) -> list[str]

The lines fm explain prints for relative: category, channel, claims.

A file is claimed by each step that reads it and each CI job whose declared inputs read it, the job as <point>/<job>. A contract also names the schema it is judged by, with the owners whose keys the schema holds.

Source code in packages/workshop/src/livery/workshop/_provenance.py
def describe(root: Path, relative: Path) -> list[str]:
    """The lines ``fm explain`` prints for *relative*: category, channel, claims.

    A file is claimed by each step that reads it and each CI job whose
    declared inputs read it, the job as ``<point>/<job>``. A contract
    also names the schema it is judged by, with the owners whose keys
    the schema holds.
    """
    from livery.workshop._packages import discover_packages
    from livery.workshop._points import jobs_reading

    packages = discover_packages(root) if (root / "packages").is_dir() else ()
    unit, inside = unit_of(root, packages, relative.as_posix())
    lines = [f"  {relative.as_posix()}"]
    if unit is not None:
        category = category_of(unit, inside)
        lines.append(f"    category: {category.name} ({category.supplier})")
    found = channel_of(root, relative)
    answer = found.provenance if found is not None else classify(root, relative)
    supplier = found.supplier if found is not None else "livery.workshop"
    lines.append(f"    channel: {answer.channel} ({supplier})")
    lines.append(f"    source: {answer.source}")
    lines.append(f"    edit: {answer.edit}")
    from livery.workshop._steps import claimants

    claims = list(claimants(unit, inside)) if unit is not None else []
    claims.extend(jobs_reading(root, relative.as_posix()))
    if claims:
        lines.append(f"    claimed by: {', '.join(claims)}")
    from livery.workshop._schema import judged_by

    schema = judged_by(root, relative)
    if schema:
        lines.append(f"    {schema}")
    lines.extend(f"    {line}" for line in owned_lines(root, relative))
    return lines

unit_of

unit_of(root: Path, packages: tuple[Package, ...], path: str) -> tuple[Package | None, str]

The package path belongs to and the path inside it, or the root's unit.

A path under no package is the workspace unit's, relative to the root; None when the root has no unit to speak of.

Source code in packages/workshop/src/livery/workshop/_provenance.py
def unit_of(
    root: Path, packages: tuple[Package, ...], path: str
) -> tuple[Package | None, str]:
    """The package *path* belongs to and the path inside it, or the root's unit.

    A path under no package is the workspace unit's, relative to the
    root; None when the root has no unit to speak of.
    """
    from livery.workshop._packages import workspace_suite

    for package in packages:
        if path.startswith(package.path + "/"):
            return package, path[len(package.path) + 1 :]
    return workspace_suite(root) or _root_unit(root), path

owned_lines

owned_lines(root: Path, relative: Path) -> list[str]

What a managed file carries that the repository owns, one line each.

A marked region is named with the lines its markers enclose. A file without one says nothing.

Source code in packages/workshop/src/livery/workshop/_provenance.py
def owned_lines(root: Path, relative: Path) -> list[str]:
    """What a managed file carries that the repository owns, one line each.

    A marked region is named with the lines its markers enclose. A file
    without one says nothing.
    """
    from livery.workshop import _regions

    path = root / relative
    if not path.is_file():
        return []
    text = path.read_text(encoding="utf-8", errors="replace")
    return [
        f"region {region.name}: lines {region.first} to {region.last}, yours to"
        " edit inside the markers; the render keeps it"
        for region in _regions.regions_in(text)
    ]

content_lint

content_lint(root: Path, *, fix: bool = False, files: frozenset[str] | None = None) -> list[str]

Extension content files missing their computed header; fix writes it.

files keeps the lint to those root-relative files; None lints every content file.

Only the workspace's own packages are linted: an installed extension's content is its home repository's to keep. Files without a comment syntax are exempt, and so are the fragment engine's templates under content/root/ and content/package/, and under content/for/<target>/root/ and content/for/<target>/package/, whose composed files carry headers of their own, and the seeds under content/seeds/ and the templates' files under content/templates/, which become the workspace's own files.

Source code in packages/workshop/src/livery/workshop/_provenance.py
def content_lint(
    root: Path, *, fix: bool = False, files: frozenset[str] | None = None
) -> list[str]:
    """Extension content files missing their computed header; ``fix`` writes it.

    *files* keeps the lint to those root-relative files; None lints
    every content file.

    Only the workspace's own packages are linted: an installed
    extension's content is its home repository's to keep. Files without
    a comment syntax are exempt, and so are the fragment engine's
    templates under `content/root/` and `content/package/`, and under
    `content/for/<target>/root/` and `content/for/<target>/package/`,
    whose composed files carry headers of their own, and the seeds under
    `content/seeds/` and the templates' files under `content/templates/`,
    which become the workspace's own files.
    """
    from livery.workshop._seeds import SEEDS, TEMPLATES
    from livery.workshop._shipped_files import (
        FOR_CONTENT,
        PACKAGE_CONTENT,
        ROOT_CONTENT,
    )

    problems = []
    for extension, content in _content_trees(root):
        for path in sorted(content.rglob("*")):
            if not path.is_file() or "__pycache__" in path.parts:
                continue
            if files is not None and path.relative_to(root).as_posix() not in files:
                continue
            # A template the fragment engine composes into a workspace file
            # carries that file's own header; this one would land in it.
            parts = path.relative_to(content).parts
            if parts[0] in (ROOT_CONTENT, PACKAGE_CONTENT, SEEDS, TEMPLATES):
                continue
            if (
                parts[0] == FOR_CONTENT
                and len(parts) > 3
                and parts[2] in (ROOT_CONTENT, PACKAGE_CONTENT)
            ):
                continue
            style = comment_style(path)
            if not style:
                continue
            header = content_header(extension, style)
            if has_header(path, header):
                continue
            if fix:
                inject(path, header)
                problems.append(f"{path.relative_to(root).as_posix()}: header written")
            else:
                problems.append(
                    f"{path.relative_to(root).as_posix()}: missing its header"
                )
    return problems

provenance_check

provenance_check(fix: Annotated[bool, doc('write the computed headers in place')] = False) -> None

Check shipped extension content opens with its provenance header.

Part of the gate. Nobody composes a header by hand: --fix writes the computed text, and the render and emitters inject theirs into everything they write.

Source code in packages/workshop/src/livery/workshop/_provenance.py
@task(name="provenance")
def provenance_check(
    fix: Annotated[bool, doc("write the computed headers in place")] = False,
) -> None:
    """Check shipped extension content opens with its provenance header.

    Part of the gate. Nobody composes a header by hand: ``--fix``
    writes the computed text, and the render and emitters inject
    theirs into everything they write.
    """
    check_content(fix=fix)

check_content

check_content(*, fix: bool = False, files: frozenset[str] | None = None) -> None

The provenance check over the content files in scope; refuses a missing header.

The engine behind fm provenance and the gate's provenance.check: files keeps it to those root-relative files, None to every content file.

Source code in packages/workshop/src/livery/workshop/_provenance.py
def check_content(*, fix: bool = False, files: frozenset[str] | None = None) -> None:
    """The provenance check over the content files in scope; refuses a missing header.

    The engine behind `fm provenance` and the gate's ``provenance.check``: *files*
    keeps it to those root-relative files, None to every content file.
    """
    root = workspace_root()
    if root is None:
        fail("no workspace: no workshop.toml above the working directory")
    findings = content_lint(root, fix=fix, files=files)
    for line in findings:
        print(f"  {line}")
    if findings and not fix:
        fail(
            "extension content is missing provenance headers: run"
            f" `{footman.prog()} check --fix` to write them"
        )