Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/docs-deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@ jobs:
- name: Install dependencies
run: npm ci

- name: Check inlined tsconfig against @docusaurus/tsconfig
run: npm run check:tsconfig

- name: Type check
run: npm run typecheck

Expand Down
3 changes: 3 additions & 0 deletions .github/workflows/docs-pr-build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ jobs:
- name: Install dependencies
run: npm ci

- name: Check inlined tsconfig against @docusaurus/tsconfig
run: npm run check:tsconfig

- name: Type check
run: npm run typecheck

Expand Down
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
"serve": "docusaurus serve",
"typecheck": "tsc"
"typecheck": "tsc",
"check:tsconfig": "node scripts/check-tsconfig-drift.mjs"
},
"dependencies": {
"@docusaurus/core": "3.10.2",
Expand Down
129 changes: 129 additions & 0 deletions scripts/check-tsconfig-drift.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
// Guards the inlined tsconfig against upstream drift.
//
// tsconfig.json inlines @docusaurus/tsconfig's compilerOptions instead
// of extending them, because the upstream config sets `baseUrl` and TypeScript 7
// removed that option (an inherited option can't be unset by the extending file).
// The cost of inlining is that upstream changes no longer reach us. This script
// pays that cost down: it fails if upstream's options stop matching our copy,
// modulo the deltas declared below.
//
// Run: npm run check:tsconfig

// Deliberately depends on nothing but Node: a guard must not break when the
// thing it guards changes. The first version imported `typescript` to parse
// JSONC and died under TS 7 (`ts.parseConfigFileTextToJson is not a function` —
// the native port does not expose the old namespace API), taking CI with it.

import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const siteDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const OURS = path.join(siteDir, 'tsconfig.json');
const UPSTREAM = path.join(siteDir, 'node_modules/@docusaurus/tsconfig/tsconfig.json');

// Deltas we intend to carry. Keep this list minimal and justified.
const DROPPED = new Set(['baseUrl']); // removed in TS 7; see tsconfig.json comment
const OURS_ONLY = new Set(['strict']); // this site's own choice, predates inlining

// Minimal JSONC -> JSON. String-aware, so it does not maul the `//` inside the
// "$schema": "https://..." value, and it drops trailing commas the way tsc does.
function stripJsonc(text) {
let out = '';
let inString = false;
let escaped = false;
let inLineComment = false;
let inBlockComment = false;

for (let i = 0; i < text.length; i++) {
const c = text[i];
const next = text[i + 1];

if (inLineComment) {
if (c === '\n') { inLineComment = false; out += c; }
continue;
}
if (inBlockComment) {
if (c === '*' && next === '/') { inBlockComment = false; i++; }
continue;
}
if (inString) {
out += c;
if (escaped) escaped = false;
else if (c === '\\') escaped = true;
else if (c === '"') inString = false;
continue;
}
if (c === '"') { inString = true; out += c; continue; }
if (c === '/' && next === '/') { inLineComment = true; i++; continue; }
if (c === '/' && next === '*') { inBlockComment = true; i++; continue; }

// Trailing comma: rewind past whitespace and drop it before } or ].
if (c === '}' || c === ']') {
const trimmed = out.replace(/\s+$/, '');
if (trimmed.endsWith(',')) out = trimmed.slice(0, -1);
}
out += c;
}
return out;
}

function readOptions(file) {
if (!fs.existsSync(file)) {
console.error(`check-tsconfig-drift: missing ${file}\nRun \`npm ci\` first.`);
process.exit(2);
}
const raw = fs.readFileSync(file, 'utf8');
try {
return JSON.parse(stripJsonc(raw)).compilerOptions ?? {};
} catch (err) {
console.error(`check-tsconfig-drift: cannot parse ${file}: ${err.message}`);
process.exit(2);
}
}

const ours = readOptions(OURS);
const upstream = readOptions(UPSTREAM);

const problems = [];
const seen = new Set([...Object.keys(ours), ...Object.keys(upstream)]);

for (const key of [...seen].sort()) {
const inOurs = Object.hasOwn(ours, key);
const inUpstream = Object.hasOwn(upstream, key);

if (inUpstream && DROPPED.has(key)) {
if (inOurs) problems.push(` ${key}: expected to be dropped from our copy, but it is present`);
continue; // upstream still ships it — that's the status quo this file documents
}
if (inOurs && OURS_ONLY.has(key)) continue;

if (inUpstream && !inOurs) {
problems.push(` ${key}: added upstream (${JSON.stringify(upstream[key])}) — missing from our copy`);
} else if (inOurs && !inUpstream) {
problems.push(` ${key}: removed upstream — still in our copy (${JSON.stringify(ours[key])})`);
} else if (JSON.stringify(ours[key]) !== JSON.stringify(upstream[key])) {
problems.push(` ${key}: upstream ${JSON.stringify(upstream[key])} != ours ${JSON.stringify(ours[key])}`);
}
}

// If upstream ever drops baseUrl, the whole workaround can go away.
if (!Object.hasOwn(upstream, 'baseUrl')) {
console.log(
'check-tsconfig-drift: @docusaurus/tsconfig no longer sets baseUrl.\n' +
'The inlining workaround is obsolete — restore `"extends": "@docusaurus/tsconfig"`\n' +
'in tsconfig.json (keeping "strict": true) and delete this script.',
);
}

if (problems.length > 0) {
console.error(
'check-tsconfig-drift: tsconfig.json has drifted from @docusaurus/tsconfig:\n' +
problems.join('\n') +
'\n\nReconcile the inline copy against node_modules/@docusaurus/tsconfig/tsconfig.json,\n' +
'or update the DROPPED / OURS_ONLY sets in this script if the delta is intentional.',
);
process.exit(1);
}

console.log('check-tsconfig-drift: inline tsconfig matches @docusaurus/tsconfig (modulo declared deltas).');
36 changes: 33 additions & 3 deletions tsconfig.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,38 @@
{
"extends": "@docusaurus/tsconfig",
"$schema": "https://json.schemastore.org/tsconfig",
// Inlined from @docusaurus/tsconfig, minus `baseUrl`, rather than extending it.
// TypeScript 7 removed baseUrl outright (TS5102). The previous
// `"ignoreDeprecations": "6.0"` silenced TS 6's TS5101 deprecation warning,
// but TS 7 rejects the option itself, so that escape hatch is gone — and an
// inherited compilerOption cannot be unset by the extending config. While
// @docusaurus/tsconfig still ships baseUrl (it does as of 3.10.2), `extends`
// and a green `npm run typecheck` are mutually exclusive under TS 7.
//
// This also FIXES `@site/*`, which was quietly broken. Relative paths in an
// extended config resolve against that config's own directory, so the
// inherited `baseUrl: "."` pointed at node_modules/@docusaurus/tsconfig —
// making `@site/foo` resolve to node_modules/@docusaurus/tsconfig/foo, i.e.
// nothing. With baseUrl gone, `paths` resolves against THIS file's directory,
// so `@site/*` now maps to the site root and agrees with Docusaurus's own
// webpack alias (siteDir). Verify with `tsc --traceResolution` if you touch it.
//
// scripts/check-tsconfig-drift.mjs fails CI if upstream's options change, so
// this copy cannot silently rot. Revert to `"extends": "@docusaurus/tsconfig"`
// once Docusaurus drops baseUrl.
"compilerOptions": {
"strict": true,
"ignoreDeprecations": "6.0"
"allowJs": true,
"esModuleInterop": true,
"jsx": "preserve",
"target": "ES2022",
"lib": ["ES2022", "DOM"],
"moduleResolution": "bundler",
"module": "esnext",
"noEmit": true,
"paths": {
"@site/*": ["./*"]
},
"skipLibCheck": true,
"strict": true
},
"exclude": [".docusaurus", "build"]
}