@codefast/cli 0.8.1 → 0.9.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 CodeFast Labs
+Copyright (c) 2024 Codefast Labs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -11,8 +11,8 @@ class strings, `audit` source conventions, `mirror` export maps from `dist/`, `p
 
 `codefast` is the command line for the [codefast monorepo](https://github.com/codefastlabs/codefast). It has five
 commands: `arrange` regroups Tailwind class strings, `audit` checks source conventions, `mirror` writes
-`package.json#exports` from `dist/`, `pack-slim` strips the source lane from the publish artifact, and `tag` stamps
-exported APIs with `@since`.
+`package.json#exports` from `dist/`, `pack-slim` slims the publish artifact down to what a consumer reads, and `tag`
+stamps exported APIs with `@since`.
 
 This is repo tooling, published to npm. It runs in any pnpm workspace with a similar layout, but its flags and defaults
 follow the codefast conventions rather than aiming to be a general-purpose product.
@@ -44,6 +44,7 @@ pnpm run cli:audit:rtl              # codefast audit rtl
 pnpm run cli:audit:links            # codefast audit links
 pnpm run cli:audit:comments         # codefast audit comments
 pnpm run cli:audit:react            # codefast audit react
+pnpm run cli:audit:display-names    # codefast audit display-names
 ```
 
 `pnpm run version-packages` runs `changeset version` and then `codefast tag`, so published APIs are stamped at release.
@@ -135,12 +136,14 @@ Exits `1` when any package fails, `0` otherwise.
 
 ## `pack-slim`
 
-Strips the source lane from published packages so the npm tarball ships `dist` runtime and types only. Where `mirror`
-writes the full exports — including the `source` condition — for repo dev, `pack-slim` removes it for publish: it drops
-`src` from `files`, every `source` condition from `exports`/`imports`, and the `dist` source maps plus their dangling
-`sourceMappingURL` directives. Private packages are skipped, since `changeset publish` never publishes them. It is meant
-to run on an ephemeral CI checkout right before publish (the release workflow runs it as its publish step), so it is
-never committed.
+Slims published packages down to what a consumer's `tsc` and Node read, so the npm tarball ships `dist` runtime and
+types only and its `package.json` describes nothing else. Where `mirror` writes the full exports — including the
+`source` condition — for repo dev, `pack-slim` removes the development lane for publish: it drops `src` from `files`,
+every `source` condition from `exports`/`imports`, every `imports` entry left pointing outside `files` (the `#/tests/*`
+and `#/examples/*` aliases), every script that is not an install or publish lifecycle hook, `devDependencies`, and the
+`dist` source maps plus their dangling `sourceMappingURL` directives. Private packages are skipped, since
+`changeset publish` never publishes them. It is meant to run on an ephemeral CI checkout right before publish (the
+release workflow runs it as its publish step), so it is never committed.
 
 Because its result must never be committed, `pack-slim` refuses to write when the git working tree has uncommitted
 tracked changes — guarding against an accidental local run landing on real work. `--dry-run` is exempt (it writes
@@ -234,7 +237,7 @@ Exits non-zero when violations remain so it can gate CI.
 
 ```bash
 codefast audit react                       # whole repo
-codefast audit react apps/ui/src           # explicit target
+codefast audit react apps/web/src           # explicit target
 codefast audit react --json                # machine-readable summary
 ```
 
@@ -245,6 +248,29 @@ codefast audit react --json                # machine-readable summary
 Configure intentional exceptions via `audit.react.allowlist` — each entry is the offending source text as written or
 `repo/relative/path.tsx:<text>`.
 
+## `audit display-names`
+
+Read-only scan enforcing the display-name convention for every string a `token()`, `tag()` or module factory takes: a
+name is spelled like the TS symbol it stands for, under its owner's namespace — `<namespace>:<Name>`. The namespace is a
+kebab-case package, app or feature slug (or a scoped package name); a token or module name is PascalCase, because it
+stands for a type or a unit of composition; a tag key is camelCase, because it names an attribute. Scans TypeScript and
+markdown alike, since a doc sample is what a reader copies; skips `tests/`, `benchmarks/`, `.changeset/` and
+`CHANGELOG.md`, where a name is scoped by its file or quoted as it was. Exits non-zero when violations remain so it can
+gate CI.
+
+```bash
+codefast audit display-names                      # whole repo
+codefast audit display-names packages/di/examples  # explicit target
+codefast audit display-names --json               # machine-readable summary
+```
+
+| Flag     | Description                       |
+| -------- | --------------------------------- |
+| `--json` | Print one JSON summary on stdout. |
+
+Configure intentional exceptions via `audit.displayNames.allowlist` — each entry is the call as written, through its
+closing quote (or parenthesis when the name is the only argument), or `repo/relative/path.ts:<call>`.
+
 ## `tag`
 
 Adds `@since <version>` tags to the doc comments of exported declarations that lack one, creating the doc block when

package/dist/audit/cli-schema.js

@@ -45,6 +45,17 @@ export const reactAuditRunRequestSchema = z.object({
     allowlist: z.array(z.string()).optional(),
     json: z.boolean(),
 });
+/**
+ * Zod schema for {@link DisplayNameAuditRunRequest}.
+ *
+ * @since 0.9.0
+ */
+export const displayNameAuditRunRequestSchema = z.object({
+    rootDir: z.string().min(1),
+    targetPath: z.string().min(1),
+    allowlist: z.array(z.string()).optional(),
+    json: z.boolean(),
+});
 /**
  * Resolves a path that may be absolute or relative to `rootDir`.
  *

package/dist/audit/command.js

@@ -1,10 +1,11 @@
 import process from "node:process";
 import { Command } from "commander";
-import { commentAuditRunRequestSchema, linkAuditRunRequestSchema, reactAuditRunRequestSchema, rtlAuditRunRequestSchema, } from "#/audit/cli-schema";
-import { exitCodeForCommentAuditResult, exitCodeForLinkAuditResult, exitCodeForReactAuditResult, exitCodeForRtlAuditResult, formatCommentAuditJsonOutput, formatLinkAuditJsonOutput, formatReactAuditJsonOutput, formatRtlAuditJsonOutput, presentCommentAuditResult, presentLinkAuditResult, presentReactAuditResult, presentRtlAuditResult, } from "#/audit/output";
-import { prepareCommentAudit, prepareLinkAudit, prepareReactAudit, prepareRtlAudit } from "#/audit/prepare";
+import { commentAuditRunRequestSchema, linkAuditRunRequestSchema, reactAuditRunRequestSchema, rtlAuditRunRequestSchema, displayNameAuditRunRequestSchema, } from "#/audit/cli-schema";
+import { exitCodeForCommentAuditResult, exitCodeForLinkAuditResult, exitCodeForReactAuditResult, exitCodeForRtlAuditResult, exitCodeForDisplayNameAuditResult, formatCommentAuditJsonOutput, formatLinkAuditJsonOutput, formatReactAuditJsonOutput, formatRtlAuditJsonOutput, formatDisplayNameAuditJsonOutput, presentCommentAuditResult, presentLinkAuditResult, presentReactAuditResult, presentRtlAuditResult, presentDisplayNameAuditResult, } from "#/audit/output";
+import { prepareCommentAudit, prepareLinkAudit, prepareReactAudit, prepareRtlAudit, prepareDisplayNameAudit, } from "#/audit/prepare";
 import { runRtlAudit } from "#/audit/run";
 import { runCommentAudit } from "#/audit/run-comments";
+import { runDisplayNameAudit } from "#/audit/run-display-names";
 import { runLinkAudit } from "#/audit/run-links";
 import { runReactAudit } from "#/audit/run-react";
 import { readOptionalPositionalArg } from "#/core/cli/positional";
@@ -137,6 +138,45 @@ export function createAuditCommand() {
         }
         process.exitCode = exitCodeForReactAuditResult(outcome.value);
     });
+    cmd
+        .command("display-names")
+        .description("Report token(), tag() and module display names that break the <namespace>:<Name> convention")
+        .argument("[target]", "Directory or file to scan (default: the repo root)")
+        .option("--json", "Print one JSON summary on stdout", false)
+        .action(async (target, opts) => {
+        const prelude = await prepareDisplayNameAudit(nodeFilesystem, {
+            currentWorkingDirectory: process.cwd(),
+            rawTarget: readOptionalPositionalArg(target),
+        });
+        if (!consumeCliAppError(prelude)) {
+            return;
+        }
+        const { rootDir, targetPath, allowlist } = prelude.value;
+        const parsed = parseWithSchema(displayNameAuditRunRequestSchema, {
+            rootDir,
+            targetPath,
+            allowlist,
+            json: !!opts.json,
+        });
+        if (!consumeCliAppError(parsed)) {
+            return;
+        }
+        const outcome = runDisplayNameAudit(nodeFilesystem, {
+            rootDir: parsed.value.rootDir,
+            targetPath: parsed.value.targetPath,
+            allowlist: parsed.value.allowlist ?? [],
+        });
+        if (!consumeCliAppError(outcome)) {
+            return;
+        }
+        if (parsed.value.json) {
+            logger.out(formatDisplayNameAuditJsonOutput(outcome.value, rootDir));
+        }
+        else {
+            presentDisplayNameAuditResult(outcome.value);
+        }
+        process.exitCode = exitCodeForDisplayNameAuditResult(outcome.value);
+    });
     cmd
         .command("comments")
         .description("Report section dividers that are not in the repo's one allowed form")

package/dist/audit/domain/comment-dividers.js

@@ -11,12 +11,31 @@ const RULE_GLYPH = "─";
 const LEAD_GLYPHS = "──";
 /** Every glyph a divider has historically been drawn with, so legacy forms are recognised too. */
 const RULE_CHARACTER_CLASS = String.raw `[-=─_*~#]`;
-const ruleOnlyLinePattern = new RegExp(String.raw `^(?<indent>[ \t]*)(?:\/\/|\/\*|\*)[ \t]*${RULE_CHARACTER_CLASS}{4,}[ \t]*(?:\*\/)?[ \t]*$`);
-const titledLinePattern = new RegExp(String.raw `^(?<indent>[ \t]*)(?:\/\/|\/\*)[ \t]*${RULE_CHARACTER_CLASS}{2,}[ \t]+(?<title>.*?)[ \t]+${RULE_CHARACTER_CLASS}{2,}[ \t]*(?:\*\/)?[ \t]*$`);
-const commentLinePattern = /^[ \t]*(?:\/\/|\/\*|\*)/;
-const bareRuleClosePattern = new RegExp(String.raw `^[ \t]*${RULE_CHARACTER_CLASS}{4,}[ \t]*\*\/[ \t]*$`);
+// The comment lead each syntax opens a divider with — `#` for ignore files, slash forms for code.
+const commentLeadByLanguage = {
+    css: String.raw `\/\/|\/\*|\*`,
+    ignore: String.raw `#`,
+    js: String.raw `\/\/|\/\*|\*`,
+};
+// One compiled pattern set per language — the comment lead is the only part that varies.
+const patternsByLanguage = new Map();
+function patternsFor(language) {
+    const cached = patternsByLanguage.get(language);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const lead = commentLeadByLanguage[language];
+    const built = {
+        ruleOnly: new RegExp(String.raw `^(?<indent>[ \t]*)(?:${lead})[ \t]*${RULE_CHARACTER_CLASS}{4,}[ \t]*(?:\*\/)?[ \t]*$`),
+        titled: new RegExp(String.raw `^(?<indent>[ \t]*)(?:${lead})[ \t]*${RULE_CHARACTER_CLASS}{2,}[ \t]+(?<title>.*?)[ \t]+${RULE_CHARACTER_CLASS}{2,}[ \t]*(?:\*\/)?[ \t]*$`),
+        commentLine: new RegExp(String.raw `^[ \t]*(?:${lead})`),
+        bareRuleClose: new RegExp(String.raw `^[ \t]*${RULE_CHARACTER_CLASS}{4,}[ \t]*\*\/[ \t]*$`),
+        commentPrefix: new RegExp(String.raw `^[ \t]*(?:${lead})[ \t]?`),
+    };
+    patternsByLanguage.set(language, built);
+    return built;
+}
 const rulesOnlyPattern = new RegExp(String.raw `^(?:${RULE_CHARACTER_CLASS}|[ \t])*$`);
-const commentPrefixPattern = /^[ \t]*(?:\/\/|\/\*|\*)[ \t]?/;
 const commentSuffixPattern = /[ \t]*\*\/[ \t]*$/;
 /** A banner spanning more lines than this is prose that happens to start with a rule, not a divider. */
 const MAX_BANNER_SPAN = 16;
@@ -36,7 +55,8 @@ export function renderDivider(indent, title, language) {
         const head = `${indent}/* ${LEAD_GLYPHS} ${title} `;
         return `${head}${RULE_GLYPH.repeat(Math.max(2, DIVIDER_COLUMN - head.length - 3))} */`;
     }
-    const head = `${indent}// ${LEAD_GLYPHS} ${title} `;
+    const prefix = language === "ignore" ? "#" : "//";
+    const head = `${indent}${prefix} ${LEAD_GLYPHS} ${title} `;
     return `${head}${RULE_GLYPH.repeat(Math.max(2, DIVIDER_COLUMN - head.length))}`;
 }
 /**
@@ -80,7 +100,8 @@ export function applyCommentDividerFixes(content, language) {
 }
 function readRegionAt(lines, index, language) {
     const line = lines[index];
-    const titled = titledLinePattern.exec(line);
+    const patterns = patternsFor(language);
+    const titled = patterns.titled.exec(line);
     const title = titled?.groups?.title?.trim();
     if (titled !== null && title !== undefined && title.length > 0 && !rulesOnlyPattern.test(title)) {
         const indent = titled.groups?.indent ?? "";
@@ -94,26 +115,29 @@ function readRegionAt(lines, index, language) {
             defect: line === canonical ? null : usesCanonicalGlyphs(line) ? "bad-width" : "legacy-form",
         };
     }
-    const ruleOnly = ruleOnlyLinePattern.exec(line);
+    const ruleOnly = patterns.ruleOnly.exec(line);
     if (ruleOnly === null) {
         return null;
     }
-    return readBannerAt(lines, index, ruleOnly.groups?.indent ?? "");
+    return readBannerAt(lines, index, ruleOnly.groups?.indent ?? "", language);
 }
-function readBannerAt(lines, index, indent) {
+function readBannerAt(lines, index, indent, language) {
     const line = lines[index];
+    const patterns = patternsFor(language);
     // An unterminated `/*` opens a block whose body needs no per-line marker, so the run ends at `*/`.
     const insideBlock = line.trimStart().startsWith("/*") && !line.includes("*/");
     const body = [];
     let cursor = index + 1;
-    while (cursor < lines.length && cursor - index <= MAX_BANNER_SPAN && !isBannerClose(lines[cursor], insideBlock)) {
-        if (!insideBlock && !commentLinePattern.test(lines[cursor])) {
+    while (cursor < lines.length &&
+        cursor - index <= MAX_BANNER_SPAN &&
+        !isBannerClose(lines[cursor], insideBlock, language)) {
+        if (!insideBlock && !patterns.commentLine.test(lines[cursor])) {
             break;
         }
-        body.push(stripCommentPrefix(lines[cursor]));
+        body.push(stripCommentPrefix(lines[cursor], language));
         cursor++;
     }
-    const closed = cursor < lines.length && cursor - index <= MAX_BANNER_SPAN && isBannerClose(lines[cursor], insideBlock);
+    const closed = cursor < lines.length && cursor - index <= MAX_BANNER_SPAN && isBannerClose(lines[cursor], insideBlock, language);
     const meaningful = body.filter((entry) => entry.length > 0);
     // A frame around prose is a doc block, and an unclosed rule is prose formatting inside one.
     if (!closed || meaningful.length !== 1 || !looksLikeTitle(meaningful[0])) {
@@ -131,15 +155,19 @@ function readBannerAt(lines, index, indent) {
 function looksLikeTitle(text) {
     return text.length <= MAX_TITLE_LENGTH && !text.endsWith(".");
 }
-function isBannerClose(line, insideBlock) {
-    if (ruleOnlyLinePattern.test(line)) {
+function isBannerClose(line, insideBlock, language) {
+    const patterns = patternsFor(language);
+    if (patterns.ruleOnly.test(line)) {
         return true;
     }
-    return insideBlock && bareRuleClosePattern.test(line);
+    return insideBlock && patterns.bareRuleClose.test(line);
 }
 function usesCanonicalGlyphs(line) {
-    return line.trimStart().startsWith(`// ${LEAD_GLYPHS} `) || line.trimStart().startsWith(`/* ${LEAD_GLYPHS} `);
+    const trimmed = line.trimStart();
+    return (trimmed.startsWith(`// ${LEAD_GLYPHS} `) ||
+        trimmed.startsWith(`/* ${LEAD_GLYPHS} `) ||
+        trimmed.startsWith(`# ${LEAD_GLYPHS} `));
 }
-function stripCommentPrefix(line) {
-    return line.replace(commentPrefixPattern, "").replace(commentSuffixPattern, "").trim();
+function stripCommentPrefix(line, language) {
+    return line.replace(patternsFor(language).commentPrefix, "").replace(commentSuffixPattern, "").trim();
 }

package/dist/audit/domain/display-names.js

@@ -0,0 +1,71 @@
+/** The owner: a kebab-case package, app or feature slug, or a scoped package name. */
+const NAMESPACE = /^(?:@[a-z0-9-]+\/)?[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A token or module stands for a type or a unit of composition. */
+const PASCAL_CASE = /^[A-Z][A-Za-z0-9]*$/;
+/** A tag key stands for an attribute a request selects on, so it reads like a property. */
+const CAMEL_CASE = /^[a-z][A-Za-z0-9]*$/;
+/**
+ * A bare `token(…)` / `tag(…)` call, or a module factory call, whose first argument is a string literal.
+ *
+ * @remarks Generic arguments are skipped up to four levels of nesting, which is deeper than any
+ * declaration in the repo. Template literals are not matched: an interpolated name has no fixed
+ * text to check. The closing parenthesis is kept when the name is the only argument, so the
+ * reported text reads as the call was written.
+ */
+const DISPLAY_NAME_CALL = /(?<![\w$.])(?:(token|tag)\s*(?:<(?:[^<>]|<(?:[^<>]|<(?:[^<>]|<[^<>]*>)*>)*>)*>)?|((?:Sync|Async)?Module)\s*\.\s*create(?:Async)?)\s*\(\s*(["'])((?:(?!\3)[^\\\n]|\\.)*)\3(\s*\))?/g;
+const KIND_LABEL = {
+    token: "token display name",
+    tag: "tag key",
+    module: "module name",
+};
+/**
+ * Scans one source or markdown text for `token()`, `tag()` and module display names that break the convention.
+ *
+ * @remarks Runs on markdown as well as TypeScript because a doc sample is what a reader copies:
+ * a convention the docs break is not one the docs teach.
+ *
+ * @since 0.9.0
+ */
+export function auditDisplayNames(sourceText) {
+    const violations = [];
+    for (const match of sourceText.matchAll(DISPLAY_NAME_CALL)) {
+        const kind = match[1] === undefined ? "module" : match[1];
+        const reason = reasonFor(kind, match[4]);
+        if (reason === null) {
+            continue;
+        }
+        violations.push({ line: lineOfOffset(sourceText, match.index), raw: match[0], reason });
+    }
+    return violations;
+}
+/** Why a display name breaks the convention, or `null` when it holds. */
+function reasonFor(kind, name) {
+    const segments = name.split(":");
+    const label = KIND_LABEL[kind];
+    if (segments.length < 2) {
+        return `${label} '${name}' has no namespace — write '<namespace>:${name}'`;
+    }
+    const local = segments.at(-1);
+    for (const namespace of segments.slice(0, -1)) {
+        if (!NAMESPACE.test(namespace)) {
+            return `namespace '${namespace}' in '${name}' is not kebab-case (or a scoped package name)`;
+        }
+    }
+    if (kind === "tag") {
+        return CAMEL_CASE.test(local)
+            ? null
+            : `${label} '${local}' in '${name}' is not camelCase — a tag key names an attribute`;
+    }
+    return PASCAL_CASE.test(local)
+        ? null
+        : `${label} '${local}' in '${name}' is not PascalCase — a ${kind} stands for a ${kind === "token" ? "type" : "unit of composition"}`;
+}
+function lineOfOffset(sourceText, offset) {
+    let line = 1;
+    for (let index = 0; index < offset; index++) {
+        if (sourceText.charCodeAt(index) === 10) {
+            line++;
+        }
+    }
+    return line;
+}

package/dist/audit/output.js

@@ -169,4 +169,45 @@ export function formatCommentAuditJsonOutput(result, rootDir) {
 }
 function truncate(raw) {
     return raw.length <= 60 ? raw : `${raw.slice(0, 57)}…`;
+}
+/**
+ * Exit `1` when any non-allowlisted display-name violation remains.
+ *
+ * @since 0.9.0
+ */
+export function exitCodeForDisplayNameAuditResult(result) {
+    return result.violationCount > 0 ? CLI_EXIT_GENERAL_ERROR : CLI_EXIT_SUCCESS;
+}
+/**
+ * Human-readable display-name report.
+ *
+ * @since 0.9.0
+ */
+export function presentDisplayNameAuditResult(result) {
+    for (const file of result.files) {
+        logger.out(`\n${file.relativePath}`);
+        for (const { line, raw, reason } of file.violations) {
+            logger.out(`  ${line}: ${raw} → ${reason}`);
+        }
+    }
+    const allowlistSuffix = result.allowlistedCount > 0 ? ` (${result.allowlistedCount} allowlisted)` : "";
+    if (result.violationCount > 0) {
+        logger.out(`\n✖ ${result.violationCount} display name(s) off the convention${allowlistSuffix}`);
+    }
+    else {
+        logger.out(`✓ Every token, tag and module display name follows <namespace>:<Name> across ${result.scannedFileCount} file(s)${allowlistSuffix}`);
+    }
+}
+/**
+ * Machine-readable display-name summary for `--json`.
+ *
+ * @since 0.9.0
+ */
+export function formatDisplayNameAuditJsonOutput(result, rootDir) {
+    return JSON.stringify({
+        schemaVersion: 1,
+        ok: result.violationCount === 0,
+        cwd: rootDir,
+        result,
+    });
 }

package/dist/audit/prepare.js

@@ -131,4 +131,35 @@ export async function prepareCommentAudit(fs, args) {
         targetPath: fs.canonicalPathSync(targetPath),
         allowlist: commentsConfig.allowlist ?? [],
     });
+}
+/**
+ * Loads config and resolves the scan target for `audit display-names`.
+ *
+ * @remarks Defaults to the repo root: a display name collides across packages, so the convention
+ * has to hold across them.
+ *
+ * @since 0.9.0
+ */
+export async function prepareDisplayNameAudit(fs, args) {
+    let rootDir;
+    try {
+        rootDir = fs.canonicalPathSync(findRepoRoot(args.currentWorkingDirectory, fs));
+    }
+    catch (caughtError) {
+        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
+    }
+    const loadedOutcome = await loadCodefastConfig(rootDir, fs);
+    if (!loadedOutcome.ok) {
+        return loadedOutcome;
+    }
+    const displayNamesConfig = loadedOutcome.value.config.audit?.displayNames ?? {};
+    const targetPath = args.rawTarget === undefined ? rootDir : resolveRepoRelativePath(args.currentWorkingDirectory, args.rawTarget);
+    if (!fs.existsSync(targetPath)) {
+        return err(new AppError("NOT_FOUND", `Not found: ${targetPath}`));
+    }
+    return ok({
+        rootDir,
+        targetPath: fs.canonicalPathSync(targetPath),
+        allowlist: displayNamesConfig.allowlist ?? [],
+    });
 }

package/dist/audit/run-comments.js

@@ -68,30 +68,34 @@ export function runCommentAudit(fs, args) {
                 }
                 breakages.push({ line: region.startLine, raw: region.raw, reason: reasonByDefect[region.defect] });
             }
-            for (const finding of scanCommentContent(content, language)) {
-                if (allowlist.has(finding.raw) || allowlist.has(`${relativePath}:${finding.raw}`)) {
-                    allowlistedCount++;
-                    continue;
-                }
-                breakages.push({ line: finding.line, raw: finding.raw, reason: reasonByDefect[finding.defect] });
-            }
-            const packageVersion = nearestVersion(fs, absolutePath, versionByDirectory);
-            if (packageVersion !== null) {
-                for (const finding of scanImpossibleSinceTags(content, packageVersion)) {
+            // The content rules — banned fragments, `@since`, TSDoc grammar — govern doc comments in
+            // code; an ignore file carries only the divider convention.
+            if (language !== "ignore") {
+                for (const finding of scanCommentContent(content, language)) {
                     if (allowlist.has(finding.raw) || allowlist.has(`${relativePath}:${finding.raw}`)) {
                         allowlistedCount++;
                         continue;
                     }
-                    breakages.push({ line: finding.line, raw: finding.raw, reason: reasonByDefect["since-impossible"] });
+                    breakages.push({ line: finding.line, raw: finding.raw, reason: reasonByDefect[finding.defect] });
                 }
-            }
-            if (language === "js") {
-                for (const finding of scanTsdocSyntax(content)) {
-                    if (allowlist.has(finding.raw) || allowlist.has(`${relativePath}:${finding.raw}`)) {
-                        allowlistedCount++;
-                        continue;
+                const packageVersion = nearestVersion(fs, absolutePath, versionByDirectory);
+                if (packageVersion !== null) {
+                    for (const finding of scanImpossibleSinceTags(content, packageVersion)) {
+                        if (allowlist.has(finding.raw) || allowlist.has(`${relativePath}:${finding.raw}`)) {
+                            allowlistedCount++;
+                            continue;
+                        }
+                        breakages.push({ line: finding.line, raw: finding.raw, reason: reasonByDefect["since-impossible"] });
+                    }
+                }
+                if (language === "js") {
+                    for (const finding of scanTsdocSyntax(content)) {
+                        if (allowlist.has(finding.raw) || allowlist.has(`${relativePath}:${finding.raw}`)) {
+                            allowlistedCount++;
+                            continue;
+                        }
+                        breakages.push({ line: finding.line, raw: finding.raw, reason: finding.reason });
                     }
-                    breakages.push({ line: finding.line, raw: finding.raw, reason: finding.reason });
                 }
             }
             if (breakages.length > 0) {

package/dist/audit/run-display-names.js

@@ -0,0 +1,60 @@
+import path from "node:path";
+import { auditDisplayNames } from "#/audit/domain/display-names";
+import { AppError, messageFrom } from "#/core/errors";
+import { err, ok } from "#/core/result";
+import { walkMarkdownFiles } from "#/core/workspace/markdown-walk";
+import { walkTsxFiles } from "#/core/workspace/typescript-walk";
+/**
+ * Trees the convention does not reach: a test or benchmark token is scoped by its file and never
+ * meets another author's, and a changelog quotes names as they were.
+ */
+const SKIPPED_SEGMENTS = new Set(["tests", "benchmarks", ".changeset"]);
+const SKIPPED_BASENAMES = new Set(["CHANGELOG.md"]);
+/**
+ * Scans a target path for `token()`, `tag()` and module display names that break the convention.
+ *
+ * @since 0.9.0
+ */
+export function runDisplayNameAudit(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 = auditDisplayNames(content).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: filesToScan.length });
+    }
+    catch (caughtError) {
+        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
+    }
+}
+function collectScanPaths(fs, rootDir, targetPath) {
+    const stats = fs.statSync(targetPath);
+    const candidates = stats.isFile()
+        ? [targetPath]
+        : [...walkTsxFiles(targetPath, fs), ...walkMarkdownFiles(targetPath, fs)];
+    return candidates.filter((absolutePath) => {
+        const relative = path.relative(rootDir, absolutePath).split(path.sep);
+        return !relative.some((segment) => SKIPPED_SEGMENTS.has(segment)) && !SKIPPED_BASENAMES.has(relative.at(-1));
+    });
+}
+function toPosixPath(filePath) {
+    return filePath.split(path.sep).join("/");
+}

package/dist/core/config/schema.js

@@ -116,6 +116,15 @@ const codefastAuditReactConfigSchema = z
     allowlist: z.array(z.string()).optional(),
 })
     .strict();
+/**
+ * Display-name audit defaults — the scan always starts at the repo root, so only exceptions are configured.
+ */
+const codefastAuditDisplayNamesConfigSchema = z
+    .object({
+    /** Offending calls as written, or `repo/relative/path.ts:<call>` entries, to ignore. */
+    allowlist: z.array(z.string()).optional(),
+})
+    .strict();
 /**
  * Zod schema grouping the per-audit configurations under `audit`.
  *
@@ -127,6 +136,7 @@ const codefastAuditConfigSchema = z
     links: codefastAuditLinksConfigSchema.optional(),
     comments: codefastAuditCommentsConfigSchema.optional(),
     react: codefastAuditReactConfigSchema.optional(),
+    displayNames: codefastAuditDisplayNamesConfigSchema.optional(),
 })
     .strict();
 /**

package/dist/core/workspace/source-walk.js

@@ -1,7 +1,15 @@
 import path from "node:path";
 import { defaultSkipDirectoryNames } from "#/core/workspace/skip-directories";
+// Ignore files carry the divider convention over `#` comments — the content rules stay code-only.
+const ignoreFileNames = new Set([
+    ".gitignore",
+    ".dockerignore",
+    ".npmignore",
+    ".prettierignore",
+    ".eslintignore",
+]);
 /**
- * Every hand-written source file a comment convention applies to — `.ts`, `.tsx`, and `.css`.
+ * Every hand-written source file a comment convention applies to — `.ts`, `.tsx`, `.css`, and ignore files.
  *
  * @remarks Emitted declarations are excluded: they carry whatever the compiler copied over,
  * and rewriting them would be undone by the next build.
@@ -25,7 +33,10 @@ export function sourceCommentLanguage(filePath) {
     if (filePath.endsWith(".ts") || filePath.endsWith(".tsx")) {
         return "js";
     }
-    return filePath.endsWith(".css") ? "css" : null;
+    if (filePath.endsWith(".css")) {
+        return "css";
+    }
+    return ignoreFileNames.has(path.basename(filePath)) ? "ignore" : null;
 }
 function visitSourcePaths(result, entryPath, fs) {
     const entryStats = fs.statSync(entryPath);

package/dist/pack-slim/command.js

@@ -15,13 +15,14 @@ import { PackSlimProgressPresenter } from "#/pack-slim/output";
 import { runPackSlim } from "#/pack-slim/sync";
 import { ensureWorkingTreeClean } from "#/pack-slim/working-tree";
 /**
- * Creates the `pack-slim` subcommand, which strips the source lane from published packages before publish.
+ * Creates the `pack-slim` subcommand, which slims published packages down to what a consumer reads before publish.
  *
  * @since 0.8.1
  */
 export function createPackSlimCommand() {
     const cmd = new Command("pack-slim")
-        .description("Strip src, source conditions, and dist source maps from published packages before publish")
+        .description("Strip src, source conditions, unshipped imports, dev-only scripts, devDependencies, and dist source maps from " +
+        "published packages before publish")
         .argument("[package]", "Optional package path relative to repo root (e.g. packages/ui)")
         .option("--dry-run", "Report what would change without touching any file", false)
         .option("--force", "Run even if the git working tree has uncommitted tracked changes", false)