From e63462072d27d59b2ec938b385b5d960d05524c7 Mon Sep 17 00:00:00 2001 From: Philipp Wullstein-Kammler Date: Thu, 23 Jul 2026 05:24:05 +0200 Subject: [PATCH 1/2] Add Copilot instructions Also update coding style accordingly. --- .github/copilot-instructions.md | 79 +++++++++++++++++++++++++++++++++ documentation/architecture.md | 21 +++------ 2 files changed, 86 insertions(+), 14 deletions(-) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..427bfdeb --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,79 @@ +# Copilot Instructions for TRLC (Starter) + +Use these instructions for any work in this repository. + +## Project profile + +- Repository: TRLC (Treat Requirements Like Code), Python reference + implementation plus docs and Bazel integration. +- Priorities: language correctness, deterministic behavior, and keeping spec/docs/tests aligned. +- Runtime constraints: Python 3.8–3.14 supported. + +## Default workflow + +1. Read nearby docs before changing behavior: + - `documentation/architecture.md` + - `documentation/dev_setup.md` + - `documentation/LRM.md` and `language-reference-manual/` for language-level changes +2. Prefer small, focused patches that solve root causes. +3. Prefer the target style below, even when surrounding code uses older patterns. +4. Introduce style migration incrementally in touched areas; avoid + broad no-op rewrites. + +## Target style migration policy + +Adopt the following style over time in production code: + +- No `assert` statements for runtime behavior checks in production + paths; use explicit validation and errors. +- Prefer f-strings over `%` formatting and `.format(...)` for string interpolation. +- Do not use horizontal alignment for assignments, dict colons, or + similar layout; use regular Python spacing instead. +- Prefer smaller files and split toward one file per class where practical. +- Format code according to Black-compatible conventions. +- Class names shall no longer follow the Ada naming convention, but + shall be in PascalCase (e.g., `MyClass`). +- Function and method names shall be in snake_case (e.g., `my_function`). + +Legacy TRLC code used runtime `assert` checks heavily; migrate away +incrementally by replacing them with explicit validation and proper +error handling in touched code. + +When changing existing code, apply these rules in the edited scope where safe. +Old code may remain in legacy style until it is touched for other reasons. + +## Environment and commands + +Repo is migrating Make→Bazel: prefer Bazel; use Make only if no Bazel target exists. + +## Change policy by area + +### Python implementation (`trlc/`, `trlc.py`, utilities) + +- Add or update tests for behavior changes (unit and/or system tests as appropriate). +- Preserve existing public API and CLI semantics unless task explicitly + requires a breaking change. +- Keep error messages and diagnostics stable where feasible (many tests assert exact output). + +### Language and checker behavior + +- If language semantics change, update both: + - language reference/manual sources in `language-reference-manual/` and/or `documentation/` + - relevant tests and expected outputs +- Keep code, docs, and traceability artifacts logically in sync in the same change. + +## Guardrails + +- Do not edit generated artifacts unless explicitly requested (for + example `docs/` HTML output files). +- Do not introduce new dependencies unless necessary; if added, update + the appropriate requirements files. +- Avoid broad renames/moves unless the task specifically asks for structural changes. +- Keep commits/patches atomic: code + tests + docs that belong to the + same behavior change. + +## Expected Copilot output style + +- Explain assumptions briefly when requirements are ambiguous. +- Propose the smallest safe implementation first. +- After edits, run the narrowest relevant checks first, then broader checks if needed. diff --git a/documentation/architecture.md b/documentation/architecture.md index c8c70497..b27398c6 100644 --- a/documentation/architecture.md +++ b/documentation/architecture.md @@ -14,26 +14,19 @@ is a good place to start. Most of these are checked with `make lint`. Generally normal Python, with some changes: -* Class names follow Ada naming convention (e.g. LASER_Is_An_Acronym) -* Methods are lowercase with underscores (e.g. eat_potato) -* Just use simple `%` string formatting -* Horizontal alignment where reasonable, for example +* Use regular Python spacing (no horizontal alignment), for example ```python x = { - "potatos" : 12, - "cats" : 3, + "potatos": 12, + "cats": 3, } ``` -* Asserts for the types of all parameters (except self), for all - functions or methods, all the time, e.g: - - ```python - def do_something(self, other, thing=None): - assert isinstance(thing, str) or thing is None - assert isinstance(other, Some_Object) - ``` +* Do not use `assert` statements for runtime behavior checks in + production code paths. Use explicit validation and proper error + handling through the existing TRLC error/message interfaces, or + raise exceptions. * Never assume anything in conditions, always deal with all cases. In practice this means the final else clause in an if statement that From b1ba6bba90761cffe613a8d9cf217e8a5619b759 Mon Sep 17 00:00:00 2001 From: Philipp Wullstein-Kammler Date: Thu, 23 Jul 2026 12:49:14 +0200 Subject: [PATCH 2/2] Add Copilot instructions for message handling Extend instructions how to use the `Message_Handler` class, to avoid `print` statements and to give concise user feedback. --- .github/copilot-instructions.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 427bfdeb..31f7d6eb 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -55,6 +55,34 @@ Repo is migrating Make→Bazel: prefer Bazel; use Make only if no Bazel target e requires a breaking change. - Keep error messages and diagnostics stable where feasible (many tests assert exact output). +### Problem signaling with Message_Handler + +- Use `Message_Handler` for all user-visible diagnostics in parser, lexer, + checker, and related tooling code. Do not introduce ad-hoc `print(...)` + based error/warning output. +- Prefer the dedicated API methods: + - `mh.error(location, message, explanation=None, fatal=True, user=False)` + for errors. Use `fatal=False` only when recovery is intentional. + - `mh.warning(location, message, explanation=None, user=False)` for + non-fatal warnings. + - `mh.check(location, message, check, explanation=None)` for lint/check + style findings that need a check category. + - `mh.lex_error(location, message)` for lexer-originated fatal errors. + - `mh.ice_loc(location, message)` only for internal-compiler-error paths. +- For user-facing diagnostics, do not leave `explanation` as `None` unless + there is truly no actionable guidance possible. +- Prefer explanations that help users fix the issue: describe what went + wrong, why it is invalid in this context, and the concrete next step. +- Keep explanations specific and stable (avoid vague text like "invalid" + without remediation guidance). +- Always pass a precise `Location` so diagnostics include source context. +- When an issue originates elsewhere, include + `mh.cross_file_reference(other_location)` in the explanation text to add + traceable cross-file context. +- Keep diagnostic wording concise and stable; many tests assert exact output. +- Count semantics are handled by `Message_Handler` (`warnings`, `errors`, + `suppressed`); do not duplicate manual counters in new code. + ### Language and checker behavior - If language semantics change, update both: