@tienne/gestalt 0.88.0 → 0.89.0

package/dist/src/architecture/doc-stale.d.ts

@@ -0,0 +1,32 @@
+import type { ArchitectureIr } from './types.js';
+import type { ScannedDoc } from './doc-scan.js';
+export interface ChangedFile {
+    /** 기술 IR의 repo id나 레포 이름, 또는 문서가 적은 레포 이름 */
+    repo: string;
+    path: string;
+}
+export interface StaleReason {
+    /** code-ref는 문서가 직접 가리킨 파일, node는 문서가 설명하는 기술 노드의 근거 파일이 바뀌었다 */
+    kind: 'code-ref' | 'node';
+    file: string;
+    node?: string;
+    line?: number;
+}
+export interface StaleDoc {
+    /** `<repoId>/<path>` */
+    doc: string;
+    title?: string;
+    reasons: StaleReason[];
+}
+export interface StaleDocsOptions {
+    /** 문서가 적은 레포 이름 → 기술 IR의 repo id */
+    repoAliases?: Record<string, string>;
+    /** link_docs가 쓴 knowledge-link IR. 없으면 문서가 직접 가리킨 파일만 본다 */
+    linkIr?: ArchitectureIr;
+}
+/**
+ * 바뀐 파일 목록으로 손봐야 할 문서를 고른다. 문서가 직접 가리킨 파일이 바뀌었거나,
+ * 문서가 설명한다고 이어진 기술 노드의 근거 파일이 바뀐 문서다
+ */
+export declare function findStaleDocs(scanned: readonly ScannedDoc[], changed: readonly ChangedFile[], options?: StaleDocsOptions): StaleDoc[];
+//# sourceMappingURL=doc-stale.d.ts.map

package/dist/src/architecture/doc-stale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-stale.d.ts","sourceRoot":"","sources":["../../../src/architecture/doc-stale.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,QAAQ;IACvB,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,4DAA4D;IAC5D,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAMD;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,OAAO,GAAE,gBAAqB,GAC7B,QAAQ,EAAE,CAqDZ"}

package/dist/src/architecture/doc-stale.js

@@ -0,0 +1,60 @@
+import { splitCodeLocation } from './doc-link.js';
+/** 근거가 폴더를 가리켰으면 그 아래 파일이 바뀐 것도 문서에 닿는다 */
+const covers = (ref, changed) => ref === changed || changed.startsWith(ref.endsWith('/') ? ref : `${ref}/`);
+/**
+ * 바뀐 파일 목록으로 손봐야 할 문서를 고른다. 문서가 직접 가리킨 파일이 바뀌었거나,
+ * 문서가 설명한다고 이어진 기술 노드의 근거 파일이 바뀐 문서다
+ */
+export function findStaleDocs(scanned, changed, options = {}) {
+    const ir = options.linkIr;
+    const aliases = options.repoAliases ?? {};
+    // 레포 이름과 id를 모두 id 하나로 모아 같은 레포를 다르게 불러도 맞게 한다
+    const canon = (name) => aliases[name] ?? ir?.repos.find((r) => r.name === name || r.id === name)?.id ?? name;
+    const changes = changed.map((c) => ({ repo: canon(c.repo), path: c.path.replace(/^\.?\//, '') }));
+    const hit = (repo, path) => changes.find((c) => c.repo === canon(repo) && covers(path, c.path))?.path;
+    const out = new Map();
+    const add = (key, title, reason) => {
+        const cur = out.get(key) ?? {
+            doc: key,
+            ...(title !== undefined ? { title } : {}),
+            reasons: [],
+        };
+        const dup = cur.reasons.some((r) => r.kind === reason.kind && r.file === reason.file && r.node === reason.node);
+        if (!dup)
+            cur.reasons.push(reason);
+        out.set(key, cur);
+    };
+    for (const d of scanned) {
+        for (const ref of d.codeRefs) {
+            const file = hit(ref.repo, ref.path);
+            if (file !== undefined)
+                add(`${d.repoId}/${d.path}`, d.title, { kind: 'code-ref', file, line: ref.line });
+        }
+    }
+    if (ir !== undefined) {
+        const changedByNode = new Map();
+        for (const n of ir.nodes) {
+            for (const e of n.evidence) {
+                if (e.type !== 'code')
+                    continue;
+                const loc = splitCodeLocation(e.location);
+                const file = loc && hit(loc.repo, loc.path);
+                if (file !== undefined && !changedByNode.has(n.id))
+                    changedByNode.set(n.id, file);
+            }
+        }
+        const byId = new Map(ir.nodes.map((n) => [n.id, n]));
+        for (const e of ir.edges) {
+            if (e.kind !== 'describes')
+                continue;
+            const file = changedByNode.get(e.to);
+            const src = byId.get(e.from);
+            if (file === undefined || src?.repo === undefined || src.doc === undefined)
+                continue;
+            const key = `${src.repo}/${src.doc.path.replace(/#.*$/, '')}`;
+            add(key, src.displayName, { kind: 'node', file, node: e.to });
+        }
+    }
+    return [...out.values()].sort((a, b) => (a.doc < b.doc ? -1 : 1));
+}
+//# sourceMappingURL=doc-stale.js.map

package/dist/src/architecture/doc-stale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-stale.js","sourceRoot":"","sources":["../../../src/architecture/doc-stale.ts"],"names":[],"mappings":"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"}

package/dist/src/architecture/drilldown.d.ts

@@ -0,0 +1,51 @@
+import { type LayoutResult } from './layout.js';
+import { type FlowLevel } from './flow-layout.js';
+import type { EdgeKind, LineStyle } from './types.js';
+import type { ValidatedIr } from './validator.js';
+export type DrillLevelKind = 'root' | 'service' | 'app' | 'server' | 'feature' | 'group';
+/**
+ * 레벨에 그리는 선. 세부 엣지를 그대로 옮긴 것이면 count가 1이고 kind가 원래 엣지 kind다.
+ * contains는 서비스 카드에서 그 안 기능 영역으로 가는 포함 선이고 IR 엣지가 아니라 parent에서 나온다
+ */
+export interface DrillEdge {
+    id: string;
+    from: string;
+    to: string;
+    kind: EdgeKind | 'bundle' | 'contains';
+    count: number;
+    memberEdgeIds: string[];
+    lineStyle: LineStyle;
+    /** 묶음 안에 코드 근거와 문서나 사용자 근거가 섞였을 때만 붙는다. memberEdgeIds 중 점선인 고리 수다 */
+    inferred?: number;
+}
+export interface DrillLevel {
+    /** `root`, `service:<id>`, `app:<id>`, `server:<id>`, `feature:<id>`, `group:<id>` */
+    id: string;
+    kind: DrillLevelKind;
+    focusId?: string;
+    title: string;
+    /** root부터 이 레벨까지의 레벨 id. 빵부스러기가 이 순서로 그린다 */
+    trail: string[];
+    nodeIds: string[];
+    edges: DrillEdge[];
+    layout: LayoutResult;
+}
+export interface Drilldown {
+    /** root가 맨 앞이고 나머지는 id 순이다 */
+    levels: DrillLevel[];
+    /** 노드 id → 그 노드를 눌러 들어갈 레벨 id */
+    enter: Record<string, string>;
+    /** 도메인 흐름 레벨. 노드 그래프가 아니라 행위자 줄 격자라 levels와 따로 싣는다 */
+    flows: FlowLevel[];
+}
+export declare const ROOT_LEVEL_ID = "root";
+/** service 노드가 하나라도 그려지면 드릴다운으로 그린다 */
+export declare function shouldDrillDown(validated: ValidatedIr): boolean;
+/**
+ * 검증된 IR에서 드릴다운 레벨과 묶음 엣지를 계산하고 레벨마다 elkjs 좌표를 미리 낸다.
+ * 정렬은 전부 id 기준이라 같은 입력이면 같은 결과가 나온다.
+ */
+/** 서비스 id → 그린 흐름 수. 카드 배지 폭과 글자가 같은 수를 써야 한다 */
+export declare function flowCountByService(flows: readonly FlowLevel[]): Record<string, number>;
+export declare function computeDrilldown(validated: ValidatedIr): Promise<Drilldown>;
+//# sourceMappingURL=drilldown.d.ts.map

package/dist/src/architecture/drilldown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drilldown.d.ts","sourceRoot":"","sources":["../../../src/architecture/drilldown.ts"],"names":[],"mappings":"AAAA,OAAO,EAiBL,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAIrE,OAAO,KAAK,EAAsC,QAAQ,EAAE,SAAS,EAAY,MAAM,YAAY,CAAC;AAEpG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEzF;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,SAAS,CAAC;IACrB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,sFAAsF;IACtF,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,8BAA8B;IAC9B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,sDAAsD;IACtD,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,aAAa,SAAS,CAAC;AA6kCpC,uCAAuC;AACvC,wBAAgB,eAAe,CAAC,SAAS,EAAE,WAAW,GAAG,OAAO,CAgB/D;AAED;;;GAGG;AACH,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAItF;AAED,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAuJjF"}