android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/core/stable-id.js

@@ -0,0 +1,92 @@
+import { createHash } from "node:crypto";
+import { semanticIdentityKinds } from "../contracts/common.js";
+const namespacePattern = /^[a-z][a-z0-9-]*$/u;
+const caseIdPattern = /^[a-z0-9][a-z0-9._-]*$/u;
+const idPattern =
+  /^[a-z][a-z0-9-]*:[a-z0-9][a-z0-9._-]*(?:\/[A-Za-z0-9._~:@#+=-]+)+$/u;
+const identityKindSet = new Set(semanticIdentityKinds);
+export function isValidCaseId(value) {
+  return caseIdPattern.test(value);
+}
+/**
+ * Derives a stable-ID-safe default from a project directory name. Explicit
+ * case IDs remain a caller-owned contract and are validated instead of being
+ * silently rewritten.
+ */
+export function deriveCaseId(projectName) {
+  const canonicalName = projectName.trim().normalize("NFC");
+  const slug = canonicalName
+    .normalize("NFKD")
+    .replace(/\p{Mark}+/gu, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/gu, "-")
+    .replace(/^[^a-z0-9]+|[^a-z0-9]+$/gu, "");
+  if (isValidCaseId(slug)) {
+    return slug;
+  }
+  const digest = createHash("sha256")
+    .update(canonicalName)
+    .digest("hex")
+    .slice(0, 12);
+  return `case-${digest}`;
+}
+function normalize(value) {
+  return value.replace(/\r\n?/gu, "\n").trim().normalize("NFC");
+}
+function entityKindSlug(value) {
+  const slug = normalize(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, "-")
+    .replace(/^-+|-+$/gu, "");
+  if (!namespacePattern.test(slug)) {
+    throw new Error(`entityKind cannot form a stable slug: ${value}`);
+  }
+  return slug;
+}
+function normalizedIdentity(identity) {
+  const unique = new Map();
+  identity.forEach((part, index) => {
+    if (!identityKindSet.has(part.kind)) {
+      throw new Error(`identity[${index}].kind is not semantic: ${part.kind}`);
+    }
+    const value = normalize(part.value);
+    if (value.length === 0) {
+      throw new Error(`identity[${index}].value must not be blank`);
+    }
+    const item = [part.kind, value];
+    unique.set(JSON.stringify(item), item);
+  });
+  return [...unique.values()].sort((left, right) => {
+    const leftKey = `${left[0]}\u0000${left[1]}`;
+    const rightKey = `${right[0]}\u0000${right[1]}`;
+    return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+  });
+}
+export function stableIdentityDigest(input) {
+  if (!namespacePattern.test(input.namespace)) {
+    throw new Error(`Invalid stable ID namespace: ${input.namespace}`);
+  }
+  if (!isValidCaseId(input.caseId)) {
+    throw new Error(`Invalid stable ID caseId: ${input.caseId}`);
+  }
+  const canonical = JSON.stringify({
+    namespace: input.namespace,
+    caseId: input.caseId,
+    entityKind: entityKindSlug(input.entityKind),
+    identity: normalizedIdentity(input.identity),
+  });
+  return createHash("sha256").update(canonical).digest("hex");
+}
+/**
+ * Builds an ID from semantic anchors only. The API intentionally has no array
+ * index or discovery-order argument, so reordering extractor output cannot
+ * change an entity's ID.
+ */
+export function createStableId(input) {
+  const kind = entityKindSlug(input.entityKind);
+  const digest = stableIdentityDigest(input).slice(0, 20);
+  return `${input.namespace}:${input.caseId}/${kind}/${digest}`;
+}
+export function isStableId(value) {
+  return idPattern.test(value);
+}

package/skills/a2h-app-req-gen/scripts/reqgen/src/dashboard-cli.js

@@ -0,0 +1,169 @@
+import { spawnSync } from "node:child_process";
+import { constants } from "node:fs";
+import { access, copyFile, mkdir } from "node:fs/promises";
+import path, { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildOpenCommand, createStaticServer } from "./agent-render/serve.js";
+const DASHBOARD_TEMPLATE = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "assets",
+  "dashboard.html",
+);
+const USAGE = `Usage:
+  pnpm dashboard -- --input <successful-stage1-run-directory>
+
+Options:
+  --input      Stage 1 run directory (required)
+  --rendering  Explicit rendering directory (default: <input>/generation/rendering)
+  --port       Server port (default: 0 for ephemeral)
+  --host       Bind address (default: 127.0.0.1)
+  --no-open    Do not open a browser automatically`;
+class DashboardUsageError extends Error {}
+function parseOptions(argv) {
+  const args = argv[0] === "--" ? argv.slice(1) : argv;
+  const values = new Map();
+  let noOpen = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "--no-open") {
+      noOpen = true;
+      continue;
+    }
+    if (!token.startsWith("--")) {
+      throw new DashboardUsageError(`Unexpected argument: ${token}`);
+    }
+    const separator = token.indexOf("=");
+    const name = token.slice(2, separator === -1 ? undefined : separator);
+    const supported = new Set(["input", "rendering", "port", "host"]);
+    if (!supported.has(name)) {
+      throw new DashboardUsageError(`Unknown option: --${name}`);
+    }
+    if (values.has(name)) {
+      throw new DashboardUsageError(`Option may be provided once: --${name}`);
+    }
+    const inline = separator === -1 ? undefined : token.slice(separator + 1);
+    const value = inline ?? args[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+      throw new DashboardUsageError(`Option requires a value: --${name}`);
+    }
+    values.set(name, value);
+    if (inline === undefined) index += 1;
+  }
+  const input = values.get("input");
+  if (input === undefined) {
+    throw new DashboardUsageError("Missing required option: --input");
+  }
+  const port = values.has("port") ? validPort(values.get("port")) : 0;
+  const host = values.get("host") ?? "127.0.0.1";
+  return {
+    inputDir: resolve(input),
+    renderingDir: values.has("rendering")
+      ? resolve(values.get("rendering"))
+      : undefined,
+    port,
+    host,
+    open: !noOpen,
+  };
+}
+function positiveInteger(value, name) {
+  const result = Number(value);
+  if (!Number.isSafeInteger(result) || result <= 0) {
+    throw new DashboardUsageError(
+      `--${name} must be a positive integer, got ${value}`,
+    );
+  }
+  return result;
+}
+function validPort(value) {
+  const result = Number(value);
+  if (!Number.isSafeInteger(result) || result < 0 || result > 65535) {
+    throw new DashboardUsageError(`--port must be 0-65535, got ${value}`);
+  }
+  return result;
+}
+async function pathExists(candidate) {
+  try {
+    await access(candidate, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function resolveRenderingDir(inputDir) {
+  if (path.basename(inputDir) === "rendering") {
+    return inputDir;
+  }
+  const candidates = [
+    join(inputDir, "rendering"),
+    join(inputDir, "generation", "rendering"),
+  ];
+  for (const candidate of candidates) {
+    if (await pathExists(candidate)) {
+      return candidate;
+    }
+  }
+  return candidates[0];
+}
+async function ensureDashboardHtml(renderingDir) {
+  await mkdir(renderingDir, { recursive: true });
+  const target = join(renderingDir, "dashboard.html");
+  try {
+    await access(DASHBOARD_TEMPLATE, constants.F_OK);
+  } catch {
+    throw new DashboardUsageError(
+      `Dashboard template not found: ${DASHBOARD_TEMPLATE}`,
+    );
+  }
+  await copyFile(DASHBOARD_TEMPLATE, target);
+}
+async function main(argv) {
+  let options;
+  try {
+    options = parseOptions(argv);
+  } catch (error) {
+    console.error(
+      `Error: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    console.error(USAGE);
+    return 2;
+  }
+  const renderingDir =
+    options.renderingDir ?? (await resolveRenderingDir(options.inputDir));
+  await ensureDashboardHtml(renderingDir);
+  const server = createStaticServer(renderingDir);
+  await server.listen(options.port, options.host);
+  const address = server.address();
+  if (address === null) {
+    throw new Error("Server did not bind to a socket");
+  }
+  const url = `http://${address.address}:${address.port}/dashboard.html`;
+  console.log(
+    JSON.stringify({ status: "starting", renderingDir, dashboard: url }),
+  );
+  if (options.open) {
+    try {
+      const { command, args } = buildOpenCommand(process.platform, url);
+      spawnSync(command, args, { stdio: "ignore" });
+    } catch (error) {
+      console.error(
+        `Could not open browser (${error instanceof Error ? error.message : String(error)}). Open ${url} manually.`,
+      );
+    }
+  }
+  process.once("SIGINT", async () => {
+    await server.close();
+    console.log("\nDashboard server stopped.");
+    process.exit(0);
+  });
+  return new Promise(() => {
+    // Keep the process alive until SIGINT.
+  });
+}
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  },
+);

package/skills/a2h-app-req-gen/scripts/reqgen/src/diagnostics.js

@@ -0,0 +1,104 @@
+import { createHash } from "node:crypto";
+import { defineDiagnostic } from "./contracts/index.js";
+function stageFor(category) {
+  switch (category) {
+    case "input":
+      return "configure";
+    case "environment":
+    case "gradle":
+    case "variant":
+      return "project-model";
+    case "manifest":
+    case "resources":
+    case "uast":
+      return "extract";
+    case "analysis":
+      return "normalize";
+    case "model":
+      return "req-text";
+    case "validation":
+      return "validate";
+  }
+}
+function contractCategory(category) {
+  switch (category) {
+    case "input":
+    case "variant":
+      return "configuration";
+    case "environment":
+    case "gradle":
+    case "manifest":
+    case "resources":
+    case "uast":
+      return "infrastructure";
+    case "model":
+      return "model";
+    case "analysis":
+    case "validation":
+      return "invariant";
+  }
+}
+function jsonValue(value) {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : String(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map(jsonValue);
+  }
+  if (typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, jsonValue(item)]),
+    );
+  }
+  return String(value);
+}
+function diagnosticId(code, stage, message) {
+  const digest = createHash("sha256")
+    .update(JSON.stringify({ code, stage, message }))
+    .digest("hex")
+    .slice(0, 20);
+  return `diagnostic:runtime/failure/${digest}`;
+}
+export class AnalysisFailure extends Error {
+  diagnostics;
+  constructor(message, diagnostics) {
+    super(message);
+    this.name = "AnalysisFailure";
+    this.diagnostics = diagnostics;
+  }
+}
+/**
+ * Compatibility boundary for infrastructure code. It now emits the same
+ * versioned Diagnostic contract that is serialized in the Stage 1 run report.
+ */
+export function hardFailure(code, category, message, remediation, details) {
+  const stage = stageFor(category);
+  const diagnostic = defineDiagnostic({
+    id: diagnosticId(code, stage, message),
+    code,
+    stage,
+    message,
+    ...(remediation ? { remediation } : {}),
+    ...(details
+      ? {
+          details: Object.fromEntries(
+            Object.entries(details).map(([key, value]) => [
+              key,
+              jsonValue(value),
+            ]),
+          ),
+        }
+      : {}),
+    disposition: "fail-run",
+    severity: "error",
+    category: contractCategory(category),
+  });
+  return new AnalysisFailure(message, [diagnostic]);
+}