Metadata-Version: 2.4
Name: repo-signal
Version: 1.7.1
Summary: AI-assisted repo analysis for turning rough prototypes into clear, documented, publishable GitHub projects.
Author: Mattias Camner
License-Expression: MIT
Project-URL: Homepage, https://mcamner.github.io/repo-signal/
Project-URL: Repository, https://github.com/MCamner/repo-signal
Keywords: cli,github,repo-analysis,documentation,automation,developer-tools
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: ai
Requires-Dist: openai>=1.0; extra == "ai"
Requires-Dist: python-dotenv>=1.0; extra == "ai"
Provides-Extra: vector
Requires-Dist: chromadb>=0.5; extra == "vector"
Dynamic: license-file

# repo-signal

[![Tests](https://github.com/MCamner/repo-signal/actions/workflows/tests.yml/badge.svg)](https://github.com/MCamner/repo-signal/actions/workflows/tests.yml)
[![PyPI publish](https://github.com/MCamner/repo-signal/actions/workflows/pypi.yml/badge.svg)](https://github.com/MCamner/repo-signal/actions/workflows/pypi.yml)
[![Release](https://img.shields.io/github/v/release/MCamner/repo-signal?label=release)](https://github.com/MCamner/repo-signal/releases)
[![Version](https://img.shields.io/badge/version-1.4.2-blue)](VERSION)

**What problem does this solve?**
You have a local repo — maybe a prototype, a side project, or a tool in progress.
It works, but the README is thin, the docs are missing, the version is out of sync,
and you don't know if it's actually ready to publish. `repo-signal` tells you exactly
what's wrong and what to fix next.

**Who is this for?**
Developers who build small tools and want structured signals for when something is
actually ready. Works standalone or as a backend contract for AI agent workflows.

`repo-signal` turns local repository state into clear analysis reports,
publish-readiness signals, and machine-readable JSON contracts for AI-assisted
development workflows.

## MQ stack architecture

`repo-signal` is part of the MQ stack. It produces repo intelligence and
observations; it does **not** own durable memory. Whole-stack architecture and
the memory loop are documented in mqobsidian (source of truth):
[docs/architecture/mq-stack.md](https://github.com/MCamner/mqobsidian/blob/main/docs/architecture/mq-stack.md).

---

## Install

Recommended for the MQ stack:

```bash
uv tool install repo-signal
```

Verify the CLI is available:

```bash
repo-signal --version
```

If the uv tool bin directory is not on `PATH`, run:

```bash
uv tool update-shell
```

`pipx install repo-signal` remains a supported alternative.

Current local development install:

```bash
git clone https://github.com/MCamner/repo-signal.git
cd repo-signal
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[ai]"
```

See [PyPI publishing guide](docs/PYPI.md) for the release workflow.

---

## Usage

Use `repo-signal` from the root of any local Git repository. The normal loop is:

```bash
repo-signal analyze              # orient around repo type, stack and focus areas
repo-signal inspect              # fast status and recommended next commit
repo-signal review-export .      # write repo-review.v1 to mqobsidian/reviews
repo-signal doctor               # full repo health, docs, release and AI-readiness check
repo-signal publish-checklist .  # public release-readiness gate
```

For automation, prefer JSON outputs such as `repo-signal inspect --json`,
`repo-signal doctor --json`, and `repo-signal publish-checklist . --format json`.

---

## Try this in 60 seconds

```bash
# Get a high-level overview
repo-signal analyze

# Fast status report and next commit suggestion
repo-signal inspect

# Machine-readable status for integrations
repo-signal inspect --json

# Full readiness diagnosis
repo-signal doctor

# Check public-readiness signals
repo-signal publish-checklist .
```

---

## Command Surface

**Stable commands:**

```text
repo-signal
├── analyze            # Front-door orientation
├── inspect            # Fast status and next commit
├── inspect --json     # Machine-readable inspect.v1 contract
├── doctor             # Full readiness diagnosis
├── publish-checklist  # Public signal quality gate
├── report             # Unified report — inspect + publish-checklist in one
├── report --json      # Machine-readable report.v1 contract
├── suggest            # Safe patch suggestions — read-only, no mutations
├── suggest --json     # Machine-readable suggest.v1 contract
├── repoaware          # AI context export
└── demo               # Generate example reports
```

**Stable JSON contracts:** `inspect.v1` · `doctor.v1` · `report.v1` · `suggest.v1`

See the [Command Reference](docs/COMMANDS.md) and [Roadmap](ROADMAP.md) for full details.

---

## Screenshots

![inspect](docs/screenshots/inspect.png)

![publish-checklist](docs/screenshots/publish-checklist.png)

![inspect --json](docs/screenshots/inspect-json.png)

---

## Examples

- [Report (text)](examples/report/report.txt)
- [Report (JSON — report.v1)](examples/report/report.v1.json)
- [Suggest (text)](examples/suggest/suggest.txt)
- [Suggest (JSON — suggest.v1)](examples/suggest/suggest.v1.json)
- [Inspect (text)](examples/inspect/inspect.txt)
- [Inspect (JSON — inspect.v1)](examples/inspect/inspect.v1.json)
- [Doctor (text)](examples/doctor/doctor.txt)
- [Doctor (JSON — doctor.v1)](examples/doctor/doctor.v1.json)
- [Analyze](examples/analyze/analyze.txt)

Generate your own local demo reports:

```bash
repo-signal demo --generate
```

---

## Use with AI agents

`repo-signal` is designed as a backend contract for AI agent workflows.
All stable commands have JSON output that agent tools can consume safely:

```bash
# Check schema before parsing
repo-signal inspect --json . | python3 -c "
import json, sys
d=json.load(sys.stdin)
assert d['schema'] == 'inspect.v1'
print(d['recommended_next_commit'])
"
```

See [Integrations](docs/INTEGRATIONS.md) for mqlaunch, mq-agent, mq-mcp, and mq-hal patterns.

---

## Documentation

Live docs: [mcamner.github.io/repo-signal](https://mcamner.github.io/repo-signal/)

**Contracts:**

- [**Inspect Schema**](docs/INSPECT_SCHEMA.md) — `inspect.v1` field reference
- [**Doctor Schema**](docs/DOCTOR_SCHEMA.md) — `doctor.v1` field reference
- [**Report Schema**](docs/REPORT_SCHEMA.md) — `report.v1` field reference
- [**Suggest Schema**](docs/SUGGEST_SCHEMA.md) — `suggest.v1` field reference, no-mutation guarantee
- [**Review Export Schema**](docs/REVIEW_EXPORT_SCHEMA.md) — `repo-review.v1` Markdown contract
- [**Memory Observation Schema**](docs/MEMORY_OBSERVATION_SCHEMA.md) — `memory-observation.v1` producer fields
- [**mqobsidian Boundary**](docs/MQOBSIDIAN_BOUNDARY.md) — who owns what across both export paths, and how each fails

**Usage:**

- [**Command Reference**](docs/COMMANDS.md) — Detailed CLI usage and flags
- [**Integrations**](docs/INTEGRATIONS.md) — How mqlaunch, mq-mcp, mq-hal, and Bridget consume JSON contracts
- [**RepoAware**](docs/REPOAWARE.md) — High-signal AI context ranking and export
- [**Semantic Memory**](docs/SEMANTIC_MEMORY.md) — Uploading symbol maps to vector stores

**Publishing:**

- [**Packaging**](docs/PACKAGING.md) — PyPI / CLI tool readiness plan and packaging smoke tests
- [**PyPI**](docs/PYPI.md) — Real PyPI publishing guide and Trusted Publisher values
- [**Generated Examples**](docs/GENERATED_EXAMPLES.md) — How examples are generated and verified before release
- [**Roadmap**](ROADMAP.md) — Release direction and stability checklist

---

## Roadmap

Current focus is keeping the v1.x contracts stable while improving the quality
of repo-aware context for AI tools. Near-term work:

- keep `inspect.v1`, `doctor.v1`, `report.v1`, and `suggest.v1` stable
- exclude generated noise such as backup folders from entrypoint detection
- improve symbol extraction for non-Python repos, especially PowerShell-heavy tools
- keep examples and generated reports current for downstream agents

See [ROADMAP.md](ROADMAP.md) for the full roadmap.

---

## Contributing

Contributions should preserve the stable JSON contracts and keep commands safe
for automation. Before opening a PR, run:

```bash
pytest
repo-signal doctor . --json
repo-signal publish-checklist . --format json
```

When changing CLI output, update the matching docs and examples so agent
integrations keep a reliable contract.

---

## v1.7.1 status

- [x] 4 stable JSON contracts: `inspect.v1`, `doctor.v1`, `report.v1`, `suggest.v1`
- [x] 2 documented export contracts: `repo-review.v1`, `memory-observation.v1`
- [x] Full test suite passes — `388 passed, 219 subtests` on Python 3.11, 3.12
  and 3.14, and from a checkout directory that is not named `repo-signal`
- [x] Schema checks in `release.sh` for all four stable contracts, plus an
  `mqobsidian export contracts` section covering both export paths
- [x] Contract docs: `INSPECT_SCHEMA.md`, `DOCTOR_SCHEMA.md`, `REPORT_SCHEMA.md`,
  `SUGGEST_SCHEMA.md`, `REVIEW_EXPORT_SCHEMA.md`,
  `MEMORY_OBSERVATION_SCHEMA.md`
- [x] Generated examples: `examples/report/`, `examples/suggest/`,
  `examples/inspect/`, `examples/doctor/`, `examples/review-export/`
- [x] No machine-local path reaches an exported artifact — a shape invariant in
  `repo_signal/redaction.py`, not a convention
- [x] A scan describes the repository, not the machine: it asks git what belongs
  to the repo, so gitignored local tool directories cannot reach a generated
  example. Held by a test that asks git for the ignored set rather than
  hard-coding it
- [x] The mqobsidian boundary is proven end to end against a temporary vault:
  ownership, both export paths, and what each does when the vault is missing,
  unwritable or the wrong shape — `docs/MQOBSIDIAN_BOUNDARY.md`
- [x] The 26 top-level commands are declared once in `repo_signal/commands.py`;
  help, the unknown-command fallback and `docs/COMMANDS.md` are held to it
- [x] CLI surface frozen for v1.x
- [x] GitHub Actions green (Tests on 3.11 and 3.12, the renamed-checkout run,
  Docs consistency, Packaging, Generated examples, Publish checklist)
- [x] `.markdownlint.json` configured

See [CHANGELOG.md](CHANGELOG.md) for full release history.

---

## Author

Mattias Camner

Infrastructure / Platform Architect  
Builder of command surfaces, endpoint readiness prototypes, and structured
workflow systems.

---

## License

MIT
