<div align="center">
# Niti by Vajra
[](https://project-vajra.github.io/niti/)
[](https://discord.gg/wjaSvGgsNN)
[](https://pypi.org/project/niti/)
Fast, Modern, Lean Linter for C++ code for Vajra. Easy to configure no frills supercharged C++ linter with plugin support for custom rules.
</div>
## Setup
### Installation
```bash
pip install rekha
```
## Usage
### Basic Linting
```bash
# Lint a single file
niti path/to/file.cpp
# Lint a directory (recursively finds all C++ files)
niti path/to/project/
# Lint current directory
niti .
# Show help and available options
niti --help
# List all available rules
niti --list-rules
# List rules with descriptions
niti --list-rules --verbose
```
### Discovering Available Rules
Before disabling rules, you can discover what rules are available and which ones are triggering:
```bash
# See all available rules and their categories
niti --list-rules
# Run linter to see which rules are being triggered
niti --check your_project/
# Get detailed information about specific rule violations
niti --check --verbose your_file.cpp
```
### Configuration File (.nitirc or niti.yaml)
Create a `.nitirc` or `niti.yaml` file in your project root to customize linting behavior:
```yaml
# Basic configuration
documentation_style: doxygen # Options: doxygen, javadoc, plain
copyright_holders:
- "Your Organization"
- "Your Team"
# File organization
header_extensions: [".h", ".hpp", ".hxx"]
source_extensions: [".cpp", ".cc", ".cxx"]
excluded_paths: ["/kernels/", "/test/", "/build/"]
# Disable specific rules globally
disabled_rules:
- type-forbidden-int
- modern-missing-noexcept
- doc-function-missing
# Enable specific rules (overrides defaults)
enabled_rules:
- modern-nodiscard-missing
- doc-function-param-desc-quality
# Override rule severities
rule_severities:
naming-function-case: error
safety-raw-pointer-param: warning
doc-class-missing: info
```
### Disabling Rules
Niti supports multiple approaches for rule suppression:
**Configuration-based (global):**
```yaml
# .nitirc or niti.yaml
rules:
type-forbidden-int:
enabled: false
naming-variable-case:
severity: warning
```
**Comment-based (NOLINT):**
```cpp
int value = 42; // NOLINT
int badName = 10; // NOLINT naming-variable-case
int multiple = 99; // NOLINT type-forbidden-int,naming-variable-case
// NOLINTNEXTLINE type-forbidden-int
int nextLine = 24;
```
**File-level disable:**
```cpp
// niti-lint-disable naming-variable-case
// niti-lint-disable type-forbidden-int
```
📚 **[Complete Rule Suppression Guide →](docs/source/index.md#rule-suppression-and-configuration)**
## Development
### Prerequisites
- Python 3.8 or higher
### Setting Up Development Environment
We recommend using a virtual environment to isolate dependencies. You can use either `uv` or `conda`:
#### Option 1: Using uv (Recommended)
```bash
# Clone the repository
git clone https://github.com/project-vajra/niti.git
cd niti
# Create and activate virtual environment with uv
uv venv
source .venv/bin/activate
# Install dependencies
# For development:
uv pip install -r requirements-dev.txt
# Install Niti
uv pip install -e .
# Or install directly with optional dependencies:
uv pip install -e .[dev]
```
#### Option 2: Using conda/mamba
```bash
# Clone the repository
git clone https://github.com/project-vajra/niti.git
cd niti
# Create conda environment from file
conda env create -f environment.yml
conda activate niti
# Install the package in editable mode
pip install -e .
# Or use the Makefile for convenience
make install-dev
```
### Installing Dependencies
The project has the following main dependencies:
- `pyyaml`: For configuration file parsing
- `tree-sitter` & `tree-sitter-cpp`: For C++ code parsing
Development dependencies include:
- `pytest`: Testing framework
- `black`, `isort` & `autoflake`: Code formatting and cleanup
- `flake8` & `mypy`: Linting and type checking
- `pytest-cov`: Coverage reporting
**Note**: Niti is not yet available on PyPI. For now, please install from source as shown above.
### Development Workflow
#### Running Tests using PyTests
Niti has a comprehensive test suite organized into unit and integration tests:
```bash
# Run all tests
pytest
# Run all tests with coverage report
pytest --cov=niti --cov-report=html
# Run only unit tests (fast, isolated)
pytest -m unit
# Run only integration tests (slower, end-to-end)
pytest -m integration
# Run tests for specific rule categories
pytest test/unit/naming/ # Naming convention rules
pytest test/unit/safety/ # Safety rules
pytest test/unit/modern_cpp/ # Modern C++ rules
pytest test/unit/documentation/ # Documentation rules
# Run tests with verbose output
pytest -v
# Run a specific test file
pytest test/unit/types/test_type_rules.py
# Run a specific test method
pytest test/unit/naming/test_naming_rules.py::TestNamingFunctionCase::test_detects_snake_case_functions
```
##### Using the Custom Test Runner
The project includes a custom test runner for convenience:
```bash
# Run unit tests
python test/run_tests.py unit
# Run integration tests
python test/run_tests.py integration
# Run all tests
python test/run_tests.py all
# Run with verbose output and coverage
python test/run_tests.py unit -v -c
```
##### Test Structure
The test suite is organized as follows:
- **`test/unit/`**: Fast, isolated unit tests organized by rule category
- **`test/integration/`**: End-to-end integration tests
- **`test/fixtures/`**: Reusable C++ code samples for testing
- **`test/test_utils.py`**: Base classes and testing utilities
Each rule category has comprehensive positive (should pass) and negative (should fail) test cases using real C++ code examples.
#### Code Quality Checks
You can use individual commands or the convenient Makefile targets:
##### Using Makefile (Recommended)
```bash
# Format code (autoflake + black + isort)
make format
# Run linting (flake8 + mypy)
make lint
# Run tests
make test
# Run tests with coverage
make test-cov
# Show all available commands
make help
```
#### Project Structure
```
niti/
├── niti/ # Main package
│ ├── cli.py # Command-line interface
│ ├── core/ # Core functionality
│ │ ├── config.py # Configuration handling
│ │ ├── engine.py # Linting engine
│ │ ├── issue.py # Issue representation
│ │ └── severity.py # Severity levels
│ └── rules/ # Linting rules (54+ rules across categories)
│ ├── base.py # Base rule classes
│ ├── naming.py # Naming convention rules
│ ├── safety.py # Safety-related rules
│ ├── modern_cpp.py # Modern C++ best practices
│ ├── documentation.py # Documentation requirements
│ ├── types.py # Type system rules
│ └── ... # Other rule categories
├── test/ # Comprehensive test suite
│ ├── unit/ # Unit tests by rule category
│ │ ├── naming/ # Tests for naming rules
│ │ ├── safety/ # Tests for safety rules
│ │ ├── modern_cpp/ # Tests for modern C++ rules
│ │ ├── documentation/ # Tests for documentation rules
│ │ ├── types/ # Tests for type system rules
│ │ └── ... # Other rule category tests
│ ├── integration/ # End-to-end integration tests
│ ├── fixtures/ # Reusable C++ code samples
│ ├── test_utils.py # Testing base classes and utilities
│ └── run_tests.py # Custom test runner
├── pyproject.toml # Project configuration
├── Makefile # Development workflow commands
├── CLAUDE.md # Claude Code assistant guidance or for other Agentic tools
└── README.md # This file
```
## Examples
Full sample on using the Linter in a large-scale C++ project in the Vajra project will be out soon. We're building [Vajra](https://github.com/project-vajra/vajra) the second-generation LLM serving engine in C++. Watch out this space for more details soon.
## License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "niti",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "c++, linter, static-analysis, code-quality",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/7d/46/54d8b5f72eec562d9cf21006f23c8fb9920811be60d682892e10bfe89b6e/niti-0.1.3.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# Niti by Vajra \n\n\n[](https://project-vajra.github.io/niti/)\n[](https://discord.gg/wjaSvGgsNN)\n[](https://pypi.org/project/niti/)\n\n\nFast, Modern, Lean Linter for C++ code for Vajra. Easy to configure no frills supercharged C++ linter with plugin support for custom rules.\n\n</div>\n\n## Setup\n\n### Installation\n\n```bash\npip install rekha\n```\n\n## Usage\n\n### Basic Linting\n\n```bash\n# Lint a single file\nniti path/to/file.cpp\n\n# Lint a directory (recursively finds all C++ files)\nniti path/to/project/\n\n# Lint current directory\nniti .\n\n# Show help and available options\nniti --help\n\n# List all available rules\nniti --list-rules\n\n# List rules with descriptions\nniti --list-rules --verbose\n```\n\n### Discovering Available Rules\n\nBefore disabling rules, you can discover what rules are available and which ones are triggering:\n\n```bash\n# See all available rules and their categories\nniti --list-rules\n\n# Run linter to see which rules are being triggered\nniti --check your_project/\n\n# Get detailed information about specific rule violations\nniti --check --verbose your_file.cpp\n```\n\n### Configuration File (.nitirc or niti.yaml)\n\nCreate a `.nitirc` or `niti.yaml` file in your project root to customize linting behavior:\n\n```yaml\n# Basic configuration\ndocumentation_style: doxygen # Options: doxygen, javadoc, plain\ncopyright_holders:\n - \"Your Organization\"\n - \"Your Team\"\n\n# File organization\nheader_extensions: [\".h\", \".hpp\", \".hxx\"]\nsource_extensions: [\".cpp\", \".cc\", \".cxx\"] \nexcluded_paths: [\"/kernels/\", \"/test/\", \"/build/\"]\n\n# Disable specific rules globally \ndisabled_rules:\n - type-forbidden-int\n - modern-missing-noexcept\n - doc-function-missing\n\n# Enable specific rules (overrides defaults)\nenabled_rules:\n - modern-nodiscard-missing\n - doc-function-param-desc-quality\n\n# Override rule severities\nrule_severities:\n naming-function-case: error\n safety-raw-pointer-param: warning\n doc-class-missing: info\n```\n\n### Disabling Rules\n\nNiti supports multiple approaches for rule suppression:\n\n**Configuration-based (global):**\n```yaml\n# .nitirc or niti.yaml\nrules:\n type-forbidden-int:\n enabled: false\n naming-variable-case:\n severity: warning\n```\n\n**Comment-based (NOLINT):**\n```cpp\nint value = 42; // NOLINT\nint badName = 10; // NOLINT naming-variable-case\nint multiple = 99; // NOLINT type-forbidden-int,naming-variable-case\n\n// NOLINTNEXTLINE type-forbidden-int\nint nextLine = 24;\n```\n\n**File-level disable:**\n```cpp\n// niti-lint-disable naming-variable-case\n// niti-lint-disable type-forbidden-int\n```\n\n\ud83d\udcda **[Complete Rule Suppression Guide \u2192](docs/source/index.md#rule-suppression-and-configuration)**\n\n\n## Development\n\n### Prerequisites\n\n- Python 3.8 or higher\n\n### Setting Up Development Environment\n\nWe recommend using a virtual environment to isolate dependencies. You can use either `uv` or `conda`:\n\n#### Option 1: Using uv (Recommended)\n```bash\n# Clone the repository\ngit clone https://github.com/project-vajra/niti.git\ncd niti\n\n# Create and activate virtual environment with uv\nuv venv\nsource .venv/bin/activate \n\n# Install dependencies\n# For development:\nuv pip install -r requirements-dev.txt\n# Install Niti\nuv pip install -e .\n\n# Or install directly with optional dependencies:\nuv pip install -e .[dev]\n```\n\n#### Option 2: Using conda/mamba\n```bash\n# Clone the repository\ngit clone https://github.com/project-vajra/niti.git\ncd niti\n\n# Create conda environment from file\nconda env create -f environment.yml\nconda activate niti\n\n# Install the package in editable mode\npip install -e .\n\n# Or use the Makefile for convenience\nmake install-dev\n```\n\n### Installing Dependencies\n\nThe project has the following main dependencies:\n- `pyyaml`: For configuration file parsing\n- `tree-sitter` & `tree-sitter-cpp`: For C++ code parsing\n\nDevelopment dependencies include:\n- `pytest`: Testing framework\n- `black`, `isort` & `autoflake`: Code formatting and cleanup\n- `flake8` & `mypy`: Linting and type checking\n- `pytest-cov`: Coverage reporting\n\n**Note**: Niti is not yet available on PyPI. For now, please install from source as shown above.\n\n### Development Workflow\n\n#### Running Tests using PyTests\n\nNiti has a comprehensive test suite organized into unit and integration tests:\n\n```bash\n# Run all tests\npytest\n\n# Run all tests with coverage report\npytest --cov=niti --cov-report=html\n\n# Run only unit tests (fast, isolated)\npytest -m unit\n\n# Run only integration tests (slower, end-to-end)\npytest -m integration\n\n# Run tests for specific rule categories\npytest test/unit/naming/ # Naming convention rules\npytest test/unit/safety/ # Safety rules\npytest test/unit/modern_cpp/ # Modern C++ rules\npytest test/unit/documentation/ # Documentation rules\n\n# Run tests with verbose output\npytest -v\n\n# Run a specific test file\npytest test/unit/types/test_type_rules.py\n\n# Run a specific test method\npytest test/unit/naming/test_naming_rules.py::TestNamingFunctionCase::test_detects_snake_case_functions\n```\n\n##### Using the Custom Test Runner\n\nThe project includes a custom test runner for convenience:\n\n```bash\n# Run unit tests\npython test/run_tests.py unit\n\n# Run integration tests\npython test/run_tests.py integration\n\n# Run all tests\npython test/run_tests.py all\n\n# Run with verbose output and coverage\npython test/run_tests.py unit -v -c\n```\n\n##### Test Structure\n\nThe test suite is organized as follows:\n- **`test/unit/`**: Fast, isolated unit tests organized by rule category\n- **`test/integration/`**: End-to-end integration tests\n- **`test/fixtures/`**: Reusable C++ code samples for testing\n- **`test/test_utils.py`**: Base classes and testing utilities\n\nEach rule category has comprehensive positive (should pass) and negative (should fail) test cases using real C++ code examples.\n\n#### Code Quality Checks\n\nYou can use individual commands or the convenient Makefile targets:\n\n##### Using Makefile (Recommended)\n```bash\n# Format code (autoflake + black + isort)\nmake format\n\n# Run linting (flake8 + mypy)\nmake lint\n\n# Run tests\nmake test\n\n# Run tests with coverage\nmake test-cov\n\n# Show all available commands\nmake help\n```\n\n#### Project Structure\n```\nniti/\n\u251c\u2500\u2500 niti/ # Main package\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u251c\u2500\u2500 core/ # Core functionality\n\u2502 \u2502 \u251c\u2500\u2500 config.py # Configuration handling\n\u2502 \u2502 \u251c\u2500\u2500 engine.py # Linting engine\n\u2502 \u2502 \u251c\u2500\u2500 issue.py # Issue representation\n\u2502 \u2502 \u2514\u2500\u2500 severity.py # Severity levels\n\u2502 \u2514\u2500\u2500 rules/ # Linting rules (54+ rules across categories)\n\u2502 \u251c\u2500\u2500 base.py # Base rule classes\n\u2502 \u251c\u2500\u2500 naming.py # Naming convention rules\n\u2502 \u251c\u2500\u2500 safety.py # Safety-related rules\n\u2502 \u251c\u2500\u2500 modern_cpp.py # Modern C++ best practices\n\u2502 \u251c\u2500\u2500 documentation.py # Documentation requirements\n\u2502 \u251c\u2500\u2500 types.py # Type system rules\n\u2502 \u2514\u2500\u2500 ... # Other rule categories\n\u251c\u2500\u2500 test/ # Comprehensive test suite\n\u2502 \u251c\u2500\u2500 unit/ # Unit tests by rule category\n\u2502 \u2502 \u251c\u2500\u2500 naming/ # Tests for naming rules\n\u2502 \u2502 \u251c\u2500\u2500 safety/ # Tests for safety rules\n\u2502 \u2502 \u251c\u2500\u2500 modern_cpp/ # Tests for modern C++ rules\n\u2502 \u2502 \u251c\u2500\u2500 documentation/ # Tests for documentation rules\n\u2502 \u2502 \u251c\u2500\u2500 types/ # Tests for type system rules\n\u2502 \u2502 \u2514\u2500\u2500 ... # Other rule category tests\n\u2502 \u251c\u2500\u2500 integration/ # End-to-end integration tests\n\u2502 \u251c\u2500\u2500 fixtures/ # Reusable C++ code samples\n\u2502 \u251c\u2500\u2500 test_utils.py # Testing base classes and utilities\n\u2502 \u2514\u2500\u2500 run_tests.py # Custom test runner\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 Makefile # Development workflow commands\n\u251c\u2500\u2500 CLAUDE.md # Claude Code assistant guidance or for other Agentic tools\n\u2514\u2500\u2500 README.md # This file\n```\n\n## Examples\n\nFull sample on using the Linter in a large-scale C++ project in the Vajra project will be out soon. We're building [Vajra](https://github.com/project-vajra/vajra) the second-generation LLM serving engine in C++. Watch out this space for more details soon.\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the LICENSE file for details.\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "A modern C++ linter written in Python",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/project-vajra/niti/issues",
"Documentation": "https://project-vajra.github.io/niti/",
"Repository": "https://github.com/project-vajra/niti.git"
},
"split_keywords": [
"c++",
" linter",
" static-analysis",
" code-quality"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0307e2a06a52b1b030d6eb4bb2f914a011138fea835f0e8ad7cef2ac88a7e5d8",
"md5": "ad45cbf31578d3df9b3ce242a376d32a",
"sha256": "6b844b4dcdad45c8c748a7938e8693e6e571c85214f735ded1e18f6b728ab241"
},
"downloads": -1,
"filename": "niti-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ad45cbf31578d3df9b3ce242a376d32a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 105243,
"upload_time": "2025-08-30T21:34:04",
"upload_time_iso_8601": "2025-08-30T21:34:04.110145Z",
"url": "https://files.pythonhosted.org/packages/03/07/e2a06a52b1b030d6eb4bb2f914a011138fea835f0e8ad7cef2ac88a7e5d8/niti-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7d4654d8b5f72eec562d9cf21006f23c8fb9920811be60d682892e10bfe89b6e",
"md5": "5e4d1cae8855a157b5f7979b4509fd7b",
"sha256": "44ba47daff35fa99f1e4a02b9a49e9a8e1f2d032052e68f20eeceace849e6bee"
},
"downloads": -1,
"filename": "niti-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "5e4d1cae8855a157b5f7979b4509fd7b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 100085,
"upload_time": "2025-08-30T21:34:05",
"upload_time_iso_8601": "2025-08-30T21:34:05.708743Z",
"url": "https://files.pythonhosted.org/packages/7d/46/54d8b5f72eec562d9cf21006f23c8fb9920811be60d682892e10bfe89b6e/niti-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 21:34:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "project-vajra",
"github_project": "niti",
"github_not_found": true,
"lcname": "niti"
}
JSON
