Business Rules¶
BR-001: Non-Empty Project Name¶
Category: Policy
Statement: A project name must not be blank.
Rationale: The name is used in generated READMEs, CI/CD files, and MkDocs configuration; a blank name produces broken output.
Applies to: GenerationRequest
Violated when: --name is absent or contains only whitespace.
Error code: EMPTY_PROJECT_NAME — "project name must not be empty"
| Valid | Invalid |
|---|---|
My Project |
"" |
prjinit |
" " |
BR-002: Non-Empty Project Description¶
Category: Policy
Statement: A project description must not be blank.
Rationale: The description appears in generated READMEs and MkDocs site metadata; a blank value produces incomplete documentation.
Applies to: GenerationRequest
Violated when: --description is absent or contains only whitespace.
Error code: EMPTY_PROJECT_DESCRIPTION — "project description must not be empty"
| Valid | Invalid |
|---|---|
"Scaffolds new projects." |
"" |
BR-003: Non-Empty Target Path¶
Category: Policy
Statement: The target path must not be blank.
Rationale: The generator writes all output into the target path; without it no file can be created.
Applies to: GenerationRequest
Violated when: --targetpath is absent or contains only whitespace.
Error code: EMPTY_TARGET_PATH — "target path must not be empty"
| Valid | Invalid |
|---|---|
/home/user/repo |
"" |
./my-repo |
" " |
BR-004: Valid Language¶
Category: Policy
Statement: The target language must be one of cpp, go, or java.
Rationale: The generator only has template sets for these three languages.
Applies to: GenerationRequest
Violated when: --language is any value not in {cpp, go, java}.
Error code: INVALID_LANGUAGE — "invalid language: must be one of cpp, go, java"
| Valid | Invalid |
|---|---|
go |
python |
cpp |
rust |
java |
"" |
BR-005: Valid Project Type¶
Category: Policy
Statement: The project type must be one of embedded, library, service, or tool.
Rationale: The generator only has template sets for these four project types.
Applies to: GenerationRequest
Violated when: --projecttype is any value not in {embedded, library, service, tool}.
Error code: INVALID_PROJECT_TYPE — "invalid type: must be one of embedded, library, service, tool"
| Valid | Invalid |
|---|---|
service |
plugin |
library |
framework |
BR-006: Go Does Not Support Embedded Projects¶
Category: Invariant
Statement: The combination of language go and project type embedded is forbidden.
Rationale: Embedded and systems-level development in this domain targets C++ toolchains (AVR, ARM, etc.); Go has no applicable template set for this context.
Applies to: ProjectDescriptor
Violated when: Language is go AND ProjectType is embedded.
Error code: UNSUPPORTED_COMBINATION — "Go does not support embedded projects"
| Valid | Invalid |
|---|---|
go + service |
go + embedded |
cpp + embedded |
BR-007: Java Supports Only Library and Service Projects¶
Category: Invariant
Statement: The language java is restricted to project types library and service.
Rationale: CLI tool and embedded templates do not exist for Java in this generator; generating them would produce incomplete scaffolding.
Applies to: ProjectDescriptor
Violated when: Language is java AND ProjectType is embedded or tool.
Error code: UNSUPPORTED_COMBINATION — "Java supports only library and service projects"
| Valid | Invalid |
|---|---|
java + library |
java + tool |
java + service |
java + embedded |
BR-008: CI Type Is Inferred from Git Remote When Not Specified¶
Category: Policy
Statement: When --ci is not provided, the CI type is derived from the Git remote URL of the current repository.
Rationale: Avoids manual input for the common case where the remote URL unambiguously identifies the CI platform.
Applies to: GenerationRequest
Violated when: --ci is absent AND the Git remote is unreachable, missing, or does not contain github.com or gitlab.com.
Error code: CI_TYPE_UNRESOLVABLE — "could not determine CI type: pass --ci github or --ci gitlab explicitly"
| Valid | Invalid |
|---|---|
Remote URL contains github.com |
No Git remote configured |
Remote URL contains gitlab.com |
Remote URL from unknown host |
--ci github passed explicitly |
BR-009: Artifact Name Is Inferred from Git Remote When Not Specified¶
Category: Policy
Statement: When --artifactname is not provided, it is derived as the last path segment of the normalised Git remote URL.
Rationale: The remote repository slug is the natural artifact name, avoiding redundant manual input.
Applies to: GenerationRequest
Violated when: --artifactname is absent AND the Git remote is unreachable or unparseable.
Error code: ARTIFACT_NAME_UNRESOLVABLE — "could not determine technical artifact name: pass --artifactname explicitly"
| Valid | Invalid |
|---|---|
Remote gitlab.com/user/my-tool → my-tool |
No Git remote configured |
--artifactname my-tool passed explicitly |
BR-010: Go Module Path Is Inferred from Git Remote When Not Specified¶
Category: Policy
Statement: When --modulepath is not provided, it is derived as the normalised host/org/repo path of the Git remote URL.
Rationale: The remote URL is the canonical Go module path for hosted repositories, avoiding redundant manual input.
Applies to: GenerationRequest
Violated when: --modulepath is absent AND the Git remote is unreachable or unparseable.
Error code: MODULE_PATH_UNRESOLVABLE — "could not determine Go module path: pass --modulepath explicitly"
| Valid | Invalid |
|---|---|
Remote git@gitlab.com:user/proj.git -> gitlab.com/user/proj |
No Git remote configured |
--modulepath gitlab.com/user/proj passed explicitly |
BR-011: Universal Guidelines Are Always Generated¶
Category: Invariant
Statement: Every generated project must include the full set of universal guidelines regardless of language or project type.
Rationale: These guidelines encode the non-negotiable quality baseline for all projects produced by this generator.
Applies to: GeneratedProject
Violated when: Any of bash_coding, ci_cd, data_modeling, error_handling, general_coding, library_design, refactoring, security, or testing is absent from the output.
Error code: MISSING_UNIVERSAL_GUIDELINE — "universal guideline missing from output"
| Valid | Invalid |
|---|---|
All 9 guidelines present in specs/guidelines/ |
Any guideline missing from output |
BR-012: Generated Files Carry a Version Marker¶
Category: Invariant
Statement: Every file produced by the generator must contain a Generated by prjinit, version X.Y.Z marker.
Rationale: Consumers must be able to identify the generator version that produced a file and distinguish generated files from hand-authored ones.
Applies to: GeneratedFile
Violated when: A generated file contains no version marker.
Error code: MISSING_VERSION_MARKER — "generated file is missing the prjinit version marker"
| Valid | Invalid |
|---|---|
Markdown: *Generated by prjinit, version 1.2.3.* |
File has no version annotation |
Source: // Generated by prjinit, version 1.2.3. |
BR-013: C++ Artifact Names Are Sanitised to Valid Identifiers¶
Category: Invariant
Statement: Hyphens in the artifact name are replaced with underscores when used as a C++ namespace or include-directory name.
Rationale: Hyphens are not valid in C++ identifiers; using them verbatim would produce uncompilable code.
Applies to: ProjectDescriptor (C++ projects only)
Violated when: A C++ namespace or include path contains a hyphen character.
Error code: INVALID_CPP_NAMESPACE — "C++ namespace must not contain hyphens"
| Valid | Invalid |
|---|---|
artifact my-lib → namespace my_lib |
namespace my-lib |
artifact mylib → namespace mylib |
BR-014: Coverage Reports¶
Category: Invariant
Statement: All coverage reports, independent of programming language or artifact type, are stored in test_reports/coverage/. Coverage reports are in Cobertura format.
Rationale: Always clear where to find reports. Prominent format used by many tools. Folder can be provided for Download as a CI build artifact.
Applies to: All generated projects.
Violated when: never
Error code: not applicable
BR-016: Service Guidelines Are Generated for Service Projects¶
Category: Invariant
Statement: Every generated service project must include the full set of service-specific guidelines in addition to the universal guidelines.
Rationale: These guidelines encode quality standards that are specific to services — API contracts, process design, logging, monitoring, and cloud-native design — and are not applicable to libraries or CLI tools.
Applies to: GeneratedProject (project type service)
Violated when: Any of api_design, business_process_design, logging, monitoring, or service_design is absent from the output of a service project.
Error code: MISSING_SERVICE_GUIDELINE — "service guideline missing from output"
| Valid | Invalid |
|---|---|
All 5 service guidelines present in specs/guidelines/ |
Any guideline missing from service output |
BR-015: Unit Test Reports¶
Category: Invariant
Statement: All unit test reports, independent of programming language or artifact type, are stored in test_reports/test/. Reports are in JUnit XML format.
Rationale: Always clear where to find reports. Prominent format used by many tools. Folder can be provided for Download as a CI build artifact.
Applies to: All generated projects.
Violated when: never
Error code: not applicable