@piklv/ftaql-cli 1.0.0

package/@types/ftaql-cli.d.ts

@@ -0,0 +1,140 @@
+declare module "@piklv/ftaql-cli" {
+  /**
+   * Полная структура метрик и анализа для одного исходного файла (1:1 с Rust FileData).
+   */
+  export type AnalyzedFile = {
+    /**
+     * Полный путь или имя исходного файла.
+     */
+    file_name: string;
+    /**
+     * Метрики размера файла.
+     */
+    size_metrics: {
+      /** Количество строк кода в файле (без пустых строк и, опционально, комментариев). */
+      line_count: number;
+    };
+    /**
+     * Метрики сложности файла.
+     */
+    complexity_metrics: {
+      /** Цикломатическая сложность (количество независимых путей исполнения). */
+      cyclomatic: number;
+      /** Метрики Холстеда — количественная оценка сложности кода. */
+      halstead: {
+        uniq_operators: number;
+        uniq_operands: number;
+        total_operators: number;
+        total_operands: number;
+        program_length: number;
+        vocabulary_size: number;
+        volume: number;
+        difficulty: number;
+        effort: number;
+        time: number;
+        bugs: number;
+      };
+    };
+    /**
+     * Метрики связанности (coupling) для файла. Может отсутствовать или быть null, если не применимо.
+     */
+    coupling_metrics?: {
+      /** Входящая связанность (afferent coupling, Ca): сколько других файлов зависят от этого файла. */
+      afferent_coupling: number;
+      /** Исходящая связанность (efferent coupling, Ce): от скольких файлов зависит этот файл. */
+      efferent_coupling: number;
+      /** Instability: Ce / (Ca + Ce). Чем ближе к 1, тем менее устойчив модуль. */
+      instability: number;
+      /** Сила зависимости: карта "путь к файлу" → "количество импортируемых идентификаторов". */
+      dependency_strength: Record<string, number>;
+      /** Информация о циклах в графе зависимостей. */
+      cycles?: {
+        /** ID цикла, в котором участвует файл. Ссылается на `project_analysis.cycles`. */
+        cycle_id?: number;
+        /** ID runtime-цикла, если цикл существует во время выполнения. Ссылается на `project_analysis.runtime_cycles`. */
+        runtime_cycle_id?: number;
+      };
+    } | null;
+    /**
+     * Итоговые оценки файла.
+     */
+    scores: {
+      /** Итоговый File Score (чем ниже, тем лучше). */
+      file_score: number;
+      /** Итоговый Coupling Score (чем ниже, тем лучше). */
+      coupling_score: number;
+    };
+  };
+
+  /**
+   * Информация о циклических зависимостях (сильно связанных компонентах) в проекте.
+   */
+  export type CycleInfo = {
+    /** Уникальный идентификатор цикла. */
+    id: number;
+    /** Количество файлов в цикле. */
+    size: number;
+    /**
+     * Граф цикла, где ключи верхнего и вложенного уровней - это индексы из
+     * `project_analysis.cycle_members`, а значения - вес связи между файлами.
+     */
+    graph: Record<string, Record<string, number>>;
+  };
+
+  /**
+   * Глобальные метрики и анализ для всего проекта.
+   */
+  export type ProjectAnalysis = {
+    /** Общий отсортированный список файлов, участвующих хотя бы в одном цикле. */
+    cycle_members: string[];
+    /** Список всех обнаруженных в проекте циклических зависимостей. */
+    cycles: CycleInfo[];
+    /** Список циклов, которые сохраняются во время выполнения. */
+    runtime_cycles: CycleInfo[];
+  };
+
+  /**
+   * Корневой объект, возвращаемый FtaQl при анализе в формате JSON.
+   */
+  export type FtaQlJsonOutput = {
+    /** Глобальный анализ проекта. */
+    project_analysis: ProjectAnalysis;
+    /** Список проанализированных файлов. */
+    findings: AnalyzedFile[];
+  };
+
+  /**
+   * Options for persisting a project analysis snapshot into SQLite.
+   *
+   * `dbPath` is required. The remaining fields are stored as metadata on the analysis run.
+   */
+  export type FtaQlRunOptions = {
+    /**
+     * Path to the SQLite database file that should receive the snapshot.
+     */
+    dbPath: string;
+    /**
+     * Optional custom path to `ftaql.json`.
+     */
+    configPath?: string;
+    /**
+     * Optional revision identifier, for example a git commit SHA.
+     */
+    revision?: string;
+    /**
+     * Optional human-readable label such as branch or tag.
+     */
+    ref?: string;
+  };
+
+  /**
+   * Runs the project analysis for the given project and persists the result into SQLite.
+   *
+   * @param projectPath - The path to the root of the project to analyze
+   * @param options - SQLite persistence options. `dbPath` is required.
+   */
+  export function runFtaQl(
+    projectPath: string,
+    options: FtaQlRunOptions
+  ): string;
+}

package/README.md

@@ -0,0 +1,260 @@
+# FtaQl
+
+[English](https://github.com/pikulev/ftaql/blob/main/README.md) | [Русский](https://github.com/pikulev/ftaql/blob/main/README.ru.md)
+
+FtaQl helps you see where risk is actually accumulating in a TS/JS project. It walks the repository, stores a snapshot in SQLite, and turns code analysis into plain SQL instead of guesswork.
+
+After one run you can ask which files stay expensive across revisions, where coupling keeps growing, and when runtime cycles first appeared. That makes it useful for refactors, CI, and history analysis when you need an accumulated dataset instead of a one-off report.
+
+The core is written in Rust, so repeated runs across large codebases and revision history stay practical. On Apple M1 hardware FtaQl can analyze up to **3000 files per second**.
+
+## What FtaQl Collects
+
+For project-level analysis through the native CLI and Node wrapper, FtaQl stores:
+
+| Metric / artifact | What it means |
+| --- | --- |
+| `file_score` | A composite score for a file based on its own metrics. |
+| `coupling_score` | A composite score for relationship risk in the context of the whole project. |
+| Cyclomatic complexity | How many independent execution paths the code contains. |
+| Halstead metrics | Operator/operand metrics that help estimate code volume and complexity. |
+| Afferent and efferent coupling | Who depends on the file, and how many files the file depends on. |
+| Dependency strength | How tight module-to-module relationships are. |
+| Full-graph cycles | Cycles in the whole project dependency graph, including type-only edges. |
+| `runtime` cycles | Cycles over dependencies that actually participate in execution. |
+| SQLite snapshots | Normalized runs for SQL queries and historical comparisons. |
+
+Detailed formulas, caveats, and interpretation notes are documented in [`docs/scoring/en.md`](https://github.com/pikulev/ftaql/blob/main/docs/scoring/en.md).
+
+A `runtime` cycle is a cyclic dependency through runtime entities. A full-graph cycle can include type-only dependencies, which may hurt tooling and architecture even when runtime is unaffected.
+
+## Quickstart: run -> persist -> query
+
+Project-level analysis is available through the native CLI and the Node.js wrapper. The WASM build analyzes a single file and returns JSON for that file only.
+In WASM, `coupling_score` is always `0.0`, and there is no project-level dependency graph or cycle analysis.
+
+The basic loop is simple: persist a snapshot to SQLite, attach `revision` and `ref` when needed, then query the accumulated runs with SQL.
+
+Persist the current checkout:
+
+```bash
+npx @piklv/ftaql-cli path/to/project --db ./ftaql.sqlite
+```
+
+Append revision metadata as you collect more snapshots:
+
+```bash
+npx @piklv/ftaql-cli path/to/project \
+  --db ./ftaql.sqlite \
+  --revision "$(git rev-parse HEAD)" \
+  --ref main
+```
+
+Use a custom config file when needed:
+
+```bash
+npx @piklv/ftaql-cli path/to/project \
+  --db ./ftaql.sqlite \
+  --config-path ./path/to/ftaql.json
+```
+
+Main options:
+
+- `--db`
+- `--config-path`
+- `--revision`
+- `--ref`
+
+When you append multiple runs into the same SQLite database:
+
+- `--revision` stores the exact snapshot identifier, usually a commit SHA
+- `--ref` stores a human-readable branch, tag, or channel label such as `main`, `release/1.2`, or `nightly`
+- using both lets you compare exact snapshots while still grouping runs by branch or release line
+
+## Querying the Snapshot History
+
+Once snapshots are in SQLite, the interesting part starts.
+
+Worst files in the latest snapshot:
+
+```sql
+SELECT file_path, file_score, coupling_score
+FROM files
+WHERE run_id = (SELECT MAX(id) FROM analysis_runs)
+ORDER BY file_score DESC, coupling_score DESC
+LIMIT 20;
+```
+
+If your team prefers buckets right away, you can layer empirical ranks on top of the same columns. This is not an official FtaQl scale, just one example of a project-level interpretation, so the thresholds should be tuned to your own codebase:
+
+```sql
+SELECT
+  file_path,
+  file_score,
+  CASE
+    WHEN file_score <= 50 THEN 'OK'
+    WHEN file_score <= 60 THEN 'Could be better'
+    ELSE 'Needs improvement'
+  END AS file_rank,
+  coupling_score,
+  CASE
+    WHEN coupling_score <= 100 THEN 'OK'
+    WHEN coupling_score <= 200 THEN 'Could be better'
+    ELSE 'Needs improvement'
+  END AS coupling_rank
+FROM files
+WHERE run_id = (SELECT MAX(id) FROM analysis_runs)
+ORDER BY file_score DESC, coupling_score DESC
+LIMIT 20;
+```
+
+Compare average `file_score` across revisions on one branch:
+
+```sql
+SELECT ar.revision, AVG(f.file_score) AS avg_file_score
+FROM analysis_runs ar
+JOIN files f ON f.run_id = ar.id
+WHERE ar.ref_label = 'main'
+GROUP BY ar.revision
+ORDER BY ar.created_at;
+```
+
+Inspect runtime cycles for a specific revision:
+
+```sql
+SELECT cf.cycle_id, cf.file_path
+FROM cycle_files cf
+JOIN analysis_runs ar ON ar.id = cf.run_id
+WHERE ar.revision = 'abc123'
+  AND cf.cycle_kind = 'runtime'
+ORDER BY cf.cycle_id, cf.file_path;
+```
+
+Shape coupling hotspots into JSON for downstream tooling:
+
+```sql
+SELECT json_group_array(
+  json_object(
+    'file_path', hotspot.file_path,
+    'file_score', hotspot.file_score,
+    'coupling_score', hotspot.coupling_score
+  )
+) AS hotspots
+FROM (
+  SELECT file_path, file_score, coupling_score
+  FROM files
+  WHERE run_id = (SELECT MAX(id) FROM analysis_runs)
+  ORDER BY coupling_score DESC, file_score DESC
+  LIMIT 10
+) AS hotspot;
+```
+
+## Typical Use Cases
+
+- Snapshot a large TS/JS monorepo before and after a refactor, then query the worst files instead of guessing where the risk lives.
+- Append runs for many commits or CI builds into the same SQLite database and compare trends by `revision` or `ref`.
+- Use SQL as the analysis layer itself: aggregate hotspots, inspect cycles, or shape rows into JSON payloads for scripts and dashboards.
+
+## What FtaQl Measures
+
+The table above is the fastest way to understand the main metrics, while formulas and caveats live in [`docs/scoring/en.md`](https://github.com/pikulev/ftaql/blob/main/docs/scoring/en.md). In practice, most teams start from three views:
+
+- `file_score`, when they want the quickest list of the heaviest files
+- `coupling_score`, when they want to see where project relationships create the most risk
+- full-graph cycles and `runtime` cycles, when they need to separate architectural smells from runtime trouble
+
+## What Gets Persisted
+
+FtaQl stores normalized project snapshots in SQLite. The core tables are:
+
+- `analysis_runs` for run metadata and resolved config
+- `files` for per-file metrics
+- `file_dependencies` for dependency edges between analyzed files
+- `cycles`, `cycle_files`, and `cycle_edges` for normalized cycle data
+
+That layout is enough to accumulate many revisions in one database and query them with plain SQL. For the full contract, see [`docs/sqlite-output/en.md`](https://github.com/pikulev/ftaql/blob/main/docs/sqlite-output/en.md).
+
+## Using FtaQl In Package Scripts
+
+Install `@piklv/ftaql-cli`:
+
+```bash
+yarn add -D @piklv/ftaql-cli
+# or
+npm install --save-dev @piklv/ftaql-cli
+# or
+pnpm add -D @piklv/ftaql-cli
+```
+
+Then add a script:
+
+```json
+{
+  "scripts": {
+    "ftaql": "ftaql . --db ./ftaql.sqlite"
+  }
+}
+```
+
+## Using FtaQl From Code
+
+`@piklv/ftaql-cli` also exports `runFtaQl(projectPath, options)`.
+
+```javascript
+import { runFtaQl } from "@piklv/ftaql-cli";
+// CommonJS alternative:
+// const { runFtaQl } = require("@piklv/ftaql-cli");
+
+const output = runFtaQl("path/to/project", {
+  dbPath: "./ftaql.sqlite",
+  revision: process.env.GIT_SHA,
+  ref: process.env.GIT_BRANCH,
+});
+
+console.log(output);
+```
+
+Important notes about the Node.js wrapper:
+
+- `options.dbPath` is required
+- the wrapper persists a snapshot and returns the CLI summary from stdout
+- `configPath`, `revision`, and `ref` are forwarded to the native binary
+
+## Configuration
+
+By default, the native CLI looks for `ftaql.json` in the analyzed project root. You can override that path with `--config-path`.
+
+The `ftaql.json` file controls analysis behavior such as:
+
+- `extensions`
+- `exclude_filenames`
+- `exclude_directories`
+- `score_cap`
+- `include_comments`
+- `exclude_under`
+
+FtaQl also auto-detects `tsconfig.json` and `jsconfig.json` files when resolving imports. It supports:
+
+- `compilerOptions.paths`
+- `compilerOptions.baseUrl`
+- inherited configs via `extends`
+- project references discovered through the resolver
+
+For monorepo and nested-config examples, see [`docs/usage-patterns/en.md`](https://github.com/pikulev/ftaql/blob/main/docs/usage-patterns/en.md). For the exact config contract, see [`docs/configuration/en.md`](https://github.com/pikulev/ftaql/blob/main/docs/configuration/en.md).
+
+## WebAssembly
+
+The `@piklv/ftaql-wasm` package is intended for browser usage and analyzes one source file at a time:
+
+- input: source code string
+- output: JSON string for a single file
+- no filesystem access
+- no project-level coupling analysis
+
+## Docs
+
+Read the full documentation in [`docs/`](https://github.com/pikulev/ftaql/tree/main/docs), especially [`docs/overview/en.md`](https://github.com/pikulev/ftaql/blob/main/docs/overview/en.md).
+
+## License
+
+MIT

package/binaries/README.md

@@ -0,0 +1 @@
+This directory must contain the ftaql crate binaries at publish time

package/check.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const { exeTargets, plainTargets } = require("./targets");
+
+let missingBinaries = [];
+
+function checkBinaryFile(target, path) {
+  try {
+    fs.readFileSync(path);
+  } catch (e) {
+    missingBinaries.push(target);
+  }
+}
+
+for (let i = 0; i < exeTargets.length; i += 1) {
+  const bin = path.join(__dirname, "binaries", exeTargets[i], "ftaql.exe");
+  checkBinaryFile(exeTargets[i], bin);
+}
+
+for (let i = 0; i < plainTargets.length; i += 1) {
+  const bin = path.join(__dirname, "binaries", plainTargets[i], "ftaql");
+  checkBinaryFile(plainTargets[i], bin);
+}
+
+if (missingBinaries.length > 0) {
+  console.log("The following binaries are missing: \n");
+  missingBinaries.forEach((target) => {
+    console.log("- " + target);
+  });
+  console.log("\n");
+  throw new Error("Check failed");
+}
+
+console.log("All binaries were located");

package/index.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+const { execFileSync } = require("node:child_process");
+const path = require("node:path");
+const fs = require("node:fs");
+
+const platform = process.platform;
+const architecture = process.arch;
+
+function getBinaryPath() {
+  const targetDirectory = path.join(__dirname, "binaries");
+
+  switch (platform) {
+    case "win32":
+      if (architecture === "x64") {
+        return path.join(
+          targetDirectory,
+          "ftaql-x86_64-pc-windows-msvc",
+          "ftaql.exe"
+        );
+      } else if (architecture === "arm64") {
+        return path.join(
+          targetDirectory,
+          "ftaql-aarch64-pc-windows-msvc",
+          "ftaql.exe"
+        );
+      }
+    case "darwin":
+      if (architecture === "x64") {
+        return path.join(targetDirectory, "ftaql-x86_64-apple-darwin", "ftaql");
+      } else if (architecture === "arm64") {
+        return path.join(targetDirectory, "ftaql-aarch64-apple-darwin", "ftaql");
+      }
+    case "linux":
+      if (architecture === "x64") {
+        return path.join(
+          targetDirectory,
+          "ftaql-x86_64-unknown-linux-musl",
+          "ftaql"
+        );
+      } else if (architecture === "arm64") {
+        return path.join(
+          targetDirectory,
+          "ftaql-aarch64-unknown-linux-musl",
+          "ftaql"
+        );
+      } else if (architecture === "arm") {
+        return path.join(
+          targetDirectory,
+          "ftaql-arm-unknown-linux-musleabi",
+          "ftaql"
+        );
+      }
+      break;
+    default:
+      throw new Error("Unsupported platform: " + platform);
+  }
+
+  throw new Error("Binary not found for the current platform");
+}
+
+function setUnixPerms(binaryPath) {
+  if (platform === "darwin" || platform === "linux") {
+    try {
+      fs.chmodSync(binaryPath, "755");
+    } catch (e) {
+      console.warn("Could not chmod ftaql binary: ", e);
+    }
+  }
+}
+
+// Run the binary from code
+// We build arguments that get sent to the binary
+function runFtaQl(project, options) {
+  if (!options || !options.dbPath) {
+    throw new Error("runFtaQl(project, options) requires options.dbPath");
+  }
+
+  const binaryPath = getBinaryPath();
+  setUnixPerms(binaryPath);
+  const binaryArgs = [project, "--db", options.dbPath];
+
+  if (options.configPath) {
+    binaryArgs.push("--config-path", options.configPath);
+  }
+  if (options.revision) {
+    binaryArgs.push("--revision", options.revision);
+  }
+  if (options.ref) {
+    binaryArgs.push("--ref", options.ref);
+  }
+
+  const result = execFileSync(binaryPath, binaryArgs);
+  return result.toString();
+}
+
+// Run the binary directly if executed as a standalone script
+// Arguments are directly forwarded to the binary
+if (require.main === module) {
+  const args = process.argv.slice(2); // Exclude the first two arguments (node binary and project path)
+  const binaryPath = getBinaryPath();
+  setUnixPerms(binaryPath);
+
+  execFileSync(binaryPath, args, { stdio: "inherit" });
+}
+
+module.exports.runFtaQl = runFtaQl;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@piklv/ftaql-cli",
+  "version": "1.0.0",
+  "description": "FtaQl is a super-fast TypeScript static analysis tool written in Rust",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pikulev/ftaql.git"
+  },
+  "author": "vasya pikulev",
+  "homepage": "https://github.com/pikulev/ftaql#readme",
+  "bugs": {
+    "url": "https://github.com/pikulev/ftaql/issues"
+  },
+  "license": "MIT",
+  "main": "index.js",
+  "bin": {
+    "ftaql": "index.js"
+  },
+  "types": "@types/ftaql-cli.d.ts",
+  "files": [
+    "index.js",
+    "check.js",
+    "targets.js",
+    "README.md",
+    "@types",
+    "binaries"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepublishOnly": "node check.js"
+  }
+}

package/targets.js

@@ -0,0 +1,18 @@
+// Windows
+const exeTargets = [
+  "ftaql-aarch64-pc-windows-msvc",
+  "ftaql-x86_64-pc-windows-msvc",
+];
+
+const plainTargets = [
+  // macOS
+  "ftaql-x86_64-apple-darwin",
+  "ftaql-aarch64-apple-darwin",
+  // Linux
+  "ftaql-x86_64-unknown-linux-musl",
+  "ftaql-aarch64-unknown-linux-musl",
+  "ftaql-arm-unknown-linux-musleabi",
+];
+
+module.exports.exeTargets = exeTargets;
+module.exports.plainTargets = plainTargets;