Merge remote-tracking branch 'origin/master' into worktree/docs-website
# Conflicts: # docs/user/develop/basic/config.zh.md # docs/user/develop/basic/index.zh.md # docs/user/develop/basic/tool.zh.md # docs/user/develop/framework/index.zh.md # docs/user/develop/framework/service.zh.md # docs/user/develop/practice/index.zh.md # docs/user/guide/index.zh.md # package.json # pnpm-lock.yaml # pnpm-workspace.yaml # website/.vitepress/config/index.ts # website/.vitepress/config/zh-CN.ts # website/package.json # website/zh-CN/api/cordis/context.md # website/zh-CN/api/cordis/events.md # website/zh-CN/api/cordis/fiber.md # website/zh-CN/api/cordis/registry.md # website/zh-CN/api/cordis/service.md # website/zh-CN/api/harness/bash.md # website/zh-CN/api/harness/fs.md # website/zh-CN/api/harness/llm.md # website/zh-CN/api/harness/tools.md # website/zh-CN/api/index.md # website/zh-CN/design/composability.md # website/zh-CN/design/context-model.md # website/zh-CN/design/reactive-coeffects.md # website/zh-CN/design/revertible-effects.md # website/zh-CN/develop/framework/events.md # website/zh-CN/develop/practice/llm-adapter.md # website/zh-CN/guide/config.md
This commit is contained in:
Yichen Jiang
@@ -1,13 +1,14 @@
|
||||
/**
|
||||
* Typecheck Markdown `ts` fences against workspace sources. `ignore-check`
|
||||
* fences are reported as opt-outs; generated catalog fragments and
|
||||
* `type-equiv` blocks are skipped here because their owning gates verify them.
|
||||
* Typecheck Markdown `ts` fences against the workspace API. `ignore-check` fences are reported as
|
||||
* opt-outs; generated catalog fragments and `type-equiv` blocks are skipped here because their
|
||||
* owning gates verify them. A build-coordinated mode consumes existing declarations without emit.
|
||||
*/
|
||||
|
||||
import { execFileSync } from 'node:child_process'
|
||||
import { globSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { join, relative, resolve } from 'node:path'
|
||||
import ts from 'typescript'
|
||||
import { extractFences } from './md-fences.ts'
|
||||
|
||||
const root = resolve(import.meta.dirname, '..')
|
||||
|
||||
@@ -27,60 +28,123 @@ interface Block {
|
||||
code: string
|
||||
}
|
||||
|
||||
/** The info-string → kind table this gate tracks. */
|
||||
const KIND_BY_INFO: Record<string, BlockKind> = {
|
||||
'ts': 'check',
|
||||
'ts ignore-check': 'ignore',
|
||||
'ts type-equiv': 'type-equiv',
|
||||
'ts cordis-catalog': 'cordis-catalog',
|
||||
'ts persistence-catalog': 'persistence-catalog',
|
||||
'ts config-catalog': 'config-catalog',
|
||||
}
|
||||
|
||||
/** Extract every recognized TypeScript fence from one Markdown file. */
|
||||
function extractBlocks(absPath: string): Block[] {
|
||||
const text = readFileSync(absPath, 'utf8')
|
||||
const lines = text.split('\n')
|
||||
const file = relative(root, absPath)
|
||||
const blocks: Block[] = []
|
||||
let open: { line: number; kind: BlockKind; body: string[] } | null = null
|
||||
return extractFences(absPath, info => KIND_BY_INFO[info] ?? null)
|
||||
.map(f => ({ file, line: f.line, kind: f.kind, code: f.code }))
|
||||
}
|
||||
|
||||
lines.forEach((raw, i) => {
|
||||
const fence = /^```(\s*)(\S.*)?$/.exec(raw)
|
||||
if (!fence) {
|
||||
if (open) open.body.push(raw)
|
||||
return
|
||||
}
|
||||
if (open) {
|
||||
// closing fence
|
||||
blocks.push({ file, line: open.line, kind: open.kind, code: open.body.join('\n') })
|
||||
open = null
|
||||
return
|
||||
}
|
||||
// Ignore non-TypeScript fences.
|
||||
const info = (fence[2] ?? '').trim()
|
||||
const kind: BlockKind | null =
|
||||
info === 'ts' ? 'check'
|
||||
: info === 'ts ignore-check' ? 'ignore'
|
||||
: info === 'ts type-equiv' ? 'type-equiv'
|
||||
: info === 'ts cordis-catalog' ? 'cordis-catalog'
|
||||
: info === 'ts persistence-catalog' ? 'persistence-catalog'
|
||||
: info === 'ts config-catalog' ? 'config-catalog'
|
||||
: null
|
||||
if (kind) open = { line: i + 1, kind, body: [] }
|
||||
const configHost: ts.ParseConfigFileHost = {
|
||||
...ts.sys,
|
||||
getCurrentDirectory: () => root,
|
||||
onUnRecoverableConfigFileDiagnostic(diagnostic) {
|
||||
throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'))
|
||||
},
|
||||
}
|
||||
|
||||
/** Load root settings and redirect workspace aliases to declarations from the coordinated build. */
|
||||
function builtTypeCompilerOptions(): ts.CompilerOptions {
|
||||
const configPath = join(root, 'tsconfig.json')
|
||||
const parsed = ts.getParsedCommandLineOfConfigFile(configPath, {}, configHost)
|
||||
if (!parsed) throw new Error(`doc-typecheck: cannot parse ${configPath}`)
|
||||
if (parsed.errors.length > 0) {
|
||||
throw new Error(parsed.errors.map(error => ts.flattenDiagnosticMessageText(error.messageText, '\n')).join('\n'))
|
||||
}
|
||||
if (parsed.options.paths === undefined) throw new Error('doc-typecheck: root tsconfig has no workspace paths')
|
||||
const paths = Object.fromEntries(Object.entries(parsed.options.paths).map(([specifier, candidates]) => [
|
||||
specifier,
|
||||
candidates.map((candidate) => {
|
||||
if (!candidate.endsWith('/src')) {
|
||||
throw new Error(`doc-typecheck: cannot map workspace source path to built declarations: ${candidate}`)
|
||||
}
|
||||
return `${candidate.slice(0, -'/src'.length)}/lib/types`
|
||||
}),
|
||||
]))
|
||||
const options: ts.CompilerOptions = {
|
||||
...parsed.options,
|
||||
paths,
|
||||
noEmit: true,
|
||||
composite: false,
|
||||
incremental: false,
|
||||
declaration: false,
|
||||
declarationMap: false,
|
||||
sourceMap: false,
|
||||
noUnusedLocals: false,
|
||||
noUnusedParameters: false,
|
||||
}
|
||||
delete options.tsBuildInfoFile
|
||||
return options
|
||||
}
|
||||
|
||||
/** Compile Markdown blocks as virtual files against declarations from the coordinated build. */
|
||||
function compileBlocksAgainstBuiltTypes(blocks: Block[]): readonly ts.Diagnostic[] {
|
||||
const options = builtTypeCompilerOptions()
|
||||
const sources = new Map<string, string>()
|
||||
for (const [index, block] of blocks.entries()) {
|
||||
const fileName = resolve(root, '.doc-typecheck', `block-${index}.ts`)
|
||||
sources.set(fileName, block.code.endsWith('\n') ? block.code : `${block.code}\n`)
|
||||
}
|
||||
|
||||
const baseHost = ts.createCompilerHost(options, true)
|
||||
const host: ts.CompilerHost = {
|
||||
...baseHost,
|
||||
fileExists(fileName) {
|
||||
return sources.has(resolve(fileName)) || baseHost.fileExists(fileName)
|
||||
},
|
||||
readFile(fileName) {
|
||||
return sources.get(resolve(fileName)) ?? baseHost.readFile(fileName)
|
||||
},
|
||||
getSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile) {
|
||||
const source = sources.get(resolve(fileName))
|
||||
if (source !== undefined) return ts.createSourceFile(fileName, source, languageVersion, true)
|
||||
return baseHost.getSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile)
|
||||
},
|
||||
writeFile() {
|
||||
throw new Error('doc-typecheck: noEmit compilation attempted to write output')
|
||||
},
|
||||
}
|
||||
const program = ts.createProgram([...sources.keys()], options, host)
|
||||
return ts.getPreEmitDiagnostics(program)
|
||||
}
|
||||
|
||||
/** Render compiler diagnostics with virtual block paths mapped back to Markdown. */
|
||||
function formatDiagnostics(diagnostics: readonly ts.Diagnostic[], blocks: Block[]): string {
|
||||
const formatted = ts.formatDiagnostics(diagnostics, {
|
||||
getCanonicalFileName: fileName => fileName,
|
||||
getCurrentDirectory: () => root,
|
||||
getNewLine: () => ts.sys.newLine,
|
||||
})
|
||||
return blocks
|
||||
return remapBlockPaths(formatted, blocks)
|
||||
}
|
||||
|
||||
/** Reuse the repo typecheck graph references from a temp project one directory below root. */
|
||||
function workspaceReferences(): { path: string }[] {
|
||||
const file = join(root, 'tsconfig.json')
|
||||
// Parse with TypeScript's own JSONC reader, not a hand-rolled comment strip:
|
||||
// a regex strip mistakes the `/*/` in a wildcard path candidate
|
||||
// (`./packages/core/*/src`) for a block comment and corrupts the map.
|
||||
const result = ts.readConfigFile(file, p => readFileSync(p, 'utf8'))
|
||||
// Parse with TypeScript's own JSONC reader: a regex comment stripper corrupts the `/*/` path
|
||||
// candidate in the workspace wildcard.
|
||||
const result = ts.readConfigFile(file, path => readFileSync(path, 'utf8'))
|
||||
if (result.error) {
|
||||
throw new Error(`doc-typecheck: cannot read ${file}: ${ts.flattenDiagnosticMessageText(result.error.messageText, '\n')}`)
|
||||
}
|
||||
// `config` is typed `any` by the TS API; narrow it to the one field we read.
|
||||
const { references } = result.config as { compilerOptions: { paths: Record<string, string[]> }; references: { path: string }[] }
|
||||
return references.map(({ path }) => {
|
||||
const relativeToTemp = path.startsWith('./') ? `../${path.slice(2)}` : `../${path}`
|
||||
return { path: relativeToTemp }
|
||||
})
|
||||
// `config` is typed `any` by the TS API; narrow it to the one field read here.
|
||||
const { references } = result.config as { references: { path: string }[] }
|
||||
return references.map(({ path }) => ({
|
||||
path: path.startsWith('./') ? `../${path.slice(2)}` : `../${path}`,
|
||||
}))
|
||||
}
|
||||
|
||||
/** The standalone tsconfig for the temp typecheck project. */
|
||||
/** The standalone temp project used when no coordinated build owns declaration freshness. */
|
||||
function tempTsconfig(): string {
|
||||
return JSON.stringify({
|
||||
extends: '../tsconfig.json',
|
||||
@@ -94,6 +158,39 @@ function tempTsconfig(): string {
|
||||
})
|
||||
}
|
||||
|
||||
/** Compile blocks through project references for the standalone command. */
|
||||
function compileBlocksStandalone(blocks: Block[]): string | undefined {
|
||||
const tmp = mkdtempSync(join(root, '.doc-typecheck-'))
|
||||
try {
|
||||
writeFileSync(join(tmp, 'tsconfig.json'), tempTsconfig())
|
||||
for (const [index, block] of blocks.entries()) {
|
||||
writeFileSync(join(tmp, `block-${index}.ts`), block.code.endsWith('\n') ? block.code : `${block.code}\n`)
|
||||
}
|
||||
try {
|
||||
// Invoke tsc's JS entry through Node instead of a platform-specific shell shim.
|
||||
execFileSync(process.execPath, ['node_modules/typescript/bin/tsc', '-b', join(tmp, 'tsconfig.json')], {
|
||||
cwd: root,
|
||||
stdio: 'pipe',
|
||||
})
|
||||
return undefined
|
||||
} catch (error: unknown) {
|
||||
const failed = error as { stdout?: Buffer; stderr?: Buffer }
|
||||
return remapBlockPaths(`${failed.stdout?.toString() ?? ''}${failed.stderr?.toString() ?? ''}`, blocks)
|
||||
}
|
||||
} finally {
|
||||
rmSync(tmp, { recursive: true, force: true })
|
||||
}
|
||||
}
|
||||
|
||||
/** Map virtual or temporary block paths back to their owning Markdown fences. */
|
||||
function remapBlockPaths(output: string, blocks: Block[]): string {
|
||||
return output.replace(/(?:[^\s:()]*[/\\])?block-(\d+)\.ts\((\d+),(\d+)\)/g, (_match, index: string, line: string, column: string) => {
|
||||
const block = blocks[Number(index)]
|
||||
if (!block) return `block-${index}.ts(${line},${column})`
|
||||
return `${block.file} (block at line ${block.line}, +${line}:${column})`
|
||||
})
|
||||
}
|
||||
|
||||
const markdownGlobs = ['README.md', 'docs/**/*.md', 'packages/*/*.md', 'packages/*/*/*.md']
|
||||
|
||||
const files: string[] = []
|
||||
@@ -114,45 +211,24 @@ if (checked.length === 0) {
|
||||
process.exit(0)
|
||||
}
|
||||
|
||||
const tmp = mkdtempSync(join(root, '.doc-typecheck-'))
|
||||
try {
|
||||
writeFileSync(join(tmp, 'tsconfig.json'), tempTsconfig())
|
||||
const fileForBlock = new Map<string, Block>()
|
||||
checked.forEach((block, i) => {
|
||||
const name = `block-${i}.ts`
|
||||
writeFileSync(join(tmp, name), block.code.endsWith('\n') ? block.code : `${block.code}\n`)
|
||||
fileForBlock.set(name, block)
|
||||
})
|
||||
|
||||
try {
|
||||
// tsc's JS entry via the current node, not the .bin shim: the extensionless
|
||||
// shim is not spawnable on Windows (the CVE-2024-27980 class the sibling
|
||||
// scripts hit), and the .cmd variant would need shell:true, which
|
||||
// concatenates args UNESCAPED — a hazard for the temp project path. The JS
|
||||
// entry behaves identically on every platform.
|
||||
execFileSync(process.execPath, ['node_modules/typescript/bin/tsc', '-b', join(tmp, 'tsconfig.json')], { cwd: root, stdio: 'pipe' })
|
||||
} catch (error: unknown) {
|
||||
const failed = error as { stdout?: Buffer; stderr?: Buffer }
|
||||
const out = `${failed.stdout?.toString() ?? ''}${failed.stderr?.toString() ?? ''}`
|
||||
// Rewrite "block-N.ts(line,col)" to the real "file:fenceLine" for triage.
|
||||
const remapped = out.replace(/(?:[^\s:()]*[/\\])?block-(\d+)\.ts\((\d+),(\d+)\)/g, (_m, idx: string, ln: string, col: string) => {
|
||||
const block = fileForBlock.get(`block-${idx}.ts`)
|
||||
if (!block) return `block-${idx}.ts(${ln},${col})`
|
||||
return `${block.file} (block at line ${block.line}, +${ln}:${col})`
|
||||
})
|
||||
console.error('doc-typecheck: documentation code blocks failed to compile.\n')
|
||||
console.error(remapped)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const ratio = ignored.length / ratioDenominator
|
||||
const skipped = all.length - ratioDenominator
|
||||
console.log(`doc-typecheck: ${checked.length} block(s) compiled, ${ignored.length} ignored (${(ratio * 100).toFixed(0)}% opt-out), ${skipped} type-equiv/catalog (checked elsewhere).`)
|
||||
// Guard against the escape hatch becoming the norm.
|
||||
if (ratioDenominator >= 4 && ratio > 0.5) {
|
||||
console.error(`doc-typecheck: too many blocks opt out of checking (${ignored.length}/${ratioDenominator}). Make them compile or delete them.`)
|
||||
process.exit(1)
|
||||
}
|
||||
} finally {
|
||||
rmSync(tmp, { recursive: true, force: true })
|
||||
const useBuiltTypes = process.env.DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT === '1'
|
||||
const compilationError = useBuiltTypes
|
||||
? (() => {
|
||||
const diagnostics = compileBlocksAgainstBuiltTypes(checked)
|
||||
return diagnostics.length === 0 ? undefined : formatDiagnostics(diagnostics, checked)
|
||||
})()
|
||||
: compileBlocksStandalone(checked)
|
||||
if (compilationError !== undefined) {
|
||||
console.error('doc-typecheck: documentation code blocks failed to compile.\n')
|
||||
console.error(compilationError)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const ratio = ignored.length / ratioDenominator
|
||||
const skipped = all.length - ratioDenominator
|
||||
console.log(`doc-typecheck: ${checked.length} block(s) compiled, ${ignored.length} ignored (${(ratio * 100).toFixed(0)}% opt-out), ${skipped} type-equiv/catalog (checked elsewhere).`)
|
||||
// Guard against the escape hatch becoming the norm.
|
||||
if (ratioDenominator >= 4 && ratio > 0.5) {
|
||||
console.error(`doc-typecheck: too many blocks opt out of checking (${ignored.length}/${ratioDenominator}). Make them compile or delete them.`)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user