Spec Generator

chunks = collection.get(
    where={"file_path": file_path},
    include=["documents", "metadatas"]
)
# Sort by chunk_index to reconstruct file order
sorted_chunks = sorted(
    zip(chunks["documents"], chunks["metadatas"]),
    key=lambda x: x[1]["chunk_index"]
)

You are generating a structured specification for a source code file. The code is provided below. Produce a specification in the exact format shown, with no preamble or commentary.

## File
{file_path}

## Source Code
{assembled_chunks}

---

Generate the specification in this exact format:

# {filename} — Specification

## Purpose
[1–2 sentences: what this file does and why it exists in the codebase]

## Key Functions/Classes

### {name}
- **Type:** function | class | method
- **Purpose:** [1 sentence]
- **Parameters:** [list with types, or "None"]
- **Returns:** [return type and description, or "None"]
- **Side Effects:** [any side effects, or "None"]

[Repeat for each significant function/class. Skip trivial helpers unless they are part of the public API.]

## Dependencies

### Internal
[List internal imports — modules from within this repository]

### External
[List external package imports with brief purpose]
- `package_name` — [what it's used for in this file]

## Architectural Patterns
[1–3 bullet points describing design patterns, notable conventions, or architectural decisions visible in this file. Examples: "Uses dependency injection via constructor parameters", "Implements the Repository pattern for data access", "Guards all public methods with input validation"]

## Notes
[Anything unusual, important, or worth flagging: TODOs, known limitations, performance considerations, or coupling to other components. If nothing notable, write "None."]

# handler.py — Specification

## Purpose
Handles JWT token validation and session management for the authentication subsystem. Called by the auth middleware on every protected route.

## Key Functions/Classes

### validate_token
- **Type:** function
- **Purpose:** Validates a JWT token string and returns the decoded payload
- **Parameters:** `token: str`, `secret: str`
- **Returns:** `TokenPayload` dataclass with `user_id`, `expires_at`, `scopes`
- **Side Effects:** None

### AuthManager
- **Type:** class
- **Purpose:** Manages authentication sessions and token lifecycle
- **Parameters:** `config: AuthConfig`, `store: SessionStore`
- **Returns:** N/A
- **Side Effects:** Writes to session store on login/logout

### AuthManager.refresh_session
- **Type:** method
- **Purpose:** Extends an existing session if the refresh token is valid
- **Parameters:** `refresh_token: str`
- **Returns:** `Session` with updated expiry, or raises `SessionExpiredError`
- **Side Effects:** Updates session record in store

## Dependencies

### Internal
- `src.models.user` — `User`, `TokenPayload` dataclasses
- `src.config` — `AuthConfig` settings
- `src.store.sessions` — `SessionStore` interface

### External
- `jwt` — JWT encoding/decoding
- `datetime` — Token expiry calculations
- `hashlib` — Session ID generation

## Architectural Patterns
- Uses constructor injection for `SessionStore`, enabling test doubles
- All public methods validate inputs before processing (fail-fast pattern)
- Token validation is stateless; session management is stateful

## Notes
- TODO on line 67: rate limiting for failed validation attempts is not yet implemented
- The `secret` parameter should be loaded from environment, not passed directly — this is a security consideration for production