@fougere/compiler 0.11.0-alpha.0 → 0.12.1-alpha.0

package/src/scan/handler-parser.ts

@@ -4,174 +4,10 @@ import { type ErrorCode } from '@fougere/core';
 
 import type ts from '@typescript/typescript6';
 import { refusalsIn } from './refusals.js';
+import { loadTS, getTS, checkedSourceOf, sourceOf, findDefaultClass, projectOf } from './TypeProgram.js';
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { join, dirname, resolve as resolvePath } from 'node:path';
 
-/** Lazy-loaded TypeScript module — avoids bundling the 9MB compiler. */
-let _ts: typeof ts | undefined;
-async function loadTS(): Promise<typeof ts> {
-  if (!_ts) _ts = (await import('@typescript/typescript6')).default;
-  return _ts;
-}
-function getTS(): typeof ts {
-  if (!_ts) throw new Error('TypeScript not loaded — call an async parse function first');
-  return _ts;
-}
-
-interface TypeProject {
-  roots: Set<string>;
-  options: ts.CompilerOptions;
-  program: ts.Program;
-}
-
-/** One checked program per project/configuration during a scan. */
-const typeProjects = new Map<string, TypeProject>();
-const compilerProjects = new Map<string, { key: string; roots: string[]; options: ts.CompilerOptions }>();
-
-/** What survives a run. */
-const sourceFiles = new Map<string, { mtime: number; file: ts.SourceFile }>();
-const retained = new Map<string, { host: ts.CompilerHost; program: ts.Program }>();
-
-export function resetTypePrograms(): void {
-  typeProjects.clear();
-  compilerProjects.clear();
-}
-
-function keptHost(key: string, options: ts.CompilerOptions): ts.CompilerHost {
-  const cached = retained.get(key);
-  if (cached) return cached.host;
-  const typescript = getTS();
-  const base = typescript.createCompilerHost(options);
-  const host: ts.CompilerHost = {
-    ...base,
-    getSourceFile(fileName, languageVersion, onError, shouldCreate) {
-      const path = resolvePath(fileName);
-      const mtime = statSync(path, { throwIfNoEntry: false })?.mtimeMs ?? -1;
-      const cached = sourceFiles.get(path);
-      if (cached && cached.mtime === mtime) return cached.file;
-      const file = base.getSourceFile(fileName, languageVersion, onError, shouldCreate);
-      if (file && mtime >= 0) sourceFiles.set(path, { mtime, file });
-      return file;
-    },
-  };
-  retained.set(key, { host, program: undefined as unknown as ts.Program });
-  return host;
-}
-
-function builtProgram(key: string, roots: readonly string[], options: ts.CompilerOptions): ts.Program {
-  const typescript = getTS();
-  const host = keptHost(key, options);
-  const program = typescript.createProgram({
-    rootNames: [...roots], options, host, oldProgram: retained.get(key)?.program,
-  });
-  retained.set(key, { host, program });
-  return program;
-}
-
-function compilerProjectOf(filePath: string, projectRoot?: string): { key: string; roots: string[]; options: ts.CompilerOptions } {
-  const typescript = getTS();
-  const absolute = resolvePath(filePath);
-  const configPath = typescript.findConfigFile(dirname(absolute), typescript.sys.fileExists);
-
-  if (configPath) {
-    const key = `${configPath}:${projectRoot ?? ''}`;
-    const cached = compilerProjects.get(key);
-    if (cached) return cached;
-
-    const read = typescript.readConfigFile(configPath, typescript.sys.readFile);
-    if (read.error) throw new Error(typescript.flattenDiagnosticMessageText(read.error.messageText, '\n'));
-    const parsed = typescript.parseJsonConfigFileContent(read.config, typescript.sys, dirname(configPath));
-    const configured = {
-      key,
-      // Compiler options belong to the project; its entire include glob does not belong
-      // to this scan. Each declaration inspected below becomes a root and TypeScript
-      // follows its imports. Seeding the monorepo here made a one-file scan compile it all.
-      roots: [],
-      // Handlers may be authored or emitted as JavaScript. They still need to belong to
-      // the checked program so constructor parsing does not fail on the first cold scan.
-      options: { ...parsed.options, allowJs: true, noEmit: true },
-    };
-    compilerProjects.set(key, configured);
-    return configured;
-  }
-
-  const key = projectRoot ?? dirname(absolute);
-  const cached = compilerProjects.get(key);
-  if (cached) return cached;
-  const configured = {
-    key,
-    roots: [],
-    options: {
-      target: typescript.ScriptTarget.ES2022,
-      module: typescript.ModuleKind.Node16,
-      moduleResolution: typescript.ModuleResolutionKind.Node16,
-      strict: true,
-      skipLibCheck: true,
-      allowJs: true,
-      noEmit: true,
-    },
-  };
-  compilerProjects.set(key, configured);
-  return configured;
-}
-
-/** Declare every file a run will read, so one program covers it. */
-export async function seedTypeProgram(filePaths: readonly string[], projectRoot?: string): Promise<void> {
-  const typescript = await loadTS();
-  const grouped = new Map<string, { options: ts.CompilerOptions; paths: string[] }>();
-
-  for (const filePath of filePaths) {
-    const absolute = resolvePath(filePath);
-    const typescript = getTS();
-  const configured = compilerProjectOf(absolute, projectRoot);
-    const group = grouped.get(configured.key) ?? { options: configured.options, paths: [] };
-    group.paths.push(absolute);
-    grouped.set(configured.key, group);
-  }
-
-  for (const [key, { options, paths }] of grouped) {
-    const roots = new Set(typeProjects.get(key)?.roots ?? []);
-    for (const path of paths) roots.add(path);
-    typeProjects.set(key, { roots, options, program: builtProgram(key, [...roots], options) });
-  }
-}
-
-/** The program a file belongs to, built once and widened as more files are asked for. */
-function projectOf(filePath: string, projectRoot?: string): { program: ts.Program; absolute: string } {
-  const absolute = resolvePath(filePath);
-  const configured = compilerProjectOf(absolute, projectRoot);
-  let project = typeProjects.get(configured.key);
-
-  if (!project) {
-    // `path.resolve` is variadic, so handing it directly to `map` also passed the
-    // index and the whole roots array as path segments. A fixture without a warm scan
-    // cache exposed that first-run-only failure.
-    const roots = new Set(configured.roots.map((root) => resolvePath(root)));
-    roots.add(absolute);
-    const program = builtProgram(configured.key, [...roots], configured.options);
-    project = { roots, options: configured.options, program };
-    typeProjects.set(configured.key, project);
-  } else if (!project.roots.has(absolute)) {
-    project.roots.add(absolute);
-    project.program = builtProgram(configured.key, [...project.roots], project.options);
-  }
-
-  return { program: project.program, absolute };
-}
-
-function checkedSourceOf(filePath: string, projectRoot?: string): { source: ts.SourceFile; checker: ts.TypeChecker } {
-  const { program, absolute } = projectOf(filePath, projectRoot);
-  const source = program.getSourceFile(absolute);
-  if (!source) throw new Error(`TypeScript did not include '${absolute}' in its program.`);
-
-  return { source, checker: program.getTypeChecker() };
-}
-
-/** A file, opened. Five places read and parsed one, each spelling the same two calls. */
-function sourceOf(filePath: string): ts.SourceFile {
-  const ts = getTS();
-  return ts.createSourceFile(filePath, readFileSync(filePath, 'utf-8'), ts.ScriptTarget.Latest, true);
-}
 
 /** One declared parameter — a constructor's and a method's are read the same way. */
 function parsedParam(param: ts.ParameterDeclaration, source: ts.SourceFile, checker?: ts.TypeChecker): Param {
@@ -194,75 +30,81 @@ function parseTypeNode(node: ts.TypeNode, source: ts.SourceFile, checker?: ts.Ty
   const ts = getTS();
   const raw = node.getText(source);
 
-  if (checker) {
-    // `Fact<T>` and `Pipe<T>` are deliberately transparent in TypeScript (`= T`), because
-    // both receive the payload itself — one reads it, the other answers the value every
-    // reader then gets. The checker erases the marker, while the binding plan still needs
-    // it to tell either from an ordinary body.
-    if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName) && ANNOUNCED.has(node.typeName.text)) {
-      return {
-        raw,
-        name: node.typeName.text,
-        generics: node.typeArguments?.map((arg) => parseTypeNode(arg, source, checker)) ?? [],
-      };
-    }
-    return parseCheckedType(checker.getTypeFromTypeNode(node), raw, checker);
+  if (checker) return announced(node, source, checker) ?? parseCheckedType(checker.getTypeFromTypeNode(node), raw, checker);
+
+  if (ts.isUnionTypeNode(node)) return fromUnion(node, source, raw);
+  if (ts.isTypeReferenceNode(node)) return fromReference(node, source, raw);
+  if (ts.isArrayTypeNode(node)) {
+    const inner = parseTypeNode(node.elementType, source);
+
+    return { ...inner, array: true, arrayDepth: (inner.arrayDepth ?? 0) + 1, raw };
   }
 
-  // Union types — extract nullable, strip Promise
-  if (ts.isUnionTypeNode(node)) {
-    const nonNull = node.types.filter(
-      (t) => !(ts.isLiteralTypeNode(t) && t.literal.kind === ts.SyntaxKind.NullKeyword)
-        && !(t.kind === ts.SyntaxKind.UndefinedKeyword)
-        && !(t.kind === ts.SyntaxKind.VoidKeyword)
-        && !(t.kind === ts.SyntaxKind.NullKeyword),
-    );
-    const nullable = node.types.some((t) =>
-      (ts.isLiteralTypeNode(t) && t.literal.kind === ts.SyntaxKind.NullKeyword)
-      || t.kind === ts.SyntaxKind.NullKeyword,
-    );
-    const undefinable = node.types.some((t) =>
-      t.kind === ts.SyntaxKind.UndefinedKeyword || t.kind === ts.SyntaxKind.VoidKeyword,
-    );
-    if (nonNull.length === 1) {
-      const inner = parseTypeNode(nonNull[0], source);
-      return { ...inner, nullable: nullable || inner.nullable, undefined: undefinable || inner.undefined, raw };
-    }
-    return { raw, name: raw, nullable, undefined: undefinable };
+  return fromKeyword(node, raw) ?? { raw, name: raw };
+}
+
+/**
+ * `Fact<T>` and `Pipe<T>` are deliberately transparent in TypeScript (`= T`), because both
+ * receive the payload itself — one reads it, the other answers the value every reader then gets.
+ * The checker erases the marker, while the binding plan still needs it to tell either from an
+ * ordinary body.
+ */
+function announced(node: ts.TypeNode, source: ts.SourceFile, checker: ts.TypeChecker): TypeRef | undefined {
+  const ts = getTS();
+  if (!ts.isTypeReferenceNode(node) || !ts.isIdentifier(node.typeName) || !ANNOUNCED.has(node.typeName.text)) {
+    return undefined;
   }
 
-  // Promise<T> — unwrap
-  if (ts.isTypeReferenceNode(node)) {
-    const typeName = node.typeName.getText(source);
+  return {
+    raw: node.getText(source),
+    name: node.typeName.text,
+    generics: node.typeArguments?.map((arg) => parseTypeNode(arg, source, checker)) ?? [],
+  };
+}
 
-    if (typeName === 'Promise' && node.typeArguments?.length === 1) {
-      const inner = parseTypeNode(node.typeArguments[0], source);
-      return { ...inner, promise: true, raw };
-    }
+/** `T | null`, `T | undefined`, `T | void` — the absence is an axis, the rest is the type. */
+function fromUnion(node: ts.UnionTypeNode, source: ts.SourceFile, raw: string): TypeRef {
+  const ts = getTS();
+  const isNull = (one: ts.TypeNode) =>
+    (ts.isLiteralTypeNode(one) && one.literal.kind === ts.SyntaxKind.NullKeyword)
+    || one.kind === ts.SyntaxKind.NullKeyword;
+  const isAbsent = (one: ts.TypeNode) =>
+    one.kind === ts.SyntaxKind.UndefinedKeyword || one.kind === ts.SyntaxKind.VoidKeyword;
 
-    // Array<T>
-    if (typeName === 'Array' && node.typeArguments?.length === 1) {
-      const inner = parseTypeNode(node.typeArguments[0], source);
-      return { ...inner, array: true, arrayDepth: (inner.arrayDepth ?? 0) + 1, raw };
-    }
+  const nullable = node.types.some(isNull);
+  const undefinable = node.types.some(isAbsent);
+  const nonNull = node.types.filter((one) => !isNull(one) && !isAbsent(one));
 
-    // Generic type: Foo<Bar, Baz>
-    if (node.typeArguments && node.typeArguments.length > 0) {
-      const generics = node.typeArguments.map((arg) => parseTypeNode(arg, source));
-      return { raw, name: typeName, generics };
-    }
+  if (nonNull.length !== 1) return { raw, name: raw, nullable, undefined: undefinable };
+
+  const inner = parseTypeNode(nonNull[0]!, source);
+
+  return { ...inner, nullable: nullable || inner.nullable, undefined: undefinable || inner.undefined, raw };
+}
 
-    // Simple type reference: Post, string, etc.
-    return { raw, name: typeName };
+/** `Promise<T>` and `Array<T>` are carriers; anything else keeps its name and its generics. */
+function fromReference(node: ts.TypeReferenceNode, source: ts.SourceFile, raw: string): TypeRef {
+  const typeName = node.typeName.getText(source);
+
+  if (typeName === 'Promise' && node.typeArguments?.length === 1) {
+    return { ...parseTypeNode(node.typeArguments[0]!, source), promise: true, raw };
   }
 
-  // T[]
-  if (ts.isArrayTypeNode(node)) {
-    const inner = parseTypeNode(node.elementType, source);
+  if (typeName === 'Array' && node.typeArguments?.length === 1) {
+    const inner = parseTypeNode(node.typeArguments[0]!, source);
+
     return { ...inner, array: true, arrayDepth: (inner.arrayDepth ?? 0) + 1, raw };
   }
 
-  // Keyword types: string, number, boolean, void
+  if (node.typeArguments && node.typeArguments.length > 0) {
+    return { raw, name: typeName, generics: node.typeArguments.map((arg) => parseTypeNode(arg, source)) };
+  }
+
+  return { raw, name: typeName };
+}
+
+function fromKeyword(node: ts.TypeNode, raw: string): TypeRef | undefined {
+  const ts = getTS();
   switch (node.kind) {
     case ts.SyntaxKind.StringKeyword: return { raw, name: 'string' };
     case ts.SyntaxKind.NumberKeyword: return { raw, name: 'number' };
@@ -272,15 +114,8 @@ function parseTypeNode(node: ts.TypeNode, source: ts.SourceFile, checker?: ts.Ty
     case ts.SyntaxKind.NullKeyword: return { raw, name: 'null', nullable: true };
     case ts.SyntaxKind.AnyKeyword: return { raw, name: 'any' };
     case ts.SyntaxKind.UnknownKeyword: return { raw, name: 'unknown' };
+    default: return undefined;
   }
-
-  // Object literal type: { title: string; limit: number }
-  if (ts.isTypeLiteralNode(node)) {
-    return { raw, name: raw };
-  }
-
-  // Fallback
-  return { raw, name: raw };
 }
 
 function meaningfulSymbolName(type: ts.Type, checker: ts.TypeChecker): string {
@@ -305,41 +140,10 @@ function parseCheckedType(type: ts.Type, raw: string, checker: ts.TypeChecker, d
   const typescript = getTS();
   if (depth > 12) return { raw, name: checker.typeToString(type) };
 
-  if (type.isUnion()) {
-    const nullable = type.types.some((member) => (member.flags & typescript.TypeFlags.Null) !== 0);
-    const undefinable = type.types.some((member) =>
-      (member.flags & (typescript.TypeFlags.Undefined | typescript.TypeFlags.Void)) !== 0,
-    );
-    const members = type.types.filter((member) =>
-      (member.flags & (typescript.TypeFlags.Null | typescript.TypeFlags.Undefined | typescript.TypeFlags.Void)) === 0,
-    );
-    // The checker represents the `boolean` keyword itself as `false | true`. Preserve
-    // the primitive vocabulary consumed by binding and presenter metadata.
-    if (
-      members.length > 0
-      && members.every((member) => (member.flags & typescript.TypeFlags.BooleanLiteral) !== 0)
-    ) {
-      return { raw, name: 'boolean', nullable, undefined: undefinable };
-    }
-    if (members.length === 1) {
-      const inner = parseCheckedType(members[0]!, raw, checker, depth + 1);
-      return {
-        ...inner,
-        raw,
-        nullable: nullable || inner.nullable,
-        undefined: undefinable || inner.undefined,
-      };
-    }
-    return {
-      raw,
-      name: members.map((member) => meaningfulSymbolName(member, checker)).join(' | ') || raw,
-      nullable,
-      undefined: undefinable,
-    };
-  }
+  if (type.isUnion()) return fromCheckedUnion(type, raw, checker, depth);
 
-  // Present at runtime in the supported compiler versions, but intentionally omitted
-  // from TypeScript's public TypeChecker declaration.
+  // Present at runtime in the supported compiler versions, but intentionally omitted from
+  // TypeScript's public TypeChecker declaration.
   const promised = (checker as ts.TypeChecker & {
     getPromisedTypeOfPromise(candidate: ts.Type): ts.Type | undefined;
   }).getPromisedTypeOfPromise(type);
@@ -348,24 +152,19 @@ function parseCheckedType(type: ts.Type, raw: string, checker: ts.TypeChecker, d
   if (checker.isArrayType(type)) {
     const [element] = checker.getTypeArguments(type as ts.TypeReference);
     const inner = element ? parseCheckedType(element, raw, checker, depth + 1) : { raw, name: 'unknown' };
+
     return { ...inner, raw, array: true, arrayDepth: (inner.arrayDepth ?? 0) + 1 };
   }
 
-  if ((type.flags & typescript.TypeFlags.StringLike) !== 0) return { raw, name: 'string' };
-  if ((type.flags & typescript.TypeFlags.NumberLike) !== 0) return { raw, name: 'number' };
-  if ((type.flags & typescript.TypeFlags.BooleanLike) !== 0) return { raw, name: 'boolean' };
-  if ((type.flags & typescript.TypeFlags.Void) !== 0) return { raw, name: 'void', undefined: true };
-  if ((type.flags & typescript.TypeFlags.Undefined) !== 0) return { raw, name: 'undefined', undefined: true };
-  if ((type.flags & typescript.TypeFlags.Null) !== 0) return { raw, name: 'null', nullable: true };
-  if ((type.flags & typescript.TypeFlags.Any) !== 0) return { raw, name: 'any' };
-  if ((type.flags & typescript.TypeFlags.Unknown) !== 0) return { raw, name: 'unknown' };
-
-  const reference = type as ts.TypeReference;
-  // A declared alias such as `Emit<PostPublished>` may reduce to a function or object
-  // type, so it is no longer a TypeReference. The checker keeps its arguments beside
-  // `aliasSymbol`; losing them turns DI keys into bare `Emit`/`Facade`.
+  const primitive = fromCheckedFlags(type.flags, raw);
+  if (primitive) return primitive;
+
+  // A declared alias such as `Emit<PostPublished>` may reduce to a function or object type, so it
+  // is no longer a TypeReference. The checker keeps its arguments beside `aliasSymbol`; losing
+  // them turns DI keys into bare `Emit`/`Facade`.
   const args = (type as ts.Type & { aliasTypeArguments?: readonly ts.Type[] }).aliasTypeArguments
-    ?? checker.getTypeArguments(reference);
+    ?? checker.getTypeArguments(type as ts.TypeReference);
+
   return {
     raw,
     name: meaningfulSymbolName(type, checker),
@@ -373,6 +172,153 @@ function parseCheckedType(type: ts.Type, raw: string, checker: ts.TypeChecker, d
   };
 }
 
+/**
+ * What an operation ANSWERS is read here, and the question asked of it is whether it is data.
+ *
+ * Data is what JSON keeps, so every node is asked one thing: can something in it be CALLED? A
+ * `Date` carries `toString`, a `Map` carries `clear`, an Effect carries `pipe`. Measured
+ * 2026-09-18 over the facade's own exit: `{ at: new Date(0) }` reaches a local caller as a `Date`
+ * and a remote one as a string, and an object with methods loses them on both sides, differently.
+ *
+ * It answers the PATH and the type sitting there — `at: Date` reads as the declaration it came
+ * from, where the first callable member (`toString`) names nothing an author wrote. `any` and
+ * `unknown` are left alone: nothing was declared to judge.
+ *
+ * Documented: [handlers](https://fougere.dev/docs/business/handlers).
+ */
+function notData(
+  type: ts.Type,
+  path: string,
+  checker: ts.TypeChecker,
+  seen = new Set<ts.Type>(),
+): string | undefined {
+  const typescript = getTS();
+  if (seen.has(type)) return undefined;
+
+  const judged = typescript.TypeFlags.Any | typescript.TypeFlags.Unknown | typescript.TypeFlags.Never
+    | typescript.TypeFlags.StringLike | typescript.TypeFlags.NumberLike | typescript.TypeFlags.BooleanLike
+    | typescript.TypeFlags.BigIntLike | typescript.TypeFlags.Null | typescript.TypeFlags.Undefined
+    | typescript.TypeFlags.Void;
+  if (type.flags & judged) return undefined;
+
+  if (type.isUnion() || type.isIntersection()) return firstRefused(type.types, (member) => notData(member, path, checker, seen));
+
+  if (type.getCallSignatures().length > 0) return `${path}: ${checker.typeToString(type)}`;
+  if (declaresShape(type)) return undefined;
+
+  seen.add(type);
+
+  const items = itemsOf(type, checker);
+  if (items) return firstRefused(items, (item) => notData(item, `${path}[]`, checker, seen));
+
+  return firstRefused(checker.getPropertiesOfType(type), (property) => {
+    const held = checker.getTypeOfSymbol(property);
+    // A symbol key never survives JSON either, and it is how an iterable declares itself.
+    if (property.escapedName.toString().startsWith('__@') || held.getCallSignatures().length > 0) {
+      return `${path}: ${checker.typeToString(type)}`;
+    }
+
+    return notData(held, `${path}.${property.name}`, checker, seen);
+  });
+}
+
+/**
+ * A class the schema declares — `extends entity({…})`, or a projection of one.
+ *
+ * Read from the HERITAGE rather than from what `resolveSchema` resolved: a frond answering with
+ * an entity its neighbour declares (a `Pipe<PostPublished>` finishing a fact) has no schema in
+ * its own module exports, so the op carries no output and would be judged as if nothing
+ * converted it. Its fields do convert it, wherever the class was written.
+ */
+function declaresShape(type: ts.Type): boolean {
+  const typescript = getTS();
+
+  return (type.getSymbol()?.declarations ?? []).some((declaration) =>
+    typescript.isClassDeclaration(declaration)
+    && (declaration.heritageClauses ?? []).some((clause) =>
+      /entity\(|\.(pick|omit|partial|extend)\(/.test(clause.getText())));
+}
+
+/**
+ * What a type holds if it is read as a list — its elements, or nothing.
+ *
+ * By its numeric INDEX and not by `isArrayType`: `ListResult<T> extends Array<T>` is a subtype,
+ * so the array test says no and the walk reached `push` and `map` instead of the rows. What rides
+ * beside the rows (`total`, `hasMore`) is data and is judged with everything else.
+ */
+function itemsOf(type: ts.Type, checker: ts.TypeChecker): readonly ts.Type[] | undefined {
+  const typescript = getTS();
+  if (checker.isArrayType(type) || checker.isTupleType(type)) {
+    return checker.getTypeArguments(type as ts.TypeReference);
+  }
+  const numeric = checker.getIndexTypeOfType(type, typescript.IndexKind.Number);
+
+  return numeric ? [numeric] : undefined;
+}
+
+function firstRefused<T>(members: readonly T[], read: (member: T) => string | undefined): string | undefined {
+  for (const member of members) {
+    const refused = read(member);
+    if (refused) return refused;
+  }
+
+  return undefined;
+}
+
+/** The type an operation hands back, past the promise every dispatch awaits. */
+function answeredBy(signature: ts.Signature | undefined, checker: ts.TypeChecker): ts.Type | undefined {
+  if (!signature) return undefined;
+  const returned = signature.getReturnType();
+
+  return checker.getAwaitedType(returned) ?? returned;
+}
+
+/** A union carries an absence on the side; what remains is the type. */
+function fromCheckedUnion(type: ts.UnionType, raw: string, checker: ts.TypeChecker, depth: number): TypeRef {
+  const typescript = getTS();
+  const nullable = type.types.some((member) => (member.flags & typescript.TypeFlags.Null) !== 0);
+  const undefinable = type.types.some((member) =>
+    (member.flags & (typescript.TypeFlags.Undefined | typescript.TypeFlags.Void)) !== 0,
+  );
+  const members = type.types.filter((member) =>
+    (member.flags & (typescript.TypeFlags.Null | typescript.TypeFlags.Undefined | typescript.TypeFlags.Void)) === 0,
+  );
+
+  // The checker represents the `boolean` keyword itself as `false | true`. Preserve the
+  // primitive vocabulary consumed by binding and presenter metadata.
+  const allBooleans = members.length > 0
+    && members.every((member) => (member.flags & typescript.TypeFlags.BooleanLiteral) !== 0);
+  if (allBooleans) return { raw, name: 'boolean', nullable, undefined: undefinable };
+
+  if (members.length === 1) {
+    const inner = parseCheckedType(members[0]!, raw, checker, depth + 1);
+
+    return { ...inner, raw, nullable: nullable || inner.nullable, undefined: undefinable || inner.undefined };
+  }
+
+  return {
+    raw,
+    name: members.map((member) => meaningfulSymbolName(member, checker)).join(' | ') || raw,
+    nullable,
+    undefined: undefinable,
+  };
+}
+
+/** The keywords, read off the flags the checker already carries. */
+function fromCheckedFlags(flags: ts.TypeFlags, raw: string): TypeRef | undefined {
+  const typescript = getTS();
+  if ((flags & typescript.TypeFlags.StringLike) !== 0) return { raw, name: 'string' };
+  if ((flags & typescript.TypeFlags.NumberLike) !== 0) return { raw, name: 'number' };
+  if ((flags & typescript.TypeFlags.BooleanLike) !== 0) return { raw, name: 'boolean' };
+  if ((flags & typescript.TypeFlags.Void) !== 0) return { raw, name: 'void', undefined: true };
+  if ((flags & typescript.TypeFlags.Undefined) !== 0) return { raw, name: 'undefined', undefined: true };
+  if ((flags & typescript.TypeFlags.Null) !== 0) return { raw, name: 'null', nullable: true };
+  if ((flags & typescript.TypeFlags.Any) !== 0) return { raw, name: 'any' };
+  if ((flags & typescript.TypeFlags.Unknown) !== 0) return { raw, name: 'unknown' };
+
+  return undefined;
+}
+
 // ── Module resolution ────────────────────────
 
 const TS_KEYWORDS = new Set([
@@ -473,9 +419,18 @@ function extractClassMethods(
     if (skip.has(name)) continue;
 
     const params = member.parameters.map((p) => parsedParam(p, source, checker));
-    const returnType = member.type ? parseTypeNode(member.type, source, checker) : undefined;
+    // An op that annotates nothing still HAS a return type, and the checker holds it — so it
+    // carries an output on the card, a cardinality, and the codecs a caller reads it back
+    // through. Measured 2026-09-18: 18 of the 42 unannotated ops here answer a declared entity,
+    // and every one of them handed a caller the encoded row its type called a `Date`.
+    const answered = checker ? answeredBy(checker.getSignatureFromDeclaration(member), checker) : undefined;
+    const returnType = member.type ? parseTypeNode(member.type, source, checker)
+      : answered && checker ? parseCheckedType(answered, checker.typeToString(answered), checker)
+      : undefined;
+    const refused = answered && checker ? notData(answered, name, checker) : undefined;
     results.push({
       name, params, returnType,
+      ...(refused ? { notData: refused } : {}),
       description: docSentenceOf(member, source),
     });
   }
@@ -538,6 +493,7 @@ function inheritedFromBase(
     if (!signature) continue;
 
     const returned = signature.getReturnType();
+    const refusedOutput = notData(checker.getAwaitedType(returned) ?? returned, property.name, checker);
     const sentence = typescript.displayPartsToString(property.getDocumentationComment(checker)).trim();
     results.push({
       name: property.name,
@@ -550,6 +506,7 @@ function inheritedFromBase(
         };
       }),
       returnType: parseCheckedType(returned, checker.typeToString(returned), checker),
+      ...(refusedOutput ? { notData: refusedOutput } : {}),
       ...(sentence ? { description: sentence.split(/(?<=\.)\s/)[0] } : {}),
     });
   }
@@ -599,35 +556,6 @@ function parseInheritedMethods(
   return [];
 }
 
-// ── Class finding ────────────────────────────
-
-/** Find the default exported class in a source file. */
-function findDefaultClass(source: ts.SourceFile): ts.ClassDeclaration | undefined {
-  const ts = getTS();
-  for (const stmt of source.statements) {
-    // export default class Foo { ... }
-    if (ts.isClassDeclaration(stmt) && stmt.modifiers?.some(
-      (m) => m.kind === ts.SyntaxKind.ExportKeyword,
-    ) && stmt.modifiers?.some(
-      (m) => m.kind === ts.SyntaxKind.DefaultKeyword,
-    )) {
-      return stmt;
-    }
-  }
-
-  // export default Foo (separate statement) — find the class it points to
-  for (const stmt of source.statements) {
-    if (ts.isExportAssignment(stmt) && !stmt.isExportEquals && ts.isIdentifier(stmt.expression)) {
-      const name = stmt.expression.text;
-      for (const s of source.statements) {
-        if (ts.isClassDeclaration(s) && s.name?.text === name) return s;
-      }
-    }
-  }
-
-  return undefined;
-}
-
 /** What a handler file yielded — its methods, AND what the pass could not open. */
 export interface HandlerParse {
   methods: Signature[];

package/src/scan/refusals.ts

@@ -86,6 +86,17 @@ function codeIn(typescript: typeof ts, node: ts.NewExpression): ErrorCode | unde
  * on `PostRepository`, which is the same node a refusal inside it was charged to. No name
  * matching, and no guess about what a dependency holds.
  */
+/** The set held under a key, created the first time something lands in it. */
+function into<T>(held: Map<string, Set<T>>, key: string): Set<T> {
+  const already = held.get(key);
+  if (already) return already;
+
+  const made = new Set<T>();
+  held.set(key, made);
+
+  return made;
+}
+
 export function refusalsIn(typescript: typeof ts, program: ts.Program, isOperation: (name: string) => boolean): Refusals {
   const checker = program.getTypeChecker();
   const sites: Site[] = [];
@@ -106,7 +117,7 @@ export function refusalsIn(typescript: typeof ts, program: ts.Program, isOperati
         const callee = calleeOf(typescript, checker, node);
         const caller = callee ? holderOf(typescript, node) : undefined;
         if (callee && caller && callee !== caller) {
-          (callers.get(callee) ?? callers.set(callee, new Set()).get(callee)!).add(caller);
+          into(callers, callee).add(caller);
         }
       }
 
@@ -154,7 +165,7 @@ function reached(
 
     while (queue.length > 0) {
       const at = queue.shift()!;
-      if (isOperation(at)) (found.get(at) ?? found.set(at, new Set()).get(at)!).add(site.code);
+      if (isOperation(at)) into(found, at).add(site.code);
       for (const caller of callers.get(at) ?? []) {
         if (walked.has(caller)) continue;
         walked.add(caller);