public-surface-sweeper 0.1.1

Pre-release hygiene CLI for public repositories and proof-surface packets

public-surface-sweeper

public-surface-sweeper is a pre-release hygiene pass for repositories that are about to become public evidence. It checks the front door: required project files, secret-shaped text, obvious presentation defects, and proof-surface packet output for downstream review.

Use it before a repository asks a user, customer, reviewer, investor, or future maintainer to trust what it says.

It is intentionally narrow: a release-hygiene gate, not a full security scanner or certification tool.

Install

python -m pip install public-surface-sweeper

For local development:

python -m pip install -e ".[test]"
python -m pytest

Usage

public-surface-sweeper .
public-surface-sweeper . --json
public-surface-sweeper . --summary
public-surface-sweeper . --summary --json
public-surface-sweeper . --proof-packet
public-surface-sweeper . --fail-on warning

The command exits with status 1 when error-level findings are present.

Use --fail-on warning to fail on warnings and errors, or --fail-on none to print findings without failing the process.

Run the bundled clean fixture:

public-surface-sweeper examples/clean-repo

Expected output:

No findings.

What it checks

Required project files:

• README.md
• LICENSE
• AUTHORS.md
• CONTRIBUTING.md

Text hygiene:

• em dash characters in public-facing text

Secret-shaped values:

• private key block markers
• GitHub token shaped values
• OpenAI key shaped values
• AWS access key shaped values
• Slack token shaped values

The scanner skips common cache, build, virtualenv, and dependency directories. It also skips binary files and text files larger than 1 MB.

Example text output

ERROR LICENSE required-file: missing required file: LICENSE
ERROR README.md:12 em-dash: replace em dash with plain punctuation

Example JSON output

[
  {
    "path": "LICENSE",
    "line": 0,
    "rule": "required-file",
    "severity": "error",
    "message": "missing required file: LICENSE"
  }
]

Example summary output

score: 75
status: blocked
total_findings: 1
errors: 1
warnings: 0
action_items:
- LICENSE: missing required file: LICENSE

Summary mode is the fastest handoff format for release reviews. It gives a bounded readiness score, a status, finding counts, and the first actionable items to fix before publishing or showing the repository to a reviewer.

Proof-surface packet output

Use --proof-packet when the scan result should feed repo-proof-index or a release-readiness report. The packet follows the shared proof-surface interop shape: claims, checks, and action items in one JSON object. The generated packet is self-checked before printing so producer drift fails before entering the pipeline.

public-surface-sweeper . --proof-packet > public-surface.packet.json
repo-proof-index public-surface.packet.json --summary

What it does not do

• It does not perform exploit testing.
• It does not audit dependencies for vulnerabilities.
• It does not validate whether a credential is real.
• It does not certify that a repository is safe, compliant, or trustworthy.
• It does not replace a security review.

Release-readiness use

public-surface-sweeper is the first point in a proof-surface pipeline:

repo public surface -> hygiene findings -> proof index -> release-readiness report

Its job is to catch basic public-surface defects before a repository asks users, clients, employers, or reviewers to trust it.

Authorship

Created and maintained by Zain Dana Harper. Claude Code contributed to the initial implementation.