@outfitter/tooling 0.2.3 → 0.3.0

package/dist/registry/schema.d.ts

@@ -1,2 +1,2 @@
-import { AddBlockOptions, AddBlockResult, Block, BlockDefinition, BlockSchema, FileEntry, FileEntrySchema, Registry, RegistryBuildConfig, RegistrySchema } from "../shared/@outfitter/tooling-sjm8nebx";
+import { AddBlockOptions, AddBlockResult, Block, BlockDefinition, BlockSchema, FileEntry, FileEntrySchema, Registry, RegistryBuildConfig, RegistrySchema } from "../shared/@outfitter/tooling-sjm8nebx.js";
 export { RegistrySchema, RegistryBuildConfig, Registry, FileEntrySchema, FileEntry, BlockSchema, BlockDefinition, Block, AddBlockResult, AddBlockOptions };

package/dist/registry/schema.js

@@ -3,7 +3,7 @@ import {
   BlockSchema,
   FileEntrySchema,
   RegistrySchema
-} from "../shared/@outfitter/tooling-g83d0kjv.js";
+} from "../shared/@outfitter/tooling-wv09k6hr.js";
 import"../shared/@outfitter/tooling-dvwh9qve.js";
 export {
   RegistrySchema,

package/dist/shared/@outfitter/{tooling-8sd32ts6.js → tooling-2n2dpsaa.js}

@@ -1,7 +1,13 @@
 // @bun
+import {
+  analyzeSourceFile,
+  calculateCoverage
+} from "./tooling-qk5xgmxr.js";
+
 // packages/tooling/src/cli/pre-push.ts
 import { existsSync, readFileSync } from "fs";
-import { join } from "path";
+import { join, resolve } from "path";
+import ts from "typescript";
 var COLORS = {
   reset: "\x1B[0m",
   red: "\x1B[31m",
@@ -38,6 +44,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__\//,
@@ -57,6 +66,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 = resolve(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(`${COLORS.blue}TSDoc${COLORS.reset}: ${coverage.percentage}% coverage (${parts.join(", ")} of ${coverage.total} total)`);
+}
 function resolveBaseRef() {
   const candidates = [
     "origin/main",
@@ -224,6 +259,11 @@ async function runPrePush(options = {}) {
   log(`${COLORS.blue}Pre-push verify${COLORS.reset} (TDD-aware)`);
   log("");
   const branch = getCurrentBranch();
+  if (isReleaseBranch(branch)) {
+    log(`${COLORS.yellow}Release branch detected${COLORS.reset}: ${COLORS.blue}${branch}${COLORS.reset}`);
+    log(`${COLORS.yellow}Skipping strict verification${COLORS.reset} for automated changeset release push`);
+    process.exit(0);
+  }
   if (isRedPhaseBranch(branch)) {
     if (maybeSkipForRedPhase("branch", branch)) {
       process.exit(0);
@@ -269,9 +309,15 @@ async function runPrePush(options = {}) {
     log("  - feature_tests");
     process.exit(1);
   }
+  const changedFiles = getChangedFilesForPush();
+  if (hasPackageSourceChanges(changedFiles)) {
+    try {
+      await printTsdocSummary();
+    } catch {}
+  }
   log("");
   log(`${COLORS.green}Strict verification passed${COLORS.reset}`);
   process.exit(0);
 }
 
-export { isRedPhaseBranch, isScaffoldBranch, isTestOnlyPath, areFilesTestOnly, canBypassRedPhaseByChangedFiles, createVerificationPlan, runPrePush };
+export { isRedPhaseBranch, isScaffoldBranch, isReleaseBranch, isTestOnlyPath, areFilesTestOnly, canBypassRedPhaseByChangedFiles, hasPackageSourceChanges, createVerificationPlan, runPrePush };

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

@@ -0,0 +1,184 @@
+// @bun
+// packages/tooling/src/cli/check-changeset.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+function getChangedPackagePaths(files) {
+  const packageNames = new Set;
+  const pattern = /^packages\/([^/]+)\/src\//;
+  for (const file of files) {
+    const match = pattern.exec(file);
+    if (match?.[1]) {
+      packageNames.add(match[1]);
+    }
+  }
+  return [...packageNames].sort();
+}
+function getChangedChangesetFiles(files) {
+  const pattern = /^\.changeset\/([^/]+\.md)$/;
+  const results = [];
+  for (const file of files) {
+    const match = pattern.exec(file);
+    if (match?.[1] && match[1] !== "README.md") {
+      results.push(match[1]);
+    }
+  }
+  return results.sort();
+}
+function checkChangesetRequired(changedPackages, changesetFiles) {
+  if (changedPackages.length === 0) {
+    return { ok: true, missingFor: [] };
+  }
+  if (changesetFiles.length > 0) {
+    return { ok: true, missingFor: [] };
+  }
+  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 COLORS = {
+  reset: "\x1B[0m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  dim: "\x1B[2m"
+};
+async function runCheckChangeset(options = {}) {
+  if (options.skip || process.env["NO_CHANGESET"] === "1") {
+    process.stdout.write(`${COLORS.dim}check-changeset skipped (NO_CHANGESET=1)${COLORS.reset}
+`);
+    process.exit(0);
+  }
+  if (process.env["GITHUB_EVENT_NAME"] === "push") {
+    process.stdout.write(`${COLORS.dim}check-changeset skipped (push event)${COLORS.reset}
+`);
+    process.exit(0);
+  }
+  const cwd = process.cwd();
+  let changedFiles;
+  try {
+    const proc = Bun.spawnSync(["git", "diff", "--name-only", "origin/main...HEAD"], { cwd });
+    if (proc.exitCode !== 0) {
+      process.exit(0);
+    }
+    changedFiles = proc.stdout.toString().trim().split(`
+`).filter((line) => line.length > 0);
+  } catch {
+    process.exit(0);
+  }
+  const changedPackages = getChangedPackagePaths(changedFiles);
+  if (changedPackages.length === 0) {
+    process.stdout.write(`${COLORS.green}No package source changes detected.${COLORS.reset}
+`);
+    process.exit(0);
+  }
+  const changesetFiles = getChangedChangesetFiles(changedFiles);
+  const check = checkChangesetRequired(changedPackages, changesetFiles);
+  if (!check.ok) {
+    process.stderr.write(`${COLORS.red}Missing changeset!${COLORS.reset}
+
+`);
+    process.stderr.write(`The following packages have source changes but no changeset:
+
+`);
+    for (const pkg of check.missingFor) {
+      process.stderr.write(`  ${COLORS.yellow}@outfitter/${pkg}${COLORS.reset}
+`);
+    }
+    process.stderr.write(`
+Run ${COLORS.blue}bun run changeset${COLORS.reset} to add a changeset, ` + `or add the ${COLORS.blue}no-changeset${COLORS.reset} label to skip.
+`);
+    process.exit(1);
+  }
+  const ignoredReferences = getIgnoredReferencesForChangedChangesets(cwd, changesetFiles);
+  if (ignoredReferences.length > 0) {
+    process.stderr.write(`${COLORS.red}Invalid changeset package reference(s).${COLORS.reset}
+
+`);
+    process.stderr.write(`Changesets must not reference packages listed in .changeset/config.json ignore:
+
+`);
+    for (const reference of ignoredReferences) {
+      process.stderr.write(`  ${COLORS.yellow}${reference.file}${COLORS.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.stdout.write(`${COLORS.green}Changeset found for ${changedPackages.length} changed package(s).${COLORS.reset}
+`);
+  process.exit(0);
+}
+
+export { getChangedPackagePaths, getChangedChangesetFiles, checkChangesetRequired, parseIgnoredPackagesFromChangesetConfig, parseChangesetFrontmatterPackageNames, findIgnoredPackageReferences, runCheckChangeset };

package/dist/shared/@outfitter/{tooling-tf22zt9p.js → tooling-enjcenja.js}

@@ -141,6 +141,9 @@ var COLORS = {
   blue: "\x1B[34m",
   dim: "\x1B[2m"
 };
+function resolveJsonMode(options = {}) {
+  return options.json ?? process.env["OUTFITTER_JSON"] === "1";
+}
 async function runCheckExports(options = {}) {
   const cwd = process.cwd();
   const configPath = resolve(cwd, "bunup.config.ts");
@@ -183,7 +186,7 @@ async function runCheckExports(options = {}) {
     ok: results.every((r) => r.status === "ok"),
     packages: results
   };
-  if (options.json) {
+  if (resolveJsonMode(options)) {
     process.stdout.write(`${JSON.stringify(checkResult, null, 2)}
 `);
   } else {
@@ -223,4 +226,4 @@ async function runCheckExports(options = {}) {
   process.exit(checkResult.ok ? 0 : 1);
 }
 
-export { entryToSubpath, compareExports, runCheckExports };
+export { entryToSubpath, compareExports, resolveJsonMode, runCheckExports };

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

@@ -0,0 +1,140 @@
+import ts from "typescript";
+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;
+}
+/**
+* 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;
+};
+/** Resolve whether JSON output mode is active. */
+declare function resolveJsonMode(options?: CheckTsDocOptions): boolean;
+/**
+* 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;
+/**
+* Run check-tsdoc across workspace packages.
+*
+* Discovers packages with `src/index.ts` entry points, analyzes TSDoc
+* coverage on exported declarations, and reports per-package statistics.
+* Calls `process.exit()` on completion.
+*/
+declare function runCheckTsdoc(options?: CheckTsDocOptions): Promise<void>;
+export { CoverageLevel, DeclarationCoverage, CoverageSummary, PackageCoverage, TsDocCheckResult, coverageLevelSchema, declarationCoverageSchema, coverageSummarySchema, packageCoverageSchema, tsDocCheckResultSchema, CheckTsDocOptions, isExportedDeclaration, getDeclarationName, getDeclarationKind, classifyDeclaration, analyzeSourceFile, calculateCoverage, resolveJsonMode, analyzeCheckTsdoc, printCheckTsdocHuman, runCheckTsdoc };