@ox0/guards 0.1.0

package/src/guards/no-set-state-in-render.ts

@@ -0,0 +1,91 @@
+import type { GuardFactory, GuardRawFinding } from "../types"
+
+function isPascalCase(name: string | null): boolean {
+  return Boolean(name) && /^[A-Z]/.test(name ?? "")
+}
+
+function isStateSetterName(name: string | null): boolean {
+  return Boolean(name) && /^set[A-Z0-9]/.test(name ?? "")
+}
+
+function scanRenderBody(node: Record<string, unknown>, findings: GuardRawFinding[]) {
+  const body = Array.isArray(node.body) ? node.body : []
+
+  for (const statement of body) {
+    if (!statement || typeof statement !== "object") {
+      continue
+    }
+
+    const current = statement as Record<string, unknown>
+
+    if (
+      current.type === "FunctionDeclaration" ||
+      current.type === "FunctionExpression" ||
+      current.type === "ArrowFunctionExpression"
+    ) {
+      continue
+    }
+
+    if (current.type === "ExpressionStatement") {
+      const expression = current.expression as Record<string, unknown> | undefined
+      if (expression?.type === "CallExpression") {
+        const callee = expression.callee as Record<string, unknown> | undefined
+        if (callee?.type === "Identifier" && isStateSetterName(callee.name as string)) {
+          findings.push({
+            start: expression.start as number,
+            end: expression.end as number,
+            message:
+              "Do not call state setters during render. Derive values in render or move the write to an event or effect.",
+          })
+        }
+      }
+    }
+
+    const consequent = current.consequent as Record<string, unknown> | undefined
+    if (consequent && Array.isArray(consequent.body)) {
+      scanRenderBody(consequent, findings)
+    }
+
+    const alternate = current.alternate as Record<string, unknown> | undefined
+    if (alternate && Array.isArray(alternate.body)) {
+      scanRenderBody(alternate, findings)
+    }
+
+    if (Array.isArray(current.body)) {
+      scanRenderBody(current, findings)
+    }
+  }
+}
+
+export const createNoSetStateInRenderGuard: GuardFactory = () => [
+  "guard/no-set-state-in-render",
+  {
+    fileExtensions: [".jsx", ".tsx"],
+    tokenPrefilter(source) {
+      return source.includes("set")
+    },
+    evaluate({ helpers, program }) {
+      const findings: GuardRawFinding[] = []
+
+      helpers.walk(program, (node, parent) => {
+        if (!helpers.isFunctionLike(node)) {
+          return
+        }
+
+        const name = helpers.getFunctionName(node, parent)
+        if (!isPascalCase(name)) {
+          return
+        }
+
+        const body = node.body as Record<string, unknown> | undefined
+        if (!body || body.type !== "BlockStatement") {
+          return
+        }
+
+        scanRenderBody(body, findings)
+      })
+
+      return findings
+    },
+  },
+]

package/src/guards/no-unsafe-type-assertion.ts

@@ -0,0 +1,50 @@
+import type { GuardFactory, GuardRawFinding } from "../types"
+
+const EXCLUDED_PATHS = new Set([
+  "packages/guards/",
+  "packages/hooks/src/use-local-storage.ts",
+  "packages/utils/src/index.ts",
+  "scripts/",
+])
+
+function isExcludedPath(relativeFilePath: string): boolean {
+  const normalized = relativeFilePath.split("\\").join("/")
+  return [...EXCLUDED_PATHS].some((entry) => normalized === entry || normalized.startsWith(entry))
+}
+
+export const createNoUnsafeTypeAssertionGuard: GuardFactory = () => [
+  "guard/no-unsafe-type-assertion",
+  {
+    fileExtensions: [".ts", ".tsx", ".mts", ".cts"],
+    tokenPrefilter(source) {
+      return source.includes(" as ")
+    },
+    evaluate({ helpers, program, relativeFilePath, source }) {
+      if (relativeFilePath.endsWith(".d.ts") || isExcludedPath(relativeFilePath)) {
+        return []
+      }
+
+      const findings: GuardRawFinding[] = []
+
+      helpers.walk(program, (node) => {
+        if (node.type !== "TSAsExpression") {
+          return
+        }
+
+        const expressionText = source.slice(node.start as number, node.end as number)
+        if (expressionText.trimEnd().endsWith(" as const")) {
+          return
+        }
+
+        findings.push({
+          start: node.start as number,
+          end: node.end as number,
+          message:
+            "Unsafe type assertions are not allowed here. Prefer narrowing, validation, or better typing.",
+        })
+      })
+
+      return findings
+    },
+  },
+]

package/src/guards/no-web-storage.ts

@@ -0,0 +1,55 @@
+import type { GuardFactory, GuardRawFinding } from "../types"
+
+const STORAGE_NAMES = new Set([
+  "localStorage",
+  "sessionStorage",
+  "window.localStorage",
+  "window.sessionStorage",
+  "globalThis.localStorage",
+  "globalThis.sessionStorage",
+])
+const ALLOWED_WRAPPER_PATHS = new Set(["packages/hooks/src/use-local-storage.ts"])
+
+export const createNoWebStorageGuard: GuardFactory = () => [
+  "guard/no-web-storage",
+  {
+    fileExtensions: [".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".mts", ".cts"],
+    tokenPrefilter(source) {
+      return source.includes("localStorage") || source.includes("sessionStorage")
+    },
+    evaluate({ filePath, helpers, program }) {
+      const normalizedFilePath = filePath.split("\\").join("/")
+      if (
+        [...ALLOWED_WRAPPER_PATHS].some((allowedPath) => normalizedFilePath.endsWith(allowedPath))
+      ) {
+        return []
+      }
+
+      const findings: GuardRawFinding[] = []
+
+      helpers.walk(program, (node) => {
+        if (node.type !== "Identifier" && node.type !== "MemberExpression") {
+          return
+        }
+
+        const name =
+          node.type === "Identifier"
+            ? helpers.getCalleeName(node)
+            : helpers.getCalleeName(node.object)
+
+        if (!name || !STORAGE_NAMES.has(name)) {
+          return
+        }
+
+        findings.push({
+          start: node.start as number,
+          end: node.end as number,
+          message:
+            "Direct web storage access is not allowed in ox0 primitives. Use a storage abstraction or inject persistence.",
+        })
+      })
+
+      return findings
+    },
+  },
+]

package/src/guards/require-effect-cleanup.ts

@@ -0,0 +1,234 @@
+import type { GuardFactory, GuardRawFinding } from "../types"
+
+const EFFECT_HOOKS = new Set(["useEffect", "useLayoutEffect"])
+const OBSERVER_NAMES = new Set(["MutationObserver", "ResizeObserver"])
+
+type SetupKind = "event-listener" | "observer" | "timeout" | "interval"
+
+function getFunctionBody(node: Record<string, unknown>): Record<string, unknown> | null {
+  const body = node.body
+  return body && typeof body === "object" && !Array.isArray(body)
+    ? (body as Record<string, unknown>)
+    : null
+}
+
+function getReturnCleanupFunction(node: Record<string, unknown>) {
+  const body = getFunctionBody(node)
+  if (!body || body.type !== "BlockStatement") {
+    return null
+  }
+
+  const statements = Array.isArray(body.body) ? body.body : []
+  for (const statement of statements) {
+    if (!statement || typeof statement !== "object") {
+      continue
+    }
+
+    const current = statement as Record<string, unknown>
+    if (current.type !== "ReturnStatement") {
+      continue
+    }
+
+    const argument = current.argument
+    if (!argument || typeof argument !== "object") {
+      continue
+    }
+
+    if (
+      (argument as { type?: string }).type === "FunctionExpression" ||
+      (argument as { type?: string }).type === "ArrowFunctionExpression"
+    ) {
+      return argument as Record<string, unknown>
+    }
+  }
+
+  return null
+}
+
+function collectSetups(
+  body: Record<string, unknown>,
+  helpers: {
+    getCalleeName: (node: unknown) => string | null
+    walk: (
+      node: unknown,
+      visitor: (node: Record<string, unknown>, parent: Record<string, unknown> | null) => void,
+      parent?: Record<string, unknown> | null,
+    ) => void
+  },
+) {
+  const setups: Array<{ end: number; kind: SetupKind; start: number }> = []
+
+  helpers.walk(body, (node) => {
+    if (node.type === "CallExpression") {
+      const calleeName = helpers.getCalleeName(node.callee)
+
+      if (calleeName === "setInterval" || calleeName === "window.setInterval") {
+        setups.push({
+          kind: "interval",
+          start: node.start as number,
+          end: node.end as number,
+        })
+      }
+
+      if (calleeName === "setTimeout" || calleeName === "window.setTimeout") {
+        setups.push({
+          kind: "timeout",
+          start: node.start as number,
+          end: node.end as number,
+        })
+      }
+
+      if (calleeName?.endsWith(".addEventListener") || calleeName === "addEventListener") {
+        setups.push({
+          kind: "event-listener",
+          start: node.start as number,
+          end: node.end as number,
+        })
+      }
+
+      return
+    }
+
+    if (node.type !== "NewExpression") {
+      return
+    }
+
+    const calleeName = helpers.getCalleeName(node.callee)
+    if (!calleeName || !OBSERVER_NAMES.has(calleeName)) {
+      return
+    }
+
+    setups.push({
+      kind: "observer",
+      start: node.start as number,
+      end: node.end as number,
+    })
+  })
+
+  return setups
+}
+
+function collectCleanupKinds(
+  cleanupFn: Record<string, unknown>,
+  helpers: {
+    getCalleeName: (node: unknown) => string | null
+    walk: (
+      node: unknown,
+      visitor: (node: Record<string, unknown>, parent: Record<string, unknown> | null) => void,
+      parent?: Record<string, unknown> | null,
+    ) => void
+  },
+) {
+  const kinds = new Set<SetupKind>()
+  const body = getFunctionBody(cleanupFn)
+  if (!body) {
+    return kinds
+  }
+
+  helpers.walk(body, (node) => {
+    if (node.type !== "CallExpression") {
+      return
+    }
+
+    const calleeName = helpers.getCalleeName(node.callee)
+    if (calleeName === "clearInterval" || calleeName === "window.clearInterval") {
+      kinds.add("interval")
+      return
+    }
+
+    if (calleeName === "clearTimeout" || calleeName === "window.clearTimeout") {
+      kinds.add("timeout")
+      return
+    }
+
+    if (calleeName?.endsWith(".removeEventListener") || calleeName === "removeEventListener") {
+      kinds.add("event-listener")
+      return
+    }
+
+    if (calleeName?.endsWith(".disconnect") || calleeName === "disconnect") {
+      kinds.add("observer")
+    }
+  })
+
+  return kinds
+}
+
+function getSetupLabel(kind: SetupKind): string {
+  if (kind === "event-listener") {
+    return "event listeners"
+  }
+
+  if (kind === "observer") {
+    return "observers"
+  }
+
+  if (kind === "timeout") {
+    return "timeouts"
+  }
+
+  return "intervals"
+}
+
+export const createRequireEffectCleanupGuard: GuardFactory = () => [
+  "guard/require-effect-cleanup",
+  {
+    fileExtensions: [".jsx", ".tsx", ".ts", ".js", ".mts", ".cts", ".mjs", ".cjs"],
+    tokenPrefilter(source) {
+      return (
+        (source.includes("useEffect") || source.includes("useLayoutEffect")) &&
+        (source.includes("addEventListener") ||
+          source.includes("setInterval") ||
+          source.includes("setTimeout") ||
+          source.includes("MutationObserver") ||
+          source.includes("ResizeObserver"))
+      )
+    },
+    evaluate({ helpers, program }) {
+      const findings: GuardRawFinding[] = []
+
+      helpers.walk(program, (node) => {
+        if (node.type !== "CallExpression") {
+          return
+        }
+
+        const hookName = helpers.getCalleeName(node.callee)
+        if (!hookName || !EFFECT_HOOKS.has(hookName)) {
+          return
+        }
+
+        const [callback] = Array.isArray(node.arguments) ? node.arguments : []
+        if (!callback || typeof callback !== "object" || !helpers.isFunctionLike(callback)) {
+          return
+        }
+
+        const callbackBody = getFunctionBody(callback as Record<string, unknown>)
+        if (!callbackBody) {
+          return
+        }
+
+        const setups = collectSetups(callbackBody, helpers)
+        if (setups.length === 0) {
+          return
+        }
+
+        const cleanupFn = getReturnCleanupFunction(callback as Record<string, unknown>)
+        const cleanupKinds = cleanupFn ? collectCleanupKinds(cleanupFn, helpers) : new Set()
+
+        for (const setup of setups) {
+          if (cleanupKinds.has(setup.kind)) {
+            continue
+          }
+
+          findings.push({
+            start: setup.start,
+            end: setup.end,
+            message: `Effects that create ${getSetupLabel(setup.kind)} must return a matching cleanup.`,
+          })
+        }
+      })
+
+      return findings
+    },
+  },
+]

package/src/guards/stable-provider-values.ts

@@ -0,0 +1,66 @@
+import type { GuardFactory, GuardRawFinding } from "../types"
+
+function isInlineUnstableExpression(node: Record<string, unknown>): boolean {
+  return (
+    node.type === "ObjectExpression" ||
+    node.type === "ArrayExpression" ||
+    node.type === "ArrowFunctionExpression" ||
+    node.type === "FunctionExpression" ||
+    node.type === "NewExpression"
+  )
+}
+
+export const createStableProviderValuesGuard: GuardFactory = () => [
+  "guard/stable-provider-values",
+  {
+    fileExtensions: [".jsx", ".tsx"],
+    tokenPrefilter(source) {
+      return source.includes("Provider") && source.includes("value=")
+    },
+    evaluate({ helpers, program }) {
+      const findings: GuardRawFinding[] = []
+
+      helpers.walk(program, (node, parent) => {
+        if (node.type !== "JSXAttribute") {
+          return
+        }
+
+        const attributeName = helpers.getJsxElementName(node.name)
+        if (attributeName !== "value") {
+          return
+        }
+
+        if (
+          !parent ||
+          parent.type !== "JSXOpeningElement" ||
+          !helpers.getJsxElementName(parent.name)?.endsWith("Provider")
+        ) {
+          return
+        }
+
+        const valueNode = node.value
+        if (!valueNode || (valueNode as { type?: string }).type !== "JSXExpressionContainer") {
+          return
+        }
+
+        const expression = (valueNode as { expression?: unknown }).expression
+        if (!expression || typeof expression !== "object") {
+          return
+        }
+
+        if (!isInlineUnstableExpression(expression as Record<string, unknown>)) {
+          return
+        }
+
+        findings.push({
+          start: node.start as number,
+          end: node.end as number,
+          message:
+            "Provider values should be referentially stable. Hoist or memoize the value before passing it to a Provider.",
+        })
+      })
+
+      return findings
+    },
+  },
+]

package/src/guards.ts

@@ -0,0 +1 @@
+export { GUARD_FACTORIES } from "./guards/index"

package/src/index.ts

@@ -0,0 +1,30 @@
+export * from "./check"
+export * from "./types"
+export * from "./guards"
+
+import type { GuardRuleId } from "./types"
+
+export interface Ox0GuardRule {
+  readonly id: GuardRuleId
+  readonly severity: "error"
+}
+
+export interface Ox0GuardsConfig {
+  readonly rules: readonly Ox0GuardRule[]
+}
+
+export function defineGuardsConfig(config: Ox0GuardsConfig): Ox0GuardsConfig {
+  return config
+}
+
+export const recommendedRules: readonly Ox0GuardRule[] = [
+  { id: "guard/no-async-react-component", severity: "error" },
+  { id: "guard/no-css-import", severity: "error" },
+  { id: "guard/no-effect-set-state-chain", severity: "error" },
+  { id: "guard/no-set-state-in-render", severity: "error" },
+  { id: "guard/no-unsafe-type-assertion", severity: "error" },
+  { id: "guard/stable-provider-values", severity: "error" },
+  { id: "guard/no-web-storage", severity: "error" },
+  { id: "guard/missing-label", severity: "error" },
+  { id: "guard/require-effect-cleanup", severity: "error" },
+]

package/src/types.ts

@@ -0,0 +1,73 @@
+export type GuardRuleId = `guard/${string}`
+
+export type GuardFinding = {
+  ruleId: GuardRuleId
+  message: string
+  filePath: string
+  relativeFilePath: string
+  line: number
+  column: number
+  endLine: number
+  endColumn: number
+  severity: "error"
+}
+
+export type GuardRawFinding = {
+  message: string
+  start: number
+  end?: number
+}
+
+export type GuardAst = Record<string, unknown>
+
+export type GuardHelperBundle = {
+  walk: (
+    node: unknown,
+    visitor: (node: Record<string, unknown>, parent: Record<string, unknown> | null) => void,
+    parent?: Record<string, unknown> | null,
+  ) => void
+  getCalleeName: (node: unknown) => string | null
+  getJsxElementName: (node: unknown) => string | null
+  getStringLiteralValue: (node: unknown) => string | null
+  isFunctionLike: (node: unknown) => boolean
+  getFunctionName: (node: unknown, parent: unknown) => string | null
+}
+
+export type GuardRuleContext = {
+  ruleId: GuardRuleId
+  projectRoot: string
+  filePath: string
+  relativeFilePath: string
+  source: string
+  helpers: GuardHelperBundle
+  program: GuardAst
+  comments: Array<Record<string, unknown>>
+}
+
+export type GuardTextRuleContext = {
+  ruleId: GuardRuleId
+  projectRoot: string
+  filePath: string
+  relativeFilePath: string
+  source: string
+}
+
+export type GuardRuleDefinition = {
+  fileExtensions: string[]
+  tokenPrefilter: (source: string) => boolean
+  evaluate?: (context: GuardRuleContext) => GuardRawFinding[]
+  evaluateText?: (context: GuardTextRuleContext) => GuardRawFinding[]
+}
+
+export type GuardFactory = () => [GuardRuleId, GuardRuleDefinition]
+
+export type RunGuardsOptions = {
+  cwd?: string
+  projectRoot: string
+  requestedRules?: string[]
+}
+
+export type RunGuardsResult = {
+  findings: GuardFinding[]
+  ruleIds: GuardRuleId[]
+}