@codelaw/rules-stencil 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Arpit Arya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+SPDX-License-Identifier: MIT

package/NOTICE

@@ -0,0 +1,6 @@
+@codelaw/rules-stencil
+
+The rules are reimplementations written for codelaw. Their `ported_from:`
+fields name the @stencil/eslint-plugin rules (MIT License) whose documented
+behaviour they reproduce; no @stencil/eslint-plugin code or documentation text
+is included.

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @codelaw/rules-stencil
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+codelaw's Stencil rules — one of codelaw's first-party rule packs
+([SR-RULE-PACKS](../../records/0101_rule-packs.md)). It ships on
+npm only, as `@codelaw/rules-stencil`; PyPI has no copy (L6 decision 11).
+
+```toml
+# codelaw.toml
+extends = ["codelaw:js/recommended", "codelaw:stencil/recommended"]
+preview = true   # every rule is `preview` until a corpus run promotes it
+```
+
+## Presets
+
+<!-- docs-sync:presets -->
+
+| preset | rules | ported from |
+|---|---|---|
+| `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.
+
+## How the ports differ
+
+Every rule matches its source's documented behaviour on the source's own
+examples. Where codelaw differs, the rule's `## Differences from the source`
+section says so. The larger ones:
+
+| rule | difference |
+|---|---|
+| `stencil/tag-prefix` | with no `prefix` option set, a tag only needs some prefix |
+| `stencil/prop-readonly` | the starter id for upstream `props-must-be-readonly` |
+
+## Not ported, and why
+
+| rule | why |
+|---|---|
+| `stencil/async-methods`, `stencil/render-returns-host`, `stencil/single-export`, `stencil/strict-boolean-conditions` | need type information |
+| `stencil/element-type` | needs the component's tag mapped to its element type name |
+| `stencil/decorators-style` | layout: the formatter owns it |
+| `stencil/dependency-suggestions` | advisory, with no fixed check to port |

package/codelaw-pack.toml

@@ -0,0 +1,6 @@
+name = "@codelaw/rules-stencil"
+version = "0.2.0"
+min_codelaw = "0.1.0"
+languages = ["typescript", "tsx"]
+presets = ["stencil/recommended", "stencil/conventions"]
+description = "codelaw's Stencil rules, from @stencil/eslint-plugin; npm only (SR-RULE-PACKS)"

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,16 @@
 {
   "name": "@codelaw/rules-stencil",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "codelaw's Stencil rules, from @stencil/eslint-plugin; npm only (SR-RULE-PACKS)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arpitarya/codelaw.git"
+  },
+  "homepage": "https://github.com/arpitarya/codelaw",
+  "keywords": [
+    "codelaw",
+    "codelaw-pack",
+    "lint-rules"
+  ]
+}

package/presets/stencil/conventions.toml

@@ -0,0 +1,4 @@
+description = "House conventions from codelaw's starter catalogue; opt in"
+
+[rules]
+"stencil/tag-prefix" = "error"

package/presets/stencil/recommended.toml

@@ -0,0 +1,20 @@
+description = "@stencil/eslint-plugin 1.4.0 recommended without its type-checked rules, reimplemented"
+
+[rules]
+"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"
+"stencil/own-methods-must-be-private" = "error"
+"stencil/own-props-must-be-private" = "error"
+"stencil/prefer-vdom-listener" = "error"
+"stencil/prop-readonly" = "error"
+"stencil/props-must-be-public" = "error"
+"stencil/required-jsdoc" = "error"
+"stencil/reserved-member-names" = "error"
+"stencil/strict-mutable" = "error"

package/rules/stencil/ban-default-true.md

@@ -0,0 +1,70 @@
+---
+id: stencil/ban-default-true
+title: "A boolean @Prop defaults to false"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "inverting the prop renames it for every user"
+stability: preview
+ported_from: [stencil/ban-default-true]
+since: 0.1.0
+---
+
+A `@Prop()` of a Stencil component doesn't default to `true`.
+
+**Why:** An HTML boolean attribute can only switch something on; a prop that starts `true` can't be
+turned off from markup.
+
+```codelaw
+native: stencil/ban-default-true
+```
+
+## How to fix
+
+1. Invert the prop's meaning so it defaults to `false` (e.g. `closable` → `hideClose`).
+2. Update the component's markup users.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  /** Shows the close button. */
+  @Prop() readonly closable = true;
+}
+```
+
+#### Do
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  /** Hides the close button. */
+  @Prop() readonly hideClose = false;
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  /** Shows the close button. */
+  @Prop() readonly closable = true;
+}
+```
+
+#### Do
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  /** Hides the close button. */
+  @Prop() readonly hideClose = false;
+}
+```

package/rules/stencil/ban-exported-const-enums.md

@@ -0,0 +1,60 @@
+---
+id: stencil/ban-exported-const-enums
+title: "No exported const enums"
+languages: [typescript, tsx]
+fix: auto
+stability: preview
+ported_from: [stencil/ban-exported-const-enums]
+since: 0.1.0
+---
+
+An exported enum is a plain `enum`, not a `const enum`.
+
+**Why:** A `const enum` is erased at compile time, so code that imports it from the built bundle
+finds nothing.
+
+```codelaw
+native: stencil/ban-exported-const-enums
+```
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+export const enum Size {
+  Small,
+  Large,
+}
+```
+
+#### Do
+
+```ts
+export enum Size {
+  Small,
+  Large,
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+export const enum Size {
+  Small,
+  Large,
+}
+```
+
+#### Do
+
+```tsx
+export enum Size {
+  Small,
+  Large,
+}
+```

package/rules/stencil/ban-prefix.md

@@ -0,0 +1,76 @@
+---
+id: stencil/ban-prefix
+title: "A component tag doesn't use a reserved prefix"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "renaming a tag changes every page that uses it"
+stability: preview
+options:
+  prefixes: { type: "string[]", default: ["stencil", "stnl", "st"] }
+ported_from: [stencil/ban-prefix]
+since: 0.1.0
+---
+
+A component's `tag` doesn't start with a prefix Stencil reserves (`stencil-`, `stnl-`, `st-` by
+default; the `prefixes` option changes the list).
+
+**Why:** Reserved prefixes may clash with Stencil's own elements.
+
+```codelaw
+native: stencil/ban-prefix
+```
+
+## How to fix
+
+1. Choose a prefix of your own and rename the tag.
+2. Update every usage of the element.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+@Component({ tag: 'stencil-card' })
+export class Card {
+  render() {
+    return null;
+  }
+}
+```
+
+#### Do
+
+```ts
+@Component({ tag: 'acme-card' })
+export class Card {
+  render() {
+    return null;
+  }
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+@Component({ tag: 'stencil-card' })
+export class Card {
+  render() {
+    return null;
+  }
+}
+```
+
+#### Do
+
+```tsx
+@Component({ tag: 'acme-card' })
+export class Card {
+  render() {
+    return null;
+  }
+}
+```

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/decorators-context.md

@@ -0,0 +1,61 @@
+---
+id: stencil/decorators-context
+title: "Stencil decorators only inside @Component classes"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "whether the class should be a component needs the author"
+stability: preview
+ported_from: [stencil/decorators-context]
+since: 0.1.0
+---
+
+`@Prop`, `@State`, `@Element`, `@Method`, `@Watch`, `@Listen`, `@Event` and `@AttachInternals`
+appear only in a class decorated with `@Component`.
+
+**Why:** Outside a component Stencil ignores them, so the code silently does nothing.
+
+```codelaw
+native: stencil/decorators-context
+```
+
+## How to fix
+
+1. Make the class a `@Component`, or remove the Stencil decorators.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+export class Store {
+  @State() count = 0;
+}
+```
+
+#### Do
+
+```ts
+export class Store {
+  count = 0;
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+export class Store {
+  @State() count = 0;
+}
+```
+
+#### Do
+
+```tsx
+export class Store {
+  count = 0;
+}
+```

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.

package/rules/stencil/host-data-deprecated.md

@@ -0,0 +1,73 @@
+---
+id: stencil/host-data-deprecated
+title: "No hostData()"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "the attributes move into `render()` by hand"
+stability: preview
+ported_from: [stencil/host-data-deprecated]
+since: 0.1.0
+---
+
+A component doesn't define `hostData()`.
+
+**Why:** `hostData()` is deprecated; the host element's attributes are set by rendering `<Host>`.
+
+```codelaw
+native: stencil/host-data-deprecated
+```
+
+## How to fix
+
+1. Render a `<Host>` element in `render()` with the attributes `hostData()` returned.
+2. Remove `hostData()`.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  hostData() {
+    return { class: 'card' };
+  }
+}
+```
+
+#### Do
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  render() {
+    return null;
+  }
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  hostData() {
+    return { class: 'card' };
+  }
+}
+```
+
+#### Do
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  render() {
+    return null;
+  }
+}
+```