seams library

A source-level engine for package-boundary audits ("seams").

A repository states its boundaries as rules — which entry point may reach which package, which package may depend on which, where a name may be declared — and checks them against the source on every run, so a boundary is a check with an exit code rather than a sentence in a design document. This library is the engine those rules are written in; the rules themselves are the repository's.

Every check reads files; nothing here parses with the analyzer or runs a process, so an audit over a large repository runs in seconds.

Classes

EntryPointRule
What a single entry point may not reach.
PublicDeclaration
One public top-level declaration in an entry point's export namespace.
Pubspec
A parsed pubspec.yaml: the package name plus every declared dependency, across all three blocks.
SeamViolation
One boundary crossing, named by the seam it belongs to.
UpwardDerivation
One place a source derives a directory by climbing.

Properties

directiveLinePattern → RegExp
An import or export directive on one line; group 1 is its URI.
final

Functions

auditEntryPointRules(String root, List<EntryPointRule> rules, {required String seam}) → List<SeamViolation>
Checks every rule in rules against the packages under root, reporting each crossing under seam.
callArgumentsFrom(String source, int open) → String
The text between the parenthesis that ends at open and its match.
dartCodeWithoutComments(String source) → String
source with its comments removed and everything else — string literals included — kept, newlines and all.
declaredTypeNamesUnder(String directory) → Set<String>
The type names (class, mixin, enum, extension, typedef) declared at the start of a line in any .dart file under directory.
dependencyReach(Pubspec root, {required bool isBanned(String package), Map<String, Pubspec?>? pubspecs}) → ({Map<String, List<String>> reached, Set<String> unresolved})
The packages isBanned matches that root reaches — each with the dependency chain that reaches it — and the hosted dependencies the walk could not follow because root was never resolved.
directiveUris(String source) → Iterable<String>
Every import / export URI in source, directives only.
exportedDeclarationsOf(String entryPoint) → Map<String, PublicDeclaration>
The public declarations entryPoint exports, keyed by name: its own, its parts', and those of every file it re-exports within its package, with show / hide applied.
externalImportsOf(String entryPoint) → Set<String>
The union of importClosureOf — what entryPoint links, in one set.
importClosureOf(String entryPoint) → Map<String, Set<String>>
The import closure of entryPoint within its own package: every file reached, mapped to the dart: and package: URIs it directly names.
packageImportsUnder(String directory) → Map<String, List<String>>
Every package: import appearing anywhere under directory, mapped to the files that carry it.
packageOf(String uri) → String
The package name of a package: URI (package:kdbx/kdbx.dart → kdbx).
packagesIn(String root) → List<Pubspec>
Every package directory directly under root that carries a pubspec.yaml.
prefixedPackagesIn(String workspaceRoot, String prefix, {int maxDepth = 3}) → List<Pubspec>
Every package whose directory is named prefix* under workspaceRoot, searched to maxDepth so a moved repository is found without walking the whole workspace.
reachableNamesOf(String entryPoint) → Set<String>
What entryPoint links, named the way a rule names it: a package name for package: URIs, the bare library for dart: ones (dart:io).
resolvedPackagesOf(String packageDir) → Map<String, String>?
Package name → its root directory in the graph pub get resolved for the package at packageDir, read from .dart_tool/package_config.json. Null when the package has not been resolved.
resolveRepositoryRoot(String from) → String
The repository: the nearest ancestor of from holding a tom_repository.yaml.
resolveWorkspaceRoot(String from) → String
The workspace: the nearest ancestor of from holding a .tom_metadata directory, which is what makes it the workspace.
runSeamAudits({required List<SeamAudit> audits, required String repositoryRoot, required String workspaceRoot, required String holds, bool quiet = false, StringSink? out, StringSink? err}) → int
Runs audits in order against repositoryRoot and workspaceRoot and prints one line per audit to out — ok <label>, or FAIL <label> with each violation under it — then holds when nothing crossed a boundary. With quiet, passing audits and the roots are not printed.
siblingImportClosureOf(String entryPoint, String root, {required String followPrefix}) → Map<String, Set<String>>
The import closure of entryPoint across sibling packages: every file reached, mapped to the URIs it names that the walk did not follow.
stripDartComments(String source) → String
source with comments removed and line breaks preserved.
topLevelDeclarations(String source) → List<({String kind, String name})>
The top-level declarations of source, public and private, in order.
upwardPathDerivations(String source) → List<UpwardDerivation>
Every place source derives a real directory by climbing a fixed number of levels.

Typedefs

SeamAudit = ({String label, List<SeamViolation> Function(String repositoryRoot, String workspaceRoot) run})
One audit a seam command runs: its label and the walk, given the repository root and the workspace root around it.