@sumrco/cli 0.2.1 → 0.3.1

package/ai/modules/kontract/resources/authoring/scope-and-splitting.rf.md

@@ -0,0 +1,244 @@
+---
+category: reference
+name: scope-and-splitting
+title: Scope, Size, and Splitting
+description: "How to keep Kontract specs and generator code small, product-aligned, and reviewable with explicit line-count budgets and split triggers."
+label: Scope and Splitting
+when: Reviewing large specs or code files, deciding whether to split a product capability/API surface spec, or optimizing oversized Kontract modules
+order: 18
+---
+
+# Scope, Size, and Splitting
+
+Kontract is the next iteration of the AutoSync/async schema idea: keep the
+documentation-first and DRY discipline, but make the boundaries more explicit.
+Large files are not automatically bad, but they hide duplicated concepts,
+mixed product areas, and unstable generated output. Treat size limits as review
+triggers first and hard caps second.
+
+## Source-of-truth rule
+
+Put durable guidance in Playbook resources and module docs; generated editor
+rules should point back to those resources. Do not copy long rules into Cursor,
+Claude, Codex, or generated contracts. The source contract spec and the source
+Playbook resource are the maintained truth.
+
+## Public example hygiene
+
+Files under `resources/` become public AI guidance. Never use internal SUMR,
+customer, product, infrastructure, event-subject, route, table, or data-model
+examples there. Public examples must be sanitized and generic.
+
+Use example areas such as:
+
+- kitchen recipes and ingredients;
+- bookstore inventory;
+- parcel shipping;
+- job hierarchies and departments;
+- todos or calendar events.
+
+Prefer `example.*`, `recipes`, `orders`, `ingredients`, `jobs`, or similarly
+generic names. Do not use real service names, internal nouns, customer nouns,
+NATS subject prefixes, API paths, or entity relationships as examples. Internal
+examples are acceptable in private `docs/` only when they are necessary to
+explain the module's current behavior.
+
+## File size budgets
+
+| File kind | Healthy target | Review trigger | Split/optimize trigger | Hard stop |
+|---|---:|---:|---:|---:|
+| Kontract TypeScript source | <= 200 lines | > 250 lines | > 400 lines | > 500 lines |
+| API/async service spec | 150-350 lines | > 400 lines | > 700 lines | > 1000 lines |
+| Shared component YAML | 100-300 lines | > 400 lines | > 600 lines | > 900 lines |
+| Generated TypeScript output | no manual target | review if surprising | fix generator/spec, never hand-split | no hand edits |
+
+Exceptions require a documented reason in the PR or handoff. Generated files,
+large fixtures, and intentionally dense compatibility snapshots are exempt from
+manual splitting, but they can still reveal generator or spec-design problems.
+
+## Split triggers
+
+Split or optimize before adding more content when a file shows any of these:
+
+- multiple product capabilities or API surfaces in one spec;
+- more than roughly 7-10 operations with different lifecycle owners;
+- request/response schemas for unrelated use cases in one component block;
+- repeated envelope, pagination, error, scalar, schedule, or config shapes;
+- repeated operation patterns that should become shared parameters/responses;
+- a TypeScript file with orchestration, parsing, emitting, IO, and formatting
+  responsibilities mixed together;
+- a generated diff where a small spec change creates many near-identical files.
+
+Do not split only by line count. First identify the product or technical
+boundary that gives the new file a stable name and owner.
+
+Visual section comments can help readers navigate a healthy file, but they are
+not a substitute for splitting an oversized or mixed-surface spec. If comments
+start acting like a table of contents, split by capability/surface instead.
+
+## Product capability and API surface spec structure
+
+Use directory nesting to communicate product ownership. The path should answer
+"who owns this contract?" and the filename should answer "which surface is this?"
+Read `kontract.guidance.profile.schemaLayoutStyle` before proposing a layout and
+use the canonical trees in the schema layout style reference. Do not describe
+resource-area fragments inside a product-capability folder as a repo-wide
+`by-resource-area` layout.
+
+For an API-only repo, keep the example API-only:
+
+```text
+schema/
+  recipes/
+    main.api.yml             # api: 3.0.3; grouped under recipes/http
+    catalog.api.yml
+    ingredients.api.yml
+    shared/                     # only promoted reusable recipe concepts
+      enums.yml
+      components.yml
+  kitchen/
+    stations.api.yml
+  shared/
+    pagination.yml              # only promoted cross-capability components
+    errors.yml
+```
+
+For an async-only repo, keep the example async-only:
+
+```text
+schema/
+  shared/
+    message-enums.yml
+  recipes/
+    recipes.async.yml
+    messages/
+      recipe-commands.yml
+      recipe-events.yml
+    models/
+      recipe.yml
+      enums.yml
+```
+
+When a folder already carries the product-capability name, prefer
+`*.api.yml` for focused surfaces that should generate as one package:
+
+```text
+schema/
+  recipes/
+    catalog.api.yml          # api: 3.0.3
+    ingredients.api.yml      # api: 3.0.3
+    shared/
+      enums.yml                 # promoted after both surfaces need it
+      components.yml
+```
+
+Kontract content-detects the protocol marker and groups those files under the
+first folder (`recipes` in this example). Use explicit `*.api.yml` or
+`*.async.yml` when each nested file should remain an independently generated
+service path.
+
+Add async schema examples only when messaging contracts exist:
+
+```text
+schema/
+  recipes/
+    catalog.api.yml          # api: 3.0.3
+    publishing.async.yml     # async: 3.0.0
+    inventory.async.yml      # async: 3.0.0
+```
+
+When API schema and async schema both exist, keep `paths/` and `messages/` separate.
+Share only schemas, especially enums, scalar value objects, IDs, and
+slugs, through `models/` or `schema/shared/`.
+
+If the selected schema layout style is `by-resource-area`, the resource
+areas should be top-level roots under the configured schema input, not nested
+under a product-capability folder. Moving from capability roots to resource-area
+roots changes generated output namespaces/import paths, so call it out as a
+schema and generated-output migration before recommending it.
+
+When one product capability should keep a single generated package but the
+contract is too large for one file, keep the explicit root files and split the
+internals into plain `.yml` fragments. This mirrors Redocly-style authoring:
+roots are the public entrypoints, fragments are implementation detail, and
+schemas can be shared by API schema and async schema only when the business shape is
+protocol-neutral.
+
+```text
+schema/
+  bookstore/
+    bookstore.api.yml       # API schema root entrypoint
+    paths/
+      books.yml                 # API schema Path Item fragment
+      authors.yml               # API schema Path Item fragment
+    models/
+      shared.yml
+      books.yml
+      authors.yml
+```
+
+Only add `bookstore.async.yml` and `messages/` fragments if the repo has
+async schema contracts or the user asks for messaging. Do not use split fragments as
+the default answer for a small API schema file.
+
+Guidelines:
+
+- Keep one entry-point spec per independently released API surface, not one
+  giant file per repo.
+- Split by product meaning: `recipes`, `ingredients`, `orders`, `jobs`, or
+  `inventory`, not by generic words like `common`, `misc`, or `helpers`.
+- Keep API schema route hierarchies aligned with the selected HTTP style. When a
+  child route depends on a parent for authorization, tenancy, lifecycle, or
+  meaning, nest it under that parent unless the selected style documents a
+  different public pattern.
+- Use short section markers only as editor landmarks inside a file that is still
+  small enough to review.
+- Use `schema/shared/` only for cross-capability concepts with stable semantics
+  and an obvious owner.
+- Prefer capability-local shared components when a concept is reused only inside
+  one product capability.
+- Keep one-off schemas inside the surface that owns them. Do not move every
+  component into `shared/` to anticipate future reuse.
+- Keep `info.title` deliberate because async schema NATS namespaces derive from it;
+  filenames and titles should not drift semantically.
+- Keep `$ref` paths repo-relative and validate after moving files.
+
+## Refactor order for oversized specs
+
+1. Keep one-off schemas local to the root or surface that owns them.
+2. Extract repeated capability-only shapes into a capability-local `shared/`
+   folder.
+3. Promote repeated cross-capability scalars, pagination, errors, envelopes,
+   schedules, and config objects into `schema/shared/` only when the same meaning
+   is reused across capabilities.
+4. Split operations by API surface when the file still mixes independently owned
+   workflows.
+5. Validate the moved refs with `sumr kontract validate`.
+6. Generate with the smallest useful scope and review both the spec diff and
+   generated output diff.
+
+## Refactor order for oversized code
+
+1. Name the current responsibilities in the file.
+2. Extract pure helpers first, then emitters/readers, then orchestration.
+3. Move interfaces and types into `src/types/` or `*.types.ts`; logic files
+   should import types instead of declaring them inline.
+4. Move reusable constants to `src/lib/constants.ts` or the existing constants
+   module.
+5. Add or adjust focused tests around the extracted seam before broad rewrites.
+
+Prefer small safe extractions over a big rewrite. The goal is a clearer module
+boundary, not a larger abstraction layer.
+
+## Review checklist
+
+Before accepting a large spec or source file:
+
+- [ ] The file is under the healthy target, or the reason for exceeding it is
+      documented.
+- [ ] The file has one clear product/technical owner.
+- [ ] Shared concepts are referenced with `$ref` rather than copied.
+- [ ] No generic bucket names (`common`, `misc`, `utils`) hide unrelated
+      responsibilities.
+- [ ] Generated output changes match the intended API surface only.
+- [ ] Any split keeps spec and regenerated output committed together.