@codefast/cli 0.12.0 → 0.14.0

package/dist/audit/publish/run.js

@@ -1,5 +1,7 @@
 import path from "node:path";
 import { scanLegacySubpathImports } from "#audit/publish/domain/legacy-subpath";
+import { missesShippedFiles, scanStylesheetSources } from "#audit/publish/domain/stylesheet-sources";
+import { listShippedFiles } from "#audit/publish/shipped-files";
 import { AppError, messageFrom } from "#core/errors";
 import { err, ok } from "#core/result";
 import { listWorkspacePackageDirectories } from "#core/workspace/resolver";
@@ -8,7 +10,8 @@ import { packageJsonFileName } from "#core/workspace/well-known-files";
 import { unshippedPublishTargets } from "#pack-slim/domain/transform";
 /**
  * Reports what would break a consumer's install: a `#/`-prefixed import Node's ESM resolver rejects on
- * the floor, and an `exports`/`imports` target the slimmed publish manifest does not ship.
+ * the floor, an `exports`/`imports` target the slimmed publish manifest does not ship, and a shipped
+ * stylesheet whose `@source` paths reach none of the files that do ship.
  *
  * @since 0.12.0
  */
@@ -29,6 +32,7 @@ export async function runPublishAudit(fs, args) {
         }
         const layout = await listWorkspacePackageDirectories(rootDir, fs, true);
         const unshipped = [];
+        const unreachableStylesheets = [];
         let packageCount = 0;
         for (const packageDir of layout.packageDirectoryPathsAbsolute) {
             const manifestPath = path.join(packageDir, packageJsonFileName);
@@ -44,10 +48,14 @@ export async function runPublishAudit(fs, args) {
             for (const target of unshippedPublishTargets(manifest)) {
                 unshipped.push({ packageName, field: target.field, subpath: target.subpath, target: target.target });
             }
+            for (const violation of unreachableStylesheetsOf(fs, { rootDir, packageDir, manifest })) {
+                unreachableStylesheets.push({ packageName, ...violation });
+            }
         }
         return ok({
             legacyImportFiles,
             unshipped,
+            unreachableStylesheets,
             legacyImportCount,
             scannedFileCount: sourceFiles.length,
             packageCount,
@@ -57,6 +65,27 @@ export async function runPublishAudit(fs, args) {
         return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
     }
 }
+// The shipped stylesheets whose `@source` paths register nothing the tarball ships — what a consumer's Tailwind scans.
+function unreachableStylesheetsOf(fs, args) {
+    const { rootDir, packageDir, manifest } = args;
+    const shipped = listShippedFiles(fs, packageDir, manifest);
+    if (shipped === null) {
+        return [];
+    }
+    const violations = [];
+    for (const stylesheet of shipped.files.filter((file) => file.endsWith(".css"))) {
+        const stylesheetPath = path.join(packageDir, stylesheet);
+        const sources = scanStylesheetSources(fs.readFileSync(stylesheetPath, "utf8"));
+        if (sources.length > 0 && missesShippedFiles(stylesheet, sources, shipped.files)) {
+            violations.push({
+                stylesheet: toPosixPath(path.relative(rootDir, stylesheetPath)),
+                sources,
+                missingFilesEntries: shipped.missingEntries,
+            });
+        }
+    }
+    return violations;
+}
 function toPosixPath(filePath) {
     return filePath.split(path.sep).join("/");
 }

package/dist/audit/publish/shipped-files.d.ts

@@ -0,0 +1,21 @@
+/** Lists the files a package's slimmed tarball ships, read from disk. */
+import type { Filesystem } from "#core/filesystem/filesystem";
+/**
+ * What a package's tarball ships, plus the `files` entries that match nothing on disk.
+ *
+ * @since 0.13.0
+ */
+export interface ShippedFiles {
+    /** Package-relative POSIX paths, sorted. */
+    readonly files: Array<string>;
+    readonly missingEntries: Array<string>;
+}
+/**
+ * Lists the files a package ships once the publish step has slimmed it, or `null` with no `files` field to go by.
+ *
+ * @remarks Applies the same slim as `pack-slim`, so a subtree it drops is absent here too, and leaves out source maps,
+ * which the publish step deletes. Without a `files` field npm ships the whole directory, which leaves nothing to judge.
+ *
+ * @since 0.13.0
+ */
+export declare function listShippedFiles(fs: Filesystem, packageDir: string, manifest: Record<string, unknown>): ShippedFiles | null;

package/dist/audit/publish/shipped-files.js

@@ -0,0 +1,36 @@
+/** Lists the files a package's slimmed tarball ships, read from disk. */
+import path from "node:path";
+import { isSourceMapFile, slimPublishManifest } from "#pack-slim/domain/transform";
+/**
+ * Lists the files a package ships once the publish step has slimmed it, or `null` with no `files` field to go by.
+ *
+ * @remarks Applies the same slim as `pack-slim`, so a subtree it drops is absent here too, and leaves out source maps,
+ * which the publish step deletes. Without a `files` field npm ships the whole directory, which leaves nothing to judge.
+ *
+ * @since 0.13.0
+ */
+export function listShippedFiles(fs, packageDir, manifest) {
+    const { manifest: slimmed } = slimPublishManifest(manifest);
+    if (!Array.isArray(slimmed.files)) {
+        return null;
+    }
+    const files = new Set();
+    const missingEntries = [];
+    for (const entry of slimmed.files) {
+        if (typeof entry !== "string" || entry.startsWith("!")) {
+            continue;
+        }
+        // An entry names a file, a directory whose whole subtree ships, or a glob.
+        const matches = [...fs.globSync(entry, { cwd: packageDir }), ...fs.globSync(`${entry}/**`, { cwd: packageDir })];
+        if (matches.length === 0) {
+            missingEntries.push(entry);
+            continue;
+        }
+        for (const match of matches) {
+            if (fs.statSync(path.join(packageDir, match)).isFile()) {
+                files.add(match.split(path.sep).join("/"));
+            }
+        }
+    }
+    return { files: [...files].filter((file) => !isSourceMapFile(file)).sort(), missingEntries };
+}

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?: {
@@ -71,7 +82,9 @@ interface CodefastAuditConfig {
     links?: CodefastAuditAllowlistConfig | undefined;
     comments?: CodefastAuditAllowlistConfig | undefined;
     imports?: CodefastAuditAllowlistConfig | undefined;
+    assertions?: CodefastAuditAllowlistConfig | undefined;
     displayNames?: CodefastAuditAllowlistConfig | undefined;
+    layers?: CodefastAuditLayersConfig | undefined;
 }
 /**
  * The validated root `codefast.config` shape.

package/dist/core/config/schema.js

@@ -52,13 +52,27 @@ 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(),
     links: codefastAuditAllowlistConfigSchema.optional(),
     comments: codefastAuditAllowlistConfigSchema.optional(),
     imports: codefastAuditAllowlistConfigSchema.optional(),
+    assertions: codefastAuditAllowlistConfigSchema.optional(),
     displayNames: codefastAuditAllowlistConfigSchema.optional(),
+    layers: codefastAuditLayersConfigSchema.optional(),
 })
     .strict();
 /**

package/dist/core/filesystem/filesystem.d.ts

@@ -32,10 +32,9 @@ export interface Filesystem {
     readdirSync(filePath: string): Array<string>;
     readFile(filePath: string, encoding: CliFileEncoding): Promise<string>;
     writeFile(filePath: string, data: string, encoding: CliFileEncoding): Promise<void>;
-    readdir(filePath: string, options?: {
-        recursive?: boolean;
-        withFileTypes?: boolean;
-    }): Promise<Array<string> | Array<DirectoryEntry>>;
+    readdirEntries(filePath: string, options?: {
+        readonly recursive?: boolean | undefined;
+    }): Promise<Array<DirectoryEntry>>;
     globSync(pattern: string, options: {
         readonly cwd: string;
     }): Array<string>;

package/dist/core/filesystem/node.js

@@ -22,13 +22,7 @@ export const nodeFilesystem = {
     },
     readFile: (filePath, enc) => fsPromises.readFile(filePath, enc),
     writeFile: (filePath, data, enc) => fsPromises.writeFile(filePath, data, enc),
-    readdir: async (filePath, opts) => {
-        const raw = await fsPromises.readdir(filePath, opts);
-        if (!opts?.withFileTypes) {
-            return raw;
-        }
-        return raw;
-    },
+    readdirEntries: (filePath, options) => fsPromises.readdir(filePath, { recursive: options?.recursive ?? false, withFileTypes: true }),
     globSync: (pattern, options) => fsSync.globSync(pattern, options),
     rename: (oldPath, newPath) => fsPromises.rename(oldPath, newPath),
     unlink: (filePath) => fsPromises.unlink(filePath),

package/dist/core/oxc-node.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The structural view every module that walks `oxc-parser`'s ESTree output reads nodes through.
+ */
+/**
+ * An oxc ESTree node: a `type` discriminant, UTF-16 `start`/`end` offsets, and fields read by name.
+ *
+ * @remarks Structural on purpose: the walkers match node shapes by `type` and read the few fields
+ * they need, so the parser's full node union never has to be spelled out.
+ *
+ * @since 0.13.0
+ */
+export interface OxcNode {
+    readonly type: string;
+    readonly start: number;
+    readonly end: number;
+    readonly [key: string]: unknown;
+}
+/**
+ * Returns whether a value is an ESTree node rather than a scalar, a list or a location record.
+ *
+ * @since 0.13.0
+ */
+export declare function isOxcNode(value: unknown): value is OxcNode;
+/**
+ * Returns a parsed program's top-level statements.
+ *
+ * @remarks Takes `parseSync(...).program` as it comes, so no caller asserts the parser's type onto
+ * the structural view.
+ *
+ * @since 0.13.0
+ */
+export declare function programStatements(program: unknown): ReadonlyArray<OxcNode>;

package/dist/core/oxc-node.js

@@ -0,0 +1,25 @@
+/**
+ * The structural view every module that walks `oxc-parser`'s ESTree output reads nodes through.
+ */
+/**
+ * Returns whether a value is an ESTree node rather than a scalar, a list or a location record.
+ *
+ * @since 0.13.0
+ */
+export function isOxcNode(value) {
+    return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
+}
+/**
+ * Returns a parsed program's top-level statements.
+ *
+ * @remarks Takes `parseSync(...).program` as it comes, so no caller asserts the parser's type onto
+ * the structural view.
+ *
+ * @since 0.13.0
+ */
+export function programStatements(program) {
+    if (!isOxcNode(program) || !Array.isArray(program.body)) {
+        return [];
+    }
+    return program.body.filter(isOxcNode);
+}

package/dist/core/source-position.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Where an offset sits in a source text, as the audits report it.
+ */
+/**
+ * Returns the one-based line an offset falls on.
+ *
+ * @since 0.13.0
+ */
+export declare function lineOfOffset(sourceText: string, offset: number): number;
+/**
+ * Returns a text up to its first line break, so a multi-line node reports as one line.
+ *
+ * @since 0.13.0
+ */
+export declare function firstLineOf(text: string): string;

package/dist/core/source-position.js

@@ -0,0 +1,26 @@
+/**
+ * Where an offset sits in a source text, as the audits report it.
+ */
+/**
+ * Returns the one-based line an offset falls on.
+ *
+ * @since 0.13.0
+ */
+export function lineOfOffset(sourceText, offset) {
+    let line = 1;
+    for (let index = 0; index < offset; index++) {
+        if (sourceText.charCodeAt(index) === 10) {
+            line++;
+        }
+    }
+    return line;
+}
+/**
+ * Returns a text up to its first line break, so a multi-line node reports as one line.
+ *
+ * @since 0.13.0
+ */
+export function firstLineOf(text) {
+    const newlineIndex = text.indexOf("\n");
+    return newlineIndex === -1 ? text : text.slice(0, newlineIndex);
+}

package/dist/mirror/dist-filesystem-node.js

@@ -1,5 +1,4 @@
 import path from "node:path";
-import { isDirentList } from "#mirror/domain/dirent-guard";
 import { normalizePath } from "#mirror/domain/path-normalizer";
 /**
  * Creates the `DistFilesystem` the mirror scan uses, backed by a `Filesystem`.
@@ -10,11 +9,8 @@ export function createMirrorDistFilesystem(fs) {
     return {
         async listRelativeFilesRecursively(dirPath) {
             try {
-                const raw = await fs.readdir(dirPath, { recursive: true, withFileTypes: true });
-                if (!isDirentList(raw)) {
-                    return [];
-                }
-                return raw
+                const entries = await fs.readdirEntries(dirPath, { recursive: true });
+                return entries
                     .filter((dirent) => dirent.isFile())
                     .map((dirent) => {
                     const fullPath = path.join(dirent.parentPath, dirent.name);
@@ -31,14 +27,8 @@ export function createMirrorDistFilesystem(fs) {
         },
         async isDirectoryCssOnly(distDir, dirPath) {
             try {
-                const raw = await fs.readdir(path.join(distDir, dirPath), { withFileTypes: true });
-                if (!isDirentList(raw)) {
-                    return false;
-                }
-                if (raw.length === 0) {
-                    return true;
-                }
-                return raw.every((dirent) => dirent.isFile() && dirent.name.endsWith(".css"));
+                const entries = await fs.readdirEntries(path.join(distDir, dirPath));
+                return entries.every((dirent) => dirent.isFile() && dirent.name.endsWith(".css"));
             }
             catch {
                 return false;

package/dist/pack-slim/run.js

@@ -115,7 +115,7 @@ async function pruneDist(fs, distDir, write, pkgStats) {
     if (!fs.existsSync(distDir)) {
         return;
     }
-    const entries = (await fs.readdir(distDir, { recursive: true, withFileTypes: true }));
+    const entries = await fs.readdirEntries(distDir, { recursive: true });
     for (const entry of entries) {
         if (!entry.isFile()) {
             continue;

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/domain/version-summary.d.ts

@@ -1,10 +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>;
+export declare function extractDistinctVersions(targetResults: ReadonlyArray<{
+    readonly result: {
+        readonly version: string;
+    } | null;
+}>): Set<string>;
 /**
  * Summarizes a set of versions as `"none"`, the single version, or `"mixed"`.
  *

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,

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

@@ -28,5 +28,10 @@ export declare class TagSinceWriter {
     private jsDocHasSinceTag;
     private makeJSDocSinceLine;
     private makeSinceOnlyJSDocBlock;
+    /**
+     * Returns whether the line above `anchor` holds a `//` note, which a fresh block would stack under,
+     * or a directive, which would then govern the block instead of the declaration.
+     */
+    private isDocBlockLineTaken;
     private makeDeclarationSinceLine;
 }

package/dist/tag/writer/since-writer.js

@@ -1,26 +1,35 @@
 import { parseSync } from "oxc-parser";
+import { isDirectiveLine, isNoteLine } from "#audit/comments/domain/comment-content";
+import { isOxcNode, programStatements } from "#core/oxc-node";
+import { lineOfOffset } from "#core/source-position";
 import { applyEditsDescending, indentOfLineContaining } from "#core/source-text-edit";
 /**
- * Top-level statement kinds that carry a `@since` tag: function, class, interface,
- * type alias, enum, and variable declaration.
+ * Top-level statement kinds that carry a `@since` tag. `TSDeclareFunction` is a function with no body —
+ * an overload signature or a `declare function` — which the `.d.ts` keeps with its own doc block.
  */
 const TAGGABLE_DECLARATION_TYPES = new Set([
     "FunctionDeclaration",
+    "TSDeclareFunction",
     "ClassDeclaration",
     "TSInterfaceDeclaration",
     "TSTypeAliasDeclaration",
     "TSEnumDeclaration",
     "VariableDeclaration",
 ]);
-function isOxcNode(value) {
-    return typeof value === "object" && value !== null && typeof value.type === "string";
-}
 function identifierName(node) {
     if (isOxcNode(node) && node.type === "Identifier" && typeof node.name === "string") {
         return node.name;
     }
     return undefined;
 }
+function lineAboveOffset(sourceText, offset) {
+    const lineStart = sourceText.lastIndexOf("\n", offset - 1) + 1;
+    if (lineStart === 0) {
+        return undefined;
+    }
+    const lineAboveStart = lineStart >= 2 ? sourceText.lastIndexOf("\n", lineStart - 2) + 1 : 0;
+    return sourceText.slice(lineAboveStart, lineStart - 1);
+}
 /**
  * The writer that adds missing `@since` tags to a file's exported declarations.
  *
@@ -35,23 +44,37 @@ export class TagSinceWriter {
     applySinceTagsToFile(filePath, version, write) {
         const sourceText = this.fs.readFileSync(filePath, "utf8");
         const { program, comments } = parseSync(filePath, sourceText);
-        const statements = program.body;
+        const statements = programStatements(program);
         const jsDocComments = comments.filter((comment) => comment.type === "Block" && comment.value.startsWith("*"));
         const edits = [];
+        const blockedDeclarations = [];
         for (const declaration of this.collectExportedDeclarations(statements)) {
-            const edit = this.makeDeclarationSinceLine(declaration, jsDocComments, sourceText, version);
+            const existing = this.associatedJsDoc(declaration, jsDocComments, sourceText);
+            if (existing === undefined && this.isDocBlockLineTaken(declaration, sourceText)) {
+                const names = this.taggableDeclarationOf(declaration)?.names ?? [];
+                blockedDeclarations.push({
+                    filePath,
+                    line: lineOfOffset(sourceText, declaration.start),
+                    name: names.length > 0 ? names.join(", ") : "default",
+                });
+                continue;
+            }
+            const edit = this.makeDeclarationSinceLine(declaration, existing, sourceText, version);
             if (edit) {
                 edits.push(edit);
             }
         }
-        if (edits.length > 0 && write) {
-            const updated = applyEditsDescending(sourceText, edits);
+        // A blocked declaration holds its whole file back, so every reported line matches the file on disk.
+        const appliedEdits = blockedDeclarations.length > 0 ? [] : edits;
+        if (appliedEdits.length > 0 && write) {
+            const updated = applyEditsDescending(sourceText, appliedEdits);
             this.fs.writeFileSync(filePath, updated, "utf8");
         }
         return {
             filePath,
-            taggedDeclarations: edits.length,
-            changed: edits.length > 0,
+            taggedDeclarations: appliedEdits.length,
+            blockedDeclarations,
+            changed: appliedEdits.length > 0,
         };
     }
     /**
@@ -213,8 +236,15 @@ export class TagSinceWriter {
         const tag = this.sinceDocumentationTag;
         return `/**\n${declarationIndent} * ${tag} ${version}\n${declarationIndent} */`;
     }
-    makeDeclarationSinceLine(anchor, jsDocComments, sourceText, version) {
-        const existing = this.associatedJsDoc(anchor, jsDocComments, sourceText);
+    /**
+     * Returns whether the line above `anchor` holds a `//` note, which a fresh block would stack under,
+     * or a directive, which would then govern the block instead of the declaration.
+     */
+    isDocBlockLineTaken(anchor, sourceText) {
+        const lineAbove = lineAboveOffset(sourceText, anchor.start);
+        return lineAbove !== undefined && (isNoteLine(lineAbove) || isDirectiveLine(lineAbove));
+    }
+    makeDeclarationSinceLine(anchor, existing, sourceText, version) {
         if (existing) {
             if (this.jsDocHasSinceTag(existing)) {
                 return undefined;