docs: present Java algorithms reliability showcase (#69)

docs: present algorithms reliability showcase

Author: krotname

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,6 +1,6 @@
 ---
 name: Feature request
-about: New kata, test strategy, or repository quality improvement
+about: New reference implementation, test strategy, or repository quality improvement
 title: "[feat] "
 labels: ["enhancement"]
 assignees: ["krotname"]

.github/workflows/no-releases.yml

@@ -19,6 +19,6 @@ jobs:
     steps:
       - name: Explain release policy
         run: |
-          echo "::error title=No releases::CodewarsKataJava is a kata practice repository and does not publish GitHub releases or release tags. Use the regular CI workflow for validation."
+          echo "::error title=No releases::JavaAlgorithmsShowcase publishes reference implementations without GitHub releases or release tags. Use the regular CI workflow for validation."
           echo "This workflow exists only to make accidental release or release-tag events visible."
           exit 1

.sonarcloud.properties

@@ -1,3 +1,3 @@
 # SonarQube Cloud automatic analysis ignores sonar-project.properties.
-# These kata/algorithm files intentionally repeat contest-style I/O and setup patterns.
+# These source-derived algorithm files intentionally repeat contest-style I/O and setup patterns.
 sonar.cpd.exclusions=src/main/java/algorithms/sprint1/SleightOfHand.java,src/main/java/algorithms/sprint8/PackedPrefix.java,src/main/java/algorithms/sprint2/Deque.java,src/main/java/algorithms/sprint6/DorogayaSet.java,src/main/java/algorithms/sprint8/Crib.java,src/main/java/algorithms/sprint6/WaterWorld.java,src/main/java/algorithms/sprint2/Calculator.java,src/main/java/algorithms/sprint7/EqualSums.java,src/main/java/algorithms/sprint1/Distances.java,src/main/java/algorithms/sprint7/LevenshteinDistance.java,src/main/java/algorithms/sprint5/PyramidSort.java,src/main/java/algorithms/sprint4/FindSystem.java,src/main/java/algorithms/sprint3/FastSort.java

ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 ## Repository model
 
-- `src/main/java` contains production kata implementations grouped by family (`kyu3`, `kyu4`, `kyu5`, `kyu6`, `kyu7`, `leetcode`, `interview`, `coderun`, `other`, `transactions`).
+- `src/main/java` contains reference implementations grouped by engineering concern (`algorithms`, `transactions`, `common`) and by retained source provenance (`kyu3`, `kyu4`, `kyu5`, `kyu6`, `kyu7`, `leetcode`, `interview`, `coderun`, `other`).
 - `src/test/java` mirrors the same package layout.
 - `src/test/java/quality` contains suite-level entry points for local and CI review:
   - `SmokeSuite` – fast baseline visibility of all unit tests.
@@ -14,7 +14,7 @@
 ## Design principles used in this repo
 
 - Deterministic API behavior where possible.
-- No mutable side effects in pure kata methods.
+- No mutable side effects in pure algorithm methods.
 - Input validation and boundary handling through explicit conditions.
 - Shared conventions and reviewability:
   - test classes are colocated with implementation packages;
@@ -29,7 +29,7 @@
 - **Security**: CodeQL workflow and Security policy in the repo root.
 - **Intentional static-analysis exceptions:** `config/checkstyle/suppressions.xml`
   documents generated smoke wrappers, while `config/spotbugs-exclude.xml` keeps
-  Codewars-compatible public API names documented instead of hiding them in code.
+  source-compatible public API names documented instead of hiding them in code.
 
 ## Future quality directions
 

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## Unreleased
 
-- Corrected boundary, overflow, validation, determinism and complexity defects across kata utilities.
+- Corrected boundary, overflow, validation, determinism and complexity defects across algorithm utilities.
 - Hardened transaction validation and made returned status collections immutable.
 - Replaced unbounded iteration in encryption and range-counting helpers with logarithmic algorithms.
 - Made the generated smoke harness fail when every executable API path fails.
@@ -14,7 +14,7 @@
 ## 1.1 - public quality hardening (2026-06-09)
 
 - Added CI, static analysis, and dependency management updates for repository quality.
-- Standardized test strategy and introduced a shared smoke harness for kata classes.
+- Standardized test strategy and introduced a shared smoke harness for reference implementations.
 - Added dedicated integration tests for the transactions validation flow.
 - Expanded README with bilingual project guidance.
 - Added community/maintenance docs (`CONTRIBUTING`, `SECURITY`, `CODE_OF_CONDUCT`).
@@ -27,5 +27,5 @@
 - Added repository-level line-ending normalization with `.gitattributes`.
 - Expanded the meaningful test baseline to 455 tests across unit/smoke, integration and property categories.
 - Set enforced JaCoCo coverage gates to 70% line, branch and instruction coverage.
-- Reduced SpotBugs debt to zero reported findings with explicit compatibility exclusions for Codewars API names.
+- Reduced SpotBugs debt to zero reported findings with explicit exclusions for source-compatible API names.
 - Reduced PMD debt to zero reported findings by removing unused code/imports and simplifying safe expressions.

CONTRIBUTING.md

@@ -41,4 +41,4 @@ Thank you for interest in this repository.
 - `mvn -B verify` runs the full quality stack: tests, coverage, checkstyle, PMD and SpotBugs.
 - CI enforces reproducible builds on Java 17 and 21.
 - Prefer explicit comments for non-obvious logic in complex methods.
-- If you touch static API in a kata class, keep test names meaningful and deterministic.
+- If you touch a source-compatible static API, keep test names meaningful and deterministic.

README.en.md

@@ -1,83 +1,71 @@
-# Codewars Solutions
+# Java Algorithms & Reliability Showcase
 
-[Russian](README.md)
+[Русская версия](README.md)
 
+Curated Java reference implementations for deterministic algorithms and stateful validation. The project demonstrates API design, edge-case handling, property-based testing, static analysis, and reproducible CI.
 
-This repository is a portfolio-grade Java kata workspace focused on deterministic algorithms, reproducible tests, visible quality workflows, readable production code, and bilingual project documentation.
+[![CI](https://github.com/krotname/JavaAlgorithmsShowcase/actions/workflows/maven.yml/badge.svg)](https://github.com/krotname/JavaAlgorithmsShowcase/actions/workflows/maven.yml)
+[![Quality Gates](https://github.com/krotname/JavaAlgorithmsShowcase/actions/workflows/quality.yml/badge.svg)](https://github.com/krotname/JavaAlgorithmsShowcase/actions/workflows/quality.yml)
+[![CodeQL](https://github.com/krotname/JavaAlgorithmsShowcase/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/krotname/JavaAlgorithmsShowcase/actions/workflows/codeql-analysis.yml)
+[![Coverage](https://codecov.io/gh/krotname/JavaAlgorithmsShowcase/branch/main/graph/badge.svg)](https://app.codecov.io/gh/krotname/JavaAlgorithmsShowcase)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/krotname/JavaAlgorithmsShowcase/badge)](https://securityscorecards.dev/viewer/?uri=github.com/krotname/JavaAlgorithmsShowcase)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13151/badge)](https://www.bestpractices.dev/projects/13151)
+[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-0f8a16)](LICENSE)
+[![Java](https://img.shields.io/badge/Java-17%2B-007396.svg)](https://adoptium.net/)
+[![JUnit](https://img.shields.io/badge/JUnit-6-25A162.svg)](https://junit.org/)
+[![Maven](https://img.shields.io/badge/Maven-3.9%2B-C71A36.svg)](https://maven.apache.org/)
 
-## Why This Repository Exists
+![Java Algorithms & Reliability Showcase](docs/assets/project-icon.svg)
 
-- It demonstrates practical coding and test engineering from problem solving to delivery quality.
-- Solutions are organized by difficulty/source: kyu, LeetCode, interview, transactions, and other groups.
-- Static checks and tests are visible and runnable in one place.
+## Selected engineering components
 
-## Repository Map
+| Component | Engineering problem | What it demonstrates |
+| --- | --- | --- |
+| [Transaction validation](src/main/java/transactions) | Ordered, stateful operations; cascading invalidation; balance and overflow boundaries | Deterministic state transitions, immutable results, integration scenarios |
+| [Algorithm utilities](src/main/java/algorithms) | Boundary conditions, complexity, stream and file I/O | Deterministic APIs, explicit complexity tradeoffs, edge cases, and property-based invariants |
+| [Parsing / validation](src/main/java/common/SafeParse.java) | Malformed numeric and text input | Explicit contracts, preserved exception causality, unit tests, and static analysis |
 
-- `src/main/java` - production solutions and domain classes.
-- `src/test/java` - tests and quality suites:
-  - `quality.SmokeSuite` for unit/smoke tests.
-  - `quality.IntegrationSuite` for transaction scenario tests.
-  - `quality.PropertySuite` for curated property-based tests.
-- `.github` - CI workflows, Dependabot, and repository templates.
-- `ARCHITECTURE.md` - architectural and reviewability notes.
-- `CHANGELOG.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `TESTING.md` - project governance.
+This is an engineering demonstration repository, not a commercial product. Implementations are selected to make code quality, test strategy, and the development process directly reviewable.
 
-## Testing Strategy
+## Verification strategy
 
-- Smoke/unit tests cover each kata directly and are grouped by `quality.SmokeSuite`.
-- Integration tests cover transaction validation state and ordering through `quality.IntegrationSuite`.
-- Property-based tests are grouped in `quality.PropertySuite`.
-- UI tests are not applicable because this repository has no UI layer.
-- Static quality gates include Checkstyle, PMD, and SpotBugs in Maven verify.
-- JaCoCo fails `mvn verify` below 70% line, branch, or instruction coverage.
+- **Smoke / unit:** baseline contracts for public APIs.
+- **Integration:** transaction state and ordering, plus algorithm CLI contracts.
+- **Property-based (jqwik):** invariants over broad generated input sets.
+- **Static analysis:** Checkstyle, PMD, and SpotBugs with a zero-new-violation baseline.
+- **Coverage:** JaCoCo fails `mvn verify` below 70% line, branch, or instruction coverage.
+- **Security:** CodeQL, dependency review, and OpenSSF Scorecard.
+- **Reproducibility:** Java 17/21 CI and a strict offline Windows gate after Maven cache priming.
 
-## CI and Quality Signals
-
-- `.github/workflows/maven.yml` runs category jobs on JDK 21 and full `mvn verify` on JDK 17 and 21.
-- The same workflow validates the strict offline PowerShell gate on Windows after an explicit dependency-prime step.
-- `.github/workflows/quality.yml` runs Checkstyle, PMD, and SpotBugs without executing tests.
-- `.github/workflows/codeql-analysis.yml` runs security analysis.
-- `.github/dependabot.yml` keeps dependency automation visible.
-
-## Default Branch Governance
-
-`main` intentionally uses lightweight branch governance. This is a personal educational kata journal where small solution, test, and explanation updates are often pushed directly to keep a fast practice loop. Public quality assurance comes from CI, CodeQL, quality gates, Dependabot, the Security Policy, and reproducible local commands. Substantive changes that affect kata behavior or quality policy still use the normal PR/review workflow.
-
-The absence of branch protection on `main` is an intentional project-specific exception and should not be treated as a hardening defect.
-
-## Local Run
+## Local verification
 
 ```bash
 mvn -B verify
-mvn -B test
 mvn -B test -Dgroups='smoke'
 mvn -B test -Dgroups='integration'
 mvn -B test -Dgroups='property'
 mvn -B -DskipTests checkstyle:check pmd:check spotbugs:check
-mvn -B test -Dtest='quality.SmokeSuite'
-mvn -B test -Dtest='quality.IntegrationSuite'
-mvn -B test -Dtest='quality.PropertySuite'
 ```
 
-Run the complete PowerShell gate without network access:
+Run the complete offline gate in PowerShell:
 
 ```powershell
 .\scripts\run-offline-gate.ps1
 ```
 
-See [`TESTING.md`](TESTING.md) for strict dependency-cache mode and the documented
-cached-JUnit fallback.
+See [TESTING.md](TESTING.md) for the complete test matrix and dependency-cache rules.
+
+## Repository map
 
-## Reviewer Checklist
+- `src/main/java/transactions` — stateful validation and its transaction domain model.
+- `src/main/java/algorithms` — sorting, graphs, dynamic programming, data structures, and CLI algorithms.
+- `src/main/java/common`, `interview`, `leetcode`, `coderun`, `other`, `kyu*` — utilities and implementations with provenance-preserving layout.
+- `src/test/java/quality` — entry points for smoke, integration, and property suites.
+- `.github/workflows` — CI, quality gates, CodeQL, dependency review, and supply-chain checks.
+- [ARCHITECTURE.md](ARCHITECTURE.md), [TESTING.md](TESTING.md), and [SECURITY.md](SECURITY.md) — architecture, test strategy, and security policy.
 
-- No hidden mutation of test inputs inside algorithmic methods.
-- Meaningful method-level comments in non-obvious logic.
-- Deterministic edge-case handling in boundary tests.
-- Governance artifacts for maintainability and process.
+## Sources & provenance
 
-## Local Quality Policy
+Problems and APIs come from several sources: Codewars, LeetCode, Yandex algorithm tracks, CodeRun, interview tasks, and standalone exercises. Links to original statements and compatible signatures remain in the code where they help verification.
 
-- Use ASCII-only patch style unless a file already contains another script.
-- Keep public method behavior deterministic.
-- Add or adjust tests for changed branch behavior.
-- Keep comments close to complex algorithmic logic.
+The `kyu*` packages are retained as internal provenance and compatibility structure. They are not the project's primary taxonomy; the showcase is organized around engineering problems, contracts, and test strategy.