| name | quickmarkup-contributing |
| description | Maps QuickMarkup repository areas to files for contributors implementing language, binders, codegen, source generation, or Roslyn analyzers. Use when editing QuickMarkup itself (not when consuming QuickMarkup as a library), adding syntax, AST nodes, binders, diagnostics, or generated C# output. |
Contributing to QuickMarkup
Paths are relative to the QuickMarkup repository root (the folder containing QuickMarkup.Language, QuickMarkup.SourceGen, etc.).
Defining or extending the language (grammar + AST)
- Parser (LR rules, reductions):
QuickMarkup.Language/Parser/QuickMarkupParser.cs
- Lexer (tokens, states, regex actions):
QuickMarkup.Language/Parser/QuickMarkupLexer.cs
- AST shapes / node types:
QuickMarkup.Language/AST/
- TextMate grammar scopes:
QuickMarkup.Language/Textmate/
Grammar and lexer use Get.Parser / Get.Lexer (usually under Parser/ submodule). For framework mechanics, see Parser/Language-Authoring-Guide.md in that tree.
Binders and language-side analysis
- Source-gen binders (how QM binds to C#):
QuickMarkup.CodeAnalysis/Binders/
- Shared symbols / language model hooks:
QuickMarkup.Language/Symbols/
- Type resolution for codegen:
QuickMarkup.CodeAnalysis/CodeTypeResolver.cs (shared with codegen; change here when binding or typing rules affect both)
- Generated member tracking:
QuickMarkup.CodeAnalysis/QuickMarkupGeneratedMemberTable.cs and QuickMarkupGeneratedMemberTableBuilder.cs
- Target type context:
QuickMarkup.CodeAnalysis/Helpers/QuickMarkupTargetContext.cs
Shared analysis project (QuickMarkup.CodeAnalysis)
QuickMarkup.CodeAnalysis/ is a shared project (.shproj) containing code used by both the source generator and the analyzer. Key files:
- Binder base and main binder:
Binders/Binder.cs, Binders/QuickMarkupBinder.cs, Binders/QuickMarkupBinder.Refs.cs
- Binder diagnostics:
Binders/QMBinderError.cs
- Ref attribute binding:
Binders/RefAttributeBinder.cs
- Type resolution:
CodeTypeResolver.cs
- Member table:
QuickMarkupGeneratedMemberTable.cs
- String similarity for suggestions:
StringSimilarity.cs
- Provider extensions (parsing + source-gen hooks):
Helpers/QuickMarkupProviderExtension.*.cs
Code generation (emitted C#)
- Generators and snippets:
QuickMarkup.SourceGen/CodeGen/
CodeGenContext.cs — generates init/setup code from bound treeCodeSnippets.cs — C# code snippet helpers (closures, property assign)RefsGenContext.cs — generates ref/computed property declarations
Source generator entry points
- User-facing attribute:
QuickMarkup.Infra/QuickMarkupAttribute.cs
- Main generator pipeline:
QuickMarkup.SourceGen/QuickMarkupGenerator.cs
- .qmui file pipeline:
QuickMarkup.SourceGen/QuickMarkupGenerator.Qmui.cs
- Diagnostic reporting:
QuickMarkup.SourceGen/QuickMarkupDiagnosticReporter.cs
Roslyn analyzers (IDE diagnostics on user C#)
- Diagnostic IDs and analyzer logic:
QuickMarkup.SourceGen/QuickMarkupAnalyzer.cs
- .qmui file analysis:
QuickMarkup.SourceGen/QuickMarkupAnalyzer.Qmui.cs
- Attribute the analyzer keys off (same surface as users):
QuickMarkup.Infra/QuickMarkupAttribute.cs
- Diagnostic reporting helpers:
QuickMarkup.SourceGen/QuickMarkupDiagnosticReporter.cs
Language Server (QuickMarkup.LanguageServer)
Full LSP server for real-time .qmui diagnostics and navigation:
- Entry point / DI:
QuickMarkup.LanguageServer/Program.cs
- Compilation enrichment:
QuickMarkupLanguageServer/QuickMarkupCompilationEnricher.cs
- Diagnostic service:
Diagnostics/QmuiDiagnosticService.cs
- Handlers:
Handlers/QmuiDefinitionHandler.cs, QmuiHoverHandler.cs, QmuiDidOpenHandler.cs, QmuiDidChangeHandler.cs, QmuiDidCloseHandler.cs
- Navigation:
Navigation/MarkupCursorResolver.cs, SymbolLocationResolver.cs
- Workspace management:
Workspace/RoslynWorkspaceManager.cs, ProjectFinder.cs, SolutionParser.cs
Snapshot persistence (QuickMarkup.Snapshot)
- Snapshot attributes:
QuickMarkup.Snapshot/Attributes.cs
- Snapshot interfaces:
QuickMarkup.Snapshot/ISnapshotComponent.cs, ISnapshotFormatter.cs
- Snapshot source generator:
QuickMarkup.Snapshot.SourceGen/QuickMarkupSnapshotGenerator.cs
- Snapshot binder:
QuickMarkup.Snapshot.SourceGen/Binders/SnapshotBinder.cs
Grammar generation and editor integration
- TextMate grammar generator:
QuickMarkup.GrammarGenerator/Program.cs — generates grammar JSON from lexer tokens
- VS Code extension:
QuickMarkup.VSCode.Extension/ — syntax highlighting, LSP client for .qmui files
Runtime infrastructure (QuickMarkup.Infra)
Runtime library with reactive infrastructure, UI block abstractions, and the user-facing [QuickMarkup] attribute.
Workflow hint
- Grammar/lexer/AST first if the feature is new surface syntax or tree shape.
- Then binders/symbols/resolver (in
QuickMarkup.CodeAnalysis/) so the generator knows types and members.
- Then
CodeGen/ output and generator wiring in QuickMarkupGenerator.cs.
- Add or extend
QuickMarkupAnalyzer.cs when users need compile-time feedback on invalid QuickMarkup usage.
- If the change affects
.qmui files, update the Language Server handlers and diagnostic service.
Keep changes scoped to the layer that actually needs to move; resolver and binders often change together with new AST or binding rules.
