docs(ztd-cli): redefine BFA boundary terminology#782
Open
Conversation
📝 WalkthroughWalkthroughThis PR updates documentation across ztd-cli and associated guides to redefine BFA from a Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
packages/ztd-cli/tests/furtherReading.docs.test.ts (1)
332-333: Harden negative guards across both READMEs for both legacy phrases.Lines 332-333 only check one legacy phrase per README. A regression could still slip in if the phrase appears in the other README.
🧪 Suggested assertion hardening
- expect(packageReadme).not.toContain('A folder is a boundary.'); - expect(scaffoldReadme).not.toContain('Every boundary folder exposes only `boundary.ts`'); + expect(packageReadme).not.toContain('A folder is a boundary.'); + expect(packageReadme).not.toContain('Every boundary folder exposes only `boundary.ts`'); + expect(scaffoldReadme).not.toContain('A folder is a boundary.'); + expect(scaffoldReadme).not.toContain('Every boundary folder exposes only `boundary.ts`');🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/ztd-cli/tests/furtherReading.docs.test.ts` around lines 332 - 333, The tests currently only assert each README omits a single legacy phrase; update the negative guards so both packageReadme and scaffoldReadme are asserted not to contain both legacy phrases ("A folder is a boundary." and "Every boundary folder exposes only `boundary.ts`") — locate the assertions using the variables packageReadme and scaffoldReadme in furtherReading.docs.test.ts and add the missing not.toContain checks for the other phrase on each README variable.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/ztd-cli/README.md`:
- Line 87: The sentence uses the awkward phrase "Features-external code"; update
the wording to something clearer — e.g., replace "Features-external code may
still use `boundary.ts` when it helps locally, but it is not a required filename
outside feature-boundaries and sub-boundaries." with "Code external to a feature
may still use `boundary.ts` when it helps locally, but it is not a required
filename outside feature-boundaries and sub-boundaries." — locate the sentence
referencing `boundary.ts`, `feature-boundaries`, and `sub-boundaries` and apply
this wording change.
---
Nitpick comments:
In `@packages/ztd-cli/tests/furtherReading.docs.test.ts`:
- Around line 332-333: The tests currently only assert each README omits a
single legacy phrase; update the negative guards so both packageReadme and
scaffoldReadme are asserted not to contain both legacy phrases ("A folder is a
boundary." and "Every boundary folder exposes only `boundary.ts`") — locate the
assertions using the variables packageReadme and scaffoldReadme in
furtherReading.docs.test.ts and add the missing not.toContain checks for the
other phrase on each README variable.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 1a007042-fac9-4ebe-981e-2405bfac47ac
📒 Files selected for processing (11)
.changeset/tall-kings-dance.mddocs/guide/sql-first-end-to-end-tutorial.mdpackages/ztd-cli/README.mdpackages/ztd-cli/templates/PROMPT_DOGFOOD.mdpackages/ztd-cli/templates/README.mdpackages/ztd-cli/templates/src/features/AGENTS.mdpackages/ztd-cli/templates/src/features/README.mdpackages/ztd-cli/tests/directoryFinding.docs.test.tspackages/ztd-cli/tests/furtherReading.docs.test.tspackages/ztd-cli/tests/init.command.test.tspackages/ztd-cli/tests/sqlFirstTutorial.docs.test.ts
| - If `<tech>` is a family or plural container such as `aws` or `cloud`, treat `src/adapters/<tech>/` as a parent and create child boundaries such as `src/adapters/aws/s3/` and `src/adapters/aws/lambda/`. | ||
|
|
||
| Reserve `db/` for DDL, migration, and schema assets only; do not place runtime clients or adapters there. | ||
| Features-external code may still use `boundary.ts` when it helps locally, but it is not a required filename outside feature-boundaries and sub-boundaries. |
There was a problem hiding this comment.
Fix wording typo in boundary guidance sentence.
Line 87 reads as “Features-external code,” which is awkward in user-facing docs.
✏️ Suggested wording fix
-Features-external code may still use `boundary.ts` when it helps locally, but it is not a required filename outside feature-boundaries and sub-boundaries.
+Feature-external code may still use `boundary.ts` when it helps locally, but it is not a required filename outside feature-boundaries and sub-boundaries.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Features-external code may still use `boundary.ts` when it helps locally, but it is not a required filename outside feature-boundaries and sub-boundaries. | |
| Feature-external code may still use `boundary.ts` when it helps locally, but it is not a required filename outside feature-boundaries and sub-boundaries. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/ztd-cli/README.md` at line 87, The sentence uses the awkward phrase
"Features-external code"; update the wording to something clearer — e.g.,
replace "Features-external code may still use `boundary.ts` when it helps
locally, but it is not a required filename outside feature-boundaries and
sub-boundaries." with "Code external to a feature may still use `boundary.ts`
when it helps locally, but it is not a required filename outside
feature-boundaries and sub-boundaries." — locate the sentence referencing
`boundary.ts`, `feature-boundaries`, and `sub-boundaries` and apply this wording
change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Issue
Customer Value
ztd-clidocs and generated starter guidance can distinguish app-level roots from feature-owned boundaries and optional child boundaries.boundary.tsremains easy to discover where the scaffold uses it, without being mistaken for the definition of BFA itself.Outcome
root-boundary,feature-boundary, andsub-boundary.root-boundaryset tosrc/features,src/adapters, andsrc/libraries.queries/is a child-boundary container and thatboundary.tsis a feature-scoped default convention.Acceptance Criteria
packages/ztd-cli/README.mdexplains BFA withroot-boundary,feature-boundary, andsub-boundary.packages/ztd-cli/templates/src/features/README.mdexplains the same model and keepsboundary.tsfeature-scoped rather than universal.boundary.tswording.queries/is a container, not a public boundary.tests/support/*,src/features/_shared/*,.ztd/*, anddb/are important areas but not root-boundaries.Verification
pnpm --filter @rawsql-ts/ztd-cli test -- tests/sqlFirstTutorial.docs.test.ts tests/directoryFinding.docs.test.ts tests/furtherReading.docs.test.ts tests/init.command.test.tsRepository Evidence
packages/ztd-cli/README.mdandpackages/ztd-cli/templates/src/features/README.mdpackages/ztd-cli/templates/README.md,packages/ztd-cli/templates/PROMPT_DOGFOOD.md,packages/ztd-cli/templates/src/features/AGENTS.md, anddocs/guide/sql-first-end-to-end-tutorial.mdpackages/ztd-cli/tests/sqlFirstTutorial.docs.test.ts,packages/ztd-cli/tests/directoryFinding.docs.test.ts,packages/ztd-cli/tests/furtherReading.docs.test.ts, andpackages/ztd-cli/tests/init.command.test.ts.changeset/tall-kings-dance.mdSupplementary Evidence
Open Questions
Merge Blockers
Summary
ztd-cliBFA docs around root/feature/sub boundaries.boundary.tsas a feature-scoped scaffold convention instead of a universal rule.Verification
pnpm --filter @rawsql-ts/ztd-cli test -- tests/sqlFirstTutorial.docs.test.ts tests/directoryFinding.docs.test.ts tests/furtherReading.docs.test.ts tests/init.command.test.tsMerge Readiness
Tracking issue: #779
Scoped checks run:
pnpm --filter @rawsql-ts/ztd-cli test -- tests/sqlFirstTutorial.docs.test.ts tests/directoryFinding.docs.test.ts tests/furtherReading.docs.test.ts tests/init.command.test.tsWhy full baseline is not required: This PR only updates docs, generated guidance text, and the docs tests that lock those reader-facing contracts.
CLI Surface Migration
No-migration rationale: This PR changes documentation vocabulary and generated guidance text only; runtime CLI behavior and scaffold output shape stay the same.
Upgrade note: none
Deprecation/removal plan or issue: none
Docs/help/examples updated:
packages/ztd-cli/README.md,packages/ztd-cli/templates/src/features/README.md,packages/ztd-cli/templates/README.md,packages/ztd-cli/templates/PROMPT_DOGFOOD.md,packages/ztd-cli/templates/src/features/AGENTS.md,docs/guide/sql-first-end-to-end-tutorial.mdRelease/changeset wording: Added a patch changeset for
@rawsql-ts/ztd-clidescribing the BFA terminology clarification and the feature-scopedboundary.tsconvention.Scaffold Contract Proof
No-proof rationale: n/a
Non-edit assertion: This PR does not change runtime CLI commands, scaffolded file names, or scaffold output shape; it only redefines the reader-facing BFA vocabulary and generated guidance text.
Fail-fast input-contract proof: Updated docs tests now assert that
queries/is a child-boundary container, the concrete root-boundary set is limited tosrc/features,src/adapters, andsrc/libraries, and legacy universal wording is absent from the public docs and generated prompt text.Generated-output viability proof:
tests/init.command.test.tsregeneratesPROMPT_DOGFOOD.mdand passes with the new feature-scoped guidance, showing the generated starter guidance remains coherent after the terminology change.Summary by CodeRabbit
Documentation
Tests