arkanalysis
v0.1.0
Published
Standalone ArkTS/HarmonyOS commit-context extractor: given a git commit, prints the changed source line ranges plus call-chain and referenced-resource context as JSON.
Maintainers
Readme
ArkAnalysis
Standalone ArkTS / HarmonyOS commit-context extractor.
Given a git commit in a HarmonyOS ArkTS project, it prints — as pure JSON on stdout — exactly the code a reviewer needs to look at for that commit:
- the changed source line ranges (1-based, inclusive),
- the call-chain context around them (callers/callees, up to 2 hops), and
- the referenced string/plural/strarray resource names.
It never prints file contents, so the caller reads only the ranges it needs — keeping review context small.
This was extracted from the HomeTrans
hmos-convert-pipeline skill into its own repository. It has no dependency on
HomeTrans; its only runtime deps are arkanalyzer
and simple-git.
Install
npm installNode.js >= 18 is required.
Usage
node bin/extract-context.mjs \
--project "<harmony_project_dir>" \
--commit "<commit_id>" \
[--mode default] \
[--ohos-sdk "<...>/default/openharmony/ets"] \
[--hms-sdk "<...>/default/hms/ets"]| Flag | Meaning |
|------|---------|
| --project | Absolute path to the HarmonyOS project root (contains the .git directory). Required. |
| --commit | The git commit to analyze — diffed against its first parent (<commit>^..<commit>). Required. |
| --mode | default builds the full call graph for call-chain context (default). |
| --ohos-sdk | Path to the OpenHarmony ETS SDK dir. Optional if resolvable (see below). |
| --hms-sdk | Path to the HMS ETS SDK dir. Optional if resolvable (see below). |
| -h, --help | Print usage. |
SDK path resolution
The OpenHarmony / HMS SDK ETS paths are resolved in this order (first non-empty wins):
--ohos-sdk/--hms-sdkCLI flags;OHOS_SDK_PATH/HMS_SDK_PATHenvironment variables;an optional config file —
~/.arkanalysis/config.json(native), then~/.hometrans/config.json(interop with HomeTrans), read as:{ "env": { "OHOS_SDK_PATH": "...", "HMS_SDK_PATH": "..." } }
At least one of the two SDK paths must resolve, or the tool exits with a descriptive error.
Output
A JSON array, one entry per affected file:
[
{ "path": "/abs/path/Foo.ets", "kind": "source", "ranges": [[10, 24], [80, 86]] },
{ "path": "/abs/.../string.json", "kind": "resource", "resourceNames": ["title", "ok"] }
]source—rangesare[start, end]pairs, 1-based and inclusive. Read only those lines (e.g. via an editor'soffset/limit).resource—resourceNameslists the referenced resource keys in thatstring.json/plural.json/strarray.json.
All diagnostics go to stderr; stdout is reserved for the JSON result.
Programmatic use
import { extractCommitContext } from 'arkanalysis';
const items = await extractCommitContext({
projectPath: '/abs/harmony/project',
commitId: 'HEAD',
mode: 'default',
// ohosSdkPath / hmsSdkPath optional — same resolution chain as the CLI
});Exit codes
0— success (JSON printed to stdout).1— bad arguments, missing SDK paths, or an analysis error (message on stderr).
