Metadata-Version: 2.4
Name: novash
Version: 0.1.0
Summary: Open-source SEO checker for websites
Author: Sanskar Garg
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: beautifulsoup4
Requires-Dist: rich
Requires-Dist: typer
Dynamic: license-file

# Novash

**Novash** is an open-source, command-line SEO checker for websites. Point it at a URL and it downloads the page, audits the core on-page SEO elements, scores the result out of 100, and tells you exactly what to fix — all from your terminal.

---

## Features

- 🔍 **Automated page crawling** — fetches and parses any public webpage, with built-in handling for timeouts, bad URLs, and connection errors.
- 📄 **Title check** — detects whether the page has a non-empty `<title>` tag.
- 📝 **Meta description check** — detects a non-empty `<meta name="description">` tag.
- 📌 **H1 check** — finds meaningful `<h1>` tags, automatically ignoring ones that are hidden (`display:none`, `aria-hidden`, etc.), empty, or too short to be a real heading.
- 🖼️ **Image alt-text audit** — counts every `<img>` tag and reports how many are missing `alt` text.
- 📊 **SEO scoring** — a 100-point score with clear, transparent deductions (see [Scoring](#scoring) below).
- 💡 **Actionable suggestions** — plain-language fixes generated from whatever the audit finds wrong.
- 📤 **JSON export** — save the full report to a file for use in other tools, dashboards, or CI pipelines.
- 🎨 **Colorful terminal output** — powered by [Rich](https://github.com/Textualize/rich), with green/yellow/red color-coding so you can scan a report at a glance.

---

## Installation

Novash requires **Python 3.8+**.

Clone the repository and install it locally:

```bash
git clone https://github.com/<your-username>/novash.git
cd novash
pip install .
```

This installs Novash's dependencies (`requests`, `beautifulsoup4`, `rich`, `typer`) and registers the `novash` command on your PATH.

For development (editable install, so code changes take effect immediately):

```bash
pip install -e .
```

---

## Usage Examples

Scan a website and print the report to your terminal:

```bash
novash scan https://example.com
```

Scan a website and also save the full report as JSON:

```bash
novash scan https://example.com --export report.json
```

View help for any command:

```bash
novash --help
novash scan --help
```

---

## CLI Commands

| Command | Description |
|---|---|
| `novash scan <url>` | Crawl a URL, run all SEO checks, calculate the score, and print the report. |
| `novash scan <url> --export <file>` | Same as above, and also save the full report as a pretty-printed JSON file. |
| `novash --help` | Show general help and available commands. |
| `novash scan --help` | Show detailed help for the `scan` command. |

### Options

| Option | Description |
|---|---|
| `--export <filename>` | Save the report as JSON, e.g. `--export report.json`. Optional. |

---

## Example Output

```
╭───────────────────╮
│ NOVASH SEO REPORT │
╰───────────────────╯
🌐 Website: https://example.com

📄 Title
✓ Title found:
  Example Domain

📝 Meta Description
✗ Meta description missing

📌 H1 Tags
✓ H1 tags found:
  - Example Domain

🖼️  Images
✓ Total images: 11
✓ Images with alt text: 1
✗ Images without alt text: 10

╭──────────────────────╮
│ ⚠️ SEO Score: 82/100 │
╰──────────────────────╯

💡 Suggestions
- Add a meta description.
- Add alt text to 10 images.
```

If every check passes, the Suggestions section shows a single line instead:

```
💡 Suggestions
✅ No SEO issues found.
```

### Scoring

Novash starts every page at **100 points** and deducts:

- **15 points** if the title is missing
- **15 points** if the meta description is missing
- **15 points** if no meaningful H1 tag is found
- **Up to 20 points**, proportional to the percentage of images missing alt text:
  `penalty = (images_without_alt / total_images) * 20`

The score never drops below 0, and is color-coded in the terminal:

| Score | Color |
|---|---|
| 90–100 | 🟢 Green |
| 70–89 | 🟡 Yellow |
| 0–69 | 🔴 Red |

---

## Roadmap

Planned improvements for future versions:

- [ ] Multi-page / full-site crawling (follow internal links)
- [ ] Additional checks: canonical tags, robots meta, Open Graph tags, heading hierarchy (H1–H6), broken links, page load time
- [ ] HTML and PDF report export, alongside JSON
- [ ] Configurable scoring weights via a config file
- [ ] Batch scanning of multiple URLs from a file
- [ ] CI/CD integration (fail a build if the score drops below a threshold)
- [ ] Publish to PyPI for `pip install novash`

Have an idea? Open an issue — see [Contributing](#contributing) below.

---

## Contributing

Contributions are welcome! To get started:

1. Fork the repository and clone your fork.
2. Create a new branch for your change:
   ```bash
   git checkout -b feature/your-feature-name
   ```
3. Install in editable mode so your changes are picked up immediately:
   ```bash
   pip install -e .
   ```
4. Make your changes, and keep functions small, documented, and covered by a quick manual test (each module includes a `if __name__ == "__main__":` block you can run directly, e.g. `python checks.py`).
5. Commit and push your branch, then open a pull request describing what you changed and why.

Please keep pull requests focused — one feature or fix per PR makes review much easier. Bug reports and feature requests are just as welcome as code; feel free to open an issue.

---

## License

This project is open-source. Add your preferred license (e.g. MIT) in a `LICENSE` file before publishing.
