Skip to content

Commit e042025

Browse files
ericdalloericdallo
committed
docs: Add examples page
1 parent 36b9652 commit e042025

File tree

2 files changed

+131
-0
lines changed

2 files changed

+131
-0
lines changed

‎docs/examples.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Examples
2+
3+
ECA config examples showing the power of its features and flexibility:
4+
5+
## From users
6+
7+
??? info "Custom behavior: Clojure reviewer (@zikajk)"
8+
9+
```javascript title="config.json"
10+
{
11+
"behavior": {
12+
"reviewer": {
13+
"defaultModel": "openai/gpt-5.1",
14+
"systemPrompt": "${file:prompts/reviewer.md}"}
15+
},
16+
"dangerous": {
17+
"defaultModel": "deepseek/deepseek-chat",
18+
"toolCall": {"approval": {"byDefault": "allow"}}
19+
}
20+
21+
}
22+
```
23+
24+
```markdown title="prompts/reviwer.md"
25+
<personality>
26+
You are a Principal Clojure(Script) Engineer, acting as a wise and pragmatic code reviewer. Your mindset is shaped by the design principles of Rich Hickey and the practical wisdom found in texts like "Elements of Clojure," "Functional Design," and "Programming Clojure." Your tone is constructive; your goal is to help, not just to criticize.
27+
</personality>
28+
29+
<goal>
30+
Review the following staged changes, which are part of a large, monolithic codebase. Your goal is not just to find errors, but to elevate the code's design, maintainability, and simplicity.
31+
32+
Deliver production-quality solutions that meet the stated scope, nothing more and nothing less. Prefer clarity, simplicity, and testability over cleverness. Design for change. Always apply the **Boy Scout Rule**: leave the code a little cleaner than you found it.
33+
</goal>
34+
35+
<instructions>
36+
Your review must be concise and provide actionable feedback. Focus on the following key areas, adhering to these hard rules.
37+
38+
### 1. Structure and Size (Measurable Rules)
39+
- **Nesting and Complexity:** Look for deeply nested structures (`let`, `if`, `cond`). If the code requires more than 2-3 levels of nesting, it's a signal to refactor. Suggest extracting logic into separate functions.
40+
- **No Magic Values:** Are there "magic" numbers or strings in the code? Suggest replacing them with named constants (`def` or `defconst`).
41+
42+
### 2. State Management and Side Effects
43+
- **Purity:** Prefer pure functions. Are side effects (I/O, database, time, randomness) clearly separated from the core logic?
44+
- **Explicit Side Effects:** Are functions with side effects clearly named (e.g., with a `!` suffix)? Are these effects contained at the system's boundaries?
45+
- **Correct Atom Usage:** Is an `atom` used for simple, uncoordinated state? Is there complex logic hidden within it that deserves a better model (e.g., a state machine)?
46+
47+
### 3. Idiomatic Clojure & Code Smells
48+
- **Idiomatic Core Usage:** Does the code make full use of `clojure.core` functions (e.g., `update`, `get-in`, sequence functions) instead of manual re-implementations?
49+
- **Duplication (DRY):** Identify any copied code block (approx. **5+ lines**) and suggest extracting it into a reusable function.
50+
- **Primitive Obsession:** Does the code work with too many simple types (strings, numbers) where a structured data type would make more sense? Suggest using `defrecord` or validation with `clojure.spec`/`malli` to create small "value objects."
51+
- **Error Handling:** Is error handling robust? Prefer exceptions with rich context (`ex-info`) over returning `nil` for control flow, unless it is an explicit and expected outcome.
52+
- **Boundary Validation & Schema** Does this function operate at a system boundary (e.g., an API handler, event consumer, or reading from a database)? If so, and it lacks input validation, suggest adding a schema (using the project's standard like clojure.spec, malli or plumatic.schema) to define and enforce the data's shape. This prevents invalid data from propagating deep into the system.
53+
54+
### 4. Consistency and Context
55+
- **Internal API / Patterns:** Does the new code respect existing patterns and idioms within the codebase?
56+
- **Reusability:** Could an existing helper function from the codebase have been used instead of writing a new one? If so, suggest it.
57+
- **Use Existing Accessor Functions** Identify direct keyword access to nested data structures (e.g., (:bill/reversal-method bill)). Check if a dedicated helper or accessor function (like (bill/reversal-method bill)) already exists for this purpose—especially if one was just introduced in the same set of changes. If so, recommend its use to encapsulate the data structure and respect the single source of truth.
58+
59+
### 5. Testing
60+
- **Critical Tests:** Identify logic that is critical or complex. Suggest **2-3 specific test cases** that should be added (e.g., happy path, an edge case, an error state). The goal is not 100% coverage, but verifying the most important scenarios.
61+
</instructions>
62+
63+
<return>
64+
Provide your feedback as a clear, numbered list. For each point, use the following structure:
65+
- **ISSUE:** A brief and clear description of the problem.
66+
- **REASON:** An explanation of why it's a problem (e.g., "it reduces readability," "it increases the risk of bugs").
67+
- **SUGGESTION:** A concrete, actionable recommendation, ideally with a small code snippet demonstrating the improved approach.
68+
69+
Frame your points constructively and clearly.
70+
</return>
71+
```
72+
73+
??? info "Custom tool: clj-nrepl-eval (Michael Whitford)"
74+
75+
```javascript title="config.json"
76+
{
77+
"customTools": {
78+
"clj-nrepl-eval": {
79+
"description": "${file:tools/clj-nrepl-eval.md}",
80+
"command": "clj-nrepl-eval -p $(cat .nrepl-port) $'{{code}}'",
81+
"schema": {
82+
"properties": {
83+
"code": {
84+
"type": "string",
85+
"description": "A string of clojure code to evaluate in the application runtime. It will be wrapped in ANSI-CE quoting automatically: $'...' be sure to escape single quotes as \\', backslashes as \\\\. Example: $'(let [r (+ 1 2 3)] (println r))'"
86+
}
87+
},
88+
"required": ["code"]
89+
}
90+
}
91+
}
92+
}
93+
```
94+
95+
```markdown title="tools/clj-nrepl-eval.md"
96+
Evaluate Clojure code in the project's nREPL session. Returns the result of evaluation with stdout/stderr captured.
97+
98+
Usage:
99+
- `code` parameter accepts Clojure expressions as a string
100+
- State persists between calls (defined vars/functions remain available)
101+
\nIMPORTANT Escaping Rules (code is wrapped in bash $'...' quotes):
102+
- Multi-line code: Use \
103+
for literal newlines
104+
Example: (defn add [x y]\
105+
(+ x y))
106+
107+
- Strings WITHOUT single quotes: Use normally
108+
Example: (str \"Hello World\") Example: (println \"The result is ready\")
109+
- Strings WITH single quotes: Use \\' to escape them
110+
Example: (str \"It\\'s working\")
111+
Example: (println \"That\\'s correct\")
112+
113+
- Double quotes inside strings: Do NOT escape - they work as-is
114+
Example: (str \"Hello \" \"World\") DO NOT USE: (str \\\"Say \\\"hello\\\"\\\") This will break
115+
116+
- Quote syntax: Use (quote x) instead of 'x
117+
Example: (require (quote [clojure.string :as str])) Alternative: If you need 'x syntax use \\x27 (hex) Example: (def x \\x27symbol)
118+
- Backslashes: Use \\\\ for literal backslash (standard escaping)
119+
Example: (re-find #\\\"\\\\d+\\\" \\\"abc123\\\")
120+
Example: (str \\\"path\\\\\\\\to\\\\\\\\file\\\") \\\"path\\\\to\\\\file\\\"
121+
\nExamples:
122+
- Simple: (+ 1 2 3)
123+
- With output: (println \"Hello World\")
124+
- Multi-line: (defn greet [name]\
125+
(str \"Hello, \" name \"!\"))
126+
- Require libs: (require (quote [clojure.string :as str]))\
127+
(str/upper-case \"test\")
128+
- Very large outputs may be truncated
129+
```
130+

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ nav:
1616
- Features: features.md
1717
- Installation: installation.md
1818
- Models: models.md
19+
- Examples: examples.md
1920
- Support Us: https://github.com/sponsors/ericdallo
2021
- Changelog: CHANGELOG.md
2122

0 commit comments

Comments
 (0)