@amxts/core 0.1.0 → 0.2.1

package/scripts/shared-modules.ts

@@ -41,13 +41,23 @@
 // The types come from compiling the module on its own with asc: its exported
 // functions are compiled as exports, so every result type the compiler
 // inferred is known, and so is every field. That compile is done before the
-// plugin's (asc is not reentrant) and remembered while the file is unchanged.
-import { join, relative, resolve } from 'node:path';
+// plugin's (asc is not reentrant). What a plugin's compile needs of it - the
+// proxy and the dispatcher, its surface - is remembered while the files it
+// read are unchanged: in memory, and on disk in the project's
+// node_modules/.cache/amxts/analysis, so another process - a build started
+// again, a parallel compile - takes it from there. A module package from npm
+// carries its surface beside its prebuilt .aot (scripts/prebuilt.ts), taken
+// while the project would make the same one.
+import type { Project, Sources } from './project';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 // @ts-ignore - shipped as JavaScript, with types beside it we do not need here
 import * as as from '../runtime/deps/assemblyscript/dist/assemblyscript.js';
 import { ascMain } from './asc';
+import { codeIdentity, diskCache } from './compile-cache';
 import { playerFieldsBuild } from './player-fields';
-import { ascPath, sourcesFor } from './project';
+import { prebuiltSurface } from './prebuilt';
+import { ascPath, currentProjectDir, sourcesFor } from './project';
 import { existsSync, statSync } from './tracked-fs';
 
 /** Where the owner's dispatcher is parsed: beside the plugin, like its natives' wrappers. */
@@ -141,28 +151,81 @@ export interface ModuleAnalysis {
 	hash: number;
 }
 
-const cache = new Map<string, { stamp: string; analysis: Promise<ModuleAnalysis> }>();
+/** What a plugin's compile needs of a module: the proxy, the owner's dispatcher, and whether functions cross. */
+export interface ModuleSurface {
+	proxy: string;
+	serve: string;
+	callbacks: boolean;
+}
 
-/** The module's exports, as the compiler sees them; remembered while the file is unchanged. */
-export function analyzeModule(root: string, name: string): Promise<ModuleAnalysis> {
-	const path = join(root, 'modules', `${name}.ts`);
-	// The module and everything it imports: a field added to a facade class changes what crosses.
-	const sources = sourcesFor(root);
-	const stamp = [...sources.reach(path)].map((place) => {
+export function surfaceOf(analysis: ModuleAnalysis): ModuleSurface {
+	return { proxy: proxySource(analysis), serve: serveSource(analysis), callbacks: analysis.fns.length > 0 };
+}
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** The surfaces kept on disk, per project folder; none where the project has no node_modules (a server). */
+const kept = new Map<string, ReturnType<typeof diskCache>>();
+
+/** The current project's surfaces on disk. */
+export function keptSurfaces() {
+	const dir = currentProjectDir();
+	const modules = join(dir, 'node_modules');
+	if (!kept.has(dir)) kept.set(dir, diskCache(existsSync(modules) ? join(modules, '.cache', 'amxts', 'analysis') : null, () => codeIdentity([join(HERE, 'shared-modules.ts')])));
+	return kept.get(dir)!;
+}
+
+/**
+ * The places a module reaches, as files on disk with their times: it is the
+ * same module while they are. A file that takes another's place changes it.
+ */
+function stampOf(sources: Sources, places: string[]): string {
+	return places.map((place) => {
 		const file = sources.real(place);
 		if (!file) return place;
 		const info = statSync(file);
 		return `${file}:${info.mtimeMs}:${info.size}`;
 	}).join('|');
-	const known = cache.get(path);
-	if (known && known.stamp === stamp) return known.analysis;
-	const analysis = analyze(root, name);
-	cache.set(path, { stamp, analysis });
-	analysis.catch(() => cache.delete(path));
-	return analysis;
 }
 
-async function analyze(root: string, name: string): Promise<ModuleAnalysis> {
+/** The surfaces made in this process, by project - its config gives the modules their options - and module file. */
+const surfaces = new WeakMap<Project, Map<string, { places: string[]; stamp: string; surface: Promise<ModuleSurface> }>>();
+
+/**
+ * The module's surface: the one its package came with, else one kept on
+ * disk, else made from its analysis. Remembered while the files it reaches -
+ * the module and everything it imports: a field added to a facade class
+ * changes what crosses - are unchanged.
+ */
+export function moduleSurface(root: string, name: string): Promise<ModuleSurface> {
+	const path = join(root, 'modules', `${name}.ts`);
+	const sources = sourcesFor(root);
+	if (!surfaces.has(sources.project)) surfaces.set(sources.project, new Map());
+	const made = surfaces.get(sources.project)!;
+	const known = made.get(path);
+	if (known && known.stamp === stampOf(sources, known.places)) return known.surface;
+
+	const places = [...sources.reach(path)];
+	const pkg = sources.project.modules.find(each => each.short === name && each.module === sources.real(path));
+	const shipped = pkg ? prebuiltSurface(pkg, sources) : null;
+	const surface = shipped && 'surface' in shipped
+		? Promise.resolve(shipped.surface)
+		: keptSurfaces().cached(['surface', resolve(root), name], async () => surfaceOf(await analyzeModule(root, name)));
+	made.set(path, { places, stamp: stampOf(sources, places), surface });
+	surface.catch(() => made.delete(path));
+	return surface;
+}
+
+/** The module's exports, as the compiler sees them. */
+export async function analyzeModule(root: string, name: string): Promise<ModuleAnalysis> {
+	return describe(await compileAlone(root, name), name);
+}
+
+/**
+ * Compiles `~/modules/<name>` on its own, its exported functions as exports:
+ * the compiler's program, or an error with what asc said.
+ */
+export async function compileAlone(root: string, name: string): Promise<any> {
 	let program: any = null;
 	const playerFields = playerFieldsBuild();
 	const sources = sourcesFor(root);
@@ -179,8 +242,7 @@ async function analyze(root: string, name: string): Promise<ModuleAnalysis> {
 		transforms: [playerFields.transform, class { afterCompile() { program = (this as any).program; } }],
 	});
 	if (error || !program) throw new Error(`~/modules/${name} does not compile:\n${stderr.toString() || String(error?.message ?? error)}`);
-
-	return describe(program, name);
+	return program;
 }
 
 function describe(program: any, name: string): ModuleAnalysis {
@@ -878,10 +940,10 @@ export async function sharedModulesBuild(root: string, entry: string) {
 	for (const path of sourcesFor(root).reach(join(root, entry))) {
 		const name = moduleName(root, path);
 		if (!name || !hasOwner(root, name)) continue;
-		const analysis = await analyzeModule(root, name);
-		if (analysis.fns.length) callbacks = true;
-		if (name === owned) serve = serveSource(analysis);
-		else proxies.set(resolve(path), proxySource(analysis));
+		const surface = await moduleSurface(root, name);
+		if (surface.callbacks) callbacks = true;
+		if (name === owned) serve = surface.serve;
+		else proxies.set(resolve(path), surface.proxy);
 	}
 
 	return {

package/scripts/source-map.ts

@@ -0,0 +1,242 @@
+// Where a plugin's machine code came from in its TypeScript, carried inside
+// the plugin: what the module reads when a call fails, or when a plugin asks
+// for `error.stack`, to print the stack as functions, files and lines
+// (runtime/src/module.cpp, PrintStack).
+//
+// asc writes a source map of the wasm it emits: for a wasm, a mapping's
+// column is a byte offset into the binary, and WAMR's frames carry the same
+// offset - the opcode a frame stopped at (wamrc --enable-dump-call-stack).
+// The table goes into the wasm as a custom section, appended after the code
+// so no offset moves, and wamrc copies it into the .aot
+// (--emit-custom-sections): a plugin carries its map wherever its .aot goes.
+//
+// The section's text, line by line:
+//
+//   amxts-map 1
+//   root <folder>          the project's folder, absolute, for a dev build:
+//                          where the module looks for the files first
+//   files <count>          then one file a line, as the project names it
+//   functions <first> <count>   the wasm index of the first defined function,
+//                          then one name a line, by index; an empty name is
+//                          the hood's own frame, which the stack leaves out
+//   mappings               then the source map's own mappings, one line
+//
+// The mappings stay as the source map writes them - base64 VLQ, each segment
+// a byte offset and, when the code there has a place, its file, line and
+// column - which is as small as the table gets without losing a column.
+
+/** The custom section's name. */
+export const MAP_SECTION = 'amxts.map';
+
+/** A place in the TypeScript: 1-based line and column. */
+export interface Place {
+	file: string;
+	line: number;
+	column: number;
+}
+
+/**
+ * One mapping: from its byte offset on, the code is at `place` - null in a
+ * file the map leaves out, undefined where the source map gave no place.
+ */
+interface Mapping {
+	offset: number;
+	place?: Place | null;
+}
+
+/** A plugin's map, read back. */
+export interface PluginMap {
+	/** The project's folder for a dev build, else empty: the files are relative to it. */
+	root: string;
+	files: string[];
+	first: number;
+	functions: string[];
+	mappings: string;
+}
+
+const BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/** Source map mappings, decoded - a wasm's are all on its one line - with no place in a file named null. */
+function decode(mappings: string, files: (string | null)[]): Mapping[] {
+	const out: Mapping[] = [];
+	const state = [0, 0, 0, 0];
+	for (const segment of mappings.split(/[,;]/)) {
+		if (!segment) continue;
+		const fields: number[] = [];
+		let value = 0;
+		let shift = 0;
+		for (const char of segment) {
+			const digit = BASE64.indexOf(char);
+			value += (digit & 31) << shift;
+			if (digit & 32) {
+				shift += 5;
+				continue;
+			}
+			fields.push(value & 1 ? -(value >>> 1) : value >>> 1);
+			value = 0;
+			shift = 0;
+		}
+		fields.forEach((field, i) => (state[i] += field));
+		const file = fields.length >= 4 ? files[state[1]] : undefined;
+		out.push({ offset: state[0], place: file ? { file, line: state[2] + 1, column: state[3] + 1 } : (file === null ? null : undefined) });
+	}
+	return out;
+}
+
+/** `mappings` as a source map writes them, and the files they name. */
+function encode(mappings: Mapping[]): { files: string[]; mappings: string } {
+	const vlq = (number: number) => {
+		let value = number < 0 ? (-number << 1) | 1 : number << 1;
+		let out = '';
+		do {
+			const digit = value & 31;
+			value >>>= 5;
+			out += BASE64[value ? digit | 32 : digit];
+		} while (value);
+		return out;
+	};
+	const files: string[] = [];
+	const state = [0, 0, 0, 0];
+	const segments = mappings.map(({ offset, place }) => {
+		const fields = [offset];
+		if (place) {
+			if (!files.includes(place.file)) files.push(place.file);
+			fields.push(files.indexOf(place.file), place.line - 1, place.column - 1);
+		}
+		return fields.map((field, i) => {
+			const delta = field - state[i];
+			state[i] = field;
+			return vlq(delta);
+		}).join('');
+	});
+	return { files, mappings: segments.join(',') };
+}
+
+/**
+ * A plugin's map from asc's source map: each file by `name` - null leaves it
+ * out, its code then has no place - and `functions`, by wasm index from
+ * `first`. Code the source map gives no place - a call the optimiser made
+ * anew, as often as not - is where the code before it is: a frame stops at
+ * such calls. A mapping that says what the one before it said goes.
+ */
+export function pluginMap(sourceMap: string, name: (file: string) => string | null, first: number, functions: string[], root = ''): PluginMap {
+	const { sources = [], mappings = '' } = sourceMap ? JSON.parse(sourceMap) : {};
+	const kept: Mapping[] = [];
+	let last = '';
+	for (const mapping of decode(mappings, sources.map(name))) {
+		if (mapping.place === undefined) continue;
+		const key = mapping.place ? `${mapping.place.file}:${mapping.place.line}:${mapping.place.column}` : '';
+		if (key === last) continue;
+		last = key;
+		kept.push(mapping);
+	}
+	return { root, ...encode(kept), first, functions };
+}
+
+/** Where the code at byte `offset` of the wasm came from, or null. */
+export function placeOf(map: PluginMap, offset: number): Place | null {
+	let found: Place | null = null;
+	for (const mapping of decode(map.mappings, map.files)) {
+		if (mapping.offset > offset) break;
+		found = mapping.place ?? null;
+	}
+	return found;
+}
+
+/**
+ * A function's name as a stack shows it, from its name in the wasm; empty
+ * for the library's error handling - `__throw`, the errors' constructors,
+ * what makes their stack - which a stack leaves out: the frame below is where
+ * the error was made.
+ */
+export function displayName(internal: string): string {
+	if (internal.startsWith('~lib/error/')) return '';
+	if (/^start:[^~]*$/.test(internal)) return '<top level>';
+	const name = internal
+		// a function made at the top level, as one made in a function: `onSelect~anonymous|0`
+		.replace(/^start:[^~]*~anonymous\|\d+/, '<anonymous>')
+		// asc writes a function type's parentheses as %28 and %29
+		.replace(/%([\dA-F]{2})/g, (_, hex: string) => String.fromCharCode(Number.parseInt(hex, 16)))
+		// a path in front of a name, the generic arguments' too:
+		// `~lib/array/Array<plugins/shop/Item>#push` is `Array<Item>#push`
+		.replace(/(?:[\w.~@-]+\/)+/g, '')
+		.replace(/~anonymous\|\d+/g, '/<anonymous>')
+		.replace(/@\w+$/, '')
+		.replace(/#(?:get|set):/, '.');
+	return name.endsWith('#constructor') ? `new ${name.slice(0, -'#constructor'.length)}` : name.replace(/#/g, '.');
+}
+
+/** The section's text for `map`. */
+export function mapText(map: PluginMap): string {
+	return [
+		'amxts-map 1',
+		`root ${map.root}`,
+		`files ${map.files.length}`,
+		...map.files,
+		`functions ${map.first} ${map.functions.length}`,
+		...map.functions,
+		'mappings',
+		map.mappings,
+		'',
+	].join('\n');
+}
+
+/** `wasm` with `text` appended as the custom section `name`. */
+export function withSection(wasm: Uint8Array, name: string, text: string): Uint8Array {
+	const leb = (value: number) => {
+		const bytes: number[] = [];
+		do {
+			const byte = value & 0x7F;
+			value >>>= 7;
+			bytes.push(value ? byte | 0x80 : byte);
+		} while (value);
+		return bytes;
+	};
+	const encoder = new TextEncoder();
+	const nameBytes = encoder.encode(name);
+	const content = [...leb(nameBytes.length), ...nameBytes, ...encoder.encode(text)];
+	return new Uint8Array([...wasm, 0, ...leb(content.length), ...content]);
+}
+
+/** The map a wasm carries, or null. */
+export function readMap(wasm: Uint8Array): PluginMap | null {
+	const text = readSection(wasm, MAP_SECTION);
+	return text === null ? null : parseMap(text);
+}
+
+/** The text of a wasm's custom section by its name, or null. */
+export function readSection(wasm: Uint8Array, wanted: string): string | null {
+	let at = 8;
+	const u32 = () => {
+		let result = 0;
+		let shift = 0;
+		for (;;) {
+			const byte = wasm[at++];
+			result |= (byte & 0x7F) << shift;
+			if ((byte & 0x80) === 0) return result >>> 0;
+			shift += 7;
+		}
+	};
+	while (at < wasm.length) {
+		const id = wasm[at++];
+		const size = u32();
+		const end = at + size;
+		if (id === 0) {
+			const length = u32();
+			const name = new TextDecoder().decode(wasm.subarray(at, at + length));
+			if (name === wanted) return new TextDecoder().decode(wasm.subarray(at + length, end));
+		}
+		at = end;
+	}
+	return null;
+}
+
+/** The section's text, read back. */
+export function parseMap(text: string): PluginMap {
+	const lines = text.split('\n');
+	const fileCount = Number(lines[2].split(' ')[1]);
+	const files = lines.slice(3, 3 + fileCount);
+	const [, first, count] = lines[3 + fileCount].split(' ').map(Number);
+	const at = 4 + fileCount;
+	return { root: lines[1].slice('root '.length), files, first, functions: lines.slice(at, at + count), mappings: lines[at + count + 1] };
+}

package/scripts/system.ts

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'node:url';
 import { executable, MODULE_FILE } from '../src/system.mjs';
 
 export type { ServerSystem, System } from '../src/system.mjs';
-export { describeSystem, detectServerSystem, executable, HOST_SYSTEM, MODULE_FILE, parseSystem, serverSystem, SYSTEM_NAME, SYSTEMS, TARGET_ABI, WAMRC_PACKAGE, wamrcPath } from '../src/system.mjs';
+export { describeSystem, detectServerSystem, executable, HOST_SYSTEM, manifestName, MODULE_FILE, moduleVersion, parseSystem, serverFiles, serverFolder, serverImage, serverSystem, SYSTEM_NAME, SYSTEMS, TARGET_ABI, WAMRC_PACKAGE, wamrcPath } from '../src/system.mjs';
 
 const CORE = resolve(fileURLToPath(new URL('..', import.meta.url)));
 

package/scripts/typed-commands.ts

@@ -0,0 +1,263 @@
+// Commands with typed arguments: `server.addCommand` and `addServerCommand`.
+//
+//   interface KickArgs {
+//     target: Player;
+//     reason?: string;
+//   }
+//
+//   server.addCommand<KickArgs>("/kick <target> [reason]", ({ player, target, reason }) => {
+//     target.kick(reason ?? "Kicked by admin");
+//   });
+//
+// The editor types the handler with amxts.d.ts's signatures: the type
+// argument's fields and `player`; without one, text for every name the usage
+// has. AssemblyScript has neither intersection types nor reflection, so the
+// build writes, for each call - reading each file on its way to the compiler
+// (Sources.read), after the typed configs:
+//
+// - the usage's names, `<name>` required and `[name]` optional, checked
+//   against the interface both ways: a name in one and not the other, an
+//   optional one in one and a required one in the other, a required one after
+//   an optional one, stop the build with the place and the fix;
+// - a class of the handler's argument: `player` (a player's command) and the
+//   interface's fields, typed as the interface types them, which implements
+//   the interface, so the argument goes where the interface is expected;
+// - a function that registers the command with a parser of its words, each
+//   read as its type says (`CommandWords` in the facade): a `number` parsed,
+//   a `Player` found by `#userid`, the whole name or a part of it, a union of
+//   string literals one of them, a `string` as it is, the last argument, when
+//   it is text, the rest of the line. A word that is not what the command
+//   takes answers the one who typed it with the usage, and the handler does
+//   not run;
+// - the call's `server.addCommand<KickArgs>` becomes that function's name,
+//   padded, so the rest of the line keeps its columns.
+//
+// The interface is read from the source text - a syntax tree, no type checker
+// - in this file or imported, as the typed configs read theirs.
+import type { ImportReader } from './typed-configs';
+import ts from 'typescript';
+import { ShapeError, Shapes, withGenerated } from './typed-configs';
+
+/** The facade by its place in the tree, as the files' imports have it once rewritten (scripts/project.ts). */
+const FACADE = '~/facade';
+
+/**
+ * A call's usage: a string in place; a template whose substitutions make the
+ * name, `${name} [value]`, its arguments the text after them; or, from any
+ * other expression, a name alone, made at run time, without arguments - a
+ * command it is given by a variable takes no words.
+ */
+function usageOf(node: ts.Expression, typed: boolean, file: ts.SourceFile): Usage {
+	if (ts.isStringLiteralLike(node)) return usageOrFail(parseUsage(node.text), node, file);
+	if (ts.isTemplateExpression(node)) {
+		const text = node.head.text + node.templateSpans.map(span => `$name${span.literal.text}`).join('');
+		return usageOrFail(parseUsage(text), node, file);
+	}
+	if (typed) throw new ShapeError(node, file, 'a command with arguments has its usage in place - "/kick <target>", or `${name} <target>` for a name made at run time: the build reads the arguments from it');
+	return { name: '', args: [] };
+}
+
+function usageOrFail(usage: Usage | string, node: ts.Node, file: ts.SourceFile): Usage {
+	if (typeof usage === 'string') throw new ShapeError(node, file, usage);
+	return usage;
+}
+
+/** What an argument is read as. */
+type Kind = { kind: 'number' } | { kind: 'text' } | { kind: 'player' } | { kind: 'name'; names: string[] };
+
+interface Argument {
+	name: string;
+	optional: boolean;
+	kind: Kind;
+}
+
+interface Usage {
+	name: string;
+	args: { name: string; optional: boolean }[];
+}
+
+interface Place { path: string; file: ts.SourceFile }
+
+/** A usage's command name and arguments, in order: `"/kick <target> [reason]"`; a chat phrase, `"say rules"`, has none. Text: what is wrong with it. */
+export function parseUsage(usage: string): Usage | string {
+	const text = usage.trim();
+	if (text.startsWith('say ')) return { name: text, args: [] };
+	const [name, ...rest] = text.split(/\s+/);
+	if (!name) return 'the usage is empty: write the command\'s name first, e.g. "/hp"';
+	const args: Usage['args'] = [];
+	for (const word of rest) {
+		const match = word.match(/^(?:<([A-Z_$][\w$]*)>|\[([A-Z_$][\w$]*)\])$/i);
+		if (!match) return `"${word}" - an argument is one word, <name> or [name]: ${name} <target> [reason]`;
+		const optional = match[2] !== undefined;
+		const argName = match[1] ?? match[2];
+		if (!optional && args.some(arg => arg.optional)) return `<${argName}> - a required argument cannot follow an optional one`;
+		if (args.some(arg => arg.name === argName)) return `${argName} - the usage names it twice`;
+		args.push({ name: argName, optional });
+	}
+	return { name, args };
+}
+
+/** What one argument's type is read as. */
+function kindOf(type: ts.TypeNode, shapes: Shapes, at: Place): Kind {
+	if (ts.isTypeReferenceNode(type) && ts.isIdentifier(type.typeName) && type.typeName.text === 'Player' && !type.typeArguments) return { kind: 'player' };
+	const shape = shapes.ofType(type, at);
+	if (shape.kind === 'number' || shape.kind === 'text') return { kind: shape.kind };
+	if (shape.kind === 'name') return { kind: 'name', names: shape.names };
+	throw new ShapeError(type, at.file, `${type.getText(at.file)} - a command's argument is a number, a string, a Player or a union of string literals`);
+}
+
+/** The arguments a call's type says: each usage name with its interface field's type; text for each without a type. */
+function argumentsOf(call: ts.CallExpression, usage: Usage, shapes: Shapes, at: Place, player: boolean): Argument[] {
+	const typeArgument = call.typeArguments?.[0];
+	if (!typeArgument) return usage.args.map(arg => ({ ...arg, kind: { kind: 'text' } }));
+
+	if (!ts.isTypeReferenceNode(typeArgument)) {
+		throw new ShapeError(typeArgument, at.file, `${typeArgument.getText(at.file)} - a command's arguments are an interface declared beside it, passed by its name: interface KickArgs { target: Player }, then addCommand<KickArgs>(...)`);
+	}
+	const found = shapes.declaration(typeArgument.typeName, at);
+	if (!found || !ts.isInterfaceDeclaration(found.node)) {
+		throw new ShapeError(typeArgument, at.file, `${typeArgument.getText(at.file)} - a command's arguments are an interface, declared in this file or imported into it`);
+	}
+
+	const fields = new Map<string, Argument & { node: ts.Node }>();
+	for (const member of found.node.members) {
+		if (!ts.isPropertySignature(member) || !member.type || !ts.isIdentifier(member.name)) {
+			throw new ShapeError(member, found.at.file, `${member.getText(found.at.file).trim()} - a command's argument is a field with its type`);
+		}
+		const name = member.name.text;
+		if (name === 'player' && player) throw new ShapeError(member, found.at.file, 'player - the handler gets the player who typed the command as player: name the argument otherwise');
+		fields.set(name, { name, optional: !!member.questionToken, kind: kindOf(member.type, shapes, found.at), node: member });
+	}
+
+	const type = typeArgument.getText(at.file);
+	for (const arg of usage.args) {
+		const field = fields.get(arg.name);
+		if (!field) throw new ShapeError(call.arguments[0], at.file, `${arg.name} - the usage has it and ${type} does not: add ${arg.name}${arg.optional ? '?' : ''}: string (or a number, a Player) to ${type}, or take it out of the usage`);
+		if (field.optional !== arg.optional) {
+			throw new ShapeError(field.node, found.at.file, arg.optional
+				? `${arg.name} - the usage has it optional, [${arg.name}]: write ${arg.name}?: in ${type}, or <${arg.name}> in the usage`
+				: `${arg.name} - the usage requires it, <${arg.name}>: write ${arg.name}: without the ? in ${type}, or [${arg.name}] in the usage`);
+		}
+	}
+	for (const [name, field] of fields) {
+		if (!usage.args.some(arg => arg.name === name)) throw new ShapeError(field.node, found.at.file, `${name} - ${type} has it and the usage does not: write <${name}> or [${name}] in the usage, or take it out of ${type}`);
+	}
+	return usage.args.map(arg => fields.get(arg.name)!);
+}
+
+/** The type of a field of the handler's argument in the generated class. */
+function typeOf(arg: Argument): string {
+	if (arg.kind.kind === 'number') return 'number';
+	return arg.kind.kind === 'player' ? '__AmxtsPlayer' : 'string';
+}
+
+/** The parser's lines that read the word at `at` into the argument, indented by `tabs`. */
+function readOf(arg: Argument, at: number, last: boolean, tabs: string): string[] {
+	switch (arg.kind.kind) {
+		case 'number': return [`${tabs}args.${arg.name} = words.number(${at});`];
+		case 'name': return [`${tabs}args.${arg.name} = words.name(${at}, ${JSON.stringify(arg.kind.names)});`];
+		case 'player': return [
+			`${tabs}const __${arg.name} = words.target(${at});`,
+			`${tabs}if (__${arg.name} == null) return;`,
+			`${tabs}args.${arg.name} = __${arg.name};`,
+		];
+		default: return [`${tabs}args.${arg.name} = words.${last ? 'rest' : 'text'}(${at});`];
+	}
+}
+
+/**
+ * The generated code for one call: the class of its handler's argument - an
+ * implementation of `shape`, the interface the call names - and the function
+ * that registers it.
+ */
+function commandCode(index: number, method: 'addCommand' | 'addServerCommand', args: Argument[], shape: string | undefined): string {
+	const player = method === 'addCommand';
+	const type = `__AmxtsCommandArgs${index}`;
+	const required = args.filter(arg => !arg.optional).length;
+	const lastIsText = args.length > 0 && args[args.length - 1].kind.kind === 'text';
+	const reads = args.flatMap((arg, at) => {
+		const lines = readOf(arg, at, at === args.length - 1, arg.optional ? '\t\t\t' : '\t\t');
+		return arg.optional ? [`\t\tif (words.count > ${at}) {`, ...lines, '\t\t}'] : lines;
+	});
+	return [
+		`class ${type}${shape ? ` implements ${shape}` : ''} {`,
+		...(player ? ['\tplayer!: __AmxtsPlayer;'] : []),
+		...args.map(arg => `\t${arg.name}${arg.optional ? '?' : '!'}: ${typeOf(arg)};`),
+		'}',
+		`function __amxtsCommand${index}(usage: string, handler: (args: ${type}) => void${player ? ', options: __AmxtsCommandOptions = {}' : ''}): void {`,
+		`\t__amxtsServer.__${method}(usage, (words: __AmxtsCommandWords): void => {`,
+		`\t\tconst args = new ${type}();`,
+		...(player ? ['\t\targs.player = words.player!;'] : []),
+		...(required > 0 ? [`\t\tif (!words.need(${required})) return;`] : []),
+		...reads,
+		...(lastIsText ? [] : [`\t\tif (!words.done(${args.length})) return;`]),
+		'\t\tif (words.failed) return;',
+		'\t\thandler(args);',
+		`\t}${player ? ', options' : ''});`,
+		'}',
+	].join('\n');
+}
+
+export interface TypedCommands {
+	text: string;
+	problems: string[];
+}
+
+/** The file with its commands' calls made the generated functions'; what does not build, with its place. */
+export function typedCommands(path: string, display: string, text: string, imports: ImportReader): TypedCommands {
+	if (!text.includes('addCommand') && !text.includes('addServerCommand')) return { text, problems: [] };
+
+	const shapes = new Shapes(imports);
+	const file = shapes.parsed(path, text);
+	// The facade's `server`, by the names this file imports it as.
+	const servers = new Set<string>();
+	for (const statement of file.statements) {
+		if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== FACADE) continue;
+		const bindings = statement.importClause?.namedBindings;
+		if (!bindings || !ts.isNamedImports(bindings)) continue;
+		for (const element of bindings.elements) {
+			if ((element.propertyName ?? element.name).text === 'server') servers.add(element.name.text);
+		}
+	}
+	if (!servers.size) return { text, problems: [] };
+
+	const edits: { start: number; end: number; with: string }[] = [];
+	const functions: string[] = [];
+	const problems: string[] = [];
+	const at: Place = { path, file };
+
+	const visit = (node: ts.Node) => {
+		ts.forEachChild(node, visit);
+		if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return;
+		const method = node.expression.name.text;
+		if (method !== 'addCommand' && method !== 'addServerCommand') return;
+		if (!ts.isIdentifier(node.expression.expression) || !servers.has(node.expression.expression.text)) return;
+
+		try {
+			const usageNode = node.arguments[0];
+			if (!usageNode) throw new ShapeError(node, file, 'the usage is missing: server.addCommand("/hp", ({ player }) => ...)');
+			const usage = usageOf(usageNode, !!node.typeArguments?.length, file);
+			const name = `__amxtsCommand${functions.length}`;
+			const shape = node.typeArguments?.[0]?.getText(file);
+			functions.push(commandCode(functions.length, method, argumentsOf(node, usage, shapes, at, method === 'addCommand'), shape));
+			const start = node.expression.getStart(file);
+			const end = node.arguments.pos - 1;
+			edits.push({ start, end, with: name.padEnd(end - start) });
+		} catch (problem) {
+			if (!(problem instanceof ShapeError)) throw problem;
+			const place = problem.file.getLineAndCharacterOfPosition(problem.node.getStart(problem.file));
+			const where = problem.file === file ? display : problem.file.fileName;
+			problems.push(`${where}:${place.line + 1}:${place.character + 1}: server.${method} - ${problem.message}`);
+		}
+	};
+	visit(file);
+
+	if (!edits.length) return { text, problems };
+
+	let out = text;
+	for (const edit of edits.sort((a, b) => b.start - a.start)) out = out.slice(0, edit.start) + edit.with + out.slice(edit.end);
+
+	const code = ['// GENERATED by scripts/typed-commands.ts: the commands this file adds, each word read as its type says.', ...functions].join('\n');
+	const facade = `import { server as __amxtsServer, Player as __AmxtsPlayer, CommandOptions as __AmxtsCommandOptions, __CommandWords as __AmxtsCommandWords } from "${FACADE}";`;
+	return { text: withGenerated(path, out, code, facade), problems };
+}