How Jev scores — Supercov docs

A quality score is not a verdict handed down by a model. It is arithmetic over twelve answers, and you can read every answer and check it against the file.

Judgments come from Jev, which answers typed questions instead of writing prose. Supercov asks the questions, and does the arithmetic itself.

One question at a time

Each of the twelve properties is a single yes-or-no question about one file, and the answer comes back as a number between 0 and 1. Supercov asks all twelve about the same file in one request, so the model reads the file once.

A property counts as present at 0.60 and above. Below that it is recorded but not reported as a finding.

The twelve properties

Property	What it asks
`god_class`	Does one type hold responsibilities that belong apart?
`long_method`	Does a method do too much to read in one pass?
`deep_nesting`	Does some method nest control flow three or more levels deep?
`complex_conditional`	Must the reader reconstruct an unnamed multi-part condition?
`long_parameter_list`	Does a method take many parameters, some of which belong together?
`duplicated_logic`	Is the same rule written out more than once?
`primitive_obsession`	Are domain concepts carried as primitives or untyped maps?
`dead_code`	Is there code nothing can reach or use?
`feature_envy`	Does a method work mostly on another object’s data?
`temporary_field`	Is a field set only for part of an object’s life?
`message_chains`	Does the code walk long chains to reach what it needs?
`magic_values`	Do unexplained literals appear in the logic?

They come from the refactoring literature, not from a house style. Each one names something a careful reviewer would also name.

Reading one file

npx supercov quality file src/session.js

src/session.js  quality fair (5.8/10)

  yes  0.95  deep_nesting
            Some method nests control flow three or more levels deep.
  yes  0.85  complex_conditional
            An unnamed multi-part condition must be reconstructed by the reader.
  yes  0.76  long_parameter_list
            A method takes many parameters, some of which belong together.
  yes  0.68  magic_values
            Unexplained literals appear in the logic.
  yes  0.66  primitive_obsession
            Domain concepts are carried as primitives, untyped maps, or untyped escape hatches.
   no  0.44  god_class
   no  0.27  long_method
   no  0.14  duplicated_logic
   no  0.12  feature_envy
   no  0.10  dead_code
   no  0.05  temporary_field
   no  0.04  message_chains

Every line is checkable. Open the file, look for three levels of nesting, and decide for yourself whether 0.95 is right.

From answers to a score

The file’s score is the mean of the twelve answers, inverted and put on a ten point scale, so a file nothing fired on scores near ten. A directory or a repository is the same calculation over its files, weighted by size, so a large file counts for more than a one-line module.

Score	Band
8.0 and above	`good`
5.0 to 7.9	`fair`
below 5.0	`weak`

How much to read into a number

Repeating the same request moves a single check by about 0.01, so a score is steady. It also tracks file size closely: long files score worse, which is part of what the properties are measuring, and means a gap of a few tenths between two files is not a ranking you should act on.

Use the band, and use the named properties. “This file is weak, and what fired is deep_nesting at 0.95” is something you can act on. “This file scores 0.3 lower than that one” is not.

What it costs

Supercov prints an estimate before it calls anything:

[supercov] quality: 22 requests, about 77773 input tokens ($0.0033) if none is cached

You pay for the source the model reads, and nothing for what it writes. A repository of a couple of hundred files costs a couple of cents. Each run saves a snapshot, so reading a result again needs no key and no network.

What it does not do

It does not run your code, so it cannot tell you whether anything works. It does not replace a linter or a type checker, which prove things it only judges. And it is not a review: it answers twelve specific questions well, and says nothing about the bug you are actually looking for.