Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

45.2 KB
Raw Blame
/**
 * Kiln Code Validation (W3b.3 - AST-hardened)
 *
 * Validates generated Kiln code before rendering. Catches:
 *  - Missing/stray imports + exports (regex, cheap)
 *  - Missing `meta` const / `build` function (AST, accurate)
 *  - `value:` keyframe typos (regex, cheap)
 *  - Infinite loops (`while(true)`, `for(;;)` without break) — AST
 *  - Recursive `build()` calls that'd blow the stack — AST
 *  - Ambient-runtime, dynamic-code, and raw material-constructor access — AST
 *  - Lexical bindings read before their declaration runs, and literal
 *    materialRecipe IDs or overrides the recipe does not list — AST
 *  - Triangle budget estimate — AST sum of geometry calls
 *  - Syntax errors — acorn throws with line numbers
 *
 * Results are compatible with the prior shape (`valid` + `errors`) — the new
 * structured `errors` / `warnings` arrays are additive.
 *
 * Not caught statically (runtime-only, surfaced via renderGLB warnings):
 *  - Animation track targets that don't match any scene node
 *  - `build()` returning a non-Object3D
 *
 * Returned `code` values follow {@link KilnCodeValidationFailed} conventions —
 * see packages/core/src/errors.ts.
 */

import * as acorn from 'acorn';
import * as walk from 'acorn-walk';
import { listHelperSpecs } from './discovery/helper-specs';
import { REMOVED_AUTHORING_HELPERS } from './geometry-catalog';
import { sourceBindings } from './source-bindings';
import { AuthoringDiagnosticError } from './evaluator/authoring-diagnostic';
import { analyzeBuildTimeThrows } from './source-runtime-checks';
import { analyzeUserData } from './user-data-validation';

// =============================================================================
// Types
// =============================================================================

export interface ValidationIssue {
  /** Stable code agents can branch on. */
  code: string;
  /** Human-readable description of the issue. */
  message: string;
  /** Agent-facing one-liner: what to change to fix. */
  fixHint?: string;
  /** 1-based source line where the issue was detected, when known. */
  line?: number;
}

export interface ValidationResult {
  valid: boolean;
  /**
   * Flat list of human-readable error messages. Kept for compatibility with
   * the pre-W3b.3 shape; existing consumers can keep using it unchanged.
   */
  errors: string[];
  /**
   * Structured error list — same set as `errors` but with codes, fix hints,
   * and line numbers. New agents should prefer this.
   */
  issues: ValidationIssue[];
  /**
   * Non-fatal advisories (style and unit suggestions). Never block
   * execution, always worth surfacing to agents.
   */
  warnings: ValidationIssue[];
  /**
   * Static triangle estimate for `build()`, summed from primitive call sites and
   * scaled by literal loop bounds. Present only when the body parsed.
   *
   * This is information and nothing else. No advisory, warning, or gate reads
   * it, and none should: Kiln has no triangle budget by design, because every
   * number it used to print read to a model as a target to stay under. Surface
   * it to a caller who asked how big something is; never compare it to a limit.
   */
  estimatedTris?: number;
}

// =============================================================================
// Triangle estimation
// =============================================================================

/**
 * Rough static triangle estimates for every geometry primitive. Exact numbers
 * come from Three.js's own primitive builders.
 *
 * Reported, never judged: `analyzeBody` sums these into `estimatedTris` so a
 * caller can SEE the scale of what a program will build. Nothing compares the
 * result to a limit — see the note above `validate` on why the budget advisory
 * was removed.
 */
function estimateGeometryTris(name: string, args: readonly acorn.Expression[]): number | null {
  function asNum(node: acorn.Expression | undefined): number | null {
    if (!node) return null;
    if (node.type === 'Literal' && typeof node.value === 'number') return node.value;
    if (node.type === 'UnaryExpression' && node.operator === '-') {
      const inner = asNum(node.argument);
      return inner === null ? null : -inner;
    }
    return null;
  }

  /** Numeric property off an options-object literal arg (e.g. gearGeo({ teeth: 16 })). */
  function asObjNum(node: acorn.Expression | undefined, prop: string): number | null {
    if (node?.type !== 'ObjectExpression') return null;
    for (const p of node.properties) {
      if (
        p.type === 'Property' &&
        !p.computed &&
        ((p.key.type === 'Identifier' && p.key.name === prop) ||
          (p.key.type === 'Literal' && p.key.value === prop))
      ) {
        return asNum(p.value as acorn.Expression);
      }
    }
    return null;
  }

  switch (name) {
    case 'boxGeo':
    case 'decalBox':
      return 12; // 6 faces x 2 tris
    case 'planeGeo': {
      const ws = asNum(args[2]) ?? 1;
      const hs = asNum(args[3]) ?? 1;
      return Math.max(1, ws * hs) * 2;
    }
    case 'coneGeo':
    case 'coneXGeo':
    case 'coneYGeo':
    case 'coneZGeo': {
      const segs = asNum(args[2]) ?? 8;
      return segs * 2; // cap + sides
    }
    case 'cylinderGeo':
    case 'cylinderXGeo':
    case 'cylinderYGeo':
    case 'cylinderZGeo': {
      const segs = asNum(args[3]) ?? 8;
      return segs * 4; // side + 2 caps
    }
    case 'taperConeGeo': {
      const segs = asNum(args[4]) ?? 8;
      return segs * 4; // open frustum ≈ cylinder budget
    }
    case 'sphereGeo': {
      const w = asNum(args[1]) ?? 8;
      const h = asNum(args[2]) ?? 6;
      return w * h * 2;
    }
    case 'capsuleGeo':
    case 'capsuleXGeo':
    case 'capsuleYGeo':
    case 'capsuleZGeo': {
      const segs = asNum(args[2]) ?? 6;
      return segs * 8; // rough: body + caps
    }
    case 'torusGeo': {
      const rad = asNum(args[2]) ?? 8;
      const tub = asNum(args[3]) ?? 12;
      return rad * tub * 2;
    }
    case 'gearGeo': {
      // Calibrated against countTriangles on the parametric gear builder:
      // each tooth contributes ~32 tris (tooth walls + rim segments + caps).
      const teeth = asObjNum(args[0], 'teeth') ?? 12;
      return teeth * 32;
    }
    case 'bladeGeo':
      return 36; // tapered prism + tip
    case 'wingGeo':
      return 24; // closed trapezoid slab
    default:
      return null;
  }
}

// There is deliberately no triangle budget here.
//
// Kiln used to emit a TRI_BUDGET_EXCEEDED advisory against per-category soft
// reference points. It was removed because it was actively harmful: triangles
// are not a cost driver (input tokens dominate generation cost, and runtime cost
// is draw-calls-not-triangles), and every number the advisory printed read to a
// model as a target to stay under. The measured effect was assets that stopped
// at the blockout stage — a few hundred triangles for something that wanted tens
// of thousands. `analyzeBody` still estimates triangles, and the render path
// still reports the real count; nothing judges either against a limit.
//
// If you want a cap, pass one explicitly through `request.budget.maxTriangles`.
// That is a caller's deliberate constraint, not a default the validator invents.

// =============================================================================
// Core validator
// =============================================================================

/**
 * Validate Kiln code before rendering.
 *
 * @param code      raw JS string as returned by the LLM
 * @param _opts     accepted and currently unread. Every category-dependent
 *                  advisory this validator had was the triangle budget, and that
 *                  is gone. The option stays in the signature because callers
 *                  pass it and because category-aware STRUCTURAL advisories are
 *                  the natural place for it to come back. It must not come back
 *                  as a size limit.
 */
export function validate(code: string, _opts: { category?: string } = {}): ValidationResult {
  const issues: ValidationIssue[] = [];
  const warnings: ValidationIssue[] = [];

  if (!code || typeof code !== 'string' || code.trim().length === 0) {
    issues.push({
      code: 'EMPTY_CODE',
      message: 'Empty or missing code',
      fixHint: 'Provide a non-empty code string from the code generator.',
    });
    return toResult(issues, warnings);
  }

  // Normalize CRLF → LF so line numbers line up with what the LLM sees.
  const normalized = code.replace(/\r\n/g, '\n');

  // --- Regex pre-checks (cheap, catch malformed code before AST parse) -----

  if (/^\s*import\s+/m.test(normalized)) {
    issues.push({
      code: 'HAS_IMPORT',
      message: 'Contains import statements — code must use sandbox globals only',
      fixHint: 'Remove all `import` lines; primitives like boxGeo are already in scope.',
      line: findLineOf(normalized, /^\s*import\s+/m),
    });
  }

  if (/^\s*export\s+/m.test(normalized)) {
    issues.push({
      code: 'HAS_EXPORT',
      message: 'Contains export statements — just define meta, build, animate',
      fixHint:
        'Remove `export` keywords; the sandbox evaluator picks up `meta` and `build` by name.',
      line: findLineOf(normalized, /^\s*export\s+/m),
    });
  }

  // The `value:` keyframe mistake is the single most common LLM regression.
  // Matched with a regex so we get it before the parser so failures point to
  // the exact line.
  const valueMatch = /\{\s*time:\s*[^,]+,\s*value:\s*\[/.exec(normalized);
  if (valueMatch) {
    issues.push({
      code: 'KEYFRAME_VALUE_KEY',
      message: 'Uses `value:` in keyframes — must use `rotation:` or `position:` instead',
      fixHint:
        'In every `{ time, value: [...] }` change `value:` to `rotation:` (degrees) or `position:`.',
      line: lineOfIndex(normalized, valueMatch.index),
    });
  }

  // --- AST parse ---------------------------------------------------------

  let ast: acorn.Program;
  try {
    ast = acorn.parse(normalized, {
      ecmaVersion: 2022,
      sourceType: 'script',
      allowReturnOutsideFunction: false,
      locations: true,
    });
  } catch (e) {
    const msg = e instanceof Error ? e.message : String(e);
    // acorn error messages already include (line:col); extract it if present
    // so `line` is available structured even with the raw string around.
    const locMatch = /\((\d+):\d+\)/.exec(msg);
    issues.push({
      code: 'SYNTAX_ERROR',
      message: `Syntax error: ${msg}`,
      fixHint: 'Fix the syntax error at the reported line/column.',
      line: locMatch ? Number(locMatch[1]) : undefined,
    });
    // Can't continue AST-level checks without a tree — return now.
    return toResult(issues, warnings);
  }
  const strict = strictModeSyntaxError(normalized);
  if (strict) {
    issues.push({
      code: 'SYNTAX_ERROR',
      message: `Syntax error in strict mode: ${strict.message}`,
      fixHint:
        'Generated code runs in strict mode; rewrite the construct at the reported line (no with, legacy octal literal, duplicate parameter name or delete of a plain name).',
      line: strict.line,
    });
  }

  // --- Structural checks --------------------------------------------------

  issues.push(...analyzeGeneratedSourceSafety(ast));
  issues.push(...analyzeBuildTimeThrows(ast));

  const structure = analyzeTopLevel(ast);

  if (!structure.hasMetaConst) {
    issues.push({
      code: 'MISSING_META',
      message: 'Missing `const meta = { ... }` declaration at top level',
      fixHint: 'Add `const meta = { name: "YourAsset" };` at the top of the file.',
    });
  } else if (!structure.metaHasName) {
    warnings.push({
      code: 'META_MISSING_NAME',
      message: '`meta` object has no `name` property',
      fixHint: 'Add `name: "YourAsset"` to the meta object.',
    });
  }

  if (!structure.hasBuildFn) {
    issues.push({
      code: 'MISSING_BUILD',
      message: 'Missing top-level `function build()` declaration',
      fixHint:
        'Add `function build() { const root = createRoot("..."); ...; return root; }` at top level.',
    });
  }

  // --- Body analysis — infinite loops, recursion ---------------------------

  const analysis = analyzeBody(ast);

  if (analysis.infiniteLoops.length > 0) {
    for (const hit of analysis.infiniteLoops) {
      issues.push({
        code: 'INFINITE_LOOP',
        message: `${hit.kind} with no break statement`,
        fixHint: `Add a break/return condition inside the ${hit.kind} loop, or switch to a bounded for/forEach.`,
        line: hit.line,
      });
    }
  }

  if (analysis.recursiveBuild) {
    issues.push({
      code: 'RECURSIVE_BUILD',
      message: '`build()` calls itself — will blow the stack at render time',
      fixHint: 'Refactor the recursive step into a helper function; keep `build()` non-recursive.',
      line: analysis.recursiveBuild,
    });
  }

  // Rotation-units advisory: createPart/createInstance rotation is DEGREES,
  // but models steeped in raw THREE habitually write radians — which silently
  // flatten to ~0°. Caught live 2026-06-11 (AC-47 prop blades all vertical).
  for (const smell of analyzeRotationUnits(ast, normalized)) {
    warnings.push({
      code: 'ROTATION_RADIANS_SUSPECTED',
      message: `${smell.fn} rotation ${smell.rendered} looks like RADIANS — the rotation option is DEGREES${smell.suggestion ? `; did you mean ${smell.suggestion}?` : ''}`,
      fixHint:
        'createPart/createInstance rotation is degrees ([0,0,90] = quarter turn). Convert: deg = rad * 180 / Math.PI. Direct THREE properties (obj.rotation.z) stay radians.',
      line: smell.line,
    });
  }

  for (const issue of unknownHelperWarnings(ast)) {
    if (issue.code === 'REMOVED_HELPER') issues.push(issue);
    else warnings.push(issue);
  }

  // userData exports as glTF extras; name what the source already shows will not export.
  warnings.push(...analyzeUserData(ast));

  return toResult(issues, warnings, analysis.estimatedTris);
}

/**
 * Identifiers that are called but neither declared in the program nor exposed
 * by the sandbox. Calling one throws the moment the program runs, so reporting
 * it before execution is strictly better than discovering it from a render.
 *
 * This is also the only place the name can be reported at all. The isolated
 * evaluator deliberately lets no identifier, message or stack cross its
 * boundary, so `kiln_render` can say that some variable was undeclared but
 * never which one. This parse happens host-side, before anything executes.
 *
 * Unknown calls are warnings; recognized removed globals are migration errors.
 * Removed globals use lexical visibility; a local in an unrelated scope must
 * not hide a migration error. Unknown-call advisories retain their conservative
 * whole-program declaration set. Neither check diagnoses reachability; a read
 * before a lexical declaration runs is TEMPORAL_DEAD_ZONE (source-runtime-checks).
 */
function unknownHelperWarnings(ast: acorn.Program): ValidationIssue[] {
  const bindings = sourceBindings(ast);
  const declared = bindings.allNames;

  const seen = new Map<string, number | undefined>();
  // Retired globals can also be captured as values before invocation. Respect
  // ordinary local definitions and property names rather than banning words.
  const checkRemoved = (node: acorn.Identifier, _state: unknown, ancestors: acorn.Node[]) => {
    if (
      !Object.hasOwn(REMOVED_AUTHORING_HELPERS, node.name) ||
      bindings.has(node.name, ancestors) ||
      identifierIsNonReferenceKey(node, ancestors.at(-2))
    )
      return;
    if (!seen.has(node.name)) seen.set(node.name, node.loc?.start.line);
  };
  const retiredVisitors = {
    Identifier: checkRemoved,
    // Includes assignment targets; declaration identifiers already resolve to
    // their binding above and therefore cannot be mistaken for removed globals.
    VariablePattern: checkRemoved,
  };
  // acorn-walk's declarations omit the virtual VariablePattern visitor.
  walk.ancestor(ast, retiredVisitors);
  walk.simple(ast, {
    CallExpression(node) {
      const callee = (node as unknown as { callee?: { type?: string; name?: string } }).callee;
      if (callee?.type !== 'Identifier' || !callee.name) return;
      const name = callee.name;
      if (declared.has(name) || SANDBOX_CALLABLES.has(name) || seen.has(name)) return;
      seen.set(name, (node as unknown as { loc?: { start?: { line?: number } } }).loc?.start?.line);
    },
  });

  return [...seen].map(([name, line]) =>
    Object.hasOwn(REMOVED_AUTHORING_HELPERS, name)
      ? {
          code: 'REMOVED_HELPER',
          message: `${name} was removed from Kiln's authoring globals. No compatibility alias is provided.`,
          fixHint: REMOVED_AUTHORING_HELPERS[name],
          ...(line === undefined ? {} : { line }),
        }
      : {
          code: 'UNKNOWN_HELPER',
          message: `${name}() is not declared in this program and is not a Kiln sandbox global; the build will fail when it runs.`,
          fixHint:
            'Call kiln_discover to confirm the helper name and signature, or declare the function in this program.',
          ...(line === undefined ? {} : { line }),
        },
  );
}

/**
 * Everything a program may legitimately call by bare name: the sandbox catalog,
 * which a bidirectional test keeps in step with `buildSandboxGlobals()`, plus
 * the JavaScript built-ins the sandbox does not remove. The catalog is imported
 * rather than the sandbox itself so this module's dependency graph stays free of
 * three.js.
 */
const SANDBOX_CALLABLES: ReadonlySet<string> = new Set([
  ...listHelperSpecs()
    .map((primitive) => primitive.name)
    .filter((name) => !Object.hasOwn(REMOVED_AUTHORING_HELPERS, name)),
  'Array',
  'BigInt',
  'Boolean',
  'Error',
  'Float32Array',
  'Float64Array',
  'Int16Array',
  'Int32Array',
  'Int8Array',
  'Map',
  'Number',
  'Object',
  'Promise',
  'Proxy',
  'RangeError',
  'Reflect',
  'RegExp',
  'Set',
  'String',
  'Symbol',
  'TypeError',
  'Uint16Array',
  'Uint32Array',
  'Uint8Array',
  'WeakMap',
  'WeakSet',
  'decodeURIComponent',
  'encodeURIComponent',
  'isFinite',
  'isNaN',
  'parseFloat',
  'parseInt',
  'structuredClone',
]);

// Backward-compat alias.
export const validateKilnCode = validate;

/**
 * Sanitized execution-boundary error. It intentionally carries a stable code
 * and line only; generated source text and dynamic-import specifiers are never
 * copied into the message.
 */
export class GeneratedSourcePolicyError extends Error {
  readonly code: string;
  readonly line?: number;

  constructor(issue: ValidationIssue) {
    super(
      `Generated source rejected by policy (${issue.code})${issue.line ? ` at line ${issue.line}` : ''}.`,
    );
    this.name = 'GeneratedSourcePolicyError';
    this.code = issue.code;
    this.line = issue.line;
  }
}

/**
 * The evaluator prepends 'use strict' to generated code (render.ts), so a construct
 * only strict mode refuses -- `with`, a legacy octal literal, duplicate parameter
 * names, `delete` of a plain name -- is a syntax error there. Parsing a second time
 * with the directive on the same first line keeps every line number the author's
 * and names the line before any evaluation (rule 9) instead of surfacing it as a
 * generic rejection. Undefined when the code is valid strict-mode script.
 */
function strictModeSyntaxError(code: string): { message: string; line?: number } | undefined {
  try {
    acorn.parse(`'use strict';${code}`, {
      ecmaVersion: 2022,
      sourceType: 'script',
      allowReturnOutsideFunction: false,
      locations: true,
    });
    return undefined;
  } catch (error) {
    const loc =
      error && typeof error === 'object' && 'loc' in error
        ? (error as { loc?: { line?: number } }).loc
        : undefined;
    return { message: error instanceof Error ? error.message : String(error), line: loc?.line };
  }
}

/** Defense-in-depth gate used immediately before the Function evaluator. */
export function assertGeneratedSourceSafe(code: string): void {
  let ast: acorn.Program;
  try {
    ast = acorn.parse(code, {
      ecmaVersion: 2022,
      sourceType: 'script',
      allowReturnOutsideFunction: false,
      locations: true,
    });
  } catch (error) {
    const line =
      error && typeof error === 'object' && 'loc' in error
        ? (error as { loc?: { line?: number } }).loc?.line
        : undefined;
    throw new GeneratedSourcePolicyError({
      code: 'SYNTAX_ERROR',
      message: 'Generated source has invalid syntax.',
      line,
    });
  }
  const strict = strictModeSyntaxError(code);
  if (strict)
    throw new GeneratedSourcePolicyError({
      code: 'SYNTAX_ERROR',
      message: 'Generated source has invalid strict-mode syntax.',
      line: strict.line,
    });
  const issue = analyzeGeneratedSourceSafety(ast)[0];
  if (issue) throw new GeneratedSourcePolicyError(issue);
  if (unknownHelperWarnings(ast).some((entry) => entry.code === 'REMOVED_HELPER'))
    throw new AuthoringDiagnosticError('REMOVED_HELPER');
}

// =============================================================================
// Internals
// =============================================================================

const FORBIDDEN_AMBIENT_IDENTIFIERS = new Set([
  'globalThis',
  'global',
  'process',
  'fetch',
  'XMLHttpRequest',
  'WebSocket',
  'Function',
  'eval',
  // Other common host-global aliases are denied for the same reason. This is
  // a denylist safety net, not a claim that the evaluator is isolated.
  'window',
  'self',
  'document',
  'navigator',
  'location',
  'Bun',
  'Deno',
  'Reflect',
  'require',
  'module',
]);

const FORBIDDEN_THREE_CONSTRUCTORS = new Set([
  'DataTexture',
  'ShaderMaterial',
  'RawShaderMaterial',
]);

function issueKey(issue: ValidationIssue): string {
  return `${issue.code}:${issue.line ?? 0}:${issue.message}`;
}

function analyzeGeneratedSourceSafety(ast: acorn.Program): ValidationIssue[] {
  const issues: ValidationIssue[] = [];
  const seen = new Set<string>();
  const staticStrings = collectStaticStringBindings(ast);
  const add = (issue: ValidationIssue): void => {
    const key = issueKey(issue);
    if (seen.has(key)) return;
    seen.add(key);
    issues.push(issue);
  };
  const ambient = (name: string, line?: number): void =>
    add({
      code: 'UNSAFE_GLOBAL_ACCESS',
      message: `Generated code cannot access ambient capability \`${name}\`.`,
      fixHint: 'Use only the documented sandbox globals and approved resource helpers.',
      line,
    });
  const dynamicCode = (line?: number): void =>
    add({
      code: 'DYNAMIC_CODE_ACCESS',
      message: 'Generated code cannot access constructor chains or dynamic-code constructors.',
      fixHint: 'Call documented sandbox helpers directly; do not derive constructors at runtime.',
      line,
    });
  const unsafeThree = (name: string, line?: number): void =>
    add({
      code: 'UNSAFE_THREE_CONSTRUCTOR',
      message: `Generated code cannot access raw THREE constructor \`${name}\`.`,
      fixHint:
        'Use approved texture loading, proceduralTexture, pbrMaterial, or materialRecipe instead.',
      line,
    });
  const unsafeThreeNamespace = (
    code: 'UNSAFE_THREE_ALIAS' | 'UNSAFE_THREE_COMPUTED_ACCESS',
    line?: number,
  ): void =>
    add({
      code,
      message:
        code === 'UNSAFE_THREE_ALIAS'
          ? 'Generated code cannot alias the THREE namespace.'
          : 'Generated code cannot use non-static computed access on the THREE namespace.',
      fixHint: 'Use a documented direct THREE constructor or a sandbox material/texture helper.',
      line,
    });

  // `this` is allowed where it is a method receiver: an object-literal method, getter,
  // setter or function property, a class method, constructor, accessor, field
  // initializer or static block, and arrows nested inside those. Generated code runs
  // in strict mode (render.ts), so every other `this` -- the top level, a plain
  // function -- is undefined or a caller's value, never the host global; those stay
  // refused as the denylist safety net (decision 23 of 2 October 2026; F28: w29's mesh
  // batcher was an object literal whose `add` method read `this`).
  const thisBindsToMethodReceiver = (ancestors: readonly acorn.Node[]): boolean => {
    for (let i = ancestors.length - 2; i >= 0; i--) {
      const node = ancestors[i]!;
      if (node.type === 'ArrowFunctionExpression') continue;
      if (node.type === 'PropertyDefinition' || node.type === 'StaticBlock') return true;
      if (node.type === 'FunctionDeclaration') return false;
      if (node.type !== 'FunctionExpression') continue;
      const parent = ancestors[i - 1] as acorn.Property | acorn.MethodDefinition | undefined;
      return (
        (parent?.type === 'Property' || parent?.type === 'MethodDefinition') &&
        parent.value === node
      );
    }
    return false;
  };
  walk.ancestor(ast, {
    Identifier(node, _state, ancestors) {
      const parent = ancestors.at(-2);
      if (identifierIsNonReferenceKey(node, parent)) return;
      if (FORBIDDEN_AMBIENT_IDENTIFIERS.has(node.name)) {
        ambient(node.name, node.loc?.start.line);
      }
    },
    ThisExpression(node, _state, ancestors) {
      if (thisBindsToMethodReceiver(ancestors)) return;
      ambient('this', node.loc?.start.line);
    },
    ImportExpression(node) {
      add({
        code: 'DYNAMIC_IMPORT',
        message: 'Generated code cannot use dynamic import.',
        fixHint: 'Remove import(); all supported helpers are already sandbox globals.',
        line: node.loc?.start.line,
      });
    },
    MemberExpression(node) {
      const property = staticPropertyName(node, staticStrings);
      if (property === 'constructor') dynamicCode(node.loc?.start.line);
      if (
        property &&
        FORBIDDEN_THREE_CONSTRUCTORS.has(property) &&
        expressionReferencesThree(node.object)
      ) {
        unsafeThree(property, node.loc?.start.line);
      }
      if (node.computed && property === undefined && expressionReferencesThree(node.object)) {
        unsafeThreeNamespace('UNSAFE_THREE_COMPUTED_ACCESS', node.loc?.start.line);
      }
    },
    VariableDeclarator(node) {
      if (node.id.type === 'Identifier' && expressionReferencesThree(node.init)) {
        unsafeThreeNamespace('UNSAFE_THREE_ALIAS', node.loc?.start.line);
      }
      if (node.id.type !== 'ObjectPattern') return;
      analyzeObjectPatternSafety(
        node.id,
        node.init?.type === 'Identifier' && node.init.name === 'THREE',
        staticStrings,
        dynamicCode,
        unsafeThree,
      );
    },
    AssignmentExpression(node) {
      if (node.left.type === 'Identifier' && expressionReferencesThree(node.right)) {
        unsafeThreeNamespace('UNSAFE_THREE_ALIAS', node.loc?.start.line);
      }
      if (node.left.type !== 'ObjectPattern') return;
      analyzeObjectPatternSafety(
        node.left,
        node.right.type === 'Identifier' && node.right.name === 'THREE',
        staticStrings,
        dynamicCode,
        unsafeThree,
      );
    },
    CallExpression(node) {
      if (node.callee.type !== 'MemberExpression' || node.callee.object.type !== 'Identifier') {
        return;
      }
      const owner = node.callee.object.name;
      const method = staticPropertyName(node.callee, staticStrings);
      if (
        !(
          (owner === 'Reflect' && method === 'get') ||
          (owner === 'Object' && method === 'getOwnPropertyDescriptor')
        )
      ) {
        return;
      }
      const property = staticExpressionString(node.arguments[1], staticStrings);
      if (property === 'constructor') dynamicCode(node.loc?.start.line);
      if (
        owner === 'Reflect' &&
        property &&
        FORBIDDEN_THREE_CONSTRUCTORS.has(property) &&
        expressionReferencesThree(node.arguments[0])
      ) {
        unsafeThree(property, node.loc?.start.line);
      }
    },
  });

  return issues;
}

function expressionReferencesThree(node: unknown): boolean {
  if (!node || typeof node !== 'object') return false;
  const expression = node as acorn.Expression;
  if (expression.type === 'Identifier') return expression.name === 'THREE';
  if (expression.type === 'ChainExpression')
    return expressionReferencesThree(expression.expression);
  if (expression.type === 'SequenceExpression') {
    return expressionReferencesThree(expression.expressions.at(-1));
  }
  return false;
}

function identifierIsNonReferenceKey(
  node: acorn.Identifier,
  parent: acorn.Node | undefined,
): boolean {
  if (!parent) return false;
  if (parent.type === 'MemberExpression') {
    const member = parent as acorn.MemberExpression;
    if (member.property === node && !member.computed) return true;
  }
  if (parent.type === 'Property') {
    const property = parent as acorn.Property;
    if (property.key === node && !property.computed && !property.shorthand) return true;
  }
  if (parent.type === 'MethodDefinition') {
    const method = parent as acorn.MethodDefinition;
    if (method.key === node && !method.computed) return true;
  }
  if (parent.type === 'LabeledStatement') {
    if ((parent as acorn.LabeledStatement).label === node) return true;
  }
  if (parent.type === 'BreakStatement' || parent.type === 'ContinueStatement') {
    if ((parent as acorn.BreakStatement | acorn.ContinueStatement).label === node) return true;
  }
  return false;
}

function analyzeObjectPatternSafety(
  pattern: acorn.ObjectPattern,
  fromThree: boolean,
  staticStrings: ReadonlyMap<string, string>,
  dynamicCode: (line?: number) => void,
  unsafeThree: (name: string, line?: number) => void,
): void {
  for (const entry of pattern.properties) {
    if (entry.type !== 'Property') continue;
    const property =
      !entry.computed && entry.key.type === 'Identifier'
        ? entry.key.name
        : staticExpressionString(entry.key, staticStrings);
    if (property === 'constructor') dynamicCode(entry.loc?.start.line);
    if (fromThree && property && FORBIDDEN_THREE_CONSTRUCTORS.has(property)) {
      unsafeThree(property, entry.loc?.start.line);
    }
  }
}

function staticPropertyName(
  node: acorn.MemberExpression,
  staticStrings: ReadonlyMap<string, string>,
): string | undefined {
  if (!node.computed && node.property.type === 'Identifier') return node.property.name;
  return staticExpressionString(node.property, staticStrings);
}

function staticExpressionString(
  node: unknown,
  staticStrings: ReadonlyMap<string, string> = new Map(),
): string | undefined {
  if (!node || typeof node !== 'object') return undefined;
  const expression = node as acorn.Expression;
  if (expression.type === 'Literal') {
    return typeof expression.value === 'string' || typeof expression.value === 'number'
      ? String(expression.value)
      : undefined;
  }
  if (expression.type === 'Identifier') return staticStrings.get(expression.name);
  if (expression.type === 'TemplateLiteral') {
    let value = expression.quasis[0]?.value.cooked ?? expression.quasis[0]?.value.raw ?? '';
    for (let index = 0; index < expression.expressions.length; index++) {
      const part = staticExpressionString(expression.expressions[index], staticStrings);
      if (part === undefined) return undefined;
      const quasi = expression.quasis[index + 1];
      value += part + (quasi?.value.cooked ?? quasi?.value.raw ?? '');
    }
    return value;
  }
  if (expression.type === 'BinaryExpression' && expression.operator === '+') {
    const left = staticExpressionString(expression.left, staticStrings);
    const right = staticExpressionString(expression.right, staticStrings);
    return left === undefined || right === undefined ? undefined : left + right;
  }
  return undefined;
}

/** Resolve unambiguous const string/number bindings for common bracket-access
 * obfuscations. Duplicate names across scopes are intentionally left unknown
 * to avoid attaching one scope's value to another. */
function collectStaticStringBindings(ast: acorn.Program): ReadonlyMap<string, string> {
  const candidates = new Map<string, acorn.Expression>();
  const duplicateNames = new Set<string>();
  walk.simple(ast, {
    VariableDeclaration(node) {
      if (node.kind !== 'const') return;
      for (const declaration of node.declarations) {
        if (declaration.id.type !== 'Identifier' || !declaration.init) continue;
        if (candidates.has(declaration.id.name)) duplicateNames.add(declaration.id.name);
        else candidates.set(declaration.id.name, declaration.init);
      }
    },
  });
  for (const name of duplicateNames) candidates.delete(name);

  const values = new Map<string, string>();
  for (let pass = 0; pass < candidates.size; pass++) {
    let changed = false;
    for (const [name, expression] of candidates) {
      if (values.has(name)) continue;
      const value = staticExpressionString(expression, values);
      if (value === undefined) continue;
      values.set(name, value);
      changed = true;
    }
    if (!changed) break;
  }
  return values;
}

function toResult(
  issues: ValidationIssue[],
  warnings: ValidationIssue[],
  estimatedTris?: number,
): ValidationResult {
  return {
    valid: issues.length === 0,
    errors: issues.map((i) => i.message),
    issues,
    warnings,
    ...(estimatedTris === undefined ? {} : { estimatedTris }),
  };
}

function findLineOf(code: string, re: RegExp): number | undefined {
  const match = re.exec(code);
  if (!match) return undefined;
  return lineOfIndex(code, match.index);
}

function lineOfIndex(code: string, idx: number): number {
  let line = 1;
  for (let i = 0; i < idx; i++) if (code.charCodeAt(i) === 10) line++;
  return line;
}

// -----------------------------------------------------------------------------
// Rotation-units lint — createPart/createInstance rotation is DEGREES
// -----------------------------------------------------------------------------

interface RotationSmell {
  fn: string;
  /** The rotation array as written in source (truncated). */
  rendered: string;
  /** Degree equivalent, when the array is a pure numeric literal triple. */
  suggestion?: string;
  line?: number;
}

const ROTATION_OPTION_FNS = new Set(['createPart', 'createInstance']);

/**
 * Find `rotation: [...]` options on createPart/createInstance calls that look
 * like radians. Two signals:
 *  - `Math.PI` anywhere in an element (unless the element divides by Math.PI —
 *    the `x * 180 / Math.PI` rad→deg conversion idiom, which IS degrees).
 *  - Pure numeric triples where every non-zero |v| < 6.3 and at least one is
 *    a non-integer: a degrees author writes 90 / 45 / -15 / 28.6, a radians
 *    author writes 0.3 / 0.785 / 1.57 / 4.49.
 * Anything dynamic (identifiers, calls) stays quiet — warnings must not cry
 * wolf on code the heuristic can't read.
 */
function analyzeRotationUnits(ast: acorn.Program, source: string): RotationSmell[] {
  const smells: RotationSmell[] = [];
  walk.simple(ast, {
    CallExpression(node) {
      if (node.callee.type !== 'Identifier' || !ROTATION_OPTION_FNS.has(node.callee.name)) return;
      const fn = node.callee.name;
      for (const arg of node.arguments) {
        if (arg.type !== 'ObjectExpression') continue;
        for (const prop of arg.properties) {
          if (prop.type !== 'Property' || prop.computed) continue;
          const key =
            prop.key.type === 'Identifier'
              ? prop.key.name
              : prop.key.type === 'Literal'
                ? String(prop.key.value)
                : '';
          if (key !== 'rotation' || prop.value.type !== 'ArrayExpression') continue;
          const smell = classifyRotationArray(prop.value, fn, source);
          if (smell) smells.push(smell);
        }
      }
    },
  });
  return smells;
}

function classifyRotationArray(
  arr: acorn.ArrayExpression,
  fn: string,
  source: string,
): RotationSmell | null {
  const rendered = () => {
    const text = source.slice(arr.start, arr.end).replace(/\s+/g, ' ');
    return text.length > 64 ? `${text.slice(0, 61)}...` : text;
  };

  // Signal 1: Math.PI in any element = radians thinking, unless every PI use
  // is the rad→deg conversion idiom (`... / Math.PI`).
  let sawPI = false;
  let onlyConversions = true;
  for (const el of arr.elements) {
    if (!el || el.type === 'SpreadElement') continue;
    if (containsMathPI(el)) {
      sawPI = true;
      if (!dividesByMathPI(el)) onlyConversions = false;
    }
  }
  if (sawPI) {
    if (onlyConversions) return null;
    return { fn, rendered: rendered(), line: arr.loc?.start.line };
  }

  // Signal 2: pure numeric literal triples with radian-scale magnitudes.
  const nums: number[] = [];
  for (const el of arr.elements) {
    if (!el || el.type === 'SpreadElement') return null;
    const n = literalNumber(el);
    if (n === undefined) return null; // dynamic expression — stay quiet
    nums.push(n);
  }
  const nonZero = nums.filter((n) => n !== 0);
  if (nonZero.length === 0) return null;
  if (!nonZero.every((n) => Math.abs(n) < 6.3)) return null;
  if (!nonZero.some((n) => !Number.isInteger(n))) return null;
  const deg = nums.map((n) => (n === 0 ? 0 : Math.round((n * 180) / Math.PI)));
  return {
    fn,
    rendered: rendered(),
    suggestion: `[${deg.join(', ')}]`,
    line: arr.loc?.start.line,
  };
}

/** Literal number, including the `-x` unary form. */
function literalNumber(el: acorn.Expression): number | undefined {
  if (el.type === 'Literal' && typeof el.value === 'number') return el.value;
  if (el.type === 'UnaryExpression' && el.operator === '-') {
    const inner = literalNumber(el.argument);
    return inner === undefined ? undefined : -inner;
  }
  return undefined;
}

/** Deep scan for a `Math.PI` member expression anywhere in the subtree. */
function containsMathPI(node: unknown): boolean {
  if (!node || typeof node !== 'object') return false;
  const n = node as Record<string, unknown> & { type?: string };
  if (n.type === 'MemberExpression') {
    const obj = n['object'] as { type?: string; name?: string } | undefined;
    const prop = n['property'] as { type?: string; name?: string } | undefined;
    if (
      obj?.type === 'Identifier' &&
      obj.name === 'Math' &&
      prop?.type === 'Identifier' &&
      prop.name === 'PI'
    ) {
      return true;
    }
  }
  for (const key of Object.keys(n)) {
    if (key === 'loc' || key === 'start' || key === 'end') continue;
    const v = n[key];
    if (Array.isArray(v)) {
      for (const item of v) if (containsMathPI(item)) return true;
    } else if (v && typeof v === 'object' && (v as { type?: string }).type) {
      if (containsMathPI(v)) return true;
    }
  }
  return false;
}

/** Is this expression a division whose divisor contains Math.PI (rad→deg)? */
function dividesByMathPI(node: unknown): boolean {
  if (!node || typeof node !== 'object') return false;
  const n = node as {
    type?: string;
    operator?: string;
    left?: unknown;
    right?: unknown;
    argument?: unknown;
  };
  if (n.type === 'BinaryExpression' && n.operator === '/' && containsMathPI(n.right)) return true;
  if (n.type === 'BinaryExpression') return dividesByMathPI(n.left) || dividesByMathPI(n.right);
  if (n.type === 'UnaryExpression') return dividesByMathPI(n.argument);
  return false;
}

// -----------------------------------------------------------------------------
// Top-level shape
// -----------------------------------------------------------------------------

interface TopLevelStructure {
  hasMetaConst: boolean;
  metaHasName: boolean;
  hasBuildFn: boolean;
  hasAnimateFn: boolean;
}

function analyzeTopLevel(ast: acorn.Program): TopLevelStructure {
  const out: TopLevelStructure = {
    hasMetaConst: false,
    metaHasName: false,
    hasBuildFn: false,
    hasAnimateFn: false,
  };

  for (const stmt of ast.body) {
    if (stmt.type === 'VariableDeclaration' && (stmt.kind === 'const' || stmt.kind === 'let')) {
      for (const decl of stmt.declarations) {
        if (decl.id.type === 'Identifier' && decl.id.name === 'meta') {
          out.hasMetaConst = true;
          if (decl.init && decl.init.type === 'ObjectExpression') {
            out.metaHasName = decl.init.properties.some(
              (p) =>
                p.type === 'Property' &&
                !p.computed &&
                ((p.key.type === 'Identifier' && p.key.name === 'name') ||
                  (p.key.type === 'Literal' && p.key.value === 'name')),
            );
          }
        }
      }
    } else if (stmt.type === 'FunctionDeclaration' && stmt.id) {
      if (stmt.id.name === 'build') out.hasBuildFn = true;
      if (stmt.id.name === 'animate') out.hasAnimateFn = true;
    }
  }

  return out;
}

// -----------------------------------------------------------------------------
// Body walk — loops, recursion, geometry calls
// -----------------------------------------------------------------------------

interface BodyAnalysis {
  infiniteLoops: Array<{ kind: 'while(true)' | 'for(;;)'; line?: number }>;
  recursiveBuild: number | undefined; // line number of the self-call
  estimatedTris: number;
}

function analyzeBody(ast: acorn.Program): BodyAnalysis {
  const infiniteLoops: BodyAnalysis['infiniteLoops'] = [];
  let recursiveBuild: number | undefined;
  let estimatedTris = 0;

  // Track the enclosing function for recursion detection.
  const stack: string[] = [];

  walk.ancestor(ast, {
    FunctionDeclaration(node, _state, ancestors) {
      void _state;
      void ancestors;
      if (node.id?.name) stack.push(node.id.name);
    },
    WhileStatement(node) {
      if (isConstantTruthy(node.test) && !hasBreak(node.body)) {
        infiniteLoops.push({ kind: 'while(true)', line: node.loc?.start.line });
      }
    },
    ForStatement(node) {
      // for(;;) with no test (always-true) and no break is infinite.
      if (!node.test && !hasBreak(node.body)) {
        infiniteLoops.push({ kind: 'for(;;)', line: node.loc?.start.line });
      } else if (node.test && isConstantTruthy(node.test) && !hasBreak(node.body)) {
        infiniteLoops.push({ kind: 'for(;;)', line: node.loc?.start.line });
      }
    },
    CallExpression(node, _state, ancestors) {
      void _state;
      // Recursion detection: `build()` invoked from inside build's body.
      if (
        node.callee.type === 'Identifier' &&
        node.callee.name === 'build' &&
        insideFunctionNamed(ancestors, 'build')
      ) {
        recursiveBuild ??= node.loc?.start.line;
      }

      // Tri estimate — count geometry primitive calls at any depth, scaled by
      // any enclosing literal-bound for-loops (the dominant undercount in real
      // failures: radial arrays and CSG cutter loops that build N geometries).
      if (node.callee.type === 'Identifier') {
        let est = estimateGeometryTris(node.callee.name, node.arguments as acorn.Expression[]);

        // subdivide(geo, n): Loop subdivision quadruples tris per iteration.
        // When the input is an inline estimable call its base count is already
        // accumulated by this walker, so add only the growth (e * (4^n - 1)).
        if (est === null && node.callee.name === 'subdivide') {
          const inner = node.arguments[0];
          if (inner && inner.type === 'CallExpression' && inner.callee.type === 'Identifier') {
            const base = estimateGeometryTris(
              inner.callee.name,
              inner.arguments as acorn.Expression[],
            );
            if (base !== null) {
              const nArg = node.arguments[1];
              const n = Math.min(
                4, // cap: beyond 4 iterations the estimate is noise anyway
                nArg && nArg.type === 'Literal' && typeof nArg.value === 'number' ? nArg.value : 1,
              );
              est = base * (4 ** Math.max(0, n) - 1);
            }
          }
        }

        if (est !== null) {
          estimatedTris += est * loopMultiplier(ancestors);
        }
      }
    },
  });

  return { infiniteLoops, recursiveBuild, estimatedTris };
}

/**
 * Product of the literal iteration counts of every enclosing for-loop of the
 * shape `for (let i = 0; i < N; i++)` (or `<=`). Unknown bounds contribute 1
 * (no scaling) so the estimate only ever moves toward the truth. Capped so a
 * pathological literal can't produce a nonsense advisory.
 */
function loopMultiplier(ancestors: readonly acorn.Node[]): number {
  let mult = 1;
  for (const node of ancestors) {
    if (node.type !== 'ForStatement') continue;
    const f = node as acorn.ForStatement;
    if (f.test?.type !== 'BinaryExpression') continue;
    const { operator, right } = f.test;
    if (operator !== '<' && operator !== '<=') continue;
    if (right.type !== 'Literal' || typeof right.value !== 'number') continue;
    const n = operator === '<' ? right.value : right.value + 1;
    if (n > 1 && Number.isFinite(n)) mult *= Math.min(n, 256);
  }
  return Math.min(mult, 4096);
}

function insideFunctionNamed(ancestors: readonly acorn.AnyNode[], name: string): boolean {
  for (let i = ancestors.length - 1; i >= 0; i--) {
    const node = ancestors[i];
    if (!node) continue;
    if (node.type === 'FunctionDeclaration' && node.id?.name === name) return true;
  }
  return false;
}

function isConstantTruthy(node: acorn.Expression): boolean {
  if (node.type === 'Literal') {
    return Boolean(node.value);
  }
  if (node.type === 'Identifier') return false;
  // `1` / `!0` / `true` all show up as Literal or UnaryExpression.
  if (node.type === 'UnaryExpression' && node.operator === '!') {
    // `!0` -> truthy, `!1` -> falsy, `!true` -> falsy, `!false` -> truthy.
    if (node.argument.type === 'Literal') return !node.argument.value;
  }
  return false;
}

function hasBreak(body: acorn.Statement): boolean {
  let found = false;
  walk.simple(body, {
    BreakStatement() {
      found = true;
    },
    ReturnStatement() {
      found = true;
    },
    ThrowStatement() {
      found = true;
    },
  });
  return found;
}