@codefast/cli 0.13.0 → 0.14.0

package/dist/audit/layers/domain/layering.js

@@ -0,0 +1,191 @@
+/**
+ * The layering rule one package's `src/` follows: a value import never points up the configured layers.
+ */
+import path from "node:path";
+import { parseSync } from "oxc-parser";
+import { isOxcNode, programStatements } from "#core/oxc-node";
+import { firstLineOf, lineOfOffset } from "#core/source-position";
+const MODULE_EXTENSIONS = [".tsx", ".ts", ".js"];
+function withoutModuleExtension(name) {
+    for (const extension of MODULE_EXTENSIONS) {
+        if (name.endsWith(extension)) {
+            return name.slice(0, -extension.length);
+        }
+    }
+    return name;
+}
+/**
+ * The key a layer entry and a module path share: the first path segment, without a module extension.
+ *
+ * @remarks `errors.ts`, `errors/` and `errors/taxonomy.ts` all key as `errors`, so a layer entry names
+ * a family directly under the root — a directory, or a lone module sitting flat.
+ *
+ * @since 0.14.0
+ */
+export function layerKeyOf(modulePath) {
+    const [first = ""] = modulePath.split("/");
+    return withoutModuleExtension(first);
+}
+/**
+ * Returns why a layer list breaks its contract, or `undefined` when every entry is a family under the root, placed once.
+ *
+ * @since 0.14.0
+ */
+export function invalidLayerEntry(layers) {
+    const seen = new Map();
+    for (const layer of layers) {
+        for (const entry of layer) {
+            const trimmed = entry.replace(/\/$/, "");
+            if (trimmed === "" || trimmed.includes("/")) {
+                return `layer entry "${entry}" must name a directory or a module file directly under the root`;
+            }
+            const key = layerKeyOf(trimmed);
+            const earlier = seen.get(key);
+            if (earlier !== undefined) {
+                return `layer entry "${entry}" is already placed by "${earlier}"`;
+            }
+            seen.set(key, entry);
+        }
+    }
+    return undefined;
+}
+/**
+ * A package's layers, bottom to top, answering the placement of any module path under the root.
+ *
+ * @since 0.14.0
+ */
+export class LayerMap {
+    #placementByKey = new Map();
+    constructor(layers) {
+        layers.forEach((layer, index) => {
+            for (const entry of layer) {
+                this.#placementByKey.set(layerKeyOf(entry.replace(/\/$/, "")), { index, entry });
+            }
+        });
+    }
+    /** The placement of a root-relative module path, or `undefined` when no layer names its family. */
+    placementOf(modulePath) {
+        return this.#placementByKey.get(layerKeyOf(modulePath));
+    }
+}
+function sourceValueOf(node) {
+    const source = node.source;
+    return isOxcNode(source) && typeof source.value === "string" ? source.value : undefined;
+}
+function everySpecifierIsTypeOnly(node, kindField) {
+    const specifiers = Array.isArray(node.specifiers) ? node.specifiers.filter(isOxcNode) : [];
+    return specifiers.length > 0 && specifiers.every((specifier) => specifier[kindField] === "type");
+}
+/**
+ * The module a top-level statement imports or re-exports at runtime, or `undefined` when it erases at build time.
+ */
+function valueSpecifierOf(statement) {
+    if (statement.type === "ImportDeclaration") {
+        if (statement.importKind === "type" || everySpecifierIsTypeOnly(statement, "importKind")) {
+            return undefined;
+        }
+        return sourceValueOf(statement);
+    }
+    if (statement.type === "ExportNamedDeclaration") {
+        if (statement.exportKind === "type" || everySpecifierIsTypeOnly(statement, "exportKind")) {
+            return undefined;
+        }
+        return sourceValueOf(statement);
+    }
+    if (statement.type === "ExportAllDeclaration") {
+        return statement.exportKind === "type" ? undefined : sourceValueOf(statement);
+    }
+    return undefined;
+}
+/**
+ * The root-relative module path a specifier names, or `undefined` for one outside the root (a package, a
+ * relative path climbing out).
+ *
+ * @remarks A `#` subpath import maps to the root directly, which is how every package's `#*` imports
+ * field is declared; a relative import resolves against the importing module.
+ */
+function moduleTargetOf(specifier, fromModulePath) {
+    if (specifier.startsWith("#")) {
+        const target = specifier.slice(1);
+        return target === "" ? undefined : target;
+    }
+    if (specifier.startsWith("./") || specifier.startsWith("../")) {
+        const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(fromModulePath), specifier));
+        return resolved.startsWith("../") ? undefined : resolved;
+    }
+    return undefined;
+}
+function collectDynamicImports(node, visit) {
+    if (node.type === "ImportExpression") {
+        const specifier = sourceValueOf(node);
+        if (specifier !== undefined) {
+            visit(node, specifier);
+        }
+    }
+    for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (isOxcNode(item)) {
+                    collectDynamicImports(item, visit);
+                }
+            }
+        }
+        else if (isOxcNode(value)) {
+            collectDynamicImports(value, visit);
+        }
+    }
+}
+/**
+ * Scans one module against its package's layers and returns the violations: the module sitting in no
+ * layer, or a value import or re-export whose target sits in a higher layer, or in none.
+ *
+ * @remarks Type-only imports and re-exports erase at build time and couple nothing, so they pass
+ * whichever way they point. Dynamic `import()` counts as a value import wherever it sits.
+ *
+ * @since 0.14.0
+ */
+export function auditLayeringSource(filePath, modulePath, sourceText, layers) {
+    const own = layers.placementOf(modulePath);
+    if (own === undefined) {
+        return [
+            {
+                line: 1,
+                raw: modulePath,
+                reason: `module sits in no configured layer — place "${layerKeyOf(modulePath)}" in one`,
+            },
+        ];
+    }
+    const violations = [];
+    const check = (node, specifier) => {
+        const target = moduleTargetOf(specifier, modulePath);
+        if (target === undefined) {
+            return;
+        }
+        const placement = layers.placementOf(target);
+        if (placement === undefined) {
+            violations.push(violationAt(sourceText, node, `imports "${specifier}", which sits in no configured layer`));
+        }
+        else if (placement.index > own.index) {
+            violations.push(violationAt(sourceText, node, `value import of "${specifier}" points up the layers — ${own.entry} (layer ${String(own.index + 1)}) reaches ${placement.entry} (layer ${String(placement.index + 1)})`));
+        }
+    };
+    const { program } = parseSync(filePath, sourceText);
+    for (const statement of programStatements(program)) {
+        const specifier = valueSpecifierOf(statement);
+        if (specifier !== undefined) {
+            check(statement, specifier);
+        }
+    }
+    if (isOxcNode(program)) {
+        collectDynamicImports(program, check);
+    }
+    violations.sort((a, b) => a.line - b.line);
+    return violations;
+}
+function violationAt(sourceText, node, reason) {
+    return {
+        line: lineOfOffset(sourceText, node.start),
+        raw: firstLineOf(sourceText.slice(node.start, node.end)),
+        reason,
+    };
+}

package/dist/audit/layers/output.d.ts

@@ -0,0 +1,7 @@
+import type { LayersAuditResult } from "#audit/domain/types";
+/**
+ * Human-readable layering report.
+ *
+ * @since 0.14.0
+ */
+export declare function presentLayersAuditResult(result: LayersAuditResult): void;

package/dist/audit/{constants → layers}/output.js

@@ -1,10 +1,10 @@
 import { logger } from "#core/logger";
 /**
- * Human-readable numeric-constant report.
+ * Human-readable layering report.
  *
- * @since 0.11.0
+ * @since 0.14.0
  */
-export function presentConstantAuditResult(result) {
+export function presentLayersAuditResult(result) {
     for (const file of result.files) {
         logger.out(`\n${file.relativePath}`);
         for (const { line, raw, reason } of file.violations) {
@@ -13,9 +13,9 @@ export function presentConstantAuditResult(result) {
     }
     const allowlistSuffix = result.allowlistedCount > 0 ? ` (${result.allowlistedCount} allowlisted)` : "";
     if (result.violationCount > 0) {
-        logger.out(`\n✖ ${result.violationCount} numeric constant(s) with no kind named${allowlistSuffix}`);
+        logger.out(`\n✖ ${result.violationCount} layering violation(s)${allowlistSuffix}`);
     }
     else {
-        logger.out(`✓ Every numeric constant names its kind across ${result.scannedFileCount} source file(s)${allowlistSuffix}`);
+        logger.out(`✓ Every value import points down the layers across ${result.scannedFileCount} file(s) in ${result.packageCount} package(s)${allowlistSuffix}`);
     }
 }

package/dist/audit/layers/prepare.d.ts

@@ -0,0 +1,25 @@
+import type { LayersAuditPackage } from "#audit/layers/cli-schema";
+import type { AuditCommandPrelude } from "#audit/prepare";
+import { AppError } from "#core/errors";
+import type { Filesystem } from "#core/filesystem/filesystem";
+import type { Result } from "#core/result";
+/**
+ * The shared audit prelude plus the layered packages `audit.layers.packages` names, resolved to their roots.
+ *
+ * @since 0.14.0
+ */
+export type LayersAuditPrelude = AuditCommandPrelude & {
+    readonly packages: ReadonlyArray<LayersAuditPackage>;
+};
+/**
+ * Loads config and resolves every package `audit.layers.packages` names to the root its layers sit under.
+ *
+ * @remarks A configured name no workspace package carries, an entry nested below the root or placed
+ * twice, and a root that does not exist are each reported here, before anything is scanned.
+ *
+ * @since 0.14.0
+ */
+export declare function prepareLayersAudit(fs: Filesystem, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<LayersAuditPrelude, AppError>>;

package/dist/audit/layers/prepare.js

@@ -0,0 +1,66 @@
+import path from "node:path";
+import { invalidLayerEntry } from "#audit/layers/domain/layering";
+import { prepareRepoRootAuditWith } from "#audit/prepare";
+import { AppError, messageFrom } from "#core/errors";
+import { err, ok } from "#core/result";
+import { listWorkspacePackageDirectories } from "#core/workspace/resolver";
+import { packageJsonFileName } from "#core/workspace/well-known-files";
+const DEFAULT_LAYERS_ROOT = "src";
+async function workspacePackageDirectoriesByName(rootDir, fs) {
+    const layout = await listWorkspacePackageDirectories(rootDir, fs, true);
+    const byName = new Map();
+    for (const directory of layout.packageDirectoryPathsAbsolute) {
+        const manifestPath = path.join(directory, packageJsonFileName);
+        if (!fs.existsSync(manifestPath)) {
+            continue;
+        }
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        if (typeof manifest === "object" && manifest !== null && "name" in manifest && typeof manifest.name === "string") {
+            byName.set(manifest.name, directory);
+        }
+    }
+    return byName;
+}
+/**
+ * Loads config and resolves every package `audit.layers.packages` names to the root its layers sit under.
+ *
+ * @remarks A configured name no workspace package carries, an entry nested below the root or placed
+ * twice, and a root that does not exist are each reported here, before anything is scanned.
+ *
+ * @since 0.14.0
+ */
+export async function prepareLayersAudit(fs, args) {
+    return prepareRepoRootAuditWith(fs, args, async (config, rootDir) => {
+        const layersConfig = config.audit?.layers;
+        const allowlist = layersConfig?.allowlist ?? [];
+        const configured = Object.entries(layersConfig?.packages ?? {});
+        if (configured.length === 0) {
+            return ok({ allowlist, packages: [] });
+        }
+        let directoryByName;
+        try {
+            directoryByName = await workspacePackageDirectoriesByName(rootDir, fs);
+        }
+        catch (caughtError) {
+            return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
+        }
+        const packages = [];
+        for (const [name, packageConfig] of configured) {
+            const directory = directoryByName.get(name);
+            if (directory === undefined) {
+                return err(new AppError("VALIDATION_ERROR", `audit.layers.packages["${name}"]: no workspace package has that name`));
+            }
+            const invalid = invalidLayerEntry(packageConfig.layers);
+            if (invalid !== undefined) {
+                return err(new AppError("VALIDATION_ERROR", `audit.layers.packages["${name}"]: ${invalid}`));
+            }
+            const rootPath = path.join(directory, packageConfig.root ?? DEFAULT_LAYERS_ROOT);
+            if (!fs.existsSync(rootPath)) {
+                return err(new AppError("NOT_FOUND", `Not found: ${rootPath}`));
+            }
+            packages.push({ name, rootPath: fs.canonicalPathSync(rootPath), layers: packageConfig.layers });
+        }
+        packages.sort((left, right) => left.name.localeCompare(right.name));
+        return ok({ allowlist, packages });
+    });
+}

package/dist/audit/layers/run.d.ts

@@ -0,0 +1,19 @@
+import type { LayersAuditResult } from "#audit/domain/types";
+import type { LayersAuditPackage } from "#audit/layers/cli-schema";
+import { AppError } from "#core/errors";
+import type { Filesystem } from "#core/filesystem/filesystem";
+import type { Result } from "#core/result";
+/**
+ * Scans every layered package the target reaches for value imports that point up its layers.
+ *
+ * @remarks The target narrows the scan: the repo root reaches every package, a package directory
+ * reaches that package, and a path under a package's root reaches the modules beneath it.
+ *
+ * @since 0.14.0
+ */
+export declare function runLayersAudit(fs: Filesystem, args: {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist: ReadonlyArray<string>;
+    readonly packages: ReadonlyArray<LayersAuditPackage>;
+}): Result<LayersAuditResult, AppError>;

package/dist/audit/layers/run.js

@@ -0,0 +1,62 @@
+import path from "node:path";
+import { auditLayeringSource, LayerMap } from "#audit/layers/domain/layering";
+import { AppError, messageFrom } from "#core/errors";
+import { err, ok } from "#core/result";
+import { walkTsxFiles } from "#core/workspace/typescript-walk";
+/**
+ * Scans every layered package the target reaches for value imports that point up its layers.
+ *
+ * @remarks The target narrows the scan: the repo root reaches every package, a package directory
+ * reaches that package, and a path under a package's root reaches the modules beneath it.
+ *
+ * @since 0.14.0
+ */
+export function runLayersAudit(fs, args) {
+    try {
+        const allowlist = new Set(args.allowlist);
+        const files = [];
+        let violationCount = 0;
+        let allowlistedCount = 0;
+        let scannedFileCount = 0;
+        let packageCount = 0;
+        for (const layeredPackage of args.packages) {
+            const targetInsideRoot = isWithin(layeredPackage.rootPath, args.targetPath);
+            if (!targetInsideRoot && !isWithin(args.targetPath, layeredPackage.rootPath)) {
+                continue;
+            }
+            packageCount++;
+            const layers = new LayerMap(layeredPackage.layers);
+            const scanRoot = targetInsideRoot ? args.targetPath : layeredPackage.rootPath;
+            const filesToScan = fs.statSync(scanRoot).isFile() ? [scanRoot] : walkTsxFiles(scanRoot, fs);
+            for (const absolutePath of filesToScan) {
+                scannedFileCount++;
+                const relativePath = toPosixPath(path.relative(args.rootDir, absolutePath));
+                const modulePath = toPosixPath(path.relative(layeredPackage.rootPath, absolutePath));
+                const content = fs.readFileSync(absolutePath, "utf8");
+                const remaining = auditLayeringSource(absolutePath, modulePath, content, layers).filter(({ raw }) => {
+                    const isAllowed = allowlist.has(raw) || allowlist.has(`${relativePath}:${raw}`);
+                    if (isAllowed) {
+                        allowlistedCount++;
+                    }
+                    return !isAllowed;
+                });
+                if (remaining.length === 0) {
+                    continue;
+                }
+                violationCount += remaining.length;
+                files.push({ relativePath, violations: remaining });
+            }
+        }
+        return ok({ files, violationCount, allowlistedCount, scannedFileCount, packageCount });
+    }
+    catch (caughtError) {
+        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
+    }
+}
+function isWithin(parentPath, childPath) {
+    const relative = path.relative(parentPath, childPath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function toPosixPath(filePath) {
+    return filePath.split(path.sep).join("/");
+}

package/dist/audit/prepare.d.ts

@@ -28,4 +28,16 @@ export declare function resolveRepoRelativePath(rootDir: string, maybeRelative:
 export declare function prepareRepoRootAudit(fs: Filesystem, args: {
     readonly currentWorkingDirectory: string;
     readonly rawTarget: string | undefined;
-}, selectAllowlist: (config: CodefastConfig) => ReadonlyArray<string>): Promise<Result<AuditCommandPrelude, AppError>>;
+}, selectAllowlist: (config: CodefastConfig) => ReadonlyArray<string>): Promise<Result<AuditCommandPrelude, AppError>>;
+/**
+ * Loads config and resolves the repo root as the scan target, taking whatever the caller selects from the config.
+ *
+ * @remarks The selection runs with the root resolved, so it may read the workspace and refuse a
+ * config that names what the workspace does not hold, before anything is scanned.
+ *
+ * @since 0.14.0
+ */
+export declare function prepareRepoRootAuditWith<Selected extends Pick<AuditCommandPrelude, "allowlist">>(fs: Filesystem, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}, select: (config: CodefastConfig, rootDir: string) => Promise<Result<Selected, AppError>>): Promise<Result<Omit<AuditCommandPrelude, "allowlist"> & Selected, AppError>>;

package/dist/audit/prepare.js

@@ -19,6 +19,17 @@ export function resolveRepoRelativePath(rootDir, maybeRelative) {
  * @since 0.11.0
  */
 export async function prepareRepoRootAudit(fs, args, selectAllowlist) {
+    return prepareRepoRootAuditWith(fs, args, (config) => Promise.resolve(ok({ allowlist: selectAllowlist(config) })));
+}
+/**
+ * Loads config and resolves the repo root as the scan target, taking whatever the caller selects from the config.
+ *
+ * @remarks The selection runs with the root resolved, so it may read the workspace and refuse a
+ * config that names what the workspace does not hold, before anything is scanned.
+ *
+ * @since 0.14.0
+ */
+export async function prepareRepoRootAuditWith(fs, args, select) {
     let rootDir;
     try {
         rootDir = fs.canonicalPathSync(resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir);
@@ -34,9 +45,13 @@ export async function prepareRepoRootAudit(fs, args, selectAllowlist) {
     if (!fs.existsSync(targetPath)) {
         return err(new AppError("NOT_FOUND", `Not found: ${targetPath}`));
     }
+    const selected = await select(loadedOutcome.value.config, rootDir);
+    if (!selected.ok) {
+        return selected;
+    }
     return ok({
         rootDir,
         targetPath: fs.canonicalPathSync(targetPath),
-        allowlist: selectAllowlist(loadedOutcome.value.config),
+        ...selected.value,
     });
 }

package/dist/core/config/schema.d.ts

@@ -62,6 +62,17 @@ export interface CodefastArrangeConfig {
 interface CodefastAuditAllowlistConfig {
     allowlist?: Array<string> | undefined;
 }
+/** One package's layering: `layers` bottom to top, each naming the directories and module files it holds under `root`. */
+interface CodefastAuditLayersPackageConfig {
+    /** The directory the layers sit under, relative to the package directory. Defaults to `src`. */
+    root?: string | undefined;
+    layers: Array<Array<string>>;
+}
+/** The `audit layers` defaults: the layered packages by name, and the entries to ignore. */
+interface CodefastAuditLayersConfig {
+    packages?: Record<string, CodefastAuditLayersPackageConfig> | undefined;
+    allowlist?: Array<string> | undefined;
+}
 /** Per-audit defaults grouped under `audit`; the scan always starts at the repo root. */
 interface CodefastAuditConfig {
     rtl?: {
@@ -73,10 +84,7 @@ interface CodefastAuditConfig {
     imports?: CodefastAuditAllowlistConfig | undefined;
     assertions?: CodefastAuditAllowlistConfig | undefined;
     displayNames?: CodefastAuditAllowlistConfig | undefined;
-    constants?: {
-        target?: string | undefined;
-        allowlist?: Array<string> | undefined;
-    } | undefined;
+    layers?: CodefastAuditLayersConfig | undefined;
 }
 /**
  * The validated root `codefast.config` shape.

package/dist/core/config/schema.js

@@ -52,6 +52,18 @@ const codefastAuditAllowlistConfigSchema = z
     allowlist: z.array(z.string()).optional(),
 })
     .strict();
+const codefastAuditLayersPackageConfigSchema = z
+    .object({
+    root: z.string().min(1).optional(),
+    layers: z.array(z.array(z.string().min(1)).min(1)).min(1),
+})
+    .strict();
+const codefastAuditLayersConfigSchema = z
+    .object({
+    packages: z.record(z.string(), codefastAuditLayersPackageConfigSchema).optional(),
+    allowlist: z.array(z.string()).optional(),
+})
+    .strict();
 const codefastAuditConfigSchema = z
     .object({
     rtl: codefastAuditRtlConfigSchema.optional(),
@@ -60,7 +72,7 @@ const codefastAuditConfigSchema = z
     imports: codefastAuditAllowlistConfigSchema.optional(),
     assertions: codefastAuditAllowlistConfigSchema.optional(),
     displayNames: codefastAuditAllowlistConfigSchema.optional(),
-    constants: codefastAuditRtlConfigSchema.optional(),
+    layers: codefastAuditLayersConfigSchema.optional(),
 })
     .strict();
 /**

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

@@ -2,6 +2,9 @@ import type { TagResult } from "#tag/domain/types";
 /**
  * Maps a tag run's result to the process exit code.
  *
+ * @remarks A blocked declaration fails the run: once its release ships unstamped, the only stamp a
+ * later run can add names a version that did not introduce it.
+ *
  * @since 0.3.16-canary.0
  */
 export declare function exitCodeForTagResult(result: TagResult): number;

package/dist/tag/cli-result.js

@@ -2,6 +2,9 @@ import { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_SUCCESS } from "#core/exit-codes";
 /**
  * Maps a tag run's result to the process exit code.
  *
+ * @remarks A blocked declaration fails the run: once its release ships unstamped, the only stamp a
+ * later run can add names a version that did not introduce it.
+ *
  * @since 0.3.16-canary.0
  */
 export function exitCodeForTagResult(result) {
@@ -9,7 +12,10 @@ export function exitCodeForTagResult(result) {
         return CLI_EXIT_GENERAL_ERROR;
     }
     const hasRunErrors = result.targetResults.some((targetResult) => targetResult.runError !== null);
-    return hasRunErrors || result.hookError !== null ? CLI_EXIT_GENERAL_ERROR : CLI_EXIT_SUCCESS;
+    const hasBlockedDeclarations = result.blockedDeclarations.length > 0;
+    return hasRunErrors || hasBlockedDeclarations || result.hookError !== null
+        ? CLI_EXIT_GENERAL_ERROR
+        : CLI_EXIT_SUCCESS;
 }
 /**
  * Serializes a tag run's result as the `--json` output string.
@@ -19,7 +25,7 @@ export function exitCodeForTagResult(result) {
 export function formatTagJsonOutput(result, rootDir) {
     return JSON.stringify({
         schemaVersion: 1,
-        ok: result.hookError === null,
+        ok: exitCodeForTagResult(result) === CLI_EXIT_SUCCESS,
         cwd: rootDir,
         result,
     });

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

@@ -1,4 +1,17 @@
 import type { CodefastConfig } from "#core/config/schema";
+/**
+ * An exported declaration left unstamped because it has no doc block and a `//` comment holds the line above it.
+ *
+ * @remarks A block written there would stack under a note or split a directive from the code it governs, so the
+ * writer leaves the whole file as it is until a person writes that doc block.
+ *
+ * @since 0.14.0
+ */
+export type TagBlockedDeclaration = {
+    filePath: string;
+    line: number;
+    name: string;
+};
 /**
  * Per-file outcome of a tag run.
  *
@@ -7,6 +20,7 @@ import type { CodefastConfig } from "#core/config/schema";
 export type TagFileResult = {
     filePath: string;
     taggedDeclarations: number;
+    blockedDeclarations: Array<TagBlockedDeclaration>;
     changed: boolean;
 };
 /**
@@ -93,6 +107,7 @@ export type TagResult = {
     filesScanned: number;
     filesChanged: number;
     taggedDeclarations: number;
+    blockedDeclarations: Array<TagBlockedDeclaration>;
     versionSummary: string;
     distinctVersions: Array<string>;
     modifiedFiles: Array<string>;

package/dist/tag/output.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { logger } from "#core/logger";
 /**
  * A progress listener that prints a line as each tag target starts and completes.
@@ -37,7 +38,7 @@ export function presentTagResult(result, rootDir) {
         logger.err("No packages found in workspace. Check your pnpm-workspace.yaml or provide an explicit target path.");
         return;
     }
-    const warningsAndErrorsSection = formatWarningsAndErrors(result);
+    const warningsAndErrorsSection = formatWarningsAndErrors(result, rootDir);
     if (warningsAndErrorsSection) {
         logger.err(warningsAndErrorsSection);
     }
@@ -46,13 +47,16 @@ export function presentTagResult(result, rootDir) {
 function withColorizedLine(line, colorCode) {
     return `${colorCode}${line}${colorReset}`;
 }
-function warningsAndErrorsFromResult(result) {
+function warningsAndErrorsFromResult(result, rootDir) {
     const entries = [];
     for (const targetResult of result.targetResults) {
         if (targetResult.runError) {
             entries.push(targetResult.runError);
         }
     }
+    for (const blocked of result.blockedDeclarations) {
+        entries.push(`${path.relative(rootDir, blocked.filePath)}:${blocked.line} \`${blocked.name}\` left unstamped: it has no doc block and a // comment holds the line above it — write the block by hand, then rerun`);
+    }
     if (result.hookError) {
         entries.push(result.hookError);
     }
@@ -72,8 +76,8 @@ function formatTargetTable(targets, rootDir) {
     }
     return lines.join("\n");
 }
-function formatWarningsAndErrors(result) {
-    const entries = warningsAndErrorsFromResult(result);
+function formatWarningsAndErrors(result, rootDir) {
+    const entries = warningsAndErrorsFromResult(result, rootDir);
     if (entries.length === 0) {
         return null;
     }
@@ -89,10 +93,13 @@ function formatSummary(result) {
     const versionSuffix = result.versionSummary === "mixed" && result.distinctVersions.length > 0
         ? ` [${result.distinctVersions.join(", ")}]`
         : "";
-    const hasError = result.targetResults.some((targetResult) => targetResult.runError !== null) || result.hookError !== null;
+    const hasError = result.targetResults.some((targetResult) => targetResult.runError !== null) ||
+        result.blockedDeclarations.length > 0 ||
+        result.hookError !== null;
     const summaryColor = hasError ? colors.red : isDryRun ? colors.yellow : colors.green;
+    const blockedSuffix = result.blockedDeclarations.length > 0 ? ` blocked=${result.blockedDeclarations.length}` : "";
     const lines = [
-        withColorizedLine(`${summaryPrefix} version=${result.versionSummary}${versionSuffix} files=${result.filesChanged}/${result.filesScanned} declarations=${result.taggedDeclarations}`, summaryColor),
+        withColorizedLine(`${summaryPrefix} version=${result.versionSummary}${versionSuffix} files=${result.filesChanged}/${result.filesScanned} declarations=${result.taggedDeclarations}${blockedSuffix}`, summaryColor),
     ];
     if (result.skippedPackages.length > 0) {
         lines.push(`[tag] Skipped: ${result.skippedPackages.length} package(s)`);

package/dist/tag/run.js

@@ -33,6 +33,7 @@ export async function runTag(fs, input) {
             taggedDeclarations += runResult.taggedDeclarations;
         }
         const modifiedFiles = allFileResults.filter((entry) => entry.changed).map((entry) => entry.filePath);
+        const blockedDeclarations = allFileResults.flatMap((entry) => entry.blockedDeclarations);
         const hookError = input.write && modifiedFiles.length > 0
             ? await runTagOnAfterWriteHook(tagConfig?.onAfterWrite, modifiedFiles)
             : null;
@@ -46,6 +47,7 @@ export async function runTag(fs, input) {
             filesScanned,
             filesChanged,
             taggedDeclarations,
+            blockedDeclarations,
             versionSummary: summarizeVersions(versionsSet),
             distinctVersions,
             modifiedFiles,