🗺️ mecha#
Emits .mcfunction.map sidecars for bolt and mecha, read straight off the compiled AST.
stewbeet.plugins.source_maps runs it from its teardown: the same output contract, an entirely different front half.
Bolt’s positions were never lost, so there is no capture, no frame walk and no difflib:
every mecha.AstNode carries its own location, and column precision comes free.
Not to be confused with mecha.contrib.source_map, which prepends a header comment naming the file
and emits no line mapping at all.
- class Compilation(mc: ~mecha.api.Mecha, sources: dict[str, str], vanilla: frozenset[str], bolt: frozenset[str], disk: dict[str, ~stewbeet.plugins.source_maps.mecha.attribute.OnDisk] = <factory>)[source]#
Bases:
objectWhat every command of one build is attributed against.
- bolt: frozenset[str][source]#
Normalised absolute paths of the
.mcfunctionsources written in bolt or mecha syntax.
- disk: dict[str, OnDisk][source]#
Each source file against the text mecha parsed from it, read as files are met.
- chunks(
- path: str,
- ast: AstRoot,
- source: str | None,
- own_file: str | None,
Each command of a compiled function as mecha serialised it, with the line of the project’s source it came from.
- Parameters:
source – Text the function was parsed from.
own_file – The file the function was compiled from, None when no project file backs it.
- project_roots(
- ctx: Context,
Roots under which a compiled file counts as the project’s own source.
Defaults to beet’s project directory.
meta.source_maps.rootsnarrows it, which is what a project vendoring bolt libraries into its own tree needs: those compile into the pack and would otherwise be named as mapping targets.
- write_maps(ctx: Context) int[source]#
Write one sidecar per compiled function whose lines reach the project’s own source.
The serialised commands are reconciled against the function’s final text rather than trusted positionally, because a StewBeet pipeline runs
auto.headersaftermechaand prepends a header block to every function. That is the same reason the StewBeet producer aligns, so it is the samealign.A function the helpers also wrote into, like a load function a plugin prepends a line to, keeps the origins they recorded and takes mecha’s for the lines they left unmapped, replacing the map the capture half wrote first.
- Returns:
How many sidecars were written.
- write_merged_sidecar(
- ctx: Context,
- path: str,
- func: Function,
- mapped: dict[int, SourceOrigin] | None,
Write a function’s map over any the capture half wrote, and return 1 when one was written.
- merged_origins(
- compiled: dict[int, SourceOrigin],
- captured: list[WriteChunk],
- text: str,
mecha’s origins, under those of what the helpers wrote. None when the helpers’ map already holds every line mecha maps.
attribute#
Which file wrote a command, when the AST node only carries a position.
A SourceLocation has no filename, and the obvious substitute, the compilation unit’s own filename,
names only the first module that contributed. A function assembled from two modules,
which is what every shulker component does to PLAYER_TICK, would send most of its lines to the wrong file.
The spike at specs/001-stewbeet-vscode-dx/spike/bolt-attribution/ measured it.
- SIMILAR: float = 0.6[source]#
How alike an edited line and an original one must be, by
SequenceMatcher.ratio, to count as the same line rewritten.
- class OnDisk(
- parsed: list[str],
- disk: list[str],
- lines: dict[int, int] | None,
Bases:
objectA source file as mecha parsed it and as it is on disk, which differ once a plugin edits a function before mecha compiles it.
Function.prependadds lines, and a versioning refactor rewritesns:impl/intons:v1.2.3/inside them. A line rewritten in place is still the line on disk it came from, with its columns moved through what both share, and a line the plugin added has no line on disk at all.>>> on_disk = OnDisk.of(parsed=["say added", "function ns:v1/a"], disk=["function ns:impl/a"]) >>> on_disk.position(1, 12), on_disk.position(1, 16), on_disk.position(0, 0) ((0, 12), (0, 18), None)
- lines: dict[int, int] | None[source]#
The disk line of each parsed line that has one, None when the two texts are the same.
- classmethod read(path: str, parsed: str) Self[source]#
The file at
pathagainst the text mecha parsed from it.
- paired_lines(
- parsed: list[str],
- disk: list[str],
- edited: range,
- original: range,
The lines of an edited run paired, in order, with the original lines they still look like.
A run holding a line a plugin added has one line more than the original, and which one it is can only be told by looking.
>>> paired_lines(["say added", "function ns:v1/a"], ["function ns:impl/a"], range(2), range(1)) {1: 0}
- candidate_sources(
- mc: Mecha,
- directory: str,
- roots: tuple[str, ...],
Absolute path to source text, for every compiled file the project may be mapped onto.
Every unit in the database is a candidate, not just the one being emitted, because a command’s position belongs to whichever module wrote it. Units outside the project roots or inside an installed library are dropped here, so FR-010 holds for every line without a second check.
- Parameters:
directory – beet’s project directory, which
filenameis relative to.roots – Normalised absolute directories the project owns.
- source_file_of(
- unit: CompilationUnit,
- directory: str,
Absolute path a compilation unit was parsed from, None when it was assembled in memory.
- Parameters:
directory – beet’s project directory, which
filenameis relative to.
- owner_of(
- location: SourceLocation,
- sources: dict[str, str],
- command: str,
- own: str | None = None,
- own_file: str | None = None,
The one file a location can belong to, or None when it cannot be narrowed to one.
The position must sit where the location says and the file must say there what the command starts with, since the first character of every file is a valid position. The word check costs 46 of 815 mappings on a real project (FR-010).
- Parameters:
command – The command as mecha serialised it. Its first word is the evidence.
own – The text this unit’s AST was parsed from, when it has one.
own_file – Absolute path of that text on disk, or None when it was assembled in memory.
>>> sources = {"helper.bolt": "# helper module\nappend function demo:shared:\n say from helper\n"} >>> owner_of(SourceLocation(49, 3, 5), sources, "say from helper") 'helper.bolt'
- sits_at(
- source: str,
- pos: int,
- lineno: int,
- colno: int,
Whether offset
posofsourceis at 1-based linelineno, columncolno.The three fields of a
SourceLocationare mutually redundant, so a file that did not produce the node has to agree on the offset and the line and the column to be a false positive. That redundancy is the whole attribution mechanism.>>> sits_at("ab\ncd\n", 3, 2, 1) True >>> sits_at("ab\ncd\n", 3, 1, 4) False
compiled#
What a compiled command says about its source beyond where it starts: where each of its nodes sits, and where vanilla syntax ends.
An editor showing a datapack parser the source needs both. The nodes are how it gives a bolt expression or a ~/child path the value
mecha resolved it to, column for column, and the end of vanilla syntax is where the parser’s opinion stops being worth showing:
a plugin can add commands to mecha’s tree, and the build accepting them is the proof that they are right.
- compiled_line(
- mc: Mecha,
- command: AstCommand,
- serialized: str,
- source: str,
- disk: OnDisk,
- vanilla: frozenset[str],
- bolt: bool,
Everything an editor can learn about one compiled command, its source positions moved to the file on disk.
- Parameters:
serialized – The command as mecha serialised it.
source – Text mecha parsed the command from.
vanilla – Every path of the vanilla command tree, see
vanilla_paths.
- node_columns(
- mc: Mecha,
- command: AstCommand,
- written: str,
The column of
writtenat which each node of the command starts and ends, with the source position it was parsed at.A node’s text is looked for inside its parent’s, after its previous sibling, which is the order a serialiser writes them in. A node mecha placed nowhere, or one that does not serialise on its own, is skipped, and its children are looked for in its parent.
detect#
Which of the project’s own .mcfunction sources no vanilla parser can read.
Four things take a source file out of vanilla mcfunction, and all are read off structures the build already has rather than guessed from the text: bolt generated Python for it, mecha split it into more than one function, one of its commands spans several lines, or one is a command a plugin added to mecha.
- WORD: Pattern[str] = re.compile('\\s*\\S+')[source]#
One literal of a command and the whitespace before it.
- unparseable_sources(
- ctx: Context,
Project-relative paths of the
.mcfunctionsources Spyglass reports as broken.- Returns:
Sorted forward-slash paths.
- opaque_sources(
- mc: Mecha,
- vanilla: frozenset[str],
Files holding a command a plugin added to mecha’s tree, which the build accepts and no vanilla parser reads.
- Parameters:
vanilla – Every path of the vanilla command tree, see
vanilla_paths.
- spread_sources(mc: Mecha) set[str][source]#
Files holding a command written over several lines, which mecha’s
multilinemode and bolt’s brackets allow.Counted as more than one line of text between where a command starts and where the next one does, since a plugin’s node may carry no end position. A blank line, a comment and vanilla’s own
\continuation do not count.
- written_lines(lines: list[str]) int[source]#
How many of the lines hold text, a blank line, a comment and a line a
\continues left aside.>>> written_lines(["execute", " as @a", "", "# note", " run say hi"]), written_lines(["say a \\", " b"]) (3, 1)
- nested_sources(mc: Mecha) set[str][source]#
Files backing more than one compilation unit, which is mecha’s
function ./name:nesting.Nesting is not vanilla syntax twice over: the line opening a body ends in a colon, and
./nameis not a resource location. A file using it is a file Spyglass underlines.
- bolt_sources(
- ctx: Context,
- mc: Mecha,
Files bolt generated Python for, which is every file that used bolt syntax.
A plain function compiled while bolt is loaded keeps its
pythonat None, so this says the file used bolt rather than that bolt was available.
- existing_service(
- ctx: Context,
- service: Callable[[Context], T],
A service this build already has, or None when nothing asked for one.
ctx.injectcreates what it cannot find, and creating bolt’s runtime at the end of a build would enable bolt on a project that does not use it, so the container is read instead.
- project_relative(filename: str | None) str | None[source]#
A compiled file’s path relative to the project root, or None when it lies outside the project.
CompilationUnit.filenameis already relative to beet’s project directory, so this normalises separators and drops a file from a dependency, which is not the project’s own source.>>> project_relative("src/data/ns/function/a.mcfunction") 'src/data/ns/function/a.mcfunction' >>> project_relative("src\\data\\ns\\function\\a.mcfunction") 'src/data/ns/function/a.mcfunction' >>> [project_relative(outside) for outside in ("../shared/x.mcfunction", "/tmp/x.mcfunction", "D:/x.mcfunction", None)] [None, None, None, None]
- opaque_start(
- mc: Mecha,
- command: AstCommand,
- vanilla: frozenset[str],
- source: str,
Where the first piece of syntax the vanilla command tree does not have begins, None for a vanilla command.
A nested block is mecha’s own and its body is compiled as commands of their own, so it is not counted. A literal has no node to read a position from, so it is found as the word it is after the last argument placed before it.
- Parameters:
vanilla – Every path of the vanilla command tree, see
vanilla_paths.source – Text the command was parsed from, which the positions index.
- literal_start(
- signature: tuple[object, ...],
- arguments: dict[int, AstNode],
- diverging: int,
- start: SourceLocation,
- source: str,
Where entry
divergingof a signature sits, counted in words from the last argument placed before it.- Parameters:
arguments – Each argument node by the index of its entry in the signature.
start – Where the command starts, counted from when no argument before it was placed.
- location_at(
- source: str,
- position: int,
The 1-based line and column of an offset, which is how mecha spells a position.
>>> location_at("say a\ncompute bolt", 14) SourceLocation(pos=14, lineno=2, colno=9)
- project_vanilla_paths(
- ctx: Context,
The vanilla command paths of the Minecraft version the project compiles for.
- vanilla_paths(version: str) frozenset[str][source]#
Every path of the vanilla command tree of a Minecraft version, spelled like mecha’s command identifiers.
Read from the tree mecha ships for that version, so a new version needs nothing here.
>>> {"compute", "compute:bolt"} & vanilla_paths("26.3") {'compute'}