1  # Bar - BAsh Rulez AI Coding Instructions
  2  
  3  Bar is a rule-based command runner implementing a declarative workflow system for bash. It resembles make/just but adds rule caching, conditional evaluation, git hook integration, and background job scheduling.
  4  
  5  ## Immediate Checklist
  6  
  7  - Run `./bar` before every commit; it validates lints, tests, docs, and rebuilds the README. Fix any reported issues first.
  8  - Only commit the README when you meaningfully update documentation or finish a task for review.
  9  - Keep `.github/copilot-instructions.md` current as new guardrails emerge; remove outdated guidance promptly.
 10  - Ensure every `tests/test_*.sh` script is executable and that `./bar tests` passes cleanly.
 11  
 12  ## Development Workflow
 13  
 14  - Clarify the requirement, then inspect existing modules for comparable patterns.
 15  - Extend existing rules and hooks when possible instead of writing bespoke scripts.
 16  - Run shellcheck on touched shell scripts (`shellcheck <file>` or `./bar lints`) and resolve findings.
 17  - Add or update automated tests covering success, failure, and edge cases for new behaviour.
 18  - Update `Bar.d/help` whenever behaviour or CLI contracts change, then run `./bar doc` to regenerate the README when appropriate.
 19  - when changing something to figure out if it works/fixes something and this was not the case, then undo those changes before committing. 
 20  - Stage work logically and write concise commit messages that capture rationale and testing.
 21  
 22  ## Code Quality and Testing
 23  
 24  - `./bar` orchestrates the core pipeline; it must succeed prior to committing.
 25  - `./bar tests` executes the full suite defined in Barf; run it before submission.
 26  - The `shellcheckrc` configuration governs linting expectations; follow it for consistent shellcheck runs.
 27  - New tests belong in `tests/` with the `test_*.sh` naming convention and executable bit set.
 28  - Reuse existing helpers such as the `testdir` system for isolated environments instead of custom scaffolding.
 29  - **IMPORTANT: For each bug found, add a reproducer test to `tests/` before fixing it.** This ensures the bug is properly captured and prevents regressions.
 30  
 31  ## Documentation
 32  
 33  - `Bar.d/help` is the single source of user-facing documentation; avoid ad-hoc docs elsewhere.
 34  - Regenerate the README with `./bar doc` after material help changes and include it in commits when content meaningfully changes.
 35  - Headings: use three leading hashes for file-level descriptions and two leading hashes for individual rules or functions inside help modules.
 36  - Follow the documented parameter grammar: `<param>` for required values, `[param]` for optional, `..` for repetition, `a|b` for alternatives, and literal tokens for fixed strings. Prototypes bind specific completers.
 37  - Study `README` when you are tasked to write bar rules.
 38  
 39  ## Completion System Reference
 40  
 41  - `contrib/bar_complete` implements parameter-aware completion with module tracking, prototype registry, predicate filtering, and result caching.
 42  - Register prototypes via `# prototype: "name" = "spec"` comments or `module_prototype_complete` functions; specs map to built-ins like `file`, `file existing`, `ext func`, or `extcomp command`.
 43  - Resolver order prefers `module@proto`, then `func@proto`, falling back to global `proto` definitions.
 44  - Literal punctuation in prototypes (such as `[+toolchain]` or `<rule:>`) is preserved; completions inject the literal when the user has not typed it yet.
 45  - External completers reuse the invoking command (for example `./bar --bare ...`) and cache results in `_bar_completion_extcomplete_cache` for efficiency.
 46  
 47  ## Architecture Overview
 48  
 49  - `bar` - main script handling module loading and rule evaluation.
 50  - `Bar.d/` - module directory with rule libraries and tooling support.
 51  - `Barf` - project rule file (Makefile analogue) defining orchestration.
 52  - Rule engine provides dependency graphs, caching, conditional execution, and background scheduling.
 53  
 54  ## Rule System Essentials
 55  
 56  - Rules use the syntax `rule [name:] [deps..] [-- body]` and behave as cached pure functions.
 57  - Default rules are conjunctive; add `--disjunct` to stop at the first succeeding clause.
 58  - Dependency modifiers: `dep?` skips if the dependency fails, `!dep` expects failure, and `dep~` forces execution.
 59  - Lifecycle hooks include `SETUP`, `PREPROCESS`, `MAIN`, `POSTPROCESS`, and `CLEANUP`.
 60  
 61  ## Module System
 62  
 63  - `*_lib` modules expose function libraries; load them explicitly with `require name_lib`.
 64  - `*_rules` modules hook into standard targets and auto-load at startup.
 65  - Single-word modules load lazily when their rule prefix is invoked.
 66  - Completion helpers follow `module_prototype_complete` naming with lowercase alphanumeric segments.
 67  
 68  ## Standard Integration Points
 69  
 70  - Standard targets in `std_rules`: `build` (via `build_libs` and `build_bins`), `tests` (`test_units`, `test_integrations`), `lints` (`lint_sources`, `lint_docs`), and `all` (`build`, `doc`).
 71  - Git hook execution: `SETUP` → `PREPROCESS` → branch-specific main rule → `POSTPROCESS` → `CLEANUP`; enable hooks with `./bar activate`.
 72  - Branch defaults (`Barf.default`): feature branches run fast checks, devel branches run full tests, main/release branches perform exhaustive validation.
 73  
 74  ## Development Commands
 75  
 76  - `./bar` - run the full pipeline (lints, tests, docs, build).
 77  - `./bar fastchk` - execute quick, branch-aware checks.
 78  - `./bar watch` - start the file watcher for continuous testing.
 79  - `./bar activate` - install configured git hooks.
 80  - `./bar help <module>` - render module documentation.
 81  - `./bar --debug <rule>` - run a rule with verbose diagnostics.
 82  - `./bar testdir_enter` / `./bar test_staged` - set up isolated test directories.
 83  
 84  ## Testing Infrastructure
 85  
 86  - `tests/test_*.sh` scripts validate functionality; ensure they use repository-relative sourcing via the `SCRIPT_DIR` and `REPO_ROOT` pattern.
 87  - The `testdir` system creates clean environments from git trees for reproducible runs.
 88  - `memodb` enables background job scheduling; pair `memodb_schedule` with `memodb_result` during async testing scenarios.
 89  - Completion features have dedicated integration tests under `tests/`.
 90  
 91  ## Project Notes
 92  
 93  - The project is self-hosting; Bar manages its own workflows through Bar rules.
 94  - Production code must not contain `DBG` statements.
 95  - The module system operates entirely within the repository without external path assumptions.
 96  - Bash completion relies on parameter prototypes and should remain consistent across modules.
 97  - `is_cargo_toolchain_available` must not depend on `rustup`; many environments ship only distro `cargo`.
 98  
 99  ## Key Patterns for Extension
100  
101  - Add tool support by creating `<tool>_rules` modules that extend standard targets and paired `<tool>` modules containing implementations plus detection helpers (for example `is_tool_project`).
102  - Compose workflows with multi-clause rules or disjunctive fallbacks instead of large monolithic scripts.
103  - Encode branch-aware or conditional behaviour using built-in predicates within rule clauses.
104  
105  ## Patterns and Examples
106  
107  ```
108  function my_function ## <required> [optional] - Summary
109  {
110      ## <required> - Required parameter description
111      ## [optional] - Optional parameter description
112  }
113  
114  ## <arg> [options..] - Rule summary
115  rule my_rule:
116      ## <arg> - Explanation
117      ## [options..] - Option details
118  
119  function mymodule_mytype_complete ## Emit completions for mytype
120  {
121      echo "option1"
122      echo "option2"
123  }
124  ```
125  
126  ## Project Structure
127  
128  - `bar` - entrypoint script.
129  - `Bar.d/` - modules for libraries, rules, and tooling.
130  - `Bar.d/help` - authoritative documentation source.
131  - `contrib/bar_complete` - bash completion implementation.
132  - `tests/` - integration and regression suite.
133  
134  ## Git History Guidance
135  
136  - Store implementation notes and context in commit messages rather than standalone files.
137  - Keep messages brief but informative, describing behaviour changes, rationale, and tests executed.
138  
139  ## Configuration and References
140  
141  - `Barf.default` - template showcasing branch-aware orchestration.
142  - `example/` - comprehensive syntax demonstrations and fixtures.
143  - `Pleasef.default` - please integration example.
144  - Use `./bar help` and module sources in `Bar.d/` as primary references when extending functionality.
145  
146  # Tasks
147  
148  ## Rewrite the completion engine in contrib/bar_complete 
149  
150  The new implementation should be more streamlined and regular.
151  
152  general instructions:
153  - Focus on rewriting the engine, but if necessary you can touch all other functions and refine them for the tasks.
154  - make a plan for the rewrite, write that to a file, execute it step by step, confirm every step is working with tests
155  - in the current engine we implemented some caching. the rewrite needs that too, but it should be readded as the last step.
156  - When any existing test/completion breaks, consider the lack of a prototype definiton, predicate, completer (in that order). If neceessary implement those (also consider that order, new completers should be only implemented when the completion cant be composed by existing ones) 
157  
158  observations:
159  - parameter specifications have the following syntax
160      - literal
161          - anything not inside `<>` or `[]` is considered literal, when one wants to have literals inside <> or [] one has to define a literal prototype for that `# prototype: "lit" = "literal lit"`, exception here is that `--` and `-` prefixes make the parameter literal even inside <> and []
162          - punctuation is literal except prefix `--` and `-` and the suffix `..` used for repetions and '|' which is the alternatives operator
163      - <proto>
164          - Mandatory parameter (prototype)
165          - the proto may be prefixed or suffixed by literal punctuation which then has a higher precedence than | or ..  ( [foo:..]  is many 'foo:' not foo with many colons) 
166              - this can should be implented by some hidden grouping.
167      - [proto]
168          - Optional parameter (prototype)
169      - group
170          - anything inside <> or [] or a hidden group
171              - groups can be nested ([foo [[bar] baz]])
172      - param
173          - is either a literal, proto or group
174      - proto.. or group..
175          - a `..` suffix means multiple occurences
176              - <proto..> or <proto>..
177                  - One or more occurrences
178              - [proto..] or [proto]..
179                  - Zero or more occurrences
180      - param|param
181          - the `|` is used for alternatives, can be used multiple times `--foo|--bar|--baz`
182          - can be outside groups (--foo|--bar) or inside ([this|that])
183          - has a lower precedence than `..` (<foo|bar..> is either one foo or many bar)
184      - --flag or -f
185          - Literal flag / short flag
186          - stays literal even inside <> and []
187  - The engine has the protos array which can be an aribitrary list of parameters specs.
188  
189  
190  
191  Completion process:
192  I sketch here a completion algorithm. before you start, check it for correctness and soundness. ask back if anything is not clear, correct any mistakes. Are there any corner cases and unclear specifications?
193  
194  - make a detailed plan on how you implement this algorithm
195  - if possiblle and sound try to make it as minimal as possible, dont add things that are not necessary.
196  
197  - collect all prototypes for the current position. This means all alternative prototypes in the protos array up to the first non alternative part
198      - since each entry in the protos array can be a nested group, this needs to be handled as well:
199          `protos=("[[--verbose] foo [bar|baz]]" "--flag|--other" "<later>")` (proto_idx=0)
200          will collect '--verbose', foo, '--flag', '--other'
201          - remember somewhere (another array) for each collected item from what proto position it came: (0 0 1 1)
202          - the --flags are literal
203          - foo is a prototype and eventually resolves to a completer which returns a list of possible completions.
204          - [bar|baz] won't be reached because the foo before it is mandatory.
205          - <later> won't be reached because "--flag|--other" are non optional alternatives
206          - write a test for this, testing the good case, failures and corner cases
207      - once the completion is done, we need to calculate how to proceed:
208          - set proto_idx to the the index from what the completion came from, then refine that entry:
209              - backup the current entry (stack)
210              - remove the completed part eg:
211                  - when the user completed `--verbose` then protos[0] becomes `[foo [bar]]` 
212                  - when the user completed `foo` then protos[0] becomes `[[bar|baz]]` (or simplified to `[bar|baz]`)
213              - when the refined entry becomes empty then we increment proto_idx
214              - when the user stepped back we need to restore from the backup we made earlier
215                  - when that stack becomes empty then decrement proto_pos
216  
217  - proto lookup rules
218      - every prototype eventually calls a completer
219      - prototyoes have a 1 level module "module:proto"
220      - lookup rules:
221          1. prototype for the current module
222          2. global prototype
223          3. completer function
224  
225      example: when a module 'foo' has a `function bar ## <file> - foo:bar`
226      then it searches "foo:bar" and then "bar" in the prototype registry,
227      when that is not found it checks if a `_bar_complete_comp_file` function exists.
228                                                  
229  # COPILOT PLAN AND COMMENTS
230  
231  - Rewriting `contrib/bar_complete` will require a full grammar-driven parser for parameter specs so we can expand nested groups, repetitions, and literals deterministically before dispatching to completers.
232  - We must stage the work: (1) design and document the parser/state machine in a plan file, (2) implement the new engine without caching, validating via existing completion tests plus new coverage for nested alternatives, (3) reintroduce caching and ensure no regressions.
233  - Critical risks: faithfully handling hidden grouping precedence (`..` vs `|`), backward navigation stack mechanics, and ensuring prototype lookup order (`module@proto` → global → function) still works for legacy modules.
234  - Extra test investments: targeted cases for mixed literal/prototype alternations, nested optional groups, and regression tests for cargo build/test args to prove the new traversal logic is sound.