@lpm-registry/cli 0.2.0

package/lib/quality/display.js

@@ -0,0 +1,139 @@
+import chalk from "chalk"
+
+const TIER_COLORS = {
+	excellent: chalk.green,
+	good: chalk.blue,
+	fair: chalk.yellow,
+	"needs-work": chalk.gray,
+}
+
+const TIER_LABELS = {
+	excellent: "Excellent",
+	good: "Good",
+	fair: "Fair",
+	"needs-work": "Needs Work",
+}
+
+const CATEGORY_LABELS = {
+	documentation: "Documentation",
+	code: "Code Quality",
+	testing: "Testing",
+	health: "Package Health",
+}
+
+/**
+ * Render a progress bar string
+ * @param {number} value
+ * @param {number} max
+ * @param {number} width
+ * @returns {string}
+ */
+function progressBar(value, max, width = 18) {
+	const ratio = Math.min(value / max, 1)
+	const filled = Math.round(ratio * width)
+	const empty = width - filled
+	return chalk.cyan("█".repeat(filled)) + chalk.gray("░".repeat(empty))
+}
+
+/**
+ * Display quality report in the terminal.
+ *
+ * @param {{ score: number, checks: Array, meta: object }} result
+ */
+export function displayQualityReport({ score, checks, meta }) {
+	const tierColor = TIER_COLORS[meta.tier] || chalk.white
+	const tierLabel = TIER_LABELS[meta.tier] || meta.tier
+
+	const hasServerOnly = checks.some(c => c.serverOnly)
+
+	console.log("")
+
+	// Individual checks first
+	for (const check of checks) {
+		if (check.serverOnly) {
+			// Show server-only checks dimmed with ~ icon
+			const icon = chalk.dim("~")
+			const label = chalk.dim(check.label)
+			const detail = chalk.dim(" (verified after publish)")
+			console.log(`  ${icon} ${label}${detail}`)
+			continue
+		}
+		const icon = check.passed ? chalk.green("✓") : chalk.red("✗")
+		const label = check.passed ? check.label : chalk.dim(check.label)
+		const detail = check.detail ? chalk.dim(` (${check.detail})`) : ""
+		console.log(`  ${icon} ${label}${detail}`)
+	}
+
+	// Tips for failed checks (exclude server-only)
+	const failed = checks.filter(c => !c.passed && !c.serverOnly)
+	if (failed.length > 0) {
+		console.log("")
+		const tips = failed.slice(0, 3)
+		for (const check of tips) {
+			console.log(
+				chalk.dim(`  Tip: ${getTip(check.id)} (+${check.maxPoints} points)`),
+			)
+		}
+	}
+
+	// Score summary at the end
+	console.log("")
+	console.log(
+		`  ${chalk.bold("Quality Score:")} ${tierColor(`${score}/100`)} ${tierColor(`(${tierLabel})`)}${hasServerOnly ? chalk.dim(" — estimated, final score after publish") : ""}`,
+	)
+	console.log("")
+
+	// Category bars
+	for (const [cat, { score: catScore, max }] of Object.entries(
+		meta.categories,
+	)) {
+		const label = (CATEGORY_LABELS[cat] || cat).padEnd(16)
+		const bar = progressBar(catScore, max)
+		console.log(`  ${label}${bar}  ${catScore}/${max}`)
+	}
+
+	console.log("")
+}
+
+/**
+ * Get a human-readable tip for a failed check
+ * @param {string} checkId
+ * @returns {string}
+ */
+function getTip(checkId) {
+	const tips = {
+		"has-readme": "Add a README.md with at least 100 characters",
+		"readme-install": "Add an install/getting started section to your README",
+		"readme-usage": "Add usage examples with code blocks to your README",
+		"readme-api": "Add an API/reference section to your README",
+		"has-changelog": "Add a CHANGELOG.md file",
+		"has-license": "Add a LICENSE file",
+		"has-types": 'Add TypeScript types ("types" field or .d.ts files)',
+		"intellisense-coverage":
+			"Add .d.ts type definitions or JSDoc @param/@returns comments",
+		"esm-exports": 'Add "type": "module" or "exports" to package.json',
+		"tree-shakable":
+			'Add "sideEffects": false to package.json for tree-shaking',
+		"no-eval": "Remove eval() and new Function() usage",
+		"has-engines": 'Add "engines": { "node": ">=18" } to package.json',
+		"has-exports-map": 'Add an "exports" map to package.json',
+		"small-deps": "Reduce the number of production dependencies",
+		"source-maps": "Include .js.map source maps for easier debugging",
+		"has-test-files": "Add test files (*.test.js, *.spec.js)",
+		"has-test-script": "Add a test script to package.json",
+		"has-description": "Add a description (>10 chars) to package.json",
+		"has-keywords": "Add keywords to package.json",
+		"has-repository": "Add a repository field to package.json",
+		"has-homepage": "Add a homepage field to package.json",
+		"reasonable-size": "Reduce unpacked size (check for unnecessary files)",
+		"no-vulnerabilities": "Fix known vulnerabilities in dependencies",
+		"maintenance-health": "Publish updates regularly (within 90 days)",
+		"semver-consistency": "Use valid semantic versioning (major.minor.patch)",
+		"author-verified": "Link your GitHub or LinkedIn in your profile settings",
+		"has-skills":
+			"Add Agent Skills in .lpm/skills/*.md to help AI assistants use your package",
+		"skills-comprehensive":
+			"Add 3+ Agent Skills covering getting-started, best-practices, and anti-patterns",
+	}
+	return tips[checkId] || `Improve: ${checkId}`
+}

package/lib/quality/score.js

@@ -0,0 +1,115 @@
+import { getSourcePackageInfo, checks as jsChecks } from "./checks.js"
+import { swiftChecks, xcframeworkChecks } from "./swift-checks.js"
+
+const TIERS = [
+	{ min: 90, tier: "excellent" },
+	{ min: 70, tier: "good" },
+	{ min: 50, tier: "fair" },
+	{ min: 0, tier: "needs-work" },
+]
+
+function getTier(score) {
+	return TIERS.find(t => score >= t.min)?.tier || "needs-work"
+}
+
+/**
+ * Get the check set for a given ecosystem.
+ *
+ * @param {string} ecosystem - "js", "swift", "rust", etc.
+ * @returns {Array} Check definitions
+ */
+function getChecksForEcosystem(ecosystem) {
+	switch (ecosystem) {
+		case "swift":
+			return swiftChecks
+		case "xcframework":
+			return xcframeworkChecks
+		default:
+			return jsChecks
+	}
+}
+
+/**
+ * Run all quality checks and compute the score.
+ *
+ * @param {object} params
+ * @param {object} params.packageJson - Parsed package.json
+ * @param {string|null} params.readme - README content
+ * @param {object|null} params.lpmConfig - Parsed lpm.config.json
+ * @param {Array} params.files - File list (each has .path)
+ * @param {number} [params.unpackedSize] - Unpacked size in bytes
+ * @param {string} [params.ecosystem] - Ecosystem identifier (default: "js")
+ * @param {object} [params.swiftManifest] - Parsed Swift manifest metadata (for Swift packages)
+ * @returns {{ score: number, checks: Array, meta: object }}
+ */
+export function runQualityChecks({
+	packageJson,
+	readme,
+	lpmConfig,
+	files,
+	unpackedSize,
+	ecosystem = "js",
+	swiftManifest,
+	xcframeworkMeta,
+}) {
+	const context = {
+		packageJson,
+		readme,
+		lpmConfig,
+		files,
+		unpackedSize,
+		swiftManifest,
+		xcframeworkMeta,
+	}
+	const checks = getChecksForEcosystem(ecosystem)
+
+	const results = checks.map(check => {
+		const result = check.run(context)
+		// Some checks return custom points (e.g. smallDeps, reasonableSize)
+		const points = result.passed
+			? result.points !== undefined
+				? result.points
+				: check.maxPoints
+			: 0
+		return {
+			id: check.id,
+			category: check.category,
+			label: check.label,
+			passed: result.passed,
+			points,
+			maxPoints: check.maxPoints,
+			detail: result.detail,
+			...(result.serverOnly && { serverOnly: true }),
+		}
+	})
+
+	// Compute category scores dynamically from actual check maxPoints
+	const categories = {}
+	for (const result of results) {
+		if (!categories[result.category]) {
+			categories[result.category] = { score: 0, max: 0 }
+		}
+		categories[result.category].score += result.points
+		categories[result.category].max += result.maxPoints
+	}
+
+	const totalScore = Object.values(categories).reduce(
+		(sum, c) => sum + c.score,
+		0,
+	)
+	const maxScore = Object.values(categories).reduce((sum, c) => sum + c.max, 0)
+
+	const meta = {
+		version: 1,
+		tier: getTier(totalScore),
+		score: totalScore,
+		maxScore,
+		ecosystem,
+		isSourcePackage: !!lpmConfig,
+		categories,
+		sourcePackageInfo: getSourcePackageInfo(lpmConfig),
+		computedAt: new Date().toISOString(),
+	}
+
+	return { score: totalScore, checks: results, meta }
+}

package/lib/quality/swift-checks.js

@@ -0,0 +1,447 @@
+/**
+ * Swift-specific quality check definitions for LPM packages.
+ * Replaces JS-specific checks (TypeScript types, ESM, tree-shaking, etc.)
+ * while keeping universal checks (README, license, testing, health).
+ *
+ * Categories:
+ *   - documentation: 22 points (6 checks)
+ *   - code: 31 points (6 checks)
+ *   - testing: 11 points (2 checks)
+ *   - health: 36 points (11 checks)
+ */
+
+// --- Documentation checks (22 points) ---
+// Reused from JS: hasReadme, readmeHasInstall, readmeHasUsage, readmeHasApi, hasChangelog, hasLicense
+// readmeHasInstall is modified to also look for Swift-specific install patterns
+
+export const swiftReadmeHasInstall = {
+	id: "readme-install",
+	category: "documentation",
+	label: "README has install section",
+	maxPoints: 3,
+	run: ({ readme }) => {
+		if (!readme) return { passed: false, detail: "No README" }
+		const lower = readme.toLowerCase()
+		const hasSection =
+			lower.includes("## install") ||
+			lower.includes("## getting started") ||
+			lower.includes("## setup") ||
+			lower.includes("## requirements") ||
+			lower.includes("swift package manager") ||
+			lower.includes("package.swift") ||
+			lower.includes(".package(") ||
+			lower.includes("lpm add") ||
+			lower.includes("lpm install")
+		return {
+			passed: hasSection,
+			detail: hasSection
+				? "Install instructions found"
+				: "No install section found in README",
+		}
+	},
+}
+
+// --- Code Quality checks (31 points) — Swift-specific ---
+
+export const hasPlatformDeclarations = {
+	id: "has-platforms",
+	category: "code",
+	label: "Has platform declarations",
+	maxPoints: 6,
+	run: ({ swiftManifest }) => {
+		if (!swiftManifest)
+			return { passed: false, detail: "No Swift manifest data" }
+		const platforms = swiftManifest.platforms || []
+		if (platforms.length === 0) {
+			return {
+				passed: false,
+				detail:
+					"No platform declarations in Package.swift (add platforms: [.iOS(.v16), .macOS(.v13)])",
+			}
+		}
+		const names = platforms.map(p => `${p.name} ${p.version}`).join(", ")
+		return {
+			passed: true,
+			detail: `Platforms: ${names}`,
+		}
+	},
+}
+
+export const recentToolsVersion = {
+	id: "recent-tools-version",
+	category: "code",
+	label: "Uses recent swift-tools-version",
+	maxPoints: 5,
+	run: ({ swiftManifest }) => {
+		if (!swiftManifest)
+			return { passed: false, detail: "No Swift manifest data" }
+		const version = swiftManifest.toolsVersion
+		if (!version) {
+			return { passed: false, detail: "No swift-tools-version found" }
+		}
+		// Parse major.minor from version string
+		const match = version.match(/^(\d+)\.(\d+)/)
+		if (!match) {
+			return { passed: false, detail: `Invalid tools version: ${version}` }
+		}
+		const major = parseInt(match[1], 10)
+		const minor = parseInt(match[2], 10)
+		// 5.9+ is recent (Swift 5.9 introduced macros, 5.10 strict concurrency)
+		const isRecent = major > 5 || (major === 5 && minor >= 9)
+		return {
+			passed: isRecent,
+			detail: isRecent
+				? `swift-tools-version: ${version}`
+				: `swift-tools-version ${version} is outdated (5.9+ recommended)`,
+		}
+	},
+}
+
+export const supportsMultiplePlatforms = {
+	id: "multi-platform",
+	category: "code",
+	label: "Supports multiple platforms",
+	maxPoints: 4,
+	run: ({ swiftManifest }) => {
+		if (!swiftManifest)
+			return { passed: false, detail: "No Swift manifest data" }
+		const platforms = swiftManifest.platforms || []
+		const count = platforms.length
+		let points
+		if (count >= 3) points = 4
+		else if (count === 2) points = 3
+		else if (count === 1) points = 2
+		else points = 0
+		return {
+			passed: points > 0,
+			points,
+			detail:
+				count > 0
+					? `Supports ${count} platform${count !== 1 ? "s" : ""}`
+					: "No platform declarations",
+		}
+	},
+}
+
+export const hasPublicAPI = {
+	id: "has-public-api",
+	category: "code",
+	label: "Has public API surface",
+	maxPoints: 5,
+	run: ({ files }) => {
+		// Check if any .swift source files exist (exclude manifest and tests)
+		const swiftFiles = files.filter(f => {
+			const name = f.path || f
+			return (
+				name.endsWith(".swift") &&
+				!name.includes("Tests/") &&
+				name !== "Package.swift"
+			)
+		})
+		if (swiftFiles.length === 0) {
+			return { passed: false, detail: "No Swift source files found" }
+		}
+		// CLI can't read file contents from the file list alone
+		// Server will do deeper analysis; CLI just checks file presence
+		return {
+			passed: true,
+			detail: `${swiftFiles.length} Swift source file${swiftFiles.length !== 1 ? "s" : ""} found`,
+			serverOnly: true,
+		}
+	},
+}
+
+export const hasDocComments = {
+	id: "has-doc-comments",
+	category: "code",
+	label: "Has DocC documentation",
+	maxPoints: 7,
+	run: () => {
+		// Full check runs server-side from tarball contents.
+		// CLI assumes pass; server overrides if no documentation found.
+		return {
+			passed: true,
+			detail: "Full check runs server-side",
+			serverOnly: true,
+		}
+	},
+}
+
+export const smallDepsSwift = {
+	id: "small-deps",
+	category: "code",
+	label: "Small dependency footprint",
+	maxPoints: 4,
+	run: ({ swiftManifest }) => {
+		if (!swiftManifest)
+			return { passed: true, points: 4, detail: "No manifest data" }
+		const deps = swiftManifest.dependencies?.length || 0
+		let points
+		if (deps === 0) points = 4
+		else if (deps <= 2) points = 3
+		else if (deps <= 5) points = 2
+		else if (deps <= 10) points = 1
+		else points = 0
+		return {
+			passed: points > 0,
+			points,
+			detail: `${deps} ${deps === 1 ? "dependency" : "dependencies"}`,
+		}
+	},
+}
+
+// --- Testing checks (15 points) ---
+
+export const swiftHasTestTargets = {
+	id: "has-test-files",
+	category: "testing",
+	label: "Has test targets",
+	maxPoints: 7,
+	run: ({ swiftManifest, files }) => {
+		// Check Swift manifest for test targets
+		const testTargets = (swiftManifest?.targets || []).filter(
+			t => t.type === "test",
+		)
+
+		// Also check file paths
+		const testFiles = files.filter(f => {
+			const name = (f.path || f).toLowerCase()
+			return name.includes("tests/") || name.includes("test/")
+		})
+
+		const passed = testTargets.length > 0 || testFiles.length > 0
+		let detail
+		if (testTargets.length > 0) {
+			detail = `${testTargets.length} test target${testTargets.length !== 1 ? "s" : ""}: ${testTargets.map(t => t.name).join(", ")}`
+		} else if (testFiles.length > 0) {
+			detail = `${testFiles.length} test file${testFiles.length !== 1 ? "s" : ""} found`
+		} else {
+			detail = "No test targets or test files found"
+		}
+
+		return { passed, detail }
+	},
+}
+
+export const swiftHasTestScript = {
+	id: "has-test-script",
+	category: "testing",
+	label: "Has test configuration",
+	maxPoints: 4,
+	run: ({ swiftManifest }) => {
+		// For Swift, having test targets in the manifest is the equivalent
+		const testTargets = (swiftManifest?.targets || []).filter(
+			t => t.type === "test",
+		)
+		const passed = testTargets.length > 0
+		return {
+			passed,
+			detail: passed
+				? "Test targets defined in Package.swift"
+				: "No test targets in Package.swift",
+		}
+	},
+}
+
+// --- XCFramework-specific checks ---
+
+export const xcfHasValidPlist = {
+	id: "xcf-valid-plist",
+	category: "code",
+	label: "Valid Info.plist",
+	maxPoints: 10,
+	run: ({ xcframeworkMeta }) => {
+		if (!xcframeworkMeta)
+			return { passed: false, detail: "No XCFramework metadata" }
+		const slices = xcframeworkMeta.slices || []
+		if (slices.length === 0)
+			return {
+				passed: false,
+				detail: "Info.plist has no platform slices",
+			}
+		return {
+			passed: true,
+			detail: `Info.plist defines ${slices.length} platform slice${slices.length !== 1 ? "s" : ""}`,
+		}
+	},
+}
+
+export const xcfMultipleSlices = {
+	id: "xcf-multi-slice",
+	category: "code",
+	label: "Supports multiple platform slices",
+	maxPoints: 15,
+	run: ({ xcframeworkMeta }) => {
+		if (!xcframeworkMeta)
+			return { passed: false, detail: "No XCFramework metadata" }
+		const slices = xcframeworkMeta.slices || []
+		const uniquePlatforms = new Set(
+			slices.map(s => (s.variant ? `${s.platform}-${s.variant}` : s.platform)),
+		)
+		const count = uniquePlatforms.size
+		let points
+		if (count >= 4) points = 15
+		else if (count === 3) points = 11
+		else if (count === 2) points = 9
+		else if (count === 1) points = 4
+		else points = 0
+		const labels = [...uniquePlatforms].join(", ")
+		return {
+			passed: points > 0,
+			points,
+			detail:
+				count > 0
+					? `${count} platform target${count !== 1 ? "s" : ""}: ${labels}`
+					: "No platform slices",
+		}
+	},
+}
+
+export const xcfReasonableSize = {
+	id: "xcf-size",
+	category: "code",
+	label: "Reasonable framework size",
+	maxPoints: 5,
+	run: ({ unpackedSize }) => {
+		if (!unpackedSize)
+			return { passed: true, points: 5, detail: "No size data" }
+		const mb = unpackedSize / (1024 * 1024)
+		let points
+		if (mb <= 10) points = 5
+		else if (mb <= 50) points = 4
+		else if (mb <= 100) points = 3
+		else if (mb <= 200) points = 1
+		else points = 0
+		return {
+			passed: points > 0,
+			points,
+			detail: `${mb.toFixed(1)} MB`,
+		}
+	},
+}
+
+export const xcfHasArchitectures = {
+	id: "xcf-architectures",
+	category: "code",
+	label: "Supports arm64 architecture",
+	maxPoints: 10,
+	run: ({ xcframeworkMeta }) => {
+		if (!xcframeworkMeta)
+			return { passed: false, detail: "No XCFramework metadata" }
+		const slices = xcframeworkMeta.slices || []
+		const allArchs = new Set(slices.flatMap(s => s.architectures || []))
+		const hasArm64 = allArchs.has("arm64")
+		return {
+			passed: hasArm64,
+			detail: hasArm64
+				? `Architectures: ${[...allArchs].join(", ")}`
+				: "Missing arm64 architecture support",
+		}
+	},
+}
+
+// --- XCFramework health size check (MB-appropriate thresholds) ---
+// The JS reasonableSize check uses KB thresholds which are unsuitable for
+// binary frameworks. This replaces it in xcframeworkChecks with MB thresholds.
+export const xcfHealthReasonableSize = {
+	id: "reasonable-size",
+	category: "health",
+	label: "Reasonable framework size",
+	maxPoints: 3,
+	run: ({ unpackedSize }) => {
+		if (!unpackedSize)
+			return { passed: true, points: 3, detail: "Size unknown" }
+		const mb = unpackedSize / (1024 * 1024)
+		let points
+		if (mb <= 10) points = 3
+		else if (mb <= 50) points = 2
+		else if (mb <= 100) points = 1
+		else points = 0
+		return {
+			passed: points > 0,
+			points,
+			detail: `${mb.toFixed(1)} MB`,
+		}
+	},
+}
+
+// --- Export check sets ---
+// We import the universal checks from checks.js and replace JS-specific ones
+
+import {
+	authorVerified,
+	hasChangelog,
+	hasDescription,
+	hasHomepage,
+	hasKeywords,
+	hasLicense,
+	hasReadme,
+	hasRepository,
+	hasSkills,
+	maintenanceHealth,
+	noVulnerabilities,
+	readmeHasApi,
+	readmeHasUsage,
+	reasonableSize,
+	semverConsistency,
+	skillsComprehensive,
+} from "./checks.js"
+
+export const swiftChecks = [
+	// Documentation (22)
+	hasReadme,
+	swiftReadmeHasInstall,
+	readmeHasUsage,
+	readmeHasApi,
+	hasChangelog,
+	hasLicense,
+	// Code Quality (31)
+	hasPlatformDeclarations,
+	recentToolsVersion,
+	supportsMultiplePlatforms,
+	hasPublicAPI,
+	hasDocComments,
+	smallDepsSwift,
+	// Testing (11)
+	swiftHasTestTargets,
+	swiftHasTestScript,
+	// Health (36)
+	hasDescription,
+	hasKeywords,
+	hasRepository,
+	hasHomepage,
+	reasonableSize,
+	noVulnerabilities,
+	maintenanceHealth,
+	semverConsistency,
+	authorVerified,
+	hasSkills,
+	skillsComprehensive,
+]
+
+export const xcframeworkChecks = [
+	// Documentation (22)
+	hasReadme,
+	swiftReadmeHasInstall,
+	readmeHasUsage,
+	readmeHasApi,
+	hasChangelog,
+	hasLicense,
+	// Code Quality (40) — XCFramework-specific
+	xcfHasValidPlist,
+	xcfMultipleSlices,
+	xcfReasonableSize,
+	xcfHasArchitectures,
+	// Health (38) — XCF keeps original maintenance-health (5) and author-verified (4)
+	hasDescription,
+	hasKeywords,
+	hasRepository,
+	hasHomepage,
+	xcfHealthReasonableSize,
+	noVulnerabilities,
+	{ ...maintenanceHealth, maxPoints: 5 },
+	semverConsistency,
+	{ ...authorVerified, maxPoints: 4 },
+	hasSkills,
+	skillsComprehensive,
+]