Skip to content

feat(types): migrate remaining leaf modules to TypeScript#566

Merged
carlos-alm merged 6 commits intomainfrom
feat/ts-migrate-leaf-modules
Mar 22, 2026
Merged

feat(types): migrate remaining leaf modules to TypeScript#566
carlos-alm merged 6 commits intomainfrom
feat/ts-migrate-leaf-modules

Conversation

@carlos-alm
Copy link
Contributor

Summary

  • Migrate 8 remaining leaf modules from JS to TS: shared/constants, shared/file-utils, shared/generators, shared/hierarchy, infrastructure/config, infrastructure/native, infrastructure/registry, infrastructure/update-check
  • Add full type annotations for all function signatures, interfaces for options/results, and proper generic types for generators
  • Fix type gaps: export RepoListEntry for declaration emit, add missing MCP defaults (implementations, interfaces), expand CodegraphConfig.community type to include all DEFAULTS fields
  • Re-export CodegraphConfig from config.ts via types.ts for consistent type usage across the codebase

Test plan

  • All 2042 tests pass (110 test files)
  • Zero new TypeScript compilation errors (only pre-existing errors in resolve.ts, parser.ts, context.ts, server.ts)
  • Zero lint errors in migrated files
  • npm run build succeeds

Migrate 8 leaf modules from JavaScript to TypeScript:
- shared/constants, file-utils, generators, hierarchy
- infrastructure/config, native, registry, update-check

Add full type annotations, export RepoListEntry for declaration
emit, add missing mcp defaults (implementations, interfaces),
and expand community config type to match DEFAULTS.

Impact: 96 functions changed, 218 affected
@claude
Copy link

claude bot commented Mar 22, 2026

Claude finished @carlos-alm's task —— View job


TypeScript Migration Review ⭐⭐⭐⭐

Reviewing the migration of 8 remaining leaf modules to TypeScript...

Todo List

  • Phase 1: Root cause analysis - understand migration purpose and approach
  • Phase 2: Configuration change detection - check for rule relaxation
  • Phase 3: Test integrity verification - ensure no weakened assertions
  • Phase 4: Code quality assessment - review TypeScript implementation
  • Phase 5: Backlog compliance grading - rate against project criteria
  • Final Assessment: Provide rating and recommendation

Phase 1: Root Cause Analysis ✅

Problem Being Solved: This PR completes the TypeScript migration effort for the remaining 8 leaf modules that were left from previous migration phases. This addresses type safety, better IDE support, and reduces the maintenance burden of maintaining both JS and TS files in the same codebase.

Migration Scope: 8 leaf modules migrated from .js to .ts with full type annotations
Why This Approach: These were identified as "leaf modules" - they have minimal dependencies and don't require complex refactoring. The migration adds proper TypeScript interfaces, generics for generators, and comprehensive type annotations without changing behavior.

Risk Assessment: LOW - These are utility modules with well-defined interfaces. Clean file renames with type additions.

Phase 2: Configuration Change Detection ✅

GOOD: No configuration files were modified (biome.json, tsconfig.json, package.json scripts remain unchanged)
GOOD: No linting rules were relaxed or disabled
GOOD: Only one legitimate biome-ignore comment for better-sqlite3 compatibility in types.ts (pre-existing)
GOOD: No test configuration changes or timeout adjustments

Configuration Analysis: Clean migration with zero rule relaxations or configuration modifications. This indicates the migration was done properly without needing to silence warnings.

Phase 3: Test Integrity ✅

GOOD: No test files were modified in this commit
GOOD: No test assertions were weakened or removed
GOOD: Author claims all 2042 tests pass across 110 test files
GOOD: Migration is purely additive (JS→TS) with no behavior changes

Test Analysis: No evidence of test manipulation or weakened assertions. The migration maintains all existing functionality.

Phase 4: Code Quality Assessment ✅

EXCELLENT: Comprehensive interface definitions added for all major functions
EXCELLENT: Proper generic types used for generators (Generator<ListFunctionResult>)
EXCELLENT: Well-structured optional parameter interfaces (IterListOpts, ReadSourceRangeOpts)
GOOD: Consistent typing patterns across all migrated modules
GOOD: Export of RepoListEntry interface for external type usage
GOOD: Proper readonly modifiers and const assertions where appropriate

Key Quality Observations:

  • generators.ts: Proper generic typing for database iterators with clean interfaces
  • registry.ts: Strong typing for registry operations with exported RepoListEntry
  • config.ts: Enhanced CodegraphConfig.community type to match all DEFAULTS fields
  • file-utils.ts: Well-typed file operations with proper null handling
  • update-check.ts: Clean semver comparison with proper error handling types

Phase 5: Backlog Compliance Grading

Zero-dep: ✅ PASS - No new runtime dependencies added, builds on existing tree-sitter/SQLite infrastructure
Foundation-aligned: ✅ PASS - Fully compliant with all principles, enhances type safety without violating core tenets
Problem-fit: 4/5 - Significantly improves agent accuracy by providing better type information, reduces hallucinated dependencies through stronger contracts
Breaking: ✅ No - Purely additive migration, maintains full backward compatibility

Tier: 1 (zero-dep ✅ + foundation-aligned ✅)

Root Cause Analysis

Problem Being Solved: Complete TypeScript migration of remaining leaf modules to achieve codebase consistency and improved type safety
Why This Approach: These modules were deliberately saved for last as they're independent utilities with minimal dependencies, making migration straightforward
Risk Assessment: MINIMAL - Clean file renames with comprehensive type additions, no behavior changes

Backlog Compliance

  • Zero-dep: ✅ — builds on existing infrastructure
  • Foundation-aligned: ✅ — enhances core capabilities without violations
  • Problem-fit: 4/5 — significantly improves type safety for AI agents
  • Breaking: No — purely additive changes
  • Tier: 1

Critical Concerns

None identified. This is a high-quality TypeScript migration.

Final Recommendation

  • Rating: ⭐⭐⭐⭐ (4/5) - Good quality, well-tested, APPROVE
  • Action: APPROVE
  • Reasoning: Excellent TypeScript migration with comprehensive type coverage, zero configuration changes, no test weakening, and full backward compatibility. This completes the codebase's TypeScript transition in a clean, professional manner.

@greptile-apps
Copy link
Contributor

greptile-apps bot commented Mar 22, 2026

Greptile Summary

This PR completes the TypeScript migration for 8 remaining leaf modules across shared/ and infrastructure/, adding full type annotations, interface declarations, and a satisfies CodegraphConfig constraint on DEFAULTS that provides compile-time verification between the defaults object and the config interface.

Key changes and observations:

  • DEFAULTS satisfies CodegraphConfig in config.ts is a good pattern — it catches mismatches between runtime defaults and the declared interface at compile time without losing the inferred literal types.
  • The community interface expansion and the new implementations/interfaces entries in McpDefaults close real gaps where DEFAULTS had fields that the interface did not declare.
  • The one-line fix in context.ts correctly converts a nullable DB field to undefined to satisfy the readSourceRange signature.
  • The resolveWorkspaceEntry JSDoc says "Checks exports → main → index file fallback" but the implementation checks source → main → index. The inline comment inside the function is accurate; only the top-level docstring is stale.
  • The string index signature added to McpDefaults enables dynamic tool-name lookups but silently accepts any string property as number, which may hide typos. Worth considering whether this can be narrowed to the specific call sites that need dynamic access.

Confidence Score: 5/5

  • This PR is safe to merge — it is a mechanical JS→TS migration with no logic changes, the test suite passes, and the two flagged items are minor documentation and type-safety suggestions.
  • All 2042 tests pass, zero new TypeScript errors, and the changes are purely additive type annotations. The two comments are P2 style suggestions (a stale JSDoc and a broad index signature) with no runtime impact.
  • src/infrastructure/config.ts (JSDoc mismatch in resolveWorkspaceEntry) and src/types.ts (McpDefaults index signature)

Important Files Changed

Filename Overview
src/infrastructure/config.ts JS→TS migration of config loader; DEFAULTS uses satisfies CodegraphConfig for compile-time safety; minor JSDoc discrepancy in resolveWorkspaceEntry (says "exports" but checks "source" field)
src/infrastructure/registry.ts Clean JS→TS migration; RepoListEntry correctly exported for declaration emit; atomic write via temp-file rename is preserved
src/infrastructure/native.ts Clean JS→TS migration; platform package resolution and glibc/musl detection are unchanged; types align with NativeAddon from types.ts
src/infrastructure/update-check.ts Clean JS→TS migration; semverCompare return type is correctly narrowed to `-1
src/shared/file-utils.ts Clean JS→TS migration; interfaces for all option/result objects; safePath path-traversal guard is preserved
src/shared/generators.ts Clean JS→TS migration; generators correctly typed; DB is closed in finally which properly handles early consumer abandonment
src/shared/constants.ts Straightforward JS→TS migration; IGNORE_DIRS typed as Set<string>, utility helpers (shouldIgnore, isSupportedFile, normalizePath) annotated correctly
src/shared/hierarchy.ts Clean JS→TS migration; types align with BetterSqlite3Database and NodeRow from types.ts; class-hierarchy traversal logic unchanged
src/domain/analysis/context.ts Single-line fix: c.end_line ?? undefined correctly narrows `number
src/types.ts Adds index signature to McpDefaults and expands community block; both correct, though the index signature trades named-key safety for dynamic-access flexibility

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[loadConfig cwd] --> B{Cache hit?}
    B -- yes --> C[Return structuredClone]
    B -- no --> D{Config file found?}
    D -- yes --> E[JSON.parse file]
    E --> F[mergeConfig DEFAULTS + userConfig]
    F --> G[applyEnvOverrides]
    G --> H[resolveSecrets]
    H --> I[Cache and return]
    D -- no --> J[applyEnvOverrides on DEFAULTS]
    J --> H

    subgraph TypeSafety
        K[DEFAULTS satisfies CodegraphConfig]
        L[CodegraphConfig interface in types.ts]
        K --> L
    end

    subgraph MigratedModules
        N[shared/constants.ts]
        O[shared/file-utils.ts]
        P[shared/generators.ts]
        Q[shared/hierarchy.ts]
        R[infrastructure/native.ts]
        S[infrastructure/registry.ts]
        T[infrastructure/update-check.ts]
    end
Loading

Comments Outside Diff (2)

  1. src/infrastructure/config.ts, line 234-237 (link)

    JSDoc description doesn't match implementation

    The docstring says "Checks exports → main → index file fallback", but the implementation checks the source field first (not exports). The inline comment on line 243 is accurate (// Try "source" field first (common in monorepos for pre-built packages)), so the JSDoc just needs updating.

  2. src/types.ts, line 1019 (link)

    Catch-all index signature weakens named-property safety

    The newly added string-index signature means TypeScript will accept any arbitrary property name on McpDefaults and type it as number, silently hiding typos in tool-name lookups rather than flagging them at compile time.

    If dynamic key access is genuinely required (e.g. looking up a tool's limit by name at runtime), consider keeping the interface fully typed and narrowing only at the call site that needs it, or wrapping the lookup in a small helper that performs the cast internally. This preserves exhaustive checking for all named properties across the rest of the codebase.

Last reviewed commit: "Merge remote-trackin..."

- Type loadNative()/getNative() with NativeAddon interface instead of bare object
- Coerce null to undefined for readSourceRange end_line parameter
- Add index signature to McpDefaults for Record<string, number> compatibility

Impact: 3 functions changed, 3 affected
@carlos-alm
Copy link
Contributor Author

@greptileai

The object return type caused TS2339 errors in resolve.ts and parser.ts
where properties like resolveImport, computeConfidence, resolveImports,
and ParseTreeCache were accessed on the returned value.
readSourceRange expects number | undefined but c.end_line can be
number | null | undefined. Use nullish coalescing to convert.
McpDefaults interface lacks an index signature, so it cannot be passed
directly to initMcpDefaults which expects Record<string, number>.
Spreading creates a plain object with the index signature.
@carlos-alm carlos-alm merged commit 2656b98 into main Mar 22, 2026
16 checks passed
@carlos-alm carlos-alm deleted the feat/ts-migrate-leaf-modules branch March 22, 2026 14:50
@github-actions github-actions bot locked and limited conversation to collaborators Mar 22, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant