Metadata-Version: 2.3
Name: qubership-envgene-linter
Version: 0.0.4
Summary: Qubership EnvGene CLI that checks instance repositories for configuration placement, naming, secret handling, and reference integrity.
Keywords: envgene,linter,lint,configuration,yaml,quality
Author: Qubership
Maintainer: Qubership
Requires-Python: ~=3.12
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Provides-Extra: dev
Provides-Extra: release
Requires-Dist: build (>=1.2) ; extra == "release"
Requires-Dist: click (==8.1.7)
Requires-Dist: pytest (>=8.3) ; extra == "dev"
Requires-Dist: ruamel.yaml (==0.18.17)
Requires-Dist: twine (>=6) ; extra == "release"
Project-URL: Documentation, https://github.com/Netcracker/qubership-envgene/blob/feature/envgene-linter-dev/modules/envgene-linter/README.md
Project-URL: Homepage, https://github.com/Netcracker/qubership-envgene/tree/feature/envgene-linter-dev/modules/envgene-linter
Project-URL: Issues, https://github.com/Netcracker/qubership-envgene/issues
Project-URL: Source, https://github.com/Netcracker/qubership-envgene/tree/feature/envgene-linter-dev/modules/envgene-linter
Description-Content-Type: text/markdown

# EnvGene Linter

- [Install](#install)
- [Run a check](#run-a-check)
- [Open the report](#open-the-report)
- [Optional commands](#optional-commands)
- [Troubleshooting](#troubleshooting)

EnvGene Linter checks the configuration files in an EnvGene instance repository and saves the findings in an HTML report.

## Install

You need Python 3.12 or newer with pip. Run this command in a terminal to install or update the tool:

```bash
python -m pip install --upgrade qubership-envgene-linter
```

If your system uses `python3` instead of `python`, use `python3 -m pip` in that command.
You do not need to download the source code or build the package.

## Run a check

Open a terminal in the root of your instance repository: the directory containing `environments/`.
Run:

```bash
envgene-linter check
```

## Open the report

When the check finishes, the terminal shows the report location, for example:

```text
Report saved to: /path/to/instance-repository/envgene-linter-report.html
```

Open that HTML file in your browser. Each finding shows the affected file, the issue, and a suggested action.
The linter does not fix configuration files automatically.

Every successful check replaces the previous report. The report filename is added to the repository's `.gitignore`.
Errors and messages about skipped files appear in the terminal. Review those messages if a file could not be checked.

## Optional commands

To also display findings in the terminal:

```bash
envgene-linter check --console
```

To check a repository without changing directories:

```bash
envgene-linter check /path/to/instance-repository
```

Both commands also create the HTML report. The old `--html` flag is no longer needed or accepted.

## Troubleshooting

- If pip reports `externally-managed-environment`, install in a Python virtual environment.
  A virtual environment is optional for the linter, but some systems require one for pip installations.
- If the terminal cannot find `envgene-linter`, check that your Python scripts directory is on `PATH`.
  If you installed in a virtual environment, activate that environment first.
- If the linter reports a missing `environments/` directory, run it from the instance repository root.

This is an alpha release. Checks cover supported references and generator inputs, not every file in the repository.
Exit code `0` means the check completed, including runs with findings. Exit code `2` indicates a command or execution error.

# EnvGene Linter changelog

- [0.0.4](#004)
- [0.0.3](#003)
- [0.0.2](#002)
- [0.0.1](#001)

## 0.0.4

- Add INT-3 to report used reference names defined at multiple environment, cluster, or repository scopes.
  Checks cover ParameterSets, shared Credential files, Resource Profile Overrides, and Shared Template Variables.
- Add INT-4 to flag authored entities for which no references were found in available local sources.
  Findings recommend Review and explain uncertainty, including external templates and rendered references.
  The rule does not establish that removal is safe or delete entities automatically.
- Add NAME-8 to check that selected default Cloud Passports use the filename stem `passport`
  and their selected companion Credential files use `passport-creds`.
  The `passport-infra` file and its companion are excluded.
- Enable INT-3, INT-4, and NAME-8 by default, bringing the implemented rule catalog to 21 rules.
- Remove the Type row and its colored chips from HTML findings.
  Cards retain File, Issue, Action, and Fix suggestion. Console severity remains unchanged.
- Show the repository's root folder name below the HTML report heading and in the browser tab title.
  Escape special characters and show the name even when there are no findings.
- Document local builds and installation from source.
- Add English specifications, designs, algorithms, tests, and runnable examples for the new rules.
  Update the documentation index to cover all 21 implemented rules.

## 0.0.3

- Simplify installation to one pip command and show how to run a check and open the HTML report.
- Include the complete changelog directly in the PyPI description, after the usage instructions.
- Verify that both distribution archives contain the instructions and changelog in their descriptions.

The CLI behavior and linter rules are unchanged from `0.0.2`.

## 0.0.2

- Allow `envgene-linter check` without a repository argument to check the current directory.
  Explicit repository paths remain supported.
- Create or update `envgene-linter-report.html` by default and print its absolute path.
- Add `--console` to also print findings in the terminal. Errors and parsing diagnostics remain visible by default.
- Remove `--html`. HTML reports are generated automatically, including when `--console` is used.
- Update installation instructions to use the `qubership-envgene-linter` package from PyPI.

To migrate from `0.0.1`, remove `--html` from existing commands.
Add `--console` to commands that need findings on stdout, including shell redirection and CI log collection.
Each successful check now writes the report and adds it to the checked repository's `.gitignore` if needed.
The report location must be writable. Findings still return exit code `0`, and operational errors return `2`.

## 0.0.1

- Initial PyPI release of `qubership-envgene-linter`.
- Check local instance repositories for placement, naming, secret handling, and reference integrity.
- Print findings in the terminal, with optional HTML output through `--html`.
- Support rule switches configured when the package is built.

