Skip to content

feat(graph): resolve TypeScript tsconfig path aliases - #867

Open
nguyenduyhung1989 wants to merge 1 commit into
trailhq:mainfrom
nguyenduyhung1989:fix/tsconfig-paths-resolution
Open

nguyenduyhung1989 wants to merge 1 commit into
trailhq:mainfrom
nguyenduyhung1989:fix/tsconfig-paths-resolution

Conversation

@nguyenduyhung1989

Copy link
Copy Markdown
Contributor

Problem

resolveImport only follows specifiers that start with .. Anything else is treated as an external package. In a TypeScript repo that imports through tsconfig aliases (@/x, @core/x, or a baseUrl-relative core/x), every such import stays an unresolved string, so no call or reference edge is drawn to the real file.

The failure is silent. graft callers and graft blast return a short, confident list, the hub ranking in graft map favours code that happens to use relative imports, and the coupling-based ranking in graft ask loses the edges that matter most.

Change

  • src/graph/ts-paths.ts (new): reads every tsconfig.json, tsconfig.*.json and jsconfig.json once per build from the same repoFiles walk the rest of the build uses. Handles JSONC (comments, trailing commas), relative extends chains (also arrays), baseUrl, and paths with an exact key or a single * (longest prefix wins, several targets tried in order). A config applies only to importers under its own directory; nearest directory first, then tsconfig.json, then the other configs by name. include and exclude are deliberately ignored, graph membership still comes from graft's file walk.
  • src/graph/build.ts: passes the compiled aliases to resolveEdges, the same way readGoModules feeds goModules.
  • src/graph/resolve.ts: non-relative specifiers from JS/TS-family importers (.ts .tsx .mts .cts .js .jsx .mjs .cjs .vue .svelte .astro) go through the aliases. The candidate order (exact, extension swap, /index.*) is now one helper shared with relative imports, and relative behaviour is unchanged. Python importers are untouched.

An alias that does not land on an indexed file stays unresolved, exactly as today, so the change cannot invent an edge.

Evidence

Measured on a 2,100-file TypeScript repo (backend and frontend tsconfig both define paths). For 7 exported symbols, the "truth" is every file that mentions the symbol on a non-comment line, excluding the defining file (410 files in total). graft callers <symbol> --depth 1:

files found recall precision
before 15 / 410 4% 100%
build --lsp (typescript-language-server) 311 / 410 76% 100%
this change 399 / 410 97% 100%

The remaining misses are barrel files (export { x } from './y'), which graft records as an import but not as a reference to the symbol. That is a separate question and this PR does not touch it.

For six plain-language "where is X" questions, the expected file was ranked first for 6 of 6 (5 of 6 before). A full build took the same time as before (about 27 s on this repo); --lsp took 2 min 54 s.

Tests

test/graph-resolve-ts-paths.test.ts (11 tests): wildcard alias to a directory index, exact and prefix*suffix aliases, longest prefix wins, baseUrl only (an unknown bare specifier such as react stays external), paths without baseUrl, an extends chain with a child overriding paths, JSONC, monorepo scoping with two configs defining @/* differently, several targets (first existing wins), Python importers and relative specifiers unchanged, an alias to a missing file stays unresolved, and an end-to-end buildGraph check that incoming calls edges appear for an aliased import. Written red first (8 of the new tests failed before the change).

tsc --noEmit is clean, and all test/graph-*.test.ts plus generic-extract.test.ts pass (487 run, 0 failed, 4 skipped).

Known limitation

Editing a tsconfig on its own does not mark the graph stale, because the fingerprint tracks source files only. go.mod has the same limitation today. The next source change or graft build picks the new aliases up.

🤖 Generated with Claude Code

resolveImport only followed relative specifiers, so an import through a
tsconfig alias (`@core/x`, `@/x`, a baseUrl-relative `core/x`) stayed an
external string and no call or reference edge was drawn to the real file.
In a repo that uses aliases, `callers`, `blast`, hub ranking in `map` and the
coupling-based ranking in `ask` silently missed almost every caller.

Read every tsconfig.json, tsconfig.*.json and jsconfig.json once per build
(JSONC, relative `extends` chains, `baseUrl`, `paths` with an exact key or one
`*`, longest-prefix-wins, several targets), scope each config to the importers
under its directory, and resolve through the same candidate order relative
imports use. Only JS/TS-family importers are affected; an alias that does not
land on an indexed file stays unresolved, so no edge is ever invented.

Editing a tsconfig alone does not mark the graph stale, the same limitation
`go.mod` has today: the fingerprint tracks source files only.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@trailhq-graft

trailhq-graft Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

🌱 graft blast radius

1 area changed → 3 areas can be affected. 10 dependent symbols, depth 2.
Tests: 1 area updated its tests.
Tag: @anirudhkumar-nanonets — 4 of 4 areas · @shhdwi — 3 of 4 areas

flowchart TB
  A0(("Graph Refresh<br/>5 symbols"))
  A1(("Pull Request Review<br/>4 symbols"))
  A2(("Engine Core<br/>1 symbol"))
  classDef reached fill:#D9EDF3,stroke:#3AA7C9,stroke-width:1.5px,color:#0E313C;
  class A0,A1,A2 reached;
Loading
Can be affected Symbols Nearest hop Reached from
Graph Refresh 5 src/graph/refresh-run.ts:L18-L21 main — calls, depth 1 Graph Construction
Pull Request Review 4 src/app/review.ts:L45-L99 reviewPullRequest — calls, depth 1 Graph Construction
Engine Core 1 src/engine.ts:L104-L115 graph — calls, depth 1 Graph Construction
Who knows this code — 2 people across 4 areas
Area Who knows it
Graph Construction · changed @anirudhkumar-nanonets — 20 commits, last 3mo ago · @shhdwi — 15 commits, last 23d ago
Graph Refresh · affected @anirudhkumar-nanonets — 11 commits, last 18d ago · @shhdwi — 6 commits, last 23d ago
Pull Request Review · affected @anirudhkumar-nanonets — 11 commits, last 1mo ago · @shhdwi — 2 commits, last 23d ago
Engine Core · affected @anirudhkumar-nanonets — 17 commits, last 1mo ago

Ownership is git history over each area's own files, weighted towards recent work (120-day half-life). Merge commits and bots are dropped, and you are dropped from your own PR. A name with no @ has no GitHub handle in its commit email — tag them by hand, or add a .mailmap entry. A suggestion from history, not a CODEOWNERS rule.

All 10 dependent symbols, grouped by area

Graph Refresh — 5 symbols in 3 files

  • src/graph/refresh-run.ts:L18-L21 — main (calls, depth 1)
    20: await buildGraph(dir, { contextDir, graphOnly: true, onlyDirs, extensions });
  • src/graph/refresh.ts:L202-L225 — rebuild (calls, depth 1)
    205: await buildGraph(args.dir, {
  • src/graph/refresh-run.ts:L1-L33 — refresh-run.ts (calls, depth 2)
    9: import { buildGraph } from "./build.js";
  • src/graph/refresh.ts:L271-L347 — ensureFreshGraph (calls, depth 2)
    287: // other repo gets the caller's own "no graph — run graft build" message.
  • src/graph/workspace-cli.ts:L65-L108 — buildChild (calls, depth 2)

Pull Request Review — 4 symbols in 4 files

  • src/app/review.ts:L45-L99 — reviewPullRequest (calls, depth 1)
    55: await buildGraph(checkout.dir);
  • src/app/review-process.ts:L178-L182 — childReviewer (references, depth 2)
  • src/app/review-worker.ts:L67-L87 — run (calls, depth 2)
  • src/app/server.ts:L31-L37 — AppSeams (references, depth 2)

Engine Core — 1 symbol in 1 file

  • src/engine.ts:L104-L115 — graph (calls, depth 1)
    105: return buildGraph(dir, {
Test signal per changed area — 1 ✓

Reached = a node under a test path has a resolved edge into the changed symbol. It undercounts anything called indirectly — through a CLI, a spawned process or a dynamic import — so read a low ratio as “look here”, never as a coverage gate.

  • ✓ Graph Construction — 2 of 16 reached · 1 test file changed here: test/graph-resolve-ts-paths.test.ts
    • not reached: resolveImport, findImportCandidate, comparePath, compilePaths, isRecord, matchPattern, pathDepth, readEffectiveConfig, …6 more
53 test suites also reference this code

66 symbols, kept out of the diagram and the table so they cannot crowd out the areas a reviewer has to look at.

  • test/ask-index.test.ts
  • test/ask.test.ts
  • test/claude-hooks.test.ts
  • test/claude-prompt-private.test.ts
  • test/container-extract.test.ts
  • test/context-only-dir.test.ts
  • test/context.test.ts
  • test/covers.test.ts
  • test/depth-parity.ts
  • test/generic-extract.test.ts
  • test/graph-bash.test.ts
  • test/graph-cross-language.test.ts
  • test/graph-elixir.test.ts
  • test/graph-extensions.test.ts
  • test/graph-go.test.ts
  • test/graph-incremental.test.ts
  • test/graph-invariants.test.ts
  • test/graph-java.test.ts
  • test/graph-jsx.test.ts
  • test/graph-kotlin.test.ts
  • …33 more

graft blast · origin/main...HEAD · depth 2 · 4 changed files

Open the interactive graph → — click an area to see its dependent symbols at file:line.

github-actions Bot added a commit that referenced this pull request Nov 20, 2026
Comment thread src/graph/ts-paths.ts
const configs: TsPathConfig[] = [];
const configFiles = repoFiles
.map(toPosixPath)
.filter((file) => /(?:^|\/)(?:tsconfig(?:\..+)?|jsconfig)\.json$/.test(file))

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants