feat/quality gate language policy and 3484

.editorconfig

@@ -11,5 +11,5 @@ indent_size = 2
 [*.md]
 trim_trailing_whitespace = false
 
-[*.{cpp,c,h,hpp,py,js}]
+[*.{cpp,c,h,hpp,py,js,rs}]
 indent_size = 4

.github/README-maintenance.md

@@ -90,10 +90,15 @@ Each problem should follow the established repository conventions:
 
 - physical organization by ID range 
 - one main documentation file per problem 
-- multiple implementations under `solutions/`
+- one primary language per problem; extra implementations only with a stated reason
+- test cases under `tests/`, shared by all implementations
 - optional `notes.md`
 - optional `deep-dive.md`
 
+## Verification Before Any Git Update
+
+Run `python scripts/check_all.py` (see `docs/testing.md`). Enable the Git hooks once per clone with `git config core.hooksPath scripts/hooks`. CI repeats the full gate on every push and pull request.
+
 ## Index and Tracker Maintenance
 
 Whenever relevant, update:

.github/dependabot.yml

@@ -0,0 +1,9 @@
+# Keeps the GitHub Actions used by CI up to date (supply-chain hygiene).
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore(ci)"

.github/pull_request_template.md

@@ -38,6 +38,8 @@ Explain why this change improves the repository.
 - [ ] Public-facing content is written in English
 - [ ] Naming follows the established conventions
 - [ ] Documentation is aligned with the correct level (L1, L2, or L3)
+- [ ] `python scripts/check_all.py` passes (structure, lint, and test cases)
+- [ ] `Status: Solved` is used only for submissions accepted by the judge
 - [ ] Links and paths were checked
 - [ ] Trackers/indexes were updated when necessary
 

.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Least privilege: the checks only need to read the repository.
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: Validate, lint and test
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Toolchain versions
+        run: |
+          g++ --version | head -n 1
+          gcc --version | head -n 1
+          rustc --version
+          node --version
+          python --version
+
+      - name: Run every check
+        run: python scripts/check_all.py --all --sanitize --werror --require-toolchains --github

.gitignore

@@ -14,6 +14,7 @@ venv/
 
 # C / C++
 *.out
+!problems/**/tests/*.out
 *.exe
 *.o
 *.obj
@@ -22,6 +23,9 @@ venv/
 *.dll
 build/
 
+# Rust
+target/
+
 # JavaScript
 node_modules/
 dist/

CONTRIBUTING.md

@@ -24,6 +24,8 @@ Please read:
 - `docs/repository-conventions.md`
 - `docs/git-workflow.md`
 - `docs/documentation-standard.md`
+- `docs/coding-standards.md`
+- `docs/testing.md`
 
 ## Main principle
 

README.md

@@ -14,26 +14,30 @@ This repository is part of my long-term technical growth and public portfolio. I
 
 ## Main Languages
 
-- C++17 / C++20 as the primary problem-solving language
-- Python as a secondary language for clarity and speed 
-- JavaScript as a complementary language aligned with my professional stack 
-- C for fundamentals and low-level reasoning
+Each problem has **one primary language**, chosen for what the problem trains (see `docs/language-policy.md`):
+
+- C++17 / C++20 as the default problem-solving language
+- C for memory, bits, and low-level reasoning
+- Rust for ownership and memory safety, as the counterpart of C
+- Python for clarity, strings, and quick prototypes
+- JavaScript for parsing and text processing, aligned with my professional stack
+- SQL for the SQL category
 
 ## Repository Structure
 
 - `problems/` → problem-based documentation model;
 - `docs/` → philosophy, workflow, standards, references, and language guides
 - `trackers/` → progress tracking and reviews
 - `templates/` → reusable documentation templates
-- `scripts/` → automation helpers for repository maintenance
+- `scripts/` → automation helpers: validation, linting, test runner, Git hooks
 
 ## Documentation Levels
 
 This repository uses a layered documentation model:
 
 - **L1 — Quick Log**: short documentation for straightforward problems
 - **L2 — Standard**: structured explanation for relevant problems
-- **L2 — Deep Dive**: deeper analysis for hard, elegant, or high-value problems
+- **L3 — Deep Dive**: deeper analysis for hard, elegant, or high-value problems
 
 Not every problem needs the same depth. The goal is not bureaucratic documentation – the goal is sustainable excellence.
 
@@ -55,6 +59,16 @@ The absence of a license file is intentional. Public visibility does not mean th
 
 Problem statements, titles, and platform references belong to their respective owners. This repository contains my own implementations, notes, and interpretations for educational and portfolio purposes.
 
+## Quality Gate
+
+Every change is verified before it reaches Git, locally and in CI:
+
+```bash
+python scripts/check_all.py
+```
+
+See `docs/testing.md` for what it checks and how to enable the Git hooks.
+
 # Status
 
 This repository is being built incrementally, with careful structure, documentation, and selective migration from older problem-solving repositories.

docs/coding-standards.md

@@ -0,0 +1,87 @@
+# Coding Standards
+
+These rules apply to **every language** in this repository. Each language adds its own details in `docs/style-guides/`:
+
+[C++](style-guides/cpp.md) · [C](style-guides/c.md) · [Python](style-guides/python.md) · [JavaScript](style-guides/javascript.md) · [Rust](style-guides/rust.md) · [SQL](style-guides/sql.md)
+
+The rules that a program can decide are checked automatically by `scripts/lint_solutions.py`. The rest is checked by review, using the checklist at the end of this page.
+
+## 1. Think before typing
+
+1. **Estimate complexity from the constraints before coding.** Choosing the right algorithm is the largest optimization there is. `N <= 250` allows `O(N^2)` or even `O(N^3)`; `N = 10^5` calls for `O(N log N)`.
+2. **Correct first, fast second.** Optimize only after the samples pass and a measurement or a complexity estimate says it is necessary.
+3. **Pick the data structure for the operations you need**, not for habit: lookups, ordered traversal, a queue, a priority queue.
+4. **Prefer the simplest correct approach.** Clever code is a liability; clear code is an asset.
+
+## 2. Input and output contract
+
+1. Read **exactly** what the statement describes. Handle end-of-file when the statement says the input ends that way.
+2. Never assume a particular whitespace layout; read tokens, not lines, unless lines matter.
+3. Match the output format **character for character**: separators, decimals, trailing spaces, and the final newline. Judges report formatting differences as errors.
+4. Read the whole input efficiently when it is large, and write the output in as few calls as practical.
+
+## 3. Safety is the default
+
+These rules are cheap in a puzzle and essential in real code, which is why they are practiced here.
+
+1. **Every index needs an argument.** Either a bounds check, or a short comment that explains why it cannot go out of range.
+2. **Know the largest value before choosing a numeric type.** Compute the worst case. Signed overflow is undefined behavior in C and C++, wraps silently in release Rust, and loses precision in JavaScript numbers above 2^53.
+3. **Never trust sizes or counts from input** when allocating or indexing. Validate them against the statement's limits.
+4. **Initialize everything.** No variable is read before it has a value.
+5. **Ownership is explicit.** Prefer containers and smart pointers (or Rust's ownership) to manual memory management. A non-owning cursor is fine; a second owner is a bug.
+6. **No dynamic code execution** (`eval`, `exec`, `new Function`) and no building queries by string concatenation.
+7. **Treat compiler and linter warnings as defects.** Fix them or justify them.
+
+## 4. Performance rules
+
+1. Measure or estimate; do not guess.
+2. Avoid work in the inner loop that can be done once outside it.
+3. Prefer the standard library: it is tested, documented, and fast.
+4. Fast input/output matters only when the input is large. Add it deliberately and say why in a comment.
+5. Know the cost of the operations you call (`list.pop(0)`, `Array.shift()`, string concatenation in a loop, copying large values).
+6. Beware of adversarial inputs for hash tables when the input is not trusted.
+
+## 5. Structure, naming, and comments
+
+1. One file per implementation: `solutions/<language>/main.<ext>`. Standard library only, no external dependencies.
+2. Small functions with one clear purpose; `main` reads, calls, and prints.
+3. Meaningful names. One-letter names only in very local scopes (`i`, `j`, `n`).
+4. Comments explain **why**, never what. A good comment records a non-obvious reason: a bound, a trick, an invariant.
+5. Follow the naming rules of each language (see the style guides) and `.editorconfig` (UTF-8, LF, spaces, 4-space indent for code).
+6. English only for code, comments, and documentation.
+7. No leftover `TODO`, debugging output, or commented-out code.
+
+## 6. Testing expectations
+
+Every solved problem has test cases in `tests/` (see [Testing](testing.md)): the public samples, the edge cases, and, when a faster solution replaced a simpler one, cases cross-checked against a brute-force oracle.
+
+## 7. What is checked automatically
+
+`scripts/lint_solutions.py` reports findings with a stable rule id. Errors block a commit; warnings are advice. The full list per language is in the style guides.
+
+| Area | Examples of what it catches |
+|------|-----------------------------|
+| Portability | `<bits/stdc++.h>`, std symbols used without their `#include` |
+| Memory safety | raw `new`/`delete`, `gets`, unbounded `%s`, `strcpy`, `unsafe` without a `SAFETY` note |
+| Correctness traps | `var` and `==` in JavaScript, default `Array.sort()`, mutable default arguments |
+| Security | `eval`/`exec`, wildcard imports, `SELECT *` and comma joins in SQL |
+| Hygiene | leftover `TODO`/`FIXME` (`GEN001`), lines over 120 characters (`GEN002`) |
+
+### Deliberate exceptions
+
+A rule can be waived on purpose with a comment on the same line or the line above, naming the rule and giving the reason:
+
+```cpp
+int* raw = new int[3];  // lint:allow CPP004 deliberate raw-pointer exercise
+```
+
+An exception without a reason does not pass review.
+
+## 8. Review checklist before submitting
+
+- [ ] I can explain the algorithm and its complexity in my own words.
+- [ ] Every index and every numeric range has an argument.
+- [ ] The samples pass, plus edge cases (smallest and largest input, sorted, reversed, duplicates when allowed).
+- [ ] The output format matches the statement exactly.
+- [ ] No warnings, no leftover markers, no unused code.
+- [ ] `python scripts/check_all.py` passes.

docs/indexes/by-language.md

@@ -16,4 +16,12 @@ _No entries yet._
 
 ## C
 
+_No entries yet._
+
+## Rust
+
+_No entries yet._
+
+## SQL
+
 _No entries yet._

docs/language-policy.md

@@ -0,0 +1,58 @@
+# Language Policy
+
+This repository supports six languages: **C++, C, Python, JavaScript, Rust, and SQL**.
+
+Supporting many languages does not mean solving every problem in all of them. Rewriting the same solution five times adds repetition, not evidence of reasoning. The rule is simple:
+
+> **Each problem has one primary language, chosen for what the problem trains.**
+
+## Choosing the primary language
+
+| Language | Choose it when the problem is mostly about... |
+|----------|-----------------------------------------------|
+| **C++** (default) | data structures, graphs, paradigms, mathematics, anything that benefits from the standard library and predictable performance |
+| **C** | bit manipulation, memory layout, manual buffers, C-style strings and input parsing |
+| **Rust** | ownership, lifetimes, and memory safety as the point of the exercise; the natural counterpart to C |
+| **Python** | strings, ad-hoc simulation, big integers, quick prototypes |
+| **JavaScript** | parsing and text processing close to my professional stack |
+| **SQL** | the SQL category, and only the SQL category |
+
+```mermaid
+flowchart TD
+    A[New problem] --> B{SQL category?}
+    B -- yes --> S[SQL]
+    B -- no --> C{Trains memory layout, bits or manual buffers?}
+    C -- yes --> D[C - add Rust only to contrast ownership]
+    C -- no --> E{Mostly parsing, strings or a quick prototype?}
+    E -- yes --> F[Python or JavaScript]
+    E -- no --> G[C++ - the default]
+```
+
+Any problem that does not use C++ states the reason in one line of its `README.md`, so the variety is visibly intentional.
+
+## Additional implementations
+
+`Other Implementations` stays empty by default. A second implementation is added only when it teaches something specific:
+
+- a **C versus Rust** comparison of manual memory management and ownership;
+- a short **Python oracle** (brute force) used to cross-check a faster solution;
+- a deliberate exercise in the idioms of another language.
+
+The reason is written in the problem `README.md`. Documentation stays centralized: one explanation file per problem.
+
+## Status integrity
+
+`Status: Solved` is only valid for code that was **submitted to the judge and accepted**.
+
+- When migrating a legacy solution, keep the language in which it was accepted.
+- Rewriting a solution in another language is a new submission and has its own status.
+- Use `In Progress`, `Improving`, or `To Review` until the judge confirms the result.
+
+## Open points
+
+- Judge support for **Rust** is not confirmed. Until it is, Rust solutions are local study material and are never marked `Solved`.
+- The **SQL** engine used by the judge, and a local SQL test runner, are still to be defined.
+
+## How the policy is enforced
+
+`scripts/validate_structure.py` rejects unsupported language folders, empty solution files, a primary language without code, SQL outside the SQL category, and a `Solved` status without test cases. See [Testing](testing.md).

docs/references.md

@@ -18,6 +18,20 @@ This repository is influenced by principles commonly associated with the followi
 - The Algorithm Design Manual
 - Programming Pearls
 
+## Language and safe-coding references
+
+- Competitive Programmer's Handbook (Antti Laaksonen)
+- CP-Algorithms (online)
+- C++ Core Guidelines (Bjarne Stroustrup and Herb Sutter)
+- Effective Modern C++ (Scott Meyers)
+- SEI CERT C Coding Standard
+- Secure Coding in C and C++ (Robert C. Seacord)
+- The Rust Programming Language ("the book") and The Rustonomicon
+- PEP 8 and PEP 20 (Python)
+- MDN Web Docs (JavaScript)
+- SQL Antipatterns (Bill Karwin)
+- OWASP Cheat Sheet Series
+
 ## Practical interpretation for this repository
 
 These references inspire the following standards:

docs/repository-conventions.md

@@ -50,7 +50,24 @@ This keeps the filesystem stable and scalable.
 
 A problem has one main conceptual documentation file.
 
-Multiple implementations may exist inside `solutions/`, but the explanation should remain centralized.
+A problem has one primary language. Extra implementations may exist inside `solutions/` when there is a stated reason (see `language-policy.md`), but the explanation remains centralized.
+
+## Problem folder layout
+
+```text
+<problem-id>-<slug>/
+├── README.md              one explanation, with the metadata block
+├── notes.md               optional
+├── deep-dive.md           optional, for L3
+├── solutions/<language>/main.<ext>
+└── tests/<name>.in, <name>.out
+```
+
+Supported language folders: `cpp`, `c`, `python`, `javascript`, `rust`, `sql`. Test cases are shared by every implementation (see `testing.md`).
+
+## Code standards
+
+All code follows `coding-standards.md` and the style guide of its language. The rules are checked by `scripts/lint_solutions.py`.
 
 ## Statements