#!/usr/bin/env node /** * Fail when user-visible UI copy contains a Unicode em dash. * * The check covers locale values, rendered web source strings, backend mock-agent * response strings, backend shared page catalogs, and published Markdown. Historical * changelog content is intentionally excluded because the changelog is generated * release history and must remain immutable. * Comments are ignored in source files so this remains a copy check rather than * a style check for developer prose. */ import fs from "node:fs"; import path from "node:path"; import { fileURLToPath } from "node:url"; export const EM_DASH = "\u2014"; const WEB_ROOT = path.resolve(import.meta.dirname, ".."); const REPO_ROOT = path.resolve(WEB_ROOT, "..", ".."); const SOURCE_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx"]); const BACKEND_SOURCE_EXTENSIONS = new Set([".go"]); const PUBLIC_DOC_EXTENSIONS = new Set([".md", ".mdx"]); const IGNORED_DIRECTORIES = new Set(["dist", "e2e", "node_modules"]); const CODE_STATE = "code"; const LINE_COMMENT_STATE = "line-comment"; const BLOCK_COMMENT_STATE = "block-comment"; const STRING_STATE = "string"; const REGEX_START_CHARACTERS = new Set("=([{,:;!?&|+-*%^~<>".split("")); const REGEX_KEYWORDS = new Set([ "await", "case", "delete", "do", "else", "in", "instanceof", "new", "of", "return", "throw", "typeof", "void", "while", "yield", ]); export function containsEmDash(value) { return value.includes(EM_DASH) || /\\u2014/i.test(value); } function relativePath(file, root) { return path.relative(root, file).split(path.sep).join("/"); } function commentCharacter(character, state) { return character === "\n" ? { output: character, nextState: state === LINE_COMMENT_STATE ? CODE_STATE : state } : { output: " ", nextState: state }; } function consumeLineComment(source, index) { return { ...commentCharacter(source[index], LINE_COMMENT_STATE), nextIndex: index + 1 }; } function consumeBlockComment(source, index) { const closesComment = source[index] === "*" && source[index + 1] === "/"; if (closesComment) return { output: " ", nextIndex: index + 2, nextState: CODE_STATE }; return { ...commentCharacter(source[index], BLOCK_COMMENT_STATE), nextIndex: index + 1 }; } function consumeString(source, index, quote, escaped) { const character = source[index]; const closesString = !escaped && character === quote; return { output: character, nextIndex: index + 1, nextState: closesString ? CODE_STATE : STRING_STATE, nextQuote: closesString ? "" : quote, nextEscaped: closesString ? false : !escaped && character === "\\", }; } function previousToken(source, index) { let cursor = index - 1; while (cursor >= 0 && /\s/.test(source[cursor])) cursor -= 1; const end = cursor; while (cursor >= 0 && /[\w$]/.test(source[cursor])) cursor -= 1; return source.slice(cursor + 1, end + 1); } function canStartRegex(source, index) { if (source[index - 1] === "<") return false; let cursor = index - 1; while (cursor >= 0 && /\s/.test(source[cursor])) cursor -= 1; if (cursor < 0) return true; if (REGEX_START_CHARACTERS.has(source[cursor])) return true; return REGEX_KEYWORDS.has(previousToken(source, index)); } function consumeRegex(source, index) { let inCharacterClass = false; let escaped = false; for (let cursor = index + 1; cursor < source.length; cursor += 1) { const character = source[cursor]; if (escaped) { escaped = false; continue; } if (character === "\\") { escaped = true; continue; } if (character === "[") { inCharacterClass = true; continue; } if (character === "]") { inCharacterClass = false; continue; } if (character !== "/" || inCharacterClass) continue; let end = cursor + 1; while (/[a-z]/i.test(source[end] ?? "")) end += 1; return { output: source.slice(index, end).replace(/[^\n]/g, " "), nextIndex: end, nextState: CODE_STATE, }; } return { output: source[index], nextIndex: index + 1, nextState: CODE_STATE }; } function consumeCode(source, index) { const character = source[index]; const next = source[index + 1]; if (character === "/" && next === "/") { return { output: " ", nextIndex: index + 2, nextState: LINE_COMMENT_STATE }; } if (character === "/" && next === "*") { return { output: " ", nextIndex: index + 2, nextState: BLOCK_COMMENT_STATE }; } if (character === "/" && canStartRegex(source, index)) return consumeRegex(source, index); if (["'", '"', "`"].includes(character)) { return { output: character, nextIndex: index + 1, nextState: STRING_STATE, nextQuote: character, nextEscaped: false, }; } return { output: character, nextIndex: index + 1, nextState: CODE_STATE }; } const STATE_CONSUMERS = { [LINE_COMMENT_STATE]: consumeLineComment, [BLOCK_COMMENT_STATE]: consumeBlockComment, }; function consumeState(source, index, state, quote, escaped) { if (state === STRING_STATE) return consumeString(source, index, quote, escaped); return (STATE_CONSUMERS[state] ?? consumeCode)(source, index); } /** Remove comments while retaining strings and source line positions. */ export function stripCommentsPreservingStrings(source) { let output = ""; let state = CODE_STATE; let quote = ""; let escaped = false; for (let index = 0; index < source.length; ) { const consumed = consumeState(source, index, state, quote, escaped); output += consumed.output; index = consumed.nextIndex; state = consumed.nextState; quote = consumed.nextQuote ?? ""; escaped = consumed.nextEscaped ?? false; } return output; } export function findSourceViolations(source, file, root) { const cleanedSource = stripCommentsPreservingStrings(source); return cleanedSource .split("\n") .flatMap((line, index) => containsEmDash(line) ? [{ kind: "source", file: relativePath(file, root), line: index + 1 }] : [], ); } const PUBLIC_DOC_COMMENT_MARKERS = [ { start: "" }, { start: "{/*", end: "*/" }, ]; function readBacktickRun(source, index) { let end = index; while (source[end] === "`") end += 1; return source.slice(index, end); } function findBacktickRun(source, run, start) { let cursor = source.indexOf(run, start); while (cursor >= 0) { const before = source[cursor - 1]; const after = source[cursor + run.length]; if (before !== "`" && after !== "`") return cursor; cursor = source.indexOf(run, cursor + 1); } return -1; } function readFence(line) { const match = /^( {0,3})(`{3,}|~{3,})(.*)$/.exec(line); if (!match || (match[2][0] === "`" && match[3].includes("`"))) return null; return { marker: match[2][0], length: match[2].length }; } function isClosingFence(line, fence) { const match = /^( {0,3})(`{3,}|~{3,})\s*$/.exec(line); return Boolean(match && match[2][0] === fence.marker && match[2].length >= fence.length); } function findPublicDocComment(line, index) { return PUBLIC_DOC_COMMENT_MARKERS.find(({ start }) => line.startsWith(start, index)); } function maskPublicDocComment(line, index, endMarker) { const end = line.indexOf(endMarker, index); if (end < 0) { return { output: line.slice(index).replace(/[^\n]/g, " "), nextIndex: line.length, commentEnd: endMarker, closed: false, }; } const endExclusive = end + endMarker.length; return { output: line.slice(index, endExclusive).replace(/[^\n]/g, " "), nextIndex: endExclusive, commentEnd: null, closed: true, }; } function copyInlineCode(line, index, run) { const end = findBacktickRun(line, run, index); if (end < 0) { return { output: line.slice(index), nextIndex: line.length, closed: false }; } const endExclusive = end + run.length; return { output: line.slice(index, endExclusive), nextIndex: endExclusive, closed: true }; } function consumePublicDocToken(line, index, state) { if (state.commentEnd) { const consumed = maskPublicDocComment(line, index, state.commentEnd); return { ...consumed, inlineCodeRun: null, done: !consumed.closed, }; } if (state.inlineCodeRun) { const consumed = copyInlineCode(line, index, state.inlineCodeRun); return { ...consumed, commentEnd: null, inlineCodeRun: consumed.closed ? null : state.inlineCodeRun, done: !consumed.closed, }; } if (line[index] === "`") { const run = readBacktickRun(line, index); const consumed = copyInlineCode(line, index + run.length, run); return { output: line.slice(index, index + run.length) + consumed.output, nextIndex: consumed.nextIndex, commentEnd: null, inlineCodeRun: consumed.closed ? null : run, done: !consumed.closed, }; } const comment = findPublicDocComment(line, index); if (comment) { const consumed = maskPublicDocComment(line, index, comment.end); return { ...consumed, inlineCodeRun: null, done: !consumed.closed, }; } return { output: line[index], nextIndex: index + 1, commentEnd: null, inlineCodeRun: null, done: false, }; } function maskPublicDocLine(line, state) { let output = ""; let cursor = 0; let currentState = state; while (cursor < line.length) { const consumed = consumePublicDocToken(line, cursor, currentState); output += consumed.output; currentState = { commentEnd: consumed.commentEnd, inlineCodeRun: consumed.inlineCodeRun, }; if (consumed.done) return { output, ...currentState }; cursor = consumed.nextIndex; } return { output, ...currentState }; } function stripPublicDocCommentsPreservingLines(source) { let output = ""; let fence = null; let state = { commentEnd: null, inlineCodeRun: null }; for (const line of source.split("\n")) { if (fence) { output += line; if (isClosingFence(line, fence)) fence = null; } else { const openingFence = state.commentEnd || state.inlineCodeRun ? null : readFence(line); if (openingFence) { output += line; fence = openingFence; state = { commentEnd: null, inlineCodeRun: null }; } else { const masked = maskPublicDocLine(line, state); output += masked.output; state = { commentEnd: masked.commentEnd, inlineCodeRun: masked.inlineCodeRun }; } } output += "\n"; } return output.slice(0, -1); } function containsPublicDocEmDash(value) { return value.includes(EM_DASH); } export function findPublicDocViolations(source, file, root) { return stripPublicDocCommentsPreservingLines(source) .split("\n") .flatMap((line, index) => containsPublicDocEmDash(line) ? [{ kind: "public-doc", file: relativePath(file, root), line: index + 1 }] : [], ); } function listFiles(directory, predicate, files = []) { if (!fs.existsSync(directory)) return files; for (const entry of fs.readdirSync(directory, { withFileTypes: true })) { if (entry.isSymbolicLink()) continue; const file = path.join(directory, entry.name); if (entry.isDirectory()) { if (!IGNORED_DIRECTORIES.has(entry.name)) listFiles(file, predicate, files); } else if (predicate(file)) { files.push(file); } } return files; } function collectCatalogStrings(value, keyPath, file, root, violations) { if (typeof value === "string") { if (containsEmDash(value)) { violations.push({ kind: "catalog", file: relativePath(file, root), key: keyPath }); } return; } if (Array.isArray(value)) { value.forEach((item, index) => collectCatalogStrings(item, `${keyPath}[${index}]`, file, root, violations), ); return; } if (value && typeof value === "object") { for (const [key, child] of Object.entries(value)) { const childPath = keyPath ? `${keyPath}.${key}` : key; collectCatalogStrings(child, childPath, file, root, violations); } } } function scanCatalogDirectory(directory, root, violations) { for (const file of listFiles(directory, (candidate) => candidate.endsWith(".json"))) { let catalog; try { catalog = JSON.parse(fs.readFileSync(file, "utf8")); } catch (error) { throw new Error(`Unable to parse locale catalog ${file}: ${error.message}`); } collectCatalogStrings(catalog, "", file, root, violations); } } export function scanPublicDocsEmDashViolations({ docsRoot = path.join(REPO_ROOT, "docs", "public"), root = REPO_ROOT, } = {}) { const violations = []; for (const file of listFiles(docsRoot, (candidate) => PUBLIC_DOC_EXTENSIONS.has(path.extname(candidate).toLowerCase()), )) { violations.push(...findPublicDocViolations(fs.readFileSync(file, "utf8"), file, root)); } return violations; } export function scanUiEmDashViolations({ repoRoot = REPO_ROOT, webRoot = WEB_ROOT } = {}) { const violations = []; const sourceRoots = ["components", "app", "src", "hooks", "lib"].map((directory) => path.join(webRoot, directory), ); const catalogRoots = [ path.join(webRoot, "src", "locales"), path.join(repoRoot, "apps", "backend", "internal", "i18n", "locales"), ]; for (const directory of catalogRoots) scanCatalogDirectory(directory, repoRoot, violations); for (const directory of sourceRoots) { for (const file of listFiles(directory, (candidate) => { const extension = path.extname(candidate); return SOURCE_EXTENSIONS.has(extension) && !/\.(test|spec)\.[^.]+$/.test(candidate); })) { violations.push(...findSourceViolations(fs.readFileSync(file, "utf8"), file, repoRoot)); } } const backendRenderedSourceRoots = [path.join(repoRoot, "apps", "backend", "cmd", "mock-agent")]; for (const directory of backendRenderedSourceRoots) { for (const file of listFiles(directory, (candidate) => { return ( BACKEND_SOURCE_EXTENSIONS.has(path.extname(candidate)) && !candidate.endsWith("_test.go") ); })) { violations.push(...findSourceViolations(fs.readFileSync(file, "utf8"), file, repoRoot)); } } violations.push( ...scanPublicDocsEmDashViolations({ docsRoot: path.join(repoRoot, "docs", "public"), root: repoRoot, }), ); return violations; } function formatViolation(violation) { const location = violation.key ? `${violation.file}:${violation.key}` : `${violation.file}:${violation.line}`; return ` ${location} (${violation.kind})`; } function main() { const violations = scanUiEmDashViolations(); if (violations.length > 0) { console.error(`✗ ${violations.length} public-copy em dash violation(s):\n`); for (const violation of violations) console.error(formatViolation(violation)); console.error("\nUse a period, colon, comma, semicolon, or parentheses in user-facing copy."); process.exitCode = 1; return; } console.log("✓ no em dashes in public copy or locale values."); } if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { main(); }