basta

basta

Find dead code: unused files, exports, declarations and imports across JavaScript, TypeScript, Vue, Svelte, Astro and Python, and Rust through the compiler's own diagnostics.

basta builds the import graph from a project's entry points, walks it, and reports what it never reaches. It ships as its own basta command and inside jscpd as jscpd --dead-code.

basta src

Unused files (1)
 - src/legacy-export.ts  certain 95%  11 lines

Unused exports (1)
 - function src/invoice.ts:21:17 renderReceipt  high 85%  3 lines

Unused symbols (1)
 - function src/invoice.ts:29:10 describeTotal  certain 90%  3 lines

Unused imports (1)
 - import src/invoice.ts:2:10 roundToCents  certain 100%  1 lines

Found 4 dead code findings in 4 files (31.6% of 57 lines).
Done in 12ms

What makes it different

It is a traversal, not a reference count. A helper whose only caller is itself dead is reported too. That cascade is most of what a reference-counting linter misses.

It tells you how sure it is. Static analysis of JavaScript and Python cannot be certain, so every finding carries a score from 0 to 100 and the reasons it is not higher — a file that calls eval or getattr, an unrecognised decorator, a wildcard re-export, a name that shows up in a string literal, a file whose path is written out in one. --min-confidence sets the floor; the default is 60.

It reads components, not just scripts. A .vue, .svelte or .astro file is a module wrapped in markup, and the markup is where a component's imports are actually used. basta reads both halves, so <Foo /> counts as the use of import Foo from './Foo.vue' — kebab-case spellings, {{ … }} interpolations, Svelte actions and attribute expressions included. A tool that stops at </script> does not merely miss findings here; it reports every component import in the project as dead.

It knows the conventions. A package's __init__.py re-exports are its API, not unused imports. from __future__ import annotations is a directive, not a binding. # noqa: F401 and PEP 484's import x as x mean a deliberate re-export. A package.json pointing at dist/index.js means src/index.ts. CommonJS counts: require('./x'), module.exports = { a } and a literal import('./x') are edges like any import. A shell script or CI workflow that names a source file keeps it alive.

Usage

basta [PATHS]...

  --categories <LIST>        unused-file, unused-export, unused-symbol,
                             unused-import, unused-member, or `all`
  --min-confidence <N>       drop findings below this score (default: 60)
  --entry <GLOB>             treat matching files as entry points (repeatable)
  -c, --config <FILE>        jscpd config to read the dead-code section from
                             (default: .jscpd.json, .config/jscpd.json,
                             package.json)
  --rust-diagnostics <FILE>  Rust dead code from `cargo check
                             --message-format=json`; `-` reads stdin
  --frameworks-config <FILE> framework definitions to add, YAML or JSON
                             (default: basta.frameworks.{yaml,yml,json})
  --framework <NAME>         take this framework as present (repeatable)
  --no-frameworks            do not detect frameworks
  --ignore <GLOB>            skip matching files (repeatable)
  --include-tests            report dead code inside test files
  --include-entry-exports    report exports of entry points
  --min-lines <N>            only report declarations this many lines or longer
  -r, --reporters <LIST>     console, json, sarif, html, markdown, csv, xml,
                             codeclimate, openmetrics, badge, xcode, ai, silent
  -o, --output <DIR>         where file reporters write (default: report)
  --threshold <PERCENT>      fail when dead code exceeds this share
  --exit-code <CODE>         exit with this code when anything is found
  --format <FORMAT>          restrict the scan (repeatable)
  --list                     print the formats basta analyzes
  --list-frameworks          print the frameworks basta recognises

Entry points

Every finding is the answer to nothing reaches this, so the entry points are the whole basis of the result. basta finds them from package.json (main, module, bin, exports, files, scripts), pyproject.toml ([project.scripts] and entry-point tables), scripts in the tree (*.sh, CI workflows, Makefiles, Dockerfiles) that name a source file, and conventions: src/index.ts, __main__.py, manage.py, framework routes under pages/ and app/, *.config.ts, .d.ts declarations, shebangs, if __name__ == "__main__", every __init__.py, and the file-system routes of the component frameworks — pages/, layouts/, src/routes/, app.vue, error.vue.

When a project does something none of that covers, say so once:

basta src --entry 'src/handlers/**' --entry 'scripts/*.ts'

It reads the project's own build. resolve.alias from vite.config.*, kit.alias and $lib from SvelteKit, paths from tsconfig.json, and — in a monorepo — every workspace package's name, so @acme/ui/date reaches the file that package's exports names. A specifier computed over a directory (import(`./locales/${l}.json`), import.meta.glob('./lang/**/*.ts')) is expanded to the files its pattern matches, the way a bundler expands it; a literal import('./x.svelte') in a component's markup and the imports of an Astro client <script> are edges like any other.

Some aliases come with a framework. With a wxt.config.ts in the project, @ and ~ mean WXT's srcDir, and @@ and ~~ mean the project root. WXT declares them only in the generated .wxt/tsconfig.json, which no repository commits, so basta supplies them itself. When no config declares ~/x, @/x or ~~/x, basta resolves them from the project root. That is what they mean in Nuxt, whose alias table is generated into .nuxt/ and never scanned.

Frameworks

A framework runs files that nothing imports. A router turns the files in pages/ into URLs. A runtime loads everything in plugins/. basta works out which frameworks a project uses and keeps the files they load out of the report.

It knows Next.js, Nuxt, Nitro, WXT, Plasmo, Remix, React Router, SvelteKit, Astro, SolidStart, TanStack Start, Qwik City, Gatsby, Angular, NestJS, AdonisJS, Strapi, Medusa, Ember, Quasar, React Native, Expo, Cloudflare Workers, Vercel, Netlify, Serverless, Docusaurus, VitePress, Eleventy, Storybook, Jest, Vitest, Playwright, Cypress, Prisma, Knex and TypeORM. On the Python side it knows Django, Alembic and Scrapy. Run basta --list-frameworks to see all of them, with the signs basta uses to detect each one.

A framework counts as present when basta finds any one of these:

• its config file, by name (next.config.mjs, wxt.config.ts, .storybook/main.ts);
• its package among the dependencies in package.json, in any of the dependency tables;
• its section in package.json ("jest": {…}).

basta looks in every directory that holds a scanned file, so each package of a monorepo is treated as its own project. Most projects use more than one framework. All the frameworks that match apply at the same time, and each one keeps its own files alive.

If the framework's config is a JavaScript or TypeScript file, basta reads the plain values that move directories around: srcDir, entrypointsDir, appDirectory and imports: false. It reads a JSON config such as nest-cli.json the same way. The console report lists what was detected above the findings, for example Frameworks: next (apps/web), vitest.

The list of frameworks is a data file, frameworks.yaml, built into the binary. You can add a framework basta does not know, or replace a built-in one that has the same name, with a file of the same shape:

# basta.frameworks.yaml — or .yml / .json, or --frameworks-config <file>
frameworks:
  - name: kiosk-router
    detect:
      configFiles: ["kiosk.config.{js,ts}"]
      dependencies: ["@acme/kiosk-router"]
      packageJsonKeys: [kioskRouter]
    variables:
      screensDir: screens            # read from the config file, else this
    bases: [".", "src"]
    entry: ["${screensDir}/**/*.screen.{js,ts}"]
    directories: [plugins]           # loaded whole
    autoImports:
      disabledBy: imports            # `imports: false` turns these off
      directories: [composables]
    globals:                         # names the framework reads: always used
      - onKioskBoot                  # …in any file of the project
      - names: [guard, title]        # …or only in the files it reads them from
        files: ["${screensDir}/**/*.screen.{js,ts}"]

globals are the names a framework looks up in your code. Examples are Next's getServerSideProps and generateMetadata, Remix's loader and action, SvelteKit's load, Angular's ngOnInit and a Pages Function's onRequestGet. No file in the project mentions these names, so basta treats a declaration with such a name as used. It never reports it, and everything that declaration calls stays reachable. The built-in list has these names for the frameworks that need them, limited to the files each framework reads them from.

Use --framework next when the scan starts below the package.json that names the framework, as in basta src --framework next. basta then treats the framework as present. --no-frameworks turns detection off, and entry points then come only from manifests, conventions and --entry.

Rust

basta does not parse Rust. The compiler already finds unused code and prints it on every build, for example function reprint is never used. It has real name resolution, trait dispatch and macro expansion, which no scan of the source could match, so basta reads the compiler's output instead:

cargo check --all-targets --message-format=json | basta . --rust-diagnostics -

Or from a file, which lets CI reuse a check it already runs:

cargo check --all-targets --message-format=json > target/check.json
basta . --rust-diagnostics target/check.json

basta never runs cargo itself. Running it would execute the project's build scripts and procedural macros, and everything else basta does is safe to run on a repository nobody has read.

The findings go through the same categories, reporters and --min-confidence as every other language, at 100% confidence. dead_code on a function, struct, enum, constant or trait is an unused symbol. On a method, field or variant it is an unused member. unused_imports is an unused import. The compiler's span covers only the name, so basta reads each item's real size from the source.

Test code is handled the same way as in every other language. The compiler says which target a diagnostic came from, and cargo check --all-targets checks the test harness too. A finding from a test target is reported only with --include-tests, at 85% rather than 100%, because a test helper is often kept for the next test.

basta reports only what the compiler reports. A pub item of a library is never reported, because a crate outside the workspace may use it. Code that only exists under a feature or target the check did not build is reported as dead, because for that build it is, so check with the features and targets you ship. #[allow(dead_code)] hides an item from cargo and so from basta. RUSTFLAGS="--force-warn dead_code" shows it anyway.

The file can also be named in the configuration file as rustDiagnostics, which is how jscpd --dead-code reads it.

Configuration file

Flags apply to one run. Settings a project always wants belong in its jscpd config, under deadCode. The key can also be spelled dead-code or basta.

basta reads the file you pass with --config. Without that flag it looks in the working directory for .jscpd.json, then .config/jscpd.json, then the jscpd key of package.json. jscpd --dead-code reads the same file, so the two tools give the same result.

{
  "threshold": 10,
  "deadCode": {
    "minConfidence": 80,
    "categories": ["unused-file", "unused-export", "unused-symbol", "unused-import"],
    "minLines": 0,
    "entry": ["tools/*.js"],
    "ignore": ["**/generated/**"],
    "includeTests": false,
    "includeEntryExports": false,
    "threshold": 5,
    "framework": ["next"],
    "noFrameworks": false,
    "frameworksConfig": "tools/frameworks.yaml",
    "rustDiagnostics": "target/check.json",
    "frameworks": [
      {
        "name": "job-runner",
        "detect": { "packageJsonKeys": ["jobRunner"] },
        "entry": ["jobs/**/*.job.js"],
        "globals": [{ "names": ["schedule"], "files": ["jobs/**/*.job.js"] }]
      }
    ]
  }
}

A flag wins over the same setting in the section. A list given on the command line replaces the list in the section and does not add to it.

frameworks holds definitions inline, in the same shape as basta.frameworks.yaml. They are applied last, so they win over a definitions file. threshold is the limit for dead code only. The top-level threshold next to it is the limit for duplication. enabled matters to jscpd, which has other modes to choose between, and basta ignores it.

A misspelled key stops the run when you named the file with --config. For a file basta found by itself, it prints a warning and ignores the section.

Adding a language

One file under src/lang/ implementing Analyzer, and one line in the ANALYZERS registry. The trait is the only place a language is allowed to be special: it parses one file into declarations, imports and references, resolves that language's specifiers against the index of scanned modules, and declares its entry-point conventions, manifests and path traits. The walker, the graph, the confidence model, the classifier, the reporters and both CLIs are language-agnostic and pick the new language up from the registry.

docs/basta-extending.md is the walk-through: how a run works, the contract an analyzer has to honour (each rule there was a real false positive once), a worked skeleton, and how to prove a new language right against real projects.

License

MIT