Merge pull request #20275 from emberjs/stable-types-infra

[FEATURE] Stable types infra

.gitattributes

@@ -1,2 +1,5 @@
 # Set the default behavior, in case people don't have core.autocrlf set.
-* text=auto
+* text=auto
+
+# Tell GH to render all tsconfigs in the tsconfig dir correctly.
+tsconfig/*.json linguist-language=JSON-with-Comments

.gitignore

@@ -47,3 +47,9 @@ npm-debug.log
 *.log
 /.vscode
 
+# These are automatically generated by our build process.
+# TODO: make that *fully* true: The root types/stable directory is *not*
+# automatically generated yet, and accordingly we have explicitly committed a
+# couple of the files. Once it is, we can switch this over to just ignoring
+# `types/stable` entirely.
+types/stable

package.json

@@ -35,6 +35,7 @@
   "scripts": {
     "build": "ember build --environment production",
     "docs": "ember ember-cli-yuidoc",
+    "types": "tsc --project tsconfig/publish-types.json && node types/publish.mjs",
     "link:glimmer": "node bin/yarn-link-glimmer.js",
     "start": "ember serve",
     "lint": "npm-run-all --continue-on-error --aggregate-output --parallel \"lint:!(fix)\"",
@@ -143,6 +144,7 @@
     "glob": "^8.0.3",
     "html-differ": "^1.4.0",
     "lodash.uniq": "^4.5.0",
+    "magic-string": "^0.26.7",
     "mkdirp": "^1.0.4",
     "mocha": "^9.2.2",
     "npm-run-all": "^4.1.5",

packages/@ember/object/-internals.ts

@@ -7,9 +7,23 @@ import { symbol } from '@ember/-internals/utils';
 import { DEBUG } from '@glimmer/env';
 import EmberObject from '.';
 
+// Here we have runtime shenanigans to add debug-only errors to the class in dev
+// builds. Those runtime shenanigans produce the need for type-level shenanigans
+// to match: if we just assign without an explicit type annotation on the `let`
+// binding below for `FrameworkObject`, TS gets stuck because this creates
+// `FrameworkObject` with a class expression (rather than the usual class
+// declaration form). That in turn means TS needs to be able to fully name the
+// type produced by the class expression, which includes the `OWNER` symbol from
+// `@glimmer/owner`.
+//
+// By explicitly giving the declaration a type when assigning it the class
+// expression, instead of relying on inference, TS no longer needs to name the
+// `OWNER` property key from the super class, eliminating the private name
+// shenanigans.
+
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 interface FrameworkObject extends EmberObject {}
-let FrameworkObject = class FrameworkObject extends EmberObject {};
+let FrameworkObject: typeof EmberObject = class FrameworkObject extends EmberObject {};
 
 if (DEBUG) {
   const INIT_WAS_CALLED = Symbol('INIT_WAS_CALLED');

packages/@ember/object/core.ts

@@ -234,6 +234,7 @@ interface CoreObject {
   _super(...args: any[]): any;
 }
 class CoreObject {
+  /** @internal */
   [OWNER]?: Owner;
 
   constructor(owner?: Owner) {

tsconfig.json

@@ -1,39 +1,9 @@
 {
+  "extends": "./tsconfig/compiler-options.json",
   "compilerOptions": {
-    // Compilation Configuration
-    "target": "es2017",
-    "sourceMap": true,
     "outDir": "dist",
-    "baseUrl": "packages",
-    "rootDir": "packages",
-
-    // Environment Configuration
-    "experimentalDecorators": true,
-    "moduleResolution": "node",
-
-    // Enhance Strictness
-    "strict": true,
-    "noImplicitReturns": true,
-    "allowUnreachableCode": false,
-    "noPropertyAccessFromIndexSignature": true,
-    "noUnusedLocals": true,
-    "noUncheckedIndexedAccess": true,
-    "noUnusedParameters": true,
-    "esModuleInterop": false,
-    "allowSyntheticDefaultImports": false,
-
-    "newLine": "LF",
-    "noEmit": true,
-
-    "allowJs": true,
-    "checkJs": false,
-
-    "paths": {
-      "backburner": ["../node_modules/backburner.js/dist/backburner.d.ts"]
-    }
+    "noEmit": true
   },
-
   "include": ["packages/**/*.ts"],
-
   "exclude": ["dist", "node_modules", "tmp", "types"]
 }

tsconfig/compiler-options.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    // Compilation Configuration
+    "target": "es2019",
+    "sourceMap": true,
+    "baseUrl": "../packages",
+    "rootDir": "../packages",
+
+    // Environment Configuration
+    "experimentalDecorators": true,
+    "moduleResolution": "node",
+
+    // Enhance Strictness
+    "strict": true,
+    "noImplicitReturns": true,
+    "allowUnreachableCode": false,
+    "noPropertyAccessFromIndexSignature": true,
+    "noUnusedLocals": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedParameters": true,
+    "esModuleInterop": false,
+    "allowSyntheticDefaultImports": false,
+
+    "newLine": "LF",
+
+    "allowJs": true,
+    "checkJs": false,
+
+    "paths": {
+      "backburner": ["../node_modules/backburner.js/dist/backburner.d.ts"],
+      "require": ["./loader/lib/index.d.ts"]
+    }
+  }
+}

tsconfig/publish-types.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./compiler-options.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    // It'd be really nice to be able to supply sourcemaps, and at some point we
+    // will be able to by using e.g. rollup-plugin-ts once we solve other issues
+    // blocking that in our publishing pipeline by way of circular and repeated
+    // dependencies in the graph, but at the moment we are using `magic-string`
+    // to post-process these to add `declare module` declarations (see the
+    // `types/publish.mjs` script or details), and that doesn't support updating
+    // *existing* source maps, unfortunately.
+    "declarationMap": false,
+    "declarationDir": "../types/stable"
+  },
+  "include": [
+    // Note: these will also pull on all their transitive dependencies, so we
+    // will end up publishing the (private!) types for packages not named here
+    // until we update the actual internals to avoid referencing them!
+    "../packages/@ember/**/*",
+    "../packages/ember/**/*",
+    "../packages/@glimmer/**/*"
+  ],
+  "exclude": [
+    "../**/type-tests",
+    "../**/tests",
+    "../**/internal-test-helpers"
+  ]
+}

types/preview/index.d.ts

@@ -1,11 +1,22 @@
 /**
-  @module
-  Makes Ember's types for the packages it publishes available by importing this
-  path from `ember-source`:
+  *Provides **preview** type definitions for Ember.js.*
+
+  These types are maintained by hand and the types provided here are unstable
+  and subject to change without warning, though we make a best effort to keep
+  churn to a minimum while we work to stabilize Ember's types.
+
+  To use these type definitions, add these import to any TypeScript file in your
+  Ember app or addon:
 
   ```ts
-  import 'ember-source/preview';
+  import 'ember-source/types';
+  import 'ember-source/types/preview';
   ```
+
+  As Ember's types become more stable, this will automatically give you the
+  latest mix of stable and preview types, with no effort from you.
+
+  @module
  */
 
 // This works because each of these modules presents `declare module` definition