feat(infra): prohibit new assertions to unknown

This commit is contained in:
Tianyi Cui committed 2026-09-19 20:13:58 +08:00
1 parent bc45bd821a
commit c5d775d437
10 files changed
+3288

No files matched your search

File diff suppressed because it is too large. Load diff
+11
View File
@@ -319,6 +319,7 @@ describe('gate graph validation', () => {
'rescope-vendor', 'publint', 'constraints', 'default-product-isolation', 'package-dependencies', 'application-entrypoints',
'dsh-package-licenses', 'package-invariants', 'built-package-invariants', 'node-next-types',
'optional-dependency-imports', 'client-packages', 'client-ui-i18n', 'client-route-resolution', 'no-bare-dispatcher',
'no-unknown-casts',
'cordis-config', 'runtime-closure',
])
})
@@ -360,6 +361,16 @@ describe('gate graph validation', () => {
},
)
it.each(['ci-primary', 'ci-static', 'check-all', 'hygiene'] as const)(
'rejects new unknown casts in %s',
(mode) => {
const gate = withPnpmEntrypoint(() => gatesForMode(mode).find(subject => subject.id === 'no-unknown-casts'))
expect(gate?.args).toContain('verify-no-unknown-casts')
expect(gate?.allowFailure).not.toBe(true)
},
)
it.each(['ci-primary', 'ci-static', 'check-all', 'hygiene'] as const)(
'keeps package dependency enforcement in %s',
(mode) => {
+1
View File
@@ -363,6 +363,7 @@ function sharedHygieneGates(): Gate[] {
pnpmScript('client-ui-i18n', 'verify-client-ui-i18n', { label: 'client UI i18n' }),
pnpmScript('client-route-resolution', 'verify-client-route-resolution', { label: 'client route resolution' }),
pnpmScript('no-bare-dispatcher', 'verify-no-bare-dispatcher', { label: 'proxy-aware dispatchers' }),
pnpmScript('no-unknown-casts', 'verify-no-unknown-casts', { label: 'no new unknown casts' }),
]
}
+236
View File
@@ -0,0 +1,236 @@
import { execFileSync } from 'node:child_process'
import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
import { afterEach, describe, expect, it } from 'vitest'
import { countUnknownCasts, findUnknownCasts, scanUnknownCasts, verifyNoUnknownCasts } from './verify-no-unknown-casts.ts'
const roots: string[] = []
const baselinePath = 'scripts/no-unknown-casts.baseline.json'
const sourcePath = 'packages/example/src/index.ts'
const assertion = 'const result = value as unknown\n'
afterEach(() => {
for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
})
function write(root: string, file: string, contents: string): void {
const path = join(root, file)
mkdirSync(dirname(path), { recursive: true })
writeFileSync(path, contents)
}
function git(root: string, ...args: string[]): void {
execFileSync('git', args, { cwd: root, stdio: 'pipe' })
}
function fixture(): string {
const root = mkdtempSync(join(tmpdir(), 'dsh-unknown-casts-'))
roots.push(root)
git(root, 'init', '--quiet')
for (const area of ['packages', 'apps', 'scripts', 'website']) {
write(root, `${area}/seed.ts`, 'export {}\n')
}
write(root, baselinePath, '{}\n')
git(root, 'add', '.')
return root
}
function recordBaseline(root: string): string {
const text = `${JSON.stringify(countUnknownCasts(scanUnknownCasts(root)), null, 2)}\n`
write(root, baselinePath, text)
return text
}
describe('unknown assertion syntax', () => {
it.each([
['standalone', 'input.ts', 'value as unknown', 1],
['double assertion', 'input.ts', 'value as unknown as Result', 1],
['nested assertions', 'input.ts', '(value as unknown) as unknown', 2],
['multiline', 'input.ts', 'value as\nunknown', 1],
['comment-separated', 'input.ts', 'value as /* explanation */ unknown', 1],
['parenthesized type', 'input.ts', 'value as ((unknown))', 1],
['angle assertion', 'input.ts', '<unknown>value', 1],
['parenthesized angle type', 'input.ts', '<(unknown)>value', 1],
['TSX expression', 'input.tsx', '<View value={input as unknown} />', 1],
['template interpolation', 'input.ts', '`text ${value as unknown}`', 1],
])('finds %s', (_name, file, text, count) => {
expect(findUnknownCasts(file, text)).toHaveLength(count)
})
it.each([
'// value as unknown\n/* <unknown>value */',
'const text = "value as unknown"',
'const text = `value as unknown`',
'const result = value as unknown[]',
'const result = value as Record<string, unknown>',
'const result = <unknown[]>value',
'const result: unknown = value',
'type Input = unknown; const result = value as Input',
])('accepts source without a direct assertion: %s', (text) => {
expect(findUnknownCasts('input.ts', text)).toEqual([])
})
it('accepts JSX text without ignoring assertions in expressions', () => {
expect(findUnknownCasts('input.tsx', '<View>as unknown</View>')).toEqual([])
expect(findUnknownCasts('input.tsx', '<View>{value as unknown}</View>')).toHaveLength(1)
})
it('reports normalized paths and the asserted type line', () => {
const casts = findUnknownCasts('packages\\example\\index.ts', '\nvalue as\nunknown')
expect(casts).toHaveLength(1)
expect(casts[0]).toMatchObject({ file: 'packages/example/index.ts', line: 3 })
expect(casts[0]?.fingerprint).toMatch(/^[a-f0-9]{64}$/u)
})
it('keeps syntax fingerprints through whitespace and comment edits', () => {
const original = findUnknownCasts('input.ts', 'call(value, "text") as unknown')
const formatted = findUnknownCasts('input.ts', '\ncall /* call */ (value,\n "text") as /* type */ unknown')
expect(formatted.map(cast => cast.fingerprint)).toEqual(original.map(cast => cast.fingerprint))
expect(findUnknownCasts('input.ts', 'call(value, "other") as unknown').map(cast => cast.fingerprint))
.not.toEqual(original.map(cast => cast.fingerprint))
})
})
describe('unknown assertion inventory', () => {
it('accepts recorded assertions after formatting without rewriting the baseline', () => {
const root = fixture()
write(root, sourcePath, assertion)
const baseline = recordBaseline(root)
write(root, sourcePath, 'const result = value as\n /* reason */ unknown\n')
expect(verifyNoUnknownCasts(root)).toBe(1)
expect(verifyNoUnknownCasts(root, true)).toBe(1)
expect(readFileSync(join(root, baselinePath), 'utf8')).toBe(baseline)
})
it.each([
['additional assertion', `${assertion}const other = input as unknown\n`],
['duplicate assertion', `${assertion}${assertion}`],
['replacement assertion', 'const result = other as unknown\n'],
])('rejects an %s without changing the baseline', (_name, text) => {
const root = fixture()
write(root, sourcePath, assertion)
const baseline = recordBaseline(root)
write(root, sourcePath, text)
expect(() => verifyNoUnknownCasts(root)).toThrow(/new assertions to unknown/u)
expect(() => verifyNoUnknownCasts(root, true)).toThrow(/new assertions to unknown/u)
expect(readFileSync(join(root, baselinePath), 'utf8')).toBe(baseline)
})
it('rejects a new assertion when the inventory is empty', () => {
const root = fixture()
write(root, sourcePath, assertion)
expect(() => verifyNoUnknownCasts(root)).toThrow(`${sourcePath}:1`)
})
it('requires pruning retired counts while preserving the remaining assertion', () => {
const root = fixture()
write(root, sourcePath, `${assertion}${assertion}`)
write(root, 'apps/retired.ts', 'const retired = input as unknown\n')
recordBaseline(root)
write(root, sourcePath, assertion)
unlinkSync(join(root, 'apps/retired.ts'))
expect(() => verifyNoUnknownCasts(root)).toThrow(/remove retired baseline entries/u)
expect(verifyNoUnknownCasts(root, true)).toBe(1)
expect(JSON.parse(readFileSync(join(root, baselinePath), 'utf8'))).toEqual(
countUnknownCasts(findUnknownCasts(sourcePath, assertion)),
)
expect(verifyNoUnknownCasts(root)).toBe(1)
})
it('prunes a deleted tracked file without treating it as a discovery failure', () => {
const root = fixture()
write(root, sourcePath, assertion)
git(root, 'add', sourcePath)
recordBaseline(root)
unlinkSync(join(root, sourcePath))
expect(() => verifyNoUnknownCasts(root)).toThrow(/remove retired baseline entries/u)
expect(verifyNoUnknownCasts(root, true)).toBe(0)
expect(readFileSync(join(root, baselinePath), 'utf8')).toBe('{}\n')
})
it.each([
['not an object', '[]'],
['null', 'null'],
['invalid JSON', '{'],
['non-source path', '{"input.json":{"HASH":1}}'],
['absolute path', '{"/input.ts":{"HASH":1}}'],
['parent path', '{"../input.ts":{"HASH":1}}'],
['backslash path', JSON.stringify({ 'packages\\input.ts': { HASH: 1 } })],
['excluded path', '{"vendor/input.ts":{"HASH":1}}'],
['empty file counts', '{"input.ts":{}}'],
['array counts', '{"input.ts":[]}'],
['invalid fingerprint', '{"input.ts":{"invalid":1}}'],
['zero count', '{"input.ts":{"HASH":0}}'],
['negative count', '{"input.ts":{"HASH":-1}}'],
['fractional count', '{"input.ts":{"HASH":1.5}}'],
['unsafe count', '{"input.ts":{"HASH":9007199254740992}}'],
['string count', '{"input.ts":{"HASH":"1"}}'],
])('rejects a malformed baseline: %s', (_name, text) => {
const root = fixture()
const contents = text.replaceAll('HASH', 'a'.repeat(64))
write(root, baselinePath, contents)
expect(() => verifyNoUnknownCasts(root, true)).toThrow()
expect(readFileSync(join(root, baselinePath), 'utf8')).toBe(contents)
})
})
describe('unknown assertion source discovery', () => {
it('checks tracked source across areas, extensions, tests and root configuration', () => {
const root = fixture()
const files = [
'packages/example/src/input.ts',
'apps/example/input.tsx',
'scripts/input.mts',
'website/input.cts',
'packages/example/tests/input.js',
'apps/example/input.jsx',
'scripts/input.mjs',
'website/input.cjs',
'config.ts',
]
for (const file of files) write(root, file, assertion)
git(root, 'add', '.')
expect(scanUnknownCasts(root).map(cast => cast.file)).toEqual(files.toSorted())
expect(() => verifyNoUnknownCasts(root)).toThrow(/new assertions to unknown/u)
})
it('includes untracked source while excluding ignored files, vendor, archives and other extensions', () => {
const root = fixture()
write(root, '.gitignore', 'ignored/\n')
for (const file of ['ignored/input.ts', 'vendor/input.ts', '.agents/notes/archived/input.ts', 'docs/input.md']) {
write(root, file, assertion)
}
git(root, 'add', '.')
write(root, 'scripts/new.ts', assertion)
expect(scanUnknownCasts(root).map(cast => cast.file)).toEqual(['scripts/new.ts'])
expect(() => verifyNoUnknownCasts(root)).toThrow('scripts/new.ts:1')
unlinkSync(join(root, 'scripts/new.ts'))
expect(verifyNoUnknownCasts(root)).toBe(0)
})
it.each(['packages', 'apps', 'scripts', 'website'])('rejects discovery missing %s', (area) => {
const root = fixture()
unlinkSync(join(root, `${area}/seed.ts`))
expect(() => verifyNoUnknownCasts(root)).toThrow(`source discovery omitted ${area}/`)
})
it('rejects an empty source corpus', () => {
const root = fixture()
for (const area of ['packages', 'apps', 'scripts', 'website']) unlinkSync(join(root, `${area}/seed.ts`))
expect(() => verifyNoUnknownCasts(root)).toThrow(/source discovery omitted/u)
})
// Creating file symlinks requires privileges that Windows CI does not guarantee.
it.skipIf(process.platform === 'win32')('rejects a source symlink', () => {
const root = fixture()
write(root, 'target.txt', assertion)
const link = join(root, 'scripts/linked.ts')
symlinkSync(join(root, 'target.txt'), link)
try {
expect(() => verifyNoUnknownCasts(root)).toThrow('source symlink is unsupported: scripts/linked.ts')
} finally {
unlinkSync(link)
}
})
})
+183
View File
@@ -0,0 +1,183 @@
/** Reject new assertions to unknown while retiring the recorded existing assertions. */
import { execFileSync } from 'node:child_process'
import { createHash } from 'node:crypto'
import { lstatSync, readFileSync, writeFileSync } from 'node:fs'
import { resolve } from 'node:path'
import ts from 'typescript'
const root = resolve(import.meta.dirname, '..')
const baselinePath = 'scripts/no-unknown-casts.baseline.json'
/** Existing assertion counts, keyed by repository path and syntax fingerprint. */
export type UnknownCastBaseline = Record<string, Record<string, number>>
/** One direct assertion to unknown in authored source. */
export interface UnknownCast {
/** Repository-relative path with forward slashes. */
file: string
/** One-based source line. */
line: number
/** SHA-256 of the assertion's syntax tokens, excluding comments and whitespace. */
fingerprint: string
}
function syntaxFingerprint(node: ts.Node, source: ts.SourceFile): string {
const tokens: [number, string][] = []
const visit = (child: ts.Node): void => {
if (ts.isJSDoc(child)) return
const children = child.getChildren(source)
if (children.length === 0) tokens.push([child.kind, child.getText(source)])
else children.forEach(visit)
}
visit(node)
return createHash('sha256').update(JSON.stringify(tokens)).digest('hex')
}
/**
* Find direct assertions to unknown, including angle assertions and parenthesized types.
* @param file - repository-relative source path; its extension selects TS or TSX parsing.
* @param text - source contents.
* @returns assertions in source order; comments, strings, aliases and unknown containers do not match.
*/
export function findUnknownCasts(file: string, text: string): UnknownCast[] {
const normalized = file.replaceAll('\\', '/')
const source = ts.createSourceFile(normalized, text, ts.ScriptTarget.Latest, true)
const casts: UnknownCast[] = []
const visit = (node: ts.Node): void => {
if (ts.isAsExpression(node) || ts.isTypeAssertionExpression(node)) {
let type = node.type
while (ts.isParenthesizedTypeNode(type)) type = type.type
if (type.kind === ts.SyntaxKind.UnknownKeyword) {
casts.push({
file: normalized,
line: source.getLineAndCharacterOfPosition(node.type.getStart(source)).line + 1,
fingerprint: syntaxFingerprint(node, source),
})
}
}
ts.forEachChild(node, visit)
}
visit(source)
return casts
}
function isSource(file: string): boolean {
return /\.(?:[cm]?[jt]s|[jt]sx)$/u.test(file)
&& !file.startsWith('vendor/')
&& !file.startsWith('.agents/notes/archived/')
}
/**
* Scan tracked source and non-ignored new source, including tests and configuration files.
* @param repoRoot - repository root containing the Git index.
* @returns every direct unknown assertion in the current working tree.
* @throws if discovery omits a required source area or an eligible path is a symlink.
*/
export function scanUnknownCasts(repoRoot: string): UnknownCast[] {
const files = [...new Set(execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z'], {
cwd: repoRoot,
encoding: 'utf8',
maxBuffer: 16 * 1024 * 1024,
}).split('\0').map(file => file.replaceAll('\\', '/')).filter(isSource))].sort()
const present = files.filter((file) => {
const stat = lstatSync(resolve(repoRoot, file), { throwIfNoEntry: false })
if (stat?.isSymbolicLink()) throw new Error(`verify-no-unknown-casts: source symlink is unsupported: ${file}`)
return stat?.isFile() === true
})
for (const area of ['packages/', 'apps/', 'scripts/', 'website/']) {
if (!present.some(file => file.startsWith(area))) {
throw new Error(`verify-no-unknown-casts: source discovery omitted ${area}`)
}
}
return present.flatMap(file => findUnknownCasts(file, readFileSync(resolve(repoRoot, file), 'utf8')))
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
function readBaseline(repoRoot: string): UnknownCastBaseline {
const value: unknown = JSON.parse(readFileSync(resolve(repoRoot, baselinePath), 'utf8'))
if (!isRecord(value)) throw new Error('verify-no-unknown-casts: baseline must be a file-to-counts object')
const baseline: UnknownCastBaseline = {}
for (const [file, counts] of Object.entries(value)) {
if (!isSource(file) || file.startsWith('/') || file.includes('\\') || file.split('/').includes('..')
|| !isRecord(counts) || Object.keys(counts).length === 0) {
throw new Error(`verify-no-unknown-casts: invalid baseline file: ${file}`)
}
const parsed: Record<string, number> = {}
for (const [fingerprint, count] of Object.entries(counts)) {
if (!/^[a-f0-9]{64}$/u.test(fingerprint) || typeof count !== 'number' || !Number.isSafeInteger(count) || count <= 0) {
throw new Error(`verify-no-unknown-casts: invalid baseline count: ${file}:${fingerprint}`)
}
parsed[fingerprint] = count
}
baseline[file] = parsed
}
return baseline
}
/**
* Count exact assertions without granting a file-wide allowance.
* @param casts - observed assertions.
* @returns path and fingerprint counts in stable order for comparison and pruning.
*/
export function countUnknownCasts(casts: readonly UnknownCast[]): UnknownCastBaseline {
const baseline: UnknownCastBaseline = {}
for (const { file, fingerprint } of casts) {
const counts = baseline[file] ??= {}
counts[fingerprint] = (counts[fingerprint] ?? 0) + 1
}
return Object.fromEntries(Object.entries(baseline).sort(([a], [b]) => a.localeCompare(b))
.map(([file, counts]) => [file, Object.fromEntries(Object.entries(counts).sort(([a], [b]) => a.localeCompare(b)))]))
}
/**
* Enforce the recorded assertion inventory, optionally deleting retired allowances.
* @param repoRoot - repository root to scan.
* @param prune - remove stale entries only after establishing that no new assertion exists.
* @returns the number of existing assertions still present.
* @throws for new assertions, malformed inventories, or stale entries without pruning.
*/
export function verifyNoUnknownCasts(repoRoot: string, prune = false): number {
const baseline = readBaseline(repoRoot)
const casts = scanUnknownCasts(repoRoot)
const current = countUnknownCasts(casts)
const remaining = structuredClone(baseline)
const added: UnknownCast[] = []
for (const cast of casts) {
const counts = remaining[cast.file]
const allowance = counts?.[cast.fingerprint] ?? 0
if (counts !== undefined && allowance > 0) counts[cast.fingerprint] = allowance - 1
else added.push(cast)
}
if (added.length > 0) {
throw new Error('verify-no-unknown-casts: new assertions to unknown are forbidden. Use a typed value or narrow the input.\n'
+ added.map(cast => ` ${cast.file}:${String(cast.line)} (${cast.fingerprint})`).join('\n'))
}
const stale = Object.entries(remaining).flatMap(([file, counts]) => Object.entries(counts)
.filter(([, count]) => count > 0).map(([fingerprint]) => ` ${file} (${fingerprint})`))
if (stale.length > 0) {
if (!prune) {
throw new Error('verify-no-unknown-casts: remove retired baseline entries with pnpm run verify-no-unknown-casts --prune.\n'
+ stale.join('\n'))
}
writeFileSync(resolve(repoRoot, baselinePath), `${JSON.stringify(current, null, 2)}\n`)
}
return casts.length
}
if (import.meta.filename === resolve(process.argv[1] ?? '')) {
try {
const args = process.argv.slice(2)
if (args.length > 1 || (args.length === 1 && args[0] !== '--prune')) {
throw new Error('Usage: pnpm run verify-no-unknown-casts [--prune]')
}
const count = verifyNoUnknownCasts(root, args[0] === '--prune')
console.log(`verify-no-unknown-casts: no new assertions; ${String(count)} existing assertions remain.`)
} catch (error) {
console.error(error instanceof Error ? error.message : String(error))
process.exitCode = 1
}
}