Codebase Health Methodology, version 1.0

This document explains how a codebase health score is computed and why each rule exists. The YAML files in this folder are the source of truth; section 6 is generated from them. If this document and the YAML disagree, the YAML is correct.

FileContents
methodology.yamlAggregation, bands, execution rules, delta rules, regression flags
scope.yamlWhich files count and how lines are counted
dimensions/*.yamlThe 30 parameters: weights, anchors, measurement, rationale, sources
presets/*.yamlDefault import rules for Next.js, Express, Django, FastAPI and generic projects

1. Purpose

Health is how safely and cheaply someone with no memory of this codebase, whether a contractor or an agent, can make a correct change.

The methodology is built for three uses:

  1. Audits. A run gives a baseline score, six dimension scores and the 30 parameter values behind them.
  2. Before and after. A second run after the work shows what the fixes changed, parameter by parameter.
  3. Sprint-loop gate. Every automated change is scored against its base commit. Regressions are flagged and never block.

It covers TypeScript, JavaScript and Python. Every parameter is computed from the repository by a tool. There are no surveys, no manual judgements and no AI grading. One parameter (6.3, feedback loop time) depends on wall-clock time and can vary slightly between identical runs; every other parameter gives the same result for the same commit, tool versions and as-of date.

2. How a score is computed

Parameter score

Each parameter has a raw value measured from the repository, such as "62% line coverage" or "3.1 escape hatches per 1,000 lines". A fixed rubric turns the raw value into a score from 0 to 100.

Most rubrics are piecewise-linear: 3 or 4 anchors, each with a raw value, a score and a written meaning. Between two anchors the score is interpolated linearly. Below the first anchor and above the last, the score is clamped. Yes/no facts and configuration choices use levels instead, where each named level has a fixed score.

Example, 1.2 line coverage at 52%:

RawScore
40%50
60%75

52% is 12/20 of the way from 40% to 60%, so the score is 50 + 0.6 × 25 = 65.

Anchors are fixed. They do not depend on other repositories, so a score means the same thing in every audit and every year until the methodology version changes.

Dimension score

A dimension score is the weighted mean of its parameter scores. Weights within each dimension add up to 100.

Example, D1 Safety net:

ParameterRawScoreWeightContribution
1.1 Suite pass rate97%7020%14.0
1.2 Line coverage52%6525%16.3
1.3 Branch coverage38%6015%9.0
1.4 Modules with tests55%62.525%15.6
1.5 Tests that assert something92%7015%10.5
D165

Not applicable

A parameter can be not applicable only when its precondition is a design choice the methodology does not score. In v1.0 there are two such cases:

The weight of a not-applicable parameter is spread over the other parameters in the same dimension, in proportion to their weights. With 3.5 not applicable, D3's weights become 17.6 / 35.3 / 29.4 / 17.6.

Missing tests, a failed install or a failed test run are never "not applicable". They score 0.

Health score

health = min( mean(D1..D6), min(D1..D6) + 30 )

The six dimensions have equal weight. The cap means one very weak dimension pulls the headline down, because a codebase with no tests is not made safe by clean dependencies.

ExampleD1D2D3D4D5D6MeanWeakest + 30Health
Balanced72655881906071.08871 Stable
No tests5808080808067.53535 Vibe-coded

Bands

HealthBandMeaning
0–39Vibe-codedChanges break things without anyone noticing. Nobody, human or agent, can work here safely.
40–59FragileIt works, but every change is a gamble.
60–79StableChanges are safe with care and review.
80–100Agent-readyAn agent with no memory of the codebase can make a correct change and verify it alone.

Because of the cap, Agent-ready requires every dimension to score at least 49.5.

Precision

Scores are stored at full precision in run.json. The report shows health and dimension scores as integers (rounded half up) and the health delta with one decimal. The band comes from the displayed health score.

3. Layers and execution

Every run has two layers.

LayerWhat it doesParameters
StaticReads tracked files, parses ASTs, builds import graphs. Never runs repository code.23
ExecutionInstalls dependencies, then runs the build, the typechecker, a pinned lint ruleset and the test suite with coverage.7 (1.1, 1.2, 1.3, 2.1, 2.5, 6.1, 6.3)

Both layers run on every scan. The execution layer runs in a pinned Docker image, health:1.0, with 4 CPUs and 8 GB of memory. The same image runs the client's code, so nothing from the repository runs on the host.

There are two kinds of failure:

FailureCauseResult
Repository failureInstall, build, typecheck or tests fail or time out because of the repositoryEvery parameter that needs that step scores 0. An install that fails in one install root zeroes only the units beneath that root; the other roots are still measured. The run is valid.
Tool errorThe scanner itself fails, for example a crash or coverage data missing after a test run that produced resultsThe run is invalid and produces no score.

4. Scope

Full rules are in scope.yaml.

Monorepos and mixed languages

A repository always gets one headline score.

The report breaks every dimension down per package and per language.

5. Comparing runs and regression flags

The as-of date

Two parameters depend on outside data that changes over time: 5.1 (known vulnerabilities) and 5.2 (dependencies a major version behind). Every run has an as-of date. Advisories published on or before that date count, and "latest version" means the latest version published on or before that date.

Without this, a repository's score would drop when a new advisory is published, even if nobody changed the code.

Delta rule

health diff before.json after.json compares two runs only when all five conditions match. Otherwise it refuses and names the conditions that differ.

  1. Layers. Both runs attempted the same layers.
  2. Tool versions. Both runs used the same image digest.
  3. Methodology version. Both runs used the same methodology version.
  4. As-of date. Both runs were scored at the same as-of date. In a contract, this is the baseline's as-of date. The report also shows the newer run's score as of today.
  5. Ignore set. Both runs used the same .healthignore and .gitleaksignore contents.

run.json stores raw values and the resolved dependency list, so the newer run can be rescored at the baseline's as-of date without rescanning.

Sprint-loop regression flags

Each change is scored against its base commit, at the same as-of date. Base commit runs are cached by tree hash, methodology version and as-of date.

A change is flagged when any dimension drops by 3.0 points or more (unrounded), or when the band drops. A flagged pull request gets the health-regression label. Flags never block a merge.

Telegram summary format:

Health 62 Stable (+1.4) · Safety net +6 · Complexity −1 · ⚠ none

6. The six dimensions

#DimensionQuestion
D1Safety netWill a change break something without anyone noticing?
D2Type & static rigorDoes the code tell you what it expects before you run it?
D3Architecture & boundariesCan you change one part without reading the rest?
D4Complexity & maintainabilityHow much does someone have to read to make one change correctly?
D5Dependency & security hygieneIs the code built on parts that are known, current and safe?
D6Operability & feedback loopCan someone new set it up, check a change and know they are done?

D1. Safety net

Question. Will a change break something without anyone noticing?

Why it matters for agents. An agent cannot remember how the system is supposed to behave. The test suite is the only record of that behaviour it can check its change against.

#ParameterLayerWeight
1.1Suite pass rateExecution20%
1.2Line coverageExecution25%
1.3Branch coverageExecution15%
1.4Modules with testsStatic25%
1.5Tests that assert somethingStatic15%

1.1 Suite pass rate

Weight 20%. Execution layer. Scores 0 if any of these steps fail: install, test run. Pooled as a ratio across languages and packages.

Raw value (percent). passed / (passed + failed + errored) test cases. Skipped and expected-failure tests are excluded from both numerator and denominator. A test file that fails to load or collect counts as one failed test case.

RawScoreMeaning
800The suite is red. Nobody can use it to check a change.
9550Mostly green, with known failures people have learned to ignore.
100100Green. A new failure means the change broke something.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 0.

How it is measured.

Why. A suite with known failures stops working as a check: a new failure looks the same as the old ones. The curve is steep on purpose. 95% of a 200-test suite is 10 failing tests, which is already enough for people to stop reading the output.

1.2 Line coverage

Weight 25%. Execution layer. Scores 0 if any of these steps fail: install, test run. Pooled as a ratio across languages and packages.

Raw value (percent). Covered lines / coverable lines across all logic files, including logic files no test loads. A file no test loads counts as 0% covered. For TypeScript and JavaScript the coverable lines are health's code lines (lines with at least one token). A line counts as covered when the innermost statement or function containing it ran.

RawScoreMeaning
100No safety net.
4050Happy paths only.
6075Acceptable.
80100Well covered. No extra credit above this.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 0.

How it is measured.

Why. Coverage shows which code no test executes. It does not show that the executed code is checked, which is why 1.5 exists. The 60% anchor matches Google's "acceptable" level. The 100 anchor is 80%, which is the coverage SonarQube's default quality gate requires on new code and sits between Google's "commendable" (75%) and "exemplary" (90%). Above 80% the methodology gives no extra credit, because the remaining code is often glue that costs more to test than it returns.

Sources.

1.3 Branch coverage

Weight 15%. Execution layer. Scores 0 if any of these steps fail: install, test run. Pooled as a ratio across languages and packages.

Raw value (percent). Covered branches / total branches across all logic files, including files no test loads.

RawScoreMeaning
50Only one path through each decision is ever run.
3050Error and edge paths are mostly untested.
5075Main error paths are tested.
70100Most decisions are tested both ways.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 0.

How it is measured.

Why. Tests written quickly cover the happy path. Line coverage can be high while every error branch is untested. Branch coverage shows that gap. Branch percentages are lower than line percentages on the same code, so the anchors sit about 10 points lower than 1.2's.

1.4 Modules with tests

Weight 25%. Static layer. Pooled as a ratio across languages and packages.

Raw value (percent). Logic files directly imported by at least one test file / all logic files. Imports are followed through barrel files and Python __init__.py re-exports to the file that defines the imported name. Transitive imports do not count.

RawScoreMeaning
100Almost nothing has a test.
4050Some modules have tests; most do not.
7075Most modules have a test.
90100Nearly every module has a test.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 0.

How it is measured.

Why. This is the static counterpart to coverage. It still works when the suite does not run, so a repository with tests that are broken gets partial credit, and "make the existing tests run" shows up as a gain in 1.1 to 1.3. Only direct imports count; otherwise one test that imports the app entry point would mark every file as tested.

1.5 Tests that assert something

Weight 15%. Static layer. Pooled as a ratio across languages and packages.

Raw value (percent). Test cases containing at least one assertion / all test cases. An assertion inside a helper function defined in the same file and called by the test counts (one level deep).

RawScoreMeaning
500Many tests run code without checking anything.
8050A noticeable share of tests check nothing.
9575A few tests check nothing.
100100Every test checks something.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 0.

How it is measured.

Why. A test without an assertion raises coverage and checks nothing. This is the cheapest way to game 1.2 and 1.3, and it is common in generated tests. The anchors are strict because writing a test without an assertion is almost never intentional.

D2. Type & static rigor

Question. Does the code tell you what it expects before you run it?

Why it matters for agents. Type errors and lint findings are the fastest feedback an agent gets. A strict typechecker catches a wrong change in seconds, before any test runs, and the types document what each function accepts and returns.

#ParameterLayerWeight
2.1Typecheck errorsExecution25%
2.2Declared strictnessStatic20%
2.3Escape hatchesStatic20%
2.4Typed public surfaceStatic15%
2.5Baseline lint findingsExecution20%

2.1 Typecheck errors

Weight 25%. Execution layer. Scores 0 if any of these steps fail: install, typecheck run. Pooled as a ratio across languages and packages.

Raw value (errors per 1,000 source lines). Typechecker errors located in in-scope files (logic and test), divided by source lines / 1,000. Errors in excluded files and in dependencies are ignored. Warnings are ignored.

RawScoreMeaning
0100Clean. A new error means the change introduced it.
175A few known errors.
550Errors are routine and people work around them.
200The typechecker is ignored.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Why. The repository's own config is used so the count reflects what its developers see. A config error, or a checker that cannot start, is a repository failure and scores 0. Untyped code is checked with a default config on purpose, so "add types" is visible as a score change.

Sources.

2.2 Declared strictness

Weight 20%. Static layer. Scored per language and package, then combined by logic-line weight.

Raw value (level). The strictness the repository's typechecker configuration declares, read from the config files without running anything.

TypeScript / JavaScript:

LevelScoreMeaning
none0No strict-family flag is enabled, or JavaScript without checkJs.
partial40Some strict-family flags are enabled, or strict is true with one or more strict-family flags turned back off.
strict75strict is true and no strict-family flag is turned off.
strict_plus100strict plus noUncheckedIndexedAccess.

Python:

LevelScoreMeaning
none0No pyright or mypy configuration.
basic40pyright typeCheckingMode basic, or mypy with default settings.
standard75pyright typeCheckingMode standard (pyright's default when a config exists), or mypy with disallow_untyped_defs and check_untyped_defs.
strict100pyright typeCheckingMode strict, or mypy strict = true.

How it is measured.

Why. 2.1 counts errors under whatever config the repository chose. Without 2.2, turning strictness off would raise the score. Strict null checks catch access to null and undefined values, a common runtime error in both languages. noUncheckedIndexedAccess makes array and record lookups return possibly undefined values, which is where strict TypeScript still lets runtime errors through.

Sources.

2.3 Escape hatches

Weight 20%. Static layer. Pooled as a ratio across languages and packages.

Raw value (escape hatches per 1,000 logic lines). Points where code opts out of the typechecker, counted in logic files, divided by logic lines / 1,000. A file-level opt-out counts as 10.

RawScoreMeaning
0100The types are trusted everywhere.
275A few documented exceptions.
550Casts are a common way to make errors go away.
150The types say little about what the code does.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Why. Each escape hatch is a place where the typechecker cannot help the next person. A change that breaks a contract passes the typechecker silently at that point. The typescript-eslint no-unsafe-* rules are not used in 2.5, so the same problem is not counted twice.

2.4 Typed public surface

Weight 15%. Static layer. Pooled as a ratio across languages and packages.

Raw value (percent). Typed slots / all slots on the public surface of logic files. In TypeScript and JavaScript a slot is a parameter. In Python a slot is a parameter or a return type.

RawScoreMeaning
200The public surface is untyped.
5050Half of what callers use is typed.
8075Most of what callers use is typed.
100100Every public function says what it accepts.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Why. The public surface is what the next person calls without reading the body. In TypeScript, inferred return types are reliable, so only parameters are counted. In Python, an unannotated return is Any, so both are counted. Untyped JavaScript and untyped Python score low on purpose.

Sources.

2.5 Baseline lint findings

Weight 20%. Execution layer. Scores 0 if any of these steps fail: install, lint run. Pooled as a ratio across languages and packages.

Raw value (findings per 1,000 source lines). Findings from the methodology's pinned correctness ruleset in in-scope files (logic and test), divided by source lines / 1,000. The repository's own lint config is not used. A file that cannot be parsed counts as one finding.

RawScoreMeaning
0100No known bug patterns.
275A few.
550Bug patterns are common.
200The code has never been linted for correctness.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Why. Each rule in the set catches a real bug pattern, such as an unawaited promise or an unreachable branch. Style rules are excluded, so formatting choices do not affect the score. The ruleset is pinned so every repository is judged by the same rules, and so turning rules off in the repository's own config does not raise the score.

Sources.

D3. Architecture & boundaries

Question. Can you change one part without reading the rest?

Why it matters for agents. An agent works inside a limited context window. Enforced boundaries limit how much of the codebase one change can affect, so the agent only needs to read the module it is changing and that module's public entry points.

#ParameterLayerWeight
3.1Boundaries declared and enforcedStatic15%
3.2Boundary violationsStatic30%
3.3Import cyclesStatic25%
3.4Public-entry disciplineStatic15%
3.5Domain purityStatic15%

Presets. When a repository declares no import rules, the scan uses the preset for the detected framework (presets/*.yaml). When it declares rules (see 3.1), its rules replace the preset. Detection order: nextjs, express, django, fastapi, generic. Each workspace package gets its own preset.

3.1 Boundaries declared and enforced

Weight 15%. Static layer. Scored per language and package, then combined by logic-line weight.

Raw value (level). Whether the repository declares import rules in a supported rules file, and whether CI runs them.

LevelScoreMeaning
none0No import rules are declared.
declared50A rules file declares at least one direction rule, but CI does not run it.
enforced100The rules are declared and CI runs them on pull requests.

How it is measured.

Why. An architecture that exists only in people's heads is not visible to an agent and erodes with each change. A rules file states the architecture in a form a tool can check. Running it in CI is what stops new violations.

Sources.

3.2 Boundary violations

Weight 30%. Static layer. Pooled as a ratio across languages and packages.

Raw value (violations per 1,000 imports). Import edges that break a rule, divided by all internal import edges / 1,000. Rules come from the repository's declared rules file, or from the preset when none is declared. Rules with severity error or warn count; info is ignored. Each violating edge counts once, even when it breaks several rules. Imports from test files are excluded. Type-only imports are included, except where a preset rule says otherwise.

RawScoreMeaning
0100Every import respects the architecture.
275A few known shortcuts.
1050The layers exist in name only in places.
300Anything imports anything.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Why. Each violation is a dependency a reader would not expect from the directory structure. The count is normalized per 1,000 imports so repositories of different sizes are comparable.

Sources.

3.3 Import cycles

Weight 25%. Static layer. Pooled as a ratio across languages and packages.

Raw value (percent). Logic files that belong to an import cycle / all logic files. A cycle is a strongly connected component of two or more files in the graph of module-level static imports. Type-only imports, dynamic imports, imports inside functions and imports under "if TYPE_CHECKING:" are excluded.

RawScoreMeaning
0100The import graph has no cycles.
275One or two small cycles.
550Cycles connect several areas.
150Large parts of the code depend on each other.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Why. Files in a cycle cannot be understood, tested or changed one at a time. Cycles also cause import-order bugs at runtime, especially in Python. Type-only imports are excluded because they have no runtime effect.

Sources.

3.4 Public-entry discipline

Weight 15%. Static layer. Pooled as a ratio across languages and packages.

Raw value (percent). Imports that cross from one module into another and land on that module's public entry / all imports that cross between modules. Modules are defined by the preset (or by the independence or layer contracts in the declared rules). The public entry is index.* in TypeScript and JavaScript, and __init__.py in Python.

RawScoreMeaning
500Other modules reach into internals as often as not.
7550Entry points exist and are often bypassed.
9075Entry points are mostly used.
100100Every cross-module import goes through the entry point.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Not applicable when. The repository has fewer than two modules as defined by the preset or the declared rules. Splitting code into modules is a design choice the methodology does not score.

Why. A public entry point is a small interface the next person can read instead of the whole module. When other modules import internals directly, every internal file becomes part of the interface and cannot be changed safely.

Sources.

3.5 Domain purity

Weight 15%. Static layer. Pooled as a ratio across languages and packages.

Raw value (percent). Files in the domain layer that import a framework, database, network or filesystem package, or an infrastructure directory / all files in the domain layer.

RawScoreMeaning
0100Domain logic is plain code that runs and tests without infrastructure.
575A few domain files touch infrastructure.
1550Domain logic regularly reaches for the database or the network.
400The domain layer is a directory name.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Not applicable when. The repository declares no domain layer. Choosing a layered or domain-driven design is a design choice the methodology does not score.

Why. This is the deterministic part of domain-driven design alignment. Pure domain code can be tested without a database or network and changed without reading infrastructure code. The methodology does not judge whether the domain model is good; it checks that the repository keeps the boundary it declared.

Sources.

D4. Complexity & maintainability

Question. How much does someone have to read to make one change correctly?

Why it matters for agents. Every line an agent reads uses context. Long files, complex functions, duplicated logic and dead code all increase how much it must read, and duplicated logic is where an agent fixes one copy and misses the other.

#ParameterLayerWeight
4.1Complex functionsStatic30%
4.2Lines in large filesStatic20%
4.3DuplicationStatic25%
4.4Unused exports and filesStatic25%

4.1 Complex functions

Weight 30%. Static layer. Pooled as a ratio across languages and packages.

Raw value (percent). Functions with cognitive complexity strictly greater than 15 / all functions in logic files, as enumerated by the tool.

RawScoreMeaning
0100Every function can be read in one pass.
375A few hard functions.
850Hard functions in most areas.
200Logic is concentrated in functions nobody wants to touch.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Why. Cognitive complexity counts nesting and breaks in linear flow, which is closer to how hard a function is to read than cyclomatic complexity. 15 is the default threshold in SonarQube, eslint-plugin-sonarjs and complexipy. Counting the share of functions over the threshold, instead of the mean, keeps many small functions from hiding a few large ones.

Sources.

4.2 Lines in large files

Weight 20%. Static layer. Pooled as a ratio across languages and packages.

Raw value (percent). Logic lines in logic files with more than 500 logic lines / all logic lines.

RawScoreMeaning
0100Every file fits in one read.
1075A few large files.
2550A quarter of the code lives in large files.
500Most of the code lives in files too large to read whole.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Why. A large file has to be read in parts, so changes to it are made with partial context. The threshold of 500 logic lines is more lenient than ESLint's max-lines default (300 physical lines) and stricter than Pylint's max-module-lines default (1,000). The raw value is a share of lines, not of files, so one 5,000-line file weighs more than one 501-line file.

Sources.

4.3 Duplication

Weight 25%. Static layer. Pooled as a ratio across languages and packages.

Raw value (percent). Duplicated lines / all lines in logic files, as reported by jscpd.

RawScoreMeaning
3100Duplication is incidental.
575Some copied blocks.
1050Copy and paste is a common way to add features.
200Large parts of the logic exist in several copies.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Why. A bug fixed in one copy stays in the others. This is a common agent mistake: the agent finds one copy, fixes it, and its tests pass. 3% is the default duplication limit in SonarQube's quality gate.

Sources.

4.4 Unused exports and files

Weight 25%. Static layer. Pooled as a ratio across languages and packages.

Raw value (percent). (Unused exported symbols + exported symbols in unused files) / all exported symbols in logic files. Exported types count. Library entry points (package.json exports and main, Python __all__ of a distributed package) count as used.

RawScoreMeaning
0100Everything exported is used.
375A little dead code.
850Dead code is common.
200A large share of the code is never called.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Why. Dead code costs reading time and looks like a place to make a change. An agent that edits an unused function gets no test failure and no effect. Decorated Python definitions are treated as used because frameworks register them by decorator (routes, fixtures, signals). Methods that override a base class are treated as used for the same reason: frameworks and the standard library call hooks such as do_GET, setUp or emit by name, which vulture cannot see.

Sources.

D5. Dependency & security hygiene

Question. Is the code built on parts that are known, current and safe?

Why it matters for agents. An agent adds dependencies and copies patterns from what it finds. An undeclared dependency, a stale major version or a committed secret gets copied into new code the same way good patterns do.

#ParameterLayerWeight
5.1Known vulnerabilities in production dependenciesStatic30%
5.2Dependencies a major version behindStatic20%
5.3LockfileStatic15%
5.4Secrets in the working treeStatic20%
5.5Dependency declaration errorsStatic15%

As of date. Parameters 5.1 and 5.2 are evaluated at the run's as-of date: advisories published on or before that date count, and the latest version of a package is the latest published on or before that date.

5.1 Known vulnerabilities in production dependencies

Weight 30%. Static layer. Pooled as a ratio across languages and packages.

Raw value (severity points). Sum of severity points over advisories affecting resolved production dependencies (direct and transitive). Critical 10, high 5, moderate 2, low 0.5. Each advisory counts once per package; aliases are deduplicated. Withdrawn advisories are excluded.

RawScoreMeaning
0100No known vulnerabilities.
275One moderate, or a few low.
1050A critical, or several highs.
300Several criticals. Nobody is watching.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Why. Severity points stop one critical advisory from scoring the same as one low one. The count is not normalized by repository size, because a vulnerability's risk does not shrink as the codebase grows. Development-only dependencies are reported separately and not scored.

Sources.

5.2 Dependencies a major version behind

Weight 20%. Static layer. Pooled as a ratio across languages and packages.

Raw value (percent). Direct dependencies (production and development) whose resolved version is at least one major version behind the highest stable, non-yanked version published on or before the as-of date / all direct dependencies. For 0.x versions, a minor version bump counts as major.

RawScoreMeaning
0100Every direct dependency is on its current major.
1075A few dependencies are behind.
2550A quarter of dependencies are behind.
500Upgrades have stopped.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Why. Each major version behind is a migration someone will have to do, and an agent writing code against current documentation will use APIs the installed version does not have. Development dependencies are included because outdated tooling affects every change.

Sources.

5.3 Lockfile

Weight 15%. Static layer. Scored per language and package, then combined by logic-line weight.

Raw value (level). Whether a lockfile exists and matches the manifest.

LevelScoreMeaning
none0No lockfile. Every install can resolve different versions.
out_of_sync40A lockfile exists but does not match the manifest.
in_sync100The lockfile matches the manifest.

How it is measured.

Why. Without a lockfile, two installs of the same commit can produce different code. Results stop being reproducible, including this methodology's results.

Sources.

5.4 Secrets in the working tree

Weight 20%. Static layer. Scored per language and package, then combined by logic-line weight.

Raw value (count). Secrets found by the pinned gitleaks default ruleset in every tracked file at the scanned commit. .healthignore does not apply. .gitleaksignore applies and is part of the ignore set.

RawScoreMeaning
0100No secrets in the code.
10At least one secret is in the code.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Why. One committed secret is enough to cause a breach, so the parameter is binary. Secrets in git history are reported but not scored, because the fix is rotating the key, which cannot be seen in the code.

Sources.

5.5 Dependency declaration errors

Weight 15%. Static layer. Pooled as a ratio across languages and packages.

Raw value (percent). (Declared dependencies that are never imported + imported packages that are not declared) / declared direct dependencies.

RawScoreMeaning
0100The manifest matches the code.
575A few stale or missing entries.
1550The manifest and the code have drifted apart.
300Nobody maintains the manifest.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 100.

How it is measured.

Why. An undeclared import works until the transitive dependency that provides it changes. An unused declaration adds install time and attack surface. Both mislead a reader about what the code depends on.

Sources.

D6. Operability & feedback loop

Question. Can someone new set it up, check a change and know they are done?

Why it matters for agents. An agent needs a command that tells it whether its change is correct, and it needs to find that command without asking. A slow or missing check means the agent stops early or guesses.

#ParameterLayerWeight
6.1Clean install and buildExecution25%
6.2One-command verifyStatic15%
6.3Feedback loop timeExecution10%
6.4CI runs the checks on pull requestsStatic20%
6.5Reproducible environmentStatic15%
6.6Commands documented for agentsStatic15%

Script resolution. Parameters 6.2, 6.4 and 6.6 follow package.json scripts, Makefile targets, justfile recipes, tox and nox sessions, and pyproject.toml script tables up to 3 levels deep. Recognised tools: typecheckers tsc, vue-tsc, pyright, basedpyright, mypy; linters eslint, biome, oxlint, ruff, flake8, pylint; test runners vitest, jest, mocha, node --test, pytest, python -m unittest, tox, nox. The prefixes npx, bunx, pnpm exec, yarn, uv run, poetry run, pdm run and python -m are removed before a command is matched.

6.1 Clean install and build

Weight 25%. Execution layer. Scored per language and package, then combined by logic-line weight.

Raw value (level). Result of a clean install from the lockfile, followed by the build step, in the pinned runner.

LevelScoreMeaning
install_fails0The project does not install from a clean checkout.
build_fails40It installs, but the build fails.
works100It installs and builds from a clean checkout. A project with no build step scores 100 when the install succeeds.

How it is measured.

Why. Everything in the execution layer depends on this step. A project that does not install from a clean checkout depends on someone's machine.

6.2 One-command verify

Weight 15%. Static layer. Scored per language and package, then combined by logic-line weight.

Raw value (count of checks (0-3)). The largest number of the three checks (typecheck, lint, tests) that a single entry point runs: one package.json script, Makefile target, justfile recipe, tox or nox session, or pyproject script.

LevelScoreMeaning
00No single command runs any check.
133One command runs one check.
266One command runs two checks.
3100One command runs typecheck, lint and tests.

How it is measured.

Why. "Run this and it tells you if you are done" is the most useful fact an agent can learn about a repository. Without it, the agent has to find and run each check separately, and often skips one.

6.3 Feedback loop time

Weight 10%. Execution layer. Scores 0 if any of these steps fail: install, typecheck run, lint run, test run. Scored per language and package, then combined by logic-line weight.

Raw value (seconds). Summed wall-clock time of the methodology's own typecheck (2.1), lint (2.5) and test (1.1) runs on the pinned runner.

RawScoreMeaning
60100A full check takes about a minute.
18075A full check takes a few minutes.
60050The ten-minute build.
12000Nobody runs the full check locally.

Scores are interpolated between anchors and clamped outside them. If there is nothing to count, the score is 0.

How it is measured.

Why. A slow check gets run less often, by people and by agents. This is the only parameter whose raw value varies between identical runs, so its weight is low and the runner hardware is fixed.

Sources.

6.4 CI runs the checks on pull requests

Weight 20%. Static layer. Scored per language and package, then combined by logic-line weight.

Raw value (count of checks (0-3)). How many of the three checks (typecheck, lint, tests) CI runs on pull requests or on every push. Checks may be spread across jobs and workflows.

LevelScoreMeaning
00CI runs no checks, or there is no CI.
133CI runs one check.
266CI runs two checks.
3100CI runs typecheck, lint and tests on every pull request.

How it is measured.

Why. Local checks are optional; CI checks are not. CI is what keeps the score from dropping after the audit ends.

Sources.

6.5 Reproducible environment

Weight 15%. Static layer. Scored per language and package, then combined by logic-line weight.

Raw value (score). Mean of two components.

The score is the mean of two components, each 0-100:

How it is measured.

Why. A missing environment variable is a common reason a fresh checkout does not start, and an agent cannot guess the names. Config read from the environment, with the names documented, is the Twelve-Factor approach.

Sources.

6.6 Commands documented for agents

Weight 15%. Static layer. Scored per language and package, then combined by logic-line weight.

Raw value (level). Whether the repository documents how to install, run and check it, and whether the documented commands exist.

LevelScoreMeaning
none0No documented commands.
readme50README documents commands, or an agent instructions file exists but at least one command in it does not resolve.
agent_file100AGENTS.md or CLAUDE.md at the repository root documents commands, and every command in it resolves.

How it is measured.

Why. An agent reads AGENTS.md or CLAUDE.md before anything else. Commands in that file that do not exist send it down the wrong path, which is worse than no file, so they drop the level to README.

Sources.

7. Report-only signals

These appear in the report and never change the score.

SignalWhat it showsWhy it is not scored
HotspotsFiles ranked by churn (commits in the last 12 months) × cognitive complexityThe "fix these first" list. Churn describes how the team works, not the code's state, and would make two runs of the same tree differ.
Secrets in git historySecrets in past commitsThe fix is rotating the key, which the code cannot show.
Development dependency vulnerabilitiesAdvisories in packages reachable only from development dependenciesThey do not ship to production.
Top scaresThe first three of a fixed list of consequences the findings trigger, such as a Supabase service-role key in the tree, secrets in the tree or history, known production advisories, or an install that failsA consequence in plain words, not a measurement. The scan cannot see access rules such as row-level security.
Excluded linesPercentage of lines excluded by .healthignoreMakes exclusions visible to the reader.
Per-package breakdownEvery dimension per workspace package and per languageShows where the pooled score comes from.

8. What a 100 looks like

Concrete descriptions of a repository that scores 100 on every parameter.

TypeScript

Python

A Python project at 100 uses a small set of modern tools. Most of them are configured in pyproject.toml.

Example pyproject.toml:

[project]
name = "billing"
requires-python = ">=3.12"
dependencies = ["fastapi>=0.115", "sqlalchemy>=2.0"]

[dependency-groups]
dev = ["pytest>=8", "pytest-cov>=5", "pyright>=1.1.380", "ruff>=0.6", "import-linter>=2"]

[tool.pyright]
typeCheckingMode = "strict"

[tool.ruff.lint]
select = ["E", "F", "B", "I", "UP"]

[tool.pytest.ini_options]
addopts = "--cov=billing --cov-branch"

[tool.importlinter]
root_package = "billing"

[[tool.importlinter.contracts]]
name = "Layers"
type = "layers"
layers = ["billing.api", "billing.services", "billing.domain"]

Example Makefile target:

check:
	uv run pyright
	uv run ruff check
	uv run pytest

9. Known limits of v1.0

  1. Anchors are not calibrated against a corpus. They come from the cited sources and from judgement. The next step is to run v1.0 on a set of repositories and check that the bands match how those repositories feel to work in. Any anchor change will be a new version.
  2. Test quality is measured only by assertions. A test can assert something trivial. Mutation testing would measure this directly but is too slow for every run, so it is out of v1.0.
  3. Tests that need external services fail. No database, queue or browser is provided. Integration tests that need one count as failed in 1.1, and the code they cover counts as uncovered.
  4. Declared import rules replace the preset. A repository can declare a permissive rules file and avoid the preset's rules. 3.1 still rewards the declaration with 50 or 100.
  5. Domain-driven design is checked only at the boundary. 3.5 checks that domain code does not import infrastructure. It does not judge whether the domain model is good.
  6. Static analysis misses dynamic behaviour. Dependency injection, plugin registration and string-based imports can make used code look unused (4.4) or hide imports (D3).
  7. Security covers known advisories and committed secrets only. There is no static application security testing (SAST).
  8. 6.3 varies between runs. It is the only parameter that does, and it has a weight of 10%.
  9. Other languages are ignored. Files in other languages do not count toward any parameter.

10. Versioning

11. Sources

This methodology is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You may share and adapt it, including commercially, if you credit vibecodedshit.com and indicate any changes.