/**
 * TokenTaxonomy — Organize and classify design tokens
 *
 * Parses token files and classifies tokens by tier (definition/usage/component),
 * category (color/spacing/typography), and theme.
 */
import type { TokenCategory, TokenEntry, TokenTier } from '../types.js';
export declare class TokenTaxonomy {
    private tokens;
    /**
     * Build the token taxonomy by scanning token files.
     *
     * Two-pass build:
     *  1. Walk the source JSON files in `tier-{1-definitions,2-usage,3-components}/`
     *     directories to build an authoritative `tokenName → tier` map. The file
     *     path is the source of truth for tier; relying on CSS-variable name
     *     heuristics mis-classifies tier-2 blocks like `animation` and `viz`
     *     because their first segment after `--ed-theme-` isn't a stock CSS
     *     category name (#680).
     *  2. Parse the compiled tokens.css per theme for the actual values,
     *     looking up the tier in the map produced by pass 1.
     *
     * Tokens that exist in the compiled CSS but not in any source JSON
     * (deprecated/leftover) fall through to the legacy name-heuristic
     * classifier so we never emit an empty tier — but in practice every
     * compiled token traces back to a JSON definition.
     */
    build(rootDir: string): Promise<void>;
    /**
     * Build the authoritative `tokenName → tier` map by walking source JSON.
     *
     * Looks under any theme directory (`bfw`, `bfw-dark`, `altitude`, etc.)
     * for these conventional subdirectories:
     *   - `tier-1-definitions/*.json` → tier "definition"
     *   - `tier-2-usage/*.json`        → tier "usage"
     *   - `tier-3-components/*.json`   → tier "component"
     *
     * Each leaf node (object with a non-object `value`) becomes a CSS variable
     * name derived from the path: `--ed-<dot.path.dashed>` for tier 1, and
     * `--ed-theme-<dot.path.dashed>` for tiers 2 and 3. The tier-1 vs theme
     * prefix split mirrors how Style Dictionary emits the compiled CSS.
     *
     * Earliest tier wins on collision (in practice tokens don't appear in
     * multiple tiers; this just keeps the result deterministic).
     */
    private buildTierMap;
    /**
     * Walk a Style-Dictionary-style JSON tree and yield the CSS variable name
     * for each leaf (object with a non-object `value` property). Non-leaf
     * objects recurse; primitive/array values are ignored.
     */
    private collectCssVarNames;
    /**
     * Parse a tokens.css file and extract all tokens
     */
    private parseTokenFile;
    /**
     * Derive the color subcategory ("background" | "content" | "border") from
     * a token name. The convention is that the segment immediately after
     * `color-` in the name is the subcategory:
     *   --ed-theme-color-background-default → "background"
     *   --ed-theme-color-content-default    → "content"
     *   --ed-theme-color-border-subtle      → "border"
     * Returns undefined for non-color tokens, definition-tier color tokens
     * (no subcategory in name), and any color-token shape we don't recognize.
     */
    private deriveSubcategory;
    /**
     * Derive the CSS properties this token is valid to apply to.
     * Only meaningful for color tokens with a known subcategory; other tokens
     * return undefined (no `validProperties` field on output).
     */
    private deriveValidProperties;
    /**
     * Classify a token as tier 1 (definition), tier 2 (usage), or tier 3 (component)
     *
     * Tier 1: --ed-{category}-{name} (e.g., --ed-color-brand-blue)
     * Tier 2: --ed-theme-{category}-{semantic} (e.g., --ed-theme-color-background-default)
     * Tier 3: --ed-theme-{component}-{property} (e.g., --ed-theme-button-background)
     */
    private classifyTier;
    /**
     * Classify a token by category
     */
    private classifyCategory;
    /**
     * Extract intent from token name
     */
    private extractIntent;
    /**
     * Extract what token this one references (if any)
     */
    private extractReferences;
    /**
     * Get a token by name
     */
    getToken(name: string): TokenEntry | undefined;
    /**
     * Get all tokens
     */
    getAll(): TokenEntry[];
    /**
     * Get tokens by tier
     */
    getByTier(tier: TokenTier): TokenEntry[];
    /**
     * Get tokens by category
     */
    getByCategory(category: TokenCategory): TokenEntry[];
    /**
     * Get tokens by theme
     */
    getByTheme(theme: string): TokenEntry[];
    /**
     * Get available themes (raw build-directory names).
     *
     * Returns every theme that has a compiled `build/css/tokens.css`, including
     * the `bfw-v9-*` palette variants. Coverage validators (drift-detector,
     * token-validator) use this so they check token coverage across *every*
     * compiled theme, variants included.
     */
    getThemes(): string[];
    /**
     * Get canonical themes — the human-facing theme list.
     *
     * Collapses `bfw-v9-<variant>` palette dirs (ember, funk, midnight, …) into
     * the single `bfw-v9` theme they are variants of. This is the count docs and
     * agents should reason about (7 themes), distinct from the raw build-dir
     * count (`getThemes()`, which includes every variant). See issue #1017.
     */
    getCanonicalThemes(): string[];
    /**
     * Normalize a build-dir theme name to its canonical theme.
     * `bfw-v9-ember` → `bfw-v9`; everything else is returned unchanged.
     */
    canonicalizeTheme(theme: string): string;
    /**
     * Theme inheritance: `variant → parent`.
     *
     * A theme listed here is a *variant* — it compiles as `core` → parent →
     * variant and its source directory carries **colors and nothing else**. Its
     * typography, shadow geometry, borders and motion are the parent's, by
     * construction. An agent asked to change a non-color token in a variant
     * should change it in the parent instead; `eddie_validate_file` errors on
     * the variant, and `npm run check:theme-inheritance` fails the build.
     *
     * Mirrors `THEME_PARENTS` in `packages/eddie-design-tokens/themes.js` (the
     * brain ships standalone and cannot read the tokens package at runtime).
     *
     * This is not the same relationship as the `bfw-v9-*` palette variants that
     * `canonicalizeTheme` collapses: those are separate compiled themes that
     * share a name prefix, whereas these are one compiled theme layered on
     * another at build time.
     */
    getThemeParents(): Record<string, string>;
    /**
     * Serialize to JSON
     */
    toJSON(): Record<string, TokenEntry>;
    /**
     * Deserialize from JSON
     */
    static fromJSON(obj: Record<string, TokenEntry>): TokenTaxonomy;
}
//# sourceMappingURL=token-taxonomy.d.ts.map