@justinmoto/frontend-guardian-core 0.1.0

package/babel-traverse.d.ts

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { scanZip, scanFiles, type ScanResult, type Warning, type Duplicate } from "./scanEngine.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

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

package/dist/scanEngine.d.ts

@@ -0,0 +1,21 @@
+export type Warning = {
+    file: string;
+    message: string;
+    suggestion?: string;
+};
+export type Duplicate = {
+    files: string[];
+    reason?: string;
+    suggestion?: string;
+};
+export type ScanResult = {
+    score: number;
+    warnings: Warning[];
+    duplicates: Duplicate[];
+};
+export declare function scanZip(buffer: Buffer): Promise<ScanResult>;
+export declare function scanFiles(files: {
+    path: string;
+    code: string;
+}[]): ScanResult;
+//# sourceMappingURL=scanEngine.d.ts.map

package/dist/scanEngine.d.ts.map

@@ -0,0 +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"}

package/dist/scanEngine.js

@@ -0,0 +1,234 @@
+import * as parser from "@babel/parser";
+import _traverse from "@babel/traverse";
+const traverse = (typeof _traverse === "function" ? _traverse : _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"];
+function isCodeFile(path) {
+    return EXT.some((e) => path.toLowerCase().endsWith(e));
+}
+function isSourcePath(path) {
+    const normalized = path.replace(/\\/g, "/");
+    return !IGNORE_PATH_PARTS.some((part) => normalized.includes(part));
+}
+function extractClassNames(ast) {
+    const classes = [];
+    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);
+            }
+        },
+    });
+    return classes;
+}
+function normalizeJsxForHash(code) {
+    return code
+        .replace(/\s+/g, " ")
+        .replace(/\bclassName="[^"]*"/g, 'className=""')
+        .replace(/\bclassName=\{[^}]*\}/g, "className={}")
+        .trim();
+}
+function extractButtonClassNames(ast) {
+    const classes = [];
+    traverse(ast, {
+        JSXOpeningElement(path) {
+            const name = path.node.name;
+            const tagName = name.type === "JSXIdentifier" ? name.name : "";
+            let className = "";
+            for (const attr of path.node.attributes) {
+                if (attr.type === "JSXAttribute" && attr.name?.name === "className" && attr.value?.type === "StringLiteral") {
+                    className = attr.value.value;
+                    break;
+                }
+            }
+            const isButton = tagName === "button" || (typeof className === "string" && /btn|button/i.test(className));
+            if (isButton && className)
+                classes.push(className);
+        },
+    });
+    return classes;
+}
+function getUnusedImports(ast) {
+    const unused = [];
+    traverse(ast, {
+        ImportDeclaration(path) {
+            for (const spec of path.node.specifiers) {
+                const s = spec;
+                const local = s.local?.name;
+                if (!local)
+                    continue;
+                if (s.importKind === "type" || s.importKind === "typeof")
+                    continue;
+                const binding = path.scope.getBinding(local);
+                if (binding && !binding.referenced)
+                    unused.push(local);
+            }
+        },
+    });
+    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 colorClassesByFile = new Map();
+    const arbitraryColorByFile = new Map();
+    const buttonClassesByFile = new Map();
+    for (const { path, code } of sourceOnly) {
+        try {
+            const ast = parser.parse(code, { sourceType: "module", plugins: ["jsx", "typescript"] });
+            const unused = getUnusedImports(ast);
+            for (const name of unused) {
+                warnings.push({
+                    file: path,
+                    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 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 (/^rounded[a-z0-9-]*$/.test(p)) {
+                        if (!radiusValues.has(path))
+                            radiusValues.set(path, new Set());
+                        radiusValues.get(path).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);
+                    }
+                }
+            }
+            const btnClasses = extractButtonClassNames(ast);
+            if (btnClasses.length > 0)
+                buttonClassesByFile.set(path, btnClasses);
+            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);
+            }
+        }
+        catch {
+            warnings.push({
+                file: path,
+                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) {
+            warnings.push({
+                file: "(project)",
+                message: `Mixed spacing values: ${[...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())];
+        if (unique.length > 1) {
+            warnings.push({
+                file: "(project)",
+                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) {
+        warnings.push({
+            file: filesWithArbitraryColors[0],
+            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+/)) {
+                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 (/^rounded[a-z0-9-]*$/.test(p)) {
+                    if (!buttonRadius.has(filePath))
+                        buttonRadius.set(filePath, new Set());
+                    buttonRadius.get(filePath).add(p);
+                }
+            }
+        }
+    }
+    for (const [, values] of buttonPadding) {
+        if (values.size > 1) {
+            warnings.push({
+                file: "(project)",
+                message: `Mixed button padding: ${[...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) {
+        warnings.push({
+            file: "(project)",
+            message: `Inconsistent button border-radius: ${[...new Set(allBtnRadius)].join(", ")}`,
+            suggestion: "Use one radius (e.g. rounded-lg) for all buttons.",
+        });
+    }
+    const duplicates = [];
+    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, warnings, duplicates };
+}
+export async function scanZip(buffer) {
+    const zip = await JSZip.loadAsync(buffer);
+    const fileContents = [];
+    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) {
+    const filtered = files.filter((f) => isCodeFile(f.path) && isSourcePath(f.path));
+    return runAnalysis(filtered);
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@justinmoto/frontend-guardian-core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.26.0",
+    "@babel/traverse": "^7.26.0",
+    "jszip": "^3.10.1"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.ts

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

package/src/scanEngine.ts

@@ -0,0 +1,237 @@
+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; message: string; suggestion?: string };
+export type Duplicate = { files: string[]; reason?: string; suggestion?: string };
+export type ScanResult = { score: 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 extractClassNames(ast: ReturnType<typeof parser.parse>): string[] {
+  const classes: string[] = [];
+  traverse(ast, {
+    JSXAttribute(path: { node: { name: { type: string; name: string }; value?: { type: string; value: string } } }) {
+      if (path.node.name.type === "JSXIdentifier" && path.node.name.name === "className") {
+        const val = path.node.value;
+        if (val?.type === "StringLiteral") classes.push(val.value);
+      }
+    },
+  });
+  return classes;
+}
+
+function normalizeJsxForHash(code: string): string {
+  return code
+    .replace(/\s+/g, " ")
+    .replace(/\bclassName="[^"]*"/g, 'className=""')
+    .replace(/\bclassName=\{[^}]*\}/g, "className={}")
+    .trim();
+}
+
+function extractButtonClassNames(ast: ReturnType<typeof parser.parse>): string[] {
+  const classes: string[] = [];
+  traverse(ast, {
+    JSXOpeningElement(path: { node: { name: { type: string; name: string }; attributes: unknown[] } }) {
+      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 isButton = tagName === "button" || (typeof className === "string" && /btn|button/i.test(className));
+      if (isButton && className) classes.push(className);
+    },
+  });
+  return classes;
+}
+
+function getUnusedImports(ast: ReturnType<typeof parser.parse>): string[] {
+  const unused: string[] = [];
+  traverse(ast, {
+    ImportDeclaration(path: { node: { specifiers: unknown[] }; scope: { getBinding: (n: string) => { referenced: boolean } | undefined } }) {
+      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;
+        const binding = path.scope.getBinding(local);
+        if (binding && !binding.referenced) unused.push(local);
+      }
+    },
+  });
+  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 colorClassesByFile = new Map<string, Set<string>>();
+  const arbitraryColorByFile = new Map<string, boolean>();
+  const buttonClassesByFile = new Map<string, string[]>();
+
+  for (const { path, code } of sourceOnly) {
+    try {
+      const ast = parser.parse(code, { sourceType: "module", plugins: ["jsx", "typescript"] });
+      const unused = getUnusedImports(ast);
+      for (const name of unused) {
+        warnings.push({
+          file: path,
+          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 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 (/^rounded[a-z0-9-]*$/.test(p)) {
+            if (!radiusValues.has(path)) radiusValues.set(path, new Set());
+            radiusValues.get(path)!.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);
+          }
+        }
+      }
+      const btnClasses = extractButtonClassNames(ast);
+      if (btnClasses.length > 0) buttonClassesByFile.set(path, btnClasses);
+
+      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);
+      }
+    } catch {
+      warnings.push({
+        file: path,
+        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) {
+      warnings.push({
+        file: "(project)",
+        message: `Mixed spacing values: ${[...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())];
+    if (unique.length > 1) {
+      warnings.push({
+        file: "(project)",
+        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) {
+    warnings.push({
+      file: filesWithArbitraryColors[0],
+      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+/)) {
+        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 (/^rounded[a-z0-9-]*$/.test(p)) {
+          if (!buttonRadius.has(filePath)) buttonRadius.set(filePath, new Set());
+          buttonRadius.get(filePath)!.add(p);
+        }
+      }
+    }
+  }
+  for (const [, values] of buttonPadding) {
+    if (values.size > 1) {
+      warnings.push({
+        file: "(project)",
+        message: `Mixed button padding: ${[...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) {
+    warnings.push({
+      file: "(project)",
+      message: `Inconsistent button border-radius: ${[...new Set(allBtnRadius)].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, 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

@@ -0,0 +1,15 @@
+{
+  "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"]
+}