@elench/testkit 0.1.117 → 0.1.119

package/lib/lint/index.mjs

@@ -0,0 +1,569 @@
+import fs from "fs";
+import path from "path";
+import ts from "typescript";
+import { findConfigFile } from "../config/config-loader.mjs";
+import { normalizePath } from "../config/paths.mjs";
+
+const DEFAULT_EXCLUDED_DIRS = new Set([
+  ".git",
+  ".next",
+  ".next-testkit",
+  ".testkit",
+  "coverage",
+  "dist",
+  "node_modules",
+  "playwright-report",
+]);
+
+const DEFAULT_UI_MAX_LINES = 220;
+const DEFAULT_UI_MAX_TESTS = 8;
+
+export async function runLint(options = {}) {
+  const productDir = path.resolve(process.cwd(), options.dir || ".");
+  const lintOptions = normalizeLintOptions(options);
+  const files = collectSourceFiles(productDir);
+  const testkitFiles = files.filter((filePath) => isTestkitSuiteFile(filePath));
+  const aliasResolver = createAliasResolver(productDir, files);
+  const violations = [];
+
+  if (lintOptions.rules.missingImports) {
+    violations.push(...findMissingImports(productDir, files, aliasResolver));
+  }
+  if (lintOptions.rules.uiRuntimeImports) {
+    violations.push(...findPlaywrightRuntimeImportViolations(productDir, testkitFiles));
+  }
+  if (lintOptions.rules.uiSpecShape) {
+    violations.push(...findUiSpecShapeViolations(productDir, testkitFiles, lintOptions.ui));
+  }
+  if (lintOptions.rules.dalParallelSafety) {
+    violations.push(...findDalParallelSafetyViolations(productDir, files, testkitFiles));
+  }
+  if (lintOptions.rules.legacyHttpAssertions) {
+    violations.push(...findLegacyHttpAssertionViolations(productDir, testkitFiles));
+  }
+  if (lintOptions.rules.legacyDalAssertions) {
+    violations.push(...findLegacyDalAssertionViolations(productDir, testkitFiles));
+  }
+  if (lintOptions.rules.configImports) {
+    violations.push(...findConfigImportViolations(productDir));
+  }
+
+  const sortedViolations = violations.sort(compareViolations);
+  return {
+    ok: sortedViolations.length === 0,
+    productDir,
+    summary: {
+      files: files.length,
+      testkitFiles: testkitFiles.length,
+      violations: sortedViolations.length,
+    },
+    violations: sortedViolations,
+  };
+}
+
+export function normalizeLintConfig(config = {}) {
+  const lint = config?.lint || {};
+  return normalizeLintOptions(lint);
+}
+
+function normalizeLintOptions(options = {}) {
+  const rules = options.rules || {};
+  const disabled = new Set(Array.isArray(options.disable) ? options.disable : []);
+  const enabled = {
+    missingImports: true,
+    uiRuntimeImports: true,
+    uiSpecShape: true,
+    dalParallelSafety: true,
+    legacyHttpAssertions: true,
+    legacyDalAssertions: true,
+    configImports: true,
+  };
+
+  for (const [ruleName, value] of Object.entries(rules)) {
+    if (Object.prototype.hasOwnProperty.call(enabled, ruleName)) {
+      enabled[ruleName] = value !== false;
+    }
+  }
+  for (const ruleName of disabled) {
+    if (Object.prototype.hasOwnProperty.call(enabled, ruleName)) {
+      enabled[ruleName] = false;
+    }
+  }
+
+  return {
+    rules: enabled,
+    ui: {
+      maxLines: normalizePositiveInteger(options.ui?.maxLines, DEFAULT_UI_MAX_LINES),
+      maxTests: normalizePositiveInteger(options.ui?.maxTests, DEFAULT_UI_MAX_TESTS),
+    },
+  };
+}
+
+function normalizePositiveInteger(value, fallback) {
+  if (value == null) return fallback;
+  const normalized = Number(value);
+  if (!Number.isInteger(normalized) || normalized <= 0) {
+    throw new Error("lint numeric limits must be positive integers");
+  }
+  return normalized;
+}
+
+function collectSourceFiles(rootDir) {
+  const out = [];
+  walk(rootDir, out);
+  return out.sort((left, right) => left.localeCompare(right));
+
+  function walk(current, entries) {
+    if (!fs.existsSync(current)) return;
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const absolutePath = path.join(current, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        if (DEFAULT_EXCLUDED_DIRS.has(entry.name)) continue;
+        walk(absolutePath, entries);
+        continue;
+      }
+      if (entry.isFile() && isSourceLikeFile(entry.name)) {
+        entries.push(absolutePath);
+      }
+    }
+  }
+}
+
+function isSourceLikeFile(fileName) {
+  return /\.(?:[cm]?[jt]sx?|json)$/.test(fileName);
+}
+
+function isTypeScriptLikeFile(filePath) {
+  return /\.(?:[cm]?tsx?|jsx?)$/.test(filePath);
+}
+
+function isTestkitSuiteFile(filePath) {
+  return /\.(?:int|e2e|scenario|dal|load|ui)\.testkit\.ts$/.test(filePath);
+}
+
+function relative(productDir, absolutePath) {
+  return normalizePath(path.relative(productDir, absolutePath));
+}
+
+function readSourceFile(filePath) {
+  return ts.createSourceFile(
+    filePath,
+    fs.readFileSync(filePath, "utf8"),
+    ts.ScriptTarget.Latest,
+    true,
+    filePath.endsWith(".tsx") || filePath.endsWith(".jsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS
+  );
+}
+
+function violationFromSource(ruleId, productDir, filePath, sourceFile, node, message, extra = {}) {
+  const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  const snippet = node.getText(sourceFile).split(/\r?\n/)[0] || null;
+  return {
+    ruleId,
+    severity: "error",
+    file: relative(productDir, filePath),
+    line: position.line + 1,
+    message,
+    ...(snippet ? { snippet } : {}),
+    ...extra,
+  };
+}
+
+function findMissingImports(productDir, files, aliasResolver) {
+  const violations = [];
+  for (const filePath of files.filter(isTypeScriptLikeFile)) {
+    const sourceFile = readSourceFile(filePath);
+    for (const statement of sourceFile.statements) {
+      if (!isImportLike(statement)) continue;
+      if (!statement.moduleSpecifier) continue;
+      if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+      const specifier = statement.moduleSpecifier.text;
+      if (!shouldResolveImport(specifier, aliasResolver)) continue;
+      if (resolveImport(filePath, specifier, aliasResolver)) continue;
+      violations.push(
+        violationFromSource(
+          "missing-import",
+          productDir,
+          filePath,
+          sourceFile,
+          statement,
+          `Import "${specifier}" could not be resolved`
+        )
+      );
+    }
+  }
+  return violations;
+}
+
+function isImportLike(statement) {
+  return ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement);
+}
+
+function shouldResolveImport(specifier, aliasResolver) {
+  if (specifier.startsWith(".")) return true;
+  return aliasResolver.mappings.some((mapping) => specifier.startsWith(mapping.prefix));
+}
+
+function createAliasResolver(productDir, files) {
+  const mappings = [];
+  for (const configPath of files.filter((filePath) => path.basename(filePath) === "tsconfig.json")) {
+    const parsed = readJson(configPath);
+    const paths = parsed?.compilerOptions?.paths;
+    if (!paths || typeof paths !== "object") continue;
+    const baseUrl = path.resolve(path.dirname(configPath), parsed.compilerOptions?.baseUrl || ".");
+    for (const [alias, targets] of Object.entries(paths)) {
+      if (!Array.isArray(targets)) continue;
+      const starIndex = alias.indexOf("*");
+      const prefix = starIndex >= 0 ? alias.slice(0, starIndex) : alias;
+      const suffix = starIndex >= 0 ? alias.slice(starIndex + 1) : "";
+      mappings.push({
+        prefix,
+        suffix,
+        hasStar: starIndex >= 0,
+        targets: targets.map((target) => ({
+          raw: target,
+          base: baseUrl,
+        })),
+      });
+    }
+  }
+  return { productDir, mappings };
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function resolveImport(importerPath, specifier, aliasResolver) {
+  if (specifier.startsWith(".")) {
+    return resolveCandidate(path.resolve(path.dirname(importerPath), specifier));
+  }
+  for (const mapping of aliasResolver.mappings) {
+    if (!specifier.startsWith(mapping.prefix) || !specifier.endsWith(mapping.suffix)) continue;
+    const matched = mapping.hasStar
+      ? specifier.slice(mapping.prefix.length, specifier.length - mapping.suffix.length)
+      : "";
+    for (const target of mapping.targets) {
+      const rawTarget = mapping.hasStar ? target.raw.replace("*", matched) : target.raw;
+      const resolved = resolveCandidate(path.resolve(target.base, rawTarget));
+      if (resolved) return resolved;
+    }
+  }
+  return null;
+}
+
+function resolveCandidate(candidate) {
+  for (const filePath of expandImportCandidates(candidate)) {
+    if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) return filePath;
+  }
+  return null;
+}
+
+function expandImportCandidates(candidate) {
+  const parsed = path.parse(candidate);
+  const candidates = [candidate];
+  const extensionAlternates = {
+    ".js": [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"],
+    ".mjs": [".mts", ".mjs"],
+    ".cjs": [".cts", ".cjs"],
+    ".jsx": [".tsx", ".jsx"],
+  };
+  if (extensionAlternates[parsed.ext]) {
+    candidates.push(...extensionAlternates[parsed.ext].map((ext) => path.join(parsed.dir, `${parsed.name}${ext}`)));
+  } else if (!parsed.ext) {
+    candidates.push(
+      `${candidate}.ts`,
+      `${candidate}.tsx`,
+      `${candidate}.mts`,
+      `${candidate}.cts`,
+      `${candidate}.js`,
+      `${candidate}.jsx`,
+      `${candidate}.mjs`,
+      `${candidate}.cjs`,
+      path.join(candidate, "index.ts"),
+      path.join(candidate, "index.tsx"),
+      path.join(candidate, "index.mts"),
+      path.join(candidate, "index.js"),
+      path.join(candidate, "index.mjs")
+    );
+  }
+  return [...new Set(candidates)];
+}
+
+function findPlaywrightRuntimeImportViolations(productDir, testkitFiles) {
+  const violations = [];
+  for (const filePath of testkitFiles.filter((entry) => entry.endsWith(".ui.testkit.ts"))) {
+    const sourceFile = readSourceFile(filePath);
+    for (const statement of sourceFile.statements) {
+      if (!ts.isImportDeclaration(statement)) continue;
+      if (!hasRuntimePlaywrightImport(statement)) continue;
+      violations.push(
+        violationFromSource(
+          "ui-runtime-imports",
+          productDir,
+          filePath,
+          sourceFile,
+          statement,
+          "UI suites must import runtime helpers from @elench/testkit/ui, not @playwright/test"
+        )
+      );
+    }
+  }
+  return violations;
+}
+
+function hasRuntimePlaywrightImport(statement) {
+  if (!ts.isStringLiteral(statement.moduleSpecifier)) return false;
+  if (statement.moduleSpecifier.text !== "@playwright/test") return false;
+  const clause = statement.importClause;
+  if (!clause) return true;
+  if (clause.isTypeOnly) return false;
+  if (clause.name) return true;
+  if (!clause.namedBindings) return true;
+  if (ts.isNamespaceImport(clause.namedBindings)) return true;
+  return clause.namedBindings.elements.some((element) => !element.isTypeOnly);
+}
+
+function findUiSpecShapeViolations(productDir, testkitFiles, options) {
+  const violations = [];
+  for (const filePath of testkitFiles.filter((entry) => entry.endsWith(".ui.testkit.ts"))) {
+    const source = fs.readFileSync(filePath, "utf8");
+    const lines = source.split(/\r?\n/).length;
+    const tests = countPlaywrightTests(source);
+    if (lines > options.maxLines || tests > options.maxTests) {
+      violations.push({
+        ruleId: "ui-spec-shape",
+        severity: "error",
+        file: relative(productDir, filePath),
+        line: 1,
+        message: `UI spec exceeds shape limit (${lines}/${options.maxLines} lines, ${tests}/${options.maxTests} tests)`,
+      });
+    }
+  }
+  return violations;
+}
+
+function countPlaywrightTests(source) {
+  return [...source.matchAll(/\btest\s*\(\s*['"`]/g)].length;
+}
+
+function findDalParallelSafetyViolations(productDir, files, testkitFiles) {
+  const violations = [];
+  const dalFiles = testkitFiles.filter((entry) => entry.endsWith(".dal.testkit.ts"));
+  const duplicateFields = new Map(["slug", "email", "authProviderId"].map((field) => [field, new Map()]));
+
+  for (const filePath of dalFiles) {
+    const source = fs.readFileSync(filePath, "utf8");
+    if (/\btruncate\s*\(/.test(source) || /\.\s*truncate\s*\(/.test(source)) {
+      violations.push({
+        ruleId: "dal-parallel-safety",
+        severity: "error",
+        file: relative(productDir, filePath),
+        line: firstMatchingLine(source, /\btruncate\s*\(|\.\s*truncate\s*\(/),
+        message: "DAL specs must not truncate shared tables; seed namespaced rows and scope queries instead",
+      });
+    }
+
+    for (const field of duplicateFields.keys()) {
+      const matcher = new RegExp(`${field}\\s*:\\s*(['"])([^'"\\\\]*(?:\\\\.[^'"\\\\]*)*)\\1`, "g");
+      for (const match of source.matchAll(matcher)) {
+        const value = match[2];
+        if (!value) continue;
+        const occurrences = duplicateFields.get(field).get(value) || [];
+        occurrences.push({ filePath, index: match.index || 0 });
+        duplicateFields.get(field).set(value, occurrences);
+      }
+    }
+  }
+
+  for (const [field, values] of duplicateFields) {
+    for (const [value, occurrences] of values) {
+      const uniqueFiles = [...new Set(occurrences.map((entry) => entry.filePath))];
+      if (uniqueFiles.length <= 1) continue;
+      for (const occurrence of occurrences) {
+        violations.push({
+          ruleId: "dal-parallel-safety",
+          severity: "error",
+          file: relative(productDir, occurrence.filePath),
+          line: lineForIndex(fs.readFileSync(occurrence.filePath, "utf8"), occurrence.index),
+          message: `Duplicate ${field} literal "${value}" appears across DAL specs; use fixture-derived namespaced values`,
+        });
+      }
+    }
+  }
+
+  for (const filePath of files.filter((entry) => isTestkitHelperFile(productDir, entry))) {
+    const source = stripComments(fs.readFileSync(filePath, "utf8"));
+    if (/ON\s+CONFLICT(?:\s*\([^)]*\))?\s+DO\s+NOTHING/i.test(source)) {
+      violations.push({
+        ruleId: "dal-parallel-safety",
+        severity: "error",
+        file: relative(productDir, filePath),
+        line: firstMatchingLine(source, /ON\s+CONFLICT(?:\s*\([^)]*\))?\s+DO\s+NOTHING/i),
+        message: "Testkit helper seed code must not use ON CONFLICT DO NOTHING; collisions should fail loudly",
+      });
+    }
+  }
+
+  return violations;
+}
+
+function isTestkitHelperFile(productDir, filePath) {
+  const parts = relative(productDir, filePath).split("/");
+  return parts.includes("__testkit__") && parts.includes("helpers") && filePath.endsWith(".ts");
+}
+
+function stripComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+}
+
+function firstMatchingLine(source, pattern) {
+  const lines = source.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    if (pattern.test(lines[index])) return index + 1;
+  }
+  return 1;
+}
+
+function lineForIndex(source, index) {
+  return source.slice(0, index).split(/\r?\n/).length;
+}
+
+function findLegacyHttpAssertionViolations(productDir, testkitFiles) {
+  const violations = [];
+  for (const filePath of testkitFiles.filter((entry) => !entry.endsWith(".dal.testkit.ts"))) {
+    const sourceFile = readSourceFile(filePath);
+    visit(sourceFile, (node) => {
+      if (!isLegacyHttpStatusCheck(node, sourceFile)) return;
+      violations.push(
+        violationFromSource(
+          "legacy-http-assertions",
+          productDir,
+          filePath,
+          sourceFile,
+          node,
+          "HTTP response status assertions must use expectStatus/expectStatusOneOf"
+        )
+      );
+    });
+  }
+  return violations;
+}
+
+function isLegacyHttpStatusCheck(node, sourceFile) {
+  if (!ts.isCallExpression(node)) return false;
+  if (node.expression.getText(sourceFile) !== "check") return false;
+  if (node.arguments.length !== 2 || !ts.isObjectLiteralExpression(node.arguments[1])) return false;
+  const targetText = node.arguments[0]?.getText(sourceFile) || "";
+  if (!/^(?:res|[A-Za-z_$][\w$]*Res)$/.test(targetText)) return false;
+
+  for (const property of node.arguments[1].properties) {
+    if (!ts.isPropertyAssignment(property)) continue;
+    const initializer = unwrap(property.initializer);
+    if (!ts.isArrowFunction(initializer) && !ts.isFunctionExpression(initializer)) continue;
+    if (initializer.parameters.length === 0 || ts.isBlock(initializer.body)) continue;
+    const paramName = initializer.parameters[0]?.name.getText(sourceFile);
+    if (paramName && hasLegacyStatusPredicate(initializer.body, paramName, sourceFile)) return true;
+  }
+  return false;
+}
+
+function unwrap(expression) {
+  while (ts.isParenthesizedExpression(expression)) {
+    expression = expression.expression;
+  }
+  return expression;
+}
+
+function hasLegacyStatusPredicate(expression, paramName, sourceFile) {
+  expression = unwrap(expression);
+  if (!ts.isBinaryExpression(expression)) return false;
+  if (
+    expression.operatorToken.kind === ts.SyntaxKind.EqualsEqualsEqualsToken ||
+    expression.operatorToken.kind === ts.SyntaxKind.ExclamationEqualsEqualsToken
+  ) {
+    return isParamStatus(expression.left, paramName, sourceFile) || isParamStatus(expression.right, paramName, sourceFile);
+  }
+  if (expression.operatorToken.kind === ts.SyntaxKind.BarBarToken) {
+    return (
+      hasLegacyStatusPredicate(expression.left, paramName, sourceFile) ||
+      hasLegacyStatusPredicate(expression.right, paramName, sourceFile)
+    );
+  }
+  return false;
+}
+
+function isParamStatus(expression, paramName, sourceFile) {
+  expression = unwrap(expression);
+  return (
+    ts.isPropertyAccessExpression(expression) &&
+    expression.expression.getText(sourceFile) === paramName &&
+    expression.name.getText(sourceFile) === "status"
+  );
+}
+
+function findLegacyDalAssertionViolations(productDir, testkitFiles) {
+  const violations = [];
+  for (const filePath of testkitFiles.filter((entry) => entry.endsWith(".dal.testkit.ts"))) {
+    const sourceFile = readSourceFile(filePath);
+    visit(sourceFile, (node) => {
+      if (!ts.isCallExpression(node)) return;
+      if (node.expression.getText(sourceFile) !== "check") return;
+      violations.push(
+        violationFromSource(
+          "legacy-dal-assertions",
+          productDir,
+          filePath,
+          sourceFile,
+          node,
+          "DAL assertions must use Testkit expect* helpers instead of raw check(...)"
+        )
+      );
+    });
+  }
+  return violations;
+}
+
+function findConfigImportViolations(productDir) {
+  const configFile = findConfigFile(productDir);
+  if (!configFile || !fs.existsSync(configFile)) return [];
+  const sourceFile = readSourceFile(configFile);
+  const violations = [];
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    const specifier = statement.moduleSpecifier.text;
+    if (!specifier.startsWith(".") && !specifier.startsWith("/")) continue;
+    if (!specifier.includes("__testkit__")) continue;
+    violations.push(
+      violationFromSource(
+        "config-imports",
+        productDir,
+        configFile,
+        sourceFile,
+        statement,
+        "testkit.config.ts must not import repo-local __testkit__ helper modules"
+      )
+    );
+  }
+  return violations;
+}
+
+function visit(node, fn) {
+  fn(node);
+  ts.forEachChild(node, (child) => visit(child, fn));
+}
+
+function compareViolations(left, right) {
+  return (
+    left.file.localeCompare(right.file) ||
+    (left.line || 0) - (right.line || 0) ||
+    left.ruleId.localeCompare(right.ruleId) ||
+    left.message.localeCompare(right.message)
+  );
+}