편집기 지원 (템플릿)

템플릿을 편집하는 동안 컴포넌트·핸들러·수정자·슬롯·태그·필터의 이름을 편집기가 알게 한다. 이름을 틀리면 페이지를 그려 볼 때가 아니라 치는 자리에서 안다.

두 갈래가 있다. 파이썬 쪽은 타입 스텁이 맡는다 — 컴포넌트 클래스의 .pyi로 pyright·mypy와 IDE가 필드와 핸들러를 안다. 템플릿 쪽이 이 문서다. manage.py wireview_lsp가 프로젝트를 읽어 JSON 하나로 내고, 편집기가 그것을 읽는다. 이 저장소의 editors/vscode/에 VS Code 확장이 있고, 같은 진단을 CI에서 돌리는 것이 manage.py wireview_check_templates다.

VS Code 확장#

확장 ID는 itda.django-wireview다. VS Code는 Visual Studio Marketplace에서, Cursor·VSCodium처럼 Open VSX를 쓰는 편집기는 Open VSX에서 설치한다. 확장 보기에서 "Django Wireview"를 찾거나 명령으로 설치한다.

code --install-extension itda.django-wireview

Marketplace에 닿지 않는 환경이거나 아직 게시하지 않은 변경을 써 보려면 .vsix 파일을 직접 설치한다. 게시한 버전의 .vsix는 그 버전의 GitHub Release(태그 vscode-v<버전>)에 붙어 있고, 저장소에서 만들 수도 있다.

make ext-install    # editors/vscode 의 npm 의존성
make ext-package    # editors/vscode/dist/django-wireview-<버전>.vsix
code --install-extension editors/vscode/dist/django-wireview-<버전>.vsix

할 수 있는 일, 설정, 알려진 한계는 확장의 README에 있다(Marketplace 페이지가 되는 영어판과 같은 내용). 요약하면:

  • **/templates/**/*.html과, 메타데이터의 template_dirs 안에 있는 .html을 django-html 언어로 열고 구문 강조·주석·자동 닫기·들여쓰기를 준다. files.associations가 html로 적은 파일과 사용자가 html로 되돌린 문서는 그대로 둔다. 언어가 html이 아니게 되어 잃는 HTML 기능(태그·속성 자동완성, 닫는 태그)은 HTML 언어 서비스로 되돌린다. 다른 Django 확장은 필요 없다
  • Django 태그·필터와 django-wireview의 컴포넌트·인자·이벤트·수정자·핸들러·슬롯·훅의 자동완성, 호버, 정의로 이동
  • Django나 django-wireview가 렌더할 때 낼 오류의 진단. 확실하지 않으면 말하지 않는다 — 이 저장소의 모든 템플릿이 진단 0건인 것을 tests/test_vscode_extension.py가 확인한다
  • 파이썬 파일을 저장하면 메타데이터를 다시 만든다. 실패하면 마지막으로 성공한 것을 쓴다
  • 개발 서버가 렌더마다 쓰는 부분별 SQL을 읽어 템플릿 줄과 property의 def 줄 끝에 inlay hint로 수를 단다(6 queries, ⚠ 6× same query, 1 query per render). 저장된 파일이고 서버가 실행한 원본이 바로 그 파일일 때만 보인다. 무엇을 확인하는지는 편집기에서 보기에 있다
설정 기본값 뜻
wireview.renderQueries.enable true SQL 수를 단다
wireview.renderQueries.directory "" 개발 서버가 쓰는 디렉터리(폴더 기준). 비우면 manage.py 옆의 .wireview/render-queries. DEBUG_RENDER_QUERIES_DIR을 바꿨을 때 같은 곳을 적는다
wireview.renderQueries.maxAge 30 컴포넌트의 마지막 렌더를 몇 분 동안 보이는가
wireview.renderQueries.mapRelative false 기록의 rel을 manage.py의 디렉터리 아래에서도 찾는다. 편집기 밖의 컨테이너에서 서버가 돌 때

신뢰하지 않은 워크스페이스(제한 모드)에서 확장은 프로세스를 하나도 띄우지 않고 메타데이터 파일도 읽지 않는다. wireview_lsp를 돌리는 것은 프로젝트의 코드를 실행하는 일이고, 메타데이터에 적힌 경로는 정의로 이동이 여는 파일이기 때문이다. 개발 서버가 쓰는 SQL 기록도 읽지 않는다. 구문 강조·스니펫·HTML 기능만 되고, 워크스페이스를 신뢰하는 순간 메타데이터를 만들고 기록을 읽는다.

확장은 라이브러리의 공개 API가 아니고 버전을 따로 매긴다(editors/vscode/package.json, 변경은 확장의 CHANGELOG). 라이브러리와 확장 사이의 약속은 둘이다. 아래 JSON과, 렌더 부분별 SQL의 파일 형식이다. 둘 다 자기 version으로 따로 매긴다. tests/test_vscode_extension.py가 서버가 실제로 쓴 SQL 기록을 확장의 코드(editors/vscode/src/core/queries.ts)로 읽어 본다.

CI에서: manage.py wireview_check_templates#

확장과 같은 진단을 편집기 없이 돌리고, 문제가 있으면 실패로 끝난다. CI와 코딩 에이전트가 "템플릿이 틀렸다"를 종료 코드로 받는 길이다.

$ python manage.py wireview_check_templates
myapp/templates/myapp/board.html:12:31: error [unknown-handler] XBoard has no method 'incremnt'.
1 error in 24 templates
CommandError: templates have problems that fail the check
$ echo $?
1
python manage.py wireview_check_templates                      # 프로젝트의 템플릿 디렉터리 전부
python manage.py wireview_check_templates myapp/templates a.html  # 파일·디렉터리를 골라서
python manage.py wireview_check_templates --strict             # warning도 실패로
python manage.py wireview_check_templates --format json        # 진단의 JSON 그대로
python manage.py wireview_check_templates --node /opt/node/bin/node

Node.js 22.18 이상이 필요하다. 진단은 확장의 코드(editors/vscode/src/core/) 그대로이고 node가 TypeScript 소스를 그대로 실행한다 — npm 패키지는 필요 없다. 그 코드는 wheel에 함께 실린다(wireview/template_diagnostics/). 파이썬은 메타데이터(wireview_lsp)를 임시 파일로 만들어 넘길 뿐이다.

종료 코드 뜻
0 error가 없다(--strict면 warning도 없다)
1 문제가 있다. 무엇이 어디에 있는지 한 줄씩 찍는다
2 검사를 하지 못했다: node가 없거나 22.18보다 낮다, 경로가 없다, 템플릿이 하나도 없다, 진단이 죽었다

2를 1과 나눈 것은 CI가 "node가 낡았다"를 "템플릿이 틀렸다"로 읽지 않게 하려는 것이다. 템플릿을 하나도 찾지 못한 경로도 2다 — 잘못된 디렉터리를 가리킨 관문은 언제나 통과한다.

error만 실패다. error는 Django나 django-wireview가 렌더할 때 낼 오류(모르는 필터·핸들러·컴포넌트, 닫히지 않은 블록, load하지 않은 태그 …)이고, warning은 그렇지 않을 수 있는 것이다 — 어느 라이브러리도 등록하지 않은 태그 (unknown-tag), 컴포넌트에 없는 인자(unknown-argument), 빠진 필수 인자(missing-argument, 같은 id의 인스턴스가 이미 그 값을 들고 있으면 괜찮다), 핸들러에 없는 인자(unknown-handler-argument), 파일 시스템에 없는 템플릿(template-not-found, 다른 로더가 찾을 수 있다). --strict가 이것도 실패로 친다. information(훅 파일이 등록하지 않은 훅, unknown-hook)은 찍기만 하고 --strict에서도 실패로 치지 않는다.

경로를 주지 않으면 템플릿 엔진의 로더가 찾는 디렉터리(template_dirs) 가운데 설치된 패키지(site-packages) 밖의 것만 본다. Django admin이나 서드파티 앱의 템플릿은 그 패키지가 검사할 것이다.

Node가 없는 CI라면 manage.py check의 System Checks가 파이썬 쪽 함정만 본다. 템플릿은 보지 않는다.

manage.py wireview_lsp#

python manage.py wireview_lsp                          # stdout
python manage.py wireview_lsp --output metadata.json   # 파일
python manage.py wireview_lsp --pretty

Django를 띄워 등록된 컴포넌트, 함수 컴포넌트, 훅 파일, 템플릿 엔진을 읽는다. 템플릿은 컴파일하지 않는다 — 편집 중인 템플릿 하나의 구문 오류가 다른 모든 것을 가리지 않게 하려는 것이다.

버전#

최상위의 version이 형식의 버전이다. minor는 키를 더할 때, major는 있던 키의 뜻이나 모양을 바꿀 때 올린다. 읽는 쪽은 자기가 아는 major이고 minor가 그 major에서 자기가 아는 것 이상이면 읽는다. 규칙은 호환성 정책에도 있다.

지금 형식은 2.0이다. django-wireview 1.0부터 1.2까지는 1.1을 낸다. 확장은 둘 다 읽는다:

읽는 쪽 \ 메타데이터 1.1 (django-wireview 1.0~1.2) 2.0
1.1 이상의 1.x만 읽는 확장(#162 전) 읽는다 읽지 않는다. 확장을 올리라고 알린다
1.1 이상의 1.x와 2.x를 읽는 확장 읽는다. 펼칠 것이 없다 읽는다. 프레임워크 메서드를 컴포넌트에 다시 펼친다
wireview_check_templates — 같은 휠의 진단이 같은 휠의 메타데이터를 읽으므로 언제나 2.0

확장은 1.0이면 django-wireview를, 3.0 이상이면 확장을 올리라고 알린다. major를 보는 다른 도구는 2.0을 거절할 것이다 — 그것이 major를 올린 이유다(아래).

1.x에서 2.0으로#

1.x의 컴포넌트 methods는 공개 메서드를 전부 담았다. 그 대부분은 모든 컴포넌트에 똑같이 있는 pydantic과 wireview의 메서드(model_dump, joined, allow_upload …)와 그 docstring이었다 — testproj에서 출력의 97%다. 2.0은 그것을 최상위 framework_methods에 한 번 적고, 컴포넌트에는 inherited_methods로 이름만 적는다. methods에는 컴포넌트 자신의 코드가 정의한 메서드만 남는다. 프레임워크 이름을 사용자 클래스가 오버라이드한 것 (async def joined)은 자기 것이므로 methods에 남고 is_handler는 여전히 거짓이다.

키를 더하기만 한 것이 아니라 methods의 뜻이 바뀌었으므로 major를 올렸다. 1.x 독자가 2.0을 읽으면 {% on "click" "joined" %}를 "핸들러가 아니다"가 아니라 "그런 메서드가 없다"로 말하고, 그 메서드로 가는 호버와 정의로 이동을 잃는다. 확장은 읽을 때 inherited_methods를 framework_methods에서 찾아 컴포넌트의 methods에 다시 넣으므로(editors/vscode/src/core/metadata.ts의 expandMethods) 1.1과 2.0에서 같은 진단·호버· 완성·정의로 이동을 낸다(editors/vscode/test/metadata.test.ts).

형식 2.0#

1.1에 있던 키는 그대로다. 1.1이라고 적은 것은 1.0에 더해진 것, 2.0이라고 적은 것은 2.0에서 바뀌거나 더해진 것이다.

최상위:

키 뜻
version 형식의 버전, "2.0"
wireview_version 1.1 이 JSON을 만든 django-wireview의 버전. 설치되지 않은 소스 트리면 ""
generated_at 만든 시각(UTC, ISO 8601)
components 등록된 이름 → 컴포넌트(아래). 같은 이름이 둘이면 템플릿의 이름 찾기처럼 나중 것
framework_methods 2.0 메서드를 정의한 곳 → 메서드 이름 → is_async, parameters, docstring, file_path, line_number. 정의한 곳은 그 메서드를 자기 속성으로 가진 프레임워크 클래스의 점 경로(pydantic.main.BaseModel, wireview.core.component.Component, wireview.features.presence.PresenceMixin)이고, 설명은 그 클래스에서 읽은 것이다. 사용자 클래스나 사용자 믹스인이 그 이름을 자기 속성으로 가지면 — 오버라이드든, 프레임워크 함수를 다른 이름에 넣은 것(leaving = Component.joined)이든, 다르게 바인딩한 것(new = staticmethod(Component.new.__func__))이든 — 공유하지 않고 그 컴포넌트의 methods에 남는다. 예외는 pydantic이 private 속성이 있는 클래스에 넣는 클래스 밖 함수(model_post_init) 하나로, 그 키는 그 함수의 점 경로(pydantic._internal._model_construction.init_private_attributes)다. pydantic이 사용자의 model_post_init을 감싼 것은 감싼 안의 함수로 읽는다(functools.wraps가 없는 pydantic 2.7에서도). 모두 핸들러가 아니므로 is_handler가 없다
function_components 1.1 {% func %}의 이름 → 함수 컴포넌트(아래)
hooks 1.1 훅 파일이 등록한 이름 → static_path(<app_label>/hooks/x.js), file_path, line_number(등록한 줄)
modifiers {% on %}의 수정자 → description, docstring(1.0부터 있던 키, description과 같은 값), has_argument, 1.1 argument("number", "text", null)
template_dirs 1.1 로더가 찾는 순서의 템플릿 디렉터리(DIRS와 앱의 templates). 절대 경로
template_builtins 1.1 템플릿 엔진의 내장 태그·필터(아래의 라이브러리 모양)
template_libraries 1.1 {% load %}의 이름 → 라이브러리: module, file_path, tags, filters

컴포넌트:

키 뜻
name, fqn, app_key 템플릿이 찾는 세 이름: Counter, myapp.live.Counter, myapp:Counter
module, file_path, line_number 클래스가 있는 곳
kind 1.1 "component" 또는 "live_component"
docstring 클래스의 docstring
template_name Meta.template_name
template_path 1.1 그 이름이 가리키는 디스크의 파일, 없으면 null. 템플릿 디렉터리를 순서대로 찾고, 심볼릭 링크를 푼 실제 경로를 적는다
fields 필드 → type, annotation(그 안 객체의 repr에서 메모리 주소를 지운다 — 실행마다 같은 출력이 나오게. 문자열은 그대로다), default, required, description, 1.1 in_state. id·user·session·wire는 빠진다. 1.1부터 Meta.exclude_fields의 필드도 실린다(in_state: false) — 템플릿이 넘기는 인자이기 때문이다
accepts_extra_kwargs 1.1 사용자 클래스가 new()를(LiveComponent면 update()·update_many()도) 오버라이드했는가. 참이면 필드가 아닌 인자도 그 코드가 읽을 수 있다
properties 1.1 사용자 클래스의 property·cached_property → type, is_async, docstring, file_path, line_number
methods 2.0 컴포넌트 자신의 코드(wireview·pydantic 밖)가 정의한 메서드 → is_handler(클라이언트가 부를 수 있는가, is_client_callable과 같은 판정), is_async, parameters, docstring, line_number, 1.1 file_path(믹스인의 메서드는 믹스인의 파일). 1.x에서는 프레임워크의 메서드도 여기 있었다
inherited_methods 2.0 프레임워크가 정의하고 컴포넌트가 오버라이드하지 않은 메서드: 정의한 곳(framework_methods의 키) → 이름 목록. 컴포넌트의 공개 메서드 전부는 methods와 이것을 합친 것이다
slots Meta.slots
subscriptions, subscriptions_is_dynamic, temporary_assigns Meta의 그것. get_subscriptions()를 오버라이드하면 subscriptions_is_dynamic

parameters는 이름 → type, default, has_default, kind(POSITIONAL_OR_KEYWORD, KEYWORD_ONLY, VAR_KEYWORD …)이다. 함수 컴포넌트는 name, fqn, module, file_path, line_number, docstring, template_name, template_path, parameters, slots를 갖는다.

라이브러리(template_builtins와 template_libraries의 값):

키 뜻
tags 태그 → docstring, file_path, line_number(태그를 등록한 함수. simple_tag는 감싼 사용자 함수), end, intermediate
filters 필터 → docstring, file_path, line_number, argument("none", "optional", "required"), forbidden_in_filter_tag({% filter %}가 거절하는가. Django의 do_filter처럼 이름이 아니라 함수가 마지막으로 등록된 이름 _filter_name이 escape·safe인지로 정한다. 키가 없으면 편집기는 말하지 않는다)

휴리스틱의 한계#

Django는 블록 태그가 어디서 끝나는지 기록하지 않는다. 태그의 컴파일 함수가 parser.parse(("else", "endif"))처럼 멈출 이름을 넘길 뿐이다. 그래서 end(끝 태그)와 intermediate(사이의 태그)는 그 함수의 소스에서 읽는다:

  • parser.parse((...))와 parser.skip_past(...)의 따옴표 리터럴. end로 시작하는 첫 이름이 끝 태그, 나머지가 사이의 태그다
  • 이름을 변수로 넘기면(parser.parse(until)) 소스의 "end…" 리터럴
  • simple_block_tag는 그것이 기억하는 end_name
  • Django의 blocktranslate(blocktrans)는 끝 태그 이름을 실행 중에 end + 태그를 부른 이름으로 만든다. 그 컴파일 함수(do_block_translate)로 등록된 태그만 그렇게 읽는다 — 다른 라이브러리가 같은 이름으로 등록한 태그는 제 소스대로 읽는다

읽지 못하면 end는 null이다. null은 "블록이 아니다"의 증거가 아니다 — {% load %}도 null이고, 이름을 다른 함수에서 만드는 서드파티 블록 태그도 null이다. 확장은 null인 태그를 블록으로 다루지 않고, 모르는 end… 태그와 제자리를 벗어난 사이 태그에는 아무것도 말하지 않는다.

template_dirs는 TEMPLATES에 적힌 Django 엔진의 로더가 찾는 디렉터리다. Django 폼 렌더러의 템플릿 (django/forms/...)은 엔진이 아니라 렌더러가 따로 찾으므로 여기 없다 — Django 자신의 폼 위젯 템플릿을 열면 그 안의 {% include %}가 template-not-found 경고를 받을 수 있다.

필드의 annotation과 default는 실행마다 같도록 객체 repr의 메모리 주소(<function f.<lambda> at 0x…>의 at 0x…)를 뺀다. 값 안의 문자열은 그대로 두지만, 객체 repr 안에 <… at 0x…> 모양의 문자열이 있으면 정규화될 수 있다 (Label(text='<object at 0xCAFE>')가 Label(text='<object>')로).

필터의 argument는 Django의 FilterExpression.args_check가 세는 방식으로 함수의 인자를 센다. needs_autoescape 필터가 받는 autoescape는 Django가 넘기는 것이라 세지 않는다.

다른 편집기#

같은 JSON을 읽으면 된다. 확장이 하는 것을 따라 하려면:

  1. 프로젝트의 파이썬으로 manage.py wireview_lsp --output <파일>을 돌리고, 파이썬 파일이 바뀌면 다시 돌린다. 실패하면 지난 결과를 쓴다. 실행을 멈출 때는 그것이 띄운 프로세스도 멈춰야 한다 — uv run 같은 래퍼는 SIGTERM을 자식에게 넘기지 않을 수 있다. 확장은 macOS·Linux에서 명령을 작은 /bin/sh 감독자 아래에서 돌린다. 감독자가 자기 프로세스 그룹의 리더이고, 멈출 때 그 그룹에 SIGTERM을, 2초 뒤 SIGKILL을 보낸다. 감독자는 SIGTERM을 받으면 그 SIGKILL까지 리더로 남으므로, 래퍼가 SIGTERM에 먼저 죽어도 그룹에 남은 프로세스까지 SIGKILL이 닿는다. 남아 있는 데는 쉘 내장 명령만 쓰고 사용자의 PATH에서 프로그램을 찾지 않는다. 명령은 포그라운드로 돌리므로 SIGINT·SIGQUIT를 받은 그대로 시작한다(백그라운드 작업은 둘을 무시한 채 시작한다). 신호는 Node가 감독자의 종료를 아직 보고하지 않았을 때만 보낸다(번호가 다른 그룹의 것이 된 뒤에 보내지 않으려는 것이다). 스스로 다른 그룹으로 옮겨 간 프로세스에는 닿지 않는다. Windows는 taskkill /T /F로 프로세스 트리를 끝내며, 이미 끝난 프로세스가 띄운 것은 트리에서 찾지 못한다. 그 판단은 editors/vscode/src/core/runner.ts의 supervised·stopSteps·Stopper에 있다
  2. version의 major를 확인한다
  3. 템플릿 파일의 실제 경로(심볼릭 링크를 푼 것)가 어떤 컴포넌트의 template_path와 같으면 그 컴포넌트가 템플릿의 this다 — 핸들러와 변수를 거기서 찾는다
  4. 태그가 보이는가는 template_builtins에 템플릿의 {% load %}를 적힌 순서대로 얹은 것이다. 나중 load가 같은 이름을 덮어쓰고(Parser.add_library), load보다 앞에 쓴 태그·필터는 그 라이브러리를 아직 모른다

SQL 기록을 읽는 법(세그먼트 이어 읽기, 클래스별 최신 스냅샷, 줄이 맞다는 확인)은 편집기에서 보기에 있고, 그 판단은 editors/vscode/src/core/queries.ts다.

확장의 판단은 editors/vscode/src/core/의 순수 모듈에 있다(VS Code를 import하지 않는다). 다른 편집기의 플러그인이 그대로 가져다 쓸 수도 있다. editors/vscode/scripts/diagnose.ts가 VS Code 없이 그 모듈로 템플릿을 진단하는 예다 (wireview_check_templates가 부르는 것도 이것이다):

node editors/vscode/scripts/diagnose.ts [--strict] metadata.json myapp/templates

경로마다 문제 목록을 JSON으로 찍고, 종료 코드는 위 표와 같다(error면 1, --strict면 warning도, 사용법 오류는 2). node 자신이 죽어도 1로 끝나므로 JSON을 읽지 못하면 문제가 아니라 실패로 다룬다.

Phoenix LiveView와 다른 점#

템플릿 완성·진단·SQL 귀속·CI 검사는 지원하지만 HEEx의 모든 컴파일 검증과 동일하지 않다. 특히 속성·슬롯 선언의 허용 값·global 속성·슬롯 속성 검증은 없다. Phoenix ColocatedHook·ColocatedJS의 템플릿 내 JS 추출도 제공하지 않는다. 외부 훅 파일 수집과 구분한다. 템플릿 수정 시 재join은 지원하지만 phx-track-static·static_changed?에 해당하는 배포 자산 변경 감지는 없다.

Phoenix 1.2의 ColocatedCSS, script/style용 TagFormatter, 모듈별 HEEx 디버그 주석 제외 설정은 대응 API가 없다. wireview의 외부 정적 파일·템플릿 진단과는 별개다.

브라우저 지연 시뮬레이션도 세부 의미가 다르다. wireview는 송신에 고정 지연을 더하고, Phoenix의 요청·응답 지연 및 브라우저 세션 저장 규칙을 그대로 구현하지 않는다.