Lintora

Code governance engine — AST-based pattern matching for JS/TS.

Installation

npm install @lintora/core

Local monorepo (contributors): CLI without npx or extra env

From packages/js after a normal install and build, use npm run cli so you never depend on npx shims or node_modules/.bin/lintora quirks:

cd packages/js
npm ci
npm run build
npm run cli -- login

npm run build runs prebuild, which writes .cache/baked-dev-define.json and embeds the same hosted Lintora defaults as the published package (Supabase URL, license-check URL, web origin, publishable anon key). Anon resolution order:

1. Environment variable LINTORA_BUILD_DEFAULT_SUPABASE_ANON_KEY (optional one-time export).
2. SKIP_DEV_BAKED_DEFAULTS=1 — placeholder only (used by CI for sourcemap artifacts; that dist is not meant for live CLI).
3. Otherwise supabase projects api-keys using ../../supabase/.temp/project-ref (requires supabase link + supabase login on your machine).

If prebuild fails, it prints the exact recovery steps (export anon, or link CLI, or skip for CI).

How to use (CLI)

1. Config (optional). In the project root you may create a config file. If you do not, the default config below is used (no error).
   • Create lintora.config.json in the project root (empty {} is enough).
   • Optional fields: rootDir, include, exclude, enableTypeAwareAnalysis, maxConcurrentFiles.
2. Full ARC coverage (recommended): For the complete ARC rule set including type-aware policies ARC-002-013, ARC-002-014, ARC-002-015, ARC-002-016 (nullable checks via TypeScript), set "enableTypeAwareAnalysis": true in your config. If this flag is false or omitted, those four policies report no violations by design (no type checker in RunContext). See DOCS/analiz/41-ARC-STATIK-SOUNDNESS-FP-CONTRACT.md (ARC-R2). Example file: packages/js/lintora.config.example.json (repo root path from this package: lintora.config.example.json in this directory).
3. Minimal path (same for every user): sign in once (npm run cli -- login from packages/js after npm run build), then go to your app repo root in the shell and run:

   npm run cli -- run

   when @lintora/core is installed there, or from the monorepo call the built CLI with an explicit root:

   cd /path/to/packages/js
   npm run cli -- run --cwd /path/to/your/app

   Default: --cwd is optional; if you omit it, the scan root is process.cwd() (the directory your terminal is in). Use --cwd only when you cannot cd into the project first (CI matrix, parent-folder workflow, or a sandbox). Legacy equivalents: npx lintora run / npx lintora run --cwd /path/to/your/repo. Multiple Lintora accounts on one OS user: set LINTORA_HOME to a separate directory (absolute path, path relative to cwd, or ~/...) before lintora login and each lintora run so credentials do not overwrite each other; default is ~/.lintora/. Run lintora logout to clear the active directory only. After browser lintora login: the CLI writes only the new install key (drops any previous saved access token), clears the on-disk license cache and rate-limit warn file, and warns when LINTORA_INSTALL_KEY in the shell differs from the saved key (local runs prefer credentials.json first so a stale export cannot undo a fresh login; CI prefers LINTORA_INSTALL_KEY). In a TTY, lintora run can open the same re-bind flow once when the server reports the workstation key was replaced; CI stays non-interactive (LINTORA_INSTALL_KEY or a prior successful login on that runner). Relative paths in config and reports resolve from that scan root. loadConfig searches upward from the scan root for lintora.config.json. By default the CLI prints a short English scan summary (counts by severity) plus hub guidance — not a policy-by-policy breakdown. Set LINTORA_WEB_ORIGIN if your hub host differs from https://www.lintora.dev. For the full policy findings list in the terminal (same as older CLI behavior), pass --show-findings or set LINTORA_SHOW_FINDINGS=1 (that mode still prints the detailed multiline Summary after the findings). Or: npm exec lintora run. For a complete plain-text violation list on disk (avoids truncated tee / terminal capture), add --violations-log reports/violations-full.txt to run (writes every finding, no ANSI; section labels are English, e.g. Affected locations:). For an English-only Markdown summary that embeds that log, from the repository root run node scripts/generate-lintora-markdown-from-lossless-json.mjs --json <report.json> --violations-txt <violations.txt> --out <report.md> [--project-name "..."] (see scripts/generate-lintora-markdown-from-lossless-json.mjs).
4. File discovery is automatic: the engine walks the entire rootDir tree (not only src/ or backend/) and collects every path that matches include and does not match exclude (glob). You do not pass file paths by hand.
5. When no config file is found: The default config is used: rootDir = current working directory (or the directory passed with --cwd), include = ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts", "**/*.js", "**/*.jsx", "**/*.mjs", "**/*.cjs"], exclude = ["node_modules/**", "dist/**", "build/**", "out/**", ".next/**", "coverage/**", ".expo/**", ".git/**", "ios/Pods/**", "android/.gradle/**"]. Those paths (plus Pods and .gradle directory trees during the walk) are not scanned by default. This is documented default behaviour, not a silent fallback.
6. Parse / JSX: The engine passes jsx: true for .tsx, .jsx, .js, .mjs, and .cjs when JSX may appear. Plain .ts, .mts, and .cts use jsx: false so valid generic arrows like <T>(x) => x are not misread as JSX. Prefer .tsx for new TypeScript + JSX code.
7. When the config file is invalid (e.g. bad JSON or schema mismatch): The CLI prints an error and exits with code 1. Solution: fix the config file to match the schema (see types or docs).

Publish a scan to your account on lintora.dev

Per-user storage uses the same Supabase project as Auth for lintora-web. Apply migration supabase/migrations/20260504120000_lintora_scans_and_pending.sql once (supabase db push or SQL Editor).

Default handoff: after lintora login on your machine, npx lintora run uploads the lossless report to your hub when hub env vars are set and LINTORA_HUB_PUBLISH is not 0 (no deprecated run --web-publish flag needed; that flag is ignored).

Open the hub after a run with a report file:

npx lintora run --report-path ./lintora-report.json --web-open

--web-open launches your default browser to the hub URL after upload. If you are already signed in to lintora.dev, the scan lands in My hub without pasting JSON in the browser.

Two-step variant (existing file): npx lintora web publish --report-path ./lintora-report.json --open (or without --open, copy the printed URL).

CI / headless (no browser login): set the same LINTORA_INSTALL_KEY you use for license checks (from lintora login / dashboard install key). With hub env vars set, lintora run uploads via import_lossless_scan_with_install_key (apply migration 20260508100000_import_lossless_scan_with_install_key.sql). Precedence: in CI, LINTORA_INSTALL_KEY wins over ~/.lintora/credentials.json when both are set; on a normal workstation, the saved key from lintora login wins so a leftover env export does not override it.

Opt-out: set LINTORA_HUB_PUBLISH=0 before lintora run to skip every hub upload attempt for that process (local --report-path output still works). Default is upload enabled when hub env vars and publish flow apply.

What the lossless JSON contains (schema lintora.lossless-report.v1; see packages/js/src/types/lossless-report.ts):

• schemaVersion, generatedAtUtc, runFingerprint (deterministic id for the run scope).
• context.cwd (absolute project path), context.format, context.policy, context.reportOn.
• summary: violation counts, severity and policy breakdowns.
• output.errors and output.violations (each violation may include absolute file paths; source code snippets are not embedded).

Paths may reveal monorepo layout or internal directory names; review before sharing exports outside your team.

Usage (API)

Use runCli() for the full default policy set, or build a registry and pass it to Engine:

import { runCli } from '@lintora/core';

await runCli(process.argv);

For programmatic use with config: loadConfig({ cwd }) returns the config (or default when no file is found); pass it to engine.run(config).

API

See types exported from @lintora/core and @lintora/core/types.

Maintainers (release)

1. Add a changeset after user-facing changes: cd packages/js && npx changeset, commit .changeset/*.md, open PR to main.
2. Merge the Version packages PR opened by GitHub Actions (changesets-version-pr.yml).
3. On main, run Tag release from package.json (workflow_dispatch in Actions) or tag manually so v + package.json version matches exactly (triggers release.yml).
4. Optional cold-start sample after npm run build: npm run bench:cold-cli.

Details: packages/js/.changeset/README.md and DOCS/NPM-PUBLISH-VE-OBFUSCATION-PLAN.md (section 5.4).

License

MIT