Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,15 @@ There is **no test suite**. Verify by hand:

- Frontend: `npm run build` and `npm run lint` in `frontend/`.
- Backend: start uvicorn and `GET /api/health`.
- Analyzer or language-plugin changes: run `python -m backend.analyzer` on `sample_project` and `sample_rust_project` before and after, and compare function and edge counts. An unexplained drop in edges is a regression.
- Analyzer or language-plugin changes: run `python -m backend.analyzer` on `sample_project`, `sample_rust_project` and `sample_typescript_project` before and after, and compare function and edge counts. An unexplained drop in edges is a regression.

CI (`.github/workflows/pr-checks.yml`) only runs the frontend build and the backend health check. It does not lint and does not exercise the analyzer, so green CI says little about analysis correctness.

## Things the code won't tell you

- **The server never reads the visitor's filesystem.** The browser reads picked files and POSTs `{root, files: [{path, content}]}` to `/api/analyze`. `analyze_path()` and the disk walk in `analyzer.py` exist for the CLI only.
- **The wire format is a two-sided contract.** Backend `FunctionInfo.to_dict()` (`backend/languages/base.py`) emits camelCase; `frontend/src/types.ts` mirrors it by hand. Change one, change the other.
- **`SKIP_DIRS` is duplicated** in `backend/languages/base.py` and `frontend/src/localFiles.ts`. Keep them in sync.
- **`SKIP_DIRS` is duplicated** in `backend/languages/base.py` and `frontend/src/localFiles.ts`. Keep them in sync. So is the rule that drops `.d.ts` and `*.min.js` (`_is_skipped_file` in `typescript.py`, `SKIP_FILE` in `localFiles.ts`).
- **The theme is applied in two places.** The inline script in `frontend/index.html` sets `data-theme` before first paint, and `frontend/src/theme.ts` owns it afterwards. They share the storage key and the resolution rules; keep them in sync. Colors belong in the tokens at the top of `index.css`, never as literals (the function card header and the language badge text are the deliberately theme-independent surfaces).
- **Paths must be relative to the picked folder's contents**, with the folder's own name stripped (`localFiles.ts`). Module-name derivation and import resolution in the plugins depend on it.
- **Vocabulary lives in `CONTEXT.md`; use its terms.** The code hasn't caught up on two of them: **File mode** is still `"folder"` in the code (`OrgMode`, `FolderFrame`, `layoutFolderGraph`), and **Trace up / Trace down** is still `showFlow`. Don't rename these as a drive-by; use the glossary term in prose and the code name in code.
Expand Down
5 changes: 4 additions & 1 deletion CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,11 @@ _Avoid_: Link, dependency
The function activated automatically when a project loads: the project's top-level `main`, if it has one.
_Avoid_: Start function, root function

**Language**:
What a source file is written in, as shown by its badge, its Explorer icon and its syntax highlighting. A file has exactly one Language.

**Language plugin**:
The support for one programming language: the piece that knows how to read that language's functions and their calls.
The support for one programming language, or for a family of closely related ones whose files import each other (TypeScript and JavaScript share one): the piece that knows how to read those languages' functions and their calls. One plugin may read several Languages; each file keeps its own.
_Avoid_: Parser

### Roots
Expand Down
8 changes: 6 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ The goal is to make the flow of a codebase visible instead of jumping between fi
| --- | --- |
| Python | `.py` |
| Rust | `.rs` |
| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` |

More languages can be added without touching the frontend - see [Backend](#backend) below.

Expand All @@ -43,7 +45,7 @@ npm install
npm run dev
```

Open http://localhost:5173 and load a folder or file from the sidebar. Try `sample_project` (Python) or `sample_rust_project` (Rust) for a quick demo.
Open http://localhost:5173 and load a folder or file from the sidebar. Try `sample_project` (Python), `sample_rust_project` (Rust) or `sample_typescript_project` (TypeScript and JavaScript) for a quick demo.

## Codebase

Expand All @@ -52,6 +54,7 @@ backend/ FastAPI + a per-language plugin architecture, static analysi
frontend/src/ React 19 + React Flow + Zustand, the UI
sample_project/ Python demo fixture used for manual testing
sample_rust_project/ Rust demo fixture used for manual testing
sample_typescript_project/ TypeScript + JavaScript demo fixture used for manual testing
```

### Backend
Expand All @@ -60,6 +63,7 @@ sample_rust_project/ Rust demo fixture used for manual testing
- `languages/`: one module per language, each implementing the same `LanguagePlugin` contract (`languages/base.py`) - parse every file, extract each function's signature/docstring/source lines, and resolve which loaded functions it calls (direct calls, `module.func()`, `self.method()`, constructors/associated functions). Only calls between functions that were actually loaded get resolved. Adding a language means adding one new module here and registering it in `languages/__init__.py`; nothing else changes.
- `python.py`: parses with the stdlib `ast`.
- `rust.py`: parses with `tree-sitter` + `tree-sitter-rust` (functions, `impl` methods, `use`-based and bare-path module resolution). Calls made inside a macro invocation (`println!`, `format!`, ...) aren't visible to it - macro arguments are an opaque token stream, not parsed expressions.
- `typescript.py`: one plugin for TypeScript and JavaScript, parsed with `tree-sitter` + `tree-sitter-typescript` (the `typescript` grammar for `.ts`, `.tsx` for everything else). It stamps each file with its own language, so a `.ts` file and a `.js` file get their own badge but can call each other. Reads ESM and basic CommonJS imports, resolves relative specifiers and (by unique path suffix) aliases, and ignores `.d.ts` and minified files. There's no separate "JS mode": a missing annotation is just a missing annotation. Its docstring lists exactly what it resolves and what it can't (JSX elements, inheritance, dynamic calls, ...).
- `main.py`: the FastAPI app. `GET /api/browse` powers the server-side folder picker, `POST /api/analyze` runs the analyzer and returns the graph as JSON. Also serves the built frontend in production.

### Frontend
Expand All @@ -72,7 +76,7 @@ sample_rust_project/ Rust demo fixture used for manual testing
- `components/FolderFrame.tsx`: the folder style group frame used in folder mode.
- `components/Sidebar.tsx`, `FileTree.tsx`, `SearchBar.tsx`, `PathBrowser.tsx`: import controls, a nested directory tree, search, and the server-side folder browser.
- `components/LanguageIcon.tsx`: the small per-file language badge shown in the Explorer.
- `languages.ts`: the frontend's mirror of the backend's language registry - id, label, extensions, icon color per language. Adding a language to the backend also means adding one entry here.
- `languages.ts`: the frontend's mirror of the backend's language registry - id, label, extensions, icon color per language, plus two optional settings (`prism`, a highlighting grammar not named like the id; `unannotatedReturn`, what a card shows when a return type is missing). Adding a language to the backend also means adding one entry here.
- `api.ts`, `types.ts`, `colors.ts`: fetch wrapper, wire format types, and per file color hashing.
- `theme.ts`, `components/ThemeToggle.tsx`: the theme preference (System, Light or Dark), the System theme tracking, and the topbar toggle. The resolved theme is set as `data-theme` on `<html>`, and every color in `index.css` is a token that the Light theme overrides.

Expand Down
6 changes: 4 additions & 2 deletions backend/analyzer.py
Original file line number Diff line number Diff line change
Expand Up @@ -51,11 +51,13 @@ def analyze_sources(sources: dict[str, str], root: str = "") -> dict:
if not lang_sources:
continue
result = lang.analyze(lang_sources)
# A plugin that reads several languages stamps each file/function itself;
# otherwise everything it returned is in the plugin's own language.
for file_entry in result["files"]:
file_entry["language"] = lang.id
file_entry.setdefault("language", lang.id)
files.append(file_entry)
for func_id, func in result["functions"].items():
func["language"] = lang.id
func.setdefault("language", lang.id)
functions[func_id] = func
edges.extend(result["edges"])

Expand Down
3 changes: 2 additions & 1 deletion backend/languages/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,9 @@
from .base import SKIP_DIRS, LanguagePlugin
from .python import PythonLanguage
from .rust import RustLanguage
from .typescript import TypeScriptLanguage

LANGUAGES: list[LanguagePlugin] = [PythonLanguage(), RustLanguage()]
LANGUAGES: list[LanguagePlugin] = [PythonLanguage(), RustLanguage(), TypeScriptLanguage()]

EXTENSION_TO_LANGUAGE: dict[str, LanguagePlugin] = {ext: lang for lang in LANGUAGES for ext in lang.extensions}

Expand Down
8 changes: 6 additions & 2 deletions backend/languages/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

# Directories skipped while walking a disk tree, shared across all languages
# (build/dependency/vcs dirs a source scan should never descend into).
SKIP_DIRS = {"__pycache__", "node_modules", ".git", ".venv", "venv", ".tox", ".mypy_cache", "target"}
SKIP_DIRS = {"__pycache__", "node_modules", ".git", ".venv", "venv", ".tox", ".mypy_cache", "target", "dist", "build"}


@dataclass
Expand Down Expand Up @@ -55,7 +55,7 @@ def to_dict(self) -> dict:
class LanguagePlugin(ABC):
"""One entry in the language registry (see languages/__init__.py)."""

id: str # "python", "rust" - also stamped onto each file/function in the response
id: str # "python", "rust" - stamped onto each file/function unless the plugin sets its own
label: str # "Python", "Rust"
extensions: frozenset[str] # {".py"}, {".rs"} - dot-prefixed, lowercase

Expand All @@ -66,4 +66,8 @@ def analyze(self, sources: dict[str, str]) -> dict:
Returns {"files": [...], "functions": {...}, "edges": [...]} - the
same shape the top-level analyzer.py dispatcher returns, scoped to
just this language's files.

A plugin that reads a family of related languages (TypeScript and
JavaScript) sets "language" on each file and function entry itself;
the dispatcher only fills it in, with `id`, where it is missing.
"""
Loading
Loading