metascope 0.1.0 → 0.2.0

package/dist/lib/parsers/gemspec-parser.js

@@ -0,0 +1,256 @@
+import { getRubyLanguage, initParser } from "../utilities/tree-sitter-wasm.js";
+import is from "@sindresorhus/is";
+//#region src/lib/parsers/gemspec-parser.ts
+function emptySpec() {
+	return {
+		authors: [],
+		bindir: void 0,
+		cert_chain: [],
+		dependencies: [],
+		description: void 0,
+		email: void 0,
+		executables: [],
+		extensions: [],
+		extra: {},
+		extra_rdoc_files: [],
+		files: [],
+		homepage: void 0,
+		license: void 0,
+		licenses: [],
+		metadata: {},
+		name: void 0,
+		platform: void 0,
+		post_install_message: void 0,
+		rdoc_options: [],
+		require_paths: [],
+		required_ruby_version: void 0,
+		required_rubygems_version: void 0,
+		signing_key: void 0,
+		summary: void 0,
+		test_files: [],
+		version: void 0
+	};
+}
+/** Filter nulls from web-tree-sitter's `namedChildren` array. */
+function children(node) {
+	return node.namedChildren.filter((c) => c !== null);
+}
+/** Methods that return the receiver unchanged — safe to unwrap. */
+const IDENTITY_METHODS = new Set([
+	"-@",
+	"dup",
+	"freeze"
+]);
+/** Extract the raw string value from a tree-sitter string/symbol node. */
+function extractString(node) {
+	switch (node.type) {
+		case "call": {
+			const method = node.childForFieldName("method");
+			if (method && IDENTITY_METHODS.has(method.text)) {
+				const receiver = node.childForFieldName("receiver");
+				if (receiver) return extractString(receiver);
+			}
+			return;
+		}
+		case "float":
+		case "integer": return node.text;
+		case "heredoc_body": return node.text.trim();
+		case "simple_symbol": return node.text.replace(/^:/, "");
+		case "string":
+		case "string_content": {
+			const parts = children(node).filter((c) => c.type === "string_content");
+			if (parts.length > 0) return parts.map((p) => p.text).join("");
+			return node.text.replaceAll(/^["']|["']$/g, "");
+		}
+		default: return;
+	}
+}
+/** Extract a string array from an array node like `["a", "b"]`. */
+function extractStringArray(node) {
+	if (node.type === "array") return children(node).map((element) => extractString(element)).filter((s) => s !== void 0);
+	if (node.type === "string_array") return children(node).map((c) => c.type === "bare_string" ? c.text : c.text);
+	const single = extractString(node);
+	return single === void 0 ? [] : [single];
+}
+/**
+* Attempt to extract a usable value from an arbitrary RHS node.
+* Returns string | string[] | null — we intentionally skip expressions
+* we can't statically evaluate (method calls, constants, etc.).
+*/
+function extractValue(node) {
+	if (node.type === "array" || node.type === "string_array") return extractStringArray(node);
+	if (node.type === "call") {
+		const method = node.childForFieldName("method");
+		if (method && IDENTITY_METHODS.has(method.text)) {
+			const receiver = node.childForFieldName("receiver");
+			if (receiver) return extractValue(receiver);
+		}
+	}
+	if (node.type === "true") return "true";
+	if (node.type === "false") return "false";
+	if (node.type === "nil") return void 0;
+	return extractString(node);
+}
+/** Resolve the attribute name from the LHS of `spec.foo = ...` */
+function resolveAttribute(node) {
+	if (node.type === "call") return node.childForFieldName("method")?.text ?? void 0;
+}
+const DEP_METHODS = {
+	add_dependency: "runtime",
+	add_development_dependency: "development",
+	add_runtime_dependency: "runtime"
+};
+function tryParseDependency(node) {
+	if (node.type !== "call" && node.type !== "method_call") return void 0;
+	const methodNode = node.childForFieldName("method");
+	if (!methodNode) return void 0;
+	let methodName;
+	if (methodNode.type === "call") methodName = methodNode.childForFieldName("method")?.text ?? void 0;
+	else if (methodNode.type === "identifier") methodName = methodNode.text;
+	else methodName = methodNode.text;
+	if (!methodName) {
+		const topMethod = node.childForFieldName("method");
+		if (topMethod?.type === "identifier") methodName = topMethod.text;
+	}
+	if (!methodName || !DEP_METHODS[methodName]) {
+		for (const m of Object.keys(DEP_METHODS)) if (node.text.includes(`.${m}`)) {
+			methodName = m;
+			break;
+		}
+	}
+	if (!methodName || !DEP_METHODS[methodName]) return void 0;
+	const depType = DEP_METHODS[methodName];
+	const arguments_ = node.childForFieldName("arguments");
+	if (!arguments_) return void 0;
+	const argumentNodes = children(arguments_);
+	if (argumentNodes.length === 0) return void 0;
+	const depName = extractString(argumentNodes[0]);
+	if (!depName) return void 0;
+	return {
+		name: depName,
+		requirements: argumentNodes.slice(1).map((element) => extractString(element)).filter((s) => s !== void 0),
+		type: depType
+	};
+}
+function extractHash(node) {
+	const result = {};
+	if (node.type !== "hash") return result;
+	for (const pair of children(node)) {
+		if (pair.type !== "pair") continue;
+		const key = pair.childForFieldName("key");
+		const value = pair.childForFieldName("value");
+		if (!key || !value) continue;
+		const k = extractString(key);
+		const v = extractString(value);
+		if (k && v) result[k] = v;
+	}
+	return result;
+}
+function setStringAttribute(spec, key, value) {
+	Object.assign(spec, { [key]: value });
+}
+function setArrayAttribute(spec, key, value) {
+	Object.assign(spec, { [key]: value });
+}
+/**
+* Parse a `.gemspec` file's contents and return a plain object with the
+* extracted fields.
+*
+* Uses tree-sitter with the Ruby grammar to walk the AST, so it can handle
+* most real-world gemspec patterns without executing Ruby.
+*
+* Fields that reference Ruby constants (e.g. `Foo::VERSION`) or dynamic
+* expressions (e.g. `Dir.glob(...)`) will be `null` / empty — the parser
+* only extracts statically determinable values.
+*/
+async function parseGemspec(source) {
+	const parser = await initParser();
+	const ruby = await getRubyLanguage();
+	parser.setLanguage(ruby);
+	const tree = parser.parse(source);
+	if (!tree) throw new Error("Failed to parse gemspec source");
+	const spec = emptySpec();
+	/** Map of simple attribute names → setter logic */
+	const STRING_ATTRS = new Set([
+		"bindir",
+		"description",
+		"homepage",
+		"license",
+		"name",
+		"platform",
+		"post_install_message",
+		"required_ruby_version",
+		"required_rubygems_version",
+		"signing_key",
+		"summary",
+		"version"
+	]);
+	const ARRAY_ATTRS = new Set([
+		"authors",
+		"cert_chain",
+		"executables",
+		"extensions",
+		"extra_rdoc_files",
+		"files",
+		"licenses",
+		"rdoc_options",
+		"require_paths",
+		"test_files"
+	]);
+	function visit(node) {
+		if (node.type === "assignment") {
+			const lhs = node.childForFieldName("left");
+			const rhs = node.childForFieldName("right");
+			if (!lhs || !rhs) {
+				visitChildren(node);
+				return;
+			}
+			const attribute = resolveAttribute(lhs);
+			if (!attribute) {
+				visitChildren(node);
+				return;
+			}
+			if (attribute === "email") {
+				const value = extractValue(rhs);
+				if (value !== void 0) spec.email = value;
+				return;
+			}
+			if (attribute === "metadata") {
+				if (rhs.type === "hash") spec.metadata = {
+					...is.plainObject(spec.metadata) ? spec.metadata : {},
+					...extractHash(rhs)
+				};
+				return;
+			}
+			if (STRING_ATTRS.has(attribute)) {
+				const value = extractString(rhs);
+				if (value !== void 0) setStringAttribute(spec, attribute, value);
+				return;
+			}
+			if (ARRAY_ATTRS.has(attribute)) {
+				const array = extractStringArray(rhs);
+				if (array.length > 0) setArrayAttribute(spec, attribute, array);
+				return;
+			}
+			const value = extractValue(rhs);
+			if (value !== void 0 && is.plainObject(spec.extra)) spec.extra[attribute] = value;
+			return;
+		}
+		if (node.type === "call" || node.type === "method_call") {
+			const dep = tryParseDependency(node);
+			if (dep) {
+				if (Array.isArray(spec.dependencies)) spec.dependencies.push(dep);
+				return;
+			}
+		}
+		if (node.type === "element_assignment" || node.type === "indexing") {}
+		visitChildren(node);
+	}
+	function visitChildren(node) {
+		for (const child of children(node)) visit(child);
+	}
+	visit(tree.rootNode);
+	return spec;
+}
+//#endregion
+export { parseGemspec };

package/dist/lib/parsers/go-mod-parser.js

@@ -0,0 +1,153 @@
+//#region src/lib/parsers/go-mod-parser.ts
+/**
+* Known source-repo hosts and the number of path segments that make a repo URL.
+* e.g. github.com/owner/repo → 3 segments.
+*/
+const HOST_SEGMENTS = {
+	"bitbucket.com": 3,
+	"bitbucket.org": 3,
+	"codeberg.org": 3,
+	"git.sr.ht": 3,
+	"github.com": 3,
+	"gitlab.com": 3
+};
+/** Derive a repository URL from a Go module path, if on a known host. */
+function moduleToRepoUrl(modulePath) {
+	const segments = modulePath.split("/");
+	const host = segments[0];
+	if (!host) return void 0;
+	const needed = HOST_SEGMENTS[host];
+	if (!needed || segments.length < needed) return void 0;
+	let repoPath = segments.slice(0, needed).join("/");
+	repoPath = repoPath.replace(/\/v\d+$/, "");
+	return `https://${repoPath}`;
+}
+/** Strip inline comments and trim whitespace. */
+function stripComment(line) {
+	const index = line.indexOf("//");
+	return index === -1 ? line.trim() : line.slice(0, index).trim();
+}
+/** Check whether a line has an `// indirect` comment. */
+function isIndirect(line) {
+	return /\/\/\s*indirect/.test(line);
+}
+/** Parse a require-style line: `module version [// indirect]` */
+function parseRequireLine(line) {
+	const indirect = isIndirect(line);
+	const clean = stripComment(line);
+	const match = /^(\S+)\s+(\S+)/.exec(clean);
+	if (!match) return void 0;
+	const version = match[2].replace(/\+incompatible$/, "");
+	return {
+		indirect,
+		module: match[1],
+		version
+	};
+}
+/** Parse a replace-style line: `old [version] => new version` or `old [version] => ./local` */
+function parseReplaceLine(line) {
+	const parts = stripComment(line).split("=>");
+	if (parts.length !== 2) return void 0;
+	const left = parts[0].trim().split(/\s+/);
+	const right = parts[1].trim().split(/\s+/);
+	const from = left[0];
+	if (!from || right.length === 0) return void 0;
+	const target = right[0];
+	if (!target) return void 0;
+	if (target.startsWith("./") || target.startsWith("../") || target.startsWith("/")) return {
+		from,
+		to: "local"
+	};
+	return {
+		from,
+		to: {
+			module: target,
+			version: (right[1] ?? "").replace(/\+incompatible$/, "")
+		}
+	};
+}
+/** Parse a tool-style line: just a module path. */
+function parseToolLine(line) {
+	const clean = stripComment(line).trim();
+	if (clean.length === 0) return void 0;
+	return clean.split(/\s+/)[0] || void 0;
+}
+/**
+* Parse a go.mod file and return structured metadata.
+*
+* Extracts module identity, Go version, direct dependencies (skipping
+* indirect ones), tool dependencies, and applies replace directives.
+*/
+function parseGoMod(source) {
+	const data = {
+		dependencies: [],
+		go_version: void 0,
+		module: void 0,
+		repository_url: void 0,
+		tool_dependencies: []
+	};
+	const directDeps = {};
+	const toolDeps = [];
+	const replacements = /* @__PURE__ */ new Map();
+	let blockState = "none";
+	for (const rawLine of source.split("\n")) {
+		const line = rawLine.trim();
+		if (line === "" || line.startsWith("//") && blockState === "none") continue;
+		if (line === ")" || line.startsWith(")")) {
+			blockState = "none";
+			continue;
+		}
+		if (blockState !== "none") {
+			switch (blockState) {
+				case "replace": {
+					const rep = parseReplaceLine(line);
+					if (rep) replacements.set(rep.from, rep.to);
+					break;
+				}
+				case "require": {
+					const dep = parseRequireLine(line);
+					if (dep && !dep.indirect) directDeps[dep.module] = dep.version;
+					break;
+				}
+				case "skip": break;
+				case "tool": {
+					const tool = parseToolLine(line);
+					if (tool) toolDeps.push(tool);
+					break;
+				}
+			}
+			continue;
+		}
+		if (line.startsWith("module ")) data.module = line.slice(7).trim();
+		else if (line.startsWith("go ")) data.go_version = line.slice(3).trim();
+		else if (line.startsWith("require ")) if (line.includes("(")) blockState = "require";
+		else {
+			const dep = parseRequireLine(line.slice(8));
+			if (dep && !dep.indirect) directDeps[dep.module] = dep.version;
+		}
+		else if (line.startsWith("replace ")) if (line.includes("(")) blockState = "replace";
+		else {
+			const rep = parseReplaceLine(line.slice(8));
+			if (rep) replacements.set(rep.from, rep.to);
+		}
+		else if (line.startsWith("tool ")) if (line.includes("(")) blockState = "tool";
+		else {
+			const tool = parseToolLine(line.slice(5));
+			if (tool) toolDeps.push(tool);
+		}
+		else if ((line.startsWith("exclude ") || line.startsWith("retract ") || line.startsWith("godebug ") || line.startsWith("toolchain ")) && line.includes("(")) blockState = "skip";
+	}
+	for (const [from, to] of replacements) if (from in directDeps) {
+		delete directDeps[from];
+		if (to !== "local") directDeps[to.module] = to.version;
+	}
+	data.dependencies = Object.entries(directDeps).map(([module, version]) => ({
+		module,
+		version
+	}));
+	data.tool_dependencies = toolDeps;
+	if (data.module) data.repository_url = moduleToRepoUrl(data.module);
+	return data;
+}
+//#endregion
+export { parseGoMod };

package/dist/lib/parsers/makefile-config-parser.js

@@ -0,0 +1,102 @@
+//#region src/lib/parsers/makefile-config-parser.ts
+/**
+* Parser for Makefile-style configuration files.
+*
+* These files use a GNU Makefile-like syntax with section headers (lines
+* ending in `:`) and variable assignments (`VAR = value` or `VAR += value`).
+* This parser extracts metadata from the `meta:` section and structural
+* information (dependencies, platform sections) from the rest of the file.
+*
+* The parser is intentionally simple — no Make variable expansion, no
+* includes, no conditionals. It mirrors the line-by-line algorithm used
+* by the openFrameworks Project Generator.
+*/
+/** Section header pattern: a word (with optional hyphens/slashes) followed by a colon. */
+const SECTION_RE = /^[\w/][\w/-]*:$/;
+/** Variable assignment pattern: VARNAME = value  or  VARNAME += value */
+const ASSIGNMENT_RE = /^(\w+)\s*(\+?=)\s*(.*)/;
+/**
+* Sections that are not platform-specific and should be excluded
+* from operatingSystem inference.
+*/
+const NON_PLATFORM_SECTIONS = new Set([
+	"all",
+	"common",
+	"meta"
+]);
+/**
+* Parse a Makefile-style config file and return structured metadata.
+*/
+function parseMakefileConfig(content) {
+	const metaVariables = /* @__PURE__ */ new Map();
+	const commonDependencies = [];
+	const platformSectionsWithContent = /* @__PURE__ */ new Set();
+	let currentSection = "";
+	let currentSectionHasAssignment = false;
+	for (const rawLine of content.split("\n")) {
+		const line = rawLine.replace(/#.*$/, "").trim();
+		if (line.length === 0) continue;
+		if (SECTION_RE.test(line)) {
+			if (currentSectionHasAssignment && !NON_PLATFORM_SECTIONS.has(currentSection)) platformSectionsWithContent.add(currentSection);
+			currentSection = line.slice(0, -1);
+			currentSectionHasAssignment = false;
+			continue;
+		}
+		const match = ASSIGNMENT_RE.exec(line);
+		if (!match) continue;
+		const [, variableName, operator, rawValue] = match;
+		currentSectionHasAssignment = true;
+		if (currentSection === "meta") {
+			const values = tokenizeValues(rawValue);
+			if (operator === "+=") {
+				const existing = metaVariables.get(variableName) ?? [];
+				metaVariables.set(variableName, [...existing, ...values]);
+			} else metaVariables.set(variableName, values);
+		} else if (currentSection === "common" && variableName === "ADDON_DEPENDENCIES") {
+			const values = tokenizeValues(rawValue);
+			if (operator === "+=") commonDependencies.push(...values);
+			else {
+				commonDependencies.length = 0;
+				commonDependencies.push(...values);
+			}
+		}
+	}
+	if (currentSectionHasAssignment && !NON_PLATFORM_SECTIONS.has(currentSection)) platformSectionsWithContent.add(currentSection);
+	return {
+		author: singleValue(metaVariables, "ADDON_AUTHOR"),
+		dependencies: commonDependencies,
+		description: singleValue(metaVariables, "ADDON_DESCRIPTION"),
+		name: singleValue(metaVariables, "ADDON_NAME"),
+		platformSections: [...platformSectionsWithContent],
+		tags: metaVariables.get("ADDON_TAGS") ?? [],
+		url: singleValue(metaVariables, "ADDON_URL")
+	};
+}
+/**
+* Get a single string value from the meta variables map.
+* Joins multiple tokens with spaces (for values split across `+=` lines).
+* Returns undefined for empty/whitespace-only results.
+*/
+function singleValue(variables, key) {
+	const values = variables.get(key);
+	if (!values || values.length === 0) return void 0;
+	const joined = values.join(" ").trim();
+	return joined.length > 0 ? joined : void 0;
+}
+/**
+* Tokenize a value string, handling both bare tokens and "quoted multi-word"
+* tokens. For example:
+*   `"computer vision" "opencv" bare` → `["computer vision", "opencv", "bare"]`
+*/
+function tokenizeValues(raw) {
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) return [];
+	const values = [];
+	for (const [, quoted, bare] of trimmed.matchAll(/"([^"]+)"|(\S+)/g)) {
+		const value = quoted || bare;
+		if (value.length > 0) values.push(value);
+	}
+	return values;
+}
+//#endregion
+export { parseMakefileConfig };

package/dist/lib/parsers/properties-parser.js

@@ -0,0 +1,31 @@
+//#region src/lib/parsers/properties-parser.ts
+/**
+* Parser for Java `*.properties` files (key=value format).
+*
+* Used by both Arduino and Processing IDE library managers. These are
+* flat UTF-8 properties files with no sections or nesting. Comment lines
+* start with `#`. Only the first `=` on each line is the delimiter.
+*
+* Returns raw key-value pairs — all domain-specific validation and
+* transformation is handled by the consuming source.
+*
+* See https://en.wikipedia.org/wiki/.properties
+*/
+/**
+* Parse a `*.properties` content string into raw key-value pairs.
+*/
+function parseProperties(content) {
+	const raw = {};
+	for (const rawLine of content.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (line.length === 0 || line.startsWith("#")) continue;
+		const eqIndex = line.indexOf("=");
+		if (eqIndex === -1) continue;
+		const key = line.slice(0, eqIndex).trim();
+		const value = line.slice(eqIndex + 1).trim();
+		if (key.length > 0) raw[key] = value;
+	}
+	return raw;
+}
+//#endregion
+export { parseProperties };

package/dist/lib/parsers/rfc822-header-parser.js

@@ -0,0 +1,48 @@
+//#region src/lib/parsers/rfc822-header-parser.ts
+/** Multi-value headers that can appear multiple times. */
+const MULTI_VALUE_HEADERS = new Set([
+	"Classifier",
+	"Platform",
+	"Project-URL",
+	"Requires-Dist",
+	"Requires-External",
+	"Supported-Platform"
+]);
+/**
+* Parse RFC 822-style headers from PKG-INFO / METADATA content.
+* Multi-value headers are collected into newline-separated strings.
+* Stops at the first blank line (which separates headers from body).
+*/
+function parseRfc822Headers(content) {
+	const headers = {};
+	let lastKey = "";
+	for (const line of content.split("\n")) {
+		if (line.trim() === "") break;
+		if (/^\s/.test(line) && lastKey) {
+			const continuation = line.trim();
+			if (continuation) headers[lastKey] = `${headers[lastKey]}\n${continuation}`;
+			continue;
+		}
+		const colonIndex = line.indexOf(": ");
+		if (colonIndex > 0) {
+			const key = line.slice(0, colonIndex);
+			const value = line.slice(colonIndex + 2).trim();
+			headers[key] = MULTI_VALUE_HEADERS.has(key) && headers[key] ? `${headers[key]}\n${value}` : value;
+			lastKey = key;
+		}
+	}
+	return headers;
+}
+/** Extract body text after the first blank line. */
+function extractRfc822Body(content) {
+	const blankIndex = content.indexOf("\n\n");
+	if (blankIndex === -1) return void 0;
+	return content.slice(blankIndex + 2).trim() || void 0;
+}
+/** Split newline-separated multi-value into array. */
+function splitMultiValues(value) {
+	if (!value) return [];
+	return value.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+}
+//#endregion
+export { extractRfc822Body, parseRfc822Headers, splitMultiValues };