dartograph 0.7.0

A minor release introducing privacy-preserving graph export, dead-code redundant public reporting, architectural zone classifications in metrics, and cycle node highlighting in DOT output.

New Features & CLI surfaces

• graph --format anon (dependency-cruiser parity): exports privacy-preserving anonymized dependency graphs. File paths and identifiers are replaced with deterministic injective tokens (s0, s1, ...) while preserving graph topology, file extensions, and idiomatic Dart vocabulary. Limitation strings are sanitized in a single alternation pass.
• dead --report-redundant-public (Periphery parity): reports live public declarations that are never referenced outside their defining library as informational (info) diagnostics (exit code 0). Compatible with --since and machine-readable output formats (usage 64 when combined with --explain, --baseline, or --report-test-only).
• metrics architectural zones (cartograph parity): JSON output now includes a zone field (main-sequence, zone-of-pain, zone-of-uselessness, or isolated) for each metric item, aligned with --strict threshold calculations.
• graph --format dot circular dependency highlighting (madge parity): vertices participating in dependency cycles (detected via Tarjan's SCC) are rendered in red (#d9383a). Acyclic graph outputs remain byte-identical.

Analysis & Diagnostics

• GraphNode explicit isLibrary: HTML export and graph projections now use an explicit flag rather than .dart:: string heuristics, properly classifying libraries with :: in their filenames. Analysis cache serialization schema version bumped to v3 (automatic re-analysis of prior caches; cache identity unchanged).
• bridges limitations grammar: fixed plural noun formatting for unscanned-* limitations (N ≥ 2) and singular verb agreement for dynamic channel/method names (N = 1).

Full details: CHANGELOG.md (English) / CHANGELOG.ko.md (Korean).

Install: dart pub global activate dartograph — pure Dart CLI, Dart SDK 3.11+, no Flutter SDK required. MIT licensed, permanently free (commercial use included).

dartograph 0.6.0

A minor release: the public library API was trimmed to what is actually supported, plus output-fidelity fixes and a pub workspace membership hardening. CLI behavior and exit codes are unchanged for normal inputs.

Library API (breaking for library consumers; CLI unchanged)

• Removed querySymbol (a one-shot wrapper used only by tool/ benchmarks) — construct a SymbolQuerySession and call query.
• Removed CodeGraph.usageEdgesFrom (no product caller) — filter CodeGraph.edges.
• SymbolQuerySession.analysis is no longer public. Use deadDeclarations (an unmodifiable List<DeadFinding>) for the query --baseline flow, or SymbolQuerySession.query for reachability (each document carries the symbol's reachability state). DeadFinding is now exported; ReachabilityResult/ReachabilityExplanation stay internal, so no public member references an unexported type.

Fixes & hardening

• SARIF: output no longer corrupts already-absolute source URIs — file: (out-of-root) and package: (dependency) sources are passed through instead of being split on / and re-encoded (file:///a.dart used to become file%3A///a.dart). Project-relative sources keep the existing backslash-/percent-safe encoding.
• HTML graph: a library whose file name contains :: is classified correctly (via the .dart:: declaration boundary) instead of being shown as a member with a truncated name.
• bridges pub workspace: detection now validates membership. A resolution: workspace package joins the nearest ancestor workspace: root when that root plausibly lists it (explicit paths matched after URL normalization; glob entries and non-list values conservatively accepted). A well-formed explicit list that omits the package falls back to the scan root with a new pub-workspace-member-not-listed limitation, so a misconfigured workspace never silently skews the isthmus join basis.

Docs

• README revised for clarity (English original + Korean twin); no behavior change.

Full details: CHANGELOG.md (English) / CHANGELOG.ko.md (Korean).

Install: dart pub global activate dartograph — pure Dart CLI, Dart SDK 3.11+, no Flutter SDK required. MIT licensed, permanently free (commercial use included).

dartograph 0.5.0

0.5.0

신규 — bridges 모노레포 조인 (isthmus #38)

• bridges --format json --project <shared-root>: 스캔은 위치 인자(package-root) 그대로, 문서의 project 필드와 location.path를 공유 루트 기준(POSIX realpath)으로 내보냅니다. 공유 루트는 package root를 포함하거나 동일해야 하며(아니면 usage 64), 문서 생산 후 project를 손으로 고쳐 쓰는 것은 provenance를 깨므로 금지됩니다(GRAPH-EXCHANGE).
• pub workspace 자동 감지: pubspec에 resolution: workspace를 선언한 패키지는 workspace: 키를 가진 가장 가까운 조상 pubspec 디렉터리를 프로젝트로 자동 사용합니다. 감지 실패 시 스캔 루트로 폴백하며 pub-workspace-root-not-found/pub-workspace-pubspec-unparsed limitation으로 알립니다(조인 기준 어긋남이 조용하지 않음). 우선순위: --project > 감지 > 스캔 루트.
• 이로써 pub 모노레포의 형제 패키지들(*_platform_interface의 MethodChannel + plugin 패키지의 네이티브 쪽)이 isthmus 조인이 요구하는 정확히 같은 project 문자열을 낼 수 있습니다. 설치본 isthmus 0.2.0으로 왕복 검증: 3문서 조인 성공(evidence의 재기준 경로 보존) + 불일치 문서 거부.
• 옵션·선언이 없으면 기존 출력과 byte-for-byte 동일합니다.

성능 (출력 byte 동일 — A/B 하네스 sha256 7종 전후 동일로 고정)

• 인덱싱 cold-run -28% (합성 600파일/4,923노드 기준 1456→1053ms): element→ID 메모, CodeGraph 읽기 뷰 캐시, export 루프 hoist, 비교자 일원화, pubspec/source 단일 계산.
• query 배치 -84% (10.7→1.7ms): 도달성 Set·멤버 witness 색인(결정적 의미 보존), 이중 정렬 제거.
• rules 평가 -72% (10.8→3.0ms): glob RegExp 패턴별 캐시.
• dead --since의 심볼릭 링크 해석을 finding별에서 고유 source별 1회로 메모화.
• 신규 tool/benchmark_index.dart가 합성 패키지로 위 수치를 재현 가능하게 측정합니다(머신 의존 — 상대 비교용, SLA 아님).

출력 바이트가 바뀌는 지점 (0.4.1 대비)

• bridges: workspace 선언 패키지(또는 --project 사용 시)의 project·location.path — 그 외 기존 문서와 동일. bridges 제어문자 거부 메시지 정정("a fact value or source path contains control characters") — 동작은 0.3.0부터 동일.
• 성능 변경은 전부 산출물 sha256 동일로 검증 — 바이트 변화 없음.

캐시 identity에 toolVersion이 포함되어 0.4.x 캐시는 자동으로 한 번 재분석됩니다.

분석 한계는 파일 단위 관측이며 완전성이나 삭제 안전성을 보증하지 않습니다. bridge 심볼은 어휘적 이름이며 컴파일러 USR를 생성하지 않습니다.

dartograph 0.4.1

0.4.1

전체 감사(성능·보안·구조) 후속 수정 릴리스입니다. 새 명령·옵션은 없고(0.4.0 참조) 결함 수정·출력 충실성·문서 영어 전환이 내용입니다. pub.dev의 Readme·Changelog 탭이 이번 릴리스부터 영어로 제공됩니다(한국어본은 저장소의 README.ko.md·CHANGELOG.ko.md).

보안·주입 (실측 재현 후 수정)

• 개행 파일명이 Mermaid 라벨을 두 문장으로 절단(구문 주입)하고 text 진단줄을 위조하고 ESC·bidi가 GitHub Actions 로그로 통과하던 문제를 출력 표면 전체의 제어문자 정책으로 통일했습니다. Mermaid CR·LF는 엔티티 코드(#13;·#10;), text는 가시 이스케이프, GH는 C0·DEL·C1·U+2028/9·bidi까지 퍼센트 인코딩, DOT는 CR 대칭 이스케이프.
• SARIF artifact uri의 조용한 손상·오귀속을 수정했습니다(back\slash.dart → back/slash.dart, %41.dart → A.dart였던 것이 세그먼트별 인코딩으로 무손실).
• analyzer/yaml 내부에서 새는 Error 계열이 스택트레이스(경로 반향)와 미문서화 종료 코드 255로 끝나던 것을 CLI 경계에서 계약된 실패(2)로 수습합니다. bridges의 제어문자 거부와 git 비-UTF8 출력도 원인에 맞는 진단으로 귀인됩니다.
• 분석 캐시 키가 표준 5 디렉터리 밖의 루트 안 .dart(예: tool/) 변경을 놓쳐 낡은 해석을 재사용하던 stale hit을 차단했습니다(루트 전체 열거, .fvm 등 숨김 디렉터리는 가지치기). SECURITY.md에 심볼릭 링크 유입 채널을 문서화했습니다.

정확성

• --since·affected의 Git 변경 매칭이 심볼릭 링크 소스에 대해 양방향이 됐습니다(링크 파일 변경과 링크 대상 변경 모두).
• entry_points를 선언한 dartograph.yaml은 entry-points: main retention roots narrowed to N ... 한계를 보고합니다 — 설정이 보존을 좁혔다는 사실이 출력에 남습니다.
• dead --format json에 report 분류 필드(dead/test-only), github-actions에 baseline 억제 notice(억제 > 0일 때만), graph --format json 노드에 조건부 isEnumConstant: true가 추가됐습니다.
• SARIF 파일 finding이 1:1 region을 발명하지 않습니다(region은 선택 요소).
• generated-code-staleness 한계가 mtime 관측임(=선언된 결정성 예외)을 문서화했습니다.

0.4.0 대비 출력 바이트가 바뀌는 지점 (정상 입력 기준)

• dead --format json: report 필드 추가(항상).
• graph --format json: enum 상수 노드에만 isEnumConstant: true 추가.
• github-actions: baseline 억제 > 0일 때만 notice 줄 추가.
• entry_points 설정 저장소만: 새 limitation 문자열 추가.
• SARIF: 파일 finding의 region 제거(오정보였으므로 보존 대상 아님).
• 병적 입력(개행·제어문자·역슬래시 파일명)에서만: Mermaid/text/GH/SARIF 위escape. 그 외 정상 경로는 전 표면 byte-for-byte 불변(기존 골든 테스트 무수정 통과가 증거).

검증

244 테스트, 라인 커버리지 95.9%, 오탐 코퍼스 양방향, CLI 계약 55케이스, 두 SDK(3.11.0/3.13.3) CI. 캐시 identity에 toolVersion이 포함되어 0.4.0 캐시는 자동으로 한 번 재분석됩니다.

분석 한계는 파일 단위 관측이며 완전성이나 삭제 안전성을 보증하지 않습니다.

dartograph 0.4.0

0.4.0

• affected <git-ref> <package-root>: Git 기준점 이후 변경된 라이브러리와 그에 전이적으로 의존하는 라이브러리를 답합니다. 각 피영향 라이브러리에는 가장 가까운 변경 라이브러리까지의 최단 의존 사슬 path와 depth 근거가 붙습니다(라이브러리 수준 관측).
• graph --format html: 외부 CDN·스크립트·폰트 참조가 전혀 없는 단일 자기완결 파일입니다. 네트워크가 막힌 사내망·CI 아티팩트에서도 열리며 캔버스 힘 기반 배치·검색·팬·줌으로 렌더링됩니다. 400정점을 넘으면 연결이 많은 정점부터 남기고 truncatedFrom과 페이지 알림으로 정직하게 보고합니다(전체 그래프는 --format dot).
• graph --level file|type|symbol·--collapse <n>: 그릴 해상도를 고릅니다. file은 선언을 소속 라이브러리로, type은 멤버를 최상위 선언으로 접고, symbol(기본)은 기존 출력을 byte-for-byte 보존합니다. --collapse는 파일 수준 그래프를 경로 앞 n세그먼트 폴더로 요약합니다.
• // dartograph:ignore 인라인 주석: 주석이 위에 오는 선언의 dead 보고를 억제합니다(retentionReason: inlineIgnore). 같은 줄 꼬리 주석은 다음 선언의 억제로 해석되지 않고, 산문의 마커 언급은 오발하지 않습니다. 억제된 선언은 보존 루트라 참조하는 것도 보고에서 함께 사라집니다 — 단일 finding 억제는 baseline을 쓰십시오.
• dead --report-test-only: 테스트에서만 도달되는 프로덕션 선언을 관찰합니다("테스트가 유일한 호출자" 관측, info 심각도 — finding이 있어도 종료 코드 0).
• cycles --explain <id>·rules --explain <id>: 한 정점이 참여하는 순환과 breakCandidate, 레이어 배치와 matchedPattern·matchedCandidate 근거를 JSON으로 답합니다. 그래프에 없는 ID는 known: false와 종료 코드 64입니다.
• query --depth <n>·--limit <n>: 사용 관계를 n단계 BFS로 따라가며 이웃별 depth와 간선 종류 전부를 보고합니다. --limit으로 생략하면 해당 방향 truncated가 서고 생략된 이웃은 더 확장하지 않습니다(좁은 파괴적 변경: 재귀처럼 자기 자신으로 향하는 사용 간선은 모든 depth에서 자기 자신의 이웃에서 제외됩니다 — 옛 1-hop은 포함했습니다).
• 사용 중인 operator 선언이 dead로 보고되던 오탐을 수정했습니다. 연산자 구문(a + b·a[i]·-a·a++·m[i] += v)이 클래스·extension type 모두에서 사용 간선으로 기록됩니다.
• 입력 오류 메시지를 원인별로 구분했습니다: baseline 부재, rules --config 실패, baseline --write 쓰기 실패를 "unable to index the package"로 답하지 않습니다.
• Mermaid 출력이 자체 노드 ID의 <·>·&·"·\·#를 HTML 엔티티 코드로 escape합니다 — 따옴표 포함 파일명이 라벨 구조를 깨지 않습니다.
• 퍼센트 인코딩된 파일명의 dead file finding이 파일 수준 한계를 유지합니다.

분석 한계는 파일 단위 관측이며 완전성이나 삭제 안전성을 보증하지 않습니다. affected의 영향 반경은 라이브러리 수준이라 나열되지 않은 선언의 무영향 증명이 아닙니다. html 그래프의 400정점 초과 truncation은 페이지에 알림이 남습니다. bridge 심볼은 어휘적 이름이며 컴파일러 USR를 생성하지 않습니다.

dartograph 0.3.0

0.3.0

• dartograph.yaml의 entry_points: 실제 build target을 선언해 main 보존 루트를 좁힙니다. 없으면 기본 보수 정책을 유지하고, 빈 문서는 기본 정책으로 봅니다.
• .values로만 소비되는 enum 상수의 미도달 오탐을 수정했습니다. enum이 도달 가능하면 그 상수도 보존하고 explain은 retained by its reachable enum 근거와 enum까지의 경로를 냅니다. enum 자체가 미도달이면 상수도 계속 보고합니다.
• Flutter 채널 사실 추출을 보강했습니다: 선언 본문에서 채널이 사용처보다 뒤에 선언돼도 method-invoke 사실을 누락하지 않고, MethodChannel('')처럼 빈 이름은 그 사실만 건너뛰고 empty-bridge-names 한계로 집계합니다(제어 문자는 계속 전면 거부).
• dead --since가 diff.relative=true와 하위 패키지에서 변경 파일을 놓치던 문제를 수정했습니다.
• dead --explain이 멤버로 보존된 컨테이너를 미도달로 단정하던 문제를 수정해 retained by a reachable member 근거와 witness를 냅니다.
• 심볼릭 링크로 연결된 Dart 소스를 분석 캐시 입력과 bridge 스캔에 포함했습니다.
• 옵션 모양(-로 시작)의 값을 경로로 받던 문제를 usage 오류(64)로 거부합니다(좁은 파괴적 변경: ./-name으로 우회, bridges는 --도 유지).

분석 한계는 파일 단위 관측이며 완전성이나 삭제 안전성을 보증하지 않습니다. enum 상수 보존은 도달 가능 enum에 대해 보수적으로 적용됩니다. bridge 심볼은 어휘적 이름이며 컴파일러 USR을 생성하지 않습니다.

dartograph 0.2.0

0.2.0

• query --batch: 여러 심볼의 질의가 색인·도달성·baseline 계산을 공유합니다.
• compare: 준비된 두 checkout의 그래프 변화와 이전 도달 경로, 제거된 참조·루트를 설명합니다.
• 분석 오류·미해석 호출·조건부 구성의 소스별 한계를 finding에 연결합니다.
• bridge fact에 지원되는 Dart 선언 이름을 추가해 isthmus의 양방향 근거에 보존합니다.
• 소스 변형 회귀 평가, batch 벤치마크, isthmus 왕복 검증 도구를 추가했습니다.

분석 한계는 파일 단위 관측이며 완전성이나 삭제 안전성을 보증하지 않습니다. 비교에는 같은 프로젝트의 의존성·SDK를 맞춘 checkout이 필요합니다. bridge 심볼은 어휘적 이름이며 컴파일러 USR을 생성하지 않습니다.

설치: dart pub global activate dartograph 0.2.0

dartograph 0.1.1

0.1.1

• isthmus GRAPH-EXCHANGE v1에 맞춘 UTC 밀리초 생성 시각과 UTF-8 byte 위치
• Flutter services import provenance와 어휘 범위를 따르는 MethodChannel 추출
• cascade와 invokeListMethod/invokeMapMethod, 동적 이름 fact와 미귀속·잘못된 호출 limitation 보강
• EventChannel·BasicMessageChannel, 조건부 import, re-export를 거짓 사실 대신 limitation으로 보고
• Flutter services re-export를 거친 사용은 추측하지 않고 문서화된 누락 방향으로 보존
• explain의 미발견·파일 근거, analyzer 신원·생성 코드·중첩 의존 캐시 판정 보강
• 잘못된 CLI 호출과 Git 실패를 구분하고 옵션 모양의 skill 경로를 거부

dartograph 0.1.0

Changelog

0.1.0

• Dart analyzer 14.3.0 기반의 결정적 심볼·파일 의존성 그래프
• 근거와 한계를 포함하는 dead, query, cycles, rules, metrics
• DOT, Mermaid, JSON, text, GitHub Actions, SARIF 출력
• baseline과 Git 변경 범위를 조합하는 --since
• 내용·분석기 신원 기반의 손상 허용 영속 사실 캐시
• package barrel 공개 API, 다중 main, override, 생성 코드, 테스트, 플러그인 보존 규칙
• Flutter 플랫폼 채널 교환 사실을 내보내는 bridges
• 에이전트용 안전 지침을 출력·설치하는 skill
• 종료 코드 0/1/2/64, 오탐 코퍼스, 90% 라인 커버리지 게이트
• 대형 프로젝트의 보존 루트 근거를 count·20개 sample·truncated 표시로 제한

dartograph는 MIT 라이선스로 상업적 사용을 포함해 영구 무료이며, 삭제 판정이나
자동 삭제 기능을 제공하지 않는다.