android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/analysis/source-facts/android.js

@@ -0,0 +1,1062 @@
+function resolvedClassName(name, packageName) {
+  if (!packageName || (name.includes(".") && !name.startsWith(".")))
+    return name;
+  if (name.startsWith(".")) return `${packageName}${name}`;
+  return `${packageName}.${name}`;
+}
+function manifestComponentType(component) {
+  switch (component.kind) {
+    case "fragment":
+      return "fragment";
+    case "app-widget":
+      return "widget";
+    case "receiver":
+      return "receiver";
+    case "activity":
+    case "activity-alias":
+      return "activity";
+  }
+}
+function simpleTag(tag) {
+  return tag.includes(".") ? tag.slice(tag.lastIndexOf(".") + 1) : tag;
+}
+function elementType(view) {
+  const name = simpleTag(view.tag).toLowerCase();
+  if (name.endsWith("edittextpreference")) return "text-input";
+  if (name.includes("switchpreference") || name.endsWith("checkboxpreference"))
+    return name.includes("switch") ? "switch" : "checkbox";
+  if (name.endsWith("listpreference") || name.endsWith("dropdownpreference"))
+    return "preference-list";
+  if (name.endsWith("preferencecategory")) return "preference-category";
+  if (name.endsWith("preferencescreen")) return "preference-screen";
+  if (name.endsWith("preference")) return "preference";
+  if (name === "edittext" || name.endsWith("textinputedittext")) {
+    return "text-input";
+  }
+  if (name === "imagebutton") return "icon-button";
+  if (name === "switch" || name === "switchcompat") return "switch";
+  if (name === "checkbox") return "checkbox";
+  if (name === "radiobutton") return "radio-button";
+  if (name === "togglebutton") return "toggle-button";
+  if (name === "textview" && view.actionable) return "clickable-text";
+  if (view.resourceType === "menu" && name === "item") return "menu-item";
+  return name.replace(/([a-z0-9])([A-Z])/gu, "$1-$2").toLowerCase();
+}
+function resolvedLabel(attribute) {
+  if (!attribute) return undefined;
+  if (attribute.resolved?.trim()) return attribute.resolved.trim();
+  return attribute.raw.startsWith("@") ? undefined : attribute.raw.trim();
+}
+function iconResource(reference) {
+  if (!reference) return undefined;
+  const owner = reference.packageName ? `${reference.packageName}.R` : "R";
+  return `${owner}.${reference.resourceType}.${reference.name}`;
+}
+function labelsByTarget(android) {
+  const result = new Map();
+  for (const label of android.views) {
+    if (!label.labelFor) continue;
+    const attribute = label.text ?? label.contentDescription;
+    const key = `${label.resourceType}/${label.resourceName}#${label.labelFor}`;
+    const candidates = result.get(key) ?? [];
+    candidates.push({
+      ...(resolvedLabel(attribute) ? { value: resolvedLabel(attribute) } : {}),
+      ...(attribute?.raw ? { raw: attribute.raw } : {}),
+      evidence: label.evidence,
+    });
+    result.set(key, candidates);
+  }
+  return result;
+}
+function associatedLabelFor(view, labels) {
+  const explicit = view.id
+    ? (labels.get(`${view.resourceType}/${view.resourceName}#${view.id}`) ?? [])
+    : [];
+  const values = [
+    ...new Set(
+      explicit
+        .map((candidate) => candidate.value)
+        .filter((value) => value !== undefined),
+    ),
+  ];
+  if (values.length === 1) {
+    return {
+      value: values[0],
+      candidates: explicit,
+      source: "label-for",
+      labelForUnresolved: false,
+    };
+  }
+  const hint = resolvedLabel(view.hint);
+  if (explicit.length > 0) {
+    return {
+      ...(hint ? { value: hint } : {}),
+      candidates: explicit,
+      source: hint ? "hint" : "none",
+      labelForUnresolved: true,
+    };
+  }
+  return {
+    ...(hint ? { value: hint } : {}),
+    candidates: [],
+    source: hint ? "hint" : "none",
+    labelForUnresolved: false,
+  };
+}
+function ownerFactData(builder, ownerRef) {
+  const fact = builder.fact(ownerRef);
+  if (!fact || fact.kind !== "component") {
+    throw new Error(`Missing component owner ${ownerRef}`);
+  }
+  return fact.data;
+}
+function propagateIncludedLayoutOwners(android, state) {
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const include of android.includes) {
+      const parentOwners = state.layoutOwners.get(include.resourceName);
+      if (!parentOwners) continue;
+      const childOwners =
+        state.layoutOwners.get(include.includedLayout) ?? new Set();
+      const before = childOwners.size;
+      parentOwners.forEach((owner) => childOwners.add(owner));
+      if (childOwners.size !== before) {
+        state.layoutOwners.set(include.includedLayout, childOwners);
+        changed = true;
+      }
+    }
+  }
+}
+function addManifestFacts(android, state) {
+  for (const component of android.manifest.components) {
+    if (component.kind === "activity-alias" && component.targetActivity) {
+      const targetRef = state.ensureComponent(
+        component.targetActivity,
+        "activity",
+        component.evidence,
+        "activity-alias target",
+        "high",
+        {
+          uiTechnology: "views",
+          ...(component.provenance
+            ? { manifestProvenance: component.provenance }
+            : {}),
+        },
+      );
+      // Retain the technical alias declaration without turning it into a
+      // user-visible Area. Entry filters declared on the alias resolve to the
+      // actual Activity target.
+      state.ensureComponent(
+        component.name,
+        "other",
+        component.evidence,
+        "activity-alias declaration",
+        "high",
+        {
+          exported: component.exported,
+          ...(component.provenance
+            ? { manifestProvenance: component.provenance }
+            : {}),
+        },
+      );
+      state.activityAliasTargetByQualifiedName.set(component.name, targetRef);
+      continue;
+    }
+    const widgetLayout =
+      component.kind === "app-widget"
+        ? android.appWidgetLayouts?.find(
+            (item) => item.componentName === component.name,
+          )
+        : undefined;
+    const componentRef = state.ensureComponent(
+      component.name,
+      manifestComponentType(component),
+      component.evidence,
+      "manifest component declaration",
+      "high",
+      {
+        exported: component.exported,
+        uiTechnology:
+          component.kind === "app-widget" ? "remote-views" : "views",
+        ...(widgetLayout
+          ? { layoutResource: widgetLayout.layoutResourceName }
+          : {}),
+        ...(component.provenance
+          ? { manifestProvenance: component.provenance }
+          : {}),
+      },
+    );
+    if (widgetLayout) {
+      state.addLayoutOwner(widgetLayout.layoutResourceName, componentRef);
+    }
+  }
+  for (const entry of android.manifest.entries) {
+    let componentRef =
+      state.activityAliasTargetByQualifiedName.get(entry.componentName) ??
+      state.componentByQualifiedName.get(entry.componentName);
+    if (!componentRef) {
+      componentRef = state.ensureComponent(
+        entry.componentName,
+        "activity",
+        entry.evidence,
+        "entry component declaration",
+        "high",
+        { uiTechnology: "views" },
+      );
+    }
+    const widgetInfo =
+      entry.kind === "widget"
+        ? android.appWidgetLayouts?.find(
+            (item) => item.componentName === entry.componentName,
+          )
+        : undefined;
+    const widgetConditionRef =
+      entry.kind === "widget"
+        ? state.builder.addFact("condition", {
+            identity: [
+              { kind: "component", value: componentRef },
+              { kind: "semantic-key", value: "app-widget-added" },
+            ],
+            confidence: "high",
+            support: [
+              {
+                location: entry.evidence,
+                role: "manifest declares an installable app-widget provider",
+              },
+              ...(widgetInfo
+                ? [
+                    {
+                      location: widgetInfo.evidence,
+                      role: "app-widget provider declares a RemoteViews layout",
+                    },
+                  ]
+                : []),
+            ],
+            data: {
+              ownerKey: componentRef,
+              expressionAnchor: "app-widget-added",
+              plainLanguage: "应用小组件已添加到 Android 主屏幕",
+              valueKind: "runtime",
+            },
+            relatedFactRefs: [componentRef],
+          })
+        : undefined;
+    state.builder.addFact("entry-point", {
+      identity: [
+        { kind: "entry", value: entry.kind },
+        { kind: "component", value: entry.componentName },
+        ...(entry.uri ? [{ kind: "route", value: entry.uri }] : []),
+      ],
+      confidence: "high",
+      support: [
+        {
+          location: entry.evidence,
+          role: "manifest intent filter",
+        },
+      ],
+      data: {
+        entryKind: entry.kind,
+        category: entry.category,
+        componentKey: componentRef,
+        action: entry.action,
+        ...(entry.uri ? { uri: entry.uri } : {}),
+        conditionKeys: widgetConditionRef ? [widgetConditionRef] : [],
+      },
+      relatedFactRefs: [
+        componentRef,
+        ...(widgetConditionRef ? [widgetConditionRef] : []),
+      ],
+    });
+  }
+}
+function addResourceFacts(android, builder) {
+  for (const value of android.values) {
+    builder.addFact("resource-value", {
+      identity: [
+        {
+          kind: "resource",
+          value: `${value.resourceType}/${value.name}`,
+        },
+        { kind: "variant", value: value.configuration },
+      ],
+      confidence: "high",
+      support: [
+        {
+          location: value.evidence,
+          role: "selected resource value",
+        },
+      ],
+      data: {
+        resourceType: value.resourceType,
+        resourceName: value.name,
+        configuration: value.configuration,
+        value: value.value,
+      },
+    });
+  }
+}
+function addFragmentComponents(android, state) {
+  for (const fragment of android.fragments) {
+    const className = resolvedClassName(
+      fragment.className,
+      android.manifest.packageName,
+    );
+    const ref = state.ensureComponent(
+      className,
+      "fragment",
+      fragment.evidence,
+      "XML fragment declaration",
+      "high",
+      { uiTechnology: "views" },
+    );
+    if (fragment.id) state.fragmentByNavigationId.set(fragment.id, ref);
+  }
+}
+/**
+ * Connects fragments declared by a selected layout to that layout's resolved
+ * Activity/Fragment owner. A NavHost is implementation infrastructure: its
+ * navigation graph is hosted by the layout owner, while a plain static
+ * <fragment> is the owner's fixed initial content.
+ *
+ * This runs after JVM structure preparation because setContentView/ViewBinding
+ * calls are what establish most layout owners.
+ */
+function addXmlFragmentBindings(android, state) {
+  for (const fragment of android.fragments) {
+    const owners = [
+      ...(state.layoutOwners.get(fragment.resourceName) ?? []),
+    ].sort();
+    if (owners.length === 0) continue;
+    if (fragment.navigationGraph) {
+      const hosts =
+        state.navigationHostsByGraph.get(fragment.navigationGraph) ?? new Set();
+      owners.forEach((ownerRef) => hosts.add(ownerRef));
+      state.navigationHostsByGraph.set(fragment.navigationGraph, hosts);
+      continue;
+    }
+    const className = resolvedClassName(
+      fragment.className,
+      android.manifest.packageName,
+    );
+    const fragmentRef = state.componentByQualifiedName.get(className);
+    if (!fragmentRef) continue;
+    for (const ownerRef of owners) {
+      state.builder.addFact("container-binding", {
+        identity: [
+          { kind: "component", value: ownerRef },
+          {
+            kind: "semantic-key",
+            value: `fragment:${fragment.id ?? className}`,
+          },
+        ],
+        confidence: "high",
+        support: [
+          {
+            location: fragment.evidence,
+            role: "static XML fragment content",
+          },
+        ],
+        data: {
+          bindingKind: "fragment",
+          hostKey: ownerRef,
+          contentKeys: [fragmentRef],
+          initialContentKey: fragmentRef,
+        },
+        relatedFactRefs: [ownerRef, fragmentRef],
+      });
+    }
+  }
+}
+function identityForView(ownerRef, view, inferredResourceId) {
+  const semanticControl =
+    view.id ??
+    inferredResourceId ??
+    [
+      simpleTag(view.tag),
+      elementType(view) === "text-input"
+        ? ""
+        : (resolvedLabel(view.text) ?? ""),
+      resolvedLabel(view.hint) ?? "",
+      resolvedLabel(view.contentDescription) ?? "",
+      iconResource(view.iconResources?.[0]) ?? "",
+      view.onClick ?? "",
+    ].join("|");
+  return [
+    { kind: "component", value: ownerRef },
+    {
+      kind: "resource",
+      value: `${view.resourceType}/${view.resourceName}`,
+    },
+    { kind: "control", value: semanticControl },
+  ];
+}
+function addAttributeUnresolved(
+  builder,
+  factRef,
+  property,
+  attribute,
+  evidenceRef,
+) {
+  if (
+    !attribute?.raw.startsWith("@") ||
+    attribute.resolved !== undefined ||
+    attribute.resolvedValue !== undefined
+  ) {
+    return;
+  }
+  builder.addUnresolved({
+    ownerRef: factRef,
+    fieldPath: `data.${property}`,
+    reasonCode: "INTRINSIC_RESOURCE_VALUE_UNKNOWN",
+    message: `The selected resources do not resolve ${attribute.raw}.`,
+    evidenceRefs: [evidenceRef],
+    candidates: [],
+    impact: ["control-description"],
+    originRef: attribute.raw,
+  });
+}
+function resolvedAttributeValue(attribute) {
+  if (!attribute) return undefined;
+  if (attribute.resolvedValue !== undefined) {
+    return attribute.resolvedValue;
+  }
+  if (attribute.resolved !== undefined) return attribute.resolved;
+  return attribute.raw.startsWith("@") ? undefined : attribute.raw;
+}
+function booleanAttributeValue(attribute) {
+  const value = resolvedAttributeValue(attribute);
+  if (typeof value === "boolean") return value;
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "true") return true;
+  if (normalized === "false") return false;
+  return undefined;
+}
+function textDefaultValue(attribute) {
+  const value = resolvedAttributeValue(attribute);
+  return typeof value === "string" ? value : undefined;
+}
+function preferenceDefaultValue(attribute) {
+  const value = resolvedAttributeValue(attribute);
+  if (typeof value !== "string") return value;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "true") return true;
+  if (normalized === "false") return false;
+  return value;
+}
+function optionsAttributeValue(attribute) {
+  const value = resolvedAttributeValue(attribute);
+  return Array.isArray(value) ? value : undefined;
+}
+function addXmlUiProperty(state, factRef, view, property, value) {
+  state.builder.addFact("ui-property", {
+    identity: [
+      { kind: "control", value: factRef },
+      { kind: "semantic-key", value: property },
+    ],
+    confidence: "high",
+    support: [
+      {
+        location: view.evidence,
+        role: "selected XML control property",
+      },
+    ],
+    data: {
+      ownerKey: factRef,
+      property,
+      value,
+    },
+    relatedFactRefs: [factRef],
+  });
+}
+function addXmlPropertyUnresolved(
+  state,
+  factRef,
+  property,
+  attribute,
+  evidenceRef,
+) {
+  if (!attribute) return;
+  state.builder.addUnresolved({
+    ownerRef: factRef,
+    fieldPath: `data.${property}`,
+    reasonCode: attribute.raw.startsWith("@")
+      ? "INTRINSIC_RESOURCE_VALUE_UNKNOWN"
+      : "INTRINSIC_XML_PROPERTY_VALUE_UNKNOWN",
+    message:
+      `The selected XML value ${attribute.raw || "(empty)"} cannot be ` +
+      `normalized as control property ${property}.`,
+    evidenceRefs: [evidenceRef],
+    candidates: [],
+    impact: ["control-description"],
+    originRef: attribute.raw,
+  });
+}
+const booleanOptionElementTypes = new Set([
+  "checkbox",
+  "radio-button",
+  "switch",
+  "toggle-button",
+]);
+function addXmlHandler(state, ownerRef, viewFactRef, view) {
+  if (!view.onClick) return;
+  const owner = ownerFactData(state.builder, ownerRef);
+  const callableSymbol = `${owner.qualifiedName}#${view.onClick}`;
+  const callbackRef = state.builder.addFact("callback", {
+    identity: [
+      { kind: "component", value: ownerRef },
+      { kind: "callback", value: callableSymbol },
+    ],
+    confidence: "high",
+    support: [
+      {
+        location: view.evidence,
+        role: "android:onClick handler",
+      },
+    ],
+    data: {
+      ownerKey: ownerRef,
+      callableSymbol,
+      callbackKind: "xml-handler",
+    },
+    relatedFactRefs: [ownerRef],
+  });
+  state.registerCallback(callableSymbol, callbackRef);
+  state.builder.addFact("interaction-binding", {
+    identity: [
+      { kind: "control", value: viewFactRef },
+      { kind: "callback", value: callbackRef },
+      { kind: "semantic-key", value: "click" },
+    ],
+    confidence: "high",
+    support: [
+      {
+        location: view.evidence,
+        role: "android:onClick binding",
+      },
+    ],
+    data: {
+      elementKey: viewFactRef,
+      callbackKey: callbackRef,
+      trigger: "click",
+      bindingApi: "android:onClick",
+    },
+    relatedFactRefs: [viewFactRef, callbackRef],
+  });
+}
+function addViews(android, state) {
+  propagateIncludedLayoutOwners(android, state);
+  const associatedLabels = labelsByTarget(android);
+  const contentByLayout = new Map();
+  const semanticOccurrences = new Map();
+  for (const view of android.views) {
+    let owners = [...(state.layoutOwners.get(view.resourceName) ?? [])];
+    let surrogate = false;
+    if (owners.length === 0) {
+      owners = [state.ensureLayoutSurrogate(view.resourceName, view.evidence)];
+      surrogate = true;
+    }
+    for (const ownerRef of owners.sort()) {
+      const inferredResourceId = view.isLayoutRoot
+        ? state.repeatedLayoutResourceId(view.resourceName, ownerRef)
+        : undefined;
+      const effectiveResourceId = view.id ?? inferredResourceId;
+      const identity = identityForView(ownerRef, view, inferredResourceId);
+      const collisionKey = JSON.stringify(identity);
+      semanticOccurrences.set(
+        collisionKey,
+        (semanticOccurrences.get(collisionKey) ?? 0) + 1,
+      );
+      const normalizedElementType = elementType(view);
+      // android:text is the initial value of an input, not its product label.
+      const text =
+        normalizedElementType === "text-input"
+          ? undefined
+          : resolvedLabel(view.text);
+      const description = resolvedLabel(view.contentDescription);
+      const label = associatedLabelFor(view, associatedLabels);
+      const icon = iconResource(view.iconResources?.[0]);
+      const support = [
+        {
+          location: view.evidence,
+          role: "selected XML view declaration",
+        },
+        ...label.candidates.map((candidate) => ({
+          location: candidate.evidence,
+          role: "android:labelFor naming evidence",
+        })),
+      ];
+      const onlyIconNamingEvidence =
+        !text && !description && !label.value && Boolean(icon);
+      const onlyIdentifierNamingEvidence =
+        !text &&
+        !description &&
+        !label.value &&
+        !icon &&
+        Boolean(effectiveResourceId);
+      const noNamingEvidence =
+        !text && !description && !label.value && !icon && !effectiveResourceId;
+      const factRef = state.builder.addFact("ui-element", {
+        identity,
+        confidence:
+          surrogate ||
+          onlyIconNamingEvidence ||
+          onlyIdentifierNamingEvidence ||
+          noNamingEvidence
+            ? "medium"
+            : "high",
+        support,
+        data: {
+          ownerKey: ownerRef,
+          elementType: inferredResourceId
+            ? "repeated-row"
+            : ownerFactData(state.builder, ownerRef).uiTechnology ===
+                "remote-views"
+              ? `remote-views-${normalizedElementType}`
+              : normalizedElementType,
+          actionable: view.actionable,
+          ...(effectiveResourceId ? { resourceId: effectiveResourceId } : {}),
+          ...(text ? { visibleText: text } : {}),
+          ...(description ? { contentDescription: description } : {}),
+          ...(label.value ? { associatedLabel: label.value } : {}),
+          ...(icon ? { iconResource: icon } : {}),
+          ...(inferredResourceId
+            ? { dynamicIdentity: inferredResourceId }
+            : {}),
+        },
+        relatedFactRefs: [ownerRef],
+      });
+      state.uiOwnerById.set(factRef, ownerRef);
+      state.registerUi(view.id, factRef);
+      state.registerLayoutUi(
+        view.resourceName,
+        factRef,
+        view.isLayoutRoot === true,
+      );
+      const list = contentByLayout.get(view.resourceName) ?? [];
+      list.push(factRef);
+      contentByLayout.set(view.resourceName, list);
+      const evidenceRef = state.builder.addEvidence(view.evidence);
+      if (normalizedElementType !== "text-input") {
+        addAttributeUnresolved(
+          state.builder,
+          factRef,
+          "visibleText",
+          view.text,
+          evidenceRef,
+        );
+      }
+      if (view.enabled) {
+        const enabled = booleanAttributeValue(view.enabled);
+        if (enabled === undefined) {
+          addXmlPropertyUnresolved(
+            state,
+            factRef,
+            "enabled",
+            view.enabled,
+            evidenceRef,
+          );
+        } else {
+          addXmlUiProperty(state, factRef, view, "enabled", enabled);
+        }
+      }
+      const defaultAttribute =
+        view.checked ??
+        (normalizedElementType === "text-input" ? view.text : undefined);
+      if (defaultAttribute) {
+        const preferenceControl =
+          view.resourceType === "xml" &&
+          simpleTag(view.tag).toLowerCase().includes("preference");
+        const defaultValue = view.checked
+          ? preferenceControl
+            ? preferenceDefaultValue(defaultAttribute)
+            : booleanAttributeValue(defaultAttribute)
+          : textDefaultValue(defaultAttribute);
+        if (defaultValue === undefined) {
+          addXmlPropertyUnresolved(
+            state,
+            factRef,
+            "default",
+            defaultAttribute,
+            evidenceRef,
+          );
+        } else {
+          addXmlUiProperty(state, factRef, view, "default", defaultValue);
+        }
+      }
+      if (view.entries) {
+        const options = optionsAttributeValue(view.entries);
+        if (!options) {
+          addXmlPropertyUnresolved(
+            state,
+            factRef,
+            "options",
+            view.entries,
+            evidenceRef,
+          );
+        } else {
+          addXmlUiProperty(state, factRef, view, "options", options);
+        }
+      } else if (
+        view.checked !== undefined ||
+        booleanOptionElementTypes.has(normalizedElementType)
+      ) {
+        addXmlUiProperty(state, factRef, view, "options", [false, true]);
+      }
+      if (label.source !== "label-for") {
+        addAttributeUnresolved(
+          state.builder,
+          factRef,
+          "associatedLabel",
+          view.hint,
+          evidenceRef,
+        );
+      }
+      if (label.candidates.length > 0 && label.labelForUnresolved) {
+        const candidateEvidence = label.candidates.map((candidate) =>
+          state.builder.addEvidence(candidate.evidence),
+        );
+        state.builder.addUnresolved({
+          ownerRef: factRef,
+          fieldPath: "data.associatedLabel",
+          reasonCode: "INTRINSIC_LABEL_FOR_TEXT_UNKNOWN",
+          message:
+            "android:labelFor associates this control with label elements, " +
+            "but their selected text is absent or conflicting.",
+          evidenceRefs: candidateEvidence,
+          candidates: label.candidates.map((candidate, index) => ({
+            value: candidate.value ?? candidate.raw ?? null,
+            supportRefs: [candidateEvidence[index]],
+          })),
+          impact: ["control-description"],
+        });
+      }
+      if (
+        view.actionable &&
+        !inferredResourceId &&
+        (onlyIdentifierNamingEvidence || noNamingEvidence)
+      ) {
+        state.builder.addUnresolved({
+          ownerRef: factRef,
+          fieldPath: "data.controlName",
+          reasonCode: "INTRINSIC_CONTROL_NAME_UNKNOWN",
+          message:
+            "The control has no visible text, content description, " +
+            "associated label, hint, or stable icon resource name.",
+          evidenceRefs: [evidenceRef],
+          candidates: [],
+          impact: ["control-description"],
+        });
+      }
+      addAttributeUnresolved(
+        state.builder,
+        factRef,
+        "contentDescription",
+        view.contentDescription,
+        evidenceRef,
+      );
+      if (surrogate) {
+        state.builder.addUnresolved({
+          ownerRef: factRef,
+          fieldPath: "data.ownerKey",
+          reasonCode: "INTRINSIC_LAYOUT_OWNER_UNKNOWN",
+          message:
+            `No resolved source binding associates @layout/${view.resourceName} ` +
+            "with an Activity or Fragment.",
+          evidenceRefs: [evidenceRef],
+          candidates: [],
+          impact: ["area-ownership", "control-paths"],
+          originRef: ownerRef,
+        });
+      }
+      addXmlHandler(state, ownerRef, factRef, view);
+    }
+  }
+  for (const [collisionKey, count] of semanticOccurrences) {
+    if (count <= 1) continue;
+    const identity = JSON.parse(collisionKey);
+    const factRef = state.builder.stableId("fact", "ui-element", identity);
+    const fact = state.builder.fact(factRef);
+    if (!fact) continue;
+    state.builder.addUnresolved({
+      ownerRef: factRef,
+      fieldPath: "id",
+      reasonCode: "INTRINSIC_UI_IDENTITY_AMBIGUOUS",
+      message:
+        "Multiple XML elements have the same semantic identity and no " +
+        "resource ID; they are represented as one conservative fact.",
+      evidenceRefs: fact.support.map((item) => item.evidenceRef),
+      candidates: [],
+      impact: ["control-cardinality"],
+    });
+  }
+  return contentByLayout;
+}
+function addLayoutBindings(android, state, contentByLayout) {
+  for (const resource of android.resources) {
+    if (resource.resourceType !== "layout") continue;
+    const contentRefs = [
+      ...new Set(contentByLayout.get(resource.name) ?? []),
+    ].sort();
+    if (contentRefs.length === 0) continue;
+    let owners = [...(state.layoutOwners.get(resource.name) ?? [])];
+    if (owners.length === 0) {
+      owners = [state.ensureLayoutSurrogate(resource.name, resource.evidence)];
+    }
+    for (const ownerRef of owners.sort()) {
+      state.builder.addFact("container-binding", {
+        identity: [
+          { kind: "component", value: ownerRef },
+          { kind: "resource", value: `layout/${resource.name}` },
+        ],
+        confidence:
+          ownerFactData(state.builder, ownerRef).componentType === "widget"
+            ? "medium"
+            : "high",
+        support: [
+          {
+            location: resource.evidence,
+            role: "selected layout",
+          },
+        ],
+        data: {
+          bindingKind: "layout",
+          hostKey: ownerRef,
+          contentKeys: contentRefs,
+        },
+        relatedFactRefs: [ownerRef, ...contentRefs],
+      });
+    }
+  }
+}
+function navigationHosts(android, state, resourceName, location) {
+  const resolved = [
+    ...(state.navigationHostsByGraph.get(resourceName) ?? []),
+  ].sort();
+  if (resolved.length > 0) return resolved;
+  return [
+    state.ensureComponent(
+      `@navigation/${resourceName}`,
+      "other",
+      location,
+      "navigation graph",
+      "high",
+      { uiTechnology: "views" },
+    ),
+  ];
+}
+function addNavigationFacts(android, state) {
+  const shortcutResources = new Set(
+    android.manifest.components.flatMap(
+      (component) => component.shortcutResources ?? [],
+    ),
+  );
+  for (const target of android.navigationTargets) {
+    // Shortcut intents are alternate entry declarations, not user actions
+    // originating from an in-app Area.
+    if (
+      target.kind === "intent" &&
+      target.resourceType === "xml" &&
+      shortcutResources.has(target.resourceName)
+    )
+      continue;
+    const hostRefs = navigationHosts(
+      android,
+      state,
+      target.resourceName,
+      target.evidence,
+    );
+    for (const hostRef of hostRefs) {
+      const sourceRef = target.sourceId
+        ? (state.fragmentByNavigationId.get(target.sourceId) ?? hostRef)
+        : hostRef;
+      const destinationRef = target.destination
+        ? state.fragmentByNavigationId.get(target.destination)
+        : undefined;
+      if (
+        target.kind === "navigation-action" &&
+        target.actionId &&
+        destinationRef
+      ) {
+        state.navigationTargetByActionId.set(target.actionId, destinationRef);
+      }
+      if (target.kind === "graph-start" && destinationRef) {
+        state.builder.addFact("container-binding", {
+          identity: [
+            { kind: "component", value: hostRef },
+            {
+              kind: "resource",
+              value: `navigation/${target.resourceName}`,
+            },
+          ],
+          confidence: "high",
+          support: [
+            {
+              location: target.evidence,
+              role: "navigation start destination",
+            },
+          ],
+          data: {
+            bindingKind: "navigation",
+            hostKey: hostRef,
+            contentKeys: [destinationRef],
+            initialContentKey: destinationRef,
+          },
+          relatedFactRefs: [hostRef, destinationRef],
+        });
+        continue;
+      }
+      let resolvedTarget = destinationRef;
+      let targetKind = destinationRef ? "component" : "dynamic";
+      if (target.targetClass) {
+        const className = resolvedClassName(
+          target.targetClass,
+          target.targetPackage ?? android.manifest.packageName,
+        );
+        resolvedTarget =
+          state.componentByQualifiedName.get(className) ??
+          state.ensureComponent(
+            className,
+            "activity",
+            target.evidence,
+            "navigation intent target",
+            "high",
+            { uiTechnology: "views" },
+          );
+        targetKind =
+          target.targetPackage &&
+          target.targetPackage !== android.manifest.packageName
+            ? "external"
+            : "component";
+      } else if (target.targetPackage) {
+        resolvedTarget = state.ensureComponent(
+          `external-package:${target.targetPackage}`,
+          "other",
+          target.evidence,
+          "external navigation package",
+          "medium",
+        );
+        targetKind = "external";
+      }
+      const callbackRef = state.builder.addFact("callback", {
+        identity: [
+          { kind: "component", value: sourceRef },
+          {
+            kind: "callback",
+            value:
+              `@${target.resourceType}/${target.resourceName}:${target.kind}:` +
+              `${target.actionId ?? target.sourceId ?? "root"}`,
+          },
+        ],
+        confidence: "high",
+        support: [
+          {
+            location: target.evidence,
+            role: "navigation declaration",
+          },
+        ],
+        data: {
+          ownerKey: sourceRef,
+          callableSymbol:
+            `@${target.resourceType}/${target.resourceName}#` +
+            `${target.actionId ?? target.sourceId ?? target.kind}`,
+          callbackKind: "function",
+        },
+        relatedFactRefs: [sourceRef],
+      });
+      const effectRef = state.builder.addFact("behavior-effect", {
+        identity: [
+          { kind: "callback", value: callbackRef },
+          {
+            kind: "route",
+            value:
+              target.destination ??
+              target.targetClass ??
+              target.targetPackage ??
+              target.kind,
+          },
+        ],
+        confidence: resolvedTarget ? "high" : "medium",
+        support: [
+          {
+            location: target.evidence,
+            role: "navigation target declaration",
+          },
+        ],
+        data: {
+          callbackKey: callbackRef,
+          effectKind:
+            targetKind === "external" ? "open-external" : "navigate-area",
+          ...(resolvedTarget ? { targetKey: resolvedTarget } : {}),
+        },
+        relatedFactRefs: [
+          callbackRef,
+          ...(resolvedTarget ? [resolvedTarget] : []),
+        ],
+      });
+      const navigationRef = state.builder.addFact("navigation-target", {
+        identity: [
+          { kind: "semantic-key", value: effectRef },
+          {
+            kind: "route",
+            value:
+              target.destination ??
+              target.targetClass ??
+              target.targetPackage ??
+              target.kind,
+          },
+        ],
+        confidence: resolvedTarget ? "high" : "medium",
+        support: [
+          {
+            location: target.evidence,
+            role: "navigation destination",
+          },
+        ],
+        data: {
+          effectKey: effectRef,
+          targetKind,
+          ...(resolvedTarget ? { targetKey: resolvedTarget } : {}),
+        },
+        relatedFactRefs: [
+          effectRef,
+          ...(resolvedTarget ? [resolvedTarget] : []),
+        ],
+      });
+      if (!resolvedTarget) {
+        const evidenceRef = state.builder.addEvidence(target.evidence);
+        state.builder.addUnresolved({
+          ownerRef: navigationRef,
+          fieldPath: "data.targetKey",
+          reasonCode: "INTRINSIC_NAVIGATION_TARGET_UNKNOWN",
+          message:
+            "The navigation declaration names a destination that is not " +
+            "present in the selected source facts.",
+          evidenceRefs: [evidenceRef],
+          candidates: target.destination
+            ? [{ value: target.destination, supportRefs: [evidenceRef] }]
+            : [],
+          impact: ["area-edge-target"],
+        });
+      }
+    }
+  }
+}
+export function normalizeAndroidFacts(android, state) {
+  addManifestFacts(android, state);
+  addResourceFacts(android, state.builder);
+  addFragmentComponents(android, state);
+  addXmlFragmentBindings(android, state);
+  const contentByLayout = addViews(android, state);
+  addLayoutBindings(android, state, contentByLayout);
+  addNavigationFacts(android, state);
+}
+/**
+ * Registers semantic component identities before JVM calls are interpreted.
+ * Calling `normalizeAndroidFacts` afterwards is safe and only merges support.
+ */
+export function prepareAndroidStructure(android, state) {
+  addManifestFacts(android, state);
+  addFragmentComponents(android, state);
+}