Module: lib/compiler/bundle/validate

Proves that emitted JavaScript parses before the build is allowed to call itself successful.

Why this is a separate, unconditional step

The compiler could previously emit a bundle containing

const { AvenxGuard } = Avenx;
const { AvenxGuard } = Avenx;

and report Build successful. The generated file was not JavaScript; the application did not start; nothing in the pipeline noticed, because nothing in the pipeline ever asked whether the output it had just written could be parsed. That specific collision cannot happen any more -- every module is its own scope now, so two files declaring the same name simply coexist -- but a code generator that is only correct because its known failure modes have been fixed one at a time is a generator whose next failure ships silently.

So this check is not about guards. It establishes the invariant:

avenx build reports success  =>  the emitted JavaScript parses

How

node:vm compiles the source without running it. That is a real parse by the same engine that will parse the file in production, it needs no dependency, and it costs a few milliseconds on a bundle of this size.

Validation happens against the staging directory, before promotion, so a bundle that fails never reaches dist/ at all — the previous build's output is left intact rather than being replaced by something broken.

Source:

Methods

(static) assertRuntimeCapabilities(outputs, required)

Asserts that the bundle carries the runtime capabilities the build linked.

The compiler decides what a bundle needs from what it saw while compiling: a template the IR refused puts the string renderer into the entry graph, and the build then tells the developer, through AVX_W47, that their component renders through it. That sentence has to be true of the artifact, not just of the intent.

It stopped being true once. The string renderer registers itself into a module-scoped registry, and a build that linked the same runtime file twice -- which a symlinked avenx-core used to cause -- filled one copy of that registry while the component consulted the other. The build reported success and the application rendered nothing.

Resolution no longer produces two copies of a file, so that specific cause is gone. This check is here because the property is worth asserting on the output regardless of which defect might break it next: a capability the build committed to is either in the bundle or the build fails.

Parameters:
Name Type Description
outputs Map:.<string:, string:>

Artifact name to contents.
required Array:.<{capability:: string:, reason:: string:, evidence:: string:}>
  • Capabilities the build linked. evidence is a pattern source that can only match if the capability was linked and executed, never merely defined.
Source:
Throws:

AVX_C23 when a linked capability is absent.

Type
BuildError

(static) assertValidJavaScript(code, artifact)

Asserts that a string of emitted JavaScript parses as a classic script.

The bundle is a classic script, not a module: it is loaded with a plain <script src> tag, and every specifier in it has been resolved into the graph rather than left for a module loader. Parsing it as a script is therefore the same parse the browser will perform.

Parameters:
Name Type Description
code string

The emitted JavaScript.
artifact string

The artifact name, used in the diagnostic.
Source:
Throws:

AVX_C15 when the source does not parse.

Type
BuildError

(static) assertValidOutputs(outputs)

Validates every JavaScript artifact in a build's output set.

Parameters:
Name Type Description
outputs Map:.<string:, string:>

Artifact name to contents.
Source:
Throws:

When any .js artifact does not parse.

Type
BuildError

(inner) excerpt(source, lineNumber) → {string}

Extracts the offending line from a source, for the error message.

A syntax error in a 190 KB single-line minified bundle is unreadable without an excerpt, and the line number alone points at a file the developer did not write. Showing the text is what makes the diagnostic actionable.

Parameters:
Name Type Description
source string

The emitted source.
lineNumber number

1-based line number.
Source:
Returns:

A trimmed excerpt, or an empty string.

Type
string

(inner) lineFromStack(error, filename) → {number}

Reads the line number out of a V8 syntax error's stack.

V8 reports the position as <filename>:<line> on the stack's first line. It is not exposed as a structured property, so it has to be read back out.

Parameters:
Name Type Description
error Error

The thrown SyntaxError.
filename string

The filename passed to the compiler.
Source:
Returns:

The 1-based line, or 0 when it cannot be determined.

Type
number