The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
feat(docs): gate MDX docs on Crowdin-safe placeholders (#24540)
Félix Malfait9618231dfc8d
diff --git a/.github/workflows/ci-docs.yaml b/.github/workflows/ci-docs.yamlindex 0c5d28e5629..ade8b2fd9f9 100644--- a/.github/workflows/ci-docs.yaml+++ b/.github/workflows/ci-docs.yaml@@ -39,3 +39,5 @@ jobs:- name: Docs / Lintrun: npx nx lint twenty-docs+ - name: Docs / Test+ run: npx nx test twenty-docsdiff --git a/packages/twenty-docs/package.json b/packages/twenty-docs/package.jsonindex 84ff14e3ffc..92460290d92 100644--- a/packages/twenty-docs/package.json+++ b/packages/twenty-docs/package.json@@ -14,7 +14,9 @@"mintlify": "^4.2.594"},"devDependencies": {- "twenty-shared": "workspace:*"+ "tsx": "^4.19.3",+ "twenty-shared": "workspace:*",+ "vitest": "^4.1.0"},"engines": {"node": "^24.5.0",diff --git a/packages/twenty-docs/project.json b/packages/twenty-docs/project.jsonindex b3d7b63bfec..91b15ce0875 100644--- a/packages/twenty-docs/project.json+++ b/packages/twenty-docs/project.json@@ -19,7 +19,18 @@"command": "mintlify validate"}},- "lint": {},+ "lint": {+ "executor": "nx:run-commands",+ "cache": true,+ "options": {+ "cwd": "{projectRoot}",+ "commands": [+ "npx oxlint -c .oxlintrc.json .",+ "npx tsx scripts/lint-mdx.ts"+ ],+ "parallel": false+ }+ },"fmt": {"executor": "nx:run-commands","cache": true,@@ -33,6 +44,12 @@"command": "prettier . --write --cache --cache-location ../../.cache/prettier/{projectRoot} --cache-strategy metadata"}}+ },+ "test": {+ "executor": "nx:run-commands",+ "options": {+ "command": "npx vitest run --config {projectRoot}/vitest.config.mts"+ }}}}diff --git a/packages/twenty-docs/scripts/__tests__/lint-mdx.spec.ts b/packages/twenty-docs/scripts/__tests__/lint-mdx.spec.tsnew file mode 100644index 00000000000..8083b608b5c--- /dev/null+++ b/packages/twenty-docs/scripts/__tests__/lint-mdx.spec.ts@@ -0,0 +1,128 @@+import { describe, expect, it } from 'vitest';++import { findAngleBracketPlaceholders } from '../lint-mdx';++describe('findAngleBracketPlaceholders', () => {+ it('flags a placeholder in prose', () => {+ const violations = findAngleBracketPlaceholders(+ 'Set the header to <your-api-key> before calling.',+ );++ expect(violations).toEqual([+ { line: 1, column: 19, text: '<your-api-key>', name: 'your-api-key' },+ ]);+ });++ it('reports the line and column of a placeholder further down the page', () => {+ const violations = findAngleBracketPlaceholders(+ 'intro\n\nuse <workspace-id> here',+ );++ expect(violations).toEqual([+ { line: 3, column: 5, text: '<workspace-id>', name: 'workspace-id' },+ ]);+ });++ it('allows HTML elements', () => {+ expect(+ findAngleBracketPlaceholders('press <kbd>K</kbd> to search'),+ ).toEqual([]);+ });++ it('allows closing tags', () => {+ expect(findAngleBracketPlaceholders('<details>x</details>')).toEqual([]);+ });++ it('ignores placeholders inside a fenced code block', () => {+ expect(+ findAngleBracketPlaceholders(+ 'before\n\n```bash\ncurl -H "key: <token>"\n```\n\nafter',+ ),+ ).toEqual([]);+ });++ it('ignores placeholders inside inline code', () => {+ expect(findAngleBracketPlaceholders('run `deploy <env>` first')).toEqual(+ [],+ );+ });++ it('still flags a placeholder after a closed inline code span', () => {+ const violations = findAngleBracketPlaceholders(+ 'run `deploy` against <env> now',+ );++ expect(violations).toHaveLength(1);+ expect(violations[0].name).toBe('env');+ });++ it('flags an HTML element name used as a host placeholder', () => {+ const violations = findAngleBracketPlaceholders(+ 'open https://<code>.twenty.com',+ );++ expect(violations).toHaveLength(1);+ expect(violations[0].name).toBe('code');+ });++ it('flags a placeholder inside a path segment', () => {+ const violations = findAngleBracketPlaceholders(+ 'edit packages/<package-name>/README.md',+ );++ expect(violations).toHaveLength(1);+ expect(violations[0].name).toBe('package-name');+ });++ it('does not flag single letter or capitalised tags', () => {+ expect(+ findAngleBracketPlaceholders('<a>link</a> and <Card>body</Card>'),+ ).toEqual([]);+ });++ it('reports every placeholder on a line', () => {+ const violations = findAngleBracketPlaceholders(+ '<first-id> and <second-id>',+ );++ expect(violations.map((violation) => violation.name)).toEqual([+ 'first-id',+ 'second-id',+ ]);+ });+ it('is not blinded by an unpaired backtick earlier in the file', () => {+ const violations = findAngleBracketPlaceholders(+ 'a stray ` backtick\n\nthen use <workspace-id> here',+ );++ expect(violations).toHaveLength(1);+ expect(violations[0].name).toBe('workspace-id');+ });++ it('pairs backtick runs by length', () => {+ expect(+ findAngleBracketPlaceholders('``code with ` tick and <env>``'),+ ).toEqual([]);+ });++ it('does not treat a backtick on a previous line as opening a span', () => {+ const violations = findAngleBracketPlaceholders(+ 'ends with a tick `\nnext line has <api-key>',+ );++ expect(violations).toHaveLength(1);+ expect(violations[0].name).toBe('api-key');+ });++ it('keeps a four-backtick block that shows a triple-backtick example as code', () => {+ expect(+ findAngleBracketPlaceholders('````md\n```\n<token>\n```\n````'),+ ).toEqual([]);+ });++ it('closes a block on a longer fence than the one that opened it', () => {+ expect(findAngleBracketPlaceholders('```ini\nKEY=<value>\n````')).toEqual(+ [],+ );+ });+});diff --git a/packages/twenty-docs/scripts/lint-mdx.ts b/packages/twenty-docs/scripts/lint-mdx.tsnew file mode 100644index 00000000000..ff78f5fe981--- /dev/null+++ b/packages/twenty-docs/scripts/lint-mdx.ts@@ -0,0 +1,266 @@+import fs from 'fs';+import path from 'path';++// Crowdin parses `<foo>` in prose as a tag rather than literal text, so an angle+// bracket placeholder is either dropped or mangled in every translated page.+// Curly braces `{foo}` survive the round trip.++const DOCS_ROOT = path.resolve(__dirname, '..');++const IGNORED_DIRECTORIES = ['node_modules', 'l', 'images', 'scripts'];++const HTML_ELEMENTS = [+ 'abbr',+ 'article',+ 'aside',+ 'blockquote',+ 'br',+ 'button',+ 'cite',+ 'code',+ 'dd',+ 'del',+ 'details',+ 'div',+ 'dl',+ 'dt',+ 'em',+ 'figcaption',+ 'figure',+ 'footer',+ 'form',+ 'h1',+ 'h2',+ 'h3',+ 'h4',+ 'h5',+ 'h6',+ 'header',+ 'hr',+ 'iframe',+ 'img',+ 'input',+ 'ins',+ 'kbd',+ 'label',+ 'li',+ 'main',+ 'mark',+ 'nav',+ 'ol',+ 'option',+ 'picture',+ 'pre',+ 'samp',+ 'section',+ 'select',+ 'small',+ 'source',+ 'span',+ 'strong',+ 'sub',+ 'summary',+ 'sup',+ 'table',+ 'tbody',+ 'td',+ 'textarea',+ 'tfoot',+ 'th',+ 'thead',+ 'tr',+ 'ul',+ 'var',+ 'video',+];++const PLACEHOLDER_PATTERN = /<([a-z][a-z0-9_-]+)>/g;++const URL_PREFIX_PATTERN = /https?:\/\/$/;++export type MdxViolation = {+ line: number;+ column: number;+ text: string;+ name: string;+};++type Range = {+ start: number;+ end: number;+};++const FENCE_LINE_PATTERN = /^\s*(`{3,})/;++// A fence closes only on a run at least as long as the one that opened it, so a+// block opened with ``` is not closed by the first ``` inside a ```` example.+const getFencedCodeRanges = (text: string): Range[] => {+ const ranges: Range[] = [];+ const lines = text.split('\n');++ let lineStart = 0;+ let openStart: number | null = null;+ let openLength = 0;++ for (const line of lines) {+ const fence = FENCE_LINE_PATTERN.exec(line);++ if (openStart === null) {+ if (fence) {+ openStart = lineStart;+ openLength = fence[1].length;+ }+ } else if (+ fence &&+ fence[1].length >= openLength &&+ line.slice(fence[0].length).trim() === ''+ ) {+ ranges.push({ start: openStart, end: lineStart + line.length });+ openStart = null;+ }++ lineStart += line.length + 1;+ }++ return ranges;+};++const isInsideRange = (position: number, ranges: Range[]) =>+ ranges.some((range) => position >= range.start && position < range.end);++// Backtick runs are paired within a line, never across one. A running parity+// counter would let a single unpaired backtick silently suppress every finding+// in the rest of the file.+const getInlineCodeRanges = (text: string, fencedRanges: Range[]): Range[] => {+ const ranges: Range[] = [];+ let lineStart = 0;++ for (const line of text.split('\n')) {+ const runs: { start: number; length: number }[] = [];++ for (const match of line.matchAll(/`+/g)) {+ const start = lineStart + match.index;++ if (!isInsideRange(start, fencedRanges)) {+ runs.push({ start, length: match[0].length });+ }+ }++ const unclosed: typeof runs = [];++ for (const run of runs) {+ const openerIndex = unclosed.findIndex(+ (candidate) => candidate.length === run.length,+ );++ if (openerIndex === -1) {+ unclosed.push(run);+ continue;+ }++ ranges.push({+ start: unclosed[openerIndex].start,+ end: run.start + run.length,+ });+ unclosed.splice(0, openerIndex + 1);+ }++ lineStart += line.length + 1;+ }++ return ranges;+};++const getLineAndColumn = (text: string, position: number) => {+ const precedingText = text.slice(0, position);+ const lines = precedingText.split('\n');++ return {+ line: lines.length,+ column: lines[lines.length - 1].length + 1,+ };+};++export const findAngleBracketPlaceholders = (text: string): MdxViolation[] => {+ const fencedRanges = getFencedCodeRanges(text);+ const inlineCodeRanges = getInlineCodeRanges(text, fencedRanges);+ const violations: MdxViolation[] = [];++ for (const match of text.matchAll(PLACEHOLDER_PATTERN)) {+ const name = match[1];+ const position = match.index;++ const isUrlPlaceholder = URL_PREFIX_PATTERN.test(text.slice(0, position));++ if (HTML_ELEMENTS.includes(name) && !isUrlPlaceholder) {+ continue;+ }++ if (+ isInsideRange(position, fencedRanges) ||+ isInsideRange(position, inlineCodeRanges)+ ) {+ continue;+ }++ violations.push({+ ...getLineAndColumn(text, position),+ text: match[0],+ name,+ });+ }++ return violations;+};++const collectMdxFiles = (directory: string, collected: string[] = []) => {+ for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {+ if (IGNORED_DIRECTORIES.includes(entry.name)) {+ continue;+ }++ const entryPath = path.join(directory, entry.name);++ if (entry.isDirectory()) {+ collectMdxFiles(entryPath, collected);+ } else if (entry.name.endsWith('.mdx')) {+ collected.push(entryPath);+ }+ }++ return collected;+};++const main = () => {+ const files = collectMdxFiles(DOCS_ROOT);+ let violationCount = 0;++ for (const file of files) {+ const violations = findAngleBracketPlaceholders(+ fs.readFileSync(file, 'utf8'),+ );++ for (const violation of violations) {+ const relativePath = path.relative(DOCS_ROOT, file);++ console.error(+ `${relativePath}:${violation.line}:${violation.column} ${violation.text} reads as a tag in Crowdin, use {${violation.name}} instead`,+ );+ }++ violationCount += violations.length;+ }++ if (violationCount > 0) {+ console.error(+ `\n${violationCount} angle bracket placeholder(s) found in ${files.length} MDX files.`,+ );+ process.exit(1);+ }++ console.log(`No angle bracket placeholders in ${files.length} MDX files.`);+};++if (require.main === module) {+ main();+}diff --git a/packages/twenty-docs/vitest.config.mts b/packages/twenty-docs/vitest.config.mtsnew file mode 100644index 00000000000..765bb0a479c--- /dev/null+++ b/packages/twenty-docs/vitest.config.mts@@ -0,0 +1,9 @@+import { defineConfig } from 'vitest/config';++export default defineConfig({+ test: {+ root: 'packages/twenty-docs',+ include: ['scripts/**/*.spec.ts'],+ globals: true,+ },+});diff --git a/yarn.lock b/yarn.lockindex 0544bb15df5..473a560cd7b 100644--- a/yarn.lock+++ b/yarn.lock@@ -49756,7 +49756,9 @@ __metadata:resolution: "twenty-docs@workspace:packages/twenty-docs"dependencies:mintlify: "npm:^4.2.594"+ tsx: "npm:^4.19.3"twenty-shared: "workspace:*"+ vitest: "npm:^4.1.0"languageName: unknownlinkType: soft