Troubleshooting

Start with Doctor

Doctor is built for config triage. Run it before widening project scope or forcing a fix, then read the warning code first and the message second. The code tells you what class of risk Codescythe found; the message names the concrete pattern, count, or file involved.

npx codescythe doctor --config codescythe.jsonc
npx codescythe doctor --json --config codescythe.jsonc

Use the doctor output guide when JSON includes unresolved import diagnostics or alias candidates.

Empty or Tiny Results

If the report is unexpectedly empty, verify that entry and project globs match real files from the same directory root. Verbose mode prints matched entry and project counts.

npx codescythe --verbose --json --config codescythe.jsonc

Unresolved Imports

Unresolved imports can make cleanup unsafe because an unresolved source import may hide real usage. Inspect resolver diagnostics before ignoring broad patterns: candidate files with exists=false usually point to missing generated output or a bad alias target; candidates with exists=true but inProject=false usually mean project scope is too narrow.

"unresolvedImports": {
  "mode": "error",
  "ignore": ["*.svg?raw"]
}

Fix Refused

Fix mode refuses source-like unresolved-import ignore patterns that overlap package imports or configured aliases. Narrow the pattern, fix the resolver issue, or force only after reviewing doctor output.

Surprising Live Code

When a symbol stays live unexpectedly, use export explanations and inspect whether a reachable importer, entry export rule, barrel export, dynamic import, or ignored unresolved import is keeping it reachable.

npx codescythe --explain-export src/module.ts:legacyExport

If JSON reports importersSkipped, those imports were observed but did not count because the importer was unreachable or treated as a test leaf. If ignoredUnresolvedImportsThatMightHavePointedAtThisFile is non-empty, resolve that uncertainty before editing exports.