gofront 1.8.0 → 1.9.0

package/src/typechecker/index.js

@@ -21,12 +21,14 @@ import { setupGlobals } from "./stdlib/index.js";
 import { terminationMethods } from "./termination.js";
 import {
 	ANY,
+	BOOL,
 	defaultType,
 	ERROR,
 	INTRINSICS,
 	isAny,
 	isBool,
 	isVoid,
+	NATIVES,
 	Scope,
 	TAINTED_ANY,
 	TypeCheckError,
@@ -39,6 +41,7 @@ import {
 const TEMPL_NODE_CHECKS = {
 	TemplElement: "_checkTemplElement",
 	TemplExpr: "_checkTemplLeaf",
+	TemplChildren: "_checkTemplChildren",
 	TemplComponent: "_checkTemplLeaf",
 	TemplIf: "_checkTemplIf",
 	TemplFor: "_checkTemplFor",
@@ -105,6 +108,7 @@ export class TypeChecker {
 		this.universe = new Scope();
 		this.globals = new Scope(this.universe);
 		this.errors = [];
+		this._reportedAt = new WeakMap();
 		this.warnings = []; // non-fatal diagnostics (e.g. boundary-call-in-loop hints)
 		this.target = "js";
 		this.pkgName = null;
@@ -117,6 +121,12 @@ export class TypeChecker {
 		this._typeSwitchDepth = 0; // for rejecting fallthrough in type switch
 		this._deferCount = 0; // tracks defer usage in current function body
 		this._imports = []; // tracked imports for unused-import detection
+		// Lazy body checking (Go-source stdlib): with `lazyBodies` set, checkAll
+		// types declarations only and `checkBody` types a function or method
+		// body when it is first reached.
+		this.lazyBodies = false;
+		this.stats = { bodiesChecked: 0 };
+		this._lazyBodies = new Map(); // FuncDecl/MethodDecl -> its program
 		this._constExprs = new Map(); // name -> AST initializer expr
 		this._importedConsts = new Map(); // dot-imported const name -> value
 		this._externalNames = new Set(); // package-scope names from .d.ts / npm definitions
@@ -174,7 +184,10 @@ export class TypeChecker {
 				this._ambiguousImported.add(prior);
 				this._ambiguousImported.add(type);
 			}
-			this.types.set(name, type);
+			// A renamed type (`Pt` declared as `Pt$$b`) never takes the bare name:
+			// another package owns it, and this package's own declaration would
+			// otherwise reuse the imported placeholder. It is reached as `pkg.Pt`.
+			if (type.name === name) this.types.set(name, type);
 			this.types.set(`${pkgName}.${name}`, type);
 		}
 	}
@@ -255,6 +268,14 @@ export class TypeChecker {
 	}
 
 	err(msg, node, hint = null) {
+		// One diagnostic per root cause: a node revisited by a later pass (a
+		// signature resolved at declaration and again in the body) reports once.
+		if (node && typeof node === "object") {
+			const seen = this._reportedAt.get(node) ?? new Set();
+			this._reportedAt.set(node, seen);
+			if (seen.has(msg)) return TAINTED_ANY;
+			seen.add(msg);
+		}
 		const e = new TypeCheckError(
 			msg,
 			node,
@@ -702,7 +723,11 @@ export class TypeChecker {
 		const { cycles } = orderPackageInits(programs);
 		for (const c of cycles) {
 			const owner = programs.find((p) =>
-				p.decls?.some((d) => d.kind === "VarDecl" && d.decls?.includes(c.spec)),
+				p.decls?.some(
+					(d) =>
+						(d.kind === "VarDecl" || d.kind === "ConstDecl") &&
+						d.decls?.includes(c.spec),
+				),
 			);
 			if (owner) this._setCurrentFile(owner);
 			this.err(c.message, c.spec);
@@ -725,6 +750,11 @@ export class TypeChecker {
 			this._setCurrentFile(p);
 			for (const d of p.decls) {
 				if (
+					this.lazyBodies &&
+					(d.kind === "FuncDecl" || d.kind === "MethodDecl")
+				)
+					this._deferBody(d, p);
+				else if (
 					d.kind === "FuncDecl" ||
 					d.kind === "MethodDecl" ||
 					d.kind === "TemplDecl"
@@ -735,14 +765,48 @@ export class TypeChecker {
 		}
 	}
 
+	// Lazy mode: validate what does not need the body now, check it on demand.
+	_deferBody(decl, program) {
+		if (decl.intrinsic) this._checkIntrinsic(decl);
+		if (decl.native) this._checkNative(decl);
+		this._lazyBodies.set(decl, program);
+	}
+
+	// Types the body of a function or method deferred by `lazyBodies`; a
+	// declaration checked already (or not deferred) is left alone.
+	checkBody(decl) {
+		const program = this._lazyBodies.get(decl);
+		if (!program) return;
+		this._lazyBodies.delete(decl);
+		this._setCurrentFile(program);
+		this.checkTopDecl(decl, this.globals);
+	}
+
 	// ── Shared pass helpers ──────────────────────────────────────
 
+	// Instances made while types were collected (`struct{ Inner[int] }`) have
+	// no methods yet, and a type embedding another embedder (`Deep` over `E`
+	// over `Base`) needs the inner promotion first, so repeat until nothing
+	// new is promoted.
 	_promoteEmbeddedMethods() {
+		const structs = [];
 		for (const type of this.types.values()) {
-			this._promoteEmbeddedInto(type.underlying);
-			for (const inst of type._generic?._instances?.values() ?? [])
-				this._promoteEmbeddedInto(inst.underlying);
+			structs.push(type.underlying);
+			for (const inst of type._generic?._instances?.values() ?? []) {
+				this._syncInstanceMethods(type._generic, inst);
+				structs.push(inst.underlying);
+			}
 		}
+		const count = () =>
+			structs.reduce(
+				(n, st) => n + (st?.methods?.size ?? 0) + (st?.fields?.size ?? 0),
+				0,
+			);
+		let before;
+		do {
+			before = count();
+			for (const st of structs) this._promoteEmbeddedInto(st);
+		} while (count() !== before);
 	}
 
 	_promoteEmbeddedInto(struct) {
@@ -750,8 +814,21 @@ export class TypeChecker {
 		for (const embed of struct._embeds) {
 			const inner = embed.kind === "pointer" ? embed.base : embed;
 			const base = inner.kind === "named" ? inner.underlying : inner;
-			if (base?.kind !== "struct" || !base.methods) continue;
-			for (const [mName, mType] of base.methods.entries()) {
+			// Fields of an embedded type declared after the embedder were not
+			// there when the embedder's fields were collected.
+			if (base?.kind === "struct" && struct.fields)
+				for (const [k, v] of base.fields)
+					if (!struct.fields.has(k)) struct.fields.set(k, v);
+			// A named non-struct type (`time.Duration`) keeps its methods on
+			// the named type itself.
+			const methods =
+				base?.kind === "struct"
+					? base.methods
+					: inner.kind === "named" && base?.kind !== "interface"
+						? inner.methods
+						: null;
+			if (!methods) continue;
+			for (const [mName, mType] of methods.entries()) {
 				if (!struct.methods.has(mName)) struct.methods.set(mName, mType);
 			}
 		}
@@ -801,6 +878,9 @@ export class TypeChecker {
 			this.globals.define(decl.name, named);
 			return;
 		}
+		// A type declared inside a function is registered before its fields
+		// resolve so `next *L` finds it; package-level types already are.
+		this._registerLocalTypePlaceholder(decl);
 		let underlying = this.resolveTypeNode(decl.type, this.globals);
 		// `type W V` with V a named array: W's underlying type is V's array.
 		if (!decl.isAlias && underlying.kind === "named") {
@@ -836,6 +916,13 @@ export class TypeChecker {
 		this.globals.define(decl.name, named);
 	}
 
+	_registerLocalTypePlaceholder(decl) {
+		if (decl.isAlias || this.types.has(decl.name)) return;
+		const placeholder = { kind: "named", name: decl.name, underlying: null };
+		this.types.set(decl.name, placeholder);
+		this.globals.define(decl.name, placeholder);
+	}
+
 	// type A[P any] = T[P] — Go 1.24 generic alias. The declaration is a
 	// template only: each instantiation A[X] substitutes X into the aliased
 	// type and resolves to exactly that type (no new named type).
@@ -888,6 +975,9 @@ export class TypeChecker {
 	_registerFuncDecl(decl, funcType, typeParamTypes) {
 		if (this.globals.symbols.has(decl.name) && decl.name !== "init")
 			this.err(`${decl.name} redeclared in this block`, decl);
+		if (decl.native) funcType.native = decl.native;
+		this._funcDeclNames ??= new Set();
+		this._funcDeclNames.add(decl.name);
 		if (typeParamTypes) {
 			this.globals.define(decl.name, {
 				kind: "generic",
@@ -932,6 +1022,9 @@ export class TypeChecker {
 	}
 
 	_attachNonGenericMethod(decl, funcType) {
+		// Codegen of an importing package reads the body of a Go-source
+		// method (does it accept a nil receiver?).
+		funcType._methodDecl = decl;
 		const recvType = this.resolveTypeNodeName(decl.recvType, this.globals);
 		const base = recvType?.underlying ?? recvType;
 		if (base?.kind === "struct") {
@@ -1008,12 +1101,26 @@ export class TypeChecker {
 
 	_checkTemplElement(n, scope) {
 		for (const a of n.attrs ?? []) {
-			if (a.kind === "expr" || a.kind === "cond-bool")
-				this._checkTemplExpr(a, a.tokens, scope);
+			if (a.kind === "expr") this._checkTemplExpr(a, a.tokens, scope);
+			else if (a.kind === "cond-bool") this._checkTemplCondAttr(a, scope);
 		}
 		this._checkTemplNodes(n.children, scope);
 	}
 
+	// `name?={ cond }` sets the attribute when `cond` is true.
+	_checkTemplCondAttr(a, scope) {
+		const t = this._checkTemplExpr(a, a.tokens, scope);
+		if (t && !isBool(t) && !isAny(t))
+			this.err(`Conditional attribute '${a.name}' must be bool`, a.expr);
+	}
+
+	// `{ name... }` names a variadic parameter. A templ without a `children`
+	// parameter may still write `{ children... }` (it mounts nothing).
+	_checkTemplChildren(n, scope) {
+		if (n.name === "children" && !scope.lookup("children")) return;
+		this._checkTemplExpr(n, [], scope);
+	}
+
 	_checkTemplLeaf(n, scope) {
 		this._checkTemplExpr(n, n.tokens, scope);
 	}
@@ -1028,8 +1135,13 @@ export class TypeChecker {
 
 	_checkTemplSwitch(n, scope) {
 		this._checkTemplExpr(n, n.exprTokens, scope);
+		// A tag that failed to parse leaves `n.expr` unset: not a tagless switch.
+		const tagless = !n.exprTokens?.length;
 		for (const c of n.cases ?? []) {
 			this._checkTemplExpr(c, c.caseTokens, scope);
+			for (const e of c.exprs?.slice(1) ?? []) this.checkExpr(e, scope);
+			if (n.expr || tagless)
+				for (const e of c.exprs ?? []) this._checkCaseValue(n.expr, e);
 			this._checkTemplNodes(c.body, scope);
 		}
 	}
@@ -1147,8 +1259,27 @@ export class TypeChecker {
 			);
 	}
 
+	_checkNative(decl) {
+		if (!this.isStdlib && !this.nativesChecked)
+			return this.err(
+				"//gofront:native is reserved for the standard library",
+				decl,
+			);
+		if (decl.kind !== "FuncDecl")
+			return this.err(
+				`native '${decl.native}' must mark a function, not a method`,
+				decl,
+			);
+		if (!NATIVES.has(decl.native))
+			return this.err(`unknown native '${decl.native}'`, decl);
+		if (decl._bodyless)
+			this.err(`native '${decl.native}' must have a Go body`, decl);
+	}
+
 	checkFuncDecl(decl, outer) {
+		this.stats.bodiesChecked++;
 		if (decl.intrinsic) this._checkIntrinsic(decl);
+		if (decl.native) this._checkNative(decl);
 		if (
 			(this.target === "wasm" || this.target === "both") &&
 			(decl.async || decl.isAsync)
@@ -1173,6 +1304,8 @@ export class TypeChecker {
 	}
 
 	checkMethodDecl(decl, outer) {
+		this.stats.bodiesChecked++;
+		if (decl.native) this._checkNative(decl);
 		if (
 			(this.target === "wasm" || this.target === "both") &&
 			(decl.async || decl.isAsync)
@@ -1199,7 +1332,13 @@ export class TypeChecker {
 			inner.define(p.name, this._paramType(p, inner));
 		}
 		const returnType = this._setupFuncReturnType(decl, inner);
-		this._runFuncBody(decl, inner, returnType);
+		const savedRecvGeneric = this._recvGeneric;
+		this._recvGeneric = recvNamedType?._generic;
+		try {
+			this._runFuncBody(decl, inner, returnType);
+		} finally {
+			this._recvGeneric = savedRecvGeneric;
+		}
 		this._checkMissingReturn(decl, returnType, "method");
 	}
 
@@ -1210,14 +1349,19 @@ export class TypeChecker {
 		return p.variadic ? { kind: "slice", elem: t } : t;
 	}
 
-	_injectTypeParams(decl, inner, outer) {
+	_injectTypeParams(decl, inner, _outer) {
 		if (!decl.typeParams) return;
-		for (const tp of decl.typeParams) {
-			const constraint = tp.constraint
-				? this.resolveTypeNode(tp.constraint, outer)
-				: ANY;
-			inner.define(tp.name, { kind: "typeParam", name: tp.name, constraint });
-		}
+		// Declare every parameter first so a constraint may mention one that
+		// comes later in the list (`[S ~[]E, E any]`).
+		const params = decl.typeParams.map((tp) => {
+			const t = { kind: "typeParam", name: tp.name, constraint: ANY };
+			inner.define(tp.name, t);
+			return t;
+		});
+		decl.typeParams.forEach((tp, i) => {
+			if (tp.constraint)
+				params[i].constraint = this.resolveTypeNode(tp.constraint, inner);
+		});
 	}
 
 	// Inside a method of `G[T]` the receiver is the instance `G[T]` over the
@@ -1258,7 +1402,11 @@ export class TypeChecker {
 	}
 
 	_checkMissingReturn(decl, returnType, kind) {
-		if (!isVoid(returnType) && !returnType._hasNamedReturns) {
+		if (
+			!decl._bodyless &&
+			!isVoid(returnType) &&
+			!returnType._hasNamedReturns
+		) {
 			if (!this._isTerminating(decl.body)) {
 				this.err(`missing return at end of ${kind} '${decl.name}'`, decl);
 			}
@@ -1281,21 +1429,7 @@ export class TypeChecker {
 		for (const spec of decl.decls) {
 			let type = spec.type ? this.resolveTypeNode(spec.type, scope) : null;
 			if (spec.value) {
-				const valTypes = spec.value.map((v) => this.checkExpr(v, scope));
-				const isTuple = valTypes.length === 1 && valTypes[0]?.kind === "tuple";
-				const valTypesFlat = isTuple ? valTypes[0].types : valTypes;
-				if (spec.names.length !== valTypesFlat.length) {
-					const vars =
-						spec.names.length === 1
-							? "1 variable"
-							: `${spec.names.length} variables`;
-					const vals = isTuple
-						? `returns ${valTypesFlat.length} values`
-						: valTypesFlat.length === 1
-							? "1 value"
-							: `${valTypesFlat.length} values`;
-					this.err(`assignment mismatch: ${vars} but ${vals}`, spec);
-				}
+				const valTypesFlat = this._varSpecValueTypes(spec, scope);
 				for (let i = 0; i < spec.names.length; i++) {
 					const vt = valTypesFlat[i] ?? ANY;
 					const varType = type ?? defaultType(vt) ?? ANY;
@@ -1318,6 +1452,45 @@ export class TypeChecker {
 		this._sharedAllocOk = savedSharedAlloc;
 	}
 
+	// The type of each value a `var` spec binds (a multi-value call or a
+	// comma-ok form spreads over several names); reports a count mismatch.
+	_varSpecValueTypes(spec, scope) {
+		const commaOk = this._checkVarCommaOk(spec, scope);
+		const valTypes = commaOk ?? spec.value.map((v) => this.checkExpr(v, scope));
+		const isTuple =
+			!commaOk && valTypes.length === 1 && valTypes[0]?.kind === "tuple";
+		const flat = isTuple ? valTypes[0].types : valTypes;
+		if (spec.names.length !== flat.length && !flat.some((t) => t?._tainted))
+			this._reportAssignMismatch(spec.names.length, flat.length, isTuple, spec);
+		return flat;
+	}
+
+	_reportAssignMismatch(nameCount, valueCount, isTuple, node) {
+		const vars = nameCount === 1 ? "1 variable" : `${nameCount} variables`;
+		const vals = isTuple
+			? `returns ${valueCount} values`
+			: valueCount === 1
+				? "1 value"
+				: `${valueCount} values`;
+		this.err(`assignment mismatch: ${vars} but ${vals}`, node);
+	}
+
+	// `var v, ok = m[k]` / `var v, ok = x.(T)`: the comma-ok forms yield the
+	// value and a bool. Returns their types, or null for any other spec.
+	_checkVarCommaOk(spec, scope) {
+		if (spec.names.length !== 2 || spec.value.length !== 1) return null;
+		const value = spec.value[0];
+		if (value.kind === "TypeAssertExpr") {
+			value._commaOk = true;
+			spec._commaOk = true;
+			return [this.checkExpr(value, scope), BOOL];
+		}
+		const stmt = { lhs: spec.names, rhs: spec.value };
+		const types = this._checkAssignCommaOkMap(stmt, scope);
+		if (types) spec._commaOk = true;
+		return types;
+	}
+
 	checkConstDecl(decl, scope) {
 		for (const spec of decl.decls) {
 			const valTypes = spec.value.map((v) => this.checkExpr(v, scope));
@@ -1335,6 +1508,8 @@ export class TypeChecker {
 						expr,
 						"constant declaration",
 					);
+				// `const D Duration = 1` is a BigInt in JS.
+				if (spec.type && expr) this._tag64BitNode(this.resolveType(type), expr);
 				scope.defineConst(name, type, expr);
 			}
 		}

package/src/typechecker/init-order.js

@@ -8,10 +8,9 @@
 // (a constant may name one declared later).
 //
 // The checker reports cycles; both backends emit initialisers in this order.
-// Shadowing is handled conservatively: a name declared anywhere in a function
-// body (or as a parameter) is never counted as a reference to the package-level
-// name inside that function, so the analysis can miss a dependency but never
-// invents a cycle.
+// Shadowing follows Go's block scoping: a name declared by a parameter, result,
+// receiver or statement hides the package-level one from the next statement to
+// the end of its block, and not outside it.
 
 function forEachChildNode(node, fn) {
 	for (const key of Object.keys(node)) {
@@ -21,34 +20,35 @@ function forEachChildNode(node, fn) {
 	}
 }
 
-// Names declared inside a function-like node (parameters, results, locals).
-function declaredNames(node, out = new Set()) {
-	if (!node || typeof node !== "object") return out;
-	if (Array.isArray(node)) {
-		for (const n of node) declaredNames(n, out);
-		return out;
+// A lexical scope of locally declared names.
+class Shadow {
+	constructor(parent = null) {
+		this.parent = parent;
+		this.names = new Set();
 	}
-	if (node.kind === "DefineStmt") {
-		for (const l of [node.lhs].flat()) if (l?.kind === "Ident") out.add(l.name);
-	} else if (node.kind === "VarDecl" || node.kind === "ConstDecl") {
-		for (const spec of node.decls ?? []) for (const n of spec.names) out.add(n);
-	} else if (node.kind === "RangeStmt" || node.kind === "ForRangeStmt") {
-		for (const k of [node.key, node.value, node.keyVar, node.valueVar])
-			if (k?.kind === "Ident") out.add(k.name);
-		if (typeof node.key === "string") out.add(node.key);
-		if (typeof node.value === "string") out.add(node.value);
-	} else if (node.kind === "TypeSwitchStmt" && node.assign) {
-		out.add(node.assign);
+
+	has(name) {
+		for (let s = this; s; s = s.parent) if (s.names.has(name)) return true;
+		return false;
 	}
-	if (Array.isArray(node.params))
-		for (const p of node.params) if (p?.name) out.add(p.name);
-	if (node.recvName) out.add(node.recvName);
-	for (const r of node.returnType?._namedReturns ?? [])
-		if (r.name) out.add(r.name);
-	forEachChildNode(node, (c) => declaredNames(c, out));
+
+	add(...names) {
+		for (const n of names) if (n) this.names.add(n);
+	}
+}
+
+// Names a function-like node declares for its body: receiver, parameters and
+// named results.
+function signatureNames(node) {
+	const out = [];
+	if (node.recvName) out.push(node.recvName);
+	for (const p of node.params ?? []) if (p?.name) out.push(p.name);
+	for (const r of node.returnType?._namedReturns ?? []) out.push(r.name);
 	return out;
 }
 
+const lhsName = (l) => (typeof l === "string" ? l : l?.name);
+
 // The `Type.method` key of the declaration `name` selects on a value of type
 // `t`, found the way the checker finds it: on the type itself, else on an
 // embedded type (through pointers too).  Interface methods have no body to
@@ -83,6 +83,60 @@ function litHasExprKeys(lit) {
 	return ["MapType", "SliceType", "ArrayType"].includes(lit.typeExpr?.kind);
 }
 
+// Statements that open a scope and declare names as they run.  Each handler
+// walks the node's children in order, adding declarations to `shadow` after
+// the expressions that cannot see them.
+const SCOPED = {
+	FuncDecl: walkFunc,
+	MethodDecl: walkFunc,
+	FuncLit: walkFunc,
+	Block: (node, shadow, ctx, out) =>
+		walkRefs(node.stmts, new Shadow(shadow), ctx, out),
+	DefineStmt: (node, shadow, ctx, out) => {
+		walkRefs(node.rhs, shadow, ctx, out);
+		shadow.add(...[node.lhs].flat().map(lhsName));
+	},
+	VarDecl: walkDeclSpecs,
+	ConstDecl: walkDeclSpecs,
+	IfStmt: (node, shadow, ctx, out) => {
+		const inner = new Shadow(shadow);
+		for (const c of [node.init, node.cond, node.body, node.elseBody])
+			walkRefs(c, inner, ctx, out);
+	},
+	ForStmt: (node, shadow, ctx, out) => {
+		const inner = new Shadow(shadow);
+		for (const c of [node.init, node.cond, node.post, node.body])
+			walkRefs(c, inner, ctx, out);
+	},
+	SwitchStmt: walkSwitch,
+	TypeSwitchStmt: walkSwitch,
+};
+
+function walkFunc(node, shadow, ctx, out) {
+	const inner = new Shadow(shadow);
+	inner.add(...signatureNames(node));
+	walkRefs(node.body, inner, ctx, out);
+}
+
+function walkDeclSpecs(node, shadow, ctx, out) {
+	for (const spec of node.decls ?? []) {
+		walkRefs(spec.value, shadow, ctx, out);
+		shadow.add(...(spec.names ?? []));
+	}
+}
+
+function walkSwitch(node, shadow, ctx, out) {
+	const inner = new Shadow(shadow);
+	walkRefs(node.init, inner, ctx, out);
+	walkRefs(node.tag ?? node.expr, inner, ctx, out);
+	for (const c of node.cases ?? []) {
+		const clause = new Shadow(inner);
+		if (node.assign) clause.add(node.assign);
+		walkRefs(c.list, clause, ctx, out);
+		walkRefs(c.stmts, clause, ctx, out);
+	}
+}
+
 function walkRefs(node, shadow, ctx, out) {
 	if (!node || typeof node !== "object") return;
 	if (Array.isArray(node)) {
@@ -90,10 +144,17 @@ function walkRefs(node, shadow, ctx, out) {
 		return;
 	}
 	if (node.kind === "Ident") {
-		if (ctx.pkgNames.has(node.name) && !shadow.has(node.name))
+		// The blank identifier names nothing, whatever `var _` the package has.
+		if (
+			node.name !== "_" &&
+			ctx.pkgNames.has(node.name) &&
+			!shadow.has(node.name)
+		)
 			out.names.add(node.name);
 		return;
 	}
+	const scoped = SCOPED[node.kind];
+	if (scoped) return scoped(node, shadow, ctx, out);
 	if (node.kind === "SelectorExpr") {
 		const key = methodKeyOf(node.expr?._type, node.field, ctx.funcs);
 		if (key) out.methods.add(key);
@@ -118,11 +179,10 @@ function walkRefs(node, shadow, ctx, out) {
 /**
  * Collects what `root` (an initialiser expression or a function declaration)
  * refers to: package-level names (`names`) and declarations selected as methods
- * (`methods`, keyed `Type.method`).  The single place shadowing is decided:
- * a name declared anywhere inside `root` never counts as the package-level one.
+ * (`methods`, keyed `Type.method`), honouring block-scoped shadowing.
  */
 function collectRefs(root, ctx, out) {
-	walkRefs(root, declaredNames(root), ctx, out);
+	walkRefs(root, new Shadow(), ctx, out);
 }
 
 const emptyRefs = () => ({ names: new Set(), methods: new Set() });
@@ -261,24 +321,52 @@ function orderVars(varEntries, depsOf) {
 	return { vars, cycles: [] };
 }
 
-// Constants depend on other constants only.
+// Constants depend on other constants only; a constant that reaches itself is
+// a cycle (reported once, at the constant where the walk closed it).
 function orderConsts(constEntries) {
 	const constNames = new Set(constEntries.flatMap((e) => e.names));
 	const ctx = { pkgNames: constNames, funcs: new Map() };
 	const owner = new Map();
 	for (const e of constEntries) for (const n of e.names) owner.set(n, e);
 	const consts = [];
-	const state = new Set();
+	const cycles = [];
+	const state = new Map(); // entry -> 1 while on the walk's path, 2 when done
+	const path = [];
 	const visit = (e) => {
-		if (state.has(e)) return;
-		state.add(e);
+		state.set(e, 1);
+		path.push(e);
 		const refs = emptyRefs();
 		for (const v of e.spec.value ?? []) collectRefs(v, ctx, refs);
-		for (const n of refs.names) if (owner.has(n)) visit(owner.get(n));
+		for (const n of refs.names) {
+			const dep = owner.get(n);
+			if (!dep) continue;
+			if (state.get(dep) === 1) {
+				const names = path.slice(path.indexOf(dep)).map((p) => p.names[0]);
+				const chain = names.length === 1 ? names : [...names, names[0]];
+				cycles.push({ spec: dep.spec, message: cycleMessage(dep, chain) });
+			} else if (!state.has(dep)) visit(dep);
+		}
+		path.pop();
+		state.set(e, 2);
 		consts.push(e);
 	};
-	for (const e of constEntries) visit(e);
-	return consts;
+	for (const e of constEntries) if (!state.has(e)) visit(e);
+	return { consts, cycles };
+}
+
+// A literal initialiser (or none: the zero value) reads nothing and has no
+// effect, and gc initialises it statically, so a function that runs during
+// another variable's initialiser sees it set even when it is declared later
+// (an interface method call adds no dependency in the spec).
+const isStaticValue = (v) =>
+	v?.kind === "BasicLit" ||
+	(v?.kind === "UnaryExpr" &&
+		["-", "+"].includes(v.op) &&
+		isStaticValue(v.operand));
+
+function staticInitsFirst(vars) {
+	const isStatic = (e) => (e.spec.value ?? []).every(isStaticValue);
+	return [...vars.filter(isStatic), ...vars.filter((e) => !isStatic(e))];
 }
 
 /**
@@ -290,8 +378,16 @@ function orderConsts(constEntries) {
 export function orderPackageInits(programs) {
 	const decls = collectDecls(programs);
 	const depsOf = buildVarDeps(decls);
-	const { vars, cycles } = orderVars(decls.varEntries, depsOf);
-	return { consts: orderConsts(decls.constEntries), vars, cycles };
+	const ordered = orderVars(decls.varEntries, depsOf);
+	const { cycles } = ordered;
+	const vars =
+		cycles.length === 0 ? staticInitsFirst(ordered.vars) : ordered.vars;
+	const constOrder = orderConsts(decls.constEntries);
+	return {
+		consts: constOrder.consts,
+		vars,
+		cycles: [...constOrder.cycles, ...cycles],
+	};
 }
 
 /**