From 2a7c1175be1c63023d62904d315bbff9463e1cd0 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 8 Aug 2026 11:52:18 +0800 Subject: [PATCH] fix(docs): keep doc typecheck on Host sources --- docs/api-gateway.i18n.yaml | 4 ++-- docs/api-gateway.md | 2 +- docs/api-gateway.zh.md | 2 +- scripts/doc-typecheck.ts | 28 ++++++++++++---------------- 4 files changed, 16 insertions(+), 20 deletions(-) diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml index 6bf3151311..360e4b32e4 100644 --- a/docs/api-gateway.i18n.yaml +++ b/docs/api-gateway.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/api-gateway.md -api-gateway.md: 7d5c5b7e46a66b2bf56ee1a1bbd57e7758a4c520 -api-gateway.zh.md: cbf62258b7bf4a1d2f657cf1fc08a8dbc0a1a939 +api-gateway.md: e8aafc173dced3c4ead07421d92401411565ece6 +api-gateway.zh.md: 92681b72ffc573cde834cece19568ec3f1d515ce diff --git a/docs/api-gateway.md b/docs/api-gateway.md index 7d5c5b7e46..e8aafc173d 100644 --- a/docs/api-gateway.md +++ b/docs/api-gateway.md @@ -57,7 +57,7 @@ Remote methods may return a value synchronously or return a Promise. For coopera The Client uses concrete functions on ordinary objects, not a JavaScript Proxy. Direct and scoped calls appear under `ctx.remote.` and `agentCtx.remote.`. Each namespace is a traced Cordis child Service registered as `remote.`; the Client assembly mounts contributions through `ctx.remote.$mount()`, and the namespace unloads after its last method is withdrawn. Dependency declarations belong to the actual caller: only a business package that reads `ctx.remote.` or `agentCtx.remote.` declares both `remote` and `remote.` in its own `inject`; assemblies that only mount contributions and higher-level runtimes that do not call that namespace do not declare the namespace dependency on the business package's behalf. When an `@Remote` method has exactly one lookup parameter and a same-named `TypeRTContextMap` uses the same wire identity, the generated scoped signature omits that identity parameter. `@RemoteScope` generates only the scoped invocation interface. -```ts +```ts ignore-check import type { SessionId } from '@deepseek-ai/dsh-session/types' import type { AgentContext } from '@deepseek-ai/dsh-client-runtime/client' import type { Context } from 'cordis' diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md index cbf62258b7..92681b72ff 100644 --- a/docs/api-gateway.zh.md +++ b/docs/api-gateway.zh.md @@ -57,7 +57,7 @@ Remote 方法可以同步返回或返回 Promise。若需要协作式取消，Ho Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接调用与作用域调用分别出现在 `ctx.remote.` 和 `agentCtx.remote.`。每个 namespace 都是注册为 `remote.` 的可追踪 Cordis 子 Service；Client assembly 通过 `ctx.remote.$mount()` 挂载贡献，最后一个方法撤回后该 namespace 随即卸载。依赖声明归实际调用方所有：只有读取 `ctx.remote.` 或 `agentCtx.remote.` 的业务包才在自己的 `inject` 中同时声明 `remote` 与 `remote.`；只负责挂载 contribution 的 assembly，以及不调用该 namespace 的上层 runtime，不代业务包声明 namespace 依赖。当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypeRTContextMap` 使用相同 wire identity 时，生成的作用域签名会省略该 identity 参数。`@RemoteScope` 只生成作用域调用界面。 -```ts +```ts ignore-check import type { SessionId } from '@deepseek-ai/dsh-session/types' import type { AgentContext } from '@deepseek-ai/dsh-client-runtime/client' import type { Context } from 'cordis' diff --git a/scripts/doc-typecheck.ts b/scripts/doc-typecheck.ts index 456dedecfe..efdb03eaad 100644 --- a/scripts/doc-typecheck.ts +++ b/scripts/doc-typecheck.ts @@ -136,25 +136,21 @@ function formatDiagnostics(diagnostics: readonly ts.Diagnostic[], blocks: Block[ } /** - * Reuse both aggregate reference sets from a temp project one directory below - * root. Each referenced package remains its own program, while documentation - * examples can import either the Host or Client API. + * Reuse the Host aggregate references from a temp project one directory below + * root. Generated Client API examples opt out because their declarations do + * not exist until Host tsdown has run. */ function workspaceReferences(): { path: string }[] { - const paths = new Set() - for (const aggregate of ['tsconfig.host.json', 'tsconfig.client.json']) { - const file = join(root, aggregate) - // Parse with TypeScript's own JSONC reader: a regex comment stripper corrupts the `/*/` path - // candidate in the workspace wildcard. - const result = ts.readConfigFile(file, path => readFileSync(path, 'utf8')) - if (result.error) { - throw new Error(`doc-typecheck: cannot read ${file}: ${ts.flattenDiagnosticMessageText(result.error.messageText, '\n')}`) - } - // `config` is typed `any` by the TS API; narrow it to the one field read here. - const { references } = result.config as { references: { path: string }[] } - for (const { path } of references) paths.add(path) + const file = join(root, 'tsconfig.host.json') + // Parse with TypeScript's own JSONC reader: a regex comment stripper corrupts the `/*/` path + // candidate in the workspace wildcard. + const result = ts.readConfigFile(file, path => readFileSync(path, 'utf8')) + if (result.error) { + throw new Error(`doc-typecheck: cannot read ${file}: ${ts.flattenDiagnosticMessageText(result.error.messageText, '\n')}`) } - return [...paths].map(path => ({ + // `config` is typed `any` by the TS API; narrow it to the one field read here. + const { references } = result.config as { references: { path: string }[] } + return references.map(({ path }) => ({ path: path.startsWith('./') ? `../${path.slice(2)}` : `../${path}`, })) }