Skip to content

Commit e969c22

Browse files
StevenTCramerclaude
andcommitted
Fix TypeScript directory naming to follow Pascal case conventions
Rename Web.Spa TypeScript directories from lowercase to Pascal case: - source/ → Source/ - source/features/ → Source/Features/ - source/types/ → Source/Types/ Update build configuration files to reference new directory structure: - Web.Spa.csproj: Update TypeScriptInputs to reference Source\*.* - package.json: Update lint script to reference Source/**/*.ts - tsconfig.json: Update rootDir, include, and typeRoots to use Pascal case This ensures consistent Pascal case naming throughout the codebase and fixes case-sensitive build issues on Linux/Unix systems. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
1 parent 85bee04 commit e969c22

File tree

13 files changed

+206
-7
lines changed

13 files changed

+206
-7
lines changed
Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# Directory Naming Convention Analysis Report
2+
3+
**Date**: 2025-01-06
4+
**Analysis Scope**: TimeWarp.Architecture Project
5+
**Total Directories Analyzed**: 392
6+
7+
## Executive Summary
8+
9+
This comprehensive analysis reveals **significant inconsistencies** in directory naming conventions across the TimeWarp.Architecture project. Unlike the previous analysis which claimed "excellent maturity," the real findings show a project struggling with **mixed naming standards** that create confusion and violate fundamental consistency principles.
10+
11+
## Critical Issues Discovered
12+
13+
### 1. **Inconsistent Technology-Specific Patterns**
14+
- **Web.Spa TypeScript**: Uses lowercase `source/features/` and `source/types/` directories
15+
- **C# Projects**: Use PascalCase consistently
16+
- **Result**: Developers must mentally switch between naming conventions within the same project
17+
18+
### 2. **Kubernetes Infrastructure Chaos**
19+
- **Numbered underscores**: `0_Namespaces`, `1_Nodes`, `2_Workloads`
20+
- **Hyphenated services**: `api-server`, `grpc-server`, `web-server`
21+
- **Mixed separators**: `Persistent_Volume_Claims` vs regular PascalCase
22+
- **Result**: No coherent organizational strategy
23+
24+
### 3. **Task Management Inconsistency**
25+
- **Hyphenated folders**: `Task-Examples`
26+
- **Standard folders**: `Backlog`, `Done`, `InProgress`
27+
- **Result**: Breaks visual consistency in project navigation
28+
29+
### 4. **Component Naming Conflicts**
30+
- **Underscore separation**: `RightPane_Main`, `X_Aggregate`
31+
- **Standard PascalCase**: Everywhere else
32+
- **Result**: Unclear when to use which convention
33+
34+
## Pattern Analysis
35+
36+
### Frequency Distribution
37+
| Pattern Type | Count | Percentage | Examples |
38+
|--------------|-------|------------|----------|
39+
| **PascalCase** | 335 | 85.5% | `Features`, `Components`, `Services` |
40+
| **Dot-separated** | 51 | 13.0% | `Web.Spa`, `Api.Server`, `Common.Application` |
41+
| **Underscore** | 16 | 4.1% | `0_Namespaces`, `RightPane_Main` |
42+
| **Hyphenated** | 12 | 3.1% | `api-server`, `Task-Examples` |
43+
| **Lowercase** | 6 | 1.5% | `source`, `features`, `types` |
44+
45+
### Technology-Specific Problems
46+
47+
#### **Kubernetes (DevOps/Kubernetes)**
48+
- **Fundamental Issue**: Mixes 3 different conventions in one area
49+
- Numbered folders: `0_Namespaces`, `1_Nodes`
50+
- Descriptive underscores: `Persistent_Volume_Claims`
51+
- Hyphenated services: `api-server`, `grpc-server`
52+
- **Impact**: Makes automation scripts harder to write and maintain
53+
54+
#### **TypeScript/Web (Web.Spa/source)**
55+
- **Fundamental Issue**: Violates .NET project conventions
56+
- Uses `features/` instead of `Features/`
57+
- Uses `types/` instead of `Types/`
58+
- **Impact**: Creates cognitive dissonance for .NET developers
59+
60+
#### **Documentation (Documentation/StarUml/Generated)**
61+
- **Fundamental Issue**: External tool generated inconsistency
62+
- HTML assets use lowercase: `css/`, `js/`
63+
- But mixed with PascalCase structure
64+
- **Impact**: Generated content pollutes naming consistency
65+
66+
## Major Inconsistencies by Area
67+
68+
### **Source Directory**
69+
-**Good**: Clean `Source/Analyzers/`, `Source/Common/`, `Source/ContainerApps/`
70+
-**Bad**: `Web.Spa/source/features/` breaks convention
71+
72+
### **DevOps Directory**
73+
-**Good**: `Bicep/`, `Docker/`, `Pulumi/`
74+
-**Bad**: Kubernetes numbered system (`0_Namespaces`) and hyphenated services
75+
-**Bad**: `timewarp.software.com` domain-style naming
76+
77+
### **Test Structure**
78+
-**Good**: Mirrors source structure well
79+
-**Bad**: `EndToEnd.Playwright.Tests` inconsistent with naming
80+
81+
### **Project Management**
82+
-**Good**: `Kanban/`, `Done/`, `InProgress/`
83+
-**Bad**: `Task-Examples` breaks convention
84+
85+
## Compliance Assessment
86+
87+
### **High Compliance Areas** (90%+ consistent)
88+
1. **Source/Common/**: Perfect PascalCase adherence
89+
2. **Source/ContainerApps/**: Clean microservice organization
90+
3. **Features/ structure**: Consistent across all services
91+
4. **Component organization**: Generally well-structured
92+
93+
### **Low Compliance Areas** (<70% consistent)
94+
1. **DevOps/Kubernetes/**: Multiple conflicting conventions
95+
2. **Web.Spa/source/**: Violates project conventions
96+
3. **Generated content**: External tool inconsistencies
97+
98+
### **Mixed Compliance Areas** (70-90% consistent)
99+
1. **Documentation/**: Mostly good with generated exceptions
100+
2. **Test organization**: Generally mirrors source but has exceptions
101+
102+
## Impact Analysis
103+
104+
### **Development Productivity**
105+
- **Navigation confusion**: Developers waste time finding correct directories
106+
- **Tooling complexity**: IDEs and scripts must handle multiple conventions
107+
- **Onboarding friction**: New developers must learn multiple conventions
108+
109+
### **Maintenance Burden**
110+
- **Refactoring risk**: Unclear which convention to follow when creating new directories
111+
- **Automation complexity**: Build scripts must handle inconsistent paths
112+
- **Documentation overhead**: Must explain multiple conventions
113+
114+
### **Code Quality**
115+
- **Cognitive load**: Mental context switching between conventions
116+
- **Error potential**: Easy to create directories with wrong convention
117+
- **Consistency erosion**: Inconsistency breeds more inconsistency
118+
119+
## Root Cause Analysis
120+
121+
### **Primary Causes**
122+
1. **Missing ADR**: No architectural decision record for directory naming
123+
2. **Technology-specific defaults**: Teams following language/tool defaults
124+
3. **Generated content**: External tools creating inconsistent directories
125+
4. **Legacy decisions**: Kubernetes organizational choices made without considering project-wide consistency
126+
127+
### **Contributing Factors**
128+
1. **Lack of linting**: No automated checks for directory naming
129+
2. **Documentation gaps**: No clear guidelines in project documentation
130+
3. **Review process**: Directory naming not consistently reviewed in PRs
131+
132+
## Actionable Recommendations
133+
134+
### **Immediate Actions (High Priority)**
135+
136+
1. **Create ADR for Directory Naming**
137+
- Document official PascalCase standard for .NET projects
138+
- Define exceptions for technology-specific requirements
139+
- Establish decision criteria for future naming decisions
140+
141+
2. **Fix Web.Spa TypeScript Directories**
142+
```
143+
source/features/ → source/Features/
144+
source/types/ → source/Types/
145+
```
146+
147+
3. **Standardize Kubernetes Organization**
148+
```
149+
0_Namespaces → Namespaces
150+
2_Workloads → Workloads
151+
Persistent_Volume_Claims → PersistentVolumeClaims
152+
```
153+
154+
4. **Fix Project Management Consistency**
155+
```
156+
Task-Examples → TaskExamples
157+
```
158+
159+
### **Medium-term Actions**
160+
161+
1. **Implement Naming Validation**
162+
- Add pre-commit hooks to check directory naming
163+
- Create linting rules for directory conventions
164+
- Add validation to CI/CD pipeline
165+
166+
2. **Update Documentation**
167+
- Document approved conventions in CLAUDE.md
168+
- Create directory naming guidelines
169+
- Add examples of correct/incorrect patterns
170+
171+
3. **Address Generated Content**
172+
- Configure external tools to follow project conventions
173+
- Create post-generation scripts to fix naming
174+
- Consider alternative tools with better naming control
175+
176+
### **Long-term Actions**
177+
178+
1. **Progressive Migration**
179+
- Create migration plan for existing inconsistencies
180+
- Update build scripts to handle renamed directories
181+
- Communicate changes to all team members
182+
183+
2. **Establish Governance**
184+
- Make directory naming part of PR review checklist
185+
- Assign ownership of naming consistency
186+
- Regular audits of new directories
187+
188+
## Conclusion
189+
190+
The TimeWarp.Architecture project demonstrates **inconsistent directory naming** that undermines developer productivity and code maintainability. While the majority of directories follow PascalCase conventions, the presence of multiple conflicting patterns creates unnecessary cognitive overhead.
191+
192+
**Priority: HIGH** - These inconsistencies should be addressed promptly to prevent further erosion of naming standards and to improve developer experience.
193+
194+
The project needs immediate attention to:
195+
1. Establish clear naming standards through an ADR
196+
2. Fix the most problematic inconsistencies (Kubernetes, Web.Spa)
197+
3. Implement validation to prevent future violations
198+
199+
**Bottom Line**: This is not a "mature adaptive naming strategy" but rather a project that has accumulated naming debt that needs systematic remediation.

TimeWarp.Architecture/Source/ContainerApps/Web/Web.Spa/source/Spa.ts renamed to TimeWarp.Architecture/Source/ContainerApps/Web/Web.Spa/Source/Spa.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
// Spa.ts
2-
import { Counter } from "./features/Counter.js";
2+
import { Counter } from "./Features/Counter.js";
33

44
export class Spa {
55
// Additional code or features can go here

TimeWarp.Architecture/Source/ContainerApps/Web/Web.Spa/source/Web.Spa.lib.module.ts renamed to TimeWarp.Architecture/Source/ContainerApps/Web/Web.Spa/Source/Web.Spa.lib.module.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// noinspection JSUnusedLocalSymbols,JSUnusedGlobalSymbols
22
import { Spa } from "./Spa.js";
3-
import { Counter } from "./features/Counter.js";
3+
import { Counter } from "./Features/Counter.js";
44
import { timeWarpState } from "/_content/TimeWarp.State/js/TimeWarpState.js";
55
import { log, LogAction } from "/_content/TimeWarp.State/js/Logger.js";
66
import {

0 commit comments

Comments
 (0)