{"slug": "valknut", "title": "Valknut", "summary": "Sibylline Software released Valknut, a Rust-native code analysis platform that combines structural heuristics, AST-driven complexity metrics, and documentation audits, distributed via npm as @sibyllinesoft/valknut, Homebrew, and cargo install valknut-rs. Valknut ships full support for Python, TypeScript/JavaScript, and Rust, with beta adapters for Go, C++, and C#; the C++ adapter was validated against 40+ major open source repositories including fmt, nlohmann/json, googletest, protobuf, OpenCV, and TensorFlow with 99%+ parse success rates. The tool exposes a Model Context Protocol server via the valknut mcp-stdio command for IDE automation and exports reports in JSONL, JSON, YAML, CSV, Markdown, HTML, Sonar, and CI-summary formats.", "body_md": "Valknut is a Rust-native analysis platform that combines structural heuristics, AST-driven complexity metrics, and documentation audits. The CLI ships with CI-friendly output, a documentation linter, and MCP endpoints for IDE automation.\n\n- Docs site: [https://valknut.sibylline.dev](https://valknut.sibylline.dev)\n- Live report snapshot: [https://valknut.sibylline.dev/report-dev.html](https://valknut.sibylline.dev/report-dev.html)\n\n- **Comprehensive analysis pipeline** – structure, complexity, dependency graph, coverage, LSH clone detection, semantic cohesion, refactoring scoring, and health metrics driven by`AnalysisPipeline` .\n- **Documentation awareness** – the bundled`doc-audit` command finds missing/dated READMEs, TODO clusters, and style regressions with language-specific scanners for Rust, Python, and TypeScript.\n- **MCP integration** – run`valknut mcp-stdio` to expose a Model Context Protocol server.\n- **High-performance internals** – arena allocation, shared AST caches, SIMD-accelerated similarity, and git-aware file discovery keep large repos manageable.\n- **Modular architecture** – cleanly separated detector modules (LSH, complexity, structure, cohesion) with dedicated submodules for metrics, configuration, and analysis stages.\n- **Battle-tested reports** – export JSONL/JSON/YAML/CSV/Markdown/HTML/Sonar/CI-summary formats plus colorized console summaries.\n\n| Language | Status | Notes | \n|---|---|---|\n| Python | ✅ Full support | Tree-sitter Python with structure/complexity/refactoring detectors | \n| TypeScript / JavaScript | ✅ Full support | Handles `.ts` ,`.tsx` ,`.js` ,`.jsx` ,`.mjs` ,`.cjs` | \n| Rust | ✅ Full support | Ownership-aware complexity & dependency graphs | \n| Go | 🚧 Beta | AST parsing works; recommendations still limited | \n| C++ | 🚧 Beta | Handles `.cpp` ,`.cxx` ,`.cc` ,`.hpp` ,`.h` and more; tested against 40+ major OSS repos | \n| C# | 🚧 Beta | Types, members, calls, and `using` dependencies for`.cs` projects | \n\n**C++ Support (Beta)**: The C++ adapter has been validated against major open source codebases including fmt, nlohmann/json, googletest, protobuf, OpenCV, TensorFlow, and others with 99%+ parse success rates. Feedback welcome via [GitHub Issues](https://github.com/sibyllinesoft/valknut/issues).\n\nValknut currently exposes only these adapters in `src/lang/registry.rs`. Other extensions will be skipped unless/until dedicated adapters are implemented.\n\n| Command | Purpose | \n|---|---|\n| `valknut analyze [PATH]` | Run the full analysis pipeline with selectable profiles and output formats | \n| `valknut doc-audit --root REPO` | Audit READMEs, TODO hot-spots, and stale docs using the `doc_audit` crate | \n| `valknut list-languages` | Display the runtime language matrix (driven by the actual adapters) | \n| `valknut init-config` /`print-default-config` | Scaffold or inspect `valknut.yml` | \n| `valknut validate-config --config valknut.yml` | Sanity-check custom configuration files | \n| `valknut mcp-stdio` /`mcp-manifest` | Launch the MCP server or emit a manifest for IDE agents | \n\nPre-built binaries for supported platforms:\n\n```\nnpm install -g @sibyllinesoft/valknut\n```\n\n| Platform | Architecture | Supported | \n|---|---|---|\n| Linux | x64 (glibc) | ✅ | \n| macOS | x64 | ✅ | \n| macOS | ARM64 (Apple Silicon) | ✅ | \n| Windows | x64 | ✅ | \n\n```\nbrew tap sibyllinesoft/valknut\nbrew install valknut\ncargo install valknut-rs\n```\n\nFor platforms without pre-built binaries (ARM Linux, Alpine/musl), compile from source:\n\n```\ncargo install --git https://github.com/sibyllinesoft/valknut\n# Fast scan with JSONL output (default profile)\nvalknut analyze ./src --format jsonl\n\n# HTML + Markdown bundle for stakeholders\nvalknut analyze ./ --format html --profile thorough\n\n# Documentation audit with strict exit codes\nvalknut doc-audit --root . --strict\n\n# List the languages compiled into your build\nvalknut list-languages\n```\n\n- `--profile fast|balanced|thorough|extreme` selects how many detectors and optimizations run.\n- `--no-structure` ,`--no-impact` ,`--no-lsh` , etc., mirror`analysis.modules.*` toggles in`valknut.yml` .\n- Clone detection controls live under `--semantic-clones` ,`--denoise` ,`--min-function-tokens` , etc.\n\n**Structure Analysis** – deterministic directory/file re-organization packs (`src/detectors/structure/`) surface imbalance, whale files, and recommended splits with dedicated modules for cohesion, imports, and partitioning.\n\n**Complexity Intelligence** – AST-backed cyclomatic/cognitive metrics and severity classification per entity (`src/detectors/complexity/`).\n\n**Semantic Cohesion** – TF-IDF weighted symbol extraction and optional embedding-based analysis for measuring how well related code entities are grouped (`src/detectors/cohesion/`).\n\n**Dependency & Impact Analysis** – `ProjectDependencyAnalysis` builds call graphs, detects cycles, and feeds choke-point scoring plus similarity cliques.\n\n**Clone Detection (opt-in)** – locality-sensitive hashing with shingle generation, AST-based stop motif filtering, and SIMD-accelerated similarity for semantic clone clusters (`src/detectors/lsh/`).\n\n**Coverage Awareness** – auto-discover or pin coverage files, surface gap summaries, and include them in health metrics.\n\n**Refactoring Scoring** – aggregated feature vectors drive health, maintainability, and technical-debt indices for gating.\n\nGitHub Actions example:\n\n```\nname: Valknut Quality Gate\non: [push, pull_request]\n\njobs:\n  quality:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - run: npm install -g @sibyllinesoft/valknut\n      - run: |\n          valknut analyze ./src \\\n            --format html \\\n            --out quality-reports \\\n            --quality-gate \\\n            --max-complexity 70 \\\n            --min-health 65\n      - uses: actions/upload-artifact@v4\n        if: always()\n        with:\n          name: quality-reports\n          path: quality-reports\n```\n\nQuality gates can also be expressed in config (`analysis.quality`) or via CLI flags (`--max-debt`, `--max-issues`, `--max-critical`, etc.).\n\nThe `doc-audit` command walks the repo, scores directory complexity, and tracks README freshness:\n\n```\nvalknut doc-audit --root . --complexity-threshold 10 --max-readme-commits 8 --strict\n```\n\nUse `--ignore-dir` / `--ignore-suffix` to skip generated assets. The audit exits non-zero in `--strict` mode when gaps exist, making it ideal for CI.\n\n- **Model Context Protocol** :`valknut mcp-stdio` exposes the analyze/list/gate abilities to IDE agents. Use`valknut mcp-manifest --output manifest.json` to publish the schema from`src/bin/cli/commands.rs` .\n\n- Run `valknut init-config` to generate`.valknut.yml` (see`valknut.yml.example` for every toggle).\n- CLI → API → pipeline config layers are merged via `src/bin/cli/config_layer.rs` . Settings such as coverage search paths, structure thresholds, or LSH tuning can live in config files, environment variables, or direct flags.\n- Profiles, module toggles, and quality gates can be version-controlled to keep CI deterministic.\n\nSelect via `--format`:\n\n- `jsonl` ,`json` ,`yaml` – machine-friendly ingestion.\n- `markdown` ,`html` ,`pretty` – human-friendly reports powered by`src/io/reports` handlebars templates.\n- `csv` – spreadsheet-ready metrics.\n- `sonar` – SonarQube compatibility.\n- `ci-summary` – concise JSON for bots.\n\n```\ncargo fmt && cargo clippy\ncargo test\n./scripts/install_parsers.sh  # install/update tree-sitter grammars\n```\n\nThe codebase follows a modular architecture with clear separation of concerns:\n\n- `src/core/` – pipeline orchestration, AST services, dependency analysis\n- `src/detectors/` – analysis modules (complexity, structure, lsh, cohesion, coverage)\n- `src/doc_audit/` – documentation gap detection with language-specific scanners\n- `src/bin/cli/` – command handling, quality gates, config building, report generation\n\nHelpful references:\n\n- `docs/CLI_USAGE.md` – CLI walkthroughs.\n- `docs/ARCHITECTURE_DEEP_DIVE.md` – November 2025 architectural analysis and modernization plan.\n- `docs/CONFIG_GUIDE.md` /`docs/QUALITY_GATES_GUIDE.md` – configuration details.\n\nMIT License – see [LICENSE](/sibyllinesoft/valknut/blob/main/LICENSE).", "url": "https://wpnews.pro/news/valknut", "canonical_source": "https://github.com/sibyllinesoft/valknut", "published_at": "2026-09-11 21:08:20+00:00", "updated_at": "2026-09-11 21:23:33.990960+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["Valknut", "Sibylline Software", "Rust", "Python", "TypeScript", "Model Context Protocol", "TensorFlow", "OpenCV"], "alternates": {"html": "https://wpnews.pro/news/valknut", "markdown": "https://wpnews.pro/news/valknut.md", "text": "https://wpnews.pro/news/valknut.txt", "jsonld": "https://wpnews.pro/news/valknut.jsonld"}}