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": {}Fields
Section titled “Fields”| 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. |
Allowed files: children
Section titled “Allowed files: children”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.
Naming
Section titled “Naming”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}/refusesTodos_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.
Required siblings
Section titled “Required siblings”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.tsgivescreate-todo.handler, so"{base}.test.ts"iscreate-todo.handler.test.ts.../resolves against the file’s own folder.requiresNotlists filenames the rule skips.
Stray folders
Section titled “Stray folders”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).