Repository navigation
Description
Compile-time code can see only the expression it is evaluating. It cannot see the program being compiled, or what the checker decided about it. This issue is about letting Kex code read the checked program while it compiles, so that rules about the whole application can be written as ordinary Kex libraries.
What exists
Kex.AST(Expose the AST to Kex programs (Kex.AST) #131) parses source at run time:Kex.AST.parseFile("src/main.kex")for the AST, andKex.AST.parseSyntaxfor the lossless syntax tree. The syntax tree keeps comments:toSourcereprints it byte for byte, andcommentsBeforegives the comments that belong to a node, including a# kex:disable-next-line. Both return the syntax and nothing the checker worked out: no types, and no answer to which function a call resolves to.compiled doruns Kex during compilation, but only on its own expression. Builder-chain collapse evaluates a whole query chain at compile time, and--collapse-reportprints what it found. Kex code cannot read either.- The HIR (
hir::Program) holds the checker's answers: the target of every call, the type of every expression, trait dictionaries. Only the C++ consumers can read it.
What is missing
- The checked program as data, at compile time. The
Kex.ASTtree for every unit in the program, together with the checker's answers for each node: its type, the definition a call resolves to, and the record, trait or module behind a name. - A whole-program phase. A hook that runs compile-time Kex after every unit is checked, instead of once per declaration as
compiled dodoes. A failure in it is a compile error at a source position the hook names. - Facts that compile-time code produced. What collapse evaluated (a Harmat query's tables and conditions, a builder step such as
.dismissGuard(:name)), readable by that phase as values. Frameworks also need a way to add their own facts, such as a Metro route and its pipelines. - Facts that survive separate compilation. Units are checked and built one at a time, so each unit's facts would be stored with its interface data (next to KexI) and read when the program is linked. Changing one unit then re-reads only that unit's facts.
No new syntax is needed. This is a compiler capability, exposed through a stdlib module.
Why
The motivating case is application guardrails: rules of the form "every X must Y" that are broken by an omission, and that no reviewer can check by reading the code. For example:
- every query on a table with
organization_idfilters by the current organization; - every route goes through one of the sign-in pipelines;
- a file is served only after an
availableTo?check; - a raw token never reaches a log.
Written as pseudo-code against Slick:
guard :organization_scoped do
says "A query on organization data filters by the organization being asked about"
covers Queries.touching(:organization_id)
requires { |q| q.filters(:organization_id, by: Route.param(:organization)) }
rejects Conversations.all
accepts Conversations.where(organizationId: Current.organizationId)
end
# an exception, in the query it applies to
SiteWide.all.dismissGuard(:organization_scoped).run
Every rule like this needs the same things: every query or route in the program, and what the checker knows about the values in it. With this issue done, the guard form, the query and route facts, and the analyses can all be libraries in Harmat, Metro or the stdlib.
The same capability would also serve:
- a linter in Kex (kex lint / kex format: a linter and autoformatter written in Kex #169);
- the review graph of changed entities;
- a code navigator.
Analyses, as libraries on top
These do not have to be in the compiler. They can be written in Kex over the data above:
- Where a value came from. Immutability makes this mostly a walk along bindings.
- A check runs on every path before an action. Control flow is structured: no goto, and early
return … if. - A value never reaches a sink.
foulalready marks where effects can happen.
The known hard cases are values sent between processes, function values, and checks done inside a helper. The safe default is that a fact the analysis cannot settle fails the rule.
Open questions
- Dependencies: does the phase see dependency packages' facts, or only the current package's?
- Representation: are the checker's answers attached to
Kex.ASTnodes, or a separate table keyed by node? The HIR keys answers by node address today. - Stability: which parts of the representation become a public interface that packages depend on?
- Sandbox: is the phase sandboxed like
compiled do? It should read the program, not the file system or the network. - Cost: how expensive is it on Slick-sized programs, and can the phase re-run per changed unit?
Activity