跳到主要内容

案例研究:退役 tsc

读完你能带走: 一份可转发的迁移剧本——前后诊断对照、命令序列 status → strip → verify → retire,以及诚实的摩擦记录——背后是本 monorepo 里可运行的样例。

终局始终一样:nudo check 是唯一的门禁;typescript 被摘掉。 共存是迁移战术,不是目的地。命令走读:从 TypeScript 迁移。

诚实标签。 下面每个包都是来自 docs/examples/ 的示例级样例(两个真实 npm 消费方,一个公开 demo 包)。耗时与摩擦计数是示例级,非生产规模 —— 不是一次生产迁移审计。不要编造外部公司名;证据是已提交的 before/ / after/ 树与 pnpm run verify:examples。

单向门​

audit (migrate status) → strip → verify (nudo check) → retire (drop tsc)

可直接复制的序列(路径换成你的包):

# 0. audit —— what still carries tsc
npx nudojs migrate status ./my-pkg

# 1. strip —— .ts → .js (annotations out, runtime stays). --write to emit.
npx nudojs migrate strip ./my-pkg/src --write

# 2. optional —— reverse old annotations into a reviewable contract draft
npx nudojs contract --from-dts ./my-pkg/src/index.ts
# → @nudo:draft (NOT enforced until you copy it into *.nudo.js)

# 3. verify —— nudo check must pass on the stripped JS
npx nudojs migrate verify ./my-pkg/src

# 4. retire —— drop typescript, rewrite tsc scripts / GHA lines, write marker
npx nudojs migrate retire ./my-pkg --dry-run # then drop --dry-run

步骤回顾:status 摸清面积(.ts 数量、tsc scripts、blockers)→ strip 产出纯 JS(--write,可选侧车草稿)→ verify 用 nudo check 门禁剥好的 JS(--with-tsc 双跑仅限迁移期间)→ retire 摘掉 typescript、改写 tsc scripts 与 workflow 行、写出 .nudo/migrate-retired.json。完整步骤表(做什么 / 何时退出)见从 TypeScript 迁移。

migrate retire --all 可批处理 monorepo。双跑只作为迁移期间的 migrate verify --with-tsc 存在——永远不是终局。

1. checkout-demo(公开样例)​

beforeafter
内容TypeScript 结账辅助函数普通 JS
门禁tsc --noEmitnudo check src
故事合成但完整已提交的 after/ 就是黄金终局

源码:docs/examples/migrate/

Before → after(代码)​

// before/src/math.ts
export function lineTotal(price: number, qty: number): number {
return price * qty;
}
// after/src/math.js — runtime unchanged
export function lineTotal(price, qty) {
return price * qty;
}

跨文件:cart.ts 里的 type Item = { … } 被删除(TS 专用;它在运行时从未存在)。import 保留。

Before → after(诊断)​

Before 是 tsc --noEmit 的类型名。After 是 Nudo 签名(成功时也打印)加上可选的 L1/L2 面:

nudo check docs/examples/migrate/after/src/math.js
OK
0 error · 1 warning · 0 info · 3 fn

signatures
lineTotal(price: any, qty: any) => number
applyCoupon(total: any, percent: any) => number throws RangeError
formatMoney(cents: any) => string

issues
[WARNING L9 applyCoupon] applyCoupon (export): may throw RangeError (nudo:entry-may-throw)
→ throw RangeError → @nudo:throws RangeError / sidecar fn({ … }) contract / refine / guard / try-catch
fix: nudo contract --draft (emit a sidecar draft you can edit)

读法是:签名照常打印;无约束参数是 any(不是 unknown);有意的 throw 以 L2 浮出,并带下一步。如果你想要第一周更软,after 包可以用 package.json#nudo.check.entryThrows 把它翻成 warning。

之后再收紧,脸会变成值 + 谓词(而不是类型名)——见错误对照:

actual: -1 #exact
expected: x > 0
→ use a value satisfying x > 0
fix: nudo contract --draft

2. 真实包:ms(vercel/ms)​

一个消费真实 ms 格式化器(纯 JS、非常常见)的包,从 TS + @types/ms 迁到 JS + nudo check。依赖本身不变。

beforeafter
语言age.ts + ms.d.tsage.js
门禁tsc --noEmitnudo check
typescript 依赖有无
真实依赖ms@^2.1.3相同

源码:docs/examples/retire-real/

命令序列(实际)​

# status —— audit face (real output)
npx nudojs migrate status docs/examples/retire-real/before
# ts files: 2 tsx: 0 tsconfig: yes typescript dep: yes
# tsc scripts: typecheck
# blockers: tsc still in scripts; no nudo check/test script yet; typescript still in dependencies

# strip —— dry-run in this repo; --write emits
npx nudojs migrate strip docs/examples/retire-real/before/src/age.ts

# reverse annotations into a draft you must review
npx nudojs contract --from-dts docs/examples/retire-real/before/src/age.ts
# export const formatAge = fn({ durationMs: number() }, string());
# export const parseAge = fn({ text: string() }, number());
# → copy into age.nudo.js only after review (that is when L1 goes live)

# verify / gate on the committed after/
npx nudojs check docs/examples/retire-real/after/src/age.js

# retire —— dry-run first
npx nudojs migrate retire docs/examples/retire-real/after --dry-run

Before → after(代码 + 门禁)​

// before/src/age.ts
export function formatAge(durationMs: number): string {
return ms(durationMs, { long: true });
}
// after/src/age.js
export function formatAge(durationMs) {
return ms(durationMs, { long: true });
}

已接受的侧车(after/src/age.nudo.js)——上面那份草稿,已审阅:

import { fn, number, string } from "@nudojs/core";

export const formatAge = fn({ durationMs: number() }, string());
export const parseAge = fn({ text: string() }, number());

退役后的 check 脸(示例级;native ms() 内部未被完整 harvest——parseAge 折叠为精确 undefined,那是值证据而非引擎债(Bug 22);现存义务是两条 L2 may-throw 警告):

signatures
formatAge(durationMs: number) => string throws Error
parseAge(text: string) => undefined throws Error

issues
[WARNING L10 formatAge] formatAge (export): may throw Error (nudo:entry-may-throw)
→ ToString coercion of abstract operand (Symbol) → @nudo:throws TypeError | sidecar: fn({ … }): shape({ <body-read fields> }) | refine / guard / try-catch
fix: nudo contract --draft (emit a sidecar draft you can edit)
[WARNING L19 parseAge] parseAge (export): may throw Error (nudo:entry-may-throw)
→ computed member on nullish (union arm) → @nudo:throws TypeError | sidecar: fn({ … }): shape({ <body-read fields> }) | refine / guard / try-catch
fix: nudo contract --draft (emit a sidecar draft you can edit)

真实退役后的标记:.nudo/migrate-retired.json(typecheck: tsc --noEmit → nudo check src 已改写,typescript 已移除)。

3. 真实包:debug(visionmedia/debug)​

同一道门,对 debug——半个 npm 背后的日志门面。

beforeafter
语言logger.ts + debug.d.tslogger.js
门禁tsc --noEmitnudo check src
真实依赖debug@^4.3.4相同

源码:docs/examples/retire-debug/

npx nudojs migrate status docs/examples/retire-debug/before
npx nudojs migrate strip docs/examples/retire-debug/before/src/logger.ts
npx nudojs contract --from-dts docs/examples/retire-debug/before/src/logger.ts
# → export const createLogger = fn({ namespace: string() }, any());
npx nudojs check docs/examples/retire-debug/after/src/logger.js
npx nudojs migrate retire docs/examples/retire-debug/after --dry-run

诚实边缘: debug() 是 native 入口。宿主能解析到真实 debug 包时,引擎会真实求值并给出精确返回面(函数探针 () => ?,内部仍是开放的);解析不到时诚实退化为 unknown + nudo:opaque-result。两者都不是契约失败——门禁恒为 0 error:

signatures
createLogger(namespace: any) => (() => ?)
logHello(name: any) => undefined

(no issues)

在解析不到 debug 的环境里,这两行读作 => unknown,并多一行 INFO ... conf=opaque (nudo:opaque-result) 提示;门禁仍然是 0 error。

有 @types/debug 时,harvest 会填满签名;或用 @nudo:mock / 声明的返回契约(@nudo:contract 或侧车返回槽)钉住。这与 ms() 是同一个故事。

摩擦与耗时(示例级)​

摩擦出现在哪里怎么修好成本(示例级)
tsc scripts + typescript 依赖还在migrate status blockers 列表migrate retire 改写 scripts;摘掉依赖一条命令(先 --dry-run)
旧标注只有被你接受才变成义务contract --from-dts 发出 @nudo:draft审阅 → 拷进 *.nudo.js每文件几分钟;绝不静默
native / 未 harvest 依赖(ms()、debug())unknown / conf=opaque / nudo:unknown-inference@types/* harvest、@nudo:mock,或声明的返回契约有界;在你钉住之前一直是 warning
有意 throw 上的 L2 entry-may-throwcheckout-demo 的 applyCoupon@nudo:throws RangeError / guard,或 nudo.check.entryThrows: "warning"package.json 一行,或一条 throws 指令
双跑诱惑迁移中期的 CI只在迁移期间保留 verify --with-tsc;出口是 retire政策问题,不是工具问题

墙钟时间(示例级,非生产规模): 这些样例很小(2–3 个模块,每包约剥 1–2 个文件)。已提交的树就是证据——自己跑 pnpm run verify:examples。我们不发布生产规模的小时/天数数字;发布说明里的「7 天退役路径」是产品目标叙事,不是实测中位数。对真实包,请按 migrate status 给出的 .ts 文件数做预算,而不是按博客文章。

这些证明了什么​

主张证据
JS 保持 JSafter/ 源码是普通 .js
契约是可选义务contract --from-dts → 审阅 → *.nudo.js
出口是 retire,不是双跑.nudo/migrate-retired.json + 无 typescript 依赖
真实包能迁ms 与 debug 不是合成 fixture
诚实的引擎债unknown / opaque 保持可见;从不伪装成成功

跑一遍矩阵​

pnpm run verify:examples

上面每条命令都钉在 docs/examples/README.md 的 CI 里。

转发这个故事​

可直接复制的博客 / HN / 发布说明文案:docs/reports/retire-tsc-announcement.md。

下一步​