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: |
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 |
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; |
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 ¶
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
format_header ¶
The header lines as one comment block in style.
Source code in packages/workshop/src/livery/workshop/_provenance.py
generated_header ¶
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
content_header ¶
The header shipped extension content carries, lint-enforced.
Source code in packages/workshop/src/livery/workshop/_provenance.py
inject ¶
Open path with header, replacing a stale machine header.
Source code in packages/workshop/src/livery/workshop/_provenance.py
has_header ¶
Whether path already opens with header (shebang-tolerant).
Source code in packages/workshop/src/livery/workshop/_provenance.py
strip_header ¶
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
emitted_paths ¶
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
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
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
describe ¶
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
unit_of ¶
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
owned_lines ¶
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
content_lint ¶
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
provenance_check ¶
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
check_content ¶
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.