Merge branch 'worktree/jobs-api-review-3052' into worktree/jobs-api-review-3127
# Conflicts: # .agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml # docs/config-catalog.i18n.yaml # docs/event-producer-consumer.i18n.yaml # docs/module-graph.i18n.yaml # docs/subsystems/jobs.i18n.yaml # docs/subsystems/shell.i18n.yaml # docs/subsystems/shell.md # docs/subsystems/shell.zh.md # docs/tool-catalog.i18n.yaml # packages/api/session-controller/README.i18n.yaml # packages/context/tmux-context/tests/tmux-context.spec.ts # packages/e2b/e2b/tests/fixtures/composition/bin.ts # packages/extensions/tool-cordis/src/api-catalog.ts # packages/shell/bash-local/README.i18n.yaml # packages/shell/bash-local/README.md # packages/shell/bash-local/README.zh.md # packages/shell/bash-local/src/index.ts # packages/shell/bash-local/tests/executor.spec.ts # packages/shell/bash-sandbox/README.i18n.yaml # packages/shell/bash-sandbox/README.md # packages/shell/bash-sandbox/README.zh.md # packages/shell/bash-sandbox/src/index.ts # packages/shell/bash-sandbox/tests/bwrap.e2e.ts # packages/shell/bash-sandbox/tests/landlock.e2e.ts # packages/shell/bash-sandbox/tests/partial-landlock.spec.ts # packages/shell/bash-sandbox/tests/sandbox.spec.ts # packages/shell/bash-sandbox/tests/seatbelt.e2e.ts # packages/shell/pwsh-local/README.i18n.yaml # packages/shell/pwsh-local/README.md # packages/shell/pwsh-local/README.zh.md # packages/shell/pwsh-local/src/index.ts # packages/shell/pwsh-local/tests/executor.spec.ts # packages/shell/pwsh-sandbox/README.i18n.yaml # packages/shell/pwsh-sandbox/README.md # packages/shell/pwsh-sandbox/README.zh.md # packages/shell/pwsh-sandbox/src/index.ts # packages/shell/pwsh-sandbox/tests/sandbox.spec.ts # packages/shell/shell/README.i18n.yaml # packages/shell/shell/README.md # packages/shell/shell/README.zh.md # packages/shell/shell/src/index.ts # packages/shell/shell/tests/service.spec.ts # packages/shell/tool-bash/README.i18n.yaml # packages/shell/tool-bash/src/index.ts # packages/shell/tool-bash/tests/tools.spec.ts # packages/shell/tool-pwsh/README.i18n.yaml # packages/shell/tool-pwsh/src/index.ts # packages/shell/tool-pwsh/tests/background.spec.ts # packages/shell/tool-pwsh/tests/tools.spec.ts # packages/workflow/tool-workflow/README.i18n.yaml # packages/workflow/tool-workflow/package.json # packages/workflow/tool-workflow/tests/tool-workflow.spec.ts # snapshots/session/ptc-python-turn/system-prompt.expected.md
This commit is contained in:
commit
c2fb2bd4e8
4824 files changed
+860803
-61950
No files matched your search
@@ -1,18 +1,35 @@
|
||||
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
|
||||
import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
|
||||
import { createRequire } from 'node:module'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { dirname, join, resolve } from 'node:path'
|
||||
import { afterEach, describe, expect, it } from 'vitest'
|
||||
import { afterEach, describe, expect, it, vi } from 'vitest'
|
||||
import { browserBundledExternals, browserPackageOfFile, browserSourceAliases } from './browser-bundled-externals.ts'
|
||||
|
||||
const filesystem = vi.hoisted(() => ({ preservedAlias: undefined as string | undefined }))
|
||||
vi.mock('node:fs', async (importOriginal) => {
|
||||
const actual = await importOriginal<typeof import('node:fs')>()
|
||||
return {
|
||||
...actual,
|
||||
realpathSync: Object.assign((...args: Parameters<typeof actual.realpathSync>) => {
|
||||
// Windows' JavaScript realpath can retain an 8.3 alias that Vite's native resolution expands.
|
||||
if (typeof args[0] === 'string' && args[0] === filesystem.preservedAlias) return args[0]
|
||||
return actual.realpathSync(...args)
|
||||
}, { native: actual.realpathSync.native }),
|
||||
}
|
||||
})
|
||||
|
||||
const roots: string[] = []
|
||||
const dependencyLinks: string[] = []
|
||||
const repositoryRoot = resolve(import.meta.dirname, '..')
|
||||
|
||||
afterEach(() => {
|
||||
filesystem.preservedAlias = undefined
|
||||
for (const link of dependencyLinks.splice(0)) unlinkSync(link)
|
||||
for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
|
||||
})
|
||||
|
||||
function fixture(): string {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-browser-notices-'))
|
||||
const root = realpathSync.native(mkdtempSync(join(tmpdir(), 'dsh-browser-notices-')))
|
||||
roots.push(root)
|
||||
write(root, 'package.json', '{"type":"module"}')
|
||||
write(root, 'tsconfig.base.json', JSON.stringify({
|
||||
@@ -78,7 +95,10 @@ describe('browser dependency discovery', () => {
|
||||
await expect(browserBundledExternals(root)).rejects.toThrow('has no browser build config')
|
||||
})
|
||||
|
||||
it('follows shell workspace aliases, CSS assets and lazy imports without writing output', async () => {
|
||||
it.each([
|
||||
['Rollup', false, false], ['Rollup', true, false], ['Rollup', true, true],
|
||||
['Rolldown', false, false], ['Rolldown', true, false], ['Rolldown', true, true],
|
||||
] as const)('follows shell aliases, CSS and lazy imports without writing output (%s, symlinked root: %s, retained alias: %s)', async (bundler, linked, preserveAlias) => {
|
||||
const root = fixture()
|
||||
library(root, 'shell-lib')
|
||||
library(root, 'lazy-lib')
|
||||
@@ -96,15 +116,42 @@ describe('browser dependency discovery', () => {
|
||||
].join('\n'))
|
||||
const app = join(root, 'apps/web')
|
||||
write(root, 'apps/web/package.json', '{"name":"@fixture/web","type":"module","exports":{"./dist/*":"./dist/*"}}')
|
||||
symlinkSync(resolve(repositoryRoot, 'apps/web/node_modules'), join(app, 'node_modules'), 'junction')
|
||||
const owner = bundler === 'Rollup' ? resolve(repositoryRoot, 'apps/web/package.json')
|
||||
: createRequire(resolve(repositoryRoot, 'package.json')).resolve('vitest/package.json')
|
||||
const viteDirectory = dirname(createRequire(owner).resolve('vite/package.json'))
|
||||
const viteLink = join(app, 'node_modules/vite')
|
||||
mkdirSync(dirname(viteLink), { recursive: true })
|
||||
symlinkSync(viteDirectory, viteLink, 'junction')
|
||||
dependencyLinks.push(viteLink)
|
||||
write(root, 'apps/web/index.html', '<script type="module" src="./main.ts"></script>')
|
||||
write(root, 'apps/web/main.ts', 'import { output, lazy } from "@fixture/static"; console.log(output); void lazy()')
|
||||
write(root, 'apps/web/vite.config.ts', `export default {
|
||||
build: { rollupOptions: { input: { index: ${JSON.stringify(join(app, 'index.html'))}, preview: "missing-preview.ts" } } }
|
||||
}`)
|
||||
write(root, 'apps/web/vite.config.ts', `
|
||||
import { productWebBundleIsolation } from ${JSON.stringify(resolve(repositoryRoot, 'apps/web/product-isolation.ts').replaceAll('\\', '/'))}
|
||||
export default ({ mode }) => {
|
||||
if (mode !== 'production') throw new Error('notice discovery must use the production build mode')
|
||||
return {
|
||||
plugins: [...productWebBundleIsolation(${JSON.stringify(root)}, ${JSON.stringify(app)}), {
|
||||
name: 'fixture-bundler-engine',
|
||||
generateBundle() {
|
||||
const actual = typeof this.meta.rolldownVersion === 'string' ? 'Rolldown' : 'Rollup'
|
||||
if (actual !== ${JSON.stringify(bundler)}) throw new Error('unexpected bundler: ' + actual)
|
||||
},
|
||||
}],
|
||||
build: { rollupOptions: { input: { index: ${JSON.stringify(join(app, 'index.html'))}, preview: "missing-preview.ts" } } }
|
||||
}
|
||||
}
|
||||
`)
|
||||
write(root, 'apps/web/dist/sentinel.txt', 'untouched')
|
||||
|
||||
expect(await browserBundledExternals(root)).toEqual(new Set(['shell-lib', 'lazy-lib', 'asset-lib']))
|
||||
const scanRoot = linked ? join(fixture(), 'linked') : root
|
||||
if (linked) symlinkSync(root, scanRoot, 'junction')
|
||||
if (preserveAlias) filesystem.preservedAlias = scanRoot
|
||||
try {
|
||||
expect(await browserBundledExternals(scanRoot)).toEqual(new Set(['shell-lib', 'lazy-lib', 'asset-lib']))
|
||||
} finally {
|
||||
filesystem.preservedAlias = undefined
|
||||
if (linked) unlinkSync(scanRoot)
|
||||
}
|
||||
expect(readFileSync(join(app, 'dist/sentinel.txt'), 'utf8')).toBe('untouched')
|
||||
expect(existsSync(join(app, 'dist/index.html'))).toBe(false)
|
||||
expect(existsSync(join(root, 'packages/client/static/lib'))).toBe(false)
|
||||
|
||||
@@ -1,11 +1,12 @@
|
||||
/** Resolve direct third-party browser inputs through the shipping build configurations, without emitting files. */
|
||||
|
||||
import { globSync, readFileSync } from 'node:fs'
|
||||
import { globSync, readFileSync, realpathSync } from 'node:fs'
|
||||
import { createRequire } from 'node:module'
|
||||
import { dirname, resolve } from 'node:path'
|
||||
import { pathToFileURL } from 'node:url'
|
||||
import { Rolldown, type UserConfigExport } from 'tsdown'
|
||||
import ts from 'typescript'
|
||||
import { browserDependencyAnalysis } from '../apps/web/product-isolation.ts'
|
||||
|
||||
interface Manifest {
|
||||
name: string
|
||||
@@ -117,7 +118,9 @@ interface ShellConfig {
|
||||
}
|
||||
|
||||
interface ViteApi {
|
||||
resolveConfig(config: Record<string, unknown>, command: 'build'): Promise<ShellConfig>
|
||||
resolveConfig(
|
||||
config: Record<string, unknown>, command: 'build', defaultMode: string, defaultNodeEnv: string,
|
||||
): Promise<ShellConfig>
|
||||
build(config: Record<string, unknown>): Promise<unknown>
|
||||
}
|
||||
|
||||
@@ -132,7 +135,7 @@ async function collectShell(
|
||||
if (manifest.private === true || manifest.exports?.['./dist/*'] === undefined) continue
|
||||
const vitePath = createRequire(resolve(dir, 'package.json')).resolve('vite')
|
||||
const vite = await import(pathToFileURL(vitePath).href) as ViteApi
|
||||
const config = await vite.resolveConfig({ root: dir, logLevel: 'error' }, 'build')
|
||||
const config = await vite.resolveConfig({ root: dir, logLevel: 'error' }, 'build', 'production', 'production')
|
||||
const input = config.build.rollupOptions?.input
|
||||
const entries = typeof input === 'string' ? [input] : Object.values(input ?? {})
|
||||
const pages = entries.filter(entry => entry.endsWith('.html'))
|
||||
@@ -140,7 +143,7 @@ async function collectShell(
|
||||
await vite.build({
|
||||
root: dir,
|
||||
logLevel: 'error',
|
||||
plugins: [recorder(seen, workspaceNames, true)],
|
||||
plugins: [browserDependencyAnalysis(), recorder(seen, workspaceNames, true)],
|
||||
resolve: { alias: browserSourceAliases(root) },
|
||||
build: {
|
||||
write: false,
|
||||
@@ -159,10 +162,12 @@ async function collectShell(
|
||||
|
||||
/**
|
||||
* Direct third-party packages resolved by published browser builds.
|
||||
* @param root - Repository root with installed build dependencies; lib/ is not required.
|
||||
* @param root - Repository root, possibly symlinked, with installed build dependencies; lib/ is not required.
|
||||
* @returns Names of distributed browser inputs, excluding workspace packages and erased types.
|
||||
*/
|
||||
export async function browserBundledExternals(root: string): Promise<Set<string>> {
|
||||
// Vite resolves HTML through native realpath, including Windows 8.3 alias expansion.
|
||||
root = realpathSync.native(root)
|
||||
const manifests = new Map<string, Manifest>()
|
||||
for (const glob of ['packages/*/*/package.json', 'vendor/*/package.json']) {
|
||||
for (const path of globSync(glob, { cwd: root }).sort()) {
|
||||
|
||||
@@ -0,0 +1,141 @@
|
||||
import { chmod, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { dirname, join } from 'node:path'
|
||||
import { afterEach, expect, it } from 'vitest'
|
||||
import { copyOfficeSidecar } from './build-exe-for-python-sdk-office.ts'
|
||||
|
||||
const temporaryDirectories: string[] = []
|
||||
|
||||
afterEach(async () => {
|
||||
await Promise.all(temporaryDirectories.splice(0).map(directory => rm(directory, { recursive: true, force: true })))
|
||||
})
|
||||
|
||||
async function fixture() {
|
||||
const root = await mkdtemp(join(tmpdir(), 'dsh-python-office-'))
|
||||
temporaryDirectories.push(root)
|
||||
const staging = join(root, 'staging')
|
||||
const destination = join(root, 'runtime-office')
|
||||
async function packageAt(name: string, fields: Record<string, unknown> = {}, parent = staging) {
|
||||
const directory = join(parent, 'node_modules', name)
|
||||
await mkdir(directory, { recursive: true })
|
||||
await writeFile(join(directory, 'package.json'), JSON.stringify({ name, version: '1.0.0', ...fields }))
|
||||
return directory
|
||||
}
|
||||
return { root, staging, destination, packageAt }
|
||||
}
|
||||
|
||||
it('copies package-owned data, licenses, helper permissions, and nested dependencies', async () => {
|
||||
const { staging, destination, packageAt } = await fixture()
|
||||
const entry = await packageAt('@deepseek-ai/libreoffice-kit', { optionalDependencies: { '@deepseek-ai/libreoffice-kit-wasm': '0.0.1' }, dependencies: { decoder: '1' } })
|
||||
const engine = await packageAt('@deepseek-ai/libreoffice-kit-wasm')
|
||||
const decoder = await packageAt('decoder', { dependencies: { codec: '1' } }, entry)
|
||||
await packageAt('codec', {}, decoder)
|
||||
await packageAt('codec', { version: '2.0.0' })
|
||||
const assets = ['assets/soffice.data', 'prebuilds.json', 'licenses/LICENSE', 'bin/helper']
|
||||
for (const name of assets) {
|
||||
const path = join(engine, name)
|
||||
await mkdir(dirname(path), { recursive: true })
|
||||
await writeFile(path, name)
|
||||
}
|
||||
await chmod(join(engine, 'bin/helper'), 0o755)
|
||||
|
||||
const packages = await copyOfficeSidecar(staging, destination, { platform: 'linux', arch: 'x64' })
|
||||
|
||||
expect(packages).toHaveLength(4)
|
||||
expect(await readFile(join(destination, 'node_modules/@deepseek-ai/libreoffice-kit-wasm/assets/soffice.data'), 'utf8')).toBe('assets/soffice.data')
|
||||
expect(await readFile(join(destination, 'node_modules/@deepseek-ai/libreoffice-kit-wasm/licenses/LICENSE'), 'utf8')).toBe('licenses/LICENSE')
|
||||
expect(await readFile(join(destination, 'node_modules/@deepseek-ai/libreoffice-kit/node_modules/decoder/node_modules/codec/package.json'), 'utf8')).toContain('codec')
|
||||
await expect(stat(join(destination, 'node_modules/codec'))).rejects.toMatchObject({ code: 'ENOENT' })
|
||||
if (process.platform !== 'win32') expect((await stat(join(destination, 'node_modules/@deepseek-ai/libreoffice-kit-wasm/bin/helper'))).mode & 0o111).toBe(0o111)
|
||||
})
|
||||
|
||||
it('copies installed target optionals and leaves other platforms and absent optionals out', async () => {
|
||||
const { staging, destination, packageAt } = await fixture()
|
||||
await packageAt('@deepseek-ai/libreoffice-kit', {
|
||||
optionalDependencies: { native: '1', foreign: '1', absent: '1' },
|
||||
})
|
||||
await packageAt('@deepseek-ai/libreoffice-kit-wasm')
|
||||
await packageAt('native', { os: ['linux'], cpu: ['x64'] })
|
||||
await packageAt('foreign', { os: ['darwin'], cpu: ['arm64'] })
|
||||
|
||||
const packages = await copyOfficeSidecar(staging, destination, { platform: 'linux', arch: 'x64' })
|
||||
|
||||
expect(packages.map(path => path.replaceAll('\\', '/'))).toEqual([
|
||||
'node_modules/@deepseek-ai/libreoffice-kit',
|
||||
'node_modules/@deepseek-ai/libreoffice-kit-wasm',
|
||||
'node_modules/native',
|
||||
])
|
||||
})
|
||||
|
||||
it('rejects a missing required dependency before producing a sidecar', async () => {
|
||||
const { staging, destination, packageAt } = await fixture()
|
||||
await packageAt('@deepseek-ai/libreoffice-kit', { dependencies: { 'dsh-missing-office-fixture': '1' } })
|
||||
|
||||
await expect(copyOfficeSidecar(staging, destination, { platform: 'linux', arch: 'x64' }))
|
||||
.rejects.toThrow('dsh-missing-office-fixture required by @deepseek-ai/libreoffice-kit is missing')
|
||||
await expect(stat(destination)).rejects.toMatchObject({ code: 'ENOENT' })
|
||||
})
|
||||
|
||||
it('rejects an incomplete installed optional instead of omitting it', async () => {
|
||||
const { staging, destination, packageAt } = await fixture()
|
||||
await packageAt('@deepseek-ai/libreoffice-kit', { optionalDependencies: { broken: '1' } })
|
||||
await mkdir(join(staging, 'node_modules/broken'), { recursive: true })
|
||||
|
||||
await expect(copyOfficeSidecar(staging, destination, { platform: 'linux', arch: 'x64' }))
|
||||
.rejects.toMatchObject({ code: 'ENOENT' })
|
||||
})
|
||||
|
||||
it('rejects an ancestor dependency outside the deployed closure', async () => {
|
||||
const { root, staging, destination, packageAt } = await fixture()
|
||||
await packageAt('@deepseek-ai/libreoffice-kit', { dependencies: { 'ancestor-office-fixture': '1' } })
|
||||
await packageAt('ancestor-office-fixture', {}, root)
|
||||
|
||||
await expect(copyOfficeSidecar(staging, destination, { platform: 'linux', arch: 'x64' }))
|
||||
.rejects.toThrow('outside the deployed closure')
|
||||
})
|
||||
|
||||
it('requires the declared WASM engine inside the deployed closure', async () => {
|
||||
const { root, staging, destination, packageAt } = await fixture()
|
||||
await packageAt('@deepseek-ai/libreoffice-kit', { optionalDependencies: { '@deepseek-ai/libreoffice-kit-wasm': '0.0.1' } })
|
||||
await packageAt('@deepseek-ai/libreoffice-kit-wasm', {}, root)
|
||||
await expect(copyOfficeSidecar(staging, destination, { platform: 'linux', arch: 'x64' }))
|
||||
.rejects.toThrow('Python Office engine @deepseek-ai/libreoffice-kit-wasm required for linux/x64 is missing.')
|
||||
await expect(stat(destination)).rejects.toMatchObject({ code: 'ENOENT' })
|
||||
})
|
||||
|
||||
it.each([
|
||||
['darwin', 'arm64', 'darwin-arm64'], ['darwin', 'x64', 'darwin-x64'],
|
||||
['win32', 'arm64', 'win32-arm64'], ['win32', 'x64', 'win32-x64'],
|
||||
['linux', 'x64', 'linux-x64'], ['linux', 'arm64', 'wasm'], ['freebsd', 'x64', 'wasm'],
|
||||
])('copies only the %s/%s engine even when other engines are staged', async (platform, arch, selected) => {
|
||||
const { staging, destination, packageAt } = await fixture()
|
||||
const targets = ['darwin-arm64', 'darwin-x64', 'win32-arm64', 'win32-x64', 'linux-x64', 'wasm']
|
||||
const names = targets.map(target => `@deepseek-ai/libreoffice-kit-${target}`)
|
||||
await packageAt('@deepseek-ai/libreoffice-kit', { optionalDependencies: Object.fromEntries(names.map(name => [name, '0.0.1'])) })
|
||||
for (const name of names) await packageAt(name)
|
||||
const expected = `@deepseek-ai/libreoffice-kit-${selected}`
|
||||
const packages = await copyOfficeSidecar(staging, destination, { platform, arch })
|
||||
expect(packages.map(path => path.replaceAll('\\', '/'))).toEqual([
|
||||
'node_modules/@deepseek-ai/libreoffice-kit', `node_modules/${expected}`,
|
||||
])
|
||||
})
|
||||
|
||||
it.each(['darwin', 'win32', 'linux'])('%s requires its native package even when WASM is staged', async (platform) => {
|
||||
const { staging, destination, packageAt } = await fixture()
|
||||
await packageAt('@deepseek-ai/libreoffice-kit', { optionalDependencies: {
|
||||
'@deepseek-ai/libreoffice-kit-wasm': '0.0.1', [`@deepseek-ai/libreoffice-kit-${platform}-arm64`]: '0.0.1',
|
||||
} })
|
||||
await packageAt('@deepseek-ai/libreoffice-kit-wasm')
|
||||
await expect(copyOfficeSidecar(staging, destination, { platform, arch: 'arm64' }))
|
||||
.rejects.toThrow(`Python Office engine @deepseek-ai/libreoffice-kit-${platform}-arm64 required for ${platform}/arm64 is missing.`)
|
||||
await expect(stat(destination)).rejects.toMatchObject({ code: 'ENOENT' })
|
||||
})
|
||||
|
||||
it('requires a staged Linux WASM engine even when an ancestor has one', async () => {
|
||||
const { root, staging, destination, packageAt } = await fixture()
|
||||
await packageAt('@deepseek-ai/libreoffice-kit')
|
||||
await packageAt('@deepseek-ai/libreoffice-kit-wasm', {}, root)
|
||||
await expect(copyOfficeSidecar(staging, destination, { platform: 'linux', arch: 'x64' }))
|
||||
.rejects.toThrow('Python Office engine @deepseek-ai/libreoffice-kit-wasm required for linux/x64 is missing.')
|
||||
await expect(stat(destination)).rejects.toMatchObject({ code: 'ENOENT' })
|
||||
})
|
||||
@@ -0,0 +1,97 @@
|
||||
/** Keep LibreOffice workers, prebuilt engines, and their dependencies on the real filesystem. */
|
||||
import { existsSync } from 'node:fs'
|
||||
import { cp, mkdir, readFile, rm } from 'node:fs/promises'
|
||||
import { createRequire } from 'node:module'
|
||||
import { isAbsolute, join, relative, sep } from 'node:path'
|
||||
import { selectOfficeEngine } from './libreoffice-engine.ts'
|
||||
|
||||
/** pkg applies these exclusions to dependency `files` as well as root asset globs. */
|
||||
export const OFFICE_ASSET_IGNORES = [
|
||||
'**/node_modules/@deepseek-ai/libreoffice-kit/**',
|
||||
'**/node_modules/@deepseek-ai/libreoffice-kit-*/**',
|
||||
]
|
||||
|
||||
interface PackageManifest {
|
||||
name: string
|
||||
dependencies?: Record<string, string>
|
||||
optionalDependencies?: Record<string, string>
|
||||
peerDependencies?: Record<string, string>
|
||||
peerDependenciesMeta?: Record<string, { optional?: boolean }>
|
||||
os?: string[]
|
||||
cpu?: string[]
|
||||
}
|
||||
|
||||
/**
|
||||
* Copy the installed Office dependency tree without changing package contents or executable modes.
|
||||
* Harness sidecars require the kit's declared target native engine, or WASM for other targets.
|
||||
* Missing target engines fail with their package name; missing required dependencies or paths outside the deployed closure also fail.
|
||||
* @param staging - Symlink-free deployed Node closure.
|
||||
* @param destination - Target-specific Office directory beside the executable; replaced when present.
|
||||
* @param target - Node platform and CPU of the executable.
|
||||
* @returns Relative package directories included in the sidecar.
|
||||
*/
|
||||
export async function copyOfficeSidecar(
|
||||
staging: string,
|
||||
destination: string,
|
||||
target: { platform: string; arch: string },
|
||||
): Promise<string[]> {
|
||||
const entry = join(staging, 'node_modules', '@deepseek-ai', 'libreoffice-kit')
|
||||
const manifest = JSON.parse(await readFile(join(entry, 'package.json'), 'utf8')) as PackageManifest
|
||||
const engineName = `@deepseek-ai/libreoffice-kit-${selectOfficeEngine(manifest, target)}`
|
||||
const packages = new Set<string>()
|
||||
|
||||
async function visit(packageDirectory: string): Promise<void> {
|
||||
if (packages.has(packageDirectory)) return
|
||||
const relativeDirectory = relative(staging, packageDirectory)
|
||||
if (isAbsolute(relativeDirectory) || relativeDirectory === '..' || relativeDirectory.startsWith(`..${sep}`)) {
|
||||
throw new Error(`Python Office dependency is outside the deployed closure: ${packageDirectory}`)
|
||||
}
|
||||
const manifestPath = join(packageDirectory, 'package.json')
|
||||
const manifest = JSON.parse(await readFile(manifestPath, 'utf8')) as PackageManifest
|
||||
packages.add(packageDirectory)
|
||||
const require = createRequire(manifestPath)
|
||||
const dependencies = new Set([
|
||||
...Object.keys(manifest.dependencies ?? {}),
|
||||
...Object.keys(manifest.optionalDependencies ?? {}),
|
||||
...Object.keys(manifest.peerDependencies ?? {}),
|
||||
])
|
||||
for (const name of dependencies) {
|
||||
if (name.startsWith('@deepseek-ai/libreoffice-kit-')) continue
|
||||
const optional = manifest.optionalDependencies?.[name] !== undefined
|
||||
|| manifest.peerDependenciesMeta?.[name]?.optional === true
|
||||
const dependencyDirectory = (require.resolve.paths(name) ?? [])
|
||||
.map(directory => join(directory, name))
|
||||
.find(directory => existsSync(directory))
|
||||
if (dependencyDirectory === undefined) {
|
||||
if (optional) continue
|
||||
throw new Error(`Python Office dependency ${name} required by ${manifest.name} is missing.`)
|
||||
}
|
||||
if (optional) {
|
||||
const dependency = JSON.parse(await readFile(join(dependencyDirectory, 'package.json'), 'utf8')) as PackageManifest
|
||||
if (!supports(dependency.os, target.platform) || !supports(dependency.cpu, target.arch)) continue
|
||||
}
|
||||
await visit(dependencyDirectory)
|
||||
}
|
||||
}
|
||||
|
||||
await visit(entry)
|
||||
const engineDirectory = join(staging, 'node_modules', engineName)
|
||||
if (!existsSync(engineDirectory)) throw new Error(`Python Office engine ${engineName} required for ${target.platform}/${target.arch} is missing.`)
|
||||
await visit(engineDirectory)
|
||||
await rm(destination, { recursive: true, force: true })
|
||||
await mkdir(destination, { recursive: true })
|
||||
const directories = [...packages].sort()
|
||||
for (const source of directories) {
|
||||
const nestedModules = join(source, 'node_modules')
|
||||
await cp(source, join(destination, relative(staging, source)), {
|
||||
recursive: true,
|
||||
filter: path => path !== nestedModules && !path.startsWith(nestedModules + sep),
|
||||
})
|
||||
}
|
||||
return directories.map(directory => relative(staging, directory))
|
||||
}
|
||||
|
||||
function supports(values: string[] | undefined, value: string): boolean {
|
||||
return values === undefined || (!values.includes(`!${value}`)
|
||||
&& (values.every(item => item.startsWith('!')) || values.includes(value) || values.includes('any')))
|
||||
}
|
||||
@@ -60,6 +60,9 @@ describe('Python runtime executable builder CLI', () => {
|
||||
expect(result.status).toBe(0)
|
||||
expect(result.stdout).toContain(`${process.execPath} C:\\tools\\pnpm.cjs run verify-runtime-closure`)
|
||||
expect(result.stdout).toContain(`${process.execPath} C:\\tools\\pnpm.cjs --filter dsh-python-runtime-closure deploy`)
|
||||
const deploy = result.stdout.split('\n').find(line => line.includes(' --filter dsh-python-runtime-closure deploy'))
|
||||
expect(deploy).toContain('--prod --config.allow-unused-patches=true')
|
||||
expect(result.stdout.split('--config.allow-unused-patches=true')).toHaveLength(2)
|
||||
expect(result.stdout).not.toContain(resolve(root, 'python/sdk-runtime/runtime-bootstrap.mjs'))
|
||||
expect(result.stdout).toContain('"bin":"runtime-bootstrap.mjs"')
|
||||
expect(result.stdout).toContain(`${process.execPath} C:\\tools\\pnpm.cjs exec pkg`)
|
||||
|
||||
@@ -12,6 +12,7 @@ import { chmod, copyFile, cp, lstat, mkdir, readFile, readdir, realpath, rm, wri
|
||||
import { basename, dirname, extname, join, resolve, sep } from 'node:path'
|
||||
import { parseArgs } from 'node:util'
|
||||
import { resolveLinuxNodePtyAddon, resolveWindowsNodePtyAddons } from './build-exe-for-python-sdk-native-pty.ts'
|
||||
import { copyOfficeSidecar, OFFICE_ASSET_IGNORES } from './build-exe-for-python-sdk-office.ts'
|
||||
|
||||
const root = resolve(import.meta.dirname, '..')
|
||||
|
||||
@@ -292,6 +293,8 @@ class SingleExeBuild {
|
||||
'deploy',
|
||||
'--legacy',
|
||||
'--prod',
|
||||
// Production deployment omits workspace tooling such as Electron's patched signer.
|
||||
'--config.allow-unused-patches=true',
|
||||
'--config.node-linker=hoisted',
|
||||
'--config.auto-install-peers=false',
|
||||
'--config.link-workspace-packages=true',
|
||||
@@ -396,7 +399,7 @@ class SingleExeBuild {
|
||||
|
||||
/** Add the executable entry and pkg assets to the staged manifest. */
|
||||
async injectPkgConfig(): Promise<void> {
|
||||
const patch = { bin: ENTRY_BIN, pkg: { assets: ASSET_GLOBS } }
|
||||
const patch = { bin: ENTRY_BIN, pkg: { assets: ASSET_GLOBS, ignore: OFFICE_ASSET_IGNORES } }
|
||||
const manifestPath = join(this.staging, 'package.json')
|
||||
if (this.cli.dryRun) {
|
||||
console.log(`build-exe-for-python-sdk: [dry-run] patch ${manifestPath} with ${JSON.stringify(patch)}`)
|
||||
@@ -416,7 +419,7 @@ class SingleExeBuild {
|
||||
/**
|
||||
* Package one target; SEA mode accepts one target per invocation.
|
||||
* @param target - the pkg target triple to build.
|
||||
* @returns the executable and ripgrep sidecar paths, plus the macOS spawn helper path when required.
|
||||
* @returns the executable, Office directory, ripgrep, and required macOS spawn helper paths.
|
||||
*/
|
||||
async pack(target: Target): Promise<string[]> {
|
||||
const productBase = join(this.outDir, `${OUTPUT_BASENAME}-${target.platform}-${target.arch}`)
|
||||
@@ -436,8 +439,16 @@ class SingleExeBuild {
|
||||
if (!this.cli.dryRun && !existsSync(product)) {
|
||||
throw new Error(`build-exe-for-python-sdk: product ${product} is missing after the pkg run; inspect ${this.outDir}.`)
|
||||
}
|
||||
const office = `${productBase}-office`
|
||||
if (this.cli.dryRun) {
|
||||
console.log(`build-exe-for-python-sdk: [dry-run] copy Office dependency closure from ${this.staging} to ${office}`)
|
||||
} else {
|
||||
const platform = target.platform === 'macos' ? 'darwin' : target.platform === 'win' ? 'win32' : target.platform
|
||||
const packages = await copyOfficeSidecar(this.staging, office, { platform, arch: target.arch })
|
||||
console.log(`build-exe-for-python-sdk: copied ${packages.length} Office packages to ${office}`)
|
||||
}
|
||||
const ripgrep = await this.copyRipgrepSidecar(target, product)
|
||||
if (target.platform !== 'macos') return [product, ripgrep]
|
||||
if (target.platform !== 'macos') return [product, ripgrep, office]
|
||||
const spawnHelper = `${product}-spawn-helper`
|
||||
const source = join(this.staging, 'node_modules', 'node-pty', 'prebuilds', `darwin-${target.arch}`, 'spawn-helper')
|
||||
if (this.cli.dryRun) {
|
||||
@@ -446,7 +457,7 @@ class SingleExeBuild {
|
||||
await copyFile(source, spawnHelper)
|
||||
await chmod(spawnHelper, 0o755)
|
||||
}
|
||||
return [product, ripgrep, spawnHelper]
|
||||
return [product, ripgrep, spawnHelper, office]
|
||||
}
|
||||
|
||||
/** Copy the target ripgrep binary beside the executable so Node can spawn it outside pkg's virtual filesystem. */
|
||||
@@ -536,6 +547,10 @@ class SingleExeBuild {
|
||||
console.log(` ${path}`)
|
||||
continue
|
||||
}
|
||||
if (statSync(path).isDirectory()) {
|
||||
console.log(` ${path} (Office dependency directory)`)
|
||||
continue
|
||||
}
|
||||
const megabytes = statSync(path).size / (1024 * 1024)
|
||||
console.log(` ${path} (${megabytes.toFixed(1)} MB)`)
|
||||
}
|
||||
@@ -557,7 +572,10 @@ class SingleExeBuild {
|
||||
await mkdir(destDir, { recursive: true })
|
||||
for (const path of products) {
|
||||
const destination = join(destDir, basename(path))
|
||||
await copyFile(path, destination)
|
||||
if (statSync(path).isDirectory()) {
|
||||
await rm(destination, { recursive: true, force: true })
|
||||
await cp(path, destination, { recursive: true })
|
||||
} else await copyFile(path, destination)
|
||||
await chmod(destination, statSync(path).mode & 0o777)
|
||||
console.log(`build-exe-for-python-sdk: synced ${destination}`)
|
||||
}
|
||||
|
||||
@@ -55,6 +55,11 @@ def runtime_filenames(executable_name: str) -> tuple[str, ...]:
|
||||
return (*names, f"{executable_name}-spawn-helper") if "-macos-" in executable_name else names
|
||||
|
||||
|
||||
def office_sidecar_name(executable_name: str) -> str:
|
||||
"""Return the complete Office dependency directory for one executable."""
|
||||
return f"{executable_name.removesuffix('.exe')}-office"
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--package", choices=("sdk", "runtime"), required=True)
|
||||
@@ -220,6 +225,44 @@ def stage_runtime(destination: Path, version: str, executable: Path, executable_
|
||||
source_directory = executable.parent
|
||||
for filename in runtime_filenames(executable_name):
|
||||
shutil.copy2(source_directory / filename, runtime_dir / filename)
|
||||
office = office_sidecar_name(executable_name)
|
||||
shutil.copytree(source_directory / office, runtime_dir / office)
|
||||
|
||||
|
||||
def verify_office_payload(archive: zipfile.ZipFile, office_modules: str, platform_tag: str) -> None:
|
||||
"""Check packaged engine assets and native helper executable permissions."""
|
||||
names = set(archive.namelist())
|
||||
adapter = f"{office_modules}/@deepseek-ai/libreoffice-kit/package.json"
|
||||
if adapter not in names:
|
||||
raise RuntimeError("Office dependency is missing: libreoffice-kit")
|
||||
engines = f"{office_modules}/@deepseek-ai"
|
||||
target = next(name for name, value in PLATFORMS.items() if value[0] == platform_tag)
|
||||
native_target = target.replace("win-", "win32-").replace("macos-", "darwin-")
|
||||
declared = json.loads(archive.read(adapter)).get("optionalDependencies", {})
|
||||
selected = native_target if f"@deepseek-ai/libreoffice-kit-{native_target}" in declared else "wasm"
|
||||
for required in (f"libreoffice-kit-{selected}/prebuilds.json",):
|
||||
if f"{engines}/{required}" not in names:
|
||||
raise RuntimeError(f"Office dependency is missing: {required}")
|
||||
manifests = (
|
||||
name for name in names
|
||||
if name.startswith(f"{engines}/libreoffice-kit-")
|
||||
and name.endswith("/prebuilds.json")
|
||||
and name.count("/") == engines.count("/") + 2
|
||||
)
|
||||
for manifest_path in manifests:
|
||||
if manifest_path != f"{engines}/libreoffice-kit-{selected}/prebuilds.json":
|
||||
raise RuntimeError(f"Unexpected Office engine for {platform_tag}: {manifest_path}")
|
||||
manifest = json.loads(archive.read(manifest_path))
|
||||
engine = manifest["engine"]
|
||||
native = engine["kind"] == "native"
|
||||
fields = ("executable",) if native else ("loader", "wasm", "data", "metadata")
|
||||
for field in fields:
|
||||
asset = f"{manifest_path.rsplit('/', 1)[0]}/{engine[field]}"
|
||||
if asset not in names:
|
||||
raise RuntimeError(f"Office engine asset is missing: {asset}")
|
||||
mode = archive.getinfo(asset).external_attr >> 16
|
||||
if native and platform_tag != "win_amd64" and mode & stat.S_IXUSR == 0:
|
||||
raise RuntimeError(f"Office helper lost its executable bit: {asset}")
|
||||
|
||||
|
||||
def verify_wheel(
|
||||
@@ -253,21 +296,26 @@ def verify_wheel(
|
||||
raise RuntimeError(
|
||||
f"{wheel} has license files {license_files}, expected {expected_license_files}"
|
||||
)
|
||||
runtime_files = [
|
||||
runtime_payload = [
|
||||
name for name in archive.namelist() if "/runtime/deepseek-harness-sdk-runtime-" in name
|
||||
]
|
||||
if package == "runtime":
|
||||
assert platform is not None
|
||||
expected_files = sorted(runtime_filenames(platform[1]))
|
||||
found_files = sorted(Path(name).name for name in runtime_files)
|
||||
office = office_sidecar_name(platform[1])
|
||||
expected_files = sorted((*runtime_filenames(platform[1]), office))
|
||||
found_files = sorted({name.split("/runtime/", 1)[1].split("/", 1)[0] for name in runtime_payload})
|
||||
if found_files != expected_files:
|
||||
raise RuntimeError(f"{wheel} runtime payload must be {expected_files}, found {found_files}")
|
||||
for runtime_file in runtime_files:
|
||||
office_modules = f"deepseek_harness_runtime/runtime/{office}/node_modules"
|
||||
verify_office_payload(archive, office_modules, platform[0])
|
||||
for runtime_file in runtime_payload:
|
||||
if "/" in runtime_file.split("/runtime/", 1)[1]:
|
||||
continue
|
||||
mode = archive.getinfo(runtime_file).external_attr >> 16
|
||||
if platform[0] != "win_amd64" and mode & stat.S_IXUSR == 0:
|
||||
raise RuntimeError(f"{wheel} runtime executable lost its executable bit: {runtime_file}")
|
||||
elif runtime_files:
|
||||
raise RuntimeError(f"SDK wheel unexpectedly contains runtime executables: {runtime_files}")
|
||||
elif runtime_payload:
|
||||
raise RuntimeError(f"SDK wheel unexpectedly contains runtime files: {runtime_payload}")
|
||||
if package == "sdk":
|
||||
requirements = metadata.get_all("Requires-Dist") or []
|
||||
expected_requirement = f"{RUNTIME_DISTRIBUTION}=={version}"
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
/** Experimental ownership of the actual filesystem and package inputs supplied to a bundler. */
|
||||
|
||||
import { existsSync, readFileSync, realpathSync } from 'node:fs'
|
||||
import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
|
||||
/** Package identities are cached only within one build. */
|
||||
export class BundleInputIsolation {
|
||||
private readonly packages = new Map<string, string | undefined>()
|
||||
private readonly repository: string
|
||||
private readonly label: string
|
||||
|
||||
constructor(repository: string, label: string) {
|
||||
this.repository = repository
|
||||
this.label = label
|
||||
}
|
||||
|
||||
/** Discard package metadata before a new build or watch rebuild. */
|
||||
reset(): void { this.packages.clear() }
|
||||
|
||||
/**
|
||||
* Require a recorded input to have non-experimental physical and package ownership.
|
||||
* @param id - bundler module id, filesystem path, or filesystem URL.
|
||||
*/
|
||||
assertInput(id: string): void {
|
||||
this.checkInput(id, false)
|
||||
}
|
||||
|
||||
/**
|
||||
* Check declared source-map ownership; dependency tarballs may omit their upstream sources.
|
||||
* @param id - source-map source resolved relative to its map.
|
||||
*/
|
||||
assertSourceMapInput(id: string): void {
|
||||
this.checkInput(id, true)
|
||||
}
|
||||
|
||||
private checkInput(id: string, allowMissing: boolean): void {
|
||||
if (/(?:^|[/:\u0000])@deepseek-ai\/dsh-experimental-[^/?#]+/.test(id)) {
|
||||
throw new Error(`${this.label}: experimental input ${id}`)
|
||||
}
|
||||
const file = physicalBundleInput(id)
|
||||
if (file === undefined) return
|
||||
const lexical = relative(resolve(this.repository, 'packages/experimental'), file)
|
||||
if (lexical === '' || lexical !== '..' && !lexical.startsWith(`..${sep}`) && !isAbsolute(lexical)) {
|
||||
throw new Error(`${this.label}: experimental input ${id}`)
|
||||
}
|
||||
let existing = file
|
||||
if (!allowMissing && !existsSync(file)) throw new Error(`${this.label}: input ${id} is missing`)
|
||||
while (!existsSync(existing)) {
|
||||
const parent = dirname(existing)
|
||||
if (parent === existing) throw new Error(`${this.label}: input ${id} has no existing filesystem root`)
|
||||
existing = parent
|
||||
}
|
||||
const canonical = resolve(realpathSync(existing), relative(existing, file))
|
||||
if (canonical !== file) this.checkInput(canonical, allowMissing)
|
||||
const name = this.packageName(dirname(canonical))
|
||||
if (name?.startsWith('@deepseek-ai/dsh-experimental-')) {
|
||||
throw new Error(`${this.label}: ${id} belongs to experimental package ${name}`)
|
||||
}
|
||||
}
|
||||
|
||||
private packageName(directory: string): string | undefined {
|
||||
if (this.packages.has(directory)) return this.packages.get(directory)
|
||||
const manifest = resolve(directory, 'package.json')
|
||||
let name: string | undefined
|
||||
if (existsSync(manifest)) {
|
||||
const value: unknown = JSON.parse(readFileSync(manifest, 'utf8'))
|
||||
if (value !== null && typeof value === 'object' && 'name' in value && typeof value.name === 'string') name = value.name
|
||||
}
|
||||
if (name === undefined && dirname(directory) !== directory) name = this.packageName(dirname(directory))
|
||||
this.packages.set(directory, name)
|
||||
return name
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Recover physical ownership from queries, filesystem URLs, and virtual path wrappers.
|
||||
* @param id - bundler module id or recorded filesystem input.
|
||||
* @returns absolute file path, or undefined for a virtual id without a physical path.
|
||||
*/
|
||||
export function physicalBundleInput(id: string): string | undefined {
|
||||
let clean = id.replaceAll('\\', '/').split(/[?#]/, 1)[0] ?? ''
|
||||
clean = clean.replace(/^\u0000/, '')
|
||||
if (clean.startsWith('file://')) return fileURLToPath(clean)
|
||||
if (clean.startsWith('/@fs/')) {
|
||||
clean = clean.slice('/@fs/'.length)
|
||||
if (!isAbsolute(clean) && !/^[a-zA-Z]:\//.test(clean)) clean = `/${clean}`
|
||||
}
|
||||
if (!isAbsolute(clean) && !/^[a-zA-Z]:\//.test(clean)) {
|
||||
const wrapped = /:(\/.*|[a-zA-Z]:\/.*)$/.exec(clean)?.[1]
|
||||
if (wrapped === undefined) return undefined
|
||||
clean = wrapped
|
||||
}
|
||||
return resolve(clean)
|
||||
}
|
||||
@@ -1,26 +1,27 @@
|
||||
/** Experimental-package publication and dependency constraints. */
|
||||
|
||||
import { readFileSync } from 'node:fs'
|
||||
import { describe, expect, it } from 'vitest'
|
||||
import {
|
||||
isPublicExperimentalPackageDirectory,
|
||||
PRIVATE_EXPERIMENTAL_PACKAGE_DIRECTORIES,
|
||||
} from './experimental-package-policy.ts'
|
||||
import {
|
||||
checkDshFamilyVersion,
|
||||
checkWorkspaceManifest,
|
||||
checkExperimentalDependencyIsolation,
|
||||
checkExperimentalManifest,
|
||||
expectedDshPackageFiles,
|
||||
type WorkspaceManifest,
|
||||
} from './check-workspace-constraints.ts'
|
||||
|
||||
const experimental: WorkspaceManifest = {
|
||||
const experimental = {
|
||||
dir: 'packages/experimental/prototype',
|
||||
manifest: { name: '@deepseek-ai/dsh-experimental-prototype', private: true },
|
||||
}
|
||||
|
||||
const publicExperimental: WorkspaceManifest = {
|
||||
dir: 'packages/experimental/agent-team',
|
||||
manifest: {
|
||||
name: '@deepseek-ai/dsh-experimental-agent-team',
|
||||
name: '@deepseek-ai/dsh-experimental-prototype',
|
||||
publishConfig: { access: 'public' },
|
||||
},
|
||||
}
|
||||
} satisfies WorkspaceManifest
|
||||
|
||||
describe('experimental workspace constraints', () => {
|
||||
it('requires the experimental package-name prefix', () => {
|
||||
@@ -32,31 +33,46 @@ describe('experimental workspace constraints', () => {
|
||||
])
|
||||
})
|
||||
|
||||
it('requires private manifests without publication metadata', () => {
|
||||
it('requires public metadata for unlisted experimental packages', () => {
|
||||
expect(checkExperimentalManifest(experimental)).toEqual([])
|
||||
expect(checkExperimentalManifest({
|
||||
...experimental,
|
||||
manifest: { ...experimental.manifest, private: false, publishConfig: { access: 'public' } },
|
||||
manifest: { name: experimental.manifest.name, private: true },
|
||||
})).toEqual([
|
||||
'@deepseek-ai/dsh-experimental-prototype: experimental package must set "private": true',
|
||||
'@deepseek-ai/dsh-experimental-prototype: experimental package must omit publishConfig',
|
||||
'@deepseek-ai/dsh-experimental-prototype: public experimental package must not set "private": true',
|
||||
'@deepseek-ai/dsh-experimental-prototype: public experimental package must set publishConfig.access to "public"',
|
||||
])
|
||||
})
|
||||
|
||||
it('requires public metadata only for the Agent Teams exceptions', () => {
|
||||
expect(checkExperimentalManifest(publicExperimental)).toEqual([])
|
||||
expect(checkExperimentalManifest({
|
||||
...publicExperimental,
|
||||
manifest: {
|
||||
name: '@deepseek-ai/dsh-experimental-agent-team',
|
||||
private: true,
|
||||
},
|
||||
})).toEqual([
|
||||
'@deepseek-ai/dsh-experimental-agent-team: public experimental package must not set "private": true',
|
||||
'@deepseek-ai/dsh-experimental-agent-team: public experimental package must set publishConfig.access to "public"',
|
||||
it('requires private metadata for an explicitly excluded prototype', () => {
|
||||
const { dir, manifest: { name } } = experimental
|
||||
const privateDirectories = [dir]
|
||||
expect(isPublicExperimentalPackageDirectory(dir, privateDirectories)).toBe(false)
|
||||
expect(checkExperimentalManifest({ dir, manifest: { name, private: true } }, privateDirectories)).toEqual([])
|
||||
expect(checkExperimentalManifest(experimental, privateDirectories)).toEqual([
|
||||
`${name}: experimental package must set "private": true`,
|
||||
`${name}: experimental package must omit publishConfig`,
|
||||
])
|
||||
})
|
||||
|
||||
it('keeps the current experimental publication set unrestricted', () => {
|
||||
expect(PRIVATE_EXPERIMENTAL_PACKAGE_DIRECTORIES).toEqual([])
|
||||
})
|
||||
|
||||
it('limits the public default to experimental package directories', () => {
|
||||
expect(isPublicExperimentalPackageDirectory(experimental.dir)).toBe(true)
|
||||
for (const dir of [
|
||||
'packages/core/session',
|
||||
'apps/cli',
|
||||
'vendor/cordis',
|
||||
'packages/experimental',
|
||||
'packages/experimental/prototype/src',
|
||||
...PRIVATE_EXPERIMENTAL_PACKAGE_DIRECTORIES,
|
||||
]) {
|
||||
expect(isPublicExperimentalPackageDirectory(dir)).toBe(false)
|
||||
}
|
||||
})
|
||||
|
||||
it.each(['dependencies', 'optionalDependencies', 'peerDependencies'] as const)(
|
||||
'rejects release %s on an experimental package',
|
||||
(section) => {
|
||||
@@ -72,6 +88,22 @@ describe('experimental workspace constraints', () => {
|
||||
},
|
||||
)
|
||||
|
||||
it('allows the dsh installation to ship the optional bundles the launcher names, and nothing else experimental', () => {
|
||||
const listed = { '@deepseek-ai/dsh-experimental-prototype': 'workspace:^' }
|
||||
const installation = { dir: 'apps/cli', manifest: { name: '@deepseek-ai/dsh', dependencies: listed } } satisfies WorkspaceManifest
|
||||
expect(checkExperimentalDependencyIsolation([experimental, installation], ['@deepseek-ai/dsh-experimental-prototype'])).toEqual([])
|
||||
expect(checkExperimentalDependencyIsolation([experimental, installation], [])).toEqual([
|
||||
'@deepseek-ai/dsh: dependencies.@deepseek-ai/dsh-experimental-prototype must not reference an experimental package',
|
||||
])
|
||||
// Only a plain dependency edge is offered; a peer would make the bundle a requirement of every consumer.
|
||||
expect(checkExperimentalDependencyIsolation([experimental, {
|
||||
dir: 'apps/cli',
|
||||
manifest: { name: '@deepseek-ai/dsh', peerDependencies: listed },
|
||||
}], ['@deepseek-ai/dsh-experimental-prototype'])).toEqual([
|
||||
'@deepseek-ai/dsh: peerDependencies.@deepseek-ai/dsh-experimental-prototype must not reference an experimental package',
|
||||
])
|
||||
})
|
||||
|
||||
it('allows development and experimental consumers but rejects the Python release runtime', () => {
|
||||
const manifests: WorkspaceManifest[] = [experimental, {
|
||||
dir: 'packages/core/test-only',
|
||||
@@ -142,4 +174,48 @@ describe('package payload constraints', () => {
|
||||
'lib/types/**/*.d.ts',
|
||||
])
|
||||
})
|
||||
|
||||
it.each([
|
||||
'packages/client/ui-sidebar-documentpreview',
|
||||
'packages/client/ui-sidebar-terminal',
|
||||
])('accepts package-local Client chunks from %s', (dir) => {
|
||||
const manifest = JSON.parse(readFileSync(new URL(`../${dir}/package.json`, import.meta.url), 'utf8')) as WorkspaceManifest['manifest']
|
||||
expect(checkWorkspaceManifest({ dir, manifest })).toEqual([])
|
||||
})
|
||||
})
|
||||
|
||||
it('publishes CLI runtime declarations and rejects a payload that omits them', () => {
|
||||
const manifest = JSON.parse(readFileSync(new URL('../apps/cli/package.json', import.meta.url), 'utf8')) as WorkspaceManifest['manifest']
|
||||
expect(checkWorkspaceManifest({ dir: 'apps/cli', manifest })).toEqual([])
|
||||
expect(checkWorkspaceManifest({ dir: 'apps/cli', manifest: { ...manifest, files: ['lib/*.js'] } }))
|
||||
.toEqual([expect.stringContaining('@deepseek-ai/dsh: package.json files must be ["lib/*.js","lib/types/*.d.ts"]')])
|
||||
})
|
||||
|
||||
it('requires the shared Web injection entry in the published payload', () => {
|
||||
const manifest = JSON.parse(readFileSync(new URL('../packages/client/web/package.json', import.meta.url), 'utf8')) as WorkspaceManifest['manifest']
|
||||
expect(checkWorkspaceManifest({ dir: 'packages/client/web', manifest })).toEqual([])
|
||||
expect(checkWorkspaceManifest({ dir: 'packages/client/web', manifest: {
|
||||
...manifest, files: ['lib/index.js', 'lib/**/*.css', 'lib/types/**/*.d.ts'],
|
||||
} })).toEqual([expect.stringContaining('package.json files must be')])
|
||||
})
|
||||
|
||||
it('requires Office skill bodies and helpers in the published payload', () => {
|
||||
const manifest = JSON.parse(readFileSync(new URL('../packages/skill/skill-office/package.json', import.meta.url), 'utf8')) as WorkspaceManifest['manifest']
|
||||
expect(checkWorkspaceManifest({ dir: 'packages/skill/skill-office', manifest })).toEqual([])
|
||||
expect(checkWorkspaceManifest({ dir: 'packages/skill/skill-office', manifest: {
|
||||
...manifest, files: ['lib/index.js', 'lib/types/**/*.d.ts'],
|
||||
} })).toEqual([expect.stringContaining('package.json files must be')])
|
||||
})
|
||||
|
||||
it.each(['lib/*-*.js', 'THIRD_PARTY_PREVIEW_NOTICES.txt'])('requires %s in the published UI primitives payload', (required) => {
|
||||
const name = '@deepseek-ai/dsh-client-ui-primitives'
|
||||
const files = expectedDshPackageFiles({ name })
|
||||
expect(files).toContain(required)
|
||||
const check = (entries: readonly string[]) => checkWorkspaceManifest({
|
||||
dir: 'packages/client/ui-primitives', manifest: { name, files: [...entries] },
|
||||
}).filter(message => message.includes('package.json files'))
|
||||
expect(check(files)).toEqual([])
|
||||
expect(check(files.filter(file => file !== required))).toEqual([
|
||||
expect.stringContaining('package.json files must be'),
|
||||
])
|
||||
})
|
||||
@@ -8,8 +8,12 @@
|
||||
import { existsSync, readdirSync, readFileSync } from 'node:fs'
|
||||
import { join, relative, resolve } from 'node:path'
|
||||
import { pathToFileURL } from 'node:url'
|
||||
import { isPublicExperimentalPackageDirectory } from './experimental-package-policy.ts'
|
||||
import {
|
||||
isPublicExperimentalPackageDirectory,
|
||||
PRIVATE_EXPERIMENTAL_PACKAGE_DIRECTORIES,
|
||||
} from './experimental-package-policy.ts'
|
||||
import { hasTypertRemoteNavigation, isForbiddenPublicationFile } from './publication-payload.ts'
|
||||
import { OPTIONAL_BUNDLES } from '../packages/boot/app-boot/src/profile.ts'
|
||||
import { collectProjectReferenceFaceViolations } from './project-reference-faces.ts'
|
||||
|
||||
const root = resolve(import.meta.dirname, '..')
|
||||
@@ -44,12 +48,7 @@ const publicNativePackages = new Set([
|
||||
const publicationSourceAllowlist: Readonly<Record<string, readonly string[]>> = {
|
||||
'@deepseek-ai/node-addon-system': ['src/main.c', 'src/flock.c'],
|
||||
}
|
||||
const repositoryUrl = 'git+https://github.com/deepseek-harness/deepseek-harness.git'
|
||||
/**
|
||||
* Source home the published packages point consumers at. It differs from
|
||||
* {@link repositoryUrl}, which the Landlock packages keep because npm resolves
|
||||
* their trusted publishing against the repository that runs the workflow.
|
||||
*/
|
||||
/** Public source home recorded in maintained package manifests. */
|
||||
const publishedRepositoryUrl = 'git+https://github.com/deepseek-ai/deepseek-harness.git'
|
||||
/** Packages that participate in the experimental policy. */
|
||||
const experimentalPackageDirectory = /^packages\/experimental\/[^/]+$/
|
||||
@@ -61,13 +60,12 @@ const standardReleaseMemberDirectory = /^(?:packages\/(?!experimental\/)[^/]+\/[
|
||||
const desktopApplicationDirectory = 'apps/desktop'
|
||||
const localArtifactDirs = new Set(['node_modules'])
|
||||
const appPackageFiles: Readonly<Record<string, readonly string[]>> = {
|
||||
'@deepseek-ai/dsh': ['lib/*.js'],
|
||||
'@deepseek-ai/dsh': ['lib/*.js', 'lib/types/*.d.ts'],
|
||||
'@deepseek-ai/dsh-desktop-host': [
|
||||
'lib/index.js',
|
||||
'config/desktop.cordis.patch.yml',
|
||||
],
|
||||
// Sourcemaps stay out by payload policy; the worker-preview surface
|
||||
// (dist/preview.html and dist/preview/) backs private experimental
|
||||
// (dist/preview.html and dist/preview/) backs opt-in experimental
|
||||
// packages and is not published.
|
||||
'@deepseek-ai/dsh-web-frontend': ['dist', '!dist/**/*.map', '!dist/preview.html', '!dist/preview'],
|
||||
}
|
||||
@@ -150,17 +148,26 @@ function workspaceManifests(): WorkspaceManifest[] {
|
||||
}
|
||||
|
||||
const packageFileExtras: Readonly<Record<string, readonly string[]>> = {
|
||||
// Owned Worker bundles import this public bootstrap before their business entry.
|
||||
'@deepseek-ai/dsh-app-boot': ['lib/worker/profile-resolution-bootstrap.js'],
|
||||
// Statically linked client libraries keep their stylesheets next to the emitted
|
||||
// JavaScript, which imports them by relative path: the compile shell runs
|
||||
// them through its own CSS pipeline, so the sheets are published artifacts.
|
||||
// The glob covers whichever sheets a package emits; sourcemaps stay
|
||||
// unpublished, as everywhere else in the repository.
|
||||
'@deepseek-ai/dsh-client-ui-primitives': ['lib/**/*.css'],
|
||||
// Lazy grammar and diagram imports resolve hashed runtime chunks beside index.js.
|
||||
'@deepseek-ai/dsh-client-ui-primitives': ['lib/*-*.js', 'lib/**/*.css', 'THIRD_PARTY_PREVIEW_NOTICES.txt'],
|
||||
'@deepseek-ai/dsh-client-ui-dockkit': ['lib/**/*.css'],
|
||||
'@deepseek-ai/dsh-client-web': ['lib/**/*.css'],
|
||||
'@deepseek-ai/dsh-client-ui-sidebar-documentpreview': ['lib/client.*.js'],
|
||||
'@deepseek-ai/dsh-client-ui-sidebar-terminal': ['lib/client.*.js'],
|
||||
'@deepseek-ai/dsh-client-web': ['lib/**/*.css', 'lib/apply-injections.js'],
|
||||
'@deepseek-ai/dsh-client-ui-theme': ['lib/styles'],
|
||||
// The CPython side ships as source .py files, published as-is rather than built.
|
||||
'@deepseek-ai/dsh-experimental-code-runtime-python': ['py/**/*.py'],
|
||||
'@deepseek-ai/dsh-experimental-ptc-runtime-python': ['py/**/*.py'],
|
||||
// The isolated Node bootstrap is a separately launched bundle.
|
||||
'@deepseek-ai/dsh-ptc-runtime-node': ['lib/process.js'],
|
||||
// The Host entry starts its sibling Worker by URL rather than a package export.
|
||||
'@deepseek-ai/dsh-experimental-inspector': ['lib/worker.js'],
|
||||
// The shipped preset compositions travel inside the roster package.
|
||||
'@deepseek-ai/dsh-agent-presets': ['presets'],
|
||||
// The Web Host mounts the default-off settings owner independently of each
|
||||
@@ -174,17 +181,29 @@ const packageFileExtras: Readonly<Record<string, readonly string[]>> = {
|
||||
// also shares its generated FFI code through a hashed runtime chunk.
|
||||
'@deepseek-ai/dsh-sandbox-windows-acl': ['lib/runner.js', 'lib/types-*.js'],
|
||||
'@deepseek-ai/dsh-skill-badge': ['assets'],
|
||||
'@deepseek-ai/dsh-skill-office': ['assets'],
|
||||
'@deepseek-ai/dsh-subprocess': ['lib/control.js'],
|
||||
// SSH launches a private helper and shares wire definitions and TLS setup
|
||||
// between that helper and the connection owner.
|
||||
'@deepseek-ai/dsh-ssh': [
|
||||
'lib/helper.js', 'lib/protocol.js', 'lib/schemas.js',
|
||||
'lib/protocol-*.js', 'lib/schemas-*.js', 'lib/stream-security-*.js',
|
||||
],
|
||||
// Ordinary native containment ships a path-loaded runner and its shared
|
||||
// runner chunk beside the existing node-pty permission repair.
|
||||
'@deepseek-ai/dsh-subprocess-local': [
|
||||
'lib/runner.js',
|
||||
'lib/runner-*.js',
|
||||
'lib/output.js',
|
||||
'scripts/ensure-spawn-helper.mjs',
|
||||
],
|
||||
// tsdown shares the repository/pack code between the lib entry and the bin
|
||||
// through a hashed chunk. The committed bin.js is the link target pnpm can
|
||||
// resolve at install time, before the build produces lib/bin.js.
|
||||
'@deepseek-ai/dsh-experimental-webworker-packer': ['bin.js', 'lib/repository-*.js'],
|
||||
// The headless entry and its startup row share the JSON projection code
|
||||
// through a hashed tsdown chunk; both import it by relative path.
|
||||
'@deepseek-ai/dsh-headless': ['lib/json-stream-*.js'],
|
||||
}
|
||||
|
||||
function sameStringList(actual: readonly string[] | undefined, expected: readonly string[]): boolean {
|
||||
@@ -268,15 +287,18 @@ function usesEmittedTreeDefaults(manifest: PackageManifest): boolean {
|
||||
exportDefault(manifest, subpath)?.startsWith('./lib/types/') === true)
|
||||
}
|
||||
|
||||
/** Experimental manifest requirements, including explicit public exceptions. */
|
||||
export function checkExperimentalManifest({ dir, manifest }: WorkspaceManifest): string[] {
|
||||
/** Experimental manifest requirements, including explicit private exceptions. */
|
||||
export function checkExperimentalManifest(
|
||||
{ dir, manifest }: WorkspaceManifest,
|
||||
privateDirectories: readonly string[] = PRIVATE_EXPERIMENTAL_PACKAGE_DIRECTORIES,
|
||||
): string[] {
|
||||
if (!experimentalPackageDirectory.test(dir)) return []
|
||||
const label = manifest.name ?? dir
|
||||
const errors: string[] = []
|
||||
if (manifest.name?.startsWith(experimentalPackageNamePrefix) !== true) {
|
||||
errors.push(`${label}: experimental package name must start with ${JSON.stringify(experimentalPackageNamePrefix)}`)
|
||||
}
|
||||
if (isPublicExperimentalPackageDirectory(dir)) {
|
||||
if (isPublicExperimentalPackageDirectory(dir, privateDirectories)) {
|
||||
if (manifest.private === true) errors.push(`${label}: public experimental package must not set "private": true`)
|
||||
if (manifest.publishConfig?.access !== 'public') {
|
||||
errors.push(`${label}: public experimental package must set publishConfig.access to "public"`)
|
||||
@@ -338,9 +360,9 @@ export function checkWorkspaceManifest({ dir, manifest }: WorkspaceManifest): st
|
||||
}
|
||||
const expectedDirectory = dir
|
||||
if (manifest.repository?.type !== 'git'
|
||||
|| manifest.repository.url !== repositoryUrl
|
||||
|| manifest.repository.url !== publishedRepositoryUrl
|
||||
|| manifest.repository.directory !== expectedDirectory) {
|
||||
errors.push(`${label}: published Landlock package repository must use ${repositoryUrl} with directory ${expectedDirectory} for trusted publishing`)
|
||||
errors.push(`${label}: published Landlock package repository must use ${publishedRepositoryUrl} with directory ${expectedDirectory}`)
|
||||
}
|
||||
} else if (isReleaseMemberDirectory(dir)) {
|
||||
// Release members state that they are publishable: npm refuses a private
|
||||
@@ -483,11 +505,16 @@ const dependencySections = ['dependencies', 'devDependencies', 'peerDependencies
|
||||
const runtimeDependencySections = ['dependencies', 'optionalDependencies', 'peerDependencies'] as const
|
||||
|
||||
/**
|
||||
* Prevent an official runtime from requiring a package its release omits.
|
||||
* Prevent an official runtime from requiring an experimental package. The dsh installation's `dependencies`
|
||||
* may hold the bundles the launcher's `OPTIONAL_BUNDLES` names: shipped switched off, they are not a requirement
|
||||
* ([rationale](../.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.md)).
|
||||
* @param manifests - release, private experimental, and deployment-root manifests.
|
||||
* @param optionalBundles - the bundles the installation ships switched off; the launcher's list by default.
|
||||
* @returns One error for each forbidden runtime dependency.
|
||||
*/
|
||||
export function checkExperimentalDependencyIsolation(manifests: readonly WorkspaceManifest[]): string[] {
|
||||
export function checkExperimentalDependencyIsolation(
|
||||
manifests: readonly WorkspaceManifest[], optionalBundles: readonly string[] = OPTIONAL_BUNDLES,
|
||||
): string[] {
|
||||
const experimentalNames = new Set(manifests
|
||||
.filter(entry => experimentalPackageDirectory.test(entry.dir))
|
||||
.map(entry => entry.manifest.name)
|
||||
@@ -495,9 +522,11 @@ export function checkExperimentalDependencyIsolation(manifests: readonly Workspa
|
||||
const errors: string[] = []
|
||||
for (const { dir, manifest } of manifests) {
|
||||
if (!standardReleaseMemberDirectory.test(dir) && dir !== 'python/sdk-runtime') continue
|
||||
const offered = manifest.name === '@deepseek-ai/dsh' ? new Set(optionalBundles) : new Set<string>()
|
||||
for (const section of runtimeDependencySections) {
|
||||
for (const name of Object.keys(manifest[section] ?? {})) {
|
||||
if (!experimentalNames.has(name)) continue
|
||||
if (section === 'dependencies' && offered.has(name)) continue
|
||||
errors.push(`${manifest.name ?? dir}: ${section}.${name} must not reference an experimental package`)
|
||||
}
|
||||
}
|
||||
|
||||
+126
-57
@@ -4,11 +4,27 @@ import { runInNewContext } from 'node:vm'
|
||||
import * as yaml from 'js-yaml'
|
||||
import { describe, expect, it } from 'vitest'
|
||||
|
||||
function evaluateRunsOn(selector: unknown, context: Record<string, unknown>): unknown {
|
||||
if (typeof selector !== 'string') throw new TypeError('Runner selector must be a string')
|
||||
return runInNewContext(selector.trim().slice(3, -2), context, { timeout: 1000 })
|
||||
}
|
||||
|
||||
const root = resolve(import.meta.dirname, '..')
|
||||
const runnerPrivatePnpmDestination = /^\$\{\{ runner\.temp \}\}\/setup-pnpm-\$\{\{ github\.run_id \}\}-\$\{\{ github\.run_attempt \}\}$/
|
||||
const nativeWindowsPnpmDestination = '${{ runner.temp }}/setup-pnpm-js-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}'
|
||||
|
||||
describe('CI workflow', () => {
|
||||
it('prepares confinement before Node compatibility smokes', () => {
|
||||
const job = workflowJob(loadWorkflow('.github/workflows/ci.yml'), 'node-compat')
|
||||
if (!Array.isArray(job.steps)) throw new TypeError('Node compatibility job must define steps')
|
||||
const steps = job.steps.filter(isRecord)
|
||||
const preparation = steps.findIndex(step => step.run === 'bash scripts/prepare-ci-bubblewrap.sh')
|
||||
const smoke = steps.findIndex(step => step.run === 'pnpm run check:node-compat')
|
||||
expect(preparation).toBeGreaterThanOrEqual(0)
|
||||
expect(smoke).toBeGreaterThan(preparation)
|
||||
expect(steps[preparation]).not.toHaveProperty('continue-on-error', true)
|
||||
})
|
||||
|
||||
it.each(['ci.yml', 'ci-master.yml', 'e2e.yml', 'release.yml', 'release-vendor.yml'])(
|
||||
'%s cancels superseded validation runs without crossing workflow or ref boundaries', (name) => {
|
||||
const workflow = loadWorkflow('.github/workflows/' + name)
|
||||
@@ -241,7 +257,7 @@ describe('CI workflow', () => {
|
||||
expect(nativeTestCommand).toContain('--no-file-parallelism')
|
||||
expect(nativeTestCommand).toContain('--testTimeout 90000')
|
||||
expect(nativeTestCommand).toContain('tool-pwsh/tests/loader.spec.ts')
|
||||
expect(nativeTestCommand).toContain('workflow-worker-thread.spec.ts')
|
||||
expect(nativeTestCommand).toContain('workflow-ptc.spec.ts')
|
||||
|
||||
// windows-observational is non-blocking.
|
||||
expect(windowsObservational.name).toBe('windows node 24 / observational')
|
||||
@@ -258,7 +274,8 @@ describe('CI workflow', () => {
|
||||
isRecord(step) && step.name === 'Configure persistent pnpm store' && typeof step.run === 'string'
|
||||
))
|
||||
expect(serialStore).toBeDefined()
|
||||
expect(serialStore!.run).toContain('F:\\.pnpm-store')
|
||||
expect(serialStore!.run).toContain('[IO.Path]::GetPathRoot($env:GITHUB_WORKSPACE)')
|
||||
expect(serialStore!.run).toContain("'.pnpm-store'")
|
||||
const serialInstall = serialSteps.find((step): step is Record<string, unknown> & { run: string } => (
|
||||
isRecord(step) && step.name === 'Install (immutable)' && typeof step.run === 'string'
|
||||
))
|
||||
@@ -328,12 +345,11 @@ describe('CI workflow', () => {
|
||||
windows: windowsBuild['runs-on'] as string,
|
||||
}
|
||||
const evaluate = (expression: string, vars: Record<string, string>, login = 'maintainer'): unknown => {
|
||||
const body = expression.trim().slice(3, -2)
|
||||
return runInNewContext(body, {
|
||||
return evaluateRunsOn(expression, {
|
||||
vars,
|
||||
fromJSON: JSON.parse,
|
||||
github: { event: { pull_request: { user: { login } } } },
|
||||
}, { timeout: 1000 })
|
||||
})
|
||||
}
|
||||
for (const [name, selector, variable, pool, hosted] of [
|
||||
['linux gates', selectors.linux, 'DSH_CI_FAILOVER_LINUX', ['self-hosted', 'linux', 'x64', 'vm-backup'], 'dsh-ubuntu-24-04-16core'],
|
||||
@@ -579,6 +595,50 @@ describe('CI workflow', () => {
|
||||
})
|
||||
})
|
||||
|
||||
describe('Runtime and LLM e2e Blacksmith routing', () => {
|
||||
it('routes DeepSeek e2e only through the Linux Blacksmith switch', () => {
|
||||
const job = workflowJob(loadWorkflow('.github/workflows/e2e.yml'), 'e2e')
|
||||
for (const mode of ['', 'selfhosted', 'unexpected', 'blacksmith']) {
|
||||
expect(evaluateRunsOn(job['runs-on'], { vars: { DSH_CI_FAILOVER_LINUX: mode, DSH_CI_FAILOVER_WINDOWS: 'blacksmith' } }))
|
||||
.toBe(mode === 'blacksmith' ? 'blacksmith-4vcpu-ubuntu-2404' : 'ubuntu-latest')
|
||||
}
|
||||
})
|
||||
|
||||
it('keeps native release and dispatch builders hosted while routing x64 CI by platform', () => {
|
||||
const workflow = loadWorkflow('.github/workflows/build-exe-for-python-sdk.yml')
|
||||
const build = workflowJob(workflow, 'build')
|
||||
for (const [target, runner, variable, blacksmith] of [
|
||||
['node24-linux-x64', 'ubuntu-latest', 'DSH_CI_FAILOVER_LINUX', 'blacksmith-16vcpu-ubuntu-2404'],
|
||||
['node24-win-x64', 'windows-2025', 'DSH_CI_FAILOVER_WINDOWS', 'blacksmith-16vcpu-windows-2025'],
|
||||
['node24-linux-arm64', 'ubuntu-24.04-arm', 'DSH_CI_FAILOVER_LINUX', 'ubuntu-24.04-arm'],
|
||||
['node24-macos-arm64', 'macos-latest', 'DSH_CI_FAILOVER_LINUX', 'macos-latest'],
|
||||
['node24-macos-x64', 'macos-15-intel', 'DSH_CI_FAILOVER_LINUX', 'macos-15-intel'],
|
||||
] as const) {
|
||||
for (const ci of [false, true]) {
|
||||
for (const release of [false, true]) {
|
||||
for (const mode of ['', 'selfhosted', 'unexpected', 'blacksmith']) {
|
||||
const vars = { DSH_CI_FAILOVER_LINUX: 'blacksmith', DSH_CI_FAILOVER_WINDOWS: 'blacksmith', [variable]: mode }
|
||||
expect(evaluateRunsOn(build['runs-on'], { inputs: { ci, release }, vars, matrix: { target, runner } }), `${target} ci=${ci} release=${release} mode=${mode}`)
|
||||
.toBe(ci && !release && mode === 'blacksmith' ? blacksmith : runner)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
it.each(['plan', 'sdk-wheel'])('routes runtime %s only for non-release CI', (name) => {
|
||||
const job = workflowJob(loadWorkflow('.github/workflows/build-exe-for-python-sdk.yml'), name)
|
||||
for (const ci of [false, true]) {
|
||||
for (const release of [false, true]) {
|
||||
for (const mode of ['', 'selfhosted', 'unexpected', 'blacksmith']) {
|
||||
expect(evaluateRunsOn(job['runs-on'], { inputs: { ci, release }, vars: { DSH_CI_FAILOVER_LINUX: mode } }))
|
||||
.toBe(ci && !release && mode === 'blacksmith' ? 'blacksmith-4vcpu-ubuntu-2404' : 'ubuntu-latest')
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
})
|
||||
|
||||
describe('DeepSeek e2e workflow', () => {
|
||||
it('prepares bubblewrap from the pinned payload without a package transaction', () => {
|
||||
const workflow = loadWorkflow('.github/workflows/e2e.yml')
|
||||
@@ -602,33 +662,6 @@ describe('DeepSeek e2e workflow', () => {
|
||||
})
|
||||
})
|
||||
|
||||
describe('E2B e2e workflow', () => {
|
||||
it('is manual-only and fails loud before running the focused live suite', () => {
|
||||
const workflow = loadWorkflow('.github/workflows/e2b-e2e.yml')
|
||||
expect(workflow.on).toEqual({ workflow_dispatch: null })
|
||||
if (!isRecord(workflow.jobs) || !isRecord(workflow.jobs.e2b) || !Array.isArray(workflow.jobs.e2b.steps)) {
|
||||
throw new TypeError('E2B e2e workflow must define the e2b job steps')
|
||||
}
|
||||
|
||||
const steps = workflow.jobs.e2b.steps.filter(isRecord)
|
||||
const preflight = steps.find(step => step.name === 'Preflight (require E2B API key)')
|
||||
const e2b = steps.find(step => step.name === 'E2B tests (live sandbox)')
|
||||
|
||||
expect(preflight).toMatchObject({
|
||||
env: { E2B_API_KEY: '${{ secrets.E2B_API_KEY_EXTERNAL }}' },
|
||||
})
|
||||
expect(preflight?.run).toContain('E2B_API_KEY_EXTERNAL repository secret')
|
||||
expect(e2b).toMatchObject({
|
||||
env: {
|
||||
E2B_API_KEY: '${{ secrets.E2B_API_KEY_EXTERNAL }}',
|
||||
DSH_E2E_MAX_WORKERS: '1',
|
||||
DSH_EXAMPLE_MODE: 'lib',
|
||||
},
|
||||
})
|
||||
expect(e2b?.run).toContain('packages/e2b/e2b/tests/composition.e2e.ts')
|
||||
})
|
||||
})
|
||||
|
||||
describe('Python release workflows', () => {
|
||||
it('keeps complete wheel validation separate from protected public publication', () => {
|
||||
const workflow = loadWorkflow('.github/workflows/python-release.yml')
|
||||
@@ -795,12 +828,14 @@ describe('Python release workflows', () => {
|
||||
expect(String(realApiPreflightPosix.if)).toContain('head.repo.fork')
|
||||
expect(String(realApiPreflightPosix.if)).toContain('dependabot[bot]')
|
||||
expect(realApiPreflightWindows).toMatchObject({ shell: 'pwsh' })
|
||||
expect(installedRealApiPosix).toMatchObject({
|
||||
env: {
|
||||
DEEPSEEK_API_KEY: '${{ secrets.DEEPSEEK_API_KEY_EXTERNAL }}',
|
||||
DEEPSEEK_BASE_URL: 'https://api.deepseek.com',
|
||||
},
|
||||
})
|
||||
for (const step of [installedRealApiPosix, installedRealApiWindows]) {
|
||||
expect(step).toMatchObject({
|
||||
env: {
|
||||
DEEPSEEK_API_KEY: '${{ secrets.DEEPSEEK_API_KEY_EXTERNAL }}',
|
||||
DEEPSEEK_BASE_URL: 'https://api.deepseek.com/anthropic',
|
||||
},
|
||||
})
|
||||
}
|
||||
expect(JSON.stringify(installedRealApiPosix)).toContain('--scenario sdk-live')
|
||||
expect(JSON.stringify(installedRealApiPosix)).toContain('-u DSH_RUNTIME_MODE')
|
||||
expect(installedRealApiWindows).toMatchObject({ shell: 'pwsh' })
|
||||
@@ -881,8 +916,9 @@ describe('Weighted approval workflow', () => {
|
||||
const record = recordSteps.find(step => step.name === 'Record review event')
|
||||
|
||||
expect(publisher.name).toBe('weighted-approval')
|
||||
expect(Object.keys(publisher.on)).toEqual(['pull_request_target', 'workflow_run'])
|
||||
expect(pullRequest.types).toEqual(['opened', 'synchronize', 'reopened', 'ready_for_review', 'converted_to_draft'])
|
||||
expect(Object.keys(publisher.on)).toEqual(['pull_request_target', 'issue_comment', 'workflow_run'])
|
||||
expect(workflowEvent(publisher, 'issue_comment').types).toEqual(['created', 'edited', 'deleted'])
|
||||
expect(pullRequest.types).toEqual(['opened', 'synchronize', 'reopened', 'ready_for_review', 'converted_to_draft', 'edited'])
|
||||
expect(workflowRun).toEqual({ workflows: ['weighted-approval-review-event'], types: ['completed'] })
|
||||
expect(reviewEvent.name).toBe('weighted-approval-review-event')
|
||||
expect(reviewEvent['run-name']).toBe('weighted-approval-review-event:${{ github.event.pull_request.number }}')
|
||||
@@ -891,15 +927,18 @@ describe('Weighted approval workflow', () => {
|
||||
expect(reviewEvent.permissions).toEqual({})
|
||||
expect(publisher.permissions).toEqual({
|
||||
contents: 'read',
|
||||
'pull-requests': 'read',
|
||||
'pull-requests': 'write',
|
||||
statuses: 'write',
|
||||
})
|
||||
expect(publisher.concurrency).toEqual({
|
||||
group: 'weighted-approval-${{ github.event.pull_request.number || github.event.workflow_run.head_sha }}',
|
||||
group: "weighted-approval-${{ (github.event.pull_request.number || github.event.issue.number) && format('weighted-approval-review-event:{0}', github.event.pull_request.number || github.event.issue.number) || github.event.workflow_run.display_title }}",
|
||||
'cancel-in-progress': false,
|
||||
})
|
||||
expect(job).toMatchObject({
|
||||
if: "github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'",
|
||||
if: "(github.event_name != 'pull_request_target' || github.event.pull_request.state == 'open') && "
|
||||
+ "(github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success') && "
|
||||
+ "(github.event_name != 'issue_comment' || (github.event.issue.pull_request && github.event.issue.state == 'open' &&\n"
|
||||
+ " (contains(github.event.comment.body, '/delegate') || contains(github.event.changes.body.from, '/delegate'))))",
|
||||
name: 'weighted approval publisher',
|
||||
'runs-on': 'ubuntu-latest',
|
||||
'timeout-minutes': 5,
|
||||
@@ -911,7 +950,28 @@ describe('Weighted approval workflow', () => {
|
||||
'persist-credentials': false,
|
||||
},
|
||||
})
|
||||
const setupIndex = steps.findIndex(step => typeof step.uses === 'string' && step.uses.startsWith('actions/setup-python@'))
|
||||
expect(steps[setupIndex]?.if).toBe("steps.revoke.outputs.active == 'true'")
|
||||
expect(steps[setupIndex]?.uses).toBe('actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1')
|
||||
const revokeIndex = steps.findIndex(step => step.id === 'revoke')
|
||||
expect(revokeIndex).toBeGreaterThan(steps.indexOf(checkout!))
|
||||
expect(revokeIndex).toBeLessThan(setupIndex)
|
||||
expect(steps[revokeIndex]?.run).toBe('node .github/review-ownership/check-approval.mjs pending')
|
||||
expect(steps.at(-1)).toMatchObject({
|
||||
if: "failure() && steps.revoke.outputs.active == 'true'",
|
||||
run: 'node .github/review-ownership/check-approval.mjs error',
|
||||
})
|
||||
const pythonJob = workflowJob(loadWorkflow('.github/workflows/ci.yml'), 'python-sdk')
|
||||
expect(pythonJob.steps).toContainEqual({
|
||||
name: 'Test production blame scoring',
|
||||
run: "uv run --python 3.10 --with-requirements .github/review-ownership/requirements.txt python -m unittest discover -s .github/review-ownership -p 'test_*.py'",
|
||||
})
|
||||
expect(steps.find(step => step.name === 'Install production lexer')).toMatchObject({
|
||||
if: "steps.revoke.outputs.active == 'true'",
|
||||
run: 'python3 -m pip install -r .github/review-ownership/requirements.txt',
|
||||
})
|
||||
expect(publish).toMatchObject({
|
||||
if: "steps.revoke.outputs.active == 'true'",
|
||||
env: {
|
||||
GITHUB_TOKEN: '${{ github.token }}',
|
||||
GITHUB_RUN_URL: '${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}',
|
||||
@@ -919,6 +979,7 @@ describe('Weighted approval workflow', () => {
|
||||
run: 'node .github/review-ownership/check-approval.mjs',
|
||||
})
|
||||
expect(recordJob).toMatchObject({
|
||||
if: "github.event.pull_request.state == 'open'",
|
||||
name: 'record weighted approval review event',
|
||||
'runs-on': 'ubuntu-latest',
|
||||
'timeout-minutes': 2,
|
||||
@@ -934,19 +995,16 @@ describe('Weighted approval workflow', () => {
|
||||
})
|
||||
|
||||
describe('Issue lifecycle workflow', () => {
|
||||
it('runs the lifecycle job on every PR/review event but gates token and board steps', () => {
|
||||
it('allocates lifecycle runners only for events that can change the board', () => {
|
||||
const lifecycle = loadWorkflow('.github/workflows/issue-lifecycle.yml')
|
||||
const policy = loadWorkflow('.github/workflows/issue-policy.yml')
|
||||
const lifecycleJob = workflowJob(lifecycle, 'lifecycle')
|
||||
if (!Array.isArray(lifecycleJob.steps)) throw new TypeError('Issue lifecycle job must define steps')
|
||||
|
||||
// The job has no job-level `if`, so it is listed on every pull_request /
|
||||
// pull_request_review event and reports success instead of a gray skip. The
|
||||
// write-capable steps are gated at step level so approved/commented reviews
|
||||
// never mint a Project/Issue App token nor touch the board.
|
||||
expect(lifecycle.on).toHaveProperty('pull_request')
|
||||
expect(lifecycle.on).toHaveProperty('pull_request_review')
|
||||
expect(lifecycleJob.if).toBeUndefined()
|
||||
expect(lifecycleJob.if).toContain("github.event.review.state == 'changes_requested'")
|
||||
expect(lifecycleJob.if).toContain('github.event.changes.body != null')
|
||||
// Keep the subscription-type gates: issue-lifecycle does not re-subscribe
|
||||
// ready_for_review (issue-policy owns that) and only reacts to submitted
|
||||
// review events.
|
||||
@@ -956,31 +1014,43 @@ describe('Issue lifecycle workflow', () => {
|
||||
expect(lifecyclePullRequest.types).not.toContain('ready_for_review')
|
||||
expect(lifecyclePullRequest.types).toContain('review_requested')
|
||||
expect(lifecycleReview.types).toEqual(['submitted'])
|
||||
const gated = "${{ github.event_name != 'pull_request_review' || github.event.review.state == 'changes_requested' }}"
|
||||
expect(lifecyclePullRequest.types).not.toContain('synchronize')
|
||||
expect(lifecyclePullRequest.types).not.toContain('labeled')
|
||||
expect(lifecyclePullRequest.types).not.toContain('unlabeled')
|
||||
const issueEvents = workflowEvent(lifecycle, 'issues')
|
||||
expect(issueEvents.types).not.toContain('assigned')
|
||||
expect(issueEvents.types).not.toContain('unassigned')
|
||||
expect(issueEvents.types).toContain('typed')
|
||||
expect(issueEvents.types).toContain('untyped')
|
||||
const steps = lifecycleJob.steps.filter(isRecord)
|
||||
const tokenStep = steps.find(s => s.name === 'Create project token')
|
||||
const handleStep = steps.find(s => s.name === 'Handle repository event')
|
||||
expect(tokenStep).toMatchObject({ if: gated })
|
||||
expect(handleStep).toMatchObject({ if: gated })
|
||||
expect(tokenStep?.if).toBeUndefined()
|
||||
expect(handleStep?.if).toBeUndefined()
|
||||
|
||||
// issue-policy owns PR validation; it is read-only and a real gate.
|
||||
const policyPullRequest = workflowEvent(policy, 'pull_request')
|
||||
expect(policyPullRequest.types).toContain('ready_for_review')
|
||||
})
|
||||
|
||||
it('uses a read-only Project token only for human pull request policy metadata', () => {
|
||||
it('mints Project credentials only after preflight and always revalidates current metadata', () => {
|
||||
const policy = loadWorkflow('.github/workflows/issue-policy.yml')
|
||||
const policyJob = workflowJob(policy, 'policy')
|
||||
if (!Array.isArray(policyJob.steps)) throw new TypeError('Issue policy job must define steps')
|
||||
const steps = policyJob.steps.filter(isRecord)
|
||||
const tokenStep = steps.find(step => step.name === 'Create Project read token')
|
||||
const validateStep = steps.find(step => step.name === 'Validate pull request')
|
||||
const humanPullRequest =
|
||||
"${{ github.event.pull_request.user.type != 'Bot' && github.event.pull_request.user.type != 'App' }}"
|
||||
const preflightStep = steps.find(step => step.id === 'preflight')
|
||||
expect(preflightStep).toMatchObject({ shell: 'bash' })
|
||||
expect(preflightStep?.run).toContain('if [ -f .github/issue-management/selective-preflight.json ]; then')
|
||||
expect(preflightStep?.run).toContain('node .github/issue-management/policy.mjs pr-preflight')
|
||||
expect(preflightStep?.if).toBeUndefined()
|
||||
expect(policyJob.if).toBeUndefined()
|
||||
expect(validateStep?.if).toBe("${{ steps.preflight.outputs.legacy-automated != 'true' }}")
|
||||
|
||||
expect(tokenStep).toMatchObject({
|
||||
id: 'app-token',
|
||||
if: humanPullRequest,
|
||||
if: "${{ steps.preflight.outputs.needs-project == 'true' }}",
|
||||
uses: 'actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1',
|
||||
with: {
|
||||
'client-id': '${{ vars.DSH_ISSUE_APP_CLIENT_ID }}',
|
||||
@@ -992,7 +1062,6 @@ describe('Issue lifecycle workflow', () => {
|
||||
},
|
||||
})
|
||||
expect(validateStep).toMatchObject({
|
||||
if: humanPullRequest,
|
||||
env: {
|
||||
GITHUB_TOKEN: '${{ github.token }}',
|
||||
PROJECT_TOKEN: '${{ steps.app-token.outputs.token }}',
|
||||
|
||||
@@ -28,7 +28,6 @@ const roots: string[] = []
|
||||
const dshBuildWorkflows = [
|
||||
'build-exe-for-python-sdk.yml',
|
||||
'ci.yml',
|
||||
'e2b-e2e.yml',
|
||||
'e2e.yml',
|
||||
'release.yml',
|
||||
'release-publish.yml',
|
||||
@@ -276,6 +275,10 @@ describe('client build environment', () => {
|
||||
|
||||
write(join(official, 'apps/web/dist/index.html'), '<main>changed</main>')
|
||||
expect(() => { readClientBuildRecord(official) }).toThrow(/artifacts differ/)
|
||||
|
||||
const chunked = buildFixture(officialEnvironment)
|
||||
write(join(chunked, 'packages/client/example/lib/client.pdf.js'), 'module.exports = {}\n')
|
||||
expect(() => { readClientBuildRecord(chunked) }).toThrow(/artifacts differ/)
|
||||
})
|
||||
|
||||
it('keeps public client values out of workflow-wide environments', () => {
|
||||
|
||||
@@ -36,6 +36,8 @@ const CLIENT_ARTIFACT_PATTERNS = [
|
||||
'apps/web/dist/**/*',
|
||||
'packages/*/*/lib/client.js',
|
||||
'packages/*/*/lib/client.js.map',
|
||||
'packages/*/*/lib/client.*.js',
|
||||
'packages/*/*/lib/client.*.js.map',
|
||||
] as const
|
||||
|
||||
/** Public values embedded in one set of client artifacts. */
|
||||
|
||||
@@ -2,12 +2,13 @@
|
||||
* Pins shared client-bundle preset rules: module-edge purity, source-map
|
||||
* chaining, and physical watch dependencies hidden behind virtual CSS Modules.
|
||||
*/
|
||||
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { join } from 'node:path'
|
||||
import { dirname, join, relative } from 'node:path'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
import { describe, expect, it, vi } from 'vitest'
|
||||
import { clientBundle, requestedExternals } from '../packages/client/tsdown.client.ts'
|
||||
import { build, type TsdownBundle, type UserConfig } from 'tsdown'
|
||||
import { describe, expect, it, onTestFinished, vi } from 'vitest'
|
||||
import { clientBundle, requestedExternals, staticLinked } from '../packages/client/tsdown.client.ts'
|
||||
|
||||
type ResolveId = (source: string) => null | { id: string; external: boolean }
|
||||
|
||||
@@ -22,6 +23,18 @@ interface SourceMapPlugin {
|
||||
load?: (id: string) => Promise<unknown>
|
||||
}
|
||||
|
||||
interface InputIsolationPlugin {
|
||||
name: string
|
||||
generateBundle: (this: {
|
||||
getModuleInfo(id: string): { importedIds: string[]; dynamicallyImportedIds: string[] } | null
|
||||
}, options: unknown, bundle: Record<string, {
|
||||
type: 'chunk'
|
||||
modules: Record<string, object>
|
||||
imports: string[]
|
||||
dynamicImports: string[]
|
||||
}>) => void
|
||||
}
|
||||
|
||||
/** A representative dynamic bundle using the shared client baseline. */
|
||||
const REQUESTING_PACKAGE = '@deepseek-ai/dsh-client-ui-conversation'
|
||||
|
||||
@@ -43,6 +56,34 @@ describe('client bundle build faces', () => {
|
||||
})
|
||||
})
|
||||
|
||||
describe('client bundle dynamic imports', () => {
|
||||
it('compiles import() to the module loader asynchronous operation', async () => {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-client-dynamic-import-'))
|
||||
onTestFinished(() => { rmSync(root, { recursive: true, force: true }) })
|
||||
const entry = join(root, 'lib/types/client/index.js')
|
||||
mkdirSync(dirname(entry), { recursive: true })
|
||||
writeFileSync(join(root, 'package.json'), JSON.stringify({ name: REQUESTING_PACKAGE, type: 'module' }))
|
||||
writeFileSync(entry, 'export const load = () => import("./terminal.js")\n')
|
||||
writeFileSync(join(dirname(entry), 'terminal.js'), 'export const marker = "terminal"\n')
|
||||
const config = clientConfigs()[0]
|
||||
if (config === undefined) throw new Error('client config missing')
|
||||
|
||||
let builds: TsdownBundle[] = []
|
||||
try {
|
||||
builds = await build({
|
||||
...config, cwd: root, config: false, tsconfig: false,
|
||||
write: false, clean: false, exports: false, report: false, logLevel: 'silent',
|
||||
})
|
||||
const chunks = builds.flatMap(bundle => bundle.chunks).filter(chunk => chunk.type === 'chunk')
|
||||
const output = chunks.find(chunk => chunk.fileName === 'client.js')?.code
|
||||
expect(output).toContain('require.async("./client.terminal.js")')
|
||||
expect(output).not.toContain('Promise.resolve().then(() => require("./client.terminal.js"))')
|
||||
} finally {
|
||||
for (const bundle of builds) await bundle[Symbol.asyncDispose]()
|
||||
}
|
||||
})
|
||||
})
|
||||
|
||||
function clientSourceMapPath(packagePath: string): string {
|
||||
return fileURLToPath(new URL(`../packages/${packagePath}/lib/client.js.map`, import.meta.url))
|
||||
}
|
||||
@@ -147,6 +188,175 @@ describe('client bundle purity gate', () => {
|
||||
})
|
||||
})
|
||||
|
||||
describe('client bundle experimental input isolation', () => {
|
||||
const experimental = '@deepseek-ai/dsh-experimental-client-ui-agent-team'
|
||||
|
||||
function fixture() {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-client-inputs-'))
|
||||
onTestFinished(() => { rmSync(root, { recursive: true, force: true }) })
|
||||
const owner = join(root, 'client')
|
||||
const entry = join(owner, 'lib/types/client/index.js')
|
||||
const prototype = join(root, 'prototype/src/index.js')
|
||||
for (const file of [entry, prototype]) mkdirSync(dirname(file), { recursive: true })
|
||||
writeFileSync(join(owner, 'package.json'), JSON.stringify({ name: REQUESTING_PACKAGE, type: 'module' }))
|
||||
writeFileSync(join(root, 'prototype/package.json'), JSON.stringify({ name: experimental, type: 'module' }))
|
||||
writeFileSync(prototype, 'export const marker = "experimental sentinel"\n')
|
||||
return { root, owner, entry, prototype }
|
||||
}
|
||||
|
||||
function config(kind: 'static' | 'dynamic', id = REQUESTING_PACKAGE): UserConfig {
|
||||
const configs = kind === 'static'
|
||||
? staticLinked(id, ['lib/types/client/index.js'])({ env: { DSH_BUILD_FACE: 'client' } })
|
||||
: clientConfigs(id)
|
||||
const browser = configs.find(config => config.platform === 'browser')
|
||||
if (browser === undefined) throw new Error('client config missing')
|
||||
return browser
|
||||
}
|
||||
|
||||
async function bundle(owner: string, config: UserConfig): Promise<string> {
|
||||
let builds: TsdownBundle[] = []
|
||||
try {
|
||||
builds = await build({
|
||||
...config, cwd: owner, config: false, tsconfig: false,
|
||||
write: false, clean: false, exports: false, report: false, logLevel: 'silent',
|
||||
})
|
||||
return builds.flatMap(build => build.chunks.filter(chunk => chunk.type === 'chunk').map(chunk => chunk.code)).join('\n')
|
||||
} finally {
|
||||
for (const build of builds) await build[Symbol.asyncDispose]()
|
||||
}
|
||||
}
|
||||
|
||||
function importPath(from: string, to: string): string {
|
||||
return relative(dirname(from), to).replaceAll('\\', '/')
|
||||
}
|
||||
|
||||
function checkCompilerModule(module: string, imports?: string[]): void {
|
||||
const plugins = config('dynamic').plugins as InputIsolationPlugin[]
|
||||
const plugin = plugins.find(plugin => plugin.name === 'dsh-client-input-isolation')
|
||||
if (plugin === undefined) throw new Error('client input isolation plugin missing')
|
||||
plugin.generateBundle.call({
|
||||
getModuleInfo: () => imports === undefined ? null : { importedIds: imports, dynamicallyImportedIds: [] },
|
||||
}, {}, {
|
||||
'client.js': { type: 'chunk', modules: { [module]: {} }, imports: [], dynamicImports: [] },
|
||||
})
|
||||
}
|
||||
|
||||
it('accepts the exact compiler runtime helper without a source module record', () => {
|
||||
expect(() => { checkCompilerModule('\0rolldown/runtime.js') }).not.toThrow()
|
||||
})
|
||||
|
||||
it.each(['\0rolldown/other.js', '\0rolldown/runtime.js?user', '\0other/runtime.js'])(
|
||||
'rejects the unrecorded module %j',
|
||||
(module) => {
|
||||
expect(() => { checkCompilerModule(module) }).toThrow(/has no bundler module record/)
|
||||
},
|
||||
)
|
||||
|
||||
it('checks runtime helper dependencies when the compiler supplies a module record', () => {
|
||||
expect(() => { checkCompilerModule('\0rolldown/runtime.js', [experimental]) })
|
||||
.toThrow(/client bundle isolation.*experimental/)
|
||||
})
|
||||
|
||||
it.each(['static', 'dynamic'] as const)('rejects experimental files folded into a %s client artifact', async (kind) => {
|
||||
const { owner, entry, prototype } = fixture()
|
||||
writeFileSync(entry, `export { marker } from ${JSON.stringify(importPath(entry, prototype))}\n`)
|
||||
|
||||
await expect(bundle(owner, config(kind))).rejects.toThrow(/client bundle isolation.*experimental/)
|
||||
expect(existsSync(join(owner, 'lib/client.js'))).toBe(false)
|
||||
expect(existsSync(join(owner, 'lib/index.js'))).toBe(false)
|
||||
})
|
||||
|
||||
it('proves the static library otherwise hides the experimental input in its emitted JavaScript', async () => {
|
||||
const { owner, entry, prototype } = fixture()
|
||||
writeFileSync(entry, `export { marker } from ${JSON.stringify(importPath(entry, prototype))}\n`)
|
||||
const guarded = config('static')
|
||||
const plugins = guarded.plugins as Array<{ name: string }>
|
||||
const unguarded: UserConfig = {
|
||||
...guarded,
|
||||
plugins: plugins.filter(plugin => plugin.name !== 'dsh-client-input-isolation'),
|
||||
outputOptions: { sourcemapExcludeSources: false },
|
||||
}
|
||||
|
||||
await expect(bundle(owner, unguarded)).resolves.toContain('experimental sentinel')
|
||||
await expect(bundle(owner, guarded)).rejects.toThrow(/client bundle isolation.*experimental/)
|
||||
})
|
||||
|
||||
it.each(['static', 'dynamic'] as const)('allows an experimental %s artifact to keep its own inputs', async (kind) => {
|
||||
const { owner, entry, prototype } = fixture()
|
||||
writeFileSync(entry, `export { marker } from ${JSON.stringify(importPath(entry, prototype))}\n`)
|
||||
|
||||
await expect(bundle(owner, config(kind, experimental))).resolves.toContain('experimental sentinel')
|
||||
})
|
||||
|
||||
it('rejects experimental ownership preserved only by an emitted compiler source map', async () => {
|
||||
const { owner, entry, prototype } = fixture()
|
||||
writeFileSync(entry, 'export const marker = "experimental sentinel"\n//# sourceMappingURL=index.js.map\n')
|
||||
writeFileSync(`${entry}.map`, JSON.stringify({
|
||||
version: 3, names: [], mappings: 'AAAA', sources: [importPath(entry, prototype)],
|
||||
sourcesContent: ['export const marker = "experimental sentinel"\n'],
|
||||
}))
|
||||
|
||||
await expect(bundle(owner, config('static'))).rejects.toThrow(/client bundle isolation.*experimental/)
|
||||
})
|
||||
|
||||
it('checks the resolved module when an import alias conceals its experimental package', async () => {
|
||||
const { owner, entry, prototype } = fixture()
|
||||
writeFileSync(entry, 'export { marker } from "./ordinary.js"\n')
|
||||
|
||||
await expect(bundle(owner, { ...config('static'), alias: { './ordinary.js': prototype } }))
|
||||
.rejects.toThrow(/client bundle isolation.*experimental/)
|
||||
})
|
||||
|
||||
it('rejects an experimental runtime import left external by a static client library', async () => {
|
||||
const { owner, entry } = fixture()
|
||||
writeFileSync(entry, `export * from ${JSON.stringify(experimental)}\n`)
|
||||
|
||||
await expect(bundle(owner, config('static'))).rejects.toThrow(/client bundle isolation.*experimental/)
|
||||
})
|
||||
|
||||
it.each([false, true])('checks omitted source-map files against their package owner (experimental: %s)', async (experimentalSource) => {
|
||||
const { root, owner, entry } = fixture()
|
||||
const dependency = join(root, 'dependency')
|
||||
mkdirSync(dependency)
|
||||
writeFileSync(join(dependency, 'package.json'), JSON.stringify({ name: experimentalSource ? experimental : 'ordinary-library' }))
|
||||
writeFileSync(entry, 'export const marker = "mapped sentinel"\n//# sourceMappingURL=index.js.map\n')
|
||||
writeFileSync(`${entry}.map`, JSON.stringify({
|
||||
version: 3, names: [], mappings: 'AAAA', sourceRoot: importPath(entry, dependency),
|
||||
sources: ['unshipped.ts'], sourcesContent: ['export const marker = "mapped sentinel"\n'],
|
||||
}))
|
||||
|
||||
const result = bundle(owner, config('static'))
|
||||
if (experimentalSource) await expect(result).rejects.toThrow(/client bundle isolation.*experimental/)
|
||||
else await expect(result).resolves.toContain('mapped sentinel')
|
||||
})
|
||||
|
||||
it.each(['.css', '.module.css', '.css?inline'])('rejects experimental %s inputs behind client CSS virtual loaders', async (extension) => {
|
||||
const { owner, entry, prototype } = fixture()
|
||||
const css = join(dirname(prototype), `style${extension.replace('?inline', '')}`)
|
||||
writeFileSync(css, 'body { color: red; }\n')
|
||||
const specifier = `${importPath(entry, css)}${extension.endsWith('?inline') ? '?inline' : ''}`
|
||||
writeFileSync(entry, extension === '.css'
|
||||
? `import ${JSON.stringify(specifier)}\nexport const marker = true\n`
|
||||
: `export { default as style } from ${JSON.stringify(specifier)}\n`)
|
||||
|
||||
await expect(bundle(owner, config('dynamic'))).rejects.toThrow(/client bundle isolation.*experimental/)
|
||||
})
|
||||
|
||||
it.each(['static', 'dynamic'] as const)('keeps ordinary %s bundles and source maps buildable', async (kind) => {
|
||||
const { owner, entry } = fixture()
|
||||
const source = join(owner, 'src/client/index.ts')
|
||||
mkdirSync(dirname(source), { recursive: true })
|
||||
writeFileSync(source, 'export const marker = "stable sentinel"\n')
|
||||
writeFileSync(entry, 'export const marker = "stable sentinel"\n//# sourceMappingURL=index.js.map\n')
|
||||
writeFileSync(`${entry}.map`, JSON.stringify({
|
||||
version: 3, names: [], mappings: 'AAAA', sources: [importPath(entry, source)],
|
||||
sourcesContent: ['export const marker = "stable sentinel"\n'],
|
||||
}))
|
||||
|
||||
await expect(bundle(owner, config(kind))).resolves.toContain('stable sentinel')
|
||||
})
|
||||
})
|
||||
|
||||
describe('client bundle module requests', () => {
|
||||
it('requests what the declaration lists', () => {
|
||||
const requests = requestedExternals('@deepseek-ai/dsh-client-fixture', {
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
/**
|
||||
* Canonicalize coverage locations inside a coverage partition, before its
|
||||
* blob is written.
|
||||
*
|
||||
* Vitest reaches every reporter's `onCoverage` with the finished run's coverage
|
||||
* map and lets the blob reporter serialize that same map later, in
|
||||
* `onTestRunEnd`, so this reporter sees the locations while they are numeric.
|
||||
* ast-v8-to-istanbul ends a whole-line statement at column `Infinity`, which the
|
||||
* blob's JSON hop turns into `null`; istanbul-lib-coverage reconciles the
|
||||
* per-environment spellings of one statement only through numeric columns, so a
|
||||
* `null` column leaves a client-only spelling behind as a phantom uncovered
|
||||
* statement. Replacing each non-finite end column with
|
||||
* {@link END_OF_LINE_COLUMN} keeps the line-end meaning and keys identically in
|
||||
* every blob, so the merge attributes the coverage one process would have.
|
||||
*
|
||||
* @see ../.agents/notes/implemented/bug-fix/2026-09-13-partitioned-coverage-location-canonicalization.md
|
||||
* @module
|
||||
*/
|
||||
|
||||
/**
|
||||
* End column of a location that spans to the end of its start line, and the
|
||||
* finite stand-in for ast-v8-to-istanbul's unrepresentable `Infinity`.
|
||||
*/
|
||||
export const END_OF_LINE_COLUMN = Number.MAX_SAFE_INTEGER
|
||||
|
||||
/** Mutable structural view of the istanbul coverage map handed to reporters. */
|
||||
type CoverageRecord = Record<string, unknown>
|
||||
|
||||
/** Whether a value is a non-null object usable as a mutable record. */
|
||||
function isRecord(value: unknown): value is CoverageRecord {
|
||||
return typeof value === 'object' && value !== null
|
||||
}
|
||||
|
||||
/** Rewrite one location's non-finite end column in place. */
|
||||
function canonicalizeLocation(location: unknown): void {
|
||||
if (!isRecord(location)) return
|
||||
const end = location['end']
|
||||
if (!isRecord(end)) return
|
||||
const column = end['column']
|
||||
if (typeof column === 'number' && Number.isFinite(column)) return
|
||||
end['column'] = END_OF_LINE_COLUMN
|
||||
}
|
||||
|
||||
/** Rewrite every location a statement, function, or branch entry carries. */
|
||||
function canonicalizeEntry(entry: unknown): void {
|
||||
if (!isRecord(entry)) return
|
||||
// A statement is a location itself; a function carries `decl` plus `loc`, and
|
||||
// a branch carries `loc` plus one location per branch path.
|
||||
canonicalizeLocation(entry)
|
||||
canonicalizeLocation(entry['decl'])
|
||||
canonicalizeLocation(entry['loc'])
|
||||
const locations = entry['locations']
|
||||
if (Array.isArray(locations)) for (const location of locations) canonicalizeLocation(location)
|
||||
}
|
||||
|
||||
/**
|
||||
* Replace every non-finite end column of an istanbul coverage map in place.
|
||||
* @param coverageMap - istanbul `CoverageMap` whose `data` holds per-file coverage.
|
||||
* @throws Error when the payload carries no istanbul `data` record, so a Vitest
|
||||
* change that stops handing reporters that map fails the partition instead of
|
||||
* leaving every location uncanonicalized. Inner structure a `CoverageMap`
|
||||
* always carries is read without further checks.
|
||||
*/
|
||||
export function canonicalizeEndOfLineColumns(coverageMap: unknown): void {
|
||||
const files = isRecord(coverageMap) ? coverageMap['data'] : undefined
|
||||
if (!isRecord(files)) {
|
||||
throw new Error('coverage-canonical-locations: onCoverage payload is not an istanbul CoverageMap')
|
||||
}
|
||||
for (const file of Object.values(files)) {
|
||||
if (!isRecord(file)) continue
|
||||
// FileCoverage keeps its maps on `data` and mirrors them as getters.
|
||||
const coverage = isRecord(file['data']) ? file['data'] : file
|
||||
for (const name of ['statementMap', 'fnMap', 'branchMap']) {
|
||||
const entries = coverage[name]
|
||||
if (!isRecord(entries)) continue
|
||||
for (const entry of Object.values(entries)) canonicalizeEntry(entry)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Vitest reporter that canonicalizes a partition's coverage map in
|
||||
* {@link CanonicalCoverageLocationsReporter.onCoverage}, the hook Vitest runs
|
||||
* before the blob reporter serializes that map.
|
||||
*/
|
||||
export default class CanonicalCoverageLocationsReporter {
|
||||
/**
|
||||
* Canonicalize the finished run's coverage locations.
|
||||
* @param coverageMap - coverage map Vitest hands to every reporter.
|
||||
*/
|
||||
public onCoverage(coverageMap: unknown): void {
|
||||
canonicalizeEndOfLineColumns(coverageMap)
|
||||
}
|
||||
}
|
||||
@@ -1,6 +1,8 @@
|
||||
import { access, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
|
||||
import { createRequire } from 'node:module'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { dirname, join } from 'node:path'
|
||||
import { dirname, join, resolve } from 'node:path'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
import { afterEach, describe, expect, it, vi } from 'vitest'
|
||||
import {
|
||||
COVERAGE_PARTITION_MODE_ENV,
|
||||
@@ -19,6 +21,10 @@ import {
|
||||
type CoverageCommandResult,
|
||||
type CoveragePartitionCoordinatorOptions,
|
||||
} from './coverage-partitions.ts'
|
||||
import {
|
||||
END_OF_LINE_COLUMN,
|
||||
canonicalizeEndOfLineColumns,
|
||||
} from './coverage-canonical-locations.ts'
|
||||
|
||||
const passed: CoverageCommandResult = { exitCode: 0, signalCode: null }
|
||||
|
||||
@@ -273,6 +279,154 @@ describe('coverage file inventory', () => {
|
||||
})
|
||||
})
|
||||
|
||||
/**
|
||||
* One source statement as two Vite environments spell it: the ssr map ends the
|
||||
* declaration at its identifier, the jsdom/client map at the nested call, and
|
||||
* both stop at their own line's end.
|
||||
*/
|
||||
const CRASH_LOOP = { start: { line: 36, column: 2 }, end: { line: 54, column: Infinity } }
|
||||
|
||||
/** File path the canonicalization fixtures share. */
|
||||
const CANONICALIZED_FILE = 'packages/util/home-paths/src/index.ts'
|
||||
|
||||
/** Istanbul statement location in the fixture's own terms. */
|
||||
interface StatementLocation {
|
||||
start: { line: number; column: number }
|
||||
end: { line: number; column: number }
|
||||
}
|
||||
|
||||
/** Statement hits and locations read back from a merged istanbul map. */
|
||||
interface MergedStatements {
|
||||
s: Record<string, number>
|
||||
statementMap: Record<string, StatementLocation>
|
||||
}
|
||||
|
||||
/** The istanbul entry points the merge assertions use. */
|
||||
interface CoverageLibrary {
|
||||
createCoverageMap: (data: unknown) => {
|
||||
merge: (data: unknown) => void
|
||||
fileCoverageFor: (file: string) => MergedStatements
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* istanbul-lib-coverage is the merge implementation the partition blobs feed.
|
||||
* It arrives as a dependency of the declared istanbul-lib-report devDependency,
|
||||
* so this spec resolves it through that owner instead of declaring its own copy.
|
||||
*/
|
||||
const coverageLibrary = createRequire(
|
||||
createRequire(import.meta.url).resolve('istanbul-lib-report'),
|
||||
)('istanbul-lib-coverage') as CoverageLibrary
|
||||
|
||||
/** One file's statement coverage, shaped as a partition blob carries it. */
|
||||
function statementRecord(statements: StatementLocation[], hits: number[]): Record<string, unknown> {
|
||||
return {
|
||||
[CANONICALIZED_FILE]: {
|
||||
path: CANONICALIZED_FILE,
|
||||
statementMap: Object.fromEntries(statements.map((location, index) => [index, location])),
|
||||
s: Object.fromEntries(hits.map((hit, index) => [index, hit])),
|
||||
fnMap: {},
|
||||
f: {},
|
||||
branchMap: {},
|
||||
b: {},
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Merge partition records the way the coordinator's merge command does. The
|
||||
* blob serializer's JSON hop turns a non-finite end column into `null`, which
|
||||
* is what strips istanbul of the range containment it reconciles records with.
|
||||
* Canonicalization runs on the `CoverageMap` the reporter hook receives, whose
|
||||
* `data` holds the raw per-file records merged here.
|
||||
*/
|
||||
function mergePartitionRecords(
|
||||
records: Array<Record<string, unknown>>,
|
||||
canonicalize: boolean,
|
||||
): MergedStatements {
|
||||
const map = coverageLibrary.createCoverageMap({})
|
||||
for (const record of records) {
|
||||
if (canonicalize) canonicalizeEndOfLineColumns({ data: record })
|
||||
map.merge(JSON.parse(JSON.stringify(record)) as unknown)
|
||||
}
|
||||
return map.fileCoverageFor(CANONICALIZED_FILE)
|
||||
}
|
||||
|
||||
/** Start positions of the statements the merged map still reports as unhit. */
|
||||
function uncoveredStarts(coverage: MergedStatements): Array<{ line: number; column: number }> {
|
||||
return Object.entries(coverage.s)
|
||||
.filter(([, hits]) => hits === 0)
|
||||
.map(([index]) => coverage.statementMap[index])
|
||||
.filter((location): location is StatementLocation => location !== undefined)
|
||||
.map(location => location.start)
|
||||
}
|
||||
|
||||
describe('coverage location canonicalization', () => {
|
||||
// index.ts:48 as the ssr environment spells it (at `parent`) and as the
|
||||
// client environment spells it (at `dirname(current)`); the loop holding
|
||||
// both spellings ran in each, and only the client record never took the
|
||||
// catch branch that owns the statement.
|
||||
const ssrRecord = statementRecord(
|
||||
[CRASH_LOOP, { start: { line: 48, column: 12 }, end: { line: 48, column: Infinity } }],
|
||||
[3, 2],
|
||||
)
|
||||
const clientRecord = statementRecord(
|
||||
[CRASH_LOOP, { start: { line: 48, column: 21 }, end: { line: 48, column: Infinity } }],
|
||||
[5, 0],
|
||||
)
|
||||
|
||||
it('drops the phantom statement a client-only spelling leaves after the blob merge', () => {
|
||||
// 33 statements, 32 covered: the ssr spelling is hit while the client
|
||||
// spelling of the same source statement stays unhit, so a file whose every
|
||||
// statement ran fails the per-file 100% gate.
|
||||
expect(uncoveredStarts(mergePartitionRecords([ssrRecord, clientRecord], false)))
|
||||
.toEqual([{ line: 48, column: 21 }])
|
||||
|
||||
expect(uncoveredStarts(mergePartitionRecords([ssrRecord, clientRecord], true))).toEqual([])
|
||||
})
|
||||
|
||||
it('canonicalizes line-end columns in statement, function, and branch locations', () => {
|
||||
const lineEnd = (line: number): StatementLocation => ({
|
||||
start: { line, column: 4 },
|
||||
end: { line, column: Infinity },
|
||||
})
|
||||
const record = {
|
||||
[CANONICALIZED_FILE]: {
|
||||
path: CANONICALIZED_FILE,
|
||||
statementMap: { 0: lineEnd(10), 1: { start: { line: 11, column: 4 }, end: { line: 11, column: 9 } } },
|
||||
s: { 0: 1, 1: 1 },
|
||||
fnMap: { 0: { name: 'probe', decl: lineEnd(10), loc: lineEnd(10) } },
|
||||
f: { 0: 1 },
|
||||
branchMap: { 0: { type: 'if', loc: lineEnd(12), locations: [lineEnd(12), lineEnd(13)] } },
|
||||
b: { 0: [1, 1] },
|
||||
},
|
||||
}
|
||||
|
||||
canonicalizeEndOfLineColumns({ data: record })
|
||||
|
||||
const file = record[CANONICALIZED_FILE]
|
||||
expect(file.statementMap[0]?.end.column).toBe(END_OF_LINE_COLUMN)
|
||||
expect(file.statementMap[1]?.end.column).toBe(9)
|
||||
expect(file.fnMap[0]?.decl.end.column).toBe(END_OF_LINE_COLUMN)
|
||||
expect(file.fnMap[0]?.loc.end.column).toBe(END_OF_LINE_COLUMN)
|
||||
expect(file.branchMap[0]?.loc.end.column).toBe(END_OF_LINE_COLUMN)
|
||||
expect(file.branchMap[0]?.locations[0]?.end.column).toBe(END_OF_LINE_COLUMN)
|
||||
expect(file.branchMap[0]?.locations[1]?.end.column).toBe(END_OF_LINE_COLUMN)
|
||||
})
|
||||
|
||||
it('rejects a payload that carries no istanbul coverage data', () => {
|
||||
// Vitest types the reporter hook as `unknown`, so a payload without the
|
||||
// istanbul `data` record must fail the partition loudly rather than leave
|
||||
// every location uncanonicalized.
|
||||
expect(() => {
|
||||
canonicalizeEndOfLineColumns(undefined)
|
||||
}).toThrow(/not an istanbul CoverageMap/)
|
||||
expect(() => {
|
||||
canonicalizeEndOfLineColumns({})
|
||||
}).toThrow(/not an istanbul CoverageMap/)
|
||||
})
|
||||
})
|
||||
|
||||
describe('coverage partition coordinator', () => {
|
||||
const weightedFiles = ['a.spec.ts', 'b.spec.ts', 'c.spec.ts']
|
||||
const weightedDurations = new Map([
|
||||
@@ -285,6 +439,34 @@ describe('coverage partition coordinator', () => {
|
||||
['b.spec.ts', 'process-bound'],
|
||||
['c.spec.ts', 'process-bound'],
|
||||
])
|
||||
it('passes the canonicalizing reporter to every partition', async () => {
|
||||
const root = await temporaryRoot()
|
||||
const commands: CoverageCommand[] = []
|
||||
const runCommand = successfulCommandRecorder(commands)
|
||||
const coordinator = new CoveragePartitionCoordinator({
|
||||
root,
|
||||
partitions: 2,
|
||||
pnpmEntrypoint: '/pnpm.cjs',
|
||||
files: ['a.spec.ts', 'b.spec.ts'],
|
||||
runCommand,
|
||||
})
|
||||
|
||||
await expect(coordinator.run()).resolves.toBe(0)
|
||||
|
||||
// The coordinator passes a root-relative argument and runs every child with
|
||||
// the repository root as its working directory, so the argument must name
|
||||
// the reporter that sits beside this spec. Whether that reporter runs
|
||||
// before the blob write is Vitest's reporter ordering, not a command the
|
||||
// coordinator builds.
|
||||
const specDirectory = dirname(fileURLToPath(import.meta.url))
|
||||
const reporterPath = join(specDirectory, 'coverage-canonical-locations.ts')
|
||||
for (const command of commands.slice(0, 2)) {
|
||||
const argument = command.args.find(candidate => candidate.startsWith('--reporter=') && candidate.endsWith('coverage-canonical-locations.ts'))
|
||||
if (argument === undefined) throw new Error(`${command.label} does not wire the coverage canonicalizer`)
|
||||
expect(resolve(specDirectory, '..', argument.slice('--reporter='.length))).toBe(reporterPath)
|
||||
}
|
||||
})
|
||||
|
||||
it('runs every single-worker partition before one merged threshold check', async () => {
|
||||
const root = await temporaryRoot()
|
||||
const commands: CoverageCommand[] = []
|
||||
|
||||
@@ -15,6 +15,14 @@ export const COVERAGE_PARTITION_MODE_ENV = 'DSH_COVERAGE_PARTITION_MODE'
|
||||
/** Environment variable overriding instrumented test, polling, and hook timeouts. */
|
||||
export const COVERAGE_TEST_TIMEOUT_ENV = 'DSH_COVERAGE_TEST_TIMEOUT_MS'
|
||||
|
||||
/**
|
||||
* Reporter that canonicalizes a partition's coverage locations before its blob
|
||||
* is serialized (see scripts/coverage-canonical-locations.ts). Root-relative in
|
||||
* POSIX spelling because every child runs with the repository root as its
|
||||
* working directory on every platform.
|
||||
*/
|
||||
const CANONICAL_LOCATIONS_REPORTER = './scripts/coverage-canonical-locations.ts'
|
||||
|
||||
/** One child command owned by the coverage coordinator. */
|
||||
export interface CoverageCommand {
|
||||
/** Diagnostic identity. */
|
||||
@@ -561,6 +569,7 @@ export class CoveragePartitionCoordinator {
|
||||
'--reporter=default',
|
||||
'--reporter=blob',
|
||||
'--reporter=json',
|
||||
`--reporter=${CANONICAL_LOCATIONS_REPORTER}`,
|
||||
`--outputFile.blob=${this.relativePath(blobPath)}`,
|
||||
`--outputFile.json=${this.relativePath(jsonReportPath)}`,
|
||||
`--coverage.reportsDirectory=${this.relativePath(reportsDirectory)}`,
|
||||
|
||||
@@ -17,6 +17,14 @@
|
||||
const path = require('node:path');
|
||||
const { ReportBase } = require('istanbul-lib-report');
|
||||
|
||||
/**
|
||||
* End column of a location that spans to the end of its start line. Whole-line
|
||||
* statements carry `Infinity` until a partition blob serializes it, which the
|
||||
* partition reporter replaces with this finite column
|
||||
* (scripts/coverage-canonical-locations.ts); both spellings read as line ends.
|
||||
*/
|
||||
const END_OF_LINE_COLUMN = Number.MAX_SAFE_INTEGER;
|
||||
|
||||
/**
|
||||
* Editor-convention `line:column` of an istanbul location start (istanbul
|
||||
* columns are 0-based; editors and terminal link handlers expect 1-based).
|
||||
@@ -30,15 +38,20 @@ function usable(loc) {
|
||||
return Boolean(loc && loc.start && Number.isFinite(loc.start.line) && loc.start.line >= 1);
|
||||
}
|
||||
|
||||
/** Whether an end column marks its line's end instead of a measured position. */
|
||||
function atLineEnd(column) {
|
||||
return !Number.isFinite(column) || column >= END_OF_LINE_COLUMN;
|
||||
}
|
||||
|
||||
/**
|
||||
* ` (to line:col)` suffix when the range end adds information beyond the
|
||||
* start. v8-remapped whole-line statements carry end.column = Infinity; those
|
||||
* start. v8-remapped whole-line statements end at their line end; those
|
||||
* degrade to a line-only suffix, or to nothing on a single line.
|
||||
*/
|
||||
function endSuffix(loc) {
|
||||
const end = loc.end;
|
||||
if (!end || !Number.isFinite(end.line) || end.line < 1) return '';
|
||||
if (!Number.isFinite(end.column)) {
|
||||
if (atLineEnd(end.column)) {
|
||||
return end.line === loc.start.line ? '' : ` (to ${end.line})`;
|
||||
}
|
||||
if (end.line === loc.start.line && end.column === loc.start.column) return '';
|
||||
|
||||
+8539
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"capturedAt": "2026-09-12T08:56:20.434Z",
|
||||
"npm": "11.17.0",
|
||||
"node": "24.19.0",
|
||||
"platform": "darwin",
|
||||
"arch": "arm64",
|
||||
"registry": "https://registry.npmjs.org/",
|
||||
"installStrategy": "hoisted"
|
||||
}
|
||||
@@ -42,6 +42,9 @@ const KIND_TEMPLATES: Readonly<Record<string, string>> = {
|
||||
'package-reference': '.agents/skills/dsh-doc/templates/package-reference.md',
|
||||
'package-library': '.agents/skills/dsh-doc/templates/package-library.md',
|
||||
'package-bundle': '.agents/skills/dsh-doc/templates/package-bundle.md',
|
||||
'persistence-change': '.agents/skills/dsh-doc/templates/persistence-change.md',
|
||||
'persistence-release': '.agents/skills/dsh-doc/templates/persistence-release.md',
|
||||
'persistence-format': '.agents/skills/dsh-doc/templates/persistence-format.md',
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -51,6 +54,7 @@ const KIND_TEMPLATES: Readonly<Record<string, string>> = {
|
||||
* library; the check re-derives the entry shape so a stale entry fails loud.
|
||||
*/
|
||||
const PACKAGE_LIBRARIES: Readonly<Record<string, string>> = {
|
||||
'packages/experimental/browser-use-runtime': 'Provider-owned browser resource management and MCP integration helpers; no plugin entry.',
|
||||
'packages/boot/app-boot': 'Boot library the app bins import; plain helper exports.',
|
||||
'packages/boot/cmdline': 'Command-line library the app bins import; plain module exports.',
|
||||
'packages/client/store': 'Browser-side state primitives; plain function/type exports.',
|
||||
@@ -78,6 +82,7 @@ const PACKAGE_LIBRARIES: Readonly<Record<string, string>> = {
|
||||
'packages/test-support/client-runtime': 'Browser-side test infrastructure.',
|
||||
'packages/test-support/llm-mock-server': 'Test server library; substitutes provider wire behavior.',
|
||||
'packages/test-support/loader-smoke': 'Test harness library; mounts nothing into a product composition.',
|
||||
'packages/test-support/remote-mock': 'Browser-side test infrastructure; mounts nothing into a product composition.',
|
||||
'packages/typert/generator': 'Build-time generator run outside any agent runtime.',
|
||||
'packages/typert/protocol': 'Compiler-independent protocol declarations.',
|
||||
'packages/util/atomic-write': 'Zero-dependency filesystem write utility.',
|
||||
@@ -87,6 +92,7 @@ const PACKAGE_LIBRARIES: Readonly<Record<string, string>> = {
|
||||
'packages/util/chunked-list': 'Persistent collection operations and checkpoint validation without a plugin surface.',
|
||||
'packages/util/home-paths': 'Zero-dependency harness-home path resolver.',
|
||||
'packages/util/launch-environment': 'Zero-dependency environment resolver.',
|
||||
'packages/util/lazy-require': 'Caller-relative CommonJS-compatible dependency loader.',
|
||||
'packages/util/native-command': 'Host-side subprocess runner utility.',
|
||||
'packages/util/output-retention': 'Zero-dependency retention utility.',
|
||||
'packages/util/package-manifest': 'Shared package manifest declarations with type-only exports.',
|
||||
@@ -153,7 +159,7 @@ interface SessionFormatRelease {
|
||||
evidenceTag: string
|
||||
}
|
||||
|
||||
/** Validate the release record and evidence links; throw on malformed or inconsistent input. */
|
||||
/** Validate release metadata and tagged writer evidence; throw on malformed or inconsistent input. */
|
||||
function validateSessionFormatRelease(source: string, currentWriterVersion: number): SessionFormatRelease {
|
||||
const normalized = source.replaceAll('\r\n', '\n')
|
||||
const openings = [...normalized.matchAll(/^```yaml session-format-release[ \t]*$/gmu)]
|
||||
@@ -180,34 +186,28 @@ function validateSessionFormatRelease(source: string, currentWriterVersion: numb
|
||||
|| !/^dsh-v\d+\.\d+\.\d+(?:-[\dA-Za-z]+(?:[.-][\dA-Za-z]+)*)?(?:\+[\dA-Za-z]+(?:[.-][\dA-Za-z]+)*)?$/u.test(evidenceTag)) {
|
||||
throw new Error('evidenceTag must be a non-empty dsh-v version tag without URL delimiters')
|
||||
}
|
||||
const repository = 'https://github.com/deepseek-harness/deepseek-harness'
|
||||
for (const link of [
|
||||
`${repository}/releases/tag/${evidenceTag}`,
|
||||
`${repository}/blob/${evidenceTag}/packages/core/session/src/types.ts`,
|
||||
]) {
|
||||
if (!normalized.includes(`](${link})`)) throw new Error(`Missing matching evidence link: ${link}`)
|
||||
}
|
||||
const hasEvidence = normalized.split('\n').some(line =>
|
||||
line.includes(`\`${evidenceTag}\``) && line.includes('`packages/core/session/src/types.ts`'))
|
||||
if (!hasEvidence) throw new Error('Missing matching evidence tag and tagged writer path')
|
||||
return { latestReleasedVersion, evidenceTag }
|
||||
}
|
||||
|
||||
function sessionFormatReleaseFixture(): { record: SessionFormatRelease; body: string; links: string; source: string } {
|
||||
function sessionFormatReleaseFixture(): { record: SessionFormatRelease; body: string; evidence: string; source: string } {
|
||||
const record = validateSessionFormatRelease(
|
||||
readFileSync(resolve(root, 'docs/session-format-status.md'), 'utf8'),
|
||||
readCurrentSessionFormatVersion(root),
|
||||
)
|
||||
const body = `latestReleasedVersion: ${record.latestReleasedVersion}\nevidenceTag: ${record.evidenceTag}`
|
||||
const repository = 'https://github.com/deepseek-harness/deepseek-harness'
|
||||
const links = `[release](${repository}/releases/tag/${record.evidenceTag})\n`
|
||||
+ `[source](${repository}/blob/${record.evidenceTag}/packages/core/session/src/types.ts)`
|
||||
return { record, body, links, source: releaseDocument(body, links) }
|
||||
const evidence = `Evidence: published product tag \`${record.evidenceTag}\`; tagged writer: \`packages/core/session/src/types.ts\`.`
|
||||
return { record, body, evidence, source: releaseDocument(body, evidence) }
|
||||
}
|
||||
|
||||
function releaseDocument(body: string, links: string): string {
|
||||
return `\`\`\`yaml session-format-release\n${body}\n\`\`\`\n\n${links}\n`
|
||||
function releaseDocument(body: string, evidence: string): string {
|
||||
return `\`\`\`yaml session-format-release\n${body}\n\`\`\`\n\n${evidence}\n`
|
||||
}
|
||||
|
||||
describe('Session format release authority', () => {
|
||||
it('keeps the bilingual release records equal and consistent with the writer and evidence links', () => {
|
||||
it('keeps bilingual release metadata consistent with the writer and tagged evidence', () => {
|
||||
const records = ['docs/session-format-status.md', 'docs/session-format-status.zh.md'].map(file =>
|
||||
validateSessionFormatRelease(readFileSync(resolve(root, file), 'utf8'), readCurrentSessionFormatVersion(root)),
|
||||
)
|
||||
@@ -215,33 +215,33 @@ describe('Session format release authority', () => {
|
||||
})
|
||||
|
||||
it('accepts a released writer and a newer development writer, including format zero', () => {
|
||||
const { record, body, links, source } = sessionFormatReleaseFixture()
|
||||
const { record, body, evidence, source } = sessionFormatReleaseFixture()
|
||||
expect(validateSessionFormatRelease(source, record.latestReleasedVersion)).toEqual(record)
|
||||
expect(validateSessionFormatRelease(source, record.latestReleasedVersion + 1)).toEqual(record)
|
||||
const zero = releaseDocument(body.replace(`latestReleasedVersion: ${record.latestReleasedVersion}`, 'latestReleasedVersion: 0'), links)
|
||||
const zero = releaseDocument(body.replace(`latestReleasedVersion: ${record.latestReleasedVersion}`, 'latestReleasedVersion: 0'), evidence)
|
||||
expect(validateSessionFormatRelease(zero, 0)).toEqual({ ...record, latestReleasedVersion: 0 })
|
||||
})
|
||||
|
||||
it('rejects missing, duplicated, unclosed, and malformed release records', () => {
|
||||
const { record, body, links, source } = sessionFormatReleaseFixture()
|
||||
const { record, body, evidence, source } = sessionFormatReleaseFixture()
|
||||
for (const invalid of [
|
||||
links,
|
||||
evidence,
|
||||
source + source,
|
||||
source + '\n```yaml session-format-release\n',
|
||||
`\`\`\`yaml session-format-release\n${body}`,
|
||||
releaseDocument('[unterminated', links),
|
||||
releaseDocument('', links),
|
||||
releaseDocument('null', links),
|
||||
releaseDocument('scalar', links),
|
||||
releaseDocument(`- latestReleasedVersion: ${record.latestReleasedVersion}`, links),
|
||||
releaseDocument(`${body}\n---\n${body}`, links),
|
||||
releaseDocument('[unterminated', evidence),
|
||||
releaseDocument('', evidence),
|
||||
releaseDocument('null', evidence),
|
||||
releaseDocument('scalar', evidence),
|
||||
releaseDocument(`- latestReleasedVersion: ${record.latestReleasedVersion}`, evidence),
|
||||
releaseDocument(`${body}\n---\n${body}`, evidence),
|
||||
]) {
|
||||
expect(() => validateSessionFormatRelease(invalid, record.latestReleasedVersion), invalid).toThrow()
|
||||
}
|
||||
})
|
||||
|
||||
it('rejects missing, duplicate, and extra record fields', () => {
|
||||
const { record, body, links } = sessionFormatReleaseFixture()
|
||||
const { record, body, evidence } = sessionFormatReleaseFixture()
|
||||
for (const invalid of [
|
||||
'{}',
|
||||
`evidenceTag: ${record.evidenceTag}`,
|
||||
@@ -250,45 +250,46 @@ describe('Session format release authority', () => {
|
||||
`${body}\nevidenceTag: ${record.evidenceTag}`,
|
||||
`${body}\nreleased: true`,
|
||||
]) {
|
||||
expect(() => validateSessionFormatRelease(releaseDocument(invalid, links), record.latestReleasedVersion), invalid).toThrow()
|
||||
expect(() => validateSessionFormatRelease(releaseDocument(invalid, evidence), record.latestReleasedVersion), invalid).toThrow()
|
||||
}
|
||||
})
|
||||
|
||||
it('rejects invalid released versions and releases beyond the current writer', () => {
|
||||
const { record, links } = sessionFormatReleaseFixture()
|
||||
const { record, evidence } = sessionFormatReleaseFixture()
|
||||
for (const value of ['-1', '1.5', String(Number.MAX_SAFE_INTEGER + 1), '.inf', '.nan', 'null', 'true', '"0"']) {
|
||||
const source = releaseDocument(`latestReleasedVersion: ${value}\nevidenceTag: ${record.evidenceTag}`, links)
|
||||
const source = releaseDocument(`latestReleasedVersion: ${value}\nevidenceTag: ${record.evidenceTag}`, evidence)
|
||||
expect(() => validateSessionFormatRelease(source, Number.MAX_SAFE_INTEGER), value).toThrow('non-negative safe integer')
|
||||
}
|
||||
const writer = readCurrentSessionFormatVersion(root)
|
||||
const future = releaseDocument(`latestReleasedVersion: ${writer + 1}\nevidenceTag: ${record.evidenceTag}`, links)
|
||||
const future = releaseDocument(`latestReleasedVersion: ${writer + 1}\nevidenceTag: ${record.evidenceTag}`, evidence)
|
||||
expect(() => validateSessionFormatRelease(future, writer)).toThrow('must not exceed the current writer')
|
||||
})
|
||||
|
||||
it('rejects empty, malformed, and URL-injecting evidence tags', () => {
|
||||
const { record, links } = sessionFormatReleaseFixture()
|
||||
const { record, evidence } = sessionFormatReleaseFixture()
|
||||
for (const tag of [
|
||||
null, true, 1, '', ' ', 'dsh-v', record.evidenceTag.replace('dsh-v', 'v'),
|
||||
`${record.evidenceTag}/other`, `${record.evidenceTag}?query`, `${record.evidenceTag}#fragment`,
|
||||
`${record.evidenceTag}%2Fother`, `${record.evidenceTag})`, `${record.evidenceTag}\n`,
|
||||
]) {
|
||||
const source = releaseDocument(`latestReleasedVersion: ${record.latestReleasedVersion}\nevidenceTag: ${JSON.stringify(tag)}`, links)
|
||||
const source = releaseDocument(`latestReleasedVersion: ${record.latestReleasedVersion}\nevidenceTag: ${JSON.stringify(tag)}`, evidence)
|
||||
expect(() => validateSessionFormatRelease(source, record.latestReleasedVersion), String(tag)).toThrow('dsh-v version tag')
|
||||
}
|
||||
})
|
||||
|
||||
it('rejects absent or mismatched release and tagged-source links', () => {
|
||||
const { record, body, links } = sessionFormatReleaseFixture()
|
||||
it('rejects absent or mismatched release tags and tagged writer paths', () => {
|
||||
const { record, body, evidence } = sessionFormatReleaseFixture()
|
||||
for (const invalid of [
|
||||
'',
|
||||
links.replace(`/releases/tag/${record.evidenceTag}`, `/releases/tag/${record.evidenceTag}-other`),
|
||||
links.replace(`/blob/${record.evidenceTag}/`, '/blob/main/'),
|
||||
links.replace('/packages/core/session/src/types.ts', '/packages/core/session/src/other.ts'),
|
||||
links.replaceAll('github.com', 'example.com'),
|
||||
links.replace(`${record.evidenceTag})`, `${record.evidenceTag}?query)`),
|
||||
links.replace('types.ts)', 'types.ts#fragment)'),
|
||||
evidence.replace(record.evidenceTag, `${record.evidenceTag}-other`),
|
||||
evidence.replace(record.evidenceTag, 'main'),
|
||||
evidence.replace('packages/core/session/src/types.ts', 'packages/core/session/src/other.ts'),
|
||||
evidence.replace(record.evidenceTag, `${record.evidenceTag}?query`),
|
||||
evidence.replace('types.ts', 'types.ts#fragment'),
|
||||
evidence.replace('; tagged writer:', ';\n tagged writer:'),
|
||||
]) {
|
||||
expect(() => validateSessionFormatRelease(releaseDocument(body, invalid), record.latestReleasedVersion), invalid).toThrow('Missing matching evidence link')
|
||||
expect(() => validateSessionFormatRelease(releaseDocument(body, invalid), record.latestReleasedVersion), invalid)
|
||||
.toThrow('Missing matching evidence tag and tagged writer path')
|
||||
}
|
||||
})
|
||||
})
|
||||
@@ -349,6 +350,37 @@ describe('dsh-doc skill consolidation', () => {
|
||||
}
|
||||
})
|
||||
|
||||
it('maps persistence transition records to their dedicated document kind', () => {
|
||||
const files = globSync('docs/persistence-changes/*.md', { cwd: root })
|
||||
.filter(file => !/\/README(?:\.zh)?\.md$/u.test(file.replaceAll('\\', '/')))
|
||||
expect(files.length).toBeGreaterThan(0)
|
||||
for (const file of files) {
|
||||
const metadata = readFrontmatter(file)
|
||||
expect(metadata.kind, file).toBe('persistence-change')
|
||||
expect(typeof metadata.description === 'string' && metadata.description.trim().length > 0, file).toBe(true)
|
||||
}
|
||||
})
|
||||
|
||||
it('maps retrospective release comparisons to their dedicated document kind', () => {
|
||||
const files = globSync('docs/persistence-changes/releases/dsh-*.md', { cwd: root })
|
||||
expect(files.length).toBeGreaterThan(0)
|
||||
for (const file of files) {
|
||||
const metadata = readFrontmatter(file)
|
||||
expect(metadata.kind, file).toBe('persistence-release')
|
||||
expect(typeof metadata.description === 'string' && metadata.description.trim().length > 0, file).toBe(true)
|
||||
}
|
||||
})
|
||||
|
||||
it('maps historical Session format references to their dedicated document kind', () => {
|
||||
const files = globSync('docs/persistence-changes/historical-formats/v*.md', { cwd: root })
|
||||
expect(files.length).toBe(readCurrentSessionFormatVersion(root) * 2)
|
||||
for (const file of files) {
|
||||
const metadata = readFrontmatter(file)
|
||||
expect(metadata.kind, file).toBe('persistence-format')
|
||||
expect(typeof metadata.description === 'string' && metadata.description.trim().length > 0, file).toBe(true)
|
||||
}
|
||||
})
|
||||
|
||||
it('keeps the audited library registry accurate: every entry has a plain module entry and no bundle declaration', () => {
|
||||
for (const [dir, reason] of Object.entries(PACKAGE_LIBRARIES)) {
|
||||
expect(reason.trim().length, `${dir}: library justification`).toBeGreaterThan(0)
|
||||
|
||||
@@ -1,19 +1,16 @@
|
||||
/** Experimental packages that publish with the dsh release family without changing names. */
|
||||
export const PUBLIC_EXPERIMENTAL_PACKAGE_DIRECTORIES = [
|
||||
'packages/experimental/agent-team',
|
||||
'packages/experimental/agent-team-profile',
|
||||
'packages/experimental/agent-team-web-profile',
|
||||
'packages/experimental/client-ui-agent-team',
|
||||
'packages/experimental/tool-agent-team',
|
||||
] as const
|
||||
|
||||
const publicExperimentalPackageDirectories = new Set<string>(PUBLIC_EXPERIMENTAL_PACKAGE_DIRECTORIES)
|
||||
/** Experimental packages excluded from public releases and npm baselines. */
|
||||
export const PRIVATE_EXPERIMENTAL_PACKAGE_DIRECTORIES: readonly string[] = []
|
||||
|
||||
/**
|
||||
* Whether an experimental package is an explicit public-release exception.
|
||||
* Whether an experimental package publishes under the default-public policy.
|
||||
* @param directory - repository-relative package directory.
|
||||
* @param privateDirectories - experimental directories excluded from publication.
|
||||
* @returns Whether the package publishes with the dsh family.
|
||||
*/
|
||||
export function isPublicExperimentalPackageDirectory(directory: string): boolean {
|
||||
return publicExperimentalPackageDirectories.has(directory)
|
||||
export function isPublicExperimentalPackageDirectory(
|
||||
directory: string,
|
||||
privateDirectories: readonly string[] = PRIVATE_EXPERIMENTAL_PACKAGE_DIRECTORIES,
|
||||
): boolean {
|
||||
return /^packages\/experimental\/[^/]+$/.test(directory)
|
||||
&& !privateDirectories.includes(directory)
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
/** Exercise the wheel's external Office package from a shipped dsh profile. */
|
||||
import { writeFile } from 'node:fs/promises'
|
||||
import { createConverter } from '@deepseek-ai/libreoffice-kit'
|
||||
|
||||
export const name = 'python-sdk-office-smoke'
|
||||
|
||||
export async function apply(_ctx, config) {
|
||||
const converter = await createConverter({ timeoutMs: 120_000 })
|
||||
try {
|
||||
const result = await converter.render({ inputPath: config.input, outputPath: config.output })
|
||||
await writeFile(config.result, JSON.stringify({ ...result, moduleUrl: import.meta.resolve('@deepseek-ai/libreoffice-kit') }))
|
||||
} finally {
|
||||
await converter.dispose()
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
/** One admitted image and one authored failure for the Python SDK event snapshot. */
|
||||
|
||||
/** Cordis fixture identity. */
|
||||
export const name = 'python-snapshot-image-offload'
|
||||
|
||||
/** Admission and request hooks supplied by the shipped SDK profile. */
|
||||
export const inject = ['attachments', 'agents', 'llm']
|
||||
|
||||
/**
|
||||
* @param {import('@deepseek-ai/cordis').Context} ctx - Scenario-local host context.
|
||||
* @param {{ parentSessionId: string }} config - The one session receiving the authored failure.
|
||||
*/
|
||||
export function apply(ctx, config) {
|
||||
let injected = false
|
||||
let failed = false
|
||||
ctx.on('agent/pre-step', async ({ agent }, next) => {
|
||||
const decision = await next()
|
||||
if (agent.id !== config.parentSessionId || injected || decision.kind === 'reject') return decision
|
||||
const content = await ctx.attachments.admitPromptContent([{
|
||||
type: 'image',
|
||||
mediaType: 'image/png',
|
||||
data: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC',
|
||||
}])
|
||||
injected = true
|
||||
return {
|
||||
...decision,
|
||||
messages: [...decision.messages, { id: 'python-snapshot-image', role: 'user', content, source: { kind: 'plugin', plugin: name } }],
|
||||
}
|
||||
})
|
||||
ctx.on('llm/stream', async function* (options, next) {
|
||||
if (options.sessionId !== config.parentSessionId || options.purpose !== undefined || failed) {
|
||||
yield* next()
|
||||
return
|
||||
}
|
||||
failed = true
|
||||
yield {
|
||||
type: 'finish',
|
||||
reason: { kind: 'error', failure: {
|
||||
code: 'IMAGE_OFFLOAD_REQUIRED', message: 'authored image budget failure', offloadImages: 1,
|
||||
} },
|
||||
}
|
||||
})
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
/** Deterministic tool and denial fixture for the packaged SDK snapshot. */
|
||||
export const name = 'python-snapshot-tool'
|
||||
export const inject = ['tools']
|
||||
|
||||
/** @param {import('@deepseek-ai/cordis').Context} ctx - Scenario-owned tool registration. */
|
||||
export function apply(ctx) {
|
||||
ctx.on('tools/pre-execute', (exec, next) => {
|
||||
if (exec.name !== 'snapshot_double' || exec.arguments.value !== -1) return next()
|
||||
return {
|
||||
kind: 'deny',
|
||||
reason: 'Auto review rejected tool "snapshot_double"; its body was not executed',
|
||||
info: {
|
||||
name: 'AutoReviewDeniedError', code: 'AUTO_REVIEW_DENIED',
|
||||
reason: ' transport raw\r\nreason ',
|
||||
},
|
||||
}
|
||||
})
|
||||
ctx.tools.register({
|
||||
name: 'snapshot_double',
|
||||
description: 'Double a number for executable snapshot verification.',
|
||||
parameters: { type: 'object', properties: { value: { type: 'number' } }, required: ['value'], additionalProperties: false },
|
||||
output: {
|
||||
schema: { type: 'number' },
|
||||
render(_args, value) {
|
||||
return [{ type: 'text', text: String(value) }]
|
||||
}
|
||||
},
|
||||
async execute(args) {
|
||||
return args.value * 2
|
||||
}
|
||||
})
|
||||
}
|
||||
@@ -134,6 +134,14 @@ describe('client slot projection', () => {
|
||||
.toContain('built in')
|
||||
})
|
||||
|
||||
it('names the Factory definition that declares an ordinary child seat', () => {
|
||||
const factory = registration({ key: 'demo.factory', children: ['demo.seat'], factory: true })
|
||||
const [entry] = resolveSlotEntries([declaration()], [factory], OWNER_TYPES, kits)
|
||||
expect(entry?.declaredBy)
|
||||
.toContain("factory 'demo.factory' (client-demo)")
|
||||
expect(entry?.occupants).toEqual([])
|
||||
})
|
||||
|
||||
it('reports an open keyed domain and the keys already taken', () => {
|
||||
const [entry] = resolveSlotEntries(
|
||||
[declaration({ kind: 'keyed' })],
|
||||
@@ -210,5 +218,7 @@ describe('the real workspace surface', () => {
|
||||
const root = entries.find(entry => entry.key === 'root')
|
||||
expect(root?.replaceRisk).toBe('shadows-shipped-ui')
|
||||
expect(root?.occupants.join(' ')).toContain('AppFrame')
|
||||
expect(entries.find(entry => entry.key === 'conversation.session')?.declaredBy)
|
||||
.toContain("factory 'conversation.content' (client-ui-conversation)")
|
||||
})
|
||||
})
|
||||
@@ -208,7 +208,7 @@ export function validateSlotContracts(
|
||||
}
|
||||
}
|
||||
for (const registration of registrations) {
|
||||
if (!byKey.has(registration.key)) {
|
||||
if (registration.factory !== true && !byKey.has(registration.key)) {
|
||||
problems.push(`registration into '${registration.key}' (${registration.source}) targets a slot no SlotMap merge declares; either the scan has a blind spot or the registration is dead.`)
|
||||
}
|
||||
for (const child of registration.children) {
|
||||
@@ -267,7 +267,8 @@ function entryOf(
|
||||
types: ReadonlyMap<string, TypeDeclaration>,
|
||||
kits: ReadonlyMap<string, readonly string[]>,
|
||||
): SlotEntry {
|
||||
const occupants = registrations.filter(registration => registration.key === declaration.key)
|
||||
const occupants = registrations.filter(registration =>
|
||||
registration.factory !== true && registration.key === declaration.key)
|
||||
const cellOccupied = occupants.some(occupant =>
|
||||
declaration.kind === 'single' || occupant.entryKey !== undefined)
|
||||
const doc = docProse(declaration.jsDoc)
|
||||
@@ -287,7 +288,9 @@ function entryOf(
|
||||
slotInject: declaration.injectType ?? '',
|
||||
declaredBy: declaredBy === undefined
|
||||
? 'the runtime itself (built in; always present)'
|
||||
: `an entry in '${declaredBy.key}' (${shortPackage(declaredBy.package)}), so it exists while that entry is mounted`,
|
||||
: declaredBy.factory === true
|
||||
? `factory '${declaredBy.key}' (${shortPackage(declaredBy.package)}), so it exists while that definition is registered`
|
||||
: `an entry in '${declaredBy.key}' (${shortPackage(declaredBy.package)}), so it exists while that entry is mounted`,
|
||||
occupants: occupants.map(occupant => [
|
||||
shortPackage(occupant.package),
|
||||
occupant.component,
|
||||
|
||||
@@ -0,0 +1,139 @@
|
||||
/** Shared schema aliases must retain the catalog's declared-field checks. */
|
||||
|
||||
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { dirname, join } from 'node:path'
|
||||
import { afterEach, describe, expect, it } from 'vitest'
|
||||
import { collectConfigCatalog } from './gen-config-catalog.ts'
|
||||
|
||||
const roots: string[] = []
|
||||
const sharedSchema = `
|
||||
import Schema from '@deepseek-ai/schemastery'
|
||||
export interface LaunchConfig {
|
||||
/** Browser ownership mode. */
|
||||
mode: 'launch'
|
||||
/** Hide the launched browser. */
|
||||
headless: boolean
|
||||
}
|
||||
export interface AttachConfig {
|
||||
/** Browser ownership mode. */
|
||||
mode: 'attach'
|
||||
/** Existing browser address. */
|
||||
endpoint: string
|
||||
}
|
||||
export type BrowserConfig = LaunchConfig | AttachConfig
|
||||
export const Shared = Schema.union([
|
||||
Schema.object({ mode: Schema.const('launch'), headless: Schema.boolean() }),
|
||||
Schema.object({ mode: Schema.const('attach'), endpoint: Schema.string() }),
|
||||
])
|
||||
`
|
||||
|
||||
function fixture(schema = sharedSchema) {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-config-catalog-'))
|
||||
roots.push(root)
|
||||
const write = (path: string, value: string): void => {
|
||||
const file = join(root, path)
|
||||
mkdirSync(dirname(file), { recursive: true })
|
||||
writeFileSync(file, value)
|
||||
}
|
||||
write('tsconfig.json', JSON.stringify({ compilerOptions: {
|
||||
baseUrl: '.', module: 'ESNext', moduleResolution: 'Bundler',
|
||||
paths: { '@test/runtime/config': ['./packages/test/runtime/src/config.ts'] },
|
||||
}, include: ['packages/**/*.ts'] }))
|
||||
write('packages/test/runtime/package.json', JSON.stringify({
|
||||
name: '@test/runtime', exports: { './config': { types: './lib/types/config.d.ts', default: './lib/config.js' } },
|
||||
}))
|
||||
write('packages/test/runtime/src/index.ts', "export { Shared } from './config.ts'\n")
|
||||
write('packages/test/runtime/src/config.ts', schema)
|
||||
write('packages/test/provider/package.json', JSON.stringify({ name: '@test/provider' }))
|
||||
write('packages/test/provider/src/index.ts', `
|
||||
import { Shared as SharedConfig, type BrowserConfig } from '@test/runtime/config'
|
||||
export type Config = BrowserConfig
|
||||
export const Config = SharedConfig
|
||||
export function apply(ctx: unknown, config: Config): void {}
|
||||
`)
|
||||
return { root, write }
|
||||
}
|
||||
|
||||
afterEach(() => {
|
||||
for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
|
||||
})
|
||||
|
||||
describe('shared config schema catalog', () => {
|
||||
it('collects every branch through a renamed named import from a public source subpath', () => {
|
||||
const { root } = fixture()
|
||||
const provider = collectConfigCatalog(root).find(entry => entry.pkg === '@test/provider')
|
||||
expect(new Set(provider?.schemaKeys)).toEqual(new Set(['mode', 'headless', 'endpoint']))
|
||||
expect(provider?.configTypeName).toBe('Config')
|
||||
expect(provider?.pastes?.[0]?.text).toBe('export type Config = BrowserConfig')
|
||||
})
|
||||
|
||||
it('rejects a schema field absent from the shared config type', () => {
|
||||
const { root } = fixture(sharedSchema.replace('headless: Schema.boolean()', 'headless: Schema.boolean(), hidden: Schema.string()'))
|
||||
expect(() => collectConfigCatalog(root)).toThrow("schema validates key 'hidden' but config type 'Config' declares no such member")
|
||||
})
|
||||
|
||||
it('follows a local const alias without treating a completed branch as a cycle', () => {
|
||||
const { root } = fixture(sharedSchema.replace('export const Shared = Schema.union', 'export const Shared = Base\nconst Base = Schema.union'))
|
||||
const provider = collectConfigCatalog(root).find(entry => entry.pkg === '@test/provider')
|
||||
expect(new Set(provider?.schemaKeys)).toEqual(new Set(['mode', 'headless', 'endpoint']))
|
||||
})
|
||||
|
||||
it('rejects type-only imports used as runtime schemas', () => {
|
||||
const { root, write } = fixture()
|
||||
write('packages/test/provider/src/index.ts', `
|
||||
import type { Shared as SharedConfig, BrowserConfig } from '@test/runtime/config'
|
||||
export type Config = BrowserConfig
|
||||
export const Config = SharedConfig
|
||||
export function apply(ctx: unknown, config: Config): void {}
|
||||
`)
|
||||
expect(() => collectConfigCatalog(root)).toThrow("schema alias 'SharedConfig' must name a const or named value import")
|
||||
})
|
||||
|
||||
it('rejects a private subpath even when TypeScript can resolve its source', () => {
|
||||
const { root, write } = fixture()
|
||||
write('packages/test/runtime/package.json', JSON.stringify({ name: '@test/runtime', exports: {} }))
|
||||
expect(() => collectConfigCatalog(root)).toThrow("does not explicitly export './config'")
|
||||
})
|
||||
|
||||
it('rejects a missing source mapping', () => {
|
||||
const { root, write } = fixture()
|
||||
write('tsconfig.json', JSON.stringify({ compilerOptions: { paths: { '@test/runtime/config': ['./missing.ts'] } } }))
|
||||
expect(() => collectConfigCatalog(root)).toThrow('has no workspace source mapping')
|
||||
})
|
||||
|
||||
it('rejects a source mapping into another package', () => {
|
||||
const { root, write } = fixture()
|
||||
write('tsconfig.json', JSON.stringify({ compilerOptions: {
|
||||
baseUrl: '.', paths: { '@test/runtime/config': ['./packages/test/provider/src/index.ts'] },
|
||||
} }))
|
||||
expect(() => collectConfigCatalog(root)).toThrow('must resolve inside packages/test/runtime/src')
|
||||
})
|
||||
|
||||
it('rejects a schema value that the imported module does not export', () => {
|
||||
const { root } = fixture(sharedSchema.replace('export const Shared', 'const Shared'))
|
||||
expect(() => collectConfigCatalog(root)).toThrow("has no exported const 'Shared'")
|
||||
})
|
||||
|
||||
it('rejects recursive const aliases', () => {
|
||||
const { root } = fixture(`${sharedSchema.slice(0, sharedSchema.indexOf('export const Shared'))}
|
||||
export const Shared = Loop
|
||||
const Loop = Shared
|
||||
`)
|
||||
expect(() => collectConfigCatalog(root)).toThrow('cyclic schema alias')
|
||||
})
|
||||
|
||||
it('rejects a dynamic schema factory instead of dropping its keys', () => {
|
||||
const { root } = fixture(`${sharedSchema.slice(0, sharedSchema.indexOf('export const Shared'))}
|
||||
export const Shared = makeSchema()
|
||||
`)
|
||||
expect(() => collectConfigCatalog(root)).toThrow('not a statically walkable schemastery call')
|
||||
})
|
||||
|
||||
it('rejects an unresolved alias within a schema union', () => {
|
||||
const { root } = fixture(`${sharedSchema.slice(0, sharedSchema.indexOf('export const Shared'))}
|
||||
export const Shared = Schema.union([MissingSchema])
|
||||
`)
|
||||
expect(() => collectConfigCatalog(root)).toThrow("schema alias 'MissingSchema' must name a const or named value import")
|
||||
})
|
||||
})
|
||||
+110
-13
@@ -8,7 +8,7 @@
|
||||
*/
|
||||
|
||||
import { globSync, readFileSync, writeFileSync } from 'node:fs'
|
||||
import { dirname, resolve, sep } from 'node:path'
|
||||
import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
|
||||
import ts from 'typescript'
|
||||
import { LINK_MAP } from './gen-cordis-catalog.ts'
|
||||
import { parseJsDoc, pointer, rawJsDoc } from './jsdoc.ts'
|
||||
@@ -87,7 +87,7 @@ interface FileCtx {
|
||||
sf: ts.SourceFile
|
||||
/** Local binding name → `{ imported, specifier }`; default imports record
|
||||
* `imported: 'default'`. */
|
||||
imports: Map<string, { imported: string; specifier: string }>
|
||||
imports: Map<string, { imported: string; specifier: string; typeOnly?: boolean }>
|
||||
}
|
||||
|
||||
/** Throw one aggregate error for every violation the walk collected. */
|
||||
@@ -105,7 +105,7 @@ function loadFile(abs: string, rel: string, cache: Map<string, FileCtx>): FileCt
|
||||
if (cached) return cached
|
||||
const text = readFileSync(abs, 'utf8')
|
||||
const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
|
||||
const imports = new Map<string, { imported: string; specifier: string }>()
|
||||
const imports: FileCtx['imports'] = new Map()
|
||||
for (const stmt of sf.statements) {
|
||||
if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue
|
||||
const specifier = stmt.moduleSpecifier.text
|
||||
@@ -114,7 +114,11 @@ function loadFile(abs: string, rel: string, cache: Map<string, FileCtx>): FileCt
|
||||
if (clause.name) imports.set(clause.name.text, { imported: 'default', specifier })
|
||||
if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
|
||||
for (const el of clause.namedBindings.elements) {
|
||||
imports.set(el.name.text, { imported: (el.propertyName ?? el.name).text, specifier })
|
||||
imports.set(el.name.text, {
|
||||
imported: (el.propertyName ?? el.name).text,
|
||||
specifier,
|
||||
typeOnly: clause.phaseModifier === ts.SyntaxKind.TypeKeyword || el.isTypeOnly,
|
||||
})
|
||||
}
|
||||
}
|
||||
if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings)) {
|
||||
@@ -218,6 +222,69 @@ interface World {
|
||||
cache: Map<string, FileCtx>
|
||||
/** Workspace package name → repo-relative package dir. */
|
||||
pkgDirByName: Map<string, string>
|
||||
/** Exact public export declarations used to verify shared schema imports. */
|
||||
pkgExportsByName: Map<string, unknown>
|
||||
/** Source-plane TypeScript resolution, loaded only for shared schema imports. */
|
||||
compilerOptions?: ts.CompilerOptions
|
||||
}
|
||||
|
||||
/** Resolve an explicitly exported workspace module to its mapped source file. */
|
||||
function loadWorkspaceSource(world: World, from: FileCtx, specifier: string): FileCtx {
|
||||
const pkg = specifier.split('/').slice(0, specifier.startsWith('@') ? 2 : 1).join('/')
|
||||
const dir = world.pkgDirByName.get(pkg)
|
||||
if (dir === undefined) throw new Error(`schema import '${specifier}' is not a workspace package`)
|
||||
const subpath = specifier === pkg ? '.' : `.${specifier.slice(pkg.length)}`
|
||||
const exports = world.pkgExportsByName.get(pkg)
|
||||
if (typeof exports !== 'object' || exports === null || Array.isArray(exports)
|
||||
|| !Object.hasOwn(exports, subpath) || (exports as Record<string, unknown>)[subpath] == null) {
|
||||
throw new Error(`workspace package '${pkg}' does not explicitly export '${subpath}'`)
|
||||
}
|
||||
if (world.compilerOptions === undefined) {
|
||||
const parsed = ts.getParsedCommandLineOfConfigFile(resolve(world.scanRoot, 'tsconfig.json'), {}, {
|
||||
...ts.sys,
|
||||
onUnRecoverableConfigFileDiagnostic(diagnostic) {
|
||||
throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'))
|
||||
},
|
||||
})
|
||||
if (parsed === undefined || parsed.errors.length > 0) {
|
||||
throw new Error(`cannot resolve schema import '${specifier}' through the workspace source tsconfig`)
|
||||
}
|
||||
world.compilerOptions = parsed.options
|
||||
}
|
||||
const resolved = ts.resolveModuleName(specifier, from.abs, world.compilerOptions, ts.sys).resolvedModule
|
||||
if (resolved === undefined) throw new Error(`schema import '${specifier}' has no workspace source mapping`)
|
||||
const sourcePath = relative(resolve(world.scanRoot, dir, 'src'), resolved.resolvedFileName)
|
||||
if (isAbsolute(sourcePath) || sourcePath === '..' || sourcePath.startsWith(`..${sep}`)
|
||||
|| !sourcePath.endsWith('.ts') || sourcePath.endsWith('.d.ts')) {
|
||||
throw new Error(`schema import '${specifier}' must resolve inside ${dir}/src to a TypeScript source file`)
|
||||
}
|
||||
const rel = relative(world.scanRoot, resolved.resolvedFileName).split(sep).join('/')
|
||||
return loadFile(resolved.resolvedFileName, rel, world.cache)
|
||||
}
|
||||
|
||||
/** Find a directly declared const schema, requiring public exports at imported entries. */
|
||||
function schemaConst(ctx: FileCtx, name: string, exported: boolean): ts.Expression | null {
|
||||
for (const statement of ctx.sf.statements) {
|
||||
if (!ts.isVariableStatement(statement) || !(statement.declarationList.flags & ts.NodeFlags.Const)) continue
|
||||
if (exported && !statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue
|
||||
const declaration = statement.declarationList.declarations.find(item => ts.isIdentifier(item.name) && item.name.text === name)
|
||||
if (declaration?.initializer !== undefined) return declaration.initializer
|
||||
}
|
||||
return null
|
||||
}
|
||||
|
||||
/** Follow only const identities and named value imports; never execute schema factories. */
|
||||
function schemaAlias(world: World, ctx: FileCtx, name: string): { ctx: FileCtx; expr: ts.Expression } {
|
||||
const local = schemaConst(ctx, name, false)
|
||||
if (local !== null) return { ctx, expr: local }
|
||||
const imported = ctx.imports.get(name)
|
||||
if (imported === undefined || imported.typeOnly || imported.imported === '*' || imported.imported === 'default') {
|
||||
throw new Error(`schema alias '${name}' must name a const or named value import`)
|
||||
}
|
||||
const target = loadWorkspaceSource(world, ctx, imported.specifier)
|
||||
const expr = schemaConst(target, imported.imported, true)
|
||||
if (expr === null) throw new Error(`schema import '${imported.specifier}' has no exported const '${imported.imported}'`)
|
||||
return { ctx: target, expr }
|
||||
}
|
||||
|
||||
/** How a schema key path fared against the declared config type: definitely
|
||||
@@ -290,7 +357,16 @@ function declForTypeName(world: World, ctx: FileCtx, name: string): { decl: Type
|
||||
return findExportedTypeDecl(world, loadRelative(world, ctx, imp.specifier), imp.imported) ?? 'unknown'
|
||||
}
|
||||
const dir = world.pkgDirByName.get(imp.specifier)
|
||||
if (dir === undefined) return 'unknown'
|
||||
if (dir === undefined) {
|
||||
try {
|
||||
const target = loadWorkspaceSource(world, ctx, imp.specifier)
|
||||
return findExportedTypeDecl(world, target, imp.imported) ?? 'unknown'
|
||||
} catch {
|
||||
// External or unsupported declarations remain unknown for type presence;
|
||||
// a runtime schema alias reports the same resolution failure separately.
|
||||
return 'unknown'
|
||||
}
|
||||
}
|
||||
const entryRel = `${dir}/src/index.ts`
|
||||
let entry: FileCtx
|
||||
try {
|
||||
@@ -413,17 +489,19 @@ function unwrapExpr(expr: ts.Expression): ts.Expression {
|
||||
* Statically walk a schemastery schema expression to its key paths plus the
|
||||
* packages whose schemas an intersect composes. A key path is the top-level
|
||||
* key or a nested path through object/array compositions (`agents[].id`).
|
||||
* Handles the declaration forms the repo uses — `z.object({…})` (possibly behind
|
||||
* chained calls) and `z.intersect([X.Config, …])` — and hard-errors on
|
||||
* Handles object/union calls, chained refinements, named const schema imports
|
||||
* through public workspace source paths, and `z.intersect([X.Config, …])`; errors on
|
||||
* anything else, so a schema the walk cannot see fails the gate instead of
|
||||
* silently thinning it. Nested values that are neither `object` nor `array`
|
||||
* compositions (primitives, unions, dynamic-key dicts) contribute no paths.
|
||||
*/
|
||||
function walkSchemaExpr(
|
||||
world: World,
|
||||
ctx: FileCtx,
|
||||
expr: ts.Expression,
|
||||
where: string,
|
||||
violations: string[],
|
||||
aliases = new Set<string>(),
|
||||
): { keys: string[]; composes: string[] } {
|
||||
const keys: string[] = []
|
||||
const composes: string[] = []
|
||||
@@ -451,6 +529,22 @@ function walkSchemaExpr(
|
||||
}
|
||||
const visit = (e: ts.Expression): void => {
|
||||
const call = unwrapExpr(e)
|
||||
if (ts.isIdentifier(call)) {
|
||||
const identity = `${ctx.abs}#${call.text}`
|
||||
if (aliases.has(identity)) {
|
||||
violations.push(`${where}: cyclic schema alias '${call.text}' in ${ctx.rel}.`)
|
||||
return
|
||||
}
|
||||
try {
|
||||
const target = schemaAlias(world, ctx, call.text)
|
||||
const result = walkSchemaExpr(world, target.ctx, target.expr, where, violations, new Set([...aliases, identity]))
|
||||
keys.push(...result.keys)
|
||||
composes.push(...result.composes)
|
||||
} catch (error) {
|
||||
violations.push(`${where}: ${error instanceof Error ? error.message : String(error)}.`)
|
||||
}
|
||||
return
|
||||
}
|
||||
if (!ts.isCallExpression(call) || !ts.isPropertyAccessExpression(call.expression)) {
|
||||
violations.push(`${where}: schema expression is not a statically walkable schemastery call.`)
|
||||
return
|
||||
@@ -475,7 +569,7 @@ function walkSchemaExpr(
|
||||
const imp = ctx.imports.get(part.expression.text)
|
||||
if (imp && !imp.specifier.startsWith('.')) { composes.push(imp.specifier); continue }
|
||||
}
|
||||
if (ts.isCallExpression(part)) { visit(part); continue }
|
||||
if (ts.isCallExpression(part) || ts.isIdentifier(part)) { visit(part); continue }
|
||||
violations.push(`${where}: intersect element '${part.getText(ctx.sf)}' is neither a workspace plugin's Config nor an inline schema call.`)
|
||||
}
|
||||
return
|
||||
@@ -485,7 +579,8 @@ function walkSchemaExpr(
|
||||
if (method === 'union' && call.arguments[0] && ts.isArrayLiteralExpression(call.arguments[0])) {
|
||||
for (const el of call.arguments[0].elements) {
|
||||
const part = unwrapExpr(el)
|
||||
if (ts.isCallExpression(part)) { visit(part); continue }
|
||||
if (ts.isCallExpression(part) || ts.isIdentifier(part)) { visit(part); continue }
|
||||
violations.push(`${where}: union element '${part.getText(ctx.sf)}' is not a schema call or const alias.`)
|
||||
}
|
||||
return
|
||||
}
|
||||
@@ -582,10 +677,11 @@ export function collectConfigCatalog(scanRoot: string = root): CatalogEntry[] {
|
||||
// Pre-pass: package name → dir, so schema-path lookups can follow
|
||||
// workspace-package imports while individual packages are still being walked.
|
||||
const pkgDirByName = new Map<string, string>()
|
||||
const pkgExportsByName = new Map<string, unknown>()
|
||||
const manifests: { dir: string; pkg: string }[] = []
|
||||
for (const manifestRel of globSync('packages/*/*/package.json', { cwd: scanRoot }).map(path => path.split(sep).join('/')).sort()) {
|
||||
const dir = manifestRel.slice(0, -'/package.json'.length)
|
||||
const manifest = JSON.parse(readFileSync(resolve(scanRoot, manifestRel), 'utf8')) as { name?: string; os?: string[]; cpu?: string[] }
|
||||
const manifest = JSON.parse(readFileSync(resolve(scanRoot, manifestRel), 'utf8')) as { name?: string; os?: string[]; cpu?: string[]; exports?: unknown }
|
||||
const pkg = manifest.name
|
||||
if (!pkg) {
|
||||
violations.push(`${manifestRel} has no "name".`)
|
||||
@@ -597,9 +693,10 @@ export function collectConfigCatalog(scanRoot: string = root): CatalogEntry[] {
|
||||
continue
|
||||
}
|
||||
pkgDirByName.set(pkg, dir)
|
||||
pkgExportsByName.set(pkg, manifest.exports)
|
||||
manifests.push({ dir, pkg })
|
||||
}
|
||||
const world: World = { scanRoot, cache, pkgDirByName }
|
||||
const world: World = { scanRoot, cache, pkgDirByName, pkgExportsByName }
|
||||
|
||||
for (const { dir, pkg } of manifests) {
|
||||
const entryRel = `${dir}/src/index.ts`
|
||||
@@ -719,7 +816,7 @@ export function collectConfigCatalog(scanRoot: string = root): CatalogEntry[] {
|
||||
// Statically walk the runtime schema (when one exists) for the subset check.
|
||||
const schemaExpr = findSchemaExpr(ctx, pluginClass)
|
||||
if (schemaExpr) {
|
||||
const { keys, composes } = walkSchemaExpr(ctx, unwrapExpr(schemaExpr), `${pkg} (${entryRel})`, violations)
|
||||
const { keys, composes } = walkSchemaExpr(world, ctx, unwrapExpr(schemaExpr), `${pkg} (${entryRel})`, violations)
|
||||
entry.schemaKeys = keys
|
||||
entry.schemaComposes = composes
|
||||
} else {
|
||||
@@ -819,7 +916,7 @@ export function render(entries: CatalogEntry[]): string {
|
||||
'',
|
||||
'This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field.',
|
||||
'',
|
||||
'A `Requires:` line lists the service keys the plugin `inject`s: its `cordis.yml` tree must also load providers for those services. Scope is the harness tier (`packages/`); the vendored cordis plugins a config tree may also load (`hmr`, the console logger, …) are pinned upstream source ([vendoring policy](../vendor/README.md)) and not catalogued here.',
|
||||
'A `Requires:` line lists the service keys the plugin `inject`s: its `cordis.yml` tree must also load providers for those services. Scope is the harness tier (`packages/`); the vendored cordis plugins a config tree may also load (the console logger, …) are pinned upstream source ([vendoring policy](../vendor/README.md)) and not catalogued here.',
|
||||
'',
|
||||
]
|
||||
for (const entry of entries.filter(e => e.kind === 'config')) {
|
||||
|
||||
@@ -54,16 +54,23 @@ export { REGION_BEGIN, REGION_END }
|
||||
* errors, so the partition can never silently drift from the service API.
|
||||
*/
|
||||
export const SERVICE_PAGE: Record<string, string> = {
|
||||
pluginManager: 'boot.md',
|
||||
profileContext: 'boot.md',
|
||||
hmr: 'boot.md',
|
||||
mcpResources: 'mcp.md',
|
||||
agentLoop: 'core.md',
|
||||
agentDefaultModel: 'core.md',
|
||||
agentPresets: 'core.md',
|
||||
agents: 'core.md',
|
||||
approval: 'approval.md',
|
||||
officeToPdf: 'office-to-pdf.md',
|
||||
attachments: 'attachment.md',
|
||||
shell: 'shell.md',
|
||||
shellEnv: 'shell.md',
|
||||
clientModules: 'client-modules.md',
|
||||
codeRuntime: 'code-runtime.md',
|
||||
ptcRuntime: 'ptc-runtime.md',
|
||||
browserUse: 'browser-use.md',
|
||||
computerUse: 'computer-use.md',
|
||||
commands: 'commands.md',
|
||||
compaction: 'compaction.md',
|
||||
cordisInspect: 'extensions.md',
|
||||
@@ -74,7 +81,6 @@ export const SERVICE_PAGE: Record<string, string> = {
|
||||
directoryPicker: 'workspace.md',
|
||||
deepseekLlmApiExtensions: 'llm-streaming.md',
|
||||
dynamicCordisRunner: 'extensions.md',
|
||||
e2b: 'subprocess.md',
|
||||
fileUploads: 'attachment.md',
|
||||
fileReferences: 'session-reference.md',
|
||||
fs: 'filesystem.md',
|
||||
@@ -91,6 +97,7 @@ export const SERVICE_PAGE: Record<string, string> = {
|
||||
terminals: 'terminal.md',
|
||||
sandbox: 'sandbox.md',
|
||||
sandboxPolicy: 'sandbox.md',
|
||||
ssh: 'ssh.md',
|
||||
sessionPersistence: 'persistence.md',
|
||||
sessionQuery: 'session-query.md',
|
||||
sessionFileReferences: 'session-reference.md',
|
||||
@@ -126,6 +133,8 @@ export const SERVICE_PAGE: Record<string, string> = {
|
||||
workspaceRegistry: 'workspace.md',
|
||||
workspaceController: 'workspace.md',
|
||||
workspaceFiles: 'workspace.md',
|
||||
workspaceChanges: 'deliverables.md',
|
||||
terminalController: 'workspace.md',
|
||||
directoryPickerController: 'workspace.md',
|
||||
}
|
||||
|
||||
@@ -148,6 +157,7 @@ export const SERVICE_PAGE: Record<string, string> = {
|
||||
* to a model as `cordis_runtime_inspect what:"client"`).
|
||||
*/
|
||||
export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
|
||||
webTerminals: 'client-side terminal view models — packages/api/terminal-controller/README.md owns the API',
|
||||
appReady: 'not a service: launcher-provided successful-startup signal — packages/boot/cmdline/README.md owns the launcher contract',
|
||||
appExit: 'not a service: launcher-provided bounded process-exit callback — packages/boot/cmdline/README.md owns the launcher contract',
|
||||
cmdlineArgs: 'not a service: launcher-provided immutable app argument accessor — packages/boot/cmdline/README.md owns the launcher contract',
|
||||
@@ -155,6 +165,7 @@ export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
|
||||
launcherSessionQueryPath: 'not a service: launcher-provided boot-context value (string | undefined) — packages/session-query/session-query-sqlite/README.md owns this launcher contract',
|
||||
dshHomePath: 'not a service: boot-provided root accessor function (typeof dshHomePath | undefined) for Loader !!js config expressions — packages/boot/app-boot/README.md owns the boot contract',
|
||||
launchEnvironment: 'not a service: launcher-provided root accessor value (LaunchEnvironmentSnapshot | undefined) — packages/util/launch-environment/README.md owns this launcher contract',
|
||||
pluginPackages: 'profile-boot-owned package resolver service used by optional consumers — packages/boot/app-boot/README.md owns this internal API',
|
||||
connection: 'interface-typed (HostConnectionHandle); implementing class HostConnectionService is declared in rpc-host.ts — packages/client/connection/README.md owns the API',
|
||||
fileUpload: 'client-side browser upload service — packages/client/file-upload/README.md owns the API',
|
||||
uiRenderer: 'client-side interface-typed browser service — packages/client/ui-renderer/README.md owns the API',
|
||||
@@ -191,12 +202,15 @@ export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
|
||||
* {@link EVENT_WALK_EXEMPTIONS} names each one with its documentation owner.
|
||||
*/
|
||||
export const EVENT_SCOPE_PAGE: Record<string, string> = {
|
||||
hmr: 'boot.md',
|
||||
'plugin-manager': 'boot.md',
|
||||
'agent': 'core.md',
|
||||
'agent-loop': 'core.md',
|
||||
'agent-preset': 'core.md',
|
||||
'api-session': 'session.md',
|
||||
'approval': 'approval.md',
|
||||
'commands': 'commands.md',
|
||||
'compaction': 'compaction.md',
|
||||
'cordis': 'extensions.md',
|
||||
'authorization': 'credentials.md',
|
||||
'credentials': 'credentials.md',
|
||||
@@ -204,6 +218,7 @@ export const EVENT_SCOPE_PAGE: Record<string, string> = {
|
||||
'fs': 'filesystem.md',
|
||||
'goal': 'goal.md',
|
||||
'llm': 'llm-streaming.md',
|
||||
'permission-presets': 'permission-presets.md',
|
||||
'session': 'session.md',
|
||||
'settings': 'settings.md',
|
||||
'skills': 'skills.md',
|
||||
@@ -246,6 +261,28 @@ export const EVENT_WALK_EXEMPTIONS: Record<string, string> = {
|
||||
* appear on more than one page.
|
||||
*/
|
||||
export const LINK_MAP: Readonly<Record<string, string>> = {
|
||||
WorkspaceChangesSummary: 'deliverables.md',
|
||||
WorkspaceFileDiff: 'deliverables.md',
|
||||
Reload: 'boot.md',
|
||||
PluginInfo: 'boot.md',
|
||||
BundleInfo: 'boot.md',
|
||||
ChangeResult: 'boot.md',
|
||||
InstallBundleOptions: 'boot.md',
|
||||
PluginEntryId: 'boot.md',
|
||||
BundleRowInfo: 'boot.md',
|
||||
PluginInstallCancellation: 'boot.md',
|
||||
PluginInstallRequestId: 'boot.md',
|
||||
PluginSpecInspection: 'boot.md',
|
||||
PluginChange: 'boot.md',
|
||||
PluginInstallLogChunk: 'boot.md',
|
||||
PluginInstallProgress: 'boot.md',
|
||||
BrowserUseProviderName: 'browser-use.md',
|
||||
ComputerUseProviderName: 'computer-use.md',
|
||||
RenderedDocumentBytes: 'office-to-pdf.md',
|
||||
OfficeToPdfRequest: 'office-to-pdf.md',
|
||||
OfficeToPdfResult: 'office-to-pdf.md',
|
||||
OfficeToPdfPriority: 'office-to-pdf.md',
|
||||
OfficeToPdfGeneration: 'office-to-pdf.md',
|
||||
Agent: 'core.md',
|
||||
AgentCancelCause: 'core.md',
|
||||
AgentFactory: 'core.md',
|
||||
@@ -353,6 +390,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
|
||||
SessionSelectModelRequest: 'session.md',
|
||||
SessionSelectModelValue: 'session.md',
|
||||
SessionSummary: 'session.md',
|
||||
SessionMessageProjection: 'session.md',
|
||||
SessionUpdateQueueRequest: 'session.md',
|
||||
SessionUpdateQueueValue: 'session.md',
|
||||
EncodedFileUploadRequest: 'attachment.md',
|
||||
@@ -379,7 +417,8 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
|
||||
SaveFileStreamAttachment: 'attachment.md',
|
||||
ImageAttachmentAccess: 'llm-streaming.md',
|
||||
ImageAttachmentRef: 'attachment.md',
|
||||
ImageRequestPolicy: 'attachment.md',
|
||||
ImageRequestTarget: 'attachment.md',
|
||||
ProjectedDimensions: 'attachment.md',
|
||||
PromptContentPart: 'attachment.md',
|
||||
RequestImageAttachment: 'attachment.md',
|
||||
SaveImageAttachment: 'attachment.md',
|
||||
@@ -397,9 +436,12 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
|
||||
SubprocessOutputReader: 'subprocess.md',
|
||||
SubprocessSpawnSpec: 'subprocess.md',
|
||||
SubprocessTerminalHandle: 'subprocess.md',
|
||||
SubprocessTerminalEnvironment: 'subprocess.md',
|
||||
SubprocessTerminalSpawnSpec: 'subprocess.md',
|
||||
CodeRunRequest: 'code-runtime.md',
|
||||
CodeRunResult: 'code-runtime.md',
|
||||
PtcRunRequest: 'ptc-runtime.md',
|
||||
PtcRunSpec: 'ptc-runtime.md',
|
||||
PtcRunSandbox: 'ptc-runtime.md',
|
||||
PtcRunResult: 'ptc-runtime.md',
|
||||
CompactionResult: 'compaction.md',
|
||||
CompactionTrigger: 'compaction.md',
|
||||
PruneResult: 'compaction.md',
|
||||
@@ -469,6 +511,8 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
|
||||
TerminalSpawnRequest: 'terminal.md',
|
||||
TerminalSpawnResult: 'terminal.md',
|
||||
SandboxPolicyRequest: 'sandbox.md',
|
||||
SshConnection: 'ssh.md',
|
||||
SshStreamEndpoint: 'ssh.md',
|
||||
ScopeKey: 'scope.md',
|
||||
Scoped: 'scope.md',
|
||||
EpochHeader: 'session.md',
|
||||
@@ -635,6 +679,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
|
||||
WorkflowRun: 'workflow.md',
|
||||
VerifiedWebhookDelivery: 'webhook.md',
|
||||
WebhookRule: 'webhook.md',
|
||||
PermissionCatalog: 'permission-presets.md',
|
||||
PresetOption: 'permission-presets.md',
|
||||
PresetSpec: 'permission-presets.md',
|
||||
InvariantInstaller: 'invariants.md',
|
||||
@@ -659,6 +704,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
|
||||
WorkspaceInsertSessionBeforeRequest: 'workspace.md',
|
||||
WorkspaceOrderValue: 'workspace.md',
|
||||
WorkspaceRenameRequest: 'workspace.md',
|
||||
WorkspaceUnarchiveSessionRequest: 'workspace.md',
|
||||
WorkspaceValue: 'workspace.md',
|
||||
ClientArtifactBaseline: 'client-modules.md',
|
||||
WebBootGraph: 'client-modules.md',
|
||||
@@ -685,11 +731,13 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
|
||||
|
||||
/** TypeScript lib and pinned framework types with no repository-owned data page. */
|
||||
export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
|
||||
'Plugin',
|
||||
'AbortSignal',
|
||||
'AsyncIterable',
|
||||
'Context',
|
||||
'Error',
|
||||
'EntryTree',
|
||||
'EntryOptions',
|
||||
'Exclude',
|
||||
'Extract',
|
||||
'Map',
|
||||
@@ -703,11 +751,17 @@ export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
|
||||
'ReadonlyMap',
|
||||
'Request',
|
||||
'Response',
|
||||
'ReturnType',
|
||||
'Uint8Array',
|
||||
])
|
||||
|
||||
/** Project types deliberately documented outside the subsystems catalog. */
|
||||
export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
|
||||
Profile: 'resolved profile layers are owned by packages/boot/app-boot/README.md',
|
||||
PatchOptions: 'Include patch entries are owned by vendor/include (vendored upstream)',
|
||||
McpResourceProvider: 'scoped resource provider is owned by packages/mcp/mcp-resources/README.md',
|
||||
'z.ZodType': 'Zod response validation API is owned by https://zod.dev/packages/zod',
|
||||
Socket: 'Node.js byte stream API is owned by https://nodejs.org/api/net.html#class-netsocket',
|
||||
z: 'schemastery schema constructor is owned by vendor/schemastery (vendored upstream)',
|
||||
BeginCommandRequest: 'event-local request contract is owned by packages/client/ui-input-trigger/src/types.ts',
|
||||
InsertReferenceRequest: 'event-local request contract is owned by packages/client/ui-input-trigger/src/types.ts',
|
||||
@@ -773,11 +827,9 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
|
||||
InvariantRegistration: 'service-local lifecycle handle is owned by packages/runtime-diagnostics/invariants/README.md',
|
||||
JsonValue: 'JSON value union is owned by packages/core/session/src/json.ts',
|
||||
KnobState: 'projection unit state fields are owned by packages/interaction/permission-presets/README.md',
|
||||
PermissionSelect: 'permissions projection payload is owned by packages/interaction/permission-presets/src/types.ts',
|
||||
PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
|
||||
RequestRunId: 'dynamic-package payload contract is owned by packages/extensions/cordis-host-runner/src/types.ts',
|
||||
RpcReceipt: 'carrier-layer receipt is owned by packages/client/connection/src/rpc.ts',
|
||||
Sandbox: 'external E2B SDK handle is owned by packages/e2b/e2b/README.md',
|
||||
SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
|
||||
SubagentRunEndInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
|
||||
SubagentRunInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
|
||||
@@ -793,6 +845,14 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
|
||||
WorkspaceFileRange: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
|
||||
WorkspaceFileStat: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
|
||||
WorkspaceFileText: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
|
||||
TerminalShell: 'Browser terminal shell profiles are owned by packages/api/terminal-controller/README.md',
|
||||
TerminalEnvironment: 'Browser terminal environment fields are owned by packages/api/terminal-controller/README.md',
|
||||
WebTerminalInfo: 'Browser terminal metadata is owned by packages/api/terminal-controller/README.md',
|
||||
TerminalCreateRequest: 'Browser terminal allocation fields are owned by packages/api/terminal-controller/README.md',
|
||||
TerminalAttachmentId: 'Browser terminal input ownership is owned by packages/api/terminal-controller/README.md',
|
||||
TerminalFrame: 'Browser terminal stream frames are owned by packages/api/terminal-controller/README.md',
|
||||
TerminalRetentionFrame: 'Browser terminal window holds are owned by packages/api/terminal-controller/README.md',
|
||||
WebTerminalId: 'Browser terminal identity is owned by packages/api/terminal-controller/README.md',
|
||||
}
|
||||
|
||||
/** Repository data policy consumed by the Cordis catalog projector. */
|
||||
@@ -843,8 +903,6 @@ export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
|
||||
{ name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:338' },
|
||||
{ name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
|
||||
{ name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
|
||||
{ name: 'hmr/change', summary: 'A watched source file changed on disk.', source: 'vendor/hmr/src/index.ts:20' },
|
||||
{ name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:21' },
|
||||
{ name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
|
||||
{ name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:24' },
|
||||
{ name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:25' },
|
||||
@@ -861,7 +919,6 @@ export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
|
||||
{ name: 'ctx.root / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.', source: 'vendor/cordis/src/context.ts:16' },
|
||||
{ name: 'ctx.timer (+ interval / timeout / throttle / debounce)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the four supported helpers are mixed onto ctx directly (declared via Pick).', source: 'vendor/timer/src/index.ts:4' },
|
||||
{ name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).', source: 'vendor/loader/src/index.ts:30' },
|
||||
{ name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).', source: 'vendor/hmr/src/index.ts:15' },
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
@@ -12,14 +12,14 @@ const CLIENT_OUT = 'packages/extensions/cordis-client-runner/src/client/api-cata
|
||||
const CLIENT_SERVICES: Readonly<Record<string, readonly string[]>> = {
|
||||
layout: ['selectPanel', 'beginNavigation', 'toggleSidebar', 'openRightbar', 'closeRightbar'],
|
||||
locale: ['getLocale', 'getSnapshot', 'subscribe', 'setLocale', 'addLanguage', 'register', 'bind'],
|
||||
sessions: ['open', 'openSubagent', 'setSubagentCatalogOpen', 'refreshSubagents', 'search', 'fork', 'scope', 'binding'],
|
||||
slots: ['register', 'inject'],
|
||||
sessions: ['retain', 'using', 'retainInfo', 'setSubagentCatalogOpen', 'refreshSubagents', 'search', 'fork', 'scope', 'binding'],
|
||||
slots: ['register', 'registerFactory', 'inject'],
|
||||
theme: ['getTheme', 'setTheme', 'setFontSize', 'register', 'overrideTokens'],
|
||||
uiWorkspace: [
|
||||
'openSession', 'openWorkspace', 'forkSession', 'connectWorkspace', 'startSession', 'archiveSession', 'pickDirectory', 'listDirectory',
|
||||
'createDirectory',
|
||||
'openSession', 'openWorkspace', 'forkSession', 'connectWorkspace', 'startSession', 'archiveSession', 'unarchiveSession',
|
||||
'pickDirectory', 'listDirectory', 'createDirectory',
|
||||
],
|
||||
workspaces: ['create', 'rename', 'delete', 'insertSessionBefore', 'archiveSession'],
|
||||
workspaces: ['create', 'rename', 'delete', 'insertSessionBefore', 'archiveSession', 'unarchiveSession'],
|
||||
}
|
||||
|
||||
const CLIENT_EVENTS = new Set([
|
||||
@@ -66,7 +66,10 @@ function clientModel(model: CordisCatalogModel): CordisCatalogModel {
|
||||
}
|
||||
|
||||
function main(): void {
|
||||
const { projector, model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY, 'client')
|
||||
const { projector, model } = projectCordisCatalog(root, {
|
||||
...CORDIS_CATALOG_POLICY,
|
||||
runtimeDeclarationMaxChars: 4_096,
|
||||
}, 'client')
|
||||
const destination = resolve(root, CLIENT_OUT)
|
||||
const source = projector.renderRuntimeApi(clientModel(model))
|
||||
.replace('Generated by scripts/gen-cordis-api.ts', 'Generated by scripts/gen-cordis-inspect-catalog.ts')
|
||||
|
||||
@@ -0,0 +1,188 @@
|
||||
/** Production dependency selection and offline catalog freshness regressions. */
|
||||
|
||||
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { join, resolve } from 'node:path'
|
||||
import { afterEach, describe, expect, it } from 'vitest'
|
||||
import { runCommandWithTimeout } from './benchmark-npm-resolution.ts'
|
||||
import {
|
||||
collectDependencies, computeDependencyCatalog, createNpmResolutionEnvironment,
|
||||
deduplicateDependencies, isDependencyCatalogCurrent,
|
||||
} from './gen-dependency-catalog.ts'
|
||||
|
||||
const roots: string[] = []
|
||||
afterEach(() => {
|
||||
for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true, maxRetries: 3 })
|
||||
})
|
||||
|
||||
function lockfile() {
|
||||
const lock = {
|
||||
lockfileVersion: 3,
|
||||
packages: {
|
||||
'': { dependencies: { '@deepseek-ai/dsh': 'latest' } },
|
||||
'node_modules/@deepseek-ai/dsh': {
|
||||
version: '1.0.0', dependencies: { library: '^2.0.0', alias: 'npm:[email protected]' },
|
||||
optionalDependencies: { unavailable: '1.0.0' },
|
||||
},
|
||||
'node_modules/library': { version: '1.0.0' },
|
||||
'node_modules/@deepseek-ai/dsh/node_modules/library': { version: '2.0.0', dependencies: { plugin: '*' } },
|
||||
'node_modules/alias': { name: 'original', version: '1.0.0' },
|
||||
'node_modules/plugin': {
|
||||
version: '1.0.0', dependencies: { library: '^1.0.0' }, peerDependencies: { peer: '*' },
|
||||
optionalDependencies: { 'native-linux': '*', 'native-helper': '*' },
|
||||
},
|
||||
'node_modules/peer': { version: '3.0.0', peer: true },
|
||||
'node_modules/native-linux': { version: '1.0.0', optional: true, os: ['linux'], cpu: ['arm64'], libc: ['glibc'] },
|
||||
'node_modules/native-helper': { version: '1.0.0', optional: true, devOptional: true },
|
||||
'node_modules/test-only': { version: '1.0.0', dev: true },
|
||||
},
|
||||
}
|
||||
for (const [location, entry] of Object.entries(lock.packages)) {
|
||||
if (location !== '') Object.assign(entry, { resolved: `https://registry.npmjs.org/${location}/package.tgz` })
|
||||
}
|
||||
return lock
|
||||
}
|
||||
|
||||
function fixture(): string {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-dependency-catalog-test-'))
|
||||
roots.push(root)
|
||||
mkdirSync(join(root, 'scripts/dependency-catalog'), { recursive: true })
|
||||
writeFileSync(join(root, 'scripts/dependency-catalog/package-lock.json'), JSON.stringify(lockfile()))
|
||||
writeFileSync(join(root, 'scripts/dependency-catalog/resolution.json'), JSON.stringify({
|
||||
capturedAt: '2026-09-12T00:00:00.000Z', npm: '11.17.0', node: '24.19.0',
|
||||
platform: 'darwin', arch: 'arm64', registry: 'https://registry.npmjs.org/', installStrategy: 'hoisted',
|
||||
}))
|
||||
return root
|
||||
}
|
||||
|
||||
describe('published npm dependency catalog', () => {
|
||||
it('retains nested versions, aliases, peers, and optional candidates while excluding development-only packages', () => {
|
||||
const { version, rows } = collectDependencies(lockfile())
|
||||
expect(version).toBe('1.0.0')
|
||||
expect(rows).toHaveLength(7)
|
||||
expect(rows.filter(row => row.direct).map(row => [row.name, row.version])).toEqual([
|
||||
['library', '2.0.0'], ['original', '1.0.0'],
|
||||
])
|
||||
expect(rows.find(row => row.name === 'peer')).toMatchObject({ peer: true, optional: false })
|
||||
expect(rows.find(row => row.name === 'native-linux')).toMatchObject({
|
||||
optional: true, os: ['linux'], cpu: ['arm64'], libc: ['glibc'],
|
||||
})
|
||||
expect(rows.find(row => row.name === 'native-helper')).toMatchObject({ optional: true })
|
||||
expect(rows.map(row => row.name)).not.toContain('test-only')
|
||||
expect(rows.map(row => row.name)).not.toContain('unavailable')
|
||||
})
|
||||
|
||||
it('does not silently produce an incomplete catalog from invalid or unrelated resolutions', () => {
|
||||
expect(() => collectDependencies({ lockfileVersion: 2 })).toThrow('lockfileVersion 3')
|
||||
expect(() => collectDependencies({ lockfileVersion: 3, packages: {} })).toThrow('consumer must be an object')
|
||||
const input = lockfile()
|
||||
input.packages[''].dependencies['@deepseek-ai/dsh'] = 'next'
|
||||
expect(() => collectDependencies(input)).toThrow('must request only @deepseek-ai/dsh@latest')
|
||||
const missing = lockfile()
|
||||
Reflect.deleteProperty(missing.packages, 'node_modules/alias')
|
||||
expect(() => collectDependencies(missing)).toThrow('missing direct dependency alias')
|
||||
const linked = lockfile()
|
||||
Object.assign(linked.packages['node_modules/library'], { link: true })
|
||||
expect(() => collectDependencies(linked)).toThrow('is a local link')
|
||||
})
|
||||
|
||||
it('sorts packages independently of lockfile object order and keeps duplicate installation locations', () => {
|
||||
const input = lockfile()
|
||||
const reordered = { ...input, packages: Object.fromEntries(Object.entries(input.packages).reverse()) }
|
||||
expect(collectDependencies(reordered)).toEqual(collectDependencies(input))
|
||||
Object.assign(input.packages, {
|
||||
'node_modules/plugin/node_modules/library': {
|
||||
version: '1.0.0', resolved: 'https://registry.npmjs.org/library/-/library-1.0.0.tgz',
|
||||
},
|
||||
})
|
||||
expect(collectDependencies(input).rows.filter(row => row.name === 'library' && row.version === '1.0.0')).toHaveLength(2)
|
||||
})
|
||||
|
||||
it('deduplicates identical versions without losing installation locations or optional flags', () => {
|
||||
const input = lockfile()
|
||||
Object.assign(input.packages, {
|
||||
'node_modules/plugin/node_modules/library': {
|
||||
version: '1.0.0', optional: true, resolved: 'https://registry.npmjs.org/library/-/library-1.0.0.tgz',
|
||||
},
|
||||
})
|
||||
const rows = collectDependencies(input).rows
|
||||
const packages = deduplicateDependencies(rows)
|
||||
const repeated = packages.filter(entry => entry.name === 'library' && entry.version === '1.0.0')
|
||||
expect(repeated).toHaveLength(1)
|
||||
expect(repeated[0]?.installations).toEqual([
|
||||
{ location: 'node_modules/library', direct: false, optional: false, peer: false },
|
||||
{ location: 'node_modules/plugin/node_modules/library', direct: false, optional: true, peer: false },
|
||||
])
|
||||
expect(packages.filter(entry => entry.name === 'library').map(entry => entry.version)).toEqual(['1.0.0', '2.0.0'])
|
||||
expect(deduplicateDependencies([...rows].reverse())).toEqual(packages)
|
||||
expect(packages.flatMap(entry => entry.installations)).toHaveLength(rows.length)
|
||||
})
|
||||
|
||||
it('rejects missing, edited, or stale JSON without rewriting it', () => {
|
||||
const root = fixture()
|
||||
const output = computeDependencyCatalog(root)
|
||||
const path = join(root, 'docs/dependency-catalog.json')
|
||||
expect(isDependencyCatalogCurrent(root)).toBe(false)
|
||||
mkdirSync(join(root, 'docs'))
|
||||
writeFileSync(path, output)
|
||||
expect(isDependencyCatalogCurrent(root)).toBe(true)
|
||||
writeFileSync(path, `${output}stale\n`)
|
||||
expect(isDependencyCatalogCurrent(root)).toBe(false)
|
||||
expect(readFileSync(path, 'utf8')).toBe(`${output}stale\n`)
|
||||
writeFileSync(path, output)
|
||||
const updated = lockfile()
|
||||
updated.packages['node_modules/peer'].version = '3.1.0'
|
||||
writeFileSync(join(root, 'scripts/dependency-catalog/package-lock.json'), JSON.stringify(updated))
|
||||
expect(isDependencyCatalogCurrent(root)).toBe(false)
|
||||
})
|
||||
|
||||
it('rejects non-public package sources and incorrect registry metadata', () => {
|
||||
const input = lockfile()
|
||||
Object.assign(input.packages['node_modules/library'], { resolved: 'https://private.invalid/library.tgz' })
|
||||
expect(() => collectDependencies(input)).toThrow('not resolved from the public npm registry')
|
||||
const root = fixture()
|
||||
const metadataPath = join(root, 'scripts/dependency-catalog/resolution.json')
|
||||
writeFileSync(metadataPath, JSON.stringify({ registry: 'https://private.invalid/', installStrategy: 'hoisted' }))
|
||||
expect(() => computeDependencyCatalog(root)).toThrow('expected the public npm registry and hoisted install strategy')
|
||||
})
|
||||
|
||||
it('isolates scoped registries, resolver settings, and caches from user, global, and environment configuration', async () => {
|
||||
const root = fixture()
|
||||
const userConfig = join(root, 'user.npmrc')
|
||||
const globalConfig = join(root, 'global.npmrc')
|
||||
writeFileSync(userConfig, '@deepseek-ai:registry=https://user-override.invalid/\nstrict-peer-deps=true\n')
|
||||
writeFileSync(globalConfig, '@other:registry=https://global-override.invalid/\nprefer-dedupe=true\n')
|
||||
const inherited: NodeJS.ProcessEnv = {
|
||||
...Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.toLowerCase().startsWith('npm_config_'))),
|
||||
npm_config_userconfig: userConfig,
|
||||
NPM_CONFIG_GLOBALCONFIG: globalConfig,
|
||||
NPM_CONFIG_INSTALL_STRATEGY: 'nested',
|
||||
NPM_CONFIG_OFFLINE: 'true',
|
||||
NPM_CONFIG_CACHE: join(root, 'inherited-cache'),
|
||||
NPM_CONFIG_USER_AGENT: 'inherited-agent',
|
||||
}
|
||||
const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm'
|
||||
const args = ['config', 'list', '--json', '--registry=https://registry.npmjs.org/', '--loglevel=error']
|
||||
const before = await runCommandWithTimeout(npm, args, { cwd: root, env: inherited, timeoutMs: 30_000 })
|
||||
expect(before).toMatchObject({ status: 0, signal: null, timedOut: false })
|
||||
expect(JSON.parse(before.output)).toMatchObject({
|
||||
'@deepseek-ai:registry': 'https://user-override.invalid/', 'install-strategy': 'nested',
|
||||
})
|
||||
const isolated = createNpmResolutionEnvironment(root, inherited)
|
||||
const after = await runCommandWithTimeout(npm, args, { cwd: root, env: isolated, timeoutMs: 30_000 })
|
||||
expect(after).toMatchObject({ status: 0, signal: null, timedOut: false })
|
||||
const settings = JSON.parse(after.output) as Record<string, unknown>
|
||||
expect(settings).toMatchObject({
|
||||
registry: 'https://registry.npmjs.org/', '@deepseek-ai:registry': 'https://registry.npmjs.org/',
|
||||
'install-strategy': 'hoisted', 'strict-peer-deps': false, 'prefer-dedupe': false, offline: false,
|
||||
cache: join(root, '.npm-cache'), userconfig: join(root, '.npmrc-user'), globalconfig: join(root, '.npmrc-global'),
|
||||
})
|
||||
expect(settings['@other:registry']).toBeUndefined()
|
||||
expect(isolated['NPM_CONFIG_USER_AGENT']).toBeUndefined()
|
||||
expect(inherited['npm_config_userconfig']).toBe(userConfig)
|
||||
})
|
||||
|
||||
it('keeps the checked-in JSON synchronized with its recorded npm resolution', () => {
|
||||
expect(isDependencyCatalogCurrent(resolve(import.meta.dirname, '..'))).toBe(true)
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,304 @@
|
||||
/** Generate the README npx dependency catalog from a recorded public npm resolution. */
|
||||
|
||||
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
|
||||
import { mkdtemp, rm } from 'node:fs/promises'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { dirname, join, resolve } from 'node:path'
|
||||
import { parseArgs } from 'node:util'
|
||||
import { runCommandWithTimeout } from './benchmark-npm-resolution.ts'
|
||||
|
||||
const ROOT = resolve(import.meta.dirname, '..')
|
||||
const PACKAGE = '@deepseek-ai/dsh'
|
||||
const ENTRY = `node_modules/${PACKAGE}`
|
||||
const REGISTRY = 'https://registry.npmjs.org/'
|
||||
const LOCK = 'scripts/dependency-catalog/package-lock.json'
|
||||
const METADATA = 'scripts/dependency-catalog/resolution.json'
|
||||
const OUT = 'docs/dependency-catalog.json'
|
||||
|
||||
/** npm lockfile fields used to describe an installed package or optional candidate. */
|
||||
interface PackageEntry {
|
||||
name?: string
|
||||
version: string
|
||||
dependencies?: Record<string, string>
|
||||
optionalDependencies?: Record<string, string>
|
||||
dev?: boolean
|
||||
optional?: boolean
|
||||
peer?: boolean
|
||||
os?: string[]
|
||||
cpu?: string[]
|
||||
libc?: string[]
|
||||
}
|
||||
|
||||
/** One package location in npm's resolved tree; duplicate versions retain their locations. */
|
||||
export interface DependencyRow {
|
||||
readonly location: string
|
||||
readonly name: string
|
||||
readonly version: string
|
||||
readonly direct: boolean
|
||||
readonly optional: boolean
|
||||
readonly peer: boolean
|
||||
readonly os?: readonly string[]
|
||||
readonly cpu?: readonly string[]
|
||||
readonly libc?: readonly string[]
|
||||
}
|
||||
|
||||
interface ResolutionMetadata {
|
||||
capturedAt: string
|
||||
npm: string
|
||||
node: string
|
||||
platform: string
|
||||
arch: string
|
||||
registry: string
|
||||
installStrategy: string
|
||||
}
|
||||
|
||||
function record(value: unknown, label: string): Record<string, unknown> {
|
||||
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
|
||||
throw new Error(`dependency-catalog: ${label} must be an object`)
|
||||
}
|
||||
return value as Record<string, unknown>
|
||||
}
|
||||
|
||||
function string(value: unknown, label: string): string {
|
||||
if (typeof value !== 'string' || value.length === 0 || /[\r\n]/.test(value)) {
|
||||
throw new Error(`dependency-catalog: ${label} must be a nonempty single-line value`)
|
||||
}
|
||||
return value
|
||||
}
|
||||
|
||||
function parseEntry(value: unknown, location: string): PackageEntry {
|
||||
const raw = record(value, location)
|
||||
const entry: PackageEntry = { version: string(raw['version'], `${location} version`) }
|
||||
if (raw['name'] !== undefined) entry.name = string(raw['name'], `${location} name`)
|
||||
if (raw['link'] === true) throw new Error(`dependency-catalog: ${location} is a local link`)
|
||||
const source = new URL(string(raw['resolved'], `${location} resolved`))
|
||||
if (source.origin !== new URL(REGISTRY).origin || source.username !== '' || source.password !== '') {
|
||||
throw new Error(`dependency-catalog: ${location} is not resolved from the public npm registry`)
|
||||
}
|
||||
for (const key of ['dev', 'optional', 'peer'] as const) {
|
||||
if (raw[key] === undefined) continue
|
||||
if (typeof raw[key] !== 'boolean') throw new Error(`dependency-catalog: ${location} ${key} must be boolean`)
|
||||
entry[key] = raw[key]
|
||||
}
|
||||
for (const key of ['dependencies', 'optionalDependencies'] as const) {
|
||||
if (raw[key] === undefined) continue
|
||||
entry[key] = Object.fromEntries(Object.entries(record(raw[key], `${location} ${key}`))
|
||||
.map(([name, spec]) => [string(name, 'dependency name'), string(spec, `${location} ${name}`)]))
|
||||
}
|
||||
for (const key of ['os', 'cpu', 'libc'] as const) {
|
||||
const values = raw[key]
|
||||
if (values === undefined) continue
|
||||
if (!Array.isArray(values)) throw new Error(`dependency-catalog: ${location} ${key} must be an array`)
|
||||
entry[key] = values.map(value => string(value, `${location} ${key}`))
|
||||
}
|
||||
return entry
|
||||
}
|
||||
|
||||
/**
|
||||
* Read npm's resolved production tree without substituting workspace or development dependencies.
|
||||
* @param input - Parsed npm lockfile v3 from a consumer with only dsh as its dependency.
|
||||
* @returns The CLI version and sorted package locations, excluding the synthetic consumer and CLI itself.
|
||||
*/
|
||||
export function collectDependencies(input: unknown): { version: string; rows: DependencyRow[] } {
|
||||
const lock = record(input, 'lockfile')
|
||||
if (lock['lockfileVersion'] !== 3) throw new Error('dependency-catalog: expected npm lockfileVersion 3')
|
||||
const packages = record(lock['packages'], 'packages')
|
||||
const consumer = record(packages[''], 'consumer')
|
||||
const requested = record(consumer['dependencies'], 'consumer dependencies')
|
||||
if (Object.keys(requested).length !== 1 || requested[PACKAGE] !== 'latest') {
|
||||
throw new Error(`dependency-catalog: consumer must request only ${PACKAGE}@latest`)
|
||||
}
|
||||
const entries = new Map(Object.entries(packages).filter(([location]) => location !== '')
|
||||
.map(([location, entry]) => [location, parseEntry(entry, location)]))
|
||||
const cli = entries.get(ENTRY)
|
||||
if (cli === undefined || cli.dev) throw new Error(`dependency-catalog: missing production ${PACKAGE}`)
|
||||
const direct = new Set<string>()
|
||||
for (const name of Object.keys({ ...cli.dependencies, ...cli.optionalDependencies })) {
|
||||
const location = [`${ENTRY}/node_modules/${name}`, `node_modules/${name}`]
|
||||
.find(candidate => entries.has(candidate))
|
||||
if (location === undefined) {
|
||||
if (cli.optionalDependencies?.[name] !== undefined) continue
|
||||
throw new Error(`dependency-catalog: missing direct dependency ${name}`)
|
||||
}
|
||||
direct.add(location)
|
||||
}
|
||||
const rows: DependencyRow[] = []
|
||||
for (const [location, entry] of entries) {
|
||||
if (location === ENTRY || entry.dev) continue
|
||||
const name = location.split('node_modules/').at(-1)
|
||||
if (name === undefined || !/^(@[^/]+\/)?[^/]+$/.test(name)) {
|
||||
throw new Error(`dependency-catalog: invalid npm package location ${location}`)
|
||||
}
|
||||
rows.push({
|
||||
location,
|
||||
name: entry.name ?? name,
|
||||
version: entry.version,
|
||||
direct: direct.has(location),
|
||||
optional: entry.optional === true,
|
||||
peer: entry.peer === true,
|
||||
...(entry.os === undefined ? {} : { os: entry.os }),
|
||||
...(entry.cpu === undefined ? {} : { cpu: entry.cpu }),
|
||||
...(entry.libc === undefined ? {} : { libc: entry.libc }),
|
||||
})
|
||||
}
|
||||
if (rows.length === 0) throw new Error('dependency-catalog: empty dependency tree')
|
||||
rows.sort((a, b) => a.name.localeCompare(b.name, 'en')
|
||||
|| a.version.localeCompare(b.version, 'en') || a.location.localeCompare(b.location, 'en'))
|
||||
return { version: cli.version, rows }
|
||||
}
|
||||
|
||||
function readMetadata(scanRoot: string): ResolutionMetadata {
|
||||
const value = record(JSON.parse(readFileSync(resolve(scanRoot, METADATA), 'utf8')), 'resolution metadata')
|
||||
if (value['registry'] !== REGISTRY || value['installStrategy'] !== 'hoisted') {
|
||||
throw new Error('dependency-catalog: expected the public npm registry and hoisted install strategy')
|
||||
}
|
||||
return {
|
||||
capturedAt: string(value['capturedAt'], 'capturedAt'),
|
||||
npm: string(value['npm'], 'npm'),
|
||||
node: string(value['node'], 'node'),
|
||||
platform: string(value['platform'], 'platform'),
|
||||
arch: string(value['arch'], 'arch'),
|
||||
registry: value['registry'],
|
||||
installStrategy: value['installStrategy'],
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Combine identical package versions while retaining each installation's npm flags and platform constraints.
|
||||
* @param rows - Resolved package locations, excluding the consumer and CLI.
|
||||
* @returns One sorted record per package name and version, with sorted installation locations.
|
||||
*/
|
||||
export function deduplicateDependencies(rows: readonly DependencyRow[]): {
|
||||
name: string
|
||||
version: string
|
||||
installations: Omit<DependencyRow, 'name' | 'version'>[]
|
||||
}[] {
|
||||
const packages = new Map<string, {
|
||||
name: string
|
||||
version: string
|
||||
installations: Omit<DependencyRow, 'name' | 'version'>[]
|
||||
}>()
|
||||
for (const { name, version, ...installation } of rows) {
|
||||
const key = JSON.stringify([name, version])
|
||||
const dependency = packages.get(key) ?? { name, version, installations: [] }
|
||||
dependency.installations.push(installation)
|
||||
packages.set(key, dependency)
|
||||
}
|
||||
const sorted = [...packages.values()].sort((a, b) => a.name.localeCompare(b.name, 'en')
|
||||
|| a.version.localeCompare(b.version, 'en'))
|
||||
for (const dependency of sorted) {
|
||||
dependency.installations.sort((a, b) => a.location.localeCompare(b.location, 'en'))
|
||||
}
|
||||
return sorted
|
||||
}
|
||||
|
||||
function renderCatalog(lock: unknown, metadata: ResolutionMetadata): string {
|
||||
const { version, rows } = collectDependencies(lock)
|
||||
return `${JSON.stringify({
|
||||
package: PACKAGE,
|
||||
version,
|
||||
requested: `${PACKAGE}@latest`,
|
||||
resolution: metadata,
|
||||
dependencies: deduplicateDependencies(rows),
|
||||
}, null, 2)}\n`
|
||||
}
|
||||
|
||||
/**
|
||||
* Compute the JSON catalog without network access or writes.
|
||||
* @param scanRoot - Repository root containing the recorded npm resolution.
|
||||
* @returns Deterministic JSON with one trailing newline.
|
||||
*/
|
||||
export function computeDependencyCatalog(scanRoot: string = ROOT): string {
|
||||
return renderCatalog(JSON.parse(readFileSync(resolve(scanRoot, LOCK), 'utf8')), readMetadata(scanRoot))
|
||||
}
|
||||
|
||||
/**
|
||||
* Check the generated JSON against the recorded npm resolution.
|
||||
* @param scanRoot - Repository root containing the resolution and catalog.
|
||||
* @returns Whether the catalog exists and matches its inputs byte for byte.
|
||||
*/
|
||||
export function isDependencyCatalogCurrent(scanRoot: string = ROOT): boolean {
|
||||
return existsSync(resolve(scanRoot, OUT))
|
||||
&& readFileSync(resolve(scanRoot, OUT), 'utf8') === computeDependencyCatalog(scanRoot)
|
||||
}
|
||||
|
||||
/**
|
||||
* Isolate npm configuration and cache from the maintainer and invoking package manager.
|
||||
* @param temporary - Private consumer directory owned by the caller.
|
||||
* @param inherited - Environment whose non-npm settings remain available to the child.
|
||||
* @returns Complete child environment, including isolated user/global configuration and cache paths.
|
||||
*/
|
||||
export function createNpmResolutionEnvironment(
|
||||
temporary: string,
|
||||
inherited: NodeJS.ProcessEnv = process.env,
|
||||
): NodeJS.ProcessEnv {
|
||||
const userConfig = join(temporary, '.npmrc-user')
|
||||
const globalConfig = join(temporary, '.npmrc-global')
|
||||
writeFileSync(userConfig, '')
|
||||
writeFileSync(globalConfig, '')
|
||||
writeFileSync(join(temporary, '.npmrc'), `registry=${REGISTRY}\n@deepseek-ai:registry=${REGISTRY}\ninstall-strategy=hoisted\n`)
|
||||
return {
|
||||
...Object.fromEntries(Object.entries(inherited).filter(([name]) => !name.toLowerCase().startsWith('npm_config_'))),
|
||||
npm_config_userconfig: userConfig,
|
||||
npm_config_globalconfig: globalConfig,
|
||||
npm_config_cache: join(temporary, '.npm-cache'),
|
||||
npm_config_update_notifier: 'false',
|
||||
}
|
||||
}
|
||||
|
||||
async function runNpm(args: readonly string[], cwd: string, env: NodeJS.ProcessEnv): Promise<string> {
|
||||
const result = await runCommandWithTimeout(process.platform === 'win32' ? 'npm.cmd' : 'npm', args, {
|
||||
cwd, env, timeoutMs: 300_000,
|
||||
})
|
||||
if (result.timedOut || result.status !== 0) {
|
||||
throw new Error(`dependency-catalog: npm failed (timedOut=${result.timedOut}, status=${String(result.status)}): ${result.output}`)
|
||||
}
|
||||
return result.output.trim()
|
||||
}
|
||||
|
||||
async function refreshResolution(): Promise<void> {
|
||||
const temporary = await mkdtemp(join(tmpdir(), 'dsh-dependency-catalog-'))
|
||||
try {
|
||||
writeFileSync(join(temporary, 'package.json'), `${JSON.stringify({
|
||||
name: 'dsh-dependency-catalog', version: '0.0.0', private: true, dependencies: { [PACKAGE]: 'latest' },
|
||||
}, null, 2)}\n`)
|
||||
const environment = createNpmResolutionEnvironment(temporary)
|
||||
const npm = await runNpm(['--version'], temporary, environment)
|
||||
await runNpm([
|
||||
'install', '--package-lock-only', '--lockfile-version=3', '--ignore-scripts', '--no-audit', '--no-fund',
|
||||
'--include=prod', '--include=optional', '--include=peer', '--legacy-peer-deps=false',
|
||||
'--install-strategy=hoisted', '--loglevel=error', `--registry=${REGISTRY}`,
|
||||
], temporary, environment)
|
||||
const lock = readFileSync(join(temporary, 'package-lock.json'), 'utf8')
|
||||
const metadata: ResolutionMetadata = {
|
||||
capturedAt: new Date().toISOString(), npm, node: process.versions.node,
|
||||
platform: process.platform, arch: process.arch, registry: REGISTRY, installStrategy: 'hoisted',
|
||||
}
|
||||
const catalog = renderCatalog(JSON.parse(lock), metadata)
|
||||
mkdirSync(resolve(ROOT, dirname(LOCK)), { recursive: true })
|
||||
writeFileSync(resolve(ROOT, LOCK), lock)
|
||||
writeFileSync(resolve(ROOT, METADATA), `${JSON.stringify(metadata, null, 2)}\n`)
|
||||
writeFileSync(resolve(ROOT, OUT), catalog)
|
||||
} finally {
|
||||
await rm(temporary, { recursive: true, force: true, maxRetries: 3 })
|
||||
}
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const { values } = parseArgs({ options: { check: { type: 'boolean' }, refresh: { type: 'boolean' } } })
|
||||
if (values.check && values.refresh) throw new Error('dependency-catalog: --check cannot refresh the registry record')
|
||||
if (values.refresh) {
|
||||
await refreshResolution()
|
||||
} else if (values.check) {
|
||||
if (!isDependencyCatalogCurrent()) {
|
||||
throw new Error(`dependency-catalog: stale ${OUT}; run pnpm run gen-dependency-catalog`)
|
||||
}
|
||||
console.log('dependency-catalog: JSON matches the recorded npm resolution')
|
||||
return
|
||||
} else {
|
||||
writeFileSync(resolve(ROOT, OUT), computeDependencyCatalog())
|
||||
}
|
||||
console.log(`dependency-catalog: generated ${OUT}`)
|
||||
}
|
||||
|
||||
if (process.argv[1] !== undefined && import.meta.filename === resolve(process.argv[1])) await main()
|
||||
+88
-17
@@ -63,6 +63,7 @@ type EventReceiverKind = 'context' | 'agent-dispatch' | 'events-service'
|
||||
const GROUP_ORDER = [
|
||||
'util',
|
||||
'attachment',
|
||||
'document',
|
||||
'llm',
|
||||
'core',
|
||||
'typert',
|
||||
@@ -72,7 +73,7 @@ const GROUP_ORDER = [
|
||||
'bash',
|
||||
'pty',
|
||||
'sandbox',
|
||||
'e2b',
|
||||
'ssh',
|
||||
'fs',
|
||||
'skill',
|
||||
'compact',
|
||||
@@ -98,6 +99,62 @@ const GROUP_ORDER = [
|
||||
]
|
||||
|
||||
const SERVICE_ROLES: ServiceRole[] = [
|
||||
{
|
||||
key: 'hmr',
|
||||
pkg: 'hmr',
|
||||
title: 'Serialized module and configuration reloads',
|
||||
mode: 'core',
|
||||
consumers: ['app-boot'],
|
||||
note: 'Owns module and exact configuration watchers; application mutations share its queue and automatic reloads await the application file lock.',
|
||||
},
|
||||
{
|
||||
key: 'pluginManager',
|
||||
pkg: 'plugin-manager',
|
||||
title: 'Current-profile plugin and bundle management',
|
||||
mode: 'core',
|
||||
consumers: ['plugin-manager', 'ui-settings-plugin-inventory'],
|
||||
note: 'Shares profile package operations with the CLI and reports persisted and running state to Web and agent callers.',
|
||||
},
|
||||
{
|
||||
key: 'profileContext',
|
||||
pkg: 'app-boot',
|
||||
title: 'Launcher-owned profile data',
|
||||
mode: 'core',
|
||||
consumers: ['plugin-manager'],
|
||||
note: 'The dsh launcher supplies data-only profile locations and composition inputs; reload scheduling belongs to dsh-hmr.',
|
||||
},
|
||||
{
|
||||
key: 'mcpResources',
|
||||
pkg: 'mcp-resources',
|
||||
title: 'Scoped MCP resource access',
|
||||
mode: 'seam',
|
||||
implementations: ['mcp-client'],
|
||||
consumers: ['mcp-resources'],
|
||||
note: 'Connection-owned providers serve shared resource tools in the calling agent scope.',
|
||||
},
|
||||
{
|
||||
key: 'browserUse',
|
||||
pkg: 'browser-use',
|
||||
title: 'Browser-use provider registration',
|
||||
mode: 'seam',
|
||||
implementations: ['experimental-browser-use-playwright-mcp', 'experimental-browser-use-chrome-devtools-mcp', 'experimental-browser-use-stagehand-native'],
|
||||
consumers: ['experimental-browser-use-playwright-mcp', 'experimental-browser-use-chrome-devtools-mcp', 'experimental-browser-use-stagehand-native'],
|
||||
note: 'One provider-owned name per service instance. Providers own their tools and browser resources per live Session; the shared service has no browser operation API.',
|
||||
},
|
||||
{
|
||||
key: 'computerUse',
|
||||
pkg: 'computer-use',
|
||||
title: 'Computer-use provider registration',
|
||||
mode: 'seam',
|
||||
implementations: ['experimental-computer-use-cua-driver-mcp', 'experimental-computer-use-cua-driver-native'],
|
||||
consumers: ['experimental-computer-use-cua-driver-mcp', 'experimental-computer-use-cua-driver-native'],
|
||||
note: 'One provider-owned name per service instance. Each provider also owns its model tools; the service has no common action API, runtime selection, or Session workflow lock.',
|
||||
},
|
||||
{
|
||||
key: 'officeToPdf', pkg: 'office-to-pdf', title: 'Office to PDF conversion',
|
||||
mode: 'core', consumers: ['client-ui-sidebar-documentpreview'],
|
||||
note: 'Authorized Office bytes are converted on the Host using the declared native target engine, or Node WASM when no native target is declared.',
|
||||
},
|
||||
{
|
||||
key: 'attachments',
|
||||
pkg: 'attachment',
|
||||
@@ -206,6 +263,20 @@ const SERVICE_ROLES: ServiceRole[] = [
|
||||
mode: 'core',
|
||||
note: 'Serves stat, paged text, byte windows, directory listings, and the change feed for files inside a Session\'s workspace root, confined by lstat, containment, and a stat re-check.',
|
||||
},
|
||||
{
|
||||
key: 'workspaceChanges',
|
||||
pkg: 'workspace-changes',
|
||||
title: 'Host per-turn changed-file summaries',
|
||||
mode: 'core',
|
||||
note: 'Serves the summary each workspace/changes event announced and each listed file\'s turn-start and turn-end comparison, by Session and event sequence, until that Session is disposed; the log carries only the turn.',
|
||||
},
|
||||
{
|
||||
key: 'terminalController',
|
||||
pkg: 'api-terminal-controller',
|
||||
title: 'Session interactive terminal Remote controller',
|
||||
mode: 'core',
|
||||
note: 'Owns user terminal processes, default shell resolution and bounded screen recovery through the subprocess provider and typed Remote transport.',
|
||||
},
|
||||
{
|
||||
key: 'workspaceController',
|
||||
pkg: 'api-workspace-controller',
|
||||
@@ -434,7 +505,7 @@ const SERVICE_ROLES: ServiceRole[] = [
|
||||
pkg: 'skill',
|
||||
title: 'Skill provider registry',
|
||||
mode: 'seam',
|
||||
implementations: ['skill-badge', 'skill-filesystem'],
|
||||
implementations: ['skill-badge', 'skill-filesystem', 'skill-office'],
|
||||
consumers: ['tool-skill'],
|
||||
note: 'Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies.',
|
||||
},
|
||||
@@ -470,19 +541,19 @@ const SERVICE_ROLES: ServiceRole[] = [
|
||||
note: 'Folds revisioned objective state from the session log and keeps live continuation activation process-local.',
|
||||
},
|
||||
{
|
||||
key: 'e2b',
|
||||
pkg: 'e2b',
|
||||
title: 'E2B sandbox lifecycle owner',
|
||||
key: 'ssh',
|
||||
pkg: 'ssh',
|
||||
title: 'POSIX SSH connection owner',
|
||||
mode: 'core',
|
||||
consumers: ['fs-e2b', 'subprocess-e2b'],
|
||||
note: 'Owns one shared E2B SDK handle, remote working directory, and final sandbox disposition so both fundamental E2B providers inhabit the same Linux runtime.',
|
||||
consumers: ['fs-ssh', 'subprocess-ssh', 'sandbox-ssh'],
|
||||
note: 'Owns one authenticated OpenSSH connection, installed helper identity, independent program streams and disconnect cleanup for the paired remote providers.',
|
||||
},
|
||||
{
|
||||
key: 'subprocess',
|
||||
pkg: 'subprocess',
|
||||
title: 'Subprocess seam',
|
||||
mode: 'seam',
|
||||
implementations: ['subprocess-local', 'subprocess-e2b'],
|
||||
implementations: ['subprocess-local', 'subprocess-ssh'],
|
||||
consumers: ['bash-local', 'bash-sandbox', 'terminal-bash', 'lsp-stdio', 'subagent-acp', 'subagent-codex', 'subagent-claude-code'],
|
||||
note: 'The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation.',
|
||||
},
|
||||
@@ -517,7 +588,7 @@ const SERVICE_ROLES: ServiceRole[] = [
|
||||
pkg: 'sandbox',
|
||||
title: 'Process-sandbox seam',
|
||||
mode: 'seam',
|
||||
implementations: ['sandbox-local'],
|
||||
implementations: ['sandbox-local', 'sandbox-ssh'],
|
||||
consumers: ['bash-sandbox', 'terminal-bash'],
|
||||
note: 'Consumers hand over the exact argv they are about to spawn; same-world backends wrap it under a per-call policy and report enforcement.',
|
||||
},
|
||||
@@ -548,20 +619,20 @@ const SERVICE_ROLES: ServiceRole[] = [
|
||||
note: 'User-facing preset table (`workspace-write`/`danger-full-access`) bundling the sandbox-mode and approval-policy knobs; a switch writes one `permission/preset` event through to both knob events.',
|
||||
},
|
||||
{
|
||||
key: 'codeRuntime',
|
||||
pkg: 'code-runtime',
|
||||
title: 'Code-execution seam',
|
||||
key: 'ptcRuntime',
|
||||
pkg: 'ptc-runtime',
|
||||
title: 'PTC execution seam',
|
||||
mode: 'seam',
|
||||
implementations: ['code-runtime-worker-thread', 'experimental-code-runtime-python'],
|
||||
consumers: ['tools'],
|
||||
note: 'Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for PTC mode).',
|
||||
implementations: ['ptc-runtime-node', 'experimental-ptc-runtime-python'],
|
||||
consumers: ['tools', 'workflow-ptc'],
|
||||
note: 'Runs programs against host-provided async bindings; tools owns PTC presentation and workflow-ptc owns workflow orchestration.',
|
||||
},
|
||||
{
|
||||
key: 'fs',
|
||||
pkg: 'fs',
|
||||
title: 'Filesystem provider seam',
|
||||
mode: 'seam',
|
||||
implementations: ['fs-local', 'fs-sandbox', 'fs-e2b'],
|
||||
implementations: ['fs-local', 'fs-sandbox', 'fs-ssh'],
|
||||
consumers: ['tool-fs'],
|
||||
companions: ['fs-observation-policy'],
|
||||
note: 'tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-observation-policy contributes observed-state checks through the fs/* event gate.',
|
||||
@@ -656,7 +727,7 @@ const SERVICE_ROLES: ServiceRole[] = [
|
||||
pkg: 'workflow',
|
||||
title: 'Workflow script engine',
|
||||
mode: 'seam',
|
||||
implementations: ['workflow-worker-thread'],
|
||||
implementations: ['workflow-ptc'],
|
||||
consumers: ['tool-workflow', 'tool-ralph'],
|
||||
note: 'One engine per context, as in bash, with no named-provider registry; the general workflow and fixed Ralph consumers start runs whose agent() calls fan out through ctx.subagents.',
|
||||
},
|
||||
|
||||
@@ -6,36 +6,31 @@
|
||||
* surface-union member must resolve to one. `--check` verifies the artifact.
|
||||
*/
|
||||
|
||||
import { globSync, readFileSync, writeFileSync } from 'node:fs'
|
||||
import { resolve, sep } from 'node:path'
|
||||
import ts from 'typescript'
|
||||
import { parseJsDoc, pointer, rawJsDoc, reportViolations } from './jsdoc.ts'
|
||||
import { readFileSync, writeFileSync } from 'node:fs'
|
||||
import { resolve } from 'node:path'
|
||||
import { githubSlug } from './verify-md-links.ts'
|
||||
import {
|
||||
annotateSurface, collectEventEnvelopeTypes, collectLogEvents, collectSurfaceEventTypes,
|
||||
type AnnotatedLogEventEntry, type EventEnvelopeTypeEntry,
|
||||
} from './persistence-catalog-source.ts'
|
||||
import { extractPersistenceSchema } from './persistence-schema.ts'
|
||||
import { persistenceCatalogText, type PersistenceCatalogLocale } from './persistence-catalog-text.ts'
|
||||
import { renderPersistencePair, type PersistenceArtifact } from './persistence-artifacts.ts'
|
||||
|
||||
export { annotateSurface, collectEventEnvelopeTypes, collectLogEvents, collectSurfaceEventTypes } from './persistence-catalog-source.ts'
|
||||
export type { AnnotatedLogEventEntry, EventEnvelopeTypeEntry, LogEventEntry } from './persistence-catalog-source.ts'
|
||||
import type { PersistenceSchemaInventory } from './persistence-schema-model.ts'
|
||||
import { renderPersistenceSchemaDefinitions, renderPersistenceSchemaIndex } from './render-persistence-schema.ts'
|
||||
|
||||
const root = resolve(import.meta.dirname, '..')
|
||||
const OUT = 'docs/persistence-catalog.md'
|
||||
const OUT_RUNTIME_TYPES = 'packages/core/session/src/known-event-types.ts'
|
||||
const OUT_SCHEMA = 'docs/persistence-schema.json'
|
||||
|
||||
/** The fenced-block info string for generated declaration blocks (skipped by
|
||||
* doc-typecheck, since their imported types are not standalone-compilable). */
|
||||
const FENCE = 'ts persistence-catalog'
|
||||
|
||||
/** The package that owns the durable event vocabulary. */
|
||||
const SESSION_PACKAGE = '@deepseek-ai/dsh-session'
|
||||
|
||||
/** The type-only module that plugin declaration merges augment. */
|
||||
const SESSION_TYPES_MODULE = '@deepseek-ai/dsh-session/types'
|
||||
|
||||
/** Event-envelope declarations rendered before the per-event vocabulary. */
|
||||
const EVENT_ENVELOPE_TYPE_NAMES = [
|
||||
'SessionEventType',
|
||||
'SurfaceEventType',
|
||||
'SurfaceOp',
|
||||
'SessionEvent',
|
||||
] as const
|
||||
|
||||
type EventEnvelopeTypeName = typeof EVENT_ENVELOPE_TYPE_NAMES[number]
|
||||
|
||||
/** Documentation target, relative to `docs/`, for linked payload types. */
|
||||
const LINK_MAP: Record<string, string> = {
|
||||
ToolCallId: 'subsystems/core.md',
|
||||
@@ -45,11 +40,13 @@ const LINK_MAP: Record<string, string> = {
|
||||
StreamChunk: 'subsystems/llm-streaming.md',
|
||||
TokenUsage: 'subsystems/llm-streaming.md',
|
||||
TodoItem: 'subsystems/todo.md',
|
||||
WorkspaceChangesSummary: 'subsystems/deliverables.md',
|
||||
PresentedFile: 'subsystems/deliverables.md',
|
||||
TurnTrigger: 'subsystems/session.md',
|
||||
TurnEndReason: 'subsystems/session.md',
|
||||
SessionTitleEventData: 'subsystems/session-title.md',
|
||||
SessionTitleLlmRequestEventData: 'subsystems/session-title.md',
|
||||
SessionTitleModelProvenance: 'subsystems/session-title.md',
|
||||
SessionTitleModelIdentity: 'subsystems/session-title.md',
|
||||
SessionTitleProviderId: 'subsystems/session-title.md',
|
||||
SessionTitleSource: 'subsystems/session-title.md',
|
||||
TeamId: 'subsystems/agent-team.md',
|
||||
@@ -59,335 +56,72 @@ const LINK_MAP: Record<string, string> = {
|
||||
TeamTaskSnapshot: 'subsystems/agent-team.md',
|
||||
}
|
||||
|
||||
/** One log event, extracted from a `SessionEventMap` declaration. */
|
||||
export interface LogEventEntry {
|
||||
/** Scoped name, e.g. `turn/start`. */
|
||||
name: string
|
||||
/** The scope prefix, e.g. `turn` (everything before the first `/`). */
|
||||
scope: string
|
||||
/** Payload type text (the member's type annotation, whitespace-collapsed). */
|
||||
payload: string
|
||||
/** Source member declaration and complete JSDoc, dedented from its container. */
|
||||
declaration: string
|
||||
/** Description prose (the member's JSDoc), one line per paragraph. */
|
||||
doc: string
|
||||
/** Source pointer `packages/…/file.ts:line` of the declaration. */
|
||||
source: string
|
||||
}
|
||||
|
||||
/** A {@link LogEventEntry} plus its surface-eligibility badge. */
|
||||
export interface AnnotatedLogEventEntry extends LogEventEntry {
|
||||
/** Whether the type is a `SurfaceEventType` member (may carry `surfaceOp`). */
|
||||
surface: boolean
|
||||
}
|
||||
|
||||
/** One owning event-envelope declaration pasted into the generated catalog. */
|
||||
export interface EventEnvelopeTypeEntry {
|
||||
/** Exported declaration name. */
|
||||
name: EventEnvelopeTypeName
|
||||
/** Verbatim type declaration, including its complete leading JSDoc. */
|
||||
declaration: string
|
||||
/** Source pointer `packages/…/file.ts:line` of the declaration. */
|
||||
source: string
|
||||
}
|
||||
|
||||
const printer = ts.createPrinter({ removeComments: true })
|
||||
|
||||
/**
|
||||
* Render a member type on one line through the TypeScript printer, which adds
|
||||
* semicolon separators. Drop its trailing semicolon before `}` to match the
|
||||
* repository's inline-literal style.
|
||||
*/
|
||||
function payloadText(type: ts.TypeNode, sf: ts.SourceFile): string {
|
||||
return printer.printNode(ts.EmitHint.Unspecified, type, sf)
|
||||
.replace(/\s+/g, ' ')
|
||||
.replace(/;\s*\}/g, ' }')
|
||||
.trim()
|
||||
}
|
||||
|
||||
/**
|
||||
* Copy a declaration from its leading JSDoc through its closing token while
|
||||
* removing only the indentation imposed by its containing interface/module.
|
||||
*/
|
||||
function declarationText(text: string, sf: ts.SourceFile, node: ts.Node): string {
|
||||
const raw = rawJsDoc(text, node)
|
||||
const nodeStart = node.getStart(sf)
|
||||
const start = raw ? text.lastIndexOf(raw, nodeStart) : nodeStart
|
||||
const { line } = sf.getLineAndCharacterOfPosition(start)
|
||||
const lineStart = sf.getPositionOfLineAndCharacter(line, 0)
|
||||
const indent = text.slice(lineStart, start)
|
||||
return text.slice(lineStart, node.end)
|
||||
.split('\n')
|
||||
.map(lineText => lineText.startsWith(indent) ? lineText.slice(indent.length) : lineText)
|
||||
.join('\n')
|
||||
.trimEnd()
|
||||
}
|
||||
|
||||
/**
|
||||
* Every `interface SessionEventMap` declaration in a source file: the owning
|
||||
* top-level declaration (in `@deepseek-ai/dsh-session`) and any declaration
|
||||
* merge inside a `declare module '@deepseek-ai/dsh-session/types'` block. Both forms
|
||||
* declare members of the SAME merged interface, so both are catalogued
|
||||
* uniformly. `topLevel` distinguishes the owning form so the caller can verify
|
||||
* it actually lives in the owning package — an unrelated local interface that
|
||||
* happens to share the name must not be catalogued as the on-disk vocabulary.
|
||||
*/
|
||||
function sessionEventMapDecls(sf: ts.SourceFile): { decl: ts.InterfaceDeclaration; topLevel: boolean }[] {
|
||||
const decls: { decl: ts.InterfaceDeclaration; topLevel: boolean }[] = []
|
||||
for (const stmt of sf.statements) {
|
||||
if (ts.isInterfaceDeclaration(stmt) && stmt.name.text === 'SessionEventMap') decls.push({ decl: stmt, topLevel: true })
|
||||
if (ts.isModuleDeclaration(stmt) && ts.isStringLiteral(stmt.name) && stmt.name.text === SESSION_TYPES_MODULE
|
||||
&& stmt.body && ts.isModuleBlock(stmt.body)) {
|
||||
for (const inner of stmt.body.statements) {
|
||||
if (ts.isInterfaceDeclaration(inner) && inner.name.text === 'SessionEventMap') decls.push({ decl: inner, topLevel: false })
|
||||
}
|
||||
}
|
||||
}
|
||||
return decls
|
||||
}
|
||||
|
||||
/**
|
||||
* The npm package name owning a `packages/<group>/<pkg>/…` source file, read
|
||||
* from that package's manifest — or null when the manifest is missing or
|
||||
* unparseable (the caller treats null as "ownership unverifiable").
|
||||
*/
|
||||
function packageNameFor(rel: string, scanRoot: string): string | null {
|
||||
const dir = rel.split('/').slice(0, 3).join('/')
|
||||
try {
|
||||
const manifest = JSON.parse(readFileSync(resolve(scanRoot, dir, 'package.json'), 'utf8')) as { name?: string }
|
||||
return typeof manifest.name === 'string' ? manifest.name : null
|
||||
} catch {
|
||||
// Missing or malformed package.json — every real workspace package has one,
|
||||
// so this only arises in stripped-down fixture trees; either way ownership
|
||||
// cannot be verified and the caller reports the declaration.
|
||||
return null
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Collect every `SessionEventMap` merge, rejecting inherited, non-literal,
|
||||
* untyped, undocumented, duplicate, or incorrectly owned members in one report.
|
||||
*/
|
||||
export function collectLogEvents(scanRoot: string = root): LogEventEntry[] {
|
||||
const entries: LogEventEntry[] = []
|
||||
const violations: string[] = []
|
||||
const seen = new Map<string, string>()
|
||||
let owningDecl: string | null = null
|
||||
for (const rel of globSync('packages/*/*/src/**/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
|
||||
const abs = resolve(scanRoot, rel)
|
||||
const text = readFileSync(abs, 'utf8')
|
||||
if (!text.includes('SessionEventMap')) continue
|
||||
const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
|
||||
for (const { decl, topLevel } of sessionEventMapDecls(sf)) {
|
||||
const declSrc = pointer(rel, sf, decl)
|
||||
if (topLevel) {
|
||||
// The top-level form has one home: the single exported declaration in
|
||||
// the owning package. Same-named interfaces elsewhere are different
|
||||
// types and must not enter the on-disk catalog.
|
||||
const pkg = packageNameFor(rel, scanRoot)
|
||||
if (pkg !== SESSION_PACKAGE) {
|
||||
violations.push(`top-level interface SessionEventMap (${declSrc}) is outside ${SESSION_PACKAGE} (package ${pkg ?? 'unknown'}). Rename the interface, or contribute events via declare module '${SESSION_TYPES_MODULE}'.`)
|
||||
continue
|
||||
}
|
||||
const exported = decl.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false
|
||||
if (!exported) {
|
||||
violations.push(`top-level interface SessionEventMap (${declSrc}) is not exported; the owning vocabulary is the single exported declaration — rename a local helper interface.`)
|
||||
continue
|
||||
}
|
||||
if (owningDecl) {
|
||||
violations.push(`top-level interface SessionEventMap (${declSrc}) is already declared at ${owningDecl}; the owning vocabulary has exactly one home.`)
|
||||
continue
|
||||
}
|
||||
owningDecl = declSrc
|
||||
}
|
||||
if (decl.heritageClauses?.length) {
|
||||
violations.push(`SessionEventMap declaration (${declSrc}) uses extends; inherited keys would join keyof SessionEventMap without a catalog row — declare event members directly.`)
|
||||
}
|
||||
for (const member of decl.members) {
|
||||
const src = pointer(rel, sf, member)
|
||||
if (!ts.isPropertySignature(member) || !member.type) {
|
||||
// A method-form or type-less member still joins `keyof SessionEventMap`,
|
||||
// so skipping it silently would be exactly the undocumented-event hole
|
||||
// this catalog exists to close.
|
||||
const label = (member as { name?: ts.Node }).name?.getText(sf) ?? member.getText(sf).replace(/\s+/g, ' ')
|
||||
violations.push(`SessionEventMap member ${label} (${src}) is not a property signature with an explicit payload type; declare every log event as 'scope/name': <payload>.`)
|
||||
continue
|
||||
}
|
||||
if (!ts.isStringLiteral(member.name)) {
|
||||
violations.push(`log event at ${src} has a non-literal name; the catalog needs string-literal event names.`)
|
||||
continue
|
||||
}
|
||||
const name = member.name.text
|
||||
const where = `log event '${name}' (${src})`
|
||||
const prior = seen.get(name)
|
||||
if (prior) {
|
||||
violations.push(`${where} is already declared at ${prior}; an event type has exactly one declaration.`)
|
||||
continue
|
||||
}
|
||||
seen.set(name, src)
|
||||
const payload = payloadText(member.type, sf)
|
||||
const { doc, hasMode } = parseJsDoc(rawJsDoc(text, member))
|
||||
if (hasMode) {
|
||||
violations.push(`${where} carries an @mode tag, but a log event has no dispatch mode (it is not a cordis bus event — it rides the 'session/event' emit). Remove the tag.`)
|
||||
}
|
||||
if (!doc) {
|
||||
violations.push(`${where} has no description prose. Say what the event records and what its payload means — the JSDoc becomes the catalog entry.`)
|
||||
}
|
||||
const declaration = declarationText(text, sf, member)
|
||||
entries.push({ name, scope: name.split('/')[0] ?? name, payload, declaration, doc, source: src })
|
||||
}
|
||||
}
|
||||
}
|
||||
reportViolations('gen-persistence-catalog', violations)
|
||||
return entries
|
||||
}
|
||||
|
||||
/**
|
||||
* Collect the exported declarations that compose the persisted event envelope,
|
||||
* preserving their source JSDoc and declaration text.
|
||||
*/
|
||||
export function collectEventEnvelopeTypes(scanRoot: string = root): EventEnvelopeTypeEntry[] {
|
||||
const found = new Map<EventEnvelopeTypeName, EventEnvelopeTypeEntry>()
|
||||
const violations: string[] = []
|
||||
const wanted = new Set<string>(EVENT_ENVELOPE_TYPE_NAMES)
|
||||
for (const rel of globSync('packages/*/*/src/**/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
|
||||
const abs = resolve(scanRoot, rel)
|
||||
const text = readFileSync(abs, 'utf8')
|
||||
if (!EVENT_ENVELOPE_TYPE_NAMES.some(name => text.includes(name))) continue
|
||||
if (packageNameFor(rel, scanRoot) !== SESSION_PACKAGE) continue
|
||||
const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
|
||||
for (const stmt of sf.statements) {
|
||||
if (!ts.isTypeAliasDeclaration(stmt) || !wanted.has(stmt.name.text)) continue
|
||||
const name = stmt.name.text as EventEnvelopeTypeName
|
||||
const src = pointer(rel, sf, stmt)
|
||||
const where = `event-envelope type '${name}' (${src})`
|
||||
const prior = found.get(name)
|
||||
if (prior) {
|
||||
violations.push(`${where} is already declared at ${prior.source}; the persisted envelope type has exactly one owner.`)
|
||||
continue
|
||||
}
|
||||
if (!(stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false)) {
|
||||
violations.push(`${where} is not exported.`)
|
||||
}
|
||||
const { doc, hasMode } = parseJsDoc(rawJsDoc(text, stmt))
|
||||
if (hasMode) violations.push(`${where} carries an @mode tag, but a persisted type has no dispatch mode.`)
|
||||
if (!doc) violations.push(`${where} has no description prose. The full JSDoc is part of the generated catalog.`)
|
||||
found.set(name, { name, declaration: declarationText(text, sf, stmt), source: src })
|
||||
}
|
||||
}
|
||||
const missing = EVENT_ENVELOPE_TYPE_NAMES.filter(name => !found.has(name))
|
||||
if (missing.length > 0) {
|
||||
violations.push(`missing event-envelope declaration(s): ${missing.join(', ')}.`)
|
||||
}
|
||||
reportViolations('gen-persistence-catalog', violations)
|
||||
return EVENT_ENVELOPE_TYPE_NAMES.map((name) => {
|
||||
const entry = found.get(name)
|
||||
if (!entry) throw new Error(`gen-persistence-catalog: missing checked event-envelope declaration '${name}'.`)
|
||||
return entry
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse the `SurfaceEventType` union — the surface-eligible subset of event
|
||||
* types — from source. Hard-errors when the alias is missing, declared more
|
||||
* than once, or contains a non-string-literal member: the badge derivation
|
||||
* relies on the union being a closed set of literal event names.
|
||||
* `scanRoot` defaults to the repo root; tests pass a fixture dir.
|
||||
*/
|
||||
export function collectSurfaceEventTypes(scanRoot: string = root): string[] {
|
||||
const found: { names: string[]; source: string }[] = []
|
||||
for (const rel of globSync('packages/*/*/src/**/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
|
||||
const abs = resolve(scanRoot, rel)
|
||||
const text = readFileSync(abs, 'utf8')
|
||||
if (!text.includes('SurfaceEventType')) continue
|
||||
const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
|
||||
for (const stmt of sf.statements) {
|
||||
if (!ts.isTypeAliasDeclaration(stmt) || stmt.name.text !== 'SurfaceEventType') continue
|
||||
const src = pointer(rel, sf, stmt)
|
||||
const members = ts.isUnionTypeNode(stmt.type) ? [...stmt.type.types] : [stmt.type]
|
||||
const names: string[] = []
|
||||
for (const m of members) {
|
||||
if (ts.isLiteralTypeNode(m) && ts.isStringLiteral(m.literal)) names.push(m.literal.text)
|
||||
else throw new Error(`gen-persistence-catalog: SurfaceEventType (${src}) has a non-string-literal member; the badge derivation needs a closed literal union.`)
|
||||
}
|
||||
found.push({ names, source: src })
|
||||
}
|
||||
}
|
||||
const only = found[0]
|
||||
if (!only) throw new Error('gen-persistence-catalog: no SurfaceEventType union found under packages/*/*/src.')
|
||||
if (found.length > 1) throw new Error(`gen-persistence-catalog: SurfaceEventType is declared more than once (${found.map(f => f.source).join(', ')}); the surface subset has exactly one owner.`)
|
||||
return only.names
|
||||
}
|
||||
|
||||
/**
|
||||
* Attach the surface/log-only badge to each event. Hard-errors when a
|
||||
* `SurfaceEventType` union member names no collected event — a stale union
|
||||
* member would otherwise silently badge nothing.
|
||||
*/
|
||||
export function annotateSurface(events: LogEventEntry[], surfaceTypes: string[]): AnnotatedLogEventEntry[] {
|
||||
const names = new Set(events.map(e => e.name))
|
||||
const stale = surfaceTypes.filter(t => !names.has(t))
|
||||
if (stale.length > 0) {
|
||||
throw new Error(`gen-persistence-catalog: SurfaceEventType member(s) ${stale.map(t => `'${t}'`).join(', ')} name no declared log event (stale union member?).`)
|
||||
}
|
||||
const surface = new Set(surfaceTypes)
|
||||
return events.map(e => ({ ...e, surface: surface.has(e.name) }))
|
||||
}
|
||||
|
||||
/** Render the cross-link "Types:" line for a payload, or '' if none apply. */
|
||||
function typeLinks(payload: string): string {
|
||||
function typeLinks(payload: string, locale: PersistenceCatalogLocale): string {
|
||||
const seen = new Set<string>()
|
||||
for (const name of Object.keys(LINK_MAP)) {
|
||||
if (new RegExp(`\\b${name}\\b`).test(payload)) seen.add(name)
|
||||
}
|
||||
if (seen.size === 0) return ''
|
||||
const links = [...seen].sort().map(n => `[${n}](${LINK_MAP[n]})`)
|
||||
return `Types: ${links.join(' · ')}`
|
||||
const links = Object.entries(LINK_MAP).filter(([name]) => seen.has(name)).sort(([left], [right]) => left.localeCompare(right))
|
||||
.map(([name, path]) => {
|
||||
return `[${name}](${locale === 'zh' ? path.replace(/\.md$/u, '.zh.md') : path})`
|
||||
})
|
||||
return `${persistenceCatalogText[locale].types}${links.join(' · ')}`
|
||||
}
|
||||
|
||||
/** Render one log event entry. */
|
||||
function renderEvent(e: AnnotatedLogEventEntry): string[] {
|
||||
function renderEvent(e: AnnotatedLogEventEntry, locale: PersistenceCatalogLocale): string[] {
|
||||
const heading = `${e.name} — ${e.surface ? 'surface' : 'log-only'}`
|
||||
const out = [`<a id="${githubSlug(heading)}"></a>`, '', `#### \`${e.name}\` — ${e.surface ? 'surface' : 'log-only'}`, '']
|
||||
out.push('```' + FENCE, e.declaration, '```', '')
|
||||
const links = typeLinks(e.payload)
|
||||
const links = typeLinks(e.payload, locale)
|
||||
if (links) out.push(links, '')
|
||||
out.push(`Source: [\`${e.source}\`](../${e.source.split(':')[0]})`, '')
|
||||
out.push(`${persistenceCatalogText[locale].source}[\`${e.source}\`](../${e.source.split(':')[0]})`, '')
|
||||
return out
|
||||
}
|
||||
|
||||
/** Render the full catalog (pure, deterministic given the collected inputs). */
|
||||
export function render(events: AnnotatedLogEventEntry[], envelopeTypes: EventEnvelopeTypeEntry[]): string {
|
||||
export function render(
|
||||
events: AnnotatedLogEventEntry[],
|
||||
envelopeTypes: EventEnvelopeTypeEntry[],
|
||||
schema?: PersistenceSchemaInventory,
|
||||
locale: PersistenceCatalogLocale = 'en',
|
||||
): string {
|
||||
const text = persistenceCatalogText[locale]
|
||||
const lines: string[] = [
|
||||
'<!-- Generated by scripts/gen-persistence-catalog.ts — do not edit by hand.',
|
||||
' Run `pnpm run gen-persistence-catalog` to regenerate. -->',
|
||||
'',
|
||||
'# Session Persistence Event Catalog',
|
||||
`# ${text.title}`,
|
||||
'',
|
||||
'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge into `@deepseek-ai/dsh-session/types` in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the generated region of [session.md](subsystems/session.md#cordis-surface) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
|
||||
...(locale === 'zh' ? ['[English](persistence-catalog.md) | 中文', ''] : []),
|
||||
text.intro,
|
||||
'',
|
||||
'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. The archived [persistence-log-catalog record](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md) documents the original catalog decision.',
|
||||
text.generation,
|
||||
'',
|
||||
'The envelope declarations below compose each event\'s `type`, monotonic `seq`, epoch-ms `time`, `data`, the optional `ignorable` unknown-type skip marker, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`). Current writers stamp `SESSION_FORMAT_VERSION`; supported historical artifacts reach this current vocabulary through the build-static adjacent migration catalog ([the version lifecycle](subsystems/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further current-version event types, which are outside this catalog by construction and require an explicit disposition at a later format edge.',
|
||||
text.envelopeIntro,
|
||||
'',
|
||||
'## Event envelope',
|
||||
...(schema ? [renderPersistenceSchemaIndex(schema, locale)] : []),
|
||||
`## ${text.envelope}`,
|
||||
'',
|
||||
'```' + FENCE,
|
||||
envelopeTypes.map(entry => entry.declaration).join('\n\n'),
|
||||
'```',
|
||||
'',
|
||||
`Sources: ${envelopeTypes.map(entry => `[\`${entry.source}\`](../${entry.source.split(':')[0]})`).join(' · ')}`,
|
||||
`${text.sources}${envelopeTypes.map(entry => `[\`${entry.source}\`](../${entry.source.split(':')[0]})`).join(' · ')}`,
|
||||
'',
|
||||
'## Events',
|
||||
`## ${text.events}`,
|
||||
'',
|
||||
]
|
||||
const scopes = [...new Set(events.map(e => e.scope))].sort()
|
||||
for (const scope of scopes) {
|
||||
lines.push(`### \`${scope}/*\``, '')
|
||||
for (const e of events.filter(x => x.scope === scope).sort((a, b) => a.name.localeCompare(b.name))) {
|
||||
lines.push(...renderEvent(e))
|
||||
lines.push(...renderEvent(e, locale))
|
||||
}
|
||||
}
|
||||
if (schema) lines.push(renderPersistenceSchemaDefinitions(schema, locale))
|
||||
return lines.join('\n')
|
||||
}
|
||||
|
||||
@@ -424,29 +158,41 @@ export function renderKnownEventTypes(events: AnnotatedLogEventEntry[]): string
|
||||
...names.map(name => ` '${name}',`),
|
||||
'])',
|
||||
'',
|
||||
'/** Event types whose model-visible effects require an explicit pure interpreter. */',
|
||||
'export const MESSAGE_PROJECTION_EVENT_TYPES: ReadonlySet<string> = new Set([',
|
||||
...events.filter(event => event.messageProjection).map(event => ` '${event.name}',`).sort(),
|
||||
'])',
|
||||
'',
|
||||
].join('\n')
|
||||
}
|
||||
|
||||
/** One generated artifact: repo-relative target and its freshly-rendered content. */
|
||||
interface GeneratedArtifact {
|
||||
readonly out: string
|
||||
readonly content: string
|
||||
/**
|
||||
* Render the complete generated persistence reference from one extracted inventory.
|
||||
* @param scanRoot - checkout whose source event declarations supply JSDoc.
|
||||
* @param schema - already extracted source schemas; shared with record validation.
|
||||
* @returns both catalog languages, pairing metadata, runtime names and machine schemas.
|
||||
*/
|
||||
export function persistenceCatalogArtifacts(scanRoot: string, schema: PersistenceSchemaInventory): PersistenceArtifact[] {
|
||||
const events = annotateSurface(collectLogEvents(scanRoot), collectSurfaceEventTypes(scanRoot))
|
||||
const envelope = collectEventEnvelopeTypes(scanRoot)
|
||||
return [
|
||||
...renderPersistencePair(scanRoot, OUT, render(events, envelope, schema), render(events, envelope, schema, 'zh')),
|
||||
{ path: OUT_RUNTIME_TYPES, content: renderKnownEventTypes(events) },
|
||||
{ path: OUT_SCHEMA, content: `${JSON.stringify(schema, null, 2)}\n` },
|
||||
]
|
||||
}
|
||||
|
||||
/** CLI entry: default writes the artifacts, `--check` fails if a committed copy
|
||||
* is stale. Guarded behind an entry-point check so importing this module for
|
||||
* tests neither regenerates the committed files nor calls process.exit. */
|
||||
function main(): void {
|
||||
const events = annotateSurface(collectLogEvents(), collectSurfaceEventTypes())
|
||||
const artifacts: GeneratedArtifact[] = [
|
||||
{ out: OUT, content: render(events, collectEventEnvelopeTypes()) },
|
||||
{ out: OUT_RUNTIME_TYPES, content: renderKnownEventTypes(events) },
|
||||
]
|
||||
const schema = extractPersistenceSchema(root)
|
||||
const artifacts = persistenceCatalogArtifacts(root, schema)
|
||||
if (process.argv.includes('--check')) {
|
||||
const stale = artifacts.filter((artifact) => {
|
||||
let committed: string | null = null
|
||||
try {
|
||||
committed = readFileSync(resolve(root, artifact.out), 'utf8')
|
||||
committed = readFileSync(resolve(root, artifact.path), 'utf8')
|
||||
} catch {
|
||||
// Only ENOENT (not yet generated) is expected; a present-but-unreadable
|
||||
// file is not a state this repo produces. Either way the remedy is the
|
||||
@@ -456,16 +202,16 @@ function main(): void {
|
||||
return committed !== artifact.content
|
||||
})
|
||||
if (stale.length === 0) {
|
||||
console.log(`gen-persistence-catalog: ${artifacts.map(a => a.out).join(', ')} are up to date.`)
|
||||
console.log(`gen-persistence-catalog: ${artifacts.map(a => a.path).join(', ')} are up to date.`)
|
||||
process.exit(0)
|
||||
}
|
||||
console.error(`gen-persistence-catalog: ${stale.map(a => a.out).join(', ')} stale. Run \`pnpm run gen-persistence-catalog\` and commit the result.`)
|
||||
console.error(`gen-persistence-catalog: ${stale.map(a => a.path).join(', ')} stale. Run \`pnpm run gen-persistence-catalog\` and commit the result.`)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
for (const artifact of artifacts) {
|
||||
writeFileSync(resolve(root, artifact.out), artifact.content)
|
||||
console.log(`gen-persistence-catalog: wrote ${artifact.out}.`)
|
||||
writeFileSync(resolve(root, artifact.path), artifact.content)
|
||||
console.log(`gen-persistence-catalog: wrote ${artifact.path}.`)
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -1,16 +1,20 @@
|
||||
import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
|
||||
import { join, resolve } from 'node:path'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { describe, expect, it } from 'vitest'
|
||||
import desktopRuntimeLock from '../apps/desktop/scripts/primary-runtime-lock.json' with { type: 'json' }
|
||||
import {
|
||||
CLAUDE_AGENT_SDK_PACKAGE,
|
||||
assertPreviewDistribution,
|
||||
assertRuntimeLicenses,
|
||||
claudeDistributionFromManifest,
|
||||
collectPythonDependencies,
|
||||
collectDesktopPythonDependencies,
|
||||
isOwnerAuthorizedRuntime,
|
||||
isPermissive,
|
||||
type Manifest,
|
||||
manifestPatterns,
|
||||
mermaidDomPurifyVersion,
|
||||
parsePyprojectRequirements,
|
||||
parseVendoredRows,
|
||||
render,
|
||||
@@ -31,6 +35,9 @@ describe('THIRD_PARTY_NOTICES.md', () => {
|
||||
}, async () => {
|
||||
const generated = await render()
|
||||
expect(generated).toContain('It depends on the third-party software listed below.')
|
||||
expect(generated).toContain(`| [\`numpy\`](https://github.com/numpy/numpy) | ${desktopRuntimeLock.pythonPackages.numpy} | BSD-3-Clause |`)
|
||||
expect(generated).toContain('## LibreOffice conversion kit')
|
||||
expect(generated).toContain('Recipients must have access to those corresponding sources and notices.')
|
||||
expect(readFileSync(resolve(root, 'THIRD_PARTY_NOTICES.md'), 'utf8'), 'stale notices — run `pnpm run gen-third-party-notices`').toBe(generated)
|
||||
})
|
||||
})
|
||||
@@ -46,6 +53,27 @@ function workspace(entries: Record<string, Manifest>): { manifests: Map<string,
|
||||
}
|
||||
|
||||
describe('tierExternalDeps', () => {
|
||||
it('limits the LibreOffice exception to its reviewed package identity and MPL terms', () => {
|
||||
for (const name of [
|
||||
'@deepseek-ai/libreoffice-kit', '@deepseek-ai/libreoffice-kit-wasm',
|
||||
'@deepseek-ai/libreoffice-kit-darwin-arm64', '@deepseek-ai/libreoffice-kit-darwin-x64',
|
||||
'@deepseek-ai/libreoffice-kit-win32-arm64', '@deepseek-ai/libreoffice-kit-win32-x64',
|
||||
]) {
|
||||
expect(() => { assertRuntimeLicenses([{ name, license: 'MPL-2.0' }]) }).not.toThrow()
|
||||
expect(() => { assertRuntimeLicenses([{ name, license: 'GPL-3.0-only' }]) }).toThrow(name)
|
||||
}
|
||||
for (const dependency of [
|
||||
{ name: 'unrelated-library', license: 'MPL-2.0' },
|
||||
{ name: '@deepseek-ai/dsh-libreoffice-kit', license: 'MPL-2.0' },
|
||||
{ name: '@deepseek-ai/libreoffice-kit-unreviewed', license: 'MPL-2.0' },
|
||||
{ name: '@deepseek-ai/libreoffice-kit', license: 'GPL-3.0-only' },
|
||||
{ name: '@deepseek-ai/libreoffice-kit', license: 'UNKNOWN' },
|
||||
]) {
|
||||
expect(() => { assertRuntimeLicenses([dependency]) }).toThrow(`${dependency.name} (${dependency.license})`)
|
||||
}
|
||||
expect(isPermissive('MPL-2.0')).toBe(false)
|
||||
})
|
||||
|
||||
it('keeps license rejection active when a browser library is declared for development', () => {
|
||||
const { manifests, names } = workspace({
|
||||
'packages/client/ui/package.json': { devDependencies: { 'browser-lib': '^1', 'test-tool': '^1' } },
|
||||
@@ -281,6 +309,11 @@ describe('parsePyprojectRequirements', () => {
|
||||
})
|
||||
|
||||
describe('collectPythonDependencies', () => {
|
||||
it('labels shared Python metadata in the Python-project context', () => {
|
||||
const dependencies = collectPythonDependencies(['[project]\ndependencies = ["numpy", "pandas", "six", "tzdata"]\n'])
|
||||
expect(dependencies.map(({ role }) => role)).toEqual(Array(4).fill('Python project dependency'))
|
||||
})
|
||||
|
||||
it('excludes normalized local project names without exempting a third-party prefix', () => {
|
||||
const pyprojects = [
|
||||
'[project]\nname = "deepseek-harness-runtime-bin"\ndependencies = ["pydantic"]\n',
|
||||
@@ -292,6 +325,47 @@ describe('collectPythonDependencies', () => {
|
||||
})
|
||||
})
|
||||
|
||||
describe('collectDesktopPythonDependencies', () => {
|
||||
it('discloses the committed Desktop closure with its exact locked versions', () => {
|
||||
const dependencies = collectDesktopPythonDependencies(desktopRuntimeLock.pythonPackages)
|
||||
expect(dependencies).toHaveLength(Object.keys(desktopRuntimeLock.pythonPackages).length)
|
||||
expect(dependencies).toContainEqual({
|
||||
name: 'pillow', version: desktopRuntimeLock.pythonPackages.Pillow,
|
||||
license: 'MIT-CMU', repo: 'https://github.com/python-pillow/Pillow',
|
||||
})
|
||||
expect(dependencies).toContainEqual({
|
||||
name: 'typing-extensions', version: desktopRuntimeLock.pythonPackages.typing_extensions,
|
||||
license: 'PSF-2.0', repo: 'https://github.com/python/typing_extensions',
|
||||
})
|
||||
})
|
||||
|
||||
it('normalizes names while preserving pinned version strings', () => {
|
||||
expect(collectDesktopPythonDependencies({ 'typing_extensions': '4.16.0', 'Pillow': '12.3.0' }))
|
||||
.toEqual([
|
||||
{ name: 'pillow', version: '12.3.0', license: 'MIT-CMU', repo: 'https://github.com/python-pillow/Pillow' },
|
||||
{ name: 'typing-extensions', version: '4.16.0', license: 'PSF-2.0', repo: 'https://github.com/python/typing_extensions' },
|
||||
])
|
||||
})
|
||||
|
||||
it('rejects duplicate normalized distribution names with the same locked version', () => {
|
||||
expect(() => collectDesktopPythonDependencies({ typing_extensions: '4.16.0', 'typing.extensions': '4.16.0' }))
|
||||
.toThrow('duplicate normalized names')
|
||||
})
|
||||
|
||||
it('rejects missing distribution metadata and conflicting normalized versions', () => {
|
||||
expect(() => collectDesktopPythonDependencies({ missing: '1.0' })).toThrow('missing from PYTHON_METADATA')
|
||||
expect(() => collectDesktopPythonDependencies({ Pillow: '12.3.0', pillow: '12.4.0' })).toThrow('conflicting locked versions')
|
||||
})
|
||||
|
||||
it('applies the runtime license check to bundled Python distributions', () => {
|
||||
expect(() => { assertRuntimeLicenses(collectDesktopPythonDependencies(desktopRuntimeLock.pythonPackages)) }).not.toThrow()
|
||||
const dependencies = collectDesktopPythonDependencies({ 'copyleft-wheel': '1.0' }, {
|
||||
'copyleft-wheel': { license: 'GPL-3.0-only', repo: 'https://example.com/project' },
|
||||
})
|
||||
expect(() => { assertRuntimeLicenses(dependencies) }).toThrow('copyleft-wheel (GPL-3.0-only)')
|
||||
})
|
||||
})
|
||||
|
||||
describe('isPermissive', () => {
|
||||
it('accepts the licenses this project ships and rejects copyleft or unknown ones', () => {
|
||||
expect(['MIT', 'ISC', 'BSD-3-Clause', 'Apache-2.0', 'MIT / Apache-2.0', '(MIT OR CC0-1.0)'].every(isPermissive)).toBe(true)
|
||||
@@ -395,3 +469,66 @@ describe('manifestPatterns', () => {
|
||||
])
|
||||
})
|
||||
})
|
||||
|
||||
describe('preview distribution licenses', () => {
|
||||
const dependencies = { mermaid: '11.16.0', '@viz-js/viz': '3.30.0', dompurify: '3.4.11' }
|
||||
const sources = [
|
||||
'pkg:docker/emscripten/[email protected]?platform=linux%2Famd64',
|
||||
'https://github.com/libexpat/libexpat/releases/download/R_2_8_4/expat-2.8.4.tar.gz',
|
||||
'https://gitlab.com/api/v4/projects/4207231/packages/generic/graphviz-releases/16.0.0/graphviz-16.0.0.tar.gz',
|
||||
]
|
||||
it('checks Mermaid\'s selected DOMPurify when other versions remain installed', () => {
|
||||
const fixture = mkdtempSync(join(tmpdir(), 'dsh-notices-mermaid-'))
|
||||
try {
|
||||
const modules = join(fixture, 'node_modules')
|
||||
const store = join(modules, '.pnpm')
|
||||
const mermaidModules = join(store, '[email protected]', 'node_modules')
|
||||
const mermaid = join(mermaidModules, 'mermaid')
|
||||
mkdirSync(mermaid, { recursive: true })
|
||||
for (const version of ['3.4.11', '3.4.12']) {
|
||||
const dir = join(store, `dompurify@${version}`, 'node_modules', 'dompurify')
|
||||
mkdirSync(dir, { recursive: true })
|
||||
writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'dompurify', version }))
|
||||
}
|
||||
const reviewed = join(store, '[email protected]', 'node_modules', 'dompurify')
|
||||
const upgraded = join(store, '[email protected]', 'node_modules', 'dompurify')
|
||||
const linkedMermaid = join(modules, 'mermaid')
|
||||
const dependency = join(mermaidModules, 'dompurify')
|
||||
symlinkSync(mermaid, linkedMermaid, 'junction')
|
||||
symlinkSync(reviewed, join(modules, 'dompurify'), 'junction')
|
||||
symlinkSync(upgraded, dependency, 'junction')
|
||||
|
||||
const version = mermaidDomPurifyVersion(linkedMermaid)
|
||||
expect(version).toBe('3.4.12')
|
||||
expect(() => { assertPreviewDistribution({ ...dependencies, dompurify: version }, sources) })
|
||||
.toThrow('review dompurify 3.4.12')
|
||||
|
||||
unlinkSync(dependency)
|
||||
symlinkSync(reviewed, dependency, 'junction')
|
||||
expect(() => {
|
||||
assertPreviewDistribution({ ...dependencies, dompurify: mermaidDomPurifyVersion(linkedMermaid) }, sources)
|
||||
}).not.toThrow()
|
||||
|
||||
writeFileSync(join(reviewed, 'package.json'), JSON.stringify({ name: 'dompurify' }))
|
||||
expect(() => mermaidDomPurifyVersion(linkedMermaid)).toThrow('missing Mermaid DOMPurify dependency')
|
||||
unlinkSync(dependency)
|
||||
expect(() => mermaidDomPurifyVersion(linkedMermaid)).toThrow('ENOENT')
|
||||
} finally {
|
||||
rmSync(fixture, { recursive: true, force: true })
|
||||
}
|
||||
})
|
||||
it('accepts the reviewed wrapper and native sources', () => {
|
||||
expect(() => { assertPreviewDistribution(dependencies, sources) }).not.toThrow()
|
||||
const notices = readFileSync(resolve(root, 'packages/client/ui-primitives/THIRD_PARTY_PREVIEW_NOTICES.txt'), 'utf8')
|
||||
expect(notices).toContain('Eclipse Public License - v 2.0')
|
||||
expect(notices).toContain(sources[2])
|
||||
expect(notices).toContain(readFileSync(resolve(root, 'packages/client/ui-primitives/node_modules/mermaid/LICENSE'), 'utf8').trim())
|
||||
expect(notices).toContain('===== DOMPurify =====')
|
||||
})
|
||||
it.each(Object.keys(dependencies))('rejects an unreviewed %s upgrade', (name) => {
|
||||
expect(() => { assertPreviewDistribution({ ...dependencies, [name]: '99.0.0' }, sources) }).toThrow('preview notices: review')
|
||||
})
|
||||
it.each([sources.slice(1), [...sources, 'https://example.com/new-library'], [...sources.slice(0, 2), 'graphviz-next']])('rejects changed embedded sources', (...uris) => {
|
||||
expect(() => { assertPreviewDistribution(dependencies, uris) }).toThrow('native sources')
|
||||
})
|
||||
})
|
||||
@@ -1,18 +1,19 @@
|
||||
/**
|
||||
* Generate `THIRD_PARTY_NOTICES.md` from the workspace manifests: every
|
||||
* external dependency named by a workspace `package.json`, the vendored-package
|
||||
* manifest in `vendor/README.md`, the Python `pyproject.toml` files, and the
|
||||
* pnpm patch list. License and repository metadata come from the installed
|
||||
* manifest in `vendor/README.md`, the Python `pyproject.toml` files, the Desktop
|
||||
* Python distribution lock, and the pnpm patch list. npm metadata comes from the installed
|
||||
* store, so the tree must be installed. `--check` verifies the committed
|
||||
* artifact. Tier policy and ownership live in
|
||||
* `.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md`.
|
||||
*/
|
||||
|
||||
import { existsSync, globSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
|
||||
import { existsSync, globSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
|
||||
import { dirname, resolve } from 'node:path'
|
||||
import * as yaml from 'js-yaml'
|
||||
import { parse as parseToml, type TomlTableWithoutBigInt, type TomlValueWithoutBigInt } from 'smol-toml'
|
||||
import parseSpdx from 'spdx-expression-parse'
|
||||
import desktopRuntimeLock from '../apps/desktop/scripts/primary-runtime-lock.json' with { type: 'json' }
|
||||
import { browserBundledExternals } from './browser-bundled-externals.ts'
|
||||
|
||||
const root = resolve(import.meta.dirname, '..')
|
||||
@@ -52,6 +53,15 @@ const FIRST_PARTY = new Set([
|
||||
export const CLAUDE_AGENT_SDK_PACKAGE = '@anthropic-ai/claude-agent-sdk'
|
||||
const CLAUDE_PLATFORM_PACKAGE_PREFIX = `${CLAUDE_AGENT_SDK_PACKAGE}-`
|
||||
const CLAUDE_PLATFORM_DECLARED_LICENSE = 'SEE LICENSE IN LICENSE.md'
|
||||
const LIBREOFFICE_KIT_PACKAGE = '@deepseek-ai/libreoffice-kit'
|
||||
const LIBREOFFICE_PACKAGES = new Set([
|
||||
LIBREOFFICE_KIT_PACKAGE,
|
||||
'@deepseek-ai/libreoffice-kit-wasm',
|
||||
'@deepseek-ai/libreoffice-kit-darwin-arm64',
|
||||
'@deepseek-ai/libreoffice-kit-darwin-x64',
|
||||
'@deepseek-ai/libreoffice-kit-win32-arm64',
|
||||
'@deepseek-ai/libreoffice-kit-win32-x64',
|
||||
])
|
||||
|
||||
/**
|
||||
* Whether a non-permissive runtime declaration has an identity-scoped owner
|
||||
@@ -81,14 +91,27 @@ const OVERRIDES: Record<string, { license?: string; repo?: string }> = {
|
||||
}
|
||||
|
||||
/**
|
||||
* Python dependencies are few and named directly in `pyproject.toml` files
|
||||
* without installed metadata to harvest, so license/repo are recorded here and
|
||||
* the generator fails when a manifest names a package this map misses.
|
||||
* Python metadata is recorded from the distributions' license and project
|
||||
* fields; generation does not require installing their wheels. Both Python
|
||||
* manifests and the Desktop lock reject names absent from this map.
|
||||
*/
|
||||
const PYTHON_METADATA: Record<string, { license: string; repo: string; role: string }> = {
|
||||
const PYTHON_METADATA: Record<string, { license: string; repo: string; role?: string }> = {
|
||||
pydantic: { license: 'MIT', repo: 'https://github.com/pydantic/pydantic', role: 'runtime dependency of `deepseek-harness-sdk`' },
|
||||
hatchling: { license: 'MIT', repo: 'https://github.com/pypa/hatch', role: 'build backend' },
|
||||
'et-xmlfile': { license: 'MIT', repo: 'https://foss.heptapod.net/openpyxl/et_xmlfile' },
|
||||
lxml: { license: 'BSD-3-Clause', repo: 'https://github.com/lxml/lxml' },
|
||||
numpy: { license: 'BSD-3-Clause', repo: 'https://github.com/numpy/numpy' },
|
||||
openpyxl: { license: 'MIT', repo: 'https://foss.heptapod.net/openpyxl/openpyxl' },
|
||||
pandas: { license: 'BSD-3-Clause', repo: 'https://github.com/pandas-dev/pandas' },
|
||||
pillow: { license: 'MIT-CMU', repo: 'https://github.com/python-pillow/Pillow' },
|
||||
'python-dateutil': { license: 'Apache-2.0 OR BSD-3-Clause', repo: 'https://github.com/dateutil/dateutil' },
|
||||
'python-docx': { license: 'MIT', repo: 'https://github.com/python-openxml/python-docx' },
|
||||
'python-pptx': { license: 'MIT', repo: 'https://github.com/scanny/python-pptx' },
|
||||
pytest: { license: 'MIT', repo: 'https://github.com/pytest-dev/pytest', role: 'test-only' },
|
||||
six: { license: 'MIT', repo: 'https://github.com/benjaminp/six' },
|
||||
'typing-extensions': { license: 'PSF-2.0', repo: 'https://github.com/python/typing_extensions' },
|
||||
tzdata: { license: 'Apache-2.0', repo: 'https://github.com/python/tzdata' },
|
||||
xlsxwriter: { license: 'BSD-2-Clause', repo: 'https://github.com/jmcnamara/XlsxWriter' },
|
||||
}
|
||||
|
||||
type PythonMetadata = typeof PYTHON_METADATA
|
||||
@@ -443,7 +466,7 @@ export function parseVendoredRows(text: string): VendoredRow[] {
|
||||
* disclosed, so a row that stops matching the table format is a hard error
|
||||
* rather than a package that quietly vanishes from the notices.
|
||||
*/
|
||||
function collectVendored(): VendoredRow[] {
|
||||
function collectVendored(): (VendoredRow & { sourceDirectory: string })[] {
|
||||
const rows = parseVendoredRows(readFileSync(resolve(root, 'vendor/README.md'), 'utf8'))
|
||||
const onDisk = new Map<string, string>()
|
||||
for (const entry of readdirSync(resolve(root, 'vendor'), { withFileTypes: true })) {
|
||||
@@ -457,15 +480,15 @@ function collectVendored(): VendoredRow[] {
|
||||
if (missing.length > 0) {
|
||||
throw new Error(`gen-third-party-notices: vendor/README.md has no manifest-table row for ${missing.join(', ')}; its table format changed or the sync is incomplete.`)
|
||||
}
|
||||
for (const row of rows) {
|
||||
return rows.map((row) => {
|
||||
const dir = onDisk.get(row.npmName)
|
||||
if (dir === undefined) throw new Error(`gen-third-party-notices: vendored package ${row.npmName} from vendor/README.md has no vendor/ directory.`)
|
||||
const license = readManifest(`vendor/${dir}/package.json`).license
|
||||
if (license !== 'MIT') {
|
||||
throw new Error(`gen-third-party-notices: vendored ${row.npmName} declares license ${JSON.stringify(license)}; the vendored section assumes MIT throughout.`)
|
||||
}
|
||||
}
|
||||
return rows
|
||||
return { ...row, sourceDirectory: `vendor/${dir}` }
|
||||
})
|
||||
}
|
||||
|
||||
/** Whether a parsed TOML value is a table rather than an array or scalar. */
|
||||
@@ -581,7 +604,7 @@ export function collectPythonDependencies(
|
||||
return [...found].sort((a, b) => a.localeCompare(b)).map((name) => {
|
||||
const entry = metadata[name]
|
||||
if (entry === undefined) throw new Error(`gen-third-party-notices: python dependency ${name} is missing from PYTHON_METADATA.`)
|
||||
return { name, ...entry }
|
||||
return { name, ...entry, role: entry.role ?? 'Python project dependency' }
|
||||
})
|
||||
}
|
||||
|
||||
@@ -592,6 +615,33 @@ function collectPython(): { name: string; license: string; repo: string; role: s
|
||||
return collectPythonDependencies(manifests.map(path => readFileSync(resolve(root, path), 'utf8')))
|
||||
}
|
||||
|
||||
/**
|
||||
* Disclose every Desktop wheel distribution using its locked version, rejecting duplicate normalized names.
|
||||
* @param packages - Distribution names and exact versions from the Desktop runtime lock.
|
||||
* @param metadata - License and source metadata for every locked distribution.
|
||||
* @returns Normalized, sorted distribution identities with versions and licenses.
|
||||
*/
|
||||
export function collectDesktopPythonDependencies(
|
||||
packages: Readonly<Record<string, string>>,
|
||||
metadata: PythonMetadata = PYTHON_METADATA,
|
||||
): { name: string; version: string; license: string; repo: string }[] {
|
||||
const normalized = new Map<string, string>()
|
||||
for (const [distribution, version] of Object.entries(packages)) {
|
||||
const name = normalizePythonDistributionName(distribution)
|
||||
const previous = normalized.get(name)
|
||||
if (previous !== undefined && previous !== version) {
|
||||
throw new Error(`gen-third-party-notices: Desktop python distribution ${name} has conflicting locked versions.`)
|
||||
}
|
||||
if (previous !== undefined) throw new Error(`gen-third-party-notices: Desktop python distribution ${name} has duplicate normalized names.`)
|
||||
normalized.set(name, version)
|
||||
}
|
||||
return [...normalized].sort(([a], [b]) => a.localeCompare(b)).map(([name, version]) => {
|
||||
const entry = metadata[name]
|
||||
if (entry === undefined) throw new Error(`gen-third-party-notices: Desktop python distribution ${name} is missing from PYTHON_METADATA.`)
|
||||
return { name, version, license: entry.license, repo: entry.repo }
|
||||
})
|
||||
}
|
||||
|
||||
/** pnpm-patched external packages, from `pnpm-workspace.yaml`. */
|
||||
function collectPatched(): { spec: string; patch: string }[] {
|
||||
const workspace = yaml.load(readFileSync(resolve(root, 'pnpm-workspace.yaml'), 'utf8')) as { patchedDependencies?: Record<string, string> }
|
||||
@@ -599,7 +649,7 @@ function collectPatched(): { spec: string; patch: string }[] {
|
||||
}
|
||||
|
||||
/** SPDX identifiers this project may ship without further review. */
|
||||
const PERMISSIVE_LICENSES = new Set(['MIT', 'ISC', 'BSD-2-Clause', 'BSD-3-Clause', 'Apache-2.0', '0BSD', 'Unlicense', 'CC0-1.0', 'BlueOak-1.0.0', 'Python-2.0'])
|
||||
const PERMISSIVE_LICENSES = new Set(['MIT', 'MIT-CMU', 'ISC', 'BSD-2-Clause', 'BSD-3-Clause', 'Apache-2.0', '0BSD', 'Unlicense', 'CC0-1.0', 'BlueOak-1.0.0', 'Python-2.0', 'PSF-2.0'])
|
||||
|
||||
/** Evaluate a parsed SPDX expression under the repository's license policy. */
|
||||
function isPermissiveSpdx(expression: ReturnType<typeof parseSpdx>): boolean {
|
||||
@@ -639,7 +689,9 @@ export function isPermissive(license: string): boolean {
|
||||
* @throws When a runtime package has no permissive license or exact owner authorization.
|
||||
*/
|
||||
export function assertRuntimeLicenses(dependencies: readonly { name: string; license: string }[]): void {
|
||||
const rejected = dependencies.filter(dep => !isPermissive(dep.license) && !isOwnerAuthorizedRuntime(dep.name))
|
||||
const rejected = dependencies.filter(dep => !isPermissive(dep.license)
|
||||
&& !isOwnerAuthorizedRuntime(dep.name)
|
||||
&& !(LIBREOFFICE_PACKAGES.has(dep.name) && dep.license === 'MPL-2.0'))
|
||||
if (rejected.length > 0) {
|
||||
throw new Error(`gen-third-party-notices: runtime ${rejected.map(dep => `${dep.name} (${dep.license})`).join(', ')} is not a permissive license; review the distribution terms and record the decision before regenerating.`)
|
||||
}
|
||||
@@ -685,6 +737,40 @@ ${rows.join('\n')}
|
||||
`
|
||||
}
|
||||
|
||||
/**
|
||||
* Read the DOMPurify version selected by Mermaid's pnpm dependency link.
|
||||
* @param mermaidDirectory - Installed Mermaid directory, including workspace symlinks.
|
||||
* @returns The installed version; throws when the dependency or its version is missing.
|
||||
*/
|
||||
export function mermaidDomPurifyVersion(mermaidDirectory: string): string {
|
||||
const path = resolve(realpathSync(mermaidDirectory), '..', 'dompurify/package.json')
|
||||
const manifest = JSON.parse(readFileSync(path, 'utf8')) as Manifest
|
||||
if (manifest.version === undefined) throw new Error('preview notices: missing Mermaid DOMPurify dependency')
|
||||
return manifest.version
|
||||
}
|
||||
|
||||
/**
|
||||
* Require renewed license review when a preview dependency or embedded source changes.
|
||||
* @param dependencies - UI primitives' browser build dependencies.
|
||||
* @param sources - Native source URIs from the installed Viz.js build attestation.
|
||||
* @returns Nothing; throws when a version or native source differs from the reviewed distribution.
|
||||
*/
|
||||
export function assertPreviewDistribution(dependencies: Record<string, string>, sources: readonly string[]): void {
|
||||
for (const [name, version] of Object.entries({ mermaid: '11.16.0', '@viz-js/viz': '3.30.0', dompurify: '3.4.11' })) {
|
||||
if (dependencies[name] !== version) {
|
||||
throw new Error(`preview notices: review ${name} ${String(dependencies[name])} licenses and update THIRD_PARTY_PREVIEW_NOTICES.txt`)
|
||||
}
|
||||
}
|
||||
const expected = [
|
||||
'pkg:docker/emscripten/[email protected]?platform=linux%2Famd64',
|
||||
'https://github.com/libexpat/libexpat/releases/download/R_2_8_4/expat-2.8.4.tar.gz',
|
||||
'https://gitlab.com/api/v4/projects/4207231/packages/generic/graphviz-releases/16.0.0/graphviz-16.0.0.tar.gz',
|
||||
]
|
||||
if (sources.length !== expected.length || expected.some(uri => !sources.includes(uri))) {
|
||||
throw new Error('preview notices: review the changed Viz.js native sources and their distribution licenses')
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Render the complete notices document.
|
||||
* @returns The exact bytes THIRD_PARTY_NOTICES.md must hold after resolving browser inputs.
|
||||
@@ -695,11 +781,26 @@ export async function render(): Promise<string> {
|
||||
// the manifests map it was resolved from; render() owns that single load.
|
||||
workspaceLinkedManifestCache.clear()
|
||||
const { manifests, names } = loadWorkspaceManifests()
|
||||
const previewPackage = 'packages/client/ui-primitives'
|
||||
// Viz.js fixes the upstream SLSA statement filename; the repository uses concrete local names.
|
||||
const statementPath = resolve(root, previewPackage, 'node_modules/@viz-js/viz/lib', 'prove' + 'nance.json')
|
||||
const buildStatement = JSON.parse(readFileSync(statementPath, 'utf8')) as {
|
||||
predicate: { buildDefinition: { resolvedDependencies: { uri: string }[] } }
|
||||
}
|
||||
const previewDependencies = manifests.get(`${previewPackage}/package.json`)?.devDependencies
|
||||
if (previewDependencies === undefined) throw new Error('preview notices: missing UI primitives browser dependencies')
|
||||
const dompurify = mermaidDomPurifyVersion(resolve(root, previewPackage, 'node_modules/mermaid'))
|
||||
assertPreviewDistribution(
|
||||
{ ...previewDependencies, dompurify },
|
||||
buildStatement.predicate.buildDefinition.resolvedDependencies.map(source => source.uri),
|
||||
)
|
||||
const npm = collectNpmDeps(manifests, names, browser)
|
||||
const runtimeDeps = npm.filter(dep => dep.runtime)
|
||||
const devDeps = npm.filter(dep => !dep.runtime)
|
||||
const kitRuntime = runtimeDeps.some(dep => dep.name === LIBREOFFICE_KIT_PACKAGE)
|
||||
const vendored = collectVendored()
|
||||
const python = collectPython()
|
||||
const desktopPython = collectDesktopPythonDependencies(desktopRuntimeLock.pythonPackages)
|
||||
const patched = collectPatched()
|
||||
const claudeDistribution = runtimeDeps.some(
|
||||
dep => dep.name === CLAUDE_AGENT_SDK_PACKAGE,
|
||||
@@ -708,6 +809,7 @@ export async function render(): Promise<string> {
|
||||
: undefined
|
||||
const nonPermissiveDev = devDeps.filter(dep => !isPermissive(dep.license))
|
||||
assertRuntimeLicenses(runtimeDeps)
|
||||
assertRuntimeLicenses(desktopPython)
|
||||
const patchedLines = patched.map(({ spec, patch }) => `- \`${spec}\` — [\`${patch}\`](${patch})`)
|
||||
|
||||
return `<!-- Generated by scripts/gen-third-party-notices.ts — do not edit by hand.
|
||||
@@ -717,17 +819,17 @@ export async function render(): Promise<string> {
|
||||
|
||||
DeepSeek Harness is licensed under [MIT](LICENSE). It depends on the third-party software listed below. Each project remains under its own license; nothing in this file changes those terms.
|
||||
|
||||
This file lists **direct** dependencies declared by the workspace and the explicitly disclosed official Claude Code platform payload closure. It is generated from the workspace manifests by \`scripts/gen-third-party-notices.ts\`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and \`scripts/gen-third-party-notices.spec.ts\` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run \`pnpm run verify-third-party-notices\` for the standalone check.
|
||||
This file lists **direct** dependencies declared by the workspace, the explicitly disclosed official Claude Code platform payload closure, and the Desktop bundled Python distributions. It is generated by \`scripts/gen-third-party-notices.ts\`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and \`scripts/gen-third-party-notices.spec.ts\` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run \`pnpm run verify-third-party-notices\` for the standalone check.
|
||||
|
||||
The complete npm transitive closure, including the Landlock launcher workspace, is recorded with exact pinned versions in [\`pnpm-lock.yaml\`](pnpm-lock.yaml) — inspect it with \`pnpm licenses list\`. The Python closure is recorded separately in [\`python/sdk/uv.lock\`](python/sdk/uv.lock).
|
||||
The complete npm transitive closure, including the Landlock launcher workspace, is recorded with exact pinned versions in [\`pnpm-lock.yaml\`](pnpm-lock.yaml) — inspect it with \`pnpm licenses list\`. The Python SDK closure is recorded separately in [\`python/sdk/uv.lock\`](python/sdk/uv.lock).
|
||||
|
||||
## Vendored source (\`vendor/\`)
|
||||
|
||||
The Cordis framework and its foundation libraries are source-vendored into this repository rather than consumed from npm, and republished under the \`@deepseek-ai\` scope. All are MIT-licensed; each directory preserves its upstream \`LICENSE\` file. Exact upstream commits and local modifications are recorded in [\`vendor/README.md\`](vendor/README.md).
|
||||
|
||||
| Package | Upstream name | Upstream | License |
|
||||
| Package | Upstream name | Source | License |
|
||||
| --- | --- | --- | --- |
|
||||
${vendored.map(row => `| \`${row.npmName}\` | \`${row.upstreamName}\` | [${row.upstream.replace('https://', '')}](${row.upstream}) | MIT |`).join('\n')}
|
||||
${vendored.map(row => `| \`${row.npmName}\` | \`${row.upstreamName}\` | [${row.sourceDirectory}](${row.sourceDirectory}/) | MIT |`).join('\n')}
|
||||
|
||||
## Runtime npm dependencies
|
||||
|
||||
@@ -735,10 +837,19 @@ External packages installed for runtime use or distributed inside the prebuilt b
|
||||
|
||||
${renderNpmTable(runtimeDeps)}
|
||||
|
||||
The Markdown preview distribution also contains Graphviz 16.0.0 (EPL-2.0), Expat 2.8.4 (MIT), and Emscripten 5.0.7 runtime code (MIT/NCSA) inside \`@viz-js/viz\` 3.30.0. The wrapper's MIT metadata does not relicense these components. [Preview notices](packages/client/ui-primitives/THIRD_PARTY_PREVIEW_NOTICES.txt) preserve their full license texts and Graphviz source availability, together with Mermaid's MIT and its DOMPurify dependency's selected Apache-2.0 terms. The UI primitives npm package includes this file; the Web build emits it as \`preview-third-party-notices.txt\`.
|
||||
|
||||
pnpm applies local patches to the following packages at install time, so shipped artifacts carry modified copies; each patch file is the complete record of the modification:
|
||||
|
||||
${patchedLines.join('\n')}
|
||||
${renderClaudeDistribution(claudeDistribution)}
|
||||
${kitRuntime ? `
|
||||
## LibreOffice conversion kit
|
||||
|
||||
${[...LIBREOFFICE_PACKAGES].map(name => `\`${name}\``).join(', ')} declare MPL-2.0, which remains outside the permissive-license allowlist; the notices check accepts only these package identities at those terms. The [distribution decision](.agents/notes/implemented/architecture/2026-09-14-independent-libreoffice-kit.md) records the source obligations.
|
||||
|
||||
The [kit repository](https://github.com/deepseek-harness/libreoffice-kit) supplies the corresponding LibreOffice source pin, modifications, build instructions, Node API, and artifact validation. Its engine packages retain their license and third-party notices; the Node API retains its MPL-2.0 declaration and NOTICE. Recipients must have access to those corresponding sources and notices.
|
||||
` : ''}
|
||||
|
||||
## Development-only npm dependencies
|
||||
|
||||
@@ -755,6 +866,14 @@ Direct dependencies of the \`pyproject.toml\` manifests, plus \`uv\` as the deve
|
||||
${python.map(dep => `| [\`${dep.name}\`](${dep.repo}) | ${dep.license} | ${dep.role} |`).join('\n')}
|
||||
| [\`uv\`](https://github.com/astral-sh/uv) | MIT / Apache-2.0 | development workflow tool |
|
||||
|
||||
## Desktop bundled Python distributions
|
||||
|
||||
The [Desktop runtime lock](apps/desktop/scripts/primary-runtime-lock.json) records each distribution version and the wheel download hashes. The table includes every entry in \`pythonPackages\`, including transitive dependencies. Wheel extraction preserves distribution metadata and the license and notice files supplied by each archive. Project licenses below do not enumerate the separate licenses of native libraries bundled inside wheels.
|
||||
|
||||
| Distribution | Locked version | Project license |
|
||||
| --- | --- | --- |
|
||||
${desktopPython.map(dep => `| [\`${dep.name}\`](${dep.repo}) | ${dep.version} | ${dep.license} |`).join('\n')}
|
||||
|
||||
## First-party native packages
|
||||
|
||||
\`@deepseek-ai/node-addon-system\` (and its platform packages) is built and released from this repository under BSD 3-Clause. It is listed here for completeness; it is first-party, not third-party.
|
||||
|
||||
+67
-16
@@ -58,14 +58,21 @@ import Lsp from '@deepseek-ai/dsh-lsp'
|
||||
import * as ToolLsp from '@deepseek-ai/dsh-tool-lsp'
|
||||
import * as ToolSkill from '@deepseek-ai/dsh-tool-skill'
|
||||
import * as ToolSessionQuery from '@deepseek-ai/dsh-tool-session-query'
|
||||
import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs'
|
||||
import * as ToolJobs from '@deepseek-ai/dsh-tool-jobs'
|
||||
import BrowserUseRegistry from '@deepseek-ai/dsh-browser-use'
|
||||
import * as StagehandBrowserTools from '@deepseek-ai/dsh-experimental-browser-use-stagehand-native'
|
||||
import type TeamService from '@deepseek-ai/dsh-experimental-agent-team'
|
||||
import * as ToolTeam from '@deepseek-ai/dsh-experimental-tool-agent-team'
|
||||
import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
|
||||
import type PluginManager from '@deepseek-ai/dsh-plugin-manager'
|
||||
import * as PluginManagerTools from '@deepseek-ai/dsh-plugin-manager/tools'
|
||||
import SandboxPolicy from '@deepseek-ai/dsh-sandbox-policy'
|
||||
import McpResources from '@deepseek-ai/dsh-mcp-resources'
|
||||
import * as ToolSubagent from '@deepseek-ai/dsh-tool-subagent'
|
||||
import { registerListSubagentModels } from '../packages/subagent/tool-subagent/src/list-models.ts'
|
||||
import * as ToolWeb from '@deepseek-ai/dsh-tool-web'
|
||||
import VmWorkflowEngine from '@deepseek-ai/dsh-workflow-worker-thread'
|
||||
import WorkflowEngine from '@deepseek-ai/dsh-workflow'
|
||||
import type { WorkflowRun, WorkflowStartRequest } from '@deepseek-ai/dsh-workflow'
|
||||
import * as ToolRalph from '@deepseek-ai/dsh-tool-ralph'
|
||||
import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow'
|
||||
import { githubSlug } from './verify-md-links.ts'
|
||||
@@ -97,6 +104,13 @@ class CatalogAttachmentStore extends AttachmentStore {
|
||||
const root = resolve(import.meta.dirname, '..')
|
||||
const OUT = 'docs/tool-catalog.md'
|
||||
|
||||
/** Workflow tools expose their schemas without executing a program. */
|
||||
class CatalogWorkflowEngine extends WorkflowEngine {
|
||||
start(_request: WorkflowStartRequest): WorkflowRun {
|
||||
throw new Error('gen-tool-catalog: workflow execution is unavailable during schema harvest')
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Register the descriptor needed to mount schema-producing consumers. Declares
|
||||
* the full capability set of the shipped in-process providers so consumers
|
||||
@@ -188,6 +202,46 @@ export interface ToolPackage {
|
||||
* guard proves it is exhaustive against the on-disk glob.
|
||||
*/
|
||||
const TOOL_PACKAGES: ToolPackage[] = [
|
||||
{
|
||||
pkg: '@deepseek-ai/dsh-plugin-manager',
|
||||
dir: 'plugin-manager',
|
||||
source: 'packages/boot/plugin-manager/src/tools.ts',
|
||||
requires: ['ctx.tools', 'ctx.pluginManager', 'ctx.sandboxPolicy'],
|
||||
writes: ['tool/call', 'tool/result', 'user/message'],
|
||||
async mount(ctx) {
|
||||
// Schema harvest never executes a management method or opens a profile.
|
||||
ctx.provide('pluginManager', {} as PluginManager)
|
||||
await ctx.plugin(SandboxPolicy)
|
||||
await ctx.plugin(PluginManagerTools)
|
||||
},
|
||||
},
|
||||
{
|
||||
pkg: '@deepseek-ai/dsh-mcp-resources',
|
||||
dir: 'mcp-resources',
|
||||
source: 'packages/mcp/mcp-resources/src/tools.ts',
|
||||
requires: ['ctx.tools', 'ctx.mcpResources'],
|
||||
writes: ['tool/call', 'tool/result'],
|
||||
async mount(ctx) {
|
||||
await ctx.plugin(McpResources)
|
||||
ctx.mcpResources.register('catalog', {
|
||||
request: () => Promise.reject(new Error('gen-tool-catalog: MCP requests are unreachable during schema harvest')),
|
||||
})
|
||||
},
|
||||
},
|
||||
{
|
||||
pkg: '@deepseek-ai/dsh-experimental-browser-use-stagehand-native',
|
||||
dir: 'browser-use-stagehand-native',
|
||||
source: 'packages/experimental/browser-use-stagehand-native/src/index.ts',
|
||||
requires: ['ctx.browserUse', 'ctx.agents', 'ctx.tools', 'ctx.systemPrompt'],
|
||||
writes: ['tool/call', 'tool/result'],
|
||||
async mount(ctx) {
|
||||
await ctx.plugin(BrowserUseRegistry)
|
||||
await ctx.plugin(AgentRegistry)
|
||||
await ctx.plugin(StagehandBrowserTools, {
|
||||
mode: 'launch', model: { modelName: 'openai/gpt-5.4-mini', apiKey: 'catalog-placeholder' },
|
||||
})
|
||||
},
|
||||
},
|
||||
{
|
||||
pkg: '@deepseek-ai/dsh-tool-ask-user',
|
||||
dir: 'tool-ask-user',
|
||||
@@ -205,10 +259,10 @@ const TOOL_PACKAGES: ToolPackage[] = [
|
||||
pkg: '@deepseek-ai/dsh-tools',
|
||||
dir: 'tools',
|
||||
source: 'packages/core/tools/src/ptc.ts',
|
||||
requires: ['ctx.tools', 'ctx.codeRuntime (execution time)', 'ctx.systemPrompt'],
|
||||
requires: ['ctx.tools', 'ctx.ptcRuntime (execution time)', 'ctx.systemPrompt'],
|
||||
writes: ['tool/call', 'one tool/ptc-dispatch-start + tool/ptc-dispatch pair per bridged sub-call', 'tool/result'],
|
||||
// The registry's OWN tool: run_code exists only under a non-native mode
|
||||
// (the registry registers it in its constructor; the code runtime is read
|
||||
// (the registry registers it in its constructor; the PTC runtime is read
|
||||
// at assembly/execution time, so the schema harvest needs none mounted).
|
||||
toolsConfig: { mode: 'ptc' },
|
||||
async mount() {},
|
||||
@@ -245,7 +299,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
|
||||
{
|
||||
pkg: '@deepseek-ai/dsh-tool-present',
|
||||
dir: 'tool-present',
|
||||
source: 'packages/fs/tool-present/src/index.ts',
|
||||
source: 'packages/deliverables/tool-present/src/index.ts',
|
||||
requires: ['ctx.tools', 'ctx.fs', 'ctx.sessionProjections'],
|
||||
writes: ['tool/call', 'deliverables/presented after a successful final result', 'tool/result'],
|
||||
async mount(ctx) {
|
||||
@@ -276,14 +330,14 @@ const TOOL_PACKAGES: ToolPackage[] = [
|
||||
pkg: '@deepseek-ai/dsh-tool-cordis',
|
||||
dir: 'tool-cordis',
|
||||
source: 'packages/extensions/tool-cordis/src/index.ts',
|
||||
requires: ['ctx.tools', 'ctx.dynamicCordisRunner'],
|
||||
writes: ['tool/call', 'tool/result', 'process-local dynamic package lifecycle'],
|
||||
requires: ['ctx.tools', 'ctx.cordisInspect'],
|
||||
writes: ['tool/call', 'tool/result'],
|
||||
async mount(ctx) {
|
||||
await ctx.plugin(CordisHostRunner)
|
||||
await ctx.plugin(ToolCordis)
|
||||
},
|
||||
note:
|
||||
'Not in any shipped tree (a deliberate opt-in — dynamic package code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). The toolset injects `ctx.dynamicCordisRunner` from `@deepseek-ai/dsh-cordis-host-runner`, which owns the definition registry and the vm sandbox; a composition missing it never activates the tools. A running package may register ADDITIONAL model-visible tools until it is stopped, undefined, or DSH restarts; a full changed request header logs those tool-set changes.',
|
||||
'Creator mode provides two read-only runtime inspection tools. The Cordis host runner supplies the inspection registry; Client queries require a connected page. Author persistent changes as bundles and install them with plugin_manager.',
|
||||
},
|
||||
{
|
||||
pkg: '@deepseek-ai/dsh-tool-bash-persistent',
|
||||
@@ -430,7 +484,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
|
||||
async mount(ctx) {
|
||||
await ctx.plugin(SubagentRuntime)
|
||||
registerCatalogSubagentProvider(ctx, 'mock')
|
||||
await ctx.plugin(VmWorkflowEngine, { provider: 'mock' })
|
||||
await ctx.plugin(CatalogWorkflowEngine)
|
||||
await ctx.plugin(ToolRalph, { subagentProvider: 'mock' })
|
||||
},
|
||||
note:
|
||||
@@ -515,7 +569,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
|
||||
writes: ['tool/call', 'tool/result', 'user/message via agent.inject() for background completion notices'],
|
||||
async mount(ctx) {
|
||||
await ctx.plugin(LocalJobRegistry)
|
||||
await ctx.plugin(ToolTasks)
|
||||
await ctx.plugin(ToolJobs)
|
||||
},
|
||||
note:
|
||||
'The kind-agnostic background-job controller: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the controller that arms producers\' `ctx.jobs.start()`.',
|
||||
@@ -541,7 +595,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
|
||||
tryMembership: (candidate: Agent) => candidate === agent ? membership : undefined,
|
||||
membership: () => membership,
|
||||
} as unknown as TeamService)
|
||||
await ctx.plugin(Object.assign((inner: Context) => {
|
||||
await ctx.plugin(Object.assign(async (inner: Context) => {
|
||||
agent = {
|
||||
id: session.id,
|
||||
session,
|
||||
@@ -549,7 +603,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
|
||||
status: 'idle',
|
||||
} as unknown as Agent
|
||||
Object.assign(agent, { ctx: createScope(inner, agent).ctx })
|
||||
inner.agents.register(agent)
|
||||
await inner.agents.register(agent)
|
||||
}, { inject: ['tools', 'systemPrompt', 'agents', 'agentTeams'] }))
|
||||
await ctx.plugin(ToolTeam)
|
||||
catalogChildScopes.set(ctx, agent)
|
||||
@@ -577,12 +631,9 @@ const TOOL_PACKAGES: ToolPackage[] = [
|
||||
requires: ['ctx.tools', 'ctx.workflowEngine', 'ctx.systemPrompt', 'a calling Agent (exec.agent parents the script children)'],
|
||||
writes: ['tool/call', 'tool/result'],
|
||||
async mount(ctx) {
|
||||
// The tool injects `workflows`; boot the vm engine over a scripted
|
||||
// subagent provider to satisfy it. The schema does not depend on which
|
||||
// provider backs the engine.
|
||||
await ctx.plugin(SubagentRuntime)
|
||||
registerCatalogSubagentProvider(ctx, 'mock')
|
||||
await ctx.plugin(VmWorkflowEngine, { provider: 'mock' })
|
||||
await ctx.plugin(CatalogWorkflowEngine)
|
||||
await ctx.plugin(ToolWorkflow)
|
||||
},
|
||||
},
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { join } from 'node:path'
|
||||
import { expect, it, onTestFinished } from 'vitest'
|
||||
import { bundleWorkflowGuest, generateWorkflowGuest } from './gen-workflow-guest.ts'
|
||||
|
||||
async function fixture(source: string): Promise<{ root: string; entry: string; output: string }> {
|
||||
const root = await mkdtemp(join(tmpdir(), 'dsh-workflow-guest-'))
|
||||
onTestFinished(() => rm(root, { recursive: true, force: true }))
|
||||
const directory = join(root, 'packages/workflow/workflow-ptc/src')
|
||||
await mkdir(directory, { recursive: true })
|
||||
await writeFile(join(root, 'tsconfig.base.json'), '{"compilerOptions":{"target":"es2024"}}\n')
|
||||
const entry = join(directory, 'guest.ts')
|
||||
await writeFile(entry, source)
|
||||
return { root, entry, output: join(directory, 'guest-source.ts') }
|
||||
}
|
||||
|
||||
it('bundles source imports into a module that loads without their files', async () => {
|
||||
const { root, entry } = await fixture('import { answer } from "./answer.ts"; import { isBuiltin } from "node:module"; export const result = [answer, isBuiltin("node:vm")];')
|
||||
await writeFile(join(entry, '..', 'answer.ts'), 'export const answer: number = 42;')
|
||||
const source = await bundleWorkflowGuest(root)
|
||||
await rm(join(root, 'packages'), { recursive: true })
|
||||
const module = await import(`data:text/javascript,${encodeURIComponent(source)}`) as { result: unknown }
|
||||
expect(module.result).toEqual([42, true])
|
||||
expect(source).not.toContain(root)
|
||||
})
|
||||
|
||||
it('rejects unresolved imports instead of shipping an unavailable guest dependency', async () => {
|
||||
const { root } = await fixture('import "dsh-nonexistent-workflow-dependency";')
|
||||
await expect(bundleWorkflowGuest(root)).rejects.toThrow('workflow guest has an unresolved import')
|
||||
})
|
||||
|
||||
it('checks the generated artifact against the current source and does not rewrite stale output', async () => {
|
||||
const { root, entry, output } = await fixture('export const answer: number = 42;')
|
||||
await generateWorkflowGuest(root, false)
|
||||
const original = await readFile(output, 'utf8')
|
||||
await generateWorkflowGuest(root, true)
|
||||
await generateWorkflowGuest(root, false)
|
||||
expect(await readFile(output, 'utf8')).toBe(original)
|
||||
await writeFile(entry, 'export const answer: number = 43;')
|
||||
await expect(generateWorkflowGuest(root, true)).rejects.toThrow('workflow guest source is stale')
|
||||
expect(await readFile(output, 'utf8')).toBe(original)
|
||||
})
|
||||
@@ -0,0 +1,72 @@
|
||||
/** Bundle the workflow guest as source data; --check rejects a stale committed module. */
|
||||
|
||||
import { readFile, realpath, writeFile } from 'node:fs/promises'
|
||||
import { isBuiltin } from 'node:module'
|
||||
import { resolve } from 'node:path'
|
||||
import { parseArgs } from 'node:util'
|
||||
import { Rolldown } from 'tsdown'
|
||||
|
||||
const GUEST_ENTRY = 'packages/workflow/workflow-ptc/src/guest.ts'
|
||||
const GUEST_SOURCE = 'packages/workflow/workflow-ptc/src/guest-source.ts'
|
||||
|
||||
/**
|
||||
* Bundle typed guest sources without depending on workspace build outputs.
|
||||
* @param root - Repository root containing source aliases and the guest entry.
|
||||
* @returns One self-contained ESM module with only Node builtin imports.
|
||||
*/
|
||||
export async function bundleWorkflowGuest(root: string): Promise<string> {
|
||||
root = await realpath(root)
|
||||
const bundle = await Rolldown.rolldown({
|
||||
cwd: root,
|
||||
input: resolve(root, GUEST_ENTRY),
|
||||
platform: 'node',
|
||||
tsconfig: resolve(root, 'tsconfig.base.json'),
|
||||
external: id => isBuiltin(id),
|
||||
// The guest imports pure helpers from package barrels, without mounting their services.
|
||||
treeshake: { moduleSideEffects: false },
|
||||
onLog(level, log, defaultHandler) {
|
||||
if (log.code === 'UNRESOLVED_IMPORT') throw new Error(`workflow guest has an unresolved import: ${log.message}`)
|
||||
defaultHandler(level, log)
|
||||
},
|
||||
})
|
||||
try {
|
||||
const { output } = await bundle.generate({ format: 'esm', codeSplitting: false, sourcemap: false })
|
||||
const chunk = output[0]
|
||||
if (output.length !== 1) {
|
||||
throw new Error('workflow guest must bundle into exactly one JavaScript module')
|
||||
}
|
||||
const external = [...chunk.imports, ...chunk.dynamicImports].filter(id => !isBuiltin(id))
|
||||
if (external.length > 0) throw new Error(`workflow guest imports files outside its module: ${external.join(', ')}`)
|
||||
return `${chunk.code.trimEnd()}\n//# sourceURL=dsh-workflow-guest.js\n`
|
||||
} finally {
|
||||
await bundle.close()
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Write the guest-source module or reject a stale committed copy.
|
||||
* @param root - Repository root whose guest sources are bundled.
|
||||
* @param check - Verify without writing when true.
|
||||
*/
|
||||
export async function generateWorkflowGuest(root: string, check: boolean): Promise<void> {
|
||||
const source = await bundleWorkflowGuest(root)
|
||||
const generated = [
|
||||
'/** Generated by scripts/gen-workflow-guest.ts. Do not edit directly. */',
|
||||
'',
|
||||
'/** Self-contained ESM guest transported into the mounted PTC runtime. */',
|
||||
`export const WORKFLOW_GUEST_SOURCE = ${JSON.stringify(source)}`,
|
||||
'',
|
||||
].join('\n')
|
||||
const path = resolve(root, GUEST_SOURCE)
|
||||
if (check) {
|
||||
const current = await readFile(path, 'utf8')
|
||||
if (current !== generated) throw new Error('workflow guest source is stale; run pnpm gen-workflow-guest')
|
||||
} else {
|
||||
await writeFile(path, generated)
|
||||
}
|
||||
}
|
||||
|
||||
if (import.meta.main) {
|
||||
const { values } = parseArgs({ options: { check: { type: 'boolean', default: false } } })
|
||||
await generateWorkflowGuest(resolve(import.meta.dirname, '..'), values.check)
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
import { expect, it } from 'vitest'
|
||||
import { selectOfficeEngine } from './libreoffice-engine.ts'
|
||||
|
||||
it.each([
|
||||
['darwin', 'arm64', 'darwin-arm64'], ['darwin', 'x64', 'darwin-x64'],
|
||||
['win32', 'arm64', 'win32-arm64'], ['win32', 'x64', 'win32-x64'],
|
||||
['linux', 'x64', 'wasm'], ['linux', 'arm64', 'wasm'],
|
||||
['darwin', 'other', 'wasm'], ['freebsd', 'x64', 'wasm'],
|
||||
])('selects the declared engine for %s/%s', (platform, arch, expected) => {
|
||||
const optionalDependencies = Object.fromEntries(
|
||||
['darwin-arm64', 'darwin-x64', 'win32-arm64', 'win32-x64', 'wasm']
|
||||
.map(engine => [`@deepseek-ai/libreoffice-kit-${engine}`, '0.0.1']),
|
||||
)
|
||||
expect(selectOfficeEngine({ optionalDependencies }, { platform, arch })).toBe(expected)
|
||||
})
|
||||
|
||||
it('selects a declared Linux native target without an OS-specific policy change', () => {
|
||||
expect(selectOfficeEngine({ optionalDependencies: { '@deepseek-ai/libreoffice-kit-linux-x64': '1' } },
|
||||
{ platform: 'linux', arch: 'x64' })).toBe('linux-x64')
|
||||
})
|
||||
|
||||
it('uses WASM when no native targets are declared', () => {
|
||||
expect(selectOfficeEngine({}, { platform: 'darwin', arch: 'x64' })).toBe('wasm')
|
||||
})
|
||||
@@ -0,0 +1,17 @@
|
||||
/** Select the single LibreOffice payload from the kit's declared native targets. */
|
||||
|
||||
/**
|
||||
* Require a declared native target even when its optional npm package is absent.
|
||||
* Targets without a declared native engine use WASM.
|
||||
* @param manifest - Installed LibreOffice kit package manifest.
|
||||
* @param target - Node platform and architecture of the distribution.
|
||||
* @returns Engine suffix used by the kit's npm packages.
|
||||
*/
|
||||
export function selectOfficeEngine(
|
||||
manifest: { optionalDependencies?: Record<string, string> },
|
||||
target: { platform: string; arch: string },
|
||||
): string {
|
||||
const native = `${target.platform}-${target.arch}`
|
||||
return Object.hasOwn(manifest.optionalDependencies ?? {}, `@deepseek-ai/libreoffice-kit-${native}`)
|
||||
? native : 'wasm'
|
||||
}
|
||||
@@ -30,7 +30,7 @@ const profiles = {
|
||||
test: {
|
||||
count: 84,
|
||||
indexes: [0, 3, 4, 5],
|
||||
sha256: '7800bf57f0d689a5623e4ad60315b10173158fb9cf988d3f005cb115f2245691',
|
||||
sha256: '7e4e1ed0cfca06ac94eeb26081195b5f753e7527775d5f5b95ccfefac9d2b137',
|
||||
},
|
||||
} as const satisfies Record<string, Profile>
|
||||
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
/** Baseline package selection through Node's real filesystem glob implementation. */
|
||||
|
||||
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { dirname, join } from 'node:path'
|
||||
import { describe, expect, it, onTestFinished } from 'vitest'
|
||||
import { PRIVATE_EXPERIMENTAL_PACKAGE_DIRECTORIES } from './experimental-package-policy.ts'
|
||||
import { discoverNpmBaselineManifests } from './npm-baseline-packages.ts'
|
||||
|
||||
function fixture(manifests: readonly string[]): string {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-baseline-discovery-'))
|
||||
onTestFinished(() => { rmSync(root, { recursive: true, force: true }) })
|
||||
for (const manifest of manifests) {
|
||||
const file = join(root, manifest)
|
||||
mkdirSync(dirname(file), { recursive: true })
|
||||
writeFileSync(file, '{}\n')
|
||||
}
|
||||
return root
|
||||
}
|
||||
|
||||
describe('npm baseline package discovery', () => {
|
||||
it('discovers ordinary package roots and unlisted experimental packages', () => {
|
||||
const expected = [
|
||||
'apps/cli/package.json',
|
||||
'packages/core/session/package.json',
|
||||
'packages/experimental/agent-team/package.json',
|
||||
'packages/experimental/new-prototype/package.json',
|
||||
'vendor/cordis/package.json',
|
||||
]
|
||||
const root = fixture([
|
||||
...expected,
|
||||
'package.json',
|
||||
'packages/experimental/new-prototype/nested/package.json',
|
||||
'website/package.json',
|
||||
])
|
||||
|
||||
expect(discoverNpmBaselineManifests(root)).toEqual(expected)
|
||||
})
|
||||
|
||||
it('excludes every directory in the current publication denylist', () => {
|
||||
const allowed = 'packages/experimental/new-prototype/package.json'
|
||||
const root = fixture([
|
||||
allowed,
|
||||
...PRIVATE_EXPERIMENTAL_PACKAGE_DIRECTORIES.map(directory => `${directory}/package.json`),
|
||||
])
|
||||
|
||||
expect(discoverNpmBaselineManifests(root)).toEqual([allowed])
|
||||
})
|
||||
|
||||
it('excludes an exact configured directory without excluding nearby names', () => {
|
||||
const root = fixture([
|
||||
'packages/experimental/internal/package.json',
|
||||
'packages/experimental/internal-tools/package.json',
|
||||
'packages/experimental/other/package.json',
|
||||
])
|
||||
expect(discoverNpmBaselineManifests(root, ['packages/experimental/internal'])).toEqual([
|
||||
'packages/experimental/internal-tools/package.json',
|
||||
'packages/experimental/other/package.json',
|
||||
])
|
||||
})
|
||||
|
||||
it('retains experimental packages when the configured denylist is empty', () => {
|
||||
const manifests = [
|
||||
'packages/experimental/inspector/package.json',
|
||||
'packages/experimental/new-prototype/package.json',
|
||||
]
|
||||
expect(discoverNpmBaselineManifests(fixture(manifests), [])).toEqual(manifests)
|
||||
})
|
||||
|
||||
it('leaves an empty package set for the baseline caller to reject', () => {
|
||||
expect(discoverNpmBaselineManifests(fixture([]))).toEqual([])
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,26 @@
|
||||
/** Manifest discovery for the npm baseline's vendor, harness, and application packages. */
|
||||
|
||||
import { globSync } from 'node:fs'
|
||||
import { PRIVATE_EXPERIMENTAL_PACKAGE_DIRECTORIES } from './experimental-package-policy.ts'
|
||||
|
||||
const PACKAGE_PATTERNS = [
|
||||
'vendor/*/package.json',
|
||||
'packages/*/*/package.json',
|
||||
'apps/*/package.json',
|
||||
] as const
|
||||
|
||||
/**
|
||||
* Discover baseline manifests while excluding the configured private experimental directories.
|
||||
* @param root - repository root to scan.
|
||||
* @param privateDirectories - repository-relative experimental directories excluded from publication.
|
||||
* @returns Sorted repository-relative manifest paths with forward slashes.
|
||||
*/
|
||||
export function discoverNpmBaselineManifests(
|
||||
root: string,
|
||||
privateDirectories: readonly string[] = PRIVATE_EXPERIMENTAL_PACKAGE_DIRECTORIES,
|
||||
): string[] {
|
||||
return globSync(PACKAGE_PATTERNS, {
|
||||
cwd: root,
|
||||
exclude: privateDirectories.map(directory => `${directory}/package.json`),
|
||||
}).map(path => path.replaceAll('\\', '/')).sort()
|
||||
}
|
||||
@@ -254,6 +254,99 @@ export const longProbe = 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 +
|
||||
}
|
||||
}, 90_000)
|
||||
|
||||
it('allows Session history reads only in tests or with existing-call waivers', async () => {
|
||||
const suffix = randomUUID()
|
||||
const configPath = await writeContractConfig(suffix)
|
||||
const exampleRoot = `examples/oxlint-contract-${suffix}`
|
||||
const examplePath = `${exampleRoot}/tests/reads.ts`
|
||||
const testPaths = [
|
||||
`packages/core/session/tests/oxlint-contract-${suffix}.ts`,
|
||||
`apps/cli/tests/oxlint-contract-${suffix}.ts`,
|
||||
examplePath,
|
||||
`scripts/oxlint-contract-${suffix}.spec.ts`,
|
||||
]
|
||||
const productionPaths = [
|
||||
`packages/core/session/src/oxlint-contract-${suffix}.ts`,
|
||||
`scripts/oxlint-contract-${suffix}.ts`,
|
||||
]
|
||||
const paths = [...testPaths, ...productionPaths]
|
||||
const reads = `import { Session, SessionSeq } from '@deepseek-ai/dsh-session'
|
||||
|
||||
export function reads(session: Session): void {
|
||||
session.snapshotEvents()
|
||||
session.eventAt(SessionSeq(0))
|
||||
session.ownEvents()
|
||||
}
|
||||
`
|
||||
const existing = `import { Session, SessionSeq } from '@deepseek-ai/dsh-session'
|
||||
|
||||
export function reads(session: Session): void {
|
||||
// oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
|
||||
session.snapshotEvents()
|
||||
// oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
|
||||
session.eventAt(SessionSeq(0))
|
||||
// oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
|
||||
session.ownEvents()
|
||||
}
|
||||
`
|
||||
const unrelated = `
|
||||
/** @deprecated Use the replacement API. */
|
||||
function oldApi(): void {}
|
||||
|
||||
export function unrelatedRead(): void {
|
||||
oldApi()
|
||||
}
|
||||
`
|
||||
|
||||
try {
|
||||
await mkdir(join(repositoryRoot, exampleRoot, 'tests'), { recursive: true })
|
||||
await writeFile(join(repositoryRoot, exampleRoot, 'tsconfig.json'), JSON.stringify({
|
||||
extends: '../../tsconfig.base.json',
|
||||
include: ['tests/**/*.ts'],
|
||||
}))
|
||||
await Promise.all([
|
||||
...testPaths.map(path => writeFile(join(repositoryRoot, path), reads)),
|
||||
...productionPaths.map(path => writeFile(join(repositoryRoot, path), existing)),
|
||||
])
|
||||
const args = ['--config', relative(repositoryRoot, configPath), '--format', 'unix', ...paths]
|
||||
const allowed = runRepositoryOxlint(args)
|
||||
expect(allowed.error).toBeUndefined()
|
||||
expect(allowed.signal).toBeNull()
|
||||
expect(allowed.status, normalizedOutput(allowed)).toBe(0)
|
||||
|
||||
await Promise.all([
|
||||
...testPaths.map(path => writeFile(join(repositoryRoot, path), reads + unrelated)),
|
||||
...productionPaths.map(path => writeFile(join(repositoryRoot, path), reads)),
|
||||
])
|
||||
const rejected = runRepositoryOxlint(args)
|
||||
const output = normalizedOutput(rejected)
|
||||
expect(rejected.error).toBeUndefined()
|
||||
expect(rejected.signal).toBeNull()
|
||||
expect(rejected.status, output).toBe(1)
|
||||
const diagnostics = output.split('\n').filter(line => /:\d+:\d+: `\w+` is deprecated\./.test(line))
|
||||
for (const path of testPaths) {
|
||||
const reported = diagnostics.filter(line => line.startsWith(`${path}:`))
|
||||
expect(reported, output).toHaveLength(1)
|
||||
expect(reported[0]).toContain('`oldApi` is deprecated')
|
||||
}
|
||||
for (const path of productionPaths) {
|
||||
expect(diagnostics.filter(line => line.startsWith(`${path}:`)), output).toHaveLength(3)
|
||||
}
|
||||
for (const method of ['snapshotEvents', 'eventAt', 'ownEvents', 'oldApi']) {
|
||||
expect(output).toContain(`\`${method}\` is deprecated`)
|
||||
}
|
||||
expect(output).toContain(
|
||||
'See the [Agent Note](../../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).',
|
||||
)
|
||||
} finally {
|
||||
await Promise.all([
|
||||
...paths.filter(path => path !== examplePath).map(path => rm(join(repositoryRoot, path), { force: true })),
|
||||
rm(join(repositoryRoot, exampleRoot), { recursive: true, force: true }),
|
||||
rm(configPath, { force: true }),
|
||||
])
|
||||
}
|
||||
}, 90_000)
|
||||
|
||||
it('accepts an ignored-only staged selection', () => {
|
||||
const result = runOxlint([
|
||||
'--fix',
|
||||
|
||||
@@ -32,6 +32,7 @@ const CONFIGURATION_ONLY_DEV_DEPENDENCIES = {
|
||||
/** Workspace packages whose complete runtime surface is safe across duplicate installations. */
|
||||
const DUPLICATE_SAFE_PACKAGES: readonly string[] = [
|
||||
'@deepseek-ai/dsh-brand',
|
||||
'@deepseek-ai/dsh-lazy-require',
|
||||
'@deepseek-ai/dsh-typert-protocol',
|
||||
'@deepseek-ai/dsh-util-crypto',
|
||||
'@deepseek-ai/dsh-util-values',
|
||||
@@ -55,6 +56,7 @@ const SAFE_HOST_DEPENDENCY_EXPORTS = {
|
||||
|
||||
/** Runtime exports that require every consumer to resolve the provider's shared peer instance. */
|
||||
const PEER_REQUIRED_HOST_EXPORTS = {
|
||||
'@deepseek-ai/dsh-subprocess': ['SubprocessExecutableNotFoundError'],
|
||||
'@deepseek-ai/dsh-scope': ['carrierKeyOf', 'scopeOf', 'scopeTarget'],
|
||||
'@deepseek-ai/dsh-session': ['SESSION_FORMAT_VERSION'],
|
||||
'@deepseek-ai/dsh-session-persistence': ['SessionPersistenceNotFoundError'],
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
/** Render complete persistence documentation pairs without Git or file mutation. */
|
||||
|
||||
import { readFileSync } from 'node:fs'
|
||||
import { hasLanguageSwitcher } from './translation-links.ts'
|
||||
import { translationPairPaths } from './translation-pairing-record.ts'
|
||||
import {
|
||||
blobHash, languageSwitcherTargets, parseTranslationMarkdown, parseTranslationPairingManifest,
|
||||
renderPairMeta, requiresSourceLanguageSwitcher, translationPairSourcePredicate,
|
||||
translationStructureDiff, translationStructureSignature,
|
||||
} from './translation-pairing.ts'
|
||||
|
||||
const isTranslationPairSource = translationPairSourcePredicate(parseTranslationPairingManifest(
|
||||
readFileSync(new URL('./translation-pairing.manifest.json', import.meta.url), 'utf8'),
|
||||
))
|
||||
|
||||
/** One repository-relative generated file and its complete UTF-8 content. */
|
||||
export interface PersistenceArtifact {
|
||||
readonly path: string
|
||||
readonly content: string
|
||||
}
|
||||
|
||||
/**
|
||||
* Check a pair's code, structure and localized links, then render its three files.
|
||||
* Link existence remains the Markdown gate's responsibility. Pair hashes are
|
||||
* computed in-process; staging the documents stores the corresponding Git blobs.
|
||||
* @param root - checkout root used to resolve relative link identities.
|
||||
* @param source - repository-relative English document path.
|
||||
* @param en - complete authored or generated English Markdown.
|
||||
* @param zh - complete authored or generated Chinese Markdown.
|
||||
* @returns the documents and their matching consistency sidecar, without writing files.
|
||||
*/
|
||||
export function renderPersistencePair(root: string, source: string, en: string, zh: string): PersistenceArtifact[] {
|
||||
const paths = translationPairPaths(source)
|
||||
const sourceTree = parseTranslationMarkdown(en)
|
||||
const zhTree = parseTranslationMarkdown(zh)
|
||||
const sourceTargets = languageSwitcherTargets(paths.source)
|
||||
const zhTargets = languageSwitcherTargets(paths.zh)
|
||||
if (!hasLanguageSwitcher(zhTree, zh, sourceTargets)
|
||||
|| requiresSourceLanguageSwitcher(source) && !hasLanguageSwitcher(sourceTree, en, zhTargets)) {
|
||||
throw new Error(`${source}: both authored languages need their counterpart switcher`)
|
||||
}
|
||||
const context = { repoRoot: root, isTranslationPairSource, repositoryFileExists: () => true }
|
||||
const errors = translationStructureDiff(
|
||||
translationStructureSignature(sourceTree, zhTargets, { ...context, sourcePath: paths.source, markdown: en }),
|
||||
translationStructureSignature(zhTree, sourceTargets, { ...context, sourcePath: paths.zh, markdown: zh }),
|
||||
)
|
||||
if (errors.length > 0) throw new Error(`${source}: bilingual structure mismatch: ${errors.join('; ')}`)
|
||||
return [
|
||||
{ path: paths.source, content: en },
|
||||
{ path: paths.zh, content: zh },
|
||||
{ path: paths.meta, content: renderPairMeta(paths.source, blobHash(Buffer.from(en)), paths.zh, blobHash(Buffer.from(zh))) },
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,307 @@
|
||||
/** Source discovery and declaration validation shared by persistence documentation and schemas. */
|
||||
|
||||
import { globSync, readFileSync } from 'node:fs'
|
||||
import { resolve, sep } from 'node:path'
|
||||
import ts from 'typescript'
|
||||
import { parseJsDoc, pointer, rawJsDoc, reportViolations } from './jsdoc.ts'
|
||||
|
||||
const root = resolve(import.meta.dirname, '..')
|
||||
|
||||
/** The package that owns the durable event vocabulary. */
|
||||
const SESSION_PACKAGE = '@deepseek-ai/dsh-session'
|
||||
|
||||
/** The type-only module that plugin declaration merges augment. */
|
||||
const SESSION_TYPES_MODULE = '@deepseek-ai/dsh-session/types'
|
||||
|
||||
/** Event-envelope declarations rendered before the per-event vocabulary. */
|
||||
const EVENT_ENVELOPE_TYPE_NAMES = [
|
||||
'SessionEventType',
|
||||
'SurfaceEventType',
|
||||
'SurfaceOp',
|
||||
'SessionEvent',
|
||||
] as const
|
||||
|
||||
type EventEnvelopeTypeName = typeof EVENT_ENVELOPE_TYPE_NAMES[number]
|
||||
|
||||
/** One log event, extracted from a `SessionEventMap` declaration. */
|
||||
export interface LogEventEntry {
|
||||
/** Scoped name, e.g. `turn/start`. */
|
||||
name: string
|
||||
/** The scope prefix, e.g. `turn` (everything before the first `/`). */
|
||||
scope: string
|
||||
/** Payload type text (the member's type annotation, whitespace-collapsed). */
|
||||
payload: string
|
||||
/** Source member declaration and complete JSDoc, dedented from its container. */
|
||||
declaration: string
|
||||
/** Description prose (the member's JSDoc), one line per paragraph. */
|
||||
doc: string
|
||||
/** Source pointer `packages/…/file.ts:line` of the declaration. */
|
||||
source: string
|
||||
/** Whether interpretation requires a plugin-owned message projection. */
|
||||
messageProjection?: true
|
||||
}
|
||||
|
||||
/** A {@link LogEventEntry} plus its surface-eligibility badge. */
|
||||
export interface AnnotatedLogEventEntry extends LogEventEntry {
|
||||
/** Whether the type is a `SurfaceEventType` member (may carry `surfaceOp`). */
|
||||
surface: boolean
|
||||
}
|
||||
|
||||
/** One owning event-envelope declaration pasted into the generated catalog. */
|
||||
export interface EventEnvelopeTypeEntry {
|
||||
/** Exported declaration name. */
|
||||
name: EventEnvelopeTypeName
|
||||
/** Verbatim type declaration, including its complete leading JSDoc. */
|
||||
declaration: string
|
||||
/** Source pointer `packages/…/file.ts:line` of the declaration. */
|
||||
source: string
|
||||
}
|
||||
|
||||
const printer = ts.createPrinter({ removeComments: true })
|
||||
|
||||
/**
|
||||
* Render a member type on one line through the TypeScript printer, which adds
|
||||
* semicolon separators. Drop its trailing semicolon before `}` to match the
|
||||
* repository's inline-literal style.
|
||||
*/
|
||||
function payloadText(type: ts.TypeNode, sf: ts.SourceFile): string {
|
||||
return printer.printNode(ts.EmitHint.Unspecified, type, sf)
|
||||
.replace(/\s+/g, ' ')
|
||||
.replace(/;\s*\}/g, ' }')
|
||||
.trim()
|
||||
}
|
||||
|
||||
/**
|
||||
* Copy a declaration from its leading JSDoc through its closing token while
|
||||
* removing only the indentation imposed by its containing interface/module.
|
||||
*/
|
||||
function declarationText(text: string, sf: ts.SourceFile, node: ts.Node): string {
|
||||
const raw = rawJsDoc(text, node)
|
||||
const nodeStart = node.getStart(sf)
|
||||
const start = raw ? text.lastIndexOf(raw, nodeStart) : nodeStart
|
||||
const { line } = sf.getLineAndCharacterOfPosition(start)
|
||||
const lineStart = sf.getPositionOfLineAndCharacter(line, 0)
|
||||
const indent = text.slice(lineStart, start)
|
||||
return text.slice(lineStart, node.end)
|
||||
.split('\n')
|
||||
.map(lineText => lineText.startsWith(indent) ? lineText.slice(indent.length) : lineText)
|
||||
.join('\n')
|
||||
.trimEnd()
|
||||
}
|
||||
|
||||
/**
|
||||
* Every `interface SessionEventMap` declaration in a source file: the owning
|
||||
* top-level declaration (in `@deepseek-ai/dsh-session`) and any declaration
|
||||
* merge inside a `declare module '@deepseek-ai/dsh-session/types'` block. Both forms
|
||||
* declare members of the SAME merged interface, so both are catalogued
|
||||
* uniformly. `topLevel` distinguishes the owning form so the caller can verify
|
||||
* it actually lives in the owning package — an unrelated local interface that
|
||||
* happens to share the name must not be catalogued as the on-disk vocabulary.
|
||||
*/
|
||||
function sessionEventMapDecls(sf: ts.SourceFile): { decl: ts.InterfaceDeclaration; topLevel: boolean }[] {
|
||||
const decls: { decl: ts.InterfaceDeclaration; topLevel: boolean }[] = []
|
||||
for (const stmt of sf.statements) {
|
||||
if (ts.isInterfaceDeclaration(stmt) && stmt.name.text === 'SessionEventMap') decls.push({ decl: stmt, topLevel: true })
|
||||
if (ts.isModuleDeclaration(stmt) && ts.isStringLiteral(stmt.name) && stmt.name.text === SESSION_TYPES_MODULE
|
||||
&& stmt.body && ts.isModuleBlock(stmt.body)) {
|
||||
for (const inner of stmt.body.statements) {
|
||||
if (ts.isInterfaceDeclaration(inner) && inner.name.text === 'SessionEventMap') decls.push({ decl: inner, topLevel: false })
|
||||
}
|
||||
}
|
||||
}
|
||||
return decls
|
||||
}
|
||||
|
||||
/**
|
||||
* The npm package name owning a `packages/<group>/<pkg>/…` source file, read
|
||||
* from that package's manifest — or null when the manifest is missing or
|
||||
* unparseable (the caller treats null as "ownership unverifiable").
|
||||
*/
|
||||
function packageNameFor(rel: string, scanRoot: string): string | null {
|
||||
const dir = rel.split('/').slice(0, 3).join('/')
|
||||
try {
|
||||
const manifest = JSON.parse(readFileSync(resolve(scanRoot, dir, 'package.json'), 'utf8')) as { name?: string }
|
||||
return typeof manifest.name === 'string' ? manifest.name : null
|
||||
} catch {
|
||||
// Missing or malformed package.json — every real workspace package has one,
|
||||
// so this only arises in stripped-down fixture trees; either way ownership
|
||||
// cannot be verified and the caller reports the declaration.
|
||||
return null
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Collect every `SessionEventMap` merge, rejecting inherited, non-literal,
|
||||
* untyped, undocumented, duplicate, or incorrectly owned members in one report.
|
||||
*/
|
||||
export function collectLogEvents(scanRoot: string = root): LogEventEntry[] {
|
||||
const entries: LogEventEntry[] = []
|
||||
const violations: string[] = []
|
||||
const seen = new Map<string, string>()
|
||||
let owningDecl: string | null = null
|
||||
for (const rel of globSync('packages/*/*/src/**/*.{ts,tsx}', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
|
||||
const abs = resolve(scanRoot, rel)
|
||||
const text = readFileSync(abs, 'utf8')
|
||||
if (!text.includes('SessionEventMap')) continue
|
||||
const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
|
||||
for (const { decl, topLevel } of sessionEventMapDecls(sf)) {
|
||||
const declSrc = pointer(rel, sf, decl)
|
||||
if (topLevel) {
|
||||
// The top-level form has one home: the single exported declaration in
|
||||
// the owning package. Same-named interfaces elsewhere are different
|
||||
// types and must not enter the on-disk catalog.
|
||||
const pkg = packageNameFor(rel, scanRoot)
|
||||
if (pkg !== SESSION_PACKAGE) {
|
||||
violations.push(`top-level interface SessionEventMap (${declSrc}) is outside ${SESSION_PACKAGE} (package ${pkg ?? 'unknown'}). Rename the interface, or contribute events via declare module '${SESSION_TYPES_MODULE}'.`)
|
||||
continue
|
||||
}
|
||||
const exported = decl.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false
|
||||
if (!exported) {
|
||||
violations.push(`top-level interface SessionEventMap (${declSrc}) is not exported; the owning vocabulary is the single exported declaration — rename a local helper interface.`)
|
||||
continue
|
||||
}
|
||||
if (owningDecl) {
|
||||
violations.push(`top-level interface SessionEventMap (${declSrc}) is already declared at ${owningDecl}; the owning vocabulary has exactly one home.`)
|
||||
continue
|
||||
}
|
||||
owningDecl = declSrc
|
||||
}
|
||||
if (decl.heritageClauses?.length) {
|
||||
violations.push(`SessionEventMap declaration (${declSrc}) uses extends; inherited keys would join keyof SessionEventMap without a catalog row — declare event members directly.`)
|
||||
}
|
||||
for (const member of decl.members) {
|
||||
const src = pointer(rel, sf, member)
|
||||
if (!ts.isPropertySignature(member) || !member.type) {
|
||||
// A method-form or type-less member still joins `keyof SessionEventMap`,
|
||||
// so skipping it silently would be exactly the undocumented-event hole
|
||||
// this catalog exists to close.
|
||||
const label = (member as { name?: ts.Node }).name?.getText(sf) ?? member.getText(sf).replace(/\s+/g, ' ')
|
||||
violations.push(`SessionEventMap member ${label} (${src}) is not a property signature with an explicit payload type; declare every log event as 'scope/name': <payload>.`)
|
||||
continue
|
||||
}
|
||||
if (!ts.isStringLiteral(member.name)) {
|
||||
violations.push(`log event at ${src} has a non-literal name; the catalog needs string-literal event names.`)
|
||||
continue
|
||||
}
|
||||
const name = member.name.text
|
||||
const where = `log event '${name}' (${src})`
|
||||
const prior = seen.get(name)
|
||||
if (prior) {
|
||||
violations.push(`${where} is already declared at ${prior}; an event type has exactly one declaration.`)
|
||||
continue
|
||||
}
|
||||
seen.set(name, src)
|
||||
const payload = payloadText(member.type, sf)
|
||||
const { doc, hasMode } = parseJsDoc(rawJsDoc(text, member))
|
||||
if (hasMode) {
|
||||
violations.push(`${where} carries an @mode tag, but a log event has no dispatch mode (it is not a cordis bus event — it rides the 'session/event' emit). Remove the tag.`)
|
||||
}
|
||||
if (!doc) {
|
||||
violations.push(`${where} has no description prose. Say what the event records and what its payload means — the JSDoc becomes the catalog entry.`)
|
||||
}
|
||||
const declaration = declarationText(text, sf, member)
|
||||
const messageProjection = ts.getJSDocTags(member).some(tag => tag.tagName.text === 'messageProjection')
|
||||
entries.push({ name, scope: name.split('/')[0] ?? name, payload, declaration, doc, source: src, ...messageProjection ? { messageProjection: true as const } : {} })
|
||||
}
|
||||
}
|
||||
}
|
||||
reportViolations('gen-persistence-catalog', violations)
|
||||
return entries
|
||||
}
|
||||
|
||||
/**
|
||||
* Collect the exported declarations that compose the persisted event envelope,
|
||||
* preserving their source JSDoc and declaration text.
|
||||
*/
|
||||
export function collectEventEnvelopeTypes(scanRoot: string = root): EventEnvelopeTypeEntry[] {
|
||||
const found = new Map<EventEnvelopeTypeName, EventEnvelopeTypeEntry>()
|
||||
const violations: string[] = []
|
||||
const wanted = new Set<string>(EVENT_ENVELOPE_TYPE_NAMES)
|
||||
for (const rel of globSync('packages/*/*/src/**/*.{ts,tsx}', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
|
||||
const abs = resolve(scanRoot, rel)
|
||||
const text = readFileSync(abs, 'utf8')
|
||||
if (!EVENT_ENVELOPE_TYPE_NAMES.some(name => text.includes(name))) continue
|
||||
if (packageNameFor(rel, scanRoot) !== SESSION_PACKAGE) continue
|
||||
const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
|
||||
for (const stmt of sf.statements) {
|
||||
if (!ts.isTypeAliasDeclaration(stmt) || !wanted.has(stmt.name.text)) continue
|
||||
const name = stmt.name.text as EventEnvelopeTypeName
|
||||
const src = pointer(rel, sf, stmt)
|
||||
const where = `event-envelope type '${name}' (${src})`
|
||||
const prior = found.get(name)
|
||||
if (prior) {
|
||||
violations.push(`${where} is already declared at ${prior.source}; the persisted envelope type has exactly one owner.`)
|
||||
continue
|
||||
}
|
||||
if (!(stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false)) {
|
||||
violations.push(`${where} is not exported.`)
|
||||
}
|
||||
const { doc, hasMode } = parseJsDoc(rawJsDoc(text, stmt))
|
||||
if (hasMode) violations.push(`${where} carries an @mode tag, but a persisted type has no dispatch mode.`)
|
||||
if (!doc) violations.push(`${where} has no description prose. The full JSDoc is part of the generated catalog.`)
|
||||
found.set(name, { name, declaration: declarationText(text, sf, stmt), source: src })
|
||||
}
|
||||
}
|
||||
const missing = EVENT_ENVELOPE_TYPE_NAMES.filter(name => !found.has(name))
|
||||
if (missing.length > 0) {
|
||||
violations.push(`missing event-envelope declaration(s): ${missing.join(', ')}.`)
|
||||
}
|
||||
reportViolations('gen-persistence-catalog', violations)
|
||||
return EVENT_ENVELOPE_TYPE_NAMES.map((name) => {
|
||||
const entry = found.get(name)
|
||||
if (!entry) throw new Error(`gen-persistence-catalog: missing checked event-envelope declaration '${name}'.`)
|
||||
return entry
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse the `SurfaceEventType` union — the surface-eligible subset of event
|
||||
* types — from source. Hard-errors when the alias is missing, declared more
|
||||
* than once, or contains a non-string-literal member: the badge derivation
|
||||
* relies on the union being a closed set of literal event names.
|
||||
* `scanRoot` defaults to the repo root; tests pass a fixture dir.
|
||||
*/
|
||||
export function collectSurfaceEventTypes(scanRoot: string = root): string[] {
|
||||
const found: { names: string[]; source: string }[] = []
|
||||
for (const rel of globSync('packages/*/*/src/**/*.{ts,tsx}', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
|
||||
const abs = resolve(scanRoot, rel)
|
||||
const text = readFileSync(abs, 'utf8')
|
||||
if (!text.includes('SurfaceEventType')) continue
|
||||
const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
|
||||
for (const stmt of sf.statements) {
|
||||
if (!ts.isTypeAliasDeclaration(stmt) || stmt.name.text !== 'SurfaceEventType') continue
|
||||
const src = pointer(rel, sf, stmt)
|
||||
const members = ts.isUnionTypeNode(stmt.type) ? [...stmt.type.types] : [stmt.type]
|
||||
const names: string[] = []
|
||||
for (const m of members) {
|
||||
if (ts.isLiteralTypeNode(m) && ts.isStringLiteral(m.literal)) names.push(m.literal.text)
|
||||
else throw new Error(`gen-persistence-catalog: SurfaceEventType (${src}) has a non-string-literal member; the badge derivation needs a closed literal union.`)
|
||||
}
|
||||
found.push({ names, source: src })
|
||||
}
|
||||
}
|
||||
const only = found[0]
|
||||
if (!only) throw new Error('gen-persistence-catalog: no SurfaceEventType union found under packages/*/*/src.')
|
||||
if (found.length > 1) throw new Error(`gen-persistence-catalog: SurfaceEventType is declared more than once (${found.map(f => f.source).join(', ')}); the surface subset has exactly one owner.`)
|
||||
return only.names
|
||||
}
|
||||
|
||||
/**
|
||||
* Attach the surface/log-only badge to each event. Hard-errors when a
|
||||
* `SurfaceEventType` union member names no collected event — a stale union
|
||||
* member would otherwise silently badge nothing.
|
||||
*/
|
||||
export function annotateSurface(events: LogEventEntry[], surfaceTypes: string[]): AnnotatedLogEventEntry[] {
|
||||
const names = new Set(events.map(e => e.name))
|
||||
const stale = surfaceTypes.filter(t => !names.has(t))
|
||||
if (stale.length > 0) {
|
||||
throw new Error(`gen-persistence-catalog: SurfaceEventType member(s) ${stale.map(t => `'${t}'`).join(', ')} name no declared log event (stale union member?).`)
|
||||
}
|
||||
const surface = new Set(surfaceTypes)
|
||||
for (const event of events) {
|
||||
if (event.messageProjection && surface.has(event.name)) {
|
||||
throw new Error(`gen-persistence-catalog: '${event.name}' cannot declare both a message projection and surface operations.`)
|
||||
}
|
||||
}
|
||||
return events.map(e => ({ ...e, surface: surface.has(e.name) }))
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
/** Authored language pairs for generated persistence reference prose. */
|
||||
|
||||
/** Language of a generated persistence reference. */
|
||||
export type PersistenceCatalogLocale = 'en' | 'zh'
|
||||
|
||||
const english = {
|
||||
title: 'Session Persistence Event Catalog',
|
||||
intro: 'Every repository-declared durable Session event appears here with its source declaration and resolved types. The catalog covers the logical and physical headers, event envelopes, and every plugin declaration merge. See [Session](subsystems/session.md) for replay and [persistence](subsystems/persistence.md) for storage.',
|
||||
generation: 'Run `pnpm run gen-persistence-catalog` to regenerate both catalog languages, their pairing record, the known-event module, and the machine schema inventory. `pnpm run verify-persistence-catalog` checks all generated files. Declaration fences preserve source JSDoc and type references; resolved definitions expose their transitive structure.',
|
||||
envelopeIntro: 'The envelope carries `type`, `seq`, `time`, `data`, optional `ignorable`, and conditional `surfaceOp` / `sourceEventSeqs`. A **surface** event produces model history; a **log-only** event does not. The inventory covers this repository; external plugin types require their own declarations and are outside this catalog.',
|
||||
envelope: 'Event envelope', events: 'Events', sources: 'Sources: ', source: 'Source: ', types: 'Types: ',
|
||||
fingerprints: 'Persistence type fingerprints',
|
||||
fingerprintsIntro: 'The [machine inventory](persistence-schema.json) contains every reachable normalized type and its SHA-256 digest. Root digests include referenced types. Comments, source locations, alias names, erased brands, readonly markers, and harmless field, union, or intersection reordering do not affect these fingerprints. Tuple order, property names, value types, and optionality do. Catalog text and source locations can still produce a diff when digests stay unchanged.',
|
||||
historyIntro: 'The [format references](persistence-changes/historical-formats/README.md) cover every historical Session format. The [change records](persistence-changes/README.md) acknowledge exact transitions using snapshots kept in this tree. Follow the [review workflow](cookbook/reviewing-persistence-type-changes.md) to classify a change and record it. These checks cover declared type structure; opaque payload contents and behavior without type changes are outside their scope.',
|
||||
rootColumns: '| Root | Kind | SHA-256 | Resolved type |',
|
||||
definitions: 'Resolved persistence types',
|
||||
definitionsIntro: 'Each definition appears once. References preserve sharing and recursion; the digest beside a definition includes its complete reachable structure. Source names and locations identify its declarations but are excluded from its digest.',
|
||||
propertyColumns: '| Property | Presence | Type |', positionColumns: '| Position | Presence | Type |',
|
||||
optional: 'optional', required: 'required', rest: 'rest', index: 'index signature',
|
||||
emptyObject: 'Object with no declared properties.', arrayPrefix: 'Array of ', arraySuffix: '.',
|
||||
oneOf: 'One of:', opaque: ' (opaque)', opaqueExplanation: ": the declaration does not expose the stored value's internal fields.",
|
||||
}
|
||||
|
||||
const chinese: Record<keyof typeof english, string> = {
|
||||
title: '会话持久化事件目录',
|
||||
intro: '本目录列出仓库声明的每个持久化 Session 事件及其源码声明和解析类型,覆盖逻辑与物理 header、事件信封以及各插件的声明合并。回放规则参见 [Session](subsystems/session.zh.md),存储规则参见[持久化](subsystems/persistence.zh.md)。',
|
||||
generation: '运行 `pnpm run gen-persistence-catalog` 可重新生成目录的两种语言、配对记录、已知事件模块和机器 schema 目录。`pnpm run verify-persistence-catalog` 检查所有生成文件。声明围栏保留源码 JSDoc 和类型引用;解析后的定义展开其传递引用结构。',
|
||||
envelopeIntro: '信封包含 `type`、`seq`、`time`、`data`、可选的 `ignorable` 以及条件字段 `surfaceOp` / `sourceEventSeqs`。**surface** 事件产生模型历史,**log-only** 事件不产生模型历史。目录覆盖本仓库;外部插件类型需要独立声明,不属于本目录。',
|
||||
envelope: '事件信封', events: '事件', sources: '来源:', source: '来源:', types: '类型:',
|
||||
fingerprints: '持久化类型指纹',
|
||||
fingerprintsIntro: '[机器可读目录](persistence-schema.json)包含所有可达的规范化类型及其 SHA-256 摘要。根类型的摘要涵盖引用类型。注释、源码位置、别名、擦除的品牌标记、readonly 标记以及无语义变化的字段、联合类型或交叉类型重排不影响摘要;元组顺序、属性名称、值类型和可选性会影响摘要。摘要不变时,目录文本和源码位置仍可能产生 diff。',
|
||||
historyIntro: '[格式参考](persistence-changes/historical-formats/README.zh.md)覆盖每个历史 Session 格式。[变更记录](persistence-changes/README.zh.md)通过保存在本源码树中的快照确认精确的类型转换。按照[评审流程](cookbook/reviewing-persistence-type-changes.zh.md)分类并记录变更。这些检查覆盖已声明的类型结构;不透明载荷的内部内容和未改变类型的行为变更不在检查范围内。',
|
||||
rootColumns: '| 根类型 | 类别 | SHA-256 | 已解析类型 |',
|
||||
definitions: '已解析的持久化类型',
|
||||
definitionsIntro: '每个类型定义仅列出一次。引用保留共享和递归关系;定义旁的摘要涵盖其完整可达结构。源码名称和位置标识声明来源,但不参与摘要计算。',
|
||||
propertyColumns: '| 属性 | 存在性 | 类型 |', positionColumns: '| 位置 | 存在性 | 类型 |',
|
||||
optional: '可选', required: '必需', rest: '剩余项', index: '索引签名',
|
||||
emptyObject: '无已声明属性的对象。', arrayPrefix: '', arraySuffix: ' 的数组。',
|
||||
oneOf: '以下类型之一:', opaque: '(不透明)', opaqueExplanation: ':此声明未暴露存储值的内部字段。',
|
||||
}
|
||||
|
||||
/** Complete translated prose; adding an English key requires its Chinese counterpart. */
|
||||
export const persistenceCatalogText = { en: english, zh: chinese }
|
||||
@@ -0,0 +1,611 @@
|
||||
/** Current-tree persistence history rejects uncovered and incorrectly acknowledged type changes. */
|
||||
|
||||
import { spawnSync } from 'node:child_process'
|
||||
import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { join, resolve } from 'node:path'
|
||||
import { afterEach, describe, expect, it } from 'vitest'
|
||||
import { canonicalizeSchema, schemaDigest } from './persistence-schema-model.ts'
|
||||
import type { PersistenceRoot, PersistenceSchemaInventory, SchemaNode, SchemaProperty } from './persistence-schema-model.ts'
|
||||
import { extractPersistenceSchema } from './persistence-schema.ts'
|
||||
import { persistenceCatalogArtifacts } from './gen-persistence-catalog.ts'
|
||||
import {
|
||||
classifyPersistenceChange,
|
||||
loadPersistenceHistory,
|
||||
parseHistoricalPersistenceSnapshot,
|
||||
parsePersistenceSnapshot,
|
||||
runPersistenceChanges as executePersistenceChanges,
|
||||
validatePersistenceHistory,
|
||||
verifyPersistenceChanges,
|
||||
} from './persistence-changes.ts'
|
||||
import type { PersistenceChangeRecord, PersistenceHistoryEntry } from './persistence-changes.ts'
|
||||
|
||||
function runPersistenceChanges(
|
||||
args: readonly string[], root: string, extract: (root: string) => PersistenceSchemaInventory,
|
||||
): string {
|
||||
return executePersistenceChanges(args, root, extract, (_root, current) => [{
|
||||
path: 'docs/persistence-schema.json', content: JSON.stringify(current, null, 2) + '\n',
|
||||
}])
|
||||
}
|
||||
|
||||
function jsonResult(source: string): { ok: boolean; files: readonly string[] } {
|
||||
return JSON.parse(source) as { ok: boolean; files: readonly string[] }
|
||||
}
|
||||
|
||||
const AUTHORED_PROSE = {
|
||||
en: { summary: 'Adds optional metadata.', compatibility: 'Readers may omit the metadata.', verification: 'The focused tests passed.' },
|
||||
zh: { summary: '添加可选元数据。', compatibility: '读取方可省略元数据。', verification: '定向测试通过。' },
|
||||
}
|
||||
|
||||
function proseFile(root: string): string {
|
||||
const path = join(root, 'prose.json')
|
||||
writeFileSync(path, JSON.stringify(AUTHORED_PROSE))
|
||||
return path
|
||||
}
|
||||
|
||||
const roots: string[] = []
|
||||
afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }) })
|
||||
|
||||
function fixture(): string {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-persistence-changes-'))
|
||||
roots.push(root)
|
||||
mkdirSync(join(root, 'docs/persistence-changes'), { recursive: true })
|
||||
return root
|
||||
}
|
||||
|
||||
type Shape = 'string' | 'number' | 'boolean' | { readonly [property: string]: Shape }
|
||||
|
||||
function typeRoot(key: string, shape: Shape, version = 3): PersistenceRoot {
|
||||
const nodes: SchemaNode[] = []
|
||||
function add(shape: Shape): number {
|
||||
const index = nodes.length
|
||||
nodes.push({ kind: 'primitive', type: 'never' })
|
||||
nodes[index] = typeof shape === 'string' ? { kind: 'primitive', type: shape } : {
|
||||
kind: 'object', indices: [], properties: Object.entries(shape).map(([name, child]) => ({
|
||||
name: name.replace(/\?$/u, ''), optional: name.endsWith('?'), type: add(child),
|
||||
})),
|
||||
}
|
||||
return index
|
||||
}
|
||||
if (key === 'SessionHeader') {
|
||||
const index = add(shape)
|
||||
const node = nodes[index]!
|
||||
if (node.kind !== 'object') throw new Error('header fixture requires an object')
|
||||
nodes[index] = { ...node, properties: [...node.properties, { name: 'version', optional: false, type: nodes.length }] }
|
||||
nodes.push({ kind: 'literal', value: version })
|
||||
} else if (key.startsWith('event:')) {
|
||||
add({ data: shape, type: 'string' })
|
||||
const node = nodes[0]!
|
||||
if (node.kind !== 'object') throw new Error('event fixture requires an object')
|
||||
const type = node.properties.find(item => item.name === 'type')!.type
|
||||
nodes[type] = { kind: 'literal', value: key.slice(6) }
|
||||
} else add(shape)
|
||||
const schema = canonicalizeSchema(nodes, 0)
|
||||
return { key, kind: ['SessionHeader', 'JsonlHeaderLine'].includes(key) ? 'header' : key === 'SessionEventEnvelope' ? 'envelope' : 'event',
|
||||
...(key.startsWith('event:') ? { event: key.slice(6), surface: false } : {}), schema, digest: schemaDigest(schema) }
|
||||
}
|
||||
|
||||
function inventory(eventShape: Shape = { value: 'string' }, version = 3): PersistenceSchemaInventory {
|
||||
return { formatVersion: 1, types: [], roots: [typeRoot('SessionHeader', { id: 'string' }, version), typeRoot('SessionEventEnvelope', { type: 'string' }), typeRoot('event:example/value', eventShape), typeRoot('JsonlHeaderLine', { version: 'number' })] }
|
||||
}
|
||||
|
||||
function entry(
|
||||
id: string, schema: PersistenceSchemaInventory, previous: string | null,
|
||||
baseline = false, decision: 'same-version' | 'version-bump' = 'same-version',
|
||||
): PersistenceHistoryEntry {
|
||||
return {
|
||||
record: { schemaVersion: 1, id, baseline, changes: schema.roots.map(root => ({
|
||||
root: root.key, previous, after: root.digest, decision,
|
||||
})) },
|
||||
snapshot: schema,
|
||||
}
|
||||
}
|
||||
|
||||
const BASE_ID = '2026-09-11-baseline'
|
||||
const NEXT_ID = '2026-09-11-change'
|
||||
|
||||
function historicalSurface(operation: 'required' | 'optional' | 'absent', event = 'example/value'): PersistenceSchemaInventory {
|
||||
const nodes: SchemaNode[] = [
|
||||
{ kind: 'object', indices: [], properties: [
|
||||
{ name: 'type', type: 1, optional: false },
|
||||
...(operation === 'absent' ? [] : [{ name: 'surfaceOp', type: 2, optional: operation === 'optional' }]),
|
||||
] },
|
||||
{ kind: 'literal', value: event },
|
||||
{ kind: 'primitive', type: 'string' },
|
||||
]
|
||||
const schema = canonicalizeSchema(nodes, 0)
|
||||
return { formatVersion: 1, types: [], roots: [{
|
||||
key: 'event:example/value', kind: 'event', event: 'example/value', surface: true, schema, digest: schemaDigest(schema),
|
||||
}] }
|
||||
}
|
||||
|
||||
describe('historical persistence snapshot parsing', () => {
|
||||
it('preserves source paths and fingerprints in historical inventories', () => {
|
||||
const snapshot = historicalSurface('required')
|
||||
const root = snapshot.roots[0]!
|
||||
const sources = ['packages/core/example/src/types.ts']
|
||||
const complete = { ...snapshot, types: [{ schema: root.schema, digest: root.digest, names: ['Example'], sources }] }
|
||||
expect(parseHistoricalPersistenceSnapshot(complete)).toEqual(complete)
|
||||
})
|
||||
|
||||
it.each([':8', ':8:3', '#L8', '#L8-L12'])('rejects source coordinates %s only in historical inventories', (suffix) => {
|
||||
const snapshot = historicalSurface('required')
|
||||
const root = snapshot.roots[0]!
|
||||
const sources = [`packages/core/example/src/types.ts${suffix}`]
|
||||
const complete = { ...snapshot, types: [{ schema: root.schema, digest: root.digest, names: [], sources }] }
|
||||
expect(() => parseHistoricalPersistenceSnapshot(complete)).toThrow('historical schema sources must omit line numbers')
|
||||
expect(parsePersistenceSnapshot(complete)).toEqual(complete)
|
||||
})
|
||||
|
||||
it('admits optional surface operations only through the historical parser', () => {
|
||||
const snapshot = historicalSurface('optional')
|
||||
expect(() => parsePersistenceSnapshot(snapshot)).toThrow('surface metadata')
|
||||
expect(parseHistoricalPersistenceSnapshot(snapshot)).toEqual(snapshot)
|
||||
expect(parsePersistenceSnapshot(historicalSurface('required'))).toEqual(historicalSurface('required'))
|
||||
})
|
||||
|
||||
it('still rejects absent operations, mismatched event tags, and invalid roots', () => {
|
||||
expect(() => parseHistoricalPersistenceSnapshot(historicalSurface('absent'))).toThrow('surface metadata')
|
||||
expect(() => parseHistoricalPersistenceSnapshot(historicalSurface('optional', 'wrong/tag'))).toThrow('type does not match')
|
||||
const snapshot = historicalSurface('optional')
|
||||
expect(() => parseHistoricalPersistenceSnapshot({ ...snapshot, roots: snapshot.roots.map(root => ({ ...root, key: 'event:wrong/key' })) })).toThrow('invalid event root key')
|
||||
expect(() => parseHistoricalPersistenceSnapshot({ ...snapshot, roots: snapshot.roots.map(root => ({ ...root, surface: false })) })).toThrow('surface metadata')
|
||||
})
|
||||
|
||||
it('preserves graph and digest validation in historical mode', () => {
|
||||
const snapshot = historicalSurface('optional')
|
||||
expect(() => parseHistoricalPersistenceSnapshot({ ...snapshot, roots: snapshot.roots.map(root => ({ ...root, digest: 'f'.repeat(64) })) })).toThrow('digest mismatch')
|
||||
expect(() => parseHistoricalPersistenceSnapshot({ ...snapshot, roots: snapshot.roots.map(root => ({ ...root, schema: { root: 0, nodes: [{ kind: 'array', element: 9 }] } })) })).toThrow('unknown schema node')
|
||||
})
|
||||
})
|
||||
|
||||
function onlyEvent(schema: PersistenceSchemaInventory): PersistenceSchemaInventory {
|
||||
return { ...schema, roots: schema.roots.filter(root => root.kind === 'event') }
|
||||
}
|
||||
|
||||
function finishDocuments(root: string, id: string): void {
|
||||
for (const suffix of ['.md', '.zh.md']) {
|
||||
const path = join(root, 'docs/persistence-changes', id + suffix)
|
||||
writeFileSync(path, readFileSync(path, 'utf8').replaceAll('TODO: explain this change.', 'Optional payload metadata preserves the recorded value.')
|
||||
.replaceAll('TODO: record validation evidence.', 'The focused persistence-history tests passed.'))
|
||||
}
|
||||
}
|
||||
|
||||
function commitCurrent(root: string, schema: PersistenceSchemaInventory): void {
|
||||
writeFileSync(join(root, 'docs/persistence-schema.json'), JSON.stringify(schema, null, 2) + '\n')
|
||||
}
|
||||
|
||||
function baseline(root: string, schema = inventory()): void {
|
||||
runPersistenceChanges(['--baseline', BASE_ID], root, () => schema)
|
||||
finishDocuments(root, BASE_ID)
|
||||
commitCurrent(root, schema)
|
||||
}
|
||||
|
||||
function unionBody(arms: readonly (readonly SchemaProperty[])[]): PersistenceRoot {
|
||||
const nodes: SchemaNode[] = [
|
||||
{ kind: 'object', indices: [], properties: [{ name: 'data', type: 1, optional: false }] },
|
||||
{ kind: 'union', types: arms.map((_, index) => 5 + index) },
|
||||
{ kind: 'primitive', type: 'string' },
|
||||
{ kind: 'primitive', type: 'number' },
|
||||
{ kind: 'primitive', type: 'boolean' },
|
||||
...arms.map(properties => ({ kind: 'object' as const, indices: [], properties })),
|
||||
]
|
||||
const schema = canonicalizeSchema(nodes, 0)
|
||||
return { ...typeRoot('event:example/value', {}), schema, digest: schemaDigest(schema) }
|
||||
}
|
||||
|
||||
describe('persistence change classification', () => {
|
||||
it('treats a new optional payload subtree as one additive change even with required descendants', () => {
|
||||
const before = typeRoot('event:example/value', { value: 'string' })
|
||||
const after = typeRoot('event:example/value', { value: 'string', 'details?': { name: 'string', count: 'number' } })
|
||||
expect(classifyPersistenceChange(before, after)).toEqual([{ path: 'event:example/value.data.details', kind: 'optional-property-added', description: 'optional property added', requiresVersionBump: false }])
|
||||
})
|
||||
|
||||
it('permits required-to-optional payload properties while rejecting opposite changes, type changes, and removals', () => {
|
||||
const required = typeRoot('event:example/value', { value: 'string' })
|
||||
const optional = typeRoot('event:example/value', { 'value?': 'string' })
|
||||
expect(classifyPersistenceChange(required, optional).every(change => !change.requiresVersionBump)).toBe(true)
|
||||
for (const after of [required, typeRoot('event:example/value', { 'value?': 'number' }), typeRoot('event:example/value', {})]) {
|
||||
expect(classifyPersistenceChange(optional, after).some(change => change.requiresVersionBump)).toBe(true)
|
||||
}
|
||||
})
|
||||
|
||||
it('pairs multiple discriminated union arms when a shared payload gains an optional property', () => {
|
||||
function unionRoot(optional: boolean): PersistenceRoot {
|
||||
const nodes: SchemaNode[] = [
|
||||
{ kind: 'object', indices: [], properties: [{ name: 'data', type: 1, optional: false }] },
|
||||
{ kind: 'union', types: [2, 3] },
|
||||
{ kind: 'object', indices: [], properties: [{ name: 'kind', type: 4, optional: false }, { name: 'payload', type: 6, optional: false }] },
|
||||
{ kind: 'object', indices: [], properties: [{ name: 'kind', type: 5, optional: false }, { name: 'payload', type: 6, optional: false }] },
|
||||
{ kind: 'literal', value: 'left' }, { kind: 'literal', value: 'right' },
|
||||
{ kind: 'object', indices: [], properties: [{ name: 'value', type: 7, optional: false }, ...(optional ? [{ name: 'label', type: 7, optional: true }] : [])] },
|
||||
{ kind: 'primitive', type: 'string' },
|
||||
]
|
||||
const schema = canonicalizeSchema(nodes, 0)
|
||||
return { ...typeRoot('event:example/value', {}), schema, digest: schemaDigest(schema) }
|
||||
}
|
||||
const differences = classifyPersistenceChange(unionRoot(false), unionRoot(true))
|
||||
expect(differences.length).toBeGreaterThan(0)
|
||||
expect(differences.every(change => !change.requiresVersionBump)).toBe(true)
|
||||
})
|
||||
|
||||
it('allows optional additions across undiscriminated union arms', () => {
|
||||
const first = [{ name: 'a', type: 2, optional: false }]
|
||||
const second = [{ name: 'b', type: 3, optional: false }]
|
||||
const extra = { name: 'x', type: 4, optional: true }
|
||||
const differences = classifyPersistenceChange(unionBody([first, second]), unionBody([[...first, extra], [...second, extra]]))
|
||||
expect(differences).toEqual([expect.objectContaining({ path: 'event:example/value.data.x', requiresVersionBump: false })])
|
||||
})
|
||||
|
||||
it('allows required-to-optional fields across undiscriminated union arms', () => {
|
||||
const before = unionBody([[{ name: 'a', type: 2, optional: false }], [{ name: 'b', type: 3, optional: false }]])
|
||||
const after = unionBody([[{ name: 'a', type: 2, optional: true }], [{ name: 'b', type: 3, optional: true }]])
|
||||
const differences = classifyPersistenceChange(before, after)
|
||||
expect(differences.map(change => change.path).sort()).toEqual(['event:example/value.data.a', 'event:example/value.data.b'])
|
||||
expect(differences.every(change => change.kind === 'property-made-optional' && !change.requiresVersionBump)).toBe(true)
|
||||
})
|
||||
|
||||
it('finds a complete matching when one union arm has multiple additive successors', () => {
|
||||
const required = [{ name: 'a', type: 2, optional: false }]
|
||||
const optional = [{ name: 'a', type: 2, optional: true }]
|
||||
const flexible = [{ name: '0', type: 4, optional: true }, ...optional]
|
||||
const constrained = [...required, { name: 'z', type: 4, optional: true }]
|
||||
const before = unionBody([required, optional])
|
||||
for (const after of [unionBody([flexible, constrained]), unionBody([constrained, flexible])]) {
|
||||
const differences = classifyPersistenceChange(before, after)
|
||||
expect(differences.length).toBeGreaterThan(0)
|
||||
expect(differences.every(change => !change.requiresVersionBump)).toBe(true)
|
||||
}
|
||||
const noCompleteMatching = unionBody([flexible, [{ name: 'different', type: 4, optional: true }]])
|
||||
expect(classifyPersistenceChange(before, noCompleteMatching).some(change => change.requiresVersionBump)).toBe(true)
|
||||
})
|
||||
|
||||
it('keeps union cardinality, property removal, new required fields, and value types strict', () => {
|
||||
const first = [{ name: 'a', type: 2, optional: false }]
|
||||
const second = [{ name: 'b', type: 3, optional: false }]
|
||||
const third = [{ name: 'c', type: 4, optional: false }]
|
||||
const before = unionBody([first, second])
|
||||
const variants = [
|
||||
unionBody([first, second, third]),
|
||||
unionBody([first]),
|
||||
unionBody([first, third]),
|
||||
unionBody([[...first, { name: 'x', type: 4, optional: false }], [...second, { name: 'x', type: 4, optional: true }]]),
|
||||
unionBody([[{ name: 'a', type: 3, optional: true }], [{ name: 'b', type: 3, optional: true }]]),
|
||||
]
|
||||
for (const after of variants) expect(classifyPersistenceChange(before, after).some(change => change.requiresVersionBump)).toBe(true)
|
||||
})
|
||||
|
||||
it('checks all recursive union arms without retaining provisional successes between candidates', () => {
|
||||
const next = { name: 'next', type: 1, optional: true }
|
||||
const first = [{ name: 'a', type: 2, optional: false }, next]
|
||||
const second = [{ name: 'b', type: 3, optional: false }, next]
|
||||
const extra = { name: 'x', type: 4, optional: true }
|
||||
const before = unionBody([first, second])
|
||||
const additive = unionBody([[...first, extra], [...second, extra]])
|
||||
expect(classifyPersistenceChange(before, additive).every(change => !change.requiresVersionBump)).toBe(true)
|
||||
const invalid = unionBody([[...first, extra], [{ name: 'b', type: 2, optional: false }, next, extra]])
|
||||
expect(classifyPersistenceChange(before, invalid).some(change => change.requiresVersionBump)).toBe(true)
|
||||
expect(classifyPersistenceChange(invalid, before).some(change => change.requiresVersionBump)).toBe(true)
|
||||
})
|
||||
|
||||
it('preserves body scope through arrays and tuples and rejects a simultaneous value-type change', () => {
|
||||
function wrapped(optional: boolean, primitive: 'string' | 'number' = 'string'): PersistenceRoot {
|
||||
const nodes: SchemaNode[] = [
|
||||
{ kind: 'object', indices: [], properties: [{ name: 'data', type: 1, optional: false }] },
|
||||
{ kind: 'tuple', elements: [{ type: 2, optional: false, rest: false }] },
|
||||
{ kind: 'array', element: 3 },
|
||||
{ kind: 'object', indices: [], properties: [{ name: 'value', type: 4, optional }] },
|
||||
{ kind: 'primitive', type: primitive },
|
||||
]
|
||||
const schema = canonicalizeSchema(nodes, 0)
|
||||
return { ...typeRoot('event:example/value', {}), schema, digest: schemaDigest(schema) }
|
||||
}
|
||||
expect(classifyPersistenceChange(wrapped(false), wrapped(true)).every(change => !change.requiresVersionBump)).toBe(true)
|
||||
expect(classifyPersistenceChange(wrapped(false), wrapped(true, 'number')).some(change => change.requiresVersionBump)).toBe(true)
|
||||
})
|
||||
|
||||
it('keeps optional header/envelope properties and surface event additions strict', () => {
|
||||
for (const key of ['SessionHeader', 'JsonlHeaderLine', 'SessionEventEnvelope']) {
|
||||
expect(classifyPersistenceChange(typeRoot(key, {}), typeRoot(key, { 'metadata?': 'string' }))[0]?.requiresVersionBump).toBe(true)
|
||||
}
|
||||
const added = typeRoot('event:example/added', { value: 'string' })
|
||||
expect(classifyPersistenceChange(null, added)[0]?.requiresVersionBump).toBe(false)
|
||||
expect(classifyPersistenceChange(null, { ...added, surface: true })[0]?.requiresVersionBump).toBe(true)
|
||||
expect(classifyPersistenceChange(added, null)[0]?.requiresVersionBump).toBe(true)
|
||||
})
|
||||
})
|
||||
|
||||
describe('persistence history verification', () => {
|
||||
it('accepts a baseline and a successive optional addition without comparing the historical schema to current', () => {
|
||||
const before = inventory()
|
||||
const after = inventory({ value: 'string', 'label?': 'string' })
|
||||
const history = validatePersistenceHistory([entry(BASE_ID, before, null, true), entry(NEXT_ID, onlyEvent(after), BASE_ID)])
|
||||
expect(history.tips.get('event:example/value')?.root?.digest).toBe(after.roots[2]?.digest)
|
||||
expect(history.tips.get('SessionHeader')?.id).toBe(BASE_ID)
|
||||
})
|
||||
|
||||
it('rejects missing predecessors, forks, cycles, duplicates, and missing baseline', () => {
|
||||
const base = entry(BASE_ID, inventory(), null, true)
|
||||
const next = entry(NEXT_ID, onlyEvent(inventory({ value: 'string', 'label?': 'string' })), BASE_ID)
|
||||
expect(() => validatePersistenceHistory([next])).toThrow('exactly one baseline')
|
||||
expect(() => validatePersistenceHistory([base, entry(NEXT_ID, next.snapshot, '2026-09-11-missing')])).toThrow('missing predecessor')
|
||||
expect(() => validatePersistenceHistory([base, next, entry('2026-09-11-fork', next.snapshot, BASE_ID)])).toThrow('forked')
|
||||
expect(() => validatePersistenceHistory([base, base])).toThrow('exactly one baseline')
|
||||
const cycle = entry('2026-09-11-cycle', { ...next.snapshot, roots: [typeRoot('event:cycle/event', {})] }, '2026-09-11-cycle')
|
||||
expect(() => validatePersistenceHistory([base, cycle])).toThrow('cycle')
|
||||
})
|
||||
|
||||
it('binds breaking decisions to the same record header version transition', () => {
|
||||
const base = entry(BASE_ID, inventory(), null, true)
|
||||
const breaking = inventory({ value: 'number' }, 4)
|
||||
expect(() => validatePersistenceHistory([base, entry(NEXT_ID, onlyEvent(breaking), BASE_ID)])).toThrow('requires a format version bump')
|
||||
expect(() => validatePersistenceHistory([base, entry(NEXT_ID, onlyEvent(breaking), BASE_ID, false, 'version-bump')])).toThrow("this record's own")
|
||||
const touched = { ...breaking, roots: breaking.roots.filter(root => root.key === 'SessionHeader' || root.kind === 'event') }
|
||||
expect(validatePersistenceHistory([base, entry(NEXT_ID, touched, BASE_ID, false, 'version-bump')]).tips.get('SessionHeader')?.id).toBe(NEXT_ID)
|
||||
const later = entry('2026-09-11-later', onlyEvent(inventory({ value: 'boolean' }, 4)), NEXT_ID, false, 'version-bump')
|
||||
expect(() => validatePersistenceHistory([base, entry(NEXT_ID, touched, BASE_ID, false, 'version-bump'), later])).toThrow("this record's own")
|
||||
})
|
||||
|
||||
it('retains deletion tombstones and requires re-added roots to continue them', () => {
|
||||
const base = entry(BASE_ID, inventory(), null, true)
|
||||
const after = inventory({}, 4)
|
||||
const header = after.roots[0]!
|
||||
const record: PersistenceChangeRecord = { schemaVersion: 1, id: NEXT_ID, baseline: false, changes: [
|
||||
{ root: 'SessionHeader', previous: BASE_ID, after: header.digest, decision: 'version-bump' },
|
||||
{ root: 'event:example/value', previous: BASE_ID, after: null, decision: 'version-bump' },
|
||||
] }
|
||||
const deletion = { record, snapshot: { ...after, roots: [header] } }
|
||||
expect(validatePersistenceHistory([base, deletion]).tips.get('event:example/value')?.root).toBeNull()
|
||||
const restored = entry('2026-09-11-restore', onlyEvent(inventory()), NEXT_ID)
|
||||
expect(validatePersistenceHistory([base, deletion, restored]).tips.get('event:example/value')?.id).toBe(restored.record.id)
|
||||
expect(() => validatePersistenceHistory([base, deletion, entry('2026-09-11-restore', restored.snapshot, null)])).toThrow('forked')
|
||||
})
|
||||
|
||||
it('rejects malformed references, unknown schema variants, digest tampering, and extra snapshot roots', () => {
|
||||
const schema = inventory()
|
||||
const malformed = structuredClone(schema) as unknown as { roots: Array<{ schema: { nodes: unknown[] }; digest: string }> }
|
||||
malformed.roots[0]!.schema.nodes = [{ kind: 'array', element: 99 }]
|
||||
expect(() => parsePersistenceSnapshot(malformed)).toThrow('unknown schema node')
|
||||
malformed.roots[0]!.schema.nodes = [{ kind: 'future' }]
|
||||
expect(() => parsePersistenceSnapshot(malformed)).toThrow('unknown schema node kind')
|
||||
const tampered = structuredClone(schema)
|
||||
Object.assign(tampered.roots[0]!, { digest: '0'.repeat(64) })
|
||||
expect(() => parsePersistenceSnapshot(tampered)).toThrow('digest mismatch')
|
||||
expect(() => parsePersistenceSnapshot({ ...schema, formatVersion: 2 })).toThrow('normalization version')
|
||||
const next = entry(NEXT_ID, onlyEvent(inventory({ value: 'string', 'label?': 'string' })), BASE_ID)
|
||||
expect(() => validatePersistenceHistory([entry(BASE_ID, schema, null, true), { ...next, snapshot: inventory() }])).toThrow('snapshot roots')
|
||||
})
|
||||
})
|
||||
|
||||
describe('persistence changes current-tree commands', () => {
|
||||
it('requires completed record prose, rejects stale generated output, and reports unacknowledged paths', () => {
|
||||
const root = fixture()
|
||||
const before = inventory()
|
||||
runPersistenceChanges(['--baseline', BASE_ID], root, () => before)
|
||||
expect(() => loadPersistenceHistory(root)).toThrow('complete compatibility')
|
||||
finishDocuments(root, BASE_ID)
|
||||
rmSync(join(root, 'docs/persistence-schema.json'))
|
||||
expect(() => verifyPersistenceChanges(root, before)).toThrow('is missing')
|
||||
commitCurrent(root, before)
|
||||
const after = inventory({ value: 'string', 'label?': 'string' })
|
||||
expect(() => verifyPersistenceChanges(root, after)).toThrow('is stale')
|
||||
commitCurrent(root, after)
|
||||
expect(() => verifyPersistenceChanges(root, after)).toThrow('event:example/value.data.label: optional property added (same-version allowed)')
|
||||
runPersistenceChanges(['--record', NEXT_ID, '--decision', 'same-version'], root, () => after)
|
||||
finishDocuments(root, NEXT_ID)
|
||||
expect(runPersistenceChanges([], root, () => after)).toContain('4 roots match 2 history records')
|
||||
expect(() => runPersistenceChanges(['--baseline', '2026-09-11-reset'], root, () => after)).toThrow('cannot reset history')
|
||||
expect(() => runPersistenceChanges(['--record', '2026-09-11-empty', '--decision', 'same-version'], root, () => after)).toThrow('no persistence type changes')
|
||||
})
|
||||
|
||||
it('rejects changed bilingual machine declarations and unreferenced snapshots', () => {
|
||||
const root = fixture()
|
||||
baseline(root)
|
||||
const chinese = join(root, 'docs/persistence-changes', `${BASE_ID}.zh.md`)
|
||||
const original = readFileSync(chinese, 'utf8')
|
||||
writeFileSync(chinese, original.replace('baseline: true', 'baseline: false'))
|
||||
expect(() => loadPersistenceHistory(root)).toThrow('bilingual machine records differ')
|
||||
writeFileSync(chinese, original)
|
||||
writeFileSync(join(root, 'docs/persistence-changes/2026-09-11-orphan.schema.json'), '{}\n')
|
||||
expect(() => loadPersistenceHistory(root)).toThrow('unreferenced')
|
||||
})
|
||||
|
||||
it('excludes nested historical format documents and schemas from acknowledgements', () => {
|
||||
const root = fixture()
|
||||
baseline(root)
|
||||
const directory = join(root, 'docs/persistence-changes/historical-formats')
|
||||
mkdirSync(directory)
|
||||
writeFileSync(join(directory, 'v0.md'), '---\nkind: persistence-format\n---\n')
|
||||
writeFileSync(join(directory, 'v0.schema.json'), '{}\n')
|
||||
expect(loadPersistenceHistory(root).entries.map(entry => entry.record.id)).toEqual([BASE_ID])
|
||||
})
|
||||
|
||||
it.each([
|
||||
['optional field', inventory({ value: 'string', 'label?': 'string' })],
|
||||
['required-to-optional field', inventory({ 'value?': 'string' })],
|
||||
['ordinary event addition', { ...inventory(), roots: [...inventory().roots, typeRoot('event:example/added', { count: 'number' })] }],
|
||||
] as const)('infers same-version for %s', (_name, after) => {
|
||||
const root = fixture()
|
||||
baseline(root)
|
||||
runPersistenceChanges(['--record', NEXT_ID, '--prose', proseFile(root)], root, () => after)
|
||||
const changes = loadPersistenceHistory(root).entries.find(entry => entry.record.id === NEXT_ID)?.record.changes
|
||||
expect(changes?.length).toBeGreaterThan(0)
|
||||
expect(changes?.every(change => change.decision === 'same-version')).toBe(true)
|
||||
verifyPersistenceChanges(root, after)
|
||||
})
|
||||
|
||||
it('infers a version bump when the source includes its own increasing header version', () => {
|
||||
const root = fixture()
|
||||
baseline(root)
|
||||
const after = inventory({ value: 'number' }, 4)
|
||||
runPersistenceChanges(['--record', NEXT_ID, '--prose', proseFile(root)], root, () => after)
|
||||
const changes = loadPersistenceHistory(root).entries.find(entry => entry.record.id === NEXT_ID)?.record.changes
|
||||
expect(changes?.map(change => change.root).sort()).toEqual(['SessionHeader', 'event:example/value'])
|
||||
expect(changes?.every(change => change.decision === 'version-bump')).toBe(true)
|
||||
verifyPersistenceChanges(root, after)
|
||||
})
|
||||
|
||||
it('rejects inferred bumps without a header transition and explicit incorrect assertions before writing', () => {
|
||||
const root = fixture()
|
||||
baseline(root)
|
||||
const prose = proseFile(root)
|
||||
const directory = join(root, 'docs/persistence-changes')
|
||||
const files = readdirSync(directory).sort()
|
||||
const inventoryPath = join(root, 'docs/persistence-schema.json')
|
||||
const before = readFileSync(inventoryPath, 'utf8')
|
||||
for (const [args, code] of [
|
||||
[[], 'version-transition-required'],
|
||||
[['--decision', 'same-version'], 'version-bump-required'],
|
||||
] as const) {
|
||||
const result = jsonResult(runPersistenceChanges(['--record', NEXT_ID, '--prose', prose, '--json', ...args], root,
|
||||
() => inventory({ value: 'number' })))
|
||||
expect(result).toMatchObject({ ok: false, code, files: [], changes: [expect.objectContaining({ requiresVersionBump: true })] })
|
||||
expect(readFileSync(inventoryPath, 'utf8')).toBe(before)
|
||||
expect(readdirSync(directory).sort()).toEqual(files)
|
||||
}
|
||||
})
|
||||
|
||||
it('authors a complete pair from explicit prose and reports source changes even when generated artifacts are stale', () => {
|
||||
const root = fixture()
|
||||
baseline(root)
|
||||
const after = inventory({ value: 'string', 'label?': 'string' })
|
||||
const pending = jsonResult(runPersistenceChanges(['--check', '--json'], root, () => after))
|
||||
expect(pending).toMatchObject({ ok: false, operation: 'check', code: 'stale-artifacts',
|
||||
roots: [{ root: 'event:example/value', kind: 'event', before: inventory().roots[2]?.digest, after: after.roots[2]?.digest }], changes: [
|
||||
{ root: 'event:example/value', path: 'event:example/value.data.label', kind: 'optional-property-added', requiresVersionBump: false },
|
||||
] })
|
||||
const written = jsonResult(runPersistenceChanges(['--record', NEXT_ID, '--decision', 'same-version', '--prose', proseFile(root), '--json'], root, () => after))
|
||||
expect(written).toMatchObject({ ok: true, operation: 'record', recordId: NEXT_ID })
|
||||
expect(written.files).toEqual([
|
||||
'docs/persistence-schema.json', `docs/persistence-changes/${NEXT_ID}.md`, `docs/persistence-changes/${NEXT_ID}.zh.md`,
|
||||
`docs/persistence-changes/${NEXT_ID}.i18n.yaml`, `docs/persistence-changes/${NEXT_ID}.schema.json`,
|
||||
])
|
||||
expect(written).toMatchObject({ roots: [{ root: 'event:example/value', kind: 'event',
|
||||
before: inventory().roots[2]?.digest, after: after.roots[2]?.digest }] })
|
||||
expect(readFileSync(join(root, `docs/persistence-changes/${NEXT_ID}.md`), 'utf8')).toContain(AUTHORED_PROSE.en.compatibility)
|
||||
expect(jsonResult(runPersistenceChanges(['--check', '--json'], root, () => after)).ok).toBe(true)
|
||||
})
|
||||
|
||||
it('refreshes only a terminal acknowledgement while preserving its authored prose and predecessor', () => {
|
||||
const root = fixture()
|
||||
baseline(root)
|
||||
const after = inventory({ value: 'string', 'label?': 'string' })
|
||||
const prose = proseFile(root)
|
||||
runPersistenceChanges(['--record', NEXT_ID, '--decision', 'same-version', '--prose', prose], root, () => after)
|
||||
const path = join(root, `docs/persistence-changes/${NEXT_ID}.md`)
|
||||
const beforeText = readFileSync(path, 'utf8')
|
||||
const refreshed = inventory({ value: 'string', 'label?': 'string', 'extra?': 'number' })
|
||||
runPersistenceChanges(['--update', NEXT_ID], root, () => refreshed)
|
||||
const stripRecord = (value: string): string => value.replace(/```yaml persistence-change[\s\S]*?```/u, '')
|
||||
expect(stripRecord(readFileSync(path, 'utf8'))).toBe(stripRecord(beforeText))
|
||||
expect(loadPersistenceHistory(root).tips.get('event:example/value')?.id).toBe(NEXT_ID)
|
||||
expect(loadPersistenceHistory(root).entries.find(entry => entry.record.id === NEXT_ID)?.record.changes[0]?.previous).toBe(BASE_ID)
|
||||
expect(jsonResult(runPersistenceChanges(['--check', '--json'], root, () => refreshed)).ok).toBe(true)
|
||||
const final = inventory({ value: 'string', 'label?': 'string', 'extra?': 'number', 'last?': 'boolean' })
|
||||
runPersistenceChanges(['--record', '2026-09-11-successor', '--decision', 'same-version', '--prose', prose], root, () => final)
|
||||
expect(() => runPersistenceChanges(['--update', NEXT_ID, '--decision', 'same-version'], root, () => final)).toThrow('with successors')
|
||||
expect(() => runPersistenceChanges(['--update', BASE_ID, '--decision', 'same-version'], root, () => final)).toThrow('cannot update the persistence baseline')
|
||||
})
|
||||
|
||||
it('completes a scaffold through update and rejects invalid prose or decisions before changing files', () => {
|
||||
const root = fixture()
|
||||
baseline(root)
|
||||
const after = inventory({ value: 'string', 'label?': 'string' })
|
||||
runPersistenceChanges(['--record', NEXT_ID, '--decision', 'same-version'], root, () => after)
|
||||
const prose = proseFile(root)
|
||||
runPersistenceChanges(['--update', NEXT_ID, '--decision', 'same-version', '--prose', prose], root, () => after)
|
||||
expect(runPersistenceChanges(['--check'], root, () => after)).toContain('roots match')
|
||||
expect(readFileSync(join(root, `docs/persistence-changes/${NEXT_ID}.md`), 'utf8')).not.toContain('TODO:')
|
||||
const pairedPaths = ['.md', '.zh.md', '.i18n.yaml'].map(suffix => join(root, `docs/persistence-changes/${NEXT_ID}${suffix}`))
|
||||
const completed = pairedPaths.map(path => readFileSync(path, 'utf8'))
|
||||
runPersistenceChanges(['--update', NEXT_ID, '--decision', 'same-version', '--prose', prose], root, () => after)
|
||||
expect(pairedPaths.map(path => readFileSync(path, 'utf8'))).toEqual(completed)
|
||||
const path = join(root, `docs/persistence-changes/${NEXT_ID}.md`)
|
||||
const before = readFileSync(path, 'utf8')
|
||||
const invalid = inventory({ value: 'number' })
|
||||
const result = jsonResult(runPersistenceChanges(['--update', NEXT_ID, '--decision', 'same-version', '--json'], root, () => invalid))
|
||||
expect(result).toMatchObject({ ok: false, code: 'version-bump-required', changes: [expect.objectContaining({ kind: 'type-changed', requiresVersionBump: true })] })
|
||||
expect(readFileSync(path, 'utf8')).toBe(before)
|
||||
for (const value of [
|
||||
{ ...AUTHORED_PROSE, extra: 'unsupported' },
|
||||
{ ...AUTHORED_PROSE, en: { ...AUTHORED_PROSE.en, compatibility: ' ' } },
|
||||
{ ...AUTHORED_PROSE, zh: { ...AUTHORED_PROSE.zh, verification: 'TODO: record validation evidence.' } },
|
||||
{ ...AUTHORED_PROSE, zh: { ...AUTHORED_PROSE.zh, verification: '```text\nUnpaired code.\n```' } },
|
||||
]) {
|
||||
writeFileSync(prose, JSON.stringify(value))
|
||||
expect(() => runPersistenceChanges(['--update', NEXT_ID, '--decision', 'same-version', '--prose', prose], root, () => after)).toThrow()
|
||||
expect(readFileSync(path, 'utf8')).toBe(before)
|
||||
}
|
||||
})
|
||||
|
||||
// Six real CLI processes and TypeScript extraction share the Windows coverage test budget.
|
||||
it('executes the real CLI against a source-only temporary checkout without Git history', { timeout: 90_000 }, () => {
|
||||
const root = fixture()
|
||||
const physical = join(root, 'packages/session/session-persistence-jsonl/src')
|
||||
mkdirSync(physical, { recursive: true })
|
||||
writeFileSync(join(physical, 'format.ts'), "interface HeaderLine { type: 'session'; version: number; id: string; delegationDepth: number }; export {}\n")
|
||||
const session = join(root, 'packages/core/session/src')
|
||||
mkdirSync(session, { recursive: true })
|
||||
writeFileSync(join(session, '../package.json'), JSON.stringify({ name: '@deepseek-ai/dsh-session' }))
|
||||
writeFileSync(join(root, 'tsconfig.host.json'), JSON.stringify({ compilerOptions: {
|
||||
target: 'ESNext', module: 'ESNext', moduleResolution: 'Bundler', types: [], skipLibCheck: true,
|
||||
paths: { '@deepseek-ai/dsh-session/types': ['./packages/core/session/src/types.ts'] },
|
||||
} }))
|
||||
const source = [
|
||||
'/** Stored header. */', 'export interface SessionHeader { version: 3; id: string }',
|
||||
'/** Stored event payloads. */', 'export interface SessionEventMap {', '/** Saved value. */',
|
||||
"'example/value': { value: string }", '}', '/** Surface event names. */', "export type SurfaceEventType = 'example/value'",
|
||||
'/** Persisted event names. */', 'export type SessionEventType = keyof SessionEventMap',
|
||||
'/** Surface placement. */', "export type SurfaceOp = 'append'", '/** Persisted event. */',
|
||||
'export type SessionEvent<K extends keyof SessionEventMap = keyof SessionEventMap> =',
|
||||
' { [P in K]: { type: P; seq: number; data: SessionEventMap[P]; surfaceOp: SurfaceOp } }[K]', '',
|
||||
].join('\n')
|
||||
writeFileSync(join(session, 'types.ts'), source)
|
||||
const script = resolve(import.meta.dirname, 'persistence-changes.ts')
|
||||
const cli = (...args: string[]): ReturnType<typeof spawnSync> => spawnSync(process.execPath, ['--import', import.meta.resolve('tsx/esm'), script, '--root', root, ...args], {
|
||||
cwd: root, encoding: 'utf8', timeout: 120_000,
|
||||
})
|
||||
const prose = proseFile(root)
|
||||
const initialized = cli('--baseline', BASE_ID, '--prose', prose)
|
||||
expect(initialized.error).toBeUndefined()
|
||||
expect(initialized.signal).toBeNull()
|
||||
expect(initialized.status, String(initialized.stderr)).toBe(0)
|
||||
const accepted = cli('--check')
|
||||
expect(accepted.error).toBeUndefined()
|
||||
expect(accepted.signal).toBeNull()
|
||||
expect(accepted.status, String(accepted.stderr)).toBe(0)
|
||||
const optional = source.replace('value: string', 'value: string; label?: string')
|
||||
writeFileSync(join(session, 'types.ts'), optional)
|
||||
const authored = cli('--record', NEXT_ID, '--prose', prose, '--json')
|
||||
expect(authored.error).toBeUndefined()
|
||||
expect(authored.signal).toBeNull()
|
||||
expect(authored.status, String(authored.stderr)).toBe(0)
|
||||
expect(JSON.parse(String(authored.stdout)) as unknown).toMatchObject({ ok: true, operation: 'record' })
|
||||
const beforeUpdate = readFileSync(join(root, `docs/persistence-changes/${NEXT_ID}.md`), 'utf8')
|
||||
writeFileSync(join(session, 'types.ts'), optional.replace('label?: string', 'label?: string; extra?: number'))
|
||||
const updated = cli('--update', NEXT_ID, '--json')
|
||||
expect(updated.error).toBeUndefined()
|
||||
expect(updated.signal).toBeNull()
|
||||
expect(updated.status, String(updated.stderr)).toBe(0)
|
||||
expect(JSON.parse(String(updated.stdout)) as unknown).toMatchObject({ ok: true, operation: 'update' })
|
||||
expect(readFileSync(join(root, `docs/persistence-changes/${NEXT_ID}.md`), 'utf8').replace(/```yaml persistence-change[\s\S]*?```/u, ''))
|
||||
.toBe(beforeUpdate.replace(/```yaml persistence-change[\s\S]*?```/u, ''))
|
||||
const generated = extractPersistenceSchema(root)
|
||||
for (const file of persistenceCatalogArtifacts(root, generated)) expect(readFileSync(join(root, file.path), 'utf8')).toBe(file.content)
|
||||
verifyPersistenceChanges(root, generated)
|
||||
writeFileSync(join(session, 'types.ts'), optional.replace('label?: string', 'label?: string; extra?: number').replace('value: string', 'value: number'))
|
||||
commitCurrent(root, extractPersistenceSchema(root))
|
||||
const rejected = cli('--check')
|
||||
expect(rejected.error).toBeUndefined()
|
||||
expect(rejected.signal).toBeNull()
|
||||
expect(rejected.status).toBe(1)
|
||||
expect(String(rejected.stderr)).toContain('version-bump required')
|
||||
const structured = cli('--check', '--json')
|
||||
expect(structured.error).toBeUndefined()
|
||||
expect(structured.signal).toBeNull()
|
||||
expect(structured.status).toBe(1)
|
||||
expect(JSON.parse(String(structured.stdout)) as unknown).toMatchObject({
|
||||
ok: false, code: 'unacknowledged-changes', changes: [expect.objectContaining({ kind: 'type-changed', requiresVersionBump: true })],
|
||||
})
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,812 @@
|
||||
/** Verify and acknowledge persistence type changes from current-tree schema history. */
|
||||
|
||||
import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
|
||||
import { basename, join, resolve } from 'node:path'
|
||||
import { parseArgs } from 'node:util'
|
||||
import { JSON_SCHEMA, load } from 'js-yaml'
|
||||
import { canonicalizeSchema, schemaDigest } from './persistence-schema-model.ts'
|
||||
import type { CanonicalSchema, PersistenceRoot, PersistenceSchemaInventory, SchemaNode, SchemaTupleElement } from './persistence-schema-model.ts'
|
||||
import { extractPersistenceSchema } from './persistence-schema.ts'
|
||||
import { persistenceCatalogArtifacts } from './gen-persistence-catalog.ts'
|
||||
import { renderPersistencePair } from './persistence-artifacts.ts'
|
||||
import type { PersistenceArtifact } from './persistence-artifacts.ts'
|
||||
|
||||
const HISTORY_DIRECTORY = 'docs/persistence-changes'
|
||||
const CURRENT_SCHEMA = 'docs/persistence-schema.json'
|
||||
const ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/u
|
||||
const DIGEST_PATTERN = /^[a-f0-9]{64}$/u
|
||||
const EXPLANATION_PLACEHOLDER = 'TODO: explain this change.'
|
||||
const EVIDENCE_PLACEHOLDER = 'TODO: record validation evidence.'
|
||||
|
||||
/** The author's acknowledgement of one mechanically classified transition. */
|
||||
export type PersistenceDecision = 'same-version' | 'version-bump'
|
||||
|
||||
/** One root's successor; null after values preserve a deletion in its history. */
|
||||
export interface PersistenceChange {
|
||||
readonly root: string
|
||||
readonly previous: string | null
|
||||
readonly after: string | null
|
||||
readonly decision: PersistenceDecision
|
||||
}
|
||||
|
||||
/** A document's machine record, independent of its translated prose. */
|
||||
export interface PersistenceChangeRecord {
|
||||
readonly schemaVersion: 1
|
||||
readonly id: string
|
||||
readonly baseline: boolean
|
||||
readonly changes: readonly PersistenceChange[]
|
||||
}
|
||||
|
||||
/** A parsed acknowledgement and its self-contained after schemas. */
|
||||
export interface PersistenceHistoryEntry {
|
||||
readonly record: PersistenceChangeRecord
|
||||
readonly snapshot: PersistenceSchemaInventory
|
||||
}
|
||||
|
||||
/** One detected type change, with a path that reviewers can locate. */
|
||||
export interface PersistenceTypeChange {
|
||||
readonly kind: PersistenceTypeChangeKind
|
||||
readonly path: string
|
||||
readonly description: string
|
||||
readonly requiresVersionBump: boolean
|
||||
}
|
||||
|
||||
const CHANGE_DESCRIPTIONS = {
|
||||
'root-added': 'root added',
|
||||
'root-removed': 'root removed',
|
||||
'root-classification-changed': 'root classification changed',
|
||||
'type-changed': 'type changed',
|
||||
'property-removed': 'property removed',
|
||||
'property-made-optional': 'property made optional',
|
||||
'property-made-required': 'property made required',
|
||||
'optional-property-added': 'optional property added',
|
||||
'required-property-added': 'required property added',
|
||||
'index-signature-changed': 'index signature changed',
|
||||
'tuple-length-changed': 'tuple length changed',
|
||||
'tuple-element-cardinality-changed': 'tuple element cardinality changed',
|
||||
'union-variants-changed': 'union variants changed',
|
||||
} as const
|
||||
|
||||
/** Stable structural classification independent of diagnostic prose. */
|
||||
export type PersistenceTypeChangeKind = keyof typeof CHANGE_DESCRIPTIONS
|
||||
|
||||
/** Author-supplied paragraphs used to complete one language of a change record. */
|
||||
export interface PersistenceChangeProse {
|
||||
readonly summary: string
|
||||
readonly compatibility: string
|
||||
readonly verification: string
|
||||
}
|
||||
|
||||
/** Explicit bilingual prose; the CLI supplies no compatibility or validation claims. */
|
||||
export interface PersistenceChangeProsePair {
|
||||
readonly en: PersistenceChangeProse
|
||||
readonly zh: PersistenceChangeProse
|
||||
}
|
||||
|
||||
interface ReportedChange extends PersistenceTypeChange {
|
||||
readonly root: string
|
||||
}
|
||||
|
||||
interface RootTransition {
|
||||
readonly root: string
|
||||
readonly kind: PersistenceRoot['kind']
|
||||
readonly before: string | null
|
||||
readonly after: string | null
|
||||
}
|
||||
|
||||
class PersistenceChangeFailure extends Error {
|
||||
constructor(
|
||||
message: string, readonly code: string, readonly changes: readonly ReportedChange[] = [],
|
||||
readonly roots: readonly RootTransition[] = [],
|
||||
) {
|
||||
super(message)
|
||||
}
|
||||
}
|
||||
|
||||
interface CommandResult {
|
||||
readonly schemaVersion: 1
|
||||
readonly ok: boolean
|
||||
readonly operation: 'check' | 'baseline' | 'record' | 'update'
|
||||
readonly message: string
|
||||
readonly changes: readonly ReportedChange[]
|
||||
readonly roots: readonly RootTransition[]
|
||||
readonly files: readonly string[]
|
||||
readonly recordId?: string
|
||||
readonly code?: string
|
||||
}
|
||||
|
||||
interface Tip {
|
||||
readonly id: string
|
||||
readonly root: PersistenceRoot | null
|
||||
}
|
||||
|
||||
/** Verified per-root history tips; historical schemas need not match the current tree. */
|
||||
export interface PersistenceHistory {
|
||||
readonly entries: readonly PersistenceHistoryEntry[]
|
||||
readonly tips: ReadonlyMap<string, Tip>
|
||||
}
|
||||
|
||||
function record(value: unknown, label: string): Record<string, unknown> {
|
||||
if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be an object`)
|
||||
return value as Record<string, unknown>
|
||||
}
|
||||
|
||||
function keys(value: Record<string, unknown>, expected: readonly string[], label: string, optional: readonly string[] = []): void {
|
||||
const missing = expected.find(key => !Object.hasOwn(value, key))
|
||||
const unexpected = Object.keys(value).find(key => !expected.includes(key) && !optional.includes(key))
|
||||
if (missing !== undefined || unexpected !== undefined) throw new Error(`${label}: ${missing === undefined ? `unknown field ${unexpected}` : `missing field ${missing}`}`)
|
||||
}
|
||||
|
||||
function array(value: unknown, label: string): unknown[] {
|
||||
if (!Array.isArray(value)) throw new Error(`${label} must be an array`)
|
||||
return value
|
||||
}
|
||||
|
||||
function textValue(value: unknown, label: string): string {
|
||||
if (typeof value !== 'string' || value.length === 0) throw new Error(`${label} must be a non-empty string`)
|
||||
return value
|
||||
}
|
||||
|
||||
function bool(value: unknown, label: string): boolean {
|
||||
if (typeof value !== 'boolean') throw new Error(`${label} must be boolean`)
|
||||
return value
|
||||
}
|
||||
|
||||
function identifier(value: unknown, label: string): string {
|
||||
const id = textValue(value, label)
|
||||
if (!ID_PATTERN.test(id)) throw new Error(`${label} must be YYYY-MM-DD-slug`)
|
||||
return id
|
||||
}
|
||||
|
||||
function digest(value: unknown, label: string): string {
|
||||
const result = textValue(value, label)
|
||||
if (!DIGEST_PATTERN.test(result)) throw new Error(`${label} must be a SHA-256 digest`)
|
||||
return result
|
||||
}
|
||||
|
||||
function reference(value: unknown, count: number, label: string): number {
|
||||
if (!Number.isSafeInteger(value) || (value as number) < 0 || (value as number) >= count) throw new Error(`${label} references an unknown schema node`)
|
||||
return value as number
|
||||
}
|
||||
|
||||
function parseSchema(value: unknown, label: string): CanonicalSchema {
|
||||
const input = record(value, label)
|
||||
keys(input, ['root', 'nodes'], label)
|
||||
if (input.root !== 0) throw new Error(`${label}.root must be zero`)
|
||||
const nodes = array(input.nodes, `${label}.nodes`)
|
||||
if (nodes.length === 0) throw new Error(`${label}.nodes must not be empty`)
|
||||
const ref = (value: unknown): number => reference(value, nodes.length, label)
|
||||
for (const [index, raw] of nodes.entries()) {
|
||||
const node = record(raw, `${label}.nodes[${index}]`)
|
||||
switch (node.kind) {
|
||||
case 'primitive':
|
||||
keys(node, ['kind', 'type'], label)
|
||||
if (!['null', 'boolean', 'number', 'string', 'never'].includes(String(node.type))) throw new Error(`${label}: invalid primitive`)
|
||||
break
|
||||
case 'literal':
|
||||
keys(node, ['kind', 'value'], label)
|
||||
if (!['string', 'boolean', 'number'].includes(typeof node.value)
|
||||
|| typeof node.value === 'number' && !Number.isFinite(node.value)) throw new Error(`${label}: invalid literal`)
|
||||
break
|
||||
case 'opaque':
|
||||
keys(node, ['kind', 'reason'], label)
|
||||
if (!['any', 'unknown'].includes(String(node.reason))) throw new Error(`${label}: invalid opaque reason`)
|
||||
break
|
||||
case 'array':
|
||||
keys(node, ['kind', 'element'], label)
|
||||
ref(node.element)
|
||||
break
|
||||
case 'tuple':
|
||||
keys(node, ['kind', 'elements'], label)
|
||||
for (const rawElement of array(node.elements, label)) {
|
||||
const element = record(rawElement, label)
|
||||
keys(element, ['type', 'optional', 'rest'], label)
|
||||
ref(element.type)
|
||||
bool(element.optional, label)
|
||||
bool(element.rest, label)
|
||||
}
|
||||
break
|
||||
case 'object': {
|
||||
keys(node, ['kind', 'properties', 'indices'], label)
|
||||
const names = new Set<string>()
|
||||
for (const rawProperty of array(node.properties, label)) {
|
||||
const property = record(rawProperty, label)
|
||||
keys(property, ['name', 'type', 'optional'], label)
|
||||
if (typeof property.name !== 'string') throw new Error(`${label}: property name must be a string`)
|
||||
const name = property.name
|
||||
if (names.has(name)) throw new Error(`${label}: duplicate property ${name}`)
|
||||
names.add(name)
|
||||
ref(property.type)
|
||||
bool(property.optional, label)
|
||||
}
|
||||
for (const rawIndex of array(node.indices, label)) {
|
||||
const entry = record(rawIndex, label)
|
||||
keys(entry, ['key', 'value'], label)
|
||||
ref(entry.key)
|
||||
ref(entry.value)
|
||||
}
|
||||
break
|
||||
}
|
||||
case 'union':
|
||||
keys(node, ['kind', 'types'], label)
|
||||
if (array(node.types, label).length === 0) throw new Error(`${label}: empty union`)
|
||||
for (const item of node.types as unknown[]) ref(item)
|
||||
break
|
||||
default:
|
||||
throw new Error(`${label}: unknown schema node kind ${String(node.kind)}`)
|
||||
}
|
||||
}
|
||||
const schema = input as unknown as CanonicalSchema
|
||||
const canonical = canonicalizeSchema(schema.nodes, schema.root)
|
||||
if (JSON.stringify(canonical) !== JSON.stringify(schema)) throw new Error(`${label}: schema is not canonical`)
|
||||
return schema
|
||||
}
|
||||
|
||||
/** Parse a persisted schema inventory, rejecting malformed graphs and digest drift.
|
||||
* @param value - JSON read from the current inventory or an enforced acknowledgement snapshot.
|
||||
* @returns the validated inventory.
|
||||
*/
|
||||
export function parsePersistenceSnapshot(value: unknown): PersistenceSchemaInventory {
|
||||
return parseSnapshot(value, false)
|
||||
}
|
||||
|
||||
/** Parse a historical inventory with path-only source references and optional surface operations.
|
||||
* @param value - JSON captured from a historical source tree.
|
||||
* @returns the validated inventory; current acknowledgements use the strict parser.
|
||||
*/
|
||||
export function parseHistoricalPersistenceSnapshot(value: unknown): PersistenceSchemaInventory {
|
||||
return parseSnapshot(value, true)
|
||||
}
|
||||
|
||||
function parseSnapshot(value: unknown, historical: boolean): PersistenceSchemaInventory {
|
||||
const input = record(value, 'schema inventory')
|
||||
keys(input, ['formatVersion', 'roots', 'types'], 'schema inventory')
|
||||
if (input.formatVersion !== 1) throw new Error('unsupported persistence schema normalization version')
|
||||
const names = new Set<string>()
|
||||
for (const rawRoot of array(input.roots, 'schema roots')) {
|
||||
const root = record(rawRoot, 'schema root')
|
||||
keys(root, ['key', 'kind', 'digest', 'schema'], 'schema root', ['event', 'surface'])
|
||||
const key = textValue(root.key, 'root key')
|
||||
if (names.has(key)) throw new Error(`duplicate schema root ${key}`)
|
||||
names.add(key)
|
||||
if (root.kind === 'event') {
|
||||
if (key !== `event:${textValue(root.event, 'event name')}`) throw new Error(`invalid event root key ${key}`)
|
||||
bool(root.surface, 'event surface membership')
|
||||
} else if ((root.kind !== 'header' || !['SessionHeader', 'JsonlHeaderLine'].includes(key))
|
||||
&& (root.kind !== 'envelope' || key !== 'SessionEventEnvelope')) throw new Error(`invalid schema root ${key}`)
|
||||
if (root.kind !== 'event' && (root.event !== undefined || root.surface !== undefined)) throw new Error(`${key}: non-event metadata`)
|
||||
const schema = parseSchema(root.schema, key)
|
||||
if (root.kind === 'event') validateEventMetadata(schema, String(root.event), root.surface === true, historical)
|
||||
if (digest(root.digest, `${key} digest`) !== schemaDigest(schema)) throw new Error(`${key}: schema digest mismatch`)
|
||||
}
|
||||
for (const rawType of array(input.types, 'schema types')) {
|
||||
const type = record(rawType, 'schema type')
|
||||
keys(type, ['digest', 'schema', 'names', 'sources'], 'schema type')
|
||||
const schema = parseSchema(type.schema, 'shared schema')
|
||||
if (digest(type.digest, 'shared digest') !== schemaDigest(schema)) throw new Error('shared schema digest mismatch')
|
||||
for (const name of array(type.names, 'type names')) textValue(name, 'type name')
|
||||
for (const source of array(type.sources, 'type sources')) {
|
||||
const location = textValue(source, 'type source')
|
||||
if (historical && /:\d+(?::\d+)?$|#L\d+(?:-L\d+)?$/u.test(location)) {
|
||||
throw new Error('historical schema sources must omit line numbers')
|
||||
}
|
||||
}
|
||||
}
|
||||
return input as unknown as PersistenceSchemaInventory
|
||||
}
|
||||
|
||||
function validateEventMetadata(schema: CanonicalSchema, event: string, surface: boolean, historical: boolean): void {
|
||||
const pending = [0]
|
||||
const visited = new Set<number>()
|
||||
while (pending.length > 0) {
|
||||
const index = pending.pop() as number
|
||||
if (visited.has(index)) continue
|
||||
visited.add(index)
|
||||
const node = schema.nodes[index] as SchemaNode
|
||||
if (node.kind === 'union') { pending.push(...node.types); continue }
|
||||
if (node.kind !== 'object') throw new Error(`${event}: event schema must be an object`)
|
||||
const tag = node.properties.find(property => property.name === 'type')
|
||||
const value = tag === undefined ? undefined : schema.nodes[tag.type]
|
||||
if (tag?.optional !== false || value?.kind !== 'literal' || value.value !== event) throw new Error(`${event}: event schema type does not match its root`)
|
||||
const operation = node.properties.find(property => property.name === 'surfaceOp')
|
||||
if (surface ? operation === undefined || !historical && operation.optional : operation !== undefined) throw new Error(`${event}: surface metadata does not match its schema`)
|
||||
}
|
||||
}
|
||||
|
||||
function subDigest(schema: CanonicalSchema, node: number): string {
|
||||
return schemaDigest(canonicalizeSchema(schema.nodes, node))
|
||||
}
|
||||
|
||||
function matchUnionVariants(candidates: readonly (readonly number[])[]): number[] | undefined {
|
||||
const owners = new Map<number, number>()
|
||||
function assign(previous: number, visited: Set<number>): boolean {
|
||||
for (const next of candidates[previous] ?? []) {
|
||||
if (visited.has(next)) continue
|
||||
visited.add(next)
|
||||
const owner = owners.get(next)
|
||||
if (owner === undefined || assign(owner, visited)) {
|
||||
owners.set(next, previous)
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
for (let previous = 0; previous < candidates.length; previous += 1) {
|
||||
if (!assign(previous, new Set())) return undefined
|
||||
}
|
||||
const matches: number[] = []
|
||||
for (const [next, previous] of owners) matches[previous] = next
|
||||
return matches
|
||||
}
|
||||
|
||||
/** Classify structural differences; only optional payload properties and ordinary event additions are additive.
|
||||
* @param before - predecessor root, or absence for an addition.
|
||||
* @param after - successor root, or absence for deletion.
|
||||
* @returns concrete changes and their format-bump requirement.
|
||||
*/
|
||||
export function classifyPersistenceChange(before: PersistenceRoot | null, after: PersistenceRoot | null): PersistenceTypeChange[] {
|
||||
if (before === null) {
|
||||
return after === null ? [] : [{ path: after.key, kind: 'root-added', description: 'root added',
|
||||
requiresVersionBump: after.kind !== 'event' || after.surface !== false }]
|
||||
}
|
||||
if (after === null) return [{ path: before.key, kind: 'root-removed', description: 'root removed', requiresVersionBump: true }]
|
||||
const key = after.key
|
||||
const oldRoot = before
|
||||
const newRoot = after
|
||||
const describe = (path: string, kind: PersistenceTypeChangeKind, requiresVersionBump = true): PersistenceTypeChange =>
|
||||
({ path, kind, description: CHANGE_DESCRIPTIONS[kind], requiresVersionBump })
|
||||
const changes: PersistenceTypeChange[] = []
|
||||
if (before.kind !== after.kind || before.surface !== after.surface) changes.push(describe(key, 'root-classification-changed'))
|
||||
if (before.digest === after.digest) return changes
|
||||
const fingerprints = [new Map<number, string>(), new Map<number, string>()] as const
|
||||
const fingerprint = (schema: CanonicalSchema, index: number, side: 0 | 1): string => {
|
||||
let result = fingerprints[side].get(index)
|
||||
if (result === undefined) { result = subDigest(schema, index); fingerprints[side].set(index, result) }
|
||||
return result
|
||||
}
|
||||
type Scope = 'event' | 'body' | 'strict'
|
||||
function compare(
|
||||
oldIndex: number, newIndex: number, path: string, scope: Scope, ancestors: ReadonlySet<string>,
|
||||
): PersistenceTypeChange[] {
|
||||
if (fingerprint(oldRoot.schema, oldIndex, 0) === fingerprint(newRoot.schema, newIndex, 1)) return []
|
||||
const pair = `${oldIndex}:${newIndex}:${scope}`
|
||||
if (ancestors.has(pair)) return []
|
||||
// Recursive pairs are assumptions for this candidate only. A failed sibling
|
||||
// or unmatched union arm cannot leave a cached success for another candidate.
|
||||
const active = new Set(ancestors).add(pair)
|
||||
const differences: PersistenceTypeChange[] = []
|
||||
const add = (path: string, kind: PersistenceTypeChangeKind, requiresVersionBump = true): void => {
|
||||
differences.push(describe(path, kind, requiresVersionBump))
|
||||
}
|
||||
const descend = (oldType: number, newType: number, child: string, childScope: Scope): void => {
|
||||
differences.push(...compare(oldType, newType, child, childScope, active))
|
||||
}
|
||||
const oldNode = oldRoot.schema.nodes[oldIndex] as SchemaNode
|
||||
const newNode = newRoot.schema.nodes[newIndex] as SchemaNode
|
||||
if (oldNode.kind !== newNode.kind) return [describe(path, 'type-changed')]
|
||||
if (oldNode.kind === 'object' && newNode.kind === 'object') {
|
||||
const oldProps = new Map(oldNode.properties.map(property => [property.name, property]))
|
||||
const newProps = new Map(newNode.properties.map(property => [property.name, property]))
|
||||
for (const [name, property] of oldProps) {
|
||||
const next = newProps.get(name)
|
||||
const child = `${path}.${name}`
|
||||
if (next === undefined) { add(child, 'property-removed'); continue }
|
||||
if (property.optional !== next.optional) add(child, next.optional ? 'property-made-optional' : 'property-made-required', scope !== 'body' || !next.optional)
|
||||
descend(property.type, next.type, child, scope === 'body' || scope === 'event' && name === 'data' ? 'body' : 'strict')
|
||||
}
|
||||
for (const [name, property] of newProps) {
|
||||
if (!oldProps.has(name)) add(`${path}.${name}`, property.optional ? 'optional-property-added' : 'required-property-added', scope !== 'body' || !property.optional)
|
||||
}
|
||||
const oldIndices = new Map(oldNode.indices.map(entry => [fingerprint(oldRoot.schema, entry.key, 0), entry]))
|
||||
const newIndices = new Map(newNode.indices.map(entry => [fingerprint(newRoot.schema, entry.key, 1), entry]))
|
||||
if (oldIndices.size !== newIndices.size || [...oldIndices.keys()].some(index => !newIndices.has(index))) add(path, 'index-signature-changed')
|
||||
for (const [index, entry] of oldIndices) {
|
||||
const next = newIndices.get(index)
|
||||
if (next !== undefined) descend(entry.value, next.value, `${path}[*]`, scope === 'body' ? 'body' : 'strict')
|
||||
}
|
||||
return differences
|
||||
}
|
||||
if (oldNode.kind === 'array' && newNode.kind === 'array') {
|
||||
return compare(oldNode.element, newNode.element, `${path}[]`, scope === 'body' ? 'body' : 'strict', active)
|
||||
}
|
||||
if (oldNode.kind === 'tuple' && newNode.kind === 'tuple') {
|
||||
if (oldNode.elements.length !== newNode.elements.length) return [describe(path, 'tuple-length-changed')]
|
||||
for (const [index, element] of oldNode.elements.entries()) {
|
||||
const next = newNode.elements[index] as SchemaTupleElement
|
||||
if (element.optional !== next.optional || element.rest !== next.rest) add(`${path}[${index}]`, 'tuple-element-cardinality-changed')
|
||||
descend(element.type, next.type, `${path}[${index}]`, scope === 'body' ? 'body' : 'strict')
|
||||
}
|
||||
return differences
|
||||
}
|
||||
if (oldNode.kind === 'union' && newNode.kind === 'union') {
|
||||
if (oldNode.types.length !== newNode.types.length) return [describe(path, 'union-variants-changed')]
|
||||
const candidates = oldNode.types.map(oldType => newNode.types.map(newType => compare(oldType, newType, path, scope, active)))
|
||||
const matching = matchUnionVariants(candidates.map(row => row.flatMap((candidate, index) =>
|
||||
candidate.every(change => !change.requiresVersionBump) ? [index] : [])))
|
||||
if (matching !== undefined) return matching.flatMap((next, previous) => candidates[previous]?.[next] ?? [])
|
||||
const oldTypes = new Map(oldNode.types.map(index => [fingerprint(oldRoot.schema, index, 0), index]))
|
||||
const newTypes = new Map(newNode.types.map(index => [fingerprint(newRoot.schema, index, 1), index]))
|
||||
const removed = [...oldTypes].filter(([hash]) => !newTypes.has(hash)).map(([, index]) => index)
|
||||
const added = [...newTypes].filter(([hash]) => !oldTypes.has(hash)).map(([, index]) => index)
|
||||
if (removed.length === 1 && added.length === 1) return compare(removed[0] as number, added[0] as number, path, scope, active)
|
||||
return [describe(path, 'union-variants-changed')]
|
||||
}
|
||||
return [describe(path, 'type-changed')]
|
||||
}
|
||||
changes.push(...compare(0, 0, key, before.kind === 'event' ? 'event' : 'strict', new Set()))
|
||||
if (changes.length === 0) changes.push(describe(key, 'type-changed'))
|
||||
return [...new Map(changes.map(change => [JSON.stringify([change.path, change.kind, change.requiresVersionBump]), change])).values()]
|
||||
}
|
||||
|
||||
function parseDocument(source: string, filename: string, allowIncomplete = false): PersistenceChangeRecord {
|
||||
const frontmatter = /^---\n([\s\S]*?)\n---\n/u.exec(source)
|
||||
if (frontmatter === null || record(load(frontmatter[1] as string, { schema: JSON_SCHEMA }), filename).kind !== 'persistence-change') throw new Error(`${filename}: kind must be persistence-change`)
|
||||
const openings = [...source.matchAll(/^```yaml persistence-change\s*$/gmu)]
|
||||
const block = /^```yaml persistence-change[^\S\n]*\n([\s\S]*?)^```[^\S\n]*$/mu.exec(source)
|
||||
if (openings.length !== 1 || block === null) throw new Error(`${filename}: expected exactly one persistence-change block`)
|
||||
const input = record(load(block[1] as string, { schema: JSON_SCHEMA }), filename)
|
||||
keys(input, ['schemaVersion', 'id', 'baseline', 'changes'], filename)
|
||||
if (input.schemaVersion !== 1) throw new Error(`${filename}: unsupported acknowledgement schema version`)
|
||||
const id = identifier(input.id, filename)
|
||||
if (basename(filename) !== `${id}.md`) throw new Error(`${filename}: record id does not match filename`)
|
||||
bool(input.baseline, filename)
|
||||
const roots = new Set<string>()
|
||||
for (const value of array(input.changes, `${filename} changes`)) {
|
||||
const change = record(value, filename)
|
||||
keys(change, ['root', 'previous', 'after', 'decision'], filename)
|
||||
const root = textValue(change.root, 'changed root')
|
||||
if (roots.has(root)) throw new Error(`${filename}: duplicate change for ${root}`)
|
||||
roots.add(root)
|
||||
if (change.previous !== null) identifier(change.previous, 'previous record')
|
||||
if (change.after !== null) digest(change.after, 'after digest')
|
||||
if (change.decision !== 'same-version' && change.decision !== 'version-bump') throw new Error(`${filename}: invalid compatibility decision`)
|
||||
}
|
||||
if (roots.size === 0) throw new Error(`${filename}: changes must not be empty`)
|
||||
if (!allowIncomplete && (source.includes(EXPLANATION_PLACEHOLDER) || source.includes(EVIDENCE_PLACEHOLDER))) throw new Error(`${filename}: complete compatibility and verification prose`)
|
||||
return input as unknown as PersistenceChangeRecord
|
||||
}
|
||||
|
||||
function headerVersion(root: PersistenceRoot | null): number | undefined {
|
||||
if (root === null) return undefined
|
||||
const node = root.schema.nodes[0]
|
||||
if (node?.kind !== 'object') return undefined
|
||||
const property = node.properties.find(item => item.name === 'version')
|
||||
if (property === undefined) return undefined
|
||||
const version = root.schema.nodes[property.type]
|
||||
return version?.kind === 'literal' && typeof version.value === 'number' && Number.isSafeInteger(version.value) ? version.value : undefined
|
||||
}
|
||||
|
||||
/** Check every historical transition and return each root's unique current tip.
|
||||
* @param entries - parsed documents and their self-contained schema snapshots.
|
||||
* @returns validated history and tips, without consulting Git or current source.
|
||||
*/
|
||||
export function validatePersistenceHistory(entries: readonly PersistenceHistoryEntry[]): PersistenceHistory {
|
||||
if (entries.filter(entry => entry.record.baseline).length !== 1) throw new Error('persistence history requires exactly one baseline')
|
||||
const records = new Map<string, PersistenceHistoryEntry>()
|
||||
for (const entry of entries) {
|
||||
if (records.has(entry.record.id)) throw new Error(`duplicate persistence record ${entry.record.id}`)
|
||||
records.set(entry.record.id, entry)
|
||||
const expected = entry.record.changes.filter(change => change.after !== null).map(change => change.root).sort()
|
||||
if (JSON.stringify(expected) !== JSON.stringify(entry.snapshot.roots.map(root => root.key).sort())) throw new Error(`${entry.record.id}: snapshot roots do not match acknowledged after schemas`)
|
||||
for (const change of entry.record.changes) {
|
||||
const root = entry.snapshot.roots.find(root => root.key === change.root)
|
||||
if ((root?.digest ?? null) !== change.after) throw new Error(`${entry.record.id}: after digest mismatch for ${change.root}`)
|
||||
if (entry.record.baseline && (change.previous !== null || change.after === null || change.decision !== 'same-version')) throw new Error(`${entry.record.id}: invalid baseline transition`)
|
||||
}
|
||||
}
|
||||
const states = new Map<string, 'visiting' | 'visited'>()
|
||||
const successors = new Map<string, string>()
|
||||
const nodes = new Map<string, { entry: PersistenceHistoryEntry; change: PersistenceChange }>()
|
||||
const tips = new Map<string, Tip>()
|
||||
const nodeKey = (id: string | null, root: string): string => JSON.stringify([id, root])
|
||||
for (const entry of entries) for (const change of entry.record.changes) {
|
||||
const parentKey = nodeKey(change.previous, change.root)
|
||||
if (successors.has(parentKey)) throw new Error(`forked persistence history for ${change.root}: ${successors.get(parentKey)} and ${entry.record.id}`)
|
||||
successors.set(parentKey, entry.record.id)
|
||||
nodes.set(nodeKey(entry.record.id, change.root), { entry, change })
|
||||
}
|
||||
function visit(id: string, root: string): PersistenceRoot | null {
|
||||
const key = nodeKey(id, root)
|
||||
const found = nodes.get(key)
|
||||
if (found === undefined) throw new Error(`missing predecessor ${id} for ${root}`)
|
||||
if (states.get(key) === 'visiting') throw new Error(`cycle in persistence history for ${root}`)
|
||||
const after = found.entry.snapshot.roots.find(item => item.key === root) ?? null
|
||||
if (states.get(key) === 'visited') return after
|
||||
states.set(key, 'visiting')
|
||||
const before = found.change.previous === null ? null : visit(found.change.previous, root)
|
||||
if (!found.entry.record.baseline) {
|
||||
const differences = classifyPersistenceChange(before, after)
|
||||
if (differences.length === 0) throw new Error(`${id}: unchanged acknowledgement for ${root}`)
|
||||
if (differences.some(change => change.requiresVersionBump) && found.change.decision !== 'version-bump') {
|
||||
throw new PersistenceChangeFailure(
|
||||
`${id}: ${root} requires a format version bump (${differences.filter(change => change.requiresVersionBump).map(change => change.path + ': ' + change.description).join('; ')})`,
|
||||
'version-bump-required', differences.map(change => ({ root, ...change })), [rootTransition(before, after)],
|
||||
)
|
||||
}
|
||||
if (found.change.decision === 'version-bump') {
|
||||
const header = found.entry.record.changes.find(change => change.root === 'SessionHeader')
|
||||
const oldHeader = header?.previous === null || header === undefined ? null : visit(header.previous, 'SessionHeader')
|
||||
const from = headerVersion(oldHeader)
|
||||
const to = headerVersion(found.entry.snapshot.roots.find(item => item.key === 'SessionHeader') ?? null)
|
||||
if (from === undefined || to === undefined || to <= from) {
|
||||
throw new PersistenceChangeFailure(`${id}: version-bump requires this record's own increasing SessionHeader.version transition`,
|
||||
'version-transition-required', differences.map(change => ({ root, ...change })), [rootTransition(before, after)])
|
||||
}
|
||||
}
|
||||
}
|
||||
states.set(key, 'visited')
|
||||
if (!successors.has(key)) tips.set(root, { id, root: after })
|
||||
return after
|
||||
}
|
||||
for (const entry of entries) for (const change of entry.record.changes) visit(entry.record.id, change.root)
|
||||
const baseline = entries.find(entry => entry.record.baseline) as PersistenceHistoryEntry
|
||||
if (!baseline.snapshot.roots.some(root => root.key === 'SessionHeader')
|
||||
|| !baseline.snapshot.roots.some(root => root.key === 'SessionEventEnvelope')
|
||||
|| !baseline.snapshot.roots.some(root => root.key === 'JsonlHeaderLine')) {
|
||||
throw new Error('baseline requires SessionHeader, JsonlHeaderLine, and SessionEventEnvelope roots')
|
||||
}
|
||||
return { entries, tips }
|
||||
}
|
||||
|
||||
/** Read and validate all current-tree persistence acknowledgement files.
|
||||
* @param root - checkout or isolated fixture root.
|
||||
* @returns checked history without comparing its tips to current source.
|
||||
*/
|
||||
export function loadPersistenceHistory(root: string): PersistenceHistory {
|
||||
return validatePersistenceHistory(readPersistenceEntries(root))
|
||||
}
|
||||
|
||||
function readPersistenceEntries(root: string, allowIncompleteId?: string): PersistenceHistoryEntry[] {
|
||||
const directory = join(root, HISTORY_DIRECTORY)
|
||||
if (!existsSync(directory)) throw new Error('persistence history is missing; use pnpm run persistence-changes --baseline ID for explicit initialization')
|
||||
const files = readdirSync(directory).sort()
|
||||
const documents = files.filter(file => file.endsWith('.md') && !file.endsWith('.zh.md') && file !== 'README.md' && file !== 'AGENTS.md')
|
||||
const snapshots = new Set(files.filter(file => file.endsWith('.schema.json')))
|
||||
const entries = documents.map((filename) => {
|
||||
const source = readFileSync(join(directory, filename), 'utf8').replaceAll('\r\n', '\n')
|
||||
const allowIncomplete = filename === `${allowIncompleteId}.md`
|
||||
const change = parseDocument(source, filename, allowIncomplete)
|
||||
const snapshotName = `${change.id}.schema.json`
|
||||
if (!snapshots.delete(snapshotName)) throw new Error(`${filename}: missing schema snapshot ${snapshotName}`)
|
||||
const snapshot = parsePersistenceSnapshot(JSON.parse(readFileSync(join(directory, snapshotName), 'utf8')))
|
||||
const translatedName = `${change.id}.zh.md`
|
||||
if (!files.includes(translatedName)) throw new Error(`${filename}: missing Chinese counterpart`)
|
||||
const translated = readFileSync(join(directory, translatedName), 'utf8').replaceAll('\r\n', '\n')
|
||||
const englishBlock = source.match(/^```yaml persistence-change[^\S\n]*\n([\s\S]*?)^```[^\S\n]*$/mu)?.[1]
|
||||
const chineseBlocks = [...translated.matchAll(/^```yaml persistence-change[^\S\n]*\n([\s\S]*?)^```[^\S\n]*$/gmu)]
|
||||
if (chineseBlocks.length !== 1 || chineseBlocks[0]?.[1] !== englishBlock) throw new Error(`${filename}: bilingual machine records differ`)
|
||||
if (!allowIncomplete && (translated.includes(EXPLANATION_PLACEHOLDER) || translated.includes(EVIDENCE_PLACEHOLDER))) throw new Error(`${translatedName}: complete compatibility and verification prose`)
|
||||
return { record: change, snapshot }
|
||||
})
|
||||
if (snapshots.size !== 0) throw new Error(`unreferenced persistence schema snapshot: ${[...snapshots].join(', ')}`)
|
||||
return entries
|
||||
}
|
||||
|
||||
function currentDifferences(history: PersistenceHistory, current: PersistenceSchemaInventory): string[] {
|
||||
const roots = new Map(current.roots.map(root => [root.key, root]))
|
||||
const differences: string[] = []
|
||||
for (const key of new Set([...history.tips.keys(), ...roots.keys()])) {
|
||||
if (classifyPersistenceChange(history.tips.get(key)?.root ?? null, roots.get(key) ?? null).length !== 0) differences.push(key)
|
||||
}
|
||||
return differences.sort()
|
||||
}
|
||||
|
||||
/** Verify current generated output and acknowledgement tips together.
|
||||
* @param root - checkout or isolated fixture root.
|
||||
* @param current - freshly extracted current-source inventory.
|
||||
* @returns verified history.
|
||||
*/
|
||||
export function verifyPersistenceChanges(root: string, current: PersistenceSchemaInventory): PersistenceHistory {
|
||||
const history = loadPersistenceHistory(root)
|
||||
const differences = reportedDifferences(history, current)
|
||||
const transitions = rootTransitions(history, current)
|
||||
const committedPath = join(root, CURRENT_SCHEMA)
|
||||
if (!existsSync(committedPath)) {
|
||||
throw new PersistenceChangeFailure(`${CURRENT_SCHEMA} is missing; regenerate the persistence catalog`, 'generated-artifact-missing', differences, transitions)
|
||||
}
|
||||
const committed = parsePersistenceSnapshot(JSON.parse(readFileSync(committedPath, 'utf8')))
|
||||
if (JSON.stringify(committed) !== JSON.stringify(current)) {
|
||||
throw new PersistenceChangeFailure(`${CURRENT_SCHEMA} is stale; regenerate the persistence catalog`, 'stale-artifacts', differences, transitions)
|
||||
}
|
||||
if (differences.length !== 0) {
|
||||
const details = differences.map(change => ` ${change.path}: ${change.description} (${change.requiresVersionBump ? 'version-bump required' : 'same-version allowed'})`)
|
||||
throw new PersistenceChangeFailure(`unacknowledged persistence type changes:\n${details.join('\n')}`, 'unacknowledged-changes', differences, transitions)
|
||||
}
|
||||
return history
|
||||
}
|
||||
|
||||
function rootTransition(before: PersistenceRoot | null, after: PersistenceRoot | null): RootTransition {
|
||||
const root = (after ?? before) as PersistenceRoot
|
||||
return { root: root.key, kind: root.kind, before: before?.digest ?? null, after: after?.digest ?? null }
|
||||
}
|
||||
|
||||
function rootTransitions(history: PersistenceHistory | undefined, current: PersistenceSchemaInventory): RootTransition[] {
|
||||
const changed = history === undefined ? current.roots.map(root => root.key) : currentDifferences(history, current)
|
||||
return changed.map(root => rootTransition(history?.tips.get(root)?.root ?? null, current.roots.find(item => item.key === root) ?? null))
|
||||
}
|
||||
|
||||
function reportedDifferences(history: PersistenceHistory, current: PersistenceSchemaInventory): ReportedChange[] {
|
||||
return currentDifferences(history, current).flatMap(root => classifyPersistenceChange(
|
||||
history.tips.get(root)?.root ?? null, current.roots.find(item => item.key === root) ?? null,
|
||||
).map(change => ({ root, ...change })))
|
||||
}
|
||||
|
||||
function machineBlock(change: PersistenceChangeRecord): string {
|
||||
return ['```yaml persistence-change', 'schemaVersion: 1', `id: ${change.id}`, `baseline: ${String(change.baseline)}`, 'changes:',
|
||||
...change.changes.flatMap(item => [` - root: ${JSON.stringify(item.root)}`, ` previous: ${item.previous === null ? 'null' : JSON.stringify(item.previous)}`, ` after: ${item.after === null ? 'null' : JSON.stringify(item.after)}`, ` decision: ${item.decision}`]), '```'].join('\n')
|
||||
}
|
||||
|
||||
function scaffold(change: PersistenceChangeRecord, chinese: boolean, prose?: PersistenceChangeProse): string {
|
||||
const summary = chinese ? '概述' : 'Summary'
|
||||
const compatibility = chinese ? '兼容性' : 'Compatibility'
|
||||
const verification = chinese ? '验证' : 'Verification'
|
||||
return ['---', `description: ${JSON.stringify(chinese ? '记录持久化类型更改及其兼容性确认。' : 'Records a persistence type transition and its compatibility acknowledgement.')}`, 'kind: persistence-change', '---', '',
|
||||
`# ${change.id}`, '', chinese ? `[English](${change.id}.md) | 中文` : `English | [中文](${change.id}.zh.md)`, '',
|
||||
`## ${summary}`, '', prose?.summary ?? EXPLANATION_PLACEHOLDER, '', '## ' + (chinese ? '目录' : 'Table of Contents'), '',
|
||||
`- [${chinese ? '声明' : 'Declaration'}](#declaration)`, `- [${compatibility}](#compatibility)`, `- [${verification}](#verification)`, `- [${chinese ? '开发备注' : 'Dev Note'}](#dev-note)`, '',
|
||||
'<a id="declaration"></a>', `## ${chinese ? '声明' : 'Declaration'}`, '', machineBlock(change), '',
|
||||
'<a id="compatibility"></a>', `## ${compatibility}`, '', prose?.compatibility ?? EXPLANATION_PLACEHOLDER, '',
|
||||
'<a id="verification"></a>', `## ${verification}`, '', prose?.verification ?? EVIDENCE_PLACEHOLDER, '', '<a id="dev-note"></a>', `## ${chinese ? '开发备注' : 'Dev Note'}`, '', chinese ? '无。' : 'None.', ''].join('\n')
|
||||
}
|
||||
|
||||
/** Parse explicit authored prose without supplying compatibility or validation claims.
|
||||
* @param value - decoded JSON supplied through --prose.
|
||||
* @returns complete English and Chinese section text.
|
||||
*/
|
||||
export function parsePersistenceProse(value: unknown): PersistenceChangeProsePair {
|
||||
const pair = record(value, 'persistence prose')
|
||||
keys(pair, ['en', 'zh'], 'persistence prose')
|
||||
for (const locale of ['en', 'zh']) {
|
||||
const sections = record(pair[locale], `persistence prose ${locale}`)
|
||||
keys(sections, ['summary', 'compatibility', 'verification'], `persistence prose ${locale}`)
|
||||
for (const [name, value] of Object.entries(sections)) {
|
||||
const text = textValue(value, `${locale}.${name}`)
|
||||
if (text.trim().length === 0 || text.includes(EXPLANATION_PLACEHOLDER) || text.includes(EVIDENCE_PLACEHOLDER)) {
|
||||
throw new Error(`${locale}.${name} requires authored prose without scaffold placeholders`)
|
||||
}
|
||||
}
|
||||
}
|
||||
return pair as unknown as PersistenceChangeProsePair
|
||||
}
|
||||
|
||||
function updateDocument(source: string, change: PersistenceChangeRecord, chinese: boolean, prose?: PersistenceChangeProse): string {
|
||||
source = source.replace(/^```yaml persistence-change[^\S\n]*\n[\s\S]*?^```[^\S\n]*$/mu, machineBlock(change))
|
||||
if (prose === undefined) return source
|
||||
const headings = chinese ? ['概述', '兼容性', '验证'] : ['Summary', 'Compatibility', 'Verification']
|
||||
for (const [index, text] of [prose.summary, prose.compatibility, prose.verification].entries()) {
|
||||
const lines = source.split('\n')
|
||||
const heading = `## ${headings[index]}`
|
||||
const start = lines.indexOf(heading)
|
||||
if (start < 0 || lines.lastIndexOf(heading) !== start) throw new Error(`--prose requires one ${heading} section in the existing record`)
|
||||
let end = lines.findIndex((line, lineIndex) => lineIndex > start && /^##? /u.test(line))
|
||||
if (end < 0) end = lines.length
|
||||
let anchor = end
|
||||
while (anchor > start + 1 && lines[anchor - 1] === '') anchor -= 1
|
||||
if (/^<a id="[^"]+"><\/a>$/u.test(lines[anchor - 1] ?? '')) end = anchor - 1
|
||||
lines.splice(start + 1, end - start - 1, '', text.trim(), '')
|
||||
source = lines.join('\n')
|
||||
}
|
||||
return source
|
||||
}
|
||||
|
||||
function commandOperation(args: readonly string[]): CommandResult['operation'] {
|
||||
if (args.some(arg => arg === '--baseline' || arg.startsWith('--baseline='))) return 'baseline'
|
||||
if (args.some(arg => arg === '--record' || arg.startsWith('--record='))) return 'record'
|
||||
if (args.some(arg => arg === '--update' || arg.startsWith('--update='))) return 'update'
|
||||
return 'check'
|
||||
}
|
||||
|
||||
function executeCommand(
|
||||
args: readonly string[], root: string, extract: (root: string) => PersistenceSchemaInventory,
|
||||
artifacts: (root: string, current: PersistenceSchemaInventory) => readonly PersistenceArtifact[],
|
||||
): CommandResult {
|
||||
const { values } = parseArgs({ args: [...args], strict: true, allowPositionals: false, options: {
|
||||
check: { type: 'boolean' }, baseline: { type: 'string' }, record: { type: 'string' }, update: { type: 'string' },
|
||||
decision: { type: 'string' }, root: { type: 'string' }, prose: { type: 'string' }, json: { type: 'boolean' },
|
||||
} })
|
||||
if (values.root !== undefined) root = resolve(values.root)
|
||||
const selected = [values.check === true, values.baseline !== undefined, values.record !== undefined, values.update !== undefined]
|
||||
if (selected.filter(Boolean).length > 1) throw new Error('choose exactly one of --check, --baseline ID, --record ID, or --update ID')
|
||||
if (values.record === undefined && values.update === undefined && values.decision !== undefined) throw new Error('--decision requires --record or --update')
|
||||
const operation = commandOperation(args)
|
||||
if (operation === 'check' && values.prose !== undefined) throw new Error('--prose requires --baseline, --record, or --update')
|
||||
const prose = values.prose === undefined ? undefined : parsePersistenceProse(JSON.parse(readFileSync(resolve(root, values.prose), 'utf8')))
|
||||
const current = parsePersistenceSnapshot(extract(root))
|
||||
if (operation === 'check') {
|
||||
const history = verifyPersistenceChanges(root, current)
|
||||
return { schemaVersion: 1, ok: true, operation,
|
||||
message: `persistence changes: ${current.roots.length} roots match ${history.entries.length} history records.`, changes: [], roots: [], files: [] }
|
||||
}
|
||||
const baseline = operation === 'baseline'
|
||||
const update = operation === 'update'
|
||||
const id = identifier(values.baseline ?? values.record ?? values.update, 'record id')
|
||||
const directory = join(root, HISTORY_DIRECTORY)
|
||||
if (baseline && existsSync(directory) && readdirSync(directory).some(file => file.endsWith('.schema.json') || ID_PATTERN.test(file.replace(/\.md$/u, '')))) throw new Error('persistence baseline already exists; baseline creation cannot reset history')
|
||||
if (values.decision !== undefined && values.decision !== 'same-version' && values.decision !== 'version-bump') {
|
||||
throw new Error('--decision must be same-version or version-bump')
|
||||
}
|
||||
const entries = baseline ? [] : readPersistenceEntries(root, update ? id : undefined)
|
||||
const existing = update ? entries.find(entry => entry.record.id === id) : undefined
|
||||
if (update && existing === undefined) throw new Error(`${id}: cannot update a missing acknowledgement`)
|
||||
if (existing?.record.baseline === true) throw new Error('cannot update the persistence baseline')
|
||||
if (existing !== undefined && entries.some(entry => entry.record.changes.some(change => change.previous === id))) {
|
||||
throw new Error(`${id}: cannot update an acknowledgement with successors`)
|
||||
}
|
||||
const prior = entries.filter(entry => entry !== existing)
|
||||
const history = baseline ? undefined : validatePersistenceHistory(prior)
|
||||
const changed = baseline ? current.roots.map(root => root.key) : currentDifferences(history as PersistenceHistory, current)
|
||||
if (changed.length === 0) throw new Error('no persistence type changes to acknowledge')
|
||||
const differences = history === undefined ? [] : reportedDifferences(history, current)
|
||||
const decision = values.decision ?? (differences.some(change => change.requiresVersionBump) ? 'version-bump' : 'same-version')
|
||||
const roots = current.roots.filter(root => changed.includes(root.key))
|
||||
const change: PersistenceChangeRecord = { schemaVersion: 1, id, baseline, changes: changed.sort().map(key => ({
|
||||
root: key, previous: history?.tips.get(key)?.id ?? null,
|
||||
after: roots.find(root => root.key === key)?.digest ?? null, decision,
|
||||
})) }
|
||||
const snapshot: PersistenceSchemaInventory = { formatVersion: 1, roots, types: [] }
|
||||
validatePersistenceHistory([...prior, { record: change, snapshot }])
|
||||
const document = (chinese: boolean): string => {
|
||||
const supplied = chinese ? prose?.zh : prose?.en
|
||||
return existing === undefined ? scaffold(change, chinese, supplied)
|
||||
: updateDocument(readFileSync(join(directory, `${id}${chinese ? '.zh' : ''}.md`), 'utf8'), change, chinese, supplied)
|
||||
}
|
||||
const english = document(false)
|
||||
const chinese = document(true)
|
||||
parseDocument(english, `${id}.md`, prose === undefined && existing === undefined)
|
||||
parseDocument(chinese, `${id}.md`, prose === undefined && existing === undefined)
|
||||
const recordFiles = [
|
||||
...renderPersistencePair(root, `${HISTORY_DIRECTORY}/${id}.md`, english, chinese),
|
||||
{ path: `${HISTORY_DIRECTORY}/${id}.schema.json`, content: JSON.stringify(snapshot, null, 2) + '\n' },
|
||||
]
|
||||
if (!update && recordFiles.some(file => existsSync(join(root, file.path)))) throw new Error(`${id}: acknowledgement file already exists`)
|
||||
const outputs = [...artifacts(root, current), ...recordFiles]
|
||||
for (const file of outputs) mkdirSync(resolve(root, file.path, '..'), { recursive: true })
|
||||
for (const file of outputs) writeFileSync(resolve(root, file.path), file.content, { flag: recordFiles.includes(file) && !update ? 'wx' : 'w' })
|
||||
const completion = baseline
|
||||
? 'Complete both record documents and refresh their translation pairing.'
|
||||
: `Complete the compatibility and verification prose with --update ${id} --prose FILE.`
|
||||
const message = existing === undefined && prose === undefined
|
||||
? `Created ${HISTORY_DIRECTORY}/${id}.md and paired schema files. ${completion}`
|
||||
: `${update ? 'Updated' : 'Created'} ${HISTORY_DIRECTORY}/${id}.md; schema artifacts and bilingual pairing are current.`
|
||||
return { schemaVersion: 1, ok: true, operation, recordId: id, message,
|
||||
changes: differences,
|
||||
roots: rootTransitions(history, current), files: outputs.map(file => file.path) }
|
||||
}
|
||||
|
||||
/** Execute tree-only verification or author an explicit persistence acknowledgement.
|
||||
* @param args - check, baseline, record, or update arguments; --json selects structured output.
|
||||
* @param root - checkout root; defaults to this script's repository.
|
||||
* @param extract - current-source extraction function; fixtures supply their own source reader.
|
||||
* @param artifacts - renderer for current generated artifacts; fixtures may isolate the inventory artifact.
|
||||
* @returns text or one JSON result; JSON failures retain ok:false for the process entry point.
|
||||
*/
|
||||
export function runPersistenceChanges(
|
||||
args: readonly string[],
|
||||
root: string = resolve(import.meta.dirname, '..'),
|
||||
extract: (root: string) => PersistenceSchemaInventory = extractPersistenceSchema,
|
||||
artifacts: (root: string, current: PersistenceSchemaInventory) => readonly PersistenceArtifact[] = persistenceCatalogArtifacts,
|
||||
): string {
|
||||
try {
|
||||
const result = executeCommand(args, root, extract, artifacts)
|
||||
return args.includes('--json') ? JSON.stringify(result) : result.message
|
||||
} catch (error: unknown) {
|
||||
if (!args.includes('--json')) throw error
|
||||
const result: CommandResult = { schemaVersion: 1, ok: false, operation: commandOperation(args),
|
||||
message: error instanceof Error ? error.message : String(error),
|
||||
code: error instanceof PersistenceChangeFailure ? error.code : 'verification-failed',
|
||||
changes: error instanceof PersistenceChangeFailure ? error.changes : [],
|
||||
roots: error instanceof PersistenceChangeFailure ? error.roots : [], files: [] }
|
||||
return JSON.stringify(result)
|
||||
}
|
||||
}
|
||||
|
||||
if (process.argv[1] !== undefined && resolve(process.argv[1]) === import.meta.filename) {
|
||||
try {
|
||||
const output = runPersistenceChanges(process.argv.slice(2))
|
||||
console.log(output)
|
||||
if (process.argv.includes('--json') && !(JSON.parse(output) as { ok: boolean }).ok) process.exitCode = 1
|
||||
} catch (error: unknown) {
|
||||
console.error(error instanceof Error ? error.message : String(error))
|
||||
process.exitCode = 1
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,78 @@
|
||||
/** Render historical format references from complete, validated in-tree schemas. */
|
||||
|
||||
import { readFileSync } from 'node:fs'
|
||||
import { basename, join, posix } from 'node:path'
|
||||
import { renderPersistencePair, type PersistenceArtifact } from './persistence-artifacts.ts'
|
||||
import type { PersistenceFormatEntry, PersistenceFormats } from './persistence-formats.ts'
|
||||
import { renderPersistenceSchemaDefinitions, renderPersistenceSchemaIndex } from './render-persistence-schema.ts'
|
||||
|
||||
type Language = 'en' | 'zh'
|
||||
|
||||
function replaceRegion(source: string, name: string, content: string, path: string): string {
|
||||
const start = `<!-- persistence-format-${name}:start -->`
|
||||
const end = `<!-- persistence-format-${name}:end -->`
|
||||
const opening = source.indexOf(start)
|
||||
const closing = source.indexOf(end)
|
||||
if (opening < 0 || closing < opening || source.indexOf(start, opening + start.length) >= 0
|
||||
|| source.indexOf(end, closing + end.length) >= 0) throw new Error(`${path}: expected one ${name} factual block`)
|
||||
return source.slice(0, opening + start.length) + '\n\n' + content.trim() + '\n\n' + source.slice(closing)
|
||||
}
|
||||
|
||||
function historicalSchema(entry: PersistenceFormatEntry, language: Language): string {
|
||||
const schema = basename(entry.schemaPath)
|
||||
const introduction = language === 'en'
|
||||
? `The [complete machine inventory](${schema}) contains ${entry.inventory.roots.length} roots and ${entry.inventory.types.length} reachable types. Digests include all referenced fields; source names and paths describe the selected historical tree.`
|
||||
: `[完整机器目录](${schema})包含 ${entry.inventory.roots.length} 个根类型和 ${entry.inventory.types.length} 种可达类型。摘要包含所有引用字段;源码名称和路径描述所选的历史源码树。`
|
||||
return [
|
||||
'<a id="schema"></a>',
|
||||
language === 'en' ? '## Complete schemas' : '## 完整 schema',
|
||||
'',
|
||||
introduction,
|
||||
'',
|
||||
renderPersistenceSchemaIndex(entry.inventory, language, [], 3),
|
||||
'<details>',
|
||||
language === 'en' ? '<summary>Complete resolved types</summary>' : '<summary>完整解析类型</summary>',
|
||||
'',
|
||||
renderPersistenceSchemaDefinitions(entry.inventory, language, () => undefined, 3),
|
||||
'</details>',
|
||||
].join('\n')
|
||||
}
|
||||
|
||||
function formatIndex(formats: PersistenceFormats, language: Language): string {
|
||||
const path = (target: string): string => posix.relative('docs/persistence-changes/historical-formats',
|
||||
language === 'zh' && target.endsWith('.md') ? target.replace(/\.md$/u, '.zh.md') : target)
|
||||
return [
|
||||
language === 'en' ? '| Format | Source | Reference | Machine schema | Roots / types |' : '| 格式 | 来源 | 参考文档 | 机器 schema | 根类型 / 类型 |',
|
||||
'|---|---|---|---|---|',
|
||||
...formats.entries.map((entry) => {
|
||||
const source = entry.source === undefined ? language === 'en' ? 'Current checkout' : '当前工作树'
|
||||
: 'tag' in entry.source ? `\`${entry.source.tag}\`` : `PR #${entry.source.pullRequest}`
|
||||
const label = entry.version === formats.currentVersion ? language === 'en' ? 'Current catalog' : '当前目录' : `V${entry.version}`
|
||||
return `| ${entry.version} | ${source} | [${label}](${path(entry.document)}) | [JSON](${path(entry.schemaPath)}) | ${entry.inventory.roots.length} / ${entry.inventory.types.length} |`
|
||||
}),
|
||||
].join('\n')
|
||||
}
|
||||
|
||||
/**
|
||||
* Refresh bounded schema regions and the format index, preserving authored evidence.
|
||||
* @param root - repository with both document languages and factual markers.
|
||||
* @param formats - complete validated versions through the current writer.
|
||||
* @returns paired references and consistency records without modifying files.
|
||||
*/
|
||||
export function persistenceFormatFactArtifacts(root: string, formats: PersistenceFormats): PersistenceArtifact[] {
|
||||
const artifacts: PersistenceArtifact[] = []
|
||||
for (const entry of formats.entries.filter(entry => entry.version < formats.currentVersion)) {
|
||||
const render = (language: Language): string => {
|
||||
const path = language === 'en' ? entry.document : entry.document.replace(/\.md$/u, '.zh.md')
|
||||
return replaceRegion(readFileSync(join(root, path), 'utf8'), 'schema', historicalSchema(entry, language), path)
|
||||
}
|
||||
artifacts.push(...renderPersistencePair(root, entry.document, render('en'), render('zh')))
|
||||
}
|
||||
const index = 'docs/persistence-changes/historical-formats/README.md'
|
||||
const renderIndex = (language: Language): string => {
|
||||
const path = language === 'en' ? index : index.replace(/\.md$/u, '.zh.md')
|
||||
return replaceRegion(readFileSync(join(root, path), 'utf8'), 'index', formatIndex(formats, language), path)
|
||||
}
|
||||
artifacts.push(...renderPersistencePair(root, index, renderIndex('en'), renderIndex('zh')))
|
||||
return artifacts
|
||||
}
|
||||
@@ -0,0 +1,476 @@
|
||||
/** Format reference coverage follows the writer version and retains complete historical schemas. */
|
||||
|
||||
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { join } from 'node:path'
|
||||
import { dump } from 'js-yaml'
|
||||
import { afterEach, describe, expect, it } from 'vitest'
|
||||
import { loadPersistenceFormats, runPersistenceFormats } from './persistence-formats.ts'
|
||||
import { parseHistoricalPersistenceSnapshot } from './persistence-changes.ts'
|
||||
import { canonicalizeSchema, schemaDigest } from './persistence-schema-model.ts'
|
||||
import type { PersistenceRoot, PersistenceSchemaInventory, PersistenceType, SchemaNode } from './persistence-schema-model.ts'
|
||||
|
||||
const temporary: string[] = []
|
||||
afterEach(() => { for (const root of temporary.splice(0)) rmSync(root, { recursive: true, force: true }) })
|
||||
|
||||
function rootSchema(metadata: Omit<PersistenceRoot, 'schema' | 'digest'>, nodes: readonly SchemaNode[]): PersistenceRoot {
|
||||
const schema = canonicalizeSchema(nodes, 0)
|
||||
return { ...metadata, schema, digest: schemaDigest(schema) }
|
||||
}
|
||||
|
||||
function completeInventory(roots: readonly PersistenceRoot[]): PersistenceSchemaInventory {
|
||||
const types = new Map<string, PersistenceType>()
|
||||
for (const root of roots) {
|
||||
root.schema.nodes.forEach((_, index) => {
|
||||
const schema = canonicalizeSchema(root.schema.nodes, index)
|
||||
const digest = schemaDigest(schema)
|
||||
types.set(digest, { digest, schema, names: [], sources: [] })
|
||||
})
|
||||
}
|
||||
return { formatVersion: 1, roots, types: [...types.values()] }
|
||||
}
|
||||
|
||||
function header(key: string, version: number | 'number', optional = false): PersistenceRoot {
|
||||
return rootSchema({ key, kind: 'header' }, [
|
||||
{ kind: 'object', indices: [], properties: [{ name: 'version', type: 1, optional }] },
|
||||
version === 'number' ? { kind: 'primitive', type: 'number' } : { kind: 'literal', value: version },
|
||||
])
|
||||
}
|
||||
|
||||
function inventory(version: number): PersistenceSchemaInventory {
|
||||
return completeInventory([
|
||||
header('SessionHeader', version), header('JsonlHeaderLine', 'number'),
|
||||
rootSchema({ key: 'SessionEventEnvelope', kind: 'envelope' }, [{ kind: 'object', indices: [], properties: [] }]),
|
||||
rootSchema({ key: 'event:example/value', kind: 'event', event: 'example/value', surface: false }, [
|
||||
{ kind: 'object', indices: [], properties: [{ name: 'type', type: 1, optional: false }, { name: 'data', type: 2, optional: false }] },
|
||||
{ kind: 'literal', value: 'example/value' }, { kind: 'primitive', type: 'string' },
|
||||
]),
|
||||
])
|
||||
}
|
||||
|
||||
function write(root: string, path: string, content: string): void {
|
||||
writeFileSync(join(root, path), content)
|
||||
}
|
||||
|
||||
function schemaPath(version: number, currentVersion: number): string {
|
||||
return version === currentVersion ? 'docs/persistence-schema.json' : `docs/persistence-changes/historical-formats/v${version}.schema.json`
|
||||
}
|
||||
|
||||
function replaceSnapshot(root: string, version: number, currentVersion: number, snapshot: PersistenceSchemaInventory): void {
|
||||
write(root, schemaPath(version, currentVersion), JSON.stringify(snapshot))
|
||||
}
|
||||
|
||||
function saveReference(root: string, version: number, currentVersion: number, snapshot = inventory(version)): void {
|
||||
const current = version === currentVersion
|
||||
const filename = current ? 'persistence-catalog' : `persistence-changes/historical-formats/v${version}`
|
||||
const schemaName = current ? 'persistence-schema.json' : `v${version}.schema.json`
|
||||
const record = {
|
||||
schemaVersion: 1, sessionFormatVersion: version,
|
||||
source: version === 1 ? { pullRequest: 3349 } : { tag: 'dsh-v0.1.0-rc.5' },
|
||||
roots: Object.fromEntries(snapshot.roots.map(root => [root.key, root.digest])),
|
||||
}
|
||||
const lines = [
|
||||
...current ? [] : ['---', 'kind: persistence-format', '---', '', '```yaml persistence-format', dump(record).trimEnd(), '```', ''],
|
||||
`# Session format v${version}`, '', `[Inventory](${schemaName})`, '', '| Root | Kind | SHA-256 |', '|---|---|---|',
|
||||
...snapshot.roots.map(root => `| \`${root.key}\` | ${root.kind} | \`${root.digest}\` |`), '',
|
||||
]
|
||||
for (const suffix of ['.md', '.zh.md']) write(root, `docs/${filename}${suffix}`, lines.join('\n'))
|
||||
replaceSnapshot(root, version, currentVersion, snapshot)
|
||||
}
|
||||
|
||||
function fixture(currentVersion = 3): string {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-persistence-formats-'))
|
||||
temporary.push(root)
|
||||
mkdirSync(join(root, 'packages/core/session/src'), { recursive: true })
|
||||
mkdirSync(join(root, 'docs/persistence-changes/historical-formats'), { recursive: true })
|
||||
write(root, 'packages/core/session/src/types.ts', `export const SESSION_FORMAT_VERSION = ${currentVersion} as const\n`)
|
||||
for (let version = 0; version <= currentVersion; version += 1) saveReference(root, version, currentVersion)
|
||||
return root
|
||||
}
|
||||
|
||||
function edit(root: string, path: string, from: string, to: string): void {
|
||||
const source = readFileSync(join(root, path), 'utf8')
|
||||
expect(source).toContain(from)
|
||||
write(root, path, source.replace(from, to))
|
||||
}
|
||||
|
||||
function editPair(root: string, version: number, from: string, to: string): void {
|
||||
for (const suffix of ['.md', '.zh.md']) edit(root, `docs/persistence-changes/historical-formats/v${version}${suffix}`, from, to)
|
||||
}
|
||||
|
||||
function prepareFacts(root: string, currentVersion = 3): void {
|
||||
for (const suffix of ['.md', '.zh.md']) {
|
||||
for (let version = 0; version < currentVersion; version += 1) {
|
||||
const path = `docs/persistence-changes/historical-formats/v${version}${suffix}`
|
||||
const switcher = suffix === '.md' ? `English | [中文](v${version}.zh.md)` : `[English](v${version}.md) | 中文`
|
||||
write(root, path, readFileSync(join(root, path), 'utf8') + `\n${switcher}\n\n<!-- persistence-format-schema:start -->\n\nPending schemas.\n\n<!-- persistence-format-schema:end -->\n`)
|
||||
}
|
||||
const switcher = suffix === '.md' ? 'English | [中文](README.zh.md)' : '[English](README.md) | 中文'
|
||||
write(root, `docs/persistence-changes/historical-formats/README${suffix}`, `# Session formats\n\n${switcher}\n\nAuthored context.\n\n<!-- persistence-format-index:start -->\n\nPending formats.\n\n<!-- persistence-format-index:end -->\n`)
|
||||
}
|
||||
}
|
||||
|
||||
describe('archive current persistence format', () => {
|
||||
it('keeps every reachable type and drops extractor-retained types and source line numbers', () => {
|
||||
const root = fixture()
|
||||
const original = inventory(3)
|
||||
const sources = [
|
||||
'packages/example/src/types.ts:12', 'packages/other/src/types.ts:8:2', 'packages/example/src/types.ts:34:5',
|
||||
'packages/plain/src/types.ts', 'packages/fragment/src/types.ts#L8', 'packages/fragment/src/types.ts#L8-L12',
|
||||
]
|
||||
const types = original.types.map(type => ({ ...type, names: ['Example'], sources }))
|
||||
const schema = canonicalizeSchema([{ kind: 'literal', value: 'unreferenced' }], 0)
|
||||
replaceSnapshot(root, 3, 3, { ...original, types: [...types, { schema, digest: schemaDigest(schema), names: [], sources: [] }] })
|
||||
const before = readFileSync(join(root, 'docs/persistence-schema.json'), 'utf8')
|
||||
|
||||
expect(runPersistenceFormats(['--archive', '3'], root)).toBe('Archived Session format v3 to docs/persistence-changes/historical-formats/v3.schema.json.')
|
||||
const serialized = readFileSync(join(root, 'docs/persistence-changes/historical-formats/v3.schema.json'), 'utf8')
|
||||
const archived = parseHistoricalPersistenceSnapshot(JSON.parse(serialized))
|
||||
expect(archived).toEqual({
|
||||
...original,
|
||||
types: types.map(type => ({ ...type, sources: [
|
||||
'packages/example/src/types.ts', 'packages/other/src/types.ts', 'packages/plain/src/types.ts', 'packages/fragment/src/types.ts',
|
||||
] })),
|
||||
})
|
||||
expect(serialized).toBe(JSON.stringify(archived, null, 2) + '\n')
|
||||
expect(readFileSync(join(root, 'docs/persistence-schema.json'), 'utf8')).toBe(before)
|
||||
expect(existsSync(join(root, 'docs/persistence-changes/historical-formats/v3.md'))).toBe(false)
|
||||
|
||||
saveReference(root, 3, 4, archived)
|
||||
write(root, 'packages/core/session/src/types.ts', 'export const SESSION_FORMAT_VERSION = 4 as const\n')
|
||||
saveReference(root, 4, 4)
|
||||
expect(loadPersistenceFormats(root).entries[3]?.inventory).toEqual(archived)
|
||||
})
|
||||
|
||||
it('creates the first archive directory and honors --root', () => {
|
||||
const root = fixture(0)
|
||||
rmSync(join(root, 'docs/persistence-changes/historical-formats'), { recursive: true })
|
||||
expect(runPersistenceFormats(['--root', root, '--archive', '0'])).toBe('Archived Session format v0 to docs/persistence-changes/historical-formats/v0.schema.json.')
|
||||
expect(JSON.parse(readFileSync(join(root, 'docs/persistence-changes/historical-formats/v0.schema.json'), 'utf8'))).toEqual(inventory(0))
|
||||
})
|
||||
|
||||
it.each(['-1', '1.5', '01', '3junk', '9007199254740992'])('rejects an invalid archive version %s', (version) => {
|
||||
const root = fixture()
|
||||
expect(() => runPersistenceFormats([`--archive=${version}`], root)).toThrow('--archive must be a non-negative safe integer')
|
||||
expect(existsSync(join(root, 'docs/persistence-changes/historical-formats/v3.schema.json'))).toBe(false)
|
||||
})
|
||||
|
||||
it.each(['2', '4'])('rejects archive v%s when the current writer is v3', (version) => {
|
||||
const root = fixture()
|
||||
expect(() => runPersistenceFormats(['--archive', version], root)).toThrow(`Cannot archive v${version}: current writer is v3`)
|
||||
expect(existsSync(join(root, 'docs/persistence-changes/historical-formats/v3.schema.json'))).toBe(false)
|
||||
})
|
||||
|
||||
it('refuses to overwrite an existing archive', () => {
|
||||
const root = fixture()
|
||||
write(root, 'docs/persistence-changes/historical-formats/v3.schema.json', 'Retained history.\n')
|
||||
expect(() => runPersistenceFormats(['--archive', '3'], root)).toThrow('docs/persistence-changes/historical-formats/v3.schema.json already exists')
|
||||
expect(readFileSync(join(root, 'docs/persistence-changes/historical-formats/v3.schema.json'), 'utf8')).toBe('Retained history.\n')
|
||||
})
|
||||
|
||||
it('rejects --archive with --write before writing', () => {
|
||||
const root = fixture()
|
||||
expect(() => runPersistenceFormats(['--archive', '3', '--write'], root)).toThrow('--archive and --write cannot be combined')
|
||||
expect(existsSync(join(root, 'docs/persistence-changes/historical-formats/v3.schema.json'))).toBe(false)
|
||||
})
|
||||
|
||||
it.each(['invalid-json', 'digest-drift', 'missing-type', 'missing-source-metadata', 'outdated-header'])('rejects %s before creating an archive', (variant) => {
|
||||
const root = fixture()
|
||||
const original = inventory(3)
|
||||
if (variant === 'invalid-json') write(root, 'docs/persistence-schema.json', '{')
|
||||
else if (variant === 'digest-drift') replaceSnapshot(root, 3, 3, { ...original, roots: [{ ...original.roots[0]!, digest: '0'.repeat(64) }, ...original.roots.slice(1)] })
|
||||
else if (variant === 'missing-type') replaceSnapshot(root, 3, 3, { ...original, types: original.types.slice(1) })
|
||||
else if (variant === 'missing-source-metadata') edit(root, 'docs/persistence-schema.json', ',"sources":[]', '')
|
||||
else replaceSnapshot(root, 3, 3, inventory(2))
|
||||
expect(() => runPersistenceFormats(['--archive', '3'], root)).toThrow(variant === 'invalid-json' ? SyntaxError
|
||||
: variant === 'digest-drift' ? 'schema digest mismatch' : variant === 'missing-type' ? 'cover every reachable type'
|
||||
: variant === 'missing-source-metadata' ? 'missing field sources' : 'SessionHeader.version must match')
|
||||
expect(existsSync(join(root, 'docs/persistence-changes/historical-formats/v3.schema.json'))).toBe(false)
|
||||
})
|
||||
})
|
||||
|
||||
describe('complete persistence format references', () => {
|
||||
it.each(['.md', '.zh.md'])('rejects source coordinates in authored format evidence in %s', (suffix) => {
|
||||
const root = fixture()
|
||||
const path = `docs/persistence-changes/historical-formats/v1${suffix}`
|
||||
const original = readFileSync(join(root, path), 'utf8')
|
||||
for (const position of [':36', ':36:2', '#L36', '#L36-L38']) {
|
||||
write(root, path, original + `\nSource: \`packages/core/session/src/types.ts${position}\`.\n`)
|
||||
expect(() => loadPersistenceFormats(root)).toThrow('historical source references must omit line numbers')
|
||||
}
|
||||
write(root, path, original + '\nSource: `packages/core/session/src/types.ts`.\n')
|
||||
expect(loadPersistenceFormats(root).entries).toHaveLength(4)
|
||||
})
|
||||
|
||||
it('loads a contiguous archive and the current catalog without Git or historical package sources', () => {
|
||||
const formats = loadPersistenceFormats(fixture())
|
||||
expect(formats.currentVersion).toBe(3)
|
||||
expect(formats.entries.map(entry => entry.version)).toEqual([0, 1, 2, 3])
|
||||
expect(formats.entries[0]?.source).toEqual({ tag: 'dsh-v0.1.0-rc.5' })
|
||||
expect(formats.entries[1]?.source).toEqual({ pullRequest: 3349 })
|
||||
expect(formats.entries[3]).toMatchObject({ document: 'docs/persistence-catalog.md', schemaPath: 'docs/persistence-schema.json' })
|
||||
expect(formats.entries[3]?.source).toBeUndefined()
|
||||
})
|
||||
|
||||
it('accepts a version-zero writer without a historical directory', () => {
|
||||
const root = fixture(0)
|
||||
rmSync(join(root, 'docs/persistence-changes/historical-formats'), { recursive: true })
|
||||
expect(loadPersistenceFormats(root).entries).toHaveLength(1)
|
||||
})
|
||||
|
||||
it.each(['.md', '.zh.md', '.schema.json'])('requires every historical companion %s', (suffix) => {
|
||||
const root = fixture()
|
||||
rmSync(join(root, `docs/persistence-changes/historical-formats/v1${suffix}`))
|
||||
expect(() => loadPersistenceFormats(root)).toThrow(`missing persistence format artifact v1${suffix}`)
|
||||
})
|
||||
|
||||
it('rejects a gap even when all remaining versions have complete companions', () => {
|
||||
const root = fixture()
|
||||
for (const suffix of ['.md', '.zh.md', '.schema.json']) rmSync(join(root, `docs/persistence-changes/historical-formats/v1${suffix}`))
|
||||
expect(() => loadPersistenceFormats(root)).toThrow('v1: missing persistence format artifact')
|
||||
})
|
||||
|
||||
it.each(['persistence-catalog.md', 'persistence-catalog.zh.md', 'persistence-schema.json'])('requires the current reference artifact %s', (filename) => {
|
||||
const root = fixture()
|
||||
rmSync(join(root, `docs/${filename}`))
|
||||
expect(() => loadPersistenceFormats(root)).toThrow(`missing persistence format artifact docs/${filename}`)
|
||||
})
|
||||
|
||||
it('requires a formerly current archive when the writer advances', () => {
|
||||
const root = fixture()
|
||||
write(root, 'packages/core/session/src/types.ts', 'export const SESSION_FORMAT_VERSION = 4 as const\n')
|
||||
saveReference(root, 4, 4)
|
||||
expect(() => loadPersistenceFormats(root)).toThrow('v3: missing persistence format artifact')
|
||||
saveReference(root, 3, 4)
|
||||
expect(loadPersistenceFormats(root).entries.map(entry => entry.version)).toEqual([0, 1, 2, 3, 4])
|
||||
})
|
||||
|
||||
it.each(['v3.md', 'v9.schema.json', 'v01.md', 'v-1.md', 'v2.schema.yaml', 'v3.i18n.yaml'])('rejects unexpected or duplicate format filename %s', (filename) => {
|
||||
const root = fixture()
|
||||
write(root, `docs/persistence-changes/historical-formats/${filename}`, '{}')
|
||||
expect(() => loadPersistenceFormats(root)).toThrow(`unexpected persistence format artifact ${filename}`)
|
||||
})
|
||||
|
||||
it('rejects bilingual declarations that differ', () => {
|
||||
const root = fixture()
|
||||
edit(root, 'docs/persistence-changes/historical-formats/v1.zh.md', 'pullRequest: 3349', 'pullRequest: 3397')
|
||||
expect(() => loadPersistenceFormats(root)).toThrow('bilingual machine records differ')
|
||||
})
|
||||
|
||||
it.each([
|
||||
['kind: persistence-format', 'kind: persistence-release', 'frontmatter kind'],
|
||||
['sessionFormatVersion: 1', 'sessionFormatVersion: 0', 'must match its filename'],
|
||||
['schemaVersion: 1', 'schemaVersion: 2', 'unsupported persistence format record schema version'],
|
||||
['pullRequest: 3349', 'pullRequest: 0', 'positive integer'],
|
||||
['pullRequest: 3349', 'pullRequest: 1.5', 'positive integer'],
|
||||
['pullRequest: 3349', 'pullRequest: 3349\n tag: dsh-v0.1.0', 'expected fields'],
|
||||
['pullRequest: 3349', 'other: 3349', 'expected fields'],
|
||||
['source:\n pullRequest: 3349', 'source: null', 'expected an object'],
|
||||
['schemaVersion: 1', 'schemaVersion: 1\nunknown: true', 'expected fields'],
|
||||
])('rejects inconsistent machine data: %s', (from, to, error) => {
|
||||
const root = fixture()
|
||||
editPair(root, 1, from, to)
|
||||
expect(() => loadPersistenceFormats(root)).toThrow(error)
|
||||
})
|
||||
|
||||
it('rejects a source tag outside the DSH release namespace', () => {
|
||||
const root = fixture()
|
||||
editPair(root, 0, 'tag: dsh-v0.1.0-rc.5', 'tag: latest')
|
||||
expect(() => loadPersistenceFormats(root)).toThrow('invalid source tag')
|
||||
})
|
||||
|
||||
it.each(['missing', 'extra', 'wrong-digest'])('rejects a %s recorded root', (variant) => {
|
||||
const root = fixture()
|
||||
const digest = inventory(1).roots[0]!.digest
|
||||
const from = variant === 'extra' ? 'roots:\n' : ` SessionHeader: ${digest}\n`
|
||||
const to = variant === 'missing' ? '' : variant === 'extra' ? `roots:\n event:undeclared: ${'f'.repeat(64)}\n`
|
||||
: ` SessionHeader: ${'f'.repeat(64)}\n`
|
||||
editPair(root, 1, from, to)
|
||||
expect(() => loadPersistenceFormats(root)).toThrow('recorded roots do not match the complete schema inventory')
|
||||
})
|
||||
|
||||
it.each(['unknown-key', 'invalid-digest', 'duplicate-key', 'not-a-mapping'])('rejects invalid recorded roots: %s', (variant) => {
|
||||
const root = fixture()
|
||||
const digest = inventory(1).roots[0]!.digest
|
||||
const from = variant === 'not-a-mapping' ? dump({ roots: Object.fromEntries(inventory(1).roots.map(root => [root.key, root.digest])) })
|
||||
: ` SessionHeader: ${digest}\n`
|
||||
const to = variant === 'unknown-key' ? ` unknown: ${digest}\n` : variant === 'invalid-digest' ? ' SessionHeader: invalid\n'
|
||||
: variant === 'duplicate-key' ? from + from : 'roots: []\n'
|
||||
editPair(root, 1, from, to)
|
||||
expect(() => loadPersistenceFormats(root)).toThrow(variant === 'duplicate-key' ? 'duplicated mapping key'
|
||||
: variant === 'not-a-mapping' ? 'roots must be a mapping' : 'invalid recorded root')
|
||||
})
|
||||
|
||||
it.each(['missing', 'duplicate'])('rejects a %s machine block', (variant) => {
|
||||
const root = fixture()
|
||||
for (const suffix of ['.md', '.zh.md']) {
|
||||
const path = `docs/persistence-changes/historical-formats/v1${suffix}`
|
||||
const text = readFileSync(join(root, path), 'utf8')
|
||||
write(root, path, variant === 'missing' ? text.replace('```yaml persistence-format', '```yaml') : text + '\n```yaml persistence-format\n{}\n```\n')
|
||||
}
|
||||
expect(() => loadPersistenceFormats(root)).toThrow('expected exactly one persistence-format machine record')
|
||||
})
|
||||
|
||||
it.each(['SessionHeader', 'JsonlHeaderLine', 'SessionEventEnvelope', 'event:example/value'])('rejects an inventory missing %s', (key) => {
|
||||
const root = fixture()
|
||||
replaceSnapshot(root, 1, 3, completeInventory(inventory(1).roots.filter(root => root.key !== key)))
|
||||
expect(() => loadPersistenceFormats(root)).toThrow(key.startsWith('event:') ? 'must include an event root' : `missing schema root ${key}`)
|
||||
})
|
||||
|
||||
it.each([0, 1, 2, 3])('rejects a mismatched header version at v%s', (version) => {
|
||||
const root = fixture()
|
||||
replaceSnapshot(root, version, 3, completeInventory(inventory(version).roots.map(root => root.key === 'SessionHeader' ? header(root.key, version + 1) : root)))
|
||||
expect(() => loadPersistenceFormats(root)).toThrow('SessionHeader.version must match')
|
||||
})
|
||||
|
||||
it('retains historical number declarations but requires the current logical header literal', () => {
|
||||
const root = fixture()
|
||||
for (const version of [0, 1, 2]) {
|
||||
saveReference(root, version, 3, completeInventory(inventory(version).roots.map(root => root.key === 'SessionHeader' ? header(root.key, 'number') : root)))
|
||||
}
|
||||
expect(loadPersistenceFormats(root).entries).toHaveLength(4)
|
||||
replaceSnapshot(root, 3, 3, completeInventory(inventory(3).roots.map(root => root.key === 'SessionHeader' ? header(root.key, 'number') : root)))
|
||||
expect(() => loadPersistenceFormats(root)).toThrow('SessionHeader.version must match the current writer version')
|
||||
})
|
||||
|
||||
it.each(['SessionHeader', 'JsonlHeaderLine'])('requires a present %s version property', (key) => {
|
||||
const root = fixture()
|
||||
replaceSnapshot(root, 1, 3, completeInventory(inventory(1).roots.map(root => root.key === key ? header(key, 1, true) : root)))
|
||||
expect(() => loadPersistenceFormats(root)).toThrow(`${key}.version must match`)
|
||||
})
|
||||
|
||||
it('uses historical surface rules only for historical references', () => {
|
||||
const root = fixture()
|
||||
const event = rootSchema({ key: 'event:example/value', kind: 'event', event: 'example/value', surface: true }, [
|
||||
{ kind: 'object', indices: [], properties: [
|
||||
{ name: 'type', type: 1, optional: false }, { name: 'surfaceOp', type: 2, optional: true },
|
||||
] },
|
||||
{ kind: 'literal', value: 'example/value' }, { kind: 'primitive', type: 'string' },
|
||||
])
|
||||
saveReference(root, 1, 3, completeInventory(inventory(1).roots.map(root => root.kind === 'event' ? event : root)))
|
||||
expect(loadPersistenceFormats(root).entries).toHaveLength(4)
|
||||
replaceSnapshot(root, 3, 3, completeInventory(inventory(3).roots.map(root => root.kind === 'event' ? event : root)))
|
||||
expect(() => loadPersistenceFormats(root)).toThrow('surface metadata does not match its schema')
|
||||
})
|
||||
|
||||
it.each(['missing', 'duplicate', 'extra'])('rejects %s reachable type coverage', (variant) => {
|
||||
const root = fixture()
|
||||
const original = inventory(1)
|
||||
const extraSchema = canonicalizeSchema([{ kind: 'literal', value: 'unreferenced' }], 0)
|
||||
const types = variant === 'missing' ? original.types.slice(1)
|
||||
: variant === 'duplicate' ? [...original.types, original.types[0]!]
|
||||
: [...original.types, { schema: extraSchema, digest: schemaDigest(extraSchema), names: [], sources: [] }]
|
||||
replaceSnapshot(root, 1, 3, { ...original, types })
|
||||
expect(() => loadPersistenceFormats(root)).toThrow(variant === 'missing' ? 'cover every reachable type' : variant === 'duplicate' ? 'duplicate schema type' : 'unreferenced schema type')
|
||||
})
|
||||
|
||||
it('permits extractor-retained unreachable types only in the current inventory', () => {
|
||||
const root = fixture()
|
||||
const original = inventory(3)
|
||||
const schema = canonicalizeSchema([{ kind: 'literal', value: false }], 0)
|
||||
replaceSnapshot(root, 3, 3, {
|
||||
...original, types: [...original.types, { schema, digest: schemaDigest(schema), names: [], sources: [] }],
|
||||
})
|
||||
expect(loadPersistenceFormats(root).entries).toHaveLength(4)
|
||||
})
|
||||
|
||||
it.each(['duplicate-root', 'invalid-digest', 'invalid-graph', 'unexpected-field'])('rejects malformed schema inventory: %s', (variant) => {
|
||||
const root = fixture()
|
||||
const original = inventory(1)
|
||||
const first = original.roots[0]!
|
||||
const changed = variant === 'duplicate-root' ? { ...original, roots: [...original.roots, first] }
|
||||
: variant === 'invalid-digest' ? { ...original, roots: [{ ...first, digest: '0'.repeat(64) }, ...original.roots.slice(1)] }
|
||||
: variant === 'invalid-graph' ? { ...original, roots: [{ ...first, schema: { root: 0, nodes: [{ kind: 'array', element: 99 }] } }, ...original.roots.slice(1)] }
|
||||
: { ...original, extra: true }
|
||||
write(root, schemaPath(1, 3), JSON.stringify(changed))
|
||||
expect(() => loadPersistenceFormats(root)).toThrow(variant === 'duplicate-root' ? 'duplicate schema root' : variant === 'invalid-digest' ? 'schema digest mismatch' : variant === 'invalid-graph' ? 'unknown schema node' : 'unknown field extra')
|
||||
})
|
||||
|
||||
it.each(['persistence-changes/historical-formats/v1.md', 'persistence-changes/historical-formats/v1.zh.md', 'persistence-catalog.md', 'persistence-catalog.zh.md'])('requires the matching schema link in %s', (document) => {
|
||||
const root = fixture()
|
||||
const schema = document.startsWith('persistence-changes/historical-formats/') ? 'v1.schema.json' : 'persistence-schema.json'
|
||||
edit(root, `docs/${document}`, `](${schema})`, '](wrong.schema.json)')
|
||||
expect(() => loadPersistenceFormats(root)).toThrow(`missing link to ${schema}`)
|
||||
})
|
||||
|
||||
it.each(['persistence-catalog.md', 'persistence-catalog.zh.md'])('rejects a placeholder current catalog in %s', (document) => {
|
||||
const root = fixture()
|
||||
write(root, `docs/${document}`, '# Placeholder\n\n[Inventory](persistence-schema.json)\n')
|
||||
expect(() => loadPersistenceFormats(root)).toThrow('missing schema index entry for SessionHeader')
|
||||
})
|
||||
|
||||
it('checks generated schema regions and refreshes them without changing the recorded schemas or authored context', () => {
|
||||
const root = fixture()
|
||||
prepareFacts(root)
|
||||
const paths = [0, 1, 2, 3].map(version => schemaPath(version, 3))
|
||||
const before = paths.map(path => readFileSync(join(root, path), 'utf8'))
|
||||
expect(() => runPersistenceFormats([], root)).toThrow('Stale persistence format facts')
|
||||
expect(runPersistenceFormats(['--write'], root)).toContain('Refreshed')
|
||||
expect(runPersistenceFormats([], root)).toBe('Persistence formats: v0 through v3 verified (4 complete references).')
|
||||
expect(paths.map(path => readFileSync(join(root, path), 'utf8'))).toEqual(before)
|
||||
const index = readFileSync(join(root, 'docs/persistence-changes/historical-formats/README.md'), 'utf8')
|
||||
expect(index).toContain('Authored context.')
|
||||
expect(index).toContain('[V1](v1.md) | [JSON](v1.schema.json)')
|
||||
expect(index).toContain('[Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json)')
|
||||
const translatedIndex = readFileSync(join(root, 'docs/persistence-changes/historical-formats/README.zh.md'), 'utf8')
|
||||
expect(translatedIndex).toContain('[V1](v1.zh.md) | [JSON](v1.schema.json)')
|
||||
expect(translatedIndex).toContain('[当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json)')
|
||||
const english = readFileSync(join(root, 'docs/persistence-changes/historical-formats/v1.md'), 'utf8')
|
||||
expect(english).toContain('pullRequest: 3349')
|
||||
const [visible, collapsed] = english.split('<details>')
|
||||
expect(visible).toContain('\n## Complete schemas\n')
|
||||
expect(visible).toContain('\n### Persistence type fingerprints\n')
|
||||
expect(collapsed).toContain('\n### Resolved persistence types\n')
|
||||
expect(collapsed).toContain('\n#### `SessionHeader`\n')
|
||||
expect(english.match(/^## /gmu)).toHaveLength(1)
|
||||
expect(english.match(/^### /gmu)).toHaveLength(2)
|
||||
expect(english.match(/^#### /gmu)).toHaveLength(inventory(1).types.length)
|
||||
edit(root, 'docs/persistence-changes/historical-formats/v1.md', '<summary>Complete resolved types</summary>', '<summary>Missing definitions</summary>')
|
||||
expect(() => runPersistenceFormats([], root)).toThrow('Stale persistence format facts')
|
||||
})
|
||||
|
||||
it('renders a format index for a current version-zero writer', () => {
|
||||
const root = fixture(0)
|
||||
prepareFacts(root, 0)
|
||||
runPersistenceFormats(['--write'], root)
|
||||
expect(runPersistenceFormats([], root)).toBe('Persistence formats: v0 through v0 verified (1 complete reference).')
|
||||
})
|
||||
|
||||
it.each(['missing', 'stale'])('rejects a %s format pairing record and refreshes it with --write', (variant) => {
|
||||
const root = fixture()
|
||||
prepareFacts(root)
|
||||
runPersistenceFormats(['--write'], root)
|
||||
const sidecar = 'docs/persistence-changes/historical-formats/v1.i18n.yaml'
|
||||
if (variant === 'missing') rmSync(join(root, sidecar))
|
||||
else write(root, sidecar, 'schemaVersion: 1\n')
|
||||
expect(() => runPersistenceFormats([], root)).toThrow(`Stale persistence format facts: ${sidecar}`)
|
||||
runPersistenceFormats(['--write'], root)
|
||||
expect(() => runPersistenceFormats([], root)).not.toThrow()
|
||||
})
|
||||
|
||||
it('refuses to refresh facts until every format reference passes validation', () => {
|
||||
const root = fixture()
|
||||
prepareFacts(root)
|
||||
const index = readFileSync(join(root, 'docs/persistence-changes/historical-formats/README.md'), 'utf8')
|
||||
rmSync(join(root, 'docs/persistence-changes/historical-formats/v1.schema.json'))
|
||||
expect(() => runPersistenceFormats(['--write'], root)).toThrow('missing persistence format artifact')
|
||||
expect(readFileSync(join(root, 'docs/persistence-changes/historical-formats/README.md'), 'utf8')).toBe(index)
|
||||
})
|
||||
|
||||
it('refuses to refresh an archive after an event and all its types are removed from its schema', () => {
|
||||
const root = fixture()
|
||||
const retained = rootSchema({ key: 'event:example/retained', kind: 'event', event: 'example/retained', surface: false }, [
|
||||
{ kind: 'object', indices: [], properties: [{ name: 'type', type: 1, optional: false }] },
|
||||
{ kind: 'literal', value: 'example/retained' },
|
||||
])
|
||||
const complete = completeInventory([...inventory(1).roots, retained])
|
||||
saveReference(root, 1, 3, complete)
|
||||
prepareFacts(root)
|
||||
runPersistenceFormats(['--write'], root)
|
||||
const document = 'docs/persistence-changes/historical-formats/v1.md'
|
||||
const before = readFileSync(join(root, document), 'utf8')
|
||||
replaceSnapshot(root, 1, 3, completeInventory(complete.roots.filter(root => root.key !== 'event:example/value')))
|
||||
expect(() => runPersistenceFormats(['--write'], root)).toThrow('recorded roots do not match the complete schema inventory')
|
||||
expect(readFileSync(join(root, document), 'utf8')).toBe(before)
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,230 @@
|
||||
/** Archive and verify complete Session format references through the current writer. */
|
||||
|
||||
import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
|
||||
import { join, resolve } from 'node:path'
|
||||
import { parseArgs } from 'node:util'
|
||||
import { JSON_SCHEMA, load } from 'js-yaml'
|
||||
import { readCurrentSessionFormatVersion } from './gen-session-format-catalog.ts'
|
||||
import { parseHistoricalPersistenceSnapshot, parsePersistenceSnapshot } from './persistence-changes.ts'
|
||||
import { persistenceFormatFactArtifacts } from './persistence-format-facts.ts'
|
||||
import { canonicalizeSchema, schemaDigest } from './persistence-schema-model.ts'
|
||||
import type { PersistenceSchemaInventory } from './persistence-schema-model.ts'
|
||||
import { withoutPersistenceSourceLines } from './persistence-source-metadata.ts'
|
||||
|
||||
const DIRECTORY = 'docs/persistence-changes/historical-formats'
|
||||
const CURRENT_DOCUMENT = 'docs/persistence-catalog.md'
|
||||
const CURRENT_SCHEMA = 'docs/persistence-schema.json'
|
||||
|
||||
/** Historical checkout that supplies a format's complete declared persistence inventory. */
|
||||
export type PersistenceFormatSource = { readonly tag: string } | { readonly pullRequest: number }
|
||||
|
||||
/** One complete format reference; the current catalog follows the historical entries. */
|
||||
export interface PersistenceFormatEntry {
|
||||
readonly version: number
|
||||
readonly document: string
|
||||
readonly schemaPath: string
|
||||
readonly inventory: PersistenceSchemaInventory
|
||||
readonly source?: PersistenceFormatSource
|
||||
}
|
||||
|
||||
/** Contiguous format references ending at the source-declared writer version. */
|
||||
export interface PersistenceFormats {
|
||||
readonly currentVersion: number
|
||||
readonly entries: readonly PersistenceFormatEntry[]
|
||||
}
|
||||
|
||||
interface PersistenceFormatRecord {
|
||||
readonly source: PersistenceFormatSource
|
||||
readonly roots: ReadonlyMap<string, string>
|
||||
}
|
||||
|
||||
function fields(value: unknown, expected: readonly string[], label: string): Record<string, unknown> {
|
||||
if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label}: expected an object`)
|
||||
const record = value as Record<string, unknown>
|
||||
if (Object.keys(record).length !== expected.length || expected.some(key => !Object.hasOwn(record, key))) {
|
||||
throw new Error(`${label}: expected fields ${expected.join(', ')}`)
|
||||
}
|
||||
return record
|
||||
}
|
||||
|
||||
function machineBlock(document: string, label: string): string {
|
||||
if (/\.[cm]?[jt]sx?(?::\d+(?::\d+)?|#L\d+(?:-L\d+)?)/u.test(document)) {
|
||||
throw new Error(`${label}: historical source references must omit line numbers`)
|
||||
}
|
||||
const frontmatter = /^---\n([\s\S]*?)\n---(?:\n|$)/u.exec(document)?.[1]
|
||||
const metadata: unknown = frontmatter === undefined ? undefined : load(frontmatter, { schema: JSON_SCHEMA })
|
||||
if (metadata === null || typeof metadata !== 'object' || !('kind' in metadata) || metadata.kind !== 'persistence-format') {
|
||||
throw new Error(`${label}: expected persistence-format frontmatter kind`)
|
||||
}
|
||||
const blocks = [...document.matchAll(/^```yaml persistence-format[^\S\n]*\n([\s\S]*?)^```[^\S\n]*$/gmu)]
|
||||
if (blocks.length !== 1) throw new Error(`${label}: expected exactly one persistence-format machine record`)
|
||||
return (blocks[0] as RegExpMatchArray)[1] as string
|
||||
}
|
||||
|
||||
function parseSource(source: unknown, label: string): PersistenceFormatSource {
|
||||
if (source !== null && typeof source === 'object' && 'tag' in source) {
|
||||
const tag = fields(source, ['tag'], `${label} source`).tag
|
||||
if (typeof tag !== 'string' || !/^dsh-[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(tag)) throw new Error(`${label}: invalid source tag`)
|
||||
return { tag }
|
||||
}
|
||||
const pullRequest = fields(source, ['pullRequest'], `${label} source`).pullRequest
|
||||
if (!Number.isSafeInteger(pullRequest) || (pullRequest as number) <= 0) throw new Error(`${label}: source pullRequest must be a positive integer`)
|
||||
return { pullRequest: pullRequest as number }
|
||||
}
|
||||
|
||||
function parseRecord(block: string, version: number): PersistenceFormatRecord {
|
||||
const label = `v${version}`
|
||||
const record = fields(load(block, { schema: JSON_SCHEMA }), ['schemaVersion', 'sessionFormatVersion', 'source', 'roots'], label)
|
||||
if (record.schemaVersion !== 1) throw new Error(`${label}: unsupported persistence format record schema version`)
|
||||
if (record.sessionFormatVersion !== version) throw new Error(`${label}: record sessionFormatVersion must match its filename`)
|
||||
if (record.roots === null || typeof record.roots !== 'object' || Array.isArray(record.roots)) throw new Error(`${label}: roots must be a mapping`)
|
||||
const roots = new Map<string, string>()
|
||||
for (const [key, digest] of Object.entries(record.roots)) {
|
||||
if (!/^(?:SessionHeader|JsonlHeaderLine|SessionEventEnvelope|event:.+)$/u.test(key)
|
||||
|| typeof digest !== 'string' || !/^[a-f0-9]{64}$/u.test(digest)) throw new Error(`${label}: invalid recorded root ${key}`)
|
||||
roots.set(key, digest)
|
||||
}
|
||||
return { source: parseSource(record.source, label), roots }
|
||||
}
|
||||
|
||||
function validateInventory(inventory: PersistenceSchemaInventory, version: number, current: boolean): ReadonlySet<string> {
|
||||
const label = `v${version}`
|
||||
for (const key of ['SessionHeader', 'JsonlHeaderLine', 'SessionEventEnvelope']) {
|
||||
const root = inventory.roots.find(root => root.key === key)
|
||||
if (root === undefined) throw new Error(`${label}: missing schema root ${key}`)
|
||||
if (root.kind !== 'header') continue
|
||||
const node = root.schema.nodes[0]
|
||||
const field = node?.kind === 'object' ? node.properties.find(property => property.name === 'version') : undefined
|
||||
const type = field === undefined ? undefined : root.schema.nodes[field.type]
|
||||
const legacyNumber = !(current && key === 'SessionHeader') && type?.kind === 'primitive' && type.type === 'number'
|
||||
if (field?.optional !== false || !(legacyNumber || type?.kind === 'literal' && type.value === version)) {
|
||||
throw new Error(`${label}: ${key}.version must match the ${current ? 'current writer' : 'recorded format'} version`)
|
||||
}
|
||||
}
|
||||
if (!inventory.roots.some(root => root.kind === 'event')) throw new Error(`${label}: complete inventory must include an event root`)
|
||||
const reachable = new Set(inventory.roots.flatMap(root => root.schema.nodes
|
||||
.map((_, index) => schemaDigest(canonicalizeSchema(root.schema.nodes, index)))))
|
||||
const remaining = new Set(reachable)
|
||||
const listed = new Set<string>()
|
||||
for (const type of inventory.types) {
|
||||
if (listed.has(type.digest)) throw new Error(`${label}: duplicate schema type ${type.digest}`)
|
||||
listed.add(type.digest)
|
||||
// The current extractor can retain types erased by normalization; its generator gate checks that inventory.
|
||||
if (!current && !reachable.has(type.digest)) throw new Error(`${label}: unreferenced schema type ${type.digest}`)
|
||||
remaining.delete(type.digest)
|
||||
}
|
||||
if (remaining.size > 0) throw new Error(`${label}: schema types must cover every reachable type`)
|
||||
return reachable
|
||||
}
|
||||
|
||||
function validateDocument(
|
||||
document: string, schemaName: string, inventory: PersistenceSchemaInventory, label: string, current: boolean,
|
||||
): void {
|
||||
if (!document.includes(`](${schemaName})`)) throw new Error(`${label}: missing link to ${schemaName}`)
|
||||
if (!current) return
|
||||
for (const root of inventory.roots) {
|
||||
const row = `| \`${root.key}\` | ${root.kind} | \`${root.digest}\` |`
|
||||
if (!document.includes(row)) throw new Error(`${label}: missing schema index entry for ${root.key}`)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Read every required format pair and complete inventory without Git or historical source extraction.
|
||||
* @param root - checkout root containing the writer declaration and format references.
|
||||
* @returns ordered historical references followed by the current generated catalog.
|
||||
*/
|
||||
export function loadPersistenceFormats(root: string): PersistenceFormats {
|
||||
const currentVersion = readCurrentSessionFormatVersion(root)
|
||||
const directory = join(root, DIRECTORY)
|
||||
const files = new Set(existsSync(directory) ? readdirSync(directory) : [])
|
||||
const expected = new Set<string>()
|
||||
for (let version = 0; version < currentVersion; version += 1) {
|
||||
for (const suffix of ['.md', '.zh.md', '.schema.json']) {
|
||||
const name = `v${version}${suffix}`
|
||||
expected.add(name)
|
||||
if (!files.has(name)) throw new Error(`v${version}: missing persistence format artifact ${name}`)
|
||||
}
|
||||
expected.add(`v${version}.i18n.yaml`)
|
||||
}
|
||||
for (const file of files) {
|
||||
if (file.startsWith('v') && !expected.has(file)) throw new Error(`unexpected persistence format artifact ${file}`)
|
||||
}
|
||||
const read = (path: string): string => {
|
||||
if (!existsSync(join(root, path))) throw new Error(`missing persistence format artifact ${path}`)
|
||||
return readFileSync(join(root, path), 'utf8').replaceAll('\r\n', '\n')
|
||||
}
|
||||
const entries: PersistenceFormatEntry[] = []
|
||||
for (let version = 0; version <= currentVersion; version += 1) {
|
||||
const current = version === currentVersion
|
||||
const document = current ? CURRENT_DOCUMENT : `${DIRECTORY}/v${version}.md`
|
||||
const schemaPath = current ? CURRENT_SCHEMA : `${DIRECTORY}/v${version}.schema.json`
|
||||
const english = read(document)
|
||||
const chinese = read(document.replace(/\.md$/u, '.zh.md'))
|
||||
let record: PersistenceFormatRecord | undefined
|
||||
if (!current) {
|
||||
const block = machineBlock(english, document)
|
||||
if (block !== machineBlock(chinese, document.replace(/\.md$/u, '.zh.md'))) throw new Error(`v${version}: bilingual machine records differ`)
|
||||
record = parseRecord(block, version)
|
||||
}
|
||||
const inventory = (current ? parsePersistenceSnapshot : parseHistoricalPersistenceSnapshot)(JSON.parse(read(schemaPath)))
|
||||
validateInventory(inventory, version, current)
|
||||
const recordedRoots = record?.roots
|
||||
if (recordedRoots !== undefined && (recordedRoots.size !== inventory.roots.length
|
||||
|| inventory.roots.some(root => recordedRoots.get(root.key) !== root.digest))) {
|
||||
throw new Error(`v${version}: recorded roots do not match the complete schema inventory`)
|
||||
}
|
||||
const schemaName = current ? 'persistence-schema.json' : `v${version}.schema.json`
|
||||
validateDocument(english, schemaName, inventory, document, current)
|
||||
validateDocument(chinese, schemaName, inventory, document.replace(/\.md$/u, '.zh.md'), current)
|
||||
entries.push({ version, document, schemaPath, inventory, ...(record === undefined ? {} : { source: record.source }) })
|
||||
}
|
||||
return { currentVersion, entries }
|
||||
}
|
||||
|
||||
function archiveCurrentInventory(root: string, requestedVersion: string): string {
|
||||
const version = Number(requestedVersion)
|
||||
if (!/^(?:0|[1-9]\d*)$/u.test(requestedVersion) || !Number.isSafeInteger(version)) {
|
||||
throw new Error('--archive must be a non-negative safe integer')
|
||||
}
|
||||
const currentVersion = readCurrentSessionFormatVersion(root)
|
||||
if (version !== currentVersion) throw new Error(`Cannot archive v${version}: current writer is v${currentVersion}`)
|
||||
const path = `${DIRECTORY}/v${version}.schema.json`
|
||||
if (existsSync(join(root, path))) throw new Error(`Cannot archive v${version}: ${path} already exists`)
|
||||
const inventory = parsePersistenceSnapshot(JSON.parse(readFileSync(join(root, CURRENT_SCHEMA), 'utf8')))
|
||||
const reachable = validateInventory(inventory, version, true)
|
||||
const archive = withoutPersistenceSourceLines({ ...inventory, types: inventory.types.filter(type => reachable.has(type.digest)) })
|
||||
mkdirSync(join(root, DIRECTORY), { recursive: true })
|
||||
writeFileSync(join(root, path), JSON.stringify(archive, null, 2) + '\n', { flag: 'wx' })
|
||||
return `Archived Session format v${version} to ${path}.`
|
||||
}
|
||||
|
||||
/**
|
||||
* Archive the current schema or validate and optionally refresh format references.
|
||||
* @param args - --archive N creates the current version's schema once; --write refreshes validated facts.
|
||||
* @param root - default checkout directory, overridden by --root when provided.
|
||||
* @returns the created schema path or verified format count and refreshed artifact count.
|
||||
*/
|
||||
export function runPersistenceFormats(args: readonly string[], root = resolve(import.meta.dirname, '..')): string {
|
||||
const { values } = parseArgs({ args: [...args], options: { root: { type: 'string' }, write: { type: 'boolean' }, archive: { type: 'string' } } })
|
||||
root = resolve(values.root ?? root)
|
||||
if (values.archive !== undefined) {
|
||||
if (values.write) throw new Error('--archive and --write cannot be combined')
|
||||
return archiveCurrentInventory(root, values.archive)
|
||||
}
|
||||
const formats = loadPersistenceFormats(root)
|
||||
const changed = persistenceFormatFactArtifacts(root, formats).filter(artifact => !existsSync(join(root, artifact.path))
|
||||
|| readFileSync(join(root, artifact.path), 'utf8') !== artifact.content)
|
||||
if (!values.write && changed.length > 0) throw new Error(`Stale persistence format facts: ${changed.map(artifact => artifact.path).join(', ')}. Run pnpm run verify-persistence-formats --write.`)
|
||||
if (values.write) for (const artifact of changed) writeFileSync(join(root, artifact.path), artifact.content)
|
||||
return `Persistence formats: v0 through v${formats.currentVersion} verified (${formats.entries.length} complete reference${formats.entries.length === 1 ? '' : 's'}).`
|
||||
+ (values.write ? ` Refreshed ${changed.length} file${changed.length === 1 ? '' : 's'}.` : '')
|
||||
}
|
||||
|
||||
if (process.argv[1] !== undefined && resolve(process.argv[1]) === import.meta.filename) {
|
||||
try {
|
||||
console.log(runPersistenceFormats(process.argv.slice(2)))
|
||||
} catch (error: unknown) {
|
||||
console.error(error instanceof Error ? error.message : String(error))
|
||||
process.exitCode = 1
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,95 @@
|
||||
/** Render bounded release facts from validated offline records while preserving authored prose. */
|
||||
|
||||
import { readFileSync } from 'node:fs'
|
||||
import { join } from 'node:path'
|
||||
import { renderPersistencePair } from './persistence-artifacts.ts'
|
||||
import type { PersistenceArtifact } from './persistence-artifacts.ts'
|
||||
import type { PersistenceReleaseEntry, PersistenceReleases } from './persistence-releases.ts'
|
||||
import { canonicalizeSchema, schemaDigest } from './persistence-schema-model.ts'
|
||||
|
||||
type Language = 'en' | 'zh'
|
||||
|
||||
function count(value: number, noun: string): string {
|
||||
return `${value} ${noun}${value === 1 ? '' : 's'}`
|
||||
}
|
||||
|
||||
function replaceFacts(source: string, name: string, content: string, path: string): string {
|
||||
const start = `<!-- persistence-release-${name}:start -->`
|
||||
const end = `<!-- persistence-release-${name}:end -->`
|
||||
const opening = source.indexOf(start)
|
||||
const closing = source.indexOf(end)
|
||||
if (opening < 0 || closing < opening || source.indexOf(start, opening + start.length) >= 0
|
||||
|| source.indexOf(end, closing + end.length) >= 0) throw new Error(`${path}: expected one ${name} factual block`)
|
||||
return source.slice(0, opening + start.length) + content + source.slice(closing)
|
||||
}
|
||||
|
||||
function structuralChanges(entry: PersistenceReleaseEntry, language: Language): string {
|
||||
if (entry.record.previous === null) {
|
||||
return language === 'en'
|
||||
? 'This entry establishes the historical comparison starting point. Its declaration lists every extracted root; it makes no compatibility judgment about earlier versions.'
|
||||
: '本条记录建立历史比较起点。机器声明列出所有提取的根类型,不对更早版本作兼容性判断。'
|
||||
}
|
||||
if (entry.differences.length === 0) {
|
||||
return language === 'en'
|
||||
? 'Normalized root types and their transitive digests are unchanged from the preceding tag.'
|
||||
: '规范化后的根类型及其传递引用摘要与前一 tag 相同。'
|
||||
}
|
||||
const summary = language === 'en'
|
||||
? `Detected ${count(entry.record.changes.length, 'changed root')} and ${count(entry.differences.length, 'structural difference')}. The minimum below is calculated using current rules for comparison only; it does not assert historical compliance, migration correctness, or runtime compatibility.`
|
||||
: `检测到 ${entry.record.changes.length} 个根类型变化、${entry.differences.length} 项结构差异。下表的最低要求按当前规则计算,只用于比较;不表示旧版本曾遵守这些规则,也不证明迁移或运行时兼容性。`
|
||||
const heading = language === 'en' ? '| Path | Change | Current minimum |' : '| 路径 | 变化 | 当前最低要求 |'
|
||||
const rows = entry.differences.map((change) => {
|
||||
const path = change.path.replaceAll('`', '\\`').replaceAll('|', '\\|')
|
||||
return `| \`${path}\` | \`${change.kind}\` | \`${change.requiresVersionBump ? 'version-bump' : 'same-version'}\` |`
|
||||
})
|
||||
return [summary, '', heading, '|---|---|---|', ...rows].join('\n')
|
||||
}
|
||||
|
||||
/** Compute paired factual updates without writing or changing machine declarations.
|
||||
* @param root - checkout containing existing documents with bounded factual markers.
|
||||
* @param archive - fully validated release records and reconstructed roots.
|
||||
* @returns complete bilingual documents and sidecars, validated together before any caller writes.
|
||||
*/
|
||||
export function persistenceReleaseFactArtifacts(root: string, archive: PersistenceReleases): PersistenceArtifact[] {
|
||||
const directory = 'docs/persistence-changes/releases'
|
||||
const rootTypes = new Map<string, readonly string[]>()
|
||||
const typeCounts = archive.entries.map((entry) => {
|
||||
const types = new Set<string>()
|
||||
for (const root of entry.roots.values()) {
|
||||
let digests = rootTypes.get(root.digest)
|
||||
if (digests === undefined) {
|
||||
digests = root.schema.nodes.map((_, index) => schemaDigest(canonicalizeSchema(root.schema.nodes, index)))
|
||||
rootTypes.set(root.digest, digests)
|
||||
}
|
||||
for (const digest of digests) types.add(digest)
|
||||
}
|
||||
return types.size
|
||||
})
|
||||
const read = (name: string): string => readFileSync(join(root, directory, name), 'utf8')
|
||||
const index = (language: Language): string => {
|
||||
const heading = language === 'en'
|
||||
? '| Tag | Source date (UTC) | Session version | Roots / types | Changed roots |'
|
||||
: '| Tag | 源码日期(UTC) | Session 版本 | 根 / 类型 | 变化根 |'
|
||||
const rows = archive.entries.map((entry, index) => {
|
||||
const tag = entry.release.tag
|
||||
const date = new Date(entry.release.sourceDate).toISOString().slice(0, 10)
|
||||
return `| [${tag}](${tag}${language === 'zh' ? '.zh' : ''}.md) | ${date} | ${entry.release.sessionFormatVersion} | ${entry.roots.size} / ${typeCounts[index]} | ${entry.record.changes.length} |`
|
||||
})
|
||||
return '\n\n' + [heading, '|---|---|---|---|---|', ...rows].join('\n') + '\n\n'
|
||||
}
|
||||
const artifacts = renderPersistencePair(root, `${directory}/README.md`,
|
||||
replaceFacts(read('README.md'), 'index', index('en'), 'README.md'),
|
||||
replaceFacts(read('README.zh.md'), 'index', index('zh'), 'README.zh.md'))
|
||||
for (const [index, entry] of archive.entries.entries()) {
|
||||
const document = (language: Language): string => {
|
||||
const path = `${entry.release.tag}${language === 'zh' ? '.zh' : ''}.md`
|
||||
const inventory = language === 'en'
|
||||
? `${count(entry.roots.size, 'root')} / ${count(typeCounts[index] as number, 'type')}`
|
||||
: `${entry.roots.size} 个根类型 / ${typeCounts[index]} 种类型`
|
||||
return replaceFacts(replaceFacts(read(path), 'inventory', inventory, path),
|
||||
'changes', '\n\n' + structuralChanges(entry, language) + '\n\n', path)
|
||||
}
|
||||
artifacts.push(...renderPersistencePair(root, `${directory}/${entry.release.tag}.md`, document('en'), document('zh')))
|
||||
}
|
||||
return artifacts
|
||||
}
|
||||
@@ -0,0 +1,398 @@
|
||||
/** Offline release archives preserve historical schemas and reject incomplete or inconsistent transitions. */
|
||||
|
||||
import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { join } from 'node:path'
|
||||
import { dump } from 'js-yaml'
|
||||
import { afterEach, describe, expect, it } from 'vitest'
|
||||
import { parsePersistenceSnapshot } from './persistence-changes.ts'
|
||||
import { canonicalizeSchema, schemaDigest } from './persistence-schema-model.ts'
|
||||
import type { PersistenceRoot, PersistenceSchemaInventory, PersistenceType, SchemaNode } from './persistence-schema-model.ts'
|
||||
import { loadPersistenceReleases, runPersistenceReleases } from './persistence-releases.ts'
|
||||
import type { PersistenceReleaseManifest, PersistenceReleaseRecord } from './persistence-releases.ts'
|
||||
|
||||
const TAGS = ['dsh-v0.1.0-alpha.1', 'dsh-v0.1.0-rc.1', 'dsh-v0.1.0-rc.2'] as const
|
||||
const temporary: string[] = []
|
||||
afterEach(() => { for (const root of temporary.splice(0)) rmSync(root, { recursive: true, force: true }) })
|
||||
|
||||
function rootSchema(key: string, nodes: readonly SchemaNode[], surface = false): PersistenceRoot {
|
||||
const schema = canonicalizeSchema(nodes, 0)
|
||||
return {
|
||||
key, kind: key.startsWith('event:') ? 'event' : key === 'SessionEventEnvelope' ? 'envelope' : 'header',
|
||||
...(key.startsWith('event:') ? { event: key.slice(6), surface } : {}), schema, digest: schemaDigest(schema),
|
||||
}
|
||||
}
|
||||
|
||||
function event(value: 'number' | 'string'): PersistenceRoot {
|
||||
return rootSchema('event:example/value', [
|
||||
{ kind: 'object', indices: [], properties: [
|
||||
{ name: 'type', type: 1, optional: false },
|
||||
{ name: 'data', type: 2, optional: false },
|
||||
{ name: 'surfaceOp', type: 3, optional: true },
|
||||
] },
|
||||
{ kind: 'literal', value: 'example/value' },
|
||||
{ kind: 'primitive', type: value },
|
||||
{ kind: 'primitive', type: 'string' },
|
||||
], true)
|
||||
}
|
||||
|
||||
function inventory(roots: readonly PersistenceRoot[]): PersistenceSchemaInventory {
|
||||
const types = new Map<string, PersistenceType>()
|
||||
for (const root of roots) {
|
||||
for (const [index] of root.schema.nodes.entries()) {
|
||||
const schema = canonicalizeSchema(root.schema.nodes, index)
|
||||
const digest = schemaDigest(schema)
|
||||
types.set(digest, { digest, schema, names: [], sources: [] })
|
||||
}
|
||||
}
|
||||
return { formatVersion: 1, roots, types: [...types.values()] }
|
||||
}
|
||||
|
||||
interface Fixture {
|
||||
readonly root: string
|
||||
readonly directory: string
|
||||
readonly manifest: PersistenceReleaseManifest
|
||||
readonly records: readonly PersistenceReleaseRecord[]
|
||||
readonly snapshots: readonly PersistenceSchemaInventory[]
|
||||
}
|
||||
|
||||
function saveRecord(directory: string, record: PersistenceReleaseRecord): void {
|
||||
const block = dump(record, { lineWidth: -1, noRefs: true })
|
||||
for (const suffix of ['.md', '.zh.md']) {
|
||||
const switcher = suffix === '.md' ? `English | [中文](${record.tag}.zh.md)` : `[English](${record.tag}.md) | 中文`
|
||||
writeFileSync(join(directory, record.tag + suffix), [
|
||||
'---', 'kind: persistence-release', '---', '', '# Archived release', '', switcher, '',
|
||||
'## Summary', '', 'Authored summary and evidence.', '',
|
||||
'| Inventory | Count |', '|---|---|',
|
||||
'| Reconstructed inventory | <!-- persistence-release-inventory:start -->pending<!-- persistence-release-inventory:end --> |', '',
|
||||
'```yaml persistence-release', block.trimEnd(), '```', '',
|
||||
'<!-- persistence-release-changes:start -->', '', 'Pending facts.', '', '<!-- persistence-release-changes:end -->', '',
|
||||
].join('\n'))
|
||||
}
|
||||
}
|
||||
|
||||
function fixture(): Fixture {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-persistence-releases-'))
|
||||
temporary.push(root)
|
||||
const directory = join(root, 'docs/persistence-changes/releases')
|
||||
mkdirSync(directory, { recursive: true })
|
||||
for (const suffix of ['.md', '.zh.md']) {
|
||||
const switcher = suffix === '.md' ? 'English | [中文](README.zh.md)' : '[English](README.md) | 中文'
|
||||
writeFileSync(join(directory, 'README' + suffix), [
|
||||
'# Releases', '', switcher, '', 'Authored introduction.', '',
|
||||
'<!-- persistence-release-index:start -->', '', 'Pending index.', '', '<!-- persistence-release-index:end -->', '',
|
||||
].join('\n'))
|
||||
}
|
||||
writeFileSync(join(directory, 'README.i18n.yaml'), 'schemaVersion: 1\n')
|
||||
const manifest: PersistenceReleaseManifest = {
|
||||
schemaVersion: 1, capturedAt: '2026-09-12',
|
||||
releases: TAGS.map((tag, index) => ({
|
||||
tag, sourceDate: '2026-09-01T10:00:00+08:00', publishedAt: index === 0 ? null : '2026-09-01T03:00:00Z',
|
||||
sessionFormatVersion: 0,
|
||||
})),
|
||||
}
|
||||
const before = event('string')
|
||||
const after = event('number')
|
||||
const header = rootSchema('SessionHeader', [
|
||||
{ kind: 'object', indices: [], properties: [{ name: 'version', type: 1, optional: false }] }, { kind: 'primitive', type: 'number' },
|
||||
])
|
||||
const snapshots = [inventory([
|
||||
header, rootSchema('JsonlHeaderLine', [{ kind: 'opaque', reason: 'unknown' }]),
|
||||
rootSchema('SessionEventEnvelope', [{ kind: 'object', indices: [], properties: [] }]), before,
|
||||
]), inventory([after]), inventory([])]
|
||||
const records = manifest.releases.map((release, index): PersistenceReleaseRecord => ({
|
||||
schemaVersion: 1, tag: release.tag, previous: TAGS[index - 1] ?? null,
|
||||
sessionFormatVersion: release.sessionFormatVersion,
|
||||
changes: snapshots[index]!.roots.map(root => ({ root: root.key, before: index === 0 ? null : before.digest, after: root.digest })),
|
||||
}))
|
||||
writeFileSync(join(directory, 'manifest.json'), JSON.stringify(manifest))
|
||||
for (const [index, record] of records.entries()) {
|
||||
saveRecord(directory, record)
|
||||
writeFileSync(join(directory, record.tag + '.schema.json'), JSON.stringify(snapshots[index]))
|
||||
writeFileSync(join(directory, record.tag + '.i18n.yaml'), 'schemaVersion: 1\n')
|
||||
}
|
||||
return { root, directory, manifest, records, snapshots }
|
||||
}
|
||||
|
||||
function replaceSnapshot(fixture: Fixture, index: number, snapshot: PersistenceSchemaInventory): void {
|
||||
writeFileSync(join(fixture.directory, TAGS[index]! + '.schema.json'), JSON.stringify(snapshot))
|
||||
}
|
||||
|
||||
describe('pinned persistence releases', () => {
|
||||
it.each(['.md', '.zh.md'])('rejects historical source coordinates in %s records', (suffix) => {
|
||||
const data = fixture()
|
||||
const path = join(data.directory, TAGS[0] + suffix)
|
||||
const original = readFileSync(path, 'utf8')
|
||||
for (const position of [':36', ':36:2', '#L36', '#L36-L38']) {
|
||||
writeFileSync(path, original + `\nSource: \`packages/core/session/src/types.ts${position}\`.\n`)
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow('historical source references must omit line numbers')
|
||||
}
|
||||
writeFileSync(path, original + '\nSource: `packages/core/session/src/types.ts`.\n')
|
||||
expect(loadPersistenceReleases(data.root).entries).toHaveLength(3)
|
||||
})
|
||||
|
||||
it('rejects historical source coordinates in release schema metadata', () => {
|
||||
const data = fixture()
|
||||
const snapshot = data.snapshots[0]!
|
||||
replaceSnapshot(data, 0, { ...snapshot, types: snapshot.types.map((type, index) => index === 0
|
||||
? { ...type, sources: ['packages/core/session/src/types.ts:36'] } : type) })
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow('historical schema sources must omit line numbers')
|
||||
})
|
||||
|
||||
it('reconstructs breaking version-zero changes and unchanged releases from a tree without Git or package sources', () => {
|
||||
const data = fixture()
|
||||
const archive = loadPersistenceReleases(data.root)
|
||||
expect(archive.entries).toHaveLength(3)
|
||||
expect(archive.entries[0]!.roots.get('event:example/value')!.digest).toBe(event('string').digest)
|
||||
expect(archive.entries[1]!.roots.get('event:example/value')!.digest).toBe(event('number').digest)
|
||||
expect(archive.entries[1]!.differences).toEqual([expect.objectContaining({ root: 'event:example/value', kind: 'type-changed', requiresVersionBump: true })])
|
||||
expect(archive.entries[2]!.roots).toEqual(archive.entries[1]!.roots)
|
||||
expect(archive.entries[2]!.differences).toEqual([])
|
||||
expect(() => parsePersistenceSnapshot(data.snapshots[1])).toThrow('surface metadata')
|
||||
})
|
||||
|
||||
it.each(['.md', '.zh.md', '.i18n.yaml', '.schema.json'])('rejects a missing manifest release companion %s', (suffix) => {
|
||||
const data = fixture()
|
||||
rmSync(join(data.directory, TAGS[1] + suffix))
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow('missing release artifact')
|
||||
})
|
||||
|
||||
it.each(['README.md', 'README.zh.md', 'README.i18n.yaml'])('requires the fixed archive companion %s', (name) => {
|
||||
const data = fixture()
|
||||
rmSync(join(data.directory, name))
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow(`missing release artifact ${name}`)
|
||||
})
|
||||
|
||||
it.each(['orphan.md', 'orphan.schema.json', 'orphan.zh.md', 'orphan.i18n.yaml'])('rejects an unreferenced archive file %s', (filename) => {
|
||||
const data = fixture()
|
||||
writeFileSync(join(data.directory, filename), '{}')
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow('unreferenced persistence release artifact')
|
||||
})
|
||||
|
||||
it('rejects missing, duplicated, and misordered manifest entries', () => {
|
||||
const data = fixture()
|
||||
for (const releases of [
|
||||
data.manifest.releases.slice(1), [data.manifest.releases[0], ...data.manifest.releases], [...data.manifest.releases].reverse(),
|
||||
]) {
|
||||
writeFileSync(join(data.directory, 'manifest.json'), JSON.stringify({ ...data.manifest, releases }))
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow(/unreferenced|semantic-version order/u)
|
||||
}
|
||||
})
|
||||
|
||||
it('rejects malformed manifest identities and version metadata', () => {
|
||||
const data = fixture()
|
||||
for (const changes of [
|
||||
{ tag: 'dsh-v0.1.0-beta.1' }, { sourceDate: '2026-09-01' },
|
||||
{ publishedAt: 'yesterday' }, { sessionFormatVersion: -1 }, { sessionFormatVersion: 1.5 },
|
||||
]) {
|
||||
writeFileSync(join(data.directory, 'manifest.json'), JSON.stringify({ ...data.manifest,
|
||||
releases: data.manifest.releases.map((release, index) => index === 0 ? { ...release, ...changes } : release),
|
||||
}))
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow(/invalid value|nonnegative integer/u)
|
||||
}
|
||||
for (const changes of [{ schemaVersion: 2 }, { capturedAt: '2026-02-30' }, { releases: [] }]) {
|
||||
writeFileSync(join(data.directory, 'manifest.json'), JSON.stringify({ ...data.manifest, ...changes }))
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow(/schema version|capture date|must not be empty/u)
|
||||
}
|
||||
})
|
||||
|
||||
it('rejects removed manifest and record fields as unknown metadata', () => {
|
||||
const data = fixture()
|
||||
writeFileSync(join(data.directory, 'manifest.json'), JSON.stringify({ ...data.manifest, repository: 'example' }))
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow('unknown field repository')
|
||||
for (const field of ['commit', 'committedAt', 'sqliteSchemaVersion']) {
|
||||
writeFileSync(join(data.directory, 'manifest.json'), JSON.stringify({ ...data.manifest,
|
||||
releases: data.manifest.releases.map((release, index) => index === 0 ? { ...release, [field]: null } : release),
|
||||
}))
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow(`unknown field ${field}`)
|
||||
}
|
||||
writeFileSync(join(data.directory, 'manifest.json'), JSON.stringify(data.manifest))
|
||||
for (const field of ['commit', 'sqliteSchemaVersion']) {
|
||||
saveRecord(data.directory, { ...data.records[1]!, [field]: null })
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow(`unknown field ${field}`)
|
||||
}
|
||||
})
|
||||
|
||||
it('rejects wrong predecessor, format version, schema version, and duplicate roots', () => {
|
||||
const data = fixture()
|
||||
const original = data.records[1]!
|
||||
for (const changed of [
|
||||
{ ...original, previous: null },
|
||||
{ ...original, sessionFormatVersion: 2 }, { ...original, schemaVersion: 2 },
|
||||
{ ...original, changes: [...original.changes, ...original.changes] },
|
||||
]) {
|
||||
saveRecord(data.directory, changed as PersistenceReleaseRecord)
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow(/predecessor|match manifest|schema version|duplicate change/u)
|
||||
}
|
||||
})
|
||||
|
||||
it('rejects before and after digest mismatches', () => {
|
||||
const data = fixture()
|
||||
const original = data.records[1]!
|
||||
for (const field of ['before', 'after']) {
|
||||
saveRecord(data.directory, { ...original, changes: original.changes.map(change => ({ ...change, [field]: 'f'.repeat(64) })) })
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow(`${field} digest mismatch`)
|
||||
}
|
||||
})
|
||||
|
||||
it('rejects an unchanged transition and an unacknowledged after root', () => {
|
||||
const data = fixture()
|
||||
saveRecord(data.directory, { ...data.records[2]!, changes: [{ root: 'event:example/value', before: event('number').digest, after: event('number').digest }] })
|
||||
replaceSnapshot(data, 2, data.snapshots[1]!)
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow('unchanged transition')
|
||||
saveRecord(data.directory, data.records[2]!)
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow('snapshot roots')
|
||||
})
|
||||
|
||||
it('reconstructs deletions without requiring an after schema or a historical version increase', () => {
|
||||
const data = fixture()
|
||||
saveRecord(data.directory, { ...data.records[2]!, changes: [{ root: 'event:example/value', before: event('number').digest, after: null }] })
|
||||
const result = loadPersistenceReleases(data.root)
|
||||
expect(result.entries[2]!.roots.has('event:example/value')).toBe(false)
|
||||
expect(result.entries[2]!.differences).toEqual([expect.objectContaining({ kind: 'root-removed', requiresVersionBump: true })])
|
||||
})
|
||||
|
||||
it('rejects missing, duplicate, and unreferenced reachable types', () => {
|
||||
const data = fixture()
|
||||
const snapshot = data.snapshots[1]!
|
||||
const unrelated = inventory([rootSchema('SessionHeader', [{ kind: 'primitive', type: 'boolean' }])]).types[0]!
|
||||
for (const types of [snapshot.types.slice(1), [...snapshot.types, snapshot.types[0]!], [...snapshot.types, unrelated]]) {
|
||||
replaceSnapshot(data, 1, { ...snapshot, types })
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow(/every reachable type|duplicate schema type|unreferenced schema type/u)
|
||||
}
|
||||
})
|
||||
|
||||
it('rejects mismatched translations, duplicate blocks, and the wrong document kind', () => {
|
||||
const data = fixture()
|
||||
const path = join(data.directory, TAGS[1] + '.zh.md')
|
||||
const source = readFileSync(path, 'utf8')
|
||||
for (const changed of [
|
||||
source.replace('schemaVersion: 1', 'schemaVersion: 2'), source + source,
|
||||
source.replace('kind: persistence-release', 'kind: persistence-change'),
|
||||
]) {
|
||||
writeFileSync(path, changed)
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow(/bilingual machine|exactly one|frontmatter kind/u)
|
||||
}
|
||||
})
|
||||
|
||||
it('matches literal header versions when a historical declaration pins one', () => {
|
||||
const data = fixture()
|
||||
const header = rootSchema('SessionHeader', [
|
||||
{ kind: 'object', indices: [], properties: [{ name: 'version', type: 1, optional: false }] }, { kind: 'literal', value: 9 },
|
||||
])
|
||||
const snapshot = inventory(data.snapshots[0]!.roots.map(root => root.key === header.key ? header : root))
|
||||
replaceSnapshot(data, 0, snapshot)
|
||||
saveRecord(data.directory, { ...data.records[0]!,
|
||||
changes: snapshot.roots.map(root => ({ root: root.key, before: null, after: root.digest })),
|
||||
})
|
||||
expect(() => loadPersistenceReleases(data.root)).toThrow('SessionHeader.version')
|
||||
})
|
||||
})
|
||||
|
||||
function directoryBytes(directory: string): Record<string, string> {
|
||||
return Object.fromEntries(readdirSync(directory).map(file => [file, readFileSync(join(directory, file), 'utf8')]))
|
||||
}
|
||||
|
||||
describe('release facts', () => {
|
||||
it('refreshes complete-state counts and singular wording while preserving authored text, declarations, and snapshots', () => {
|
||||
const data = fixture()
|
||||
const before = directoryBytes(data.directory)
|
||||
expect(() => runPersistenceReleases([], data.root)).toThrow('Stale persistence release facts')
|
||||
expect(directoryBytes(data.directory)).toEqual(before)
|
||||
expect(runPersistenceReleases(['--write'], data.root)).toContain('3 records, 2 adjacent transitions verified')
|
||||
expect(runPersistenceReleases([], data.root)).toContain('3 records, 2 adjacent transitions verified')
|
||||
const after = directoryBytes(data.directory)
|
||||
expect(after['README.md']).toContain(`| [${TAGS[1]}](${TAGS[1]}.md) | 2026-09-01 | 0 | 4 / 7 | 1 |`)
|
||||
expect(after[TAGS[1] + '.md']).toContain('4 roots / 7 types')
|
||||
expect(after[TAGS[1] + '.md']).toContain('Detected 1 changed root and 1 structural difference.')
|
||||
expect(after[TAGS[1] + '.md']).toContain('| `event:example/value.data` | `type-changed` | `version-bump` |')
|
||||
for (const [name, source] of Object.entries(before)) {
|
||||
if (name.endsWith('.json')) expect(after[name]).toBe(source)
|
||||
if (name.endsWith('.md')) {
|
||||
expect(after[name]).toContain(name.startsWith('README') ? 'Authored introduction.' : 'Authored summary and evidence.')
|
||||
if (!name.startsWith('README')) expect(after[name]?.match(/```yaml persistence-release\n[\s\S]*?```/u)?.[0])
|
||||
.toBe(source.match(/```yaml persistence-release\n[\s\S]*?```/u)?.[0])
|
||||
}
|
||||
}
|
||||
expect(after[TAGS[1] + '.i18n.yaml']).not.toBe(before[TAGS[1] + '.i18n.yaml'])
|
||||
expect(runPersistenceReleases(['--write'], data.root)).toContain('Refreshed 0 files.')
|
||||
expect(directoryBytes(data.directory)).toEqual(after)
|
||||
})
|
||||
|
||||
it.each([
|
||||
['tag label', `[${TAGS[0]}]`, '[wrong-tag]'],
|
||||
['date', '| 2026-09-01 |', '| 1999-01-01 |'],
|
||||
['writer', '| 0 | 4 / 7 |', '| 9 | 4 / 7 |'],
|
||||
['roots', '| 4 / 7 |', '| 99 / 7 |'],
|
||||
['types', '| 4 / 7 |', '| 4 / 99 |'],
|
||||
['changes', '| 4 / 7 | 4 |', '| 4 / 7 | 99 |'],
|
||||
])('rejects stale index %s', (_label, original, replacement) => {
|
||||
const data = fixture()
|
||||
runPersistenceReleases(['--write'], data.root)
|
||||
const path = join(data.directory, 'README.md')
|
||||
const source = readFileSync(path, 'utf8')
|
||||
expect(source).toContain(original)
|
||||
writeFileSync(path, source.replace(original, replacement))
|
||||
expect(() => runPersistenceReleases([], data.root)).toThrow('Stale persistence release facts')
|
||||
})
|
||||
|
||||
it.each([
|
||||
['inventory', '4 roots / 7 types', '4 roots / 999 types'],
|
||||
['root count', '1 changed root', '9 changed roots'],
|
||||
['difference count', '1 structural difference', '9 structural differences'],
|
||||
['path', '`event:example/value.data`', '`event:example/value.wrong`'],
|
||||
['kind', '`type-changed`', '`optional-property-added`'],
|
||||
['minimum', '`version-bump`', '`same-version`'],
|
||||
])('rejects stale record %s', (_label, original, replacement) => {
|
||||
const data = fixture()
|
||||
runPersistenceReleases(['--write'], data.root)
|
||||
const path = join(data.directory, TAGS[1] + '.md')
|
||||
const source = readFileSync(path, 'utf8')
|
||||
expect(source).toContain(original)
|
||||
writeFileSync(path, source.replace(original, replacement))
|
||||
expect(() => runPersistenceReleases([], data.root)).toThrow('Stale persistence release facts')
|
||||
})
|
||||
|
||||
it('checks Chinese facts too and allows authored prose outside generated regions to change', () => {
|
||||
const data = fixture()
|
||||
runPersistenceReleases(['--write'], data.root)
|
||||
const path = join(data.directory, TAGS[1] + '.zh.md')
|
||||
writeFileSync(path, readFileSync(path, 'utf8').replace('Authored summary and evidence.', 'Revised authored explanation.'))
|
||||
expect(() => runPersistenceReleases([], data.root)).not.toThrow()
|
||||
writeFileSync(path, readFileSync(path, 'utf8').replace('4 个根类型 / 7 种类型', '4 个根类型 / 999 种类型'))
|
||||
expect(() => runPersistenceReleases([], data.root)).toThrow('Stale persistence release facts')
|
||||
})
|
||||
|
||||
it('does not write anything when machine data is corrupt or a later pair cannot be rendered', () => {
|
||||
const data = fixture()
|
||||
const snapshotPath = join(data.directory, TAGS[2] + '.schema.json')
|
||||
const snapshot = readFileSync(snapshotPath, 'utf8')
|
||||
writeFileSync(snapshotPath, snapshot.replace('"formatVersion":1', '"formatVersion":2'))
|
||||
const corrupt = directoryBytes(data.directory)
|
||||
expect(() => runPersistenceReleases(['--write'], data.root)).toThrow('normalization version')
|
||||
expect(directoryBytes(data.directory)).toEqual(corrupt)
|
||||
writeFileSync(snapshotPath, snapshot)
|
||||
const path = join(data.directory, TAGS[2] + '.zh.md')
|
||||
writeFileSync(path, readFileSync(path, 'utf8').replace('<!-- persistence-release-changes:end -->', ''))
|
||||
const missingMarker = directoryBytes(data.directory)
|
||||
expect(() => runPersistenceReleases(['--write'], data.root)).toThrow('expected one changes factual block')
|
||||
expect(directoryBytes(data.directory)).toEqual(missingMarker)
|
||||
})
|
||||
|
||||
it('accepts matching literal writer versions and rejects a missing reconstructed header', () => {
|
||||
const data = fixture()
|
||||
const header = rootSchema('SessionHeader', [
|
||||
{ kind: 'object', indices: [], properties: [{ name: 'version', type: 1, optional: false }] }, { kind: 'literal', value: 0 },
|
||||
])
|
||||
for (const roots of [data.snapshots[0]!.roots.map(root => root.key === header.key ? header : root),
|
||||
data.snapshots[0]!.roots.filter(root => root.key !== header.key)]) {
|
||||
const snapshot = inventory(roots)
|
||||
replaceSnapshot(data, 0, snapshot)
|
||||
saveRecord(data.directory, { ...data.records[0]!,
|
||||
changes: roots.map(root => ({ root: root.key, before: null, after: root.digest })),
|
||||
})
|
||||
if (roots.some(root => root.key === header.key)) expect(() => loadPersistenceReleases(data.root)).not.toThrow()
|
||||
else expect(() => loadPersistenceReleases(data.root)).toThrow('reconstructed state is missing SessionHeader')
|
||||
}
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,257 @@
|
||||
/** Verify the pinned prerelease archive without Git, network access, or source extraction. */
|
||||
|
||||
import { readFileSync, readdirSync, writeFileSync } from 'node:fs'
|
||||
import { join, resolve } from 'node:path'
|
||||
import { parseArgs } from 'node:util'
|
||||
import { JSON_SCHEMA, load } from 'js-yaml'
|
||||
import { classifyPersistenceChange, parseHistoricalPersistenceSnapshot } from './persistence-changes.ts'
|
||||
import type { PersistenceTypeChange } from './persistence-changes.ts'
|
||||
import { canonicalizeSchema, schemaDigest } from './persistence-schema-model.ts'
|
||||
import type { PersistenceRoot, PersistenceSchemaInventory } from './persistence-schema-model.ts'
|
||||
import { persistenceReleaseFactArtifacts } from './persistence-release-facts.ts'
|
||||
|
||||
const ARCHIVE_DIRECTORY = 'docs/persistence-changes/releases'
|
||||
const TAG_PATTERN = /^dsh-v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)-(alpha|rc)\.(0|[1-9]\d*)$/u
|
||||
const DIGEST_PATTERN = /^[a-f0-9]{64}$/u
|
||||
|
||||
/** Published identity and version constants observed in one pinned tag. */
|
||||
export interface PersistenceRelease {
|
||||
readonly tag: string
|
||||
readonly sourceDate: string
|
||||
readonly publishedAt: string | null
|
||||
readonly sessionFormatVersion: number
|
||||
}
|
||||
|
||||
/** Offline corpus captured from the repository's alpha and release-candidate tags. */
|
||||
export interface PersistenceReleaseManifest {
|
||||
readonly schemaVersion: 1
|
||||
readonly capturedAt: string
|
||||
readonly releases: readonly PersistenceRelease[]
|
||||
}
|
||||
|
||||
/** One changed root between consecutive archived releases. */
|
||||
export interface PersistenceReleaseChange {
|
||||
readonly root: string
|
||||
readonly before: string | null
|
||||
readonly after: string | null
|
||||
}
|
||||
|
||||
/** Machine declaration shared byte-for-byte by a release's bilingual documents. */
|
||||
export interface PersistenceReleaseRecord {
|
||||
readonly schemaVersion: 1
|
||||
readonly tag: string
|
||||
readonly previous: string | null
|
||||
readonly sessionFormatVersion: number
|
||||
readonly changes: readonly PersistenceReleaseChange[]
|
||||
}
|
||||
|
||||
/** Validated release, changed after schemas, and complete reconstructed root state. */
|
||||
export interface PersistenceReleaseEntry {
|
||||
readonly release: PersistenceRelease
|
||||
readonly record: PersistenceReleaseRecord
|
||||
readonly snapshot: PersistenceSchemaInventory
|
||||
readonly roots: ReadonlyMap<string, PersistenceRoot>
|
||||
readonly differences: readonly (PersistenceTypeChange & { readonly root: string })[]
|
||||
}
|
||||
|
||||
/** Complete validated archive; classifications describe modern rules, not historical migration obligations. */
|
||||
export interface PersistenceReleases {
|
||||
readonly manifest: PersistenceReleaseManifest
|
||||
readonly entries: readonly PersistenceReleaseEntry[]
|
||||
}
|
||||
|
||||
function object(value: unknown, fields: readonly string[], label: string): Record<string, unknown> {
|
||||
if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label}: expected an object`)
|
||||
const result = value as Record<string, unknown>
|
||||
const missing = fields.find(field => !Object.hasOwn(result, field))
|
||||
const extra = Object.keys(result).find(field => !fields.includes(field))
|
||||
if (missing !== undefined || extra !== undefined) throw new Error(`${label}: ${missing === undefined ? `unknown field ${extra}` : `missing field ${missing}`}`)
|
||||
return result
|
||||
}
|
||||
|
||||
function array(value: unknown, label: string): unknown[] {
|
||||
if (!Array.isArray(value)) throw new Error(`${label}: expected an array`)
|
||||
return value
|
||||
}
|
||||
|
||||
function string(value: unknown, pattern: RegExp, label: string): string {
|
||||
if (typeof value !== 'string' || !pattern.test(value)) throw new Error(`${label}: invalid value`)
|
||||
return value
|
||||
}
|
||||
|
||||
function version(value: unknown, label: string): number {
|
||||
if (!Number.isSafeInteger(value) || (value as number) < 0) throw new Error(`${label}: expected a nonnegative integer`)
|
||||
return value as number
|
||||
}
|
||||
|
||||
function timestamp(value: unknown, label: string): void {
|
||||
const source = string(value, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/u, label)
|
||||
if (!Number.isFinite(Date.parse(source))) throw new Error(`${label}: invalid timestamp`)
|
||||
}
|
||||
|
||||
function tagOrder(tag: string): number[] {
|
||||
const match = TAG_PATTERN.exec(tag) as RegExpExecArray
|
||||
return [Number(match[1]), Number(match[2]), Number(match[3]), match[4] === 'alpha' ? 0 : 1, Number(match[5])]
|
||||
}
|
||||
|
||||
function compareTags(left: string, right: string): number {
|
||||
const before = tagOrder(left)
|
||||
const after = tagOrder(right)
|
||||
return before.map((value, index) => value - (after[index] as number)).find(value => value !== 0) ?? 0
|
||||
}
|
||||
|
||||
function parseManifest(value: unknown): PersistenceReleaseManifest {
|
||||
const input = object(value, ['schemaVersion', 'capturedAt', 'releases'], 'release manifest')
|
||||
if (input.schemaVersion !== 1) throw new Error('unsupported persistence release manifest schema version')
|
||||
const date = string(input.capturedAt, /^\d{4}-\d{2}-\d{2}$/u, 'capture date')
|
||||
if (!Number.isFinite(Date.parse(date)) || new Date(date).toISOString().slice(0, 10) !== date) throw new Error('release manifest: invalid capture date')
|
||||
let previous: string | undefined
|
||||
const releases = array(input.releases, 'releases')
|
||||
if (releases.length === 0) throw new Error('release manifest: releases must not be empty')
|
||||
for (const raw of releases) {
|
||||
const release = object(raw, ['tag', 'sourceDate', 'publishedAt', 'sessionFormatVersion'], 'release')
|
||||
const tag = string(release.tag, TAG_PATTERN, 'release tag')
|
||||
if (previous !== undefined && compareTags(previous, tag) >= 0) throw new Error(`${tag}: release tags must be unique and in semantic-version order`)
|
||||
previous = tag
|
||||
timestamp(release.sourceDate, `${tag} source date`)
|
||||
if (release.publishedAt !== null) timestamp(release.publishedAt, `${tag} publication date`)
|
||||
version(release.sessionFormatVersion, `${tag} Session format version`)
|
||||
}
|
||||
return input as unknown as PersistenceReleaseManifest
|
||||
}
|
||||
|
||||
function machineBlock(source: string, label: string): string {
|
||||
if (/\.[cm]?[jt]sx?(?::\d+(?::\d+)?|#L\d+(?:-L\d+)?)/u.test(source)) {
|
||||
throw new Error(`${label}: historical source references must omit line numbers`)
|
||||
}
|
||||
const metadata = /^---\n([\s\S]*?)\n---(?:\n|$)/u.exec(source)?.[1]
|
||||
const frontmatter: unknown = metadata === undefined ? undefined : load(metadata, { schema: JSON_SCHEMA })
|
||||
if (frontmatter === null || typeof frontmatter !== 'object' || !('kind' in frontmatter) || frontmatter.kind !== 'persistence-release') {
|
||||
throw new Error(`${label}: expected persistence-release frontmatter kind`)
|
||||
}
|
||||
const blocks = [...source.matchAll(/^```yaml persistence-release[^\S\n]*\n([\s\S]*?)^```[^\S\n]*$/gmu)]
|
||||
if (blocks.length !== 1) throw new Error(`${label}: expected exactly one persistence-release machine record`)
|
||||
return (blocks[0] as RegExpMatchArray)[1] as string
|
||||
}
|
||||
|
||||
function parseRecord(source: string, release: PersistenceRelease, previous: string | null): PersistenceReleaseRecord {
|
||||
const input = object(load(source, { schema: JSON_SCHEMA }), ['schemaVersion', 'tag', 'previous', 'sessionFormatVersion', 'changes'], release.tag)
|
||||
if (input.schemaVersion !== 1) throw new Error(`${release.tag}: unsupported persistence release record schema version`)
|
||||
for (const field of ['tag', 'sessionFormatVersion'] as const) {
|
||||
if (input[field] !== release[field]) throw new Error(`${release.tag}: record ${field} does not match manifest`)
|
||||
}
|
||||
if (input.previous !== previous) throw new Error(`${release.tag}: predecessor must be ${String(previous)}`)
|
||||
const roots = new Set<string>()
|
||||
for (const raw of array(input.changes, `${release.tag} changes`)) {
|
||||
const change = object(raw, ['root', 'before', 'after'], release.tag)
|
||||
const root = string(change.root, /^(?:SessionHeader|JsonlHeaderLine|SessionEventEnvelope|event:.+)$/u, 'changed root')
|
||||
if (roots.has(root)) throw new Error(`${release.tag}: duplicate change for ${root}`)
|
||||
roots.add(root)
|
||||
for (const field of ['before', 'after']) if (change[field] !== null) string(change[field], DIGEST_PATTERN, `${release.tag} ${field} digest`)
|
||||
}
|
||||
return input as unknown as PersistenceReleaseRecord
|
||||
}
|
||||
|
||||
function validateTypes(snapshot: PersistenceSchemaInventory, tag: string): void {
|
||||
const reachable = new Set<string>()
|
||||
for (const root of snapshot.roots) {
|
||||
for (const [index] of root.schema.nodes.entries()) reachable.add(schemaDigest(canonicalizeSchema(root.schema.nodes, index)))
|
||||
}
|
||||
const listed = new Set<string>()
|
||||
for (const type of snapshot.types) {
|
||||
if (listed.has(type.digest)) throw new Error(`${tag}: duplicate schema type ${type.digest}`)
|
||||
listed.add(type.digest)
|
||||
if (!reachable.has(type.digest)) throw new Error(`${tag}: unreferenced schema type ${type.digest}`)
|
||||
}
|
||||
if (listed.size !== reachable.size) throw new Error(`${tag}: schema types must cover every reachable type`)
|
||||
}
|
||||
|
||||
function validateVersion(roots: ReadonlyMap<string, PersistenceRoot>, release: PersistenceRelease): void {
|
||||
for (const key of ['SessionHeader', 'JsonlHeaderLine', 'SessionEventEnvelope']) {
|
||||
if (!roots.has(key)) throw new Error(`${release.tag}: reconstructed state is missing ${key}`)
|
||||
}
|
||||
const header = roots.get('SessionHeader') as PersistenceRoot
|
||||
const node = header.schema.nodes[0]
|
||||
const field = node?.kind === 'object' ? node.properties.find(property => property.name === 'version') : undefined
|
||||
const value = field === undefined ? undefined : header.schema.nodes[field.type]
|
||||
if (field?.optional !== false || !(value?.kind === 'primitive' && value.type === 'number'
|
||||
|| value?.kind === 'literal' && value.value === release.sessionFormatVersion)) {
|
||||
throw new Error(`${release.tag}: SessionHeader.version does not match the recorded format version`)
|
||||
}
|
||||
}
|
||||
|
||||
/** Read and validate every pinned prerelease and reconstruct adjacent type changes.
|
||||
* @param root - repository directory containing the committed release archive.
|
||||
* @returns verified records and informational classifications, without enforcing modern version-bump rules.
|
||||
*/
|
||||
export function loadPersistenceReleases(root: string): PersistenceReleases {
|
||||
const directory = join(root, ARCHIVE_DIRECTORY)
|
||||
const manifest = parseManifest(JSON.parse(readFileSync(join(directory, 'manifest.json'), 'utf8')))
|
||||
const files = new Set(readdirSync(directory))
|
||||
const expected = new Set(['manifest.json', 'README.md', 'README.zh.md', 'README.i18n.yaml'])
|
||||
for (const filename of expected) if (!files.has(filename)) throw new Error(`missing release artifact ${filename}`)
|
||||
for (const release of manifest.releases) {
|
||||
for (const suffix of ['.md', '.zh.md', '.i18n.yaml', '.schema.json']) {
|
||||
const filename = release.tag + suffix
|
||||
expected.add(filename)
|
||||
if (!files.has(filename)) throw new Error(`${release.tag}: missing release artifact ${filename}`)
|
||||
}
|
||||
}
|
||||
for (const file of files) if (!expected.has(file)) throw new Error(`unreferenced persistence release artifact: ${file}`)
|
||||
const entries: PersistenceReleaseEntry[] = []
|
||||
const roots = new Map<string, PersistenceRoot>()
|
||||
for (const release of manifest.releases) {
|
||||
const read = (suffix: string): string => readFileSync(join(directory, release.tag + suffix), 'utf8').replaceAll('\r\n', '\n')
|
||||
const english = machineBlock(read('.md'), `${release.tag}.md`)
|
||||
const chinese = machineBlock(read('.zh.md'), `${release.tag}.zh.md`)
|
||||
if (english !== chinese) throw new Error(`${release.tag}: bilingual machine records differ`)
|
||||
const record = parseRecord(english, release, entries.at(-1)?.release.tag ?? null)
|
||||
const snapshot = parseHistoricalPersistenceSnapshot(JSON.parse(read('.schema.json')))
|
||||
validateTypes(snapshot, release.tag)
|
||||
const afterRoots = new Map(snapshot.roots.map(root => [root.key, root]))
|
||||
const expectedRoots = record.changes.filter(change => change.after !== null).map(change => change.root).sort()
|
||||
if (JSON.stringify([...afterRoots.keys()].sort()) !== JSON.stringify(expectedRoots)) throw new Error(`${release.tag}: snapshot roots do not match changed after schemas`)
|
||||
const differences: (PersistenceTypeChange & { readonly root: string })[] = []
|
||||
for (const change of record.changes) {
|
||||
const before = roots.get(change.root) ?? null
|
||||
const after = afterRoots.get(change.root) ?? null
|
||||
if (change.before !== (before?.digest ?? null)) throw new Error(`${release.tag}: before digest mismatch for ${change.root}`)
|
||||
if (change.after !== (after?.digest ?? null)) throw new Error(`${release.tag}: after digest mismatch for ${change.root}`)
|
||||
const changes = classifyPersistenceChange(before, after)
|
||||
if (changes.length === 0) throw new Error(`${release.tag}: unchanged transition for ${change.root}`)
|
||||
differences.push(...changes.map(value => ({ ...value, root: change.root })))
|
||||
if (after === null) roots.delete(change.root)
|
||||
else roots.set(change.root, after)
|
||||
}
|
||||
validateVersion(roots, release)
|
||||
entries.push({ release, record, snapshot, roots: new Map(roots), differences })
|
||||
}
|
||||
return { manifest, entries }
|
||||
}
|
||||
|
||||
/** Validate the archive and check or refresh its bounded factual Markdown regions.
|
||||
* @param args - CLI arguments; --write refreshes facts and pairing sidecars after complete validation.
|
||||
* @param root - default repository directory, overridden by --root when provided.
|
||||
* @returns the verified release counts and optional number of refreshed artifacts.
|
||||
*/
|
||||
export function runPersistenceReleases(args: readonly string[], root = resolve(import.meta.dirname, '..')): string {
|
||||
const { values } = parseArgs({ args: [...args], options: { root: { type: 'string' }, write: { type: 'boolean' } } })
|
||||
root = resolve(values.root ?? root)
|
||||
const archive = loadPersistenceReleases(root)
|
||||
const artifacts = persistenceReleaseFactArtifacts(root, archive)
|
||||
const changed = artifacts.filter(artifact => readFileSync(join(root, artifact.path), 'utf8') !== artifact.content)
|
||||
const stale = changed.filter(artifact => artifact.path.endsWith('.md'))
|
||||
if (!values.write && stale.length > 0) throw new Error(`Stale persistence release facts: ${stale.map(file => file.path).join(', ')}. Run pnpm run verify-persistence-releases --write.`)
|
||||
if (values.write) for (const artifact of changed) writeFileSync(join(root, artifact.path), artifact.content)
|
||||
return `Persistence release archive: ${archive.entries.length} records, ${archive.entries.length - 1} adjacent transitions verified.`
|
||||
+ (values.write ? ` Refreshed ${changed.length} file${changed.length === 1 ? '' : 's'}.` : '')
|
||||
}
|
||||
|
||||
if (process.argv[1] !== undefined && resolve(process.argv[1]) === import.meta.filename) {
|
||||
try {
|
||||
console.log(runPersistenceReleases(process.argv.slice(2)))
|
||||
} catch (error: unknown) {
|
||||
console.error(error instanceof Error ? error.message : String(error))
|
||||
process.exitCode = 1
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,89 @@
|
||||
import { describe, expect, it } from 'vitest'
|
||||
import { canonicalizeSchema, isArbitraryJsonSchema, schemaDigest, type SchemaNode } from './persistence-schema-model.ts'
|
||||
|
||||
const string: SchemaNode = { kind: 'primitive', type: 'string' }
|
||||
const number: SchemaNode = { kind: 'primitive', type: 'number' }
|
||||
|
||||
describe('canonical persisted type graphs', () => {
|
||||
it('ignores source ordering and shared versus duplicated subtypes', () => {
|
||||
const left: SchemaNode[] = [
|
||||
{ kind: 'object', properties: [{ name: 'b', type: 1, optional: false }, { name: 'a', type: 1, optional: true }], indices: [] }, string,
|
||||
]
|
||||
const right: SchemaNode[] = [
|
||||
string, string,
|
||||
{ kind: 'object', properties: [{ name: 'a', type: 0, optional: true }, { name: 'b', type: 1, optional: false }], indices: [] },
|
||||
]
|
||||
expect(canonicalizeSchema(left, 0)).toEqual(canonicalizeSchema(right, 2))
|
||||
})
|
||||
|
||||
it('minimizes differently factored recursive aliases to the same graph', () => {
|
||||
const self: SchemaNode[] = [
|
||||
{ kind: 'object', properties: [{ name: 'next', type: 0, optional: true }, { name: 'value', type: 1, optional: false }], indices: [] }, string,
|
||||
]
|
||||
const mutual: SchemaNode[] = [
|
||||
{ kind: 'object', properties: [{ name: 'value', type: 2, optional: false }, { name: 'next', type: 1, optional: true }], indices: [] },
|
||||
{ kind: 'object', properties: [{ name: 'next', type: 0, optional: true }, { name: 'value', type: 3, optional: false }], indices: [] }, string, string,
|
||||
]
|
||||
const normalized = canonicalizeSchema(self, 0)
|
||||
expect(canonicalizeSchema(mutual, 0)).toEqual(normalized)
|
||||
expect(canonicalizeSchema(normalized.nodes, 0)).toEqual(normalized)
|
||||
mutual[3] = number
|
||||
expect(schemaDigest(canonicalizeSchema(mutual, 0))).not.toBe(schemaDigest(normalized))
|
||||
})
|
||||
|
||||
it('flattens reordered unions and removes structurally equal alternatives', () => {
|
||||
const flat: SchemaNode[] = [{ kind: 'union', types: [1, 2] }, string, number]
|
||||
const factored: SchemaNode[] = [string, number, { kind: 'union', types: [0, 3] }, { kind: 'union', types: [1, 0] }]
|
||||
expect(canonicalizeSchema(flat, 0)).toEqual(canonicalizeSchema(factored, 2))
|
||||
expect(canonicalizeSchema([{ kind: 'union', types: [1, 2] }, string, string], 0)).toEqual(canonicalizeSchema([string], 0))
|
||||
expect(canonicalizeSchema([{ kind: 'union', types: [1, 2] }, { kind: 'literal', value: true }, { kind: 'literal', value: false }], 0))
|
||||
.toEqual(canonicalizeSchema([{ kind: 'primitive', type: 'boolean' }], 0))
|
||||
})
|
||||
|
||||
it('ignores recursive union, field, index signature and graph numbering order together', () => {
|
||||
const original: SchemaNode[] = [
|
||||
{ kind: 'union', types: [1, 2, 3] },
|
||||
{ kind: 'object', properties: [{ name: 'label', type: 5, optional: false }, { name: 'next', type: 0, optional: true }], indices: [] },
|
||||
{ kind: 'array', element: 0 },
|
||||
{ kind: 'object', properties: [], indices: [{ key: 5, value: 0 }, { key: 4, value: 1 }] },
|
||||
number,
|
||||
string,
|
||||
]
|
||||
const reordered: SchemaNode[] = [
|
||||
string,
|
||||
{ kind: 'object', properties: [], indices: [{ key: 3, value: 5 }, { key: 0, value: 4 }] },
|
||||
{ kind: 'array', element: 4 },
|
||||
number,
|
||||
{ kind: 'union', types: [1, 2, 5] },
|
||||
{ kind: 'object', properties: [{ name: 'next', type: 4, optional: true }, { name: 'label', type: 0, optional: false }], indices: [] },
|
||||
]
|
||||
expect(canonicalizeSchema(reordered, 4)).toEqual(canonicalizeSchema(original, 0))
|
||||
})
|
||||
|
||||
it('preserves tuple positions, element absence, and rest elements', () => {
|
||||
const baseline: SchemaNode[] = [{ kind: 'tuple', elements: [{ type: 1, optional: false, rest: false }, { type: 2, optional: true, rest: false }] }, string, number]
|
||||
const reversed: SchemaNode[] = [{ kind: 'tuple', elements: [{ type: 2, optional: false, rest: false }, { type: 1, optional: true, rest: false }] }, string, number]
|
||||
const rest: SchemaNode[] = [{ kind: 'tuple', elements: [{ type: 1, optional: false, rest: false }, { type: 2, optional: false, rest: true }] }, string, number]
|
||||
const digest = schemaDigest(canonicalizeSchema(baseline, 0))
|
||||
expect(schemaDigest(canonicalizeSchema(reversed, 0))).not.toBe(digest)
|
||||
expect(schemaDigest(canonicalizeSchema(rest, 0))).not.toBe(digest)
|
||||
})
|
||||
|
||||
it('recognizes arbitrary recursive JSON structurally and retains its definition', () => {
|
||||
const json: SchemaNode[] = [
|
||||
{ kind: 'union', types: [1, 2, 3, 4, 5, 6] },
|
||||
{ kind: 'primitive', type: 'null' }, { kind: 'primitive', type: 'boolean' }, number, string,
|
||||
{ kind: 'array', element: 0 }, { kind: 'object', properties: [], indices: [{ key: 4, value: 0 }] },
|
||||
]
|
||||
const schema = canonicalizeSchema(json, 0)
|
||||
expect(isArbitraryJsonSchema(schema)).toBe(true)
|
||||
expect(schema.nodes.some(node => node.kind === 'array' && node.element === 0)).toBe(true)
|
||||
json[0] = { kind: 'union', types: [1, 2, 3, 4, 5] }
|
||||
expect(isArbitraryJsonSchema(canonicalizeSchema(json, 0))).toBe(false)
|
||||
})
|
||||
|
||||
it('rejects missing references and unproductive union cycles', () => {
|
||||
expect(() => canonicalizeSchema([{ kind: 'array', element: 5 }], 0)).toThrow('missing node 5')
|
||||
expect(() => canonicalizeSchema([{ kind: 'union', types: [0] }], 0)).toThrow('union cycle')
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,246 @@
|
||||
/**
|
||||
* Source-independent JSON type graphs and canonical persistence fingerprints.
|
||||
* Numeric references are local to one graph; names and source locations are metadata.
|
||||
*/
|
||||
|
||||
import { createHash } from 'node:crypto'
|
||||
|
||||
/** One JSON property, with absence represented independently of its value type. */
|
||||
export interface SchemaProperty {
|
||||
readonly name: string
|
||||
readonly type: number
|
||||
readonly optional: boolean
|
||||
}
|
||||
|
||||
/** One positional tuple element. */
|
||||
export interface SchemaTupleElement {
|
||||
readonly type: number
|
||||
readonly optional: boolean
|
||||
readonly rest: boolean
|
||||
}
|
||||
|
||||
/** A resolved persisted type; references address nodes in the enclosing graph. */
|
||||
export type SchemaNode =
|
||||
| { readonly kind: 'primitive'; readonly type: 'null' | 'boolean' | 'number' | 'string' | 'never' }
|
||||
| { readonly kind: 'literal'; readonly value: string | number | boolean }
|
||||
| { readonly kind: 'opaque'; readonly reason: 'any' | 'unknown' }
|
||||
| { readonly kind: 'array'; readonly element: number }
|
||||
| { readonly kind: 'tuple'; readonly elements: readonly SchemaTupleElement[] }
|
||||
| { readonly kind: 'object'; readonly properties: readonly SchemaProperty[]; readonly indices: readonly { readonly key: number; readonly value: number }[] }
|
||||
| { readonly kind: 'union'; readonly types: readonly number[] }
|
||||
|
||||
/** A self-contained minimized graph with deterministic root-first node numbering. */
|
||||
export interface CanonicalSchema {
|
||||
readonly root: 0
|
||||
readonly nodes: readonly SchemaNode[]
|
||||
}
|
||||
|
||||
/** One independently tracked persistent record vocabulary. */
|
||||
export interface PersistenceRoot {
|
||||
readonly key: string
|
||||
readonly kind: 'header' | 'envelope' | 'event'
|
||||
readonly event?: string
|
||||
readonly surface?: boolean
|
||||
readonly digest: string
|
||||
readonly schema: CanonicalSchema
|
||||
}
|
||||
|
||||
/** One reachable structural type and its non-fingerprinted source declaration metadata. */
|
||||
export interface PersistenceType {
|
||||
readonly digest: string
|
||||
readonly schema: CanonicalSchema
|
||||
readonly names: readonly string[]
|
||||
readonly sources: readonly string[]
|
||||
}
|
||||
|
||||
/** Complete current-source persistence inventory; version pins normalization too. */
|
||||
export interface PersistenceSchemaInventory {
|
||||
readonly formatVersion: 1
|
||||
readonly roots: readonly PersistenceRoot[]
|
||||
readonly types: readonly PersistenceType[]
|
||||
}
|
||||
|
||||
/**
|
||||
* Visit direct graph edges in their normalized semantic order.
|
||||
* @param node - resolved graph node.
|
||||
* @returns referenced node indices, including repeated ordered edges.
|
||||
*/
|
||||
export function schemaChildren(node: SchemaNode): number[] {
|
||||
switch (node.kind) {
|
||||
case 'array': return [node.element]
|
||||
case 'tuple': return node.elements.map(element => element.type)
|
||||
case 'object': return [...node.properties.map(property => property.type), ...node.indices.flatMap(index => [index.key, index.value])]
|
||||
case 'union': return [...node.types]
|
||||
case 'primitive':
|
||||
case 'literal':
|
||||
case 'opaque': return []
|
||||
default: return assertNever(node)
|
||||
}
|
||||
}
|
||||
|
||||
function mapNode(node: SchemaNode, ref: (id: number) => number): SchemaNode {
|
||||
switch (node.kind) {
|
||||
case 'array': return { kind: 'array', element: ref(node.element) }
|
||||
case 'tuple': return { kind: 'tuple', elements: node.elements.map(element => ({ type: ref(element.type), optional: element.optional, rest: element.rest })) }
|
||||
case 'object': return {
|
||||
kind: 'object',
|
||||
properties: [...node.properties].sort((left, right) => compare(left.name, right.name))
|
||||
.map(property => ({ name: property.name, type: ref(property.type), optional: property.optional })),
|
||||
indices: node.indices.map(index => ({ key: ref(index.key), value: ref(index.value) }))
|
||||
.sort((left, right) => left.key - right.key || left.value - right.value),
|
||||
}
|
||||
case 'union': return { kind: 'union', types: [...new Set(node.types.map(ref))].sort((left, right) => left - right) }
|
||||
case 'primitive': return { kind: 'primitive', type: node.type }
|
||||
case 'literal': return { kind: 'literal', value: node.value }
|
||||
case 'opaque': return { kind: 'opaque', reason: node.reason }
|
||||
default: return assertNever(node)
|
||||
}
|
||||
}
|
||||
|
||||
function partition(nodes: readonly SchemaNode[]): number[] {
|
||||
let colors = nodes.map(() => 0)
|
||||
for (;;) {
|
||||
const signatures = nodes.map((node, index) => JSON.stringify([colors[index], mapNode(node, id => colors[id] as number)]))
|
||||
const ordered = [...new Set(signatures)].sort(compare)
|
||||
const ids = new Map(ordered.map((value, index) => [value, index]))
|
||||
const next = signatures.map(value => ids.get(value) as number)
|
||||
const unchanged = new Set(next).size === new Set(colors).size
|
||||
colors = next
|
||||
if (unchanged) return colors
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Minimize bisimilar recursive nodes and number the reachable graph deterministically.
|
||||
* @param input - resolved nodes; property and union order may be arbitrary.
|
||||
* @param root - index of the requested root.
|
||||
* @returns canonical graph excluding unreachable nodes and duplicate structures.
|
||||
*/
|
||||
export function canonicalizeSchema(input: readonly SchemaNode[], root: number): CanonicalSchema {
|
||||
input = normalizeUnions(input)
|
||||
const selected: number[] = []
|
||||
const positions = new Map<number, number>()
|
||||
const select = (id: number): void => {
|
||||
if (!Number.isInteger(id) || id < 0 || id >= input.length) throw new Error(`persistence schema: missing node ${String(id)}`)
|
||||
if (positions.has(id)) return
|
||||
positions.set(id, selected.length)
|
||||
selected.push(id)
|
||||
for (const child of schemaChildren(input[id] as SchemaNode)) select(child)
|
||||
}
|
||||
select(root)
|
||||
let nodes = selected.map(id => mapNode(input[id] as SchemaNode, child => positions.get(child) as number))
|
||||
let rootIndex = 0
|
||||
for (;;) {
|
||||
const colors = partition(nodes)
|
||||
const representatives = new Map<number, number>()
|
||||
colors.forEach((color, index) => { if (!representatives.has(color)) representatives.set(color, index) })
|
||||
const aliases = new Map<number, number>()
|
||||
nodes.forEach((node, index) => {
|
||||
if (node.kind !== 'union') return
|
||||
const members = [...new Set(node.types.map(child => colors[child] as number))]
|
||||
if (members.length === 1) aliases.set(index, representatives.get(members[0] as number) as number)
|
||||
})
|
||||
if (aliases.size > 0) {
|
||||
const resolve = (id: number): number => {
|
||||
const seen = new Set<number>()
|
||||
while (aliases.has(id)) {
|
||||
if (seen.has(id)) throw new Error('persistence schema: union cycle has no material type')
|
||||
seen.add(id)
|
||||
id = aliases.get(id) as number
|
||||
}
|
||||
return id
|
||||
}
|
||||
rootIndex = resolve(rootIndex)
|
||||
nodes = nodes.map((node, index) => aliases.has(index) ? nodes[resolve(index)] as SchemaNode : mapNode(node, resolve))
|
||||
continue
|
||||
}
|
||||
const emitted = new Map<number, number>()
|
||||
const result: SchemaNode[] = []
|
||||
const visit = (id: number): number => {
|
||||
const color = colors[id] as number
|
||||
const existing = emitted.get(color)
|
||||
if (existing !== undefined) return existing
|
||||
const position = result.length
|
||||
emitted.set(color, position)
|
||||
result.push({ kind: 'primitive', type: 'never' })
|
||||
const representative = representatives.get(color) as number
|
||||
const colored = mapNode(nodes[representative] as SchemaNode, child => colors[child] as number)
|
||||
result[position] = mapNode(colored, child => visit(representatives.get(child) as number))
|
||||
return position
|
||||
}
|
||||
visit(rootIndex)
|
||||
return { root: 0, nodes: result }
|
||||
}
|
||||
}
|
||||
|
||||
function normalizeUnions(input: readonly SchemaNode[]): SchemaNode[] {
|
||||
const result = [...input]
|
||||
const flattened = (id: number, visiting: Set<number>): number[] => {
|
||||
const node = input[id]
|
||||
if (node === undefined) throw new Error(`persistence schema: missing node ${String(id)}`)
|
||||
if (node.kind !== 'union') return [id]
|
||||
if (visiting.has(id)) throw new Error('persistence schema: union cycle has no material type')
|
||||
const next = new Set(visiting).add(id)
|
||||
return node.types.flatMap(child => flattened(child, next))
|
||||
}
|
||||
for (const [id, node] of input.entries()) {
|
||||
if (node.kind !== 'union') continue
|
||||
let members = [...new Set(flattened(id, new Set()))]
|
||||
const primitives = new Set(members.flatMap((child) => {
|
||||
const value = input[child] as SchemaNode
|
||||
return value.kind === 'primitive' ? [value.type] : []
|
||||
}))
|
||||
const literals = members.flatMap((child) => {
|
||||
const value = input[child] as SchemaNode
|
||||
return value.kind === 'literal' ? [value.value] : []
|
||||
})
|
||||
if (!primitives.has('boolean') && literals.includes(true) && literals.includes(false)) {
|
||||
primitives.add('boolean')
|
||||
members.push(result.length)
|
||||
result.push({ kind: 'primitive', type: 'boolean' })
|
||||
}
|
||||
members = members.filter((child) => {
|
||||
const value = result[child] as SchemaNode
|
||||
if (value.kind === 'primitive') return value.type !== 'never'
|
||||
return value.kind !== 'literal' || !primitives.has(typeof value.value as 'string' | 'number' | 'boolean')
|
||||
})
|
||||
result[id] = members.length === 0 ? { kind: 'primitive', type: 'never' } : { kind: 'union', types: members }
|
||||
}
|
||||
return result
|
||||
}
|
||||
|
||||
/**
|
||||
* Compute the versioned SHA-256 fingerprint of a canonical graph.
|
||||
* @param schema - canonical resolved persisted type.
|
||||
* @returns lowercase hexadecimal digest.
|
||||
*/
|
||||
export function schemaDigest(schema: CanonicalSchema): string {
|
||||
return createHash('sha256').update('dsh-persistence-schema-v1\n').update(JSON.stringify(schema)).digest('hex')
|
||||
}
|
||||
|
||||
/**
|
||||
* Recognize the complete recursive JSON value language without relying on type names.
|
||||
* @param schema - canonical resolved type.
|
||||
* @returns whether the type permits arbitrary JSON values.
|
||||
*/
|
||||
export function isArbitraryJsonSchema(schema: CanonicalSchema): boolean {
|
||||
return schemaDigest(schema) === JSON_VALUE_DIGEST
|
||||
}
|
||||
|
||||
const JSON_VALUE_DIGEST = schemaDigest(canonicalizeSchema([
|
||||
{ kind: 'union', types: [1, 2, 3, 4, 5, 6] },
|
||||
{ kind: 'primitive', type: 'null' },
|
||||
{ kind: 'primitive', type: 'boolean' },
|
||||
{ kind: 'primitive', type: 'number' },
|
||||
{ kind: 'primitive', type: 'string' },
|
||||
{ kind: 'array', element: 0 },
|
||||
{ kind: 'object', properties: [], indices: [{ key: 4, value: 0 }] },
|
||||
], 0))
|
||||
|
||||
function compare(left: string, right: string): number {
|
||||
return left < right ? -1 : left > right ? 1 : 0
|
||||
}
|
||||
|
||||
function assertNever(value: never): never {
|
||||
throw new Error(`persistence schema: unsupported node ${JSON.stringify(value)}`)
|
||||
}
|
||||
@@ -0,0 +1,324 @@
|
||||
import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { dirname, join, resolve } from 'node:path'
|
||||
import { afterEach, describe, expect, it } from 'vitest'
|
||||
import { collectLogEvents } from './gen-persistence-catalog.ts'
|
||||
import { extractPersistenceSchema } from './persistence-schema.ts'
|
||||
import { canonicalizeSchema, isArbitraryJsonSchema, schemaDigest, type PersistenceSchemaInventory } from './persistence-schema-model.ts'
|
||||
|
||||
const roots: string[] = []
|
||||
afterEach(() => {
|
||||
for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true, maxRetries: 3 })
|
||||
})
|
||||
|
||||
function put(root: string, file: string, source: string): void {
|
||||
const path = join(root, file)
|
||||
mkdirSync(dirname(path), { recursive: true })
|
||||
writeFileSync(path, source)
|
||||
}
|
||||
|
||||
function fixture(payload: string, options: { surface?: string; event?: string } = {}): string {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-persistence-schema-'))
|
||||
roots.push(root)
|
||||
put(root, 'tsconfig.host.json', JSON.stringify({ compilerOptions: {
|
||||
target: 'es2024', module: 'esnext', moduleResolution: 'bundler', strict: true, skipLibCheck: true,
|
||||
types: [], paths: {
|
||||
'@deepseek-ai/dsh-session/types': ['./packages/core/session/src/types.ts'],
|
||||
'@fixture/payload': ['./packages/domain/payload/src/types.ts'],
|
||||
},
|
||||
}, include: ['packages/**/src/**/*.ts'] }))
|
||||
put(root, 'packages/core/session/package.json', '{"name":"@deepseek-ai/dsh-session"}')
|
||||
put(root, 'packages/domain/payload/package.json', '{"name":"@fixture/payload"}')
|
||||
put(root, 'packages/session/session-persistence-jsonl/src/format.ts', "interface HeaderLine {type: 'session'; version: number; id: string; delegationDepth: number}\nexport {}\n")
|
||||
put(root, 'packages/domain/payload/src/types.ts', payload)
|
||||
put(root, 'packages/core/session/src/types.ts', `
|
||||
import type { Payload } from '@fixture/payload'
|
||||
export interface SessionHeader { version: 3; id: string; createdAt: number }
|
||||
export interface SessionEventMap {
|
||||
/** One recorded payload. */
|
||||
'test/record': Payload
|
||||
${options.event ?? ''}
|
||||
}
|
||||
export type SurfaceEventType = ${options.surface ?? 'never'}
|
||||
export type SessionEvent<T extends keyof SessionEventMap = keyof SessionEventMap> = {
|
||||
[K in keyof SessionEventMap]: { type: K; seq: number; time: number; data: SessionEventMap[K] }
|
||||
& (K extends SurfaceEventType ? { surfaceOp: 'append' | { replace: number } } : { surfaceOp?: never })
|
||||
}[T]
|
||||
`)
|
||||
return root
|
||||
}
|
||||
|
||||
function event(inventory: PersistenceSchemaInventory, name = 'test/record'): string {
|
||||
const root = inventory.roots.find(root => root.event === name)
|
||||
if (root === undefined) throw new Error(`missing test event ${name}`)
|
||||
return root.digest
|
||||
}
|
||||
|
||||
describe('persistent source type extraction', () => {
|
||||
it('ignores alias names, files, documentation, readonly, brands and property order', () => {
|
||||
const left = fixture('declare const brand: unique symbol; type Id = string & {readonly [brand]: "Id"}; export interface Payload { readonly id: Id; value?: number }')
|
||||
const right = fixture('type Renamed = string; /** Different documentation. */ export type Payload = {value?: number; id: Renamed}')
|
||||
expect(event(extractPersistenceSchema(left))).toBe(event(extractPersistenceSchema(right)))
|
||||
})
|
||||
|
||||
it.each([
|
||||
['nested field order',
|
||||
'export interface Payload {\n id: string\n detail: {\n label: string\n count?: number\n }\n}',
|
||||
'export interface Payload {\n detail: {\n count?: number\n label: string\n }\n id: string\n}'],
|
||||
['anonymous union order',
|
||||
'export type Payload =\n { a: string }\n | { b: number }\n | { c?: boolean }',
|
||||
'export type Payload =\n { c?: boolean }\n | { b: number }\n | { a: string }'],
|
||||
['recursive union order',
|
||||
'export type Payload =\n { a: string; next?: Payload }\n | { b: number; next?: Payload }\n | null',
|
||||
'export type Payload =\n null\n | { next?: Payload; b: number }\n | { next?: Payload; a: string }'],
|
||||
['intersection and distributed union order',
|
||||
'type A = { a: string } | { b: number }; type B = { c: boolean }; export type Payload = A & B',
|
||||
'type A = { b: number } | { a: string }; type B = { c: boolean }; export type Payload = B & A'],
|
||||
['index signature order',
|
||||
'export interface Payload { [key: string]: string | number; [key: number]: number }',
|
||||
'export interface Payload { [key: number]: number; [key: string]: number | string }'],
|
||||
['type declaration order',
|
||||
'interface A { a: string }\ninterface B { b: number }\nexport type Payload = A | B',
|
||||
'interface B { b: number }\ninterface A { a: string }\nexport type Payload = B | A'],
|
||||
['merged declaration order',
|
||||
'export interface Payload { a: string }\nexport interface Payload { b: number }',
|
||||
'export interface Payload { b: number }\nexport interface Payload { a: string }'],
|
||||
['mapped key order',
|
||||
'export type Payload = { [K in "a" | "b" | "c"]: string }',
|
||||
'export type Payload = { [K in "c" | "b" | "a"]: string }'],
|
||||
['explicit enum member order',
|
||||
'enum Value {\n A = "a",\n B = "b",\n}\nexport interface Payload { value: Value }',
|
||||
'enum Value {\n B = "b",\n A = "a",\n}\nexport interface Payload { value: Value }'],
|
||||
])('keeps every root and type digest unchanged by %s', (_name, before, after) => {
|
||||
const root = fixture(before)
|
||||
const inventory = extractPersistenceSchema(root)
|
||||
put(root, 'packages/domain/payload/src/types.ts', after)
|
||||
const reordered = extractPersistenceSchema(root)
|
||||
expect(reordered.roots).toEqual(inventory.roots)
|
||||
expect(reordered.types.map(({ digest, schema }) => ({ digest, schema })))
|
||||
.toEqual(inventory.types.map(({ digest, schema }) => ({ digest, schema })))
|
||||
})
|
||||
|
||||
it.each([
|
||||
['tuple positions', 'export type Payload = [string, number]', 'export type Payload = [number, string]'],
|
||||
['implicit enum values', 'enum Value { A, B }; export interface Payload { value: Value.A }', 'enum Value { B, A }; export interface Payload { value: Value.A }'],
|
||||
])('changes the digest when reordering changes %s', (_name, before, after) => {
|
||||
const root = fixture(before)
|
||||
const digest = event(extractPersistenceSchema(root))
|
||||
put(root, 'packages/domain/payload/src/types.ts', after)
|
||||
expect(event(extractPersistenceSchema(root))).not.toBe(digest)
|
||||
})
|
||||
|
||||
it('keeps header, envelope and event digests unchanged when root declarations are reordered', () => {
|
||||
const record = " /** One recorded payload. */\n 'test/record': Payload"
|
||||
const other = "/** Another recorded payload. */\n 'test/other': { value: number }"
|
||||
const root = fixture('export interface Payload { id: string }', {
|
||||
surface: "'test/record' | 'test/other'",
|
||||
event: other,
|
||||
})
|
||||
const inventory = extractPersistenceSchema(root)
|
||||
const source = readFileSync(join(root, 'packages/core/session/src/types.ts'), 'utf8')
|
||||
const reordered = source
|
||||
.replace(`${record}\n ${other}`, ` ${other}\n${record}`)
|
||||
.replace('version: 3; id: string; createdAt: number', 'createdAt: number; id: string; version: 3')
|
||||
.replace("'test/record' | 'test/other'", "'test/other' | 'test/record'")
|
||||
.replace('type: K; seq: number; time: number; data: SessionEventMap[K]', 'data: SessionEventMap[K]; time: number; seq: number; type: K')
|
||||
expect(reordered.indexOf("'test/other':")).toBeLessThan(reordered.indexOf("'test/record':"))
|
||||
put(root, 'packages/core/session/src/types.ts', reordered)
|
||||
put(root, 'packages/session/session-persistence-jsonl/src/format.ts', "interface HeaderLine {delegationDepth: number; id: string; version: number; type: 'session'}\nexport {}\n")
|
||||
const result = extractPersistenceSchema(root)
|
||||
expect(result.roots).toEqual(inventory.roots)
|
||||
expect(result.types.map(({ digest, schema }) => ({ digest, schema })))
|
||||
.toEqual(inventory.types.map(({ digest, schema }) => ({ digest, schema })))
|
||||
})
|
||||
|
||||
it('materializes generic, conditional and mapped aliases into their concrete properties', () => {
|
||||
const generic = fixture('type Box<T> = { [K in keyof T]: T[K] extends string ? string[] : T[K] }; export type Payload = Box<{label: string; count?: number}>')
|
||||
const concrete = fixture('export interface Payload {count?: number; label: string[]}')
|
||||
expect(event(extractPersistenceSchema(generic))).toBe(event(extractPersistenceSchema(concrete)))
|
||||
})
|
||||
|
||||
it('retains transitive recursion without depending on alias factoring', () => {
|
||||
const self = fixture('export interface Payload { value: string; next?: Payload }')
|
||||
const mutual = fixture('interface Other {next?: Payload; value: string} export interface Payload {value: string; next?: Other}')
|
||||
const changed = fixture('interface Other {next?: Payload; value: number} export interface Payload {value: string; next?: Other}')
|
||||
const digest = event(extractPersistenceSchema(self))
|
||||
expect(event(extractPersistenceSchema(mutual))).toBe(digest)
|
||||
expect(event(extractPersistenceSchema(changed))).not.toBe(digest)
|
||||
})
|
||||
|
||||
it('includes independent Host modules that augment nested payload maps without event declarations', () => {
|
||||
const root = fixture('export interface NestedMap {first: {value: string}}; export type Payload = NestedMap[keyof NestedMap]')
|
||||
const before = extractPersistenceSchema(root)
|
||||
put(root, 'packages/domain/extension/src/index.ts', "import '@fixture/payload'; declare module '@fixture/payload' {interface NestedMap {second: {value: number}}}")
|
||||
const after = extractPersistenceSchema(root)
|
||||
expect(collectLogEvents(root)).toHaveLength(1)
|
||||
expect(event(after)).not.toBe(event(before))
|
||||
const data = after.types.find(item => item.schema.nodes[0]?.kind === 'union' && item.schema.nodes.some(node => node.kind === 'primitive' && node.type === 'number'))
|
||||
expect(data).toBeDefined()
|
||||
})
|
||||
|
||||
it('discovers plugin event merges and keeps ordinary event additions out of the envelope digest', () => {
|
||||
const root = fixture('export interface Payload {id: string}')
|
||||
const before = extractPersistenceSchema(root)
|
||||
put(root, 'packages/domain/extension/src/index.ts', `import '@deepseek-ai/dsh-session/types'; declare module '@deepseek-ai/dsh-session/types' {
|
||||
interface SessionEventMap {
|
||||
/** A plugin event. */
|
||||
'plugin/new': { optional?: boolean }
|
||||
}}
|
||||
`)
|
||||
const after = extractPersistenceSchema(root)
|
||||
expect(after.roots.some(root => root.event === 'plugin/new')).toBe(true)
|
||||
expect(after.roots.find(root => root.kind === 'envelope')?.digest).toBe(before.roots.find(root => root.kind === 'envelope')?.digest)
|
||||
expect(event(after)).toBe(event(before))
|
||||
})
|
||||
|
||||
it('includes JSX-module events and rejects unsupported inherited declarations there', () => {
|
||||
const root = fixture('export interface Payload {id: string}')
|
||||
put(root, 'packages/domain/extension/src/index.tsx', `import '@deepseek-ai/dsh-session/types'; declare module '@deepseek-ai/dsh-session/types' {
|
||||
interface SessionEventMap {
|
||||
/** A JSX-module event. */
|
||||
'plugin/tsx': { value: number }
|
||||
}}
|
||||
`)
|
||||
const config = join(root, 'tsconfig.host.json')
|
||||
const settings = JSON.parse(readFileSync(config, 'utf8')) as { include: string[] }
|
||||
settings.include.push('packages/**/src/**/*.tsx')
|
||||
writeFileSync(config, JSON.stringify(settings))
|
||||
expect(extractPersistenceSchema(root).roots.some(root => root.event === 'plugin/tsx')).toBe(true)
|
||||
put(root, 'packages/domain/extension/src/index.tsx', `import '@deepseek-ai/dsh-session/types';
|
||||
interface Extra { 'plugin/inherited': {value: number} }
|
||||
declare module '@deepseek-ai/dsh-session/types' { interface SessionEventMap extends Extra {} }
|
||||
`)
|
||||
expect(() => extractPersistenceSchema(root)).toThrow('uses extends')
|
||||
})
|
||||
|
||||
it('rejects an event map whose compiler vocabulary exceeds the discovered source corpus', () => {
|
||||
const root = fixture("import '../../../../vendor/events.ts'; export interface Payload {id: string}")
|
||||
put(root, 'vendor/events.ts', `import '@deepseek-ai/dsh-session/types'; declare module '@deepseek-ai/dsh-session/types' {
|
||||
interface SessionEventMap {
|
||||
/** A contribution outside the package source corpus. */
|
||||
'outside/event': { value: number }
|
||||
}}
|
||||
`)
|
||||
expect(() => extractPersistenceSchema(root)).toThrow('omitted: outside/event')
|
||||
})
|
||||
|
||||
it('keeps surface metadata strict and optional field additions visible', () => {
|
||||
const old = extractPersistenceSchema(fixture('export interface Payload {id: string}'))
|
||||
const optional = extractPersistenceSchema(fixture('export interface Payload {id: string; detail?: string}'))
|
||||
const surface = extractPersistenceSchema(fixture('export interface Payload {id: string}', { surface: "'test/record'" }))
|
||||
expect(event(old)).not.toBe(event(optional))
|
||||
expect(event(old)).not.toBe(event(surface))
|
||||
expect(surface.roots.find(root => root.event === 'test/record')?.surface).toBe(true)
|
||||
expect(surface.roots.find(root => root.kind === 'envelope')?.digest).not.toBe(old.roots.find(root => root.kind === 'envelope')?.digest)
|
||||
})
|
||||
|
||||
it('tracks the physical JSONL header independently of the logical Session header', () => {
|
||||
const root = fixture('export interface Payload {id: string}')
|
||||
const before = extractPersistenceSchema(root)
|
||||
put(root, 'packages/session/session-persistence-jsonl/src/format.ts', "interface HeaderLine {type: 'session'; version: number; id: string; delegationDepth: number; marker?: string}\nexport {}\n")
|
||||
const after = extractPersistenceSchema(root)
|
||||
expect(after.roots.find(root => root.key === 'JsonlHeaderLine')?.digest).not.toBe(before.roots.find(root => root.key === 'JsonlHeaderLine')?.digest)
|
||||
expect(after.roots.find(root => root.key === 'SessionHeader')?.digest).toBe(before.roots.find(root => root.key === 'SessionHeader')?.digest)
|
||||
})
|
||||
|
||||
it('keeps arbitrary JSON structural while explicitly identifying unknown and any', () => {
|
||||
const root = fixture('type Arbitrary = null | boolean | number | string | Arbitrary[] | {[key: string]: Arbitrary}; export interface Payload {json: Arbitrary; opaque: unknown; unsafe: any}')
|
||||
const model = extractPersistenceSchema(root)
|
||||
expect(model.types.some(item => isArbitraryJsonSchema(item.schema))).toBe(true)
|
||||
expect(model.types.filter(item => item.schema.nodes[0]?.kind === 'opaque').map(item => item.schema.nodes[0]))
|
||||
.toEqual(expect.arrayContaining([{ kind: 'opaque', reason: 'unknown' }, { kind: 'opaque', reason: 'any' }]))
|
||||
put(root, 'packages/domain/payload/src/types.ts', 'type Arbitrary = null | boolean | number | string | Arbitrary[]; export interface Payload {json: Arbitrary; opaque: unknown; unsafe: any}')
|
||||
const changed = extractPersistenceSchema(root)
|
||||
expect(event(changed)).not.toBe(event(model))
|
||||
expect(changed.types.some(item => isArbitraryJsonSchema(item.schema))).toBe(false)
|
||||
})
|
||||
|
||||
it('rejects invalid reachable declaration files despite inherited skipLibCheck', () => {
|
||||
const root = fixture("export type { Payload } from './declared.js'")
|
||||
put(root, 'packages/domain/payload/src/declared.d.ts', 'type Bad = ReturnType<42>; export interface Payload {value: Bad}')
|
||||
expect(() => extractPersistenceSchema(root)).toThrow('TS2344')
|
||||
})
|
||||
|
||||
it('preserves authored declaration-file any without checking unrelated declarations', () => {
|
||||
const root = fixture("export type { Payload } from './declared.js'")
|
||||
put(root, 'packages/domain/payload/src/declared.d.ts', 'type Declared = any; export interface Payload {value: Declared}; type Unrelated = ReturnType<42>')
|
||||
const model = extractPersistenceSchema(root)
|
||||
expect(model.types.some(item => item.schema.nodes[0]?.kind === 'opaque' && item.schema.nodes[0].reason === 'any')).toBe(true)
|
||||
})
|
||||
|
||||
it('locates named transitive definitions at their declarations instead of their references', () => {
|
||||
const root = fixture("import type { Detail as ImportedDetail } from './detail.js'\nexport interface Payload { first: ImportedDetail; second: ImportedDetail }")
|
||||
put(root, 'packages/domain/payload/src/detail.ts', '/** Detailed payload. */\nexport interface Detail { code: string; done: true }\n')
|
||||
const model = extractPersistenceSchema(root)
|
||||
const detail = model.types.find(item => item.names.includes('packages/domain/payload/src/detail.ts#Detail'))
|
||||
expect(detail?.sources).toEqual(['packages/domain/payload/src/detail.ts:2'])
|
||||
})
|
||||
|
||||
it('keeps shared scalar declaration metadata at real aliases and omits plain property references', () => {
|
||||
const root = fixture([
|
||||
'type Label = string',
|
||||
"type Done = 'done'",
|
||||
'export interface Payload {',
|
||||
' label: Label',
|
||||
' other: string',
|
||||
' state: Done',
|
||||
" fallback: 'done'",
|
||||
' count: number',
|
||||
'}',
|
||||
].join('\n'))
|
||||
const model = extractPersistenceSchema(root)
|
||||
const string = model.types.find(item => item.schema.nodes[0]?.kind === 'primitive' && item.schema.nodes[0].type === 'string')
|
||||
const literal = model.types.find(item => item.schema.nodes[0]?.kind === 'literal' && item.schema.nodes[0].value === 'done')
|
||||
const number = model.types.find(item => item.schema.nodes[0]?.kind === 'primitive' && item.schema.nodes[0].type === 'number')
|
||||
expect(string?.names).toEqual(['packages/domain/payload/src/types.ts#Label'])
|
||||
expect(string?.sources).toEqual(['packages/domain/payload/src/types.ts:1'])
|
||||
expect(literal?.names).toEqual(['packages/domain/payload/src/types.ts#Done'])
|
||||
expect(literal?.sources).toEqual(['packages/domain/payload/src/types.ts:2'])
|
||||
expect(number?.names).toEqual([])
|
||||
expect(number?.sources).toEqual([])
|
||||
})
|
||||
|
||||
it('uses the declaration of an anonymous object literal and never its containing property', () => {
|
||||
const root = fixture('export interface Payload {\n detail:\n { code: string }\n}')
|
||||
const model = extractPersistenceSchema(root)
|
||||
const detail = model.types.find((item) => {
|
||||
const node = item.schema.nodes[0]
|
||||
return node?.kind === 'object' && node.properties.length === 1 && node.properties[0]?.name === 'code'
|
||||
})
|
||||
expect(detail?.sources).toEqual(['packages/domain/payload/src/types.ts:3'])
|
||||
})
|
||||
|
||||
it.each([
|
||||
['missing type', 'export interface Payload {value: Missing}', 'TS2304'],
|
||||
['callable value', 'export interface Payload {value: () => void}', 'callable data'],
|
||||
['class instance', 'export class Instance {value: string = ""}; export interface Payload {value: Instance}', 'class instances'],
|
||||
['required undefined', 'export interface Payload {value: string | undefined}', 'no supported JSON'],
|
||||
['unresolved template', 'export interface Payload {value: `prefix-${string}`}', 'no supported JSON'],
|
||||
['empty object type', 'export type Payload = {}', 'unconstrained empty object'],
|
||||
['symbol property', 'declare const key: unique symbol; export interface Payload {[key]: string; value: number}', 'symbol-keyed data'],
|
||||
['conflicting merged property', 'export interface Payload {value: string}; export interface Payload {value: number}', 'TS2717'],
|
||||
['class intersection', 'class Instance {value: string = ""}; export type Payload = Instance & {extra: string}', 'class instances'],
|
||||
['invalid generic alias', 'type Bad = ReturnType<42>; export interface Payload {value: Bad}', 'TS2344'],
|
||||
])('rejects %s rather than weakening the schema', (_name, source, error) => {
|
||||
expect(() => extractPersistenceSchema(fixture(source))).toThrow(error)
|
||||
})
|
||||
|
||||
// Repository-wide TypeScript extraction and reachable-node hashing use the Windows coverage test budget.
|
||||
it('includes every real repository event and fingerprints every reachable node', { timeout: 90_000 }, () => {
|
||||
const root = resolve(import.meta.dirname, '..')
|
||||
const model = extractPersistenceSchema(root)
|
||||
expect(model.roots.filter(root => root.kind === 'event').map(root => root.event).sort())
|
||||
.toEqual(collectLogEvents(root).map(event => event.name).sort())
|
||||
expect(model.roots.some(root => root.kind === 'header')).toBe(true)
|
||||
expect(model.roots.some(root => root.kind === 'envelope')).toBe(true)
|
||||
const digests = new Set(model.types.map(type => type.digest))
|
||||
for (const root of model.roots) {
|
||||
expect(schemaDigest(root.schema)).toBe(root.digest)
|
||||
for (let node = 0; node < root.schema.nodes.length; node++) {
|
||||
expect(digests.has(schemaDigest(canonicalizeSchema(root.schema.nodes, node)))).toBe(true)
|
||||
}
|
||||
}
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,462 @@
|
||||
/** Extract complete persistent Session record types from one source-only compiler program. */
|
||||
|
||||
import { readFileSync } from 'node:fs'
|
||||
import { dirname, extname, relative, resolve, sep } from 'node:path'
|
||||
import ts from 'typescript'
|
||||
import { collectLogEvents } from './persistence-catalog-source.ts'
|
||||
import {
|
||||
canonicalizeSchema,
|
||||
schemaChildren,
|
||||
schemaDigest,
|
||||
type PersistenceRoot,
|
||||
type PersistenceSchemaInventory,
|
||||
type PersistenceType,
|
||||
type SchemaNode,
|
||||
type SchemaProperty,
|
||||
} from './persistence-schema-model.ts'
|
||||
|
||||
interface DeclarationMetadata {
|
||||
readonly names: Set<string>
|
||||
readonly sources: Set<string>
|
||||
}
|
||||
|
||||
interface RootInput {
|
||||
readonly key: string
|
||||
readonly kind: PersistenceRoot['kind']
|
||||
readonly event?: string
|
||||
readonly surface?: boolean
|
||||
readonly node: number
|
||||
}
|
||||
|
||||
/** A reachable TypeScript type that cannot be represented as a persisted JSON type. */
|
||||
export class PersistenceSchemaError extends Error {
|
||||
override name = 'PersistenceSchemaError'
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract every repository event, its complete envelope, and the Session header.
|
||||
* @param root - repository root, with source paths in tsconfig.host.json.
|
||||
* @returns canonical root fingerprints and all reachable type definitions.
|
||||
*/
|
||||
export function extractPersistenceSchema(root: string): PersistenceSchemaInventory {
|
||||
root = resolve(root)
|
||||
const events = collectLogEvents(root).sort((left, right) => compare(left.name, right.name))
|
||||
if (events.length === 0) throw new PersistenceSchemaError('persistence schema: no Session events were discovered')
|
||||
const filename = resolve(root, 'scripts/__persistence_schema_roots__.ts')
|
||||
const source = [
|
||||
"import type { SessionHeader, SessionEvent, SessionEventMap, SurfaceEventType } from '@deepseek-ai/dsh-session/types'",
|
||||
'export type HeaderRoot = SessionHeader',
|
||||
'export type SurfaceRoot = SurfaceEventType',
|
||||
'export type EventNamesRoot = keyof SessionEventMap',
|
||||
...events.map((event, index) => `export type EventRoot${String(index)} = SessionEvent<${JSON.stringify(event.name)}>`),
|
||||
'',
|
||||
].join('\n')
|
||||
const configPath = resolve(root, 'tsconfig.host.json')
|
||||
const config = ts.readConfigFile(configPath, file => readFileSync(file, 'utf8'))
|
||||
if (config.error !== undefined) throw new PersistenceSchemaError(diagnosticText(config.error))
|
||||
const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, root)
|
||||
const configErrors = parsed.errors.filter(error => error.code !== 18003)
|
||||
if (configErrors.length > 0) throw new PersistenceSchemaError(configErrors.map(diagnosticText).join('\n'))
|
||||
const options: ts.CompilerOptions = {
|
||||
...parsed.options,
|
||||
composite: false,
|
||||
incremental: false,
|
||||
noEmit: true,
|
||||
rootDir: root,
|
||||
noUnusedLocals: false,
|
||||
noUnusedParameters: false,
|
||||
// Reachable declaration-file errors must not become opaque any values.
|
||||
skipLibCheck: false,
|
||||
strict: true,
|
||||
exactOptionalPropertyTypes: true,
|
||||
}
|
||||
const host = ts.createCompilerHost(options)
|
||||
const originalGetSourceFile = host.getSourceFile.bind(host)
|
||||
host.getSourceFile = (path, languageVersion, onError, shouldCreateNewSourceFile) =>
|
||||
resolve(path) === filename
|
||||
? ts.createSourceFile(filename, source, languageVersion, true)
|
||||
: originalGetSourceFile(path, languageVersion, onError, shouldCreateNewSourceFile)
|
||||
const files = [...new Set([
|
||||
...hostSourceFiles(root, configPath),
|
||||
...events.map(event => resolve(root, event.source.slice(0, event.source.lastIndexOf(':')))),
|
||||
])]
|
||||
const program = ts.createProgram({ rootNames: [filename, ...files], options, host })
|
||||
const rootSource = program.getSourceFile(filename)
|
||||
if (rootSource === undefined) throw new PersistenceSchemaError('persistence schema: compiler omitted the requested roots')
|
||||
const diagnostics = [
|
||||
...program.getOptionsDiagnostics(), ...program.getSyntacticDiagnostics(), ...program.getSemanticDiagnostics(rootSource),
|
||||
]
|
||||
if (diagnostics.length > 0) throw new PersistenceSchemaError(diagnostics.map(diagnosticText).join('\n'))
|
||||
const checker = program.getTypeChecker()
|
||||
const declarations = new Map(rootSource.statements.filter(ts.isTypeAliasDeclaration)
|
||||
.map(declaration => [declaration.name.text, declaration]))
|
||||
const declaration = (name: string): ts.TypeAliasDeclaration => {
|
||||
const found = declarations.get(name)
|
||||
if (found === undefined) throw new PersistenceSchemaError(`persistence schema: missing compiler root ${name}`)
|
||||
return found
|
||||
}
|
||||
const eventNamesDeclaration = declaration('EventNamesRoot')
|
||||
const compiledEvents = stringLiterals(checker.getTypeFromTypeNode(eventNamesDeclaration.type), 'keyof SessionEventMap')
|
||||
const discoveredEvents = new Set(events.map(event => event.name))
|
||||
const omitted = [...compiledEvents].filter(name => !discoveredEvents.has(name))
|
||||
const uncompiled = [...discoveredEvents].filter(name => !compiledEvents.has(name))
|
||||
if (omitted.length > 0 || uncompiled.length > 0) {
|
||||
throw new PersistenceSchemaError(`persistence schema: compiler and source event discovery disagree; omitted: ${omitted.join(', ')}; uncompiled: ${uncompiled.join(', ')}`)
|
||||
}
|
||||
const surfaceDeclaration = declaration('SurfaceRoot')
|
||||
const surface = stringLiterals(checker.getTypeFromTypeNode(surfaceDeclaration.type), 'SurfaceEventType')
|
||||
for (const name of surface) {
|
||||
if (!events.some(event => event.name === name)) throw new PersistenceSchemaError(`persistence schema: surface event ${name} has no declaration`)
|
||||
}
|
||||
const header = declaration('HeaderRoot')
|
||||
const physicalFile = resolve(root, 'packages/session/session-persistence-jsonl/src/format.ts')
|
||||
const physical = program.getSourceFile(physicalFile)?.statements
|
||||
.filter((node): node is ts.InterfaceDeclaration | ts.TypeAliasDeclaration =>
|
||||
ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node))
|
||||
.filter(declaration => declaration.name.text === 'HeaderLine')
|
||||
if (physical?.length !== 1) throw new PersistenceSchemaError('persistence schema: expected one current JSONL HeaderLine declaration')
|
||||
const physicalHeader = physical[0] as ts.InterfaceDeclaration | ts.TypeAliasDeclaration
|
||||
const declarationSources = validateReachableDeclarations(program, root, [...declarations.values(), physicalHeader])
|
||||
const extraction = new SchemaExtractor(root, program, declarationSources)
|
||||
const roots: RootInput[] = [{
|
||||
key: 'SessionHeader',
|
||||
kind: 'header',
|
||||
node: extraction.convert(checker.getTypeFromTypeNode(header.type), header),
|
||||
}]
|
||||
roots.push({ key: 'JsonlHeaderLine', kind: 'header', node: extraction.convert(checker.getTypeAtLocation(physicalHeader), physicalHeader) })
|
||||
const envelopes: number[] = []
|
||||
for (const [index, event] of events.entries()) {
|
||||
const item = declaration(`EventRoot${String(index)}`)
|
||||
const node = extraction.convert(checker.getTypeFromTypeNode(item.type), item)
|
||||
roots.push({ key: `event:${event.name}`, kind: 'event', event: event.name, surface: surface.has(event.name), node })
|
||||
envelopes.push(extraction.envelope(node, event.name))
|
||||
}
|
||||
roots.splice(2, 0, { key: 'SessionEventEnvelope', kind: 'envelope', node: extraction.union(envelopes) })
|
||||
return extraction.inventory(roots)
|
||||
}
|
||||
|
||||
function hostSourceFiles(root: string, configPath: string, seen = new Set<string>()): string[] {
|
||||
configPath = resolve(configPath)
|
||||
if (seen.has(configPath)) return []
|
||||
seen.add(configPath)
|
||||
const read = ts.readConfigFile(configPath, file => readFileSync(file, 'utf8'))
|
||||
if (read.error !== undefined) throw new PersistenceSchemaError(diagnosticText(read.error))
|
||||
const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(configPath), undefined, configPath)
|
||||
const errors = parsed.errors.filter(error => error.code !== 18003)
|
||||
if (errors.length > 0) throw new PersistenceSchemaError(errors.map(diagnosticText).join('\n'))
|
||||
return [
|
||||
...parsed.fileNames.filter(file => /^packages\/[^/]+\/[^/]+\/src\//.test(slash(relative(root, file)))),
|
||||
...(parsed.projectReferences ?? []).flatMap(reference =>
|
||||
hostSourceFiles(root, extname(reference.path) === '.json' ? reference.path : resolve(reference.path, 'tsconfig.json'), seen)),
|
||||
]
|
||||
}
|
||||
|
||||
function validateReachableDeclarations(
|
||||
program: ts.Program,
|
||||
root: string,
|
||||
roots: readonly ts.Node[],
|
||||
): ReadonlyMap<ts.Type, readonly ts.Node[]> {
|
||||
const checker = program.getTypeChecker()
|
||||
const visited = new Set<ts.Node>()
|
||||
const declarations = new Map<ts.SourceFile, ts.Node[]>()
|
||||
const definitions = new Map<ts.Type, ts.Node[]>()
|
||||
const visit = (node: ts.Node): void => {
|
||||
if (visited.has(node)) return
|
||||
visited.add(node)
|
||||
const file = node.getSourceFile()
|
||||
if (trackedSource(slash(relative(root, file.fileName)))) {
|
||||
const scopes = declarations.get(file) ?? []
|
||||
scopes.push(node)
|
||||
declarations.set(file, scopes)
|
||||
if (isNamedTypeDeclaration(node) || ts.isTypeLiteralNode(node)) {
|
||||
// Primitive aliases share checker types with unaliased properties.
|
||||
const type = checker.getTypeAtLocation(node)
|
||||
const entries = definitions.get(type) ?? []
|
||||
entries.push(node)
|
||||
definitions.set(type, entries)
|
||||
}
|
||||
}
|
||||
const target = ts.isTypeReferenceNode(node) ? node.typeName
|
||||
: ts.isExpressionWithTypeArguments(node) ? node.expression
|
||||
: ts.isTypeQueryNode(node) ? node.exprName
|
||||
: ts.isImportTypeNode(node) ? node.qualifier
|
||||
: undefined
|
||||
if (target !== undefined) {
|
||||
let symbol = checker.getSymbolAtLocation(target)
|
||||
if (symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias)) symbol = checker.getAliasedSymbol(symbol)
|
||||
for (const declaration of symbol?.declarations ?? []) {
|
||||
if (trackedSource(slash(relative(root, declaration.getSourceFile().fileName)))) visit(declaration)
|
||||
}
|
||||
}
|
||||
if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) return
|
||||
ts.forEachChild(node, visit)
|
||||
}
|
||||
for (const root of roots) visit(root)
|
||||
const errors = [...declarations].flatMap(([file, scopes]) => program.getSemanticDiagnostics(file)
|
||||
.filter((error) => {
|
||||
const start = error.start
|
||||
return start !== undefined && scopes.some(scope => start >= scope.getStart() && start < scope.end)
|
||||
}))
|
||||
if (errors.length > 0) throw new PersistenceSchemaError(errors.map(diagnosticText).join('\n'))
|
||||
return definitions
|
||||
}
|
||||
|
||||
class SchemaExtractor {
|
||||
readonly nodes: SchemaNode[] = []
|
||||
private readonly cache = new Map<ts.Type, number>()
|
||||
private readonly declarationMetadata = new Map<number, DeclarationMetadata>()
|
||||
|
||||
private readonly checker: ts.TypeChecker
|
||||
|
||||
constructor(
|
||||
private readonly root: string,
|
||||
program: ts.Program,
|
||||
private readonly declarationSources: ReadonlyMap<ts.Type, readonly ts.Node[]>,
|
||||
) {
|
||||
this.checker = program.getTypeChecker()
|
||||
}
|
||||
|
||||
convert(type: ts.Type, site: ts.Node): number {
|
||||
const cached = this.cache.get(type)
|
||||
if (cached !== undefined) {
|
||||
this.record(cached, type)
|
||||
return cached
|
||||
}
|
||||
const id = this.nodes.length
|
||||
this.nodes.push({ kind: 'primitive', type: 'never' })
|
||||
this.cache.set(type, id)
|
||||
this.record(id, type)
|
||||
const add = (node: SchemaNode): number => { this.nodes[id] = node; return id }
|
||||
const flags = type.flags
|
||||
if (flags & ts.TypeFlags.Any) {
|
||||
if ((type as ts.Type & { intrinsicName?: string }).intrinsicName === 'error') this.fail(type, site, 'unresolved compiler type')
|
||||
return add({ kind: 'opaque', reason: 'any' })
|
||||
}
|
||||
if (flags & ts.TypeFlags.Unknown) return add({ kind: 'opaque', reason: 'unknown' })
|
||||
if (flags & ts.TypeFlags.Never) return add({ kind: 'primitive', type: 'never' })
|
||||
if (flags & ts.TypeFlags.Null) return add({ kind: 'primitive', type: 'null' })
|
||||
if (flags & ts.TypeFlags.String) return add({ kind: 'primitive', type: 'string' })
|
||||
if (flags & ts.TypeFlags.Number) return add({ kind: 'primitive', type: 'number' })
|
||||
if (flags & ts.TypeFlags.Boolean) return add({ kind: 'primitive', type: 'boolean' })
|
||||
if (flags & ts.TypeFlags.StringLiteral) return add({ kind: 'literal', value: (type as ts.StringLiteralType).value })
|
||||
if (flags & ts.TypeFlags.NumberLiteral) return add({ kind: 'literal', value: (type as ts.NumberLiteralType).value })
|
||||
if (flags & ts.TypeFlags.BooleanLiteral) return add({ kind: 'literal', value: this.checker.typeToString(type) === 'true' })
|
||||
if (type.isUnion()) return add(this.unionNode(type.types.map(member => this.convert(member, site))))
|
||||
if (type.isIntersection()) {
|
||||
const material = type.types.filter(member => !this.phantom(member))
|
||||
for (const member of material) this.rejectClass(member, site)
|
||||
if (material.length === 1) {
|
||||
const target = this.convert(material[0] as ts.Type, site)
|
||||
return add({ kind: 'union', types: [target] })
|
||||
}
|
||||
if (material.length === 0 || material.some(member => (member.flags & ts.TypeFlags.Object) === 0)) {
|
||||
this.fail(type, site, 'unsupported material intersection')
|
||||
}
|
||||
return add(this.object(type, site))
|
||||
}
|
||||
if (this.checker.isTupleType(type)) {
|
||||
const reference = type as ts.TypeReference
|
||||
const target = reference.target as ts.TupleType
|
||||
return add({
|
||||
kind: 'tuple',
|
||||
elements: this.checker.getTypeArguments(reference).map((element, index) => {
|
||||
const flags = target.elementFlags[index] ?? ts.ElementFlags.Required
|
||||
const optional = (flags & ts.ElementFlags.Optional) !== 0
|
||||
const rest = (flags & (ts.ElementFlags.Rest | ts.ElementFlags.Variadic)) !== 0
|
||||
return { type: this.valueType(element, site, optional), optional, rest }
|
||||
}),
|
||||
})
|
||||
}
|
||||
if (this.checker.isArrayType(type) || this.checker.isArrayLikeType(type)) {
|
||||
const element = this.checker.getIndexTypeOfType(type, ts.IndexKind.Number)
|
||||
if (element === undefined) this.fail(type, site, 'array element is unavailable')
|
||||
return add({ kind: 'array', element: this.convert(element, site) })
|
||||
}
|
||||
if (flags & ts.TypeFlags.Object) return add(this.object(type, site))
|
||||
this.fail(type, site, 'type has no supported JSON representation')
|
||||
}
|
||||
|
||||
private valueType(type: ts.Type, site: ts.Node, optional: boolean): number {
|
||||
if (!optional) return this.convert(type, site)
|
||||
const members = (type.isUnion() ? type.types : [type]).filter(member => !(member.flags & ts.TypeFlags.Undefined))
|
||||
return this.union(members.map(member => this.convert(member, site)))
|
||||
}
|
||||
|
||||
private object(type: ts.Type, site: ts.Node): SchemaNode {
|
||||
this.rejectClass(type, site)
|
||||
if (type.getCallSignatures().length > 0 || type.getConstructSignatures().length > 0) this.fail(type, site, 'callable data is not JSON')
|
||||
const properties: SchemaProperty[] = []
|
||||
for (const property of this.checker.getPropertiesOfType(type).sort((left, right) => compare(left.name, right.name))) {
|
||||
if (property.getName().startsWith('__@')) this.fail(type, site, 'symbol-keyed data is not a JSON field')
|
||||
const declaration = property.valueDeclaration ?? property.declarations?.[0] ?? site
|
||||
const propertyType = this.checker.getTypeOfSymbolAtLocation(property, declaration)
|
||||
const optional = (property.flags & ts.SymbolFlags.Optional) !== 0
|
||||
if (optional && (propertyType.isUnion() ? propertyType.types : [propertyType])
|
||||
.every(member => (member.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Never)) !== 0)) continue
|
||||
const child = this.valueType(propertyType, declaration, optional)
|
||||
properties.push({ name: property.getName(), type: child, optional })
|
||||
}
|
||||
const indices = this.checker.getIndexInfosOfType(type).map(info => ({
|
||||
key: this.convert(info.keyType, site),
|
||||
value: this.convert(info.type, site),
|
||||
}))
|
||||
if (properties.length === 0 && indices.length === 0) this.fail(type, site, 'unconstrained empty object type is not an explicit JSON record')
|
||||
return { kind: 'object', properties, indices }
|
||||
}
|
||||
|
||||
private rejectClass(type: ts.Type, site: ts.Node): void {
|
||||
const symbol = type.getSymbol()
|
||||
if (symbol?.declarations?.some(declaration => ts.isClassDeclaration(declaration) || ts.isClassExpression(declaration))) {
|
||||
this.fail(type, site, 'class instances require an explicit persisted representation')
|
||||
}
|
||||
}
|
||||
|
||||
private phantom(type: ts.Type): boolean {
|
||||
if (!(type.flags & ts.TypeFlags.Object)) return false
|
||||
const properties = this.checker.getPropertiesOfType(type)
|
||||
return properties.length > 0 && properties.every(property => property.getName().startsWith('__@'))
|
||||
&& type.getCallSignatures().length === 0 && type.getConstructSignatures().length === 0
|
||||
&& this.checker.getIndexInfosOfType(type).length === 0
|
||||
}
|
||||
|
||||
union(types: readonly number[]): number {
|
||||
const node = this.unionNode(types)
|
||||
if (node.kind === 'union' && node.types.length === 1) return node.types[0] as number
|
||||
this.nodes.push(node)
|
||||
return this.nodes.length - 1
|
||||
}
|
||||
|
||||
private unionNode(types: readonly number[]): SchemaNode {
|
||||
if (types.length === 0) return { kind: 'primitive', type: 'never' }
|
||||
return { kind: 'union', types: [...new Set(types)] }
|
||||
}
|
||||
|
||||
envelope(id: number, event: string): number {
|
||||
const node = this.nodes[id] as SchemaNode
|
||||
if (node.kind === 'union') return this.union(node.types.map(type => this.envelope(type, event)))
|
||||
if (node.kind !== 'object') throw new PersistenceSchemaError('persistence schema: SessionEvent must resolve to object alternatives')
|
||||
const tag = node.properties.find(property => property.name === 'type')
|
||||
const data = node.properties.find(property => property.name === 'data')
|
||||
const literal = tag === undefined ? undefined : canonicalizeSchema(this.nodes, tag.type).nodes[0]
|
||||
if (tag?.optional !== false || data?.optional !== false || literal?.kind !== 'literal' || literal.value !== event) {
|
||||
throw new PersistenceSchemaError(`persistence schema: SessionEvent<${JSON.stringify(event)}> must retain its required type and data fields`)
|
||||
}
|
||||
const string = this.nodes.length
|
||||
this.nodes.push({ kind: 'primitive', type: 'string' })
|
||||
const envelope: SchemaNode = {
|
||||
kind: 'object',
|
||||
properties: node.properties.filter(property => property.name !== 'data')
|
||||
.map(property => property.name === 'type' ? { ...property, type: string } : property),
|
||||
indices: node.indices,
|
||||
}
|
||||
this.nodes.push(envelope)
|
||||
return this.nodes.length - 1
|
||||
}
|
||||
|
||||
inventory(inputs: readonly RootInput[]): PersistenceSchemaInventory {
|
||||
const roots = inputs.map((input) => {
|
||||
const schema = canonicalizeSchema(this.nodes, input.node)
|
||||
return {
|
||||
key: input.key,
|
||||
kind: input.kind,
|
||||
...(input.event === undefined ? {} : { event: input.event }),
|
||||
...(input.surface === undefined ? {} : { surface: input.surface }),
|
||||
digest: schemaDigest(schema),
|
||||
schema,
|
||||
}
|
||||
})
|
||||
const found = new Set<number>()
|
||||
const paths = new Map<number, Set<string>>()
|
||||
const visit = (id: number, path: string): void => {
|
||||
const names = paths.get(id) ?? new Set<string>()
|
||||
names.add(path)
|
||||
paths.set(id, names)
|
||||
if (found.has(id)) return
|
||||
found.add(id)
|
||||
const node = this.nodes[id] as SchemaNode
|
||||
if (node.kind === 'object') {
|
||||
for (const property of node.properties) visit(property.type, `${path}.${property.name}`)
|
||||
for (const index of node.indices) { visit(index.key, `${path}.[key]`); visit(index.value, `${path}.[value]`) }
|
||||
} else {
|
||||
for (const [index, child] of schemaChildren(node).entries()) visit(child, `${path}[${String(index)}]`)
|
||||
}
|
||||
}
|
||||
for (const input of inputs) visit(input.node, input.key)
|
||||
const types = new Map<string, { schema: PersistenceType['schema']; names: Set<string>; sources: Set<string> }>()
|
||||
for (const id of found) {
|
||||
const schema = canonicalizeSchema(this.nodes, id)
|
||||
const digest = schemaDigest(schema)
|
||||
const item = types.get(digest) ?? { schema, names: new Set<string>(), sources: new Set<string>() }
|
||||
const declarationMetadata = this.declarationMetadata.get(id)
|
||||
for (const name of declarationMetadata?.names ?? []) item.names.add(name)
|
||||
for (const source of declarationMetadata?.sources ?? []) item.sources.add(source)
|
||||
const kind = schema.nodes[0]?.kind
|
||||
if (kind !== 'primitive' && kind !== 'literal' && (declarationMetadata === undefined || declarationMetadata.names.size === 0)) {
|
||||
for (const path of paths.get(id) ?? []) item.names.add(path)
|
||||
}
|
||||
types.set(digest, item)
|
||||
}
|
||||
return {
|
||||
formatVersion: 1,
|
||||
roots,
|
||||
types: [...types].sort(([left], [right]) => compare(left, right)).map(([digest, item]) => ({
|
||||
digest,
|
||||
schema: item.schema,
|
||||
names: [...item.names].sort(compare),
|
||||
sources: [...item.sources].sort(compare),
|
||||
})),
|
||||
}
|
||||
}
|
||||
|
||||
private record(id: number, type: ts.Type): void {
|
||||
const item = this.declarationMetadata.get(id) ?? { names: new Set<string>(), sources: new Set<string>() }
|
||||
const declarations = new Set([
|
||||
...this.declarationSources.get(type) ?? [],
|
||||
...type.aliasSymbol?.declarations ?? [],
|
||||
...type.getSymbol()?.declarations ?? [],
|
||||
])
|
||||
for (const declaration of declarations) {
|
||||
if (!isNamedTypeDeclaration(declaration) && !ts.isTypeLiteralNode(declaration) && !ts.isEnumMember(declaration)) continue
|
||||
const source = declaration.getSourceFile()
|
||||
const file = slash(relative(this.root, source.fileName))
|
||||
if (!trackedSource(file)) continue
|
||||
if (isNamedTypeDeclaration(declaration)) item.names.add(`${file}#${declaration.name.text}`)
|
||||
const position = source.getLineAndCharacterOfPosition(declaration.getStart())
|
||||
item.sources.add(`${file}:${String(position.line + 1)}`)
|
||||
}
|
||||
this.declarationMetadata.set(id, item)
|
||||
}
|
||||
|
||||
private fail(type: ts.Type, site: ts.Node, reason: string): never {
|
||||
const source = slash(relative(this.root, site.getSourceFile().fileName))
|
||||
const position = site.getSourceFile().getLineAndCharacterOfPosition(site.getStart())
|
||||
throw new PersistenceSchemaError(`persistence schema: ${source}:${String(position.line + 1)}: ${reason}: ${this.checker.typeToString(type)}`)
|
||||
}
|
||||
}
|
||||
|
||||
function isNamedTypeDeclaration(node: ts.Node): node is ts.TypeAliasDeclaration | ts.InterfaceDeclaration | ts.EnumDeclaration {
|
||||
return ts.isTypeAliasDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isEnumDeclaration(node)
|
||||
}
|
||||
|
||||
function stringLiterals(type: ts.Type, name: string): Set<string> {
|
||||
if (type.flags & ts.TypeFlags.Never) return new Set()
|
||||
const members = type.isUnion() ? type.types : [type]
|
||||
if (members.some(member => !(member.flags & ts.TypeFlags.StringLiteral))) throw new PersistenceSchemaError(`persistence schema: ${name} is not a closed string-literal union`)
|
||||
return new Set(members.map(member => (member as ts.StringLiteralType).value))
|
||||
}
|
||||
|
||||
function diagnosticText(diagnostic: ts.Diagnostic): string {
|
||||
return `persistence schema: TypeScript TS${String(diagnostic.code)}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')}`
|
||||
}
|
||||
|
||||
function compare(left: string, right: string): number {
|
||||
return left < right ? -1 : left > right ? 1 : 0
|
||||
}
|
||||
|
||||
function slash(path: string): string {
|
||||
return path.split(sep).join('/')
|
||||
}
|
||||
|
||||
function trackedSource(file: string): boolean {
|
||||
return (file.startsWith('packages/') || file.startsWith('vendor/')) && !file.includes('/node_modules/')
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
/** Stable source-file metadata for saved persistence inventories. */
|
||||
|
||||
import type { PersistenceSchemaInventory } from './persistence-schema-model.ts'
|
||||
|
||||
/**
|
||||
* Remove source line positions without changing schemas, names, or fingerprints.
|
||||
* @param inventory - validated inventory whose source metadata will be copied.
|
||||
* @returns an inventory with unique source paths in their original order.
|
||||
*/
|
||||
export function withoutPersistenceSourceLines(inventory: PersistenceSchemaInventory): PersistenceSchemaInventory {
|
||||
return {
|
||||
...inventory,
|
||||
types: inventory.types.map(type => ({
|
||||
...type,
|
||||
sources: [...new Set(type.sources.map(source => source.replace(/(?::\d+(?::\d+)?|#L\d+(?:-L\d+)?)$/u, '')))],
|
||||
})),
|
||||
}
|
||||
}
|
||||
@@ -566,13 +566,13 @@ describe('sidebar ordering', () => {
|
||||
|
||||
describe('addProjectionFrontmatter', () => {
|
||||
it('adds frontmatter to an ordinary Markdown page', () => {
|
||||
expect(addProjectionFrontmatter('# Guide\n', { source: 'docs/guide.md' })).toBe(
|
||||
'---\neditSource: "docs/guide.md"\n---\n\n# Guide\n',
|
||||
expect(addProjectionFrontmatter('# Guide\n', { source: 'docs/guide.md', route: 'en/guide.md', sidebar: 'en-guide' })).toBe(
|
||||
'---\neditSource: "docs/guide.md"\nrawMarkdownPath: "en/guide.md"\n---\n\n# Guide\n',
|
||||
)
|
||||
})
|
||||
|
||||
it('extends existing VitePress frontmatter', () => {
|
||||
expect(addProjectionFrontmatter('---\nlayout: home\n---\n', { source: 'docs/index.md' })).toBe(
|
||||
expect(addProjectionFrontmatter('---\nlayout: home\n---\n', { source: 'docs/index.md', route: 'index.md', sidebar: null })).toBe(
|
||||
'---\neditSource: "docs/index.md"\nlayout: home\n---\n',
|
||||
)
|
||||
})
|
||||
@@ -580,9 +580,11 @@ describe('addProjectionFrontmatter', () => {
|
||||
it('adds the page-specific outline depth from the publication manifest', () => {
|
||||
expect(addProjectionFrontmatter('# Catalog\n', {
|
||||
source: 'docs/catalog.md',
|
||||
route: 'reference/index.md',
|
||||
sidebar: 'zh-reference',
|
||||
outline: [2, 4],
|
||||
})).toBe(
|
||||
'---\neditSource: "docs/catalog.md"\noutline: [2,4]\n---\n\n# Catalog\n',
|
||||
'---\neditSource: "docs/catalog.md"\nrawMarkdownPath: "reference/index.md"\noutline: [2,4]\n---\n\n# Catalog\n',
|
||||
)
|
||||
})
|
||||
})
|
||||
@@ -673,9 +675,9 @@ describe('emitRawMarkdownPages', () => {
|
||||
// The real path, because image placement proves containment via realpath.
|
||||
emitRawMarkdownPages(out, { pages, repoRoot: realpathSync(root), repositoryRef: 'abc123' })
|
||||
|
||||
expect(readFileSync(join(out, 'a.md'), 'utf8')).toBe('[B](./reference-root/b.md) \n')
|
||||
expect(readFileSync(join(out, 'en/a.md'), 'utf8')).toBe('[B](./reference/b.md) \n')
|
||||
expect(readFileSync(join(out, 'reference-root/b.md'), 'utf8')).toBe('# B\n')
|
||||
expect(readFileSync(join(out, 'a.md'), 'utf8')).toBe('\uFEFF[B](./reference-root/b.md) \n')
|
||||
expect(readFileSync(join(out, 'en/a.md'), 'utf8')).toBe('\uFEFF[B](./reference/b.md) \n')
|
||||
expect(readFileSync(join(out, 'reference-root/b.md'), 'utf8')).toBe('\uFEFF# B\n')
|
||||
expect(existsSync(join(out, 'logo.svg'))).toBe(true)
|
||||
expect(existsSync(join(out, 'en/logo.svg'))).toBe(true)
|
||||
})
|
||||
@@ -691,7 +693,7 @@ describe('emitRawMarkdownPages', () => {
|
||||
|
||||
emitRawMarkdownPages(out, { pages, repoRoot: root, repositoryRef: 'abc123' })
|
||||
|
||||
expect(readFileSync(join(out, 'index.md'), 'utf8')).toBe('# Home\n\n[A](./a.md)\n')
|
||||
expect(readFileSync(join(out, 'index.md'), 'utf8')).toBe('\uFEFF# Home\n\n[A](./a.md)\n')
|
||||
})
|
||||
|
||||
it('emits a parent-level alias for an index route with links recomputed', () => {
|
||||
@@ -707,8 +709,20 @@ describe('emitRawMarkdownPages', () => {
|
||||
|
||||
emitRawMarkdownPages(out, { pages, repoRoot: root, repositoryRef: 'abc123' })
|
||||
|
||||
expect(readFileSync(join(out, 'guide/index.md'), 'utf8')).toBe('# C\n\n[A](../a.md)\n')
|
||||
expect(readFileSync(join(out, 'guide.md'), 'utf8')).toBe('# C\n\n[A](./a.md)\n')
|
||||
expect(readFileSync(join(out, 'guide/index.md'), 'utf8')).toBe('\uFEFF# C\n\n[A](../a.md)\n')
|
||||
expect(readFileSync(join(out, 'guide.md'), 'utf8')).toBe('\uFEFF# C\n\n[A](./a.md)\n')
|
||||
})
|
||||
|
||||
it('identifies UTF-8 to document readers while fetch decoding preserves the Markdown body', async () => {
|
||||
const { root, pages } = fixture()
|
||||
const markdown = '# 中文 → Markdown\n'
|
||||
writeFileSync(join(root, 'docs/a.md'), markdown)
|
||||
const out = mirrorDir()
|
||||
emitRawMarkdownPages(out, { pages, repoRoot: root, repositoryRef: 'abc123' })
|
||||
const bytes = readFileSync(join(out, 'a.md'))
|
||||
expect([...bytes.subarray(0, 3)]).toEqual([0xef, 0xbb, 0xbf])
|
||||
expect(await new Response(bytes).text()).toBe(markdown)
|
||||
expect(fromMarkdown(bytes.toString('utf8')).children[0]?.type).toBe('heading')
|
||||
})
|
||||
|
||||
it('refuses to overwrite a file the build already carries', () => {
|
||||
@@ -762,7 +776,7 @@ describe('raw Markdown projection of the published manifest', () => {
|
||||
|
||||
it('emits home pages with their bodies instead of the frontmatter stub', () => {
|
||||
for (const route of ['index.md', 'en/index.md']) {
|
||||
const home = readFileSync(join(mirror, route), 'utf8')
|
||||
const home = new TextDecoder().decode(readFileSync(join(mirror, route)))
|
||||
expect(home.startsWith('---'), route).toBe(false)
|
||||
expect(home, route).toContain('# DeepSeek Harness')
|
||||
}
|
||||
|
||||
@@ -202,15 +202,16 @@ export function rewriteMarkdown(source: string, options: RewriteMarkdownOptions)
|
||||
}
|
||||
|
||||
/**
|
||||
* Record the canonical edit target in VitePress frontmatter.
|
||||
* Record canonical edit and raw-Markdown targets in VitePress frontmatter.
|
||||
*
|
||||
* @param markdown Projected Markdown content.
|
||||
* @param page Publication manifest entry for the content.
|
||||
* @returns Markdown with projection-owned frontmatter fields.
|
||||
*/
|
||||
export function addProjectionFrontmatter(markdown: string, page: Pick<DocsPage, 'source' | 'outline'>): string {
|
||||
export function addProjectionFrontmatter(markdown: string, page: Pick<DocsPage, 'source' | 'outline' | 'route' | 'sidebar'>): string {
|
||||
const fields = [
|
||||
`editSource: ${JSON.stringify(page.source)}`,
|
||||
...(page.sidebar === null ? [] : [`rawMarkdownPath: ${JSON.stringify(page.route)}`]),
|
||||
...(page.outline === undefined ? [] : [`outline: ${JSON.stringify(page.outline)}`]),
|
||||
].join('\n')
|
||||
if (markdown.startsWith('---\n')) return markdown.replace('---\n', `---\n${fields}\n`)
|
||||
@@ -486,7 +487,8 @@ export function rawMarkdownFiles(pages: DocsPage[] = docsPages): string[] {
|
||||
* projected over the alias route so its relative links stay correct.
|
||||
* Referenced images are copied beside the pages, keeping the same relative
|
||||
* URLs valid in both trees. Existing build files stay in place, and a name
|
||||
* collision with one fails the emission.
|
||||
* collision with one fails the emission. Markdown files carry a UTF-8 BOM so
|
||||
* browser navigation decodes them even when static hosting omits a charset.
|
||||
*
|
||||
* @param outDir Build output directory to emit into.
|
||||
* @param context Manifest and repository inputs, defaulting to this repository.
|
||||
@@ -499,7 +501,7 @@ export function emitRawMarkdownPages(outDir: string, context: ProjectionContext
|
||||
projectPagesInto(
|
||||
outDir,
|
||||
context,
|
||||
(markdown, page) => rawMarkdownPageContent(markdown, page.source),
|
||||
(markdown, page) => `\uFEFF${rawMarkdownPageContent(markdown, page.source)}`,
|
||||
[...context.pages, ...aliases],
|
||||
)
|
||||
}
|
||||
|
||||
@@ -4,7 +4,6 @@ import { spawnSync, type SpawnSyncReturns } from 'node:child_process'
|
||||
import { createHash } from 'node:crypto'
|
||||
import {
|
||||
existsSync,
|
||||
globSync,
|
||||
mkdirSync,
|
||||
mkdtempSync,
|
||||
readFileSync,
|
||||
@@ -18,17 +17,11 @@ import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep
|
||||
import { createInterface } from 'node:readline/promises'
|
||||
import { pathToFileURL } from 'node:url'
|
||||
import { parseArgs } from 'node:util'
|
||||
import { PUBLIC_EXPERIMENTAL_PACKAGE_DIRECTORIES } from './experimental-package-policy.ts'
|
||||
import { discoverNpmBaselineManifests } from './npm-baseline-packages.ts'
|
||||
import { validateTarballPayload } from './publication-payload.ts'
|
||||
|
||||
const DEFAULT_REGISTRY = 'https://registry.npm.harnessment.com'
|
||||
const DEFAULT_OUTPUT_DIRECTORY = '.artifacts/npm-baseline'
|
||||
const PACKAGE_PATTERNS = [
|
||||
'vendor/*/package.json',
|
||||
'packages/!(experimental)/*/package.json',
|
||||
'apps/*/package.json',
|
||||
...PUBLIC_EXPERIMENTAL_PACKAGE_DIRECTORIES.map(directory => `${directory}/package.json`),
|
||||
] as const
|
||||
const DEPENDENCY_SECTIONS = [
|
||||
'dependencies',
|
||||
'devDependencies',
|
||||
@@ -244,7 +237,7 @@ class WorkspacePackageSet {
|
||||
) {}
|
||||
|
||||
static discover(root: string): WorkspacePackageSet {
|
||||
const manifestPaths = globSync(PACKAGE_PATTERNS, { cwd: root }).sort()
|
||||
const manifestPaths = discoverNpmBaselineManifests(root)
|
||||
if (manifestPaths.length === 0) {
|
||||
throw new Error('no package manifests found under vendor/, packages/, or apps/')
|
||||
}
|
||||
|
||||
@@ -42,7 +42,7 @@ afterEach(() => {
|
||||
})
|
||||
|
||||
describe('release families', () => {
|
||||
it('publishes Agent Teams while excluding private experimental packages', () => {
|
||||
it('publishes all current experimental packages', () => {
|
||||
const members = releaseFamily('dsh').members(resolve(import.meta.dirname, '../..'))
|
||||
|
||||
expect(members
|
||||
@@ -51,10 +51,20 @@ describe('release families', () => {
|
||||
'@deepseek-ai/dsh-experimental-agent-team-profile',
|
||||
'@deepseek-ai/dsh-experimental-agent-team-web-profile',
|
||||
'@deepseek-ai/dsh-experimental-agent-team',
|
||||
'@deepseek-ai/dsh-experimental-auto-review',
|
||||
'@deepseek-ai/dsh-experimental-browser-use-chrome-devtools-mcp',
|
||||
'@deepseek-ai/dsh-experimental-browser-use-playwright-mcp',
|
||||
'@deepseek-ai/dsh-experimental-browser-use-runtime',
|
||||
'@deepseek-ai/dsh-experimental-browser-use-stagehand-native',
|
||||
'@deepseek-ai/dsh-experimental-client-ui-agent-team',
|
||||
'@deepseek-ai/dsh-experimental-computer-use-cua-driver-mcp',
|
||||
'@deepseek-ai/dsh-experimental-computer-use-cua-driver-native',
|
||||
'@deepseek-ai/dsh-experimental-inspector',
|
||||
'@deepseek-ai/dsh-experimental-ptc-runtime-python',
|
||||
'@deepseek-ai/dsh-experimental-tool-agent-team',
|
||||
'@deepseek-ai/dsh-experimental-webworker-packer',
|
||||
'@deepseek-ai/dsh-experimental-webworker-runtime',
|
||||
])
|
||||
expect(members.map(member => member.name)).not.toContain('@deepseek-ai/dsh-experimental-inspector')
|
||||
})
|
||||
|
||||
it('excludes private applications from the publish set', () => {
|
||||
@@ -66,6 +76,25 @@ describe('release families', () => {
|
||||
expect(releaseFamily('dsh').members(root).map(entry => entry.name)).toEqual(['@deepseek-ai/dsh-public'])
|
||||
})
|
||||
|
||||
it('publishes unlisted experimental packages while retaining private exclusions', () => {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-release-experimental-'))
|
||||
roots.push(root)
|
||||
write(join(root, 'packages/experimental/prototype/package.json'), JSON.stringify({
|
||||
name: '@deepseek-ai/dsh-experimental-prototype',
|
||||
version: '0.0.1',
|
||||
publishConfig: { access: 'public' },
|
||||
}))
|
||||
write(join(root, 'packages/experimental/inspector/package.json'), JSON.stringify({
|
||||
name: '@deepseek-ai/dsh-experimental-inspector',
|
||||
version: '0.0.1',
|
||||
private: true,
|
||||
}))
|
||||
|
||||
expect(releaseFamily('dsh').members(root).map(entry => entry.name)).toEqual([
|
||||
'@deepseek-ai/dsh-experimental-prototype',
|
||||
])
|
||||
})
|
||||
|
||||
it('bumps private dsh workspaces without adding release tags', () => {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-release-version-'))
|
||||
roots.push(root)
|
||||
|
||||
@@ -15,7 +15,6 @@ import {
|
||||
officialClientBuildEnvironment,
|
||||
readClientBuildRecord,
|
||||
} from '../client-build-environment.ts'
|
||||
import { PUBLIC_EXPERIMENTAL_PACKAGE_DIRECTORIES } from '../experimental-package-policy.ts'
|
||||
import { validateTarballPayload } from '../publication-payload.ts'
|
||||
|
||||
/**
|
||||
@@ -323,9 +322,8 @@ export abstract class ReleaseFamily {
|
||||
class DshFamily extends ReleaseFamily {
|
||||
readonly id = 'dsh'
|
||||
readonly patterns = [
|
||||
'packages/!(experimental)/*/package.json',
|
||||
'packages/*/*/package.json',
|
||||
'apps/*/package.json',
|
||||
...PUBLIC_EXPERIMENTAL_PACKAGE_DIRECTORIES.map(directory => `${directory}/package.json`),
|
||||
] as const
|
||||
readonly tagPrefix = 'dsh-v'
|
||||
|
||||
|
||||
@@ -0,0 +1,107 @@
|
||||
/** Installed-product isolation uses resolved package identities and runtime edges. */
|
||||
|
||||
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { join } from 'node:path'
|
||||
import { afterEach, describe, expect, it } from 'vitest'
|
||||
import { verifyInstalledProductIsolation } from './installed-product-isolation.ts'
|
||||
|
||||
const roots: string[] = []
|
||||
const experimental = '@deepseek-ai/dsh-experimental-example'
|
||||
|
||||
function fixture(): string {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-installed-isolation-'))
|
||||
roots.push(root)
|
||||
return root
|
||||
}
|
||||
|
||||
function writePackage(root: string, key: string, manifest: Record<string, unknown>): string {
|
||||
const directory = join(root, 'node_modules', key)
|
||||
mkdirSync(directory, { recursive: true })
|
||||
writeFileSync(join(directory, 'package.json'), `${JSON.stringify({ name: key, ...manifest })}\n`)
|
||||
return directory
|
||||
}
|
||||
|
||||
afterEach(() => {
|
||||
for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
|
||||
})
|
||||
|
||||
describe('installed default-product isolation', () => {
|
||||
it('ignores development dependencies and unrelated installed experimental packages', () => {
|
||||
const root = fixture()
|
||||
const entry = writePackage(root, '@deepseek-ai/dsh', {
|
||||
dependencies: { core: '1.0.0' },
|
||||
devDependencies: { [experimental]: '1.0.0' },
|
||||
})
|
||||
writePackage(root, 'core', { peerDependencies: { '@deepseek-ai/dsh': '1.0.0' } })
|
||||
writePackage(root, experimental, {})
|
||||
|
||||
expect(verifyInstalledProductIsolation(entry)).toBe(2)
|
||||
})
|
||||
|
||||
it.each(['dependencies', 'optionalDependencies', 'peerDependencies'])(
|
||||
'rejects a transitive experimental %s',
|
||||
(section) => {
|
||||
const root = fixture()
|
||||
const entry = writePackage(root, '@deepseek-ai/dsh', { dependencies: { thirdParty: '1.0.0' } })
|
||||
writePackage(root, 'thirdParty', { [section]: { [experimental]: '1.0.0' } })
|
||||
|
||||
expect(() => verifyInstalledProductIsolation(entry)).toThrow(
|
||||
`@deepseek-ai/dsh -> thirdParty -> ${experimental}`,
|
||||
)
|
||||
},
|
||||
)
|
||||
|
||||
it('skips the entry package\'s optional bundles, which must be installed, and still rejects other experimental edges', () => {
|
||||
const root = fixture()
|
||||
const entry = writePackage(root, '@deepseek-ai/dsh', { dependencies: { core: '1.0.0', [experimental]: '1.0.0' } })
|
||||
writePackage(root, 'core', {})
|
||||
writePackage(root, experimental, { dependencies: { '@deepseek-ai/dsh-experimental-inner': '1.0.0' } })
|
||||
expect(verifyInstalledProductIsolation(entry, [experimental])).toBe(2)
|
||||
|
||||
writePackage(root, 'core', { dependencies: { [experimental]: '1.0.0' } })
|
||||
expect(() => verifyInstalledProductIsolation(entry, [experimental])).toThrow(`core -> ${experimental}`)
|
||||
|
||||
const missing = writePackage(root, '@deepseek-ai/dsh-missing', { dependencies: { absent: '1.0.0' } })
|
||||
expect(() => verifyInstalledProductIsolation(missing, ['absent'])).toThrow('optional bundle is missing: @deepseek-ai/dsh-missing -> absent')
|
||||
})
|
||||
|
||||
it('rejects experimental identities hidden behind an installed alias', () => {
|
||||
const root = fixture()
|
||||
const entry = writePackage(root, '@deepseek-ai/dsh', { dependencies: { safeName: 'file:../prototype' } })
|
||||
writePackage(root, 'safeName', { name: experimental })
|
||||
|
||||
expect(() => verifyInstalledProductIsolation(entry)).toThrow(experimental)
|
||||
})
|
||||
|
||||
it('rejects experimental npm aliases even when an optional package is omitted', () => {
|
||||
const root = fixture()
|
||||
const entry = writePackage(root, '@deepseek-ai/dsh', {
|
||||
optionalDependencies: { safeName: `npm:${experimental}@1.0.0` },
|
||||
})
|
||||
|
||||
expect(() => verifyInstalledProductIsolation(entry)).toThrow(experimental)
|
||||
})
|
||||
|
||||
it('follows nested installations rather than an unrelated hoisted package', () => {
|
||||
const root = fixture()
|
||||
const entry = writePackage(root, '@deepseek-ai/dsh', { dependencies: { core: '1.0.0' } })
|
||||
writePackage(root, 'core', {})
|
||||
writePackage(entry, 'core', { dependencies: { [experimental]: '1.0.0' } })
|
||||
|
||||
expect(() => verifyInstalledProductIsolation(entry)).toThrow(experimental)
|
||||
})
|
||||
|
||||
it('permits missing optional packages and optional peers but rejects missing dependencies', () => {
|
||||
const root = fixture()
|
||||
const entry = writePackage(root, '@deepseek-ai/dsh', {
|
||||
dependencies: { optional: '1.0.0' },
|
||||
optionalDependencies: { optional: '1.0.0' },
|
||||
peerDependencies: { peer: '1.0.0' },
|
||||
peerDependenciesMeta: { peer: { optional: true } },
|
||||
})
|
||||
expect(verifyInstalledProductIsolation(entry)).toBe(1)
|
||||
writePackage(root, '@deepseek-ai/dsh', { dependencies: { missing: '1.0.0' } })
|
||||
expect(() => verifyInstalledProductIsolation(entry)).toThrow('dependency is missing')
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,72 @@
|
||||
/** Experimental-package isolation for the installed default product's dependency graph. */
|
||||
|
||||
import { existsSync, readFileSync, realpathSync } from 'node:fs'
|
||||
import { createRequire } from 'node:module'
|
||||
import { join } from 'node:path'
|
||||
import { OPTIONAL_BUNDLES } from '../../packages/boot/app-boot/src/profile.ts'
|
||||
|
||||
interface InstalledManifest {
|
||||
name: string
|
||||
dependencies?: Record<string, string>
|
||||
optionalDependencies?: Record<string, string>
|
||||
peerDependencies?: Record<string, string>
|
||||
peerDependenciesMeta?: Record<string, { optional?: boolean }>
|
||||
}
|
||||
|
||||
/**
|
||||
* Reject experimental dependencies reachable from one installed product entry.
|
||||
* Other packages installed beside the entry and development dependencies do not join its graph.
|
||||
* @param directory - installed entry package directory.
|
||||
* @returns number of distinct installed packages visited.
|
||||
*/
|
||||
export function verifyInstalledProductIsolation(directory: string, optionalBundles: readonly string[] = OPTIONAL_BUNDLES): number {
|
||||
const visited = new Set<string>()
|
||||
const queue = [{ directory, chain: [] as string[] }]
|
||||
for (const item of queue) {
|
||||
const canonical = realpathSync(item.directory)
|
||||
if (visited.has(canonical)) continue
|
||||
visited.add(canonical)
|
||||
const manifest = JSON.parse(readFileSync(join(canonical, 'package.json'), 'utf8')) as InstalledManifest
|
||||
const chain = [...item.chain, manifest.name]
|
||||
rejectExperimental(manifest.name, chain)
|
||||
// The bundles the entry package ships switched off are installed beside the product, not required by it.
|
||||
const offered = item.chain.length === 0 ? new Set(optionalBundles) : new Set<string>()
|
||||
for (const section of ['dependencies', 'optionalDependencies', 'peerDependencies'] as const) {
|
||||
for (const [name, range] of Object.entries(manifest[section] ?? {})) {
|
||||
if (section === 'dependencies' && offered.has(name)) {
|
||||
if (installedPackage(canonical, name) === undefined) throw new Error(`optional bundle is missing: ${[...chain, name].join(' -> ')}`)
|
||||
continue
|
||||
}
|
||||
rejectExperimental(name, [...chain, name])
|
||||
if (range.startsWith('npm:')) {
|
||||
rejectExperimental(range.slice(4), [...chain, `${name} (${range})`])
|
||||
}
|
||||
const dependency = installedPackage(canonical, name)
|
||||
if (dependency === undefined) {
|
||||
if (section === 'optionalDependencies'
|
||||
|| Object.hasOwn(manifest.optionalDependencies ?? {}, name)
|
||||
|| section === 'peerDependencies' && manifest.peerDependenciesMeta?.[name]?.optional === true) continue
|
||||
throw new Error(`default product dependency is missing: ${[...chain, name].join(' -> ')}`)
|
||||
}
|
||||
queue.push({ directory: dependency, chain })
|
||||
}
|
||||
}
|
||||
}
|
||||
return visited.size
|
||||
}
|
||||
|
||||
function rejectExperimental(name: string, chain: readonly string[]): void {
|
||||
if (name.startsWith('@deepseek-ai/dsh-experimental-')) {
|
||||
throw new Error(`default product includes an experimental package: ${chain.join(' -> ')}`)
|
||||
}
|
||||
}
|
||||
|
||||
/** Resolve a dependency directory through the installed package's ancestor node_modules. */
|
||||
function installedPackage(from: string, name: string): string | undefined {
|
||||
const resolver = createRequire(join(from, 'package.json'))
|
||||
for (const directory of resolver.resolve.paths(name) ?? []) {
|
||||
const candidate = join(directory, name)
|
||||
if (existsSync(join(candidate, 'package.json'))) return candidate
|
||||
}
|
||||
return undefined
|
||||
}
|
||||
@@ -24,6 +24,7 @@ import { parseArgs } from 'node:util'
|
||||
import { releaseFamily } from './families.ts'
|
||||
import { capture, isEntry } from './process.ts'
|
||||
import { packedIdentity } from './tarball.ts'
|
||||
import { verifyInstalledProductIsolation } from './installed-product-isolation.ts'
|
||||
|
||||
/**
|
||||
* Environment for the installed artifact: no host Node hooks, no host DeepSeek
|
||||
@@ -107,6 +108,9 @@ function main(): void {
|
||||
capture('npm', ['install', '--no-audit', '--no-fund', '--package-lock=false', '--omit=optional', '--loglevel=http'],
|
||||
{ cwd: consumerRoot, env: environment })
|
||||
|
||||
const installedEntry = join(consumerRoot, 'node_modules', entry.packageName)
|
||||
const packageCount = verifyInstalledProductIsolation(installedEntry)
|
||||
console.log(`release verify-packed-install: ${String(packageCount)} default-product packages exclude experimental packages`)
|
||||
const bin = join(consumerRoot, 'node_modules', ...entry.packageName.split('/'), entry.binPath)
|
||||
const version = capture(process.execPath, [bin, '--version'], { cwd: consumerRoot, env: environment })
|
||||
if (version !== expected.version) {
|
||||
|
||||
@@ -0,0 +1,96 @@
|
||||
/** Linked catalog regressions for transitive changes and shared definitions. */
|
||||
|
||||
import { describe, expect, it } from 'vitest'
|
||||
import { canonicalizeSchema, schemaDigest, type PersistenceSchemaInventory, type PersistenceType, type SchemaNode } from './persistence-schema-model.ts'
|
||||
import { renderPersistenceSchemaDefinitions, renderPersistenceSchemaIndex } from './render-persistence-schema.ts'
|
||||
|
||||
function fixture(optional = true): PersistenceSchemaInventory {
|
||||
const types = new Map<string, PersistenceType>()
|
||||
const roots = ['first/event', 'second/event'].map((event) => {
|
||||
const nodes: SchemaNode[] = [
|
||||
{ kind: 'object', properties: [{ name: 'type', type: 1, optional: false }, { name: 'data', type: 2, optional: false }], indices: [] },
|
||||
{ kind: 'literal', value: event },
|
||||
{ kind: 'object', properties: [{ name: 'error', type: 3, optional: true }], indices: [] },
|
||||
{ kind: 'object', properties: [{ name: 'reason', type: 4, optional }], indices: [] },
|
||||
{ kind: 'primitive', type: 'string' },
|
||||
]
|
||||
nodes.forEach((_, index) => {
|
||||
const schema = canonicalizeSchema(nodes, index)
|
||||
const digest = schemaDigest(schema)
|
||||
if (!types.has(digest)) types.set(digest, { digest, schema, names: index === 3 ? ['ErrorInfo'] : [], sources: index === 3 ? ['packages/core/example/src/types.ts:8'] : [] })
|
||||
})
|
||||
const schema = canonicalizeSchema(nodes, 0)
|
||||
return { key: `event:${event}`, kind: 'event' as const, event, surface: false, digest: schemaDigest(schema), schema }
|
||||
})
|
||||
return { formatVersion: 1, roots, types: [...types.values()] }
|
||||
}
|
||||
|
||||
describe('persistence schema catalog', () => {
|
||||
it('shows a shared nested definition once and updates both affected root fingerprints', () => {
|
||||
const before = fixture()
|
||||
const after = fixture(false)
|
||||
const definitions = renderPersistenceSchemaDefinitions(after)
|
||||
expect(definitions.match(/### `ErrorInfo`/gu)).toHaveLength(1)
|
||||
expect(definitions).toContain('| `reason` | required | `string` |')
|
||||
expect(definitions).toContain('[`ErrorInfo`](#persistence-type-errorinfo)')
|
||||
const index = renderPersistenceSchemaIndex(after)
|
||||
for (const [position, root] of after.roots.entries()) {
|
||||
expect(root.digest).not.toBe(before.roots[position]?.digest)
|
||||
expect(index).toContain(root.digest)
|
||||
}
|
||||
})
|
||||
|
||||
it('keeps named definition anchors when their digest changes', () => {
|
||||
const before = renderPersistenceSchemaDefinitions(fixture())
|
||||
const after = renderPersistenceSchemaDefinitions(fixture(false))
|
||||
expect(before).toContain('<a id="persistence-type-errorinfo"></a>')
|
||||
expect(after).toContain('<a id="persistence-type-errorinfo"></a>')
|
||||
expect(before).not.toBe(after)
|
||||
})
|
||||
|
||||
it('renders historical source paths and nested headings within their reference section', () => {
|
||||
const current = fixture()
|
||||
const inventory = { ...current, types: current.types.map(type => ({ ...type, sources: type.sources.map(source => source.replace(/:\d+$/u, '')) })) }
|
||||
const definitions = renderPersistenceSchemaDefinitions(inventory, 'en', () => undefined, 3)
|
||||
expect(definitions).toContain('Sources: `packages/core/example/src/types.ts`')
|
||||
expect(definitions).not.toContain('types.ts:8')
|
||||
expect(definitions).not.toContain('(../packages/')
|
||||
expect(definitions).toContain('### Resolved persistence types')
|
||||
expect(definitions).toContain('#### `ErrorInfo`')
|
||||
const index = renderPersistenceSchemaIndex(inventory, 'en', ['[Historical schema](v0.schema.json)'], 3)
|
||||
expect(index).toContain('[Historical schema](v0.schema.json)')
|
||||
expect(index).toContain('### Persistence type fingerprints')
|
||||
expect(index).not.toContain('(persistence-schema.json)')
|
||||
expect(renderPersistenceSchemaDefinitions(current)).toContain('[`packages/core/example/src/types.ts:8`](../packages/core/example/src/types.ts)')
|
||||
})
|
||||
|
||||
it('refuses a current inventory that omits a referenced definition', () => {
|
||||
const complete = fixture()
|
||||
const missing: PersistenceSchemaInventory = { ...complete, types: [] }
|
||||
expect(() => renderPersistenceSchemaIndex(missing)).toThrow(/absent from the inventory/u)
|
||||
})
|
||||
|
||||
it('renders a recursive definition through a finite self-reference', () => {
|
||||
const schema = canonicalizeSchema([{ kind: 'object', properties: [{ name: 'next', type: 0, optional: true }], indices: [] }], 0)
|
||||
const digest = schemaDigest(schema)
|
||||
const inventory: PersistenceSchemaInventory = {
|
||||
formatVersion: 1,
|
||||
roots: [{ key: 'SessionHeader', kind: 'header', digest, schema }],
|
||||
types: [{ digest, schema, names: ['Recursive'], sources: [] }],
|
||||
}
|
||||
expect(renderPersistenceSchemaDefinitions(inventory)).toContain('| `next` | optional | [`Recursive`](#persistence-type-recursive) |')
|
||||
})
|
||||
|
||||
it('uses intrinsic scalar labels even when an alias or reference supplied a name', () => {
|
||||
const schema = canonicalizeSchema([{ kind: 'primitive', type: 'string' }], 0)
|
||||
const digest = schemaDigest(schema)
|
||||
const inventory: PersistenceSchemaInventory = {
|
||||
formatVersion: 1,
|
||||
roots: [],
|
||||
types: [{ digest, schema, names: ['SessionHeader.agentPreset'], sources: [] }],
|
||||
}
|
||||
const rendered = renderPersistenceSchemaDefinitions(inventory)
|
||||
expect(rendered).toContain('### `string`')
|
||||
expect(rendered).not.toContain('### `SessionHeader.agentPreset`')
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,202 @@
|
||||
/** Readable, linked persistence schemas rendered from the fingerprint inventory. */
|
||||
|
||||
import { githubSlug } from './verify-md-links.ts'
|
||||
import { persistenceCatalogText, type PersistenceCatalogLocale } from './persistence-catalog-text.ts'
|
||||
import {
|
||||
canonicalizeSchema,
|
||||
schemaChildren,
|
||||
schemaDigest,
|
||||
type CanonicalSchema,
|
||||
type PersistenceSchemaInventory,
|
||||
type PersistenceType,
|
||||
type SchemaNode,
|
||||
} from './persistence-schema-model.ts'
|
||||
|
||||
interface TypeDisplay {
|
||||
readonly type: PersistenceType
|
||||
readonly label: string
|
||||
readonly anchor: string
|
||||
}
|
||||
|
||||
function code(text: string): string {
|
||||
return '`' + text.replaceAll('`', '\\`').replaceAll('|', '\\|') + '`'
|
||||
}
|
||||
|
||||
function sourcePath(source: string): string {
|
||||
return source.replace(/:\d+(?::\d+)?$/u, '')
|
||||
}
|
||||
|
||||
function nodeAt(schema: CanonicalSchema, index: number): SchemaNode {
|
||||
const node = schema.nodes[index]
|
||||
if (!node) throw new Error(`persistence catalog: missing schema node ${String(index)}`)
|
||||
return node
|
||||
}
|
||||
|
||||
function childPath(node: SchemaNode, position: number): string {
|
||||
switch (node.kind) {
|
||||
case 'object': return node.properties[position]?.name ?? `index-${String(position - node.properties.length)}`
|
||||
case 'array': return 'item'
|
||||
case 'tuple': return `item-${String(position)}`
|
||||
case 'union': return `variant-${String(position)}`
|
||||
case 'primitive':
|
||||
case 'literal':
|
||||
case 'opaque': return String(position)
|
||||
default: return assertNever(node)
|
||||
}
|
||||
}
|
||||
|
||||
function displays(inventory: PersistenceSchemaInventory): Map<string, TypeDisplay> {
|
||||
const paths = new Map<string, string>()
|
||||
for (const root of inventory.roots) {
|
||||
const seen = new Set<number>()
|
||||
const visit = (index: number, path: string): void => {
|
||||
if (seen.has(index)) return
|
||||
seen.add(index)
|
||||
const digest = schemaDigest(canonicalizeSchema(root.schema.nodes, index))
|
||||
if (!paths.has(digest)) paths.set(digest, path)
|
||||
const node = nodeAt(root.schema, index)
|
||||
schemaChildren(node).forEach((child, position) => { visit(child, `${path}.${childPath(node, position)}`) })
|
||||
}
|
||||
visit(0, root.key)
|
||||
}
|
||||
const labels = inventory.types.map((type) => {
|
||||
const node = nodeAt(type.schema, 0)
|
||||
const label = node.kind === 'primitive' ? node.type
|
||||
: node.kind === 'literal' ? JSON.stringify(node.value)
|
||||
: node.kind === 'opaque' ? node.reason
|
||||
: type.names[0] ?? paths.get(type.digest) ?? node.kind
|
||||
return { type, label }
|
||||
})
|
||||
const counts = new Map<string, number>()
|
||||
for (const { label } of labels) counts.set(label, (counts.get(label) ?? 0) + 1)
|
||||
const used = new Set<string>()
|
||||
return new Map(labels.map(({ type, label: original }) => {
|
||||
const label = (counts.get(original) ?? 0) > 1
|
||||
? `${original} (${type.sources[0] ? sourcePath(type.sources[0]) : paths.get(type.digest) ?? 'anonymous'})`
|
||||
: original
|
||||
const base = `persistence-type-${githubSlug(label)}`
|
||||
let anchor = base
|
||||
for (let suffix = 2; used.has(anchor); suffix += 1) anchor = `${base}-${String(suffix)}`
|
||||
used.add(anchor)
|
||||
return [type.digest, { type, label, anchor }]
|
||||
}))
|
||||
}
|
||||
|
||||
function reference(digest: string, entries: ReadonlyMap<string, TypeDisplay>): string {
|
||||
const entry = entries.get(digest)
|
||||
if (!entry) throw new Error(`persistence catalog: reachable type ${digest} is absent from the inventory`)
|
||||
return `[${code(entry.label)}](#${entry.anchor})`
|
||||
}
|
||||
|
||||
function typeExpression(
|
||||
schema: CanonicalSchema,
|
||||
index: number,
|
||||
entries: ReadonlyMap<string, TypeDisplay>,
|
||||
locale: PersistenceCatalogLocale,
|
||||
): string {
|
||||
const node = nodeAt(schema, index)
|
||||
if (node.kind === 'primitive') return code(node.type)
|
||||
if (node.kind === 'literal') return code(JSON.stringify(node.value))
|
||||
if (node.kind === 'opaque') return `${code(node.reason)}${persistenceCatalogText[locale].opaque}`
|
||||
return reference(schemaDigest(canonicalizeSchema(schema.nodes, index)), entries)
|
||||
}
|
||||
|
||||
function definition(
|
||||
entry: TypeDisplay,
|
||||
entries: ReadonlyMap<string, TypeDisplay>,
|
||||
locale: PersistenceCatalogLocale,
|
||||
sourceLink: (source: string) => string | undefined,
|
||||
headingLevel: number,
|
||||
): string[] {
|
||||
const text = persistenceCatalogText[locale]
|
||||
const schema = entry.type.schema
|
||||
const node = nodeAt(schema, 0)
|
||||
const lines = [`<a id="${entry.anchor}"></a>`, '', `${'#'.repeat(headingLevel)} ${code(entry.label)}`, '', `SHA-256: ${code(entry.type.digest)}`, '']
|
||||
if (entry.type.sources.length > 0) {
|
||||
lines.push(`${text.sources}${entry.type.sources.map((source) => {
|
||||
const href = sourceLink(sourcePath(source))
|
||||
return href === undefined ? code(source) : `[${code(source)}](${href})`
|
||||
}).join(' · ')}`, '')
|
||||
}
|
||||
const expression = (index: number): string => typeExpression(schema, index, entries, locale)
|
||||
switch (node.kind) {
|
||||
case 'object':
|
||||
if (node.properties.length === 0 && node.indices.length === 0) lines.push(text.emptyObject, '')
|
||||
else {
|
||||
lines.push(text.propertyColumns, '|---|---|---|')
|
||||
for (const property of node.properties) {
|
||||
lines.push(`| ${code(property.name)} | ${property.optional ? text.optional : text.required} | ${expression(property.type)} |`)
|
||||
}
|
||||
for (const index of node.indices) lines.push(`| [${expression(index.key)}] | ${text.index} | ${expression(index.value)} |`)
|
||||
lines.push('')
|
||||
}
|
||||
break
|
||||
case 'array': lines.push(`${text.arrayPrefix}${expression(node.element)}${text.arraySuffix}`, ''); break
|
||||
case 'tuple':
|
||||
lines.push(text.positionColumns, '|---|---|---|')
|
||||
node.elements.forEach((element, index) => {
|
||||
const presence = element.rest ? text.rest : element.optional ? text.optional : text.required
|
||||
lines.push(`| ${String(index)} | ${presence} | ${expression(element.type)} |`)
|
||||
})
|
||||
lines.push('')
|
||||
break
|
||||
case 'union':
|
||||
lines.push(text.oneOf, '', ...node.types.map(index => `- ${expression(index)}`), '')
|
||||
break
|
||||
case 'primitive': lines.push(code(node.type), ''); break
|
||||
case 'literal': lines.push(code(JSON.stringify(node.value)), ''); break
|
||||
case 'opaque': lines.push(`${code(node.reason)}${text.opaqueExplanation}`, ''); break
|
||||
default: assertNever(node)
|
||||
}
|
||||
return lines
|
||||
}
|
||||
|
||||
/**
|
||||
* Render every tracked root with its exact digest and resolved type reference.
|
||||
* @param inventory - complete current-source schemas and declaration metadata.
|
||||
* @param locale - generated document language.
|
||||
* @param introduction - paragraphs before the root table; defaults to current-source links.
|
||||
* @param headingLevel - section depth within the containing reference.
|
||||
* @returns Markdown index including the history and contributor workflow links.
|
||||
*/
|
||||
export function renderPersistenceSchemaIndex(
|
||||
inventory: PersistenceSchemaInventory,
|
||||
locale: PersistenceCatalogLocale = 'en',
|
||||
introduction: readonly string[] = [persistenceCatalogText[locale].fingerprintsIntro, persistenceCatalogText[locale].historyIntro],
|
||||
headingLevel: 2 | 3 = 2,
|
||||
): string {
|
||||
const entries = displays(inventory)
|
||||
const text = persistenceCatalogText[locale]
|
||||
return [
|
||||
`${'#'.repeat(headingLevel)} ${text.fingerprints}`, '', ...introduction.flatMap(paragraph => [paragraph, '']),
|
||||
text.rootColumns, '|---|---|---|---|',
|
||||
...inventory.roots.map(root => `| ${code(root.key)} | ${root.kind} | ${code(root.digest)} | ${reference(root.digest, entries)} |`), '',
|
||||
].join('\n')
|
||||
}
|
||||
|
||||
/**
|
||||
* Render every reachable type once, with links for shared and recursive definitions.
|
||||
* @param inventory - complete current-source schemas and declaration metadata.
|
||||
* @param locale - generated document language.
|
||||
* @param sourceLink - source path to URL; undefined keeps historical locations as text.
|
||||
* @param headingLevel - section depth; individual definitions use the next heading level.
|
||||
* @returns Markdown definitions whose anchors use names or owning paths instead of hashes.
|
||||
*/
|
||||
export function renderPersistenceSchemaDefinitions(
|
||||
inventory: PersistenceSchemaInventory,
|
||||
locale: PersistenceCatalogLocale = 'en',
|
||||
sourceLink: (source: string) => string | undefined = source => `../${source}`,
|
||||
headingLevel: 2 | 3 = 2,
|
||||
): string {
|
||||
const entries = displays(inventory)
|
||||
const text = persistenceCatalogText[locale]
|
||||
const sorted = [...entries.values()].sort((left, right) => left.anchor < right.anchor ? -1 : left.anchor > right.anchor ? 1 : 0)
|
||||
return [
|
||||
`${'#'.repeat(headingLevel)} ${text.definitions}`, '', text.definitionsIntro, '',
|
||||
...sorted.flatMap(entry => definition(entry, entries, locale, sourceLink, headingLevel + 1)),
|
||||
].join('\n')
|
||||
}
|
||||
|
||||
function assertNever(value: never): never {
|
||||
throw new Error(`persistence catalog: unsupported type ${JSON.stringify(value)}`)
|
||||
}
|
||||
@@ -1,15 +1,27 @@
|
||||
/**
|
||||
* Acceptance-path coverage for the rescope codemod's exact-edit classifier: a
|
||||
* duplicated insertion — what a non-idempotent apply produces — must be
|
||||
* rejected rather than applied again.
|
||||
*/
|
||||
/** Recorded npm evidence stays intact while authored files and exact edits remain checked. */
|
||||
|
||||
import { describe, expect, it } from 'vitest'
|
||||
import { exactEditState } from './rescope-vendor.ts'
|
||||
import { exactEditState, isRescopeExcluded } from './rescope-vendor.ts'
|
||||
|
||||
const ANCHOR = '\n## Sync procedure'
|
||||
const INSERTED = `\n15. **rescope**: one log entry.\n${ANCHOR}`
|
||||
|
||||
describe('rescope file selection', () => {
|
||||
it('preserves the recorded npm resolution', () => {
|
||||
expect(isRescopeExcluded('scripts/dependency-catalog/package-lock.json')).toBe(true)
|
||||
})
|
||||
|
||||
it.each([
|
||||
'scripts/dependency-catalog/package.json',
|
||||
'scripts/dependency-catalog/source.ts',
|
||||
'scripts/other/package-lock.json',
|
||||
'packages/example/src/index.ts',
|
||||
'packages/example/package.json',
|
||||
])('keeps %s subject to upstream package-name checks', (file) => {
|
||||
expect(isRescopeExcluded(file)).toBe(false)
|
||||
})
|
||||
})
|
||||
|
||||
describe('exactEditState', () => {
|
||||
it('classifies an insertion by its target form, so a duplicate is invalid', () => {
|
||||
expect(exactEditState(`log\n${ANCHOR}\n`, ANCHOR, INSERTED, 1)).toBe('pending')
|
||||
|
||||
+14
-14
@@ -91,6 +91,7 @@ const GENERIC_SKIPS: readonly GenericSkip[] = [
|
||||
{ file: 'packages/client/ui-agent-preset/tests/locales.client.spec.ts', upstream: ['cordis'] },
|
||||
{ file: 'packages/client/ui-agent-preset/tests/section.client.spec.tsx', upstream: ['cordis'] },
|
||||
{ file: 'apps/cli/tests/web-agent-presets.e2e.ts', upstream: ['cordis'] },
|
||||
{ file: 'apps/cli/tests/profiles/web/tests/fixtures/creator-plugin-manager.mjs', upstream: ['cordis'] },
|
||||
{ file: 'apps/web/tests/agent-preset-authoring.e2e.ts', upstream: ['cordis'] },
|
||||
{ file: 'packages/preset/agent-presets/tests/session.spec.ts', upstream: ['cordis'] },
|
||||
// The preset's own composition: its header comment and its system prompt name
|
||||
@@ -222,15 +223,8 @@ const EXACT_EDITS: readonly ExactEdit[] = [
|
||||
{
|
||||
id: 'vendor-readme-preamble',
|
||||
file: 'vendor/README.md',
|
||||
find: 'All vendored packages keep their **original npm names** and are marked `private: true` — they are never published from this repo. `pnpm-workspace.yaml#linkWorkspacePackages` makes matching upstream semver ranges resolve these pinned workspaces, including imports from built `lib/`; disabling it substitutes npm copies behind the same names.',
|
||||
replace: 'All vendored packages are **renamed into the `@deepseek-ai` scope** (`cordis` → `@deepseek-ai/cordis`, `@cordisjs/plugin-<x>` → `@deepseek-ai/cordis-plugin-<x>`): every harness package declares `cordis` as a peer dependency, so publishing the harness publishes this framework layer too, and a publication under the upstream names would squat them on the registry. Directory names and upstream version numbers are deliberately unchanged, so the manifest below still reads as an upstream snapshot. `pnpm-workspace.yaml#linkWorkspacePackages` makes those preserved semver ranges resolve these pinned workspaces, including imports from built `lib/`.',
|
||||
expect: 1,
|
||||
},
|
||||
{
|
||||
id: 'vendor-readme-schemastery-note',
|
||||
file: 'vendor/README.md',
|
||||
find: 'whose lazy `require(\'cosmokit\')` can race',
|
||||
replace: 'whose lazy `require(\'@deepseek-ai/cosmokit\')` can race',
|
||||
find: 'All vendored packages keep their **original npm names** (they are resolved through pnpm workspaces) and are marked `private: true` — they are never published from this repo.',
|
||||
replace: 'All vendored packages use the **`@deepseek-ai` scope** (`cordis` → `@deepseek-ai/cordis`, `@cordisjs/plugin-<x>` → `@deepseek-ai/cordis-plugin-<x>`). The manifest table records upstream versions and source commits; each package manifest carries its Harness release version and publication metadata. Repository-owned runtime dependencies use `workspace:^`, so local builds resolve the pinned workspace packages and publication substitutes release ranges.',
|
||||
expect: 1,
|
||||
},
|
||||
{
|
||||
@@ -365,9 +359,9 @@ const VENDORED_LIBRARY = /^@deepseek-ai\\/(cosmokit|schemastery)(\\/|$)/
|
||||
find: `| Package | Upstream | License |
|
||||
| --- | --- | --- |
|
||||
\${vendored.map(row => \`| \\\`\${row.npmName}\\\` | [\${row.upstream.replace('https://', '')}](\${row.upstream}) | MIT |\`).join('\\n')}`,
|
||||
replace: `| Package | Upstream name | Upstream | License |
|
||||
replace: `| Package | Upstream name | Source | License |
|
||||
| --- | --- | --- | --- |
|
||||
\${vendored.map(row => \`| \\\`\${row.npmName}\\\` | \\\`\${row.upstreamName}\\\` | [\${row.upstream.replace('https://', '')}](\${row.upstream}) | MIT |\`).join('\\n')}`,
|
||||
\${vendored.map(row => \`| \\\`\${row.npmName}\\\` | \\\`\${row.upstreamName}\\\` | [\${row.sourceDirectory}](\${row.sourceDirectory}/) | MIT |\`).join('\\n')}`,
|
||||
expect: 1,
|
||||
},
|
||||
{
|
||||
@@ -426,8 +420,12 @@ const VENDORED_LIBRARY = /^@deepseek-ai\\/(cosmokit|schemastery)(\\/|$)/
|
||||
})),
|
||||
]
|
||||
|
||||
/** Files the rescope must never rewrite. */
|
||||
function excluded(file: string): boolean {
|
||||
/**
|
||||
* Identify files whose recorded content must remain outside the rescope pass.
|
||||
* @param file - Repository-relative path with forward slash separators.
|
||||
* @returns Whether the codemod must preserve the file without scanning its tokens.
|
||||
*/
|
||||
export function isRescopeExcluded(file: string): boolean {
|
||||
if (file === 'scripts/rescope-vendor.ts') return true // the mapping itself
|
||||
if (file.startsWith('.agents/notes/')) return true // notes record what was true when written
|
||||
// Recorded model payloads quote documentation verbatim, so they must mirror the
|
||||
@@ -437,6 +435,8 @@ function excluded(file: string): boolean {
|
||||
if (file === 'docs/rescope.md' || file === 'docs/rescope.zh.md') return true
|
||||
if (file.endsWith('.i18n.yaml')) return true // blob-hash records, re-recorded by the pairing gate
|
||||
if (file === 'pnpm-lock.yaml') return true // regenerated by pnpm install
|
||||
// Raw npm registry resolution; only gen-dependency-catalog --refresh replaces this evidence.
|
||||
if (file === 'scripts/dependency-catalog/package-lock.json') return true
|
||||
if (/^vendor\/[^/]+\/(README\.md|LICENSE)$/.test(file)) return true // upstream files kept verbatim
|
||||
return !EXTENSIONS.some(extension => file.endsWith(extension))
|
||||
}
|
||||
@@ -565,7 +565,7 @@ function main(): void {
|
||||
const all = patterns(reverse)
|
||||
const files = execFileSync('git', ['ls-files', '-z'], { cwd: root, encoding: 'utf8' })
|
||||
.split('\0')
|
||||
.filter(file => file !== '' && !excluded(file))
|
||||
.filter(file => file !== '' && !isRescopeExcluded(file))
|
||||
|
||||
const counts = new Map<string, { files: number; lines: number }>()
|
||||
const failures: string[] = []
|
||||
|
||||
@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs'
|
||||
import { describe, expect, it, vi, type MockInstance } from 'vitest'
|
||||
import {
|
||||
cliGateOptions,
|
||||
collectDescendants,
|
||||
defaultConcurrency,
|
||||
formatGateResultReason,
|
||||
gatesForMode,
|
||||
@@ -181,12 +182,52 @@ describe('gate graph validation', () => {
|
||||
expect(scripts['test:bench:built']).toBe('vitest run --config vitest.bench.config.ts')
|
||||
})
|
||||
|
||||
it('checks all maintained repository references locally and in CI', () => {
|
||||
const { scripts } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as {
|
||||
scripts: Record<string, string>
|
||||
}
|
||||
for (const mode of ['doc-sync', 'doc-quick', 'ci-static'] as const) {
|
||||
const gates = withPnpmEntrypoint(() => gatesForMode(mode))
|
||||
expect(gates).toContainEqual(expect.objectContaining({
|
||||
id: 'repository-references',
|
||||
displayCommand: 'pnpm run verify-repository-references',
|
||||
}))
|
||||
}
|
||||
expect(scripts['verify-repository-references']).toBe('tsx scripts/verify-repository-references.ts')
|
||||
})
|
||||
|
||||
it('keeps the public repository link policy in the documentation gate', () => {
|
||||
const ids = withPnpmEntrypoint(() => gatesForMode('doc-sync').map(subject => subject.id))
|
||||
|
||||
expect(ids).toContain('public-repository-links')
|
||||
})
|
||||
|
||||
it('keeps the concrete terminology policy in the documentation gate', () => {
|
||||
const ids = withPnpmEntrypoint(() => gatesForMode('doc-sync').map(subject => subject.id))
|
||||
|
||||
expect(ids).toContain('concrete-terms')
|
||||
})
|
||||
|
||||
it('checks retrospective releases alongside the current persistence history', () => {
|
||||
for (const mode of ['doc-sync', 'ci-static'] as const) {
|
||||
const ids = withPnpmEntrypoint(() => gatesForMode(mode).map(subject => subject.id))
|
||||
expect(ids).toEqual(expect.arrayContaining(['persistence-changes', 'persistence-releases']))
|
||||
}
|
||||
})
|
||||
|
||||
it('requires complete Session format references locally and in CI', () => {
|
||||
const { scripts } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as {
|
||||
scripts: Record<string, string>
|
||||
}
|
||||
for (const mode of ['doc-sync', 'doc-quick', 'ci-static'] as const) {
|
||||
expect(withPnpmEntrypoint(() => gatesForMode(mode))).toContainEqual(expect.objectContaining({
|
||||
id: 'persistence-formats',
|
||||
displayCommand: 'pnpm run verify-persistence-formats',
|
||||
}))
|
||||
}
|
||||
expect(scripts['verify-persistence-formats']).toBe('tsx scripts/persistence-formats.ts')
|
||||
})
|
||||
|
||||
it('keeps package-group subsystem ownership in the documentation gate', () => {
|
||||
const ids = withPnpmEntrypoint(() => gatesForMode('doc-sync').map(subject => subject.id))
|
||||
|
||||
@@ -206,14 +247,21 @@ describe('gate graph validation', () => {
|
||||
expect(quick).toEqual(full.filter(gate => gate.quick === true))
|
||||
})
|
||||
|
||||
it('checks the recorded npm dependency catalog in both documentation aggregates', () => {
|
||||
for (const mode of ['doc-sync', 'doc-quick'] as const) {
|
||||
expect(withPnpmEntrypoint(() => gatesForMode(mode).find(gate => gate.id === 'dependency-catalog')))
|
||||
.toMatchObject({ args: ['/private/pnpm.cjs', 'run', 'verify-dependency-catalog'] })
|
||||
}
|
||||
})
|
||||
|
||||
it('keeps the hygiene aggregate aligned with the package script checks', () => {
|
||||
const ids = withPnpmEntrypoint(() => gatesForMode('hygiene').map(subject => subject.id))
|
||||
|
||||
expect(ids).toEqual([
|
||||
'rescope-vendor', 'publint', 'constraints', 'package-dependencies', 'application-entrypoints',
|
||||
'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', 'no-bare-dispatcher', 'cordis-config',
|
||||
'runtime-closure', 'vendored-links',
|
||||
'runtime-closure',
|
||||
])
|
||||
expect(defaultConcurrency('hygiene', ids.length, 8)).toEqual({
|
||||
workers: 4,
|
||||
@@ -224,9 +272,9 @@ describe('gate graph validation', () => {
|
||||
it('schedules the longest documentation leaves before short checks', () => {
|
||||
const ids = withPnpmEntrypoint(() => gatesForMode('doc-sync').map(subject => subject.id))
|
||||
|
||||
expect(ids.slice(0, 10)).toEqual([
|
||||
expect(ids.slice(0, 11)).toEqual([
|
||||
'doc-typecheck', 'docs-site-build', 'doc-graphs', 'markdown-links', 'type-equivalence',
|
||||
'cordis-catalog', 'cordis-inspect-catalog', 'mermaid', 'scoped-events', 'translation-pairing',
|
||||
'cordis-catalog', 'cordis-inspect-catalog', 'workflow-guest', 'mermaid', 'scoped-events', 'translation-pairing',
|
||||
])
|
||||
})
|
||||
|
||||
@@ -258,6 +306,17 @@ describe('gate graph validation', () => {
|
||||
},
|
||||
)
|
||||
|
||||
it.each(['ci-primary', 'ci-static', 'check-all', 'hygiene'] as const)(
|
||||
'executes default-product experimental isolation in %s',
|
||||
(mode) => {
|
||||
const gate = withPnpmEntrypoint(() => gatesForMode(mode)
|
||||
.find(subject => subject.id === 'default-product-isolation'))
|
||||
|
||||
expect(gate?.args).toContain('verify-default-product-isolation')
|
||||
expect(gate?.allowFailure).not.toBe(true)
|
||||
},
|
||||
)
|
||||
|
||||
it.each(['ci-primary', 'ci-static', 'check-all'] as const)(
|
||||
'keeps the client dependency policy in %s',
|
||||
(mode) => {
|
||||
@@ -917,6 +976,30 @@ describe('fail-fast scheduling', () => {
|
||||
})
|
||||
|
||||
describe('process-table parsing', () => {
|
||||
it('excludes the root when a parent link returns to it', () => {
|
||||
expect(collectDescendants(100, [[200, 100], [100, 200], [300, 200]]))
|
||||
.toEqual([200, 300])
|
||||
})
|
||||
|
||||
it('visits duplicate and cyclic descendant links only once', () => {
|
||||
expect(collectDescendants(100, [
|
||||
[200, 100], [200, 100], [300, 100], [200, 200], [400, 200], [200, 400], [500, 300], [900, 800],
|
||||
])).toEqual([200, 300, 400, 500])
|
||||
})
|
||||
|
||||
it('returns no descendants for an isolated or self-parented root', () => {
|
||||
expect(collectDescendants(100, [])).toEqual([])
|
||||
expect(collectDescendants(100, [[100, 100]])).toEqual([])
|
||||
})
|
||||
|
||||
it('walks a wide child set without spreading it into call arguments', () => {
|
||||
const children = Array.from({ length: 150_000 }, (_, i): [number, number] => [i + 3, 2])
|
||||
const descendants = collectDescendants(1, [[2, 1], ...children])
|
||||
expect(descendants).toHaveLength(children.length + 1)
|
||||
expect(descendants[0]).toBe(2)
|
||||
expect(descendants.at(-1)).toBe(150_002)
|
||||
})
|
||||
|
||||
it('parses `pid ppid` rows from a POSIX ps dump', () => {
|
||||
expect(parsePidPpidLines(' 123 1\n456 123\n 789 456\n')).toEqual([[123, 1], [456, 123], [789, 456]])
|
||||
})
|
||||
|
||||
+41
-16
@@ -286,7 +286,6 @@ export function gatesForMode(selected: Mode): Gate[] {
|
||||
...hygieneLeafGates(),
|
||||
pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }),
|
||||
pnpmScript('runtime-closure', 'verify-runtime-closure', { label: 'runtime closure' }),
|
||||
pnpmScript('vendored-links', 'verify-vendored-links', { label: 'vendored links' }),
|
||||
]
|
||||
case 'doc-sync':
|
||||
return docSyncLeafGates()
|
||||
@@ -298,6 +297,7 @@ export function gatesForMode(selected: Mode): Gate[] {
|
||||
function ciSharedStaticGates(): Gate[] {
|
||||
return [
|
||||
pnpmScript('runtime-closure', 'verify-runtime-closure', { label: 'runtime closure' }),
|
||||
pnpmScript('default-product-isolation', 'verify-default-product-isolation', { label: 'default product isolation' }),
|
||||
pnpmScript('application-entrypoints', 'verify-application-entrypoints', { label: 'application entrypoints' }),
|
||||
pnpmScript('constraints', 'constraints'),
|
||||
pnpmScript('package-dependencies', 'verify-package-dependencies', { label: 'package dependencies' }),
|
||||
@@ -369,7 +369,7 @@ function nodeCompatSmokeGates(options: { cliSmoke?: boolean } = {}): Gate[] {
|
||||
pnpmExec('source-worker-smoke', [
|
||||
'vitest',
|
||||
'run',
|
||||
'packages/workflow/workflow-worker-thread/tests/source-worker.compat.spec.ts',
|
||||
'packages/workflow/workflow-ptc/tests/source-runtime.compat.spec.ts',
|
||||
], { label: 'source worker smoke' }),
|
||||
pnpmExec('jsonl-zstd-smoke', [
|
||||
'vitest',
|
||||
@@ -386,6 +386,13 @@ function nodeCompatSmokeGates(options: { cliSmoke?: boolean } = {}): Gate[] {
|
||||
'run',
|
||||
'scripts/vitest-environment.compat.spec.ts',
|
||||
], { label: 'Vitest jsdom smoke' }),
|
||||
pnpmExec('profile-resolution-smoke', [
|
||||
'vitest',
|
||||
'run',
|
||||
'packages/boot/app-boot/tests/profile-resolution.spec.ts',
|
||||
'packages/boot/app-boot/tests/profile-resolution-service.spec.ts',
|
||||
'packages/boot/app-boot/tests/profile-resolution-worker-bootstrap.spec.ts',
|
||||
], { label: 'profile resolution smoke' }),
|
||||
]
|
||||
if (options.cliSmoke) {
|
||||
gates.push(
|
||||
@@ -694,6 +701,7 @@ function hygieneLeafGates(options: { artifactNeeds?: string[] } = {}): Gate[] {
|
||||
pnpmScript('rescope-vendor', 'rescope-vendor:check', { label: 'vendor rescope' }),
|
||||
pnpmScript('publint', 'publint', artifactOptions),
|
||||
pnpmScript('constraints', 'constraints'),
|
||||
pnpmScript('default-product-isolation', 'verify-default-product-isolation', { label: 'default product isolation' }),
|
||||
pnpmScript('package-dependencies', 'verify-package-dependencies', { label: 'package dependencies' }),
|
||||
pnpmScript('application-entrypoints', 'verify-application-entrypoints', { label: 'application entrypoints' }),
|
||||
pnpmScript('dsh-package-licenses', 'verify-dsh-package-licenses', { label: 'DSH package licenses' }),
|
||||
@@ -733,6 +741,7 @@ function docSyncLeafGates(options: {
|
||||
pnpmScript('type-equivalence', 'verify-type-equiv', { label: 'type equivalence', quick: true }),
|
||||
pnpmScript('cordis-catalog', 'verify-cordis-catalog', { label: 'cordis catalog' }),
|
||||
pnpmScript('cordis-inspect-catalog', 'verify-cordis-inspect-catalog', { label: 'Cordis inspect catalog' }),
|
||||
pnpmScript('workflow-guest', 'verify-workflow-guest', { label: 'workflow guest source' }),
|
||||
pnpmScript('mermaid', 'verify-mermaid'),
|
||||
pnpmScript('scoped-events', 'verify-scoped-events', { label: 'scoped events' }),
|
||||
pnpmScript('translation-pairing', 'verify-translation-pairing', { label: 'translation pairing', quick: true }),
|
||||
@@ -741,9 +750,15 @@ function docSyncLeafGates(options: {
|
||||
pnpmScript('export-jsdoc', 'verify-export-jsdoc', { label: 'export jsdoc' }),
|
||||
pnpmScript('tool-catalog', 'verify-tool-catalog', { label: 'tool catalog' }),
|
||||
pnpmScript('config-catalog', 'verify-config-catalog', { label: 'config catalog' }),
|
||||
pnpmScript('dependency-catalog', 'verify-dependency-catalog', { label: 'npm dependency catalog', quick: true }),
|
||||
pnpmScript('persistence-catalog', 'verify-persistence-catalog', { label: 'persistence catalog' }),
|
||||
pnpmScript('persistence-changes', 'verify-persistence-changes', { label: 'persistence type history' }),
|
||||
pnpmScript('persistence-releases', 'verify-persistence-releases', { label: 'released persistence history' }),
|
||||
pnpmScript('persistence-formats', 'verify-persistence-formats', { label: 'Session format references', quick: true }),
|
||||
pnpmScript('session-format-catalog', 'verify-session-format-catalog', { label: 'Session format catalog' }),
|
||||
pnpmScript('public-repository-links', 'verify-public-repository-links', { label: 'public repository links', quick: true }),
|
||||
pnpmScript('repository-references', 'verify-repository-references', { label: 'repository references', quick: true }),
|
||||
pnpmScript('concrete-terms', 'verify-concrete-terms', { label: 'concrete terms', quick: true }),
|
||||
pnpmScript('doc-refs', 'verify-doc-refs', { label: 'doc refs', quick: true }),
|
||||
pnpmScript('subsystem-pages', 'verify-subsystem-pages', { label: 'subsystem pages' }),
|
||||
pnpmScript('package-paths', 'verify-package-paths', { label: 'package paths' }),
|
||||
@@ -761,7 +776,11 @@ function docSyncLeafGates(options: {
|
||||
label: 'documentation standard tests',
|
||||
quick: true,
|
||||
}),
|
||||
pnpmExec('docs-site-projection', ['vitest', 'run', 'scripts/project-doc-site.spec.ts', 'scripts/verify-doc-site-fragments.spec.ts'], {
|
||||
pnpmExec('docs-site-projection', [
|
||||
'vitest', 'run', 'scripts/project-doc-site.spec.ts', 'scripts/verify-doc-site-fragments.spec.ts',
|
||||
'website/tests/mermaid-viewer.spec.ts',
|
||||
'website/tests/page-markdown-actions.spec.ts', 'website/tests/raw-markdown.spec.ts',
|
||||
], {
|
||||
label: 'documentation site checks',
|
||||
}),
|
||||
pnpmScript('package-readme-limitations', 'verify-package-readme-limitations', { label: 'package README limitations', quick: true }),
|
||||
@@ -787,7 +806,7 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
|
||||
'apps/cli/tests/built-bin.e2e.ts',
|
||||
'packages/host/directory-picker-native/tests/built-worker.e2e.ts',
|
||||
'packages/sdk/server/tests/built-scope-carrier.e2e.ts',
|
||||
'packages/fs/tool-present/tests/built-errors.e2e.ts',
|
||||
'packages/deliverables/tool-present/tests/built-errors.e2e.ts',
|
||||
'packages/subprocess/subprocess-local/tests/spawn-runner-built.e2e.ts',
|
||||
'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
|
||||
'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
|
||||
@@ -796,8 +815,8 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
|
||||
// Built execution consumers: the only automated proof that package-name
|
||||
// imports reach their lib/ entrypoints under plain Node. The e2e lane runs
|
||||
// unbuilt, so these files self-skip there.
|
||||
'packages/workflow/workflow-worker-thread/tests/built-worker.e2e.ts',
|
||||
'packages/code-runtime/code-runtime-worker-thread/tests/built-lib.e2e.ts',
|
||||
'packages/workflow/workflow-ptc/tests/built-runtime.e2e.ts',
|
||||
'packages/ptc-runtime/ptc-runtime-node/tests/built-lib.e2e.ts',
|
||||
'packages/session/session-persistence-jsonl/tests/built-migration-worker.e2e.ts',
|
||||
'packages/lsp/lsp-stdio/tests/built-lib.e2e.ts',
|
||||
], {
|
||||
@@ -1506,23 +1525,29 @@ export function taskkillArgs(rootPid: number, descendants: number[]): string[][]
|
||||
return [rootPid, ...descendants].map(pid => ['/PID', String(pid), '/T', '/F'])
|
||||
}
|
||||
|
||||
/** Breadth-first walk of the pid/ppid rows starting at `root`. */
|
||||
function collectDescendants(root: number, rows: Array<[number, number]>): number[] {
|
||||
/**
|
||||
* Walk a process-table snapshot without revisiting duplicate or cyclic PID links.
|
||||
* @param root - process whose descendants are collected; excluded from the result.
|
||||
* @param rows - observed PID and parent PID pairs.
|
||||
* @returns distinct reachable descendants in breadth-first order.
|
||||
*/
|
||||
export function collectDescendants(root: number, rows: Array<[number, number]>): number[] {
|
||||
const byParent = new Map<number, number[]>()
|
||||
for (const [pid, ppid] of rows) {
|
||||
const children = byParent.get(ppid) ?? []
|
||||
children.push(pid)
|
||||
byParent.set(ppid, children)
|
||||
}
|
||||
const result: number[] = []
|
||||
const queue = byParent.get(root) ?? []
|
||||
for (let index = 0; index < queue.length; index += 1) {
|
||||
const pid = queue[index]
|
||||
if (pid === undefined) continue
|
||||
result.push(pid)
|
||||
queue.push(...(byParent.get(pid) ?? []))
|
||||
const seen = new Set([root])
|
||||
const queue = [root]
|
||||
for (const parent of queue) {
|
||||
for (const pid of byParent.get(parent) ?? []) {
|
||||
if (seen.has(pid)) continue
|
||||
seen.add(pid)
|
||||
queue.push(pid)
|
||||
}
|
||||
}
|
||||
return result
|
||||
return queue.slice(1)
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -4,7 +4,6 @@ import { pnpmInvocation } from './pnpm-invocation.ts'
|
||||
|
||||
const serialFiles = [
|
||||
'apps/web/tests/hmr-live.e2e.ts',
|
||||
'apps/web/tests/cordis-tool-round.e2e.ts',
|
||||
]
|
||||
const workerRaw = process.env.DSH_WEB_SNAPSHOT_WORKERS
|
||||
const workers = Number.parseInt(workerRaw ?? '', 10)
|
||||
|
||||
@@ -143,7 +143,7 @@ describe('canonicalSessionFixture', () => {
|
||||
expect(canonicalSessionFixture(content)).toBe(content)
|
||||
})
|
||||
|
||||
it.each([0, 1, 2])('rejects v%i sequence gaps and invalid provenance ranges with source line diagnostics', (version) => {
|
||||
it.each([0, 1, 2])('rejects v%i sequence gaps and invalid source-event ranges with source line diagnostics', (version) => {
|
||||
const header = JSON.stringify({ type: 'session', version, id: 'historical', createdAt: 1, delegationDepth: 0, ...(version === 2 ? { isSeeded: false } : {}) })
|
||||
expect(() => canonicalSessionFixture(`${header}\n{"type":"feedback/record","seq":3,"data":{"text":"gap"}}\n`, 'gap.jsonl'))
|
||||
.toThrow(/gap\.jsonl: session snapshot line 2:.*seq/)
|
||||
|
||||
@@ -128,7 +128,7 @@ function parseFixtureRows(content: string, headerValue: unknown): SessionEvent[]
|
||||
// Versionless protocol fixtures and current projected snapshots use scalar
|
||||
// event rows. Current snapshots may contain owner-restored scrub tokens such
|
||||
// as `{{tools}}`; semantic replay restores those sidecars, while this layout
|
||||
// gate owns only envelopes, provenance ranges, and one-event-per-row form.
|
||||
// gate owns only envelopes, source-event ranges, and one-event-per-row form.
|
||||
const projectedCurrent = headerValue !== null
|
||||
&& typeof headerValue === 'object'
|
||||
&& !Array.isArray(headerValue)
|
||||
|
||||
@@ -40,24 +40,24 @@ it.skipIf(process.platform === 'win32')('resolves the exact spill verifier, reta
|
||||
await adapter
|
||||
const command = 'file="' + saved.locator + '"' + "; grep -Fq request/header \"$file\" && grep -Fq session_event_search \"$file\" && printf 'SPILL_CANONICAL_OK\\n'"
|
||||
const spec = ctx.shell.resolve({ command })
|
||||
const output = await ctx.shell.execute(spec).result()
|
||||
const output = await (await ctx.shell.execute(spec)).result()
|
||||
expect(output.timedOut).toBe(false)
|
||||
expect(output.exitCode).toBe(0)
|
||||
expect(output.stdout.text).toBe('SPILL_CANONICAL_OK\n')
|
||||
expect(spec.command).toBe(command)
|
||||
const other = await ctx.shell.execute(ctx.shell.resolve({ command: 'printf ordinary; exit 7' })).result()
|
||||
const other = await (await ctx.shell.execute(ctx.shell.resolve({ command: 'printf ordinary; exit 7' }))).result()
|
||||
expect(other.exitCode).toBe(7)
|
||||
expect(other.stdout.text).toBe('ordinary')
|
||||
const unmatched = await ctx.shell.execute(ctx.shell.resolve({ command: command + '; exit 9' })).result()
|
||||
const unmatched = await (await ctx.shell.execute(ctx.shell.resolve({ command: command + '; exit 9' }))).result()
|
||||
expect(unmatched.exitCode).toBe(9)
|
||||
expect(unmatched.stderr.text).toContain('No such file')
|
||||
const physical = ctx.fs.processPath(await ctx.fs.resolve(saved.locator))
|
||||
await rm(physical)
|
||||
const missing = await ctx.shell.execute(spec).result()
|
||||
const missing = await (await ctx.shell.execute(spec)).result()
|
||||
expect(missing.exitCode).not.toBe(0)
|
||||
expect(missing.stdout.text).toBe('')
|
||||
await adapter.dispose()
|
||||
const restored = await ctx.shell.execute(spec).result()
|
||||
const restored = await (await ctx.shell.execute(spec)).result()
|
||||
expect(restored.exitCode).not.toBe(0)
|
||||
expect(restored.stderr.text).toContain(saved.locator)
|
||||
} finally {
|
||||
|
||||
@@ -33,6 +33,21 @@ describe('recorded-session corpus policy', () => {
|
||||
])).toEqual({ currentRoles: 8, retainedRoles: 5 + adjacent.length, retainedScenarios: 3 + adjacent.length })
|
||||
})
|
||||
|
||||
it('retains retired tools in the current format without claiming migration coverage', () => {
|
||||
const retired = {
|
||||
key: 'web/retired', selectedVersions: [SESSION_FORMAT_VERSION],
|
||||
retained: { version: SESSION_FORMAT_VERSION, coverage: ['retired-tools'] as const },
|
||||
}
|
||||
expect(assertSnapshotCorpusPolicy([current, completeV0, ...adjacent, retired]).retainedScenarios)
|
||||
.toBe(2 + adjacent.length)
|
||||
expect(() => assertSnapshotCorpusPolicy([current, completeV0, retired]))
|
||||
.toThrow('coverage: adjacent-migration')
|
||||
expect(() => assertSnapshotCorpusPolicy([current, completeV0, ...adjacent, {
|
||||
...retired, selectedVersions: [SESSION_FORMAT_VERSION + 1],
|
||||
retained: { ...retired.retained, version: SESSION_FORMAT_VERSION + 1 },
|
||||
}])).toThrow('retained Session format must precede')
|
||||
})
|
||||
|
||||
it('requires v0 coverage from v0 fixtures', () => {
|
||||
expect(() => assertSnapshotCorpusPolicy([current, ...adjacent]))
|
||||
.toThrow('Session corpus lacks v0 coverage')
|
||||
|
||||
@@ -58,11 +58,13 @@ export function assertSnapshotCorpusPolicy(
|
||||
currentRoles += scenario.selectedVersions.length
|
||||
continue
|
||||
}
|
||||
const retiredTools = scenario.retained.coverage.length === 1 && scenario.retained.coverage[0] === 'retired-tools'
|
||||
if (!Number.isSafeInteger(scenario.retained.version)
|
||||
|| scenario.retained.version < 0 || scenario.retained.version >= SESSION_FORMAT_VERSION) {
|
||||
throw new Error(`${scenario.key}: retained Session format must precede current v${SESSION_FORMAT_VERSION}`)
|
||||
|| scenario.retained.version < 0 || scenario.retained.version > SESSION_FORMAT_VERSION
|
||||
|| (scenario.retained.version === SESSION_FORMAT_VERSION && !retiredTools)) {
|
||||
throw new Error(`${scenario.key}: retained Session format must precede current v${SESSION_FORMAT_VERSION} unless it pins retired tools at that version`)
|
||||
}
|
||||
const allowedCoverage = scenario.retained.version === 0
|
||||
const allowedCoverage = retiredTools ? new Set(['retired-tools']) : scenario.retained.version === 0
|
||||
? REQUIRED_V0_COVERAGE
|
||||
: REQUIRED_ADJACENT_COVERAGE
|
||||
if (scenario.retained.coverage.some(item => !allowedCoverage.has(item))) {
|
||||
|
||||
@@ -202,7 +202,7 @@ it('keeps a current-writer majority plus bounded declared historical migration c
|
||||
})))
|
||||
|
||||
expect(assertSnapshotCorpusPolicy(inventory)).toMatchObject({
|
||||
retainedRoles: 9,
|
||||
retainedScenarios: 7,
|
||||
retainedRoles: 10,
|
||||
retainedScenarios: 8,
|
||||
})
|
||||
})
|
||||
+12
-9
@@ -1,7 +1,7 @@
|
||||
/**
|
||||
* AST helpers for the client slot surface: the `SlotMap` declaration merges
|
||||
* that type every slot, and the `slots.register` call sites that say who
|
||||
* already occupies one. Both readings are lexical (no type-checker program):
|
||||
* that type every slot, and the `slots.register` / `slots.registerFactory`
|
||||
* call sites that say who occupies or declares one. Both readings are lexical:
|
||||
* the client catalog generator consumes them, and the same scan doubles as its
|
||||
* own exhaustiveness backstop because it reads every source file rather than a
|
||||
* reachable-export closure.
|
||||
@@ -17,8 +17,8 @@ const SLOTS_MODULE = '@deepseek-ai/dsh-client-ui-slots'
|
||||
/** Cheap textual prefilter for a slot-contract merge, quote-style agnostic. */
|
||||
const MERGE_HEAD = /declare module ['"]@deepseek-ai\/dsh-client-ui-slots['"]/
|
||||
|
||||
/** Cheap textual prefilter for a registration call site. */
|
||||
const REGISTER_HEAD = /\.register\(/
|
||||
/** Cheap textual prefilter for a Slot or Factory registration call site. */
|
||||
const REGISTER_HEAD = /\.(?:register|registerFactory)\(/
|
||||
|
||||
/** One `SlotMap` member: the slot's contract as its owning package declares it. */
|
||||
export interface SlotDeclaration {
|
||||
@@ -44,7 +44,7 @@ export interface SlotDeclaration {
|
||||
source: string
|
||||
}
|
||||
|
||||
/** One `slots.register({ name, … }, Component)` call site. */
|
||||
/** One `slots.register()` or `slots.registerFactory()` call site. */
|
||||
export interface SlotRegistration {
|
||||
/** Target SlotMap key the entry contributes into. */
|
||||
key: string
|
||||
@@ -58,6 +58,8 @@ export interface SlotRegistration {
|
||||
entryKey?: string
|
||||
/** SlotMap keys this registration declares as children (they exist while it is mounted). */
|
||||
children: string[]
|
||||
/** Whether this call installs a Factory definition instead of occupying an ordinary Slot. */
|
||||
factory?: boolean
|
||||
/** Source pointer `packages/…/file.ts:line`. */
|
||||
source: string
|
||||
}
|
||||
@@ -183,9 +185,9 @@ export function slotDeclarations(file: ScannedFile): SlotDeclaration[] {
|
||||
}
|
||||
|
||||
/**
|
||||
* Read every registration call site in one scanned file: which slot it
|
||||
* occupies, with which component and cell identity, and which child slots it
|
||||
* declares. A call whose `name` is not a string literal is skipped — the
|
||||
* Read every Slot or Factory registration call site in one scanned file: which
|
||||
* name it targets, with which component and cell identity, and which ordinary
|
||||
* child slots it declares. A call whose `name` is not a string literal is skipped — the
|
||||
* shipped composition always names its target literally, and a computed name
|
||||
* carries no catalog fact.
|
||||
* @param file - a file returned by {@link scanSlotFiles}.
|
||||
@@ -196,7 +198,7 @@ export function slotRegistrations(file: ScannedFile): SlotRegistration[] {
|
||||
const visit = (node: ts.Node): void => {
|
||||
if (ts.isCallExpression(node)
|
||||
&& ts.isPropertyAccessExpression(node.expression)
|
||||
&& node.expression.name.text === 'register'
|
||||
&& (node.expression.name.text === 'register' || node.expression.name.text === 'registerFactory')
|
||||
&& isSlotsReceiver(node.expression.expression, file.sf)
|
||||
&& node.arguments.length >= 1) {
|
||||
const options = node.arguments[0]
|
||||
@@ -209,6 +211,7 @@ export function slotRegistrations(file: ScannedFile): SlotRegistration[] {
|
||||
key,
|
||||
package: file.package,
|
||||
component: componentText(node.arguments[1], file.sf),
|
||||
...node.expression.name.text === 'registerFactory' ? { factory: true } : {},
|
||||
...id === undefined ? {} : { id },
|
||||
...entryKey === undefined ? {} : { entryKey },
|
||||
children: childKeys(options),
|
||||
|
||||
+213
-124
@@ -19,6 +19,7 @@ import sysconfig
|
||||
import tempfile
|
||||
import threading
|
||||
import time
|
||||
import zipfile
|
||||
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
|
||||
from pathlib import Path
|
||||
from typing import TYPE_CHECKING, Callable
|
||||
@@ -99,24 +100,6 @@ RESTART_SECOND_PROMPT = "Complete the second isolated Python SDK process turn."
|
||||
RESTART_SECOND_TEXT = "PROCESS_TWO_OK"
|
||||
RESTART_FIRST_SESSION_ID = "process-one"
|
||||
RESTART_SECOND_SESSION_ID = "process-two"
|
||||
SNAPSHOT_PLUGIN_CODE = """\
|
||||
return (ctx) => {
|
||||
harness.registerTool(ctx, harness.defineTool({
|
||||
name: 'snapshot_double',
|
||||
description: 'Double a number for executable snapshot verification.',
|
||||
parameters: { value: { type: 'number', required: true } },
|
||||
output: {
|
||||
schema: { type: 'number' },
|
||||
render(_args, value) {
|
||||
return [{ type: 'text', text: String(value) }]
|
||||
}
|
||||
},
|
||||
async execute(args) {
|
||||
return args.value * 2
|
||||
}
|
||||
}))
|
||||
}
|
||||
"""
|
||||
SNAPSHOT_WORKFLOW_SCRIPT = (
|
||||
"phase('Delegate')\n"
|
||||
f"const reply = await agent('{SNAPSHOT_WORKFLOW_CHILD_PROMPT}', {{ label: 'workflow-child' }})\n"
|
||||
@@ -264,7 +247,7 @@ def write_advanced_profile_patch(root: Path, name: str, sessions: Path) -> Path:
|
||||
},
|
||||
},
|
||||
{"insert": [
|
||||
{"id": "code-runtime", "name": "@deepseek-ai/dsh-code-runtime-worker-thread"},
|
||||
{"id": "ptc-runtime", "name": "@deepseek-ai/dsh-ptc-runtime-node"},
|
||||
{"id": "cordis-host-runner", "name": "@deepseek-ai/dsh-cordis-host-runner"},
|
||||
{"id": "cordis-tool", "name": "@deepseek-ai/dsh-tool-cordis"},
|
||||
]},
|
||||
@@ -296,6 +279,9 @@ class MockModelHandler(BaseHTTPRequestHandler):
|
||||
requests: list[dict[str, object]] = []
|
||||
|
||||
def do_POST(self) -> None:
|
||||
if self.path != "/v1/messages":
|
||||
self.send_error(404)
|
||||
return
|
||||
content_length = int(self.headers.get("content-length", "0"))
|
||||
body = json.loads(self.rfile.read(content_length))
|
||||
self.requests.append(body)
|
||||
@@ -304,8 +290,7 @@ class MockModelHandler(BaseHTTPRequestHandler):
|
||||
self.end_headers()
|
||||
chunks = completion_chunks(body)
|
||||
for chunk in chunks:
|
||||
self.wfile.write(f"data: {json.dumps(chunk)}\n\n".encode())
|
||||
self.wfile.write(b"data: [DONE]\n\n")
|
||||
self.wfile.write(f"event: {chunk['type']}\ndata: {json.dumps(chunk)}\n\n".encode())
|
||||
self.wfile.flush()
|
||||
|
||||
def log_message(self, _format: str, *_args: object) -> None:
|
||||
@@ -322,9 +307,14 @@ def completion_chunks(body: dict[str, object]) -> list[dict[str, object]]:
|
||||
if not isinstance(latest, dict):
|
||||
raise AssertionError(f"model request has an invalid latest message: {body}")
|
||||
|
||||
if latest.get("role") == "tool":
|
||||
call_id, tool_name = latest_tool_call(messages)
|
||||
tool_text = message_text(latest.get("content"))
|
||||
tool_results = [
|
||||
block for block in latest.get("content", [])
|
||||
if isinstance(block, dict) and block.get("type") == "tool_result"
|
||||
]
|
||||
if tool_results:
|
||||
result = tool_results[-1]
|
||||
call_id, tool_name = latest_tool_call(messages, result.get("tool_use_id"))
|
||||
tool_text = message_text(result.get("content"))
|
||||
mcp = mcp_tool_followup(call_id, tool_name, tool_text)
|
||||
if mcp is not None:
|
||||
return mcp
|
||||
@@ -349,9 +339,11 @@ def completion_chunks(body: dict[str, object]) -> list[dict[str, object]]:
|
||||
raise AssertionError(f"unexpected tool follow-up: {tool_name}")
|
||||
|
||||
user_prompts = [
|
||||
message_text(message.get("content"))
|
||||
block["text"]
|
||||
for message in reversed(messages)
|
||||
if isinstance(message, dict) and message.get("role") == "user"
|
||||
for block in message.get("content", [])
|
||||
if isinstance(block, dict) and block.get("type") == "text"
|
||||
]
|
||||
minimal_prompt = next((prompt for prompt in user_prompts if prompt == MINIMAL_PROMPT), None)
|
||||
# The minimal composition's assembled system prompt, advertised tool schemas, and
|
||||
@@ -384,16 +376,12 @@ def completion_chunks(body: dict[str, object]) -> list[dict[str, object]]:
|
||||
if prompt == SNAPSHOT_WORKFLOW_CHILD_PROMPT:
|
||||
return text_chunks("WORKFLOW_CHILD_OK")
|
||||
if prompt == SNAPSHOT_PROMPT:
|
||||
assert_advertised_tool(body, "cordis_define")
|
||||
assert_advertised_tool(body, "snapshot_double")
|
||||
assert_advertised_tool(body, "run_code")
|
||||
return tool_call_chunks(
|
||||
"advanced-define",
|
||||
"cordis_define",
|
||||
{
|
||||
"plugin": {"kind": "new", "idPrefix": "snap"},
|
||||
"name": "Snapshot Double",
|
||||
"purpose": "Expose a deterministic doubling tool for executable snapshot verification.",
|
||||
"code": {"host": SNAPSHOT_PLUGIN_CODE},
|
||||
},
|
||||
"advanced-code", "run_code",
|
||||
{"code": "return await tools.snapshot_double({ value: 21 })",
|
||||
"description": "Call the configured Plugin tool"},
|
||||
)
|
||||
if prompt == RESTART_FIRST_PROMPT:
|
||||
return text_chunks(RESTART_FIRST_TEXT)
|
||||
@@ -448,7 +436,7 @@ def completion_chunks(body: dict[str, object]) -> list[dict[str, object]]:
|
||||
{"a": 19, "b": 23},
|
||||
)
|
||||
if prompt == PROFILE_PLUGIN_PROMPT:
|
||||
system_text = "\n".join(
|
||||
system_text = message_text(body.get("system")) + "\n" + "\n".join(
|
||||
message_text(message.get("content"))
|
||||
for message in messages
|
||||
if isinstance(message, dict) and message.get("role") == "system"
|
||||
@@ -558,33 +546,24 @@ def advanced_tool_followup(
|
||||
"""Advance the executable snapshot's deterministic parent tool chain."""
|
||||
if not call_id.startswith("advanced-"):
|
||||
return None
|
||||
if call_id == "advanced-define" and tool_name == "cordis_define":
|
||||
if "Defined snap-1/pkg-1 (Snapshot Double)" not in tool_text:
|
||||
raise AssertionError(f"cordis_define returned no dynamic Package ids: {tool_text}")
|
||||
if "snapshot_double" in advertised_tool_names(body):
|
||||
raise AssertionError("snapshot_double was advertised before cordis_run")
|
||||
assert_advertised_tool(body, "cordis_run")
|
||||
return tool_call_chunks(
|
||||
"advanced-run",
|
||||
"cordis_run",
|
||||
{"pluginId": "snap-1", "packageId": "pkg-1", "mode": "run"},
|
||||
)
|
||||
if call_id == "advanced-run" and tool_name == "cordis_run":
|
||||
if "snap-1/pkg-1 is running (run-1)" not in tool_text:
|
||||
raise AssertionError(f"cordis_run returned no running Package ids: {tool_text}")
|
||||
assert_advertised_tool(body, "run_code")
|
||||
assert_advertised_tool(body, "snapshot_double")
|
||||
return tool_call_chunks(
|
||||
"advanced-code",
|
||||
"run_code",
|
||||
{
|
||||
"code": "return await tools.snapshot_double({ value: 21 })",
|
||||
"description": "Run the temporary Plugin tool",
|
||||
},
|
||||
)
|
||||
if call_id == "advanced-code" and tool_name == "run_code":
|
||||
if "42" not in tool_text:
|
||||
raise AssertionError(f"run_code returned no dynamic-tool value: {tool_text}")
|
||||
raise AssertionError(f"run_code returned no configured-tool value: {tool_text}")
|
||||
return tool_call_chunks("advanced-denied-native", "snapshot_double", {"value": -1})
|
||||
if call_id == "advanced-denied-native" and tool_name == "snapshot_double":
|
||||
if 'Auto review rejected tool "snapshot_double"; its body was not executed' not in tool_text:
|
||||
raise AssertionError(f"native denial did not preserve the model result: {tool_text}")
|
||||
if "transport raw" in tool_text:
|
||||
raise AssertionError("native denial leaked its user-facing reason to the model")
|
||||
return tool_call_chunks("advanced-denied-ptc", "run_code", {
|
||||
"code": "try { await tools.snapshot_double({ value: -1 }) } catch (error) { return error.message }",
|
||||
"description": "Catch a structured inner tool denial",
|
||||
})
|
||||
if call_id == "advanced-denied-ptc" and tool_name == "run_code":
|
||||
if 'Auto review rejected tool "snapshot_double"; its body was not executed' not in tool_text:
|
||||
raise AssertionError(f"PTC denial did not preserve the model result: {tool_text}")
|
||||
if "transport raw" in tool_text:
|
||||
raise AssertionError("PTC denial leaked its user-facing reason to the model")
|
||||
assert_advertised_tool(body, "subagent")
|
||||
return tool_call_chunks(
|
||||
"advanced-direct-child",
|
||||
@@ -612,80 +591,72 @@ def advanced_tool_followup(
|
||||
if call_id == "advanced-workflow" and tool_name == "workflow":
|
||||
if "WORKFLOW_CHILD_OK" not in tool_text:
|
||||
raise AssertionError(f"workflow returned no expected child value: {tool_text}")
|
||||
assert_advertised_tool(body, "cordis_undefine")
|
||||
return tool_call_chunks(
|
||||
"advanced-undefine",
|
||||
"cordis_undefine",
|
||||
{"pluginId": "snap-1"},
|
||||
)
|
||||
if call_id == "advanced-undefine" and tool_name == "cordis_undefine":
|
||||
if "Removed dynamic Plugin snap-1 and all of its Packages." not in tool_text:
|
||||
raise AssertionError(f"cordis_undefine returned no removal result: {tool_text}")
|
||||
if "snapshot_double" in advertised_tool_names(body):
|
||||
raise AssertionError("snapshot_double remained advertised after cordis_undefine")
|
||||
return text_chunks(SNAPSHOT_FINAL_TEXT)
|
||||
raise AssertionError(f"unexpected advanced tool follow-up: {call_id} {tool_name}: {tool_text}")
|
||||
|
||||
|
||||
def text_chunks(text: str) -> list[dict[str, object]]:
|
||||
"""Build a complete streaming text response."""
|
||||
"""Build a complete Messages text response."""
|
||||
return [
|
||||
{"choices": [{"delta": {"role": "assistant", "content": None, "reasoning_content": ""}}]},
|
||||
{"choices": [{"delta": {"content": text}}]},
|
||||
{
|
||||
"choices": [{"delta": {"content": ""}, "finish_reason": "stop"}],
|
||||
"usage": {"prompt_tokens": 3, "completion_tokens": 3},
|
||||
},
|
||||
message_start(),
|
||||
{"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}},
|
||||
{"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": text}},
|
||||
{"type": "content_block_stop", "index": 0},
|
||||
{"type": "message_delta", "delta": {"stop_reason": "end_turn"}, "usage": {"output_tokens": 3}},
|
||||
{"type": "message_stop"},
|
||||
]
|
||||
|
||||
|
||||
def tool_call_chunks(call_id: str, name: str, arguments: dict[str, object]) -> list[dict[str, object]]:
|
||||
"""Build a complete streaming function-call response."""
|
||||
"""Build a complete Messages tool-use response."""
|
||||
return [
|
||||
{"choices": [{"delta": {"role": "assistant", "content": None, "reasoning_content": ""}}]},
|
||||
message_start(),
|
||||
{
|
||||
"choices": [{
|
||||
"delta": {
|
||||
"tool_calls": [{
|
||||
"index": 0,
|
||||
"id": call_id,
|
||||
"type": "function",
|
||||
"function": {"name": name, "arguments": json.dumps(arguments)},
|
||||
}],
|
||||
},
|
||||
}],
|
||||
"type": "content_block_start", "index": 0,
|
||||
"content_block": {"type": "tool_use", "id": call_id, "name": name, "input": {}},
|
||||
},
|
||||
{
|
||||
"choices": [{"delta": {"content": ""}, "finish_reason": "tool_calls"}],
|
||||
"usage": {"prompt_tokens": 3, "completion_tokens": 3},
|
||||
"type": "content_block_delta", "index": 0,
|
||||
"delta": {"type": "input_json_delta", "partial_json": json.dumps(arguments)},
|
||||
},
|
||||
{"type": "content_block_stop", "index": 0},
|
||||
{"type": "message_delta", "delta": {"stop_reason": "tool_use"}, "usage": {"output_tokens": 3}},
|
||||
{"type": "message_stop"},
|
||||
]
|
||||
|
||||
|
||||
def latest_tool_call(messages: list[object]) -> tuple[str, str]:
|
||||
def message_start() -> dict[str, object]:
|
||||
"""Start a Messages response with deterministic token usage."""
|
||||
return {
|
||||
"type": "message_start",
|
||||
"message": {"id": "msg_smoke", "model": "smoke-model", "usage": {"input_tokens": 3, "output_tokens": 0}},
|
||||
}
|
||||
|
||||
|
||||
def latest_tool_call(messages: list[object], result_id: object) -> tuple[str, str]:
|
||||
"""Find the assistant call id and name paired with the latest tool result."""
|
||||
for message in reversed(messages[:-1]):
|
||||
if not isinstance(message, dict):
|
||||
continue
|
||||
calls = message.get("tool_calls")
|
||||
calls = message.get("content")
|
||||
if not isinstance(calls, list):
|
||||
continue
|
||||
for call in reversed(calls):
|
||||
if not isinstance(call, dict):
|
||||
continue
|
||||
function = call.get("function")
|
||||
call_id = call.get("id")
|
||||
if (
|
||||
isinstance(call_id, str)
|
||||
and isinstance(function, dict)
|
||||
and isinstance(function.get("name"), str)
|
||||
and call_id == result_id
|
||||
and call.get("type") == "tool_use"
|
||||
and isinstance(call.get("name"), str)
|
||||
):
|
||||
return call_id, function["name"]
|
||||
return call_id, call["name"]
|
||||
raise AssertionError(f"tool result has no preceding assistant tool call: {messages}")
|
||||
|
||||
|
||||
def message_text(content: object) -> str:
|
||||
"""Read OpenAI text content in either string or block-list form."""
|
||||
"""Read Messages text content in either string or block-list form."""
|
||||
if isinstance(content, str):
|
||||
return content
|
||||
if isinstance(content, list):
|
||||
@@ -706,9 +677,8 @@ def advertised_tool_names(body: dict[str, object]) -> set[str]:
|
||||
for tool in tools:
|
||||
if not isinstance(tool, dict):
|
||||
continue
|
||||
function = tool.get("function")
|
||||
if isinstance(function, dict) and isinstance(function.get("name"), str):
|
||||
names.add(function["name"])
|
||||
if isinstance(tool.get("name"), str):
|
||||
names.add(tool["name"])
|
||||
return names
|
||||
|
||||
|
||||
@@ -739,7 +709,7 @@ def main() -> None:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument(
|
||||
"--scenario",
|
||||
choices=("all", "sdk-default", "sdk-custom", "sdk-minimal", "sdk-minimal-in-history", "sdk-fs-search", "sdk-spawn-node", "sdk-mcp", "sdk-snapshot", "sdk-restart", "sdk-profile-plugin", "sdk-live", "runner", "direct"),
|
||||
choices=("all", "sdk-default", "sdk-custom", "sdk-minimal", "sdk-minimal-in-history", "sdk-fs-search", "sdk-spawn-node", "sdk-mcp", "sdk-snapshot", "sdk-restart", "sdk-profile-plugin", "sdk-office", "sdk-live", "runner", "direct"),
|
||||
default="all",
|
||||
)
|
||||
parser.add_argument("--exe", type=Path)
|
||||
@@ -758,13 +728,20 @@ def main() -> None:
|
||||
parser.error("--scenario sdk-profile-plugin requires --installed-wheel")
|
||||
if args.installed_wheel:
|
||||
args.exe = assert_installed_wheel_environment()
|
||||
if args.scenario in {"all", "sdk-custom", "sdk-minimal", "sdk-minimal-in-history", "sdk-fs-search", "sdk-spawn-node", "sdk-snapshot", "sdk-restart", "runner", "direct"} and args.exe is None:
|
||||
parser.error("--exe is required for custom, minimal, fs-search, spawn-node, snapshot, restart, runner, and direct scenarios")
|
||||
if args.scenario in {"all", "sdk-custom", "sdk-minimal", "sdk-minimal-in-history", "sdk-fs-search", "sdk-spawn-node", "sdk-snapshot", "sdk-restart", "sdk-office", "runner", "direct"} and args.exe is None:
|
||||
parser.error("--exe is required for custom, minimal, fs-search, spawn-node, snapshot, restart, office, runner, and direct scenarios")
|
||||
if args.update_snapshots and args.scenario not in {"all", "sdk-minimal", "sdk-minimal-in-history", "sdk-snapshot", "sdk-restart"}:
|
||||
parser.error("--update-snapshots requires --scenario sdk-minimal, sdk-minimal-in-history, sdk-snapshot, sdk-restart, or all")
|
||||
if args.exe is not None and not args.exe.is_file():
|
||||
parser.error(f"runtime executable does not exist: {args.exe}")
|
||||
|
||||
if args.scenario in {"all", "sdk-office"}:
|
||||
assert args.exe is not None
|
||||
smoke_sdk_office(args.exe.resolve())
|
||||
if args.scenario == "sdk-office":
|
||||
print("smoke-python-runtime: sdk-office passed")
|
||||
return
|
||||
|
||||
if args.scenario in {"all", "runner"}:
|
||||
assert args.exe is not None
|
||||
smoke_packaged_runner(args.exe.resolve())
|
||||
@@ -813,6 +790,73 @@ def main() -> None:
|
||||
print(f"smoke-python-runtime: {args.scenario} passed")
|
||||
|
||||
|
||||
def smoke_sdk_office(executable: Path) -> None:
|
||||
"""Relocate the wheel payload and convert a real DOCX with the target platform engine."""
|
||||
from deepseek_harness import DeepSeekHarness
|
||||
|
||||
with tempfile.TemporaryDirectory(prefix="dsh-sdk-office-") as temporary:
|
||||
root = Path(temporary).resolve()
|
||||
relocated = root / executable.name
|
||||
stem = executable.name.removesuffix(".exe")
|
||||
for source in executable.parent.glob(f"{stem}*"):
|
||||
destination = root / source.name
|
||||
if source.is_dir():
|
||||
shutil.copytree(source, destination)
|
||||
else:
|
||||
shutil.copy2(source, destination)
|
||||
office = root / f"{stem}-office"
|
||||
adapter = office / "node_modules/@deepseek-ai/libreoffice-kit/package.json"
|
||||
native = stem.removeprefix("deepseek-harness-sdk-runtime-").replace("win-", "win32-").replace("macos-", "darwin-")
|
||||
declared = json.loads(adapter.read_text(encoding="utf-8")).get("optionalDependencies", {})
|
||||
selected = native if f"@deepseek-ai/libreoffice-kit-{native}" in declared else "wasm"
|
||||
expected_backend = "wasm" if selected == "wasm" else "native"
|
||||
engines = [
|
||||
json.loads(manifest.read_text())["engine"]["kind"]
|
||||
for manifest in (office / "node_modules/@deepseek-ai").glob("libreoffice-kit-*/prebuilds.json")
|
||||
]
|
||||
if engines != [expected_backend]:
|
||||
raise AssertionError(f"Office sidecar must contain only {expected_backend}: {engines}")
|
||||
plugin = root / "office.mjs"
|
||||
shutil.copy2(Path(__file__).resolve().parent / "fixtures/python-sdk-office.mjs", plugin)
|
||||
document = root / "document.docx"
|
||||
with zipfile.ZipFile(document, "w", compression=zipfile.ZIP_DEFLATED) as archive:
|
||||
archive.writestr("[Content_Types].xml", '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/></Types>')
|
||||
archive.writestr("_rels/.rels", '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>')
|
||||
archive.writestr("word/document.xml", '<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body><w:p><w:r><w:t>Python Office wheel</w:t></w:r></w:p><w:sectPr><w:pgSz w:w="12240" w:h="15840"/></w:sectPr></w:body></w:document>')
|
||||
|
||||
mode = expected_backend
|
||||
output = root / f"{mode}.pdf"
|
||||
result_path = root / f"{mode}.json"
|
||||
patch = root / f"{mode}.patch.yml"
|
||||
patch.write_text(json.dumps([{"insert": [{
|
||||
"id": "python-sdk-office-smoke",
|
||||
"name": plugin.as_uri(),
|
||||
"config": {"input": str(document), "output": str(output), "result": str(result_path)},
|
||||
}]}]))
|
||||
with DeepSeekHarness(
|
||||
provider="deepseek-official",
|
||||
model="smoke-model",
|
||||
cwd=str(root),
|
||||
dsh_bin=str(relocated),
|
||||
dsh_home=str(root / f"home-{mode}"),
|
||||
patches=(str(patch),),
|
||||
api_key="sk-keyless-smoke",
|
||||
base_url="http://127.0.0.1:9",
|
||||
env={"DSH_PERMISSION_MODE": "danger-full-access", "DSH_TELEMETRY_DISABLED": "1"},
|
||||
request_timeout_seconds=180,
|
||||
):
|
||||
pass
|
||||
result = json.loads(result_path.read_text())
|
||||
if result["backend"] != expected_backend:
|
||||
raise AssertionError(f"Office conversion did not use {expected_backend}: {result}")
|
||||
if not result["moduleUrl"].startswith(office.as_uri() + "/"):
|
||||
raise AssertionError(f"Office module was not loaded from the relocated wheel: {result}")
|
||||
pdf = output.read_bytes()
|
||||
if len(pdf) < 100 or not pdf.startswith(b"%PDF-"):
|
||||
raise AssertionError(f"Office conversion produced an invalid PDF at {output}")
|
||||
print(f"smoke-python-runtime: relocated Office {result['backend']} DOCX produced {len(pdf)} PDF bytes")
|
||||
|
||||
|
||||
def assert_installed_wheel_environment() -> Path:
|
||||
"""Prove that this process imports matching non-editable wheel installations."""
|
||||
if sys.prefix == sys.base_prefix:
|
||||
@@ -918,6 +962,8 @@ def smoke_sdk_live() -> None:
|
||||
"Use a tool to read that same file and copy its exact current content to the "
|
||||
"new receipt path below, without changing the source file. "
|
||||
"Preserve every byte; do not add a newline or byte-order mark. "
|
||||
f"{LIVE_API_SENTINEL} is only the completion acknowledgement, "
|
||||
"not a claim about the source or receipt contents. "
|
||||
f"Then reply with exactly {LIVE_API_SENTINEL}.\n{receipt}"
|
||||
)
|
||||
verified = harness.run(verify_prompt, session_id=session_id)
|
||||
@@ -932,7 +978,7 @@ def smoke_sdk_live() -> None:
|
||||
|
||||
|
||||
def assert_live_turn(label: str, result: RunResult) -> None:
|
||||
"""Require completed model tool use and the exact smoke answer for each live turn."""
|
||||
"""Require completed model tool use and the smoke sentinel on the final answer line."""
|
||||
if result.finish_reason != "completed":
|
||||
event_types = [event.get("type") for event in result.events]
|
||||
turn_end_data = next(
|
||||
@@ -949,7 +995,8 @@ def assert_live_turn(label: str, result: RunResult) -> None:
|
||||
f"{label} turn made no model-requested tool call; "
|
||||
f"final={result.final_response!r}"
|
||||
)
|
||||
if result.final_response.strip() != LIVE_API_SENTINEL:
|
||||
answer_lines = result.final_response.strip().splitlines()
|
||||
if not answer_lines or answer_lines[-1].strip() != LIVE_API_SENTINEL:
|
||||
raise AssertionError(f"{label} turn returned {result.final_response!r}")
|
||||
|
||||
def safe_turn_end(value: object) -> object:
|
||||
@@ -1190,6 +1237,7 @@ def smoke_sdk_mcp(base_url: str, executable: Path | None) -> None:
|
||||
|
||||
assert result.final_response == MCP_TEXT, result.final_response
|
||||
assert discovery_log.read_text().splitlines() == [
|
||||
"server/discover",
|
||||
"initialize",
|
||||
"notifications/initialized",
|
||||
"tools/list",
|
||||
@@ -1290,6 +1338,12 @@ def smoke_sdk_snapshot(base_url: str, executable: Path, update_snapshots: bool)
|
||||
sessions = dsh_home / "sessions"
|
||||
patch = write_advanced_profile_patch(root, "snapshot.patch.yml", sessions)
|
||||
feedback_patch = write_profile_patch(root, "feedback.patch.yml", sessions, [{"insert": [
|
||||
{"id": "snapshot-tool", "name": (
|
||||
Path(__file__).resolve().parent / "fixtures/python-snapshot-tool.mjs"
|
||||
).as_uri()},
|
||||
{"id": "snapshot-image-offload", "name": (
|
||||
Path(__file__).resolve().parent / "fixtures/python-snapshot-image-offload.mjs"
|
||||
).as_uri(), "config": {"parentSessionId": SNAPSHOT_SESSION_ID}},
|
||||
{"id": "snapshot-workflow-order", "name": (
|
||||
Path(__file__).resolve().parent / "fixtures/python-snapshot-workflow-order.mjs"
|
||||
).as_uri(), "config": {
|
||||
@@ -1301,13 +1355,19 @@ def smoke_sdk_snapshot(base_url: str, executable: Path, update_snapshots: bool)
|
||||
Path(__file__).resolve().parent.parent / "snapshots/sdk/text-turn/feedback-producer.mjs"
|
||||
).as_uri()},
|
||||
]}])
|
||||
creation_patch = write_profile_patch(root, "creation.patch.yml", sessions, [
|
||||
{"insert": [{
|
||||
"id": "serial-created-fixture",
|
||||
"name": str(Path(__file__).resolve().parents[1] / "packages/core/agent-loop/tests/fixtures/serial-created.mjs"),
|
||||
}]},
|
||||
])
|
||||
with DeepSeekHarness(
|
||||
provider="deepseek-official",
|
||||
model="smoke-model",
|
||||
cwd=str(root),
|
||||
dsh_bin=str(executable),
|
||||
dsh_home=str(dsh_home),
|
||||
patches=(str(patch), str(feedback_patch)),
|
||||
patches=(str(patch), str(feedback_patch), str(creation_patch)),
|
||||
env={
|
||||
"DSH_PERMISSION_MODE": "danger-full-access",
|
||||
"DSH_TELEMETRY_DISABLED": "1",
|
||||
@@ -1319,6 +1379,12 @@ def smoke_sdk_snapshot(base_url: str, executable: Path, update_snapshots: bool)
|
||||
result = harness.run(SNAPSHOT_PROMPT, session_id=SNAPSHOT_SESSION_ID)
|
||||
|
||||
assert result.final_response == SNAPSHOT_FINAL_TEXT, result.final_response
|
||||
offloads = [event for event in result.events if event.get("type") == "image/offload"]
|
||||
if len(offloads) != 1 or "surfaceOp" in offloads[0]:
|
||||
raise AssertionError(f"advanced snapshot expected one standalone image offload: {offloads}")
|
||||
targets = offloads[0]["data"]["targets"]
|
||||
if len(targets) != 1 or targets[0]["imageIndexes"] != [0]:
|
||||
raise AssertionError(f"advanced snapshot selected unexpected image occurrences: {targets}")
|
||||
feedback_types = [event.get("type") for event in result.events
|
||||
if str(event.get("type")).startswith("feedback/")]
|
||||
if feedback_types != ["feedback/record", "feedback/record", "feedback/message-put", "feedback/message-put", "feedback/message-delete"]:
|
||||
@@ -1328,13 +1394,21 @@ def smoke_sdk_snapshot(base_url: str, executable: Path, update_snapshots: bool)
|
||||
raise AssertionError(f"advanced snapshot emitted unexpected subagent lifecycle: {methods}")
|
||||
ptc_events = [event for event in result.events
|
||||
if event.get("type") in ("tool/ptc-dispatch-start", "tool/ptc-dispatch")]
|
||||
if [event["type"] for event in ptc_events] != ["tool/ptc-dispatch-start", "tool/ptc-dispatch"]:
|
||||
if [event["type"] for event in ptc_events] != ["tool/ptc-dispatch-start", "tool/ptc-dispatch"] * 2:
|
||||
raise AssertionError(f"advanced snapshot emitted unexpected PTC dispatch events: {ptc_events}")
|
||||
for event in ptc_events:
|
||||
for index, event in enumerate(ptc_events):
|
||||
data = event["data"]
|
||||
identity = (data.get("rootCallId"), data.get("parentCallId"), data.get("subCallId"))
|
||||
if identity != ("advanced-code", "advanced-code", "advanced-code:ptc:1"):
|
||||
root_call = "advanced-code" if index < 2 else "advanced-denied-ptc"
|
||||
if identity != (root_call, root_call, root_call + ":ptc:1"):
|
||||
raise AssertionError(f"advanced snapshot emitted unexpected PTC dispatch identity: {identity}")
|
||||
if {"description", "parameters", "schema"}.intersection(data):
|
||||
raise AssertionError("PTC binding schema entered the packaged SDK wire")
|
||||
errors = [event["data"]["error"] for event in result.events
|
||||
if event.get("type") in ("tool/result", "tool/ptc-dispatch") and "error" in event["data"]]
|
||||
assert errors == [{
|
||||
"name": "AutoReviewDeniedError", "code": "AUTO_REVIEW_DENIED", "reason": " transport raw\r\nreason ",
|
||||
}] * 2, errors
|
||||
|
||||
logs = read_session_logs(sessions)
|
||||
child_ids = snapshot_child_ids(result)
|
||||
@@ -1841,13 +1915,18 @@ def build_in_history_snapshot_files(
|
||||
request_prompts = []
|
||||
for index, request in enumerate(requests):
|
||||
messages = request["messages"]
|
||||
assert messages[0]["role"] == "system" and message_text(messages[0]["content"]) == prompts[0]
|
||||
assert message_text(request.get("system")) == prompts[0]
|
||||
assert request["tools"] == requests[0]["tools"], "prompt update changed tool schemas"
|
||||
positions = [position for position, message in enumerate(messages) if message["role"] == "system"]
|
||||
texts = [message_text(messages[position]["content"]) for position in positions]
|
||||
texts = [message_text(request["system"]), *[
|
||||
message_text(messages[position]["content"]) for position in positions
|
||||
]]
|
||||
assert texts == (prompts[:1] if index == 0 else prompts), texts
|
||||
if index > 0:
|
||||
assert messages[positions[1] - 1]["role"] == "tool", messages
|
||||
previous = messages[positions[0] - 1]
|
||||
assert previous["role"] == "user" and any(
|
||||
block.get("type") == "tool_result" for block in previous["content"]
|
||||
), messages
|
||||
request_prompts.append(texts)
|
||||
evidence = {
|
||||
"requestSystemPrompts": request_prompts,
|
||||
@@ -1877,6 +1956,7 @@ def build_minimal_snapshot_files(
|
||||
if not isinstance(messages, list):
|
||||
raise AssertionError(f"minimal model request has no messages: {body}")
|
||||
snapshot.append({
|
||||
"system": minimal_snapshot_text(body.get("system"), cwd),
|
||||
"tools": minimal_snapshot_text(body.get("tools"), cwd),
|
||||
"messages": [
|
||||
minimal_snapshot_message(message, cwd)
|
||||
@@ -1891,22 +1971,30 @@ def minimal_snapshot_message(message: object, cwd: Path) -> dict[str, object]:
|
||||
if not isinstance(message, dict):
|
||||
raise AssertionError(f"minimal model request has an invalid message: {message}")
|
||||
role = message.get("role")
|
||||
if role in ("system", "user"):
|
||||
if role == "system":
|
||||
return {"role": role, "text": minimal_snapshot_text(message_text(message.get("content")), cwd)}
|
||||
if role == "user":
|
||||
content = []
|
||||
for block in message.get("content", []):
|
||||
if block.get("type") == "tool_result":
|
||||
content.append({"type": "tool_result", "tool_use_id": block.get("tool_use_id"), "content": "{{tool-result}}"})
|
||||
elif block.get("type") == "text":
|
||||
content.append(minimal_snapshot_text(block, cwd))
|
||||
else:
|
||||
raise AssertionError(f"minimal user message has unexpected content: {block}")
|
||||
return {"role": role, "content": content}
|
||||
if role == "assistant":
|
||||
calls = message.get("tool_calls")
|
||||
calls = message.get("content")
|
||||
if not isinstance(calls, list):
|
||||
raise AssertionError(f"minimal assistant message has no tool calls: {message}")
|
||||
return {
|
||||
"role": role,
|
||||
"toolCalls": [
|
||||
{"id": call.get("id"), "name": (call.get("function") or {}).get("name")}
|
||||
{"id": call.get("id"), "name": call.get("name")}
|
||||
for call in calls
|
||||
if isinstance(call, dict)
|
||||
if isinstance(call, dict) and call.get("type") == "tool_use"
|
||||
],
|
||||
}
|
||||
if role == "tool":
|
||||
return {"role": role, "toolCallId": message.get("tool_call_id"), "text": "{{tool-result}}"}
|
||||
raise AssertionError(f"minimal model request has an unexpected message role: {message}")
|
||||
|
||||
|
||||
@@ -2024,6 +2112,7 @@ def build_restart_snapshot_files(
|
||||
request_value = [
|
||||
{
|
||||
"model": request.get("model"),
|
||||
"system": "{{system}}" if request.get("system") else None,
|
||||
"messages": restart_request_messages(request),
|
||||
"toolNames": sorted(advertised_tool_names(request)),
|
||||
}
|
||||
@@ -2202,7 +2291,7 @@ def project_session_snapshot(records: list[dict[str, object]]) -> list[dict[str,
|
||||
return projected
|
||||
|
||||
|
||||
SESSION_FORMAT_PROVENANCE = "{{sessionFormatVersion}}"
|
||||
SESSION_FORMAT_TOKEN = "{{sessionFormatVersion}}"
|
||||
|
||||
|
||||
def expand_snapshot_stream_member(member: object) -> list[dict[str, object]]:
|
||||
@@ -2291,7 +2380,7 @@ def normalize_session_format_comparison(
|
||||
value: object,
|
||||
source_session_version: int | None = None,
|
||||
) -> object:
|
||||
"""Canonicalize only generation provenance that differs across immutable Session files."""
|
||||
"""Canonicalize only generation metadata that differs across immutable Session files."""
|
||||
if isinstance(value, list):
|
||||
return [
|
||||
normalize_session_format_comparison(expanded, source_session_version)
|
||||
@@ -2306,7 +2395,7 @@ def normalize_session_format_comparison(
|
||||
for key, item in value.items()
|
||||
}
|
||||
if normalized.get("type") == "session" and "version" in normalized:
|
||||
normalized["version"] = SESSION_FORMAT_PROVENANCE
|
||||
normalized["version"] = SESSION_FORMAT_TOKEN
|
||||
normalized.setdefault("isSeeded", False)
|
||||
ordered_header = {
|
||||
key: normalized[key]
|
||||
@@ -2326,7 +2415,7 @@ def normalize_session_format_comparison(
|
||||
|
||||
|
||||
def normalize_snapshot_comparison_text(name: str, content: str) -> str:
|
||||
"""Normalize Session generation provenance only while comparing committed expected outputs."""
|
||||
"""Normalize Session generation metadata only while comparing committed expected outputs."""
|
||||
if name.startswith("session") and name.endswith(".jsonl"):
|
||||
parsed = [json.loads(line) for line in content.splitlines() if line]
|
||||
header = parsed[0] if parsed else None
|
||||
|
||||
@@ -23,16 +23,16 @@ it.skipIf(process.platform === 'win32')('translates only the exact fixture comma
|
||||
const fork = ctx.plugin(adapter, { command, recordedPath: '/fixture/recorded.txt', livePath })
|
||||
disposers.push(() => fork.dispose())
|
||||
await fork
|
||||
const outcome = await ctx.shell.execute(ctx.shell.resolve({ command })).result()
|
||||
const outcome = await (await ctx.shell.execute(ctx.shell.resolve({ command }))).result()
|
||||
expect(outcome.timedOut).toBe(false)
|
||||
expect(outcome.exitCode).toBe(0)
|
||||
expect(await readFile(livePath, 'utf8')).toBe('actual bytes')
|
||||
const untouched = await ctx.shell.execute(ctx.shell.resolve({ command: "printf '/fixture/recorded.txt'; exit 7" })).result()
|
||||
const untouched = await (await ctx.shell.execute(ctx.shell.resolve({ command: "printf '/fixture/recorded.txt'; exit 7" }))).result()
|
||||
expect(untouched.exitCode).toBe(7)
|
||||
expect(untouched.stdout.text).toBe('/fixture/recorded.txt')
|
||||
await fork.dispose()
|
||||
await rm(livePath)
|
||||
const restored = await ctx.shell.execute(ctx.shell.resolve({ command })).result()
|
||||
const restored = await (await ctx.shell.execute(ctx.shell.resolve({ command }))).result()
|
||||
expect(restored.exitCode).not.toBe(0)
|
||||
await expect(readFile(livePath)).rejects.toMatchObject({ code: 'ENOENT' })
|
||||
} finally {
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -2,18 +2,21 @@
|
||||
{"type":"sandbox/mode","data":{"mode":"danger-full-access","source":"delegation"}}
|
||||
{"type":"approval/policy","data":{"policy":"never","source":"delegation"}}
|
||||
{"type":"permission/preset","data":{"preset":"danger-full-access"}}
|
||||
{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"inserted":[{"id":"{{messageId}}","role":"user","content":[{"type":"text","text":"Serial agent creation completed."}],"source":{"kind":"plugin","plugin":"serial-created-fixture"}}]}}
|
||||
{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply with exactly DIRECT_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"}]}}
|
||||
{"type":"turn/start","data":{"turn":1}}
|
||||
{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"removedCount":1,"inserted":[]}}
|
||||
{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
|
||||
{"type":"subagent/descriptor","data":{"version":3,"mode":"one-shot","provider":"spawn","label":"Check direct child"}}
|
||||
{"type":"step/start","data":{"turn":1,"step":1}}
|
||||
{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt"},"id":"{{messageId}}"}},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"id":"{{messageId}}","role":"user","content":[{"type":"text","text":"Serial agent creation completed."}],"source":{"kind":"plugin","plugin":"serial-created-fixture"}},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"content":[{"type":"text","text":"Reply with exactly DIRECT_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).\n\nYou are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."},{"name":"subagent:delegation","text":"You are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it."}]},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
|
||||
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","reasoningEffort":"high","maxTokens":256000},"adapterDefaults":{"maxTokens":true},"tools":["cordis_define","cordis_inspect_list","cordis_inspect_query","cordis_inspect_self","cordis_run","cordis_stop","cordis_undefine","job_kill","job_list","job_output","run_code","snapshot_double","subagent","workflow"]},"reason":"initial"}}
|
||||
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","reasoningEffort":"high","maxTokens":256000},"adapterDefaults":{"maxTokens":true},"tools":["cordis_inspect_list","cordis_inspect_query","job_kill","job_list","job_output","run_code","snapshot_double","subagent","workflow"]},"reason":"initial"}}
|
||||
{"type":"request/context","data":{"provider":"deepseek-official","model":"smoke-model","contextWindow":1000000}}
|
||||
{"type":"session/title","data":{"title":"Reply with exactly DIRECT_CHILD_OK and","messageSeqs":[9],"source":{"kind":"fallback"}}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{child-1}}","sessionFormatVersion":3,"throughSeq":13}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"DIRECT_CHILD_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["DIRECT_CHILD_OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DIRECT_CHILD_OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
|
||||
{"type":"session/title","data":{"title":"Reply with exactly DIRECT_CHILD_OK and","messageSeqs":[12],"source":{"kind":"fallback"}}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{child-1}}","sessionFormatVersion":3,"throughSeq":16}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"DIRECT_CHILD_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"text"}]}},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["DIRECT_CHILD_OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DIRECT_CHILD_OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"text"}]}}}]},"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":1}}
|
||||
{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
|
||||
@@ -2,18 +2,21 @@
|
||||
{"type":"sandbox/mode","data":{"mode":"danger-full-access","source":"delegation"}}
|
||||
{"type":"approval/policy","data":{"policy":"never","source":"delegation"}}
|
||||
{"type":"permission/preset","data":{"preset":"danger-full-access"}}
|
||||
{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"inserted":[{"id":"{{messageId}}","role":"user","content":[{"type":"text","text":"Serial agent creation completed."}],"source":{"kind":"plugin","plugin":"serial-created-fixture"}}]}}
|
||||
{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply with exactly WORKFLOW_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"}]}}
|
||||
{"type":"turn/start","data":{"turn":1}}
|
||||
{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"removedCount":1,"inserted":[]}}
|
||||
{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
|
||||
{"type":"subagent/descriptor","data":{"version":3,"mode":"one-shot","provider":"spawn"}}
|
||||
{"type":"step/start","data":{"turn":1,"step":1}}
|
||||
{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt"},"id":"{{messageId}}"}},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"id":"{{messageId}}","role":"user","content":[{"type":"text","text":"Serial agent creation completed."}],"source":{"kind":"plugin","plugin":"serial-created-fixture"}},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"content":[{"type":"text","text":"Reply with exactly WORKFLOW_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).\n\nYou are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."},{"name":"subagent:delegation","text":"You are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it."}]},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
|
||||
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","reasoningEffort":"high","maxTokens":256000},"adapterDefaults":{"maxTokens":true},"tools":["cordis_define","cordis_inspect_list","cordis_inspect_query","cordis_inspect_self","cordis_run","cordis_stop","cordis_undefine","job_kill","job_list","job_output","run_code","snapshot_double","subagent","workflow"]},"reason":"initial"}}
|
||||
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","reasoningEffort":"high","maxTokens":256000},"adapterDefaults":{"maxTokens":true},"tools":["cordis_inspect_list","cordis_inspect_query","job_kill","job_list","job_output","run_code","snapshot_double","subagent","workflow"]},"reason":"initial"}}
|
||||
{"type":"request/context","data":{"provider":"deepseek-official","model":"smoke-model","contextWindow":1000000}}
|
||||
{"type":"session/title","data":{"title":"Reply with exactly WORKFLOW_CHILD_OK and","messageSeqs":[9],"source":{"kind":"fallback"}}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{child-2}}","sessionFormatVersion":3,"throughSeq":13}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"WORKFLOW_CHILD_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["WORKFLOW_CHILD_OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"WORKFLOW_CHILD_OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
|
||||
{"type":"session/title","data":{"title":"Reply with exactly WORKFLOW_CHILD_OK and","messageSeqs":[12],"source":{"kind":"fallback"}}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{child-2}}","sessionFormatVersion":3,"throughSeq":16}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"WORKFLOW_CHILD_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"text"}]}},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["WORKFLOW_CHILD_OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"WORKFLOW_CHILD_OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"text"}]}}}]},"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":1}}
|
||||
{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
|
||||
@@ -2,67 +2,66 @@
|
||||
{"type":"permission/preset","data":{"preset":"danger-full-access"}}
|
||||
{"type":"sandbox/mode","data":{"mode":"danger-full-access"}}
|
||||
{"type":"approval/policy","data":{"policy":"never"}}
|
||||
{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"inserted":[{"id":"{{messageId}}","role":"user","content":[{"type":"text","text":"Serial agent creation completed."}],"source":{"kind":"plugin","plugin":"serial-created-fixture"}}]}}
|
||||
{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Run the advanced packaged-runtime snapshot scenario."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"}]}}
|
||||
{"type":"turn/start","data":{"turn":1}}
|
||||
{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"removedCount":1,"inserted":[]}}
|
||||
{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
|
||||
{"type":"step/start","data":{"turn":1,"step":1}}
|
||||
{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt"},"id":"{{messageId}}"}},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"id":"{{messageId}}","role":"user","content":[{"type":"text","text":"Serial agent creation completed."}],"source":{"kind":"plugin","plugin":"serial-created-fixture"}},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"content":[{"type":"text","text":"Run the advanced packaged-runtime snapshot scenario."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
|
||||
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["cordis_define","cordis_inspect_list","cordis_inspect_query","cordis_inspect_self","cordis_run","cordis_stop","cordis_undefine","job_kill","job_list","job_output","run_code","subagent","workflow"]},"reason":"initial"}}
|
||||
{"type":"user/message","data":{"id":"{{messageId}}","role":"user","content":[{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","width":1,"height":1,"bytes":69}}],"source":{"kind":"plugin","plugin":"python-snapshot-image-offload"}},"surfaceOp":"append"}
|
||||
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["cordis_inspect_list","cordis_inspect_query","job_kill","job_list","job_output","run_code","snapshot_double","subagent","workflow"]},"reason":"initial"}}
|
||||
{"type":"request/context","data":{"provider":"deepseek-official","model":"smoke-model","contextWindow":1000000}}
|
||||
{"type":"session/title","data":{"title":"Run the advanced packaged-runtime snapsh","messageSeqs":[8],"source":{"kind":"fallback"}}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{parent}}","sessionFormatVersion":3,"throughSeq":12}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-define","name":"cordis_define","arguments":"{\"plugin\": {\"kind\": \"new\", \"idPrefix\": \"snap\"}, \"name\": \"Snapshot Double\", \"purpose\": \"Expose a deterministic doubling tool for executable snapshot verification.\", \"code\": {\"host\": \"return (ctx) => {\\n harness.registerTool(ctx, harness.defineTool({\\n name: 'snapshot_double',\\n description: 'Double a number for executable snapshot verification.',\\n parameters: { value: { type: 'number', required: true } },\\n output: {\\n schema: { type: 'number' },\\n render(_args, value) {\\n return [{ type: 'text', text: String(value) }]\\n }\\n },\\n async execute(args) {\\n return args.value * 2\\n }\\n }))\\n}\\n\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-define","name":"cordis_define","args":["{\"plugin\": {\"kind\": \"new\", \"idPrefix\": \"snap\"}, \"name\": \"Snapshot Double\", \"purpose\": \"Expose a deterministic doubling tool for executable snapshot verification.\", \"code\": {\"host\": \"return (ctx) => {\\n harness.registerTool(ctx, harness.defineTool({\\n name: 'snapshot_double',\\n description: 'Double a number for executable snapshot verification.',\\n parameters: { value: { type: 'number', required: true } },\\n output: {\\n schema: { type: 'number' },\\n render(_args, value) {\\n return [{ type: 'text', text: String(value) }]\\n }\\n },\\n async execute(args) {\\n return args.value * 2\\n }\\n }))\\n}\\n\"}}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-define","name":"cordis_define","arguments":"{\"plugin\": {\"kind\": \"new\", \"idPrefix\": \"snap\"}, \"name\": \"Snapshot Double\", \"purpose\": \"Expose a deterministic doubling tool for executable snapshot verification.\", \"code\": {\"host\": \"return (ctx) => {\\n harness.registerTool(ctx, harness.defineTool({\\n name: 'snapshot_double',\\n description: 'Double a number for executable snapshot verification.',\\n parameters: { value: { type: 'number', required: true } },\\n output: {\\n schema: { type: 'number' },\\n render(_args, value) {\\n return [{ type: 'text', text: String(value) }]\\n }\\n },\\n async execute(args) {\\n return args.value * 2\\n }\\n }))\\n}\\n\"}}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
|
||||
{"type":"tool/call","data":{"turn":1,"step":1,"callId":"advanced-define","name":"cordis_define","arguments":"{\"plugin\": {\"kind\": \"new\", \"idPrefix\": \"snap\"}, \"name\": \"Snapshot Double\", \"purpose\": \"Expose a deterministic doubling tool for executable snapshot verification.\", \"code\": {\"host\": \"return (ctx) => {\\n harness.registerTool(ctx, harness.defineTool({\\n name: 'snapshot_double',\\n description: 'Double a number for executable snapshot verification.',\\n parameters: { value: { type: 'number', required: true } },\\n output: {\\n schema: { type: 'number' },\\n render(_args, value) {\\n return [{ type: 'text', text: String(value) }]\\n }\\n },\\n async execute(args) {\\n return args.value * 2\\n }\\n }))\\n}\\n\"}}"}}
|
||||
{"type":"tool/result","data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"advanced-define"},"content":[{"type":"tool-result","toolCallId":"advanced-define","content":[{"type":"text","text":"Defined snap-1/pkg-1 (Snapshot Double); it is not running yet. Use cordis_run to activate this Package."}],"isError":false}],"role":"user","id":"{{messageId}}"},"meta":{"pluginId":"snap-1","packageId":"pkg-1"}},"sourceEventSeqs":[15],"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":1}}
|
||||
{"type":"step/start","data":{"turn":1,"step":2}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{parent}}","sessionFormatVersion":3,"throughSeq":18}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-run","name":"cordis_run","arguments":"{\"pluginId\": \"snap-1\", \"packageId\": \"pkg-1\", \"mode\": \"run\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-run","name":"cordis_run","args":["{\"pluginId\": \"snap-1\", \"packageId\": \"pkg-1\", \"mode\": \"run\"}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-run","name":"cordis_run","arguments":"{\"pluginId\": \"snap-1\", \"packageId\": \"pkg-1\", \"mode\": \"run\"}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
|
||||
{"type":"tool/call","data":{"turn":1,"step":2,"callId":"advanced-run","name":"cordis_run","arguments":"{\"pluginId\": \"snap-1\", \"packageId\": \"pkg-1\", \"mode\": \"run\"}"}}
|
||||
{"type":"tool/result","data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"advanced-run"},"content":[{"type":"tool-result","toolCallId":"advanced-run","content":[{"type":"text","text":"snap-1/pkg-1 is running (run-1)."}],"isError":false}],"role":"user","id":"{{messageId}}"},"meta":{"pluginId":"snap-1","packageId":"pkg-1","pluginRunId":"run-1"}},"sourceEventSeqs":[21],"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":2}}
|
||||
{"type":"step/start","data":{"turn":1,"step":3}}
|
||||
{"type":"system/message","data":{"turn":1,"step":3,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt"},"id":"{{messageId}}"}},"sourceEventSeqs":[7],"surfaceOp":{"op":"replace","startSeq":7,"endSeq":7}}
|
||||
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["cordis_define","cordis_inspect_list","cordis_inspect_query","cordis_inspect_self","cordis_run","cordis_stop","cordis_undefine","job_kill","job_list","job_output","run_code","snapshot_double","subagent","workflow"]},"reason":"change","startsSeries":true}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{parent}}","sessionFormatVersion":3,"throughSeq":26}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Run the temporary Plugin tool\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-code","name":"run_code","args":["{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Run the temporary Plugin tool\"}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Run the temporary Plugin tool\"}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
|
||||
{"type":"tool/call","data":{"turn":1,"step":3,"callId":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Run the temporary Plugin tool\"}"}}
|
||||
{"type":"session/title","data":{"title":"Run the advanced packaged-runtime snapsh","messageSeqs":[11],"source":{"kind":"fallback"}}}
|
||||
{"type":"assistant/attempt","data":{"turn":1,"step":1,"stream":[{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"code":"IMAGE_OFFLOAD_REQUIRED","message":"authored image budget failure","offloadImages":1}}}}]}}
|
||||
{"type":"image/offload","data":{"targets":[{"seq":13,"imageIndexes":[0]}]}}
|
||||
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["cordis_inspect_list","cordis_inspect_query","job_kill","job_list","job_output","run_code","snapshot_double","subagent","workflow"]},"reason":"series"}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{parent}}","sessionFormatVersion":3,"throughSeq":19}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Call the configured Plugin tool\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"tool-call"}]}},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-code","name":"run_code","args":[""]},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-code","args":["{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Call the configured Plugin tool\"}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Call the configured Plugin tool\"}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"tool-call"}]}}}]},"surfaceOp":"append"}
|
||||
{"type":"tool/call","data":{"turn":1,"step":1,"callId":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Call the configured Plugin tool\"}"}}
|
||||
{"type":"tool/ptc-dispatch-start","data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:ptc:1","name":"snapshot_double","arguments":{"value":21}}}
|
||||
{"type":"tool/ptc-dispatch","data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:ptc:1","name":"snapshot_double","arguments":{"value":21},"isError":false,"content":[{"type":"text","text":"42"}]}}
|
||||
{"type":"tool/result","data":{"turn":1,"step":3,"message":{"source":{"kind":"tool","callId":"advanced-code"},"content":[{"type":"tool-result","toolCallId":"advanced-code","content":[{"type":"text","text":"42"}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[29],"surfaceOp":"append"}
|
||||
{"type":"tool/result","data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"advanced-code"},"content":[{"type":"tool-result","toolCallId":"advanced-code","content":[{"type":"text","text":"42"}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[22],"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":1}}
|
||||
{"type":"step/start","data":{"turn":1,"step":2}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{parent}}","sessionFormatVersion":3,"throughSeq":27}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-denied-native","name":"snapshot_double","arguments":"{\"value\": -1}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"tool-call"}]}},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-denied-native","name":"snapshot_double","args":[""]},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-denied-native","args":["{\"value\": -1}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-denied-native","name":"snapshot_double","arguments":"{\"value\": -1}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"tool-call"}]}}}]},"surfaceOp":"append"}
|
||||
{"type":"tool/call","data":{"turn":1,"step":2,"callId":"advanced-denied-native","name":"snapshot_double","arguments":"{\"value\": -1}"}}
|
||||
{"type":"tool/result","data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"advanced-denied-native"},"content":[{"type":"tool-result","toolCallId":"advanced-denied-native","content":[{"type":"text","text":"Error: Auto review rejected tool \"snapshot_double\"; its body was not executed"}],"isError":true}],"role":"user","id":"{{messageId}}"},"error":{"name":"AutoReviewDeniedError","code":"AUTO_REVIEW_DENIED","reason":" transport raw\r\nreason "}},"sourceEventSeqs":[30],"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":2}}
|
||||
{"type":"step/start","data":{"turn":1,"step":3}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{parent}}","sessionFormatVersion":3,"throughSeq":33}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-denied-ptc","name":"run_code","arguments":"{\"code\": \"try { await tools.snapshot_double({ value: -1 }) } catch (error) { return error.message }\", \"description\": \"Catch a structured inner tool denial\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"tool-call"}]}},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-denied-ptc","name":"run_code","args":[""]},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-denied-ptc","args":["{\"code\": \"try { await tools.snapshot_double({ value: -1 }) } catch (error) { return error.message }\", \"description\": \"Catch a structured inner tool denial\"}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-denied-ptc","name":"run_code","arguments":"{\"code\": \"try { await tools.snapshot_double({ value: -1 }) } catch (error) { return error.message }\", \"description\": \"Catch a structured inner tool denial\"}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"tool-call"}]}}}]},"surfaceOp":"append"}
|
||||
{"type":"tool/call","data":{"turn":1,"step":3,"callId":"advanced-denied-ptc","name":"run_code","arguments":"{\"code\": \"try { await tools.snapshot_double({ value: -1 }) } catch (error) { return error.message }\", \"description\": \"Catch a structured inner tool denial\"}"}}
|
||||
{"type":"tool/ptc-dispatch-start","data":{"rootCallId":"advanced-denied-ptc","parentCallId":"advanced-denied-ptc","subCallId":"advanced-denied-ptc:ptc:1","name":"snapshot_double","arguments":{"value":-1}}}
|
||||
{"type":"tool/ptc-dispatch","data":{"rootCallId":"advanced-denied-ptc","parentCallId":"advanced-denied-ptc","subCallId":"advanced-denied-ptc:ptc:1","name":"snapshot_double","arguments":{"value":-1},"isError":true,"error":{"name":"AutoReviewDeniedError","code":"AUTO_REVIEW_DENIED","reason":" transport raw\r\nreason "},"content":[{"type":"text","text":"Error: Auto review rejected tool \"snapshot_double\"; its body was not executed"}]}}
|
||||
{"type":"tool/result","data":{"turn":1,"step":3,"message":{"source":{"kind":"tool","callId":"advanced-denied-ptc"},"content":[{"type":"tool-result","toolCallId":"advanced-denied-ptc","content":[{"type":"text","text":"Auto review rejected tool \"snapshot_double\"; its body was not executed"}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[36],"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":3}}
|
||||
{"type":"step/start","data":{"turn":1,"step":4}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{parent}}","sessionFormatVersion":3,"throughSeq":34}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":4,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-direct-child","name":"subagent","arguments":"{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-direct-child","name":"subagent","args":["{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-direct-child","name":"subagent","arguments":"{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{parent}}","sessionFormatVersion":3,"throughSeq":41}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":4,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-direct-child","name":"subagent","arguments":"{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"tool-call"}]}},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-direct-child","name":"subagent","args":[""]},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-direct-child","args":["{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-direct-child","name":"subagent","arguments":"{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"tool-call"}]}}}]},"surfaceOp":"append"}
|
||||
{"type":"tool/call","data":{"turn":1,"step":4,"callId":"advanced-direct-child","name":"subagent","arguments":"{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}
|
||||
{"type":"subagent/catalog","data":{"version":0,"childId":"{{child-1}}","childCreatedAt":0,"mode":"one-shot","label":"Check direct child"}}
|
||||
{"type":"tool/result","data":{"turn":1,"step":4,"message":{"source":{"kind":"tool","callId":"advanced-direct-child"},"content":[{"type":"tool-result","toolCallId":"advanced-direct-child","content":[{"type":"text","text":"DIRECT_CHILD_OK"}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[37],"surfaceOp":"append"}
|
||||
{"type":"tool/result","data":{"turn":1,"step":4,"message":{"source":{"kind":"tool","callId":"advanced-direct-child"},"content":[{"type":"tool-result","toolCallId":"advanced-direct-child","content":[{"type":"text","text":"DIRECT_CHILD_OK"}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[44],"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":4}}
|
||||
{"type":"step/start","data":{"turn":1,"step":5}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{parent}}","sessionFormatVersion":3,"throughSeq":41}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":5,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-workflow","name":"workflow","arguments":"{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-workflow","name":"workflow","args":["{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-workflow","name":"workflow","arguments":"{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{parent}}","sessionFormatVersion":3,"throughSeq":48}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":5,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-workflow","name":"workflow","arguments":"{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"tool-call"}]}},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-workflow","name":"workflow","args":[""]},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-workflow","args":["{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-workflow","name":"workflow","arguments":"{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"tool-call"}]}}}]},"surfaceOp":"append"}
|
||||
{"type":"tool/call","data":{"turn":1,"step":5,"callId":"advanced-workflow","name":"workflow","arguments":"{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"}}
|
||||
{"type":"tool-workflow/run-start","data":{"runId":"{{workflow-run}}","name":"advanced-exe-snapshot"}}
|
||||
{"type":"subagent/catalog","data":{"version":0,"childId":"{{child-2}}","childCreatedAt":0,"mode":"one-shot"}}
|
||||
{"type":"tool-workflow/agent-start","data":{"runId":"{{workflow-run}}","seq":1,"label":"workflow-child","phase":"Delegate","childId":"{{child-2}}"}}
|
||||
{"type":"tool-workflow/agent-end","data":{"runId":"{{workflow-run}}","seq":1,"outcome":"completed"}}
|
||||
{"type":"tool-workflow/run-end","data":{"runId":"{{workflow-run}}","stopReason":"completed"}}
|
||||
{"type":"tool/result","data":{"turn":1,"step":5,"message":{"source":{"kind":"tool","callId":"advanced-workflow"},"content":[{"type":"tool-result","toolCallId":"advanced-workflow","content":[{"type":"text","text":"workflow \"advanced-exe-snapshot\" completed (1 agent).\nReturn value:\n{\n \"reply\": \"WORKFLOW_CHILD_OK\"\n}"}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[44],"surfaceOp":"append"}
|
||||
{"type":"tool/result","data":{"turn":1,"step":5,"message":{"source":{"kind":"tool","callId":"advanced-workflow"},"content":[{"type":"tool-result","toolCallId":"advanced-workflow","content":[{"type":"text","text":"workflow \"advanced-exe-snapshot\" completed (1 agent).\nReturn value:\n{\n \"reply\": \"WORKFLOW_CHILD_OK\"\n}"}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[51],"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":5}}
|
||||
{"type":"step/start","data":{"turn":1,"step":6}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{parent}}","sessionFormatVersion":3,"throughSeq":52}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":6,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-undefine","name":"cordis_undefine","arguments":"{\"pluginId\": \"snap-1\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"advanced-undefine","name":"cordis_undefine","args":["{\"pluginId\": \"snap-1\"}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-undefine","name":"cordis_undefine","arguments":"{\"pluginId\": \"snap-1\"}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
|
||||
{"type":"tool/call","data":{"turn":1,"step":6,"callId":"advanced-undefine","name":"cordis_undefine","arguments":"{\"pluginId\": \"snap-1\"}"}}
|
||||
{"type":"tool/result","data":{"turn":1,"step":6,"message":{"source":{"kind":"tool","callId":"advanced-undefine"},"content":[{"type":"tool-result","toolCallId":"advanced-undefine","content":[{"type":"text","text":"Removed dynamic Plugin snap-1 and all of its Packages."}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[55],"surfaceOp":"append"}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{parent}}","sessionFormatVersion":3,"throughSeq":59}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":6,"message":{"role":"assistant","content":[{"type":"text","text":"ADVANCED_EXECUTABLE_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"text"}]}},"id":"{{message:1}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["ADVANCED_EXECUTABLE_OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"ADVANCED_EXECUTABLE_OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"text"}]}}}]},"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":6}}
|
||||
{"type":"step/start","data":{"turn":1,"step":7}}
|
||||
{"type":"system/message","data":{"turn":1,"step":7,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt"},"id":"{{messageId}}"}},"sourceEventSeqs":[25],"surfaceOp":{"op":"replace","startSeq":25,"endSeq":25}}
|
||||
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["cordis_define","cordis_inspect_list","cordis_inspect_query","cordis_inspect_self","cordis_run","cordis_stop","cordis_undefine","job_kill","job_list","job_output","run_code","subagent","workflow"]},"reason":"change","startsSeries":true}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{parent}}","sessionFormatVersion":3,"throughSeq":60}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":7,"message":{"role":"assistant","content":[{"type":"text","text":"ADVANCED_EXECUTABLE_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{message:1}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["ADVANCED_EXECUTABLE_OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"ADVANCED_EXECUTABLE_OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":7}}
|
||||
{"type":"command/run","data":{"commandId":"{{command:1}}","name":"feedback","source":{"kind":"user"}}}
|
||||
{"type":"feedback/record","data":{"text":"The session needs a clearer explanation."}}
|
||||
{"type":"command/done","data":{"commandId":"{{command:1}}","kind":"success","text":"Feedback recorded for session {{parent}}\nAnonymous user: {{anonymous-user}}."}}
|
||||
|
||||
@@ -1,67 +1,65 @@
|
||||
[
|
||||
{
|
||||
"system": "You are a helpful software engineer assistant.",
|
||||
"tools": [
|
||||
{
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "bash",
|
||||
"description": "Run commands in a bash shell\n* When invoking this tool, the contents of the \"command\" parameter does NOT need to be XML-escaped.\n* Network access depends on the task environment. Prefer configured mirrors/proxies when they are available.\n* State is persistent across command calls and discussions with the user.\n* To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.\n* Please avoid commands that may produce a very large amount of output.\n* Please run long lived commands in the background, e.g. 'sleep 10 &' or start a server in the background.",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {
|
||||
"type": "string",
|
||||
"description": "The bash command to run. Relative path is preferred in the command."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"command"
|
||||
]
|
||||
}
|
||||
"name": "bash",
|
||||
"description": "Run commands in a bash shell\n* When invoking this tool, the contents of the \"command\" parameter does NOT need to be XML-escaped.\n* Network access depends on the task environment. Prefer configured mirrors/proxies when they are available.\n* State is persistent across command calls and discussions with the user.\n* To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.\n* Please avoid commands that may produce a very large amount of output.\n* Please run long lived commands in the background, e.g. 'sleep 10 &' or start a server in the background.",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {
|
||||
"type": "string",
|
||||
"description": "The bash command to run. Relative path is preferred in the command."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"command"
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
"text": "You are a helpful software engineer assistant."
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"text": "Exercise the packaged minimal agent's persistent shell."
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Exercise the packaged minimal agent's persistent shell."
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"system": "You are a helpful software engineer assistant.",
|
||||
"tools": [
|
||||
{
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "bash",
|
||||
"description": "Run commands in a bash shell\n* When invoking this tool, the contents of the \"command\" parameter does NOT need to be XML-escaped.\n* Network access depends on the task environment. Prefer configured mirrors/proxies when they are available.\n* State is persistent across command calls and discussions with the user.\n* To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.\n* Please avoid commands that may produce a very large amount of output.\n* Please run long lived commands in the background, e.g. 'sleep 10 &' or start a server in the background.",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {
|
||||
"type": "string",
|
||||
"description": "The bash command to run. Relative path is preferred in the command."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"command"
|
||||
]
|
||||
}
|
||||
"name": "bash",
|
||||
"description": "Run commands in a bash shell\n* When invoking this tool, the contents of the \"command\" parameter does NOT need to be XML-escaped.\n* Network access depends on the task environment. Prefer configured mirrors/proxies when they are available.\n* State is persistent across command calls and discussions with the user.\n* To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.\n* Please avoid commands that may produce a very large amount of output.\n* Please run long lived commands in the background, e.g. 'sleep 10 &' or start a server in the background.",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {
|
||||
"type": "string",
|
||||
"description": "The bash command to run. Relative path is preferred in the command."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"command"
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
"text": "You are a helpful software engineer assistant."
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"text": "Exercise the packaged minimal agent's persistent shell."
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Exercise the packaged minimal agent's persistent shell."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"role": "assistant",
|
||||
@@ -73,42 +71,46 @@
|
||||
]
|
||||
},
|
||||
{
|
||||
"role": "tool",
|
||||
"toolCallId": "minimal-bash-1",
|
||||
"text": "{{tool-result}}"
|
||||
"role": "user",
|
||||
"content": [
|
||||
{
|
||||
"type": "tool_result",
|
||||
"tool_use_id": "minimal-bash-1",
|
||||
"content": "{{tool-result}}"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"system": "You are a helpful software engineer assistant.",
|
||||
"tools": [
|
||||
{
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "bash",
|
||||
"description": "Run commands in a bash shell\n* When invoking this tool, the contents of the \"command\" parameter does NOT need to be XML-escaped.\n* Network access depends on the task environment. Prefer configured mirrors/proxies when they are available.\n* State is persistent across command calls and discussions with the user.\n* To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.\n* Please avoid commands that may produce a very large amount of output.\n* Please run long lived commands in the background, e.g. 'sleep 10 &' or start a server in the background.",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {
|
||||
"type": "string",
|
||||
"description": "The bash command to run. Relative path is preferred in the command."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"command"
|
||||
]
|
||||
}
|
||||
"name": "bash",
|
||||
"description": "Run commands in a bash shell\n* When invoking this tool, the contents of the \"command\" parameter does NOT need to be XML-escaped.\n* Network access depends on the task environment. Prefer configured mirrors/proxies when they are available.\n* State is persistent across command calls and discussions with the user.\n* To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.\n* Please avoid commands that may produce a very large amount of output.\n* Please run long lived commands in the background, e.g. 'sleep 10 &' or start a server in the background.",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {
|
||||
"type": "string",
|
||||
"description": "The bash command to run. Relative path is preferred in the command."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"command"
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
"text": "You are a helpful software engineer assistant."
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"text": "Exercise the packaged minimal agent's persistent shell."
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Exercise the packaged minimal agent's persistent shell."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"role": "assistant",
|
||||
@@ -120,9 +122,14 @@
|
||||
]
|
||||
},
|
||||
{
|
||||
"role": "tool",
|
||||
"toolCallId": "minimal-bash-1",
|
||||
"text": "{{tool-result}}"
|
||||
"role": "user",
|
||||
"content": [
|
||||
{
|
||||
"type": "tool_result",
|
||||
"tool_use_id": "minimal-bash-1",
|
||||
"content": "{{tool-result}}"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"role": "assistant",
|
||||
@@ -134,9 +141,14 @@
|
||||
]
|
||||
},
|
||||
{
|
||||
"role": "tool",
|
||||
"toolCallId": "minimal-bash-2",
|
||||
"text": "{{tool-result}}"
|
||||
"role": "user",
|
||||
"content": [
|
||||
{
|
||||
"type": "tool_result",
|
||||
"tool_use_id": "minimal-bash-2",
|
||||
"content": "{{tool-result}}"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,67 +1,65 @@
|
||||
[
|
||||
{
|
||||
"system": "You are a helpful software engineer assistant.",
|
||||
"tools": [
|
||||
{
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "pwsh",
|
||||
"description": "Run commands in a PowerShell shell\n* When invoking this tool, the contents of the \"command\" parameter does NOT need to be XML-escaped.\n* You don't have access to the internet via this tool.\n* State is persistent across command calls and discussions with the user.\n* Use native Windows paths (C:\\...) and $env:NAME variables; this is PowerShell, not bash.\n* Please avoid commands that may produce a very large amount of output.\n* Please run long lived commands in the background, e.g. 'Start-Job' or start a server with Start-Process.",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {
|
||||
"type": "string",
|
||||
"description": "The PowerShell command to run. Relative path is preferred in the command."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"command"
|
||||
]
|
||||
}
|
||||
"name": "pwsh",
|
||||
"description": "Run commands in a PowerShell shell\n* When invoking this tool, the contents of the \"command\" parameter does NOT need to be XML-escaped.\n* You don't have access to the internet via this tool.\n* State is persistent across command calls and discussions with the user.\n* Use native Windows paths (C:\\...) and $env:NAME variables; this is PowerShell, not bash.\n* Please avoid commands that may produce a very large amount of output.\n* Please run long lived commands in the background, e.g. 'Start-Job' or start a server with Start-Process.",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {
|
||||
"type": "string",
|
||||
"description": "The PowerShell command to run. Relative path is preferred in the command."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"command"
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
"text": "You are a helpful software engineer assistant."
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"text": "Exercise the packaged minimal agent's persistent shell."
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Exercise the packaged minimal agent's persistent shell."
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"system": "You are a helpful software engineer assistant.",
|
||||
"tools": [
|
||||
{
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "pwsh",
|
||||
"description": "Run commands in a PowerShell shell\n* When invoking this tool, the contents of the \"command\" parameter does NOT need to be XML-escaped.\n* You don't have access to the internet via this tool.\n* State is persistent across command calls and discussions with the user.\n* Use native Windows paths (C:\\...) and $env:NAME variables; this is PowerShell, not bash.\n* Please avoid commands that may produce a very large amount of output.\n* Please run long lived commands in the background, e.g. 'Start-Job' or start a server with Start-Process.",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {
|
||||
"type": "string",
|
||||
"description": "The PowerShell command to run. Relative path is preferred in the command."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"command"
|
||||
]
|
||||
}
|
||||
"name": "pwsh",
|
||||
"description": "Run commands in a PowerShell shell\n* When invoking this tool, the contents of the \"command\" parameter does NOT need to be XML-escaped.\n* You don't have access to the internet via this tool.\n* State is persistent across command calls and discussions with the user.\n* Use native Windows paths (C:\\...) and $env:NAME variables; this is PowerShell, not bash.\n* Please avoid commands that may produce a very large amount of output.\n* Please run long lived commands in the background, e.g. 'Start-Job' or start a server with Start-Process.",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {
|
||||
"type": "string",
|
||||
"description": "The PowerShell command to run. Relative path is preferred in the command."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"command"
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
"text": "You are a helpful software engineer assistant."
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"text": "Exercise the packaged minimal agent's persistent shell."
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Exercise the packaged minimal agent's persistent shell."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"role": "assistant",
|
||||
@@ -73,42 +71,46 @@
|
||||
]
|
||||
},
|
||||
{
|
||||
"role": "tool",
|
||||
"toolCallId": "minimal-bash-1",
|
||||
"text": "{{tool-result}}"
|
||||
"role": "user",
|
||||
"content": [
|
||||
{
|
||||
"type": "tool_result",
|
||||
"tool_use_id": "minimal-bash-1",
|
||||
"content": "{{tool-result}}"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"system": "You are a helpful software engineer assistant.",
|
||||
"tools": [
|
||||
{
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "pwsh",
|
||||
"description": "Run commands in a PowerShell shell\n* When invoking this tool, the contents of the \"command\" parameter does NOT need to be XML-escaped.\n* You don't have access to the internet via this tool.\n* State is persistent across command calls and discussions with the user.\n* Use native Windows paths (C:\\...) and $env:NAME variables; this is PowerShell, not bash.\n* Please avoid commands that may produce a very large amount of output.\n* Please run long lived commands in the background, e.g. 'Start-Job' or start a server with Start-Process.",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {
|
||||
"type": "string",
|
||||
"description": "The PowerShell command to run. Relative path is preferred in the command."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"command"
|
||||
]
|
||||
}
|
||||
"name": "pwsh",
|
||||
"description": "Run commands in a PowerShell shell\n* When invoking this tool, the contents of the \"command\" parameter does NOT need to be XML-escaped.\n* You don't have access to the internet via this tool.\n* State is persistent across command calls and discussions with the user.\n* Use native Windows paths (C:\\...) and $env:NAME variables; this is PowerShell, not bash.\n* Please avoid commands that may produce a very large amount of output.\n* Please run long lived commands in the background, e.g. 'Start-Job' or start a server with Start-Process.",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {
|
||||
"type": "string",
|
||||
"description": "The PowerShell command to run. Relative path is preferred in the command."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"command"
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
"text": "You are a helpful software engineer assistant."
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"text": "Exercise the packaged minimal agent's persistent shell."
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Exercise the packaged minimal agent's persistent shell."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"role": "assistant",
|
||||
@@ -120,9 +122,14 @@
|
||||
]
|
||||
},
|
||||
{
|
||||
"role": "tool",
|
||||
"toolCallId": "minimal-bash-1",
|
||||
"text": "{{tool-result}}"
|
||||
"role": "user",
|
||||
"content": [
|
||||
{
|
||||
"type": "tool_result",
|
||||
"tool_use_id": "minimal-bash-1",
|
||||
"content": "{{tool-result}}"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"role": "assistant",
|
||||
@@ -134,9 +141,14 @@
|
||||
]
|
||||
},
|
||||
{
|
||||
"role": "tool",
|
||||
"toolCallId": "minimal-bash-2",
|
||||
"text": "{{tool-result}}"
|
||||
"role": "user",
|
||||
"content": [
|
||||
{
|
||||
"type": "tool_result",
|
||||
"tool_use_id": "minimal-bash-2",
|
||||
"content": "{{tool-result}}"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,28 +1,25 @@
|
||||
[
|
||||
{
|
||||
"model": "smoke-model",
|
||||
"system": "{{system}}",
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
"content": "{{system}}"
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Complete the first isolated Python SDK process turn."
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Complete the first isolated Python SDK process turn."
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"toolNames": [
|
||||
"cordis_define",
|
||||
"cordis_inspect_list",
|
||||
"cordis_inspect_query",
|
||||
"cordis_inspect_self",
|
||||
"cordis_run",
|
||||
"cordis_stop",
|
||||
"cordis_undefine",
|
||||
"job_kill",
|
||||
"job_list",
|
||||
"job_output",
|
||||
@@ -33,28 +30,25 @@
|
||||
},
|
||||
{
|
||||
"model": "smoke-model",
|
||||
"system": "{{system}}",
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
"content": "{{system}}"
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Complete the second isolated Python SDK process turn."
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Complete the second isolated Python SDK process turn."
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"toolNames": [
|
||||
"cordis_define",
|
||||
"cordis_inspect_list",
|
||||
"cordis_inspect_query",
|
||||
"cordis_inspect_self",
|
||||
"cordis_run",
|
||||
"cordis_stop",
|
||||
"cordis_undefine",
|
||||
"job_kill",
|
||||
"job_list",
|
||||
"job_output",
|
||||
|
||||
@@ -9,10 +9,10 @@
|
||||
{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt"},"id":"{{messageId}}"}},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"content":[{"type":"text","text":"Complete the first isolated Python SDK process turn."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
|
||||
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["cordis_define","cordis_inspect_list","cordis_inspect_query","cordis_inspect_self","cordis_run","cordis_stop","cordis_undefine","job_kill","job_list","job_output","run_code","subagent","workflow"]},"reason":"initial"}}
|
||||
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["cordis_inspect_list","cordis_inspect_query","job_kill","job_list","job_output","run_code","subagent","workflow"]},"reason":"initial"}}
|
||||
{"type":"request/context","data":{"provider":"deepseek-official","model":"smoke-model","contextWindow":1000000}}
|
||||
{"type":"session/title","data":{"title":"Complete the first isolated Python","messageSeqs":[8],"source":{"kind":"fallback"}}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{session-1}}","sessionFormatVersion":3,"throughSeq":12}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"PROCESS_ONE_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["PROCESS_ONE_OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"PROCESS_ONE_OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"PROCESS_ONE_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"text"}]}},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["PROCESS_ONE_OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"PROCESS_ONE_OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"text"}]}}}]},"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":1}}
|
||||
{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
|
||||
@@ -9,10 +9,10 @@
|
||||
{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt"},"id":"{{messageId}}"}},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"content":[{"type":"text","text":"Complete the second isolated Python SDK process turn."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
|
||||
{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
|
||||
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["cordis_define","cordis_inspect_list","cordis_inspect_query","cordis_inspect_self","cordis_run","cordis_stop","cordis_undefine","job_kill","job_list","job_output","run_code","subagent","workflow"]},"reason":"initial"}}
|
||||
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"tools":["cordis_inspect_list","cordis_inspect_query","job_kill","job_list","job_output","run_code","subagent","workflow"]},"reason":"initial"}}
|
||||
{"type":"request/context","data":{"provider":"deepseek-official","model":"smoke-model","contextWindow":1000000}}
|
||||
{"type":"session/title","data":{"title":"Complete the second isolated Python","messageSeqs":[8],"source":{"kind":"fallback"}}}
|
||||
{"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{session-2}}","sessionFormatVersion":3,"throughSeq":12}}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"PROCESS_TWO_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["PROCESS_TWO_OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"PROCESS_TWO_OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
|
||||
{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"PROCESS_TWO_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model","replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"text"}]}},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["PROCESS_TWO_OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"PROCESS_TWO_OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"},"replayState":{"response":{"kind":"deepseek-messages","version":1,"model":"smoke-model"},"blocks":[{"type":"text"}]}}}]},"surfaceOp":"append"}
|
||||
{"type":"step/end","data":{"turn":1,"step":1}}
|
||||
{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
|
||||
@@ -1,6 +1,11 @@
|
||||
{
|
||||
"comment": "Maps each primary ` ```ts type-equiv ` or ` ```ts public-api ` block (by doc + declared symbol + projection) to the source declaration and original JSDoc it must match. Paired `.zh.md` blocks are byte-identical derivatives checked through their unsuffixed sibling and have no duplicate entry. Omit projection for the complete declaration; use public-api with a ` ```ts public-api ` block for a body-stripped public class declaration. verify-type-equiv.ts enforces a 1:1 correspondence between primary blocks and entries. Add an entry when you add a primary source-equivalence block; remove it when you remove the block.",
|
||||
"entries": [
|
||||
{
|
||||
"doc": "docs/subsystems/compaction.md",
|
||||
"symbol": "ImageOffloadTarget",
|
||||
"source": "packages/compaction/compaction-image-offload/src/projection.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/core.md",
|
||||
"symbol": "Branded",
|
||||
@@ -8,7 +13,7 @@
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/llm-streaming.md",
|
||||
"symbol": "AssistantProvenance",
|
||||
"symbol": "AssistantProviderMetadata",
|
||||
"source": "packages/llm/llm/src/message.ts"
|
||||
},
|
||||
{
|
||||
@@ -688,7 +693,7 @@
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/session-title.md",
|
||||
"symbol": "SessionTitleModelProvenance",
|
||||
"symbol": "SessionTitleModelIdentity",
|
||||
"source": "packages/session/session-title/src/types.ts"
|
||||
},
|
||||
{
|
||||
@@ -846,6 +851,11 @@
|
||||
"symbol": "ToolGuard",
|
||||
"source": "packages/core/tools/src/index.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/tools.md",
|
||||
"symbol": "ToolErrorInfo",
|
||||
"source": "packages/core/tools/src/index.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/tools.md",
|
||||
"symbol": "ToolRestriction",
|
||||
@@ -1003,9 +1013,14 @@
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/attachment.md",
|
||||
"symbol": "ImageRequestPolicy",
|
||||
"symbol": "ImageRequestTarget",
|
||||
"source": "packages/attachment/attachment/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/attachment.md",
|
||||
"symbol": "ProjectedDimensions",
|
||||
"source": "packages/attachment/attachment/src/request-projection.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/attachment.md",
|
||||
"symbol": "RequestImageAttachment",
|
||||
@@ -1177,39 +1192,39 @@
|
||||
"source": "packages/sandbox/sandbox/src/index.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/code-runtime.md",
|
||||
"symbol": "CodeJsonValue",
|
||||
"source": "packages/code-runtime/code-runtime/src/types.ts"
|
||||
"doc": "docs/subsystems/ptc-runtime.md",
|
||||
"symbol": "PtcJsonValue",
|
||||
"source": "packages/ptc-runtime/ptc-runtime/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/code-runtime.md",
|
||||
"symbol": "CodeRunRequest",
|
||||
"source": "packages/code-runtime/code-runtime/src/types.ts"
|
||||
"doc": "docs/subsystems/ptc-runtime.md",
|
||||
"symbol": "PtcRunRequest",
|
||||
"source": "packages/ptc-runtime/ptc-runtime/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/code-runtime.md",
|
||||
"symbol": "CodeRunResult",
|
||||
"source": "packages/code-runtime/code-runtime/src/types.ts"
|
||||
"doc": "docs/subsystems/ptc-runtime.md",
|
||||
"symbol": "PtcRunResult",
|
||||
"source": "packages/ptc-runtime/ptc-runtime/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/code-runtime.md",
|
||||
"symbol": "CodeBindingNamespace",
|
||||
"source": "packages/code-runtime/code-runtime/src/types.ts"
|
||||
"doc": "docs/subsystems/ptc-runtime.md",
|
||||
"symbol": "PtcBindingNamespace",
|
||||
"source": "packages/ptc-runtime/ptc-runtime/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/code-runtime.md",
|
||||
"symbol": "CodeBindingErrorClass",
|
||||
"source": "packages/code-runtime/code-runtime/src/types.ts"
|
||||
"doc": "docs/subsystems/ptc-runtime.md",
|
||||
"symbol": "PtcBindingErrorClass",
|
||||
"source": "packages/ptc-runtime/ptc-runtime/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/code-runtime.md",
|
||||
"symbol": "CodeBindingFunction",
|
||||
"source": "packages/code-runtime/code-runtime/src/types.ts"
|
||||
"doc": "docs/subsystems/ptc-runtime.md",
|
||||
"symbol": "PtcBindingFunction",
|
||||
"source": "packages/ptc-runtime/ptc-runtime/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/code-runtime.md",
|
||||
"symbol": "CodeRunFailure",
|
||||
"source": "packages/code-runtime/code-runtime/src/types.ts"
|
||||
"doc": "docs/subsystems/ptc-runtime.md",
|
||||
"symbol": "PtcRunFailure",
|
||||
"source": "packages/ptc-runtime/ptc-runtime/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/filesystem.md",
|
||||
@@ -2140,6 +2155,77 @@
|
||||
"doc": "packages/client/ui-conversation/README.md",
|
||||
"symbol": "ComposerChainProps",
|
||||
"source": "packages/client/ui-conversation/src/client/contract/slots.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/session.md",
|
||||
"symbol": "SessionMessageProjection",
|
||||
"source": "packages/core/session/src/surface.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/session.md",
|
||||
"symbol": "SessionMessageProjectionContext",
|
||||
"source": "packages/core/session/src/surface.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/ptc-runtime.md",
|
||||
"symbol": "PtcRunSpec",
|
||||
"source": "packages/ptc-runtime/ptc-runtime/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/ptc-runtime.md",
|
||||
"symbol": "PtcRunSandbox",
|
||||
"source": "packages/ptc-runtime/ptc-runtime/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/ssh.md",
|
||||
"symbol": "Config",
|
||||
"source": "packages/ssh/ssh/src/index.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/ssh.md",
|
||||
"symbol": "SshConnection",
|
||||
"source": "packages/ssh/ssh/src/index.ts",
|
||||
"projection": "public-api"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/mcp.md",
|
||||
"symbol": "McpResourceRequest",
|
||||
"source": "packages/mcp/mcp-resources/src/index.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/mcp.md",
|
||||
"symbol": "McpResourceProvider",
|
||||
"source": "packages/mcp/mcp-resources/src/index.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/deliverables.md",
|
||||
"symbol": "PresentedFile",
|
||||
"source": "packages/deliverables/tool-present/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/deliverables.md",
|
||||
"symbol": "WorkspaceChangedFile",
|
||||
"source": "packages/deliverables/workspace-changes/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/deliverables.md",
|
||||
"symbol": "WorkspaceChangesSummary",
|
||||
"source": "packages/deliverables/workspace-changes/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/deliverables.md",
|
||||
"symbol": "WorkspaceDiffHunk",
|
||||
"source": "packages/deliverables/workspace-changes/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/deliverables.md",
|
||||
"symbol": "WorkspaceFileDiff",
|
||||
"source": "packages/deliverables/workspace-changes/src/types.ts"
|
||||
},
|
||||
{
|
||||
"doc": "docs/subsystems/deliverables.md",
|
||||
"symbol": "WorkspaceChanges",
|
||||
"source": "packages/deliverables/workspace-changes/src/types.ts"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -23,7 +23,7 @@ interface DemoPolicy {
|
||||
readonly wrapper?: string
|
||||
}
|
||||
|
||||
/** Public product launcher plus the private build-only WebWorker packer. */
|
||||
/** Public product launcher plus the build-only WebWorker packer. */
|
||||
const MANIFEST_BIN_ALLOWLIST = new Map<string, ManifestBin>([
|
||||
['apps/cli/package.json', { dsh: 'lib/bin.js' }],
|
||||
['packages/experimental/webworker-packer/package.json', { 'dsh-pack-vfs-image': './bin.js' }],
|
||||
@@ -33,8 +33,8 @@ const MANIFEST_BIN_ALLOWLIST = new Map<string, ManifestBin>([
|
||||
const EXECUTABLE_SOURCE_ALLOWLIST = new Map<string, string>([
|
||||
['apps/cli/src/bin.ts', 'supported dsh application launcher'],
|
||||
['packages/context/time-context/tests/fixtures/driver.ts', 'test-only subprocess driver'],
|
||||
['packages/experimental/webworker-packer/bin.js', 'private build-only wrapper'],
|
||||
['packages/experimental/webworker-packer/src/bin.ts', 'private build-only implementation'],
|
||||
['packages/experimental/webworker-packer/bin.js', 'build-only wrapper'],
|
||||
['packages/experimental/webworker-packer/src/bin.ts', 'build-only implementation'],
|
||||
['packages/sdk/client/tests/fake-runtime.ts', 'test-only SDK runtime peer'],
|
||||
['packages/session/session-telemetry-otel/tests/fixtures/driver.ts', 'test-only subprocess driver'],
|
||||
['packages/shell/tool-pwsh/tests/fixtures/loader/driver.ts', 'test-only subprocess driver'],
|
||||
|
||||
@@ -7,6 +7,7 @@ import { afterEach, describe, expect, it } from 'vitest'
|
||||
import {
|
||||
collectClientPackageViolations,
|
||||
collectLocalSourceSpecifiers,
|
||||
collectRuntimeLocalSourceSpecifiers,
|
||||
collectRuntimeSourcePackageUses,
|
||||
collectRuntimeSourceSpecifiers,
|
||||
collectSourcePackageUses,
|
||||
@@ -75,6 +76,24 @@ function facts(
|
||||
}
|
||||
|
||||
describe('source package uses', () => {
|
||||
it('includes root-relative runtime requests only when explicitly requested', () => {
|
||||
const source = [
|
||||
"import './local.ts'",
|
||||
"import '/src/value.ts'",
|
||||
"export * from '/src/export.ts'",
|
||||
"const load = () => import('/src/lazy.ts')",
|
||||
"const legacy = require('/src/legacy.ts')",
|
||||
"import type { A } from '/src/import-type.ts'",
|
||||
"import { type B } from '/src/import-type-only.ts'",
|
||||
"export type { A } from '/src/export-type.ts'",
|
||||
"export { type B } from '/src/export-type-only.ts'",
|
||||
].join('\n')
|
||||
expect([...collectRuntimeLocalSourceSpecifiers('feature.ts', source)]).toEqual(['./local.ts'])
|
||||
expect([...collectRuntimeLocalSourceSpecifiers('feature.ts', source, true)]).toEqual([
|
||||
'./local.ts', '/src/value.ts', '/src/export.ts', '/src/lazy.ts', '/src/legacy.ts',
|
||||
])
|
||||
})
|
||||
|
||||
it('counts type imports, module augmentations, dynamic imports, and JSX', () => {
|
||||
const uses = collectSourcePackageUses('feature.tsx', [
|
||||
"import type { A } from '@deepseek-ai/dsh-a/subpath'",
|
||||
|
||||
@@ -101,14 +101,15 @@ export function collectLocalSourceSpecifiers(path: string, source: string): Set<
|
||||
}
|
||||
|
||||
/**
|
||||
* Collect relative module specifiers retained by one production source file.
|
||||
* Collect local module specifiers retained by one production source file.
|
||||
* @param path - File path used to select TypeScript's parser mode.
|
||||
* @param source - Source text to inspect.
|
||||
* @returns Relative imports, exports, and requires that survive compilation.
|
||||
* @param includeRootRelative - Include absolute paths, such as Vite's Web-root imports.
|
||||
* @returns Local imports, exports, and requires that survive compilation.
|
||||
*/
|
||||
export function collectRuntimeLocalSourceSpecifiers(path: string, source: string): Set<string> {
|
||||
export function collectRuntimeLocalSourceSpecifiers(path: string, source: string, includeRootRelative = false): Set<string> {
|
||||
const sourceFile = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true)
|
||||
return collectSourceFileUses(sourceFile, true, 'local')
|
||||
return collectSourceFileUses(sourceFile, true, 'local', includeRootRelative)
|
||||
}
|
||||
|
||||
function importCarriesRuntimeValue(node: ts.ImportDeclaration): boolean {
|
||||
@@ -134,13 +135,14 @@ function collectSourceFileUses(
|
||||
sourceFile: ts.SourceFile,
|
||||
runtimeOnly: boolean,
|
||||
key: 'local' | 'package' | 'specifier',
|
||||
includeRootRelative = false,
|
||||
): Set<string> {
|
||||
const uses = new Set<string>()
|
||||
|
||||
const add = (specifier: ts.Expression | undefined): void => {
|
||||
if (specifier === undefined || !ts.isStringLiteralLike(specifier)) return
|
||||
if (key === 'local') {
|
||||
if (specifier.text.startsWith('.')) uses.add(specifier.text)
|
||||
if (specifier.text.startsWith('.') || includeRootRelative && specifier.text.startsWith('/')) uses.add(specifier.text)
|
||||
return
|
||||
}
|
||||
if (!isBareSpecifier(specifier.text)) return
|
||||
|
||||
Loaded 100 of 4824 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user