A local-first multi-agent app development platform, built on PenguinHarness
#!/usr/bin/env node
/**
* gen-ifaces: project every interface class (`@Interface()`, or `extends Interface<…>()`) and every @Component
* class of a package into the
* kernel's signature-level form (core kernel/sig.ts) and write ONE `ifaces.json` per
* package — the table the module-tree check (kernel/check.ts) runs over.
*
* node scripts/gen-ifaces.mjs --project packages/server/tsconfig.json --out packages/server/src/ifaces.json
* node scripts/gen-ifaces.mjs ... --check # CI: fail when the file on disk is stale
*
* The table also carries every module's manifest, read STATICALLY off its class — the
* `@Module({...})` / `@Component({...})` literal and the `@Use` / `@Provide` / `@Bind`
* fields, identifiers resolved to their declarations, never executed. A @Component is a
* class that exports itself: its key is `<name>#<Class>`, its interface is its public
* surface (members that do not project become opaque with a warning), and a bare
* `@Use()` field typed by a component is wired to that component.
*
* The TS interface is the source; this file is its projection, so the two cannot drift
(the table is generated,
* not committed: `pnpm typecheck`, the server's `build` and `test`, and deploy.mjs all
* regenerate it; `--check` remains for a CI that wants to assert a committed copy). Keys are `<module>#<Export>`, where the
* module is the package name for an interface class (its identity is its structure; the
* key only has to agree between provider and consumer) and a component's own name.
*
* Projection rules — the generator REFUSES what it does not recognize rather than guess:
* data types (primitives, literals, unions, arrays, tuples, plain objects, records)
* → arktype definitions; a NAMED data type (an interface without methods, a type
* alias) is emitted once into `types` and referenced as { "$ref": "<module>#<Name>" },
* which also makes a recursive type a reference to itself rather than a cut
* an interface WITH methods → { iface: "<module>#<Name>" }, emitted into the table;
* its non-method members become `fields` (a published config object is all fields)
* function types → { fn }
* Promise<T> / PromiseLike<T> → { promise }
* AsyncIterable<T> / AsyncGenerator<T> → { stream }
* void / undefined return → { void }
* Opaque<"Name"> (core kernel/markers) → { opaque: "<package>#Name" } — the only by-name
* comparison, and the name is always qualified by the declaring package
* <Name>Slots companion interface → the slots of <Name>; a property typed Slot<D, C>
* declares a code half
* classes, Map/Set, generics, rest parameters, unions mixing data with non-data → error
* A type that recurses into itself is cut at the cycle and compared by name (a warning).
*/
import fs from "node:fs";
import { createHash } from "node:crypto";
import path from "node:path";
import ts from "typescript";
const args = process.argv.slice(2);
const opt = (name) => {
const at = args.indexOf(name);
return at === -1 ? null : args[at + 1];
};
const projects = args.flatMap((a, i) => (a === "--project" ? [args[i + 1]] : []));
const outPath = opt("--out");
const checkOnly = args.includes("--check");
if (projects.length === 0 || outPath === null) {
console.error(
"usage: gen-ifaces --project <tsconfig> [--project ...] --out <ifaces.json> [--check]",
);
process.exit(2);
}
const warnings = [];
const errors = [];
/** The last reason dataOf answered null, for the error that follows it. */
let notData = "";
/** module name for a source file: nearest module.json's name, else nearest package.json's name. */
const moduleNameCache = new Map();
function moduleNameOf(fileName) {
let dir = path.dirname(fileName);
if (moduleNameCache.has(dir)) return moduleNameCache.get(dir);
const start = dir;
for (;;) {
// A module's name is the `name` of the defineModule({...}) literal in its module.ts;
// a plugin package's classes are keyed by the package name (the table it ships is
// generated over its own tsconfig, so the key only has to agree within it).
const mts = path.join(dir, "module.ts");
if (fs.existsSync(mts)) {
const m =
/(?:defineModule|manifestOf|@Module|@Component)\(\s*\{\s*"?name"?:\s*"([^"]+)"/.exec(
fs.readFileSync(mts, "utf8"),
);
if (m) {
moduleNameCache.set(start, m[1]);
return m[1];
}
}
const pkg = path.join(dir, "package.json");
if (fs.existsSync(pkg)) {
const name = JSON.parse(fs.readFileSync(pkg, "utf8")).name;
moduleNameCache.set(start, name);
return name;
}
const parent = path.dirname(dir);
if (parent === dir) throw new Error(`no module.json or package.json above ${fileName}`);
dir = parent;
}
}
const table = {};
/** `@Use` fields typed by a component class — a dependency on an implementation, not a mechanism. */
const implementationDeps = [];
/** Named data types, keyed like interfaces; signatures reference them as { "$ref": key }. */
const types = {};
/** Module manifests, extracted STATICALLY from each module.ts's defineModule({...}) literal. */
const manifests = {};
/**
* What a PLUGIN package's default export names — `{ modules: [A, B], replaces: [C] }` —
* read off the source, so a surface can say what a listed package adds without importing
* it. Absent for a package that has no such default export (the harness itself).
*/
let pluginDecl = null;
for (const project of projects) {
const configPath = path.resolve(project);
const parsed = ts.getParsedCommandLineOfConfigFile(
configPath,
{},
{
...ts.sys,
onUnRecoverableConfigFileDiagnostic: (d) => {
throw new Error(ts.flattenDiagnosticMessageText(d.messageText, "\n"));
},
},
);
const program = ts.createProgram({ rootNames: parsed.fileNames, options: parsed.options });
const checker = program.getTypeChecker();
const sourceFiles = program
.getSourceFiles()
.filter((sf) => !sf.isDeclarationFile && !sf.fileName.includes("/node_modules/"));
/** An `@Interface()` decorator, like every other decorator here a factory call. */
const hasInterfaceDecorator = (d) =>
(ts.getDecorators?.(d) ?? []).some(
(dec) =>
ts.isCallExpression(dec.expression) &&
ts.isIdentifier(dec.expression.expression) &&
dec.expression.expression.text === "Interface",
);
/**
* An interface handle, wherever it is declared, in either spelling: `@Interface()`
* on a class that declares its own abstract members, or `extends Interface<…>()` for
* an interface that IS an existing type (see core kernel/markers.ts).
*/
const isInterfaceClassDecl = (d) =>
ts.isClassDeclaration(d) &&
(hasInterfaceDecorator(d) ||
(d.heritageClauses ?? []).some((h) =>
h.types.some(
(t) =>
ts.isCallExpression(t.expression) &&
ts.isIdentifier(t.expression.expression) &&
t.expression.expression.text === "Interface",
),
));
/**
* A decorated interface class must be exactly a declaration. Anything else — a base to
* inherit members from, a constructor, a member with a body, a private one — would put
* implementation into the contract or hide part of it, and which of the two was meant
* is not something to guess at.
*/
const checkDecoratedInterface = (d, file) => {
if (!ts.isClassDeclaration(d) || !hasInterfaceDecorator(d)) return;
const name = d.name?.text ?? "?";
const abstract = (d.modifiers ?? []).some((m) => m.kind === ts.SyntaxKind.AbstractKeyword);
if (!abstract) errors.push(`${file}: @Interface() ${name}: must be an abstract class`);
if ((d.heritageClauses ?? []).length > 0)
errors.push(
`${file}: @Interface() ${name}: must not extend or implement anything — an interface that IS an existing type uses \`extends Interface<T>()\``,
);
for (const m of d.members) {
const mods = m.modifiers ?? [];
const has = (k) => mods.some((x) => x.kind === k);
const label = m.name?.getText?.() ?? "member";
if (ts.isConstructorDeclaration(m)) {
errors.push(`${file}: @Interface() ${name}: must not declare a constructor`);
continue;
}
if (has(ts.SyntaxKind.PrivateKeyword) || has(ts.SyntaxKind.ProtectedKeyword))
errors.push(`${file}: @Interface() ${name}.${label}: every member is public`);
if (has(ts.SyntaxKind.StaticKeyword))
errors.push(`${file}: @Interface() ${name}.${label}: static members are not part of it`);
if (!has(ts.SyntaxKind.AbstractKeyword))
errors.push(
`${file}: @Interface() ${name}.${label}: must be abstract — a member with a body is implementation`,
);
}
};
// Module manifests: the first argument of every defineModule(...) call, which must be a
// pure literal — the static half that is checked before any module code runs.
const literal = (node, file) => {
if (ts.isObjectLiteralExpression(node)) {
const out = {};
for (const prop of node.properties) {
if (!ts.isPropertyAssignment(prop)) {
errors.push(
`${file}:${node.getStart()}: manifest literal: only plain properties are allowed`,
);
continue;
}
const key = ts.isIdentifier(prop.name)
? prop.name.text
: ts.isStringLiteral(prop.name)
? prop.name.text
: null;
if (key === null) {
errors.push(`${file}: manifest literal: computed property names are not allowed`);
continue;
}
out[key] = literal(prop.initializer, file);
}
return out;
}
if (ts.isArrayLiteralExpression(node)) return node.elements.map((e) => literal(e, file));
if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
if (ts.isNumericLiteral(node)) return Number(node.text);
if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
if (node.kind === ts.SyntaxKind.NullKeyword) return null;
if (
ts.isAsExpression(node) ||
ts.isSatisfiesExpression(node) ||
ts.isParenthesizedExpression(node)
)
return literal(node.expression, file);
errors.push(
`${file}:${node.getStart()}: manifest literal: '${node.getText().slice(0, 40)}' is not a literal — a manifest is data`,
);
return null;
};
// Module classes: the @Module({...}) meta literal (name, contributes, context, children) plus
// the @Use / @Provide fields, whose TYPE ANNOTATION names the interface class and whose
// decorator argument names the providing module class. Identifiers resolve to their
// declarations — never executed. Pass 1 collects names; pass 2 resolves references.
const moduleClasses = new Map(); // class symbol → { node, meta, file }
const refLiteral = (node, file) => {
if (ts.isIdentifier(node)) {
const sym = checker.getSymbolAtLocation(node);
return { $id: sym && sym.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(sym) : sym };
}
if (ts.isObjectLiteralExpression(node)) {
const out = {};
for (const prop of node.properties) {
if (!ts.isPropertyAssignment(prop)) {
errors.push(`${file}: @Module literal: only plain properties are allowed`);
continue;
}
const key = ts.isIdentifier(prop.name)
? prop.name.text
: ts.isStringLiteral(prop.name)
? prop.name.text
: null;
if (key === null) {
errors.push(`${file}: @Module literal: computed property names are not allowed`);
continue;
}
out[key] = refLiteral(prop.initializer, file);
}
return out;
}
if (ts.isArrayLiteralExpression(node)) return node.elements.map((e) => refLiteral(e, file));
return literal(node, file);
};
const decoratorCall = (node, name) => {
for (const dec of ts.getDecorators?.(node) ?? []) {
const call = dec.expression;
if (
ts.isCallExpression(call) &&
ts.isIdentifier(call.expression) &&
call.expression.text === name
)
return call;
}
return null;
};
for (const sf of program.getSourceFiles()) {
if (sf.isDeclarationFile || sf.fileName.includes("/node_modules/")) continue;
const file = path.relative(process.cwd(), sf.fileName);
const visit = (node) => {
if (ts.isClassDeclaration(node) && node.name) {
const asModule = decoratorCall(node, "Module");
const asComponent = decoratorCall(node, "Component");
const call = asModule ?? asComponent;
if (asModule && asComponent)
errors.push(`${file}: class '${node.name.text}' is both a @Module and a @Component`);
if (call && call.arguments.length <= 1) {
moduleClasses.set(checker.getSymbolAtLocation(node.name), {
node,
meta: call.arguments.length === 0 ? {} : refLiteral(call.arguments[0], file),
file,
kind: asModule ? "module" : "component",
className: node.name.text,
});
}
}
ts.forEachChild(node, visit);
};
visit(sf);
}
const moduleNameBySymbol = new Map();
/** component class symbol → its interface key: a component's name is its own module. */
const componentKeyBySymbol = new Map();
for (const [sym, { node, meta, file, kind, className }] of moduleClasses) {
// A node is named by its class: `export class AuthService` is the node `AuthService`.
if ("name" in meta) {
errors.push(
`${file}: @${kind === "module" ? "Module" : "Component"} meta names the node — a node is named by its class ('${className}')`,
);
continue;
}
meta.name = className;
moduleNameBySymbol.set(sym, meta.name);
// `export default class X` names its symbol "default"; the class keeps its own name.
if (kind === "component")
componentKeyBySymbol.set(sym, `${moduleNameOf(node.getSourceFile().fileName)}#${className}`);
}
// The plugin declaration: `export default { modules: [...], replaces: [...] }`, or a
// default-exported binding initialized to that literal (`const plugin: Plugin = {...}`).
// Each element must be a module class of this package; anything else is refused.
const unwrap = (e) =>
ts.isSatisfiesExpression(e) || ts.isAsExpression(e) || ts.isParenthesizedExpression(e)
? unwrap(e.expression)
: e;
for (const sf of program.getSourceFiles()) {
if (sf.isDeclarationFile || sf.fileName.includes("/node_modules/")) continue;
for (const st of sf.statements) {
if (!ts.isExportAssignment(st) || st.isExportEquals) continue;
let literal = unwrap(st.expression);
if (ts.isIdentifier(literal)) {
const sym0 = checker.getSymbolAtLocation(literal);
const sym =
sym0 && sym0.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(sym0) : sym0;
const decl = sym?.valueDeclaration;
if (decl && ts.isVariableDeclaration(decl) && decl.initializer)
literal = unwrap(decl.initializer);
}
if (!ts.isObjectLiteralExpression(literal)) continue;
const lists = { modules: [], replaces: [] };
let isPlugin = false;
for (const prop of literal.properties) {
const key =
ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name) ? prop.name.text : null;
if (key !== "modules" && key !== "replaces") continue;
isPlugin = true;
const file = path.relative(process.cwd(), sf.fileName);
const arr = unwrap(prop.initializer);
if (!ts.isArrayLiteralExpression(arr)) {
errors.push(
`${file}: the default export's ${key} must be an array literal of module classes`,
);
continue;
}
for (const el of arr.elements) {
const sym0 = ts.isIdentifier(el) ? checker.getSymbolAtLocation(el) : undefined;
const sym =
sym0 && sym0.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(sym0) : sym0;
const name = sym === undefined ? undefined : moduleNameBySymbol.get(sym);
if (name === undefined) {
errors.push(
`${file}: the default export's ${key} names '${el.getText()}', which is not a @Module or @Component class of this package`,
);
continue;
}
lists[key].push(name);
}
}
if (!isPlugin) continue;
if (pluginDecl !== null) {
errors.push(
`${path.relative(process.cwd(), sf.fileName)}: a second default export names modules — a package has one plugin declaration`,
);
}
pluginDecl = lists;
}
}
/** interfaces with methods, by symbol → key; filled as they are met so references resolve. */
const keys = new Map();
const pending = [];
// An exported interface class is keyed by the EXPORTING module (a re-export from elsewhere in
// the package keeps that module's name); a type only reached through a signature is
// keyed by where it is declared.
const keyOf = (symbol, decl, exportingFile = null) => {
if (keys.has(symbol)) return keys.get(symbol);
const owner = exportingFile ?? decl.getSourceFile();
const key =
componentKeyBySymbol.get(symbol) ?? `${moduleNameOf(owner.fileName)}#${symbol.getName()}`;
keys.set(symbol, key);
pending.push({ symbol, decl, key });
return key;
};
const where = (node) => {
const sf = node.getSourceFile();
const { line } = sf.getLineAndCharacterOfPosition(node.getStart());
return `${path.relative(process.cwd(), sf.fileName)}:${line + 1}`;
};
const fail = (node, message) => {
errors.push(`${where(node)}: ${message}`);
return { data: "unknown" };
};
const isMethodLike = (symbol, atNode) => {
const t = checker.getTypeOfSymbolAtLocation(symbol, atNode);
return t.getCallSignatures().length > 0 && t.getProperties().length === 0;
};
const hasMethods = (type, atNode) => type.getProperties().some((p) => isMethodLike(p, atNode));
const hasUndefined = (type) =>
type.isUnion() && type.types.some((t) => t.getFlags() & ts.TypeFlags.Undefined);
const hasNull = (type) =>
type.isUnion()
? type.types.some((t) => (t.getFlags() & ts.TypeFlags.Null) !== 0)
: (type.getFlags() & ts.TypeFlags.Null) !== 0;
/**
* What an optional member or parameter adds is `undefined`; that is what comes off.
* `null` is a value the contract has to keep — `x?: string | null` and `x?: string` are
* different promises, and a provider handing back null where the consumer allows only
* undefined must not pass. The checker can only strip both at once, so null is noted
* here and put back on the projected definition by `orNull` / `exprOrNull`.
*/
// `getNonNullableType(unknown)` is `{}` — everything that is not null or undefined — so an
// optional `unknown` member (a JSON body, say) used to be projected as the empty object
// shape, which refuses `null`. `unknown` and `any` have nothing to strip: keep them.
const sansUndefined = (type) => ({
type:
type.flags & (ts.TypeFlags.Unknown | ts.TypeFlags.Any)
? type
: checker.getNonNullableType(type),
nullable: type.isUnion() && hasNull(type),
});
const orNull = (def) =>
typeof def === "string"
? def
.split("|")
.map((s) => s.trim())
.includes("null")
? def
: `${def}|null`
: [def, "|", "null"];
const exprOrNull = (expr) =>
"data" in expr ? { ...expr, data: orNull(expr.data) } : { oneOf: [expr, { data: "null" }] };
/**
* A type declared by the platform (TypeScript's lib, @types/node, a dependency's .d.ts)
* rather than by this package: compared by NAME, as `Opaque<>` would spell it — the host
* object behind AbortSignal or Request is the same on both sides of a push, and its
* structure is not ours to check.
*/
/** An interface class (core kernel/markers.ts Interface) or a component: a handle, never a host object. */
const isIfaceClass = (symbol) =>
symbol !== undefined &&
(componentKeyBySymbol.has(symbol) ||
(symbol.declarations ?? []).some((d) => isInterfaceClassDecl(d)));
const isHostDeclared = (symbol) =>
symbol !== undefined &&
(symbol.declarations ?? []).length > 0 &&
symbol.declarations.every((d) => {
const f = d.getSourceFile();
return (
f.isDeclarationFile &&
(f.fileName.includes("/node_modules/") || /\/lib\.[\w.]+\.d\.ts$/.test(f.fileName))
);
});
const quote = (s) => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
/** The `types` key for a named data type, or null for an anonymous one. */
function namedKeyOf(type) {
const alias = type.aliasSymbol;
const symbol = alias ?? type.getSymbol();
if (!symbol) return null;
const name = symbol.getName();
if (name === "__type" || name === "__object" || name.startsWith("__")) return null;
// Instantiated generics (OmniMessage<OmniPayload>) are named by their instantiation.
const args = alias ? type.aliasTypeArguments : checker.getTypeArguments?.(type);
const decl = symbol.declarations?.[0];
if (!decl) return null;
if (!(symbol.flags & (ts.SymbolFlags.Interface | ts.SymbolFlags.TypeAlias))) return null;
const suffix =
args && args.length > 0 ? `<${args.map((a) => checker.typeToString(a)).join(",")}>` : "";
return `${moduleNameOf(decl.getSourceFile().fileName)}#${name}${suffix}`;
}
/** arktype definition for a DATA type, or null when the type is not data. */
function dataOf(type, atNode, stack) {
// A named data type is emitted once and referenced — so a recursive one refers to
// itself and needs no cut. Anonymous shapes still guard on identity.
const key = namedKeyOf(type);
if (key !== null && !(type.getFlags() & (ts.TypeFlags.Primitive | ts.TypeFlags.Literal))) {
if (key in types || stack.includes(type)) return { $ref: key };
types[key] = null; // reserve: a self-reference met while projecting resolves to $ref
const projected = projectData(type, atNode, [...stack, type]);
if (projected === null) {
delete types[key];
return null;
}
types[key] = projected;
return { $ref: key };
}
if (stack.includes(type)) {
const label = type.aliasSymbol?.getName() ?? type.getSymbol()?.getName() ?? "type";
warnings.push(
`${where(atNode)}: '${label}' is recursive; compared as unknown past the cycle`,
);
return "unknown";
}
return projectData(type, atNode, stack);
}
/** dataOf without the naming step. */
function projectData(type, atNode, stack) {
if (stack.length > 12) {
warnings.push(
`${where(atNode)}: '${checker.typeToString(type)}' is deeper than 12 levels; compared as unknown past that`,
);
return "unknown";
}
stack = [...stack, type];
const f = type.getFlags();
if (f & ts.TypeFlags.String) return "string";
if (f & ts.TypeFlags.Number) return "number";
if (f & ts.TypeFlags.BigInt) return "bigint";
if (f & ts.TypeFlags.Boolean) return "boolean";
if (f & ts.TypeFlags.BooleanLiteral) return checker.typeToString(type);
if (f & ts.TypeFlags.Null) return "null";
if (f & ts.TypeFlags.Undefined) return "undefined";
if (f & (ts.TypeFlags.Unknown | ts.TypeFlags.Any)) return "unknown";
if (f & ts.TypeFlags.Never) return "never";
if (f & ts.TypeFlags.StringLiteral) return quote(type.value);
if (f & ts.TypeFlags.NumberLiteral) return String(type.value);
if (f & ts.TypeFlags.EnumLiteral && type.isUnion()) {
return type.types.map((t) => dataOf(t, atNode, stack)).join("|");
}
if (type.isUnion()) {
const parts = type.types.map((t) => dataOf(t, atNode, stack));
if (parts.some((p) => p === null)) {
notData = `member of '${checker.typeToString(type)}': ${notData || "not data"}`;
return null;
}
// Collapse `true | false` back to boolean and keep string-only unions readable.
if (parts.every((p) => typeof p === "string")) {
const set = new Set(parts);
if (set.has("true") && set.has("false")) {
set.delete("true");
set.delete("false");
set.add("boolean");
}
return [...set].join("|");
}
return parts.slice(1).reduce((acc, p) => [acc, "|", p], parts[0]);
}
if (type.isIntersection()) {
const opaque = type.types.find((t) => t.getProperty("__opaque"));
if (opaque) {
notData = `'${checker.typeToString(type)}' is opaque`;
return null; // handled as opaque by exprOf
}
const parts = type.types.map((t) => dataOf(t, atNode, stack));
if (parts.some((p) => p === null)) {
notData = `part of '${checker.typeToString(type)}': ${notData || "not data"}`;
return null;
}
return parts.slice(1).reduce((acc, p) => [acc, "&", p], parts[0]);
}
if (f & ts.TypeFlags.TypeParameter) {
// Erased: a type parameter has no wire form, so the contract says `unknown` here.
warnings.push(
`${where(atNode)}: type parameter '${checker.typeToString(type)}' erased to unknown`,
);
return "unknown";
}
if (f & ts.TypeFlags.Object) {
const symbol = type.getSymbol();
const name = symbol?.getName();
if (name === "Date") return "Date";
if (checker.isArrayType(type) || name === "ReadonlyArray") {
const elem = checker.getTypeArguments(type)[0];
const inner = dataOf(elem, atNode, stack);
if (inner === null) {
notData = `element of '${checker.typeToString(type)}': ${notData || "not data"}`;
return null;
}
return typeof inner === "string" && /^[\w'|]+$/.test(inner) ? `${inner}[]` : [inner, "[]"];
}
if (checker.isTupleType(type)) {
const elems = checker.getTypeArguments(type).map((t) => dataOf(t, atNode, stack));
if (elems.some((e) => e === null)) {
notData = `tuple element: ${notData || "not data"}`;
return null;
}
return elems;
}
if (name === "Map" || name === "Set" || name === "WeakMap") {
fail(atNode, `${name} has no wire form; use an array or a record`);
return "unknown";
}
if (type.getCallSignatures().length > 0) {
notData = `'${checker.typeToString(type)}' is a function`;
return null;
}
// A host-declared object with behavior is opaque (exprOf); a host-declared plain
// shape ({ x: number } from a .d.ts) is data like any other.
if (
isHostDeclared(symbol) &&
(symbol.flags & ts.SymbolFlags.Class || hasMethods(type, atNode))
) {
notData = `'${name}' is a host object`;
return null;
}
if (symbol && symbol.flags & ts.SymbolFlags.Class) {
if (isIfaceClass(symbol)) {
notData = `'${name}' is an interface class`;
return null;
}
fail(atNode, `class '${name}' cannot be a data type; wrap it as Opaque<"${name}">`);
return "unknown";
}
if (hasMethods(type, atNode)) {
notData = `'${checker.typeToString(type)}' has methods`;
return null;
}
const next = stack;
const out = {};
const stringIndex = checker.getIndexInfoOfType(type, ts.IndexKind.String);
if (stringIndex) {
const v = dataOf(stringIndex.type, atNode, next);
if (v === null) {
notData = `${name ?? "object"}.[string]: ${notData || checker.typeToString(stringIndex.type)}`;
return null;
}
out["[string]"] = v;
}
for (const prop of type.getProperties()) {
const propType = checker.getTypeOfSymbolAtLocation(prop, atNode);
// `x?: T` reads as `T | undefined` under strictNullChecks; an instantiated property
// may carry the union without the Optional flag, so the union is the test.
const optional = (prop.flags & ts.SymbolFlags.Optional) !== 0 || hasUndefined(propType);
const { type: kept, nullable } = optional
? sansUndefined(propType)
: { type: propType, nullable: false };
let v = dataOf(kept, atNode, next);
if (v === null) {
notData = `${name ?? "object"}.${prop.getName()}: ${notData || `'${checker.typeToString(propType)}' flags=${propType.getFlags()} sym=${propType.getSymbol()?.getName()}`}`;
return null;
}
if (nullable) v = orNull(v);
out[optional ? `${prop.getName()}?` : prop.getName()] = v;
}
return out;
}
notData = `'${checker.typeToString(type)}' (flags ${type.getFlags()}) has no data form`;
return null;
}
/**
* The package a declaration belongs to — the second half of an opaque identity. A
* by-name comparison is only safe when the name is qualified by who declared it: two
* packages may both declare a `Resources`, and they must not match.
*/
const packageCache = new Map();
function packageOf(fileName) {
if (/\/lib\.[\w.]+\.d\.ts$/.test(fileName)) return "lib";
// pnpm nests `node_modules/.pnpm/<pkg>@<ver>/node_modules/<pkg>/…`: the LAST segment names the package.
const segments = [...fileName.matchAll(/node_modules\/(@[^/]+\/[^/]+|[^/@.][^/]*)/g)];
if (segments.length > 0) return segments[segments.length - 1][1];
let dir = path.dirname(fileName);
for (;;) {
if (packageCache.has(dir)) return packageCache.get(dir);
const pkg = path.join(dir, "package.json");
if (fs.existsSync(pkg)) {
const name = JSON.parse(fs.readFileSync(pkg, "utf8")).name;
packageCache.set(dir, name);
return name;
}
const parent = path.dirname(dir);
if (parent === dir) return "?";
dir = parent;
}
}
/** `<package>#<name>`: an opaque identity, never a bare name. */
const opaqueId = (name, fileName) => `${packageOf(fileName)}#${name}`;
/**
* The identity of an `Opaque<"Name", T>`: the name, qualified by the package declaring
* T (else the package writing the marker) — so the same word in two packages is two
* identities.
*/
function opaqueName(type, atNode) {
const prop = type.getProperty("__opaque");
if (!prop) return null;
const t = checker.getNonNullableType(checker.getTypeOfSymbol(prop));
if (!t.isStringLiteral()) return null;
const parts = type.isIntersection()
? type.types.filter((x) => !x.getProperty("__opaque") || x.getProperties().length > 1)
: [type];
const declaring = parts
.map((x) => (x.aliasSymbol ?? x.getSymbol())?.declarations?.[0]?.getSourceFile()?.fileName)
.find((f) => f !== undefined);
return opaqueId(t.value, declaring ?? atNode.getSourceFile().fileName);
}
/** TypeExpr for any type in a signature position. */
function exprOf(type, atNode, stack = []) {
notData = "";
const f = type.getFlags();
if (f & ts.TypeFlags.Void) return { void: true };
const opaque = opaqueName(type, atNode);
if (opaque !== null) return { opaque };
const symbol = type.getSymbol();
const name = symbol?.getName();
if (name === "Promise" || name === "PromiseLike") {
return { promise: exprOf(checker.getTypeArguments(type)[0], atNode, stack) };
}
if (name === "AsyncIterable" || name === "AsyncIterableIterator" || name === "AsyncGenerator") {
const [t, r] = checker.getTypeArguments(type);
const out = { stream: exprOf(t, atNode, stack) };
if (
name === "AsyncGenerator" &&
r &&
!(r.getFlags() & (ts.TypeFlags.Void | ts.TypeFlags.Any | ts.TypeFlags.Unknown))
) {
out.returns = exprOf(r, atNode, stack);
}
return out;
}
const data = dataOf(type, atNode, stack);
if (data !== null) return { data };
if (type.isUnion()) {
// T | null | undefined around a non-data T: `undefined` is absence (`maybe`), `null`
// is a value and stays a member.
const rest = type.types.filter(
(t) => !(t.getFlags() & (ts.TypeFlags.Null | ts.TypeFlags.Undefined)),
);
const absent = type.types.some((t) => (t.getFlags() & ts.TypeFlags.Undefined) !== 0);
if (rest.length > 0) {
const members = rest.map((t) => exprOf(t, atNode, stack));
if (hasNull(type)) members.push({ data: "null" });
const inner = members.length === 1 ? members[0] : { oneOf: members };
return absent ? { maybe: inner } : inner;
}
return fail(
atNode,
`union '${checker.typeToString(type)}' mixes data with a function, promise or interface (${notData})`,
);
}
const sigs = type.getCallSignatures();
if (sigs.length === 1 && type.getProperties().length === 0) {
return { fn: sigOf(sigs[0], atNode, stack) };
}
if (f & ts.TypeFlags.Object) {
if (checker.isArrayType(type)) {
return { array: exprOf(checker.getTypeArguments(type)[0], atNode, stack) };
}
if (checker.isTupleType(type)) {
return fail(
atNode,
`tuple '${checker.typeToString(type)}' holds a non-data element (${notData})`,
);
}
// A mapped or anonymous type (`Pick<…>`, `Record<…>`, an inline `{…}`) has the lib's
// `__type` symbol; it is a shape, not a host object. With methods and a name (a
// `type X = Pick<…>` alias) it is an interface keyed by the alias; otherwise its
// members are projected in place.
const anonymous = name === "__type" || name === "__object";
if (anonymous && type.aliasSymbol && hasMethods(type, atNode)) {
const aliasDecl = type.aliasSymbol.declarations?.[0];
if (aliasDecl) return { iface: keyOf(type.aliasSymbol, aliasDecl) };
}
if (!anonymous && isHostDeclared(symbol))
return { opaque: opaqueId(name, symbol.declarations[0].getSourceFile().fileName) };
// A plain object shape some member of which is not data (a Buffer field, a callback
// property): structured, compared member by member.
if (
!hasMethods(type, atNode) &&
!(symbol && symbol.flags & ts.SymbolFlags.Class) &&
!stack.includes(type)
) {
const members = {};
const optional = [];
for (const prop of type.getProperties()) {
const t = checker.getTypeOfSymbolAtLocation(prop, atNode);
const opt = (prop.flags & ts.SymbolFlags.Optional) !== 0 || hasUndefined(t);
if (opt) optional.push(prop.getName());
const { type: kept, nullable } = opt ? sansUndefined(t) : { type: t, nullable: false };
const e = exprOf(kept, prop.valueDeclaration ?? atNode, [...stack, type]);
members[prop.getName()] = nullable ? exprOrNull(e) : e;
}
return optional.length > 0 ? { object: members, optional } : { object: members };
}
if (symbol && symbol.flags & ts.SymbolFlags.Class && !isIfaceClass(symbol)) {
return fail(atNode, `class '${name}' in a signature: wrap it as Opaque<"${name}">`);
}
// Inside a component's own surface, an interface with methods that is not an
// interface class is a host object of that class's world, compared by name — the
// component does not publish its dependencies' types as contracts.
if (lenient && hasMethods(type, atNode) && !isIfaceClass(symbol))
return {
opaque: opaqueId(
name,
symbol?.declarations?.[0]?.getSourceFile()?.fileName ?? atNode.getSourceFile().fileName,
),
};
if (hasMethods(type, atNode) || isIfaceClass(symbol)) {
const decl = symbol?.declarations?.find(
(d) =>
ts.isInterfaceDeclaration(d) ||
ts.isTypeAliasDeclaration(d) ||
ts.isClassDeclaration(d),
);
if (!decl)
return fail(atNode, `anonymous object with methods; declare it as an exported interface`);
return { iface: keyOf(symbol, decl) };
}
}
return fail(atNode, `unsupported type '${checker.typeToString(type)}' (${notData})`);
}
function sigOf(signature, atNode, stack) {
if (signature.getTypeParameters()?.length) {
warnings.push(
`${where(atNode)}: generic method — its type parameters are erased to unknown in the contract`,
);
}
const params = signature.getParameters().map((p) => {
const decl = p.valueDeclaration;
if (decl && ts.isParameter(decl) && decl.dotDotDotToken) {
fail(decl, "rest parameters are not allowed on an interface");
}
const t = checker.getTypeOfSymbolAtLocation(p, atNode);
const optional =
decl &&
ts.isParameter(decl) &&
(decl.questionToken !== undefined || decl.initializer !== undefined);
const { type: kept, nullable } = optional ? sansUndefined(t) : { type: t, nullable: false };
let expr = exprOf(kept, decl ?? atNode, stack);
if (nullable) expr = exprOrNull(expr);
if (optional) {
if (!("data" in expr)) return { maybe: expr };
expr.data =
typeof expr.data === "string" && !expr.data.includes("undefined")
? `${expr.data}|undefined`
: [expr.data, "|", "undefined"];
}
return expr;
});
return { params, returns: exprOf(signature.getReturnType(), atNode, stack) };
}
/** True while a component member is being projected (see `tolerant` in ifaceOf). */
let lenient = false;
const LIFECYCLE = new Set(["setup", "park", "migrations"]);
/** A member of a component class that is not part of its interface. */
const isHiddenMember = (prop) => {
const d = prop.valueDeclaration;
if (!d) return false;
const flags = ts.getCombinedModifierFlags(d);
if (flags & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected | ts.ModifierFlags.Static))
return true;
if (ts.isPrivateIdentifier(d.name)) return true;
if (LIFECYCLE.has(prop.getName())) return true;
return ["Use", "Provide", "Bind"].some((n) => decoratorCall(d, n));
};
function ifaceOf(symbol, decl) {
const type = checker.getDeclaredTypeOfSymbol(symbol);
const key = componentKeyBySymbol.get(symbol);
const component = key !== undefined;
const methods = {};
const fields = {};
// A component's interface is whatever of its public surface projects; a member that
// does not is opaque (compared by name only) with a warning, since a consumer that
// never names it loses nothing and one that does will see the mismatch.
const tolerant = (prop, project) => {
if (!component) return project();
const mark = errors.length;
lenient = true;
let out;
try {
out = project();
} finally {
lenient = false;
}
if (errors.length === mark) return out;
const why = errors.splice(mark).map((e) => e.slice(e.indexOf(": ") + 2));
warnings.push(
`${where(prop.valueDeclaration ?? decl)}: component member '${prop.getName()}' is opaque in the contract (${why.join("; ")})`,
);
return {
opaque: opaqueId(`${symbol.getName()}.${prop.getName()}`, decl.getSourceFile().fileName),
};
};
for (const prop of type.getProperties()) {
if (component && isHiddenMember(prop)) continue;
if (!isMethodLike(prop, decl)) {
const t = checker.getTypeOfSymbolAtLocation(prop, decl);
const optional = (prop.flags & ts.SymbolFlags.Optional) !== 0 || hasUndefined(t);
const { type: kept, nullable } = optional ? sansUndefined(t) : { type: t, nullable: false };
const projected = tolerant(prop, () => exprOf(kept, prop.valueDeclaration ?? decl, [type]));
const expr = nullable ? exprOrNull(projected) : projected;
// An optional field may be absent on the instance; the consumer sees a `maybe`.
fields[prop.getName()] = optional && !("maybe" in expr) ? { maybe: expr } : expr;
continue;
}
const t = checker.getTypeOfSymbolAtLocation(prop, decl);
const sigs = t.getCallSignatures();
if (sigs.length !== 1) {
tolerant(prop, () =>
fail(
prop.valueDeclaration ?? decl,
`method '${prop.getName()}' has ${sigs.length} overloads; one signature per method`,
),
);
continue;
}
const sig = tolerant(prop, () => sigOf(sigs[0], prop.valueDeclaration ?? decl, [type]));
if ("opaque" in sig) fields[prop.getName()] = sig;
else methods[prop.getName()] = sig;
}
const out = { name: component ? key.slice(key.indexOf("#") + 1) : symbol.getName(), methods };
if (Object.keys(fields).length > 0) out.fields = fields;
out.slots = {};
return out;
}
function slotsOf(symbol, decl) {
const type = checker.getDeclaredTypeOfSymbol(symbol);
const slots = {};
for (const prop of type.getProperties()) {
const t = checker.getTypeOfSymbolAtLocation(prop, decl);
const at = prop.valueDeclaration ?? decl;
const isSlot =
t.getSymbol()?.getName() === "Slot" && t.getProperty("data") && t.getProperty("code");
if (isSlot) {
const data = dataOf(checker.getTypeOfSymbol(t.getProperty("data")), at, []);
if (data === null) {
fail(at, `slot '${prop.getName()}': the data half must be a data type`);
continue;
}
const codeType = checker.getTypeOfSymbol(t.getProperty("code"));
const slot = { data };
if (!(codeType.getFlags() & ts.TypeFlags.Never)) slot.code = exprOf(codeType, at, []);
slots[prop.getName()] = slot;
} else {
const data = dataOf(t, at, []);
if (data === null) {
fail(
at,
`slot '${prop.getName()}' must be a data type, or Slot<Data, Code> for a code half`,
);
continue;
}
slots[prop.getName()] = { data };
}
}
return slots;
}
// Every exported interface class (either spelling) anywhere in the package is
// a table entry, and an exported `<Name>Slots` interface beside one names its slots;
// everything else is a data type, reached only through references.
const slotCompanions = [];
for (const sf of sourceFiles) {
const moduleSymbol = checker.getSymbolAtLocation(sf);
if (!moduleSymbol) continue;
for (const exp of checker.getExportsOfModule(moduleSymbol)) {
// A re-export (`export type { X } from "..."`) is an alias; follow it to the declaration.
const symbol = exp.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exp) : exp;
const decl = symbol.declarations?.[0];
if (!decl) continue;
const name = symbol.getName();
if (ts.isInterfaceDeclaration(decl) && name.endsWith("Slots")) {
slotCompanions.push({ symbol, decl, owner: name.slice(0, -"Slots".length), sf });
continue;
}
if (!isInterfaceClassDecl(decl)) continue;
checkDecoratedInterface(decl, path.relative(process.cwd(), sf.fileName));
keyOf(symbol, decl, sf);
}
}
for (const [sym, { node }] of moduleClasses) if (componentKeyBySymbol.has(sym)) keyOf(sym, node);
while (pending.length > 0) {
const { symbol, decl, key } = pending.shift();
table[key] = ifaceOf(symbol, decl);
}
const ifaceKeyOfType = (typeNode, file) => {
const sym0 =
typeNode && ts.isTypeReferenceNode(typeNode)
? checker.getSymbolAtLocation(typeNode.typeName)
: undefined;
const sym = sym0 && sym0.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(sym0) : sym0;
if (sym && componentKeyBySymbol.has(sym)) return componentKeyBySymbol.get(sym);
const decl = sym?.declarations?.find((d) => isInterfaceClassDecl(d));
if (!decl) {
errors.push(
`${file}: a @Use/@Provide field's type must be a @Component class or an interface class (@Interface(), or extends Interface<…>()) (got '${typeNode?.getText() ?? "?"}')`,
);
return "?";
}
return `${moduleNameOf(decl.getSourceFile().fileName)}#${sym.getName()}`;
};
/** The component a bare `@Use()` field is wired to: the one its type names, if any. */
const componentOfType = (typeNode) => {
const sym0 =
typeNode && ts.isTypeReferenceNode(typeNode)
? checker.getSymbolAtLocation(typeNode.typeName)
: undefined;
const sym = sym0 && sym0.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(sym0) : sym0;
return sym && componentKeyBySymbol.has(sym) ? moduleNameBySymbol.get(sym) : undefined;
};
for (const [sym, { node, meta, file, kind, className }] of moduleClasses) {
const m = {
name: meta.name,
kind,
requires: {},
provides: {},
contributes: meta.contributes ?? {},
children: [],
};
if (meta.context !== undefined) m.context = meta.context;
if (kind === "component") {
m.provides[className] = componentKeyBySymbol.get(sym);
// `implements Users`: the component declares the mechanism it implements; the
// provision is the same instance under the interface's name.
for (const clause of node.heritageClauses ?? []) {
if (clause.token !== ts.SyntaxKind.ImplementsKeyword) continue;
for (const t of clause.types) {
const s0 = checker.getSymbolAtLocation(t.expression);
const isym = s0 && s0.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(s0) : s0;
const idecl = isym?.declarations?.find((d) => isInterfaceClassDecl(d));
if (!idecl) {
errors.push(
`${file}: ${className} implements '${t.getText()}', which is not an interface class (extends Interface<…>())`,
);
continue;
}
m.provides[isym.getName()] = keyOf(isym, idecl);
}
}
if (meta.children !== undefined)
errors.push(`${file}: a @Component has no children — it exports itself`);
}
for (const member of node.members) {
if (!ts.isPropertyDeclaration(member) || !member.name) continue;
const field = ts.isIdentifier(member.name)
? member.name.text
: ts.isStringLiteral(member.name)
? member.name.text
: null;
if (field === null) continue;
const use = decoratorCall(member, "Use");
if (use) {
const req = { iface: ifaceKeyOfType(member.type, file) };
if (componentOfType(member.type) !== undefined)
implementationDeps.push(`${m.name}.${field} → ${member.type.getText()}`);
if (use.arguments.length > 0) {
const ref = refLiteral(use.arguments[0], file);
const fromName = moduleNameBySymbol.get(ref?.$id);
if (fromName === undefined)
errors.push(
`${file}: @Use(${use.arguments[0].getText()}) on '${field}': not a @Module class`,
);
req.from = fromName ?? "?";
} else {
const from = componentOfType(member.type);
if (from !== undefined) req.from = from;
}
m.requires[field] = req;
}
if (decoratorCall(member, "Provide")) {
if (kind === "component")
errors.push(`${file}: @Provide on a @Component: a component exports only itself`);
m.provides[field] = ifaceKeyOfType(member.type, file);
}
}
// `exports: [Users, …]`: the module forwards a child's provision under that interface.
for (const exp of meta.exports ?? []) {
const isym = exp?.$id;
const idecl = isym?.declarations?.find((d) => isInterfaceClassDecl(d));
if (!idecl) {
errors.push(
`${file}: exports: an entry is not an interface class (extends Interface<…>())`,
);
continue;
}
m.provides[isym.getName()] = keyOf(isym, idecl);
(m.exports ??= []).push(isym.getName());
}
for (const child of meta.children ?? []) {
const childName = moduleNameBySymbol.get(child?.$id);
if (childName === undefined)
errors.push(`${file}: children: an entry is not a @Module or @Component class`);
m.children.push(childName ?? "?");
}
if (manifests[m.name]) errors.push(`${file}: module '${m.name}' is defined twice`);
manifests[m.name] = m;
}
// Wire every requirement that names no module to the module that will provide it —
// the one visible provider declaring that very interface (siblings, or an ancestor's
// siblings; never an ancestor). Recorded as `from`, so the table says which MODULE a
// node depends on, not only which interface, and the booter follows the same choice.
{
const childOf = new Map();
for (const m of Object.values(manifests))
for (const c of m.children) if (c !== "*") childOf.set(c, m.name);
const visibleOf = (name) => {
const out = new Set();
const ancestors = new Set();
let cur = name;
for (;;) {
const parent = childOf.get(cur);
if (parent === undefined) break;
ancestors.add(parent);
for (const s of manifests[parent].children) if (s !== "*" && s !== name) out.add(s);
cur = parent;
}
for (const a of ancestors) out.delete(a); // an ancestor's exports face outward, not down
return out;
};
for (const m of Object.values(manifests)) {
if (!childOf.has(m.name)) continue; // roots and extension modules: the booter decides
const visible = visibleOf(m.name);
for (const [alias, req] of Object.entries(m.requires)) {
if (req.from !== undefined) continue;
const declaring = [...visible].filter((v) =>
Object.values(manifests[v]?.provides ?? {}).includes(req.iface),
);
if (declaring.length === 1) req.from = declaring[0];
}
}
}
for (const { symbol, decl, owner, sf } of slotCompanions) {
const ownerExp = checker
.getExportsOfModule(checker.getSymbolAtLocation(sf))
.find((e) => e.getName() === owner);
const ownerSym =
ownerExp &&
(ownerExp.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(ownerExp) : ownerExp);
const key = ownerSym && keys.get(ownerSym);
if (!key || !table[key]) {
errors.push(
`${where(decl)}: '${symbol.getName()}' has no interface '${owner}' in the same module to attach to`,
);
continue;
}
table[key].slots = slotsOf(symbol, decl);
}
}
for (const w of warnings) console.warn(`gen-ifaces: warning: ${w}`);
// A node depends on mechanisms, never on implementations: a `@Use` field typed by a
// @Component class is refused. The component implements an interface class; require that.
for (const dep of implementationDeps)
errors.push(`${dep}: a @Use field names an implementation; require the interface it implements`);
if (errors.length > 0) {
for (const e of errors) console.error(`gen-ifaces: error: ${e}`);
process.exit(1);
}
const sortKeys = (o) =>
Object.fromEntries(
Object.keys(o)
.sort()
.map((k) => [k, o[k]]),
);
// The table's identity: a sha256 over its canonical content, so two builds can tell at
// a glance whether they agree on every interface and manifest (the page CI publishes
// carries it, and a pre-push check compares it). The hash is not part of what it hashes.
const body = {
ifaces: sortKeys(table),
types: sortKeys(types),
modules: sortKeys(manifests),
...(pluginDecl === null ? {} : { plugin: pluginDecl }),
};
const hash = createHash("sha256").update(JSON.stringify(body)).digest("hex");
const text = `${JSON.stringify({ hash, ...body }, null, 1)}\n`;
const existing = fs.existsSync(outPath) ? fs.readFileSync(outPath, "utf8") : null;
if (checkOnly) {
if (existing !== text) {
console.error(`gen-ifaces: ${outPath} is stale — run \`pnpm gen:ifaces\``);
process.exit(1);
}
console.log(
`gen-ifaces: ${outPath} is up to date (${Object.keys(table).length} interfaces, ${Object.keys(types).length} types)`,
);
} else if (existing !== text) {
fs.mkdirSync(path.dirname(outPath), { recursive: true });
fs.writeFileSync(outPath, text);
console.log(
`gen-ifaces: wrote ${outPath} (${Object.keys(table).length} interfaces, ${Object.keys(types).length} types)`,
);
} else {
console.log(
`gen-ifaces: ${outPath} unchanged (${Object.keys(table).length} interfaces, ${Object.keys(types).length} types)`,
);
}