@scantrix/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scantrix
+
+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.

package/README.md

@@ -0,0 +1,219 @@
+<p align="center">
+  <img src="docs/scantrix-logo-light.svg" alt="Scantrix" width="420" />
+</p>
+
+<h3 align="center">
+<em>Playwright</em> · <em>Cypress</em> ·<em> Selenium</em></br>
+Find out why your tests keep failing without running a single one.
+</h3>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> &middot;
+  <a href="#output-formats">Output</a> &middot;
+  <a href="#cli-reference">CLI Reference</a> &middot;
+  <a href="#github-action">GitHub Action</a> &middot;
+  <a href="docs/RULES.md">Rules</a> &middot;
+  <a href="#license">License</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Scantrix/scantrix/actions/workflows/ci.yml">
+    <img src="https://img.shields.io/github/actions/workflow/status/Scantrix/scantrix/ci.yml?branch=main&label=build" alt="Build Status" />
+  </a>
+  <a href="https://www.npmjs.com/package/@scantrix/cli">
+    <img src="https://img.shields.io/npm/v/@scantrix/cli?color=cb3837&logo=npm&logoColor=white" alt="NPM Version" />
+  </a>
+  <a href="#license">
+    <img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT" />
+  </a>
+</p>
+
+---
+
+Most tools tell you a test failed. **Scantrix tells you why your entire approach is failing** and exactly how to fix it.
+
+ No test execution. No credentials. No file modifications. Just root causes.
+
+### EXAMPLE FINDING
+![Example Finding](docs/images/findings.svg)
+
+### KEY CAPABILITIES
+  >
+  >| Capability        | Traditional Reporters     | Scantrix                          |
+  >|-------------------|---------------------------|-----------------------------------|
+  >| Analysis          | Runtime (Post Failure)    | Static (Pre-emptive)              |
+  >| Scope             | Single Test Result        | Repository wide Health            |
+  >| Root Cause        | Stack Trace only          | Correlated Design Patterns        |
+  >| Actionability     | "Test Failed"             | Step-by-step Fix Guidance         |
+  >| CI Impact         | Log bloat                 | CI Pipeline Optimization          |
+  >| Security          | Requires Tokens           | Zero Footprint (Local Execution)  |
+
+</br>
+
+### RISK OVERVIEW
+
+![Risk Overview](docs/images/risk.svg)
+
+### RECOMMENDED ACTIONS
+
+![Recommended Actions](docs/images/recommendations.svg)
+
+
+## What Scantrix Diagnoses
+
+**Flaky test root causes.** Not just which tests fail, but exactly why they fail and what will actually fix them.
+
+**Framework-level design debt.** Structural patterns that silently destabilize entire test suites before anyone realizes something is wrong.
+
+**CI configuration risks.** The environmental factors making your pipeline unpredictable run to run.
+
+**Blast radius of bad patterns.** One anti-pattern can affect hundreds of tests. Scantrix quantifies that exposure so you know where to act first.
+
+**Execution waste.** Where time is being burned in your pipeline and the precise changes that recover it.
+
+
+## What Scantrix Does NOT Do
+Scantrix operates as a zero-footprint, read-only analyzer, ensuring repository integrity while maintaining a strict security posture. <br>
+-  It does not execute your tests <br>
+-  It does not modify any files in the target repository <br>
+-  It does not make network connections beyond the local filesystem <br>
+-  It does not require credentials and access tokens of any kind </br>
+
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Scan a repository
+node dist/cli.js /path/to/repo --out ./audit-out
+
+# Or use the shorthand (builds + scans)
+npm run audit -- /path/to/repo --out ./audit-out
+```
+
+## Output Formats
+
+Every scan produces an **overall risk grade (A through F)** alongside severity-bucketed findings.
+
+| Format | File | Description |
+|--------|------|-------------|
+| Markdown | `audit_summary.md` | Primary report with executive-grade findings and hotspots |
+| HTML | `audit_summary.html` | Styled report for browser viewing |
+| JSON | `findings.json` | Machine-readable findings array |
+| SARIF | `audit.sarif` | Native GitHub Code Scanning and Azure DevOps support — findings appear directly in the Security tab |
+| Email | `audit_email.html` | Email-ready HTML summary |
+
+Use `--format` to select specific formats:
+
+```bash
+node dist/cli.js /path/to/repo --out ./audit-out --format md,json,sarif
+```
+
+
+
+## CLI Reference
+
+```
+scantrix <repoPath> [options]
+scantrix init [dir]
+```
+
+### Scan Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--out <dir>` | Output directory for reports | `./audit-out` |
+| `--format <list>` | Comma-separated formats: `md,html,json,sarif,email` | all |
+| `--config <path>` | Path to `.auditrc.json` config file | auto-detected |
+| `--updates` | Check npm registry for outdated dependencies | off |
+| `--diff <path>` | Explicit baseline `findings.json` for comparison | auto |
+| `--json-path <path>` | Write canonical `ScanResult` JSON to this path | — |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SCANTRIX_JSON_PATH` | Write canonical results JSON to this path |
+
+### Init Subcommand
+
+```bash
+# Create a starter .auditrc.json in the target repo
+node dist/cli.js init /path/to/repo
+```
+
+## Configuration
+
+Create an `.auditrc.json` in the target repository to customize behavior:
+
+```bash
+node dist/cli.js init /path/to/repo
+```
+
+The config file supports rule overrides (disable rules, adjust severity) and scan options. See [CLI Architecture](docs/CLI_ARCHITECTURE.md) for details.
+
+## GitHub Action
+
+Use Scantrix in CI with the provided composite action:
+
+```yaml
+- uses: Scantrix/scantrix@v1
+  with:
+    repo-path: "."
+    output-dir: "./scantrix-out"
+    format: "md,html,json,sarif"
+    post-comment: "true"    # Post summary on PRs
+    fail-on-high: "true"    # Block merges with high-severity findings
+```
+
+### Action Inputs
+
+| Input | Description | Default |
+|-------|-------------|---------|
+| `repo-path` | Path to repository to scan | `.` |
+| `output-dir` | Directory for audit artifacts | `./scantrix-out` |
+| `config-path` | Path to `.auditrc.json` | — |
+| `format` | Output formats (comma-separated) | `md,html,json,sarif` |
+| `check-updates` | Check for outdated dependencies | `false` |
+| `post-comment` | Post summary comment on PRs | `true` |
+| `fail-on-high` | Fail if high-severity findings exist | `false` |
+
+### Action Outputs
+
+| Output | Description |
+|--------|-------------|
+| `findings-count` | Total number of findings |
+| `high-count` | Number of high-severity findings |
+| `medium-count` | Number of medium-severity findings |
+| `low-count` | Number of low-severity findings |
+| `risk-grade` | Overall risk grade (A through F) |
+| `report-path` | Path to generated report directory |
+
+## Documentation
+
+- [Rules Reference](docs/RULES.md) — all 87 finding rules with severity and description
+- [CI Integration](docs/CI_INTEGRATION.md) — CI pipeline setup and quality gates
+- [CLI Architecture](docs/CLI_ARCHITECTURE.md) — module diagram and data flow
+- [Security](SECURITY.md) — security model and threat considerations
+- [Finding Reference](docs/FINDING_REFERENCE.md) — complete finding ID catalog
+
+## Contributing
+
+Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.
+
+```bash
+# Run the test suite
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+## License
+
+[MIT](LICENSE) — See LICENSE file.</br>

package/dist/astConfigParser.js

@@ -0,0 +1,308 @@
+"use strict";
+/**
+ * AST-based Playwright config parser using the TypeScript Compiler API.
+ *
+ * This module parses playwright.config.ts/js using a real TypeScript AST instead
+ * of regexes, handling:
+ *   - Computed values: `60 * 1000`, `2 * 60 * 1000`
+ *   - Spread operators: `...baseUse` (recorded as unknown)
+ *   - Ternary expressions: `process.env.CI ? 2 : 0` (recorded as the raw source text)
+ *   - Variable references within the same file
+ *   - `satisfies` keyword (TS 4.9+)
+ *   - Template literals (partial)
+ *   - Array/object literals (recursed)
+ *
+ * Falls back gracefully when encountering unsupported patterns.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseConfigWithAst = parseConfigWithAst;
+const typescript_1 = __importDefault(require("typescript"));
+// ─── Public API ──────────────────────────────────────────────────────
+/**
+ * Parse a Playwright config file using the TypeScript compiler API.
+ * Returns a structured PlaywrightConfigSummary, or undefined if parsing fails.
+ */
+function parseConfigWithAst(filePath, sourceText) {
+    try {
+        const sourceFile = typescript_1.default.createSourceFile(filePath, sourceText, typescript_1.default.ScriptTarget.Latest, 
+        /* setParentNodes */ true);
+        // Build a simple scope of top-level `const x = ...` declarations
+        const scope = buildFileScope(sourceFile);
+        // Find the config object: `defineConfig({...})` or `export default {...}`
+        const configNode = findConfigObject(sourceFile);
+        if (!configNode)
+            return undefined;
+        const raw = evaluateObject(configNode, scope);
+        if (!raw || typeof raw !== "object")
+            return undefined;
+        return mapToSummary(filePath, raw, scope);
+    }
+    catch {
+        return undefined;
+    }
+}
+function buildFileScope(sourceFile) {
+    const scope = new Map();
+    for (const stmt of sourceFile.statements) {
+        // const FOO = expr;
+        if (typescript_1.default.isVariableStatement(stmt)) {
+            for (const decl of stmt.declarationList.declarations) {
+                if (typescript_1.default.isIdentifier(decl.name) && decl.initializer) {
+                    scope.set(decl.name.text, decl.initializer);
+                }
+            }
+        }
+    }
+    return scope;
+}
+// ─── Config Object Finder ────────────────────────────────────────────
+function findConfigObject(sourceFile) {
+    let result;
+    function visit(node) {
+        // defineConfig({ ... })
+        if (typescript_1.default.isCallExpression(node) &&
+            typescript_1.default.isIdentifier(node.expression) &&
+            node.expression.text === "defineConfig" &&
+            node.arguments.length >= 1) {
+            const arg = node.arguments[0];
+            if (typescript_1.default.isObjectLiteralExpression(arg)) {
+                result = arg;
+                return;
+            }
+        }
+        // export default { ... }
+        if (typescript_1.default.isExportAssignment(node) && !node.isExportEquals) {
+            let expr = node.expression;
+            // Handle: export default { ... } satisfies PlaywrightTestConfig
+            if (typescript_1.default.isSatisfiesExpression?.(expr)) {
+                expr = expr.expression;
+            }
+            // Handle: export default { ... } as PlaywrightTestConfig
+            if (typescript_1.default.isAsExpression(expr)) {
+                expr = expr.expression;
+            }
+            if (typescript_1.default.isObjectLiteralExpression(expr)) {
+                result = expr;
+                return;
+            }
+        }
+        typescript_1.default.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return result;
+}
+// ─── AST Evaluator ───────────────────────────────────────────────────
+// Tries to evaluate AST nodes into plain JS values.
+// Returns undefined for unevaluable nodes, or the raw source text as a string.
+function evaluateNode(node, scope) {
+    // Numeric literal
+    if (typescript_1.default.isNumericLiteral(node)) {
+        return Number(node.text);
+    }
+    // String literal
+    if (typescript_1.default.isStringLiteral(node) || typescript_1.default.isNoSubstitutionTemplateLiteral(node)) {
+        return node.text;
+    }
+    // Boolean
+    if (node.kind === typescript_1.default.SyntaxKind.TrueKeyword)
+        return true;
+    if (node.kind === typescript_1.default.SyntaxKind.FalseKeyword)
+        return false;
+    if (node.kind === typescript_1.default.SyntaxKind.UndefinedKeyword)
+        return undefined;
+    if (node.kind === typescript_1.default.SyntaxKind.NullKeyword)
+        return null;
+    // Identifier — look up in scope
+    if (typescript_1.default.isIdentifier(node)) {
+        const ref = scope.get(node.text);
+        if (ref)
+            return evaluateNode(ref, scope);
+        return `<ref:${node.text}>`;
+    }
+    // Binary expression (multiplication, addition)
+    if (typescript_1.default.isBinaryExpression(node)) {
+        const left = evaluateNode(node.left, scope);
+        const right = evaluateNode(node.right, scope);
+        if (typeof left === "number" && typeof right === "number") {
+            switch (node.operatorToken.kind) {
+                case typescript_1.default.SyntaxKind.AsteriskToken: return left * right;
+                case typescript_1.default.SyntaxKind.PlusToken: return left + right;
+                case typescript_1.default.SyntaxKind.MinusToken: return left - right;
+                case typescript_1.default.SyntaxKind.SlashToken: return right !== 0 ? left / right : undefined;
+            }
+        }
+        // Logical OR for fallback patterns: `process.env.X || 'default'`
+        if (node.operatorToken.kind === typescript_1.default.SyntaxKind.BarBarToken) {
+            // Return the raw source expression as a string for display
+            return node.getText();
+        }
+        // Return raw expression text
+        return node.getText();
+    }
+    // Conditional (ternary) expression
+    if (typescript_1.default.isConditionalExpression(node)) {
+        // We can't evaluate process.env.CI at parse time, so return the raw text
+        return node.getText();
+    }
+    // Property access: process.env.CI, devices['Desktop Chrome']
+    if (typescript_1.default.isPropertyAccessExpression(node) || typescript_1.default.isElementAccessExpression(node)) {
+        return node.getText();
+    }
+    // Prefix unary: !condition, -number
+    if (typescript_1.default.isPrefixUnaryExpression(node)) {
+        const operand = evaluateNode(node.operand, scope);
+        if (node.operator === typescript_1.default.SyntaxKind.ExclamationToken && typeof operand === "boolean")
+            return !operand;
+        if (node.operator === typescript_1.default.SyntaxKind.MinusToken && typeof operand === "number")
+            return -operand;
+        return node.getText();
+    }
+    // Object literal
+    if (typescript_1.default.isObjectLiteralExpression(node)) {
+        return evaluateObject(node, scope);
+    }
+    // Array literal
+    if (typescript_1.default.isArrayLiteralExpression(node)) {
+        return node.elements.map((el) => evaluateNode(el, scope));
+    }
+    // Spread element
+    if (typescript_1.default.isSpreadElement(node)) {
+        return { __spread: node.expression.getText() };
+    }
+    // Call expression: require.resolve('...'), etc.
+    if (typescript_1.default.isCallExpression(node)) {
+        // Try to get the first string argument
+        if (node.arguments.length > 0 && typescript_1.default.isStringLiteral(node.arguments[0])) {
+            return node.arguments[0].text;
+        }
+        return node.getText();
+    }
+    // Template expression: `${process.env.BASE_URL}/api`
+    if (typescript_1.default.isTemplateExpression(node)) {
+        return node.getText();
+    }
+    // ParenthesizedExpression
+    if (typescript_1.default.isParenthesizedExpression(node)) {
+        return evaluateNode(node.expression, scope);
+    }
+    // `satisfies` expression (TS 4.9+)
+    if (typescript_1.default.isSatisfiesExpression?.(node)) {
+        return evaluateNode(node.expression, scope);
+    }
+    // `as` expression
+    if (typescript_1.default.isAsExpression(node)) {
+        return evaluateNode(node.expression, scope);
+    }
+    // Fallback: raw text
+    return node.getText();
+}
+function evaluateObject(node, scope) {
+    const result = {};
+    for (const prop of node.properties) {
+        // Spread assignment: ...baseConfig
+        if (typescript_1.default.isSpreadAssignment(prop)) {
+            result.__spreads = result.__spreads || [];
+            result.__spreads.push(prop.expression.getText());
+            continue;
+        }
+        if (typescript_1.default.isPropertyAssignment(prop)) {
+            const key = getPropertyName(prop);
+            if (key) {
+                result[key] = evaluateNode(prop.initializer, scope);
+            }
+        }
+        // Shorthand property: { workers }
+        if (typescript_1.default.isShorthandPropertyAssignment(prop)) {
+            const key = prop.name.text;
+            const ref = scope.get(key);
+            result[key] = ref ? evaluateNode(ref, scope) : `<ref:${key}>`;
+        }
+        // Method declaration: ignored (not typical in config)
+    }
+    return result;
+}
+function getPropertyName(prop) {
+    const name = prop.name;
+    if (typescript_1.default.isIdentifier(name))
+        return name.text;
+    if (typescript_1.default.isStringLiteral(name))
+        return name.text;
+    if (typescript_1.default.isComputedPropertyName(name))
+        return undefined; // can't evaluate
+    return undefined;
+}
+// ─── Mapping to PlaywrightConfigSummary ──────────────────────────────
+function asNumber(v) {
+    if (typeof v === "number" && Number.isFinite(v))
+        return v;
+    return undefined;
+}
+function asString(v) {
+    if (typeof v === "string")
+        return v;
+    return undefined;
+}
+function mapToSummary(filePath, raw, scope) {
+    const summary = { configPath: filePath };
+    summary.testDir = asString(raw.testDir);
+    summary.timeoutMs = asNumber(raw.timeout);
+    summary.workers = raw.workers !== undefined ? String(raw.workers) : undefined;
+    summary.retries = raw.retries !== undefined ? String(raw.retries) : undefined;
+    summary.globalSetup = asString(raw.globalSetup);
+    // expect block
+    if (raw.expect && typeof raw.expect === "object") {
+        summary.expectTimeoutMs = asNumber(raw.expect.timeout);
+    }
+    // use block
+    if (raw.use && typeof raw.use === "object") {
+        const u = raw.use;
+        summary.use = {
+            headless: u.headless !== undefined ? String(u.headless) : undefined,
+            actionTimeoutMs: asNumber(u.actionTimeout),
+            trace: asString(u.trace),
+            video: asString(u.video),
+            screenshot: asString(u.screenshot),
+            ignoreHTTPSErrors: u.ignoreHTTPSErrors === true ? true :
+                u.ignoreHTTPSErrors === false ? false : undefined,
+            baseURL: asString(u.baseURL),
+        };
+        // Parse launchOptions.args if present
+        if (u.launchOptions && typeof u.launchOptions === "object" && Array.isArray(u.launchOptions.args)) {
+            summary.use.launchArgs = u.launchOptions.args.filter((a) => typeof a === "string");
+        }
+    }
+    // reporters
+    if (Array.isArray(raw.reporter)) {
+        summary.reporters = raw.reporter
+            .map((r) => {
+            if (typeof r === "string")
+                return { name: r };
+            if (Array.isArray(r) && typeof r[0] === "string") {
+                return { name: r[0], details: r[1] && typeof r[1] === "object" ? r[1] : undefined };
+            }
+            return undefined;
+        })
+            .filter((x) => x != null);
+    }
+    // projects
+    if (Array.isArray(raw.projects)) {
+        summary.projects = raw.projects
+            .map((p) => {
+            if (!p || typeof p !== "object")
+                return undefined;
+            return {
+                name: asString(p.name) ?? "unknown",
+                grep: asString(p.grep),
+                browserName: asString(p.browserName),
+                isMobile: p.isMobile === true ? true : p.isMobile === false ? false : undefined,
+            };
+        })
+            .filter((x) => x != null);
+    }
+    // env hints — detect from raw source text patterns
+    // (these are derived from text patterns, not AST; we keep them for compatibility)
+    return summary;
+}