Fast TypeScript Analyzer CLI

Common errors

• Error: Command not found: fta-cli

  cause `fta-cli` is not installed globally or `npx` cannot locate it.
  fix Ensure you run `npx fta-cli ...` to execute the package without global installation, or install it globally with `npm install -g fta-cli` if preferred.

• Error: The specified path does not exist: /path/to/nonexistent/project

  cause The directory or file path provided to `fta-cli` does not exist on your file system.
  fix Double-check the provided path. Ensure it's an existing directory or file, and that your current working directory is correct if using relative paths.

• Failed to parse TypeScript/JavaScript file: Syntax Error...

  cause `fta-cli` encountered modern or non-standard syntax that its underlying SWC parser version does not yet support.
  fix Update `fta-cli` to the latest version. Version 3.0.0 and above significantly improve support for modern syntax due to SWC upgrades. If the issue persists, report it to the `fta-cli` GitHub repository.

Warnings

• breaking Version 3.0.0 includes an upgrade to underlying SWC libraries. This results in material changes to how operands and operators are counted, leading to different FTA scores compared to previous versions. It may require recalibrating thresholds or expectations for existing projects.
  Fix: Review your analysis output and adjust any custom thresholds or baseline expectations for FTA scores to account for the updated calculation methodology.
• breaking Version 2.0.0 introduced corrections to the Halstead calculations. This change materially affects the reported Halstead and FTA scores, making direct comparison with results from v1.x inaccurate.
  Fix: Re-run analysis on your codebase with v2.0.0+ to establish new baselines for Halstead and FTA scores. Do not directly compare scores from v1.x with v2.x or v3.x.
• breaking In v1.0.0, the `include_comments` option's default value changed to `false`, meaning comments are no longer included in scoring by default. Also, the `exclude_under` option was added with a default of `6`, excluding files under 6 lines of code.
  Fix: If you relied on comments being included in scores or need to analyze very small files, explicitly set `--include-comments true` or `--exclude-under 0` when running the CLI. The `output_limit` option's behavior also changed in v1.0.0, now only affecting `table` format output.

Install

• npm install fta-cli npm
• yarn add fta-cli yarn
• pnpm add fta-cli pnpm

Imports

• FtaAnalysisOptions

  import type { FtaAnalysisOptions } from 'fta-cli'

  While primarily a CLI, this package ships TypeScript types. `FtaAnalysisOptions` might be used for programmatic configuration when integrating the core logic or interpreting results.
• FtaReportEntry

  import type { FtaReportEntry } from 'fta-cli'

  Represents a single row of the analysis output, containing metrics like line count, FTA score, and assessment. Useful for typing programmatic handling of CLI output.
• FtaAssessment

  import type { FtaAssessment } from 'fta-cli'

  A type representing the assessment category (e.g., 'OK', 'Needs improvement'). For robust type-checking when processing FTA results.
• ftaCliCommand
  wrong:

  import { ftaCliCommand } from 'fta-cli'

  correct:
  The `fta-cli` package is primarily a command-line interface. There is no direct JavaScript/TypeScript function to import and run its CLI commands programmatically within your code. Instead, use `npx fta-cli` or `child_process.spawn('fta-cli', ...)`.

Quickstart

Demonstrates the basic usage of the `fta-cli` command-line tool to analyze a project directory or specific files.

npx fta-cli ./src --format table --exclude-under 10

# Example of running against a specific file or directory
npx fta-cli my-project/index.ts

# To analyze your current project directory
npx fta-cli .