@mmerterden/multi-agent-pipeline 14.2.2 → 15.1.0

package/pipeline/skills/shared/external/ios-module-structure/references/rules.yml

@@ -0,0 +1,559 @@
+version: 0.1.0
+updated: 2026-08-13
+owner: iOS platform
+description: >
+  The ios-module-structure rule registry. Where a declaration lives, what its file is called, and what
+  its folder must contain beside it. Sibling to the coding-standard registry, which governs file
+  CONTENT; this one governs the TREE. IDs are stable and never renumbered - a rule is retired by
+  status, not deletion.
+
+  MATURITY: 0.x. The rule set was generalised from one module's conventions and stress-tested
+  against one more; that second contact added two dialect slots. Expect a third module to add
+  more. Slots and carve-outs absorb that without breaking a binding, but do not treat this as a
+  frozen standard yet.
+
+  Every rule here is written over ROLES, never over literal paths or type names. A role is bound by
+  the module's own overlay. That is what lets one registry serve a module that spells its subview
+  folder one way and a module that spells it another, without either becoming a hundred findings.
+
+# What these rules may be applied to. A consumer resolves this BEFORE selecting rules and records
+# what it dropped. Per-rule `scope:` narrows this and never widens it.
+scope:
+  languages: [swift]
+  # The engine reads this: it holds no language of its own.
+  sourceExtension: .swift
+  paths:
+    - "**/*.swift"
+  excludePaths:
+    - "**/*.generated.swift"
+    - "**/Generated/**"
+    - "**/*.pb.swift"
+    - "**/.build/**"
+    - "**/DerivedData/**"
+  notCovered:
+    objective-c: "*.m / *.mm / *.h - no rules here speak for them; report as a coverage gap"
+    resources: "asset catalogs, plists, storyboards - the tree rules do not describe them"
+
+severity_levels: [blocking, important, suggestion]
+enforcement_kinds:
+  lint: a tool decides it mechanically from the tree and file text
+  scan: a tool measures it across the module (counts, ratios, mirrors)
+  judgement: requires a human; the tool can only surface the candidate
+exception_marker: "// standard:exception(<RULE-ID>) <reason> <expiry:YYYY-MM-DD>"
+
+# ---------------------------------------------------------------------------
+# Roles
+# ---------------------------------------------------------------------------
+# A rule names a role; the overlay binds the role to this module's reality. An UNBOUND role
+# disables every rule that reads it, and the audit reports that rather than guessing a shape.
+#
+# Binding forms:
+#   glob     - a path pattern relative to the module root, e.g. "Sources/*/Screens/*/Presentation/*Scene.swift"
+#   derived  - a pattern computed from another role's match, e.g. "{dir}/{stem}Configuration.swift"
+# `{dir}`, `{stem}`, `{screen}` and `{target}` are the only substitutions.
+roles:
+  screen.root:
+    description: the directory that is one screen. Everything else is resolved relative to it.
+    required: true
+  screen.entry:
+    description: the file a coordinator or factory constructs to show the screen.
+  screen.viewmodel:
+    description: the type holding the screen's behaviour and service calls.
+  screen.state:
+    description: the type holding the screen's UI state, when the module separates it from the view model.
+  screen.analytics:
+    description: the screen's analytics surface.
+  screen.factory:
+    description: the seam another module calls to build the screen.
+  screen.mapper:
+    description: the wire-to-domain translation for the screen.
+  service.dir:
+    description: one directory per service operation, holding that operation's models.
+  service.request:
+    description: the request half of a service operation.
+  service.response:
+    description: the response half of a service operation.
+  subview.dir:
+    description: where a screen's extracted views live, when the module extracts them into folders.
+  subview.view:
+    description: an extracted view belonging to one screen.
+  subview.configuration:
+    description: the value type an extracted view renders.
+  repository.live:
+    description: the production implementation of a screen's data access.
+  repository.mock:
+    description: the offline/scripted implementation used by previews and the debug menu.
+  shared.root:
+    description: the module's cross-screen folder.
+  source.root:
+    description: the module's source tree, as the mirror rule's counterpart to the test tree.
+  test.root:
+    description: the module's test tree.
+
+# ---------------------------------------------------------------------------
+# Dialect slots
+# ---------------------------------------------------------------------------
+module_overlay_slots:
+  description: >
+    Some rules govern a CHOICE rather than a defect: two shapes are each internally coherent, the
+    cost is only in mixing them, and picking one is the module's call. Writing one of them into the
+    shared registry turns every module that chose the other into a hundred findings - which is a
+    migration proposal wearing a structure pass. Those rules bind to a slot here instead. An
+    UNBOUND slot disables its rules and the audit says so, rather than defaulting to one dialect
+    silently.
+
+    A slot is only legitimate when both values are genuinely defensible. A module with no analytics
+    surface has not chosen a different dialect, it is missing the surface - so STRUCT-04 is a rule,
+    not a slot.
+  slots:
+    - id: ScreenLayerShape
+      governs: [STRUCT-01, STRUCT-02]
+      values:
+        layered: >
+          every screen carries the same fixed set of layer folders, including the ones that are
+          empty for that screen. The tree teaches the architecture; a missing folder is a finding.
+        organic: >
+          a screen carries only the layers it actually has. Nothing is created to satisfy a shape,
+          and a missing layer means the screen genuinely has no work at that level.
+      note: >
+        Module-wide. The audit reads it to decide whether "screen has no data layer" is a finding
+        or a fact.
+    - id: ServiceModelDir
+      governs: [STRUCT-03]
+      values:
+        under-data: the request/response pair sits in the data layer, beside the code that calls the service.
+        under-mapper: the pair sits beside the mapper that translates it.
+      note: The pairing rule is the same either way; only the parent differs.
+    - id: ScreenAssemblyShape
+      governs: [STRUCT-05]
+      values:
+        per-screen-factory: each screen ships its own construction seam.
+        shared-factory: one factory per module builds every screen.
+      note: >
+        Both put construction behind a seam, which is the property STRUCT-05 protects. Counting
+        factories against screens tells you which one the module chose.
+    - id: UIStateHolder
+      governs: [STRUCT-06]
+      values:
+        separate-state-type: UI state lives in its own type beside the view model.
+        view-model-owned: the view model holds UI state directly.
+      note: >
+        Unbound, STRUCT-06 is disabled - "the view model holds a form field" is only a finding in a
+        module that decided it should not.
+    - id: SubviewShape
+      governs: [STRUCT-07, STRUCT-08, STRUCT-09]
+      values:
+        folder-per-subview: each extracted view gets a folder holding it and its value type.
+        flat: extracted views sit loose in one folder, with no required companion.
+      note: >
+        The sibling rules only make sense under folder-per-subview. Under flat they are disabled,
+        not violated.
+    - id: ScreenCompositionShape
+      governs: [STRUCT-10]
+      values:
+        extracted: >
+          a fragment of the screen becomes a named view beside it. The entry file is a table of
+          contents; each piece can be previewed and snapshotted alone.
+        in-file: >
+          the entry file composes its own fragments. One file tells the whole screen's story and a
+          reader never chases a name across the folder.
+      note: >
+        Both keep the body readable, which is what STRUCT-10 protects. Counting view members on
+        entry files against extracted view files tells you which one the module chose.
+    - id: ServiceModelPairing
+      governs: [STRUCT-03]
+      values:
+        both: every operation models a request and a response, even when the request is empty.
+        response-only: >
+          a request is modelled only when the call carries a body; a bodyless GET has a response
+          and nothing else.
+      note: >
+        Under response-only a lone response is normal and only a lone REQUEST is the finding.
+
+    - id: CopyResolution
+      governs: [VOCAB-06]
+      values:
+        render-site: copy keys are resolved where the text is rendered.
+        copy-layer: a per-screen type owns every string the screen shows.
+      note: Both keep copy findable; mixing them is what costs.
+
+# ---------------------------------------------------------------------------
+# Rules
+# ---------------------------------------------------------------------------
+rules:
+  # --- Tree ---------------------------------------------------------------
+  - id: STRUCT-01
+    title: A screen carries the layer folders its module's shape declares
+    severity: important
+    enforcement: lint
+    predicate: dir_required_in_dir
+    params:
+      slot: ScreenLayerShape
+      slot_value: layered
+      vocabulary_key: LayerDirs
+    applies_when: the module binds ScreenLayerShape. Unbound, this rule is DISABLED.
+    applies_to_value: layered
+    rationale: navigability
+    check: >
+      Under `layered`, a screen missing one of the declared layer folders is a finding: the tree is
+      the architecture diagram and a hole in it makes the reader guess. Under `organic` this rule
+      does not run at all.
+
+  - id: STRUCT-02
+    title: A screen's presentation layer is never absent
+    severity: blocking
+    enforcement: lint
+    predicate: dir_required_in_dir
+    params:
+      vocabulary_key: PresentationDir
+    rationale: navigability
+    check: >
+      Whatever else a screen does or does not carry, it renders something. A screen directory with
+      no presentation layer is either dead or misfiled; both are findings.
+
+  - id: STRUCT-03
+    title: A service operation's request and response live together, and neither travels alone
+    severity: important
+    enforcement: lint
+    predicate: pair_required_in_dir
+    params:
+      slot: ServiceModelDir
+      container_role: service.dir
+      left_role: service.request
+      right_role: service.response
+      pairing_slot: ServiceModelPairing
+      right_only_value: response-only
+    applies_when: the module binds ServiceModelDir. Unbound, this rule is DISABLED.
+    rationale: navigability
+    check: >
+      A directory that holds one half of a service operation must hold the other. A lone response
+      means the request is inlined somewhere a reader will not find it, and a lone request means
+      the response is being decoded into a type that does not say which call produced it.
+    exempt: [operations whose request carries no fields and is not modelled at all]
+
+  - id: STRUCT-04
+    title: A screen owns an analytics surface
+    severity: important
+    enforcement: lint
+    predicate: file_required_in_dir
+    params:
+      role: screen.analytics
+      screen_exemptable: true
+    rationale: observability
+    check: >
+      A screen a user can reach reports that they reached it. The surface is one type per screen so
+      that its events can be spied in a test without touching the tracker.
+    exempt: >
+      Screens with no product identity of their own - a picker sheet, a system-wrapper cover, a web
+      host - presented inside another screen's flow. The presenting screen tracks the interaction
+      that opened them. Inventing screen-view events for them puts names in the analytics schema
+      nobody asked for. List them in the overlay's `exempt_screens`.
+
+  - id: STRUCT-05
+    title: A screen ships the construction seam its module's assembly shape declares
+    severity: important
+    enforcement: scan
+    predicate: file_required_in_dir
+    params:
+      slot: ScreenAssemblyShape
+      slot_value: per-screen-factory
+      role: screen.factory
+    applies_when: the module binds ScreenAssemblyShape to per-screen-factory. Otherwise DISABLED.
+    rationale: module boundaries
+    check: >
+      Under per-screen-factory, each screen ships its own construction seam. Under shared-factory
+      the seam is one per module and this rule does not run per screen.
+
+  - id: STRUCT-06
+    title: UI state lives where the module decided it lives
+    severity: important
+    enforcement: lint
+    predicate: file_required_in_dir
+    params:
+      slot: UIStateHolder
+      slot_value: separate-state-type
+      role: screen.state
+      trigger_role: screen.viewmodel
+      trigger_pattern: '(FormField|\.Section\b|var\s+(is|selected|shows|expanded)\w*(Presented|Expanded|Sheet|Index|Visible|Selected|Shown)\b)'
+    applies_when: >
+      the module binds UIStateHolder to separate-state-type AND the screen actually has UI state
+      (a bound form field, a selected index, a presented sheet). Otherwise DISABLED.
+    rationale: testability
+    check: >
+      A screen with bound form objects or visual state, in a module that separated that state out,
+      must carry the state type. A screen with neither is not missing anything.
+
+  - id: STRUCT-07
+    title: An extracted view carries the value type it renders
+    severity: important
+    enforcement: lint
+    predicate: sibling_required
+    params:
+      slot: SubviewShape
+      slot_value: folder-per-subview
+      subject_role: subview.view
+      strip_suffix_from_vocabulary: SubviewViewSuffix
+      append_suffix_from_vocabulary: SubviewConfigurationSuffix
+    applies_when: the module binds SubviewShape to folder-per-subview. Otherwise DISABLED.
+    rationale: testability
+    check: >
+      Every extracted view has a value type beside it holding what it renders. A view that reads
+      its data from anywhere else cannot be rendered in isolation, which means it cannot be
+      previewed or snapshotted.
+
+  - id: STRUCT-08
+    title: The value type an extracted view renders holds values, not behaviour
+    severity: blocking
+    enforcement: lint
+    predicate: forbidden_pattern
+    params:
+      slot: SubviewShape
+      slot_value: folder-per-subview
+      subject_role: subview.configuration
+      pattern: '^\s+(let|var)\s+\w+\s*:\s*(@escaping\s+)?\('
+    applies_when: the module binds SubviewShape to folder-per-subview. Otherwise DISABLED.
+    rationale: testability
+    check: >
+      A closure stored in the value type makes it non-comparable and drags the caller's lifetime
+      into it. Actions reach the view as its own parameters; the value type carries only what is
+      drawn.
+
+  - id: STRUCT-09
+    title: An extracted view takes values, never the screen's view model
+    severity: blocking
+    enforcement: lint
+    predicate: forbidden_pattern
+    params:
+      slot: SubviewShape
+      subject_role: subview.view
+      pattern: '^\s+(let|var)\s+\w+\s*:\s*(any\s+)?\w*ViewModel\b'
+    applies_when: the module binds SubviewShape. Otherwise DISABLED.
+    rationale: testability
+    check: >
+      A view holding the view model can reach anything, so nothing about it can be asserted from
+      its inputs. It also cannot be previewed without constructing the whole screen.
+
+  - id: STRUCT-10
+    title: The screen's entry file composes; it does not also carry the pieces
+    severity: important
+    applies_when: the module binds ScreenCompositionShape to extracted. Otherwise DISABLED.
+    enforcement: lint
+    predicate: forbidden_member
+    params:
+      slot: ScreenCompositionShape
+      slot_value: extracted
+      subject_role: screen.entry
+      pattern: '^\s+(?:@ViewBuilder\s+)?(?:private\s+)?(?:var|func)\s+(\w+)[^\n]*?some View'
+      allow: [body]
+    rationale: readability
+    check: >
+      The entry file holds its properties, its init, one body and its previews. A second view
+      member on it is a fragment that either belongs in the body's composition or belongs beside
+      the screen as an extracted view. The exception is a fragment the type system pins to the call
+      site - an alert's content, a modifier-constrained builder - which cannot be moved.
+
+  - id: STRUCT-11
+    title: A cross-screen folder holds no type named after one screen
+    severity: important
+    enforcement: lint
+    predicate: prefix_collision
+    params:
+      subject_role: shared.root
+    rationale: module boundaries
+    check: >
+      A type in the shared folder carrying a screen's prefix is shared by accident. Either it is
+      genuinely common, and the prefix is wrong, or it belongs to that screen and the folder is
+      wrong.
+
+  - id: STRUCT-12
+    title: The test tree mirrors the source tree
+    severity: suggestion
+    enforcement: scan
+    predicate: mirror_required
+    params:
+      test_role: test.root
+      source_role: source.root
+    rationale: navigability
+    check: >
+      A reader looking for a type's tests should find them at the same path under the test root. A
+      test folder with no source counterpart is either testing something that moved or grouping by
+      a concept the source does not have.
+
+  # --- Size and shape ------------------------------------------------------
+  - id: STRUCT-13
+    title: File size has a target and a ceiling, and tests get a wider one
+    severity: important
+    enforcement: lint
+    predicate: file_size
+    params:
+      test_marker: /Tests/
+    rationale: readability
+    metric: lines per file
+    check: >
+      Past the target a file is a candidate for splitting; past the ceiling it is a finding. Tests
+      get a wider band because a suite legitimately repeats its arrange step. The numbers live in
+      the overlay - a module that has not chosen them gets the registry defaults.
+    exempt: [generated sources, fixture and mock data files]
+
+  - id: STRUCT-14
+    title: Layout numbers are not a type
+    severity: suggestion
+    enforcement: lint
+    predicate: forbidden_pattern
+    params:
+      glob_from_vocabulary: PresentationDir
+      pattern: '^\s*(?:private\s+)?(?:struct|enum)\s+\w+(Constants|Layout|Metrics|Dimensions)\b'
+    rationale: readability
+    check: >
+      A per-screen constants, layout or metrics type collects numbers that belong either to a
+      design-token namespace or to the one view that uses them. It becomes a dumping ground whose
+      entries no one dares delete.
+
+  - id: STRUCT-15
+    title: A view type is previewable, and previews it
+    severity: suggestion
+    enforcement: lint
+    predicate: required_pattern
+    params:
+      glob: '**/*.swift'
+      when_pattern: '^\s*(?:public\s+)?struct\s+\w+(View|Scene)\s*:'
+      pattern: '#Preview'
+      label: no preview
+    rationale: testability
+    check: >
+      A view with no preview is a view nobody looked at in isolation. The preview is also the
+      cheapest proof that the type can be constructed from values alone.
+
+  # --- Vocabulary ----------------------------------------------------------
+  - id: VOCAB-01
+    title: A boolean reads as a claim about the subject
+    severity: important
+    enforcement: lint
+    predicate: naming_pattern
+    params:
+      glob: '**/*.swift'
+      declaration: '^\s+(?:@\w+\s+)?(?:private\(set\)\s+)?(?:public\s+)?var\s+([a-z]\w*)\s*:\s*Bool\b'
+      accept_from_vocabulary: BooleanPrefixes
+    rationale: readability
+    check: >
+      A boolean is prefixed so the reader knows it is one and knows which way it points. Plural
+      subjects agree with the plural rather than taking a singular prefix. A bare adjective or noun
+      forces the reader to open the declaration.
+
+  - id: VOCAB-02
+    title: A positional index carries the same label everywhere
+    severity: suggestion
+    enforcement: lint
+    predicate: naming_pattern
+    params:
+      glob: '**/*.swift'
+      declaration: '\((for|_)\s+(?:index|\w+Index)\s*:\s*Int'
+      accept_from_vocabulary: IndexLabel
+    rationale: readability
+    check: >
+      One spelling for "at this position" across the module. Two spellings make the call sites read
+      as two different concepts.
+
+  - id: VOCAB-03
+    title: Section headings come from a closed vocabulary
+    severity: suggestion
+    enforcement: lint
+    predicate: vocabulary
+    params:
+      vocabulary_key: SectionHeadings
+      declaration: '^\s*//\s*MARK:\s*-\s*(.+)$'
+      exempt_patterns: ['^[a-z][a-zA-Z0-9/{}.\- ]*$', '→', '↔']
+    rationale: navigability
+    check: >
+      Headings are a map, and a map with a hundred distinct labels is not one. The vocabulary lives
+      in the overlay. Headings naming an external contract - an endpoint, a protocol being
+      conformed to, a wire direction - are outside the vocabulary by construction and are exempt.
+
+  - id: VOCAB-04
+    title: A method name says which layer speaks
+    severity: important
+    enforcement: lint
+    predicate: naming_pattern
+    params:
+      subject_role: screen.viewmodel
+      declaration: '^\s+(?:private\s+)?func\s+([a-z]\w*)\s*\('
+      reject_from_vocabulary: BareVerbs
+    rationale: readability
+    check: >
+      A user event, a service call and a derived value are three different things and their names
+      say which. A bare verb on a presentation type does not say whether it asks the network, mutates
+      state, or both.
+
+  - id: VOCAB-05
+    title: A type's last word says what it does, and some last words say nothing
+    severity: important
+    enforcement: lint
+    predicate: naming_pattern
+    params:
+      glob: '**/*.swift'
+      declaration: '^(?:public\s+)?(?:final\s+)?(?:struct|class|enum|actor|protocol)\s+(\w+)'
+      reject_from_vocabulary: ForbiddenTypeSuffixes
+    rationale: readability
+    check: >
+      The role suffix set lives in the overlay. Suffixes that describe no role - the ones that mean
+      "code that does things" - are listed there as forbidden, and a type carrying one has not been
+      named yet.
+
+  - id: VOCAB-06
+    title: Copy is resolved in one place per module
+    severity: suggestion
+    enforcement: lint
+    predicate: forbidden_pattern
+    params:
+      slot: CopyResolution
+      glob: '**/*.swift'
+      pattern_from_vocabulary_by_slot:
+        render-site: CopyLayerTypePattern
+        copy-layer: RawCopyKeyAtRenderSitePattern
+    applies_when: the module binds CopyResolution. Unbound, this rule is DISABLED.
+    rationale: navigability
+    check: >
+      Under `render-site` a per-screen copy layer is the finding; under `copy-layer` a raw key at a
+      render site is. Either is fine; both at once means a reader has to check two places.
+
+  - id: VOCAB-07
+    title: One declaration per file, and the file is named after it
+    severity: important
+    enforcement: lint
+    predicate: naming_pattern
+    params:
+      glob: '**/*.swift'
+      declaration: '^(?:public\s+)?(?:final\s+)?(?:struct|class|enum|actor|protocol)\s+(\w+)'
+      match_file_stem: true
+    rationale: navigability
+    check: >
+      A reader who knows a type's name knows its file. A second top-level declaration in a file is
+      findable only by grep - and gets deleted by accident when the first one moves.
+    exempt: >
+      A private helper that exists only for the file's own declaration, and an extension of the
+      file's own type.
+
+  # --- Judgement (surfaced, never auto-failed) -----------------------------
+  - id: STRUCT-16
+    title: A subfolder is earned by its contents
+    severity: suggestion
+    enforcement: judgement
+    predicate: none
+    params: {}
+    rationale: navigability
+    check: >
+      A folder holding one or two files usually names a concept the module does not actually have.
+      The tool can list the candidates; whether a given one is a seam worth keeping is a reading,
+      not a count. Service operation folders are exempt by construction - the pair is the point.
+
+  - id: STRUCT-17
+    title: Fixture data lives with the fixtures, not inside the thing that serves it
+    severity: suggestion
+    enforcement: judgement
+    predicate: none
+    params: {}
+    rationale: readability
+    check: >
+      A scripted implementation that also carries its own payload literals mixes the decision of
+      which scenario to answer with the content of the answer. The tool can surface the size ratio;
+      the split itself is a judgement.