forgesmith 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.2.0 — Architecture Narrative Generators
+
+- `generateArchitectureWalkthrough(blueprint, opts, provider)` — long-form narrative explaining structure, key files, and important relationships. Tones: `technical` | `casual` | `onboarding`
+- `generateChangesSince(current, previous, opts, provider)` — delta narrative: what changed between two Blueprint snapshots (new/removed files, edge changes, stats delta)
+- `generateOnboardingDoc(blueprint, opts, provider)` — new-developer intro to codebase with "Start here", key folders, core shared files. Tones: `friendly` | `formal` | `technical`
+- `generateRefactoringReport(blueprint, opts, provider)` — identifies architecture debt (hot spots, high fan-out, import cycles), suggests refactoring priorities. Tones: `analytical` | `casual` | `executive`
+- `readBlueprintData(targetPath)` — reads `.prism/blueprint/snapshot.json`; returns `BlueprintData | null`
+- New exported types: `BlueprintData`, `BlueprintFile`, `BlueprintEdge`, `ArchitectureWalkthroughOpts`, `ChangesSinceOpts`, `OnboardingDocOpts`, `RefactoringReportOpts`
+- 44 unit tests, all green (+31 new)
+
+## 0.1.1 — /providers sub-entry fix
+
+- Add explicit `./providers` export entry to package.json exports map
+- Add `src/providers.ts` barrel (re-exports `DirectLlmProvider`)
+- Fixes `Module not found: Can't resolve 'forgesmith/providers'` for consumers
+
 ## 0.1.0 — Initial real release
 
 - `generateReleaseNotes(data, opts, provider)` — LLM-powered release note generation from prism0x2A data

package/dist/index.cjs

@@ -72,6 +72,279 @@ async function generateReleaseNotes(data, opts, provider) {
     }
   };
 }
+
+// src/generators/architectureWalkthrough.ts
+var NO_DATA_MSG = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt2(tone) {
+  const toneMap = {
+    technical: "You are a senior software architect who writes precise, technical documentation for engineering teams.",
+    casual: "You are a friendly developer advocate who explains codebases in an approachable, conversational style.",
+    onboarding: "You are an experienced engineering mentor who helps new developers quickly understand a codebase."
+  };
+  return `${toneMap[tone] ?? toneMap.technical} Write only the requested document \u2014 no preamble, no meta-commentary.`;
+}
+function buildUserPrompt2(blueprint, opts) {
+  const tone = opts.tone ?? "technical";
+  const length = opts.length ?? "long";
+  const format = opts.format ?? "markdown";
+  const lengthGuide = {
+    short: "3-4 sections, concise overview",
+    medium: "5-7 sections with moderate detail",
+    long: "comprehensive, 8+ sections with full detail and examples"
+  }[length];
+  const topFiles = blueprint.files.slice().sort((a, b) => (b.importedByCount ?? 0) - (a.importedByCount ?? 0)).slice(0, 15);
+  const edgeSample = blueprint.edges.slice(0, 20);
+  const lines = [
+    `Generate an architecture walkthrough document in ${format} format for the codebase at "${blueprint.targetPath}".`,
+    `Tone: ${tone}. Length: ${length} (${lengthGuide}).`,
+    ``,
+    `## Codebase Stats`,
+    `- Total files: ${blueprint.stats.totalFiles}`,
+    `- Runtime dependency edges: ${blueprint.stats.runtimeEdges}`,
+    `- Categories: ${JSON.stringify(blueprint.categories)}`,
+    ``,
+    `## Key Files (by incoming dependency count)`,
+    ...topFiles.map((f) => `- ${f.path} [${f.category ?? "unknown"}] \u2014 importedBy: ${f.importedByCount ?? 0}, imports: ${f.importCount ?? 0}, lines: ${f.lineCount ?? "?"}`),
+    ``,
+    `## Dependency Edge Sample`,
+    ...edgeSample.map((e) => `- ${e.from} \u2192 ${e.to}${e.type ? ` (${e.type})` : ""}`),
+    ``,
+    `Cover: architecture overview, key layers/folders, entry points, important relationships, and what a new developer should understand first.`
+  ];
+  return lines.join("\n");
+}
+async function generateArchitectureWalkthrough(blueprint, opts, provider) {
+  if (!blueprint) {
+    return {
+      text: NO_DATA_MSG,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt2(opts.tone ?? "technical"),
+    messages: [{ role: "user", content: buildUserPrompt2(blueprint, opts) }],
+    maxTokens: 4096
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+
+// src/generators/changesSince.ts
+var NO_DATA_MSG2 = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt3() {
+  return `You are a technical writer who produces clear, concise architecture change summaries for development teams. Focus on what changed and why it matters. Write only the document \u2014 no preamble, no meta-commentary.`;
+}
+function computeDelta(current, previous) {
+  const currentPaths = new Set(current.files.map((f) => f.path));
+  const previousPaths = new Set(previous.files.map((f) => f.path));
+  const added = current.files.filter((f) => !previousPaths.has(f.path));
+  const removed = previous.files.filter((f) => !currentPaths.has(f.path));
+  const currentEdgeKeys = new Set(current.edges.map((e) => `${e.from}\u2192${e.to}`));
+  const previousEdgeKeys = new Set(previous.edges.map((e) => `${e.from}\u2192${e.to}`));
+  const addedEdges = current.edges.filter((e) => !previousEdgeKeys.has(`${e.from}\u2192${e.to}`));
+  const removedEdges = previous.edges.filter((e) => !currentEdgeKeys.has(`${e.from}\u2192${e.to}`));
+  return { added, removed, addedEdges, removedEdges };
+}
+function buildUserPrompt3(current, previous, opts) {
+  const tone = opts.tone ?? "professional";
+  const length = opts.length ?? "medium";
+  const format = opts.format ?? "markdown";
+  const delta = computeDelta(current, previous);
+  const prevDate = new Date(previous.scanTimestamp).toISOString().split("T")[0];
+  const currDate = new Date(current.scanTimestamp).toISOString().split("T")[0];
+  const lines = [
+    `Generate an architecture change summary in ${format} format.`,
+    `Tone: ${tone}. Length: ${length}.`,
+    `Period: ${prevDate} \u2192 ${currDate}`,
+    ``,
+    `## File Changes`,
+    `- Added files (${delta.added.length}): ${delta.added.slice(0, 20).map((f) => f.path).join(", ") || "none"}`,
+    `- Removed files (${delta.removed.length}): ${delta.removed.slice(0, 20).map((f) => f.path).join(", ") || "none"}`,
+    ``,
+    `## Dependency Edge Changes`,
+    `- New edges (${delta.addedEdges.length}): ${delta.addedEdges.slice(0, 10).map((e) => `${e.from}\u2192${e.to}`).join(", ") || "none"}`,
+    `- Removed edges (${delta.removedEdges.length}): ${delta.removedEdges.slice(0, 10).map((e) => `${e.from}\u2192${e.to}`).join(", ") || "none"}`,
+    ``,
+    `## Stats Delta`,
+    `- Files: ${previous.stats.totalFiles} \u2192 ${current.stats.totalFiles} (${current.stats.totalFiles - previous.stats.totalFiles >= 0 ? "+" : ""}${current.stats.totalFiles - previous.stats.totalFiles})`,
+    `- Edges: ${previous.stats.runtimeEdges} \u2192 ${current.stats.runtimeEdges} (${current.stats.runtimeEdges - previous.stats.runtimeEdges >= 0 ? "+" : ""}${current.stats.runtimeEdges - previous.stats.runtimeEdges})`,
+    ``,
+    `Summarize what changed architecturally, highlight significant additions or removals, and note any structural shifts.`
+  ];
+  return lines.join("\n");
+}
+async function generateChangesSince(current, previous, opts, provider) {
+  if (!current || !previous) {
+    return {
+      text: NO_DATA_MSG2,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt3(),
+    messages: [{ role: "user", content: buildUserPrompt3(current, previous, opts) }],
+    maxTokens: 2048
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+
+// src/generators/onboardingDoc.ts
+var NO_DATA_MSG3 = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt4(tone) {
+  const toneMap = {
+    friendly: "You are a helpful senior developer writing a welcoming onboarding guide for new team members. Be warm, encouraging, and practical.",
+    formal: "You are a documentation engineer writing a structured onboarding reference for enterprise engineering teams.",
+    technical: "You are a senior engineer writing a technical onboarding document focused on implementation details and system internals."
+  };
+  return `${toneMap[tone] ?? toneMap.friendly} Write only the document \u2014 no preamble, no meta-commentary.`;
+}
+function buildUserPrompt4(blueprint, opts) {
+  const tone = opts.tone ?? "friendly";
+  const length = opts.length ?? "medium";
+  const format = opts.format ?? "markdown";
+  const topEntryPoints = blueprint.files.filter((f) => f.category === "app" || (f.importedByCount ?? 0) === 0).slice(0, 10);
+  const topImported = blueprint.files.slice().sort((a, b) => (b.importedByCount ?? 0) - (a.importedByCount ?? 0)).slice(0, 10);
+  const folderMap = /* @__PURE__ */ new Map();
+  for (const f of blueprint.files) {
+    const parts = f.path.split("/");
+    if (parts.length > 1) {
+      const folder = parts[0];
+      folderMap.set(folder, (folderMap.get(folder) ?? 0) + 1);
+    }
+  }
+  const topFolders = [...folderMap.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([folder, count]) => `${folder}/ (${count} files)`);
+  const lines = [
+    `Generate an onboarding document in ${format} format for new developers joining this codebase.`,
+    `Project path: "${blueprint.targetPath}"`,
+    `Tone: ${tone}. Length: ${length}.`,
+    ``,
+    `## Codebase Overview`,
+    `- ${blueprint.stats.totalFiles} files across ${Object.keys(blueprint.categories).length} categories`,
+    `- Categories: ${JSON.stringify(blueprint.categories)}`,
+    ``,
+    `## Top-level Folders`,
+    ...topFolders.map((f) => `- ${f}`),
+    ``,
+    `## Entry Points (app-layer files, zero incoming deps)`,
+    ...topEntryPoints.map((f) => `- ${f.path}`),
+    ``,
+    `## Core Shared Files (most imported)`,
+    ...topImported.map((f) => `- ${f.path} \u2014 used by ${f.importedByCount ?? 0} files`),
+    ``,
+    `Include: "Start here" section, key folders tour, important conventions to follow, the 3-5 files to read first, and how to run/test the project.`
+  ];
+  return lines.join("\n");
+}
+async function generateOnboardingDoc(blueprint, opts, provider) {
+  if (!blueprint) {
+    return {
+      text: NO_DATA_MSG3,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt4(opts.tone ?? "friendly"),
+    messages: [{ role: "user", content: buildUserPrompt4(blueprint, opts) }],
+    maxTokens: 3072
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+
+// src/generators/refactoringReport.ts
+var NO_DATA_MSG4 = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt5(tone) {
+  const toneMap = {
+    analytical: "You are a software architecture consultant who produces rigorous, evidence-based refactoring reports with clear prioritization.",
+    casual: "You are a senior developer who gives honest, practical refactoring advice based on code structure data.",
+    executive: "You are a CTO-level advisor who summarizes architectural debt and refactoring priorities for engineering leadership."
+  };
+  return `${toneMap[tone] ?? toneMap.analytical} Write only the report \u2014 no preamble, no meta-commentary.`;
+}
+function detectImportCycles(edges) {
+  const graph = /* @__PURE__ */ new Map();
+  for (const e of edges) {
+    if (!graph.has(e.from)) graph.set(e.from, /* @__PURE__ */ new Set());
+    graph.get(e.from).add(e.to);
+  }
+  const cycles = [];
+  const visited = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  function dfs(node, path2) {
+    if (cycles.length >= 5) return;
+    if (stack.has(node)) {
+      const cycleStart = path2.indexOf(node);
+      if (cycleStart !== -1) {
+        cycles.push(path2.slice(cycleStart).join(" \u2192 ") + " \u2192 " + node);
+      }
+      return;
+    }
+    if (visited.has(node)) return;
+    visited.add(node);
+    stack.add(node);
+    for (const neighbor of graph.get(node) ?? []) {
+      dfs(neighbor, [...path2, node]);
+    }
+    stack.delete(node);
+  }
+  for (const node of graph.keys()) {
+    if (!visited.has(node)) dfs(node, []);
+  }
+  return cycles;
+}
+function buildUserPrompt5(blueprint, opts) {
+  const tone = opts.tone ?? "analytical";
+  const length = opts.length ?? "medium";
+  const format = opts.format ?? "markdown";
+  const hotFiles = blueprint.files.slice().sort((a, b) => (b.importedByCount ?? 0) + (b.importCount ?? 0) - ((a.importedByCount ?? 0) + (a.importCount ?? 0))).slice(0, 10);
+  const highFanOut = blueprint.files.slice().sort((a, b) => (b.importCount ?? 0) - (a.importCount ?? 0)).slice(0, 8);
+  const importCycles = detectImportCycles(blueprint.edges);
+  const lines = [
+    `Generate a refactoring report in ${format} format for the codebase at "${blueprint.targetPath}".`,
+    `Tone: ${tone}. Length: ${length}.`,
+    ``,
+    `## Architecture Metrics`,
+    `- Total files: ${blueprint.stats.totalFiles}`,
+    `- Dependency edges: ${blueprint.stats.runtimeEdges}`,
+    `- Categories: ${JSON.stringify(blueprint.categories)}`,
+    ``,
+    `## High-Coupling Hot Spots (high total connections)`,
+    ...hotFiles.map((f) => `- ${f.path} \u2014 in: ${f.importedByCount ?? 0}, out: ${f.importCount ?? 0}, lines: ${f.lineCount ?? "?"}`),
+    ``,
+    `## High Fan-Out Files (many outgoing dependencies)`,
+    ...highFanOut.map((f) => `- ${f.path} \u2014 imports: ${f.importCount ?? 0}`),
+    ``,
+    `## Import Cycles Detected (${importCycles.length})`,
+    ...importCycles.length > 0 ? importCycles.map((c) => `- ${c}`) : ["No cycles detected in sampled edges"],
+    ``,
+    `Identify refactoring priorities: coupling issues, over-large files, circular dependencies, layer violations. Suggest concrete refactoring actions with rationale.`
+  ];
+  return lines.join("\n");
+}
+async function generateRefactoringReport(blueprint, opts, provider) {
+  if (!blueprint) {
+    return {
+      text: NO_DATA_MSG4,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt5(opts.tone ?? "analytical"),
+    messages: [{ role: "user", content: buildUserPrompt5(blueprint, opts) }],
+    maxTokens: 3072
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
 async function readJsonFiles(dir) {
   try {
     const entries = await fs__default.default.readdir(dir);
@@ -100,6 +373,20 @@ async function readPrismDirectory(prismPath) {
   ]);
   return { sessions, recommendations, insights };
 }
+async function readBlueprintData(targetPath) {
+  const snapshotPath = path__default.default.join(targetPath, ".prism", "blueprint", "snapshot.json");
+  try {
+    const raw = await fs__default.default.readFile(snapshotPath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
 
+exports.generateArchitectureWalkthrough = generateArchitectureWalkthrough;
+exports.generateChangesSince = generateChangesSince;
+exports.generateOnboardingDoc = generateOnboardingDoc;
+exports.generateRefactoringReport = generateRefactoringReport;
 exports.generateReleaseNotes = generateReleaseNotes;
+exports.readBlueprintData = readBlueprintData;
 exports.readPrismDirectory = readPrismDirectory;

package/dist/index.d.cts

@@ -29,6 +29,56 @@ interface ReleaseNotesOpts {
     length?: "short" | "medium" | "long";
     format?: "markdown" | "plain";
 }
+interface BlueprintFile {
+    path: string;
+    category?: "app" | "component" | "lib" | "hook" | string;
+    importCount?: number;
+    importedByCount?: number;
+    lineCount?: number;
+}
+interface BlueprintEdge {
+    from: string;
+    to: string;
+    type?: string;
+}
+interface BlueprintData {
+    targetPath: string;
+    scanTimestamp: number;
+    stats: {
+        totalFiles: number;
+        runtimeEdges: number;
+        [key: string]: number;
+    };
+    files: BlueprintFile[];
+    edges: BlueprintEdge[];
+    categories: {
+        app: number;
+        component: number;
+        lib: number;
+        hook: number;
+        [key: string]: number;
+    };
+}
+interface ArchitectureWalkthroughOpts {
+    tone?: "technical" | "casual" | "onboarding";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface ChangesSinceOpts {
+    tone?: "professional" | "casual" | "technical";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface OnboardingDocOpts {
+    tone?: "friendly" | "formal" | "technical";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface RefactoringReportOpts {
+    tone?: "analytical" | "casual" | "executive";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
 interface GenerationResult {
     text: string;
     metadata: {
@@ -58,6 +108,15 @@ interface LlmProvider {
 
 declare function generateReleaseNotes(data: PrismData, opts: ReleaseNotesOpts, provider: LlmProvider): Promise<GenerationResult>;
 
+declare function generateArchitectureWalkthrough(blueprint: BlueprintData | null, opts: ArchitectureWalkthroughOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function generateChangesSince(current: BlueprintData | null, previous: BlueprintData | null, opts: ChangesSinceOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function generateOnboardingDoc(blueprint: BlueprintData | null, opts: OnboardingDocOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function generateRefactoringReport(blueprint: BlueprintData | null, opts: RefactoringReportOpts, provider: LlmProvider): Promise<GenerationResult>;
+
 declare function readPrismDirectory(prismPath: string): Promise<PrismData>;
+declare function readBlueprintData(targetPath: string): Promise<BlueprintData | null>;
 
-export { type GenerationResult, type LlmMessage, type LlmProvider, type LlmRequest, type LlmResponse, type PrismData, type PrismInsight, type PrismRecommendation, type PrismSession, type ReleaseNotesOpts, generateReleaseNotes, readPrismDirectory };
+export { type ArchitectureWalkthroughOpts, type BlueprintData, type BlueprintEdge, type BlueprintFile, type ChangesSinceOpts, type GenerationResult, type LlmMessage, type LlmProvider, type LlmRequest, type LlmResponse, type OnboardingDocOpts, type PrismData, type PrismInsight, type PrismRecommendation, type PrismSession, type RefactoringReportOpts, type ReleaseNotesOpts, generateArchitectureWalkthrough, generateChangesSince, generateOnboardingDoc, generateRefactoringReport, generateReleaseNotes, readBlueprintData, readPrismDirectory };

package/dist/index.d.ts

@@ -29,6 +29,56 @@ interface ReleaseNotesOpts {
     length?: "short" | "medium" | "long";
     format?: "markdown" | "plain";
 }
+interface BlueprintFile {
+    path: string;
+    category?: "app" | "component" | "lib" | "hook" | string;
+    importCount?: number;
+    importedByCount?: number;
+    lineCount?: number;
+}
+interface BlueprintEdge {
+    from: string;
+    to: string;
+    type?: string;
+}
+interface BlueprintData {
+    targetPath: string;
+    scanTimestamp: number;
+    stats: {
+        totalFiles: number;
+        runtimeEdges: number;
+        [key: string]: number;
+    };
+    files: BlueprintFile[];
+    edges: BlueprintEdge[];
+    categories: {
+        app: number;
+        component: number;
+        lib: number;
+        hook: number;
+        [key: string]: number;
+    };
+}
+interface ArchitectureWalkthroughOpts {
+    tone?: "technical" | "casual" | "onboarding";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface ChangesSinceOpts {
+    tone?: "professional" | "casual" | "technical";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface OnboardingDocOpts {
+    tone?: "friendly" | "formal" | "technical";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface RefactoringReportOpts {
+    tone?: "analytical" | "casual" | "executive";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
 interface GenerationResult {
     text: string;
     metadata: {
@@ -58,6 +108,15 @@ interface LlmProvider {
 
 declare function generateReleaseNotes(data: PrismData, opts: ReleaseNotesOpts, provider: LlmProvider): Promise<GenerationResult>;
 
+declare function generateArchitectureWalkthrough(blueprint: BlueprintData | null, opts: ArchitectureWalkthroughOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function generateChangesSince(current: BlueprintData | null, previous: BlueprintData | null, opts: ChangesSinceOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function generateOnboardingDoc(blueprint: BlueprintData | null, opts: OnboardingDocOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function generateRefactoringReport(blueprint: BlueprintData | null, opts: RefactoringReportOpts, provider: LlmProvider): Promise<GenerationResult>;
+
 declare function readPrismDirectory(prismPath: string): Promise<PrismData>;
+declare function readBlueprintData(targetPath: string): Promise<BlueprintData | null>;
 
-export { type GenerationResult, type LlmMessage, type LlmProvider, type LlmRequest, type LlmResponse, type PrismData, type PrismInsight, type PrismRecommendation, type PrismSession, type ReleaseNotesOpts, generateReleaseNotes, readPrismDirectory };
+export { type ArchitectureWalkthroughOpts, type BlueprintData, type BlueprintEdge, type BlueprintFile, type ChangesSinceOpts, type GenerationResult, type LlmMessage, type LlmProvider, type LlmRequest, type LlmResponse, type OnboardingDocOpts, type PrismData, type PrismInsight, type PrismRecommendation, type PrismSession, type RefactoringReportOpts, type ReleaseNotesOpts, generateArchitectureWalkthrough, generateChangesSince, generateOnboardingDoc, generateRefactoringReport, generateReleaseNotes, readBlueprintData, readPrismDirectory };

package/dist/index.mjs

@@ -65,6 +65,279 @@ async function generateReleaseNotes(data, opts, provider) {
     }
   };
 }
+
+// src/generators/architectureWalkthrough.ts
+var NO_DATA_MSG = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt2(tone) {
+  const toneMap = {
+    technical: "You are a senior software architect who writes precise, technical documentation for engineering teams.",
+    casual: "You are a friendly developer advocate who explains codebases in an approachable, conversational style.",
+    onboarding: "You are an experienced engineering mentor who helps new developers quickly understand a codebase."
+  };
+  return `${toneMap[tone] ?? toneMap.technical} Write only the requested document \u2014 no preamble, no meta-commentary.`;
+}
+function buildUserPrompt2(blueprint, opts) {
+  const tone = opts.tone ?? "technical";
+  const length = opts.length ?? "long";
+  const format = opts.format ?? "markdown";
+  const lengthGuide = {
+    short: "3-4 sections, concise overview",
+    medium: "5-7 sections with moderate detail",
+    long: "comprehensive, 8+ sections with full detail and examples"
+  }[length];
+  const topFiles = blueprint.files.slice().sort((a, b) => (b.importedByCount ?? 0) - (a.importedByCount ?? 0)).slice(0, 15);
+  const edgeSample = blueprint.edges.slice(0, 20);
+  const lines = [
+    `Generate an architecture walkthrough document in ${format} format for the codebase at "${blueprint.targetPath}".`,
+    `Tone: ${tone}. Length: ${length} (${lengthGuide}).`,
+    ``,
+    `## Codebase Stats`,
+    `- Total files: ${blueprint.stats.totalFiles}`,
+    `- Runtime dependency edges: ${blueprint.stats.runtimeEdges}`,
+    `- Categories: ${JSON.stringify(blueprint.categories)}`,
+    ``,
+    `## Key Files (by incoming dependency count)`,
+    ...topFiles.map((f) => `- ${f.path} [${f.category ?? "unknown"}] \u2014 importedBy: ${f.importedByCount ?? 0}, imports: ${f.importCount ?? 0}, lines: ${f.lineCount ?? "?"}`),
+    ``,
+    `## Dependency Edge Sample`,
+    ...edgeSample.map((e) => `- ${e.from} \u2192 ${e.to}${e.type ? ` (${e.type})` : ""}`),
+    ``,
+    `Cover: architecture overview, key layers/folders, entry points, important relationships, and what a new developer should understand first.`
+  ];
+  return lines.join("\n");
+}
+async function generateArchitectureWalkthrough(blueprint, opts, provider) {
+  if (!blueprint) {
+    return {
+      text: NO_DATA_MSG,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt2(opts.tone ?? "technical"),
+    messages: [{ role: "user", content: buildUserPrompt2(blueprint, opts) }],
+    maxTokens: 4096
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+
+// src/generators/changesSince.ts
+var NO_DATA_MSG2 = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt3() {
+  return `You are a technical writer who produces clear, concise architecture change summaries for development teams. Focus on what changed and why it matters. Write only the document \u2014 no preamble, no meta-commentary.`;
+}
+function computeDelta(current, previous) {
+  const currentPaths = new Set(current.files.map((f) => f.path));
+  const previousPaths = new Set(previous.files.map((f) => f.path));
+  const added = current.files.filter((f) => !previousPaths.has(f.path));
+  const removed = previous.files.filter((f) => !currentPaths.has(f.path));
+  const currentEdgeKeys = new Set(current.edges.map((e) => `${e.from}\u2192${e.to}`));
+  const previousEdgeKeys = new Set(previous.edges.map((e) => `${e.from}\u2192${e.to}`));
+  const addedEdges = current.edges.filter((e) => !previousEdgeKeys.has(`${e.from}\u2192${e.to}`));
+  const removedEdges = previous.edges.filter((e) => !currentEdgeKeys.has(`${e.from}\u2192${e.to}`));
+  return { added, removed, addedEdges, removedEdges };
+}
+function buildUserPrompt3(current, previous, opts) {
+  const tone = opts.tone ?? "professional";
+  const length = opts.length ?? "medium";
+  const format = opts.format ?? "markdown";
+  const delta = computeDelta(current, previous);
+  const prevDate = new Date(previous.scanTimestamp).toISOString().split("T")[0];
+  const currDate = new Date(current.scanTimestamp).toISOString().split("T")[0];
+  const lines = [
+    `Generate an architecture change summary in ${format} format.`,
+    `Tone: ${tone}. Length: ${length}.`,
+    `Period: ${prevDate} \u2192 ${currDate}`,
+    ``,
+    `## File Changes`,
+    `- Added files (${delta.added.length}): ${delta.added.slice(0, 20).map((f) => f.path).join(", ") || "none"}`,
+    `- Removed files (${delta.removed.length}): ${delta.removed.slice(0, 20).map((f) => f.path).join(", ") || "none"}`,
+    ``,
+    `## Dependency Edge Changes`,
+    `- New edges (${delta.addedEdges.length}): ${delta.addedEdges.slice(0, 10).map((e) => `${e.from}\u2192${e.to}`).join(", ") || "none"}`,
+    `- Removed edges (${delta.removedEdges.length}): ${delta.removedEdges.slice(0, 10).map((e) => `${e.from}\u2192${e.to}`).join(", ") || "none"}`,
+    ``,
+    `## Stats Delta`,
+    `- Files: ${previous.stats.totalFiles} \u2192 ${current.stats.totalFiles} (${current.stats.totalFiles - previous.stats.totalFiles >= 0 ? "+" : ""}${current.stats.totalFiles - previous.stats.totalFiles})`,
+    `- Edges: ${previous.stats.runtimeEdges} \u2192 ${current.stats.runtimeEdges} (${current.stats.runtimeEdges - previous.stats.runtimeEdges >= 0 ? "+" : ""}${current.stats.runtimeEdges - previous.stats.runtimeEdges})`,
+    ``,
+    `Summarize what changed architecturally, highlight significant additions or removals, and note any structural shifts.`
+  ];
+  return lines.join("\n");
+}
+async function generateChangesSince(current, previous, opts, provider) {
+  if (!current || !previous) {
+    return {
+      text: NO_DATA_MSG2,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt3(),
+    messages: [{ role: "user", content: buildUserPrompt3(current, previous, opts) }],
+    maxTokens: 2048
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+
+// src/generators/onboardingDoc.ts
+var NO_DATA_MSG3 = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt4(tone) {
+  const toneMap = {
+    friendly: "You are a helpful senior developer writing a welcoming onboarding guide for new team members. Be warm, encouraging, and practical.",
+    formal: "You are a documentation engineer writing a structured onboarding reference for enterprise engineering teams.",
+    technical: "You are a senior engineer writing a technical onboarding document focused on implementation details and system internals."
+  };
+  return `${toneMap[tone] ?? toneMap.friendly} Write only the document \u2014 no preamble, no meta-commentary.`;
+}
+function buildUserPrompt4(blueprint, opts) {
+  const tone = opts.tone ?? "friendly";
+  const length = opts.length ?? "medium";
+  const format = opts.format ?? "markdown";
+  const topEntryPoints = blueprint.files.filter((f) => f.category === "app" || (f.importedByCount ?? 0) === 0).slice(0, 10);
+  const topImported = blueprint.files.slice().sort((a, b) => (b.importedByCount ?? 0) - (a.importedByCount ?? 0)).slice(0, 10);
+  const folderMap = /* @__PURE__ */ new Map();
+  for (const f of blueprint.files) {
+    const parts = f.path.split("/");
+    if (parts.length > 1) {
+      const folder = parts[0];
+      folderMap.set(folder, (folderMap.get(folder) ?? 0) + 1);
+    }
+  }
+  const topFolders = [...folderMap.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([folder, count]) => `${folder}/ (${count} files)`);
+  const lines = [
+    `Generate an onboarding document in ${format} format for new developers joining this codebase.`,
+    `Project path: "${blueprint.targetPath}"`,
+    `Tone: ${tone}. Length: ${length}.`,
+    ``,
+    `## Codebase Overview`,
+    `- ${blueprint.stats.totalFiles} files across ${Object.keys(blueprint.categories).length} categories`,
+    `- Categories: ${JSON.stringify(blueprint.categories)}`,
+    ``,
+    `## Top-level Folders`,
+    ...topFolders.map((f) => `- ${f}`),
+    ``,
+    `## Entry Points (app-layer files, zero incoming deps)`,
+    ...topEntryPoints.map((f) => `- ${f.path}`),
+    ``,
+    `## Core Shared Files (most imported)`,
+    ...topImported.map((f) => `- ${f.path} \u2014 used by ${f.importedByCount ?? 0} files`),
+    ``,
+    `Include: "Start here" section, key folders tour, important conventions to follow, the 3-5 files to read first, and how to run/test the project.`
+  ];
+  return lines.join("\n");
+}
+async function generateOnboardingDoc(blueprint, opts, provider) {
+  if (!blueprint) {
+    return {
+      text: NO_DATA_MSG3,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt4(opts.tone ?? "friendly"),
+    messages: [{ role: "user", content: buildUserPrompt4(blueprint, opts) }],
+    maxTokens: 3072
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+
+// src/generators/refactoringReport.ts
+var NO_DATA_MSG4 = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt5(tone) {
+  const toneMap = {
+    analytical: "You are a software architecture consultant who produces rigorous, evidence-based refactoring reports with clear prioritization.",
+    casual: "You are a senior developer who gives honest, practical refactoring advice based on code structure data.",
+    executive: "You are a CTO-level advisor who summarizes architectural debt and refactoring priorities for engineering leadership."
+  };
+  return `${toneMap[tone] ?? toneMap.analytical} Write only the report \u2014 no preamble, no meta-commentary.`;
+}
+function detectImportCycles(edges) {
+  const graph = /* @__PURE__ */ new Map();
+  for (const e of edges) {
+    if (!graph.has(e.from)) graph.set(e.from, /* @__PURE__ */ new Set());
+    graph.get(e.from).add(e.to);
+  }
+  const cycles = [];
+  const visited = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  function dfs(node, path2) {
+    if (cycles.length >= 5) return;
+    if (stack.has(node)) {
+      const cycleStart = path2.indexOf(node);
+      if (cycleStart !== -1) {
+        cycles.push(path2.slice(cycleStart).join(" \u2192 ") + " \u2192 " + node);
+      }
+      return;
+    }
+    if (visited.has(node)) return;
+    visited.add(node);
+    stack.add(node);
+    for (const neighbor of graph.get(node) ?? []) {
+      dfs(neighbor, [...path2, node]);
+    }
+    stack.delete(node);
+  }
+  for (const node of graph.keys()) {
+    if (!visited.has(node)) dfs(node, []);
+  }
+  return cycles;
+}
+function buildUserPrompt5(blueprint, opts) {
+  const tone = opts.tone ?? "analytical";
+  const length = opts.length ?? "medium";
+  const format = opts.format ?? "markdown";
+  const hotFiles = blueprint.files.slice().sort((a, b) => (b.importedByCount ?? 0) + (b.importCount ?? 0) - ((a.importedByCount ?? 0) + (a.importCount ?? 0))).slice(0, 10);
+  const highFanOut = blueprint.files.slice().sort((a, b) => (b.importCount ?? 0) - (a.importCount ?? 0)).slice(0, 8);
+  const importCycles = detectImportCycles(blueprint.edges);
+  const lines = [
+    `Generate a refactoring report in ${format} format for the codebase at "${blueprint.targetPath}".`,
+    `Tone: ${tone}. Length: ${length}.`,
+    ``,
+    `## Architecture Metrics`,
+    `- Total files: ${blueprint.stats.totalFiles}`,
+    `- Dependency edges: ${blueprint.stats.runtimeEdges}`,
+    `- Categories: ${JSON.stringify(blueprint.categories)}`,
+    ``,
+    `## High-Coupling Hot Spots (high total connections)`,
+    ...hotFiles.map((f) => `- ${f.path} \u2014 in: ${f.importedByCount ?? 0}, out: ${f.importCount ?? 0}, lines: ${f.lineCount ?? "?"}`),
+    ``,
+    `## High Fan-Out Files (many outgoing dependencies)`,
+    ...highFanOut.map((f) => `- ${f.path} \u2014 imports: ${f.importCount ?? 0}`),
+    ``,
+    `## Import Cycles Detected (${importCycles.length})`,
+    ...importCycles.length > 0 ? importCycles.map((c) => `- ${c}`) : ["No cycles detected in sampled edges"],
+    ``,
+    `Identify refactoring priorities: coupling issues, over-large files, circular dependencies, layer violations. Suggest concrete refactoring actions with rationale.`
+  ];
+  return lines.join("\n");
+}
+async function generateRefactoringReport(blueprint, opts, provider) {
+  if (!blueprint) {
+    return {
+      text: NO_DATA_MSG4,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt5(opts.tone ?? "analytical"),
+    messages: [{ role: "user", content: buildUserPrompt5(blueprint, opts) }],
+    maxTokens: 3072
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
 async function readJsonFiles(dir) {
   try {
     const entries = await fs.readdir(dir);
@@ -93,5 +366,14 @@ async function readPrismDirectory(prismPath) {
   ]);
   return { sessions, recommendations, insights };
 }
+async function readBlueprintData(targetPath) {
+  const snapshotPath = path.join(targetPath, ".prism", "blueprint", "snapshot.json");
+  try {
+    const raw = await fs.readFile(snapshotPath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
 
-export { generateReleaseNotes, readPrismDirectory };
+export { generateArchitectureWalkthrough, generateChangesSince, generateOnboardingDoc, generateRefactoringReport, generateReleaseNotes, readBlueprintData, readPrismDirectory };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgesmith",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "forgesmith — content & asset-generation engine. Forge release notes, blog posts, social copy from prism0x2A data.",
   "type": "module",
   "main": "./dist/index.cjs",