@codefast/cli 0.8.1 → 0.10.0

package/dist/pack-slim/domain/transform.js

@@ -1,8 +1,23 @@
-/** Pure transforms that strip a package's source lane from a publish artifact. */
+/** Pure transforms that slim a package's manifest and dist for publish. */
 /**
  * The emitted-file extensions that may carry a `sourceMappingURL` directive.
  */
 const MAP_ANNOTATED_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".d.ts", ".d.mts", ".d.cts"]);
+/**
+ * The script names npm and pnpm run on their own, on a consumer's install or on this package's publish.
+ */
+const LIFECYCLE_SCRIPT_STEMS = new Set([
+    "install",
+    "prepare",
+    "prepublish",
+    "prepublishOnly",
+    "pack",
+    "publish",
+]);
+/**
+ * The characters that make a `files` entry a glob rather than a path.
+ */
+const GLOB_CHARACTERS = /[*?[\]{}]/;
 /**
  * Whether a dist entry is a source-map sidecar (`*.map`).
  *
@@ -25,11 +40,26 @@ export function isMapAnnotatedFile(fileName) {
     return false;
 }
 /**
- * Produces a publish manifest with `src` dropped from `files` and every `source` export/import condition removed.
+ * Whether a script name is an install or publish lifecycle hook, with or without its `pre`/`post` prefix.
+ *
+ * @remarks Publish hooks stay because `pnpm publish` runs them right after pack-slim; install hooks stay because a
+ * consumer's package manager runs them.
+ *
+ * @since 0.9.0
+ */
+export function isLifecycleScript(name) {
+    if (LIFECYCLE_SCRIPT_STEMS.has(name)) {
+        return true;
+    }
+    const stem = name.replace(/^(?:pre|post)/, "");
+    return stem !== name && LIFECYCLE_SCRIPT_STEMS.has(stem);
+}
+/**
+ * Produces a publish manifest carrying only what a consumer's `tsc` and Node read.
  *
- * @remarks Operates on a structural clone, so the caller's manifest is left intact. A consumer never enables the
- * `source` condition and resolves `#/` through `types`/`default` to `dist`, so dropping the source lane and the shipped
- * sources it points at leaves the published surface whole.
+ * @remarks Operates on a structural clone, so the caller's manifest is left intact. A consumer never enables `source`
+ * and resolves `#/` through `types`/`default` to `dist`, so dropping the source lane, the `imports` left pointing
+ * outside `files`, the scripts that are not lifecycle hooks, and `devDependencies` leaves the published surface whole.
  *
  * @since 0.8.1
  */
@@ -38,10 +68,21 @@ export function slimPublishManifest(manifest) {
     const filesSrcRemoved = removeSrcFromFiles(draft);
     const exportsSourceRemoved = deleteSourceConditions(draft.exports);
     const importsSourceRemoved = deleteSourceConditions(draft.imports);
-    const changed = filesSrcRemoved || exportsSourceRemoved > 0 || importsSourceRemoved > 0;
+    const importsUnshippedRemoved = deleteUnshippedImports(draft);
+    const scriptsRemoved = deleteDevOnlyScripts(draft);
+    const devDependenciesRemoved = deleteDevDependencies(draft);
+    const changed = JSON.stringify(draft) !== JSON.stringify(manifest);
     return {
         manifest: draft,
-        report: { filesSrcRemoved, exportsSourceRemoved, importsSourceRemoved, changed },
+        report: {
+            filesSrcRemoved,
+            exportsSourceRemoved,
+            importsSourceRemoved,
+            importsUnshippedRemoved,
+            scriptsRemoved,
+            devDependenciesRemoved,
+            changed,
+        },
     };
 }
 /**
@@ -69,8 +110,8 @@ function removeSrcFromFiles(manifest) {
     manifest.files = next;
     return true;
 }
-// Walks a conditions tree deleting every `source` key. A subpath key always starts with ".", so only real
-// condition objects match, and a source-only entry never occurs here, so no node is left empty.
+// Walks a conditions tree deleting every `source` key. A subpath key always starts with ".", so only real condition
+// objects match; an `imports` entry this leaves empty is what the unshipped pass removes.
 function deleteSourceConditions(node) {
     if (Array.isArray(node)) {
         let removed = 0;
@@ -79,17 +120,102 @@ function deleteSourceConditions(node) {
         }
         return removed;
     }
-    if (node === null || typeof node !== "object") {
+    if (!isRecord(node)) {
         return 0;
     }
-    const record = node;
     let removed = 0;
-    if ("source" in record) {
-        delete record.source;
+    if ("source" in node) {
+        delete node.source;
         removed += 1;
     }
-    for (const key of Object.keys(record)) {
-        removed += deleteSourceConditions(record[key]);
+    for (const key of Object.keys(node)) {
+        removed += deleteSourceConditions(node[key]);
     }
     return removed;
+}
+// Keeps an `imports` entry only while one of its targets lands inside a path `files` ships. `files` is read after the
+// `src` drop, so a lane still pointing at `./src/*` counts as unshipped; with no `files` at all npm ships everything.
+function deleteUnshippedImports(manifest) {
+    const imports = manifest.imports;
+    const files = manifest.files;
+    if (!isRecord(imports) || !Array.isArray(files)) {
+        return 0;
+    }
+    const shippedEntries = files.filter((entry) => typeof entry === "string");
+    let removed = 0;
+    for (const specifier of Object.keys(imports)) {
+        const targets = collectTargets(imports[specifier]);
+        if (targets.some((target) => isShippedTarget(target, shippedEntries))) {
+            continue;
+        }
+        delete imports[specifier];
+        removed += 1;
+    }
+    if (Object.keys(imports).length === 0) {
+        delete manifest.imports;
+    }
+    return removed;
+}
+function collectTargets(node, into = []) {
+    if (typeof node === "string") {
+        into.push(node);
+    }
+    else if (Array.isArray(node)) {
+        for (const item of node) {
+            collectTargets(item, into);
+        }
+    }
+    else if (isRecord(node)) {
+        for (const value of Object.values(node)) {
+            collectTargets(value, into);
+        }
+    }
+    return into;
+}
+// A glob entry is left to npm, so any target counts as shipped under it; a negated entry ships nothing.
+function isShippedTarget(target, shippedEntries) {
+    const relativeTarget = stripDotSlash(target);
+    return shippedEntries.some((entry) => {
+        if (entry.startsWith("!")) {
+            return false;
+        }
+        if (GLOB_CHARACTERS.test(entry)) {
+            return true;
+        }
+        const shipped = stripDotSlash(entry).replace(/\/+$/, "");
+        return relativeTarget === shipped || relativeTarget.startsWith(`${shipped}/`);
+    });
+}
+function stripDotSlash(filePath) {
+    return filePath.startsWith("./") ? filePath.slice(2) : filePath;
+}
+// Drops every script that is not a lifecycle hook, and the field itself once nothing is left in it.
+function deleteDevOnlyScripts(manifest) {
+    const scripts = manifest.scripts;
+    if (!isRecord(scripts)) {
+        return 0;
+    }
+    let removed = 0;
+    for (const name of Object.keys(scripts)) {
+        if (isLifecycleScript(name)) {
+            continue;
+        }
+        delete scripts[name];
+        removed += 1;
+    }
+    if (Object.keys(scripts).length === 0) {
+        delete manifest.scripts;
+    }
+    return removed;
+}
+function deleteDevDependencies(manifest) {
+    const devDependencies = manifest.devDependencies;
+    if (!isRecord(devDependencies)) {
+        return 0;
+    }
+    delete manifest.devDependencies;
+    return Object.keys(devDependencies).length;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
 }

package/dist/pack-slim/domain/types.d.ts

@@ -0,0 +1,46 @@
+/** Stats and progress types for a pack-slim run. */
+/**
+ * The outcome of slimming one workspace package.
+ *
+ * @since 0.8.1
+ */
+export interface PackSlimPackageStats {
+    name: string;
+    path: string;
+    skipped: boolean;
+    skipReason: string;
+    error: string | null;
+    filesSrcRemoved: boolean;
+    exportsSourceRemoved: number;
+    importsSourceRemoved: number;
+    importsUnshippedRemoved: number;
+    scriptsRemoved: number;
+    devDependenciesRemoved: number;
+    mapFilesDeleted: number;
+    sourceCommentsStripped: number;
+    changed: boolean;
+}
+/**
+ * The aggregate stats of a pack-slim run across every targeted package.
+ *
+ * @since 0.8.1
+ */
+export interface PackSlimRunStats {
+    packagesFound: number;
+    packagesProcessed: number;
+    packagesSkipped: number;
+    packagesErrored: number;
+    packagesChanged: number;
+    totalMapFilesDeleted: number;
+    packageDetails: Array<PackSlimPackageStats>;
+}
+/**
+ * The progress events a pack-slim run emits as it works through the packages.
+ *
+ * @since 0.8.1
+ */
+export interface PackSlimProgressListener {
+    onBanner?(): void;
+    onPackageComplete?(stats: PackSlimPackageStats, ordinal: number, total: number): void;
+    onComplete?(stats: PackSlimRunStats, elapsedSeconds: number): void;
+}

package/dist/pack-slim/output.d.ts

@@ -0,0 +1,15 @@
+import type { PackSlimPackageStats, PackSlimProgressListener, PackSlimRunStats } from "#/pack-slim/domain/types";
+/**
+ * A progress listener that renders pack-slim run events as human-readable CLI lines.
+ *
+ * @since 0.8.1
+ */
+export declare class PackSlimProgressPresenter implements PackSlimProgressListener {
+    private dryRun;
+    configure(options: {
+        readonly dryRun: boolean;
+    }): void;
+    onBanner(): void;
+    onPackageComplete(stats: PackSlimPackageStats, ordinal: number, total: number): void;
+    onComplete(stats: PackSlimRunStats, elapsedSeconds: number): void;
+}

package/dist/pack-slim/output.js

@@ -10,7 +10,7 @@ export class PackSlimProgressPresenter {
         this.dryRun = options.dryRun;
     }
     onBanner() {
-        logger.out(this.dryRun ? "pack-slim (dry run) — no files will change" : "pack-slim — stripping source lane");
+        logger.out(this.dryRun ? "pack-slim (dry run) — no files will change" : "pack-slim — slimming publish artifacts");
     }
     onPackageComplete(stats, ordinal, total) {
         const position = `[${ordinal}/${total}]`;
@@ -37,6 +37,15 @@ export class PackSlimProgressPresenter {
         if (stats.importsSourceRemoved > 0) {
             parts.push(`imports:source×${stats.importsSourceRemoved}`);
         }
+        if (stats.importsUnshippedRemoved > 0) {
+            parts.push(`imports:unshipped×${stats.importsUnshippedRemoved}`);
+        }
+        if (stats.scriptsRemoved > 0) {
+            parts.push(`scripts×${stats.scriptsRemoved}`);
+        }
+        if (stats.devDependenciesRemoved > 0) {
+            parts.push(`devDependencies×${stats.devDependenciesRemoved}`);
+        }
         if (stats.mapFilesDeleted > 0) {
             parts.push(`maps×${stats.mapFilesDeleted}`);
         }

package/dist/pack-slim/sync.d.ts

@@ -0,0 +1,23 @@
+import { AppError } from "#/core/errors";
+import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Result } from "#/core/result";
+import type { PackSlimRunRequest } from "#/pack-slim/cli-schema";
+import type { PackSlimProgressListener, PackSlimRunStats } from "#/pack-slim/domain/types";
+/**
+ * A pack-slim run request paired with an optional progress listener.
+ *
+ * @since 0.8.1
+ */
+export type PackSlimRunInput = PackSlimRunRequest & {
+    readonly listener?: PackSlimProgressListener | undefined;
+};
+/**
+ * Slims every published package's manifest and build output for publish and returns the aggregate stats.
+ *
+ * @remarks Meant to run on an ephemeral CI checkout right before `changeset publish`: it rewrites `package.json` down to
+ * what a consumer reads, drops `dist` source maps, and clears their now-dangling `sourceMappingURL` directives, so the
+ * tarball ships only `dist` runtime and types. Private packages are skipped because `changeset publish` never publishes them.
+ *
+ * @since 0.8.1
+ */
+export declare function runPackSlim(fs: FilesystemPort, input: PackSlimRunInput): Promise<Result<PackSlimRunStats, AppError>>;

package/dist/pack-slim/sync.js

@@ -2,14 +2,14 @@ import path from "node:path";
 import { AppError, messageFrom } from "#/core/errors";
 import { err, ok } from "#/core/result";
 import { listWorkspacePackageDirectories } from "#/core/workspace/resolver";
-import { DIST_DIR, PACKAGE_JSON } from "#/mirror/domain/constants";
+import { distDirName, packageJsonFileName } from "#/core/workspace/well-known-files";
 import { isMapAnnotatedFile, isSourceMapFile, slimPublishManifest, stripSourceMappingComment, } from "#/pack-slim/domain/transform";
 /**
- * Strips the source lane from every published package's build output and returns the aggregate stats.
+ * Slims every published package's manifest and build output for publish and returns the aggregate stats.
  *
- * @remarks Meant to run on an ephemeral CI checkout right before `changeset publish`: it rewrites `package.json`, drops
- * `dist` source maps, and clears their now-dangling `sourceMappingURL` directives, so the tarball ships only `dist`
- * runtime and types. Private packages are skipped because `changeset publish` never publishes them.
+ * @remarks Meant to run on an ephemeral CI checkout right before `changeset publish`: it rewrites `package.json` down to
+ * what a consumer reads, drops `dist` source maps, and clears their now-dangling `sourceMappingURL` directives, so the
+ * tarball ships only `dist` runtime and types. Private packages are skipped because `changeset publish` never publishes them.
  *
  * @since 0.8.1
  */
@@ -47,7 +47,7 @@ export async function runPackSlim(fs, input) {
 async function resolveTargets(fs, rootDir, packageFilter) {
     if (packageFilter !== undefined) {
         const packageDir = path.resolve(rootDir, packageFilter);
-        if (!fs.existsSync(path.join(packageDir, PACKAGE_JSON))) {
+        if (!fs.existsSync(path.join(packageDir, packageJsonFileName))) {
             throw new Error(`No package.json under "${packageFilter}"`);
         }
         return [packageDir];
@@ -56,7 +56,7 @@ async function resolveTargets(fs, rootDir, packageFilter) {
     return [...layout.packageDirectoryPathsAbsolute].sort((left, right) => left.localeCompare(right));
 }
 async function slimWorkspacePackage(fs, packageDir, write) {
-    const packageJsonPath = path.join(packageDir, PACKAGE_JSON);
+    const packageJsonPath = path.join(packageDir, packageJsonFileName);
     const pkgStats = {
         name: path.basename(packageDir),
         path: packageDir,
@@ -66,6 +66,9 @@ async function slimWorkspacePackage(fs, packageDir, write) {
         filesSrcRemoved: false,
         exportsSourceRemoved: 0,
         importsSourceRemoved: 0,
+        importsUnshippedRemoved: 0,
+        scriptsRemoved: 0,
+        devDependenciesRemoved: 0,
         mapFilesDeleted: 0,
         sourceCommentsStripped: 0,
         changed: false,
@@ -94,10 +97,13 @@ async function slimWorkspacePackage(fs, packageDir, write) {
         pkgStats.filesSrcRemoved = report.filesSrcRemoved;
         pkgStats.exportsSourceRemoved = report.exportsSourceRemoved;
         pkgStats.importsSourceRemoved = report.importsSourceRemoved;
+        pkgStats.importsUnshippedRemoved = report.importsUnshippedRemoved;
+        pkgStats.scriptsRemoved = report.scriptsRemoved;
+        pkgStats.devDependenciesRemoved = report.devDependenciesRemoved;
         if (report.changed && write) {
             await fs.writeFile(packageJsonPath, `${JSON.stringify(slimmed, null, 2)}\n`, "utf8");
         }
-        await pruneDist(fs, path.join(packageDir, DIST_DIR), write, pkgStats);
+        await pruneDist(fs, path.join(packageDir, distDirName), write, pkgStats);
         pkgStats.changed = report.changed || pkgStats.mapFilesDeleted > 0 || pkgStats.sourceCommentsStripped > 0;
     }
     catch (caughtError) {

package/dist/pack-slim/working-tree.d.ts

@@ -0,0 +1,20 @@
+import { AppError } from "#/core/errors";
+import type { Result } from "#/core/result";
+/**
+ * Whether git's tracked-only porcelain output reports any uncommitted change.
+ *
+ * @remarks The output is read with `--untracked-files=no`, so untracked and gitignored paths (like the freshly built
+ * `dist`) never appear — any non-blank line is a staged or unstaged change to a tracked file.
+ *
+ * @since 0.8.1
+ */
+export declare function hasUncommittedTrackedChanges(porcelainOutput: string): boolean;
+/**
+ * Refuses when the git working tree carries uncommitted tracked changes, so a destructive slim never lands on real work.
+ *
+ * @remarks pack-slim rewrites tracked `package.json` files and deletes build output; its result must never be committed.
+ * A caller passing `--force` skips this, and `--dry-run` never reaches it because it writes nothing.
+ *
+ * @since 0.8.1
+ */
+export declare function ensureWorkingTreeClean(rootDir: string): Result<void, AppError>;

package/dist/tag/cli-result.d.ts

@@ -0,0 +1,7 @@
+import type { TagSyncResult } from "#/tag/domain/types";
+/**
+ * Maps a tag run's result to the process exit code.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function exitCodeForTagSyncResult(result: TagSyncResult): number;

package/dist/tag/cli-schema.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import type { TagSyncRunRequest } from "#/tag/sync";
+/**
+ * Zod schema validating a `TagSyncRunRequest`.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare const tagSyncRunRequestSchema: z.ZodType<TagSyncRunRequest>;

package/dist/tag/command.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+/**
+ * Creates the `tag` subcommand, which stamps `@since` tags on exported declarations.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function createTagCommand(): Command;

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

@@ -0,0 +1,111 @@
+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 TagSyncResult = {
+    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;
+}
+export {};

package/dist/tag/output.d.ts

@@ -0,0 +1,17 @@
+import type { TagProgressListener, TagResolvedTarget, TagSyncResult, 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 TagSyncProgressPresenter 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, and returns the exit code.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function presentTagSyncResult(result: TagSyncResult, rootDir: string): number;

package/dist/tag/prepare.d.ts

@@ -0,0 +1,13 @@
+import type { AppError } from "#/core/errors";
+import type { FilesystemPort } from "#/core/filesystem/port";
+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 prepareTagSync(fs: FilesystemPort, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<TagCommandPrelude, AppError>>;

package/dist/tag/prepare.js

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

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

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

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

@@ -0,0 +1,32 @@
+import type { FilesystemPort } from "#/core/filesystem/port";
+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: FilesystemPort);
+    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/sync.d.ts

@@ -0,0 +1,42 @@
+import { AppError } from "#/core/errors";
+import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Result } from "#/core/result";
+import type { TagProgressListener, TagSyncResult, TagTargetCandidate } from "#/tag/domain/types";
+/**
+ * The inputs a tag run is invoked with.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type TagSyncRunRequest = {
+    rootDir: string;
+    write: boolean;
+    json?: boolean | undefined;
+    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 TagSyncExecutionInput = TagSyncRunRequest & {
+    readonly listener?: TagProgressListener | undefined;
+};
+/**
+ * Runs the tag sync across the selected targets and returns the aggregate result.
+ *
+ * @since 0.3.16-canary.0
+ */
+export declare function runTagSync(fs: FilesystemPort, input: TagSyncExecutionInput): Promise<Result<TagSyncResult, AppError>>;
+/**
+ * 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 declare function filterSkippedCandidates(targetCandidates: Array<TagTargetCandidate>, skipPackages: ReadonlyArray<string> | undefined): {
+    includedCandidates: Array<TagTargetCandidate>;
+    skippedPackages: Array<string>;
+};