Skip to content

Structure

Structure rules check whether a file may exist where it is, and whether the files it needs exist beside it. Use them to stop stray files like session-utils.ts drifting into a folder.

"@/modules/{module}/commands/":
message: "commands/ holds a *.command.ts and a *.handler.ts with its test."
name: kebab-case
children:
"*.command.ts": {}
"*.handler.ts": { requires: ["{base}.test.ts"] }
"*.handler.test.ts": {}
Field Meaning
children Folder only. The filenames and subfolders it admits. Anything else is a violation.
layout open: the folder admits any filename. Only its subfolders are checked.
name Naming convention for concept names. Inherited by the subtree. See Naming.
requires Files that must exist beside this one. See Required siblings.
requiresNot Filenames requires skips.
message Reported when a file is refused.

A folder with children is deny-by-default: a file matching no key is reported with the folder’s message. An empty body ({}) just admits the filename.

For a folder with no filename scheme, such as a component library, write layout: open. It still counts as described, so the stray-folder check skips it.

name fixes the casing that *.handler.ts leaves open, such as CreateTodo.handler.ts versus create-todo.handler.ts.

"~/server/src/": { name: kebab-case } # inherited by the whole subtree
"~/contracts/src/": { name: PascalCase }
Value Shape
kebab-case lowercase words joined by hyphens
camelCase lowercase first word, then capitalized ones
PascalCase capitalized words, no separators
snake_case lowercase words joined by underscores
{ regex, message? } anything else, with a sentence saying why
{ like, message? } equal to an ancestor capture

On a folder, name checks:

  • the folder’s own segment, if its key has a capture (@/modules/{module}/ refuses Todos_V2/);
  • the concept name of every file directly inside it.

A file’s concept name is its basename up to the first dot: in todos.repository-live.ts it’s todos.

Use like on a file node to require a file be named after its folder:

"@/modules/{module}/domain/{subdomain}/":
children:
"*.root.ts": { name: { like: "{subdomain}" } }

So todo/ must hold todo.root.ts. A like naming a capture no ancestor declares fails to load.

Each missing file is reported separately.

"*.repository.ts":
message: "A repository port needs a live adapter and a fake."
requires:
- "../../infrastructure/repositories/{base}-live.ts"
- "../../infrastructure/repositories/{base}-fake.ts"
requiresNot: ["*.read-only.repository.ts"]
  • {base} is the filename minus its final extension: create-todo.handler.ts gives create-todo.handler, so "{base}.test.ts" is create-todo.handler.test.ts.
  • ../ resolves against the file’s own folder.
  • requiresNot lists filenames the rule skips.

Each top-level tree node that lists its contents also reports folders no rule describes, such as a new modules/user/helpers/. It reports the folder, not each file. To describe only part of a folder, use partial: true (see Inheritance).