Skip to content

Surface

surface restricts what a file exports: which names, declared as what, and how many. (To restrict who may import a name, use exports.)

"*.handler.ts":
surface:
- message: "A handler exports exactly one function."
declares: [function]
count: { min: 1, max: 1 }
- message: "A handler's name is camelCase: `{name}` is not."
kinds: [named]
convention: camelCase

surface is a list. Each entry selects some exports, then makes one demand of them. An entry with two demands fails to load; write two entries. Written on a folder, a rule covers the subtree.

Selector Meaning
kinds named, default, namespace (export * and export * as).
declares What the export was declared as: function, class, variable, type, interface, enum, expression, other.
reexport true selects only export … from "m"; false only what the file declares.
match Exported names to select. Omit for all.
matchNot Names removed from match.
except Files under this node the rule skips.
Demand Meaning
(none) Forbid: any selected export is a violation. forbid: true says so explicitly.
allow Names that are fine. Any other selected name is a violation.
convention kebab-case, camelCase, PascalCase, snake_case or { regex }.
count { min, max } selected exports per file. At least one of min/max is required.

message is required. {name} in it is replaced with the offending name. probe is covered below.

Each top-level exported name, using the exported name, not the local one:

export const a = 1,
b = 2; // named a, named b (variable)
export default class Main {} // default (class)
export { Todo } from "./todo.js"; // named Todo, re-export (declares `other`)
export * from "./ids.js"; // namespace *, re-export

Exports inside a namespace body and export = aren’t counted.

No default exports:

"src/":
surface:
- message: "No default exports; a name is greppable."
kinds: [default]

A barrel only re-exports:

"index.ts":
surface:
- message: "A barrel re-exports; `{name}` is declared here."
reexport: false

Other one-liners: kinds: [namespace] forbids export *; count: { max: 0 } on "*.test.ts" keeps tests from exporting.

An authored probe is a source snippet the rule must report something out of, or the policy fails to load.

probe:
source: "export default function main() {}"

See Probes.