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.

```bash
./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:
  ```bash
  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. |