supercov 0.0.55 → 1.0.1

package/README.md

@@ -1,10 +1,16 @@
-![Coverage for coding agents and software factories 🌙](https://raw.githubusercontent.com/supercorp-ai/supercov/main/supercov.jpg)
+![Code quality and coverage for coding agents](https://raw.githubusercontent.com/supercorp-ai/supercov/main/supercov.jpg)
 
-**Coverage for coding agents and software factories 🌙**
+**Code quality and coverage for coding agents**
 
-**Supercov gives your coding agent the next useful test to write.** It runs the test command you already use, records local coverage evidence, and turns uncovered paths into small, actionable queries. Your agent writes a focused test, reruns the suite, proves what improved, and keeps going while useful gaps remain.
+**Supercov tells your coding agent what to fix and what to test.** It scores your code quality with [Jev](https://typesafe.ai), runs the test command you already use, and turns uncovered paths into small, actionable queries. Your agent picks a target, writes a focused test or a focused refactor, proves what improved, and keeps going.
 
-No account, config file, import, custom reporter, or hosted service is required. Supercov is local, free, open source, and MIT licensed.
+Paste this to your coding agent to start:
+
+```text supercov-prompt
+Measure code quality with npx supercov and show me the weakest files.
+```
+
+Scoring needs a [TypeSafe AI](https://typesafe.ai) API key, and your coding agent will usually ask you for it. It costs about a cent per megabyte of source. Coverage needs no account, config file, import, custom reporter, or hosted service. Supercov is local, free, open source, and MIT licensed.
 
 [Website](https://supercov.com) · [Documentation](https://supercov.com/docs) · [npm](https://www.npmjs.com/package/supercov) · [GitHub](https://github.com/supercorp-ai/supercov)
 
@@ -13,6 +19,41 @@ Supported by [Supercorp](https://supercorp.ai).
 [Agent workflow](https://supercov.com/docs/agent-loop): ask your coding agent
 to add a test in your own project, with a recorded example to follow along.
 
+## Score your code
+
+```bash
+export TYPESAFE_API_KEY=...   # get one at https://typesafe.ai
+npx supercov quality
+```
+
+No arguments and no configuration. It finds your source, asks Jev a set of
+yes/no questions about each file, and does the arithmetic itself, so every part
+of a score is a claim you can check against the file.
+
+```
+Quality weak (3.8/10) over 163 files.
+  11 good, 52 fair, 100 weak.
+
+Weakest:
+  weak  runtime/python/supercov_runtime.py
+        long_method 0.96, deep_nesting 0.92, complex_conditional 0.89, +9 more
+  weak  crates/supercov-engine/src/assertion_store.rs
+        long_method 0.96, deep_nesting 0.91, complex_conditional 0.86, +8 more
+```
+
+Narrow to what fired, read one file in full, or review a change:
+
+```bash
+npx supercov quality gaps
+npx supercov quality file src/server.ts
+npx supercov quality patch                    # your uncommitted work, or your branch
+npx supercov quality patch --annotate github  # workflow annotations, no token
+```
+
+Jev charges for what it reads and nothing for what it writes, so a megabyte of
+source costs a little over a cent. Answers are cached by content, so a second
+run pays only for what changed. See [Understanding quality](docs/quality.md).
+
 ## Start with the suite you already have
 
 ```bash
@@ -25,12 +66,33 @@ github.com/supercorp-ai/supercov/cmd/supercov@latest`.
 
 Everything after `--` is your test command. Supercov runs it without changing your source, tests, runner configuration, or normal build output.
 
-Then ask what is still uncovered:
+Then read the result and ask what is still uncovered:
+
+```bash
+npx supercov runs latest
+```
+
+```
+run run_7fc676ba671d42be
+command: npm test
+
+Coverage
+  Lines      100.00% (5/5)
+  Branches   66.67% (4/6)
+  MC/DC      33.33% (1/3)
+```
 
 ```bash
 npx supercov runs latest gaps --limit 10
 ```
 
+```
+Coverage gaps — only files with unresolved obligations
+
+src/pricing.js
+  uncovered: lines 0  statements 1  functions 0  branch outcomes 0  MC/DC conditions 2
+```
+
 After your agent adds a test, rerun the complete suite and prove the gain:
 
 ```bash
@@ -243,6 +305,7 @@ npx supercov clean             # remove all runs and the build cache
 ## Documentation
 
 - [Getting started](https://supercov.com/docs/getting-started)
+- [Understanding quality](https://supercov.com/docs/quality)
 - [Agent workflow](https://supercov.com/docs/agent-loop)
 - [Understanding assertions](docs/assertions.md)
 - [Troubleshooting](https://supercov.com/docs/troubleshooting)

package/docs/cli.md

@@ -24,8 +24,70 @@ npx supercov --help
 | Find the tests a change affects | `npx supercov runs latest tests affected` |
 | Combine shards | `npx supercov merge <id> <id> [...]` |
 | Remove local data | `npx supercov clean` |
+| Assess code quality with Jev | `npx supercov quality` |
+| See only files with findings | `npx supercov quality gaps` |
+| Review what a change introduced | `npx supercov quality patch` |
 | Read bundled guides | `npx supercov docs` |
 
+## Assess source quality
+
+```sh supercov-example
+supercov quality                 # this repository
+supercov quality src/            # one directory
+supercov quality gaps            # only files something fired on
+supercov quality file src/a.ts   # one file, every check
+supercov quality scope           # which files are assessed, and why
+supercov quality snapshots       # saved assessments
+supercov quality diff <older> <newer>
+```
+
+With no argument the subject is the repository you are standing in. Every
+assessment saves a snapshot, so the reading commands work afterwards with no key
+and no network.
+
+Twelve yes/no questions about named code properties go to [Jev](https://typesafe.ai);
+the score is arithmetic this command does over the answers. Text reports a band,
+`good`, `fair` or `weak`; `--json` carries the number and every check with what
+is known about it. `--all` includes test files, generated output and anything
+outside a source root, all of which are left out by default. `--dry-run` prints
+the exact requests and contacts nothing.
+
+`quality diff` reports what declined between two assessments: which files lost
+health, which properties appeared, and which files entered or left the scope.
+
+Assessing needs a TypeSafe AI API key in `TYPESAFE_API_KEY`; reading a saved
+assessment does not. The command prints a cost estimate before sending anything
+and caches answers by content, so a second run pays only for what changed.
+
+See [Understanding quality](https://supercov.com/docs/quality) for what the
+number is worth and which files get assessed.
+
+## Review what a change introduced
+
+```sh supercov-example
+supercov quality patch
+supercov quality patch --base origin/main
+supercov quality patch --base origin/main --annotate github --run latest
+```
+
+The same twelve properties asked of a change, plus six risk checks that only
+apply to one: a credential in source, untrusted input in a query, a change to
+who may do what, a test that now checks less, a schema migration, and debugging
+left behind.
+
+With no range it reviews uncommitted work when the tree is dirty and everything
+since this branch left its default branch when it is clean. `--unstaged`,
+`--staged` and `--base <ref>` say so explicitly; `--base` uses the merge base,
+like `runs patch`, so commits other people landed after you branched are not
+your change.
+
+`--annotate github` prints workflow annotations on stdout, needing no token and
+posting no comment. `--run <id>` reads a saved coverage run and marks any file
+where a property appeared and the run left lines uncovered.
+
+Output lists only files where something appeared. A change that introduces
+nothing prints one line saying so. About $0.0005 per changed file.
+
 ## Measure a test command
 
 ```sh supercov

package/docs/getting-started.md

@@ -12,6 +12,15 @@ added and the before-and-after coverage.
 Your agent can install Supercov if needed. It runs the commands and edits the
 tests; you don't need to do those steps yourself.
 
+To score the code itself rather than its tests, set a [Jev](https://typesafe.ai)
+key and ask:
+
+```text supercov-prompt
+Measure code quality with npx supercov and show me the weakest files.
+```
+
+See [Understanding quality](https://supercov.com/docs/quality).
+
 When it finishes, review the test change and coverage comparison in your
 conversation. Ask separately if you want a commit or pull request.
 

package/docs/quality.md

@@ -0,0 +1,208 @@
+# Understanding quality
+
+`supercov quality` tells you what is in your code: twelve named properties,
+checked file by file, so a score is never a number you have to take on faith.
+
+Judgments come from [Jev](https://typesafe.ai), which answers typed questions
+rather than generating prose. Supercov asks the questions and does the
+arithmetic, so every part of a score is a claim you can check against the file.
+
+## Set your key
+
+Assessing needs a TypeSafe AI API key, and your coding agent will usually ask
+you for it. Get one at [typesafe.ai](https://typesafe.ai).
+
+Supercov looks for it in `TYPESAFE_API_KEY`:
+
+```bash
+export TYPESAFE_API_KEY=...        # for this shell
+TYPESAFE_API_KEY=... npx supercov quality   # for one command
+```
+
+The environment variable is the only way to pass it. A key given on the command
+line ends up in your shell history and in the process list, where anyone on the
+machine can read it.
+
+Set it the way your environment already sets secrets:
+
+| Where | How |
+| --- | --- |
+| GitHub Actions | `env: { TYPESAFE_API_KEY: ${{ secrets.TYPESAFE_API_KEY }} }` |
+| GitLab CI | a masked CI/CD variable named `TYPESAFE_API_KEY` |
+| Docker | `docker run -e TYPESAFE_API_KEY ...` |
+| Local development | a `.env` loaded by `direnv`, `dotenv` or your shell profile |
+
+Reading a saved assessment never needs a key, and `--dry-run` prints the exact
+requests without sending them.
+
+## Start with the repository
+
+```bash
+npx supercov quality
+```
+
+No arguments, no configuration. It finds your source, asks twelve questions of
+each file, and saves a snapshot you can read afterwards without a key or a
+network.
+
+```
+Quality fair (5.0/10) over 163 files.
+  11 good, 53 fair, 99 weak.
+
+Weakest:
+  weak  src/lib/modernHttp.ts
+        long_method 0.93, duplicated_logic 0.88, complex_conditional 0.87, +7 more
+```
+
+`good` is 8 and above, `fair` is 5 to 8, `weak` is below 5. `--json` carries the
+number when something needs to sort.
+
+## The twelve properties
+
+god class, long method, deep nesting, complex conditional, long parameter list,
+duplicated logic, primitive obsession, dead code, feature envy, temporary field,
+message chains, magic values.
+
+They come from Fowler and Beck's refactoring smells and the class-scope smells
+CodeScene's Code Health is built from. Each is a yes/no question with a
+definition and a stated exception, so two careful readers would agree on the
+answer.
+
+Three of them fire on more than half the files in a typical repository, so the
+summary shows the three strongest per file. To see all twelve with what is known
+about each:
+
+```bash
+npx supercov quality file src/lib/modernHttp.ts
+npx supercov quality gaps        # only files something fired on
+```
+
+## Reading the score
+
+Health is the mean of the twelve answers, done by this command rather than by
+the model. A directory or a whole repository counts its larger files for more,
+so a folder of one-line re-exports cannot outvote the file everything depends
+on.
+
+Use it to find the code that is hardest to change, and `quality gaps` to jump
+straight to the files something fired on.
+
+## What a change introduced
+
+```bash
+npx supercov quality patch
+```
+
+With no range it reviews your uncommitted work when the tree is dirty, and
+everything since your branch left its default branch when it is clean. Say so
+explicitly with `--unstaged`, `--staged`, or `--base origin/main`, which uses
+the merge base so commits other people landed after you branched are not
+counted as yours.
+
+It asks the twelve properties differentially, whether the new version shows
+something the old one did not, and adds six checks that only make sense for a
+change:
+
+- a credential written into source
+- untrusted input interpolated into a query
+- a change to how the system decides who may do what
+- a test that now checks less than it did
+- a database schema or data migration
+- debugging left behind
+
+Output lists only files where something appeared. A change that introduces
+nothing says so in one line.
+
+```bash
+npx supercov quality patch --base origin/main --annotate github
+```
+
+`--annotate github` prints workflow annotations on stdout. It needs no token and
+posts no comment.
+
+## Which files get looked at
+
+```bash
+npx supercov quality scope
+```
+
+Source roots come from your package manifests and from what they declare, so a
+`bin` or `exports` entry counts even when it is not in a conventional directory.
+Test files, generated output, tool scripts, examples, benchmarks and
+documentation are left out, each with its reason. `--all` includes everything.
+
+If some of your code sits somewhere none of that recognises, Supercov asks Jev
+about those paths with your whole tree as context, and says how many it decided
+that way. To decide yourself:
+
+```bash
+SUPERCOV_SOURCE_ROOTS=src,packages npx supercov quality
+```
+
+A declaration is never second-guessed.
+
+## Tracking it over time
+
+```bash
+npx supercov quality snapshots
+npx supercov quality diff <older> <newer>
+```
+
+Which files lost health, which gained, which properties appeared, and which
+files entered or left the scope. A file whose contents did not change is marked,
+so a small movement does not send you looking for an edit that was never made.
+
+## What it costs
+
+Jev charges for what it reads and nothing for what it writes, at $42 per billion
+input tokens. What that means in practice, measured rather than estimated:
+
+| | source | cost |
+| --- | ---: | ---: |
+| Supercov's CLI crate | 0.5 MB | $0.007 |
+| a TypeScript gateway, 197 files | 0.9 MB | $0.02 |
+| one changed file in a review | — | $0.0005 |
+
+About a cent per megabyte of source, a little more when the files are small,
+because each one carries its own questions.
+
+The command prints its estimate before sending anything, so a number that looks
+wrong can be stopped rather than discovered on an invoice:
+
+```
+[supercov] quality: 35 requests, about 111840 input tokens ($0.0047) if none is cached
+```
+
+**Most runs cost far less than that estimate.** Answers are cached by content
+under `.supercov/quality/requests/`, so a second run pays only for files that
+actually changed. The cache follows content rather than paths, which means
+switching branches, rebasing or checking out an old commit reuses everything
+unchanged: assessing the same directory 400 commits back in a real repository
+answered every file from cache and sent nothing.
+
+Three ways to spend less:
+
+- **Assess a directory, not the tree**, while you are iterating:
+  `npx supercov quality src/api`.
+- **Review the change, not the repository**, in CI: `npx supercov quality patch`
+  costs about $0.0005 per changed file, so a typical pull request is a fraction
+  of a cent.
+- **Keep `.supercov/` between CI runs** if your runner supports a cache. An
+  unchanged file then costs nothing on every run after the first.
+
+`--refresh` asks again and bypasses the cache. `--dry-run` prints the exact
+requests, sends nothing and costs nothing.
+
+## Reference
+
+```bash
+npx supercov quality                             # this repository
+npx supercov quality gaps                        # only files something fired on
+npx supercov quality file src/server.ts          # one file, every check
+npx supercov quality scope                       # which files, and why
+npx supercov quality snapshots                   # saved assessments
+npx supercov quality diff <older> <newer>        # what declined
+npx supercov quality patch                       # what a change introduced
+```
+
+Full options are in the [CLI reference](https://supercov.com/docs/cli).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "supercov",
-  "version": "0.0.55",
-  "description": "Coverage for coding agents and software factories \ud83c\udf19",
+  "version": "1.0.1",
+  "description": "Code quality and coverage for coding agents",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,6 +18,7 @@
     "docs/getting-started.md",
     "docs/agent-loop.md",
     "docs/assertions.md",
+    "docs/quality.md",
     "docs/assertion-evidence.md",
     "docs/assertion-maps.md",
     "docs/assertion-agent.md",
@@ -98,14 +99,14 @@
     "test:launcher": "go vet ./cmd/... && go test ./cmd/..."
   },
   "optionalDependencies": {
-    "@supercov/cli-darwin-arm64": "0.0.55",
-    "@supercov/cli-darwin-x64": "0.0.55",
-    "@supercov/cli-linux-arm64-gnu": "0.0.55",
-    "@supercov/cli-linux-arm64-musl": "0.0.55",
-    "@supercov/cli-linux-x64-gnu": "0.0.55",
-    "@supercov/cli-linux-x64-musl": "0.0.55",
-    "@supercov/cli-win32-arm64": "0.0.55",
-    "@supercov/cli-win32-x64": "0.0.55"
+    "@supercov/cli-darwin-arm64": "1.0.1",
+    "@supercov/cli-darwin-x64": "1.0.1",
+    "@supercov/cli-linux-arm64-gnu": "1.0.1",
+    "@supercov/cli-linux-arm64-musl": "1.0.1",
+    "@supercov/cli-linux-x64-gnu": "1.0.1",
+    "@supercov/cli-linux-x64-musl": "1.0.1",
+    "@supercov/cli-win32-arm64": "1.0.1",
+    "@supercov/cli-win32-x64": "1.0.1"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.55.0",