@ox0/guards 0.1.0

package/src/cli.ts

@@ -0,0 +1,160 @@
+import path from "node:path"
+import process from "node:process"
+
+import { listGuardRuleIds, runGuards } from "./check"
+
+type CliOptions = {
+  color: boolean
+  projectRoot: string
+  quiet: boolean
+  requestedRules: string[]
+  showRules: boolean
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  const options: CliOptions = {
+    color: process.stdout.isTTY,
+    projectRoot: ".",
+    quiet: false,
+    requestedRules: [],
+    showRules: false,
+  }
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+
+    if (arg === "--all") {
+      continue
+    }
+
+    if (arg === "--quiet") {
+      options.quiet = true
+      continue
+    }
+
+    if (arg === "--rules") {
+      options.showRules = true
+      continue
+    }
+
+    if (arg === "--color") {
+      options.color = true
+      continue
+    }
+
+    if (arg === "--no-color") {
+      options.color = false
+      continue
+    }
+
+    if (arg === "--rule") {
+      const value = argv[index + 1]
+      if (!value) {
+        throw new Error("--rule requires a value.")
+      }
+      options.requestedRules.push(value)
+      index += 1
+      continue
+    }
+
+    if (arg.startsWith("--rule=")) {
+      options.requestedRules.push(arg.slice("--rule=".length))
+      continue
+    }
+
+    if (arg === "--project") {
+      const value = argv[index + 1]
+      if (!value) {
+        throw new Error("--project requires a value.")
+      }
+      options.projectRoot = value
+      index += 1
+      continue
+    }
+
+    if (arg.startsWith("--project=")) {
+      options.projectRoot = arg.slice("--project=".length)
+      continue
+    }
+
+    if (!arg.startsWith("-")) {
+      options.projectRoot = arg
+      continue
+    }
+
+    throw new Error(`Unknown argument: ${arg}`)
+  }
+
+  return options
+}
+
+function paint(value: string, color: boolean, code: number): string {
+  return color ? `\u001B[${code}m${value}\u001B[0m` : value
+}
+
+function formatFinding(
+  finding: {
+    relativeFilePath: string
+    line: number
+    column: number
+    ruleId: string
+    message: string
+  },
+  color: boolean,
+): string {
+  const location = `${finding.relativeFilePath}:${finding.line}:${finding.column}`
+  return `${paint(location, color, 36)}  ${paint(finding.ruleId, color, 31)}  ${finding.message}`
+}
+
+function main(): void {
+  const options = parseArgs(process.argv.slice(2))
+
+  if (options.showRules) {
+    for (const ruleId of listGuardRuleIds()) {
+      console.log(ruleId)
+    }
+    return
+  }
+
+  const projectRoot = path.resolve(process.cwd(), options.projectRoot)
+  const result = runGuards({
+    cwd: process.cwd(),
+    projectRoot: options.projectRoot,
+    requestedRules: options.requestedRules,
+  })
+
+  if (result.findings.length === 0) {
+    if (!options.quiet) {
+      console.log(`No guard findings in ${path.basename(projectRoot)}.`)
+    }
+    return
+  }
+
+  const counts = new Map<string, number>()
+  for (const finding of result.findings) {
+    counts.set(finding.ruleId, (counts.get(finding.ruleId) ?? 0) + 1)
+  }
+
+  console.log(paint(`Guard findings: ${result.findings.length}`, options.color, 31))
+  for (const [ruleId, count] of [...counts.entries()].toSorted((left, right) =>
+    left[0].localeCompare(right[0]),
+  )) {
+    console.log(`  ${paint(ruleId, options.color, 33)}: ${count}`)
+  }
+  console.log("")
+
+  for (const finding of result.findings) {
+    console.log(formatFinding(finding, options.color))
+  }
+
+  process.exitCode = 1
+}
+
+try {
+  main()
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(message)
+  console.error("Usage: ox0-guards [--project <path>] [--rule <rule-id>] [--quiet] [--rules]")
+  process.exitCode = 1
+}

package/src/guards/index.ts

@@ -0,0 +1,24 @@
+import type { GuardFactory } from "../types"
+import { createMissingLabelGuard } from "./missing-label"
+import { createNoAsyncReactComponentGuard } from "./no-async-react-component"
+import { createNoBareIntlGuard } from "./no-bare-intl"
+import { createNoCssImportGuard } from "./no-css-import"
+import { createNoEffectSetStateChainGuard } from "./no-effect-set-state-chain"
+import { createNoSetStateInRenderGuard } from "./no-set-state-in-render"
+import { createNoUnsafeTypeAssertionGuard } from "./no-unsafe-type-assertion"
+import { createNoWebStorageGuard } from "./no-web-storage"
+import { createRequireEffectCleanupGuard } from "./require-effect-cleanup"
+import { createStableProviderValuesGuard } from "./stable-provider-values"
+
+export const GUARD_FACTORIES: GuardFactory[] = [
+  createNoAsyncReactComponentGuard,
+  createNoBareIntlGuard,
+  createNoCssImportGuard,
+  createNoEffectSetStateChainGuard,
+  createNoSetStateInRenderGuard,
+  createNoUnsafeTypeAssertionGuard,
+  createStableProviderValuesGuard,
+  createNoWebStorageGuard,
+  createMissingLabelGuard,
+  createRequireEffectCleanupGuard,
+]

package/src/guards/missing-label.ts

@@ -0,0 +1,79 @@
+import type { GuardFactory, GuardRawFinding } from "../types"
+
+const LABELABLE_ELEMENTS = new Set(["input", "select", "textarea"])
+const LABEL_ATTRIBUTES = new Set(["aria-label", "aria-labelledby"])
+const ALLOWED_COMPONENT_PATHS = new Set(["packages/ui/src/components/text-field.tsx"])
+
+function hasUsefulAttribute(
+  node: Record<string, unknown>,
+  helpers: { getJsxElementName: (node: unknown) => string | null },
+) {
+  const attributes = Array.isArray(node.attributes) ? node.attributes : []
+  for (const attribute of attributes) {
+    if (!attribute || typeof attribute !== "object") {
+      continue
+    }
+
+    const name = helpers.getJsxElementName((attribute as Record<string, unknown>).name)
+    if (name && LABEL_ATTRIBUTES.has(name)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+export const createMissingLabelGuard: GuardFactory = () => [
+  "guard/missing-label",
+  {
+    fileExtensions: [".jsx", ".tsx"],
+    tokenPrefilter(source) {
+      return source.includes("<input") || source.includes("<select") || source.includes("<textarea")
+    },
+    evaluate({ helpers, program, relativeFilePath }) {
+      if (ALLOWED_COMPONENT_PATHS.has(relativeFilePath.split("\\").join("/"))) {
+        return []
+      }
+
+      const findings: GuardRawFinding[] = []
+
+      helpers.walk(program, (node, parent) => {
+        if (node.type !== "JSXElement") {
+          return
+        }
+
+        const openingElement = node.openingElement as Record<string, unknown> | undefined
+        if (!openingElement) {
+          return
+        }
+
+        const elementName = helpers.getJsxElementName(openingElement.name)
+        if (!elementName || !LABELABLE_ELEMENTS.has(elementName)) {
+          return
+        }
+
+        if (hasUsefulAttribute(openingElement, helpers)) {
+          return
+        }
+
+        const wrappedByLabel =
+          parent?.type === "JSXElement" &&
+          helpers.getJsxElementName((parent.openingElement as Record<string, unknown>).name) ===
+            "label"
+
+        if (wrappedByLabel) {
+          return
+        }
+
+        findings.push({
+          start: openingElement.start as number,
+          end: openingElement.end as number,
+          message:
+            "Form controls must have a visible label or an accessible label via aria-label or aria-labelledby.",
+        })
+      })
+
+      return findings
+    },
+  },
+]

package/src/guards/no-async-react-component.ts

@@ -0,0 +1,42 @@
+import type { GuardFactory, GuardRawFinding } from "../types"
+
+function isPascalCase(name: string | null): boolean {
+  return Boolean(name) && /^[A-Z]/.test(name ?? "")
+}
+
+export const createNoAsyncReactComponentGuard: GuardFactory = () => [
+  "guard/no-async-react-component",
+  {
+    fileExtensions: [".jsx", ".tsx"],
+    tokenPrefilter(source) {
+      return source.includes("async")
+    },
+    evaluate({ helpers, program }) {
+      const findings: GuardRawFinding[] = []
+
+      helpers.walk(program, (node, parent) => {
+        if (!helpers.isFunctionLike(node)) {
+          return
+        }
+
+        if (node.async !== true) {
+          return
+        }
+
+        const name = helpers.getFunctionName(node, parent)
+        if (!isPascalCase(name)) {
+          return
+        }
+
+        findings.push({
+          start: node.start as number,
+          end: node.end as number,
+          message:
+            "React components should not be async. Move async work into loaders, actions, or effects.",
+        })
+      })
+
+      return findings
+    },
+  },
+]

package/src/guards/no-bare-intl.ts

@@ -0,0 +1,54 @@
+import type { GuardFactory, GuardRawFinding } from "../types"
+
+const INTL_CONSTRUCTORS = new Set([
+  "Intl.DateTimeFormat",
+  "Intl.NumberFormat",
+  "Intl.RelativeTimeFormat",
+  "Intl.PluralRules",
+  "Intl.Collator",
+  "Intl.ListFormat",
+  "Intl.Segmenter",
+])
+
+const ALLOWED_PATHS = ["packages/i18n/"]
+
+function isAllowedPath(relativeFilePath: string): boolean {
+  const normalized = relativeFilePath.split("\\").join("/")
+  return ALLOWED_PATHS.some((prefix) => normalized.startsWith(prefix))
+}
+
+export const createNoBareIntlGuard: GuardFactory = () => [
+  "guard/no-bare-intl",
+  {
+    fileExtensions: [".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".mts", ".cts"],
+    tokenPrefilter(source) {
+      return source.includes("new Intl.")
+    },
+    evaluate({ helpers, program, relativeFilePath }) {
+      if (isAllowedPath(relativeFilePath)) {
+        return []
+      }
+
+      const findings: GuardRawFinding[] = []
+
+      helpers.walk(program, (node) => {
+        if (node.type !== "NewExpression") {
+          return
+        }
+
+        const calleeName = helpers.getCalleeName(node.callee)
+        if (!calleeName || !INTL_CONSTRUCTORS.has(calleeName)) {
+          return
+        }
+
+        findings.push({
+          start: node.start as number,
+          end: node.end as number,
+          message: `Do not construct bare ${calleeName} instances. Intl constructors are slow; use the caching helpers from the i18n package instead.`,
+        })
+      })
+
+      return findings
+    },
+  },
+]

package/src/guards/no-css-import.ts

@@ -0,0 +1,102 @@
+import type { GuardFactory, GuardRawFinding } from "../types"
+
+const CSS_PATTERN = /\.(css|scss|less)$/i
+const ALLOWED_SPECIFIERS = new Set(["@ox0/tokens/styles.css"])
+const ALLOWED_FILE_PATHS = new Set(["packages/ui/src/providers/ox0-provider.tsx"])
+
+function isAllowedImport(relativeFilePath: string, sourceValue: string | null): boolean {
+  const normalizedPath = relativeFilePath.split("\\").join("/")
+  return (
+    Boolean(sourceValue) &&
+    ALLOWED_SPECIFIERS.has(sourceValue ?? "") &&
+    ALLOWED_FILE_PATHS.has(normalizedPath)
+  )
+}
+
+function isCssSpecifier(value: string | null): boolean {
+  return Boolean(value && CSS_PATTERN.test(value))
+}
+
+export const createNoCssImportGuard: GuardFactory = () => [
+  "guard/no-css-import",
+  {
+    fileExtensions: [".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".mts", ".cts"],
+    tokenPrefilter(source) {
+      return source.includes(".css") || source.includes(".scss") || source.includes(".less")
+    },
+    evaluate({ helpers, program, relativeFilePath }) {
+      const findings: GuardRawFinding[] = []
+
+      helpers.walk(program, (node) => {
+        if (node.type === "ImportDeclaration" || node.type === "ExportAllDeclaration") {
+          const sourceValue = helpers.getStringLiteralValue(node.source)
+          if (isAllowedImport(relativeFilePath, sourceValue) || !isCssSpecifier(sourceValue)) {
+            return
+          }
+
+          findings.push({
+            start: node.start as number,
+            end: node.end as number,
+            message:
+              "CSS imports are not allowed here. Route shared styling through approved package entrypoints.",
+          })
+          return
+        }
+
+        if (node.type === "ExportNamedDeclaration" && node.source) {
+          const sourceValue = helpers.getStringLiteralValue(node.source)
+          if (isAllowedImport(relativeFilePath, sourceValue) || !isCssSpecifier(sourceValue)) {
+            return
+          }
+
+          findings.push({
+            start: node.start as number,
+            end: node.end as number,
+            message:
+              "CSS re-exports are not allowed here. Route shared styling through approved package entrypoints.",
+          })
+          return
+        }
+
+        if (node.type === "CallExpression") {
+          const calleeName = helpers.getCalleeName(node.callee)
+          if (calleeName !== "require") {
+            return
+          }
+
+          const [firstArg] = Array.isArray(node.arguments) ? node.arguments : []
+          const sourceValue = helpers.getStringLiteralValue(firstArg)
+          if (isAllowedImport(relativeFilePath, sourceValue) || !isCssSpecifier(sourceValue)) {
+            return
+          }
+
+          findings.push({
+            start: node.start as number,
+            end: node.end as number,
+            message:
+              "CSS require calls are not allowed here. Route shared styling through approved package entrypoints.",
+          })
+          return
+        }
+
+        if (node.type !== "ImportExpression") {
+          return
+        }
+
+        const sourceValue = helpers.getStringLiteralValue(node.source)
+        if (isAllowedImport(relativeFilePath, sourceValue) || !isCssSpecifier(sourceValue)) {
+          return
+        }
+
+        findings.push({
+          start: node.start as number,
+          end: node.end as number,
+          message:
+            "Dynamic CSS imports are not allowed here. Route shared styling through approved package entrypoints.",
+        })
+      })
+
+      return findings
+    },
+  },
+]

package/src/guards/no-effect-set-state-chain.ts

@@ -0,0 +1,189 @@
+import type { GuardFactory, GuardRawFinding } from "../types"
+
+const EFFECT_HOOKS = new Set(["useEffect", "useLayoutEffect"])
+
+function isNode(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value)
+}
+
+function isIdentifier(node: unknown): node is { name: string; type: "Identifier" } {
+  return isNode(node) && node.type === "Identifier" && typeof node.name === "string"
+}
+
+function getFunctionBody(node: unknown): Record<string, unknown> | null {
+  return isNode(node) && isNode(node.body) ? node.body : null
+}
+
+function collectStatePairs(body: Record<string, unknown>): Map<string, string> {
+  const setterToState = new Map<string, string>()
+  const statements = Array.isArray(body.body) ? body.body : []
+
+  for (const statement of statements) {
+    if (!isNode(statement) || statement.type !== "VariableDeclaration") {
+      continue
+    }
+
+    const declarations = Array.isArray(statement.declarations) ? statement.declarations : []
+
+    for (const declaration of declarations) {
+      if (!isNode(declaration)) {
+        continue
+      }
+
+      const id = declaration.id
+      const init = declaration.init
+      if (!isNode(id) || !isNode(init) || init.type !== "CallExpression") {
+        continue
+      }
+
+      const callee = init.callee
+      if (!isIdentifier(callee) || callee.name !== "useState") {
+        continue
+      }
+
+      const elements = Array.isArray(id.elements) ? id.elements : []
+      const [stateNode, setterNode] = elements
+      if (!isIdentifier(stateNode) || !isIdentifier(setterNode)) {
+        continue
+      }
+
+      setterToState.set(setterNode.name, stateNode.name)
+    }
+  }
+
+  return setterToState
+}
+
+function collectDependencyNames(node: Record<string, unknown>): Set<string> {
+  const names = new Set<string>()
+  const elements = Array.isArray(node.elements) ? node.elements : []
+
+  for (const element of elements) {
+    if (isIdentifier(element)) {
+      names.add(element.name)
+    }
+  }
+
+  return names
+}
+
+function referencesIdentifier(
+  node: unknown,
+  identifierName: string,
+  helpers: {
+    walk: (
+      node: unknown,
+      visitor: (node: Record<string, unknown>, parent: Record<string, unknown> | null) => void,
+      parent?: Record<string, unknown> | null,
+    ) => void
+  },
+): boolean {
+  let found = false
+
+  helpers.walk(node, (current) => {
+    if (found) {
+      return
+    }
+
+    if (current.type === "Identifier" && current.name === identifierName) {
+      found = true
+    }
+  })
+
+  return found
+}
+
+export const createNoEffectSetStateChainGuard: GuardFactory = () => [
+  "guard/no-effect-set-state-chain",
+  {
+    fileExtensions: [".jsx", ".tsx"],
+    tokenPrefilter(source) {
+      return (
+        (source.includes("useEffect") || source.includes("useLayoutEffect")) &&
+        source.includes("useState") &&
+        source.includes("set")
+      )
+    },
+    evaluate({ helpers, program }) {
+      const findings: GuardRawFinding[] = []
+
+      helpers.walk(program, (node) => {
+        if (!helpers.isFunctionLike(node)) {
+          return
+        }
+
+        const functionBody = getFunctionBody(node)
+        if (!functionBody || functionBody.type !== "BlockStatement") {
+          return
+        }
+
+        const setterToState = collectStatePairs(functionBody)
+        if (setterToState.size === 0) {
+          return
+        }
+
+        helpers.walk(functionBody, (innerNode) => {
+          if (innerNode.type !== "CallExpression") {
+            return
+          }
+
+          const hookName = helpers.getCalleeName(innerNode.callee)
+          if (!hookName || !EFFECT_HOOKS.has(hookName)) {
+            return
+          }
+
+          const args = Array.isArray(innerNode.arguments) ? innerNode.arguments : []
+          const callback = args[0]
+          const deps = args[1]
+          if (
+            !callback ||
+            !helpers.isFunctionLike(callback) ||
+            !isNode(deps) ||
+            deps.type !== "ArrayExpression"
+          ) {
+            return
+          }
+
+          const depNames = collectDependencyNames(deps)
+          if (depNames.size === 0) {
+            return
+          }
+
+          const callbackBody = getFunctionBody(callback)
+          if (!callbackBody) {
+            return
+          }
+
+          helpers.walk(callbackBody, (effectNode) => {
+            if (effectNode.type !== "CallExpression") {
+              return
+            }
+
+            const callee = effectNode.callee
+            if (!isIdentifier(callee)) {
+              return
+            }
+
+            const stateName = setterToState.get(callee.name)
+            if (!stateName || !depNames.has(stateName)) {
+              return
+            }
+
+            const [firstArgument] = Array.isArray(effectNode.arguments) ? effectNode.arguments : []
+            if (!firstArgument || !referencesIdentifier(firstArgument, stateName, helpers)) {
+              return
+            }
+
+            findings.push({
+              start: effectNode.start as number,
+              end: effectNode.end as number,
+              message: `Avoid deriving state in effects via ${callee.name} from the dependency state "${stateName}".`,
+            })
+          })
+        })
+      })
+
+      return findings
+    },
+  },
+]