@buaa_smat/hometrans 0.1.0 → 0.1.2

package/skills/hmos-resources-convert/references/dependency-analysis-rules.md

@@ -0,0 +1,388 @@
+# Android Resource Dependency Analysis Rules
+
+This document defines how to extract, track, and resolve inter-resource dependencies during Android-to-HarmonyOS resource conversion. Dependency analysis runs regardless of resource source — whether from a decompiled APK (complete resource set) or from the project's source `res/` directory (potentially missing library resources). When working from source `res/`, more references will be unresolvable, but the analysis is still essential to identify exactly what's missing and why. It also provides the evidence used to infer screen ownership, source ownership, and review-oriented function descriptions for the markdown written to `resource_mapping_path`.
+
+## Table of Contents
+1. [Resource Reference Patterns](#resource-reference-patterns)
+2. [Building the Resource Value Lookup Table](#building-the-resource-value-lookup-table)
+3. [Resolving References to True Values](#resolving-references-to-true-values)
+4. [Where to Scan for Dependencies](#where-to-scan-for-dependencies)
+5. [Dependency Verification](#dependency-verification)
+6. [Handling Missing Library Resources](#handling-missing-library-resources)
+
+---
+
+## Resource Reference Patterns
+
+Android resources reference each other using `@type/name` syntax. Extract these references from XML attribute values and text content.
+
+### Reference Regex Pattern
+
+Use the following pattern to extract resource references from any XML content:
+
+```
+@(color|drawable|mipmap|string|dimen|integer|bool|array|style|attr|id|layout|menu|anim|animator|raw|font|xml|plurals)/([a-zA-Z_][a-zA-Z0-9_]*)
+```
+
+This captures:
+- Group 1: resource type (`color`, `drawable`, etc.)
+- Group 2: resource name
+
+### System Resource References
+
+References prefixed with `@android:` (e.g., `@android:color/black`, `@android:drawable/ic_menu_close`) are Android framework resources provided by the OS. These resources do NOT exist in HarmonyOS and MUST be resolved to concrete values during conversion — they cannot be left as-is in the output.
+
+**Resolution rules for system resources:**
+- `@android:color/*` — resolve using the built-in Android system color lookup table (defined in SKILL.md Step 5.2). NEVER leave `@android:color/*` references in the converted output. If a color is not in the lookup table, use the decompiled APK's framework resources or fall back to `#ff000000` with a warning.
+- `@android:dimen/*` — resolve using the built-in Android system dimension lookup table (defined in SKILL.md Step 5.2). Fall back to `0vp` with a warning if not found.
+- `@android:string/*` — resolve to the known English string value if available, otherwise use `""` with a warning.
+- `@android:integer/*` — resolve to the known value if available, otherwise use `0` with a warning.
+- `@android:drawable/*` — these are Android framework drawables (icons, backgrounds). Log as "system drawable — requires manual replacement" in the report. If converting from a decompiled APK, extract and convert the drawable. Otherwise, create a placeholder SVG.
+
+In the conversion report, list all resolved system resource references in a dedicated section so the developer can verify the resolved values are correct.
+
+### Theme Attribute References
+
+References using `?attr/name` or `?android:attr/name` are theme attribute references resolved at runtime. These **cannot** be statically resolved — they depend on which theme is applied at runtime. Log them as "unresolvable theme attribute" and keep the reference as-is in the converted output.
+
+### Reference Locations in XML
+
+Resource references can appear in several places within Android XML files:
+
+**1. XML attribute values:**
+```xml
+<background android:drawable="@color/md_amber_700" />
+<TextView android:text="@string/hello" android:textColor="@color/primary" />
+<ImageView android:src="@drawable/icon" />
+```
+
+**2. Style/theme item values:**
+```xml
+<style name="AppTheme">
+    <item name="colorPrimary">@color/primary</item>
+    <item name="android:windowBackground">@drawable/bg_window</item>
+</style>
+```
+
+**3. Color state list references:**
+```xml
+<selector>
+    <item android:color="@color/pressed_color" android:state_pressed="true" />
+    <item android:color="@color/default_color" />
+</selector>
+```
+
+**4. Drawable XML references:**
+```xml
+<layer-list>
+    <item android:drawable="@drawable/bg_layer" />
+</layer-list>
+
+<adaptive-icon>
+    <background android:drawable="@color/ic_bg" />
+    <foreground android:drawable="@mipmap/ic_fg" />
+</adaptive-icon>
+```
+
+**5. Values XML cross-references (these are the primary targets for resolution):**
+```xml
+<!-- colors.xml -->
+<color name="primary_light">@color/primary</color>
+
+<!-- dimens.xml -->
+<color name="margin_double">@dimen/margin_base</color>
+```
+
+## Screen and Source Attribution Support
+
+Use dependency analysis not only to resolve resources, but also to collect evidence for the mapping markdown.
+
+### Screen attribution evidence sources
+
+Collect evidence from:
+- Activities
+- Fragments
+- Compose / UI page files
+- Navigation graphs
+- Layout XML files referenced by Activities or Fragments
+- Menu XML files referenced by screens
+- Direct `R.type.name` references in code
+
+### Screen attribution rules
+
+- If a screen directly references a resource, attribute the resource to that screen.
+- If a screen references a layout and the layout references additional resources, attribute those resources to that screen.
+- If a shared component is referenced by multiple screens, record all known screens or use `Common`.
+- For launcher icons, round icons, adaptive icons, app name, and app-wide theme resources, use `Launcher` or `Global` as defined by `references/resource-mapping-rules.md`.
+- If evidence is insufficient, use `Unknown`.
+
+### Source attribution evidence sources
+
+Collect evidence from:
+- Actual source path (`app/src/...`, local module `src/...`)
+- Decompiled APK presence without a matching source resource
+- Resource naming prefixes such as `abc_*`, `mtrl_*`, `design_*`, `material_*`
+- Declared Gradle dependencies
+- Android framework reference prefix `@android:`
+- Runtime URL / remote-loading code patterns
+
+### Function-description evidence sources
+
+Collect evidence from:
+- resource name semantics
+- XML root type (`vector`, `shape`, `selector`, `layer-list`, `adaptive-icon`)
+- usage site labels or surrounding code context
+- manifest usage (`android:icon`, `android:roundIcon`, etc.)
+
+Do not overstate certainty. If the conclusion is inferred, retain that explanation in the eventual mapping-row notes.
+
+---
+
+
+Before resolving references, build a complete lookup table from the resource source directory (either decompiled `res/` or source `res/`). When using the decompiled APK, this table will be comprehensive. When using source `res/`, it will only contain app-defined resources — library resources will be absent, and references to them will be flagged during verification.
+
+### Value Resources
+
+Parse all `values*/*.xml` files and build mappings:
+
+```
+colors:
+  "primary" → "#FF6200EE"
+  "primary_light" → "@color/primary"     # reference chain — will be resolved
+  "md_blue_500" → "#2196F3"
+
+dimens:
+  "margin_base" → "16dp"
+  "margin_double" → "@dimen/margin_base"  # reference chain
+
+strings:
+  "app_name" → "My App"
+  "greeting" → "Hello, %1$s!"
+
+integers:
+  "max_items" → "10"
+
+bools:
+  "is_tablet" → "false"
+```
+
+Include ALL qualifier variants (e.g., `values/colors.xml`, `values-night/colors.xml`, `values-ar/colors.xml`). Each qualifier variant gets its own entry in the lookup table.
+
+### File Resources
+
+Record all drawable and mipmap files:
+
+```
+drawables:
+  "icon" → "drawable/icon.png"
+  "bg_card" → "drawable/bg_card.xml" (shape)
+  "ic_arrow" → "drawable/ic_arrow.xml" (vector)
+
+mipmaps:
+  "ic_launcher" → "mipmap-anydpi-v26/ic_launcher.xml" (adaptive-icon)
+  "ic_launcher_foreground" → "mipmap-xxxhdpi/ic_launcher_foreground.png"
+```
+
+---
+
+## Resolving References to True Values
+
+The key step: walk through all resource values and replace references with actual concrete values.
+
+### Resolution Algorithm
+
+```
+function resolve(type, name, qualifier, depth=0):
+    if depth > 5: return UNRESOLVABLE  # prevent infinite loops
+    value = lookup_table[qualifier][type][name]
+    if value is a concrete value (hex color, number, string literal):
+        return value
+    if value matches @type/other_name:
+        return resolve(type, other_name, qualifier, depth+1)
+    if value matches ?attr/name:
+        return UNRESOLVABLE  # theme attribute, cannot resolve statically
+    return value
+```
+
+### What Gets Resolved
+
+**Value-to-value references** (primary targets):
+- `@color/name` → resolved hex color (e.g., `@color/primary` → `#FF6200EE`)
+- `@dimen/name` → resolved dimension value (e.g., `@dimen/margin_base` → `16dp`)
+- `@string/name` → resolved string value
+- `@integer/name` → resolved integer value
+- `@bool/name` → resolved boolean value
+
+**File references** (kept as HarmonyOS references, not resolved to values):
+- `@drawable/name` → `$media:name` (the file itself is converted separately)
+- `@mipmap/name` → `$media:name`
+
+**Unresolvable references** (logged but kept as-is):
+- `?attr/name` — theme attributes depend on runtime theme
+- `@style/name` — styles have no HarmonyOS equivalent
+
+**System resources** (resolved to concrete values, NOT kept as references):
+- `@android:color/name` — resolved via built-in lookup table to hex values
+- `@android:dimen/name` — resolved via built-in lookup table
+- `@android:string/name` — resolved to known string values
+- `@android:drawable/name` — extracted from APK or replaced with placeholder
+
+### Resolution During Conversion
+
+Resolution happens at conversion time, not as a separate pass. When converting a value from Android XML to HarmonyOS JSON:
+
+1. Parse the XML value
+2. If it's a concrete value (hex color, number, string), convert directly using format rules
+3. If it's a resource reference (`@type/name`):
+   a. Look up in the lookup table
+   b. Follow the chain to the concrete value
+   c. Convert the concrete value using format rules
+   d. Use the resolved concrete value in the HarmonyOS JSON output
+4. If the reference can't be resolved, use HarmonyOS reference syntax (`$color:name`, `$float:name`, etc.) and log it
+
+### Example: Full Resolution Chain
+
+Android `values/colors.xml`:
+```xml
+<color name="app_background">@color/surface_color</color>
+<color name="surface_color">@color/md_grey_50</color>
+<color name="md_grey_50">#FAFAFA</color>
+```
+
+Resolution:
+- `app_background` → `@color/surface_color` → `@color/md_grey_50` → `#FAFAFA`
+
+HarmonyOS `color.json` output:
+```json
+{
+  "color": [
+    {"name": "app_background", "value": "#ffFAFAFA"},
+    {"name": "surface_color", "value": "#ffFAFAFA"},
+    {"name": "md_grey_50", "value": "#ffFAFAFA"}
+  ]
+}
+```
+
+All three resolve to the same concrete value. The `#ffFAFAFA` format is after applying the `#RRGGBB` → `#ffRRGGBB` color format conversion.
+
+---
+
+## Where to Scan for Dependencies
+
+Scan ALL resource files from the resource source directory for dependencies, organized by priority:
+
+### High Priority (converted resources — broken dependencies cause direct errors)
+
+| File Type | Typical Location | Why It Matters |
+|---|---|---|
+| Adaptive icon XML | `mipmap-anydpi-v26/*.xml` | References colors, drawables, mipmaps for icon layers |
+| Vector drawables | `drawable/*.xml` (root: `<vector>`) | May reference colors via theme attrs |
+| Shape drawables | `drawable/*.xml` (root: `<shape>`) | May reference colors, dimens |
+| Layer-list drawables | `drawable/*.xml` (root: `<layer-list>`) | References other drawables |
+| Selector drawables | `drawable/*.xml` (root: `<selector>`) | References other drawables for states |
+| Color state lists | `color/*.xml` | References other colors |
+| Values XML | `values*/*.xml` | Cross-references between value types |
+
+### Required — Layout and Menu (not converted, but dependencies must be verified)
+
+Layout and menu files are **not** converted to HarmonyOS (they use ArkUI instead), but the resources they reference — strings, colors, drawables, dimensions — **must** be present in the converted output so the developer has everything needed when rebuilding the UI.
+
+| File Type | Typical Location | Why It Matters |
+|---|---|---|
+| Layout XML | `layout*/*.xml` | References strings, colors, drawables, dimens used by every UI component |
+| Menu XML | `menu/*.xml` | References strings and drawables for action bar / navigation items |
+
+### Skip (no meaningful dependencies)
+
+- Raw files (`raw/`)
+- Font files (`font/`) — unless font XML family definitions reference other fonts
+- Image files (PNG, JPG, WEBP, etc.) — binary files, no references
+
+---
+
+## Dependency Verification
+
+After conversion with reference resolution, verify that the output is self-consistent:
+
+### Check by Resource Type
+
+| Dependency Type | Where to Check in HarmonyOS Output |
+|---|---|
+| `@color/name` | Should be resolved to hex in `*/element/color.json`. If not resolved, check `name` exists. |
+| `@drawable/name` | Look for `name.*` (any extension: .png, .svg, .jpg, etc.) in `*/media/` |
+| `@mipmap/name` | Same as drawable — mipmaps go to `media/` in HarmonyOS |
+| `@string/name` | Should be resolved to literal in `*/element/string.json`. If not resolved, check `name` exists. |
+| `@dimen/name` | Should be resolved to value in `*/element/float.json`. If not resolved, check `name` exists. |
+| `@integer/name` | Look for `name` in `*/element/integer.json` |
+| `@bool/name` | Look for `name` in `*/element/boolean.json` |
+| `@array/name` | Look for `name` in `*/element/strarray.json` or `*/element/intarray.json` |
+| `@plurals/name` | Look for `name` in `*/element/plural.json` |
+| `@style/name` | Mark as "unmappable type" (styles have no HarmonyOS equivalent) |
+| `@attr/name` | Mark as "unmappable type" |
+| `@layout/name` | Mark as "not applicable" (layouts aren't converted) |
+| `@id/name` | Mark as "not applicable" (IDs are code-level concerns) |
+
+### Qualifier Coverage Check
+
+When a dependency is satisfied, also verify qualifier coverage. If the dependent resource exists in multiple qualifier directories (e.g., `base`, `dark`, `ldpi`), the dependency should ideally exist in matching qualifier directories. Flag cases where a dependency exists in `base` but the dependent resource also has `dark` or density-qualified variants — the dependency may need those variants too.
+
+---
+
+## Handling Missing Library Resources
+
+When converting from source `res/` (because the APK build failed or no APK was available), library-provided resources will be absent from the lookup table. This section describes how to handle these gaps gracefully.
+
+### Identifying Library Resources
+
+Many common Android libraries define resources with recognizable naming patterns. Use these heuristics to correlate unsatisfied dependencies with likely library sources:
+
+| Library | Common Resource Prefixes |
+|---|---|
+| Material Components (`com.google.android.material`) | `material_*`, `design_*`, `mtrl_*`, `Widget.Material*`, `Theme.Material*` |
+| AndroidX AppCompat (`androidx.appcompat`) | `abc_*`, `Widget.AppCompat.*` |
+| AndroidX Core (`androidx.core`) | `notification_*`, `compat_*` |
+| AndroidX ConstraintLayout | `constraint_*` |
+| Google Play Services | `common_google_*` |
+
+### Extracting Library Dependencies from build.gradle
+
+Parse `build.gradle` or `build.gradle.kts` to identify declared library dependencies:
+
+```groovy
+// build.gradle
+dependencies {
+    implementation 'com.google.android.material:material:1.9.0'
+    implementation 'androidx.appcompat:appcompat:1.6.1'
+    implementation 'androidx.core:core-ktx:1.12.0'
+}
+```
+
+Extract the group:artifact for each dependency. In the conversion report, list these libraries with their likely resource prefixes so the developer knows which libraries contribute which missing resources.
+
+### Resolution Behavior for Missing Resources
+
+When a reference cannot be resolved because the target resource is not in the lookup table:
+
+1. **Apply a type-appropriate fallback value** to ensure the output compiles without errors:
+   - `$color:name` → `#ff000000` (black)
+   - `$float:name` → `0vp`
+   - `$string:name` → `""`
+   - `$integer:name` → `0`
+   - `$boolean:name` → `false`
+2. **Log it as an unsatisfied dependency** with:
+   - The original reference (`@color/design_default_color_primary`)
+   - The fallback value applied (`#ff000000`)
+   - The source file where it was found
+   - The likely library source (if identifiable from naming patterns)
+   - The reason: "Library resource not available in source res/ — fallback applied"
+3. **Why fallback instead of keeping the reference**: Keeping `$color:name` references in the output causes HarmonyOS compilation errors. Applying a safe default ensures the project compiles and the developer can identify and fix the fallback values by searching for the logged warnings. The conversion report provides a complete list of all fallbacks applied.
+4. **When converting from a decompiled APK**: unresolved references should be very rare (the APK contains all merged resources). If they occur, log them as errors rather than warnings — they indicate a bug in the resolution logic.
+
+### Categorizing Unresolved References
+
+In the report, separate unresolved references into categories:
+
+1. **Missing library resources** — references to resources that likely come from declared library dependencies. These are expected when converting from source `res/`.
+2. **Theme attributes** (`?attr/name`) — cannot be statically resolved regardless of resource source.
+3. **System resources** (`@android:type/name`) — Android framework resources that MUST be resolved to concrete values using the built-in lookup tables. If resolution fails, use a type-appropriate default (colors → `#ff000000`, dimens → `0vp`, integers → `0`, strings → `""`) and log a warning. System resource references must NEVER appear in the final converted output.
+4. **Truly missing** — references that don't match any known library pattern and aren't in the lookup table. These may indicate a project misconfiguration or an undeclared dependency.