qualm-a11y 1.0.0

package/README.md

@@ -0,0 +1,201 @@
+# qualm
+
+[![npm version](https://img.shields.io/npm/v/qualm.svg)](https://www.npmjs.com/package/qualm)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20482307-blue)](https://doi.org/10.5281/zenodo.20482307)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/SomilKSharma/qualm/actions/workflows/qualm-ci.yml/badge.svg)](https://github.com/SomilKSharma/qualm/actions)
+
+**Static AST-level quality analyser for LLM-generated React/TypeScript code.** Operationalises the empirical findings of [Sharma (2026)](https://doi.org/10.5281/zenodo.20482307) as a working static analyser.
+
+> _AI coding tools do not produce an immediate, dramatic accessibility regression—but a slow accumulation effect, particularly in structural HTML semantics, warrants further investigation._
+> — Sharma (2026), Abstract
+
+qualm detects the violation patterns that the Sharma (2026) empirical study found most associated with AI-assisted code: generic containers substituted for semantic HTML, landmark elements rendered as divs, and structural HTML degradation that accumulates silently over months.
+
+---
+
+## Quick Start
+
+```bash
+# Run directly on a directory
+npx qualm-a11y ./src
+
+# Or install globally
+npm install -g qualm-a11y
+qualm-a11y ./src
+```
+
+---
+
+## All CLI Flags
+
+```
+Usage: qualm [options] <paths...>
+
+Arguments:
+  paths                    Files or directories to analyse (.tsx, .ts, .jsx, .js)
+
+Options:
+  -f, --format <format>    Output format: terminal, json, sarif  (default: "terminal")
+  -o, --output <file>      Write output to file instead of stdout
+  --diff-branch <branch>   Compare against git branch to detect regressions
+  --fail-on <level>        Exit 1 if violations of this level exist: error, warning  (default: "error")
+  --research-mode          Output metrics in Sharma (2026) taxonomy format
+  -V, --version            Output version number
+  -h, --help               Display help
+```
+
+### Examples
+
+```bash
+# Analyse a single file
+qualm src/components/Button.tsx
+
+# Analyse entire src directory, JSON output
+qualm src/ --format json --output results.json
+
+# SARIF output for GitHub Code Scanning
+qualm src/ --format sarif --output results.sarif
+
+# Detect regressions vs main branch
+qualm src/ --diff-branch main
+
+# Fail CI on warnings too
+qualm src/ --fail-on warning
+
+# Research mode — Sharma (2026) taxonomy table
+qualm src/ --research-mode
+```
+
+---
+
+## Research Background
+
+This tool directly implements the measurement framework from:
+
+**Sharma, S. (2026).** _Accessibility and Semantic Quality Regressions in AI-Assisted React Development: An Empirical Study._ arXiv preprint.
+
+**Study design**: Longitudinal difference-in-differences across 74 open-source React/TypeScript repositories (41 treated with AI tools, 33 matched controls), 2,374 repo-months.
+
+**Key findings (Table 5 — DiD estimates by violation category):**
+
+| Violation Category   | β (paper) | p-value | Interpretation                                   |
+| -------------------- | --------- | ------- | ------------------------------------------------ |
+| `document_structure` | +0.007    | 0.151   | Largest point estimate — dominant AI-gen failure |
+| `aria_specific`      | +0.002    | 0.561   | Moderate ARIA degradation                        |
+| `semantic_naming`    | −0.003    | 0.824   | AI may slightly improve naming visibility        |
+
+**AST semantic score (Table A1):** Treated repos show treated-pre mean = 0.989, treated-post mean = 0.983, consistent with marginal but accumulating structural degradation (DiD β = +0.005, p = 0.075).
+
+qualm's semantic score is computed using these β values as weights — `document_structure` violations deduct proportionally more than `aria_correctness` violations because the empirical evidence assigns them greater causal weight.
+
+---
+
+## Violation Categories
+
+| Category                | β Weight  | Severity | Description                                                   | Example Violation                              |
+| ----------------------- | --------- | -------- | ------------------------------------------------------------- | ---------------------------------------------- |
+| `document_structure`    | **0.007** | error    | Interactive `<div>`/`<span>` without semantic element or role | `<div onClick={fn}>` → use `<button>`          |
+| `landmark_structure`    | 0.004     | warning  | Generic container with landmark-suggesting class/id           | `<div className="navbar">` → use `<nav>`       |
+| `heading_hierarchy`     | 0.003     | warning  | Skipped heading level                                         | `<h1>` → `<h3>` without `<h2>`                 |
+| `interactive_semantics` | 0.003     | error    | Missing `alt` on image; icon button without label             | `<img src="...">` (no alt)                     |
+| `aria_correctness`      | 0.002     | error    | Invalid boolean ARIA value                                    | `aria-expanded="yes"` → `"true"`               |
+| `form_semantics`        | 0.002     | error    | Form control without associated label                         | `<input id="x">` with no `<label htmlFor="x">` |
+
+---
+
+## `--research-mode` Output
+
+```
+qualm Research Mode — Sharma (2026) Taxonomy
+
+────────────────────────────────────────────────────────────────────────────────
+Category                     | Violations   | β (paper)    | Weighted Score
+────────────────────────────────────────────────────────────────────────────────
+document_structure           | 3            | +0.007       | 0.0500
+landmark_structure           | 2            | +0.004       | 0.0190
+heading_hierarchy            | 0            | +0.003       | 0.0000
+interactive_semantics        | 1            | +0.003       | 0.0143
+aria_correctness             | 0            | +0.002       | 0.0000
+form_semantics               | 1            | +0.002       | 0.0095
+────────────────────────────────────────────────────────────────────────────────
+Composite Regression Score   | 0.0928       | Baseline     | 0.9334
+────────────────────────────────────────────────────────────────────────────────
+Paper baseline (Table A1): treated-pre AST score = 0.989, treated-post = 0.983
+```
+
+---
+
+## GitHub Action
+
+```yaml
+# .github/workflows/qualm.yml
+name: qualm accessibility check
+
+on: [pull_request]
+
+jobs:
+  qualm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # needed for --diff-branch
+
+      - name: Run qualm
+        run: npx qualm src/ --diff-branch main --fail-on error
+```
+
+For SARIF upload to GitHub Code Scanning:
+
+```yaml
+- name: Run qualm (SARIF)
+  run: npx qualm src/ --format sarif --output qualm.sarif || true
+
+- name: Upload SARIF
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: qualm.sarif
+```
+
+---
+
+## Contributing
+
+qualm is explicitly designed for researcher extension. Each rule in `src/rules/` is a self-contained module — adding a new rule requires touching only three files:
+
+1. `src/rules/your-rule.ts` — implement the `Rule` interface
+2. `src/rules/index.ts` — add to `activeRules`
+3. `src/types.ts` — add β coefficient to `PAPER_BETA_COEFFICIENTS`
+
+See [RESEARCH.md](RESEARCH.md) for the full extension guide, β coefficient derivation, and known limitations.
+
+Researchers extending this tool are encouraged to:
+
+- Add rules targeting violation types identified in replication studies
+- Update β coefficients with your own DiD estimates
+- Contribute fixtures from real AI-generated code samples
+
+---
+
+## Citation
+
+If you use qualm in research, please cite the underlying empirical study:
+
+```bibtex
+@article{sharma2026qualm,
+  title     = {Accessibility and Semantic Quality Regressions in AI-Assisted React Development: An Empirical Study},
+  author    = {Sharma, Somil},
+  year      = {2026},
+  month     = {May},
+  journal   = {arXiv preprint},
+  note      = {Independent Researcher, Gurugram, India},
+  url       = {https://doi.org/10.5281/zenodo.20482307}
+}
+```
+
+---
+
+## License
+
+MIT © Somil Sharma

package/RESEARCH.md

@@ -0,0 +1,139 @@
+# RESEARCH.md — qualm Methodology
+
+qualm operationalises the empirical findings of:
+
+> Sharma, S. (2026). *Accessibility and Semantic Quality Regressions in AI-Assisted React Development: An Empirical Study.* arXiv preprint.
+
+---
+
+## Rule-to-Taxonomy Mapping
+
+The paper defines three primary violation categories (Table 2, Table 5). qualm extends these to six rules, all of which are detectable via static AST analysis without a DOM runtime.
+
+| qualm Rule ID         | Paper Category      | Paper β (Table 5) | Detection Method |
+|-----------------------|---------------------|--------------------|------------------|
+| `document-structure`  | `document_structure`| **+0.007** (dominant) | Interactive handler on generic container (`<div>`, `<span>`) without `role` |
+| `landmark-structure`  | `document_structure`| **+0.007** (shared)   | Generic container with landmark-suggesting `className`/`id` |
+| `aria-correctness`    | `aria_specific`     | +0.002             | Invalid string literal on boolean ARIA attribute |
+| `interactive-semantics` | `semantic_naming` | −0.003             | Missing `alt` on `<img>`; icon-only button without `aria-label` |
+| `heading-hierarchy`   | `document_structure`| —                  | Skipped heading level within component |
+| `form-semantics`      | `semantic_naming`   | —                  | Form control without associated `<label>` or `aria-label` |
+
+The paper's `semantic_naming` category has β = −0.003 (Table 5), indicating that AI adoption may slightly *improve* naming violations — possibly because AI tools generate boilerplate `aria-label` attributes. This is reflected in the lower β weight assigned to `interactive_semantics` and `form_semantics` in qualm's semantic score.
+
+---
+
+## Semantic Score Operationalisation
+
+The paper reports AST-based semantic score as a key outcome variable (Section 3.6.2):
+
+- **Treated PRE mean**: 0.989 (SD 0.022) — Table A1
+- **Treated POST mean**: 0.983 (SD 0.027) — Table A1
+- **DiD estimate**: β = +0.005, p = 0.075 (marginal significance)
+- **Tobit-corrected**: β = +0.005, p = 0.092
+
+qualm computes a file-level semantic score in [0, 1] using:
+
+```
+semanticScore = 1.0 - Σ_c [ (β_c / Σβ) × count_c × 0.05 ]
+```
+
+Where:
+- `β_c` = paper β coefficient for category `c` (from Table 5)
+- `count_c` = violation count in category `c`
+- `0.05` = per-violation deduction constant, calibrated against paper baselines
+- Result is clamped to [0.0, 1.0]
+
+This formula weights violations by their empirically estimated contribution to semantic HTML degradation — `document_structure` violations (β = 0.007) deduct proportionally more than `aria_correctness` violations (β = 0.002).
+
+---
+
+## How `--diff-branch` Simulates the DiD Estimator
+
+The paper uses a two-way fixed effects DiD design (Section 3.2):
+
+```
+y_{it} = α_i + γ_t + β·(Treated_i × Post_{it}) + X_{it}δ + ε_{it}
+```
+
+qualm's `--diff-branch` command simulates the "before/after" component of this estimator at the single-file level:
+
+- **Before** = file content at the specified git branch (Pre-treatment)
+- **After** = current working tree content (Post-treatment)
+- **deltaSemanticScore** = after.semanticScore − before.semanticScore (analogous to β)
+- **regressionDetected** = true when deltaSemanticScore < 0 OR new `document_structure`/`landmark_structure` violations appear
+
+This is a per-file approximation — not a panel estimate — but it provides the same directional signal: has this code change *introduced* accessibility debt?
+
+---
+
+## β Coefficients and Semantic Score Weights
+
+From Table 5 of the paper (DiD estimates by violation category):
+
+| Category              | β (paper) | Normalised weight | 
+|-----------------------|-----------|-------------------|
+| `document_structure`  | +0.007    | 0.333             |
+| `landmark_structure`  | +0.004    | 0.190             |
+| `heading_hierarchy`   | +0.003    | 0.143             |
+| `interactive_semantics` | +0.003  | 0.143             |
+| `aria_correctness`    | +0.002    | 0.095             |
+| `form_semantics`      | +0.002    | 0.095             |
+| **Sum**               | **0.021** | **1.000**         |
+
+The three categories without a direct paper estimate (`landmark_structure`, `heading_hierarchy`, `form_semantics`) use conservative values set between the two confirmed paper values (0.002–0.007). Researchers should update these with their own empirical estimates as replication data becomes available.
+
+---
+
+## Extending qualm with New Rules
+
+1. Create `src/rules/your-rule.ts` implementing the `Rule` interface from `src/types.ts`
+2. Export a single named constant: `export const yourRule: Rule = { ... }`
+3. Add it to `activeRules` array in `src/rules/index.ts`
+4. Choose an existing `ViolationCategory` or extend the type in `src/types.ts`
+5. Add corresponding β to `PAPER_BETA_COEFFICIENTS` in `src/types.ts`
+6. Write tests in `tests/rules/your-rule.test.ts`
+7. Add fixture files in `tests/fixtures/`
+
+Rule `create(context)` receives a `RuleContext` with:
+- `context.report({ message, fixSuggestion, location, snippet? })` — emit a violation
+- `context.getSourceCode(node)` — get source text for a node
+- `context.getLoc(node)` — get `{ line, column, lineEnd, columnEnd }` for a node
+
+Listeners are keyed by AST node type. Use `simpleTraverse` visitor keys:
+- `JSXOpeningElement` — fires on `<Tag` opening
+- `JSXElement` — fires on the full `<Tag>...</Tag>` (gives access to children)
+- `JSXAttribute` — fires on each attribute
+- `Program:exit` — fires after full traversal (use for post-collection checks)
+
+---
+
+## Known Limitations
+
+1. **Single-file scope**: Rules operate within one file at a time. Cross-component prop drilling and component-tree accessibility errors (e.g. context-dependent ARIA relationships) are not detectable.
+
+2. **No runtime DOM**: qualm is purely static. Runtime violations that only manifest after rendering (e.g. dynamic `aria-hidden` state, focus management) are outside scope. The paper (Section 3.6.1) notes 60.4% of component-snapshot pairs failed to render — qualm's static approach avoids this limitation entirely.
+
+3. **JavaScript only**: qualm analyses JSX/TSX as written. Components using headless UI libraries (Radix, Ariakit, Chakra UI) that wrap semantic elements may score lower than their actual HTML output warrants — exactly the ambiguity noted in the paper's Appendix D.
+
+4. **Form label matching is file-scoped**: `<label htmlFor="x">` and `<input id="x">` must appear in the same file for the association to be detected. Split across files → false positive.
+
+5. **Single-rater construct validity**: The paper's AST score has Spearman ρ = 0.751 with expert ratings (Appendix D, N=53, single rater). qualm's semantic score inherits this validity ceiling and the single-rater limitation.
+
+6. **β coefficients not replicated yet**: The paper's Table 5 estimates are from 74 repos across 2,374 repo-months. qualm uses these as calibration weights but they should be treated as priors pending independent replication.
+
+---
+
+## Citation
+
+```bibtex
+@article{sharma2026qualm,
+  title     = {Accessibility and Semantic Quality Regressions in AI-Assisted React Development: An Empirical Study},
+  author    = {Sharma, Somil},
+  year      = {2026},
+  month     = {May},
+  journal   = {arXiv preprint},
+  note      = {Independent Researcher, Gurugram, India},
+  url       = {https://doi.org/10.5281/zenodo.20482307}
+}
+```

package/dist/analyser.d.ts

@@ -0,0 +1,3 @@
+import { FileAnalysisResult } from './types';
+export declare function analyseFile(sourceCode: string, filePath: string): FileAnalysisResult;
+//# sourceMappingURL=analyser.d.ts.map

package/dist/analyser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyser.d.ts","sourceRoot":"","sources":["../src/analyser.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,kBAAkB,EAKnB,MAAM,SAAS,CAAC;AAEjB,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAiFpF"}

package/dist/analyser.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyseFile = analyseFile;
+const typescript_estree_1 = require("@typescript-eslint/typescript-estree");
+const parser_1 = require("./parser");
+const index_1 = require("./rules/index");
+const complexity_1 = require("./rules/complexity");
+const types_1 = require("./types");
+function analyseFile(sourceCode, filePath) {
+    const ast = (0, parser_1.parseTSX)(sourceCode, filePath);
+    const violations = [];
+    const createContext = (ruleId, category, severity) => ({
+        report(v) {
+            violations.push({ ...v, ruleId, category, severity });
+        },
+        getSourceCode(node) {
+            if (node.range) {
+                return sourceCode.slice(node.range[0], node.range[1]);
+            }
+            return '';
+        },
+        getLoc(node) {
+            return {
+                line: node.loc.start.line,
+                column: node.loc.start.column,
+                lineEnd: node.loc.end.line,
+                columnEnd: node.loc.end.column
+            };
+        }
+    });
+    // Build a listener map: nodeType -> list of callbacks
+    const listeners = {};
+    for (const rule of index_1.activeRules) {
+        const ctx = createContext(rule.id, rule.category, rule.severity);
+        const ruleListeners = rule.create(ctx);
+        for (const [nodeType, callback] of Object.entries(ruleListeners)) {
+            if (!listeners[nodeType])
+                listeners[nodeType] = [];
+            listeners[nodeType].push(callback);
+        }
+    }
+    // Collect Program:exit callbacks separately — they run after traversal
+    const exitCallbacks = listeners['Program:exit'] ?? [];
+    delete listeners['Program:exit'];
+    (0, typescript_estree_1.simpleTraverse)(ast, {
+        enter(node) {
+            const callbacks = listeners[node.type];
+            if (callbacks) {
+                for (const cb of callbacks)
+                    cb(node);
+            }
+        }
+    });
+    // Fire Program:exit listeners
+    for (const cb of exitCallbacks) {
+        cb(ast);
+    }
+    const metrics = (0, complexity_1.calculateComplexityMetrics)(ast, sourceCode);
+    // Weighted semantic score using paper β coefficients from Table 5 (Sharma 2026).
+    // Each violation in a category deducts (β_i / Σβ) * 0.05 from the score.
+    // The 0.05-per-violation constant is calibrated so that the treated-post mean
+    // of ~0.983 (Table A1) is reachable with a small number of violations.
+    const totalBeta = Object.values(types_1.PAPER_BETA_COEFFICIENTS).reduce((a, b) => a + b, 0);
+    const violationsByCategory = violations.reduce((acc, v) => {
+        acc[v.category] = (acc[v.category] ?? 0) + 1;
+        return acc;
+    }, {});
+    let totalDeduction = 0;
+    for (const [category, count] of Object.entries(violationsByCategory)) {
+        const beta = types_1.PAPER_BETA_COEFFICIENTS[category] ?? 0;
+        const weight = beta / totalBeta;
+        totalDeduction += weight * count * 0.05;
+    }
+    const semanticScore = Math.max(0.0, Math.min(1.0, 1.0 - totalDeduction));
+    return { filePath, violations, metrics, semanticScore };
+}
+//# sourceMappingURL=analyser.js.map

package/dist/analyser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyser.js","sourceRoot":"","sources":["../src/analyser.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const child_process_1 = require("child_process");
+const glob_1 = require("glob");
+const analyser_1 = require("./analyser");
+const diff_1 = require("./diff");
+const terminal_1 = require("./reporters/terminal");
+const json_1 = require("./reporters/json");
+const sarif_1 = require("./reporters/sarif");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const pkg = require('../package.json');
+const program = new commander_1.Command();
+program
+    .name('qualm')
+    .description('Static AST-level quality analyser for LLM-generated React/TypeScript code.\n' +
+    'Based on Sharma (2026) empirical study: https://doi.org/10.5281/zenodo.20482307')
+    .version(pkg.version);
+program
+    .argument('<paths...>', 'Files or directories to analyse (supports .tsx, .ts, .jsx, .js)')
+    .option('-f, --format <format>', 'Output format: terminal, json, sarif', 'terminal')
+    .option('-o, --output <file>', 'Write output to file instead of stdout')
+    .option('--diff-branch <branch>', 'Compare current files against git branch to detect regressions')
+    .option('--fail-on <level>', 'Exit with code 1 if violations of this severity exist: error, warning', 'error')
+    .option('--research-mode', 'Output metrics in Sharma (2026) taxonomy format')
+    .action(async (paths, options) => {
+    try {
+        const files = [];
+        for (const p of paths) {
+            const resolved = (0, path_1.resolve)(p);
+            const ext = (0, path_1.extname)(resolved);
+            if (['.tsx', '.ts', '.jsx', '.js'].includes(ext)) {
+                files.push(resolved);
+            }
+            else {
+                // Directory — glob for React/TS files
+                const found = await (0, glob_1.glob)(`${resolved}/**/*.{tsx,ts,jsx,js}`, {
+                    ignore: ['**/node_modules/**', '**/dist/**', '**/.next/**']
+                });
+                files.push(...found);
+            }
+        }
+        if (files.length === 0) {
+            console.error('qualm: No TypeScript/React files found at the specified paths.');
+            process.exit(1);
+        }
+        const results = [];
+        for (const file of files) {
+            if (!(0, fs_1.existsSync)(file))
+                continue;
+            const source = (0, fs_1.readFileSync)(file, 'utf-8');
+            if (options.diffBranch) {
+                let beforeContent = null;
+                try {
+                    beforeContent = (0, child_process_1.execSync)(`git show ${options.diffBranch}:${file}`, {
+                        encoding: 'utf-8',
+                        stdio: ['pipe', 'pipe', 'pipe']
+                    });
+                }
+                catch {
+                    beforeContent = null;
+                }
+                const diff = (0, diff_1.diffFiles)(beforeContent, source, file);
+                if (options.format === 'json') {
+                    const out = (0, json_1.renderDiffJSON)(diff);
+                    if (options.output) {
+                        (0, fs_1.writeFileSync)(options.output, out, 'utf-8');
+                    }
+                    else {
+                        console.log(out);
+                    }
+                }
+                else {
+                    (0, terminal_1.renderDiffTerminal)(diff);
+                }
+                if (diff.regressionDetected) {
+                    process.exit(1);
+                }
+            }
+            else {
+                results.push((0, analyser_1.analyseFile)(source, file));
+            }
+        }
+        if (!options.diffBranch && results.length > 0) {
+            let output = null;
+            if (options.researchMode) {
+                (0, terminal_1.renderResearchMode)(results);
+            }
+            else if (options.format === 'json') {
+                output = (0, json_1.renderJSON)(results);
+            }
+            else if (options.format === 'sarif') {
+                output = (0, sarif_1.renderSARIF)(results);
+            }
+            else {
+                (0, terminal_1.renderTerminal)(results);
+            }
+            if (output !== null) {
+                if (options.output) {
+                    (0, fs_1.writeFileSync)(options.output, output, 'utf-8');
+                }
+                else {
+                    console.log(output);
+                }
+            }
+        }
+        // Determine exit code
+        if (!options.diffBranch) {
+            const failLevel = options.failOn;
+            const hasFailure = results.some(r => r.violations.some(v => {
+                if (failLevel === 'warning') {
+                    return v.severity === 'error' || v.severity === 'warning';
+                }
+                return v.severity === 'error';
+            }));
+            process.exit(hasFailure ? 1 : 0);
+        }
+    }
+    catch (err) {
+        console.error('qualm error:', err.message);
+        process.exit(2);
+    }
+});
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/diff.d.ts

@@ -0,0 +1,3 @@
+import { DiffResult } from './types';
+export declare function diffFiles(beforeContent: string | null, afterContent: string, filePath: string): DiffResult;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAgC,MAAM,SAAS,CAAC;AAUnE,wBAAgB,SAAS,CACvB,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,UAAU,CA8DZ"}

package/dist/diff.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffFiles = diffFiles;
+const analyser_1 = require("./analyser");
+// Fingerprint uses ruleId + column offset + snippet to identify a violation
+// across refactors. Line numbers are intentionally excluded because they are
+// unstable when code is reformatted; column + snippet provides sufficient
+// structural identity within a file.
+function fingerprintViolation(v) {
+    return `${v.ruleId}::${v.location.column}::${(v.snippet ?? '').slice(0, 60)}`;
+}
+function diffFiles(beforeContent, afterContent, filePath) {
+    const afterResult = (0, analyser_1.analyseFile)(afterContent, filePath);
+    if (!beforeContent) {
+        return {
+            filePath,
+            before: null,
+            after: {
+                violationsCount: afterResult.violations.length,
+                semanticScore: afterResult.semanticScore,
+                metrics: afterResult.metrics
+            },
+            deltaSemanticScore: 0,
+            addedViolations: afterResult.violations,
+            removedViolations: [],
+            regressionDetected: afterResult.violations.length > 0,
+            regressionCategories: [...new Set(afterResult.violations.map(v => v.category))]
+        };
+    }
+    const beforeResult = (0, analyser_1.analyseFile)(beforeContent, filePath);
+    const beforeFingerprints = new Set(beforeResult.violations.map(fingerprintViolation));
+    const afterFingerprints = new Set(afterResult.violations.map(fingerprintViolation));
+    const addedViolations = afterResult.violations.filter(v => !beforeFingerprints.has(fingerprintViolation(v)));
+    const removedViolations = beforeResult.violations.filter(v => !afterFingerprints.has(fingerprintViolation(v)));
+    const deltaSemanticScore = afterResult.semanticScore - beforeResult.semanticScore;
+    const regressionDetected = deltaSemanticScore < 0 ||
+        addedViolations.some(v => v.category === 'document_structure' || v.category === 'landmark_structure');
+    const regressionCategories = [
+        ...new Set(addedViolations.map(v => v.category))
+    ];
+    return {
+        filePath,
+        before: {
+            violationsCount: beforeResult.violations.length,
+            semanticScore: beforeResult.semanticScore,
+            metrics: beforeResult.metrics
+        },
+        after: {
+            violationsCount: afterResult.violations.length,
+            semanticScore: afterResult.semanticScore,
+            metrics: afterResult.metrics
+        },
+        deltaSemanticScore,
+        addedViolations,
+        removedViolations,
+        regressionDetected,
+        regressionCategories
+    };
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"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"}

package/dist/parser.d.ts

@@ -0,0 +1,3 @@
+import { TSESTree } from '@typescript-eslint/utils';
+export declare function parseTSX(sourceCode: string, filePath: string): TSESTree.Program;
+//# sourceMappingURL=parser.d.ts.map