@vasanth-mv/pqs-cli 1.1.0

package/python/README.md

@@ -0,0 +1,236 @@
+# qcBot — Python package
+
+> **Python interface for the qcBot test quality analyser.**
+> The rule engine runs in **Node.js** (via `npx @cqs/qcbot`).
+> Node.js 18+ must be on your PATH — the package checks for it at call time.
+
+---
+
+## Why Python?
+
+The rule engine is written in JavaScript/TypeScript and runs in Node.js.
+This Python package is a **thin subprocess bridge** — the same pattern
+Playwright itself uses for its Python SDK.
+
+- Zero rule duplication — one engine, many language wrappers
+- Returns structured Python objects (`PwQualityResult`, `FileResult`, `Finding`)
+- CLI (`qcbot-py check`) produces the same colour output as the Node.js CLI
+- Works in Python 3.9+
+
+---
+
+## Requirements
+
+| Requirement | Version |
+|-------------|---------|
+| Python | 3.9+ |
+| Node.js + npx | **18+** (checked at runtime) |
+
+---
+
+## Installation
+
+```bash
+# Library only (use as import)
+pip install qcbot
+
+# Library + command-line tool
+pip install "qcbot[cli]"
+```
+
+---
+
+## Quickstart — CLI
+
+```bash
+# Analyse a folder, fail if score < 80, generate HTML report
+qcbot-py check ./functional-tests --threshold 80 --report
+
+# List all supported stacks
+qcbot-py stacks
+
+# Get JSON output (pipe into jq, scripts, etc.)
+qcbot-py check ./tests --json | python3 -c "import sys,json; r=json.load(sys.stdin); print(r['score'], r['passed'])"
+```
+
+---
+
+## Quickstart — Python API
+
+```python
+from pw_quality import check
+
+# Basic check
+result = check("./functional-tests", threshold=80)
+
+print(result.score)        # 87
+print(result.passed)       # True
+print(result.grade)        # "Good"
+print(result.summary)      # Summary(critical=12, warnings=34, total=284, files=168)
+
+# Per-file breakdown
+for file in result.files:
+    print(f"{file.score:3}  {file.name}  ({file.critical_count} critical)")
+
+# All findings
+for finding in result.findings:
+    print(f"[{finding.severity}] {finding.title} — {finding.file}:{finding.line}")
+
+# Critical findings only
+criticals = result.critical_findings
+```
+
+---
+
+## API Reference
+
+### `check(path, *, stack, threshold, ...) → PwQualityResult`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `path` | str / Path | — | Directory with test files |
+| `stack` | str | `"playwright"` | Rule set id (`"typescript"`, `"pytest_api"`, …) |
+| `threshold` | int | `80` | Minimum passing score |
+| `parallel` | int | `4` | Parallel workers |
+| `report` | bool | `False` | Write HTML report to disk |
+| `output_dir` | str | `None` | Override report output directory |
+| `no_cross_file` | bool | `False` | Skip cross-file duplicate detection |
+| `project` | str | `None` | Project name in HTML report |
+| `npm_package` | str | `"@cqs/qcbot"` | Override for private npm registry |
+| `verbose` | bool | `False` | Print raw CLI output to stdout |
+
+### `PwQualityResult`
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `score` | int | Average quality score 0–100 |
+| `passed` | bool | True if score ≥ threshold |
+| `grade` | str | "Excellent" / "Good" / "Fair" / "Needs work" |
+| `threshold` | int | Threshold used for this run |
+| `summary` | Summary | `.critical`, `.warnings`, `.total`, `.files` |
+| `files` | list[FileResult] | Per-file breakdown |
+| `findings` | list[Finding] | All findings (flat, all files) |
+| `critical_findings` | list[Finding] | Only severity=critical |
+| `report_path` | str or None | Path to HTML report if `report=True` |
+
+---
+
+## CI / CD Integration
+
+### GitHub Actions
+
+```yaml
+- name: Install qcbot
+  run: pip install "qcbot[cli]"
+
+- name: Quality Gate
+  run: qcbot-py check ./tests --threshold 80 --report
+
+- name: Upload report
+  if: always()
+  uses: actions/upload-artifact@v4
+  with:
+    name: quality-report
+    path: qcbot-report/report.html
+```
+
+### pytest integration
+
+```python
+# conftest.py — add quality gate as a pytest fixture / session hook
+import pytest
+from pw_quality import check, PwQualityError
+
+def pytest_sessionfinish(session, exitstatus):
+    try:
+        result = check("./tests", threshold=80)
+        if not result.passed:
+            print(f"\n⚠  Quality gate FAILED — score {result.score} < 80")
+    except PwQualityError as e:
+        print(f"\n⚠  qcBot not available: {e}")
+```
+
+### Django / Flask API endpoint
+
+```python
+from pw_quality import check, PwQualityResult
+
+@app.post("/api/quality-gate")
+def quality_gate():
+    data = request.json
+    result: PwQualityResult = check(
+        data["path"],
+        stack=data.get("stack", "playwright"),
+        threshold=data.get("threshold", 80),
+    )
+    return {
+        "score":    result.score,
+        "passed":   result.passed,
+        "grade":    result.grade,
+        "critical": result.summary.critical,
+        "findings": [
+            {"rule": f.rule_id, "severity": f.severity, "title": f.title, "line": f.line}
+            for f in result.findings
+        ],
+    }
+```
+
+### Jenkins (Python-based pipeline)
+
+```python
+# Jenkinsfile (python-pipeline plugin) or a build script
+from pw_quality import check
+
+result = check("./functional-tests", threshold=80, report=True)
+print(f"Quality score: {result.score} — {'PASSED' if result.passed else 'FAILED'}")
+if not result.passed:
+    raise SystemExit(1)   # Fails the Jenkins step
+```
+
+---
+
+## Supported stacks
+
+```bash
+qcbot-py stacks
+```
+
+Includes: `playwright`, `typescript`, `java_api`, `restassured`, `karate`,
+`pytest_api`, `postman`, `python_api`, `ts_frontend`, `python_frontend`,
+`playwright_java`, `playwright_python`, and more.
+
+---
+
+## Error handling
+
+```python
+from pw_quality import check, PwQualityError
+
+try:
+    result = check("./tests")
+except PwQualityError as e:
+    print(f"Analysis failed: {e}")
+    # Common causes:
+    # - Node.js not found  → install Node 18+
+    # - npx not available  → ships with Node; re-install
+    # - Unknown stack      → run qcbot-py stacks
+```
+
+---
+
+## FAQ
+
+**Q: Does it send my code anywhere?**
+> No. All rule-based analysis runs locally in Node.js. Only if you pass `--llm` to the underlying CLI does it contact an AI provider, using your own API key.
+
+**Q: Do I need to install `@cqs/qcbot` separately?**
+> No — `npx` downloads and caches it automatically on first run.
+
+**Q: Can I use a private npm registry?**
+> Yes: `check(path, npm_package="@cqs/qcbot")` and set `NPM_TOKEN` in your environment.
+
+---
+
+## Licence
+
+MIT — © Your Company

package/python/pw_quality/__init__.py

@@ -0,0 +1,21 @@
+"""
+pw_quality — Python interface for the qcBot CLI.
+
+The rule engine lives in Node.js (npm: @cqs/qcbot).
+This package is a thin wrapper that:
+  1. Checks Node.js ≥ 18 is available
+  2. Optionally bootstraps the npm package via npx
+  3. Calls the CLI as a subprocess and returns structured Python objects
+
+Usage
+-----
+from pw_quality import check, stacks
+
+result = check("./functional-tests", threshold=80, report=True)
+print(result.score, result.passed, result.findings)
+"""
+
+from .runner import check, stacks, PwQualityResult, PwQualityError
+
+__all__ = ["check", "stacks", "PwQualityResult", "PwQualityError"]
+__version__ = "1.0.0"

package/python/pw_quality/cli.py

@@ -0,0 +1,177 @@
+"""
+cli.py — Click-based command-line interface for the pw_quality Python package.
+
+Installed as `qcbot-py` by pyproject.toml.
+Thin shell over runner.py — all analysis runs in Node.js via npx.
+"""
+
+import sys
+
+try:
+    import click
+except ImportError:
+    print(
+        "ERROR: 'click' is required. Install it with:  pip install qcbot[cli]",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+from . import runner
+
+
+# ── Formatting helpers ────────────────────────────────────────────────────────
+
+def _grade_color(score: int) -> str:
+    if score >= 90: return "bright_green"
+    if score >= 75: return "cyan"
+    if score >= 60: return "yellow"
+    return "red"
+
+
+def _sev_color(sev: str) -> str:
+    return {"critical": "red", "warning": "yellow"}.get(sev, "cyan")
+
+
+def _bar(score: int, width: int = 20) -> str:
+    filled = round(score / 100 * width)
+    return "█" * filled + "░" * (width - filled)
+
+
+# ── CLI definition ────────────────────────────────────────────────────────────
+
+@click.group()
+@click.version_option("1.0.0", prog_name="qcbot-py")
+def cli():
+    """qcBot — Playwright & multi-stack test quality analyser (Python interface).\n
+    The rule engine runs in Node.js (via npx @cqs/qcbot).
+    Node.js 18+ must be available on your PATH.
+    """
+
+
+@cli.command()
+@click.argument("path")
+@click.option("-s", "--stack",       default="playwright", show_default=True, help="Rule set id.  Run `qcbot-py stacks` for options.")
+@click.option("-t", "--threshold",   default=80, show_default=True, type=int,  help="Fail if score is below this (0–100).")
+@click.option("-p", "--parallel",    default=4,  show_default=True, type=int,  help="Max files analysed in parallel.")
+@click.option("--report",            is_flag=True,                             help="Generate self-contained HTML report.")
+@click.option("--output",            default=None,                             help="Output directory for HTML/JSON reports.")
+@click.option("--no-cross-file",     is_flag=True,                             help="Skip cross-file duplicate detection.")
+@click.option("--project",           default=None,                             help="Project name shown in the HTML report header.")
+@click.option("--json",   "json_out",is_flag=True,                             help="Print the full JSON result to stdout instead of the summary table.")
+@click.option("--package",           default="@cqs/qcbot",             help="Override npm package name (for private registries).")
+def check(path, stack, threshold, parallel, report, output, no_cross_file, project, json_out, package):
+    """Analyse test files in PATH and report quality findings.
+
+    PATH is a directory or glob that contains the spec/test files.
+
+    \b
+    Examples:
+      qcbot-py check ./functional-tests
+      qcbot-py check ./tests --stack pytest_api --threshold 75 --report
+      qcbot-py check ./src/tests --json | jq '.score'
+    """
+    click.echo(f"\n⚡ qcBot  ·  stack: {stack}  ·  threshold: {threshold}\n")
+
+    try:
+        result = runner.check(
+            path,
+            stack=stack,
+            threshold=threshold,
+            parallel=parallel,
+            report=report,
+            output_dir=output,
+            no_cross_file=no_cross_file,
+            project=project,
+            npm_package=package,
+            verbose=False,
+        )
+    except runner.PwQualityError as exc:
+        click.secho(f"✗ Error: {exc}", fg="red", err=True)
+        sys.exit(2)
+
+    if json_out:
+        import json as _json, dataclasses
+        def _serial(obj):
+            if dataclasses.is_dataclass(obj):
+                return dataclasses.asdict(obj)
+            raise TypeError(f"Not serialisable: {type(obj)}")
+        click.echo(_json.dumps(dataclasses.asdict(result), indent=2, default=_serial))
+        sys.exit(0 if result.passed else 1)
+
+    # ── Pretty terminal output ────────────────────────────────────────────────
+    gc = _grade_color(result.score)
+    click.echo("Results")
+    click.echo("─" * 52)
+    click.secho(f"  Score    {_bar(result.score)}  {result.score}  {result.grade}", fg=gc, bold=True)
+    click.echo(f"  Files    {result.summary.files}")
+    crit_color = "red" if result.summary.critical > 0 else "green"
+    warn_color = "yellow" if result.summary.warnings > 0 else "green"
+    click.secho(f"  Critical {result.summary.critical}", fg=crit_color, nl=False)
+    click.echo("  ", nl=False)
+    click.secho(f"Warnings {result.summary.warnings}", fg=warn_color, nl=False)
+    click.echo(f"  Total {result.summary.total}")
+    status_color = "green" if result.passed else "red"
+    status_text  = "✓ PASSED" if result.passed else "✗ FAILED"
+    click.secho(f"  Status   {status_text}  (threshold {threshold})", fg=status_color, bold=True)
+    click.echo("─" * 52)
+
+    # Per-file
+    click.echo()
+    click.echo("File breakdown")
+    for fr in result.files:
+        fc = _grade_color(fr.score)
+        crit = fr.critical_count
+        crit_label = click.style(f"{crit} crit  ", fg="red") if crit > 0 else click.style("✓      ", fg="green")
+        click.echo(
+            f"  {click.style(str(fr.score).rjust(3), fg=fc)}  "
+            f"{_bar(fr.score, 14)}  "
+            f"{crit_label}"
+            f"{click.style(fr.name, fg='bright_black')}"
+        )
+
+    # Top findings
+    top = [f for f in result.findings if f.severity in ("critical", "warning")][:10]
+    if top:
+        click.echo()
+        click.echo("Top findings")
+        for f in top:
+            click.secho(f"  {f.severity.upper():<9}", fg=_sev_color(f.severity), bold=True, nl=False)
+            click.echo(f" {f.title}")
+            loc = f.file or ""
+            if f.line:
+                loc += f":{f.line}"
+            click.secho(f"  {loc}  {f.rule_id}", fg="bright_black")
+
+    # Report link
+    if result.report_path:
+        click.echo()
+        click.secho(f"✓ HTML report → {result.report_path}", fg="green")
+        click.echo(f"  Open: open {result.report_path}")
+
+    click.echo()
+    sys.exit(0 if result.passed else 1)
+
+
+@cli.command()
+@click.option("--package", default="@cqs/qcbot", help="Override npm package name.")
+def stacks(package):
+    """List all supported stacks (language/framework rule sets)."""
+    try:
+        all_stacks = runner.stacks(npm_package=package)
+    except runner.PwQualityError as exc:
+        click.secho(f"✗ Error: {exc}", fg="red", err=True)
+        sys.exit(2)
+
+    click.echo("\nSupported stacks\n")
+    for s in all_stacks:
+        click.secho(f"  {s['id']:<22}", fg="cyan", bold=True, nl=False)
+        click.echo(s.get("label", ""))
+    click.echo()
+
+
+def main():
+    cli()
+
+
+if __name__ == "__main__":
+    main()