@aas-dev/stack 0.0.0-stage → 0.1.0

package/plugin/aas.mjs

@@ -0,0 +1,567 @@
+const markers = [
+  "@ts-ignore",
+  "@ts-expect-error",
+  "@ts-nocheck",
+  "eslint-disable",
+  "eslint-enable",
+  "oxlint-disable",
+  "oxlint-enable",
+]
+
+const errorNames = new Set([
+  "Error",
+  "AggregateError",
+  "EvalError",
+  "RangeError",
+  "ReferenceError",
+  "SyntaxError",
+  "TypeError",
+  "URIError",
+])
+
+const rawSpecifiers = new Set([
+  "child_process",
+  "fs",
+  "http",
+  "https",
+  "net",
+  "node:child_process",
+  "node:fs",
+  "node:fs/promises",
+  "node:http",
+  "node:https",
+  "node:net",
+])
+
+const consoleMethods = new Set(["debug", "error", "info", "log", "warn"])
+
+const effectRunMethods = new Set(["runFork", "runPromise", "runPromiseExit", "runSync"])
+
+const bannedTestMembers = new Set(["only", "skip", "skipIf", "todo"])
+
+const testAliases = new Set(["fdescribe", "fit", "ftest", "xdescribe", "xit", "xtest"])
+
+const report = (context, node, message) => {
+  context.report({ node, message })
+}
+
+const literalName = (property, computed) => {
+  if (!computed && property.type === "Identifier") {
+    return property.name
+  }
+  if (
+    computed &&
+    (property.type === "Literal" || property.type === "StringLiteral") &&
+    typeof property.value === "string"
+  ) {
+    return property.value
+  }
+  return ""
+}
+
+const isProcessEnv = (node) => {
+  if (node.type !== "MemberExpression") {
+    return false
+  }
+  return (
+    node.object.type === "Identifier" &&
+    node.object.name === "process" &&
+    literalName(node.property, node.computed) === "env"
+  )
+}
+
+const hasName = (node, name) => {
+  if (node === null || node === undefined || typeof node !== "object") {
+    return false
+  }
+  if (node.type === "Identifier" && node.name === name) {
+    return true
+  }
+  return (
+    hasName(node.callee, name) ||
+    hasName(node.object, name) ||
+    hasName(node.property, name) ||
+    hasName(node.expression, name)
+  )
+}
+
+const blessedSuper = (node) => hasName(node, "TaggedError") || hasName(node, "Service")
+
+const specifier = (node) => {
+  if (node === null || node === undefined) {
+    return ""
+  }
+  if (
+    (node.type === "Literal" || node.type === "StringLiteral") &&
+    typeof node.value === "string"
+  ) {
+    return node.value
+  }
+  return ""
+}
+
+const chainParts = (callee) => {
+  const parts = []
+  let current = callee
+  while (current.type === "MemberExpression" || current.type === "ChainExpression") {
+    if (current.type === "ChainExpression") {
+      current = current.expression
+      continue
+    }
+    if (current.computed || current.property.type !== "Identifier") {
+      return []
+    }
+    parts.push(current.property.name)
+    current = current.object
+  }
+  if (current.type !== "Identifier") {
+    return []
+  }
+  parts.push(current.name)
+  parts.reverse()
+  return parts
+}
+
+const isItEffect = (parts) => {
+  if (parts[0] !== "it" || parts[1] !== "effect") {
+    return false
+  }
+  let index = 2
+  while (index < parts.length) {
+    const part = parts[index]
+    if (part !== undefined && bannedTestMembers.has(part)) {
+      return false
+    }
+    index += 1
+  }
+  return true
+}
+
+const flagModuleBinding = (context, statement) => {
+  if (statement === null || statement === undefined) {
+    return
+  }
+  if (statement.type === "VariableDeclaration" && statement.kind !== "const") {
+    report(
+      context,
+      statement,
+      "module-scope let and var are banned; keep state in a Context.Service",
+    )
+  }
+  const binding = statement.init ?? statement.left
+  if (
+    (statement.type === "ForStatement" ||
+      statement.type === "ForInStatement" ||
+      statement.type === "ForOfStatement") &&
+    binding !== null &&
+    binding !== undefined &&
+    binding.type === "VariableDeclaration" &&
+    binding.kind !== "const"
+  ) {
+    report(context, binding, "module-scope let and var are banned; keep state in a Context.Service")
+  }
+}
+
+const noThrow = {
+  meta: { type: "problem" },
+  create(context) {
+    return {
+      ThrowStatement(node) {
+        report(context, node, "throw is banned; yield a Schema.TaggedError")
+      },
+    }
+  },
+}
+
+const noTry = {
+  meta: { type: "problem" },
+  create(context) {
+    return {
+      TryStatement(node) {
+        report(context, node, "try is banned; failures stay on the Effect channel")
+      },
+    }
+  },
+}
+
+const noErrorClass = {
+  meta: { type: "problem" },
+  create(context) {
+    return {
+      NewExpression(node) {
+        const callee = node.callee
+        const name =
+          callee.type === "Identifier"
+            ? callee.name
+            : callee.type === "MemberExpression"
+              ? literalName(callee.property, callee.computed)
+              : ""
+        if (errorNames.has(name)) {
+          report(context, node, "new Error is banned; define a Schema.TaggedError")
+        }
+      },
+    }
+  },
+}
+
+const noProcessEnv = {
+  meta: { type: "problem" },
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if (isProcessEnv(node)) {
+          report(
+            context,
+            node,
+            "process.env is banned; declare the variable in .env.schema and read it with Config",
+          )
+        }
+      },
+    }
+  },
+}
+
+const noTypeAssertion = {
+  meta: { type: "problem" },
+  create(context) {
+    return {
+      TSAsExpression(node) {
+        report(
+          context,
+          node,
+          "type assertions are banned, including as const; parse with Schema or use a const type parameter",
+        )
+      },
+      TSTypeAssertion(node) {
+        report(
+          context,
+          node,
+          "angle-bracket assertions are banned; parse with Schema or use a const type parameter",
+        )
+      },
+    }
+  },
+}
+
+const noExplicitAny = {
+  meta: { type: "problem" },
+  create(context) {
+    return {
+      TSAnyKeyword(node) {
+        report(context, node, "any is banned; use unknown and decode it with Schema")
+      },
+    }
+  },
+}
+
+const noNonNullAssertion = {
+  meta: { type: "problem" },
+  create(context) {
+    return {
+      TSNonNullExpression(node) {
+        report(
+          context,
+          node,
+          "non-null assertions are banned; narrow the value or decode it with Schema",
+        )
+      },
+    }
+  },
+}
+
+const textOf = (context) => {
+  const source = context.sourceCode
+  if (typeof source.text === "string") {
+    return source.text
+  }
+  if (typeof source.getText === "function") {
+    return source.getText()
+  }
+  return ""
+}
+
+const commentStart = (comment) => {
+  const range = comment.range
+  if (Array.isArray(range)) {
+    const start = range[0]
+    return typeof start === "number" ? start : -1
+  }
+  if (range !== null && range !== undefined && typeof range.start === "number") {
+    return range.start
+  }
+  if (typeof comment.start === "number") {
+    return comment.start
+  }
+  return -1
+}
+
+const isShebang = (comment, text) => {
+  if (comment.type === "Shebang" || comment.type === "Hashbang") {
+    return true
+  }
+  return text.startsWith("#!") && commentStart(comment) === 0
+}
+
+const noComments = {
+  meta: { type: "problem" },
+  create(context) {
+    const text = textOf(context)
+    return {
+      Program(node) {
+        for (const comment of context.sourceCode.getAllComments()) {
+          if (isShebang(comment, text)) {
+            continue
+          }
+          const message = "comments are banned; use clearer names or docs"
+          if (comment.loc === undefined || comment.loc === null) {
+            report(context, node, message)
+          } else {
+            context.report({ loc: comment.loc, message })
+          }
+        }
+      },
+    }
+  },
+}
+
+const noBypassComment = {
+  meta: { type: "problem" },
+  create(context) {
+    return {
+      Program(node) {
+        for (const comment of context.sourceCode.getAllComments()) {
+          let matched = ""
+          for (const marker of markers) {
+            if (comment.value.includes(marker)) {
+              matched = marker
+              break
+            }
+          }
+          if (matched === "") {
+            continue
+          }
+          const message = `directive comments are banned (${matched})`
+          if (comment.loc === undefined || comment.loc === null) {
+            report(context, node, message)
+          } else {
+            context.report({ loc: comment.loc, message })
+          }
+        }
+      },
+    }
+  },
+}
+
+const effectTests = {
+  meta: { type: "problem" },
+  create(context) {
+    const filename = typeof context.filename === "string" ? context.filename : ""
+    const isTest = filename.endsWith(".test.ts")
+    return {
+      ImportDeclaration(node) {
+        const source = specifier(node.source)
+        if (source === "vitest/config") {
+          if (!filename.endsWith("/vitest.config.ts") && !filename.endsWith("\\vitest.config.ts")) {
+            report(context, node, "import tests from @effect/vitest")
+          }
+          return
+        }
+        if (source === "vitest" || source.startsWith("vitest/") || source.startsWith("@vitest/")) {
+          report(context, node, "import tests from @effect/vitest")
+        }
+      },
+      CallExpression(node) {
+        if (!isTest) {
+          return
+        }
+        const parts = chainParts(node.callee)
+        const root = parts[0]
+        if (root === undefined) {
+          if (
+            node.callee.type === "Identifier" &&
+            (node.callee.name === "it" ||
+              node.callee.name === "test" ||
+              testAliases.has(node.callee.name))
+          ) {
+            report(context, node, "tests use it.effect from @effect/vitest")
+          }
+          return
+        }
+        if (isItEffect(parts)) {
+          return
+        }
+        if (root === "it" || root === "test" || testAliases.has(root)) {
+          report(context, node, "tests use it.effect from @effect/vitest")
+          return
+        }
+        if (root === "describe") {
+          let index = 1
+          while (index < parts.length) {
+            const part = parts[index]
+            if (part !== undefined && bannedTestMembers.has(part)) {
+              report(context, node, "skipped, focused, and todo tests are banned")
+              return
+            }
+            index += 1
+          }
+        }
+      },
+    }
+  },
+}
+
+const noRawIo = {
+  meta: { type: "problem" },
+  create(context) {
+    return {
+      ImportDeclaration(node) {
+        if (rawSpecifiers.has(specifier(node.source))) {
+          report(
+            context,
+            node,
+            "raw IO imports are banned; use Effect FileSystem, HttpClient, or ChildProcess",
+          )
+        }
+      },
+      ImportExpression(node) {
+        if (rawSpecifiers.has(specifier(node.source))) {
+          report(
+            context,
+            node,
+            "raw IO imports are banned; use Effect FileSystem, HttpClient, or ChildProcess",
+          )
+        }
+      },
+      CallExpression(node) {
+        const callee = node.callee
+        if (callee.type === "Identifier" && callee.name === "fetch") {
+          report(context, node, "global fetch is banned; use Effect HttpClient")
+          return
+        }
+        if (
+          callee.type === "Identifier" &&
+          callee.name === "require" &&
+          rawSpecifiers.has(specifier(node.arguments[0]))
+        ) {
+          report(
+            context,
+            node,
+            "raw IO imports are banned; use Effect FileSystem, HttpClient, or ChildProcess",
+          )
+          return
+        }
+        if (callee.type !== "MemberExpression") {
+          return
+        }
+        const name = literalName(callee.property, callee.computed)
+        if (
+          callee.object.type === "Identifier" &&
+          callee.object.name === "console" &&
+          consoleMethods.has(name)
+        ) {
+          report(context, node, "console is banned; use Effect Console")
+          return
+        }
+        if (
+          callee.object.type === "Identifier" &&
+          (callee.object.name === "globalThis" ||
+            callee.object.name === "global" ||
+            callee.object.name === "window") &&
+          name === "fetch"
+        ) {
+          report(context, node, "global fetch is banned; use Effect HttpClient")
+        }
+      },
+    }
+  },
+}
+
+const noEffectRun = {
+  meta: { type: "problem" },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        if (callee.type !== "MemberExpression") {
+          return
+        }
+        if (
+          callee.object.type === "Identifier" &&
+          callee.object.name === "Effect" &&
+          effectRunMethods.has(literalName(callee.property, callee.computed))
+        ) {
+          report(
+            context,
+            node,
+            "Effect.run* is banned; stay inside Effect and use it.effect in tests",
+          )
+        }
+      },
+    }
+  },
+}
+
+const noModuleLet = {
+  meta: { type: "problem" },
+  create(context) {
+    return {
+      Program(node) {
+        for (const statement of node.body) {
+          const declaration =
+            statement.type === "ExportNamedDeclaration" ? statement.declaration : statement
+          flagModuleBinding(context, declaration)
+        }
+      },
+    }
+  },
+}
+
+const noPlainClass = {
+  meta: { type: "problem" },
+  create(context) {
+    return {
+      ClassDeclaration(node) {
+        if (!blessedSuper(node.superClass)) {
+          report(
+            context,
+            node,
+            "plain classes are banned; extend Schema.TaggedError or Context.Service",
+          )
+        }
+      },
+      ClassExpression(node) {
+        if (!blessedSuper(node.superClass)) {
+          report(
+            context,
+            node,
+            "plain classes are banned; extend Schema.TaggedError or Context.Service",
+          )
+        }
+      },
+    }
+  },
+}
+
+const rules = {
+  "effect-tests": effectTests,
+  "no-bypass-comment": noBypassComment,
+  "no-comments": noComments,
+  "no-effect-run": noEffectRun,
+  "no-error-class": noErrorClass,
+  "no-explicit-any": noExplicitAny,
+  "no-module-let": noModuleLet,
+  "no-non-null-assertion": noNonNullAssertion,
+  "no-plain-class": noPlainClass,
+  "no-process-env": noProcessEnv,
+  "no-raw-io": noRawIo,
+  "no-throw": noThrow,
+  "no-try": noTry,
+  "no-type-assertion": noTypeAssertion,
+}
+
+export const ruleNames = Object.keys(rules)
+
+export default {
+  meta: { name: "aas" },
+  rules,
+}

package/templates/AGENTS.md

@@ -0,0 +1,132 @@
+# AGENTS.md
+
+This project uses aas-stack. The ideal is one way to do each thing, and `pnpm verify` is the score. A check that cannot run in this environment gets changed until it can. A check that passes while a bypass still works is too lax.
+
+`aas verify` is the gate. `pnpm verify` calls it. On success it prints nothing. On failure it prints `file:line` diagnostics.
+
+## The loop
+
+`aas verify` runs, in order:
+
+1. A drift check. `.cursor/hooks.json`, `.vite-hooks/pre-commit`, `pnpm-workspace.yaml`, `AGENTS.md`, `.github/workflows/verify.yml`, `vite.config.ts`, and `tsconfig.json` must match the templates from `aas init`. `aas sync` rewrites them.
+2. `varlock load`, when `.env.schema` is present, so the schema is valid.
+3. `vp fmt --check` (Oxfmt, through Vite+).
+4. `vp lint` (Oxlint, through Vite+, with the `aas` rules below).
+5. `vp pack` (tsdown, through Vite+) for each library.
+6. `tsc --noEmit` with the `@effect/tsgo` language service.
+7. `vp test` (`@effect/vitest` on the Vitest that ships with Vite+).
+
+Vite+ does not replace the Effect typecheck. `vp check`'s type checker is tsgolint and does not run `@effect/language-service`. The patched `tsc` does.
+
+The Cursor `beforeShellExecution` hook, the Vite+ pre-commit hook, and GitHub Actions all call this same gate. The hook is `failClosed`. CI does not set `continue-on-error`.
+
+`NodeRuntime.runMain` in `packages/cli/src/bin.ts` and `packages/cli/src/cursor-hook.ts` is the process boundary. Everywhere else, stay inside Effect.
+
+## Blessed patterns
+
+One pattern per concern. The lint rule is what makes the other patterns unavailable.
+
+### Errors
+
+Yield a `Schema.TaggedError`. Pass the brand parameter `@effect/tsgo` requires.
+
+```ts
+export class EmptyText extends Schema.TaggedError<EmptyText, { readonly brand: unique symbol }>()(
+  "EmptyText",
+  {},
+) {}
+
+yield * new EmptyText({})
+```
+
+`aas/no-throw`, `aas/no-try`, and `aas/no-error-class` reject `throw`, `try`, and `new Error` (including the other built-in error constructors).
+
+### Config
+
+Declare every variable in `.env.schema`. Read it with `Config`. The schema is the only place a default lives. Do not also call `Config.withDefault`.
+
+`aas/no-process-env` rejects `process.env`, `process["env"]`, and `process?.env`.
+
+Keep a string tuple without a type assertion:
+
+```ts
+const literals = <const Values extends readonly string[]>(...values: Values): Values => values
+
+export const AppEnv = Config.Literals(literals("development", "test", "production"), "APP_ENV")
+```
+
+### Services
+
+Extend `Context.Service` and provide a `Layer`.
+
+```ts
+export class AppConfig extends Context.Service<
+  AppConfig,
+  { readonly env: "development" | "test" | "production" }
+>()("aas/AppConfig") {
+  static readonly layer = Layer.effect(
+    AppConfig,
+    Effect.gen(function* () {
+      const env = yield* AppEnv
+      return AppConfig.of({ env })
+    }),
+  )
+}
+```
+
+`aas/no-plain-class` rejects a class whose superclass is not `Schema.TaggedError` or `Context.Service`. `aas/no-module-let` rejects module-scope `let` and `var`. A binding inside a function is fine. State that outlives a call belongs on a service.
+
+### IO
+
+Use Effect's `FileSystem`, `HttpClient`, `ChildProcess`, and `Console`. Stay inside Effect. Tests use `it.effect` instead of running the boundary.
+
+`aas/no-raw-io` rejects `node:fs`, `node:fs/promises`, `fs`, `node:child_process`, `child_process`, `node:http`, `http`, `node:https`, `https`, `node:net`, `net`, `require` of those modules, dynamic `import` of those modules, global `fetch`, and `console.log` / `error` / `warn` / `info` / `debug`.
+
+`aas/no-effect-run` rejects `Effect.runPromise`, `Effect.runSync`, `Effect.runFork`, and `Effect.runPromiseExit`.
+
+### Tests
+
+```ts
+import { assert, describe, it } from "@effect/vitest"
+
+it.effect("counts code points", () =>
+  Effect.gen(function* () {
+    const counted = yield* countText("👋")
+    assert.strictEqual(counted.characters, 1)
+  }),
+)
+```
+
+`aas/effect-tests` rejects imports from `vitest` or `@vitest/*`, plain `it()` / `test()`, `it.skip` / `it.only` / `it.todo` / `it.skipIf` / `it.live`, `describe.only`, and the aliases `fit`, `fdescribe`, `ftest`, `xit`, `xdescribe`, `xtest`. `it.effect` (and `it.effect.each` / `it.effect.prop`) is the runner. `describe` without a focus or skip modifier is fine.
+
+Assert observable behavior. Do not mock the capability. A test that needs a process or the filesystem uses the Node `ChildProcess` and `FileSystem` layers and really runs them.
+
+### Types
+
+`aas/no-explicit-any` rejects `any`. `aas/no-type-assertion` rejects `as` and angle-bracket assertions, including `as const`. `aas/no-non-null-assertion` rejects `!`. An import alias (`import { readFile as read }`) is not a type assertion.
+
+External data is `unknown` until a `Schema` decodes it. Discriminate unions and exhaust them. Brand a value by parsing it. A `Schema.TaggedError` passes `{ readonly brand: unique symbol }` as its brand parameter. `@effect/tsgo` errors on leaked requirements, floating effects, global `Date` / `fetch` / `console`, Node built-in imports, and `instanceof` on a schema type (`Schema.is` is the check). `unstableApiUsage` is off because the Effect v4 APIs this stack requires are still marked unstable.
+
+## Comments
+
+`aas/no-comments` rejects a line comment, a block comment, and a JSDoc comment. The diagnostic tells the author to use clearer names or docs. A shebang line is not a comment. `/// <reference>` is a line comment, and `aas/no-bypass-comment` does not list it. `@ts-ignore`, `@ts-expect-error`, and `@ts-nocheck` are already `aas/no-bypass-comment` hits; `aas/no-comments` reports those comments as well. `@ts-check` is not a bypass marker. The fence test scans source text, skipping a leading shebang and quoted spans, so a comment the linter did not report still fails.
+
+## Bypasses the fence catches
+
+`aas/no-bypass-comment` rejects comments that contain `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, `eslint-disable`, `eslint-enable`, `oxlint-disable`, or `oxlint-enable`. A disable comment can silence the statement it covers, so the fence test also scans source text. A block comment that hides every oxlint diagnostic still fails that scan. The fixtures in `packages/fence/fixtures` are ignored by the normal lint so they can exist; `packages/fence` runs `vp lint` on them and asserts each rule id and count. Blessed fixtures must produce zero diagnostics.
+
+Git cannot delete `--no-verify`. The agent hook rejects it anyway, including inside `bash -c "..."`. It also rejects a short option cluster that contains `n` on `commit`, `merge`, `rebase`, `cherry-pick`, `am`, and `pull` (`-n`, `-nm`, `-an`), and it rejects `LEFTHOOK=0`, `HUSKY=0`, `VP_GIT_HOOKS=0`, `VITE_GIT_HOOKS=0`, `vp hooks disable`, and `vp.hooks.disabled`. `git log -n 5`, `git push -n`, `git commit -m "hello -n"`, `vp hooks enable`, and `vp hooks status` stay allowed: `-n` is only special on the subcommands above, and a quoted message is not a flag. Unreadable hook input crashes the process, and `failClosed` turns that crash into a deny. The Vite+ pre-commit hook runs `pnpm exec aas verify` for a human commit. CI runs the same command even if the hook was skipped.
+
+## Ideal
+
+One capability, one error style, one config source, one service style, one IO style, one test style. `@aas-stack/core` is that shape for one capability, `countText`: blank text fails with `EmptyText`, and a counted value reports Unicode code points, whitespace-separated words, and `\n`-separated lines. `AppEnv` and `AppConfig` are the config and service examples. Climb toward more capabilities in that shape. Do not add a second pattern because the first one is inconvenient.
+
+## Vendored Effect
+
+`pnpm vendor:agent-sources` clones the Effect version pinned by `@aas-stack/core` into `vendor/effect`. The clone is gitignored. `pnpm verify` does not clone.
+
+## Not in this commit
+
+HTTP with OpenAPI, MCP, and the Executor app adapter are next. The runtime constraint those adapters have to meet is already written in `docs/executor-runtime.md`. `kristoffer-aas/roborock-mcp` is the planned first consumer.
+
+rat-stack and pstack are the inspiration for the fence and the TypeScript rules. This repo does not vendor their code, and it does not use XState or Alchemy.

package/templates/hooks.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": "node ./node_modules/@aas-dev/stack/dist/cursor-hook.js",
+        "failClosed": true
+      }
+    ]
+  }
+}