@groma/scanner-go 0.1.0 → 0.1.2

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@groma/scanner-go",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Go project evidence through Go language tooling.",
   "private": false,
   "type": "module",
   "license": "MIT",
   "os": [
-    "win32",
     "linux",
-    "darwin"
+    "darwin",
+    "win32"
   ],
   "cpu": [
     "arm64",
@@ -35,10 +35,7 @@
           }
         ],
         "compatibility": {
-          "groma": "^0.3.0",
-          "technologyVersions": {
-            "go": "1.20.0"
-          }
+          "groma": "^0.3.0"
         }
       }
     }

package/src/index.js

@@ -1,9 +1,152 @@
 // @bun
-// plugins/scanners/go/src/adapter.ts
+// plugins/scanners/go/src/index.ts
+import path5 from "path";
+
+// plugins/scanners/projects.ts
 import { execFile } from "child_process";
-import { access, realpath } from "fs/promises";
+import { existsSync } from "fs";
 import path from "path";
-import { fileURLToPath } from "url";
+import { promisify } from "util";
+var execute = promisify(execFile);
+var excluded = new Set([
+  ".git",
+  "node_modules",
+  "vendor",
+  "target",
+  "dist",
+  "build",
+  "bin",
+  "obj",
+  ".gradle",
+  ".angular",
+  "coverage",
+  "generated",
+  "groma",
+  ".groma"
+]);
+async function repositoryFiles(root, matches) {
+  const { stdout } = await execute("git", ["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { maxBuffer: 64 * 1024 * 1024 });
+  return [...new Set(stdout.split("\x00").filter((file) => file && matches(file) && existsSync(path.join(root, file))))].sort();
+}
+function projectFiles(root, matches) {
+  return repositoryFiles(root, (file) => matches(file) && !file.split("/").some((part) => excluded.has(part)));
+}
+
+// plugins/scanners/project-scanner.ts
+import path3 from "path";
+
+// plugins/scanners/observations.ts
+import path2 from "path";
+
+// packages/scanner/src/values.ts
+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;
+}
+
+// packages/scanner/src/http.ts
+var pathText = /^[A-Za-z0-9\-._~!$&'()*+,;=:@%]+$/;
+var methodToken = /^[A-Z][A-Z-]*$/;
+function fail(message) {
+  throw new Error(message);
+}
+function text(value, label) {
+  if (typeof value !== "string" || !pathText.test(value))
+    fail(`${label} must be nonempty URL path characters`);
+  return value;
+}
+function method(value, label, anyMethod) {
+  if (typeof value !== "string" || !(methodToken.test(value) || anyMethod && value === "*")) {
+    fail(`${label} must be an uppercase HTTP method${anyMethod ? " or *" : ""}`);
+  }
+  return value;
+}
+function operation(value, operations) {
+  if (typeof value !== "string" || !operations.has(value))
+    fail("HTTP fact references unknown operation");
+  return value;
+}
+function endpointSegment(value, last) {
+  const segment = object(value, "HTTP endpoint segment");
+  if (segment.kind === "literal")
+    return { kind: "literal", value: text(segment.value, "HTTP literal segment") };
+  if (segment.kind !== "parameter" && segment.kind !== "catch-all")
+    fail(`unknown HTTP endpoint segment kind: ${String(segment.kind)}`);
+  if (segment.kind === "catch-all" && !last)
+    fail("an HTTP catch-all segment must be last");
+  for (const flag of ["optional", "constrained"]) {
+    if (segment[flag] !== undefined && typeof segment[flag] !== "boolean")
+      fail(`HTTP segment ${flag} must be a boolean`);
+  }
+  return {
+    kind: segment.kind,
+    name: text(segment.name, "HTTP segment name"),
+    ...segment.optional ? { optional: true } : {},
+    ...segment.constrained ? { constrained: true } : {}
+  };
+}
+function requestSegment(value) {
+  const segment = object(value, "HTTP request segment");
+  if (segment.kind === "literal")
+    return { kind: "literal", value: text(segment.value, "HTTP literal segment") };
+  if (segment.kind === "dynamic" || segment.kind === "unknown")
+    return { kind: segment.kind };
+  return fail(`unknown HTTP request segment kind: ${String(segment.kind)}`);
+}
+function order(value) {
+  const fact = object(value, "HTTP endpoint order");
+  const application = string(fact.application, "HTTP endpoint order application");
+  if (application === "")
+    fail("HTTP endpoint order application must be nonempty");
+  const position = fact.position;
+  if (typeof position !== "number" || !Number.isInteger(position) || position < 0) {
+    fail("HTTP endpoint order position must be a nonnegative integer");
+  }
+  return { application, position };
+}
+function endpoint(value, operations) {
+  const fact = object(value, "HTTP endpoint");
+  const path = array(fact.path, "HTTP endpoint path");
+  return {
+    operation: operation(fact.operation, operations),
+    method: method(fact.method, "HTTP endpoint method", true),
+    path: path.map((segment, index) => endpointSegment(segment, index === path.length - 1)),
+    ...fact.order === undefined ? {} : { order: order(fact.order) }
+  };
+}
+function request(value, operations) {
+  const fact = object(value, "HTTP request");
+  if (fact.configured !== undefined && typeof fact.configured !== "boolean")
+    fail("HTTP request configured must be a boolean");
+  return {
+    operation: operation(fact.operation, operations),
+    ...fact.method === undefined ? {} : { method: method(fact.method, "HTTP request method", false) },
+    ...fact.configured ? { configured: true } : {},
+    path: array(fact.path, "HTTP request path").map(requestSegment)
+  };
+}
+function httpEvidence(endpoints, requests, operations) {
+  if (endpoints === undefined && requests === undefined)
+    return {};
+  if (operations === undefined)
+    fail("HTTP facts require operation declarations");
+  return {
+    ...endpoints === undefined ? {} : { httpEndpoints: array(endpoints, "httpEndpoints").map((fact) => endpoint(fact, operations)) },
+    ...requests === undefined ? {} : { httpRequests: array(requests, "httpRequests").map((fact) => request(fact, operations)) }
+  };
+}
 
 // packages/scanner/src/index.ts
 function compare(...values) {
@@ -48,7 +191,9 @@ function createScanObservation(input) {
     scanner: input.scanner,
     roots,
     files,
+    ...sourceUnits(input.sourceUnits, filePaths),
     ...operationEvidence(input, filePaths),
+    ...httpEvidence(input.httpEndpoints, input.httpRequests, input.operations && new Set(input.operations.map((operation) => operation.id))),
     diagnostics: [...new Map(input.diagnostics.map((diagnostic) => [
       diagnosticKey(diagnostic),
       diagnostic
@@ -57,6 +202,23 @@ function createScanObservation(input) {
     })
   };
 }
+function sourceUnits(input, paths) {
+  if (input === undefined)
+    return {};
+  const units = array(input, "sourceUnits").map((entry) => {
+    const unit = object(entry, "source unit");
+    const primary = string(unit.primary, "source unit.primary");
+    const files = [...new Set(array(unit.files, "source unit.files").map((file) => string(file, "source unit.file")))].sort();
+    if (!files.includes(primary))
+      throw new Error(`source unit omits primary file: ${primary}`);
+    for (const file of files) {
+      if (!paths.has(file))
+        throw new Error(`source unit references unknown file: ${file}`);
+    }
+    return { primary, files };
+  });
+  return { sourceUnits: [...new Map(units.map((unit) => [compare(unit.primary, ...unit.files), unit])).values()].sort((a, b) => compare(a.primary, ...a.files).localeCompare(compare(b.primary, ...b.files))) };
+}
 function validateRoots(input) {
   const roots = uniqueBy(input, (root) => root.id, "root id");
   const byId = new Map(roots.map((root) => [root.id, root]));
@@ -87,22 +249,6 @@ function diagnosticLocation(value) {
     ...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)
@@ -116,6 +262,9 @@ function parseScanObservation(source) {
       engineVersion: string(scanner.engineVersion, "scanner.engineVersion")
     },
     ...parseOperations(value),
+    httpEndpoints: value.httpEndpoints,
+    httpRequests: value.httpRequests,
+    ...sourceUnits(value.sourceUnits, new Set(array(value.files, "files").map((entry) => string(object(entry, "file").file, "file.file")))),
     roots: array(value.roots, "roots").map((entry) => {
       const root = object(entry, "root");
       return {
@@ -259,11 +408,97 @@ function sourcePosition(position) {
   return { position: Number(position) };
 }
 
+// plugins/scanners/observations.ts
+function relocateObservation(observation, directory) {
+  const file = (value) => path2.posix.normalize(path2.posix.join(directory, value));
+  return {
+    ...observation,
+    roots: observation.roots.map((root) => ({ ...root, ...root.file ? { file: file(root.file) } : {} })),
+    files: observation.files.map((source) => ({ ...source, file: file(source.file) })),
+    ...observation.sourceUnits === undefined ? {} : {
+      sourceUnits: observation.sourceUnits.map((unit) => ({ primary: file(unit.primary), files: unit.files.map(file) }))
+    },
+    operations: observation.operations?.map((operation) => ({ ...operation, file: file(operation.file) })),
+    invocations: observation.invocations?.map((call) => ({
+      ...call,
+      ...call.binding ? { binding: { ...call.binding, file: file(call.binding.file) } } : {}
+    })),
+    diagnostics: observation.diagnostics.map((item) => ({ ...item, ...item.file ? { file: file(item.file) } : {} }))
+  };
+}
+function combineObservations(parts) {
+  if (!parts.length)
+    return;
+  const roots = [];
+  const files = new Map;
+  const operations = [];
+  const invocations = [];
+  const diagnostics = [];
+  const sourceUnits = [];
+  const httpEndpoints = [];
+  const httpRequests = [];
+  for (const { key, observation } of parts) {
+    const id = (value) => JSON.stringify([key, value]);
+    roots.push(...observation.roots.map((root) => ({ ...root, id: id(root.id), ...root.parent ? { parent: id(root.parent) } : {} })));
+    for (const source of observation.files) {
+      const combined = files.get(source.file) ?? { file: source.file, roots: [], symbols: [] };
+      combined.roots.push(...source.roots.map(id));
+      combined.symbols.push(...source.symbols.map((symbol) => ({ ...symbol, id: id(symbol.id) })));
+      files.set(source.file, combined);
+    }
+    operations.push(...(observation.operations ?? []).map((operation) => ({ ...operation, id: id(operation.id) })));
+    invocations.push(...(observation.invocations ?? []).map((call) => ({ ...call, source: id(call.source), targets: call.targets.map(id) })));
+    httpEndpoints.push(...(observation.httpEndpoints ?? []).map((endpoint) => ({ ...endpoint, operation: id(endpoint.operation) })));
+    httpRequests.push(...(observation.httpRequests ?? []).map((request) => ({ ...request, operation: id(request.operation) })));
+    diagnostics.push(...observation.diagnostics);
+    sourceUnits.push(...observation.sourceUnits ?? []);
+  }
+  return createScanObservation({
+    scanner: parts[0].observation.scanner,
+    roots,
+    files: [...files.values()],
+    operations,
+    invocations,
+    diagnostics,
+    ...parts.some((part) => part.observation.sourceUnits !== undefined) ? { sourceUnits } : {},
+    ...parts.some((part) => part.observation.httpEndpoints !== undefined) ? { httpEndpoints } : {},
+    ...parts.some((part) => part.observation.httpRequests !== undefined) ? { httpRequests } : {}
+  });
+}
+
+// plugins/scanners/project-scanner.ts
+function projectScanner(scanner, select) {
+  return {
+    ...scanner,
+    checkReadiness: async (root, settings = {}) => {
+      const projects = await select(root, settings);
+      if (!projects.length)
+        throw new Error(`${scanner.id}: No supported project declaration was found.`);
+      for (const project of projects)
+        await scanner.checkReadiness?.(project, settings);
+    },
+    scan: async (root, settings = {}) => {
+      const parts = [];
+      for (const project of await select(root, settings)) {
+        const observation = await scanner.scan(project, settings);
+        const key = path3.relative(root, project).split(path3.sep).join("/");
+        if (observation)
+          parts.push({ key, observation: relocateObservation(observation, key) });
+      }
+      return combineObservations(parts);
+    }
+  };
+}
+
 // plugins/scanners/go/src/adapter.ts
+import { execFile as execFile2 } from "child_process";
+import { access, realpath } from "fs/promises";
+import path4 from "path";
+import { fileURLToPath } from "url";
 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) {
+function run(command, args, root, { env = process.env, input } = {}) {
   return new Promise((resolve, reject) => {
-    execFile(command, args, {
+    const child = execFile2(command, args, {
       cwd: root,
       env,
       encoding: "utf8",
@@ -276,55 +511,54 @@ function run(command, args, root, env = process.env) {
       else
         resolve(stdout);
     });
+    if (input !== undefined)
+      child.stdin?.end(input);
   });
 }
-async function checkGoReadiness(repositoryRoot, options = {}) {
-  const root = await realpath(repositoryRoot);
+async function workerPath(options) {
   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 };
+  return worker;
+}
+async function checkGoReadiness(repositoryRoot, options = {}) {
+  const root = await realpath(repositoryRoot);
+  const worker = await workerPath(options);
+  await access(path4.join(root, "go.mod"));
+  return { root, worker };
+}
+async function readGoCodeStructure(repositoryRoot, references, options = {}) {
+  const worker = await workerPath(options);
+  return JSON.parse(await run(worker, ["outline", repositoryRoot], repositoryRoot, { input: JSON.stringify(references) }));
 }
 async function scanGoSource(repositoryRoot, options = {}) {
-  const { root, worker, env } = await checkGoReadiness(repositoryRoot, options);
+  const { root, worker } = await checkGoReadiness(repositoryRoot, options);
   try {
-    return parseScanObservation(await run(worker, [root], root, env));
+    return parseScanObservation(await run(worker, [root], root));
   } 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}`);
+    throw new Error(`GO_SOURCE_INVALID: No observation was produced. Check Go source syntax and module declarations. ${error}`);
   }
 }
 
 // plugins/scanners/go/src/index.ts
-var src_default = {
+async function goSources(root) {
+  const modules = (await projectFiles(root, (file) => path5.posix.basename(file) === "go.mod")).map((file) => path5.posix.dirname(file));
+  return projectFiles(root, (file) => file.endsWith(".go") && !file.endsWith("_test.go") && !file.split("/").some((part) => part === "testdata" || part.startsWith(".")) && modules.some((module) => module === "." || file.startsWith(`${module}/`)));
+}
+var scanner = {
   id: "go",
   watch: { include: ["**/*.go", "**/go.mod", "**/go.sum", "**/go.work"], exclude: [] },
+  listSourceFiles: goSources,
   checkReadiness: async (root) => {
     await checkGoReadiness(root);
   },
+  readCodeStructure: readGoCodeStructure,
   scan: scanGoSource
 };
+var src_default = projectScanner(scanner, async (root) => (await projectFiles(root, (file) => path5.posix.basename(file) === "go.mod")).map((file) => path5.dirname(path5.join(root, file))));
 export {
   src_default as default
 };