import fs from "node:fs";
import path from "node:path";
import ts from "typescript";
import { REPO_ROOT, readProviderNames } from "./provider-inventory.mjs";
/**
* The provider export surface: which `*Namespace` types a provider declares as
* public in its `src/**\/*.ts` modules, and which of them its `src/index.ts`
* actually re-exports.
*
* `FalRunNanoBanana2LiteNamespace` was declared `export interface` in
* `packages/provider/fal/src/types.ts` and never named in `index.ts`, so no
* consumer of `@apicity/fal` could reach it. It passed lint, passed
* `tsc --noEmit` (the declaration is used inside `types.ts`), and passed the
* whole Polly replay suite; it was caught by eye in review (`ac-c2cc4j`
* finding `G2` / `RR-2`, follow-up `FU-1`, filed as `ac-gvqa18`). No gate in
* this repository observes a declared-but-unexported public type, and the same
* defect was live on `main` in the same model family.
*
* Reading and checking are kept apart, following the
* `scripts/lib/provider-inventory.mjs` precedent: `read*` touches the
* filesystem, `checkExportSurface` is pure surfaces-in/problems-out. That is
* what lets the guard drive the ratchet from synthetic surfaces instead of
* depending on whichever defect happens to be live in the tree.
*
* A surface is one declaring *file*, not one provider. The first cut read
* `src/types.ts` alone, which holds 407 of the 414 exported namespaces in the
* tree; the other seven — four in b2's `s3-types.ts`, three in kie's
* `responses.ts` — are all public today, so that reading hid no live defect.
* What it hid was the *reachability* of one: a new namespace added to
* `kie/src/responses.ts` and left out of `index.ts` reproduces `RR-2` exactly
* while the guard stays green, in a file the guard never opened. Widening the
* file set forces the star-export skip to become per module as well — b2's
* star is at `./s3-types`, so skipping the whole provider would drop its
* `types.ts` from the guard, and checking the whole provider would report four
* public names as missing.
*
* Two things this module deliberately does NOT do:
*
* - It never builds a `ts.Program`. Both `tests/unit/request-input-types.test.ts`
* and `tests/unit/fal-request-input-types.test.ts` do, under a 120s
* timeout, and this checker runs in the cross-cutting block of every
* provider's fast gate. Parse-only `ts.createSourceFile` stays cheap
* enough that widening the file set from the 29 `types.ts` files to the
* 216 flat `src/*.ts` modules cost +0.40s per walk, and recursing below
* `src/` afterwards cost +0.107s more (both measured in
* `scripts/lib/cross-cutting-tests.mjs`, each on its own machine); neither
* moved `CROSS_CUTTING_COST_SECONDS`. The importability proof that
* genuinely needs a program lives in the fal-scoped
* `tests/fixtures/fal-request-input-types.ts` fixture instead.
* - It parses each module exactly once. Declarations, named re-exports and
* star re-exports come out of a single `walkModule` pass, because with 235
* modules in the walk a second parse would cost as much again as the
* widening itself.
*
* The walk is `src/**\/*.ts` at any depth (`ac-bsl9tx`). A provider that
* declares an exported `*Namespace` under `src/
/` and leaves it out of
* `index.ts` reproduces `RR-2` one directory down, in a file a flat walk never
* opens; no provider declares one below `src/` today, so what recursion buys is
* coverage of the next one that does. Three rules keep it precise:
*
* - Only the provider's own depth-0 `index.ts` is excluded. A namespace
* declared there is exported by construction; `src//index.ts` carries
* no such guarantee and is a declaring surface like any other module.
* - A `.d.ts` is skipped. `moduleKey` strips only the final extension, so a
* nested one would otherwise be advised as `from ".//foo.d"`.
* - A directory-style star specifier resolves to that directory's barrel,
* in {@link resolveStarExportedModules} rather than at parse time, which
* keeps `walkModule` filesystem-free.
*/
/**
* One declaring file's export surface.
*
* @typedef {{
* provider: string,
* sourcePath: string,
* indexPath: string,
* declarations: { name: string, line: number }[] | null,
* exportedNames: string[] | null,
* starExportedModules: string[],
* }} ExportSurface
*/
/** Where the baseline the problem messages point at actually lives. */
const BASELINE_FILE = "tests/unit/provider-export-surface.test.ts";
/** The extensions a module specifier may carry and a module key may not. */
const MODULE_EXTENSION = /\.(m?[jt]s)$/;
/**
* Parse source text with parent pointers, which `ts.getCombinedModifierFlags`
* and `node.getStart` both need.
*
* @param {string} fileName Used for line reporting and for resolving a star
* export's module specifier; it need not exist on disk.
* @param {string} source
* @returns {ts.SourceFile}
*/
function parseSourceFile(fileName, source) {
return ts.createSourceFile(
fileName,
source,
ts.ScriptTarget.Latest,
/* setParentNodes */ true,
ts.ScriptKind.TS
);
}
/**
* The identity a file and a module specifier are compared under: the path
* without its extension. `packages/provider/b2/src/s3-types.ts` and the
* `"./s3-types"` in `b2/src/index.ts` both reduce to
* `packages/provider/b2/src/s3-types`.
*
* @param {string} filePath
* @returns {string}
*/
function moduleKey(filePath) {
return filePath.replace(MODULE_EXTENSION, "");
}
/**
* How a module would be written as a specifier in the provider's `index.ts`,
* for problem messages: `packages/provider/kie/src/responses.ts` reads back as
* `./responses`, and `packages/provider/cost/src/pricing/fal.ts` as
* `./pricing/fal`. The specifier is relative to the provider's `src/` rather
* than a bare basename, which would print `./fal` for the nested module —
* advice that names a file that does not exist.
*
* @param {string} filePath
* @param {string} indexPath The provider's `src/index.ts`; what the specifier
* is written relative to. Every surface of a provider carries the same one.
* @returns {string}
*/
function moduleSpecifier(filePath, indexPath) {
const from = path.posix.dirname(indexPath);
return `./${path.posix.relative(from, moduleKey(filePath))}`;
}
/**
* Walk one module for everything the guard reads out of it, in a single parse.
*
* The `*Namespace` walk is top-level only — all 414 namespaces in the tree are
* declared at file scope, so `ts.forEachChild` at that depth loses nothing.
* `export` on the declaration is the signal of public intent; a module-private
* helper such as fal's bare `type FalNanoBanana2LiteTextToImageFn` is not one
* and is correctly out of reach.
*
* Both re-export forms the repository actually uses are handled:
*
* - a `NamedExports` clause — 27 providers hand-list every name;
* - no export clause at all with a module specifier, i.e.
* `export * from ...` / `export type * from ...`, which publishes every
* declaration in the named module. Only relative specifiers are collected:
* `export * from "some-package"` republishes that package's names and says
* nothing about any file in this walk.
*
* Reading the AST rather than the text satisfies REQ-011: a name inside a
* comment, a string literal, or a disabled block is not an export element and
* can neither satisfy nor trip the rule.
*
* Aliases contribute both sides (`element.name.text` and
* `element.propertyName?.text`). This is deliberately over-permissive: for
* `export type { BarNamespace as FooNamespace }` a declared `FooNamespace`
* would count as exported although only `BarNamespace` escapes. The tree holds
* exactly one aliased re-export (`kie/src/index.ts:421`,
* `sseDataToIterable as sseToIterable`) and it is not a namespace, so the
* false negative is hypothetical; collecting both keeps a renamed re-export
* from being reported as a missing export, which is the likelier mistake.
*
* @param {string} modulePath Repo-relative or absolute; used for line
* reporting and as the base a relative specifier resolves against, so both
* sides of a module comparison come from this argument and agree either way.
* @param {string} source
* @returns {{
* declarations: { name: string, line: number }[],
* names: string[],
* starExportedModules: string[],
* }} Declarations in file order, with 1-based line numbers so a problem
* message can cite `types.ts:1810`.
*/
function walkModule(modulePath, source) {
const sourceFile = parseSourceFile(modulePath, source);
const directory = path.posix.dirname(modulePath);
/** @type {{ name: string, line: number }[]} */
const declarations = [];
/** @type {string[]} */
const names = [];
/** @type {string[]} */
const starExportedModules = [];
ts.forEachChild(sourceFile, (node) => {
if (ts.isInterfaceDeclaration(node)) {
if (!node.name.text.endsWith("Namespace")) return;
const flags = ts.getCombinedModifierFlags(node);
if (!(flags & ts.ModifierFlags.Export)) return;
const { line } = sourceFile.getLineAndCharacterOfPosition(
node.getStart(sourceFile)
);
declarations.push({ name: node.name.text, line: line + 1 });
return;
}
if (!ts.isExportDeclaration(node)) return;
if (node.exportClause === undefined) {
if (!node.moduleSpecifier || !ts.isStringLiteral(node.moduleSpecifier)) {
return;
}
const specifier = node.moduleSpecifier.text;
if (!specifier.startsWith(".")) return;
starExportedModules.push(
path.posix.normalize(
path.posix.join(directory, specifier.replace(MODULE_EXTENSION, ""))
)
);
return;
}
if (!ts.isNamedExports(node.exportClause)) return;
for (const element of node.exportClause.elements) {
names.push(element.name.text);
if (element.propertyName) names.push(element.propertyName.text);
}
});
return { declarations, names, starExportedModules };
}
/**
* The exported, top-level `*Namespace` interfaces one module declares.
*
* Pure — source text instead of a path — so the guard can assert the rule
* against synthetic files that do not exist on disk: a `Namespace` name inside
* a comment or a string literal, an interface with no `export` modifier
* (REQ-011).
*
* @param {string} modulePath Repo-relative or absolute; used only for labelling.
* @param {string} source
* @returns {{ name: string, line: number }[]}
*/
export function parseNamespaceDeclarations(modulePath, source) {
return walkModule(modulePath, source).declarations;
}
/**
* What one module publishes: hand-listed names, and the modules it re-exports
* wholesale.
*
* `starExportedModules` holds module keys resolved against `indexPath`'s own
* directory, so they compare directly against a surface's `sourcePath`. It is
* the direct, one-hop set; {@link resolveStarExportedModules} closes it.
*
* @param {string} indexPath Repo-relative or absolute.
* @param {string} source
* @returns {{ names: string[], starExportedModules: string[] }}
*/
export function parseExportedNames(indexPath, source) {
const { names, starExportedModules } = walkModule(indexPath, source);
return { names, starExportedModules };
}
/**
* The filesystem half: parse one module on disk, labelled by its repo-relative
* path so problem messages and module keys read the same from any checkout.
*
* @param {string} absolutePath
* @param {string} label Repo-relative path, used for reporting and resolution.
* @returns {ReturnType}
*/
function readModule(absolutePath, label) {
return walkModule(label, fs.readFileSync(absolutePath, "utf8"));
}
/**
* Close a star-export seed under the star exports of the modules it reaches.
*
* One hop is not enough, and the tree already proves it:
* `telegram/src/index.ts:3` is `export type * from "./types"` and
* `telegram/src/types.ts:4` is `export type * from "./zod"`, so every
* declaration in `telegram/src/zod.ts` is public two hops out. Stopping at one
* would report such a declaration as unexported while it is fully reachable —
* a false positive that reds a correct change, the mirror image of the false
* negative this guard exists to catch.
*
* The walk is over modules that were parsed anyway, so it reads no files. The
* `reached` guard is also what terminates a cycle.
*
* @param {string[]} seed Module keys `index.ts` star-exports directly.
* @param {Map} starsByModule Module key to the module keys
* that module itself star-exports.
* @returns {string[]} The fixed point, sorted.
*/
export function resolveStarExportedModules(seed, starsByModule) {
/** @type {Set} */
const reached = new Set();
/** @type {string[]} */
const queue = [];
const visit = (key) => {
if (reached.has(key)) return;
reached.add(key);
queue.push(key);
// A directory specifier names that directory's barrel: `export * from
// "./pricing"` in index.ts is `src/pricing/index.ts` on disk. The map is
// keyed by every module in the walk, stars or none, so `has(key)` reads as
// "a `.ts` exists" — a real sibling module therefore wins over a
// same-named directory, matching TypeScript's own resolution order.
if (!starsByModule.has(key) && starsByModule.has(`${key}/index`)) {
visit(`${key}/index`);
}
};
for (const key of seed) visit(key);
while (queue.length > 0) {
const current = queue.pop();
for (const next of starsByModule.get(current) ?? []) visit(next);
}
return [...reached].sort();
}
/**
* Every `.ts` module under one provider's `src/`, `src`-relative and in a
* deterministic pre-order: entries sorted by name at each level — by code
* unit, matching both the flat `.sort()` this replaces and `listHarFiles` in
* `scripts/lib/fal-credential-hosts.mjs`, neither of which uses the
* locale-sensitive `localeCompare` — with directories descended in place.
*
* The recursion is written out rather than delegated to `readdirSync`'s
* `{ recursive: true }` so the file filter and the ordering stay visible at the
* one place that decides what the guard reads.
*
* @param {string} directory Absolute path to walk.
* @param {string} [prefix] The `src`-relative path of `directory`.
* @returns {string[]} `src`-relative module paths, POSIX-shaped.
*/
function listSourceModules(directory, prefix = "") {
/** @type {string[]} */
const modules = [];
const entries = fs
.readdirSync(directory, { withFileTypes: true })
.sort((left, right) =>
left.name < right.name ? -1 : left.name > right.name ? 1 : 0
);
for (const entry of entries) {
const relativePath = prefix
? path.posix.join(prefix, entry.name)
: entry.name;
if (entry.isDirectory()) {
modules.push(
...listSourceModules(path.join(directory, entry.name), relativePath)
);
continue;
}
if (!entry.isFile() || !entry.name.endsWith(".ts")) continue;
// A generated `.d.ts` is not a declaring surface. `moduleKey` strips only
// the final extension, so a nested one would produce the fix message
// `from ".//foo.d"` — the REQ-006 defect one directory down. None
// exists in the tree today, and recursion is what would first reach one.
if (entry.name.endsWith(".d.ts")) continue;
modules.push(relativePath);
}
return modules;
}
/**
* Read one export surface per declaring file on disk.
*
* Provider discovery is `readProviderNames` and module discovery is the
* recursive walk, so a new package, a new file inside an existing one, and a
* new file in a new subdirectory are all covered the day they land rather than
* when someone remembers a list.
*
* The provider's own `src/index.ts` is not a surface: a namespace declared
* there is exported by construction. That exclusion is depth-0-specific, and
* deliberately so — `src//index.ts` carries no such guarantee, so a
* namespace declared in a nested barrel is checked like any other declaration
* and is what puts the barrel's own module key into the star map that
* {@link resolveStarExportedModules} aliases a directory specifier onto.
*
* A provider whose `src/index.ts` is missing yields surfaces with a `null`
* `exportedNames`; `checkExportSurface` skips those rather than treating them
* as violations (REQ-003). One whose `src/` holds nothing but `index.ts`
* yields no surface at all, which is the same answer by a shorter route. No
* provider is in either state today — all 29 ship both files — but the shape is
* what the guard asserts against instead of assuming.
*
* @param {string} [repoRoot]
* @returns {ExportSurface[]} Surfaces with repo-relative paths, so problem
* messages read the same from any checkout and synthetic surfaces can be
* written by hand.
*/
export function readProviderExportSurfaces(repoRoot = REPO_ROOT) {
/** @type {ExportSurface[]} */
const surfaces = [];
for (const provider of readProviderNames(repoRoot)) {
const sourceDirectory = path.join(
repoRoot,
"packages",
"provider",
provider,
"src"
);
if (!fs.existsSync(sourceDirectory)) continue;
const relative = (file) =>
path.posix.join("packages", "provider", provider, "src", file);
const indexPath = relative("index.ts");
const indexFile = path.join(sourceDirectory, "index.ts");
const index = fs.existsSync(indexFile)
? readModule(indexFile, indexPath)
: null;
const modules = listSourceModules(sourceDirectory)
.filter((relativePath) => relativePath !== "index.ts")
.map((relativePath) => ({
sourcePath: relative(relativePath),
parsed: readModule(
path.join(sourceDirectory, relativePath),
relative(relativePath)
),
}));
const starExportedModules = index
? resolveStarExportedModules(
index.starExportedModules,
new Map(
modules.map((module) => [
moduleKey(module.sourcePath),
module.parsed.starExportedModules,
])
)
)
: [];
for (const module of modules) {
surfaces.push({
provider,
sourcePath: module.sourcePath,
indexPath,
declarations: module.parsed.declarations,
exportedNames: index ? index.names : null,
starExportedModules,
});
}
}
return surfaces;
}
/**
* A surface can only be checked when both halves of the rule are present.
*
* @param {{ declarations: unknown, exportedNames: unknown }} surface
* @returns {boolean}
*/
function isCheckable(surface) {
return surface.declarations !== null && surface.exportedNames !== null;
}
/**
* Whether this surface's own module is republished wholesale, in which case
* every declaration in it is already public and a name set would be the wrong
* answer rather than an incomplete one (DC-4).
*
* Per module, not per provider: b2 star-exports `./s3-types` and hand-lists
* everything else, so its `s3-types.ts` is skipped while its `types.ts` stays
* checked (DC-7).
*
* @param {{ sourcePath: string, starExportedModules: string[] }} surface
* @returns {boolean}
*/
function isStarExported(surface) {
return surface.starExportedModules.includes(moduleKey(surface.sourcePath));
}
/**
* Compare declared namespaces against re-exported names.
*
* Pure: everything it needs is in `surfaces` and `baseline`, which is what
* lets the guard assert the ratchet over synthetic input instead of over
* whichever defect is live in the tree today.
*
* Three problem classes, the last two being REQ-005's reverse ratchet — a
* baseline entry is a claim about the tree, and a claim that stopped being
* true is itself a failure:
*
* 1. declared, not exported, not baselined;
* 2. baselined but no longer declared;
* 3. baselined but now exported (including "already public by star export").
*
* A provider now contributes several surfaces, so a baseline entry is stale
* only once *every* module that declares it has stopped needing it.
*
* @param {ExportSurface[]} surfaces
* @param {Record>} baseline Provider to type
* name to rationale.
* @returns {string[]} Problem descriptions, empty when the surface is clean.
*/
export function checkExportSurface(surfaces, baseline) {
/** @type {string[]} */
const problems = [];
/** @type {Map} */
const byProvider = new Map();
for (const surface of surfaces) {
const known = byProvider.get(surface.provider);
if (known) known.push(surface);
else byProvider.set(surface.provider, [surface]);
}
for (const surface of surfaces) {
if (!isCheckable(surface)) continue;
if (isStarExported(surface)) continue;
const exported = new Set(surface.exportedNames);
const allowed = baseline[surface.provider] ?? {};
for (const declaration of surface.declarations) {
if (exported.has(declaration.name)) continue;
if (Object.hasOwn(allowed, declaration.name)) continue;
problems.push(
`${surface.provider}: ${declaration.name} is declared at\n` +
` ${surface.sourcePath}:${declaration.line} but never re-exported from\n` +
` ${surface.indexPath}.\n` +
" Fix: add it to the `export type { ... } from " +
`"${moduleSpecifier(surface.sourcePath, surface.indexPath)}"\` list in index.ts,\n` +
` or add a baseline entry in ${BASELINE_FILE}\n` +
" with a rationale."
);
}
}
const stale = (provider, name, because) =>
`${provider}: stale baseline entry ${name} — ${because}\n` +
` Remove it from EXPORT_SURFACE_BASELINE in ${BASELINE_FILE}.`;
for (const provider of Object.keys(baseline).sort()) {
const checkable = (byProvider.get(provider) ?? []).filter(isCheckable);
for (const name of Object.keys(baseline[provider]).sort()) {
if (checkable.length === 0) {
problems.push(
stale(
provider,
name,
`${provider} has no src/**/*.ts + src/index.ts pair under\n packages/provider/.`
)
);
continue;
}
const declaring = checkable.filter((surface) =>
surface.declarations.some((entry) => entry.name === name)
);
if (declaring.length === 0) {
problems.push(
stale(
provider,
name,
"no exported interface by that name is declared in\n" +
` ${path.posix.dirname(checkable[0].indexPath)}/**/*.ts.`
)
);
continue;
}
// The entry still earns its place while any module that declares the
// name is checked and does not export it.
const live = declaring.some(
(surface) =>
!isStarExported(surface) && !surface.exportedNames.includes(name)
);
if (live) continue;
const starred = declaring.find(isStarExported);
if (starred) {
problems.push(
stale(
provider,
name,
`${starred.indexPath} star-exports ` +
`${moduleSpecifier(starred.sourcePath, starred.indexPath)} (directly or\n` +
` transitively), so every declaration in ${starred.sourcePath}\n` +
" is already public."
)
);
continue;
}
problems.push(
stale(
provider,
name,
`it is now re-exported from ${declaring[0].indexPath}.`
)
);
}
}
return problems;
}