@g1cloud/entity-modeler-next 5.0.11 → 5.1.0

package/dist/adapter/diagramAdapter.d.ts

@@ -14,6 +14,11 @@ export interface DiagramMeta {
     schemaVersion?: number;
     /** op 쓰기 롤아웃 게이트(불변식: true ⟹ schemaVersion>=2). v2 && false = read-only 프리즈(B-0-1). */
     opWriteEnabled?: boolean;
+    /**
+     * 문서 단위 「참고 전용」(v2 doc 루트 마커) — 문서 전체가 산출·검증 대상 밖. 엔티티 단위는 논리 모델의
+     * `Entity.referenceOnly` 이고 판정은 **OR** 다(둘 중 하나면 대상 외). v1 은 undefined.
+     */
+    referenceOnly?: boolean;
     /**
      * v2 doc일 때 RevCache 시드(컨테이너 rev + layout/logical version). v1은 undefined.
      * controller가 OpSyncAdapter.seed로 주입(base rev 라이브 캐시 초기화).

package/dist/adapter/persisted.d.ts

@@ -238,6 +238,17 @@ export interface PDiagramV2 {
     schemaVersion: 2;
     /** op 쓰기 롤아웃 게이트. false = read-only 프리즈(B-0-1, 쓰기 kill-switch). */
     opWriteEnabled?: boolean;
+    /**
+     * 문서 단위 「참고 전용」 — 이 문서 전체가 산출·검증 대상이 아니다(이해용 스크래치 자료·테스트 문서).
+     *
+     * ★엔티티 단위는 `Entity.referenceOnly`(논리 모델)이고 이쪽은 **doc 루트 마커**다. 자리가 갈리는 이유:
+     * op 어휘에 모델·문서 레벨 op 이 **하나도 없다**(`opSubject.ts` 인벤토리 실측) ⇒ 논리 모델에 두면 op
+     * 신설 + 호스트 인터프리터 선행 배포가 딸려 온다. 반면 문서 레벨 정책 마커는 이미 이 자리에 산다
+     * (`schemaVersion`·`opWriteEnabled`) ⇒ 호스트 라우트가 토글하고 lib 은 `DiagramMeta` 로 읽는다.
+     *
+     * ⚠️대가 둘(선례 `opWriteEnabled` 와 동일): 변경이 op 이력에 남지 않고, JSON 백업 왕복에 실리지 않는다.
+     */
+    referenceOnly?: boolean;
     /** doc-level optlock(기존 version 계승). */
     version?: number;
     diagramVersion?: string;

package/dist/core/referenceOnly.d.ts

@@ -0,0 +1,50 @@
+import { Association, Entity, LogicalModel, ModelId } from './types';
+/**
+ * 「참고 전용」 축의 단일 출처 — 산출(DDL·코드젠·mermaid)과 검증이 같은 기준으로 대상을 고르게 한다.
+ *
+ * 판정 자체는 한 줄이지만(플래그 하나) 자리를 따로 두는 이유는 **소비처가 넷**이고 그 넷이 기준을 각자
+ * 재기술하면 어긋나기 때문이다 — `entityPackage.ts`·`indexColumnRef.ts` 와 같은 근거다. 실제로 그룹
+ * `excludeDDLGeneration` 은 소비처가 자기 자리에서 각자 판단하다가 산출 경로에서 통째로 누락됐다
+ * (2026-08-24 · 레거시 패리티 회귀 4번째).
+ *
+ * ★**대상에서 뺀다 ≠ 참조를 못 푼다.** 여기 함수들은 *생성·판정 목록*만 좁힌다. 살아남은 요소가 참고 전용
+ * 요소를 참조할 수 있고(임베드 소스·상속 부모·공유 컬럼) 그 해소 맵은 모델 전량을 훑어야 한다 — 좁히면
+ * 산출이 조용히 어긋난다(`ddl.ts` 의 `attrOwner`·`attrCols` 주석과 같은 기준).
+ */
+/** 참고 전용 여부 — 미설정/false 는 대상(기본이 「대상」이다: 신호를 지우는 쪽이 명시적 선택이어야 한다). */
+export declare function isReferenceOnly(e: Entity): boolean;
+/** 참고 전용 엔티티 modelId 집합 — 관계 필터·FK 부모 가드가 반복 순회 없이 공유한다. */
+export declare function referenceOnlyIds(logical: LogicalModel): ReadonlySet<ModelId>;
+/** 산출·판정 대상 엔티티. */
+export declare function targetEntities(logical: LogicalModel): Entity[];
+/**
+ * 산출·판정 대상 관계 — **양 end 가 모두 대상**일 때만.
+ *
+ * 한쪽만 참고 전용인 관계를 남기면 그 관계의 결함(cascade·다중성·nav)이 *대상 쪽 이슈로* 보고되는데
+ * 고칠 지점은 참고 전용 쪽에 있어 「고칠 수 있는 자리를 지목해야 한다」를 위반한다. 반대로 그런 관계가
+ * 존재한다는 사실 자체는 신호 가치가 있다 — 그건 이 필터가 아니라 전용 규칙이 다룰 축이다(잔여 등재).
+ */
+export declare function targetAssociations(logical: LogicalModel, refOnly?: ReadonlySet<ModelId>): Association[];
+/**
+ * 문서 단위 「참고 전용」을 **엔티티 층으로 투영**한다 — doc 루트 마커(`DiagramMeta.referenceOnly`)를
+ * 산출·검증이 이미 보는 그 기준 하나로 내린다.
+ *
+ * ★두 번째 코드 경로를 만들지 않는 것이 요점이다. "문서 플래그면 결과가 빈다"를 소비처마다 따로 쓰면
+ * 그 단락 로직이 엔티티 층 시맨틱과 어긋날 수 있다(모델 레벨 규칙·헤더 방출 등). 투영은 **정의상**
+ * 엔티티 층과 같은 답을 준다.
+ *
+ * 플래그가 꺼져 있으면 **원 객체를 그대로** 돌려주므로(참조 동일) 통상 경로의 추가 비용은 0이다.
+ */
+export declare function applyDocumentReferenceOnly(logical: LogicalModel, docReferenceOnly: boolean | undefined): LogicalModel;
+/**
+ * **실효** 참고 전용 — 엔티티 단위 ∪ 문서 단위. 표시 계층(캔버스)이 쓴다.
+ *
+ * ★산출·검증은 `applyDocumentReferenceOnly` **투영**으로 같은 답을 얻으므로 이 함수를 쓰지 않는다
+ * (모델을 한 번 좁히면 하류 전체가 엔티티 층 기준 하나만 보게 되는 것이 그쪽의 요점이다). 반면 캔버스는
+ * 노드마다 렌더하므로 모델을 좁히는 것이 아니라 **노드별 질의**가 필요하다 — 그래서 축이 둘로 갈리고,
+ * 갈리는 만큼 OR 를 각자 재기술하지 않도록 여기 한 곳에 둔다.
+ *
+ * ⚠️화면이 이 OR 를 안 보면 **거짓말을 한다** — 문서가 참고 전용이라 산출이 0인데 노드가 실선이면
+ * 사용자는 그것들이 산출에 들어간다고 읽는다(이 리포가 반복해 경계해 온 무신호 소실의 표시 축 변형).
+ */
+export declare function effectiveReferenceOnly(e: Entity, docReferenceOnly: boolean | undefined): boolean;

package/dist/core/types.d.ts

@@ -299,6 +299,29 @@ export interface Entity {
     description?: MultiLangText;
     abstractClass?: boolean;
     hasPersonalInfo?: boolean;
+    /**
+     * 참고 전용 — 이 엔티티는 **산출·검증 대상이 아니다**(문서 이해용 스크래치·테스트 초안 등).
+     *
+     * ★그룹 `excludeDDLGeneration`(LogicalGroup)과 **다른 축**이다. 그쪽은 레거시 시맨틱 그대로
+     * 「DDL 만 제외, Java 클래스는 계속 생성」이라(`bluework-im` 이 `EntityJavaSrcGen` 에는 필터 없이 전체를
+     * 넘긴다) 그 그룹의 엔티티도 `@Column(name·length)` 을 방출하고 물리명 충돌은 여전히
+     * `Repeated column in mapping` 으로 실패한다 ⇒ **검증이 유효**하다. 반면 이쪽은 아무것도 만들지
+     * 않으므로 판정 자체가 무의미하다. 두 수단을 겹쳐 쓰지 말 것 — 「타 서비스 소유 테이블」은 전자,
+     * 「우리 산출물이 아닌 자료」는 후자다.
+     *
+     * 실효 범위(단일 출처 `core/referenceOnly.ts`): 검증 **판정 모집단 제외** · DDL·코드젠·mermaid
+     * **산출 제외** · `text`(LLM 입력)는 **유지** — 참고 자료를 읽을 수 있어야 그 문서의 존재 이유가
+     * 성립한다(만드는 표면만 제외, 읽는 표면은 유지).
+     *
+     * ⚠️**판정·생성 목록에서만 빼고 참조 해소는 전량 유지**한다(`ddl.ts` 의 `attrOwner`·`attrCols` 와 같은
+     * 기준) — 살아남은 요소가 이 엔티티를 참조할 수 있고, 그 참조를 못 풀면 산출이 조용히 어긋난다.
+     * 예외는 FK 부모: 참고 전용 부모의 테이블은 방출되지 않으므로 그 FK 는 생략 주석과 함께 뺀다.
+     *
+     * 문서 단위 「참고 전용」은 이 필드가 아니라 **v2 doc 루트 마커**다(`opWriteEnabled` 와 같은 층 —
+     * 호스트 소유). op 어휘에 문서·모델 레벨 op 이 없다는 실측(`opSubject.ts` 인벤토리)이 그 분담의 근거고,
+     * 그래서 이 필드만 기존 `entity.update` 로 흐른다(op 어휘 변화 0 · 호스트 인터프리터 무변경).
+     */
+    referenceOnly?: boolean;
     declarationOfInterfaces?: string[];
     attributes: Attribute[];
     operations?: Operation[];

package/dist/editor/controller.d.ts

@@ -133,6 +133,12 @@ export interface EditorController {
      * 생성 시 editable=false로 연동. full-replace 폴백이 아니라 쓰기 kill-switch.
      */
     opWriteEnabled: Ref<boolean>;
+    /**
+     * 문서 단위 「참고 전용」(v2 doc 루트 마커 — 호스트 소유). true 면 이 문서 전체가 산출·검증 대상 밖이다.
+     * 엔티티 단위 `Entity.referenceOnly` 와 **같은 기준으로 수렴**시킨다(`applyDocumentReferenceOnly` 투영)
+     * — 소비처마다 별도 단락 로직을 두면 엔티티 층 시맨틱과 어긋날 수 있다.
+     */
+    referenceOnlyDocument: Ref<boolean>;
     /**
      * op-mode 활성 여부 — `schemaVersion>=2 && opWriteEnabled`. op emit(B-2)의 게이트로,
      * 레거시 doc(v1)·read-only v2는 false. editable 게이트와 같은 단일 통과점 옆에 둔다(stack은 마커 무지).