metascope 0.1.0 → 0.2.0

package/dist/lib/sources/node-npm-registry.d.ts

@@ -0,0 +1,19 @@
+import { OneOrMany, SourceRecord } from "../source.js";
+
+//#region src/lib/sources/node-npm-registry.d.ts
+type NodeNpmRegistryInfo = {
+  /** Deprecation message, if the package is deprecated. */deprecated?: string; /** Downloads in the last month. */
+  downloadsMonthly?: number; /** All-time total downloads. */
+  downloadsTotal?: number; /** Downloads in the last week. */
+  downloadsWeekly?: number; /** Downloads in the last year. */
+  downloadsYearly?: number; /** Number of files in the published package. */
+  fileCount?: number; /** Whether the package exposes TypeScript types. */
+  hasTypes?: boolean; /** ISO 8601 date the package was last published. */
+  publishDateLatest?: string; /** Unpacked size of the published package in bytes. */
+  unpackedSizeBytes?: number; /** The npmjs.com URL for the package. */
+  url?: string; /** Latest published version string. */
+  versionLatest?: string;
+};
+type NodeNpmRegistryData = OneOrMany<SourceRecord<NodeNpmRegistryInfo>> | undefined;
+//#endregion
+export { NodeNpmRegistryData };

package/dist/lib/sources/node-npm-registry.js

@@ -0,0 +1,74 @@
+import { log } from "../log.js";
+import { defineSource } from "../source.js";
+import { ensureArray } from "../utilities/template-helpers.js";
+import { fetchWithRetry } from "../utilities/fetch.js";
+import { nodePackageJsonSource } from "./node-package-json.js";
+import is from "@sindresorhus/is";
+import { z } from "zod";
+import packageJson from "package-json";
+//#region src/lib/sources/node-npm-registry.ts
+const nodeNpmRegistrySource = defineSource({
+	async discover(context) {
+		if (context.options.offline) {
+			log.warn("Skipping Node NPM registry data source since we're in offline mode");
+			return [];
+		}
+		let packages = ensureArray(context.metadata?.nodePackageJson);
+		if (packages.length === 0 && !context.completedSources?.has("nodePackageJson")) {
+			log.warn(`Missing nodePackageJson in source context metadata for ${context.options.path}, extracting it now...`);
+			packages = ensureArray(await nodePackageJsonSource.extract(context));
+		}
+		return packages.filter((packageJson) => {
+			if (packageJson.data.private === true || packageJson.data.publishConfig?.access === "restricted") {
+				log.debug(`Skipping NPM registry lookup for "${packageJson.data.name}" in "${context.options.path}" because it is a private package`);
+				return false;
+			}
+			return true;
+		}).map((packageJson) => packageJson.data.name);
+	},
+	key: "nodeNpmRegistry",
+	async parse(input) {
+		log.debug("Extracting npm metadata...");
+		const name = input;
+		const [metadata, downloadsWeekly, downloadsMonthly, downloadsYearly, downloadsTotal] = await Promise.all([
+			packageJson(name, { fullMetadata: true }).catch(() => void 0),
+			fetchDownloads(name, "last-week"),
+			fetchDownloads(name, "last-month"),
+			fetchDownloads(name, "last-year"),
+			fetchDownloads(name, "2005-01-01:3000-01-01")
+		]);
+		if (!metadata) return;
+		const hasTypes = Boolean(metadata.types ?? metadata.typings ?? (is.plainObject(metadata) ? metadata.exports : void 0));
+		const distribution = is.plainObject(metadata.dist) ? metadata.dist : void 0;
+		const time = is.plainObject(metadata.time) ? metadata.time : void 0;
+		return {
+			data: {
+				deprecated: typeof metadata.deprecated === "string" ? metadata.deprecated : void 0,
+				downloadsMonthly,
+				downloadsTotal: downloadsTotal || void 0,
+				downloadsWeekly,
+				downloadsYearly,
+				fileCount: typeof distribution?.fileCount === "number" ? distribution.fileCount : void 0,
+				hasTypes,
+				publishDateLatest: typeof time?.modified === "string" ? time.modified : void 0,
+				unpackedSizeBytes: typeof distribution?.unpackedSize === "number" ? distribution.unpackedSize : void 0,
+				url: `https://www.npmjs.com/package/${encodeURIComponent(name)}`,
+				versionLatest: metadata.version
+			},
+			source: `https://www.npmjs.com/package/${encodeURIComponent(name)}`
+		};
+	},
+	phase: 2
+});
+const npmDownloadsSchema = z.object({ downloads: z.number() });
+async function fetchDownloads(packageName, period) {
+	try {
+		const response = await fetchWithRetry(`https://api.npmjs.org/downloads/point/${period}/${encodeURIComponent(packageName)}`);
+		if (!response.ok) return void 0;
+		return npmDownloadsSchema.parse(await response.json()).downloads;
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { nodeNpmRegistrySource };

package/dist/lib/sources/node-package-json.d.ts

@@ -0,0 +1,7 @@
+import { OneOrMany, SourceRecord } from "../source.js";
+import { NormalizedPackageJson } from "read-pkg";
+
+//#region src/lib/sources/node-package-json.d.ts
+type NodePackageJsonData = OneOrMany<SourceRecord<NormalizedPackageJson>> | undefined;
+//#endregion
+export { NodePackageJsonData };

package/dist/lib/sources/node-package-json.js

@@ -0,0 +1,27 @@
+import { getMatches } from "../file-matching.js";
+import { defineSource } from "../source.js";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parsePackage } from "read-pkg";
+//#region src/lib/sources/node-package-json.ts
+/**
+* Parse package.json content and return structured metadata.
+*/
+function parse(content) {
+	return parsePackage(content);
+}
+const nodePackageJsonSource = defineSource({
+	async discover(context) {
+		return getMatches(context.options, ["package.json"]);
+	},
+	key: "nodePackageJson",
+	async parse(input, context) {
+		return {
+			data: parse(await readFile(resolve(context.options.path, input), "utf8")),
+			source: input
+		};
+	},
+	phase: 1
+});
+//#endregion
+export { nodePackageJsonSource };

package/dist/lib/sources/obsidian-plugin-manifest-json.d.ts

@@ -0,0 +1,17 @@
+import { OneOrMany, SourceRecord } from "../source.js";
+
+//#region src/lib/sources/obsidian-plugin-manifest-json.d.ts
+type ObsidianManifest = {
+  /** Plugin author name. */author?: string; /** URL for the plugin author. */
+  authorUrl?: string; /** Plugin description. */
+  description?: string; /** URL for funding or sponsorship. */
+  fundingUrl?: string; /** Unique plugin identifier. */
+  id: string; /** Whether the plugin is desktop-only. */
+  isDesktopOnly?: boolean; /** Minimum Obsidian app version required. */
+  minAppVersion?: string; /** Display name of the plugin. */
+  name?: string; /** Plugin version string. */
+  version?: string;
+};
+type ObsidianPluginManifestJsonData = OneOrMany<SourceRecord<ObsidianManifest>> | undefined;
+//#endregion
+export { ObsidianPluginManifestJsonData };

package/dist/lib/sources/obsidian-plugin-manifest-json.js

@@ -0,0 +1,34 @@
+import { getMatches } from "../file-matching.js";
+import { defineSource } from "../source.js";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { z } from "zod";
+//#region src/lib/sources/obsidian-plugin-manifest-json.ts
+const manifestSchema = z.object({
+	author: z.string().optional(),
+	authorUrl: z.string().optional(),
+	description: z.string().optional(),
+	fundingUrl: z.string().optional(),
+	id: z.string(),
+	isDesktopOnly: z.boolean().optional(),
+	minAppVersion: z.string().optional(),
+	name: z.string().optional(),
+	version: z.string().optional()
+});
+const obsidianPluginManifestJsonSource = defineSource({
+	async discover(context) {
+		return getMatches(context.options, ["manifest.json"]);
+	},
+	key: "obsidianPluginManifestJson",
+	async parse(input, context) {
+		const content = await readFile(resolve(context.options.path, input), "utf8");
+		const parsed = manifestSchema.safeParse(JSON.parse(content));
+		if (parsed.success) return {
+			data: parsed.data,
+			source: input
+		};
+	},
+	phase: 1
+});
+//#endregion
+export { obsidianPluginManifestJsonSource };

package/dist/lib/sources/obsidian-plugin-registry.d.ts

@@ -0,0 +1,10 @@
+import { OneOrMany, SourceRecord } from "../source.js";
+
+//#region src/lib/sources/obsidian-plugin-registry.d.ts
+type ObsidianPluginRegistryInfo = {
+  /** Total community download count. */downloadCount?: number; /** Obsidian plugin directory URL. */
+  url?: string;
+};
+type ObsidianPluginRegistryData = OneOrMany<SourceRecord<ObsidianPluginRegistryInfo>> | undefined;
+//#endregion
+export { ObsidianPluginRegistryData };

package/dist/lib/sources/obsidian-plugin-registry.js

@@ -0,0 +1,44 @@
+import { log } from "../log.js";
+import { defineSource } from "../source.js";
+import { ensureArray } from "../utilities/template-helpers.js";
+import { fetchWithRetry } from "../utilities/fetch.js";
+import { obsidianPluginManifestJsonSource } from "./obsidian-plugin-manifest-json.js";
+import { z } from "zod";
+//#region src/lib/sources/obsidian-plugin-registry.ts
+const communityPluginsUrl = "https://raw.githubusercontent.com/obsidianmd/obsidian-releases/master/community-plugin-stats.json";
+const pluginStatsSchema = z.record(z.string(), z.record(z.string(), z.number()));
+const obsidianPluginRegistrySource = defineSource({
+	async discover(context) {
+		if (context.options.offline) {
+			log.warn("Skipping Obsidian plugin registry data source since we're in offline mode");
+			return [];
+		}
+		let pluginIds = ensureArray(context.metadata?.obsidianPluginManifestJson).map((value) => value.data.id);
+		if (pluginIds.length === 0 && !context.completedSources?.has("obsidianPluginManifestJson")) {
+			log.warn(`Missing obsidianPluginManifestJson in source context metadata for ${context.options.path}, extracting it now...`);
+			pluginIds = ensureArray(await obsidianPluginManifestJsonSource.extract(context)).map((value) => value.data.id);
+		}
+		return pluginIds;
+	},
+	key: "obsidianPluginRegistry",
+	async parse(input) {
+		log.debug("Extracting Obsidian plugin registry metadata...");
+		const pluginId = input;
+		const url = `https://obsidian.md/plugins?id=${encodeURIComponent(pluginId)}`;
+		const response = await fetchWithRetry(communityPluginsUrl);
+		if (!response.ok) return {
+			data: { url },
+			source: url
+		};
+		return {
+			data: {
+				downloadCount: pluginStatsSchema.parse(await response.json())[pluginId]?.downloads || void 0,
+				url
+			},
+			source: url
+		};
+	},
+	phase: 2
+});
+//#endregion
+export { obsidianPluginRegistrySource };

package/dist/lib/sources/openframeworks-addon-config-mk.d.ts

@@ -0,0 +1,17 @@
+import { OneOrMany, SourceRecord } from "../source.js";
+import { z } from "zod";
+
+//#region src/lib/sources/openframeworks-addon-config-mk.d.ts
+declare const openframeworksAddonConfigSchema: z.ZodObject<{
+  author: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  dependencies: z.ZodPipe<z.ZodTransform<string[], unknown>, z.ZodArray<z.ZodString>>;
+  description: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  name: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  platformSections: z.ZodPipe<z.ZodTransform<string[], unknown>, z.ZodArray<z.ZodString>>;
+  tags: z.ZodPipe<z.ZodTransform<string[], unknown>, z.ZodArray<z.ZodString>>;
+  url: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+type OpenframeworksAddonConfig = z.infer<typeof openframeworksAddonConfigSchema>;
+type OpenframeworksAddonConfigMkData = OneOrMany<SourceRecord<OpenframeworksAddonConfig>> | undefined;
+//#endregion
+export { OpenframeworksAddonConfigMkData };

package/dist/lib/sources/openframeworks-addon-config-mk.js

@@ -0,0 +1,39 @@
+import { getMatches } from "../file-matching.js";
+import { defineSource } from "../source.js";
+import { nonEmptyString, optionalUrl, stringArray } from "../utilities/schema-primitives.js";
+import { parseMakefileConfig } from "../parsers/makefile-config-parser.js";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { z } from "zod";
+//#region src/lib/sources/openframeworks-addon-config-mk.ts
+const openframeworksAddonConfigSchema = z.object({
+	author: nonEmptyString,
+	dependencies: stringArray,
+	description: nonEmptyString,
+	name: nonEmptyString,
+	platformSections: stringArray,
+	tags: stringArray,
+	url: optionalUrl
+});
+/**
+* Parse an `addon_config.mk` file and return validated metadata.
+*/
+function parse(content) {
+	const raw = parseMakefileConfig(content);
+	return openframeworksAddonConfigSchema.parse(raw);
+}
+const openframeworksAddonConfigMkSource = defineSource({
+	async discover(context) {
+		return getMatches(context.options, ["addon_config.mk"]);
+	},
+	key: "openframeworksAddonConfigMk",
+	async parse(input, context) {
+		return {
+			data: parse(await readFile(resolve(context.options.path, input), "utf8")),
+			source: input
+		};
+	},
+	phase: 1
+});
+//#endregion
+export { openframeworksAddonConfigMkSource };

package/dist/lib/sources/openframeworks-install-xml.d.ts

@@ -0,0 +1,20 @@
+import { OneOrMany, SourceRecord } from "../source.js";
+import { z } from "zod";
+
+//#region src/lib/sources/openframeworks-install-xml.d.ts
+declare const openframeworksInstallXmlSchema: z.ZodObject<{
+  author: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  codeUrl: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  description: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  downloadUrl: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  name: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  operatingSystems: z.ZodPipe<z.ZodTransform<string[], unknown>, z.ZodArray<z.ZodString>>;
+  requirements: z.ZodPipe<z.ZodTransform<string[], unknown>, z.ZodArray<z.ZodString>>;
+  siteUrl: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  url: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  version: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+type OpenframeworksInstallXml = z.infer<typeof openframeworksInstallXmlSchema>;
+type OpenframeworksInstallXmlData = OneOrMany<SourceRecord<OpenframeworksInstallXml>> | undefined;
+//#endregion
+export { OpenframeworksInstallXmlData };

package/dist/lib/sources/openframeworks-install-xml.js

@@ -0,0 +1,153 @@
+import { getMatches } from "../file-matching.js";
+import { defineSource } from "../source.js";
+import { nonEmptyString, optionalUrl, stringArray } from "../utilities/schema-primitives.js";
+import { ensureArray } from "../utilities/template-helpers.js";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import is from "@sindresorhus/is";
+import { z } from "zod";
+import { XMLParser } from "fast-xml-parser";
+//#region src/lib/sources/openframeworks-install-xml.ts
+/**
+* Source and parser for legacy openFrameworks addon `install.xml` files.
+*
+* This is a legacy format predating `addon_config.mk`. The root element is
+* `<install>`, with flat metadata elements (`<name>`, `<version>`, `<author>`,
+* etc.) followed by build configuration in an `<add>` block.
+*
+* Since `install.xml` is a generic filename, the parser validates that the
+* content is actually an openFrameworks addon by checking for the `<install>`
+* root element and the presence of "addons" in the file content.
+*
+* Uses `fast-xml-parser` with attribute parsing enabled to read `<lib os="...">`
+* attributes for operating system inference.
+*/
+const openframeworksInstallXmlSchema = z.object({
+	author: nonEmptyString,
+	codeUrl: optionalUrl,
+	description: nonEmptyString,
+	downloadUrl: optionalUrl,
+	name: nonEmptyString,
+	operatingSystems: stringArray,
+	requirements: stringArray,
+	siteUrl: optionalUrl,
+	url: optionalUrl,
+	version: nonEmptyString
+});
+/**
+* Map `<lib os="...">` attribute values to human-readable OS names.
+*/
+const LIB_OS_MAP = {
+	linux: "Linux",
+	mac: "macOS",
+	win32: "Windows"
+};
+/**
+* Parse a legacy openFrameworks `install.xml` content string into a structured object.
+* Returns undefined if the XML is malformed, missing the `<install>` root element,
+* or does not appear to be an openFrameworks addon.
+*/
+function parse(content) {
+	if (!content.toLowerCase().includes("addons")) return;
+	const fixedContent = content.replaceAll("<[CDATA[", "<![CDATA[");
+	const parser = new XMLParser({
+		attributeNamePrefix: "@_",
+		ignoreAttributes: false,
+		parseTagValue: false
+	});
+	let data;
+	try {
+		const parsed = parser.parse(fixedContent);
+		if (!is.plainObject(parsed)) return void 0;
+		data = parsed;
+	} catch {
+		return;
+	}
+	if (!is.plainObject(data.install)) return void 0;
+	const { install } = data;
+	return openframeworksInstallXmlSchema.parse({
+		author: getString(install.author),
+		codeUrl: getString(install.code_url),
+		description: getString(install.description),
+		downloadUrl: getString(install.download_url),
+		name: getString(install.name),
+		operatingSystems: parseOperatingSystems(install),
+		requirements: parseRequirements(install),
+		siteUrl: getString(install.site_url),
+		url: getString(install.url),
+		version: getString(install.version)
+	});
+}
+/**
+* Get a trimmed non-empty string from a parsed XML value.
+* Returns undefined for empty strings, non-strings, or whitespace-only values.
+*/
+function getString(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : void 0;
+}
+/**
+* Extract software requirements from `<requires>`.
+* Handles three variants:
+* 1. Empty — skip
+* 2. Free text — emit as-is
+* 3. Structured `<addon>` children — emit each separately
+*/
+function parseRequirements(install) {
+	const { requires } = install;
+	if (requires === void 0 || requires === null) return [];
+	if (typeof requires === "string") {
+		const trimmed = requires.trim();
+		return trimmed.length > 0 ? [trimmed] : [];
+	}
+	if (is.plainObject(requires)) {
+		const results = [];
+		for (const addon of ensureArray(requires.addon)) {
+			const name = getString(addon);
+			if (name) results.push(name);
+		}
+		return results;
+	}
+	return [];
+}
+/**
+* Extract operating system information from `<lib os="...">` attributes
+* found within `<add><link>` sections.
+*/
+function parseOperatingSystems(install) {
+	if (!is.plainObject(install.add)) return [];
+	const { add } = install;
+	if (!is.plainObject(add.link)) return [];
+	const { link } = add;
+	const results = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const library of ensureArray(link.lib)) {
+		if (!is.plainObject(library)) continue;
+		const os = getString(library["@_os"]);
+		if (os) {
+			const mapped = LIB_OS_MAP[os.toLowerCase()] ?? os;
+			if (!seen.has(mapped)) {
+				seen.add(mapped);
+				results.push(mapped);
+			}
+		}
+	}
+	return results;
+}
+const openframeworksInstallXmlSource = defineSource({
+	async discover(context) {
+		return getMatches(context.options, ["install.xml"]);
+	},
+	key: "openframeworksInstallXml",
+	async parse(input, context) {
+		const data = parse(await readFile(resolve(context.options.path, input), "utf8"));
+		if (data !== void 0) return {
+			data,
+			source: input
+		};
+	},
+	phase: 1
+});
+//#endregion
+export { openframeworksInstallXmlSource };

package/dist/lib/sources/processing-library-properties.d.ts

@@ -0,0 +1,44 @@
+import { OneOrMany, SourceRecord } from "../source.js";
+import { z } from "zod";
+
+//#region src/lib/sources/processing-library-properties.d.ts
+declare const processingLibraryPropertiesSchema: z.ZodObject<{
+  authors: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  categories: z.ZodArray<z.ZodEnum<{
+    GUI: "GUI";
+    "3D": "3D";
+    Animation: "Animation";
+    Compilations: "Compilations";
+    Data: "Data";
+    Fabrication: "Fabrication";
+    Geometry: "Geometry";
+    Hardware: "Hardware";
+    "I/O": "I/O";
+    Language: "Language";
+    Math: "Math";
+    Simulation: "Simulation";
+    Sound: "Sound";
+    Utilities: "Utilities";
+    Typography: "Typography";
+    "Video & Vision": "Video & Vision";
+  }>>;
+  download: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  id: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  maxRevision: z.ZodNumber;
+  minRevision: z.ZodNumber;
+  name: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  paragraph: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  prettyVersion: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  raw: z.ZodRecord<z.ZodString, z.ZodString>;
+  sentence: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  type: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  url: z.ZodPipe<z.ZodTransform<string | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+  version: z.ZodNumber;
+}, z.core.$strip>;
+type ProcessingLibraryProperties = z.infer<typeof processingLibraryPropertiesSchema>;
+type ProcessingLibraryPropertiesData = OneOrMany<SourceRecord<ProcessingLibraryProperties>> | undefined;
+//#endregion
+export { ProcessingLibraryPropertiesData };