Krypton
Wire format

Wire format, version 1

The body of POST /v1/score. A client reads source on the user's machine and writes this.

Status. Version 1 is the format the server speaks; a server answers 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 */ ]
}
FieldTypeMeaning
wire_versionintegerMust be 1.
clientobjectname (up to 64 characters) and version (up to 32). Used for support.
options.levelstringrelaxed, standard (default) or strict: how tight the flag limits are.
options.detailstringsummary (default) or full. full is refused unless the server was started to allow it.
options.configobjectOverrides for file selection and conventions only. See capabilities for the allowed keys. Anything else is refused.
filesarrayAt 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

FieldTypeMeaning
pathstringThe path the server will report, with forward slashes.
languagestringpython, javascript, typescript or tsx.
bytesintegerSize on disk, for the size limits.
longest_lineintegerCharacters in the longest line, counted as the command line counts them.
lines, cr, final_newlineThe line shapes. See Line shapes.
flagsobjectgenerated_marker (boolean) and vendored (vendored_path, vendored_name, vendored_content or null).
waiversobjectLine number (1-based) to { comment_only, reason }, only for lines holding a krypton: ignore comment.
importsarrayEach import as the ordered candidate paths that exist among this request's files. The server takes the first one it scored.
altered_linesarray or null1-based lines changed, when scoring a diff. Null means every line.
change_frequencynumber or null0 to 1, from git history, when ordering matters.
treeobjectThe 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.

ArrayEntry for node i
nThe number of nodes. Node 0 is the root.
kinds, kindA string table of grammar kinds, and each node's index into it.
fields, fieldA string table of roles (name, body, ...), and each node's role in its parent, or -1.
parentThe parent's index, -1 for the root. Always an earlier node (parent[i] < i).
flagsA bit mask: 1 named, 2 extra (a comment), 4 syntax error, 8 missing (inserted by the parser).
start_line, end_line0-based lines.
start_col, end_colColumns, in characters.
start_index, end_indexCharacter offsets from the start of the file; the end is exclusive.
maskSparse map, node index to a stand-in that keeps one fact.
digestSparse 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:

NodeSent asWhy
A name: identifier, property, type name, object key, a declaration's namedigest: 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 namedigest, of the text with whitespace runs collapsed to one space and trimmedTwo outputs are the same exactly when their fingerprints are.
A match patternmask: _ if exactly _, else ?The engine asks only whether it is a catch-all.
A dotted namemask: each part becomes n, so a.b.c is n.n.nThe 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:

ikindfieldparentnamedstartenddigest
0module-1yes050
1function_definition0yes049
2def1no03
3identifiername1yes45252f10c83610ebca
4parameters1yes58
5(4no56
6identifier4yes672d711642b726b044
7)4no78
8:1no89
9blockbody1yes1449
10if_statement9yes1436
11if10no1416
12identifier10yes17182d711642b726b044
13:10no1819
14blockconsequence10yes2836
15return_statement14yes2836
16return15no2834
17integer15yes35366b86b273ff34fce1
18return_statement9yes4149
19return18no4147
20integer18yes4849d4735e3a265e16ee

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

A request that breaks a rule gets 422 with the JSON path of the first problem. The size limits are in the API reference.