Update tsconfig and corresponding docs

Our generated blueprint was *years* out of date, and between the
changes we made in the types over the last year or so and the guidance
we have given in the TS RFCs we are now both *able* and *required* to
set `strict: true` as well as to opt into `noUncheckedIndexedAccess`
and to disable `allowSyntheticDefaultImports` and `esModuleInterop`.

Additionally, this provided a nice opportunity to document the choices
we have made so folks have something to latch onto when looking at the
config we generate for them, and to update the config to target the
current latest versions of the `target` and `module` fields.

Author: chriskrycho

blueprint-files/ember-cli-typescript/tsconfig.json

@@ -1,25 +1,68 @@
 {
   "compilerOptions": {
-    "target": "es2020",
-    "allowJs": true,
+    "target": "ES2022",
+    "module": "ES2022",
     "moduleResolution": "node",
-    "allowSyntheticDefaultImports": true,
-    "noImplicitAny": true,
-    "noImplicitThis": true,
-    "alwaysStrict": true,
-    "strictNullChecks": true,
-    "strictPropertyInitialization": true,
+
+    // Trying to check Ember apps and addons with `allowJs: true` is a recipe
+    // for many unresolveable type errors, because with *considerable* extra
+    // configuration it ends up including many files which are *not* valid and
+    // cannot be: they *appear* to be resolve-able to TS, but are in fact not in
+    // valid Node-resolveable locations and may not have TS-ready types. This
+    // will likely improve over time
+    "allowJs": false,
+
+    // --- TS for SemVer Types compatibility
+    // Strictness settings -- you should *not* change these: Ember code is not
+    // guaranteed to type check with these set to looser values.
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+
+    // Interop: these are viral and will require anyone downstream of your
+    // package to *also* set them to true. If you *must* enable them to consume
+    // an upstream package, you should
+    "allowSyntheticDefaultImports": false,
+    "esModuleInterop": false,
+
+    // --- Lint-style rules
+
+    // You should feel free to change these, especially if you are already
+    // covering them via linting (e.g. with @typescript-eslint).
     "noFallthroughCasesInSwitch": true,
     "noUnusedLocals": true,
     "noUnusedParameters": true,
     "noImplicitReturns": true,
+    "noPropertyAccessFromIndexSignature": true,
+
+    // --- Compilation/integration settings
+    // Setting `noEmitOnError` here allows ember-cli-typescript to catch errors
+    // and inject them into Ember CLI's build error reporting, which provides
+    // nice feedback for when
     "noEmitOnError": true,
+
+    // We use Babel for emitting runtime code, because it's very important that
+    // we always and only use the same transpiler for non-stable features, in
+    // particular decorators. If you were to change this to `true`, it could
+    // lead to accidentally generating code with `tsc` instead of Babel, and
+    // could thereby result in broken code at runtime.
     "noEmit": true,
+
+    // Ember makes heavy use of decorators; TS does not support them at all
+    // without this flag.
+    "experimentalDecorators": true,
+
+    // Support generation of source maps. Note: you must *also* enable source
+    // maps in your `ember-cli-babel` config and/or `babel.config.js`.
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
     "inlineSourceMap": true,
     "inlineSources": true,
+
+    // The combination of `baseUrl` with `paths` allows Ember's classic package
+    // layout, which is not resolveable with the Node resolution algorithm, to
+    // work with TypeScript.
     "baseUrl": ".",
-    "module": "es6",
-    "experimentalDecorators": true,
     "paths": <%= pathsFor(dasherizedPackageName) %>
   },
   "include": <%= includes %>

docs/ts/using-ts-effectively.md

@@ -8,24 +8,28 @@ Some specific tips for success on the technical front:
 
 First, use the _strictest_ strictness settings that our typings allow (currently all strictness settings except `strictFunctionTypes`). While it may be tempting to start with the _loosest_ strictness settings and then to tighten them down as you go, this will actually mean that "getting your app type-checking" will become a repeated process—getting it type-checking with every new strictness setting you enable—rather than something you do just once.
 
-The full recommended _strictness_ settings in your `"compilerOptions"` hash:
+The full recommended _strictness_ settings in your `"compilerOptions"` hash (which are also the settings generated by the ember-cli-typescript blueprint):
 
-```json
+```json5
 {
-  "noImplicitAny": true,
-  "noImplicitThis": true,
-  "alwaysStrict": true,
-  "strictNullChecks": true,
-  "strictPropertyInitialization": true,
-  "noFallthroughCasesInSwitch": true,
-  "noUnusedLocals": true,
-  "noUnusedParameters": true,
-  "noImplicitReturns": true,
-  "noUncheckedIndexedAccess": true,
+  "compilerOptions": {
+    // Strictness settings -- you should *not* change these: Ember code is not
+    // guaranteed to type check with these set to looser values.
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+
+    // You should feel free to change these, especially if you are already
+    // covering them via linting (e.g. with @typescript-eslint).
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noPropertyAccessFromIndexSignature": true,
+  }
 }
 ```
 
-A good approach is to start at your "leaf" files (the ones that don't import anything else from your app, only Ember types) and then work your way back inward toward the most core types that are used everywhere. Often the highest-value modules are your Ember Data models and any core services that are used everywhere else in the app – and those are also the ones that tend to have the most cascading effects (having to update _tons_ of other places in your app) when you type them later in the process.
+A good approach is to start at your "leaf" modules (the ones that don't import anything else from your app, only Ember or third-party types) and then work your way back inward toward the most core moduels that are used everywhere. Often the highest-value modules are your Ember Data models and any core services that are used everywhere else in the app – and those are also the ones that tend to have the most cascading effects (having to update _tons_ of other places in your app) when you type them later in the process.
 
 Finally, leave `"noEmitOnError": true` (the default) in the `"compilerOptions"` hash in your `tsconfig.json`. This will fail your build if you have type errors, which gives you the fastest feedback as you add types.