@codefast/cli 0.13.0 → 0.14.0

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,12 +1,15 @@
 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",
@@ -19,6 +22,14 @@ function identifierName(node) {
     }
     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.
  *
@@ -36,20 +47,34 @@ export class TagSinceWriter {
         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,
         };
     }
     /**
@@ -211,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codefast/cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Developer CLI for the Codefast monorepo (arrange, audit, mirror, pack-slim, tag)",
   "keywords": [
     "cli",

package/dist/audit/constants/cli-result.d.ts

@@ -1,13 +0,0 @@
-import type { ConstantAuditResult } from "#audit/domain/types";
-/**
- * Exit `1` when any non-allowlisted numeric constant is unlabelled.
- *
- * @since 0.11.0
- */
-export declare function exitCodeForConstantAuditResult(result: ConstantAuditResult): number;
-/**
- * Machine-readable numeric-constant summary for `--json`.
- *
- * @since 0.11.0
- */
-export declare function formatConstantAuditJsonOutput(result: ConstantAuditResult, rootDir: string): string;

package/dist/audit/constants/cli-schema.d.ts

@@ -1,18 +0,0 @@
-import * as z from "zod";
-/**
- * Resolved request for a single numeric-constant audit run.
- *
- * @since 0.11.0
- */
-export type ConstantAuditRunRequest = {
-    readonly rootDir: string;
-    readonly targetPath: string;
-    readonly allowlist?: ReadonlyArray<string> | undefined;
-    readonly json: boolean;
-};
-/**
- * Zod schema for {@link ConstantAuditRunRequest}.
- *
- * @since 0.11.0
- */
-export declare const constantAuditRunRequestSchema: z.ZodType<ConstantAuditRunRequest>;

package/dist/audit/constants/cli-schema.js

@@ -1,12 +0,0 @@
-import * as z from "zod";
-/**
- * Zod schema for {@link ConstantAuditRunRequest}.
- *
- * @since 0.11.0
- */
-export const constantAuditRunRequestSchema = z.object({
-    rootDir: z.string().min(1),
-    targetPath: z.string().min(1),
-    allowlist: z.array(z.string()).optional(),
-    json: z.boolean(),
-});

package/dist/audit/constants/domain/constants.d.ts

@@ -1,8 +0,0 @@
-/** The numeric-constant convention: a `const NAME = <number>` in a source tree names the kind of number it is. */
-import type { ConstantViolation } from "#audit/domain/types";
-/**
- * Scans one TypeScript source for numeric constants whose comment names none of the three kinds.
- *
- * @since 0.11.0
- */
-export declare function auditNumericConstants(sourceText: string): Array<ConstantViolation>;

package/dist/audit/constants/domain/constants.js

@@ -1,66 +0,0 @@
-/**
- * The three kinds a numeric constant may be, each named by one phrase in the comment above it.
- *
- * @remarks A width of the machine, a value the contract fixes, or a figure derived from the data a
- * bind hands in. A count that merely looks reasonable is none of them, and the audit says so.
- */
-const KIND_PHRASES = [
-    "a constant of the machine",
-    "a value the contract fixes",
-    "derived from bind-time data",
-];
-/** An upper-case `const` bound to a numeric literal, with an optional type annotation. */
-const NUMERIC_CONST = /^\s*(?:export\s+)?const\s+([A-Z][A-Z0-9_]*)\s*(?::[^=]+)?=\s*(-?\d[\d_]*(?:\.\d+)?)(?![\w.])/;
-/** Values that stand for absence or identity, never for a tuned size: any distinct value would do. */
-const SENTINEL_VALUES = new Set(["0", "1", "-1"]);
-/**
- * Scans one TypeScript source for numeric constants whose comment names none of the three kinds.
- *
- * @since 0.11.0
- */
-export function auditNumericConstants(sourceText) {
-    const lines = sourceText.split("\n");
-    const violations = [];
-    for (let index = 0; index < lines.length; index += 1) {
-        const match = NUMERIC_CONST.exec(lines[index]);
-        if (match === null || SENTINEL_VALUES.has(match[2])) {
-            continue;
-        }
-        const comment = commentAbove(lines, index);
-        if (KIND_PHRASES.some((phrase) => comment.includes(phrase))) {
-            continue;
-        }
-        violations.push({
-            line: index + 1,
-            raw: `${match[1]} = ${match[2]}`,
-            reason: `no kind named above it — say which it is: ${KIND_PHRASES.join(" · ")}`,
-        });
-    }
-    return violations;
-}
-/** The doc block or run of `//` lines directly above a line, as one text; empty when there is none. */
-function commentAbove(lines, index) {
-    let cursor = index - 1;
-    const gathered = [];
-    while (cursor >= 0) {
-        const line = lines[cursor].trim();
-        if (line.startsWith("//")) {
-            gathered.unshift(line);
-            cursor -= 1;
-            continue;
-        }
-        if (line.endsWith("*/")) {
-            // Walk back to the opening of the block, collecting it whole.
-            while (cursor >= 0) {
-                gathered.unshift(lines[cursor].trim());
-                if (lines[cursor].trim().startsWith("/*")) {
-                    break;
-                }
-                cursor -= 1;
-            }
-            break;
-        }
-        break;
-    }
-    return gathered.join(" ");
-}

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

@@ -1,7 +0,0 @@
-import type { ConstantAuditResult } from "#audit/domain/types";
-/**
- * Human-readable numeric-constant report.
- *
- * @since 0.11.0
- */
-export declare function presentConstantAuditResult(result: ConstantAuditResult): void;

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

@@ -1,16 +0,0 @@
-import type { AuditCommandPrelude } from "#audit/prepare";
-import { AppError } from "#core/errors";
-import type { Filesystem } from "#core/filesystem/filesystem";
-import type { Result } from "#core/result";
-/**
- * Loads config and resolves the scan target for `audit constants`.
- *
- * @remarks The target is the library tree the convention holds over, from `audit.constants.target`
- * unless the command names one.
- *
- * @since 0.11.0
- */
-export declare function prepareConstantAudit(fs: Filesystem, args: {
-    readonly currentWorkingDirectory: string;
-    readonly rawTarget: string | undefined;
-}): Promise<Result<AuditCommandPrelude, AppError>>;

package/dist/audit/constants/prepare.js

@@ -1,37 +0,0 @@
-import { resolveRepoRelativePath } from "#audit/prepare";
-import { loadCodefastConfig } from "#core/config";
-import { AppError, messageFrom } from "#core/errors";
-import { err, ok } from "#core/result";
-import { resolveProjectRoot } from "#core/workspace/resolver";
-/**
- * Loads config and resolves the scan target for `audit constants`.
- *
- * @remarks The target is the library tree the convention holds over, from `audit.constants.target`
- * unless the command names one.
- *
- * @since 0.11.0
- */
-export async function prepareConstantAudit(fs, args) {
-    let rootDir;
-    try {
-        rootDir = fs.canonicalPathSync(resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir);
-    }
-    catch (caughtError) {
-        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
-    }
-    const loadedOutcome = await loadCodefastConfig(rootDir, fs);
-    if (!loadedOutcome.ok) {
-        return loadedOutcome;
-    }
-    const { config } = loadedOutcome.value;
-    const constantsConfig = config.audit?.constants ?? {};
-    const resolvedTargetInput = args.rawTarget ?? constantsConfig.target;
-    if (resolvedTargetInput === undefined) {
-        return err(new AppError("VALIDATION_ERROR", "audit constants needs a target: pass one, or set audit.constants.target in codefast.config"));
-    }
-    const targetPath = resolveRepoRelativePath(args.rawTarget !== undefined ? args.currentWorkingDirectory : rootDir, resolvedTargetInput);
-    if (!fs.existsSync(targetPath)) {
-        return err(new AppError("NOT_FOUND", `Not found: ${targetPath}`));
-    }
-    return ok({ rootDir, targetPath: fs.canonicalPathSync(targetPath), allowlist: constantsConfig.allowlist ?? [] });
-}

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

@@ -1,14 +0,0 @@
-import type { ConstantAuditResult } from "#audit/domain/types";
-import { AppError } from "#core/errors";
-import type { Filesystem } from "#core/filesystem/filesystem";
-import type { Result } from "#core/result";
-/**
- * Scans a target path's library sources for numeric constants that name none of the three kinds.
- *
- * @since 0.11.0
- */
-export declare function runConstantAudit(fs: Filesystem, args: {
-    readonly rootDir: string;
-    readonly targetPath: string;
-    readonly allowlist: ReadonlyArray<string>;
-}): Result<ConstantAuditResult, AppError>;

package/dist/audit/constants/run.js

@@ -1,64 +0,0 @@
-import path from "node:path";
-import { auditNumericConstants } from "#audit/constants/domain/constants";
-import { AppError, messageFrom } from "#core/errors";
-import { err, ok } from "#core/result";
-import { walkTsxFiles } from "#core/workspace/typescript-walk";
-/**
- * Trees the convention does not reach: a test fixes a value to observe it, a benchmark sizes a
- * workload, and an app or example is a consumer, not the library.
- */
-const SKIPPED_SEGMENTS = new Set([
-    "tests",
-    "benchmarks",
-    "apps",
-    "examples",
-    "node_modules",
-    "dist",
-]);
-/**
- * Scans a target path's library sources for numeric constants that name none of the three kinds.
- *
- * @since 0.11.0
- */
-export function runConstantAudit(fs, args) {
-    try {
-        const allowlist = new Set(args.allowlist);
-        const { rootDir, targetPath } = args;
-        const filesToScan = collectScanPaths(fs, rootDir, targetPath);
-        const files = [];
-        let violationCount = 0;
-        let allowlistedCount = 0;
-        for (const absolutePath of filesToScan) {
-            const relativePath = toPosixPath(path.relative(rootDir, absolutePath));
-            const content = fs.readFileSync(absolutePath, "utf8");
-            const remaining = auditNumericConstants(content).filter(({ raw }) => {
-                const name = raw.split(" ")[0];
-                const isAllowed = allowlist.has(name) || allowlist.has(`${relativePath}:${name}`);
-                if (isAllowed) {
-                    allowlistedCount++;
-                }
-                return !isAllowed;
-            });
-            if (remaining.length === 0) {
-                continue;
-            }
-            violationCount += remaining.length;
-            files.push({ relativePath, violations: remaining });
-        }
-        return ok({ files, violationCount, allowlistedCount, scannedFileCount: filesToScan.length });
-    }
-    catch (error) {
-        return err(new AppError("INFRA_FAILURE", messageFrom(error), error));
-    }
-}
-/** The `.ts` files under a `src` directory of a library package, below the target. */
-function collectScanPaths(fs, rootDir, targetPath) {
-    const candidates = fs.statSync(targetPath).isDirectory() ? walkTsxFiles(targetPath, fs) : [targetPath];
-    return candidates.filter((absolutePath) => {
-        const segments = toPosixPath(path.relative(rootDir, absolutePath)).split("/");
-        return segments.includes("src") && !segments.some((segment) => SKIPPED_SEGMENTS.has(segment));
-    });
-}
-function toPosixPath(filePath) {
-    return filePath.split(path.sep).join("/");
-}