@mximz/argus

Zero-dependency architecture compliance enforcer for Next.js monorepos.

Argus enforces six dimensions of architectural discipline — Security · Speed · SEO · Efficiency · Performance · Code Health — flags violations with actionable fix suggestions, detects systemic patterns, and tracks whether your architecture is improving or degrading over time.

Zero runtime dependencies. Under 3 seconds. At every commit.

Named after Argus Panoptes — the hundred-eyed giant of Greek mythology who never slept.

Why Argus

Most linters enforce language syntax. Argus enforces architectural discipline — the rules that prevent design system drift, SEO regressions, and supply chain vulnerabilities in production Next.js + Supabase applications.

| Tool | What it catches | |---|---| | ESLint / Biome | JavaScript / TypeScript syntax rules | | Stylelint | CSS syntax rules | | Argus | Design token violations · OWASP-mapped security · Core Web Vitals patterns · Dead CSS · Supabase query safety |

They are complementary. Argus covers what generic linters cannot.

Argus is also different from AI-powered code review tools. It is deterministic and rule-based — same input, same output, every time, with no API key and no model required. An AI reviewer catches logic errors and design judgment calls; Argus catches specific architectural violations at commit speed. They solve different problems and work well together.

What Argus answers

| Question | Feature | |---|---| | What is wrong? | 20 rules across 6 dimensions | | What do I do about it? | Suggestions — every violation carries an actionable fix | | Is this isolated or systemic? | Pattern detection — systemic drift · repeated values · hotspot files | | Are we improving or regressing? | History — trend arrows per dimension · --trend dashboard |

What it looks like

Run npx @mximz/argus --summary for a dashboard view:

════════════════════════════════════════════════════════════════════════════
  SUMMARY  ·  159 files scanned  ·  0.13s
────────────────────────────────────────────────────────────────────────────
  🔴  Security        ░░░░░░░░░░░░░░░░░░░░ 23 warnings
  🟡  Speed           ✓ clean
  🟠  SEO             ✓ clean
  🔵  Efficiency      ✓ clean
  🟣  Performance     ░░░░░░░ 7 warnings
  🟢  Code Health     ✓ clean
────────────────────────────────────────────────────────────────────────────
  Warnings do not block commits — but address them before they accumulate.
════════════════════════════════════════════════════════════════════════════

Run npx @mximz/argus for the full report with file-level detail:

🔴  SECURITY  (1 warning shown of 23)
────────────────────────────────────────────────────────────────────────────
  ⚠️  WARN  [S5:unpinned-dependency]
  package.json:17
  "stylelint": "^17.13.0" — ^ ranges allow automatic updates that may
  introduce supply-chain compromises; consider pinning
  · OWASP A03:2025 Software Supply Chain Failures

🟣  PERFORMANCE  (1 error shown of 7)
────────────────────────────────────────────────────────────────────────────
  🚨  ERROR  [PF1:hero-missing-priority]
  sites/your-app/app/(public)/page.tsx:14
  First <Image> in file is missing priority — LCP threshold is 2.0s in 2026

Quick start

# Scan your project — zero config required
npx @mximz/argus

# Install as a dev dependency
npm install --save-dev @mximz/argus

# Generate a config file
npx @mximz/argus init

# Install the pre-commit hook
npx @mximz/argus install-hook

CLI flags

npx @mximz/argus              # full report with suggestions + patterns
npx @mximz/argus --summary    # summary table with trend arrows
npx @mximz/argus --trend      # trend dashboard (no scan — reads history only)
npx @mximz/argus --json       # machine-readable JSON (CI pipelines)
npx @mximz/argus --staged     # staged files only (fast pre-commit mode)
npx @mximz/argus --deep       # include deep checks (CH4: no-any-type)

Rules

Security — OWASP Top 10:2025 mapped

| Rule | Default | OWASP | Description | |---|---|---|---| | S1:no-select-star | error | A01 | select('*') exposes all columns — use explicit column constants | | S2:build-client-in-gsp | error | A02 | createClient() alongside generateStaticParams — use createBuildClient() | | S3:no-uuid-in-urls | error | A01 | UUIDs in public href — use slugs only | | S4:public-prefix-on-secret | error | A02 | NEXT_PUBLIC_ on secret-category env var names | | S5:unpinned-dependency | warn | A03 | ^ ranges allow supply chain injection |

Speed

| Rule | Default | Description | |---|---|---| | SP1:missing-revalidate | error | generateStaticParams page with no revalidate export | | SP2:use-client-with-revalidate | warn | revalidate on a Client Component is silently ignored |

SEO

| Rule | Default | Description | |---|---|---| | SEO1:missing-metadata | error | No generateMetadata() or metadata export | | SEO1:missing-auth-metadata | error | (auth) layout missing robots: { index: false } | | SEO2:missing-h1 / multiple-h1 | error | Every page needs exactly one <h1> | | SEO3:image-no-alt / image-empty-alt | error | <Image> missing or empty alt | | SEO4:native-img-tag | error | <img> instead of Next.js <Image> |

Efficiency

| Rule | Default | Description | |---|---|---| | EF1:console-log | error | console.log/debug/info in production code | | EF2:unresolved-debt | warn | TODO / FIXME / HACK in comments |

Performance — Core Web Vitals 2026

| Rule | Default | Description | |---|---|---| | PF1:hero-missing-priority | error | First <Image> missing priority — LCP threshold is 2.0s in 2026 | | PF2:static-inline-style | error | Quoted literal in style={{}} — use a CSS class | | PF3:heavy-event-handler | warn | Heavy synchronous ops in event handlers — protects INP (200ms) |

Code Health

| Rule | Default | Description | |---|---|---| | CH1:hardcode-colour | error | Hex / rgba / hsl in CSS modules instead of var(--token) | | CH1:hardcode-font-* | error | Hardcoded font-size px / font-family string / font-weight number | | CH2:svg-* | error | SVG fill= / stroke= / fontFamily= with hardcoded values | | CH3:dead-css | warn | CSS class defined in module but never referenced in TSX | | CH4:no-any-type | warn | TypeScript any type (deep mode only) |

Configuration

// argus.config.js
module.exports = {
  sitesDir:    'sites',
  packagesDir: 'packages',

  h1Components:   ['PageHero', 'SiteHero'],
  heroComponents: ['PageHero', 'SiteHero'],

  // Downgrade CH1/PF2 from error to warn on prototype files
  prototypePatterns: ['**/prototype/**'],

  // Core Web Vitals thresholds (update when Google revises)
  cwv: {
    lcp: { good: 2000, poor: 4000 },
    inp: { good: 200,  poor: 500  },
    cls: { good: 0.1,  poor: 0.25 },
  },

  rules: {
    'S5:unpinned-dependency': true,   // promote to error
    'CH3:dead-css':           false,  // disable entirely
  },
}

Suppressing known exceptions

// argus-ignore
const result = await supabase.from('table').select('*')

// argus-ignore-next-line
<img src="/legacy.png" alt="legacy" />

/* argus-ignore */
color: #1a1a2e;

Programmatic API

const argus = require('@mximz/argus')

const result = argus.run({ root: process.cwd(), staged: true, saveHistory: true })

console.log(result.passed)      // boolean
console.log(result.errors)      // blocking violations (each has .suggestion)
console.log(result.warnings)    // non-blocking (each has .suggestion)
console.log(result.patterns)    // systemic · repeated-value · hotspot patterns
console.log(result.history)     // last 30 runs (populated when saveHistory: true)
console.log(result.meta)        // filesScanned, sites, timestamp

// Trend for a specific dimension
const t = argus.getTrend(result.history, 'Code Health')
// { prev: 5, curr: 2, delta: -3, direction: '↓' }

// Print the trend dashboard as a string
console.log(argus.reportTrend(result.history))

GitHub Actions CI

- name: Argus SSSEP audit
  run: npx @mximz/argus --json

See .github/workflows/ for a complete example workflow.

Pre-commit hook

npx @mximz/argus install-hook

Writes .git/hooks/pre-commit. Runs argus --staged on every git commit. Bypass sparingly with git commit --no-verify.

Limitations

• Static pattern analysis, not AST parsing. Argus reads code as text. Multiline JSX edge cases may produce false positives — use // argus-ignore where appropriate.
• CH3 (dead CSS) flags dynamic class names — styles[computedKey], clsx() usage. Suppress with // argus-ignore on the CSS selector.
• git commit --no-verify bypasses the hook. The pre-commit hook is friction, not a hard guarantee. Your CI pipeline is the real enforcement gate.
• Next.js + Supabase oriented. Several rules (S1, S2, SP1) are specific to this stack. Teams on other frameworks should disable irrelevant rules via config.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for the vulnerability disclosure policy.

Credits

Conceived and directed by Rani Wilfred, MXiMz Digital LLP. Lead technology: Claude Code (Anthropic) — claude-sonnet-4-6.

License

MIT — MXiMz Digital LLP