Skip to content

Dead-code candidates ​

architecture_health (CLI: architecture-health) reports dead_code_candidates alongside its hubs and hotspots: components with no inbound edge among the selected edge kinds. It returns one page of them; knossos dead-code <path|project-id> lists every candidate, with --reachability=unreferenced|test-only to narrow it, and ends with what it left out (annotated, suppressed, reached by convention).

These are candidates, not findings. They rest on what the graph and its evidence can and cannot see. A zero in-degree is only the absence of static evidence: reflection, configuration, templates, registry arrays, callbacks, dispatch tables, and framework conventions all reference code without leaving a statically visible edge. The tool says so in its own warnings, and every candidate carries a reachability, a confidence and a reason.

The summary splits the whole list by confidence, so a count of candidates does not read as that much dead code: By confidence: 14 probable, 29 possible. The same split is in bounds.candidates_probable and bounds.candidates_possible, the test-only count in bounds.candidates_test_only, counted before limit slices the list. knossos dead-code prints each candidate's confidence beside its reachability, ends with the same split, and returns it as by_confidence with --json.

The Issues tab on this repository: the policy violation, diagnostic and dead-code cards, each headed by its count of zero, the complexity hotspots ranked by lines times dependents, and the line budget with no function over 205 lines

In the pane, the Issues tab lists the candidates beside the other findings, the probable ones marked apart from the possible.

Reachability ​

Two components can both be unreachable from anything a user can open and still ask for opposite action, so each candidate says which case it is.

reachabilityMeaningAction
unreferencedNothing references it, tests included.Delete it, once you have ruled out the dynamic dispatch the confidence column warns about.
test_onlyEvery inbound reference comes from code classified as a test.The component and the test guarding it can both go.

Candidates are ordered unreferenced first, then test_only, each by canonical name, so limit slices along the class boundary rather than along the alphabet. The summary names both counts, so a truncated list still says how many test-only findings are waiting behind a higher limit.

test_only is usually the more valuable half. A component nothing references may be waiting on a caller nobody has written yet; one whose own test is its only caller is finished work that no product path reaches, and it still costs review, refactors, and CI time. In a codebase with a thorough test suite, test_only is often the larger half of the list.

Test code is recognised by path: test and fixture directories at a package root (tests, spec, e2e, fixtures), __tests__, __fixtures__ and __mocks__ anywhere, src/test/, Laravel's database/factories/, and the usual test file names. A helper there is test support, so it is never reported, even when nothing calls it.

Passing include_tests asks for test code to count as part of the architecture, which collapses the distinction: nothing is reported as test_only, and a component its test reaches is simply referenced.

Components reached by convention rather than by an edge (controllers, commands, entry points, tool configuration) are excluded rather than given a class of their own. They are counted in bounds.excluded_convention_discovered; see what is excluded below.

Confidence ​

ConfidenceMeaning
probableNo inbound reference, and nothing about the component suggests dynamic dispatch.
possibleNo inbound reference, but the component is reached in ways a scan cannot see: a non-ast origin, a framework role, a member of a type extending an external ancestor whose hooks Knossos does not know, a method of an object literal handed to other code with no type naming its methods, or a method or function sharing its name with a call on a receiver no scanner could type.

A framework base Knossos knows, such as a Laravel FormRequest, Model, JsonResource, migration, factory, seeder, service provider or command, calls a known set of methods on its subclasses by name: rules, toArray, up, definition, handle and the like. Those are excluded as inherited members (counted in bounds.excluded_inherited_methods), and the base hides nothing else, so any other unused method of its subclass is probable. A base not on that list still makes every member of its subtypes possible.

The untyped-call ground is a name match. A JavaScript function taking an untyped parameter, a closure argument in Rust, or a PHP parameter without a declared type calls methods no scan can bind to a declaration. Each scanner lists the names called that way on the file's module node (on the calling declaration in PHP) as unresolved_member_calls, and any method by one of those names drops to possible. That holds even when the call reaches a different class, which is why such a method is not excluded outright.

An object literal passed as an argument, returned, or nested in an array or another literal (filters: [{ name: 'all', func() {} }] handed to a component prop) is called by whatever receives it, and so is one a const binding holds once the binding is handed on the same way. When the TypeScript scanner finds a type for it in the project, that type is its contract and its methods are judged against it; when it finds none, its methods drop to possible. A literal typed only by a library counts as extending an external ancestor.

A PHP class name built at runtime from a namespace literal, new ('App\Cards\' . $command) or the same string held in a variable first, references every class directly in that namespace: any of them may be the one built.

A candidate demoted only by the untyped-call ground is left out of dead_code_candidates and counted in bounds.excluded_untyped_receiver: on a Rust workspace nearly every method name is called on some receiver the scan cannot type, and nearly every such candidate turned out to have a caller. include_untyped_receiver (--include-untyped-receiver) lists them after every other candidate, unreferenced and test_only alike, counted in bounds.candidates_untyped_receiver. Each candidate's reason_code names its ground in a word (framework_role when a framework role may reach it by convention, dynamic_origin when it was found by a fallback rather than the syntax tree, untyped_receiver, shape_contract, uncontracted_literal, external_ancestor, implicit_protocol, or unreferenced/test_only when nothing qualifies it). A Rust inherent method is never demoted for an external trait its type implements: Debug, Drop or Serialize dispatch only to the methods of their own impl block.

The reason field names the ground for three of the cases: an untyped call, an object literal with no contract, and an external ancestor. A demotion for a non-ast origin or a framework role keeps the generic reason, so read origin and roles on the component for those.

What is excluded before reporting ​

Several classes of component have a structurally zero in-degree and would drown the real signal. Each exclusion is counted in bounds so the filtering is auditable rather than invisible.

bounds counterExcluded
excluded_external_componentsHub ranking only: nodes in the examined window resolved outside the project (external_* kinds, external/unresolved origins), left out of hubs and hotspots. Include with include_external. External nodes are never candidates.
excluded_test_componentsHub ranking only: nodes in the examined window classified quality.test_module, left out of hubs and hotspots. Include with include_tests. An unreferenced test module is counted in excluded_convention_discovered, since a runner discovers it by glob.
excluded_inherited_methodsMethods declared by an internal ancestor whose declaration something reaches: the interface or base class carries the contract, and the override is reached through it. An implementation whose every contract is the project's own and reached by nothing is judged on its own callers instead, so one only a test calls is test_only. Also methods a scanner marks overrides (see below), whose supertype may live outside the project.
excluded_contract_methodsThe mirror: declarations an internal implementation carries, when the declaring type is used (see below).
excluded_constructorsEngine-invoked members (constructors, destructors, magic/protocol methods) whose declaring type is referenced (see below), and components a scanner marks runtime_invoked: Rust's Drop::drop, and functions exported to a foreign host (#[no_mangle], #[wasm_bindgen], an extern ABI).
excluded_entry_scriptsModules a scanner marked as executable scripts (a shebang, a __main__ guard, PHP file-scope code, a library crate's root) whose bodies something outside the graph enters, and a Python package's __init__ when the package holds other modules.
excluded_type_declarationsModules and symbols declared in a .d.ts / .d.mts, and declarations inside declare global { } or declare module 'x' { } in any file (see below).
excluded_test_supporttest_only components in a file outside its package's source roots (src, lib, app, source) when that package keeps its product code in one: a scripts/ helper its tests import is test tooling, not dead product code. A test-only component under a source root is still reported. Also code its scanner marks as compiled only for the tests through a test-support feature (Rust's #[cfg(feature = "test-support")]), whether a test reaches it or not.
suppressed_candidatesCanonical names matched by dead_code_suppressions in project configuration.
excluded_convention_discoveredComponents a framework or tool reaches by convention: controllers, commands, jobs, listeners, handlers, migrations and similar framework roles, application.entry_point, library.public_api, test modules and tooling.config (see below).
excluded_example_componentsExample code: files under examples/, example/, samples/ or demo/ outside a package's source roots, or under docs/**/examples/, which the quality.example_module role marks. Nothing imports it by design. include_examples (--include-examples) judges it like any other code. A product component only example or test code reaches is test_only.
annotated_false_positivesComponents carrying a false_positive annotation.
annotated_intentionalComponents carrying an intentional annotation: true findings that are meant, such as a parked route.

Why engine-invoked members are excluded ​

Instantiating a type is recorded as a constructs edge to the class, never to its constructor. Every constructor in every graph therefore has an in-degree of zero, however heavily the class is used. Without the exclusion, a small TypeScript project reports constructors of classes the same graph shows being instantiated.

Constructors are the most common case among several. __destruct runs when the last reference drops, __toString on a string cast, __invoke on a call, and Python's protocol methods (__repr__, __enter__, __eq__) the same way. None is ever written at a call site, so each is structurally unreferenced.

Such a member is excluded when its declaring type has any inbound reference. When the type itself is unreferenced, both stay reportable: the type is the unit worth deleting, and the member goes with it.

Recognised names are constructor (TypeScript/JavaScript) and any member starting with __: the prefix PHP and Python both reserve for engine dispatch, covering __construct, __init__, and every magic or protocol method beside them. Ordinary members of the same type are unaffected.

Why type declarations are excluded ​

A .d.ts describes an implementation that lives elsewhere and emits nothing that runs. Call sites resolve to the .mjs behind it, so every symbol in the declaration file carries an in-degree of zero by construction. Acting on that report would delete the declaration while the implementation stays, breaking every typed call site.

The question worth asking about color-debt.d.mts#measureTree is whether color-debt.mjs#measureTree is used, and that one is reported on its own merits. The scanner marks both the module node and every declaration inside it with declaration_file, and both are excluded.

Why contract declarations are excluded ​

A call edges to an interface method only when its receiver is typed as the interface. foreach ($this->rules as $rule) { $rule->classify($node); } types nothing, so the declaration carries an in-degree of zero while every implementation runs on every scan.

A candidate method is excluded when an internal type that implements or extends the declaring type declares a member of the same name, and the declaring type is used by something other than those implements/extends edges. Being implemented is not evidence that a contract is used, so those edges are discounted; when nothing else references the type, the type and its members all stay reportable, on the same reasoning the constructor exclusion uses: the type is the unit worth deleting.

This is the mirror of excluded_inherited_methods, which drops the override on the grounds that the ancestor carries the contract. Together they report a hierarchy once, through whichever end is genuinely unreachable.

The override may also be inherited rather than written: a trait's method, or a base class's, fulfils an interface that the using or extending class declares without redeclaring the method. A call through the interface reaches that method, so it counts under excluded_inherited_methods too, as long as some subtype that does not override it has an internal ancestor, outside the method's own hierarchy, declaring a member of that name.

A supertype that lives outside the project (a dependency's base class, a built-in interface, a trait from a crate) has no members in the graph, so the walk above cannot find the contract. The scanners mark such a method overrides instead, where the source or the language says so: every method of a Rust impl Trait for T; a PHP #[\Override] method, or a member of a PHP built-in class or interface the type extends or implements (jsonSerialize, count); a Python @override method (from typing or typing_extensions), or an ast.NodeVisitor/NodeTransformer subclass's visit, generic_visit and visit_<Node> hooks, which the visitor dispatches to by name; a PHP class extending PhpParser\NodeVisitorAbstract or implementing PhpParser\NodeVisitor, whose beforeTraverse, enterNode, leaveNode and afterTraverse hooks the traverser calls, with or without #[\Override]; a TypeScript override method, an instance method the checker finds on a heritage type, and an object literal's method the type it is handed to declares. A marked method counts under excluded_inherited_methods. A dependency's PHP base class is not described by anything the worker can read, so its overrides need the attribute.

Why manifest entry points are excluded ​

npm run build invokes scripts/build.mjs by name, and Composer invokes bin/console the same way. Nothing in the project imports either, so both carry an in-degree of zero however central they are.

Discovery reads each package.json and composer.json for the paths it names as bin, main/module, and scripts (and, for a package depending on react-scripts, the src/index Create React App builds from), and each Azure Functions function.json for its scriptFile, anchored to the manifest's own directory so a monorepo package resolves correctly. Script values are shell commands, so they are tokenised and only tokens shaped like a source file are kept. That tokenising is loose on purpose: matching is by exact project-relative path, so a token naming something no scanner emitted never matches anything. Files that do match are classified application.entry_point (rule core.manifest.entrypoints.v1).

Discovery also reads every .html file for the scripts it loads (see below), every other .md file for what a VitePress or VuePress page's scripts import (see below), every README for the paths it hands to an interpreter (node scripts/x.mjs, python3 tools/y.py), every .yml/.yaml and .neon file, Dockerfile and shell script (.sh, .bash) for tokens shaped like a source path, and every tool config module for the keys naming files the tool loads. A shell script's path is also read from the directory a cd before it on the same line names, or a cd on a line of its own until its case branch or block ends, so cd server && npx tsx src/reset.ts names server/src/reset.ts. In a Dockerfile, a path a COPY put in the image (python3 /tmp/probe/check.py after COPY scripts/probe /tmp/probe) is read as the file it was copied from. A single-page application is entered through its HTML shell, a Compose file mounts a config by path, and Vitest loads setupFiles before every test; none of those is an import, so each named file carried an in-degree of zero while being the reason the thing runs. YAML is tokenised as text rather than parsed. That is loose on purpose and safe for the same reason the Composer script tokenising is: a token that names no file any scanner emitted matches nothing. A tool config is the exception and is read key by key, because it names files to exclude as well as files to load, and an excluded path is exactly the kind that turns out to be dead. Its keys include Vite's ssr, Cypress's pluginsFile and supportFile (and their defaults, from cypress.json), and TypeORM's migrations, entities and subscribers, whose globs are matched against the discovered files; webpack.mix.js names its entries as mix.js('resources/js/app.js', ...).

function.json earns its place for a second reason. A handler directory holding both index.js and a stale index.ts resolves the wrong way: asked where a sibling's require('../management') points, TypeScript's own module resolution answers with the .ts, so the fossil absorbs the dependency and the handler the host actually executes is left looking dead. The manifest settles which of the two runs on the runtime's authority rather than the type checker's.

A script the manifest does not name stays reportable, which is the useful signal: a developer tool wired into nothing.

How an HTML page's scripts are resolved ​

A browser front end is entered from its page, and nothing in the project imports the module the page loads. Discovery reads each .html and .htm file in the scan for every local script it loads:

  • <script src="...">, classic or type="module", in any quoting and case;
  • <link rel="modulepreload" href="...">;
  • in an inline <script>, import ... from "...", import "...", export ... from "..." and import("..."), where a template literal counts by its text before the first ${, so import(`/static/app.mjs${location.search}`) loads /static/app.mjs.

A script tag inside an HTML comment, inside a <template>, <textarea>, <title>, <xmp>, <noscript>, <style>, <iframe>, <noembed> or <noframes>, or anywhere after <plaintext>, a custom element such as <script-loader>, and an import inside a string or comment of an inline script, load nothing. The query and fragment are dropped. Remote URLs, data: and blob: URLs, package names such as react, and files no scanner reads (.css, .json) are ignored without a word.

Each reference then has to name exactly one scanned file:

  • A relative URL (app.mjs, ./app.mjs, ../lib/x.js) is read from the page's folder.
  • A root URL (/static/app.mjs) is read through web_roots when one of its prefixes matches, and never any other way then.
  • Otherwise a root URL is looked for in the page's folder without its first segment, so /static/app.mjs from web/public/index.html finds web/public/app.mjs when a server mounts that folder at /static/. The full path is looked for under the page's folder, each folder above it up to the project root, and the public/ and static/ folders in each. The first segment is dropped beside the page only, so /assets/main.js from apps/admin/index.html never lands on an unrelated main.js higher up.
  • A .. in the URL is applied first, so /static/../x.js is /x.js and cannot climb out of a mapped folder.
  • A page that loads tsc output (main.js beside main.ts, which the scan leaves out) names the TypeScript source.

A file found this way is classified application.entry_point with the page as named_by, so it and everything only it reaches stop being candidates. A module that file loads with import(`./draw.mjs${query}`) is reached too: the TypeScript worker follows a template literal by its text before the first ${, without any ? or # part, when that text is a relative path ending in a file name. It names that exact file, or, for a .js, .jsx, .mjs or .cjs name, the TypeScript source it is built from when one exists, as a string specifier would; and it leaves `./${name}.mjs` and an absolute `/x.mjs${q}` unresolved. When no file matches, or more than one does, nothing is guessed: the reference adds no entry point and the scan reports a warning naming the page, the line, the URL and the reason, with code DISCOVERY_HTML_SCRIPT_UNRESOLVED or DISCOVERY_HTML_SCRIPT_AMBIGUOUS. To settle an ambiguous one, map its URL prefix to a folder with web_roots. A warning never fails a scan, and a quality gate counts it under warning_diagnostics, not error_diagnostics.

How a VitePress or VuePress page's scripts are resolved ​

VitePress and VuePress compile each markdown page into a Vue component, so a <script setup> in a page is that component's script, and the components it imports and renders are reached through the page alone. Discovery reads every .md file for the imports of its <script> blocks, read as an inline HTML script is. A block counts where markdown reads it as HTML: at the start of a line, indented by at most three spaces, outside a fenced code block and an HTML comment. A script shown in a fence, an indented code block or an inline code span loads nothing.

Those imports become entry points only for a page inside a site: below the directory holding .vitepress/config.* or .vuepress/config.*. Elsewhere a markdown file is plain text and adds nothing. Within a site:

  • A relative path (./Card.vue, ../../.vitepress/theme/components/Card.vue) is read from the page's folder.
  • In VitePress, @theme/x is read from the site's .vitepress/theme/.
  • A path that names no file is completed as Vite completes it: with .vue, .ts, .mts, .tsx, .js, .mjs or .jsx, or as a folder's index.ts or index.js.
  • A package name (vue, vitepress) and a path that names no scanned file add nothing, and no warning: Vite fails the build on a broken one.

A file found this way is classified application.entry_point with the page as named_by.

Why tool configuration is excluded ​

ESLint reads eslint.config.js, Vitest reads vitest.config.ts, pytest reads conftest.py: the tool finds each by filename and no project code imports it, so its in-degree is zero in every project. Without the exclusion, a small TypeScript project reports its own tool configuration as candidates.

Such modules are classified tooling.config (rule core.tooling.config.v1) and, like test modules, are not reported. Recognition is by filename convention only (<tool>.config.<ext>, <tool>.conf.<ext>, an rc dotfile, gulpfile, gruntfile, or conftest.py) and deliberately narrow: a module that merely reads configuration, such as src/utils/config-loader.ts, is ordinary source and stays reportable.

Why a published library's API is excluded ​

A package other projects install is called by code outside the repository, so nothing inside has to call its public API for that API to be wanted. Such components are classified library.public_api and not reported:

  • a JavaScript or TypeScript package that is not private and names an entry (main, exports): what that entry exports and re-exports. An entry in a tsconfig's outDir stands for the source under its rootDir; with no tsconfig laying the build out, an entry in dist/, build/, lib/ or out/ stands for the same path under src/;
  • a Composer package whose composer.json says "type": "library": the classes, interfaces, traits and enums under its autoload PSR-4 roots, and their public and protected methods. Composer's default type is library, but an application that never names its type is the common case, so only an explicit one counts;
  • a Python project whose pyproject.toml has a [build-system] and [project] (or Poetry's table) and installs no command ([project.scripts], [project.gui-scripts], [tool.poetry.scripts]): every module, class, function and method under its directory whose name has no segment made private by a leading underscore. A dunder counts as public.

What a library keeps private stays reportable, and so do its tests.

A module and what its file declares ​

A module is used when something outside its file reaches what the file declares, also a declaration it makes for a container elsewhere: a Rust file holding only impl BrokerState { .. } for its parent's type contains nothing itself, but the methods it adds are called.

Methods the runtime calls ​

A method a JavaScript runtime calls with no call site naming it is at most a possible candidate, whatever its class extends, and its reason says so: toJSON (JSON.stringify), toString, valueOf and [Symbol.toPrimitive] (conversion), then (await), [Symbol.iterator] and [Symbol.asyncIterator] (for ... of), [Symbol.dispose] and [Symbol.asyncDispose] (using), and inspect (Node's util.inspect).

Filtering and paging ​

A large project can have hundreds of candidates, and a framework's lifecycle methods, marked possible, can fill the first page. candidate_confidence: "probable" (CLI: --candidate-confidence=probable) reports only the stronger claims, and candidate_offset (--candidate-offset=N) pages past the first page. candidates_only (--candidates-only) answers with the candidates alone, each as component, kind, path, line, reachability, confidence and reason_code, with no hubs or hotspots computed or sent, and lets candidate_limit go to 1000: one call lists what took several full pages.

candidate_limit (--candidate-limit=N) sets how many candidates a page lists, up to 100; left at 0 it is limit, which then sizes only the hubs and hotspots, so a page of 100 candidates no longer brings 100 hubs and 100 hotspots with it. pagination.next_offset is where the next page starts, null on the last one. Over MCP, an answer cut to fit max_chars trims the hubs, hotspots and other lists first and the candidates last, and pagination.next_offset then points at the first candidate it left out, so paging by it skips none. bounds.candidates_total says how many there are after the filter. Each candidate carries the path and line it is declared at.

path_prefix (--path-prefix=PATH) lists only the candidates under one project-relative path, and the candidate counts then describe that part. A test_only candidate carries test_reference, the first test reference to it by path and line, and test_reference_count; a container whose members only tests use has no reference of its own, so its count is 0. include_annotated (--include-annotated) also lists the candidates a false_positive or intentional annotation hid, each with its annotation and hidden_by_annotation: true, still counted under the annotation.

Scope and budget ​

Candidates are found over the whole project. max_nodes, max_edges and timeout_ms bound the hub and hotspot ranking only, and nodes_examined, edges_examined, truncated and truncation_reasons describe that ranking.

The candidate list reports its own truncation in bounds.candidates_truncated and bounds.candidate_truncation_reasons:

  • result_limit: more candidates follow the page. candidate_offset pages past it.
  • time_limit: the candidate search ran out of its own budget, candidate_timeout_ms (CLI: --candidate-timeout), default 5000 and at most 60000. The result holds the candidates classified so far, and candidates_total counts what was classified.

Acting on a candidate ​

  • Confirm it is genuinely unused, then delete it.
  • Record confirmed_dead with annotate_component when a human or agent has verified it but the deletion is not yet scheduled.
  • Record false_positive when the component is reached in a way the scan cannot see. It is dropped from future candidate lists and the count moves to bounds.annotated_false_positives. On a module or a class it covers every member too, unless a member carries an annotation of its own.
  • Record intentional when the finding is true and meant: a route parked on purpose, a helper only tests use by design. It is dropped from future candidate lists and counted under bounds.annotated_intentional, and covers the members of a module or class the same way. confirmed_dead judges only the component it is on.
  • Use dead_code_suppressions for whole families of such components (a generated namespace, a plugin directory) rather than annotating each one.

Limits ​

  • Candidates depend on the selected edge_kinds and min_confidence. Narrowing either produces more candidates.
  • The candidate search is bounded by candidate_timeout_ms alone; a search cut short reports time_limit among candidate_truncation_reasons, and its candidate list is partial. max_nodes, max_edges and timeout_ms bound the hub ranking only.
  • limit caps the reported list. The candidate counters in bounds describe the whole project; excluded_external_components and excluded_test_components describe the hub ranking's window. None describe only the reported slice.
  • A reference from a non-code file suppresses the candidate but contributes no edge, so list_usages will not name the HTML shell, the Compose file or the tool config as a dependant. The claiming file is recorded on the role as named_by.
  • A tool config is read only for the keys that name files it loads (setupFiles, globalSetup, entry, and their siblings), and for files a key maps to through a path anchored to the config (replacement: resolve(__dirname, 'visual/stubs.tsx') in a bundler alias, or new URL('./stub.ts', import.meta.url)). A path reached some other way (built from a variable, or under a key not on that list) is still invisible.