pre-analyze

설치 경로와 호스트 연결

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

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

SKILL_ROOT는 지금 읽은 SKILL.md의 부모 디렉터리다. 이 스킬 전용 scripts/assets는 SKILL_ROOT 아래에 있다. ${SKILL_ROOT}는 설명용 표기이며 자동 설정된 환경변수가 아니다. 스크립트 실행 시 로드한 SKILL.md의 실제 위치로 절대경로를 구성한다. 프로젝트 작업 디렉터리를 스킬 폴더로 바꾸지 않는다.

실행 경로

${SKILL_ROOT}는 이 SKILL.md가 있는 디렉터리의 절대 경로로 바꿔 실행한다. 작업 디렉터리는 분석 대상 프로젝트에 유지한다. scripts/run.py는 이 플러그인의 공용 런타임을 사용하므로 스킬 폴더만 따로 복사하지 않는다.

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

현재 작업 디렉터리의 프로젝트를 STATIC으로 분석한다.

다음을 실행하라:

python "${SKILL_ROOT}/scripts/run.py" pre-analyze --project-dir "$(pwd)"

출력은 JSON 하나다. 다음 규칙으로 해석해 사용자에게 전달하라.

먼저 language 필드를 보라. 없으면 C/C++ 이고 아래 규칙이 전부 그대로 적용된다. java · kotlin · python · csharp 이면 두 가지가 달라진다.

• 이 실행은 서버에 업로드하지 않는다. analyzer-plugin --no-upload 로 전량 분석하고 결과를 로컬에 저장한다(uploaded: false). 서버 연결은 여전히 필요하다. 사용자가 /statica:upload 를 호출하거나 서버 업로드를 명시적으로 요청한 경우에만 upload 스킬을 사용한다. 최초 연결의 bootstrap-finish 는 전체 분석·업로드를 함께 수행한다.
• TU 도 재빌드도 없다. rebuild · rebuildNote · analyzerFailures 는 늘 비어 있으니 언급하지 마라. 대신 uncapturedNewFiles 는 "빌드가 캡처하지 못한 파일"이 아니라 기술서의 소스 루트나 제외 설정에 걸려 분석 범위 밖인 파일이라는 뜻이다.

• ok: true 이고 reason: "NO_CHANGES" → "변경된 분석 대상이 없습니다"라고 전한다. 이유를 지어내지 마라. 방금 소스를 고쳤는데 이 답이 나왔다면 원인은 거의 언제나 직전 응답이 끝날 때 Stop 훅이 이미 그 TU 를 분석해 버린 것이다(훅은 매 응답마다 돌고 7초쯤 걸린다). 그것이 정상이며 할 일은 없다. 확인은 워크스페이스의 .staticdata/.app/tu.analyzed.json 에 적힌 그 TU 의 시각이 소스 mtime 보다 최신인지 보면 된다.

  여기서 재빌드나 /statica:upload 를 제안하지 마라. 편집만으로도 증분 분석 대상이 되므로 재빌드는 필요 없다(재빌드가 필요한 것은 새 파일을 추가했을 때뿐이고, 그때는 rebuildNote 가 따로 나온다). 이미 최신인 결과를 다시 얻겠다고 전체 재분석을 돌리면 라이선스 슬롯을 물고 팀 전체가 보는 revision 을 만든다.

• ok: true 이고 analyzed > 0 → message 를 그대로 전하고, defects.topRules 가 있으면 룰별 건수를 짧게 덧붙인다. 이때 그 건수는 이번 실행에서 분석한 대상(TU)만의 집계이지 프로젝트 전체 누적 결함 수가 아니라는 점을 함께 밝혀라. 결함 목록을 파일별로 나열하지 마라 — 이 플러그인의 역할은 분석까지다.

  defects.scope 가 changedFiles 면 그 수는 이번에 변경된 파일에 달린 위반만 센 것이다. TU 에는 전처리에 딸려 온 시스템 헤더가 수백 개 들어 있고(실측: TU 하나에 161개 중 159개), 그것까지 세면 .c 한 줄 고치고 수천 건이 나온다. allSourceFiles 면 그 TU 의 전부다.

  defects.note 가 있으면 그대로 전하라. C/C++ 에서는 TU 단위 분석이라 여러 번역 단위를 함께 봐야 하는 규칙이 링크 분석에서 달라질 수 있다는 뜻이고, 타 언어에서는 전량 분석 결과의 집계 범위를 설명한다. 결함 파일이 있다는 이유로 업로드됐다고 말하지 마라.

• failures 배열이 비어 있지 않으면 각 항목의 hint 를 함께 알린다. 타 언어에서는 실행이 하나뿐이라 ok: false 와 code: "ANALYZE_FAILED" 가 같이 온다 — 분석이 통째로 실패한 것이니 결함 수를 보고하지 마라. hint 가 "다른 실행이 분석 중" 이면 훅과 커맨드가 겹친 것이니 잠시 뒤 다시 하면 된다.
• rebuildNote 가 비어 있지 않으면 그 문장을 반드시 전하라. buildCommand 가 없어(GUI 로만 빌드하는 환경) 재빌드를 돌리지 못했고, 그래서 사용자가 새로 추가한 소스가 캡처되지 않아 분석에서 빠졌다는 뜻이다. message 에도 들어 있지만 요약하면서 떨어뜨리지 마라 — 말하지 않으면 사용자는 그 파일이 검사된 줄 안다. IDE 에서 한 번 빌드한 뒤 다시 실행하도록 안내하라.
• 부트스트랩 단계(bootstrap-finish)의 결과에 buildCommandWarning 이 있으면 그 문장도 그대로 전하라. 실패가 아니라 경고다 — 자세한 판단 기준은 statica-analyze-bootstrap 스킬 §7 에 있다.
• code: "AGENT_JSON_CORRUPT" → 이 프로젝트의 워크스페이스는 있으나 그 agent.json 이 깨져 읽히지 않는다. 메시지에 적힌 파일을 사용자에게 알리고 고치거나 지우도록 안내하라. 부트스트랩을 새로 시작하지 마라 — 워크스페이스가 둘이 된다.
• ok: true 이고 reason: "BOOTSTRAP_IN_PROGRESS" → 워크스페이스는 있으나 아직 부트스트랩이 끝나지 않았다. statica-analyze-bootstrap 스킬의 남은 단계(치환 · 빌드 · bootstrap-verify · bootstrap-finish)를 이어서 진행하라.

• code: "NEEDS_BOOTSTRAP" → 이 프로젝트는 아직 STATIC에 연결되지 않았다. statica-analyze-bootstrap 스킬을 읽고 그 절차를 따르라. 부트스트랩은 한 줄 명령이 아니라 환경 식별부터 서버 등록까지 이어지는 여러 단계이고, 환경에 따라 사용자가 IDE에서 직접 조작해 줄 때까지 기다려야 한다.

  부트스트랩은 사용자 프로젝트 파일을 고치고, 전체 빌드를 돌리며, 공용 STATIC 서버에 프로젝트를 생성한다. 반드시 사용자 승인을 먼저 받아라. 원하지 않으면 그냥 하지 않는다 — Stop 훅은 연결되지 않은 프로젝트에서 아무 말도 하지 않는다.

  부트스트랩의 마지막 단계인 bootstrap-finish 가 전체 분석과 서버 업로드까지 같이 끝낸다. 그 결과가 fullAnalysis 에 들어 있으니 그것을 사용자에게 전하라. 맨 위의 analyze 를 다시 실행하지 마라 — 방금 돈 전체 빌드 때문에 증분 분석은 언제나 "변경된 대상이 없습니다"로 끝나고, 그러면 분석이 안 된 것처럼 읽힌다.

• code: "NO_ACCESS_KEY" 또는 "NO_SERVER_SETTING" → Arachne 설정에서 서버 주소와 AccessKey를 등록하도록 안내하라. 값을 직접 받아 파일에 쓰려 하지 마라.

컴파일러를 찾지 못했을 때는 추측하지 말고 사용자에게 컴파일러 경로를 물어라.