AI code legibility measures whether a codebase is legible to a language model: whether the code carries machine-checkable type information and whether files fit comfortably in a model's working context. The same properties that help a human navigate an unfamiliar codebase help a model — but for models, oversized files are a hard constraint rather than an annoyance.
- Category: AI Readiness (15% within category)
- Weight in overall index: 0% — part of the independent AI Readiness badge
- Metric key:
ai_code_legibility nullfor repositories with no detectable source files — docs-only projects are not penalized
How the value is computed
| Component | Weight | Criteria |
|---|---|---|
| Type-checkable code | 45 | statically typed language → 45 pts; dynamically typed with a type-check configuration → 27; neither → 0 |
| Manageable file sizes | 55 | (1 − oversized / total) × 55, where a source file over ~60 KB (~1,500 lines) counts as oversized; vendored and generated paths are excluded |
Why these two signals
- Types are compressed documentation. A typed signature tells a model what a function accepts and returns without reading its body — and a type-checker turns the model's misunderstandings into immediate, mechanical errors instead of latent bugs. Partial credit for dynamically typed projects with a checker (mypy, pyright, tsconfig) reflects that gradual typing captures much of the benefit.
- File size distribution determines whether a model can hold a unit of code in context whole. A codebase of focused modules can be read piecewise; a 5,000-line file forces truncation, and truncation is where agent errors concentrate.
Vendored and generated code is excluded so that a committed vendor/ tree or generated bindings do not distort the measurement.
Reading the result
- The metric reads structure, not style — naming, comments, and architecture are not graded (see the honesty rules in AI Readiness).
- The file-size component is proportional: one oversized file among fifty costs little; a codebase of monoliths reads accordingly.
Improving the value
- Adopt a type checker; in dynamic languages, even a permissive initial configuration earns the partial credit and creates the ratchet.
- Split files approaching ~1,500 lines along their natural seams.
- Keep generated and vendored code in conventionally named paths so it is excluded from measurement.
Related: AI verify loop · AI interfaces