Aiglare

aiglare

Lint your AI features for governance guardrails — where can the model do something you can't undo?

[npm] [CI] [license: MIT] [node]

Live site: nugehs.github.io/aiglare-web

[aiglare demo]

Point it at any JS/TS repo and it finds every place an LLM/AI output reaches a user or triggers a side-effect (payment, booking, email, database write) — then flags which of those have no confidence handling, no fallback, no output validation, and no human-in-the-loop.

Most AI incidents aren't model failures. They're governance failures: the model output flowed straight to a user or an irreversible action with nothing in between. This tool makes those paths visible, and lets you block them in CI.

npx @nugehs/aiglare                                        # audit current reponpx @nugehs/aiglare ./src --ci                             # fail the build on a red side-effectful surfacenpx @nugehs/aiglare --compliance all --format html         # HTML evidence report for auditorsnpx @nugehs/aiglare --compliance soc2,eu-ai-act --format lint --ci  # compliance linter in CI

What it reports

Each AI surface is classified by sink — where the output goes:

• user-facing — returned from a route/controller, or rendered in a component
• side-effectful — feeds a payment, booking, email, db/file write, or shell
• internal — logged or cached only

…and scored on five guardrail dimensions: confidence handling, fallback/uncertain path, output validation, human-in-the-loop (for side-effects), and error isolation.

The CI gate (--ci) fails only on red + side-effectful surfaces — the "AI auto-triggers an irreversible action with no confirmation" case — so it's safe to adopt without drowning a team in warnings.

Compliance reports

Pass --compliance to map every finding to specific regulatory controls, then pick your output format:

# HTML evidence report — branded, collapsible per-framework sections, guardrail matrixaiglare --compliance all --format html > report.html
# ESLint-style linter — pipe into CI, editors, or reviewersaiglare --compliance soc2,eu-ai-act --format lint
# Markdown evidence doc — ready to hand to an auditoraiglare --compliance all --format markdown > AUDIT.md
# Guardrail linter (no framework) — rule IDs like guardrail/human-in-loopaiglare --format lint

Supported frameworks:

Use all to include every framework. Each surface in --json output gains a violations[] array with the framework, control ID, description, and error/warning level.

Multi-repo: pass multiple paths for a single combined report:

aiglare ./api ./web --compliance all --format html > report.html

Provider-agnostic

Detection is driven by a provider registry covering OpenAI, Anthropic, Google, Cohere, Mistral, Replicate, the Vercel AI SDK, LangChain/LangGraph, Ollama, AWS Bedrock, Cloudflare Workers AI, and Hugging Face — plus raw fetch/axios calls to known inference hosts. Adding a provider is a one-line PR.

Optional: repoctx acceleration

If a repoctx index (.dev-context/index.json) is present, the tool uses it automatically to prioritize likely AI files and sharpen sink classification via repoctx's kind/domain data (e.g. a file repoctx marks as a controller route is correctly treated as user-facing even when the native scanner can't see the call graph). Without it, a built-in TypeScript-compiler scanner does the same job at lower fidelity. Same tool, two fidelity levels — standalone for everyone, richer for repoctx users.

MCP server

aiglare ships a built-in Model Context Protocol server so agents can run audits directly:

aiglare mcp        # stdio JSON-RPC server (no SDK dependency)

It exposes three tools:

Register it with an MCP host (Claude Desktop, Cursor, VS Code, …):

{  "mcpServers": {    "aiglare": {      "command": "npx",      "args": ["-y", "@nugehs/aiglare", "mcp"]    }  }}

aiglare vs alternatives

These are complementary: aiglare tells you where a guardrail is missing; runtime validators are how you add one.

Run a 1-week pilot

Want to evaluate aiglare on a real codebase before adopting the CI gate? PILOT.md is a step-by-step one-week runbook: install, first audit on a backend and a frontend repo, reading the report, tuning --severity/--sinks, and deciding whether to turn on --ci.

Honest limitations

This is static, advisory analysis — a linter, not a verifier. It produces false positives (a guardrail two call-hops away can be missed) and false negatives (a confidence variable that doesn't actually gate anything reads as present). Treat output as surfaces to review, not violations. The single-file native scanner cannot follow the call graph; the repoctx adapter exists precisely to close that gap.

Options

aiglare [path...] [options]  --compliance <fw>   Map findings to compliance controls.                      Comma-separated: soc2, eu-ai-act, nist, owasp, or "all"  --format <fmt>      Output format: terminal (default), json, lint, markdown, html  --json              JSON output (alias for --format json)  --ci                Exit non-zero on a red side-effectful surface  --severity <lvl>    Show only red, or amber-and-worse  --sinks <list>      Filter: user-facing,side-effectful,internal
aiglare mcp           Start the MCP server (stdio)

The MCP tool ai_surface_audit accepts an optional compliance array — each surface in the response includes a violations[] array when set.

License

MIT

Part of the toolchain

aiglare is one of four tools that form a deterministic trust layer for AI-assisted development. Each answers a question people keep handing to an LLM — with static analysis instead.

• repoctx — context: what does this change actually touch?
• tieline — contracts: did the front end and back end quietly stop agreeing?
• bouncer — compliance: could you defend this to Ofcom?
• aiglare (this tool) — governance: where can the model do something you can't undo?

More at segunolumbe.com. static analysis, never the model.