Skip to content

Commit 5afe54c

Browse files
tomtastischgithub-actions[bot]Copilot
authored
refactor(filetypedetection): policy-045 strukturell und dokumentarisch durchgezogen (#82)
* refactor(filetypedetection): code-quality-policy 045 auf alle klassen angewendet * refactor(filetypedetection): remove redundant `Global` qualifiers and align variable names with code-quality policies * ci(preflight): re-trigger with updated pr governance body * ci(preflight): trigger run after pr-body governance fix * refactor(filetypedetection): evidencehashing whitespace policy-konform formatieren * Update src/FileTypeDetection/Infrastructure/ArchiveManagedInternals.vb Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Tomtastisch <82227609+tomtastisch@users.noreply.github.com> * Update src/FileTypeDetection/Infrastructure/CoreInternals.vb Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Tomtastisch <82227609+tomtastisch@users.noreply.github.com> * Update src/FileTypeDetection/Infrastructure/ArchiveManagedInternals.vb Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Tomtastisch <82227609+tomtastisch@users.noreply.github.com> * fix(filetypedetection): review-fixes fuer catch-filter und policy 045 * docs(policy): .MD konvergenz und docs-links-full fix * docs(policy): roc-bijection mapping fuer policy 045/145 --------- Signed-off-by: Tomtastisch <82227609+tomtastisch@users.noreply.github.com> Co-authored-by: GitHub Copilot Agent <github-actions[bot]@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent aec1ce0 commit 5afe54c

23 files changed

Lines changed: 1258 additions & 41 deletions

‎docs/governance/045_CODE_QUALITY_POLICY_DE.MD‎

Lines changed: 760 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/governance/145_CODE_QUALITY_POLICY_DE.MD‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
<!-- LANG_SWITCH:BEGIN -->
2+
[DE](045_CODE_QUALITY_POLICY_DE.MD) | [EN](145_CODE_QUALITY_POLICY_DE.MD)
3+
<!-- LANG_SWITCH:END -->
4+
5+
# Code Quality & Documentation Policy (EN)
6+
Status: binding (project policy)
7+
Scope: `src/FileTypeDetection/*` (VB.NET and C#), public API + internal implementation
8+
9+
## 1. Purpose
10+
This policy defines a consistent, auditable schema for:
11+
- code structure (readability, semantics, member ordering)
12+
- error handling (fail-closed, consistent logging)
13+
- documentation (German for public API, complete, with real umlauts)
14+
- reproducible Codex changes without behavioral drift
15+
16+
## 2. Normative Orientation (DIN/ISO/IEC/IEEE)
17+
Note: there is no single “DIN for code formatting”. This is an internal rule set aligned with established standards for information quality and software quality:
18+
- ISO/IEC/IEEE 26514:2022-01
19+
- ISO/IEC 25010:2023
20+
- ISO/IEC/IEEE 15289:2019
21+
- optional: DIN EN IEC/IEEE 82079-1:2021-09
22+
23+
## 3. Hard Principles
24+
- Never transliterate German umlauts: `ä ö ü Ä Ö Ü ß` (no `ae/oe/ue/ss`).
25+
- Files remain UTF-8.
26+
- No behavior changes through formatting/docs:
27+
- no signature changes
28+
- no semantic changes in exceptions/returns/side effects
29+
- no new external dependencies
30+
31+
## 4. Shared vs. Instance (Construction Rule)
32+
### 4.1 Shared (utility) is allowed only if all are true
33+
- type is stateless
34+
- no DI or swappable dependencies needed
35+
- no polymorphism/test doubles via interfaces needed
36+
- typically: `NotInheritable` + `Private Sub New()` + only shared members
37+
38+
### 4.2 Instance/service type is mandatory if at least one applies
39+
- dependencies should be injectable/swappable (I/O, logger, policy, clock, provider, ...)
40+
- testability via DI/interfaces is required
41+
- per-instance state/configuration is meaningful
42+
43+
Within style/docs-only updates, type kind must not be changed unless already clearly established as utility/service.
44+
45+
## 5. File and Type Structure
46+
### 5.1 File order
47+
1) file header comment (policy/context block, not XML docs)
48+
2) `Option Strict On` / `Option Explicit On` (VB)
49+
3) imports
50+
4) namespace
51+
5) types
52+
53+
### 5.2 Type layout (member order)
54+
1) XML docs on type (`summary` + `remarks`)
55+
2) constants (`Const`) / `Shared ReadOnly`
56+
3) fields/properties (only when type state exists)
57+
4) constructors
58+
5) public API (all public members, ordered)
59+
6) internal/private helpers
60+
7) nested types (only if needed; at end)
61+
62+
### 5.3 Semantic blocks in methods
63+
Use visible block separation (empty line + block comment markers):
64+
- options/snapshot
65+
- guard clauses (fail-closed)
66+
- normalization/canonicalization
67+
- branches (for example secure extraction)
68+
- fallback
69+
- I/O helpers separated
70+
71+
## 6. Variable Rule
72+
- All local variables are declared in a declaration block at the start of the function.
73+
- Placement:
74+
- function-local when only needed there
75+
- class-level only when shared across members by design
76+
- Alignment: column-style (`Dim` / name / `As` / initializer) using tabs/spaces.
77+
- Exception: `Using`/`For` headers may contain local variables when idiomatic and more readable.
78+
79+
## 6.1 Naming Conventions (VB.NET + C#)
80+
- Public API is a contract and must be convention-compliant.
81+
- No umlauts in identifiers.
82+
- No underscores in public API names (except required interop contracts).
83+
- Avoid unclear abbreviations in public API.
84+
- Keep PascalCase for namespaces/types/public members.
85+
- Parameters/locals: camelCase.
86+
- Private fields: `_camelCase` (or existing repo SSOT if different).
87+
- Boolean names should be positive and use `is/has/can/should` where applicable.
88+
- `Async` suffix only for true async semantics.
89+
90+
## 7. Exception Handling & Logging (Fail-Closed)
91+
- Prefer catch filter form in VB: `Catch ex As Exception When TypeOf ex Is ...`
92+
- Forbidden redundant pseudo-filter: `Catch ex As Exception When TypeOf ex Is Exception`
93+
If all exceptions must be handled, use `Catch ex As Exception` instead.
94+
- No unfiltered catch-all unless technically required and documented.
95+
- No silent swallow: log (`Warn`/`Error`) and preserve prior fail-closed behavior.
96+
- Keep log wording consistent (German with proper umlauts in this project).
97+
- No exception semantics change (no new wrapping, no new throws).
98+
99+
## 8. Documentation Standard (Public API)
100+
### 8.1 Language/characters
101+
- German language for public API docs.
102+
- Real umlauts, no transliteration.
103+
104+
### 8.2 Minimum per public type/member
105+
- Type:
106+
- `<summary>`: 1-3 sentences (purpose/scope)
107+
- `<remarks>`: structured sections (purpose, responsibilities, non-goals, side effects, error cases, security notes, threading if relevant)
108+
- Public methods/functions:
109+
- `<summary>`, all `<param>`, always `<returns>`
110+
- `<exception>` only if actually propagated by API contract; otherwise describe fail-closed behavior in remarks
111+
- `<example>` when useful
112+
113+
### 8.3 “DIN-/standard-oriented” means
114+
- precise wording
115+
- consistent terminology
116+
- explicit error paths and side effects
117+
118+
## 9. Definition of Done (DoD)
119+
For each file in `src/FileTypeDetection/*`:
120+
- layout complies with sections 5-7
121+
- public API documented per section 8
122+
- umlauts preserved (no `ae/oe/ue` transliteration)
123+
- build/tests successful
124+
- no public signature changes
125+
- no behavior drift (no new dependencies, no semantic changes)
126+
127+
## 10. Style Reference (SSOT)
128+
The authoritative style/semantics template is the reference block in `docs/governance/045_CODE_QUALITY_POLICY_DE.MD` section “10. STYLE REFERENCE (SSOT)”.
129+
Apply that schema to all files in `src/FileTypeDetection/*`.
130+
Deviations are allowed only when technically required and must be justified in diff summary.
131+
132+
## Source of Truth Note
133+
This English edition is provided for accessibility. If wording differs, the German policy file
134+
`docs/governance/045_CODE_QUALITY_POLICY_DE.MD` is authoritative.
135+
136+
## 11. Policy/RoC Mapping (CI)
137+
This policy is mapped in the CI RoC matrix to the following rule files:
138+
- `tools/ci/policies/rules/artifact_contract.yaml`
139+
- `tools/ci/policies/rules/docs_drift.yaml`
140+
- `tools/ci/policies/rules/naming_snt.yaml`
141+
- `tools/ci/policies/rules/shell_safety.yaml`
142+
- `tools/ci/policies/rules/versioning_svt.yaml`

‎src/FileTypeDetection/Abstractions/Archive/ZipExtractedEntry.vb‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
' ============================================================================
2+
' FILE: ZipExtractedEntry.vb
3+
'
4+
' INTERNE POLICY (DIN-/Norm-orientiert, verbindlich)
5+
' - Datei- und Type-Struktur gemäß docs/governance/045_CODE_QUALITY_POLICY_DE.MD
6+
' - Try/Catch konsistent im Catch-Filter-Schema
7+
' - Variablen im Deklarationsblock, spaltenartig ausgerichtet
8+
' ============================================================================
9+
110
Option Strict On
211
Option Explicit On
312

‎src/FileTypeDetection/Abstractions/Detection/DetectionDetail.vb‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
' ============================================================================
2+
' FILE: DetectionDetail.vb
3+
'
4+
' INTERNE POLICY (DIN-/Norm-orientiert, verbindlich)
5+
' - Datei- und Type-Struktur gemäß docs/governance/045_CODE_QUALITY_POLICY_DE.MD
6+
' - Try/Catch konsistent im Catch-Filter-Schema
7+
' - Variablen im Deklarationsblock, spaltenartig ausgerichtet
8+
' ============================================================================
9+
110
Option Strict On
211
Option Explicit On
312

‎src/FileTypeDetection/Abstractions/Detection/FileKind.vb‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
' ============================================================================
2+
' FILE: FileKind.vb
3+
'
4+
' INTERNE POLICY (DIN-/Norm-orientiert, verbindlich)
5+
' - Datei- und Type-Struktur gemäß docs/governance/045_CODE_QUALITY_POLICY_DE.MD
6+
' - Try/Catch konsistent im Catch-Filter-Schema
7+
' - Variablen im Deklarationsblock, spaltenartig ausgerichtet
8+
' ============================================================================
9+
110
Option Strict On
211
Option Explicit On
312
Option Infer On

‎src/FileTypeDetection/Abstractions/Detection/FileType.vb‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
' ============================================================================
2+
' FILE: FileType.vb
3+
'
4+
' INTERNE POLICY (DIN-/Norm-orientiert, verbindlich)
5+
' - Datei- und Type-Struktur gemäß docs/governance/045_CODE_QUALITY_POLICY_DE.MD
6+
' - Try/Catch konsistent im Catch-Filter-Schema
7+
' - Variablen im Deklarationsblock, spaltenartig ausgerichtet
8+
' ============================================================================
9+
110
Option Strict On
211
Option Explicit On
312

‎src/FileTypeDetection/Abstractions/Hashing/HashDigestSet.vb‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
' ============================================================================
2+
' FILE: HashDigestSet.vb
3+
'
4+
' INTERNE POLICY (DIN-/Norm-orientiert, verbindlich)
5+
' - Datei- und Type-Struktur gemäß docs/governance/045_CODE_QUALITY_POLICY_DE.MD
6+
' - Try/Catch konsistent im Catch-Filter-Schema
7+
' - Variablen im Deklarationsblock, spaltenartig ausgerichtet
8+
' ============================================================================
9+
110
Option Strict On
211
Option Explicit On
312

‎src/FileTypeDetection/Abstractions/Hashing/HashEvidence.vb‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
' ============================================================================
2+
' FILE: HashEvidence.vb
3+
'
4+
' INTERNE POLICY (DIN-/Norm-orientiert, verbindlich)
5+
' - Datei- und Type-Struktur gemäß docs/governance/045_CODE_QUALITY_POLICY_DE.MD
6+
' - Try/Catch konsistent im Catch-Filter-Schema
7+
' - Variablen im Deklarationsblock, spaltenartig ausgerichtet
8+
' ============================================================================
9+
110
Option Strict On
211
Option Explicit On
312

@@ -33,12 +42,12 @@ Namespace Global.Tomtastisch.FileClassifier
3342
''' <summary>
3443
''' Optional mitgeführte komprimierte Bytes.
3544
''' </summary>
36-
Public ReadOnly Property CompressedBytes As Global.System.Collections.Immutable.ImmutableArray(Of Byte)
45+
Public ReadOnly Property CompressedBytes As Immutable.ImmutableArray(Of Byte)
3746

3847
''' <summary>
3948
''' Optional mitgeführte unkomprimierte bzw. logische Bytes.
4049
''' </summary>
41-
Public ReadOnly Property UncompressedBytes As Global.System.Collections.Immutable.ImmutableArray(Of Byte)
50+
Public ReadOnly Property UncompressedBytes As Immutable.ImmutableArray(Of Byte)
4251

4352
''' <summary>
4453
''' Anzahl berücksichtigter Entries im Nachweis.
@@ -98,11 +107,11 @@ Namespace Global.Tomtastisch.FileClassifier
98107
notes:=notes)
99108
End Function
100109

101-
Private Shared Function ToImmutable(data As Byte()) As Global.System.Collections.Immutable.ImmutableArray(Of Byte)
110+
Private Shared Function ToImmutable(data As Byte()) As Immutable.ImmutableArray(Of Byte)
102111
If data Is Nothing OrElse data.Length = 0 Then
103-
Return Global.System.Collections.Immutable.ImmutableArray(Of Byte).Empty
112+
Return Immutable.ImmutableArray(Of Byte).Empty
104113
End If
105-
Return Global.System.Collections.Immutable.ImmutableArray.Create(data)
114+
Return Immutable.ImmutableArray.Create(data)
106115
End Function
107116
End Class
108117
End Namespace

‎src/FileTypeDetection/Abstractions/Hashing/HashOptions.vb‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,17 @@
1+
' ============================================================================
2+
' FILE: HashOptions.vb
3+
'
4+
' INTERNE POLICY (DIN-/Norm-orientiert, verbindlich)
5+
' - Datei- und Type-Struktur gemäß docs/governance/045_CODE_QUALITY_POLICY_DE.MD
6+
' - Try/Catch konsistent im Catch-Filter-Schema
7+
' - Variablen im Deklarationsblock, spaltenartig ausgerichtet
8+
' ============================================================================
9+
110
Option Strict On
211
Option Explicit On
312

13+
Imports System.Diagnostics.CodeAnalysis
14+
415
Namespace Global.Tomtastisch.FileClassifier
516
''' <summary>
617
''' Konfiguriert das Verhalten der öffentlichen deterministischen Hashing-APIs.
@@ -49,19 +60,20 @@ Namespace Global.Tomtastisch.FileClassifier
4960
Return cloned
5061
End Function
5162

63+
<SuppressMessage("Usage", "CA2249:Use 'string.Contains' instead of 'string.IndexOf' to improve readability", Justification:="IndexOf bleibt hier für deterministische Zeichenprüfung ohne Semantikänderung bestehen.")>
5264
Private Shared Function NormalizeMaterializedFileName(candidate As String) As String
5365
Dim normalized = If(candidate, String.Empty).Trim()
5466
If String.IsNullOrWhiteSpace(normalized) Then Return "deterministic-roundtrip.bin"
5567

5668
Try
57-
normalized = Global.System.IO.Path.GetFileName(normalized)
69+
normalized = IO.Path.GetFileName(normalized)
5870
Catch
5971
Return "deterministic-roundtrip.bin"
6072
End Try
6173

6274
If String.IsNullOrWhiteSpace(normalized) Then Return "deterministic-roundtrip.bin"
6375

64-
For Each invalidChar In Global.System.IO.Path.GetInvalidFileNameChars()
76+
For Each invalidChar In IO.Path.GetInvalidFileNameChars()
6577
If normalized.IndexOf(invalidChar) >= 0 Then
6678
Return "deterministic-roundtrip.bin"
6779
End If

‎src/FileTypeDetection/Abstractions/Hashing/HashRoundTripReport.vb‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
' ============================================================================
2+
' FILE: HashRoundTripReport.vb
3+
'
4+
' INTERNE POLICY (DIN-/Norm-orientiert, verbindlich)
5+
' - Datei- und Type-Struktur gemäß docs/governance/045_CODE_QUALITY_POLICY_DE.MD
6+
' - Try/Catch konsistent im Catch-Filter-Schema
7+
' - Variablen im Deklarationsblock, spaltenartig ausgerichtet
8+
' ============================================================================
9+
110
Option Strict On
211
Option Explicit On
312

0 commit comments

Comments
 (0)