dexllm 0.8.2__tar.gz

dexllm-0.8.2/.claude/dad-reminder.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Pre-edit hook for DAD-aligned C++ sources.
+# Reads tool_input JSON from stdin (Claude Code hook protocol).
+# Emits a system reminder enforcing DAD-reference development when the target
+# file is under vendor/dexkit_core/Core/, native/binding/, native/dad_cpp/,
+# or native/core_ext/.
+#
+# Removed subsystems (2026-05-26 audit, do NOT reintroduce):
+#   - Legacy expr-tree pipeline (Phase 2a/2b/3/4/5/6/8e)
+#   - L6_NO_EXPR_TREE / L6_LEGACY_MODE / L6_SSA_MODE env flags
+#   - PostInlineSingleUse / PostInlineShortExitTargets / PostStructureForwardGotos
+#   - PostEliminateDeadWrites / PostCollapseEmptyBlocks / PostSuppressUnusedLabels
+#   - PostSSARename / PostSuppressOrphanGotos (Phase 22)
+#   - All text-based regex post-passes on emit output
+# Never block the tool call: any failure (malformed JSON, missing jq, parse
+# error) should silently exit 0 so the user's edit proceeds. The reminder is
+# advisory, not enforced.
+set -u
+
+# Local checkout of androguard's DAD reference source. Override per-machine:
+#   export DAD_REF=/path/to/androguard-master/androguard/decompiler
+DAD_REF="${DAD_REF:-$HOME/androguard/androguard/decompiler}"
+
+path="$(jq -r '.tool_input.file_path // empty' 2>/dev/null || true)"
+if [[ -z "$path" ]]; then
+    exit 0
+fi
+if ! [[ "$path" =~ /vendor/dexkit_core/Core/.*\.(cpp|cc|h|hpp)$ ]] && \
+   ! [[ "$path" =~ /native/binding/.*\.(cpp|cc|h|hpp)$ ]] && \
+   ! [[ "$path" =~ /native/dad_cpp/.*\.(cpp|cc|h|hpp)$ ]] && \
+   ! [[ "$path" =~ /native/core_ext/.*\.(cpp|cc|h|hpp)$ ]]; then
+    exit 0
+fi
+
+cat <<MSG
+🔬 DAD-aligned source. Before editing this file:
+
+  1. Identify the corresponding DAD algorithm in androguard:
+     ${DAD_REF}/
+       basic_blocks.py | control_flow.py | dast.py | dataflow.py
+       decompile.py    | graph.py        | instruction.py | node.py
+       opcode_ins.py   | util.py         | writer.py
+
+  2. If your change has NO DAD analogue, it is a band-aid. Do not add
+     ad-hoc text/regex post-passes, opportunistic pattern matchers, or
+     heuristic structural detection. Discuss with the user first.
+
+  3. Reference the DAD file:lineno in the code comment AND commit message.
+     Example: "// DAD: control_flow.py:225 switch_struct"
+
+  4. Removed in 2026-05-26 audit — DO NOT REINTRODUCE:
+       - Legacy expr-tree pipeline (Phase 2a/2b/3/4/5/6/8e)
+       - L6_NO_EXPR_TREE / L6_LEGACY_MODE / L6_SSA_MODE flags
+       - Post* text regex passes (Inline*, *ForwardGotos, *DeadWrites,
+         CollapseEmptyBlocks, SuppressUnusedLabels, SSARename,
+         SuppressOrphanGotos (Phase 22))
+
+  5. After C++ changes, run /dexkit-build (ninja + pip install -e) then
+     /dexkit-sweep. Aggregate counts must not regress.
+MSG

dexllm-0.8.2/.claude/docs-precommit-check.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# PreToolUse(Bash) gate — runs before every Bash tool call.
+#
+# Purpose: before `git commit` / `git push`, force a review of the project's
+# docs .md files for drift against the change (and an update of any that are
+# now inaccurate) in the same commit. Docs drift silently — perf numbers, API
+# names, file paths, counts, install/build steps — so this makes the doc pass
+# a conscious step at publish time.
+#
+# The LLM does the actual review; this hook only ensures it happens. Once the
+# docs have been reviewed (and any drift fixed), bypass the gate by prefixing
+# the SAME command with `DOCS_CHECKED=1`, e.g.:
+#     DOCS_CHECKED=1 git commit -m "..."
+#     DOCS_CHECKED=1 git push origin master
+#
+# Non-git Bash, and git reads (status/log/diff/add/...), pass through untouched.
+set -u
+
+cmd="$(jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+[[ -z "$cmd" ]] && exit 0
+
+# Only gate git commit / git push.
+grep -qE 'git[^&|;]*\b(commit|push)\b' <<<"$cmd" || exit 0
+
+# Already reviewed this turn → allow.
+grep -qE 'DOCS_CHECKED=1|#[[:space:]]*docs-checked' <<<"$cmd" && exit 0
+
+root="${CLAUDE_PROJECT_DIR:-.}"
+docs="$(cd "$root" 2>/dev/null && ls README.md CLAUDE.md docs/*.md 2>/dev/null)"
+
+{
+    echo "📝 Docs gate — before committing/pushing, review these for drift against"
+    echo "   this change and update any that are now inaccurate (API names, file"
+    echo "   paths, perf numbers, counts, behavior, install/build steps) IN THIS"
+    echo "   COMMIT:"
+    if [[ -n "$docs" ]]; then
+        echo "$docs" | sed 's/^/       - /'
+    fi
+    echo "   Then re-run the SAME command prefixed with DOCS_CHECKED=1, e.g.:"
+    echo "       DOCS_CHECKED=1 git commit -m \"...\""
+    echo "   If every doc already matches the new state, just add the prefix."
+} >&2
+exit 2

dexllm-0.8.2/.claude/py-quality.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# PostToolUse hook: enforce the project's Python standards on every edit to a
+# package source file (PEP 8 / PEP 257 / PEP 484 via Black, Ruff, mypy).
+#
+# Behaviour:
+#   1. Auto-applies Black + `ruff check --fix` in place (formatting + safe fixes).
+#   2. Reports any REMAINING Ruff violations and mypy errors back to Claude
+#      (exit 2 surfaces stderr as actionable feedback). Clean → silent exit 0.
+#
+# Scoped to src/dexllm/**.py — the typed public package. Other dirs
+# (examples/bench/tests) are intentionally exempt (see pyproject per-file
+# ignores; mypy is configured for the package only).
+
+f="$(jq -r '.tool_input.file_path // empty')"
+[ -z "$f" ] && exit 0
+case "$f" in
+  */src/dexllm/*.py) ;;
+  *) exit 0 ;;
+esac
+[ -f "$f" ] || exit 0
+
+cd "${CLAUDE_PROJECT_DIR:-.}" || exit 0
+
+# 1. Auto-format + auto-fix in place (these mutate the file).
+black -q "$f" 2>/dev/null || true
+ruff check --fix -q "$f" 2>/dev/null || true
+
+# 2. Collect what still needs a human/Claude decision.
+issues=""
+ruff_left="$(ruff check "$f" 2>&1)" || issues+="$ruff_left"$'\n'
+mypy_out="$(mypy 2>&1)" || true
+if echo "$mypy_out" | grep -q "error:"; then
+  issues+="$mypy_out"$'\n'
+fi
+
+if [ -n "${issues//[$' \t\n']/}" ]; then
+  {
+    echo "⚠ Python standards: Black + Ruff auto-fixes applied to $f."
+    echo "   Remaining issues to fix (PEP 8 / PEP 257 / PEP 484):"
+    echo "$issues"
+  } >&2
+  exit 2
+fi
+exit 0

dexllm-0.8.2/.claude/review-precommit-check.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# PreToolUse(Bash) gate — runs before every Bash tool call.
+#
+# Purpose: after any FIX (a change to production source), force an ADVERSARIAL
+# CODE REVIEW before the commit/push lands. A decompiler type/dataflow change can
+# be subtly wrong in a way tests don't catch; the project's practice is to spawn
+# independent reviewer agents on the diff, triage their findings, fix the real
+# ones, and re-verify (a/b before-after + parity + 0-crash sweep) BEFORE
+# committing. This gate makes that a mandatory, conscious step at publish time.
+#
+# What "adversarial review" means here (do ALL of it, then commit):
+#   0. HACK SELF-CHECK (root-cause, not output masking). Before reviewing, ask:
+#      does this fix address the ROOT of the defect, or does it mask a symptom at
+#      the output/late layer? A change that suppresses/rewrites Writer or dast
+#      OUTPUT to hide a defect whose true origin is the IR builder / dataflow /
+#      control-flow (opcode_ins, instruction, dataflow, graph, control_flow) is a
+#      HACK — even when the emitted text looks correct (the AST/other consumers
+#      still carry the defect). Precedent: the v0.1.12 void-invoke "fix" masked in
+#      Writer::visit_assign, left `this = voidcall` in the AST, and was REWRITTEN
+#      at the IR builder (the range invoke handlers). If this is a hack, DO NOT
+#      commit — RECONSIDER and redo it at the layer where the defect originates
+#      (CLAUDE.md: "structural defects must be fixed at the IR level, not in Writer
+#      output"). Only genuine beyond-DAD emit divergences (return-literal, catch-
+#      clamp, <clinit> static{}) legitimately live in the Writer; a defect with an
+#      earlier structural origin does not.
+#   1. Spawn ≥2 INDEPENDENT reviewer agents on the diff — e.g. the Agent tool with
+#      compound-engineering:ce-adversarial-reviewer + ce-correctness-reviewer, or
+#      invoke the `code-review` skill. Each must try to CONSTRUCT a breaking input,
+#      not just pattern-match.
+#   2. Triage every finding (CONFIRMED / PLAUSIBLE / REFUTED). Fix the real ones.
+#   3. Re-verify: a/b (fix on vs off) shows 0 regression on the relevant axes,
+#      parity 28/28, sweep 0-crash. Remove any temporary a/b env-gate.
+#   4. THEN re-run the SAME commit/push command prefixed with REVIEWED=1, e.g.:
+#          REVIEWED=1 git commit -m "..."
+#      (Combine with the docs gate when both apply: DOCS_CHECKED=1 REVIEWED=1 …)
+#
+# Only gates commits/pushes whose change touches PRODUCTION source (native/**,
+# vendor/dexkit_core/Core/**, src/dexllm/**). Docs-only / test-only / config-only
+# commits, non-git Bash, and git reads pass through untouched.
+set -u
+
+cmd="$(jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+[[ -z "$cmd" ]] && exit 0
+
+# Only gate git commit / git push.
+grep -qE 'git[^&|;]*\b(commit|push)\b' <<<"$cmd" || exit 0
+
+# Already reviewed this turn → allow.
+grep -qE 'REVIEWED=1|#[[:space:]]*reviewed' <<<"$cmd" && exit 0
+
+root="${CLAUDE_PROJECT_DIR:-.}"
+cd "$root" 2>/dev/null || exit 0
+
+# Collect the files this operation would carry. A COMMIT carries only its own
+# change (staged + unstaged-tracked, covering `git commit -a`); a PUSH carries
+# every commit ahead of upstream. Keeping these separate means a config/docs-only
+# commit is not blocked just because earlier (already-reviewed) code commits are
+# still unpushed — while a push still re-confirms the whole set.
+if grep -qE 'git[^&|;]*\bpush\b' <<<"$cmd"; then
+    up="$(git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' 2>/dev/null || true)"
+    changed="$([[ -n "$up" ]] && git diff --name-only "$up"...HEAD 2>/dev/null)"
+else
+    changed="$( { git diff --cached --name-only 2>/dev/null
+                  git diff --name-only 2>/dev/null; } | sort -u )"
+fi
+
+# Does the change touch PRODUCTION source (a "fix")? If not, pass through.
+grep -qE '^(native/|vendor/dexkit_core/Core/|src/dexllm/).*\.(cpp|cc|h|hpp|py)$' \
+    <<<"$changed" || exit 0
+
+{
+    echo "🔬 Adversarial-review gate — this commit/push changes production source"
+    echo "   (a fix). Before it lands, run an ADVERSARIAL CODE REVIEW and address"
+    echo "   the findings:"
+    echo "     0. HACK SELF-CHECK (root-cause, not output masking): does this fix"
+    echo "        the ROOT of the defect, or mask a symptom in Writer/dast OUTPUT"
+    echo "        while the true origin is the IR builder / dataflow / control-flow?"
+    echo "        Output-layer suppression that hides an earlier structural defect"
+    echo "        (AST still carries it) is a HACK — RECONSIDER and redo it at the"
+    echo "        originating layer (cf. v0.1.12 void-invoke: Writer-hack → IR fix)."
+    echo "        Only genuine beyond-DAD emit divergences belong in the Writer."
+    echo "     1. Spawn ≥2 INDEPENDENT reviewers on the diff (Agent tool:"
+    echo "        compound-engineering:ce-adversarial-reviewer +"
+    echo "        ce-correctness-reviewer, or the code-review skill). Each must try"
+    echo "        to CONSTRUCT a breaking input, not just pattern-match."
+    echo "     2. Triage findings; fix the real ones."
+    echo "     3. Re-verify: a/b (fix on vs off) 0-regression + parity 28/28 +"
+    echo "        0-crash sweep; remove any temp a/b env-gate."
+    echo "   Then re-run the SAME command prefixed with REVIEWED=1, e.g.:"
+    echo "       REVIEWED=1 git commit -m \"...\""
+    echo "   (with the docs gate: DOCS_CHECKED=1 REVIEWED=1 git commit -m \"...\")"
+} >&2
+exit 2

dexllm-0.8.2/.claude/settings.json

@@ -0,0 +1,56 @@
+{
+  "availableModels": [
+    "opus",
+    "claude-fable-5"
+  ],
+  "permissions": {
+    "allow": [
+      "Bash(*)",
+      "WebFetch(domain:github.com)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/dad-reminder.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/docs-precommit-check.sh\"",
+            "statusMessage": "Docs gate (review docs/*.md before commit/push)"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/review-precommit-check.sh\"",
+            "statusMessage": "Adversarial-review gate (review a code fix before commit/push)"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_input.file_path // empty' | grep -qE '(/vendor/dexkit_core/Core/|/native/(binding|dad_cpp|core_ext)/).*\\.(cpp|cc|h|hpp)$' && echo '⚠ DexKit C++ source modified — run /dexkit-build before testing or sweeping. The currently-installed .so is now stale.' || true"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/py-quality.sh\"",
+            "statusMessage": "Enforcing Python standards (Black / Ruff / mypy)"
+          }
+        ]
+      }
+    ]
+  }
+}

dexllm-0.8.2/.claude/skills/dexkit-bench/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: dexkit-bench
+description: |
+  Head-to-head performance benchmark — androguard DAD (Python reference) vs DexKit-DAD (C++ port).
+  Measures wall-clock time per method on the same corpus, verifies parity of output where the
+  port is byte-identical to DAD. Use to validate that the C++ port preserves DAD semantics while
+  delivering the expected speedup.
+---
+
+## What this measures
+
+For a chosen APK, decompile a sample of N methods (default 500) on both implementations:
+
+| Metric | DexKit-DAD (C++) | androguard DAD (Python) |
+|---|---|---|
+| Total wall time | sum of `dk.decompile_method()` | sum of `DvMethod(m).process()` + `get_source()` |
+| Per-method mean | ms | ms |
+| Output match rate | byte-identical method count / N | — |
+| Empty rate | external-ref methods (both should agree) | same |
+
+A healthy result: DexKit ~50-200× faster, with high byte-identical match rate on non-external
+methods (mismatches are either DAD quirks already deferred in CLAUDE.md or genuine port bugs
+worth investigating via [/dexkit-diff](../dexkit-diff/SKILL.md)).
+
+## Execute
+
+```bash
+python << 'EOF'
+import sys, time, random
+sys.stdout.reconfigure(line_buffering=True)
+from loguru import logger; logger.remove()
+import dexllm
+from androguard.misc import AnalyzeAPK
+from androguard.decompiler.decompile import DvMethod
+
+APK = "test_apk/APK/com.example.android.tvleanback.apk"
+N = 500
+
+dk = dexllm.DexKit(APK)
+_a, _d_list, dx = AnalyzeAPK(APK)
+methods = [m for m in dx.get_methods() if not m.is_external() and m.get_method().get_code() is not None]
+random.seed(42); random.shuffle(methods); sample = methods[:N]
+print(f"Sampling {len(sample)} methods from {APK}", flush=True)
+
+def norm(s):
+    # androguard DAD emits standalone-method output with class-context 4-space
+    # indent; DexKit's decompile_method is true standalone (no indent).
+    # Strip leading whitespace per line so byte-match isn't dominated by indent.
+    return "\n".join(line.lstrip() for line in s.splitlines()) if s else ""
+
+# DexKit-DAD pass
+t0 = time.time(); dk_out = {}
+for m in sample:
+    em = m.get_method()
+    desc = f"{em.get_class_name()}->{em.get_name()}{em.get_descriptor()}"
+    try: dk_out[desc] = dk.decompile_method(desc)
+    except Exception as e: dk_out[desc] = f"// CRASH: {type(e).__name__}"
+dk_ms = (time.time() - t0) * 1000
+
+# androguard DAD pass
+t0 = time.time(); dad_out = {}
+for m in sample:
+    em = m.get_method()
+    desc = f"{em.get_class_name()}->{em.get_name()}{em.get_descriptor()}"
+    try:
+        dv = DvMethod(m); dv.process(); dad_out[desc] = dv.get_source()
+    except Exception as e: dad_out[desc] = f"// CRASH: {type(e).__name__}"
+dad_ms = (time.time() - t0) * 1000
+
+match = sum(1 for d in dk_out if norm(dk_out[d]) == norm(dad_out.get(d, "")))
+both_nonempty = sum(1 for d in dk_out if dk_out[d] and dad_out.get(d, ""))
+print(f"\n=== Bench result over {N} methods ===")
+print(f"  DexKit-DAD : {dk_ms:>8.1f} ms total ({dk_ms/N:.3f} ms/method)")
+print(f"  androguard : {dad_ms:>8.1f} ms total ({dad_ms/N:.3f} ms/method)")
+print(f"  speedup    : {dad_ms/max(dk_ms,0.001):.1f}x")
+print(f"  byte-match : {match}/{N} ({match/N*100:.1f}%), both-nonempty: {both_nonempty}")
+EOF
+```
+
+## Interpreting results
+
+- **Speedup < 10×**: investigate. The DAD port should be heavily faster — Python interpreter
+  + per-instance object overhead is the dominant cost in androguard DAD.
+- **Match rate < 80% on non-trivial methods**: investigate divergence with `/dexkit-diff` on
+  a sample of mismatches. Common legitimate causes (mismatches from DAD bugs we've fixed in
+  production — see CLAUDE.md "Upstream DAD bug fixes" section):
+  - `get_params_type` quirk (DAD: `IJ p0`, DexKit: `int p0, long p1`)
+  - `java/lang/*` char-set strip bug (DAD: `otation.Foo`, DexKit: `annotation.Foo` — fixed)
+- **Match rate ~90%**: port is healthy. The residual mismatch is dominated by `var_naming`
+  suffix off-by-N (semantic-equivalent) and other deep-IR categories — see CLAUDE.md
+  `project-deferred-decompiler-tasks`.
+
+## Caveats
+
+- androguard DAD crashes (RecursionError, AttributeError on ExternalMethod, etc.) — caught as
+  `// CRASH:` strings in the bench output. These count as legitimate divergence from DexKit
+  (which generally doesn't crash on the same input).
+- `random.seed(42)` keeps the sample deterministic across runs for diff-able output.
+- `AnalyzeAPK` load time (~3-5s for tvleanback) is NOT in the per-pass timing; both passes
+  reuse the loaded `dx` object.

dexllm-0.8.2/.claude/skills/dexkit-build/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: dexkit-build
+description: Rebuild the DexKit C++ core via ninja and reinstall the editable Python wheel. Run this every time any C++ source under vendor/dexkit_core/Core/, native/binding/, native/dad_cpp/, or native/core_ext/ is modified — the in-memory pip extension does NOT pick up rebuilt .so files automatically.
+---
+
+DexKit develops natively (C++ static lib + pybind11 module) and Python wraps it. Two directories are involved:
+
+- Build artifacts: `<repo>/build/<wheel_tag>` — scikit-build-core names this per platform/Python (e.g. `cp313-cp313-linux_x86_64` on Linux, `cp313-cp313-macosx_14_0_arm64` on macOS). Discover it; never hardcode the name.
+- Package root (for editable install): `<repo>` (the directory with `pyproject.toml`)
+
+A correct rebuild ALWAYS runs both steps in this order — running ninja from inside the build dir, then pip install from the package root. Skipping the second step leaves the installed extension stale.
+
+## Execute
+
+Run this single chained command (platform-agnostic — discovers the build dir by its `build.ninja`; if none exists yet, the `pip install` does a full configure+build):
+
+```bash
+R="$(git rev-parse --show-toplevel)" && B="$(find "$R/build" -maxdepth 2 -name build.ninja -exec dirname {} \; 2>/dev/null | head -1)" && { [ -n "$B" ] && cd "$B" && ninja 2>&1 | tail -5; } ; cd "$R" && pip install -e . --no-build-isolation 2>&1 | tail -3
+```
+
+Report success only when both `Linking CXX shared module _dexkit_core...so` and `Successfully installed dexllm-0.0.1` appear in output.
+
+## Common pitfalls
+
+- `pip install -e .` from the build directory FAILS with "does not appear to be a Python project" — always cd to the repo root (`git rev-parse --show-toplevel`) first.
+- If compilation fails, do not retry blindly — read the error and fix the C++ source. Do not work around by reverting changes unless the user asks.

dexllm-0.8.2/.claude/skills/dexkit-decompile/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: dexkit-decompile
+description: |
+  Decompile a single method (or class) via the DAD-aligned C++ pipeline and print the result.
+  Argument is a Dalvik method descriptor (e.g. `LX/00D9;->equals(Ljava/lang/Object;)Z`) or a
+  class descriptor (`LX/00D9;`), optionally followed by `from <apk_path>`.
+---
+
+## Usage
+
+```
+/dexkit-decompile <method-or-class-descriptor> [from <apk-path>]
+```
+
+If no APK is given, default to `com.example.android.tvleanback.apk` (~4135 classes, real-world
+Android support library code — good coverage of if/else, try-catch, switch, synchronized).
+
+## Execute
+
+Single method:
+```bash
+python << 'EOF'
+import dexllm
+APK = "<resolved_apk_path>"
+DESC = "<method_descriptor>"
+dk = dexllm.DexKit(APK)
+try:
+    src = dk.decompile_method(DESC)
+    print(src if src else "(empty — likely external method ref, no code in this dex)")
+except RuntimeError as e:
+    print(f"ERROR: {e}")
+EOF
+```
+
+Whole class:
+```bash
+python << 'EOF'
+import dexllm
+dk = dexllm.DexKit("<resolved_apk_path>")
+print(dk.decompile_class("<class_descriptor>"))
+EOF
+```
+
+## Notes
+
+- Descriptors with `$` for inner classes use Smali form (`LX/0F$Inner;`).
+- Method protos use `(args)Ret` Dalvik shape.
+- `<init>` and `<clinit>` are valid method names.
+- Shell escaping: `$` may need `\$` if passed through bash; prefer Python heredoc.
+- **External method refs** (entries in MethodIds without ClassData in this dex) return empty
+  output — DAD-equivalent behavior, not a bug.
+- Multi-dex APKs are fully supported; the descriptor is resolved across all dexes.

dexllm-0.8.2/.claude/skills/dexkit-diff/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: dexkit-diff
+description: |
+  Side-by-side parity diff between androguard DAD (Python reference) and DexKit-DAD (our C++ port)
+  for a given method descriptor. Use when investigating output divergence — confirms whether a
+  defect is a port bug or matches DAD's behavior (in which case it's DAD-faithful and out of scope).
+---
+
+## Usage
+
+```
+/dexkit-diff <method-descriptor> [from <apk-path>]
+```
+
+## When to use
+
+When `dk.decompile_method(desc)` produces output that looks wrong, the first question is
+"does DAD produce the same wrong output?" Three outcomes:
+
+1. **DAD matches DexKit (both wrong the same way)** — DAD bug we haven't tackled yet. Check
+   CLAUDE.md "Deferred DAD quirks" (bug-for-bug faithful by design) or consider promoting to
+   "Upstream DAD bug fixes" with a dual-track parity entry.
+2. **DAD wrong, DexKit correct** — we've already fixed it upstream-of-DAD. Look for a
+   `*DADFaithful` sibling in `util.cpp` etc.; the mismatch is intentional and counts as
+   improvement, not divergence.
+3. **DAD correct, DexKit wrong** — port bug. Use the diverging output region to narrow down
+   which pass introduced the regression.
+
+## Execute
+
+```bash
+DESC='<method_descriptor>'
+APK='<resolved_apk_path>'
+
+# DexKit-DAD output
+python << EOF > /tmp/dexkit.txt 2>&1
+from loguru import logger; logger.remove()
+import dexllm
+dk = dexllm.DexKit("$APK")
+print(dk.decompile_method("$DESC"))
+EOF
+
+# androguard DAD reference output
+python << EOF > /tmp/dad.txt 2>&1
+from loguru import logger; logger.remove()
+from androguard.misc import AnalyzeAPK
+from androguard.decompiler.decompile import DvMethod
+_a, _d, dx = AnalyzeAPK("$APK")
+cls, _, name, proto = "$DESC".replace('->', '|').replace('(', '|(', 1).split('|', 2)
+for m in dx.find_methods(classname=cls, methodname=name, descriptor=proto):
+    if not m.is_external():
+        dv = DvMethod(m); dv.process(); print(dv.get_source())
+EOF
+
+diff -u /tmp/dad.txt /tmp/dexkit.txt | head -80
+```
+
+## Interpreting results
+
+- **No diff**: byte-identical → port is DAD-faithful. Any "defect" must be addressed at
+  DAD's level (a DAD bug) — either deferred (add to CLAUDE.md "Deferred DAD quirks") or
+  fixed in production (add to "Upstream DAD bug fixes" with a `*DADFaithful` sibling +
+  dual-track parity test). Precedents: `GetType` (fixed), `ParseParamsType` (Writer-side
+  alternative to DAD's `GetParamsType`).
+- **Diff present, DexKit looks better**: we already fixed a DAD bug — confirm via
+  CLAUDE.md "Upstream DAD bug fixes" section. Not a regression.
+- **Diff present, DexKit looks wrong**: port bug. Use the diverging region to narrow down.
+  Common classes: `decompile.cpp` (pass ordering), `writer.cpp` (Java text emission),
+  `instruction.cpp` (IR semantics), `dataflow.cpp` (def-use / propagation), `control_flow.cpp`
+  (structuring).
+
+## Caveats
+
+- DAD's output may include surrogate-half MUTF-8 bytes that crash Python's `print()` on
+  strict-UTF-8 stdout. Pipe through `iconv -f UTF-8//IGNORE` if needed.
+- ExternalMethod refs: DAD's `DvMethod.__init__` crashes; our port returns empty. The
+  "no diff" check should skip external refs (the `is_external()` guard above does that).

dexllm-0.8.2/.claude/skills/dexkit-sweep/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: dexkit-sweep
+description: |
+  Full-APK regression sweep across every loadable APK in test_apk/APK/. Decompiles every class,
+  counts crashes/errors/empties, reports throughput. Use as the primary success gate for any
+  decompiler change — a green sweep means no class in the corpus crashes the C++ pipeline.
+---
+
+## What this measures
+
+For every method in every loadable APK:
+- **class_crash**: `decompile_class()` raised a Python exception (segfault, runtime_error, etc.)
+- **method_decompile_error / method_method_error**: output starts with `// DECOMPILE ERROR:` or
+  `// METHOD ERROR:` (caught in C++ via `try{...}catch(std::exception&)`)
+- **method_empty**: empty output — usually external method ref (no ClassData in this dex),
+  matches DAD's effective behavior
+- **method_success**: any other non-empty output
+
+The previous L6-era defect categories (orphan goto, brace imbalance, invalid_lhs,
+duplicate_return, self_assign) were text artifacts of the L6 output and are no longer relevant.
+The DAD pipeline produces correct Java by construction; defects manifest as either crashes,
+exceptions, or wrong-but-non-crashing output (which the sweep won't catch — use
+[/dexkit-diff](../dexkit-diff/SKILL.md) for that).
+
+## Execute
+
+```bash
+python /tmp/full_sweep.py
+```
+
+If `/tmp/full_sweep.py` is missing, recreate it. It must:
+- Glob every `*.apk` in `test_apk/APK/`
+- Skip APKs with `dexllm.identify(apk)["dex_count"] == 0` (resources-only) **before**
+  constructing `DexKit(apk)` — the constructor now raises on a container with no
+  `classes*.dex` (validated load), so probe with `identify()` first instead of
+  loading and checking `dex_count()`
+- For each APK, enumerate classes via `androguard.misc.AnalyzeAPK` (DexKit has no class
+  enumeration API)
+- Call `dk.decompile_class(class_descriptor)` for each class
+- Categorize each method block by marker (`// DECOMPILE ERROR`, `// METHOD ERROR`) or empty
+- For APKs >5MB, cap class processing at 200 to keep total time bounded; for true full
+  coverage on the cap'd APK, run a focused sweep instead (see below)
+- **`gc.collect()` between APKs** (mandatory). androguard's `AnalyzeAPK` returns a heavy
+  `dx`/`d_list` graph held by Python cyclic refs; without explicit GC the working set grows
+  monotonically and later APK iterations slow down (~30× slowdown observed at ~17 APKs on
+  this corpus, hang-like behavior visible to the user). The dropped refs free both the
+  androguard analysis and any DexKit-side caches scoped to the per-APK `DexKit` instance.
+
+## Focused full-coverage sweep (no cap)
+
+For one APK without the 200-class cap:
+```bash
+python << 'EOF'
+import sys, time; sys.stdout.reconfigure(line_buffering=True)
+from loguru import logger; logger.remove()
+import dexllm; from androguard.misc import AnalyzeAPK
+APK = "test_apk/APK/com.example.android.tvleanback.apk"
+dk = dexllm.DexKit(APK)
+_, d_list, _ = AnalyzeAPK(APK)
+classes = [c.get_name() for dex in d_list for c in dex.get_classes()]
+print(f"{len(classes)} classes", flush=True)
+crashes = 0; t = time.time()
+for c in classes:
+    try: dk.decompile_class(c)
+    except Exception as e:
+        crashes += 1
+        print(f"CRASH {c}: {type(e).__name__}: {str(e)[:80]}", flush=True)
+print(f"{crashes} crashes / {len(classes)} classes in {time.time()-t:.1f}s")
+EOF
+```
+
+## Comparing runs
+
+When investigating a category, save a baseline before your change:
+```bash
+python /tmp/full_sweep.py > /tmp/sweep_before.txt
+```
+
+Then patch + `/dexkit-build` + re-sweep, and diff the AGGREGATE block. Per-category deltas
+tell you whether the patch helped, regressed, or was neutral.
+
+## Performance reference
+
+- Workstation: Ryzen 9 9950X (16C/32T), 128GB DDR5 — single-process sequential.
+- Last reference run (2026-05-27): 22 APKs, 20,221 classes, 159,305 methods, **0 crashes**,
+  ~17,900 methods/sec.
+- Bottleneck is androguard `AnalyzeAPK` loading (per-APK), not DexKit decompilation.
+- If runtime > 30s on the full sweep, suspect a hang in one specific method — bisect by
+  enumerating classes and decompiling per-class until a target hangs.
+
+## Multi-process variant (legacy reference)
+
+The L6-era multi-process sweep used `ProcessPoolExecutor(max_workers=24)` with class-chunks
+of 200. Currently overkill — single-process sweep finishes in ~10s for the full corpus.
+If sweeping enormous external APK collections (1000+ APKs), revive the multi-process pattern.