refactor(filetypedetection): policy-045 strukturell und dokumentarisch durchgezogen

[tomtastisch]

Ziel & Scope

• Verbindliche Umsetzung der Policy docs/governance/045_CODE_QUALITY_POLICY_DE.md über alle Klassen/Typen unter src/FileTypeDetection/*.
• Fokus auf Struktur, Dokumentation, Catch-Filter-Konsistenz, Header-Konvergenz und formatbezogene Härtung ohne API-Drift.

Umgesetzte Aufgaben (abhaken)

• docs/governance/045_CODE_QUALITY_POLICY_DE.md als verbindliche Policy im Branch enthalten.
• docs/governance/145_CODE_QUALITY_POLICY_DE.md als englische Version inkl. LANG_SWITCH ergänzt.
• Alle *.vb unter src/FileTypeDetection/* mit einheitlichem Policy-Dateiheader versehen.
• Catch-Schema auf Catch-Filter-Form vereinheitlicht (Catch ex As Exception When ...).
• Fehlende XML-Typdokumentation für öffentliche und interne Typen ergänzt.
• Öffentliche Member-Dokumentation in internen Archiv-Backends/-Modellen ergänzt.
• Kommentar-/XML-Umlaute konsolidiert (keine ae/oe/ue-Umschreibung).
• Build und Tests lokal vollständig grün ausgeführt.
• Keine Public-Signaturdrift im Diff (src/FileTypeDetection).
• Keine neuen Dependencies/Package-Änderungen eingeführt.

Nachbesserungen aus Review (iterativ)

• Fehlerhaften Zwischenversuch zur Deklarationsverschiebung vollständig verworfen.
• Stabilen Policy-Pass deterministisch neu ausgeführt.
• Kritische Datei src/FileTypeDetection/FileTypeDetector.vb separat verifiziert (Diff + Einzelbuild).

Security- und Merge-Gates

• security/code-scanning/tools: als Merge-Gate berücksichtigt; Zielzustand ist 0 offene Alerts.
• Merge erst bei grünem Required-Checks-Status, ohne offene Review-Threads und mit branch-protection-konformem Merge.

Evidence (auditierbar)

• dotnet build FileClassifier.sln
• dotnet test FileClassifier.sln --no-build
• dotnet build src/FileTypeDetection/FileTypeDetectionLib.vbproj -f net10.0
• rg -n "^\s*Catch\s+ex As Exception\s*$" src/FileTypeDetection -g "*.vb" (keine Treffer)
• for f in $(rg --files src/FileTypeDetection -g "*.vb"); do head -n 1 "$f" | rg -q "^' ============================================================================" || echo "NOHEADER $f"; done (keine Treffer)
• git diff -- src/FileTypeDetection | rg "^[+-].*\bPublic\b" (kein Treffer)
• git diff -- '*.vbproj' 'Directory.Packages.props' 'packages.lock.json' 'Directory.Build.props' (leer)

DoD (mindestens 2 pro Punkt)

Punkt	DoD A	DoD B
Header-/Struktur-Konvergenz	Jede Datei in src/FileTypeDetection/*.vb startet mit Policy-Header	dotnet build ohne Fehler/Warnungen
Catch-Filter-Konsistenz	Keine unfilterten Catch ex As Exception-Treffer	Testsuite grün (413/413)
Doku-Konvergenz	XML-Typdoku für fehlende Typen ergänzt	Öffentliche Member-Doku in Archiv-Backends/-Modellen ergänzt
Safety/Drift	Keine Public-Signatur-Diff-Hits	Keine Dependency-Dateien geändert

[Copilot]

Pull request overview

This PR implements a comprehensive code quality and documentation policy (Policy-045) across the src/FileTypeDetection namespace. The policy defines standardized file structure, error handling patterns, documentation requirements, and formatting conventions inspired by DIN/ISO/IEC/IEEE standards.

Changes:

• Added two policy documents (DE and EN versions) defining binding conventions for code structure, error handling, and documentation
• Added standardized file headers to all VB.NET files in FileTypeDetection
• Updated catch blocks to use catch filter syntax (Catch ex As Exception When ...)
• Added XML documentation to internal types and members
• Consolidated German umlauts in comments (removed ae/oe/ue transliterations)
• Applied column-style variable alignment in declaration blocks

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 24 comments.

Show a summary per file

File	Description
docs/governance/045_CODE_QUALITY_POLICY_DE.md	New German policy document defining code quality standards (749 lines)
docs/governance/145_CODE_QUALITY_POLICY_DE.md	New English translation of the policy document (132 lines)
src/FileTypeDetection/Infrastructure/MimeProvider.vb	Added header, updated umlauts in comments
src/FileTypeDetection/Infrastructure/CoreInternals.vb	Added header, type documentation, catch filter, variable alignment
src/FileTypeDetection/Infrastructure/ArchiveManagedInternals.vb	Added header, type/member docs, catch filters
src/FileTypeDetection/Infrastructure/ArchiveInternals.vb	Added header, extensive type docs for enums/interfaces/classes, catch filters, variable alignment
src/FileTypeDetection/FileTypeOptions.vb	Added header, catch filter
src/FileTypeDetection/FileTypeDetector.vb	Added header, catch filters, structure documentation
src/FileTypeDetection/FileMaterializer.vb	Added header, Security.SecurityException namespace simplification, variable alignment
src/FileTypeDetection/EvidenceHashing.vb	Added header, catch filters, variable alignment, class documentation
src/FileTypeDetection/Detection/FileTypeRegistry.vb	Added header, updated umlauts, structure documentation
src/FileTypeDetection/Configuration/*.vb	Added headers to FileTypeProjectOptions and FileTypeProjectBaseline
src/FileTypeDetection/ArchiveProcessing.vb	Added header
src/FileTypeDetection/Abstractions//.vb	Added headers to all abstraction files (Hashing, Detection, Archive namespaces)

[tomtastisch]

Follow-up umgesetzt in Commit 6f8eb03:

• Alle redundanten Catch-Filter When TypeOf ex Is Exception unter src/FileTypeDetection/* entfernt.
• Policy präzisiert: Pattern jetzt explizit verboten in Abschnitt 7 (docs/governance/045_CODE_QUALITY_POLICY_DE.md, docs/governance/145_CODE_QUALITY_POLICY_DE.md).
• XML-Doku für ArchiveDescriptor, SharpCompressArchiveBackend, ArchiveManagedBackend und ArchiveManagedEntryModel inhaltlich geschärft.
• Tote Variable errorMessage in FileMaterializer entfernt und Logging auf ex.Message korrigiert.

Lokal verifiziert mit dotnet format FileClassifier.sln --verify-no-changes, dotnet build FileClassifier.sln, dotnet test FileClassifier.sln -c Release.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (5)

src/FileTypeDetection/FileTypeDetector.vb:362

• The catch-all uses Catch ex As Exception When TypeOf ex Is Exception, which is effectively unfiltered. Either drop the filter (and document that this is a deliberate compatibility/fail-closed catch-all) or use a meaningful filter; otherwise the extra catch block adds noise without changing behavior.

                End Using
            Catch ex As Exception When _
                TypeOf ex Is UnauthorizedAccessException OrElse
                TypeOf ex Is Security.SecurityException OrElse
                TypeOf ex Is IOException OrElse
                TypeOf ex Is InvalidDataException OrElse
                TypeOf ex Is NotSupportedException OrElse
                TypeOf ex Is ArgumentException
                Return False
            Catch ex As Exception
                ' Kompatibilitäts-Catch: unbekannte Ausnahme bleibt fail-closed.
                Return False

src/FileTypeDetection/FileTypeDetector.vb:915

• DetectionTrace is documented as an "unveränderlicher Datenträger", but its fields are mutable (Friend ReasonCode As String, etc.) and are modified later (e.g., trace.ReasonCode = ...). Please adjust the wording, or make the structure actually immutable (e.g., ReadOnly Structure + ReadOnly fields + constructor).

        ''' <summary>
        '''     Interner, unveränderlicher Datenträger <c>DetectionTrace</c> für strukturierte Verarbeitungsschritte.
        ''' </summary>
        Private Structure DetectionTrace
            Friend ReasonCode As String
            Friend UsedZipContentCheck As Boolean
            Friend UsedStructuredRefinement As Boolean

src/FileTypeDetection/EvidenceHashing.vb:630

• This catch-all (Catch ex As Exception When TypeOf ex Is Exception) is redundant and currently sets the same "invalid Base64" note as the Format/ArgumentException case. Consider either removing the catch-all (let truly unexpected exceptions bubble) or changing the note/logging so unexpected failures aren’t misreported as Base64 format issues.

            Catch ex As Exception When _
                TypeOf ex Is FormatException OrElse
                TypeOf ex Is ArgumentException
                key = Array.Empty(Of Byte)()
                note = $"Secure hashing requested but env var '{HmacKeyEnvVarB64}' is invalid Base64; HMAC digests omitted."
                Return False
            Catch ex As Exception
                key = Array.Empty(Of Byte)()
                note = $"Secure hashing requested but env var '{HmacKeyEnvVarB64}' is invalid Base64; HMAC digests omitted."
                Return False

src/FileTypeDetection/FileTypeOptions.vb:220

• Catch ex As Exception When TypeOf ex Is Exception is equivalent to a catch-all and doesn’t add value here. If the goal is to swallow all remaining exceptions fail-closed, use a plain Catch ex As Exception and (optionally) log/debug to aid diagnosis; otherwise apply a meaningful filter.

            Catch ex As Exception
                Return False
            End Try

src/FileTypeDetection/Infrastructure/ArchiveInternals.vb:141

• Catch ex As Exception When TypeOf ex Is Exception is a tautology and behaves like an unfiltered catch-all, but reads like a meaningful filter. If this is intentionally a catch-all, prefer Catch ex As Exception plus an explanatory comment; otherwise replace with an actual filter (e.g., only the exception types you want to fail-closed on) so unexpected exceptions aren’t mislabeled/hidden.

            Try
                Using ms As New MemoryStream(data, writable:=False)
                    Return TryDescribeStream(ms, opt, descriptor)
                End Using
            Catch ex As Exception
                LogGuard.Debug(opt.Logger, $"[ArchiveDetect] Byte-Erkennung fehlgeschlagen: {ex.Message}")
                descriptor = ArchiveDescriptor.UnknownDescriptor()
                Return False

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/FileTypeDetection/FileTypeDetector.vb:916

• Die XML-Doku beschreibt DetectionTrace als „unveränderlich“, aber die Struktur hat veränderbare Felder (Friend ReasonCode As String etc.) und wird im Code auch mutiert (z. B. trace.ReasonCode = ...). Bitte entweder die Doku anpassen (z. B. „interner Trace-Datenträger“) oder die Struktur tatsächlich unveränderlich machen (ReadOnly-Felder/Constructor) – je nachdem, was hier beabsichtigt ist.

        ''' <summary>
        '''     Interner, unveränderlicher Datenträger <c>DetectionTrace</c> für strukturierte Verarbeitungsschritte.
        ''' </summary>
        Private Structure DetectionTrace
            Friend ReasonCode As String
            Friend UsedZipContentCheck As Boolean
            Friend UsedStructuredRefinement As Boolean

[Copilot]

In dieser Warnmeldung ist „Ungueltiger“ eine Umlaut-Umschreibung. Das widerspricht der eigenen Policy („keine ae/oe/ue“) und ist inkonsistent zu anderen aktualisierten Texten. Bitte auf „Ungültiger“ umstellen (und ggf. ähnliche Vorkommen konsolidieren, falls gewünscht).

Suggested change

	LogGuard.Warn(opt.Logger, $"[Materialize] Ungueltiger Zielpfad: {ex.Message}")
	LogGuard.Warn(opt.Logger, $"[Materialize] Ungültiger Zielpfad: {ex.Message}")

[Copilot]

Der Dateiheader behauptet „Try/Catch konsistent im Catch-Filter-Schema“, aber in dieser Datei gibt es weiterhin unfilterte Catch-Blöcke (z. B. Catch ex As Exception sowie Catch ohne Exception-Typ). Das steht auch im Widerspruch zur PR-Beschreibung/Evidence („keine Treffer“ für unfilterte Catches). Bitte entweder (a) Header/PR-Text präzisieren, dass Catch-All hier bewusst genutzt wird, oder (b) die Catch-Blöcke auf das gewünschte Filter-Schema umstellen (falls das tatsächlich Policy-Ziel ist).