@deslop/coding-standards 0.1.1076 → 0.1.1079

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deslop/coding-standards",
-  "version": "0.1.1076",
+  "version": "0.1.1079",
   "repository": {
     "type": "git",
     "url": "https://github.com/MP281X/deslop",

package/skills/architecture/SKILL.md

@@ -19,7 +19,7 @@ Before code, settle these facts in the current plan, without creating another do
 - The boundary where untrusted input becomes trusted data.
 - What remains durable after interruption, and how the caller knows.
 
-For a user-visible direction that remains open, decide it with the user before implementation; use orchestrator when available. Settle technical mechanisms with source, a disposable inline probe or a small executable prototype. Do not ask the user to choose between implementation details that evidence can rank.
+For a user-visible direction that remains open, decide it with the user before implementation; use orchestrator when available. File layout, module boundaries, public interfaces and names are the user's taste: when the Patterns and Taste sections of `CODING_STANDARDS.md` do not settle them, show the shape before code, per orchestrator's Taste gate when available. Settle technical mechanisms with source, a disposable inline probe or a small executable prototype. Do not ask the user to choose between implementation details that evidence can rank.
 
 ## Choose the smallest mechanism
 

package/skills/design/SKILL.md

@@ -13,11 +13,11 @@ Follow the engineering skill and the repository's `CODING_STANDARDS.md` when pre
 
 ## Before the first draft
 
-For an open direction, show a question-sized prototype before polishing it. Use orchestrator when available to settle consequential user choices. Approval is provisional: let the user try a small real journey before expensive expansion. Own routine refinement, but expect the real experience to change the user's direction.
+For a screen that the recorded taste does not settle, agree on a realistic mock with the user before product code. Use orchestrator's Taste gate when available. Approval is provisional: let the user try a small real journey before expensive expansion. Own routine refinement, but expect the real experience to change the user's direction.
 
 1. **Task and feeling.** Name the person, their task, their context and the feeling the product gives, such as calm, fast or trustworthy. Name three qualities the person notices, each with what "excellent" looks like.
 2. **Baseline.** Name the category and platform, and the reference screen for each screen you build: in product mode the canonical screen per engineering's Patterns, otherwise one of Apple's apps on iOS or a reference the user named. Capture the reference in the states you need. Start from the system or established component defaults.
-3. **Range.** Compare structurally different solutions only when the structure has a real unresolved fork, on the same data. Include a simpler solution that removes unnecessary controls. Show the smallest comparison that decides the fork, then develop the chosen direction.
+3. **Range.** When the reference screen and the Taste section of `CODING_STANDARDS.md` do not settle the structure, compare 2–3 structurally different solutions on the same data. Include a simpler solution that removes unnecessary controls. Develop only the chosen direction.
 4. **States.** List every screen, its reachable states (empty, loading, partial, error, success, long content) and the events between them, before any code. Group states by concern instead of multiplying every combination.
 5. **Settled choices.** Carry forward what the user approved and what he removed. Never re-add a removed element, rename a visible term or change an approved detail without a request.
 
@@ -98,9 +98,9 @@ For an open direction, show a question-sized prototype before polishing it. Use
 
 ## Prototype and tune
 
-**Variants.** For a real unresolved choice, show one representative journey or a small comparison on the same realistic data before product code. Use the app's tokens, components, copy and behavior. Add interaction only when manipulating the subject exposes a consequential difference; never add tabs or a state dashboard merely to navigate the explanation. Get the direction approved before expanding its states and polish. For a native app the render settles structure and flow; settle its native appearance in simulator captures.
+**Mocks.** Start the mock from the real screen: copy its rendered markup, theme tokens and fonts from the running app or its source, then change only what the decision needs. Keep its components, copy, spacing, realistic data and main states. For a native app, imitate the platform's system look; the mock settles structure, flow and the rough look. Add interaction only when manipulating the subject exposes a consequential difference; never add tabs or a state dashboard merely to navigate the explanation. Revise the mock until the user accepts the direction, then expand states and polish in code.
 
-**Real host.** For a consequential behavior or taste choice, build one complete representative journey with realistic data in the real host: the browser preview for the web, the simulator for a native app. Let the user try it before broader implementation and polish. Complete specified fixes and approved-pattern work with focused proof, without a user checkpoint. Carry unaffected choices forward when feedback changes the journey; revise the affected design instead of defending prototype approval. An HTML imitation of a native screen misleads.
+**Real host.** After the mock, build one complete representative journey with realistic data in the real host: the browser preview for the web, the simulator for a native app. Settle the final native appearance there. Let the user try it before broader implementation and polish. Complete specified fixes and approved-pattern work with focused proof, without a user checkpoint. Carry unaffected choices forward when feedback changes the journey; revise the affected design instead of defending the approved mock.
 
 **Tune.** Settle values yourself. For values you cannot settle by reasoning, such as spacing, timing, springs or blur, capture candidates side by side, including both extremes, and judge them against the reference. Write the chosen values into the source and recapture.
 

package/skills/engineering/SKILL.md

@@ -3,7 +3,7 @@ name: engineering
 description: 'TypeScript and Effect code conventions paired with shared lint. Use when designing, implementing or reviewing product and test code, including prototypes.'
 ---
 
-**Scope.** Apply these rules and the repository's `CODING_STANDARDS.md` when present. Aim for a structurally correct first pass with few lint errors, not a promise of zero diagnostics. Oxlint remains the authoritative check; instructions do not replace it. Oxfmt owns whitespace, indentation and other mechanical formatting. Use automatic formatting and available fixes instead of spending reasoning on those details; fix remaining structural diagnostics at their source without a full rewrite or weakened rules. A refactor or cleanup request applies every rule to every line of the owned files. Scratch code outside the repository follows no style rule. Create a missing standards file only to hold a [Patterns](#patterns) row.
+**Scope.** Apply these rules and the repository's `CODING_STANDARDS.md` when present. Aim for a structurally correct first pass with few lint errors, not a promise of zero diagnostics. Oxlint remains the authoritative check; instructions do not replace it. Oxfmt owns whitespace, indentation and other mechanical formatting. Use automatic formatting and available fixes instead of spending reasoning on those details; fix remaining structural diagnostics at their source without a full rewrite or weakened rules. A refactor or cleanup request applies every rule to every line of the owned files. Scratch code outside the repository follows no style rule. Create a missing standards file only to hold a [Patterns](#patterns) or Taste row.
 
 **Before checking.** Run Oxfmt and the repository's deterministic lint autofix before manual code analysis, independent review or a check-only lint pass. Use the owned scope and preserve unrelated changes. Run both even when generated code looks correct; automatic fixes need no model iteration. Analyze the remaining diagnostics and behavior only after normalization. For a read-only review, the author prepares the normalized diff; the reviewer never writes the reviewed checkout.
 
@@ -112,6 +112,8 @@ Keep the repository consistent by default, without a reminder, and change a stan
 
 **Register.** When a task settles a shape that two or more consumers share and the Patterns section has no row for it, add one: the pattern, its owner and canonical example, a search that lists its consumers, and what enforces it.
 
+**Taste.** Read the Taste section of `CODING_STANDARDS.md` before choosing a layout, file organization, interface or name, and follow its rows like Patterns rows. When the user picks a variant, rejects one or corrects a taste choice that no rule covers, add a row in the same change: the area, the choice, the rejected alternative and his reason in his words. A row that recurs across repositories moves into the owning skill.
+
 **Pattern change.** A user change to a pattern, style, name or convention changes the repository standard, unless he limits its scope. In the same change, update its owner: the shared component, template, generator, lint rule and Patterns row. List every consumer with the row's search, migrate each one, delete the superseded variant and its exemptions, then run the search for the old form again. Report each consumer kept on purpose with its reason. A migration that crosses another repository or a published contract needs the user's approval first.
 
 **Enforce.** When the same correction happens twice, make the mistake impossible at the highest level that works: an owner component, export or type that removes the wrong form, then a lint rule whose message names the replacement, then a test. Keep a prose rule only for a judgment that no check can make. Prove a new check against the real past mistake and an accepted control.
@@ -134,13 +136,13 @@ const root = options?.root !== undefined ? options.root : '.'
 ```tsx
 // good
 if (enabled) return
-aria-current={props.selected === true ? 'page' : undefined}
+aria-current={Boolean.match(props.selected === true, {onFalse: () => undefined, onTrue: () => 'page'})}
 // bad
 if (enabled === true) return // enabled is a boolean
 if (props.selected) return // props.selected can be undefined
 ```
 
-**Flat.** Use early-return statements in Effect.fn. No nested ternaries or combinators deeper than equivalent statements. Match and combinators serve single expressions; Boolean.match selects a value, except one-line JSX-attribute ternaries.
+**Flat.** Use early-return statements in Effect.fn. No ternaries, in JSX too, and no combinators deeper than equivalent statements. An early return, `Boolean.match`, `Option.match`, `Array.match`, `Match` or a lookup record selects a value.
 
 ```ts
 // good
@@ -153,6 +155,7 @@ Boolean.match(ignoreCase, {onFalse: () => undefined, onTrue: () => 'i'})
 // bad
 const type = event.type === 'text-delta' ? 'text' : event.type === 'reasoning-delta' ? 'reasoning' : 'unknown'
 const flags = ignoreCase ? 'i' : undefined // "instead of a ternary the Boolean.match would be cleaner"
+{props.children ? props.children(entry) : <Label entry={entry} />} // "the ternaries are impossible to read"
 // bad
 Array.appendAll(
 	base,
@@ -180,6 +183,17 @@ if (Option.isSome(open)) open.value.append(event.delta)
 const parsed = Option.getOrUndefined(Number.parse(event.target.value))
 ```
 
+**Absence.** `undefined` marks an absent value. Use `null` only where an outside contract, such as a stored schema or a library callback, demands it, with an inline disable that names the contract.
+
+```ts
+// good
+const last = Option.getOrUndefined(Array.last(sessions))
+// oxlint-disable-next-line no-restricted-properties -- The schema stores a missing link as null.
+url: Option.getOrNull(url)
+// bad
+failed: Option.getOrNull(Option.none()) // "i don't like null, i prefer undefined"
+```
+
 **Handlers.** A handler used once is an arrow in place; a handler used twice is a `function`.
 
 **Accumulators.** No `let`: a fold or an Effect collection operation that says what it selects.
@@ -207,6 +221,7 @@ items.filter(item => supports(item)).map(item => item.value)
 // good
 Number.parse(input.count)
 Predicate.isString(value)
+Predicate.hasProperty(node, 'tagName')
 Predicate.isNotNullish(annotation)
 Array.isReadonlyArrayEmpty(node.arguments)
 String.isNonEmpty(event.delta)
@@ -221,6 +236,7 @@ const serve = Effect.gen(function* () {
 // bad
 parseInt(input.count)
 typeof value === 'string'
+'tagName' in node // "typeof and in shouldn't be allowed, probably this should use effect schema"
 annotation !== null && annotation !== undefined
 node.arguments.length === 0
 Effect.promise(() => new Promise(resolve => setTimeout(resolve, delay)))
@@ -304,11 +320,11 @@ files: ['packages/components-web/src/form.tsx', 'packages/components-web/src/ric
 
 ## Effect
 
-**Functions.** Use Effect.fn('Name.method') for a traced function with arguments and Effect.fnUntraced for an internal helper. Use Effect.gen for an effect with several statements and no arguments, and a single effect directly. Use Effect.fn.Return for an explicit return type.
+**Functions.** Use Effect.fn('Name.method') for a traced function with arguments and Effect.fnUntraced for an internal helper. Use Effect.gen for an effect with several statements and no arguments, and a single effect directly. Use Effect.fn.Return only for a generator that calls itself.
 
 ```ts
 // good
-const prompt = Effect.fn('Ai.prompt')(function* (message: Prompt.UserMessage): Effect.fn.Return<void, AiError> {
+const prompt = Effect.fn('Ai.prompt')(function* (message: Prompt.UserMessage) {
 	const input = yield* piUserMessage(message)
 	yield* send(input)
 })
@@ -403,15 +419,17 @@ const traced = Effect.withSpan('Notes.create')(notes.create(input))
 Effect.addFinalizer(() => closeSocket(socket)) // acquisition and release with different owners
 ```
 
-**Runtime.** The owned runtime runs the program. Bridge to a Promise once, where an external contract demands it. React is no such contract: atoms run its Effects.
+**Runtime.** The entry point runs the program with `NodeRuntime.runMain`. Bridge to a Promise once, where an external contract demands it, with `Effect.runPromise` and an inline disable that names the contract. React is no such contract: atoms run its Effects.
 
 ```ts
 // good
 NodeRuntime.runMain(program)
-health: flow(rpc.health, Effect.runPromiseWith(Context.empty())),
+// oxlint-disable-next-line no-restricted-properties -- Bingo's produce contract demands a Promise.
+produce: flow(generate, Effect.runPromise),
 // bad
 const runtime = ManagedRuntime.make(AppLayer)
 const run = <A, E>(effect: Effect.Effect<A, E>) => Effect.runPromise(effect)
+Effect.runPromiseWith(Context.empty()) // "what's the point of using the runPromiseWith if i pass an empty context?"
 ```
 
 **Sorting.** `Order` for sorting, `Result` for a fallible pure value.
@@ -429,7 +447,7 @@ entries.sort((left, right) => left.tokens - right.tokens)
 
 ## Types and Schema
 
-**Inference.** Infer types. Annotate recursion or branches TypeScript cannot unite; use schema types and indexed members in signatures. Keep intentional widening, not repeated inferred generics.
+**Inference.** Infer types. Annotate a return type only on a type guard, an assertion function, a recursive function or the thunk of a recursive `Schema.suspend`. Check a returned object with `satisfies`, and type an empty or one-element array with `Array.empty<T>()` or `Array.of<T>(...)` instead of its callback. Use schema types and indexed members in signatures. Keep intentional widening, not repeated inferred generics.
 
 ```ts
 // good
@@ -442,8 +460,14 @@ function visit(node: Node): Result {
 function settle(amount: LedgerEntry['amount']) {
 	return BigDecimal.format(amount)
 }
+function still(bytes: Uint8Array) {
+	return {bytes, type: 'image/jpeg'} satisfies Image
+}
 export type Sandbox = ReturnType<typeof fromSdk>
 // bad
+function still(bytes: Uint8Array): Image {
+	return {bytes, type: 'image/jpeg'}
+} // "not a fan of assigning the return type, i would have preferred a satisfies"
 const Input = Schema.Struct({value: Schema.String}) satisfies Schema.Schema<Input>
 const label = MutableRef.make<string>('') // repeats the inferred type
 export type SandboxLike = {id: string; renew: (seconds: number) => Promise<unknown>} // a copy of an inferred shape
@@ -511,7 +535,7 @@ function isPathNotFound(error: unknown) {
 
 ## Shape
 
-**Inline.** Inline forwarding wrappers, temporaries and constants. Keep a helper only for logic that is reused or deserves its own name. Argument-free functions are named values.
+**Inline.** Inline forwarding wrappers, temporaries, constants and property aliases; keep an alias only where a callback needs its narrowed type. Inline a small helper with one caller. A helper that several files share lives in the package's `lib/utils`. Argument-free functions are named values.
 
 ```ts
 // good
@@ -528,6 +552,10 @@ function isBackendRequest(request: IncomingMessage) {
 } // "this is just a wrapper / factory function"
 Ref.set(entries, Array.copy(decoded)) // decoded is already an array
 const runPromise = Effect.runPromiseWith(Context.empty()) // "wrapper function, tmp variable ... that can be inlined"
+const parent = read.parent // "inline the property access since it add no value"
+function isVideo(type: FileType) {
+	return String.startsWith('video/')(type)
+} // String.startsWith('video/') is already the function
 ```
 
 **Linked state.** Linked state moves in one pure updater, never a setter that calls another.
@@ -563,7 +591,7 @@ const warned = ['sort-keys', 'typescript/no-restricted-types'] // a package rule
 
 ## React
 
-**Components.** React Compiler memoizes. Destructure state at its declaration, receive component refs through props, and keep only a component's own interaction state in React.
+**Components.** React Compiler memoizes. Import hooks by name from `react`. Destructure state at its declaration, receive component refs through props, and keep only a component's own interaction state in React.
 
 ```tsx
 // good
@@ -573,6 +601,7 @@ const moveRpc = useAtomSet(RpcClient.mutation('portfolio.move'))
 // bad
 const handle = useCallback(() => setOpen(true), [])
 const state = useState(false)
+const [open, setOpen] = React.useState(false) // "why are you using the React.useState and not importing useState"
 ```
 
 **Atoms.** Data, shared state and every Effect a component needs live in atoms; a component reads them with hooks and never runs an Effect. A task that changes a React Query hook, a fetching Effect or an Effect runner in React code moves that code to an atom. Declare atoms at module level or in `Atom.family`, never during render. Import `Atom` and `AsyncResult` from `effect/reactivity` and the hooks from `@effect/atom-react`. Supply services through `Atom.runtime(layer)`, and build every read and write with that runtime's `atom` and `fn`. Tie each write to the reads it changes with reactivity keys; only a runtime's `fn` honors them, so never pass them to `Atom.fn`.

package/skills/testing/SKILL.md

@@ -42,7 +42,7 @@ assert.strictEqual(Array.flatMap(attioProvider.groups, group => group.actions).l
 - **Branches.** Exercise the reachable distinctions: empty, duplicate, concurrent and dependency failure. Write no Cartesian product, and no random or repeated happy paths without a hypothesis.
 - **Failure.** Use `Effect.flip` for an expected failure and `Effect.exit` for both outcomes. Assert domain identity and preserved state and resources: no partial write, lost value, extra retry or leak. Wording or rejection alone is not enough, and incidental order is no assertion.
 - **Control.** Run the regression test against the unfixed implementation, and confirm that the intended assertion fails, not setup, imports or compilation. Before a refactor, cover the old behavior.
-- **Audit.** Remove duplicate and tautological cases in the touched scope, but retain independent protocol, package, validation, authorization and persistence contracts. Mock call counts do not prove an external boundary. Do not replace a useful test with a disposable script just to reduce the count.
+- **Audit.** Delete a case that no plausible wrong implementation fails, such as an assertion on a constant placeholder. Remove duplicate and tautological cases in the touched scope, but retain independent protocol, package, validation, authorization and persistence contracts. Mock call counts do not prove an external boundary. Do not replace a useful test with a disposable script just to reduce the count.
 
 ## Effect and fixtures