@cleya/contributor-java-scip 0.0.0-stage → 1.0.0-next.0

package/dist/java-scip.contributor.d.ts

@@ -0,0 +1,28 @@
+import type { Contributor, ContributorContext } from "@cleya/config";
+import { type ScipFailure, type ScipGeneration } from "@cleya/contributor-scip";
+import type { regionTrace } from "@cleya/region-trace";
+import type { JavaScipOptions } from "./java-scip.types";
+import { type BuildTool } from "./jvm/build-process";
+import { type BinaryResolver } from "./requirements/binary.resolver";
+/** scip-java args for the build tool (Maven needs batch-mode + skip tests). */
+export declare const buildScipArgs: (buildTool: BuildTool, output: string) => string[];
+/**
+ * Generate a SCIP index for a JVM project: detect the build tool, verify the
+ * environment, run `scip-java`, and translate a failed build into a readable
+ * error. Exported on its own so it can be tested without contributor plumbing.
+ */
+export declare const runScipJava: (ctx: ContributorContext, options: JavaScipOptions, system: BinaryResolver) => Promise<ScipGeneration | ScipFailure>;
+/**
+ * An indexer for JVM (Gradle or Maven) projects, backed by `scip-java` (which
+ * must be on PATH, alongside a JDK >= 17 and a Gradle/Maven wrapper or system
+ * binary). Decoding the resulting SCIP index into domain files is delegated to
+ * the shared {@link scipContributor}.
+ *
+ * @param options - Contributor options; see {@link JavaScipOptions}.
+ * @param system - Host machine access; injected in tests.
+ * @returns A trace contributor that generates and decodes a SCIP index.
+ * @example
+ * javaScipContributor({ buildTool: "gradle" }).region.id; // "trace"
+ * javaScipContributor({ output: "artifacts/java.scip" }).id; // "java-scip-contributor"
+ */
+export declare function javaScipContributor(options?: JavaScipOptions, system?: BinaryResolver): Contributor<typeof regionTrace>;

package/dist/java-scip.index.d.ts

@@ -0,0 +1,3 @@
+export { javaScipContributor } from "./java-scip.contributor";
+export type { JavaScipOptions } from "./java-scip.types";
+export type { BuildTool } from "./jvm/build-process";

package/dist/java-scip.index.js

@@ -0,0 +1,226 @@
+// @bun
+// src/java-scip.contributor.ts
+import {
+  prepareScipOutput,
+  scipContributor
+} from "@cleya/contributor-scip";
+
+// src/jvm/build-process.ts
+import { existsSync } from "fs";
+import { join } from "path";
+
+// src/jvm/readable-error.ts
+class ReadableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ReadableError";
+  }
+}
+
+// src/jvm/build-process.ts
+var GRADLE_FILES = [
+  "build.gradle",
+  "build.gradle.kts",
+  "settings.gradle",
+  "settings.gradle.kts"
+];
+var MAVEN_FILES = ["pom.xml"];
+var JDK = [
+  /invalid source release/i,
+  /Unsupported class file major version/i,
+  /class file version/i
+];
+var DEPS = [/Could not resolve/i, /Could not find/i, /Non-resolvable/i];
+var TEST = [
+  /There were failing tests/i,
+  /Failed tests:/i,
+  /Tests run:.*(?:Failures|Errors): [1-9]/i
+];
+var COMPILE = [/BUILD FAILED/i, /compilation failed/i, /\berror:/i];
+var hasAny = (root, files) => files.some((file) => existsSync(join(root, file)));
+var hasAnyGradleFile = (root) => hasAny(root, GRADLE_FILES);
+var hasAnyMavenFile = (root) => hasAny(root, MAVEN_FILES);
+var resolveBuildTool = (root, override) => {
+  if (override)
+    return override;
+  const gradle = hasAnyGradleFile(root);
+  const maven = hasAnyMavenFile(root);
+  if (gradle && maven)
+    throw new ReadableError(`Both Gradle and Maven detected at ${root}. Choose the build tool to index:
+` + `  --build-tool gradle   (build.gradle, settings.gradle)
+` + "  --build-tool maven    (pom.xml)");
+  if (gradle)
+    return "gradle";
+  if (maven)
+    return "maven";
+  throw new ReadableError(`Neither Gradle nor Maven detected at ${root} ` + "(expected build.gradle[.kts]/settings.gradle[.kts] or pom.xml).");
+};
+var matchesAny = (text, signatures) => signatures.some((signature) => signature.test(text));
+var diagnose = (result, buildTool) => {
+  const out = `${result.stdout}
+${result.stderr}`;
+  const head = `Build ${buildTool} (scip-java) failed (exit ${result.exitCode}).`;
+  const cmd = `
+Command: ${result.command}`;
+  if (matchesAny(out, JDK))
+    return new ReadableError(`${head}
+Likely JDK mismatch: check that JAVA_HOME points to a JDK compatible with the project.${cmd}`);
+  if (matchesAny(out, DEPS))
+    return new ReadableError(`${head}
+Unresolved dependencies: check repository access (network / offline mode).${cmd}`);
+  if (matchesAny(out, TEST))
+    return new ReadableError(`${head}
+Test failures: the project compiled but some tests failed (see the logs above).${cmd}`);
+  if (matchesAny(out, COMPILE))
+    return new ReadableError(`${head}
+Compilation error: fix the build (see the logs above).${cmd}`);
+  return new ReadableError(`${head}
+See the output above.${cmd}`);
+};
+
+// src/requirements/requirement.ts
+import { existsSync as existsSync2 } from "fs";
+import { join as join2 } from "path";
+
+// src/requirements/version.utils.ts
+var versionParts = (version) => version.split(".").map((part) => Number.parseInt(part, 10) || 0);
+var parseVersion = (text) => {
+  const match = text.match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  return match ? match[0] : null;
+};
+var satisfiesMin = (version, minimum) => {
+  const actual = versionParts(version);
+  const required = versionParts(minimum);
+  for (let i = 0;i < Math.max(actual.length, required.length); i++) {
+    const actualPart = actual[i] ?? 0;
+    const requiredPart = required[i] ?? 0;
+    if (actualPart > requiredPart)
+      return true;
+    if (actualPart < requiredPart)
+      return false;
+  }
+  return true;
+};
+
+// src/requirements/requirement.ts
+var MIN_JDK = "17";
+var JDK_HINT = "install JDK Temurin 17/21";
+var SCIP_JAVA_HINT = "install scip-java \u2014 https://sourcegraph.github.io/scip-java/docs/getting-started.html";
+var BUILD_TOOL_HINT = "install the build tool or add its wrapper";
+var issue = (tool, installHint, reason = "not found in PATH") => ({ tool, reason, installHint });
+var requireBinary = (name, installHint) => async (ctx) => await ctx.system.resolve(name) ? null : issue(name, installHint);
+var scipJavaRequirement = requireBinary("scip-java", SCIP_JAVA_HINT);
+var jdkRequirement = async (ctx) => {
+  const java = await ctx.system.resolve("java", ["-version"]);
+  if (!java?.version)
+    return issue("java", JDK_HINT);
+  if (!satisfiesMin(java.version, MIN_JDK))
+    return issue("java", JDK_HINT, `version too old (detected ${java.version}, requires ${MIN_JDK}+)`);
+  return null;
+};
+var hasUsableBuildTool = async (buildTool, root, resolve) => {
+  const repoWrapper = buildTool === "gradle" ? "gradlew" : "mvnw";
+  const systemTool = buildTool === "gradle" ? "gradle" : "mvn";
+  if (existsSync2(join2(root, repoWrapper)))
+    return true;
+  return await resolve(systemTool) != null;
+};
+var buildToolRequirement = async (ctx) => {
+  if (await hasUsableBuildTool(ctx.buildTool, ctx.projectRoot, ctx.system.resolve))
+    return null;
+  const tool = ctx.buildTool === "gradle" ? "gradlew|gradle" : "mvnw|mvn";
+  return issue(tool, BUILD_TOOL_HINT);
+};
+var runRequirements = async (requirements, ctx) => {
+  const results = await Promise.all(requirements.map((r) => r(ctx)));
+  return results.filter((r) => r !== null);
+};
+var formatMissing = (issues, subject) => {
+  const lines = issues.map((i) => `  - ${i.tool}: ${i.reason} \u2192 ${i.installHint}`);
+  return `Missing requirements for ${subject}:
+${lines.join(`
+`)}`;
+};
+
+// src/requirements/index.ts
+var JAVA_SCIP_REQUIREMENTS = [
+  scipJavaRequirement,
+  jdkRequirement,
+  buildToolRequirement
+];
+
+// src/requirements/binary.resolver.ts
+var readVersion = async (binPath, args) => {
+  try {
+    const proc = Bun.spawn([binPath, ...args], {
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text()
+    ]);
+    if (await proc.exited !== 0)
+      return null;
+    return parseVersion(`${stdout}
+${stderr}`);
+  } catch {
+    return null;
+  }
+};
+var binaryResolver = {
+  resolve: async (name, versionArgs) => {
+    const binPath = Bun.which(name);
+    if (!binPath)
+      return null;
+    if (!versionArgs)
+      return { binPath, version: null };
+    return { binPath, version: await readVersion(binPath, versionArgs) };
+  }
+};
+
+// src/java-scip.contributor.ts
+var INDEXER_ID = "java-scip";
+var CONTRIBUTOR_ID = `${INDEXER_ID}-contributor`;
+var buildScipArgs = (buildTool, output) => {
+  const base = ["index", "--build-tool", buildTool, "--output", output];
+  if (buildTool === "maven")
+    return [...base, "--", "--batch-mode", "-DskipTests", "package"];
+  return base;
+};
+var runScipJava = async (ctx, options, system) => {
+  try {
+    const buildTool = resolveBuildTool(ctx.root, options.buildTool);
+    const issues = await runRequirements(JAVA_SCIP_REQUIREMENTS, {
+      projectRoot: ctx.root,
+      buildTool,
+      system
+    });
+    if (issues.length)
+      return { error: formatMissing(issues, "scip-java") };
+    const output = await prepareScipOutput(ctx, options.output);
+    const argv = ["scip-java", ...buildScipArgs(buildTool, output)];
+    const result = await ctx.exec({ argv, cwd: ctx.root });
+    if (result.code !== 0) {
+      const run = {
+        exitCode: result.code,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        command: argv.join(" ")
+      };
+      return { error: diagnose(run, buildTool).message };
+    }
+    return { scipPath: output };
+  } catch (e) {
+    return { error: e instanceof Error ? e.message : String(e) };
+  }
+};
+function javaScipContributor(options = {}, system = binaryResolver) {
+  return scipContributor({
+    id: CONTRIBUTOR_ID,
+    generate: (ctx) => runScipJava(ctx, options, system)
+  });
+}
+export {
+  javaScipContributor
+};

package/dist/java-scip.types.d.ts

@@ -0,0 +1,8 @@
+import type { BuildTool } from "./jvm/build-process";
+/** Options of `javaScipContributor`. */
+export interface JavaScipOptions {
+    /** Override relative to the workspace root. Defaults to `index.scip` in the contributor's artifacts directory under the config's `.cleya`. */
+    output?: string;
+    /** Force the build tool, skipping filesystem detection. */
+    buildTool?: BuildTool;
+}

package/dist/jvm/build-process.d.ts

@@ -0,0 +1,32 @@
+import { ReadableError } from "./readable-error";
+export type BuildTool = "gradle" | "maven";
+/** Captured result of a finished process run (shape `diagnose` needs). */
+export interface RunResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    command: string;
+}
+/**
+ * Resolve the build tool driving the project at `root`. `override` short-circuits
+ * file inspection. Throws a {@link ReadableError} when both tools are present
+ * (ambiguous) or neither is (nothing to build).
+ *
+ * @example
+ * resolveBuildTool("/repo")           // → "gradle"  (build.gradle present)
+ * resolveBuildTool("/repo", "maven")  // → "maven"   (override, no inspection)
+ * resolveBuildTool("/repo-with-both") // → throws ReadableError
+ */
+export declare const resolveBuildTool: (root: string, override?: BuildTool) => BuildTool;
+/**
+ * Translate a failed scip-java run into a user-readable error (best-effort).
+ * The output is matched against known failure signatures, most specific first;
+ * an unrecognized failure still yields an error pointing at the logs.
+ *
+ * @example
+ * diagnose({ exitCode: 1, stdout: "", stderr: "invalid source release: 17", command: "…" }, "gradle")
+ * // → ReadableError: "Build gradle (scip-java) failed (exit 1).
+ * //    Likely JDK mismatch: check that JAVA_HOME points to a JDK compatible with the project.
+ * //    Command: …"
+ */
+export declare const diagnose: (result: RunResult, buildTool: BuildTool) => ReadableError;

package/dist/jvm/readable-error.d.ts

@@ -0,0 +1,4 @@
+/** An error whose message is already formatted for the end user. */
+export declare class ReadableError extends Error {
+    constructor(message: string);
+}

package/dist/requirements/binary.resolver.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Read-only access to the host machine (PATH lookups, process output). The only
+ * impure module of the plugin — injected in tests.
+ */
+/** A binary found on PATH, with its version when one was asked for and read. */
+export interface ResolveResult {
+    /** Absolute path of the binary on PATH. */
+    binPath: string;
+    /** Version reported by the binary. Null when unasked, unrun, or unparseable. */
+    version: string | null;
+}
+export interface BinaryResolver {
+    /**
+     * Locates `name` on PATH. Null when `name` is absent.
+     *
+     * Reading a version costs a process launch — hundreds of milliseconds for a
+     * JVM launcher like `scip-java` — so it happens only on demand: pass the
+     * flags the binary answers to (`["--version"]` for most, `["-version"]` for
+     * `java`). Omit them for a presence check and `version` comes back null
+     * without anything being run.
+     */
+    resolve: (name: string, versionArgs?: string[]) => Promise<ResolveResult | null>;
+}
+/** Real system access: PATH lookup via Bun.which, version via a captured spawn. */
+export declare const binaryResolver: BinaryResolver;

package/dist/requirements/index.d.ts

@@ -0,0 +1,6 @@
+import { type Requirement } from "./requirement";
+/**
+ * The environment a scip-java run requires. Order only affects the order of the
+ * reported issues. Add a requirement in `requirement.ts` and list it here.
+ */
+export declare const JAVA_SCIP_REQUIREMENTS: Requirement[];

package/dist/requirements/requirement.d.ts

@@ -0,0 +1,45 @@
+import type { BuildTool } from "../jvm/build-process";
+import type { BinaryResolver } from "./binary.resolver";
+/**
+ * Every environment requirement a scip-java run has, and the machinery to run
+ * them. Each requirement owns its own policy and its own message — nothing else
+ * knows them. List them in JAVA_SCIP_REQUIREMENTS (index.ts).
+ */
+/** A single unmet environment requirement, reported uniformly. */
+export interface RequirementIssue {
+    tool: string;
+    reason: string;
+    installHint: string;
+}
+/** Everything a requirement may inspect. Requirements receive it; they take nothing else. */
+export interface RequirementContext {
+    projectRoot: string;
+    buildTool: BuildTool;
+    system: BinaryResolver;
+}
+/**
+ * One environment requirement. Returns the issue when unmet, null when
+ * satisfied.
+ */
+export type Requirement = (ctx: RequirementContext) => Promise<RequirementIssue | null>;
+/** Uniform issue constructor. */
+export declare const issue: (tool: string, installHint: string, reason?: string) => RequirementIssue;
+/** Requires a binary on PATH — the shape every binary presence check shares. */
+export declare const requireBinary: (name: string, installHint: string) => Requirement;
+/** Requires the `scip-java` binary on PATH. */
+export declare const scipJavaRequirement: Requirement;
+/**
+ * Requires a JDK >= 17 on PATH. Sole owner of the minimum-version policy —
+ * `version.utils` compares, but knows no minimum. `java` spells its version
+ * flag `-version`, not `--version`.
+ */
+export declare const jdkRequirement: Requirement;
+/** Requires a usable build tool: a repo wrapper, or the binary on PATH. */
+export declare const buildToolRequirement: Requirement;
+/**
+ * Run every requirement and collect what is missing, in declaration order. An
+ * empty array means the environment is ready.
+ */
+export declare const runRequirements: (requirements: Requirement[], ctx: RequirementContext) => Promise<RequirementIssue[]>;
+/** Render unmet requirements into one user-readable message. */
+export declare const formatMissing: (issues: RequirementIssue[], subject: string) => string;

package/dist/requirements/version.utils.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Version handling for noisy tool output: extracting a version from it, and
+ * comparing it to a minimum. Pure — no PATH, no process, no policy. Each
+ * requirement owns the minimum it enforces; this module only answers the
+ * comparison.
+ */
+/**
+ * Extract the first version-like token from noisy text.
+ *
+ * @example
+ * parseVersion('openjdk version "17.0.9" 2023-10-17') // → "17.0.9"
+ * parseVersion("command not found")                   // → null
+ */
+export declare const parseVersion: (text: string) => string | null;
+/**
+ * True when `version` >= `minimum`, compared part by part. A missing part
+ * counts as 0, so "17" satisfies "17.0.0".
+ *
+ * @example
+ * satisfiesMin("17.0.9", "17") // → true
+ * satisfiesMin("1.8.0", "17")  // → false (legacy 1.x numbering)
+ */
+export declare const satisfiesMin: (version: string, minimum: string) => boolean;

package/package.json

@@ -1,6 +1,37 @@
 {
-  "name": "@cleya/contributor-java-scip",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@cleya/contributor-java-scip",
+	"description": "Indexes Java symbols and their references",
+	"cleya": {
+		"category": "contributor"
+	},
+	"version": "1.0.0-next.0",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/java-scip.index.d.ts",
+			"default": "./dist/java-scip.index.js"
+		}
+	},
+	"types": "./dist/java-scip.index.d.ts",
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "bun build ./src/java-scip.index.ts --outdir dist --target bun --external @cleya/config --external @cleya/region-trace --external @cleya/contributor-scip && bunx tsc -p tsconfig.build.json"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@cleya/contributor-scip": "^1.0.0-next.0"
+	},
+	"peerDependencies": {
+		"@cleya/config": "1.0.0-next.0",
+		"@cleya/region-trace": "1.0.0-next.0",
+		"typescript": "^5"
+	},
+	"devDependencies": {
+		"@cleya/config": "1.0.0-next.0",
+		"@cleya/region-trace": "1.0.0-next.0"
+	}
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.