From ca427df92452745332e159696b676e146b935844 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Tue, 28 Apr 2026 23:56:41 -0700 Subject: [PATCH] test(scripts): guard deprecated alias jsdoc --- package.json | 3 +- scripts/check-deprecated-jsdoc.mjs | 131 +++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+), 1 deletion(-) create mode 100644 scripts/check-deprecated-jsdoc.mjs diff --git a/package.json b/package.json index d12340b4b71..52bd8315a93 100644 --- a/package.json +++ b/package.json @@ -1267,12 +1267,13 @@ "canvas:a2ui:bundle": "node scripts/bundle-a2ui.mjs", "changed:lanes": "node scripts/changed-lanes.mjs", "check": "node scripts/check.mjs", - "check:architecture": "pnpm check:import-cycles && pnpm check:madge-import-cycles && pnpm check:deprecated-internal-config-api", + "check:architecture": "pnpm check:import-cycles && pnpm check:madge-import-cycles && pnpm check:deprecated-internal-config-api && pnpm check:deprecated-jsdoc", "check:base-config-schema": "node --import tsx scripts/generate-base-config-schema.ts --check", "check:bundled-channel-config-metadata": "node --import tsx scripts/generate-bundled-channel-config-metadata.ts --check", "check:changed": "node scripts/check-changed.mjs", "check:changelog-attributions": "node scripts/check-changelog-attributions.mjs", "check:deprecated-internal-config-api": "node scripts/check-deprecated-internal-config-api.mjs", + "check:deprecated-jsdoc": "node scripts/check-deprecated-jsdoc.mjs", "check:docs": "pnpm format:docs:check && pnpm lint:docs && pnpm docs:check-mdx && pnpm docs:check-i18n-glossary && pnpm docs:check-links", "check:host-env-policy:swift": "node scripts/generate-host-env-security-policy-swift.mjs --check", "check:import-cycles": "node --import tsx scripts/check-import-cycles.ts", diff --git a/scripts/check-deprecated-jsdoc.mjs b/scripts/check-deprecated-jsdoc.mjs new file mode 100644 index 00000000000..96bd204f735 --- /dev/null +++ b/scripts/check-deprecated-jsdoc.mjs @@ -0,0 +1,131 @@ +#!/usr/bin/env node +import fs from "node:fs"; +import { createRequire } from "node:module"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; + +const require = createRequire(import.meta.url); +const ts = require("typescript"); + +const repoRoot = path.resolve(path.dirname(fileURLToPath(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, files = []) { + 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, node) { + return (ts.getLeadingCommentRanges(sourceFile.text, node.pos) ?? []) + .map((range) => sourceFile.text.slice(range.pos, range.end)) + .join("\n"); +} + +function normalizeCommentText(comment) { + return comment + .replace(/\/\*\*?/g, "") + .replace(/\*\//g, "") + .split("\n") + .map((line) => line.replace(/^\s*(?:\*|\/\/)\s?/, "").trim()) + .filter(Boolean) + .join(" "); +} + +function lineOf(sourceFile, node) { + return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1; +} + +function isExported(node) { + return ( + node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) || + node.parent?.kind === ts.SyntaxKind.SourceFile + ); +} + +function symbolName(node) { + const declaration = node.declarationList?.declarations?.[0] ?? node; + return declaration.name?.getText?.() ?? ""; +} + +function shouldInspectNode(node) { + if ( + ts.isFunctionDeclaration(node) || + ts.isClassDeclaration(node) || + ts.isInterfaceDeclaration(node) || + ts.isTypeAliasDeclaration(node) || + ts.isEnumDeclaration(node) || + ts.isVariableStatement(node) + ) { + return isExported(node); + } + return ( + ts.isPropertySignature(node) || + ts.isMethodSignature(node) || + ts.isPropertyDeclaration(node) || + ts.isEnumMember(node) + ); +} + +function collectViolations(filePath) { + const sourceText = fs.readFileSync(filePath, "utf8"); + const sourceFile = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true); + const violations = []; + + function visit(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: lineOf(sourceFile, node), + name: symbolName(node), + filePath: path.relative(repoRoot, filePath).replaceAll(path.sep, "/"), + }); + } + } + ts.forEachChild(node, visit); + } + + visit(sourceFile); + return violations; +} + +const violations = SCAN_ROOTS.flatMap((root) => + walk(path.join(repoRoot, root)).flatMap(collectViolations), +); + +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"); +}