# Preflight & Diagnostics

Before any conformance changes are applied, xtarterize runs a series of validation checks. After changes, it can also diagnose potential issues with your project's tooling setup.

## Preflight Checks

Every command that modifies or inspects your project (`init`, `sync`, `diff`, `check`, `add`, `list`) runs preflight checks first via `runPreflight(cwd)`.

### Validations

| Check | Requirement | Error Code |
|-------|-------------|------------|
| [`package.json`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json) exists | Project root must contain a `package.json` | `MISSING_PACKAGE_JSON` |
| [`name`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#name) field present | `package.json` must have a `"name"` field | `INVALID_PACKAGE_JSON` |
| [Git](https://git-scm.com/) repository | [`.git`](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F) directory must exist | `MISSING_GIT` |

### Behavior

If preflight checks fail, the CLI exits with code `1` and displays all errors with hints:

```
✖ Preflight checks failed

  ✗ No package.json found
    Run xtarterize init from the root of a JS/TS project.

  ✗ No .git directory found
    Initialize a git repository with "git init" before running xtarterize.
```
**Note:** Preflight errors are non-destructive — no files are modified if checks fail.

## Diagnostics

The `check` command with `--verbose` flag runs additional diagnostics to surface potential issues:

### Conflict Checks

Detects incompatible or redundant tooling configurations:

| Check | Condition | Status |
|-------|-----------|--------|
| Biome + ESLint | Both [`@biomejs/biome`](https://biomejs.dev/) and [`eslint`](https://eslint.org/) in dependencies | `warn` |
| Biome + Prettier | Both [`@biomejs/biome`](https://biomejs.dev/) and [`prettier`](https://prettier.io/) in dependencies | `warn` |
| Legacy ESLint config | [`.eslintrc.*`](https://eslint.org/docs/latest/use/configure/configuration-files-deprecated) file exists | `warn` |
| No conflicts | None of the above | `pass` |

### Tool Installation Checks

Verifies that tools listed in [`package.json`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json) [`dependencies`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#dependencies)/[`devDependencies`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#devdependencies) are actually installed in [`node_modules`](https://docs.npmjs.com/cli/v10/configuring-npm/folders#node-modules):

| Tool | Dependency | Command Checked |
|------|------------|-----------------|
| [Biome](https://biomejs.dev/) | [`@biomejs/biome`](https://www.npmjs.com/package/@biomejs/biome) | [`biome --version`](https://biomejs.dev/reference/cli/) |
| [ESLint](https://eslint.org/) | [`eslint`](https://www.npmjs.com/package/eslint) | [`eslint --version`](https://eslint.org/docs/latest/use/command-line-interface) |
| [TypeScript](https://www.typescriptlang.org/) | [`typescript`](https://www.npmjs.com/package/typescript) | [`tsc --version`](https://www.typescriptlang.org/docs/handbook/compiler-options.html) |
| [Commitlint](https://commitlint.js.org/) | [`@commitlint/cli`](https://www.npmjs.com/package/@commitlint/cli) | [`commitlint --version`](https://commitlint.js.org/reference/cli.html) |
| [Knip](https://knip.dev/) | [`knip`](https://www.npmjs.com/package/knip) | [`knip --version`](https://knip.dev/reference/cli/) |

### Diagnostic Output

```
Diagnostics

  ✔ Biome installation — Biome is installed
  ~ ESLint installation — ESLint is in package.json but not installed (run install)
  ~ Conflicting tools — Both Biome and ESLint are configured. Consider using one as primary.
```

## API Reference

### `runPreflight(cwd)`

```typescript
import { runPreflight } from '@xtarterize/core'

const result = await runPreflight('/path/to/project')

if (!result.valid) {
  for (const error of result.errors) {
    console.log(error.code)    // 'MISSING_PACKAGE_JSON'
    console.log(error.message) // 'No package.json found'
    console.log(error.hint)    // 'Run xtarterize init from...'
  }
}
```

### `runConflictChecks(cwd)`

```typescript
import { runConflictChecks } from '@xtarterize/core'

const checks = await runConflictChecks('/path/to/project')

for (const check of checks) {
  console.log(check.name)    // 'Conflicting tools'
  console.log(check.status)  // 'warn' | 'pass' | 'fail'
  console.log(check.message) // 'Both Biome and ESLint are configured...'
}
```

### `runToolInstallationChecks(cwd)`

```typescript
import { runToolInstallationChecks } from '@xtarterize/core'

const checks = await runToolInstallationChecks('/path/to/project')

for (const check of checks) {
  console.log(check.name)    // 'Biome installation'
  console.log(check.status)  // 'pass' | 'warn' | 'fail'
  console.log(check.message) // 'Biome is installed'
}
```

## References

- [Biome Documentation](https://biomejs.dev/) — Fast linter and formatter
- [ESLint Documentation](https://eslint.org/docs/latest/) — Pluggable JavaScript linter
- [Prettier Documentation](https://prettier.io/docs/en/) — Opinionated code formatter
- [ESLint Configuration Files (Deprecated)](https://eslint.org/docs/latest/use/configure/configuration-files-deprecated) — Legacy `.eslintrc` format
- [TypeScript Documentation](https://www.typescriptlang.org/docs/) — Typed JavaScript
- [Commitlint Documentation](https://commitlint.js.org/) — Lint commit messages
- [Knip Documentation](https://knip.dev/) — Find unused files and dependencies

## CI Mode

In CI environments (`CI=true` or `CI=1`), the `--quiet` flag is automatically enabled for all commands, suppressing interactive prompts and verbose output.