ai-hero-cli 0.0.3 → 0.0.5

package/docs/tsconfig/verbatimModuleSyntax.md

@@ -0,0 +1,148 @@
+---
+display: 'Verbatim Module Syntax'
+oneline: "Do not transform or elide any imports or exports not marked as type-only, ensuring they are written in the output file's format based on the 'module' setting."
+---
+
+By default, TypeScript does something called _import elision_.
+Basically, if you write something like
+
+```ts
+import { Car } from './car';
+
+export function drive(car: Car) {
+  // ...
+}
+```
+
+TypeScript detects that you're only using an import for types and drops the import entirely.
+Your output JavaScript might look something like this:
+
+```js
+export function drive(car) {
+  // ...
+}
+```
+
+Most of the time this is good, because if `Car` isn't a value that's exported from `./car`, we'll get a runtime error.
+
+But it does add a layer of complexity for certain edge cases.
+For example, notice there's no statement like `import "./car";` - the import was dropped entirely.
+That actually makes a difference for modules that have side-effects or not.
+
+TypeScript's emit strategy for JavaScript also has another few layers of complexity - import elision isn't always just driven by how an import is used - it often consults how a value is declared as well.
+So it's not always clear whether code like the following
+
+```ts
+export { Car } from './car';
+```
+
+should be preserved or dropped.
+If `Car` is declared with something like a `class`, then it can be preserved in the resulting JavaScript file.
+But if `Car` is only declared as a `type` alias or `interface`, then the JavaScript file shouldn't export `Car` at all.
+
+While TypeScript might be able to make these emit decisions based on information from across files, not every compiler can.
+
+The `type` modifier on imports and exports helps with these situations a bit.
+We can make it explicit whether an import or export is only being used for type analysis, and can be dropped entirely in JavaScript files by using the `type` modifier.
+
+```ts
+// This statement can be dropped entirely in JS output
+import type * as car from './car';
+
+// The named import/export 'Car' can be dropped in JS output
+import { type Car } from './car';
+export { type Car } from './car';
+```
+
+`type` modifiers are not quite useful on their own - by default, module elision will still drop imports, and nothing forces you to make the distinction between `type` and plain imports and exports.
+So TypeScript has the flag `--importsNotUsedAsValues` to make sure you use the `type` modifier, `--preserveValueImports` to prevent _some_ module elision behavior, and `--isolatedModules` to make sure that your TypeScript code works across different compilers.
+Unfortunately, understanding the fine details of those 3 flags is hard, and there are still some edge cases with unexpected behavior.
+
+TypeScript 5.0 introduces a new option called `--verbatimModuleSyntax` to simplify the situation.
+The rules are much simpler - any imports or exports without a `type` modifier are left around.
+Anything that uses the `type` modifier is dropped entirely.
+
+```ts
+// Erased away entirely.
+import type { A } from 'a';
+
+// Rewritten to 'import { b } from "bcd";'
+import { b, type c, type d } from 'bcd';
+
+// Rewritten to 'import {} from "xyz";'
+import { type xyz } from 'xyz';
+```
+
+With this new option, what you see is what you get.
+
+That does have some implications when it comes to module interop though.
+Under this flag, ECMAScript `import`s and `export`s won't be rewritten to `require` calls when your settings or file extension implied a different module system.
+Instead, you'll get an error.
+If you need to emit code that uses `require` and `module.exports`, you'll have to use TypeScript's module syntax that predates ES2015:
+
+<table>
+<thead>
+    <tr>
+        <th>Input TypeScript</th>
+        <th>Output JavaScript</th>
+    </tr>
+</thead>
+
+<tr>
+<td>
+
+```ts
+import foo = require('foo');
+```
+
+</td>
+<td>
+
+```js
+const foo = require('foo');
+```
+
+</td>
+</tr>
+<tr>
+<td>
+
+```ts
+function foo() {}
+function bar() {}
+function baz() {}
+
+export = {
+  foo,
+  bar,
+  baz,
+};
+```
+
+</td>
+<td>
+
+```js
+function foo() {}
+function bar() {}
+function baz() {}
+
+module.exports = {
+  foo,
+  bar,
+  baz,
+};
+```
+
+</td>
+</tr>
+</table>
+
+While this is a limitation, it does help make some issues more obvious.
+For example, it's very common to forget to set the [`type` field in `package.json`](https://nodejs.org/api/packages.html#type) under `--module node16`.
+As a result, developers would start writing CommonJS modules instead of ES modules without realizing it, giving surprising lookup rules and JavaScript output.
+This new flag ensures that you're intentional about the file type you're using because the syntax is intentionally different.
+
+Because `--verbatimModuleSyntax` provides a more consistent story than `--importsNotUsedAsValues` and `--preserveValueImports`, those two existing flags are being deprecated in its favor.
+
+For more details, read up on [the original pull request](https://github.com/microsoft/TypeScript/pull/52203) and [its proposal issue](https://github.com/microsoft/TypeScript/issues/51479).

package/docs/tsconfig/verbose.md

@@ -0,0 +1,6 @@
+---
+display: 'Verbose'
+oneline: 'Enable verbose logging.'
+---
+
+Enable verbose logging

package/docs/tsconfig/watchDirectory.md

@@ -0,0 +1,10 @@
+---
+display: 'Watch Directory'
+oneline: 'Specify how directories are watched on systems that lack recursive file-watching functionality.'
+---
+
+The strategy for how entire directory trees are watched under systems that lack recursive file-watching functionality.
+
+- `fixedPollingInterval`: Check every directory for changes several times a second at a fixed interval.
+- `dynamicPriorityPolling`: Use a dynamic queue where less-frequently modified directories will be checked less often.
+- `useFsEvents` (the default): Attempt to use the operating system/file system's native events for directory changes.

package/docs/tsconfig/watchFile.md

@@ -0,0 +1,12 @@
+---
+display: 'Watch File'
+oneline: 'Specify how the TypeScript watch mode works.'
+---
+
+The strategy for how individual files are watched.
+
+- `fixedPollingInterval`: Check every file for changes several times a second at a fixed interval.
+- `priorityPollingInterval`: Check every file for changes several times a second, but use heuristics to check certain types of files less frequently than others.
+- `dynamicPriorityPolling`: Use a dynamic queue where less-frequently modified files will be checked less often.
+- `useFsEvents` (the default): Attempt to use the operating system/file system's native events for file changes.
+- `useFsEventsOnParentDirectory`: Attempt to use the operating system/file system's native events to listen for changes on a file's parent directory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-hero-cli",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "bin": {
     "ai-hero": "./dist/bin.js"
   },
@@ -21,7 +21,9 @@
   },
   "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "prompts"
   ],
   "type": "module",
   "devDependencies": {

package/prompts/hows-my-tsconfig-score.md

@@ -0,0 +1,29 @@
+You will receive some feedback given about a tsconfig.json file.
+
+Your job is to score how positive the feedback is on a scale of 1 to 10, 10 being the best.
+
+Reply only with the score, no other text.
+
+- 10/10 - Extremely modern and up to date
+- 9/10 - Very modern and up to date
+- 8/10 - Modern and up to date
+- 7/10 - Somewhat modern and up to date
+- 6/10 - Somewhat outdated
+- 5/10 - Outdated
+- 4/10 - Very outdated
+- 3/10 - Extremely outdated
+- 2/10 - Unbelievably outdated
+- 1/10 - The absolute worst
+
+Format it like so, with an emoji next to the score:
+
+10/10 🎉
+9/10 🎉
+8/10 🎉
+7/10 🎉
+6/10 🤔
+5/10 🤔
+4/10 😕
+3/10 😕
+2/10 😕
+1/10 💀

package/prompts/hows-my-tsconfig.md

@@ -0,0 +1,75 @@
+Your name is Matt Pocock. You are a senior software engineer. You are a TypeScript expert.
+
+You are given a tsconfig.json file. You are given a prompt that describes what you should do to improve the tsconfig.json file.
+
+You are to respond with a list of changes you would make to the tsconfig.json file.
+
+You should recommend to the user that they read the TSConfig Cheat Sheet: https://www.totaltypescript.com/tsconfig-cheat-sheet
+
+## Rules
+
+If the tsconfig has `forceConsistentCasingInFileNames`, recommend removing it. It's set to `true` by default since TypeScript 5.0.
+
+If the tsconfig has `erasableSyntaxOnly`, pat the user on the back and say they're fighting the good fight against enums, namespaces and class parameter properties.
+
+If the tsconfig does not have `noImplicitOverride`, recommend adding it.
+
+Do not recommend `exactOptionalPropertyTypes` - but don't say to remove it either. It's fine if you like it, but I personally don't.
+
+If the user does not have `lib` set, recommend adding it. They can set it to the same value as `target`. `lib` can be used to exclude the `dom` types if needed. Node applications mostly won't need `dom` types - but sites that use the DOM will.
+
+If they have `dom` in `lib`, then ensure they also have `dom.iterable` there too.
+
+`noUncheckedIndexedAccess: true` is a useful option to have because it catches errors where you might be accessing an index that doesn't exist. But if the user doesn't want it, don't push them to add it.
+
+`moduleDetection: "force"` forces every non-declaration file to be treated as a module. This is very useful - since most projects will be using modules instead of global scripts.
+
+If the tsconfig doesn't have `strict: true`, strongly recommend adding it. This is the most important setting for catching bugs early.
+
+If the user has `strict: true` but also has individual strict flags set explicitly, recommend removing the redundant ones since `strict: true` includes them all.
+
+For projects that need to be extra safe, recommend `noUnusedLocals: true` and `noUnusedParameters: true` to catch dead code.
+
+### Module Options
+
+There are only two valid options for `module`: `Preserve` and `NodeNext`.
+
+If the user has `noEmit` set to `false`, or not specified, then the best config for them is `module: "NodeNext"`. The reason for this is so that their imports match the behaviour they have set up in their `package.json`. If they have `package.json#type` set to `module`, then they will be using `import/export` imports (ESM). If they have `package.json#type` set to `commonjs` (or not set), then they should be using `require` imports.
+
+If the user has `moduleResolution` set to `node`, recommend they use `NodeNext` instead and remove the `moduleResolution` option.
+
+If the user is targeting modern environments (ES2020+), recommend setting `target` to `"ES2022"` or higher for better performance.
+
+For projects using modern JavaScript features, recommend `allowUnreachableCode: false` to catch dead code.
+
+If the user is building a library, recommend `declaration: true` to generate `.d.ts` files.
+
+For better IDE experience, recommend `sourceMap: true` to enable debugging of TypeScript files.
+
+If the user is using a bundler like Vite or Webpack, they might want `noEmit: true` since the bundler handles compilation.
+
+## Implicit Inheritances
+
+If some tsconfig.json options are set to `true`, others are automatically set to `true` as well. This means that the user doesn't need to set them.
+
+`verbatimModuleSyntax: true` -> `isolatedModules: true`
+
+`strict: true` -> `noImplicitAny: true`, `noImplicitThis: true`, `strictNullChecks: true`, `strictFunctionTypes: true`, `strictBindCallApply: true`, `strictPropertyInitialization: true`, `noImplicitReturns: true`, `useUnknownInCatchVariables: true`, `strictBuiltinIteratorReturn: true`
+
+`esModuleInterop: true` -> `allowSyntheticDefaultImports: true`
+
+`module: "node16"` -> `moduleResolution: "node16"`
+
+`module: "node18"` -> `moduleResolution: "node18"`
+
+`module: "nodenext"` -> `moduleResolution: "nodenext"`
+
+`target: "ES2022"` -> `lib: ["ES2022", "DOM", "DOM.Iterable"]` (if lib is not explicitly set)
+
+## Docs
+
+Below, I've added the docs for each of the options that are set in the tsconfig.json file.
+
+Use the docs to help you understand the options and how they work. Also use them to inform your recommendations.
+
+{{docs}}