Merge pull request #22 from robinlopez/v.0.2.1

V.0.2.1

Author: robinlopez

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 Format : [Keep a Changelog](https://keepachangelog.com/) — versionning [SemVer](https://semver.org/).
 
+## [0.2.1] — 2026-05-29
+
+### Added
+- **Analyser — sticky section headers** : while scrolling through a long report, the header of the section currently in view pins itself at the top of the panel. The sticky strip mirrors the section title and count — you always know which section you are reading without scrolling back to the heading.
+
+### Changed
+- **Analyser — section order** : *Broken references* is now the first section — these are genuine bugs (broken `var(--…)` / `$var` references) and should be triaged before the lower-urgency hardcoded sections. *Hardcoded clusters* and *Hardcoded values* follow immediately after.
+- **Analyser — occurrence rows show `filename:line · property` instead of parent folder** : the per-file list inside an expanded hardcoded row now shows the CSS/JS property the literal is bound to (`Button.scss:42 · padding`) instead of echoing the parent directory name. The fixed 28 px height cap that clipped long labels has been removed.
+- **Analyser — no more 50-row ceiling on hardcoded results** : the hard cap of 50 at the analyser layer has been removed. Truncation is now handled exclusively by the `+ N more…` expander in the UI, so the count badge always matches the real number of detected items.
+
+### Fixed
+- **Analyser — token definitions no longer flagged as hardcoded** : literal values that are part of a token declaration (SCSS `$var: value`, CSS `--var: value`, JSON / JS object entries such as `"sm": "8px"`) are now correctly recognised as definitions and excluded from both *Hardcoded clusters* and *Hardcoded values*. Declaration detection has been extended to quoted JSON / JS object keys (`"borderRadius": "8px"`, `"sm": 8`).
+- **Analyser — pure token-catalog files fully excluded from hardcoded scan** : `.ts/.tsx/.js/.jsx/.json` files registered as token sources are now skipped entirely in the hardcoded scan, eliminating false positives from design-token catalog files.
+- **Analyser — TS / JS files only receive format-compatible token suggestions** : CSS custom-property suggestions (`var(--…)`) are no longer offered when the occurrence lives in a `.ts`/`.tsx`/`.js`/`.jsx` source. Only JS-reachable token kinds (object-path, runtime property access, helper call) are surfaced.
+
 ## [0.2.0] — 2026-05-22
 
 ### Added

build.gradle.kts

@@ -6,7 +6,7 @@ plugins {
 }
 
 group = "fr.fsh.tokendesigner"
-version = "0.2.0"
+version = "0.2.1"
 
 repositories {
     mavenCentral()

src/main/kotlin/fr/fsh/tokendesigner/analyze/AnalysisReport.kt

@@ -104,6 +104,13 @@ data class HardcodedOccurrence(
     val filePath: String,
     val offset: Int,
     val line: Int,
+    /**
+     * CSS / JS property name the literal is assigned to, when detectable
+     * (e.g. `padding`, `font-size`, `borderRadius`). Surfaced in the
+     * dashboard's per-occurrence rows so the user sees WHY the literal was
+     * picked up instead of a redundant parent-folder echo.
+     */
+    val propertyName: String? = null,
 )
 
 data class Coverage(

src/main/kotlin/fr/fsh/tokendesigner/analyze/DesignSystemAnalyzer.kt

@@ -539,18 +539,42 @@ class DesignSystemAnalyzer(private val project: Project) {
             val offset: Int,
             val kind: LiteralFinder.Kind,
             val expectedRole: fr.fsh.tokendesigner.model.TokenRole?,
+            val propertyName: String?,
         )
         val byBucket = LinkedHashMap<BucketKey, MutableList<Hit>>()
         val tokenNames = tokens.map { it.name }.toSet()
+        // Pure-declaration files: paths that *only* declare tokens (JSON/TS/JS
+        // catalogs). Their entire content is a token definition, so flagging
+        // any literal inside as "hardcoded" is pure noise. SCSS / CSS / Vue
+        // are left in the scan even when they declare tokens, because they
+        // commonly mix declarations with consumption rules.
+        val pureDeclarationExtensions = setOf("ts", "tsx", "js", "jsx", "json")
+        val pureDeclarationSources = tokens.asSequence()
+            .filter { it.filePath.substringAfterLast('.').lowercase() in pureDeclarationExtensions }
+            .map { it.filePath }
+            .toSet()
 
         for (vf in scannedFiles) {
+            if (vf.path in pureDeclarationSources) continue
             val text = try {
                 readAction { VfsUtilCore.loadText(vf) }
             } catch (_: Exception) { continue }
             for (h in LiteralFinder.findIn(text)) {
                 if (h.insidePartialString) continue
                 if (h.kind == LiteralFinder.Kind.REFERENCE) continue
-                if (h.isDeclaration && (!inspectVariableDeclarations || (h.declarationName != null && h.declarationName in tokenNames))) continue
+                // Skip token-map values (SCSS `$map: (...)` entries) and any
+                // detected variable / object-property declaration. The latter
+                // bypasses `inspectVariableDeclarations` when the declaration
+                // sits in a token-source file — those declarations are *never*
+                // consumption, so the setting shouldn't unhide them.
+                if (h.insideTokenMap) continue
+                val isCatalogFile = vf.path in pureDeclarationSources
+                if (h.isDeclaration && (
+                        isCatalogFile ||
+                            !inspectVariableDeclarations ||
+                            (h.declarationName != null && h.declarationName in tokenNames)
+                        )
+                ) continue
 
                 val literal = h.text.lowercase()
                 if (literal in ignoredNames) continue
@@ -560,11 +584,12 @@ class DesignSystemAnalyzer(private val project: Project) {
                 // still get a coarse bucket.
                 val ctxCategory = PropertyContext.detectAt(text, h.startOffset)
                 val role = PropertyContext.detectRoleAt(text, h.startOffset)
+                val propertyName = PropertyContext.detectPropertyNameAt(text, h.startOffset)
                 val category = ctxCategory ?: kindFallbackCategory(h.kind)
                 val key = BucketKey(literal, category)
 
                 byBucket.getOrPut(key) { mutableListOf() }
-                    .add(Hit(vf, lineFor(text, h.startOffset), h.startOffset, h.kind, role))
+                    .add(Hit(vf, lineFor(text, h.startOffset), h.startOffset, h.kind, role, propertyName))
             }
         }
 
@@ -591,9 +616,12 @@ class DesignSystemAnalyzer(private val project: Project) {
             // the bucket has no detected category (JS object, no CSS context)
             // accept any exact match.
             val exact = suggestions.firstOrNull { it.exact &&
-                (category == null || it.token.category == category) }?.token
+                (category == null || it.token.category == category) &&
+                isTokenUsableInAll(it.token, occurrences.map { it.file }) }?.token
 
-            val occList = occurrences.map { HardcodedOccurrence(it.file.path, it.offset, it.line) }
+            val occList = occurrences.map {
+                HardcodedOccurrence(it.file.path, it.offset, it.line, it.propertyName)
+            }
 
             if (exact != null) {
                 // A token already covers this literal → actionable debt.
@@ -613,12 +641,47 @@ class DesignSystemAnalyzer(private val project: Project) {
             }
         }
 
+        // No `.take(…)` cap here: the UI uses a `+more` expander to truncate
+        // the visible list, so the full set must reach the report — otherwise
+        // a hard 50-row ceiling at the analyser layer artificially capped the
+        // counter even when many more hits existed.
         return HardcodedScan(
-            clusters = clusters.sortedByDescending { it.occurrences.size }.take(50),
-            values = values.sortedByDescending { it.occurrences.size }.take(50),
+            clusters = clusters.sortedByDescending { it.occurrences.size },
+            values = values.sortedByDescending { it.occurrences.size },
         )
     }
 
+    /**
+     * True when [token] can be referenced from every file in [files] given
+     * the file extension's binding format. CSS custom properties / SCSS
+     * variables aren't reachable from a `.ts` / `.tsx` / `.js` / `.jsx`
+     * source — suggesting a `var(--foo)` token in a React Native style
+     * object is wrong because that file can't resolve CSS variables. Only
+     * JS-flavoured token kinds (object paths, runtime property accesses,
+     * runtime helpers) are valid there.
+     *
+     * Returns true when [files] is empty so an exact match always survives
+     * if no occurrence files were captured (shouldn't happen in practice).
+     */
+    private fun isTokenUsableInAll(
+        token: DesignToken,
+        files: List<VirtualFile>,
+    ): Boolean {
+        if (files.isEmpty()) return true
+        return files.all { isTokenUsableIn(token, it.extension?.lowercase()) }
+    }
+
+    private fun isTokenUsableIn(token: DesignToken, ext: String?): Boolean = when (ext) {
+        "ts", "tsx", "js", "jsx" -> token.kind in JS_BINDABLE_KINDS
+        "json" -> token.kind in JS_BINDABLE_KINDS
+        "css" -> token.kind == fr.fsh.tokendesigner.model.TokenKind.CSS_CUSTOM_PROPERTY
+        // SCSS / Sass / Vue: anything goes — these files routinely consume
+        // both `$var` and `var(--…)`, and `<script>` blocks in Vue accept
+        // JS-style tokens too.
+        "scss", "sass", "vue", "html", null -> true
+        else -> true
+    }
+
     private fun kindFallbackCategory(kind: LiteralFinder.Kind): TokenCategory? = when (kind) {
         LiteralFinder.Kind.COLOR -> TokenCategory.COLOR
         LiteralFinder.Kind.LENGTH -> TokenCategory.SPACING
@@ -746,6 +809,12 @@ class DesignSystemAnalyzer(private val project: Project) {
     companion object {
         private const val MIN_HARDCODED_CLUSTER = 2
         private val COVERAGE_EXTS = listOf("scss", "sass", "css", "vue", "ts", "tsx", "js", "jsx")
+        /** Token kinds reachable from a `.ts` / `.tsx` / `.js` / `.jsx` / `.json` source. */
+        private val JS_BINDABLE_KINDS = setOf(
+            fr.fsh.tokendesigner.model.TokenKind.JS_OBJECT_PATH,
+            fr.fsh.tokendesigner.model.TokenKind.JS_RUNTIME_PROPERTY,
+            fr.fsh.tokendesigner.model.TokenKind.JS_RUNTIME_FUNCTION,
+        )
         // Each pattern's group 1 captures the bare token name so we can fold
         // the references into a single `Set<String>` for unused-token detection.
         private val CSS_REF = Regex("var\\(\\s*--([A-Za-z_][A-Za-z0-9_-]*)(?:\\s*,.*)?\\)")

src/main/kotlin/fr/fsh/tokendesigner/inspection/LiteralFinder.kt

@@ -154,9 +154,10 @@ object LiteralFinder {
             if (isWhitelisted(value)) continue
             if (isIgnored(start)) continue
             if (out.any { it.startOffset == start }) continue
-            // If the key starts with $ or is --, it's a variable declaration.
-            val key = m.value.substringBefore(':').trim()
-            val declName = if (key.startsWith("$") || key.startsWith("--")) key else null
+            // Reuse the same declaration detector as the unit-bearing literals
+            // so RN/JS catalog files (`sm: 8`, `"sm": 8`) are folded into the
+            // declaration bucket exactly like `8px` and skipped consistently.
+            val declName = variableDeclarationName(text, start)
             out += Hit(
                 value, start, end, Kind.NUMBER,
                 isDeclaration = declName != null,
@@ -444,16 +445,55 @@ object LiteralFinder {
      * Checks if the literal at [offset] is part of a variable declaration
      * like `$name: ...` or `--name: ...`, and returns the variable name.
      */
+    /**
+     * Walks back from a literal hit to decide whether it sits in a variable /
+     * property *declaration* (token definition) rather than a *consumption*
+     * site. Recognised shapes:
+     *
+     *  • SCSS:  `$name: <literal>`               → returns `$name`
+     *  • CSS:   `--name: <literal>`              → returns `--name`
+     *  • JS/TS object literal:                   → returns the bare key
+     *      - `name: "<literal>"` or `name: '<literal>'`
+     *      - `"name": "<literal>"` / `'name': '<literal>'`
+     *      - `"name": <literal>` (numeric value)
+     *
+     * For a *bare* key with a *bare* numeric value (e.g. `padding: 12px` in a
+     * CSS block) we deliberately return `null`. That shape is ambiguous —
+     * either a CSS rule (definite consumption, should be flagged) or a
+     * RN-style object property (could be either). We err on flagging so real
+     * CSS hardcoded values still surface; the token-source file whole-skip
+     * (see `DesignSystemAnalyzer.collectHardcodedScan`) handles the few false
+     * positives that remain in TS catalog files.
+     */
     private fun variableDeclarationName(text: CharSequence, offset: Int): String? {
         var i = offset - 1
         while (i >= 0 && text[i].isWhitespace()) i--
+
+        // Optional opening string quote — the literal lives inside `"…"` /
+        // `'…'` / `` `…` ``. This is the strong JS/JSON declaration signal.
+        val openQuote = if (i >= 0 && (text[i] == '"' || text[i] == '\'' || text[i] == '`')) {
+            text[i].also { i-- }
+        } else null
+        while (i >= 0 && text[i].isWhitespace()) i--
         if (i < 0 || text[i] != ':') return null
 
         i--
         while (i >= 0 && text[i].isWhitespace()) i--
         if (i < 0) return null
 
-        // Match variable name backwards
+        // Quoted key — only legal in JS / TS / JSON object literals, never in
+        // CSS. Always treated as a declaration regardless of value shape.
+        if (text[i] == '"' || text[i] == '\'') {
+            val keyEnd = i
+            val quote = text[i]
+            i--
+            while (i >= 0 && text[i] != quote) i--
+            if (i < 0) return null
+            val name = text.subSequence(i + 1, keyEnd).toString()
+            return name.ifBlank { null }
+        }
+
+        // Bare key — walk back to capture the identifier.
         var j = i
         while (j >= 0 && (text[j].isLetterOrDigit() || text[j] == '-' || text[j] == '_')) j--
         if (j == i) return null
@@ -462,10 +502,15 @@ object LiteralFinder {
 
         // SCSS: $name
         if (j >= 0 && text[j] == '$') return "$$name"
-
-        // CSS: --name
+        // CSS custom property: --name
         if (j > 0 && text[j] == '-' && text[j - 1] == '-') return "--$name"
 
+        // Bare key with **quoted** value → JS/TS declaration (`size: "8px"`).
+        if (openQuote != null) return name
+
+        // Bare key, bare value → ambiguous CSS-rule vs. RN-style assignment.
+        // Return null so legitimate hardcoded CSS values still surface; the
+        // token-source whole-file skip handles the RN-catalog edge case.
         return null
     }