lipstyk: Instructions file for Codex

AGENTS.md

lipstyk is a static analysis tool that detects machine-generated code patterns. Deterministic rules, no ML. Rust codebase, edition 2024.

Build

cargo build --release                    # CLI only
cargo build --release --features agent   # CLI + MCP/Omegon agent
cargo build --release --features lsp     # CLI + LSP server
cargo test                               # 87 integration tests

CI runs cargo clippy -- -D warnings. Fix all warnings before opening a PR.

Architecture

src/
  rules/          # Rust-specific rules (AST via syn)
  ts/             # TypeScript/JavaScript rules (AST via oxc + text)
  python/         # Python rules (AST via tree-sitter + text)
  golang/         # Go rules (AST via tree-sitter + text)
  html/           # HTML/CSS rules (tag parser)
  java/           # Java rules (text)
  shell/          # Shell rules (text)
  docker/         # Dockerfile rules (text)
  devops/         # Kubernetes + CI/CD YAML rules (content-sniffed)
  markdown/       # Markdown rules (text)
  common/         # Shared analysis utilities
  lint.rs         # Linter core — rule registration and dispatch
  source_rule.rs  # SourceRule trait, Lang enum, SourceContext
  diagnostic.rs   # Diagnostic, Severity, SlopScore
  config.rs       # .lipstyk.toml loading
  diff.rs         # --diff mode (changed-lines filtering)
  report.rs       # Output formatting (JSON, SARIF, Markdown, summary)
  main.rs         # CLI entry point
  agent.rs        # MCP/Omegon entry point (behind `agent` feature)
  lsp.rs          # LSP server (behind `lsp` feature)

Adding a rule

1. Pick the right trait

Rust rules implement Rule (uses syn AST):

pub trait Rule: Send + Sync {
    fn name(&self) -> &'static str;
    fn check(&self, file: &syn::File, ctx: &LintContext) -> Vec<Diagnostic>;
}

LintContext carries filename, source, and exclude_tests.

All other languages implement SourceRule:

pub trait SourceRule: Send + Sync {
    fn name(&self) -> &'static str;
    fn langs(&self) -> &[Lang];
    fn check(&self, ctx: &SourceContext) -> Vec<Diagnostic>;
}