Files
HashTool/docs/ARCHITECTURE.md
T
poli0981andClaude Opus 5.5 dcfe5c6b7c docs: maintenance mode
From 1.3.0 Hash Tool is in maintenance mode. What it accepts is written down once, in CONTRIBUTING.md ("Project
status"): security fixes (high/critical vulnerabilities in .NET or a dependency get a prompt release), dependency and
.NET updates, bug and UI/UX fixes, accessibility, translation fixes, and hash algorithms on real demand; no new
features unless truly necessary.

- README: maintenance, Qodana and .NET 10 LTS badges and a "Project status" section.
- CONTRIBUTING: the policy, the issue forms, and the hash algorithm candidates (BLAKE2b-512, SHA3-256/512, CRC-32C)
  with what each would take; ARCHITECTURE: a checklist for adding an algorithm.
- Issue forms: the feature request form is replaced by "Hash algorithm request" and "Translation problem"; feature
  ideas go to Discussions (Ideas). The accessibility form gives the email address for people who cannot use GitHub.
- Pull request template: the kinds of change that are accepted.
- SECURITY: 1.3.x supported, the security commitment during maintenance, Qodana among the checks.
- CLAUDE.md: the project status for agents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 09:20:51 +07:00

7.8 KiB
Raw Blame History

Architecture

HashTool is a .NET 10 solution with three shipped programs sharing one core library.

src/HashTool.Core   hashing, checksum files, folder walking, settings (no UI; trim/AOT compatible)
src/HashTool.App    Avalonia 12 desktop app (CheckHash.exe) — views, view models, services
src/HashTool.Cli    `hashtool` command-line tool (System.CommandLine, NativeAOT)
tests/              Core.Tests, Cli.Tests, App.Tests (Avalonia headless); Compat/LegacyClient (release gate)
bench/              BenchmarkDotNet benchmarks (run by hand)
eng/                scripts used by CI and releases (translations, coverage, release notes, package checks)
build/              packaging inputs (macOS Info.plist, Linux icon)

Shared build settings: Directory.Build.props (version, nullable, analyzers, NuGet audit), Directory.Packages.props (central package versions with transitive pinning), global.json (SDK and the Microsoft.Testing.Platform runner), .config/dotnet-tools.json (vpk, nuget-license, CycloneDX, SonarScanner for .NET, dotnet-coverage; Dependabot keeps them up to date).

HashTool.Core

Area Types Notes
Hashing HashEngine, HashType, HashAlgorithms, HashResult, HashMatcher, TextHashing One read per file for any number of algorithms: double-buffered reads (1 MiB, 4 MiB above 1 GiB), each block fed to every algorithm in parallel; BLAKE3 uses its multi-threaded update for large blocks. CRC32 is big-endian (as 7-Zip/SFV); HashMatcher still accepts the reversed order Hash Tool 1.1 wrote. TextHashing turns text into the bytes the Hash Text page and hashtool hash - hash: UTF-8/UTF-16 without a byte order mark, LF or CRLF line breaks, nothing appended.
Checksum files ChecksumParser, ChecksumWriter, ChecksumDocument, ChecksumFileNames Reads GNU (hash name, *name, escaped names), BSD tagged, SFV, xxhsum XXH3_ and bare sidecar hashes; writes GNU/BSD/SFV/JSON/CSV. The algorithm comes from the line, then the file name, then the user's choice, then the hash length. Paths may not point to UNC or device locations; CSV output neutralises formulas.
Files FileEnumerator, FileErrors Walks folders without following symbolic links or junctions, skips unreadable folders, optionally hidden files.
Processing BatchProcessor, HashJob, IHashJobObserver<T> Small files in parallel (default min(cores, 4)), files ≥ 1 GiB in a separate lane, one at a time in HDD mode; per-file time-out; every item is reported exactly once.
Configuration AppSettings, SettingsStore config.json with a schema version; atomic writes (temp file + move), values clamped on load, a corrupt file is backed up as config.json.bak-<time>, 1.x font settings are migrated.

HashTool.App

  • Composition — AppHost builds a Microsoft.Extensions.DependencyInjection container (services and view models are singletons). Program.Main runs Velopack hooks first, then --smoke-test, single-instance forwarding and Avalonia.
  • Views and view models — compiled bindings everywhere; App.axaml maps each view model to its view. FileListViewModelBase holds what Generate and Verify share: importing (background enumeration, batches of 1000), filtering, running a BatchProcessor with UI updates pumped every 100 ms, and the summary dialog. TextHashViewModel (Hash Text) hashes text in memory with every algorithm, shortly after each change.
  • Localization — LocalizationService reads the satellite resources, detects the system language, sets the culture (including DefaultThreadCurrentCulture, so async work keeps it) and right-to-left flow. Views bind Localization[Key]; view models swap their LocalizationProxy when the language changes, which refreshes every binding. Status texts are stored as enums and translated by converters, so they follow language changes.
  • Services — dialogs, file pickers, clipboard and launcher behind interfaces (UiServices.cs); SettingsService debounces saves; ThemeService/ThemePalettes swap brush resources; FontService picks per-script fonts; UpdateService wraps Velopack (GitHub source, stable channel).
  • Infrastructure — logging to daily files and an in-memory sink for the Developer console (Logging/), crash reports, AppPaths (HASHTOOL_DATA_DIR override), command-line parsing, single instance (named mutex/lock file plus a per-user named pipe), Windows shell integration under HKCU\Software\Classes, on-demand elevation, and the headless smoke test.

HashTool.Cli

hashtool hash | verify | check | algorithms, built on Core; hash - reads standard input. Exit codes follow sha256sum: 0 success, 1 failed or mismatched file, 2 usage error or unreadable checksum file. Published per platform as a single NativeAOT executable.

Tests

  • HashTool.Core.Tests — known-answer vectors for every algorithm, engine, parser/writer, enumerator, batch processor, settings store. CI requires at least 80% line coverage of Core.
  • HashTool.Cli.Tests — commands, output formats and exit codes.
  • HashTool.App.Tests — Avalonia headless: every page in several languages, a create-and-verify flow, translation integrity (keys, placeholders, Languages.json ↔ resx ↔ project, satellite assemblies, unused keys), language detection, and accessibility (AccessibilityTests: a real, translated automation name for every control, headings, Tab inside file rows, focus when buttons swap, WCAG contrast of every theme palette; see ACCESSIBILITY.md).
  • tests/Compat/LegacyClient — not in the solution: the release workflow uses it to update a real 1.1.3 install with its own Velopack 0.0.1298 library and updater (see RELEASING.md).

SonarCloud analyses every pull request and main from the SonarCloud workflow: the C# during a real build, with coverage from the tests above and from the smoke test (dotnet-coverage), plus the scripts and workflows. Its quality gate ("Sonar way") applies to new code; bench/ is analysed as test code and eng/ is left out of coverage.

Adding a hash algorithm

In maintenance mode an algorithm is added only on real demand (CONTRIBUTING.md, "Hash algorithms"). What it touches:

  • HashType: append only, never rename. Settings store the name ("SHA256"), an unknown name resets config.json (so would a downgrade after a new algorithm was chosen), and the name is what the UI, the CLI and -a show.
  • HashAlgorithms: GuessPriority (every algorithm must be listed), Aliases, SizeInBytes, FileExtension, BsdTag, IsInsecure.
  • HashFunction.Create: the implementation. HashEngine creates every requested function before reading, so one that can fail on some platforms (the SHA-3 of .NET on macOS and Windows 10) breaks unrelated rows: use a managed implementation.
  • ChecksumFileNames: extensions and well-known file names (B2SUMS…). The Windows context menu uses the same list, and build/macos/Info.plist must match it (PackagingTests).
  • Digests of the same length become guesses (64 hex digits: SHA-256, BLAKE3…): Verify hashes every candidate in one read, except when the Default algorithm of the page has that length.
  • Tests: KnownAnswerTests (published vectors), EdgeCaseTests and CliTests (both assert that sha3 is unknown today), HashMatcherTests; docs: README, USAGE, hashtool hash --help.

Benchmarks

dotnet run -c Release --project bench/HashTool.Benchmarks -- --filter '*'

LargeFileBenchmarks compares the engine with SHA256.HashData(FileStream); SmallFilesBenchmarks compares sequential hashing with BatchProcessor. On an i7-14700KF with a warm cache: SHA-256 of 256 MiB 129 ms vs 221 ms, BLAKE3 57 ms, XXH3 36 ms, CRC32 34 ms; 2,000 × 16 KiB files 26 ms in parallel vs 89 ms sequentially.