docs(roadmap): SonarDelphi migration plan (todo-sonardelphi-migration.md)

Internal working document for the next big initiative — porting SonarDelphi
plugin coverage (144 rules in v1.18.3, IntegraDev fork) onto our SCA
platform so SCA alone replaces SonarDelphi+SCA dual-install.

Researched via two parallel agents:
- Rule inventory and gap analysis: 22 SCA<->SonarDelphi overlaps, ~119
  unique-to-SonarDelphi rules to port, ~37 unique-to-SCA differentiators
  (the 20 DFM rules + security/SQL family).
- Technical migration strategy: ANTLR3 vs our recursive-descent parser,
  type-system gaps (we don't have cross-unit symbol resolution for types,
  only names), class-hierarchy index missing, per-rule effort estimate
  bucketed A-G by detection-approach category.

Plan:
- Phase 0 (1d): catalog-first placeholders for all 144 rule IDs
- Phase 1 (2w): 50 lexical + single-AST detectors
- Phase 2 (1w): Forbidden-tracker + Naming-conventions frameworks (25 rules
  via 2 frameworks)
- Phase 3 (3w): 35 multi-node + cross-unit detectors
- Phase 4 (2w): 12 inheritance/inline-decl rules + new uClassHierarchyIndex
- Phase 5 (4w, optional): 17 type-flow rules + uTypeRegistry

Total without Phase 5: 9 weeks for 122 ported + 22 existing = 144 (100%)
plus 37 our-unique = 110% target reached.

Shadow-run script and coverage-gap test scaffold described as
cross-cutting tasks - implementation deferred to the actual migration
sprints. Document follows the same convention as todo-sonar.md
(checked-in working doc, not part of the release artifacts).

Author: nrodear

todo-sonardelphi-migration.md

@@ -0,0 +1,203 @@
+# TODO — SonarDelphi → SCA Detector Migration
+
+**Goal: 110 % coverage of all SonarDelphi findings**, plus our existing
+SCA-unique detectors (DFM, security, SQL).
+
+> **Recherche-Stand 2026-05-16**:
+> - SonarDelphi v1.18.3 (IntegraDev fork): **144 Rules** (25 BUG + 119 CODE_SMELL, 0 Vulnerability/Hotspot)
+> - SCA v0.9.1: **59 Rules**, davon ~22 mit SonarDelphi-Overlap, ~37 unique (20 DFM-Rules + SQL/Security/Format-Locale)
+> - Coverage-Gap zum 110 %-Ziel: **~119 Rules** zu portieren, **~25 Rules** schon vorhanden
+
+---
+
+## Context
+
+Heute haben wir die SonarQube-Integration auf Production-Niveau gebracht
+(`v0.9.1`). SCA-Findings landen als External Issues neben dem SonarQube-
+Default-Profile "Sonar Way". Wenn ein User aber **auch** das SonarDelphi-
+Plugin installiert hat, sieht er TWO Detektor-Sets parallel — wir wollen,
+dass SCA allein ausreicht und das SonarDelphi-Plugin **überflüssig** wird.
+
+"110 % Coverage" bedeutet:
+- Jeder SonarDelphi-Finding muss von SCA matched werden (sonst: regression
+  beim Wechsel weg von SonarDelphi)
+- Unsere zusätzlichen Findings (DFM, SQL, Format-Locale) bleiben unsere
+  Differentiation
+- **Shadow-Run**: SonarDelphi und SCA parallel über denselben Code-Korpus,
+  diff der Findings nach `(file, line, rule)` — Ziel: SonarDelphi-only-
+  Findings = 0
+
+## Bestehende Infrastruktur (nicht neu bauen)
+
+- AST: [`uAstNode.pas`](StaticCodeAnalyserForm/sources/Parsing/uAstNode.pas), [`uParser2.pas`](StaticCodeAnalyserForm/sources/Parsing/uParser2.pas) — Visitor-tauglich, 45 `TNodeKind`-Werte
+- Symbol-Reference-Index: [`uSymbolReferenceIndex.pas`](StaticCodeAnalyserForm/sources/Infrastructure/uSymbolReferenceIndex.pas) — Cross-Unit-Visibility (genutzt von `uVisibilityCheck`)
+- Catalog: [`rules/sca-rules.json`](rules/sca-rules.json) + `uRuleCatalog.pas`
+- KIND_META: [`uSCAConsts.pas`](StaticCodeAnalyserForm/sources/Common/uSCAConsts.pas) — Single-Source für Severity + FindingType + Name
+- Detector-Pattern: 53 Beispiele in [`StaticCodeAnalyserForm/sources/Detectors/`](StaticCodeAnalyserForm/sources/Detectors/)
+- Tests: DUnitX-Fixtures in `tests/uTest*.pas`
+
+## Was SonarDelphi anders / besser macht
+
+Nicht-portable Java-Stack:
+- **ANTLR3-AST** mit ~50 fein-granulierten Node-Klassen (`RoutineImplementationNode`, `AnonymousMethodNode`, `FieldDeclarationNode`, ...)
+- **Type-System mit Symbol-Resolution** über Unit-Imports (`getType().isUnresolved/isClass/isUnknown`)
+- **Inheritance-Index** ("ist Klasse direkt von TObject abgeleitet?")
+- **DelphiCheckContext + reportIssue()** Sonar-Framework-API
+
+Bei uns fehlend:
+- Fein-granulierte AST-Subtypes (wir haben `nkMethod` als Einheits-Bucket)
+- Type-Registry mit Cross-Unit-Lookup
+- Class-Hierarchy-Index (parent_name_chain pro `class_name`)
+
+## Phase Plan
+
+### Phase 0 — Catalog-First (1 Tag) 🅐
+
+**Ziel**: SonarDelphi-Push-Kompatibilität sofort, ohne Detection-Logik.
+
+- [ ] Alle 144 SonarDelphi-Rule-Keys als `fk*`-Konstanten in [`uSCAConsts.pas`](StaticCodeAnalyserForm/sources/Common/uSCAConsts.pas) (TFindingKind enum + KIND_META) einpflegen
+- [ ] [`rules/sca-rules.json`](rules/sca-rules.json) auf 144 + 37 = **~181 Rules** erweitern (placeholders mit Beschreibung aus SonarDelphi-JSON)
+- [ ] MQR-Mapping pro neuer Rule (`cleanCodeAttribute` + `impacts`) — viel ist mechanisch übertragbar aus SonarDelphi-Severity
+- [ ] Drift-Tests `EveryFindingKindHasRichMetadata` + `EveryFindingKindHasMqrMapping` müssen weiterhin grün sein
+- [ ] **Acceptance**: `analyser.exe --sonar-export` schreibt 144+37 Rule-Entries; Sonar-Push akzeptiert die JSON
+
+> **Wert**: dadurch verstummen die SonarDelphi-Findings im Dashboard nicht
+> mehr, weil unsere ID's dieselben sind — aber wir melden noch nichts.
+> User sieht "alles bekannt", nur wenige Findings (die SCA schon hat).
+
+### Phase 1 — Lexical + Single-Node-AST (Kat A+B, ~50 Rules, 2 Wochen) 🅑
+
+Triviale Detektoren — Pattern matched 1:1 unsere bestehenden.
+
+**Kat A (Lexical, Regex/Substring, ~20 Rules)**:
+
+`CommentRegularExpression`, `StringLiteralRegularExpression`, `TabulationCharacter`, `TrailingWhitespace`, `TooLongLine`, `CommentedOutCode`, `LowercaseKeyword`, `MissingSemicolon`, `SuperfluousSemicolon`, `RedundantParentheses`, `TrailingCommaArgumentList`, `DigitGrouping`, `DigitSeparator`, `NoSonar`, `MixedNames`, `InlineAssembly`, `LegacyInitializationSection`, `UnitLevelKeywordIndentation`, `VisibilityKeywordIndentation`, `PascalStyleResult`
+
+**Vorlage**: [`uTodoComment.pas`](StaticCodeAnalyserForm/sources/Detectors/uTodoComment.pas), [`uHardcodedPath.pas`](StaticCodeAnalyserForm/sources/Detectors/uHardcodedPath.pas), [`uMagicNumbers.pas`](StaticCodeAnalyserForm/sources/Detectors/uMagicNumbers.pas).
+**Aufwand**: 1-2 h pro Rule.
+
+**Kat B (AST single-node, ~30 Rules)**:
+
+`EmptyArgumentList`, `EmptyBlock`, `EmptyFieldSection`, `EmptyFile`, `EmptyFinallyBlock`, `EmptyInterface`, `EmptyVisibilitySection`, `GotoStatement`, `GroupedFieldDeclaration`, `GroupedParameterDeclaration`, `GroupedVariableDeclaration`, `MemberDeclarationOrder`, `VisibilitySectionOrder`, `ConsecutiveConstSection`, `ConsecutiveTypeSection`, `ConsecutiveVarSection`, `ConsecutiveVisibilitySection`, `BeginEndRequired`, `CaseStatementSize`, `EmptyRoutine` (✅ haben wir), `RedundantBoolean`, `RedundantJump`, `ExplicitBitwiseNot`, `AssertMessage`, `PublicField`, `ProjectFileRoutine`, `ProjectFileVariable`, `ExplicitTObjectInheritance`, `EmptyInterface`, `ClassPerFile`
+
+**Vorlage**: [`uEmptyMethod.pas`](StaticCodeAnalyserForm/sources/Detectors/uEmptyMethod.pas) (74 Zeilen), [`uDebugOutput.pas`](StaticCodeAnalyserForm/sources/Detectors/uDebugOutput.pas), [`uReversedForRange.pas`](StaticCodeAnalyserForm/sources/Detectors/uReversedForRange.pas).
+**Aufwand**: 2-4 h pro Rule.
+
+**Acceptance Phase 1**:
+- [ ] DUnitX-Tests pro Rule mit SonarDelphi-Fixture-Files als Truth (aus `delphi-checks/src/test/resources/au/com/integradev/delphi/checks/<RuleName>/`)
+- [ ] Shadow-Run: 50 Rules sollten matching Findings produzieren
+
+### Phase 2 — Configurable Forbidden + Naming-Conventions (Framework, ~25 Rules, 1 Woche) 🅒
+
+**Diese 25 Rules teilen sich 2 Frameworks** — bauen wir die zwei, kriegen wir 25 Rules.
+
+**Framework A — `TForbiddenChecker<T>`** (10 Rules):
+
+`ForbiddenConstant`, `ForbiddenEnumValue`, `ForbiddenField`, `ForbiddenIdentifier`, `ForbiddenImportFilePattern`, `ForbiddenProperty`, `ForbiddenRoutine`, `ForbiddenType`, plus die zwei Regex-Tracker (`CommentRegularExpression`, `StringLiteralRegularExpression`).
+
+Pattern: Config-Liste in `analyser.ini` `[ForbiddenIdentifiers]`, `[ForbiddenRoutines]`, etc. Vorlage existiert teilweise in [`uDfmForbiddenClass.pas`](StaticCodeAnalyserForm/sources/Detectors/uDfmForbiddenClass.pas).
+
+**Framework B — `TNamingConventionChecker`** (16 Rules):
+
+`AttributeName`, `ClassName`, `ConstantName`, `ConstructorName`, `DestructorName`, `EnumName`, `FieldName`, `HelperName`, `InheritedTypeName`, `InterfaceName`, `PointerName`, `RecordName`, `RoutineName`, `ShortIdentifier`, `UnitName`, `VariableName`
+
+Pattern: ein Regex pro Naming-Kind, Default-Patterns aus SonarDelphi übernehmen (z.B. `T[A-Z][a-zA-Z0-9]*` für Class). Config-Override per `analyser.ini`.
+
+**Acceptance Phase 2**: SonarDelphi-Default-Naming-Profile produziert identische Findings wie unser.
+
+### Phase 3 — AST Multi-Node + Cross-Unit (Kat C+D, ~35 Rules, 3 Wochen) 🅓
+
+**Kat C — AST multi-node matching, ~20 Rules**:
+
+`FormatArgumentCount` (✅ ähnlich vorhanden in `uFormatMismatch`), `FormatArgumentType`, `FormatStringValid`, `IfThenShortCircuit`, `LoopExecutingAtMostOnce`, `RedundantAssignment`, `RedundantInherited`, `MissingRaise`, `RaisingRawException`, `CatchingRawException`, `ReRaiseException`, `SwallowedException` (✅ ähnlich `uCodeSmells2/EmptyExcept`), `NilComparison`, `InstanceInvokedConstructor`, `InterfaceGuid`, `ObjectType`, `ObjectPassedAsInterface`, `ExplicitDefaultPropertyReference`, `RedundantCast`, `IndexLastListElement`
+
+**Vorlagen**: [`uFormatMismatch.pas`](StaticCodeAnalyserForm/sources/Detectors/uFormatMismatch.pas), [`uTautologicalExpr.pas`](StaticCodeAnalyserForm/sources/Detectors/uTautologicalExpr.pas), [`uMissingFinally.pas`](StaticCodeAnalyserForm/sources/Detectors/uMissingFinally.pas).
+
+**Kat D — Cross-Unit (Symbol-Index nötig), ~15 Rules**:
+
+`UnusedConstant`, `UnusedField`, `UnusedGlobalVariable`, `UnusedImport` (✅ `uUnusedUses`), `UnusedProperty`, `UnusedRoutine`, `UnusedType`, `UnusedLocalVariable` (✅ `uUnusedLocal`), `UnusedParameter` (✅), `TooManyDefaultParameters`, `TooManyVariables`, `TooManyNestedRoutines`, `FullyQualifiedImport`, `ImportSpecificity`, `TypeAlias`, `UnspecifiedReturnType`
+
+**Vorlage**: [`uVisibilityCheck.pas`](StaticCodeAnalyserForm/sources/Detectors/uVisibilityCheck.pas) (nutzt `SymbolReferenceIndex`), [`uUnusedUses.pas`](StaticCodeAnalyserForm/sources/Detectors/uUnusedUses.pas).
+
+**Acceptance Phase 3**: Cross-Unit-Coverage matched SonarDelphi's `UnusedX`-Familie.
+
+### Phase 4 — Inline-Declarations + Inheritance (Kat F + Modern Delphi, ~12 Rules, 2 Wochen) 🅔
+
+**Inline-Declarations (Delphi 10.3+, 5 Rules)**:
+
+`InlineConstExplicitType`, `InlineVarExplicitType`, `InlineLoopVarExplicitType`, `InlineDeclarationCapturedByAnonymousMethod`, `AddressOfNestedRoutine`
+
+**Inheritance-Index nötig** (7 Rules):
+
+`ConstructorWithoutInherited`, `DestructorWithoutInherited`, `InheritedMethodWithNoCode`, `RedundantInherited`, `InheritedTypeName`, `ExplicitTObjectInheritance` (Bonus zu Phase 1), `EmptyInterface`
+
+**Vorab-Investition**: Neue Unit `uClassHierarchyIndex.pas` analog [`uSymbolReferenceIndex.pas`](StaticCodeAnalyserForm/sources/Infrastructure/uSymbolReferenceIndex.pas) — baut `ClassName -> ParentChain` Repo-weit. ~2 Tage Vorlauf.
+
+**Acceptance Phase 4**: `class(TFoo)` Vererbung wird über Unit-Grenzen resolved.
+
+### Phase 5 — Type-Flow (Kat E, ~17 Rules, **OPTIONAL** 4 Wochen) 🅕
+
+**Hard — braucht Type-Registry**:
+
+`AddressOfCharacterData`, `CastAndFree`, `CharacterToCharacterPointerCast`, `FreeAndNilTObject`, `NonLinearCast`, `PlatformDependentCast`, `PlatformDependentTruncation`, `UnicodeToAnsiCast`, `MathFunctionSingleOverload`, `IterationPastHighBound`, `StringListDuplicates`, `DateFormatSettings`, `ImplicitDefaultEncoding`, `AssignedAndFree`, `VariableInitialization`, `CognitiveComplexityRoutine`, `RoutineResultAssigned`
+
+**Vorab-Investition**: `uTypeRegistry.pas` mit Cross-Unit-Type-Resolution. ~1 Woche.
+
+**Workaround ohne Type-Registry**: pattern-match auf bekannte Type-Names als Negativliste — liefert ~70 % Coverage. Akzeptabel für Phase 5 zum Start, später durch echte Type-Registry ersetzen.
+
+**Diese Phase ist nicht teil des 110 %-Coverage-Ziels** wenn der Aufwand zu hoch ist — SonarDelphi selbst hat hier die höchste False-Positive-Rate. Wir können diese 17 Rules im Catalog als "deferred" markieren und kommunizieren.
+
+## Cross-cutting Tasks
+
+### Shadow-Run-Infrastruktur (1 Tag)
+
+- [ ] Bash/PowerShell-Script `tools/shadow-diff-sonardelphi.ps1`:
+  1. Test-Corpus (z.B. Embarcadero-Samples + unser Repo) gegen SonarDelphi pushen (Pfad: sonar-scanner mit SonarDelphi-Plugin)
+  2. Gleichen Corpus gegen SCA pushen (`sonar-scan.ps1` + `sonar-upload.ps1`)
+  3. Diff der Findings nach `(file, line, ruleId-equivalent)` via Mapping-Tabelle in `tools/sonardelphi-rule-mapping.json`
+  4. Output: "SonarDelphi-only findings: X (REGRESSIONS)" / "SCA-only: Y (OK)" / "Matched: Z"
+- [ ] Mapping-Tabelle: SCA-RuleID ↔ SonarDelphi-RuleKey pflegen während Migration
+
+### Drift-Test gegen 110 %-Ziel
+
+- [ ] Neuer Test `uTestCoverageGap.pas`: lädt SonarDelphi-Rule-Inventar (statisches JSON checked-in als `tests/data/sonardelphi-rules-v1.18.3.json`), prüft pro Rule-Key ob ein SCA-Mapping-Eintrag existiert. Fehlende Mappings: Test rot.
+
+### Test-Fixture-Import
+
+- [ ] `tools/import-sonardelphi-fixtures.ps1` cloned SonarDelphi-Repo, kopiert `delphi-checks/src/test/resources/au/com/integradev/delphi/checks/<RuleName>/*.pas` als `tests/fixtures/sonardelphi/<RuleName>/`. Lizenz-Compliance: Header beachten, Quelle dokumentieren.
+
+## Out of Scope
+
+- **GUI** für SonarDelphi-Rule-Verwaltung — `analyser.ini` reicht für Phase 0-4
+- **Quality-Profile-Migration** — SonarQube-seitig, wir liefern nur Findings
+- **Auto-Fix-Suggestions** für SonarDelphi-Rules — separater Sprint
+- **Reverse-Migration** (SCA → SonarDelphi-Plugin) — explizit nicht das Ziel
+
+## Empfehlung — Reihenfolge
+
+| Phase | Items | Aufwand | ROI |
+|---|---|---|---|
+| **0** Catalog-First | 144 Rule-IDs + KIND_META + JSON | 1 d | Sofort: Sonar-Push akzeptiert alles |
+| **1** Lexical + Single-Node | 50 Rules (Kat A+B) | 2 w | Volumen-Gewinn, einfache Migration |
+| **2** Forbidden + Naming-Framework | 25 Rules über 2 Frameworks | 1 w | Hohe Rule-Anzahl pro Code-Aufwand |
+| **3** Multi-Node + Cross-Unit | 35 Rules (Kat C+D) | 3 w | Substanz, nutzt vorhandene Infrastruktur |
+| **4** Inline + Inheritance | 12 Rules + Hierarchy-Index | 2 w | Modern-Delphi-Coverage |
+| **5** Type-Flow (optional) | 17 Rules + Type-Registry | 4 w | High-FP-rate, separat planen |
+
+**Total ohne Phase 5: ~9 Wochen für ~122 portierte Rules** plus die existierenden 22 Overlaps = **144 = 100 % SonarDelphi-Coverage**. Plus unsere 37 unique → **110 % erreicht**.
+
+Mit Phase 5: ~13 Wochen für **161 Rules total** = **112 %**.
+
+**Strikte Abhängigkeit**: Phase 0 vor allem anderen. Phase 4 braucht den Hierarchy-Index (Vorinvestition). Phase 5 braucht Type-Registry (separate Entscheidung).
+
+---
+
+## Sources
+
+- [SonarDelphi v1.18.3 Repo](https://github.com/integrated-application-development/sonar-delphi/tree/v1.18.3) — 144 Rules, ANTLR3-AST
+- Rule JSONs: `delphi-checks/src/main/resources/org/sonar/l10n/delphi/rules/community-delphi/*.json`
+- Check-Implementations: `delphi-checks/src/main/java/au/com/integradev/delphi/checks/*Check.java`
+- Test-Fixtures: `delphi-checks/src/test/resources/au/com/integradev/delphi/checks/<RuleName>/`
+- Unsere Rule-Liste: [`rules/sca-rules.json`](rules/sca-rules.json) (59 Regeln, MQR-tauglich)
+- Bestehender Sonar-Workflow: [`sonarHowto.md`](sonarHowto.md), [`StaticCodeAnalyserForm/scripts/`](StaticCodeAnalyserForm/scripts/)
+- Verwandter TODO: [`todo-sonar.md`](todo-sonar.md) (Sonar-Integration — abgeschlossen mit v0.9.1)