android2harmony 0.1.6 → 0.1.8

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

@@ -0,0 +1,398 @@
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_ANALYSIS_LIMITS, runStage1 } from "./pipeline/index.js";
+import { deriveCaseId, isValidCaseId } from "./core/stable-id.js";
+import {
+  ensureOutputDirectoryEmpty,
+  OutputDirectoryNotEmptyError,
+} from "./core/output-guard.js";
+import { parseResourceConfiguration } from "./project/resource-profile.js";
+export const CLI_USAGE = `Usage:
+  pnpm stage1 -- --project <android-project> \\
+    [--module <:application-module>] [--variant <build-variant>]
+
+Module and variant may be omitted only when the Gradle model has one choice.
+Stage 1 performs static analysis and deterministically writes req.md;
+it never accepts model or API options. Every run extracts the current project
+with the current analyzer; cached Raw JVM input and replay are intentionally
+unsupported.
+By default, output is written below .build/runs/<case-id>/<run-id>/.
+
+Optional:
+  --output <new-run-directory>              (must be empty or non-existent)
+  --locale <locale>                         (default: zh-CN)
+  --orientation <portrait|landscape>        (default: portrait)
+  --ui-mode <notnight|night>                (default: notnight)
+  --api-level <positive-integer>             (default: 36)
+  --density <density>                        (default: xhdpi)
+  --smallest-width-dp <positive-integer>     (default: 360)
+  --case-id <stable-case-id>
+  --run-id <run-id>
+  --init-script <path>
+  --analyzer-project <path>
+  --analyzer-artifact <path-relative-to-analyzer-project>
+  --gradle-timeout-ms <positive-integer>    per Gradle invocation (default: 600000)
+  --max-call-depth <positive-integer>
+  --max-callback-iterations <positive-integer>
+  --max-graph-states <positive-integer>
+
+Toolchain environment (optional):
+  REQGEN_PROJECT_GRADLE_EXECUTABLE       Target-project Gradle executor
+  REQGEN_PROJECT_JAVA_HOME               Target-project JDK
+  REQGEN_ANALYZER_GRADLE_EXECUTABLE      Reqgen analyzer Gradle executor
+  REQGEN_ANALYZER_JAVA_HOME              Reqgen analyzer JDK
+
+REQGEN_GRADLE_EXECUTABLE and JAVA_HOME remain shared fallbacks when a
+scope-specific value is not set.
+`;
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export class CliUsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliUsageError";
+  }
+}
+const allowedOptions = new Set([
+  "project",
+  "output",
+  "module",
+  "variant",
+  "locale",
+  "orientation",
+  "ui-mode",
+  "api-level",
+  "density",
+  "smallest-width-dp",
+  "case-id",
+  "run-id",
+  "init-script",
+  "analyzer-project",
+  "analyzer-artifact",
+  "gradle-timeout-ms",
+  "max-call-depth",
+  "max-callback-iterations",
+  "max-graph-states",
+]);
+function parseOptions(args) {
+  const values = new Map();
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (!token.startsWith("--")) {
+      throw new CliUsageError(`Unexpected argument: ${token}`);
+    }
+    const separator = token.indexOf("=");
+    const name = token.slice(2, separator === -1 ? undefined : separator);
+    if (!allowedOptions.has(name)) {
+      throw new CliUsageError(`Unknown option: --${name}`);
+    }
+    if (values.has(name)) {
+      throw new CliUsageError(`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.trim().length === 0 ||
+      (inline === undefined && value.startsWith("--"))
+    ) {
+      throw new CliUsageError(`Option requires a value: --${name}`);
+    }
+    values.set(name, value);
+    if (inline === undefined) {
+      index += 1;
+    }
+  }
+  return values;
+}
+function generatedRunId() {
+  const timestamp = new Date()
+    .toISOString()
+    .replace(/[-:]/gu, "")
+    .replace(/\.\d{3}Z$/u, "Z");
+  return `${timestamp}-${randomUUID().slice(0, 8)}`;
+}
+function safePathSegment(value, fallback) {
+  const sanitized = value
+    .trim()
+    .normalize("NFC")
+    .replace(/[^\p{Letter}\p{Number}._-]+/gu, "-")
+    .replace(/^-+|-+$/gu, "");
+  return sanitized.length === 0 || sanitized === "." || sanitized === ".."
+    ? fallback
+    : sanitized;
+}
+function required(values, name) {
+  const value = values.get(name);
+  if (value === undefined) {
+    throw new CliUsageError(`Missing required option: --${name}`);
+  }
+  return value;
+}
+function positiveInteger(value, option) {
+  const result = Number(value);
+  if (!Number.isSafeInteger(result) || result <= 0) {
+    throw new CliUsageError(
+      `--${option} must be a positive integer, got ${value}`,
+    );
+  }
+  return result;
+}
+export function parseStage1Arguments(args) {
+  const values = parseOptions(args);
+  const projectRoot = resolve(required(values, "project"));
+  let resourceConfiguration;
+  try {
+    resourceConfiguration = parseResourceConfiguration({
+      ...(values.has("locale") ? { locale: required(values, "locale") } : {}),
+      ...(values.has("orientation")
+        ? { orientation: required(values, "orientation") }
+        : {}),
+      ...(values.has("ui-mode") ? { uiMode: required(values, "ui-mode") } : {}),
+      ...(values.has("api-level")
+        ? { apiLevel: required(values, "api-level") }
+        : {}),
+      ...(values.has("density")
+        ? { density: required(values, "density") }
+        : {}),
+      ...(values.has("smallest-width-dp")
+        ? {
+            smallestWidthDp: required(values, "smallest-width-dp"),
+          }
+        : {}),
+    });
+  } catch (error) {
+    throw new CliUsageError(
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+  const limits = {
+    maxCallDepth: values.has("max-call-depth")
+      ? positiveInteger(required(values, "max-call-depth"), "max-call-depth")
+      : DEFAULT_ANALYSIS_LIMITS.maxCallDepth,
+    maxCallbackIterations: values.has("max-callback-iterations")
+      ? positiveInteger(
+          required(values, "max-callback-iterations"),
+          "max-callback-iterations",
+        )
+      : DEFAULT_ANALYSIS_LIMITS.maxCallbackIterations,
+    maxGraphStates: values.has("max-graph-states")
+      ? positiveInteger(
+          required(values, "max-graph-states"),
+          "max-graph-states",
+        )
+      : DEFAULT_ANALYSIS_LIMITS.maxGraphStates,
+  };
+  const explicitCaseId = values.has("case-id")
+    ? required(values, "case-id")
+    : undefined;
+  if (explicitCaseId !== undefined && !isValidCaseId(explicitCaseId)) {
+    throw new CliUsageError(
+      "--case-id must start with a lowercase ASCII letter or digit and " +
+        "contain only lowercase ASCII letters, digits, '.', '_', or '-'",
+    );
+  }
+  const caseId = explicitCaseId ?? deriveCaseId(basename(projectRoot));
+  const needsGeneratedRunId = !values.has("output") && !values.has("run-id");
+  const runId = values.has("run-id")
+    ? required(values, "run-id")
+    : needsGeneratedRunId
+      ? generatedRunId()
+      : undefined;
+  const outputExplicit = values.has("output");
+  const outputDirectory = outputExplicit
+    ? resolve(required(values, "output"))
+    : join(
+        PACKAGE_ROOT,
+        ".build",
+        "runs",
+        safePathSegment(caseId, "case"),
+        safePathSegment(runId ?? generatedRunId(), "run"),
+      );
+  const gradleTimeoutMs = values.has("gradle-timeout-ms")
+    ? positiveInteger(
+        required(values, "gradle-timeout-ms"),
+        "gradle-timeout-ms",
+      )
+    : undefined;
+  return {
+    options: {
+      projectRoot,
+      outputDirectory,
+      resourceConfiguration,
+      limits,
+      ...(values.has("module")
+        ? { applicationModulePath: required(values, "module") }
+        : {}),
+      ...(values.has("variant")
+        ? { variantName: required(values, "variant") }
+        : {}),
+      caseId,
+      ...(runId === undefined ? {} : { runId }),
+      ...(values.has("init-script")
+        ? { initScriptPath: resolve(required(values, "init-script")) }
+        : {}),
+      ...(values.has("analyzer-project")
+        ? {
+            analyzerProjectRoot: resolve(required(values, "analyzer-project")),
+          }
+        : {}),
+      ...(values.has("analyzer-artifact")
+        ? { analyzerArtifactPath: required(values, "analyzer-artifact") }
+        : {}),
+      ...(gradleTimeoutMs === undefined
+        ? {}
+        : {
+            projectGradle: { timeoutMs: gradleTimeoutMs },
+            analyzerGradle: { timeoutMs: gradleTimeoutMs },
+          }),
+    },
+    outputExplicit,
+  };
+}
+const defaultIo = {
+  stdout: (text) => process.stdout.write(text),
+  stderr: (text) => process.stderr.write(text),
+};
+const defaultRuntime = {
+  environment: process.env,
+};
+function durationText(elapsedMs) {
+  return elapsedMs < 1_000
+    ? `${elapsedMs} ms`
+    : `${(elapsedMs / 1_000).toFixed(1)} s`;
+}
+function progressLine(event) {
+  const prefix = `[Stage ${event.index}/${event.total}] ${event.label}`;
+  if (event.status === "started") {
+    return `${prefix}...\n`;
+  }
+  return `${prefix} ${event.status} in ${durationText(event.elapsedMs ?? 0)}.\n`;
+}
+function streamedGradleOptions(scope, options, io, runtimeEnvironment) {
+  const environment = {
+    ...runtimeEnvironment,
+    ...options?.environment,
+  };
+  const prefix = scope === "project" ? "REQGEN_PROJECT" : "REQGEN_ANALYZER";
+  const scopedExecutable = environment[`${prefix}_GRADLE_EXECUTABLE`];
+  const scopedJavaHome = environment[`${prefix}_JAVA_HOME`];
+  const executable =
+    options?.executable ??
+    scopedExecutable ??
+    environment.REQGEN_GRADLE_EXECUTABLE;
+  environment.REQGEN_GRADLE_SCOPE = scope;
+  if (scopedJavaHome !== undefined && scopedJavaHome.trim().length > 0) {
+    environment.JAVA_HOME = scopedJavaHome;
+  }
+  const existingStdout = options?.onStdout;
+  const existingStderr = options?.onStderr;
+  return {
+    ...options,
+    ...(executable === undefined ? {} : { executable }),
+    environment,
+    onStdout: (chunk) => {
+      existingStdout?.(chunk);
+      io.stdout(chunk);
+    },
+    onStderr: (chunk) => {
+      existingStderr?.(chunk);
+      io.stderr(chunk);
+    },
+  };
+}
+export async function runCli(
+  argv,
+  dependencies = { runStage1 },
+  io = defaultIo,
+  runtime = defaultRuntime,
+) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    io.stdout(CLI_USAGE);
+    return 0;
+  }
+  const [command, ...rawArgs] = argv;
+  if (command !== "stage1") {
+    io.stderr(
+      `${command ? `Unknown command: ${command}\n\n` : ""}${CLI_USAGE}`,
+    );
+    return 2;
+  }
+  const args = rawArgs[0] === "--" ? rawArgs.slice(1) : rawArgs;
+  let parsed;
+  try {
+    parsed = parseStage1Arguments(args);
+  } catch (error) {
+    io.stderr(
+      `${error instanceof Error ? error.message : String(error)}\n\n${CLI_USAGE}`,
+    );
+    return 2;
+  }
+  const { options } = parsed;
+  // Guard: refuse to overwrite an existing output directory when the user
+  // explicitly set --output.  Auto-generated default paths already embed a
+  // unique timestamp-based run-id and are never guarded.
+  if (parsed.outputExplicit) {
+    try {
+      await ensureOutputDirectoryEmpty(options.outputDirectory);
+    } catch (error) {
+      if (error instanceof OutputDirectoryNotEmptyError) {
+        io.stderr(error.message + "\n");
+        return 2;
+      }
+      throw error;
+    }
+  }
+  try {
+    const existingProgress = options.onProgress;
+    const result = await dependencies.runStage1({
+      ...options,
+      projectGradle: streamedGradleOptions(
+        "project",
+        options.projectGradle,
+        io,
+        runtime.environment,
+      ),
+      analyzerGradle: streamedGradleOptions(
+        "analyzer",
+        options.analyzerGradle,
+        io,
+        runtime.environment,
+      ),
+      onProgress: (event) => {
+        existingProgress?.(event);
+        io.stderr(progressLine(event));
+      },
+    });
+    if (result.report.status === "succeeded") {
+      const publication = result.report.publishable
+        ? "publishable; deterministic REQ draft generated"
+        : "semantic quality incomplete; deterministic REQ draft generated for review";
+      io.stdout(
+        `Stage 1 succeeded (${publication}): ${result.outputDirectory}\n` +
+          `Target: ${result.report.target.applicationModule}/` +
+          `${result.report.target.buildVariant}\n` +
+          `Unresolved: ${result.coverage.counts.unresolved}\n` +
+          `Draft: ${join(result.outputDirectory, "generation", "req.draft.md")}\n`,
+      );
+      return 0;
+    }
+    io.stderr(
+      `Stage 1 failed; partial facts are not publishable: ${result.outputDirectory}\n${result.report.diagnostics
+        .map((diagnostic) => `${diagnostic.code}: ${diagnostic.message}`)
+        .join("\n")}\n`,
+    );
+    return 1;
+  } catch (error) {
+    io.stderr(
+      `Unable to write the Stage 1 failure report: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    return 1;
+  }
+}
+const isDirectExecution =
+  process.argv[1] !== undefined &&
+  resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+if (isDirectExecution) {
+  process.exitCode = await runCli(process.argv.slice(2));
+}

package/skills/a2h-app-req-gen/scripts/reqgen/src/contracts/area-graph.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,16 @@
+export const semanticIdentityKinds = [
+  "application",
+  "variant",
+  "component",
+  "symbol",
+  "resource",
+  "route",
+  "container",
+  "control",
+  "callback",
+  "state",
+  "entry",
+  "external-target",
+  "semantic-position",
+  "semantic-key",
+];

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

@@ -0,0 +1,10 @@
+export const DIAGNOSTIC_CONTRACT_VERSION = "1.0.0";
+export function defineDiagnostic(input) {
+  return {
+    ...input,
+    contractVersion: DIAGNOSTIC_CONTRACT_VERSION,
+  };
+}
+export function diagnosticFailsRun(diagnostic) {
+  return diagnostic.disposition === "fail-run";
+}

package/skills/a2h-app-req-gen/scripts/reqgen/src/contracts/gap-audit.js

@@ -0,0 +1,14 @@
+export const GAP_AUDIT_CONTRACT_VERSION = "1.0.0";
+export const gapAuditCategoryIds = [
+  "manifest-components",
+  "manifest-entries",
+  "actionable-xml-controls",
+  "resolved-listener-interactions",
+  "resolved-compose-controls",
+  "resolved-compose-surfaces",
+  "resolved-compose-ui",
+  "resolved-navigation-calls",
+  "resolved-pager-tab-calls",
+  "resolved-async-calls",
+  "other-resolved-calls",
+];

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

@@ -0,0 +1,11 @@
+export * from "./artifact.js";
+export * from "./area-graph.js";
+export * from "./common.js";
+export * from "./diagnostic.js";
+export * from "./gap-audit.js";
+export * from "./name-traceability.js";
+export * from "./raw-fact.js";
+export * from "./req-model.js";
+export * from "./run.js";
+export * from "./semantic-completeness.js";
+export * from "./source-facts.js";

package/skills/a2h-app-req-gen/scripts/reqgen/src/contracts/name-traceability.js

@@ -0,0 +1,26 @@
+export const NAME_TRACEABILITY_CONTRACT_VERSION = "1.0.0";
+export function nameTraceKey(kind, ref) {
+  return `${kind}:${ref}`;
+}
+export function buildNameTraceLookup(entries) {
+  return new Map(
+    entries.map((entry) => [
+      nameTraceKey(entry.entityKind, entry.entityRef),
+      entry,
+    ]),
+  );
+}
+/**
+ * Strategies that read real, user-visible UI text — never a translation
+ * candidate (agent-render) and never a code Symbol (dump). Anything else
+ * (component-identifier, resource-id, symbol, icon-resource,
+ * dynamic-list-item) is code/structural in origin and may happen to be
+ * English purely because the identifier is.
+ */
+export const LITERAL_NAME_STRATEGIES = new Set([
+  "visible-title",
+  "visible-text",
+  "content-description",
+  "associated-label",
+  "variant-display-name",
+]);

package/skills/a2h-app-req-gen/scripts/reqgen/src/contracts/raw-fact.js

@@ -0,0 +1,40 @@
+export const RAW_FACT_CONTRACT_VERSION = "1.0.0";
+export const rawFactKinds = [
+  "component",
+  "component-variant",
+  "entry-point",
+  "resource-value",
+  "ui-element",
+  "ui-property",
+  "container-binding",
+  "callback",
+  "interaction-binding",
+  "callback-flow",
+  "condition",
+  "behavior-effect",
+  "navigation-target",
+];
+function assertNonBlank(value, field) {
+  if (value.trim().length === 0) {
+    throw new Error(`${field} must not be blank`);
+  }
+}
+export function defineRawFact(input) {
+  input.identity.forEach((part, index) =>
+    assertNonBlank(part.value, `identity[${index}].value`),
+  );
+  input.evidence.forEach((location, index) => {
+    assertNonBlank(location.path, `evidence[${index}].path`);
+    assertNonBlank(location.anchor, `evidence[${index}].anchor`);
+    if (
+      location.range.startLine < 1 ||
+      location.range.endLine < location.range.startLine
+    ) {
+      throw new Error(`evidence[${index}].range is invalid`);
+    }
+  });
+  return {
+    ...input,
+    contractVersion: RAW_FACT_CONTRACT_VERSION,
+  };
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,19 @@
+export const RUN_CONTRACT_VERSION = "1.0.0";
+export const STAGE1_COVERAGE_VERSION = "1.0.0";
+export const stage1CoverageStageNames = [
+  "projectModel",
+  "androidXml",
+  "jvm",
+  "normalize",
+  "graph",
+  "reqModel",
+];
+export function defineRunRequest(input) {
+  return {
+    ...input,
+    contractVersion: RUN_CONTRACT_VERSION,
+  };
+}
+export function runCanPublish(report) {
+  return report.status === "succeeded" && report.publishable;
+}

package/skills/a2h-app-req-gen/scripts/reqgen/src/contracts/semantic-completeness.js

@@ -0,0 +1,11 @@
+export const semanticCompletenessValues = [
+  "complete",
+  "incomplete-known",
+  "limited",
+];
+export const semanticCandidateStatuses = [
+  "recognized",
+  "unresolved",
+  "excluded-with-reason",
+  "limited",
+];

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

@@ -0,0 +1 @@
+export {};

package/skills/a2h-app-req-gen/scripts/reqgen/src/core/output-guard.js

@@ -0,0 +1,41 @@
+import { readdir } from "node:fs/promises";
+/**
+ * Fail-fast guard: when --output is explicitly provided, refuse to write into
+ * a directory that already contains results — this prevents accidentally
+ * overwriting a previous run's output.  The check only applies when the user
+ * explicitly sets --output; auto-generated default paths are never guarded
+ * because they already include a unique run-id timestamp.
+ *
+ * Snapshot mode (stage2 --snapshot) is exempt: it must be able to read
+ * existing output.json files from a prior rendering pass.
+ */
+export class OutputDirectoryNotEmptyError extends Error {
+  constructor(outputDir) {
+    super(
+      `Output directory is not empty: ${outputDir}\n` +
+        `Refusing to overwrite existing results.  Either:\n` +
+        `  - Choose a different --output path, or\n` +
+        `  - Delete / clear the directory first, then re-run.`,
+    );
+    this.name = "OutputDirectoryNotEmptyError";
+  }
+}
+/**
+ * Throws {@link OutputDirectoryNotEmptyError} if `outputDir` exists and
+ * contains at least one entry (file or subdirectory).  Does nothing when the
+ * directory does not exist yet or is empty.
+ */
+export async function ensureOutputDirectoryEmpty(outputDir) {
+  let entries;
+  try {
+    entries = await readdir(outputDir);
+  } catch (error) {
+    // Directory doesn't exist — that's fine, it'll be created downstream.
+    const code = error?.code;
+    if (code === "ENOENT" || code === "ENOTDIR") return;
+    throw error;
+  }
+  if (entries.length > 0) {
+    throw new OutputDirectoryNotEmptyError(outputDir);
+  }
+}