@justinmoto/frontend-guardian-core 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,10 @@
 # @justinmoto/frontend-guardian-core
 
-Library (scan engine) for Frontend Guardian. Use this package if you want to call the scanner from your own Node code.
+Library (scan engine) for **Frontend Guardian**.
+
+**Frontend Guardian** helps frontend developers keep their UI consistent. After you ship a project it often *looks* good but when you (or someone else) opens it again later, you notice uneven spacing, inconsistent borders and radii, mixed colors, or copy-pasted components that drifted apart. Frontend Guardian scans your code and flags those issues so you can fix them before they pile up.
+
+Use this package if you want to call the scanner from your own Node code.
 
 **To run scans from the command line**, use the CLI instead:
 

package/dist/scanEngine.d.ts

@@ -1,5 +1,10 @@
 export type Warning = {
     file: string;
+    line?: number;
+    locations?: {
+        file: string;
+        line: number;
+    }[];
     message: string;
     suggestion?: string;
 };
@@ -10,6 +15,7 @@ export type Duplicate = {
 };
 export type ScanResult = {
     score: number;
+    filesScanned: number;
     warnings: Warning[];
     duplicates: Duplicate[];
 };

package/dist/scanEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanEngine.d.ts","sourceRoot":"","sources":["../src/scanEngine.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAC7E,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAClF,MAAM,MAAM,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;IAAC,UAAU,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC;AA+MzF,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAajE;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,UAAU,CAG7E"}
+{"version":3,"file":"scanEngine.d.ts","sourceRoot":"","sources":["../src/scanEngine.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AACF,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAClF,MAAM,MAAM,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;IAAC,UAAU,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC;AA4S/G,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAajE;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,UAAU,CAG7E"}

package/dist/scanEngine.js

@@ -12,18 +12,20 @@ function isSourcePath(path) {
     const normalized = path.replace(/\\/g, "/");
     return !IGNORE_PATH_PARTS.some((part) => normalized.includes(part));
 }
-function extractClassNames(ast) {
-    const classes = [];
+function extractClassNamesWithLines(ast) {
+    const out = [];
     traverse(ast, {
         JSXAttribute(path) {
             if (path.node.name.type === "JSXIdentifier" && path.node.name.name === "className") {
                 const val = path.node.value;
-                if (val?.type === "StringLiteral")
-                    classes.push(val.value);
+                if (val?.type === "StringLiteral") {
+                    const line = path.node.loc?.start?.line ?? 0;
+                    out.push({ value: val.value, line });
+                }
             }
         },
     });
-    return classes;
+    return out;
 }
 function normalizeJsxForHash(code) {
     return code
@@ -32,8 +34,8 @@ function normalizeJsxForHash(code) {
         .replace(/\bclassName=\{[^}]*\}/g, "className={}")
         .trim();
 }
-function extractButtonClassNames(ast) {
-    const classes = [];
+function extractButtonClassNamesWithLine(ast) {
+    const out = [];
     traverse(ast, {
         JSXOpeningElement(path) {
             const name = path.node.name;
@@ -45,17 +47,59 @@ function extractButtonClassNames(ast) {
                     break;
                 }
             }
+            const line = path.node.loc?.start?.line ?? 0;
             const isButton = tagName === "button" || (typeof className === "string" && /btn|button/i.test(className));
             if (isButton && className)
-                classes.push(className);
+                out.push({ classes: className, line });
+        },
+    });
+    return out;
+}
+const SKIP_UNUSED_IMPORT_NAMES = new Set([
+    "React", "Metadata", "FormEvent", "ChangeEvent", "ReactElement", "ReactNode", "FC", "NextConfig",
+    "FormEventHandler", "ChangeEventHandler", "MouseEvent", "KeyboardEvent", "SyntheticEvent",
+    "Props", "ComponentProps", "ReactNode", "CSSProperties", "HTMLAttributes", "ButtonHTMLAttributes",
+]);
+const SKIP_IF_FROM_REACT = new Set(["React", "FC", "ReactNode", "ReactElement", "CSSProperties", "FormEvent", "ChangeEvent", "MouseEvent", "KeyboardEvent", "SyntheticEvent", "Props", "ComponentProps", "HTMLAttributes", "ButtonHTMLAttributes", "FormEventHandler", "ChangeEventHandler"]);
+const SKIP_IF_FROM_NEXT = new Set(["Metadata", "NextConfig", "Image", "Link", "Router", "Head", "Script"]);
+function getNamesUsedInTypePosition(ast) {
+    const used = new Set();
+    traverse(ast, {
+        TSTypeReference(path) {
+            const n = path.node.typeName;
+            if (n.type === "Identifier" && n.name)
+                used.add(n.name);
+            if (n.type === "TSQualifiedName") {
+                if (n.right?.name)
+                    used.add(n.right.name);
+                if (n.left && "name" in n.left && n.left.name)
+                    used.add(n.left.name);
+            }
         },
     });
-    return classes;
+    return used;
 }
-function getUnusedImports(ast) {
+function getNamesUsedInJSX(ast) {
+    const used = new Set();
+    traverse(ast, {
+        JSXOpeningElement(path) {
+            const name = path.node.name;
+            if (name.type === "JSXIdentifier" && name.name)
+                used.add(name.name);
+        },
+    });
+    return used;
+}
+function getUnusedImportsWithLine(ast) {
+    const usedInTypes = getNamesUsedInTypePosition(ast);
+    const usedInJSX = getNamesUsedInJSX(ast);
     const unused = [];
     traverse(ast, {
         ImportDeclaration(path) {
+            const line = path.node.loc?.start?.line ?? 0;
+            const source = path.node.source?.value ?? "";
+            const fromReact = source === "react" || source.startsWith("react/");
+            const fromNext = source === "next" || source.startsWith("next/");
             for (const spec of path.node.specifiers) {
                 const s = spec;
                 const local = s.local?.name;
@@ -63,141 +107,199 @@ function getUnusedImports(ast) {
                     continue;
                 if (s.importKind === "type" || s.importKind === "typeof")
                     continue;
+                if (SKIP_UNUSED_IMPORT_NAMES.has(local))
+                    continue;
+                if (fromReact && SKIP_IF_FROM_REACT.has(local))
+                    continue;
+                if (fromNext && SKIP_IF_FROM_NEXT.has(local))
+                    continue;
+                if (usedInTypes.has(local))
+                    continue;
+                if (usedInJSX.has(local))
+                    continue;
                 const binding = path.scope.getBinding(local);
                 if (binding && !binding.referenced)
-                    unused.push(local);
+                    unused.push({ name: local, line });
             }
         },
     });
     return unused;
 }
+function getUnusedVariablesWithLine(ast) {
+    const unused = [];
+    traverse(ast, {
+        VariableDeclarator(path) {
+            const id = path.node.id;
+            if (id.type !== "Identifier" || !id.name)
+                return;
+            if (id.name.startsWith("_"))
+                return;
+            const binding = path.scope.getBinding(id.name);
+            if (!binding || binding.referenced)
+                return;
+            unused.push({ name: id.name, line: id.loc?.start?.line ?? 0 });
+        },
+    });
+    return unused;
+}
 function runAnalysis(fileContents) {
     const sourceOnly = fileContents.filter((f) => isSourcePath(f.path));
     const warnings = [];
     const jsxHashes = new Map();
-    const spacingValues = new Map();
-    const radiusValues = new Map();
+    const spacingData = new Map();
+    const radiusByFile = new Map();
     const colorClassesByFile = new Map();
     const arbitraryColorByFile = new Map();
-    const buttonClassesByFile = new Map();
-    for (const { path, code } of sourceOnly) {
+    const buttonDataByFile = new Map();
+    const MAX_LOCATIONS = 25;
+    for (const { path: filePath, code } of sourceOnly) {
         try {
-            const ast = parser.parse(code, { sourceType: "module", plugins: ["jsx", "typescript"] });
-            const unused = getUnusedImports(ast);
-            for (const name of unused) {
+            const ast = parser.parse(code, { sourceType: "module", plugins: ["jsx", "typescript"], attachComment: false });
+            const unusedList = getUnusedImportsWithLine(ast);
+            for (const { name, line } of unusedList) {
                 warnings.push({
-                    file: path,
+                    file: filePath,
+                    line,
                     message: `Unused import: ${name}`,
                     suggestion: "Remove unused imports to keep the file clean and avoid confusion. Use your editor's organize-imports or run ESLint with no-unused-vars.",
                 });
             }
-            const classNames = extractClassNames(ast);
-            for (const cn of classNames) {
+            const unusedVars = getUnusedVariablesWithLine(ast);
+            for (const { name, line } of unusedVars) {
+                warnings.push({
+                    file: filePath,
+                    line,
+                    message: `Unused variable: ${name}`,
+                    suggestion: "Remove or use the variable. Prefix with _ if intentionally unused.",
+                });
+            }
+            const classEntries = extractClassNamesWithLines(ast);
+            for (const { value: cn, line } of classEntries) {
                 const parts = cn.split(/\s+/).filter(Boolean);
                 for (const p of parts) {
                     if (/^p[xy]?-[a-z0-9]+$/.test(p) || /^m[xy]?-[a-z0-9]+$/.test(p)) {
                         const key = p.replace(/[0-9]+$/, "N");
-                        if (!spacingValues.has(key))
-                            spacingValues.set(key, new Set());
-                        spacingValues.get(key).add(p);
+                        if (!spacingData.has(key))
+                            spacingData.set(key, { values: new Set(), locations: [] });
+                        const entry = spacingData.get(key);
+                        entry.values.add(p);
+                        if (entry.locations.length < MAX_LOCATIONS)
+                            entry.locations.push({ file: filePath, line });
                     }
                     if (/^rounded[a-z0-9-]*$/.test(p)) {
-                        if (!radiusValues.has(path))
-                            radiusValues.set(path, new Set());
-                        radiusValues.get(path).add(p);
+                        if (!radiusByFile.has(filePath))
+                            radiusByFile.set(filePath, { values: new Set(), line });
+                        radiusByFile.get(filePath).values.add(p);
                     }
                     if (/^(bg|text|border)-(.+)$/.test(p)) {
-                        if (!colorClassesByFile.has(path))
-                            colorClassesByFile.set(path, new Set());
-                        colorClassesByFile.get(path).add(p);
+                        if (!colorClassesByFile.has(filePath))
+                            colorClassesByFile.set(filePath, new Set());
+                        colorClassesByFile.get(filePath).add(p);
                         if (/\[#|\[rgb|\[hsl/.test(p.replace(/^(bg|text|border)-/, "")))
-                            arbitraryColorByFile.set(path, true);
+                            arbitraryColorByFile.set(filePath, line);
                     }
                 }
             }
-            const btnClasses = extractButtonClassNames(ast);
-            if (btnClasses.length > 0)
-                buttonClassesByFile.set(path, btnClasses);
+            const btnEntries = extractButtonClassNamesWithLine(ast);
+            if (btnEntries.length > 0)
+                buttonDataByFile.set(filePath, btnEntries.map((e) => ({ classes: e.classes.split(/\s+/).filter(Boolean), line: e.line })));
             const normalized = normalizeJsxForHash(code);
             if (normalized.length > 50) {
                 const hash = crypto.createHash("md5").update(normalized).digest("hex");
                 if (!jsxHashes.has(hash))
                     jsxHashes.set(hash, []);
-                jsxHashes.get(hash).push(path);
+                jsxHashes.get(hash).push(filePath);
             }
         }
         catch {
             warnings.push({
-                file: path,
+                file: filePath,
                 message: "Parse error (not valid JS/TS/JSX)",
                 suggestion: "Check syntax, brackets, and that the file is valid JS/TS/JSX. Fix or remove the file from the scan.",
             });
         }
     }
-    for (const [, values] of spacingValues) {
-        if (values.size > 1) {
+    for (const [, data] of spacingData) {
+        if (data.values.size > 1) {
             warnings.push({
                 file: "(project)",
-                message: `Mixed spacing values: ${[...values].join(", ")}`,
+                locations: data.locations.slice(0, MAX_LOCATIONS),
+                message: `Mixed spacing values: ${[...data.values].join(", ")}`,
                 suggestion: "Pick one spacing scale (e.g. px-4, py-2) for similar elements and use it across the project so spacing stays consistent.",
             });
         }
     }
-    const radiusByFile = new Map();
-    for (const [path, values] of radiusValues)
-        radiusByFile.set(path, [...values]);
-    if (radiusByFile.size > 1) {
-        const unique = [...new Set([...radiusByFile.values()].flat())];
+    const radiusFileList = [...radiusByFile.entries()];
+    if (radiusFileList.length > 1) {
+        const unique = [...new Set(radiusFileList.flatMap(([, r]) => [...r.values]))];
         if (unique.length > 1) {
             warnings.push({
                 file: "(project)",
+                locations: radiusFileList.map(([p, r]) => ({ file: p, line: r.line })).slice(0, MAX_LOCATIONS),
                 message: `Inconsistent border-radius: ${unique.join(", ")}`,
                 suggestion: "Use one radius token (e.g. rounded-lg) for cards and buttons so the UI looks consistent.",
             });
         }
     }
-    const filesWithArbitraryColors = [...arbitraryColorByFile.entries()].filter(([, v]) => v).map(([p]) => p);
-    if (filesWithArbitraryColors.length > 0) {
+    const arbitraryEntries = [...arbitraryColorByFile.entries()];
+    if (arbitraryEntries.length > 0) {
+        const [firstFile, line] = arbitraryEntries[0];
         warnings.push({
-            file: filesWithArbitraryColors[0],
+            file: firstFile,
+            line,
             message: "Arbitrary color values (e.g. bg-[#hex], text-[rgb()]) detected.",
             suggestion: "Prefer Tailwind palette classes (e.g. bg-zinc-100, text-emerald-600) for consistent theming and maintenance.",
         });
     }
     const buttonPadding = new Map();
     const buttonRadius = new Map();
-    for (const [filePath, classes] of buttonClassesByFile) {
-        for (const cn of classes) {
-            for (const p of cn.split(/\s+/)) {
+    for (const [filePath, entries] of buttonDataByFile) {
+        for (const { classes: cn, line } of entries) {
+            for (const p of cn) {
                 if (/^p[xy]?-[a-z0-9]+$/.test(p)) {
                     const key = p.replace(/[0-9]+$/, "N");
                     if (!buttonPadding.has(key))
-                        buttonPadding.set(key, new Set());
-                    buttonPadding.get(key).add(p);
+                        buttonPadding.set(key, { values: new Set(), locations: [] });
+                    const entry = buttonPadding.get(key);
+                    entry.values.add(p);
+                    if (entry.locations.length < MAX_LOCATIONS)
+                        entry.locations.push({ file: filePath, line });
                 }
                 if (/^rounded[a-z0-9-]*$/.test(p)) {
                     if (!buttonRadius.has(filePath))
-                        buttonRadius.set(filePath, new Set());
-                    buttonRadius.get(filePath).add(p);
+                        buttonRadius.set(filePath, []);
+                    const arr = buttonRadius.get(filePath);
+                    const existing = arr.find((x) => x.values.has(p));
+                    if (!existing)
+                        arr.push({ values: new Set([p]), line });
+                    else
+                        existing.values.add(p);
                 }
             }
         }
     }
-    for (const [, values] of buttonPadding) {
-        if (values.size > 1) {
+    for (const [, data] of buttonPadding) {
+        if (data.values.size > 1) {
             warnings.push({
                 file: "(project)",
-                message: `Mixed button padding: ${[...values].join(", ")}`,
+                locations: data.locations.slice(0, MAX_LOCATIONS),
+                message: `Mixed button padding: ${[...data.values].join(", ")}`,
                 suggestion: "Use one button padding (e.g. px-4 py-2) across all buttons for a consistent look.",
             });
             break;
         }
     }
-    const allBtnRadius = [...buttonRadius.values()].flatMap((s) => [...s]);
-    if (allBtnRadius.length > 1 && new Set(allBtnRadius).size > 1) {
+    const allBtnRadiusValues = [...buttonRadius.values()].flatMap((arr) => arr.flatMap((r) => [...r.values]));
+    if (allBtnRadiusValues.length > 1 && new Set(allBtnRadiusValues).size > 1) {
+        const locations = [];
+        for (const [file, arr] of buttonRadius.entries()) {
+            if (arr.length > 0 && locations.length < MAX_LOCATIONS)
+                locations.push({ file, line: arr[0].line });
+        }
         warnings.push({
             file: "(project)",
-            message: `Inconsistent button border-radius: ${[...new Set(allBtnRadius)].join(", ")}`,
+            locations,
+            message: `Inconsistent button border-radius: ${[...new Set(allBtnRadiusValues)].join(", ")}`,
             suggestion: "Use one radius (e.g. rounded-lg) for all buttons.",
         });
     }
@@ -210,7 +312,7 @@ function runAnalysis(fileContents) {
     }
     const penalty = warnings.length * 5 + duplicates.length * 10;
     const score = Math.max(0, Math.min(100, 100 - penalty));
-    return { score, warnings, duplicates };
+    return { score, filesScanned: sourceOnly.length, warnings, duplicates };
 }
 export async function scanZip(buffer) {
     const zip = await JSZip.loadAsync(buffer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justinmoto/frontend-guardian-core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Scan engine for Frontend Guardian. To run scans from the CLI use: npx frontend-guardian .",
   "type": "module",
   "main": "dist/index.js",

package/src/scanEngine.ts

@@ -7,9 +7,15 @@ import JSZip from "jszip";
 const EXT = [".js", ".jsx", ".ts", ".tsx"];
 const IGNORE_PATH_PARTS = ["node_modules", ".next", "dist", "build", ".git"];
 
-export type Warning = { file: string; message: string; suggestion?: string };
+export type Warning = {
+  file: string;
+  line?: number;
+  locations?: { file: string; line: number }[];
+  message: string;
+  suggestion?: string;
+};
 export type Duplicate = { files: string[]; reason?: string; suggestion?: string };
-export type ScanResult = { score: number; warnings: Warning[]; duplicates: Duplicate[] };
+export type ScanResult = { score: number; filesScanned: number; warnings: Warning[]; duplicates: Duplicate[] };
 
 function isCodeFile(path: string): boolean {
   return EXT.some((e) => path.toLowerCase().endsWith(e));
@@ -20,17 +26,20 @@ function isSourcePath(path: string): boolean {
   return !IGNORE_PATH_PARTS.some((part) => normalized.includes(part));
 }
 
-function extractClassNames(ast: ReturnType<typeof parser.parse>): string[] {
-  const classes: string[] = [];
+function extractClassNamesWithLines(ast: ReturnType<typeof parser.parse>): { value: string; line: number }[] {
+  const out: { value: string; line: number }[] = [];
   traverse(ast, {
-    JSXAttribute(path: { node: { name: { type: string; name: string }; value?: { type: string; value: string } } }) {
+    JSXAttribute(path: { node: { name: { type: string; name: string }; value?: { type: string; value: string }; loc?: { start: { line: number } } } }) {
       if (path.node.name.type === "JSXIdentifier" && path.node.name.name === "className") {
         const val = path.node.value;
-        if (val?.type === "StringLiteral") classes.push(val.value);
+        if (val?.type === "StringLiteral") {
+          const line = path.node.loc?.start?.line ?? 0;
+          out.push({ value: val.value, line });
+        }
       }
     },
   });
-  return classes;
+  return out;
 }
 
 function normalizeJsxForHash(code: string): string {
@@ -41,10 +50,10 @@ function normalizeJsxForHash(code: string): string {
     .trim();
 }
 
-function extractButtonClassNames(ast: ReturnType<typeof parser.parse>): string[] {
-  const classes: string[] = [];
+function extractButtonClassNamesWithLine(ast: ReturnType<typeof parser.parse>): { classes: string; line: number }[] {
+  const out: { classes: string; line: number }[] = [];
   traverse(ast, {
-    JSXOpeningElement(path: { node: { name: { type: string; name: string }; attributes: unknown[] } }) {
+    JSXOpeningElement(path: { node: { name: { type: string; name: string }; attributes: unknown[]; loc?: { start: { line: number } } } }) {
       const name = path.node.name;
       const tagName = name.type === "JSXIdentifier" ? name.name : "";
       let className = "";
@@ -54,152 +63,242 @@ function extractButtonClassNames(ast: ReturnType<typeof parser.parse>): string[]
           break;
         }
       }
+      const line = path.node.loc?.start?.line ?? 0;
       const isButton = tagName === "button" || (typeof className === "string" && /btn|button/i.test(className));
-      if (isButton && className) classes.push(className);
+      if (isButton && className) out.push({ classes: className, line });
+    },
+  });
+  return out;
+}
+
+const SKIP_UNUSED_IMPORT_NAMES = new Set([
+  "React", "Metadata", "FormEvent", "ChangeEvent", "ReactElement", "ReactNode", "FC", "NextConfig",
+  "FormEventHandler", "ChangeEventHandler", "MouseEvent", "KeyboardEvent", "SyntheticEvent",
+  "Props", "ComponentProps", "ReactNode", "CSSProperties", "HTMLAttributes", "ButtonHTMLAttributes",
+]);
+
+const SKIP_IF_FROM_REACT = new Set(["React", "FC", "ReactNode", "ReactElement", "CSSProperties", "FormEvent", "ChangeEvent", "MouseEvent", "KeyboardEvent", "SyntheticEvent", "Props", "ComponentProps", "HTMLAttributes", "ButtonHTMLAttributes", "FormEventHandler", "ChangeEventHandler"]);
+const SKIP_IF_FROM_NEXT = new Set(["Metadata", "NextConfig", "Image", "Link", "Router", "Head", "Script"]);
+
+function getNamesUsedInTypePosition(ast: ReturnType<typeof parser.parse>): Set<string> {
+  const used = new Set<string>();
+  traverse(ast, {
+    TSTypeReference(path: { node: { typeName: unknown } }) {
+      const n = path.node.typeName as { type?: string; name?: string; right?: { name: string }; left?: { name?: string } };
+      if (n.type === "Identifier" && n.name) used.add(n.name);
+      if (n.type === "TSQualifiedName") {
+        if (n.right?.name) used.add(n.right.name);
+        if (n.left && "name" in n.left && n.left.name) used.add(n.left.name);
+      }
+    },
+  });
+  return used;
+}
+
+function getNamesUsedInJSX(ast: ReturnType<typeof parser.parse>): Set<string> {
+  const used = new Set<string>();
+  traverse(ast, {
+    JSXOpeningElement(path: { node: { name: { type: string; name?: string } } }) {
+      const name = path.node.name;
+      if (name.type === "JSXIdentifier" && name.name) used.add(name.name);
     },
   });
-  return classes;
+  return used;
 }
 
-function getUnusedImports(ast: ReturnType<typeof parser.parse>): string[] {
-  const unused: string[] = [];
+function getUnusedImportsWithLine(ast: ReturnType<typeof parser.parse>): { name: string; line: number }[] {
+  const usedInTypes = getNamesUsedInTypePosition(ast);
+  const usedInJSX = getNamesUsedInJSX(ast);
+  const unused: { name: string; line: number }[] = [];
   traverse(ast, {
-    ImportDeclaration(path: { node: { specifiers: unknown[] }; scope: { getBinding: (n: string) => { referenced: boolean } | undefined } }) {
+    ImportDeclaration(path: { node: { specifiers: unknown[]; source: { value?: string }; loc?: { start: { line: number } } }; scope: { getBinding: (n: string) => { referenced: boolean } | undefined } }) {
+      const line = path.node.loc?.start?.line ?? 0;
+      const source = (path.node.source?.value as string) ?? "";
+      const fromReact = source === "react" || source.startsWith("react/");
+      const fromNext = source === "next" || source.startsWith("next/");
       for (const spec of path.node.specifiers) {
         const s = spec as { local: { name: string }; importKind?: string };
         const local = s.local?.name;
         if (!local) continue;
         if (s.importKind === "type" || s.importKind === "typeof") continue;
+        if (SKIP_UNUSED_IMPORT_NAMES.has(local)) continue;
+        if (fromReact && SKIP_IF_FROM_REACT.has(local)) continue;
+        if (fromNext && SKIP_IF_FROM_NEXT.has(local)) continue;
+        if (usedInTypes.has(local)) continue;
+        if (usedInJSX.has(local)) continue;
         const binding = path.scope.getBinding(local);
-        if (binding && !binding.referenced) unused.push(local);
+        if (binding && !binding.referenced) unused.push({ name: local, line });
       }
     },
   });
   return unused;
 }
 
+function getUnusedVariablesWithLine(ast: ReturnType<typeof parser.parse>): { name: string; line: number }[] {
+  const unused: { name: string; line: number }[] = [];
+  traverse(ast, {
+    VariableDeclarator(path: { node: { id: { type?: string; name?: string; loc?: { start: { line: number } } } }; scope: { getBinding: (n: string) => { referenced: boolean } | undefined } }) {
+      const id = path.node.id as { type?: string; name?: string; loc?: { start: { line: number } } };
+      if (id.type !== "Identifier" || !id.name) return;
+      if (id.name.startsWith("_")) return;
+      const binding = path.scope.getBinding(id.name);
+      if (!binding || binding.referenced) return;
+      unused.push({ name: id.name, line: id.loc?.start?.line ?? 0 });
+    },
+  });
+  return unused;
+}
+
 function runAnalysis(fileContents: { path: string; code: string }[]): ScanResult {
   const sourceOnly = fileContents.filter((f) => isSourcePath(f.path));
   const warnings: Warning[] = [];
   const jsxHashes = new Map<string, string[]>();
-  const spacingValues = new Map<string, Set<string>>();
-  const radiusValues = new Map<string, Set<string>>();
+  const spacingData = new Map<string, { values: Set<string>; locations: { file: string; line: number }[] }>();
+  const radiusByFile = new Map<string, { values: Set<string>; line: number }>();
   const colorClassesByFile = new Map<string, Set<string>>();
-  const arbitraryColorByFile = new Map<string, boolean>();
-  const buttonClassesByFile = new Map<string, string[]>();
+  const arbitraryColorByFile = new Map<string, number>();
+  const buttonDataByFile = new Map<string, { classes: string[]; line: number }[]>();
+
+  const MAX_LOCATIONS = 25;
 
-  for (const { path, code } of sourceOnly) {
+  for (const { path: filePath, code } of sourceOnly) {
     try {
-      const ast = parser.parse(code, { sourceType: "module", plugins: ["jsx", "typescript"] });
-      const unused = getUnusedImports(ast);
-      for (const name of unused) {
+      const ast = parser.parse(code, { sourceType: "module", plugins: ["jsx", "typescript"], attachComment: false });
+      const unusedList = getUnusedImportsWithLine(ast);
+      for (const { name, line } of unusedList) {
         warnings.push({
-          file: path,
+          file: filePath,
+          line,
           message: `Unused import: ${name}`,
           suggestion: "Remove unused imports to keep the file clean and avoid confusion. Use your editor's organize-imports or run ESLint with no-unused-vars.",
         });
       }
-      const classNames = extractClassNames(ast);
-      for (const cn of classNames) {
+      const unusedVars = getUnusedVariablesWithLine(ast);
+      for (const { name, line } of unusedVars) {
+        warnings.push({
+          file: filePath,
+          line,
+          message: `Unused variable: ${name}`,
+          suggestion: "Remove or use the variable. Prefix with _ if intentionally unused.",
+        });
+      }
+      const classEntries = extractClassNamesWithLines(ast);
+      for (const { value: cn, line } of classEntries) {
         const parts = cn.split(/\s+/).filter(Boolean);
         for (const p of parts) {
           if (/^p[xy]?-[a-z0-9]+$/.test(p) || /^m[xy]?-[a-z0-9]+$/.test(p)) {
             const key = p.replace(/[0-9]+$/, "N");
-            if (!spacingValues.has(key)) spacingValues.set(key, new Set());
-            spacingValues.get(key)!.add(p);
+            if (!spacingData.has(key)) spacingData.set(key, { values: new Set(), locations: [] });
+            const entry = spacingData.get(key)!;
+            entry.values.add(p);
+            if (entry.locations.length < MAX_LOCATIONS) entry.locations.push({ file: filePath, line });
           }
           if (/^rounded[a-z0-9-]*$/.test(p)) {
-            if (!radiusValues.has(path)) radiusValues.set(path, new Set());
-            radiusValues.get(path)!.add(p);
+            if (!radiusByFile.has(filePath)) radiusByFile.set(filePath, { values: new Set(), line });
+            radiusByFile.get(filePath)!.values.add(p);
           }
           if (/^(bg|text|border)-(.+)$/.test(p)) {
-            if (!colorClassesByFile.has(path)) colorClassesByFile.set(path, new Set());
-            colorClassesByFile.get(path)!.add(p);
-            if (/\[#|\[rgb|\[hsl/.test(p.replace(/^(bg|text|border)-/, ""))) arbitraryColorByFile.set(path, true);
+            if (!colorClassesByFile.has(filePath)) colorClassesByFile.set(filePath, new Set());
+            colorClassesByFile.get(filePath)!.add(p);
+            if (/\[#|\[rgb|\[hsl/.test(p.replace(/^(bg|text|border)-/, ""))) arbitraryColorByFile.set(filePath, line);
           }
         }
       }
-      const btnClasses = extractButtonClassNames(ast);
-      if (btnClasses.length > 0) buttonClassesByFile.set(path, btnClasses);
+      const btnEntries = extractButtonClassNamesWithLine(ast);
+      if (btnEntries.length > 0) buttonDataByFile.set(filePath, btnEntries.map((e) => ({ classes: e.classes.split(/\s+/).filter(Boolean), line: e.line })));
 
       const normalized = normalizeJsxForHash(code);
       if (normalized.length > 50) {
         const hash = crypto.createHash("md5").update(normalized).digest("hex");
         if (!jsxHashes.has(hash)) jsxHashes.set(hash, []);
-        jsxHashes.get(hash)!.push(path);
+        jsxHashes.get(hash)!.push(filePath);
       }
     } catch {
       warnings.push({
-        file: path,
+        file: filePath,
         message: "Parse error (not valid JS/TS/JSX)",
         suggestion: "Check syntax, brackets, and that the file is valid JS/TS/JSX. Fix or remove the file from the scan.",
       });
     }
   }
 
-  for (const [, values] of spacingValues) {
-    if (values.size > 1) {
+  for (const [, data] of spacingData) {
+    if (data.values.size > 1) {
       warnings.push({
         file: "(project)",
-        message: `Mixed spacing values: ${[...values].join(", ")}`,
+        locations: data.locations.slice(0, MAX_LOCATIONS),
+        message: `Mixed spacing values: ${[...data.values].join(", ")}`,
         suggestion: "Pick one spacing scale (e.g. px-4, py-2) for similar elements and use it across the project so spacing stays consistent.",
       });
     }
   }
-  const radiusByFile = new Map<string, string[]>();
-  for (const [path, values] of radiusValues) radiusByFile.set(path, [...values]);
-  if (radiusByFile.size > 1) {
-    const unique = [...new Set([...radiusByFile.values()].flat())];
+  const radiusFileList = [...radiusByFile.entries()];
+  if (radiusFileList.length > 1) {
+    const unique = [...new Set(radiusFileList.flatMap(([, r]) => [...r.values]))];
     if (unique.length > 1) {
       warnings.push({
         file: "(project)",
+        locations: radiusFileList.map(([p, r]) => ({ file: p, line: r.line })).slice(0, MAX_LOCATIONS),
         message: `Inconsistent border-radius: ${unique.join(", ")}`,
         suggestion: "Use one radius token (e.g. rounded-lg) for cards and buttons so the UI looks consistent.",
       });
     }
   }
 
-  const filesWithArbitraryColors = [...arbitraryColorByFile.entries()].filter(([, v]) => v).map(([p]) => p);
-  if (filesWithArbitraryColors.length > 0) {
+  const arbitraryEntries = [...arbitraryColorByFile.entries()];
+  if (arbitraryEntries.length > 0) {
+    const [firstFile, line] = arbitraryEntries[0];
     warnings.push({
-      file: filesWithArbitraryColors[0],
+      file: firstFile,
+      line,
       message: "Arbitrary color values (e.g. bg-[#hex], text-[rgb()]) detected.",
       suggestion: "Prefer Tailwind palette classes (e.g. bg-zinc-100, text-emerald-600) for consistent theming and maintenance.",
     });
   }
 
-  const buttonPadding = new Map<string, Set<string>>();
-  const buttonRadius = new Map<string, Set<string>>();
-  for (const [filePath, classes] of buttonClassesByFile) {
-    for (const cn of classes) {
-      for (const p of cn.split(/\s+/)) {
+  const buttonPadding = new Map<string, { values: Set<string>; locations: { file: string; line: number }[] }>();
+  const buttonRadius = new Map<string, { values: Set<string>; line: number }[]>();
+  for (const [filePath, entries] of buttonDataByFile) {
+    for (const { classes: cn, line } of entries) {
+      for (const p of cn) {
         if (/^p[xy]?-[a-z0-9]+$/.test(p)) {
           const key = p.replace(/[0-9]+$/, "N");
-          if (!buttonPadding.has(key)) buttonPadding.set(key, new Set());
-          buttonPadding.get(key)!.add(p);
+          if (!buttonPadding.has(key)) buttonPadding.set(key, { values: new Set(), locations: [] });
+          const entry = buttonPadding.get(key)!;
+          entry.values.add(p);
+          if (entry.locations.length < MAX_LOCATIONS) entry.locations.push({ file: filePath, line });
         }
         if (/^rounded[a-z0-9-]*$/.test(p)) {
-          if (!buttonRadius.has(filePath)) buttonRadius.set(filePath, new Set());
-          buttonRadius.get(filePath)!.add(p);
+          if (!buttonRadius.has(filePath)) buttonRadius.set(filePath, []);
+          const arr = buttonRadius.get(filePath)!;
+          const existing = arr.find((x) => x.values.has(p));
+          if (!existing) arr.push({ values: new Set([p]), line });
+          else existing.values.add(p);
         }
       }
     }
   }
-  for (const [, values] of buttonPadding) {
-    if (values.size > 1) {
+  for (const [, data] of buttonPadding) {
+    if (data.values.size > 1) {
       warnings.push({
         file: "(project)",
-        message: `Mixed button padding: ${[...values].join(", ")}`,
+        locations: data.locations.slice(0, MAX_LOCATIONS),
+        message: `Mixed button padding: ${[...data.values].join(", ")}`,
         suggestion: "Use one button padding (e.g. px-4 py-2) across all buttons for a consistent look.",
       });
       break;
     }
   }
-  const allBtnRadius = [...buttonRadius.values()].flatMap((s) => [...s]);
-  if (allBtnRadius.length > 1 && new Set(allBtnRadius).size > 1) {
+  const allBtnRadiusValues = [...buttonRadius.values()].flatMap((arr) => arr.flatMap((r) => [...r.values]));
+  if (allBtnRadiusValues.length > 1 && new Set(allBtnRadiusValues).size > 1) {
+    const locations: { file: string; line: number }[] = [];
+    for (const [file, arr] of buttonRadius.entries()) {
+      if (arr.length > 0 && locations.length < MAX_LOCATIONS) locations.push({ file, line: arr[0].line });
+    }
     warnings.push({
       file: "(project)",
-      message: `Inconsistent button border-radius: ${[...new Set(allBtnRadius)].join(", ")}`,
+      locations,
+      message: `Inconsistent button border-radius: ${[...new Set(allBtnRadiusValues)].join(", ")}`,
       suggestion: "Use one radius (e.g. rounded-lg) for all buttons.",
     });
   }
@@ -213,7 +312,7 @@ function runAnalysis(fileContents: { path: string; code: string }[]): ScanResult
 
   const penalty = warnings.length * 5 + duplicates.length * 10;
   const score = Math.max(0, Math.min(100, 100 - penalty));
-  return { score, warnings, duplicates };
+  return { score, filesScanned: sourceOnly.length, warnings, duplicates };
 }
 
 export async function scanZip(buffer: Buffer): Promise<ScanResult> {