@groma/scanner-go 0.1.0

package/GO-LICENSE

@@ -0,0 +1,27 @@
+Copyright 2009 The Go Authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/GO-MOD-LICENSE

@@ -0,0 +1,27 @@
+Copyright 2009 The Go Authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/GO-SYNC-LICENSE

@@ -0,0 +1,27 @@
+Copyright 2009 The Go Authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/GO-TOOLS-LICENSE

@@ -0,0 +1,27 @@
+Copyright 2009 The Go Authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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,53 @@
+{
+  "name": "@groma/scanner-go",
+  "version": "0.1.0",
+  "description": "Go project evidence through Go language tooling.",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "os": [
+    "win32",
+    "linux",
+    "darwin"
+  ],
+  "cpu": [
+    "arm64",
+    "x64"
+  ],
+  "groma": {
+    "scanner": {
+      "id": "go",
+      "entry": "./src/index.js",
+      "discovery": {
+        "technologies": [
+          "go"
+        ],
+        "rules": [
+          {
+            "type": "text",
+            "files": [
+              "**/go.mod"
+            ],
+            "technology": "go",
+            "kind": "language",
+            "versionPattern": "^go\\s+(\\S+)",
+            "declaration": "Go module go directive"
+          }
+        ],
+        "compatibility": {
+          "groma": "^0.3.0",
+          "technologyVersions": {
+            "go": "1.20.0"
+          }
+        }
+      }
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MrLesk/Groma.md.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,330 @@
+// @bun
+// plugins/scanners/go/src/adapter.ts
+import { execFile } from "child_process";
+import { access, realpath } from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+
+// 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/go/src/adapter.ts
+var packagedWorker = fileURLToPath(new URL(`../dist/${process.platform}-${process.arch}/worker${process.platform === "win32" ? ".exe" : ""}`, import.meta.url));
+function run(command, args, root, env = process.env) {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, {
+      cwd: root,
+      env,
+      encoding: "utf8",
+      timeout: 120000,
+      killSignal: "SIGKILL",
+      maxBuffer: 64 * 1024 * 1024
+    }, (error, stdout, stderr) => {
+      if (error)
+        reject(new Error(stderr.trim() || stdout.trim() || error.message));
+      else
+        resolve(stdout);
+    });
+  });
+}
+async function checkGoReadiness(repositoryRoot, options = {}) {
+  const root = await realpath(repositoryRoot);
+  const worker = options.worker ?? packagedWorker;
+  try {
+    await access(worker);
+  } catch {
+    throw new Error("GO_WORKER_MISSING: Install the packaged Go scanner for this platform, or build it with bun plugins/scanners/go/build.ts.");
+  }
+  const env = { ...process.env, GOTOOLCHAIN: "local", GOPROXY: "off", GOSUMDB: "off" };
+  let context;
+  try {
+    context = JSON.parse(await run(options.go ?? "go", ["env", "-json", "GOMOD", "GOWORK", "GOROOT"], root, env));
+  } catch (error) {
+    throw new Error(`GO_TOOLCHAIN_MISSING: Install the project's Go toolchain and add its bin directory to PATH (Go 1.27.1 for the qualified example). ${error}`);
+  }
+  if (context.GOWORK && context.GOWORK !== "off") {
+    throw new Error("GO_PROJECT_SCOPE: This scanner supports one root module. Select the supported module with GOWORK=off; workspace analysis is not qualified.");
+  }
+  if (context.GOMOD !== path.join(root, "go.mod")) {
+    throw new Error("GO_PROJECT_SCOPE: Run Groma at the supported Go module root containing go.mod.");
+  }
+  env.PATH = `${path.join(context.GOROOT, "bin")}${path.delimiter}${process.env.PATH ?? ""}`;
+  try {
+    await run(options.go ?? "go", ["list", "-mod=readonly", "-deps", "./..."], root, env);
+  } catch (error) {
+    throw new Error(`GO_PROJECT_PREPARATION: Prepare dependencies and generated source with the project's documented build commands (go mod download for module dependencies), then retry. Scan does not download tools or modules. ${error}`);
+  }
+  return { root, worker, env };
+}
+async function scanGoSource(repositoryRoot, options = {}) {
+  const { root, worker, env } = await checkGoReadiness(repositoryRoot, options);
+  try {
+    return parseScanObservation(await run(worker, [root], root, env));
+  } catch (error) {
+    throw new Error(`GO_COMPILATION_FAILED: No observation was produced. Correct compilation errors with the project's Go toolchain and prepare its dependencies and generated source. ${error}`);
+  }
+}
+
+// plugins/scanners/go/src/index.ts
+var src_default = {
+  id: "go",
+  watch: { include: ["**/*.go", "**/go.mod", "**/go.sum", "**/go.work"], exclude: [] },
+  checkReadiness: async (root) => {
+    await checkGoReadiness(root);
+  },
+  scan: scanGoSource
+};
+export {
+  src_default as default
+};