@groma/scanner-rust 0.1.0

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@groma/scanner-rust",
+  "version": "0.1.0",
+  "description": "Rust project evidence through established semantic tooling.",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "os": [
+    "win32",
+    "linux",
+    "darwin"
+  ],
+  "cpu": [
+    "arm64",
+    "x64"
+  ],
+  "groma": {
+    "scanner": {
+      "id": "rust",
+      "entry": "./src/index.js",
+      "discovery": {
+        "technologies": [
+          "rust"
+        ],
+        "rules": [
+          {
+            "type": "toml",
+            "files": [
+              "**/Cargo.toml"
+            ],
+            "technology": "rust",
+            "kind": "language",
+            "tables": [
+              "package",
+              "workspace"
+            ],
+            "versionPath": [
+              "package",
+              "rust-version"
+            ],
+            "declaration": "Cargo package or workspace"
+          }
+        ],
+        "compatibility": {
+          "groma": "^0.3.0",
+          "technologyVersions": {}
+        }
+      }
+    }
+  },
+  "files": [
+    "src",
+    "dist/bin",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MrLesk/Groma.md.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,364 @@
+// plugins/scanners/rust/src/index.ts
+import { fileURLToPath } from "node:url";
+import path2 from "node: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/rust/src/project.ts
+import { execFile } from "node:child_process";
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+var execute = promisify(execFile);
+async function exists(file) {
+  try {
+    await access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function manifestAt(root, settings) {
+  if (settings.manifest === undefined)
+    return path.join(root, "Cargo.toml");
+  if (typeof settings.manifest !== "string") {
+    throw new Error("RUST_PROJECT_SELECTION: Set settings.manifest on the rust entry in scanners.json to a Cargo.toml path.");
+  }
+  return path.resolve(root, settings.manifest);
+}
+async function readRustProject(root, settings, options) {
+  const manifest = manifestAt(root, settings);
+  if (!await exists(manifest)) {
+    throw new Error("RUST_PROJECT_MISSING: Select an existing Cargo.toml with settings.manifest on the rust entry in scanners.json.");
+  }
+  let metadata;
+  try {
+    const result = await execute(options.cargo ?? "cargo", ["metadata", "--format-version", "1", "--offline", "--locked", "--manifest-path", manifest], { cwd: root, maxBuffer: 64 * 1024 * 1024 });
+    metadata = JSON.parse(result.stdout);
+  } catch (error) {
+    throw new Error(`RUST_CARGO_NOT_READY: Install the project's Rust toolchain, then run cargo fetch --manifest-path "${manifest}" to prepare its lockfile and dependencies. ${error}`);
+  }
+  const packageAtManifest = metadata.packages.find((pkg) => pkg.manifest_path === manifest);
+  const packages = packageAtManifest ? [packageAtManifest] : metadata.packages.filter((pkg) => metadata.workspace_members.includes(pkg.id));
+  const targets = packages.flatMap((pkg) => pkg.targets).filter((target) => target.kind.some((kind) => kind === "lib" || kind === "bin")).map((target) => target.src_path).sort();
+  if (!targets.length)
+    throw new Error("RUST_TARGET_MISSING: The selected Cargo project needs a library or binary target.");
+  return { root, manifest, name: packageAtManifest?.name ?? path.basename(path.dirname(manifest)), targets };
+}
+async function checkRustToolchain(root, options) {
+  try {
+    await execute(options.cargo ?? "cargo", ["--version"], { cwd: root });
+    const result = await execute(options.rustc ?? "rustc", ["--print", "sysroot"], { cwd: root });
+    const library = path.join(result.stdout.trim(), "lib/rustlib/src/rust/library");
+    if (!await exists(library))
+      throw new Error("Rust standard library sources are missing.");
+  } catch (error) {
+    throw new Error(`RUST_TOOLCHAIN_MISSING: Install the project's Rust toolchain with Cargo and rustc, and add its standard library sources with rustup component add rust-src. ${error}`);
+  }
+}
+
+// plugins/scanners/rust/src/index.ts
+var executable = fileURLToPath(new URL(`../dist/bin/${process.platform}-${process.arch}/groma-rust-scanner${process.platform === "win32" ? ".exe" : ""}`, import.meta.url));
+async function checkRustReadiness(repositoryRoot, settings = {}, options = {}) {
+  const root = path2.resolve(repositoryRoot);
+  const worker = options.worker ?? executable;
+  if (!await exists(worker)) {
+    throw new Error("RUST_WORKER_MISSING: Install the packaged Rust scanner, or build it with bun plugins/scanners/rust/build.ts.");
+  }
+  await checkRustToolchain(root, options);
+  return { input: await readRustProject(root, settings, options), worker };
+}
+async function scanRustSource(repositoryRoot, settings = {}, options = {}) {
+  const { input, worker } = await checkRustReadiness(repositoryRoot, settings, options);
+  try {
+    const pending = execute(worker, [], {
+      cwd: input.root,
+      encoding: "utf8",
+      timeout: 120000,
+      maxBuffer: 64 * 1024 * 1024,
+      killSignal: "SIGKILL",
+      windowsHide: true
+    });
+    pending.child.stdin?.end(JSON.stringify(input));
+    const { stdout } = await pending;
+    return parseScanObservation(stdout);
+  } catch (error) {
+    throw new Error(`RUST_ANALYSIS_FAILED: No observation was produced. Check the selected Cargo project and the engine diagnostic. ${error}`);
+  }
+}
+var scanner = {
+  id: "rust",
+  watch: {
+    include: [
+      "**/*.rs",
+      "**/Cargo.toml",
+      "**/Cargo.lock",
+      "**/rust-toolchain",
+      "**/rust-toolchain.toml",
+      "**/.cargo/**"
+    ],
+    exclude: ["**/target/**", "**/node_modules/**", "**/.git/**", "**/vendor/**", "**/dist/**"]
+  },
+  checkReadiness: async (root, settings) => {
+    await checkRustReadiness(root, settings);
+  },
+  scan: scanRustSource
+};
+var src_default = scanner;
+export {
+  checkRustReadiness,
+  src_default as default,
+  scanRustSource
+};