vibe-code-explainer 0.2.1 → 0.3.1

package/README.md

@@ -16,30 +16,57 @@ No more accepting code blindly.
 **Safe change (low/no risk):**
 
 ```
-┌─ code-explainer ─────────────────────────────
-│  src/app/page.tsx
-│
-│  Changed the page background from a solid dark color to a
-│  gradient that blends two shades of blue. Visual-only change,
-│  no logic or data affected.
-│
-│  Risk: ✅ None
-└──────────────────────────────────────────────
+╭─ vibe-code-explainer ─────────────────────────╮
+│                                                 │
+│  📄  src/app/page.tsx                           │
+│                                                 │
+│  ▸ Impact                                       │
+│    Changed page background from solid dark      │
+│    blue to a gradient.                          │
+│                                                 │
+│  ▸ How it works                                 │
+│    `bg-gradient-to-br` + `from-`/`to-` Tailwind │
+│    utilities generate a CSS linear-gradient.    │
+│                                                 │
+│  ▸ Why                                          │
+│    Tailwind: utility classes for gradients      │
+│    instead of writing custom CSS.               │
+│                                                 │
+│  ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄  │
+│                                                 │
+│  ✓  Risk: None                                  │
+│                                                 │
+╰─────────────────────────────────────────────────╯
 ```
 
 **Risky change (medium/high risk):**
 
 ```
-┌─ code-explainer ⚠️ ──────────────────────────
-│  🚨  .env
-│
-│  Adds a Stripe payment secret key directly in the environment
-│  file. This key gives access to your payment system.
-│
-│  Risk: 🚨 High
-│  A live payment API key is hardcoded in the file and should
-│  not be committed to version control.
-└──────────────────────────────────────────────
+╭─ vibe-code-explainer ─────────────────────────╮       ← red border
+│                                                 │
+│  📄  .env                                       │
+│                                                 │
+│  ▸ Impact                                       │
+│    Added a Stripe payment secret key directly   │
+│    in the environment file.                     │
+│                                                 │
+│  ▸ How it works                                 │
+│    `.env` files store environment variables,    │
+│    read by your code at runtime. `sk_live_`     │
+│    is Stripe's prefix for production keys.      │
+│                                                 │
+│  ▸ Why                                          │
+│    Convention: secrets live in .env files that  │
+│    are kept out of git via .gitignore.          │
+│                                                 │
+│  ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄  │
+│                                                 │
+│  🚨  Risk: High                                 │
+│      A live Stripe production key is hardcoded. │
+│      Make sure .env is in .gitignore before     │
+│      committing.                                │
+│                                                 │
+╰─────────────────────────────────────────────────╯
 ```
 
 ---
@@ -112,9 +139,15 @@ exist, so you can set a global default and override per-project.
 
 #### 3. Detail level
 
-- **Standard** — 1–2 sentence explanation per change (recommended)
-- **Minimal** — one short sentence per change
-- **Verbose** — detailed bullet-point breakdown of every change
+This is also the **teacher mode** switch:
+
+- **Minimal** — single sentence describing the impact. **No teaching.** Use
+  this if you just want to know what changed without any educational content.
+- **Standard** — three sections per change: **Impact** (what changes for the
+  user), **How it works** (mechanical explanation of the syntax/concept),
+  **Why** (why this approach was used). Recommended.
+- **Verbose** — same three sections, each more in-depth (2–4 sentences).
+  Plus a fourth **Deeper dive** section with related terms to look up.
 
 #### 4. Language
 
@@ -123,10 +156,25 @@ Pick the language the explanations are written in. Supported:
 English, Portuguese, Spanish, French, German, Italian, Chinese, Japanese,
 Korean.
 
-Only the `summary` and `riskReason` fields are translated. JSON keys and the
-risk labels (`none` / `low` / `medium` / `high`) stay in English.
+Only the natural-language fields (impact, howItWorks, why, deepDive items,
+riskReason) are translated. JSON keys and risk labels (`none` / `low` /
+`medium` / `high`) stay in English so parsing stays stable.
+
+#### 5. Programming knowledge level (only when teaching is on)
+
+If you picked Standard or Verbose, the installer asks how much you already
+know about programming. This calibrates the depth of the teaching:
 
-#### 5. Model (Ollama only)
+- **Never programmed** — explanations start from "what is a variable" when
+  needed. Uses everyday-life analogies.
+- **Just starting out** — explains new technical terms, doesn't re-teach
+  basics like variables and functions.
+- **Read code with difficulty** — assumes core concepts, focuses on idiomatic
+  patterns and what specific syntax accomplishes.
+- **Code regularly** — concise. Mentions modern features, gotchas, and
+  alternatives rather than syntax basics.
+
+#### 6. Model (Ollama only)
 
 - If you have an NVIDIA GPU, the installer auto-detects your VRAM and picks
   the right model.
@@ -249,14 +297,15 @@ offers to download it on the spot if not.
 code-explainer config (project)
 
 Current settings:
-  Engine:        Local LLM (Ollama)
-  Model:         qwen3.5:4b
-  Ollama URL:    http://localhost:11434
-  Detail level:  standard
-  Language:      English
-  Hooks:         Edit ✓  Write ✓  Bash ✓
-  Excluded:      *.lock, dist/**, node_modules/**
-  Skip if slow:  8s
+  Engine:         Local LLM (Ollama)
+  Model:          qwen3.5:4b
+  Ollama URL:     http://localhost:11434
+  Detail level:   standard
+  Language:       English
+  Learner level:  Read code with difficulty
+  Hooks:          Edit ✓  Write ✓  Bash ✓
+  Excluded:       *.lock, dist/**, node_modules/**
+  Skip if slow:   Never skip
 
 ? What would you like to change?
   ❯ Engine
@@ -264,6 +313,7 @@ Current settings:
     Ollama URL
     Detail level
     Language
+    Learner level
     Enable/disable hooks
     File exclusions
     Latency timeout
@@ -288,16 +338,20 @@ If both exist, the project config takes precedence at runtime.
 - **Detail level** — minimal / standard / verbose. See
   [Install → Detail level](#3-detail-level) for what each produces.
 - **Language** — English, Portuguese, Spanish, French, German, Italian,
-  Chinese, Japanese, Korean. Applies to the `summary` and `riskReason`
-  fields; JSON keys and risk labels stay in English.
+  Chinese, Japanese, Korean. Applies to the natural-language fields (impact,
+  howItWorks, why, deepDive, riskReason); JSON keys and risk labels stay in
+  English.
+- **Learner level** — calibrates teaching depth. Options: never programmed /
+  just starting / read code with difficulty / code regularly. See
+  [Install → step 5](#5-programming-knowledge-level-only-when-teaching-is-on).
 - **Hooks** — turn on or off individually. If Bash explanations feel noisy,
   disable just that hook and keep Edit + Write.
 - **File exclusions** — glob patterns for files you never want explained.
   Defaults cover lockfiles, build output, and dependencies. Add patterns like
   `*.generated.*` if your project has codegen.
 - **Latency timeout** — maximum time to wait for an explanation before
-  skipping it. Options: 5s (aggressive), 8s (balanced, recommended), 15s
-  (patient), or never skip.
+  skipping it. Options: 5s (aggressive), 8s (balanced), 15s (patient), or
+  never skip (default — explanations always wait until the engine responds).
 
 ### Editing the config file directly
 
@@ -316,13 +370,14 @@ Full config schema:
   "ollamaUrl": "http://localhost:11434",
   "detailLevel": "standard",
   "language": "en",
+  "learnerLevel": "intermediate",
   "hooks": {
     "edit": true,
     "write": true,
     "bash": true
   },
   "exclude": ["*.lock", "dist/**", "node_modules/**"],
-  "skipIfSlowMs": 8000,
+  "skipIfSlowMs": 0,
   "bashFilter": {
     "capturePatterns": [
       "rm", "mv", "cp", "mkdir",
@@ -344,6 +399,7 @@ Field types:
 | `ollamaUrl` | Any valid URL (warns on non-loopback) |
 | `detailLevel` | `"minimal"` / `"standard"` / `"verbose"` |
 | `language` | `"en"` / `"pt"` / `"es"` / `"fr"` / `"de"` / `"it"` / `"zh"` / `"ja"` / `"ko"` |
+| `learnerLevel` | `"none"` / `"beginner"` / `"intermediate"` / `"regular"` |
 | `hooks.edit` / `hooks.write` / `hooks.bash` | `true` or `false` |
 | `exclude` | Array of glob patterns |
 | `skipIfSlowMs` | Number in milliseconds; `0` means never skip |
@@ -441,14 +497,19 @@ Most common causes, in order:
    the issue.
 4. **The file is excluded.** Check your `exclude` patterns in the config.
 
-### The explanation took too long and got skipped
+### Claude Code feels slow because it's waiting for explanations
+
+By default, code-explainer never skips — every explanation waits for the
+engine to finish so you don't lose context. With Ollama, that can be 10–15s
+on cold start, then 2–5s for normal explanations.
 
-Default timeout is 8 seconds. Cold starts with Ollama (first explanation
-after starting the service) can be 10–15 seconds. Two fixes:
+If the wait is bothering you:
 
-- Run `vibe-code-explainer warmup` right after starting Ollama.
-- Raise the timeout to 15 seconds via `vibe-code-explainer config →
-  Latency timeout`.
+- Run `vibe-code-explainer warmup` after starting Ollama, so the first
+  explanation is fast.
+- Set a timeout via `vibe-code-explainer config → Latency timeout`. Options:
+  5s (aggressive), 8s (balanced), 15s (patient). Anything that takes longer
+  is skipped with a notice instead of blocking Claude Code.
 
 ### Explanations are low-quality
 

package/dist/{chunk-5NCRRHU7.js → chunk-RK7ZFN4W.js}

@@ -15,6 +15,12 @@ var LANGUAGE_NAMES = {
   ja: "Japanese",
   ko: "Korean"
 };
+var LEARNER_LEVEL_NAMES = {
+  none: "Never programmed",
+  beginner: "Just starting out",
+  intermediate: "Read code with difficulty",
+  regular: "Code regularly"
+};
 var CONFIG_FILENAME = "code-explainer.config.json";
 function getGlobalConfigPath() {
   return join(homedir(), ".code-explainer.config.json");
@@ -25,13 +31,14 @@ var DEFAULT_CONFIG = {
   ollamaUrl: "http://localhost:11434",
   detailLevel: "standard",
   language: "en",
+  learnerLevel: "intermediate",
   hooks: {
     edit: true,
     write: true,
     bash: true
   },
   exclude: ["*.lock", "dist/**", "node_modules/**"],
-  skipIfSlowMs: 8e3,
+  skipIfSlowMs: 0,
   bashFilter: {
     capturePatterns: [
       "rm",
@@ -81,9 +88,10 @@ function loadConfig(configPath) {
 
 export {
   LANGUAGE_NAMES,
+  LEARNER_LEVEL_NAMES,
   CONFIG_FILENAME,
   getGlobalConfigPath,
   DEFAULT_CONFIG,
   loadConfig
 };
-//# sourceMappingURL=chunk-5NCRRHU7.js.map
+//# sourceMappingURL=chunk-RK7ZFN4W.js.map

package/dist/chunk-RK7ZFN4W.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config/schema.ts"],"sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\n\nexport type Engine = \"ollama\" | \"claude\";\nexport type DetailLevel = \"minimal\" | \"standard\" | \"verbose\";\nexport type RiskLevel = \"none\" | \"low\" | \"medium\" | \"high\";\n\nexport type Language =\n  | \"en\"\n  | \"pt\"\n  | \"es\"\n  | \"fr\"\n  | \"de\"\n  | \"it\"\n  | \"zh\"\n  | \"ja\"\n  | \"ko\";\n\nexport const LANGUAGE_NAMES: Record<Language, string> = {\n  en: \"English\",\n  pt: \"Portuguese\",\n  es: \"Spanish\",\n  fr: \"French\",\n  de: \"German\",\n  it: \"Italian\",\n  zh: \"Chinese\",\n  ja: \"Japanese\",\n  ko: \"Korean\",\n};\n\nexport type LearnerLevel = \"none\" | \"beginner\" | \"intermediate\" | \"regular\";\n\nexport const LEARNER_LEVEL_NAMES: Record<LearnerLevel, string> = {\n  none: \"Never programmed\",\n  beginner: \"Just starting out\",\n  intermediate: \"Read code with difficulty\",\n  regular: \"Code regularly\",\n};\n\nexport interface HooksConfig {\n  edit: boolean;\n  write: boolean;\n  bash: boolean;\n}\n\nexport interface BashFilterConfig {\n  capturePatterns: string[];\n}\n\nexport interface Config {\n  engine: Engine;\n  ollamaModel: string;\n  ollamaUrl: string;\n  detailLevel: DetailLevel;\n  language: Language;\n  learnerLevel: LearnerLevel;\n  hooks: HooksConfig;\n  exclude: string[];\n  skipIfSlowMs: number;\n  bashFilter: BashFilterConfig;\n}\n\nexport interface DeepDiveItem {\n  term: string;\n  explanation: string;\n}\n\nexport interface ExplanationResult {\n  impact: string;\n  howItWorks: string;\n  why: string;\n  deepDive: DeepDiveItem[];\n  isSamePattern: boolean;\n  samePatternNote: string;\n  risk: RiskLevel;\n  riskReason: string;\n}\n\nexport interface HookPayload {\n  session_id: string;\n  transcript_path: string;\n  cwd: string;\n  permission_mode: string;\n  hook_event_name: string;\n  tool_name: string;\n  tool_input: Record<string, unknown>;\n  tool_response: string;\n}\n\nexport const CONFIG_FILENAME = \"code-explainer.config.json\";\n\nexport function getGlobalConfigPath(): string {\n  return join(homedir(), \".code-explainer.config.json\");\n}\n\nexport const DEFAULT_CONFIG: Config = {\n  engine: \"ollama\",\n  ollamaModel: \"qwen3.5:4b\",\n  ollamaUrl: \"http://localhost:11434\",\n  detailLevel: \"standard\",\n  language: \"en\",\n  learnerLevel: \"intermediate\",\n  hooks: {\n    edit: true,\n    write: true,\n    bash: true,\n  },\n  exclude: [\"*.lock\", \"dist/**\", \"node_modules/**\"],\n  skipIfSlowMs: 0,\n  bashFilter: {\n    capturePatterns: [\n      \"rm\",\n      \"mv\",\n      \"cp\",\n      \"mkdir\",\n      \"npm install\",\n      \"pip install\",\n      \"yarn add\",\n      \"pnpm add\",\n      \"chmod\",\n      \"chown\",\n      \"git checkout\",\n      \"git reset\",\n      \"git revert\",\n      \"sed -i\",\n    ],\n  },\n};\n\nfunction mergeConfig(base: Config, overlay: Partial<Config>): Config {\n  return {\n    ...base,\n    ...overlay,\n    hooks: { ...base.hooks, ...(overlay.hooks ?? {}) },\n    bashFilter: {\n      ...base.bashFilter,\n      ...(overlay.bashFilter ?? {}),\n    },\n  };\n}\n\nfunction tryReadJson(path: string): Partial<Config> | null {\n  if (!existsSync(path)) return null;\n  try {\n    return JSON.parse(readFileSync(path, \"utf-8\")) as Partial<Config>;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Load config with three-level resolution, most specific first:\n *   1. Project config (passed as configPath) — overrides everything\n *   2. Global user config (~/.code-explainer.config.json)\n *   3. Built-in defaults\n *\n * A project config that lacks a field falls through to the global; a global\n * that lacks a field falls through to defaults. This lets a global install\n * set everyone's defaults while still allowing per-project overrides.\n */\nexport function loadConfig(configPath: string): Config {\n  const globalConfig = tryReadJson(getGlobalConfigPath());\n  const projectConfig = tryReadJson(configPath);\n\n  let result = DEFAULT_CONFIG;\n  if (globalConfig) result = mergeConfig(result, globalConfig);\n  if (projectConfig) result = mergeConfig(result, projectConfig);\n  return result;\n}\n"],"mappings":";;;AAAA,SAAS,YAAY,oBAAoB;AACzC,SAAS,eAAe;AACxB,SAAS,YAAY;AAiBd,IAAM,iBAA2C;AAAA,EACtD,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AACN;AAIO,IAAM,sBAAoD;AAAA,EAC/D,MAAM;AAAA,EACN,UAAU;AAAA,EACV,cAAc;AAAA,EACd,SAAS;AACX;AAoDO,IAAM,kBAAkB;AAExB,SAAS,sBAA8B;AAC5C,SAAO,KAAK,QAAQ,GAAG,6BAA6B;AACtD;AAEO,IAAM,iBAAyB;AAAA,EACpC,QAAQ;AAAA,EACR,aAAa;AAAA,EACb,WAAW;AAAA,EACX,aAAa;AAAA,EACb,UAAU;AAAA,EACV,cAAc;AAAA,EACd,OAAO;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,IACP,MAAM;AAAA,EACR;AAAA,EACA,SAAS,CAAC,UAAU,WAAW,iBAAiB;AAAA,EAChD,cAAc;AAAA,EACd,YAAY;AAAA,IACV,iBAAiB;AAAA,MACf;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;AAEA,SAAS,YAAY,MAAc,SAAkC;AACnE,SAAO;AAAA,IACL,GAAG;AAAA,IACH,GAAG;AAAA,IACH,OAAO,EAAE,GAAG,KAAK,OAAO,GAAI,QAAQ,SAAS,CAAC,EAAG;AAAA,IACjD,YAAY;AAAA,MACV,GAAG,KAAK;AAAA,MACR,GAAI,QAAQ,cAAc,CAAC;AAAA,IAC7B;AAAA,EACF;AACF;AAEA,SAAS,YAAY,MAAsC;AACzD,MAAI,CAAC,WAAW,IAAI,EAAG,QAAO;AAC9B,MAAI;AACF,WAAO,KAAK,MAAM,aAAa,MAAM,OAAO,CAAC;AAAA,EAC/C,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAYO,SAAS,WAAW,YAA4B;AACrD,QAAM,eAAe,YAAY,oBAAoB,CAAC;AACtD,QAAM,gBAAgB,YAAY,UAAU;AAE5C,MAAI,SAAS;AACb,MAAI,aAAc,UAAS,YAAY,QAAQ,YAAY;AAC3D,MAAI,cAAe,UAAS,YAAY,QAAQ,aAAa;AAC7D,SAAO;AACT;","names":[]}