|
|
@@ -0,0 +1,368 @@
|
|
|
+/**
|
|
|
+ * Keep browser-only external packages out of installed dependency sections.
|
|
|
+ *
|
|
|
+ * A browser artifact resolves nothing on the user's machine: tsdown inlines
|
|
|
+ * every non-platform specifier into `lib/client.js`, the shell `dist` answers
|
|
|
+ * `PLATFORM_MODULES` from its frozen module table, and Vite inlines the shell's
|
|
|
+ * own imports into that published `dist`. A specifier only browser source
|
|
|
+ * reaches is therefore a build-time input and belongs in `devDependencies`,
|
|
|
+ * because npm installs `dependencies` and non-optional `peerDependencies` for
|
|
|
+ * every consumer of the published package.
|
|
|
+ *
|
|
|
+ * Each face is walked from the entries the manifest publishes, not by a
|
|
|
+ * directory rule, so a module under `src/` that only the browser entry reaches
|
|
|
+ * counts as browser source:
|
|
|
+ *
|
|
|
+ * `./client` is `lib/client.js` host: the other export targets; browser: the bundle
|
|
|
+ * `packages/client/*` with no browser-only library: host is `src/invariant.ts`,
|
|
|
+ * `./client` export the companion the host mounts; `.` is browser code
|
|
|
+ * no `.` export, ships a `dist` prebuilt browser bundle: no host face at all
|
|
|
+ *
|
|
|
+ * Only external packages are subject: they are what an install downloads. A
|
|
|
+ * workspace name stays where its manifest puts it, because that declaration also
|
|
|
+ * states which package supplies an injected service or a mounted Remote
|
|
|
+ * contribution, and the app installs it either way. A reference from the host
|
|
|
+ * face, an erased type import included, likewise keeps a declaration in place.
|
|
|
+ *
|
|
|
+ * Run: pnpm exec tsx scripts/verify-client-runtime-deps.ts [--json]
|
|
|
+ */
|
|
|
+
|
|
|
+import { existsSync, globSync, readFileSync } from 'node:fs'
|
|
|
+import { dirname, join, resolve } from 'node:path'
|
|
|
+import ts from 'typescript'
|
|
|
+import { TypeScriptProject, type CompilerFace } from './ts-project.ts'
|
|
|
+
|
|
|
+const root = resolve(import.meta.dirname, '..')
|
|
|
+
|
|
|
+/**
|
|
|
+ * `@deepseek-ai/cordis` placement belongs to check-workspace-constraints, which
|
|
|
+ * requires it as a peerDependency plus devDependency of every harness package
|
|
|
+ * regardless of face.
|
|
|
+ */
|
|
|
+const PLACEMENT_OWNED_ELSEWHERE = new Set(['@deepseek-ai/cordis'])
|
|
|
+
|
|
|
+/** Dependency sections npm installs for a consumer of the published package. */
|
|
|
+const INSTALLED_SECTIONS = ['dependencies', 'peerDependencies'] as const
|
|
|
+
|
|
|
+type Section = (typeof INSTALLED_SECTIONS)[number]
|
|
|
+
|
|
|
+interface Manifest {
|
|
|
+ name?: string
|
|
|
+ files?: string[]
|
|
|
+ exports?: Record<string, unknown>
|
|
|
+ dependencies?: Record<string, string>
|
|
|
+ peerDependencies?: Record<string, string>
|
|
|
+ peerDependenciesMeta?: Record<string, { optional?: boolean }>
|
|
|
+}
|
|
|
+
|
|
|
+/** How a package reaches the browser, which fixes the entries Node can load. */
|
|
|
+type Kind = 'bundle-half' | 'browser-library' | 'prebuilt-dist'
|
|
|
+
|
|
|
+/** What settles an external specifier as build-time only. */
|
|
|
+type Reached = 'browser' | 'nothing'
|
|
|
+
|
|
|
+interface Violation {
|
|
|
+ readonly section: Section
|
|
|
+ readonly dep: string
|
|
|
+ readonly reached: Reached
|
|
|
+ /** Whether the browser face names it, which decides dev-move versus deletion. */
|
|
|
+ readonly browserReferenced: boolean
|
|
|
+}
|
|
|
+
|
|
|
+interface Offender {
|
|
|
+ readonly name: string
|
|
|
+ readonly dir: string
|
|
|
+ readonly kind: Kind
|
|
|
+ readonly violations: Violation[]
|
|
|
+}
|
|
|
+
|
|
|
+/** Why each class needs no install, for the failure report. */
|
|
|
+const REASON: Record<Reached, string> = {
|
|
|
+ browser: 'only a browser artifact reaches it, and that resolves nothing on the user machine',
|
|
|
+ nothing: 'no reference names it at all',
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * Classify a package by the browser artifact it produces.
|
|
|
+ * @param dir - repository-relative package directory.
|
|
|
+ * @param manifest - the package manifest.
|
|
|
+ * @returns the package kind, or undefined when the package has no browser face.
|
|
|
+ */
|
|
|
+function kindOf(dir: string, manifest: Manifest): Kind | undefined {
|
|
|
+ if (manifest.exports?.['./client'] !== undefined) return 'bundle-half'
|
|
|
+ if (dir.startsWith('packages/client/')) return 'browser-library'
|
|
|
+ const shipsDist = (manifest.files ?? []).some(entry => entry === 'dist' || entry.startsWith('dist/'))
|
|
|
+ if (shipsDist && manifest.exports?.['.'] === undefined) return 'prebuilt-dist'
|
|
|
+ return undefined
|
|
|
+}
|
|
|
+
|
|
|
+/** The bare package name a specifier names, keeping a leading scope. */
|
|
|
+function packageOf(specifier: string): string {
|
|
|
+ const parts = specifier.split('/')
|
|
|
+ return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0] ?? specifier
|
|
|
+}
|
|
|
+
|
|
|
+/** One compiler face's bound program plus its module resolution state. */
|
|
|
+interface Face {
|
|
|
+ readonly project: TypeScriptProject
|
|
|
+ readonly host: ts.CompilerHost
|
|
|
+ readonly cache: ts.ModuleResolutionCache
|
|
|
+}
|
|
|
+
|
|
|
+const faces = new Map<CompilerFace, Face>()
|
|
|
+for (const face of ['host', 'client'] as const) {
|
|
|
+ const project = new TypeScriptProject(root, face)
|
|
|
+ const options = project.program.getCompilerOptions()
|
|
|
+ faces.set(face, {
|
|
|
+ project,
|
|
|
+ host: ts.createCompilerHost(options, false),
|
|
|
+ cache: ts.createModuleResolutionCache(root, fileName => fileName, options),
|
|
|
+ })
|
|
|
+}
|
|
|
+
|
|
|
+/** Which face's program bound each workspace module, keyed by absolute path. */
|
|
|
+const boundIn = new Map<string, CompilerFace>()
|
|
|
+for (const [face, { project }] of faces) {
|
|
|
+ for (const sourceFile of project.sourceFiles()) {
|
|
|
+ if (sourceFile.isDeclarationFile) continue
|
|
|
+ if (!boundIn.has(sourceFile.fileName)) boundIn.set(sourceFile.fileName, face)
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * Read every module specifier one source file names.
|
|
|
+ *
|
|
|
+ * An import clause is not the only way to reach a package: `require`,
|
|
|
+ * `require.resolve`, and a dynamic `import()` on a literal each name one, and a
|
|
|
+ * type-only import still names a package the build must resolve.
|
|
|
+ * @param sourceFile - a bound source file.
|
|
|
+ * @returns every specifier, relative ones included.
|
|
|
+ */
|
|
|
+function specifiersOf(sourceFile: ts.SourceFile): string[] {
|
|
|
+ const specifiers: string[] = []
|
|
|
+ const visit = (node: ts.Node): void => {
|
|
|
+ if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node) || ts.isImportEqualsDeclaration(node)) {
|
|
|
+ const specifier = ts.isImportEqualsDeclaration(node)
|
|
|
+ ? (ts.isExternalModuleReference(node.moduleReference) ? node.moduleReference.expression : undefined)
|
|
|
+ : node.moduleSpecifier
|
|
|
+ if (specifier !== undefined && ts.isStringLiteralLike(specifier)) specifiers.push(specifier.text)
|
|
|
+ } else if (ts.isCallExpression(node)) {
|
|
|
+ const target = node.expression
|
|
|
+ const isRequire = ts.isIdentifier(target) && target.text === 'require'
|
|
|
+ const isRequireResolve = ts.isPropertyAccessExpression(target)
|
|
|
+ && ts.isIdentifier(target.expression) && target.expression.text === 'require'
|
|
|
+ && target.name.text === 'resolve'
|
|
|
+ const argument = node.arguments[0]
|
|
|
+ if ((isRequire || isRequireResolve || target.kind === ts.SyntaxKind.ImportKeyword)
|
|
|
+ && argument !== undefined && ts.isStringLiteralLike(argument)) {
|
|
|
+ specifiers.push(argument.text)
|
|
|
+ }
|
|
|
+ }
|
|
|
+ ts.forEachChild(node, visit)
|
|
|
+ }
|
|
|
+ visit(sourceFile)
|
|
|
+ return specifiers
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * Walk one face from its entries and collect the packages it names.
|
|
|
+ * @param entries - absolute entry module paths.
|
|
|
+ * @param packageDir - absolute package directory; the walk stops at its edge.
|
|
|
+ * @returns package names the walk reaches.
|
|
|
+ */
|
|
|
+function walk(entries: readonly string[], packageDir: string): Set<string> {
|
|
|
+ const found = new Set<string>()
|
|
|
+ const seen = new Set<string>()
|
|
|
+ const queue = entries.filter(entry => boundIn.has(entry))
|
|
|
+ while (queue.length > 0) {
|
|
|
+ const file = queue.pop()
|
|
|
+ if (file === undefined || seen.has(file)) continue
|
|
|
+ seen.add(file)
|
|
|
+ const faceName = boundIn.get(file)
|
|
|
+ const face = faceName === undefined ? undefined : faces.get(faceName)
|
|
|
+ const sourceFile = face?.project.program.getSourceFile(file)
|
|
|
+ if (face === undefined || sourceFile === undefined) continue
|
|
|
+
|
|
|
+ for (const specifier of specifiersOf(sourceFile)) {
|
|
|
+ if (!specifier.startsWith('.')) {
|
|
|
+ if (!specifier.startsWith('node:')) found.add(packageOf(specifier))
|
|
|
+ continue
|
|
|
+ }
|
|
|
+ const resolved = ts.resolveModuleName(
|
|
|
+ specifier, file, face.project.program.getCompilerOptions(), face.host, face.cache,
|
|
|
+ ).resolvedModule?.resolvedFileName
|
|
|
+ // A relative specifier resolving outside the package is a packaging error
|
|
|
+ // verify-package-paths owns; either way it is not this package's own module.
|
|
|
+ if (resolved !== undefined && resolved.startsWith(`${packageDir}/`)) queue.push(resolved)
|
|
|
+ }
|
|
|
+ }
|
|
|
+ return found
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * The source module behind one published JavaScript export target.
|
|
|
+ *
|
|
|
+ * `lib/` holds the tsdown bundles and `lib/types/` the tsc emit, so both
|
|
|
+ * prefixes lead back to one `src` module.
|
|
|
+ * @param dir - absolute package directory.
|
|
|
+ * @param emitted - the export target, as written in the manifest.
|
|
|
+ * @returns the absolute source path, or undefined when nothing in `src` emits it.
|
|
|
+ */
|
|
|
+function sourceBehind(dir: string, emitted: string): string | undefined {
|
|
|
+ const stem = emitted.replace(/^\.\/lib\/types\//, '').replace(/^\.\/lib\//, '').replace(/\.js$/, '')
|
|
|
+ return [`src/${stem}.ts`, `src/${stem}.tsx`, `src/${stem}/index.ts`, `src/${stem}/index.tsx`]
|
|
|
+ .map(candidate => join(dir, candidate))
|
|
|
+ .find(candidate => existsSync(candidate))
|
|
|
+}
|
|
|
+
|
|
|
+interface Entries {
|
|
|
+ readonly host: string[]
|
|
|
+ readonly browser: string[]
|
|
|
+ /**
|
|
|
+ * Published JavaScript entries no `src` module emits — a generated artifact
|
|
|
+ * such as `lib/typert.host.js`, whose own runtime imports are invisible here.
|
|
|
+ */
|
|
|
+ readonly generated: string[]
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * The entry modules of each face, derived from what the manifest publishes.
|
|
|
+ * @param dir - absolute package directory.
|
|
|
+ * @param manifest - the package manifest.
|
|
|
+ * @param kind - the package kind.
|
|
|
+ * @returns absolute entry module paths per face, plus unmapped published entries.
|
|
|
+ */
|
|
|
+function faceEntries(dir: string, manifest: Manifest, kind: Kind): Entries {
|
|
|
+ if (kind === 'prebuilt-dist') return { host: [], browser: [], generated: [] }
|
|
|
+ if (kind === 'browser-library') {
|
|
|
+ return { host: [join(dir, 'src/invariant.ts')], browser: [join(dir, 'src/index.ts')], generated: [] }
|
|
|
+ }
|
|
|
+ const host = [join(dir, 'src/index.ts'), join(dir, 'src/invariant.ts')]
|
|
|
+ const browser: string[] = []
|
|
|
+ const generated: string[] = []
|
|
|
+ for (const [key, target] of Object.entries(manifest.exports ?? {})) {
|
|
|
+ if (key === '.' || key === './package.json' || key.includes('*')) continue
|
|
|
+ const emitted = typeof target === 'string' ? target : (target as { default?: unknown }).default
|
|
|
+ if (typeof emitted !== 'string' || !emitted.endsWith('.js')) continue
|
|
|
+ // Keyed on the artifact path, not the subpath name: `./client` is the tsdown
|
|
|
+ // browser bundle only when it resolves to lib/client.js, while other packages
|
|
|
+ // publish a plain browser-shared module under the same subpath.
|
|
|
+ const source = emitted === './lib/client.js'
|
|
|
+ ? sourceBehind(dir, './lib/client/index.js')
|
|
|
+ : sourceBehind(dir, emitted)
|
|
|
+ if (source === undefined) generated.push(`${key} -> ${emitted}`)
|
|
|
+ else if (key === './client') browser.push(source)
|
|
|
+ else host.push(source)
|
|
|
+ }
|
|
|
+ return { host, browser, generated }
|
|
|
+}
|
|
|
+
|
|
|
+/** Every installed dependency of a manifest, paired with its section. */
|
|
|
+function installedDeps(manifest: Manifest): { section: Section; dep: string }[] {
|
|
|
+ const deps: { section: Section; dep: string }[] = []
|
|
|
+ for (const section of INSTALLED_SECTIONS) {
|
|
|
+ for (const dep of Object.keys(manifest[section] ?? {})) {
|
|
|
+ if (section === 'peerDependencies' && manifest.peerDependenciesMeta?.[dep]?.optional === true) continue
|
|
|
+ if (PLACEMENT_OWNED_ELSEWHERE.has(dep)) continue
|
|
|
+ deps.push({ section, dep })
|
|
|
+ }
|
|
|
+ }
|
|
|
+ return deps
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * Test whether a Loader config names a package as a whole word.
|
|
|
+ * @param text - raw config text.
|
|
|
+ * @param dep - package name to look for.
|
|
|
+ * @returns true when the name appears outside a longer specifier.
|
|
|
+ */
|
|
|
+function namesPackage(text: string, dep: string): boolean {
|
|
|
+ const escaped = dep.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
|
|
|
+ return new RegExp(`(^|[^\\w@/.-])${escaped}(?![\\w.-])`).test(text)
|
|
|
+}
|
|
|
+
|
|
|
+interface Candidate {
|
|
|
+ readonly name: string
|
|
|
+ readonly relativeDir: string
|
|
|
+ readonly manifest: Manifest
|
|
|
+ readonly kind: Kind
|
|
|
+}
|
|
|
+
|
|
|
+const candidates: Candidate[] = []
|
|
|
+for (const path of [
|
|
|
+ ...globSync('packages/*/*/package.json', { cwd: root }),
|
|
|
+ ...globSync('apps/*/package.json', { cwd: root }),
|
|
|
+].sort()) {
|
|
|
+ const relativeDir = dirname(path)
|
|
|
+ const manifest = JSON.parse(readFileSync(join(root, path), 'utf8')) as Manifest
|
|
|
+ if (manifest.name === undefined) continue
|
|
|
+ const kind = kindOf(relativeDir, manifest)
|
|
|
+ if (kind !== undefined) candidates.push({ name: manifest.name, relativeDir, manifest, kind })
|
|
|
+}
|
|
|
+
|
|
|
+const offenders: Offender[] = []
|
|
|
+const unchecked: string[] = []
|
|
|
+for (const { name, relativeDir, manifest, kind } of candidates) {
|
|
|
+ const dir = join(root, relativeDir)
|
|
|
+ const entries = faceEntries(dir, manifest, kind)
|
|
|
+ // A generated Node entry carries runtime imports of its own that no source
|
|
|
+ // states, so this package's declarations cannot be judged from `src` alone.
|
|
|
+ if (entries.generated.length > 0) {
|
|
|
+ unchecked.push(`${name}: generated entry ${entries.generated.join(', ')}`)
|
|
|
+ continue
|
|
|
+ }
|
|
|
+ const host = walk(entries.host, dir)
|
|
|
+ const browser = walk(entries.browser, dir)
|
|
|
+ // A Loader row names its plugin package instead of importing it, so a config
|
|
|
+ // the package owns is part of its host face. YAML keys carry no quotes, so
|
|
|
+ // these are matched as whole names against the raw text.
|
|
|
+ const configs = globSync('cordis*.yml', { cwd: dir }).map(config => readFileSync(join(dir, config), 'utf8'))
|
|
|
+
|
|
|
+ const violations = installedDeps(manifest)
|
|
|
+ // A workspace name stays where the manifest puts it. Such a declaration also
|
|
|
+ // states which package supplies an injected service, which Remote contribution
|
|
|
+ // an assembly mounts, or which Loader row must resolve; the app installs the
|
|
|
+ // package regardless, so moving one saves no download while deleting what
|
|
|
+ // verify-runtime-closure and the Loader read. External packages are the
|
|
|
+ // download, and this gate is about the download.
|
|
|
+ .filter(({ dep }) => !dep.startsWith('@deepseek-ai/'))
|
|
|
+ .filter(({ dep }) => !host.has(dep) && !configs.some(text => namesPackage(text, dep)))
|
|
|
+ .map(({ section, dep }) => ({
|
|
|
+ section,
|
|
|
+ dep,
|
|
|
+ browserReferenced: browser.has(dep),
|
|
|
+ // A prebuilt bundle publishes no Node entry, so everything it declares is
|
|
|
+ // build-time by construction, named in its Vite graph rather than in src.
|
|
|
+ reached: kind === 'prebuilt-dist' || browser.has(dep) ? 'browser' as const : 'nothing' as const,
|
|
|
+ }))
|
|
|
+ if (violations.length > 0) offenders.push({ name, dir: relativeDir, kind, violations })
|
|
|
+}
|
|
|
+
|
|
|
+if (process.argv.includes('--json')) {
|
|
|
+ console.log(JSON.stringify(offenders, null, 2))
|
|
|
+ process.exit(0)
|
|
|
+}
|
|
|
+
|
|
|
+if (unchecked.length > 0) {
|
|
|
+ console.log(`verify-client-runtime-deps: ${String(unchecked.length)} package(s) not checked, no source states their entry's imports:`)
|
|
|
+ for (const entry of unchecked) console.log(` ${entry}`)
|
|
|
+}
|
|
|
+
|
|
|
+if (offenders.length > 0) {
|
|
|
+ const all = offenders.flatMap(offender => offender.violations)
|
|
|
+ console.error(`verify-client-runtime-deps: ${String(all.length)} build-time specifier(s) in installed sections:`)
|
|
|
+ for (const { name, dir, kind, violations } of offenders) {
|
|
|
+ console.error(` ${name} (${dir}, ${kind})`)
|
|
|
+ for (const { section, dep, reached } of violations) {
|
|
|
+ console.error(` ${section}.${dep} -> devDependencies [${reached}]`)
|
|
|
+ }
|
|
|
+ }
|
|
|
+ console.error('')
|
|
|
+ for (const reached of ['browser', 'nothing'] as const) {
|
|
|
+ const count = all.filter(violation => violation.reached === reached).length
|
|
|
+ if (count > 0) console.error(` ${String(count).padStart(4)} ${reached}: ${REASON[reached]}`)
|
|
|
+ }
|
|
|
+ console.error('\nDeclaration rules: packages/client/AGENTS.md.')
|
|
|
+ process.exit(1)
|
|
|
+}
|
|
|
+console.log(`verify-client-runtime-deps: browser-face specifiers are dev-only across ${String(candidates.length)} browser-facing packages.`)
|
imccyu