Metadata-Version: 2.4
Name: github-first-impression
Version: 0.2.2
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)

## What is it?

A deterministic quality gate for AI coding agents and maintainers auditing the presentation of public GitHub repositories.

## Why?

Agents need a fast, predictable answer after changing a repository. GitHub First Impression applies transparent rules to documentation, installability signals, trust signals, releases, and maintenance indicators.

- **Deterministic:** every run produces the same score and audit decisions for the same repository state.
- **Reproducible:** rules and point allocations are public and contain no random component.
- **Machine-readable:** stable JSON fields and rule IDs support automation.
- **CI-friendly:** exit codes distinguish a passing gate, a failed gate, and a tool error.
- **Bounded:** it reads one public repository through GitHub's official REST API only.

It is not an AI reviewer, does not call an LLM, and does not analyze source-code quality. The score is a documentation and repository-presentation heuristic. It is not a code-quality, security, popularity, or maintainability guarantee.

## Installation

For an isolated command-line installation:

```bash
pipx install github-first-impression
```

Or install it into the active Python environment:

```bash
python -m pip install github-first-impression
```

Python 3.12 or newer is required.

## Quick example

```bash
github-first-impression \
  https://github.com/psf/requests \
  --format json \
  --fail-under 80
```

Selected fields from an actual run on August 3, 2026 are shown below. The full document also contains every category, scored check, and metadata; repository changes can change the result.

```json
{
  "schema_version": "1.0",
  "tool": {
    "name": "github-first-impression",
    "version": "0.2.1"
  },
  "repository": {
    "url": "https://github.com/psf/requests",
    "owner": "psf",
    "name": "requests",
    "default_branch": "main",
    "archived": false
  },
  "result": {
    "status": "pass",
    "score": 86,
    "grade": "Good",
    "threshold": 80
  },
  "blocking_issues": [],
  "warnings": [
    {
      "id": "readme_contribution_guidance_missing",
      "check_id": "readme_has_contribution_guidance",
      "severity": "warning",
      "source": "repository",
      "message": "README does not mention contribution guidance.",
      "suggested_fix": "Link to contribution guidance from the README."
    }
  ],
  "artifacts": {
    "markdown_report": null
  }
}
```

## Exit codes

| Exit | Meaning |
| ---: | --- |
| `0` | Quality gate passed |
| `1` | Quality gate failed |
| `2` | Tool error |

An invalid input, GitHub API failure, network failure, or local I/O failure is a tool error. Parse the JSON on every exit code instead of treating all nonzero results alike.

## Features

- Stable JSON output for agents and automated workflows
- Deterministic 100-point scoring with a configurable `--fail-under` threshold
- Prioritized `blocking_issues` when a repository misses the configured gate
- Stable category, check, issue, warning, and error IDs
- Explicit warning sources and concrete remediation suggestions
- Side-effect-free JSON mode unless a Markdown output path is requested
- CI-friendly exit codes and structured errors
- Optional Markdown reports for maintainers

## Documentation

- [Agent examples](docs/agent-examples.md)
- [JSON output contract](docs/json-output.md)
- [Publishing](docs/publishing.md)

## Usage

Audit one public GitHub repository:

```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
```

Text mode prints a terminal summary and creates `first-impression-report.md`. Use `--output PATH` to choose another report path or `--output -` to disable the Markdown report.

JSON mode has no Markdown side effect by default. Add `--output report.md` only when a Markdown artifact is wanted:

```bash
github-first-impression \
  https://github.com/owner/repository \
  --format json \
  --fail-under 80 \
  --output report.md
```

Use `--verbose` to include the full score breakdown in text-mode terminal output:

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

### Optional GitHub token

`GITHUB_TOKEN` is optional. It increases GitHub's normal API rate limit but does not grant private-repository support or bypass access controls. Prefer the environment variable because command-line values may appear in shell history or process listings:

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

Use a token with no permissions beyond reading public repository information. The tool sends it only in the HTTPS `Authorization` header and does not include it in JSON or Markdown reports.

## 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 |

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 for finding missing repository-presentation signals. It should not be used as an absolute ranking between unrelated projects.

## Limitations

GitHub First Impression does not verify:

- Code correctness or architecture
- Security or exploitability
- Dependency vulnerabilities or supply-chain safety
- Legal compliance or license compatibility
- Whether a project is suitable for a particular user

Additional boundaries:

- README checks use headings, keywords, and regular expressions rather than semantic understanding.
- Non-English READMEs and unconventional headings may be underestimated.
- Information available only in external documentation may not earn README points.
- File presence does not prove that a policy, test suite, or configuration is effective.
- GitHub may truncate very large repository trees, causing files to be missed.
- Private repositories and bulk repository discovery are intentionally unsupported.

## Responsible use

Each audit is initiated for one user-supplied public repository and uses only GitHub's official REST API. The tool does not access GitHub HTML, bypass access controls, evade rate limits, enumerate targets, or collect contributor profiles.

Read [RESPONSIBLE_USE.md](RESPONSIBLE_USE.md) for the complete boundaries and token-safety guidance.

## Development

```bash
git clone https://github.com/PiggyDoggo/GitHub-First-Impression.git
cd GitHub-First-Impression
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[development]"
python -m pytest
```

Build release artifacts with:

```bash
python -m build
```

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

## License

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