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.
$ lexcode check --declaration ACTIVITIES.md lexcode check against ACTIVITIES.md 221 files read; rules 1.5.0; engine opengrep 1.33.1; registry 1.15 WARN automated_outreach a dependency enables automated_outreach and the declaration says the software does not do it; a dependency is a question, not an answer backend/pyproject.toml:11 pkg:pypi/emails@1.1.2 It sends people messages by email, text, call or direct message that the software initiates, rather than a person sending each one. Requests under a records law are statutory_requests. [cut here: the WARN for tracks_devices] PASS processes_personal_data declared, and the code shows it (300 rules tried) backend/app/models.py:14 lexcode.personal.py-pydantic-email backend/app/models.py:26 lexcode.personal.py-pydantic-email frontend/src/components/Admin/AddUser.tsx:36 lexcode.personal.js-form-schema-email and 4 more [cut here: the scan notices] Worth a look (no effect on the result): distributes_software_product backend/pyproject.toml:1 lexcode.distribute.pyproject-package ships_consumer_interface backend/app/api/routes/users.py:146 lexcode.consumer.signup-route-py Result: 0 FAIL, 2 WARN, 1 PASS, 0 INFO.

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.
LexCode on a public app, narrated: the scan, the check and what a team does with a WARN. Watch it with the transcript

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.

LanguagesLexCode reads them
C#, Go, Java, JavaScript, Kotlin, PHP, Python, Ruby, Rust, Swift and TypeScriptToday

Run it

$ npx @ungovr/lexcode scan # writes lexcode.json in the repository root $ npx @ungovr/lexcode check # compares the code with your declaration

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.

Where LexCode sits lexcode scan turns the repository into an evidence record. lexcode check compares the record with the declaration a person wrote and gives PASS, WARN or FAIL in CI. The LexLint lint reads the declaration and returns findings that cite the law. Your repository code and manifests Evidence record activity, file and line Declaration written by a person lexcode check record against declaration In CI PASS, WARN or FAIL LexLint lint your jurisdictions and roles Findings each citing the law scan

Scroll sideways to see the whole figure.

LexCode works on the left half: it turns the code into evidence and holds the declaration to it. The lint reads the declaration against the law.

How a scan works

  1. It reads the files git tracks. It honors .gitignore and leaves out tests, vendored and minified code, generated files, symbolic links and files over 5 megabytes.
  2. 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.
  3. 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.
  4. It writes the record. lexcode.json lists 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 recordWhat it means
performsA rule matched your own code doing it.
enablesOnly a dependency makes it possible. A package can be installed and never called, so this is a question, not an answer.
worth a lookA weak hint. It is shown, and it never changes a result.
searched, not foundLexCode 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 showsThe declaration saysResult
performs XX is declaredPASS
performs Xnothing about XFAIL
performs Xthe app does not do XFAIL
enables X onlyX is not declaredWARN, or FAIL with --fail-on-enables
nothing for XX is declaredINFO: 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.

$ lexcode check --declaration ACTIVITIES.md lexcode check against ACTIVITIES.md 174 files read; rules 1.5.0; engine opengrep 1.33.1; registry 1.15 PASS deploys_chatbot declared, and the code shows it (33 rules tried) hooks/use-active-chat.tsx:109 lexcode.chatbot.js-usechat-hook PASS generates_content declared, and the code shows it (119 rules tried) package.json:40 pkg:npm/ai@7.0.15 PASS generates_text declared, and the code shows it (22 rules tried) app/(chat)/api/chat/route.ts:332 lexcode.text.js-aisdk-stream-response PASS processes_personal_data declared, and the code shows it (300 rules tried) app/(auth)/actions.ts:10 lexcode.personal.js-form-schema-email app/(chat)/api/chat/route.ts:173 lexcode.personal.js-geolocation lib/db/schema.ts:16 lexcode.personal.js-db-schema-field PASS records_text_chat declared, and the code shows it (55 rules tried) app/(chat)/api/chat/route.ts:126 lexcode.chat.chat-saved-by-name app/(chat)/api/chat/route.ts:183 lexcode.chat.chat-saved-by-name app/(chat)/api/chat/route.ts:364 lexcode.chat.chat-saved-by-name PASS tracks_devices declared, and the code shows it (212 rules tried) package.json:36 pkg:npm/%40vercel/analytics@2.0.1 Worth a look (no effect on the result): generates_text artifacts/code/server.ts:35 lexcode.text.js-chat-result-returned artifacts/code/server.ts:57 lexcode.text.js-chat-result-returned artifacts/sheet/server.ts:28 lexcode.text.js-chat-result-returned and 4 more Result: 0 FAIL, 0 WARN, 6 PASS, 0 INFO.

A large Python and JavaScript codebase

openedx/edx-platform at db5bfda, 5,762 files, scanned in 15 seconds

$ lexcode scan lexcode scan: 5,762 files read; 4 activities with performs evidence, 3 with enables evidence, 3 signals; record written to lexcode.json notice: skipped 29 symbolic links; lexcode does not follow them notice: skipped 3 bundled, minified or generated files (named *.min.js, *.bundle.js, vendor.*.js, *.vendor.js, *.g.cs, *.g.i.cs, *.generated.swift, *+Generated.swift, *.pb.swift or *.grpc.swift, or under a GeneratedSources directory) notice: the engine could not read 35 files; their evidence is missing from this record

The record's evidence for Open edX, one row per activity and kind:

ActivityHowMatchesFirst match, and the rule or package
automated_outreachperforms1 openedx/features/calendar_sync/utils.py:87
lexcode.outreach.send-in-loop-or-job-py
processes_personal_dataperforms8 common/djangoapps/student/models/course_enrollment.py:1620
lexcode.personal.py-model-field
processes_personal_dataenables2 pyproject.toml:11
pkg:pypi/analytics-python@1.4.post1
relies_on_digital_identityperforms2 lms/djangoapps/verify_student/models.py:320
lexcode.identity.selfie-and-id-document-py
ships_encryptionenables5 pyproject.toml:20
pkg:pypi/cryptography@50.0.2
tracks_devicesperforms41 cms/static/js/views/course_highlights_enable.js:35
lexcode.tracking.js-analytics-and-pixel-calls
tracks_devicesenables1 pyproject.toml:11
pkg:pypi/analytics-python@1.4.post1

Worth a look, with no effect on any result:

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.

$ lexcode scan lexcode scan: 14,800 files read; 5 activities with performs evidence, 6 with enables evidence, 5 signals; record written to lexcode.json notice: skipped 8 symbolic links; lexcode does not follow them notice: skipped 9 bundled, minified or generated files (named *.min.js, *.bundle.js, vendor.*.js, *.vendor.js, *.g.cs, *.g.i.cs, *.generated.swift, *+Generated.swift, *.pb.swift or *.grpc.swift, or under a GeneratedSources directory) notice: skipped 10 files over 5 MB notice: skipped 2 files with a line over 100,000 characters (generated or minified code); the engine did not read them notice: the engine could not read 17 files; their evidence is missing from this record
ActivityHowMatchesFirst match, and the rule or package
aggregates_contentperforms1 lib/external_feed_aggregator.rb:68
lexcode.aggregate.rb-feedjira-parse
aggregates_contentenables1 Gemfile.d/app.rb:96
pkg:gem/feedjira@4.0.2
automated_outreachenables1 Gemfile.d/app.rb:39
pkg:gem/aws-sdk-sns@1.113.0
generates_contentenables2 Gemfile.d/app.rb:36
pkg:gem/aws-sdk-bedrockruntime@1.75.0
processes_personal_dataperforms12 app/controllers/developer_keys_controller.rb:486
lexcode.personal.rb-permitted-params
processes_personal_dataenables4 Gemfile.d/app.rb:109
pkg:gem/sentry-rails@6.5.0
processes_voiceperforms1 ui/features/speed_grader/jquery/speed_grader.tsx:1264
lexcode.voice.speech-recognition-start
records_callsperforms1 app/models/big_blue_button_conference.rb:187
lexcode.calls.rb-bigbluebutton-record
ships_encryptionperforms6 gems/canvas_security/lib/canvas_security.rb:120
lexcode.crypto.rb-platform-encryption
ships_encryptionenables2 package.json:142
pkg:npm/crypto-js@4.2.0
tracks_devicesenables4 Gemfile.d/app.rb:109
pkg: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.

$ lexcode explain tracks_devices tracks_devices (Tracks devices) class: evidence (a match is evidence of the activity) definition: It stores or reads information on a user's browser or device beyond what delivering the service needs: analytics or advertising cookies, pixels, SDK identifiers, fingerprinting. page: https://lexlint.io/activities/tracks-devices rules (34): lexcode.tracking.cs-advertising-id, lexcode.tracking.cs-analytics-calls, lexcode.tracking.cs-tracking-cookie, lexcode.tracking.go-analytics-and-cookies, lexcode.tracking.ios-plist-tracking-request, lexcode.tracking.java-advertising-id, lexcode.tracking.java-analytics-calls, lexcode.tracking.java-android-id-sent, lexcode.tracking.java-tracking-cookie, lexcode.tracking.js-advertising-id, lexcode.tracking.js-analytics-and-pixel-calls, lexcode.tracking.js-device-id-sent, lexcode.tracking.js-fingerprint, lexcode.tracking.js-tracking-cookie, lexcode.tracking.kt-advertising-id, lexcode.tracking.kt-analytics-calls, lexcode.tracking.kt-android-id-sent, lexcode.tracking.kt-tracking-cookie, lexcode.tracking.php-analytics-calls, lexcode.tracking.php-tracking-cookie, lexcode.tracking.py-analytics-and-cookies, lexcode.tracking.rb-analytics-calls, lexcode.tracking.rb-tracking-cookie, lexcode.tracking.rs-analytics-calls, lexcode.tracking.rs-tracking-cookie, lexcode.tracking.swift-advertising-id, lexcode.tracking.swift-analytics-google, lexcode.tracking.swift-analytics-product, lexcode.tracking.swift-attribution-sdk, lexcode.tracking.swift-crash-reporting, lexcode.tracking.swift-device-id-sent, lexcode.tracking.xcode-infoplist-tracking-request, lexcode.tracking.xcprivacy-tracking-domains, lexcode.tracking.xcprivacy-tracking dependency map: 178 entries enable it

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.

$ lexcode deps vercel-chatbot nextjs-subscription-payments obytes-expo full-stack-fastapi bullet-train spring-petclinic nowinandroid symfony-demo wave eshop clean-architecture clean-architecture-swiftui penny-bot zero-to-production realworld-axum-sqlx lexcode deps: 531 packages in 15 repositories; 517 with no activity in the component map repos ecosystem package activities 5 npm react - 5 npm react-dom - 4 npm lucide-react - 4 npm tailwind-merge - 3 npm class-variance-authority - 3 npm clsx - 3 npm tailwindcss - 3 npm zod - 2 cargo anyhow - 2 cargo argon2 - 2 cargo log - 2 cargo rand -

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.

ActivityA reader foundLexCode foundMissed in
aggregates_content20 Now in Android, Penny, Vapor's Discord bot
automated_outreach32 Zero To Production newsletter service
crawls_web10 Penny, Vapor's Discord bot
deploys_chatbot22 none
distributes_software_product52 Now in Android, eShop .NET reference app, Clean Architecture for SwiftUI
generates_content22 none
generates_text22 none
operates_social_platform20 Symfony Demo, RealWorld API on axum and sqlx
processes_personal_data1413 Penny, Vapor's Discord bot
records_text_chat31 eShop .NET reference app, Penny, Vapor's Discord bot
ships_consumer_interface140 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_encryption20 Penny, Vapor's Discord bot, Zero To Production newsletter service
ships_mobile_app44 none
tracks_devices33 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.