Metadata-Version: 2.2
Name: hmos-precheck
Version: 0.1.0
Summary: LLM-first low-noise Build@1 guard for HarmonyOS and ArkTS repos.
Author: OpenAI Codex
License: MIT
Keywords: harmonyos,arkts,precheck,cli,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# hmos-precheck

LLM-first, low-noise Build@1 guard for HarmonyOS / ArkTS repositories.

`hmos-precheck` is a small CLI for HarmonyOS repositories. It focuses on
changed files, keeps stdout compact, and degrades cleanly when optional
HarmonyOS tooling is not configured.

## Features

- runs low-noise SDK-backed checks for ArkTS and CodeLinter
- writes compact repair-oriented JSON instead of dumping raw backend output
- keeps debug artifacts opt-in
- warns clearly when `command-line-tools` or `codelinter` are unavailable

## Install

```bash
pip install hmos-precheck
```

After install, `hmos-precheck` is available directly from `PATH` through the
`project.scripts` entry point.

## Quick start

```bash
hmos-precheck doctor --project-root /path/to/project
hmos-precheck init --scope user --commandline-tools /abs/path/to/command-line-tools
hmos-precheck run --project-root /path/to/project --output-dir /tmp/hmos-out
```

Commands:

- `hmos-precheck run`
- `hmos-precheck doctor`
- `hmos-precheck init`

## Config

User config locations:

- Linux: `~/.config/hmos-precheck/config.json`
- macOS: `~/Library/Application Support/hmos-precheck/config.json`
- Windows: `%APPDATA%\\hmos-precheck\\config.json`

Project config location:

- repository root: `.hmos-precheck.json`

Resolution order:

1. `--commandline-tools`
2. project config: `.hmos-precheck.json`
3. user config: platform-specific `config.json`
4. `lab_root/config/projects.local.json`
5. environment variable: `HARMONYOS_COMMANDLINE_TOOLS`
6. built-in auto-detect locations

Example config:

```json
{
  "toolchain": {
    "commandline_tools": "/path/to/command-line-tools"
  },
  "run": {
    "profiles": ["arkts-diff", "codelinter-diff"]
  }
}
```

## Profiles

- default: `arkts-diff`, `codelinter-diff`
- supported: `arkts-diff`, `codelinter-diff`

`codelinter-diff` runs the SDK `command-line-tools/bin/codelinter` only for
changed `.ets` files, then keeps only diagnostics on changed lines. Only
`error` diagnostics are blocking; `warning` and `suggestion` diagnostics are
kept in artifacts and hidden from the repair payload. This keeps stdout as a
status signal plus compact repair summary, while filtered lint details stay in
`--output-dir`.

## Scan scope

By default, `run` checks the working tree diff against `HEAD`:

```bash
hmos-precheck run --project-root /path/to/project --output-dir /tmp/hmos-out
```

This is `diff-working-tree` mode. It includes changed tracked files and
untracked files that are not ignored by Git. Untracked temporary/generated paths
covered by `.gitignore` or Git excludes are skipped through `git ls-files
--others --exclude-standard`.

To compare two refs explicitly:

```bash
hmos-precheck run \
  --project-root /path/to/project \
  --output-dir /tmp/hmos-out \
  --base-ref origin/main \
  --head-ref HEAD
```

## Output

- `run` prints compact JSON intended for repair loops
- `doctor` prints detailed environment and toolchain discovery state
- `--output-dir` always receives run artifacts
- `hmos-precheck-result.json` contains the reduced repair payload
- `hmos-precheck-summary.md` contains the human-readable summary
- `hmos-precheck-debug.json` is written only when `--debug-artifact` is passed

## Tooling Gaps

- ArkTS-dependent checks degrade gracefully instead of crashing
- CodeLinter timeouts degrade to `not_checked` instead of failing the run
- `doctor` explains what is missing and how to configure it

## Release check

```bash
python3 -m pylint src tests
python3 -m pytest -q
python3 -m build
```
