@osdlc/tsconfig 0.0.0-stage → 0.3.3

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.3.3] - 2026-10-16
+
+### Changed
+
+- Renamed from `@sksizer/tsconfig`. No other changes.
+- To move, replace `@sksizer/tsconfig` with `@osdlc/tsconfig` in `devDependencies` and in every
+  `extends`.
+
+## [0.3.2] - 2026-10-15
+
+### Changed
+
+- First release made from [sksizer/sdlc](https://github.com/sksizer/sdlc) CI, through npm trusted
+  publishing, so the package now carries provenance. The package contents are unchanged.
+
+## [0.3.1] - 2026-10-15
+
+### Changed
+
+- Published to npm from [sksizer/sdlc](https://github.com/sksizer/sdlc), with a LICENSE file
+  and a README written for outside readers. The resolution probe runs as `npm run typecheck`.
+
+## [0.3.0] - 2026-09-06
+
+### Changed
+
+- **BREAKING:** `exactOptionalPropertyTypes` moves into the shared `base` preset, so every consumer
+  now compiles under it.
+
+## [0.2.0] - 2026-09-04
+
+### Changed
+
+- **BREAKING:** Shipping-model options split out of the shared bar into the `source-shipped` preset;
+  `base` no longer carries them.
+
+### Fixed
+
+- Presets no longer resolve a sibling package to a `dist/` nothing builds.
+- Presets stop naming internal packages and counts in their docs.
+
+## [0.1.0] - 2026-09-01
+
+### Added
+
+- Initial `@sksizer/tsconfig` workspace package: the shared compiler bar as `base`, plus `node-lib`,
+  `bun-lib`, `build` and `vue` presets.
+- A `bun` resolution condition.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SK Sizer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# @osdlc/tsconfig
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Strict TypeScript compiler presets: one shared bar, plus the package shapes
+that recur on top of it. Consumed through `extends`; ships no code.
+
+```sh
+npm install --save-dev @osdlc/tsconfig typescript
+```
+
+Requires TypeScript 5.7 or later (`build` uses `rewriteRelativeImportExtensions`
+and the `${configDir}` template).
+
+## Presets
+
+| Preset | What it is |
+|---|---|
+| `base` | The shared bar, carrying nothing specific to how a package ships. |
+| `source-shipped` | `base` + `allowImportingTsExtensions` and `noEmit`, for a package consumed as TypeScript source rather than as built `dist/`. |
+| `node-lib` | `source-shipped` + the ES2022 runtime and node globals. |
+| `bun-lib` | `node-lib` + bun's globals, for a package whose tests or runtime are Bun. |
+| `vue` | `source-shipped` + the modern browser, the DOM, `jsx: preserve`, and no ambient types. |
+| `build` | The emit block, as a mixin. Not a standalone config — see below. |
+
+## Use
+
+`base` and `source-shipped` differ by two options, and TypeScript couples them:
+`allowImportingTsExtensions` is rejected unless `noEmit`, `emitDeclarationOnly`
+or `rewriteRelativeImportExtensions` is set (TS5096). A package consumed as
+TypeScript source, importing `./x.ts`, wants `source-shipped` (directly or
+through `node-lib`, `bun-lib` or `vue`). A package that builds with tsc and
+imports `./x.js` wants `base`.
+
+```jsonc
+// tsconfig.json — the family preset, then your own per-package facts
+{
+  "extends": "@osdlc/tsconfig/node-lib",
+  "include": ["index.ts", "sync.ts"]
+}
+```
+
+`lib`, `types`, `jsx` and `include` are genuine per-package facts, so a package
+still states the ones where it really differs from its preset. What it should
+not restate is anything the preset already says.
+
+The emit mixin goes **last in an array**, on top of the package's own config:
+
+```jsonc
+// tsconfig.build.json
+{
+  "extends": ["./tsconfig.json", "@osdlc/tsconfig/build"],
+  "compilerOptions": { "rootDir": "." }
+}
+```
+
+TypeScript applies array entries left to right, and the extending file's own
+`compilerOptions` last — so `build`'s `noEmit: false` lands on top of the dev
+config's `noEmit: true`, while `rootDir` and `include` stay where they belong.
+`build` deliberately declares no `extends` and no `include`; `presets/build.json`
+explains why each of those would break silently.
+
+## Adding a preset
+
+Add the file under `presets/`, **and add both its `exports` keys** (the
+extensionless and `.json` spellings) to `package.json`. Then add it to
+`tests/resolve.json`. Skipping the `exports` entry still resolves from inside
+this package and breaks every consumer; `npm run typecheck` (tsc over
+`tests/resolve.json`) is what catches that.
+
+## Not for framework-generated configs
+
+A config that extends `./.nuxt/tsconfig.json` or `astro/tsconfigs/*` must stay
+that way. Layering this bar on top would clobber the `paths`, `types`,
+`moduleResolution` and `jsx` the generator computed.
+
+## Source and releases
+
+Developed and released in
+[osdlc/osdlc](https://github.com/osdlc/osdlc/tree/main/packages/tsconfig),
+under `packages/tsconfig`. Report issues at
+[osdlc/osdlc/issues](https://github.com/osdlc/osdlc/issues).
+
+## License
+
+[MIT](https://github.com/osdlc/osdlc/blob/main/packages/tsconfig/LICENSE)

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@osdlc/tsconfig",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.3",
+  "description": "Strict TypeScript compiler presets: a shared bar plus node, bun, vue and build shapes. Consumed through `extends`; ships no code.",
+  "license": "MIT",
+  "author": "SK Sizer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/osdlc/osdlc.git",
+    "directory": "packages/tsconfig"
+  },
+  "homepage": "https://github.com/osdlc/osdlc/tree/main/packages/tsconfig#readme",
+  "bugs": "https://github.com/osdlc/osdlc/issues",
+  "keywords": [
+    "tsconfig",
+    "typescript",
+    "preset",
+    "strict"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "presets/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./base": "./presets/base.json",
+    "./base.json": "./presets/base.json",
+    "./source-shipped": "./presets/source-shipped.json",
+    "./source-shipped.json": "./presets/source-shipped.json",
+    "./node-lib": "./presets/node-lib.json",
+    "./node-lib.json": "./presets/node-lib.json",
+    "./bun-lib": "./presets/bun-lib.json",
+    "./bun-lib.json": "./presets/bun-lib.json",
+    "./vue": "./presets/vue.json",
+    "./vue.json": "./presets/vue.json",
+    "./build": "./presets/build.json",
+    "./build.json": "./presets/build.json",
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "oxlint": "^1.65.0",
+    "prettier": "3.9.6",
+    "typescript": "~6.0.3",
+    "@osdlc/prettier-config": "^0.2.3"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tests/resolve.json",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "oxlint ."
+  }
 }

package/presets/base.json

@@ -0,0 +1,61 @@
+{
+  // The one TypeScript bar every package on these presets meets — and the only
+  // preset that assumes nothing about how a package is shipped.
+  //
+  // It exists so that "how strictly is this checked" is not a per-package
+  // accident. A package cannot be laxer than the app that consumes it, and a
+  // new package inherits the bar instead of choosing one.
+  //
+  // Nothing here assumes a workspace, a bundler, or source-shipped siblings, so
+  // this is the preset an outside consumer extends. The two options that DO
+  // assume all three — `allowImportingTsExtensions` and `noEmit` — live one
+  // level down in ./source-shipped.json, which the sibling presets reach
+  // through. Nothing extends this file for the bar alone; the resolution probe
+  // in this package's tests is what keeps it honest with no local consumer.
+  //
+  // What is NOT here is otherwise deliberate. `lib`, `types`, `jsx` and
+  // `include` are genuine per-package facts — a DOM library and a node CLI
+  // legitimately differ — so packages still set those themselves. The
+  // combinations that recur anyway are the sibling presets: ./node-lib.json,
+  // ./bun-lib.json and ./vue.json. A package not covered by one extends
+  // ./source-shipped.json and states its own facts; a preset with two consumers
+  // would hide one self-documenting line behind an indirection, which is worse
+  // than the line.
+  //
+  // NOT reachable from here: a config that extends a framework-generated one
+  // (./.nuxt/tsconfig.json, astro/tsconfigs/*). Applying this bar on top of
+  // those would clobber the `paths`, `types`, `moduleResolution` and `jsx` the
+  // generator computed.
+  //
+  // `exactOptionalPropertyTypes` was the last option to arrive, in 2026-09, and
+  // it came in the long way: per package, cheapest first, each setting it
+  // locally until the last holdout fell and the line could move here. It cost
+  // 59 fixes across 8 packages, nearly all of one shape — an optional property
+  // handed a `T | undefined` — and nearly all resolved by omitting the key
+  // rather than widening the type, which is the distinction the flag exists to
+  // preserve.
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    // Capitalised. TypeScript accepts either spelling, which is exactly how the
+    // two drift apart across a set of packages.
+    "moduleResolution": "Bundler",
+
+    "strict": true,
+    // `arr[i]` is `T | undefined`, which is true. Pretending otherwise is how an
+    // index out of range becomes a runtime error rather than a compile one.
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+
+    // An optional property is absent or it holds a value; it is not "present
+    // and undefined". See the note above for how this one arrived.
+    "exactOptionalPropertyTypes": true
+  }
+}

package/presets/build.json

@@ -0,0 +1,35 @@
+{
+  // The emit block, as a MIXIN. Use it as the LAST element of an extends array,
+  // never on its own:
+  //
+  //   "extends": ["./tsconfig.json", "@osdlc/tsconfig/build"]
+  //
+  // Two things here are deliberate, and both fail silently if changed.
+  //
+  // 1. `${configDir}` on outDir. A file-path option in an extended config is
+  //    normalized against THAT CONFIG'S directory, not the consumer's — a plain
+  //    "dist" here emits into this package's own directory, so every consumer's
+  //    build produces nothing and the npm tarballs ship empty. The template is
+  //    exempted from that normalization and substitutes against the consuming
+  //    project. (typescript 6.0.3, normalizeNonListOptionValue.)
+  //
+  // 2. No `extends`, and no `include`/`exclude`/`files`. Extending a preset here
+  //    would re-apply it over the consumer's own config and revert what the
+  //    consumer overrode — a NodeNext package would silently become
+  //    ESNext/Bundler. An `include` here would replace the consumer's, rebased
+  //    onto a directory inside node_modules.
+  //
+  // `rootDir` is not here either: it differs between consumers ("." or "src"),
+  // and guessing wrong quietly changes the dist/ layout.
+  "compilerOptions": {
+    "noEmit": false,
+    "outDir": "${configDir}/dist",
+    "declaration": true,
+    "declarationMap": true,
+    // What makes an emitting build legal alongside source-shipped.json's
+    // `allowImportingTsExtensions`, which TS otherwise rejects (TS5096); also
+    // what lets a source-shipped dependency whose own imports carry .ts
+    // extensions typecheck through (TS5097).
+    "rewriteRelativeImportExtensions": true
+  }
+}

package/presets/bun-lib.json

@@ -0,0 +1,24 @@
+{
+  // A node library whose tests (or runtime) are Bun: node globals plus bun's.
+  //
+  // Adds nothing but `types`. `customConditions: ["bun"]` is deliberately NOT
+  // folded in, because it is a per-package fact rather than a property of this
+  // shape — packages in this shape legitimately differ on it.
+  //
+  // What that setting decides: whether a workspace sibling resolves to its
+  // TypeScript source or to its published `dist/`. Getting it wrong is not a
+  // style choice. A package that imports a source-shipped sibling typechecks
+  // THAT sibling's source under ITS OWN options, so if the sibling in turn
+  // reaches a package whose `types` point at a `dist/` no typecheck builds, the
+  // import is unresolvable — TS2307 — even though the sibling's own check is
+  // green. Nothing reports it until the importing package is next checked, so a
+  // package can sit red for as long as nothing touches it.
+  //
+  // So: a package importing a source-shipped sibling must match that sibling's
+  // condition. The alternative is to build the dependency first, which requires
+  // it to have a build task — a source-shipped package may not.
+  "extends": "./node-lib.json",
+  "compilerOptions": {
+    "types": ["node", "bun"]
+  }
+}

package/presets/node-lib.json

@@ -0,0 +1,14 @@
+{
+  // A node library: the ES2022 runtime, node globals, no DOM.
+  //
+  // `customConditions: ["bun"]` is deliberately not here — it is a per-package
+  // decision rather than a property of this shape, so it stays a stated line in
+  // the packages that need it. See ./bun-lib.json for what the setting decides
+  // and how getting it wrong turns into a TS2307 nothing reports until the
+  // importing package is next checked.
+  "extends": "./source-shipped.json",
+  "compilerOptions": {
+    "lib": ["ES2022"],
+    "types": ["node"]
+  }
+}

package/presets/source-shipped.json

@@ -0,0 +1,22 @@
+{
+  // The shared bar plus the two options that assume packages are consumed as
+  // SOURCE — resolved through a `bun` export condition to TypeScript rather
+  // than to a built `dist/` — so an import may name its `.ts` extension.
+  //
+  // Split out of ./base.json rather than left in it because these two are the
+  // only part of the bar an outside consumer would not want. A package that
+  // builds with tsc and imports `./x.js` wants base; a package consumed as
+  // source wants this file, directly or through ./node-lib.json and ./vue.json.
+  //
+  // The two travel together by force, not by preference: TypeScript rejects
+  // `allowImportingTsExtensions` unless one of `noEmit`, `emitDeclarationOnly`
+  // or `rewriteRelativeImportExtensions` is set (TS5096). That is why they moved
+  // as a pair and why neither belongs in base alone. ./build.json sets
+  // `rewriteRelativeImportExtensions`, which is what lets an emitting build
+  // override this file's `noEmit` without tripping the same rule.
+  "extends": "./base.json",
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  }
+}

package/presets/vue.json

@@ -0,0 +1,17 @@
+{
+  // A Vue 3 component package: the modern browser, the DOM and the iterable form
+  // of its collections, SFC/JSX left for the bundler, and NO ambient @types at
+  // all — a browser component must not silently pick up node globals, which is
+  // what an omitted `types` gets you once anything hoists them into reach.
+  //
+  // A Vue package that targets ES2022, or sets no `jsx`, is a different shape
+  // rather than a drifted copy of this one; it extends ./source-shipped.json
+  // directly and states its own facts.
+  "extends": "./source-shipped.json",
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "preserve",
+    "types": []
+  }
+}