Module: lib/compiler/sourceMapTrace

Builds the source-location sidecar that avenx trace view uses.

A trace records the source text of every action and computed it ran, which is already more than a compiled framework can offer. What it cannot know at runtime is where that text came from — the bundle is one concatenated script with no file boundaries left in it.

The compiler does know, so it writes the answer beside the bundle rather than inside it. bundle.trace.json is emitted next to bundle.js and is not referenced by it: an application that never records a trace downloads nothing extra, and a deployment that does not want the file simply does not upload it.

Source:

Methods

(static) annotateTrace(trace, sidecar) → {object}

Annotates a trace's nodes with the source locations the sidecar holds.

Applied when a trace is read, not when it is recorded: a trace stays a record of what happened, and the mapping from that to a file and a line is a property of the build it came from.

Parameters:
Name Type Description
trace object

The trace to annotate. Mutated in place.
sidecar object | null

The sidecar, or null to leave the trace alone.
Source:
Returns:

The same trace.

Type
object

(static) buildSidecar(components, bridgesopt, rootDiropt) → {object}

Assembles the sidecar document.

Parameters:
Name Type Attributes Description
components Map:.<string:, object:>

Entries keyed by class name.
bridges Map:.<string:, object:> <optional>

Bridge descriptors. The compiler keys these by absolute path, so the descriptor's own name is used for the sidecar rather than the map key — a trace records bridge names, not paths.
rootDir string <optional>

The project root, for relative bridge paths.
Source:
Returns:

The sidecar, ready to serialize.

Type
object

(static) collectLocations(unit) → {object}

Collects the source locations of one component's declarations.

Parameters:
Name Type Description
unit object

What the parser extracted.

Properties
Name Type Attributes Description
name string

The component class name.
filePath string

Absolute path to the source file.
rootDir string

The project root, for relative paths.
content string

The file contents.
computed object <optional>

Computed definitions by name.
methods object <optional>

Action bodies by name.
resources object <optional>

Resource definitions by name.
contracts Set:.<string:> <optional>

Declared contracts.
Source:
Returns:

The component's sidecar entry.

Type
object

(static) sidecarFileName(outputName) → {string}

The file name the sidecar is written under, given a bundle name.

Parameters:
Name Type Description
outputName string

The configured bundle name, e.g. bundle.
Source:
Returns:

The sidecar file name.

Type
string

(inner) escape(name) → {string}

Escapes a name for use inside a regular expression.

Parameters:
Name Type Description
name string

The declared name.
Source:
Returns:

The escaped name.

Type
string

(inner) lineOf(source, pattern) → {number|null}

Finds the 1-based line a pattern first occurs on.

Parameters:
Name Type Description
source string

The file contents.
pattern RegExp

What to look for.
Source:
Returns:

The line number, or null when absent.

Type
number | null