ai-hero-cli 0.0.3 → 0.0.4

package/docs/tsconfig/emitDecoratorMetadata.md

@@ -0,0 +1,81 @@
+---
+display: 'Emit Decorator Metadata'
+oneline: 'Emit design-type metadata for decorated declarations in source files.'
+---
+
+Enables experimental support for emitting type metadata for decorators which works with the module [`reflect-metadata`](https://www.npmjs.com/package/reflect-metadata).
+
+For example, here is the TypeScript
+
+```ts twoslash
+// @experimentalDecorators
+function LogMethod(
+  target: any,
+  propertyKey: string | symbol,
+  descriptor: PropertyDescriptor,
+) {
+  console.log(target);
+  console.log(propertyKey);
+  console.log(descriptor);
+}
+
+class Demo {
+  @LogMethod
+  public foo(bar: number) {
+    // do nothing
+  }
+}
+
+const demo = new Demo();
+```
+
+With `emitDecoratorMetadata` not set to true (default) the emitted JavaScript is:
+
+```ts twoslash
+// @experimentalDecorators
+// @showEmit
+function LogMethod(
+  target: any,
+  propertyKey: string | symbol,
+  descriptor: PropertyDescriptor,
+) {
+  console.log(target);
+  console.log(propertyKey);
+  console.log(descriptor);
+}
+
+class Demo {
+  @LogMethod
+  public foo(bar: number) {
+    // do nothing
+  }
+}
+
+const demo = new Demo();
+```
+
+With `emitDecoratorMetadata` set to true the emitted JavaScript is:
+
+```ts twoslash
+// @experimentalDecorators
+// @showEmit
+// @emitDecoratorMetadata
+function LogMethod(
+  target: any,
+  propertyKey: string | symbol,
+  descriptor: PropertyDescriptor,
+) {
+  console.log(target);
+  console.log(propertyKey);
+  console.log(descriptor);
+}
+
+class Demo {
+  @LogMethod
+  public foo(bar: number) {
+    // do nothing
+  }
+}
+
+const demo = new Demo();
+```

package/docs/tsconfig/enable.md

@@ -0,0 +1,14 @@
+---
+display: 'Enable'
+oneline: 'Disable the type acquisition for JavaScript projects.'
+---
+
+Disables automatic type acquisition in JavaScript projects:
+
+```json
+{
+  "typeAcquisition": {
+    "enable": false
+  }
+}
+```

package/docs/tsconfig/erasableSyntaxOnly.md

@@ -0,0 +1,65 @@
+---
+display: 'Erasable Syntax Only'
+oneline: 'Do not allow runtime constructs that are not part of ECMAScript.'
+---
+
+Node.js [supports running TypeScript files directly](https://nodejs.org/api/typescript.html#type-stripping) as of v23.6;
+however, only TypeScript-specific syntax that does not have runtime semantics are supported under this mode.
+In other words, it must be possible to easily _erase_ any TypeScript-specific syntax from a file, leaving behind a valid JavaScript file.
+
+That means the following constructs are not supported:
+
+- `enum` declarations
+- `namespace`s and `module`s with runtime code
+- parameter properties in classes
+- Non-ECMAScript `import =` and `export =` assignments
+
+```ts
+// ❌ error: An `import ... = require(...)` alias
+import foo = require('foo');
+
+// ❌ error: A namespace with runtime code.
+namespace container {
+  foo.method();
+
+  export type Bar = string;
+}
+
+// ❌ error: An `import =` alias
+import Bar = container.Bar;
+
+class Point {
+  // ❌ error: Parameter properties
+  constructor(
+    public x: number,
+    public y: number,
+  ) {}
+}
+
+// ❌ error: An `export =` assignment.
+export = Point;
+
+// ❌ error: An enum declaration.
+enum Direction {
+  Up,
+  Down,
+  Left,
+  Right,
+}
+```
+
+Similar tools like [ts-blank-space](https://github.com/bloomberg/ts-blank-space) or [Amaro](https://github.com/nodejs/amaro) (the underlying library for type-stripping in Node.js) have the same limitations.
+These tools will provide helpful error messages if they encounter code that doesn't meet these requirements, but you still won't find out your code doesn't work until you actually try to run it.
+
+The `--erasableSyntaxOnly` flag will cause TypeScript to error on most TypeScript-specific constructs that have runtime behavior.
+
+```ts
+class C {
+    constructor(public x: number) { }
+    //          ~~~~~~~~~~~~~~~~
+    // error! This syntax is not allowed when 'erasableSyntaxOnly' is enabled.
+    }
+}
+```
+
+Typically, you will want to combine this flag with the `--verbatimModuleSyntax`, which ensures that a module contains the appropriate import syntax, and that import elision does not take place.

package/docs/tsconfig/esModuleInterop.md

@@ -0,0 +1,74 @@
+---
+display: 'ES Module Interop'
+oneline: 'Emit additional JavaScript to ease support for importing CommonJS modules. This enables [`allowSyntheticDefaultImports`](#allowSyntheticDefaultImports) for type compatibility.'
+---
+
+By default (with `esModuleInterop` false or not set) TypeScript treats CommonJS/AMD/UMD modules similar to ES6 modules. In doing this, there are two parts in particular which turned out to be flawed assumptions:
+
+- a namespace import like `import * as moment from "moment"` acts the same as `const moment = require("moment")`
+
+- a default import like `import moment from "moment"` acts the same as `const moment = require("moment").default`
+
+This mis-match causes these two issues:
+
+- the ES6 modules spec states that a namespace import (`import * as x`) can only be an object, by having TypeScript
+  treating it the same as `= require("x")` then TypeScript allowed for the import to be treated as a function and be callable. That's not valid according to the spec.
+
+- while accurate to the ES6 modules spec, most libraries with CommonJS/AMD/UMD modules didn't conform as strictly as TypeScript's implementation.
+
+Turning on `esModuleInterop` will fix both of these problems in the code transpiled by TypeScript. The first changes the behavior in the compiler, the second is fixed by two new helper functions which provide a shim to ensure compatibility in the emitted JavaScript:
+
+```ts
+import * as fs from 'fs';
+import _ from 'lodash';
+
+fs.readFileSync('file.txt', 'utf8');
+_.chunk(['a', 'b', 'c', 'd'], 2);
+```
+
+With `esModuleInterop` disabled:
+
+```ts twoslash
+// @noErrors
+// @showEmit
+// @esModuleInterop: false
+// @module: commonjs
+import * as fs from 'fs';
+import _ from 'lodash';
+
+fs.readFileSync('file.txt', 'utf8');
+_.chunk(['a', 'b', 'c', 'd'], 2);
+```
+
+With `esModuleInterop` set to `true`:
+
+```ts twoslash
+// @noErrors
+// @showEmit
+// @esModuleInterop
+// @module: commonjs
+import * as fs from 'fs';
+import _ from 'lodash';
+
+fs.readFileSync('file.txt', 'utf8');
+_.chunk(['a', 'b', 'c', 'd'], 2);
+```
+
+_Note_: The namespace import `import * as fs from "fs"` only accounts for properties which [are owned](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty) (basically properties set on the object and not via the prototype chain) on the imported object. If the module you're importing defines its API using inherited properties, you need to use the default import form (`import fs from "fs"`), or disable `esModuleInterop`.
+
+_Note_: You can make JS emit terser by enabling [`importHelpers`](#importHelpers):
+
+```ts twoslash
+// @noErrors
+// @showEmit
+// @esModuleInterop
+// @importHelpers
+// @module: commonjs
+import * as fs from 'fs';
+import _ from 'lodash';
+
+fs.readFileSync('file.txt', 'utf8');
+_.chunk(['a', 'b', 'c', 'd'], 2);
+```
+
+Enabling `esModuleInterop` will also enable [`allowSyntheticDefaultImports`](#allowSyntheticDefaultImports).

package/docs/tsconfig/exactOptionalPropertyTypes.md

@@ -0,0 +1,37 @@
+---
+display: 'Exact Optional Property Types'
+oneline: 'Interpret optional property types as written, rather than adding `undefined`.'
+---
+
+With exactOptionalPropertyTypes enabled, TypeScript applies stricter rules around how it handles properties on `type` or `interfaces` which have a `?` prefix.
+
+For example, this interface declares that there is a property which can be one of two strings: 'dark' or 'light' or it should not be in the object.
+
+```ts
+interface UserDefaults {
+  // The absence of a value represents 'system'
+  colorThemeOverride?: 'dark' | 'light';
+}
+```
+
+Without this flag enabled, there are three values which you can set `colorThemeOverride` to be: "dark", "light" and `undefined`.
+
+Setting the value to `undefined` will allow most JavaScript runtime checks for the existence to fail, which is effectively falsy. However, this isn't quite accurate; `colorThemeOverride: undefined` is not the same as `colorThemeOverride` not being defined. For example, `"colorThemeOverride" in settings` would have different behavior with `undefined` as the key compared to not being defined.
+
+`exactOptionalPropertyTypes` makes TypeScript truly enforce the definition provided as an optional property:
+
+```ts twoslash
+// @exactOptionalPropertyTypes
+// @errors: 2322 2412
+interface UserDefaults {
+  colorThemeOverride?: 'dark' | 'light';
+}
+declare function getUserSettings(): UserDefaults;
+// ---cut---
+const settings = getUserSettings();
+settings.colorThemeOverride = 'dark';
+settings.colorThemeOverride = 'light';
+
+// But not:
+settings.colorThemeOverride = undefined;
+```

package/docs/tsconfig/exclude.md

@@ -0,0 +1,11 @@
+---
+display: 'Exclude'
+oneline: 'Filters results from the [`include`](#include) option.'
+---
+
+Specifies an array of filenames or patterns that should be skipped when resolving [`include`](#include).
+
+**Important**: `exclude` _only_ changes which files are included as a result of the [`include`](#include) setting.
+A file specified by `exclude` can still become part of your codebase due to an `import` statement in your code, a `types` inclusion, a `/// <reference` directive, or being specified in the [`files`](#files) list.
+
+It is not a mechanism that **prevents** a file from being included in the codebase - it simply changes what the [`include`](#include) setting finds.

package/docs/tsconfig/excludeDirectories.md

@@ -0,0 +1,14 @@
+---
+display: 'Exclude Directories'
+oneline: 'Remove a list of directories from the watch process.'
+---
+
+You can use [`excludeFiles`](#excludeFiles) to drastically reduce the number of files which are watched during `--watch`. This can be a useful way to reduce the number of open file which TypeScript tracks on Linux.
+
+```json tsconfig
+{
+  "watchOptions": {
+    "excludeDirectories": ["**/node_modules", "_build", "temp/*"]
+  }
+}
+```

package/docs/tsconfig/excludeFiles.md

@@ -0,0 +1,14 @@
+---
+display: 'Exclude Files'
+oneline: "Remove a list of files from the watch mode's processing."
+---
+
+You can use `excludeFiles` to remove a set of specific files from the files which are watched.
+
+```json tsconfig
+{
+  "watchOptions": {
+    "excludeFiles": ["temp/file.ts"]
+  }
+}
+```

package/docs/tsconfig/experimentalDecorators.md

@@ -0,0 +1,11 @@
+---
+display: 'Experimental Decorators'
+oneline: 'Enable experimental support for TC39 stage 2 draft decorators.'
+---
+
+Enables [experimental support for decorators](https://github.com/tc39/proposal-decorators), which is a version of decorators that predates the TC39 standardization process.
+
+Decorators are a language feature which hasn't yet been fully ratified into the JavaScript specification.
+This means that the implementation version in TypeScript may differ from the implementation in JavaScript when it it decided by TC39.
+
+You can find out more about decorator support in TypeScript in [the handbook](/docs/handbook/decorators.html).

package/docs/tsconfig/explainFiles.md

@@ -0,0 +1,54 @@
+---
+display: 'Explain Files'
+oneline: 'Print files read during the compilation including why it was included.'
+---
+
+Print names of files which TypeScript sees as a part of your project and the reason they are part of the compilation.
+
+For example, with this project of just a single `index.ts` file
+
+```sh
+example
+├── index.ts
+├── package.json
+└── tsconfig.json
+```
+
+Using a `tsconfig.json` which has `explainFiles` set to true:
+
+```json
+{
+  "compilerOptions": {
+    "target": "es5",
+    "module": "commonjs",
+    "explainFiles": true
+  }
+}
+```
+
+Running TypeScript against this folder would have output like this:
+
+```
+❯ tsc
+node_modules/typescript/lib/lib.d.ts
+  Default library for target 'es5'
+node_modules/typescript/lib/lib.es5.d.ts
+  Library referenced via 'es5' from file 'node_modules/typescript/lib/lib.d.ts'
+node_modules/typescript/lib/lib.dom.d.ts
+  Library referenced via 'dom' from file 'node_modules/typescript/lib/lib.d.ts'
+node_modules/typescript/lib/lib.webworker.importscripts.d.ts
+  Library referenced via 'webworker.importscripts' from
+    file 'node_modules/typescript/lib/lib.d.ts'
+node_modules/typescript/lib/lib.scripthost.d.ts
+  Library referenced via 'scripthost'
+    from file 'node_modules/typescript/lib/lib.d.ts'
+index.ts
+  Matched by include pattern '**/*' in 'tsconfig.json'
+```
+
+The output above show:
+
+- The initial lib.d.ts lookup based on [`target`](#target), and the chain of `.d.ts` files which are referenced
+- The `index.ts` file located via the default pattern of [`include`](#include)
+
+This option is intended for debugging how a file has become a part of your compile.

package/docs/tsconfig/extendedDiagnostics.md

@@ -0,0 +1,9 @@
+---
+display: 'Extended Diagnostics'
+oneline: 'Output more detailed compiler performance information after building.'
+---
+
+You can use this flag to discover where TypeScript is spending its time when compiling.
+This is a tool used for understanding the performance characteristics of your codebase overall.
+
+You can learn more about how to measure and understand the output in the performance [section of the wiki](https://github.com/microsoft/TypeScript/wiki/Performance).

package/docs/tsconfig/extends.md

@@ -0,0 +1,49 @@
+---
+display: 'Extends'
+oneline: 'Specify one or more path or node module references to base configuration files from which settings are inherited.'
+---
+
+The value of `extends` is a string which contains a path to another configuration file to inherit from.
+The path may use Node.js style resolution.
+
+The configuration from the base file are loaded first, then overridden by those in the inheriting config file. All relative paths found in the configuration file will be resolved relative to the configuration file they originated in.
+
+It's worth noting that [`files`](#files), [`include`](#include), and [`exclude`](#exclude) from the inheriting config file _overwrite_ those from the
+base config file, and that circularity between configuration files is not allowed.
+
+Currently, the only top-level property that is excluded from inheritance is [`references`](#references).
+
+##### Example
+
+`configs/base.json`:
+
+```json tsconfig
+{
+  "compilerOptions": {
+    "noImplicitAny": true,
+    "strictNullChecks": true
+  }
+}
+```
+
+`tsconfig.json`:
+
+```json tsconfig
+{
+  "extends": "./configs/base",
+  "files": ["main.ts", "supplemental.ts"]
+}
+```
+
+`tsconfig.nostrictnull.json`:
+
+```json tsconfig
+{
+  "extends": "./tsconfig",
+  "compilerOptions": {
+    "strictNullChecks": false
+  }
+}
+```
+
+Properties with relative paths found in the configuration file, which aren't excluded from inheritance, will be resolved relative to the configuration file they originated in.

package/docs/tsconfig/fallbackPolling.md

@@ -0,0 +1,11 @@
+---
+display: 'Fallback Polling'
+oneline: 'Specify what approach the watcher should use if the system runs out of native file watchers.'
+---
+
+When using file system events, this option specifies the polling strategy that gets used when the system runs out of native file watchers and/or doesn't support native file watchers.
+
+- `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.
+- `synchronousWatchDirectory`: Disable deferred watching on directories. Deferred watching is useful when lots of file changes might occur at once (e.g. a change in `node_modules` from running `npm install`), but you might want to disable it with this flag for some less-common setups.

package/docs/tsconfig/files.md

@@ -0,0 +1,26 @@
+---
+display: 'Files'
+oneline: 'Include a list of files. This does not support glob patterns, as opposed to [`include`](#include).'
+---
+
+Specifies an allowlist of files to include in the program. An error occurs if any of the files can't be found.
+
+```json tsconfig
+{
+  "compilerOptions": {},
+  "files": [
+    "core.ts",
+    "sys.ts",
+    "types.ts",
+    "scanner.ts",
+    "parser.ts",
+    "utilities.ts",
+    "binder.ts",
+    "checker.ts",
+    "tsc.ts"
+  ]
+}
+```
+
+This is useful when you only have a small number of files and don't need to use a glob to reference many files.
+If you need that then use [`include`](#include).

package/docs/tsconfig/force.md

@@ -0,0 +1,6 @@
+---
+display: 'Force'
+oneline: 'Build all projects, including those that appear to be up to date.'
+---
+
+Build all projects, including those that appear to be up to date

package/docs/tsconfig/forceConsistentCasingInFileNames.md

@@ -0,0 +1,10 @@
+---
+display: 'Force Consistent Casing In File Names'
+oneline: 'Ensure that casing is correct in imports.'
+---
+
+TypeScript follows the case sensitivity rules of the file system it's running on.
+This can be problematic if some developers are working in a case-sensitive file system and others aren't.
+If a file attempts to import `fileManager.ts` by specifying `./FileManager.ts` the file will be found in a case-insensitive file system, but not on a case-sensitive file system.
+
+When this option is set, TypeScript will issue an error if a program tries to include a file by a casing different from the casing on disk.

package/docs/tsconfig/generateCpuProfile.md

@@ -0,0 +1,15 @@
+---
+display: 'Generate CPU Profile'
+oneline: 'Emit a v8 CPU profile of the compiler run for debugging.'
+---
+
+This option gives you the chance to have TypeScript emit a v8 CPU profile during the compiler run. The CPU profile can provide insight into why your builds may be slow.
+
+This option can only be used from the CLI via: `--generateCpuProfile tsc-output.cpuprofile`.
+
+```sh
+npm run tsc --generateCpuProfile tsc-output.cpuprofile
+```
+
+This file can be opened in a chromium based browser like Chrome or Edge Developer in [the CPU profiler](https://developers.google.com/web/tools/chrome-devtools/rendering-tools/js-execution) section.
+You can learn more about understanding the compilers performance in the [TypeScript wiki section on performance](https://github.com/microsoft/TypeScript/wiki/Performance).

package/docs/tsconfig/generateTrace.md

@@ -0,0 +1,6 @@
+---
+display: 'generateTrace'
+oneline: 'Generates an event trace and a list of types.'
+---
+
+Generates an event trace and a list of types.

package/docs/tsconfig/importHelpers.md

@@ -0,0 +1,46 @@
+---
+display: 'Import Helpers'
+oneline: 'Allow importing helper functions from tslib once per project, instead of including them per-file.'
+---
+
+For certain downleveling operations, TypeScript uses some helper code for operations like extending class, spreading arrays or objects, and async operations.
+By default, these helpers are inserted into files which use them.
+This can result in code duplication if the same helper is used in many different modules.
+
+If the `importHelpers` flag is on, these helper functions are instead imported from the [tslib](https://www.npmjs.com/package/tslib) module.
+You will need to ensure that the `tslib` module is able to be imported at runtime.
+This only affects modules; global script files will not attempt to import modules.
+
+For example, with this TypeScript:
+
+```ts
+export function fn(arr: number[]) {
+  const arr2 = [1, ...arr];
+}
+```
+
+Turning on [`downlevelIteration`](#downlevelIteration) and `importHelpers` is still false:
+
+```ts twoslash
+// @showEmit
+// @target: ES5
+// @downleveliteration
+export function fn(arr: number[]) {
+  const arr2 = [1, ...arr];
+}
+```
+
+Then turning on both [`downlevelIteration`](#downlevelIteration) and `importHelpers`:
+
+```ts twoslash
+// @showEmit
+// @target: ES5
+// @downleveliteration
+// @importhelpers
+// @noErrors
+export function fn(arr: number[]) {
+  const arr2 = [1, ...arr];
+}
+```
+
+You can use [`noEmitHelpers`](#noEmitHelpers) when you provide your own implementations of these functions.

package/docs/tsconfig/importsNotUsedAsValues.md

@@ -0,0 +1,16 @@
+---
+display: 'Imports Not Used As Values'
+oneline: 'Specify emit/checking behavior for imports that are only used for types.'
+---
+
+Deprecated in favor of [`verbatimModuleSyntax`](#verbatimModuleSyntax).
+
+This flag controls how `import` works, there are 3 different options:
+
+- `remove`: The default behavior of dropping `import` statements which only reference types.
+
+- `preserve`: Preserves all `import` statements whose values or types are never used. This can cause imports/side-effects to be preserved.
+
+- `error`: This preserves all imports (the same as the preserve option), but will error when a value import is only used as a type. This might be useful if you want to ensure no values are being accidentally imported, but still make side-effect imports explicit.
+
+This flag works because you can use `import type` to explicitly create an `import` statement which should never be emitted into JavaScript.

package/docs/tsconfig/include.md

@@ -0,0 +1,66 @@
+---
+display: 'Include'
+oneline: 'Specify a list of glob patterns that match files to be included in compilation.'
+---
+
+Specifies an array of filenames or patterns to include in the program.
+These filenames are resolved relative to the directory containing the `tsconfig.json` file.
+
+```json
+{
+  "include": ["src/**/*", "tests/**/*"]
+}
+```
+
+Which would include:
+
+<!-- TODO: #135
+```diff
+  .
+- ├── scripts
+- │   ├── lint.ts
+- │   ├── update_deps.ts
+- │   └── utils.ts
++ ├── src
++ │   ├── client
++ │   │    ├── index.ts
++ │   │    └── utils.ts
++ │   ├── server
++ │   │    └── index.ts
++ ├── tests
++ │   ├── app.test.ts
++ │   ├── utils.ts
++ │   └── tests.d.ts
+- ├── package.json
+- ├── tsconfig.json
+- └── yarn.lock
+``` -->
+
+```
+.
+├── scripts                ⨯
+│   ├── lint.ts            ⨯
+│   ├── update_deps.ts     ⨯
+│   └── utils.ts           ⨯
+├── src                    ✓
+│   ├── client             ✓
+│   │    ├── index.ts      ✓
+│   │    └── utils.ts      ✓
+│   ├── server             ✓
+│   │    └── index.ts      ✓
+├── tests                  ✓
+│   ├── app.test.ts        ✓
+│   ├── utils.ts           ✓
+│   └── tests.d.ts         ✓
+├── package.json
+├── tsconfig.json
+└── yarn.lock
+```
+
+`include` and `exclude` support wildcard characters to make glob patterns:
+
+- `*` matches zero or more characters (excluding directory separators)
+- `?` matches any one character (excluding directory separators)
+- `**/` matches any directory nested to any level
+
+If the last path segment in a pattern does not contain a file extension or wildcard character, then it is treated as a directory, and files with supported extensions inside that directory are included (e.g. `.ts`, `.tsx`, and `.d.ts` by default, with `.js` and `.jsx` if [`allowJs`](#allowJs) is set to true).

package/docs/tsconfig/incremental.md

@@ -0,0 +1,10 @@
+---
+display: 'Incremental'
+oneline: 'Save .tsbuildinfo files to allow for incremental compilation of projects.'
+---
+
+Tells TypeScript to save information about the project graph from the last compilation to files stored on disk. This
+creates a series of `.tsbuildinfo` files in the same folder as your compilation output. They are not used by your
+JavaScript at runtime and can be safely deleted. You can read more about the flag in the [3.4 release notes](/docs/handbook/release-notes/typescript-3-4.html#faster-subsequent-builds-with-the---incremental-flag).
+
+To control which folders you want to the files to be built to, use the config option [`tsBuildInfoFile`](#tsBuildInfoFile).