Add jbeam extraction tooling and project documentation - #226
Merged
Conversation
Adds .claude/settings.json with allowlist rules for beamng helper
functions, restricting extraction output to /tmp/jbeam-edit-* paths.
Renames temp directories from /tmp/jbeam-{tune,transform}-XXXXXX to
/tmp/jbeam-edit-{tune,transform}-XXXXXX for clarity.
Two spaces for shell, no logic touched.
--transform also rewrites the other .jbeam files next to it, so a shared work directory made the files rewrite each other and every measurement came out against the wrong baseline. Beam validation now runs per vehicle for the same reason. One pass says almost nothing either. Names that grow, comments that swap places and metadata that drifts all look like success until the second run, so the summary now reports whether the file is a fixed point.
A locally installed hpack of another version reformats the whole cabal file and CI rejects it. Also point the transform-check skill at the new per-file directories and the fixed point column.
JBEAM_DOCS.md describes how a nodes section is modelled, what the config actually does when it fails to load, and which input shapes change behaviour when building a fixture. CLAUDE.md gets the agent-facing half: run the binary in an isolated directory before reasoning about the pipeline.
The curated file lists answer tuning questions, not prevalence ones, and extract-tune-examples.sh cannot stand in: it collides on basenames, formats every file and writes inside the repo. corpus-extract.sh pulls all 4900 or so jbeam files into a scratch directory outside it, prefixed by vehicle.
The rule named tools/lib/beamng.sh, which does not exist, so it never matched. Also ignore .claude/settings.local.json in the repo rather than relying on a personal global gitignore, and allow the corpus script and its output.
The skill was never reached, because reviews here go through the review skill in the personal profile, which reads CLAUDE.md and already covers the generic Haskell material through the language guidelines. What was worth keeping is the four checks that depend on how this project uses Haskell rather than on Haskell.
TRANSFORMATION_DOCS.md existed on one machine while an issue linked to it, so the reference pointed at nothing. JBEAM_DOCS.md covered the same ground from the code's side rather than the reader's and goes away with this. Corrected the support index numbering and the Y band description, and wrote down the three ways the config fails quietly.
TRANSFORMATION_DOCS.md deliberately names no functions, so the map from behaviour back to code had nowhere to live. The two facts that cost the most time go with it: breakVertices splits on the name prefix rather than the side, and a wrong metadata model still produces output that reads correctly.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Working on the transformation means testing against real BeamNG files, and until now that meant navigating the install directory and unzipping by hand every time.
tools/extract-and-format-jbeam/puts that behind scripts: a curated list for demo and tuning work, andcorpus-extract.shfor the case where the question is how common something is rather than what one file looks like. That distinction turned out to matter. A dozen files gave the wrong answer three times in one session on questions the full 4900 file corpus answered the other way, so the two entry points are kept deliberately separate and the corpus one refuses to write inside the repo.JBEAM_DOCS.mdis the part of the jbeam format that decides this tool's behaviour: sticky metadata rows, how a nodes section is chunked and sorted, what the config actually does when it fails to load, and which input shapes change the outcome.CLAUDE.mdcovers the build, the layout and the conventions that were previously only in commit messages and heads. Both exist because the same questions kept getting re-derived from the source, and getting re-derived wrong..github/AGENT_INSTRUCTIONS.mdgoes away with this, since Copilot is no longer used and.claude/replaces it. Nothing derived from BeamNG is committed: the file lists hold names and zip names only, and the extraction output is now gitignored so it cannot be picked up by accident.No Haskell changes, so nothing here can affect the build or the released binary.