@wooojin/forgen 0.1.0

package/dist/engine/solution-format.js

@@ -0,0 +1,432 @@
+import yaml from 'js-yaml';
+export const DEFAULT_EVIDENCE = {
+    injected: 0, reflected: 0, negative: 0, sessions: 0, reExtracted: 0,
+};
+const VALID_STATUSES = ['experiment', 'candidate', 'verified', 'mature', 'retired'];
+const VALID_TYPES = ['pattern', 'solution', 'decision', 'troubleshoot', 'anti-pattern', 'convention'];
+// ── Helpers ──
+export function slugify(text) {
+    const slug = text
+        .toLowerCase()
+        .replace(/[^a-z0-9가-힣\s-]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 60);
+    return slug || `untitled-${Date.now()}`;
+}
+// ── Validation ──
+/** Runtime type guard for SolutionFrontmatter */
+export function validateFrontmatter(fm) {
+    if (fm == null || typeof fm !== 'object')
+        return false;
+    const o = fm;
+    if (typeof o.name !== 'string')
+        return false;
+    if (typeof o.version !== 'number' || o.version <= 0)
+        return false;
+    if (typeof o.status !== 'string' || !VALID_STATUSES.includes(o.status))
+        return false;
+    if (typeof o.confidence !== 'number' || o.confidence < 0 || o.confidence > 1)
+        return false;
+    if (typeof o.type !== 'string' || !VALID_TYPES.includes(o.type))
+        return false;
+    if (o.scope !== 'me' && o.scope !== 'team' && o.scope !== 'project')
+        return false;
+    if (!Array.isArray(o.tags) || !o.tags.every((t) => typeof t === 'string'))
+        return false;
+    if (!Array.isArray(o.identifiers) || !o.identifiers.every((t) => typeof t === 'string'))
+        return false;
+    if (typeof o.created !== 'string')
+        return false;
+    if (typeof o.updated !== 'string')
+        return false;
+    if (o.supersedes !== null && typeof o.supersedes !== 'string')
+        return false;
+    if (o.extractedBy !== 'auto' && o.extractedBy !== 'manual')
+        return false;
+    // evidence
+    if (o.evidence == null || typeof o.evidence !== 'object')
+        return false;
+    const ev = o.evidence;
+    const evFields = ['injected', 'reflected', 'negative', 'sessions', 'reExtracted'];
+    for (const f of evFields) {
+        if (typeof ev[f] !== 'number')
+            return false;
+    }
+    return true;
+}
+// ── Parsing ──
+/** Parse YAML frontmatter from solution file content */
+export function parseFrontmatterOnly(content) {
+    try {
+        const trimmed = content.trimStart();
+        if (!trimmed.startsWith('---'))
+            return null;
+        const endIdx = trimmed.indexOf('---', 3);
+        if (endIdx === -1)
+            return null;
+        const raw = trimmed.slice(3, endIdx);
+        // YAML bomb protection: reject oversized frontmatter
+        if (raw.length > 5000)
+            return null;
+        // YAML anchor abuse protection
+        const anchorCount = (raw.match(/(?<=\s|^)&\w+/g) ?? []).length;
+        if (anchorCount > 3)
+            return null;
+        const parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
+        if (!validateFrontmatter(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse a full V3 solution file into its components */
+export function parseSolutionV3(content) {
+    try {
+        const frontmatter = parseFrontmatterOnly(content);
+        if (!frontmatter)
+            return null;
+        // Extract body after the closing ---
+        const trimmed = content.trimStart();
+        const endIdx = trimmed.indexOf('---', 3);
+        const body = trimmed.slice(endIdx + 3).trim();
+        const contextHeader = '## Context';
+        const contentHeader = '## Content';
+        const ctxIdx = body.indexOf(contextHeader);
+        const cntIdx = body.indexOf(contentHeader);
+        let context = '';
+        let solutionContent = '';
+        if (ctxIdx !== -1 && cntIdx !== -1) {
+            context = body.slice(ctxIdx + contextHeader.length, cntIdx).trim();
+            solutionContent = body.slice(cntIdx + contentHeader.length).trim();
+        }
+        else if (ctxIdx !== -1) {
+            context = body.slice(ctxIdx + contextHeader.length).trim();
+        }
+        else if (cntIdx !== -1) {
+            solutionContent = body.slice(cntIdx + contentHeader.length).trim();
+        }
+        else {
+            // No headers — treat entire body as content
+            solutionContent = body;
+        }
+        return { frontmatter, context, content: solutionContent };
+    }
+    catch {
+        return null;
+    }
+}
+// ── Serialization ──
+/** Serialize a SolutionV3 to a markdown string with YAML frontmatter */
+export function serializeSolutionV3(solution) {
+    const yamlStr = yaml.dump(solution.frontmatter, { lineWidth: -1, quotingType: '"', schema: yaml.JSON_SCHEMA });
+    return `---\n${yamlStr}---\n\n## Context\n${solution.context}\n\n## Content\n${solution.content}\n`;
+}
+// ── Format Detection ──
+/** Check if content is in V3 format (YAML frontmatter) */
+export function isV3Format(content) {
+    return content.trimStart().startsWith('---');
+}
+/** Check if content is in V1 format (# Title + > Type: pattern) */
+export function isV1Format(content) {
+    const lines = content.split('\n');
+    let hasTitle = false;
+    let hasType = false;
+    for (const line of lines) {
+        if (line.startsWith('# '))
+            hasTitle = true;
+        if (line.startsWith('> Type:'))
+            hasType = true;
+        if (hasTitle && hasType)
+            return true;
+    }
+    return false;
+}
+// ── Tag Extraction ──
+/** 한국어 불용어 — 태그로 의미 없는 일반 단어 */
+const KO_STOPWORDS = new Set([
+    // 일반 불용어
+    '적용', '패턴', '모든', '같은', '발견', '다른', '사용', '경우', '위해',
+    '통해', '대한', '이후', '때문', '하는', '있는', '없는', '되는', '관련',
+    '해야', '하고', '있다', '없다', '한다', '이런', '그런', '저런', '매우',
+    '항상', '모두', '각각', '대해', '여러', '시작', '그것', '이것', '저것',
+    '아주', '정말', '너무', '많이', '자주', '가장', '먼저', '이미', '아직',
+    '그냥', '바로', '다시', '함께', '위한', '따라', '부분', '전체', '방법',
+    '내용', '결과', '문제', '시점', '설정', '작업', '확인', '수행', '처리',
+    '기본', '추가', '변경', '제거', '포함', '생성', '실행', '완료', '필요',
+    // 조사/어미/접속사 — Jaccard 분모 희석 방지
+    '에서', '으로', '에게', '에는', '에도', '까지', '부터', '보다', '처럼',
+    '만큼', '대로', '밖에', '뿐만', '이나', '이고', '이면', '이라', '인데',
+    '했는데', '됐는데', '있으면', '없으면', '하면', '되면', '하지', '되지',
+    '하며', '되며', '에서의', '으로의', '라는', '라고', '이라고', '때문에',
+    '아니라', '하지만', '그러나', '그래서', '따라서', '그리고', '그러면',
+    '만약', '비록', '하여', '않고', '않은', '않는', '해서', '해도', '해야',
+    // 일반 동사/형용사 어간 — 의미 없는 고빈도 단어
+    '가능', '상태', '이유', '방지', '의존', '의존성', '즉시', '원칙', '근거',
+    '수정', '제안', '기능', '구현', '구조', '단계', '목적', '상황', '조건',
+    '규칙', '동작', '활성', '비활성', '원래', '현재', '이전', '다음', '최종',
+]);
+/** 영어 불용어 */
+const EN_STOPWORDS = new Set([
+    'the', 'and', 'for', 'that', 'this', 'with', 'from', 'are', 'was',
+    'were', 'been', 'have', 'has', 'had', 'not', 'but', 'all', 'can',
+    'will', 'use', 'used', 'using', 'when', 'each', 'which', 'their',
+    'also', 'into', 'more', 'some', 'than', 'other', 'should', 'would',
+    'could', 'about', 'after', 'before', 'between', 'does', 'only',
+    'across', 'just', 'detected', 'based', 'sessions', 'prompts',
+]);
+/** 한국어 일반 조사/어미 — strip 대상 (긴 것부터 매칭)
+ *
+ * term-matcher에서 재사용 가능하도록 export — 매칭 시점과 추출 시점의 stripping
+ * 규칙을 단일 source of truth로 유지해 한국어 stem 비교 정합성 보장.
+ *
+ * 주의: 이 리스트는 **추출 시점에도 적용**되므로 1글자 suffix를 추가할 때
+ * `집중`→`집`, `시도`→`시` 같은 한자어 명사가 깨지지 않도록 극도로 보수적으로
+ * 유지한다. 동사 활용형(`리팩토링중`, `배포시`)처럼 매칭 전용 suffix가 필요하면
+ * term-matcher의 `KO_VERBAL_SUFFIXES`에 따로 둔다.
+ */
+export const KO_SUFFIXES = [
+    '했습니다', '있습니다', '합니다', '입니다', '됩니다',
+    '에서', '까지', '으로', '하는', '하고', '했다', '된다', '한다',
+    '을', '를', '이', '가', '은', '는', '의', '에', '와', '과', '도', '만', '로',
+];
+export function stripKoSuffix(word) {
+    for (const suffix of KO_SUFFIXES) {
+        if (word.endsWith(suffix) && word.length > suffix.length) {
+            return word.slice(0, -suffix.length);
+        }
+    }
+    return word;
+}
+/** 최대 태그 수 — Jaccard 분모 희석 방지 */
+const MAX_TAGS = 8;
+/**
+ * Extract tags from text.
+ * Korean 2-char words preserved (e.g. "에러", "배포"), stopwords filtered.
+ * English words require 3+ chars, stopwords filtered.
+ * Tags capped at MAX_TAGS, ranked by frequency.
+ *
+ * NOTE on hyphens: this function strips `-` to a space (`api-key` query token
+ * becomes `api` and `key` separately). Solution-side compound tags are
+ * recovered downstream by `expandCompoundTags`, and query-side bigram
+ * recovery is done by `expandQueryBigrams`. Both ship as part of R4-T1
+ * (compound-tag tokenizer fix) — see `docs/plans/2026-04-08-t4-bm25-skip-adr.md`
+ * "Round 4 candidates" section for the rationale. Changing this regex
+ * directly was considered but rejected: it would silently shift the index
+ * representation of every existing solution, requiring an index rebuild and
+ * a fresh `ROUND3_BASELINE` measurement on every downstream PR.
+ */
+export function extractTags(text) {
+    const cleaned = text
+        .toLowerCase()
+        .replace(/[^가-힣a-z0-9\s]/g, ' ');
+    const words = cleaned.split(/\s+/).filter(Boolean);
+    const freq = new Map();
+    for (const w of words) {
+        const isKorean = /[가-힣]/.test(w);
+        if (isKorean && w.length >= 2) {
+            const stem = stripKoSuffix(w);
+            if (stem.length >= 2 && !KO_STOPWORDS.has(stem)) {
+                freq.set(stem, (freq.get(stem) ?? 0) + 1);
+            }
+        }
+        else if (!isKorean && w.length > 2 && !EN_STOPWORDS.has(w)) {
+            freq.set(w, (freq.get(w) ?? 0) + 1);
+        }
+    }
+    // 빈도 높은 순으로 MAX_TAGS개만 반환
+    return [...freq.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, MAX_TAGS)
+        .map(([tag]) => tag);
+}
+// ── Compound-tag expansion (R4-T1) ──
+//
+// The matcher's tag intersection step compares solution.tags directly
+// against the (expanded) query tag set. Hyphenated solution tags like
+// `api-key`, `code-review`, `red-green-refactor` only intersect literal
+// query tokens that contain the hyphen — but `extractTags` strips hyphens
+// from query input, so a query "api keys" produces ['api', 'keys'] and
+// never reaches the compound `api-key` tag via direct intersection. The
+// existing `partialMatches` substring rule catches some of these at half
+// weight, but the half-weight discount + a Jaccard denominator that doesn't
+// know about the compound structure means the right solution still loses
+// to a competitor that has a generic single-word match (`api`,
+// `code`, `function`).
+//
+// R4-T1 fixes this from BOTH sides:
+//   - solution-side: `expandCompoundTags` returns the raw tags PLUS the
+//     hyphen-split parts (≥3 chars each), so `api-key` indexes as
+//     {api-key, api, key}. The compound tag stays in the set so existing
+//     literal hits keep working.
+//   - query-side: `expandQueryBigrams` adds adjacent-token compounds and
+//     a singular-stem variant (`api keys` → +{api-key, apikey, api-keys,
+//     apikeys}), so the compound tag still wins via direct intersection
+//     even after the query lost its hyphen during extraction.
+//
+// Both helpers are intentionally lossless additions on top of the raw
+// tag/token list — callers that pass these into `calculateRelevance` MUST
+// keep the RAW tags for the Jaccard union denominator (otherwise the
+// expanded set inflates the union and silently shifts the score). The
+// `solutionTagsExpanded` option on `calculateRelevance` enforces this
+// separation: matching uses expanded, normalization uses raw.
+/** Minimum length of a hyphen-split part to be kept as an alternative tag. */
+const COMPOUND_PART_MIN_LENGTH = 3;
+/**
+ * Expand a solution tag list with hyphen-split alternatives.
+ *
+ * Each input tag is preserved verbatim, and any tag containing `-` also
+ * contributes its parts (length ≥ 3 each) as additional tags. The output
+ * is deduplicated.
+ *
+ * Examples:
+ *   - `['api-key', 'security']` → `['api-key', 'api', 'key', 'security']`
+ *   - `['code-review', 'quality']` → `['code-review', 'code', 'review', 'quality']`
+ *   - `['n+1', 'database']` → `['n+1', 'database']` (no hyphen, n+1 unchanged)
+ *   - `['red-green-refactor']` → `['red-green-refactor', 'red', 'green', 'refactor']`
+ *   - `['typescript']` → `['typescript']` (no hyphen, no expansion)
+ *
+ * Korean compound tags (`API에러`, `테스트주도개발`) are preserved verbatim
+ * because they contain no `-`. The expansion is intentionally English-
+ * compound-aware only — Korean compound recovery is not in scope for R4-T1
+ * (the existing `term-normalizer` family expansion handles Korean ↔ English
+ * cross-mapping).
+ *
+ * The output ordering is insertion order: original tags first, then split
+ * parts in left-to-right order. Stable across runs (Set + Array dedup).
+ */
+export function expandCompoundTags(tags) {
+    const out = new Set();
+    for (const t of tags) {
+        out.add(t);
+        if (t.includes('-')) {
+            for (const part of t.split('-')) {
+                if (part.length >= COMPOUND_PART_MIN_LENGTH) {
+                    out.add(part);
+                }
+            }
+        }
+    }
+    return [...out];
+}
+/**
+ * Expand a query tag list with adjacent-token bigram alternatives.
+ *
+ * For each adjacent (a, b) pair where both tokens are length ≥ 3, the
+ * function adds:
+ *   - `a-b`   (hyphen-joined form, e.g. `api-key`)
+ *   - `ab`    (concatenated form, e.g. `apikey`)
+ *   - `a-b'`  (singular stem of b, only if b ends in `s` and length > 3)
+ *   - `ab'`   (concatenated singular stem)
+ *
+ * Examples:
+ *   - `['api', 'keys']` → `['api', 'keys', 'api-key', 'apikey', 'api-keys', 'apikeys']`
+ *   - `['code', 'review']` → `['code', 'review', 'code-review', 'codereview']`
+ *   - `['red', 'green', 'refactor']` → `[..., 'red-green', 'redgreen', 'green-refactor', 'greenrefactor']`
+ *
+ * Plural→singular stem is intentionally minimal: only `s`-suffix removal,
+ * no `es`/`ies` handling. The cost-benefit is asymmetric — `apis → api`
+ * is the highest-value case and is handled correctly; `classes → classe`
+ * is wrong but doesn't matter because no solution tag is `classe`.
+ *
+ * Why both `-` and concatenated forms: solution tag conventions vary
+ * across packs (`api-key` vs `apikey`), and this expansion is cheap.
+ * The downstream intersection check is O(M) per solution where M = expanded
+ * query tag count, so even doubling the query tag count is well within
+ * the matcher's hot-path budget for the corpus sizes Forgen targets
+ * (N ≤ 200 solutions).
+ *
+ * Korean tokens (`/[가-힣]/`) are passed through verbatim: bigram
+ * concatenation of Korean compound words is meaningless because the
+ * boundary is lexical, not whitespace-driven (`디버깅` is one word, not
+ * two adjacent tokens). Only ASCII-letter pairs participate.
+ */
+export function expandQueryBigrams(tags) {
+    const out = new Set(tags);
+    for (let i = 0; i < tags.length - 1; i++) {
+        const a = tags[i];
+        const b = tags[i + 1];
+        if (a.length < 3 || b.length < 3)
+            continue;
+        // ASCII-only filter — Korean bigrams are not meaningful (see header).
+        if (!/^[a-z0-9]+$/.test(a) || !/^[a-z0-9]+$/.test(b))
+            continue;
+        out.add(`${a}-${b}`);
+        out.add(`${a}${b}`);
+        if (b.endsWith('s') && b.length > 3) {
+            const bSing = b.slice(0, -1);
+            out.add(`${a}-${bSing}`);
+            out.add(`${a}${bSing}`);
+        }
+    }
+    return [...out];
+}
+// ── Migration ──
+const V1_TYPE_MAP = {
+    solution: 'pattern',
+    rule: 'decision',
+    convention: 'decision',
+    pattern: 'pattern',
+};
+/** Migrate a V1-format solution file to V3 format */
+export function migrateV1toV3(content, filePath) {
+    const lines = content.split('\n');
+    let title = '';
+    let v1Type = '';
+    let scope = 'me';
+    let bodyStartIdx = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!title && line.startsWith('# ')) {
+            title = line.replace(/^#\s+/, '').trim();
+            bodyStartIdx = i + 1;
+        }
+        if (line.startsWith('> Type:')) {
+            v1Type = line.replace('> Type:', '').trim().toLowerCase();
+            bodyStartIdx = Math.max(bodyStartIdx, i + 1);
+        }
+        if (line.startsWith('> Scope:')) {
+            const rawScope = line.replace('> Scope:', '').trim().toLowerCase();
+            scope = rawScope === 'project' ? 'project' : 'me';
+            bodyStartIdx = Math.max(bodyStartIdx, i + 1);
+        }
+    }
+    // Skip remaining metadata lines (> Classification:, > Created:, blank lines right after)
+    while (bodyStartIdx < lines.length) {
+        const l = lines[bodyStartIdx].trim();
+        if (l.startsWith('>') || l === '') {
+            bodyStartIdx++;
+        }
+        else {
+            break;
+        }
+    }
+    const body = lines.slice(bodyStartIdx).join('\n').trim();
+    const today = new Date().toISOString().split('T')[0];
+    const name = slugify(title || filePath);
+    const type = V1_TYPE_MAP[v1Type] ?? 'pattern';
+    const tags = extractTags(`${title} ${body}`);
+    const solution = {
+        frontmatter: {
+            name,
+            version: 1,
+            status: 'candidate',
+            confidence: 0.5,
+            type,
+            scope,
+            tags,
+            identifiers: [],
+            evidence: { ...DEFAULT_EVIDENCE },
+            created: today,
+            updated: today,
+            supersedes: null,
+            extractedBy: 'auto',
+        },
+        context: '',
+        content: body,
+    };
+    return serializeSolutionV3(solution);
+}

package/dist/engine/solution-index.d.ts

@@ -0,0 +1,13 @@
+import type { SolutionIndexEntry } from './solution-format.js';
+export interface SolutionDirConfig {
+    dir: string;
+    scope: 'me' | 'team' | 'project';
+}
+export interface SolutionIndex {
+    entries: SolutionIndexEntry[];
+    directoryMtimes: Record<string, number>;
+    builtAt: number;
+}
+export declare function isIndexStale(index: SolutionIndex): boolean;
+export declare function getOrBuildIndex(dirs: SolutionDirConfig[]): SolutionIndex;
+export declare function resetIndexCache(): void;