chore: initial release v1.0.0

Author: qa-ashutosh

.eslintrc.json

@@ -0,0 +1,19 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module"
+  },
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "no-console": "off"
+  },
+  "ignorePatterns": ["dist/", "node_modules/", "*.js"]
+}

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,25 @@
+---
+name: Bug report
+about: Something isn't working correctly
+title: '[bug] '
+labels: bug
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**To reproduce**
+Steps to reproduce the behaviour, including the test file content that triggers the issue.
+
+**Expected behaviour**
+What you expected to happen.
+
+**Environment**
+- assert-guard version:
+- Node.js version:
+- OS:
+
+**Config (ag.config.json)**
+```json
+
+```

.github/ISSUE_TEMPLATE/rule_request.md

@@ -0,0 +1,20 @@
+---
+name: Rule request
+about: Suggest a new quality rule
+title: '[rule] '
+labels: enhancement
+---
+
+**What anti-pattern should this rule catch?**
+Describe the bad practice with a code example.
+
+**Why is this harmful in a test suite?**
+Explain the real-world consequences (flakiness, maintenance burden, CI failures, etc.)
+
+**What should the fix hint say?**
+What guidance should assert-guard give to the developer?
+
+**Suggested severity**
+- [ ] error (blocks merge)
+- [ ] warn (advisory)
+- [ ] info (informational)

.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test & Build
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm run test:coverage
+
+      - name: Upload coverage
+        uses: actions/upload-artifact@v4
+        if: matrix.node-version == '20.x'
+        with:
+          name: coverage-report
+          path: coverage/
+
+  self-scan:
+    name: Self Quality Gate
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+      - name: Run assert-guard on test fixtures
+        run: node bin/assert-guard.js scan --dir ./tests --format cli || true

.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+
+      - name: Publish
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+coverage/
+assert-guard-reports/
+*.tsbuildinfo
+.DS_Store
+.env
+.env.local

CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to assert-guard are documented here.
+
+This project follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+_Nothing yet._
+
+---
+
+## [1.0.0] — 2026-04-15
+
+### Added
+
+- **Core rule engine** — AST-based scanner using `@babel/parser` with TypeScript and JSX support
+- **7 built-in rules** covering the most common test anti-patterns:
+  - `no-hard-waits` (error) — flags `cy.wait(N)`, `Thread.sleep()`, `page.waitForTimeout()`
+  - `no-logic-in-tests` (error) — detects `if/else`, `for` loops, and `try/catch` inside test blocks
+  - `no-focused-tests` (error) — catches `it.only()`, `test.only()`, `fit()`, `fdescribe()`
+  - `no-hardcoded-credentials` (error) — detects hardcoded passwords, tokens, and API keys
+  - `no-flaky-selectors` (warn) — flags `nth-child()`, absolute XPath, and generated CSS class selectors
+  - `single-assertion-focus` (warn) — warns when a test block exceeds the configured assertion limit
+  - `test-isolation-check` (info) — detects shared `let` state declared at describe scope
+- **CLI commands**: `scan`, `init`, `rules`
+- **Three report formats**: `cli` (coloured terminal), `json`, `html` (self-contained single file)
+- **Quality gate exit codes**: exits `1` on errors (or warnings when `failOnWarnings: true`), `0` on pass
+- **`ag.config.json` config file** — customise rules, include/exclude globs, assertion limits, output directory
+- **`assert-guard init`** — scaffolds a default config file
+- **`assert-guard rules`** — lists all available rules with their default severity
+- **GitHub Actions workflows** — CI (test + build on Node 18/20) and npm publish on release
+- **Full TypeScript** — ships with `.d.ts` declarations for use as a library
+- **Programmatic API** — all core functions exported from the main entry point
+
+### Rules detail
+
+| Rule | Default | Catches |
+|------|---------|---------|
+| `no-hard-waits` | error | `cy.wait(N)`, `Thread.sleep()`, `waitForTimeout()` |
+| `no-logic-in-tests` | error | `if`, `for`, `for..of`, `try/catch` inside `it()`/`test()` |
+| `no-focused-tests` | error | `it.only`, `test.only`, `describe.only`, `fit`, `fdescribe` |
+| `no-hardcoded-credentials` | error | hardcoded passwords, tokens, API keys in test files |
+| `no-flaky-selectors` | warn | positional CSS, absolute XPath, generated class names |
+| `single-assertion-focus` | warn | more than N assertions per test (default N=5) |
+| `test-isolation-check` | info | shared `let` state in `describe` scope |
+
+---
+
+[Unreleased]: https://github.com/qa-ashutosh/assert-guard/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/qa-ashutosh/assert-guard/releases/tag/v1.0.0

CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to assert-guard
+
+Thank you for your interest in contributing! assert-guard is open source and welcomes community contributions — especially new rules.
+
+## Getting started
+
+```bash
+git clone https://github.com/qa-ashutosh/assert-guard.git
+cd assert-guard
+npm install
+npm run build
+npm test
+```
+
+## Adding a new rule
+
+Each rule lives in `src/rules/` as its own TypeScript file. Here is the minimum shape:
+
+```typescript
+import traverse from '@babel/traverse';
+import * as t from '@babel/types';
+import type { Rule, Violation } from '../types';
+
+const rule: Rule = {
+  name: 'your-rule-name',          // kebab-case, unique
+  description: 'One sentence.',
+  severity: 'warn',                // 'error' | 'warn' | 'info'
+  hint: 'What the developer should do instead.',
+
+  check(ast, filePath): Violation[] {
+    const violations: Violation[] = [];
+    traverse(ast, {
+      // visit AST nodes here
+    });
+    return violations;
+  },
+};
+
+export default rule;
+```
+
+Then register it in `src/rules/index.ts` and add a default severity to `DEFAULT_CONFIG`.
+
+Every rule must have a corresponding test file in `tests/rules/`.
+
+## Running tests
+
+```bash
+npm test              # run all tests
+npm run test:coverage # with coverage report
+```
+
+## Code style
+
+- TypeScript strict mode is enforced
+- Run `npm run lint` before opening a PR
+- Keep dependencies minimal — if the standard library can do it, prefer that
+
+## Pull request checklist
+
+- [ ] New rule has unit tests covering at least: one positive case, one negative (no false positive), and one edge case
+- [ ] Rule is registered in `src/rules/index.ts`
+- [ ] `CHANGELOG.md` entry added under `[Unreleased]`
+- [ ] `npm test` passes locally
+
+## Reporting bugs
+
+Use the GitHub issue tracker with the bug report template.
+
+## Suggesting rules
+
+Open an issue using the rule request template. Include a code example of the anti-pattern and explain why it's harmful.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashutosh Parihar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.