AI Codebase Understanding Assistant — Sleep Journal

Overview

This project implements a lightweight AI-assisted developer tool designed to help engineers quickly understand an unfamiliar iOS codebase.

The tool analyzes the provided Sleep Journal Swift project, which intentionally contains imperfect patterns, potential bugs, and architectural inconsistencies similar to those found in real-world codebases.

Instead of refactoring the application, the goal is to accelerate codebase understanding by automatically generating structured insights about:

• Architecture and key components
• Potential bugs and design risks
• Engineering questions a new developer should ask
• Limitations and uncertainties in the analysis

The output is a machine-readable JSON report that summarizes the most important insights about the repository.

---

Quick Start (Fastest Way)

Run the tool in offline mode (no API key required):

python main.py --repo "/path/to/Sleep-Journal-Candidate" --out report.offline.json --offline

Example:

python main.py --repo "/Users/xxx/Sleep-Journal-Candidate" --out report.offline.json --offline

This generates a structured analysis report without requiring any external services.

---

What This Tool Does

Given a repository path, the tool performs the following steps:

1. Repository Scan

The analyzer recursively scans the repository and collects all .swift files.

2. Per-file Analysis

Each Swift file is analyzed to extract:

• File responsibility
• Key symbols (classes / structs / functions)
• Dependencies
• Potential risks or design smells
• Engineering questions a new developer should ask

Two analysis modes are available:

Mode	Description
Online Mode	Uses an LLM for deeper semantic analysis
Offline Mode	Uses static heuristics (regex-based) to detect common issues

3. Structured Aggregation

The individual file analyses are aggregated into a single structured report containing:

• High-level codebase summary
• Architecture overview
• Key engineering findings
• Suggested engineering questions
• Known limitations of the analysis

---

Output

The tool generates a machine-readable JSON report.

Example structure:

{
  "summary": "...",

  "architecture_overview": {
    "ui_framework": "...",
    "pattern_guess": "...",
    "key_components": [...],
    "data_flow_guess": "...",
    "external_services": [...]
  },

  "findings": [
    {
      "type": "...",
      "location": {...},
      "explanation": "...",
      "confidence": "high | medium | low"
    }
  ],

  "questions": [...],

  "limitations": [...]
}

Each finding contains:

• type — bug, architecture issue, smell, test gap, etc.
• location — file, component, and optional line range
• explanation — engineering reasoning
• confidence — communicates analysis certainty

---

How to Run

1. Create Environment

conda create -n sleep-ai python=3.12 -y
conda activate sleep-ai

Install dependencies:

pip install -r requirements.txt

---

Running the Analyzer

Option 1 — Offline Mode (Recommended)

No API key required.

Uses lightweight static heuristics to detect common issues such as:

• try! crash paths
• fatalError() usage
• force unwraps (!)
• singleton patterns
• UserDefaults persistence risks
• hardcoded UI strings
• missing tests

Run:

python main.py --repo "/path/to/Sleep-Journal-Candidate" --out report.offline.json --offline

Example:

python main.py --repo "/Users/xxx/Sleep-Journal-Candidate" --out report.offline.json --offline

---

Option 2 — Online Mode (LLM Analysis)

For deeper semantic analysis, configure an OpenAI API key.

Create a .env file:

OPENAI_API_KEY=your_api_key_here
OPENAI_MODEL=gpt-4o-mini

Then run:

python main.py --repo "/path/to/Sleep-Journal-Candidate" --out report.json

---

AI Tools and Models Used

Online mode uses:

• OpenAI Chat API
• GPT-4o-mini

Structured outputs are enforced using JSON Schema, ensuring deterministic, machine-readable responses.

This prevents issues such as:

• malformed JSON
• inconsistent formats
• extra explanatory text

---

Design Decisions

Multi-file Analysis

Each Swift file is analyzed independently before aggregation.

Advantages:

• scalable for larger repositories
• modular reasoning per component
• better architecture synthesis

---

Structured LLM Outputs

The tool enforces JSON schema responses to ensure predictable and reliable parsing.

This improves robustness compared to free-form LLM responses.

---

Confidence Scoring

Each finding includes a confidence score:

Confidence	Meaning
High	Strong evidence in code
Medium	Likely issue but limited context
Low	Heuristic match or uncertainty

This avoids overclaiming and communicates analysis reliability.

---

Tradeoffs

Per-file vs Global Analysis

Per-file analysis improves scalability but may miss:

• cross-view navigation flows
• complex lifecycle interactions
• deep state propagation

These are partially mitigated during aggregation.

---

Heuristic Limitations (Offline Mode)

Offline mode uses regex-based heuristics, which may:

• miss subtle semantic issues
• produce occasional false positives

However, it ensures the tool can run without external dependencies.

---

Approximate Line Numbers

Line numbers are estimated based on pattern matching and may not always correspond to exact AST nodes.

---

Known Limitations

1. No compilation or runtime verification

The analyzer does not build or execute the iOS project.

2. No Swift AST parsing

Semantic checks such as:

• unreachable code
• unused variables
• strict type guarantees

are outside the scope of this prototype.

3. LLM uncertainty

Online analysis may still produce occasional false positives or missed issues.

4. Context window limits

Very large files may be chunked before analysis.

---

Future Improvements

Possible extensions include:

• Swift AST parsing
• dependency graph visualization
• architecture diagrams
• code complexity metrics
• integration with static analysis tools
• IDE plugins

---

Example Output

Example reports included in this repository:

report.offline.json
report.json

• report.offline.json — generated using heuristic analysis
• report.json — generated using LLM analysis

---

Conclusion

This project demonstrates how LLM-assisted tooling can accelerate developer onboarding and codebase understanding by transforming raw source code into structured engineering insights.

It provides a practical example of combining:

• static heuristics
• structured LLM outputs
• repository-level reasoning

to build lightweight AI developer tools.

---