Metadata-Version: 2.5
Name: suitescript-checker
Version: 1.0.1
Summary: Scan Bitbucket Cloud workspaces for SuiteScript 1.0 / 2.x evidence and report to Excel
Author: Folio3
License: Proprietary
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: openpyxl>=3.1
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.31
Requires-Dist: tree-sitter-javascript>=0.23
Requires-Dist: tree-sitter>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: responses>=0.25; extra == 'dev'
Description-Content-Type: text/markdown

# SuiteScript Version Checker

Cross-platform Python CLI that scans every accessible repository in a Bitbucket
Cloud workspace, inspects the latest commit of every remote branch for SuiteScript
version evidence, and writes an Excel report.

Everything runs locally with read-only access. No repository modifications,
pipelines, webhooks, or frontend are required.

## Requirements

- Python 3.11+
- Git installed and available on `PATH`
- Bitbucket Cloud personal API token with Bitbucket scopes, at least
  `read:repository:bitbucket` (a token with **no Bitbucket scopes** will return 401)
- A credentials file containing:
  - `BITBUCKET_EMAIL` — your Atlassian account email
  - `BITBUCKET_API_TOKEN` — API token that includes Bitbucket scopes

## Install (end users)

1. Install [Python 3.11+](https://www.python.org/downloads/) and [Git](https://git-scm.com/).
2. Create and activate a virtual environment:

```bash
# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate

# Windows (cmd)
python -m venv .venv
.venv\Scripts\activate.bat

# Windows (PowerShell)
python -m venv .venv
.venv\Scripts\Activate.ps1
```

3. Upgrade pip and install the package:

```bash
pip install -U pip
pip install suitescript-checker
```

4. Create a credentials file (any path; do not commit secrets):

```bash
BITBUCKET_EMAIL=you@example.com
BITBUCKET_API_TOKEN=your-api-token
```

## Usage

```bash
suitescript-checker scan \
  --workspace WORKSPACE_SLUG \
  --creds /path/to/creds.env
```

`--output` is optional. If omitted, the detailed report is written as
`version-report.xlsx` in the current working directory. A second sibling file
`{stem}-repo-summary.xlsx` is always written beside it (for example
`version-report-repo-summary.xlsx` or `report-repo-summary.xlsx`).

```bash
suitescript-checker scan \
  --workspace WORKSPACE_SLUG \
  --creds /path/to/creds.env \
  --output /path/to/report.xlsx
# also writes /path/to/report-repo-summary.xlsx
```

Flags:

- `--workspace` — required Bitbucket Cloud workspace slug
- `--creds` — required path to the credentials file
- `--output` — optional detailed Excel path (default: `./version-report.xlsx`);
  also writes `{stem}-repo-summary.xlsx` beside it
- `--cache-dir DIR` — override the local bare-Git / detection cache
- `--repo SLUG` — repeatable filter; scan only the listed repositories

Default cache locations:

- Linux/macOS: `~/.cache/suitescript-checker`
- Windows: `%LOCALAPPDATA%\suitescript-checker`

## Developer install (this repository)

```bash
# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate

pip install -e ".[dev]"
```

Optional local credentials for live tests (gitignored):

```bash
# cp .env.example .env
# then edit .env
BITBUCKET_EMAIL=you@example.com
BITBUCKET_API_TOKEN=your-api-token
```

```bash
suitescript-checker scan \
  --workspace WORKSPACE_SLUG \
  --creds .env \
  --output report.xlsx
```

## What is detected

| Classification | Evidence |
|---|---|
| **1.0** | Real `nlapi*` / `nlobj*` usage outside comments and strings |
| **2.0** | `@NApiVersion 2.0` |
| **2.x** | `@NApiVersion 2.x` only — shown in **2.x available** / **filepaths_2.x** (syntax hint kept in review reason) |
| **2.1** | `@NApiVersion 2.1` is authoritative (even if `window.opener.nlapi*` remains). **Not** listed in 1.0 / 2.0 / 2.x summary columns |
| **Needs review** | Conflicts, parse failures, LFS pointers, submodules, ambiguous shadows |
| **Unclassified** | Ordinary JavaScript with no SuiteScript signals |

Scans branch tips only (no commit history, no tags). React/helper JS without
SuiteScript markers remains unclassified.

## Excel reports

Two workbooks are written on every successful write:

1. **Detailed report** (`--output`) — three worksheets:
   - **Branch Summary** — per branch tip: `1.0` / `2.0` / `2.x` Yes-No flags, filepath columns, needs-review count + `review_count_files_path`
   - **File Details** — per-file classification with Bitbucket deep links
   - **Run Details** — workspace, detector version, `2.x` syntax-resolution policy, coverage, errors
2. **Repo summary** (`{stem}-repo-summary.xlsx`) — one row per repository with only:
   `Repo Name`, `Repo Link`, `1.0 available`, `2.0 available`, `2.x available`
   (Yes if any scanned branch tip has that version available)

Exit codes:

- `0` — completed coverage
- `1` — partial coverage (isolated repo/branch failures)
- `2` — fatal setup / authentication / output failure

Legacy findings alone do **not** cause a non-zero exit.

## Automated tests

```bash
pytest
```

Tests use local Git fixtures and mocked Bitbucket HTTP. No network access is required.

## Live end-to-end (manual)

```bash
suitescript-checker scan \
  --workspace YOUR_TEST_WORKSPACE \
  --creds /path/to/creds.env \
  --output report.xlsx
```

Confirm the report covers every accessible branch tip and that remotes were not
modified (read-only clone/fetch only).

Switching from a test workspace to Folio3 only requires changing `--workspace`
and, if needed, the credentials file.
