okstra 0.228.0 → 0.228.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
package/runtime/BUILD.json
CHANGED
|
@@ -20,7 +20,7 @@ Good:
|
|
|
20
20
|
const sum = (arr) => arr.reduce((acc, x) => acc + x, 0);
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
Caveat:
|
|
23
|
+
Caveat: extract when two current callers implement the same capability and would change together. Similar syntax alone does not establish a shared capability; keep independent decisions separate. Do not add an abstraction for a hypothetical second caller. A literal copy of an existing capability — test helpers included — reuses or moves the existing implementation.
|
|
24
24
|
|
|
25
25
|
Two more forms of duplication that hide from symbol-level grep:
|
|
26
26
|
|
|
@@ -33,14 +33,16 @@ The simplest solution that meets the requirement wins. Cleverness has a maintena
|
|
|
33
33
|
|
|
34
34
|
Bad:
|
|
35
35
|
```javascript
|
|
36
|
-
|
|
36
|
+
const canSubmit = isReady ? true : false;
|
|
37
37
|
```
|
|
38
38
|
|
|
39
39
|
Good:
|
|
40
40
|
```javascript
|
|
41
|
-
|
|
41
|
+
const canSubmit = isReady;
|
|
42
42
|
```
|
|
43
43
|
|
|
44
|
+
Here `isReady` is already a boolean, so both versions preserve the same value. Do not replace explicit null, undefined, or empty-string checks with a truthiness check unless rejecting `0`, `false`, and `NaN` is also intended.
|
|
45
|
+
|
|
44
46
|
## SOLID
|
|
45
47
|
|
|
46
48
|
- **S**ingle Responsibility — one reason to change per class / module.
|
|
@@ -95,8 +97,8 @@ The name must describe what the function actually does. Misleading names break r
|
|
|
95
97
|
|
|
96
98
|
Flag and rename:
|
|
97
99
|
|
|
98
|
-
- `get*` / `fetch*` / `find*` that also
|
|
99
|
-
- `is*` / `has*` / `can*` that
|
|
100
|
+
- `get*` / `fetch*` / `find*` that also perform caller-visible state changes their read-oriented names do not disclose. Documented lookup failures and diagnostic logging do not by themselves make a read name misleading.
|
|
101
|
+
- `is*` / `has*` / `can*` that use an exception for an ordinary negative answer instead of returning `false`. An operational failure may still propagate under a documented failure contract.
|
|
100
102
|
- `find*` that *creates* the entity when missing → `findOrCreate*` or `ensure*`.
|
|
101
103
|
- Names that describe the implementation, not the intent: `loopOverUsers` → `notifyActiveUsers`, `runQuery` → `listOverdueInvoices`.
|
|
102
104
|
- Names that say the opposite of what they do under some branch: `enableFoo` that disables when a flag is off, with no hint in the name.
|
|
@@ -129,9 +131,9 @@ The test: grep the identifier across the file. If two occurrences carry differen
|
|
|
129
131
|
|
|
130
132
|
## Functions do one thing
|
|
131
133
|
|
|
132
|
-
|
|
134
|
+
A name containing "and" or a body requiring scrolling is a reason to inspect responsibilities, not proof that a split is needed. Split when the body mixes independent responsibilities or levels of abstraction; apply the 50-line cap below separately.
|
|
133
135
|
|
|
134
|
-
|
|
136
|
+
A short orchestrator may call several already-named steps at the same abstraction level:
|
|
135
137
|
```javascript
|
|
136
138
|
function handleData() {
|
|
137
139
|
fetchData();
|
|
@@ -140,7 +142,7 @@ function handleData() {
|
|
|
140
142
|
}
|
|
141
143
|
```
|
|
142
144
|
|
|
143
|
-
|
|
145
|
+
The body above does not need further splitting: each step is already a separate function. The generic name `handleData` is a naming issue; choose a name for the overall operation based on the caller's purpose.
|
|
144
146
|
|
|
145
147
|
### Plain-English summary test
|
|
146
148
|
|
|
@@ -148,11 +150,11 @@ For every function you add or meaningfully modify, ask:
|
|
|
148
150
|
|
|
149
151
|
> Can I summarize what this function does, line by line, as a short English sentence per line — and does the resulting summary read as prose?
|
|
150
152
|
|
|
151
|
-
If the answer is "no, I'd have to group several lines together and invent a name for the group", **that grouping should already exist in the code as a named helper or named intermediate value**. The fact that you had to invent the name is the signal to extract.
|
|
153
|
+
If the answer is "no, I'd have to group several lines together and invent a name for the group", **that grouping should already exist in the code as a named helper or named intermediate value**. The fact that you had to invent the name is the signal to extract. A local readability helper can have one caller; the second-caller requirement applies to reuse-driven abstraction layers.
|
|
152
154
|
|
|
153
|
-
###
|
|
155
|
+
### Inspect for readability problems
|
|
154
156
|
|
|
155
|
-
-
|
|
157
|
+
- Three nested control-flow blocks — inspect whether early returns or named predicates improve readability. Four or more require refactoring under "Limit nesting depth" below.
|
|
156
158
|
- Mixed levels of abstraction — a high-level orchestrator suddenly doing string parsing, date arithmetic, or SQL assembly inline.
|
|
157
159
|
- A reader has to track 5+ anonymous temporary values to understand the return.
|
|
158
160
|
- A long `.map().filter().reduce()` chain where each stage does non-obvious work and no stage has a name.
|
|
@@ -170,7 +172,7 @@ Crossing the cap is an extraction signal, not a style nit. Before declaring a fu
|
|
|
170
172
|
### What's fine
|
|
171
173
|
|
|
172
174
|
- Functions that read as a straight sequence of clear, already-named steps (each line is an English sentence).
|
|
173
|
-
- Short functions (< ~10 lines)
|
|
175
|
+
- Short functions (< ~10 lines) with a clear purpose and readable flow. Shortness does not exempt a function from the nesting-depth rule or other applicable checks.
|
|
174
176
|
- Idiomatic framework patterns used clearly (a 30-line controller method obviously doing its job).
|
|
175
177
|
- Guard clauses at the top — they *help* readability, they don't count against you.
|
|
176
178
|
|
|
@@ -228,6 +230,8 @@ Replacing a typed library error with a bare one throws away what the caller need
|
|
|
228
230
|
|
|
229
231
|
These principles apply to every test file regardless of language or framework. The mechanical detection patterns (which mock library, which spy API) are in each `languages/*.md` Tests section.
|
|
230
232
|
|
|
233
|
+
Follow the testing-waiver policy in `overview.md` "Tests planned". An explicit waiver applies only to the named behavior or check, including its branch-test, branch-deletion, or resource-bound requirement. Record that scope as unverified. All checks outside the waiver and the quality rules for tests that are written or edited still apply.
|
|
234
|
+
|
|
231
235
|
### No self-mocking
|
|
232
236
|
|
|
233
237
|
A unit test for class `Foo` must **not** stub, spy on, or replace methods on the instance of `Foo` being tested. Mocking injected collaborators (other services, repositories, adapters, ports, the clock) is fine and expected.
|
|
@@ -332,7 +336,7 @@ The failures the plan names are where the trace starts, not where it stops. Two
|
|
|
332
336
|
|
|
333
337
|
A failure the test fakes cannot produce is not covered by a passing test. Name it as unverified rather than calling the path clean.
|
|
334
338
|
|
|
335
|
-
**
|
|
339
|
+
**An execution-error finding names the input or state that produces the wrong result.** *"If the archive yields no entries, line 42 reports success and stores an empty result"* is an execution-error finding. A design-violation finding instead identifies the applicable rule, the violating code, and its concrete design or maintenance consequence; it does not require a runtime failure. An alternative implementation or preferred name alone establishes neither kind. Guards for states no caller can reach and extra tests for already-covered behavior are optional improvements unless a separate applicable rule violation is demonstrated. A real failure that is small and cheap to fix is still a finding.
|
|
336
340
|
|
|
337
341
|
## Untrusted input and security
|
|
338
342
|
|
|
@@ -346,13 +350,13 @@ A size or count limit protects nothing if a costlier check still runs on the ove
|
|
|
346
350
|
|
|
347
351
|
Input that reaches SQL, a shell command, a file path, a URL fetched server-side, a template, or a regular expression goes through a parameter, an allowlist, or an escaping API for that sink — never string concatenation or interpolation. A path from input is resolved and checked to stay under its root; a server-side fetch target is checked against an allowlist of hosts.
|
|
348
352
|
|
|
349
|
-
### Every new entry point checks
|
|
353
|
+
### Every new entry point checks the caller's access rights
|
|
350
354
|
|
|
351
|
-
A new route, handler, resolver, or job that reads or writes per-user data
|
|
355
|
+
A new route, handler, resolver, or job that reads or writes per-user data establishes the caller or execution identity through the project's authentication mechanism and checks permission for the requested operation before returning or changing the resource. Apply the project's access policy: ownership, shared access, tenant membership, or an authorized administrative role may establish permission. An id the caller can choose is not proof of access. An explicitly public operation follows the project's public-access policy rather than requiring a user identity.
|
|
352
356
|
|
|
353
|
-
###
|
|
357
|
+
### Protect secrets and limit personal-data disclosure
|
|
354
358
|
|
|
355
|
-
|
|
359
|
+
Keep real secrets, tokens, and credentials out of source and fixtures meant for production. Logs and error messages do not expose secrets, full tokens, passwords, or personal data through echoed request bodies or upstream errors passed through verbatim. A response may return personal data only when the operation's access policy authorizes the recipient and the fields are needed for its documented purpose. Credentials or tokens are returned only by operations explicitly designed to issue them to an authorized recipient; unrelated responses do not echo them.
|
|
356
360
|
|
|
357
361
|
### No execution of input
|
|
358
362
|
|
|
@@ -367,7 +371,7 @@ Good: `const LEGAL_AGE = 18; if (age > LEGAL_AGE)`
|
|
|
367
371
|
|
|
368
372
|
## Limit nesting depth
|
|
369
373
|
|
|
370
|
-
|
|
374
|
+
Count nested control-flow blocks within each function; the function, class, and module bodies do not count. At three levels, inspect readability rather than requiring a split solely for the count. At four or more, flatten with early returns or extract a named step before completion. Short functions follow the same threshold. Enforcement is the preflight self-check and code review.
|
|
371
375
|
|
|
372
376
|
Bad:
|
|
373
377
|
```javascript
|
|
@@ -396,6 +400,8 @@ function process(user) {
|
|
|
396
400
|
|
|
397
401
|
The code already says **what**. Comments record the hidden constraint, the bug being worked around, the surprising tradeoff. Never narrate the next line.
|
|
398
402
|
|
|
403
|
+
Interface documentation may describe caller-visible contracts that the signature cannot express: error versus ordinary negative results, missing-input behavior, side effects, or security constraints. This is not redundant narration of an implementation. Verify the documented behavior against implementations, callers, and relevant tests; do not infer it from the documentation alone. When the contract requires non-obvious work, explain its reason if that reason is established by evidence.
|
|
404
|
+
|
|
399
405
|
Bad:
|
|
400
406
|
```javascript
|
|
401
407
|
// increment i
|
|
@@ -5,9 +5,9 @@ These rules apply to every worker writing or editing project code (executor and
|
|
|
5
5
|
## Core principles
|
|
6
6
|
|
|
7
7
|
1. **DRY — single reference point** — One implementation per capability. A second caller signals "extract shared logic", not "duplicate path".
|
|
8
|
-
2. **KISS — simplest sufficient design** — Add abstraction layers (helper modules, strategy/factory, configuration flags, indirection) only when
|
|
9
|
-
3. **YAGNI — build only for current requirements** — No speculative parameters, optional configs, "future-proof" hooks, or pre-1.0 backwards-compat shims. *Self-check: every newly introduced identifier
|
|
10
|
-
4. **Clean Code — names carry WHAT, comments explain WHY** — Identifiers must make intent obvious;
|
|
8
|
+
2. **KISS — simplest sufficient design** — Add reusable abstraction layers (helper modules, strategy/factory, configuration flags, indirection) only when current callers require them. For reuse-driven extraction, name the second caller now; otherwise inline. A local helper with one caller is appropriate when it names a distinct step in a mixed-level function or brings a body under the 50-line cap. Keep that helper local rather than introducing a reusable layer. Project-required architecture boundaries still apply. *Example violation: extracting a shared `formatUserName()` module used by exactly one call site, "in case we need it elsewhere".*
|
|
9
|
+
3. **YAGNI — build only for current requirements** — No speculative parameters, optional configs, "future-proof" hooks, or pre-1.0 backwards-compat shims. *Self-check: every newly introduced identifier serves a current internal use, an established external contract, a runtime entry point, or an explicit user requirement. Cite the caller, contract, registration, or requirement; a hypothetical future consumer is not evidence.* *Example violation: adding `options?: { retries?, timeout? }` parameter when the current call passes nothing.*
|
|
10
|
+
4. **Clean Code — names carry WHAT, comments explain WHY** — Identifiers must make intent obvious; replace comments that merely narrate executable code with clearer names. Reserve implementation comments for non-obvious WHY (hidden constraint, workaround, surprising invariant). Interface documentation may state caller-visible contracts that names and types cannot express, such as error versus mismatch results or required work for missing inputs; verify those claims against implementations and callers. Delete dead/commented-out code immediately — git history is the archive. *Example — WHAT (rename instead): `// increment counter` above `i++`. WHY (keep): `// retry up to 3x: upstream returns 502 during deploys`.*
|
|
11
11
|
5. **Function length cap — 50 lines** — A single function/method body must stay within 50 lines, counting only effective code (exclude blank lines, comments, and pure data declarations such as large enums, lookup tables, or constant maps). Crossing the cap is an extraction signal, not a style nit. *Self-check: for any function newly added or substantially edited, count effective body lines; if over 50, split before declaring complete, or surface the violation and confirm with the user.*
|
|
12
12
|
6. **Simplest conforming approach** — When choosing how to implement or fix something, pick the simplest, most direct solution path that still conforms to the project's architecture and established conventions. This is broader than KISS (#2): KISS bounds abstraction; this bounds the whole approach. Simplicity never licenses bending the structure or a convention — rule out non-conforming paths first, then take the plainest of what remains. Self-check: name the architecture/convention boundary the chosen approach respects; if a simpler path respects it too, take that one.
|
|
13
13
|
7. **Fix at the cause, inside the change set** — An error surfacing during your work is fixed in the code that produced it — the files you are changing and the modules they directly call. A build/deploy/test failure is NOT a license to edit configuration or manifest files (`package.json`, lockfiles, `tsconfig`, CI config, build scripts) that were already passing before this change; a regression in something previously green almost always lives in the new code, not in long-stable config. If a config/manifest edit looks unavoidable, stop and confirm with the user first — state which file, why the current code can't carry the fix, and what was passing before. *Self-check: every file edited to resolve the error is in the current change set or a module it directly calls; no previously-passing config/manifest was touched to silence the failure without the user's explicit sign-off.* *Example violation: tests fail to import a new module, so you loosen `package.json`/`tsconfig` paths instead of fixing the import in the code you just wrote.*
|
|
@@ -50,10 +50,10 @@ If no Stage 1 language rule matches (an unlisted language), stop and ask the use
|
|
|
50
50
|
- [ ] Language reference read for this turn.
|
|
51
51
|
- [ ] `clean-code.md` principles applied: DRY, KISS, SOLID, YAGNI, meaningful naming (truthful + standalone + one identifier one meaning per file), single-purpose functions, plain-English summary test, 50-line cap, no magic numbers, shallow nesting, comments-explain-why.
|
|
52
52
|
- [ ] **Mutation and state boundaries** (`clean-code.md`): decide on the direct identifier, not a status/flag proxy; capture before-state in one snapshot ahead of the mutating boundary; update only this work's owned fields on an existing row; re-read state before calling a zero-affected-rows write success or failure; put priority-between-inputs in a named domain function; keep error messages to what was observed.
|
|
53
|
-
- [ ] **Untrusted input and security** (`clean-code.md`), for every file that reads input from outside the process: a size/count bound rejects oversized input before any check or step that grows faster than the input; input reaches SQL, shell, paths, server-side fetches, templates and regexes only through parameters, allowlists or escaping;
|
|
54
|
-
- [ ] Tests planned: which test(s) cover this change. New behaviour without a test is **incomplete** unless the user has explicitly opted out for this change.
|
|
53
|
+
- [ ] **Untrusted input and security** (`clean-code.md`), for every file that reads input from outside the process or acts on its behalf: a size/count bound rejects oversized input before any check or step that grows faster than the input; input reaches SQL, shell, paths, server-side fetches, templates and regexes only through parameters, allowlists or escaping; new entry points enforce the project's operation-specific access policy, including shared, administrative, and explicitly public access where applicable; protect secrets and limit personal-data disclosure as specified in `clean-code.md`, including authorized data responses and credential issuance; no eval or unsafe deserialization of input.
|
|
54
|
+
- [ ] Tests planned: which test(s) cover this change. New behaviour without a test is **incomplete** unless the user has explicitly opted out for this change and project rules permit it. Record the exact waived behavior or check and its unverified coverage. That waiver applies to the corresponding branch-test, branch-deletion, and resource-bound checks in this pack; it does not waive unrelated checks, weaken existing tests, or establish verified coverage.
|
|
55
55
|
- [ ] **Existing tests surveyed (run this before planning any new test):** for every surface this change touches, `grep -rln` the candidate test files, list their test names, then READ the bodies of the ones that could overlap. A list of names does not tell you what a test asserts, and behavioural overlap does not collide on names — treat a clean name search as unfinished, not as a clear result. Record per surface: `extend <path:line>` / `new (nothing covers <behaviour>)` / `retire <path:line> (behaviour moved to <where>)`. A new test or test file with no survey line is unfinished work. The survey may change the design — moving the seam so existing tests keep passing beats adding parallel ones. Carry out a `retire` verdict in the same commit, on behavioural grounds only: the behaviour it asserted is gone, or a new test asserts it more strongly through the same seam. "Looks similar" / "touches the same file" is not grounds; without grounds the test stays, because a silent coverage loss costs more than one extra test.
|
|
56
|
-
- [ ] **Testing discipline:** the test does not stub/spy methods on the SUT itself (collaborators are fine), and assertions are on outcomes (return values, state, events, boundary calls) — not on which internal helper was called. Each branch this change adds (`catch`, guard, early return, `else`) has a test that fails when the branch body is deleted; assertions land on the last write to a record, not an intermediate one; each test title names its unit and the single condition it isolates; no effect is claimed under its own mock; shared fixtures keep their ordinary defaults; the scenarios' setup values actually differ; every new test helper/mock is used by a test in this same change; no positional mock-argument access (`rg 'mock\.calls'`).
|
|
56
|
+
- [ ] **Testing discipline:** apply the recorded testing waiver only to its stated scope. For tests written or edited, the test does not stub/spy methods on the SUT itself (collaborators are fine), and assertions are on outcomes (return values, state, events, boundary calls) — not on which internal helper was called. Each unwaived branch this change adds (`catch`, guard, early return, `else`) has a test that fails when the branch body is deleted; assertions land on the last write to a record, not an intermediate one; each test title names its unit and the single condition it isolates; no effect is claimed under its own mock; shared fixtures keep their ordinary defaults; the scenarios' setup values actually differ; every new test helper/mock is used by a test in this same change; no positional mock-argument access (`rg 'mock\.calls'`).
|
|
57
57
|
- [ ] **Third-party wrapper (when this change wraps a library call):** the wrapper adds behaviour the library does not already provide — read the installed library source before keeping a recovery branch — no comment names a condition the call site does not establish, and a rethrow keeps the original error as `cause`.
|
|
58
58
|
- [ ] **Hexagonal overlay (if loaded):** no business logic inside any port body, adapter methods are I/O only (no post-fetch JS filtering on domain state, no `findValid*`/`findActive*` adapter names hiding rules), all domain objects declared under `domain/`, no changed domain file importing outward (ORM / framework / adapters / services), and a service dependency you add or modify goes through a port rather than a concrete adapter (advisory — record it with the port sketch; blocking when the project declares `architecture.style = hexagonal` in `.okstra/project.json` — fix before write, never record-and-pass).
|
|
59
59
|
- [ ] **Existing code searched — by capability, not by name:** `grep` the identifier you are about to add AND the behaviour it performs (call sites, domain literals, error strings, the shape of the data it returns). A capability that already exists under a different name is the duplication this check exists to catch, and an identifier grep alone never finds it — name-level uniqueness is not evidence of absence. Record per new unit: the search terms used, the nearest existing implementation found, and the verdict `extend <path:line>` / `new (nothing covers <behaviour>)`. No survey line, no new unit.
|