deployscout 1.0.1

package/Project.md

@@ -0,0 +1,206 @@
+# DeployScout — PROJECT.md
+
+
+ 
+
+## 1. The problem (the 30-second pitch)
+
+MERN apps routinely work perfectly in local dev and break the moment
+they're deployed — not because of bad code, but because of **environment
+assumptions** that only become visible in a different environment.
+
+Examples that have personally happened to me, building and deploying a
+real app (Affinity, a MERN chat app):
+
+- Hardcoded `localhost` URLs in API calls and socket connections
+- CORS configured with a dev-only origin (`http://localhost:3000`)
+  hardcoded, instead of reading from an environment variable
+- Cookies set with `sameSite: "strict"`, which silently breaks
+  authentication the moment frontend and backend are on different domains
+- A monorepo where the deploy host couldn't find the entry file because
+  the root directory wasn't configured
+
+None of these are *logic* bugs. The code is "correct" — it just makes an
+assumption (same origin, same machine, same `localhost`) that's true in
+dev and false in prod. **Generic linters and code reviewers don't catch
+this category of bug**, because there's nothing syntactically wrong with
+the code. ESLint won't flag `origin: 'http://localhost:3000'` — it's
+perfectly valid JavaScript. The problem only exists in the *relationship*
+between this code and where it's about to be deployed.
+
+**This is the gap DeployScout fills**: it doesn't check if your code is
+well-written. It checks if your code's environment assumptions will
+survive contact with a real deployment.
+
+---
+
+## 2. Why this isn't "just another linter" (the question to expect)
+
+Tools that already exist, and exactly what they don't cover:
+
+| Tool | What it does | What it misses |
+|---|---|---|
+| ESLint | Syntax, style, logic bugs | Has no concept of "this string will be a different value in production" |
+| gitleaks / truffleHog | Finds committed secrets via pattern matching | Doesn't understand CORS, cookies, or deployment config at all |
+| npm audit / Snyk | Dependency vulnerabilities | Unrelated problem space entirely |
+| CodeRabbit / Qodo | General AI code review (bugs, style, security) | Broad and generic — not specialized in dev-vs-prod environment mismatches, and doesn't reason about *why* a specific config breaks in *your* specific deployment context |
+
+**The honest differentiator:** existing tools can tell you "this is a
+string" or "this matches a secret pattern." None of them understand that
+`cors({ origin: 'http://localhost:3000' })` is *structurally fine* but
+*semantically broken* for production — that requires understanding what
+CORS does, what `sameSite` cookies require, and why `localhost` never
+matches a deployed origin. That's domain reasoning, not pattern matching,
+which is why this tool uses AST analysis (to understand code structure)
+combined with an LLM explanation step (to reason about *why* it matters
+in context) — not just regex.
+
+---
+
+## 3. Explicit scope boundaries
+
+**This tool does NOT:**
+- Act as a general code reviewer (that's CodeRabbit's job)
+- Scan for dependency vulnerabilities (that's `npm audit`/Snyk's job)
+- Scan git history for committed secrets (that's `gitleaks`'s job)
+- Monitor live/deployed apps or logs (out of scope for all phases — this
+  is a pre-deploy static check, not an APM tool)
+- Support non-MERN stacks in v1 (Next.js, Django, etc. — explicitly out
+  of scope until the core engine is proven)
+
+Knowing what this *isn't* is as important as what it is — it's what
+keeps the pitch sharp instead of "an AI tool that does everything."
+
+---
+
+## 4. Functional & non-functional requirements
+
+### Functional
+| ID | Requirement | Status |
+|---|---|---|
+| FR1 | Detect hardcoded `localhost` URLs in API calls/sockets | Not started |
+| FR2 | Detect missing `.env.example` vs. used env vars | Not started |
+| FR3 | Detect CORS misconfiguration (`cors` package, hardcoded origin) | **Built — Phase 1** |
+| FR3b | Detect CORS misconfiguration (manual `res.header(...)` pattern) | Planned — Phase 1.5 |
+| FR4 | Detect risky cookie config (`sameSite: strict` + cross-origin intent) | Not started |
+| FR5 | Detect case-sensitivity import risks (Windows/Mac vs. Linux) | Not started |
+| FR6 | Detect entry-point/monorepo root mismatches | Not started |
+| FR7 | LLM-generated plain-English explanation per finding | Not started |
+| FR8 | Structured terminal report output | **Built — Phase 1** |
+| FR9 | Non-zero exit code on critical findings (CI-ready) | **Built — Phase 1** |
+
+### Non-functional
+| ID | Requirement |
+|---|---|
+| NFR1 | Works on any MERN repo structure without manual config |
+| NFR2 | Static analysis runs with zero API calls; LLM only called on actual findings |
+| NFR3 | Low false-positive rate is prioritized over coverage breadth in v1 |
+| NFR4 | Full scan completes in under ~10 seconds for a typical repo |
+| NFR5 | Only the flagged snippet + minimal context is sent to the LLM, never the full file/repo |
+
+---
+
+## 5. Architecture
+
+```
+repo to scan
+     │
+     ▼
+scanner.js  ──────►  finds candidate .js/.jsx files (fast-glob, ignores node_modules)
+     │
+     ▼
+rules/*.js  ──────►  one file per concern (cors.js, cookies.js, env-vars.js, ...)
+     │                each rule: parse file → AST (@babel/parser)
+     │                          → traverse (@babel/traverse)
+     │                          → return findings[]
+     ▼
+cli.js      ──────►  wires scanner + all rules together, formats output (chalk)
+     │
+     ▼
+explain.js  ──────►  (Phase 2) takes findings, calls LLM for context-aware
+                      explanations beyond the rule's built-in message
+```
+
+**Why AST instead of regex:** regex can't reliably distinguish "a string
+that happens to contain `localhost`" from "the actual `origin` property
+of an actual CORS config object." It also can't resolve a variable
+reference back to its declaration. AST parsing gives the tool real
+understanding of code *structure*, not just text patterns — this was
+proven necessary almost immediately: the real Affinity bug used
+`cors(corsOption)` (a variable reference), not `cors({...})` (an inline
+object), and only AST + scope resolution could trace that correctly.
+
+---
+
+## 6. Decisions log (the "why did you do it this way" answers)
+
+Keeping this section honest and current is what makes this document
+actually useful in an interview — it's the paper trail of real
+engineering judgment calls, not just a feature list.
+
+- **Decided to scope Phase 1 to ONE rule (CORS, `cors` package pattern
+  only), built completely end-to-end, rather than partial coverage of
+  many rules.** Reasoning: a fully working narrow slice proves the
+  architecture; a half-built wide slice proves nothing and is hard to
+  debug.
+
+- **Decided NOT to flag `origin: process.env.X || 'http://localhost:3000'`
+  in v1**, even though the `localhost` fallback is still technically
+  present and still a real risk. Reasoning: this value is a
+  `LogicalExpression`, not a plain `StringLiteral` — handling it correctly
+  requires recursively checking both sides of the `||`, which is a known,
+  deliberate v1 limitation, not an oversight. Documented here so it can
+  be explained honestly rather than discovered as a "bug" later.
+
+- **Decided to resolve variable references** (`cors(corsOption)` →
+  trace back to `const corsOption = {...}`) rather than only matching
+  inline objects (`cors({...})`). Reasoning: the real-world bug that
+  motivated this whole project used the variable pattern, not the inline
+  one — building the simpler version first would have meant the tool
+  couldn't catch its own origin story's bug.
+
+- **Decided to use regex/static-analysis first, LLM only for explanation,
+  not detection.** Reasoning: deterministic detection means reliable,
+  fast, free-to-run core checks; the LLM's job is narrowly to explain
+  *why* something matters in plain English, not to decide *if* something
+  is wrong — keeps cost and false-positive risk down.
+
+- **Found a second real CORS pattern (manual `res.header(...)` calls,
+  not the `cors` package) while building test fixtures.** Decided to
+  defer this to Phase 1.5 rather than build both patterns simultaneously,
+  to keep Phase 1 finishable and provably complete before expanding.
+
+---
+
+## 7. Phase plan
+
+| Phase | Scope | Status |
+|---|---|---|
+| **Phase 1** | CLI scans a repo, detects CORS issues (`cors` package, hardcoded localhost origin, inline + variable reference), prints terminal report, exits non-zero on critical | ✅ Built, tested on real positive case |
+| **Phase 1.5** | Add second CORS pattern: manual `res.header("Access-Control-Allow-Origin", ...)` detection | Planned |
+| **Phase 2** | `explain.js` — LLM call (Gemini) to generate context-aware explanations per finding | Planned |
+| **Phase 3** | Additional rules: env vars, cookies, case-sensitivity, entry-point mismatch | Planned |
+| **Phase 4** | GitHub Action surface (same engine, CI-integrated) | Planned |
+| **Phase 5** | VS Code extension (inline flagging) | Stretch goal |
+
+---
+
+## 8. Validation so far
+
+- ✅ Tested against a real, lived bug (Affinity's actual broken CORS
+  config) — correctly flagged as `CRITICAL` with accurate line number
+  and explanation
+- ⏳ Negative case (clean config using `process.env.FRONTEND_URL`)
+  pending verification — expected to NOT flag, confirming the rule's
+  actual decision boundary
+
+---
+
+## 9. One-line resume/pitch version
+
+> Built a static analysis CLI that catches dev-to-prod environment bugs
+> (CORS misconfig, hardcoded URLs, cookie cross-origin issues) using AST
+> parsing — not regex — to understand code structure and resolve variable
+> references, with LLM-generated, context-aware explanations for each
+> finding. Built after personally losing hours to these exact bugs
+> deploying a real MERN app.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "deployscout",
+  "version": "1.0.1",
+  "description": "Catches dev-to-prod environment bugs before they bite you",
+  "main": "src/cli.js",
+  "bin": {
+    "deployscout": "src/cli.js"
+  },
+  "files": [
+    "src/",
+    "readme.md",
+    "Project.md"
+  ],
+  "scripts": {
+    "test": "jest"
+  },
+  "jest": {
+    "transformIgnorePatterns": [
+      "node_modules/(?!(@babel/parser|@babel/traverse)/)"
+    ]
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@babel/parser": "^7.23.9",
+    "@babel/traverse": "^7.23.9",
+    "axios": "^1.18.1",
+    "chalk": "^4.1.2",
+    "commander": "^15.0.0",
+    "dotenv": "^17.4.2",
+    "express": "^5.2.1",
+    "fast-glob": "^3.3.3",
+    "fs": "^0.0.1-security",
+    "path": "^0.12.7"
+  },
+  "devDependencies": {
+    "jest": "^30.4.2"
+  }
+}

package/readme.md

@@ -0,0 +1,151 @@
+# DeployScout
+
+> Catch dev-to-prod environment bugs before they bite you.
+
+MERN apps routinely work perfectly in local development and break the moment they're deployed — not because of bad code, but because of **environment assumptions** that only become visible in a different environment. A hardcoded `localhost` URL, a CORS config scoped to your dev machine, a cookie setting that silently breaks cross-origin auth in production.
+
+Generic linters won't catch these. They have no concept of "this string is fine locally and completely wrong in production." DeployScout does.
+
+---
+
+## What it catches
+
+### CORS misconfiguration
+- `cors()` package called with a hardcoded `localhost` origin — via both inline config objects and variable references
+- Manual `res.header("Access-Control-Allow-Origin", "http://localhost:...")` calls
+
+### Hardcoded localhost URLs
+- `axios.get/post/put/delete/patch("http://localhost:...")` calls
+- `fetch("http://localhost:...")` calls
+- `io("http://localhost:...")` socket connections
+- Variable declarations with URL-like names pointing to localhost (`BASE_URL`, `API_URL`, `BACKEND_HOST`, etc.)
+
+---
+
+## Why AST, not regex
+
+DeployScout uses `@babel/parser` and `@babel/traverse` to parse files into an Abstract Syntax Tree rather than pattern-matching on raw text. This means it:
+
+- **Resolves variable references** — detects `cors(corsOption)` where `corsOption` is declared elsewhere in the file, not just `cors({ origin: '...' })` inline
+- **Understands code structure** — distinguishes an actual CORS config object from a string that happens to contain `localhost` in a comment or unrelated variable
+- **Avoids false positives** — the hardcoded-URL variable check only flags variables whose *name* suggests a URL or endpoint (`URL`, `API`, `BASE`, `HOST`, `ENDPOINT`, `SERVER`, `BACKEND`), not every string in the codebase
+
+---
+
+## Installation
+
+Run directly without installing:
+
+```bash
+npx deployscout <path-to-repo>
+```
+
+Or install globally:
+
+```bash
+npm install -g deployscout
+deployscout <path-to-repo>
+```
+
+---
+
+## Usage
+
+```bash
+# Scan a repo
+deployscout ./my-mern-app
+
+# Scan a specific subfolder
+deployscout ./my-mern-app/backend
+```
+
+DeployScout walks all `.js` and `.jsx` files under the given path, skipping `node_modules`, `dist`, and `build` automatically.
+
+---
+
+## Example output
+
+```
+Scanning /path/to/my-mern-app...
+
+Found 2 issue(s):
+
+ CRITICAL  backend/index.js:8
+  origin: 'http://localhost:3000',
+  CORS origin is hardcoded to "http://localhost:3000". This will reject every
+  real production frontend URL — the deployed frontend's origin will never
+  match "localhost", so every cross-origin request will be blocked by the browser.
+  AI: The corsOption origin is set to http://localhost:3000, which is only valid
+  during local development. Once deployed, your frontend will run on a different
+  domain and all cross-origin requests will be blocked. Fix: origin: process.env.FRONTEND_URL
+
+ CRITICAL  frontend/src/hooks/useGetUsers.js:12
+  const res = await axios.get("http://localhost:8080/api/v1/user/");
+  This axios.get() call is hardcoded to "http://localhost:8080". In production,
+  your backend will be hosted at a different domain — this call will fail with
+  a connection error once deployed.
+  AI: Replace with: const res = await axios.get(`${process.env.REACT_APP_BACKEND_URL}/api/v1/user/`);
+```
+
+DeployScout exits with a **non-zero status code** when critical findings are present, making it usable in CI pipelines.
+
+---
+
+## AI-powered explanations (optional)
+
+If a `GEMINI_API_KEY` is set, DeployScout enriches each finding with a context-specific explanation and suggested fix generated by Gemini — referencing the actual variable names and code patterns in your file, not a generic template.
+
+```bash
+# .env or environment
+GEMINI_API_KEY=your_key_here
+```
+
+Get a free API key at [aistudio.google.com/apikey](https://aistudio.google.com/apikey) — no credit card required.
+
+If `GEMINI_API_KEY` is not set, DeployScout still runs and prints built-in explanations for every finding. The AI layer is an enhancement, never a dependency.
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | No issues found, or only warnings |
+| `1` | One or more critical findings detected |
+
+---
+
+## Project layout
+
+```
+src/
+├── cli.js              entry point, wires everything together
+├── scanner.js          walks the repo, finds candidate .js/.jsx files
+├── explain.js          optional Gemini API explanation layer
+└── rules/
+    ├── cors.js         CORS misconfiguration detection
+    └── hardcoded-url.js  hardcoded localhost URL detection
+```
+
+---
+
+## Current scope and known limitations
+
+DeployScout is currently scoped to MERN (MongoDB / Express / React / Node) apps. It deliberately does not:
+
+- Act as a general code reviewer
+- Scan for dependency vulnerabilities (`npm audit` covers this)
+- Detect committed secrets (`gitleaks` covers this)
+- Support non-JS stacks in the current version
+
+Known detection limitations in the current version:
+
+- `process.env.FRONTEND_URL || 'http://localhost:3000'` (a `||` fallback with a localhost default) is not flagged — the value is a logical expression, not a plain string literal, and the fallback risk is considered a known v1 gap
+- Variable-based CORS config (`cors(corsOption)`) is resolved one level deep; deeply nested or dynamically constructed config objects are not followed
+- Manual CORS header checks assume the Express response object is named `res` or `response`
+
+---
+
+## Background
+
+DeployScout was built after personally losing hours to the exact bugs it now detects — deploying a real MERN chat app and hitting CORS errors, hardcoded localhost failures, and cookie cross-origin issues one after another. The tool exists because none of the existing linters or code reviewers understand the relationship between local dev assumptions and production deployment reality.

package/src/cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+require("dotenv").config();
+
+const { Command } = require("commander");
+const chalk = require("chalk");
+const path = require("path");
+
+const { findCandidateFiles } = require("./scanner");
+const corsRule = require("./rules/cors");
+const hardcodedUrlRule = require("./rules/hardcoded-url");
+const { explainFinding } = require("./explain");
+
+const program = new Command();
+
+program
+  .name("deployscout")
+  .description("Catches dev-to-prod environment bugs before they bite you")
+  .argument("<repoPath>", "path to the repo you want to scan")
+  .action(async (repoPath) => {
+    const absolutePath = path.resolve(repoPath);
+
+    console.log(chalk.bold(`\nScanning ${absolutePath}...\n`));
+
+    const files = await findCandidateFiles(absolutePath);
+
+    if (files.length === 0) {
+      console.log(chalk.yellow("No JS/JSX files found to scan."));
+      return;
+    }
+
+    let allFindings = [];
+
+    for (const file of files) {
+      const corsFindings = corsRule.checkFile(file);
+      const urlFindings = hardcodedUrlRule.checkFile(file);
+      allFindings = allFindings.concat(corsFindings, urlFindings);
+    }
+
+    if (allFindings.length === 0) {
+      console.log(chalk.green("✔ No issues found.\n"));
+      return;
+    }
+
+    console.log(chalk.bold(`Found ${allFindings.length} issue(s):\n`));
+
+    if (!process.env.GEMINI_API_KEY) {
+      console.log(
+        chalk.dim(
+          "  (No GEMINI_API_KEY set — showing built-in explanations only. " +
+            "See .env.example to enable AI-generated context-specific fixes.)\n"
+        )
+      );
+    }
+
+    for (const finding of allFindings) {
+      const relativePath = path.relative(absolutePath, finding.file);
+      const badge =
+        finding.severity === "critical"
+          ? chalk.bgRed.white.bold(" CRITICAL ")
+          : chalk.bgYellow.black.bold(" WARNING ");
+
+      console.log(`${badge} ${chalk.underline(`${relativePath}:${finding.line}`)}`);
+      console.log(`  ${chalk.dim(finding.snippet)}`);
+      console.log(`  ${finding.message}`);
+
+      const aiExplanation = await explainFinding(finding);
+      if (aiExplanation) {
+        console.log(`  ${chalk.cyan("AI:")} ${aiExplanation}`);
+      }
+
+      console.log("");
+    }
+
+    const hasCritical = allFindings.some((f) => f.severity === "critical");
+    if (hasCritical) {
+      process.exitCode = 1;
+    }
+  });
+
+program.parse();

package/src/explain.js

@@ -0,0 +1,87 @@
+const fs = require("fs");
+
+const GEMINI_MODEL = process.env.GEMINI_MODEL || "gemini-2.5-flash";
+const GEMINI_URL = `https://generativelanguage.googleapis.com/v1beta/models/${GEMINI_MODEL}:generateContent`;
+
+/**
+ * Reads a small, bounded window of lines around the flagged line, so the
+ * LLM has just enough real context to give a specific fix — without
+ * sending the whole file. (NFR5: only the flagged snippet + minimal
+ * context goes to the LLM, never the full file/repo.)
+ */
+function getContextWindow(filePath, line, windowSize = 2) {
+  const code = fs.readFileSync(filePath, "utf-8");
+  const lines = code.split("\n");
+
+  const start = Math.max(0, line - 1 - windowSize);
+  const end = Math.min(lines.length, line + windowSize);
+
+  return lines.slice(start, end).join("\n");
+}
+
+function buildPrompt(finding, contextWindow) {
+  return `You are a senior backend engineer reviewing a deployment-readiness flag found by a static analyzer in a MERN (MongoDB/Express/React/Node) app.
+
+Issue type: CORS misconfiguration
+Severity: ${finding.severity}
+Flagged line: ${finding.snippet}
+
+Surrounding code for context:
+${contextWindow}
+
+Static analyzer's built-in explanation: ${finding.message}
+
+In 2-3 sentences, explain concretely why this will break once the app is deployed — reference the actual code shown above, not a generic explanation. Then give ONE line of suggested fixed code, using an environment variable, that matches the existing variable/property names from the snippet above. Keep the total response under 80 words. Do not use markdown formatting, just plain text.`;
+}
+
+/**
+ * Calls the Gemini API to generate a context-specific explanation and fix
+ * suggestion for a single finding. Returns null on ANY failure (missing
+ * key, network error, bad response) so the caller can gracefully fall
+ * back to the rule's built-in message — this layer must never crash the
+ * tool or block its core function.
+ *
+ * @param {object} finding - a single finding object from a rule's checkFile()
+ * @returns {Promise<string|null>} AI-generated explanation, or null
+ */
+async function explainFinding(finding) {
+  const apiKey = process.env.GEMINI_API_KEY;
+  if (!apiKey) return null; // caller already warns once, not per-finding
+
+  let contextWindow;
+  try {
+    contextWindow = getContextWindow(finding.file, finding.line);
+  } catch (err) {
+    return null; // couldn't re-read the file for context, skip silently
+  }
+
+  const prompt = buildPrompt(finding, contextWindow);
+
+  try {
+    const response = await fetch(GEMINI_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-goog-api-key": apiKey,
+      },
+      body: JSON.stringify({
+        contents: [{ role: "user", parts: [{ text: prompt }] }],
+      }),
+    });
+
+    if (!response.ok) {
+      // e.g. 429 rate limit, 401 invalid key, 500 server error
+      return null;
+    }
+
+    const data = await response.json();
+    const text = data?.candidates?.[0]?.content?.parts?.[0]?.text;
+
+    return text ? text.trim() : null;
+  } catch (err) {
+    // network failure, DNS issue, etc. — fail silently, caller falls back
+    return null;
+  }
+}
+
+module.exports = { explainFinding };

package/src/rules/cors.js

@@ -0,0 +1,269 @@
+const fs = require("fs");
+const parser = require("@babel/parser");
+const traverse = require("@babel/traverse").default;
+
+/**
+ * Detects risky CORS configuration in two patterns:
+ *
+ *  1. The `cors` npm package:
+ *       cors({ origin: 'http://localhost:3000', credentials: true })
+ *
+ *  2. Manual header-setting (Express's res.header / res.set):
+ *       res.header("Access-Control-Allow-Origin", "http://localhost:3000")
+ *
+ * These are structurally unrelated AST shapes, so they're detected by
+ * two separate checks inside the same CallExpression visitor.
+ *
+ * What counts as "risky" for the origin check, in both patterns:
+ *   - origin is a hardcoded string literal (not process.env.SOMETHING)
+ *   - that string literal contains "localhost"
+ *
+ * @param {string} filePath - absolute path to the file being checked
+ * @returns {object[]} list of findings, each with file/line/message
+ */
+function checkFile(filePath) {
+  const findings = [];
+  const code = fs.readFileSync(filePath, "utf-8");
+
+  let ast;
+  try {
+    ast = parser.parse(code, {
+      sourceType: "unambiguous", // handles both CommonJS and ESM files
+      plugins: ["jsx"], // in case a .jsx file slips through
+    });
+  } catch (err) {
+    // file isn't valid JS (or uses syntax we don't support yet) — skip it
+    return findings;
+  }
+
+  traverse(ast, {
+    CallExpression(path) {
+      checkCorsPackagePattern(path, code, filePath, findings);
+      checkManualHeaderPattern(path, code, filePath, findings);
+    },
+  });
+
+  return findings;
+}
+
+/**
+ * Pattern 1: the `cors` npm package, e.g. cors({ origin: '...' })
+ * or cors(corsOption) where corsOption is a variable.
+ */
+function checkCorsPackagePattern(path, code, filePath, findings) {
+  const callee = path.node.callee;
+
+  // Only interested in calls literally named "cors"
+  // e.g. cors({...})  -- NOT app.use(cors()) directly, but the
+  // inner cors(...) call itself, which is what holds the config.
+  const isCorsCall = callee.type === "Identifier" && callee.name === "cors";
+  if (!isCorsCall) return;
+
+  const args = path.node.arguments;
+  if (args.length === 0) return; // cors() with no args -- nothing to check
+
+  let configArg = args[0];
+
+  // Handle the common pattern:
+  //   const corsOption = { origin: '...', credentials: true };
+  //   app.use(cors(corsOption));
+  // Here cors() is called with an Identifier (variable name), not an
+  // inline object -- so we resolve the variable to find its declaration.
+  if (configArg.type === "Identifier") {
+    const binding = path.scope.getBinding(configArg.name);
+    if (!binding || binding.path.node.type !== "VariableDeclarator") return;
+
+    const init = binding.path.node.init;
+    if (!init || init.type !== "ObjectExpression") return;
+
+    configArg = init;
+  }
+
+  if (configArg.type !== "ObjectExpression") return; // not a config object, skip
+
+  // Walk the properties of the config object looking for `origin`
+  for (const prop of configArg.properties) {
+    if (prop.type !== "ObjectProperty") continue;
+
+    const keyName = prop.key.name || prop.key.value; // handles origin: vs "origin":
+    if (keyName !== "origin") continue;
+
+    const value = prop.value;
+
+    if (value.type === "StringLiteral") {
+      pushOriginFinding({
+        findings,
+        filePath,
+        code,
+        line: prop.loc.start.line,
+        originValue: value.value,
+      });
+    }
+    // If it's not a StringLiteral (e.g. it's `process.env.FRONTEND_URL`),
+    // we consider that safe for this rule and don't flag it.
+  }
+}
+
+/**
+ * Pattern 2: manual header-setting via res.header(...) or res.set(...)
+ * e.g. res.header("Access-Control-Allow-Origin", "http://localhost:3000")
+ *
+ * v1 scope: only checks the origin header. Missing
+ * Access-Control-Allow-Headers and overly-restrictive
+ * Access-Control-Allow-Methods are deliberately deferred — see
+ * PROJECT.md decisions log.
+ */
+function checkManualHeaderPattern(path, code, filePath, findings) {
+  const callee = path.node.callee;
+
+  // We're looking for res.header(...) or res.set(...) -- a member call
+  // where the object is named "res" (or "response") and the method is
+  // "header" or "set".
+  const isMemberCall = callee.type === "MemberExpression";
+  if (!isMemberCall) return;
+
+  const objectName = callee.object.name;
+  const methodName = callee.property.name;
+
+  const isResLike = objectName === "res" || objectName === "response";
+  const isHeaderMethod = methodName === "header" || methodName === "set";
+  if (!isResLike || !isHeaderMethod) return;
+
+  const args = path.node.arguments;
+  if (args.length < 2) return; // need both header name and value
+
+  const headerNameArg = args[0];
+  const headerValueArg = args[1];
+
+  if (headerNameArg.type !== "StringLiteral") return;
+  if (headerNameArg.value !== "Access-Control-Allow-Origin") return;
+
+  if (headerValueArg.type === "StringLiteral") {
+    pushOriginFinding({
+      findings,
+      filePath,
+      code,
+      line: path.node.loc.start.line,
+      originValue: headerValueArg.value,
+    });
+  }
+}
+
+/**
+ * Shared finding-builder for both patterns, so the message wording and
+ * severity logic stay consistent regardless of which pattern triggered it.
+ */
+function pushOriginFinding({ findings, filePath, code, line, originValue }) {
+  const isLocalhost = originValue.includes("localhost");
+  findings.push({
+    file: filePath,
+    line,
+    issueType: "CORS misconfiguration",  // ← add this line
+    severity: isLocalhost ? "critical" : "warning",
+    message: isLocalhost
+      ? `CORS origin is hardcoded to "${originValue}"...`
+      : `CORS origin is a hardcoded string...`,
+    snippet: code.split("\n")[line - 1].trim(),
+  });
+}
+
+module.exports = { checkFile };
+
+
+//__________________________phse 1 
+// const fs = require("fs");
+// const parser = require("@babel/parser");
+// const traverse = require("@babel/traverse").default;
+
+// /**
+//  * Detects risky CORS configuration passed to the `cors` npm package,
+//  * e.g. cors({ origin: 'http://localhost:3000', credentials: true })
+//  *
+//  * What counts as "risky" for this rule:
+//  *   - origin is a hardcoded string literal (not process.env.SOMETHING)
+//  *   - that string literal contains "localhost"
+//  *
+//  * @param {string} filePath - absolute path to the file being checked
+//  * @returns {object[]} list of findings, each with file/line/message
+//  */
+// function checkFile(filePath) {
+//   const findings = [];
+//   const code = fs.readFileSync(filePath, "utf-8");
+
+//   let ast;
+//   try {
+//     ast = parser.parse(code, {
+//       sourceType: "unambiguous", // handles both CommonJS and ESM files
+//       plugins: ["jsx"], // in case a .jsx file slips through
+//     });
+//   } catch (err) {
+//     // file isn't valid JS (or uses syntax we don't support yet) — skip it
+//     return findings;
+//   }
+
+//   traverse(ast, {
+//     // We're looking for any function call: someName(...)
+//     CallExpression(path) {
+//       const callee = path.node.callee;
+
+//       // Only interested in calls literally named "cors"
+//       // e.g. cors({...})  -- NOT app.use(cors()) directly, but the
+//       // inner cors(...) call itself, which is what holds the config.
+//       const isCorsCall =
+//         callee.type === "Identifier" && callee.name === "cors";
+
+//       if (!isCorsCall) return;
+
+//       const args = path.node.arguments;
+//       if (args.length === 0) return; // cors() with no args -- nothing to check
+
+//       let configArg = args[0];
+
+//       // Handle the common pattern:
+//       //   const corsOption = { origin: '...', credentials: true };
+//       //   app.use(cors(corsOption));
+//       // Here cors() is called with an Identifier (variable name), not an
+//       // inline object -- so we resolve the variable to find its declaration.
+//       if (configArg.type === "Identifier") {
+//         const binding = path.scope.getBinding(configArg.name);
+//         if (!binding || binding.path.node.type !== "VariableDeclarator") return;
+
+//         const init = binding.path.node.init;
+//         if (!init || init.type !== "ObjectExpression") return;
+
+//         configArg = init;
+//       }
+
+//       if (configArg.type !== "ObjectExpression") return; // not a config object, skip
+
+//       // Walk the properties of the config object looking for `origin`
+//       for (const prop of configArg.properties) {
+//         if (prop.type !== "ObjectProperty") continue;
+
+//         const keyName = prop.key.name || prop.key.value; // handles origin: vs "origin":
+//         if (keyName !== "origin") continue;
+
+//         const value = prop.value;
+
+//         if (value.type === "StringLiteral") {
+//           const isLocalhost = value.value.includes("localhost");
+//           findings.push({
+//             file: filePath,
+//             line: prop.loc.start.line,
+//             severity: isLocalhost ? "critical" : "warning",
+//             message: isLocalhost
+//               ? `CORS origin is hardcoded to "${value.value}". This will reject every real production frontend URL — the deployed frontend's origin will never match "localhost", so every cross-origin request will be blocked by the browser.`
+//               : `CORS origin is a hardcoded string ("${value.value}") instead of an environment variable. This works until your deployed frontend URL changes or differs per environment.`,
+//             snippet: code.split("\n")[prop.loc.start.line - 1].trim(),
+//           });
+//         }
+//         // If it's not a StringLiteral (e.g. it's `process.env.FRONTEND_URL`),
+//         // we consider that safe for this rule and don't flag it.
+//       }
+//     },
+//   });
+
+//   return findings;
+// }
+
+// module.exports = { checkFile };

package/src/rules/hardcoded-url.js

@@ -0,0 +1,204 @@
+const fs = require("fs");
+const parser = require("@babel/parser");
+const traverse = require("@babel/traverse").default;
+
+/**
+ * Detects hardcoded "localhost" URLs in two patterns:
+ *
+ *  1. Function-call arguments (Phase 3):
+ *       axios.get('http://localhost:8080/api/...')
+ *       axios.post('http://localhost:8080/api/...', body)
+ *       fetch('http://localhost:8080/api/...')
+ *       io('http://localhost:8080', { query: {...} })
+ *
+ *  2. Variable declarations whose name suggests a URL/endpoint (Phase 3.5):
+ *       export const BASE_URL = "http://localhost:8080"
+ *       const API_URL = "http://localhost:8080"
+ *
+ * Pattern 2 requires the variable name to contain a URL-related keyword
+ * (URL, API, BASE, HOST, ENDPOINT, SERVER, BACKEND) — a deliberate
+ * heuristic to avoid flagging unrelated variables that happen to hold a
+ * string containing "localhost". See PROJECT.md decisions log.
+ *
+ * What counts as "risky" for both patterns:
+ *   - the value is a hardcoded string literal (or a template literal
+ *     with no ${...} interpolation)
+ *   - that string contains "localhost"
+ *
+ * @param {string} filePath - absolute path to the file being checked
+ * @returns {object[]} list of findings, each with file/line/message
+ */
+function checkFile(filePath) {
+  const findings = [];
+  const code = fs.readFileSync(filePath, "utf-8");
+
+  let ast;
+  try {
+    ast = parser.parse(code, {
+      sourceType: "unambiguous",
+      plugins: ["jsx"],
+    });
+  } catch (err) {
+    return findings;
+  }
+
+  traverse(ast, {
+    CallExpression(path) {
+      checkAxiosCall(path, code, filePath, findings);
+      checkFetchCall(path, code, filePath, findings);
+      checkSocketIoCall(path, code, filePath, findings);
+    },
+    VariableDeclarator(path) {
+      checkUrlVariableDeclaration(path, code, filePath, findings);
+    },
+  });
+
+  return findings;
+}
+
+/**
+ * axios.get(url), axios.post(url, body), axios.put(url, body), etc.
+ */
+function checkAxiosCall(path, code, filePath, findings) {
+  const callee = path.node.callee;
+  if (callee.type !== "MemberExpression") return;
+
+  const objectName = callee.object.name;
+  const methodName = callee.property.name;
+
+  const HTTP_METHODS = ["get", "post", "put", "delete", "patch"];
+  if (objectName !== "axios" || !HTTP_METHODS.includes(methodName)) return;
+
+  const urlArg = path.node.arguments[0];
+  if (!urlArg) return;
+
+  flagIfHardcodedLocalhost({
+    argNode: urlArg,
+    source: `axios.${methodName}() call`,
+    path,
+    code,
+    filePath,
+    findings,
+  });
+}
+
+/**
+ * fetch(url, options)
+ */
+function checkFetchCall(path, code, filePath, findings) {
+  const callee = path.node.callee;
+  if (callee.type !== "Identifier" || callee.name !== "fetch") return;
+
+  const urlArg = path.node.arguments[0];
+  if (!urlArg) return;
+
+  flagIfHardcodedLocalhost({
+    argNode: urlArg,
+    source: "fetch() call",
+    path,
+    code,
+    filePath,
+    findings,
+  });
+}
+
+/**
+ * io(url, options) — socket.io-client connection
+ */
+function checkSocketIoCall(path, code, filePath, findings) {
+  const callee = path.node.callee;
+  if (callee.type !== "Identifier" || callee.name !== "io") return;
+
+  const urlArg = path.node.arguments[0];
+  if (!urlArg) return;
+
+  flagIfHardcodedLocalhost({
+    argNode: urlArg,
+    source: "io() call",
+    path,
+    code,
+    filePath,
+    findings,
+  });
+}
+
+// Keywords that suggest a variable name represents a URL/endpoint.
+// Substring match, case-insensitive. A deliberate heuristic — see
+// PROJECT.md decisions log for the reasoning and known limitations.
+const URL_LIKE_NAME_KEYWORDS = [
+  "URL",
+  "API",
+  "BASE",
+  "HOST",
+  "ENDPOINT",
+  "SERVER",
+  "BACKEND",
+];
+
+function isUrlLikeVariableName(name) {
+  const upperName = name.toUpperCase();
+  return URL_LIKE_NAME_KEYWORDS.some((keyword) => upperName.includes(keyword));
+}
+
+/**
+ * const BASE_URL = "http://localhost:8080"
+ * export const API_URL = "http://localhost:8080"
+ *
+ * Only flags if BOTH:
+ *   - the variable name matches the URL-like keyword heuristic
+ *   - the assigned value is a hardcoded localhost string
+ */
+function checkUrlVariableDeclaration(path, code, filePath, findings) {
+  const id = path.node.id;
+  if (id.type !== "Identifier") return; // skip destructuring, etc.
+
+  if (!isUrlLikeVariableName(id.name)) return;
+
+  const init = path.node.init;
+  if (!init) return; // declared but not initialized, e.g. `let x;`
+
+  flagIfHardcodedLocalhost({
+    argNode: init,
+    source: `"${id.name}" declaration`,
+    path,
+    code,
+    filePath,
+    findings,
+  });
+}
+
+/**
+ * Shared check: is this argument/value node a hardcoded string literal
+ * containing "localhost"? If so, push a finding. Handles plain string
+ * literals directly; template literals with no interpolated expressions
+ * are also checked, since that's a common stylistic choice that's
+ * otherwise identical in risk to a plain string.
+ */
+function flagIfHardcodedLocalhost({ argNode, source, path, code, filePath, findings }) {
+  let urlValue = null;
+
+  if (argNode.type === "StringLiteral") {
+    urlValue = argNode.value;
+  } else if (
+    argNode.type === "TemplateLiteral" &&
+    argNode.expressions.length === 0
+  ) {
+    urlValue = argNode.quasis.map((q) => q.value.cooked).join("");
+  }
+
+  if (urlValue === null) return; // not a static string we can check
+  if (!urlValue.includes("localhost")) return;
+
+  const line = path.node.loc.start.line;
+
+  findings.push({
+    file: filePath,
+    line,
+    issueType: "Hardcoded localhost URL",
+    severity: "critical",
+    message: `This ${source} is hardcoded to "${urlValue}". In production, your backend will be hosted at a different domain — "localhost" will never resolve to it, so this will fail with a connection error once deployed.`,
+    snippet: code.split("\n")[line - 1].trim(),
+  });
+}
+
+module.exports = { checkFile };

package/src/scanner.js

@@ -0,0 +1,27 @@
+const fg = require("fast-glob");
+
+/**
+ * Walks the given repo root and returns a list of candidate JS/JSX files
+ * to scan for issues. Skips node_modules, build output, and hidden folders.
+ *
+ * @param {string} repoPath - absolute or relative path to the repo root
+ * @returns {Promise<string[]>} list of absolute file paths
+ */
+async function findCandidateFiles(repoPath) {
+  const patterns = ["**/*.js", "**/*.jsx"];
+
+  const files = await fg(patterns, {
+    cwd: repoPath,
+    absolute: true,
+    ignore: [
+      "**/node_modules/**",
+      "**/dist/**",
+      "**/build/**",
+      "**/.git/**",
+    ],
+  });
+
+  return files;
+}
+
+module.exports = { findCandidateFiles };