Wire format, version 1
The body of POST /v1/score. A client reads source on the user's machine and writes this.
426 to any other wire_version.The request
{
"wire_version": 1,
"client": { "name": "my-client", "version": "0.1.0" },
"options": { "level": "standard", "detail": "summary", "config": {} },
"files": [ /* one entry per file, see below */ ]
}
| Field | Type | Meaning |
|---|---|---|
wire_version | integer | Must be 1. |
client | object | name (up to 64 characters) and version (up to 32). Used for support. |
options.level | string | relaxed, standard (default) or strict: how tight the flag limits are. |
options.detail | string | summary (default) or full. full is refused unless the server was started to allow it. |
options.config | object | Overrides for file selection and conventions only. See capabilities for the allowed keys. Anything else is refused. |
files | array | At least one file. Paths must be unique. |
Unknown keys anywhere in the body are refused, so a typo cannot silently change a score.
A file
| Field | Type | Meaning |
|---|---|---|
path | string | The path the server will report, with forward slashes. |
language | string | python, javascript, typescript or tsx. |
bytes | integer | Size on disk, for the size limits. |
longest_line | integer | Characters in the longest line, counted as the command line counts them. |
lines, cr, final_newline | The line shapes. See Line shapes. | |
flags | object | generated_marker (boolean) and vendored (vendored_path, vendored_name, vendored_content or null). |
waivers | object | Line number (1-based) to { comment_only, reason }, only for lines holding a krypton: ignore comment. |
imports | array | Each import as the ordered candidate paths that exist among this request's files. The server takes the first one it scored. |
altered_lines | array or null | 1-based lines changed, when scoring a diff. Null means every line. |
change_frequency | number or null | 0 to 1, from git history, when ordering matters. |
tree | object | The tree. See below. |
The tree
A tree is flat parallel arrays in depth-first pre-order, one entry per node, never nested objects: nested JSON hits parser depth limits on deeply nested code, and arrays are smaller and compress well. Every node is present, punctuation and comments included.
| Array | Entry for node i |
|---|---|
n | The number of nodes. Node 0 is the root. |
kinds, kind | A string table of grammar kinds, and each node's index into it. |
fields, field | A string table of roles (name, body, ...), and each node's role in its parent, or -1. |
parent | The parent's index, -1 for the root. Always an earlier node (parent[i] < i). |
flags | A bit mask: 1 named, 2 extra (a comment), 4 syntax error, 8 missing (inserted by the parser). |
start_line, end_line | 0-based lines. |
start_col, end_col | Columns, in characters. |
start_index, end_index | Character offsets from the start of the file; the end is exclusive. |
mask | Sparse map, node index to a stand-in that keeps one fact. |
digest | Sparse map, node index to a 16-hex fingerprint. |
All offsets are characters, not bytes. All arrays have exactly n entries.
What carries text
An unnamed token (a keyword or punctuation) needs none: its kind is its text. For named nodes, the client sends one of three stand-ins and never the text:
| Node | Sent as | Why |
|---|---|---|
| A name: identifier, property, type name, object key, a declaration's name | digest: 16 hex characters of HMAC-SHA256 of the text, under a key made fresh for each scan that never leaves the client (a short public list of framework names the server recognises uses plain SHA-256) | The server compares names, never reads them. The client's names book turns fingerprints back into names in the answer. |
An expression the engine only compares: a returned or yielded value, an expression body, the object a method is called on, the class a new builds, a decorator's name | digest, of the text with whitespace runs collapsed to one space and trimmed | Two outputs are the same exactly when their fingerprints are. |
| A match pattern | mask: _ if exactly _, else ? | The engine asks only whether it is a catch-all. |
| A dotted name | mask: each part becomes n, so a.b.c is n.n.n | The engine asks only whether there is a dot. |
If the engine needs the text of a node the client sent no stand-in for, the answer is a clear 422 invalid_tree naming the node, never a guess.
Line shapes
lines has one entry per physical line: [length, runs], where length is the line's length in characters (trailing blanks included) and runs is a list of [start, end) ranges of visible, non-blank characters. It carries line lengths and indentation exactly, with no identifiers or strings. cr lists the 0-based lines that ended with a carriage return, and final_newline says whether the text ended with a newline. The server rebuilds a same-shape skeleton from this, so every line-based rule gives the same answer it would on the real text.
Facts from the client
Some facts need real text and are worked out on the client: whether the file carries a generated marker, whether it looks like a bundled library, how long its longest line is, which lines hold a waiver and the digest of its reason, which imports resolve to which files in the request, and which lines changed. They arrive as the plain fields above.
A worked example
For src/a.py:
def f(x):
if x:
return 1
return 2
the tree has 21 nodes. Here they are, in order:
| i | kind | field | parent | named | start | end | digest |
|---|---|---|---|---|---|---|---|
| 0 | module | -1 | yes | 0 | 50 | ||
| 1 | function_definition | 0 | yes | 0 | 49 | ||
| 2 | def | 1 | no | 0 | 3 | ||
| 3 | identifier | name | 1 | yes | 4 | 5 | 252f10c83610ebca |
| 4 | parameters | 1 | yes | 5 | 8 | ||
| 5 | ( | 4 | no | 5 | 6 | ||
| 6 | identifier | 4 | yes | 6 | 7 | 2d711642b726b044 | |
| 7 | ) | 4 | no | 7 | 8 | ||
| 8 | : | 1 | no | 8 | 9 | ||
| 9 | block | body | 1 | yes | 14 | 49 | |
| 10 | if_statement | 9 | yes | 14 | 36 | ||
| 11 | if | 10 | no | 14 | 16 | ||
| 12 | identifier | 10 | yes | 17 | 18 | 2d711642b726b044 | |
| 13 | : | 10 | no | 18 | 19 | ||
| 14 | block | consequence | 10 | yes | 28 | 36 | |
| 15 | return_statement | 14 | yes | 28 | 36 | ||
| 16 | return | 15 | no | 28 | 34 | ||
| 17 | integer | 15 | yes | 35 | 36 | 6b86b273ff34fce1 | |
| 18 | return_statement | 9 | yes | 41 | 49 | ||
| 19 | return | 18 | no | 41 | 47 | ||
| 20 | integer | 18 | yes | 48 | 49 | d4735e3a265e16ee |
Note that x at nodes 6 and 12 has the same fingerprint: that is how the server knows it is the same name without knowing the name. The names f and x are in the client's book and nowhere else. The line shapes for the same file:
"lines": [[9, [[0, 3], [4, 9]]], [9, [[4, 6], [7, 9]]], [16, [[8, 14], [15, 16]]], [12, [[4, 10], [11, 12]]]],
"cr": [],
"final_newline": true
Line 1 is 9 characters long, def at 0 to 3 and f(x): at 4 to 9. The indentation is the gap before the first run.
Rules a request must meet
- All tree arrays have length
n;parent[i] < ifor every node except the root; every kind and field index points into its table. - Every range lies inside the file the
linesdescribe, a node's range lies inside its parent's, and siblings do not overlap. - Waiver and carriage-return line numbers are lines of the file; each run lies inside its line, in order, not overlapping.
- Masks are short, digests are exactly 16 hex characters, and the number of imports and candidates is bounded.
A request that breaks a rule gets 422 with the JSON path of the first problem. The size limits are in the API reference.