@tienne/gestalt 0.72.7 → 0.72.9

package/dist/src/explain/audience.js

@@ -0,0 +1,121 @@
+/**
+ * 설명 대상 프리셋.
+ *
+ * 여섯 값이 용어 허용치와 문장 길이, 원문 핵심어를 얼마나 남겨야 하는지, 비유가 필요한지,
+ * 어미를 무엇으로 끝낼지를 한꺼번에 정한다. 사람이 읽는 기준은
+ * `plugin/role-agents/explainer/references/audience.md`가 말로 정하고 숫자는 이 파일이 갖는다.
+ * 두 곳에 같은 숫자를 적으면 갈라지므로 문서는 방향을, 코드는 값을 든다.
+ *
+ * 임계값이 프리셋마다 다른 이유는 설명이 잘될수록 원문에서 멀어지기 때문이다. 같은 잣대를
+ * 들이대면 `outsider`용 좋은 설명이 `peer` 기준으로는 내용을 버린 글이 된다.
+ */
+export const AUDIENCES = [
+    'nontech',
+    'junior',
+    'peer',
+    'manager',
+    'exec',
+    'outsider',
+];
+/**
+ * 대상을 안 밝히면 동료 개발자로 본다.
+ *
+ * 개발 레포 안에서 `outsider`를 기본으로 잡으면 옆자리 개발자에게 일상 비유를 늘어놓는
+ * 글이 나간다. 반대 방향 실수가 훨씬 싸다.
+ */
+export const DEFAULT_AUDIENCE = 'peer';
+/** 원문에서 핵심어로 볼 상위 몇 개 */
+export const CORE_TERM_COUNT = 5;
+/**
+ * 숫자를 고를 때 쓴 기준.
+ *
+ * 이 값들은 audience.md 의 프리셋 표에서 옮겨온 게 아니다. 그 표는 용어와 비유, 깊이를
+ * 말로 정하고 숫자는 여기서 처음 정해진다 — 두 곳에 같은 숫자를 적으면 갈라지므로
+ * 문서는 방향을, 코드는 값을 갖는다. 값을 바꿀 때 대조할 곳은 아래 근거지 문서가 아니다.
+ *
+ * **jargon** — nontech 과 exec 는 어절 200개에 풀이 없는 용어가 하나 나오면 경고(0.005)다.
+ * 그보다 잦으면 풀이를 빠뜨린 것이다. outsider 는 그보다 엄격해 하나만 나와도 바로
+ * 경고(warn 0)다 — 룰북이 그 대상에게는 우회할 수 없으면 그 얘기를 빼라고 적어서다.
+ * peer 는 반대로 거의 안 걸려야 한다 — 재보면 동료용 짧은 문장 하나에 용어 셋이 30%
+ * 근처라 그 위(0.35)에 둔다.
+ *
+ * **sentence** — 기준은 peer 의 70자다. 한글 산문에서 그쯤이면 한 번에 읽히는 끝이다.
+ * outsider 는 그 절반(35)이고 나머지는 사이에 둔다.
+ *
+ * **coverage** — 용어를 허용한 대상만 잰다. 핵심어를 다섯 개 잡으므로 0.6 은 셋, 0.8 은
+ * 넷이다. peer 는 넷을 요구하고 manager 는 절반이면 된다. 나머지 셋은 아래 CoverageRule
+ * 주석대로 축을 끈다.
+ */
+export const PRESETS = {
+    nontech: {
+        audience: 'nontech',
+        who: '기획, 디자인, 마케팅 동료',
+        jargon: { warn: 0.005, abort: 0.02 },
+        sentence: { warn: 45, abort: 60 },
+        coverage: 'off',
+        analogy: 'required',
+        register: 'polite',
+    },
+    junior: {
+        audience: 'junior',
+        who: '주니어 개발자',
+        jargon: { warn: 0.06, abort: 0.12 },
+        sentence: { warn: 60, abort: 80 },
+        coverage: { warn: 0.7, abort: 0.5 },
+        analogy: 'recommended',
+        register: 'polite',
+    },
+    peer: {
+        audience: 'peer',
+        who: '동료 개발자',
+        jargon: { warn: 0.35, abort: 0.5 },
+        sentence: { warn: 70, abort: 95 },
+        coverage: { warn: 0.8, abort: 0.6 },
+        analogy: 'off',
+        register: 'polite',
+    },
+    manager: {
+        audience: 'manager',
+        who: '관리자',
+        jargon: { warn: 0.02, abort: 0.05 },
+        sentence: { warn: 55, abort: 75 },
+        coverage: { warn: 0.5, abort: 0.3 },
+        analogy: 'off',
+        register: 'formal',
+    },
+    exec: {
+        audience: 'exec',
+        who: '경영진',
+        jargon: { warn: 0.005, abort: 0.02 },
+        sentence: { warn: 50, abort: 70 },
+        coverage: 'off',
+        analogy: 'off',
+        register: 'formal',
+    },
+    outsider: {
+        audience: 'outsider',
+        who: '사외 비전문가, 가족',
+        jargon: { warn: 0, abort: 0.01 },
+        sentence: { warn: 35, abort: 50 },
+        coverage: 'off',
+        analogy: 'required',
+        register: 'polite',
+    },
+};
+export function isAudience(value) {
+    return AUDIENCES.includes(value);
+}
+/**
+ * 값이 없으면 기본값, 모르는 값이면 undefined. 종료 코드는 부르는 쪽이 정한다.
+ *
+ * 빈 문자열도 안 준 것으로 본다. commander 가 `--audience` 를 값 없이 받으면 그 꼴로 온다.
+ */
+export function parseAudience(value) {
+    if (value === undefined || value === '')
+        return DEFAULT_AUDIENCE;
+    return isAudience(value) ? value : undefined;
+}
+export function presetOf(audience) {
+    return PRESETS[audience];
+}
+//# sourceMappingURL=audience.js.map

package/dist/src/explain/audience.js.map

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

package/dist/src/explain/check.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 설명이 그 대상에게 읽히는 글인지 코드가 판단하는 검사.
+ *
+ * humanize-check 와 판정 구조만 같고 재는 것은 반대다. 거기는 의미가 보존됐는지를 보고
+ * 원문을 절반 넘게 버리면 채택 금지다. 설명은 원문을 많이 버려야 성공이라 그 검사를 그대로
+ * 쓰면 잘된 설명일수록 막힌다. 그래서 축을 새로 잡았다 — 용어, 문장 길이, 핵심어 잔존,
+ * 비유, 어미, 사실 정확도.
+ *
+ * 여섯 중 다섯이 결정론이다. LLM 없이 돌고 같은 입력에 같은 점수가 나온다. 심판 모델은
+ * 사실이 틀렸는지 하나만 본다 — 그건 코드가 못 재는 자리라서다.
+ */
+import { EXIT_CODE, MAX_ATTEMPTS, type Decision, type NextAction, type Verdict } from '../humanize/check.js';
+import type { LLMAdapter } from '../llm/types.js';
+import { type Audience } from './audience.js';
+import { type Grounding } from './grounding.js';
+export { EXIT_CODE, MAX_ATTEMPTS, type Decision, type NextAction, type Verdict };
+export type ExplainAxis = 'jargon' | 'length' | 'grounding' | 'coverage' | 'analogy' | 'register' | 'accuracy';
+/** 심판 모델 없이 도는 축. `--judge` 를 안 켜도 검사가 성립한다는 근거다 */
+export declare const DETERMINISTIC_AXES: readonly ExplainAxis[];
+export interface AxisResult {
+    axis: ExplainAxis;
+    verdict: Verdict;
+    detail: string;
+    evidence?: string[];
+}
+export interface ExplainMetrics {
+    words: number;
+    sentences: number;
+    avgSentenceLength: number;
+    /** 풀이 없이 남은 용어 출현 수를 어절 수로 나눈 값 */
+    jargonDensity: number;
+    unglossed: number;
+    glossed: number;
+    coverage: number;
+    coreTerms: string[];
+    coveredTerms: string[];
+    /** 원문에서 뽑은 전문용어 후보가 상한에서 잘렸나 */
+    termsTruncated: boolean;
+    grounding: Grounding;
+    analogyMarkers: string[];
+    register: RegisterStats;
+}
+export interface ExplainReport {
+    audience: Audience;
+    verdict: Verdict;
+    exitCode: number;
+    metrics: ExplainMetrics;
+    axes: AxisResult[];
+}
+export interface ExplainCheckOptions {
+    audience?: Audience;
+}
+export interface RegisterStats {
+    polite: number;
+    formal: number;
+    plain: number;
+}
+/**
+ * 어미를 갈래별로 센다.
+ *
+ * 인용줄을 뺀 산문을 따로 받는 건 남의 말투가 딸려오면 섞임으로 오판하기 때문이다.
+ * 그 산문을 만드는 일은 부르는 쪽이 한다 — runExplainCheck 가 같은 필터링을 두 번 태우지
+ * 않으려고 미리 만들어 넘긴다. 인자를 안 주면 여기서 만든다.
+ */
+export declare function registerStats(text: string, prose?: string): RegisterStats;
+export declare function runExplainCheck(source: string, explanation: string, options?: ExplainCheckOptions): ExplainReport;
+/** 심판 축을 얹고 판정을 다시 낸다. 결정론 축은 그대로 둔다 */
+export declare function withAxis(report: ExplainReport, axis: AxisResult): ExplainReport;
+export interface JudgeInput {
+    source: string;
+    explanation: string;
+    audience: Audience;
+}
+/**
+ * 사실 정확도만 심판 모델에게 묻는다.
+ *
+ * 어댑터를 인자로 받아 이 파일이 설정을 안 읽게 막는다. 결정론 축은 파일만 있으면 돌아야
+ * 하는데 설정을 여기서 읽으면 그 조건이 깨진다.
+ */
+export declare function judgeAccuracy(adapter: LLMAdapter, input: JudgeInput): Promise<AxisResult>;
+export declare function decide(report: ExplainReport, attempt?: number, maxAttempts?: number): Decision;
+export declare function formatExplainReport(report: ExplainReport, attempt?: number): string;
+//# sourceMappingURL=check.d.ts.map

package/dist/src/explain/check.d.ts.map

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