Documentation menu
Documentation
Little Owl analyses a project on disk and reports on its structure. It needs no configuration to be useful, and no service to talk to.
Start here
Reference
Automation
The mental model
Three concepts carry everything else. If you understand these, the rest of the documentation is reference material you can read when you need it.
- Baseline. A recorded snapshot of what healthy means for this project — the scores, the counts behind them, and the findings that existed at the time. It only moves when you move it.
- Scope. What a change was supposed to touch. Anything outside it gets reported, which is the guardrail for “I asked for a fix to orders and it also rewrote authentication”.
- Drift. The distance between now and the baseline, expressed both as score movement and as the concrete counts that caused it.
Language support
TypeScript and JavaScript are parsed into a full syntax tree. Python and Go are analysed line by line — genuinely supported, and genuinely shallower. Everything that comes from the import graph or from git works the same in all four.
| Capability | TS | JS | Py | Go |
|---|---|---|---|---|
| Dependency graphGo resolves at package level | supported | supported | supported | supported |
| Circular dependencies | supported | supported | supported | supported |
| Layers and boundariesDriven by directories, so language-agnostic | supported | supported | supported | supported |
| File and function size | supported | supported | supported | supported |
| Cyclomatic complexityKeyword-counted outside TS/JS | supported | supported | supported | supported |
| Duplicate blocksTextual, so it works anywhere | supported | supported | supported | supported |
| Impact and reverse deps | supported | supported | supported | supported |
| Code archaeologyReads git, not code | supported | supported | supported | supported |
| Project map | supported | supported | supported | supported |
| Dead codeConfidence is capped below high for Python and Go | supported | supported | supported | supported |
| Test gapsRecognises test_*.py and *_test.go | supported | supported | supported | supported |
| React component budgets | supported | supported | not supported | not supported |
| Type-safety rulesNeeds types to exist | supported | not supported | not supported | not supported |
| Dependency hygieneReads package.json only | supported | supported | not supported | not supported |
| Structural pattern rulesGo exports are functions only | supported | supported | supported | not supported |
TypeScript
Full AST.ts .tsx .mts .cts
TypeScript compiler API — full syntax tree
Imports, exports, dynamic imports, path aliases, functions, components, cyclomatic complexity, nesting, `any`, assertions and suppressions.
Rules only this language gets
- type-safety/explicit-any
- type-safety/suppression
- type-safety/unsafe-assertion
- type-safety/js-in-ts-project
- next/server-import-in-client
- react/effect-dependency-risk
JavaScript
Full AST.js .jsx .mjs .cjs
TypeScript compiler API — full syntax tree
Everything TypeScript gets, minus the type-safety rules that need types to exist. JSX, CommonJS `require` and ESM are all understood.
Rules only this language gets
- next/server-import-in-client
- react/effect-dependency-risk
Python
Shallow.py .pyi
Line and indentation based
Imports and the dependency graph, relative and absolute module resolution, function boundaries by indentation, complexity, module sizes, and three known smells.
Limits: Not a full parse. Re-exports through `__init__.py` are not followed, so a module reached only through a package export can look unreferenced. Decorators, metaclasses and dynamic attribute access are invisible. It will not replace Ruff.
Rules only this language gets
- python/bare-except
- python/mutable-default
- python/global-state
Go
Shallow.go
Line and brace based
Package clauses, grouped and single imports, module-relative resolution through go.mod, package-level cycles, function boundaries by brace balance, and oversized packages.
Limits: Exports are detected from capitalised functions only, so exported types, constants and variables are invisible to the dead-code and pattern rules. Build tags and generated code are not special-cased. It will not replace golangci-lint.
Rules only this language gets
- go/ignored-error
- go/large-package
What it writes to your project
Little Owl never modifies your source. It writes one directory, .little-owl/, containing your configuration and baseline — which belong in version control — plus a parse cache and a local review log, which do not. It adds those two to a .gitignore inside that directory the first time it writes anything, so the cache cannot end up in a pull request.