itworksbut 0.5.0 → 0.7.0

package/src/stress/discoverEndpoints.js

@@ -0,0 +1,200 @@
+import path from "node:path";
+import { DEFAULT_IGNORE } from "../core/config.js";
+import { walkProject } from "../core/fileWalker.js";
+import { readFileSafe } from "../utils/fs.js";
+
+const HTTP_METHODS = ["get", "head", "post", "put", "patch", "delete"];
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+const ROUTE_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"]);
+const DISCOVERY_IGNORE = [
+  ...DEFAULT_IGNORE,
+  "test/**",
+  "tests/**",
+  "__tests__/**",
+  "**/*.test.js",
+  "**/*.test.ts",
+  "**/*.spec.js",
+  "**/*.spec.ts"
+];
+
+export async function discoverEndpoints(rootPath) {
+  const { textFiles } = await walkProject(rootPath, DISCOVERY_IGNORE);
+  return await discoverEndpointsFromFiles({
+    rootPath,
+    files: textFiles,
+    readFile: async (relativePath) => await readFileSafe(path.join(rootPath, relativePath))
+  });
+}
+
+export async function discoverEndpointsFromFiles({ rootPath, files, readFile }) {
+  const endpoints = [];
+
+  for (const file of files.filter(isSourceFile)) {
+    const content = await readFile(file);
+    if (content === null || content === undefined) continue;
+
+    endpoints.push(...discoverExpressEndpoints(file, content));
+    endpoints.push(...discoverFetchReferences(file, content));
+    endpoints.push(...discoverNextAppRouterEndpoints(file, content));
+    endpoints.push(...discoverNextPagesRouterEndpoints(file, content));
+  }
+
+  return classifyEndpoints(dedupeEndpoints(endpoints), rootPath);
+}
+
+export function classifyEndpoints(endpoints) {
+  const all = endpoints.map((endpoint) => {
+    const method = endpoint.method.toUpperCase();
+    const dynamic = isDynamicRoute(endpoint.path);
+    const unsafe = MUTATING_METHODS.has(method);
+    let status = "selected";
+    let reason;
+
+    if (unsafe) {
+      status = "skipped";
+      reason = "unsafe method";
+    } else if (dynamic) {
+      status = "skipped";
+      reason = "dynamic route requires parameter";
+    }
+
+    return {
+      ...endpoint,
+      method,
+      dynamic,
+      status,
+      reason
+    };
+  });
+
+  return {
+    status: all.length === 0 ? "skip" : "pass",
+    endpoints: all,
+    safeEndpoints: all.filter((endpoint) => endpoint.status === "selected"),
+    skippedEndpoints: all
+      .filter((endpoint) => endpoint.status === "skipped")
+      .map(({ method, path, reason, source, type }) => ({ method, path, reason, source, type }))
+  };
+}
+
+function discoverExpressEndpoints(file, content) {
+  const endpoints = [];
+  const methods = HTTP_METHODS.join("|");
+  const regex = new RegExp(`\\b(?:app|router|server)\\s*\\.\\s*(${methods})\\s*\\(\\s*(['"\`])([^'"\`]+)\\2`, "gi");
+  let match;
+
+  while ((match = regex.exec(content)) !== null) {
+    const routePath = normalizeRoutePath(match[3]);
+    if (!routePath) continue;
+    endpoints.push(endpoint(match[1], routePath, file, "express"));
+  }
+
+  return endpoints;
+}
+
+function discoverFetchReferences(file, content) {
+  const endpoints = [];
+  const regex = /\bfetch\s*\(\s*(['"`])(\/api\/[^'"`]+)\1/gi;
+  let match;
+
+  while ((match = regex.exec(content)) !== null) {
+    const routePath = normalizeRoutePath(match[2]);
+    if (!routePath) continue;
+    endpoints.push(endpoint("GET", routePath, file, "fetch-reference"));
+  }
+
+  return endpoints;
+}
+
+function discoverNextAppRouterEndpoints(file, content) {
+  const normalized = normalizeFilePath(file);
+  const match = normalized.match(/(?:^|\/)(?:src\/)?app\/api\/(.+)\/route\.(?:js|jsx|ts|tsx|mjs|cjs)$/);
+  if (!match) return [];
+
+  const routePath = normalizeRoutePath(`/api/${routeSegmentsToPath(match[1])}`);
+  const exportedMethods = discoverExportedRouteMethods(content);
+  const methods = exportedMethods.length > 0 ? exportedMethods : ["GET"];
+
+  return methods.map((method) => endpoint(method, routePath, file, "next-app-router"));
+}
+
+function discoverNextPagesRouterEndpoints(file, content) {
+  const normalized = normalizeFilePath(file);
+  const match = normalized.match(/(?:^|\/)(?:src\/)?pages\/api\/(.+)\.(?:js|jsx|ts|tsx|mjs|cjs)$/);
+  if (!match) return [];
+
+  const routePath = normalizeRoutePath(`/api/${routeSegmentsToPath(match[1])}`);
+  const guardedMethods = discoverMethodGuards(content);
+  const methods = guardedMethods.length > 0 ? guardedMethods : ["GET"];
+
+  return methods.map((method) => endpoint(method, routePath, file, "next-pages-router"));
+}
+
+function discoverExportedRouteMethods(content) {
+  const methods = new Set();
+  const regex = /\bexport\s+(?:async\s+)?function\s+(GET|HEAD|POST|PUT|PATCH|DELETE)\b/g;
+  let match;
+
+  while ((match = regex.exec(content)) !== null) {
+    methods.add(match[1]);
+  }
+
+  return [...methods];
+}
+
+function discoverMethodGuards(content) {
+  const methods = new Set();
+  const regex = /\b(?:req|request)\.method\s*(?:===|!==|==|!=)\s*['"`](GET|HEAD|POST|PUT|PATCH|DELETE)['"`]/gi;
+  let match;
+
+  while ((match = regex.exec(content)) !== null) {
+    methods.add(match[1].toUpperCase());
+  }
+
+  return [...methods];
+}
+
+function endpoint(method, routePath, file, type) {
+  return {
+    method: method.toUpperCase(),
+    path: routePath,
+    source: file,
+    type
+  };
+}
+
+function dedupeEndpoints(endpoints) {
+  const byKey = new Map();
+  for (const endpoint of endpoints) {
+    const key = `${endpoint.method.toUpperCase()} ${endpoint.path}`;
+    if (!byKey.has(key)) byKey.set(key, endpoint);
+  }
+  return [...byKey.values()].sort((a, b) => `${a.method} ${a.path}`.localeCompare(`${b.method} ${b.path}`));
+}
+
+function isSourceFile(file) {
+  const normalized = normalizeFilePath(file);
+  return ROUTE_EXTENSIONS.has(path.extname(normalized));
+}
+
+function normalizeFilePath(file) {
+  return String(file).replace(/\\/g, "/");
+}
+
+function normalizeRoutePath(value) {
+  if (!value || value.includes("${")) return null;
+  const pathValue = value.startsWith("/") ? value : `/${value}`;
+  return pathValue.replace(/\/+/g, "/").replace(/\/$/, "") || "/";
+}
+
+function routeSegmentsToPath(value) {
+  return value
+    .split("/")
+    .filter(Boolean)
+    .map((segment) => segment.replace(/^\[(\.\.\.)?(.+)]$/, ":$2"))
+    .join("/");
+}
+
+function isDynamicRoute(routePath) {
+  return /(^|\/):[^/]+|\[[^/]+]|\*/.test(routePath);
+}

package/src/stress/stressConfig.js

@@ -0,0 +1,31 @@
+export function createArtilleryConfig({ target, duration, arrivalRate, maxVusers, endpoints }) {
+  const flow = endpoints.map((endpoint) => ({
+    [endpoint.method.toLowerCase()]: {
+      url: endpoint.path
+    }
+  }));
+
+  return {
+    config: {
+      target,
+      phases: [
+        {
+          duration,
+          arrivalRate,
+          maxVusers
+        }
+      ],
+      defaults: {
+        headers: {
+          "user-agent": "ItWorksBut Stress"
+        }
+      }
+    },
+    scenarios: [
+      {
+        name: "Discovered API endpoints",
+        flow
+      }
+    ]
+  };
+}

package/src/stress/stressRenderer.js

@@ -0,0 +1,80 @@
+import { getChalk } from "../cli/terminal.js";
+
+export function reportStressConsole(result, options = {}) {
+  const colors = getChalk(options);
+  const details = result.details || {};
+
+  if (!options.quiet) {
+    process.stdout.write(`${colors.bold("ItWorksBut Stress")}\n\n`);
+    process.stdout.write("Only run this against systems you own or are explicitly authorized to test.\n\n");
+    process.stdout.write(`Target: ${details.target}\n`);
+    process.stdout.write(`Duration: ${details.duration}s\n`);
+    process.stdout.write(`Arrival rate: ${details.arrivalRate} req/s\n`);
+    process.stdout.write(`Max virtual users: ${details.maxVusers}\n\n`);
+
+    writeDiscovery(details, colors);
+    writeEndpoints(details, colors);
+  }
+
+  writeSummary(result, colors);
+}
+
+function writeDiscovery(details, colors) {
+  const found = details.endpointsFound || 0;
+  const safe = details.safeEndpoints || 0;
+  const skipped = details.skippedEndpoints?.length || 0;
+  const unsafe = details.skippedEndpoints?.filter((endpoint) => endpoint.reason === "unsafe method").length || 0;
+  const dynamic = details.skippedEndpoints?.filter((endpoint) => endpoint.reason === "dynamic route requires parameter").length || 0;
+
+  process.stdout.write(`${colors.green("✓")} Endpoint discovery: ${found} ${found === 1 ? "endpoint" : "endpoints"} found\n`);
+  process.stdout.write(`${colors.green("✓")} Safe endpoints: ${safe} GET/HEAD ${safe === 1 ? "endpoint" : "endpoints"} selected\n`);
+  if (skipped > 0) {
+    process.stdout.write(`- Skipped: ${unsafe} unsafe methods, ${dynamic} dynamic routes\n`);
+  }
+  process.stdout.write("\n");
+}
+
+function writeEndpoints(details, colors) {
+  const testedEndpoints = details.testedEndpoints || [];
+  if (testedEndpoints.length === 0) {
+    process.stdout.write("Running Artillery: skipped\n\n");
+    return;
+  }
+
+  process.stdout.write("Running Artillery: complete\n\n");
+  for (const endpoint of testedEndpoints) {
+    const symbol = endpoint.status === "pass" ? colors.green("✓") : endpoint.status === "warn" ? colors.yellow("⚠") : colors.red("✕");
+    process.stdout.write(`${symbol} ${endpoint.method} ${endpoint.path}\n`);
+    process.stdout.write(`  p95: ${formatMs(endpoint.p95)}\n`);
+    process.stdout.write(`  p99: ${formatMs(endpoint.p99)}\n`);
+    process.stdout.write(`  errors: ${endpoint.errors}\n`);
+    process.stdout.write(`  error rate: ${formatPercent(endpoint.errorRate)}\n\n`);
+  }
+}
+
+function writeSummary(result, colors) {
+  const details = result.details || {};
+  const warnings = details.warnings || 0;
+  const failed = details.failed || 0;
+  const tested = details.testedEndpoints?.length || 0;
+  const skipped = details.skippedEndpoints?.length || 0;
+
+  process.stdout.write("Summary:\n");
+  process.stdout.write(`${colors.green("✓")} Tested endpoints: ${tested}\n`);
+  process.stdout.write(`${colors.yellow("⚠")} Warnings: ${warnings}\n`);
+  process.stdout.write(`${colors.red("✕")} Failed: ${failed}\n`);
+  process.stdout.write(`- Skipped: ${skipped}\n`);
+  process.stdout.write(`- Status: ${result.status}\n`);
+  process.stdout.write(`- ${result.summary}\n`);
+  if (details.artilleryError) {
+    process.stdout.write(`- Artillery error: ${details.artilleryError}\n`);
+  }
+}
+
+function formatMs(value) {
+  return value === null || value === undefined ? "n/a" : `${Math.round(value)} ms`;
+}
+
+function formatPercent(value) {
+  return `${Number(value || 0).toFixed(Number.isInteger(value) ? 0 : 2).replace(/\.00$/, "")}%`;
+}

package/src/stress/stressResultParser.js

@@ -0,0 +1,155 @@
+const DEFAULT_THRESHOLDS = {
+  p95WarnMs: 500,
+  p95FailMs: 2000,
+  p99WarnMs: 1500,
+  errorRateWarn: 0,
+  errorRateFail: 10
+};
+
+export function parseArtilleryResult(artilleryResult, endpoints, options = {}) {
+  const thresholds = { ...DEFAULT_THRESHOLDS, ...(options.thresholds || {}) };
+
+  if (!artilleryResult?.report) {
+    return {
+      status: "fail",
+      summary: "Artillery did not produce a parseable report.",
+      testedEndpoints: endpoints.map((endpoint) => ({
+        method: endpoint.method,
+        path: endpoint.path,
+        status: "fail",
+        requests: 0,
+        p95: null,
+        p99: null,
+        errors: 1,
+        errorRate: 100
+      })),
+      warnings: 0,
+      failed: endpoints.length,
+      error: trimText(artilleryResult?.stderr || artilleryResult?.stdout || "Artillery failed.")
+    };
+  }
+
+  const aggregate = getAggregate(artilleryResult.report);
+  const counters = aggregate.counters || {};
+  const summaries = aggregate.summaries || {};
+  const fallbackRequests = countRequests(counters);
+  const fallbackErrors = countErrors(counters);
+
+  const testedEndpoints = endpoints.map((endpoint) => {
+    const summary = findEndpointSummary(summaries, endpoint) || summaries["http.response_time"] || {};
+    const requests = countEndpointRequests(counters, endpoint) ?? fallbackRequests;
+    const errors = countEndpointErrors(counters, endpoint) ?? fallbackErrors;
+    const errorRate = requests > 0 ? round((errors / requests) * 100, 2) : (errors > 0 ? 100 : 0);
+    const p95 = numeric(summary.p95);
+    const p99 = numeric(summary.p99);
+    const status = classifyEndpoint({ p95, p99, errorRate, errors }, thresholds);
+
+    return {
+      method: endpoint.method,
+      path: endpoint.path,
+      status,
+      requests,
+      p95,
+      p99,
+      errors,
+      errorRate
+    };
+  });
+
+  const warnings = testedEndpoints.filter((endpoint) => endpoint.status === "warn").length;
+  const failed = testedEndpoints.filter((endpoint) => endpoint.status === "fail").length;
+  const status = !artilleryResult.ok || failed > 0 ? "fail" : warnings > 0 ? "warn" : "pass";
+  const summary = summarize(testedEndpoints.length, warnings, failed, artilleryResult);
+
+  return {
+    status,
+    summary,
+    testedEndpoints,
+    warnings,
+    failed,
+    error: artilleryResult.ok ? undefined : trimText(artilleryResult.stderr || artilleryResult.stdout)
+  };
+}
+
+function getAggregate(report) {
+  if (report?.aggregate) return report.aggregate;
+  if (Array.isArray(report?.intermediate) && report.intermediate.length > 0) {
+    return report.intermediate[report.intermediate.length - 1] || {};
+  }
+  return report || {};
+}
+
+function findEndpointSummary(summaries, endpoint) {
+  const methodPath = `${endpoint.method} ${endpoint.path}`;
+  const candidates = Object.entries(summaries);
+  const match = candidates.find(([key]) => key.includes(methodPath));
+  if (match) return match[1];
+
+  const pathMatch = candidates.find(([key]) => key.includes(endpoint.path));
+  return pathMatch ? pathMatch[1] : null;
+}
+
+function countRequests(counters) {
+  if (Number.isFinite(counters["http.requests"])) return counters["http.requests"];
+  if (Number.isFinite(counters["http.responses"])) return counters["http.responses"];
+
+  return Object.entries(counters)
+    .filter(([key]) => /^http\.codes\.\d+$/.test(key))
+    .reduce((total, [, value]) => total + numeric(value), 0);
+}
+
+function countErrors(counters) {
+  const explicit = Object.entries(counters)
+    .filter(([key]) => key.startsWith("http.errors"))
+    .reduce((total, [, value]) => total + numeric(value), 0);
+  const statusErrors = Object.entries(counters)
+    .filter(([key]) => /^http\.codes\.[45]\d\d$/.test(key))
+    .reduce((total, [, value]) => total + numeric(value), 0);
+
+  return explicit + statusErrors;
+}
+
+function countEndpointRequests(counters, endpoint) {
+  return countEndpointMetric(counters, endpoint, ["requests", "responses"]);
+}
+
+function countEndpointErrors(counters, endpoint) {
+  return countEndpointMetric(counters, endpoint, ["errors"]);
+}
+
+function countEndpointMetric(counters, endpoint, names) {
+  const methodPath = `${endpoint.method} ${endpoint.path}`;
+  const matches = Object.entries(counters).filter(([key]) => {
+    return key.includes(methodPath) && names.some((name) => key.toLowerCase().includes(name));
+  });
+  if (!matches.length) return null;
+  return matches.reduce((total, [, value]) => total + numeric(value), 0);
+}
+
+function classifyEndpoint({ p95, p99, errorRate, errors }, thresholds) {
+  if (errorRate >= thresholds.errorRateFail || p95 >= thresholds.p95FailMs) return "fail";
+  if (errorRate > thresholds.errorRateWarn || errors > 0 || p95 > thresholds.p95WarnMs || p99 > thresholds.p99WarnMs) {
+    return "warn";
+  }
+  return "pass";
+}
+
+function summarize(tested, warnings, failed, artilleryResult) {
+  if (!artilleryResult.ok) return `Artillery failed after testing ${tested} ${tested === 1 ? "endpoint" : "endpoints"}.`;
+  return `${tested} ${tested === 1 ? "endpoint" : "endpoints"} tested, ${warnings} ${warnings === 1 ? "warning" : "warnings"}, ${failed} failed`;
+}
+
+function numeric(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : 0;
+}
+
+function round(value, digits) {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}
+
+function trimText(value) {
+  const normalized = String(value || "").trim();
+  return normalized.length > 1000 ? `${normalized.slice(0, 1000)}...` : normalized;
+}

package/src/utils/packageManager.js

@@ -0,0 +1,28 @@
+export function detectOutdatedPackageManager({ packageJson, files = [] } = {}) {
+  if (!packageJson) {
+    return {
+      status: "skip",
+      manager: null,
+      summary: "skipped, no package.json found"
+    };
+  }
+
+  if (files.includes("pnpm-lock.yaml")) return packageManager("pnpm");
+  if (files.includes("yarn.lock")) return packageManager("yarn");
+  if (files.includes("package-lock.json")) return packageManager("npm");
+  return packageManager("npm");
+}
+
+export function getOutdatedCommand(manager) {
+  if (manager === "pnpm") return { command: "pnpm", args: ["outdated", "--json"] };
+  if (manager === "yarn") return { command: "yarn", args: ["outdated", "--json"] };
+  return { command: "npm", args: ["outdated", "--json"] };
+}
+
+function packageManager(manager) {
+  return {
+    status: "run",
+    manager,
+    ...getOutdatedCommand(manager)
+  };
+}

package/src/utils/targetSafety.js

@@ -0,0 +1,90 @@
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "0.0.0.0"]);
+
+export const STRESS_DEFAULTS = {
+  target: "http://localhost:3000",
+  duration: 30,
+  arrivalRate: 5,
+  maxVusers: 50
+};
+
+export const STRESS_LIMITS = {
+  duration: 300,
+  arrivalRate: 50,
+  maxVusers: 100
+};
+
+export function validateStressOptions(args = {}) {
+  const target = normalizeTarget(args.target || STRESS_DEFAULTS.target);
+  const duration = parsePositiveNumber(args.duration, STRESS_DEFAULTS.duration, "duration");
+  const arrivalRate = parsePositiveNumber(args.arrivalRate, STRESS_DEFAULTS.arrivalRate, "arrival-rate");
+  const maxVusers = parsePositiveInteger(args.maxVusers, STRESS_DEFAULTS.maxVusers, "max-vusers");
+
+  assertWithinLimit(duration, STRESS_LIMITS.duration, "duration", "seconds");
+  assertWithinLimit(arrivalRate, STRESS_LIMITS.arrivalRate, "arrival-rate", "requests/second");
+  assertWithinLimit(maxVusers, STRESS_LIMITS.maxVusers, "max-vusers", "virtual users");
+
+  const local = isLocalTarget(target);
+  if (!local && !args.iOwnThis) {
+    throw new Error(
+      "Refusing to stress-test an external target without --i-own-this. Only run this against systems you own or are explicitly authorized to test."
+    );
+  }
+
+  return {
+    target,
+    duration,
+    arrivalRate,
+    maxVusers,
+    iOwnThis: Boolean(args.iOwnThis),
+    local
+  };
+}
+
+export function isLocalTarget(target) {
+  let parsed;
+  try {
+    parsed = new URL(target);
+  } catch {
+    return false;
+  }
+
+  return LOCAL_HOSTS.has(parsed.hostname.toLowerCase());
+}
+
+function normalizeTarget(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(`Invalid stress target URL: ${value}`);
+  }
+
+  if (!["http:", "https:"].includes(parsed.protocol)) {
+    throw new Error("Stress target must use http:// or https://.");
+  }
+
+  return parsed.toString().replace(/\/$/, "");
+}
+
+function parsePositiveNumber(value, fallback, label) {
+  if (value === undefined || value === null || value === "") return fallback;
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) {
+    throw new Error(`Invalid --${label}: expected a positive number.`);
+  }
+  return number;
+}
+
+function parsePositiveInteger(value, fallback, label) {
+  const number = parsePositiveNumber(value, fallback, label);
+  if (!Number.isInteger(number)) {
+    throw new Error(`Invalid --${label}: expected a positive integer.`);
+  }
+  return number;
+}
+
+function assertWithinLimit(value, limit, label, unit) {
+  if (value > limit) {
+    throw new Error(`Refusing --${label} ${value}. Maximum allowed is ${limit} ${unit}.`);
+  }
+}