-
Task
-
Resolution: Unresolved
-
Major
-
None
-
None
-
Quality / Stability / Reliability
-
False
-
-
False
-
-
-
None
This ticket is for the technical writer to create comprehensive documentation for the architecture of the C# Analyzer Provider, utilizing the Jobs to be Done (JTBD) framework to ensure the content is user-centric and addresses specific user goals. The existing source document (c-sharp-analyzer-provider/docs/architecture.md) will serve as the primary content for this documentation effort.
The C# Analyzer Provider represents a significant architectural shift in how C# code is analyzed within the Migration Toolkit for Applications (MTA) ecosystem compared to previous .NET analysis tools, primarily by moving from a rule-based, potentially syntax-heavy analysis model to a semantic, graph-based model.
Architectural Changes: Graph-Based Semantic Analysis
The most fundamental change is the shift in the analysis engine:
| Feature | New C# Analyzer Provider | Previous MTA/Windup Analysis |
| Parsing Engine | Uses tree-sitter for robust, incremental parsing. | Often relied on compiler APIs (like Roslyn) for C# or YAML-based rules for file scanning and classification. |
| Semantic Model | Builds a Stack Graph for name resolution and semantic analysis. | Used an internal graph database primarily to store data model based on rule execution results. |
| Analysis Method | Focuses on querying the graph for semantic references (types, methods, fields) using location filtering and FQDN resolution. | Relied on a rule-based pattern (when(condition) message(message) tag(tags)) to detect issues and produce reports. |
Job to be Done (JTBD) Framework
The documentation is structured around the following key user jobs, which should be satisfied by the content in the existing architecture document:
| Situation | Motivation | Expected Outcome |
| When I start working with the C# Analyzer Provider and its codebase | I want to quickly understand the system's architecture, components, and data flow | So I can efficiently contribute to its development, integration, and maintenance. |
| When I need to add a new analysis feature to the provider | I want to know the established process and location for implementing new capabilities or location types | So I can correctly extend the functionality without introducing errors or breaking the system. |
| When I encounter an issue with the analyzer provider’s performance or data management | I want to understand the underlying mechanisms for caching, threading, and storage | So I can effectively troubleshoot and optimize the service. |
Target Personas
The documentation should cater to the needs of the following personas, using the details provided in the existing source document:
- Developer/Engineer:
-
- Goal: Quickly understand the core components and data flow for feature development or bug fixing.
-
- Focus Areas: Main Entry Point (threads, transport, logging) , Query System logic (FQDN Resolution, pattern matching) , and Extension Points (adding capabilities/location types) .
- Focus Areas: Main Entry Point (threads, transport, logging) , Query System logic (FQDN Resolution, pattern matching) , and Extension Points (adding capabilities/location types) .
- DevOps/System Integrator:
-
- Goal: Understand how the service is run and configured for deployment and integration.
-
- Focus Areas: Transport Layer options (HTTP/2, Unix Sockets, Named Pipes) , Dependency Resolution process (Paket, ILSpy) , and Storage configuration (SQLite database path and persistence) .
Feature Details: Leveraging Existing Content
The technical writer must transform the existing technical architecture Markdown file into user-centric documentation by highlighting the following aspects:
- System Architecture & Components: Explain the function of each core component (e.g., Provider Service, Project Manager, Dependency Resolver) and their interaction, as described in the architecture overview .
- Provider Service Endpoints: Detail the purpose and flow for the three gRPC endpoints: capabilities() , init() , and evaluate() .
- Analysis Modes and State: Clearly differentiate between the SourceOnly and Full analysis modes and explain the contents of the Project struct that manages the state .
- Data Flows: Illustrate the Initialization Flow and the Query Flow , which include steps like dependency resolution, graph building, and result formatting .
- Key Concepts: Dedicate sections to explain the semantic analysis engine built on tree-sitter and stack-graphs , specifically the function of Source Type Tagging (source vs. dependency) and FQDN Resolution .
- Extension/Maintenance: Provide clear guidance on the established processes for Adding a New Capability or Adding a New Location Type, using the steps outlined in the document.