@democratize-quality/qualitylens-core 0.1.0

package/dist/core/detector.mjs

@@ -0,0 +1,395 @@
+// src/core/detector.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+
+// src/utils/logger.ts
+import * as fs from "fs";
+import * as path from "path";
+var Logger = class {
+  logPath = null;
+  fd = null;
+  /**
+   * Open (or create) qualitylens.log in the given directory.
+   * Appends to an existing log so multiple runs accumulate history.
+   * Call once at the start of each command.
+   */
+  configure(outputDir) {
+    try {
+      fs.mkdirSync(outputDir, { recursive: true });
+      this.logPath = path.join(outputDir, "qualitylens.log");
+      this.fd = fs.openSync(this.logPath, "a");
+      this.write("INFO", `--- qualitylens session started (pid ${process.pid}) ---`);
+    } catch {
+      this.logPath = null;
+      this.fd = null;
+    }
+  }
+  /** Path to the current log file, or null if not configured. */
+  get filePath() {
+    return this.logPath;
+  }
+  info(msg, detail) {
+    this.write("INFO", msg, detail);
+  }
+  warn(msg, detail) {
+    this.write("WARN", msg, detail);
+  }
+  /** Logs full detail (stack trace, raw error) to file only. */
+  error(msg, detail) {
+    this.write("ERROR", msg, detail);
+  }
+  debug(msg, detail) {
+    this.write("DEBUG", msg, detail);
+  }
+  close() {
+    if (this.fd !== null) {
+      try {
+        fs.closeSync(this.fd);
+      } catch {
+      }
+      this.fd = null;
+    }
+  }
+  write(level, msg, detail) {
+    if (this.fd === null) return;
+    const ts = (/* @__PURE__ */ new Date()).toISOString();
+    let line = `[${ts}] ${level.padEnd(5)} ${msg}`;
+    if (detail !== void 0) {
+      if (detail instanceof Error) {
+        line += `
+  ${detail.message}`;
+        if (detail.stack) {
+          line += "\n" + detail.stack.split("\n").map((l) => "  " + l).join("\n");
+        }
+      } else if (typeof detail === "string" && detail.trim()) {
+        line += "\n" + detail.split("\n").map((l) => "  " + l).join("\n");
+      } else if (typeof detail === "object") {
+        try {
+          line += "\n  " + JSON.stringify(detail, null, 2).replace(/\n/g, "\n  ");
+        } catch {
+        }
+      }
+    }
+    try {
+      fs.writeSync(this.fd, line + "\n");
+    } catch {
+    }
+  }
+};
+var logger = new Logger();
+
+// src/sources/routes.source.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import glob from "fast-glob";
+var RoutesSource = class {
+  constructor(config) {
+    this.config = config;
+  }
+  async collect() {
+    const type = this.config.type;
+    logger.info(`[routes] collecting routes`, { type, path: this.config.path });
+    try {
+      switch (type) {
+        case "nextjs":
+          return await this.collectNextJs();
+        case "openapi":
+          return await this.collectOpenApi();
+        case "express":
+          return await this.collectExpress();
+        case "manual":
+          return await this.collectManual();
+        default:
+          throw new Error(
+            `Unknown routes.type "${this.config.type}" in qualitylens.yaml.
+  Valid values: nextjs, openapi, express, manual`
+          );
+      }
+    } catch (err) {
+      logger.error(`[routes] collection failed (type=${type}, path=${this.config.path})`, err);
+      throw err;
+    }
+  }
+  /**
+   * Next.js pages/ or app/ directory scanner.
+   * 
+   * AI INSTRUCTIONS:
+   * 1. Glob all .tsx, .ts, .jsx, .js files under config.path
+   * 2. Convert file path to route:
+   *    pages/checkout/payment.tsx   → /checkout/payment
+   *    pages/index.tsx              → /
+   *    pages/auth/[id].tsx          → /auth/:id
+   *    app/checkout/page.tsx        → /checkout  (App Router pattern)
+   * 3. Skip: _app, _document, _error, api/ routes, layout.tsx, loading.tsx
+   * 4. Return AppRoute[]
+   */
+  async collectNextJs() {
+    const rootPath = path2.resolve(this.config.path);
+    if (!fs2.existsSync(rootPath)) {
+      throw new Error(
+        `Next.js routes directory not found: ${rootPath}
+  Check routes.path in qualitylens.yaml \u2014 it should point to your pages/ or app/ directory.`
+      );
+    }
+    const appRouterPages = await glob("**/page.{tsx,ts,jsx,js}", {
+      cwd: rootPath,
+      absolute: false,
+      ignore: ["**/node_modules/**"]
+    });
+    if (appRouterPages.length > 0) {
+      return appRouterPages.map((filePath) => {
+        const dir = filePath.replace(/\/page\.[jt]sx?$/, "").replace(/^page\.[jt]sx?$/, "");
+        const segments = dir.split("/").filter((seg) => !(seg.startsWith("(") && seg.endsWith(")")));
+        const routeSegments = segments.map(
+          (seg) => seg.startsWith("[") && seg.endsWith("]") ? `:${seg.slice(1, -1)}` : seg
+        );
+        const normalised = ("/" + routeSegments.join("/")).replace(/\/+/g, "/").replace(/\/$/, "") || "/";
+        return { path: normalised };
+      });
+    }
+    const pageFiles = await glob("**/*.{tsx,ts,jsx,js}", {
+      cwd: rootPath,
+      absolute: false,
+      ignore: ["**/node_modules/**", "**/_app.*", "**/_document.*", "**/_error.*", "**/api/**"]
+    });
+    return pageFiles.map((filePath) => {
+      const withoutExt = filePath.replace(/\.[jt]sx?$/, "");
+      const withoutIndex = withoutExt.replace(/(^|\/)index$/, "");
+      const segments = withoutIndex.split("/").map((seg) => seg.startsWith("[") && seg.endsWith("]") ? `:${seg.slice(1, -1)}` : seg);
+      return { path: ("/" + segments.join("/")).replace(/\/+/g, "/").replace(/\/$/, "") || "/" };
+    });
+  }
+  /**
+   * OpenAPI / Swagger spec parser.
+   * 
+   * AI INSTRUCTIONS:
+   * 1. Read the JSON or YAML file at config.path
+   * 2. Extract spec.paths object — keys are route paths
+   * 3. For each path, extract HTTP methods (get, post, put, delete, patch)
+   * 4. Return one AppRoute per path+method combination
+   * 5. Support both JSON (.json) and YAML (.yaml, .yml) specs
+   */
+  async collectOpenApi() {
+    const absPath = path2.resolve(this.config.path);
+    if (!fs2.existsSync(absPath)) {
+      throw new Error(
+        `OpenAPI spec not found: ${absPath}
+  If your spec is generated at build time, check the routes.generate command in qualitylens.yaml.
+  Run the generate command manually first to confirm it produces the file.`
+      );
+    }
+    let content;
+    try {
+      content = fs2.readFileSync(absPath, "utf-8");
+    } catch (err) {
+      throw new Error(`Could not read OpenAPI spec at ${absPath}: ${err.message}`);
+    }
+    const ext = path2.extname(this.config.path).toLowerCase();
+    let spec;
+    try {
+      spec = ext === ".json" ? JSON.parse(content) : (await import("js-yaml")).load(content);
+    } catch (err) {
+      throw new Error(
+        `Failed to parse OpenAPI spec at ${absPath} as ${ext === ".json" ? "JSON" : "YAML"}.
+  Parse error: ${err.message}
+  Check the file is valid by running: node -e "JSON.parse(require('fs').readFileSync('${absPath}','utf-8'))"`
+      );
+    }
+    const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"];
+    const routes = [];
+    for (const [routePath, pathItem] of Object.entries(spec.paths ?? {})) {
+      const normalisedPath = routePath.replace(/\{(\w+)\}/g, ":$1");
+      for (const method of HTTP_METHODS) {
+        if (pathItem[method]) {
+          routes.push({ path: normalisedPath, method: method.toUpperCase() });
+        }
+      }
+    }
+    return routes;
+  }
+  /**
+   * Express routes manifest (JSON file).
+   * Format: [{ path: '/checkout', method: 'GET' }, ...]
+   * Users generate this with express-list-routes or similar.
+   */
+  async collectExpress() {
+    return this.readJsonRouteManifest("express");
+  }
+  /**
+   * Manual route list in qualitylens.yaml.
+   * config.path points to a JSON file with [{ path: '/route' }]
+   */
+  async collectManual() {
+    return this.readJsonRouteManifest("manual");
+  }
+  /** Shared reader for express and manual JSON route manifests. */
+  readJsonRouteManifest(type) {
+    const absPath = path2.resolve(this.config.path);
+    if (!fs2.existsSync(absPath)) {
+      throw new Error(
+        `Routes manifest not found: ${absPath}
+  routes.type is "${type}" \u2014 qualitylens expects a JSON file at routes.path.
+  Format: [{ "path": "/api/users", "method": "GET" }, ...]`
+      );
+    }
+    let content;
+    try {
+      content = fs2.readFileSync(absPath, "utf-8");
+    } catch (err) {
+      throw new Error(`Could not read routes manifest at ${absPath}: ${err.message}`);
+    }
+    try {
+      return JSON.parse(content);
+    } catch (err) {
+      throw new Error(
+        `Failed to parse routes manifest at ${absPath} as JSON.
+  Parse error: ${err.message}
+  Expected format: [{ "path": "/api/users", "method": "GET" }, ...]`
+      );
+    }
+  }
+};
+
+// src/core/detector.ts
+var KNOWN_AREA_NAMES = {
+  auth: "Authentication",
+  login: "Authentication",
+  register: "Authentication",
+  logout: "Authentication",
+  signup: "Authentication",
+  checkout: "Checkout",
+  cart: "Shopping & Cart",
+  basket: "Shopping & Cart",
+  orders: "Orders",
+  order: "Orders",
+  account: "Account",
+  profile: "Account",
+  admin: "Admin",
+  settings: "Settings",
+  products: "Products",
+  product: "Products",
+  users: "Users",
+  user: "Users",
+  health: "Health",
+  ai: "AI",
+  billing: "Billing",
+  dashboard: "Dashboard"
+};
+async function detect(targetDir) {
+  const projectName = path3.basename(targetDir);
+  const pkgPath = path3.join(targetDir, "package.json");
+  const pkg = fs3.existsSync(pkgPath) ? JSON.parse(fs3.readFileSync(pkgPath, "utf-8")) : {};
+  const allDeps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies
+  };
+  const hasNext = "next" in allDeps;
+  const hasExpress = "express" in allDeps;
+  const hasSwaggerJsdoc = "swagger-jsdoc" in allDeps;
+  const hasPlaywright = "@playwright/test" in allDeps;
+  const TEST_DIR_CANDIDATES = ["e2e-tests", "e2e", "tests", "__tests__", "cypress/e2e", "test"];
+  let testsPath = null;
+  for (const candidate of TEST_DIR_CANDIDATES) {
+    if (fs3.existsSync(path3.join(targetDir, candidate))) {
+      testsPath = `./${candidate}`;
+      break;
+    }
+  }
+  let framework = "unknown";
+  let routeType = "manual";
+  let routesPath = null;
+  let generate = null;
+  if (hasNext) {
+    framework = "nextjs";
+    routeType = "nextjs";
+    for (const candidate of ["src/app", "app", "src/pages", "pages"]) {
+      if (fs3.existsSync(path3.join(targetDir, candidate))) {
+        routesPath = `./${candidate}`;
+        break;
+      }
+    }
+  } else if (hasExpress && hasSwaggerJsdoc) {
+    framework = "express-openapi";
+    routeType = "openapi";
+    routesPath = "./openapi.json";
+    generate = "npx ts-node src/generate-openapi.ts";
+  } else if (hasExpress) {
+    framework = "express";
+    routeType = "express";
+  }
+  let discoveredRoutes = [];
+  if (routesPath) {
+    const absoluteRoutesPath = path3.join(targetDir, routesPath.replace("./", ""));
+    const shouldDiscover = routeType === "nextjs" || routeType === "openapi" && fs3.existsSync(absoluteRoutesPath);
+    if (shouldDiscover) {
+      try {
+        const source = new RoutesSource({
+          type: routeType === "openapi" ? "openapi" : "nextjs",
+          path: absoluteRoutesPath
+        });
+        discoveredRoutes = await source.collect();
+      } catch {
+      }
+    }
+  }
+  const basePath = detectBasePath(discoveredRoutes);
+  const suggestedAreas = suggestAreas(discoveredRoutes, basePath);
+  return {
+    projectName,
+    framework,
+    routeType,
+    routesPath,
+    testsPath,
+    generate,
+    basePath,
+    hasSwaggerJsdoc,
+    hasPlaywright,
+    discoveredRoutes,
+    suggestedAreas
+  };
+}
+function detectBasePath(routes) {
+  if (routes.length === 0) return null;
+  const versionedPrefix = routes[0].path.match(/^(\/api\/v\d+)\//)?.[1];
+  if (versionedPrefix) {
+    const count = routes.filter((r) => r.path.startsWith(versionedPrefix + "/")).length;
+    if (count > routes.length * 0.5) return versionedPrefix;
+  }
+  const apiCount = routes.filter((r) => r.path.startsWith("/api/")).length;
+  if (apiCount > routes.length * 0.5) return "/api";
+  return null;
+}
+function suggestAreas(routes, basePath) {
+  if (routes.length === 0) return [];
+  const nameGroups = /* @__PURE__ */ new Map();
+  for (const route of routes) {
+    const hasPrefix = basePath ? route.path.startsWith(basePath + "/") : false;
+    const normalised = hasPrefix ? route.path.slice(basePath.length) : route.path;
+    const segments = normalised.split("/").filter((s) => s.length > 0 && !s.startsWith(":"));
+    const firstSegment = segments[0] ?? "";
+    if (!firstSegment) continue;
+    const areaName = toAreaName(firstSegment);
+    const pattern = hasPrefix ? `${basePath}/${firstSegment}` : `/${firstSegment}`;
+    if (!nameGroups.has(areaName)) {
+      nameGroups.set(areaName, { routes: [], patterns: /* @__PURE__ */ new Set() });
+    }
+    const group = nameGroups.get(areaName);
+    group.routes.push(route);
+    group.patterns.add(pattern);
+  }
+  return Array.from(nameGroups.entries()).map(([name, { routes: routes2, patterns }]) => ({
+    suggestedName: name,
+    routes: routes2,
+    patterns: Array.from(patterns)
+  }));
+}
+function toAreaName(segment) {
+  const lower = segment.toLowerCase();
+  if (KNOWN_AREA_NAMES[lower]) return KNOWN_AREA_NAMES[lower];
+  return segment.charAt(0).toUpperCase() + segment.slice(1);
+}
+export {
+  detect,
+  suggestAreas
+};
+//# sourceMappingURL=detector.mjs.map

package/dist/core/detector.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/detector.ts","../../src/utils/logger.ts","../../src/sources/routes.source.ts"],"sourcesContent":["/**\n * src/core/detector.ts\n *\n * Auto-detection logic for `qualitylens init`.\n * Inspects a target directory and returns everything it can infer:\n * framework, route type, routes path, discovered routes, and suggested areas.\n *\n * Nothing here writes files or prompts the user — it only observes.\n */\n\nimport * as fs from 'fs'\nimport * as path from 'path'\nimport { RoutesSource } from '../sources/routes.source'\nimport { AppRoute } from './types'\n\nexport type Framework = 'nextjs' | 'express-openapi' | 'express' | 'unknown'\nexport type RouteType = 'nextjs' | 'openapi' | 'express' | 'manual'\n\nexport interface SuggestedArea {\n  suggestedName: string\n  routes: AppRoute[]\n  patterns: string[]\n}\n\nexport interface DetectionResult {\n  projectName: string\n  framework: Framework\n  routeType: RouteType\n  routesPath: string | null    // null = could not detect\n  testsPath: string | null     // null = use config dir default\n  generate: string | null      // suggested generate command for openapi\n  basePath: string | null      // detected route prefix to strip when grouping areas (e.g. /api, /api/v1)\n  hasSwaggerJsdoc: boolean\n  hasPlaywright: boolean\n  discoveredRoutes: AppRoute[]\n  suggestedAreas: SuggestedArea[]\n}\n\n// Known path segment → human-readable area name.\n// Segments not listed here get title-cased automatically (e.g. 'billing' → 'Billing').\nconst KNOWN_AREA_NAMES: Record<string, string> = {\n  auth:      'Authentication',\n  login:     'Authentication',\n  register:  'Authentication',\n  logout:    'Authentication',\n  signup:    'Authentication',\n  checkout:  'Checkout',\n  cart:      'Shopping & Cart',\n  basket:    'Shopping & Cart',\n  orders:    'Orders',\n  order:     'Orders',\n  account:   'Account',\n  profile:   'Account',\n  admin:     'Admin',\n  settings:  'Settings',\n  products:  'Products',\n  product:   'Products',\n  users:     'Users',\n  user:      'Users',\n  health:    'Health',\n  ai:        'AI',\n  billing:   'Billing',\n  dashboard: 'Dashboard',\n}\n\nexport async function detect(targetDir: string): Promise<DetectionResult> {\n  const projectName = path.basename(targetDir)\n\n  // ── Read package.json ────────────────────────────────────────────────────\n  const pkgPath = path.join(targetDir, 'package.json')\n  const pkg = fs.existsSync(pkgPath)\n    ? JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))\n    : {}\n\n  const allDeps: Record<string, string> = {\n    ...pkg.dependencies,\n    ...pkg.devDependencies,\n  }\n\n  const hasNext         = 'next' in allDeps\n  const hasExpress      = 'express' in allDeps\n  const hasSwaggerJsdoc = 'swagger-jsdoc' in allDeps\n  const hasPlaywright   = '@playwright/test' in allDeps\n\n  // ── Detect test directory ────────────────────────────────────────────────\n  // Check common test directory names in order of specificity.\n  // null means \"use the config file directory\" (the default behaviour).\n  const TEST_DIR_CANDIDATES = ['e2e-tests', 'e2e', 'tests', '__tests__', 'cypress/e2e', 'test']\n  let testsPath: string | null = null\n  for (const candidate of TEST_DIR_CANDIDATES) {\n    if (fs.existsSync(path.join(targetDir, candidate))) {\n      testsPath = `./${candidate}`\n      break\n    }\n  }\n\n  // ── Determine framework and route type ──────────────────────────────────\n  let framework: Framework = 'unknown'\n  let routeType: RouteType = 'manual'\n  let routesPath: string | null = null\n  let generate: string | null = null\n\n  if (hasNext) {\n    framework = 'nextjs'\n    routeType = 'nextjs'\n\n    // Check for App Router first, then Pages Router, in likely locations\n    for (const candidate of ['src/app', 'app', 'src/pages', 'pages']) {\n      if (fs.existsSync(path.join(targetDir, candidate))) {\n        routesPath = `./${candidate}`\n        break\n      }\n    }\n  } else if (hasExpress && hasSwaggerJsdoc) {\n    framework = 'express-openapi'\n    routeType = 'openapi'\n    routesPath = './openapi.json'\n    // Suggest generate command — user must create the script, but we show them what to put\n    generate = 'npx ts-node src/generate-openapi.ts'\n  } else if (hasExpress) {\n    framework = 'express'\n    routeType = 'express'\n  }\n\n  // ── Discover routes ──────────────────────────────────────────────────────\n  // Next.js: always discoverable from the file system.\n  // OpenAPI: discoverable only if the spec file already exists on disk.\n  // Express/manual: need a generate step — skip discovery.\n  let discoveredRoutes: AppRoute[] = []\n\n  if (routesPath) {\n    const absoluteRoutesPath = path.join(targetDir, routesPath.replace('./', ''))\n    const shouldDiscover =\n      routeType === 'nextjs' ||\n      (routeType === 'openapi' && fs.existsSync(absoluteRoutesPath))\n\n    if (shouldDiscover) {\n      try {\n        const source = new RoutesSource({\n          type: routeType === 'openapi' ? 'openapi' : 'nextjs',\n          path: absoluteRoutesPath,\n        })\n        discoveredRoutes = await source.collect()\n      } catch {\n        // Not a blocker — init still works, areas will be empty\n      }\n    }\n  }\n\n  // ── Detect basePath ──────────────────────────────────────────────────────\n  const basePath = detectBasePath(discoveredRoutes)\n\n  // ── Suggest areas from discovered routes ────────────────────────────────\n  const suggestedAreas = suggestAreas(discoveredRoutes, basePath)\n\n  return {\n    projectName,\n    framework,\n    routeType,\n    routesPath,\n    testsPath,\n    generate,\n    basePath,\n    hasSwaggerJsdoc,\n    hasPlaywright,\n    discoveredRoutes,\n    suggestedAreas,\n  }\n}\n\n/**\n * Infers the common base path prefix from discovered routes.\n * Checks for /api/vN (versioned) first, then plain /api.\n * Returns null when fewer than half the routes share the prefix — avoids false guesses.\n */\nfunction detectBasePath(routes: AppRoute[]): string | null {\n  if (routes.length === 0) return null\n\n  // Check for versioned prefix /api/vN\n  const versionedPrefix = routes[0].path.match(/^(\\/api\\/v\\d+)\\//)?.[1]\n  if (versionedPrefix) {\n    const count = routes.filter(r => r.path.startsWith(versionedPrefix + '/')).length\n    if (count > routes.length * 0.5) return versionedPrefix\n  }\n\n  // Check for plain /api prefix\n  const apiCount = routes.filter(r => r.path.startsWith('/api/')).length\n  if (apiCount > routes.length * 0.5) return '/api'\n\n  return null\n}\n\n/**\n * Groups routes by their first meaningful path segment and maps each group\n * to a human-readable area name.\n * basePath (e.g. /api, /api/v1) is stripped per-route before grouping so routes\n * are organised by service name rather than the shared prefix.\n * Exported so the init command can re-run it after the user confirms/changes basePath.\n */\nexport function suggestAreas(routes: AppRoute[], basePath: string | null): SuggestedArea[] {\n  if (routes.length === 0) return []\n\n  // Group routes by suggested area name (multiple segments can map to the same name)\n  const nameGroups = new Map<string, { routes: AppRoute[]; patterns: Set<string> }>()\n\n  for (const route of routes) {\n    // Strip basePath per-route when it matches — handles mixed specs where only\n    // some routes carry the prefix (e.g. /health alongside /api/products)\n    const hasPrefix = basePath ? route.path.startsWith(basePath + '/') : false\n    const normalised = hasPrefix ? route.path.slice(basePath!.length) : route.path\n    const segments = normalised.split('/').filter(s => s.length > 0 && !s.startsWith(':'))\n    const firstSegment = segments[0] ?? ''\n\n    // Root route (/) goes into an 'uncategorised' bucket — not forced into an area\n    if (!firstSegment) continue\n\n    const areaName = toAreaName(firstSegment)\n    const pattern  = hasPrefix ? `${basePath}/${firstSegment}` : `/${firstSegment}`\n\n    if (!nameGroups.has(areaName)) {\n      nameGroups.set(areaName, { routes: [], patterns: new Set() })\n    }\n    const group = nameGroups.get(areaName)!\n    group.routes.push(route)\n    group.patterns.add(pattern)\n  }\n\n  return Array.from(nameGroups.entries()).map(([name, { routes, patterns }]) => ({\n    suggestedName: name,\n    routes,\n    patterns: Array.from(patterns),\n  }))\n}\n\n/** Converts a raw path segment to a human-readable area name. */\nfunction toAreaName(segment: string): string {\n  const lower = segment.toLowerCase()\n  if (KNOWN_AREA_NAMES[lower]) return KNOWN_AREA_NAMES[lower]\n  // Title-case unknown segments: 'invoices' → 'Invoices'\n  return segment.charAt(0).toUpperCase() + segment.slice(1)\n}\n","/**\n * src/utils/logger.ts\n *\n * Module-level singleton logger.\n * - Always writes to a log file (qualitylens.log) with timestamps and full detail.\n * - Console output is handled separately by each command — the logger only writes the file.\n *\n * Usage:\n *   import { logger } from './utils/logger'\n *   logger.configure('./reports')        // call once at startup\n *   logger.info('scan started', { config: opts.config })\n *   logger.error('route discovery failed', err)\n */\n\nimport * as fs from 'fs'\nimport * as path from 'path'\n\ntype LogLevel = 'INFO' | 'WARN' | 'ERROR' | 'DEBUG'\n\nclass Logger {\n  private logPath: string | null = null\n  private fd: number | null = null\n\n  /**\n   * Open (or create) qualitylens.log in the given directory.\n   * Appends to an existing log so multiple runs accumulate history.\n   * Call once at the start of each command.\n   */\n  configure(outputDir: string): void {\n    try {\n      fs.mkdirSync(outputDir, { recursive: true })\n      this.logPath = path.join(outputDir, 'qualitylens.log')\n      this.fd = fs.openSync(this.logPath, 'a')\n      this.write('INFO', `--- qualitylens session started (pid ${process.pid}) ---`)\n    } catch {\n      // If we can't open a log file, continue silently — logging is non-blocking\n      this.logPath = null\n      this.fd = null\n    }\n  }\n\n  /** Path to the current log file, or null if not configured. */\n  get filePath(): string | null {\n    return this.logPath\n  }\n\n  info(msg: string, detail?: unknown): void {\n    this.write('INFO', msg, detail)\n  }\n\n  warn(msg: string, detail?: unknown): void {\n    this.write('WARN', msg, detail)\n  }\n\n  /** Logs full detail (stack trace, raw error) to file only. */\n  error(msg: string, detail?: unknown): void {\n    this.write('ERROR', msg, detail)\n  }\n\n  debug(msg: string, detail?: unknown): void {\n    this.write('DEBUG', msg, detail)\n  }\n\n  close(): void {\n    if (this.fd !== null) {\n      try { fs.closeSync(this.fd) } catch { /* ignore */ }\n      this.fd = null\n    }\n  }\n\n  private write(level: LogLevel, msg: string, detail?: unknown): void {\n    if (this.fd === null) return\n\n    const ts = new Date().toISOString()\n    let line = `[${ts}] ${level.padEnd(5)} ${msg}`\n\n    if (detail !== undefined) {\n      if (detail instanceof Error) {\n        line += `\\n  ${detail.message}`\n        if (detail.stack) {\n          line += '\\n' + detail.stack.split('\\n').map(l => '  ' + l).join('\\n')\n        }\n      } else if (typeof detail === 'string' && detail.trim()) {\n        line += '\\n' + detail.split('\\n').map(l => '  ' + l).join('\\n')\n      } else if (typeof detail === 'object') {\n        try {\n          line += '\\n  ' + JSON.stringify(detail, null, 2).replace(/\\n/g, '\\n  ')\n        } catch { /* circular ref or similar — skip */ }\n      }\n    }\n\n    try {\n      fs.writeSync(this.fd, line + '\\n')\n    } catch { /* disk full or fd closed — ignore */ }\n  }\n}\n\nexport const logger = new Logger()\n","/**\n * src/sources/routes.source.ts\n * \n * Discovers application routes from the project structure.\n * Supports: Next.js pages/, Next.js app/, OpenAPI spec, Express manifest.\n * \n * AI INSTRUCTIONS:\n * Implement each strategy as a private method.\n * collect() dispatches to the right strategy based on config.type.\n */\n\nimport { AppRoute, TestGapConfig } from '../core/types'\nimport { logger } from '../utils/logger'\nimport * as fs from 'fs'\nimport * as path from 'path'\nimport glob from 'fast-glob'\n\nexport class RoutesSource {\n  constructor(private config: TestGapConfig['routes']) {}\n\n  async collect(): Promise<AppRoute[]> {\n    const type = this.config.type\n    logger.info(`[routes] collecting routes`, { type, path: this.config.path })\n\n    try {\n      switch (type) {\n        case 'nextjs':   return await this.collectNextJs()\n        case 'openapi':  return await this.collectOpenApi()\n        case 'express':  return await this.collectExpress()\n        case 'manual':   return await this.collectManual()\n        default:\n          throw new Error(\n            `Unknown routes.type \"${(this.config as any).type}\" in qualitylens.yaml.\\n` +\n            `  Valid values: nextjs, openapi, express, manual`\n          )\n      }\n    } catch (err) {\n      logger.error(`[routes] collection failed (type=${type}, path=${this.config.path})`, err)\n      throw err\n    }\n  }\n\n  /**\n   * Next.js pages/ or app/ directory scanner.\n   * \n   * AI INSTRUCTIONS:\n   * 1. Glob all .tsx, .ts, .jsx, .js files under config.path\n   * 2. Convert file path to route:\n   *    pages/checkout/payment.tsx   → /checkout/payment\n   *    pages/index.tsx              → /\n   *    pages/auth/[id].tsx          → /auth/:id\n   *    app/checkout/page.tsx        → /checkout  (App Router pattern)\n   * 3. Skip: _app, _document, _error, api/ routes, layout.tsx, loading.tsx\n   * 4. Return AppRoute[]\n   */\n  private async collectNextJs(): Promise<AppRoute[]> {\n    const rootPath = path.resolve(this.config.path)\n\n    if (!fs.existsSync(rootPath)) {\n      throw new Error(\n        `Next.js routes directory not found: ${rootPath}\\n` +\n        `  Check routes.path in qualitylens.yaml — it should point to your pages/ or app/ directory.`\n      )\n    }\n\n    // Detect App Router vs Pages Router by looking for files named \"page.tsx/ts\".\n    // App Router  → files are named page.tsx inside route folders: app/cart/page.tsx\n    // Pages Router → files ARE the routes: pages/cart.tsx\n    const appRouterPages = await glob('**/page.{tsx,ts,jsx,js}', {\n      cwd: rootPath,\n      absolute: false,\n      ignore: ['**/node_modules/**'],\n    })\n\n    if (appRouterPages.length > 0) {\n      // ── App Router ──────────────────────────────────────────────────────────\n      return appRouterPages.map(filePath => {\n        // fast-glob always uses forward slashes — safe to split on '/' on all OSes.\n        // filePath examples:\n        //   page.tsx                  → /\n        //   cart/page.tsx             → /cart\n        //   orders/[id]/page.tsx      → /orders/:id\n        //   (auth)/login/page.tsx     → /login  (route groups in parens are stripped)\n\n        // Remove the trailing \"/page.tsx\" (or page.ts etc.)\n        const dir = filePath\n          .replace(/\\/page\\.[jt]sx?$/, '')\n          .replace(/^page\\.[jt]sx?$/, '')\n\n        // Strip route groups: (auth) → removed entirely\n        const segments = dir\n          .split('/')\n          .filter(seg => !(seg.startsWith('(') && seg.endsWith(')')))\n\n        // Convert [param] dynamic segments to :param\n        const routeSegments = segments.map(seg =>\n          seg.startsWith('[') && seg.endsWith(']') ? `:${seg.slice(1, -1)}` : seg\n        )\n\n        const normalised = ('/' + routeSegments.join('/')).replace(/\\/+/g, '/').replace(/\\/$/, '') || '/'\n        return { path: normalised }\n      })\n    }\n\n    // ── Pages Router ──────────────────────────────────────────────────────────\n    const pageFiles = await glob('**/*.{tsx,ts,jsx,js}', {\n      cwd: rootPath,\n      absolute: false,\n      ignore: ['**/node_modules/**', '**/_app.*', '**/_document.*', '**/_error.*', '**/api/**'],\n    })\n\n    return pageFiles.map(filePath => {\n      // pages/checkout/payment.tsx → /checkout/payment\n      // pages/index.tsx            → /\n      const withoutExt = filePath.replace(/\\.[jt]sx?$/, '')\n      const withoutIndex = withoutExt.replace(/(^|\\/)index$/, '')\n      const segments = withoutIndex\n        .split('/')\n        .map(seg => seg.startsWith('[') && seg.endsWith(']') ? `:${seg.slice(1, -1)}` : seg)\n\n      return { path: ('/' + segments.join('/')).replace(/\\/+/g, '/').replace(/\\/$/, '') || '/' }\n    })\n  }\n\n  /**\n   * OpenAPI / Swagger spec parser.\n   * \n   * AI INSTRUCTIONS:\n   * 1. Read the JSON or YAML file at config.path\n   * 2. Extract spec.paths object — keys are route paths\n   * 3. For each path, extract HTTP methods (get, post, put, delete, patch)\n   * 4. Return one AppRoute per path+method combination\n   * 5. Support both JSON (.json) and YAML (.yaml, .yml) specs\n   */\n  private async collectOpenApi(): Promise<AppRoute[]> {\n    const absPath = path.resolve(this.config.path)\n\n    if (!fs.existsSync(absPath)) {\n      throw new Error(\n        `OpenAPI spec not found: ${absPath}\\n` +\n        `  If your spec is generated at build time, check the routes.generate command in qualitylens.yaml.\\n` +\n        `  Run the generate command manually first to confirm it produces the file.`\n      )\n    }\n\n    let content: string\n    try {\n      content = fs.readFileSync(absPath, 'utf-8')\n    } catch (err) {\n      throw new Error(`Could not read OpenAPI spec at ${absPath}: ${(err as Error).message}`)\n    }\n\n    // Support both JSON and YAML OpenAPI specs — detect by file extension\n    const ext = path.extname(this.config.path).toLowerCase()\n    let spec: any\n    try {\n      spec = (ext === '.json')\n        ? JSON.parse(content)\n        : (await import('js-yaml')).load(content)\n    } catch (err) {\n      throw new Error(\n        `Failed to parse OpenAPI spec at ${absPath} as ${ext === '.json' ? 'JSON' : 'YAML'}.\\n` +\n        `  Parse error: ${(err as Error).message}\\n` +\n        `  Check the file is valid by running: node -e \"JSON.parse(require('fs').readFileSync('${absPath}','utf-8'))\"`\n      )\n    }\n\n    // The OpenAPI `paths` object is a map of route → { get: {}, post: {}, ... }\n    // e.g. { '/api/products': { get: {...}, post: {...} }, '/api/products/{id}': { get: {...} } }\n    const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options']\n    const routes: AppRoute[] = []\n\n    for (const [routePath, pathItem] of Object.entries(spec.paths ?? {})) {\n      // Convert OpenAPI {param} style to :param style (consistent with the rest of qualitylens)\n      const normalisedPath = routePath.replace(/\\{(\\w+)\\}/g, ':$1')\n\n      for (const method of HTTP_METHODS) {\n        if ((pathItem as any)[method]) {\n          routes.push({ path: normalisedPath, method: method.toUpperCase() })\n        }\n      }\n    }\n\n    return routes\n  }\n\n  /**\n   * Express routes manifest (JSON file).\n   * Format: [{ path: '/checkout', method: 'GET' }, ...]\n   * Users generate this with express-list-routes or similar.\n   */\n  private async collectExpress(): Promise<AppRoute[]> {\n    return this.readJsonRouteManifest('express')\n  }\n\n  /**\n   * Manual route list in qualitylens.yaml.\n   * config.path points to a JSON file with [{ path: '/route' }]\n   */\n  private async collectManual(): Promise<AppRoute[]> {\n    return this.readJsonRouteManifest('manual')\n  }\n\n  /** Shared reader for express and manual JSON route manifests. */\n  private readJsonRouteManifest(type: string): AppRoute[] {\n    const absPath = path.resolve(this.config.path)\n\n    if (!fs.existsSync(absPath)) {\n      throw new Error(\n        `Routes manifest not found: ${absPath}\\n` +\n        `  routes.type is \"${type}\" — qualitylens expects a JSON file at routes.path.\\n` +\n        `  Format: [{ \"path\": \"/api/users\", \"method\": \"GET\" }, ...]`\n      )\n    }\n\n    let content: string\n    try {\n      content = fs.readFileSync(absPath, 'utf-8')\n    } catch (err) {\n      throw new Error(`Could not read routes manifest at ${absPath}: ${(err as Error).message}`)\n    }\n\n    try {\n      return JSON.parse(content) as AppRoute[]\n    } catch (err) {\n      throw new Error(\n        `Failed to parse routes manifest at ${absPath} as JSON.\\n` +\n        `  Parse error: ${(err as Error).message}\\n` +\n        `  Expected format: [{ \"path\": \"/api/users\", \"method\": \"GET\" }, ...]`\n      )\n    }\n  }\n}\n"],"mappings":"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","names":["fs","path","fs","path","routes"]}

package/dist/core/engine.d.mts

@@ -0,0 +1,29 @@
+import { TestGapConfig, CoverageReport } from './types.mjs';
+import { BaseSource } from '../sources/base.source.mjs';
+import { RoutesSource } from '../sources/routes.source.mjs';
+import { FuzzyMatcher } from '../matchers/fuzzy.matcher.mjs';
+import { AreaMatcher } from '../matchers/area.matcher.mjs';
+
+/**
+ * src/core/engine.ts
+ *
+ * The main orchestrator. Zero I/O — all dependencies injected.
+ * This design makes the engine fully unit-testable with mock sources.
+ *
+ * AI INSTRUCTIONS: implement run() using the step-by-step comments.
+ */
+
+declare class CoverageEngine {
+    private sources;
+    private routesSource;
+    private matcher;
+    private areaMatcher;
+    private config;
+    constructor(sources: BaseSource[], routesSource: RoutesSource, matcher: FuzzyMatcher, areaMatcher: AreaMatcher, config: TestGapConfig);
+    run(): Promise<CoverageReport>;
+    private deriveStatus;
+    private deriveStaleness;
+    private latestDate;
+}
+
+export { CoverageEngine };

package/dist/core/engine.d.ts

@@ -0,0 +1,29 @@
+import { TestGapConfig, CoverageReport } from './types.js';
+import { BaseSource } from '../sources/base.source.js';
+import { RoutesSource } from '../sources/routes.source.js';
+import { FuzzyMatcher } from '../matchers/fuzzy.matcher.js';
+import { AreaMatcher } from '../matchers/area.matcher.js';
+
+/**
+ * src/core/engine.ts
+ *
+ * The main orchestrator. Zero I/O — all dependencies injected.
+ * This design makes the engine fully unit-testable with mock sources.
+ *
+ * AI INSTRUCTIONS: implement run() using the step-by-step comments.
+ */
+
+declare class CoverageEngine {
+    private sources;
+    private routesSource;
+    private matcher;
+    private areaMatcher;
+    private config;
+    constructor(sources: BaseSource[], routesSource: RoutesSource, matcher: FuzzyMatcher, areaMatcher: AreaMatcher, config: TestGapConfig);
+    run(): Promise<CoverageReport>;
+    private deriveStatus;
+    private deriveStaleness;
+    private latestDate;
+}
+
+export { CoverageEngine };

package/dist/core/engine.js

@@ -0,0 +1,151 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/engine.ts
+var engine_exports = {};
+__export(engine_exports, {
+  CoverageEngine: () => CoverageEngine
+});
+module.exports = __toCommonJS(engine_exports);
+var CoverageEngine = class {
+  constructor(sources, routesSource, matcher, areaMatcher, config) {
+    this.sources = sources;
+    this.routesSource = routesSource;
+    this.matcher = matcher;
+    this.areaMatcher = areaMatcher;
+    this.config = config;
+  }
+  async run() {
+    const sourceResults = await Promise.all(this.sources.map((s) => s.collect()));
+    const allTests = sourceResults.flat();
+    const routes = await this.routesSource.collect();
+    const matchMap = this.matcher.match(routes, allTests);
+    const matchedTests = /* @__PURE__ */ new Set();
+    for (const tests of matchMap.values()) {
+      for (const t of tests) matchedTests.add(t);
+    }
+    const hints = this.config.testHints ?? [];
+    const hintMap = /* @__PURE__ */ new Map();
+    for (const hint of hints) hintMap.set(hint.test, hint);
+    const routeGaps = [];
+    const acknowledgedTests = [];
+    const hintResolved = /* @__PURE__ */ new Set();
+    for (const test of allTests) {
+      if (matchedTests.has(test)) continue;
+      const hint = hintMap.get(test.title);
+      if (!hint) continue;
+      if (hint.status === "resolved" && hint.route) {
+        const key = hint.method ? `${hint.method} ${hint.route}` : hint.route;
+        const existing = matchMap.get(key) ?? [];
+        matchMap.set(key, [...existing, test]);
+        matchedTests.add(test);
+        hintResolved.add(test);
+      } else if (hint.status === "gap") {
+        const existing = routeGaps.find(
+          (g) => g.route === hint.route && g.method === hint.method
+        );
+        if (existing) {
+          existing.coveredByTests.push(test);
+        } else {
+          routeGaps.push({
+            route: hint.route ?? test.title,
+            method: hint.method,
+            reason: hint.reason,
+            coveredByTests: [test]
+          });
+        }
+        matchedTests.add(test);
+      } else if (hint.status === "acknowledged" || hint.status === "ignore") {
+        acknowledgedTests.push(hint);
+        matchedTests.add(test);
+      }
+    }
+    const routeCoverages = routes.map((route) => {
+      const key = route.method ? `${route.method} ${route.path}` : route.path;
+      const matched = matchMap.get(key) ?? [];
+      const automatedTests = matched.filter((t) => t.source === "playwright");
+      const manualTests = matched.filter((t) => t.source === "ado" || t.source === "yaml");
+      const status = this.deriveStatus(automatedTests.length, manualTests.length);
+      const lastTestedAt = this.latestDate([...automatedTests, ...manualTests]);
+      const staleness = this.deriveStaleness(lastTestedAt, manualTests.length);
+      return {
+        route,
+        status,
+        automatedTests,
+        manualTests,
+        staleness,
+        lastTestedAt
+      };
+    });
+    const { areas, uncategorised } = this.areaMatcher.assign(routeCoverages);
+    const total = routeCoverages.length;
+    const automated = routeCoverages.filter((r) => r.status === "automated" || r.status === "both").length;
+    const manualOnly = routeCoverages.filter((r) => r.status === "manual").length;
+    const none = routeCoverages.filter((r) => r.status === "none").length;
+    const toLRM = (counts) => {
+      if (total === 0) return counts.map(() => 0);
+      const exact = counts.map((n) => n / total * 100);
+      const floored = exact.map((n) => Math.floor(n));
+      const remainder = 100 - floored.reduce((a, b) => a + b, 0);
+      const order = exact.map((n, i) => ({ i, frac: n - Math.floor(n) })).sort((a, b) => b.frac - a.frac);
+      for (let k = 0; k < remainder; k++) floored[order[k].i]++;
+      return floored;
+    };
+    const [automatedCoverage, manualOnlyCoverage, noCoverage] = toLRM([automated, manualOnly, none]);
+    const totalCoverage = automatedCoverage + manualOnlyCoverage;
+    return {
+      generatedAt: /* @__PURE__ */ new Date(),
+      projectName: this.config.projectName,
+      summary: {
+        totalRoutes: total,
+        totalCoverage,
+        automatedCoverage,
+        manualOnlyCoverage,
+        noCoverage
+      },
+      areas,
+      uncategorised,
+      unmatchedTests: allTests.filter((t) => !matchedTests.has(t)),
+      routeGaps,
+      acknowledgedTests
+    };
+  }
+  deriveStatus(autoCount, manualCount) {
+    if (autoCount > 0 && manualCount > 0) return "both";
+    if (autoCount > 0) return "automated";
+    if (manualCount > 0) return "manual";
+    return "none";
+  }
+  deriveStaleness(lastTestedAt, manualCount) {
+    if (manualCount === 0) return "unknown";
+    if (!lastTestedAt) return "unknown";
+    const daysSince = (Date.now() - lastTestedAt.getTime()) / (1e3 * 60 * 60 * 24);
+    return daysSince > this.config.staleThresholdDays ? "stale" : "fresh";
+  }
+  latestDate(tests) {
+    const dates = tests.map((t) => t.lastRun).filter((d) => d instanceof Date);
+    if (dates.length === 0) return void 0;
+    return new Date(Math.max(...dates.map((d) => d.getTime())));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CoverageEngine
+});
+//# sourceMappingURL=engine.js.map