docs: map existing codebase
This commit is contained in:
1 parent
bdca29d3aa
commit
f2f3a805cd
7 files changed
+1012
No files matched your search
@@ -0,0 +1,121 @@
|
||||
---
|
||||
last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45
|
||||
last_mapped_at: 2026-11-12
|
||||
---
|
||||
# Coding Conventions
|
||||
|
||||
**Analysis Date:** 2026-11-12
|
||||
|
||||
## Naming Patterns
|
||||
|
||||
**Files:**
|
||||
- Use PascalCase C# filenames matching the principal type: `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`.
|
||||
- Use snake_case Python modules and `test_*.py` regressions: `tools/extractors/sound_bank.py`, `tests/test_actor_contact.py`.
|
||||
- Keep shell entry points under `scripts/`, using descriptive hyphenated names such as `scripts/test-window-transitions.sh`.
|
||||
|
||||
**Functions:**
|
||||
- Use PascalCase C# methods (`ReadVelocity`, `GenericWall`) as in `src/GamePort/Game/OriginalNormalContacts.cs`.
|
||||
- Use snake_case Python functions (`export_sound_bank`, `validate_output`) as in `tools/extractors/sound_bank.py` and `tools/extractors/omt.py`.
|
||||
- Name Python test methods `test_<behavior>`; `tests/test_extractors.py` names invalid-input cases explicitly.
|
||||
|
||||
**Variables:**
|
||||
- Use camelCase C# parameters and locals, with explicit role names such as `headingUnits`, `oldHeading`, `carriedPlayer` in `src/GamePort/Game/OriginalNormalContacts.cs` and `src/GamePort/Program.cs`.
|
||||
- Private C# fields do not uniformly use underscore prefixes; match the surrounding module (`src/GamePort/Assets/GamLevel.cs`).
|
||||
- Python locals use snake_case; module constants use uppercase (`ROOT`, `ORIGINAL`, `CALLBACK_OPERANDS` in `tests/test_actor_contact.py`).
|
||||
|
||||
**Types:**
|
||||
- Use PascalCase C# classes/records and `I`-prefixed interfaces, exemplified by `OriginalNormalContacts` and `IOriginalNormalBody` in `src/GamePort/Game/OriginalNormalContacts.cs`.
|
||||
- Python uses PascalCase classes and frozen dataclasses for resource identity (`Reader`, `Entry`, `FormatError` in `tools/extractors/omt.py`).
|
||||
|
||||
## Code Style
|
||||
|
||||
**Formatting:**
|
||||
- No tracked formatter or `.editorconfig` is detected in the mapped repository. Follow each file's existing style rather than assuming an enforced formatter (`GamePort.csproj`, `src/GamePort/Assets/GamLevel.cs`).
|
||||
- C# generally uses four spaces, file-scoped namespaces and braces on separate lines; short guards and expression-bodied helpers are common. Some numerical modules and console tests use compact spacing (`src/GamePort/Game/OriginalNormalContacts.cs`, `tests/GamePort.JimmyGroundTests/Program.cs`).
|
||||
- Python uses four spaces, type annotations where useful, and compact reader helpers; quotation style varies (`tools/extractors/omt.py`, `tools/extractors/sound_bank.py`).
|
||||
|
||||
**Linting:**
|
||||
- Dedicated C#/Python lint configurations are Not detected. `GamePort.csproj` enables nullable references, implicit usings and unsafe blocks; it does not declare warnings-as-errors or a separate analyzer package.
|
||||
- Preserve explicit compile globs and shader copy rules in `GamePort.csproj`; test projects can compile production source directly, as in `tests/GamePort.ActorContactTests/GamePort.ActorContactTests.csproj`.
|
||||
|
||||
## Import Organization
|
||||
|
||||
**Order:**
|
||||
1. C# explicit `System` namespaces precede project namespaces in `src/GamePort/Program.cs` and `tests/GamePort.ActorContactTests/Program.cs`.
|
||||
2. Group runtime dependencies by namespace; implicit usings supply common base namespaces (`GamePort.csproj`).
|
||||
3. Python standard library imports precede local tool imports. Tests insert the relevant tools directory into `sys.path` (`tests/test_extractors.py`, `tests/test_actor_contact.py`).
|
||||
|
||||
**Path Aliases:**
|
||||
- No frontend-style aliases are applicable. Use `GamePort.Assets`, `GamePort.Game` and related C# namespaces; Python tool imports resolve from explicit local paths (`src/GamePort/Program.cs`, `tests/test_actor_contact.py`).
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Patterns:**
|
||||
- Fail malformed assets with contextual format exceptions, including offsets. Do not silently truncate or accept trailing bytes (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/omt.py`).
|
||||
- Reject unsupported recovered behavior explicitly with `NotSupportedException`; validate nonfinite values separately with argument exceptions (`src/GamePort/Game/OriginalNormalContacts.cs`).
|
||||
- Keep entry-point failure reporting centralized: `src/GamePort/Program.cs` catches exceptions, writes to stderr and returns status 1.
|
||||
- Resolve original asset names case-insensitively after direct lookup, reject `.`/`..`, and reject missing/ambiguous matches (`src/GamePort/Assets/AssetPath.cs`).
|
||||
- Reject extraction output overlapping originals; preserve source hashes and archive identities in generated metadata (`tools/extractors/sound_bank.py`).
|
||||
|
||||
Representative bounded C# reader from `src/GamePort/Assets/GamLevel.cs`:
|
||||
|
||||
```csharp
|
||||
public ReadOnlySpan<byte> Take(int length)
|
||||
{
|
||||
if (length < 0 || length > Remaining)
|
||||
throw new InvalidDataException($"Truncated GAM at {Offset:x}");
|
||||
var result = data.Slice(Offset, length);
|
||||
Offset += length;
|
||||
return result;
|
||||
}
|
||||
public uint U32() => BinaryPrimitives.ReadUInt32BigEndian(Take(4));
|
||||
```
|
||||
|
||||
## Logging
|
||||
|
||||
**Framework:** Console output, with explicit application diagnostics; no hosted logging service is detected (`src/GamePort/Program.cs`, `src/GamePort/Application/DebugDiagnostics.cs`).
|
||||
|
||||
**Patterns:**
|
||||
- Report fatal errors to `Console.Error`; expose inspection/smoke commands and readback paths through CLI options (`src/GamePort/Program.cs`).
|
||||
- Tests print descriptive `PASS` messages and throw on failure (`tests/GamePort.ActorContactTests/Program.cs`).
|
||||
- Persist verification scope and limitations in `docs/progress.md`, `docs/compatibility.md` and subsystem reports; console success alone does not establish whole-game equivalence.
|
||||
|
||||
## Comments
|
||||
|
||||
**When to Comment:**
|
||||
- Explain original addresses, ownership, sampled field order and excluded behavior rather than restating arithmetic (`src/GamePort/Game/OriginalNormalContacts.cs`).
|
||||
- Preserve concrete resource semantics: effect IDs are archive identities, and encoded audio preservation is separate from decoder support (`tools/extractors/sound_bank.py`).
|
||||
- Keep recovered contracts distinct from approximations and runtime admission; `AGENTS.md` and `docs/checkpoint/actor-normal-contacts.md` make these evidence boundaries explicit.
|
||||
|
||||
**XML documentation / Python docstrings:**
|
||||
- Use C# `/// <summary>` for bounded public contracts and interfaces (`src/GamePort/Game/OriginalNormalContacts.cs`).
|
||||
- Use Python module/class docstrings for recovery purpose and failure semantics (`tools/extractors/omt.py`). JSDoc/TSDoc is Not applicable.
|
||||
|
||||
## Function Design
|
||||
|
||||
**Size:**
|
||||
- Prefer focused components such as the ceiling/reflection helpers in `src/GamePort/Game/OriginalNormalContacts.cs`; no numerical line-count rule is detected. `src/GamePort/Program.cs` remains a substantial orchestration entry point.
|
||||
|
||||
**Parameters:**
|
||||
- Use explicit vectors, typed state and named flags rather than hidden scene state in recovered algorithms (`src/GamePort/Game/OriginalNormalContacts.cs`, `tests/GamePort.JimmyGroundTests/Program.cs`).
|
||||
- Inject actor-owned accessors through interfaces where read order matters; do not cache values across callbacks without evidence (`IOriginalNormalBody` in `src/GamePort/Game/OriginalNormalContacts.cs`).
|
||||
- Keep bounded readers over spans/bytes and explicitly choose endianness (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/omt.py`).
|
||||
|
||||
**Return Values:**
|
||||
- Return parsed records, typed state, or explicit metadata; throw for malformed/unsupported input (`src/GamePort/Assets/GamLevel.cs`, `tools/extractors/sound_bank.py`).
|
||||
- Preserve float-store boundaries and intentional double intermediates in recovered math. Do not simplify formulas or clamp source values without evidence (`src/GamePort/Game/OriginalNormalContacts.cs`, `docs/checkpoint/dynamic-reclip.md`).
|
||||
|
||||
## Module Design
|
||||
|
||||
**Exports:**
|
||||
- Keep asset decoding in `src/GamePort/Assets/`, recovered algorithms in `src/GamePort/Game/`, SDL interop in `src/GamePort/Platform/Sdl.cs`, and presentation in `src/GamePort/Application/`.
|
||||
- Python tools expose importable parser/export functions as well as CLI-oriented modules (`tools/extractors/omt.py`, `tools/extractors/sound_bank.py`).
|
||||
- Use `using`/disposal and explicit native ownership at runtime boundaries (`src/GamePort/Program.cs`, `src/GamePort/Rendering/Vulkan/VulkanRenderer.cs`); follow the project requirement in `AGENTS.md`.
|
||||
|
||||
**Barrel Files:**
|
||||
- Not detected / Not applicable. C# namespaces and project compile includes provide organization (`GamePort.csproj`).
|
||||
- Project-local agent skill constraints: the configured agent-skill query is empty; the applicable project constraints are in `AGENTS.md`.
|
||||
|
||||
---
|
||||
|
||||
*Convention analysis: 2026-11-12*
|
||||
Reference in new issue
Block a user