WUT_Computer_Science/CLAUDE.md

WUT_Computer_Science

Archive of university coursework from Warsaw University of Technology. 44 course directories, 12 languages, ~28k lines of authored code plus the submitted reports, figures and datasets. It is an archive: the code is finished, and the value is that it still builds, runs and is readable.

Repository Layout

Path	What it is
Programming/	25 course dirs with real code (Python, C/C++, Java, TS/Angular, C#, Unity, MATLAB-adjacent).
NotProgramming/	19 course dirs that are mostly LaTeX reports, PDFs and EDA schematics. Exceptions: ENUME (MATLAB), STUP/makieta (Angular), EDABA-LAB (SQL).
gates/	Machine-readable gate inputs. vendored.txt is the source of truth for "not my code".
scripts/	Repo-local gates. Shims that exec into ~/utils live here too.

Two structural facts that surprise people:

• Programming/PSD/zin3/third/ and Programming/psd_project/ are the same services under different names, and WDWR/project/ vs WDWR/projekt/, SDM vs SDM2, and EMISY/componentSchematic/ vs EMISY/schematic/ are likewise near-duplicates. They are not de-duplicated: each is a separate submitted deliverable, and merging them would rewrite the academic record.
• Programming/EOPSY/lab{3,4}/task*/work/ is not student code. It is the extraction target of make setup from the tarballs in the sibling ftp/. Verified byte-identical, 14/14 files. Do not edit or split it.

Git Workflow

Work directly on main; commit and push straight there.

./install.sh          # deps + pre-commit hooks, then verifies and fails loudly
./run.sh check        # the full local gate
./run.sh status       # probe every course dir, regenerate DOCS-runnability.md
./run.sh run <dir>    # build/run one course, capped at 2G RAM and 2 cores

run executes inside a transient systemd scope (MemoryMax=2G, MemorySwapMax=0, CPUQuota=200%, nice -n 19, ionice -c 3), so a course build cannot make an interactive machine stutter. This is not caution, it is a kernel-enforced ceiling -- PORR's suite solves 10000x10000 systems and will take every core it is given. Raise it deliberately for a single run with RUN_MEMORY_MAX=8G RUN_CPU_QUOTA=800% ./run.sh run <dir>.

Never --no-verify. If a gate fails, fix the cause.

Development Workflow

• Confirm a change works by running the thing and reading its output, not by running tests. Tests come after.
• git rm --cached, never bare git rm, when removing build output — it must stay on disk so a mis-classification is recoverable.
• After touching .gitignore or .binary-allowlist, re-run:

  git ls-files | git check-ignore --stdin --no-index
  

  It must print nothing. A file that is both tracked and ignored fails silently on git add: not an error, the edit just never lands. This repo had 130 such files.

Code Conventions

Anything a hook already enforces is omitted here — read .pre-commit-config.yaml for that list. What follows is what a linter cannot check.

Everything

• Every file is at most 250 lines, source and prose alike, enforced by the shared gate in ~/utils. There is deliberately no baseline and no allowlist: split the file. For a LaTeX report that means \input{} per section; for a markdown report, sibling DOCS-*.md files behind an index.
• Do not "fix" coursework to be better than it was submitted. Correct what is broken, keep what is merely old-fashioned. The archive should still show what was actually handed in.

Vendored content

gates/vendored.txt is the only place a path becomes exempt from lint, coverage and the cap. Every entry carries a reason and how it was verified — an unverified entry is a suppression wearing a costume. The list is mirrored into ~/utils/file_length/_tables.py, [tool.ruff] exclude and [tool.coverage.run] omit; edit the manifest, never a mirror.

Python

• ruff runs with select = ["ALL"] and mypy with strict = true.
• No # noqa, no # type: ignore. A pre-commit hook rejects both outright.
• Notebooks: outputs are stripped on commit, lint via nbqa. Real logic belongs in a sibling importable module — a notebook cannot be covered.

LaTeX

Build output is ignored, not committed: .aux, .fls, .fdb_latexmk, .xdv, -eps-converted-to.pdf and friends. The submitted .pdf is committed, because it is the deliverable.

Shell

set -euo pipefail, quoted expansions, main "$@" last. Never embed another language's logic inline — put it in its own file so that language's tooling applies.

Key Files

Path	Why it matters
gates/vendored.txt	What is not my code, and how each entry was verified.
gates/coverage.tsv	Per-directory coverage floors. Floors may only rise.
.binary-allowlist	Path-scoped: deliverables allowed under the two course trees, compiled output allowed nowhere.
DOCS-runnability.md	Per-course run status, recorded separately for local and ci.
TODO-*.md	Open decisions. Each carries the removal marker and is deleted when the work lands.