android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/agent-render/name-trace.js

@@ -0,0 +1,153 @@
+// Grounds two prompt sections in the stage1 name-traceability artifact
+// (source-facts.json + area-graph.json), when present, instead of leaving
+// the Agent to rediscover the same evidence via blind Read/Glob/Grep:
+//   - a title-hint for displayName segments the template left unresolved,
+//     or resolved from a code identifier rather than real UI text
+//   - a citation seed for segments resolved from real UI text
+import {
+  buildNameTraceLookup,
+  LITERAL_NAME_STRATEGIES,
+  nameTraceKey,
+} from "../contracts/index.js";
+// The lookup shape/keying convention (nameTraceKey/buildNameTraceLookup) and
+// the literal-vs-code strategy classification now live in contracts, shared
+// with the dump module (which resolves Symbol/@Anchor from the same
+// name-traceability.json), so both consumers stay aligned instead of
+// drifting; re-exported here so every existing `from "./name-trace.js"`
+// import site in this directory keeps working.
+export { buildNameTraceLookup, nameTraceKey };
+function oneLineName(value) {
+  return value.trim().replace(/\s+/gu, " ");
+}
+export function resolveDisplayName(
+  displayName,
+  pendingFallback,
+  kind,
+  ref,
+  nameTrace,
+) {
+  const resolved = displayName.status === "resolved";
+  const name = resolved ? oneLineName(displayName.value) : pendingFallback;
+  const strategy = nameTrace?.get(nameTraceKey(kind, ref))?.selectedStrategy;
+  const translatable =
+    resolved &&
+    strategy !== undefined &&
+    !LITERAL_NAME_STRATEGIES.has(strategy) &&
+    /[A-Za-z]/u.test(name);
+  return { resolved, name, translatable };
+}
+function candidateLine(rawValue, confidence, outcome, detail) {
+  const suffix = detail === undefined ? "" : `，${detail}`;
+  return `  - 候选="${rawValue}"（置信度 ${confidence}，结论 ${outcome}${suffix}）`;
+}
+function unresolvedCandidateLines(entry) {
+  const rejected = entry.rejectedCandidates.map((candidate) =>
+    candidateLine(
+      candidate.rawValue,
+      "n/a",
+      "rejected",
+      `${candidate.reasonCode}：${candidate.reason}`,
+    ),
+  );
+  const absent = entry.attempts
+    .filter(
+      (attempt) =>
+        attempt.outcome !== "selected" && attempt.rawValue !== undefined,
+    )
+    .map((attempt) =>
+      candidateLine(attempt.rawValue, attempt.confidence, attempt.outcome),
+    );
+  return [...rejected, ...absent];
+}
+function locationLines(entry, usage) {
+  return entry.sourceLocations
+    .filter((location) => location.usage === usage)
+    .map(
+      (location) =>
+        `  - ${location.path}:${location.range.startLine}-${location.range.endLine}` +
+        (location.symbol === undefined ? "" : `（${location.symbol}）`),
+    );
+}
+/** For a title segment the template left unresolved: candidates + coordinates
+ * already extracted by stage1, so translation starts grounded instead of blind. */
+export function renderTitleHint(label, kind, ref, lookup) {
+  const entry = lookup.get(nameTraceKey(kind, ref));
+  const candidates = entry === undefined ? [] : unresolvedCandidateLines(entry);
+  const locations =
+    entry === undefined
+      ? []
+      : [
+          ...locationLines(entry, "unresolved"),
+          ...locationLines(entry, "candidate"),
+        ];
+  if (candidates.length === 0 && locations.length === 0) {
+    return `${label}：无 stage1 候选记录，需自行在源码中定位类名/资源标识。`;
+  }
+  const sections = [
+    candidates.length === 0
+      ? undefined
+      : [
+          `${label}的 stage1 候选（已提取但未采用，翻译前请核实，不要凭空编造）：`,
+          ...candidates,
+        ].join("\n"),
+    locations.length === 0
+      ? undefined
+      : [`${label}相关源码坐标：`, ...locations].join("\n"),
+  ].filter((section) => section !== undefined);
+  return sections.join("\n");
+}
+/** For a title segment the template already resolved: the exact evidence
+ * stage1 used, as an optional citation starting point — this only covers the
+ * area/control identity itself, every other body claim still needs its own
+ * independently-found citation (Law 第 2 条不因此放宽)。 */
+export function renderCitationSeed(label, kind, ref, lookup) {
+  const entry = lookup.get(nameTraceKey(kind, ref));
+  if (entry === undefined) return undefined;
+  const locations = locationLines(entry, "selected");
+  if (locations.length === 0) return undefined;
+  return [
+    `${label}本身的证据坐标（仅覆盖这个名称，正文其余每句陈述仍需自行查找并给出独立 citation）：`,
+    ...locations,
+  ].join("\n");
+}
+export function nameTraceBlockFor(
+  label,
+  kind,
+  ref,
+  resolved,
+  translatable,
+  lookup,
+) {
+  // Translatable resolved names need the same hint as unresolved ones (a
+  // grounded candidate to translate from); only a fixed, real-UI-text
+  // resolved name gets a citation seed instead.
+  return resolved && !translatable
+    ? renderCitationSeed(label, kind, ref, lookup)
+    : renderTitleHint(label, kind, ref, lookup);
+}
+/** Only present when a name-traceability artifact was loaded (SPEC-0001
+ * amendment 2026-07-22); absent gracefully degrades to blind exploration. */
+export function renderNameTraceSection(item, parts, lookup) {
+  if (lookup === undefined) return undefined;
+  const blocks = [
+    nameTraceBlockFor(
+      "区域名称",
+      "area",
+      item.area.areaRef,
+      parts.areaResolved,
+      parts.areaTranslatable,
+      lookup,
+    ),
+    nameTraceBlockFor(
+      "控件名称",
+      "control",
+      item.feature.controlRef,
+      parts.featureResolved,
+      parts.featureTranslatable,
+      lookup,
+    ),
+  ].filter((block) => block !== undefined);
+  return blocks.length === 0
+    ? undefined
+    : ["## nameTrace", ...blocks].join("\n\n");
+}