hmos-precheck 0.1.0

LLM-first low-noise Build@1 guard for HarmonyOS and ArkTS repos.

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

pip install hmos-precheck

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

Quick start

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:

{
  "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:

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:

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

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