/**
 * Shared skip-context helpers used by tokens/no-hardcoded-color and
 * tokens/no-hardcoded-spacing to suppress intentional false positives.
 *
 * Most helpers operate on the source string without an AST. `isInsideCodeDisplay`
 * handles both same-line and multi-line <code>/<pre> blocks via backward scan.
 * The `sizes={"..."}` JSX-expression form is still not handled — it requires
 * AST traversal to detect the expression boundary.
 */
/**
 * Returns true if the file is a browser-normalize / CSS-reset stylesheet or a
 * minified CSS bundle — files that are never DS-authored, so hardcoded color
 * values in them are categorically not design-system drift.
 *
 * This complements the built-in directory-level vendoring check below
 * (`.yarn/`, `vendor/`, `bower_components/`) with basename-level signals for
 * normalize/reset files that may live inside the repo's own tree (e.g.
 * `src/base/normalize.scss` in primer-css).
 */
export declare function isVendoredOrResetFile(filePath: string): boolean;
/**
 * Returns true if the CSS source string is a generated build artifact whose
 * colors were never authored by a design-system contributor.
 *
 * Keyed entirely on the generator banner in the file head — no path heuristics.
 */
export declare function isGeneratedCssSource(source: string): boolean;
/**
 * Returns true if the file is a color token definition file, demo, or a CSS/SCSS
 * file under a stories/ directory — places where hex literals are the source of
 * truth, not drift.
 *
 * Patterns:
 *   - colors.ts / colors.js / colors.css / colors.scss (top-level or nested)
 *   - *-colors.ts / *-colors.js (e.g. brand-colors.ts, legacy-colors.ts)
 *   - _legacy-colors.ts / _legacy-colors.js
 *   - palette.ts / palette.js / palette.css / palette.scss
 *   - *.colors.ts / *.colors.css / *.colors.scss (e.g. button.colors.ts)
 *   - Files under demos/ directory
 *   - *.demo.{ts,tsx,js,jsx,mjs,cjs} files
 *   - CSS/SCSS files anywhere under stories/ (the existing guard catches *.stories.tsx
 *     for TS files, but not stories/x.module.css)
 *   - _?tokens.{scss,sass,less} / _?vars?.{scss,sass,less} (e.g. var.scss, vars.scss,
 *     _tokens.scss — Element Plus / Ant Design style Sass token partials)
 *   - theme/tokens/ and semantic-tokens/ definition files — restricted to
 *     definition-file extensions (.ts/.js/.mjs/.cjs/.json/.css/.scss/.sass/.less)
 *     so a consumer component like theme/tokens/Button.tsx is NOT suppressed
 *     (e.g. Chakra UI's token-definition dirs)
 *
 * Note: theme.ts / theme.css are intentionally excluded — they are borderline
 * (theme files can be component stylesheets, not purely token definitions).
 * The ts-morph isTokenDefinitionFile heuristic already handles TS theme files
 * with the right export shape for the classifyConfidence path.
 */
export declare function isColorTokenDefFile(filePath: string): boolean;
/**
 * Returns true if the file is an SVG icon file based on its path.
 * Hardcoded color values in these files are vector art, not DS drift.
 *
 * Path signals (general — no repo-specific names):
 *   - *Icon.{tsx,jsx,ts,js}  — named-icon component pattern
 *   - *.svg                   — pure SVG asset files
 *   - /icons/, /icon/, /svg/  — icon directory conventions
 *
 * The content signal (fill="#hex" / stroke="#hex") was removed: it suppressed
 * the whole file on any SVG attribute match, causing a recall hole when a
 * non-icon file mixed decorative SVG markup with real hardcoded DS colors.
 * dataset id 86 (icon-library-picker.tsx — no icon path signal) is now a
 * RESIDUAL FP.
 */
export declare function isSvgIconContext(filePath: string): boolean;
/**
 * Returns true if the file path is a test, story, mock, or fixture file.
 * Hardcoded values in these contexts are documentation/assertion artefacts,
 * not real design-system drift.
 */
export declare function isLowSignalValueFile(filePath: string): boolean;
/**
 * Returns true if the file path is a NestJS DTO, JSON-schema, config, or
 * TypeScript declaration file. Hardcoded values in these roles (e.g. an
 * @ApiProperty example) are schema documentation, not DS drift.
 */
export declare function isSchemaOrDataFile(filePath: string): boolean;
/**
 * Returns true if the matched literal at `matchIndex` in `source` is:
 *   (a) the value of an object key named example/default/placeholder/sample/mock, OR
 *   (b) inside a JSDoc `@example` block (`/** … @example … *\/`).
 *
 * For (a): walks back from `matchIndex` to the nearest `:` at the same paren
 * depth, then checks the key name — mirroring the isCssCustomPropertyDeclaration
 * pattern.
 * For (b): checks whether the line or any preceding line (within the same
 * `/** … *\/` block) contains `@example`.
 */
export declare function isInExampleOrSchemaValuePosition(source: string, matchIndex: number): boolean;
/**
 * Returns true if the byte offset `index` in `source` falls inside a
 * `<code>...</code>` or `<pre>...</pre>` block — either on the same line or
 * across multiple lines. Useful for skipping display-only CSS examples in
 * documentation components (shadcn theme customizer pattern, Storybook docs).
 *
 * Strategy:
 *   1. Same-line check: if open+close tags bracket the position on the same
 *      line, return true immediately (fast path, no backtracking needed).
 *   2. Multi-line check: scan backwards from `index` for the nearest `<code>`
 *      or `<pre>` opening tag; if found, scan forwards for the matching close
 *      tag and verify `index` falls between them.
 *
 * Limitation: does not handle nested `<code>` inside `<code>`, or tags with
 * attributes like `<code class="language-css">`. Attributes version is a
 * common pattern — add attribute-tolerant open-tag matching.
 */
export declare function isInsideCodeDisplay(source: string, index: number): boolean;
/**
 * Returns true if `index` is inside the quoted value of a JSX attribute we
 * intentionally skip (sizes, srcSet, media — responsive image markup).
 */
export declare function isInsideSkippedJsxAttr(source: string, index: number): boolean;
/**
 * Returns true if the byte offset `index` falls on the right-hand side of a
 * CSS custom-property declaration (`--x: <value>`), in any selector scope.
 *
 * A value on the RHS of a custom property is, structurally, a *token
 * definition* — not drift via a hardcoded value in a real CSS property. This
 * holds whether the declaration sits in `:root` or in a component-scoped
 * `.widget { --local: 16px }` (a common pattern: define a local var, then use
 * it via `var(--local)`). The cross-tool calibration (#120) showed the prior
 * selector-scoped narrowing (Track 9.11) produced hundreds of false positives
 * on real design systems (e.g. `--heatmap-level-1: rgba(...)` in a chart
 * module), dominating the disagreement with stylelint, which never flags
 * custom-property values either.
 *
 * The remaining semantic case — "this `--x: #hex` should reference an existing
 * token rather than hardcode" — needs the token catalogue and is left to the
 * LLM filter layer, not this static guard.
 */
export declare function isCssCustomPropertyDeclaration(source: string, index: number): boolean;
/**
 * Returns true if the literal at `index` sits in the *fallback* position of a
 * `var(--token, <fallback>)` call. Such a declaration is tokenized usage — the
 * `var()` reference is the real value; the literal only applies if the token is
 * undefined (dead code in a well-formed design system). Flagging it as drift is
 * a false positive. Handles nesting (`var(--a, var(--b, 8px))`). A literal in
 * any non-`var` function (e.g. `calc(50% - 1px)`) returns false.
 */
export declare function isInVarFallback(source: string, index: number): boolean;
/**
 * Returns true if the offset `hitStart` falls inside a line comment, a block
 * comment, or a URL fragment — positions where a hex/px literal is not a real
 * declaration value. The SCSS transform converts `.scss` `//` comments into
 * block comments, so this also catches a value inside a former line comment.
 */
export declare function isInCommentOrUrl(source: string, hitStart: number): boolean;
/**
 * Returns true when the color literal at `hitStart` in `source` is an
 * element of a multi-color collection — an array `[ … ]` or an object
 * `{ … }` whose block contains at least `PALETTE_MIN_COLORS` color literals.
 *
 * The check walks outward through up to 2 nesting levels: first the
 * immediate enclosing block, then one level up if the immediate block does
 * not qualify. This handles syntax-highlight theme objects where individual
 * hex values live inside nested `settings: { foreground: '#hex' }` objects
 * that are themselves elements of a large outer `tokenColors` array or
 * `colors` object with many color-valued properties.
 *
 * Intentionally NOT palette context:
 *   - Two-color pairs / lone values — below the threshold, always flag.
 *   - A CSS rule body `{ property: #hex; property2: #hex2 }` with only
 *     a couple of colors — below the threshold.
 *
 * Limit of 2 outer levels: avoids over-suppression of isolated DS-component
 * colors that happen to be nested deeply inside a large component tree.
 */
export declare function isDataPaletteContext(source: string, hitStart: number): boolean;
/**
 * Returns true if the px/rem/em hit at `matchIndex` is in a CSS or JS source
 * string that is NOT a spacing property context.
 *
 * That is: returns true (= skip) when the value should NOT fire the spacing rule.
 * Returns false (= do not skip = may fire) when the value is in a spacing context.
 *
 * Spacing CSS properties: margin*, padding*, gap, row-gap, column-gap, top,
 * right, bottom, left, inset*.
 *
 * Spacing Tailwind prefixes: p-, px-, py-, pt-, pr-, pb-, pl-, m-, mx-, my-,
 * mt-, mr-, mb-, ml-, gap-, gap-x-, gap-y-, space-x-, space-y-, inset-, top-,
 * right-, bottom-, left-.
 *
 * Non-spacing (always skip): @media queries, useMediaQuery / matchMedia calls,
 * translate*()/translateX()/translateY() transform functions.
 *
 * For CSS: walks back from `matchIndex` to the nearest property colon at depth 0
 * and reads the property name.
 *
 * For Tailwind arbitrary values (`prefix-[value]`): checks the character before
 * the `[` bracket that wraps the value.
 */
export declare function isNotSpacingPropertyContext(source: string, matchIndex: number): boolean;