feat(eslint-plugin): add no-scope-get rule

documentation/src/content/docs/learn/linting.mdx

@@ -109,6 +109,46 @@ compose().step(login).step(debug(login)).run()
 compose().step(login).run()
 ```
 
+### no-scope-get
+
+This rule is not enabled in the `recommended` config. Enable it explicitly to keep application work inside the
+composition.
+
+💭 This rule requires [typed linting](https://typescript-eslint.io/getting-started/typed-linting/).
+
+```js
+{
+  rules: {
+    'app-compose/no-scope-get': 'warn',
+  },
+}
+```
+
+<hr />
+
+`scope.get()` can lead to imperative work outside the composition: surrounding code reads a value and decides what
+runs next. Put the work in a Task and pass the values it needs through the Task's `context`.
+
+The plugin reports every call to `scope.get()` on the App-Compose `Scope` type, including values returned by `run()`
+and values received by observers. Other objects with a method named `get` are not reported.
+
+```ts
+// ❌ Wrong
+const scope = await compose().step(login).run()
+renderUser(scope.get(login.result))
+
+// ✅ Correct
+const showUser = createTask({
+  name: "show-user",
+  run: {
+    context: login.result,
+    fn: (user) => renderUser(user),
+  },
+})
+
+await compose().step(login).step(showUser).run()
+```
+
 ### task-options-order
 
 ⚠️ This rule warns in the `recommended` config.

packages/eslint-plugin/README.md

@@ -48,5 +48,6 @@ Or wire the plugin manually:
 | ----------------------------------------------------------------------------------------- | ------------------------------------------------- | --- | --- | --- |
 | [no-async-shape-callback](https://app-compose.dev/learn/linting/#no-async-shape-callback) | Disallow async callbacks in `shape()`             |     | ❗  |     |
 | [no-coda-debug](https://app-compose.dev/learn/linting/#no-coda-debug)                     | Disallow `debug()` calls from `@app-compose/coda` |     | ❗  |     |
+| [no-scope-get](https://app-compose.dev/learn/linting/#no-scope-get)                       | Disallow `scope.get()` calls                      |     |     |     |
 | [task-options-order](https://app-compose.dev/learn/linting/#task-options-order)           | Enforce options order for `createTask`            | ⚠️  |     | 🔧  |
 | [wire-options-order](https://app-compose.dev/learn/linting/#wire-options-order)           | Enforce options order for `createWire`            | ⚠️  |     | 🔧  |

packages/eslint-plugin/src/index.ts

@@ -2,6 +2,7 @@ import type { TSESLint } from "@typescript-eslint/utils"
 import { name, version } from "../package.json"
 import noAsyncShapeCallback from "./rules/no-async-shape-callback/no-async-shape-callback"
 import noCodaDebug from "./rules/no-coda-debug/no-coda-debug"
+import noScopeGet from "./rules/no-scope-get/no-scope-get"
 import taskOptionsOrder from "./rules/task-options-order/task-options-order"
 import wireOptionsOrder from "./rules/wire-options-order/wire-options-order"
 import { ruleset } from "./ruleset"
@@ -11,6 +12,7 @@ const base = {
   rules: {
     "no-async-shape-callback": noAsyncShapeCallback,
     "no-coda-debug": noCodaDebug,
+    "no-scope-get": noScopeGet,
     "task-options-order": taskOptionsOrder,
     "wire-options-order": wireOptionsOrder,
   },

packages/eslint-plugin/src/rules/no-scope-get/no-scope-get.test.ts

@@ -0,0 +1,88 @@
+import { RuleTester } from "@typescript-eslint/rule-tester"
+import { ts } from "@/shared/tag"
+import rule from "./no-scope-get"
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parserOptions: {
+      projectService: {
+        allowDefaultProject: ["*.ts*"],
+      },
+      tsconfigRootDir: import.meta.dirname,
+    },
+  },
+})
+
+ruleTester.run("no-scope-get", rule, {
+  valid: [
+    {
+      name: "unrelated get method",
+      code: ts`
+        const registry = new Map<string, string>()
+        registry.get("value")
+      `,
+    },
+    {
+      name: "unrelated type named Scope",
+      code: ts`
+        type Scope = { get: () => unknown }
+        declare const scope: Scope
+        scope.get()
+      `,
+    },
+    {
+      name: "run without reading the scope",
+      code: ts`
+        import { compose } from "@app-compose/core"
+        await compose().run()
+      `,
+    },
+  ],
+  invalid: [
+    {
+      name: "scope returned by run",
+      code: ts`
+        import { compose, type Spot } from "@app-compose/core"
+        declare const spot: Spot<string>
+
+        const scope = await compose().run()
+        scope.get(spot)
+      `,
+      errors: [{ messageId: "unexpectedScopeGet" }],
+    },
+    {
+      name: "composer without a local compose call",
+      code: ts`
+        import type { Composer, Spot } from "@app-compose/core"
+        declare const composer: Composer
+        declare const spot: Spot<string>
+
+        const scope = await composer.run()
+        scope.get(spot)
+      `,
+      errors: [{ messageId: "unexpectedScopeGet" }],
+    },
+    {
+      name: "scope in a promise callback",
+      code: ts`
+        import { compose, type Spot } from "@app-compose/core"
+        declare const spot: Spot<string>
+
+        compose().run().then((scope) => scope.get(spot))
+      `,
+      errors: [{ messageId: "unexpectedScopeGet" }],
+    },
+    {
+      name: "scope from an observer event",
+      code: ts`
+        import type { ComposeObserver, Spot } from "@app-compose/core"
+        declare const spot: Spot<string>
+
+        const observe: ComposeObserver = (event) => {
+          event.scope.get(spot)
+        }
+      `,
+      errors: [{ messageId: "unexpectedScopeGet" }],
+    },
+  ],
+})

packages/eslint-plugin/src/rules/no-scope-get/no-scope-get.ts

@@ -0,0 +1,37 @@
+import { ESLintUtils, type TSESTree as Node } from "@typescript-eslint/utils"
+import { createRule } from "@/shared/create"
+import { isType } from "@/shared/is"
+
+export default createRule({
+  name: "no-scope-get",
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Disallow `scope.get()` calls",
+    },
+    messages: {
+      unexpectedScopeGet:
+        "`scope.get()` can lead to imperative work outside the composition. Put the work in a Task and pass values through its context.",
+    },
+    schema: [],
+    hasSuggestions: false,
+  },
+  defaultOptions: [],
+  create: (context) => {
+    const services = ESLintUtils.getParserServices(context)
+
+    type ScopeGetCall = Node.CallExpression & { callee: Node.MemberExpression & { property: Node.Identifier } }
+
+    return {
+      [`CallExpression[callee.type="MemberExpression"][callee.property.type="Identifier"][callee.property.name="get"]`]:
+        (node: ScopeGetCall) => {
+          const type = services.getTypeAtLocation(node.callee.object)
+
+          const isScope = isType.scope(type, services.program)
+          if (!isScope) return
+
+          context.report({ node, messageId: "unexpectedScopeGet" })
+        },
+    }
+  },
+})

packages/eslint-plugin/src/shared/is.ts

@@ -0,0 +1,10 @@
+import type { Program, Type } from "typescript"
+import { typeMatchesSpecifier } from "@typescript-eslint/type-utils"
+import { PACKAGE_NAME } from "@/shared/constants"
+
+const isType = {
+  scope: (type: Type, program: Program) =>
+    typeMatchesSpecifier(type, { from: "package", package: PACKAGE_NAME.CORE, name: "Scope" }, program),
+}
+
+export { isType }