
# stewbeet.plugins.source_maps

The `source_maps` plugin records where every generated line came from, and writes a<br>
[Source Map v3](https://tc39.es/ecma426/) `.mcfunction.map` sidecar next to each generated function.<br>
An editor or a debugger reading one of those maps can jump from a command in the built datapack<br>
straight to the `write_function` call in your Python that produced it.

The format is the same one JavaScript tooling has used for a decade, so it is readable by anything<br>
that already speaks source maps, including the Minecraft debugger [Sniffer](https://github.com/mcbookshelf/sniffer).

### <u>What it looks like</u>

**The Python that wrote the command, the command, and the sidecar that links them**<br>
<img src="https://raw.githubusercontent.com/Stoupy51/StewBeet/main/docs/plugins/img/source_maps.sidecar.jpg">

**Required**: Nothing. It is off unless you ask for it.<br>
**Position**: One entry in `require`. See below.<br>
**Source Code**: [`stewbeet/plugins/source_maps/__init__.py`](https://github.com/Stoupy51/StewBeet/blob/main/python_package/stewbeet/plugins/source_maps/__init__.py) <br>
**Source Code**: [`stewbeet/plugins/source_maps/emit/__init__.py`](https://github.com/Stoupy51/StewBeet/blob/main/python_package/stewbeet/plugins/source_maps/emit/__init__.py) <br>
**Source Code**: [`stewbeet/plugins/source_maps/mecha/__init__.py`](https://github.com/Stoupy51/StewBeet/blob/main/python_package/stewbeet/plugins/source_maps/mecha/__init__.py) <br>


## What it does

- Records every `write_function`, `write_versioned_function`, `.obj.append(...)` and friends, in call order
- Resolves each write back to the line and column of the Python that made it
- Follows a variable back to every literal it was assigned and grown with, so a command built in a loop maps to the literal line that spells it
- Follows a parameter annotated `McFunction` back to the call that passed it, so a function wrapping `write_function` maps to the literal its caller wrote
- Realigns the recorded lines against the final text, so post-processing like `auto.headers` does not shift the mapping
- Writes one `<name>.mcfunction.map` per function, beside the function and named after it. The function itself is untouched
- Maps content a plugin generated from one of your declarations back to that `Block(...)` or `Item(...)` call
- Maps what **mecha** compiled as well, so a `.bolt` module and a `.mcfunction` holding bolt lead back to their own lines
- Maps each line of a function both wrote to, like a load function a plugin prepends to, back to its own origin
- Never names a file inside StewBeet, beet, bolt, mecha or stouputils: a mapping points at your own source or at nothing

## Configuration

There is nothing to configure, and one entry to add:

```yaml
require:
    - "stewbeet"
    - "stewbeet.plugins.source_maps"
```

`stewbeet.plugins.source_maps` goes in `require`, next to `stewbeet` itself. Everything in `require` runs
before the pack is even loaded, so nothing can write a function before recording starts. Its position
within `require` does not matter. Recording the pack's own hand-written `.mcfunction` files as they
load costs nothing: they have no Python behind them, so they get no map.

To try it without editing `beet.yml`, or in a project whose snapshot tests compare the whole pack, ask for it on the command line:
`beet -s "require[]=stewbeet.plugins.source_maps" build`.

That is the whole configuration, `mecha` included: beet unwinds `require` last, so by the time this
plugin finishes, mecha has compiled and its compilation units are still there to be read.
`stewbeet.plugins.archive` writes the maps itself before it zips, so both the build directory and the zip that ends up in `saves/<world>/datapacks` carry the same thing.

If you package the pack some other way, add `stewbeet.plugins.source_maps.emit` to your pipeline, **after** every plugin that writes or rewrites functions and **before** whichever plugin packages it.
Forget it and the maps are still written at the very end of the build, with a warning naming the count whenever a packaging plugin already ran.

### <u>A project with no StewBeet writes in it</u>

A pure bolt or mecha project needs the same single line. Nothing calls the helpers, so nothing is recorded,
and every function mecha compiled is mapped from its AST:

```yaml
require:
    - "bolt"
    - "stewbeet.plugins.source_maps"
```

## What you get

A generated function is exactly what it always was:

```mcfunction
say Starting root
function tns:helper/do_work
```

And the sidecar beside it, `root.mcfunction.map`, names your own source relative to the project root:

```json
{
	"version": 3,
	"file": "root.mcfunction",
	"sources": ["src/link.py"],
	"names": [],
	"mappings": "AAKA;AACA;AACA"
}
```

`sourcesContent` is deliberately absent. Consumers read your sources from disk, and inlining a whole project into every map would cost tens of megabytes.
There is no `sourceRoot` either: Sniffer resolves it itself, so `sources` are plain paths from the project root and a consumer looks for the first folder above the map that holds them.

What mecha compiled carries more, for an editor showing your source to a vanilla parser:

- **A segment for each end of each AST node**, after the one at column 0, so a value bolt computed or a `~/child` path mecha resolved is found in the generated line column for column.
- **`x_stewbeet_bolt`**: the indices of the `sources` no vanilla parser reads, because bolt generated Python for them, mecha nested a function in them, one of their commands spans several lines, or one comes from a plugin.
- **`x_stewbeet_opaque`**: `[source, line, column]` where syntax a plugin added to mecha's command tree begins, read against the tree mecha ships for your Minecraft version.

Fields starting with `x_` are the standard's own room for vendors, so every other consumer ignores them.

## What is mapped, and what is not

A command you wrote yourself maps to the line you wrote it on. A command a plugin generated from one
of your declarations maps to the declaration, not to the plugin: ctrl+clicking inside a custom
block's `place_main` leads to your `Block(...)` call.

Scoped so far: `datapack.custom_blocks`, and the parts of `custom_recipes` that write a function per
item (smithed, furnace, pulverizer, awakened forge). Everything else a plugin generates on its own
account stays unmapped, which is the designed behaviour rather than a failure: an unmapped line costs
you nothing, a line pointing at the wrong place costs you a wasted search.

Two more things stay unmapped by design:

- **Pack-level scaffolding.** `custom_blocks/get_rotation` and friends are written once for the whole
  pack and belong to no declaration, so they are attributed to none.
- **Definitions with no Python declaration**, loaded from JSON or coming from `external_definitions`.
  There is no call to point at.

## Shipping a release

The maps are only in your build because you asked for them.
A release build that does not ask for them produces exactly the same datapack it always did, byte for byte, with no maps beside the functions.

## Next steps

- [Writing functions and files](../2_writing_to_files/en.md): the calls this plugin records.
- [All plugins](README.md): the rest of the pipeline, in the order it runs.
- [Configuring the build](../3_beet_config/en.md): enabling, ordering and configuring plugins.

