ai-test-guardrails 0.2.0 → 0.2.1

package/README.md

@@ -1,10 +1,13 @@
 # ai-test-guardrails
 
+[![npm version](https://img.shields.io/npm/v/ai-test-guardrails.svg)](https://www.npmjs.com/package/ai-test-guardrails)
+[![licence](https://img.shields.io/npm/l/ai-test-guardrails.svg)](./LICENSE)
+
 An MCP (Model Context Protocol) server that provides deterministic guardrails for AI-generated and existing test automation. It validates Playwright and Cypress test proposals using AST-based analysis — detecting flake-prone patterns, enforcing architecture rules, scoring risk, and scanning entire projects in a single call.
 
 ## What It Does
 
-- **Validates** AI-generated test code for determinism, flake risk, and architecture compliance
+- **Validates** AI-generated test/ existing test code for determinism, flake risk, and architecture compliance
 - **Classifies** violations as `critical`, `major`, or `minor` for prioritised remediation
 - **Scans** entire project directories, validating every test file in one pass with severity breakdown
 - **Detects** flake-prone constructs: hard sleeps, unbounded retries, unmocked network calls, dynamic selectors
@@ -422,10 +425,66 @@ tests/
 └── severity.test.ts
 ```
 
+## Contributing
+
+Contributions, bug reports, and feature suggestions are welcome. This is an open source project and community input directly shapes the roadmap.
+
+### Reporting Issues
+
+If you find a bug or unexpected behaviour, please [open an issue](https://github.com/jch1887/ai-test-guardrails/issues) and include:
+
+- A minimal code snippet that reproduces the problem
+- The framework (`playwright` or `cypress`) and enforcement mode you were using
+- The full tool output (JSON response)
+- Your Node.js version (`node --version`)
+
+### Suggesting Features or New Rules
+
+Have an idea for a new validation rule, flake risk factor, or tool feature? [Open an issue](https://github.com/jch1887/ai-test-guardrails/issues) with the label **`enhancement`** and describe:
+
+- The problem or pattern you want to catch
+- Why it matters for test reliability or architecture
+- Any example code that should trigger (or not trigger) the rule
+
+### Submitting a Pull Request
+
+1. Fork the repository and create a branch from `main`
+2. Install dependencies: `npm install`
+3. Make your changes — new rules live in `src/validators/`, new flake factors in `src/validators/flakeRisk.ts`
+4. Add or update tests in `tests/` to cover your change
+5. Ensure all checks pass:
+
+```bash
+npm test          # all tests must pass
+npm run lint      # no lint errors
+npm run typecheck # no type errors
+```
+
+6. Open a pull request against `main` with a clear description of what changed and why
+
+### Development Setup
+
+```bash
+git clone https://github.com/jch1887/ai-test-guardrails.git
+cd ai-test-guardrails
+npm install
+npm run build
+npm test
+```
+
+### Code Style
+
+- TypeScript strict mode is enabled — avoid `any`
+- Prettier and ESLint configs are included; run `npm run format` before committing
+- Keep rule logic self-contained and unit-testable
+- Violation messages should be actionable: say what to do, not just what went wrong
+
+---
+
 ## Roadmap
 
 - [x] **v0.1** — Core validation engine, three enforcement modes, project scanning
-- [x] **v0.2** — Violation severity tiers (critical / major / minor), k6 detection, severity breakdown in scan summary, two-pass `.js`/`.ts` file discovery
+- [x] **v0.2** — Violation severity tiers (critical / major / minor), severity breakdown in scan summary, two-pass `.js`/`.ts` file discovery
 - [ ] **v0.3** — Auto-fix suggestions in violation messages
 - [ ] **v0.3** — Cypress-specific selector pattern detection
 - [ ] **v0.4** — Support for custom rule plugins

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-test-guardrails",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "MCP server providing deterministic guardrails for AI-generated test automation",
   "type": "module",
   "main": "./dist/server.js",

package/.cursor/mcp.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "ai-test-guardrails": {
-      "command": "node",
-      "args": ["/Users/jason/Documents/GitHub/ai-test-guardrails/dist/server.js"]
-    }
-  }
-}

package/.prettierrc

@@ -1,8 +0,0 @@
-{
-  "semi": true,
-  "trailingComma": "all",
-  "singleQuote": false,
-  "printWidth": 100,
-  "tabWidth": 2,
-  "arrowParens": "always"
-}

package/eslint.config.js

@@ -1,25 +0,0 @@
-import tseslint from "typescript-eslint";
-
-export default tseslint.config(
-  {
-    ignores: ["dist/", "node_modules/", "*.config.*"],
-  },
-  ...tseslint.configs.strictTypeChecked,
-  {
-    languageOptions: {
-      parserOptions: {
-        projectService: true,
-        tsconfigRootDir: import.meta.dirname,
-      },
-    },
-    rules: {
-      "@typescript-eslint/no-unused-vars": [
-        "error",
-        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
-      ],
-      "@typescript-eslint/explicit-function-return-type": "error",
-      "@typescript-eslint/no-explicit-any": "error",
-      "@typescript-eslint/strict-boolean-expressions": "off",
-    },
-  },
-);

package/examples/playwright/.auth/care-admin-api-rest-dev-0.json

@@ -1 +0,0 @@
-{}

package/examples/playwright/.auth/care-admin-api-rest-stage-0.json

@@ -1 +0,0 @@
-{}

package/examples/playwright/.auth/care-admin-api-soap-dev-0.json

@@ -1 +0,0 @@
-{}

package/examples/playwright/.auth/care-admin-api-soap-stage-0.json

@@ -1 +0,0 @@
-{}

package/examples/playwright/.auth/care-admin-dev-0.json

@@ -1 +0,0 @@
-{}

package/examples/playwright/.auth/care-admin-stage-0-data.json

@@ -1 +0,0 @@
-{}

package/examples/playwright/.auth/care-admin-stage-0.json

@@ -1 +0,0 @@
-{}

package/examples/playwright/.auth/care-admin-stage-1.json

@@ -1 +0,0 @@
-{}

package/examples/playwright/.auth/care-admin-stage-2.json

@@ -1 +0,0 @@
-{}

package/examples/playwright/.auth/care-community-dev-0-data.json

@@ -1,3 +0,0 @@
-{
-  "localStorage": {}
-}

package/examples/playwright/.auth/care-community-dev-0.json

@@ -1,15 +0,0 @@
-{
-  "cookies": [
-    {
-      "name": "PHPSESSID",
-      "value": "3qoqnrnr3rj3fola066u63pgm2",
-      "domain": "fs.care.idss-dev.iu-aws.de",
-      "path": "/",
-      "expires": -1,
-      "httpOnly": true,
-      "secure": false,
-      "sameSite": "Lax"
-    }
-  ],
-  "origins": []
-}

package/examples/playwright/.auth/care-community-stage-0.json

@@ -1 +0,0 @@
-{}

package/examples/playwright/care-admin-base.ts

@@ -1,66 +0,0 @@
-import { createTest, expect } from "@iu/playwright-test-utils/care-admin/base";
-import type { Page } from "@playwright/test";
-import { BetterCareButtonPage } from "./pages/better-care/better-care-button.page";
-import { MenuPage } from "./pages/better-care/menu.page";
-import { Main } from "./pages/care-admin/main.frame";
-import { Nav } from "./pages/care-admin/nav.frame";
-import { SetupPage } from "./pages/care-admin/setup.page";
-import { StudyProgramsPage } from "./pages/care-admin/study-programs.page";
-import { Toolbar } from "./pages/care-admin/toolbar.frame";
-
-/*
-  This file allows us to inherit any fixtures from the utils library as well as add our own.
-
-  See https://playwright.dev/docs/test-fixtures for more details or the Care Community base file for a more comprehensive example.
-*/
-
-type TestFixtures = {
-  page: Page;
-  setup: SetupPage;
-  studyPrograms: StudyProgramsPage;
-  toolbar: Toolbar;
-  main: Main;
-  nav: Nav;
-  // Better Care
-  menu: MenuPage;
-  betterCareButton: BetterCareButtonPage;
-};
-
-const base = createTest();
-
-const test = base.extend<TestFixtures>({
-  async page({ page }, use) {
-    await use(page);
-  },
-
-  async setup({ page }, use) {
-    await use(new SetupPage(page));
-  },
-
-  async toolbar({ page }, use) {
-    await use(new Toolbar(page));
-  },
-
-  async nav({ page }, use) {
-    await use(new Nav(page));
-  },
-
-  async main({ page }, use) {
-    await use(new Main(page));
-  },
-
-  async studyPrograms({ page, setup, toolbar, main }, use) {
-    await use(new StudyProgramsPage(page, setup, toolbar, main));
-  },
-
-  // Better Care
-  async menu({ nav }, use) {
-    await use(new MenuPage(nav));
-  },
-
-  async betterCareButton({ page }, use) {
-    await use(new BetterCareButtonPage(page));
-  },
-});
-
-export { test, expect };

package/examples/playwright/care-community-base.ts

@@ -1,65 +0,0 @@
-import {
-  createTest,
-  expect,
-} from "@iu/playwright-test-utils/care-community/base";
-import type { Page } from "@playwright/test";
-import { CourseRegistrationPage } from "./pages/care-community/course-registration.page";
-import { DocumentsPage } from "./pages/care-community/documents.page";
-import { ExaminationResultsPage } from "./pages/care-community/examination-results.page";
-import { NavBar } from "./pages/care-community/nav-bar.page";
-import { Language } from "./pages/language.page";
-
-const base = createTest();
-
-type TestFixtures = {
-  page: Page;
-  navBar: NavBar;
-  courseRegistrationPage: CourseRegistrationPage;
-  documentsPage: DocumentsPage;
-  examinationResultsPage: ExaminationResultsPage;
-  language: Language;
-};
-
-/*
-  This file allows us to inherit any fixtures from the utils library as well as add our own.
-
-  In this example we are inheriting the fixtures provided from the utils library and adding our own additional fixtures.
-
-  For example we have added `language` and `navBar` which means they can be imported into all our spec files without manual imports.
-
-  See https://playwright.dev/docs/test-fixtures for more details.
-*/
-
-const test = base.extend<TestFixtures>({
-  async page({ page }, use) {
-    await use(page);
-  },
-
-  async language({ page }, use, testInfo) {
-    const language = new Language(page, testInfo);
-
-    await use(language);
-  },
-
-  async navBar({ page, language }, use) {
-    const navBar = new NavBar(page, language);
-    await use(navBar);
-  },
-
-  async documentsPage({ page, language }, use) {
-    const documentsPage = new DocumentsPage(page, language);
-    await use(documentsPage);
-  },
-
-  async examinationResultsPage({ page }, use) {
-    const examinationResultsPage = new ExaminationResultsPage(page);
-    await use(examinationResultsPage);
-  },
-
-  async courseRegistrationPage({ page }, use) {
-    const courseRegistrationPage = new CourseRegistrationPage(page);
-    await use(courseRegistrationPage);
-  },
-});
-
-export { test, expect };

package/examples/playwright/constants.ts

@@ -1,3 +0,0 @@
-export const PROFILE_ID = "10608473"; //  Academy5Id/AC5ID - QI Esmeralda
-export const BOOKING_ID = "10958750"; // Default booking for "QI Esmeralda FS Study Tester"
-export const COURSE_ID = "10050031"; // Course ID for "Einführung in die Soziale Arbeit (DLBSAESA01-QI)" in FS BA QIBA test study programme

package/examples/playwright/pages/better-care/better-care-button.page.ts

@@ -1,15 +0,0 @@
-import type { Locator, Page } from "@playwright/test";
-
-export class BetterCareButtonPage {
-  readonly bubble: Locator;
-  readonly infoPanel: Locator;
-  readonly debugModeToggle: Locator;
-
-  constructor(private readonly page: Page) {
-    this.bubble = this.page
-      .getByTestId("bcv2-global-module-container")
-      .filter({ hasText: "Better Care" });
-    this.infoPanel = this.page.getByTestId("bcv2-info-panel");
-    this.debugModeToggle = this.infoPanel.getByTestId("debug-mode-toggle");
-  }
-}

package/examples/playwright/pages/better-care/menu.page.ts

@@ -1,14 +0,0 @@
-import type { Locator } from "@playwright/test";
-import type { Nav } from "../care-admin/nav.frame";
-
-export class MenuPage {
-  readonly peopleSearch: Locator;
-  readonly studyPrograms: Locator;
-  readonly showFullMenu: Locator;
-
-  constructor(private readonly nav: Nav) {
-    this.peopleSearch = this.nav.frame.getByTestId("menu-people-search");
-    this.studyPrograms = this.nav.frame.getByTestId("menu-study-programs");
-    this.showFullMenu = this.nav.frame.getByTestId("menu-show-full-menu");
-  }
-}

package/examples/playwright/pages/care-admin/main.frame.ts

@@ -1,17 +0,0 @@
-import type { FrameLocator, Locator, Page } from "@playwright/test";
-
-type MenuItems = {
-  edit: Locator;
-};
-
-export class Main {
-  readonly frame: FrameLocator;
-  readonly menuItems: MenuItems;
-
-  constructor(private readonly page: Page) {
-    this.frame = this.page.frameLocator("#main");
-    this.menuItems = {
-      edit: this.frame.locator(".menuitems").filter({ hasText: "Bearbeiten" }),
-    };
-  }
-}

package/examples/playwright/pages/care-admin/nav.frame.ts

@@ -1,9 +0,0 @@
-import type { FrameLocator, Page } from "@playwright/test";
-
-export class Nav {
-  readonly frame: FrameLocator;
-
-  constructor(private readonly page: Page) {
-    this.frame = this.page.frameLocator("#nav");
-  }
-}

package/examples/playwright/pages/care-admin/setup.page.ts

@@ -1,131 +0,0 @@
-import type { Frame, FrameLocator, Locator, Page } from "@playwright/test";
-import { expect } from "playwright/care-admin-base";
-
-export class SetupPage {
-  readonly sideBySideFrame: FrameLocator;
-  readonly navBar: Locator;
-  readonly reminder: Locator;
-  readonly reminderClose: Locator;
-
-  constructor(private readonly page: Page) {
-    this.sideBySideFrame = this.page.frameLocator("#side-by-side-iframe");
-    this.navBar = this.page.locator("#navbar-academy-five");
-    this.reminder = this.page.locator(".p-reminder");
-    this.reminderClose = this.page.locator(".p-reminder-close");
-  }
-
-  private async waitForHomeUrl() {
-    // wait till the url changed to /home (note that Firefox loads home#)
-    await this.page.waitForURL("/home**");
-  }
-
-  private async setupAuthenticatedPage() {
-    // Navigate to login page
-    await this.page.goto("/");
-
-    await this.waitForHomeUrl();
-
-    // wait till #navbar-academy-five exists and is visible
-    await expect(this.navBar).toBeVisible({ timeout: 20000 });
-
-    // wait till everything is loaded
-    await this.page.waitForLoadState("domcontentloaded");
-
-    // wait till frame elements exist on page
-    await this.page.waitForSelector("#nav", { state: "visible" });
-    await this.page.waitForSelector("#main", { state: "visible" });
-
-    // Debug: Log all available frames
-    const allFrames: Record<string, Frame> = {};
-    for (const f of this.page.frames()) {
-      if (f.isDetached()) {
-        continue;
-      }
-      allFrames[
-        f.name() ||
-          (await f
-            .frameElement()
-            .then((el) => el?.getAttribute("id"))
-            .catch(() => null)) ||
-          ""
-      ] = f;
-    }
-
-    // get frame accessors
-    const navFrame = allFrames.nav;
-    const mainFrame = allFrames.main;
-    const toolbarFrame = allFrames.toolbar;
-    const sideBySideFrame = allFrames["side-by-side-iframe"];
-
-    // check if all frames exist
-    if (!navFrame) {
-      console.error("Failed to get navigation frame [name=nav]", navFrame);
-      throw new Error("Failed to get navigation frame [name=nav]");
-    }
-    if (!mainFrame) {
-      console.error("Failed to get main frame [name=main]", mainFrame);
-      throw new Error("Failed to get main frame [name=main]");
-    }
-    if (!toolbarFrame) {
-      console.error("Failed to get toolbar frame [name=toolbar]", toolbarFrame);
-      throw new Error("Failed to get toolbar frame [name=toolbar]");
-    }
-    if (!sideBySideFrame) {
-      throw new Error(
-        "Failed to get side-by-side-iframe [name=side-by-side-iframe]",
-      );
-    }
-
-    // wait for all frames to be loaded
-    await Promise.all([
-      navFrame.waitForLoadState("domcontentloaded"),
-      mainFrame.waitForLoadState("domcontentloaded"),
-      toolbarFrame.waitForLoadState("domcontentloaded"),
-    ]);
-
-    // wait untl mainFrame has url "/dashboard"
-    await mainFrame.waitForURL("/dashboard");
-  }
-
-  public async frameGoto(url: string, timeout?: number) {
-    await this.page.evaluate((url) => {
-      const iFrame = document.querySelector<HTMLIFrameElement>(
-        'iframe[name="main"]',
-      );
-      if (iFrame) {
-        iFrame.src = url;
-      }
-    }, url);
-
-    // Wait for frame to be fully loaded
-    await this.page.waitForLoadState("domcontentloaded");
-    await this.page.waitForLoadState("networkidle", { timeout });
-  }
-
-  public async loadPage(caseName?: string) {
-    await this.page.route("**/*", (route) => {
-      const headers = {
-        ...route.request().headers(),
-        "X-Test-Context": caseName || "default",
-      };
-      route.continue({ headers });
-    });
-
-    await this.setupAuthenticatedPage();
-    await this.waitForHomeUrl();
-
-    if (await this.reminder.isVisible()) {
-      await this.reminderClose.click();
-    }
-
-    return {
-      registerApiMock: async (
-        url: string,
-        response: {
-          statusCode: number;
-          body: string;
-        },
-      ) => {},
-    };
-  }
-}