AgenticTyper: Automated Typing of Legacy Software Projects Using Agentic AI

1. Problem and Motivation

Legacy software systems, particularly those written in dynamically typed languages like JavaScript, accumulate significant business value but suffer from high maintenance costs and risks. The lack of type safety makes modifications dangerous, often leading to runtime errors that break existing functionality. While TypeScript offers optional typing to mitigate these risks by providing documentation, explicit dependencies, and bug prevention, manually migrating a large legacy codebase is prohibitively expensive and time-consuming (often taking years).

Current automated typing solutions face several limitations:

• Type Inference: Traditional static, dynamic, or probabilistic methods often fail to handle dynamic language features, require extensive test suites, or produce incorrect predictions that require manual discarding.
• LLM Limitations: Simply prompting Large Language Models (LLMs) to add types fails at the repository scale because models struggle to navigate multiple files, handle cascading errors, or verify that code changes do not alter runtime behavior.
• Scope Gaps: Existing research rarely addresses the full lifecycle of typing: setting up type checking, generating definitions, identifying bugs, and ensuring behavioral correctness across an entire repository.

2. Methodology: AgenticTyper

The authors propose AgenticTyper, an agentic AI system designed to automate the typing of legacy JavaScript repositories. Unlike previous approaches, it utilizes LLM-based coding agents combined with a transpilation comparison mechanism to ensure behavior preservation without relying on pre-existing test suites.

Core Architecture

The system employs a multi-agent workflow where agents run in parallel to edit files. A critical component is the Behavior Preservation Hook (Figure 2):

1. Edit: An agent modifies a file (adding JSDoc annotations or TypeScript types).
2. Transpile: The modified code is immediately transpiled to JavaScript.
3. Compare: The transpiled output is compared against the original transpiled output.
4. Verification: If the outputs differ, the agent is alerted to a behavioral regression and must revert or adjust the change. This ensures that type annotations do not alter the runtime logic.

Three-Phase Approach

The system operates in three incremental phases (Figure 1):

• Phase 1: Minimal Setup:
  • Enables basic TypeScript checking.
  • Agents install missing @types and analyze compiler diagnostics.
  • Agents fix errors by adding JSDoc annotations (e.g., @type, @param).
  • Suppression Strategy: If an error cannot be fixed without changing behavior (e.g., valid type coercion), the agent inserts a suppression comment (@ts-expect-error).
    • Bugs: Marked for human review.
    • Valid Patterns: Marked with neutral explanations to create a clean baseline.
• Phase 2: Full Coverage:
  • Enables noImplicitAny, requiring explicit annotations everywhere.
  • Agents add type definitions and annotations to address newly surfaced errors, repeating the fix/suppress logic.
• Phase 3: Strict Mode:
  • Enables strict checking modes.
  • Reveals issues often requiring refactoring (e.g., null checks).
  • This phase requires regression testing via generated tests or manual verification due to higher risk.

3. Key Contributions

1. Novel Agentic Approach: Introduces a system that combines agentic AI with transpilation comparison to automate typing at the repository level without needing a pre-existing test suite.
2. Behavior Preservation: A unique mechanism that detects runtime regressions by comparing transpiled outputs, allowing safe automated refactoring.
3. Distinction of Issues: The system differentiates between actual bugs requiring human intervention and valid dynamic patterns that cannot be typed without altering behavior.
4. Open-Source Implementation: The authors provide an open-source implementation featuring parallel agent execution.

4. Results and Evaluation

The system was evaluated on two proprietary Node.js backend repositories (totaling 81,000 Lines of Code) from an industrial facility management platform.

• Performance:
  • Time: AgenticTyper resolved all 633 initial type errors in approximately 20 minutes (19:57 min).
  • Cost: The total cost was $24.93 (using Claude Sonnet 4.5 via the Claude Agent SDK).
  • Comparison: A task that previously required one full working day for an experienced TypeScript developer was completed in minutes.
• Accuracy:
  • The system successfully established type checking without modifying runtime behavior (verified via transpilation comparison).
  • Suppressions: 383 suppressions were necessary. 26 of these (6.8%) were "additional" suppressions caused by the agent suppressing errors at multiple usage sites rather than the root cause (e.g., parameter shadowing). This indicates that while effective, root-cause tracing could be improved.
• Scalability: The system ran 10 agents in parallel, demonstrating the ability to handle cross-file dependencies effectively.

5. Significance and Future Work

Significance:
AgenticTyper demonstrates that agentic AI can significantly reduce the cost and time associated with modernizing legacy software. By automating the tedious process of adding type safety, it lowers the barrier for organizations to adopt TypeScript, thereby improving code maintainability and reducing the risk of future bugs. The "behavior preservation" hook is a critical innovation that solves the "regression fear" often associated with automated code modification.

Future Work:

• Implementation and evaluation of Phase 2 and Phase 3 on the same repositories.
• Testing on a 300,000 LOC TypeScript repository where Phase 1 is unnecessary.
• Metrics for future evaluation will include type coverage, annotation correctness (via manual review), and cleanup effort.
• Extension to other optionally typed languages, such as Python.