@codelaw/rules-stencil 0.1.0 → 0.2.0

package/README.md

@@ -12,11 +12,15 @@ preview = true   # every rule is `preview` until a corpus run promotes it
 
 ## Presets
 
+<!-- docs-sync:presets -->
+
 | preset | rules | ported from |
 |---|---|---|
-| `stencil/recommended` | 15 | @stencil/eslint-plugin 1.4.0 `recommended` — 15 of its 21 rules |
+| `stencil/recommended` | 17 | @stencil/eslint-plugin 1.4.0 `recommended` — 16 of the 23 rules it turns on, and `stencil/prop-readonly` (upstream `props-must-be-readonly`) |
 | `stencil/conventions` | 1 | codelaw's starter catalogue: `stencil/tag-prefix` — opt in |
 
+<!-- /docs-sync:presets -->
+
 Every rule is **reimplemented**, not vendored: the matchers, messages and docs
 are written fresh, and each rule's `ported_from:` names the source rule.
 

package/codelaw-pack.toml

@@ -1,5 +1,5 @@
 name = "@codelaw/rules-stencil"
-version = "0.1.0"
+version = "0.2.0"
 min_codelaw = "0.1.0"
 languages = ["typescript", "tsx"]
 presets = ["stencil/recommended", "stencil/conventions"]

package/corpus.toml

@@ -0,0 +1,22 @@
+# `codelaw test --corpus` finding counts (SR-RULE-AUTHORING decision 4).
+# Rewrite with --update-snapshot, and review the change.
+
+[findings]
+"stencil/ban-default-true" = 39
+"stencil/ban-exported-const-enums" = 0
+"stencil/ban-prefix" = 0
+"stencil/ban-side-effects" = 141
+"stencil/decorators-context" = 0
+"stencil/enforce-slot-jsdoc" = 50
+"stencil/host-data-deprecated" = 0
+"stencil/methods-must-be-public" = 0
+"stencil/no-unused-watch" = 6
+"stencil/own-methods-must-be-private" = 202
+"stencil/own-props-must-be-private" = 224
+"stencil/prefer-vdom-listener" = 12
+"stencil/prop-readonly" = 589
+"stencil/props-must-be-public" = 0
+"stencil/required-jsdoc" = 3
+"stencil/reserved-member-names" = 9
+"stencil/strict-mutable" = 8
+"stencil/tag-prefix" = 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codelaw/rules-stencil",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "codelaw's Stencil rules, from @stencil/eslint-plugin; npm only (SR-RULE-PACKS)",
   "license": "MIT",
   "repository": {

package/presets/stencil/recommended.toml

@@ -4,7 +4,9 @@ description = "@stencil/eslint-plugin 1.4.0 recommended without its type-checked
 "stencil/ban-default-true" = "error"
 "stencil/ban-exported-const-enums" = "error"
 "stencil/ban-prefix" = "error"
+"stencil/ban-side-effects" = "error"
 "stencil/decorators-context" = "error"
+"stencil/enforce-slot-jsdoc" = "error"
 "stencil/host-data-deprecated" = "error"
 "stencil/methods-must-be-public" = "error"
 "stencil/no-unused-watch" = "error"

package/rules/stencil/ban-side-effects.md

@@ -0,0 +1,81 @@
+---
+id: stencil/ban-side-effects
+title: "No calls at a module's top level"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "where the call should run instead — a function, a lifecycle method — needs the author"
+stability: preview
+options:
+  allow: { type: "string[]", default: ["describe", "test", "bind", "createStore"], description: "functions that may be called at the top level; setting it replaces the default list" }
+ported_from: [stencil/ban-side-effects]
+since: 0.2.0
+---
+
+A module makes no calls at its top level: every call sits inside a function, a method or a class, or
+in an `export` declaration. Test files (a name with `spec.`, `e2e.` or `test.` in it) are not
+checked, and `describe`, `test`, `bind` and `createStore` may be called anywhere (the `allow` option
+changes that list).
+
+**Why:** Stencil's compiler loads modules to analyse them and bundles them lazily, so a call that runs
+on import runs at a time no one chose, and may not run at all when a bundle is split.
+
+```codelaw
+native: stencil/ban-side-effects
+```
+
+## How to fix
+
+1. Move the call into the function, method or lifecycle hook (`componentWillLoad`, `connectedCallback`)
+   that needs its effect.
+2. If the call builds a value, export a function that builds it, or keep it in an `export const`.
+3. If the call must run at load time, add the function's name to the `allow` option.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+import { setupConfig } from './config';
+
+setupConfig({ mode: 'md' });
+```
+
+#### Do
+
+```ts
+import { setupConfig } from './config';
+
+export function init() {
+  setupConfig({ mode: 'md' });
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+import { setupConfig } from './config';
+
+setupConfig({ mode: 'md' });
+```
+
+#### Do
+
+```tsx
+import { setupConfig } from './config';
+
+export function init() {
+  setupConfig({ mode: 'md' });
+}
+```
+
+## Differences from the source
+
+- Every function is a boundary: the source treats arrow functions and function declarations as
+  boundaries but reports calls inside a function expression or an object method, which run only
+  when called.
+- The option is named `allow`, not the source's unnamed list.
+- A tagged template and a dynamic `import()` are not calls here, as in the source.

package/rules/stencil/enforce-slot-jsdoc.md

@@ -0,0 +1,68 @@
+---
+id: stencil/enforce-slot-jsdoc
+title: "Every slot a component renders has a @slot tag, and every @slot tag a slot"
+languages: [tsx]
+fix: manual
+fix_reason: "the slot's description, or whether it should exist, needs the author"
+stability: preview
+ported_from: [stencil/enforce-slot-jsdoc]
+since: 0.2.0
+---
+
+A `@Component` class's JSDoc has a `@slot` tag for each `<slot>` it renders — `@slot name - what it
+holds` for a named slot, `@slot - what it holds` for the default one — and no `@slot` tag for a slot
+it doesn't render.
+
+**Why:** Stencil builds the component's documentation and editor hints from these tags, so a missing
+tag hides a slot from its users, and a stale one promises a slot that isn't there.
+
+```codelaw
+native: stencil/enforce-slot-jsdoc
+```
+
+## How to fix
+
+1. For a slot reported as rendered without a tag, add `@slot <name> - <what it holds>` (or
+   `@slot - <what it holds>` for the default slot) to the JSDoc above `@Component`.
+2. For a tag reported as never rendered, remove the tag, or render the `<slot>` it describes.
+
+## Examples
+
+### TSX
+
+#### Don't
+
+```tsx
+/**
+ * A card.
+ */
+@Component({ tag: 'my-card' })
+export class Card {
+  render() {
+    return <slot name="header" />;
+  }
+}
+```
+
+#### Do
+
+```tsx
+/**
+ * A card.
+ * @slot header - The card's title row.
+ */
+@Component({ tag: 'my-card' })
+export class Card {
+  render() {
+    return <slot name="header" />;
+  }
+}
+```
+
+## Differences from the source
+
+- A `<slot>` whose `name` is an expression (`name={this.slot}`) is left out; the source records it as
+  a slot named `undefined`.
+- A `@slot` tag's text stops at the end of its line; the source lets a bare `@slot` take its
+  description from the next line.
+- TSX only: a `.ts` file has no `<slot>` elements to check.