diff --git a/docs.json b/docs.json index 00b03a59..f678f5fe 100644 --- a/docs.json +++ b/docs.json @@ -2145,17 +2145,45 @@ "group": "Rust", "pages": [ "sdks/rust/api/README", - "sdks/rust/api/resq-ai", + "sdks/rust/api/resq-ai/config", + "sdks/rust/api/resq-ai/index", + "sdks/rust/api/resq-ai/provider", + "sdks/rust/api/resq-ai/token", "sdks/rust/api/resq-bin", "sdks/rust/api/resq-clean", - "sdks/rust/api/resq-cli", + "sdks/rust/api/resq-cli/commands", + "sdks/rust/api/resq-cli/commands/audit", + "sdks/rust/api/resq-cli/commands/commit", + "sdks/rust/api/resq-cli/commands/completions", + "sdks/rust/api/resq-cli/commands/copyright", + "sdks/rust/api/resq-cli/commands/dev", + "sdks/rust/api/resq-cli/commands/docs", + "sdks/rust/api/resq-cli/commands/explore", + "sdks/rust/api/resq-cli/commands/format", + "sdks/rust/api/resq-cli/commands/hook_templates", + "sdks/rust/api/resq-cli/commands/hooks", + "sdks/rust/api/resq-cli/commands/pre_commit", + "sdks/rust/api/resq-cli/commands/secrets", + "sdks/rust/api/resq-cli/commands/version", + "sdks/rust/api/resq-cli/gitignore", + "sdks/rust/api/resq-cli/index", + "sdks/rust/api/resq-cli/resq_cli", + "sdks/rust/api/resq-cli/utils", "sdks/rust/api/resq-deploy", - "sdks/rust/api/resq-dsa", + "sdks/rust/api/resq-dsa/bloom", + "sdks/rust/api/resq-dsa/count_min", + "sdks/rust/api/resq-dsa/graph", + "sdks/rust/api/resq-dsa/heap", + "sdks/rust/api/resq-dsa/index", + "sdks/rust/api/resq-dsa/resq_dsa", + "sdks/rust/api/resq-dsa/trie", "sdks/rust/api/resq-flame", "sdks/rust/api/resq-health", "sdks/rust/api/resq-logs", "sdks/rust/api/resq-perf", - "sdks/rust/api/resq-tui" + "sdks/rust/api/resq-tui/index", + "sdks/rust/api/resq-tui/resq_tui", + "sdks/rust/api/resq-tui/terminal" ] }, { @@ -2494,4 +2522,4 @@ "website": "https://resq.software" } } -} +} \ No newline at end of file diff --git a/sdks/rust/api/README.mdx b/sdks/rust/api/README.mdx index c50c4934..32220f4a 100644 --- a/sdks/rust/api/README.mdx +++ b/sdks/rust/api/README.mdx @@ -2,7 +2,7 @@ Auto-generated reference for [`resq-software/crates`](https://github.com/resq-software/crates) at ref `master`. -Each entry below lists a crate published from the workspace. Click through for the README plus a link to the canonical [docs.rs](https://docs.rs) API reference. +Each entry below lists a crate from the workspace. Library crates link to their full rendered API reference; binary-only crates show their README and link to [docs.rs](https://docs.rs). ## Crates diff --git a/sdks/rust/api/_pages.json b/sdks/rust/api/_pages.json index de70c342..771c253a 100644 --- a/sdks/rust/api/_pages.json +++ b/sdks/rust/api/_pages.json @@ -1,13 +1,41 @@ [ - "resq-ai", + "resq-ai/config", + "resq-ai/index", + "resq-ai/provider", + "resq-ai/token", "resq-bin", "resq-clean", - "resq-cli", + "resq-cli/commands", + "resq-cli/commands/audit", + "resq-cli/commands/commit", + "resq-cli/commands/completions", + "resq-cli/commands/copyright", + "resq-cli/commands/dev", + "resq-cli/commands/docs", + "resq-cli/commands/explore", + "resq-cli/commands/format", + "resq-cli/commands/hook_templates", + "resq-cli/commands/hooks", + "resq-cli/commands/pre_commit", + "resq-cli/commands/secrets", + "resq-cli/commands/version", + "resq-cli/gitignore", + "resq-cli/index", + "resq-cli/resq_cli", + "resq-cli/utils", "resq-deploy", - "resq-dsa", + "resq-dsa/bloom", + "resq-dsa/count_min", + "resq-dsa/graph", + "resq-dsa/heap", + "resq-dsa/index", + "resq-dsa/resq_dsa", + "resq-dsa/trie", "resq-flame", "resq-health", "resq-logs", "resq-perf", - "resq-tui" + "resq-tui/index", + "resq-tui/resq_tui", + "resq-tui/terminal" ] diff --git a/sdks/rust/api/resq-ai.md b/sdks/rust/api/resq-ai.md deleted file mode 100644 index 2038ebc6..00000000 --- a/sdks/rust/api/resq-ai.md +++ /dev/null @@ -1,10 +0,0 @@ -# resq-ai - -> **Version:** `v0.1.0` · **License:** `Apache-2.0` · **Crate:** [crates.io](https://crates.io/crates/resq-ai) · **API docs:** [docs.rs](https://docs.rs/resq-ai/0.1.0) - -Multi-provider LLM abstraction for ResQ developer tools - -_No README.md in source repo._ - -See [docs.rs](https://docs.rs/resq-ai/0.1.0) for full API reference. - diff --git a/sdks/rust/api/resq-ai/config.md b/sdks/rust/api/resq-ai/config.md new file mode 100644 index 00000000..356f9f4f --- /dev/null +++ b/sdks/rust/api/resq-ai/config.md @@ -0,0 +1,56 @@ +**resq_ai > config** + +# Module: config + +## Contents + +**Structs** + +- [`AiConfig`](#aiconfig) - AI configuration. + +**Functions** + +- [`load_config`](#load_config) - Load config with cascade: env vars -> ~/.resq/ai.toml -> .resq/ai.toml. + +--- + +## resq_ai::config::AiConfig + +*Struct* + +AI configuration. + +**Fields:** +- `provider: crate::provider::Provider` - Selected provider. +- `model: String` - Model identifier. +- `base_url: Option` - Base URL override. +- `max_tokens: u32` - Max tokens in response. +- `timeout_secs: u64` - HTTP request timeout in seconds. + +**Methods:** + +- `fn api_key(self: &Self) -> &str` - Access the API key. + +**Trait Implementations:** + +- **Debug** + - `fn fmt(self: &Self, f: & mut fmt::Formatter) -> fmt::Result` + + + +## resq_ai::config::load_config + +*Function* + +Load config with cascade: env vars -> ~/.resq/ai.toml -> .resq/ai.toml. + +# Errors + +Returns an error if no API key is found for the selected provider. + +```rust +fn load_config() -> anyhow::Result +``` + + + diff --git a/sdks/rust/api/resq-ai/index.md b/sdks/rust/api/resq-ai/index.md new file mode 100644 index 00000000..11de311b --- /dev/null +++ b/sdks/rust/api/resq-ai/index.md @@ -0,0 +1,23 @@ +# resq_ai + +> **Version:** `v0.1.0` · **License:** `Apache-2.0` · **Crate:** [crates.io](https://crates.io/crates/resq-ai) · **API docs:** [docs.rs](https://docs.rs/resq-ai/0.1.0) + +Multi-provider LLM abstraction for `ResQ` developer tools. + +Supports Anthropic, `OpenAI`, and Google Gemini APIs with a unified +`complete()` interface and cascading config resolution. + +## Modules + +### [`config`](config.md) + +*1 function, 1 struct* + +### [`provider`](provider.md) + +*1 enum, 1 function* + +### [`token`](token.md) + +*2 functions* + diff --git a/sdks/rust/api/resq-ai/provider.md b/sdks/rust/api/resq-ai/provider.md new file mode 100644 index 00000000..de3b1ae8 --- /dev/null +++ b/sdks/rust/api/resq-ai/provider.md @@ -0,0 +1,67 @@ +**resq_ai > provider** + +# Module: provider + +## Contents + +**Enums** + +- [`Provider`](#provider) - Supported LLM providers. + +**Functions** + +- [`complete`](#complete) - Send a completion request to the configured provider. + +--- + +## resq_ai::provider::Provider + +*Enum* + +Supported LLM providers. + +**Variants:** +- `Anthropic` - Anthropic Claude API +- `OpenAi` - OpenAI-compatible Chat Completions API +- `Gemini` - Google Gemini API + +**Methods:** + +- `fn default_model(self: &Self) -> &'static str` - Default model for this provider. +- `fn default_base_url(self: &Self) -> &'static str` - Default base URL for this provider. +- `fn api_key_env_var(self: &Self) -> &'static str` - Environment variable name for the API key. + +**Traits:** Eq, Copy + +**Trait Implementations:** + +- **Deserialize** + - `fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result::Error>` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` +- **Clone** + - `fn clone(self: &Self) -> Provider` +- **PartialEq** + - `fn eq(self: &Self, other: &Provider) -> bool` + + + +## resq_ai::provider::complete + +*Function* + +Send a completion request to the configured provider. + +A single [`reqwest::Client`] is reused across calls to benefit from +connection pooling. + +# Errors + +Returns an error on network failure, auth failure, or empty response. + +```rust +fn complete(config: &super::AiConfig, system: &str, user: &str) -> anyhow::Result +``` + + + diff --git a/sdks/rust/api/resq-ai/token.md b/sdks/rust/api/resq-ai/token.md new file mode 100644 index 00000000..9ac7ca55 --- /dev/null +++ b/sdks/rust/api/resq-ai/token.md @@ -0,0 +1,38 @@ +**resq_ai > token** + +# Module: token + +## Contents + +**Functions** + +- [`estimate_tokens`](#estimate_tokens) - Estimate token count using the chars/4 heuristic. +- [`truncate_to_budget`](#truncate_to_budget) - Truncate text to fit within a token budget. + +--- + +## resq_ai::token::estimate_tokens + +*Function* + +Estimate token count using the chars/4 heuristic. + +```rust +fn estimate_tokens(text: &str) -> usize +``` + + + +## resq_ai::token::truncate_to_budget + +*Function* + +Truncate text to fit within a token budget. +Cuts at line boundaries to avoid broken diff hunks. + +```rust +fn truncate_to_budget(text: &str, max_tokens: usize) -> &str +``` + + + diff --git a/sdks/rust/api/resq-cli.md b/sdks/rust/api/resq-cli.md deleted file mode 100644 index 70e39b85..00000000 --- a/sdks/rust/api/resq-cli.md +++ /dev/null @@ -1,586 +0,0 @@ -# resq-cli - -> **Version:** `v0.3.0` · **License:** `Apache-2.0` · **Crate:** [crates.io](https://crates.io/crates/resq-cli) · **API docs:** [docs.rs](https://docs.rs/resq-cli/0.3.0) - -Developer CLI for the ResQ autonomous drone platform - -## Overview - -[![Crates.io](https://img.shields.io/crates/v/resq-cli.svg)](https://crates.io/crates/resq-cli) -[![License](https://img.shields.io/crates/l/resq-cli.svg)](LICENSE) - -Unified developer CLI for the ResQ platform. Provides commands for license header management, security auditing, secret scanning, dependency cost analysis, image placeholder generation, documentation export, monorepo versioning, and launching a suite of interactive TUI tools. - -## Overview - -`resq` is the single entry point for all ResQ developer tooling. It wraps standalone TUI applications (logs, health, deploy, perf, clean, asm) and provides built-in commands for CI workflows, pre-commit hooks, and repository maintenance. - -```mermaid -graph TD - resq["resq (CLI)"] - - resq --> copyright["copyright"] - resq --> lqip["lqip"] - resq --> audit["audit"] - resq --> cost["cost"] - resq --> secrets["secrets"] - resq --> tree_shake["tree-shake"] - resq --> pre_commit["pre-commit"] - - resq --> dev["dev"] - dev --> kill_ports["dev kill-ports"] - dev --> sync_env["dev sync-env"] - dev --> upgrade["dev upgrade"] - dev --> install_hooks["dev install-hooks"] - - resq --> version["version"] - version --> version_add["version add"] - version --> version_apply["version apply"] - version --> version_check["version check"] - - resq --> docs["docs"] - - resq --> explore["explore (resq-perf)"] - resq --> logs["logs (resq-logs)"] - resq --> health["health (resq-health)"] - resq --> deploy["deploy (resq-deploy)"] - resq --> clean["clean (resq-clean)"] - resq --> asm["asm (resq-bin)"] - - style resq fill:#2563eb,color:#fff - style dev fill:#7c3aed,color:#fff - style version fill:#7c3aed,color:#fff - style explore fill:#059669,color:#fff - style logs fill:#059669,color:#fff - style health fill:#059669,color:#fff - style deploy fill:#059669,color:#fff - style clean fill:#059669,color:#fff - style asm fill:#059669,color:#fff -``` - -**Legend:** Blue = entry point, Purple = commands with subcommands, Green = TUI launchers. - -## Installation - -```bash -# Build from the workspace root -cargo build --release -p resq-cli - -# Install globally -cargo install --path cli - -# Or use the cargo alias (defined in .cargo/config.toml) -cargo resq help -``` - -The binary is installed as `resq` at `target/release/resq`. - -### Cargo Aliases - -The following workspace aliases are defined in `.cargo/config.toml`: - -| Alias | Maps to | -| ----------------- | -------------------- | -| `cargo resq` | `resq` | -| `cargo health` | `resq health` | -| `cargo logs` | `resq logs` | -| `cargo perf` | `resq explore` | -| `cargo deploy` | `resq deploy` | -| `cargo cleanup` | `resq clean` | -| `cargo bin` | `resq asm` | -| `cargo check-all` | workspace check | -| `cargo t` | workspace test | -| `cargo c` | workspace clippy | -| `cargo flame` | `resq-flame` binary | - ---- - -## Commands - -### `copyright` -- License Header Management - -Adds or checks copyright/license headers across all source files in the repository. Supports multiple comment styles (C-style block, XML/HTML, hash-line, double-dash, Elisp, AsciiDoc). Shebangs (`#!/...`) are always preserved at line 0. - -#### Arguments - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `-l, --license ` | `String` | `apache-2.0` | License type: `apache-2.0`, `mit`, `gpl-3.0`, `bsd-3-clause` | -| `-a, --author ` | `String` | `ResQ` | Copyright holder name | -| `-y, --year ` | `String` | current year | Copyright year | -| `--force` | `bool` | `false` | Overwrite existing headers | -| `--dry-run` | `bool` | `false` | Preview changes without writing files | -| `--check` | `bool` | `false` | CI mode -- exits non-zero if any headers are missing | -| `-v, --verbose` | `bool` | `false` | Print detailed processing info | -| `--glob ...` | `Vec` | none | Glob patterns to match files (e.g. `src/**/*.rs`) | -| `--ext ` | `Vec` | none | Comma-separated file extensions to include (e.g. `rs,js,py`) | -| `-e, --exclude ...` | `Vec` | none | Patterns to exclude from processing | - -#### Examples - -```bash -# Check all tracked files (CI -- exits 1 if any missing) -resq copyright --check - -# Preview what would be added without writing -resq copyright --dry-run - -# Add headers to all files missing them -resq copyright - -# Overwrite existing headers with a different license and author -resq copyright --force --license apache-2.0 --author "Acme Corp" --year 2026 - -# Process only Rust and TypeScript files -resq copyright --ext rs,ts - -# Process files matching a glob pattern -resq copyright --glob "crates/**/*.rs" -``` - ---- - -### `lqip` -- Low-Quality Image Placeholders - -Generates tiny base64-encoded data URIs from images for use as blur-up placeholders in web applications. Supports JPEG, PNG, and WebP formats. - -#### Arguments - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `-t, --target ` | `String` | *required* | Directory or file to process | -| `--width ` | `u32` | `20` | Width of the generated LQIP in pixels | -| `--height ` | `u32` | `15` | Height of the generated LQIP in pixels | -| `-r, --recursive` | `bool` | `false` | Recursively search directories for images | -| `--format ` | `String` | `text` | Output format: `text` or `json` | - -#### Examples - -```bash -# Single image -- prints data URI -resq lqip --target hero.jpg - -# Directory of images -- text list -resq lqip --target public/images/ - -# Recursive with JSON output -resq lqip --target public/ --recursive --format json - -# Custom dimensions -resq lqip --target photo.png --width 32 --height 24 -``` - ---- - -### `audit` -- Security & Quality Audit - -Three-pass security and quality sweep covering all language ecosystems. Runs Google OSV Scanner (cross-ecosystem), npm audit-ci, and React Doctor. - -#### Arguments - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `--root ` | `PathBuf` | `.` | Root directory to start search from | -| `--level ` | `String` | `critical` | Minimum npm vulnerability severity to fail on (`critical`, `high`, `moderate`, `low`) | -| `--report-type ` | `String` | `important` | audit-ci report verbosity (`important`, `full`, `summary`) | -| `--skip-prepare` | `bool` | `false` | Skip the yarn.lock generation step required by audit-ci | -| `--skip-npm` | `bool` | `false` | Skip the npm audit-ci pass | -| `--skip-osv` | `bool` | `false` | Skip the Google OSV Scanner pass | -| `--osv-format ` | `String` | `table` | OSV Scanner output format (`table`, `json`, `sarif`, `gh-annotations`) | -| `--skip-react` | `bool` | `false` | Skip the react-doctor pass | -| `--react-target ` | `PathBuf` | `/services/web-dashboard` | Path to the React/Next.js project for react-doctor | -| `--react-diff ` | `String` | none | Only scan React files changed vs this base branch | -| `--react-min-score ` | `u8` | `75` | Minimum react-doctor health score to pass (0-100) | - -#### Examples - -```bash -# Full audit (all three passes) -resq audit - -# Run only the OSV Scanner pass -resq audit --skip-npm --skip-react - -# Strict npm audit (fail on moderate) -resq audit --skip-osv --skip-react --level moderate - -# OSV Scanner with JSON output -resq audit --skip-npm --skip-react --osv-format json - -# React Doctor with custom threshold and diff mode -resq audit --skip-osv --skip-npm --react-min-score 90 --react-diff main -``` - ---- - -### `cost` -- Dependency Size Analysis - -Fetches package sizes from registries (npm, crates.io, PyPI) and categorizes dependencies by download footprint into high (>10 MB), medium (1-10 MB), and low (<1 MB) buckets. Results are saved as JSON files. - -#### Arguments - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `--root ` | `PathBuf` | `.` | Root directory containing project manifest | -| `--output ` | `PathBuf` | `scripts/out` | Output directory for result JSON files | -| `--project-type ` | `String` | auto-detected | Force a specific project type: `node`, `rust`, `python` | - -#### Examples - -```bash -# Auto-detect project type and analyze -resq cost - -# Analyze a specific project directory -resq cost --root services/coordination-hce - -# Force Rust analysis and custom output -resq cost --project-type rust --output reports/deps -``` - ---- - -### `secrets` -- Secret Scanner - -Scans source files for hardcoded credentials, API keys, private keys, tokens, and high-entropy strings. Uses pattern matching with entropy analysis (Shannon entropy with charset-specific thresholds for hex, base64, and alphanumeric strings) and Aho-Corasick multi-pattern matching for performance. - -#### Arguments - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `--root ` | `PathBuf` | `.` | Root directory to scan | -| `--git-only` | `bool` | `true` | Only scan git-tracked files | -| `-v, --verbose` | `bool` | `false` | Show verbose output (print matched content) | -| `--allowlist ` | `PathBuf` | none | Path to allowlist file (one pattern per line) | -| `--staged` | `bool` | `false` | Scan only staged git changes (for pre-commit hook) | -| `--history` | `bool` | `false` | Also scan git history (all commits reachable from HEAD) | -| `--since ` | `String` | none | Limit history scan to commits after this rev/date (e.g. `"30 days ago"`, `"v1.0.0"`) | - -#### Examples - -```bash -# Scan all git-tracked files (default) -resq secrets - -# Only scan staged changes (pre-commit hook) -resq secrets --staged - -# Scan with history and allowlist -resq secrets --history --since "v1.0.0" --allowlist .secrets-allowlist - -# Verbose output showing matched content -resq secrets --verbose -``` - ---- - -### `tree-shake` -- TypeScript Dead Code Removal - -Runs [`tsr`](https://github.com/line/ts-remove-unused) to remove unused TypeScript exports from project entry points. Requires `bun` to be installed. - -#### Arguments - -This command takes no arguments. - -#### Examples - -```bash -resq tree-shake -``` - ---- - -### `dev` -- Development Utilities - -Unified entry point for repository-level development tasks. - -#### Subcommands - -##### `dev kill-ports` -- Kill Processes on Ports - -Finds and terminates processes listening on specified TCP ports. - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `...` | `Vec` | *required* | Ports or ranges (e.g. `8000` or `8000..8010`) | -| `-f, --force` | `bool` | `false` | Use SIGKILL instead of SIGTERM | -| `-y, --yes` | `bool` | `false` | Skip confirmation prompt | - -```bash -# Kill process on port 3000 -resq dev kill-ports 3000 - -# Kill range of ports without confirmation -resq dev kill-ports 8000..8010 --yes - -# Force kill -resq dev kill-ports 3000 --force -``` - -##### `dev sync-env` -- Sync Environment Variables to turbo.json - -Scans `.env.example` files across the monorepo and synchronizes discovered environment variable names into `turbo.json` task configurations. - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `-t, --tasks ` | `String` | `build,dev,start,test` | Comma-separated tasks to update in turbo.json | -| `-d, --dry-run` | `bool` | `false` | Preview changes without writing | -| `--max-depth ` | `usize` | `10` | Maximum directory depth to search | - -```bash -# Sync all environment variables -resq dev sync-env - -# Preview changes -resq dev sync-env --dry-run - -# Sync only for build and dev tasks -resq dev sync-env --tasks build,dev -``` - -##### `dev upgrade` -- Upgrade Dependencies - -Upgrades dependencies across all language silos in the monorepo (Python/uv, Rust/cargo, JS/bun, C++/Conan, C#/dotnet, Nix). - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `` | `String` | `all` | Silo to upgrade: `python`, `rust`, `js`, `cpp`, `csharp`, `nix`, or `all` | - -```bash -# Upgrade all ecosystems -resq dev upgrade - -# Upgrade only Rust dependencies -resq dev upgrade rust - -# Upgrade only JavaScript dependencies -resq dev upgrade js -``` - -##### `dev install-hooks` -- Install Git Hooks - -Configures `git core.hooksPath` to point at the `.git-hooks` directory and makes all hook scripts executable. - -```bash -resq dev install-hooks -``` - ---- - -### `pre-commit` -- Unified Pre-Commit Hook - -Runs a suite of checks suitable for a git pre-commit hook: copyright headers, secret scanning, formatting, audits, and versioning prompts. Includes an interactive TUI progress display. - -#### Arguments - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `--root ` | `PathBuf` | `.` | Project root (defaults to auto-detected) | -| `--skip-audit` | `bool` | `false` | Skip security audit (osv-scanner + npm audit-ci) | -| `--skip-format` | `bool` | `false` | Skip formatting step | -| `--skip-versioning` | `bool` | `false` | Skip changeset/versioning prompt | -| `--max-file-size ` | `u64` | `10485760` (10 MiB) | Maximum file size in bytes | -| `--no-tui` | `bool` | `false` | Disable TUI (plain output for CI or piped stderr) | - -#### Examples - -```bash -# Run all pre-commit checks -resq pre-commit - -# Skip audit and formatting (fast mode) -resq pre-commit --skip-audit --skip-format - -# CI-friendly plain output -resq pre-commit --no-tui -``` - ---- - -### `version` -- Monorepo Versioning - -Manages package versions and changesets across the monorepo using a changeset-based workflow. Supports Cargo.toml, package.json, pyproject.toml, and Directory.Build.props manifests. - -#### Subcommands - -##### `version add` -- Create a Changeset - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `-b, --bump ` | `String` | `patch` | Type of change: `patch`, `minor`, `major` | -| `-m, --message ` | `String` | *required* | Summary of what changed | - -```bash -resq version add --bump minor --message "Add new health check endpoint" -``` - -##### `version apply` -- Apply Version Bumps - -Consumes all pending changesets, determines the highest bump level, updates all manifests, and appends to CHANGELOG.md. - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `--dry-run` | `bool` | `false` | Preview what would change without modifying files | - -```bash -# Apply version bumps -resq version apply - -# Preview only -resq version apply --dry-run -``` - -##### `version check` -- Verify Version Sync - -Checks that all manifest files contain the same version string. - -```bash -resq version check -``` - ---- - -### `docs` -- Documentation Export - -Exports and publishes OpenAPI specifications from the Infrastructure API and Coordination HCE services. - -#### Arguments - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `-e, --export-only` | `bool` | `false` | Only export specs locally without publishing | -| `-p, --publish` | `bool` | `false` | Publish specifications to the documentation repository via GitHub API | -| `--dry-run` | `bool` | `false` | Show what would be done without executing | - -#### Examples - -```bash -# Export specs locally -resq docs --export-only - -# Export and publish to GitHub -resq docs --publish - -# Preview what would happen -resq docs --dry-run -``` - ---- - -### TUI Launchers - -These commands launch standalone TUI applications from the ResQ workspace. Each delegates to a separate binary via `cargo run -p `. - -#### `explore` -- Performance Monitor (resq-perf) - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `` | `String` | `http://localhost:3000/admin/status` | Service URL to monitor | -| `--refresh-ms ` | `u64` | `500` | Refresh rate in milliseconds | - -```bash -resq explore -resq explore http://localhost:8080/status --refresh-ms 1000 -``` - -#### `logs` -- Log Aggregator (resq-logs) - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `--source ` | `String` | `docker` | Log source: `docker` or `file` | -| `--service ` | `String` | none | Filter to a specific service name | - -```bash -resq logs -resq logs --source file --service edge-aeai -``` - -#### `health` -- Health Dashboard (resq-health) - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `-i, --interval ` | `u64` | `5` | Poll interval in seconds | - -```bash -resq health -resq health --interval 10 -``` - -#### `deploy` -- Deployment Manager (resq-deploy) - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `--env ` | `String` | `dev` | Target environment: `dev`, `staging`, `prod` | -| `--k8s` | `bool` | `false` | Use Kubernetes instead of Docker Compose | - -```bash -resq deploy -resq deploy --env staging --k8s -``` - -#### `clean` -- Workspace Cleaner (resq-clean) - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `--dry-run` | `bool` | `false` | Preview what would be deleted without removing anything | - -```bash -resq clean -resq clean --dry-run -``` - -#### `asm` -- Binary Analyzer (resq-bin) - -| Flag / Option | Type | Default | Description | -| --- | --- | --- | --- | -| `--file ` | `String` | none | Analyze a single binary (conflicts with `--dir`) | -| `--dir ` | `String` | none | Analyze binaries under a directory (conflicts with `--file`) | -| `--recursive` | `bool` | `false` | Recursively traverse directory in batch mode | -| `--ext ` | `String` | none | Suffix filter in batch mode (e.g. `.so`, `.o`) | -| `--config ` | `String` | none | Path to resq-bin config TOML | -| `--no-cache` | `bool` | `false` | Disable cache reads/writes | -| `--rebuild-cache` | `bool` | `false` | Force cache rebuild | -| `--no-disasm` | `bool` | `false` | Only collect metadata, skip disassembly | -| `--max-functions ` | `usize` | none | Maximum functions to disassemble per binary | -| `--tui` | `bool` | `false` | Force interactive TUI mode | -| `--plain` | `bool` | `false` | Use non-interactive plain output | -| `--json` | `bool` | `false` | Emit JSON report output | - -```bash -resq asm --file target/release/resq -resq asm --dir target/release/ --recursive --ext .so -resq asm --file mylib.o --plain --no-cache -resq asm --dir . --recursive --json --max-functions 100 -``` - ---- - -## Environment Variables - -| Variable | Used By | Description | -| --- | --- | --- | -| `RUST_LOG` | all commands | Controls `tracing-subscriber` log level (e.g. `debug`, `info`, `warn`) | -| `GH_TOKEN` / `GITHUB_TOKEN` | `docs --publish` | GitHub API authentication for publishing specs | - -The `pre-commit` and `audit` commands shell out to external tools (`osv-scanner`, `bun`, `npx`, `audit-ci`, `react-doctor`) which may read their own environment variables. - -## Configuration - -- **Project root detection**: The CLI walks up the directory tree looking for `resQ.sln`, `package.json`, `Cargo.toml`, `pyproject.toml`, or `.git` to locate the project root. -- **Gitignore integration**: The `secrets` and `copyright` commands parse `.gitignore` for directory exclusion. When `.gitignore` is missing, a built-in fallback list is used (`node_modules`, `.git`, `dist`, `build`, `.next`, `target`, `__pycache__`, `.venv`, `venv`, `vendor`, `.turbo`, `coverage`). -- **OSV Scanner config**: If `osv-scanner.toml` exists at the project root, it is passed automatically to the `audit` command. -- **Secrets allowlist**: Create a text file with one pattern per line and pass it via `--allowlist`. -- **Changesets**: Version changesets are stored as markdown files in `.changesets/` at the repository root. - -## Exit Codes - -| Code | Meaning | -| --- | --- | -| `0` | Success | -| `1` | Command failed (e.g. audit found vulnerabilities, copyright headers missing in `--check` mode, secrets detected, versions out of sync) | -| `2` | CLI argument parsing error | - -## License - -Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/resq-software/crates/blob/master/LICENSE) for the full text. - diff --git a/sdks/rust/api/resq-cli/commands.md b/sdks/rust/api/resq-cli/commands.md new file mode 100644 index 00000000..e75b615d --- /dev/null +++ b/sdks/rust/api/resq-cli/commands.md @@ -0,0 +1,149 @@ +**resq_cli > commands** + +# Module: commands + +## Contents + +**Modules** + +- [`audit`](#audit) - Blockchain event auditing. +- [`commit`](#commit) - AI-powered commit message generation. +- [`completions`](#completions) - Shell-completion emitter (`resq completions `). +- [`copyright`](#copyright) - Copyright header management. +- [`dev`](#dev) - Development server management. +- [`docs`](#docs) - Documentation management and publication. +- [`explore`](#explore) - Service exploration and operations. +- [`format`](#format) - Polyglot source formatting (Rust, TS, Python, C++, C#). +- [`hook_templates`](#hook_templates) - Canonical git-hook templates embedded for scaffolding and drift detection. +- [`hooks`](#hooks) - Hooks lifecycle (`resq hooks install/scaffold-local/doctor/update/status`). +- [`pre_commit`](#pre_commit) - Pre-commit hook logic. +- [`secrets`](#secrets) - Secret management. +- [`version`](#version) - Version management and changesets. + +--- + +## Module: audit + +Blockchain event auditing. +Blockchain audit command. + +Queries Neo N3 and Solana blockchains for ResQ event records, +providing audit trails for incident response and delivery verification. + + + +## Module: commit + +AI-powered commit message generation. +AI-powered commit message generation from staged diffs. + + + +## Module: completions + +Shell-completion emitter (`resq completions `). +Shell-completion emitter. + +Generates completion scripts for bash, zsh, fish, elvish, and powershell +by introspecting the `clap`-derived top-level `Cli` parser. Users wire the +output into their shell's completion loader, e.g.: + +```bash +resq completions bash > /usr/local/share/bash-completion/completions/resq +``` + + + +## Module: copyright + +Copyright header management. +Copyright header command. + +Checks and updates copyright headers in source files to ensure +proper licensing and attribution. + + + +## Module: dev + +Development server management. +ResQ Dev commands — Repository and development utilities. + + + +## Module: docs + +Documentation management and publication. + + + +## Module: explore + +Service exploration and operations. +ResQ Explore commands — Unified TUI launcher. + + + +## Module: format + +Polyglot source formatting (Rust, TS, Python, C++, C#). +`resq format` — polyglot formatter with a shared implementation that +powers both the standalone command and the pre-commit format steps. + +Design: each language exports `format_(root, files, check)` — +pre-commit calls these on its staged file list and then restages; the +CLI wrapper (`resq format`) calls them on an empty list, which tells +each formatter to operate on the whole project. + + + +## Module: hook_templates + +Canonical git-hook templates embedded for scaffolding and drift detection. +Canonical git-hook templates embedded via `include_str!`. + +Both `resq dev install-hooks` (scaffolding) and `resq hooks doctor` +(drift detection) read from this single source. The templates are kept +in sync with <https://github.com/resq-software/dev/tree/main/scripts/git-hooks> +and the repo-local `.git-hooks/` — CI workflows in both repos enforce +byte equality. + + + +## Module: hooks + +Hooks lifecycle (`resq hooks install/scaffold-local/doctor/update/status`). +`resq hooks` — visibility and maintenance for installed git hooks. + +- `resq hooks doctor` reports drift between installed `.git-hooks/` + and the canonical content embedded in this binary. +- `resq hooks update` rewrites the canonical hooks (preserving any + `local-*` files the repo committed). +- `resq hooks status` prints a one-line summary suitable for shells. + + + +## Module: pre_commit + +Pre-commit hook logic. +Unified pre-commit hook logic with an optimized ratatui TUI. + + + +## Module: secrets + +Secret management. +Secret scanning command for detecting hardcoded credentials. + +Scans source files for potential secrets like API keys, passwords, tokens, +and other sensitive information using pattern matching and entropy analysis. + + + +## Module: version + +Version management and changesets. +Version management command - Polyglot Changeset Implementation. + + + diff --git a/sdks/rust/api/resq-cli/commands/audit.md b/sdks/rust/api/resq-cli/commands/audit.md new file mode 100644 index 00000000..69b70f3b --- /dev/null +++ b/sdks/rust/api/resq-cli/commands/audit.md @@ -0,0 +1,63 @@ +**resq_cli > commands > audit** + +# Module: commands::audit + +## Contents + +**Structs** + +- [`AuditArgs`](#auditargs) - CLI arguments for the security and quality audit command. + +**Functions** + +- [`run`](#run) - Run the security and quality audit. + +--- + +## resq_cli::commands::audit::AuditArgs + +*Struct* + +CLI arguments for the security and quality audit command. + +**Fields:** +- `root: std::path::PathBuf` - Root directory to start search from +- `level: String` - Minimum npm vulnerability severity to fail on (critical, high, moderate, low) +- `report_type: String` - audit-ci report verbosity (important, full, summary) +- `skip_prepare: bool` - Skip the yarn.lock generation step required by audit-ci +- `skip_npm: bool` - Skip the npm audit-ci pass +- `skip_osv: bool` - Skip the Google OSV Scanner pass (covers Rust, npm, Python, .NET, C/C++) +- `osv_format: String` - OSV Scanner output format (table, json, sarif, gh-annotations) +- `skip_react: bool` - Skip the react-doctor pass on the web dashboard +- `react_target: Option` - Path to the React/Next.js project for react-doctor +- `react_diff: Option` - Only scan React files changed vs this base branch (e.g. "main") +- `react_min_score: u8` - Minimum react-doctor health score to pass (0–100) + +**Trait Implementations:** + +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` + + + +## resq_cli::commands::audit::run + +*Function* + +Run the security and quality audit. + +```rust +fn run(args: AuditArgs) -> anyhow::Result<()> +``` + + + diff --git a/sdks/rust/api/resq-cli/commands/commit.md b/sdks/rust/api/resq-cli/commands/commit.md new file mode 100644 index 00000000..c00f8afb --- /dev/null +++ b/sdks/rust/api/resq-cli/commands/commit.md @@ -0,0 +1,50 @@ +**resq_cli > commands > commit** + +# Module: commands::commit + +## Contents + +**Structs** + +- [`CommitArgs`](#commitargs) - Arguments for the `resq commit` command. + +**Functions** + +- [`run`](#run) - Run the commit command. + +--- + +## resq_cli::commands::commit::CommitArgs + +*Struct* + +Arguments for the `resq commit` command. + +**Trait Implementations:** + +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` + + + +## resq_cli::commands::commit::run + +*Function* + +Run the commit command. + +```rust +fn run(args: CommitArgs) -> anyhow::Result<()> +``` + + + diff --git a/sdks/rust/api/resq-cli/commands/completions.md b/sdks/rust/api/resq-cli/commands/completions.md new file mode 100644 index 00000000..0999f698 --- /dev/null +++ b/sdks/rust/api/resq-cli/commands/completions.md @@ -0,0 +1,56 @@ +**resq_cli > commands > completions** + +# Module: commands::completions + +## Contents + +**Structs** + +- [`CompletionsArgs`](#completionsargs) - Arguments for `resq completions `. + +**Functions** + +- [`run`](#run) - Emit a completion script for the given shell to `stdout`. + +--- + +## resq_cli::commands::completions::CompletionsArgs + +*Struct* + +Arguments for `resq completions `. + +**Fields:** +- `shell: clap_complete::Shell` - Target shell. + +**Trait Implementations:** + +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` + + + +## resq_cli::commands::completions::run + +*Function* + +Emit a completion script for the given shell to `stdout`. + +Takes the already-built root `Command` so the caller (`main`) owns the parser +definition and this module stays decoupled from the `Cli` struct layout. + +```rust +fn run(args: CompletionsArgs, cmd: clap::Command) -> anyhow::Result<()> +``` + + + diff --git a/sdks/rust/api/resq-cli/commands/copyright.md b/sdks/rust/api/resq-cli/commands/copyright.md new file mode 100644 index 00000000..0a992aa4 --- /dev/null +++ b/sdks/rust/api/resq-cli/commands/copyright.md @@ -0,0 +1,67 @@ +**resq_cli > commands > copyright** + +# Module: commands::copyright + +## Contents + +**Structs** + +- [`CopyrightArgs`](#copyrightargs) - CLI arguments for the copyright header management command. + +**Functions** + +- [`run`](#run) - Run the copyright header management command. + +--- + +## resq_cli::commands::copyright::CopyrightArgs + +*Struct* + +CLI arguments for the copyright header management command. + +**Fields:** +- `license: String` - License type (apache-2.0, mit, gpl-3.0, bsd-3-clause) +- `author: String` - Copyright holder name +- `year: Option` - Copyright year (defaults to current year) +- `force: bool` - Overwrite existing headers +- `dry_run: bool` - Preview changes without writing files +- `check: bool` - Check for missing headers (CI mode, exits non-zero if any missing) +- `verbose: bool` - Print detailed processing info +- `glob: Vec` - Glob patterns to match files (e.g. "src/**/*.rs") +- `ext: Vec` - File extensions to include (e.g. --ext rs,js,py) +- `exclude: Vec` - Patterns to exclude from processing + +**Trait Implementations:** + +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + + + +## resq_cli::commands::copyright::run + +*Function* + +Run the copyright header management command. +Runs the copyright tool with the provided arguments. + +# Errors +Returns an error if the license year is invalid, the license file cannot be read, +or if processing any of the files fails. + +```rust +fn run(args: &CopyrightArgs) -> anyhow::Result<()> +``` + + + diff --git a/sdks/rust/api/resq-cli/commands/dev.md b/sdks/rust/api/resq-cli/commands/dev.md new file mode 100644 index 00000000..a2b5e798 --- /dev/null +++ b/sdks/rust/api/resq-cli/commands/dev.md @@ -0,0 +1,254 @@ +**resq_cli > commands > dev** + +# Module: commands::dev + +## Contents + +**Structs** + +- [`DevArgs`](#devargs) - Arguments for the 'dev' command. +- [`KillPortsArgs`](#killportsargs) - Arguments for the 'kill-ports' command. +- [`ScaffoldLocalHookArgs`](#scaffoldlocalhookargs) - Arguments for the `scaffold-local-hook` command. +- [`SyncEnvArgs`](#syncenvargs) - Arguments for the 'sync-env' command. +- [`UpgradeArgs`](#upgradeargs) - Arguments for the 'upgrade' command. + +**Enums** + +- [`DevCommands`](#devcommands) - Developer subcommands. + +**Functions** + +- [`run`](#run) - Executes the dev command. +- [`run_install_hooks_impl`](#run_install_hooks_impl) - Install the canonical git hooks into the current project's `.git-hooks/`. +- [`run_scaffold_local_hook_impl`](#run_scaffold_local_hook_impl) - Scaffold a repo-specific `.git-hooks/local-` file from a kind template. + +--- + +## resq_cli::commands::dev::DevArgs + +*Struct* + +Arguments for the 'dev' command. + +**Fields:** +- `command: DevCommands` - Dev subcommand to execute + +**Traits:** Parser + +**Trait Implementations:** + +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` +- **CommandFactory** + - `fn command<'b>() -> clap::Command` + - `fn command_for_update<'b>() -> clap::Command` +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + + + +## resq_cli::commands::dev::DevCommands + +*Enum* + +Developer subcommands. + +**Variants:** +- `KillPorts(KillPortsArgs)` - Kill processes listening on specified ports +- `SyncEnv(SyncEnvArgs)` - Sync environment variables from .env.example files to turbo.json +- `Upgrade(UpgradeArgs)` - Upgrade dependencies across all monorepo silos +- `InstallHooks` - Install git hooks from .git-hooks directory +- `ScaffoldLocalHook(ScaffoldLocalHookArgs)` - Scaffold a repo-specific `.git-hooks/local-` file + +**Trait Implementations:** + +- **Subcommand** + - `fn augment_subcommands<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_subcommands_for_update<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn has_subcommand(__clap_name: &str) -> bool` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut<'b>(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` + + + +## resq_cli::commands::dev::KillPortsArgs + +*Struct* + +Arguments for the 'kill-ports' command. + +**Fields:** +- `targets: Vec` - Ports or ranges (e.g. 8000 or 8000..8010) +- `force: bool` - Use SIGKILL instead of default SIGTERM +- `yes: bool` - Skip confirmation prompt + +**Traits:** Parser + +**Trait Implementations:** + +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **CommandFactory** + - `fn command<'b>() -> clap::Command` + - `fn command_for_update<'b>() -> clap::Command` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` + + + +## resq_cli::commands::dev::ScaffoldLocalHookArgs + +*Struct* + +Arguments for the `scaffold-local-hook` command. + +**Fields:** +- `kind: String` - Project kind. `auto` detects from root marker files +- `hook: String` - Which hook to scaffold a local override for (e.g. `pre-push`). +- `force: bool` - Overwrite an existing `local-` file. + +**Traits:** Parser + +**Trait Implementations:** + +- **CommandFactory** + - `fn command<'b>() -> clap::Command` + - `fn command_for_update<'b>() -> clap::Command` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + + + +## resq_cli::commands::dev::SyncEnvArgs + +*Struct* + +Arguments for the 'sync-env' command. + +**Fields:** +- `tasks: String` - Tasks to update in turbo.json (comma-separated) +- `dry_run: bool` - Preview changes without writing to turbo.json +- `max_depth: usize` - Maximum directory depth to search + +**Traits:** Parser + +**Trait Implementations:** + +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **CommandFactory** + - `fn command<'b>() -> clap::Command` + - `fn command_for_update<'b>() -> clap::Command` + + + +## resq_cli::commands::dev::UpgradeArgs + +*Struct* + +Arguments for the 'upgrade' command. + +**Fields:** +- `silo: String` - Specific silo to upgrade (python, rust, js, cpp, csharp, nix, or all) + +**Traits:** Parser + +**Trait Implementations:** + +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **CommandFactory** + - `fn command<'b>() -> clap::Command` + - `fn command_for_update<'b>() -> clap::Command` + + + +## resq_cli::commands::dev::run + +*Function* + +Executes the dev command. + +```rust +fn run(args: DevArgs) -> anyhow::Result<()> +``` + + + +## resq_cli::commands::dev::run_install_hooks_impl + +*Function* + +Install the canonical git hooks into the current project's `.git-hooks/`. + +# Errors +Returns an error if filesystem access or `git config` invocation fails. + +```rust +fn run_install_hooks_impl() -> anyhow::Result<()> +``` + + + +## resq_cli::commands::dev::run_scaffold_local_hook_impl + +*Function* + +Scaffold a repo-specific `.git-hooks/local-` file from a kind template. + +# Errors +Returns an error if the kind is unknown, the template is missing, or +filesystem access fails. + +```rust +fn run_scaffold_local_hook_impl(args: ScaffoldLocalHookArgs) -> anyhow::Result<()> +``` + + + diff --git a/sdks/rust/api/resq-cli/commands/docs.md b/sdks/rust/api/resq-cli/commands/docs.md new file mode 100644 index 00000000..9c9f6b6b --- /dev/null +++ b/sdks/rust/api/resq-cli/commands/docs.md @@ -0,0 +1,57 @@ +**resq_cli > commands > docs** + +# Module: commands::docs + +## Contents + +**Structs** + +- [`DocsArgs`](#docsargs) - Arguments for the `docs` command. + +**Functions** + +- [`run`](#run) - Run the documentation export and publication process. + +--- + +## resq_cli::commands::docs::DocsArgs + +*Struct* + +Arguments for the `docs` command. + +**Fields:** +- `export_only: bool` - Only export the specifications locally without publishing +- `publish: bool` - Publish the specifications to the documentation repository +- `dry_run: bool` - Dry run: show what would be done without executing + +**Trait Implementations:** + +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + + + +## resq_cli::commands::docs::run + +*Function* + +Run the documentation export and publication process. + +# Errors +Returns an error if any of the export or publication steps fail, +or if there are issues accessing the file system or GitHub API. + +```rust +fn run(args: DocsArgs) -> anyhow::Result<()> +``` + + + diff --git a/sdks/rust/api/resq-cli/commands/explore.md b/sdks/rust/api/resq-cli/commands/explore.md new file mode 100644 index 00000000..4ef0397c --- /dev/null +++ b/sdks/rust/api/resq-cli/commands/explore.md @@ -0,0 +1,292 @@ +**resq_cli > commands > explore** + +# Module: commands::explore + +## Contents + +**Structs** + +- [`AsmArgs`](#asmargs) - Arguments for the 'asm' (resq-bin) command +- [`CleanArgs`](#cleanargs) - Arguments for the 'clean' (resq-clean) command +- [`DeployArgs`](#deployargs) - Arguments for the 'deploy' (resq-deploy) command +- [`ExploreArgs`](#exploreargs) - Arguments for the 'explore' (resq-perf) command +- [`HealthArgs`](#healthargs) - Arguments for the 'health' (resq-health) command +- [`LogsArgs`](#logsargs) - Arguments for the 'logs' (resq-logs) command + +**Functions** + +- [`run_asm`](#run_asm) - Run resq-bin (Binary Explorer) +- [`run_clean`](#run_clean) - Run resq-clean (Workspace Cleaner) +- [`run_deploy`](#run_deploy) - Run resq-deploy (Deploy Explorer) +- [`run_explore`](#run_explore) - Run resq-perf (Performance Explorer) +- [`run_health`](#run_health) - Run resq-health (Health Explorer) +- [`run_logs`](#run_logs) - Run resq-logs (Log Explorer) + +--- + +## resq_cli::commands::explore::AsmArgs + +*Struct* + +Arguments for the 'asm' (resq-bin) command + +**Fields:** +- `file: Option` - Analyze a single binary path +- `dir: Option` - Analyze binaries under a directory +- `recursive: bool` - Recursively traverse directory in batch mode +- `ext: Option` - Optional suffix filter in batch mode (e.g. .so, .o) +- `config: Option` - Optional resq-bin config TOML path +- `no_cache: bool` - Disable cache reads/writes +- `rebuild_cache: bool` - Force cache rebuild +- `no_disasm: bool` - Disable disassembly and only collect metadata +- `max_functions: Option` - Maximum functions to disassemble per binary +- `tui: bool` - Force interactive TUI mode +- `plain: bool` - Use non-interactive plain output +- `json: bool` - Emit JSON report output + +**Traits:** Parser + +**Trait Implementations:** + +- **CommandFactory** + - `fn command<'b>() -> clap::Command` + - `fn command_for_update<'b>() -> clap::Command` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + + + +## resq_cli::commands::explore::CleanArgs + +*Struct* + +Arguments for the 'clean' (resq-clean) command + +**Fields:** +- `dry_run: bool` - Preview what would be deleted without removing anything + +**Traits:** Parser + +**Trait Implementations:** + +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **CommandFactory** + - `fn command<'b>() -> clap::Command` + - `fn command_for_update<'b>() -> clap::Command` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` + + + +## resq_cli::commands::explore::DeployArgs + +*Struct* + +Arguments for the 'deploy' (resq-deploy) command + +**Fields:** +- `env: String` - Target environment: dev, staging, prod +- `k8s: bool` - Use Kubernetes instead of Docker Compose + +**Traits:** Parser + +**Trait Implementations:** + +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **CommandFactory** + - `fn command<'b>() -> clap::Command` + - `fn command_for_update<'b>() -> clap::Command` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` + + + +## resq_cli::commands::explore::ExploreArgs + +*Struct* + +Arguments for the 'explore' (resq-perf) command + +**Fields:** +- `url: String` - Service URL to monitor +- `refresh_ms: u64` - Refresh rate in milliseconds + +**Traits:** Parser + +**Trait Implementations:** + +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **CommandFactory** + - `fn command<'b>() -> clap::Command` + - `fn command_for_update<'b>() -> clap::Command` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` + + + +## resq_cli::commands::explore::HealthArgs + +*Struct* + +Arguments for the 'health' (resq-health) command + +**Fields:** +- `interval: u64` - Poll interval in seconds + +**Traits:** Parser + +**Trait Implementations:** + +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **CommandFactory** + - `fn command<'b>() -> clap::Command` + - `fn command_for_update<'b>() -> clap::Command` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` + + + +## resq_cli::commands::explore::LogsArgs + +*Struct* + +Arguments for the 'logs' (resq-logs) command + +**Fields:** +- `source: String` - Log source: "docker" or "file" +- `service: Option` - Filter to a specific service name + +**Traits:** Parser + +**Trait Implementations:** + +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **CommandFactory** + - `fn command<'b>() -> clap::Command` + - `fn command_for_update<'b>() -> clap::Command` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` + + + +## resq_cli::commands::explore::run_asm + +*Function* + +Run resq-bin (Binary Explorer) + +```rust +fn run_asm(args: AsmArgs) -> anyhow::Result<()> +``` + + + +## resq_cli::commands::explore::run_clean + +*Function* + +Run resq-clean (Workspace Cleaner) + +```rust +fn run_clean(args: CleanArgs) -> anyhow::Result<()> +``` + + + +## resq_cli::commands::explore::run_deploy + +*Function* + +Run resq-deploy (Deploy Explorer) + +```rust +fn run_deploy(args: DeployArgs) -> anyhow::Result<()> +``` + + + +## resq_cli::commands::explore::run_explore + +*Function* + +Run resq-perf (Performance Explorer) + +```rust +fn run_explore(args: ExploreArgs) -> anyhow::Result<()> +``` + + + +## resq_cli::commands::explore::run_health + +*Function* + +Run resq-health (Health Explorer) + +```rust +fn run_health(args: HealthArgs) -> anyhow::Result<()> +``` + + + +## resq_cli::commands::explore::run_logs + +*Function* + +Run resq-logs (Log Explorer) + +```rust +fn run_logs(args: LogsArgs) -> anyhow::Result<()> +``` + + + diff --git a/sdks/rust/api/resq-cli/commands/format.md b/sdks/rust/api/resq-cli/commands/format.md new file mode 100644 index 00000000..ba978ef5 --- /dev/null +++ b/sdks/rust/api/resq-cli/commands/format.md @@ -0,0 +1,175 @@ +**resq_cli > commands > format** + +# Module: commands::format + +## Contents + +**Structs** + +- [`FormatArgs`](#formatargs) - Arguments for the `format` command. + +**Enums** + +- [`FormatOutcome`](#formatoutcome) - Outcome of a per-language format step. + +**Functions** + +- [`format_cpp`](#format_cpp) - Format C/C++ files via `clang-format`. +- [`format_csharp`](#format_csharp) - Format C# via `dotnet format`. +- [`format_python`](#format_python) - Format Python files via `ruff format`. +- [`format_rust`](#format_rust) - Format Rust files via `cargo fmt` (runs against the whole workspace +- [`format_ts`](#format_ts) - Format JS/TS/JSON/CSS files via Biome (preferring `biome` over `bunx --bun biome`). +- [`run`](#run) - Executes the `format` command. + +--- + +## resq_cli::commands::format::FormatArgs + +*Struct* + +Arguments for the `format` command. + +**Fields:** +- `language: Option` - Language to format. If omitted, runs every detected language. +- `check: bool` - Report issues without rewriting files. Exits non-zero if any found. + +**Traits:** Parser + +**Trait Implementations:** + +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **CommandFactory** + - `fn command<'b>() -> clap::Command` + - `fn command_for_update<'b>() -> clap::Command` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` + + + +## resq_cli::commands::format::FormatOutcome + +*Enum* + +Outcome of a per-language format step. + +**Variants:** +- `Clean` - The formatter ran and made no changes (or found no issues in `--check`). +- `Formatted` - The formatter ran and either rewrote files or — in `--check` — found issues. +- `Skipped(String)` - Skipped: either no matching files or the required tool isn't installed. +- `Failed(String)` - Formatter exited with a non-zero status unexpectedly. + +**Methods:** + +- `fn passed(self: &Self) -> bool` - `true` iff the step should be treated as a pass for pre-commit gating. + +**Traits:** Eq + +**Trait Implementations:** + +- **PartialEq** + - `fn eq(self: &Self, other: &FormatOutcome) -> bool` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` + + + +## resq_cli::commands::format::format_cpp + +*Function* + +Format C/C++ files via `clang-format`. + +# Errors +Never — failures are reported via `FormatOutcome::Failed(stderr)`. + +```rust +fn format_cpp(root: &std::path::Path, files: &[String], check: bool) -> anyhow::Result +``` + + + +## resq_cli::commands::format::format_csharp + +*Function* + +Format C# via `dotnet format`. + +# Errors +Never — failures are reported via `FormatOutcome::Failed(stderr)`. + +```rust +fn format_csharp(root: &std::path::Path, files: &[String], check: bool) -> anyhow::Result +``` + + + +## resq_cli::commands::format::format_python + +*Function* + +Format Python files via `ruff format`. + +# Errors +Never — failures are reported via `FormatOutcome::Failed(stderr)`. + +```rust +fn format_python(root: &std::path::Path, files: &[String], check: bool) -> anyhow::Result +``` + + + +## resq_cli::commands::format::format_rust + +*Function* + +Format Rust files via `cargo fmt` (runs against the whole workspace +when `files` is empty). + +# Errors +Never — failures are reported via `FormatOutcome::Failed(stderr)`. + +```rust +fn format_rust(root: &std::path::Path, files: &[String], check: bool) -> anyhow::Result +``` + + + +## resq_cli::commands::format::format_ts + +*Function* + +Format JS/TS/JSON/CSS files via Biome (preferring `biome` over `bunx --bun biome`). + +# Errors +Never — failures are reported via `FormatOutcome::Failed(stderr)`. + +```rust +fn format_ts(root: &std::path::Path, files: &[String], check: bool) -> anyhow::Result +``` + + + +## resq_cli::commands::format::run + +*Function* + +Executes the `format` command. + +# Errors +Returns an error only if the argument validation fails. Per-language +failures are reported on stderr and accumulate into the CLI exit code. + +```rust +fn run(args: FormatArgs) -> anyhow::Result<()> +``` + + + diff --git a/sdks/rust/api/resq-cli/commands/hook_templates.md b/sdks/rust/api/resq-cli/commands/hook_templates.md new file mode 100644 index 00000000..fd25c624 --- /dev/null +++ b/sdks/rust/api/resq-cli/commands/hook_templates.md @@ -0,0 +1,38 @@ +**resq_cli > commands > hook_templates** + +# Module: commands::hook_templates + +## Contents + +**Functions** + +- [`hook_content`](#hook_content) - Returns the canonical content for a given hook name, or `None` if the + +**Constants** + +- [`HOOK_TEMPLATES`](#hook_templates) - Canonical hook templates: `(hook_name, file_content)` tuples. + +--- + +## resq_cli::commands::hook_templates::HOOK_TEMPLATES + +*Constant*: `&[(&str, &str)]` + +Canonical hook templates: `(hook_name, file_content)` tuples. +The hook names correspond to git hook trigger names. + + + +## resq_cli::commands::hook_templates::hook_content + +*Function* + +Returns the canonical content for a given hook name, or `None` if the +hook is not one of the known canonical hooks. + +```rust +fn hook_content(name: &str) -> Option<&'static str> +``` + + + diff --git a/sdks/rust/api/resq-cli/commands/hooks.md b/sdks/rust/api/resq-cli/commands/hooks.md new file mode 100644 index 00000000..a7981f4f --- /dev/null +++ b/sdks/rust/api/resq-cli/commands/hooks.md @@ -0,0 +1,107 @@ +**resq_cli > commands > hooks** + +# Module: commands::hooks + +## Contents + +**Structs** + +- [`HooksArgs`](#hooksargs) - Arguments for the `hooks` command. + +**Enums** + +- [`HooksCommands`](#hookscommands) - Hooks subcommands. + +**Functions** + +- [`canonical_count`](#canonical_count) - Returns the canonical hook count — used by docs/tests. +- [`run`](#run) - Executes a `hooks` subcommand. + +--- + +## resq_cli::commands::hooks::HooksArgs + +*Struct* + +Arguments for the `hooks` command. + +**Fields:** +- `command: HooksCommands` - Hooks subcommand to execute. + +**Traits:** Parser + +**Trait Implementations:** + +- **CommandFactory** + - `fn command<'b>() -> clap::Command` + - `fn command_for_update<'b>() -> clap::Command` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + + + +## resq_cli::commands::hooks::HooksCommands + +*Enum* + +Hooks subcommands. + +**Variants:** +- `Install` - Install canonical hooks into `.git-hooks/` and set `core.hooksPath`. +- `ScaffoldLocal(crate::commands::dev::ScaffoldLocalHookArgs)` - Scaffold a repo-specific `.git-hooks/local-` from a kind template. +- `Doctor` - Report installed hook status; exit 1 if any drift / missing file detected. +- `Update` - Rewrite installed canonical hooks from embedded templates (preserves `local-*`). +- `Status` - Print a one-line summary for scripts (e.g. `installed=clean local=pre-push`). + +**Trait Implementations:** + +- **Subcommand** + - `fn augment_subcommands<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_subcommands_for_update<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn has_subcommand(__clap_name: &str) -> bool` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut<'b>(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` + + + +## resq_cli::commands::hooks::canonical_count + +*Function* + +Returns the canonical hook count — used by docs/tests. + +```rust +fn canonical_count() -> usize +``` + + + +## resq_cli::commands::hooks::run + +*Function* + +Executes a `hooks` subcommand. + +# Errors +Returns an error if filesystem access or `git config` invocation fails. + +```rust +fn run(args: HooksArgs) -> anyhow::Result<()> +``` + + + diff --git a/sdks/rust/api/resq-cli/commands/pre_commit.md b/sdks/rust/api/resq-cli/commands/pre_commit.md new file mode 100644 index 00000000..3ce3f02e --- /dev/null +++ b/sdks/rust/api/resq-cli/commands/pre_commit.md @@ -0,0 +1,60 @@ +**resq_cli > commands > pre_commit** + +# Module: commands::pre_commit + +## Contents + +**Structs** + +- [`PreCommitArgs`](#precommitargs) - Run all pre-commit checks with TUI progress output. + +**Functions** + +- [`run`](#run) - Main entry point for the pre-commit command. + +--- + +## resq_cli::commands::pre_commit::PreCommitArgs + +*Struct* + +Run all pre-commit checks with TUI progress output. + +**Fields:** +- `root: std::path::PathBuf` - Project root (defaults to auto-detected) +- `skip_audit: bool` - Skip security audit (osv-scanner + npm audit-ci) +- `skip_format: bool` - Skip formatting step +- `skip_versioning: bool` - Skip changeset/versioning prompt +- `max_file_size: u64` - Maximum file size in bytes (default: 10 MiB) +- `no_tui: bool` - Disable TUI (plain output for CI or piped stderr) + +**Trait Implementations:** + +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` + + + +## resq_cli::commands::pre_commit::run + +*Function* + +Main entry point for the pre-commit command. + +Runs verification checks and formatters with a TUI progress dashboard. + +```rust +fn run(args: PreCommitArgs) -> anyhow::Result<()> +``` + + + diff --git a/sdks/rust/api/resq-cli/commands/secrets.md b/sdks/rust/api/resq-cli/commands/secrets.md new file mode 100644 index 00000000..4e9a3380 --- /dev/null +++ b/sdks/rust/api/resq-cli/commands/secrets.md @@ -0,0 +1,59 @@ +**resq_cli > commands > secrets** + +# Module: commands::secrets + +## Contents + +**Structs** + +- [`SecretsArgs`](#secretsargs) - CLI arguments for the secrets scanning command. + +**Functions** + +- [`run`](#run) - Run the secrets scan. + +--- + +## resq_cli::commands::secrets::SecretsArgs + +*Struct* + +CLI arguments for the secrets scanning command. + +**Fields:** +- `root: std::path::PathBuf` - Root directory to scan (defaults to project root) +- `git_only: bool` - Only scan git-tracked files +- `verbose: bool` - Show verbose output (print matched content) +- `allowlist: Option` - Path to allowlist file (one pattern per line) +- `staged: bool` - Scan staged changes only (for pre-commit hook integration) +- `history: bool` - Also scan git history (all commits reachable from HEAD) +- `since: Option` - Limit history scan to commits after this rev/date (e.g. "30 days ago", "v1.0.0") + +**Trait Implementations:** + +- **Debug** + - `fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result` +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + + + +## resq_cli::commands::secrets::run + +*Function* + +Run the secrets scan. + +```rust +fn run(args: SecretsArgs) -> anyhow::Result<()> +``` + + + diff --git a/sdks/rust/api/resq-cli/commands/version.md b/sdks/rust/api/resq-cli/commands/version.md new file mode 100644 index 00000000..22fe68b2 --- /dev/null +++ b/sdks/rust/api/resq-cli/commands/version.md @@ -0,0 +1,129 @@ +**resq_cli > commands > version** + +# Module: commands::version + +## Contents + +**Structs** + +- [`AddArgs`](#addargs) - Arguments for adding a changeset. +- [`ApplyArgs`](#applyargs) - Arguments for applying version bumps. +- [`VersionArgs`](#versionargs) - Arguments for the version command. + +**Enums** + +- [`VersionCommands`](#versioncommands) - Commands for version management. + +**Functions** + +- [`run`](#run) - Run the version command + +--- + +## resq_cli::commands::version::AddArgs + +*Struct* + +Arguments for adding a changeset. + +**Fields:** +- `bump: String` - Type of change (patch, minor, major) +- `message: String` - Summary of what changed + +**Trait Implementations:** + +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + + + +## resq_cli::commands::version::ApplyArgs + +*Struct* + +Arguments for applying version bumps. + +**Fields:** +- `dry_run: bool` - Dry run - see what would change without modifying files + +**Trait Implementations:** + +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + + + +## resq_cli::commands::version::VersionArgs + +*Struct* + +Arguments for the version command. + +**Fields:** +- `command: VersionCommands` - Subcommand to execute. + +**Trait Implementations:** + +- **Args** + - `fn group_id() -> Option` + - `fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + + + +## resq_cli::commands::version::VersionCommands + +*Enum* + +Commands for version management. + +**Variants:** +- `Add(AddArgs)` - Create a new changeset (intent to change version) +- `Apply(ApplyArgs)` - Consume changesets and apply version bumps across the monorepo +- `Check` - Check if all versions are synchronized + +**Trait Implementations:** + +- **Subcommand** + - `fn augment_subcommands<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn augment_subcommands_for_update<'b>(__clap_app: clap::Command) -> clap::Command` + - `fn has_subcommand(__clap_name: &str) -> bool` +- **FromArgMatches** + - `fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result` + - `fn from_arg_matches_mut(__clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result` + - `fn update_from_arg_matches(self: & mut Self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + - `fn update_from_arg_matches_mut<'b>(self: & mut Self, __clap_arg_matches: & mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>` + + + +## resq_cli::commands::version::run + +*Function* + +Run the version command + +```rust +fn run(args: VersionArgs) -> anyhow::Result<()> +``` + + + diff --git a/sdks/rust/api/resq-cli/gitignore.md b/sdks/rust/api/resq-cli/gitignore.md new file mode 100644 index 00000000..33201c38 --- /dev/null +++ b/sdks/rust/api/resq-cli/gitignore.md @@ -0,0 +1,47 @@ +**resq_cli > gitignore** + +# Module: gitignore + +## Contents + +**Functions** + +- [`parse_gitignore`](#parse_gitignore) - Parse `.gitignore` from `root` and return a list of simple directory/file +- [`should_skip_path`](#should_skip_path) - Check whether `path` should be skipped based on its directory components + +--- + +## resq_cli::gitignore::parse_gitignore + +*Function* + +Parse `.gitignore` from `root` and return a list of simple directory/file +names to exclude during traversal. + +Strategy (matches the TS `parseGitignore` in `sync-turbo-env.ts`): +- Read `.gitignore`, split into lines +- Strip comments (`#`) and blank lines +- Normalize: remove leading `/` and trailing `/` +- Drop negations (`!`) and wildcard patterns (`*`) — too complex for + simple component-based matching; these are already handled by git itself +- Always include `.git` and `node_modules` as safety nets + +```rust +fn parse_gitignore(root: &std::path::Path) -> Vec +``` + + + +## resq_cli::gitignore::should_skip_path + +*Function* + +Check whether `path` should be skipped based on its directory components +matching any entry in `excludes`. + +```rust +fn should_skip_path(path: &std::path::Path, excludes: &[String]) -> bool +``` + + + diff --git a/sdks/rust/api/resq-cli/index.md b/sdks/rust/api/resq-cli/index.md new file mode 100644 index 00000000..baaa9d39 --- /dev/null +++ b/sdks/rust/api/resq-cli/index.md @@ -0,0 +1,108 @@ +# resq_cli + +> **Version:** `v0.3.0` · **License:** `Apache-2.0` · **Crate:** [crates.io](https://crates.io/crates/resq-cli) · **API docs:** [docs.rs](https://docs.rs/resq-cli/0.3.0) + +`ResQ` CLI - Command-line interface for managing `ResQ` services. + +This crate provides a unified CLI for interacting with the `ResQ` platform, +including service management, blockchain queries, and deployment operations. + +# Commands + +Grouped: +- `scan audit` — run cargo/bun/uv audit across the workspace +- `scan secrets` — scan for leaked credentials +- `scan copyright` — check or apply license headers +- `tui explore` / `logs` / `health` / `deploy` / `clean` / `asm` — TUI explorers + +Top-level: +- `format` — format Rust / TS / Python / C++ / C# in one pass +- `pre-commit` — full pre-commit gate (copyright, secrets, audit, format) +- `hooks` — inspect / update installed git hooks +- `dev` — repository utilities (workspace ops) +- `version` / `docs` / `commit` — release + docs + AI commit messages +- `completions` — emit shell completions for bash/zsh/fish/elvish/powershell + +Legacy flat forms (`resq audit`, `resq explore`, etc.) remain as hidden +aliases for one release cycle. + +# Usage + +```bash +resq scan audit +resq format --check +resq pre-commit +resq tui health +resq completions bash > /usr/local/share/bash-completion/completions/resq +``` + +## Modules + +### [`resq_cli`](resq_cli.md) + +*3 modules* + +### [`commands`](commands.md) + +*13 modules* + +### [`commands::audit`](commands/audit.md) + +*1 function, 1 struct* + +### [`commands::commit`](commands/commit.md) + +*1 function, 1 struct* + +### [`commands::completions`](commands/completions.md) + +*1 function, 1 struct* + +### [`commands::copyright`](commands/copyright.md) + +*1 function, 1 struct* + +### [`commands::dev`](commands/dev.md) + +*1 enum, 3 functions, 5 structs* + +### [`commands::docs`](commands/docs.md) + +*1 function, 1 struct* + +### [`commands::explore`](commands/explore.md) + +*6 functions, 6 structs* + +### [`commands::format`](commands/format.md) + +*1 enum, 1 struct, 6 functions* + +### [`commands::hook_templates`](commands/hook_templates.md) + +*1 constant, 1 function* + +### [`commands::hooks`](commands/hooks.md) + +*1 enum, 1 struct, 2 functions* + +### [`commands::pre_commit`](commands/pre_commit.md) + +*1 function, 1 struct* + +### [`commands::secrets`](commands/secrets.md) + +*1 function, 1 struct* + +### [`commands::version`](commands/version.md) + +*1 enum, 1 function, 3 structs* + +### [`gitignore`](gitignore.md) + +*2 functions* + +### [`utils`](utils.md) + +*1 function* + diff --git a/sdks/rust/api/resq-cli/resq_cli.md b/sdks/rust/api/resq-cli/resq_cli.md new file mode 100644 index 00000000..648f6953 --- /dev/null +++ b/sdks/rust/api/resq-cli/resq_cli.md @@ -0,0 +1,46 @@ +**resq_cli** + +# Module: resq_cli + +## Contents + +**Modules** + +- [`commands`](#commands) - CLI command implementations. +- [`gitignore`](#gitignore) - Gitignore pattern utilities. +- [`utils`](#utils) - Shared utility functions. + +--- + +## Module: commands + +CLI command implementations. +CLI commands for the ResQ tool. + +# Commands + +- [`audit`] - Dependency + supply-chain audit +- [`commit`] - AI-powered commit message generation +- [`copyright`] - Check/update copyright headers +- [`dev`] - Repo development utilities +- [`docs`] - Documentation export + publication +- [`explore`] - TUI explorers (launchers) +- [`hooks`] - Canonical git-hook lifecycle +- [`pre_commit`] - Unified pre-commit checks +- [`secrets`] - Secret scanning +- [`version`] - Version + changeset management + + + +## Module: gitignore + +Gitignore pattern utilities. + + + +## Module: utils + +Shared utility functions. + + + diff --git a/sdks/rust/api/resq-cli/utils.md b/sdks/rust/api/resq-cli/utils.md new file mode 100644 index 00000000..4cd5243b --- /dev/null +++ b/sdks/rust/api/resq-cli/utils.md @@ -0,0 +1,25 @@ +**resq_cli > utils** + +# Module: utils + +## Contents + +**Functions** + +- [`find_project_root`](#find_project_root) - Finds the project root by climbing up the directory tree from the CWD. + +--- + +## resq_cli::utils::find_project_root + +*Function* + +Finds the project root by climbing up the directory tree from the CWD. +Returns the current directory if no root marker is found. + +```rust +fn find_project_root() -> std::path::PathBuf +``` + + + diff --git a/sdks/rust/api/resq-dsa.md b/sdks/rust/api/resq-dsa.md deleted file mode 100644 index 824b241f..00000000 --- a/sdks/rust/api/resq-dsa.md +++ /dev/null @@ -1,449 +0,0 @@ -# resq-dsa - -> **Version:** `v0.1.3` · **License:** `Apache-2.0` · **Crate:** [crates.io](https://crates.io/crates/resq-dsa) · **API docs:** [docs.rs](https://docs.rs/resq-dsa/0.1.3) - -Production-grade data structures and algorithms — zero external dependencies - -## Overview - -[![Crates.io](https://img.shields.io/crates/v/resq-dsa.svg)](https://crates.io/crates/resq-dsa) -[![docs.rs](https://img.shields.io/docsrs/resq-dsa)](https://docs.rs/resq-dsa) -[![License](https://img.shields.io/crates/l/resq-dsa.svg)](https://github.com/wombocombo/wrk/blob/master/LICENSE) - -Production-grade data structures and algorithms with **zero external dependencies**. Designed for `no_std` environments and embedded systems while remaining ergonomic in standard Rust applications. The crate provides space-efficient probabilistic data structures (Bloom filter, Count-Min sketch), graph algorithms (BFS, Dijkstra, A\*), a bounded heap for K-nearest-neighbor tracking, a trie for prefix-based search, and Rabin-Karp rolling-hash string matching. - -## Module Structure - -```mermaid -graph TD - A[resq-dsa] --> B[bloom] - A --> C[count_min] - A --> D[graph] - A --> E[heap] - A --> F[trie] - - B --> B1[BloomFilter] - C --> C1[CountMinSketch] - D --> D1["Graph<Id>"] - D1 --> D2[bfs] - D1 --> D3[dijkstra] - D1 --> D4[astar] - E --> E1["BoundedHeap<T, D>"] - F --> F1[Trie] - F --> F2[rabin_karp] - - style A fill:#2d333b,stroke:#539bf5,color:#adbac7 - style B fill:#2d333b,stroke:#57ab5a,color:#adbac7 - style C fill:#2d333b,stroke:#57ab5a,color:#adbac7 - style D fill:#2d333b,stroke:#57ab5a,color:#adbac7 - style E fill:#2d333b,stroke:#57ab5a,color:#adbac7 - style F fill:#2d333b,stroke:#57ab5a,color:#adbac7 -``` - -## Feature Flags - -| Feature | Default | Description | -|---------|---------|-------------| -| `std` | Yes | Enables standard library support. Disable for `no_std` environments (the crate uses `alloc` internally). | - -## Installation - -### With `std` (default) - -```toml -[dependencies] -resq-dsa = "0.1" -``` - -### `no_std` environments - -```toml -[dependencies] -resq-dsa = { version = "0.1", default-features = false } -``` - -When `std` is disabled the crate compiles with `#![no_std]` and relies only on `alloc`. You must provide a global allocator in your binary. - ---- - -## Data Structures - -### Bloom Filter - -A space-efficient probabilistic set-membership data structure. It can tell you if an element is **possibly** in the set or **definitely not** in the set. False positives are possible; false negatives are not. - -The filter uses `k` independent FNV-1a hash functions (seeded variants) to set bits in an `m`-bit array. Optimal values for `k` and `m` are computed automatically from the desired capacity and false-positive rate. - -#### Complexity - -| Operation | Time | Space | -|-----------|--------|-------| -| `new` | O(m) | O(m) | -| `add` | O(k) | -- | -| `has` | O(k) | -- | -| `len` | O(1) | -- | -| `is_empty`| O(1) | -- | -| `clear` | O(m) | -- | - -Where **m** is the bit-array size and **k** is the number of hash functions (both derived from `capacity` and `error_rate`). - -#### API Reference - -| Method | Signature | Description | -|--------|-----------|-------------| -| `new` | `fn new(capacity: usize, error_rate: f64) -> Self` | Creates a new Bloom filter sized for `capacity` elements at the given false-positive `error_rate` (must be in `(0, 1)`). Panics if `error_rate` is out of range or `capacity` is zero. | -| `add` | `fn add(&mut self, item: impl AsRef<[u8]>)` | Adds an element to the filter. Accepts `&str`, `String`, `&[u8]`, `Vec`, etc. | -| `has` | `fn has(&self, item: impl AsRef<[u8]>) -> bool` | Returns `true` if the element is possibly in the set, `false` if it is definitely absent. | -| `len` | `const fn len(&self) -> usize` | Returns the number of elements that have been added. | -| `is_empty` | `const fn is_empty(&self) -> bool` | Returns `true` if no elements have been added. | -| `clear` | `fn clear(&mut self)` | Resets the filter, removing all elements. | - -#### Example - -```rust -use resq_dsa::bloom::BloomFilter; - -// Create a filter for 10,000 items with a 1% false-positive rate -let mut bf = BloomFilter::new(10_000, 0.01); - -bf.add("drone-001"); -bf.add("drone-002"); -bf.add(b"raw-bytes" as &[u8]); - -assert!(bf.has("drone-001")); // definitely present -assert!(!bf.has("drone-999")); // definitely absent -assert_eq!(bf.len(), 3); - -bf.clear(); -assert!(bf.is_empty()); -assert!(!bf.has("drone-001")); // cleared -``` - ---- - -### Count-Min Sketch - -A space-efficient probabilistic data structure for **frequency estimation**. It may overcount but never undercounts. Estimates are within `epsilon * N` of the true count with probability `1 - delta`, where `N` is the total count of all increments. - -Uses `depth` independent FNV-1a hash functions mapping elements to `width` columns. The estimated count for a key is the **minimum** across all rows. - -#### Complexity - -| Operation | Time | Space | -|-------------|----------|----------------| -| `new` | O(w * d) | O(w * d) | -| `increment` | O(d) | -- | -| `estimate` | O(d) | -- | - -Where **w** = `ceil(e / epsilon)` (width) and **d** = `ceil(ln(1 / delta))` (depth). - -#### API Reference - -| Method | Signature | Description | -|--------|-----------|-------------| -| `new` | `fn new(epsilon: f64, delta: f64) -> Self` | Creates a new sketch. `epsilon` controls error magnitude, `delta` controls failure probability. Both must be in `(0, 1)`. | -| `increment` | `fn increment(&mut self, key: impl AsRef<[u8]>, count: u64)` | Increments the count for `key` by `count`. Counts are stored as `u64` and saturate on overflow. | -| `estimate` | `fn estimate(&self, key: impl AsRef<[u8]>) -> u64` | Returns the estimated count for `key`. Guaranteed to be >= the true count. | - -#### Example - -```rust -use resq_dsa::count_min::CountMinSketch; - -// Estimates within 1% of true count, 99% of the time -let mut cms = CountMinSketch::new(0.01, 0.01); - -cms.increment("sensor-temp-high", 5); -cms.increment("sensor-temp-high", 3); -cms.increment("sensor-humidity", 1); - -let temp_count = cms.estimate("sensor-temp-high"); -assert!(temp_count >= 8); // never undercounts - -// Works with byte slices -cms.increment(b"raw-key" as &[u8], 10); -assert!(cms.estimate(b"raw-key" as &[u8]) >= 10); - -// Unknown keys return 0 -assert_eq!(cms.estimate("never-seen"), 0); -``` - ---- - -### Graph (Weighted Directed) - -A weighted directed graph with three pathfinding algorithms: breadth-first search (BFS), Dijkstra's shortest path, and A\* with a user-provided heuristic. - -Node identifiers can be any type that implements `Eq + Hash + Clone` (and additionally `Ord` for Dijkstra and A\*). Edge weights are `u64`. - -```mermaid -graph LR - A["base"] -- "100" --> B["waypoint-1"] - B -- "50" --> C["waypoint-2"] - A -- "200" --> C - C -- "25" --> D["target"] - - style A fill:#2d333b,stroke:#539bf5,color:#adbac7 - style D fill:#2d333b,stroke:#e5534b,color:#adbac7 -``` - -#### Complexity - -| Operation | Time | Space | -|------------|-----------------------|--------------| -| `new` | O(1) | O(1) | -| `add_edge` | O(1) amortized | O(1) | -| `bfs` | O(V + E) | O(V) | -| `dijkstra` | O((V + E) log V) | O(V) | -| `astar` | O((V + E) log V) * | O(V) | - -\* A\* worst case matches Dijkstra; with a good heuristic it explores fewer nodes. - -#### API Reference - -| Method | Signature | Description | -|--------|-----------|-------------| -| `new` | `fn new() -> Self` | Creates a new empty directed graph. Also implements `Default`. | -| `add_edge` | `fn add_edge(&mut self, from: Id, to: Id, weight: u64)` | Adds a directed edge. For undirected graphs, call twice with reversed nodes. | -| `bfs` | `fn bfs(&self, start: &Id) -> Vec` | Returns all reachable nodes from `start` in breadth-first order. Requires `Id: Eq + Hash + Clone`. | -| `dijkstra` | `fn dijkstra(&self, start: &Id, end: &Id) -> Option<(Vec, u64)>` | Finds the shortest path and its cost. Returns `None` if `end` is unreachable. Requires `Id: Eq + Hash + Clone + Ord`. | -| `astar` | `fn astar u64>(&self, start: &Id, end: &Id, h: H) -> Option<(Vec, u64)>` | A\* shortest path with heuristic `h(node, goal)`. The heuristic must be admissible and consistent for correct results. Requires `Id: Eq + Hash + Clone + Ord`. | - -#### Examples - -```rust -use resq_dsa::graph::Graph; - -let mut g = Graph::<&str>::new(); - -// Build the graph -g.add_edge("base", "waypoint-1", 100); -g.add_edge("waypoint-1", "waypoint-2", 50); -g.add_edge("base", "waypoint-2", 200); -g.add_edge("waypoint-2", "target", 25); - -// BFS -- visit all reachable nodes -let visited = g.bfs(&"base"); -assert!(visited.contains(&"target")); - -// Dijkstra -- find shortest path -let (path, cost) = g.dijkstra(&"base", &"target").unwrap(); -assert_eq!(path, vec!["base", "waypoint-1", "waypoint-2", "target"]); -assert_eq!(cost, 175); - -// Unreachable nodes return None -assert!(g.dijkstra(&"target", &"base").is_none()); -``` - -**A\* with a heuristic:** - -```rust -use resq_dsa::graph::Graph; - -let mut g = Graph::::new(); -g.add_edge(0, 1, 1); -g.add_edge(1, 2, 1); -g.add_edge(0, 3, 10); -g.add_edge(3, 2, 1); - -// Use absolute difference as heuristic -let (path, cost) = g.astar(&0, &2, |a, b| a.abs_diff(*b)).unwrap(); -assert_eq!(path, vec![0, 1, 2]); -assert_eq!(cost, 2); -``` - ---- - -### Bounded Heap - -A bounded max-heap that retains only the **K entries with the smallest distance values**. Useful for K-nearest-neighbor search, top-K tracking, and streaming scenarios where you want to keep only the closest results. - -The root always holds the entry with the **largest** distance among the retained items. When the heap is full and a new entry has a smaller distance than the root, the root is evicted. - -#### Complexity - -| Operation | Time | Space | -|-------------|-----------|-------| -| `new` | O(1) | O(k) | -| `insert` | O(log k) | -- | -| `peek` | O(1) | -- | -| `to_sorted` | O(k log k)| O(k) | -| `len` | O(1) | -- | -| `is_empty` | O(1) | -- | - -Where **k** is the heap limit. - -#### API Reference - -| Method | Signature | Description | -|--------|-----------|-------------| -| `new` | `fn new(limit: usize, dist: D) -> Self` | Creates a heap that keeps at most `limit` items, ordered by the distance function `dist: Fn(&T) -> f64`. | -| `insert` | `fn insert(&mut self, entry: T)` | Inserts an entry. If full and the new entry's distance is less than the current max, the max is evicted. Otherwise the entry is rejected. | -| `peek` | `fn peek(&self) -> Option<&T>` | Returns a reference to the entry with the maximum distance (the root), or `None` if empty. | -| `to_sorted` | `fn to_sorted(&self) -> Vec<&T>` | Returns all entries sorted by distance ascending (nearest first). Allocates a new `Vec` on each call. | -| `len` | `const fn len(&self) -> usize` | Returns the current number of entries. | -| `is_empty` | `const fn is_empty(&self) -> bool` | Returns `true` if the heap is empty. | - -#### Example - -```rust -use resq_dsa::heap::BoundedHeap; - -#[derive(Debug)] -struct Waypoint { id: u32, distance: f64 } - -// Keep the 3 nearest waypoints -let mut h = BoundedHeap::new(3, |w: &Waypoint| w.distance); - -h.insert(Waypoint { id: 1, distance: 10.0 }); -h.insert(Waypoint { id: 2, distance: 2.0 }); -h.insert(Waypoint { id: 3, distance: 7.0 }); -h.insert(Waypoint { id: 4, distance: 1.0 }); // evicts id=1 (distance 10.0) -h.insert(Waypoint { id: 5, distance: 50.0 }); // rejected (too far) - -assert_eq!(h.len(), 3); - -// peek returns the current max (the eviction threshold) -assert_eq!(h.peek().unwrap().id, 3); // id=3 has distance 7.0 - -// Sorted nearest-first -let sorted: Vec = h.to_sorted().iter().map(|w| w.id).collect(); -assert_eq!(sorted, vec![4, 2, 3]); -``` - -**Works with closures:** - -```rust -use resq_dsa::heap::BoundedHeap; - -let offset = 1.0; -let mut h = BoundedHeap::new(5, move |x: &f64| *x + offset); -h.insert(3.0); -h.insert(1.0); -assert_eq!(h.len(), 2); -``` - ---- - -### Trie (Prefix Tree) - -A prefix tree for efficient string storage, exact lookup, and prefix-based autocomplete. All operations run in O(m) time where m is the length of the input string. - -Internally, each node stores a `HashMap`, making the trie Unicode-aware. - -#### Complexity - -| Operation | Time | Space | -|---------------|------|-----------------| -| `new` | O(1) | O(1) | -| `insert` | O(m) | O(m) worst case | -| `search` | O(m) | -- | -| `starts_with` | O(m + r) | O(r) | - -Where **m** is the string length and **r** is the total length of all matching results. - -#### API Reference - -| Method | Signature | Description | -|--------|-----------|-------------| -| `new` | `fn new() -> Self` | Creates a new empty trie. Also implements `Default`. | -| `insert` | `fn insert(&mut self, word: &str)` | Inserts a word into the trie. | -| `search` | `fn search(&self, word: &str) -> bool` | Returns `true` if the exact word exists in the trie. | -| `starts_with` | `fn starts_with(&self, prefix: &str) -> Vec` | Returns all words that start with the given prefix. Uses DFS with a shared buffer to minimize allocations. | - -#### Example - -```rust -use resq_dsa::trie::Trie; - -let mut t = Trie::new(); -t.insert("drone"); -t.insert("drone-001"); -t.insert("drone-002"); -t.insert("deploy"); - -// Exact search -assert!(t.search("drone")); -assert!(!t.search("dro")); // prefix alone is not a word - -// Autocomplete -let mut suggestions = t.starts_with("drone-"); -suggestions.sort(); -assert_eq!(suggestions, vec!["drone-001", "drone-002"]); - -// All words starting with "d" -let mut all_d = t.starts_with("d"); -all_d.sort(); -assert_eq!(all_d, vec!["deploy", "drone", "drone-001", "drone-002"]); -``` - ---- - -### Rabin-Karp String Search - -A rolling-hash string matching algorithm that finds all occurrences of a pattern in a text. Uses a polynomial rolling hash with modular arithmetic (base 31, mod 10^9 + 7). - -The algorithm is **Unicode-aware** -- it operates on `char` boundaries, so multi-byte characters are handled correctly. Indices in the result are character positions, not byte offsets. - -#### Complexity - -| Case | Time | Space | -|---------|------------|-------| -| Average | O(n + m) | O(m) | -| Worst | O(n * m) | O(m) | - -Where **n** is the text length and **m** is the pattern length (both in chars). - -#### API Reference - -| Function | Signature | Description | -|----------|-----------|-------------| -| `rabin_karp` | `fn rabin_karp(text: &str, pattern: &str) -> Vec` | Returns a vector of starting character indices where `pattern` occurs in `text`. Returns an empty vector if there are no matches or the pattern is empty. | - -#### Example - -```rust -use resq_dsa::trie::rabin_karp; - -// Multiple overlapping matches -let matches = rabin_karp("ababab", "ab"); -assert_eq!(matches, vec![0, 2, 4]); - -// Single match -let single = rabin_karp("hello world", "world"); -assert_eq!(single, vec![6]); - -// No match -let none = rabin_karp("hello", "xyz"); -assert!(none.is_empty()); - -// Unicode support -let unicode = rabin_karp("cafe\u{0301} cafe\u{0301}", "cafe\u{0301}"); -assert_eq!(unicode, vec![0, 6]); -``` - ---- - -## Quick Reference - -| Module | Primary Type | Key Methods | -|--------|-------------|-------------| -| `bloom` | `BloomFilter` | `new`, `add`, `has`, `len`, `is_empty`, `clear` | -| `count_min` | `CountMinSketch` | `new`, `increment`, `estimate` | -| `graph` | `Graph` | `new`, `add_edge`, `bfs`, `dijkstra`, `astar` | -| `heap` | `BoundedHeap` | `new`, `insert`, `peek`, `to_sorted`, `len`, `is_empty` | -| `trie` | `Trie` | `new`, `insert`, `search`, `starts_with` | -| `trie` | (free fn) `rabin_karp` | `rabin_karp(text, pattern)` | - -## Contributing - -1. Fork the repository and create a feature branch. -2. Run `cargo test` to ensure all tests pass. -3. All new source files must include the Apache-2.0 license header. -4. Keep binary names consistent with the `resq-` convention. -5. Open a pull request against `master`. - -## License - -Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/resq-software/crates/blob/master/crates/LICENSE) for details. - diff --git a/sdks/rust/api/resq-dsa/bloom.md b/sdks/rust/api/resq-dsa/bloom.md new file mode 100644 index 00000000..987755b6 --- /dev/null +++ b/sdks/rust/api/resq-dsa/bloom.md @@ -0,0 +1,59 @@ +**resq_dsa > bloom** + +# Module: bloom + +## Contents + +**Structs** + +- [`BloomFilter`](#bloomfilter) - A space-efficient probabilistic set membership data structure. + +--- + +## resq_dsa::bloom::BloomFilter + +*Struct* + +A space-efficient probabilistic set membership data structure. + +A Bloom filter can tell you if an element is *possibly* in the set +or *definitely* not in the set. False positives are possible (it may +say an element is present when it's not), but false negatives are not. + +# Algorithm + +Uses `k` independent FNV-1a hash functions (seeded variants) to set bits +in an `m`-bit array. The optimal number of hash functions and bit array +size are calculated from the desired capacity and false positive rate. + +# Use Cases + +- Deduplication of IDs, sensor readings, or events +- Caching layer to avoid expensive lookups +- Quick membership checks before database queries + +# Examples + +``` +use resq_dsa::bloom::BloomFilter; + +let mut bf = BloomFilter::new(1000, 0.01); // 1% false positive rate +bf.add("drone-001"); +bf.add("drone-002"); + +assert!(bf.has("drone-001")); // definitely present +assert!(!bf.has("drone-999")); // definitely not present +``` + +**Methods:** + +- `fn new(capacity: usize, error_rate: f64) -> Self` - Creates a new Bloom filter with the given capacity and error rate. +- `fn from_raw_params(bit_count: usize, hash_count: usize) -> Self` - Creates a new Bloom filter from pre-computed parameters. +- `fn add>(self: & mut Self, item: impl Trait)` - Adds an element to the filter. +- `fn has>(self: &Self, item: impl Trait) -> bool` - Checks if an element might be in the set. +- `fn len(self: &Self) -> usize` - Returns the number of elements that have been added to the filter. +- `fn is_empty(self: &Self) -> bool` - Returns `true` if no elements have been added. +- `fn clear(self: & mut Self)` - Resets the filter, removing all elements. + + + diff --git a/sdks/rust/api/resq-dsa/count_min.md b/sdks/rust/api/resq-dsa/count_min.md new file mode 100644 index 00000000..52bf4523 --- /dev/null +++ b/sdks/rust/api/resq-dsa/count_min.md @@ -0,0 +1,62 @@ +**resq_dsa > count_min** + +# Module: count_min + +## Contents + +**Structs** + +- [`CountMinSketch`](#countminsketch) - A space-efficient probabilistic data structure for frequency estimation. + +--- + +## resq_dsa::count_min::CountMinSketch + +*Struct* + +A space-efficient probabilistic data structure for frequency estimation. + +The Count-Min sketch can estimate the frequency of events with guaranteed +error bounds. It may overcount but never undercounts (like Bloom filters, +this is a property of the algorithm). + +# Algorithm + +Uses `depth` independent FNV-1a hash functions (seeded variants) to map +elements to positions in `width` columns. The estimated count is the +minimum across all hash table rows. + +# Error Bounds + +- Error is at most `epsilon * total_count` with probability `1 - delta` +- Smaller epsilon/delta values require more memory + +# Use Cases + +- Tracking event frequencies +- Network traffic analysis +- Distributed counting without central aggregation + +# Examples + +``` +use resq_dsa::count_min::CountMinSketch; + +let mut cms = CountMinSketch::new(0.01, 0.01); +cms.increment("sensor-temp-high", 5); +cms.increment("sensor-temp-high", 3); +cms.increment("sensor-humidity", 1); + +let temp_estimate = cms.estimate("sensor-temp-high"); +assert!(temp_estimate >= 8); // never undercounts +``` + +**Methods:** + +- `fn new(epsilon: f64, delta: f64) -> Self` - Creates a new Count-Min sketch with the given error parameters. +- `fn from_raw_params(width: usize, depth: usize) -> Self` - Creates a new Count-Min sketch from pre-computed dimensions. +- `fn increment>(self: & mut Self, key: impl Trait, count: u64)` - Increments the count for a key by the given amount. +- `fn estimate>(self: &Self, key: impl Trait) -> u64` - Estimates the count for a key. + + + diff --git a/sdks/rust/api/resq-dsa/graph.md b/sdks/rust/api/resq-dsa/graph.md new file mode 100644 index 00000000..b3de3ed9 --- /dev/null +++ b/sdks/rust/api/resq-dsa/graph.md @@ -0,0 +1,71 @@ +**resq_dsa > graph** + +# Module: graph + +## Contents + +**Structs** + +- [`Graph`](#graph) - Graph data structure with pathfinding algorithms. + +--- + +## resq_dsa::graph::Graph + +*Struct* + +Graph data structure with pathfinding algorithms. + +Provides BFS, Dijkstra's algorithm, and A* for finding shortest paths +in weighted directed graphs. + +# Type Parameters + +- `Id`: Node identifier (must be hashable, clonable, comparable) + +# Use Cases + +- Flight path planning +- Network routing +- Game pathfinding + +# Examples + +``` +use resq_dsa::graph::Graph; + +let mut g = Graph::<&str>::new(); + +// Add edges (from, to, weight) +g.add_edge("base", "waypoint-1", 100); +g.add_edge("waypoint-1", "waypoint-2", 50); +g.add_edge("base", "waypoint-2", 150); +g.add_edge("waypoint-2", "target", 25); + +// BFS - visit all reachable nodes +let nodes = g.bfs(&"base"); +assert!(nodes.contains(&"target")); + +// Dijkstra - shortest path (175 via waypoint-2) +let (path, cost) = g.dijkstra(&"base", &"target").unwrap(); +assert_eq!(cost, 175); +``` + +**Generic Parameters:** +- Id + +**Methods:** + +- `fn dijkstra(self: &Self, start: &Id, end: &Id) -> Option<(Vec, u64)>` - Finds the shortest path using Dijkstra's algorithm. +- `fn astar(self: &Self, start: &Id, end: &Id, h: H) -> Option<(Vec, u64)>` - Finds the shortest path using A* algorithm. +- `fn new() -> Self` - Creates a new empty directed graph. +- `fn add_edge(self: & mut Self, from: Id, to: Id, weight: u64)` - Adds a directed edge from `from` to `to` with the given weight. +- `fn bfs(self: &Self, start: &Id) -> Vec` - Performs breadth-first search starting from `start`. + +**Trait Implementations:** + +- **Default** + - `fn default() -> Self` + + + diff --git a/sdks/rust/api/resq-dsa/heap.md b/sdks/rust/api/resq-dsa/heap.md new file mode 100644 index 00000000..5f5e6163 --- /dev/null +++ b/sdks/rust/api/resq-dsa/heap.md @@ -0,0 +1,74 @@ +**resq_dsa > heap** + +# Module: heap + +## Contents + +**Structs** + +- [`BoundedHeap`](#boundedheap) - A bounded max-heap that keeps the K entries with the smallest "distance" + +--- + +## resq_dsa::heap::BoundedHeap + +*Struct* + +A bounded max-heap that keeps the K entries with the smallest "distance" +values. + +This data structure is useful for tracking the K-nearest neighbors or +K-shortest paths. The root always contains the entry with the maximum +distance among the kept items. When the heap is full and a new entry has +a smaller distance than the root, the root is evicted and the new entry +takes its place. + +# Algorithm + +Uses a max-heap where: +- The root (index 0) always holds the entry with the *largest* distance +- When full, only entries with distance less than the current max can be inserted +- Insertion is O(log k) where k is the limit + +# Use Cases + +- K-nearest neighbor search in path planning +- Finding K shortest paths +- Maintaining top-K results in streaming scenarios + +# Examples + +``` +use resq_dsa::heap::BoundedHeap; + +#[derive(Debug)] +struct Waypoint { id: u32, distance: f64 } + +let mut h = BoundedHeap::new(3, |w: &Waypoint| w.distance); + +h.insert(Waypoint { id: 1, distance: 10.0 }); +h.insert(Waypoint { id: 2, distance: 2.0 }); +h.insert(Waypoint { id: 3, distance: 7.0 }); +h.insert(Waypoint { id: 4, distance: 1.0 }); // evicts id=1 (dist 10) +h.insert(Waypoint { id: 5, distance: 50.0 }); // rejected (too large) + +// Returns the 3 nearest waypoints sorted by distance +let sorted: Vec = h.to_sorted().iter().map(|w| w.id).collect(); +assert_eq!(sorted, vec![4, 2, 3]); // nearest first +``` + +**Generic Parameters:** +- T +- D + +**Methods:** + +- `fn new(limit: usize, dist: D) -> Self` - Creates a new bounded heap with the given limit and distance function. +- `fn insert(self: & mut Self, entry: T)` - Inserts an entry into the heap. +- `fn peek(self: &Self) -> Option<&T>` - Returns a reference to the entry with the maximum distance (the root). +- `fn to_sorted(self: &Self) -> Vec<&T>` - Returns all entries sorted by distance (ascending, nearest first). +- `fn len(self: &Self) -> usize` - Returns the current number of entries in the heap. +- `fn is_empty(self: &Self) -> bool` - Returns `true` if the heap contains no entries. + + + diff --git a/sdks/rust/api/resq-dsa/index.md b/sdks/rust/api/resq-dsa/index.md new file mode 100644 index 00000000..61e56183 --- /dev/null +++ b/sdks/rust/api/resq-dsa/index.md @@ -0,0 +1,67 @@ +# resq_dsa + +> **Version:** `v0.1.3` · **License:** `Apache-2.0` · **Crate:** [crates.io](https://crates.io/crates/resq-dsa) · **API docs:** [docs.rs](https://docs.rs/resq-dsa/0.1.3) + +Production-grade data structures and algorithms — zero external dependencies. + +A collection of space-efficient probabilistic data structures and +graph algorithms for general-purpose use. + +# Modules + +- [`bloom`] - Bloom filter for approximate set membership +- [`count_min`] - Count-Min sketch for frequency estimation +- [`graph`] - Graph algorithms (BFS, Dijkstra, A*) +- [`heap`] - Bounded heap for K-nearest neighbor tracking +- [`trie`] - Trie prefix tree and Rabin-Karp string matching + +# Usage + +``` +use resq_dsa::bloom::BloomFilter; +use resq_dsa::count_min::CountMinSketch; +use resq_dsa::graph::Graph; + +// Bloom filter for deduplication +let mut bf = BloomFilter::new(1000, 0.01); +bf.add("drone-001"); +assert!(bf.has("drone-001")); + +// Count-Min for frequency tracking +let mut cms = CountMinSketch::new(0.01, 0.01); +cms.increment("sensor-reading", 5); + +// Graph for pathfinding +let mut g = Graph::<&str>::new(); +g.add_edge("base", "waypoint-1", 100); +g.add_edge("waypoint-1", "target", 50); +let (path, cost) = g.dijkstra(&"base", &"target").unwrap(); +assert_eq!(path, vec!["base", "waypoint-1", "target"]); +``` + +## Modules + +### [`resq_dsa`](resq_dsa.md) + +*5 modules* + +### [`bloom`](bloom.md) + +*1 struct* + +### [`count_min`](count_min.md) + +*1 struct* + +### [`graph`](graph.md) + +*1 struct* + +### [`heap`](heap.md) + +*1 struct* + +### [`trie`](trie.md) + +*1 function, 1 struct* + diff --git a/sdks/rust/api/resq-dsa/resq_dsa.md b/sdks/rust/api/resq-dsa/resq_dsa.md new file mode 100644 index 00000000..0b93902c --- /dev/null +++ b/sdks/rust/api/resq-dsa/resq_dsa.md @@ -0,0 +1,52 @@ +**resq_dsa** + +# Module: resq_dsa + +## Contents + +**Modules** + +- [`bloom`](#bloom) - Bloom filter for approximate set membership. +- [`count_min`](#count_min) - Count-Min sketch for frequency estimation. +- [`graph`](#graph) - Graph data structure and pathfinding algorithms. +- [`heap`](#heap) - Bounded heap for K-nearest neighbor tracking. +- [`trie`](#trie) - Trie prefix tree and Rabin-Karp pattern matching. + +--- + +## Module: bloom + +Bloom filter for approximate set membership. + + + +## Module: count_min + +Count-Min sketch for frequency estimation. + + + +## Module: graph + +Graph data structure and pathfinding algorithms. + +Requires the `std` feature (enabled by default) because it depends on +`std::collections::{HashMap, HashSet, BinaryHeap, VecDeque}`. + + + +## Module: heap + +Bounded heap for K-nearest neighbor tracking. + + + +## Module: trie + +Trie prefix tree and Rabin-Karp pattern matching. + +Requires the `std` feature (enabled by default) because it depends on +`std::collections::HashMap`. + + + diff --git a/sdks/rust/api/resq-dsa/trie.md b/sdks/rust/api/resq-dsa/trie.md new file mode 100644 index 00000000..7a75124e --- /dev/null +++ b/sdks/rust/api/resq-dsa/trie.md @@ -0,0 +1,105 @@ +**resq_dsa > trie** + +# Module: trie + +## Contents + +**Structs** + +- [`Trie`](#trie) - A prefix tree (trie) for efficient string storage and retrieval. + +**Functions** + +- [`rabin_karp`](#rabin_karp) - Rabin-Karp string pattern matching using rolling hash. + +--- + +## resq_dsa::trie::Trie + +*Struct* + +A prefix tree (trie) for efficient string storage and retrieval. + +Supports insertion, exact search, and prefix-based autocomplete. +All operations are O(m) where m is the length of the string. + +# Use Cases + +- Autocomplete suggestions +- IP address routing tables +- Spell checking +- Word frequency tracking + +# Examples + +``` +use resq_dsa::trie::Trie; + +let mut t = Trie::new(); +t.insert("drone"); +t.insert("drone-001"); +t.insert("drone-002"); + +assert!(t.search("drone")); +assert!(!t.search("dro")); + +let suggestions = t.starts_with("drone-"); +assert!(suggestions.contains(&"drone-001".to_string())); +``` + +**Methods:** + +- `fn new() -> Self` - Creates a new empty Trie. +- `fn insert(self: & mut Self, word: &str)` - Inserts a word into the trie. +- `fn search(self: &Self, word: &str) -> bool` - Returns `true` if the exact word exists in the trie. +- `fn starts_with(self: &Self, prefix: &str) -> Vec` - Returns all words in the trie that start with the given prefix. + +**Trait Implementations:** + +- **Default** + - `fn default() -> Self` + + + +## resq_dsa::trie::rabin_karp + +*Function* + +Rabin-Karp string pattern matching using rolling hash. + +Finds all occurrences of `pattern` in `text` using a polynomial +rolling hash with modular arithmetic. Average case O(n + m). + +The algorithm operates on `char` boundaries, so it is +Unicode-aware (multi-byte characters are handled correctly). + +# Arguments + +* `text` - The text to search in +* `pattern` - The pattern to search for + +# Returns + +A vector of starting indices (in chars, not bytes) where the pattern matches. + +# Examples + +``` +use resq_dsa::trie::rabin_karp; + +let matches = rabin_karp("ababab", "ab"); +assert_eq!(matches, vec![0, 2, 4]); + +let single = rabin_karp("hello world", "world"); +assert_eq!(single, vec![6]); + +let none = rabin_karp("hello", "xyz"); +assert!(none.is_empty()); +``` + +```rust +fn rabin_karp(text: &str, pattern: &str) -> Vec +``` + + + diff --git a/sdks/rust/api/resq-tui.md b/sdks/rust/api/resq-tui.md deleted file mode 100644 index 9adb91b1..00000000 --- a/sdks/rust/api/resq-tui.md +++ /dev/null @@ -1,687 +0,0 @@ -# resq-tui - -> **Version:** `v0.1.8` · **License:** `Apache-2.0` · **Crate:** [crates.io](https://crates.io/crates/resq-tui) · **API docs:** [docs.rs](https://docs.rs/resq-tui/0.1.8) - -Shared TUI components and themes for ResQ developer tools - -## Overview - -[![Crates.io](https://img.shields.io/crates/v/resq-tui.svg)](https://crates.io/crates/resq-tui) -[![License](https://img.shields.io/crates/l/resq-tui.svg)](LICENSE) - -Shared TUI component library for all **ResQ** developer tools. Provides a unified theme system, console formatters, table rendering, progress bars, spinners, and terminal lifecycle management built on [Ratatui](https://ratatui.rs) and [Crossterm](https://docs.rs/crossterm). - -## Overview - -`resq-tui` ensures every ResQ tool (`resq-logs`, `resq-perf`, `resq-flame`, `resq-health`, etc.) shares a consistent visual identity and interaction model. It provides two tiers of output: - -- **Full-screen TUI** -- Ratatui-based widgets (header, footer, tabs, popups) with a standardized theme for interactive terminal applications. -- **Non-TUI CLI** -- Styled console formatters, tables, progress bars, and spinners for traditional command-line output that gracefully degrade when piped or redirected. - -All styling is gated through environment detection so ANSI codes never bleed into pipes, redirects, or screen-reader environments. - -## Architecture - -```mermaid -graph TD - subgraph resq-tui - LIB["lib.rs
Theme, Widgets, Utilities"] - THEME["theme.rs
AdaptiveColor, Palette"] - DETECT["detect.rs
TTY, Color Mode, Accessibility"] - CONSOLE["console.rs
Styled Message Formatters"] - TABLE["table.rs
CLI Table Renderer"] - PROGRESS["progress.rs
CLI Progress Bar"] - SPINNER["spinner.rs
Threaded CLI Spinner"] - TERMINAL["terminal.rs
Init, Restore, Event Loop"] - end - - THEME --> DETECT - CONSOLE --> DETECT - CONSOLE --> THEME - TABLE --> DETECT - TABLE --> THEME - PROGRESS --> DETECT - PROGRESS --> THEME - SPINNER --> DETECT - LIB --> THEME - - subgraph Consumers - LOGS["resq-logs"] - PERF["resq-perf"] - FLAME["resq-flame"] - HEALTH["resq-health"] - BIN["resq-bin"] - CLEAN["resq-clean"] - end - - LOGS --> LIB - PERF --> LIB - FLAME --> LIB - HEALTH --> LIB - BIN --> LIB - CLEAN --> LIB -``` - -### Module dependency flow - -```mermaid -flowchart LR - detect.rs -->|ColorMode| theme.rs - theme.rs -->|AdaptiveColor| console.rs - theme.rs -->|AdaptiveColor| table.rs - theme.rs -->|AdaptiveColor| progress.rs - detect.rs -->|should_style| console.rs - detect.rs -->|should_style| table.rs - detect.rs -->|should_style| progress.rs - detect.rs -->|should_style / is_tty| spinner.rs - lib.rs -->|re-exports| theme.rs - terminal.rs -->|crossterm + ratatui| lib.rs -``` - -## Installation - -Add to your `Cargo.toml`: - -```toml -[dependencies] -resq-tui = { workspace = true } -``` - -Or from crates.io: - -```toml -[dependencies] -resq-tui = "0.1.4" -``` - -## Module Reference - -### `lib.rs` -- Core Widgets and Utilities - -The root module re-exports `crossterm` and `ratatui` for convenience and provides the original `Theme` struct alongside shared TUI drawing functions. - -#### `Theme` (root) - -The original hardcoded dark-palette theme struct, retained for backward compatibility. For new code, prefer `theme::Theme::adaptive()` (see below). - -| Field | Type | Default | Description | -|-------------|---------|----------------|-------------------------------| -| `primary` | `Color` | `Cyan` | Primary brand color | -| `secondary` | `Color` | `Blue` | Secondary supporting color | -| `accent` | `Color` | `Magenta` | Metadata accent | -| `success` | `Color` | `Green` | Success state | -| `warning` | `Color` | `Yellow` | Warning / pending state | -| `error` | `Color` | `Red` | Error / critical state | -| `bg` | `Color` | `Black` | Background | -| `fg` | `Color` | `White` | Foreground text | -| `highlight` | `Color` | `Rgb(50,50,50)`| Selection highlight | -| `inactive` | `Color` | `DarkGray` | Muted / inactive elements | - -#### Widget Functions - -##### `draw_header` - -Renders a standardized header bar with service name, status badge, PID, and URL. - -```rust -use resq_tui::{self as tui, Theme}; - -fn draw(f: &mut ratatui::Frame, area: ratatui::layout::Rect) { - let theme = Theme::default(); - tui::draw_header( - f, - area, - "My-Explorer", - "READY", - theme.success, - Some(1234), // PID (or None) - "http://localhost:3000", - &theme, - ); -} -``` - -**Signature:** -```rust -pub fn draw_header( - frame: &mut Frame, - area: Rect, - title: &str, - status: &str, - status_color: Color, - pid: Option, - url: &str, - theme: &Theme, -) -``` - -##### `draw_footer` - -Renders a keyboard-shortcut footer bar. - -```rust -tui::draw_footer( - f, - area, - &[("Q", "Quit"), ("Tab", "Focus"), ("Up/Down", "Navigate")], - &theme, -); -``` - -**Signature:** -```rust -pub fn draw_footer(frame: &mut Frame, area: Rect, keys: &[(&str, &str)], theme: &Theme) -``` - -##### `draw_tabs` - -Renders a tab bar with selection highlight. Uses the default theme internally. - -```rust -tui::draw_tabs(f, area, vec!["Overview", "Details", "Logs"], 0); -``` - -**Signature:** -```rust -pub fn draw_tabs(frame: &mut Frame, area: Rect, titles: Vec<&str>, selected: usize) -``` - -##### `draw_popup` - -Renders a centered modal overlay for help dialogs or error messages. - -```rust -use ratatui::text::Line; - -tui::draw_popup( - f, - area, - "Help", - &[Line::raw("Press Q to quit"), Line::raw("Press ? for help")], - 60, // percent_x - 40, // percent_y - &theme, -); -``` - -**Signature:** -```rust -pub fn draw_popup( - frame: &mut Frame, - area: Rect, - title: &str, - lines: &[Line], - percent_x: u16, - percent_y: u16, - theme: &Theme, -) -``` - -##### `centered_rect` - -Helper that computes a centered `Rect` given percentage dimensions. Used internally by `draw_popup`. - -```rust -let popup_area = tui::centered_rect(60, 40, area); -``` - -#### Utility Functions - -##### `format_bytes` - -Converts a byte count to a human-readable string using binary units (KiB, MiB, GiB). - -```rust -use resq_tui::format_bytes; - -assert_eq!(format_bytes(0), "0 B"); -assert_eq!(format_bytes(1024), "1.0 KiB"); -assert_eq!(format_bytes(5242880), "5.0 MiB"); -assert_eq!(format_bytes(1073741824), "1.00 GiB"); -``` - -##### `format_duration` - -Converts seconds to a human-readable duration string. - -```rust -use resq_tui::format_duration; - -assert_eq!(format_duration(45), "45s"); -assert_eq!(format_duration(125), "2m 5s"); -assert_eq!(format_duration(3661), "1h 1m 1s"); -assert_eq!(format_duration(90061), "1d 1h 1m"); -``` - -##### `SPINNER_FRAMES` - -Braille animation frames for TUI spinner widgets: - -```rust -pub const SPINNER_FRAMES: &[&str] = &["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]; -``` - ---- - -### `theme` -- Adaptive Color System - -The theme module provides a Dracula-inspired adaptive color palette that switches between light and dark variants based on terminal environment detection. - -#### `AdaptiveColor` - -A color pair with `light` and `dark` variants that resolves at runtime via `detect_color_mode()`. - -```rust -use resq_tui::theme::{AdaptiveColor, COLOR_PRIMARY}; -use ratatui::style::Color; - -let resolved: Color = COLOR_PRIMARY.resolve(); -``` - -| Method | Returns | Description | -|-------------|---------|--------------------------------------------------| -| `resolve()` | `Color` | Returns the appropriate variant for the terminal | - -#### Palette Constants - -| Constant | Dark (Dracula) | Light | Usage | -|------------------------|-------------------------|-------------------------|-------------------------| -| `COLOR_PRIMARY` | `Rgb(139, 233, 253)` | `Rgb(0, 139, 139)` | Brand / primary accent | -| `COLOR_SECONDARY` | `Rgb(189, 147, 249)` | `Rgb(68, 71, 144)` | Supporting elements | -| `COLOR_ACCENT` | `Rgb(255, 121, 198)` | `Rgb(163, 55, 136)` | Metadata / PID | -| `COLOR_SUCCESS` | `Rgb(80, 250, 123)` | `Rgb(40, 130, 40)` | Success states | -| `COLOR_WARNING` | `Rgb(241, 250, 140)` | `Rgb(180, 120, 0)` | Warning states | -| `COLOR_ERROR` | `Rgb(255, 85, 85)` | `Rgb(215, 55, 55)` | Error states | -| `COLOR_FG` | `Rgb(248, 248, 242)` | `Rgb(40, 42, 54)` | Foreground text | -| `COLOR_BG` | `Rgb(40, 42, 54)` | `Rgb(248, 248, 242)` | Background | -| `COLOR_INACTIVE` | `Rgb(98, 114, 164)` | `Rgb(140, 140, 140)` | Muted / comments | -| `COLOR_HIGHLIGHT` | `Rgb(68, 71, 90)` | `Rgb(230, 230, 230)` | Selection background | -| `COLOR_PROGRESS_START` | `Rgb(189, 147, 249)` | `Rgb(100, 60, 180)` | Progress bar fill start | -| `COLOR_PROGRESS_END` | `Rgb(139, 233, 253)` | `Rgb(0, 139, 139)` | Progress bar fill end | -| `COLOR_PROGRESS_EMPTY` | `Rgb(98, 114, 164)` | `Rgb(200, 200, 200)` | Progress bar empty | - -#### `Theme` (theme module) - -Extended theme struct with adaptive color support. - -| Constructor | Description | -|-----------------|-------------------------------------------------------------------| -| `Theme::adaptive()` | Resolves all colors via `AdaptiveColor::resolve()` (recommended) | -| `Theme::default()` | Hardcoded dark palette for backward compatibility | - -```rust -use resq_tui::theme::Theme; - -// Recommended: adapts to terminal background -let theme = Theme::adaptive(); - -// Legacy: always dark -let theme = Theme::default(); -``` - ---- - -### `detect` -- Terminal Environment Detection - -Detects TTY status, color support, and accessibility mode. All detection is cached per-process via `OnceLock`. - -#### Environment Variables - -| Variable | Effect when set | -|--------------|--------------------------------------------------| -| `NO_COLOR` | Disables all ANSI styling ([no-color.org](https://no-color.org)) | -| `TERM=dumb` | Disables all ANSI styling | -| `ACCESSIBLE` | Enables screen-reader / accessible mode | -| `COLORFGBG` | Used to detect light vs dark terminal background | - -#### `ColorMode` - -```rust -pub enum ColorMode { - Dark, // Dark terminal background (default assumption) - Light, // Light terminal background - None, // No color support -} -``` - -#### Public Functions - -| Function | Returns | Description | -|-----------------------|-------------|--------------------------------------------------------| -| `is_tty_stdout()` | `bool` | Whether stdout is a TTY | -| `is_tty_stderr()` | `bool` | Whether stderr is a TTY | -| `is_accessible_mode()`| `bool` | Whether accessible / plain output is requested | -| `should_style()` | `bool` | Master gate -- all console formatters check this | -| `detect_color_mode()`| `ColorMode` | Resolved color mode for adaptive color selection | - ---- - -### `console` -- Styled Message Formatters - -TTY-gated console formatters for non-TUI CLI output. Diagnostics go to stderr, structured data to stdout. All styling respects `detect::should_style()`. - -#### Format Functions (return `String`) - -| Function | Prefix | Color | Usage | -|---------------------------|--------|-----------|------------------------------| -| `format_success(msg)` | `✅` | Success | Completion messages | -| `format_error(msg)` | `❌` | Error | Error messages (bold) | -| `format_warning(msg)` | `⚠️` | Warning | Warning messages | -| `format_info(msg)` | `ℹ️` | Primary | Informational messages | -| `format_command(cmd)` | `▶` | Secondary | Command references (bold) | -| `format_progress(msg)` | `⏳` | Warning | In-flight operations | -| `format_prompt(msg)` | `?` | Primary | Interactive prompts (bold) | -| `format_verbose(msg)` | -- | Dim | Debug / verbose output | -| `format_list_item(msg)` | ` •` | -- | Indented list items | -| `format_section_header(h)`| `━━━` | Primary | Section dividers with rule | -| `format_count(msg)` | `📊` | Accent | Metrics / counts | -| `format_location(msg)` | `📁` | Secondary | File paths / locations | -| `format_list_header(h)` | -- | FG (bold) | List / section headers | -| `format_search(msg)` | `🔍` | Primary | Search / scan operations | - -#### Print Functions (write to stderr) - -Convenience wrappers that call the corresponding `format_*` function and print to stderr: - -```rust -use resq_tui::console; - -console::success("Deployment complete"); -console::error("Connection refused"); -console::warning("Certificate expires soon"); -console::info("Scanning 42 services"); -console::progress("Uploading artifacts..."); -console::verbose("Retry attempt 3/5"); -console::section("Results"); -``` - ---- - -### `table` -- CLI Table Renderer - -Renders styled tables to stderr with zebra-striped rows, auto-computed column widths, and adaptive colors. Falls back to plain aligned text when styling is disabled. - -#### `Align` - -```rust -pub enum Align { - Left, // Default alignment - Right, // Right-aligned (for numeric columns) -} -``` - -#### `Column` - -Builder for table column definitions. - -| Method | Description | -|-----------------------|---------------------------------------| -| `Column::new(header)` | Left-aligned column | -| `Column::right(header)`| Right-aligned column | -| `.width(w)` | Sets minimum column width | - -#### `render_table` - -Renders a complete table to stderr. - -```rust -use resq_tui::table::{Column, render_table}; - -let columns = vec![ - Column::new("Service"), - Column::right("Latency"), - Column::new("Status").width(10), -]; - -let rows = vec![ - vec!["api".into(), "12ms".into(), "healthy".into()], - vec!["worker".into(), "340ms".into(), "degraded".into()], - vec!["cache".into(), "2ms".into(), "healthy".into()], -]; - -render_table(&columns, &rows); -``` - -Output (styled): -``` - Service Latency Status - ─────── ─────── ────────── - api 12ms healthy - worker 340ms degraded ← dimmed (zebra stripe) - cache 2ms healthy -``` - ---- - -### `progress` -- CLI Progress Bar - -Non-TUI progress bar rendered to stderr with adaptive gradient colors. Falls back to plain ASCII in non-TTY mode. - -#### `ProgressBar` - -| Method | Description | -|--------------------------------|---------------------------------------------------| -| `ProgressBar::new(msg, width)` | Creates a progress bar with message and width | -| `.render(fraction)` | Renders at the given fraction (0.0 to 1.0) | -| `.finish()` | Ends the bar with a newline | -| `.finish_with_message(msg)` | Clears the bar and prints a final message | - -```rust -use resq_tui::progress::ProgressBar; - -let pb = ProgressBar::new("Downloading", 40); -for i in 0..=100 { - pb.render(i as f64 / 100.0); -} -pb.finish_with_message("✅ Download complete"); -``` - -TTY output: `Downloading ████████████████░░░░░░░░░░░░░░░░░░░░░░░░ 40%` - -Non-TTY output: `Downloading [################------------------------] 40%` - ---- - -### `spinner` -- Threaded CLI Spinner - -Thread-safe stderr spinner that respects TTY and accessibility settings. Uses braille animation by default with a plain-dots fallback. - -#### `SPINNER_FRAMES` - -Braille frames used by both the TUI spinner constant and the non-TUI `Spinner`: - -```rust -pub const SPINNER_FRAMES: &[&str] = &["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]; -``` - -#### `Spinner` - -| Method | Description | -|-------------------------------|-------------------------------------------------| -| `Spinner::start(msg)` | Starts the spinner in a background thread | -| `.stop_with_message(msg)` | Stops and prints a final message | -| `.stop()` | Stops without a final message | - -The spinner is also stopped automatically on `Drop`. - -```rust -use resq_tui::spinner::Spinner; - -let spinner = Spinner::start("Fetching service health"); -// ... long-running operation ... -spinner.stop_with_message("✅ Health check complete"); -``` - -In non-TTY mode, `start()` prints `"Fetching service health..."` once and returns immediately. - ---- - -### `terminal` -- Terminal Lifecycle Management - -Manages raw mode, alternate screen, and provides a standard event loop for Ratatui applications. - -#### Type Alias - -```rust -pub type Term = Terminal>; -``` - -#### `init() -> anyhow::Result` - -Enables raw mode, enters the alternate screen, and returns an initialized `Term`. - -#### `restore()` - -Leaves the alternate screen and disables raw mode. Safe to call even in a partially-initialized state. - -#### `TuiApp` Trait - -Implement this trait on your application state to use `run_loop`. - -```rust -pub trait TuiApp { - fn draw(&mut self, frame: &mut ratatui::Frame); - fn handle_key(&mut self, key: crossterm::event::KeyEvent) -> anyhow::Result; -} -``` - -Return `false` from `handle_key` to exit the event loop. `Ctrl+C` always exits. - -#### `run_loop` - -Runs a standard TUI event loop. `poll_ms` controls input polling frequency. - -```rust -pub fn run_loop( - terminal: &mut Term, - poll_ms: u64, - app: &mut dyn TuiApp, -) -> anyhow::Result<()> -``` - ---- - -## Integration Guide - -### Building a new ResQ TUI tool - -1. **Add the dependency** to your crate's `Cargo.toml`: - -```toml -[dependencies] -resq-tui = { workspace = true } -``` - -2. **Implement `TuiApp`** on your application state: - -```rust -use resq_tui::terminal::TuiApp; -use resq_tui::theme::Theme; -use resq_tui::{draw_header, draw_footer}; -use ratatui::layout::{Constraint, Layout}; - -struct MyApp { - theme: Theme, -} - -impl TuiApp for MyApp { - fn draw(&mut self, frame: &mut ratatui::Frame) { - let area = frame.area(); - let chunks = Layout::vertical([ - Constraint::Length(3), // header - Constraint::Min(1), // body - Constraint::Length(3), // footer - ]) - .split(area); - - draw_header( - frame, chunks[0], - "My-Tool", "RUNNING", self.theme.success, - None, "localhost:8080", &self.theme, - ); - - // ... render your body content in chunks[1] ... - - draw_footer( - frame, chunks[2], - &[("Q", "Quit"), ("Tab", "Switch"), ("?", "Help")], - &self.theme, - ); - } - - fn handle_key( - &mut self, - key: crossterm::event::KeyEvent, - ) -> anyhow::Result { - use crossterm::event::KeyCode; - match key.code { - KeyCode::Char('q') => Ok(false), - _ => Ok(true), - } - } -} -``` - -3. **Run the event loop** in `main`: - -```rust -fn main() -> anyhow::Result<()> { - let mut terminal = resq_tui::terminal::init()?; - let mut app = MyApp { - theme: Theme::adaptive(), - }; - - let result = resq_tui::terminal::run_loop(&mut terminal, 100, &mut app); - resq_tui::terminal::restore(); - result -} -``` - -### Using non-TUI console output - -For CLI tools that do not need a full-screen TUI: - -```rust -use resq_tui::console; -use resq_tui::table::{Column, render_table}; -use resq_tui::progress::ProgressBar; -use resq_tui::spinner::Spinner; - -fn main() { - console::section("Service Health"); - - let spinner = Spinner::start("Checking services"); - // ... check services ... - spinner.stop_with_message("✅ All services checked"); - - let columns = vec![ - Column::new("Service"), - Column::right("Latency"), - Column::new("Status"), - ]; - let rows = vec![ - vec!["api".into(), "12ms".into(), "healthy".into()], - ]; - render_table(&columns, &rows); - - let pb = ProgressBar::new("Deploying", 30); - for i in 0..=100 { - pb.render(i as f64 / 100.0); - } - pb.finish_with_message(&console::format_success("Deployed")); -} -``` - -## Accessibility - -`resq-tui` respects the following standards: - -- **`NO_COLOR`** ([no-color.org](https://no-color.org)) -- disables all ANSI color codes -- **`TERM=dumb`** -- plain text output only -- **`ACCESSIBLE`** -- activates screen-reader-friendly output (plain dot spinners, no animation) -- Non-TTY pipes and redirects receive unstyled output automatically - -## License - -Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/resq-software/crates/blob/master/crates/LICENSE) for details. - diff --git a/sdks/rust/api/resq-tui/index.md b/sdks/rust/api/resq-tui/index.md new file mode 100644 index 00000000..cfd939ec --- /dev/null +++ b/sdks/rust/api/resq-tui/index.md @@ -0,0 +1,17 @@ +# resq_tui + +> **Version:** `v0.1.8` · **License:** `Apache-2.0` · **Crate:** [crates.io](https://crates.io/crates/resq-tui) · **API docs:** [docs.rs](https://docs.rs/resq-tui/0.1.8) + +Shared TUI components and themes for `ResQ` developer tools. +Inspired by binsider architecture. + +## Modules + +### [`resq_tui`](resq_tui.md) + +*1 constant, 1 module, 1 struct, 7 functions* + +### [`terminal`](terminal.md) + +*1 struct, 1 trait, 1 type alias, 3 functions* + diff --git a/sdks/rust/api/resq-tui/resq_tui.md b/sdks/rust/api/resq-tui/resq_tui.md new file mode 100644 index 00000000..edb669eb --- /dev/null +++ b/sdks/rust/api/resq-tui/resq_tui.md @@ -0,0 +1,153 @@ +**resq_tui** + +# Module: resq_tui + +## Contents + +**Modules** + +- [`terminal`](#terminal) - Terminal lifecycle helpers — init, restore, and event-loop runner. + +**Structs** + +- [`Theme`](#theme) - Standard `ResQ` TUI Theme. + +**Functions** + +- [`centered_rect`](#centered_rect) - Helper to create a centered rectangle for popups. +- [`draw_footer`](#draw_footer) - Renders a standardized footer with keyboard shortcuts. +- [`draw_header`](#draw_header) - Renders a standardized header with service metadata and PID. +- [`draw_popup`](#draw_popup) - Renders a centered popup for help or errors. +- [`draw_tabs`](#draw_tabs) - Renders a standardized tab bar. +- [`format_bytes`](#format_bytes) - Formats bytes into human-readable units. +- [`format_duration`](#format_duration) - Formats seconds into human-readable duration. + +**Constants** + +- [`SPINNER_FRAMES`](#spinner_frames) - Spinner animation frames for loading indicators. + +--- + +## resq_tui::SPINNER_FRAMES + +*Constant*: `&[&str]` + +Spinner animation frames for loading indicators. + + + +## resq_tui::Theme + +*Struct* + +Standard `ResQ` TUI Theme. + +**Fields:** +- `primary: ratatui::style::Color` - Primary brand color (Cyan) +- `secondary: ratatui::style::Color` - Secondary supporting color (Blue) +- `accent: ratatui::style::Color` - Accent color for PID/Metadata (Magenta) +- `success: ratatui::style::Color` - Success state (Green) +- `warning: ratatui::style::Color` - Warning/Pending state (Yellow) +- `error: ratatui::style::Color` - Error/Critical state (Red) +- `bg: ratatui::style::Color` - Background color +- `fg: ratatui::style::Color` - Foreground text color +- `highlight: ratatui::style::Color` - Highlight/Selection color +- `inactive: ratatui::style::Color` - Inactive/Muted color (`DarkGray`) + +**Trait Implementations:** + +- **Default** + - `fn default() -> Self` + + + +## resq_tui::centered_rect + +*Function* + +Helper to create a centered rectangle for popups. + +```rust +fn centered_rect(percent_x: u16, percent_y: u16, r: ratatui::layout::Rect) -> ratatui::layout::Rect +``` + + + +## resq_tui::draw_footer + +*Function* + +Renders a standardized footer with keyboard shortcuts. + +```rust +fn draw_footer(frame: & mut ratatui::Frame, area: ratatui::layout::Rect, keys: &[(&str, &str)], theme: &Theme) +``` + + + +## resq_tui::draw_header + +*Function* + +Renders a standardized header with service metadata and PID. + +```rust +fn draw_header(frame: & mut ratatui::Frame, area: ratatui::layout::Rect, title: &str, status: &str, status_color: ratatui::style::Color, pid: Option, url: &str, theme: &Theme) +``` + + + +## resq_tui::draw_popup + +*Function* + +Renders a centered popup for help or errors. + +```rust +fn draw_popup(frame: & mut ratatui::Frame, area: ratatui::layout::Rect, title: &str, lines: &[ratatui::text::Line], percent_x: u16, percent_y: u16, theme: &Theme) +``` + + + +## resq_tui::draw_tabs + +*Function* + +Renders a standardized tab bar. + +```rust +fn draw_tabs(frame: & mut ratatui::Frame, area: ratatui::layout::Rect, titles: Vec<&str>, selected: usize) +``` + + + +## resq_tui::format_bytes + +*Function* + +Formats bytes into human-readable units. + +```rust +fn format_bytes(bytes: u64) -> String +``` + + + +## resq_tui::format_duration + +*Function* + +Formats seconds into human-readable duration. + +```rust +fn format_duration(seconds: u64) -> String +``` + + + +## Module: terminal + +Terminal lifecycle helpers — init, restore, and event-loop runner. + + + diff --git a/sdks/rust/api/resq-tui/terminal.md b/sdks/rust/api/resq-tui/terminal.md new file mode 100644 index 00000000..83bd8f58 --- /dev/null +++ b/sdks/rust/api/resq-tui/terminal.md @@ -0,0 +1,119 @@ +**resq_tui > terminal** + +# Module: terminal + +## Contents + +**Structs** + +- [`TerminalGuard`](#terminalguard) - RAII guard that owns a [`Term`] and automatically calls [`restore`] on drop. + +**Functions** + +- [`init`](#init) - Initialise raw mode and enter the alternate screen. +- [`restore`](#restore) - Leave the alternate screen and disable raw mode. +- [`run_loop`](#run_loop) - Run a standard TUI event loop with the given app. + +**Traits** + +- [`TuiApp`](#tuiapp) - Implement this trait on your app state to use [`run_loop`]. + +**Type Aliases** + +- [`Term`](#term) - A `ratatui` terminal backed by Crossterm. + +--- + +## resq_tui::terminal::Term + +*Type Alias*: `ratatui::Terminal>` + +A `ratatui` terminal backed by Crossterm. + + + +## resq_tui::terminal::TerminalGuard + +*Struct* + +RAII guard that owns a [`Term`] and automatically calls [`restore`] on drop. + +This ensures the terminal is cleaned up even on panic or early `?` returns. +Use [`Deref`] / [`DerefMut`] to access the underlying [`Term`] transparently +(e.g. `guard.draw(|f| ...)` works). + +**Trait Implementations:** + +- **Drop** + - `fn drop(self: & mut Self)` +- **DerefMut** + - `fn deref_mut(self: & mut Self) -> & mut ::Target` +- **Deref** + - `fn deref(self: &Self) -> &::Target` + + + +## resq_tui::terminal::TuiApp + +*Trait* + +Implement this trait on your app state to use [`run_loop`]. + +**Methods:** + +- `draw`: Draw the current frame. +- `handle_key`: Handle a key event. Return `false` to exit the loop. + + + +## resq_tui::terminal::init + +*Function* + +Initialise raw mode and enter the alternate screen. + +Returns a [`TerminalGuard`] that will call [`restore`] automatically when +dropped, ensuring cleanup even on panic or early `?` returns. + +# Errors +Propagates any I/O error from Crossterm or Ratatui. + +```rust +fn init() -> anyhow::Result +``` + + + +## resq_tui::terminal::restore + +*Function* + +Leave the alternate screen and disable raw mode. + +Safe to call even if the terminal is in a partially-initialised state. + +```rust +fn restore() +``` + + + +## resq_tui::terminal::run_loop + +*Function* + +Run a standard TUI event loop with the given app. + +`poll_ms` controls how frequently the loop polls for keyboard input. +Ctrl+C always exits. The terminal is **not** automatically initialised +or restored — wrap the call site with [`init`] / [`restore`]. + +# Errors +Propagates draw or event errors, and errors from the app's `handle_key`. + +```rust +fn run_loop(terminal: & mut Term, poll_ms: u64, app: & mut dyn TuiApp) -> anyhow::Result<()> +``` + + +