For engineers / LexCode
LexCode
LexCode is LexLint's code reader. It reads a repository on your machine and writes down, file and line, what the code does, in the words LexLint uses for activities. In CI it fails the build when the code does something your declaration does not say.
- Runs on your machine
- Once its engine is downloaded, a scan makes no network call, and there is no telemetry. The record holds paths, line numbers and rule ids, never your source.
- 731 rules
- Rules for 26 activities in C#, Go, Java, JavaScript, Kotlin, PHP, Python, Ruby, Rust, Swift and TypeScript, and a package map that quotes each vendor's own description.
- Open source
- MIT license. Every rule is plain YAML with code it must match and code it must not.
fastapi/full-stack-fastapi-template at f4bcfab, 221 files, scanned in 6.0 seconds
The FastAPI full-stack template, checked against a declaration an agent wrote by reading its code. Two packages raise a question, not a failure.emails can send mail the software starts on its own, and sentry-sdk, whose WARN is cut from the block, can track devices; the declaration says the app does neither. A reader confirms it: the mail is password recovery a person asked for, and Sentry here reports errors only. A WARN fails the build only with --fail-on-enables.
Why it helps
A LexLint lint starts from a declaration: a short file, ACTIVITIES.md or lexlint.yml, that says what your app does and where it operates. When the code changes and the declaration does not, the lint answers for an app that no longer exists, and nothing says so.
- Drift shows up in the pull request. A new analytics package, or a model call the declaration leaves out, is a WARN or a FAIL in CI on the day it is added, not at the next review.
- Every claim has a file and a line. A security or legal reviewer reads the evidence instead of asking an engineer what the code does.
- The declaration stays a person's call. LexCode never writes it. It shows the evidence, and a person decides whether an activity describes the app.
- Your code stays with you. It runs on your machine and in your own CI, free and open source.
Languages
A scan names every language it does not read yet, with a file count, so an activity in those files reads as not checked, never as not there. Each new language comes with its own rules, its package manifests and a map of what its common packages do.
| Languages | LexCode reads them |
|---|---|
| C#, Go, Java, JavaScript, Kotlin, PHP, Python, Ruby, Rust, Swift and TypeScript | Today |
Run it
Node 20 or later. LexCode is on npm as @ungovr/lexcode for now; the command it installs is lexcode. The source, the rules and the issue tracker are at github.com/ungovr/lexcode, under the MIT license.
Where it sits
LexCode checks the declaration against the code. It looks for code that crawls other sites, records a voice, tracks a device, generates content with a model or sends messages nobody asked for, and names each match by file and line.
It says what the code does, never what law applies, and it never writes a declaration for you. Whether an activity describes your app is a question a person answers, with the evidence in front of them.
Scroll sideways to see the whole figure.
How a scan works
- It reads the files git tracks. It honors
.gitignoreand leaves out tests, vendored and minified code, generated files, symbolic links and files over 5 megabytes. - It runs its rules. 731 rules in Semgrep syntax, run by the open-source Opengrep engine (1.33.1), pinned to one version and checked against the hash LexCode ships for it before it runs.
- It reads your manifests. npm, PyPI, Go, RubyGems, Maven, Gradle, Composer, NuGet, Cargo, Swift Package Manager and CocoaPods dependencies are matched against a component map: what each package makes possible, in the vendor's own words, with a link to where the vendor says it.
- It writes the record.
lexcode.jsonlists each activity with the rule or package behind it and where it is, and on request a SARIF file for GitHub code scanning.
What the record says
Each activity in the record carries one of four words. Some activities rest on facts outside the code, such as whether an app serves minors or whether its operator is a bank. LexCode leaves those to the declaration.
| In the record | What it means |
|---|---|
performs | A rule matched your own code doing it. |
enables | Only a dependency makes it possible. A package can be installed and never called, so this is a question, not an answer. |
| worth a look | A weak hint. It is shown, and it never changes a result. |
| searched, not found | LexCode has rules for the activity and none matched. The record says how many it tried. |
The check in CI
lexcode check compares the record with the declaration you committed. Code that does something the declaration leaves out, or says it does not do, fails the build.
A suppression lives in .lexcode.yml beside the declaration, never in a code comment, and it needs a reason, because it records a person's decision.
| The code shows | The declaration says | Result |
|---|---|---|
performs X | X is declared | PASS |
performs X | nothing about X | FAIL |
performs X | the app does not do X | FAIL |
enables X only | X is not declared | WARN, or FAIL with --fail-on-enables |
| nothing for X | X is declared | INFO: a declaration can rest on things outside the repository |
Sample output from real runs
Every terminal block on this page, the one at the top included, is real output from LexCode 1.5.0, run on over public open-source code, each repository at a pinned commit. Paths are shortened to the repository root, and anything left out is marked where it was cut; nothing else is changed.
A clean check
vercel/chatbot at 8603c8e, 174 files, scanned in 5.1 seconds
Every activity the starter declares has evidence, each with the rule that found it, and no rule or package points to an activity it says it does not do.
A large Python and JavaScript codebase
openedx/edx-platform at db5bfda, 5,762 files, scanned in 15 seconds
The record's evidence for Open edX, one row per activity and kind:
| Activity | How | Matches | First match, and the rule or package |
|---|---|---|---|
automated_outreach | performs | 1 | openedx/features/calendar_sync/utils.py:87lexcode.outreach.send-in-loop-or-job-py |
processes_personal_data | performs | 8 | common/djangoapps/student/models/course_enrollment.py:1620lexcode.personal.py-model-field |
processes_personal_data | enables | 2 | pyproject.toml:11pkg:pypi/analytics-python@1.4.post1 |
relies_on_digital_identity | performs | 2 | lms/djangoapps/verify_student/models.py:320lexcode.identity.selfie-and-id-document-py |
ships_encryption | enables | 5 | pyproject.toml:20pkg:pypi/cryptography@50.0.2 |
tracks_devices | performs | 41 | cms/static/js/views/course_highlights_enable.js:35lexcode.tracking.js-analytics-and-pixel-calls |
tracks_devices | enables | 1 | pyproject.toml:11pkg:pypi/analytics-python@1.4.post1 |
Worth a look, with no effect on any result:
automated_outreachcms/djangoapps/course_creators/admin.py:193distributes_software_productpyproject.toml:1ships_consumer_interfacecms/urls.py:227
Saying what it did not read
instructure/canvas-lms at 1c9f0bb, 14,800 files, scanned in 65 seconds
Most of Canvas LMS's server is Ruby, which LexCode reads along with its Gemfile. Whatever it still skips, the scan names with a count, and an activity missing from those files reads as not checked, never as not there.
| Activity | How | Matches | First match, and the rule or package |
|---|---|---|---|
aggregates_content | performs | 1 | lib/external_feed_aggregator.rb:68lexcode.aggregate.rb-feedjira-parse |
aggregates_content | enables | 1 | Gemfile.d/app.rb:96pkg:gem/feedjira@4.0.2 |
automated_outreach | enables | 1 | Gemfile.d/app.rb:39pkg:gem/aws-sdk-sns@1.113.0 |
generates_content | enables | 2 | Gemfile.d/app.rb:36pkg:gem/aws-sdk-bedrockruntime@1.75.0 |
processes_personal_data | performs | 12 | app/controllers/developer_keys_controller.rb:486lexcode.personal.rb-permitted-params |
processes_personal_data | enables | 4 | Gemfile.d/app.rb:109pkg:gem/sentry-rails@6.5.0 |
processes_voice | performs | 1 | ui/features/speed_grader/jquery/speed_grader.tsx:1264lexcode.voice.speech-recognition-start |
records_calls | performs | 1 | app/models/big_blue_button_conference.rb:187lexcode.calls.rb-bigbluebutton-record |
ships_encryption | performs | 6 | gems/canvas_security/lib/canvas_security.rb:120lexcode.crypto.rb-platform-encryption |
ships_encryption | enables | 2 | package.json:142pkg:npm/crypto-js@4.2.0 |
tracks_devices | enables | 4 | Gemfile.d/app.rb:109pkg:gem/sentry-rails@6.5.0 |
Asking what an activity means
lexcode explain takes an activity, a rule id or a package URL, and answers from the same files the scan uses.
Finding packages the map does not know
The starter apps below, together; the first 12 of 531 rows
Most of these are interface libraries that do nothing a law asks about. The list is how new map entries are chosen: a person reads the vendor's own description and writes the entry from it.
How often it agrees with a reader
An agent that had not seen LexCode's rules read popular starter apps and wrote down what each does: the Vercel AI chatbot, the Next.js subscription payments, the Obytes Expo mobile app, the FastAPI full-stack template, the Bullet Train Rails starter, the Spring PetClinic, the Now in Android, the Symfony Demo, the Wave Laravel starter, the eShop .NET reference app, the Clean Architecture template, the Clean Architecture for SwiftUI, the Penny, Vapor's Discord bot, the Zero To Production newsletter service, and the RealWorld API on axum and sqlx. Then we ran LexCode on the same commits, on .
LexCode found 31 of the 59 activities the readers found. No rule matched code doing something a reader said the app does not do; 2 packages raised a question, shown above.
The misses are nine activities. Every starter but the RealWorld API, which serves data and no screen, serves the public, which makes it a consumer interface to a reader; LexCode has no rule that counts one as evidence, and showed it in six of the apps only as worth a look. Both encryption cases are a secure-connection stack compiled in by the client libraries the app connects through, rustls in Zero To Production and BoringSSL in Penny. The readers counted it; LexCode reads a bundled stack only where the app's own code sets one up.
Four of the other seven are in Penny, Vapor's Discord bot. Its reader counted the member records it keeps, the Swift project's proposal and release feeds it fetches on a timer and reposts to the server, and the chat it saves, deleted messages included, for the moderators; LexCode found the messages the bot sends on its own but none of those. Penny is also where the engine's Swift parser stumbles most: there are bot files it could not read, and each of those four activities rests partly on one of them, so part of that gap is the parser's and part is the rules'. Zero To Production emails each new subscriber, and every confirmed subscriber when an issue is published, by posting to the mail vendor's web API with a general HTTP client; LexCode found the personal data but not the outreach.
Now in Android lists other sites' articles, videos and podcasts and ships through Google Play, which its reader counted as aggregating content and distributing software; LexCode found the mobile app but neither of those. The eShop .NET reference app builds apps that customers install on their own devices, which its reader counted as distributing software, and sends a customer's whole chat with its assistant to the model vendor on every turn, which its reader counted as recording text chat; LexCode found the apps and the assistant but neither of those. Clean Architecture for SwiftUI is published as a template other developers build their own apps from, which its reader counted as distributing software and LexCode showed only as worth a look. Symfony Demo's signed-in users comment on blog posts, and the RealWorld API's users publish articles, comment on them and follow one another, each a social platform to its reader, which LexCode showed only as worth a look.
| Activity | A reader found | LexCode found | Missed in |
|---|---|---|---|
aggregates_content | 2 | 0 | Now in Android, Penny, Vapor's Discord bot |
automated_outreach | 3 | 2 | Zero To Production newsletter service |
crawls_web | 1 | 0 | Penny, Vapor's Discord bot |
deploys_chatbot | 2 | 2 | none |
distributes_software_product | 5 | 2 | Now in Android, eShop .NET reference app, Clean Architecture for SwiftUI |
generates_content | 2 | 2 | none |
generates_text | 2 | 2 | none |
operates_social_platform | 2 | 0 | Symfony Demo, RealWorld API on axum and sqlx |
processes_personal_data | 14 | 13 | Penny, Vapor's Discord bot |
records_text_chat | 3 | 1 | eShop .NET reference app, Penny, Vapor's Discord bot |
ships_consumer_interface | 14 | 0 | Vercel AI chatbot, Next.js subscription payments, Obytes Expo mobile app, FastAPI full-stack template, Bullet Train Rails starter, Spring PetClinic, Now in Android, Symfony Demo, Wave Laravel starter, eShop .NET reference app, Clean Architecture template, Clean Architecture for SwiftUI, Penny, Vapor's Discord bot, Zero To Production newsletter service |
ships_encryption | 2 | 0 | Penny, Vapor's Discord bot, Zero To Production newsletter service |
ships_mobile_app | 4 | 4 | none |
tracks_devices | 3 | 3 | none |
Your code stays on your machine
Once its engine is cached, a scan makes no network call. LexCode's one network call is that engine's download on first run, about 40 megabytes, checked against a hash shipped in the package; lexcode engine fetch does it ahead of time for a machine without network access.
The record holds paths, line numbers, rule ids and package URLs, and no source text unless you pass --snippets. There is no telemetry.
What it does not do
- It does not say which law applies. The lint does that, from your jurisdictions and roles.
- It reads C#, Go, Java, JavaScript, Kotlin, PHP, Python, Ruby, Rust, Swift and TypeScript, plus the script blocks of Vue, Svelte, HTML, Jinja, ERB, JSP, PHP, Blade, Twig, Tera and Razor files, and an Apple app's Info.plist, privacy manifest, entitlements and Xcode project. Any other language is named in a notice with its file count.
- It sees only the repository. A vendor's server, a dashboard setting or a contract is outside it, which is why a declared activity with no evidence is information, not a failure.
- It does not follow every call. A rule matches a pattern in the code; a package in a manifest may never be called.
- It never runs your code, and never runs a program from the directory it scans.