@codefast/cli 0.9.0 → 0.11.0

package/dist/tag/domain/types.d.ts

@@ -0,0 +1,131 @@
+import type { CodefastConfig } from "#/core/config/schema";
+/**
+ * Per-file outcome of a tag run.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type TagFileResult = {
+    filePath: string;
+    taggedDeclarations: number;
+    changed: boolean;
+};
+/**
+ * Outcome of tagging one target: the version stamped and the per-file tallies.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type TagRunResult = {
+    version: string;
+    filesScanned: number;
+    filesChanged: number;
+    taggedDeclarations: number;
+    fileResults: Array<TagFileResult>;
+};
+/**
+ * Options for one target's tag run.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type TagRunOptions = {
+    write: boolean;
+};
+type TagTargetCandidateSource = "explicit-target" | "workspace-package" | "repo-src-fallback";
+/**
+ * How a resolved tag target was chosen.
+ *
+ * @since 0.3.16-canary.0
+ */
+type TagTargetSource = "explicit-target" | "workspace-package-selected-src" | "workspace-package-selected-root" | "repo-src-fallback";
+/**
+ * A candidate path a tag run may resolve into a target.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type TagTargetCandidate = {
+    candidatePath: string;
+    rootRelativeCandidatePath: string;
+    source: TagTargetCandidateSource;
+    packageDir: string | null;
+    packageName: string | null;
+};
+/**
+ * A directory or file a tag run will stamp, with its owning package when known.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type TagResolvedTarget = {
+    targetPath: string;
+    rootRelativeTargetPath: string;
+    source: TagTargetSource;
+    packageDir: string | null;
+    packageName: string | null;
+};
+/**
+ * One target's execution outcome, carrying either its run result or its error.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type TagTargetExecutionResult = {
+    target: TagResolvedTarget;
+    targetExists: boolean;
+    runError: string | null;
+    result: TagRunResult | null;
+};
+/**
+ * Callbacks a tag run invokes as each target starts and completes.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface TagProgressListener {
+    onTargetStarted: (target: TagResolvedTarget) => void;
+    onTargetCompleted: (target: TagResolvedTarget, result: TagTargetExecutionResult) => void;
+}
+/**
+ * Aggregate outcome of a tag run across every selected target.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type TagResult = {
+    mode: "applied" | "dry-run";
+    selectedTargets: Array<TagResolvedTarget>;
+    skippedPackages: Array<string>;
+    targetResults: Array<TagTargetExecutionResult>;
+    filesScanned: number;
+    filesChanged: number;
+    taggedDeclarations: number;
+    versionSummary: string;
+    distinctVersions: Array<string>;
+    modifiedFiles: Array<string>;
+    hookError: string | null;
+};
+/**
+ * Everything the `tag` action needs resolved before a run: root, config, and target path.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface TagCommandPrelude {
+    readonly rootDir: string;
+    readonly config: CodefastConfig;
+    readonly resolvedTargetPath: string | undefined;
+}
+/**
+ * The inputs a tag run is invoked with.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type TagRunRequest = {
+    rootDir: string;
+    write: boolean;
+    targetPath?: string | undefined;
+    skipPackages?: Array<string> | undefined;
+    config?: unknown;
+};
+/**
+ * A run request paired with an optional progress listener.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type TagExecutionInput = TagRunRequest & {
+    readonly listener?: TagProgressListener | undefined;
+};
+export {};

package/dist/tag/domain/version-summary.d.ts

@@ -0,0 +1,13 @@
+import type { TagTargetExecutionResult } from "#/tag/domain/types";
+/**
+ * Collects the distinct, non-empty package versions stamped across a run's target results.
+ *
+ * @since 0.11.0
+ */
+export declare function extractDistinctVersions(targetResults: Array<TagTargetExecutionResult>): Set<string>;
+/**
+ * Summarizes a set of versions as `"none"`, the single version, or `"mixed"`.
+ *
+ * @since 0.11.0
+ */
+export declare function summarizeVersions(distinctVersions: Set<string>): string;

package/dist/tag/domain/version-summary.js

@@ -0,0 +1,24 @@
+/**
+ * Collects the distinct, non-empty package versions stamped across a run's target results.
+ *
+ * @since 0.11.0
+ */
+export function extractDistinctVersions(targetResults) {
+    return new Set(targetResults
+        .map((targetResult) => targetResult.result?.version)
+        .filter((version) => typeof version === "string" && version.length > 0));
+}
+/**
+ * Summarizes a set of versions as `"none"`, the single version, or `"mixed"`.
+ *
+ * @since 0.11.0
+ */
+export function summarizeVersions(distinctVersions) {
+    if (distinctVersions.size === 0) {
+        return "none";
+    }
+    if (distinctVersions.size > 1) {
+        return "mixed";
+    }
+    return distinctVersions.values().next().value ?? "none";
+}

package/dist/tag/output.d.ts

@@ -0,0 +1,17 @@
+import type { TagProgressListener, TagResolvedTarget, TagResult, TagTargetExecutionResult } from "#/tag/domain/types";
+/**
+ * A progress listener that prints a line as each tag target starts and completes.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare class TagProgressPresenter implements TagProgressListener {
+    onTargetStarted(target: TagResolvedTarget): void;
+    onTargetCompleted(target: TagResolvedTarget, result: TagTargetExecutionResult): void;
+    private static formatProgress;
+}
+/**
+ * Prints a tag run's target table, warnings, and summary to the human reader.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function presentTagResult(result: TagResult, rootDir: string): void;

package/dist/tag/output.js

@@ -1,17 +1,15 @@
-import { CLI_EXIT_GENERAL_ERROR } from "#/core/exit-codes";
 import { logger } from "#/core/logger";
-import { exitCodeForTagSyncResult } from "#/tag/cli-result";
 /**
  * A progress listener that prints a line as each tag target starts and completes.
  *
  * @since 0.3.16-canary.0
  */
-export class TagSyncProgressPresenter {
+export class TagProgressPresenter {
     onTargetStarted(target) {
-        logger.out(TagSyncProgressPresenter.formatProgress({ type: "target-started", target }));
+        logger.out(TagProgressPresenter.formatProgress({ type: "target-started", target }));
     }
     onTargetCompleted(target, result) {
-        logger.out(TagSyncProgressPresenter.formatProgress({ type: "target-completed", target, result }));
+        logger.out(TagProgressPresenter.formatProgress({ type: "target-completed", target, result }));
     }
     static formatProgress(event) {
         const targetDisplayName = (target) => target.packageName ?? target.rootRelativeTargetPath;
@@ -29,22 +27,21 @@ const colors = {
     yellow: "\x1b[33m",
 };
 /**
- * Prints a tag run's target table, warnings, and summary, and returns the exit code.
+ * Prints a tag run's target table, warnings, and summary to the human reader.
  *
  * @since 0.3.16-canary.0
  */
-export function presentTagSyncResult(result, rootDir) {
+export function presentTagResult(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 CLI_EXIT_GENERAL_ERROR;
+        return;
     }
     const warningsAndErrorsSection = formatWarningsAndErrors(result);
     if (warningsAndErrorsSection) {
         logger.err(warningsAndErrorsSection);
     }
     logger.out(formatSummary(result));
-    return exitCodeForTagSyncResult(result);
 }
 function withColorizedLine(line, colorCode) {
     return `${colorCode}${line}${colorReset}`;

package/dist/tag/prepare.d.ts

@@ -0,0 +1,13 @@
+import type { AppError } from "#/core/errors";
+import type { Filesystem } from "#/core/filesystem/filesystem";
+import type { Result } from "#/core/result";
+import type { TagCommandPrelude } from "#/tag/domain/types";
+/**
+ * Resolves the repo root, config, and optional target path into the prelude a tag run starts from.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function prepareTag(fs: Filesystem, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<TagCommandPrelude, AppError>>;

package/dist/tag/prepare.js

@@ -1,16 +1,16 @@
 import { loadCodefastConfig } from "#/core/config";
 import { ok } from "#/core/result";
-import { findRepoRoot } from "#/core/workspace/resolver";
-import { resolveProvidedTagTargetPath } from "#/tag/resolve-target-path";
+import { resolveProjectRoot } from "#/core/workspace/resolver";
+import { resolveProvidedTagTargetPath } from "#/tag/target/resolve-path";
 /**
  * Resolves the repo root, config, and optional target path into the prelude a tag run starts from.
  *
  * @since 0.3.16-canary.0
  */
-export async function prepareTagSync(fs, args) {
+export async function prepareTag(fs, args) {
     let rootDir;
     try {
-        rootDir = findRepoRoot(args.currentWorkingDirectory, fs);
+        rootDir = resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir;
     }
     catch {
         rootDir = args.currentWorkingDirectory;

package/dist/tag/run.d.ts

@@ -0,0 +1,10 @@
+import { AppError } from "#/core/errors";
+import type { Filesystem } from "#/core/filesystem/filesystem";
+import type { Result } from "#/core/result";
+import type { TagExecutionInput, TagResult } from "#/tag/domain/types";
+/**
+ * Applies `@since` tags across the selected targets and returns the aggregate result.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function runTag(fs: Filesystem, input: TagExecutionInput): Promise<Result<TagResult, AppError>>;

package/dist/tag/{sync.js → run.js}

@@ -1,26 +1,37 @@
 import path from "node:path";
 import { AppError } from "#/core/errors";
 import { messageFrom } from "#/core/errors";
-import { createAnyGlobMatcher } from "#/core/glob";
 import { err, ok } from "#/core/result";
-import { resolveTagTargetCandidates } from "#/tag/target-candidates";
-import { runTagOnTarget } from "#/tag/target-runner";
+import { filterSkippedCandidates } from "#/tag/domain/skip-filter";
+import { extractDistinctVersions, summarizeVersions } from "#/tag/domain/version-summary";
+import { resolveTagTargetCandidates } from "#/tag/target/candidates";
+import { runTagOnTarget } from "#/tag/target/runner";
 /**
- * Runs the tag sync across the selected targets and returns the aggregate result.
+ * Applies `@since` tags across the selected targets and returns the aggregate result.
  *
  * @since 0.3.16-canary.0
  */
-export async function runTagSync(fs, input) {
+export async function runTag(fs, input) {
     try {
         const tagConfig = input.config;
         const targetCandidates = await resolveTagTargetCandidates(fs, input.rootDir, input.targetPath);
         const { includedCandidates, skippedPackages } = filterSkippedCandidates(targetCandidates, 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 allFileResults = [];
+        let filesScanned = 0;
+        let filesChanged = 0;
+        let taggedDeclarations = 0;
+        for (const targetResult of targetExecutionResults) {
+            const runResult = targetResult.result;
+            if (runResult === null) {
+                continue;
+            }
+            allFileResults.push(...runResult.fileResults);
+            filesScanned += runResult.filesScanned;
+            filesChanged += runResult.filesChanged;
+            taggedDeclarations += runResult.taggedDeclarations;
+        }
         const modifiedFiles = allFileResults.filter((entry) => entry.changed).map((entry) => entry.filePath);
         const hookError = input.write && modifiedFiles.length > 0
             ? await runTagOnAfterWriteHook(tagConfig?.onAfterWrite, modifiedFiles)
@@ -57,20 +68,6 @@ async function runTagOnAfterWriteHook(hook, modifiedFiles) {
         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 {
@@ -103,33 +100,6 @@ function resolveTargetSelection(fs, candidate, rootDir) {
         packageName: candidate.packageName,
     };
 }
-/**
- * Partition tag target candidates into those to tag and those to skip, matching
- * each candidate's package name against `skipPackages` as glob patterns.
- * Candidates without a package name (e.g. an explicit-target path) are never skipped.
- *
- * @since 0.5.0-canary.0
- */
-export function filterSkippedCandidates(targetCandidates, skipPackages) {
-    if (!skipPackages || skipPackages.length === 0) {
-        return {
-            includedCandidates: targetCandidates,
-            skippedPackages: [],
-        };
-    }
-    const isSkipped = createAnyGlobMatcher(skipPackages);
-    const includedCandidates = [];
-    const skippedPackages = [];
-    for (const candidate of targetCandidates) {
-        const packageName = candidate.packageName;
-        if (packageName && isSkipped(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);

package/dist/tag/target/candidates.d.ts

@@ -0,0 +1,8 @@
+import type { Filesystem } from "#/core/filesystem/filesystem";
+import type { TagTargetCandidate } from "#/tag/domain/types";
+/**
+ * Resolves the candidate targets for a tag run: the explicit target, or the discovered workspace packages.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function resolveTagTargetCandidates(fs: Filesystem, rootDir: string, explicitTarget: string | undefined): Promise<Array<TagTargetCandidate>>;

package/dist/tag/{target-candidates.js → target/candidates.js}

@@ -1,7 +1,7 @@
 import path from "node:path";
-import { z } from "zod";
+import * as z from "zod";
 import { listWorkspacePackageDirectories } from "#/core/workspace/resolver";
-const packageJsonFileName = "package.json";
+import { packageJsonFileName } from "#/core/workspace/well-known-files";
 const packageJsonNameSchema = z.looseObject({
     name: z.string().min(1).optional(),
 });

package/dist/tag/target/resolve-path.d.ts

@@ -0,0 +1,10 @@
+import type { Filesystem } from "#/core/filesystem/filesystem";
+/**
+ * Canonicalizes the user-provided target path, or returns `undefined` when none was given.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function resolveProvidedTagTargetPath(fs: Filesystem, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): string | undefined;

package/dist/tag/target/runner.d.ts

@@ -0,0 +1,8 @@
+import type { Filesystem } from "#/core/filesystem/filesystem";
+import type { TagRunOptions, TagRunResult } from "#/tag/domain/types";
+/**
+ * Stamps `@since` tags across one target's TypeScript files and returns the run result.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function runTagOnTarget(fs: Filesystem, targetPath: string, opts: TagRunOptions): TagRunResult;

package/dist/tag/{target-runner.js → target/runner.js}

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { walkTsxFiles } from "#/core/workspace/typescript-walk";
-import { TagSinceWriter } from "#/tag/since-writer";
-import { resolveNearestPackageVersion } from "#/tag/version-resolver";
+import { TagSinceWriter } from "#/tag/writer/since-writer";
+import { resolveNearestPackageVersion } from "#/tag/writer/version-resolver";
 /**
  * Stamps `@since` tags across one target's TypeScript files and returns the run result.
  *

package/dist/tag/writer/since-writer.d.ts

@@ -0,0 +1,32 @@
+import type { Filesystem } from "#/core/filesystem/filesystem";
+import type { TagFileResult } from "#/tag/domain/types";
+/**
+ * The writer that adds missing `@since` tags to a file's exported declarations.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare class TagSinceWriter {
+    private readonly fs;
+    private readonly sinceDocumentationTag;
+    constructor(fs: Filesystem);
+    applySinceTagsToFile(filePath: string, version: string, write: boolean): TagFileResult;
+    /**
+     * The taggable declaration a top-level statement introduces, resolving the
+     * `export … <decl>` wrapper to the wrapper node — its `start` sits at `export`,
+     * matching `ts.getStart` on a modifier-bearing declaration.
+     */
+    private taggableDeclarationOf;
+    private declarationNames;
+    private addDeclarationName;
+    private collectLocalNamedDeclarations;
+    private collectExportedDeclarations;
+    /**
+     * The JSDoc block documenting `anchor`: the nearest preceding `/** … *\/` whose
+     * gap to the declaration is whitespace only, mirroring TS comment attachment.
+     */
+    private associatedJsDoc;
+    private jsDocHasSinceTag;
+    private makeJSDocSinceLine;
+    private makeSinceOnlyJSDocBlock;
+    private makeDeclarationSinceLine;
+}

package/dist/tag/writer/version-resolver.d.ts

@@ -0,0 +1,7 @@
+import type { Filesystem } from "#/core/filesystem/filesystem";
+/**
+ * Returns the `version` of the nearest enclosing `package.json` above a target path.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function resolveNearestPackageVersion(fs: Filesystem, targetPath: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codefast/cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Developer CLI for the Codefast monorepo (arrange, audit, mirror, pack-slim, tag)",
   "keywords": [
     "cli",
@@ -31,11 +31,22 @@
     "LICENSE"
   ],
   "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "imports": {
     "#/*": {
+      "types": "./dist/*.d.ts",
       "default": "./dist/*.js"
     }
   },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -46,7 +57,15 @@
     "oxc-parser": "^0.148.0",
     "picomatch": "^4.0.7",
     "yaml": "^2.9.0",
-    "zod": "^4.5.4"
+    "zod": "^4.6.2"
+  },
+  "peerDependencies": {
+    "typescript": "^7.0.2"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=24.0.0"

package/dist/arrange/cli-schema.js

@@ -1,34 +0,0 @@
-import { z } from "zod";
-/**
- * The `zod` schema validating an `arrange analyze` request.
- *
- * @since 0.3.16-canary.0
- */
-export const arrangeAnalyzeDirectoryRequestSchema = z.object({
-    analyzeRootPath: z.string().min(1, "analyzeRootPath is required"),
-});
-/**
- * The `zod` schema validating an `arrange` run request.
- *
- * @since 0.3.16-canary.0
- */
-export const arrangeSyncRunRequestSchema = z.object({
-    rootDir: z.string().min(1),
-    targetPath: z.string().min(1),
-    write: z.boolean(),
-    withClassName: z.boolean().optional(),
-    cnImport: z.string().optional(),
-    config: z.unknown().optional(),
-});
-/**
- * The `zod` schema validating an `arrange group` request.
- *
- * @since 0.3.16-canary.0
- */
-export const arrangeSuggestGroupsRequestSchema = z.object({
-    inlineClasses: z
-        .string()
-        .min(1, 'Pass a class string. Example: codefast arrange group "flex gap-2 text-sm rounded-md"'),
-    emitTvStyleArray: z.boolean(),
-    trailingClassName: z.boolean(),
-});