@warpgogol/forge 2.8.0 → 2.8.2

package/src/knowledge/parse.ts

@@ -0,0 +1,227 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Tolerant markdown parser for knowledge files — produces ParsedKnowledgeFile with entries, legacy sections, and parse issues (RFC-0660).</purpose>
+<non-goals>
+  <item>Do not validate entry uniqueness or cross-references — that is handled by SKILL-20 in skill-validate.ts.</item>
+  <item>Do not serialize — that is handled by serialize.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0660: initial tolerant parser for structured knowledge entries.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import {
+  knowledgeEntryMetaSchema,
+  type KnowledgeLayer,
+  type KnowledgeEntry,
+  type KnowledgeEntryMeta,
+  type LegacySection,
+  type ParseIssue,
+  type ParsedKnowledgeFile,
+} from "./schema.ts";
+
+const ENTRY_HEADING_PATTERN = /^###\s+(K-\d{4})\s*:\s*(.+)$/;
+const KNOWLEDGE_ENTRY_FENCE = "knowledge-entry";
+const LAYER_COMMENT_PATTERN = /<!--\s*knowledge-layer:\s*(L[012])\s*-->/;
+
+const FILENAME_LAYER_MAP: Record<string, KnowledgeLayer> = {
+  "qa-log.md": "L0",
+  "fix-patterns.md": "L1",
+  "learned-principles.md": "L2",
+};
+
+function detectLayer(content: string, fileName: string): KnowledgeLayer | null {
+  const commentMatch = content.match(LAYER_COMMENT_PATTERN);
+  if (commentMatch) {
+    return commentMatch[1] as KnowledgeLayer;
+  }
+  return FILENAME_LAYER_MAP[fileName] ?? null;
+}
+
+export function parseKnowledgeFile(filePath: string): ParsedKnowledgeFile {
+  let content: string;
+  try {
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    // File read errors (EISDIR, ENOENT, etc.) — return empty result
+    return {
+      path: filePath,
+      layer: null,
+      preamble: "",
+      entries: [],
+      legacySections: [],
+      parseIssues: [],
+      isKnowledgeAdjacent: true,
+    };
+  }
+  const fileName = path.basename(filePath);
+  const lines = content.split(/\r?\n/);
+  const layer = detectLayer(content, fileName);
+
+  const entries: KnowledgeEntry[] = [];
+  const legacySections: LegacySection[] = [];
+  const parseIssues: ParseIssue[] = [];
+
+  let i = 0;
+  let preambleEnd = 0;
+
+  // Find the first entry heading or the first non-preamble content
+  let firstEntryLine = -1;
+  for (let j = 0; j < lines.length; j++) {
+    if (ENTRY_HEADING_PATTERN.test(lines[j])) {
+      firstEntryLine = j;
+      break;
+    }
+  }
+
+  // If no entry headings and no layer declaration, it's a knowledge-adjacent file
+  const isKnowledgeAdjacent = firstEntryLine === -1 && layer === null;
+
+  if (isKnowledgeAdjacent) {
+    return {
+      path: filePath,
+      layer: null,
+      preamble: content,
+      entries: [],
+      legacySections: [],
+      parseIssues: [],
+      isKnowledgeAdjacent: true,
+    };
+  }
+
+  // Preamble is everything before the first entry heading
+  if (firstEntryLine === -1) {
+    // Has layer but no entries — all content is preamble (structured-empty file)
+    return {
+      path: filePath,
+      layer,
+      preamble: content,
+      entries: [],
+      legacySections: [],
+      parseIssues: [],
+      isKnowledgeAdjacent: false,
+    };
+  }
+
+  preambleEnd = firstEntryLine;
+  const preamble = lines.slice(0, preambleEnd).join("\n");
+
+  // Parse entries and legacy sections
+  i = preambleEnd;
+  while (i < lines.length) {
+    const headingMatch = lines[i].match(ENTRY_HEADING_PATTERN);
+
+    if (headingMatch) {
+      const entryId = headingMatch[1];
+      const title = headingMatch[2].trim();
+      const entryLineStart = i + 1; // 1-based
+      i++;
+
+      // Look for fenced knowledge-entry block immediately after heading
+      let meta: KnowledgeEntryMeta | null = null;
+      let metaBlockStart = -1;
+      let _metaBlockEnd = -1;
+
+      // Skip blank lines between heading and fence
+      while (i < lines.length && lines[i].trim() === "") {
+        i++;
+      }
+
+      if (i < lines.length && lines[i].trim().startsWith("```")) {
+        const fenceTag = lines[i].trim().replace(/^```/, "").trim();
+        if (fenceTag === KNOWLEDGE_ENTRY_FENCE) {
+          metaBlockStart = i + 1; // 1-based line after fence start
+          i++;
+          const yamlLines: string[] = [];
+          while (i < lines.length && !lines[i].trim().startsWith("```")) {
+            yamlLines.push(lines[i]);
+            i++;
+          }
+          if (i < lines.length && lines[i].trim().startsWith("```")) {
+            _metaBlockEnd = i + 1; // 1-based fence closing line
+            i++;
+
+            const yamlText = yamlLines.join("\n");
+            try {
+              const raw = parseYaml(yamlText) as Record<string, unknown>;
+              const result = knowledgeEntryMetaSchema.safeParse(raw);
+              if (result.success) {
+                meta = result.data as KnowledgeEntryMeta;
+              } else {
+                for (const issue of result.error.issues) {
+                  parseIssues.push({
+                    line: metaBlockStart,
+                    message: `Entry ${entryId}: ${issue.message}`,
+                    entryId,
+                  });
+                }
+              }
+            } catch (err) {
+              parseIssues.push({
+                line: metaBlockStart,
+                message: `Entry ${entryId}: YAML parse error: ${(err as Error).message}`,
+                entryId,
+              });
+            }
+          } else {
+            parseIssues.push({
+              line: metaBlockStart,
+              message: `Entry ${entryId}: unterminated knowledge-entry fence`,
+              entryId,
+            });
+          }
+        }
+      }
+
+      // Collect body until next entry heading or EOF
+      const bodyLines: string[] = [];
+      while (i < lines.length && !ENTRY_HEADING_PATTERN.test(lines[i])) {
+        bodyLines.push(lines[i]);
+        i++;
+      }
+      const body = bodyLines.join("\n").replace(/\n+$/, "");
+
+      if (meta) {
+        entries.push({
+          meta,
+          title,
+          body,
+          lineStart: entryLineStart,
+        });
+      } else if (metaBlockStart === -1) {
+        // Heading exists but no metadata block followed — it's a legacy section
+        legacySections.push({
+          text: lines.slice(entryLineStart - 1, i).join("\n"),
+          lineStart: entryLineStart,
+        });
+      }
+      // If meta parsing failed, the parse issue is already recorded
+    } else {
+      // Non-entry content — collect as legacy section
+      const legacyStart = i + 1; // 1-based
+      const legacyLines: string[] = [];
+      while (i < lines.length && !ENTRY_HEADING_PATTERN.test(lines[i])) {
+        legacyLines.push(lines[i]);
+        i++;
+      }
+      legacySections.push({
+        text: legacyLines.join("\n"),
+        lineStart: legacyStart,
+      });
+    }
+  }
+
+  return {
+    path: filePath,
+    layer,
+    preamble,
+    entries,
+    legacySections,
+    parseIssues,
+    isKnowledgeAdjacent: false,
+  };
+}

package/src/knowledge/promote.ts

@@ -0,0 +1,156 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Cross-skill duplicate detection and promotion planning for shared knowledge layer (RFC-0663).</purpose>
+<non-goals>
+  <item>Do not read or write files — that is handled by parse.ts/serialize.ts and the distill skill.</item>
+  <item>Do not execute promotions — that is the operator's decision inside fo-knowledge-distill.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0663: initial cross-skill duplicate detection and promotion planning.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ParsedKnowledgeFile, KnowledgeEntry, KnowledgeEntryMeta } from "./schema.ts";
+
+const STOP_WORDS = new Set(["the", "a", "an"]);
+
+const MIN_CONTAINMENT_LENGTH = 20;
+const MIN_CONTAINMENT_RATIO = 0.6;
+
+export interface DuplicatePair {
+  a: { skill: string; entryId: string; title: string };
+  b: { skill: string; entryId: string; title: string };
+  normalizedTitle: string;
+  kind: "exact" | "containment";
+}
+
+export interface PromotionPlan {
+  sharedEntry: KnowledgeEntry;
+  localPointers: Array<{ skill: string; file: string; entryId: string }>;
+}
+
+export function normalizeTitle(title: string): string {
+  let result = title.toLowerCase();
+  result = result.replace(/[^\p{L}\p{N}\s]/gu, " ");
+  result = result.replace(/\s+/g, " ").trim();
+  const words = result.split(" ").filter((w) => w.length > 0 && !STOP_WORDS.has(w));
+  return words.join(" ");
+}
+
+function isExcludedEntry(meta: KnowledgeEntryMeta): boolean {
+  if (meta.status === "stale" || meta.status === "archived") return true;
+  if (meta.promotedTo !== undefined && meta.promotedTo !== null) return true;
+  return false;
+}
+
+function isLinkedPair(metaA: KnowledgeEntryMeta, metaB: KnowledgeEntryMeta): boolean {
+  if (metaA.supersedes && metaB.id && metaA.supersedes.includes(metaB.id)) return true;
+  if (metaB.supersedes && metaA.id && metaB.supersedes.includes(metaA.id)) return true;
+  if (metaA.promotedTo && metaB.id && metaA.promotedTo === `shared/${metaB.id}`) return true;
+  if (metaB.promotedTo && metaA.id && metaB.promotedTo === `shared/${metaA.id}`) return true;
+  return false;
+}
+
+interface ActiveEntry {
+  skill: string;
+  entry: KnowledgeEntry;
+  normalizedTitle: string;
+}
+
+function collectActiveEntries(
+  files: Array<{ skill: string; parsed: ParsedKnowledgeFile }>,
+): ActiveEntry[] {
+  const active: ActiveEntry[] = [];
+  for (const file of files) {
+    if (file.parsed.isKnowledgeAdjacent) continue;
+    if (file.parsed.parseIssues.length > 0) continue;
+    for (const entry of file.parsed.entries) {
+      if (isExcludedEntry(entry.meta)) continue;
+      const normalized = normalizeTitle(entry.title);
+      if (normalized.length === 0) continue;
+      active.push({ skill: file.skill, entry, normalizedTitle: normalized });
+    }
+  }
+  return active;
+}
+
+export function detectDuplicatePrinciples(
+  files: Array<{ skill: string; parsed: ParsedKnowledgeFile }>,
+): DuplicatePair[] {
+  const active = collectActiveEntries(files);
+  const pairs: DuplicatePair[] = [];
+
+  for (let i = 0; i < active.length; i++) {
+    for (let j = i + 1; j < active.length; j++) {
+      const a = active[i];
+      const b = active[j];
+
+      if (isLinkedPair(a.entry.meta, b.entry.meta)) continue;
+
+      if (a.normalizedTitle === b.normalizedTitle) {
+        pairs.push({
+          a: { skill: a.skill, entryId: a.entry.meta.id, title: a.entry.title },
+          b: { skill: b.skill, entryId: b.entry.meta.id, title: b.entry.title },
+          normalizedTitle: a.normalizedTitle,
+          kind: "exact",
+        });
+        continue;
+      }
+
+      const shorter = a.normalizedTitle.length <= b.normalizedTitle.length ? a : b;
+      const longer = a.normalizedTitle.length <= b.normalizedTitle.length ? b : a;
+
+      if (shorter.normalizedTitle.length < MIN_CONTAINMENT_LENGTH) continue;
+      if (shorter.normalizedTitle.length < longer.normalizedTitle.length * MIN_CONTAINMENT_RATIO)
+        continue;
+
+      if (longer.normalizedTitle.includes(shorter.normalizedTitle)) {
+        pairs.push({
+          a: { skill: a.skill, entryId: a.entry.meta.id, title: a.entry.title },
+          b: { skill: b.skill, entryId: b.entry.meta.id, title: b.entry.title },
+          normalizedTitle: shorter.normalizedTitle,
+          kind: "containment",
+        });
+      }
+    }
+  }
+
+  return pairs;
+}
+
+export function planPromotion(
+  sources: Array<{ skill: string; file: string; entry: KnowledgeEntry }>,
+  merged: { title: string; body: string },
+  nextSharedId: string,
+  today: string,
+): PromotionPlan {
+  const totalConfirmations = sources.reduce((sum, s) => sum + (s.entry.meta.confirmations ?? 0), 0);
+
+  const promotedFrom = sources.map((s) => `${s.skill}/${s.entry.meta.id}`);
+
+  const sharedMeta: KnowledgeEntryMeta = {
+    id: nextSharedId,
+    layer: "L2",
+    created: today,
+    lastConfirmedAt: today,
+    confirmations: totalConfirmations,
+    status: "active",
+    promotedFrom,
+  };
+
+  const sharedEntry: KnowledgeEntry = {
+    meta: sharedMeta,
+    title: merged.title,
+    body: merged.body,
+    lineStart: 0,
+  };
+
+  const localPointers = sources.map((s) => ({
+    skill: s.skill,
+    file: s.file,
+    entryId: s.entry.meta.id,
+  }));
+
+  return { sharedEntry, localPointers };
+}

package/src/knowledge/schema.ts

@@ -0,0 +1,112 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Define the Zod metadata schema for knowledge entries with layer-specific refinements (RFC-0660).</purpose>
+<non-goals>
+  <item>Do not parse markdown — that is handled by parse.ts.</item>
+  <item>Do not serialize — that is handled by serialize.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0660: initial knowledge entry metadata schema with L0/L1/L2 layer-specific refinements.</item>
+  <item>RFC-0663: added promotedFrom field for shared-layer provenance tracking.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export type KnowledgeLayer = "L0" | "L1" | "L2";
+export type KnowledgeEntryStatus = "active" | "stale" | "superseded" | "archived";
+
+const ENTRY_ID_PATTERN = /^K-\d{4}$/;
+const PROMOTED_TO_PATTERN = /^shared\/K-\d{4}$/;
+const PROMOTED_FROM_PATTERN = /^[a-z0-9-]+\/K-\d{4}$/;
+
+const baseMetaSchema = z.object({
+  id: z.string().regex(ENTRY_ID_PATTERN, "id must match ^K-\\d{4}$"),
+  layer: z.enum(["L0", "L1", "L2"]),
+  created: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "created must be YYYY-MM-DD"),
+  lastConfirmedAt: z.union([z.string().regex(/^\d{4}-\d{2}-\d{2}$/), z.null()]).optional(),
+  confirmations: z.number().int().min(0).optional(),
+  expiresAt: z.union([z.string().regex(/^\d{4}-\d{2}-\d{2}$/), z.null()]).optional(),
+  supersedes: z.array(z.string().regex(ENTRY_ID_PATTERN)).optional(),
+  promotedTo: z.union([z.string().regex(PROMOTED_TO_PATTERN), z.null()]).optional(),
+  promotedFrom: z.array(z.string().regex(PROMOTED_FROM_PATTERN)).optional(),
+  status: z.enum(["active", "stale", "superseded", "archived"]),
+});
+
+export const knowledgeEntryMetaSchema = baseMetaSchema.superRefine((data, ctx) => {
+  if (data.layer === "L0" || data.layer === "L1") {
+    if (data.confirmations !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `confirmations is forbidden on ${data.layer} entries`,
+        path: ["confirmations"],
+      });
+    }
+    if (data.lastConfirmedAt !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `lastConfirmedAt is forbidden on ${data.layer} entries`,
+        path: ["lastConfirmedAt"],
+      });
+    }
+  }
+
+  if (data.layer === "L2") {
+    if (data.confirmations === undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "confirmations is required on L2 entries",
+        path: ["confirmations"],
+      });
+    }
+    if (data.lastConfirmedAt === undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "lastConfirmedAt is required on L2 entries",
+        path: ["lastConfirmedAt"],
+      });
+    }
+  }
+});
+
+export interface KnowledgeEntryMeta {
+  id: string;
+  layer: KnowledgeLayer;
+  created: string;
+  lastConfirmedAt?: string | null;
+  confirmations?: number;
+  expiresAt?: string | null;
+  supersedes?: string[];
+  promotedTo?: string | null;
+  promotedFrom?: string[];
+  status: KnowledgeEntryStatus;
+}
+
+export interface KnowledgeEntry {
+  meta: KnowledgeEntryMeta;
+  title: string;
+  body: string;
+  lineStart: number;
+}
+
+export interface LegacySection {
+  text: string;
+  lineStart: number;
+}
+
+export interface ParseIssue {
+  line: number;
+  message: string;
+  entryId?: string;
+}
+
+export interface ParsedKnowledgeFile {
+  path: string;
+  layer: KnowledgeLayer | null;
+  preamble: string;
+  entries: KnowledgeEntry[];
+  legacySections: LegacySection[];
+  parseIssues: ParseIssue[];
+  isKnowledgeAdjacent: boolean;
+}

package/src/knowledge/serialize.ts

@@ -0,0 +1,72 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Round-trip serializer for knowledge files — reconstructs markdown from ParsedKnowledgeFile (RFC-0660).</purpose>
+<non-goals>
+  <item>Do not parse — that is handled by parse.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0660: initial round-trip serializer for structured knowledge entries.</item>
+  <item>RFC-0663: added promotedFrom to FIELD_ORDER for shared-layer provenance.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ParsedKnowledgeFile, KnowledgeEntryMeta } from "./schema.ts";
+
+const FIELD_ORDER: (keyof KnowledgeEntryMeta)[] = [
+  "id",
+  "layer",
+  "created",
+  "lastConfirmedAt",
+  "confirmations",
+  "expiresAt",
+  "supersedes",
+  "promotedTo",
+  "promotedFrom",
+  "status",
+];
+
+function formatYamlValue(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    return `[${value.join(", ")}]`;
+  }
+  if (typeof value === "string") return value;
+  return String(value);
+}
+
+function serializeMeta(meta: KnowledgeEntryMeta): string {
+  const lines: string[] = ["```knowledge-entry"];
+  for (const field of FIELD_ORDER) {
+    const value = meta[field];
+    if (value === undefined) continue;
+    lines.push(`${field}: ${formatYamlValue(value)}`);
+  }
+  lines.push("```");
+  return lines.join("\n");
+}
+
+export function serializeKnowledgeFile(parsed: ParsedKnowledgeFile): string {
+  const parts: string[] = [];
+
+  if (parsed.preamble) {
+    parts.push(parsed.preamble);
+  }
+
+  for (const entry of parsed.entries) {
+    parts.push(`### ${entry.meta.id}: ${entry.title}`);
+    parts.push("");
+    parts.push(serializeMeta(entry.meta));
+    if (entry.body) {
+      parts.push("");
+      parts.push(entry.body);
+    }
+  }
+
+  for (const legacy of parsed.legacySections) {
+    parts.push(legacy.text);
+  }
+
+  return parts.join("\n").replace(/\n{3,}/g, "\n\n") + "\n";
+}

package/src/migration-adapters/__tests__/ignored-files.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { discoverIgnoredFiles, formatSize } from "../ignored-files.ts";
+import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "forge-ignored-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+describe("formatSize", () => {
+  it("formats bytes", () => {
+    expect(formatSize(0)).toBe("0 B");
+    expect(formatSize(512)).toBe("512 B");
+    expect(formatSize(1023)).toBe("1023 B");
+  });
+
+  it("formats kilobytes", () => {
+    expect(formatSize(1024)).toBe("1.0 KB");
+    expect(formatSize(1536)).toBe("1.5 KB");
+  });
+
+  it("formats megabytes", () => {
+    expect(formatSize(1024 * 1024)).toBe("1.0 MB");
+    expect(formatSize(1024 * 1024 * 5)).toBe("5.0 MB");
+  });
+
+  it("formats gigabytes", () => {
+    expect(formatSize(1024 * 1024 * 1024)).toBe("1.0 GB");
+  });
+});
+
+describe("discoverIgnoredFiles", () => {
+  it("returns empty array when no .git directory exists", async () => {
+    const result = discoverIgnoredFiles(tempDir);
+    expect(result).toEqual([]);
+  });
+
+  it("returns empty array when .git exists but no ignored files", async () => {
+    await mkdir(join(tempDir, ".git"), { recursive: true });
+    await writeFile(join(tempDir, "file.txt"), "content", "utf8");
+    const result = discoverIgnoredFiles(tempDir);
+    expect(result).toEqual([]);
+  });
+});