@savvy-web/lint-staged 0.8.0 → 1.0.0

package/index.d.ts

@@ -56,10 +56,10 @@ export declare interface BaseHandlerOptions {
  * 2. Local installation via `pnpm exec biome`
  * 3. Local installation via `npx biome`
  *
- * Config file discovery order:
- * 1. Explicit `config` option if provided
- * 2. `lib/configs/biome.jsonc` or `lib/configs/biome.json`
- * 3. Standard locations (`biome.jsonc` or `biome.json` at repo root)
+ * Config file discovery:
+ * - Searches the workspace root for `biome.jsonc` or `biome.json`.
+ * - Falls back to CWD when not in a workspace.
+ * - No `lib/configs/` convention — biome configs live at workspace roots only.
  *
  * @throws Error if Biome is not available (globally or locally)
  *
@@ -90,6 +90,8 @@ export declare class Biome {
      * @defaultValue `['package.json', 'package-lock.json', '__fixtures__', '__test__/fixtures']`
      */
     static readonly defaultExcludes: readonly ["package.json", "package-lock.json", "__fixtures__", "__test__/fixtures"];
+    /** Candidate config file names in preference order. */
+    private static readonly CONFIG_NAMES;
     /**
      * Pre-configured handler with default options.
      * Auto-discovers biome command and config file location.
@@ -113,15 +115,31 @@ export declare class Biome {
      */
     static isAvailable(): boolean;
     /**
-     * Find the Biome config file.
+     * Find the Biome config file at the workspace root.
      *
-     * Searches in order:
-     * 1. `lib/configs/` directory
-     * 2. Standard locations (repo root)
+     * @remarks
+     * Searches the workspace root directory for `biome.jsonc` then `biome.json`.
+     * Falls back to CWD when not running inside a workspace. The `lib/configs/`
+     * convention is not used — biome configs are expected at workspace roots only.
      *
-     * @returns The config file path, or undefined if not found
+     * @returns Absolute path to the config file, or undefined if not found
      */
     static findConfig(): string | undefined;
+    /**
+     * Find all Biome config files across workspace roots.
+     *
+     * @remarks
+     * Searches the workspace root and each leaf workspace root for a
+     * `biome.jsonc` or `biome.json` config file. At most one config is
+     * collected per directory (the first match in preference order).
+     * Falls back to CWD when not running inside a workspace.
+     *
+     * This method is intended for the CLI check command, which validates
+     * `$schema` URLs across all workspace biome configs.
+     *
+     * @returns Array of absolute config file paths (may be empty)
+     */
+    static findAllConfigs(): string[];
     /**
      * Create a handler with custom options.
      *
@@ -153,7 +171,7 @@ export declare interface BiomeOptions extends BaseHandlerOptions {
  * Validates the current lint-staged setup and displays detected settings.
  * With --quiet flag, only outputs warnings (for postinstall usage).
  */
-export declare const checkCommand: Command_2.Command<"check", BiomeSchemaSync | ConfigDiscovery | FileSystem.FileSystem | ManagedSection | ToolDiscovery, JsoncParseError | SectionParseError | PlatformError, {
+export declare const checkCommand: Command_2.Command<"check", ConfigDiscovery | FileSystem.FileSystem | ManagedSection | ToolDiscovery, JsoncParseError | SectionParseError | PlatformError, {
     readonly quiet: boolean;
 }>;
 
@@ -374,84 +392,6 @@ export declare interface CreateConfigOptions {
     custom?: LintStagedConfig;
 }
 
-/**
- * Result of entry extraction.
- */
-export declare interface EntryExtractionResult {
-    /**
-     * Map of export path to resolved TypeScript file path.
-     * Keys are export names (e.g., ".", "./utils"), values are file paths.
-     */
-    entries: Record<string, string>;
-    /**
-     * Export paths that couldn't be resolved to TypeScript files.
-     */
-    unresolved: string[];
-}
-
-/**
- * Extracts TypeScript entry points from package.json exports field.
- *
- * @remarks
- * Parses the `exports` field of a package.json to find all TypeScript
- * source files that are part of the public API. Handles various export
- * formats including string, object with conditions, and nested exports.
- *
- * @example
- * ```typescript
- * import type { EntryExtractionResult } from '@savvy-web/lint-staged';
- * import { EntryExtractor } from '@savvy-web/lint-staged';
- *
- * const extractor = new EntryExtractor();
- * const packageJson = {
- *   exports: {
- *     ".": "./src/index.ts",
- *     "./utils": "./src/utils/index.ts"
- *   }
- * };
- * const result: EntryExtractionResult = extractor.extract(packageJson);
- * // result.entries = { ".": "./src/index.ts", "./utils": "./src/utils/index.ts" }
- * ```
- */
-export declare class EntryExtractor {
-    /**
-     * Extract TypeScript entry points from package.json.
-     *
-     * @param packageJson - Parsed package.json object
-     * @returns Extraction result with entries and unresolved paths
-     */
-    extract(packageJson: {
-        exports?: ExportsField;
-        main?: string;
-        module?: string;
-    }): EntryExtractionResult;
-    /**
-     * Recursively extract entries from an exports object.
-     */
-    private extractFromObject;
-    /**
-     * Find a TypeScript file from condition exports.
-     * Looks for: source, types, typescript, development, default
-     */
-    private findTypeScriptCondition;
-    /**
-     * Find source path from conditions, even if not TypeScript.
-     */
-    private findSourceCondition;
-    /**
-     * Check if a path is a TypeScript file.
-     */
-    private isTypeScriptFile;
-}
-
-/**
- * Extracts TypeScript entry points from package.json exports.
- */
-/**
- * Shape of package.json exports field.
- */
-export declare type ExportsField = string | Record<string, unknown> | null;
-
 /**
  * Utilities for filtering staged file lists.
  *
@@ -548,6 +488,27 @@ export declare const fmtCommand: Command_2.Command<"fmt", never, never, {
     }>;
 }>;
 
+/**
+ * Get absolute paths of all leaf workspace package directories.
+ *
+ * @returns Array of absolute paths, empty if not in a workspace
+ */
+export declare function getWorkspacePackagePaths(): string[];
+
+/**
+ * Get all leaf workspace packages (excludes root).
+ *
+ * @returns Array of workspace packages, or null if not in a workspace
+ */
+export declare function getWorkspacePackages(): WorkspacePackageInfo[] | null;
+
+/**
+ * Get the workspace root directory.
+ *
+ * @returns Absolute path to workspace root, or null if not in a workspace
+ */
+export declare function getWorkspaceRoot(): string | null;
+
 /**
  * Abstract base class for lint-staged handlers.
  *
@@ -581,152 +542,6 @@ export declare abstract class Handler {
     static create(_options?: BaseHandlerOptions): LintStagedHandler;
 }
 
-/**
- * Analyzes TypeScript import relationships to discover all files
- * reachable from specified entry points.
- *
- * @remarks
- * This class uses the TypeScript compiler API to trace import statements
- * and discover all files that are part of the public API. It handles:
- *
- * - Static imports: `import \{ foo \} from "./module"`
- * - Dynamic imports: `import("./module")`
- * - Re-exports: `export * from "./module"` and `export \{ foo \} from "./module"`
- * - Circular imports (via visited set tracking)
- *
- * The class automatically filters out:
- * - Files in node_modules
- * - Declaration files (.d.ts)
- * - Test files (*.test.ts, *.spec.ts)
- * - Files in __test__ directories
- *
- * @example
- * ```typescript
- * import type { ImportGraphOptions } from '@savvy-web/lint-staged';
- * import { ImportGraph } from '@savvy-web/lint-staged';
- *
- * const options: ImportGraphOptions = { rootDir: process.cwd() };
- * const graph = new ImportGraph(options);
- * const result = graph.traceFromPackageExports('./package.json');
- * console.log('Public API files:', result.files);
- * ```
- */
-export declare class ImportGraph {
-    private readonly options;
-    private program;
-    private compilerOptions;
-    private moduleResolutionCache;
-    constructor(options: ImportGraphOptions);
-    /**
-     * Trace all imports from the given entry points.
-     *
-     * @param entryPaths - Paths to entry files (relative to rootDir or absolute)
-     * @returns Deduplicated list of all reachable TypeScript files
-     */
-    traceFromEntries(entryPaths: string[]): ImportGraphResult;
-    /**
-     * Trace imports from package.json exports.
-     *
-     * @param packageJsonPath - Path to package.json (relative to rootDir or absolute)
-     * @returns Deduplicated list of all reachable TypeScript files
-     */
-    traceFromPackageExports(packageJsonPath: string): ImportGraphResult;
-    /**
-     * Initialize the TypeScript program for module resolution.
-     */
-    private initializeProgram;
-    /**
-     * Find tsconfig.json path.
-     */
-    private findTsConfig;
-    /**
-     * Resolve entry path to absolute path.
-     */
-    private resolveEntryPath;
-    /**
-     * Recursively trace imports from a source file.
-     */
-    private traceImports;
-    /**
-     * Extract all import/export module specifiers from a source file.
-     */
-    private extractImports;
-    /**
-     * Resolve a module specifier to an absolute file path.
-     */
-    private resolveImport;
-    /**
-     * Check if a path is an external module (node_modules).
-     */
-    private isExternalModule;
-    /**
-     * Check if a file should be included in results.
-     * Filters out test files and non-TypeScript files.
-     */
-    private isSourceFile;
-    /**
-     * Traces TypeScript imports from entry points.
-     *
-     * @param entryPaths - Paths to entry files (relative to rootDir or absolute)
-     * @param options - Import graph configuration options
-     * @returns All TypeScript files reachable from the entries
-     */
-    static fromEntries(entryPaths: string[], options: ImportGraphOptions): ImportGraphResult;
-    /**
-     * Traces TypeScript imports from package.json exports.
-     *
-     * @param packageJsonPath - Path to package.json (relative to rootDir or absolute)
-     * @param options - Import graph configuration options
-     * @returns All TypeScript files reachable from the package exports
-     */
-    static fromPackageExports(packageJsonPath: string, options: ImportGraphOptions): ImportGraphResult;
-}
-
-/**
- * Structured error from import graph analysis.
- */
-export declare interface ImportGraphError {
-    /** The type of error that occurred. */
-    type: ImportGraphErrorType;
-    /** Human-readable error message. */
-    message: string;
-    /** The file path related to the error, if applicable. */
-    path?: string;
-}
-
-/**
- * Analyzes TypeScript import relationships to discover all files
- * reachable from specified entry points.
- */
-/**
- * Types of errors that can occur during import graph analysis.
- */
-export declare type ImportGraphErrorType = "tsconfig_not_found" | "tsconfig_read_error" | "tsconfig_parse_error" | "package_json_not_found" | "package_json_parse_error" | "entry_not_found" | "file_read_error";
-
-/**
- * Options for configuring the ImportGraph analyzer.
- */
-export declare interface ImportGraphOptions {
-    /** The project root directory. */
-    rootDir: string;
-    /** Custom path to the TypeScript configuration file. */
-    tsconfigPath?: string;
-    /** Additional patterns to exclude from results. */
-    excludePatterns?: string[];
-}
-
-/**
- * Result of import graph analysis.
- */
-export declare interface ImportGraphResult {
-    /** All TypeScript source files reachable from the entry points. */
-    files: string[];
-    /** The entry points that were traced. */
-    entries: string[];
-    /** Errors encountered during import graph analysis. */
-    errors: ImportGraphError[];
-}
-
 /**
  * Init command implementation.
  *
@@ -746,6 +561,20 @@ export declare const initCommand: Command_2.Command<"init", BiomeSchemaSync | Fi
     readonly preset: "minimal" | "silk" | "standard";
 }>;
 
+/**
+ * Check if a file path is at a workspace root or leaf workspace root.
+ *
+ * @remarks
+ * Compares the file's parent directory against the workspace root
+ * and all leaf workspace roots. Returns true as a permissive
+ * fallback when not in a workspace, so single-package repos
+ * continue to work.
+ *
+ * @param filePath - Absolute path to the file
+ * @returns true if the file is at a workspace or leaf root
+ */
+export declare function isWorkspacePackagePath(filePath: string): boolean;
+
 /**
  * A lint-staged configuration object.
  * Maps glob patterns to handlers, commands, or arrays of sequential steps.
@@ -836,9 +665,12 @@ export declare class Markdown {
     /**
      * Find the markdownlint config file.
      *
+     * Paths are anchored to the workspace root (via {@link getWorkspaceRoot}),
+     * falling back to `process.cwd()` when not inside a workspace.
+     *
      * Searches in order:
-     * 1. `lib/configs/` directory
-     * 2. Standard locations (repo root)
+     * 1. `{workspaceRoot}/lib/configs/` directory
+     * 2. `{workspaceRoot}/` (repo root)
      *
      * @returns The config file path, or undefined if not found
      */
@@ -905,6 +737,19 @@ export declare class PackageJson {
      * Pre-configured handler with default options.
      */
     static readonly handler: LintStagedHandler;
+    /**
+     * Filter filenames to workspace roots only.
+     *
+     * @remarks
+     * Applies exclude patterns first (for backward compatibility with custom
+     * excludes), then filters to workspace root and leaf workspace roots only.
+     * Falls back permissively when not in a workspace.
+     *
+     * @param filenames - Incoming file list from lint-staged
+     * @param excludes - Patterns to exclude before workspace filtering
+     * @returns Filtered list of files at workspace roots
+     */
+    private static filterToWorkspaceRoots;
     /**
      * Create a handler with custom options.
      *
@@ -1204,6 +1049,14 @@ export declare type PresetExtendOptions = CreateConfigOptions;
  */
 export declare type PresetType = "minimal" | "standard" | "silk";
 
+/**
+ * Clear all cached workspace data.
+ *
+ * @remarks
+ * Call this in test teardown to ensure clean state between tests.
+ */
+export declare function resetWorkspaceCache(): void;
+
 /** Root command for the CLI with all subcommands. */
 export declare const rootCommand: Command_2.Command<"savvy-lint", BiomeSchemaSync | ConfigDiscovery | FileSystem_2 | ManagedSection | ToolDiscovery, Error | JsoncModificationError | JsoncParseError | SectionParseError | SectionWriteError | PlatformError, {
     readonly subcommand: Option<    {
@@ -1299,262 +1152,28 @@ export declare interface ToolSearchResult {
     source: "global" | PackageManager | undefined;
 }
 
-/**
- * TSDoc linter using ESLint with bundled configuration.
- *
- * @remarks
- * This class provides programmatic TSDoc linting using ESLint's Node.js API.
- * It bundles the required ESLint configuration internally, so consumers
- * don't need to configure ESLint themselves.
- *
- * The linter checks for TSDoc syntax errors using the `eslint-plugin-tsdoc` plugin.
- *
- * @example
- * ```typescript
- * import type { TsDocLintResult } from '@savvy-web/lint-staged';
- * import { TsDocLinter } from '@savvy-web/lint-staged';
- *
- * const linter = new TsDocLinter();
- * const results: TsDocLintResult[] = await linter.lintFiles(['src/index.ts', 'src/utils.ts']);
- *
- * for (const result of results) {
- *   if (result.errorCount > 0) {
- *     console.log(`${result.filePath}: ${result.errorCount} errors`);
- *   }
- * }
- * ```
- */
-export declare class TsDocLinter {
-    private readonly eslint;
-    constructor(options?: TsDocLinterOptions);
-    /**
-     * Lint files for TSDoc issues.
-     *
-     * @param filePaths - Array of absolute file paths to lint
-     * @returns Array of lint results
-     */
-    lintFiles(filePaths: string[]): Promise<TsDocLintResult[]>;
-    /**
-     * Lint files and throw if any errors are found.
-     *
-     * @param filePaths - Array of absolute file paths to lint
-     * @throws Error if any TSDoc errors are found
-     */
-    lintFilesAndThrow(filePaths: string[]): Promise<void>;
-    /**
-     * Format lint results as a human-readable string.
-     *
-     * @param results - Array of lint results
-     * @returns Formatted string output
-     */
-    static formatResults(results: TsDocLintResult[]): string;
-    /**
-     * Check if there are any errors in the results.
-     *
-     * @param results - Array of lint results
-     * @returns True if any errors were found
-     */
-    static hasErrors(results: TsDocLintResult[]): boolean;
-}
-
-/**
- * Options for TsDocLinter.
- */
-export declare interface TsDocLinterOptions {
-    /** Additional patterns to ignore */
-    ignorePatterns?: string[];
-}
-
-/**
- * A single lint message.
- */
-export declare interface TsDocLintMessage {
-    /** Line number (1-indexed) */
-    line: number;
-    /** Column number (1-indexed) */
-    column: number;
-    /** Severity: 1 = warning, 2 = error */
-    severity: 1 | 2;
-    /** The error/warning message */
-    message: string;
-    /** The rule that triggered this message */
-    ruleId: string | null;
-}
-
-/**
- * TSDoc linter using ESLint with bundled configuration.
- */
-/**
- * Result of linting a file for TSDoc issues.
- */
-export declare interface TsDocLintResult {
-    /** Absolute path to the file */
-    filePath: string;
-    /** Number of errors found */
-    errorCount: number;
-    /** Number of warnings found */
-    warningCount: number;
-    /** Individual messages */
-    messages: TsDocLintMessage[];
-}
-
-/**
- * Resolves files for TSDoc linting based on workspace configuration.
- *
- * @remarks
- * This class handles both single-package repos and monorepos. It detects
- * workspaces from pnpm-workspace.yaml or package.json and checks for `tsdoc.json`
- * configuration files to determine which packages need TSDoc linting.
- *
- * A workspace is enabled for TSDoc linting if:
- * 1. The workspace has a `tsdoc.json` file in its root, OR
- * 2. The repo has a `tsdoc.json` file at its root
- *
- * For enabled workspaces, the resolver:
- * 1. Extracts entry points from the package.json `exports` field
- * 2. Traces imports from those entries using ImportGraph
- * 3. Returns all public API files for linting
- *
- * @example
- * ```typescript
- * import type { TsDocResolverOptions } from '@savvy-web/lint-staged';
- * import { TsDocResolver } from '@savvy-web/lint-staged';
- *
- * const options: TsDocResolverOptions = { rootDir: process.cwd() };
- * const resolver = new TsDocResolver(options);
- * const result = resolver.resolve();
- *
- * for (const workspace of result.workspaces) {
- *   console.log(`${workspace.name}: ${workspace.files.length} files to lint`);
- * }
- * ```
- */
-export declare class TsDocResolver {
-    private readonly options;
-    constructor(options: TsDocResolverOptions);
-    /**
-     * Resolve all files that need TSDoc linting.
-     *
-     * @returns Resolution result with workspaces and their files
-     */
-    resolve(): TsDocResolverResult;
-    /**
-     * Resolve files for a single workspace.
-     *
-     * @param workspacePath - Path to the workspace root
-     * @param repoTsdocConfig - Path to repo-level tsdoc.json if present
-     * @returns Workspace info if enabled for TSDoc, null otherwise
-     */
-    private resolveWorkspace;
-    /**
-     * Filter staged files to only those that need TSDoc linting.
-     *
-     * @param stagedFiles - Array of staged file paths (absolute)
-     * @returns Files that are in workspaces enabled for TSDoc and are public API files
-     */
-    filterStagedFiles(stagedFiles: string[]): {
-        files: string[];
-        tsdocConfigPath: string;
-    }[];
-    /**
-     * Check if a specific file needs TSDoc linting.
-     *
-     * @param filePath - Absolute path to the file
-     * @returns True if the file is in a workspace enabled for TSDoc and is a public API file
-     */
-    needsLinting(filePath: string): boolean;
-    /**
-     * Get the tsdoc.json config path for a specific file.
-     *
-     * @param filePath - Absolute path to the file
-     * @returns Path to tsdoc.json if the file needs linting, undefined otherwise
-     */
-    getTsDocConfig(filePath: string): string | undefined;
-    /**
-     * Find the workspace that contains a file.
-     *
-     * @param filePath - Absolute path to the file
-     * @returns Workspace info if found, undefined otherwise
-     */
-    findWorkspace(filePath: string): TsDocWorkspace | undefined;
-}
-
-/**
- * Options for TsDocResolver.
- */
-export declare interface TsDocResolverOptions {
-    /** The repository root directory */
-    rootDir: string;
-    /** Custom exclude patterns for import graph analysis */
-    excludePatterns?: string[];
-}
-
-/**
- * Result of resolving TSDoc files.
- */
-export declare interface TsDocResolverResult {
-    /** Workspaces that are enabled for TSDoc linting */
-    workspaces: TsDocWorkspace[];
-    /** Whether this is a monorepo */
-    isMonorepo: boolean;
-    /** Path to repo-level tsdoc.json if present */
-    repoTsdocConfig?: string;
-}
-
-/**
- * Resolves files for TSDoc linting based on workspace configuration.
- */
-/**
- * Information about a workspace enabled for TSDoc linting.
- */
-export declare interface TsDocWorkspace {
-    /** Workspace name from package.json */
-    name: string;
-    /** Absolute path to the workspace root */
-    path: string;
-    /** Path to the tsdoc.json config (workspace-level or repo-level) */
-    tsdocConfigPath: string;
-    /** Files to lint (absolute paths) */
-    files: string[];
-    /** Errors encountered during resolution */
-    errors: string[];
-}
-
 /**
  * Handler for TypeScript files.
  *
- * Validates TSDoc syntax with ESLint and runs type checking.
+ * Runs type checking with tsgo or tsc.
  *
  * @remarks
- * TSDoc validation uses intelligent file discovery based on workspace
- * configuration:
- *
- * 1. Detects workspaces using the npm/pnpm/yarn workspace protocol
- * 2. A workspace is enabled for TSDoc if it has `tsdoc.json` or the repo root has one
- * 3. For enabled workspaces, extracts entry points from `package.json` exports
- * 4. Traces imports from entries to find all public API files
- * 5. Only lints files that are part of the public API
- *
- * This ensures that:
- * - Only documented public API files are linted
- * - Internal implementation files are skipped
- * - Test files and fixtures are automatically excluded
- *
  * Type checking runs on all staged TypeScript files using the configured
- * compiler (tsgo or tsc).
+ * compiler (tsgo or tsc). The compiler is auto-detected at runtime using
+ * `Command.findTool()`, which correctly handles pnpm catalogs, peer
+ * dependencies, and hoisted/transitive deps.
  *
  * @example
  * ```typescript
  * import { TypeScript } from '\@savvy-web/lint-staged';
  *
  * export default {
- *   // Auto-discovers workspaces and lints public API files
+ *   // Auto-detects compiler and runs type checking
  *   [TypeScript.glob]: TypeScript.handler,
  *
  *   // Or explicit config
  *   [TypeScript.glob]: TypeScript.create({
  *     skipTypecheck: true,
- *     skipTsdoc: false,
  *   }),
  * };
  * ```
@@ -1570,11 +1189,6 @@ export declare class TypeScript {
      * @defaultValue `[]`
      */
     static readonly defaultExcludes: readonly [];
-    /**
-     * Default patterns to exclude from TSDoc linting.
-     * @defaultValue `['.test.', '.spec.', '__test__', '__tests__']`
-     */
-    static readonly defaultTsdocExcludes: readonly [".test.", ".spec.", "__test__", "__tests__"];
     /** Cached compiler detection result */
     private static cachedCompilerResult;
     /**
@@ -1617,20 +1231,8 @@ export declare class TypeScript {
     static clearCache(): void;
     /**
      * Pre-configured handler with default options.
-     * Auto-discovers workspaces for TSDoc linting.
      */
     static readonly handler: LintStagedHandler;
-    /**
-     * Check if TSDoc linting is available for the repository.
-     *
-     * TSDoc linting requires:
-     * 1. A `tsdoc.json` file at repo root or workspace level
-     * 2. Package(s) with `exports` field in package.json
-     *
-     * @param cwd - Directory to search from (defaults to process.cwd())
-     * @returns `true` if TSDoc linting can be performed
-     */
-    static isTsdocAvailable(cwd?: string): boolean;
     /**
      * Create a handler with custom options.
      *
@@ -1649,17 +1251,6 @@ export declare type TypeScriptCompiler = "tsgo" | "tsc";
  * Options for the TypeScript handler.
  */
 export declare interface TypeScriptOptions extends BaseHandlerOptions {
-    /**
-     * Additional patterns to exclude from TSDoc linting.
-     * These are in addition to the default test file exclusions.
-     * @defaultValue ['.test.', '.spec.', '__test__', '__tests__']
-     */
-    excludeTsdoc?: string[];
-    /**
-     * Skip TSDoc validation.
-     * @defaultValue false
-     */
-    skipTsdoc?: boolean;
     /**
      * Skip type checking.
      * @defaultValue false
@@ -1667,15 +1258,30 @@ export declare interface TypeScriptOptions extends BaseHandlerOptions {
     skipTypecheck?: boolean;
     /**
      * Command for type checking.
-     * @defaultValue Auto-detected based on package manager and compiler
+     * @defaultValue Auto-detected
      */
     typecheckCommand?: string;
-    /**
-     * Root directory for workspace detection.
-     * Used to find workspaces and tsdoc.json configuration.
-     * @defaultValue process.cwd()
-     */
-    rootDir?: string;
+}
+
+/**
+ * Workspace-aware discovery utilities.
+ *
+ * @remarks
+ * Wraps the synchronous APIs from `workspaces-effect` with caching.
+ * Workspace layout does not change during a lint-staged run, so
+ * results are cached on first access. Use `resetWorkspaceCache()`
+ * in tests to clear state between runs.
+ */
+/**
+ * Minimal shape of a workspace package needed by this module.
+ *
+ * @remarks
+ * Avoids importing the full WorkspacePackage Schema.Class from
+ * workspaces-effect, keeping the sync boundary clean.
+ */
+export declare interface WorkspacePackageInfo {
+    readonly name: string;
+    readonly path: string;
 }
 
 /**
@@ -1719,9 +1325,12 @@ export declare class Yaml {
     /**
      * Find the yaml-lint config file.
      *
+     * Paths are anchored to the workspace root (via {@link getWorkspaceRoot}),
+     * falling back to `process.cwd()` when not inside a workspace.
+     *
      * Searches in order:
-     * 1. `lib/configs/` directory
-     * 2. Standard locations (repo root)
+     * 1. `{workspaceRoot}/lib/configs/.yaml-lint.json`
+     * 2. `{workspaceRoot}/.yaml-lint.json`
      *
      * @returns The config file path, or undefined if not found
      */