Rules are the core building blocks of psl. Each rule declares a structural primitive (its type), scopes itself to part of the tree, and enforces a constraint on the filesystem shape or a module's symbol population. psl never inspects imports or names — only the shape of the tree and how many symbols each module defines.

Structure¶

Every rule has two required fields, one optional field, and a set of type-specific options. Unlike pnl, there is no nested filter/naming block and no apply/modules key — each rule scopes itself with its own within, source, or mirror, and the type-specific options sit flat on the rule mapping:

rules:
  - name: my-rule              # Unique identifier, referenced in `# psl: ignore`
    type: directory-exists     # Which primitive to enforce
    description: ...           # (optional) shown in violation output
    within: src/contexts/{ctx}  # type-specific options follow, flat
    require: [domain, application]

The engine is neutral: your project's taxonomy (layer names, component directories, tree roots) lives entirely in the option values, never in the rule vocabulary.

Fields¶

An unknown type, an unknown option, a missing required option, or an invalid enum value is a configuration error and exits 2.

Rule types¶

Path patterns¶

within, and the tree roots in mirror, are project-root-relative paths whose segments may be:

File-targeting rules (symbol-count) match .py files; the others match directories. The top-level include and exclude keys narrow and drop scanned paths across all rules — except mirror, whose two trees are named explicitly.

directory-exists¶

Every directory matching within must contain each of the require directories.

Options¶

Example — every context declares its layers:

rules:
  - name: context-layers
    type: directory-exists
    description: Each context has domain, application, and adapters layers
    within: src/contexts/{ctx}
    require: [domain, application, adapters]

$ psl check
src/contexts/orders
    [context-layers] Each context has domain, application, and adapters layers
    missing required directory 'adapters'

Found 1 violation(s).

One violation is reported per missing directory, anchored to the scope directory.

allowed-children¶

A scope directory may contain only the allowed child names. With group_level: optional, a child directory that is not itself an allowed name is treated as a one-level grouping tier (e.g. a subdomain) and passes only if all of its children are allowed.

Options¶

kind values:

group_level values:

Example — the domain layer holds only recognized components, with subdomain grouping:

rules:
  - name: domain-components
    type: allowed-children
    description: The domain layer holds only recognized component directories
    within: src/contexts/{ctx}/domain
    kind: dir
    group_level: optional
    allow: [entities, value_objects, events, services, errors]
    ignore: [__init__.py]

$ psl check
src/contexts/orders/domain/repositories
    [domain-components] The domain layer holds only recognized component directories
    unexpected directory 'repositories' (not an allowed component)

src/contexts/orders/domain/shipping/repositories
    [domain-components] The domain layer holds only recognized component directories
    unexpected 'repositories' in grouping directory 'shipping'

Found 2 violation(s).

With group_level: none, shipping/ would itself be reported as unexpected directory 'shipping' (not an allowed component) rather than being inspected as a grouping tier.

mirror¶

The source and mirror trees must mirror each other at directory granularity. direction selects which way the requirement runs.

Options¶

direction values:

The top-level include does not apply to mirror — the two trees are named explicitly by source and mirror. A missing or mistyped source/mirror root is a configuration error and exits 2.

Example — the tests tree mirrors the src tree:

rules:
  - name: tests-mirror-src
    type: mirror
    description: The tests tree mirrors the src tree
    source: src
    mirror: tests
    direction: mirror-to-source
    mirror_extra_allowed: [doubles, fixtures, conftest]

$ psl check
tests/contexts/orders/domain/pricing
    [tests-mirror-src] The tests tree mirrors the src tree
    no source counterpart 'src/contexts/orders/domain/pricing'

Found 1 violation(s).

An extra-allowed name exempts only the orphan itself (a directory with no counterpart whose leaf name is exempt) and its subtree — a same-named directory that does have a counterpart is still fully checked below it.

symbol-count¶

Bound the number of top-level symbols (classes or functions) a module may define. Definitions wrapped in flow-control statements (try/except, if TYPE_CHECKING:, with, for, while, match) count as top level; definitions nested inside another class or function do not.

Options¶

* At least one of max / min is required, and both must be integers.

symbol values:

visibility values:

Example — one class per domain module:

rules:
  - name: one-class-per-domain-module
    type: symbol-count
    description: Domain modules define a single class
    within: src/contexts/{ctx}/domain/**
    symbol: class
    max: 1
    ignore_files: [__init__.py]

$ psl check
src/contexts/orders/domain/entities/order.py:24
    [one-class-per-domain-module] Domain modules define a single class
    2 top-level class definitions found, at most 1 allowed

Found 1 violation(s).

A max violation is anchored to <path>:<line>, where the line is the surplus symbol — the first definition beyond max. A min violation is anchored to the path alone.

Example — a single error class per errors module:

rules:
  - name: one-error-per-file
    type: symbol-count
    description: Each errors module defines a single error class
    within: src/contexts/{ctx}/domain/**/errors/**
    symbol: class
    max: 1
    ignore_files: [__init__.py]

So src/contexts/orders/domain/errors/order_not_found_error.py may hold only class OrderNotFoundError; a second error class in the same file is a violation.

Example — exactly one public function per checker module (min + max):

rules:
  - name: one-public-function-per-checker
    type: symbol-count
    description: Each checker exposes a single public entry point
    within: src/checks/**
    symbol: function
    visibility: public
    min: 1
    max: 1

Inline ignore¶

symbol-count is the only rule type that honors an inline ignore comment. A # psl: ignore marker in a real comment (not inside a string) suppresses rules for that file:

# psl: ignore[one-error-per-file]

The bracketed token matches the full rule name or the bare id prefix (the segment before the first -).

Summary¶

Rule fields¶

Rule types¶

Path pattern tokens¶