frontend-guardian 0.1.1

package/PUBLISH.md

@@ -0,0 +1,81 @@
+# Publish frontend-guardian to npm
+
+So anyone can run `npx frontend-guardian .` without your repo.
+
+## 1. npm account
+
+- Sign up at https://www.npmjs.com/signup
+- Login in terminal: `npm login` (username, password, email, OTP if 2FA)
+
+## 2. Check package name
+
+- If **frontend-guardian** is taken on npm, use a scoped name in `package.json`:  
+  `"name": "@YOUR_NPM_USERNAME/frontend-guardian"`  
+  Then users run: `npx @YOUR_NPM_USERNAME/frontend-guardian .`
+
+## 3. Publish core first (CLI depends on it)
+
+```bash
+cd C:/Users/ADMIN/Desktop/frontend-guardian
+pnpm run build:packages
+cd packages/core
+```
+
+In `packages/core/package.json` temporarily remove the line `"private": true` (or set to `false`).
+
+```bash
+npm publish --access public
+```
+
+(Scoped packages like `@frontend-guardian/core` need `--access public`.)
+
+Put `"private": true` back in core's package.json if you want to keep the repo from publishing it again by mistake.
+
+## 4. Point CLI to published core
+
+In `packages/cli/package.json`, change:
+
+```json
+"dependencies": {
+  "@frontend-guardian/core": "workspace:*"
+}
+```
+
+to:
+
+```json
+"dependencies": {
+  "@frontend-guardian/core": "^0.1.0"
+}
+```
+
+(Use the same version you published for core, e.g. `^0.1.0`.)
+
+## 5. Publish CLI
+
+```bash
+cd C:/Users/ADMIN/Desktop/frontend-guardian/packages/cli
+npm publish
+```
+
+If the name is scoped (`@YOUR_NPM_USERNAME/frontend-guardian`):
+
+```bash
+npm publish --access public
+```
+
+## 6. After publish
+
+Anyone can run:
+
+```bash
+npx frontend-guardian .
+```
+
+(or `npx @YOUR_NPM_USERNAME/frontend-guardian .` if you used a scoped name.)
+
+## Updating later
+
+1. Bump `version` in `packages/core/package.json` and `packages/cli/package.json`.
+2. In core: `npm publish --access public`
+3. In cli: set `"@frontend-guardian/core": "^0.1.1"` (or new version), then `npm publish` (or `--access public` if scoped).

package/README.md

@@ -0,0 +1,57 @@
+# frontend-guardian (CLI)
+
+Phase 1 CLI: scan a folder or ZIP for Tailwind & component consistency.
+
+## Local (from repo)
+
+```bash
+# Build packages first (once after clone)
+pnpm run build:packages
+
+# Run CLI
+pnpm cli <path>
+pnpm cli .
+pnpm cli ./src
+pnpm cli project.zip
+```
+
+Or run the built binary:
+
+```bash
+node packages/cli/dist/cli.js .
+```
+
+## Use globally (from repo, no publish)
+
+From repo root, after `pnpm run build:packages`:
+
+```bash
+cd packages/cli
+npm link
+```
+
+Then run `frontend-guardian .` from any folder. (On Windows/Git Bash, if `pnpm link --global` fails with PATH, use `npm link` instead.)
+
+## Publish to npm
+
+From repo root:
+
+```bash
+pnpm run build:packages
+cd packages/cli
+npm publish
+```
+
+Then anyone can run:
+
+```bash
+npx frontend-guardian .
+npx frontend-guardian ./src
+npx frontend-guardian project.zip
+```
+
+## Output
+
+- Score (0–100)
+- Warnings (spacing, radius, colors, buttons, unused imports, parse errors)
+- Duplicate components (same JSX structure)

package/dist/cli.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import chalk from "chalk";
+import ora from "ora";
+import { scanFiles, scanZip } from "@justinmoto/frontend-guardian-core";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const EXT = [".js", ".jsx", ".ts", ".tsx"];
+const IGNORE = ["node_modules", ".next", "dist", "build", ".git"];
+function isCodeFile(name) {
+    return EXT.some((e) => name.toLowerCase().endsWith(e));
+}
+function isSourcePath(relativePath) {
+    const normalized = relativePath.replace(/\\/g, "/");
+    return !IGNORE.some((part) => normalized.includes(part));
+}
+function readDirRecursive(dir, base = "") {
+    const out = [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const e of entries) {
+        const rel = base ? `${base}/${e.name}` : e.name;
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            if (IGNORE.includes(e.name))
+                continue;
+            out.push(...readDirRecursive(full, rel));
+        }
+        else if (e.isFile() && isCodeFile(e.name) && isSourcePath(rel)) {
+            try {
+                const code = fs.readFileSync(full, "utf-8");
+                out.push({ path: rel, code });
+            }
+            catch {
+                // skip
+            }
+        }
+    }
+    return out;
+}
+function issueType(w) {
+    const msg = w.message;
+    if (msg.startsWith("Mixed spacing values:"))
+        return { title: "Mixed Spacing", detected: msg.replace(/^Mixed spacing values:\s*/, "") };
+    if (msg.startsWith("Inconsistent border-radius:"))
+        return { title: "Inconsistent Border Radius", detected: msg.replace(/^Inconsistent border-radius:\s*/, "") };
+    if (msg.startsWith("Arbitrary color"))
+        return { title: "Arbitrary Colors", detected: msg };
+    if (msg.startsWith("Unused import:"))
+        return { title: "Unused Imports", detected: msg.replace(/^Unused import:\s*/, "") };
+    if (msg.startsWith("Parse error"))
+        return { title: "Parse Error", detected: msg };
+    if (msg.startsWith("Mixed button padding:"))
+        return { title: "Mixed Button Padding", detected: msg.replace(/^Mixed button padding:\s*/, "") };
+    if (msg.startsWith("Inconsistent button border-radius:"))
+        return { title: "Inconsistent Button Border Radius", detected: msg.replace(/^Inconsistent button border-radius:\s*/, "") };
+    return { title: "Other", detected: msg };
+}
+function scoreColor(score) {
+    if (score >= 70)
+        return chalk.green;
+    if (score >= 40)
+        return chalk.yellow;
+    return chalk.red;
+}
+const SHORT_SUGGESTION = {
+    "Mixed Spacing": "standardize spacing scale",
+    "Inconsistent Border Radius": "use one border radius token",
+    "Arbitrary Colors": "use Tailwind theme colors",
+    "Unused Imports": "remove unused imports",
+    "Parse Error": "fix syntax or remove file",
+    "Mixed Button Padding": "use one button padding",
+    "Inconsistent Button Border Radius": "use one radius for all buttons",
+    "Duplicate Components": "extract shared component and reuse",
+};
+function shortSuggestion(title, full) {
+    return SHORT_SUGGESTION[title] ?? (full.slice(0, 55) + (full.length > 55 ? "…" : ""));
+}
+const WRAP_WIDTH = 72;
+const INDENT = "     ";
+function wrapLine(prefix, text) {
+    const maxLen = WRAP_WIDTH - prefix.length;
+    if (text.length <= maxLen) {
+        console.log(prefix + text);
+        return;
+    }
+    let rest = text;
+    let first = true;
+    while (rest.length > 0) {
+        const use = first ? prefix : INDENT;
+        const allowed = WRAP_WIDTH - use.length;
+        if (rest.length <= allowed) {
+            console.log(use + rest);
+            break;
+        }
+        let breakAt = rest.slice(0, allowed).lastIndexOf(", ") + 1 || rest.slice(0, allowed).lastIndexOf("; ") + 1;
+        if (breakAt <= 0)
+            breakAt = allowed;
+        const chunk = rest.slice(0, breakAt).trim();
+        rest = rest.slice(breakAt).trim();
+        if (chunk)
+            console.log(use + chunk);
+        first = false;
+    }
+}
+function printResult(projectName, result) {
+    const line = chalk.gray("━".repeat(28));
+    console.log("\n" + line);
+    console.log(chalk.bold("  🛡 Frontend Guardian"));
+    console.log(line + "\n");
+    let filesScanned = "filesScanned" in result ? result.filesScanned : 0;
+    if (filesScanned === 0 && (result.warnings.length > 0 || result.duplicates.length > 0)) {
+        const files = new Set();
+        result.warnings.forEach((w) => files.add(w.file));
+        result.duplicates.forEach((d) => d.files.forEach((f) => files.add(f)));
+        filesScanned = files.size;
+    }
+    console.log("  Project: " + projectName);
+    console.log("  Files scanned: " + String(filesScanned));
+    const scoreColorFn = scoreColor(result.score);
+    console.log("  Consistency Score: " + scoreColorFn(result.score + " / 100"));
+    console.log(chalk.gray("  (each warning −5, each duplicate group −10, from 100)") + "\n");
+    const byTitle = new Map();
+    for (const w of result.warnings) {
+        const { title, detected } = issueType(w);
+        const sug = w.suggestion ?? "";
+        if (!byTitle.has(title))
+            byTitle.set(title, { detected: [], suggestion: sug });
+        const entry = byTitle.get(title);
+        if (!entry.detected.includes(detected))
+            entry.detected.push(detected);
+    }
+    for (const d of result.duplicates) {
+        const title = "Duplicate Components";
+        const detected = d.files.join(", ");
+        if (!byTitle.has(title))
+            byTitle.set(title, { detected: [], suggestion: d.suggestion ?? "" });
+        byTitle.get(title).detected.push(detected);
+    }
+    const allIssues = [...byTitle.entries()].map(([title, { detected, suggestion }]) => ({
+        title,
+        detected: detected.join("; "),
+        suggestion: shortSuggestion(title, suggestion),
+    }));
+    if (allIssues.length > 0) {
+        console.log(chalk.yellow("  ⚠ ") + chalk.bold("Issues Found") + "\n");
+        allIssues.forEach((issue, i) => {
+            console.log("  " + (i + 1) + ". " + issue.title);
+            if (issue.title === "Unused Imports") {
+                wrapLine(INDENT, issue.detected);
+            }
+            else {
+                wrapLine(INDENT + "Detected: ", issue.detected);
+                console.log(INDENT + "Suggestion: " + issue.suggestion);
+            }
+            if (i < allIssues.length - 1)
+                console.log("");
+        });
+        console.log("");
+    }
+    console.log(line);
+    console.log(chalk.bold("  Scan Complete") + "\n");
+}
+async function main() {
+    const arg = process.argv[2];
+    if (!arg) {
+        console.error("Usage: frontend-guardian <path>");
+        console.error("       npx frontend-guardian .");
+        console.error("       npx frontend-guardian ./src");
+        console.error("       npx frontend-guardian project.zip");
+        process.exit(1);
+    }
+    const resolved = path.resolve(process.cwd(), arg);
+    if (!fs.existsSync(resolved)) {
+        console.error("Path not found:", resolved);
+        process.exit(1);
+    }
+    const projectName = path.basename(resolved).replace(/\.zip$/i, "") || "project";
+    const stat = fs.statSync(resolved);
+    let result;
+    if (stat.isDirectory()) {
+        const files = readDirRecursive(resolved);
+        if (files.length === 0) {
+            console.error("No .js/.jsx/.ts/.tsx files found (or all under node_modules/.next/dist/build).");
+            process.exit(1);
+        }
+        const spinner = ora("Scanning " + files.length + " file(s)...").start();
+        try {
+            result = scanFiles(files);
+            spinner.succeed("Scan complete.");
+        }
+        catch (e) {
+            spinner.fail("Scan failed.");
+            throw e;
+        }
+    }
+    else if (resolved.toLowerCase().endsWith(".zip")) {
+        const spinner = ora("Scanning ZIP...").start();
+        try {
+            const buf = fs.readFileSync(resolved);
+            result = await scanZip(buf);
+            spinner.succeed("Scan complete.");
+        }
+        catch (e) {
+            spinner.fail("Scan failed.");
+            throw e;
+        }
+    }
+    else {
+        console.error("Provide a folder path or a .zip file.");
+        process.exit(1);
+    }
+    printResult(projectName, result);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "frontend-guardian",
+  "version": "0.1.1",
+  "description": "Scan frontend projects for Tailwind & component consistency (Phase 1 CLI)",
+  "type": "module",
+  "bin": {
+    "frontend-guardian": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@justinmoto/frontend-guardian-core": "^0.1.2",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["tailwind", "consistency", "frontend", "scan", "cli"],
+  "license": "MIT"
+}

package/src/cli.ts

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import chalk from "chalk";
+import ora from "ora";
+import { scanFiles, scanZip, type ScanResult, type Warning } from "@justinmoto/frontend-guardian-core";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const EXT = [".js", ".jsx", ".ts", ".tsx"];
+const IGNORE = ["node_modules", ".next", "dist", "build", ".git"];
+
+function isCodeFile(name: string): boolean {
+  return EXT.some((e) => name.toLowerCase().endsWith(e));
+}
+
+function isSourcePath(relativePath: string): boolean {
+  const normalized = relativePath.replace(/\\/g, "/");
+  return !IGNORE.some((part) => normalized.includes(part));
+}
+
+function readDirRecursive(dir: string, base = ""): { path: string; code: string }[] {
+  const out: { path: string; code: string }[] = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const rel = base ? `${base}/${e.name}` : e.name;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (IGNORE.includes(e.name)) continue;
+      out.push(...readDirRecursive(full, rel));
+    } else if (e.isFile() && isCodeFile(e.name) && isSourcePath(rel)) {
+      try {
+        const code = fs.readFileSync(full, "utf-8");
+        out.push({ path: rel, code });
+      } catch {
+        // skip
+      }
+    }
+  }
+  return out;
+}
+
+function issueType(w: Warning): { title: string; detected: string } {
+  const msg = w.message;
+  if (msg.startsWith("Mixed spacing values:"))
+    return { title: "Mixed Spacing", detected: msg.replace(/^Mixed spacing values:\s*/, "") };
+  if (msg.startsWith("Inconsistent border-radius:"))
+    return { title: "Inconsistent Border Radius", detected: msg.replace(/^Inconsistent border-radius:\s*/, "") };
+  if (msg.startsWith("Arbitrary color"))
+    return { title: "Arbitrary Colors", detected: msg };
+  if (msg.startsWith("Unused import:"))
+    return { title: "Unused Imports", detected: msg.replace(/^Unused import:\s*/, "") };
+  if (msg.startsWith("Parse error"))
+    return { title: "Parse Error", detected: msg };
+  if (msg.startsWith("Mixed button padding:"))
+    return { title: "Mixed Button Padding", detected: msg.replace(/^Mixed button padding:\s*/, "") };
+  if (msg.startsWith("Inconsistent button border-radius:"))
+    return { title: "Inconsistent Button Border Radius", detected: msg.replace(/^Inconsistent button border-radius:\s*/, "") };
+  return { title: "Other", detected: msg };
+}
+
+function scoreColor(score: number): (s: string) => string {
+  if (score >= 70) return chalk.green;
+  if (score >= 40) return chalk.yellow;
+  return chalk.red;
+}
+
+const SHORT_SUGGESTION: Record<string, string> = {
+  "Mixed Spacing": "standardize spacing scale",
+  "Inconsistent Border Radius": "use one border radius token",
+  "Arbitrary Colors": "use Tailwind theme colors",
+  "Unused Imports": "remove unused imports",
+  "Parse Error": "fix syntax or remove file",
+  "Mixed Button Padding": "use one button padding",
+  "Inconsistent Button Border Radius": "use one radius for all buttons",
+  "Duplicate Components": "extract shared component and reuse",
+};
+
+function shortSuggestion(title: string, full: string): string {
+  return SHORT_SUGGESTION[title] ?? (full.slice(0, 55) + (full.length > 55 ? "…" : ""));
+}
+
+const WRAP_WIDTH = 72;
+const INDENT = "     ";
+
+function wrapLine(prefix: string, text: string): void {
+  const maxLen = WRAP_WIDTH - prefix.length;
+  if (text.length <= maxLen) {
+    console.log(prefix + text);
+    return;
+  }
+  let rest = text;
+  let first = true;
+  while (rest.length > 0) {
+    const use = first ? prefix : INDENT;
+    const allowed = WRAP_WIDTH - use.length;
+    if (rest.length <= allowed) {
+      console.log(use + rest);
+      break;
+    }
+    let breakAt = rest.slice(0, allowed).lastIndexOf(", ") + 1 || rest.slice(0, allowed).lastIndexOf("; ") + 1;
+    if (breakAt <= 0) breakAt = allowed;
+    const chunk = rest.slice(0, breakAt).trim();
+    rest = rest.slice(breakAt).trim();
+    if (chunk) console.log(use + chunk);
+    first = false;
+  }
+}
+
+function printResult(projectName: string, result: ScanResult) {
+  const line = chalk.gray("━".repeat(28));
+  console.log("\n" + line);
+  console.log(chalk.bold("  🛡 Frontend Guardian"));
+  console.log(line + "\n");
+
+  let filesScanned = "filesScanned" in result ? (result as ScanResult & { filesScanned?: number }).filesScanned : 0;
+  if (filesScanned === 0 && (result.warnings.length > 0 || result.duplicates.length > 0)) {
+    const files = new Set<string>();
+    result.warnings.forEach((w) => files.add(w.file));
+    result.duplicates.forEach((d) => d.files.forEach((f) => files.add(f)));
+    filesScanned = files.size;
+  }
+  console.log("  Project: " + projectName);
+  console.log("  Files scanned: " + String(filesScanned));
+  const scoreColorFn = scoreColor(result.score);
+  console.log("  Consistency Score: " + scoreColorFn(result.score + " / 100"));
+  console.log(chalk.gray("  (each warning −5, each duplicate group −10, from 100)") + "\n");
+
+  const byTitle = new Map<string, { detected: string[]; suggestion: string }>();
+  for (const w of result.warnings) {
+    const { title, detected } = issueType(w);
+    const sug = w.suggestion ?? "";
+    if (!byTitle.has(title)) byTitle.set(title, { detected: [], suggestion: sug });
+    const entry = byTitle.get(title)!;
+    if (!entry.detected.includes(detected)) entry.detected.push(detected);
+  }
+  for (const d of result.duplicates) {
+    const title = "Duplicate Components";
+    const detected = d.files.join(", ");
+    if (!byTitle.has(title)) byTitle.set(title, { detected: [], suggestion: d.suggestion ?? "" });
+    byTitle.get(title)!.detected.push(detected);
+  }
+
+  const allIssues = [...byTitle.entries()].map(([title, { detected, suggestion }]) => ({
+    title,
+    detected: detected.join("; "),
+    suggestion: shortSuggestion(title, suggestion),
+  }));
+
+  if (allIssues.length > 0) {
+    console.log(chalk.yellow("  ⚠ ") + chalk.bold("Issues Found") + "\n");
+    allIssues.forEach((issue, i) => {
+      console.log("  " + (i + 1) + ". " + issue.title);
+      if (issue.title === "Unused Imports") {
+        wrapLine(INDENT, issue.detected);
+      } else {
+        wrapLine(INDENT + "Detected: ", issue.detected);
+        console.log(INDENT + "Suggestion: " + issue.suggestion);
+      }
+      if (i < allIssues.length - 1) console.log("");
+    });
+    console.log("");
+  }
+
+  console.log(line);
+  console.log(chalk.bold("  Scan Complete") + "\n");
+}
+
+async function main() {
+  const arg = process.argv[2];
+  if (!arg) {
+    console.error("Usage: frontend-guardian <path>");
+    console.error("       npx frontend-guardian .");
+    console.error("       npx frontend-guardian ./src");
+    console.error("       npx frontend-guardian project.zip");
+    process.exit(1);
+  }
+  const resolved = path.resolve(process.cwd(), arg);
+  if (!fs.existsSync(resolved)) {
+    console.error("Path not found:", resolved);
+    process.exit(1);
+  }
+  const projectName = path.basename(resolved).replace(/\.zip$/i, "") || "project";
+
+  const stat = fs.statSync(resolved);
+  let result: ScanResult;
+
+  if (stat.isDirectory()) {
+    const files = readDirRecursive(resolved);
+    if (files.length === 0) {
+      console.error("No .js/.jsx/.ts/.tsx files found (or all under node_modules/.next/dist/build).");
+      process.exit(1);
+    }
+    const spinner = ora("Scanning " + files.length + " file(s)...").start();
+    try {
+      result = scanFiles(files);
+      spinner.succeed("Scan complete.");
+    } catch (e) {
+      spinner.fail("Scan failed.");
+      throw e;
+    }
+  } else if (resolved.toLowerCase().endsWith(".zip")) {
+    const spinner = ora("Scanning ZIP...").start();
+    try {
+      const buf = fs.readFileSync(resolved);
+      result = await scanZip(buf);
+      spinner.succeed("Scan complete.");
+    } catch (e) {
+      spinner.fail("Scan failed.");
+      throw e;
+    }
+  } else {
+    console.error("Provide a folder path or a .zip file.");
+    process.exit(1);
+  }
+
+  printResult(projectName, result);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/tsconfig.json

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