android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/analysis/names/traceability.js

@@ -0,0 +1,468 @@
+import { NAME_TRACEABILITY_CONTRACT_VERSION } from "../../contracts/index.js";
+import {
+  codeNameCandidate,
+  componentIdentifierName,
+  controlNameCandidates,
+  literalNameCandidate,
+  resolveNameCandidates,
+  semanticIdentifierName,
+} from "./policy.js";
+export const NAME_TRACEABILITY_FILENAME = "name-traceability.json";
+function uniqueSorted(values) {
+  return [...new Set(values)].sort((left, right) =>
+    left.localeCompare(right, "en"),
+  );
+}
+function displayName(value, fallback) {
+  return value.status === "resolved" ? value.value.trim() : fallback;
+}
+function comparableReqText(value) {
+  return value
+    .normalize("NFKC")
+    .replace(/\p{White_Space}+/gu, " ")
+    .trim();
+}
+function repeatedControlName(areaName) {
+  if (!areaName) return "List item";
+  return /\p{Script=Han}/u.test(areaName)
+    ? `${areaName}列表项`
+    : `${areaName} item`;
+}
+function frameworkGenericProperty(fact) {
+  return fact.support.some(
+    (support) => support.role === "resolved Compose surface API name",
+  );
+}
+function selectedFirst(values, selectedRefs) {
+  return [...values].sort(
+    (left, right) =>
+      Number(selectedRefs.has(right.id)) - Number(selectedRefs.has(left.id)) ||
+      left.id.localeCompare(right.id, "en"),
+  );
+}
+function areaNameDecision(area, source) {
+  const sourceFactRefs = new Set(area.sourceFactRefs);
+  const selectedRefs = new Set(
+    area.name.status === "resolved" ? area.name.supportRefs : [],
+  );
+  const variants = selectedFirst(
+    source.facts.filter(
+      (fact) =>
+        fact.kind === "component-variant" && sourceFactRefs.has(fact.id),
+    ),
+    selectedRefs,
+  );
+  const selectedVariant = variants.find((variant) =>
+    selectedRefs.has(variant.id),
+  );
+  if (selectedVariant) {
+    return resolveNameCandidates([
+      literalNameCandidate(
+        "variant-display-name",
+        selectedVariant.data.displayName,
+        [selectedVariant.id],
+        selectedVariant.confidence,
+      ),
+      codeNameCandidate(
+        "variant-state",
+        selectedVariant.data.stateKey,
+        area.name.status === "resolved"
+          ? area.name.supportRefs
+          : [selectedVariant.id],
+        (stateKey) =>
+          area.name.status === "resolved"
+            ? area.name.value
+            : semanticIdentifierName(stateKey.replace(/^.*[./#]/u, "")),
+      ),
+    ]);
+  }
+  const components = selectedFirst(
+    source.facts.filter(
+      (fact) => fact.kind === "component" && sourceFactRefs.has(fact.id),
+    ),
+    selectedRefs,
+  );
+  const componentRefs = new Set(components.map((component) => component.id));
+  const properties = selectedFirst(
+    source.facts.filter(
+      (fact) =>
+        fact.kind === "ui-property" &&
+        componentRefs.has(fact.data.ownerKey) &&
+        /^(title|label|name)$/iu.test(fact.data.property) &&
+        typeof fact.data.value === "string",
+    ),
+    selectedRefs,
+  );
+  return resolveNameCandidates([
+    ...properties.map((property) =>
+      literalNameCandidate(
+        "visible-title",
+        typeof property.data.value === "string"
+          ? property.data.value
+          : undefined,
+        [property.id],
+        property.confidence,
+        { frameworkGeneric: frameworkGenericProperty(property) },
+      ),
+    ),
+    ...components.map((component) =>
+      codeNameCandidate(
+        "component-identifier",
+        component.data.qualifiedName,
+        [component.id],
+        componentIdentifierName,
+      ),
+    ),
+  ]);
+}
+function controlNameDecision(control, graph, source) {
+  const selectedRefs = new Set(
+    control.name.status === "resolved" ? control.name.supportRefs : [],
+  );
+  const uiFacts = selectedFirst(
+    source.facts.filter(
+      (fact) =>
+        fact.kind === "ui-element" && control.sourceFactRefs.includes(fact.id),
+    ),
+    selectedRefs,
+  );
+  const ownerArea = graph.areas.find((area) => area.id === control.areaRef);
+  const areaName =
+    ownerArea?.name.status === "resolved" ? ownerArea.name.value : undefined;
+  const areaNameSupport =
+    ownerArea?.name.status === "resolved" ? ownerArea.name.supportRefs : [];
+  return resolveNameCandidates(
+    uiFacts.flatMap((fact) => {
+      const repeated =
+        (fact.data.elementType === "list-item" ||
+          fact.data.elementType === "repeated-row") &&
+        fact.data.dynamicIdentity
+          ? repeatedControlName(areaName)
+          : undefined;
+      return controlNameCandidates(
+        fact.data,
+        fact.id,
+        fact.confidence,
+        repeated,
+        areaNameSupport,
+      );
+    }),
+  );
+}
+function traceAttempts(decision) {
+  return decision.attempts.map((attempt) => ({
+    strategy: attempt.strategy,
+    candidateKind: attempt.kind,
+    outcome: attempt.outcome,
+    ...(attempt.rawValue === undefined ? {} : { rawValue: attempt.rawValue }),
+    ...(attempt.normalizedValue === undefined
+      ? {}
+      : { normalizedValue: attempt.normalizedValue }),
+    confidence: attempt.confidence,
+    supportRefs: uniqueSorted(attempt.supportRefs),
+    ...(attempt.reasonCode === undefined
+      ? {}
+      : { reasonCode: attempt.reasonCode }),
+    ...(attempt.reason === undefined ? {} : { reason: attempt.reason }),
+  }));
+}
+function unresolvedForName(value, graph, source) {
+  if (value.status === "resolved") return undefined;
+  return (
+    graph.unresolved.find((item) => item.id === value.unresolvedRef) ??
+    source.unresolved.find((item) => item.id === value.unresolvedRef)
+  );
+}
+const usageRank = {
+  related: 0,
+  candidate: 1,
+  unresolved: 2,
+  selected: 3,
+};
+function sourceLocations(finalName, decision, graph, source) {
+  const factById = new Map(source.facts.map((fact) => [fact.id, fact]));
+  const evidenceById = new Map(
+    source.evidence.map((evidence) => [evidence.id, evidence]),
+  );
+  const mutable = new Map();
+  const addEvidence = (evidenceRef, usage, sourceFactRef, role) => {
+    if (!evidenceById.has(evidenceRef)) return;
+    const existing = mutable.get(evidenceRef) ?? {
+      usage,
+      sourceFactRefs: new Set(),
+      supportRoles: new Set(),
+    };
+    if (usageRank[usage] > usageRank[existing.usage]) existing.usage = usage;
+    if (sourceFactRef) existing.sourceFactRefs.add(sourceFactRef);
+    if (role) existing.supportRoles.add(role);
+    mutable.set(evidenceRef, existing);
+  };
+  const addFact = (factRef, usage) => {
+    const fact = factById.get(factRef);
+    if (!fact) return;
+    fact.support.forEach((support) =>
+      addEvidence(support.evidenceRef, usage, fact.id, support.role),
+    );
+  };
+  const selectedRefs =
+    finalName.status === "resolved" ? finalName.supportRefs : [];
+  selectedRefs.forEach((ref) => addFact(ref, "selected"));
+  decision.attempts.forEach((attempt) => {
+    if (attempt.outcome === "absent") return;
+    const usage = attempt.outcome === "selected" ? "selected" : "candidate";
+    attempt.supportRefs.forEach((ref) => addFact(ref, usage));
+  });
+  const unresolved = unresolvedForName(finalName, graph, source);
+  unresolved?.evidenceRefs.forEach((ref) => addEvidence(ref, "unresolved"));
+  const directFactRefs = new Set([
+    ...selectedRefs,
+    ...decision.attempts.flatMap((attempt) => attempt.supportRefs),
+  ]);
+  for (const factRef of directFactRefs) {
+    const fact = factById.get(factRef);
+    for (const relatedRef of fact?.relatedFactRefs ?? []) {
+      const related = factById.get(relatedRef);
+      if (related?.kind === "resource-value") addFact(related.id, "related");
+    }
+  }
+  if (finalName.status === "resolved") {
+    /*
+     * Some normalizers resolve @string values before emitting UI facts and the
+     * v1 contract does not retain the resource ref on that fact. An exact
+     * selected-configuration value match is therefore reported as related
+     * definition evidence, never promoted to selected-name evidence.
+     */
+    for (const fact of source.facts) {
+      if (
+        fact.kind === "resource-value" &&
+        typeof fact.data.value === "string" &&
+        fact.data.value.trim() === finalName.value.trim()
+      )
+        addFact(fact.id, "related");
+    }
+  }
+  return [...mutable]
+    .flatMap(([evidenceRef, item]) => {
+      const evidence = evidenceById.get(evidenceRef);
+      return evidence
+        ? [
+            {
+              evidenceRef,
+              sourceFactRefs: uniqueSorted([...item.sourceFactRefs]),
+              usage: item.usage,
+              sourceKind: evidence.sourceKind,
+              path: evidence.path,
+              anchor: evidence.anchor,
+              range: evidence.range,
+              ...(evidence.symbol ? { symbol: evidence.symbol } : {}),
+              supportRoles: uniqueSorted([...item.supportRoles]),
+            },
+          ]
+        : [];
+    })
+    .sort(
+      (left, right) =>
+        left.path.localeCompare(right.path, "en") ||
+        left.range.startLine - right.range.startLine ||
+        left.range.endLine - right.range.endLine ||
+        left.evidenceRef.localeCompare(right.evidenceRef, "en"),
+    );
+}
+function reqLineIndex(reqModel, reqText) {
+  const lines = reqText.replace(/\r\n?/gu, "\n").split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  const comparableLines = lines.map(comparableReqText);
+  const areaStarts = lines.flatMap((line, index) =>
+    line.startsWith("访问路径：") ? [index] : [],
+  );
+  const areaLines = new Map();
+  const featureLines = new Map();
+  for (let areaIndex = 0; areaIndex < reqModel.areas.length; areaIndex += 1) {
+    const area = reqModel.areas[areaIndex];
+    const start = areaStarts[areaIndex] ?? 0;
+    const end = areaStarts[areaIndex + 1] ?? lines.length;
+    const name = displayName(area.displayName, "Area 名称待确认");
+    const comparableName = comparableReqText(name);
+    const matchedAreaLines = [];
+    for (let index = start; index < end; index += 1) {
+      if (comparableLines[index].includes(comparableName)) {
+        matchedAreaLines.push(index + 1);
+      }
+    }
+    if (matchedAreaLines.length === 0 && start < lines.length) {
+      matchedAreaLines.push(start + 1);
+    }
+    areaLines.set(area.id, uniqueSortedNumbers(matchedAreaLines));
+    let cursor = start;
+    for (const feature of area.features) {
+      const featureName = displayName(feature.displayName, "控件名称待确认");
+      const expected = comparableReqText(`${name}--${featureName}`);
+      const featureSuffix = comparableReqText(`--${featureName}`);
+      let lineIndex = -1;
+      for (let index = cursor; index < end; index += 1) {
+        if (comparableLines[index] === expected) {
+          lineIndex = index;
+          break;
+        }
+      }
+      if (lineIndex < 0) {
+        for (let index = cursor; index < end; index += 1) {
+          if (comparableLines[index].includes(featureSuffix)) {
+            lineIndex = index;
+            break;
+          }
+        }
+      }
+      if (lineIndex >= 0) {
+        featureLines.set(feature.id, [lineIndex + 1]);
+        cursor = lineIndex + 1;
+      } else {
+        featureLines.set(feature.id, []);
+      }
+    }
+  }
+  return { areaLines, featureLines };
+}
+function uniqueSortedNumbers(values) {
+  return [...new Set(values)].sort((left, right) => left - right);
+}
+function rejectedCandidates(attempts) {
+  return attempts.flatMap((attempt) =>
+    attempt.outcome === "rejected" &&
+    attempt.rawValue !== undefined &&
+    attempt.reasonCode !== undefined &&
+    attempt.reason !== undefined
+      ? [
+          {
+            strategy: attempt.strategy,
+            rawValue: attempt.rawValue,
+            ...(attempt.normalizedValue === undefined
+              ? {}
+              : { normalizedValue: attempt.normalizedValue }),
+            reasonCode: attempt.reasonCode,
+            reason: attempt.reason,
+            supportRefs: uniqueSorted(attempt.supportRefs),
+          },
+        ]
+      : [],
+  );
+}
+function assertSameAnalysisRun(source, graph, reqModel) {
+  if (
+    source.caseId !== graph.caseId ||
+    graph.caseId !== reqModel.caseId ||
+    JSON.stringify(source.analysisContext) !==
+      JSON.stringify(graph.analysisContext) ||
+    JSON.stringify(graph.analysisContext) !==
+      JSON.stringify(reqModel.analysisContext)
+  ) {
+    throw new Error(
+      "Name traceability inputs do not describe the same analysis run",
+    );
+  }
+}
+/**
+ * Per-entity naming evidence (finalName/attempts/rejectedCandidates/
+ * sourceLocations), independent of a rendered req.md — `reqLineNumbers` is
+ * always empty here. `buildNameTraceability` below fills it in once reqText
+ * exists; agent-render (which renders req.md one Feature at a time and has
+ * no reqText yet) uses this reqText-independent form directly, to ground
+ * title translation and citation seeding before rendering.
+ */
+export function buildNameTraceEntries(input) {
+  const { source, graph, reqModel } = input;
+  assertSameAnalysisRun(source, graph, reqModel);
+  const reqAreaByGraph = new Map(
+    reqModel.areas.map((area) => [area.areaRef, area]),
+  );
+  const reqFeaturesByControl = new Map();
+  for (const area of reqModel.areas) {
+    for (const feature of area.features) {
+      const refs = reqFeaturesByControl.get(feature.controlRef) ?? [];
+      refs.push(feature.id);
+      reqFeaturesByControl.set(feature.controlRef, refs);
+    }
+  }
+  const entries = [];
+  for (const area of [...graph.areas].sort((left, right) =>
+    left.id.localeCompare(right.id, "en"),
+  )) {
+    const decision = areaNameDecision(area, source);
+    const reqArea = reqAreaByGraph.get(area.id);
+    entries.push({
+      entityKind: "area",
+      entityRef: area.id,
+      reqRefs: reqArea ? [reqArea.id] : [],
+      finalName: area.name,
+      ...(decision.selectedStrategy
+        ? { selectedStrategy: decision.selectedStrategy }
+        : {}),
+      attempts: traceAttempts(decision),
+      rejectedCandidates: rejectedCandidates(decision.attempts),
+      sourceLocations: sourceLocations(area.name, decision, graph, source),
+      reqLineNumbers: [],
+    });
+  }
+  for (const control of [...graph.controls].sort((left, right) =>
+    left.id.localeCompare(right.id, "en"),
+  )) {
+    const decision = controlNameDecision(control, graph, source);
+    const reqRefs = uniqueSorted(reqFeaturesByControl.get(control.id) ?? []);
+    entries.push({
+      entityKind: "control",
+      entityRef: control.id,
+      ownerAreaRef: control.areaRef,
+      reqRefs,
+      finalName: control.name,
+      ...(decision.selectedStrategy
+        ? { selectedStrategy: decision.selectedStrategy }
+        : {}),
+      attempts: traceAttempts(decision),
+      rejectedCandidates: rejectedCandidates(decision.attempts),
+      sourceLocations: sourceLocations(control.name, decision, graph, source),
+      reqLineNumbers: [],
+    });
+  }
+  return entries;
+}
+function attachReqLineNumbers(entry, lineIndex) {
+  const reqLineNumbers =
+    entry.entityKind === "area"
+      ? [
+          ...(entry.reqRefs[0] !== undefined
+            ? (lineIndex.areaLines.get(entry.reqRefs[0]) ?? [])
+            : []),
+        ]
+      : uniqueSortedNumbers(
+          entry.reqRefs.flatMap((ref) => lineIndex.featureLines.get(ref) ?? []),
+        );
+  return { ...entry, reqLineNumbers };
+}
+/** Build a deterministic, source-linked explanation for every emitted name. */
+export function buildNameTraceability(input) {
+  const { graph, reqModel, reqText } = input;
+  const lineIndex = reqLineIndex(reqModel, reqText);
+  const entries = buildNameTraceEntries(input).map((entry) =>
+    attachReqLineNumbers(entry, lineIndex),
+  );
+  const resolved = entries.filter(
+    (entry) => entry.finalName.status === "resolved",
+  ).length;
+  return {
+    contractVersion: NAME_TRACEABILITY_CONTRACT_VERSION,
+    artifactKind: "name-traceability",
+    caseId: graph.caseId,
+    analysisContext: graph.analysisContext,
+    summary: {
+      areas: graph.areas.length,
+      controls: graph.controls.length,
+      resolved,
+      unresolved: entries.length - resolved,
+      rejectedCandidates: entries.reduce(
+        (count, entry) => count + entry.rejectedCandidates.length,
+        0,
+      ),
+    },
+    entries,
+  };
+}