a11ylens 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+- Initial project structure
+- CLI setup with file discovery pipeline
+- Placeholder scanning + scoring engine

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MADHAN MONISH JAYAKUMAR
+
+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,135 @@
+# A11yLens
+
+A11yLens is a TypeScript Node.js CLI + library that scans Angular component templates (external `.component.html` and inline templates in `.component.ts`) for common accessibility issues. It reports findings in console, JSON, or SARIF formats and computes a project score.
+
+No runtime dependencies are required.
+
+## Install
+
+```bash
+npm install -g a11ylens
+```
+
+Or run via npx:
+
+```bash
+npx a11ylens ./src
+```
+
+## CLI
+
+```bash
+a11ylens [roots...] [options]
+```
+
+Options:
+
+- `--config <path>`: Use a specific config file
+- `--format <console|json|sarif>`: Output format (default: console)
+- `--out <path>`: Write JSON/SARIF output to a file
+- `--min-score <n>`: Exit non-zero when score is below `n`
+- `--verbose`: Print extra diagnostics
+
+Examples:
+
+```bash
+a11ylens ./src
+npx a11ylens ./apps/admin --format json
+npx a11ylens ./src --format sarif --out a11ylens.sarif --min-score 85
+```
+
+## Library API
+
+```ts
+import { runA11yLens } from "a11ylens";
+
+const result = runA11yLens(["./src"], {
+  cwd: process.cwd(),
+  overrides: { minScore: 90 }
+});
+
+console.log(result.score);
+```
+
+## Configuration
+
+A11yLens discovers config files by searching upward from the current working directory.
+
+Supported files:
+
+- `.a11ylensrc.json`
+- `a11ylens.config.json`
+
+Example:
+
+```json
+{
+  "includePatterns": ["*.component.html", "*.component.ts"],
+  "ignoreDirs": ["node_modules", ".git", "dist"],
+  "ignorePatterns": ["**/legacy/**"],
+  "styleFiles": ["./styles.css"],
+  "minScore": 85
+}
+```
+
+Notes:
+
+- `includePatterns` and `ignorePatterns` use a minimal glob-like matcher (`*` prefix/suffix).
+- `ignoreDirs` matches directory names anywhere in the path.
+- `styleFiles` supports simple selectors (`.class`, `tag`, `tag.class`); complex selectors and CSS variables are ignored.
+
+## Output Formats
+
+- Console: human-friendly output with summary and score.
+- JSON: machine-readable full results.
+- SARIF: static analysis format for GitHub code scanning.
+
+## Rules (Built-In)
+
+- Note: rules are minimal and focus on common Angular template issues.
+- `img-alt`: images require `alt`.
+- `clickable-nonsemantic`: clickable div/span needs semantics.
+- `routerlink-text`: router links need an accessible name.
+- `icon-only-control`: icon-only controls need `aria-label`.
+- `color-contrast`: text color must meet WCAG AA ratios when `color` and `background-color` are available (inline or simple class selectors).
+
+## Exit Codes
+
+- `0`: Success
+- `1`: Runtime error
+- `2`: `--min-score` provided and score is below the threshold
+
+## CI Example (SARIF)
+
+```yaml
+name: A11yLens SARIF
+
+on:
+  workflow_dispatch:
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: node dist/cli/index.js ./src --format sarif --out a11ylens.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: a11ylens.sarif
+```
+
+## Development
+
+```bash
+npm run build
+```
+
+## License
+
+MIT

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const runA11yLens_1 = require("../engine/runA11yLens");
+const consoleReporter_1 = require("../reporters/consoleReporter");
+const jsonReporter_1 = require("../reporters/jsonReporter");
+const sarifReporter_1 = require("../reporters/sarifReporter");
+const printUsage = () => {
+    console.log("Usage: a11ylens [roots...] [options]");
+    console.log("");
+    console.log("Options:");
+    console.log("  --config <path>     Path to config file");
+    console.log("  --format <format>   console | json | sarif");
+    console.log("  --out <path>        Output file for json/sarif");
+    console.log("  --min-score <n>     Minimum passing score");
+    console.log("  --verbose           Extra logging");
+    console.log("  --help              Show usage");
+};
+const parseArgs = (argv) => {
+    const roots = [];
+    let configPath;
+    let format = "console";
+    let outPath;
+    let minScore;
+    let verbose = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            printUsage();
+            process.exit(0);
+        }
+        if (arg.startsWith("--config")) {
+            const value = readValue(arg, argv[i + 1]);
+            if (value) {
+                configPath = value;
+                if (!arg.includes("="))
+                    i += 1;
+            }
+            continue;
+        }
+        if (arg.startsWith("--format")) {
+            const value = readValue(arg, argv[i + 1]);
+            if (value === "console" || value === "json" || value === "sarif") {
+                format = value;
+            }
+            if (!arg.includes("="))
+                i += 1;
+            continue;
+        }
+        if (arg.startsWith("--out")) {
+            const value = readValue(arg, argv[i + 1]);
+            if (value) {
+                outPath = value;
+                if (!arg.includes("="))
+                    i += 1;
+            }
+            continue;
+        }
+        if (arg.startsWith("--min-score")) {
+            const value = readValue(arg, argv[i + 1]);
+            if (value) {
+                const parsed = Number(value);
+                if (!Number.isNaN(parsed)) {
+                    minScore = parsed;
+                }
+                if (!arg.includes("="))
+                    i += 1;
+            }
+            continue;
+        }
+        if (arg === "--verbose") {
+            verbose = true;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            continue;
+        }
+        roots.push(arg);
+    }
+    if (roots.length === 0) {
+        roots.push("src");
+    }
+    return { roots, configPath, format, outPath, minScore, verbose };
+};
+const readValue = (arg, nextArg) => {
+    if (arg.includes("=")) {
+        return arg.split("=").slice(1).join("=");
+    }
+    return nextArg;
+};
+const main = () => {
+    const { roots, configPath, format, outPath, minScore, verbose } = parseArgs(process.argv.slice(2));
+    const cwd = process.cwd();
+    const overrides = minScore !== undefined ? { minScore } : undefined;
+    const config = (0, runA11yLens_1.resolveConfig)(cwd, configPath, overrides);
+    if (verbose) {
+        console.log("Config:", config);
+    }
+    try {
+        const result = (0, runA11yLens_1.runA11yLens)(roots, { cwd, configFilePath: configPath, overrides });
+        if (format === "console") {
+            (0, consoleReporter_1.reportConsole)(result, cwd);
+        }
+        else if (format === "json") {
+            const output = (0, jsonReporter_1.reportJson)(result);
+            writeOutput(output, outPath);
+        }
+        else if (format === "sarif") {
+            const output = (0, sarifReporter_1.reportSarif)(result);
+            writeOutput(output, outPath);
+        }
+        if (config.minScore !== undefined && result.score < config.minScore) {
+            process.exit(2);
+        }
+    }
+    catch (error) {
+        console.error("Error running A11yLens:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+};
+const writeOutput = (output, outPath) => {
+    if (outPath) {
+        fs.writeFileSync(outPath, output, "utf8");
+        return;
+    }
+    console.log(output);
+};
+main();

package/dist/config/defaults.d.ts

@@ -0,0 +1,2 @@
+import type { A11yLensConfig } from "../types/config";
+export declare const defaultConfig: A11yLensConfig;

package/dist/config/defaults.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultConfig = void 0;
+exports.defaultConfig = {
+    includePatterns: ["*.component.html", "*.component.ts"],
+    ignoreDirs: ["node_modules", ".git", "dist"],
+    ignorePatterns: [],
+    styleFiles: []
+};

package/dist/config/loader.d.ts

@@ -0,0 +1,7 @@
+import type { A11yLensConfig, A11yLensConfigOverrides } from "../types/config";
+export interface LoadedConfig {
+    config: A11yLensConfig;
+    configPath?: string;
+}
+export declare const loadConfig: (cwd: string, configPath?: string, overrides?: A11yLensConfigOverrides) => LoadedConfig;
+export declare const mergeConfig: (base: A11yLensConfig, fileConfig: A11yLensConfigOverrides, overrides: A11yLensConfigOverrides) => A11yLensConfig;

package/dist/config/loader.js

@@ -0,0 +1,104 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeConfig = exports.loadConfig = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const defaults_1 = require("./defaults");
+const configFileNames = [".a11ylensrc.json", "a11ylens.config.json"];
+const loadConfig = (cwd, configPath, overrides) => {
+    const resolvedCwd = path.resolve(cwd);
+    const discoveredPath = configPath ? path.resolve(configPath) : findConfigUpwards(resolvedCwd);
+    let fileConfig = {};
+    if (discoveredPath) {
+        const content = readConfigFile(discoveredPath);
+        if (content)
+            fileConfig = content;
+    }
+    const merged = (0, exports.mergeConfig)(defaults_1.defaultConfig, fileConfig, overrides !== null && overrides !== void 0 ? overrides : {});
+    return { config: merged, configPath: discoveredPath };
+};
+exports.loadConfig = loadConfig;
+const mergeConfig = (base, fileConfig, overrides) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    return {
+        includePatterns: normalizeStringArray((_b = (_a = overrides.includePatterns) !== null && _a !== void 0 ? _a : fileConfig.includePatterns) !== null && _b !== void 0 ? _b : base.includePatterns),
+        ignoreDirs: normalizeStringArray((_d = (_c = overrides.ignoreDirs) !== null && _c !== void 0 ? _c : fileConfig.ignoreDirs) !== null && _d !== void 0 ? _d : base.ignoreDirs),
+        ignorePatterns: normalizeStringArray((_f = (_e = overrides.ignorePatterns) !== null && _e !== void 0 ? _e : fileConfig.ignorePatterns) !== null && _f !== void 0 ? _f : base.ignorePatterns),
+        styleFiles: normalizeStringArray((_h = (_g = overrides.styleFiles) !== null && _g !== void 0 ? _g : fileConfig.styleFiles) !== null && _h !== void 0 ? _h : base.styleFiles),
+        minScore: (_k = (_j = overrides.minScore) !== null && _j !== void 0 ? _j : fileConfig.minScore) !== null && _k !== void 0 ? _k : base.minScore
+    };
+};
+exports.mergeConfig = mergeConfig;
+const normalizeStringArray = (value) => {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => typeof entry === "string");
+};
+const findConfigUpwards = (startDir) => {
+    let current = startDir;
+    while (true) {
+        for (const name of configFileNames) {
+            const candidate = path.join(current, name);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return undefined;
+};
+const readConfigFile = (configPath) => {
+    try {
+        const raw = fs.readFileSync(configPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return undefined;
+        const record = parsed;
+        const minScore = record.minScore;
+        return {
+            includePatterns: normalizeStringArray(record.includePatterns),
+            ignoreDirs: normalizeStringArray(record.ignoreDirs),
+            ignorePatterns: normalizeStringArray(record.ignorePatterns),
+            styleFiles: normalizeStringArray(record.styleFiles),
+            minScore: typeof minScore === "number" ? minScore : undefined
+        };
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/engine/runA11yLens.d.ts

@@ -0,0 +1,9 @@
+import type { A11yLensConfig, A11yLensConfigOverrides } from "../types/config";
+import type { ProjectScanResult } from "../types/results";
+export interface RunOptions {
+    cwd?: string;
+    configFilePath?: string;
+    overrides?: A11yLensConfigOverrides;
+}
+export declare const runA11yLens: (roots: string[], options?: RunOptions) => ProjectScanResult;
+export declare const resolveConfig: (cwd: string, configFilePath?: string, overrides?: A11yLensConfigOverrides) => A11yLensConfig;

package/dist/engine/runA11yLens.js

@@ -0,0 +1,158 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfig = exports.runA11yLens = void 0;
+const path = __importStar(require("path"));
+const loader_1 = require("../config/loader");
+const fileWalker_1 = require("../scanner/fileWalker");
+const fileAnalyzer_1 = require("../scanner/fileAnalyzer");
+const templateExtractor_1 = require("../scanner/templateExtractor");
+const styleExtractor_1 = require("../scanner/styleExtractor");
+const ast_1 = require("../parser/ast");
+const engine_1 = require("../rules/engine");
+const registry_1 = require("../rules/registry");
+const styleResolver_1 = require("./styleResolver");
+const severityWeights = {
+    error: 5,
+    warn: 2,
+    info: 1
+};
+const runA11yLens = (roots, options = {}) => {
+    var _a, _b, _c, _d, _e;
+    const cwd = (_a = options.cwd) !== null && _a !== void 0 ? _a : process.cwd();
+    const { config, configPath } = (0, loader_1.loadConfig)(cwd, options.configFilePath, options.overrides);
+    const filePaths = (0, fileWalker_1.fileSystemWalker)(roots, (0, fileWalker_1.defaultWalkOptions)(config));
+    const filePathSet = new Set(filePaths.map((filePath) => path.resolve(filePath)));
+    const issueMap = new Map();
+    const styleMap = new Map();
+    const baseDir = configPath ? path.dirname(configPath) : cwd;
+    const globalStyles = [];
+    const addIssues = (filePath, issues) => {
+        var _a;
+        if (issues.length === 0)
+            return;
+        const key = path.resolve(filePath);
+        const existing = (_a = issueMap.get(key)) !== null && _a !== void 0 ? _a : [];
+        existing.push(...issues);
+        issueMap.set(key, existing);
+    };
+    for (const filePath of filePaths) {
+        issueMap.set(path.resolve(filePath), []);
+    }
+    for (const styleFile of (_b = config.styleFiles) !== null && _b !== void 0 ? _b : []) {
+        const resolved = path.resolve(baseDir, styleFile);
+        const content = (0, fileAnalyzer_1.readFileContent)(resolved);
+        if (!content) {
+            addIssues(resolved, [
+                {
+                    ruleId: "style-extraction",
+                    message: `Unable to read style file: ${resolved}`,
+                    filePath: resolved,
+                    severity: "warn"
+                }
+            ]);
+            continue;
+        }
+        globalStyles.push(content);
+    }
+    for (const filePath of filePaths) {
+        if (!filePath.endsWith(".component.ts"))
+            continue;
+        const content = (0, fileAnalyzer_1.readFileContent)(filePath);
+        const extraction = (0, styleExtractor_1.extractStyles)(filePath, content);
+        addIssues(filePath, extraction.issues);
+        const collected = (_c = styleMap.get(filePath)) !== null && _c !== void 0 ? _c : [];
+        for (const style of extraction.styles) {
+            collected.push(style.content);
+        }
+        styleMap.set(filePath, collected);
+    }
+    for (const filePath of filePaths) {
+        const content = (0, fileAnalyzer_1.readFileContent)(filePath);
+        const extraction = (0, templateExtractor_1.extractTemplates)(filePath, content);
+        addIssues(filePath, extraction.issues);
+        for (const template of extraction.templates) {
+            if (template.kind === "external" &&
+                template.filePath !== filePath &&
+                filePathSet.has(path.resolve(template.filePath))) {
+                continue;
+            }
+            const templateKey = path.resolve(template.filePath);
+            if (!issueMap.has(templateKey)) {
+                issueMap.set(templateKey, []);
+            }
+            const styleSheets = [
+                ...globalStyles,
+                ...((_d = styleMap.get(template.originFilePath)) !== null && _d !== void 0 ? _d : [])
+            ];
+            const styleLookup = (0, styleResolver_1.buildStyleLookup)(styleSheets);
+            let ast;
+            try {
+                ast = (0, ast_1.parseTemplate)(template.content);
+            }
+            catch {
+                addIssues(template.filePath, [
+                    {
+                        ruleId: "template-parse",
+                        message: "Failed to parse template content.",
+                        filePath: template.filePath,
+                        severity: "warn"
+                    }
+                ]);
+                continue;
+            }
+            const issues = (0, engine_1.runRules)(registry_1.builtInRules, ast, template.filePath, template.content, styleLookup);
+            addIssues(template.filePath, issues);
+        }
+    }
+    const files = Array.from(issueMap.entries())
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([filePath, issues]) => ({ filePath, issues }));
+    const totals = { error: 0, warn: 0, info: 0 };
+    let score = 100;
+    for (const { issues } of files) {
+        for (const issue of issues) {
+            totals[issue.severity] += 1;
+            score -= (_e = severityWeights[issue.severity]) !== null && _e !== void 0 ? _e : 0;
+        }
+    }
+    score = Math.max(0, Math.min(100, score));
+    return { files, score, totals };
+};
+exports.runA11yLens = runA11yLens;
+const resolveConfig = (cwd, configFilePath, overrides) => {
+    return (0, loader_1.loadConfig)(cwd, configFilePath, overrides).config;
+};
+exports.resolveConfig = resolveConfig;

package/dist/engine/styleResolver.d.ts

@@ -0,0 +1,2 @@
+import type { StyleLookup } from "../types/style";
+export declare const buildStyleLookup: (styleSheets: string[]) => StyleLookup;