Reports

Analysis JSON

The normal JSON report is the compact machine-readable surface for automation. Use it to gate CI or drive cleanup review, then switch to verbose JSON only when you need config and discovery diagnostics.

{
  "issues": {
    "files": { "src/legacy/dead-view.ts": {} },
    "exports": {
      "src/constants.ts": {
        "oldFlag": { "symbol": "oldFlag", "line": 4, "col": 14 }
      }
    },
    "unresolved": {}
  },
  "counters": {
    "files": 1,
    "exports": 1,
    "unresolved": 0,
    "processed": 42,
    "total": 42
  }
}

Doctor Output

Doctor returns a summary, sorted warning list, and sampled unresolved import diagnostics. It exits with findings when warnings or unresolved diagnostics are present, but it never edits files.

{
  "warnings": [
    {
      "code": "entryGlobZeroMatches",
      "message": "entry pattern \"src/app/**/*.tsx\" matched no project files"
    }
  ],
  "summary": {
    "version": "0.4.13",
    "configPath": "codescythe.jsonc",
    "projectCount": 184,
    "entryCount": 2,
    "ignoredUnresolvedCount": 0,
    "ignoredUnresolvedPatterns": ["*.svg?raw"],
    "packageImportKeys": ["#app/*"],
    "configuredAliasKeys": ["#generated/*"]
  }
}

Doctor Warning Codes

Unresolved Diagnostics

Doctor samples unresolved imports and asks the resolver to explain what it tried. Use this section to decide whether an import is a real missing file, an alias mapping gap, or a safe non-source asset.

{
  "unresolvedImports": [
    {
      "importer": "src/routes/home.tsx",
      "specifier": "#generated/client",
      "resolverError": "module not found",
      "matchedAliases": [
        {
          "source": "config",
          "key": "#generated/*",
          "target": "src/generated/*",
          "expandedTarget": "src/generated/client",
          "candidateFiles": [
            {
              "path": "src/generated/client.ts",
              "exists": false,
              "inProject": false
            }
          ]
        }
      ]
    }
  ]
}

• importer is the file that contains the unresolved import.
• specifier is the raw import string.
• matchedAliases shows package or config aliases that looked relevant.
• candidateFiles shows resolver candidates and whether each exists or is inside project scope.

Explain Export Report

Use --explain-export <file>:<symbol> when an export result is surprising. In text mode, Codescythe prints a human-readable explanation. With JSON, the explanation is available under explainExport.

npx codescythe --explain-export src/constants.ts:oldFlag
npx codescythe --json --explain-export src/constants.ts:oldFlag

{
  "explainExport": {
    "exportingFile": "src/constants.ts",
    "symbol": "oldFlag",
    "status": "dead",
    "reason": "export is not used by reachable importers",
    "explanation": {
      "fileReachable": true,
      "importersConsidered": [],
      "importersSkipped": [
        {
          "importer": "src/constants.test.ts",
          "specifier": "./constants",
          "reason": "test file leaf"
        }
      ],
      "ignoredUnresolvedImportsThatMightHavePointedAtThisFile": []
    }
  }
}

Query Output

Query JSON includes the parsed selectors, matched source and target nodes, unresolved imports observed while building the graph, and either paths or a graph depending on the query kind.

{
  "kind": "somepath",
  "from": { "kind": "file", "path": "src/main.ts" },
  "to": { "kind": "export", "path": "src/module.ts", "symbol": "used" },
  "paths": [
    {
      "nodes": [
        { "id": "file:src/main.ts", "kind": "file", "path": "src/main.ts" },
        { "id": "export:src/module.ts:used", "kind": "export", "path": "src/module.ts", "symbol": "used" }
      ],
      "edges": [
        { "kind": "namedImport", "specifier": "./module", "imported": "used" }
      ]
    }
  ]
}

allpaths returns graph.nodes and graph.edges instead of paths. Diagram formats render that same data as Mermaid or SVG.

Review Workflow

1. Start with doctor

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

2. Fix config-risk warnings first

   Zero-match entries, broad project scopes, and source-alias unresolved ignores can all make the main cleanup report less trustworthy.

3. Explain surprising exports

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

4. Only then run fix mode

   A clean doctor report and explain output that matches your expectations give fix mode a much narrower review surface.