@outfitter/tooling 0.2.2 → 0.2.3

package/README.md

@@ -87,6 +87,17 @@ bunx @outfitter/tooling pre-push
 bunx @outfitter/tooling pre-push --force
 ```
 
+### `tooling check-boundary-invocations`
+
+Validate that root/app scripts do not execute `packages/*/src/*` directly.
+
+```bash
+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).
+
 ## Configuration Presets
 
 ### Biome
@@ -151,6 +162,18 @@ Available blocks:
 - `bootstrap` — Project bootstrap script
 - `scaffolding` — Full starter kit (combines all above)
 
+## Monorepo Command Mapping
+
+Within this monorepo, maintenance checks are routed via `outfitter repo`:
+
+```bash
+bun run apps/outfitter/src/cli.ts repo check exports --cwd .
+bun run apps/outfitter/src/cli.ts repo check readme --cwd .
+bun run apps/outfitter/src/cli.ts repo check registry --cwd .
+bun run apps/outfitter/src/cli.ts repo check tree --cwd .
+bun run apps/outfitter/src/cli.ts repo check boundary-invocations --cwd .
+```
+
 ## Exports
 
 | Export | Description |

package/dist/cli/check-boundary-invocations.d.ts

@@ -0,0 +1,34 @@
+interface ScriptLocation {
+	readonly file: string;
+	readonly scriptName: string;
+	readonly command: string;
+}
+interface BoundaryViolation extends ScriptLocation {
+	readonly rule: "root-runs-package-src" | "cd-package-then-runs-src";
+}
+interface ReadScriptEntriesOptions {
+	readonly appManifestRelativePaths?: readonly string[];
+	readonly readPackageJson?: (filePath: string) => Promise<{
+		scripts?: Record<string, string>;
+	}>;
+}
+/**
+* Detect whether a single script command violates boundary invocation rules.
+*/
+declare function detectBoundaryViolation(location: ScriptLocation): BoundaryViolation | null;
+/**
+* Find all boundary violations across package/app script maps.
+*/
+declare function findBoundaryViolations(entries: readonly {
+	file: string;
+	scripts: Readonly<Record<string, string>>;
+}[]): BoundaryViolation[];
+declare function readScriptEntries(cwd: string, options?: ReadScriptEntriesOptions): Promise<{
+	file: string;
+	scripts: Record<string, string>;
+}[]>;
+/**
+* Run boundary invocation checks against root/apps package scripts.
+*/
+declare function runCheckBoundaryInvocations(): Promise<void>;
+export { runCheckBoundaryInvocations, readScriptEntries, findBoundaryViolations, detectBoundaryViolation, ScriptLocation, BoundaryViolation };

package/dist/cli/check-boundary-invocations.js

@@ -0,0 +1,14 @@
+// @bun
+import {
+  detectBoundaryViolation,
+  findBoundaryViolations,
+  readScriptEntries,
+  runCheckBoundaryInvocations
+} from "../shared/@outfitter/tooling-r9976n43.js";
+import"../shared/@outfitter/tooling-dvwh9qve.js";
+export {
+  runCheckBoundaryInvocations,
+  readScriptEntries,
+  findBoundaryViolations,
+  detectBoundaryViolation
+};

package/dist/cli/check-bunup-registry.d.ts

@@ -0,0 +1,36 @@
+/** Result of checking bunup workspace registration */
+interface RegistryCheckResult {
+	readonly ok: boolean;
+	readonly missing: string[];
+}
+/**
+* Extract the package name from a build script containing `bunup --filter`.
+*
+* @example
+* extractBunupFilterName("bunup --filter @outfitter/logging")
+* // => "@outfitter/logging"
+*
+* extractBunupFilterName("cd ../.. && bunup --filter @outfitter/types")
+* // => "@outfitter/types"
+*
+* extractBunupFilterName("tsc --noEmit")
+* // => null
+*/
+declare function extractBunupFilterName(script: string): string | null;
+/**
+* Find packages that have `bunup --filter` build scripts but are not
+* registered in the bunup workspace config.
+*
+* @param packagesWithFilter - Package names that have `bunup --filter` in their build script
+* @param registeredNames - Package names registered in bunup.config.ts
+* @returns Result with sorted list of missing packages
+*/
+declare function findUnregisteredPackages(packagesWithFilter: string[], registeredNames: string[]): RegistryCheckResult;
+/**
+* Run bunup registry check across all workspace packages.
+*
+* Scans packages/*/package.json for build scripts containing `bunup --filter`,
+* then verifies each is registered in bunup.config.ts.
+*/
+declare function runCheckBunupRegistry(): Promise<void>;
+export { runCheckBunupRegistry, findUnregisteredPackages, extractBunupFilterName, RegistryCheckResult };

package/dist/cli/check-bunup-registry.js

@@ -0,0 +1,12 @@
+// @bun
+import {
+  extractBunupFilterName,
+  findUnregisteredPackages,
+  runCheckBunupRegistry
+} from "../shared/@outfitter/tooling-t17gnh9b.js";
+import"../shared/@outfitter/tooling-dvwh9qve.js";
+export {
+  runCheckBunupRegistry,
+  findUnregisteredPackages,
+  extractBunupFilterName
+};

package/dist/cli/check-changeset.d.ts

@@ -0,0 +1,64 @@
+/**
+* Check-changeset command — validates PRs touching package source include a changeset.
+*
+* Pure core functions for detecting changed packages and verifying changeset
+* presence. The CLI runner in {@link runCheckChangeset} handles git discovery
+* and output.
+*
+* @packageDocumentation
+*/
+/** Result of checking whether changesets are required */
+interface ChangesetCheckResult {
+	readonly ok: boolean;
+	readonly missingFor: string[];
+}
+/**
+* Extract unique package names from changed file paths.
+*
+* Only considers files matching the pattern "packages/NAME/src/..." and
+* ignores apps/, root files, and package-level config.
+*
+* @param files - List of changed file paths relative to repo root
+* @returns Sorted array of unique package names
+*/
+declare function getChangedPackagePaths(files: string[]): string[];
+/**
+* Extract changeset filenames from changed file paths.
+*
+* Only considers files matching `.changeset/*.md`, excluding README.md.
+* This checks the git diff rather than disk, ensuring only changesets added
+* in the current PR are counted.
+*
+* @param files - List of changed file paths relative to repo root
+* @returns Array of changeset filenames (e.g. `["happy-turtle.md"]`)
+*/
+declare function getChangedChangesetFiles(files: string[]): string[];
+/**
+* Determine whether a changeset is required and present.
+*
+* Returns `ok: true` when either no packages were changed or at least one
+* changeset file exists. Returns `ok: false` with the list of changed
+* packages when changesets are missing.
+*
+* @param changedPackages - Package names with source changes
+* @param changesetFiles - Changeset filenames found in `.changeset/`
+*/
+declare function checkChangesetRequired(changedPackages: string[], changesetFiles: string[]): ChangesetCheckResult;
+interface CheckChangesetOptions {
+	readonly skip?: boolean;
+}
+/**
+* Run check-changeset to verify PRs include changeset files.
+*
+* Uses `git diff --name-only origin/main...HEAD` to detect changed files,
+* then checks for changeset presence when package source files are modified.
+*
+* Skips silently when:
+* - `NO_CHANGESET=1` env var is set
+* - `--skip` flag is passed
+* - `GITHUB_EVENT_NAME=push` (post-merge on main)
+* - No packages have source changes
+* - Git diff fails (local dev without origin)
+*/
+declare function runCheckChangeset(options?: CheckChangesetOptions): Promise<void>;
+export { runCheckChangeset, getChangedPackagePaths, getChangedChangesetFiles, checkChangesetRequired, CheckChangesetOptions, ChangesetCheckResult };

package/dist/cli/check-changeset.js

@@ -0,0 +1,14 @@
+// @bun
+import {
+  checkChangesetRequired,
+  getChangedChangesetFiles,
+  getChangedPackagePaths,
+  runCheckChangeset
+} from "../shared/@outfitter/tooling-3w8vr2w3.js";
+import"../shared/@outfitter/tooling-dvwh9qve.js";
+export {
+  runCheckChangeset,
+  getChangedPackagePaths,
+  getChangedChangesetFiles,
+  checkChangesetRequired
+};

package/dist/cli/check-clean-tree.d.ts

@@ -0,0 +1,36 @@
+/**
+* Check-clean-tree command — asserts the working tree has no modified or untracked files.
+*
+* Pure core functions for parsing git output and determining tree cleanliness.
+* The CLI runner in {@link runCheckCleanTree} handles git invocation and output.
+*
+* @packageDocumentation
+*/
+/** Status of the working tree after verification steps */
+interface TreeStatus {
+	readonly clean: boolean;
+	readonly modified: string[];
+	readonly untracked: string[];
+}
+/**
+* Parse `git diff --name-only` output into a list of modified file paths.
+*/
+declare function parseGitDiff(diffOutput: string): string[];
+/**
+* Parse `git ls-files --others --exclude-standard` output into a list of untracked file paths.
+*/
+declare function parseUntrackedFiles(lsOutput: string): string[];
+/**
+* Determine if the tree status represents a clean working tree.
+*/
+declare function isCleanTree(status: TreeStatus): boolean;
+interface CheckCleanTreeOptions {
+	readonly paths?: string[];
+}
+/**
+* Run clean-tree check against the current working directory.
+*
+* Exits 0 if clean, 1 if dirty files are found.
+*/
+declare function runCheckCleanTree(options?: CheckCleanTreeOptions): Promise<void>;
+export { runCheckCleanTree, parseUntrackedFiles, parseGitDiff, isCleanTree, TreeStatus, CheckCleanTreeOptions };

package/dist/cli/check-clean-tree.js

@@ -0,0 +1,14 @@
+// @bun
+import {
+  isCleanTree,
+  parseGitDiff,
+  parseUntrackedFiles,
+  runCheckCleanTree
+} from "../shared/@outfitter/tooling-1y8w5ahg.js";
+import"../shared/@outfitter/tooling-dvwh9qve.js";
+export {
+  runCheckCleanTree,
+  parseUntrackedFiles,
+  parseGitDiff,
+  isCleanTree
+};

package/dist/cli/check-exports.d.ts

@@ -0,0 +1,2 @@
+import { CheckExportsOptions, CheckResult, CompareInput, ExportDrift, ExportMap, PackageResult, compareExports, entryToSubpath, runCheckExports } from "../shared/@outfitter/tooling-q0d60xb3";
+export { runCheckExports, entryToSubpath, compareExports, PackageResult, ExportMap, ExportDrift, CompareInput, CheckResult, CheckExportsOptions };

package/dist/cli/check-exports.js

@@ -0,0 +1,12 @@
+// @bun
+import {
+  compareExports,
+  entryToSubpath,
+  runCheckExports
+} from "../shared/@outfitter/tooling-tf22zt9p.js";
+import"../shared/@outfitter/tooling-dvwh9qve.js";
+export {
+  runCheckExports,
+  entryToSubpath,
+  compareExports
+};

package/dist/cli/check-readme-imports.d.ts

@@ -0,0 +1,60 @@
+import { ExportMap } from "../shared/@outfitter/tooling-q0d60xb3";
+/** An import example extracted from a markdown code block */
+interface ImportExample {
+	/** Package name, e.g. "@outfitter/cli" */
+	readonly packageName: string;
+	/** Export subpath, e.g. "./output" or "." */
+	readonly subpath: string;
+	/** Full import specifier, e.g. "@outfitter/cli/output" */
+	readonly fullSpecifier: string;
+	/** File where the import was found */
+	readonly file: string;
+	/** 1-based line number */
+	readonly line: number;
+}
+/** Result of checking imports in a single file */
+interface ImportCheckResult {
+	readonly file: string;
+	readonly valid: ImportExample[];
+	readonly invalid: ImportExample[];
+}
+/**
+* Parse a full import specifier into package name and subpath.
+*
+* Only recognizes `@outfitter/*` scoped packages.
+*
+* @example
+* parseSpecifier("@outfitter/cli/output")
+* // { packageName: "@outfitter/cli", subpath: "./output" }
+*
+* parseSpecifier("@outfitter/contracts")
+* // { packageName: "@outfitter/contracts", subpath: "." }
+*/
+declare function parseSpecifier(specifier: string): {
+	packageName: string;
+	subpath: string;
+} | null;
+/**
+* Extract import specifiers from markdown content.
+*
+* Only extracts imports from fenced code blocks (typescript, ts,
+* javascript, js). Skips blocks preceded by a non-contractual HTML comment.
+* Deduplicates by full specifier within a single file.
+*/
+declare function extractImports(content: string, file: string): ImportExample[];
+/**
+* Check whether a subpath exists in a package.json map.
+*/
+declare function isExportedSubpath(subpath: string, exports: ExportMap): boolean;
+interface CheckReadmeImportsOptions {
+	readonly json?: boolean;
+}
+/**
+* Run check-readme-imports across all workspace packages.
+*
+* Finds README.md files in `packages/` and `docs/packages/`, extracts
+* import examples, and validates each subpath against the corresponding
+* package.json exports.
+*/
+declare function runCheckReadmeImports(options?: CheckReadmeImportsOptions): Promise<void>;
+export { runCheckReadmeImports, parseSpecifier, isExportedSubpath, extractImports, ImportExample, ImportCheckResult, ExportMap, CheckReadmeImportsOptions };

package/dist/cli/check-readme-imports.js

@@ -0,0 +1,194 @@
+// @bun
+import"../shared/@outfitter/tooling-dvwh9qve.js";
+
+// packages/tooling/src/cli/check-readme-imports.ts
+import { resolve } from "path";
+function parseSpecifier(specifier) {
+  if (!specifier.startsWith("@outfitter/")) {
+    return null;
+  }
+  const parts = specifier.split("/");
+  if (parts.length < 2) {
+    return null;
+  }
+  const packageName = `${parts[0]}/${parts[1]}`;
+  const rest = parts.slice(2);
+  if (rest.length === 0) {
+    return { packageName, subpath: "." };
+  }
+  return { packageName, subpath: `./${rest.join("/")}` };
+}
+function extractImports(content, file) {
+  const lines = content.split(`
+`);
+  const results = [];
+  const seen = new Set;
+  const CODE_FENCE_OPEN = /^```(?:typescript|ts|javascript|js)\s*$/;
+  const CODE_FENCE_CLOSE = /^```\s*$/;
+  const IMPORT_RE = /from\s+["'](@outfitter\/[^"']+)["']/;
+  const NON_CONTRACTUAL = /<!--\s*non-contractual\s*-->/;
+  let inCodeBlock = false;
+  let skipBlock = false;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (!inCodeBlock) {
+      if (CODE_FENCE_OPEN.test(line)) {
+        inCodeBlock = true;
+        skipBlock = false;
+        for (let j = i - 1;j >= 0; j--) {
+          const prev = lines[j].trim();
+          if (prev === "")
+            continue;
+          if (NON_CONTRACTUAL.test(prev)) {
+            skipBlock = true;
+          }
+          break;
+        }
+      }
+      continue;
+    }
+    if (CODE_FENCE_CLOSE.test(line) && !CODE_FENCE_OPEN.test(line)) {
+      inCodeBlock = false;
+      skipBlock = false;
+      continue;
+    }
+    if (skipBlock)
+      continue;
+    const match = IMPORT_RE.exec(line);
+    if (!match?.[1])
+      continue;
+    const fullSpecifier = match[1];
+    if (seen.has(fullSpecifier))
+      continue;
+    seen.add(fullSpecifier);
+    const parsed = parseSpecifier(fullSpecifier);
+    if (!parsed)
+      continue;
+    results.push({
+      packageName: parsed.packageName,
+      subpath: parsed.subpath,
+      fullSpecifier,
+      file,
+      line: i + 1
+    });
+  }
+  return results;
+}
+function isExportedSubpath(subpath, exports) {
+  return subpath in exports;
+}
+var COLORS = {
+  reset: "\x1B[0m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  dim: "\x1B[2m"
+};
+async function runCheckReadmeImports(options = {}) {
+  const cwd = process.cwd();
+  const readmeGlob = new Bun.Glob("**/README.md");
+  const readmeDirs = ["packages", "docs/packages"];
+  const readmePaths = [];
+  for (const dir of readmeDirs) {
+    const fullDir = resolve(cwd, dir);
+    try {
+      for (const match of readmeGlob.scanSync({ cwd: fullDir, dot: false })) {
+        const segments = match.split("/");
+        if (segments.length === 2 && segments[1] === "README.md") {
+          readmePaths.push(resolve(fullDir, match));
+        }
+      }
+    } catch {}
+  }
+  if (readmePaths.length === 0) {
+    process.stdout.write(`No README.md files found.
+`);
+    return;
+  }
+  const exportsCache = new Map;
+  async function getExportsForPackage(packageName) {
+    if (exportsCache.has(packageName)) {
+      return exportsCache.get(packageName) ?? null;
+    }
+    const shortName = packageName.replace("@outfitter/", "");
+    const pkgPath = resolve(cwd, "packages", shortName, "package.json");
+    try {
+      const pkg = await Bun.file(pkgPath).json();
+      const exports = typeof pkg.exports === "object" && pkg.exports !== null ? pkg.exports : {};
+      exportsCache.set(packageName, exports);
+      return exports;
+    } catch {
+      return null;
+    }
+  }
+  const results = [];
+  let hasInvalid = false;
+  for (const readmePath of readmePaths.sort()) {
+    const content = await Bun.file(readmePath).text();
+    const relativePath = readmePath.replace(`${cwd}/`, "");
+    const imports = extractImports(content, relativePath);
+    if (imports.length === 0)
+      continue;
+    const valid = [];
+    const invalid = [];
+    for (const imp of imports) {
+      const exports = await getExportsForPackage(imp.packageName);
+      if (exports === null) {
+        invalid.push(imp);
+        continue;
+      }
+      if (isExportedSubpath(imp.subpath, exports)) {
+        valid.push(imp);
+      } else {
+        invalid.push(imp);
+      }
+    }
+    if (valid.length > 0 || invalid.length > 0) {
+      results.push({ file: relativePath, valid, invalid });
+    }
+    if (invalid.length > 0) {
+      hasInvalid = true;
+    }
+  }
+  if (options.json) {
+    const output = {
+      ok: !hasInvalid,
+      files: results
+    };
+    process.stdout.write(`${JSON.stringify(output, null, 2)}
+`);
+  } else {
+    const totalValid = results.reduce((n, r) => n + r.valid.length, 0);
+    const totalInvalid = results.reduce((n, r) => n + r.invalid.length, 0);
+    if (!hasInvalid) {
+      process.stdout.write(`${COLORS.green}All ${totalValid} README import examples match package exports.${COLORS.reset}
+`);
+    } else {
+      process.stderr.write(`${COLORS.red}Invalid README import examples found:${COLORS.reset}
+
+`);
+      for (const result of results) {
+        if (result.invalid.length === 0)
+          continue;
+        process.stderr.write(`  ${COLORS.yellow}${result.file}${COLORS.reset}
+`);
+        for (const imp of result.invalid) {
+          process.stderr.write(`    ${COLORS.red}line ${imp.line}:${COLORS.reset} ${imp.fullSpecifier}  ${COLORS.dim}(subpath ${imp.subpath} not in ${imp.packageName} exports)${COLORS.reset}
+`);
+        }
+        process.stderr.write(`
+`);
+      }
+      process.stderr.write(`${totalInvalid} invalid, ${totalValid} valid across ${results.length} file(s).
+`);
+    }
+  }
+  process.exit(hasInvalid ? 1 : 0);
+}
+export {
+  runCheckReadmeImports,
+  parseSpecifier,
+  isExportedSubpath,
+  extractImports
+};

package/dist/cli/check.js

@@ -3,6 +3,7 @@ import {
   buildCheckCommand,
   runCheck
 } from "../shared/@outfitter/tooling-0x5q15ec.js";
+import"../shared/@outfitter/tooling-dvwh9qve.js";
 export {
   runCheck,
   buildCheckCommand

package/dist/cli/fix.js

@@ -3,6 +3,7 @@ import {
   buildFixCommand,
   runFix
 } from "../shared/@outfitter/tooling-9errkcvk.js";
+import"../shared/@outfitter/tooling-dvwh9qve.js";
 export {
   runFix,
   buildFixCommand