metascope 0.1.0 → 0.2.0

package/dist/lib/log.d.ts

@@ -0,0 +1,11 @@
+import { ILogBasic, ILogLayer } from "lognow";
+
+//#region src/lib/log.d.ts
+/**
+ * Set the logger instance for the module.
+ * Export this for library consumers to inject their own logger.
+ * @param logger - Accepts either a LogLayer instance or a Console- or Stream-like log target
+ */
+declare function setLogger(logger?: ILogBasic | ILogLayer): void;
+//#endregion
+export { setLogger };

package/dist/lib/log.js

@@ -0,0 +1,20 @@
+import { name } from "./package.js";
+import { createLogger, injectionHelper } from "lognow";
+//#region src/lib/log.ts
+/**
+* The default logger instance for the library.
+*/
+let log = createLogger({
+	logToConsole: { showTime: false },
+	name
+});
+/**
+* Set the logger instance for the module.
+* Export this for library consumers to inject their own logger.
+* @param logger - Accepts either a LogLayer instance or a Console- or Stream-like log target
+*/
+function setLogger(logger) {
+	log = injectionHelper(logger);
+}
+//#endregion
+export { log, setLogger };

package/dist/lib/metadata-types.d.ts

@@ -0,0 +1,151 @@
+import { ArduinoLibraryPropertiesData } from "./sources/arduino-library-properties.js";
+import { CinderCinderblockXmlData } from "./sources/cinder-cinderblock-xml.js";
+import { CodeStatsData } from "./sources/code-stats.js";
+import { CodeMetaJsonData } from "./sources/codemeta-json.js";
+import { DependencyUpdatesData } from "./sources/dependency-updates.js";
+import { FileStatsData } from "./sources/file-stats.js";
+import { GitConfigData } from "./sources/git-config.js";
+import { GitStatsData } from "./sources/git-stats.js";
+import { GitHubData } from "./sources/github.js";
+import { GoGoModData } from "./sources/go-go-mod.js";
+import { GoGoreleaserYamlData } from "./sources/go-goreleaser-yaml.js";
+import { JavaPomXmlData } from "./sources/java-pom-xml.js";
+import { LicenseFileData } from "./sources/license-file.js";
+import { MetadataFileData } from "./sources/metadata-file.js";
+import { MetascopeData } from "./sources/metascope.js";
+import { NodeNpmRegistryData } from "./sources/node-npm-registry.js";
+import { NodePackageJsonData } from "./sources/node-package-json.js";
+import { ObsidianPluginManifestJsonData } from "./sources/obsidian-plugin-manifest-json.js";
+import { ObsidianPluginRegistryData } from "./sources/obsidian-plugin-registry.js";
+import { OpenframeworksAddonConfigMkData } from "./sources/openframeworks-addon-config-mk.js";
+import { OpenframeworksInstallXmlData } from "./sources/openframeworks-install-xml.js";
+import { ProcessingLibraryPropertiesData } from "./sources/processing-library-properties.js";
+import { ProcessingSketchPropertiesData } from "./sources/processing-sketch-properties.js";
+import { PubliccodeYamlData } from "./sources/publiccode-yaml.js";
+import { PythonPkgInfoData } from "./sources/python-pkg-info.js";
+import { PythonPypiRegistryData } from "./sources/python-pypi-registry.js";
+import { PythonPyprojectTomlData } from "./sources/python-pyproject-toml.js";
+import { PythonSetupCfgData } from "./sources/python-setup-cfg.js";
+import { PythonSetupPyData } from "./sources/python-setup-py.js";
+import { ReadmeFileData } from "./sources/readme-file.js";
+import { RubyGemspecData } from "./sources/ruby-gemspec.js";
+import { RustCargoTomlData } from "./sources/rust-cargo-toml.js";
+import { XcodeInfoPlistData } from "./sources/xcode-info-plist.js";
+import { XcodeProjectPbxprojData } from "./sources/xcode-project-pbxproj.js";
+
+//#region src/lib/metadata-types.d.ts
+/**
+ * The complete metadata context assembled from all sources.
+ * Each key corresponds to a metadata source.
+ */
+type MetadataContext = {
+  arduinoLibraryProperties: ArduinoLibraryPropertiesData;
+  cinderCinderblockXml: CinderCinderblockXmlData;
+  codemetaJson: CodeMetaJsonData;
+  codeStats: CodeStatsData;
+  dependencyUpdates: DependencyUpdatesData;
+  fileStats: FileStatsData;
+  gitConfig: GitConfigData;
+  github: GitHubData;
+  gitStats: GitStatsData;
+  goGoMod: GoGoModData;
+  goGoreleaserYaml: GoGoreleaserYamlData;
+  javaPomXml: JavaPomXmlData;
+  licenseFile: LicenseFileData;
+  metadataFile: MetadataFileData;
+  metascope: MetascopeData;
+  nodeNpmRegistry: NodeNpmRegistryData;
+  nodePackageJson: NodePackageJsonData;
+  obsidianPluginManifestJson: ObsidianPluginManifestJsonData;
+  obsidianPluginRegistry: ObsidianPluginRegistryData;
+  openframeworksAddonConfigMk: OpenframeworksAddonConfigMkData;
+  openframeworksInstallXml: OpenframeworksInstallXmlData;
+  processingLibraryProperties: ProcessingLibraryPropertiesData;
+  processingSketchProperties: ProcessingSketchPropertiesData;
+  publiccodeYaml: PubliccodeYamlData;
+  pythonPkgInfo: PythonPkgInfoData;
+  pythonPypiRegistry: PythonPypiRegistryData;
+  pythonPyprojectToml: PythonPyprojectTomlData;
+  pythonSetupCfg: PythonSetupCfgData;
+  pythonSetupPy: PythonSetupPyData;
+  readmeFile: ReadmeFileData;
+  rubyGemspec: RubyGemspecData;
+  rustCargoToml: RustCargoTomlData;
+  xcodeInfoPlist: XcodeInfoPlistData;
+  xcodeProjectPbxproj: XcodeProjectPbxprojData;
+};
+/**
+ * The name of a metadata source.
+ */
+type SourceName = keyof MetadataContext;
+/**
+ * User-supplied data passed to templates for parameterized ownership checks.
+ * All fields are optional; templates that don't need them can ignore the argument.
+ */
+type TemplateData = {
+  [key: string]: unknown;
+  authorName?: string | string[];
+  githubAccount?: string | string[];
+};
+/**
+ * A template function that transforms MetadataContext into a custom shape.
+ * The optional second argument provides user-supplied template data.
+ */
+type Template<T> = (context: MetadataContext, templateData: TemplateData) => T;
+/**
+ * Identity wrapper for type inference in config files.
+ * Use this in `metascope.config.ts` to get autocomplete on available fields.
+ * @example
+ * ```typescript
+ * import { defineTemplate } from 'metascope'
+ *
+ * export default defineTemplate(({ codemetaJson, github }) => ({
+ *   name: codemetaJson?.data.name,
+ *   stars: github?.data.stargazerCount,
+ * }))
+ * ```
+ */
+declare function defineTemplate<T>(transform: Template<T>): Template<T>;
+/**
+ * API credentials for remote metadata sources.
+ */
+type Credentials = {
+  githubToken?: string;
+};
+/**
+ * Base options shared by all `getMetadata` overloads.
+ */
+type GetMetadataBaseOptions = {
+  /** When true (the default), all paths in the output (source, workspaceDirectories, etc.) are absolute. When false, paths are relative to the project directory. */absolute?: boolean; /** API credentials for remote sources. */
+  credentials?: Credentials; /** Skip web sources (npm registry, GitHub API, PyPI, etc.). */
+  offline?: boolean; /** Project directory path. Defaults to `'.'` (resolved to `process.cwd()` via `path.resolve`). */
+  path: string; /** Search for metadata files recursively in subdirectories. Defaults to false. */
+  recursive?: boolean; /** Ignore files specified .gitignore in the file tree. Defaults to true. */
+  respectIgnored?: boolean; /** Only run these specific sources. Defaults to all sources when undefined. */
+  sources?: SourceName[]; /** User-supplied data passed to templates. */
+  templateData?: TemplateData;
+  /**
+   * Directories to any monorepo workspaces... only supports yarn, npm, pnpm, lerna, and bolt at the moment
+   * Never includes the root path!
+   * False is disable, true is auto-discover which turns into string[], string[] is manual list relative to the project directory path...
+   */
+  workspaces?: boolean | string[];
+};
+/**
+ * Default values for optional fields in `GetMetadataBaseOptions`.
+ */
+declare const DEFAULT_GET_METADATA_OPTIONS: Required<Omit<GetMetadataBaseOptions, 'credentials' | 'sources' | 'templateData'>>;
+/**
+ * Options for `getMetadata` without a template (returns full `MetadataContext`).
+ */
+type GetMetadataOptions = GetMetadataBaseOptions & {
+  /** Built-in template name or omit for full output. */template?: 'frontmatter' | 'metadata' | 'project' | (string & {});
+};
+/**
+ * Options for `getMetadata` with a template function (returns the template's return type).
+ */
+type GetMetadataTemplateOptions<T> = GetMetadataBaseOptions & {
+  /** Template function that transforms MetadataContext into a custom shape. */template: Template<T>;
+};
+//#endregion
+export { Credentials, DEFAULT_GET_METADATA_OPTIONS, GetMetadataBaseOptions, GetMetadataOptions, GetMetadataTemplateOptions, MetadataContext, SourceName, Template, TemplateData, defineTemplate };

package/dist/lib/metadata-types.js

@@ -0,0 +1,30 @@
+//#region src/lib/metadata-types.ts
+/**
+* Identity wrapper for type inference in config files.
+* Use this in `metascope.config.ts` to get autocomplete on available fields.
+* @example
+* ```typescript
+* import { defineTemplate } from 'metascope'
+*
+* export default defineTemplate(({ codemetaJson, github }) => ({
+*   name: codemetaJson?.data.name,
+*   stars: github?.data.stargazerCount,
+* }))
+* ```
+*/
+function defineTemplate(transform) {
+	return transform;
+}
+/**
+* Default values for optional fields in `GetMetadataBaseOptions`.
+*/
+const DEFAULT_GET_METADATA_OPTIONS = {
+	absolute: true,
+	offline: false,
+	path: ".",
+	recursive: false,
+	respectIgnored: true,
+	workspaces: true
+};
+//#endregion
+export { DEFAULT_GET_METADATA_OPTIONS, defineTemplate };

package/dist/lib/metadata.d.ts

@@ -0,0 +1,16 @@
+import { GetMetadataOptions, GetMetadataTemplateOptions, MetadataContext, SourceName } from "./metadata-types.js";
+import { TemplateMap, TemplateName } from "./templates/index.js";
+
+//#region src/lib/metadata.d.ts
+/** All available source key names, for runtime use (e.g. CLI choices). */
+declare const sourceNames: SourceName[];
+type PartialPath<T> = Omit<T, 'path'> & {
+  path?: string;
+};
+declare function getMetadata<K extends TemplateName>(options: PartialPath<Omit<GetMetadataOptions, 'template'> & {
+  template: K;
+}>): Promise<TemplateMap[K]>;
+declare function getMetadata<T>(options: PartialPath<GetMetadataTemplateOptions<T>>): Promise<T>;
+declare function getMetadata(options?: PartialPath<GetMetadataOptions>): Promise<MetadataContext>;
+//#endregion
+export { getMetadata, sourceNames };

package/dist/lib/metadata.js

@@ -0,0 +1,235 @@
+import { log } from "./log.js";
+import { getTree, resetMatchCache } from "./file-matching.js";
+import { DEFAULT_GET_METADATA_OPTIONS } from "./metadata-types.js";
+import { stripUndefined } from "./utilities/template-helpers.js";
+import { arduinoLibraryPropertiesSource } from "./sources/arduino-library-properties.js";
+import { cinderCinderblockXmlSource } from "./sources/cinder-cinderblock-xml.js";
+import { codeStatsSource } from "./sources/code-stats.js";
+import { codemetaJsonSource } from "./sources/codemeta-json.js";
+import { dependencyUpdatesSource } from "./sources/dependency-updates.js";
+import { fileStatsSource } from "./sources/file-stats.js";
+import { gitConfigSource } from "./sources/git-config.js";
+import { gitStatsSource } from "./sources/git-stats.js";
+import { githubSource } from "./sources/github.js";
+import { goGoModSource } from "./sources/go-go-mod.js";
+import { goGoreleaserYamlSource } from "./sources/go-goreleaser-yaml.js";
+import { javaPomXmlSource } from "./sources/java-pom-xml.js";
+import { licenseFileSource } from "./sources/license-file.js";
+import { metadataFileSource } from "./sources/metadata-file.js";
+import { metascopeSource } from "./sources/metascope.js";
+import { nodePackageJsonSource } from "./sources/node-package-json.js";
+import { nodeNpmRegistrySource } from "./sources/node-npm-registry.js";
+import { obsidianPluginManifestJsonSource } from "./sources/obsidian-plugin-manifest-json.js";
+import { obsidianPluginRegistrySource } from "./sources/obsidian-plugin-registry.js";
+import { openframeworksAddonConfigMkSource } from "./sources/openframeworks-addon-config-mk.js";
+import { openframeworksInstallXmlSource } from "./sources/openframeworks-install-xml.js";
+import { processingLibraryPropertiesSource } from "./sources/processing-library-properties.js";
+import { processingSketchPropertiesSource } from "./sources/processing-sketch-properties.js";
+import { publiccodeYamlSource } from "./sources/publiccode-yaml.js";
+import { pythonPkgInfoSource } from "./sources/python-pkg-info.js";
+import { pythonPyprojectTomlSource } from "./sources/python-pyproject-toml.js";
+import { pythonSetupCfgSource } from "./sources/python-setup-cfg.js";
+import { pythonSetupPySource } from "./sources/python-setup-py.js";
+import { pythonPypiRegistrySource } from "./sources/python-pypi-registry.js";
+import { readmeFileSource } from "./sources/readme-file.js";
+import { rubyGemspecSource } from "./sources/ruby-gemspec.js";
+import { rustCargoTomlSource } from "./sources/rust-cargo-toml.js";
+import { xcodeInfoPlistSource } from "./sources/xcode-info-plist.js";
+import { xcodeProjectPbxprojSource } from "./sources/xcode-project-pbxproj.js";
+import { isKeyOfTemplate, templates } from "./templates/index.js";
+import { defu } from "defu";
+import { execFile } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { promisify } from "node:util";
+import prettyMs from "pretty-ms";
+//#region src/lib/metadata.ts
+const execFileAsync = promisify(execFile);
+/**
+* All registered metadata sources.
+* Each source declares its `phase` number. Sources with the same phase run in parallel.
+* Lower phases run first, and their accumulated results are available to later phases
+* via `context` in `SourceContext`.
+*/
+const sources = [
+	arduinoLibraryPropertiesSource,
+	cinderCinderblockXmlSource,
+	codemetaJsonSource,
+	gitConfigSource,
+	goGoModSource,
+	goGoreleaserYamlSource,
+	javaPomXmlSource,
+	licenseFileSource,
+	metadataFileSource,
+	metascopeSource,
+	nodePackageJsonSource,
+	obsidianPluginManifestJsonSource,
+	openframeworksAddonConfigMkSource,
+	openframeworksInstallXmlSource,
+	processingLibraryPropertiesSource,
+	processingSketchPropertiesSource,
+	publiccodeYamlSource,
+	pythonPkgInfoSource,
+	pythonPyprojectTomlSource,
+	pythonSetupCfgSource,
+	pythonSetupPySource,
+	readmeFileSource,
+	rubyGemspecSource,
+	rustCargoTomlSource,
+	xcodeInfoPlistSource,
+	xcodeProjectPbxprojSource,
+	codeStatsSource,
+	dependencyUpdatesSource,
+	fileStatsSource,
+	gitStatsSource,
+	githubSource,
+	nodeNpmRegistrySource,
+	obsidianPluginRegistrySource,
+	pythonPypiRegistrySource
+];
+/** All available source key names, for runtime use (e.g. CLI choices). */
+const sourceNames = sources.map((s) => s.key);
+/**
+* Resolve GitHub token from multiple sources, in precedence order.
+*/
+async function resolveCredentials(credentials) {
+	if (credentials?.githubToken) return credentials;
+	const environmentToken = process.env.GITHUB_TOKEN;
+	if (environmentToken) return {
+		...credentials,
+		githubToken: environmentToken
+	};
+	try {
+		const { stdout } = await execFileAsync("gh", ["auth", "token"]);
+		const token = stdout.trim();
+		if (token) return {
+			...credentials,
+			githubToken: token
+		};
+	} catch {}
+	return credentials ?? {};
+}
+/**
+* Resolve a template option to a template function.
+* Accepts a built-in template name (string) or a template function.
+*/
+function resolveTemplate(template) {
+	if (template === void 0) return void 0;
+	if (typeof template === "function") return template;
+	if (isKeyOfTemplate(template)) return templates[template];
+	log.warn(`Unknown template: "${template}". Using default (all fields).`);
+}
+/**
+* Check availability and extract data from a set of sources in parallel,
+* writing results into the provided MetadataContext.
+*/
+async function runSources(phaseSources, sourceContext, result) {
+	const extractResults = await Promise.all(phaseSources.map(async (source) => {
+		try {
+			const startTime = performance.now();
+			const data = await source.extract(sourceContext);
+			const duration = Math.round(performance.now() - startTime);
+			log.debug(`Source "${source.key}" extracted in ${duration}ms`);
+			return {
+				data,
+				key: source.key
+			};
+		} catch (error) {
+			log.warn(`Source "${source.key}" extraction failed: ${error instanceof Error ? error.message : String(error)}`);
+			return {
+				data: void 0,
+				key: source.key
+			};
+		}
+	}));
+	for (const entry of extractResults) if (entry.data !== void 0) Object.assign(result, { [entry.key]: entry.data });
+}
+/**
+* Extract metadata from a project directory.
+*/
+async function getMetadata(options) {
+	const startTime = performance.now();
+	const resolvedOptions = defu(options ?? {}, DEFAULT_GET_METADATA_OPTIONS);
+	const absolutePath = resolve(resolvedOptions.path);
+	let stats;
+	try {
+		stats = await stat(absolutePath);
+	} catch {
+		throw new Error(`Path does not exist: ${absolutePath}`);
+	}
+	if (!stats.isDirectory()) throw new Error(`Path is not a directory: ${absolutePath}`);
+	const template = resolveTemplate(resolvedOptions.template);
+	resetMatchCache();
+	log.debug(`Building file tree (respectIgnored: ${resolvedOptions.respectIgnored})...`);
+	const [credentials, rootTree] = await Promise.all([resolveCredentials(resolvedOptions.credentials), getTree(absolutePath, resolvedOptions.respectIgnored)]);
+	log.debug(`Root file tree contains ${rootTree.length} entries`);
+	const context = {
+		arduinoLibraryProperties: void 0,
+		cinderCinderblockXml: void 0,
+		codemetaJson: void 0,
+		codeStats: void 0,
+		dependencyUpdates: void 0,
+		fileStats: void 0,
+		gitConfig: void 0,
+		github: void 0,
+		gitStats: void 0,
+		goGoMod: void 0,
+		goGoreleaserYaml: void 0,
+		javaPomXml: void 0,
+		licenseFile: void 0,
+		metadataFile: void 0,
+		metascope: void 0,
+		nodeNpmRegistry: void 0,
+		nodePackageJson: void 0,
+		obsidianPluginManifestJson: void 0,
+		obsidianPluginRegistry: void 0,
+		openframeworksAddonConfigMk: void 0,
+		openframeworksInstallXml: void 0,
+		processingLibraryProperties: void 0,
+		processingSketchProperties: void 0,
+		publiccodeYaml: void 0,
+		pythonPkgInfo: void 0,
+		pythonPypiRegistry: void 0,
+		pythonPyprojectToml: void 0,
+		pythonSetupCfg: void 0,
+		pythonSetupPy: void 0,
+		readmeFile: void 0,
+		rubyGemspec: void 0,
+		rustCargoToml: void 0,
+		xcodeInfoPlist: void 0,
+		xcodeProjectPbxproj: void 0
+	};
+	const activeSources = resolvedOptions.sources ? sources.filter((s) => resolvedOptions.sources.includes(s.key)) : sources;
+	const completedSources = /* @__PURE__ */ new Set();
+	const phases = new Set(activeSources.map((s) => s.phase));
+	for (const phase of [...phases].toSorted((a, b) => a - b)) {
+		const phaseSources = activeSources.filter((s) => s.phase === phase);
+		log.debug(`Phase ${phase}: Running ${phaseSources.length} sources...`);
+		await runSources(phaseSources, {
+			completedSources,
+			metadata: { ...context },
+			options: {
+				...resolvedOptions,
+				credentials,
+				path: absolutePath
+			}
+		}, context);
+		for (const source of phaseSources) completedSources.add(source.key);
+	}
+	const metadataDuration = performance.now() - startTime;
+	if (context.metascope) context.metascope.data.durationMs = Math.round(metadataDuration);
+	log.debug(`Metadata duration: ${prettyMs(metadataDuration)}`);
+	if (template) {
+		const templateStartTime = performance.now();
+		const finalTemplateResult = stripUndefined(template(context, resolvedOptions.templateData ?? {})) ?? {};
+		const templateDuration = performance.now() - templateStartTime;
+		log.debug(`Template duration: ${prettyMs(templateDuration)}`);
+		log.debug(`Total duration: ${prettyMs(performance.now() - startTime)}`);
+		return finalTemplateResult;
+	}
+	const finalResult = stripUndefined(context);
+	log.debug(`Total duration: ${prettyMs(performance.now() - startTime)}`);
+	return finalResult;
+}
+//#endregion
+export { getMetadata, sourceNames };

package/dist/lib/package.js

@@ -0,0 +1,5 @@
+//#region package.json
+var name = "metascope";
+var version = "0.2.0";
+//#endregion
+export { name, version };

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

@@ -0,0 +1,43 @@
+//#region src/lib/parsers/configparser-parser.ts
+/**
+* Parse a ConfigParser-style INI file into sections with key-value pairs.
+* Handles Python ConfigParser conventions: multi-line values via indented
+* continuation lines, `#` and `;` comments.
+*/
+function parseConfigparser(content) {
+	const sections = {};
+	let currentSection = "";
+	let lastKey = "";
+	for (const line of content.split("\n")) {
+		const trimmed = line.trimEnd();
+		if (trimmed === "" || trimmed.startsWith("#") || trimmed.startsWith(";")) continue;
+		const sectionMatch = /^\[([^\]]+)\]/.exec(trimmed);
+		if (sectionMatch) {
+			currentSection = sectionMatch[1];
+			sections[currentSection] ??= {};
+			lastKey = "";
+			continue;
+		}
+		if (/^\s/.test(line) && lastKey && currentSection) {
+			const existing = sections[currentSection][lastKey];
+			const continuation = trimmed.trim();
+			if (continuation) sections[currentSection][lastKey] = existing ? `${existing}\n${continuation}` : continuation;
+			continue;
+		}
+		const kvMatch = /^([^=:]+)[=:](.*)$/.exec(trimmed);
+		if (kvMatch && currentSection) {
+			const key = kvMatch[1].trim();
+			const value = kvMatch[2].trim();
+			sections[currentSection] ??= {};
+			sections[currentSection][key] = value;
+			lastKey = key;
+		}
+	}
+	return sections;
+}
+/** Split a multi-line value into individual non-empty lines. */
+function splitMultiline(value) {
+	return value.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+}
+//#endregion
+export { parseConfigparser, splitMultiline };