@barefootjs/mojolicious 0.17.0 → 0.18.0

package/src/__tests__/stock-route.test.ts

@@ -0,0 +1,203 @@
+// Stock-route smoke test for the Mojo scaffold contract (#2126).
+//
+// The scaffold's happy path is: `npm run dev` (which starts `bf build
+// --watch` and morbo *concurrently*), then open `/`. That page renders a
+// component whose EP template reads props/signals as bare scalars
+// (`% my $count = ($initial // 0);`), and Mojo templates compile under
+// `use strict` — so every one of those scalars must be declared by the
+// time the template runs. Two production bugs hid in that path:
+//
+//   1. The route passes no props, so the stash seeding has to come from
+//      the manifest's `ssrDefaults` via the plugin's `before_render`
+//      hook — including props only referenced through `props.X` reads.
+//   2. The plugin used to load the manifest once at register time, so
+//      booting before the first build wrote `manifest.json` disabled
+//      auto-init for the server's lifetime: every render of `/` died
+//      with `Global symbol "$initial" requires explicit package name`
+//      (HTTP 500) until a manual restart.
+//
+// This test boots a real Mojolicious app whose `app.pl` mirrors the
+// scaffold's (plugin + dist/templates renderer path + a `/` route that
+// passes NO props) against a template + manifest produced by the real
+// compiler, and asserts the page renders — in both boot orders. It is
+// the in-repo equivalent of "scaffold → build → curl / expects 200".
+//
+// Runs only when `perl` with Mojolicious is installed (same skip policy
+// as the conformance render tests). The DevReload plugin is omitted:
+// it's dev-only plumbing with its own coverage in t/dev_reload.t.
+
+import { describe, test, expect, beforeAll } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { compileJSX } from '@barefootjs/jsx'
+import { MojoAdapter } from '../adapter/mojo-adapter'
+
+const MOJO_LIB_DIR = path.resolve(import.meta.dir, '../../lib')
+const PERL_CORE_LIB_DIR = path.resolve(import.meta.dir, '../../../adapter-perl/lib')
+
+function perlWithMojoAvailable(): boolean {
+  try {
+    const proc = Bun.spawnSync(['perl', '-MMojolicious', '-MTest::Mojo', '-e1'], {
+      env: process.env,
+    })
+    return proc.exitCode === 0
+  } catch {
+    return false
+  }
+}
+
+const PERL_AVAILABLE = perlWithMojoAvailable()
+
+// The starter-Counter shape: a prop read only through `props.X ?? …`
+// (never passed by the stock route) feeding a signal, plus a memo.
+// Exactly the pattern that dies under strict when seeding breaks.
+// `props.label` is read directly in the body (no signal/memo in
+// between) — that flattens to a bare `<%= $label %>` too, so it pins
+// that ssrDefaults seeds every declared prop, not just the ones a
+// signal initializer references.
+const COUNTER_TSX = `'use client'
+
+import { createSignal, createMemo } from '@barefootjs/client'
+
+interface CounterProps {
+  initial?: number
+  label?: string
+}
+
+export function Counter(props: CounterProps) {
+  const [count, setCount] = createSignal(props.initial ?? 0)
+  const doubled = createMemo(() => count() * 2)
+
+  return (
+    <div className="counter">
+      <p className="counter-label">{props.label}</p>
+      <p className="counter-value">count: {count()}</p>
+      <p className="counter-doubled">doubled: {doubled()}</p>
+      <button onClick={() => setCount(n => n + 1)}>+1</button>
+    </div>
+  )
+}
+`
+
+// Mirrors the scaffold's app.pl essentials. The `/` route deliberately
+// passes NO props — the manifest seeding alone must carry it. The
+// second route pins that a caller-supplied prop still wins.
+const APP_PL = `#!/usr/bin/env perl
+use Mojolicious::Lite -signatures;
+
+plugin 'BarefootJS';
+
+app->renderer->paths->[0] = app->home->child('dist/templates');
+
+get '/' => sub ($c) {
+    $c->render(template => 'Counter', layout => 'default');
+};
+
+get '/with-prop' => sub ($c) {
+    $c->render(template => 'Counter', layout => 'default', initial => 5);
+};
+
+app->start;
+
+__DATA__
+
+@@ layouts/default.html.ep
+<!DOCTYPE html>
+<html><body>
+<main><%== content %></main>
+%== $c->bf->scripts
+</body></html>
+`
+
+// Test::Mojo harness. SMOKE_SCENARIO picks the boot order:
+//   manifest-at-boot   — the manifest exists before the app loads
+//                        (server restarted after a completed build).
+//   manifest-after-boot — the app loads first, the manifest appears
+//                        afterwards (the concurrent `bf build --watch`
+//                        + morbo dev race on a fresh scaffold).
+const SMOKE_PL = `use Mojo::Base -strict;
+use Test::More;
+use Test::Mojo;
+use Mojo::File qw(curfile path);
+
+my $home     = curfile->dirname;
+my $scenario = $ENV{SMOKE_SCENARIO} // 'manifest-at-boot';
+my $staged   = $home->child('manifest.staged.json');
+my $manifest = $home->child('dist/templates/manifest.json');
+
+unlink "$manifest";
+$staged->copy_to("$manifest") if $scenario eq 'manifest-at-boot';
+
+my $t = Test::Mojo->new($home->child('app.pl'));
+
+$staged->copy_to("$manifest") if $scenario eq 'manifest-after-boot';
+
+# Stock route: no props passed — manifest ssrDefaults must seed every
+# bare template scalar ($initial included) or strict mode 500s.
+$t->get_ok('/')->status_is(200)
+  ->text_like('p.counter-value',   qr/count:\\s*0/)
+  ->text_like('p.counter-doubled', qr/doubled:\\s*0/)
+  ->content_like(qr/Counter\\.client\\.js/, 'auto-init registered the client bundle');
+
+# Caller-supplied prop wins over the manifest default.
+$t->get_ok('/with-prop')->status_is(200)
+  ->text_like('p.counter-value',   qr/count:\\s*5/)
+  ->text_like('p.counter-doubled', qr/doubled:\\s*10/);
+
+done_testing;
+`
+
+describe.skipIf(!PERL_AVAILABLE)('Mojo scaffold stock route (#2126)', () => {
+  let appDir: string
+
+  beforeAll(() => {
+    appDir = mkdtempSync(path.join(tmpdir(), 'bf-mojo-stock-route-'))
+    mkdirSync(path.join(appDir, 'dist/templates'), { recursive: true })
+
+    const result = compileJSX(COUNTER_TSX, 'Counter.tsx', { adapter: new MojoAdapter() })
+    const template = result.files.find(f => f.type === 'markedTemplate')
+    const ssrDefaults = result.files.find(f => f.type === 'ssrDefaults')
+    if (!template || !ssrDefaults) throw new Error('compileJSX produced no template/ssrDefaults')
+
+    writeFileSync(path.join(appDir, 'dist/templates/Counter.html.ep'), template.content)
+    // Same entry shape `bf build` writes to dist/templates/manifest.json.
+    writeFileSync(
+      path.join(appDir, 'manifest.staged.json'),
+      JSON.stringify({
+        Counter: {
+          markedTemplate: 'templates/Counter.html.ep',
+          ssrDefaults: JSON.parse(ssrDefaults.content),
+        },
+      }),
+    )
+    writeFileSync(path.join(appDir, 'app.pl'), APP_PL)
+    writeFileSync(path.join(appDir, 'smoke.pl'), SMOKE_PL)
+  })
+
+  async function runScenario(scenario: string): Promise<void> {
+    const perl5lib = [MOJO_LIB_DIR, PERL_CORE_LIB_DIR, process.env.PERL5LIB]
+      .filter(Boolean)
+      .join(':')
+    const proc = Bun.spawn(['perl', 'smoke.pl'], {
+      cwd: appDir,
+      env: { ...process.env, PERL5LIB: perl5lib, SMOKE_SCENARIO: scenario },
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ])
+    expect(exitCode, `TAP output:\n${stdout}\n${stderr}`).toBe(0)
+  }
+
+  test('renders / with the manifest present at boot', async () => {
+    await runScenario('manifest-at-boot')
+  })
+
+  test('renders / when the manifest appears after boot (concurrent dev-startup race)', async () => {
+    await runScenario('manifest-after-boot')
+  })
+})

package/src/adapter/expr/array-method.ts

@@ -372,6 +372,27 @@ export function renderFlatMapEval(
   return `bf->flat_map_eval(${recv}, '${escapePerlSingleQuote(json)}', '${param}', ${env})`
 }
 
+/**
+ * Emit a value-producing `.map(cb)` via the runtime evaluator (#2073): the
+ * projection `body` serializes to JSON and `bf->map_eval` projects each
+ * element, one result per element (no flatten — the JS `.map` contract).
+ * Composes through the array-method chain (`.map(cb).join(' ')`). Returns
+ * null when the projection is outside the evaluator surface, and the caller
+ * records BF101. The JSX-returning `.map` is an IRLoop upstream and never
+ * reaches this emit.
+ */
+export function renderMapEval(
+  recv: string,
+  body: ParsedExpr,
+  param: string,
+  emit: (e: ParsedExpr) => string,
+): string | null {
+  const json = serializeParsedExpr(body)
+  if (json === null) return null
+  const env = emitEvalEnvArg(body, [param], emit)
+  return `bf->map_eval(${recv}, '${escapePerlSingleQuote(json)}', '${param}', ${env})`
+}
+
 /**
  * Shared Mojo emit for `.sort(cmp)` / `.toSorted(cmp)` (#1448 Tier B).
  * Used by both the filter-context emitter and the top-level emitter,
@@ -402,7 +423,28 @@ export function renderSortMethod(recv: string, c: SortComparator): string {
 // `.flat(depth?)` → `bf->flat($recv, $depth)`. The `Infinity` form lowers
 // to the `-1` sentinel (flatten fully); a finite depth flattens that many
 // levels (`0` = shallow copy). See `sub flat` in BarefootJS.pm. (#1448)
-export function renderFlatMethod(recv: string, depth: FlatDepth): string {
+export function renderFlatMethod(
+  recv: string,
+  depth: FlatDepth | { expr: ParsedExpr },
+  emit: (e: ParsedExpr) => string,
+): string {
+  if (typeof depth === 'object') {
+    // Dynamic depth (#2094): routed to a SEPARATE runtime helper
+    // (`bf->flat_dynamic`), not `bf->flat`. The literal-depth path below
+    // already uses `-1` as a compile-time SENTINEL baked into the template
+    // source meaning "the source literally said `Infinity`". A genuinely
+    // dynamic depth that happens to evaluate to `-1` at render time means
+    // the OPPOSITE in real JS (`[1,[2]].flat(-1)` never recurses — same as
+    // `.flat(0)`). Since both paths would otherwise hand the same
+    // literal-looking argument to one shared helper, that helper couldn't
+    // tell which case it's in — so `flat_dynamic` performs its own
+    // `ToIntegerOrInfinity`-style coercion (truncate toward zero; negative
+    // -> 0; NaN/non-numeric -> 0; +Infinity or a huge finite value ->
+    // flatten fully) and then delegates to `flat`. See `sub flat_dynamic`
+    // in BarefootJS.pm and the Go reference (`FlatDynamicDepth`/
+    // `coerceFlatDepth` in bf.go).
+    return `bf->flat_dynamic(${recv}, ${emit(depth.expr)})`
+  }
   const d = depth === 'infinity' ? -1 : depth
   return `bf->flat(${recv}, ${d})`
 }

package/src/adapter/expr/emitters.ts

@@ -38,6 +38,7 @@ import {
   renderPredicateEval,
   renderFlatMethod,
   renderFlatMapEval,
+  renderMapEval,
 } from './array-method.ts'
 
 /**
@@ -81,6 +82,11 @@ export class MojoFilterEmitter implements ParsedExprEmitter {
     // against it lowers to `eq`/`ne` (#1672). Defaults to "never" for callers
     // that don't thread it through.
     private readonly isStringName: (n: string) => boolean = () => false,
+    // Records a BF101 for nested callback shapes this emitter can only
+    // degrade — `find*` and the non-predicate methods (#2038). Optional so
+    // emitter construction stays possible without an adapter; a missing hook
+    // keeps the old silent-degrade emit.
+    private readonly onUnsupported?: (message: string, reason?: string) => void,
   ) {}
 
   identifier(name: string): string {
@@ -172,20 +178,34 @@ export class MojoFilterEmitter implements ParsedExprEmitter {
   ): string {
     // Filter context only meaningfully handles the predicate methods
     // (filter / every / some land here through nested `.filter(...)` chains).
-    // Sort / reduce / flatMap never arise inside a predicate, so route them to
-    // the truthy sentinel like the old `default` arm did.
-    if (!PREDICATE_METHODS.has(method)) return '1'
+    // Sort / reduce / flatMap have no scalar Perl form here — the old
+    // `default` arm degraded them to the truthy sentinel, silently rewriting
+    // the predicate, so surface BF101 instead (#2038).
+    if (!PREDICATE_METHODS.has(method)) {
+      this.onUnsupported?.(
+        `Filter predicate contains a nested '.${method}(...)' callback, which has no Perl scalar form`,
+        `Rewrite the predicate without a nested callback method, or add /* @client */ for client-only evaluation (no SSR).`,
+      )
+      return '1'
+    }
     // The predicate body is also a filter context, but with this
     // callback's own `param` (potentially shadowing the outer one),
     // so we spin up a nested emitter with the inner param.
     const param = arrow.params[0]
     const predicate = arrow.body
     const arrayExpr = emit(object)
-    const predBody = emitParsedExpr(predicate, new MojoFilterEmitter(param, this.localVarMap, this.isStringName))
+    const predBody = emitParsedExpr(predicate, new MojoFilterEmitter(param, this.localVarMap, this.isStringName, this.onUnsupported))
     const grepBody = predBody.replace(new RegExp(`\\$${param}\\b`, 'g'), '$_')
     if (method === 'filter') return `[grep { ${grepBody} } @{${arrayExpr}}]`
     if (method === 'every') return `!(grep { !(${grepBody}) } @{${arrayExpr}})`
     if (method === 'some') return `!!(grep { ${grepBody} } @{${arrayExpr}})`
+    // `find` / `findIndex` / `findLast` / `findLastIndex` return an element
+    // (or index), not a boolean — there is no inline grep form. Degrading to
+    // the receiver silently changes predicate semantics, so be loud (#2038).
+    this.onUnsupported?.(
+      `Filter predicate contains a nested '.${method}(...)' callback, which has no Perl scalar form`,
+      `Rewrite the predicate without a nested callback method, or add /* @client */ for client-only evaluation (no SSR).`,
+    )
     return arrayExpr
   }
 
@@ -212,8 +232,12 @@ export class MojoFilterEmitter implements ParsedExprEmitter {
     return renderArrayMethod(method, object, args, emit)
   }
 
-  flatMethod(object: ParsedExpr, depth: FlatDepth, emit: (e: ParsedExpr) => string): string {
-    return renderFlatMethod(emit(object), depth)
+  flatMethod(
+    object: ParsedExpr,
+    depth: FlatDepth | { expr: ParsedExpr },
+    emit: (e: ParsedExpr) => string,
+  ): string {
+    return renderFlatMethod(emit(object), depth, emit)
   }
 
   conditional(_test: ParsedExpr, _consequent: ParsedExpr, _alternate: ParsedExpr): string {
@@ -448,6 +472,18 @@ export class MojoTopLevelEmitter implements ParsedExprEmitter {
       return "''"
     }
 
+    // Value-producing map (#2073): eval-only; BF101 when the projection is
+    // outside the surface. (The JSX-returning `.map` is an IRLoop upstream.)
+    if (method === 'map') {
+      const evalForm = renderMapEval(recv, body, params[0], emit)
+      if (evalForm !== null) return evalForm
+      this.ctx._recordExprBF101(
+        `.map(...) projection is not lowerable to a template map`,
+        `Pre-compute the projection in the route handler, or mark the position @client-only.`,
+      )
+      return "''"
+    }
+
     // Predicate methods: filter / find / every / some / findIndex / findLast /
     // findLastIndex. Eval-first (#2018 P2), then the inline `grep` / `bf->find`
     // fallback for a predicate the evaluator can't model.
@@ -527,8 +563,12 @@ export class MojoTopLevelEmitter implements ParsedExprEmitter {
     return renderArrayMethod(method, object, args, emit)
   }
 
-  flatMethod(object: ParsedExpr, depth: FlatDepth, emit: (e: ParsedExpr) => string): string {
-    return renderFlatMethod(emit(object), depth)
+  flatMethod(
+    object: ParsedExpr,
+    depth: FlatDepth | { expr: ParsedExpr },
+    emit: (e: ParsedExpr) => string,
+  ): string {
+    return renderFlatMethod(emit(object), depth, emit)
   }
 
   conditional(
@@ -596,12 +636,16 @@ export class MojoTopLevelEmitter implements ParsedExprEmitter {
     return "''"
   }
 
-  objectLiteral(_properties: ObjectLiteralProperty[], _raw: string, _emit: (e: ParsedExpr) => string): string {
-    // Mirror `unsupported`: a bare object literal reaching the dispatcher
-    // lowers to the safe Perl empty-string literal, exactly as before the
-    // `object-literal` kind existed (byte-identical; Roadmap A-1). Object
-    // values that round-trip to a Perl hashref go through the dedicated
-    // `objectLiteralToPerlHashref` lowering in the conditional/attr paths.
-    return "''"
+  objectLiteral(properties: ObjectLiteralProperty[], _raw: string, _emit: (e: ParsedExpr) => string): string {
+    // The shared `isSupported` gate only ever lets this dispatcher see an
+    // object literal as the EMPTY (`?? {}`) fallback operand of `??`
+    // (expression-parser.ts, `logical` case) — any other object literal is
+    // refused before reaching here. Emit Perl's real empty hashref literal,
+    // matching the `'{}'` convention `objectLiteralToPerlHashref` already
+    // uses for the zero-property case in the spread path. A populated
+    // literal is structurally unreachable given the gate, but still
+    // degrades safely to the pre-existing empty-string sentinel rather
+    // than silently dropping keys.
+    return properties.length === 0 ? '{}' : "''"
   }
 }

package/src/adapter/lib/ir-scope.ts

@@ -55,16 +55,3 @@ export function collectRootScopeNodes(node: IRNode): Set<IRNode> {
   visit(node)
   return out
 }
-
-/**
- * True when every `$var` the lowered (Perl / Kolon) expression references is
- * in the available set — i.e. the template already has that var in scope.
- * Guards in-template memo seeding from referencing an out-of-scope binding
- * (which would trip Perl strict mode). (#1297)
- */
-export function referencedVarsAreAvailable(expr: string, available: ReadonlySet<string>): boolean {
-  for (const m of expr.matchAll(/\$([A-Za-z_]\w*)/g)) {
-    if (!available.has(m[1])) return false
-  }
-  return true
-}

package/src/adapter/memo/seed.ts

@@ -13,13 +13,10 @@ import {
   type ComponentIR,
   type ContextConsumer,
   collectContextConsumers,
-  extractArrowBodyExpression,
-  isSupported,
-  parseExpression,
+  computeSsrSeedPlan,
 } from '@barefootjs/jsx'
 
 import type { MojoMemoContext } from '../emit-context.ts'
-import { referencedVarsAreAvailable } from '../lib/ir-scope.ts'
 
 /** Perl literal for a context-consumer's `createContext` default. */
 export function contextDefaultPerl(c: ContextConsumer): string {
@@ -49,78 +46,28 @@ export function generateContextConsumerSeed(ir: ComponentIR): string {
 }
 
 /**
- * Seed memos whose SSR default is `null` (not statically evaluable) by
- * computing them in-template from the already-seeded prop / signal vars.
- * Targets the prop-derived memo shape (`createMemo(() => props.value * 10)`)
- * that the static `extractSsrDefaults` evaluator can't fold — without this
- * the memo's `$x` renders empty (the reason `props-reactivity-comparison`
- * was skipped). Only emitted when the lowered expression references vars the
- * template already has in scope (props params + signals + prior memos), so a
- * memo over an out-of-scope binding stays on the null path rather than
- * tripping Perl strict mode. (#1297)
+ * Emit `% my $<name> = <perl>;` seed lines for every `derived` step of the
+ * backend-neutral SSR seed plan — the scope/availability/ordering analysis
+ * lives in `computeSsrSeedPlan` (packages/jsx/src/ssr-seed-plan.ts); this
+ * only lowers each step's expression to Perl and applies the two
+ * backend-specific emit guards: skip an empty lowering, and skip a lowering
+ * that references no `$var` at all (a constant init/body — e.g. a `derived`
+ * step with empty `frees` — keeps the existing static ssr-defaults seed
+ * instead). `env-reader` and `opaque` steps emit nothing (the runtime
+ * supplies the reader, or the adapter's ssr-defaults path already covers it).
+ * (#1297, #2075)
  */
 export function generateDerivedMemoSeed(ctx: MojoMemoContext, ir: ComponentIR): string {
-  const memos = ir.metadata.memos ?? []
-  const signals = ir.metadata.signals ?? []
-  if (memos.length === 0 && signals.length === 0) return ''
-  // Props seed first; each signal/memo adds its own name as it lands so a
-  // later one can reference an earlier one.
-  const available = new Set<string>(ir.metadata.propsParams.map(p => p.name))
+  // Package G attached this to metadata at compile time; the `??` fallback
+  // only covers hand-built metadata in older tests that predate the attached
+  // plan — same shared function, so there's no divergence from the compiler.
+  const plan = ir.metadata.ssrSeedPlan ?? computeSsrSeedPlan(ir.metadata)
   const lines: string[] = []
-
-  // Prop/signal-derived signals (`createSignal(props.defaultOn ?? false)`):
-  // a loop-child render receives no stash seed for the signal, so its `$on`
-  // would trip strict mode; and even when an entry render seeds it, the
-  // static default can't capture the per-call prop. Seed it in-template from
-  // the passed prop — but ONLY when the init lowers cleanly AND references an
-  // in-scope var (i.e. it's genuinely derived). Object/array/constant inits
-  // (`createSignal({…})`, `createSignal([…])`, `createSignal('b')`) keep the
-  // existing ssr-defaults seeding, so the spread / loop fixtures are
-  // untouched.
-  for (const signal of signals) {
-    const perl = tryLowerToPerl(ctx, signal.initialValue, available)
-    if (perl !== null) lines.push(`% my $${signal.getter} = ${perl};`)
-    available.add(signal.getter)
-  }
-
-  for (const memo of memos) {
-    // Seed every memo whose body lowers cleanly — not just the ones whose
-    // static SSR default is null. A statically-foldable prop-derived memo
-    // (`createMemo(() => props.disabled ?? false)` → default `false`)
-    // still depends on the per-call prop: the static stash seed bakes in
-    // the absent-prop fold, so a caller passing `disabled => 1` would
-    // render the default branch (#1897, select's disabled item). The
-    // in-template recomputation reads the prop lexical the stash already
-    // seeded, so it's correct per call; block-bodied arrows /
-    // out-of-scope references fall back to the static ssr-defaults seed.
-    const body = extractArrowBodyExpression(memo.computation)
-    if (body !== null) {
-      const perl = tryLowerToPerl(ctx, body, available)
-      if (perl !== null) lines.push(`% my $${memo.name} = ${perl};`)
-    }
-    available.add(memo.name)
+  for (const step of plan.steps) {
+    if (step.kind !== 'derived') continue
+    const perl = ctx.convertExpressionToPerl(step.expr, step.parsed)
+    if (perl === '' || !/\$[A-Za-z_]\w*/.test(perl)) continue
+    lines.push(`% my $${step.name} = ${perl};`)
   }
   return lines.length > 0 ? lines.join('\n') + '\n' : ''
 }
-
-/**
- * Lower a signal init / memo body to Perl for an in-template SSR seed, or
- * `null` when it shouldn't be seeded this way. Returns null — without
- * recording a BF101 — when the expression isn't a supported shape
- * (`isSupported` pre-check, so object/array literals don't fail the build),
- * when the lowering references no in-scope var (a constant — keep the
- * existing ssr-defaults seeding), or when it references an out-of-scope
- * binding. (#1297)
- */
-export function tryLowerToPerl(
-  ctx: MojoMemoContext,
-  expr: string,
-  available: ReadonlySet<string>,
-): string | null {
-  const trimmed = expr.trim()
-  if (!trimmed) return null
-  if (!isSupported(parseExpression(trimmed)).supported) return null
-  const perl = ctx.convertExpressionToPerl(trimmed)
-  if (perl === '' || !/\$[A-Za-z_]\w*/.test(perl)) return null
-  return referencedVarsAreAvailable(perl, available) ? perl : null
-}