Architecture enforcement#

pnpm verify runs pnpm check:architecture against the checkout and pnpm test:architecture against isolated filesystem/package fixtures, after the strict format/lint/type/build/baseline/rule checks. All authored JS/TS variants are scanned. Prototypes receive the same checks.

One explicit policy#

tooling/architecture/policy.mts describes actual module roots, names, source entries, exact built export maps, private trees, permitted dependency directions, runtime environments, and dependencies that must load on demand. The lint rule and graph share this policy and the TypeScript resolver. Future foundation paths remain illustrative; the manifest does not require empty packages.

The current direction is embedding -> reporting/capture and reporting -> capture. Capture cannot depend on reporting, including its UI. Embedding must defer capture and reporting/browser. This encodes ownership/loading constraints, not product interfaces or an obligation to add dependencies to the empty packages.

Support trees currently contain docs and tooling. New root files, support trees (for example examples or CI), extensions, and conventional names require explicit registration. Support trees do not waive naming, package registration, imports, or cycles. Packages anywhere require a module registration. Only listed generated and dependency directories, Git metadata, and TypeScript build info are excluded.

Paths and exports#

Use lowercase kebab-case directory/file basenames, with .test or .spec for tests. Registered tool suffixes include .config, .build, .browser, .base, and .d. Catalog tests use .snag.md and may start with a numeric filename prefix for deterministic ordering. README.md, AGENTS.md, GLOSSARY.md, SKILL.md and existing dotfiles are explicit exceptions. Unknown dotfiles and suffixes fail. React symbol names may remain PascalCase. Symlinked authored source is rejected to avoid hidden ownership.

JavaScript exports must match registered types and import targets exactly, without extra subpaths or conditions. Optional CSS entries use exact registered relative .css string targets, without extra conditions; their source entries still count as UI for runtime boundary enforcement. Each source entry must exist with exact case. External callers must resolve to supported source entries. Package-name deep imports fail even if they target public source. Relative imports to public source and same-module private imports are valid.

Resolution uses actual files, inherited tsconfig aliases, and workspace entries. Aliases take precedence when they redirect workspace names. Slash styles are normalized; resolved spelling is checked against the filesystem, including on case-insensitive Windows. Invalid/unresolved local paths fail. Lint alone is not the unresolved-import check.

Dependencies and loading#

Static imports, re-exports, import types, import-equals, literal import() and require() contribute edges. Computed arguments fail: use a literal. The one registered exception is the deferred trusted project-module loader in tooling/testing/plan.mts, using the exact projectModuleUrl identifier. It is restricted to that tooling path; eager imports, require(), different identifiers, and module-source exceptions still fail. Project modules execute trusted local code and are outside the workspace dependency graph. File and module cycles include type/deferred edges; module cycles also include workspace dependencies declared in package manifests.

Runtime traversal starts at every supported entry and follows transitive helpers. Declaration-level import type / export type edges load nothing. With the required verbatimModuleSyntax setting, inline import { type View } and export { type View } retain empty runtime declarations and eagerly evaluate the target module, so they are runtime edges. Static imports and top-level dynamic imports, including immediately invoked functions, are eager. Imports in other functions are deferred. Deferred edges allow portable entries to reach optional browser/UI code; top-level import() does not. Portable/browser/UI entries cannot reach server code even lazily; server entries cannot reach browser/UI code. CSS and JSX source count as UI.

Classify external runtime dependencies in externalEnvironments when adding them. React/React DOM are UI; Node built-ins are server-only. Unknown external runtime dependencies fail closed, including deferred ones. Longest matching module zones refine the default environment, separating browser/UI source from portable entries.

This source graph does not evaluate arbitrary JavaScript, infer calls to separately declared functions at initialization, inspect external packages' transitive contents, or interpret CSS imports/HTML script tags. Review initialization calls and external classifications. Retain #26's built-consumer/selective-loading checks for actual runtime and bundler behavior.

Evolve the policy#

Move source and update its root/entries/exports/private zones together. Register new packages with their dependencies/environments, and update workspace, TypeScript, build and lint configuration without relaxing strictness. Add path exceptions individually. Do not allowlist a prototype or disable checks. Changes to accepted foundation responsibilities need a recorded decision.

Add passing/failing isolated fixtures in tooling/architecture/check.test.mts for each new category or meaningful regression. Tests create real package trees and tsconfig files, assert diagnostics, and remove only their own fixtures. An actual module move demonstrates policy evolution. Run pnpm test:architecture, then pnpm verify. Diagnostics identify naming/layout, packages/exports, private and unsupported imports, casing/resolution, dependency direction, computed imports, runtime boundaries, eager optional dependencies, external classification, and file/module cycles.