@ox0/guards 0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ox0/guards",
+  "version": "0.1.0",
+  "bin": {
+    "ox0-guards": "./bin/ox0-guards.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "bin"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "oxc-parser": "^0.134.0",
+    "tsx": "^4.19.0"
+  },
+  "scripts": {
+    "build": "rslib build -c ../../rslib.config.ts",
+    "check": "node ./bin/ox0-guards.js --project ../..",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "oxlint .",
+    "test": "vitest run"
+  }
+}

package/src/ast-helpers.ts

@@ -0,0 +1,168 @@
+function isNode(value: unknown): value is Record<string, unknown> {
+  return (
+    Boolean(value) &&
+    typeof value === "object" &&
+    typeof (value as { type?: unknown }).type === "string"
+  )
+}
+
+function walkChild(
+  child: unknown,
+  visitor: (node: Record<string, unknown>, parent: Record<string, unknown> | null) => void,
+  parent: Record<string, unknown> | null,
+) {
+  if (Array.isArray(child)) {
+    for (const entry of child) {
+      walk(entry, visitor, parent)
+    }
+    return
+  }
+
+  walk(child, visitor, parent)
+}
+
+function walk(
+  node: unknown,
+  visitor: (node: Record<string, unknown>, parent: Record<string, unknown> | null) => void,
+  parent: Record<string, unknown> | null = null,
+) {
+  if (!isNode(node)) {
+    return
+  }
+
+  visitor(node, parent)
+
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "parent") {
+      continue
+    }
+
+    walkChild(value, visitor, node)
+  }
+}
+
+function getIdentifierName(node: unknown): string | null {
+  if (!isNode(node)) {
+    return null
+  }
+
+  if (node.type === "Identifier" || node.type === "JSXIdentifier") {
+    return typeof node.name === "string" ? node.name : null
+  }
+
+  return null
+}
+
+function getCalleeName(node: unknown): string | null {
+  if (!isNode(node)) {
+    return null
+  }
+
+  if (node.type === "Identifier") {
+    return typeof node.name === "string" ? node.name : null
+  }
+
+  if (node.type === "MemberExpression") {
+    const objectName = getCalleeName(node.object)
+    const propertyName = getIdentifierName(node.property)
+    return objectName && propertyName ? `${objectName}.${propertyName}` : null
+  }
+
+  return null
+}
+
+function getJsxElementName(node: unknown): string | null {
+  if (!isNode(node)) {
+    return null
+  }
+
+  if (node.type === "JSXIdentifier") {
+    return typeof node.name === "string" ? node.name : null
+  }
+
+  if (node.type === "JSXMemberExpression") {
+    const objectName = getJsxElementName(node.object)
+    const propertyName = getJsxElementName(node.property)
+    return objectName && propertyName ? `${objectName}.${propertyName}` : null
+  }
+
+  return null
+}
+
+function getStringLiteralValue(node: unknown): string | null {
+  if (!isNode(node)) {
+    return null
+  }
+
+  if (node.type === "Literal" && typeof node.value === "string") {
+    return node.value
+  }
+
+  if (
+    node.type === "TemplateLiteral" &&
+    Array.isArray(node.expressions) &&
+    node.expressions.length === 0
+  ) {
+    const quasis = Array.isArray(node.quasis) ? node.quasis : []
+    return quasis
+      .map((quasi) => {
+        if (!isNode(quasi)) {
+          return ""
+        }
+
+        const value = quasi.value
+        if (
+          !value ||
+          typeof value !== "object" ||
+          typeof (value as { cooked?: unknown }).cooked !== "string"
+        ) {
+          return ""
+        }
+
+        return (value as { cooked: string }).cooked
+      })
+      .join("")
+  }
+
+  return null
+}
+
+function isFunctionLike(node: unknown): boolean {
+  return (
+    isNode(node) &&
+    (node.type === "FunctionDeclaration" ||
+      node.type === "FunctionExpression" ||
+      node.type === "ArrowFunctionExpression")
+  )
+}
+
+function getFunctionName(node: unknown, parent: unknown): string | null {
+  if (!isNode(node)) {
+    return null
+  }
+
+  if ("id" in node && isNode(node.id) && typeof node.id.name === "string") {
+    return node.id.name
+  }
+
+  if (
+    isNode(parent) &&
+    parent.type === "VariableDeclarator" &&
+    isNode(parent.id) &&
+    parent.id.type === "Identifier" &&
+    typeof parent.id.name === "string"
+  ) {
+    return parent.id.name
+  }
+
+  return null
+}
+
+export const GUARD_HELPERS = {
+  walk,
+  getCalleeName,
+  getJsxElementName,
+  getStringLiteralValue,
+  isFunctionLike,
+  getFunctionName,
+}

package/src/check.ts

@@ -0,0 +1,429 @@
+import fs from "node:fs"
+import path from "node:path"
+
+import { parseSync } from "oxc-parser"
+
+import { GUARD_HELPERS } from "./ast-helpers"
+import { GUARD_FACTORIES } from "./guards"
+import type {
+  GuardFinding,
+  GuardRawFinding,
+  GuardRuleDefinition,
+  GuardRuleId,
+  RunGuardsOptions,
+  RunGuardsResult,
+} from "./types"
+
+const INTERNAL_INVALID_DISABLE_RULE = "guard/invalid-disable-comment" as const
+const INTERNAL_PARSE_ERROR_RULE = "guard/parse-error" as const
+const SCRIPT_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".mts", ".cts"])
+const EXCLUDED_DIRECTORIES = new Set([
+  ".git",
+  ".idea",
+  ".next",
+  ".rspress",
+  ".turbo",
+  "coverage",
+  "dist",
+  "doc_build",
+  "node_modules",
+])
+
+type Suppression = {
+  ruleId: GuardRuleId
+  startLine: number
+  endLine: number
+}
+
+type InvalidDisable = {
+  line: number
+  column: number
+  message: string
+}
+
+type ParsedDisableDirective = {
+  type: "next-line" | "start" | "end"
+  ruleId: string
+  rationale: string
+  line: number
+  column: number
+}
+
+function isScriptFile(filePath: string): boolean {
+  return SCRIPT_EXTENSIONS.has(path.extname(filePath))
+}
+
+function shouldExcludeDirectory(relativeDirPath: string): boolean {
+  return relativeDirPath
+    .split(path.sep)
+    .some((segment) => segment.length > 0 && EXCLUDED_DIRECTORIES.has(segment))
+}
+
+function collectProjectFiles(projectRoot: string, allowedExtensions: Set<string>): string[] {
+  const files: string[] = []
+
+  function walkDirectory(currentDir: string): void {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name)
+      const relativePath = path.relative(projectRoot, fullPath)
+
+      if (entry.isDirectory()) {
+        if (shouldExcludeDirectory(relativePath)) {
+          continue
+        }
+
+        walkDirectory(fullPath)
+        continue
+      }
+
+      if (allowedExtensions.has(path.extname(entry.name))) {
+        files.push(fullPath)
+      }
+    }
+  }
+
+  walkDirectory(projectRoot)
+  return files.toSorted()
+}
+
+function createLineStarts(source: string): number[] {
+  const starts = [0]
+
+  for (let index = 0; index < source.length; index += 1) {
+    if (source[index] === "\n") {
+      starts.push(index + 1)
+    }
+  }
+
+  return starts
+}
+
+function getLocationFromOffset(lineStarts: number[], offset: number) {
+  let low = 0
+  let high = lineStarts.length - 1
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2)
+    const start = lineStarts[mid]
+    const nextStart = lineStarts[mid + 1] ?? Number.POSITIVE_INFINITY
+
+    if (offset < start) {
+      high = mid - 1
+    } else if (offset >= nextStart) {
+      low = mid + 1
+    } else {
+      return {
+        line: mid + 1,
+        column: offset - lineStarts[mid] + 1,
+      }
+    }
+  }
+
+  return {
+    line: 1,
+    column: 1,
+  }
+}
+
+function buildFinding(
+  ruleId: GuardRuleId,
+  rawFinding: GuardRawFinding,
+  filePath: string,
+  relativeFilePath: string,
+  lineStarts: number[],
+): GuardFinding {
+  const startLocation = getLocationFromOffset(lineStarts, rawFinding.start)
+  const endLocation = getLocationFromOffset(lineStarts, rawFinding.end ?? rawFinding.start)
+
+  return {
+    ruleId,
+    message: rawFinding.message,
+    filePath,
+    relativeFilePath,
+    line: startLocation.line,
+    column: startLocation.column,
+    endLine: endLocation.line,
+    endColumn: endLocation.column,
+    severity: "error",
+  }
+}
+
+function parseDisableDirective(line: string, lineNumber: number): ParsedDisableDirective | null {
+  const match = line.match(
+    /^\s*\/\/\s*guard-disable-(next-line|start|end)\s+(\S+)(?:\s+(.*\S))?\s*$/,
+  )
+
+  if (!match) {
+    return null
+  }
+
+  return {
+    type: match[1] as ParsedDisableDirective["type"],
+    ruleId: match[2],
+    rationale: match[3] ?? "",
+    line: lineNumber,
+    column: line.indexOf("//") + 1,
+  }
+}
+
+function parseSuppressions(source: string, knownRuleIds: Set<GuardRuleId>) {
+  const suppressions: Suppression[] = []
+  const invalid: InvalidDisable[] = []
+  const openBlocks = new Map<string, ParsedDisableDirective>()
+  const lines = source.split(/\r?\n/)
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const lineNumber = index + 1
+    const directive = parseDisableDirective(lines[index], lineNumber)
+
+    if (!directive) {
+      continue
+    }
+
+    if (!knownRuleIds.has(directive.ruleId as GuardRuleId)) {
+      invalid.push({
+        line: directive.line,
+        column: directive.column,
+        message: `Disable comment references unknown rule "${directive.ruleId}".`,
+      })
+      continue
+    }
+
+    if (
+      (directive.type === "next-line" || directive.type === "start") &&
+      directive.rationale.trim() === ""
+    ) {
+      invalid.push({
+        line: directive.line,
+        column: directive.column,
+        message: `Disable comment for ${directive.ruleId} must include a rationale.`,
+      })
+      continue
+    }
+
+    if (directive.type === "next-line") {
+      suppressions.push({
+        ruleId: directive.ruleId as GuardRuleId,
+        startLine: directive.line + 1,
+        endLine: directive.line + 1,
+      })
+      continue
+    }
+
+    if (directive.type === "start") {
+      openBlocks.set(directive.ruleId, directive)
+      continue
+    }
+
+    const startDirective = openBlocks.get(directive.ruleId)
+    if (!startDirective) {
+      invalid.push({
+        line: directive.line,
+        column: directive.column,
+        message: `guard-disable-end for ${directive.ruleId} has no matching start.`,
+      })
+      continue
+    }
+
+    suppressions.push({
+      ruleId: directive.ruleId as GuardRuleId,
+      startLine: startDirective.line + 1,
+      endLine: Math.max(startDirective.line + 1, directive.line - 1),
+    })
+    openBlocks.delete(directive.ruleId)
+  }
+
+  for (const directive of openBlocks.values()) {
+    invalid.push({
+      line: directive.line,
+      column: directive.column,
+      message: `guard-disable-start for ${directive.ruleId} is missing a matching end.`,
+    })
+  }
+
+  return { suppressions, invalid }
+}
+
+function isSuppressed(finding: GuardFinding, suppressions: Suppression[]): boolean {
+  return suppressions.some(
+    (suppression) =>
+      suppression.ruleId === finding.ruleId &&
+      finding.line >= suppression.startLine &&
+      finding.line <= suppression.endLine,
+  )
+}
+
+function sortFindings(findings: GuardFinding[]): void {
+  const sortedFindings = findings.toSorted((left, right) => {
+    if (left.relativeFilePath !== right.relativeFilePath) {
+      return left.relativeFilePath.localeCompare(right.relativeFilePath)
+    }
+
+    if (left.line !== right.line) {
+      return left.line - right.line
+    }
+
+    if (left.column !== right.column) {
+      return left.column - right.column
+    }
+
+    return left.ruleId.localeCompare(right.ruleId)
+  })
+
+  findings.splice(0, findings.length, ...sortedFindings)
+}
+
+function getRuleRegistry(): Map<GuardRuleId, GuardRuleDefinition> {
+  const registry = new Map<GuardRuleId, GuardRuleDefinition>()
+
+  for (const factory of GUARD_FACTORIES) {
+    const [ruleId, definition] = factory()
+    registry.set(ruleId, definition)
+  }
+
+  return registry
+}
+
+export function listGuardRuleIds(): GuardRuleId[] {
+  return [...getRuleRegistry().keys()].toSorted()
+}
+
+export function runGuards(options: RunGuardsOptions): RunGuardsResult {
+  const projectRoot = path.resolve(options.cwd ?? process.cwd(), options.projectRoot)
+  const registry = getRuleRegistry()
+  const knownRuleIds = new Set<GuardRuleId>([
+    ...registry.keys(),
+    INTERNAL_INVALID_DISABLE_RULE,
+    INTERNAL_PARSE_ERROR_RULE,
+  ])
+  const requestedRuleIds = options.requestedRules?.length
+    ? options.requestedRules.map((ruleId) => ruleId as GuardRuleId)
+    : [...registry.keys()]
+
+  for (const ruleId of requestedRuleIds) {
+    if (!registry.has(ruleId)) {
+      throw new Error(`Unknown guard rule: ${ruleId}`)
+    }
+  }
+
+  const selectedEntries = [...registry.entries()].filter(([ruleId]) =>
+    requestedRuleIds.includes(ruleId),
+  )
+  const allowedExtensions = new Set<string>()
+
+  for (const [, definition] of selectedEntries) {
+    for (const extension of definition.fileExtensions) {
+      allowedExtensions.add(extension)
+    }
+  }
+
+  const files = collectProjectFiles(projectRoot, allowedExtensions)
+  const findings: GuardFinding[] = []
+
+  for (const filePath of files) {
+    const relativeFilePath = path.relative(projectRoot, filePath)
+    const source = fs.readFileSync(filePath, "utf8")
+    const lineStarts = createLineStarts(source)
+    const { suppressions, invalid } = parseSuppressions(source, knownRuleIds)
+
+    for (const invalidFinding of invalid) {
+      findings.push({
+        ruleId: INTERNAL_INVALID_DISABLE_RULE,
+        message: invalidFinding.message,
+        filePath,
+        relativeFilePath,
+        line: invalidFinding.line,
+        column: invalidFinding.column,
+        endLine: invalidFinding.line,
+        endColumn: invalidFinding.column,
+        severity: "error",
+      })
+    }
+
+    const extension = path.extname(filePath)
+    const applicableRules = selectedEntries.filter(
+      ([, definition]) =>
+        definition.fileExtensions.includes(extension) && definition.tokenPrefilter(source),
+    )
+
+    if (applicableRules.length === 0) {
+      continue
+    }
+
+    for (const [ruleId, definition] of applicableRules.filter(
+      ([, candidate]) => typeof candidate.evaluateText === "function",
+    )) {
+      const rawFindings =
+        definition.evaluateText?.({
+          ruleId,
+          projectRoot,
+          filePath,
+          relativeFilePath,
+          source,
+        }) ?? []
+
+      for (const rawFinding of rawFindings) {
+        const finding = buildFinding(ruleId, rawFinding, filePath, relativeFilePath, lineStarts)
+        if (!isSuppressed(finding, suppressions)) {
+          findings.push(finding)
+        }
+      }
+    }
+
+    const astRules = applicableRules.filter(
+      ([, definition]) => typeof definition.evaluate === "function" && isScriptFile(filePath),
+    )
+
+    if (astRules.length === 0) {
+      continue
+    }
+
+    const parseResult = parseSync(relativeFilePath, source, { astType: "ts" })
+
+    if (Array.isArray(parseResult.errors) && parseResult.errors.length > 0) {
+      for (const error of parseResult.errors) {
+        const start = "start" in error && typeof error.start === "number" ? error.start : 0
+        findings.push(
+          buildFinding(
+            INTERNAL_PARSE_ERROR_RULE,
+            {
+              start,
+              end: start,
+              message: `Parse error: ${String(error.message ?? "unknown parser error")}`,
+            },
+            filePath,
+            relativeFilePath,
+            lineStarts,
+          ),
+        )
+      }
+      continue
+    }
+
+    for (const [ruleId, definition] of astRules) {
+      const rawFindings =
+        definition.evaluate?.({
+          ruleId,
+          projectRoot,
+          filePath,
+          relativeFilePath,
+          source,
+          helpers: GUARD_HELPERS,
+          program: parseResult.program as unknown as Record<string, unknown>,
+          comments: (parseResult.comments as unknown as Array<Record<string, unknown>>) ?? [],
+        }) ?? []
+
+      for (const rawFinding of rawFindings) {
+        const finding = buildFinding(ruleId, rawFinding, filePath, relativeFilePath, lineStarts)
+        if (!isSuppressed(finding, suppressions)) {
+          findings.push(finding)
+        }
+      }
+    }
+  }
+
+  sortFindings(findings)
+  return { findings, ruleIds: listGuardRuleIds() }
+}