@outfitter/tooling 0.3.3 → 0.3.5

package/dist/shared/@outfitter/tooling-pq47jv6t.js

@@ -0,0 +1,213 @@
+// @bun
+import {
+  isTypesBunVersionCompatible,
+  parseSemver
+} from "./tooling-mkynjra9.js";
+
+// packages/tooling/src/cli/upgrade-bun.ts
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+var COLORS = {
+  reset: "\x1B[0m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m"
+};
+function log(msg) {
+  process.stdout.write(`${msg}
+`);
+}
+function info(msg) {
+  process.stdout.write(`${COLORS.blue}\u25B8${COLORS.reset} ${msg}
+`);
+}
+function success(msg) {
+  process.stdout.write(`${COLORS.green}\u2713${COLORS.reset} ${msg}
+`);
+}
+function warn(msg) {
+  process.stdout.write(`${COLORS.yellow}!${COLORS.reset} ${msg}
+`);
+}
+async function fetchLatestVersion() {
+  const response = await fetch("https://api.github.com/repos/oven-sh/bun/releases/latest");
+  const data = await response.json();
+  const match = data.tag_name.match(/bun-v(.+)/);
+  if (!match?.[1]) {
+    throw new Error(`Could not parse version from tag: ${data.tag_name}`);
+  }
+  return match[1];
+}
+async function resolveTypesBunVersion(targetVersion) {
+  const response = await fetch("https://registry.npmjs.org/@types%2fbun");
+  if (!response.ok) {
+    throw new Error(`Failed to fetch @types/bun metadata: ${response.status}`);
+  }
+  const data = await response.json();
+  if (data.versions && Object.hasOwn(data.versions, targetVersion)) {
+    return targetVersion;
+  }
+  if (data.versions) {
+    const compatible = Object.keys(data.versions).filter((candidate) => isTypesBunVersionCompatible(targetVersion, candidate)).map((candidate) => ({
+      version: candidate,
+      parsed: parseSemver(candidate)
+    })).filter((candidate) => !!candidate.parsed).toSorted((left, right) => right.parsed.patch - left.parsed.patch);
+    const preferred = compatible[0];
+    if (preferred) {
+      return preferred.version;
+    }
+  }
+  const latest = data["dist-tags"]?.latest;
+  if (latest && isTypesBunVersionCompatible(targetVersion, latest)) {
+    return latest;
+  }
+  return targetVersion;
+}
+function findPackageJsonFiles(dir) {
+  const files = new Set;
+  const glob = new Bun.Glob("**/package.json");
+  for (const path of glob.scanSync({ cwd: dir })) {
+    if (!path.includes("node_modules")) {
+      files.add(join(dir, path));
+    }
+  }
+  const gitList = Bun.spawnSync(["git", "ls-files", "--cached", "--others", "--exclude-standard"], { cwd: dir });
+  if (gitList.exitCode === 0) {
+    const trackedAndUntrackedFiles = new TextDecoder().decode(gitList.stdout).split(`
+`).filter((path) => path.endsWith("package.json")).filter((path) => !path.includes("node_modules")).map((path) => join(dir, path)).filter((path) => existsSync(path));
+    for (const filePath of trackedAndUntrackedFiles) {
+      files.add(filePath);
+    }
+  }
+  return [...files].toSorted();
+}
+function updatePackageManager(filePath, version) {
+  const content = readFileSync(filePath, "utf-8");
+  const pattern = /"packageManager":\s*"bun@[\d.]+"/;
+  if (!pattern.test(content)) {
+    return false;
+  }
+  const updated = content.replace(pattern, `"packageManager": "bun@${version}"`);
+  if (updated !== content) {
+    writeFileSync(filePath, updated);
+    return true;
+  }
+  return false;
+}
+function updateEnginesBun(filePath, version) {
+  const content = readFileSync(filePath, "utf-8");
+  const pattern = /"bun":\s*">=[\d.]+"/;
+  if (!pattern.test(content)) {
+    return false;
+  }
+  const updated = content.replace(pattern, `"bun": ">=${version}"`);
+  if (updated !== content) {
+    writeFileSync(filePath, updated);
+    return true;
+  }
+  return false;
+}
+function updateTypesBun(filePath, version) {
+  const content = readFileSync(filePath, "utf-8");
+  const pattern = /"@types\/bun":\s*"\^[\d.]+"/;
+  if (!pattern.test(content)) {
+    return false;
+  }
+  const updated = content.replace(pattern, `"@types/bun": "^${version}"`);
+  if (updated !== content) {
+    writeFileSync(filePath, updated);
+    return true;
+  }
+  return false;
+}
+async function runUpgradeBun(targetVersion, options = {}) {
+  const cwd = process.cwd();
+  const bunVersionFile = join(cwd, ".bun-version");
+  let version = targetVersion;
+  if (!version) {
+    info("Fetching latest Bun version...");
+    version = await fetchLatestVersion();
+    log(`Latest version: ${version}`);
+  }
+  const currentVersion = existsSync(bunVersionFile) ? readFileSync(bunVersionFile, "utf-8").trim() : "unknown";
+  log(`Current version: ${currentVersion}`);
+  if (currentVersion === version) {
+    success(`Already on version ${version}`);
+    return;
+  }
+  log("");
+  info(`Upgrading Bun: ${currentVersion} \u2192 ${version}`);
+  log("");
+  let typesVersion = version;
+  try {
+    info("Resolving @types/bun version...");
+    typesVersion = await resolveTypesBunVersion(version);
+    if (typesVersion !== version) {
+      warn(`@types/bun ${version} is not published yet; using @types/bun ${typesVersion}`);
+    }
+  } catch (error) {
+    warn(`Could not resolve @types/bun metadata (${error instanceof Error ? error.message : "unknown error"}), defaulting to ${version}`);
+  }
+  writeFileSync(bunVersionFile, `${version}
+`);
+  success("Updated .bun-version");
+  const packageFiles = findPackageJsonFiles(cwd);
+  info("Updating packageManager...");
+  for (const file of packageFiles) {
+    if (updatePackageManager(file, version)) {
+      log(`  ${file.replace(`${cwd}/`, "")}`);
+    }
+  }
+  info("Updating engines.bun...");
+  for (const file of packageFiles) {
+    if (updateEnginesBun(file, version)) {
+      log(`  ${file.replace(`${cwd}/`, "")}`);
+    }
+  }
+  info("Updating @types/bun...");
+  for (const file of packageFiles) {
+    if (updateTypesBun(file, typesVersion)) {
+      log(`  ${file.replace(`${cwd}/`, "")}`);
+    }
+  }
+  if (options.install !== false) {
+    log("");
+    info(`Installing Bun ${version}...`);
+    const installResult = Bun.spawnSync([
+      "bash",
+      "-c",
+      `curl -fsSL https://bun.sh/install | bash -s "bun-v${version}"`
+    ]);
+    if (installResult.exitCode !== 0) {
+      warn("Could not install Bun automatically");
+      log("Install manually: curl -fsSL https://bun.sh/install | bash");
+    } else {
+      success(`Bun ${version} installed`);
+      log("");
+      info("Updating lockfile...");
+      const bunInstall = Bun.spawnSync(["bun", "install"], {
+        cwd,
+        env: {
+          ...process.env,
+          BUN_INSTALL: `${process.env["HOME"]}/.bun`,
+          PATH: `${process.env["HOME"]}/.bun/bin:${process.env["PATH"]}`
+        }
+      });
+      if (bunInstall.exitCode === 0) {
+        success("Lockfile updated");
+      } else {
+        warn("Could not update lockfile - run 'bun install' manually");
+      }
+    }
+  }
+  log("");
+  success("Done! Changes ready to commit:");
+  log("  - .bun-version");
+  log("  - package.json files (packageManager, engines.bun, @types/bun)");
+  log("  - bun.lock");
+  log("");
+  log(`Commit with: git add -A && git commit -m 'chore: upgrade Bun to ${version}'`);
+}
+
+export { runUpgradeBun };

package/dist/shared/@outfitter/tooling-sjm8nebx.d.ts

@@ -0,0 +1,109 @@
+import { ZodType } from "zod";
+/**
+* File entry in a block.
+*/
+interface FileEntry {
+	/** Destination path relative to project root */
+	path: string;
+	/** File contents (embedded in registry) */
+	content: string;
+	/** Whether to chmod +x after copying */
+	executable?: boolean | undefined;
+	/** Whether to process as a template (future) */
+	template?: boolean | undefined;
+}
+/**
+* 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>;
+/**
+* Block in the registry.
+*/
+interface Block {
+	/** Block name (matches the key in blocks record) */
+	name: string;
+	/** Human-readable description */
+	description: string;
+	/** Files included in this block */
+	files?: FileEntry[] | undefined;
+	/** npm dependencies to add to package.json */
+	dependencies?: Record<string, string> | undefined;
+	/** npm devDependencies to add to package.json */
+	devDependencies?: Record<string, string> | undefined;
+	/** Other blocks this block extends (for composite blocks) */
+	extends?: string[] | undefined;
+}
+/**
+* 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>;
+/**
+* Complete registry structure.
+*/
+interface Registry {
+	/** Registry schema version */
+	version: string;
+	/** Map of block name to block definition */
+	blocks: Record<string, Block>;
+}
+/**
+* Schema for the complete registry.
+* Contains all available blocks with their files and metadata.
+*/
+declare const RegistrySchema: ZodType<Registry>;
+/**
+* Block definition used in the build script.
+* Specifies how to collect source files into a block.
+*/
+interface BlockDefinition {
+	/** Human-readable description */
+	description: string;
+	/** Source file paths (relative to repo root) */
+	files?: string[];
+	/** Remap source paths to destination paths */
+	remap?: Record<string, string>;
+	/** npm dependencies */
+	dependencies?: Record<string, string>;
+	/** npm devDependencies */
+	devDependencies?: Record<string, string>;
+	/** Other blocks this block extends */
+	extends?: string[];
+}
+/**
+* Configuration for the registry build.
+*/
+interface RegistryBuildConfig {
+	/** Registry schema version */
+	version: string;
+	/** Block definitions */
+	blocks: Record<string, BlockDefinition>;
+}
+/**
+* Result of adding a block to a project.
+*/
+interface AddBlockResult {
+	/** Files that were created */
+	created: string[];
+	/** Files that were skipped (already exist) */
+	skipped: string[];
+	/** Files that were overwritten (with --force) */
+	overwritten: string[];
+	/** Dependencies added to package.json */
+	dependencies: Record<string, string>;
+	/** devDependencies added to package.json */
+	devDependencies: Record<string, string>;
+}
+/**
+* Options for the add command.
+*/
+interface AddBlockOptions {
+	/** Overwrite existing files */
+	force?: boolean;
+	/** Show what would be added without making changes */
+	dryRun?: boolean;
+	/** Working directory (defaults to cwd) */
+	cwd?: string;
+}
+export { FileEntry, FileEntrySchema, Block, BlockSchema, Registry, RegistrySchema, BlockDefinition, RegistryBuildConfig, AddBlockResult, AddBlockOptions };

package/dist/shared/@outfitter/tooling-stgnc2zx.d.ts

@@ -0,0 +1,85 @@
+import { CheckTsDocOptions, CoverageLevel, DeclarationCoverage, PackageCoverage, TsDocCheckResult } from "./tooling-tj9p41vj.js";
+import ts from "typescript";
+/**
+* Check whether a node is an exported declaration worth checking.
+*
+* Returns true for function, interface, type alias, class, enum, and variable
+* declarations that carry the `export` keyword. Re-exports (`{ ... } from`)
+* and `*` are excluded since TSDoc belongs at the definition site.
+*/
+declare function isExportedDeclaration(node: ts.Node): boolean;
+/**
+* Extract the name of a declaration node.
+*
+* For variable statements, returns the name of the first variable declarator.
+* Returns `undefined` for anonymous declarations (e.g., `function() {}`).
+*/
+declare function getDeclarationName(node: ts.Node): string | undefined;
+/**
+* Determine the kind label for a declaration node.
+*
+* Maps AST node types to human-readable kind strings used in coverage reports.
+*/
+declare function getDeclarationKind(node: ts.Node): string;
+/**
+* Classify a declaration's TSDoc coverage level.
+*
+* - `"documented"` -- has a JSDoc comment with a description. For interfaces
+*   and classes, all members must also have JSDoc comments.
+* - `"partial"` -- the declaration has a JSDoc comment but some members
+*   (in interfaces/classes) lack documentation.
+* - `"undocumented"` -- no JSDoc comment at all.
+*/
+declare function classifyDeclaration(node: ts.Node, sourceFile: ts.SourceFile): CoverageLevel;
+/**
+* Analyze all exported declarations in a source file for TSDoc coverage.
+*
+* Walks top-level statements, filters to exported declarations, and
+* classifies each for documentation coverage.
+*/
+declare function analyzeSourceFile(sourceFile: ts.SourceFile): DeclarationCoverage[];
+/**
+* Calculate aggregate coverage statistics from declaration results.
+*
+* Partial documentation counts as half coverage in the percentage calculation.
+* An empty array returns 100% (no declarations to check).
+*/
+declare function calculateCoverage(declarations: readonly DeclarationCoverage[]): {
+	documented: number;
+	partial: number;
+	undocumented: number;
+	total: number;
+	percentage: number;
+};
+/** Discover packages with src/index.ts entry points. */
+declare function discoverPackages(cwd: string): Array<{
+	name: string;
+	path: string;
+	entryPoint: string;
+}>;
+/**
+* Collect source files referenced by re-exports in a barrel file.
+*
+* For `{ ... } from "./foo"` and `* from "./bar"`, resolves
+* the module specifier to a source file in the program. Returns only files
+* within the package (skips external modules).
+*/
+declare function collectReExportedSourceFiles(sourceFile: ts.SourceFile, program: ts.Program, pkgPath: string): ts.SourceFile[];
+/** Analyze a single package entry point, returning coverage data. */
+declare function analyzePackage(pkg: {
+	name: string;
+	path: string;
+	entryPoint: string;
+}, workspaceCwd: string): PackageCoverage;
+/**
+* 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;
+export { isExportedDeclaration, getDeclarationName, getDeclarationKind, classifyDeclaration, analyzeSourceFile, calculateCoverage, discoverPackages, collectReExportedSourceFiles, analyzePackage, analyzeCheckTsdoc };

package/dist/shared/@outfitter/tooling-tj9p41vj.d.ts

@@ -0,0 +1,55 @@
+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 CoverageSummary}. */
+declare const coverageSummarySchema: ZodType<CoverageSummary>;
+/** 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;
+}
+export { CoverageLevel, DeclarationCoverage, CoverageSummary, PackageCoverage, TsDocCheckResult, coverageLevelSchema, declarationCoverageSchema, coverageSummarySchema, packageCoverageSchema, tsDocCheckResultSchema, CheckTsDocOptions };

package/dist/shared/@outfitter/tooling-vjmhvpjq.d.ts

@@ -0,0 +1,29 @@
+/**
+* Shared Bun version compatibility helpers.
+*
+* @packageDocumentation
+*/
+/**
+* Parsed semantic version components.
+*/
+interface ParsedSemver {
+	readonly major: number;
+	readonly minor: number;
+	readonly patch: number;
+}
+/**
+* Parse a semver-like value into numeric components.
+*
+* Accepts standard versions like `1.3.10` and prerelease variants like
+* `1.3.10-canary.1` by reading only the numeric major/minor/patch prefix.
+*/
+declare function parseSemver(version: string): ParsedSemver | undefined;
+/**
+* Whether a candidate `@types/bun` version is compatible with a target Bun version.
+*
+* Compatibility rule:
+* - same major/minor
+* - candidate patch <= Bun patch
+*/
+declare function isTypesBunVersionCompatible(bunVersion: string, bunTypesVersion: string): boolean;
+export { ParsedSemver, parseSemver, isTypesBunVersionCompatible };

package/dist/shared/@outfitter/tooling-wwm97f47.js

@@ -0,0 +1,81 @@
+// @bun
+// packages/tooling/src/cli/check-bunup-registry.ts
+import { resolve } from "path";
+function extractBunupFilterName(script) {
+  const match = script.match(/bunup\s+--filter\s+(\S+)/);
+  return match?.[1] ?? null;
+}
+function findUnregisteredPackages(packagesWithFilter, registeredNames) {
+  const registered = new Set(registeredNames);
+  const missing = packagesWithFilter.filter((name) => !registered.has(name)).toSorted();
+  return {
+    ok: missing.length === 0,
+    missing
+  };
+}
+var COLORS = {
+  reset: "\x1B[0m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  dim: "\x1B[2m"
+};
+async function runCheckBunupRegistry() {
+  const cwd = process.cwd();
+  const configPath = resolve(cwd, "bunup.config.ts");
+  let registeredNames;
+  try {
+    const configModule = await import(configPath);
+    const rawConfig = configModule.default;
+    if (!Array.isArray(rawConfig)) {
+      process.stderr.write(`bunup.config.ts must export a workspace array
+`);
+      process.exitCode = 1;
+      return;
+    }
+    registeredNames = rawConfig.map((entry) => entry.name);
+  } catch {
+    process.stderr.write(`Could not load bunup.config.ts from ${cwd}
+`);
+    process.exitCode = 1;
+    return;
+  }
+  const packagesWithFilter = [];
+  const glob = new Bun.Glob("{packages,apps}/*/package.json");
+  for (const match of glob.scanSync({ cwd })) {
+    const pkgPath = resolve(cwd, match);
+    try {
+      const pkg = await Bun.file(pkgPath).json();
+      const buildScript = pkg.scripts?.["build"];
+      if (!buildScript)
+        continue;
+      const filterName = extractBunupFilterName(buildScript);
+      if (filterName) {
+        packagesWithFilter.push(filterName);
+      }
+    } catch {}
+  }
+  const result = findUnregisteredPackages(packagesWithFilter, registeredNames);
+  if (result.ok) {
+    process.stdout.write(`${COLORS.green}All ${packagesWithFilter.length} packages with bunup --filter are registered in bunup.config.ts.${COLORS.reset}
+`);
+    process.exitCode = 0;
+    return;
+  }
+  process.stderr.write(`${COLORS.red}${result.missing.length} package(s) have bunup --filter build scripts but are not registered in bunup.config.ts:${COLORS.reset}
+
+`);
+  for (const name of result.missing) {
+    process.stderr.write(`  ${COLORS.yellow}${name}${COLORS.reset}  ${COLORS.dim}(missing from workspace array)${COLORS.reset}
+`);
+  }
+  process.stderr.write(`
+Add the missing entries to ${COLORS.blue}bunup.config.ts${COLORS.reset} defineWorkspace array.
+`);
+  process.stderr.write(`Without registration, ${COLORS.dim}bunup --filter <name>${COLORS.reset} silently exits with no output.
+`);
+  process.exitCode = 1;
+}
+
+export { extractBunupFilterName, findUnregisteredPackages, runCheckBunupRegistry };

package/dist/shared/@outfitter/tooling-y43b117h.d.ts

@@ -0,0 +1,13 @@
+/** Options for the check-exports command */
+interface CheckExportsOptions {
+	readonly json?: boolean;
+}
+/** Resolve whether to output JSON based on options and env */
+declare function resolveJsonMode(options?: CheckExportsOptions): boolean;
+/**
+* Run check-exports across all workspace packages.
+*
+* Reads the bunup workspace config to discover packages and their * settings, then compares expected vs actual exports in each package.json.
+*/
+declare function runCheckExports(options?: CheckExportsOptions): Promise<void>;
+export { CheckExportsOptions, resolveJsonMode, runCheckExports };

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+import { VERSION } from "./shared/@outfitter/tooling-9vs606gq.js";
+export { VERSION };

package/dist/version.js

@@ -0,0 +1,8 @@
+// @bun
+import {
+  VERSION
+} from "./shared/@outfitter/tooling-ctmgnap5.js";
+import"./shared/@outfitter/tooling-jnrs9rqd.js";
+export {
+  VERSION
+};

package/lefthook.yml

@@ -13,6 +13,10 @@ pre-commit:
       run: bun x ultracite fix {staged_files}
       stage_fixed: true
 
+    home-paths:
+      glob: "*.{js,jsx,json,jsonc,css,md,ts,tsx,yaml,yml}"
+      run: bun x @outfitter/tooling check-home-paths {staged_files}
+
     typecheck:
       glob: "*.{ts,tsx}"
       run: bun run typecheck
@@ -25,4 +29,4 @@ pre-push:
       # (*-tests, */tests, *_tests). Otherwise runs verify:ci (or a strict
       # fallback: typecheck/check-or-lint/build/test).
       # Requires: @outfitter/tooling as a dev dependency.
-      run: bunx @outfitter/tooling pre-push
+      run: bun x @outfitter/tooling pre-push