@codefast/cli 0.3.15 → 0.3.16-canary.1

package/dist/mirror/sync.mjs

@@ -0,0 +1,87 @@
+import { AppError, messageFrom } from "../core/errors.mjs";
+import { err, ok } from "../core/result.mjs";
+import { listWorkspacePackageDirectories } from "../core/workspace/resolver.mjs";
+import { normalizePath } from "./domain/path-normalizer.mjs";
+import { resolvePackageFilterUnderRoot } from "./package-path.mjs";
+import { syncExportsForWorkspacePackage } from "./sync-workspace-package.mjs";
+import path from "node:path";
+//#region src/mirror/sync.ts
+/**
+* @since 0.3.16-canary.0
+*/
+async function runMirrorSync(fs, input) {
+	const config = input.config ?? {};
+	const { listener } = input;
+	listener?.onBanner();
+	const startTime = performance.now();
+	try {
+		let targetPackages = [];
+		if (input.packageFilter) {
+			const filterOutcome = resolvePackageFilterUnderRoot(fs, input.rootDir, input.packageFilter);
+			if (!filterOutcome.ok) return filterOutcome;
+			targetPackages = [filterOutcome.value];
+			listener?.onProcessingMode({ kind: "single" });
+		} else {
+			const layoutOutcome = await listWorkspacePackageDirectories(input.rootDir, fs, false);
+			const { relPaths, multiSource } = mirrorTargetsFromWorkspaceLayout(input.rootDir, layoutOutcome);
+			targetPackages = relPaths;
+			listener?.onProcessingMode({
+				kind: "multi",
+				source: multiSource
+			});
+		}
+		const stats = {
+			packagesFound: targetPackages.length,
+			packagesProcessed: 0,
+			packagesSkipped: 0,
+			packagesErrored: 0,
+			totalExports: 0,
+			totalJsModules: 0,
+			totalCssExports: 0,
+			packageDetails: []
+		};
+		if (targetPackages.length === 0) {
+			listener?.onNoPackages();
+			listener?.onComplete(stats, (performance.now() - startTime) / 1e3);
+			return ok(stats);
+		}
+		let ordinal = 1;
+		for (const pkgPath of targetPackages) {
+			const pkgStats = await syncExportsForWorkspacePackage(fs, input.rootDir, pkgPath, config);
+			stats.packageDetails.push(pkgStats);
+			listener?.onPackageComplete(pkgStats, ordinal, targetPackages.length);
+			ordinal++;
+			accumulateStats(stats, pkgStats);
+		}
+		const elapsed = (performance.now() - startTime) / 1e3;
+		listener?.onComplete(stats, elapsed);
+		return ok(stats);
+	} catch (caughtError) {
+		return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
+	}
+}
+function accumulateStats(stats, pkgStats) {
+	if (pkgStats.skipped) stats.packagesSkipped++;
+	else if (pkgStats.error !== null) stats.packagesErrored++;
+	else {
+		stats.packagesProcessed++;
+		stats.totalExports += pkgStats.totalExports;
+		stats.totalJsModules += pkgStats.jsModules;
+		stats.totalCssExports += pkgStats.cssExports;
+	}
+}
+function mirrorTargetsFromWorkspaceLayout(rootDir, layoutOutcome) {
+	if (layoutOutcome.layoutSource === "declared-empty") return {
+		relPaths: [],
+		multiSource: "declared-empty"
+	};
+	const multiSource = layoutOutcome.layoutSource;
+	const relPaths = layoutOutcome.packageDirectoryPathsAbsolute.map((absolutePath) => normalizePath(path.relative(rootDir, absolutePath))).filter((relativePath) => relativePath.length > 0);
+	relPaths.sort((left, right) => left.localeCompare(right));
+	return {
+		relPaths,
+		multiSource
+	};
+}
+//#endregion
+export { runMirrorSync };

package/dist/{domains/mirror/infrastructure/package-json-exports.repository.mjs → mirror/write-exports.mjs}

@@ -1,11 +1,14 @@
-import { messageFromCaughtUnknown } from "../../../shell/domain/caught-unknown-message.value-object.mjs";
-import { MirrorError, MirrorErrorCode } from "../domain/errors.domain.mjs";
-import { PACKAGE_JSON_EXPORT } from "../domain/constants.domain.mjs";
-//#region src/domains/mirror/infrastructure/package-json-exports.repository.ts
+import { messageFrom } from "../core/errors.mjs";
+import { PACKAGE_JSON_EXPORT } from "./domain/constants.mjs";
+import { MirrorError, MirrorErrorCode } from "./domain/errors.mjs";
+//#region src/mirror/write-exports.ts
 /**
 * Writes `exports` into `package.json` via a temp file + rename (atomic on same volume).
 * Preserves a trailing newline after JSON.
-*/ async function writePackageJsonExportsAtomic(fs, packageJsonPath, mergeInput) {
+*
+* @since 0.3.16-canary.0
+*/
+async function writePackageJsonExportsAtomic(fs, packageJsonPath, mergeInput) {
 	function containsDistTarget(value) {
 		if (typeof value === "string") return value.startsWith("./dist/");
 		if (Array.isArray(value)) return value.some((entryValue) => containsDistTarget(entryValue));
@@ -15,7 +18,8 @@ import { PACKAGE_JSON_EXPORT } from "../domain/constants.domain.mjs";
 	/**
 	* Keep `./package.json` at the very end for aesthetics by default.
 	* If a catch-all `./*` exists, move `./package.json` before wildcards so it remains reachable.
-	*/ function exportSpecifierRank(exportSpecifier, hasCatchAllWildcard) {
+	*/
+	function exportSpecifierRank(exportSpecifier, hasCatchAllWildcard) {
 		if (exportSpecifier === ".") return 0;
 		if (exportSpecifier === "./package.json") return hasCatchAllWildcard ? 2 : 4;
 		if (exportSpecifier.includes("*")) return 3;
@@ -81,7 +85,7 @@ import { PACKAGE_JSON_EXPORT } from "../domain/constants.domain.mjs";
 		await fs.rename(tmpPath, packageJsonPath);
 	} catch (caughtRenameError) {
 		await fs.unlink(tmpPath).catch(() => {});
-		throw new MirrorError(MirrorErrorCode.PACKAGE_WRITE, `Failed to atomically update ${packageJsonPath}: ${messageFromCaughtUnknown(caughtRenameError)}`, caughtRenameError instanceof Error ? { cause: caughtRenameError } : void 0);
+		throw new MirrorError(MirrorErrorCode.PACKAGE_WRITE, `Failed to atomically update ${packageJsonPath}: ${messageFrom(caughtRenameError)}`, caughtRenameError instanceof Error ? { cause: caughtRenameError } : void 0);
 	}
 	return { prunedKeys };
 }

package/dist/tag/cli-result.mjs

@@ -0,0 +1,11 @@
+import "../core/exit-codes.mjs";
+//#region src/tag/cli-result.ts
+/**
+* @since 0.3.16-canary.0
+*/
+function exitCodeForTagSyncResult(result) {
+	if (result.selectedTargets.length === 0) return 1;
+	return result.targetResults.some((targetResult) => targetResult.runError !== null) || result.hookError !== null ? 1 : 0;
+}
+//#endregion
+export { exitCodeForTagSyncResult };

package/dist/{domains/tag/presentation/presenters/tag-cli.schema.mjs → tag/cli-schema.mjs}

@@ -1,5 +1,8 @@
 import { z } from "zod";
-//#region src/domains/tag/presentation/presenters/tag-cli.schema.ts
+//#region src/tag/cli-schema.ts
+/**
+* @since 0.3.16-canary.0
+*/
 const tagSyncRunRequestSchema = z.object({
 	rootDir: z.string().min(1),
 	write: z.boolean(),

package/dist/tag/command.mjs

@@ -0,0 +1,56 @@
+import { parseWithSchema } from "../core/schema-parse.mjs";
+import { logger } from "../core/logger.mjs";
+import { consumeCliAppError } from "../core/cli/result-handle.mjs";
+import { nodeFilesystem } from "../core/filesystem/node.mjs";
+import { readOptionalPositionalArg } from "../core/cli/positional.mjs";
+import { prepareTagSync } from "./prepare.mjs";
+import { runTagSync } from "./sync.mjs";
+import { tagSyncRunRequestSchema } from "./cli-schema.mjs";
+import { exitCodeForTagSyncResult } from "./cli-result.mjs";
+import { TagSyncProgressPresenter, presentTagSyncResult } from "./output.mjs";
+import process from "node:process";
+import { Command } from "commander";
+//#region src/tag/command.ts
+/**
+* @since 0.3.16-canary.0
+*/
+function createTagCommand() {
+	return new Command("tag").description("Add @since <version> JSDoc tags to exported declarations").alias("annotate").argument("[target]", "Directory or file to annotate (default: auto-discover workspace packages)").option("--dry-run", "Show summary without writing files", false).option("--json", "Print one JSON summary on stdout (suppresses human progress)", false).action(async (target, opts) => {
+		const prelude = await prepareTagSync(nodeFilesystem, {
+			currentWorkingDirectory: process.cwd(),
+			rawTarget: readOptionalPositionalArg(target)
+		});
+		if (!consumeCliAppError(prelude)) return;
+		const { rootDir, config, resolvedTargetPath } = prelude.value;
+		const tagConfig = config.tag ?? {};
+		const parsed = parseWithSchema(tagSyncRunRequestSchema, {
+			rootDir,
+			write: !opts.dryRun,
+			json: opts.json,
+			targetPath: resolvedTargetPath,
+			skipPackages: tagConfig.skipPackages,
+			config: tagConfig
+		});
+		if (!consumeCliAppError(parsed)) return;
+		const progressPresenter = new TagSyncProgressPresenter();
+		const tagOutcome = await runTagSync(nodeFilesystem, {
+			...parsed.value,
+			listener: parsed.value.json ? void 0 : progressPresenter
+		});
+		if (!consumeCliAppError(tagOutcome)) return;
+		if (parsed.value.json) {
+			logger.out(formatTagSyncJsonOutput(tagOutcome.value, rootDir));
+			process.exitCode = exitCodeForTagSyncResult(tagOutcome.value);
+		} else process.exitCode = presentTagSyncResult(tagOutcome.value, rootDir);
+	});
+}
+function formatTagSyncJsonOutput(result, rootDir) {
+	return JSON.stringify({
+		schemaVersion: 1,
+		ok: result.hookError === null,
+		cwd: rootDir,
+		result
+	});
+}
+//#endregion
+export { createTagCommand };

package/dist/tag/output.mjs

@@ -0,0 +1,87 @@
+import "../core/exit-codes.mjs";
+import { logger } from "../core/logger.mjs";
+import { exitCodeForTagSyncResult } from "./cli-result.mjs";
+//#region src/tag/output.ts
+/**
+* @since 0.3.16-canary.0
+*/
+var TagSyncProgressPresenter = class TagSyncProgressPresenter {
+	onTargetStarted(target) {
+		logger.out(TagSyncProgressPresenter.formatProgress({
+			type: "target-started",
+			target
+		}));
+	}
+	onTargetCompleted(target, result) {
+		logger.out(TagSyncProgressPresenter.formatProgress({
+			type: "target-completed",
+			target,
+			result
+		}));
+	}
+	static formatProgress(event) {
+		const targetDisplayName = (target) => target.packageName ?? target.rootRelativeTargetPath;
+		if (event.type === "target-started") return `[tag] Processing ${targetDisplayName(event.target)}...`;
+		const changedFiles = event.result.result?.filesChanged ?? 0;
+		return `[tag] Done ${targetDisplayName(event.target)} (${changedFiles} changes)`;
+	}
+};
+const colorReset = "\x1B[0m";
+const colors = {
+	red: "\x1B[31m",
+	green: "\x1B[32m",
+	yellow: "\x1B[33m"
+};
+/**
+* @since 0.3.16-canary.0
+*/
+function presentTagSyncResult(result, rootDir) {
+	logger.out(formatTargetTable(result.selectedTargets, rootDir));
+	if (result.selectedTargets.length === 0) {
+		logger.err("No packages found in workspace. Check your pnpm-workspace.yaml or provide an explicit target path.");
+		return 1;
+	}
+	const warningsAndErrorsSection = formatWarningsAndErrors(result);
+	if (warningsAndErrorsSection) logger.err(warningsAndErrorsSection);
+	logger.out(formatSummary(result));
+	return exitCodeForTagSyncResult(result);
+}
+function withColorizedLine(line, colorCode) {
+	return `${colorCode}${line}${colorReset}`;
+}
+function warningsAndErrorsFromResult(result) {
+	const entries = [];
+	for (const targetResult of result.targetResults) if (targetResult.runError) entries.push(targetResult.runError);
+	if (result.hookError) entries.push(result.hookError);
+	return entries;
+}
+function formatTargetTable(targets, rootDir) {
+	const packageColumnWidth = Math.max(7, ...targets.map((target) => (target.packageName ?? "-").length));
+	const pathColumnWidth = Math.max(4, ...targets.map((target) => target.rootRelativeTargetPath.length));
+	const lines = [];
+	lines.push(`[tag] Root: ${rootDir}`);
+	lines.push(`[tag] Resolved targets: ${targets.length}`);
+	lines.push("[tag] Targets:");
+	lines.push(`  ${"package".padEnd(packageColumnWidth)}   ${"path".padEnd(pathColumnWidth)}   source`);
+	lines.push(`  ${"-".repeat(packageColumnWidth)}   ${"-".repeat(pathColumnWidth)}   ${"-".repeat(6)}`);
+	for (const target of targets) lines.push(`  ${(target.packageName ?? "-").padEnd(packageColumnWidth)}   ${target.rootRelativeTargetPath.padEnd(pathColumnWidth)}   ${target.source}`);
+	return lines.join("\n");
+}
+function formatWarningsAndErrors(result) {
+	const entries = warningsAndErrorsFromResult(result);
+	if (entries.length === 0) return null;
+	const lines = [withColorizedLine("⚠️ Warnings & Errors", colors.yellow)];
+	for (const entry of entries) lines.push(withColorizedLine(`- ${entry}`, colors.red));
+	return lines.join("\n");
+}
+function formatSummary(result) {
+	const isDryRun = result.mode === "dry-run";
+	const summaryPrefix = isDryRun ? "[tag:dry-run]" : "[tag]";
+	const versionSuffix = result.versionSummary === "mixed" && result.distinctVersions.length > 0 ? ` [${result.distinctVersions.join(", ")}]` : "";
+	const summaryColor = result.targetResults.some((targetResult) => targetResult.runError !== null) || result.hookError !== null ? colors.red : isDryRun ? colors.yellow : colors.green;
+	const lines = [withColorizedLine(`${summaryPrefix} version=${result.versionSummary}${versionSuffix} files=${result.filesChanged}/${result.filesScanned} declarations=${result.taggedDeclarations}`, summaryColor)];
+	if (result.skippedPackages.length > 0) lines.push(`[tag] Skipped: ${result.skippedPackages.length} package(s)`);
+	return lines.join("\n");
+}
+//#endregion
+export { TagSyncProgressPresenter, presentTagSyncResult };

package/dist/tag/prepare.mjs

@@ -0,0 +1,29 @@
+import { ok } from "../core/result.mjs";
+import { loadCodefastConfig } from "../core/config.mjs";
+import { findRepoRoot } from "../core/workspace/resolver.mjs";
+import { resolveProvidedTagTargetPath } from "./resolve-target-path.mjs";
+//#region src/tag/prepare.ts
+/**
+* @since 0.3.16-canary.0
+*/
+async function prepareTagSync(fs, args) {
+	let rootDir;
+	try {
+		rootDir = findRepoRoot(args.currentWorkingDirectory, fs);
+	} catch {
+		rootDir = args.currentWorkingDirectory;
+	}
+	const loadedOutcome = await loadCodefastConfig(rootDir, fs);
+	if (!loadedOutcome.ok) return loadedOutcome;
+	const resolvedTargetPath = resolveProvidedTagTargetPath(fs, {
+		currentWorkingDirectory: args.currentWorkingDirectory,
+		rawTarget: args.rawTarget
+	});
+	return ok({
+		rootDir,
+		config: loadedOutcome.value.config,
+		resolvedTargetPath
+	});
+}
+//#endregion
+export { prepareTagSync };

package/dist/tag/resolve-target-path.mjs

@@ -0,0 +1,12 @@
+import path from "node:path";
+//#region src/tag/resolve-target-path.ts
+/**
+* @since 0.3.16-canary.0
+*/
+function resolveProvidedTagTargetPath(fs, args) {
+	if (args.rawTarget === void 0) return;
+	const candidate = path.isAbsolute(args.rawTarget) ? path.resolve(args.rawTarget) : path.resolve(args.currentWorkingDirectory, args.rawTarget);
+	return fs.canonicalPathSync(candidate);
+}
+//#endregion
+export { resolveProvidedTagTargetPath };

package/dist/tag/since-writer.mjs

@@ -0,0 +1,131 @@
+import { applyEditsDescending, indentOfLineContaining } from "../core/source-text-edit.mjs";
+import ts from "typescript";
+//#region src/tag/since-writer.ts
+/**
+* @since 0.3.16-canary.0
+*/
+var TagSinceWriter = class {
+	fs;
+	sinceDocumentationTag = "@since";
+	constructor(fs) {
+		this.fs = fs;
+	}
+	applySinceTagsToFile(filePath, version, write) {
+		const sourceText = this.fs.readFileSync(filePath, "utf8");
+		const sf = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true, filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+		const edits = [];
+		for (const declaration of this.collectExportedDeclarations(sf)) {
+			const edit = this.makeDeclarationSinceLine(declaration, sf, sourceText, version);
+			if (edit) edits.push(edit);
+		}
+		if (edits.length > 0 && write) {
+			const updated = applyEditsDescending(sourceText, edits);
+			this.fs.writeFileSync(filePath, updated, "utf8");
+		}
+		return {
+			filePath,
+			taggedDeclarations: edits.length,
+			changed: edits.length > 0
+		};
+	}
+	hasExportModifier(node) {
+		return (ts.canHaveModifiers(node) ? ts.getModifiers(node) : void 0)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+	}
+	isTaggableDeclaration(node) {
+		return ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isEnumDeclaration(node) || ts.isVariableStatement(node);
+	}
+	addDeclarationName(registry, name, declaration) {
+		if (!registry.has(name)) {
+			registry.set(name, new Set([declaration]));
+			return;
+		}
+		const bucket = registry.get(name);
+		if (bucket === void 0) throw new Error(`declaration registry missing set for ${name}`);
+		bucket.add(declaration);
+	}
+	collectLocalNamedDeclarations(sf) {
+		const declarations = /* @__PURE__ */ new Map();
+		for (const statement of sf.statements) {
+			if (ts.isFunctionDeclaration(statement) && statement.name) {
+				this.addDeclarationName(declarations, statement.name.text, statement);
+				continue;
+			}
+			if (ts.isClassDeclaration(statement) && statement.name) {
+				this.addDeclarationName(declarations, statement.name.text, statement);
+				continue;
+			}
+			if (ts.isInterfaceDeclaration(statement)) {
+				this.addDeclarationName(declarations, statement.name.text, statement);
+				continue;
+			}
+			if (ts.isTypeAliasDeclaration(statement)) {
+				this.addDeclarationName(declarations, statement.name.text, statement);
+				continue;
+			}
+			if (ts.isEnumDeclaration(statement)) {
+				this.addDeclarationName(declarations, statement.name.text, statement);
+				continue;
+			}
+			if (!ts.isVariableStatement(statement)) continue;
+			for (const declaration of statement.declarationList.declarations) if (ts.isIdentifier(declaration.name)) this.addDeclarationName(declarations, declaration.name.text, statement);
+		}
+		return declarations;
+	}
+	collectExportedDeclarations(sf) {
+		const exported = /* @__PURE__ */ new Set();
+		const localNamed = this.collectLocalNamedDeclarations(sf);
+		for (const statement of sf.statements) {
+			if (this.isTaggableDeclaration(statement) && this.hasExportModifier(statement)) {
+				exported.add(statement);
+				continue;
+			}
+			if (ts.isExportDeclaration(statement) && !statement.moduleSpecifier && statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+				for (const element of statement.exportClause.elements) {
+					const localName = element.propertyName?.text ?? element.name.text;
+					const declarations = localNamed.get(localName);
+					if (!declarations) continue;
+					for (const declaration of declarations) exported.add(declaration);
+				}
+				continue;
+			}
+			if (!ts.isExportAssignment(statement) || !ts.isIdentifier(statement.expression)) continue;
+			const declarations = localNamed.get(statement.expression.text);
+			if (!declarations) continue;
+			for (const declaration of declarations) exported.add(declaration);
+		}
+		return exported;
+	}
+	makeJSDocSinceLine(existingComment, sourceText, version) {
+		const commentText = sourceText.slice(existingComment.pos, existingComment.end);
+		const baseIndent = indentOfLineContaining(sourceText, existingComment.pos);
+		const normalizedBodyLines = commentText.replace(/^\/\*\*\s?/, "").replace(/\s*\*\/$/, "").split("\n").map((line) => line.replace(/^\s*\*\s?/, "").replace(/\s+$/, "")).filter((line, lineIndex, lines) => {
+			if (line.length > 0) return true;
+			const hasNonEmptyBefore = lines.slice(0, lineIndex).some((value) => value.length > 0);
+			const hasNonEmptyAfter = lines.slice(lineIndex + 1).some((value) => value.length > 0);
+			return hasNonEmptyBefore && hasNonEmptyAfter;
+		});
+		const replacement = `/**\n${normalizedBodyLines.length > 0 ? `${normalizedBodyLines.map((line) => line.length > 0 ? `${baseIndent} * ${line}` : `${baseIndent} *`).join("\n")}\n${baseIndent} *\n` : ""}${baseIndent} * ${this.sinceDocumentationTag} ${version}\n${baseIndent} */`;
+		return {
+			start: existingComment.pos,
+			end: existingComment.end,
+			replacement
+		};
+	}
+	makeSinceOnlyJSDocBlock(declarationIndent, version) {
+		return `/**\n${declarationIndent} * ${this.sinceDocumentationTag} ${version}\n${declarationIndent} */`;
+	}
+	makeDeclarationSinceLine(declaration, sf, sourceText, version) {
+		if (ts.getJSDocTags(declaration).some((tag) => tag.tagName.text === "since")) return;
+		const lastJsDoc = ts.getJSDocCommentsAndTags(declaration).filter(ts.isJSDoc).at(-1);
+		if (lastJsDoc) return this.makeJSDocSinceLine(lastJsDoc, sourceText, version);
+		const start = declaration.getStart(sf);
+		const indent = indentOfLineContaining(sourceText, start);
+		return {
+			start,
+			end: start,
+			replacement: `${indent}${this.makeSinceOnlyJSDocBlock(indent, version)}\n${indent}`
+		};
+	}
+};
+//#endregion
+export { TagSinceWriter };

package/dist/tag/sync.mjs

@@ -0,0 +1,141 @@
+import { AppError, messageFrom } from "../core/errors.mjs";
+import { err, ok } from "../core/result.mjs";
+import { resolveTagTargetCandidates } from "./target-candidates.mjs";
+import { runTagOnTarget } from "./target-runner.mjs";
+import path from "node:path";
+//#region src/tag/sync.ts
+/**
+* @since 0.3.16-canary.0
+*/
+async function runTagSync(fs, input) {
+	try {
+		const tagConfig = input.config;
+		const { includedCandidates, skippedPackages } = filterSkippedCandidates(await resolveTagTargetCandidates(fs, input.rootDir, input.targetPath), input.skipPackages);
+		const selectedTargets = includedCandidates.map((candidate) => resolveTargetSelection(fs, candidate, input.rootDir));
+		const targetExecutionResults = await Promise.all(selectedTargets.map((resolvedTarget) => runOnResolvedTarget(fs, resolvedTarget, input.write, input.listener)));
+		const allFileResults = targetExecutionResults.flatMap((targetResult) => targetResult.result?.fileResults ?? []);
+		const filesScanned = targetExecutionResults.reduce((sum, targetResult) => sum + (targetResult.result?.filesScanned ?? 0), 0);
+		const filesChanged = targetExecutionResults.reduce((sum, targetResult) => sum + (targetResult.result?.filesChanged ?? 0), 0);
+		const taggedDeclarations = targetExecutionResults.reduce((sum, targetResult) => sum + (targetResult.result?.taggedDeclarations ?? 0), 0);
+		const modifiedFiles = allFileResults.filter((entry) => entry.changed).map((entry) => entry.filePath);
+		const hookError = input.write && modifiedFiles.length > 0 ? await runTagOnAfterWriteHook(tagConfig?.onAfterWrite, modifiedFiles) : null;
+		const versionsSet = extractDistinctVersions(targetExecutionResults);
+		const distinctVersions = [...versionsSet].sort((left, right) => left.localeCompare(right));
+		return ok({
+			mode: input.write ? "applied" : "dry-run",
+			selectedTargets,
+			skippedPackages,
+			targetResults: targetExecutionResults,
+			filesScanned,
+			filesChanged,
+			taggedDeclarations,
+			versionSummary: summarizeVersions(versionsSet),
+			distinctVersions,
+			modifiedFiles,
+			hookError
+		});
+	} catch (caughtError) {
+		return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
+	}
+}
+async function runTagOnAfterWriteHook(hook, modifiedFiles) {
+	if (!hook || modifiedFiles.length === 0) return null;
+	try {
+		await hook({ files: modifiedFiles });
+		return null;
+	} catch (caughtHookError) {
+		return `[tag] onAfterWrite hook failed: ${messageFrom(caughtHookError)}`;
+	}
+}
+function summarizeVersions(distinctVersions) {
+	if (distinctVersions.size === 0) return "none";
+	if (distinctVersions.size > 1) return "mixed";
+	return distinctVersions.values().next().value ?? "none";
+}
+function extractDistinctVersions(targetResults) {
+	return new Set(targetResults.map((targetResult) => targetResult.result?.version).filter((version) => typeof version === "string" && version.length > 0));
+}
+function chooseWorkspacePackageTargetPath(fs, candidate) {
+	if (candidate.source !== "workspace-package") return {
+		targetPath: candidate.candidatePath,
+		source: candidate.source
+	};
+	const preferredSourceDir = path.join(candidate.candidatePath, "src");
+	try {
+		if (fs.statSync(preferredSourceDir).isDirectory()) return {
+			targetPath: preferredSourceDir,
+			source: "workspace-package-selected-src"
+		};
+	} catch {}
+	return {
+		targetPath: candidate.candidatePath,
+		source: "workspace-package-selected-root"
+	};
+}
+function resolveTargetSelection(fs, candidate, rootDir) {
+	const selectedTarget = chooseWorkspacePackageTargetPath(fs, candidate);
+	const rootRelativeTargetPath = path.relative(rootDir, selectedTarget.targetPath).split(path.sep).join("/");
+	return {
+		targetPath: selectedTarget.targetPath,
+		rootRelativeTargetPath: rootRelativeTargetPath || ".",
+		source: selectedTarget.source,
+		packageDir: candidate.packageDir,
+		packageName: candidate.packageName
+	};
+}
+function filterSkippedCandidates(targetCandidates, skipPackages) {
+	if (!skipPackages || skipPackages.length === 0) return {
+		includedCandidates: targetCandidates,
+		skippedPackages: []
+	};
+	const skipPackageSet = new Set(skipPackages);
+	const includedCandidates = [];
+	const skippedPackages = [];
+	for (const candidate of targetCandidates) {
+		const packageName = candidate.packageName;
+		if (packageName && skipPackageSet.has(packageName)) {
+			skippedPackages.push(packageName);
+			continue;
+		}
+		includedCandidates.push(candidate);
+	}
+	return {
+		includedCandidates,
+		skippedPackages
+	};
+}
+async function runOnResolvedTarget(fs, resolvedTarget, write, listener) {
+	listener?.onTargetStarted(resolvedTarget);
+	const absoluteTargetPath = path.resolve(resolvedTarget.targetPath);
+	if (!fs.existsSync(absoluteTargetPath)) {
+		const missingTargetResult = {
+			target: resolvedTarget,
+			targetExists: false,
+			runError: `Not found: ${absoluteTargetPath}`,
+			result: null
+		};
+		listener?.onTargetCompleted(resolvedTarget, missingTargetResult);
+		return missingTargetResult;
+	}
+	try {
+		const targetRunResult = {
+			target: resolvedTarget,
+			targetExists: true,
+			runError: null,
+			result: runTagOnTarget(fs, absoluteTargetPath, { write })
+		};
+		listener?.onTargetCompleted(resolvedTarget, targetRunResult);
+		return targetRunResult;
+	} catch (caughtRunError) {
+		const failedTargetRunResult = {
+			target: resolvedTarget,
+			targetExists: true,
+			runError: messageFrom(caughtRunError),
+			result: null
+		};
+		listener?.onTargetCompleted(resolvedTarget, failedTargetRunResult);
+		return failedTargetRunResult;
+	}
+}
+//#endregion
+export { runTagSync };

package/dist/tag/target-candidates.mjs

@@ -0,0 +1,68 @@
+import { listWorkspacePackageDirectories } from "../core/workspace/resolver.mjs";
+import path from "node:path";
+import { z } from "zod";
+//#region src/tag/target-candidates.ts
+const packageJsonFileName = "package.json";
+const packageJsonNameSchema = z.looseObject({ name: z.string().min(1).optional() });
+function toPosix(filePath) {
+	return filePath.split(path.sep).join("/");
+}
+function readPackageName(fs, packageDir) {
+	const packageJsonPath = path.join(packageDir, packageJsonFileName);
+	if (!fs.existsSync(packageJsonPath)) return null;
+	try {
+		const rawPackageJson = fs.readFileSync(packageJsonPath, "utf8");
+		const parsedPackageJson = JSON.parse(rawPackageJson);
+		const parsedPackageName = packageJsonNameSchema.safeParse(parsedPackageJson);
+		if (!parsedPackageName.success) return null;
+		return parsedPackageName.data.name ?? null;
+	} catch {
+		return null;
+	}
+}
+function toRootRelativePath(rootDir, absolutePath) {
+	const relativePath = path.relative(rootDir, absolutePath);
+	return relativePath ? toPosix(relativePath) : ".";
+}
+function toPackageTargetCandidate(fs, rootDir, packageDir) {
+	const packageName = readPackageName(fs, packageDir);
+	return {
+		candidatePath: packageDir,
+		rootRelativeCandidatePath: toRootRelativePath(rootDir, packageDir),
+		source: "workspace-package",
+		packageDir,
+		packageName
+	};
+}
+/**
+* @since 0.3.16-canary.0
+*/
+async function resolveTagTargetCandidates(fs, rootDir, explicitTarget) {
+	if (explicitTarget) {
+		const resolvedExplicitTarget = path.resolve(explicitTarget);
+		return [{
+			candidatePath: resolvedExplicitTarget,
+			rootRelativeCandidatePath: toRootRelativePath(rootDir, resolvedExplicitTarget),
+			source: "explicit-target",
+			packageDir: null,
+			packageName: null
+		}];
+	}
+	const outcome = await listWorkspacePackageDirectories(rootDir, fs, true);
+	const packageDirs = [...outcome.packageDirectoryPathsAbsolute];
+	const hasWorkspaceFile = outcome.hasPnpmWorkspaceYamlFile;
+	if (packageDirs.length === 0) {
+		if (hasWorkspaceFile) return [];
+		const repoSourceDir = path.join(rootDir, "src");
+		return [{
+			candidatePath: repoSourceDir,
+			rootRelativeCandidatePath: toRootRelativePath(rootDir, repoSourceDir),
+			source: "repo-src-fallback",
+			packageDir: null,
+			packageName: null
+		}];
+	}
+	return packageDirs.map((packageDir) => toPackageTargetCandidate(fs, rootDir, packageDir));
+}
+//#endregion
+export { resolveTagTargetCandidates };