Metadata-Version: 2.4
Name: github-first-impression
Version: 0.2.1
Summary: A rule-based audit of a public GitHub repository's presentation, documentation, installability, trust signals, and maintenance status
Author: GitHub First Impression contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/PiggyDoggo/GitHub-First-Impression
Project-URL: Repository, https://github.com/PiggyDoggo/GitHub-First-Impression
Project-URL: Issues, https://github.com/PiggyDoggo/GitHub-First-Impression/issues
Project-URL: Changelog, https://github.com/PiggyDoggo/GitHub-First-Impression/blob/main/CHANGELOG.md
Keywords: github,repository,readme,audit,cli
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: development
Requires-Dist: build>=1.2; extra == "development"
Requires-Dist: pytest>=8; extra == "development"
Requires-Dist: twine>=6; extra == "development"
Dynamic: license-file

# GitHub First Impression

[![CI](https://github.com/PiggyDoggo/GitHub-First-Impression/actions/workflows/ci.yml/badge.svg)](https://github.com/PiggyDoggo/GitHub-First-Impression/actions/workflows/ci.yml)

GitHub First Impression is a deterministic, rule-based command-line audit for public GitHub repositories.

It reviews repository presentation, README structure, installation and usage guidance, trust signals, releases, and maintenance indicators through GitHub's official REST API.

It can also act as a deterministic external quality gate after a coding agent pushes its work. Stable JSON output and process exit codes let automation distinguish a passing audit, a score below a configured threshold, and a tool error.

> **Important:** The score is a documentation and repository-presentation heuristic. It is not a code-quality, security, popularity, or maintainability guarantee.

## What it does

- Audits one user-supplied public repository at a time
- Checks repository metadata and README structure using deterministic rules
- Detects common installation, usage, community, packaging, release, and maintenance signals
- Produces a transparent score from 0 to 100
- Explains every awarded and missing score item
- Prints a concise terminal summary and writes a local Markdown report

## What it does not do

- It does not understand source code or README prose like a human reviewer.
- It does not determine overall project quality, security, or suitability for use.
- It does not replace manual code review, security review, or maintenance due diligence.
- It does not access private repositories, discover targets, or scan repositories in bulk.
- It does not use AI, access GitHub HTML pages, or evade API limits and access controls.

## Requirements

- Python 3.12 or newer
- Network access to GitHub's official REST API at `api.github.com`

## Installation

Trusted Publishing has been verified on TestPyPI. The first production PyPI release is being prepared. Until then, install from the GitHub source or a GitHub Release checkout. See [Trusted Publishing setup](docs/publishing.md) for the release process.

Clone the project and install it in a virtual environment:

```bash
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install .
```

## Usage

After installation, audit a single public repository URL:

```bash
github-first-impression https://github.com/owner/repository
```

The module entry point is equivalent:

```bash
python -m github_first_impression https://github.com/owner/repository
```

In the default text mode, the command prints a summary and creates `first-impression-report.md`. Select another report path with `--output PATH`, or use `--output -` to print only the terminal summary without writing Markdown.

## Using as an Agent Quality Gate

Request machine-readable output with:

```bash
github-first-impression \
  https://github.com/owner/repository \
  --format json
```

Set a deterministic minimum score from 0 to 100 with `--fail-under`:

```bash
github-first-impression \
  https://github.com/owner/repository \
  --format json \
  --fail-under 75
```

The command exits with `0` when the analysis passes, `1` when analysis succeeds but the score is below the configured threshold, and `2` for invalid input, API failures, network failures, or other tool errors. JSON mode writes exactly one JSON document to stdout; diagnostics are written to stderr.

JSON mode has no Markdown side effect by default, so it is safe in read-only CI workspaces and parallel Agent jobs. `artifacts.markdown_report` is `null`. Add `--output report.md` only when a Markdown artifact is wanted. `--output -` explicitly disables Markdown in either output format.

A shell workflow can preserve the structured result and handle each outcome separately:

```bash
set +e
github-first-impression "$REPOSITORY_URL" \
  --format json \
  --fail-under 75 \
  > audit.json
exit_code=$?
set -e

case "$exit_code" in
  0) echo "Quality gate passed" ;;
  1) echo "Quality gate failed; inspect audit.json" ;;
  2) echo "Audit tool error; inspect audit.json and stderr" ;;
esac
```

The `set +e` section preserves exit code `1` in scripts that otherwise use `set -e`.

Agents should not act on the total score alone. Read the stable rule IDs in `categories[].checks`, address `blocking_issues`, review `warnings`, push the fixes, and run the audit again. Blocking issues are only the highest-priority score deficits, not proof of an absolute defect and not a promise that fixing them alone will pass the threshold. Warning `source` distinguishes repository observations from analysis limitations. This is an external presentation and documentation heuristic—not a guarantee of code correctness, security, maintainability, or legal compliance.

The JSON contract is documented in [docs/json-output.md](docs/json-output.md).

### Optional GitHub token

Using `GITHUB_TOKEN` is optional. A token increases the normal API rate limit but is not used to bypass GitHub's restrictions. Prefer the environment variable because a command-line argument may be visible in shell history or process listings:

```bash
export GITHUB_TOKEN="your_token"
github-first-impression https://github.com/owner/repository
```

The less-private command-line alternative is also available:

```bash
github-first-impression https://github.com/owner/repository --token "your_token"
```

Use a token with no permissions beyond reading public repository information. The tool sends it only in the HTTPS `Authorization` header. It does not print, save, cache, rotate, place it in a URL, or include it in a report.

### Verbose score breakdown

Use `--verbose` to display every score item in the terminal. Markdown reports always include the complete breakdown.

```bash
github-first-impression https://github.com/owner/repository --verbose
```

## Example output format

The repository name and numbers below are illustrative placeholders, not the current result for a real repository:

```text
GITHUB FIRST IMPRESSION
=======================
Repository: example/example-repository
Overall Score: 78/100
Grade: Good

Category scores:
- Project description & positioning: 18/20
- README readability: 20/25
- Installation & usage: 16/20
- Project trust: 14/20
- Release & maintenance: 10/15

Run with --verbose to see the full score breakdown.

Markdown report written to first-impression-report.md
```

## Scoring

The 100 available points are divided into five categories:

| Category | Points |
| --- | ---: |
| Project description and positioning | 20 |
| README readability | 25 |
| Installation and usage | 20 |
| Trust signals | 20 |
| Release and maintenance | 15 |

The score is produced entirely by deterministic rules in `src/github_first_impression/scoring.py`; it contains no random component. The same repository state and README will usually produce the same result. A score can change when repository metadata, files, documentation, releases, tags, or maintenance activity change.

Grades are Excellent (90–100), Good (75–89), Fair (60–74), Weak (40–59), and Poor (0–39). These labels summarize checklist coverage, not intrinsic project quality.

The score is most useful as a checklist for repository maintainers. It should not be used as an absolute ranking between unrelated projects. In particular:

- Non-English READMEs and unconventional heading names may be underestimated.
- Information found only in external documentation may not earn README points.
- A mature project with a deliberately minimal root README may receive a relatively low score.
- A high score does not establish code quality, security, active maintenance, popularity, or fitness for a particular purpose.

## Known limitations

- README checks use headings, keywords, and regular expressions rather than semantic understanding.
- File presence does not prove that a policy, test suite, or configuration is complete or effective.
- GitHub can truncate recursive trees for extremely large repositories, causing files to be missed.
- “Recently updated” means a code push within two years and is only a broad activity signal.
- GitHub's open issue count can include open pull requests.
- Anonymous API access has a lower rate limit. The client stops on a rate-limit response and does not retry, change identity, or fall back to HTML access.
- Private repositories are intentionally unsupported.
- JSON schema `1.0` describes repository presentation signals only; it does not make source-code assertions.

## Responsible Use

Each audit is initiated by the user for one specific public repository and is performed only through GitHub's official REST API. Reports are generated locally. The tool does not access GitHub web pages, bypass access controls, evade rate limits, enumerate repositories, or collect contributor profiles.

Repository content remains subject to its original license and copyright terms. Users are responsible for following GitHub's Terms of Service and applicable laws. Read [RESPONSIBLE_USE.md](RESPONSIBLE_USE.md) for the complete boundaries and token-safety guidance.

## Development

Create a development environment and install the optional tooling:

```bash
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[development]"
```

### Running tests

```bash
python -m pytest
```

Build release artifacts with:

```bash
python -m build
```

## Changelog

Release notes are recorded in [CHANGELOG.md](CHANGELOG.md).

## License

GitHub First Impression is available under the [MIT License](LICENSE).
