@justinmoto/frontend-guardian-core 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justinmoto/frontend-guardian-core",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Scan engine for Frontend Guardian. To run scans from the CLI use: npx frontend-guardian .",
   "type": "module",
   "main": "dist/index.js",
@@ -12,6 +12,7 @@
       "default": "./dist/index.js"
     }
   },
+  "files": ["dist", "README.md"],
   "scripts": {
     "build": "tsc"
   },

package/babel-traverse.d.ts

@@ -1,3 +0,0 @@
-declare module "@babel/traverse" {
-  export default function traverse(ast: unknown, visitors: Record<string, unknown>): void;
-}

package/src/index.ts

@@ -1 +0,0 @@
-export { scanZip, scanFiles, type ScanResult, type Warning, type Duplicate } from "./scanEngine.js";

package/src/scanEngine.ts

@@ -1,336 +0,0 @@
-import * as parser from "@babel/parser";
-import _traverse from "@babel/traverse";
-const traverse = (typeof _traverse === "function" ? _traverse : (_traverse as { default: typeof _traverse }).default)!;
-import * as crypto from "crypto";
-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;
-  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; filesScanned: number; warnings: Warning[]; duplicates: Duplicate[] };
-
-function isCodeFile(path: string): boolean {
-  return EXT.some((e) => path.toLowerCase().endsWith(e));
-}
-
-function isSourcePath(path: string): boolean {
-  const normalized = path.replace(/\\/g, "/");
-  return !IGNORE_PATH_PARTS.some((part) => normalized.includes(part));
-}
-
-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 }; loc?: { start: { line: number } } } }) {
-      if (path.node.name.type === "JSXIdentifier" && path.node.name.name === "className") {
-        const val = path.node.value;
-        if (val?.type === "StringLiteral") {
-          const line = path.node.loc?.start?.line ?? 0;
-          out.push({ value: val.value, line });
-        }
-      }
-    },
-  });
-  return out;
-}
-
-function normalizeJsxForHash(code: string): string {
-  return code
-    .replace(/\s+/g, " ")
-    .replace(/\bclassName="[^"]*"/g, 'className=""')
-    .replace(/\bclassName=\{[^}]*\}/g, "className={}")
-    .trim();
-}
-
-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[]; loc?: { start: { line: number } } } }) {
-      const name = path.node.name;
-      const tagName = name.type === "JSXIdentifier" ? name.name : "";
-      let className = "";
-      for (const attr of path.node.attributes as { type: string; name?: { name: string }; value?: { type: string; value: string } }[]) {
-        if (attr.type === "JSXAttribute" && attr.name?.name === "className" && attr.value?.type === "StringLiteral") {
-          className = attr.value.value;
-          break;
-        }
-      }
-      const line = path.node.loc?.start?.line ?? 0;
-      const isButton = tagName === "button" || (typeof className === "string" && /btn|button/i.test(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 used;
-}
-
-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[]; 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({ 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 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, number>();
-  const buttonDataByFile = new Map<string, { classes: string[]; line: number }[]>();
-
-  const MAX_LOCATIONS = 25;
-
-  for (const { path: filePath, code } of sourceOnly) {
-    try {
-      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: 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 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 (!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 (!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(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 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(filePath);
-      }
-    } catch {
-      warnings.push({
-        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 [, data] of spacingData) {
-    if (data.values.size > 1) {
-      warnings.push({
-        file: "(project)",
-        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 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 arbitraryEntries = [...arbitraryColorByFile.entries()];
-  if (arbitraryEntries.length > 0) {
-    const [firstFile, line] = arbitraryEntries[0];
-    warnings.push({
-      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, { 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, { 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, []);
-          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 [, data] of buttonPadding) {
-    if (data.values.size > 1) {
-      warnings.push({
-        file: "(project)",
-        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 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)",
-      locations,
-      message: `Inconsistent button border-radius: ${[...new Set(allBtnRadiusValues)].join(", ")}`,
-      suggestion: "Use one radius (e.g. rounded-lg) for all buttons.",
-    });
-  }
-
-  const duplicates: Duplicate[] = [];
-  const dupReason = "Same JSX structure (excluding class names) — likely copy-pasted or very similar components.";
-  const dupSuggestion = "Extract into one shared component and reuse it; this avoids drift and makes updates easier.";
-  for (const files of jsxHashes.values()) {
-    if (files.length > 1) duplicates.push({ files, reason: dupReason, suggestion: dupSuggestion });
-  }
-
-  const penalty = warnings.length * 5 + duplicates.length * 10;
-  const score = Math.max(0, Math.min(100, 100 - penalty));
-  return { score, filesScanned: sourceOnly.length, warnings, duplicates };
-}
-
-export async function scanZip(buffer: Buffer): Promise<ScanResult> {
-  const zip = await JSZip.loadAsync(buffer);
-  const fileContents: { path: string; code: string }[] = [];
-  for (const [path, entry] of Object.entries(zip.files)) {
-    if (entry.dir || !isCodeFile(path) || !isSourcePath(path)) continue;
-    try {
-      const code = await entry.async("string");
-      fileContents.push({ path, code });
-    } catch {
-      fileContents.push({ path, code: "" });
-    }
-  }
-  return runAnalysis(fileContents);
-}
-
-export function scanFiles(files: { path: string; code: string }[]): ScanResult {
-  const filtered = files.filter((f) => isCodeFile(f.path) && isSourcePath(f.path));
-  return runAnalysis(filtered);
-}

package/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "outDir": "dist",
-    "rootDir": "src",
-    "strict": true,
-    "skipLibCheck": true,
-    "declaration": true,
-    "declarationMap": true
-  },
-  "include": ["src/**/*.ts", "*.d.ts"],
-  "exclude": ["node_modules", "dist"]
-}