diff --git a/dev-docs/issues/.next-id.txt b/dev-docs/issues/.next-id.txt index a7625603..0234b515 100644 --- a/dev-docs/issues/.next-id.txt +++ b/dev-docs/issues/.next-id.txt @@ -1 +1 @@ -160 +162 diff --git a/dev-docs/issues/160-concurrent-plcc-build-dir-race.md b/dev-docs/issues/160-concurrent-plcc-build-dir-race.md new file mode 100644 index 00000000..041645c1 --- /dev/null +++ b/dev-docs/issues/160-concurrent-plcc-build-dir-race.md @@ -0,0 +1,57 @@ +# 160 - Concurrent plcc-scan/plcc-make invocations race on shared build dir + +**Type:** fix +**Date:** 2026-07-22 + +## Description + +Running two `plcc-scan` (or presumably any plcc-ng CLI, since they all shell +out to `plcc-make`) invocations concurrently in the same working directory +crashes both processes with a `FileNotFoundError`. Both invocations build +into the same `./plcc-ng/` directory using a temp file +(`tempfile.mkstemp(..., dir=build_dir)`), and there is no locking or +per-process isolation, so one process's cleanup/recreation of the build +directory races with the other's attempt to write or hash its temp file. + +This surfaced in the plcc-ng-demo repo while comparing an in-progress +activity spec against the solution spec using +`diff <(plcc-scan -s activity/spec.plcc < in.txt) <(plcc-scan -s solution/spec.plcc < in.txt)` +— a natural thing for an instructor or student to try, since the two specs +live in sibling directories but the build directory (`plcc-ng/`) is created +relative to the current working directory, not per-spec. + +Sequential invocations of the same commands work fine and produce correct, +matching output — this is purely a concurrency/shared-state bug, not a +scanning correctness issue. + +## Steps to Reproduce + +1. In a directory with a `spec.plcc` (or two sibling directories each with + their own `spec.plcc`), clear any cached build dir: `rm -rf plcc-ng` +2. Run two invocations concurrently, e.g.: + ``` + diff <(plcc-scan -s activity/spec.plcc < activity/testprog.txt) \ + <(plcc-scan -s solution/spec.plcc < activity/testprog.txt) + ``` +3. One or both sides crash with: + ``` + FileNotFoundError: [Errno 2] No such file or directory: '.../plcc-ng/tmpXXXXXXXX.json' + ``` + traced back through `plcc-make`'s `main()` → `tempfile.mkstemp` or + `compute_hash`. +4. Running the two commands sequentially (not via process substitution) + instead of concurrently succeeds every time. + +## Notes + +- Relevant code: `src/plcc/cmd/make.py`, `src/plcc/build/staleness.py` — the + shared `./plcc-ng/` build directory needs either a lock around build-dir + mutation, a per-invocation/per-spec temp directory, or at least a + graceful retry/error instead of an unhandled traceback. +- Low severity for solo interactive use (a student typing one command at a + time won't hit it), but plausible for instructors/graders who script + comparisons, run parallel test suites, or use tools like + `diff <(...) <(...)` — and the failure mode is a raw Python traceback, + not a friendly error. +- Originally filed as issue #2 in `ourPLCC/plcc-ng-demo`, which is where it + surfaced during workshop test-drive. diff --git a/dev-docs/issues/161-rename-plcc-rep-to-plcc-eval.md b/dev-docs/issues/161-rename-plcc-rep-to-plcc-eval.md new file mode 100644 index 00000000..2804c620 --- /dev/null +++ b/dev-docs/issues/161-rename-plcc-rep-to-plcc-eval.md @@ -0,0 +1,54 @@ +# 161 - Consider renaming plcc-rep to plcc-eval for phase-naming consistency + +**Type:** feat +**Date:** 2026-07-22 + +## Description + +The three plcc-ng CLI tools are named inconsistently relative to the phases +of language processing they perform: + +- `plcc-scan` — named after the phase (lexical analysis / scanning) +- `plcc-parse` — named after the phase (syntactic analysis / parsing) +- `plcc-rep` — named after the *interaction mode* (REPL), not the phase + (semantic analysis / evaluation) + +This came up while onboarding to the plcc-ng-demo repo: before reading its +`03-semantic/README.md`, the reader guessed the third tool would be called +`plcc-run` by analogy with a scan → parse → run pipeline, and was wrong — +it's `plcc-rep`. `rep` names the fact that the tool loops +read-eval-print-style, which is true, but it doesn't tell a newcomer which +phase of language processing it belongs to, breaking the pattern the other +two tool names establish. + +Renaming `plcc-rep` to `plcc-eval` would restore the pattern: +`plcc-scan` → `plcc-parse` → `plcc-eval`, each named after its phase +(lexical, syntactic, semantic/evaluation), with the REPL behavior remaining +an implementation detail of how `plcc-eval` runs rather than part of its +name. + +## Notes + +- Two ways to do this, with different classifications: + - **Hard rename** (drop `plcc-rep`, ship only `plcc-eval`): breaking for + anyone with `plcc-rep` in muscle memory, scripts, or course materials + (including plcc-ng-demo's `03-semantic/README.md` and + `solution/README.md`, which would need updating in lockstep). Not a + plain `feat` — needs a breaking-change marker (`feat!` / `BREAKING + CHANGE:` footer) so semantic-release cuts a major version, not a minor + one. + - **Alias** (keep `plcc-rep` working, add `plcc-eval` as a synonym): + purely additive, non-breaking — a plain `feat`. Newcomers get the + phase-consistent name to guess at (as happened, incorrectly, with + `plcc-run`), existing muscle memory and scripts keep working, and the + docs can migrate to `plcc-eval` as the primary name over time while + `plcc-rep` quietly remains as a deprecated-but-working alias. + - The alias approach gets most of the discoverability benefit without + forcing a major version bump or breaking anyone immediately — probably + the better starting point, with a hard rename (and removal of the + alias) reserved for a later major version if ever. +- Not urgent — `plcc-rep` is accurate and "REPL" is well-understood PL + vocabulary — but if the project revisits CLI naming, `plcc-eval` (not + `plcc-run`) is the name that best matches the existing `scan`/`parse` + convention. +- Originally filed as issue #5 in `ourPLCC/plcc-ng-demo`. diff --git a/dev-docs/roadmap.md b/dev-docs/roadmap.md index d4b1f356..06aa2f6b 100644 --- a/dev-docs/roadmap.md +++ b/dev-docs/roadmap.md @@ -2,6 +2,16 @@ ## Open Issues +### Fix + +- **[#160](issues/160-concurrent-plcc-build-dir-race.md) — Concurrent plcc-scan/plcc-make invocations race on shared build dir** + Two CLI invocations sharing the same `./plcc-ng/` build dir race on temp-file creation/cleanup and crash with a raw `FileNotFoundError` traceback instead of a friendly error. + +### Feat + +- **[#161](issues/161-rename-plcc-rep-to-plcc-eval.md) — Consider renaming plcc-rep to plcc-eval for phase-naming consistency** + `plcc-rep` is named after its interaction mode (REPL), not its phase, breaking the `scan`/`parse`/`?` naming pattern; an alias or rename to `plcc-eval` would restore it. + ### Test - **[#153](issues/153-test-artifacts-outside-project-dir.md) — Test artifacts land outside the project directory**