refactor: extract effective logic into shared module (v0.14.0)

New: src/effective.mjs — pure functions shared between dashboard and tests.
Contains: EFFECTIVE_RULES, hasEffectiveRule, getAncestorScopes,
computeEffectiveSets, getEffectiveItems.

- app.js: imports from window.Effective (served as IIFE by server)
- Unit tests: import directly from effective.mjs (ES module)
- Same code path for production and tests — no re-implementation
- server.mjs: serves effective.mjs with export keywords stripped + IIFE wrapped
- Fixed: renderRuleBar used wrong variable name (category → cat)

35 unit tests pass, all testing the actual production module.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ithiria894

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpware/claude-code-organizer",
-  "version": "0.13.16",
+  "version": "0.14.0",
   "description": "Organize all your Claude Code memories, skills, MCP servers, commands, agents, rules, and hooks — see what loads globally vs per-project, then move items between scopes",
   "type": "module",
   "files": [

package.json

@@ -0,0 +1,137 @@
+/**
+ * effective.mjs — Per-category effective resolution logic.
+ *
+ * Pure functions. No DOM, no UI, no side effects.
+ * Shared between the dashboard frontend (app.js) and unit tests.
+ *
+ * Claude Code does not use one universal scope model. Each category
+ * has its own official rules for availability, precedence, and inheritance.
+ * This module implements those rules.
+ */
+
+/**
+ * Categories that have an official effective rule.
+ * Only these participate in "Show Effective" mode.
+ */
+export const EFFECTIVE_RULES = {
+  skill:   "Available from Personal (~/.claude/skills), Project (.claude/skills), and installed Plugins",
+  mcp:     "Resolved by local > project > user — same-name servers use the narrower scope",
+  command: "Available from User and Project — same-name conflicts are not supported",
+  agent:   "Project-level agents override same-name User agents",
+  config:  "Resolved by precedence: managed > CLI > project local > project shared > user",
+  hook:    "Configured in settings files — resolved by settings precedence",
+  memory:  "Global memories are available in all projects; project memories are specific to this project",
+};
+
+/**
+ * Returns true if a category participates in Show Effective.
+ */
+export function hasEffectiveRule(category) {
+  return category in EFFECTIVE_RULES;
+}
+
+/**
+ * Find scopes whose repoDir is a path ancestor of the given scope.
+ * e.g. /work/company is an ancestor of /work/company/repo-a.
+ *
+ * @param {string} scopeId - The scope to find ancestors for
+ * @param {Array} scopes - All scopes
+ * @returns {Array} Ancestor scopes (deepest first)
+ */
+export function getAncestorScopes(scopeId, scopes) {
+  const scope = scopes.find(s => s.id === scopeId);
+  if (!scope?.repoDir) return [];
+  return scopes.filter(s =>
+    s.repoDir &&
+    s.id !== scopeId &&
+    s.id !== "global" &&
+    scope.repoDir.startsWith(s.repoDir + "/")
+  );
+}
+
+/**
+ * Compute which items are shadowed, conflicted, or from ancestor scopes.
+ *
+ * @param {string} scopeId - Currently selected project scope
+ * @param {Array} allItems - All items from all scopes
+ * @param {Array} scopes - All scopes
+ * @param {Function} keyFn - Function to generate a unique key for an item
+ * @returns {{ shadowedKeys: Set, conflictKeys: Set, ancestorKeys: Set }}
+ */
+export function computeEffectiveSets(scopeId, allItems, scopes, keyFn) {
+  const shadowedKeys = new Set();
+  const conflictKeys = new Set();
+  const ancestorKeys = new Set();
+
+  if (!scopeId || scopeId === "global") {
+    return { shadowedKeys, conflictKeys, ancestorKeys };
+  }
+
+  const projectItems = allItems.filter(i => i.scopeId === scopeId);
+  const globalItems  = allItems.filter(i => i.scopeId === "global");
+
+  // MCP & Agents: narrower scope (project) wins same-name
+  for (const cat of ["mcp", "agent"]) {
+    const projectNames = new Set(
+      projectItems.filter(i => i.category === cat).map(i => i.name)
+    );
+    for (const gi of globalItems.filter(i => i.category === cat)) {
+      if (projectNames.has(gi.name)) shadowedKeys.add(keyFn(gi));
+    }
+  }
+
+  // Commands: both levels available but same-name conflicts are officially unsupported
+  const projCmdNames   = new Set(projectItems.filter(i => i.category === "command").map(i => i.name));
+  const globalCmdNames = new Set(globalItems.filter(i => i.category === "command").map(i => i.name));
+  for (const name of projCmdNames) {
+    if (!globalCmdNames.has(name)) continue;
+    for (const i of [...projectItems, ...globalItems].filter(i => i.category === "command" && i.name === name)) {
+      conflictKeys.add(keyFn(i));
+    }
+  }
+
+  // Ancestor scopes: parent directories whose config/memory items are relevant
+  const ancestors = getAncestorScopes(scopeId, scopes);
+  for (const as of ancestors) {
+    for (const i of allItems.filter(i => i.scopeId === as.id && (i.category === "config" || i.category === "memory"))) {
+      ancestorKeys.add(keyFn(i));
+    }
+  }
+
+  return { shadowedKeys, conflictKeys, ancestorKeys };
+}
+
+/**
+ * Get the effective items for a project scope.
+ * Includes: project items + global items (for participating categories) + ancestor items.
+ *
+ * @param {string} scopeId - Currently selected scope
+ * @param {Array} allItems - All items from all scopes
+ * @param {Array} scopes - All scopes
+ * @returns {Array} Effective items
+ */
+export function getEffectiveItems(scopeId, allItems, scopes) {
+  const projectItems = allItems.filter(i => i.scopeId === scopeId);
+
+  if (scopeId === "global") return projectItems;
+
+  // Global items only for categories with official rules
+  const effectiveGlobal = allItems.filter(
+    i => i.scopeId === "global" && hasEffectiveRule(i.category)
+  );
+
+  // Ancestor scope items (config + memory from path-parent scopes)
+  const ancestorItems = [];
+  for (const as of getAncestorScopes(scopeId, scopes)) {
+    ancestorItems.push(
+      ...allItems.filter(i => i.scopeId === as.id && (i.category === "config" || i.category === "memory"))
+    );
+  }
+
+  return [...projectItems, ...effectiveGlobal, ...ancestorItems];
+}
+
+// Browser: attach to window so app.js can use it via <script> tag
+if (typeof window !== "undefined") {
+  window.Effective = { EFFECTIVE_RULES, hasEffectiveRule, getAncestorScopes, computeEffectiveSets, getEffectiveItems };
+}

src/effective.mjs

@@ -858,6 +858,16 @@ async function handleRequest(req, res) {
   if (path === "/app.js") {
     return serveFile(res, join(UI_DIR, "app.js"));
   }
+  if (path === "/effective.mjs") {
+    // Serve as browser-compatible IIFE: strip ES exports, wrap in scope
+    // Node.js unit tests import the .mjs directly; browser uses window.Effective
+    try {
+      const content = await readFile(join(import.meta.dirname, "effective.mjs"), "utf-8");
+      const browserCode = "(function(){\n" + content.replace(/^export /gm, "") + "\n})();";
+      res.writeHead(200, { "Content-Type": "application/javascript" });
+      return res.end(browserCode);
+    } catch { res.writeHead(404); return res.end(); }
+  }
 
   // Suppress favicon 404
   if (path === "/favicon.ico") {

src/server.mjs

@@ -6,6 +6,13 @@
  * move, delete, and undo behaviors.
  */
 
+// Effective resolution logic — loaded from /effective.mjs before app.js
+const { EFFECTIVE_RULES, hasEffectiveRule, getAncestorScopes: _getAncestorScopes,
+        computeEffectiveSets: _computeEffectiveSets, getEffectiveItems } = window.Effective;
+
+// Helper: get effectiveRule for a category (returns string or undefined)
+function getEffectiveRule(category) { return EFFECTIVE_RULES[category] || null; }
+
 let data = null;
 let activeFilters = new Set();
 let selectedItem = null;
@@ -37,28 +44,17 @@ const uiState = {
 const CATEGORY_ORDER = ["skill", "memory", "mcp", "command", "agent", "plan", "rule", "config", "hook", "plugin", "session"];
 
 const CATEGORIES = {
-  memory: { icon: "🧠", label: "Memories", filterLabel: "Memories", group: "memory",
-    effectiveRule: "Global memories are available in all projects; project memories are specific to this project" },
-  skill:  { icon: "⚡", label: "Skills",   filterLabel: "Skills",   group: "skill",
-    effectiveRule: "Available from Personal (~/.claude/skills), Project (.claude/skills), and installed Plugins" },
-  session:{ icon: "💬", label: "Sessions", filterLabel: "Sessions", group: null,
-    effectiveRule: null }, // project-only, no inheritance
-  mcp:    { icon: "🔌", label: "MCP Servers", filterLabel: "MCP",  group: "mcp",
-    effectiveRule: "Resolved by local > project > user — same-name servers use the narrower scope" },
-  command:{ icon: "▶️", label: "Commands", filterLabel: "Commands", group: "command",
-    effectiveRule: "Available from User and Project — same-name conflicts are not supported" },
-  agent:  { icon: "🤖", label: "Agents",   filterLabel: "Agents",  group: "agent",
-    effectiveRule: "Project-level agents override same-name User agents" },
-  plan:   { icon: "📐", label: "Plans",    filterLabel: "Plans",   group: "plan",
-    effectiveRule: null }, // no clear official scope rule
-  rule:   { icon: "📏", label: "Rules",    filterLabel: "Rules",   group: null,
-    effectiveRule: null }, // no clear official scope rule
-  config: { icon: "⚙️", label: "Config",   filterLabel: "Config",  group: null,
-    effectiveRule: "Resolved by precedence: managed > CLI > project local > project shared > user" },
-  hook:   { icon: "🪝", label: "Hooks",    filterLabel: "Hooks",   group: null,
-    effectiveRule: "Configured in settings files — resolved by settings precedence" },
-  plugin: { icon: "🧩", label: "Plugins",  filterLabel: "Plugins", group: null,
-    effectiveRule: null }, // global-only, no inheritance rule
+  memory: { icon: "🧠", label: "Memories", filterLabel: "Memories", group: "memory" },
+  skill:  { icon: "⚡", label: "Skills",   filterLabel: "Skills",   group: "skill" },
+  session:{ icon: "💬", label: "Sessions", filterLabel: "Sessions", group: null },
+  mcp:    { icon: "🔌", label: "MCP Servers", filterLabel: "MCP",  group: "mcp" },
+  command:{ icon: "▶️", label: "Commands", filterLabel: "Commands", group: "command" },
+  agent:  { icon: "🤖", label: "Agents",   filterLabel: "Agents",  group: "agent" },
+  plan:   { icon: "📐", label: "Plans",    filterLabel: "Plans",   group: "plan" },
+  rule:   { icon: "📏", label: "Rules",    filterLabel: "Rules",   group: null },
+  config: { icon: "⚙️", label: "Config",   filterLabel: "Config",  group: null },
+  hook:   { icon: "🪝", label: "Hooks",    filterLabel: "Hooks",   group: null },
+  plugin: { icon: "🧩", label: "Plugins",  filterLabel: "Plugins", group: null },
 };
 
 const ITEM_ICONS = {
@@ -696,7 +692,7 @@ function renderPills() {
     : data?.items || [];
   if (showEffective && selectedScopeId && selectedScopeId !== "global") {
     const globalItems = (data?.items || []).filter(
-      (i) => i.scopeId === "global" && Boolean(CATEGORIES[i.category]?.effectiveRule)
+      (i) => i.scopeId === "global" && Boolean(getEffectiveRule(i.category))
     );
     scopeItems = [...scopeItems, ...globalItems];
   }
@@ -712,13 +708,13 @@ function renderPills() {
     { key: "all", label: "All", icon: "◌", count: scopeTotal, tip: null },
     ...CATEGORY_ORDER.map((category) => {
       const config = CATEGORIES[category] || { icon: "📄", filterLabel: capitalize(category) };
-      const hasRule = Boolean(config.effectiveRule);
+      const hasRule = Boolean(getEffectiveRule(category));
       return {
         key: category,
         label: config.filterLabel,
         icon: config.icon,
         count: scopeCounts[category] || 0,
-        tip: config.effectiveRule || (showEffective ? NO_RULE_TIP : null),
+        tip: getEffectiveRule(category) || (showEffective ? NO_RULE_TIP : null),
         noRule: showEffective && !hasRule,
       };
     }),
@@ -777,7 +773,7 @@ function renderRuleBar() {
   const rows = CATEGORY_ORDER.map(cat => {
     const config = CATEGORIES[cat];
     if (!config) return "";
-    const rule = config.effectiveRule;
+    const rule = getEffectiveRule(cat);
     const noRule = !rule;
     return `<div class="rule-row${noRule ? " rule-none" : ""}">
       <span class="rule-cat">${config.icon} ${esc(config.filterLabel)}</span>
@@ -1096,7 +1092,7 @@ function renderEffectiveBehavior(item) {
           : "This memory is stored in this project's memory directory.";
       break;
     default:
-      why = CATEGORIES[item.category]?.effectiveRule || "";
+      why = getEffectiveRule(item.category) || "";
   }
 
   if (!why) { wrap.classList.add("hidden"); return; }
@@ -2510,82 +2506,37 @@ function findVisibleScopeInTree(scope) {
  * and which items have unresolvable name conflicts (commands).
  * Called whenever showEffective toggles or scope changes.
  */
+// getAncestorScopes — delegated to shared effective.mjs (_getAncestorScopes)
+
 /**
- * Returns scopes whose repoDir is a path ancestor of the given scope's repoDir.
- * e.g. if scopeId is /home/user/company/repo, returns the scope for /home/user/company if it exists.
+ * Wrapper: delegates to shared effective.mjs module for computation,
+ * then stores results in app-level state (effectiveShadowedKeys etc).
  */
-function getAncestorScopes(scopeId) {
-  const scope = getScopeById(scopeId);
-  if (!scope?.repoDir) return [];
-  return (data?.scopes || []).filter(s =>
-    s.repoDir &&
-    s.id !== scopeId &&
-    s.id !== "global" &&
-    scope.repoDir.startsWith(s.repoDir + "/")
-  );
-}
-
 function computeEffectiveSets(scopeId) {
-  effectiveShadowedKeys = new Set();
-  effectiveConflictKeys = new Set();
-  effectiveAncestorKeys = new Set();
-  if (!showEffective || !scopeId || scopeId === "global") return;
-
-  const projectItems = getItemsForScope(scopeId);
-  const globalItems  = getItemsForScope("global");
-
-  // MCP & Agents: narrower scope (project) wins same-name
-  for (const cat of ["mcp", "agent"]) {
-    const projectNames = new Set(
-      projectItems.filter(i => i.category === cat).map(i => i.name)
-    );
-    for (const gi of globalItems.filter(i => i.category === cat)) {
-      if (projectNames.has(gi.name)) effectiveShadowedKeys.add(itemKey(gi));
-    }
-  }
-
-  // Commands: both levels available but same-name conflicts are officially unsupported
-  const projCmdNames   = new Set(projectItems.filter(i => i.category === "command").map(i => i.name));
-  const globalCmdNames = new Set(globalItems.filter(i => i.category === "command").map(i => i.name));
-  for (const name of projCmdNames) {
-    if (!globalCmdNames.has(name)) continue;
-    for (const i of [...projectItems, ...globalItems].filter(i => i.category === "command" && i.name === name)) {
-      effectiveConflictKeys.add(itemKey(i));
-    }
-  }
-
-  // Ancestor scopes: scopes whose repoDir is a path parent of this project.
-  // Their config items (especially CLAUDE.md) are ancestor-loaded by Claude Code.
-  const ancestorScopes = getAncestorScopes(scopeId);
-  for (const as of ancestorScopes) {
-    for (const i of getItemsForScope(as.id).filter(i => i.category === "config" || i.category === "memory")) {
-      effectiveAncestorKeys.add(itemKey(i));
-    }
+  if (!showEffective || !scopeId || scopeId === "global") {
+    effectiveShadowedKeys = new Set();
+    effectiveConflictKeys = new Set();
+    effectiveAncestorKeys = new Set();
+    return;
   }
+  const result = _computeEffectiveSets(scopeId, data?.items || [], data?.scopes || [], itemKey);
+  effectiveShadowedKeys = result.shadowedKeys;
+  effectiveConflictKeys = result.conflictKeys;
+  effectiveAncestorKeys = result.ancestorKeys;
 }
 
 function getVisibleItemsForScope(scopeId) {
   const ownItems = getItemsForScope(scopeId).filter((item) => itemVisibleInMain(item));
   if (!showEffective || scopeId === "global") return ownItems;
 
-  // Only add global items for categories that have an official effective rule
-  const globalItems = getItemsForScope("global").filter((item) => {
-    if (!itemMatchesFilters(item) || !itemMatchesSearch(item)) return false;
-    return Boolean(CATEGORIES[item.category]?.effectiveRule);
-  });
-
-  // Add ancestor scope items (CLAUDE.md + memories from path-parent projects)
-  const ancestorItems = [];
-  for (const as of getAncestorScopes(scopeId)) {
-    for (const item of getItemsForScope(as.id)) {
-      if ((item.category === "config" || item.category === "memory") &&
-          itemMatchesFilters(item) && itemMatchesSearch(item)) {
-        ancestorItems.push(item);
-      }
-    }
-  }
-
-  return [...ownItems, ...globalItems, ...ancestorItems];
+  // Use shared module for effective resolution, then apply UI filters
+  const allEffective = getEffectiveItems(scopeId, data?.items || [], data?.scopes || []);
+  // Filter to non-own items that pass current UI filters
+  const ownKeys = new Set(ownItems.map(i => itemKey(i)));
+  const extra = allEffective.filter(i =>
+    !ownKeys.has(itemKey(i)) && itemMatchesFilters(i) && itemMatchesSearch(i)
+  );
+  return [...ownItems, ...extra];
 }
 
 function itemVisibleInMain(item) {

src/ui/app.js

@@ -239,6 +239,7 @@ <h3>Delete Item</h3>
     // Server auto-shuts down when all tabs close.
     new EventSource("/heartbeat");
   </script>
+  <script src="/effective.mjs"></script>
   <script src="/app.js"></script>
 </body>
 </html>