@venn-lang/dts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @venn-lang/dts
+
+> Reads the types an installed npm package publishes and returns them as Venn `TypeSpec`s.
+
+A Venn file can import from a package it installed: `import { z } from "zod"`. For the checker to say
+anything at all about `z`, something has to work out what `zod` publishes. That is this package. It
+asks the TypeScript compiler rather than parsing `.d.ts` text, and hands back plain data that
+[`@venn-lang/core`](../core) can check against without ever learning what npm is.
+
+Node only: it loads the TypeScript compiler API.
+
+## Usage
+
+```ts
+import { readPackageTypes } from "@venn-lang/dts";
+
+const types = readPackageTypes({
+  package: "zod",
+  from: "/project/target/package.json",
+});
+
+types.exports.z; // a TypeSpec
+types.covered; // { total: 42, dynamic: 3 }
+```
+
+`from` is the file the specifier is resolved against, using the same rules TypeScript itself uses.
+The CLI passes the generated `target/package.json`, beside which the package manager wrote
+`node_modules`.
+
+A package that declares this:
+
+```ts
+export declare function sum(a: number, b?: number): number;
+```
+
+comes back as this:
+
+```ts
+{
+  kind: "fn",
+  params: [{ kind: "prim", name: "number" }, { kind: "prim", name: "number" }],
+  result: { kind: "prim", name: "number" },
+  takes: 1,
+}
+```
+
+`takes` is how many arguments the caller must actually pass. Venn checks arity exactly, so without it
+`z.string()` would read as the wrong number of arguments against a signature with one optional
+parameter.
+
+## API
+
+| Export | Signature | What it does |
+| --- | --- | --- |
+| `readPackageTypes` | `({ package, from }) => PackageTypes` | Resolves the package's declaration file, runs a program over it, and converts every module export. |
+| `PackageTypes` | `interface` | `{ package, exports: Record<string, TypeSpec>, covered: { total, dynamic } }`. |
+| `toSpec` | `(type: ts.Type, conv: Conversion) => TypeSpec` | One TypeScript type as a `TypeSpec`. For callers that already hold a `ts.TypeChecker`. |
+| `Conversion` | `interface` | What one conversion carries: the checker, the current depth, and the shared state (types already read, types open, budget left). |
+
+`covered` is counted, not claimed. "94% of exports typed" is a number that can be checked and driven
+up, and it tells a reader far more than "fully compatible", which would be false for any package
+built on conditional types.
+
+A package that cannot be resolved, or that ships no declarations, is not an error. Plenty ship none.
+The answer is an empty result, and every imported name is `dynamic`, which is the truth about it.
+
+## How a TypeScript type is projected
+
+Everything TypeScript can say lands on one of the shapes in [`@venn-lang/types`](../types) or degrades to
+`dynamic`. It never fails.
+
+| TypeScript | `TypeSpec` |
+| --- | --- |
+| `string`, `number`, `boolean` | `prim` `string` / `number` / `bool` |
+| `void`, `undefined` | `prim void` |
+| `null` | `prim null` |
+| `any`, `unknown`, `never` | `dynamic` |
+| `"GET"`, `200` | `literal` |
+| `T \| U` | `union`, with the `undefined` and `null` branches folded away |
+| `T[]` | `list` |
+| `[A, B]` | `list` of `A \| B`, since the language has no fixed-length list |
+| A callable | `fn`, from the first signature only |
+| An object with properties | `record`, `open` |
+| Anything else | `dynamic` |
+
+`string | undefined` is one type in Venn, a string that may not be there, so it arrives as
+`prim string`. Writing it as a two-branch union would make every optional field something the reader
+has to take apart before using it.
+
+A method is a field whose type is a function, because that is what it is in Venn too. `schema.parse`
+is reached the same way `schema.shape` is.
+
+Records are `open`. The package's own type is the authority on what it holds and this reading of it is
+not, so anything missed stays reachable instead of being refused.
+
+Three limits keep a real package finishable. Conversion stops at depth 4, at a budget of 20,000
+types, and at any type that leads back to itself. A package's types form a graph rather than a tree:
+`zod`'s `z` holds hundreds of members and most of them lead back to the same handful of shapes, so
+reading each branch on its own re-expands the same types until the machine runs out of memory.
+Reading each type once and stopping at a budget is what makes this finish.
+
+## Why the compiler
+
+A modern package's exported types are built out of generics, conditional types and mapped types, and
+none of those mean anything until something resolves them. Parsing the text gives back the machinery;
+asking the compiler gives back the answer. A declaration of `Unwrap<Promise<string>>` arrives here as
+`prim string`.
+
+TypeScript is pulled in under the alias `tsc-api`, pinned to the 5.x line. TypeScript 7 is Go-native
+and ships no JavaScript API until 7.1, so its package exports a version string and nothing else. 7
+builds this repository, and 5.9 is a library this one package calls.
+
+## Where it is used
+
+`venn add` and `venn install` derive the types once, after the package manager has run, and write
+them to `target/types/<package>.json`. `venn check` reads them back and binds them to the names a
+file imported, so a wrong argument to `z.object` is caught without running anything.
+
+Deriving is done at install rather than on every check because reading a large package through the
+compiler takes about a second, and the answer only changes when what is installed does. The CLI also
+loads this package with a dynamic `import()`, so `venn run` never pays for ten megabytes of compiler
+it will not use.
+
+## See also
+
+- [`@venn-lang/types`](../types) defines `TypeSpec`, the vocabulary everything here is converted into.
+- [`@venn-lang/core`](../core) binds these specs to imported names and checks the calls against them.
+- [`@venn-lang/cli`](../cli) runs the derivation at install time and reads the result at check time.

package/dist/index.d.mts

@@ -0,0 +1,78 @@
+import ts from "tsc-api";
+import { TypeSpec } from "@venn-lang/types";
+//#region src/convert/to-spec.d.ts
+/**
+ * What one conversion carries: the checker, how deep it is, and what it has
+ * already worked out.
+ *
+ * The shared state is not an optimisation. A real package's types form a graph,
+ * not a tree (`zod`'s `z` holds hundreds of members, most of them leading back
+ * to the same handful of shapes), so a branch read on its own re-expands the
+ * same types until the machine runs out of memory. Reading each type once, and
+ * stopping at a budget, is what makes this finish.
+ */
+interface Conversion {
+  checker: ts.TypeChecker;
+  depth: number;
+  state: ConversionState;
+}
+/** What every branch of one conversion shares. */
+interface ConversionState {
+  done: Map<ts.Type, TypeSpec>;
+  /** Types being read right now, so one that contains itself does not loop. */
+  open: Set<ts.Type>;
+  /** How many more types may be read before the rest is `dynamic`. */
+  left: number;
+}
+/**
+ * One TypeScript type, as the language's own.
+ *
+ * Everything TS can say projects onto the ten shapes or degrades to `dynamic`,
+ * never to a failure. Generics, conditionals and mapped types are gone by the
+ * time anything reaches here: the compiler resolved them, so what arrives is the
+ * answer rather than the machinery.
+ *
+ * @param type a type the checker has already resolved
+ * @param conv the checker, the current depth and the state shared across branches
+ * @returns the type as a `TypeSpec`, or `dynamic` once the depth, the budget or
+ * a cycle stops the reading
+ */
+declare function toSpec(type: ts.Type, conv: Conversion): TypeSpec;
+//#endregion
+//#region src/read-package-types.d.ts
+/** What one installed package publishes, as this language's types. */
+interface PackageTypes {
+  package: string;
+  /** Each export, by the name it is imported under. */
+  exports: Record<string, TypeSpec>;
+  /** How many exports were read, and how many came back `dynamic`. */
+  covered: {
+    total: number;
+    dynamic: number;
+  };
+}
+/**
+ * The types an installed package publishes.
+ *
+ * Read through the TypeScript compiler rather than by parsing `.d.ts` text: a
+ * modern package's exported types are built out of generics, conditionals and
+ * mapped types, which have no meaning until something resolves them. Parsing
+ * gives back the machinery; asking the compiler gives back the answer.
+ *
+ * The compiler comes in under the alias `tsc-api`, pinned to the 5.x line,
+ * because TypeScript 7 is Go-native and ships no JavaScript API until 7.1. So
+ * 7 builds this repo and 5.9 is a library this one package calls.
+ *
+ * @returns every export as a {@link TypeSpec}, with a count of how many came
+ * back `dynamic`. A package that ships no types is not an error: `exports` is
+ * empty and `covered.total` is zero.
+ */
+declare function readPackageTypes(args: {
+  /** The package name, as it is imported. */
+  package: string;
+  /** A file to resolve from, such as the generated `package.json` in `target/`. */
+  from: string;
+}): PackageTypes;
+//#endregion
+export { type Conversion, type PackageTypes, readPackageTypes, toSpec };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/convert/to-spec.ts","../src/read-package-types.ts"],"mappings":";;;;;;;;;;;;;UAoBiB;EACf,SAAS,GAAG;EACZ;EACA,OAAO;;;UAIQ;EACf,MAAM,IAAI,GAAG,MAAM;;EAEnB,MAAM,IAAI,GAAG;;EAEb;;;;;;;;;;;;;;;iBAqBc,OAAO,MAAM,GAAG,MAAM,MAAM,aAAa;;;;UChDxC;EACf;;EAEA,SAAS,eAAe;;EAExB;IAAW;IAAe;;;;;;;;;;;;;;;;;;;iBAmBZ,iBAAiB;;EAE/B;;EAEA;IACE"}

package/dist/index.mjs

@@ -0,0 +1,292 @@
+import ts from "tsc-api";
+//#region src/convert/to-spec.ts
+/** How far into a type to look, and how much of one to read at all. */
+const DEPTH = 4;
+const BUDGET = 2e4;
+const DYNAMIC = { kind: "dynamic" };
+/** A state with nothing read yet and the full budget left. */
+function newState() {
+	return {
+		done: /* @__PURE__ */ new Map(),
+		open: /* @__PURE__ */ new Set(),
+		left: BUDGET
+	};
+}
+/**
+* One TypeScript type, as the language's own.
+*
+* Everything TS can say projects onto the ten shapes or degrades to `dynamic`,
+* never to a failure. Generics, conditionals and mapped types are gone by the
+* time anything reaches here: the compiler resolved them, so what arrives is the
+* answer rather than the machinery.
+*
+* @param type a type the checker has already resolved
+* @param conv the checker, the current depth and the state shared across branches
+* @returns the type as a `TypeSpec`, or `dynamic` once the depth, the budget or
+* a cycle stops the reading
+*/
+function toSpec(type, conv) {
+	const known = conv.state.done.get(type);
+	if (known) return known;
+	if (conv.depth > DEPTH || conv.state.left <= 0 || conv.state.open.has(type)) return DYNAMIC;
+	conv.state.left--;
+	conv.state.open.add(type);
+	const spec = convert(type, conv);
+	conv.state.open.delete(type);
+	if (conv.depth < DEPTH) conv.state.done.set(type, spec);
+	return spec;
+}
+function convert(type, conv) {
+	const flags = type.flags;
+	const primitive = primitiveOf(flags);
+	if (primitive) return primitive;
+	if (flags & ts.TypeFlags.StringLiteral) return literal(type.value);
+	if (flags & ts.TypeFlags.NumberLiteral) return literal(type.value);
+	if (flags & ts.TypeFlags.Union) return unionOf(type, deeper(conv));
+	return structural(type, deeper(conv));
+}
+function deeper(conv) {
+	return {
+		...conv,
+		depth: conv.depth + 1
+	};
+}
+const PRIMITIVES = [
+	[ts.TypeFlags.String, {
+		kind: "prim",
+		name: "string"
+	}],
+	[ts.TypeFlags.Number, {
+		kind: "prim",
+		name: "number"
+	}],
+	[ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral, {
+		kind: "prim",
+		name: "bool"
+	}],
+	[ts.TypeFlags.Void | ts.TypeFlags.Undefined, {
+		kind: "prim",
+		name: "void"
+	}],
+	[ts.TypeFlags.Null, {
+		kind: "prim",
+		name: "null"
+	}],
+	[ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never, DYNAMIC]
+];
+function primitiveOf(flags) {
+	for (const [mask, spec] of PRIMITIVES) if (flags & mask) return spec;
+}
+function literal(value) {
+	return {
+		kind: "literal",
+		value
+	};
+}
+/**
+* A union, with the branches TypeScript adds for absence folded away.
+*
+* `string | undefined` is one type in this language, a string that may not be
+* there. Writing it as a two-branch union would make every optional field
+* something the reader has to take apart before using.
+*/
+function unionOf(type, conv) {
+	const members = type.types.filter((one) => !(one.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Null))).map((one) => toSpec(one, conv));
+	if (members.length === 0) return {
+		kind: "prim",
+		name: "null"
+	};
+	return members.length === 1 ? members[0] : {
+		kind: "union",
+		members
+	};
+}
+/** An array, a callable, or an object with properties, in that order. */
+function structural(type, conv) {
+	const element = elementOf(type, conv);
+	if (element) return {
+		kind: "list",
+		element
+	};
+	const calls = conv.checker.getSignaturesOfType(type, ts.SignatureKind.Call);
+	if (calls.length > 0) return fnSpec(calls[0], conv);
+	return type.getProperties().length > 0 ? recordSpec(type, conv) : DYNAMIC;
+}
+/**
+* What a list holds, when the type is one.
+*
+* A tuple reads as a list of whatever its slots hold together: the language has
+* no fixed-length list, and `list<string | number>` is nearer the truth than
+* saying nothing at all.
+*/
+function elementOf(type, conv) {
+	const checker = conv.checker;
+	if (checker.isArrayType(type)) {
+		const [arg] = checker.getTypeArguments(type);
+		return arg ? toSpec(arg, conv) : DYNAMIC;
+	}
+	if (!checker.isTupleType(type)) return void 0;
+	const members = checker.getTypeArguments(type).map((one) => toSpec(one, conv));
+	if (members.length === 0) return DYNAMIC;
+	return members.length === 1 ? members[0] : {
+		kind: "union",
+		members
+	};
+}
+//#endregion
+//#region src/convert/shapes.ts
+/**
+* A callable, as the language writes one.
+*
+* The first signature only. An overloaded function has several and the language
+* has one shape for a function; the first is what TypeScript itself shows on
+* hover, so a reader sees the same thing in both editors rather than two
+* different half-truths.
+*/
+function fnSpec(signature, conv) {
+	return {
+		kind: "fn",
+		params: signature.getParameters().map((param) => paramSpec(param, conv)),
+		result: toSpec(conv.checker.getReturnTypeOfSignature(signature), conv),
+		takes: requiredCount(signature)
+	};
+}
+/**
+* How many arguments the caller must actually pass.
+*
+* Read from the declarations rather than from the checker's own count, which is
+* not part of its public surface. A parameter stops being required once it
+* carries a `?`, a default or a `...`, and so does everything after it.
+*/
+function requiredCount(signature) {
+	const params = signature.getParameters();
+	let required = 0;
+	for (const param of params) {
+		if (isOptional(param)) break;
+		required++;
+	}
+	return required;
+}
+function isOptional(param) {
+	const decl = param.valueDeclaration ?? param.declarations?.[0];
+	if (!decl || !ts.isParameter(decl)) return false;
+	return Boolean(decl.questionToken ?? decl.initializer ?? decl.dotDotDotToken);
+}
+function paramSpec(param, conv) {
+	const decl = param.valueDeclaration ?? param.declarations?.[0];
+	if (!decl) return { kind: "dynamic" };
+	return toSpec(conv.checker.getTypeOfSymbolAtLocation(param, decl), conv);
+}
+/**
+* An object, as a record of what it holds.
+*
+* A method is a field whose type is a function, which is what it is in this
+* language too. So `schema.parse` is reached the same way `schema.shape` is,
+* and the reader is not asked to know which of the two the author chose.
+*/
+function recordSpec(type, conv) {
+	const fields = {};
+	for (const property of type.getProperties()) {
+		const spec = propertySpec(property, conv);
+		if (spec) fields[property.getName()] = spec;
+	}
+	return {
+		kind: "record",
+		fields,
+		open: true
+	};
+}
+function propertySpec(property, conv) {
+	const decl = property.valueDeclaration ?? property.declarations?.[0];
+	if (!decl) return void 0;
+	return toSpec(conv.checker.getTypeOfSymbolAtLocation(property, decl), conv);
+}
+//#endregion
+//#region src/read-package-types.ts
+/**
+* The types an installed package publishes.
+*
+* Read through the TypeScript compiler rather than by parsing `.d.ts` text: a
+* modern package's exported types are built out of generics, conditionals and
+* mapped types, which have no meaning until something resolves them. Parsing
+* gives back the machinery; asking the compiler gives back the answer.
+*
+* The compiler comes in under the alias `tsc-api`, pinned to the 5.x line,
+* because TypeScript 7 is Go-native and ships no JavaScript API until 7.1. So
+* 7 builds this repo and 5.9 is a library this one package calls.
+*
+* @returns every export as a {@link TypeSpec}, with a count of how many came
+* back `dynamic`. A package that ships no types is not an error: `exports` is
+* empty and `covered.total` is zero.
+*/
+function readPackageTypes(args) {
+	const declarations = declarationFile(args);
+	if (!declarations) return empty(args.package);
+	const program = ts.createProgram([declarations], OPTIONS);
+	const source = program.getSourceFile(declarations);
+	const checker = program.getTypeChecker();
+	const symbol = source && checker.getSymbolAtLocation(source);
+	if (!symbol) return empty(args.package);
+	return counted(args.package, exportsOf({
+		symbol,
+		checker
+	}));
+}
+const OPTIONS = {
+	target: ts.ScriptTarget.ESNext,
+	module: ts.ModuleKind.ESNext,
+	moduleResolution: ts.ModuleResolutionKind.Bundler,
+	skipLibCheck: true,
+	strict: true
+};
+/** Where the package's declarations are, as TypeScript itself resolves them. */
+function declarationFile(args) {
+	const host = ts.createCompilerHost(OPTIONS);
+	const file = ts.resolveModuleName(args.package, args.from, OPTIONS, host).resolvedModule?.resolvedFileName;
+	return file && /\.d\.[cm]?ts$/.test(file) ? file : void 0;
+}
+function exportsOf(args) {
+	const out = {};
+	const conv = {
+		checker: args.checker,
+		depth: 0,
+		state: newState()
+	};
+	for (const each of args.checker.getExportsOfModule(args.symbol)) {
+		const decl = each.valueDeclaration ?? each.declarations?.[0];
+		if (!decl) continue;
+		out[each.getName()] = toSpec(args.checker.getTypeOfSymbolAtLocation(each, decl), conv);
+	}
+	return out;
+}
+/**
+* How much of the package came across.
+*
+* Counted and reported rather than claimed: "94% of exports typed" can be
+* checked and driven up, unlike "fully compatible".
+*/
+function counted(name, exports) {
+	const all = Object.values(exports);
+	return {
+		package: name,
+		exports,
+		covered: {
+			total: all.length,
+			dynamic: all.filter((one) => one.kind === "dynamic").length
+		}
+	};
+}
+function empty(name) {
+	return {
+		package: name,
+		exports: {},
+		covered: {
+			total: 0,
+			dynamic: 0
+		}
+	};
+}
+//#endregion
+export { readPackageTypes, toSpec };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/convert/to-spec.ts","../src/convert/shapes.ts","../src/read-package-types.ts"],"sourcesContent":["import type { TypeSpec } from \"@venn-lang/types\";\nimport ts from \"tsc-api\";\nimport { fnSpec, recordSpec } from \"./shapes.js\";\n\n/** How far into a type to look, and how much of one to read at all. */\nconst DEPTH = 4;\nconst BUDGET = 20_000;\n\nconst DYNAMIC: TypeSpec = { kind: \"dynamic\" };\n\n/**\n * What one conversion carries: the checker, how deep it is, and what it has\n * already worked out.\n *\n * The shared state is not an optimisation. A real package's types form a graph,\n * not a tree (`zod`'s `z` holds hundreds of members, most of them leading back\n * to the same handful of shapes), so a branch read on its own re-expands the\n * same types until the machine runs out of memory. Reading each type once, and\n * stopping at a budget, is what makes this finish.\n */\nexport interface Conversion {\n  checker: ts.TypeChecker;\n  depth: number;\n  state: ConversionState;\n}\n\n/** What every branch of one conversion shares. */\nexport interface ConversionState {\n  done: Map<ts.Type, TypeSpec>;\n  /** Types being read right now, so one that contains itself does not loop. */\n  open: Set<ts.Type>;\n  /** How many more types may be read before the rest is `dynamic`. */\n  left: number;\n}\n\n/** A state with nothing read yet and the full budget left. */\nexport function newState(): ConversionState {\n  return { done: new Map(), open: new Set(), left: BUDGET };\n}\n\n/**\n * One TypeScript type, as the language's own.\n *\n * Everything TS can say projects onto the ten shapes or degrades to `dynamic`,\n * never to a failure. Generics, conditionals and mapped types are gone by the\n * time anything reaches here: the compiler resolved them, so what arrives is the\n * answer rather than the machinery.\n *\n * @param type a type the checker has already resolved\n * @param conv the checker, the current depth and the state shared across branches\n * @returns the type as a `TypeSpec`, or `dynamic` once the depth, the budget or\n * a cycle stops the reading\n */\nexport function toSpec(type: ts.Type, conv: Conversion): TypeSpec {\n  const known = conv.state.done.get(type);\n  if (known) return known;\n  if (conv.depth > DEPTH || conv.state.left <= 0 || conv.state.open.has(type)) return DYNAMIC;\n  conv.state.left--;\n  conv.state.open.add(type);\n  const spec = convert(type, conv);\n  conv.state.open.delete(type);\n  // Only a reading that ran to the end is worth keeping: one cut short by the\n  // depth limit says more about where it was met than about the type.\n  if (conv.depth < DEPTH) conv.state.done.set(type, spec);\n  return spec;\n}\n\nfunction convert(type: ts.Type, conv: Conversion): TypeSpec {\n  const flags = type.flags;\n  const primitive = primitiveOf(flags);\n  if (primitive) return primitive;\n  if (flags & ts.TypeFlags.StringLiteral) return literal((type as ts.StringLiteralType).value);\n  if (flags & ts.TypeFlags.NumberLiteral) return literal((type as ts.NumberLiteralType).value);\n  if (flags & ts.TypeFlags.Union) return unionOf(type as ts.UnionType, deeper(conv));\n  return structural(type, deeper(conv));\n}\n\nfunction deeper(conv: Conversion): Conversion {\n  return { ...conv, depth: conv.depth + 1 };\n}\n\nconst PRIMITIVES: [ts.TypeFlags, TypeSpec][] = [\n  [ts.TypeFlags.String, { kind: \"prim\", name: \"string\" }],\n  [ts.TypeFlags.Number, { kind: \"prim\", name: \"number\" }],\n  [ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral, { kind: \"prim\", name: \"bool\" }],\n  [ts.TypeFlags.Void | ts.TypeFlags.Undefined, { kind: \"prim\", name: \"void\" }],\n  [ts.TypeFlags.Null, { kind: \"prim\", name: \"null\" }],\n  [ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never, DYNAMIC],\n];\n\nfunction primitiveOf(flags: ts.TypeFlags): TypeSpec | undefined {\n  for (const [mask, spec] of PRIMITIVES) {\n    if (flags & mask) return spec;\n  }\n  return undefined;\n}\n\nfunction literal(value: string | number): TypeSpec {\n  return { kind: \"literal\", value };\n}\n\n/**\n * A union, with the branches TypeScript adds for absence folded away.\n *\n * `string | undefined` is one type in this language, a string that may not be\n * there. Writing it as a two-branch union would make every optional field\n * something the reader has to take apart before using.\n */\nfunction unionOf(type: ts.UnionType, conv: Conversion): TypeSpec {\n  const members = type.types\n    .filter((one) => !(one.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Null)))\n    .map((one) => toSpec(one, conv));\n  if (members.length === 0) return { kind: \"prim\", name: \"null\" };\n  return members.length === 1 ? (members[0] as TypeSpec) : { kind: \"union\", members };\n}\n\n/** An array, a callable, or an object with properties, in that order. */\nfunction structural(type: ts.Type, conv: Conversion): TypeSpec {\n  const element = elementOf(type, conv);\n  if (element) return { kind: \"list\", element };\n  const calls = conv.checker.getSignaturesOfType(type, ts.SignatureKind.Call);\n  if (calls.length > 0) return fnSpec(calls[0] as ts.Signature, conv);\n  return type.getProperties().length > 0 ? recordSpec(type, conv) : DYNAMIC;\n}\n\n/**\n * What a list holds, when the type is one.\n *\n * A tuple reads as a list of whatever its slots hold together: the language has\n * no fixed-length list, and `list<string | number>` is nearer the truth than\n * saying nothing at all.\n */\nfunction elementOf(type: ts.Type, conv: Conversion): TypeSpec | undefined {\n  const checker = conv.checker;\n  if (checker.isArrayType(type)) {\n    const [arg] = checker.getTypeArguments(type as ts.TypeReference);\n    return arg ? toSpec(arg, conv) : DYNAMIC;\n  }\n  if (!checker.isTupleType(type)) return undefined;\n  const members = checker\n    .getTypeArguments(type as ts.TypeReference)\n    .map((one) => toSpec(one, conv));\n  if (members.length === 0) return DYNAMIC;\n  return members.length === 1 ? (members[0] as TypeSpec) : { kind: \"union\", members };\n}\n","import type { TypeSpec } from \"@venn-lang/types\";\nimport ts from \"tsc-api\";\nimport { type Conversion, toSpec } from \"./to-spec.js\";\n\n/**\n * A callable, as the language writes one.\n *\n * The first signature only. An overloaded function has several and the language\n * has one shape for a function; the first is what TypeScript itself shows on\n * hover, so a reader sees the same thing in both editors rather than two\n * different half-truths.\n */\nexport function fnSpec(signature: ts.Signature, conv: Conversion): TypeSpec {\n  const params = signature.getParameters().map((param) => paramSpec(param, conv));\n  const result = toSpec(conv.checker.getReturnTypeOfSignature(signature), conv);\n  // Optional parameters are ordinary in TypeScript and this language checks\n  // arity exactly, so `takes` is what keeps a call with no arguments legal\n  // against a signature whose only parameter is optional, as in `z.string()`.\n  return { kind: \"fn\", params, result, takes: requiredCount(signature) };\n}\n\n/**\n * How many arguments the caller must actually pass.\n *\n * Read from the declarations rather than from the checker's own count, which is\n * not part of its public surface. A parameter stops being required once it\n * carries a `?`, a default or a `...`, and so does everything after it.\n */\nfunction requiredCount(signature: ts.Signature): number {\n  const params = signature.getParameters();\n  let required = 0;\n  for (const param of params) {\n    if (isOptional(param)) break;\n    required++;\n  }\n  return required;\n}\n\nfunction isOptional(param: ts.Symbol): boolean {\n  const decl = param.valueDeclaration ?? param.declarations?.[0];\n  if (!decl || !ts.isParameter(decl)) return false;\n  return Boolean(decl.questionToken ?? decl.initializer ?? decl.dotDotDotToken);\n}\n\nfunction paramSpec(param: ts.Symbol, conv: Conversion): TypeSpec {\n  const decl = param.valueDeclaration ?? param.declarations?.[0];\n  if (!decl) return { kind: \"dynamic\" };\n  return toSpec(conv.checker.getTypeOfSymbolAtLocation(param, decl), conv);\n}\n\n/**\n * An object, as a record of what it holds.\n *\n * A method is a field whose type is a function, which is what it is in this\n * language too. So `schema.parse` is reached the same way `schema.shape` is,\n * and the reader is not asked to know which of the two the author chose.\n */\nexport function recordSpec(type: ts.Type, conv: Conversion): TypeSpec {\n  const fields: Record<string, TypeSpec> = {};\n  for (const property of type.getProperties()) {\n    const spec = propertySpec(property, conv);\n    if (spec) fields[property.getName()] = spec;\n  }\n  // Open, because a package's own type is the authority on what it holds and\n  // this reading of it is not: anything missed should be reachable, not refused.\n  return { kind: \"record\", fields, open: true };\n}\n\nfunction propertySpec(property: ts.Symbol, conv: Conversion): TypeSpec | undefined {\n  const decl = property.valueDeclaration ?? property.declarations?.[0];\n  if (!decl) return undefined;\n  return toSpec(conv.checker.getTypeOfSymbolAtLocation(property, decl), conv);\n}\n","import type { TypeSpec } from \"@venn-lang/types\";\nimport ts from \"tsc-api\";\nimport { newState, toSpec } from \"./convert/index.js\";\n\n/** What one installed package publishes, as this language's types. */\nexport interface PackageTypes {\n  package: string;\n  /** Each export, by the name it is imported under. */\n  exports: Record<string, TypeSpec>;\n  /** How many exports were read, and how many came back `dynamic`. */\n  covered: { total: number; dynamic: number };\n}\n\n/**\n * The types an installed package publishes.\n *\n * Read through the TypeScript compiler rather than by parsing `.d.ts` text: a\n * modern package's exported types are built out of generics, conditionals and\n * mapped types, which have no meaning until something resolves them. Parsing\n * gives back the machinery; asking the compiler gives back the answer.\n *\n * The compiler comes in under the alias `tsc-api`, pinned to the 5.x line,\n * because TypeScript 7 is Go-native and ships no JavaScript API until 7.1. So\n * 7 builds this repo and 5.9 is a library this one package calls.\n *\n * @returns every export as a {@link TypeSpec}, with a count of how many came\n * back `dynamic`. A package that ships no types is not an error: `exports` is\n * empty and `covered.total` is zero.\n */\nexport function readPackageTypes(args: {\n  /** The package name, as it is imported. */\n  package: string;\n  /** A file to resolve from, such as the generated `package.json` in `target/`. */\n  from: string;\n}): PackageTypes {\n  const declarations = declarationFile(args);\n  if (!declarations) return empty(args.package);\n  const program = ts.createProgram([declarations], OPTIONS);\n  const source = program.getSourceFile(declarations);\n  const checker = program.getTypeChecker();\n  const symbol = source && checker.getSymbolAtLocation(source);\n  if (!symbol) return empty(args.package);\n  return counted(args.package, exportsOf({ symbol, checker }));\n}\n\nconst OPTIONS: ts.CompilerOptions = {\n  target: ts.ScriptTarget.ESNext,\n  module: ts.ModuleKind.ESNext,\n  moduleResolution: ts.ModuleResolutionKind.Bundler,\n  skipLibCheck: true,\n  strict: true,\n};\n\n/** Where the package's declarations are, as TypeScript itself resolves them. */\nfunction declarationFile(args: { package: string; from: string }): string | undefined {\n  const host = ts.createCompilerHost(OPTIONS);\n  const found = ts.resolveModuleName(args.package, args.from, OPTIONS, host);\n  const file = found.resolvedModule?.resolvedFileName;\n  // `.d.ts`, `.d.mts` and `.d.cts` are all declarations. zod ships the last of\n  // the three, so a filter naming only the first two finds nothing at all.\n  return file && /\\.d\\.[cm]?ts$/.test(file) ? file : undefined;\n}\n\nfunction exportsOf(args: { symbol: ts.Symbol; checker: ts.TypeChecker }): Record<string, TypeSpec> {\n  const out: Record<string, TypeSpec> = {};\n  const conv = { checker: args.checker, depth: 0, state: newState() };\n  for (const each of args.checker.getExportsOfModule(args.symbol)) {\n    const decl = each.valueDeclaration ?? each.declarations?.[0];\n    if (!decl) continue;\n    out[each.getName()] = toSpec(args.checker.getTypeOfSymbolAtLocation(each, decl), conv);\n  }\n  return out;\n}\n\n/**\n * How much of the package came across.\n *\n * Counted and reported rather than claimed: \"94% of exports typed\" can be\n * checked and driven up, unlike \"fully compatible\".\n */\nfunction counted(name: string, exports: Record<string, TypeSpec>): PackageTypes {\n  const all = Object.values(exports);\n  return {\n    package: name,\n    exports,\n    covered: { total: all.length, dynamic: all.filter((one) => one.kind === \"dynamic\").length },\n  };\n}\n\nfunction empty(name: string): PackageTypes {\n  return { package: name, exports: {}, covered: { total: 0, dynamic: 0 } };\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@venn-lang/dts",
+  "version": "0.1.0",
+  "description": "Reads the types an installed npm package publishes and returns them as Venn TypeSpecs.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "typescript",
+    "declarations"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/dts#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/dts"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "tsc-api": "npm:typescript@^5.9.0",
+    "@venn-lang/types": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "tsdown": "^0.22.14",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/convert/index.ts

@@ -0,0 +1,7 @@
+export { fnSpec, recordSpec } from "./shapes.js";
+export {
+  type Conversion,
+  type ConversionState,
+  newState,
+  toSpec,
+} from "./to-spec.js";

package/src/convert/shapes.ts

@@ -0,0 +1,73 @@
+import type { TypeSpec } from "@venn-lang/types";
+import ts from "tsc-api";
+import { type Conversion, toSpec } from "./to-spec.js";
+
+/**
+ * A callable, as the language writes one.
+ *
+ * The first signature only. An overloaded function has several and the language
+ * has one shape for a function; the first is what TypeScript itself shows on
+ * hover, so a reader sees the same thing in both editors rather than two
+ * different half-truths.
+ */
+export function fnSpec(signature: ts.Signature, conv: Conversion): TypeSpec {
+  const params = signature.getParameters().map((param) => paramSpec(param, conv));
+  const result = toSpec(conv.checker.getReturnTypeOfSignature(signature), conv);
+  // Optional parameters are ordinary in TypeScript and this language checks
+  // arity exactly, so `takes` is what keeps a call with no arguments legal
+  // against a signature whose only parameter is optional, as in `z.string()`.
+  return { kind: "fn", params, result, takes: requiredCount(signature) };
+}
+
+/**
+ * How many arguments the caller must actually pass.
+ *
+ * Read from the declarations rather than from the checker's own count, which is
+ * not part of its public surface. A parameter stops being required once it
+ * carries a `?`, a default or a `...`, and so does everything after it.
+ */
+function requiredCount(signature: ts.Signature): number {
+  const params = signature.getParameters();
+  let required = 0;
+  for (const param of params) {
+    if (isOptional(param)) break;
+    required++;
+  }
+  return required;
+}
+
+function isOptional(param: ts.Symbol): boolean {
+  const decl = param.valueDeclaration ?? param.declarations?.[0];
+  if (!decl || !ts.isParameter(decl)) return false;
+  return Boolean(decl.questionToken ?? decl.initializer ?? decl.dotDotDotToken);
+}
+
+function paramSpec(param: ts.Symbol, conv: Conversion): TypeSpec {
+  const decl = param.valueDeclaration ?? param.declarations?.[0];
+  if (!decl) return { kind: "dynamic" };
+  return toSpec(conv.checker.getTypeOfSymbolAtLocation(param, decl), conv);
+}
+
+/**
+ * An object, as a record of what it holds.
+ *
+ * A method is a field whose type is a function, which is what it is in this
+ * language too. So `schema.parse` is reached the same way `schema.shape` is,
+ * and the reader is not asked to know which of the two the author chose.
+ */
+export function recordSpec(type: ts.Type, conv: Conversion): TypeSpec {
+  const fields: Record<string, TypeSpec> = {};
+  for (const property of type.getProperties()) {
+    const spec = propertySpec(property, conv);
+    if (spec) fields[property.getName()] = spec;
+  }
+  // Open, because a package's own type is the authority on what it holds and
+  // this reading of it is not: anything missed should be reachable, not refused.
+  return { kind: "record", fields, open: true };
+}
+
+function propertySpec(property: ts.Symbol, conv: Conversion): TypeSpec | undefined {
+  const decl = property.valueDeclaration ?? property.declarations?.[0];
+  if (!decl) return undefined;
+  return toSpec(conv.checker.getTypeOfSymbolAtLocation(property, decl), conv);
+}

package/src/convert/to-spec.ts

@@ -0,0 +1,145 @@
+import type { TypeSpec } from "@venn-lang/types";
+import ts from "tsc-api";
+import { fnSpec, recordSpec } from "./shapes.js";
+
+/** How far into a type to look, and how much of one to read at all. */
+const DEPTH = 4;
+const BUDGET = 20_000;
+
+const DYNAMIC: TypeSpec = { kind: "dynamic" };
+
+/**
+ * What one conversion carries: the checker, how deep it is, and what it has
+ * already worked out.
+ *
+ * The shared state is not an optimisation. A real package's types form a graph,
+ * not a tree (`zod`'s `z` holds hundreds of members, most of them leading back
+ * to the same handful of shapes), so a branch read on its own re-expands the
+ * same types until the machine runs out of memory. Reading each type once, and
+ * stopping at a budget, is what makes this finish.
+ */
+export interface Conversion {
+  checker: ts.TypeChecker;
+  depth: number;
+  state: ConversionState;
+}
+
+/** What every branch of one conversion shares. */
+export interface ConversionState {
+  done: Map<ts.Type, TypeSpec>;
+  /** Types being read right now, so one that contains itself does not loop. */
+  open: Set<ts.Type>;
+  /** How many more types may be read before the rest is `dynamic`. */
+  left: number;
+}
+
+/** A state with nothing read yet and the full budget left. */
+export function newState(): ConversionState {
+  return { done: new Map(), open: new Set(), left: BUDGET };
+}
+
+/**
+ * One TypeScript type, as the language's own.
+ *
+ * Everything TS can say projects onto the ten shapes or degrades to `dynamic`,
+ * never to a failure. Generics, conditionals and mapped types are gone by the
+ * time anything reaches here: the compiler resolved them, so what arrives is the
+ * answer rather than the machinery.
+ *
+ * @param type a type the checker has already resolved
+ * @param conv the checker, the current depth and the state shared across branches
+ * @returns the type as a `TypeSpec`, or `dynamic` once the depth, the budget or
+ * a cycle stops the reading
+ */
+export function toSpec(type: ts.Type, conv: Conversion): TypeSpec {
+  const known = conv.state.done.get(type);
+  if (known) return known;
+  if (conv.depth > DEPTH || conv.state.left <= 0 || conv.state.open.has(type)) return DYNAMIC;
+  conv.state.left--;
+  conv.state.open.add(type);
+  const spec = convert(type, conv);
+  conv.state.open.delete(type);
+  // Only a reading that ran to the end is worth keeping: one cut short by the
+  // depth limit says more about where it was met than about the type.
+  if (conv.depth < DEPTH) conv.state.done.set(type, spec);
+  return spec;
+}
+
+function convert(type: ts.Type, conv: Conversion): TypeSpec {
+  const flags = type.flags;
+  const primitive = primitiveOf(flags);
+  if (primitive) return primitive;
+  if (flags & ts.TypeFlags.StringLiteral) return literal((type as ts.StringLiteralType).value);
+  if (flags & ts.TypeFlags.NumberLiteral) return literal((type as ts.NumberLiteralType).value);
+  if (flags & ts.TypeFlags.Union) return unionOf(type as ts.UnionType, deeper(conv));
+  return structural(type, deeper(conv));
+}
+
+function deeper(conv: Conversion): Conversion {
+  return { ...conv, depth: conv.depth + 1 };
+}
+
+const PRIMITIVES: [ts.TypeFlags, TypeSpec][] = [
+  [ts.TypeFlags.String, { kind: "prim", name: "string" }],
+  [ts.TypeFlags.Number, { kind: "prim", name: "number" }],
+  [ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral, { kind: "prim", name: "bool" }],
+  [ts.TypeFlags.Void | ts.TypeFlags.Undefined, { kind: "prim", name: "void" }],
+  [ts.TypeFlags.Null, { kind: "prim", name: "null" }],
+  [ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never, DYNAMIC],
+];
+
+function primitiveOf(flags: ts.TypeFlags): TypeSpec | undefined {
+  for (const [mask, spec] of PRIMITIVES) {
+    if (flags & mask) return spec;
+  }
+  return undefined;
+}
+
+function literal(value: string | number): TypeSpec {
+  return { kind: "literal", value };
+}
+
+/**
+ * A union, with the branches TypeScript adds for absence folded away.
+ *
+ * `string | undefined` is one type in this language, a string that may not be
+ * there. Writing it as a two-branch union would make every optional field
+ * something the reader has to take apart before using.
+ */
+function unionOf(type: ts.UnionType, conv: Conversion): TypeSpec {
+  const members = type.types
+    .filter((one) => !(one.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Null)))
+    .map((one) => toSpec(one, conv));
+  if (members.length === 0) return { kind: "prim", name: "null" };
+  return members.length === 1 ? (members[0] as TypeSpec) : { kind: "union", members };
+}
+
+/** An array, a callable, or an object with properties, in that order. */
+function structural(type: ts.Type, conv: Conversion): TypeSpec {
+  const element = elementOf(type, conv);
+  if (element) return { kind: "list", element };
+  const calls = conv.checker.getSignaturesOfType(type, ts.SignatureKind.Call);
+  if (calls.length > 0) return fnSpec(calls[0] as ts.Signature, conv);
+  return type.getProperties().length > 0 ? recordSpec(type, conv) : DYNAMIC;
+}
+
+/**
+ * What a list holds, when the type is one.
+ *
+ * A tuple reads as a list of whatever its slots hold together: the language has
+ * no fixed-length list, and `list<string | number>` is nearer the truth than
+ * saying nothing at all.
+ */
+function elementOf(type: ts.Type, conv: Conversion): TypeSpec | undefined {
+  const checker = conv.checker;
+  if (checker.isArrayType(type)) {
+    const [arg] = checker.getTypeArguments(type as ts.TypeReference);
+    return arg ? toSpec(arg, conv) : DYNAMIC;
+  }
+  if (!checker.isTupleType(type)) return undefined;
+  const members = checker
+    .getTypeArguments(type as ts.TypeReference)
+    .map((one) => toSpec(one, conv));
+  if (members.length === 0) return DYNAMIC;
+  return members.length === 1 ? (members[0] as TypeSpec) : { kind: "union", members };
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+// @venn-lang/dts: the types an installed npm package publishes, read through the
+// TypeScript compiler. Node-only, since it loads the compiler itself.
+export { type Conversion, toSpec } from "./convert/index.js";
+export { type PackageTypes, readPackageTypes } from "./read-package-types.js";

package/src/read-package-types.ts

@@ -0,0 +1,92 @@
+import type { TypeSpec } from "@venn-lang/types";
+import ts from "tsc-api";
+import { newState, toSpec } from "./convert/index.js";
+
+/** What one installed package publishes, as this language's types. */
+export interface PackageTypes {
+  package: string;
+  /** Each export, by the name it is imported under. */
+  exports: Record<string, TypeSpec>;
+  /** How many exports were read, and how many came back `dynamic`. */
+  covered: { total: number; dynamic: number };
+}
+
+/**
+ * The types an installed package publishes.
+ *
+ * Read through the TypeScript compiler rather than by parsing `.d.ts` text: a
+ * modern package's exported types are built out of generics, conditionals and
+ * mapped types, which have no meaning until something resolves them. Parsing
+ * gives back the machinery; asking the compiler gives back the answer.
+ *
+ * The compiler comes in under the alias `tsc-api`, pinned to the 5.x line,
+ * because TypeScript 7 is Go-native and ships no JavaScript API until 7.1. So
+ * 7 builds this repo and 5.9 is a library this one package calls.
+ *
+ * @returns every export as a {@link TypeSpec}, with a count of how many came
+ * back `dynamic`. A package that ships no types is not an error: `exports` is
+ * empty and `covered.total` is zero.
+ */
+export function readPackageTypes(args: {
+  /** The package name, as it is imported. */
+  package: string;
+  /** A file to resolve from, such as the generated `package.json` in `target/`. */
+  from: string;
+}): PackageTypes {
+  const declarations = declarationFile(args);
+  if (!declarations) return empty(args.package);
+  const program = ts.createProgram([declarations], OPTIONS);
+  const source = program.getSourceFile(declarations);
+  const checker = program.getTypeChecker();
+  const symbol = source && checker.getSymbolAtLocation(source);
+  if (!symbol) return empty(args.package);
+  return counted(args.package, exportsOf({ symbol, checker }));
+}
+
+const OPTIONS: ts.CompilerOptions = {
+  target: ts.ScriptTarget.ESNext,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  skipLibCheck: true,
+  strict: true,
+};
+
+/** Where the package's declarations are, as TypeScript itself resolves them. */
+function declarationFile(args: { package: string; from: string }): string | undefined {
+  const host = ts.createCompilerHost(OPTIONS);
+  const found = ts.resolveModuleName(args.package, args.from, OPTIONS, host);
+  const file = found.resolvedModule?.resolvedFileName;
+  // `.d.ts`, `.d.mts` and `.d.cts` are all declarations. zod ships the last of
+  // the three, so a filter naming only the first two finds nothing at all.
+  return file && /\.d\.[cm]?ts$/.test(file) ? file : undefined;
+}
+
+function exportsOf(args: { symbol: ts.Symbol; checker: ts.TypeChecker }): Record<string, TypeSpec> {
+  const out: Record<string, TypeSpec> = {};
+  const conv = { checker: args.checker, depth: 0, state: newState() };
+  for (const each of args.checker.getExportsOfModule(args.symbol)) {
+    const decl = each.valueDeclaration ?? each.declarations?.[0];
+    if (!decl) continue;
+    out[each.getName()] = toSpec(args.checker.getTypeOfSymbolAtLocation(each, decl), conv);
+  }
+  return out;
+}
+
+/**
+ * How much of the package came across.
+ *
+ * Counted and reported rather than claimed: "94% of exports typed" can be
+ * checked and driven up, unlike "fully compatible".
+ */
+function counted(name: string, exports: Record<string, TypeSpec>): PackageTypes {
+  const all = Object.values(exports);
+  return {
+    package: name,
+    exports,
+    covered: { total: all.length, dynamic: all.filter((one) => one.kind === "dynamic").length },
+  };
+}
+
+function empty(name: string): PackageTypes {
+  return { package: name, exports: {}, covered: { total: 0, dynamic: 0 } };
+}