@codefast/cli 0.3.14 → 0.3.16-canary.0

package/dist/tag/since-writer.mjs

@@ -0,0 +1,130 @@
+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 {
+	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) => `${baseIndent} * ${line}`).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 };

package/dist/tag/target-runner.mjs

@@ -0,0 +1,26 @@
+import { walkTsxFiles } from "../core/workspace/typescript-walk.mjs";
+import { resolveNearestPackageVersion } from "./version-resolver.mjs";
+import { TagSinceWriter } from "./since-writer.mjs";
+import path from "node:path";
+//#region src/tag/target-runner.ts
+/**
+* @since 0.3.16-canary.0
+*/
+function runTagOnTarget(fs, targetPath, opts) {
+	const resolvedTarget = path.resolve(targetPath);
+	const version = resolveNearestPackageVersion(fs, resolvedTarget);
+	const tsFiles = (fs.statSync(resolvedTarget).isDirectory() ? walkTsxFiles(resolvedTarget, fs) : [resolvedTarget]).filter((filePath) => filePath.endsWith(".ts") || filePath.endsWith(".tsx"));
+	const sinceWriter = new TagSinceWriter(fs);
+	const fileResults = tsFiles.map((filePath) => sinceWriter.applySinceTagsToFile(filePath, version, opts.write));
+	const filesChanged = fileResults.filter((result) => result.changed).length;
+	const taggedDeclarations = fileResults.reduce((sum, result) => sum + result.taggedDeclarations, 0);
+	return {
+		version,
+		filesScanned: tsFiles.length,
+		filesChanged,
+		taggedDeclarations,
+		fileResults
+	};
+}
+//#endregion
+export { runTagOnTarget };

package/dist/tag/version-resolver.mjs

@@ -0,0 +1,25 @@
+import path from "node:path";
+//#region src/tag/version-resolver.ts
+const packageJsonFileName = "package.json";
+/**
+* @since 0.3.16-canary.0
+*/
+function resolveNearestPackageVersion(fs, targetPath) {
+	const resolved = path.resolve(targetPath);
+	let current = fs.statSync(resolved).isDirectory() ? resolved : path.dirname(resolved);
+	while (true) {
+		const packageJsonPath = path.join(current, packageJsonFileName);
+		if (fs.existsSync(packageJsonPath)) {
+			const raw = fs.readFileSync(packageJsonPath, "utf8");
+			const version = JSON.parse(raw).version;
+			if (typeof version === "string" && version.length > 0) return version;
+			throw new Error(`Missing or invalid version in ${packageJsonPath}`);
+		}
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	throw new Error(`Unable to locate ${packageJsonFileName} from target: ${targetPath}`);
+}
+//#endregion
+export { resolveNearestPackageVersion };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codefast/cli",
-  "version": "0.3.14",
+  "version": "0.3.16-canary.0",
   "description": "Developer CLI for the Codefast monorepo (arrange, mirror, tag)",
   "keywords": [
     "cli",
@@ -55,20 +55,17 @@
     "jiti": "^2.6.1",
     "picomatch": "^4.0.4",
     "typescript": "^6.0.3",
-    "yaml": "^2.8.3",
-    "zod": "^4.3.6",
-    "@codefast/di": "0.3.14"
+    "yaml": "^2.8.4",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
     "@types/picomatch": "^4.0.3",
-    "@typescript/native-preview": "7.0.0-dev.20260422.1",
+    "@typescript/native-preview": "7.0.0-dev.20260504.1",
     "@vitest/coverage-v8": "^4.1.5",
-    "esbuild": "^0.28.0",
-    "unplugin-swc": "^1.5.9",
-    "vite": "^8.0.9",
+    "vite": "^8.0.10",
     "vitest": "^4.1.5",
-    "@codefast/typescript-config": "0.3.14"
+    "@codefast/typescript-config": "0.3.16-canary.0"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -78,6 +75,8 @@
     "check-types": "tsgo --noEmit",
     "clean": "rm -rf dist",
     "test": "vitest run",
+    "test:integration": "vitest run tests/integration",
+    "test:unit": "vitest run tests/unit",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest"
   }