openclaw/scripts/check-deprecated-jsdoc.mts

#!/usr/bin/env node
// Checks deprecated JSDoc blocks for required migration details.
import fs from "node:fs";
import path from "node:path";
import * as ts from "typescript/unstable/ast";
import { createNativeTypeScriptParser } from "./lib/native-typescript.mts";
import { resolveRepoRoot } from "./lib/repo-root.mjs";
import { toLine } from "./lib/ts-guard-utils.mts";

const repoRoot = resolveRepoRoot(import.meta.url);
const SCAN_ROOTS = ["src", "extensions", "packages"];
const SOURCE_FILE_RE = /\.(?:ts|tsx)$/;
const SKIP_PATH_RE =
  /(?:^|\/)(?:node_modules|dist|build|protocol-generated)(?:\/|$)|(?:\.test|\.spec|\.e2e|\.generated)\.tsx?$/;
const DEPRECATED_SURFACE_COMMENT_RE =
  /^(?:back-compat alias|backward-compatible alias(?:es)?|deprecated alias|legacy alias|legacy field|legacy:\s|kept for compatibility with existing imports|keep the legacy helper name exported)\b/i;

function walk(dir: string, files: string[] = []) {
  if (!fs.existsSync(dir)) {
    return files;
  }
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const filePath = path.join(dir, entry.name);
    const relativePath = path.relative(repoRoot, filePath).replaceAll(path.sep, "/");
    if (SKIP_PATH_RE.test(relativePath)) {
      continue;
    }
    if (entry.isDirectory()) {
      walk(filePath, files);
    } else if (SOURCE_FILE_RE.test(entry.name)) {
      files.push(filePath);
    }
  }
  return files;
}

function leadingCommentText(sourceFile: ts.SourceFile, node: ts.Node) {
  return (ts.getLeadingCommentRanges(sourceFile.text, node.pos) ?? [])
    .map((range) => sourceFile.text.slice(range.pos, range.end))
    .join("\n");
}

function normalizeCommentText(comment: string) {
  return comment
    .replace(/\/\*\*?/g, "")
    .replace(/\*\//g, "")
    .split("\n")
    .map((line) => line.replace(/^\s*(?:\*|\/\/)\s?/, "").trim())
    .filter(Boolean)
    .join(" ");
}

function isExported(node: ts.ModifiersBase) {
  return (
    node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ||
    node.parent?.kind === ts.SyntaxKind.SourceFile
  );
}

type InspectedNode =
  | ts.FunctionDeclaration
  | ts.ClassDeclaration
  | ts.InterfaceDeclaration
  | ts.TypeAliasDeclaration
  | ts.EnumDeclaration
  | ts.VariableStatement
  | ts.PropertySignatureDeclaration
  | ts.MethodSignatureDeclaration
  | ts.PropertyDeclaration
  | ts.EnumMember;
type Violation = { filePath: string; line: number; name: string };

function symbolName(node: InspectedNode) {
  const declaration = ts.isVariableStatement(node) ? node.declarationList.declarations[0] : node;
  return declaration?.name?.getText() ?? "<anonymous>";
}

function shouldInspectNode(node: ts.Node): node is InspectedNode {
  if (
    ts.isFunctionDeclaration(node) ||
    ts.isClassDeclaration(node) ||
    ts.isInterfaceDeclaration(node) ||
    ts.isTypeAliasDeclaration(node) ||
    ts.isEnumDeclaration(node) ||
    ts.isVariableStatement(node)
  ) {
    return isExported(node);
  }
  return (
    ts.isPropertySignatureDeclaration(node) ||
    ts.isMethodSignatureDeclaration(node) ||
    ts.isPropertyDeclaration(node) ||
    ts.isEnumMember(node)
  );
}

function collectViolations(filePath: string, sourceFile: ts.SourceFile) {
  const violations: Violation[] = [];

  function visit(node: ts.Node) {
    if (shouldInspectNode(node)) {
      const comment = leadingCommentText(sourceFile, node);
      const normalizedComment = normalizeCommentText(comment);
      if (
        normalizedComment &&
        DEPRECATED_SURFACE_COMMENT_RE.test(normalizedComment) &&
        !/@deprecated\b/.test(comment)
      ) {
        violations.push({
          line: toLine(sourceFile, node),
          name: symbolName(node),
          filePath: path.relative(repoRoot, filePath).replaceAll(path.sep, "/"),
        });
      }
    }
    node.forEachChild(visit);
  }

  visit(sourceFile);
  return violations;
}

function scanViolations() {
  using parser = createNativeTypeScriptParser({ cwd: repoRoot });
  const files = SCAN_ROOTS.flatMap((root) => walk(path.join(repoRoot, root)));
  const sourceFiles = parser.parseSourceFiles(
    files.map((fileName) => ({ fileName, text: fs.readFileSync(fileName, "utf8") })),
  );
  return sourceFiles.flatMap((sourceFile) => collectViolations(sourceFile.fileName, sourceFile));
}

const violations = scanViolations();

if (violations.length > 0) {
  console.error("Deprecated JSDoc guard failed:");
  for (const violation of violations) {
    console.error(`- ${violation.filePath}:${violation.line} ${violation.name}`);
  }
  console.error(
    "Add an @deprecated JSDoc tag or reword the comment if the symbol is not deprecated.",
  );
  process.exitCode = 1;
} else {
  console.log("deprecated JSDoc guard passed");
}