@deslop/coding-standards 0.1.871 → 0.1.885

package/dist/install.js

@@ -24685,7 +24685,7 @@ const runWith = (command, config) => {
 };
 //#endregion
 //#region package.json
-var version = "0.1.871";
+var version = "0.1.885";
 //#endregion
 //#region src/install.ts
 const cli = pipe(make("deslop-coding-standards", {}, fnUntraced(function* () {

package/dist/oxlint.d.ts

@@ -4020,8 +4020,10 @@ export declare const oxlint: {
       'shadcn/no-restyle'?: undefined;
       'shadcn/require-static-classes'?: undefined;
       '@deslop/coding-standards/no-destructured-parameter'?: undefined;
+      '@deslop/coding-standards/no-native-control'?: undefined;
       '@deslop/coding-standards/no-renamed-import'?: undefined;
       'react/rules-of-hooks'?: undefined;
+      '@deslop/coding-standards/no-discarded-failure'?: undefined;
       'effecttsgo/async-function'?: undefined;
       'typescript/require-await'?: undefined;
       'typescript/strict-void-return'?: undefined;
@@ -4034,8 +4036,10 @@ export declare const oxlint: {
       'shadcn/no-restyle': "off";
       'shadcn/require-static-classes': "off";
       '@deslop/coding-standards/no-destructured-parameter'?: undefined;
+      '@deslop/coding-standards/no-native-control'?: undefined;
       '@deslop/coding-standards/no-renamed-import'?: undefined;
       'react/rules-of-hooks'?: undefined;
+      '@deslop/coding-standards/no-discarded-failure'?: undefined;
       'effecttsgo/async-function'?: undefined;
       'typescript/require-await'?: undefined;
       'typescript/strict-void-return'?: undefined;
@@ -4048,8 +4052,10 @@ export declare const oxlint: {
       'shadcn/no-restyle'?: undefined;
       'shadcn/require-static-classes'?: undefined;
       '@deslop/coding-standards/no-destructured-parameter': "off";
+      '@deslop/coding-standards/no-native-control': "off";
       '@deslop/coding-standards/no-renamed-import': "off";
       'react/rules-of-hooks'?: undefined;
+      '@deslop/coding-standards/no-discarded-failure'?: undefined;
       'effecttsgo/async-function'?: undefined;
       'typescript/require-await'?: undefined;
       'typescript/strict-void-return'?: undefined;
@@ -4062,8 +4068,10 @@ export declare const oxlint: {
       'shadcn/no-restyle'?: undefined;
       'shadcn/require-static-classes'?: undefined;
       '@deslop/coding-standards/no-destructured-parameter'?: undefined;
+      '@deslop/coding-standards/no-native-control'?: undefined;
       '@deslop/coding-standards/no-renamed-import'?: undefined;
       'react/rules-of-hooks': "off";
+      '@deslop/coding-standards/no-discarded-failure'?: undefined;
       'effecttsgo/async-function'?: undefined;
       'typescript/require-await'?: undefined;
       'typescript/strict-void-return'?: undefined;
@@ -4076,8 +4084,26 @@ export declare const oxlint: {
       'shadcn/no-restyle'?: undefined;
       'shadcn/require-static-classes'?: undefined;
       '@deslop/coding-standards/no-destructured-parameter'?: undefined;
+      '@deslop/coding-standards/no-native-control'?: undefined;
       '@deslop/coding-standards/no-renamed-import'?: undefined;
       'react/rules-of-hooks'?: undefined;
+      '@deslop/coding-standards/no-discarded-failure': "off";
+      'effecttsgo/async-function'?: undefined;
+      'typescript/require-await'?: undefined;
+      'typescript/strict-void-return'?: undefined;
+      'unicorn/no-null'?: undefined;
+    };
+  } | {
+    files: string[];
+    rules: {
+      'import/no-default-export'?: undefined;
+      'shadcn/no-restyle'?: undefined;
+      'shadcn/require-static-classes'?: undefined;
+      '@deslop/coding-standards/no-destructured-parameter'?: undefined;
+      '@deslop/coding-standards/no-native-control'?: undefined;
+      '@deslop/coding-standards/no-renamed-import'?: undefined;
+      'react/rules-of-hooks'?: undefined;
+      '@deslop/coding-standards/no-discarded-failure'?: undefined;
       'effecttsgo/async-function': "off";
       'typescript/require-await': "error";
       'typescript/strict-void-return': "off";
@@ -4090,12 +4116,14 @@ export declare const oxlint: {
     '@deslop/coding-standards/no-constant-function': "error";
     '@deslop/coding-standards/no-deep-pipe': "error";
     '@deslop/coding-standards/no-destructured-parameter': "error";
+    '@deslop/coding-standards/no-discarded-failure': "error";
     '@deslop/coding-standards/no-double-nullish-check': "error";
     '@deslop/coding-standards/no-effect-property-arrow': "error";
     '@deslop/coding-standards/no-error-message-assertion': "error";
     '@deslop/coding-standards/no-fake-ref-state': "error";
     '@deslop/coding-standards/no-hand-written-guard': "error";
     '@deslop/coding-standards/no-let': "error";
+    '@deslop/coding-standards/no-native-control': "error";
     '@deslop/coding-standards/no-native-emptiness-check': "error";
     '@deslop/coding-standards/no-native-method-call': "error";
     '@deslop/coding-standards/no-nullish-ternary': "error";
@@ -4308,11 +4336,15 @@ export declare const oxlint: {
     }];
     'import/no-relative-parent-imports': "error";
     'no-restricted-imports': ["error", {
-      paths: {
+      paths: ({
         importNames: string[];
         message: string;
         name: string;
-      }[];
+      } | {
+        importNames?: undefined;
+        message: string;
+        name: string;
+      })[];
       patterns: {
         message: string;
         regex: string;

package/dist/oxlint.js

@@ -1021,6 +1021,27 @@ const noDestructuredParameter = defineRule({
 	meta: { type: "problem" }
 });
 //#endregion
+//#region src/rules/no-discarded-failure.ts
+const noDiscardedFailure = defineRule({
+	create: (context) => ({ MemberExpression: (node) => {
+		if (!importedMember({
+			context,
+			importedName: "Effect",
+			node
+		})) return;
+		if (!exists(memberName(node), (name) => contains$1([
+			"ignore",
+			"orDie",
+			"orDieWith"
+		], name))) return;
+		context.report({
+			message: "Map the failure to the service's error; an expected failure is never ignored or turned into a defect.",
+			node
+		});
+	} }),
+	meta: { type: "problem" }
+});
+//#endregion
 //#region src/rules/no-double-nullish-check.ts
 function nullishOperand(node) {
 	if (node.type === "Literal" && node.value === null) return some("null");
@@ -1284,6 +1305,30 @@ const noLet = defineRule({
 	meta: { type: "problem" }
 });
 //#endregion
+//#region src/rules/no-native-control.ts
+const primitives = {
+	button: "Button",
+	input: "Input",
+	select: "Select",
+	textarea: "Textarea"
+};
+const controlStyle = /(?:^|:)(?:hover|focus|focus-visible|active):|(?:^|:)(?:rounded|shadow|ring)(?:-|$)|(?:^|:)p[blrtxy]?-(?!0$)|(?:^|:)bg-(?!transparent$)|(?:^|:)border(?:-[blrtxy])?$|(?:^|:)border-(?!0$|[blrtxy]-0$)/u;
+const noNativeControl = defineRule({
+	create: (context) => ({ JSXOpeningElement: (node) => {
+		if (node.name.type !== "JSXIdentifier") return;
+		const name = node.name.name;
+		map(get$2(primitives, name), (primitive) => {
+			const styled = pipe(node.attributes, findFirst((attribute) => attribute.type === "JSXAttribute" && attribute.name.type === "JSXIdentifier" && attribute.name.name === "className"), flatMap((attribute) => attribute.type === "JSXAttribute" && attribute.value?.type === "Literal" ? fromNullishOr(attribute.value.value) : none()), exists((value) => some$1(split(value, /\s+/u), matches(controlStyle))));
+			if (name !== "select" && !styled) return;
+			context.report({
+				message: `Use the ${primitive} UI primitive instead of a styled native control.`,
+				node
+			});
+		});
+	} }),
+	meta: { type: "problem" }
+});
+//#endregion
 //#region src/rules/no-native-emptiness-check.ts
 function emptinessPredicate(node) {
 	const comparesLength = node.left.type === "MemberExpression" && contains(memberName(node.left), "length") && node.right.type === "Literal" && node.right.value === 0;
@@ -2477,6 +2522,7 @@ const oxlint = defineConfig({
 			files: ["**/components/ui/**", "**/packages/ui/**"],
 			rules: {
 				"@deslop/coding-standards/no-destructured-parameter": "off",
+				"@deslop/coding-standards/no-native-control": "off",
 				"@deslop/coding-standards/no-renamed-import": "off"
 			}
 		},
@@ -2484,6 +2530,10 @@ const oxlint = defineConfig({
 			files: ["**/*.ts"],
 			rules: { "react/rules-of-hooks": "off" }
 		},
+		{
+			files: ["**/*.test.ts", "**/*.test.tsx"],
+			rules: { "@deslop/coding-standards/no-discarded-failure": "off" }
+		},
 		{
 			files: ["**/*.tsx"],
 			rules: {
@@ -2508,12 +2558,14 @@ const oxlint = defineConfig({
 		"@deslop/coding-standards/no-constant-function": "error",
 		"@deslop/coding-standards/no-deep-pipe": "error",
 		"@deslop/coding-standards/no-destructured-parameter": "error",
+		"@deslop/coding-standards/no-discarded-failure": "error",
 		"@deslop/coding-standards/no-double-nullish-check": "error",
 		"@deslop/coding-standards/no-effect-property-arrow": "error",
 		"@deslop/coding-standards/no-error-message-assertion": "error",
 		"@deslop/coding-standards/no-fake-ref-state": "error",
 		"@deslop/coding-standards/no-hand-written-guard": "error",
 		"@deslop/coding-standards/no-let": "error",
+		"@deslop/coding-standards/no-native-control": "error",
 		"@deslop/coding-standards/no-native-emptiness-check": "error",
 		"@deslop/coding-standards/no-native-method-call": "error",
 		"@deslop/coding-standards/no-nullish-ternary": "error",
@@ -2730,6 +2782,10 @@ const oxlint = defineConfig({
 					message: reactLegacyMessage,
 					name: "react"
 				},
+				{
+					message: "Read and write data through Effect Atom.",
+					name: "@tanstack/react-query"
+				},
 				{
 					importNames: ["vi"],
 					message: "A Layer is the seam; never use vi.",
@@ -3206,12 +3262,14 @@ var oxlint_default = definePlugin({
 		"no-constant-function": noConstantFunction,
 		"no-deep-pipe": noDeepPipe,
 		"no-destructured-parameter": noDestructuredParameter,
+		"no-discarded-failure": noDiscardedFailure,
 		"no-double-nullish-check": noDoubleNullishCheck,
 		"no-effect-property-arrow": noEffectPropertyArrow,
 		"no-error-message-assertion": noErrorMessageAssertion,
 		"no-fake-ref-state": noFakeRefState,
 		"no-hand-written-guard": noHandWrittenGuard,
 		"no-let": noLet,
+		"no-native-control": noNativeControl,
 		"no-native-emptiness-check": noNativeEmptinessCheck,
 		"no-native-method-call": noNativeMethodCall,
 		"no-nullish-ternary": noNullishTernary,

package/package.json

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

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/test code, including prototypes.'
 ---
 
-**Scope.** Apply these rules and repository-specific CODING_STANDARDS.md.
+**Scope.** Apply these rules and repository-specific CODING_STANDARDS.md. Write each line right the first time: the examples exist so lint and review find nothing, and lint is only the fallback.
 
 **Dependency APIs.** Match the manifest and lockfile versions. Before adding an API wrapper or workaround, read the upstream source per workflow's research procedure. Library APIs do not define coding policy.
 
@@ -16,16 +16,16 @@ description: 'TypeScript and Effect code conventions paired with shared lint. Us
 **Experiments.** Write with these idioms; reserve the full refactor/cleanup pass for retained delivery. Keep disposable source isolated and shared rules intact.
 
 - **Reuse first.** Check existing code, installed modules and platform capabilities before adding code. Implement only the missing behavior, without dropping required behavior, safety or accessibility. Workflow owns the scope. A refactor or cleanup request applies every rule to every line of the owned files.
-- **Inward layers.** Domain and service code never import HTTP, RPC, or other transport types.
+- **Inward layers.** Domain and service code never import HTTP, RPC, or other transport types, and domain schemas carry no transport annotation such as an HTTP status.
 - **Building blocks.** For a consequential new interface, start with a realistic caller operation and its ordering, failure and lifetime obligations; hide useful complexity, not forwarded names. Offer services, Layers and functions the caller composes like any Effect module, never a bundle such as `serve(app)`. No mandatory architecture document or alternatives round.
 - **No machinery.** Add hooks, guards or generators only for a required contract or a recurring defect.
-- **Behavior kept.** A refactor keeps observable behavior at every consumer. Report two accepted differences with the change: one no consumer observes, and one a rule here causes, such as an error keeping its cause. Printed diagnostics are not a contract. Any other behavior change follows workflow's scope.
+- **Behavior kept.** A refactor keeps observable behavior at every consumer. Report accepted differences only when they exist: a change no consumer observes, or one a rule here causes, such as an error keeping its cause. Printed diagnostics are not a contract. Any other behavior change follows workflow's scope.
 - **Reachable bugs.** Fix a bug that real input reaches when it lies inside workflow's scope, and check every consumer of the changed output. For a hard bug, use one reproduction and one prediction per probe. Remove edits based on disproven hypotheses, then rerun the original scenario. Delete handling only for input the contract excludes; keep and report code that looks intentional.
-- **Performance.** Optimize only when the request or a required contract needs it, and measure realistic input before claiming a speedup. Diagnose at the layer that owns the symptom: distributed spans for RPC/backend dependencies, React commits for rerenders, a browser performance profile for main-thread work. Correlate one real action before changing code, then repeat it on the fix; neither a screenshot nor a service name proves latency or trace coverage. Time correct completed work under equivalent workloads/configuration; distinguish setup/cache/profiling cost and report run count/variation. Differences within noise are unproved, not speedups. Use existing instrumentation; profiling is not a ritual on every change.
+- **Performance.** Optimize only when the request or a required contract needs it. Measure one real action on realistic input before and after the change, at the layer that owns the symptom: spans for backend calls, React commits for rerenders, a browser profile for main-thread work. Report run count and variation; a difference within noise is unproved.
 - **Type safety.** A fix never weakens types to make a symptom go away: no widened or erased type, cast, dropped generic, or loosened exported type.
 - **Domain.** Implement the definition the domain uses, such as a cycle for recursion, never the nearest syntactic proxy.
 
-**Happy path.** Failures flow through the error channel: no catch, retry, fallback, backup, or defensive check unless the request or an existing contract needs it.
+**Happy path.** Failures flow through the error channel: no catch, retry, fallback, backup, or defensive check unless the request or an existing contract needs it. Map an expected failure to the service's error; never `Effect.ignore` it or turn it into a defect with `Effect.orDie`.
 
 **Trusted data.** Validate and transform once at the boundary with Effect Schema. Carry narrowed values forward. Never re-check what the schema, the declared type, an earlier filter or every caller guarantees.
 
@@ -72,7 +72,7 @@ _input => onSubmit(_input.value) // or input2: an outer input is shadowed
 
 **Nearest sibling.** Extend the nearest implementation; match permissions, errors, refresh and tests. Reuse its helpers and change only affected state.
 
-**Once.** Extract repeated logic once; one fact has one owner.
+**Once.** Extract repeated logic once; one fact has one owner. A domain enum, such as a status, has one schema that every other schema reuses, and a cache key or atom family key carries the full identity of what it caches.
 
 ```ts
 // good
@@ -96,7 +96,7 @@ pipe(
 
 **Present needs.** No speculative option, abstraction, layer, export, file or check. Configure only what callers vary.
 
-**Dead code.** Every superseded or unused file, export, type, branch, config, validation, doc, test, and dependency goes in the same change.
+**Dead code.** Every superseded or unused file, export, type, branch, config, validation, doc, test, and dependency goes in the same change. Docs, guides and generated bundles that describe changed behavior change in the same commit.
 
 ## Lint pairs
 
@@ -149,22 +149,7 @@ Array.appendAll(
 )
 ```
 
-**Choices.** `Match` for a union, never `switch`.
-
-```ts
-// good
-pipe(
-	Match.value(usage.kind),
-	Match.when('input', () => 'in'),
-	Match.when('output', () => 'out'),
-	Match.exhaustive
-)
-// bad
-switch (usage.kind) {
-	case 'input':
-		return 'in'
-}
-```
+**Choices.** `Match` with `Match.exhaustive` for a union, never `switch`.
 
 **Options.** Use Option operators, never .value. Use Option where it composes; keep plain optional values otherwise. This is our convention, not a claim narrowing is unsafe.
 
@@ -187,7 +172,9 @@ const parsed = Option.getOrUndefined(Number.parse(event.target.value))
 // good
 const total = Array.reduce(values, 0, Number.sum)
 pipe(teamId, String.split(','), Array.map(String.trim), Array.findFirst(String.isNonEmpty))
-Array.filterMap(items, item => (supports(item) ? Result.succeed(item.value) : Result.failVoid))
+Array.filterMap(items, item =>
+	Boolean.match(supports(item), {onFalse: () => Result.failVoid, onTrue: () => Result.succeed(item.value)})
+)
 // bad
 let total = 0
 for (const value of values) total += value
@@ -399,7 +386,7 @@ 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; a Promise an external contract demands is bridged once, where it is returned.
+**Runtime.** The owned runtime runs the program; a Promise an external contract demands is bridged once, where it is returned. React code is no such contract: atoms run its Effects.
 
 ```ts
 // good
@@ -559,7 +546,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 shared logic in atoms.
+**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.
 
 ```tsx
 // good
@@ -571,6 +558,41 @@ const handle = useCallback(() => setOpen(true), [])
 const state = useState(false)
 ```
 
+**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`.
+
+```tsx
+// good
+const appsRuntime = Atom.runtime(DualApps.layer)
+const appAtom = Atom.family((id: AppId) => pipe(appsRuntime.atom(loadApp(id)), Atom.withReactivity(['apps'])))
+const saveAppAtom = appsRuntime.fn((draft: AppDraft) => saveApp(draft), {reactivityKeys: ['apps']})
+const app = useAtomValue(appAtom(appId))
+const [saveResult, save] = useAtom(saveAppAtom)
+// bad
+useQuery({queryFn: () => Effect.runPromiseWith(Context.empty())(loadApp(appId))})
+onClick={() => Effect.runPromise(saveApp(draft))}
+useAtomValue(Atom.make(loadApp(appId))) // a new atom on every render
+```
+
+**Outcomes.** Read data with `useAtomSuspense`. The route or section that owns a screen wraps it in one `Suspense` boundary for loading and one error boundary that shows the failure with a retry. Components never branch on loading or failure, and never turn a failure into an empty value. Take a write's pending and failure state from its atom's result, never from copied React state.
+
+```tsx
+// good
+function AppFrame(props: {appId: AppId}) {
+	return <Frame app={useAtomSuspense(appAtom(props.appId)).value} />
+}
+<ErrorBoundary fallback={<LoadError onRetry={refresh} />}>
+	<Suspense fallback={<Spinner />}>
+		<AppFrame appId={appId} />
+	</Suspense>
+</ErrorBoundary>
+<Button disabled={saveResult.waiting} onClick={() => save(draft)}>Save</Button>
+// bad
+app.data ? <AppFrame app={app.data} /> : <Spinner /> // a failed load spins forever
+const members = query.data ?? [] // a failed load looks like no members
+const [pending, setPending] = useState(false) // copies the write atom's waiting state
+```
+
+- **Ownership.** Give a component that owns its own atoms, writes or lifetime its own file; keep small presentational helpers beside their one user. Reset an editable draft through a `key` on its identity, never an Effect that copies props.
 - **Pure render.** Derive display values from props and subscribed state during render; never mutate them or perform an RPC, write or subscription there. Event handlers own user-triggered actions; Effects synchronize external systems, not copied state or calculations. Reuse the existing router/atom integration rather than fetching in a new Effect.
 - **State identity.** Keep one owner for each value, stable domain keys for list items and deliberate reset boundaries. For an observed rerender problem, derive the needed value in the existing atom graph instead of subscribing to frequently changing unrelated state. Compiler memoization is a performance optimization, never a correctness or lifetime guarantee. Do not add manual memoization, compiler escape directives or weakened hook rules to hide an ownership problem.
 

package/skills/testing/SKILL.md

@@ -20,7 +20,7 @@ description: 'Select and run black-box behavior proof for Effect apps/tools. Use
 ```ts
 // good — "test files only for the services/packages public interfaces"
 it.layer(Layer.provideMerge(Ledger.layer, NodeServices.layer))(test => {
-	test.effect('keeps the previous entries when the file is malformed', () => run(program))
+	test.effect('keeps the previous entries when the file is malformed', () => program)
 })
 assert.deepStrictEqual(customCodes(result.stdout), ['@deslop/coding-standards(no-typeof)'])
 assert.containsSubset(error, {_tag: 'SandboxUnavailable', cause: killed})