JSON 계약

공유되는 오퍼레이션

아래의 모든 오퍼레이션은 최소 두 갈래로 닿는다 — zzop CLI 서브커맨드와 인프로세스 호출 — 그리고 그 둘은 하나의 구현을 공유한다(crates/facade, 그리고 CLI 와 MCP 도구가 받는 설정 자동탐색·결과 정형을 맡는 crates/summary). 어느 표면을 쓰든 같은 요청을 넣으면 같은 JSON 이 나오고, version 을 빼면 전부 JSON 문자열 입력 / JSON 문자열 출력이다. zzop-mcp MCP 도구가 세 번째 갈래이고, 모든 오퍼레이션에 하나씩 있는 것은 아니다 — 아래 각 행은 자기 오퍼레이션이 닿는 표면을 스스로 밝히고, MCP 도구가 없는 행은 없다는 사실과 그 이유를 함께 적는다. 메워야 할 구멍이 아니라 의도된 비대칭이다: CLI 전용 레인마다 짝이 없는 이유가 docs/contracts/surface-parity.json(_cliOnlyLanes)에 레인 단위로 기록돼 있고, 메타 테스트(crates/engine/tests/rule_contracts/surface_parity.rs)가 그것을 읽어 MCP 응답을 그 등기부가 말하는 것에 붙들어 둔다.

analyze_json

(config_json: &str) -> Result<String, String>

AnalyzeRequest → AnalyzeOutputView. 트리 하나를 분석한다. zzop analyze <path> / analyze --config <path> CLI 서브커맨드와 analyze_repo MCP 도구(zzop-summary 경유)를 떠받친다.

analyze_trees_json

(config_json: &str) -> Result<String, String>

AnalyzeTreesRequest({ trees: AnalyzeRequest[] }) → MultiAnalyzeOutputView. 여러 트리를 분석하고 레이어를 가로질러 잇는다. zzop cross / cross_repo MCP 도구를 떠받친다.

analyze_envelope_json

(envelope_json: &str, config_json: &str) -> Result<String, String>

NormalizedEnvelope + EnvelopeAnalyzeRequest → AnalyzeOutputView. 외부 파서 어댑터가 만든 Normalized AST 엔벨로프를 분석한다. zzop analyze-envelope / analyze_envelope MCP 도구를 떠받친다.

query_io_json

(analysis_json: &str, query_json: &str) -> Result<String, String>

analyze_trees_json 출력 + { pattern: string } → 엔드포인트/io 키에 대한 확정 답. 이미 만들어진 다중 트리 분석 위의 순수 후처리이고 재분석은 없다: pattern 은 모든 크로스레이어 io 키(HTTP 라우트, env 키, DB 테이블, 토픽, 그리고 풀리지 않은 consume 을 위한 raw)에 대소문자 무시 부분 문자열로 맞춰 보고, 결과는 봉인된 verdict 어휘(linked | provided-only | consumed-unprovided | external | unresolved-only | ambiguous | mixed | not-found)를 그 뒤의 매치·개수·관련 발견과 함께 싣는다. 질의가 망가졌을 때와 단일 트리 analyze_json 출력이 들어왔을 때는 에러를 낸다 — 안내가 붙은 에러다. verdict 는 조인 사실이기 때문이다(트리가 하나여도 조인하는 analyze_trees_json 을 돌려라). zzop endpoint / check_endpoint MCP 도구를 떠받친다.

query_file_json

(analysis_json: &str, query_json: &str) -> Result<String, String>

analyze_trees_json 출력 + { path: string, sourceId?: string } → zzop 이 파일 하나에 대해 아는 전부. query_io_json 과 같은 순수 후처리 계약이고 — 재분석은 없다 — 대상이 io 키 대신 파일 경로다: 그 파일이 속한 트리, 심볼, io 사실, 양방향 의존 간선, 그리고 그 파일에 앵커된 모든 발견. 상한이 없다, 의도적으로: 파일 하나는 유계이므로 버리는 것이 없고, 따라서 밝힐 절단도 없다.

이쪽의 봉인된 verdict 어휘(analyzed | lexical-only | degraded | not-found)가 답하는 것은 그 파일이 분석됐는가이지 건강한가가 아니다 — 빈 발견 목록은 첫 번째에서는 "깨끗하다"이고 다음 둘에서는 "구조 분석이 애초에 돌지 않았다"이다. query_io_json 과 마찬가지로 응답 자신의 verdictMeaning 필드가 돌려준 토큰의 정의를 싣고 다니므로, 어떤 문서도 그 정의의 두 번째 주인이 되지 않는다. sourceId 가 없으면 모든 트리를 뒤지고, 응답은 매치가 나온 트리를 이름 대며 나머지는 otherTrees 에 늘어놓는다 — 말없이 하나를 고르지 않는다. not-found 응답에는 워크된 경로 중 가장 가까운 것들이 suggestions 로 실린다. path 가 없는 질의와, 보고할 트리 정체성이 없는 단일 트리 analyze_json 출력에는 에러를 낸다. zzop file / check_file MCP 도구를 떠받친다.

query_coverage_json

(analysis_json: &str) -> Result<String, String>

analyze_trees_json 출력 → 총량 가시성 뷰: “zzop 이 이 트리를 실제로 얼마나 보고 있나?” 트리마다 디스패치별 확장자 표(구조 / lexical-only / degraded, 그리고 inDepGraph), blindSpots — 컴파일된 각 룰의 시선을 그 트리의 구조 확장자 구성과 교차시킨 능력 축 — 그 트리 자신의 엔진 경고를 그대로 전달한 것(프레임워크 침묵 자기보고가 여기 실린다), 커버리지 센서스, ioChannels(extracted — 룰이 읽는 io 종류마다 한 행씩, 0 이어도 반드시 실린다: 종류를 구분하지 않는 joinContributionZero 처럼 채워진 채널이 빈 채널을 대신 보증하지 못하게 한다. zeroExtraction — 이 빌드가 인식기를 가진 (채널, 확장자) 중 추출이 0 으로 돌아온 것을 이름 붙인 능력×실측 교차: 이 실행이 구조적으로 읽은 것 중 주요 비중인 확장자만 실리고(그 아래는 목록에서 빠지는 것이지 통과한 것이 아니다), 프레임워크 이름을 알아보는 게 아니라 트리 자체를 모집단으로 삼는 커버리지 사실이다), 그리고 joinVisibility 를 개수로(provides, consumesKeyed, consumesUnresolved) 의미와 함께 낸다 — 파생 비율은 내지 않는다. 몫은 1 중 1 에서나 440 중 400 에서나 똑같이 읽히기 때문이다. 단일 점수는 일부러 없다: zzop 이 당신 트리에서 한 번도 재지 못한 축은, 그 사실 없이 인용될 숫자에 접혀 들어가는 대신 재지 못했다는 필드에 실려 간다. MCP 도구 짝이 없는 zzop coverage 를 떠받친다.

validate_envelope_only_json

(envelope_json: &str) -> String

엔벨로프 JSON → { valid: boolean, issues: string[], hints: string[] } — hints 는 언제나 있고, 구조적으로 유효한 엔벨로프가 그럼에도 아무것도 조인하지 못할 이유를 듣는 자리다. analyze_envelope_json 이 자기 엔벨로프에 적용하는 구조·의미 검사를 똑같이 돌리고 거기서 멈춘다 — 설정도, 팩 로딩도, 엔진 실행도 없다 — 어댑터 작성자를 위한 빠르고 오프라인인 "내 엔벨로프가 잘 생겼나" 피드백이다. 실패하지 않는다: 유효하지 않은 엔벨로프도 평범한 { valid: false, issues: [...] } 결과로 돌아온다. zzop validate-envelope 와 validate_envelope MCP 도구를 떠받친다.

validate_rule_pack_json

(pack_json: &str) -> String

룰팩 JSON → { valid: boolean, issues: string[] }. 엔진의 팩 로더가 적재 시점에 적용하는 구조 판정을 그대로 돌리고(망가진 JSON, 빠진 필드, 틀린 타입, 너무 새로운 schema_version), 여기에 적재는 되지만 말없이 영영 발화하지 못할 룰까지 잡는다 — 컴파일되지 않는 matcher 정규식, line_pattern 도 any 도 선언하지 않은 line-scan, trigger 가 어떤 patterns 항목도 선언하지 않은 라벨을 가리키는 method-scan. 모양만 보고 룰 품질의 의미는 절대 보지 않는다. 팩 작성자를 위한 배포 전 피드백이다. 실패하지 않는다: 유효하지 않은 팩도 평범한 { valid: false, issues: [...] } 결과로 돌아온다. zzop validate-rule-pack 과 validate_rule_pack MCP 도구를 떠받친다.

version

() -> String

핑거프린트 없는 맨 릴리스 번호 — 그냥 zzop version / zzop-mcp version 이 찍는 것. version_string 과 일부러 갈라 뒀다: 이쪽은 스크립트가 파싱하는 토큰 하나여서, 길어지면 그렇게 하는 호출자가 전부 깨진다. MCP 도구 짝은 없고, 이유는 version_string 과 같다.

version_string

() -> String

엔진 + 파서 핑거프린트 버전 문자열. Result 가 없다 — 실패할 수 없다. 사용자 표면에는 zzop manifest 와 zzop facts 의 tool 필드로, zzop graph 의 %% tool: 센서스 줄로, 그리고 zzop version --verbose / zzop-mcp version --verbose 가 찍는 것으로 닿는다. 그냥 zzop version 은 맨 릴리스 번호로 남고 핑거프린트를 싣지 않는다. MCP 도구 짝은 없다: 위에 이름 댄 zzop-mcp version --verbose 는 그 바이너리의 서브커맨드이지 MCP 호스트가 호출할 수 있는 도구가 아니다.

explain

(query: &str) -> Result<String, String>

룰 id 하나 → 그 번들 DSL 룰의 컴파일된 데이터를 사람이 읽는 줄로. 실행에서 읽는 것은 없다 — 팩 데이터는 바이너리 안에 컴파일돼 있다. Err 에는 안내가 붙는다: 그 id 가 실제로 무엇인지 이름을 대고(네이티브 분석 id, 팩 전체 id, 출력 필드 id, 모호한 맨 id, 아니면 미상), 미상인 id 에 대해서는 더 넓은 코퍼스로 explain_with_config 를 가리킨다. MCP 도구 짝이 없는 zzop explain 을 떠받친다 — 에이전트는 대신 rule-catalog 계약 리소스를 읽는다.

explain_with_config

(config_path: &str, query: &str) -> Result<String, String>

더 넓은 코퍼스 위의 같은 조회: 그 설정의 트리들이 실제로 적재하는 팩 — 컴파일된 것에 더해 그 트리들이 이름 대는 모든 zzop/rules/ 와 packs.extraDirs 디렉터리. 번들 집합을 떠난 룰에 닿는 유일한 표면이다: 트리로 회수된 그런 룰은 자기 id 로 돌면서 발견을 내는데, 컴파일된 것만 보는 조회는 그 id 를 미상이라 부른다. 설정 파일(과 그 팩 디렉터리)을 읽는다 — 무엇도 분석하지 않는다. zzop explain <rule-id> --config <path> 를 떠받치고, 그냥 zzop explain 과 마찬가지로 MCP 도구 짝은 없다.

설정은 필수다; 시작용 설정만으로도 전체 분석이 돈다

모든 분석 레인은 zzop.config.jsonc 가 없는 트리를 거부한다 — 두 배포 바이너리 모두에서, 같은 거부를 같은 문서 이름을 대며 한다. 의례가 아니다: vocabulary 블록은 그것이 없으면 zzop 이 당신 프로젝트에 대해 추측해야 할 이름들을 담고 있고, 선언되지 않은 키는 zzop 이 내리지 않는 판정이다 — 이름 기반 인증 면제, 생성 파일 탐지, 쓰기 지점 판정이 그것과 함께 전부 꺼진다. zzop init 은 zzop 자신의 값이 이미 들어 있는 그 파일을 써 준다.

나머지는 전부 기본값이 선다. roots 만 선언한 시작용 설정으로도 두 바이너리 모두에서 똑같이 전체 분석이 돈다 — 둘 다 공유 zzop-summary 층과 그 zzop-config 크레이트를 지나가고, 그 층이 번들 DSL 룰팩(바이너리에 컴파일돼 있다), 엔진의 recentDays: 30 git 기본값, 그리고 .zzop/cache 라는 cacheDir 을 주입한다:

시작용 설정이 줄 수 없는 단 하나는 두 번째 트리다: 루트가 하나면 크로스레이어 조인은 이을 것이 없다. pnpm-workspace.yaml(또는 package.json 의 workspaces)이 2개 이상의 패키지로 풀리는 워크스페이스 루트에서는, 실행의 첫 configWarnings 항목이 그 매니페스트와 정확한 패키지 개수, 그리고 {"trees": "auto"} 라는 처방을 이름 댄다.

zzop init        # writes zzop.config.jsonc — required once per tree
zzop analyze .   # that config is auto-discovered; bundled packs +
                     # git defaults fill in everything it did not say

zzop_facade::analyze_json 을 직접 부르면 그 앞에 그런 래퍼가 없다 — 파사드는 암묵적 기본값을 하나도 적용하지 않는다. 맨 {"root": "."} 설정 JSON 은 DSL 팩을 0개 적재하고(네이티브 분석만) git 수집을 끈 채 돈다(scores/health/recommendations 가 null 로 남는다) — packsDir/packDefs 와 git 을 직접 세우지 않는 한:

let config = serde_json::json!({ "root": ".", "git": {} }).to_string();
let result: serde_json::Value =
    serde_json::from_str(&zzop_facade::analyze_json(&config)?)?;

• packsDir 생략(파사드) — DSL 팩이 아예 적재되지 않는다. packsDir(*.json 팩들이 든 디렉터리)이나 packDefs(인라인 정의 — 아래 참고)를 명시적으로 넘겨라.
• packsDir 지정, 디렉터리 여럿 — 전부 적재해 병합한다. 두 디렉터리가 같은 id 의 팩을 실으면 뒤쪽 디렉터리가 그 팩을 통째로 대체한다(룰 단위 병합이 아니다).
• packDefs 지정 — 어떤 packsDir 항목보다 먼저 적재되므로, 같은 id 의 디렉터리 팩이 충돌을 통째로 이긴다. 디스크에 팩 디렉터리가 없는 호스트(예: zzop-mcp — 그 zzop-config 층이 번들 팩을 이 방식으로 주입한다)가 룰을 갖게 되는 유일한 길이 이것이다.
• git 생략(파사드) — git 수집이 꺼진다. scores, health, recommendations, critical, seams, layerCoChurn 이 null 로 남는다. 엔진 자신의 recentDays: 30 기본값으로 켜려면 git: {} 를, 그 값을 덮으려면 git: { "recentDays": N } 을 넘겨라. root 가 git 레포지토리가 아니면 엔진은 곱게 성능을 낮추고 그 사실을 warnings 에 보고한다.
• cacheDir 생략 — 디스크에 쓰는 유일한 기본값이고, 그래서 지금 어느 방언에 있는지 알아 둘 값어치가 있는 유일한 기본값이다. zzop/zzop-mcp/설정 파일 아래에서는 .zzop/cache 로 기본값이 서고, 설정 파일의 디렉터리(설정 파일이 없으면 분석 대상 루트)를 기준으로 풀리며, 첫 실행이 당신이 분석한 트리 안에 그것을 만든다 — 그 레포의 .gitignore 에는 zzop* 글롭이 아니라 앵커된 **/.zzop/ 를 넣어라. 전자는 버전 관리에 있어야 할, 사람이 쓴 zzop/ 디렉터리(커스텀 룰팩, 어댑터 오버레이)까지 삼킨다. 키를 null 로 두면 캐시가 꺼지고 아무것도 쓰지 않는다. 파사드를 직접 부르면 기본값이 아예 주입되지 않는다: 필드를 생략하면 캐시 없이 돌고 쓰는 것이 없다.
• vocabulary 생략 — 주입되는 것도 없고 폴백되는 것도 없다 — 모든 경로에서, 당신이 선언하지 않은 키는 그냥 판정되지 않는다(내장 폴백 갈래는 2026-07-27 에 제거됐다). 내장 값들은 zzop init 이 당신의 시작용 파일에 써 주는 것으로만 살아남는다 — 즉 그것들이 실행에 닿는 이유는 당신의 설정이 그렇게 말하기 때문이다. 그래서 이 블록을 쓰는 것은 아주 많은 것을 바꾼다: 빼 두면 룰은 덜이 아니라 더 발화한다. 선언되지 않은 가드 어휘는 어떤 가드도 증명하지 못하고, 선언되지 않은 면제는 어떤 면제도 주지 못하기 때문이다.

AnalyzeRequest

#[serde(rename_all = "camelCase", default)] — root 를 빼면 모든 필드가 선택이고, 모르는 필드는 거부가 아니라 무시된다.

analyzeEnvelope 의 설정(EnvelopeAnalyzeRequest)은 더 작은 모양이다 — 위 필드들의 부분집합이고, 권위 있는 목록은 EnvelopeAnalyzeRequest 구조체 자신(crates/facade/src/request.rs)이다. AnalyzeRequest 와 공유하는 필드는 그쪽 짝과 똑같이 동작한다. mountedAt/mounts 는 위에서 설명한 배포 토폴로지 마운트 의미를 그대로 싣고, 엔벨로프의 http provide 에 균일하게, 같은 접힘 순서로 적용된다(mounts 항목 전부가 먼저, 트리 전체를 뜻하는 암묵적 dir: "" 항목인 mountedAt 이 마지막). 엔벨로프에는 엔진이 다시 읽을 수 있는 파일 시스템 위치가 없으므로 root, cacheDir, git, sizeCap 은 해당되지 않는다 — 소스 텍스트가 없으니 엔벨로프 모드에서 발화하는 DSL 룰은 symbol-scan/io-scan 뿐이다. 네이티브 콜그래프 BFS 룰(mutating-route-no-auth, unsafe-read-endpoint, non-idempotent-write)은 엔벨로프가 자기 calls 채널을 줄 때 추가로 돈다(파일별 호출 간선, files[].calls — NORMALIZED_AST.md 의 calls 절, 최소 version >= 0.29.0). http 라우트는 있는데 calls 가 없는 엔벨로프는 그 룰들을 침묵시키고, 침묵한 룰의 이름을 대며 warnings 에 그렇게 적는다. 배포된 io-scan 룰 둘(http/protected-path-no-auth-evidence, http/dev-path-no-guard-hint)은 여기서도 돌지만, 그 앵커 줄 채널은 돌지 않는다: 소스 텍스트가 없으면 읽을 줄이 없으므로, 파생된 zzop-<rule-id>-ok 억제 마커와 dev-path-no-guard-hint 의 anchor_exclude_pattern 가드 힌트 예외가 둘 다 무력해진다. 둘 다 침묵이 아니라 발화 쪽으로 실패한다 — 맞는 라우트는 등록 줄이 마커나 가드 힌트 인자를 달고 있어도 보고된다 — 그러니 검토를 마친 라우트를 통과시키려면 룰이 읽는 속성을 주입하거나(protected-path-no-auth-evidence 에는 auth-guarded) 설정에서 그 룰을 끄면 된다. 모드 B 의 adapterOverlays 는 영향을 받지 않는다: 그쪽은 소스 텍스트를 읽을 수 있는, 네이티브로 파싱된 트리 위에 병합되므로 두 채널이 그대로 살아 있다.

레퍼런스 모드 B 어댑터가 완성된 예제로 레포에 들어 있다 — 채널 하나짜리 최소 어댑터(빠진 imports 채널을 90 줄 남짓으로 채운다. 가장 낮은 진입로다)와 속성 주입 어댑터(라우터 수준 가드를 파일 속성으로 주입한다), 둘 다 공유 adapter-kit 위에 얹혀 있다. 각각 프레임워크 하나씩을 보여 주는 것이 아니라 계약을 보여 준다: 프레임워크별 맛은 어댑터가 실제로 채워야 하는 채널에 자리를 내주고 제거됐다.

IO 와 의존 사실 너머로, 오버레이는 일반 엔티티 속성을 실을 수 있다: 라우트·심볼·파일·경로 범위에 붙는 열린 어휘의 { target, key, value } 주석이고, 룰이 키로 소비하되 엔진은 그 키가 무슨 뜻인지 끝까지 알지 못한다. 네이티브 패스가 혼자서는 볼 수 없는 횡단 사실 — 속도 제한, 검증 층, 또는 (네이티브 파서가 이제 직접 알아보는 흔한 Express 모양 바깥의 무엇이든) 미들웨어가 적용한 라우터 수준 인증 가드 — 을, 끝없이 자라는 네이티브 모델링 대신 주입으로 채우는 방법이 이것이다. 첫 소비자는 mutating-route-no-auth 다: 라우트의 ioKey(또는 미들웨어가 지키는 pathScope 접두사)에 auth-guarded 속성을 주입하면 룰이 그것을 통과시키고, 자기 네이티브 콜그래프 스캔과도, 알아본 Express 가드에 대해 네이티브 파서 자신이 내보내는 같은 속성과도 함께 어우러진다. 두 번째 소비자는 cross-layer/retrying-write-no-idempotency 다: 제공자 라우트에 붙은 idempotency-guarded 속성 — 핸들러가 Idempotency-Key 헤더를 읽을 때 TypeScript 파서가 네이티브로 세우거나, 다른 어떤 제공자 언어에서든 주입된다 — 이 가드가 목격되는 순간 그 발견에 거부권을 행사한다.

여러 레포지토리를 함께 분석하기

analyze_trees_json(CLI: zzop cross, MCP 도구: cross_repo)은 트리마다 analyze 를 한 번씩 돌린 다음, 모든 트리가 선언한 IoFact(HTTP/DB/tRPC 의 provide 와 consume)를 전부에 걸쳐 잇는다. 프런트엔드 체크아웃과 백엔드 체크아웃이 디스크에서 아무것도 공유하지 않는 완전히 별개의 git 레포지토리여도 조인된다.

let config = serde_json::json!({
  "trees": [
    { "root": "../frontend", "sourceId": "web" },
    { "root": "../backend",  "sourceId": "api" },
  ]
}).to_string();
let result: serde_json::Value = serde_json::from_str(&zzop_facade::analyze_trees_json(&config)?)?;

// Or from the CLI (trees tagged by directory name; use --config for custom sourceIds / topology):
// zzop cross ../frontend ../backend

결과 모양은 { trees: [{ root, sourceId, output }], crossLayer, crossLayerFindings, disclosure } 다. 트리마다의 output 은 자기 coverage 센서스를 싣고, disclosure(침묵 실패 계열 등기부)는 실행 전역이라 한 번만 나온다. crossLayer 는 날 조인 결과를 싣는다 — 맞은 edges, unconsumedProvides, unprovidedConsumes, unresolvedConsumes, 다중 트리 매치인 ambiguousConsumes, 그리고 절대 URL 인 externalConsumes. 어느 트리든 토폴로지 hosts 를 선언하면 crossLayer 는 hostRekeyCounts 도 싣는다 — 선언된 호스트마다 [host, rekeyedConsumeCount] 짝 하나이고, 어떤 트리도 호스트를 선언하지 않으면 통째로 빠진다. crossLayerFindings 는 그 조인 위에서 도는 cross-layer/* 네이티브 룰의 출력이다(전체 id 목록은 룰 카탈로그를 보라). 크로스레이어 발견은 어느 한 트리의 것이 아니므로, 어느 한 트리에서 disabledRules 로 이 룰 id 중 하나를 끄면 그것이 모든 트리의 합친 배열에서 빠진다 — 트리별 관문이 아니라 합집합이다. coverage.joinContributionZero 가 true 인 트리는 이 조인에 IO 를 하나도 보태지 않았다 — 그 트리를 참조하는 크로스레이어 발견은 그만큼 깎아 읽어라.

AnalyzeOutputView

같은 입력이면 바이트까지 같은 출력이다 — 타임스탬프도, 불안정한 맵/배열 순서도 없다. 어떤 실행이 제공할 수 없는 능력은 스키마에서 빠지고 warnings 에 스스로 보고된다. 가짜 빈 값으로 채워 넣는 일은 결코 없다. 반대로 빈 배열은 언제나 "분석했고 아무것도 찾지 못했다"는 뜻이다.

이 색인은 와이어 모양이고, 이름이 가리키는 타입보다 한 겹 넓다: 응답 루트는 AnalyzeOutputView 를 평평하게 펴고 실행 전역인 disclosure 등기부를 형제로 덧붙인다. 두 쪽 다 docs/contracts/surface-parity.json 에 한 번씩 열거돼 있다 — 최상위 키는 전부 거기에 행이 있어야 하고, 없으면 빌드 테스트가 실패한다.

JSON 트리는 위에서 아래까지 전부 camelCase 다 — 최상위 뷰뿐 아니라 중첩된 모든 타입이 자기 표기 규칙을 함께 지닌다. Finding.data 가 의도된 단 하나의 예외다: 균일한 표기 규칙이 없는, 룰 작성자가 쓴 불투명한 JSON 이다.

severity 가 주장하는 것. severity 는 그 발견 하나에 대한 zzop 의 확신을 말하고, 그 확신은 이번 실행이 볼 수 있었던 것에 묶여 있다 — zzop 은 소스를 읽지, 돌아가는 시스템을 찔러 보지 않는다. 크로스레이어 룰 둘이 스스로 등급을 낮춤으로써 그 경계를 눈에 보이게 만든다: cross-layer/unconsumed-mutation-endpoint 와 cross-layer/unprovided-mutation-call 은, HTTP 호출이 대부분 풀리지 않은 채 돌아온 소스를(각각, 서버 프레임워크를 import 하면서도 라우트를 거의 내놓지 못한 소스를) 실행이 들고 있을 때 warning 이 아니라 info 로 보고하고 그 소스를 메시지에서 이름 댄다. 어느 쪽이든 발견은 발화하므로, 이것은 억제가 아니라 확신의 눈금 맞추기다. 그 역은 성립하지 않고, warning 갈래의 메시지가 스스로 그렇게 말한다: 실명 검사 하나하나는 좁은 술어 하나이므로, 룰이 warning 에 머물렀다는 것은 실명이 목격되지 않았다는 뜻이지 커버리지가 완전하다고 증명됐다는 뜻이 아니다. 이 추출이 모델링하지 않는 호출 모양이나 언어로 부르는 호출자, 또는 이번 실행 바깥의 레포지토리에 있는 호출자는, 룰에게 그런 것과 똑같이 이 검사에게도 보이지 않는다. severity 를 판결로 대하기 전에, 이번 실행이 자기 한계를 스스로 적은 warnings 와 아래 coverage 센서스를 읽어라.

좁아진 범위는 말없이가 아니라 warnings 에 스스로 보고한다

에러는 호출이 실패했다는 뜻이다. 능력이 없는 것은 에러가 아니다 — 분석은 정상적으로 끝나고, 엔진이 무엇을 건너뛰었으며 왜 그랬는지를 정확히 말한다. 이 자기보고는 JS 래퍼가 아니라 엔진 자신 안에서 일어나므로, Rust 엔진을 직접 부르는 JS 아닌 소비자에게도 똑같이 적용된다.

"warnings": [
  "git history not requested (git option omitted): scores, health,
   recommendations, criticality, seams and layerCoChurn are null.
   Pass git: {} to enable them."
]

DSL 룰팩을 하나도 찾지 못했을 때도 같은 방식이다: 엔진은 네이티브 분석만 돌았다는 사실과 그 개수를 이름 대지, 설명 없이 조용히 더 작아진 findings 배열을 돌려주지 않는다.

프로세스는 죽지 않는다

crates/facade/src/lib.rs(크레이트 zzop-facade)는 계약상 결코 패닉하지 않는다 — 실패할 수 있는 모든 경로(망가진 JSON, 빠진 root, 유효하지 않은 엔벨로프)는 대신 Result<String, String> 을 돌려준다. 엔진은 파일 하나의 파싱/룰 실패를 이미 내부에서 격리하고, 그것이 바깥 경계에 닿기 한참 전에 그렇게 한다. Rust 로 직접 부르는 쪽은 Ok(String) 아니면 Err(String) 만 보고, 프로세스 중단은 결코 보지 않는다. zzop-mcp 바이너리는 사이에 FFI 경계 없이 이 함수들을 부르므로, 따로 따져 볼 애드온 쪽 catch_unwind 층 같은 것은 없다 — 파사드 자신의 계약이 이야기의 전부다. version_string 에는 Result 자체가 없다 — 실패할 수 없다.