scaffold-ca-python 0.3.0__tar.gz → 0.5.0__tar.gz

scaffold_ca_python-0.5.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.5.0"
+}

{scaffold_ca_python-0.3.0 → scaffold_ca_python-0.5.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.5.0](https://github.com/bancolombia/scaffold-clean-architecture-py/compare/v0.4.0...v0.5.0) (2026-10-27)
+
+
+### Features
+
+* **mcp:** generate health check route for MCP entry points ([70a2645](https://github.com/bancolombia/scaffold-clean-architecture-py/commit/70a2645e63957d211761e7535edc675685031d57))
+
+## [0.4.0](https://github.com/bancolombia/scaffold-clean-architecture-py/compare/v0.3.0...v0.4.0) (2026-10-26)
+
+
+### Features
+
+* **usecase:** standardize generated use-case module names ([74a19b2](https://github.com/bancolombia/scaffold-clean-architecture-py/commit/74a19b20a448aff780e6439b2814541480ba1111))
+
 ## [0.3.0](https://github.com/bancolombia/scaffold-clean-architecture-py/compare/v0.2.1...v0.3.0) (2026-10-26)
 
 

{scaffold_ca_python-0.3.0 → scaffold_ca_python-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scaffold-ca-python
-Version: 0.3.0
+Version: 0.5.0
 Summary: Scaffolder to generate Clean Architecture apps
 Project-URL: Homepage, https://github.com/bancolombia/scaffold-clean-architecture-py
 Project-URL: Repository, https://github.com/bancolombia/scaffold-clean-architecture-py
@@ -128,7 +128,7 @@ scaffold gm --name order --dry-run
 
 ### scaffold guc
 
-Scaffold a use case in `domain/usecase/`.
+Scaffold a use case in `domain/usecase/`. The module is always named `<name>_usecase.py` and the class `<Name>UseCase`. Writing `_usecase` in `--name` is optional and the suffix is never duplicated: `create_order`, `create_order_usecase` and `create_order_use_case` all create `create_order_usecase.py` with `CreateOrderUseCase`.
 
 ```bash
 scaffold guc --name create_order

{scaffold_ca_python-0.3.0 → scaffold_ca_python-0.5.0}/README.md

@@ -97,7 +97,7 @@ scaffold gm --name order --dry-run
 
 ### scaffold guc
 
-Scaffold a use case in `domain/usecase/`.
+Scaffold a use case in `domain/usecase/`. The module is always named `<name>_usecase.py` and the class `<Name>UseCase`. Writing `_usecase` in `--name` is optional and the suffix is never duplicated: `create_order`, `create_order_usecase` and `create_order_use_case` all create `create_order_usecase.py` with `CreateOrderUseCase`.
 
 ```bash
 scaffold guc --name create_order

scaffold_ca_python-0.5.0/specs/026-usecase-naming-standardization/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: Use Case Naming Standardization
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-10-26
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- The spec references CLI command names, file paths, and class names. For a code generator these are the user-facing output, not implementation details, so they are kept (same approach as `specs/025-model-gateway-generation/spec.md`).
+- Scope decisions agreed with the user before writing: both `_usecase` and `_use_case` suffixes are recognized, the delete-module command is in scope, and the branch is created from `main`.
+- Validation passed on the first iteration after aligning SC-003 with the repeated-suffix edge case.

scaffold_ca_python-0.5.0/specs/026-usecase-naming-standardization/contracts/dm.md

@@ -0,0 +1,22 @@
+# CLI Contract changes: `scaffold dm` / `scaffold delete-module`
+
+Only the use case lookup changes. Flags, messages, and exit codes stay the same.
+
+## Use case candidates (in order)
+
+| Layout | Source target | Test target |
+|---|---|---|
+| New | `src/<pkg>/domain/usecase/<base>_usecase.py` | `src/tests/domain/usecase/test_<base>_usecase.py` (if present) |
+| Legacy | `src/<pkg>/domain/usecase/<name>.py` | `src/tests/domain/usecase/test_<name>.py` (if present) |
+
+`<base>` is `--name` with trailing `_usecase` / `_use_case` suffixes removed. A candidate is listed once even if both rows resolve to the same file. The new row is skipped when `<base>` is empty.
+
+## Outcomes for use cases
+
+| Situation | Exit | Effect |
+|---|---|---|
+| `dm --name book` or `dm --name book_usecase`, new file exists | 0 | preview lists `book_usecase.py` and its test; `--confirm` removes both |
+| `dm --name book`, only legacy `book.py` exists | 0 | preview lists `book.py` and its test; `--confirm` removes both, as today |
+| `dm --name book`, model package `domain/model/book/` and `book_usecase.py` both exist | 0 | preview lists the model package, its tests folder, `book_usecase.py`, and its test; `--confirm` removes all of them (existing cross-layer behavior) |
+| `dm --name book`, both layouts exist | 0 | preview lists all 4 files; `--confirm` removes all 4 |
+| no match | 1 | existing "No module named ..." error |

scaffold_ca_python-0.5.0/specs/026-usecase-naming-standardization/contracts/guc.md

@@ -0,0 +1,38 @@
+# CLI Contract changes: `scaffold guc` / `scaffold generate-use-case`
+
+Flags, aliases, the no-argument help, name validation, and project-root errors stay the same. Only the generated names and two error cases change.
+
+## Outputs
+
+| `--name` | Created files | Class |
+|---|---|---|
+| `create_order` | `src/<pkg>/domain/usecase/create_order_usecase.py`, `src/tests/domain/usecase/test_create_order_usecase.py` | `CreateOrderUseCase` |
+| `create_order_usecase` | same as above | `CreateOrderUseCase` |
+| `create_order_use_case` | same as above | `CreateOrderUseCase` |
+| `create_order_usecase_usecase` | same as above | `CreateOrderUseCase` |
+| `usecase_registry` | `usecase_registry_usecase.py`, `test_usecase_registry_usecase.py` | `UsecaseRegistryUseCase` |
+
+The generated test imports `from <pkg>.domain.usecase.<base>_usecase import <Base>UseCase`.
+
+## Outcomes
+
+| Situation | Exit | Output | Effect |
+|---|---|---|---|
+| Success | 0 | `✓ Use case <Base>UseCase created. Created 2 file(s).` | 2 files written |
+| `--dry-run` | 0 | Tree titled `<base>_usecase (dry run)` listing the 2 paths | nothing written |
+| `<base>_usecase.py` already exists (any spelling) | 1 | `Error: File 'src/<pkg>/domain/usecase/<base>_usecase.py' already exists.` plus the existing hint | nothing written |
+| `src/tests/domain/usecase/test_<base>_usecase.py` already exists | 1 | `Error: File 'src/tests/domain/usecase/test_<base>_usecase.py' already exists.` plus the same hint | nothing written |
+| Legacy `<base>.py` exists | 0 | normal success | `<base>_usecase.py` created, legacy file untouched, no warning |
+| Name is only the suffix (`usecase`, `use_case`, `usecase_usecase`) | 1 | `Error: Use case name '<name>' is only the 'usecase' suffix.` / `Hint: Use a descriptive name such as 'create_order'.` | nothing written |
+
+## Help text
+
+Epilog example becomes:
+
+```text
+Example:
+
+  * scaffold guc --name create_order   (creates domain/usecase/create_order_usecase.py)
+
+  * scaffold generate-use-case --name create_order
+```

scaffold_ca_python-0.5.0/specs/026-usecase-naming-standardization/data-model.md

@@ -0,0 +1,36 @@
+# Data Model: Use Case Naming Standardization
+
+No new runtime models. The feature derives three names from the user's `--name` value and reuses the existing `ModuleContext`.
+
+## Derived names
+
+| Name | Rule | Example (`--name create_order_usecase`) |
+|---|---|---|
+| Raw name | `--name` as typed. Validated by `validate_module_name` (snake_case only). | `create_order_usecase` |
+| Base name | `strip_usecase_suffix(raw)` (research R2). Must be non-empty. | `create_order` |
+| Module name | `<base>_usecase` | `create_order_usecase` |
+| Class name | `to_pascal_case(base) + "UseCase"` | `CreateOrderUseCase` |
+
+## ModuleContext usage
+
+`ModuleContext(name=<base>, layer=Layer.DOMAIN_USECASE, project=...)`. It is unchanged, only the value passed as `name` differs.
+
+| Field | Value | Used by |
+|---|---|---|
+| `name` | base name | factory path |
+| `class_name` | `<Base>` | both templates (`{{ class_name }}UseCase`), success message |
+| `module_name` | `<base>` | factory path (`<base>_usecase.py`), test import (`{{ module_name }}_usecase`), test function name |
+
+## Generated files
+
+| File | Path |
+|---|---|
+| Use case module | `src/<pkg>/domain/usecase/<base>_usecase.py` |
+| Test stub | `src/tests/domain/usecase/test_<base>_usecase.py` |
+
+## Validation rules
+
+1. The raw name must match snake_case (existing rule, existing message).
+2. The base name must be non-empty. Otherwise exit 1 with a hint (FR-008).
+3. `src/<pkg>/domain/usecase/<base>_usecase.py` must not exist. Otherwise exit 1 with a hint (FR-009). Legacy `<base>.py` is ignored (FR-009a).
+4. `src/tests/domain/usecase/test_<base>_usecase.py` must not exist. Otherwise exit 1 with a hint (FR-009b).

scaffold_ca_python-0.5.0/specs/026-usecase-naming-standardization/plan.md

@@ -0,0 +1,109 @@
+# Implementation Plan: Use Case Naming Standardization
+
+**Branch**: `feature/usecase-naming-standardization` | **Date**: 2026-10-26 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `/specs/026-usecase-naming-standardization/spec.md`
+
+## Summary
+
+`scaffold guc --name <name>` always writes `domain/usecase/<base>_usecase.py` with `class <Base>UseCase`. `<base>` is `--name` with any trailing `_usecase` / `_use_case` suffixes removed, so the suffix never appears twice. A single helper, `strip_usecase_suffix`, in `name_utils` does the normalization. The command passes the base name into the existing `ModuleContext`. The factory and the test template append `_usecase`. Module lookup gains one candidate (`<base>_usecase.py`) ahead of the legacy `<name>.py`, so delete-module finds use cases by base name, by suffixed name, and in both layouts, with no change to the delete factory.
+
+## Technical Context
+
+**Language/Version**: Python 3.13+
+
+**Primary Dependencies**: Typer, Rich, Jinja2, Pydantic v2 (no new dependencies)
+
+**Storage**: Files on disk via the existing `FileWriter`
+
+**Testing**: pytest + pytest-cov (80% gate)
+
+**Target Platform**: macOS / Linux developer machines (CLI)
+
+**Project Type**: CLI code generator
+
+**Performance Goals**: `guc` stays under the existing 3 s benchmark (`tests/commands/test_performance.py`)
+
+**Constraints**: Generated code must pass the generated project's ruff, mypy strict, and pytest without edits. `ModuleContext` is shared by all generators and must not change behavior.
+
+**Scale/Scope**: 1 changed template, 4 changed source modules, about 7 test files updated or extended, and a README section
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status | Notes |
+|---|---|---|
+| I. Clean Architecture in generated projects | PASS | Files still land in `domain/usecase/`. `vs` classifies by the `("domain", "usecase")` prefix, so file names do not matter. |
+| II. Template-driven generation | PASS | Both files still come from `templates/use_case/*.jinja2`. The changed test template gets a rendering test for the new import. Context is the existing Pydantic `ModuleContext`. |
+| III. Command parity | PASS | `guc` / `generate-use-case` and `dm` / `delete-module` keep names, aliases, and `--dry-run`. |
+| IV. Python-first idioms | PASS | `strip_usecase_suffix` is fully typed; ruff and mypy strict apply. |
+| V. Test-first | PASS | Every step below starts with a failing test. The generated project still gets its test stub. |
+| VI. Developer experience | PASS | The new suffix-only error uses `fail()` with a hint. The help epilog shows the generated file name. |
+| VII. Branch naming | PASS | Work happens on `feature/usecase-naming-standardization`, already created from `main`. |
+
+No violations, so Complexity Tracking is empty.
+
+**Post-design re-check (after Phase 1)**: All gates still PASS. The design adds one pure function and one lookup candidate, with no new abstractions.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/026-usecase-naming-standardization/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+│   ├── guc.md
+│   └── dm.md
+├── checklists/requirements.md
+└── tasks.md             # created by /speckit-tasks
+```
+
+### Source Code (repository root)
+
+```text
+src/scaffold_ca_python/
+├── core/
+│   ├── name_utils.py               # NEW fn: strip_usecase_suffix(name) -> str
+│   └── module_locator.py           # add <base>_usecase.py candidate before <name>.py, dedupe
+├── commands/
+│   └── generate_use_case.py        # normalize name, empty-base error, src + test conflict checks, dry-run title, epilog
+├── factory/simple/
+│   ├── use_case_factory.py         # write <base>_usecase.py / test_<base>_usecase.py
+│   └── delete_module_factory.py    # docstring only (lookup already shared)
+└── templates/use_case/
+    ├── use_case.py.jinja2          # unchanged
+    └── test_use_case.py.jinja2     # CHANGED: import from ...usecase.{{ module_name }}_usecase
+
+tests/
+├── core/test_name_utils.py                 # strip_usecase_suffix table (research R2)
+├── core/test_module_locator.py             # base name, suffixed name, both layouts, dedupe
+├── templates/test_use_case_templates.py    # new import path
+├── factory/simple/test_use_case_factory.py # new queued paths
+├── commands/test_generate_use_case.py      # new paths, 3 spellings, repeated suffix, empty base, conflict, legacy ignored, dry-run
+├── commands/test_delete_module.py          # delete by base / suffixed name, both layouts
+├── commands/test_workflow.py               # new use case path
+└── commands/test_performance.py            # --name perf, cleanup perf_usecase.py / test_perf_usecase.py
+```
+
+**Structure Decision**: Single-project CLI. Every change fits into existing modules. No new packages.
+
+## Implementation Order
+
+0. **Branch**: already on `feature/usecase-naming-standardization` (from `main`). Do not commit without asking the user.
+1. **Name helper (test-first)**: add the R2 table as parametrized tests in `test_name_utils.py`, then implement `strip_usecase_suffix`.
+2. **Template (test-first)**: assert the new import in `test_use_case_templates.py`, then change `test_use_case.py.jinja2`.
+3. **Factory (test-first)**: expect `create_order_usecase.py` / `test_create_order_usecase.py` in `test_use_case_factory.py`, then change `use_case_factory.py`.
+4. **Command (test-first)**: update and extend `test_generate_use_case.py` per [contracts/guc.md](contracts/guc.md), then normalize the name in `generate_use_case.py` (empty-base `fail()`, base-name `ModuleContext`, conflict path, dry-run title, epilog).
+5. **Lookup and delete (test-first)**: extend `test_module_locator.py` and `test_delete_module.py` per [contracts/dm.md](contracts/dm.md), then add the candidate in `module_locator.py` and update the `DeleteModuleFactory` docstring.
+6. **Remaining tests**: fix paths in `test_workflow.py` and the name and cleanup in `test_performance.py` (research R7).
+7. **Docs**: the README `scaffold guc` section notes the `<name>_usecase.py` output and that `_usecase` in `--name` is optional.
+8. **Validate**: run the [quickstart](quickstart.md), then `uv run ruff check`, `uv run ruff format --check`, `uv run mypy`, and `uv run pytest`.
+
+## Complexity Tracking
+
+No constitution violations to justify.

scaffold_ca_python-0.5.0/specs/026-usecase-naming-standardization/quickstart.md

@@ -0,0 +1,66 @@
+# Quickstart: Use Case Naming Standardization
+
+End-to-end checks for the [guc contract](contracts/guc.md) and the [dm contract](contracts/dm.md).
+
+## Setup
+
+```bash
+cd "$(mktemp -d)"
+uv run --project /path/to/scaffold-clean-architecture-py scaffold ca --name demo-app
+cd demo-app
+alias scaffold='uv run --project /path/to/scaffold-clean-architecture-py scaffold'
+```
+
+## 1. Suffix is added and never duplicated
+
+```bash
+scaffold guc --name paper
+ls src/demo_app/domain/usecase/      # paper_usecase.py
+ls src/tests/domain/usecase/         # test_paper_usecase.py
+grep '^class' src/demo_app/domain/usecase/paper_usecase.py   # class PaperUseCase:
+```
+
+```bash
+scaffold guc --name create_order_usecase
+grep '^class' src/demo_app/domain/usecase/create_order_usecase.py   # class CreateOrderUseCase:
+```
+
+Expected: no file name or class contains the suffix twice.
+
+## 2. Every spelling maps to the same module
+
+```bash
+scaffold guc --name paper_use_case        # exit 1: paper_usecase.py already exists
+scaffold guc --name paper_usecase_usecase # exit 1: same file
+scaffold guc --name usecase               # exit 1: only the suffix, with hint
+```
+
+## 3. Dry-run matches the real run
+
+```bash
+scaffold guc --name invoice_usecase --dry-run   # lists invoice_usecase.py and test_invoice_usecase.py, writes nothing
+```
+
+## 4. Generated project stays green
+
+```bash
+uv run ruff check . && uv run ruff format --check . && uv run mypy src && uv run pytest
+```
+
+## 5. Delete by base name, suffixed name, and both layouts
+
+```bash
+scaffold dm --name paper            # preview lists paper_usecase.py and its test
+scaffold dm --name paper --confirm  # both removed
+scaffold dm --name create_order_usecase --confirm
+
+touch src/demo_app/domain/usecase/invoice.py
+scaffold guc --name invoice                  # succeeds, no warning; invoice.py untouched
+scaffold dm --name invoice                   # preview lists invoice_usecase.py, its test, and invoice.py
+```
+
+## 6. CLI checks
+
+```bash
+uv run ruff check && uv run ruff format --check && uv run mypy && uv run pytest
+```

scaffold_ca_python-0.5.0/specs/026-usecase-naming-standardization/research.md

@@ -0,0 +1,59 @@
+# Research: Use Case Naming Standardization
+
+## R1. Where the name is normalized
+
+- **Decision**: `generate_use_case.py` strips the suffix right after name validation and builds `ModuleContext(name=<base>, ...)`. All downstream names derive from the base name: `class_name` gives `<Base>` and `module_name` gives `<base>`. The factory and the test template append `_usecase`.
+- **Rationale**: `ModuleContext` is shared by every generator, so changing its computed fields would affect models, adapters, and helpers (out of scope). Passing the base name keeps the existing `{{ class_name }}UseCase` template line correct and fixes the doubled suffix with no template logic.
+- **Alternatives considered**:
+  - A use-case-specific context model with a `usecase_module` field. Rejected because it adds a type for one string concatenation.
+  - Stripping inside the Jinja template. Rejected because the file path is built in Python, not in the template, so the logic would be split across two places.
+
+## R2. Suffix-stripping rule
+
+- **Decision**: Add `strip_usecase_suffix(name: str) -> str` to `core/name_utils.py`. It prefixes the name with `_`, removes `(?:_(?:usecase|use_case))+$`, and drops the leading `_`.
+- **Rationale**: The leading `_` lets one regex handle both `book_usecase` and the suffix-only names `usecase` and `use_case` (which become empty), while `bookusecase` and `usecase_registry` stay untouched. The `+` removes repeated suffixes in any mix of spellings (clarification 2026-10-26).
+
+| Input | Base |
+|---|---|
+| `book` | `book` |
+| `book_usecase` / `book_use_case` | `book` |
+| `paper_usecase_usecase` / `paper_use_case_usecase` | `paper` |
+| `usecase_registry` | `usecase_registry` |
+| `bookusecase` | `bookusecase` |
+| `usecase` / `use_case` / `usecase_usecase` | empty |
+
+- **Alternatives considered**: A `while name.endswith(...)` loop. It works but needs a separate case for the bare `usecase` / `use_case` names.
+
+## R3. Empty base name
+
+- **Decision**: If the base is empty, call `fail()` with the message `Use case name '<name>' is only the 'usecase' suffix.` and the hint `Use a descriptive name such as 'create_order'.` This happens before the project-root lookup, right after `validate_name_or_exit`.
+- **Rationale**: Reuses the existing `fail()` helper (exit 1 plus hint, Principle VI). Failing before any path is computed guarantees nothing is written.
+
+## R4. Template change
+
+- **Decision**: Only `test_use_case.py.jinja2` changes. Its import becomes `from {{ project.python_package }}.domain.usecase.{{ module_name }}_usecase import {{ class_name }}UseCase`. `use_case.py.jinja2` is unchanged.
+- **Rationale**: With the base name in context, the class line is already right. Only the module path in the import has to match the new file name.
+
+## R5. Lookup and deletion
+
+- **Decision**: In `find_module_targets`, add a use case candidate `domain/usecase/<base>_usecase.py` (with `test_<base>_usecase.py`). It comes before the existing `domain/usecase/<snake>.py` candidate, which stays as the legacy lookup. If both candidates resolve to the same path (input already suffixed), it is added once. If the base is empty, the new candidate is skipped.
+- **Rationale**: `DeleteModuleFactory` already iterates `find_module_targets`, so delete-module and its preview pick up the change with no edit there. Keeping the legacy candidate satisfies FR-014. Checking both candidates satisfies FR-014a, where both layouts are listed and removed.
+
+| `dm --name` | Files checked |
+|---|---|
+| `book` | `book_usecase.py`, then `book.py` |
+| `book_usecase` | `book_usecase.py` (once) |
+| `book_use_case` | `book_usecase.py`, then `book_use_case.py` |
+
+- **Alternatives considered**: Normalizing the name in `delete_module.py` before lookup. Rejected because the legacy `<name>.py` file (and models or helpers whose name ends in `_usecase`) would no longer be found.
+
+## R6. Conflict check
+
+- **Decision**: `ensure_absent` checks both `src/<pkg>/domain/usecase/<base>_usecase.py` and `src/tests/domain/usecase/test_<base>_usecase.py`. Legacy `<base>.py` is not checked (clarification 2026-10-26, FR-009a).
+- **Rationale**: All three spellings resolve to the same paths, so these checks cover FR-009. Checking the test file up front (FR-009b) avoids the `FileWriter` pre-flight raising an unhandled `FileExistsError` after parent folders were created. Feature 025 (research R4) found and fixed the same problem for models.
+
+## R7. Existing tests that encode the old names
+
+- **Decision**: Update the paths in `tests/commands/test_generate_use_case.py`, `tests/factory/simple/test_use_case_factory.py`, `tests/commands/test_workflow.py`, and `tests/commands/test_performance.py`. In `test_performance.py`, also change `--name PerfCase` to `perf`, which generates `perf_usecase.py` with `class PerfUseCase`.
+- **Rationale**: `PerfCase` has been rejected by snake_case validation since feature 017, so the benchmark measures an error path today. Fixing the name makes it time real generation, and the cleanup has to delete `perf_usecase.py` and `test_perf_usecase.py`. The base name `perf` follows the new convention (the suffix comes from the generator). `perf_case` would produce `perf_case_usecase.py`, mixing "case" and "use case".
+- **Alternatives considered**: `--name perf_usecase`. It produces the same files, but the benchmark should time the plain generation path. Suffix stripping is already covered by the unit and command tests.

scaffold_ca_python-0.5.0/specs/026-usecase-naming-standardization/spec.md

@@ -0,0 +1,170 @@
+# Feature Specification: Use Case Naming Standardization
+
+**Feature Branch**: `feature/usecase-naming-standardization`
+
+**Created**: 2026-10-26
+
+**Status**: Draft
+
+**Input**: User description: "Standardize the naming of generated use cases in the `scaffold generate-use-case` (alias `guc`) command. The generated module must always end with `_usecase` (`<base>_usecase.py`) and the class must always be `<Base>UseCase`, whether or not the user includes the `usecase` word in `--name`, so the suffix is never duplicated."
+
+## Clarifications
+
+### Session 2026-10-26
+
+- Q: If a legacy `domain/usecase/<name>.py` exists and the developer runs `scaffold guc --name <name>`, what should happen? → A: Ignore legacy files. Whatever `--name` the user sends (for example `paper`), the command always creates `<name>_usecase.py`, with no warning and no conflict. `book` in this spec is only an example name.
+- Q: For a name that ends with the suffix more than once (for example `paper_usecase_usecase`), how many trailing suffixes are removed? → A: All of them, in any mix of `_usecase` and `_use_case`. The result is `paper_usecase.py` with the class `PaperUseCase`.
+- Q: If both a legacy `<name>.py` and a new `<name>_usecase.py` exist, what does `scaffold dm --name <name>` delete? → A: Both files and their tests. The preview lists all of them before anything is removed.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Generated use case modules always carry the `_usecase` suffix (Priority: P1)
+
+A developer working in a generated Clean Architecture project runs `scaffold guc --name book`. Today this creates `domain/usecase/book.py`, a file name that does not say it holds a use case. After this feature the command creates `domain/usecase/book_usecase.py` with the class `BookUseCase`, and the mirrored test `src/tests/domain/usecase/test_book_usecase.py`.
+
+Resulting structure inside the generated project:
+
+```text
+src/<package>/domain/usecase/
+└── book_usecase.py          # class BookUseCase
+src/tests/domain/usecase/
+└── test_book_usecase.py     # imports BookUseCase from book_usecase
+```
+
+**Why this priority**: This is the core of the feature. Every generated use case module becomes recognizable by name and follows one convention across all generated projects.
+
+**Independent Test**: In a freshly scaffolded project, run `scaffold guc --name book` and verify the file names, the class name, and that the generated project's test suite passes.
+
+**Acceptance Scenarios**:
+
+1. **Given** a valid project with no `book` use case, **When** the developer runs `scaffold guc --name book`, **Then** `domain/usecase/book_usecase.py` and `src/tests/domain/usecase/test_book_usecase.py` are created, and the command exits with code 0.
+2. **Given** the command above has run, **When** the developer opens `book_usecase.py`, **Then** it defines exactly one class named `BookUseCase`.
+3. **Given** the command above has run, **When** the developer opens `test_book_usecase.py`, **Then** it imports `BookUseCase` from the `book_usecase` module, and the generated project's lint, format, type-check, and test checks pass without manual edits.
+4. **Given** a valid project, **When** the developer runs `scaffold guc --name create_order`, **Then** the command creates `create_order_usecase.py` with the class `CreateOrderUseCase` and the test `test_create_order_usecase.py`.
+5. **Given** a valid project, **When** the developer runs `scaffold generate-use-case --name book` (the long form), **Then** the result is identical to running `scaffold guc --name book`.
+6. **Given** the command above has run, **Then** the success message reports the class name `BookUseCase` and the number of files created.
+
+---
+
+### User Story 2 - The suffix is never duplicated (Priority: P1)
+
+A developer who already thinks of the module as a use case runs `scaffold guc --name book_usecase` or `scaffold guc --name book_use_case`. Today the class ends up as `BookUsecaseUseCase`. After this feature, the command recognizes the trailing suffix and produces exactly the same output as `scaffold guc --name book`.
+
+**Why this priority**: The duplicated suffix is the reported bug. Producing the same result regardless of how the user writes the name removes it and makes the command predictable.
+
+**Independent Test**: Run the command with `book`, `book_usecase`, and `book_use_case` in three fresh projects and verify that the three produce identical file names, class names, and file contents.
+
+**Acceptance Scenarios**:
+
+1. **Given** a valid project, **When** the developer runs `scaffold guc --name book_usecase`, **Then** the command creates `book_usecase.py` with the class `BookUseCase` and the test `test_book_usecase.py`. No file or class contains the suffix twice.
+2. **Given** a valid project, **When** the developer runs `scaffold guc --name book_use_case`, **Then** the result is identical to scenario 1.
+3. **Given** a valid project, **When** the developer runs `scaffold guc --name create_order_usecase`, **Then** the command creates `create_order_usecase.py` with the class `CreateOrderUseCase`.
+4. **Given** a valid project, **When** the developer runs `scaffold guc --name usecase_registry`, **Then** only a trailing suffix is considered, so the command creates `usecase_registry_usecase.py` with the class `UsecaseRegistryUseCase`.
+
+---
+
+### User Story 3 - Preview and conflict detection use the normalized name (Priority: P2)
+
+A developer previews generation with `--dry-run`, or runs the command again for a use case that already exists under a different spelling. Both the preview and the "already exists" check use the normalized module name, so the preview is accurate and existing work is never overwritten.
+
+**Why this priority**: The constitution requires `--dry-run` on every command, and overwriting a hand-edited use case would destroy work. Both must agree with the new naming.
+
+**Independent Test**: Run `scaffold guc --name book_usecase --dry-run` and verify the listed files, then generate `book` and try to generate `book_usecase` and verify the conflict.
+
+**Acceptance Scenarios**:
+
+1. **Given** a valid project, **When** the developer runs `scaffold guc --name book --dry-run` or `scaffold guc --name book_usecase --dry-run`, **Then** the output lists `book_usecase.py` and `test_book_usecase.py`, and nothing is written to disk.
+2. **Given** a valid project, **When** the developer runs the same command without `--dry-run`, **Then** the files created match exactly the files listed by the dry-run.
+3. **Given** `domain/usecase/book_usecase.py` already exists, **When** the developer runs `scaffold guc --name book`, `--name book_usecase`, or `--name book_use_case`, **Then** the command exits with code 1, prints a clear message with a resolution hint, and writes no files.
+
+---
+
+### User Story 4 - Delete a use case by base name or suffixed name (Priority: P3)
+
+A developer removes a use case with the delete-module command (`scaffold dm` / `scaffold delete-module`). The developer can refer to it either by its base name (`book`) or by its suffixed name (`book_usecase`), and the command finds `book_usecase.py` and its test. Use cases generated by earlier versions of the tool (`book.py`) can still be deleted by their original name.
+
+**Why this priority**: Without this, deleting by the name used at generation time (`book`) would no longer find the use case. It is lower priority because deletion is used less often than generation.
+
+**Independent Test**: Generate `book`, then run the delete-module command once with `--name book` and once with `--name book_usecase` in separate projects, and verify both remove the use case and its test. Repeat with a legacy `book.py` use case.
+
+**Acceptance Scenarios**:
+
+1. **Given** a use case `book_usecase.py` with its test `test_book_usecase.py`, **When** the developer runs `scaffold dm --name book --confirm`, **Then** both files are removed.
+2. **Given** the same use case, **When** the developer runs `scaffold dm --name book_usecase --confirm`, **Then** both files are removed.
+3. **Given** the same use case, **When** the developer runs `scaffold dm --name book` with `--dry-run` or without `--confirm`, **Then** the preview lists `book_usecase.py` and `test_book_usecase.py`, and nothing is removed.
+4. **Given** a legacy use case `domain/usecase/book.py` with its test `test_book.py`, **When** the developer runs `scaffold dm --name book --confirm`, **Then** both files are removed, as they are today.
+5. **Given** both a legacy `book.py` and a new `book_usecase.py`, each with its test, **When** the developer runs `scaffold dm --name book` without `--confirm`, **Then** the preview lists all four files, and **When** the developer adds `--confirm`, **Then** all four files are removed.
+6. **Given** a model generated with `scaffold gm --name book` and a use case generated with `scaffold guc --name book`, **When** the developer runs `scaffold dm --name book` without `--confirm`, **Then** the preview lists the model package, its tests folder, `book_usecase.py`, and `test_book_usecase.py`, so the developer sees that both layers match before confirming. To remove only the use case's files, the developer deletes them by hand. A layer selector for delete-module is out of scope.
+
+---
+
+### Edge Cases
+
+- **Name is only the suffix**: `scaffold guc --name usecase`, `--name use_case`, or a repetition such as `--name usecase_usecase` leaves no base name. The command exits with code 1, prints a clear message with a resolution hint (for example, suggesting a name such as `create_order`), and writes nothing.
+- **Suffix not at the end**: the word `usecase` anywhere other than the end of the name (for example, `usecase_registry`) is kept as part of the base name.
+- **Suffix glued to another word**: a name like `bookusecase` (no underscore) is not recognized as suffixed. It produces `bookusecase_usecase.py` with the class `BookusecaseUseCase`.
+- **Repeated suffix**: all trailing suffixes are removed, in any mix of spellings. `paper_usecase_usecase` and `paper_use_case_usecase` both produce `paper_usecase.py` with the class `PaperUseCase`.
+- **Invalid names**: names that are not valid snake_case module names, such as `Book`, `my-book`, or `1book`, exit with code 1 and the existing validation message. Nothing is written.
+- **Outside a project**: running the command outside a Clean Architecture project root exits with code 1 and the existing message.
+- **No arguments**: running `scaffold guc` with no arguments shows help and exits with code 0.
+- **Legacy modules**: an existing legacy `domain/usecase/<name>.py` is ignored by generation. Running `scaffold guc --name <name>` creates `<name>_usecase.py` with no warning and no conflict, and the old file is left untouched.
+- **Delete name matches other layers**: if the delete name also matches a model, adapter, entry point, or helper, the delete-module command lists every match, as it does today. Because a model and its use case usually share the base name (model `book`, use case `book_usecase.py`), `dm --name book` normally matches both. The preview shows every match before `--confirm` (US4 scenario 6).
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The generate-use-case command (`guc` / `generate-use-case`) MUST derive a base name from `--name` by repeatedly removing a trailing `_usecase` or `_use_case` suffix until none remains. If there is no such suffix, the base name is `--name` unchanged.
+- **FR-002**: The command MUST create the use case module at `domain/usecase/<base>_usecase.py`.
+- **FR-003**: The command MUST create the test stub at `src/tests/domain/usecase/test_<base>_usecase.py`.
+- **FR-004**: The generated class MUST be named `<Base>UseCase`, where `<Base>` is the PascalCase form of the base name, and the `UseCase` suffix MUST appear exactly once.
+- **FR-005**: The generated test stub MUST import `<Base>UseCase` from the `<base>_usecase` module.
+- **FR-006**: The inputs `<base>`, `<base>_usecase`, and `<base>_use_case` MUST produce identical file paths, class names, and file contents.
+- **FR-007**: Only a trailing suffix MUST be removed. The word `usecase` or `use_case` appearing elsewhere in the name MUST be preserved.
+- **FR-008**: If removing the suffixes leaves an empty base name (for example `--name usecase`, `--name use_case`, or `--name usecase_usecase`), the command MUST exit with code 1, print a clear message with a resolution hint, and write no files.
+- **FR-009**: The "already exists" check MUST use the normalized module path `domain/usecase/<base>_usecase.py`, so that any spelling of an existing use case is reported as a conflict (exit code 1, resolution hint, no files written).
+- **FR-009a**: A legacy use case file `domain/usecase/<name>.py` MUST NOT be treated as a conflict and MUST NOT trigger a warning. Generation proceeds and leaves it untouched.
+- **FR-009b**: The command MUST also exit with code 1, with a clear message and a resolution hint, and write no files, if `src/tests/domain/usecase/test_<base>_usecase.py` already exists.
+- **FR-010**: `--dry-run` MUST list the normalized file paths and MUST write nothing.
+- **FR-011**: The success message MUST report the normalized class name `<Base>UseCase` and the number of files created.
+- **FR-012**: The command MUST keep its current snake_case name validation, project-root detection, and no-argument help behavior, including exit codes and messages.
+- **FR-013**: The delete-module command (`dm` / `delete-module`) MUST find a use case generated with the new convention when given either the base name or the suffixed name (`_usecase` or `_use_case`), and remove both the module and its test.
+- **FR-014**: The delete-module command MUST continue to find and remove legacy use cases (`domain/usecase/<name>.py` and `test_<name>.py`) by their original name.
+- **FR-014a**: When both a legacy `domain/usecase/<base>.py` and a new `domain/usecase/<base>_usecase.py` exist, the delete-module command MUST list both modules and their tests in the preview and remove all of them on `--confirm`.
+- **FR-015**: All generated files MUST keep coming from versioned templates, and every changed template MUST have rendering tests (Constitution Principle II).
+- **FR-016**: The command's help text and the project README MUST show the `<base>_usecase.py` convention in their examples.
+
+### Key Entities
+
+- **Use Case Base Name**: The `--name` value with every trailing `_usecase` or `_use_case` suffix removed. All file and class names derive from it.
+- **Use Case Module**: The file `domain/usecase/<base>_usecase.py` that contains the use case class.
+- **Use Case Class**: The class `<Base>UseCase` defined in the use case module.
+- **Use Case Test Stub**: The file `src/tests/domain/usecase/test_<base>_usecase.py` that imports and exercises the use case class.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 100% of use cases generated after this feature have a module file name ending in `_usecase.py` and a class name ending in exactly one `UseCase`.
+- **SC-002**: For every base name tested, the three spellings (`<base>`, `<base>_usecase`, `<base>_use_case`) produce byte-identical output.
+- **SC-003**: 0 generated class names contain the suffix twice, whatever the input (for example, `--name book_usecase` and `--name book_usecase_usecase` never produce `BookUsecaseUseCase`).
+- **SC-004**: In 100% of freshly scaffolded projects, the generated project's lint, format, type-check, and test checks pass immediately after generating a use case, with no manual edits.
+- **SC-005**: The files listed by `--dry-run` match the files actually created in 100% of runs.
+- **SC-006**: Re-running the command for an existing use case under any of the three spellings never modifies an existing file.
+- **SC-007**: The CLI's own test suite covers generation, suffix stripping for both spellings and repeated suffixes, the suffix-only error, dry-run, conflict detection (source and test file), legacy files being ignored by generation, and deletion by base name, suffixed name, legacy name, and with both layouts present, and stays at or above the 80% coverage gate.
+
+## Assumptions
+
+- `_usecase` is the canonical module suffix. `_use_case` is accepted as input only and is always normalized to `_usecase` in file names.
+- The class name suffix stays `UseCase` (capital U and C) as it is today. Only the module and test file names change.
+- Suffix detection is case-sensitive and requires the underscore separator. This matches the existing snake_case-only validation, which already rejects uppercase input.
+- The content of the generated use case and test templates is unchanged apart from the module name used in the test import.
+- The `--name` help text keeps asking for a snake_case name. It does not need to tell users to include or omit the suffix, because both forms work.
+- All work for this feature MUST happen on the branch `feature/usecase-naming-standardization`, created from `main`, following Constitution Principle VII.
+
+### Out of Scope
+
+- Renaming or migrating use case files already generated in existing projects. Legacy `<name>.py` use cases are left as-is.
+- Changing the naming of other generators (models, gateways, driven adapters, entry points, helpers).
+- Automatically wiring the generated use case into the application's dependency container.
+- A layer selector (for example `--layer`) for the delete-module command to target only the model or only the use case when both share a name.