@groma/scanner-java 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gavrilescu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@groma/scanner-java",
+  "version": "0.1.0",
+  "description": "Java compiler and project evidence; framework runtime use is not verified.",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "groma": {
+    "scanner": {
+      "id": "java",
+      "entry": "./src/index.js",
+      "discovery": {
+        "technologies": [
+          "java"
+        ],
+        "rules": [
+          {
+            "type": "xml",
+            "files": [
+              "**/pom.xml"
+            ],
+            "technology": "java",
+            "kind": "language",
+            "versionTags": [
+              "java.version",
+              "maven.compiler.release",
+              "maven.compiler.source"
+            ],
+            "declaration": "Maven project; Java version unresolved"
+          },
+          {
+            "type": "xml",
+            "files": [
+              "**/pom.xml"
+            ],
+            "technology": "spring-boot",
+            "kind": "framework",
+            "versionTags": [],
+            "when": {
+              "tag": "groupId",
+              "equals": "org.springframework.boot"
+            },
+            "declaration": "org.springframework.boot declaration; runtime use unverified"
+          }
+        ],
+        "compatibility": {
+          "groma": "^0.3.0",
+          "technologyVersions": {
+            "java": "25.0.0"
+          }
+        }
+      }
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MrLesk/Groma.md.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,428 @@
+// @bun
+// plugins/scanners/java/src/adapter.ts
+import { fileURLToPath } from "url";
+import path3 from "path";
+
+// packages/scanner/src/index.ts
+function compare(...values) {
+  return values.join("\x00");
+}
+function uniqueBy(values, key, label) {
+  const seen = new Set;
+  for (const value of values) {
+    const id = key(value);
+    if (seen.has(id))
+      throw new Error(`duplicate ${label}: ${id}`);
+    seen.add(id);
+  }
+  return [...values].sort((left, right) => key(left).localeCompare(key(right)));
+}
+function createScanObservation(input) {
+  const roots = validateRoots(input.roots);
+  const rootIds = new Set(roots.map((root) => root.id));
+  const files = uniqueBy(input.files.map((file) => ({
+    ...file,
+    roots: [...new Set(file.roots)].sort(),
+    symbols: [...new Map(file.symbols.map((symbol) => [
+      compare(symbol.id, symbol.kind),
+      symbol
+    ])).values()].sort((left, right) => {
+      return compare(left.id, left.kind).localeCompare(compare(right.id, right.kind));
+    })
+  })), (file) => file.file, "file path");
+  const filePaths = new Set(files.map((file) => file.file));
+  for (const file of files) {
+    if (file.roots.length === 0)
+      throw new Error(`file has no root: ${file.file}`);
+    for (const root of file.roots) {
+      if (!rootIds.has(root))
+        throw new Error(`file references unknown root: ${root}`);
+    }
+  }
+  for (const diagnostic of input.diagnostics)
+    diagnosticLocation(diagnostic);
+  return {
+    schemaVersion: 1,
+    scanner: input.scanner,
+    roots,
+    files,
+    ...operationEvidence(input, filePaths),
+    diagnostics: [...new Map(input.diagnostics.map((diagnostic) => [
+      diagnosticKey(diagnostic),
+      diagnostic
+    ])).values()].sort((left, right) => {
+      return diagnosticKey(left).localeCompare(diagnosticKey(right));
+    })
+  };
+}
+function validateRoots(input) {
+  const roots = uniqueBy(input, (root) => root.id, "root id");
+  const byId = new Map(roots.map((root) => [root.id, root]));
+  for (const root of roots) {
+    const visited = new Set([root.id]);
+    let parent = root.parent;
+    while (parent !== undefined) {
+      if (visited.has(parent))
+        throw new Error(`root hierarchy contains a cycle: ${parent}`);
+      visited.add(parent);
+      const ancestor = byId.get(parent);
+      if (ancestor === undefined)
+        throw new Error(`root references unknown parent: ${parent}`);
+      parent = ancestor.parent;
+    }
+  }
+  return roots;
+}
+function diagnosticKey(diagnostic) {
+  return compare(diagnostic.severity, diagnostic.code, diagnostic.message, diagnostic.file ?? "", String(diagnostic.line ?? ""));
+}
+function diagnosticLocation(value) {
+  if (value.line !== undefined && (!Number.isInteger(value.line) || Number(value.line) < 1)) {
+    throw new Error("diagnostic.line must be a positive integer");
+  }
+  return {
+    ...value.file === undefined ? {} : { file: string(value.file, "diagnostic.file") },
+    ...value.line === undefined ? {} : { line: Number(value.line) }
+  };
+}
+function object(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value;
+}
+function string(value, label) {
+  if (typeof value !== "string")
+    throw new Error(`${label} must be a string`);
+  return value;
+}
+function array(value, label) {
+  if (!Array.isArray(value))
+    throw new Error(`${label} must be an array`);
+  return value;
+}
+function parseScanObservation(source) {
+  const value = object(JSON.parse(source), "observation");
+  if (value.schemaVersion !== 1)
+    throw new Error("unsupported scanner schema");
+  const scanner = object(value.scanner, "scanner");
+  return createScanObservation({
+    scanner: {
+      id: string(scanner.id, "scanner.id"),
+      technology: string(scanner.technology, "scanner.technology"),
+      engine: string(scanner.engine, "scanner.engine"),
+      engineVersion: string(scanner.engineVersion, "scanner.engineVersion")
+    },
+    ...parseOperations(value),
+    roots: array(value.roots, "roots").map((entry) => {
+      const root = object(entry, "root");
+      return {
+        id: string(root.id, "root.id"),
+        kind: string(root.kind, "root.kind"),
+        name: string(root.name, "root.name"),
+        ...root.file === undefined ? {} : { file: string(root.file, "root.file") },
+        ...root.parent === undefined ? {} : { parent: string(root.parent, "root.parent") }
+      };
+    }),
+    files: array(value.files, "files").map((entry, index) => {
+      const file = object(entry, `files[${index}]`);
+      return {
+        file: string(file.file, `files[${index}].file`),
+        roots: array(file.roots, "file.roots").map((root) => string(root, "file.root")),
+        symbols: array(file.symbols, `files[${index}].symbols`).map((entry, symbolIndex) => {
+          const symbol = object(entry, `files[${index}].symbols[${symbolIndex}]`);
+          return {
+            id: string(symbol.id, "symbol.id"),
+            name: string(symbol.name, "symbol.name"),
+            kind: string(symbol.kind, "symbol.kind")
+          };
+        })
+      };
+    }),
+    diagnostics: array(value.diagnostics, "diagnostics").map((entry, index) => {
+      const diagnostic = object(entry, `diagnostics[${index}]`);
+      return {
+        severity: string(diagnostic.severity, `diagnostics[${index}].severity`),
+        code: string(diagnostic.code, `diagnostics[${index}].code`),
+        message: string(diagnostic.message, `diagnostics[${index}].message`),
+        ...diagnosticLocation(diagnostic)
+      };
+    })
+  });
+}
+function parseOperations(value) {
+  if (value.operations === undefined) {
+    if (value.invocations !== undefined)
+      throw new Error("invocations require operation declarations");
+    return {};
+  }
+  const operations = array(value.operations, "operations").map((entry) => {
+    const operation = object(entry, "operation");
+    return {
+      id: string(operation.id, "operation.id"),
+      file: string(operation.file, "operation.file"),
+      name: string(operation.name, "operation.name"),
+      ...sourcePosition(operation.position),
+      ...operationTokens(operation)
+    };
+  });
+  const invocations = array(value.invocations, "invocations").map((entry) => {
+    const invocation = object(entry, "invocation");
+    if (typeof invocation.unresolved !== "boolean")
+      throw new Error("invocation.unresolved must be a boolean");
+    if (!Number.isInteger(invocation.line) || Number(invocation.line) < 1)
+      throw new Error("invocation.line must be a positive integer");
+    const binding = invocation.binding === undefined ? undefined : object(invocation.binding, "invocation.binding");
+    if (binding && (!Number.isInteger(binding.line) || Number(binding.line) < 1))
+      throw new Error("binding.line must be a positive integer");
+    return {
+      source: string(invocation.source, "invocation.source"),
+      targets: array(invocation.targets, "invocation.targets").map((target) => string(target, "invocation.target")),
+      unresolved: invocation.unresolved,
+      line: Number(invocation.line),
+      ...sourcePosition(invocation.position),
+      ...invocation.member === undefined ? {} : { member: string(invocation.member, "invocation.member") },
+      ...binding === undefined ? {} : { binding: { file: string(binding.file, "binding.file"), line: Number(binding.line), ...sourcePosition(binding.position) } }
+    };
+  });
+  return { operations, invocations };
+}
+function operationEvidence(input, files) {
+  if (input.operations === undefined && input.invocations !== undefined)
+    throw new Error("invocations require operation declarations");
+  if (input.operations === undefined)
+    return {};
+  const operations = uniqueBy(input.operations, (operation) => operation.id, "operation id");
+  const ids = new Set(operations.map((operation) => operation.id));
+  for (const operation of operations) {
+    if (!files.has(operation.file))
+      throw new Error(`operation references unknown file: ${operation.file}`);
+    sourcePosition(operation.position);
+    validateOperationTokens(operation);
+  }
+  const invocations = input.invocations ?? [];
+  for (const invocation of invocations)
+    validateInvocation(invocation, ids, files);
+  return { operations, invocations };
+}
+function operationTokens(operation) {
+  if (operation.tokens === undefined) {
+    if (operation.startLine !== undefined || operation.endLine !== undefined) {
+      throw new Error("operation range requires tokens");
+    }
+    return {};
+  }
+  if (operation.startLine === undefined || operation.endLine === undefined) {
+    throw new Error("operation tokens require a source range");
+  }
+  if (!Number.isInteger(operation.startLine) || Number(operation.startLine) < 1) {
+    throw new Error("operation.startLine must be a positive integer");
+  }
+  if (!Number.isInteger(operation.endLine) || Number(operation.endLine) < 1) {
+    throw new Error("operation.endLine must be a positive integer");
+  }
+  const startLine = Number(operation.startLine);
+  const endLine = Number(operation.endLine);
+  if (endLine < startLine)
+    throw new Error("operation.endLine must be at or after startLine");
+  return {
+    startLine,
+    endLine,
+    tokens: array(operation.tokens, "operation.tokens").map((token) => string(token, "operation.token"))
+  };
+}
+function validateOperationTokens(operation) {
+  operationTokens({
+    tokens: operation.tokens,
+    startLine: operation.startLine,
+    endLine: operation.endLine
+  });
+}
+function validateInvocation(invocation, ids, files) {
+  sourcePosition(invocation.position);
+  sourcePosition(invocation.binding?.position);
+  if (!invocation.targets.length && !invocation.unresolved)
+    throw new Error("an empty target set must be unresolved");
+  if (!ids.has(invocation.source) || invocation.targets.some((target) => !ids.has(target))) {
+    throw new Error("invocation references unknown operation");
+  }
+  if (invocation.binding && !files.has(invocation.binding.file))
+    throw new Error("invocation binding references unknown file");
+}
+function sourcePosition(position) {
+  if (position === undefined)
+    return {};
+  if (!Number.isInteger(position) || Number(position) < 0)
+    throw new Error("source position must be a non-negative integer");
+  return { position: Number(position) };
+}
+
+// plugins/scanners/java/src/maven.ts
+import { access, mkdtemp, readFile, readdir, realpath, rm } from "fs/promises";
+import os from "os";
+import path2 from "path";
+
+// plugins/scanners/java/src/process.ts
+import { execFile } from "child_process";
+import path from "path";
+function javaCommand() {
+  const executable = process.platform === "win32" ? "java.exe" : "java";
+  return process.env.JAVA_HOME ? path.join(process.env.JAVA_HOME, "bin", executable) : executable;
+}
+function run(command, args, root, input = "", timeout = 120000) {
+  return new Promise((resolve, reject) => {
+    const child = execFile(command, args, {
+      cwd: root,
+      encoding: "utf8",
+      timeout,
+      killSignal: "SIGKILL",
+      maxBuffer: 64 * 1024 * 1024,
+      windowsVerbatimArguments: process.platform === "win32" && path.basename(command).toLowerCase() === "cmd.exe"
+    }, (error, stdout, stderr) => {
+      if (error)
+        reject(new Error(stderr.trim() || stdout.trim() || error.message));
+      else
+        resolve(stdout);
+    });
+    child.stdin?.on("error", () => {});
+    child.stdin?.end(input);
+  });
+}
+function mavenInvocation(command, args, platform = process.platform) {
+  if (platform !== "win32" || !/\.(cmd|bat)$/i.test(command))
+    return [command, args];
+  return [process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", `"${[command, ...args].map((value) => `"${value}"`).join(" ")}"`]];
+}
+
+// plugins/scanners/java/src/maven.ts
+async function exists(file) {
+  try {
+    await access(file);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return false;
+    throw error;
+  }
+}
+async function collect(root, directory) {
+  const files = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const file = path2.join(directory, entry.name);
+    if (entry.isDirectory())
+      files.push(...await collect(root, file));
+    else if (entry.isFile() && file.endsWith(".java"))
+      files.push(path2.relative(root, file).split(path2.sep).join("/"));
+  }
+  return files.sort();
+}
+async function mavenCommand(root) {
+  const wrapper = path2.join(root, process.platform === "win32" ? "mvnw.cmd" : "mvnw");
+  return await exists(wrapper) ? wrapper : process.platform === "win32" ? "mvn.cmd" : "mvn";
+}
+var mavenGoals = [
+  "org.apache.maven.plugins:maven-help-plugin:3.5.1:effective-pom",
+  "org.apache.maven.plugins:maven-dependency-plugin:3.9.0:build-classpath"
+];
+async function readJavaInput(repositoryRoot, java, worker, maven) {
+  const root = await realpath(repositoryRoot);
+  if (!await exists(path2.join(root, "pom.xml"))) {
+    throw new Error("JAVA_UNSUPPORTED_BUILD: The Java scanner supports a root single-module Maven pom.xml. Gradle and other build arrangements are not supported.");
+  }
+  const temporary = await mkdtemp(path2.join(os.tmpdir(), "groma-java-model-"));
+  try {
+    const model = path2.join(temporary, "pom.xml");
+    const classpath = path2.join(temporary, "classpath.txt");
+    const command = maven ?? await mavenCommand(root);
+    const args = [
+      "--offline",
+      "--batch-mode",
+      "--no-transfer-progress",
+      "--non-recursive",
+      ...mavenGoals,
+      `-Doutput=${model}`,
+      `-Dmdep.outputFile=${classpath}`,
+      "-DincludeScope=compile"
+    ];
+    try {
+      await run(...mavenInvocation(command, args), root);
+    } catch (error) {
+      throw new Error(`JAVA_MAVEN_PREPARATION: Install the project JDK and Maven (or use its wrapper), then run ${command} ${mavenGoals.join(" ")} -DincludeScope=compile once with dependency access. Scans use Maven offline. ${error instanceof Error ? error.message : error}`);
+    }
+    const exported = JSON.parse(await run(java, ["-jar", worker, "model", model], root));
+    const files = await collect(root, exported.sourceRoot);
+    if (!files.length)
+      throw new Error("JAVA_EMPTY_SOURCE_SET: Maven main source directory contains no Java sources.");
+    if (files.some((file) => file.endsWith("module-info.java")))
+      throw new Error("JAVA_UNSUPPORTED_BUILD: JPMS module paths are not supported.");
+    const dependencies = (await readFile(classpath, "utf8")).trim().split(path2.delimiter).filter(Boolean);
+    if (await exists(exported.output))
+      dependencies.push(exported.output);
+    return {
+      root,
+      release: exported.release,
+      encoding: exported.encoding,
+      name: exported.name,
+      files,
+      classpath: dependencies,
+      generatedRoot: await exists(exported.generatedRoot) ? exported.generatedRoot : ""
+    };
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}
+
+// plugins/scanners/java/src/adapter.ts
+var worker = fileURLToPath(new URL("../dist/worker.jar", import.meta.url));
+async function checkJavaReadiness(repositoryRoot, options = {}) {
+  const jar = options.worker ?? worker;
+  if (!await exists(jar))
+    throw new Error("JAVA_WORKER_MISSING: Install the packaged Java scanner, or build it with bun plugins/scanners/java/build.ts.");
+  const command = options.java ?? javaCommand();
+  try {
+    const modules = await run(command, ["--list-modules"], repositoryRoot);
+    if (!modules.includes("jdk.compiler@"))
+      throw new Error("The selected runtime has no Java compiler module.");
+  } catch (error) {
+    throw new Error(`JAVA_JDK_MISSING: Install the project JDK (Java 25 for the supported example) and select it with JAVA_HOME. ${error}`);
+  }
+  const input = await readJavaInput(repositoryRoot, command, jar, options.maven);
+  return { input, command, jar };
+}
+async function scanJavaSource(repositoryRoot, options = {}) {
+  const { input, command, jar } = await checkJavaReadiness(repositoryRoot, options);
+  let stdout;
+  try {
+    stdout = await run(command, [
+      "-Xmx1024m",
+      "-jar",
+      jar,
+      input.root,
+      input.release,
+      input.encoding,
+      input.generatedRoot
+    ], input.root, `${input.classpath.join(path3.delimiter)}
+${input.files.join(`
+`)}
+`, options.timeout);
+  } catch (error) {
+    throw new Error(`JAVA_COMPILATION_FAILED: No observation was produced. Use the project's declared JDK ${input.release}, resolve Maven dependencies, and prepare required generated sources with the project's documented build command. ${error}`);
+  }
+  const observation = parseScanObservation(stdout);
+  observation.roots[0].name = input.name;
+  return observation;
+}
+
+// plugins/scanners/java/src/index.ts
+var scanner = {
+  id: "java",
+  watch: { include: ["**/*.java", "pom.xml", ".mvn/**"], exclude: [] },
+  checkReadiness: async (root) => {
+    await checkJavaReadiness(root);
+  },
+  scan: scanJavaSource
+};
+var src_default = scanner;
+export {
+  src_default as default
+};