@groma/scanner-go 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groma/scanner-go",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Go project evidence through Go language tooling.",
   "private": false,
   "type": "module",

package/src/index.js

@@ -24,9 +24,12 @@ var excluded = new Set([
   "groma",
   ".groma"
 ]);
-async function projectFiles(root, matches) {
+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) && !file.split("/").some((part) => excluded.has(part)) && existsSync(path.join(root, file))))].sort();
+  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
@@ -35,6 +38,116 @@ 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) {
   return values.join("\x00");
@@ -78,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
@@ -87,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]));
@@ -117,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)
@@ -146,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 {
@@ -296,6 +415,9 @@ function relocateObservation(observation, directory) {
     ...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,
@@ -312,6 +434,9 @@ function combineObservations(parts) {
   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) } : {} })));
@@ -323,7 +448,10 @@ function combineObservations(parts) {
     }
     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,
@@ -331,7 +459,10 @@ function combineObservations(parts) {
     files: [...files.values()],
     operations,
     invocations,
-    diagnostics
+    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 } : {}
   });
 }
 
@@ -365,9 +496,9 @@ 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) => {
-    execFile2(command, args, {
+    const child = execFile2(command, args, {
       cwd: root,
       env,
       encoding: "utf8",
@@ -380,50 +511,51 @@ 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.GOMOD !== path4.join(root, "go.mod")) {
-    throw new Error("GO_PROJECT_SCOPE: The selected project must contain go.mod.");
-  }
-  env.PATH = `${path4.join(context.GOROOT, "bin")}${path4.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
+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))));