|
| 1 | +import { readFileSync, readdirSync } from "node:fs"; |
| 2 | +import { join, relative, resolve } from "node:path"; |
| 3 | +import { fileURLToPath, pathToFileURL } from "node:url"; |
| 4 | + |
| 5 | +export const COMPONENTS = ["RollingOut", "PrivateBeta"]; |
| 6 | + |
| 7 | +const TAG_PATTERN = new RegExp(`<(${COMPONENTS.join("|")})\\b`, "g"); |
| 8 | +const FEATURE_FLAG_MODULE = "apps/webapp/app/v3/featureFlags.ts"; |
| 9 | +const ENV_MODULE = "apps/webapp/app/env.server.ts"; |
| 10 | + |
| 11 | +export function extractFeatureStatusTags(source, file) { |
| 12 | + const tags = []; |
| 13 | + let inFence = false; |
| 14 | + |
| 15 | + source.split("\n").forEach((text, index) => { |
| 16 | + if (text.trimStart().startsWith("```")) { |
| 17 | + inFence = !inFence; |
| 18 | + return; |
| 19 | + } |
| 20 | + if (inFence) return; |
| 21 | + |
| 22 | + for (const match of text.matchAll(TAG_PATTERN)) { |
| 23 | + tags.push(parseTag(text.slice(match.index), match[1], file, index + 1)); |
| 24 | + } |
| 25 | + }); |
| 26 | + |
| 27 | + return tags; |
| 28 | +} |
| 29 | + |
| 30 | +function parseTag(text, component, file, line) { |
| 31 | + const end = text.indexOf("/>"); |
| 32 | + if (end === -1) { |
| 33 | + return { file, line, component, error: "must be a single-line, self-closing tag" }; |
| 34 | + } |
| 35 | + |
| 36 | + const body = text.slice(component.length + 1, end); |
| 37 | + if (body.includes("{")) { |
| 38 | + return { file, line, component, error: "attributes must be plain string literals" }; |
| 39 | + } |
| 40 | + |
| 41 | + const flag = body.match(/\bflag="([^"]*)"/)?.[1]; |
| 42 | + return { file, line, component, flag }; |
| 43 | +} |
| 44 | + |
| 45 | +export function extractFeatureFlagKeys(source) { |
| 46 | + const start = source.indexOf("export const FEATURE_FLAG = {"); |
| 47 | + if (start === -1) return new Set(); |
| 48 | + |
| 49 | + const rest = source.slice(start); |
| 50 | + const end = rest.search(/^\}( as const)?;/m); |
| 51 | + if (end === -1) return new Set(); |
| 52 | + |
| 53 | + const block = rest.slice(0, end); |
| 54 | + const keys = [...block.matchAll(/^\s*(\w+):\s*"(\w+)",?\s*$/gm)] |
| 55 | + .filter(([, key, value]) => key === value) |
| 56 | + .map(([, key]) => key); |
| 57 | + return new Set(keys); |
| 58 | +} |
| 59 | + |
| 60 | +export function extractEnvKeys(source) { |
| 61 | + return new Set([...source.matchAll(/^\s+([A-Z][A-Z0-9_]*):\s/gm)].map(([, key]) => key)); |
| 62 | +} |
| 63 | + |
| 64 | +export function findProblems(tags, flagKeys, envKeys) { |
| 65 | + const problems = []; |
| 66 | + |
| 67 | + for (const tag of tags) { |
| 68 | + const at = `${tag.file}:${tag.line}`; |
| 69 | + const usage = `<${tag.component} flag="..." />`; |
| 70 | + |
| 71 | + if (tag.error) { |
| 72 | + problems.push({ |
| 73 | + at, |
| 74 | + message: `<${tag.component}> ${tag.error}`, |
| 75 | + fix: `write it as ${usage}`, |
| 76 | + }); |
| 77 | + continue; |
| 78 | + } |
| 79 | + |
| 80 | + if (!tag.flag) { |
| 81 | + problems.push({ |
| 82 | + at, |
| 83 | + message: `<${tag.component}> is missing flag`, |
| 84 | + fix: `add flag="<key in ${FEATURE_FLAG_MODULE}>" or flag="env:<NAME in ${ENV_MODULE}>"`, |
| 85 | + }); |
| 86 | + continue; |
| 87 | + } |
| 88 | + |
| 89 | + if (tag.flag.startsWith("env:")) { |
| 90 | + const name = tag.flag.slice("env:".length); |
| 91 | + if (!envKeys.has(name)) { |
| 92 | + problems.push({ |
| 93 | + at, |
| 94 | + message: `env var "${name}" isn't declared in ${ENV_MODULE}`, |
| 95 | + fix: "fix the name, or remove the callout if the env gate was removed", |
| 96 | + }); |
| 97 | + } |
| 98 | + continue; |
| 99 | + } |
| 100 | + |
| 101 | + if (!flagKeys.has(tag.flag)) { |
| 102 | + problems.push({ |
| 103 | + at, |
| 104 | + message: `flag "${tag.flag}" isn't in ${FEATURE_FLAG_MODULE}`, |
| 105 | + fix: "fix the key, or remove the callout if the flag was removed (the feature is generally available)", |
| 106 | + }); |
| 107 | + } |
| 108 | + } |
| 109 | + |
| 110 | + return problems; |
| 111 | +} |
| 112 | + |
| 113 | +function main() { |
| 114 | + const root = resolve(fileURLToPath(import.meta.url), "../.."); |
| 115 | + const docsDir = join(root, "docs"); |
| 116 | + |
| 117 | + const flagKeys = extractFeatureFlagKeys(readFileSync(join(root, FEATURE_FLAG_MODULE), "utf8")); |
| 118 | + const envKeys = extractEnvKeys(readFileSync(join(root, ENV_MODULE), "utf8")); |
| 119 | + if (flagKeys.size === 0 || envKeys.size === 0) { |
| 120 | + console.error( |
| 121 | + `Found ${flagKeys.size} feature flags and ${envKeys.size} env vars. The file format probably changed; update scripts/check-docs-feature-status.mjs.` |
| 122 | + ); |
| 123 | + process.exit(1); |
| 124 | + } |
| 125 | + |
| 126 | + const files = readdirSync(docsDir, { recursive: true }).filter((file) => file.endsWith(".mdx")); |
| 127 | + const tags = files.flatMap((file) => |
| 128 | + extractFeatureStatusTags( |
| 129 | + readFileSync(join(docsDir, file), "utf8"), |
| 130 | + relative(root, join(docsDir, file)) |
| 131 | + ) |
| 132 | + ); |
| 133 | + |
| 134 | + const problems = findProblems(tags, flagKeys, envKeys); |
| 135 | + if (problems.length === 0) { |
| 136 | + console.log(`Checked ${tags.length} feature status callouts in ${files.length} docs pages.`); |
| 137 | + return; |
| 138 | + } |
| 139 | + |
| 140 | + for (const { at, message, fix } of problems) { |
| 141 | + console.error(`${at} ${message}\n fix: ${fix}`); |
| 142 | + } |
| 143 | + console.error(`\n${problems.length} feature status callout problem(s) found.`); |
| 144 | + process.exit(1); |
| 145 | +} |
| 146 | + |
| 147 | +if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { |
| 148 | + main(); |
| 149 | +} |
0 commit comments