assessify 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# Assessify
+
+This repo contains Assessify, an accessibility fixer for Git hooks and local files.
+
+Quick start (using Bun):
+
+```bash
+# install dependencies with bun
+bun install
+
+# run in dev (TypeScript run via bun)
+bun run src/index.ts
+
+# initialize a project
+bun run src/cli.ts init
+```
+
+## Publish To npm
+
+To publish Assessify on npm:
+
+```bash
+npm login
+npm run build
+npm version patch
+npm publish
+```
+
+If you want to test the package first, run `npm pack` to create a local tarball and inspect the published contents before releasing.
+
+## Use In A Project
+
+A developer can add Assessify to a frontend project with npm:
+
+```bash
+npm install --save-dev assessify
+npx assessify init
+```
+
+During `init`, Assessify asks for the API key and other config details, writes `.assessify.json`, and installs the selected Git hook. For frontend projects the default is `pre-commit`, so the scan runs automatically before every commit.
+
+What happens on commit:
+
+1. Git calls the installed `pre-commit` hook.
+2. The hook runs `npx assessify fix --stage staged`.
+3. Assessify scans the configured file types, checks accessibility issues, and applies fixes when possible.
+4. If changes are made, the hook stages them so the commit includes the updates.
+
+If the developer wants push-time checks too, `assessify init` can install `pre-push` or both hooks instead of only `pre-commit`.
+
+Next steps:
+- Run `assessify init` in a frontend project to collect API key and config details, then install the chosen hook
+- Configure your API key with `--api-key`, `A11Y_CLI_API_KEY`, or the key in `.assessify.json`
+- Implement LLM integration in `src/core/llm.ts`
+- Implement patcher in `src/core/patcher.ts`
+- Flesh out CLI in `bin/cli.js` or TypeScript source

package/bin/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+const { spawnSync } = require('child_process');
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  console.log('assessify: available commands: init, install, fix');
+  process.exit(0);
+}
+
+// Prefer running via bun if available
+const runner = 'bun';
+const res = spawnSync(runner, ['run', 'src/cli.ts', ...args], { stdio: 'inherit' });
+process.exit(res.status ?? 0);

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "assessify",
+  "version": "0.1.0",
+  "description": "Git hook based accessibility fixer with LLM integration",
+  "type": "commonjs",
+  "bin": {
+    "assessify": "bin/cli.js"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "build": "tsc",
+    "test": "echo \"No tests yet\"",
+    "install-hooks": "node ./bin/cli.js install"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.21.0",
+    "@types/yargs": "^17.0.35",
+    "chalk": "^5.0.0",
+    "dotenv": "^16.3.0",
+    "simple-git": "^3.20.0",
+    "yargs": "^18.0.0"
+  },
+  "optionalDependencies": {
+    "openai": "^4.11.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { AccessibilityTool } from './index';
+import { saveConfig, type AppConfig } from './core/config';
+import { installHooks } from './hooks/installer';
+
+const DEFAULT_EXTENSIONS = '.html,.htm,.jsx,.tsx';
+const DEFAULT_MODEL = 'asi1-mini';
+const DEFAULT_BASE_URL = 'https://api.asi1.ai/v1';
+
+type HookType = AppConfig['hook'];
+
+function normalizeHook(value: string, fallback: HookType = 'pre-push'): HookType {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === 'pre-commit' || normalized === 'pre-push' || normalized === 'both') {
+    return normalized;
+  }
+
+  return fallback;
+}
+
+function normalizeLevel(value: string, fallback: AppConfig['logging']['level'] = 'info'): AppConfig['logging']['level'] {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === 'debug' || normalized === 'info' || normalized === 'warn' || normalized === 'error') {
+    return normalized;
+  }
+
+  return fallback;
+}
+
+function normalizeExtensions(value: string): string[] {
+  const parsed = value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => (entry.startsWith('.') ? entry : `.${entry}`));
+
+  return parsed.length > 0 ? parsed : DEFAULT_EXTENSIONS.split(',');
+}
+
+async function ask(rl: readline.Interface, question: string, fallback: string): Promise<string> {
+  const answer = (await rl.question(`${question} [${fallback}]: `)).trim();
+  return answer || fallback;
+}
+
+async function runInit(argv: any) {
+  const interactive = process.stdin.isTTY && process.stdout.isTTY;
+  const rl = interactive ? readline.createInterface({ input, output }) : null;
+
+  try {
+    const apiKey = typeof argv.apiKey === 'string' && argv.apiKey.length > 0
+      ? argv.apiKey
+      : rl
+        ? await ask(rl, 'ASI One API key (leave blank to use env var)', '')
+        : '';
+
+    const model = typeof argv.model === 'string' && argv.model.length > 0
+      ? argv.model
+      : rl
+        ? await ask(rl, 'Model', DEFAULT_MODEL)
+        : DEFAULT_MODEL;
+
+    const baseUrl = typeof argv.baseUrl === 'string' && argv.baseUrl.length > 0
+      ? argv.baseUrl
+      : rl
+        ? await ask(rl, 'Base URL', DEFAULT_BASE_URL)
+        : DEFAULT_BASE_URL;
+
+    const hook = normalizeHook(
+      typeof argv.hook === 'string' && argv.hook.length > 0
+        ? argv.hook
+        : rl
+            ? await ask(rl, 'Git hook to install (pre-commit, pre-push, both)', 'pre-commit')
+            : 'pre-commit',
+          'pre-commit'
+    );
+
+    const logLevel = normalizeLevel(
+      typeof argv.logLevel === 'string' && argv.logLevel.length > 0
+        ? argv.logLevel
+        : rl
+          ? await ask(rl, 'Log level', process.env.NODE_ENV === 'production' ? 'info' : 'info')
+          : 'info',
+      'info'
+    );
+
+    const extensions = normalizeExtensions(
+      typeof argv.extensions === 'string' && argv.extensions.length > 0
+        ? argv.extensions
+        : rl
+          ? await ask(rl, 'File extensions to scan', DEFAULT_EXTENSIONS)
+          : DEFAULT_EXTENSIONS
+    );
+
+    const config: AppConfig = {
+      enabled: true,
+      hook,
+      llm: {
+        provider: 'asi1',
+        model,
+        apiKey: apiKey || undefined,
+        apiKeyEnv: 'ASI_ONE_API_KEY',
+        baseUrl,
+      },
+      accessibility: {},
+      files: { includeExtensions: extensions },
+      loopPrevention: { cacheFile: '.assessify-cache/processed-files.json', maxAttempts: 2 },
+      logging: { level: logLevel },
+      reporting: {},
+    };
+
+    await saveConfig(config);
+    await installHooks({ hook: config.hook });
+
+    console.log('Assessify initialized.');
+    console.log(`Config written to .assessify.json with ${config.hook} hook and ${config.files.includeExtensions.length} scan extensions.`);
+    if (!apiKey) {
+      console.log('No API key saved. Set ASI_ONE_API_KEY or rerun init with a key to enable remote analysis.');
+    }
+  } finally {
+    rl?.close();
+  }
+}
+
+async function main() {
+  yargs(hideBin(process.argv))
+    .command(
+      'init',
+      'Initialize Assessify for a project',
+      (y) => y
+        .option('api-key', { type: 'string', describe: 'Store an API key in the generated config' })
+        .option('model', { type: 'string', describe: 'Model name to use for analysis' })
+        .option('base-url', { type: 'string', describe: 'Base URL for the API provider' })
+        .option('hook', { type: 'string', choices: ['pre-push', 'pre-commit', 'both'] as const, describe: 'Which Git hook(s) to install' })
+        .option('log-level', { type: 'string', choices: ['debug', 'info', 'warn', 'error'] as const, describe: 'Initial log level' })
+        .option('extensions', { type: 'string', describe: 'Comma-separated file extensions to scan' }),
+      async (argv) => {
+        await runInit(argv);
+      }
+    )
+    .command(
+      'install',
+      'Install Git hooks',
+      () => {},
+      async () => {
+        const tool = new AccessibilityTool();
+        await tool.install();
+      }
+    )
+    .command(
+      'fix [files..]',
+      'Fix staged or provided files',
+      (y) => y.positional('files', { type: 'string', array: true }),
+      async (argv) => {
+        if (typeof argv.apiKey === 'string' && argv.apiKey.length > 0) {
+          process.env.A11Y_CLI_API_KEY = argv.apiKey;
+        }
+
+        if (typeof argv.logLevel === 'string' && argv.logLevel.length > 0) {
+          process.env.A11Y_CLI_LOG_LEVEL = argv.logLevel;
+        }
+
+        const tool = new AccessibilityTool();
+        const res = await tool.fix({
+          stage: 'staged',
+          files: argv.files as string[] | undefined,
+        });
+        console.log(JSON.stringify(res, null, 2));
+      }
+    )
+    .option('api-key', {
+      type: 'string',
+      describe: 'Override the API key used by the LLM client',
+    })
+    .option('log-level', {
+      type: 'string',
+      choices: ['debug', 'info', 'warn', 'error'] as const,
+      describe: 'Override log verbosity',
+    })
+    .help().argv;
+}
+
+if (require.main === module) main();

package/src/core/config.ts

@@ -0,0 +1,117 @@
+import { readFile, writeFile } from 'fs/promises';
+import { join } from 'path';
+
+export interface LlmConfig {
+  provider: 'asi1' | 'openai' | 'anthropic';
+  model: string;
+  apiKey?: string;
+  apiKeyEnv?: string;
+  baseUrl?: string;
+}
+
+export interface FileConfig {
+  includeExtensions: string[];
+}
+
+export interface LoggingConfig {
+  level: 'debug' | 'info' | 'warn' | 'error';
+}
+
+export interface LoopPreventionConfig {
+  cacheFile: string;
+  maxAttempts: number;
+}
+
+export interface AppConfig {
+  enabled: boolean;
+  hook: 'pre-commit' | 'pre-push' | 'both';
+  llm: LlmConfig;
+  accessibility: any;
+  files: FileConfig;
+  loopPrevention: LoopPreventionConfig;
+  logging: LoggingConfig;
+  reporting: any;
+}
+
+const DEFAULT_PATH = '.assessify.json';
+const LEGACY_PATH = '.a11y-cli.json';
+
+const DEFAULT_CONFIG: AppConfig = {
+  enabled: true,
+  hook: 'pre-commit',
+  llm: { provider: 'asi1', model: 'asi1-mini', apiKeyEnv: 'ASI_ONE_API_KEY', baseUrl: 'https://api.asi1.ai/v1' },
+  accessibility: {},
+  files: { includeExtensions: ['.html', '.htm', '.jsx', '.tsx'] },
+  loopPrevention: { cacheFile: '.assessify-cache/processed-files.json', maxAttempts: 2 },
+  logging: { level: process.env.NODE_ENV === 'production' ? 'info' : 'debug' },
+  reporting: {},
+};
+
+function normalizeFiles(parsedFiles: any): FileConfig {
+  const includeExtensions = Array.isArray(parsedFiles?.includeExtensions)
+    ? parsedFiles.includeExtensions
+    : Array.isArray(parsedFiles?.include)
+      ? ['.html', '.htm', '.jsx', '.tsx']
+      : DEFAULT_CONFIG.files.includeExtensions;
+
+  return { includeExtensions };
+}
+
+function normalizeLoopPrevention(parsedLoopPrevention: any): LoopPreventionConfig {
+  if (parsedLoopPrevention?.cacheFile) {
+    return {
+      cacheFile: parsedLoopPrevention.cacheFile,
+      maxAttempts: parsedLoopPrevention.maxAttempts ?? DEFAULT_CONFIG.loopPrevention.maxAttempts,
+    };
+  }
+
+  if (parsedLoopPrevention?.storageLocation) {
+    return {
+      cacheFile: `${parsedLoopPrevention.storageLocation.replace(/\/+$/, '')}/processed-files.json`,
+      maxAttempts: parsedLoopPrevention.maxAttempts ?? DEFAULT_CONFIG.loopPrevention.maxAttempts,
+    };
+  }
+
+  return DEFAULT_CONFIG.loopPrevention;
+}
+
+function normalizeLogging(parsed: any): LoggingConfig {
+  const level = (parsed?.level || '').toLowerCase();
+  if (level === 'debug' || level === 'info' || level === 'warn' || level === 'error') {
+    return { level };
+  }
+
+  return DEFAULT_CONFIG.logging;
+}
+
+export async function loadConfig(path = DEFAULT_PATH): Promise<AppConfig> {
+  const candidatePaths = [path, LEGACY_PATH].filter((value, index, list) => list.indexOf(value) === index);
+
+  for (const candidate of candidatePaths) {
+    try {
+      const raw = await readFile(join(process.cwd(), candidate), 'utf-8');
+      const parsed = JSON.parse(raw);
+      return {
+        ...DEFAULT_CONFIG,
+        ...parsed,
+        llm: { ...DEFAULT_CONFIG.llm, ...(parsed.llm ?? {}) },
+        files: normalizeFiles(parsed.files),
+        loopPrevention: normalizeLoopPrevention(parsed.loopPrevention),
+        logging: normalizeLogging(parsed.logging ?? { level: parsed.reporting?.logLevel }),
+        accessibility: { ...DEFAULT_CONFIG.accessibility, ...(parsed.accessibility ?? {}) },
+        reporting: { ...DEFAULT_CONFIG.reporting, ...(parsed.reporting ?? {}) },
+      } as AppConfig;
+    } catch (e) {
+      continue;
+    }
+  }
+
+  return DEFAULT_CONFIG;
+}
+
+export async function saveConfig(config: AppConfig, path = DEFAULT_PATH): Promise<void> {
+  const serialized = `${JSON.stringify(config, null, 2)}\n`;
+  await writeFile(join(process.cwd(), path), serialized, 'utf-8');
+}
+
+export default loadConfig;

package/src/core/git.ts

@@ -0,0 +1,91 @@
+import simpleGit, { SimpleGit } from 'simple-git';
+import { readFile } from 'fs/promises';
+
+export interface FileDiff {
+  filePath: string;
+  additions: string[];
+  deletions: string[];
+  fullDiff: string;
+  beforeContent: string;
+  afterContent: string;
+}
+
+export class GitManager {
+  private git: SimpleGit;
+
+  constructor(cwd?: string) {
+    this.git = simpleGit(cwd);
+  }
+
+  async isInGitRepository(): Promise<boolean> {
+    try {
+      return await this.git.checkIsRepo();
+    } catch (e) {
+      return false;
+    }
+  }
+
+  async getChangedFiles(stage: 'staged' | 'unpushed' | 'recent' = 'staged'): Promise<string[]> {
+    if (stage === 'staged') {
+      const output = await this.git.diff(['--name-only', '--cached']);
+      return output.split('\n').filter(Boolean);
+    }
+
+    if (stage === 'recent') {
+      const output = await this.git.raw(['diff', '--name-only', 'HEAD~1..HEAD']).catch(() => '');
+      return output.split('\n').filter(Boolean);
+    }
+
+    // unpushed: list commits not pushed and get files
+    if (stage === 'unpushed') {
+      const output = await this.git.raw(['diff', '--name-only', '@{u}..HEAD']).catch(() => '');
+      return output.split('\n').filter(Boolean);
+    }
+
+    return [];
+  }
+
+  async getDiffForFile(filePath: string, stage: 'staged' | 'unpushed' | 'recent' = 'staged'): Promise<FileDiff> {
+    const args = stage === 'staged'
+      ? ['--cached', '--', filePath]
+      : stage === 'recent'
+        ? ['HEAD~1..HEAD', '--', filePath]
+        : ['--', filePath];
+    const fullDiff = await this.git.diff(args).catch(() => '');
+
+    const beforeContent = stage === 'recent'
+      ? await this.getFileContent(filePath, 'HEAD~1').catch(() => '')
+      : await this.getFileContent(filePath, 'HEAD~1').catch(() => '');
+    const afterContent = await this.getFileContent(filePath).catch(() => '');
+
+    return {
+      filePath,
+      additions: [],
+      deletions: [],
+      fullDiff,
+      beforeContent,
+      afterContent
+    };
+  }
+
+  async getFileContent(filePath: string, ref?: string): Promise<string> {
+    if (ref) {
+      try {
+        return await this.git.show([`${ref}:${filePath}`]);
+      } catch (e) {
+        return '';
+      }
+    }
+
+    // read from disk
+    try {
+      return await readFile(filePath, 'utf-8');
+    } catch (e) {
+      return '';
+    }
+  }
+
+  async stageFile(filePath: string): Promise<void> {
+    await this.git.add(filePath);
+  }
+}

package/src/core/llm.ts

@@ -0,0 +1,354 @@
+import Anthropic from '@anthropic-ai/sdk';
+import OpenAI from 'openai';
+import dotenv from 'dotenv';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { logger } from '../utils/logger';
+import { loadConfig } from './config';
+
+dotenv.config();
+// Auto-sync frontend environment variables if present
+const frontendEnvLocal = join(process.cwd(), 'frontend', '.env.local');
+const frontendEnv = join(process.cwd(), 'frontend', '.env');
+const parentFrontendEnvLocal = join(process.cwd(), '..', 'frontend', '.env.local');
+if (existsSync(frontendEnvLocal)) {
+  dotenv.config({ path: frontendEnvLocal });
+} else if (existsSync(parentFrontendEnvLocal)) {
+  dotenv.config({ path: parentFrontendEnvLocal });
+} else if (existsSync(frontendEnv)) {
+  dotenv.config({ path: frontendEnv });
+}
+
+let cachedConfig: ReturnType<typeof loadConfig> | null = null;
+
+export interface AccessibilityIssue {
+  line?: number;
+  type: string;
+  severity: 'error' | 'warning' | 'info';
+  description: string;
+  wcagCriteria?: string;
+}
+
+export interface AccessibilityFix {
+  issue: AccessibilityIssue;
+  suggestedFix: string;
+  explanation?: string;
+  confidence?: number;
+}
+
+export class LLMAccessibilityAnalyzer {
+  private systemPrompt = `You are an expert web accessibility auditor. When I send code or diffs, return JSON only with two top-level keys: "issues" (array) and "fixes" (array). Each issue should have type, severity, description, and optional line. Each fix should reference an issue and include suggestedFix as either a unified diff hunk or a replacement payload prefixed with REPLACE_FILE_WITH:. Do not return explanatory text or comments.`;
+
+  private isHttpStatus(error: any, status: number): boolean {
+    return error?.status === status || error?.statusCode === status || error?.response?.status === status;
+  }
+
+  private async getConfig() {
+    if (!cachedConfig) {
+      cachedConfig = loadConfig();
+    }
+
+    return cachedConfig;
+  }
+
+  private async createClient(): Promise<OpenAI> {
+    const config = await this.getConfig();
+    const apiKey = await this.resolveApiKey();
+
+    const provider = config.llm.provider;
+    if (provider === 'anthropic') {
+      return new OpenAI({ apiKey });
+    }
+
+    const baseURL = config.llm.baseUrl || process.env.ASI_ONE_BASE_URL || process.env.OPENAI_BASE_URL || 'https://api.asi1.ai/v1';
+
+    return new OpenAI({ apiKey, baseURL });
+  }
+
+  private async resolveApiKey(): Promise<string | undefined> {
+    const config = await this.getConfig();
+    const providerEnvKey = config.llm.apiKeyEnv;
+    return process.env.GEMINI_API_KEY
+      || process.env.VITE_GEMINI_API_KEY
+      || process.env.A11Y_CLI_API_KEY
+      || config.llm.apiKey
+      || (providerEnvKey ? process.env[providerEnvKey] : undefined)
+      || process.env.ASI_ONE_API_KEY
+      || process.env.OPENAI_API_KEY
+      || process.env.ANTHROPIC_API_KEY;
+  }
+
+  private async callRemoteModel(userContent: string, maxTokens: number): Promise<string | null> {
+    const config = await this.getConfig();
+    const provider = config.llm.provider;
+    const apiKey = await this.resolveApiKey();
+
+    if (!apiKey) {
+      logger.info('No API key configured; using local accessibility heuristics', {
+        provider,
+        hint: 'Set A11Y_CLI_API_KEY or the provider-specific env var in .assessify.json.',
+      });
+      return null;
+    }
+
+    if (provider === 'anthropic') {
+      const client = new Anthropic({ apiKey });
+      try {
+        const resp = await client.messages.create({
+          model: config.llm.model,
+          max_tokens: maxTokens,
+          system: this.systemPrompt,
+          messages: [{ role: 'user', content: userContent }],
+        });
+
+        return resp.content
+          .map((part) => (part.type === 'text' ? part.text : ''))
+          .join('');
+      } catch (error: any) {
+        logger.warn('Anthropic provider unavailable; using local accessibility heuristics', {
+          provider,
+          message: error.message,
+        });
+        return null;
+      }
+    }
+
+    const client = await this.createClient();
+    try {
+      const resp = await client.chat.completions.create({
+        model: config.llm.model,
+        messages: [
+          { role: 'system', content: this.systemPrompt },
+          { role: 'user', content: userContent },
+        ],
+        temperature: 0.0,
+        max_tokens: maxTokens,
+        response_format: { type: 'json_object' },
+      });
+
+      const raw = resp.choices?.[0]?.message?.content ?? resp.choices?.[0]?.message;
+      return typeof raw === 'string' ? raw : JSON.stringify(raw);
+    } catch (error: any) {
+      logger.warn('LLM provider unavailable; using local accessibility heuristics', {
+        provider,
+        message: error.message,
+      });
+      return null;
+    }
+  }
+
+  private parseJsonObject(text: string): any | null {
+    const fencedMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const candidateTexts = [fencedMatch?.[1], text].filter((value): value is string => Boolean(value));
+
+    for (const candidate of candidateTexts) {
+      const jsonStart = candidate.indexOf('{');
+      const jsonEnd = candidate.lastIndexOf('}');
+      if (jsonStart < 0 || jsonEnd <= jsonStart) continue;
+
+      const jsonText = candidate.slice(jsonStart, jsonEnd + 1);
+      try {
+        return JSON.parse(jsonText);
+      } catch {
+        continue;
+      }
+    }
+
+    return null;
+  }
+
+  private inferAltText(sourceTag: string): string {
+    const srcMatch = sourceTag.match(/src=["']([^"']+)["']/i);
+    const source = srcMatch?.[1] ?? '';
+    const filename = source.split('/').pop()?.split('.')[0] ?? '';
+    const cleaned = filename
+      .replace(/[-_]+/g, ' ')
+      .replace(/\b\w/g, (letter) => letter.toUpperCase())
+      .trim();
+
+    if (!cleaned) return 'Descriptive text for the image';
+    if (/logo/i.test(cleaned)) return `${cleaned} logo`;
+    if (/banner/i.test(cleaned)) return `${cleaned} banner`;
+    return cleaned;
+  }
+
+  private addAriaLabel(tag: string, label: string): string {
+    if (/\baria-label\s*=/.test(tag) || /\baria-labelledby\s*=/.test(tag)) {
+      return tag;
+    }
+
+    const normalized = label.trim() || 'Descriptive label';
+    return tag.replace(/\s*\/?>$/, ` aria-label="${normalized}"$&`);
+  }
+
+  private synthesizeIssues(content: string): AccessibilityIssue[] {
+    const issues: AccessibilityIssue[] = [];
+
+    if (/<img\b(?![^>]*\balt\s*=)[^>]*>/i.test(content)) {
+      issues.push({
+        type: 'image-alt-text',
+        severity: 'error',
+        description: 'Image elements should include alternative text.',
+      });
+    }
+
+    const textInputPattern = /<input\b[^>]*type=["'](?:text|password|email|search|tel|url)["'][^>]*>/gi;
+    for (const match of content.matchAll(textInputPattern)) {
+      const tag = match[0];
+      if (/\baria-label\s*=/.test(tag) || /\baria-labelledby\s*=/.test(tag)) {
+        continue;
+      }
+
+      issues.push({
+        type: 'form-label',
+        severity: 'error',
+        description: 'Text-like inputs should have an accessible label.',
+      });
+      break;
+    }
+
+    const controlPattern = /<input\b[^>]*type=["'](?:checkbox|radio)["'][^>]*>/gi;
+    for (const match of content.matchAll(controlPattern)) {
+      const tag = match[0];
+      if (/\baria-label\s*=/.test(tag) || /\baria-labelledby\s*=/.test(tag)) {
+        continue;
+      }
+
+      issues.push({
+        type: 'form-label',
+        severity: 'error',
+        description: 'Checkbox and radio inputs should have an accessible label.',
+      });
+      break;
+    }
+
+    if (/<button\b[^>]*>(\s|&nbsp;)*<\/button>/i.test(content)) {
+      issues.push({
+        type: 'button-label',
+        severity: 'error',
+        description: 'Buttons should have visible or programmatic text.',
+      });
+    }
+
+    return issues;
+  }
+
+  private synthesizeFixes(content: string): AccessibilityFix[] {
+    let updated = content;
+
+    updated = updated.replace(/<img\b[^>]*>/gi, (tag) => {
+      if (/\balt\s*=/.test(tag)) return tag;
+      const altText = this.inferAltText(tag);
+      return tag.replace(/\s*\/?>$/, ` alt="${altText}"$&`);
+    });
+
+    updated = updated.replace(/<input\b[^>]*type=["'](?:text|password|email|search|tel|url)["'][^>]*>/gi, (tag) => {
+      if (/\baria-label\s*=/.test(tag) || /\baria-labelledby\s*=/.test(tag)) {
+        return tag;
+      }
+
+      const placeholderMatch = tag.match(/placeholder=["']([^"']+)["']/i);
+      const label = placeholderMatch?.[1] ?? 'Input';
+      return this.addAriaLabel(tag, label);
+    });
+
+    updated = updated.replace(/<input\b[^>]*type=["'](?:checkbox|radio)["'][^>]*>/gi, (tag) => {
+      if (/\baria-label\s*=/.test(tag) || /\baria-labelledby\s*=/.test(tag)) {
+        return tag;
+      }
+
+      return this.addAriaLabel(tag, 'Option');
+    });
+
+    if (updated !== content) {
+      return [
+        {
+          issue: {
+            type: 'accessibility-fallback',
+            severity: 'warning',
+            description: 'Applied deterministic accessibility replacements because the model response could not be parsed.',
+          },
+          suggestedFix: `REPLACE_FILE_WITH:${updated}`,
+          explanation: 'Fallback replacement generated locally to keep the fixer functional when the model output is malformed.',
+          confidence: 0.5,
+        },
+      ];
+    }
+
+    return [];
+  }
+
+  async analyzeFile(filePath: string, content: string, diff?: string): Promise<AccessibilityIssue[]> {
+    const userContent = `Analyze the following file for accessibility issues (WCAG 2.1 AA). Return JSON issues array.\n\nFilePath: ${filePath}\n\nContent:\n${content}\n\nDiff:\n${diff ?? ''}`;
+
+    try {
+      const text = await this.callRemoteModel(userContent, 800);
+      if (!text) {
+        return this.synthesizeIssues(content);
+      }
+
+      // try to parse JSON out of the response
+      const jsonStart = text.indexOf('{');
+      if (jsonStart >= 0) {
+        const jsonText = text.slice(jsonStart);
+        try {
+          const parsed = JSON.parse(jsonText);
+          const parsedIssues = parsed.issues ?? [];
+          if (parsedIssues.length > 0) {
+            return parsedIssues;
+          }
+        } catch (e: any) {
+          logger.warn('Failed to parse JSON from LLM analyze response', { error: e.message });
+        }
+      }
+
+      return this.synthesizeIssues(content);
+    } catch (error: any) {
+      if (this.isHttpStatus(error, 404)) {
+        logger.warn('LLM provider returned 404; using local accessibility heuristics', {
+          filePath,
+          hint: 'Check llm.provider, llm.baseUrl, and llm.model in .assessify.json or environment variables.',
+        });
+      } else {
+        logger.error('LLM analyzeFile error', { message: error.message });
+      }
+      return this.synthesizeIssues(content);
+    }
+  }
+
+  async generateFixes(issues: AccessibilityIssue[], content: string): Promise<AccessibilityFix[]> {
+    const issuesSummary = JSON.stringify(issues.slice(0, 20));
+    const userContent = `Given the following issues: ${issuesSummary}\n\nFile content:\n${content}\n\nReturn JSON only with a "fixes" array where each fix references an issue index and provides suggestedFix as either a unified diff hunk or a complete replacement prefixed with REPLACE_FILE_WITH:.`;
+
+    try {
+      const text = await this.callRemoteModel(userContent, 1200);
+      if (!text) {
+        return this.synthesizeFixes(content);
+      }
+
+      const parsed = this.parseJsonObject(text);
+      if (parsed) {
+        const parsedFixes = parsed.fixes ?? [];
+        if (parsedFixes.length > 0) {
+          return parsedFixes;
+        }
+      }
+
+      logger.warn('Failed to parse JSON from LLM generateFixes response', {
+        error: 'No valid JSON object found in model response',
+      });
+      return this.synthesizeFixes(content);
+    } catch (error: any) {
+      if (this.isHttpStatus(error, 404)) {
+        logger.warn('LLM provider returned 404 while generating fixes; using local accessibility heuristics', {
+          hint: 'Check llm.provider, llm.baseUrl, and llm.model in .assessify.json or environment variables.',
+        });
+      } else {
+        logger.error('LLM generateFixes error', { message: error.message });
+      }
+      return this.synthesizeFixes(content);
+    }
+  }
+}
+
+export default new LLMAccessibilityAnalyzer();

package/src/core/loopPrevention.ts

@@ -0,0 +1,79 @@
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { dirname, join, resolve } from 'path';
+import { sha256 } from '../utils/checksum';
+import { logger } from '../utils/logger';
+import { loadConfig } from './config';
+
+const DEFAULT_CACHE_FILE = '.assessify-cache/processed-files.json';
+
+interface ProcessedRecord {
+  fileChecksum: string;
+  timestamp: number;
+  attempts: number;
+  lastFixes?: string[];
+}
+
+export class LoopPreventionManager {
+  private path: string;
+  private cache: Record<string, ProcessedRecord> | null = null;
+  private maxAttempts = 2;
+
+  constructor(baseDir = process.cwd()) {
+    this.path = join(baseDir, DEFAULT_CACHE_FILE);
+  }
+
+  private keyFor(filePath: string): string {
+    return resolve(process.cwd(), filePath);
+  }
+
+  private async loadSettings() {
+    const config = await loadConfig();
+    this.path = join(process.cwd(), config.loopPrevention.cacheFile || DEFAULT_CACHE_FILE);
+    this.maxAttempts = config.loopPrevention.maxAttempts || 2;
+  }
+
+  private async ensureCacheLoaded() {
+    if (this.cache) return;
+    try {
+      const raw = await readFile(this.path, 'utf-8');
+      this.cache = JSON.parse(raw);
+    } catch (e) {
+      this.cache = {};
+    }
+  }
+
+  async shouldProcessFile(filePath: string, content: string, maxAttempts?: number): Promise<boolean> {
+    await this.loadSettings();
+    await this.ensureCacheLoaded();
+    const checksum = sha256(content);
+    const rec = this.cache![this.keyFor(filePath)];
+    if (!rec) return true;
+    if (rec.fileChecksum !== checksum) return true;
+    const attemptLimit = maxAttempts ?? this.maxAttempts;
+    if (rec.attempts >= attemptLimit) {
+      logger.warn(`Max attempts reached for ${filePath}`);
+      return false;
+    }
+    // same checksum and below attempts -> allow
+    return true;
+  }
+
+  async recordProcessing(filePath: string, content: string, fixes: string[] = []) {
+    await this.loadSettings();
+    await mkdir(dirname(this.path), { recursive: true }).catch(() => {});
+    await this.ensureCacheLoaded();
+    const checksum = sha256(content);
+    const cacheKey = this.keyFor(filePath);
+    const prev = this.cache![cacheKey];
+    const attempts = (prev?.attempts ?? 0) + 1;
+    this.cache![cacheKey] = {
+      fileChecksum: checksum,
+      timestamp: Date.now(),
+      attempts,
+      lastFixes: fixes,
+    };
+    await writeFile(this.path, JSON.stringify(this.cache, null, 2), 'utf-8');
+  }
+}
+
+export default new LoopPreventionManager();

package/src/core/patcher.ts

@@ -0,0 +1,83 @@
+import { readFile, writeFile, copyFile } from 'fs/promises';
+import { logger } from '../utils/logger';
+
+export interface AccessibilityFix {
+  issueIndex?: number;
+  suggestedFix: string; // full file content replacement or snippet
+}
+
+export class FilePatcher {
+  async createBackup(filePath: string): Promise<string> {
+    const backupPath = `${filePath}.a11y.bak`;
+    try {
+      await copyFile(filePath, backupPath);
+    } catch (e) {
+      // ignore
+    }
+    return backupPath;
+  }
+
+  async applyFix(filePath: string, fix: AccessibilityFix): Promise<boolean> {
+    try {
+      const original = await readFile(filePath, 'utf-8');
+      const backup = await this.createBackup(filePath);
+
+      const suggestedFix = fix.suggestedFix?.trim();
+      if (!suggestedFix) {
+        return false;
+      }
+
+      let newContent = original;
+
+      // If suggestedFix looks like a full-file replacement, apply it directly.
+      if (suggestedFix.startsWith('---')) {
+        // naive patch: replace full content after marker
+        const parts = suggestedFix.split('\n');
+        newContent = parts.slice(1).join('\n');
+      } else if (suggestedFix.includes('REPLACE_FILE_WITH:')) {
+        newContent = suggestedFix.replace('REPLACE_FILE_WITH:', '').trim();
+      } else if (filePath.match(/\.html?$/i)) {
+        const htmlReplacement = this.applyHtmlSuggestion(original, suggestedFix);
+        if (!htmlReplacement) {
+          logger.warn('Skipping unrecognized HTML fix format', { filePath });
+          return false;
+        }
+        newContent = htmlReplacement;
+      } else {
+        logger.warn('Skipping unrecognized fix format', { filePath });
+        return false;
+      }
+
+      await writeFile(filePath, newContent, 'utf-8');
+      return true;
+    } catch (e: any) {
+      logger.error('Failed to apply fix', { filePath, error: e.message });
+      return false;
+    }
+  }
+
+  private applyHtmlSuggestion(original: string, suggestion: string): string | null {
+    const titlePattern = /<title\b[\s\S]*?<\/title>/i;
+    if (suggestion.includes('<title') && titlePattern.test(original)) {
+      return original.replace(titlePattern, suggestion);
+    }
+
+    if (suggestion.includes('<label') && suggestion.includes('<input')) {
+      const inputPattern = /<input\b[^>]*type=["']text["'][^>]*\/?>/i;
+      if (inputPattern.test(original)) {
+        return original.replace(inputPattern, suggestion);
+      }
+    }
+
+    if (suggestion.includes('<img')) {
+      const imgPattern = /<img\b[^>]*>/i;
+      if (imgPattern.test(original)) {
+        return original.replace(imgPattern, suggestion);
+      }
+    }
+
+    return null;
+  }
+}
+
+export default new FilePatcher();

package/src/hooks/installer.ts

@@ -0,0 +1,57 @@
+import { readFile, writeFile, chmod, mkdir } from 'fs/promises';
+import { join } from 'path';
+
+type HookType = 'pre-commit' | 'pre-push' | 'both';
+
+export async function installHooks(options: { hook?: HookType } = {}) {
+  const hookDir = '.git/hooks';
+  await mkdir(hookDir, { recursive: true }).catch(() => {});
+  const hookType = options.hook ?? 'pre-commit';
+
+  const assessifyPreCommitBlock = `\n# --- Accessify A11y Hook Start ---\nnpx assessify fix --stage staged || true\ngit add -A\n# --- Accessify A11y Hook End ---\n`;
+  const assessifyPrePushBlock = `\n# --- Accessify A11y Hook Start ---\nnpx assessify fix --stage recent || true\nif git diff --cached --quiet; then\n  echo "No changes needed"\nelse\n  git add -A\n  git commit --amend --no-edit\nfi\n# --- Accessify A11y Hook End ---\n`;
+
+  if (hookType === 'pre-commit' || hookType === 'both') {
+    const preCommitPath = join(hookDir, 'pre-commit');
+    let existingContent = '';
+    try {
+      existingContent = await readFile(preCommitPath, 'utf-8');
+    } catch (e) {
+      existingContent = '#!/bin/bash\nset -e\n';
+    }
+
+    if (!existingContent.includes('Accessify') && !existingContent.includes('assessify')) {
+      if (existingContent.trim().length > 0 && !existingContent.includes('#!/bin/bash')) {
+        await writeFile(`${preCommitPath}.bak`, existingContent, { encoding: 'utf-8' });
+      }
+      const updatedContent = existingContent.trimEnd() + '\n' + assessifyPreCommitBlock;
+      await writeFile(preCommitPath, updatedContent, { encoding: 'utf-8' });
+      await chmod(preCommitPath, 0o755);
+      console.log('✓ Accessify pre-commit hook appended successfully.');
+    } else {
+      console.log('ℹ Accessify pre-commit hook is already installed.');
+    }
+  }
+
+  if (hookType === 'pre-push' || hookType === 'both') {
+    const prePushPath = join(hookDir, 'pre-push');
+    let existingContent = '';
+    try {
+      existingContent = await readFile(prePushPath, 'utf-8');
+    } catch (e) {
+      existingContent = '#!/bin/bash\nset -e\n';
+    }
+
+    if (!existingContent.includes('Accessify') && !existingContent.includes('assessify')) {
+      if (existingContent.trim().length > 0 && !existingContent.includes('#!/bin/bash')) {
+        await writeFile(`${prePushPath}.bak`, existingContent, { encoding: 'utf-8' });
+      }
+      const updatedContent = existingContent.trimEnd() + '\n' + assessifyPrePushBlock;
+      await writeFile(prePushPath, updatedContent, { encoding: 'utf-8' });
+      await chmod(prePushPath, 0o755);
+      console.log('✓ Accessify pre-push hook appended successfully.');
+    } else {
+      console.log('ℹ Accessify pre-push hook is already installed.');
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,138 @@
+import { installHooks } from './hooks/installer';
+import { GitManager } from './core/git';
+import { loadConfig } from './core/config';
+import llm from './core/llm';
+import patcher from './core/patcher';
+import loopManager from './core/loopPrevention';
+import { logger } from './utils/logger';
+
+function isSupportedFile(filePath: string, includeExtensions: string[]): boolean {
+  const lowerPath = filePath.toLowerCase();
+  return includeExtensions.some((extension) => lowerPath.endsWith(extension.toLowerCase()));
+}
+
+function buildLocalReplacement(content: string): string | null {
+  let updated = content;
+
+  updated = updated.replace(/<img\b[^>]*>/gi, (tag) => {
+    if (/\balt\s*=/.test(tag)) return tag;
+    const srcMatch = tag.match(/src=["']([^"']+)["']/i);
+    const source = srcMatch?.[1] ?? '';
+    const filename = source.split('/').pop()?.split('.')[0] ?? '';
+    const altText = filename
+      ? filename.replace(/[-_]+/g, ' ').replace(/\b\w/g, (letter) => letter.toUpperCase())
+      : 'Descriptive text for the image';
+    return tag.replace(/\s*\/?>$/, ` alt="${altText}"$&`);
+  });
+
+  updated = updated.replace(/<input\b[^>]*type=["'](?:text|password|email|search|tel|url)["'][^>]*>/gi, (tag) => {
+    if (/\baria-label\s*=/.test(tag) || /\baria-labelledby\s*=/.test(tag)) {
+      return tag;
+    }
+
+    const placeholderMatch = tag.match(/placeholder=["']([^"']+)["']/i);
+    const label = placeholderMatch?.[1] ?? 'Input';
+    return tag.replace(/\s*\/?>$/, ` aria-label="${label}"$&`);
+  });
+
+  updated = updated.replace(/<input\b[^>]*type=["'](?:checkbox|radio)["'][^>]*>/gi, (tag) => {
+    if (/\baria-label\s*=/.test(tag) || /\baria-labelledby\s*=/.test(tag)) {
+      return tag;
+    }
+
+    return tag.replace(/\s*\/?>$/, ' aria-label="Option"$&');
+  });
+
+  return updated === content ? null : updated;
+}
+
+export class AccessibilityTool {
+  async install() {
+    const config = await loadConfig();
+    await installHooks({ hook: config.hook });
+  }
+
+  async fix(options: { stage?: 'staged' | 'unpushed' | 'recent'; force?: boolean; files?: string[] } = {}) {
+    const config = await loadConfig();
+    const git = new GitManager();
+    const requestedFiles = options.files && options.files.length > 0
+      ? options.files
+      : await git.getChangedFiles(options.stage ?? 'staged');
+    const files = requestedFiles.filter((file) => isSupportedFile(file, config.files.includeExtensions));
+    const results: any[] = [];
+
+    logger.info('Starting accessibility scan', {
+      requested: requestedFiles.length,
+      supported: files.length,
+      skipped: requestedFiles.length - files.length,
+      extensions: config.files.includeExtensions,
+    });
+
+    for (const file of requestedFiles) {
+      if (!isSupportedFile(file, config.files.includeExtensions)) {
+        logger.debug('Skipping unsupported file type', { file });
+      }
+    }
+
+    for (const file of files) {
+      try {
+        const diff = await git.getDiffForFile(file, options.stage ?? 'staged');
+        const should = await loopManager.shouldProcessFile(file, diff.afterContent);
+        if (!should) {
+          logger.info('Skipping file due to loop prevention', { file });
+          results.push({ file, skipped: true });
+          continue;
+        }
+
+        const issues = await llm.analyzeFile(file, diff.afterContent, diff.fullDiff);
+        if (!issues || issues.length === 0) {
+          logger.info('No accessibility issues found', { file });
+          results.push({ file, issues: 0 });
+          await loopManager.recordProcessing(file, diff.afterContent, []);
+          continue;
+        }
+
+        const fixes = await llm.generateFixes(issues, diff.afterContent);
+        logger.debug('Generated fix candidates', { file, issues: issues.length, fixes: fixes.length });
+        const applied: string[] = [];
+
+        if (fixes.length === 0) {
+          const localReplacement = buildLocalReplacement(diff.afterContent);
+          if (localReplacement) {
+            const ok = await patcher.applyFix(file, { suggestedFix: `REPLACE_FILE_WITH:${localReplacement}` });
+            if (ok) {
+              applied.push('local-fallback');
+              await git.stageFile(file);
+              logger.info('Applied local fallback fix', { file });
+            }
+          }
+        }
+
+        for (const fix of fixes) {
+          const ok = await patcher.applyFix(file, { suggestedFix: fix.suggestedFix ?? fix });
+          if (ok) {
+            applied.push(typeof fix === 'string' ? fix : fix.suggestedFix ?? JSON.stringify(fix));
+            await git.stageFile(file);
+          }
+        }
+
+        await loopManager.recordProcessing(file, diff.afterContent, applied);
+        logger.info('Finished processing file', { file, issues: issues.length, fixesApplied: applied.length });
+        results.push({ file, issues: issues.length, fixesApplied: applied.length });
+      } catch (e: any) {
+        logger.error('Error processing file', { file, message: e.message });
+        results.push({ file, error: e.message });
+      }
+    }
+
+    return { processed: results };
+  }
+}
+
+if (require.main === module) {
+  (async () => {
+    const tool = new AccessibilityTool();
+    const res = await tool.fix({ stage: 'staged' });
+    console.log(JSON.stringify(res, null, 2));
+  })();
+}

package/src/utils/checksum.ts

@@ -0,0 +1,5 @@
+import { createHash } from 'crypto';
+
+export function sha256(content: string): string {
+  return createHash('sha256').update(content, 'utf8').digest('hex');
+}

package/src/utils/logger.ts

@@ -0,0 +1,92 @@
+import { readFileSync } from 'fs';
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const levelRank: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+function currentLevel(): LogLevel {
+  const explicit = (process.env.A11Y_CLI_LOG_LEVEL || process.env.LOG_LEVEL || '').toLowerCase();
+  if (explicit === 'debug' || explicit === 'info' || explicit === 'warn' || explicit === 'error') {
+    return explicit;
+  }
+
+  const configLevel = readConfiguredLevel();
+  if (configLevel) {
+    return configLevel;
+  }
+
+  return process.env.NODE_ENV === 'production' ? 'info' : 'debug';
+}
+
+function readConfiguredLevel(): LogLevel | null {
+  const candidateFiles = ['.assessify.json', '.a11y-cli.json'];
+
+  for (const candidate of candidateFiles) {
+    try {
+      const raw = readFileSync(candidate, 'utf-8');
+      const parsed = JSON.parse(raw);
+      const configured = (parsed.logging?.level || parsed.reporting?.logLevel || '').toLowerCase();
+      if (configured === 'debug' || configured === 'info' || configured === 'warn' || configured === 'error') {
+        return configured;
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return null;
+}
+
+function formatContext(ctx?: any): string {
+  if (ctx === undefined) return '';
+  try {
+    return JSON.stringify(ctx);
+  } catch {
+    return String(ctx);
+  }
+}
+
+function emit(level: LogLevel, message: string, ctx?: any) {
+  if (levelRank[level] < levelRank[currentLevel()]) return;
+
+  const timestamp = new Date().toISOString();
+  const payload = { timestamp, level, message, ...(ctx === undefined ? {} : { context: ctx }) };
+
+  if (process.env.NODE_ENV === 'production') {
+    const line = JSON.stringify(payload);
+    if (level === 'error') {
+      console.error(line);
+    } else if (level === 'warn') {
+      console.warn(line);
+    } else {
+      console.log(line);
+    }
+    return;
+  }
+
+  const contextText = formatContext(ctx);
+  const suffix = contextText ? ` ${contextText}` : '';
+  const line = `${timestamp} [${level}] ${message}${suffix}`;
+
+  if (level === 'error') {
+    console.error(line);
+  } else if (level === 'warn') {
+    console.warn(line);
+  } else if (level === 'info') {
+    console.info(line);
+  } else {
+    console.debug(line);
+  }
+}
+
+export const logger = {
+  debug: (msg: string, ctx?: any) => emit('debug', msg, ctx),
+  info: (msg: string, ctx?: any) => emit('info', msg, ctx),
+  warn: (msg: string, ctx?: any) => emit('warn', msg, ctx),
+  error: (msg: string, ctx?: any) => emit('error', msg, ctx),
+};

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}