feat: Add missing 'add' subcommands for views and specification (#392) by paulefl · Pull Request #393 · docToolchain/Bausteinsicht

paulefl · 2026-05-08T10:10:19Z

Summary

Implements complete Issue #392 - add missing subcommands for views and specification with full documentation and tests.

Implementation (3 Phases)

Phase 1: `bausteinsicht add view` command (`aab808b`)

Creates or updates views in the model
Flags: --scope, --include (repeatable), --title, --description
Validates scope and include elements exist
Supports JSON output format
Key feature: enables LLM-driven dynamic view filtering

Phase 2: `bausteinsicht add specification` commands (`da396ef`)

add specification element <key>: Define custom element types
- Flags: --notation (required), --description, --container
- Validates key format (lowercase letters, digits, hyphens, underscores)
add specification relationship <key>: Define custom relationship types
- Flags: --notation (required), --description, --dashed
- Validates key format
Both support JSON output format
Enables custom notation extensibility for architecture models

Phase 3: Documentation (`5bdebee`)

Updated CLI specification with comprehensive command documentation
Added to Command Overview table (marked as Implemented)
Complete flags tables, behavior descriptions, exit codes
Realistic usage examples for each command

Test Plan

✅ Unit tests pass for all new commands
✅ Model validation tests cover error cases
✅ Integration tests verify JSONC file updates
✅ JSON output format tested for all commands
✅ Wildcard patterns supported in view include lists
✅ Command names match specification (no typos)
✅ Exit codes align with documented values (0/1/2)

Key Features

LLM-Friendly: All commands support JSON output for AI agent integration
Comprehensive Validation: Keys, elements, relationships, and types validated
Comment-Preserving Updates: JSONC file structure and comments preserved
Flexible Include Patterns: Views support wildcard patterns like system.*
Extensibility: Custom element and relationship types enable domain-specific notations

🤖 Generated with Claude Code

raifdmueller

Code Review

Good implementation of add view and add specification subcommands with solid input validation and test coverage. Two issues before merging:

Wait for #389: Both PRs modify internal/export/export.go — rebase onto main after #389 merges to avoid conflicts.
Silent JSON errors: Lines 130 and 218 discard marshal errors (_, _ = json.MarshalIndent(...)). Use proper error handling here.

Otherwise merge-ready.

…DR-006 from PR #393 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: add ADR-006 - Testing Strategy (Unit/Integration/E2E classification) Documents decision to adopt three-tier testing strategy: - Unit tests (70%): pure functions, <100ms, in *_test.go - Integration tests (25%): multiple components with I/O, <1s - E2E tests (5%): full CLI workflows, <5s Defines coverage targets per package (80-95%) and migration path. Covers mocking policy, rationale for test pyramid, and consequences. Closes #353 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> * chore(adr): rename ADR-006 to ADR-007 to avoid naming conflict with ADR-006 from PR #393 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(lint): resolve staticcheck issues in graph, health, and analyzer files - fmt.Fprintf instead of WriteString(fmt.Sprintf(...)) - Remove unused inDegree/outDegree fields from NodeInfo - Use tagged switch on elem.Status in health analyzer Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(lint): convert remaining WriteString(fmt.Sprintf) to fmt.Fprintf Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com> Co-authored-by: R{AI}f D. Müller <ralf.d.mueller+AI@gmail.com>

paulefl · 2026-05-27T09:53:46Z

Code & Security Review — abgeschlossen ✅

Security Review: Keine Findings. Eingaben werden durch Regex validiert, kein Shell-Execution-Pfad, kein Injection-Risiko.

Code Review: 3 Issues gefunden und direkt gefixt (Commit b73d522):

#	Problem	Fix
1	`internal/export/export.go` enthielt unrelated Debug-Logging-Änderungen (Konflikt mit #389)	Auf main-Stand revertiert
2	Nil-Map-Panic in `AddSpecificationElement` wenn `specification.elements` im Modell fehlt	Nil-Guard vor Zuweisung ergänzt
3	Nicht-deterministischer `Include`-Order beim View-Merge (unnötige Git-Diffs)	`sort.Strings(merged)` ergänzt

CI: ✅ Grün — merge-bereit nach CI-Bestätigung.

github-actions · 2026-05-27T10:35:35Z

📊 Test Report (Multi-OS)

Metric	🐧 Linux	🪟 Windows	🍎 macOS
Total Tests	827	827	827
✅ Passed	824 (99.6%)	824 (99.6%)	824 (99.6%)
❌ Failed	0	0	0
⏱️ Duration	7.13s	10.80s	7.17s
📦 Coverage	69.0%	68.9%	69.0%

💡 Full report: Download artifacts from this workflow run.

paulefl · 2026-05-27T11:06:04Z

Review-Feedback umgesetzt

1. Warten auf #389 — Kein Blocker mehr: #389 hat keine Konflikte, und dieser Branch wurde auf main rebased (a752474). Nach dem Merge von #389 in main kann dieser Branch nochmals rebased werden, falls nötig.

2. Silent JSON errors (commit d9bf9bc):

add_view.go:104: _, _ = json.MarshalIndent(...) → jsonBytes, err := ... mit if err != nil { return fmt.Errorf(...) }
add_specification.go:105 und :193: identische Fix-Anwendung

Beide Review-Punkte sind damit adressiert.

github-actions · 2026-05-27T11:07:43Z

📊 Test Report (Multi-OS)

Metric	🐧 Linux	🪟 Windows	🍎 macOS
Total Tests	827	827	827
✅ Passed	824 (99.6%)	824 (99.6%)	824 (99.6%)
❌ Failed	0	0	0
⏱️ Duration	7.09s	11.25s	6.78s
📦 Coverage	68.9%	68.9%	68.9%

💡 Full report: Download artifacts from this workflow run.

Adds ability to create views and modify include lists via CLI. Changes: - cmd/bausteinsicht/add_view.go: New 'add view' command - Flags: --scope, --include (repeatable), --title, --description - Validates scope and include elements exist - Supports JSON output format - cmd/bausteinsicht/add.go: Register new subcommand - internal/model/add.go: Model methods - AddView() with validation - AddSpecificationElement() (Phase 2 preparation) - AddSpecificationRelationship() (Phase 2 preparation) - internal/model/add_test.go: Comprehensive tests - AddView with valid/invalid scopes/includes - Wildcard pattern support - View updates - Specification element/relationship creation Tests: All passing Build: Successful Fixes #392 Phase 1: Enhanced path detection across platforms. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Adds ability to define new element and relationship types via CLI. Changes: - cmd/bausteinsicht/add_specification.go: New specification commands - 'add specification element <key>' command Flags: --notation (required), --description, --container - 'add specification relationship <key>' command Flags: --notation (required), --description, --dashed - Validates key format (lowercase, digits, hyphens, underscores) - Supports JSON output format - cmd/bausteinsicht/add_specification_test.go: Key validation tests - cmd/bausteinsicht/add.go: Register new subcommand Uses existing AddSpecificationElement() and AddSpecificationRelationship() methods from internal/model/add.go. Tests: All model tests passing (11+ Add-related tests) Build: Successful Fixes #392 Phase 2: Add specification element/relationship commands. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

…ands (#392 Phase 3) Add complete documentation for: - bausteinsicht add view: create views with scope, include filters, title, description - bausteinsicht add specification element: define custom element types with notation, description, container flag - bausteinsicht add specification relationship: define custom relationship types with notation, description, dashed flag Includes flags tables, behavior descriptions, exit codes, and realistic examples for all new commands. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Views must have a title per validateViews() in internal/model/validate.go. This change enforces the requirement at CLI level using Cobra's MarkFlagRequired(). Also updated CLI specification documentation to reflect required flag status. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Add comprehensive tests for: - add view: validates --title is required - add specification element: validates --notation is required - add specification relationship: validates --notation is required - add element: already had tests, but now validates all required flags - add relationship: already had tests, but validates --from and --to required Tests cover both missing flag errors and successful execution with flags. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Consistency fix: 'add view' now rejects duplicate view keys (exit code 1) instead of silently updating the view. This aligns with the behavior of: - add element (rejects duplicate elements) - add relationship (rejects duplicate relationships) - add specification element (rejects duplicate element types) - add specification relationship (rejects duplicate relationship types) Updated: - internal/model/add.go: AddView() now checks for duplicate keys - internal/model/add_test.go: Changed UpdateExisting test to DuplicateKey test - cmd/bausteinsicht/add_view_test.go: Added TestAddViewCmd_DuplicateView - src/docs/spec/02_cli_specification.adoc: Updated behavior and exit codes Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Changed from strict duplicate-rejection to merge-friendly behavior: - New views: require --title - Existing views: merge/update fields - --title, --scope, --description update respective fields - --include elements are added to list (deduplicated) Added ADR-006 documenting the CLI Add Command Strategy. Implementation: - internal/model/add.go: Updated AddView() with merge logic - internal/model/add_test.go: Added merge tests - cmd/bausteinsicht/add_view.go: Made --title optional, validate for new views - cmd/bausteinsicht/add_view_test.go: Test merge scenarios - src/docs/spec/02_cli_specification.adoc: Updated with merge behavior - src/docs/arc42/ADRs/ADR-006-CLI-Add-Command-Strategy.adoc: NEW This enables LLM-friendly incremental model building as per Issue #392. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

… includes - Revert export.go to main state — debug logging changes belong in #389, not here - Add nil-guard before m.Specification.Elements assignment to prevent panic when model has no specification.elements section - Sort merged Include list in AddView to produce deterministic JSONC output Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…output Replace silent error discard with proper error propagation in the JSON output path of runAddView and the two runAddSpecification* functions. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

raifdmueller

Rebased onto main (post-#389 merge). JSON error handling already fixed by author in last commit. Merge-ready.

sonarqubecloud · 2026-05-27T13:35:04Z

Quality Gate failed

Failed conditions
4.8% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud

github-actions · 2026-05-27T13:36:19Z

📊 Test Report (Multi-OS)

Metric	🐧 Linux	🪟 Windows	🍎 macOS
Total Tests	832	832	832
✅ Passed	829 (99.6%)	829 (99.6%)	829 (99.6%)
❌ Failed	0	0	0
⏱️ Duration	7.41s	10.92s	6.82s
📦 Coverage	69.0%	68.9%	69.0%

💡 Full report: Download artifacts from this workflow run.

paulefl mentioned this pull request May 8, 2026

feat: Add missing 'add' subcommands for views and specification #392

Closed

paulefl linked an issue May 8, 2026 that may be closed by this pull request

feat: Add missing 'add' subcommands for views and specification #392

Closed

raifdmueller mentioned this pull request May 26, 2026

fix(export): Improve draw.io CLI detection for Windows/Scoop/macOS (#388) #389

Merged

raifdmueller requested changes May 26, 2026

View reviewed changes

raifdmueller mentioned this pull request May 26, 2026

docs: ADR-006 - Testing Strategy #374

Merged

raifdmueller added a commit that referenced this pull request May 26, 2026

chore(adr): rename ADR-006 to ADR-007 to avoid naming conflict with A…

8842a14

…DR-006 from PR #393 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

paulefl assigned raifdmueller May 27, 2026

paulefl force-pushed the 392-feat-add-missing-add-subcommands-for-views-and-specification branch from b73d522 to a752474 Compare May 27, 2026 10:34

paulefl and others added 9 commits May 27, 2026 13:33

fix(add): handle json.MarshalIndent errors in add view/specification …

a70550e

…output Replace silent error discard with proper error propagation in the JSON output path of runAddView and the two runAddSpecification* functions. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

raifdmueller force-pushed the 392-feat-add-missing-add-subcommands-for-views-and-specification branch from d9bf9bc to a70550e Compare May 27, 2026 13:34

raifdmueller approved these changes May 27, 2026

View reviewed changes

raifdmueller merged commit 38479a2 into main May 27, 2026
10 of 12 checks passed

raifdmueller deleted the 392-feat-add-missing-add-subcommands-for-views-and-specification branch May 27, 2026 13:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add missing 'add' subcommands for views and specification (#392)#393

feat: Add missing 'add' subcommands for views and specification (#392)#393
raifdmueller merged 9 commits into
mainfrom
392-feat-add-missing-add-subcommands-for-views-and-specification

paulefl commented May 8, 2026

Uh oh!

raifdmueller left a comment

Uh oh!

paulefl commented May 27, 2026

Uh oh!

github-actions Bot commented May 27, 2026

Uh oh!

paulefl commented May 27, 2026

Uh oh!

github-actions Bot commented May 27, 2026

Uh oh!

raifdmueller left a comment

Uh oh!

sonarqubecloud Bot commented May 27, 2026

Uh oh!

github-actions Bot commented May 27, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

paulefl commented May 8, 2026

Summary

Implementation (3 Phases)

Phase 1: bausteinsicht add view command (aab808b)

Phase 2: bausteinsicht add specification commands (da396ef)

Phase 3: Documentation (5bdebee)

Test Plan

Key Features

Uh oh!

raifdmueller left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

paulefl commented May 27, 2026

Code & Security Review — abgeschlossen ✅

Uh oh!

github-actions Bot commented May 27, 2026

📊 Test Report (Multi-OS)

Uh oh!

paulefl commented May 27, 2026

Review-Feedback umgesetzt

Uh oh!

github-actions Bot commented May 27, 2026

📊 Test Report (Multi-OS)

Uh oh!

raifdmueller left a comment

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented May 27, 2026

Quality Gate failed

Uh oh!

github-actions Bot commented May 27, 2026

📊 Test Report (Multi-OS)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Phase 1: `bausteinsicht add view` command (`aab808b`)

Phase 2: `bausteinsicht add specification` commands (`da396ef`)

Phase 3: Documentation (`5bdebee`)