Initial commit

skills/c4model-c4/code-element-identification.md

@@ -0,0 +1,343 @@
+# Code Element Identification Methodology
+
+This guide provides comprehensive methodology for identifying code elements at the C4 (Code) level of the C4 Model.
+
+---
+
+## Code Element Types
+
+### 1. Classes
+
+**Detection patterns:**
+```typescript
+// TypeScript/JavaScript
+class ClassName { }
+export class ClassName { }
+abstract class ClassName { }
+export default class ClassName { }
+```
+
+```python
+# Python
+class ClassName:
+    pass
+
+class ClassName(ParentClass):
+    pass
+
+class ClassName(ABC):  # Abstract
+    pass
+```
+
+```java
+// Java
+public class ClassName { }
+public abstract class ClassName { }
+public final class ClassName { }
+```
+
+**ID format:** `{component}-{class-name}-class`
+**Example:** `auth-service-user-manager-class`
+
+---
+
+### 2. Functions
+
+**Detection patterns:**
+```typescript
+// TypeScript/JavaScript
+function functionName() { }
+export function functionName() { }
+const functionName = () => { }
+export const functionName = () => { }
+export default function functionName() { }
+```
+
+```python
+# Python
+def function_name():
+    pass
+```
+
+```java
+// Java - methods are always in classes
+public static void functionName() { }
+```
+
+**ID format:** `{component}-{function-name}`
+**Example:** `auth-service-validate-token`
+
+---
+
+### 3. Async Functions
+
+**Detection patterns:**
+```typescript
+// TypeScript/JavaScript
+async function functionName() { }
+export async function functionName() { }
+const functionName = async () => { }
+```
+
+```python
+# Python
+async def function_name():
+    pass
+```
+
+**ID format:** `{component}-{function-name}`
+**Example:** `auth-service-authenticate`
+
+---
+
+### 4. Methods
+
+**Detection patterns:**
+```typescript
+// TypeScript/JavaScript - inside class
+class Example {
+  methodName() { }
+  async methodName() { }
+  private methodName() { }
+  static methodName() { }
+  get propertyName() { }
+  set propertyName(value) { }
+}
+```
+
+```python
+# Python
+class Example:
+    def method_name(self):
+        pass
+
+    @classmethod
+    def class_method(cls):
+        pass
+
+    @staticmethod
+    def static_method():
+        pass
+```
+
+**ID format:** `{class-id}-{method-name}`
+**Example:** `auth-service-class-get-user`
+
+---
+
+### 5. Interfaces
+
+**Detection patterns:**
+```typescript
+// TypeScript
+interface InterfaceName { }
+export interface InterfaceName { }
+interface InterfaceName extends OtherInterface { }
+```
+
+```java
+// Java
+public interface InterfaceName { }
+public interface InterfaceName extends OtherInterface { }
+```
+
+**ID format:** `{component}-{interface-name}-interface`
+**Example:** `auth-service-i-user-repository-interface`
+
+---
+
+### 6. Types
+
+**Detection patterns:**
+```typescript
+// TypeScript
+type TypeName = string | number;
+export type TypeName = { field: string };
+type TypeName<T> = T[];
+type TypeName = Pick<OtherType, 'field'>;
+```
+
+**ID format:** `{component}-{type-name}-type`
+**Example:** `auth-service-user-credentials-type`
+
+---
+
+### 7. Constants
+
+**Detection patterns:**
+```typescript
+// TypeScript/JavaScript
+const CONSTANT_NAME = 'value';
+export const CONSTANT_NAME = 42;
+export const CONFIG = { ... } as const;
+```
+
+```python
+# Python
+CONSTANT_NAME = 'value'
+MAX_RETRIES = 3
+```
+
+```java
+// Java
+public static final String CONSTANT_NAME = "value";
+public static final int MAX_RETRIES = 3;
+```
+
+**ID format:** `{component}-{constant-name}-const`
+**Example:** `auth-service-max-login-attempts-const`
+
+---
+
+### 8. Enums
+
+**Detection patterns:**
+```typescript
+// TypeScript
+enum EnumName { A, B, C }
+export enum EnumName { A = 'a', B = 'b' }
+const enum EnumName { A, B, C }
+```
+
+```python
+# Python
+from enum import Enum
+
+class EnumName(Enum):
+    A = 1
+    B = 2
+```
+
+```java
+// Java
+public enum EnumName { A, B, C }
+```
+
+**ID format:** `{component}-{enum-name}-enum`
+**Example:** `auth-service-user-role-enum`
+
+---
+
+### 9. Decorators
+
+**Detection patterns:**
+```typescript
+// TypeScript
+function DecoratorName(target: any) { }
+export function DecoratorName(): MethodDecorator { }
+```
+
+```python
+# Python
+def decorator_name(func):
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+    return wrapper
+```
+
+**ID format:** `{component}-{decorator-name}-decorator`
+**Example:** `auth-service-authenticated-decorator`
+
+---
+
+## Significance Criteria
+
+Only document a code element if **ANY** of these apply:
+
+### Public API
+- Exported from module
+- Part of public interface
+- Used by external callers
+
+### Complexity
+- Lines of code > 20
+- Cyclomatic complexity > 4
+- Cognitive complexity > 10
+
+### Architecture
+- Implements design pattern
+- Key abstraction or facade
+- Entry point or controller action
+
+### Business Logic
+- Contains critical business rules
+- Handles sensitive data
+- Has security implications
+
+### Dependencies
+- Multiple callers (> 2)
+- Multiple dependencies (> 3)
+- Central to component
+
+---
+
+## Detection Commands
+
+```bash
+# TypeScript - Find classes
+grep -rn "^export class\|^class " src/ --include="*.ts"
+
+# TypeScript - Find functions
+grep -rn "^export function\|^export async function\|^export const.*=.*=>" src/ --include="*.ts"
+
+# TypeScript - Find interfaces
+grep -rn "^export interface\|^interface " src/ --include="*.ts"
+
+# TypeScript - Find types
+grep -rn "^export type\|^type " src/ --include="*.ts"
+
+# TypeScript - Find enums
+grep -rn "^export enum\|^enum " src/ --include="*.ts"
+
+# Python - Find classes
+grep -rn "^class " src/ --include="*.py"
+
+# Python - Find functions
+grep -rn "^def \|^async def " src/ --include="*.py"
+
+# Count lines per file
+wc -l src/**/*.ts | sort -n
+```
+
+---
+
+## Naming Conventions
+
+### ID Format
+- Use kebab-case
+- Include component prefix
+- Include element type suffix where helpful
+- Pattern: `{component-id}-{element-name}[-{type}]`
+
+### Name Field
+- Preserve original case (PascalCase, camelCase, snake_case)
+- Use exact name from source code
+
+### Examples
+
+| Source Name | ID | name |
+|------------|-----|------|
+| `UserService` | `auth-user-service-class` | `UserService` |
+| `authenticate` | `auth-authenticate` | `authenticate` |
+| `IUserRepository` | `auth-i-user-repository-interface` | `IUserRepository` |
+| `LoginCredentials` | `auth-login-credentials-type` | `LoginCredentials` |
+| `MAX_RETRIES` | `auth-max-retries-const` | `MAX_RETRIES` |
+| `UserRole` | `auth-user-role-enum` | `UserRole` |
+
+---
+
+## Best Practices
+
+### ✅ DO:
+- Focus on significant, public elements
+- Use consistent ID naming
+- Preserve original casing in name field
+- Document all public API elements
+- Include classes that define key abstractions
+
+### ❌ DON'T:
+- Document every private helper function
+- Document trivial getters/setters
+- Document test files as code elements
+- Use file names as element IDs
+- Skip exported functions/classes