@outfitter/tooling 0.2.4 → 0.3.3

package/README.md

@@ -98,6 +98,75 @@ bunx @outfitter/tooling check-boundary-invocations
 When this fails, replace direct source execution with canonical command surfaces
 (`outfitter repo ...` in monorepo scripts, or package bins for standalone use).
 
+### `tooling check-bunup-registry`
+
+Validate that packages using `bunup --filter` are registered in `bunup.config.ts`.
+
+```bash
+bunx @outfitter/tooling check-bunup-registry
+```
+
+### `tooling check-changeset`
+
+Validate that PRs touching package source include a changeset.
+
+```bash
+bunx @outfitter/tooling check-changeset
+
+# Skip the check (e.g. for non-package changes)
+bunx @outfitter/tooling check-changeset --skip
+```
+
+### `tooling check-exports`
+
+Validate that `package.json` exports match source entry points.
+
+```bash
+bunx @outfitter/tooling check-exports
+
+# Machine-readable output
+bunx @outfitter/tooling check-exports --json
+```
+
+### `tooling check-tsdoc`
+
+Check TSDoc coverage on exported declarations.
+
+```bash
+bunx @outfitter/tooling check-tsdoc
+
+# Check specific packages
+bunx @outfitter/tooling check-tsdoc packages/cli packages/contracts
+
+# Strict mode with coverage threshold
+bunx @outfitter/tooling check-tsdoc --strict --min-coverage 80
+
+# JSON output
+bunx @outfitter/tooling check-tsdoc --json
+```
+
+### `tooling check-clean-tree`
+
+Assert the working tree is clean (no modified or untracked files).
+
+```bash
+bunx @outfitter/tooling check-clean-tree
+
+# Check specific paths only
+bunx @outfitter/tooling check-clean-tree --paths packages/cli packages/contracts
+```
+
+### `tooling check-readme-imports`
+
+Validate that README import examples match package exports.
+
+```bash
+bunx @outfitter/tooling check-readme-imports
+
+# Machine-readable output
+bunx @outfitter/tooling check-readme-imports --json
+```
+
 ## Configuration Presets
 
 ### Biome
@@ -188,7 +257,6 @@ bun run apps/outfitter/src/cli.ts repo check boundary-invocations --cwd .
 
 - [@outfitter/contracts](../contracts/README.md) — Result types and error patterns
 - [@outfitter/cli](../cli/README.md) — CLI framework
-- [@outfitter/kit](../kit/README.md) — Version coordination
 
 ## License
 

package/biome.json

@@ -1,5 +1,5 @@
 {
-	"$schema": "https://biomejs.dev/schemas/2.3.12/schema.json",
+	"$schema": "https://biomejs.dev/schemas/2.4.4/schema.json",
 	"root": false,
 	"javascript": {
 		"globals": ["Bun"]

package/dist/cli/index.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env bun
 import {
-  VERSION
-} from "../shared/chunk-8aenrm6f.js";
+  VERSION,
+  analyzeSourceFile,
+  calculateCoverage,
+  runCheckTsdoc
+} from "../shared/chunk-cmde0fwx.js";
 import {
   __require
 } from "../shared/chunk-3s189drz.js";
@@ -205,6 +208,8 @@ Add the missing entries to ${COLORS.blue}bunup.config.ts${COLORS.reset} defineWo
 }
 
 // src/cli/check-changeset.ts
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 function getChangedPackagePaths(files) {
   const packageNames = new Set;
   const pattern = /^packages\/([^/]+)\/src\//;
@@ -236,6 +241,73 @@ function checkChangesetRequired(changedPackages, changesetFiles) {
   }
   return { ok: false, missingFor: changedPackages };
 }
+function parseIgnoredPackagesFromChangesetConfig(jsonContent) {
+  try {
+    const parsed = JSON.parse(jsonContent);
+    if (!Array.isArray(parsed.ignore)) {
+      return [];
+    }
+    return parsed.ignore.filter((entry) => typeof entry === "string");
+  } catch {
+    return [];
+  }
+}
+function parseChangesetFrontmatterPackageNames(markdownContent) {
+  const frontmatterMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(markdownContent);
+  if (!frontmatterMatch?.[1]) {
+    return [];
+  }
+  const packages = new Set;
+  for (const line of frontmatterMatch[1].split(/\r?\n/)) {
+    const trimmed = line.trim();
+    const match = /^(["']?)(@[^"':\s]+\/[^"':\s]+)\1\s*:/.exec(trimmed);
+    if (match?.[2]) {
+      packages.add(match[2]);
+    }
+  }
+  return [...packages].sort();
+}
+function findIgnoredPackageReferences(input) {
+  if (input.ignoredPackages.length === 0 || input.changesetFiles.length === 0) {
+    return [];
+  }
+  const ignored = new Set(input.ignoredPackages);
+  const results = [];
+  for (const file of input.changesetFiles) {
+    const content = input.readChangesetFile(file);
+    const referencedPackages = parseChangesetFrontmatterPackageNames(content);
+    const invalidReferences = referencedPackages.filter((pkg) => ignored.has(pkg));
+    if (invalidReferences.length > 0) {
+      results.push({ file, packages: invalidReferences.sort() });
+    }
+  }
+  return results.sort((a, b) => a.file.localeCompare(b.file));
+}
+function loadIgnoredPackages(cwd) {
+  const configPath = join(cwd, ".changeset", "config.json");
+  if (!existsSync(configPath)) {
+    return [];
+  }
+  try {
+    return parseIgnoredPackagesFromChangesetConfig(readFileSync(configPath, "utf-8"));
+  } catch {
+    return [];
+  }
+}
+function getIgnoredReferencesForChangedChangesets(cwd, changesetFiles) {
+  const ignoredPackages = loadIgnoredPackages(cwd);
+  return findIgnoredPackageReferences({
+    changesetFiles,
+    ignoredPackages,
+    readChangesetFile: (filename) => {
+      try {
+        return readFileSync(join(cwd, ".changeset", filename), "utf-8");
+      } catch {
+        return "";
+      }
+    }
+  });
+}
 var COLORS2 = {
   reset: "\x1B[0m",
   red: "\x1B[31m",
@@ -275,25 +347,43 @@ async function runCheckChangeset(options = {}) {
   }
   const changesetFiles = getChangedChangesetFiles(changedFiles);
   const check = checkChangesetRequired(changedPackages, changesetFiles);
-  if (check.ok) {
-    process.stdout.write(`${COLORS2.green}Changeset found for ${changedPackages.length} changed package(s).${COLORS2.reset}
+  if (!check.ok) {
+    process.stderr.write(`${COLORS2.yellow}No changeset found.${COLORS2.reset} ` + "Consider adding one with `bun run changeset` for a custom changelog entry.\n\n");
+    process.stderr.write(`Packages with source changes:
+
+`);
+    for (const pkg of check.missingFor) {
+      process.stderr.write(`  ${COLORS2.yellow}@outfitter/${pkg}${COLORS2.reset}
+`);
+    }
+    process.stderr.write(`
+Run ${COLORS2.blue}bun run changeset${COLORS2.reset} for a custom changelog entry, ` + `or add ${COLORS2.blue}release:none${COLORS2.reset} to skip.
 `);
-    process.exit(0);
   }
-  process.stderr.write(`${COLORS2.red}Missing changeset!${COLORS2.reset}
+  const ignoredReferences = getIgnoredReferencesForChangedChangesets(cwd, changesetFiles);
+  if (ignoredReferences.length > 0) {
+    process.stderr.write(`${COLORS2.red}Invalid changeset package reference(s).${COLORS2.reset}
 
 `);
-  process.stderr.write(`The following packages have source changes but no changeset:
+    process.stderr.write(`Changesets must not reference packages listed in .changeset/config.json ignore:
 
 `);
-  for (const pkg of check.missingFor) {
-    process.stderr.write(`  ${COLORS2.yellow}@outfitter/${pkg}${COLORS2.reset}
+    for (const reference of ignoredReferences) {
+      process.stderr.write(`  ${COLORS2.yellow}${reference.file}${COLORS2.reset}
 `);
+      for (const pkg of reference.packages) {
+        process.stderr.write(`    - ${pkg}
+`);
+      }
+    }
+    process.stderr.write(`
+Update the affected changeset files to remove ignored packages before merging.
+`);
+    process.exit(1);
   }
-  process.stderr.write(`
-Run ${COLORS2.blue}bun run changeset${COLORS2.reset} to add a changeset, ` + `or add the ${COLORS2.blue}no-changeset${COLORS2.reset} label to skip.
+  process.stdout.write(`${COLORS2.green}Changeset found for ${changedPackages.length} changed package(s).${COLORS2.reset}
 `);
-  process.exit(1);
+  process.exit(0);
 }
 
 // src/cli/check-clean-tree.ts
@@ -674,8 +764,9 @@ async function runInit(cwd = process.cwd()) {
 }
 
 // src/cli/pre-push.ts
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+import { join as join2, resolve as resolve4 } from "node:path";
+import ts from "typescript";
 var COLORS5 = {
   reset: "\x1B[0m",
   red: "\x1B[31m",
@@ -712,6 +803,9 @@ function isRedPhaseBranch(branch) {
 function isScaffoldBranch(branch) {
   return branch.endsWith("-scaffold") || branch.endsWith("/scaffold") || branch.endsWith("_scaffold");
 }
+function isReleaseBranch(branch) {
+  return branch.startsWith("changeset-release/");
+}
 var TEST_PATH_PATTERNS = [
   /(^|\/)__tests__\//,
   /(^|\/)__snapshots__\//,
@@ -731,6 +825,32 @@ function areFilesTestOnly(paths) {
 function canBypassRedPhaseByChangedFiles(changedFiles) {
   return changedFiles.deterministic && areFilesTestOnly(changedFiles.files);
 }
+function hasPackageSourceChanges(changedFiles) {
+  const packageSrcPattern = /^packages\/[^/]+\/src\//;
+  return changedFiles.files.some((f) => packageSrcPattern.test(f));
+}
+async function printTsdocSummary() {
+  const glob = new Bun.Glob("packages/*/src/index.ts");
+  const cwd = process.cwd();
+  const allDeclarations = [];
+  for (const entry of glob.scanSync({ cwd })) {
+    const filePath = resolve4(cwd, entry);
+    const content = await Bun.file(filePath).text();
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+    allDeclarations.push(...analyzeSourceFile(sourceFile));
+  }
+  if (allDeclarations.length === 0)
+    return;
+  const coverage = calculateCoverage(allDeclarations);
+  const parts = [];
+  if (coverage.documented > 0)
+    parts.push(`${coverage.documented} documented`);
+  if (coverage.partial > 0)
+    parts.push(`${coverage.partial} partial`);
+  if (coverage.undocumented > 0)
+    parts.push(`${coverage.undocumented} undocumented`);
+  log(`${COLORS5.blue}TSDoc${COLORS5.reset}: ${coverage.percentage}% coverage (${parts.join(", ")} of ${coverage.total} total)`);
+}
 function resolveBaseRef() {
   const candidates = [
     "origin/main",
@@ -868,12 +988,12 @@ function createVerificationPlan(scripts) {
   };
 }
 function readPackageScripts(cwd = process.cwd()) {
-  const packageJsonPath = join(cwd, "package.json");
-  if (!existsSync(packageJsonPath)) {
+  const packageJsonPath = join2(cwd, "package.json");
+  if (!existsSync2(packageJsonPath)) {
     return {};
   }
   try {
-    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    const parsed = JSON.parse(readFileSync2(packageJsonPath, "utf-8"));
     const scripts = parsed.scripts ?? {};
     const normalized = {};
     for (const [name, value] of Object.entries(scripts)) {
@@ -898,6 +1018,11 @@ async function runPrePush(options = {}) {
   log(`${COLORS5.blue}Pre-push verify${COLORS5.reset} (TDD-aware)`);
   log("");
   const branch = getCurrentBranch();
+  if (isReleaseBranch(branch)) {
+    log(`${COLORS5.yellow}Release branch detected${COLORS5.reset}: ${COLORS5.blue}${branch}${COLORS5.reset}`);
+    log(`${COLORS5.yellow}Skipping strict verification${COLORS5.reset} for automated changeset release push`);
+    process.exit(0);
+  }
   if (isRedPhaseBranch(branch)) {
     if (maybeSkipForRedPhase("branch", branch)) {
       process.exit(0);
@@ -943,14 +1068,20 @@ async function runPrePush(options = {}) {
     log("  - feature_tests");
     process.exit(1);
   }
+  const changedFiles = getChangedFilesForPush();
+  if (hasPackageSourceChanges(changedFiles)) {
+    try {
+      await printTsdocSummary();
+    } catch {}
+  }
   log("");
   log(`${COLORS5.green}Strict verification passed${COLORS5.reset}`);
   process.exit(0);
 }
 
 // src/cli/upgrade-bun.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync } from "node:fs";
-import { join as join2 } from "node:path";
+import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync } from "node:fs";
+import { join as join3 } from "node:path";
 var COLORS6 = {
   reset: "\x1B[0m",
   red: "\x1B[31m",
@@ -988,13 +1119,13 @@ function findPackageJsonFiles(dir) {
   const glob = new Bun.Glob("**/package.json");
   for (const path of glob.scanSync({ cwd: dir })) {
     if (!path.includes("node_modules")) {
-      results.push(join2(dir, path));
+      results.push(join3(dir, path));
     }
   }
   return results;
 }
 function updateEnginesBun(filePath, version) {
-  const content = readFileSync2(filePath, "utf-8");
+  const content = readFileSync3(filePath, "utf-8");
   const pattern = /"bun":\s*">=[\d.]+"/;
   if (!pattern.test(content)) {
     return false;
@@ -1007,7 +1138,7 @@ function updateEnginesBun(filePath, version) {
   return false;
 }
 function updateTypesBun(filePath, version) {
-  const content = readFileSync2(filePath, "utf-8");
+  const content = readFileSync3(filePath, "utf-8");
   const pattern = /"@types\/bun":\s*"\^[\d.]+"/;
   if (!pattern.test(content)) {
     return false;
@@ -1021,14 +1152,14 @@ function updateTypesBun(filePath, version) {
 }
 async function runUpgradeBun(targetVersion, options = {}) {
   const cwd = process.cwd();
-  const bunVersionFile = join2(cwd, ".bun-version");
+  const bunVersionFile = join3(cwd, ".bun-version");
   let version = targetVersion;
   if (!version) {
     info("Fetching latest Bun version...");
     version = await fetchLatestVersion();
     log2(`Latest version: ${version}`);
   }
-  const currentVersion = existsSync2(bunVersionFile) ? readFileSync2(bunVersionFile, "utf-8").trim() : "unknown";
+  const currentVersion = existsSync3(bunVersionFile) ? readFileSync3(bunVersionFile, "utf-8").trim() : "unknown";
   log2(`Current version: ${currentVersion}`);
   if (currentVersion === version) {
     success(`Already on version ${version}`);
@@ -1129,6 +1260,14 @@ register(new Command("check-changeset").description("Validate PRs touching packa
 register(new Command("check-exports").description("Validate package.json exports match source entry points").option("--json", "Output results as JSON").action(async (options) => {
   await runCheckExports(options);
 }));
+register(new Command("check-tsdoc").description("Check TSDoc coverage on exported declarations").argument("[paths...]", "Specific package paths to check").option("--strict", "Exit non-zero when coverage is below threshold").option("--json", "Output results as JSON").option("--min-coverage <percentage>", "Minimum coverage percentage", "0").action(async (paths, options) => {
+  await runCheckTsdoc({
+    paths: paths.length > 0 ? paths : undefined,
+    strict: options.strict,
+    json: options.json,
+    minCoverage: options.minCoverage ? Number.parseInt(options.minCoverage, 10) : undefined
+  });
+}));
 register(new Command("check-clean-tree").description("Assert working tree is clean (no modified or untracked files)").option("--paths <paths...>", "Limit check to specific paths").action(async (options) => {
   await runCheckCleanTree(options);
 }));

package/dist/index.d.ts

@@ -1,4 +1,79 @@
 import { ZodType } from "zod";
+/** Coverage classification for a single declaration. */
+type CoverageLevel = "documented" | "partial" | "undocumented";
+/** Result for a single exported declaration. */
+interface DeclarationCoverage {
+	readonly name: string;
+	readonly kind: string;
+	readonly level: CoverageLevel;
+	readonly file: string;
+	readonly line: number;
+}
+/** Coverage summary statistics. */
+interface CoverageSummary {
+	readonly documented: number;
+	readonly partial: number;
+	readonly undocumented: number;
+	readonly total: number;
+	readonly percentage: number;
+}
+/** Per-package TSDoc coverage stats. */
+interface PackageCoverage {
+	readonly name: string;
+	readonly path: string;
+	readonly declarations: readonly DeclarationCoverage[];
+	readonly documented: number;
+	readonly partial: number;
+	readonly undocumented: number;
+	readonly total: number;
+	readonly percentage: number;
+}
+/** Aggregated result across all packages. */
+interface TsDocCheckResult {
+	readonly ok: boolean;
+	readonly packages: readonly PackageCoverage[];
+	readonly summary: CoverageSummary;
+}
+/** Zod schema for {@link CoverageLevel}. */
+declare const coverageLevelSchema: ZodType<CoverageLevel>;
+/** Zod schema for {@link DeclarationCoverage}. */
+declare const declarationCoverageSchema: ZodType<DeclarationCoverage>;
+/** Zod schema for {@link PackageCoverage}. */
+declare const packageCoverageSchema: ZodType<PackageCoverage>;
+/** Zod schema for {@link TsDocCheckResult}. */
+declare const tsDocCheckResultSchema: ZodType<TsDocCheckResult>;
+/** Options for the check-tsdoc command. */
+interface CheckTsDocOptions {
+	readonly strict?: boolean | undefined;
+	readonly json?: boolean | undefined;
+	readonly minCoverage?: number | undefined;
+	readonly cwd?: string | undefined;
+	readonly paths?: readonly string[] | undefined;
+}
+/**
+* Analyze TSDoc coverage across workspace packages.
+*
+* Pure function that discovers packages, analyzes TSDoc coverage on exported
+* declarations, and returns the aggregated result. Does not print output or
+* call `process.exit()`.
+*
+* @param options - Analysis options (paths, strict mode, coverage threshold)
+* @returns Aggregated coverage result across all packages, or `null` if no packages found
+*/
+declare function analyzeCheckTsdoc(options?: CheckTsDocOptions): TsDocCheckResult | null;
+/**
+* Print a TSDoc coverage result in human-readable format.
+*
+* Renders a bar chart per package with summary statistics. Writes to stdout/stderr.
+*
+* @param result - The coverage result to print
+* @param options - Display options (strict mode, coverage threshold for warning)
+*/
+declare function printCheckTsdocHuman(result: TsDocCheckResult, options?: {
+	strict?: boolean | undefined;
+	minCoverage?: number | undefined;
+}): void;
+import { ZodType as ZodType2 } from "zod";
 /**
 * File entry in a block.
 */
@@ -16,7 +91,7 @@ interface FileEntry {
 * Schema for a file entry in a block.
 * Represents a file that will be copied to the user's project.
 */
-declare const FileEntrySchema: ZodType<FileEntry>;
+declare const FileEntrySchema: ZodType2<FileEntry>;
 /**
 * Block in the registry.
 */
@@ -38,7 +113,7 @@ interface Block {
 * Schema for a block in the registry.
 * A block is a collection of related files that can be added together.
 */
-declare const BlockSchema: ZodType<Block>;
+declare const BlockSchema: ZodType2<Block>;
 /**
 * Complete registry structure.
 */
@@ -52,7 +127,7 @@ interface Registry {
 * Schema for the complete registry.
 * Contains all available blocks with their files and metadata.
 */
-declare const RegistrySchema: ZodType<Registry>;
+declare const RegistrySchema: ZodType2<Registry>;
 /**
 * Block definition used in the build script.
 * Specifies how to collect source files into a block.
@@ -108,4 +183,4 @@ interface AddBlockOptions {
 }
 /** Package version, read from package.json at load time. */
 declare const VERSION: string;
-export { VERSION, RegistrySchema, RegistryBuildConfig, Registry, FileEntrySchema, FileEntry, BlockSchema, BlockDefinition, Block, AddBlockResult, AddBlockOptions };
+export { tsDocCheckResultSchema, printCheckTsdocHuman, packageCoverageSchema, declarationCoverageSchema, coverageLevelSchema, analyzeCheckTsdoc, VERSION, TsDocCheckResult, RegistrySchema, RegistryBuildConfig, Registry, PackageCoverage, FileEntrySchema, FileEntry, DeclarationCoverage, CoverageLevel, CheckTsDocOptions, BlockSchema, BlockDefinition, Block, AddBlockResult, AddBlockOptions };

package/dist/index.js

@@ -1,8 +1,13 @@
 import {
-  VERSION
-} from "./shared/chunk-8aenrm6f.js";
+  VERSION,
+  analyzeCheckTsdoc,
+  coverageLevelSchema,
+  declarationCoverageSchema,
+  packageCoverageSchema,
+  printCheckTsdocHuman,
+  tsDocCheckResultSchema
+} from "./shared/chunk-cmde0fwx.js";
 import"./shared/chunk-3s189drz.js";
-
 // src/registry/schema.ts
 import { z } from "zod";
 var FileEntrySchema = z.object({
@@ -15,15 +20,21 @@ var BlockSchema = z.object({
   name: z.string().min(1),
   description: z.string().min(1),
   files: z.array(FileEntrySchema).optional(),
-  dependencies: z.record(z.string()).optional(),
-  devDependencies: z.record(z.string()).optional(),
+  dependencies: z.record(z.string(), z.string()).optional(),
+  devDependencies: z.record(z.string(), z.string()).optional(),
   extends: z.array(z.string()).optional()
 });
 var RegistrySchema = z.object({
   version: z.string(),
-  blocks: z.record(BlockSchema)
+  blocks: z.record(z.string(), BlockSchema)
 });
 export {
+  tsDocCheckResultSchema,
+  printCheckTsdocHuman,
+  packageCoverageSchema,
+  declarationCoverageSchema,
+  coverageLevelSchema,
+  analyzeCheckTsdoc,
   VERSION,
   RegistrySchema,
   FileEntrySchema,