From bdbc0d2ceb566956092bad5305546a7f2852c471 Mon Sep 17 00:00:00 2001 From: Benoit TRAVERS Date: Fri, 7 Aug 2026 02:49:19 +0200 Subject: [PATCH] chore: drop comments from tsconfig.json, moving their substance to CONTRIBUTING --- .changeset/tsconfig-comments.md | 8 ++++++++ CONTRIBUTING.md | 32 ++++++++++++++++++++++++++++---- packages/entity/tsconfig.json | 14 -------------- 3 files changed, 36 insertions(+), 18 deletions(-) create mode 100644 .changeset/tsconfig-comments.md diff --git a/.changeset/tsconfig-comments.md b/.changeset/tsconfig-comments.md new file mode 100644 index 0000000..72dd66c --- /dev/null +++ b/.changeset/tsconfig-comments.md @@ -0,0 +1,8 @@ +--- +"@btravstack/entity": patch +--- + +Documentation only: the build and publishing rationale that lived as comments +in `packages/entity/tsconfig.json` moves into CONTRIBUTING, matching the plain +JSON of `tsconfig.consumer.json`. A stale block describing a consumer-side +TS4020 hazard — fixed by the exported `ConstructionKey` seal — is dropped. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c9c54ba..1e3c17d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,11 +37,35 @@ Run `pnpm format` (no `--check`) to auto-fix formatting. ### Type-level tests Behaviour that only shows up at the type level — the construction seal, the -generated/immutable compile-time rules, `add`'s contextual typing — is pinned -in `packages/entity/src/*.test-d.ts` and checked by +generated/immutable compile-time rules, `computed`'s contextual typing — is +pinned in `packages/entity/src/*.test-d.ts` and checked by `tsc --noEmit -p tsconfig.test-d.json` (run as part of `pnpm typecheck`). If -you change a type-level guarantee, update or add the matching `@ts-expect-error` -assertion. +you change a type-level guarantee, update or add the matching +`@ts-expect-error` assertion. + +`*.test-d.ts` files are excluded from the main `tsc` pass by +`tsconfig.json`, so that pass can keep `noUnusedLocals` strict while the +assertions declare bindings they never read. + +### The consumer pass + +`pnpm typecheck` ends with `tsc -p tsconfig.consumer.json`, which compiles +`packages/entity/consumer/` **with declaration emit, against the built +`dist/*.d.mts`** — a stand-in for a downstream library. That is the only +configuration that catches a private name leaking out of the published types +(`TS4020`), because this repo's own `tsc` pass is `noEmit` and never emits +declarations. Both of that config's overrides are load-bearing; the fixture's +own doc comment says why. + +### Publishing settings + +`declarationMap` is off in `packages/entity/tsconfig.json`: `files: ["dist"]` +excludes `src/`, so published declaration maps would be dead-ends (broken +go-to-definition). Consumers get the TSDoc'd `.d.ts` instead. + +Declaration settings reach further than they look — `tsdown` reads that +tsconfig for its `--dts` emit, so what is set there shapes the _published_ +types, while the plain `tsc` pass is `noEmit` from the shared base. ## Design rules (binding) diff --git a/packages/entity/tsconfig.json b/packages/entity/tsconfig.json index 6cddd26..3c0ba5c 100644 --- a/packages/entity/tsconfig.json +++ b/packages/entity/tsconfig.json @@ -3,23 +3,9 @@ "compilerOptions": { "outDir": "./dist", "rootDir": "./src", - // `files: ["dist"]` excludes `src/`, so published declaration maps would be - // dead-ends (broken go-to-definition); consumers get the TSDoc'd d.ts. "declarationMap": false, - // Declaration settings reach further than this file. tsdown reads this - // tsconfig for its `--dts` emit (the `build` script) — the plain `tsc` pass - // is `noEmit`, inherited from the base — so what is set here shapes the - // *published* d.ts. That matters for the construction seal: `src/types.ts` - // seals classes with the module-private `CtorKey` symbol, and a consumer - // that exports an entity subclass with `declaration: true` gets TS4020 - // ("'extends' clause of exported class has or is using private name") on - // `CtorKey` and `BaseInstance`. Measured against TypeScript 5.9.3 and - // 7.0.2 with the built d.ts. Note the base sets `declaration: true`, not - // `false` as the `CtorKey` comment in `src/types.ts` still says. "types": ["node"] }, "include": ["src/**/*"], - // Type-level assertions get their own relaxed pass via tsconfig.test-d.json - // (see the `typecheck` script) — the main pass keeps noUnusedLocals strict. "exclude": ["node_modules", "dist", "src/**/*.test-d.ts"] }