adding CLAUDE.md

Author: nklapste

.gitignore

@@ -36,4 +36,5 @@ idea/
 
 # local
 .claude/
+CLAUDE.local.md
 dev/

CLAUDE.md

@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build Commands
+
+Gradle requires JDK 17+. Set `JAVA_HOME` to your JDK 17 installation before running any Gradle task.
+
+| Task | Command |
+|------|---------|
+| Build + test | `./gradlew build` |
+| Build + produce distributable jar | `./gradlew dist` |
+| Run tests only | `./gradlew test` |
+| Run a single test | `./gradlew test --tests "jadx.plugins.stringdecoder.JadxStringDecoderPluginTest.integrationTest"` |
+
+The distributable jar lands in `build/dist/`.
+
+## Architecture
+
+A JADX decompiler plugin that detects likely Base64-encoded string constants and byte array fields, adding inline comments with their decoded values. The plugin entry point is declared via Java SPI in `src/main/resources/META-INF/services/jadx.api.plugins.JadxPlugin`.
+
+### Plugin lifecycle
+
+```
+JadxStringDecoderPlugin.init()
+  → registers B64DeobfuscateOptions
+  → registers B64DeobfuscatePass  (method-body Base64 string detection)
+  → registers B64FieldInitPass    (field initializer Base64 detection)
+  → registers ByteArrayStringPass (byte[] field string detection)
+```
+
+All three passes are skipped when `enable` is false.
+
+### Pass overview
+
+**`B64DeobfuscatePass`** — runs `.after("SSATransform").before("ConstInlineVisitor")`
+
+Iterates every method's basic blocks looking for `ConstStringNode` instructions. On a likely-Base64 string it attaches a `CodeComment` to the instruction. `ConstInlineVisitor` later inlines the const into its consuming instruction and calls `inheritMetadata`, which propagates the comment. Code generation in `InsnGen`/`RegionGen` calls `CodeGenUtils.addCodeComments` to render it on the same line.
+
+Also detects when a string is a direct argument to a `Base64.decode`-like call (via `SSAVar.getUseList()`) and bypasses false-positive heuristics in that case — the call itself is strong evidence of intent.
+
+**`B64FieldInitPass`** — runs `.after("ExtractFieldInit")`
+
+Handles two field patterns:
+- *`FIELD_INIT_INSN`* — field set via `<clinit>` or constructor; `ExtractFieldInit` extracts the init expression. If the init is a direct `ConstStringNode`, detects normally. If it's a complex expression (e.g. `new String(Base64.decode("...", 0))`), walks the instruction arg tree recursively via `RegisterArg.getAssignInsn()` / `InsnWrapArg.getWrapInsn()` to find the embedded string. When the string is a direct arg to a `Base64.decode`-like `InvokeNode`, forces decode without heuristic checks.
+- *`CONSTANT_VALUE`* — `static final` field with a literal string value encoded in the class file; retrieved via `JadxAttrType.CONSTANT_VALUE` / `EncodedValue`.
+
+Comments are added via `field.addCodeComment()` which renders on a separate line above the field declaration (`FieldNode implements ICodeNode` → `startNewLine = true` in `CodeGenUtils`).
+
+**`ByteArrayStringPass`** — runs `.after("ExtractFieldInit")`
+
+Looks for `byte[]` fields initialised with a `FilledNewArrayNode` of all literal bytes. If the bytes decode as valid UTF-8 with sufficient printable characters, adds a `bytes: "..."` comment on the field.
+
+### Detection logic (`B64Detector`)
+
+`B64Detector.detect(String, B64DeobfuscateOptions)` applies a pipeline of filters (all thresholds configurable via options):
+
+1. Minimum encoded length (`minInputLength`, default 8)
+2. Require `=` padding suffix (`requirePadding`, default false)
+3. Skip identifier-like strings matching `^[A-Za-z][A-Za-z0-9]*$` (`skipIdentifiers`, default false)
+4. Charset validation — must match standard or URL-safe Base64 alphabet
+5. Attempt decode with `Base64.getDecoder()`, then `Base64.getUrlDecoder()`
+6. Strict UTF-8 decode (`CodingErrorAction.REPORT`)
+7. Minimum printable-ASCII ratio (`minPrintablePercent`, default 90%)
+8. Minimum alphanumeric ratio (`minAlphanumericPercent`, default 35%)
+9. Minimum decoded length (`minDecodedLength`, default 0 = disabled)
+10. Truncation (`maxCommentLength`, default 100; 0 = unlimited)
+
+`B64Detector.decodeForced(String, int)` skips steps 1–9 and uses `CodingErrorAction.REPLACE` instead of `REPORT`. Used when the string is an explicit arg to a `Base64.decode` call.
+
+### False-positive prevention
+
+The `<clinit>` / field-init skip: `B64DeobfuscatePass` collects all `CONSTANT_VALUE` field string literals in the class (lazily, on the first B64 hit) and skips any `ConstStringNode` whose value matches — those are handled by `B64FieldInitPass` to avoid double annotation.
+
+### Key JADX API types
+
+| Type | Notes |
+|------|-------|
+| `JadxDecompilePass` | Interface for decompile-phase passes; `visit(ClassNode)` returns `true` to enable method traversal |
+| `ConstStringNode` | `InsnNode` subtype for `CONST_STR`; use `.getString()` |
+| `InvokeNode` | `InsnNode` subtype for method calls; use `.getCallMth()` → `MethodInfo` |
+| `FilledNewArrayNode` | `InsnNode` subtype for `filled-new-array`; use `.getElemType()` and `.getArg(i)` |
+| `AType.CODE_COMMENTS` | `AttrList<CodeComment>` — add with `insn.addAttr(AType.CODE_COMMENTS, new CodeComment(text, CommentStyle.LINE))`. `InsnNode` does **not** extend `NotificationAttrNode`, so use `addAttr` directly |
+| `FieldNode.addCodeComment(text)` | Convenience method that renders a comment on a line above the field declaration |
+| `OrderedJadxPassInfo` | Supports `.before(name)` and `.after(name)`; names are JADX internal visitor class names, not `@JadxVisitor` name attributes |
+| `AType.FIELD_INIT_INSN` / `FieldInitInsnAttr` | Set by `ExtractFieldInit` on fields whose init is extracted from `<clinit>` or a constructor |
+| `JadxAttrType.CONSTANT_VALUE` / `EncodedValue` | Literal field value encoded in the class file; check `EncodedType.ENCODED_STRING` before casting |
+| `RegisterArg.getAssignInsn()` | Follows a register back to the instruction that assigned it (SSA form) |
+| `SSAVar.getUseList()` | All uses of an SSA register — used to find the instruction consuming a `ConstStringNode`'s result |
+
+### jadx-core dependency
+
+`jadx-core` is `compileOnly` — excluded from the output jar. The plugin jar is loaded into an existing JADX installation at runtime.