Boundaries

Boundaries enforce import direction between architectural zones. A zone groups files by glob pattern; a rule declares which zones may import from which. Violations appear as boundary-violation issues in fallow dead-code output.

Two optional sections extend zones beyond import direction: coverage reports source files that fall outside every zone, and calls bans specific callees per zone.

For preset descriptions, output formats, and suppression, see Architecture boundaries.

Presets

Fallow ships four built-in presets for common architecture patterns:

{
  "boundaries": {
    "preset": "bulletproof"
  }
}

tsconfig rootDir detection

When a preset is active, fallow reads compilerOptions.rootDir from tsconfig.json to determine the source root for zone patterns. Preset zones become {rootDir}/{zone}/**.

The detection logic:

1. Reads tsconfig.json from the project root (supports JSONC with comments and trailing commas)
2. Extracts compilerOptions.rootDir
3. Strips a leading ./ prefix and any trailing /
4. Rejects ., .., and absolute paths for security
5. Falls back to src if the field is missing, the file doesn't exist, or the value is rejected

{
  "compilerOptions": {
    "rootDir": "./lib"
  }
}

With the hexagonal preset, this produces zones:

lib/adapters/**
lib/ports/**
lib/domain/**

Custom zones

Define zones manually when presets don't match your architecture. Each zone has:

{
  "boundaries": {
    "zones": [
      { "name": "ui", "patterns": ["src/components/**", "src/pages/**"] },
      { "name": "data", "patterns": ["src/db/**", "src/api/**"] },
      { "name": "shared", "patterns": ["src/lib/**", "src/utils/**"] }
    ]
  }
}

Zone classification rules:

• A file belongs to the first zone whose pattern matches (first-match wins)
• Files that don't match any zone are unrestricted -- they can import from and be imported by any zone
• Zone order matters: place more specific patterns before broader ones

Auto-discovered zones

Use autoDiscover for feature-module boundaries where every immediate child directory should become its own zone. Rules can still reference the logical parent; fallow expands them to the discovered child zones.

{
  "boundaries": {
    "zones": [
      { "name": "app", "patterns": ["src/app/**"] },
      { "name": "features", "patterns": ["src/features/**"], "autoDiscover": ["src/features"] },
      { "name": "shared", "patterns": ["src/shared/**"] }
    ],
    "rules": [
      { "from": "app", "allow": ["features", "shared"] },
      { "from": "features", "allow": ["shared"] }
    ]
  }
}

If src/features/auth and src/features/billing exist, fallow list --boundaries shows features/auth and features/billing, and sibling feature imports are checked as cross-zone imports. Explicit child rules, such as from: "features/auth", override generated parent rules regardless of rule order.

When the zone also has patterns, discovered child zones are matched first and top-level files inside the auto-discover directory fall back to the parent zone. The parent fallback rule automatically allows its discovered children, so a src/features/index.ts barrel can re-export feature modules without surfacing features → features/<child> violations, while non-barrel top-level files such as src/features/types.ts still obey the parent features rule. Generated child rules keep the original allow list exactly, so sibling-feature isolation is preserved. Omit patterns from the zone when you want only discovered child directories classified and top-level files left unrestricted.

Custom rules

Rules define which zones may import from which. Each rule has:

{
  "boundaries": {
    "zones": [
      { "name": "ui", "patterns": ["src/components/**", "src/pages/**"] },
      { "name": "data", "patterns": ["src/db/**", "src/api/**"] },
      { "name": "shared", "patterns": ["src/lib/**", "src/utils/**"] }
    ],
    "rules": [
      { "from": "ui", "allow": ["shared"] },
      { "from": "data", "allow": ["shared"] },
      { "from": "shared", "allow": [] }
    ]
  }
}

Rule semantics:

• Self-imports are always allowed -- files within the same zone can freely import each other
• No rule entry means the zone is unrestricted -- it can import from any zone
• Empty allow list means the zone is isolated -- no cross-zone imports permitted
• Only zones with an explicit rule entry are constrained

Type-only imports across boundaries

TypeScript projects sometimes need type-level contracts between modules that must not have runtime dependencies on each other. A plugin system, for example, may declare a contribution interface in one feature that consumers in other features depend on at the type level only:

// features/metrics-panel/extension-api.ts
export interface MetricsPanelContribution { items?: MetricItemProvider[]; }

// features/extra-metrics/index.ts
import type { MetricsPanelContribution } from '#/features/metrics-panel/extension-api';

The import is fully erased at compile time, so it carries no runtime coupling. To admit it without opening the full allow list to the target zone, add allowTypeOnly:

{
  "boundaries": {
    "rules": [
      {
        "from": "features/extra-metrics",
        "allow": [],
        "allowTypeOnly": ["features/metrics-panel"]
      }
    ]
  }
}

What allowTypeOnly admits:

• Whole-declaration type imports: import type { Foo } from '...'
• Namespace type imports: import type * as ns from '...'
• Inline-type imports where every named specifier carries the type qualifier: import { type Foo } from '...'
• Type-only re-exports: export type { Foo } from '...'

What it does NOT admit:

• Mixed-specifier imports where at least one specifier is value-typed (import { type Foo, Bar }) -- the runtime dependency on Bar still fires a violation
• Plain value imports (import { Foo } from '...')
• Side-effect imports (import '...') -- these run the target at runtime

Semantics:

• allowTypeOnly is independent of allow. A type-only edge is admitted if its target zone is in EITHER list.
• The default value is an empty list, so omitting the field preserves pre-feature behavior exactly.
• No preset (Layered, Hexagonal, FeatureSliced, Bulletproof) defaults the field on; type-only crossings are opt-in per rule.

Merging presets with custom config

When both preset and zones/rules are specified, fallow merges them:

• Zones with the same name as a preset zone replace the preset zone entirely
• Rules with the same from as a preset rule replace the preset rule
• New zones and rules are added on top of the preset

Example: override a preset zone

Use the hexagonal preset but put your domain code in src/core instead of src/domain:

{
  "boundaries": {
    "preset": "hexagonal",
    "zones": [
      { "name": "domain", "patterns": ["src/core/**"] }
    ]
  }
}

This keeps adapters and ports from the hexagonal preset but replaces the domain zone pattern with src/core/**. All three rules remain unchanged.

Boundary coverage

Zones only constrain files they match; anything unmatched is unrestricted. To catch source files that silently fall outside every zone, enable coverage:

{
  "boundaries": {
    "zones": [
      { "name": "domain", "patterns": ["src/domain/**"] }
    ],
    "coverage": {
      "requireAllFiles": true,
      "allowUnmatched": ["src/generated/**"]
    }
  }
}

Semantics:

• Coverage only runs when requireAllFiles is true; the default keeps unmatched files unrestricted, preserving pre-coverage behavior.
• Findings share the boundary-violation rule severity and suppression token.
• Combine with forbidden calls so a zone-scoped call policy cannot be bypassed by leaving files unzoned.

Prefer allowUnmatched over file-level suppression comments for generated code: the config keeps the exemption in one reviewable place.

Forbidden calls

To ban specific calls from a zone (for example, keeping a domain layer free of process execution and logging), add a forbidden-call policy:

{
  "boundaries": {
    "zones": [
      { "name": "domain", "patterns": ["src/domain/**"] }
    ],
    "calls": {
      "forbidden": [
        { "from": "domain", "callee": "child_process.*" },
        { "from": "domain", "callee": ["console.*", "process.exit"] }
      ]
    }
  }
}

Each matching call reports as a boundary_call_violations finding naming the written callee, the matched pattern, and the zone.

Matching semantics:

• Segment-aware, not substring or glob: fetch matches only fetch (never myfetch), a trailing object.* matches any member (child_process.* matches child_process.exec), and a leading *.member matches any object (*.innerHTML matches el.innerHTML).
• Import provenance: patterns match through imports, so child_process.* covers import { execSync } from "node:child_process", the bare child_process specifier, namespace imports, and default imports alike.
• Direct callee paths only, optional chaining included (cp?.exec() matches like cp.exec()). Aliased or re-bound callees (const run = cp.exec; run()), computed members, and injected dependencies (this.client.exec()) are not followed.
• Zoned files only: rules apply only to files classified into a zone; unzoned files are unrestricted. Combine with coverage.requireAllFiles to force zoning first.
• One finding per unique callee path per file: when several rules could match, the first applicable rule in config order wins. Fixing the first call site surfaces the next occurrence of the same callee on a rerun.
• Inert patterns such as a bare * are rejected at config load, and a rule pointing at a zone that matches no files warns at analysis time.

Severity and suppression: forbidden-call findings inherit the boundary-violation rule (default error) and suppression token; the rule-id-shaped boundary-call-violation and boundary-call-violations tokens are accepted as aliases. Any of these tokens suppresses the whole boundary family on that line or file.

Inspecting boundaries

Use fallow list --boundaries to see the expanded configuration after preset expansion and merging. This is the fastest way to verify your config is correct.

Boundaries: 4 zones, 4 rules

Zones:
  app                  3 files  src/app/**
  features             12 files src/features/**
  shared               8 files  src/components/**, src/hooks/**, src/lib/**, ...
  server               4 files  src/server/**

Rules:
  app                  → features, shared, server
  features             → shared, server
  server               → shared
  shared               (isolated, no imports allowed)

For scripting or MCP tools, use JSON output:

fallow list --boundaries --format json --quiet

Common patterns

{
  "boundaries": {
    "zones": [
      { "name": "web-ui", "patterns": ["apps/web/src/components/**", "apps/web/src/pages/**"] },
      { "name": "web-data", "patterns": ["apps/web/src/api/**", "apps/web/src/hooks/**"] },
      { "name": "shared-ui", "patterns": ["packages/ui/src/**"] },
      { "name": "shared-utils", "patterns": ["packages/utils/src/**"] }
    ],
    "rules": [
      { "from": "web-ui", "allow": ["web-data", "shared-ui", "shared-utils"] },
      { "from": "web-data", "allow": ["shared-utils"] },
      { "from": "shared-ui", "allow": ["shared-utils"] },
      { "from": "shared-utils", "allow": [] }
    ]
  }
}

// fallow-ignore-file boundary-violation
import { authRouter } from '../features/auth/router'
import { billingRouter } from '../features/billing/router'

export const appRouter = router({
  auth: authRouter,
  billing: billingRouter,
})

{
  "boundaries": {
    "preset": "bulletproof",
    "rules": [
      { "from": "server", "allow": ["shared", "features"] }
    ]
  }
}

{
  "boundaries": {
    "preset": "bulletproof",
    "zones": [
      { "name": "test", "patterns": ["src/**/*.test.ts", "src/**/*.spec.ts", "src/__tests__/**"] }
    ],
    "rules": [
      { "from": "test", "allow": ["app", "features", "shared", "server"] }
    ]
  }
}

See also