설치 경로와 호스트 연결

PLUGIN_ROOT는 이 진입점이 속한 설치 플러그인 루트다. skills/<id>/SKILL.md에서는 ../..이다. 공용 scripts/assets/tmpa는 플러그인 루트에 한 번만 배치한다. 스킬의 references와 보조 문서는 해당 스킬 파일 기준이다.

${PLUGIN_ROOT}와 ${PLUGIN_DATA}가 셸에 자동 설정됐다고 가정하지 않는다. 로드한 파일의 실제 위치로 루트를 확인하고, 실행할 때 실제 절대경로로 대체하거나 동일 셸 호출에서 변수를 설정한다. PLUGIN_DATA는 호스트가 제공하는 영속 데이터 경로를 우선 사용하고, 없으면 사용자 데이터 디렉터리 아래 이 플러그인 전용 경로를 사용한다. 사용자의 분석 대상 작업 디렉터리는 바꾸지 않는다. bash 예제는 bash에서 실행한다.

사용자에게는 한국어로 답하라. 사용자가 다른 언어로 말을 걸었다면 그 언어를 따른다.

statica 플러그인 개요

무엇을 하는가, 그리고 어디서 멈추는가

작업 디렉터리의 프로젝트에 연결된 STATIC 워크스페이스의 분석 결과를 항상 최신으로 유지한다. 변경된 소스만 골라 다시 분석하고, 결함 건수와 룰별 요약을 보고하고, 요청이 있으면 서버에 반영한다.

결함을 읽고 코드를 고치는 일은 이 플러그인의 몫이 아니다. 그 작업은 별도 플러그인에서 다룬다. 이것은 선택이 아니라 설계상의 경계다.

• 이 플러그인의 출력(결함 건수, topRules, .ci 집계)을 근거로 소스 파일을 편집하지 마라.
• 결함을 파일별로 나열하지 마라. 보고하는 것은 분석의 상태이지 결함의 내용이 아니다.
• 사용자가 결함 수정을 원하면, 그것은 이 플러그인 밖의 일임을 알리고 사용자의 지시를 받아라.

C/C++ 분석 오류 복구

사용자가 툴체인 복구를 요청하거나 C/C++ 분석 오류를 발견하면 같은 플러그인의 statica-toolchain-recovery 스킬을 사용한다. 확보된 분석 오류 폴더로 설정 후보를 복사본에서 검증하고 Wrapper 설정을 반영하는 절차이며, 소스 결함 수정과는 다르다. 오류 폴더가 없으면 경로를 확인하고, 진단·설명만 요청받았으면 그 범위를 넘지 않는다. Stop 훅 자체가 복구 CLI를 자동 실행하는 것은 아니다. 복구 후 재빌드·전체 재분석은 별도 작업으로 인계한다.

두 갈래의 분석기

지원 언어는 다섯이고, 그 아래 분석기는 둘이다. 어느 갈래인지는 워크스페이스가 정한다 (agent.json 의 language, 없으면 C/C++). 결과 JSON 에 language 필드가 있으면 아래 오른쪽 칸이다.

모든 언어의 pre-analyze와 Stop 훅은 서버에 업로드하지 않는다. Java·Kotlin·Python·C#은 analyzer-plugin --no-upload 로 전량 분석 결과를 로컬에 저장한다. 이 옵션을 지원하는 바이너리가 필요하며, 서버 연결도 여전히 필요하다. /statica:upload 호출이나 "서버에 업로드해 줘"라는 명시적 요청은 upload 스킬로 처리한다. 최초 연결의 bootstrap-finish 도 전체 분석·업로드를 수행한다.

두 진입점, 하나의 CLI

스킬은 자기 폴더의 scripts/run.py를 통해 공용 CLI를 부르고, 자동 훅은 공용 CLI(${PLUGIN_ROOT}/scripts/run.py)를 직접 부른다. 전용 실행 코드와 bootstrap 설정·템플릿은 해당 스킬 안에 있으며, 분석 엔진·업로드·서버 API·상태 관리는 공유한다. 아래의 여러 기능을 함께 보여주는 예시는 공용 CLI 경로를 사용한다.

1. Stop 훅 (자동) — hooks/hooks.json 이 매 응답 종료마다 hooks/stop-hook.cmd 를 돌린다. 값싼 게이트를 순서대로 통과해야만 실제 분석까지 간다. 대부분의 응답은 밀리초 안에 빠져나온다.

1. stop_hook_active — 훅으로 인한 재진입이면 즉시 종료
2. 이 프로젝트의 자동 분석 스위치가 꺼져 있으면 종료 (switch off, 프로젝트 단위다. --global 로 끈 경우도 여기서 걸린다)
3. Arachne 서버 설정을 읽지 못하면 조용히 종료 — 설정 문제로 작업을 막지 않는다
4. 이 프로젝트에 연결된 워크스페이스가 없으면 조용히 종료
5. 변경된 분석 대상(TU)이 없으면 조용히 종료
6. 분석한 대상이 있거나, 시간 예산에 걸렸거나, 새로 캡처 실패한 신규 파일이 있을 때만 말한다 — 사용자에게는 systemMessage 로 한 줄, 너에게는 hookSpecificOutput.additionalContext 로 룰별 집계까지. 그 컨텍스트가 오면 그것을 사용자에게 보고하는 것이 네 일이다. 이미 끝난 분석이므로 pre-analyze 나 upload 를 다시 부르지 마라.

훅은 시간 예산에 묶여 있고, 결코 upload 까지 가지 않는다. 어떤 예외도 사용자의 턴을 깨뜨리지 않도록 전부 삼킨다.

훅이 실제로 분석까지 가면 몇 초 걸린다 (실측: TU 하나에 7초). 그동안 응답은 이미 화면에 다 그려져 있고, [STATIC] 요약은 그 뒤에 붙는다. 조용히 빠지는 경우는 0.3~0.5초다.

그래서 네가 소스를 고친 응답의 바로 다음 턴에 /statica:pre-analyze 를 돌리면 대개 "변경된 분석 대상이 없습니다"가 나온다. 훅이 이미 그 TU 를 분석했기 때문이며, 정상이다. 이것을 "분석이 안 됐다"로 읽고 재빌드나 upload 를 제안하지 마라.

2. 슬래시 커맨드 (명시적) — 사용자가 직접 부른다. 훅 예산에 묶이지 않으므로 전체 재빌드가 오래 걸려도 된다.

훅은 연결된 프로젝트에서만 말한다

훅은 사용자의 턴을 절대 막지 않는다. 종료 코드는 언제나 0 이다.

Stop 훅은 디렉터리를 가리지 않고 모든 세션의 모든 응답 끝에 돈다. 그래서 워크스페이스가 없는 프로젝트에서는 아무 말도 하지 않는다.

최초 연결은 사용자가 시작한다. 사용자가 /statica:pre-analyze 를 부르면 code: "NEEDS_BOOTSTRAP" 이 돌아오고, 그때 부트스트랩이 무엇을 하는지 설명하고 승인을 받은 뒤 statica-analyze-bootstrap 스킬의 절차를 따른다. 한 줄 명령이 아니다.

커맨드

각 커맨드의 결과 해석 규칙은 그 커맨드 파일 본문에 있다 — 여기서 되풀이하지 않는다.

자동 분석 ON/OFF 상태는 모든 벤더가 공유하는 ~/.suresoft/data/plugins/static/state.json에 둔다. PLUGIN_DATA나 --state-dir로 경로를 따로 지정하지 않는다. 동일 사용자·프로젝트의 설정은 벤더를 바꿔도 유지된다.

직접 부를 때의 실제 호출:

python "${PLUGIN_ROOT}/scripts/run.py" pre-analyze --project-dir "$(pwd)"
python "${PLUGIN_ROOT}/scripts/run.py" upload --project-dir "$(pwd)"
python "${PLUGIN_ROOT}/scripts/run.py" switch on|off --project-dir "$(pwd)"
python "${PLUGIN_ROOT}/scripts/run.py" status --project-dir "$(pwd)"
python "${PLUGIN_ROOT}/scripts/run.py" doctor

설정 계열은 조회 · 변경이 짝이고, 변경 전에 조회하는 것이 규칙이다. ruleset-show/ruleset-set, scope-show/scope-exclude·scope-include, metric-show/metric-set, report-generator-show/report-generator-set. 보고서 생성은 report 하나가 요청 · 대기 · 다운로드를 다 한다.

설정 계열은 전부 서버 프로젝트의 것이라 팀 전체에 영향이 간다. 그리고 둘은 전체 교체다 — ruleset-set 은 넘긴 id 만 남기고, report-generator-set 도 마찬가지다. 그래서 바꾸기 전에 반드시 현재 값을 읽어야 한다. scope 와 metric 은 증분이라 말한 것만 바뀐다. 자세한 규칙은 각 커맨드 본문에 있고 여기서 되풀이하지 않는다.

부트스트랩 서브커맨드(detect, bootstrap-begin, bootstrap-guard, bootstrap-verify, bootstrap-finish, bootstrap-abort)는 여기 적지 않는다 — 순서와 인자는 statica-analyze-bootstrap 스킬에 있다.

부트스트랩은 승인이 필요하고, 한 번에 끝나지 않는다

프로젝트를 STATIC 워크스페이스에 처음 연결하는 작업이다. 사용자 프로젝트 파일을 수정하고(고치기 전에 원본을 워크스페이스 안에 보관한다), 전체 빌드를 돌리며, 공용 STATIC 서버에 프로젝트를 생성한다. 사용자 승인 없이 실행하지 마라.

C/C++ 절차는 환경 식별 → 컴파일러 확정 → wrapper 생성 → 치환 → 빌드 → 캡처 검증 → 서버 등록으로 이어지는 여러 단계이고, 치환이 GUI 조작인 환경에서는 사용자가 IDE 에서 직접 해 줄 때까지 기다려야 한다. 진행 상태는 워크스페이스에 남으니 중단했다 이어가도 된다.

타 언어는 절차가 훨씬 짧고, 사용자 프로젝트 파일을 전혀 고치지 않는다 (wrapper 도 치환도 없다). 대신 java · kotlin 은 빌드 플러그인을 태워 분석 기술서를 뽑는 단계가 있다.

실제 명령과 순서는 statica-analyze-bootstrap 스킬에 있으니 그대로 따르고, 여기서 추측해 명령을 만들지 마라. 그 스킬은 언어부터 가른 뒤 C/C++ 은 본문으로, 나머지는 other-languages.md 로 보낸다.

사용자가 원하지 않으면 그냥 하지 않는다 — 훅은 연결되지 않은 프로젝트에서 아무 말도 하지 않으므로 따로 기록할 것이 없다. 컴파일러를 찾지 못했으면 추측하지 말고 사용자에게 경로를 물어라.

upload 는 비싸다

워크스페이스 전체를 스코프로 도는 실행이다. 라이선스 슬롯을 점유하고, 워크스페이스를 잠그고, 팀 전체가 보는 revision 을 서버에 만든다. 사용자가 명시적으로 요청했을 때만 실행하고, 먼저 제안하지 마라. 훅은 여기에 절대 닿지 않는다.

Java·Kotlin·Python·C#의 upload도 변경 여부와 무관하게 전량 분석하고 서버에 업로드한다. pre-analyze의 로컬 분석과 구분하며, upload의 결함 집계는 프로젝트 전체다.

CLI 출력 읽기

모든 서브커맨드는 stdout 에 JSON 객체를 정확히 하나 찍는다(실패해도, 내부 오류가 나도 마찬가지다). 사람이 읽을 문장은 message 에 있다. 실패는 ok: false 와 code(NEEDS_BOOTSTRAP, NO_PROJECT_KEY, NO_ACCESS_KEY 등) + hint 로 온다.

주의: defects 는 이번 실행이 분석한 범위의 집계다. 프로젝트 전체 누적 결함 수가 아니다 — C/C++ 은 이번에 돈 TU 들의 것이고, 타 언어는 전량 분석 결과에서 이번에 변경된 파일에 달린 것만 골라낸 것이다. 어느 쪽인지는 defects.scope 가 말한다(changedFiles / allSourceFiles). 매 실행마다 값이 달라지는 것이 정상이며, 이것을 누적 총계인 것처럼 보고하면 사용자를 실제로 오도한다.

전제 조건

• ARACHNE_INSTALL_PATH 환경변수가 Arachne(STATIC) 설치 경로를 가리켜야 한다. 그 아래 bin/, works/, conf/ 를 쓴다. 없으면 NO_INSTALL_PATH.
• 서버 주소와 AccessKey 는 Arachne 자신의 설정(conf/server.setting.json)에 등록되어 있어야 한다. 이 플러그인은 읽기만 한다.
  • 사용자에게 AccessKey 를 묻지 마라. 어떤 파일에도 쓰지 마라. NO_SERVER_SETTING·NO_SERVER_URL·NO_ACCESS_KEY 가 나오면 Arachne 설정에서 등록하도록 안내하는 것이 전부다.
• 환경이 의심스러우면 점검한다: python "${PLUGIN_ROOT}/scripts/run.py" doctor