gh-cubical6-melly/skills/c4model-c4/signature-analysis.md

Signature Analysis Methodology

This guide provides methodology for extracting and documenting function, method, and interface signatures at the C4 Code level.

---

Parameter Extraction

Required Information

For each parameter, extract:

Field	Description	Example
name	Parameter name (original case)	userId, options
type	Full type including generics	string, UserOptions<T>
optional	Whether parameter is optional	true, false
default	Default value if any	{}, null, 10

TypeScript Examples

// Required parameter
function getUser(userId: string) { }
// → { name: "userId", type: "string", optional: false }

// Optional parameter
function getUser(userId: string, includeDeleted?: boolean) { }
// → { name: "includeDeleted", type: "boolean", optional: true }

// Default parameter
function getUsers(limit: number = 10) { }
// → { name: "limit", type: "number", optional: true, default: "10" }

// Generic parameter
function transform<T>(input: T[]): T { }
// → { name: "input", type: "T[]", optional: false }

// Object destructuring
function create({ name, age }: UserInput) { }
// → { name: "{ name, age }", type: "UserInput", optional: false }

// Rest parameters
function concat(...items: string[]) { }
// → { name: "...items", type: "string[]", optional: false }

Python Examples

# Required parameter
def get_user(user_id: str) -> User:
# → { name: "user_id", type: "str", optional: false }

# Optional parameter (with default)
def get_users(limit: int = 10) -> List[User]:
# → { name: "limit", type: "int", optional: true, default: "10" }

# Optional type hint
def find_user(user_id: Optional[str]) -> Optional[User]:
# → { name: "user_id", type: "Optional[str]", optional: false }

# *args and **kwargs
def call_api(*args, **kwargs):
# → { name: "*args", type: "Any", optional: true }
# → { name: "**kwargs", type: "Any", optional: true }

---

Return Type Analysis

TypeScript Return Types

// Simple return
function getName(): string { }
// → return_type: "string"

// Promise return (async)
async function getUser(): Promise<User> { }
// → return_type: "Promise<User>", async: true

// Void return
function logMessage(msg: string): void { }
// → return_type: "void"

// Union return
function find(): User | null { }
// → return_type: "User | null"

// Generic return
function first<T>(arr: T[]): T | undefined { }
// → return_type: "T | undefined"

// No explicit return (inferred)
function calculate() { return 42; }
// → return_type: "number" (inferred)

Python Return Types

# Simple return
def get_name() -> str:
# → return_type: "str"

# Optional return
def find_user() -> Optional[User]:
# → return_type: "Optional[User]"

# Async return
async def get_user() -> User:
# → return_type: "User", async: true

# No return type (None)
def log_message(msg: str) -> None:
# → return_type: "None"

---

Async Detection

Patterns to Detect

Language	Pattern	Example
TypeScript	async keyword	async function fetchData()
TypeScript	Returns Promise<T>	function fetch(): Promise<Data>
Python	async def	async def fetch_data():
Java	Returns CompletableFuture<T>	CompletableFuture<Data> fetchData()

Examples

// Explicit async
async function fetchUser(id: string): Promise<User> { }
// → async: true, return_type: "Promise<User>"

// Returns Promise but not async keyword
function fetchUser(id: string): Promise<User> {
  return fetch(`/users/${id}`).then(r => r.json());
}
// → async: false, return_type: "Promise<User>"

---

Generic Type Parameters

Extracting Generics

// Single generic
function identity<T>(value: T): T { }
// → generic_params: ["T"]

// Multiple generics
function map<T, U>(arr: T[], fn: (item: T) => U): U[] { }
// → generic_params: ["T", "U"]

// Constrained generic
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] { }
// → generic_params: ["T", "K extends keyof T"]

// Default generic
function createArray<T = string>(length: number): T[] { }
// → generic_params: ["T = string"]

Python Generics

from typing import TypeVar, Generic

T = TypeVar('T')

def identity(value: T) -> T:
    return value
# → generic_params: ["T"]

class Container(Generic[T]):
    def get(self) -> T: ...
# → generic_params: ["T"]

---

Decorator Extraction

TypeScript/JavaScript Decorators

@Injectable()
@Singleton()
class UserService { }
// → decorators: ["@Injectable()", "@Singleton()"]

@Get('/users/:id')
@UseGuards(AuthGuard)
async getUser(@Param('id') id: string) { }
// → decorators: ["@Get('/users/:id')", "@UseGuards(AuthGuard)"]

Python Decorators

@classmethod
def from_dict(cls, data: dict) -> 'User':
# → decorators: ["@classmethod"]

@staticmethod
def validate(data: dict) -> bool:
# → decorators: ["@staticmethod"]

@property
def full_name(self) -> str:
# → decorators: ["@property"]

@app.route('/users/<id>')
@require_auth
def get_user(id: str):
# → decorators: ["@app.route('/users/<id>')", "@require_auth"]

Java Annotations

@Override
public String toString() { }
// → decorators: ["@Override"]

@GetMapping("/users/{id}")
@PreAuthorize("hasRole('USER')")
public User getUser(@PathVariable String id) { }
// → decorators: ["@GetMapping(\"/users/{id}\")", "@PreAuthorize(\"hasRole('USER')\")"]

---

Visibility Modifiers

TypeScript/JavaScript

Modifier	Visibility
public	public
private	private
protected	protected
#field (private field)	private
(no modifier)	public

Python

Pattern	Visibility
_method	internal (convention)
__method	private (name mangling)
(no prefix)	public

Java

Modifier	Visibility
public	public
private	private
protected	protected
(package-private)	internal

---

Complete Signature Example

{
  "signature": {
    "parameters": [
      {
        "name": "userId",
        "type": "string",
        "optional": false
      },
      {
        "name": "options",
        "type": "GetUserOptions",
        "optional": true,
        "default": "{}"
      }
    ],
    "return_type": "Promise<User>",
    "async": true,
    "generic_params": []
  }
}

---

Best Practices

✅ DO:

• Extract full type information including generics
• Note optional parameters and defaults
• Identify async functions correctly
• Preserve exact decorator syntax
• Document visibility modifiers

❌ DON'T:

• Skip type information
• Ignore generic parameters
• Miss async/Promise patterns
• Forget decorators that indicate behavior
• Assume visibility without checking