metascope 0.1.0 → 0.2.0

package/dist/lib/templates/frontmatter.js

@@ -0,0 +1,111 @@
+import { defineTemplate } from "../metadata-types.js";
+import { REPLACEMENTS, dependencyNames, firstOf, isValidUrl, mixedStringsToArray, nonEmpty, toAlias, toBasicLicenses, toBasicNames, toLocalUrl, toMb, toStatus } from "../utilities/template-helpers.js";
+import { codeMetaJsonDataSchema } from "../sources/codemeta-json.js";
+import { codemeta } from "./codemeta.js";
+import is from "@sindresorhus/is";
+//#region src/lib/templates/frontmatter.ts
+/**
+* A compact, non-nested, polyglot overview of the project.
+* Designed for Obsidian frontmatter — flat keys with natural language names,
+* blending all available sources into a single trackable snapshot.
+*/
+const frontmatter = defineTemplate((context, templateData) => {
+	const codemetaTemplateOutput = codemeta(context, templateData);
+	const codemeta$1 = codeMetaJsonDataSchema.parse(codemetaTemplateOutput);
+	const codeStats = firstOf(context.codeStats)?.data;
+	const dependencyUpdates = firstOf(context.dependencyUpdates);
+	const fileStats = firstOf(context.fileStats)?.data;
+	const cinderCinderblockXml = firstOf(context.cinderCinderblockXml)?.data;
+	const github = firstOf(context.github)?.data;
+	const gitStats = firstOf(context.gitStats)?.data;
+	const metascope = context.metascope?.data;
+	const nodeNpmRegistry = firstOf(context.nodeNpmRegistry)?.data;
+	const obsidianPluginManifestJson = firstOf(context.obsidianPluginManifestJson)?.data;
+	const obsidianPluginRegistry = firstOf(context.obsidianPluginRegistry)?.data;
+	const pythonPypiRegistry = firstOf(context.pythonPypiRegistry)?.data;
+	const primaryLanguages = mixedStringsToArray(codemeta$1.programmingLanguage ?? github?.primaryLanguage, REPLACEMENTS) ?? null;
+	const secondaryLanguages = mixedStringsToArray(codeStats?.total?.languages, REPLACEMENTS)?.filter((value) => !primaryLanguages?.includes(value)) ?? null;
+	const rawName = codemeta$1.name === "undefined" ? null : cinderCinderblockXml === void 0 ? codemeta$1.name : `Cinder ${codemeta$1.name}`;
+	const id = codemeta$1.identifier ?? rawName;
+	const name = is.nonEmptyString(rawName) ? toAlias(rawName) : void 0;
+	const aliases = id === name ? void 0 : id;
+	return {
+		Name: name ?? null,
+		ID: id ?? null,
+		Description: codemeta$1.description ?? null,
+		Author: mixedStringsToArray(toBasicNames(codemeta$1.author)) ?? null,
+		Contributor: mixedStringsToArray(toBasicNames(codemeta$1.contributor)) ?? null,
+		Maintainer: mixedStringsToArray(toBasicNames(codemeta$1.maintainer)) ?? null,
+		Version: codemeta$1.version ?? null,
+		Account: github?.ownerLogin ?? null,
+		Public: !(github?.isPrivate ?? false),
+		Fork: github?.isFork ?? false,
+		Published: Boolean(obsidianPluginRegistry?.url ?? nodeNpmRegistry?.url ?? pythonPypiRegistry?.url),
+		Status: toStatus(codemeta$1.codeRepository, codemeta$1.author, [...codemeta$1.contributor ?? [], ...codemeta$1.maintainer ?? []], github?.isFork ?? false, templateData.authorName, templateData.githubAccount),
+		Tags: codemeta$1.keywords ?? null,
+		Aliases: nonEmpty([aliases]) ?? null,
+		License: toBasicLicenses(codemeta$1.license) ?? null,
+		Language: primaryLanguages,
+		"Secondary Language": secondaryLanguages,
+		"Repo Path": metascope?.options.path === void 0 ? null : `file://${metascope.options.path}`,
+		"VS Code Path": metascope?.options.path === void 0 ? null : `vscode://file/${metascope.options.path}`,
+		"Readme Path": toLocalUrl(codemeta$1.readme, metascope?.options.path) ?? null,
+		"Homepage URL": codemeta$1.url !== void 0 && !codemeta$1.url.startsWith("https://github.com/") ? codemeta$1.url : null,
+		"Repo URL": codemeta$1.codeRepository ?? github?.url ?? null,
+		"Issues URL": codemeta$1.issueTracker ?? null,
+		"Readme URL": codemeta$1.readme !== void 0 && isValidUrl(codemeta$1.readme) ? codemeta$1.readme : null,
+		"Package URL": obsidianPluginRegistry?.url ?? nodeNpmRegistry?.url ?? pythonPypiRegistry?.url ?? null,
+		Created: codemeta$1.dateCreated ?? null,
+		"First Commit Date": gitStats?.commitDateFirst ?? null,
+		"Latest Commit Date": gitStats?.commitDateLast ?? null,
+		"Latest Push Date": github?.pushedAt ?? null,
+		"Latest Release Date": github?.releaseDateLatest ?? nodeNpmRegistry?.publishDateLatest ?? pythonPypiRegistry?.publishDateLatest ?? gitStats?.tagVersionDateLatest ?? null,
+		"Latest Release Version": obsidianPluginManifestJson?.version ?? nodeNpmRegistry?.versionLatest ?? pythonPypiRegistry?.versionLatest ?? github?.releaseVersionLatest ?? gitStats?.tagVersionLatest ?? null,
+		Stars: github?.stargazerCount ?? null,
+		Watchers: github?.watcherCount ?? null,
+		Contributors: github?.contributorCount ?? gitStats?.contributorCount ?? null,
+		Forks: github?.forkCount ?? null,
+		"Downloads Total": nodeNpmRegistry?.downloadsTotal ?? obsidianPluginRegistry?.downloadCount ?? pythonPypiRegistry?.downloads180Days ?? github?.releaseDownloadCount ?? null,
+		"Downloads Monthly": nodeNpmRegistry?.downloadsMonthly ?? pythonPypiRegistry?.downloadsMonthly ?? null,
+		Releases: github?.releaseCount ?? gitStats?.tagReleaseCount ?? null,
+		"Issues Open": github?.issueCountOpen ?? null,
+		"Issues Closed": github?.issueCountClosed ?? null,
+		"PRs Open": github?.pullRequestCountOpen ?? null,
+		"PRs Merged": github?.pullRequestCountMerged ?? null,
+		"PRs Closed": github?.pullRequestCountClosed ?? null,
+		"Vulnerability Alerts": github?.vulnerabilityAlertCount ?? null,
+		"Lines of Code": codeStats?.total?.code ?? null,
+		"Total Files": fileStats?.totalFileCount ?? null,
+		"Total Size MB": toMb(fileStats?.totalSizeBytes) ?? null,
+		"Tracked Files": gitStats?.trackedFileCount ?? null,
+		"Tracked Size MB": toMb(gitStats?.trackedSizeBytes) ?? null,
+		"GitHub Size MB": toMb(github?.diskUsageBytes) ?? null,
+		Dependencies: dependencyNames(codemeta$1, "prod") ?? null,
+		"Dev Dependencies": dependencyNames(codemeta$1, "dev") ?? null,
+		"Major Updates": dependencyUpdates?.data.major?.length ?? 0,
+		"Minor Updates": dependencyUpdates?.data.minor?.length ?? 0,
+		"Patch Updates": dependencyUpdates?.data.patch?.length ?? 0,
+		"Total Updates": dependencyUpdates?.extra?.total ?? 0,
+		Libyears: dependencyUpdates?.extra?.libyears ?? 0,
+		Runtime: codemeta$1.runtimePlatform ?? null,
+		"Operating System": codemeta$1.operatingSystem ?? null,
+		"Forked From": github?.forkedFrom ?? null,
+		"Fork Ahead": github?.commitsAheadUpstream ?? null,
+		"Fork Behind": github?.commitsBehindUpstream ?? null,
+		"Template From": github?.templateFrom ?? null,
+		Organization: github?.isInOrganization ?? false,
+		Monorepo: metascope?.workspaceDirectories === void 0 ? false : metascope.workspaceDirectories.length > 0,
+		"Git Commits": gitStats?.commitCount ?? null,
+		"Git Dirty Files": gitStats?.uncommittedFileCount ?? null,
+		"Git Remotes Ahead": gitStats?.totalAhead ?? null,
+		"Git Remotes Behind": gitStats?.totalBehind ?? null,
+		"Git LFS": gitStats?.hasLfs ?? github?.hasLfs ?? false,
+		"Git Tags": gitStats?.tagCount ?? null,
+		"Git Current Branch": gitStats?.branchCurrent ?? null,
+		"Git Branches": gitStats?.branchCount ?? null,
+		"Git Remotes": gitStats?.remoteCount ?? null,
+		"Git Submodules": gitStats?.submoduleCount ?? 0
+	};
+});
+//#endregion
+export { frontmatter };

package/dist/lib/templates/index.d.ts

@@ -0,0 +1,181 @@
+import { Template } from "../metadata-types.js";
+import { CodemetaDependencyLd, CodemetaPersonOrOrgLd } from "../utilities/codemeta-helpers.js";
+import { TemplateDataCodemeta } from "./codemeta.js";
+import { TemplateDataFrontmatter } from "./frontmatter.js";
+import { TemplateDataMetadata } from "./metadata.js";
+import { TemplateDataProject } from "./project.js";
+//#region src/lib/templates/index.d.ts
+/**
+ * Built-in templates, keyed by name.
+ */
+declare const templates: {
+  codemeta: Template<{
+    '@context': string;
+    '@type': string;
+    applicationCategory: string | undefined;
+    applicationSubCategory: string | undefined;
+    author: CodemetaPersonOrOrgLd[] | undefined;
+    buildInstructions: string | undefined;
+    codeRepository: string | undefined;
+    continuousIntegration: string | undefined;
+    contributor: CodemetaPersonOrOrgLd[] | undefined;
+    copyrightHolder: CodemetaPersonOrOrgLd[] | undefined;
+    copyrightYear: number | undefined;
+    dateCreated: string | undefined;
+    dateModified: string | undefined;
+    datePublished: string | undefined;
+    description: string | undefined;
+    developmentStatus: string | undefined;
+    downloadUrl: string | undefined;
+    funder: CodemetaPersonOrOrgLd[] | undefined;
+    funding: string | undefined;
+    identifier: string | undefined;
+    installUrl: string | undefined;
+    isAccessibleForFree: boolean | undefined;
+    issueTracker: string | undefined;
+    keywords: string[] | undefined;
+    license: string | undefined;
+    maintainer: CodemetaPersonOrOrgLd[] | undefined;
+    name: string | undefined;
+    operatingSystem: string[] | undefined;
+    programmingLanguage: string[] | undefined;
+    readme: string | undefined;
+    relatedLink: string | string[] | undefined;
+    releaseNotes: string | undefined;
+    runtimePlatform: string[] | undefined;
+    softwareHelp: string | undefined;
+    softwareRequirements: CodemetaDependencyLd[] | undefined;
+    softwareSuggestions: CodemetaDependencyLd[] | undefined;
+    targetProduct: Record<string, string> | undefined;
+    url: string | undefined;
+    version: string | undefined;
+  }>;
+  frontmatter: Template<{
+    Name: string | null;
+    ID: string | null;
+    Description: string | null;
+    Author: string[] | null;
+    Contributor: string[] | null;
+    Maintainer: string[] | null;
+    Version: string | null;
+    Account: string | null;
+    Public: boolean;
+    Fork: boolean;
+    Published: boolean;
+    Status: "unknown" | "maintainer" | "author" | "observer";
+    Tags: string[] | null;
+    Aliases: (string | null | undefined)[] | null;
+    License: string[] | null;
+    Language: string[] | null;
+    'Secondary Language': string[] | null;
+    'Repo Path': string | null;
+    'VS Code Path': string | null;
+    'Readme Path': string | null;
+    'Homepage URL': string | null;
+    'Repo URL': string | null;
+    'Issues URL': string | null;
+    'Readme URL': string | null;
+    'Package URL': string | null;
+    Created: string | null;
+    'First Commit Date': string | null;
+    'Latest Commit Date': string | null;
+    'Latest Push Date': string | null;
+    'Latest Release Date': string | null;
+    'Latest Release Version': string | null;
+    Stars: number | null;
+    Watchers: number | null;
+    Contributors: number | null;
+    Forks: number | null;
+    'Downloads Total': number | null;
+    'Downloads Monthly': number | null;
+    Releases: number | null;
+    'Issues Open': number | null;
+    'Issues Closed': number | null;
+    'PRs Open': number | null;
+    'PRs Merged': number | null;
+    'PRs Closed': number | null;
+    'Vulnerability Alerts': number | null;
+    'Lines of Code': number | null;
+    'Total Files': number | null;
+    'Total Size MB': number | null;
+    'Tracked Files': number | null;
+    'Tracked Size MB': number | null;
+    'GitHub Size MB': number | null;
+    Dependencies: string[] | null;
+    'Dev Dependencies': string[] | null;
+    'Major Updates': number;
+    'Minor Updates': number;
+    'Patch Updates': number;
+    'Total Updates': number;
+    Libyears: number;
+    Runtime: string[] | null;
+    'Operating System': string[] | null;
+    'Forked From': string | null;
+    'Fork Ahead': number | null;
+    'Fork Behind': number | null;
+    'Template From': string | null;
+    Organization: boolean;
+    Monorepo: boolean;
+    'Git Commits': number | null;
+    'Git Dirty Files': number | null;
+    'Git Remotes Ahead': number | null;
+    'Git Remotes Behind': number | null;
+    'Git LFS': boolean;
+    'Git Tags': number | null;
+    'Git Current Branch': string | null;
+    'Git Branches': number | null;
+    'Git Remotes': number | null;
+    'Git Submodules': number;
+  }>;
+  metadata: Template<{
+    description: string | undefined;
+    homepage: string | undefined;
+    topics: string[] | undefined;
+  }>;
+  project: Template<{
+    description: string | undefined;
+    firstCommitDate: string | undefined;
+    gitHubLink: string | undefined;
+    gitHubStarCount: number | undefined;
+    gitIsClean: boolean | undefined;
+    gitIsDirty: boolean | undefined;
+    gitRemoteCount: number | undefined;
+    homepage: string | undefined;
+    isAuthoredByMe: boolean | undefined;
+    isOnMyGitHub: boolean | undefined;
+    isOnNpm: boolean;
+    isPublic: boolean;
+    isRemoteAhead: boolean | undefined;
+    issueCount: number | undefined;
+    lastCommitDate: string | undefined;
+    license: string | undefined;
+    majorUpdateCount: number;
+    majorUpdateList: string[] | undefined;
+    npmDownloadCount: number | undefined;
+    readmePath: string | undefined;
+    repositoryPath: string | undefined;
+    semverUpdateCount: undefined;
+    semverUpdateList: undefined;
+    tags: string[] | undefined;
+    title: string | undefined;
+    type: "source" | "fork" | "unmaintained" | undefined;
+    usesPnpm: boolean;
+    usesSharedConfig: boolean;
+    version: string | undefined;
+  }>;
+};
+/**
+ * Maps built-in template names to their return types.
+ */
+type TemplateMap = {
+  codemeta: TemplateDataCodemeta;
+  frontmatter: TemplateDataFrontmatter;
+  metadata: TemplateDataMetadata;
+  project: TemplateDataProject;
+};
+/**
+ * Names of built-in templates.
+ */
+type TemplateName = keyof TemplateMap;
+//#endregion
+export { TemplateMap, TemplateName, templates };

package/dist/lib/templates/index.js

@@ -0,0 +1,22 @@
+import { codemeta } from "./codemeta.js";
+import { frontmatter } from "./frontmatter.js";
+import { metadata } from "./metadata.js";
+import { project } from "./project.js";
+//#region src/lib/templates/index.ts
+/**
+* Built-in templates, keyed by name.
+*/
+const templates = {
+	codemeta,
+	frontmatter,
+	metadata,
+	project
+};
+/**
+* Type guard
+*/
+function isKeyOfTemplate(value) {
+	return typeof value === "string" && value in templates;
+}
+//#endregion
+export { isKeyOfTemplate, templates };

package/dist/lib/templates/metadata.d.ts

@@ -0,0 +1,17 @@
+import { Template } from "../metadata-types.js";
+//#region src/lib/templates/metadata.d.ts
+type TemplateDataMetadata = ReturnType<typeof metadata>;
+/**
+ * A minimal metadata template for populating a GitHub repository's
+ * description, homepage, and topics via metadata.json / metadata.yaml.
+ *
+ * Builds on the codemeta template for baseline values, then lets any
+ * metadata.json source fields override the result.
+ */
+declare const metadata: Template<{
+  description: string | undefined;
+  homepage: string | undefined;
+  topics: string[] | undefined;
+}>;
+//#endregion
+export { TemplateDataMetadata };

package/dist/lib/templates/metadata.js

@@ -0,0 +1,35 @@
+import { defineTemplate } from "../metadata-types.js";
+import { firstOf } from "../utilities/template-helpers.js";
+import { codeMetaJsonDataSchema } from "../sources/codemeta-json.js";
+import { codemeta } from "./codemeta.js";
+//#region src/lib/templates/metadata.ts
+/**
+* Strip `git+` prefix and `.git` suffix from a URL.
+*/
+function normalizeGitUrl(url) {
+	if (url === void 0) return void 0;
+	let normalized = url;
+	if (normalized.startsWith("git+")) normalized = normalized.slice(4);
+	if (normalized.endsWith(".git")) normalized = normalized.slice(0, -4);
+	return normalized;
+}
+/**
+* A minimal metadata template for populating a GitHub repository's
+* description, homepage, and topics via metadata.json / metadata.yaml.
+*
+* Builds on the codemeta template for baseline values, then lets any
+* metadata.json source fields override the result.
+*/
+const metadata = defineTemplate((context, templateData) => {
+	const codemetaTemplateOutput = codemeta(context, templateData);
+	const codemeta$1 = codeMetaJsonDataSchema.parse(codemetaTemplateOutput);
+	const metadataFile = firstOf(context.metadataFile)?.data;
+	const homepage = metadataFile?.homepage ?? codemeta$1.url ?? codemeta$1.codeRepository;
+	return {
+		description: metadataFile?.description ?? codemeta$1.description,
+		homepage: normalizeGitUrl(homepage),
+		topics: metadataFile?.keywords ?? codemeta$1.keywords
+	};
+});
+//#endregion
+export { metadata };

package/dist/lib/templates/project.d.ts

@@ -0,0 +1,39 @@
+import { Template } from "../metadata-types.js";
+//#region src/lib/templates/project.d.ts
+type TemplateDataProject = ReturnType<typeof project>;
+/**
+ * Legacy structure used in AllWork desktop app
+ */
+declare const project: Template<{
+  description: string | undefined;
+  firstCommitDate: string | undefined;
+  gitHubLink: string | undefined;
+  gitHubStarCount: number | undefined;
+  gitIsClean: boolean | undefined;
+  gitIsDirty: boolean | undefined;
+  gitRemoteCount: number | undefined;
+  homepage: string | undefined;
+  isAuthoredByMe: boolean | undefined;
+  isOnMyGitHub: boolean | undefined;
+  isOnNpm: boolean;
+  isPublic: boolean;
+  isRemoteAhead: boolean | undefined;
+  issueCount: number | undefined;
+  lastCommitDate: string | undefined;
+  license: string | undefined;
+  majorUpdateCount: number;
+  majorUpdateList: string[] | undefined;
+  npmDownloadCount: number | undefined;
+  readmePath: string | undefined;
+  repositoryPath: string | undefined;
+  semverUpdateCount: undefined;
+  semverUpdateList: undefined;
+  tags: string[] | undefined;
+  title: string | undefined;
+  type: "source" | "fork" | "unmaintained" | undefined;
+  usesPnpm: boolean;
+  usesSharedConfig: boolean;
+  version: string | undefined;
+}>;
+//#endregion
+export { TemplateDataProject };

package/dist/lib/templates/project.js

@@ -0,0 +1,51 @@
+import { defineTemplate } from "../metadata-types.js";
+import { firstOf, hasDependencyWithId, isAuthoredBy, isOnGithubAccountOf, toBasicLicenses, toLocalUrl, toStatusLegacy, usesPnpm } from "../utilities/template-helpers.js";
+import { codeMetaJsonDataSchema } from "../sources/codemeta-json.js";
+import { codemeta } from "./codemeta.js";
+//#region src/lib/templates/project.ts
+/**
+* Legacy structure used in AllWork desktop app
+*/
+const project = defineTemplate((context, templateData) => {
+	const codemetaTemplateOutput = codemeta(context, templateData);
+	const codemeta$1 = codeMetaJsonDataSchema.parse(codemetaTemplateOutput);
+	const dependencyUpdates = firstOf(context.dependencyUpdates);
+	const github = firstOf(context.github)?.data;
+	const gitStats = firstOf(context.gitStats)?.data;
+	const metascope = context.metascope?.data;
+	const nodeNpmRegistry = firstOf(context.nodeNpmRegistry)?.data;
+	const nodePackageJson = firstOf(context.nodePackageJson);
+	return {
+		description: codemeta$1.description,
+		firstCommitDate: gitStats?.commitDateFirst,
+		gitHubLink: github?.url,
+		gitHubStarCount: github?.stargazerCount,
+		gitIsClean: gitStats?.isClean,
+		gitIsDirty: gitStats?.isDirty,
+		gitRemoteCount: gitStats?.remoteCount,
+		homepage: github?.homepageUrl ?? codemeta$1.url ?? github?.url,
+		isAuthoredByMe: isAuthoredBy(codemeta$1.author, templateData.authorName),
+		isOnMyGitHub: isOnGithubAccountOf(codemeta$1.codeRepository, templateData.githubAccount),
+		isOnNpm: nodeNpmRegistry?.url !== void 0,
+		isPublic: !(github?.isPrivate ?? false),
+		isRemoteAhead: gitStats?.isRemoteAhead,
+		issueCount: github?.issueCountOpen,
+		lastCommitDate: gitStats?.commitDateLast,
+		license: toBasicLicenses(codemeta$1.license ?? github?.licenseSpdxId)?.at(0),
+		majorUpdateCount: dependencyUpdates?.data.major?.length ?? 0,
+		majorUpdateList: dependencyUpdates?.data.major?.map((value) => value.name),
+		npmDownloadCount: nodeNpmRegistry?.downloadsTotal,
+		readmePath: toLocalUrl(codemeta$1.readme, metascope?.options.path),
+		repositoryPath: metascope?.options.path === void 0 ? void 0 : `file://${metascope.options.path}`,
+		semverUpdateCount: void 0,
+		semverUpdateList: void 0,
+		tags: codemeta$1.keywords,
+		title: codemeta$1.name,
+		type: toStatusLegacy(codemeta$1.codeRepository, codemeta$1.author, templateData.authorName, templateData.githubAccount),
+		usesPnpm: usesPnpm(nodePackageJson),
+		usesSharedConfig: hasDependencyWithId("@kitschpatrol/shared-config", codemeta$1),
+		version: codemeta$1.version
+	};
+});
+//#endregion
+export { project };

package/dist/lib/utilities/codemeta-helpers.d.ts

@@ -0,0 +1,39 @@
+//#region src/lib/utilities/codemeta-helpers.d.ts
+/**
+ * Helpers for building codemeta JSON-LD objects.
+ *
+ * Provides type-safe constructors for Person/Organization and SoftwareApplication
+ * dependency nodes, plus deduplication and license URL normalization.
+ */
+/**
+ * An Organization node in codemeta JSON-LD.
+ */
+type CodemetaOrganizationLd = {
+  '@type': 'Organization';
+  name: string;
+};
+/**
+ * A Person or Organization node in codemeta JSON-LD.
+ */
+type CodemetaPersonOrOrgLd = {
+  '@id'?: string;
+  '@type': 'Organization' | 'Person';
+  affiliation?: CodemetaOrganizationLd;
+  email?: string;
+  familyName?: string;
+  givenName?: string;
+  name?: string;
+  url?: string;
+};
+/**
+ * A software dependency node in codemeta JSON-LD.
+ */
+type CodemetaDependencyLd = {
+  '@type': 'SoftwareApplication';
+  identifier?: string;
+  name: string;
+  runtimePlatform?: string;
+  version?: string;
+};
+//#endregion
+export { CodemetaDependencyLd, CodemetaPersonOrOrgLd };

package/dist/lib/utilities/codemeta-helpers.js

@@ -0,0 +1,83 @@
+import is from "@sindresorhus/is";
+//#region src/lib/utilities/codemeta-helpers.ts
+/**
+* Helpers for building codemeta JSON-LD objects.
+*
+* Provides type-safe constructors for Person/Organization and SoftwareApplication
+* dependency nodes, plus deduplication and license URL normalization.
+*/
+/**
+* Build a codemeta JSON-LD Person or Organization from flexible inputs.
+* Returns undefined if no identifying information (name, givenName+familyName, or email) is present.
+*
+* Works with person shapes from any metascope source — the caller maps
+* source-specific field names into this common parameter object.
+*/
+function toPersonOrOrgLd(options) {
+	const hasName = is.nonEmptyStringAndNotWhitespace(options.name);
+	const hasGivenName = is.nonEmptyStringAndNotWhitespace(options.givenName);
+	const hasFamilyName = is.nonEmptyStringAndNotWhitespace(options.familyName);
+	const hasEmail = is.nonEmptyStringAndNotWhitespace(options.email);
+	if (!hasName && !hasGivenName && !hasFamilyName && !hasEmail) return void 0;
+	const person = { "@type": options.type ?? "Person" };
+	if (is.nonEmptyStringAndNotWhitespace(options.id)) person["@id"] = options.id;
+	if (hasName) person.name = options.name;
+	if (hasGivenName) person.givenName = options.givenName;
+	if (hasFamilyName) person.familyName = options.familyName;
+	if (hasEmail) person.email = options.email;
+	if (is.nonEmptyStringAndNotWhitespace(options.url)) person.url = options.url;
+	if (is.nonEmptyStringAndNotWhitespace(options.affiliation)) person.affiliation = {
+		"@type": "Organization",
+		name: options.affiliation
+	};
+	return person;
+}
+/**
+* Deduplicate persons by name (case-insensitive, trimmed).
+* Keeps the first occurrence, so callers should place higher-priority sources first.
+* Returns undefined if the result is empty.
+*/
+function deduplicatePersonsOrOrgs(persons) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const person of persons) {
+		const key = (person.name ?? ([person.givenName, person.familyName].filter(Boolean).join(" ") || void 0) ?? person.email ?? "").toLowerCase().trim();
+		if (key.length > 0 && !seen.has(key)) seen.set(key, person);
+	}
+	const result = [...seen.values()];
+	return result.length > 0 ? result : void 0;
+}
+/**
+* Build a codemeta JSON-LD SoftwareApplication dependency node.
+*/
+function toDependencyLd(name, version, identifier, runtimePlatform) {
+	const dep = {
+		"@type": "SoftwareApplication",
+		name
+	};
+	if (is.nonEmptyStringAndNotWhitespace(version)) dep.version = version;
+	if (is.nonEmptyStringAndNotWhitespace(identifier)) dep.identifier = identifier;
+	if (is.nonEmptyStringAndNotWhitespace(runtimePlatform)) dep.runtimePlatform = runtimePlatform;
+	return dep;
+}
+/**
+* Deduplicate dependencies by name (case-insensitive).
+* Keeps the first occurrence. Returns undefined if the result is empty.
+*/
+function deduplicateDependencies(deps) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const dep of deps) {
+		const key = dep.name.toLowerCase().trim();
+		if (key.length > 0 && !seen.has(key)) seen.set(key, dep);
+	}
+	const result = [...seen.values()];
+	return result.length > 0 ? result : void 0;
+}
+/**
+* Normalize a license identifier to an SPDX URL.
+* Handles bare SPDX IDs ("MIT") and existing SPDX URLs.
+*/
+function toSpdxLicenseUrl(spdxId) {
+	return `https://spdx.org/licenses/${spdxId.replace("https://spdx.org/licenses/", "").replace("http://spdx.org/licenses/", "")}`;
+}
+//#endregion
+export { deduplicateDependencies, deduplicatePersonsOrOrgs, toDependencyLd, toPersonOrOrgLd, toSpdxLicenseUrl };

package/dist/lib/utilities/fetch.js

@@ -0,0 +1,43 @@
+import { log } from "../log.js";
+//#region src/lib/utilities/fetch.ts
+/**
+* Fetch with automatic retries and exponential backoff.
+* Retries on network errors and 429/5xx responses.
+*/
+async function fetchWithRetry(url, options, maxRetries = 5) {
+	let lastError;
+	for (let attempt = 0; attempt <= maxRetries; attempt++) try {
+		const response = await fetch(url, options);
+		if ((response.status === 429 || response.status >= 500) && attempt < maxRetries) {
+			const delay = getDelay(attempt, response);
+			log.warn(`Fetch ${url} returned ${response.status}, retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries})`);
+			await sleep(delay);
+			continue;
+		}
+		return response;
+	} catch (error) {
+		lastError = error;
+		if (attempt < maxRetries) {
+			const delay = getDelay(attempt);
+			log.warn(`Fetch ${url} failed: ${error instanceof Error ? error.message : String(error)}, retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries})`);
+			await sleep(delay);
+		}
+	}
+	throw lastError;
+}
+function getDelay(attempt, response) {
+	const backoff = 1e3 * 2 ** attempt;
+	const retryAfter = response?.headers.get("retry-after");
+	if (retryAfter) {
+		const seconds = Number(retryAfter);
+		if (!Number.isNaN(seconds)) return Math.max(seconds * 1e3, backoff);
+	}
+	return backoff;
+}
+async function sleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+//#endregion
+export { fetchWithRetry };

package/dist/lib/utilities/formatting.js

@@ -0,0 +1,28 @@
+import { DEFAULT_GET_METADATA_OPTIONS } from "../metadata-types.js";
+import { relative } from "node:path";
+//#region src/lib/utilities/formatting.ts
+/**
+* Format an absolute path as either absolute or relative, based on the `absolute` option.
+* When relative, paths identical to `basePath` are returned as `'.'`.
+* Correctly handles Windows paths (normalizes to POSIX) and ignores URLs.
+*/
+function formatPath(absolutePath, basePath, absolute = DEFAULT_GET_METADATA_OPTIONS.absolute) {
+	if (/^[a-z]+:\/\//i.test(absolutePath)) return absolutePath;
+	if (absolute) return absolutePath.replaceAll("\\", "/");
+	const relativePath = relative(basePath, absolutePath).replaceAll("\\", "/");
+	return relativePath === "" ? "." : relativePath;
+}
+/**
+* Process an array of items in batches to avoid resource limits.
+*/
+async function batchMap(items, mapper, batchSize = 50) {
+	const results = [];
+	for (let index = 0; index < items.length; index += batchSize) {
+		const chunk = items.slice(index, index + batchSize);
+		const chunkResults = await Promise.all(chunk.map(async (item) => mapper(item)));
+		results.push(...chunkResults);
+	}
+	return results;
+}
+//#endregion
+export { batchMap, formatPath };