gofront 1.8.0 → 1.9.1

package/src/lower/json-codecs.js

@@ -14,11 +14,22 @@
 // which switches over every type the program encodes or decodes anywhere.
 
 import { resolveJsonFields } from "../typechecker/resolve.js";
-import { defaultType } from "../typechecker/types.js";
-import { forEachChild } from "./walk.js";
+import { defaultType, LOCAL_TYPE_SUFFIX } from "../typechecker/types.js";
+import {
+	collectProgramTypes,
+	hasSharedRepr,
+	importsFor,
+	isEmptyIface,
+	mentionsTypeParam,
+	results,
+	SHARED_REPR,
+	TypeSpeller,
+	under,
+	walkNodes,
+} from "./gen-types.js";
 
 const JSON_PATH = "encoding/json";
-const SITE_FUNCS = new Set(["Marshal", "MarshalIndent", "Unmarshal", "Valid"]);
+const SITE_FUNCS = new Set(["Marshal", "MarshalIndent", "Unmarshal"]);
 
 const INT_KINDS = new Set(["int", "int8", "int16", "int32", "int64"]);
 const UINT_KINDS = new Set([
@@ -67,18 +78,13 @@ const DYNAMIC_BASICS = [
 const unalias = (n) => ALIAS[n] ?? n;
 const q = (s) => JSON.stringify(s);
 
-function under(t) {
-	return t?.kind === "named" ? under(t.underlying) : t;
-}
-
 function isBasic(t, set) {
 	const u = under(t);
 	return u?.kind === "basic" && set.has(unalias(u.name));
 }
 
 const isRaw = (t) =>
-	t?.kind === "named" &&
-	(t.name === "json.RawMessage" || t.name === "encoding/json.RawMessage");
+	t?.kind === "named" && t.name === "RawMessage$$encoding$json";
 
 const isNumber = (t) =>
 	t?.kind === "named" &&
@@ -95,10 +101,6 @@ function isBytes(t) {
 	);
 }
 
-const isEmptyIface = (t) =>
-	(t?.kind === "basic" && t.name === "any") ||
-	(under(t)?.kind === "interface" && under(t).methods?.size === 0);
-
 const isNilType = (t) =>
 	t?.kind === "nil" || (t?.kind === "basic" && t.name === "nil");
 
@@ -112,14 +114,6 @@ function methodOf(t, name) {
 	return t.methods?.get(name) ?? t.underlying?.methods?.get(name) ?? null;
 }
 
-// A method's results; a multi-value result is one tuple type.
-function results(m) {
-	const r = (m.returns ?? []).filter(
-		(t) => !(t?.kind === "basic" && t.name === "void"),
-	);
-	return r.length === 1 && r[0]?.kind === "tuple" ? r[0].types : r;
-}
-
 // MarshalJSON() ([]byte, error)
 function marshalerOf(t) {
 	if (isRaw(t)) return null;
@@ -128,6 +122,14 @@ function marshalerOf(t) {
 	return m;
 }
 
+// MarshalText() ([]byte, error), used when the type has no MarshalJSON.
+function textMarshalerOf(t) {
+	if (isRaw(t) || marshalerOf(t)) return null;
+	const m = methodOf(t, "MarshalText");
+	if (m?.params?.length !== 0 || results(m).length !== 2) return null;
+	return m;
+}
+
 // UnmarshalJSON([]byte) error
 function unmarshalerOf(t) {
 	if (isRaw(t)) return null;
@@ -140,12 +142,13 @@ function isSimpleKey(s) {
 	return /^[A-Za-z0-9_ .-]*$/.test(s);
 }
 
-export class JsonCodecGen {
+const isNamedOrPointer = (t) =>
+	t.kind === "named" || (t.kind === "pointer" && t.base?.kind === "named");
+
+export class JsonCodecGen extends TypeSpeller {
 	constructor(checker, pkgName, qualifiers, programs = []) {
-		this.programs = programs;
+		super(pkgName, qualifiers, programs);
 		this.checker = checker;
-		this.pkgName = pkgName;
-		this.qualifiers = qualifiers;
 		this.prefix = `gfj_${String(pkgName).replace(/[^A-Za-z0-9_]/g, "_")}_`;
 		this.enc = new Map(); // key -> { name, t, addr }
 		this.dec = new Map();
@@ -175,6 +178,7 @@ export class JsonCodecGen {
 			map: () => `map[${k(t.key)}]${k(t.value)}`,
 			struct: () => this.structKey(t),
 			interface: () => (isEmptyIface(t) ? "any" : `iface:${t.name ?? ""}`),
+			func: () => this.funcString(t, k),
 		};
 		return (byKind[t.kind] ?? (() => `?${t.kind}`))();
 	}
@@ -187,83 +191,20 @@ export class JsonCodecGen {
 		return `struct{${fields.join(";")}}`;
 	}
 
-	// Go source for the type.
-	spell(t) {
-		const sp = (x) => this.spell(x);
-		const byKind = {
-			basic: () => t.name,
-			named: () => this.spellNamed(t),
-			pointer: () => `*${sp(t.base)}`,
-			slice: () => `[]${sp(t.elem)}`,
-			array: () => `[${t.size}]${sp(t.elem)}`,
-			map: () => `map[${sp(t.key)}]${sp(t.value)}`,
-			struct: () => this.spellStruct(t),
-			interface: () => "any",
-			func: () => this.funcString(t, sp),
-		};
-		if (!byKind[t.kind])
-			throw new Error(`json: cannot spell type kind ${t.kind}`);
-		return byKind[t.kind]();
-	}
-
-	resolveImportAlias(modPath) {
-		for (const p of this.programs) {
-			for (const imp of p.imports ?? []) {
-				for (const spec of imp.imports) {
-					if (spec.path === modPath) {
-						return spec.alias ?? spec.path.split("/").pop();
-					}
-				}
-			}
-		}
-		return modPath.split("/").pop();
-	}
-
-	spellNamed(t) {
-		let name = t.name;
-		const at = name.indexOf("$$");
-		if (at >= 0) {
-			const orig = name.slice(0, at);
-			const modPath = name.slice(at + 2).replaceAll("$", "/");
-			const alias = this.resolveImportAlias(modPath);
-			this.qualifiers.add(alias);
-			name = `${alias}.${orig}`;
-		}
-		const base = this.qualified(name);
-		return t.typeArgs?.length
-			? `${base}[${t.typeArgs.map((a) => this.spell(a)).join(", ")}]`
-			: base;
-	}
-
-	spellStruct(t) {
-		const fields = (t._structFields ?? []).map((f) => {
-			const tag = f.tag ? ` \`${f.tag}\`` : "";
-			if (f.embedded) return `${this.spell(f.type)}${tag}`;
-			return `${f.names.join(", ")} ${this.spell(f.type)}${tag}`;
-		});
-		return `struct { ${fields.join("; ")} }`;
-	}
-
-	qualified(name) {
-		const dot = name.indexOf(".");
-		if (dot > 0) this.qualifiers.add(name.slice(0, dot));
-		return name;
-	}
-
 	// reflect's Type.String() of the type, for error messages.
 	refl(t) {
 		switch (t.kind) {
 			case "basic":
 				return REFLECT_NAME[t.name] ?? unalias(t.name);
 			case "named": {
-				let name = t.name;
+				let name = t.name.replace(LOCAL_TYPE_SUFFIX, "");
 				const at = name.indexOf("$$");
 				if (at >= 0) {
 					const orig = name.slice(0, at);
 					const modPath = name.slice(at + 2).replaceAll("$", "/");
 					name = `${modPath}.${orig}`;
 				} else if (!name.includes(".")) {
-					name = `${this.pkgName}.${name}`;
+					name = `${this.declaringPackage(t)}.${name}`;
 				}
 				return t.typeArgs?.length
 					? `${name}[${t.typeArgs.map((a) => this.refl(a)).join(",")}]`
@@ -278,7 +219,9 @@ export class JsonCodecGen {
 			case "map":
 				return `map[${this.refl(t.key)}]${this.refl(t.value)}`;
 			case "interface":
-				return "interface {}";
+				return t.name === "error" ? "error" : "interface {}";
+			case "namespace":
+				return t.name;
 			case "func":
 				return this.funcString(t, (x) => this.refl(x));
 			default:
@@ -286,17 +229,6 @@ export class JsonCodecGen {
 		}
 	}
 
-	funcString(t, name) {
-		const rs = results(t);
-		const res =
-			rs.length === 0
-				? ""
-				: rs.length === 1
-					? ` ${name(rs[0])}`
-					: ` (${rs.map(name).join(", ")})`;
-		return `func(${t.params.map(name).join(", ")})${res}`;
-	}
-
 	// A struct's own name in decode errors.
 	shortName(t) {
 		return t?.kind === "named" ? t.name.split(".").pop() : "";
@@ -309,7 +241,7 @@ export class JsonCodecGen {
 	needsAddr(t, seen = new Set()) {
 		if (!t || seen.has(t)) return false;
 		seen.add(t);
-		const m = marshalerOf(t);
+		const m = marshalerOf(t) ?? textMarshalerOf(t);
 		if (m) return Boolean(m._ptrRecv);
 		const u = under(t);
 		if (u?.kind === "struct")
@@ -343,10 +275,56 @@ export class JsonCodecGen {
 
 	// Statements that encode the Go expression `x` of type `t`.
 	encValue(t, x, addr) {
+		if (holdsInterop(t)) return this.encInterop(t, x);
 		return [`${this.encFn(t, addr)}(e, ${x})`];
 	}
 
-	marshalCall(x, t) {
+	// A JS-interop value has no Go source to spell, so it is encoded where it
+	// sits: nil is `null` (an empty slice, map or array is `[]` or `{}`), and
+	// anything else fails with the type's name.
+	encInterop(t, x) {
+		const u = under(t);
+		const fail = (name) => `\te.FailType(${q(name)})`;
+		if (u.kind === "namespace")
+			return [`if ${x} == nil {`, "\te.Null()", "} else {", fail(u.name), "}"];
+		if (u.kind === "pointer")
+			return [
+				`if ${x} == nil {`,
+				"\te.Null()",
+				"} else {",
+				fail(this.refl(t)),
+				"}",
+			];
+		const [empty, elem] =
+			u.kind === "map"
+				? ["{}", holdsInterop(u.key) ? u.key : u.value]
+				: ["[]", u.elem];
+		if (u.kind === "array")
+			return [
+				`if ${u.size} == 0 {`,
+				`\te.Lit(${q(empty)})`,
+				"} else {",
+				fail(this.refl(elem)),
+				"}",
+			];
+		return [
+			`if ${x} == nil {`,
+			"\te.Null()",
+			`} else if len(${x}) == 0 {`,
+			`\te.Lit(${q(empty)})`,
+			"} else {",
+			fail(this.refl(elem)),
+			"}",
+		];
+	}
+
+	// `mt` is the type that declares the method (the pointee for a pointer).
+	marshalCall(x, t, mt = t) {
+		if (!marshalerOf(mt) && textMarshalerOf(mt))
+			return [
+				`out, err := ${x}.MarshalText()`,
+				`e.TextMarshaled(out, err, ${q(this.refl(t))})`,
+			];
 		return [
 			`out, err := ${x}.MarshalJSON()`,
 			`e.Marshaled(out, err, ${q(this.refl(t))})`,
@@ -357,7 +335,7 @@ export class JsonCodecGen {
 	encSpecial(t, addr) {
 		if (isRaw(t)) return ["e.Raw([]byte(v))"];
 		if (isNumber(t)) return ["e.Number(string(v))"];
-		const m = marshalerOf(t);
+		const m = marshalerOf(t) ?? textMarshalerOf(t);
 		if (m && (!m._ptrRecv || addr)) return this.marshalCall("v", t);
 		if (isBytes(t)) return ["e.Bytes([]byte(v))"];
 		if (isInterface(t)) {
@@ -385,7 +363,8 @@ export class JsonCodecGen {
 
 	encPointer(t, u) {
 		const lines = ["if v == nil {", "\te.Null()", "\treturn", "}"];
-		if (marshalerOf(u.base)) lines.push(...this.marshalCall("v", t));
+		if (marshalerOf(u.base) || textMarshalerOf(u.base))
+			lines.push(...this.marshalCall("v", t, u.base));
 		else lines.push(...this.encValue(u.base, "*v", true));
 		return lines;
 	}
@@ -476,6 +455,7 @@ export class JsonCodecGen {
 		if (u.kind === "slice" || u.kind === "map") return `len(${x}) == 0`;
 		if (u.kind === "array") return u.size === 0 ? "true" : "false";
 		if (u.kind === "struct") return "false";
+		if (u.kind === "namespace") return `${x} == nil`;
 		const n = unalias(u.name);
 		if (n === "bool") return `!${x}`;
 		if (n === "string") return `${x} == ""`;
@@ -558,24 +538,50 @@ export class JsonCodecGen {
 	genEncAny() {
 		const cases = [];
 		const seen = new Set();
+		const f32 = this.enc.get("float32")?.name;
 		for (const [key, e] of this.enc) {
 			if (e.addr || seen.has(key)) continue;
 			seen.add(key);
 			if (isInterface(e.t)) continue;
-			cases.push(`\tcase ${this.spell(e.t)}:\n\t\t${e.name}(e, x)`);
+			// A package that only lends its encoder knows its named types.
+			if (this.registerOnly && !isNamedOrPointer(e.t)) continue;
+			// Where one run-time shape serves both float sizes, a float64 that a
+			// float32 holds exactly encodes as the float32 it most likely is.
+			const body =
+				f32 && e.t.kind === "basic" && e.t.name === "float64"
+					? `\t\tif jsonrt.LooksFloat32(x) {\n\t\t\t${f32}(e, float32(x))\n\t\t} else {\n\t\t\t${e.name}(e, x)\n\t\t}`
+					: `\t\t${e.name}(e, x)`;
+			cases.push({
+				t: e.t,
+				src: `\tcase ${this.spell(e.t)}:\n${body}\n\t\treturn true`,
+			});
 		}
+		// JS numbers do not tell an int from a float64 or float32: whole numbers
+		// take the int cases, then float64, then float32.
+		const rank = ({ t }) =>
+			t.name === "float64" ? 1 : t.name === "float32" ? 2 : 0;
+		cases.sort((a, b) => rank(a) - rank(b));
+		const known = `${this.prefix}encKnown`;
 		this.out.push(
 			[
-				`func ${this.prefix}encAny(e *jsonrt.Enc, v any) {`,
+				`func ${known}(e *jsonrt.Enc, v any) bool {`,
 				"\tif v == nil {",
 				"\t\te.Null()",
-				"\t\treturn",
+				"\t\treturn true",
 				"\t}",
 				"\tswitch x := v.(type) {",
-				...cases,
+				...cases.map((c) => c.src),
 				"\tdefault:",
 				"\t\t_ = x",
-				'\t\te.FailType("unsupported dynamic type")',
+				"\t\treturn false",
+				"\t}",
+				"}",
+				// Every package with codecs lends its dynamic encoder to the others,
+				// so a value of a type another package declares still encodes.
+				`var _ = jsonrt.RegisterEncoder(${known})`,
+				`func ${this.prefix}encAny(e *jsonrt.Enc, v any) {`,
+				`\tif !${known}(e, v) {`,
+				"\t\te.EncodeDynamic(v)",
 				"\t}",
 				"}",
 			].join("\n"),
@@ -632,7 +638,7 @@ export class JsonCodecGen {
 		if (u.kind === "basic" && !isEmptyIface(t))
 			return this.decScalar(t, u, typ);
 		const byKind = {
-			pointer: () => this.decPointer(u, typ),
+			pointer: () => this.decPointer(u),
 			slice: () => this.decSlice(u, t, typ),
 			array: () => this.decArray(u, typ),
 			map: () => this.decMap(u, t, typ),
@@ -707,7 +713,7 @@ export class JsonCodecGen {
 		];
 	}
 
-	decPointer(u, typ) {
+	decPointer(u) {
 		const base = u.base;
 		const lines = [
 			"if d.Null() {",
@@ -717,9 +723,7 @@ export class JsonCodecGen {
 			`\tcur = new(${this.spell(base)})`,
 			"}",
 		];
-		if (under(base)?.kind === "pointer") {
-			lines.push(`d.Mismatch(${typ})`);
-		} else if (this.decInPlace(base)) {
+		if (this.decInPlace(base)) {
 			lines.push(`${this.decFn(base)}(d, cur)`);
 		} else {
 			lines.push(`*cur = ${this.decFn(base)}(d, *cur)`);
@@ -818,6 +822,9 @@ export class JsonCodecGen {
 
 	decStruct(u, t, typ) {
 		const fields = resolveJsonFields(u);
+		for (const f of fields)
+			if (holdsInterop(f.type))
+				throw new Error(`json: cannot unmarshal into ${interopName(f.type)}`);
 		const sname = this.shortName(t);
 		const lines = [
 			"if d.Null() {",
@@ -1015,19 +1022,11 @@ export class JsonCodecGen {
 		return name;
 	}
 
-	entryValid() {
-		const name = `${this.prefix}valid${this.entries.length}`;
-		this.entries.push(
-			`func ${name}(data []byte) bool {\n\treturn jsonrt.Valid(data)\n}`,
-		);
-		return name;
-	}
-
 	entryEncode(argType) {
-		this.qualified("json.Encoder");
+		const json = this.qualifierFor(JSON_PATH);
 		const name = `${this.prefix}encode${this.entries.length}`;
 		const lines = [
-			`func ${name}(enc *json.Encoder, v any) error {`,
+			`func ${name}(enc *${json}.Encoder, v any) error {`,
 			"\tif enc.Err() != nil {",
 			"\t\treturn enc.Err()",
 			"\t}",
@@ -1056,10 +1055,10 @@ export class JsonCodecGen {
 	}
 
 	entryDecode(argType) {
-		this.qualified("json.Decoder");
+		const json = this.qualifierFor(JSON_PATH);
 		const name = `${this.prefix}decode${this.entries.length}`;
 		const lines = [
-			`func ${name}(dec *json.Decoder, v any) error {`,
+			`func ${name}(dec *${json}.Decoder, v any) error {`,
 			"\tdata, err := dec.ScanNext()",
 			"\tif err != nil {",
 			"\t\treturn err",
@@ -1103,7 +1102,13 @@ export class JsonCodecGen {
 			(t) =>
 				t.kind === "pointer" && (isEmptyIface(t.base) || !isInterface(t.base)),
 		);
-		for (const pt of [...this.decTargets, ...pointers]) {
+		// A pointer to a type parameter's variable names no type in JavaScript:
+		// it decodes by its pointee's shape (see __isty), so these always exist.
+		const shapes = ["any", "float64", "string", "bool", "int64"].map((n) => ({
+			kind: "pointer",
+			base: { kind: "basic", name: n },
+		}));
+		for (const pt of [...this.decTargets, ...pointers, ...shapes]) {
 			const k = this.key(pt);
 			if (seen.has(k)) continue;
 			seen.add(k);
@@ -1133,21 +1138,22 @@ export class JsonCodecGen {
 
 	// Registers what the dynamic encoder handles, until nothing new appears.
 	addDynamicTypes() {
-		for (const n of DYNAMIC_BASICS) this.encFn({ kind: "basic", name: n });
 		const anyT = { kind: "basic", name: "any" };
-		this.encFn({ kind: "slice", elem: anyT });
-		this.encFn({
-			kind: "map",
-			key: { kind: "basic", name: "string" },
-			value: anyT,
-		});
+		if (!this.registerOnly) {
+			for (const n of DYNAMIC_BASICS) this.encFn({ kind: "basic", name: n });
+			this.encFn({ kind: "slice", elem: anyT });
+			this.encFn({
+				kind: "map",
+				key: { kind: "basic", name: "string" },
+				value: anyT,
+			});
+		}
 		for (const t of this.programTypes()) {
 			this.encFn(t, false);
 		}
-		for (const [name, t] of this.checker.types) {
-			if (t?.kind !== "named" || name.includes(".") || name.includes("$$"))
-				continue;
-			if (t.name !== name || t.typeArgs?.length || t._genericOf) continue;
+		for (const { type: t, via } of this.collectedTypes()) {
+			if (via !== "boxed" || !t || mentionsTypeParam(t)) continue;
+			if (!this.spellable(t)) continue;
 			const u = under(t);
 			if (!u || u.kind === "interface" || u.kind === "func") continue;
 			this.encFn(t, false);
@@ -1155,41 +1161,61 @@ export class JsonCodecGen {
 		}
 	}
 
-	// True when the type can be written as Go source in the generated file.
-	spellable(t, depth = 0) {
-		if (!t || depth > 8) return false;
-		const ok = (x) => this.spellable(x, depth + 1);
-		const byKind = {
-			basic: () => t.name !== "void" && t.name !== "nil",
-			named: () =>
-				!t.name.includes("$$") &&
-				!t.name.includes("[") &&
-				(t.typeArgs ?? []).every(ok),
-			pointer: () => ok(t.base),
-			slice: () => ok(t.elem),
-			array: () => ok(t.elem),
-			map: () => ok(t.key) && ok(t.value),
-			interface: () => true,
-			struct: () => (t._structFields ?? []).every((f) => ok(f.type)),
-			func: () => t.params.every(ok) && results(t).every(ok),
-		};
-		return byKind[t.kind]?.() ?? false;
+	// A struct holding a JS-interop value (a `.d.ts` interface) cannot be
+	// written as a dynamic case, so it is not spellable either.
+	spellableNamed(t, ok) {
+		if (isJsonValue(t)) return true;
+		return (
+			!t.name.includes("$$") &&
+			!t.name.includes("[") &&
+			(t.typeArgs ?? []).every(ok) &&
+			!reachesInterop(t)
+		);
+	}
+
+	addTypeArg(found, a) {
+		const t = defaultType(a);
+		if (!t || mentionsTypeParam(t) || !this.spellable(t) || isInterface(t))
+			return;
+		// An array or map of small integers would shadow its look-alikes in the
+		// type switch (see SHARED_REPR).
+		const ambiguous = !isCompositeType(t) && hasSharedRepr(t);
+		if (holdsFunc(t) || ambiguous) return;
+		found.set(this.key(t), t);
+		const p = { kind: "pointer", base: t };
+		found.set(this.key(p), p);
+	}
+
+	collectedTypes() {
+		this.collected ??= collectProgramTypes(this.programs, this.checker);
+		return this.collected;
 	}
 
 	// Types the program builds with composite literals, `&T{}`, make and new:
 	// candidates for a value stored in an interface (an `any` map value, say).
 	programTypes() {
 		const found = new Map();
-		for (const p of this.programs) {
-			walkNodes(p.decls, (node) => {
-				if (!node._type) return;
-				const t = defaultType(node._type);
-				// Slices, arrays and maps reach an interface from any expression
-				// (a function result, a variable), not only from a literal
-				if (!buildsValue(node) && !isCompositeType(t)) return;
-				if (this.spellable(t) && under(t)?.kind !== "interface")
-					found.set(this.key(t), t);
-			});
+		for (const { type: t, node, via } of this.collectedTypes()) {
+			// A generic call's type arguments are what its body encodes and
+			// decodes through `T` and `&v`.
+			if (via === "typeArg") this.addTypeArg(found, t);
+			if (via !== "expr" || !t) continue;
+			// A func literal in an interface reports its own type.
+			if (node.kind === "FuncLit" && this.spellable(t)) {
+				found.set(this.key(t), t);
+				continue;
+			}
+			// Slices, arrays and maps reach an interface from any expression
+			// (a function result, a variable), not only from a literal
+			if (
+				!buildsValue(node) &&
+				!isCompositeType(t) &&
+				!isFuncComposite(t) &&
+				!isJsonValue(t)
+			)
+				continue;
+			if (this.spellable(t) && under(t)?.kind !== "interface")
+				found.set(this.key(t), t);
 		}
 		return [...found.values()];
 	}
@@ -1212,68 +1238,85 @@ export class JsonCodecGen {
 		}
 	}
 
-	source(pkgName, imports) {
-		const importLines = imports.map((p) => `\t${q(p)}`).join("\n");
-		return [
-			`package ${pkgName}`,
-			"",
-			`import (\n\t"internal/jsonrt"\n${importLines}\n)`,
-			"",
-			...this.entries,
-			...this.out,
-			"",
-		].join("\n\n");
+	// The generated declarations (the spine adds the header and imports).
+	body() {
+		return [...this.entries, ...this.out].join("\n\n");
 	}
 }
 
-// Calls every `fn(node)` for the AST nodes under `root`.
-function walkNodes(root, fn) {
-	if (!root || typeof root !== "object") return;
-	if (Array.isArray(root)) {
-		for (const n of root) walkNodes(n, fn);
-		return;
+// A slice of booleans or small integers carries a tag of its Go type inside an
+// interface, so it never shadows another slice type in the type switch.
+const isTaggedSlice = (t) =>
+	under(t)?.kind === "slice" && isBasic(under(t).elem, SHARED_REPR);
+
+// json.RawMessage and json.Number values can reach an interface from any
+// expression (a conversion, a field read).
+// True when `t` is, or holds through pointers, elements and struct fields, a
+// JS-interop type (a `.d.ts` interface) that has no Go source to spell.
+export function reachesInterop(t, seen = new Set(), viaStruct = true) {
+	if (!t || seen.has(t)) return false;
+	seen.add(t);
+	const u = under(t) ?? t;
+	switch (u.kind) {
+		case "namespace":
+			return true;
+		case "pointer":
+			return reachesInterop(u.base, seen, viaStruct);
+		case "slice":
+		case "array":
+			return reachesInterop(u.elem, seen, viaStruct);
+		case "map":
+			return (
+				reachesInterop(u.key, seen, viaStruct) ||
+				reachesInterop(u.value, seen, viaStruct)
+			);
+		case "struct":
+			return (
+				viaStruct &&
+				(u._structFields ?? []).some((f) => reachesInterop(f.type, seen))
+			);
+		default:
+			return false;
 	}
-	fn(root);
-	forEachChild(root, (c) => walkNodes(c, fn));
 }
 
-// Slices and maps of these share one WebAssembly representation (and so one
-// type-switch case), so only literals may register them: a `[]byte` conversion
-// must not shadow a `[]int32` that is stored in an interface.
-const SHARED_REPR = new Set([
-	"bool",
-	"int8",
-	"int16",
-	"int32",
-	"uint8",
-	"uint16",
-	"uint32",
-	"byte",
-	"rune",
-]);
+// True when a value of type `t` is, or holds through pointers and elements
+// (not through a named struct, which has its own codec), a JS-interop value.
+const holdsInterop = (t) => reachesInterop(t, new Set(), false);
+
+// The name of the JS-interop type that `t` is or wraps.
+function interopName(t) {
+	const u = under(t);
+	if (u.kind === "namespace") return u.name;
+	if (u.kind === "map")
+		return interopName(holdsInterop(u.key) ? u.key : u.value);
+	return interopName(u.base ?? u.elem);
+}
 
-const isCompositeType = (t) => {
+const isJsonValue = (t) => isRaw(t) || isNumber(t);
+
+export const isCompositeType = (t) => {
 	const k = under(t)?.kind;
 	return (
 		(k === "slice" || k === "array" || k === "map") &&
 		!holdsFunc(t) &&
-		!hasSharedRepr(t)
+		(isTaggedSlice(t) || !hasSharedRepr(t))
 	);
 };
 
-function hasSharedRepr(t, depth = 0) {
-	if (!t || depth > 8) return false;
-	const u = under(t);
-	if (u?.kind === "basic") return SHARED_REPR.has(u.name);
-	if (u?.kind === "slice" || u?.kind === "array")
-		return hasSharedRepr(u.elem, depth + 1);
-	if (u?.kind === "map")
-		return hasSharedRepr(u.key, depth + 1) || hasSharedRepr(u.value, depth + 1);
-	return false;
-}
+// A slice, array or map holding funcs: it never encodes, but a nil one in an
+// interface still does, as `null`, and a non-nil one names the func.
+export const isFuncComposite = (t) => {
+	const k = under(t)?.kind;
+	return (
+		(k === "slice" || k === "array" || k === "map") &&
+		holdsFunc(t) &&
+		!hasSharedRepr(t)
+	);
+};
 
 // Func values are not JSON-encodable, and `case []func():` does not parse.
-function holdsFunc(t, depth = 0) {
+export function holdsFunc(t, depth = 0) {
 	if (!t || depth > 8) return false;
 	const u = under(t);
 	if (u?.kind === "func") return true;
@@ -1305,12 +1348,17 @@ function jsonAliases(program) {
 	return aliases;
 }
 
+// `json.Marshal`-style selector on the imported package (not a local that
+// shadows its name).
+const isJsonRef = (node, aliases) =>
+	node.kind === "SelectorExpr" &&
+	node.expr?.kind === "Ident" &&
+	node.expr._type?.kind === "namespace" &&
+	aliases.has(node.expr.name) &&
+	SITE_FUNCS.has(node.field);
+
 const isJsonCall = (node, aliases) =>
-	node.kind === "CallExpr" &&
-	node.func?.kind === "SelectorExpr" &&
-	node.func.expr?.kind === "Ident" &&
-	aliases.has(node.func.expr.name) &&
-	SITE_FUNCS.has(node.func.field);
+	node.kind === "CallExpr" && isJsonRef(node.func, aliases);
 
 function isStreamCall(node) {
 	if (node.kind !== "CallExpr" || node.func?.kind !== "SelectorExpr")
@@ -1330,21 +1378,36 @@ function isStreamCall(node) {
 	return null;
 }
 
-// Finds `json.Marshal/Unmarshal/Valid` call sites in the checked programs.
+// Finds `json.Marshal/MarshalIndent/Unmarshal` call sites in the checked
+// programs, and a diagnostic for each use of them that is not a call.
 function findSites(programs) {
 	const sites = [];
+	const diagnostics = [];
 	for (const p of programs) {
 		const aliases = jsonAliases(p);
+		const callees = new Set();
+		const refs = [];
 		walkNodes(p.decls, (node) => {
 			if (isJsonCall(node, aliases)) {
 				sites.push({ call: node, fn: node.func.field, program: p });
+				callees.add(node.func);
+			} else if (isJsonRef(node, aliases)) {
+				refs.push(node);
 			} else {
 				const streamFn = isStreamCall(node);
 				if (streamFn) sites.push({ call: node, fn: streamFn, program: p });
 			}
 		});
-	}
-	return sites;
+		for (const node of refs)
+			if (!callees.has(node))
+				diagnostics.push({
+					program: p,
+					node: node.expr,
+					message: `json.${node.field} cannot be used as a value`,
+					hint: `call json.${node.field} directly`,
+				});
+	}
+	return { sites, diagnostics };
 }
 
 function selectCodecEntry(gen, fn, argType) {
@@ -1353,22 +1416,52 @@ function selectCodecEntry(gen, fn, argType) {
 	if (fn === "Unmarshal") return gen.entryUnmarshal(argType(1));
 	if (fn === "Encode") return gen.entryEncode(argType(0));
 	if (fn === "Decode") return gen.entryDecode(argType(0));
-	return gen.entryValid();
+}
+
+// Records that the build uses `json` when this package calls it; returns
+// whether the package has call sites (or misuses) of its own. One without
+// them still lends its types to the dynamic encoder once `json` is in use.
+// The flag is tracked per target so WASM-only use does not pull `json` into
+// JS output (and vice versa).
+function jsonTargets(checker) {
+	return checker.target === "both" || !checker.target
+		? ["js", "wasm"]
+		: [checker.target];
+}
+
+function noteJsonUse(options, sites, diagnostics, checker) {
+	if (sites.length > 0 && options.jsonBuild)
+		for (const t of jsonTargets(checker)) options.jsonBuild[t] = true;
+	return sites.length + diagnostics.length > 0;
 }
 
 // Generates the codec file for a package's `json` call sites.  Returns null
-// when it has none; otherwise { source, imports } and marks each call's
-// SelectorExpr with `_jsonGen`, the entry point the WASM link calls instead.
-export function generateJsonCodecs(programs, checker, pkgName) {
-	const sites = findSites(programs);
-	if (sites.length === 0) return null;
-	const qualifiers = new Set();
+// when it has none; otherwise { body, imports, diagnostics } and marks each call's
+// SelectorExpr with `_genEntry`, the entry point the WASM link calls instead.
+export function generateJsonCodecs(programs, checker, pkgName, options = {}) {
+	const { sites, diagnostics } = findSites(programs);
+	const registerOnly = !noteJsonUse(options, sites, diagnostics, checker);
+	if (registerOnly && !jsonTargets(checker).some((t) => options.jsonBuild?.[t]))
+		return null;
+	const qualifiers = new Map();
 	const gen = new JsonCodecGen(checker, pkgName, qualifiers, programs);
+	if (registerOnly) {
+		gen.registerOnly = true;
+		gen.flagDynamic();
+	}
 	const pending = [];
-	const diagnostics = [];
 	for (const { call, fn, program } of sites) {
-		const argType = (i) => defaultType(call.args[i]?._type);
-		if (fn === "Unmarshal" && argType(1)?.base?.kind === "pointer")
+		// A site inside a generic function is shared by every instance, so a type
+		// that mentions a type parameter takes the dynamic entry.
+		const argType = (i) => {
+			const t = defaultType(call.args[i]?._type);
+			return mentionsTypeParam(t) ? null : t;
+		};
+		if (
+			fn === "Unmarshal" &&
+			checker.target !== "js" &&
+			argType(1)?.base?.kind === "pointer"
+		)
 			diagnostics.push({
 				program,
 				node: call.func.expr,
@@ -1380,19 +1473,15 @@ export function generateJsonCodecs(programs, checker, pkgName) {
 		pending.push([call.func, entry, fn === "Encode" || fn === "Decode"]);
 	}
 	gen.finish();
+	if (registerOnly && !gen.out.some((o) => o.includes("RegisterEncoder")))
+		return null;
 	for (const [sel, entry, isStream] of pending) {
-		sel._jsonGen = entry;
+		sel._genEntry = entry;
 		if (isStream) sel._jsonStream = true;
 	}
-	const importPaths = new Map();
-	for (const p of programs)
-		for (const imp of p.imports ?? [])
-			for (const spec of imp.imports) {
-				const last = spec.path.split("/").pop();
-				importPaths.set(spec.alias ?? last, spec.path);
-			}
-	const imports = [...qualifiers]
-		.map((qn) => importPaths.get(qn))
-		.filter(Boolean);
-	return { source: gen.source(pkgName, imports), diagnostics };
+	return {
+		body: gen.body(),
+		imports: ["internal/jsonrt", ...importsFor(qualifiers)],
+		diagnostics,
+	};
 }