All files / lib/compiler/bundle validate.js

95% Statements 323/340
82.92% Branches 68/82
87.5% Functions 7/8
95% Lines 323/340

Press n or j to go to the next uncovered block, b, p or k for the previous block.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 7x 7x 7x 7x 7x 7x 7x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x             458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 201x 201x 201x 201x 201x 9x     9x 9x 9x 9x 9x 9x               9x 9x 9x 9x 201x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 198x 128x 128x 70x 70x 72x 71x 70x 70x 70x 71x 83x     70x 70x 70x 70x 70x 70x 70x 70x 1x 1x 1x 1x 1x 1x 1x 70x 198x 458x 458x 458x 458x 458x 458x 458x 192x 996x 201x 201x 996x 192x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 195334x 195334x 1x 1x 195333x 195333x 195333x 195333x 195333x 195334x 2x 2x 195331x 195331x 195331x 195331x 195334x 195334x 195334x 4236x 195334x 3x 3x 195328x 195328x 195334x 458x 458x 458x 458x 458x 458x 195328x 195328x 1177730x 396418x 1177730x 35420x 58759x 58759x 1177730x 136574x 136574x 1177730x 195328x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 458x 18x 31x 14x 14x 17x 17x 17x 17x 17x 17x 17x 17x 17x 17x 17x 17x 17x 17x 31x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 16x 16x 31x 195334x 195334x 195334x 6x 6x 6x 6x 6x 6x 6x 6x 6x 195334x 195327x 195327x 195328x 31x 18x  
/**
 * @file validate.js
 * @description 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
 *
 * ```js
 * 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:
 *
 * ```text
 * 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.
 *
 * A page chunk is an ES module rather than a classic script, and `vm.Script`
 * cannot parse one, so a `SyntaxError` from V8 is retried with the compiler's
 * own parser in module mode before it is reported.
 *
 * 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.
 *
 * ## What else lives here
 *
 * Two further checks, on the same terms: the build may not report success
 * unless the artifact has the properties the build committed to.
 * {@link assertRuntimeCapabilities} covers the runtime modules the compiler
 * decided to link, and {@link assertNoDynamicCode} — only under `csp.strict` —
 * covers the absence of anything that would need `script-src 'unsafe-eval'`.
 * Both are assertions about the emitted file rather than about the compiler's
 * intentions, which is the whole reason they are not simply comments.
 * @module lib/compiler/bundle/validate
 */
 
import vm from 'vm';
import { parse } from '../parser/js/parser.js';
import { AvenxErrorCodes } from '../../core/runtime/AvenxError.js';
import { BuildError } from '../errors/index.js';
 
/**
 * 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.
 * @param {string} source - The emitted source.
 * @param {number} lineNumber - 1-based line number.
 * @returns {string} A trimmed excerpt, or an empty string.
 */
function excerpt(source, lineNumber) {
  if (!Number.isInteger(lineNumber) || lineNumber < 1) return '';
  const line = source.split(/\r?\n/)[lineNumber - 1];
  if (typeof line !== 'string') return '';
  const trimmed = line.trim();
  return trimmed.length > 200 ? `${trimmed.slice(0, 200)}…` : trimmed;
}
 
/**
 * 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.
 * @param {Error} error - The thrown SyntaxError.
 * @param {string} filename - The filename passed to the compiler.
 * @returns {number} The 1-based line, or 0 when it cannot be determined.
 */
function lineFromStack(error, filename) {
  const stack = typeof error.stack === 'string' ? error.stack : '';
  const escaped = filename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
  const match = stack.match(new RegExp(`${escaped}:(\\d+)`));
  return match ? Number(match[1]) : 0;
}
 
/**
 * 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.
 * @param {string} code - The emitted JavaScript.
 * @param {string} artifact - The artifact name, used in the diagnostic.
 * @throws {BuildError} AVX_C15 when the source does not parse.
 */
export function assertValidJavaScript(code, artifact) {
  try {
    // Compiling is enough: the script is never run, so no application code
    // executes during a build.
    new vm.Script(code, { filename: artifact });
  } catch (error) {
    if (!(error instanceof SyntaxError)) {
      throw error;
    }
    // An ES module -- a page chunk with import/export -- is not a classic
    // script, so V8 refusing it proves nothing until it has been read as one.
    try {
      parse(code, { ecmaVersion: 'latest', sourceType: 'module' });
      return;
    } catch {
      // Fall through to report classic script error
    }
    const line = lineFromStack(error, artifact);
    throw new BuildError(
      AvenxErrorCodes.COMPILER_INVALID_OUTPUT,
      artifact,
      error.message,
      line > 0 ? String(line) : 'unknown',
      excerpt(code, line) || '(source line unavailable)',
    );
  }
}
 
/**
 * 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.
 * @param {Map<string, string>} outputs - Artifact name to contents.
 * @param {Array<{capability: string, reason: string, evidence: string}>} required
 *   - Capabilities the build linked. `evidence` is a pattern source that can
 *   only match if the capability was linked *and* executed, never merely
 *   defined.
 * @throws {BuildError} AVX_C23 when a linked capability is absent.
 */
export function assertRuntimeCapabilities(outputs, required) {
  if (!Array.isArray(required) || required.length === 0) {
    return;
  }
 
  let bundle = null;
  for (const [name, contents] of outputs) {
    if (name.endsWith('.js') && !name.endsWith('.map') && typeof contents === 'string') {
      bundle = contents;
      break;
    }
  }
  if (bundle === null) {
    return;
  }
 
  for (const { capability, reason, evidence } of required) {
    // A pattern rather than a substring, because the obvious substring is the
    // wrong test: `installStringRenderer(` matches the function's own
    // declaration, which survives in the bundle whenever anything imports the
    // registry -- and `AvenxComponent` always does, to read from it. The
    // evidence has to distinguish the call from the definition.
    if (!new RegExp(evidence).test(bundle)) {
      throw new BuildError(
        AvenxErrorCodes.COMPILER_MISSING_RUNTIME_CAPABILITY,
        capability,
        reason,
        evidence,
      );
    }
  }
}
 
/**
 * Validates every JavaScript artifact in a build's output set.
 * @param {Map<string, string>} outputs - Artifact name to contents.
 * @throws {BuildError} When any `.js` artifact does not parse.
 */
export function assertValidOutputs(outputs) {
  for (const [name, contents] of outputs) {
    if (name.endsWith('.js') && typeof contents === 'string') {
      assertValidJavaScript(contents, name);
    }
  }
}
 
/**
 * Constructs that make a script need `'unsafe-eval'`, by AST node shape.
 *
 * A text search is the obvious implementation and the wrong one. The string
 * `"new Function("` appears in this repository's own comments and in the
 * diagnostic messages the runtime carries, so a bundle that evaluates nothing
 * still matches it -- and a build that failed on its own documentation would
 * teach developers to switch the check off. Matching node shapes instead means
 * the scan sees what the engine will execute and nothing else.
 *
 * `document.write`, `setTimeout("…")` and `javascript:` URLs are governed by
 * other directives and are not in scope here: this check is about
 * `'unsafe-eval'` specifically, and a check that claimed more than it tested
 * would be worse than none.
 * @param {object} node - An ESTree node.
 * @returns {string|null} What the node is, or null when it is not one of them.
 */
function dynamicCodeConstruct(node) {
  if (node.type === 'WithStatement') {
    return 'a with-statement';
  }
 
  // `eval(…)`, and only the direct call: `window.eval` is a member read, which
  // CSP governs the same way but which cannot appear in output this compiler
  // produces -- and a check that guessed at member expressions would have to
  // guess about every object named `eval` as well.
  if (node.type === 'CallExpression' && node.callee && node.callee.type === 'Identifier' && node.callee.name === 'eval') {
    return 'a call to eval';
  }
 
  // `new Function(…)` and `Function(…)`. The bare call is the same constructor
  // and the same CSP requirement, so both shapes count.
  if (
    (node.type === 'NewExpression' || node.type === 'CallExpression') &&
    node.callee &&
    node.callee.type === 'Identifier' &&
    node.callee.name === 'Function'
  ) {
    return node.type === 'NewExpression' ? 'the Function constructor' : 'a call to Function';
  }
 
  return null;
}
 
/**
 * Walks every child node of an ESTree node.
 * @param {object} node - The node.
 * @yields {object} Each child node.
 */
function* children(node) {
  for (const key of Object.keys(node)) {
    if (key === 'type' || key === 'start' || key === 'end' || key === 'loc') continue;
    const value = node[key];
    if (Array.isArray(value)) {
      for (const item of value) {
        if (item && typeof item === 'object' && typeof item.type === 'string') yield item;
      }
    } else if (value && typeof value === 'object' && typeof value.type === 'string') {
      yield value;
    }
  }
}
 
/**
 * Asserts that an emitted artifact cannot construct code from a string.
 *
 * This is what `csp.strict` actually buys, and it is deliberately a property of
 * the *file* rather than of the build's intentions. The compiler already knows
 * which modules it chose not to link, and could report on that basis; but the
 * claim a developer relies on is about the script their browser downloads, and
 * the gap between the two is exactly where a mistake would hide -- a
 * dependency that evaluates source, a runtime module reachable by a path the
 * compiler did not consider, a future refactor that puts the interpreter back
 * into the graph.
 *
 * Only reached when the option is on. Parsing a bundle costs tens of
 * milliseconds, which is nothing against a build but is not worth spending on
 * a project that has not asked for the guarantee.
 * @param {Map<string, string>} outputs - Artifact name to contents.
 * @throws {BuildError} AVX_C32 when an artifact can evaluate source at run time.
 */
export function assertNoDynamicCode(outputs) {
  for (const [name, contents] of outputs) {
    if (!name.endsWith('.js') || name.endsWith('.map') || typeof contents !== 'string') {
      continue;
    }
 
    // The same parse shape `assertValidJavaScript` uses, for the same reason:
    // the bundle is a classic script loaded with `<script src>`.
    //
    // A failure here cannot be ignored. `assertValidOutputs` has already
    // compiled this artifact with V8, so the compiler's parser refusing it
    // means the two disagree about what JavaScript is -- and skipping the
    // artifact would leave the build claiming a guarantee it had not checked.
    // It is reported as the invalid-output defect it is. The differential test
    // in test/unit/jsParserDifferential.test.js exists to keep that
    // disagreement from being this parser's fault.
    let program;
    try {
      program = parse(contents, { ecmaVersion: 'latest', sourceType: 'script', locations: true });
    } catch (error) {
      try {
        program = parse(contents, { ecmaVersion: 'latest', sourceType: 'module', locations: true });
      } catch {
        // Fall back to reporting the classic script error
        const line = typeof error.loc === 'object' && error.loc ? error.loc.line : 0;
        throw new BuildError(
          AvenxErrorCodes.COMPILER_INVALID_OUTPUT,
          name,
          `it could not be parsed for the csp.strict check: ${error.message}`,
          line > 0 ? String(line) : 'unknown',
          excerpt(contents, line) || '(source line unavailable)',
        );
      }
    }
 
    const stack = [program];
    while (stack.length > 0) {
      const node = stack.pop();
      const construct = dynamicCodeConstruct(node);
      if (construct) {
        const line = node.loc ? node.loc.start.line : 0;
        throw new BuildError(
          AvenxErrorCodes.COMPILER_CSP_STRICT_DYNAMIC_CODE,
          name,
          construct,
          line > 0 ? String(line) : 'unknown',
          excerpt(contents, line) || '(source line unavailable)',
        );
      }
      for (const child of children(node)) {
        stack.push(child);
      }
    }
  }
}