truepath은(는) 무엇을 하나요?
하나의 spec.json이 프로세스(노드, 엣지), 시나리오(경로, 메시지, 캡션, 입력) 및 평결 출처를 설명합니다. build.py는 평결을 계산하고, 그래프를 배치하며, 검사를 실행하고, 하나의 오프라인 .html 파일을 쓰거나 아무것도 쓰지 않습니다.
spec.json ──┐
oracle/port ├─► build.py ──► checks C1–C13 ─► sim.html (또는 아무것도 없음)
layout.py ──┘ └► fixture.json (--export)
워크플로우
-
대상 주제의 노트 옆에 있는 가장 가까운 예제를 복사하고(파일 참조),
spec.json의 이름을<subject>.spec.json으로 바꿉니다. -
노드와 엣지를 설명합니다. 모든 싱크 노드(결과)는
kind를 가집니다.kind는 유일한 색상이며, 각각 범례 레이블이 있습니다. -
평결 출처를 선택합니다(아래 참조): 규칙이 코드에 존재하는 경우
oracle, 그렇지 않은 경우 JSport를 사용합니다. -
시나리오를 작성합니다. 각 시나리오는
origin,inputs, 예상 평결 필드(expect), 그리고 실제 엣지를 따라가는steps를 선언합니다. -
빌드한 후 파일을 엽니다:
python3 <skill-dir>/scripts/build.py <subject>.spec.json -
위반 사항을 읽고, 스펙을 수정합니다. 검사는 절대 수정하지 마십시오.
spec.json은 sim.html을 빌드하고, <subject>.spec.json은 <subject>.sim.html을 빌드합니다. -o는 다른 파일 이름을 지정합니다.
페이지는 세부 패널이 열린 상태로 첫 번째 탭에서 열립니다. 패널을 접으면 개요로 전환됩니다: 전체 경로가 그려지고, 하나의 점이 그 위를 반복해서 이동합니다.
평결 출처
| 출처 | 스펙 키 | 사용 시기 | 패널에 표시되는 표시 |
|---|---|---|---|
| 오라클 | oracle | 규칙이 저장소에 존재할 때 | ✓ code |
| 포트 | port: "decide.js" | 아직 코드가 없거나, 논의 중인 규칙이거나, 코드가 없는 프로세스일 때 | ⚠ ported |
오라클 프로토콜. build.py는 oracle.ref의 git archive를 가져오고(절대 라이브 체크아웃이 아닙니다. 작업 중인 브랜치는 빌드 중에 이동할 수 있습니다), oracle.paths를 추출하고, oracle.link(일반적으로 node_modules)를 링크하고, oracle.files를 그 안에 복사한 다음, oracle.cwd에서 oracle.cmd를 다음 환경 변수와 함께 실행합니다:
TRUEPATH_ORACLE_IN: 모든 시나리오의inputs를 담은 JSON 배열;TRUEPATH_ORACLE_OUT: 동일한 순서로 평결의 JSON 배열을 쓸 경로.
oracle.repo는 상대 경로일 경우 스펙의 폴더에서 읽습니다. link와 files는 모두 {스냅샷 경로: 출처} 형식으로 작성됩니다. link는 저장소의 경로, files는 스펙 옆의 파일입니다.
평결은 필드의 객체입니다. outcome은 필수입니다: 경로가 끝나야 하는 노드를 지정하며, 시나리오를 로직에 연결합니다. basis는 선택적으로 필드별로 실제 코드가 계산했는지("code: …"), 접착 코드가 동작을 복사했는지("port: …"), 또는 시뮬레이션이 정의했는지(다른 텍스트, ◇ definition으로 표시)를 나타냅니다. 페이지는 기준이 있는 모든 패널 값 옆에 해당 표시를 보여주고, 호버 시 전체 텍스트를 표시하며, --export는 기준이 code인 필드만 단언합니다. 기준이 없는 필드는 오라클에서는 코드로, port에서는 포팅된 것으로 간주합니다. 하나의 오라클에서 혼합될 수 있습니다: 아직 논의 중인 규칙은 코드가 이미 실행하는 규칙 옆에 포팅됩니다. 모든 실행기가 작동합니다: 프로젝트 자체 프레임워크의 테스트 파일, 스크립트, Java용 JUnit 테스트. 바닥글에는 평결을 생성한 ref와 짧은 sha가 표시됩니다.
테스트 파일 오라클은 회귀 테스트 스위트로도 사용할 수 있습니다: TRUEPATH_ORACLE_IN이 설정되면 평결을 쓰고, 그렇지 않으면 내보낸 fixture를 읽고 단언합니다. 시나리오는 스펙에 한 번만 존재하며 CI에서 실행됩니다. examples/loyalty-tier/src/oracle.js는 둘 다 수행합니다.
스펙 참조
| 키 | 형태 | 참고 |
|---|---|---|
title, subtitle, source | 문자열 | source는 바닥글에 표시됩니다. 스펙의 모든 텍스트와 마찬가지로 HTML로 읽히지 않고 텍스트로 표시됩니다. |
lang | en(기본값) 또는 fr | 페이지 자체 단어의 언어; 스펙의 텍스트는 해당 언어로 작성됩니다. |
kinds | {id: {label, color}} | 최대 4개 |
nodes | [{id, label, role?, kind?}] | role: "decision"은 분기점을 표시합니다. 경로가 시작되는 곳은 찾아서 원형으로 그립니다. 싱크는 kind가 필요합니다. |
edges | [[from, to, label]] | 레이블이 없으면 "" |
panel | [{label, value, at, labels?, digits?, compared?}] | value는 inputs.x 또는 verdict.y를 읽습니다. at 단계부터 표시됩니다(0은 첫 번째). labels는 값을 페이지에 표시할 내용에 매핑합니다("true", "false", "null", "[]"에 대해 해당 값). digits는 숫자 코드를 해당 길이로 제로 패딩합니다. compared: true는 한 쌍이 비교하는 항목(수정, 규칙)의 이름을 지정하는 행이며, 첫 번째 차이 검색에서 제외됩니다. |
scenarios | [{id, tab, summary, origin, inputs, expect, steps, undecided?, caseName?}] | origin: {kind: real|illustrative, text}; steps: [{hop: [from, to], message, caption}]; undecided: true는 아직 결정되지 않은 규칙을 표시합니다. caseName은 내보낸 fixture에서 사례의 이름을 지정합니다. |
pairs | [{before, after, tab, summary}] | 두 시나리오 ID로, −와 +로 나란히 재생됩니다. 동일한 단계 수를 가집니다. |
grid | {baseline, questions | variants, cases, steps, expect?, show?, hover, summary?} | scenarios와 pairs 대신 사례 × 답변(또는 규칙, 수정)입니다. 아래 참조. |
oracle | {repo, ref, paths, link?, files?, cwd, cmd} | 위 참조 |
port | decide(inputs)를 내보내는 CommonJS 파일의 경로 | 오라클이 없을 때 사용합니다. |
export | {dir, fixture, assert} | --export <worktree>는 fixture를 해당 위치에 씁니다. |
여러 규칙 비교: 그리드
질문이 "각 가능한 답변이 각 사례에 대해 무엇을 하는가"일 때 grid를 선언합니다. 평평한 규칙 목록보다는 질문을 선호합니다: 독자가 질문별로 결정하므로 페이지도 그렇게 배치되어야 합니다.
baseline:{id, label, short?, inputs}, 오늘날의 상황;questions:[{id, text, options: [{id, label, inputs}], cases, if?}].cases는 해당 질문이 결정하는 사례를 나열합니다.if: {"Q1": "1A"}는 해당 답변 이후에만 질문을 표시합니다.build.py는 일관된 답변 집합(1A+2A,1A+2B,1B)당 하나의 변형을 도출하고 옵션의inputs를 병합합니다.cases:[{id, label, summary, origin, inputs, steps?}];label은 독자가 아는 단어로 행의 이름을 지정하며, 사례 코드가 아닙니다.steps: 모든 셀에서 공유되며, 사례가 자체steps를 가져오지 않는 한 사용됩니다.expect:{case: {variant: {field: value}}}, C3에서 검사합니다.show: 행렬 셀이 표시하는 하나의 패널 행입니다(기본값은hover의 첫 번째 행).hover: 셀이 호버 시 표시하는 행입니다.summary: 행렬 위의 한 줄입니다.
baseline을 ID로 하는 평평한 variants: [{id, label, short?, note?, inputs}]도 여전히 작동합니다. 행렬은 하나의 섹션을 가지며, 모든 변형에 대해 모든 사례가 표시됩니다.
페이지는 행렬에서 열립니다: 질문당 하나의 테이블, 각 질문의 사례가 오늘날과 각 답변에 대해 표시되고, 셀의 라인이 오늘날과 다른 경우 ≠로 표시됩니다. 사례별 탭은 없습니다. 셀을 클릭하면 해당 사례가 열리고, 오늘날이 해당 답변 옆에 표시되며 첫 번째 차이점이 표시됩니다. 두 개의 버튼 행(−와 +)은 섹션의 답변 중 하나를 선택하고(1A를 1B 옆에, 오늘날 옆에만이 아니라), 각 버튼은 해당 질문의 이름으로 표시됩니다. ← matrix는 뒤로 돌아갑니다. 패널에서 "value": "answer"와 "compared": true를 가진 행은 재생 중인 답변의 이름을 지정합니다.
단계 템플릿. message, caption 및 hop은 {inputs.x} 또는 {verdict.y}를 인용할 수 있습니다. 로직 실행 후 채워지며, 동일한 경로를 읽는 패널 행과 같은 형식으로 표시됩니다. {verdict.outcome}으로의 hop을 사용하면 하나의 단계 목록이 모든 규칙에 사용될 수 있습니다.
검사
| Id | 거부 조건 |
|---|---|
| C1 | hop이 엣지가 아닌 단계 |
| C2 | 끊어지거나, 소스 노드에서 시작하지 않거나, 단계가 없는 경로 |
| C3 | 로직과 모순되는 expect 필드 |
| C4 | 로직의 outcome 이외의 곳에서 끝나는 경로, 또는 아무 것도 제공하지 않는 로직 |
| C5 | kind가 없는 결과, 범례가 없는 kind, 4개를 초과하는 kind |
| C6 | 상자보다 넓은 레이블(13px 고정폭) |
| C7 | 실제 또는 예시임을 명시하고 출처를 밝히지 않은 시나리오 |
| C8 | 함께 진행할 수 없거나 알 수 없는 시나리오 쌍 |
| C9 | 시나리오에 없는 필드를 읽는 패널 행 |
| C10 | 존재하지 않는 패널 행을 참조하는 행렬 셀 |
| C11 | 셀이 여전히 다른 질문에 의존하는 질문 아래에 표시된 사례 |
| C12 | 행렬 섹션에 없는 사례, 또는 알 수 없는 사례를 참조하는 섹션 |
| C13 | 시나리오에 없는 단계에 나타나도록 설정된 패널 행 |
C3과 C4가 핵심입니다: 코드가 수행하지 않는 작업을 말하는 시나리오는 게시될 수 없습니다. C6은 스펙보다는 레이아웃을 보호합니다. 상자는 레이블 크기에 맞게 조정되므로 layout.py가 더 이상 그렇게 하지 않는 경우에만 실행됩니다. 새 검사가 작동함을 증명하려면 tests/에서 입력을 한 번 깨뜨리십시오. 각 검사는 build.py의 하나의 함수이며, 이 테이블의 ID 아래 CHECKS에 나열됩니다.
빌드가 전혀 읽을 수 없는 스펙(누락된 키, 알 수 없는 노드로의 엣지, 예외를 던지는 포트)도 검사가 실행되기 전에 일반 언어로 동일한 방식으로 거부됩니다.
디자인 규칙
- 다이어그램당 하나의 움직이는 요소: 단일 점, 일정한 속도, 한 번에 하나의 hop. 두 개의 다이어그램이 나란히 동기화되어 이동합니다.
- 사용된 엣지는 실선, 사용되지 않은 엣지는 점선과 회색; 경로에서 벗어난 노드는 희미해집니다.
- 색상은 결과 종류만 인코딩합니다. 쌍에서 첫 번째 차이점(패널 값이 달라지는 첫 번째 단계)은 호박색으로 윤곽선이 표시되고 양쪽에
≠가 표시되며 패널에−/+열이 표시됩니다. - 예시 시나리오는 실제 사례가 해당 결과에 도달하지 않는 경우에만 사용합니다. 실제 사례의 출처(티켓, 기록, 측정값, 날짜)를 명시합니다.
- 그리드는 셀당 하나의 필드를 표시합니다. 셀당 세 개의 필드는 행렬을 읽기 어렵게 만듭니다.
- 기본적으로 밝은 테마,
prefers-color-scheme아래에서 어두운 테마; 웹 폰트가 없으므로 파일이 오프라인에서 작동합니다.
파일
| 경로 | 역할 |
|---|---|
scripts/build.py | 스펙을 읽고, 평결을 가져오고, 검사를 실행하고, 페이지와 내보내기를 씁니다. |
scripts/runtime.html | 페이지; build.py는 이미 형식화된 표시할 내용만 제공하고 스펙의 다른 것은 제공하지 않습니다. |
scripts/layout.py | 계층형 레이아웃: 상자는 레이블 크기에 맞게 조정되고, 직교 엣지를 사용합니다. |
examples/refund-window/ | JS 포트와 이전/이후 쌍 |
examples/free-shipping/ | 그리드: 두 개의 미해결 질문, 각각 변경하는 사례에 대해 결정됩니다. |
examples/loyalty-tier/ | 폴더 자체 src/에 대한 오라클, 접착 코드 및 --export가 쓰는 fixture |
생성된 파일(.truepath/, 오라클 스냅샷이 있는 곳, 그리고 스펙 옆의 *.html)은 빌드 출력입니다. 포트 예제는 실행하지 않고도 스킬을 볼 수 있도록 sim.html을 유지합니다. loyalty-tier는 유지하지 않습니다. 바닥글에 평결을 생성한 커밋이 표시되므로 페이지는 커밋마다 변경되며, 이를 포함하는 git 저장소 내에서만 빌드됩니다.
제한 사항
- 하나의 다이어그램 유형: 프로세스 흐름. 시퀀스 및 아키텍처 뷰는 구축되지 않았습니다.
C6는 macOS(ui-monospace)에서 측정됩니다. 더 좁은 Windows 글꼴은 여백만 추가합니다.- 단계는 선언되며 로직에서 파생되지 않습니다. C3과 C4는 잘못된 결과는 포착하지만 잘못된 중간 메시지는 포착하지 못합니다.