Maximus

한국어 | English | 中文 | Español | 日本語

혼란스러운 설정에 질서를.

Maximus는 프로젝트 곳곳에 흩어진 설정 파일을 점검하고, 충돌과 중복을 정리하며 질서 있는 개발환경을 만드는 CLI입니다.

현대 프로젝트는 tsconfig, eslint, prettier, vite, jest, next.config, .env 등 수많은 설정 위에 서 있습니다. Maximus는 무너진 질서를 다시 세웁니다.

Canonical Runtime

Maximus는 이제 Rust runtime을 canonical implementation으로 사용합니다.

• 루트 @jeremyfellaz/maximus npm package는 thin launcher이며, 실제 실행은 플랫폼별 prebuilt Rust binary로 위임합니다.
• publish된 npm wrapper와 GitHub Action도 같은 Rust runtime 경로를 기준으로 동작합니다.
• publish된 npm 진입점은 npx @jeremyfellaz/maximus audit, npx @jeremyfellaz/maximus doctor, npx @jeremyfellaz/maximus fix이며, 설치 후 실행되는 binary 이름은 계속 maximus입니다.
• 저장소의 src/**/*.js는 parity 검증과 reference 비교를 위한 frozen reference로 남아 있습니다. native Rust runtime이 없을 때는 제한된 compatibility fallback으로만 남아 있으며, 새 runtime 기능이나 배포 동작의 기본 구현 표면으로 취급하지 않습니다. maximus.config.json 자동 로딩이나 --only 같은 Rust 전용 기능에는 canonical runtime인 Rust가 필요합니다.
• historical rewrite planning notes는 maintainer workflow 안에 남아 있을 수 있지만, 공개 contributor guidance는 CONTRIBUTING.md, docs/roadmap.md, docs/runtime-transition.md, docs/architecture/checker-authoring.md 같은 tracked repo 문서를 기준으로 따라야 합니다.

전환 경계와 contributor 규칙은 runtime transition 문서에서 확인할 수 있습니다.

주요 기능

• 설정 충돌 탐지
• 중복 config 소스 탐지
• 오래된 TypeScript 옵션 경고
• 잘못 연결된 path alias 검사
• ESLint / Prettier 충돌 분석
• 환경변수 누락 및 mismatch 검사
• 프로젝트 구조 리포트 생성

명령어

npx @jeremyfellaz/maximus audit
npx @jeremyfellaz/maximus doctor
npx @jeremyfellaz/maximus fix

audit

현재 프로젝트의 설정 상태를 검사하고 핵심 리스크를 요약합니다.

doctor

audit보다 더 설명적인 진단 모드입니다. 우선순위와 구조 개선 제안까지 함께 보여줍니다.

fix

안전하게 자동 수정할 수 있는 항목만 적용합니다.

현재 MVP에서 지원하는 자동 수정:

• .env 기반 .env.example 생성
• .env.example에 누락된 키 추가

Audit Signal 정책

Env contract

Maximus는 .env.example 같은 contract 파일을 공유 가능한 인터페이스로 취급합니다. env-example-secret 경고는 이제 key 이름과 value 형태를 함께 봅니다.

• *_TOKEN, *_SECRET, *_PASSWORD, *_SERVICE_KEY, PRIVATE_KEY, *_API_KEY, *_ACCESS_KEY 계열 key에 placeholder가 아닌 값이 들어 있으면 계속 경고합니다.
• sk_live_, sk_test_, ghp_, github_pat_, xoxb-, xoxp-, xoxa-, AWS AKIA..., Google AIza..., private key block처럼 secret 가능성이 높은 value 형태는 key 이름과 관계없이 경고합니다.
• NEXT_PUBLIC_*_CLIENT_ID, URL, repo 이름, label, date, percent, hour처럼 public/config 식별자 성격이 강한 key는 값이 길다는 이유만으로 경고하지 않습니다.
• 빈 값, change-me, example, placeholder, your-*, localhost, 127.0.0.1, true, false, 0, 1은 placeholder로 취급합니다.

로컬에는 없지만 CI나 hosting에서 주입되는 env key는 maximus.config.json 또는 .maximusrc.json에서 명시할 수 있습니다.

{
  "env": {
    "ciInjectedKeys": ["GH_COLLECTOR_TOKEN"],
    "optionalLocalKeys": ["NEXT_PUBLIC_OKTA_DOMAIN"]
  }
}

두 목록은 env-missing-concrete에서 제외할 exact key 목록입니다. Glob나 prefix matching 계약은 없으므로 VERCEL_* 같은 패턴 대신 실제 key 이름을 넣으세요. 잘못된 config field는 조용히 무시하지 않고 parse error로 처리됩니다.

TypeScript config

exclude: ["node_modules"]처럼 TypeScript의 기본 제외 디렉터리를 반복하는 no-op exclude는 기본 audit 출력에서 숨깁니다. 반면 generated/**/*.ts, dist/**/*.d.ts처럼 팀 의도가 담긴 non-default exclude가 실제 included file을 제거하지 못하면 기존처럼 Info finding을 유지합니다. include pattern이 아무 파일도 매칭하지 않는 경우의 warning도 그대로 유지됩니다.

예시 출력

Maximus audit
대상: /workspace/my-app

상태: 조치 필요
발견 항목: 오류 1개, 경고 2개, 정보 1개
적용 가능한 수정: 1개

발견 항목
- [오류] 경로 alias 대상이 존재하지 않음
  파일: packages/web/tsconfig.json
  상세: @ui/*는 src/missing/*를 가리키지만 해석된 경로를 찾을 수 없습니다.
  힌트: editor와 build 해석을 깨기 전에 오래된 alias를 수정하거나 제거하세요.

- [경고] .env.example 계약 파일 누락
  파일: .env
  상세: 실행 env 파일은 있지만 .env.example이 없습니다.
  힌트: `maximus fix`를 실행해 빈 계약 파일을 생성하세요.

GitHub Action

릴리즈 태그 이후에는 같은 npm wrapper 진입점을 GitHub Action에서도 그대로 사용합니다.

- uses: JeremyDev87/maximus@<release-tag>
  with:
    command: audit
    path: .

기본 입력:

• command: audit, doctor, fix
• path: 검사할 프로젝트 경로, 기본값 .
• registry-url: pre-release smoke나 사설 registry 검증이 필요할 때만 쓰는 optional npm registry override
• release-tag: publish된 immutable 릴리즈 태그를 넣으세요. 예: v1.0.0. 안정 major tag가 smoke를 통과한 뒤에는 v1도 사용할 수 있습니다.

유지보수자가 실제 alpha/stable 릴리즈를 준비하거나 같은 태그를 안전하게 재실행할 때는 release operator runbook을 기준으로 진행합니다. Release Drafter는 master에서 draft notes만 갱신하며, 실제 publish와 major tag promotion은 tag-driven release workflow와 action smoke 결과를 기준으로 진행합니다.

로컬 개발

npm test
cargo test --workspace
node ./bin/maximus.js audit ./test/fixtures/clean-project

node ./bin/maximus.js는 repository 안에서 빌드된 Rust CLI(target/debug/maximus, target/release/maximus)를 우선 실행하고, 없으면 설치된 platform-specific Rust binary를 찾습니다. 로컬 바이너리가 아직 없으면 cargo build -p maximus-cli로 준비할 수 있습니다. Rust runtime이 없을 때도 src/**/*.js fallback으로 기본 audit / doctor / fix --dry-run 흐름은 유지되지만, config file 자동 로딩과 --only, --skip, --fail-on 같은 Rust 전용 기능은 native Rust runtime이 필요합니다.

이 fallback 경로는 compatibility 검증과 reference 유지 목적이며, 새 canonical runtime 동작을 추가하는 기본 개발 표면은 아닙니다.

이런 팀에 추천

• 모노레포 / 멀티패키지 운영 팀
• 설정 파일이 많아 관리가 어려운 팀
• 신규 입사자가 세팅에서 자주 막히는 팀

기여하기

새로운 점검기 추가, 자동 수정 안전성 개선, false positive 감소 같은 기여를 환영합니다. 다만 canonical runtime과 배포 표면은 이제 Rust 기준이며, src/**/*.js는 frozen reference로 유지됩니다. 기여 시작 전에는 CONTRIBUTING.md와 runtime transition 문서를 먼저 확인해 주세요.

체커를 추가하거나 기존 checker의 연결 구조를 확인할 때는 checker authoring 아키텍처 문서도 함께 보시면 현재 Rust crate 경계를 빠르게 맞출 수 있습니다.

현재 저장소 기준으로 어디서 시작하면 좋은지 빠르게 잡고 싶다면 contributor roadmap, good first issues, checker ideas를 같이 보시면 좋습니다. 이 문서들은 이미 구현된 표면과 아직 backlog인 주제를 구분해서 안내합니다.

릴리즈 절차, alpha/stable 승격 순서, tag rerun 규칙은 release operator runbook에 따로 정리되어 있습니다.

보안

보안 이슈가 의심된다면 공개 이슈부터 열지 말고 SECURITY.md의 비공개 신고 절차를 따라 주세요.

스폰서

Maximus가 팀의 설정 혼란을 줄이는 데 도움이 된다면 GitHub Sponsors를 통해 유지보수를 후원할 수 있습니다.

라이선스

Maximus는 MIT License로 배포됩니다.