@typesol/cli 0.16.0 → 0.18.0

package/dist/compiler/analyze.js

@@ -4,7 +4,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { CompileError, Reporter } from "./diagnostics.js";
 import { decodeAddress } from "../keys.js";
-import { optionKey, INT_INFO, INT_NAMES, scalarKey, isScalar, scalarSize, } from "./model.js";
+import { borshIdentical } from "./emit/borsh.js";
+import { optionKey, INT_INFO, INT_NAMES, scalarKey, fixedVecName, isScalar, scalarSize, typeName, } from "./model.js";
 export const LIB_PATH = fileURLToPath(new URL("../../lib/typesol.d.ts", import.meta.url));
 /** Names a struct field may not use because account parameters already expose them. */
 const RESERVED_FIELDS = new Set(["key", "lamports", "dataLen", "create", "equals", "get", "set", "length", "isSigner", "isWritable", "pdaBump"]);
@@ -57,6 +58,7 @@ const TYPE_EXPORTS = new Set([
     "TokenInterface",
     "FixedArray",
     "FixedString",
+    "FixedVec",
     "Program",
     "UncheckedProgram",
     "CpiAccount",
@@ -88,6 +90,7 @@ const TYPE_EXPORTS = new Set([
     "SelfProgram",
     "ProgramData",
     "SignerSeeds",
+    "SystemAccount",
 ]);
 /** Largest fixed array a struct may declare, and largest FixedString. */
 const MAX_ARRAY_LEN = 1_000_000;
@@ -97,6 +100,12 @@ export const MAX_ACCOUNT_SIZE = 10 * 1024 * 1024;
 /** sol_set_return_data's limit. */
 export const MAX_RETURN_DATA = 1024;
 export const MAX_CPI_ALLOCATION = 10 * 1024;
+/** A struct named by a type reference, through the type parameters of a generic helper's instance. */
+export function structNameOf(node, scope) {
+    if (!ts.isTypeReferenceNode(node) || !ts.isIdentifier(node.typeName) || node.typeArguments?.length)
+        return undefined;
+    return scope.structArgs?.get(node.typeName.text) ?? node.typeName.text;
+}
 export function snakeCase(name) {
     return name
         .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
@@ -225,7 +234,7 @@ export function analyze(entry) {
     const isExported = (n) => ts.canHaveModifiers(n) && (ts.getModifiers(n) ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
     const declare = (name, file) => {
         // These prefixes name the IDL types TypeSOL generates for FixedString<N>, Option and data enums in account data.
-        if (/^(FixedString\d|FixedOption_|FixedEnum_)/.test(name.text))
+        if (/^(FixedString\d|FixedVec\d|FixedOption_|FixedEnum_)/.test(name.text))
             reporter.fail(name, `"${name.text}" is reserved for IDL types TypeSOL generates; pick another name`);
         const prev = declared.get(name.text);
         if (prev)
@@ -313,7 +322,8 @@ export function analyze(entry) {
                     else {
                         if (stmt.name)
                             declare(stmt.name, file);
-                        helperNodes.push({ node: stmt, imports });
+                        if (stmt.name)
+                            helperNodes.push({ node: stmt, name: stmt.name.text, display: stmt.name.text, decl: stmt, imports });
                     }
                 }
                 else if (ts.isVariableStatement(stmt)) {
@@ -324,6 +334,14 @@ export function analyze(entry) {
                         if (!ts.isIdentifier(d.name) || !d.initializer)
                             reporter.fail(d, "declare const NAME = literal");
                         const init = d.initializer;
+                        // `const f = (…): T => …` / `const f = function (…) {…}`: a helper.
+                        if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) {
+                            if (isEntry && isExported(stmt))
+                                reporter.fail(d.name, "instructions are function declarations: export function name(…)");
+                            declare(d.name, file);
+                            helperNodes.push({ node: init, name: d.name.text, display: d.name.text, decl: d, imports });
+                            continue;
+                        }
                         let value;
                         if (ts.isCallExpression(init) && ts.isIdentifier(init.expression) && imports.get(init.expression.text) === "pubkey") {
                             const arg = init.arguments[0];
@@ -358,6 +376,7 @@ export function analyze(entry) {
         }
     }
     const fstrings = new Set();
+    const fixedVecs = new Map();
     const scopeFor = (imports) => ({ imports, enums, options, dataEnums });
     for (const c of pendingConstTypes) {
         reporter.guard(() => {
@@ -372,14 +391,113 @@ export function analyze(entry) {
             c.def.type = t;
         });
     }
-    const structs = analyzeStructs(interfaces, aliases, dataEnums, reporter, scopeFor, fstrings);
+    const structs = analyzeStructs(interfaces, aliases, dataEnums, reporter, scopeFor, fstrings, fixedVecs);
+    const checker = program.getTypeChecker();
+    // Local `const f = (…) => …` in any function body (and in those local functions): lifted to helpers.
+    const locals = [];
+    const taken = new Set();
+    const collectLocals = (body, outer, imports, fn) => {
+        const generic = !!fn.typeParameters?.length;
+        const visit = (n) => {
+            if (ts.isVariableDeclaration(n) && n.initializer && (ts.isArrowFunction(n.initializer) || ts.isFunctionExpression(n.initializer))) {
+                reporter.guard(() => {
+                    if (!ts.isIdentifier(n.name))
+                        reporter.fail(n.name, "name local functions: const f = (…) => …");
+                    if (generic)
+                        reporter.fail(n, "local functions inside a generic helper are not supported; declare this one at the top level");
+                    if (!(n.parent.flags & ts.NodeFlags.Const) || !ts.isVariableStatement(n.parent.parent))
+                        reporter.fail(n, "declare local functions with const: const f = (…) => …");
+                    if (n.name.text.includes("__") || n.name.text.includes("$"))
+                        reporter.fail(n.name, `"${n.name.text}": "__" and "$" are reserved in names`);
+                    let name = `${outer}__${n.name.text}`;
+                    for (let i = 2; taken.has(name); i++)
+                        name = `${outer}__${n.name.text}__${i}`;
+                    taken.add(name);
+                    const src = { node: n.initializer, name, display: n.name.text, decl: n, imports, outer: fn };
+                    locals.push(src);
+                    if (src.node.body)
+                        collectLocals(src.node.body, name, imports, src.node);
+                });
+                return;
+            }
+            ts.forEachChild(n, visit);
+        };
+        visit(body);
+    };
+    for (const f of functions)
+        if (f.node.body && f.node.name)
+            collectLocals(f.node.body, f.node.name.text, f.imports, f.node);
+    for (const h of [...helperNodes])
+        if (h.node.body)
+            collectLocals(h.node.body, h.name, h.imports, h.node);
+    const localDecls = new Set(locals.map((l) => l.decl));
+    // A local function that reads the enclosing function's variables (or calls one that does) is a closure: it is
+    // expanded where it is called, in the enclosing function. The others become helpers of their own.
+    const inline = new Set(locals.filter((l) => captures(l, localDecls, checker)).map((l) => l.decl));
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const l of locals)
+            if (!inline.has(l.decl) && references(l, inline, checker)) {
+                inline.add(l.decl);
+                changed = true;
+            }
+    }
+    const closureDecls = new Map(locals.filter((l) => inline.has(l.decl)).map((l) => [l.decl, l.display]));
     const helpers = new Map();
-    for (const fn of helperNodes) {
-        const h = reporter.guard(() => analyzeHelper(fn.node, reporter, scopeFor(fn.imports), structs));
+    const generics = new Map();
+    const helperDecls = new Map();
+    for (const fn of [...helperNodes, ...locals.filter((l) => !inline.has(l.decl))]) {
+        helperDecls.set(fn.decl, fn.name);
+        const fnParams = fn.node.parameters.map((p, i) => (p.type && ts.isFunctionTypeNode(p.type) ? i : -1)).filter((i) => i >= 0);
+        if (fn.node.typeParameters?.length || fnParams.length) {
+            reporter.guard(() => {
+                for (const tp of fn.node.typeParameters ?? [])
+                    if (tp.default)
+                        reporter.fail(tp, "type parameters of helpers take no default");
+                generics.set(fn.name, {
+                    name: fn.name,
+                    display: fn.display,
+                    node: fn.node,
+                    typeParams: (fn.node.typeParameters ?? []).map((t) => t.name.text),
+                    fnParams,
+                    imports: fn.imports,
+                });
+            });
+            continue;
+        }
+        const h = reporter.guard(() => analyzeHelper(fn.node, fn.name, fn.display, reporter, scopeFor(fn.imports), structs));
         if (h)
             helpers.set(h.name, h);
     }
-    reporter.guard(() => checkRecursion(helpers, reporter));
+    const instances = new Map();
+    const instantiate = (g, typeArgs, fnArgs = []) => {
+        const argKey = (t) => (t.kind === "struct" ? `S${t.name}` : scalarKey(t));
+        const key = [g.name, ...typeArgs.map(argKey), ...fnArgs.map((f) => `fn_${f}`)].join("__");
+        const done = instances.get(key);
+        if (done)
+            return done;
+        const bound = new Map();
+        const boundStructs = new Map();
+        g.typeParams.forEach((n, i) => {
+            const t = typeArgs[i];
+            if (t.kind === "struct")
+                boundStructs.set(n, t.name);
+            else
+                bound.set(n, t);
+        });
+        const display = `${g.display}<${[...typeArgs.map((t) => (t.kind === "struct" ? t.name : typeName(t))), ...fnArgs].join(", ")}>`;
+        const h = analyzeHelper(g.node, key, display, reporter, { ...scopeFor(g.imports), typeArgs: bound, structArgs: boundStructs }, structs, new Set(g.fnParams));
+        h.typeArgs = bound;
+        h.structArgs = boundStructs;
+        if (g.fnParams.length) {
+            h.fnArgs = new Map(g.fnParams.map((i, k) => [g.node.parameters[i].name.text, fnArgs[k]]));
+            h.fnArgIndexes = g.fnParams;
+        }
+        instances.set(key, h);
+        helpers.set(key, h);
+        return h;
+    };
+    reporter.guard(() => checkRecursion([...helperNodes, ...locals.filter((l) => !inline.has(l.decl))], helperDecls, checker, reporter));
     const accountStructs = new Set();
     const argStructs = new Set();
     const instructions = [];
@@ -390,12 +508,32 @@ export function analyze(entry) {
         instructions.push(ix);
         for (const a of ix.args)
             collectStructs(a.type, structs, dataEnums, argStructs);
+        for (const a of ix.args) {
+            const seen = new Set();
+            collectStructs(a.type, structs, dataEnums, seen);
+            // A @layout borsh struct is decoded as a whole argument; inside lists or enums it would need a fixed size.
+            const whole = a.type.kind === "structRef" ? a.type.struct : undefined;
+            for (const s of seen)
+                if (structs.get(s).layout === "borsh" && s !== whole)
+                    reporter.error(fn.node.name ?? fn.node, `argument ${a.name}: ${s} is @layout borsh; pass it as a whole argument, not inside a list or enum`);
+        }
+        // Arguments are Borsh: a FixedVec's padded layout is account data only (a @layout borsh struct's FixedVec is a Borsh Vec).
+        for (const a of ix.args) {
+            const seen = new Set();
+            collectStructs(a.type, structs, dataEnums, seen);
+            for (const s of seen)
+                if (structs.get(s).layout !== "borsh" && structs.get(s).fields.some((f) => f.type.kind === "vec" && f.type.cap !== undefined))
+                    reporter.error(fn.node.name ?? fn.node, `argument ${a.name}: ${s} holds a FixedVec, which only account data can; pass a Vec<T> argument instead`);
+        }
         // A returned struct goes out in its fixed layout, like an argument comes in: it cannot also be a Borsh event.
         if (ix.returns?.kind === "struct")
             collectStructs(ix.returns, structs, dataEnums, argStructs);
         for (const a of ix.accounts)
-            if (a.kind.kind === "account" || a.kind.kind === "init" || a.kind.kind === "zeroed" || a.kind.kind === "initIfNeeded")
+            if (a.kind.kind === "account" || a.kind.kind === "init" || a.kind.kind === "zeroed" || a.kind.kind === "initIfNeeded") {
                 accountStructs.add(a.kind.struct.name);
+                if (a.kind.struct.viewsOnly)
+                    reporter.error(a.node, `${a.kind.struct.name} holds a string (or an enum carrying one), so it is an argument, return value or event; account data uses FixedString<N>`);
+            }
     }
     checkSnakeDuplicates(instructions.map((ix) => ({ name: ix.node.name.text, node: ix.node.name })), "instructions", reporter);
     // emitCpi's event instruction (Anchor's EVENT_IX_TAG) is dispatched before every other instruction.
@@ -426,6 +564,9 @@ export function analyze(entry) {
             structs,
             instructions,
             helpers,
+            generics,
+            helperDecls,
+            closureDecls,
             errors,
             errorEnums,
             enums,
@@ -436,12 +577,14 @@ export function analyze(entry) {
             accountStructs,
             argStructs,
             fstrings,
+            fixedVecs,
         },
         sourceFile,
         files: programFiles(program, entryPath).map((f) => f.fileName),
         imports: entryImports,
         reporter,
-        checker: program.getTypeChecker(),
+        checker,
+        instantiate,
     };
 }
 /** Every struct an argument type contains (transitively), for IDL layout decisions. */
@@ -479,7 +622,7 @@ export function resolveArgAggregate(node, scope, structs) {
         if (scalar)
             return scalar;
         if (ts.isTypeReferenceNode(t) && ts.isIdentifier(t.typeName) && !t.typeArguments?.length) {
-            const s = structs.get(t.typeName.text);
+            const s = structs.get(structNameOf(t, scope));
             if (s && s.size !== undefined && !s.vec)
                 return { kind: "struct", name: s.name };
         }
@@ -515,6 +658,11 @@ export function typesolName(node, imports) {
 export function resolveScalarType(node, scope) {
     if (node.kind === ts.SyntaxKind.BooleanKeyword)
         return { kind: "bool" };
+    if (scope.typeArgs && ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName) && !node.typeArguments) {
+        const t = scope.typeArgs.get(node.typeName.text);
+        if (t)
+            return t;
+    }
     const n = typesolName(node, scope.imports);
     if (n && INT_NAMES.includes(n))
         return { kind: "int", name: n };
@@ -557,6 +705,9 @@ export function resolveValueType(node, scope, allowVec = false) {
         return { kind: "dataEnumArg", name: node.typeName.text };
     if (allowVec && typesolName(node, scope.imports) === "Vec") {
         const elemNode = node.typeArguments?.[0];
+        // Vec<string>: Borsh Vec<String>, read as views of the instruction data.
+        if (elemNode?.kind === ts.SyntaxKind.StringKeyword)
+            return { kind: "vecArg", elem: { kind: "string" } };
         const elem = elemNode && resolveScalarType(elemNode, scope);
         if (elem)
             return { kind: "vecArg", elem };
@@ -572,7 +723,7 @@ function numericLiteralArg(node) {
  * Resolve every exported interface. Field types may name other interfaces, so names are
  * collected first; sizes are computed after, rejecting cycles.
  */
-function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings) {
+function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings, fixedVecs) {
     const names = new Set(items.map((d) => d.decl.name.text));
     const enumNames = new Set(aliases.map((a) => a.decl.name.text));
     const structs = new Map();
@@ -628,6 +779,19 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
                 reporter.fail(targs[1], `array length must be 1..${MAX_ARRAY_LEN}`);
             return { kind: "array", elem, len };
         }
+        if (ext === "FixedVec") {
+            if (!targs[0])
+                reporter.fail(node, "FixedVec<T, N> needs an element type");
+            const elem = fieldType(targs[0]);
+            if (elem.kind === "string" || elem.kind === "vec")
+                reporter.fail(targs[0], "FixedVec elements must have a fixed size (use FixedString<N>)");
+            const cap = numericLiteralArg(targs[1]);
+            if (cap === undefined || !Number.isInteger(cap) || cap < 1 || cap > MAX_ARRAY_LEN)
+                reporter.fail(node, `FixedVec<T, N> needs a literal capacity 1..${MAX_ARRAY_LEN}, e.g. FixedVec<u64, 16>`);
+            const t = { kind: "vec", elem, cap };
+            fixedVecs.set(fixedVecName(t), t);
+            return t;
+        }
         if (ext === "FixedString") {
             const cap = numericLiteralArg(targs[0]);
             if (cap === undefined || !Number.isInteger(cap) || cap < 1 || cap > MAX_STRING_CAP)
@@ -637,7 +801,7 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
         }
         if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName) && names.has(node.typeName.text) && !targs.length)
             return { kind: "struct", name: node.typeName.text };
-        reporter.fail(node, "field type must be an integer, boolean, Pubkey, FixedArray<T, N>, FixedString<N>, string (events only) or another struct");
+        reporter.fail(node, "field type must be an integer, boolean, Pubkey, FixedArray<T, N>, FixedString<N>, FixedVec<T, N>, Vec<T> (last), string (events only) or another struct");
     };
     for (const { decl, imports: fileImports } of items) {
         scope = scopeFor(fileImports);
@@ -658,12 +822,17 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
                 if (problem)
                     reporter.fail(m.name, problem);
                 const type = fieldType(m.type);
-                if (type.kind === "vec" && m !== decl.members[decl.members.length - 1])
-                    reporter.fail(m, "a Vec<T> field must be the last field of the struct (its length changes the account size)");
+                if (type.kind === "vec" && type.cap === undefined && m !== decl.members[decl.members.length - 1])
+                    reporter.fail(m, "a Vec<T> field must be the last field of the struct (its length changes the account size); use FixedVec<T, N> for a list of at most N elsewhere");
                 fields.push({ name, type });
             }
             checkSnakeDuplicates(decl.members.map((m) => ({ name: m.name.text, node: m })), "fields", reporter);
             const name = decl.name.text;
+            // `/** @layout borsh */`: stored as Anchor stores it.
+            const layoutTag = ts.getJSDocTags(decl).find((t) => t.tagName.text === "layout");
+            const layoutText = typeof layoutTag?.comment === "string" ? layoutTag.comment.trim() : undefined;
+            if (layoutTag && layoutText !== "borsh" && layoutText !== "fixed")
+                reporter.fail(layoutTag, "@layout is borsh (Anchor's account bytes) or fixed (the default)");
             structs.set(name, {
                 name,
                 fields,
@@ -671,6 +840,7 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
                 accountDiscriminator: discriminator(`account:${name}`),
                 eventDiscriminator: discriminator(`event:${name}`),
                 node: decl,
+                layout: layoutText === "borsh" ? "borsh" : "fixed",
             });
         });
     }
@@ -766,8 +936,14 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
                     return undefined;
                 return 1 + e.payload;
             }
-            case "vec":
-                return 4; // the u32 length; elements live past the fixed part
+            case "vec": {
+                if (t.cap === undefined)
+                    return 4; // the u32 length; elements live past the fixed part
+                const e = sizeOf(t.elem, at);
+                if (e === undefined)
+                    reporter.fail(at, "FixedVec elements must have a fixed size");
+                return 4 + e * t.cap;
+            }
             case "string":
                 return undefined;
             case "fstring":
@@ -799,14 +975,18 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
         state.set(s.name, "visiting");
         let total = 0;
         for (const f of s.fields) {
-            const fsz = sizeOf(f.type, s.node);
+            // In a @layout borsh struct a string (or a data enum carrying one) is held as a TS_Str view: a C size, no layout.
+            const view = s.layout === "borsh" && (f.type.kind === "string" || (f.type.kind === "dataEnum" && sizeOf(f.type, s.node) === undefined));
+            if (view)
+                s.viewsOnly = true;
+            const fsz = view ? (f.type.kind === "string" ? 16 : 1 + dataEnums.get(f.type.name).payload) : sizeOf(f.type, s.node);
             total = total === undefined || fsz === undefined ? undefined : total + fsz;
         }
         s.size = total;
         if (total !== undefined && total + 8 > MAX_ACCOUNT_SIZE)
             reporter.fail(s.node.name, `${s.name} is ${total + 8} bytes with its discriminator; Solana accounts are at most ${MAX_ACCOUNT_SIZE} bytes`);
         const last = s.fields.at(-1);
-        if (last?.type.kind === "vec") {
+        if (last?.type.kind === "vec" && last.type.cap === undefined) {
             const elemSize = sizeOf(last.type.elem, s.node);
             if (elemSize === undefined)
                 reporter.fail(s.node, "Vec elements must have a fixed size");
@@ -816,27 +996,118 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
     };
     for (const s of structs.values())
         reporter.guard(() => visit(s));
+    for (const s of structs.values())
+        if (s.layout === "borsh")
+            reporter.guard(() => checkBorshLayout(s, structs, dataEnums, reporter));
     for (const e of dataEnums.values())
         reporter.guard(() => sizeOf({ kind: "dataEnum", name: e.name }, e.node));
     return structs;
 }
-function analyzeHelper(fn, reporter, scope, structs) {
-    if (!fn.name || !fn.body)
-        reporter.fail(fn, "helper functions need a name and a body");
-    if (fn.typeParameters?.length || fn.asteriskToken)
-        reporter.fail(fn, "helper functions cannot be generic or generators");
+const isFunctionNode = (n) => ts.isFunctionDeclaration(n) || ts.isArrowFunction(n) || ts.isFunctionExpression(n) || ts.isMethodDeclaration(n);
+/** Whether a local function reads a variable or parameter of a function around it (a closure). */
+function captures(l, localDecls, checker) {
+    const fn = l.node;
+    let found = false;
+    const visit = (n) => {
+        if (found)
+            return;
+        if (ts.isIdentifier(n)) {
+            const sym = ts.isShorthandPropertyAssignment(n.parent) ? checker.getShorthandAssignmentValueSymbol(n.parent) : checker.getSymbolAtLocation(n);
+            for (const d of sym?.declarations ?? []) {
+                if (!(ts.isVariableDeclaration(d) || ts.isParameter(d) || ts.isBindingElement(d)) || localDecls.has(d))
+                    continue;
+                if (d.getSourceFile() !== fn.getSourceFile() || (d.pos >= fn.pos && d.end <= fn.end))
+                    continue;
+                for (let p = d.parent; p; p = p.parent)
+                    if (isFunctionNode(p))
+                        found = true;
+            }
+        }
+        ts.forEachChild(n, visit);
+    };
+    if (fn.body)
+        visit(fn.body);
+    return found;
+}
+/** Whether a function's body names one of `decls` (a closure it calls). */
+function references(l, decls, checker) {
+    let found = false;
+    const visit = (n) => {
+        if (found)
+            return;
+        if (ts.isIdentifier(n))
+            for (const d of checker.getSymbolAtLocation(n)?.declarations ?? [])
+                if (decls.has(d))
+                    found = true;
+        ts.forEachChild(n, visit);
+    };
+    if (l.node.body)
+        visit(l.node.body);
+    return found;
+}
+/**
+ * A `@layout borsh` struct: its own fields may be FixedString (Borsh String), FixedVec (Borsh Vec) and Option; anything
+ * nested must already be Borsh-identical (fixed-size scalars, Pubkeys, enums, arrays and structs of them).
+ */
+function checkBorshLayout(s, structs, dataEnums, reporter) {
+    const model = { structs };
+    const fixed = (t) => borshIdentical(t, model);
+    for (const f of s.fields) {
+        const t = f.type;
+        const at = s.node.members.find((m) => m.name && ts.isIdentifier(m.name) && m.name.text === f.name) ?? s.node;
+        if (fixed(t) || t.kind === "fstring" || t.kind === "string")
+            continue;
+        if (t.kind === "dataEnum") {
+            // Borsh enum: tag, then the variant's fields; each a fixed-size value or a string.
+            for (const v of dataEnums.get(t.name)?.variants ?? [])
+                for (const vf of v.fields)
+                    if (!fixed(vf.type) && vf.type.kind !== "string")
+                        reporter.fail(at, `${t.name}.${v.name}.${vf.name} in a @layout borsh struct: enum variants hold fixed-size values and strings`);
+            continue;
+        }
+        if (t.kind === "vec" && t.cap === undefined)
+            reporter.fail(at, "a @layout borsh struct cannot end in a growable Vec<T>; use FixedVec<T, N> (Anchor's #[max_len(N)] Vec)");
+        if (t.kind === "vec" && (fixed(t.elem) || t.elem.kind === "fstring"))
+            continue;
+        if (t.kind === "option" && fixed(t.inner))
+            continue;
+        if (t.kind === "struct" && structs.get(t.name)?.layout === "borsh")
+            reporter.fail(at, `${t.name} is @layout borsh itself: only account structs take a layout; nest a struct without one`);
+        reporter.fail(at, `${typeName(t)} in a @layout borsh struct: its fields may be fixed-size values, FixedString<N>, FixedVec<T, N> (of those or of FixedString) and Option<T>; nested structs and lists hold fixed-size values only`);
+    }
+    for (const other of structs.values())
+        for (const f of other.fields) {
+            const inner = f.type.kind === "array" || f.type.kind === "vec" ? f.type.elem : f.type.kind === "option" ? f.type.inner : f.type;
+            if (inner.kind === "struct" && inner.name === s.name)
+                reporter.error(s.node.name, `${s.name} is @layout borsh, so it is account data only; ${other.name}.${f.name} cannot hold one`);
+        }
+}
+function analyzeHelper(fn, name, display, reporter, scope, structs, skip = new Set()) {
+    if (!fn.body)
+        reporter.fail(fn, "helper functions need a body");
+    if (fn.asteriskToken)
+        reporter.fail(fn, "helper functions cannot be generators");
+    if ((ts.getModifiers(fn) ?? []).some((m) => m.kind === ts.SyntaxKind.AsyncKeyword))
+        reporter.fail(fn, "helper functions cannot be async");
     if (!fn.type)
-        reporter.fail(fn.name, "helper functions need an explicit return type (void, an integer, boolean, Pubkey or a struct)");
-    let returns = fn.type.kind === ts.SyntaxKind.VoidKeyword ? undefined : resolveScalarType(fn.type, scope);
+        reporter.fail(fn.name ?? fn, "helper functions need an explicit return type (void, an integer, boolean, Pubkey or a struct)");
+    let returns = fn.type.kind === ts.SyntaxKind.VoidKeyword
+        ? undefined
+        : fn.type.kind === ts.SyntaxKind.StringKeyword
+            ? { kind: "string" }
+            : resolveScalarType(fn.type, scope);
     if (fn.type.kind !== ts.SyntaxKind.VoidKeyword && !returns) {
-        const s = ts.isTypeReferenceNode(fn.type) && ts.isIdentifier(fn.type.typeName) && !fn.type.typeArguments ? structs.get(fn.type.typeName.text) : undefined;
+        const sn = structNameOf(fn.type, scope);
+        const s = sn ? structs.get(sn) : undefined;
         if (s && (s.size === undefined || s.vec))
             reporter.fail(fn.type, `${s.name} has variable-size fields and cannot be returned; return a struct of fixed size`);
         if (!s)
-            reporter.fail(fn.type, "helpers return void, an integer, boolean, Pubkey or a struct");
+            reporter.fail(fn.type, "helpers return void, an integer, boolean, Pubkey, string, a struct or a type parameter");
         returns = { kind: "struct", name: s.name };
     }
-    const params = fn.parameters.map((p) => {
+    const params = fn.parameters
+        .filter((_, i) => !skip.has(i))
+        .map((p) => {
         if (!ts.isIdentifier(p.name) || !p.type || p.initializer || p.questionToken || p.dotDotDotToken)
             reporter.fail(p, "parameters need a plain name and an explicit type");
         // `p_<name>__n` carries a SignerSeeds count: "__" in a name could collide with it.
@@ -856,16 +1127,43 @@ function analyzeHelper(fn, reporter, scope, structs) {
             reporter.fail(p.type, "helpers take accounts that exist: create Init/InitIfNeeded/Zeroed accounts in the instruction, then pass them as Mut<T>");
         return { name: p.name.text, type: { kind: "account" }, account, node: p };
     });
-    return { name: fn.name.text, params, returns, node: fn, imports: scope.imports };
+    return { name, display, params, returns, node: fn, statements: bodyStatements(fn, !returns), imports: scope.imports };
+}
+/** A function's statements; an arrow's expression body is a `return expr;` (or `expr;` when it returns void). */
+function bodyStatements(fn, isVoid) {
+    const body = fn.body;
+    if (ts.isBlock(body))
+        return body.statements;
+    const f = ts.factory;
+    const stmt = isVoid ? f.createExpressionStatement(body) : f.createReturnStatement(body);
+    ts.setTextRange(stmt, body);
+    stmt.parent = fn;
+    return [stmt];
+}
+/** The helper (or generic) a call's callee names: a local function by its declaration, others by name. */
+export function calleeName(callee, decls, checker) {
+    let sym = checker.getSymbolAtLocation(callee);
+    if (sym && sym.flags & ts.SymbolFlags.Alias)
+        sym = checker.getAliasedSymbol(sym);
+    for (const d of sym?.declarations ?? []) {
+        const name = decls.get(d);
+        if (name)
+            return name;
+    }
+    return undefined;
 }
 /** Helpers may call each other, but not recursively: SBF has a small fixed call depth. */
-function checkRecursion(helpers, reporter) {
+function checkRecursion(sources, decls, checker, reporter) {
     const calls = new Map();
-    for (const h of helpers.values()) {
+    const byName = new Map(sources.map((s) => [s.name, s]));
+    for (const h of sources) {
         const out = [];
         const visit = (n) => {
-            if (ts.isCallExpression(n) && ts.isIdentifier(n.expression) && helpers.has(n.expression.text))
-                out.push(n.expression.text);
+            if (ts.isCallExpression(n) && ts.isIdentifier(n.expression)) {
+                const c = calleeName(n.expression, decls, checker);
+                if (c)
+                    out.push(c);
+            }
             ts.forEachChild(n, visit);
         };
         visit(h.node.body);
@@ -875,14 +1173,15 @@ function checkRecursion(helpers, reporter) {
     const walk = (name, path) => {
         if (state.get(name) === "done")
             return;
+        const src = byName.get(name);
         if (state.get(name) === "visiting")
-            reporter.fail(helpers.get(name).node.name, `recursion is not supported: ${[...path, name].join(" -> ")}`);
+            reporter.fail(src.node.name ?? src.node, `recursion is not supported: ${[...path, name].map((n) => byName.get(n).display).join(" -> ")}`);
         state.set(name, "visiting");
         for (const c of calls.get(name) ?? [])
             walk(c, [...path, name]);
         state.set(name, "done");
     };
-    for (const name of helpers.keys())
+    for (const name of byName.keys())
         walk(name, []);
 }
 function analyzeInstruction(fn, reporter, scope, structs) {
@@ -895,7 +1194,7 @@ function analyzeInstruction(fn, reporter, scope, structs) {
         reporter.fail(fn, "instructions cannot be async or generators");
     let returns;
     if (fn.type && fn.type.kind !== ts.SyntaxKind.VoidKeyword) {
-        returns = resolveScalarType(fn.type, scope);
+        returns = fn.type.kind === ts.SyntaxKind.StringKeyword ? { kind: "string" } : resolveScalarType(fn.type, scope);
         const s = !returns && ts.isTypeReferenceNode(fn.type) && ts.isIdentifier(fn.type.typeName) && !fn.type.typeArguments
             ? structs.get(fn.type.typeName.text)
             : undefined;
@@ -908,7 +1207,7 @@ function analyzeInstruction(fn, reporter, scope, structs) {
             returns = { kind: "struct", name: s.name };
         }
         if (!returns)
-            reporter.fail(fn.type, "instructions return void, one integer, boolean or Pubkey, or a fixed-size struct (sent as return data)");
+            reporter.fail(fn.type, "instructions return void, one integer, boolean, Pubkey or string, or a fixed-size struct (sent as return data)");
     }
     const accounts = [];
     const args = [];
@@ -948,7 +1247,8 @@ function analyzeInstruction(fn, reporter, scope, structs) {
             const inner = unwrapConstraints(typeNode, reporter, imports, constraints);
             const kind = resolveAccountKind(inner, reporter, imports, structs);
             if (optional &&
-                (["init", "initIfNeeded", "zeroed", "pyth", "eventAuthority", "selfProgram", "programData"].includes(kind.kind) || (kind.kind === "token" && kind.init)))
+                (["init", "initIfNeeded", "zeroed", "pyth", "eventAuthority", "selfProgram", "programData"].includes(kind.kind) ||
+                    ((kind.kind === "token" || kind.kind === "mint") && kind.init)))
                 reporter.fail(p, "Init, InitIfNeeded, Zeroed, PythPriceUpdate, EventAuthority, SelfProgram and ProgramData accounts cannot be optional");
             accounts.push({ name: p.name.text, index: accounts.length, kind, node: p, constraints, ...(optional ? { optional } : {}) });
         });
@@ -961,10 +1261,11 @@ function analyzeInstruction(fn, reporter, scope, structs) {
     // Constraints refer to other parameters by name: check them now that all are known.
     for (const a of accounts) {
         const c = a.constraints;
-        if (a.kind.kind === "token" && a.kind.init && !c.ata)
-            reporter.fail(a.node, 'Init<TokenAccount> / InitIfNeeded<TokenAccount> create associated token accounts: wrap them in Ata<…, "owner", "mint">');
-        if (a.kind.kind === "token" && a.kind.init && (c.hasOne.length || c.seeds || c.address || c.owner || c.executable))
+        if (a.kind.kind === "token" && a.kind.init && c.ata && (c.hasOne.length || c.seeds || c.address || c.owner || c.executable))
             reporter.fail(a.node, "an associated token account created here is checked against Ata<…>'s owner and mint; drop HasOne/Seeds/Address/Owner/Executable");
+        // Token accounts and mints created in the body are checked there (seeds, mint, authorities).
+        if ((a.kind.kind === "token" || a.kind.kind === "mint") && a.kind.init && !c.ata && (c.hasOne.length || c.seeds || c.address || c.owner || c.executable))
+            reporter.fail(a.node, `${a.name}.create(...) takes the seeds, mint and authorities; drop HasOne/Seeds/Address/Owner/Executable`);
         if (!c.hasOne.length && !c.seeds && !c.closeTo && !c.ata)
             continue;
         const struct = a.kind.kind === "account" || a.kind.kind === "init" || a.kind.kind === "initIfNeeded" || a.kind.kind === "zeroed" ? a.kind.struct : undefined;
@@ -1038,7 +1339,8 @@ function analyzeInstruction(fn, reporter, scope, structs) {
     const pushes = (() => {
         let found = false;
         const visit = (n) => {
-            if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression) && n.expression.name.text === "push")
+            // Vec.push(value, payer) grows the account; FixedVec.push(value) does not.
+            if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression) && n.expression.name.text === "push" && n.arguments.length === 2)
                 found = true;
             ts.forEachChild(n, visit);
         };
@@ -1155,6 +1457,8 @@ function resolveAccountKind(node, reporter, imports, structs) {
         // Any account (helpers that accept every kind, e.g. generated CPI helpers).
         case "AccountMeta":
             return { kind: "info", mut: false };
+        case "SystemAccount":
+            return { kind: "info", mut: false, systemOwned: true };
         case "TokenAccount":
             return { kind: "token", mut: false };
         case "Mint":
@@ -1212,9 +1516,11 @@ function resolveAccountKind(node, reporter, imports, structs) {
         case "Init": {
             if (typesolName(inner(), imports) === "TokenAccount")
                 return { kind: "token", mut: true, init: "create" };
+            if (typesolName(inner(), imports) === "Mint")
+                return { kind: "mint", mut: true, init: "create" };
             const s = structOf(inner());
             if (!s)
-                reporter.fail(node, "Init<T> needs a struct declared in this program");
+                reporter.fail(node, "Init<T> needs a struct declared in this program, TokenAccount or Mint");
             if (s.size + 8 > MAX_CPI_ALLOCATION)
                 reporter.fail(node, `${s.name} needs ${s.size + 8} bytes but a program can create at most ${MAX_CPI_ALLOCATION} through Init<T>; have the client allocate it and take it as Zeroed<${s.name}>`);
             return { kind: "init", struct: s };
@@ -1222,6 +1528,8 @@ function resolveAccountKind(node, reporter, imports, structs) {
         case "InitIfNeeded": {
             if (typesolName(inner(), imports) === "TokenAccount")
                 return { kind: "token", mut: true, init: "ifNeeded" };
+            if (typesolName(inner(), imports) === "Mint")
+                return { kind: "mint", mut: true, init: "ifNeeded" };
             const s = structOf(inner());
             if (!s)
                 reporter.fail(node, "InitIfNeeded<T> needs a struct declared in this program");
@@ -1235,6 +1543,8 @@ function resolveAccountKind(node, reporter, imports, structs) {
                 reporter.fail(node, "Zeroed<T> needs a struct declared in this program");
             if (s.vec)
                 reporter.fail(node, `${s.name} ends in a Vec; Zeroed<T> is for fixed-size (large) accounts`);
+            if (s.layout === "borsh")
+                reporter.fail(node, `${s.name} is @layout borsh; Zeroed<T> reads large accounts in place, so it takes fixed layouts only`);
             return { kind: "zeroed", struct: s };
         }
         case "Mut": {
@@ -1247,6 +1557,8 @@ function resolveAccountKind(node, reporter, imports, structs) {
                 return { kind: "signer", mut: true };
             if (innerName === "AccountInfo" || innerName === "AccountMeta")
                 return { kind: "info", mut: true };
+            if (innerName === "SystemAccount")
+                return { kind: "info", mut: true, systemOwned: true };
             if (innerName === "TokenAccount")
                 return { kind: "token", mut: true };
             if (innerName === "Mint")