feat(release): publish package source, declaration maps, and documentation
Every release member publishes its TypeScript source and the declaration maps that resolve into it, and @deepseek-ai/dsh publishes the repository Markdown documentation staged from docs/ at prepack time. The ./src/* export most members already declared now resolves for an installed consumer, and a consumer editor follows a declaration to the implementation. Bundled JavaScript maps stay unpublished; the vendored family and the Desktop runtime file policy are unchanged. Rationale: .agents/notes/implemented/process/2026-10-08-published-source-and-docs.md
This commit is contained in:
1 parent
67c2fc749b
commit
caa7111f28
356 files changed
+1331
-415
No files matched your search
@@ -293,16 +293,16 @@ describe('package payload constraints', () => {
|
||||
[{ import: './art/icon.svg', default: './art/fallback.svg' }, ['art/icon.svg', 'art/fallback.svg']],
|
||||
[['./art/icon.svg', './art/icon.svg'], ['art/icon.svg']],
|
||||
] as const)('includes exported icon targets in the canonical payload: %j', (icon, expected) => {
|
||||
expect(expectedDshPackageFiles({ exports: { './icon': icon } })).toEqual([...expected, 'lib/index.js', 'lib/types/**/*.d.ts'])
|
||||
expect(expectedDshPackageFiles({ exports: { './icon': icon } })).toEqual([...expected, 'lib/index.js', 'lib/types/**/*.d.ts', 'lib/types/**/*.d.ts.map', 'src'])
|
||||
})
|
||||
|
||||
it.each(['icon.svg', './icon.svg'])('includes and deduplicates manifest icon %s', (icon) => {
|
||||
expect(expectedDshPackageFiles({ icon, exports: { './icon': './icon.svg' } })).toEqual(['icon.svg', 'lib/index.js', 'lib/types/**/*.d.ts'])
|
||||
expect(expectedDshPackageFiles({ icon, exports: { './icon': './icon.svg' } })).toEqual(['icon.svg', 'lib/index.js', 'lib/types/**/*.d.ts', 'lib/types/**/*.d.ts.map', 'src'])
|
||||
})
|
||||
|
||||
it('includes manifest, root, and subpath icon targets', () => {
|
||||
expect(expectedDshPackageFiles({ icon: './legacy.svg', exports: { './icon': './fallback.svg', './search/icon': './search.svg' } })).toEqual([
|
||||
'legacy.svg', 'fallback.svg', 'search.svg', 'lib/index.js', 'lib/types/**/*.d.ts',
|
||||
'legacy.svg', 'fallback.svg', 'search.svg', 'lib/index.js', 'lib/types/**/*.d.ts', 'lib/types/**/*.d.ts.map', 'src',
|
||||
])
|
||||
})
|
||||
|
||||
@@ -323,7 +323,7 @@ describe('package payload constraints', () => {
|
||||
{ exports: { './search/locale/*.json': './z/*.json', './locale/*.json': './a/*.json' }, resources: ['a/*.json', 'z/*.json'] },
|
||||
])('includes declared locale resources in the canonical payload: $exports', ({ exports, resources }) => {
|
||||
expect(expectedDshPackageFiles({ name: '@deepseek-ai/dsh-localized', exports })).toEqual([
|
||||
...resources, 'lib/index.js', 'lib/types/**/*.d.ts',
|
||||
...resources, 'lib/index.js', 'lib/types/**/*.d.ts', 'lib/types/**/*.d.ts.map', 'src',
|
||||
])
|
||||
})
|
||||
|
||||
@@ -336,7 +336,7 @@ describe('package payload constraints', () => {
|
||||
'./locale/zh.json': null,
|
||||
'./locale/fr.json': { types: './locale/fr.d.ts' },
|
||||
},
|
||||
})).toEqual(['lib/index.js', 'lib/types/**/*.d.ts'])
|
||||
})).toEqual(['lib/index.js', 'lib/types/**/*.d.ts', 'lib/types/**/*.d.ts.map', 'src'])
|
||||
})
|
||||
|
||||
it.each(['agent-team', 'agent-team-profile', 'auto-review', 'client-ui-agent-team', 'tool-agent-team'])(
|
||||
@@ -367,6 +367,8 @@ describe('package payload constraints', () => {
|
||||
'lib/index.js',
|
||||
'cordis.patch.yml',
|
||||
'lib/types/**/*.d.ts',
|
||||
'lib/types/**/*.d.ts.map',
|
||||
'src',
|
||||
])
|
||||
expect(expectedDshPackageFiles({
|
||||
name: '@deepseek-ai/dsh-private-profile',
|
||||
@@ -376,6 +378,8 @@ describe('package payload constraints', () => {
|
||||
'cordis.patch.yml',
|
||||
'layers/web.patch.yml',
|
||||
'lib/types/**/*.d.ts',
|
||||
'lib/types/**/*.d.ts.map',
|
||||
'src',
|
||||
])
|
||||
})
|
||||
|
||||
@@ -392,7 +396,7 @@ 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"]')])
|
||||
.toEqual([expect.stringContaining('@deepseek-ai/dsh: package.json files must be ["lib/*.js","lib/types/*.d.ts","lib/types/*.d.ts.map","docs","src"]')])
|
||||
})
|
||||
|
||||
it('requires the shared Web injection entry in the published payload', () => {
|
||||
|
||||
@@ -49,10 +49,6 @@ const publicNativePackages = new Set([
|
||||
'@deepseek-ai/node-addon-system-linux-arm64',
|
||||
'@deepseek-ai/node-addon-system-linux-x64',
|
||||
])
|
||||
/** Deliberate source payloads whose exact bytes are part of the package's audit surface. */
|
||||
const publicationSourceAllowlist: Readonly<Record<string, readonly string[]>> = {
|
||||
'@deepseek-ai/node-addon-system': ['src/main.c', 'src/flock.c'],
|
||||
}
|
||||
/** 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. */
|
||||
@@ -63,14 +59,16 @@ 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', 'lib/types/*.d.ts'],
|
||||
// `docs` carries the repository's Markdown documentation, staged by
|
||||
// `scripts/stage-dsh-docs.ts` before packing.
|
||||
'@deepseek-ai/dsh': ['lib/*.js', 'lib/types/*.d.ts', 'lib/types/*.d.ts.map', 'docs', 'src'],
|
||||
'@deepseek-ai/dsh-desktop-host': [
|
||||
'lib/index.js', 'lib/cli.js',
|
||||
],
|
||||
// Sourcemaps stay out by payload policy; the worker-preview surface
|
||||
// (dist/preview.html and dist/preview/) backs opt-in experimental
|
||||
// Bundled JavaScript maps stay out by payload policy; the worker-preview
|
||||
// surface (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'],
|
||||
'@deepseek-ai/dsh-web-frontend': ['dist', '!dist/**/*.map', '!dist/preview.html', '!dist/preview', 'src'],
|
||||
}
|
||||
|
||||
/** The subset of package.json fields this constraint check cares about. */
|
||||
@@ -291,6 +289,10 @@ export function expectedDshPackageFiles(manifest: PackageManifest): readonly str
|
||||
// declarations.
|
||||
...usesEmittedTreeDefaults(manifest) ? ['lib/types/**/*.js'] : [],
|
||||
'lib/types/**/*.d.ts',
|
||||
// A published declaration map plus `src` lets a consumer editor open the
|
||||
// implementation behind an exported declaration, and lets a plugin author
|
||||
// read it without a repository checkout.
|
||||
'lib/types/**/*.d.ts.map',
|
||||
...hasExportPair(manifest, './typert', './lib/typert.host.d.ts', './lib/typert.host.js')
|
||||
? ['lib/typert.host.js', 'lib/typert.host.d.ts']
|
||||
: [],
|
||||
@@ -298,8 +300,11 @@ export function expectedDshPackageFiles(manifest: PackageManifest): readonly str
|
||||
? ['lib/typert.client.js', 'lib/typert.client.d.ts']
|
||||
: [],
|
||||
...hasTypertRemoteNavigation(manifest)
|
||||
? ['lib/typert.remote-client.js', 'lib/typert.remote-client.d.ts']
|
||||
// The generated Remote declaration carries a `sourceMappingURL` its map
|
||||
// resolves, and that map resolves the Host method through `src`.
|
||||
? ['lib/typert.remote-client.js', 'lib/typert.remote-client.d.ts', 'lib/typert.remote-client.d.ts.map']
|
||||
: [],
|
||||
'src',
|
||||
]
|
||||
}
|
||||
|
||||
@@ -461,9 +466,8 @@ export function checkWorkspaceManifest({ dir, manifest }: WorkspaceManifest): st
|
||||
}
|
||||
|
||||
if (manifest.name?.startsWith('@deepseek-ai/')) {
|
||||
const allowedSources = publicationSourceAllowlist[manifest.name] ?? []
|
||||
for (const file of manifest.files ?? []) {
|
||||
if (isForbiddenPublicationFile(file) && !allowedSources.includes(file)) {
|
||||
if (isForbiddenPublicationFile(file)) {
|
||||
errors.push(`${label}: package.json files must not publish ${JSON.stringify(file)}`)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -15,47 +15,43 @@ describe('publication payload policy', () => {
|
||||
it.each([
|
||||
'lib/index.js',
|
||||
'lib/types/index.d.ts',
|
||||
'lib/types/index.d.ts.map',
|
||||
'lib/typert.remote-client.d.ts.map',
|
||||
'lib/styles/base.css',
|
||||
])('accepts %s', (file) => {
|
||||
expect(isForbiddenPublicationFile(file)).toBe(false)
|
||||
})
|
||||
|
||||
it.each([
|
||||
'src',
|
||||
'./src',
|
||||
'src/',
|
||||
'src/index.ts',
|
||||
'./src/index.ts',
|
||||
String.raw`src\index.ts`,
|
||||
'lib/types/index.d.ts.map',
|
||||
'./lib/types/index.d.ts.map',
|
||||
'lib/typert.remote-client.d.ts.map',
|
||||
])('accepts %s', (file) => {
|
||||
expect(isForbiddenPublicationFile(file)).toBe(false)
|
||||
})
|
||||
|
||||
it.each([
|
||||
'lib/client.js.map',
|
||||
'./lib/client.js.map',
|
||||
'lib/types/index.js.map',
|
||||
String.raw`lib\client.js.map`,
|
||||
])('rejects static manifest path %s', (file) => {
|
||||
expect(isForbiddenPublicationFile(file)).toBe(true)
|
||||
})
|
||||
|
||||
it('rejects source members in packed tarballs', () => {
|
||||
expect(validateFixtureTarball([
|
||||
'package/package.json',
|
||||
'package/src/index.ts',
|
||||
])).toThrow('fixture.tgz publishes source file package/src/index.ts')
|
||||
})
|
||||
|
||||
it('rejects source maps in packed tarballs', () => {
|
||||
expect(validateFixtureTarball([
|
||||
'package/package.json',
|
||||
'package/lib/types/index.d.ts.map',
|
||||
])).toThrow('fixture.tgz publishes source map package/lib/types/index.d.ts.map')
|
||||
expect(validateFixtureTarball([
|
||||
'package/package.json',
|
||||
'package/lib/typert.remote-client.d.ts.map',
|
||||
])).toThrow('fixture.tgz publishes source map package/lib/typert.remote-client.d.ts.map')
|
||||
it('rejects bundled JavaScript maps in packed tarballs', () => {
|
||||
expect(validateFixtureTarball([
|
||||
'package/package.json',
|
||||
'package/lib/client.js.map',
|
||||
])).toThrow('fixture.tgz publishes source map package/lib/client.js.map')
|
||||
])).toThrow('fixture.tgz publishes JavaScript map package/lib/client.js.map')
|
||||
})
|
||||
|
||||
it('accepts source, declaration maps, and declarations in packed tarballs', () => {
|
||||
expect(validateFixtureTarball([
|
||||
'package/package.json',
|
||||
'package/src/index.ts',
|
||||
'package/lib/types/index.d.ts',
|
||||
'package/lib/types/index.d.ts.map',
|
||||
'package/lib/typert.remote-client.d.ts.map',
|
||||
])).not.toThrow()
|
||||
})
|
||||
|
||||
it('accepts a clean packed tarball', () => {
|
||||
|
||||
@@ -23,33 +23,24 @@ function payloadPath(file: string): string {
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether a package payload path exposes source or map intermediates. Maps
|
||||
* serve editor navigation during development, where a workspace consumer
|
||||
* resolves their source through the package link; a published map resolves
|
||||
* nothing, so no payload publishes one.
|
||||
* Whether a package payload path exposes JavaScript map intermediates. A
|
||||
* declaration map pairs with the source and the declaration a consumer
|
||||
* reaches; a JavaScript map describes bundler output that no published entry
|
||||
* pairs with, so no payload publishes one.
|
||||
* @param file - manifest path or tarball member to classify.
|
||||
* @returns whether publishing this path is forbidden.
|
||||
*/
|
||||
export function isForbiddenPublicationFile(file: string): boolean {
|
||||
const normalized = payloadPath(file)
|
||||
return normalized === 'src'
|
||||
|| normalized.startsWith('src/')
|
||||
|| normalized.endsWith('.d.ts.map')
|
||||
|| normalized.endsWith('.js.map')
|
||||
return payloadPath(file).endsWith('.js.map')
|
||||
}
|
||||
|
||||
/**
|
||||
* Reject source and map members in a packed npm tarball.
|
||||
* Reject bundled JavaScript map members in a packed npm tarball.
|
||||
* @param files - tarball members to validate.
|
||||
* @param context - tarball identity named in the failure.
|
||||
*/
|
||||
export function validateTarballPayload(files: readonly string[], context: string): void {
|
||||
for (const file of files) {
|
||||
if (!isForbiddenPublicationFile(file)) continue
|
||||
const normalized = payloadPath(file)
|
||||
if (normalized === 'src' || normalized.startsWith('src/')) {
|
||||
throw new Error(`${context} publishes source file ${file}`)
|
||||
}
|
||||
throw new Error(`${context} publishes source map ${file}`)
|
||||
if (isForbiddenPublicationFile(file)) throw new Error(`${context} publishes JavaScript map ${file}`)
|
||||
}
|
||||
}
|
||||
@@ -387,12 +387,25 @@ describe('release families', () => {
|
||||
const harness = member('packages/a/library', '@deepseek-ai/dsh-library')
|
||||
const vendored = member('vendor/cordis', '@deepseek-ai/cordis')
|
||||
|
||||
expect(() => { dsh.validatePayload(harness, ['package/lib/index.js', 'package/src/index.ts']) })
|
||||
.toThrow(/publishes source file/)
|
||||
expect(() => { dsh.validatePayload(harness, ['package/lib/index.js', 'package/lib/client.js.map']) })
|
||||
.toThrow(/publishes JavaScript map/)
|
||||
expect(() => { dsh.validatePayload(harness, ['package/lib/index.js', 'package/src/index.ts']) }).not.toThrow()
|
||||
expect(() => { vendor.validatePayload(vendored, ['package/lib/index.js', 'package/src/index.ts']) }).not.toThrow()
|
||||
expect(() => { vendor.validatePayload(vendored, []) }).toThrow(/empty tarball/)
|
||||
})
|
||||
|
||||
it('requires the installed package payload the staging hook supplies', () => {
|
||||
const dsh = releaseFamily('dsh')
|
||||
const installed = member('apps/cli', '@deepseek-ai/dsh')
|
||||
|
||||
expect(() => { dsh.validatePayload(installed, ['package/lib/index.js', 'package/src/bin.ts']) })
|
||||
.toThrow(/@deepseek-ai\/dsh packed no documentation/)
|
||||
expect(() => { dsh.validatePayload(installed, ['package/lib/index.js', 'package/docs/guide.md']) })
|
||||
.toThrow(/@deepseek-ai\/dsh packed no source/)
|
||||
expect(() => { dsh.validatePayload(installed, ['package/lib/index.js', 'package/docs/guide.md', 'package/src/bin.ts']) })
|
||||
.not.toThrow()
|
||||
})
|
||||
|
||||
it('drives the installed entry only for the family that publishes one', () => {
|
||||
expect(releaseFamily('dsh').installedEntry).toEqual({ packageName: '@deepseek-ai/dsh', binPath: 'lib/bin.js' })
|
||||
expect(releaseFamily('vendor').installedEntry).toBeUndefined()
|
||||
|
||||
@@ -387,12 +387,22 @@ class DshFamily extends ReleaseFamily {
|
||||
}
|
||||
|
||||
/**
|
||||
* Reject source and declaration-map members, the repository's publication policy.
|
||||
* Reject bundled JavaScript maps, and require the installed package to carry
|
||||
* the documentation and source its manifest promises. `docs` exists only
|
||||
* because `prepack` stages it, so a pack run that skips lifecycle scripts
|
||||
* would otherwise publish the package without it.
|
||||
* @param member - the packed member.
|
||||
* @param files - every path inside its tarball.
|
||||
*/
|
||||
validatePayload(member: ReleaseMember, files: readonly string[]): void {
|
||||
validateTarballPayload(files, member.name)
|
||||
if (member.name !== this.installedEntry.packageName) return
|
||||
if (!files.some(file => file.startsWith('package/docs/') && file.endsWith('.md'))) {
|
||||
throw new Error(`${member.name} packed no documentation`)
|
||||
}
|
||||
if (!files.some(file => file.startsWith('package/src/') && file.endsWith('.ts'))) {
|
||||
throw new Error(`${member.name} packed no source`)
|
||||
}
|
||||
}
|
||||
|
||||
/** Publish every advertised on-demand package before the installation that offers it. */
|
||||
@@ -449,11 +459,10 @@ class VendorFamily extends ReleaseFamily {
|
||||
* Require the payload the vendored manifest declares, including upstream's
|
||||
* `src` tree and declaration maps.
|
||||
*
|
||||
* The harness policy that rejects both does not apply here: these manifests
|
||||
* export `./src/*` for source navigation, so dropping `src` would publish a
|
||||
* package whose export map points at absent files. What must hold instead is
|
||||
* that every path the manifest selects is present, which `files` already
|
||||
* decides and `pnpm pack` already enforces.
|
||||
* Upstream's manifest owns that payload, so this family enforces no shape of
|
||||
* its own beyond a nonempty tarball. What must hold is that every path the
|
||||
* manifest selects is present, which `files` already decides and `pnpm pack`
|
||||
* already enforces.
|
||||
* @param member - the packed member.
|
||||
* @param files - every path inside its tarball.
|
||||
*/
|
||||
|
||||
@@ -307,15 +307,15 @@ describe('release pack CLI', () => {
|
||||
it('validates every parallel tarball before recording the publish order', async () => {
|
||||
const root = fixture()
|
||||
packageFixture(root, 'packages/util/alpha', '@deepseek-ai/alpha')
|
||||
packageFixture(root, 'packages/util/zebra', '@deepseek-ai/zebra', { files: ['lib/index.js', 'src/index.ts'] })
|
||||
write(join(root, 'packages/util/zebra/src/index.ts'), 'export const source = 1\n')
|
||||
packageFixture(root, 'packages/util/zebra', '@deepseek-ai/zebra', { files: ['lib/index.js', 'lib/client.js.map'] })
|
||||
write(join(root, 'packages/util/zebra/lib/client.js.map'), '{"version":3}\n')
|
||||
write(join(root, 'apps/web/dist/index.html'), '<main></main>')
|
||||
writeClientBuildRecord(root, officialClientBuildEnvironment(root, { DSH_CLIENT_COMMIT_HASH: commit }))
|
||||
|
||||
const result = await runPack(root, ['--family', 'dsh', '--concurrency', '8'])
|
||||
|
||||
expect(result.status).not.toBe(0)
|
||||
expect(result.stderr).toContain('@deepseek-ai/zebra publishes source file package/src/index.ts')
|
||||
expect(result.stderr).toContain('@deepseek-ai/zebra publishes JavaScript map package/lib/client.js.map')
|
||||
expect(readdirSync(join(root, 'packed')).filter(name => name.endsWith('.tgz'))).toHaveLength(2)
|
||||
expect(existsSync(join(root, 'packed', PUBLISH_ORDER_FILE))).toBe(false)
|
||||
})
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
import { existsSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { tmpdir } from 'node:os'
|
||||
import { join } from 'node:path'
|
||||
import { afterEach, describe, expect, it } from 'vitest'
|
||||
import { stageDshDocs } from './stage-dsh-docs.ts'
|
||||
|
||||
const roots: string[] = []
|
||||
|
||||
function temporaryRoot(): string {
|
||||
const root = mkdtempSync(join(tmpdir(), 'dsh-stage-docs-'))
|
||||
roots.push(root)
|
||||
return root
|
||||
}
|
||||
|
||||
function write(root: string, path: string, contents = '# fixture\n'): void {
|
||||
const target = join(root, path)
|
||||
mkdirSync(join(target, '..'), { recursive: true })
|
||||
writeFileSync(target, contents)
|
||||
}
|
||||
|
||||
afterEach(() => {
|
||||
for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
|
||||
})
|
||||
|
||||
describe('documentation staging', () => {
|
||||
it('copies reader-facing documents and assets without the tooling-owned records', async () => {
|
||||
const source = join(temporaryRoot(), 'docs')
|
||||
const destination = join(temporaryRoot(), 'cli', 'docs')
|
||||
write(source, 'guide/index.md')
|
||||
write(source, 'guide/index.zh.md')
|
||||
write(source, 'guide/index.i18n.yaml')
|
||||
write(source, 'images/diagram.png', 'png')
|
||||
write(source, 'persistence-changes/v1/changes.md')
|
||||
write(source, 'persistence-changes/README.md')
|
||||
write(source, 'AGENTS.md')
|
||||
|
||||
await stageDshDocs(source, destination)
|
||||
|
||||
expect(existsSync(join(destination, 'guide', 'index.md'))).toBe(true)
|
||||
expect(existsSync(join(destination, 'guide', 'index.zh.md'))).toBe(true)
|
||||
expect(existsSync(join(destination, 'images', 'diagram.png'))).toBe(true)
|
||||
expect(existsSync(join(destination, 'AGENTS.md'))).toBe(true)
|
||||
expect(existsSync(join(destination, 'guide', 'index.i18n.yaml'))).toBe(false)
|
||||
expect(existsSync(join(destination, 'persistence-changes'))).toBe(false)
|
||||
})
|
||||
|
||||
it('replaces a previous copy instead of merging into it', async () => {
|
||||
const source = join(temporaryRoot(), 'docs')
|
||||
const destination = join(temporaryRoot(), 'cli', 'docs')
|
||||
write(source, 'kept.md')
|
||||
write(destination, 'removed.md')
|
||||
|
||||
await stageDshDocs(source, destination)
|
||||
|
||||
expect(existsSync(join(destination, 'kept.md'))).toBe(true)
|
||||
expect(existsSync(join(destination, 'removed.md'))).toBe(false)
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,49 @@
|
||||
/** Stage the reader-facing documentation inside the published `dsh` package. */
|
||||
|
||||
import { cp, rm } from 'node:fs/promises'
|
||||
import { join, relative, sep } from 'node:path'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
|
||||
/** Repository root, resolved from this script rather than the invoking directory. */
|
||||
const REPOSITORY_ROOT = fileURLToPath(new URL('..', import.meta.url))
|
||||
|
||||
/** Generated per-release migration records; an installed package carries the current contract instead. */
|
||||
const EXCLUDED_DIRECTORY = 'persistence-changes'
|
||||
|
||||
/** Translation alignment records the documentation gates own; a reader never opens one. */
|
||||
const EXCLUDED_SUFFIX = '.i18n.yaml'
|
||||
|
||||
/**
|
||||
* Replace a package's `docs` directory with the documentation a reader needs.
|
||||
*
|
||||
* Runs from the `prepack` lifecycle of `@deepseek-ai/dsh`, so packing the
|
||||
* package and packing the release set both publish the same Markdown.
|
||||
* @param source - Documentation root to copy; defaults to the repository `docs`.
|
||||
* @param destination - Package directory to replace; defaults to `apps/cli/docs`.
|
||||
* @returns Resolves after the destination holds the filtered copy.
|
||||
*/
|
||||
export async function stageDshDocs(
|
||||
source: string = join(REPOSITORY_ROOT, 'docs'),
|
||||
destination: string = join(REPOSITORY_ROOT, 'apps', 'cli', 'docs'),
|
||||
): Promise<void> {
|
||||
await rm(destination, { recursive: true, force: true })
|
||||
await cp(source, destination, {
|
||||
recursive: true,
|
||||
filter: entry => !isExcluded(source, entry),
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether one source path is tooling-owned or generated rather than reader-facing.
|
||||
* @param source - Documentation root the entry belongs to.
|
||||
* @param entry - Absolute source path offered to the copy filter.
|
||||
* @returns whether the copy skips this entry.
|
||||
*/
|
||||
function isExcluded(source: string, entry: string): boolean {
|
||||
const path = relative(source, entry).split(sep).join('/')
|
||||
return path === EXCLUDED_DIRECTORY
|
||||
|| path.startsWith(`${EXCLUDED_DIRECTORY}/`)
|
||||
|| path.endsWith(EXCLUDED_SUFFIX)
|
||||
}
|
||||
|
||||
if (import.meta.main) await stageDshDocs()
|
||||
@@ -142,6 +142,7 @@ export const TRANSLATION_SCOPE_GLOB_EXCLUDES = [
|
||||
'**/__pycache__/**',
|
||||
'**/.pytest_cache/**',
|
||||
'apps/web/dist/**',
|
||||
'apps/cli/docs/**',
|
||||
'.artifacts/**',
|
||||
'python/sdk-runtime/src/deepseek_harness_runtime/runtime/**',
|
||||
'vendor/**',
|
||||
@@ -154,6 +155,7 @@ function isTranslationSourceExcluded(file: string): boolean {
|
||||
|| segment.startsWith('.doc-typecheck-')
|
||||
|| segment.startsWith('.node-next-types-'))
|
||||
|| file.startsWith('apps/web/dist/')
|
||||
|| file.startsWith('apps/cli/docs/')
|
||||
|| file.startsWith('python/sdk-runtime/src/deepseek_harness_runtime/runtime/')
|
||||
}
|
||||
|
||||
|
||||
Reference in new issue
Block a user