agent-skill-doctor 0.1.0

package/src/doctor/phase2.js

@@ -0,0 +1,261 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const path = require('node:path');
+
+function sha256(input) {
+  return crypto.createHash('sha256').update(String(input)).digest('hex');
+}
+
+function normalizePath(input) {
+  return path.resolve(String(input || '')).replaceAll('\\\\', '/');
+}
+
+function normalizeSourceUrl(url) {
+  return String(url || '')
+    .trim()
+    .replace(/^https?:\/\//i, '')
+    .replace(/\.git$/i, '')
+    .replace(/\/$/, '')
+    .toLowerCase();
+}
+
+function buildSkillIdentityKey(skill) {
+  if (skill.upstreamSkillId || skill.upstream_skill_id) {
+    return `upstream:${skill.upstreamSkillId || skill.upstream_skill_id}`;
+  }
+
+  const sourceUrl = skill.source?.url || skill.source_url;
+  const sourceSubdir = skill.source?.subdir || skill.source_subdir || '';
+  const slug = skill.slug;
+  if (sourceUrl && slug) {
+    return `source:${normalizeSourceUrl(sourceUrl)}:${sourceSubdir}:${slug}`;
+  }
+
+  const root = skill.location?.root || skill.root || skill.root_path;
+  if (root && slug) {
+    return `path:${normalizePath(root)}:${slug}`;
+  }
+
+  const contentHash = skill.hashes?.contentSha256 || skill.content_hash || skill.contentHash || 'unknown-hash';
+  const localPath = skill.location?.path || skill.local_path || skill.path || 'unknown-path';
+  return `hash:${contentHash}:${normalizePath(localPath)}`;
+}
+
+function buildParticipantIdentityKey(skills) {
+  return sha256(skills.map(buildSkillIdentityKey).sort().join('\n'));
+}
+
+function sourceKey(skill) {
+  const sourceUrl = skill.source?.url || skill.source_url;
+  if (!sourceUrl) return null;
+  const subdir = skill.source?.subdir || skill.source_subdir || '';
+  return `${normalizeSourceUrl(sourceUrl)}:${subdir}:${skill.slug || ''}`;
+}
+
+function contentHash(skill) {
+  return skill.hashes?.contentSha256 || skill.content_hash || skill.contentHash || null;
+}
+
+function sourceRef(skill) {
+  return skill.sourceCommit || skill.source_commit || skill.source?.commit || skill.sourceRef || skill.source_ref || skill.source?.ref || null;
+}
+
+function modifiedTime(skill) {
+  return Date.parse(skill.modifiedAt || skill.modified_at || skill.updatedAt || 0) || 0;
+}
+
+function sourceTrustScore(skill) {
+  const type = skill.source?.type || skill.source_type;
+  const url = normalizeSourceUrl(skill.source?.url || skill.source_url);
+  if (type === 'marketplace') return 1.0;
+  if (/^github\.com\/(anthropics|openai|github|google-gemini)\//.test(url)) return 0.9;
+  if (/^github\.com\/[^/]+\//.test(url)) return 0.6;
+  const rootType = skill.location?.rootType || skill.root_type;
+  if (rootType === 'project_local') return 0.5;
+  if (rootType === 'agent_global') return 0.4;
+  return 0.2;
+}
+
+function locationScore(skill) {
+  const rootType = skill.location?.rootType || skill.root_type;
+  if (rootType === 'central_library') return 1;
+  if (rootType === 'project_local') return 0.7;
+  if (rootType === 'agent_global') return 0.5;
+  return 0.2;
+}
+
+function recencyScore(skill) {
+  const time = modifiedTime(skill);
+  if (!time) return 0;
+  const ageDays = Math.max(0, (Date.now() - time) / 86_400_000);
+  return Math.max(0, 1 - ageDays / 365);
+}
+
+function usageScore(skill) {
+  const usage = skill.usage || {};
+  const agentCount = usage.installedInAgents?.length || 0;
+  const projectCount = usage.installedInProjects?.length || 0;
+  return Math.min(1, (usage.presetCount || 0) * 0.25 + agentCount * 0.25 + projectCount * 0.25);
+}
+
+function descriptionScore(skill) {
+  const desc = String(skill.description || '').trim();
+  if (!desc) return 0;
+  return Math.min(1, desc.length / 120);
+}
+
+function pinnedScore(skill) {
+  const usage = skill.usage || {};
+  const tags = skill.tags || [];
+  return usage.manuallyPinned || tags.includes('keep') || tags.includes('core') ? 1 : 0;
+}
+
+function canonicalScore(skill) {
+  if (pinnedScore(skill) === 1) return Number.MAX_SAFE_INTEGER;
+  return (
+    sourceTrustScore(skill) * 0.25 +
+    recencyScore(skill) * 0.20 +
+    usageScore(skill) * 0.20 +
+    descriptionScore(skill) * 0.15 +
+    locationScore(skill) * 0.10 +
+    pinnedScore(skill) * 0.10
+  );
+}
+
+function chooseCanonical(skills) {
+  return [...skills].sort((a, b) => {
+    const scoreA = canonicalScore(a);
+    const scoreB = canonicalScore(b);
+    return scoreB - scoreA || String(a.slug || a.name).localeCompare(String(b.slug || b.name));
+  })[0];
+}
+
+function groupBy(items, keyFn) {
+  const groups = new Map();
+  for (const item of items) {
+    const key = keyFn(item);
+    if (!key) continue;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(item);
+  }
+  return [...groups.entries()].filter(([, members]) => members.length > 1);
+}
+
+function duplicateGroupId(strategy, skills) {
+  return sha256(`${strategy}:${buildParticipantIdentityKey(skills)}`);
+}
+
+function makeDuplicateGroup(strategy, confidence, skills, reason) {
+  const sorted = [...skills].sort((a, b) => buildSkillIdentityKey(a).localeCompare(buildSkillIdentityKey(b)));
+  const canonical = chooseCanonical(sorted);
+  return {
+    id: duplicateGroupId(strategy, sorted),
+    strategy,
+    confidence,
+    reason,
+    canonicalSkillId: canonical.id,
+    members: sorted.map(skill => ({
+      skillId: skill.id,
+      role: skill.id === canonical.id ? 'canonical' : 'candidate',
+      confidence,
+    })),
+    skills: sorted,
+  };
+}
+
+function detectDuplicateGroups(skills) {
+  const seen = new Set();
+  const groups = [];
+
+  const add = (strategy, confidence, grouped, reason) => {
+    for (const [, members] of grouped) {
+      const group = makeDuplicateGroup(strategy, confidence, members, reason);
+      if (seen.has(group.id)) continue;
+      seen.add(group.id);
+      groups.push(group);
+    }
+  };
+
+  add('exact_duplicate', 1.0, groupBy(skills, contentHash), 'identical content hash');
+  add('same_source_duplicate', 0.95, groupBy(skills, sourceKey), 'same source URL, subdir, and slug');
+  add(
+    'same_name_duplicate',
+    0.7,
+    groupBy(skills, skill => {
+      const sameSlug = skills.filter(other => other.slug === skill.slug);
+      const distinctHashes = new Set(sameSlug.map(contentHash).filter(Boolean));
+      return distinctHashes.size > 1 ? skill.slug : null;
+    }),
+    'same normalized skill name with different content'
+  );
+
+  return groups;
+}
+
+function versionDriftId(skills, key) {
+  return sha256(`version_drift:${buildParticipantIdentityKey(skills)}:${key || ''}`);
+}
+
+function detectVersionDrift(skills) {
+  const candidates = [
+    ...groupBy(skills, sourceKey),
+    ...groupBy(skills, skill => skill.slug),
+  ];
+  const seen = new Set();
+  const findings = [];
+
+  for (const [key, members] of candidates) {
+    const hashes = new Set(members.map(contentHash).filter(Boolean));
+    const refs = new Set(members.map(sourceRef).filter(Boolean));
+    if (hashes.size <= 1 && refs.size <= 1) continue;
+
+    const sorted = [...members].sort((a, b) => buildSkillIdentityKey(a).localeCompare(buildSkillIdentityKey(b)));
+    const id = versionDriftId(sorted, key);
+    if (seen.has(id)) continue;
+    seen.add(id);
+
+    findings.push({
+      id,
+      type: 'version_drift',
+      severity: 'medium',
+      detectorId: 'drift-detector',
+      ruleId: 'content-or-ref-drift',
+      title: 'Version drift detected',
+      description: `Detected multiple variants for ${key || 'a skill group'} with different content hashes or source refs.`,
+      skills: sorted,
+      links: sorted.map(skill => ({
+        skillId: skill.id,
+        role: roleForDrift(skill),
+      })),
+      evidence: sorted.map(skill => ({
+        slug: skill.slug,
+        path: skill.location?.path || skill.local_path || skill.path,
+        contentHash: contentHash(skill),
+        sourceRef: sourceRef(skill),
+      })),
+      recommendation: 'Review differences and either keep a pinned version or sync from the central library.',
+    });
+  }
+
+  return findings;
+}
+
+function roleForDrift(skill) {
+  const rootType = skill.location?.rootType || skill.root_type;
+  if (rootType === 'central_library') return 'central';
+  if (rootType === 'project_local') return 'project';
+  if (skill.location?.agent || skill.agent) return 'agent';
+  return 'local';
+}
+
+module.exports = {
+  buildSkillIdentityKey,
+  buildParticipantIdentityKey,
+  chooseCanonical,
+  detectDuplicateGroups,
+  detectVersionDrift,
+  normalizeSourceUrl,
+  sourceTrustScore,
+  sourceKey,
+};

package/src/doctor/risk-lite.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { buildParticipantIdentityKey } = require('./phase2');
+
+function sha256(input) {
+  return crypto.createHash('sha256').update(String(input)).digest('hex');
+}
+
+function normalizeText(text) {
+  return String(text || '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function normalizeAnchor(text) {
+  return normalizeText(text).slice(0, 300);
+}
+
+function getMatchedPatternId(ruleId, pattern, index) {
+  if (pattern && pattern.id && /^[a-z0-9-]{1,64}$/.test(pattern.id)) return pattern.id;
+  const text = typeof pattern === 'string' ? pattern : String((pattern && (pattern.regex || pattern.text || pattern.value)) || '');
+  if (text) return `${ruleId}_${sha256(text).slice(0, 8)}`;
+  return `${ruleId}_${index}`;
+}
+
+function loadJsonRules(rulesDir) {
+  const rules = [];
+  if (!rulesDir || !fs.existsSync(rulesDir)) return rules;
+  for (const file of fs.readdirSync(rulesDir).sort()) {
+    if (!file.endsWith('.json')) continue;
+    const parsed = JSON.parse(fs.readFileSync(path.join(rulesDir, file), 'utf8'));
+    if (parsed.version !== 1) throw new Error(`Unsupported rule file version in ${file}`);
+    for (const rule of parsed.rules || []) {
+      const ids = new Set();
+      for (const pattern of rule.patterns || []) {
+        if (!pattern || typeof pattern !== 'object' || !pattern.id || !/^[a-z0-9-]{1,64}$/.test(pattern.id)) continue;
+        if (ids.has(pattern.id)) throw new Error(`Duplicate pattern.id "${pattern.id}" in rule "${rule.id}"`);
+        ids.add(pattern.id);
+      }
+      rules.push({ ...rule, file });
+    }
+  }
+  return rules;
+}
+
+function isTextLike(filePath) {
+  return /\.(md|txt|json|ya?ml|toml|js|ts|py|rs|sh|bash|zsh)$/i.test(filePath);
+}
+
+function lineNumberAt(text, index) {
+  return text.slice(0, index).split(/\r?\n/).length;
+}
+
+function findPattern(original, lower, pattern) {
+  if (pattern && typeof pattern === 'object' && pattern.regex) {
+    const re = new RegExp(pattern.regex, pattern.flags || 'i');
+    const match = re.exec(original);
+    if (!match) return null;
+    return { index: match.index, text: match[0] };
+  }
+
+  const needle = String((pattern && (pattern.text || pattern.value)) || pattern || '').toLowerCase();
+  if (!needle) return null;
+  const index = lower.indexOf(needle);
+  if (index < 0) return null;
+  return { index, text: original.slice(index, index + needle.length) };
+}
+
+function scanSkillForRisks(skill, rules) {
+  // Collect all matches grouped by rule+pattern to deduplicate
+  const matchMap = new Map(); // key: `${ruleId}:${patternId}` -> { rule, patternId, evidence[] }
+  for (const file of skill.files || []) {
+    const filePath = file.path;
+    if (!filePath || !fs.existsSync(filePath) || !isTextLike(filePath)) continue;
+    const original = fs.readFileSync(filePath, 'utf8');
+    const lower = original.toLowerCase();
+    const relativeFile = file.relativePath || path.basename(filePath);
+
+    for (const rule of rules) {
+      const patterns = rule.patterns || [];
+      for (let i = 0; i < patterns.length; i++) {
+        const pattern = patterns[i];
+        const match = findPattern(original, lower, pattern);
+        if (!match) continue;
+        const matched = match.text;
+        const patternId = getMatchedPatternId(rule.id, pattern, i);
+        const line = lineNumberAt(original, match.index);
+        const mapKey = `${rule.id}:${patternId}`;
+        if (!matchMap.has(mapKey)) {
+          matchMap.set(mapKey, { rule, patternId, evidence: [] });
+        }
+        matchMap.get(mapKey).evidence.push({
+          file: relativeFile, lineStart: line, lineEnd: line,
+          text: matched, anchor: normalizeAnchor(matched),
+        });
+      }
+    }
+  }
+
+  // Generate one finding per rule+pattern per skill
+  const findings = [];
+  const participantKey = buildParticipantIdentityKey([skill]);
+  for (const [, { rule, patternId, evidence }] of matchMap) {
+    const signature = sha256(`${rule.id}:${patternId}:${evidence.map(e => `${e.file}:${e.lineStart}`).join(',')}`);
+    const id = sha256(`${participantKey}:risk:risk-detector:${rule.id}:${signature}`);
+    findings.push({
+      id,
+      type: 'risk',
+      severity: rule.severity || 'medium',
+      detectorId: 'risk-detector',
+      ruleId: rule.id,
+      title: rule.title || 'Risk pattern detected',
+      description: `${rule.description || 'Risk pattern detected.'} [matched: ${patternId}]`,
+      signature,
+      evidence: evidence.map(e => ({ ...e, occurrenceId: sha256(`${id}:${e.file}:${e.lineStart}`) })),
+      recommendation: rule.recommendation || 'Review the skill before enabling it automatically.',
+      skillId: skill.id,
+    });
+  }
+  return findings;
+}
+
+module.exports = { getMatchedPatternId, loadJsonRules, scanSkillForRisks };

package/src/doctor/rules.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+function sha256(input) {
+  return crypto.createHash('sha256').update(String(input)).digest('hex');
+}
+
+function normalizeText(text) {
+  return String(text || '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function normalizeAnchor(text) {
+  return normalizeText(text).slice(0, 300);
+}
+
+function validPatternId(id) {
+  return /^[a-z0-9-]{1,64}$/.test(String(id || ''));
+}
+
+function matchedPatternId(ruleId, pattern, index) {
+  if (pattern && typeof pattern === 'object' && validPatternId(pattern.id)) return pattern.id;
+  const text = typeof pattern === 'string' ? pattern : (pattern && (pattern.regex || pattern.text));
+  if (text) return `${ruleId}_${sha256(text).slice(0, 8)}`;
+  return `${ruleId}_${index}`;
+}
+
+const DEFAULT_RISK_RULES = [];
+
+const DEFAULT_CONFLICT_RULES = [
+  {
+    id: 'package-manager-conflict',
+    type: 'opposite_instruction',
+    severity: 'medium',
+    title: 'Conflicting package manager instructions',
+    alternatives: [['use npm', 'npm install'], ['use pnpm', 'pnpm install'], ['use yarn', 'yarn install']],
+    recommendation: 'Keep only one package-manager convention skill per project or preset.'
+  },
+  {
+    id: 'output-format-conflict',
+    type: 'output_format_conflict',
+    severity: 'medium',
+    title: 'Conflicting output format instructions',
+    alternatives: [['respond in json', 'output json only'], ['respond in markdown', 'output markdown only']],
+    recommendation: 'Scope output-format skills to specific projects or presets.'
+  }
+];
+
+module.exports = {
+  DEFAULT_RISK_RULES,
+  DEFAULT_CONFLICT_RULES,
+  matchedPatternId,
+  normalizeAnchor,
+  normalizeText,
+  sha256,
+  validPatternId
+};

package/src/doctor/zombie.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const { buildSkillIdentityKey, buildParticipantIdentityKey } = require('./phase2');
+
+function sha256(input) {
+  return crypto.createHash('sha256').update(String(input)).digest('hex');
+}
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+/**
+ * Simple description quality score (0-100).
+ * Checks for presence, length, and useful content indicators.
+ */
+function descriptionQuality(skill) {
+  const desc = String(skill.description || '').trim();
+  if (!desc) return 0;
+  let score = 40; // has description
+  if (desc.length >= 20) score += 20;
+  if (desc.length >= 60) score += 10;
+  // Check for trigger/usage indicators
+  const lower = desc.toLowerCase();
+  if (/\b(when|use |trigger|if |run |invoke)\b/.test(lower)) score += 10;
+  // Check for I/O indicators
+  if (/\b(input|output|return|result|respond|answer)\b/.test(lower)) score += 10;
+  // Check for action verbs
+  if (/\b(scan|detect|check|analyze|generate|create|build|find)\b/.test(lower)) score += 10;
+  return clamp(score, 0, 100);
+}
+
+const OFFICIAL_SOURCE_RE = /github\.com\/(anthropics|openai|github|google-gemini)\//i;
+const PLUGIN_SOURCE_RE = /superpowers|using-superpowers/i;
+
+/**
+ * Determine source protection level for zombie scoring.
+ * Returns: 'official' | 'plugin' | 'thirdParty' | null
+ */
+function sourceProtectionLevel(skill) {
+  const sourceUrl = skill.source?.url || '';
+  const plugin = skill._sourcePlugin || '';
+  if (OFFICIAL_SOURCE_RE.test(sourceUrl)) return 'official';
+  if (plugin && PLUGIN_SOURCE_RE.test(plugin)) return 'plugin';
+  if (plugin) return 'thirdParty';
+  return null;
+}
+
+/**
+ * Compute zombie score for a skill (0.0 - 1.0).
+ *
+ * Early return 0 for pinned / keep / core / system / official-source skills.
+ * Plugin-source skills get 50% score reduction. Third-party get 25% reduction.
+ *
+ * Score components:
+ *   presetCount === 0                  : +0.25
+ *   installedInAgents.length === 0     : +0.20
+ *   installedInProjects.length === 0   : +0.20
+ *   !hasRecentModification             : +0.15
+ *   !lastActivityLogAt                 : +0.15
+ *   descriptionQuality < 40            : +0.05
+ */
+function computeZombieScore(skill) {
+  const usage = skill.usage || {};
+  const tags = skill.tags || [];
+
+  // Early return for protected skills
+  if (usage.manuallyPinned || tags.includes('keep') || tags.includes('core') || tags.includes('system')) {
+    return 0.0;
+  }
+
+  // Official sources are fully protected
+  const protection = sourceProtectionLevel(skill);
+  if (protection === 'official') return 0.0;
+
+  let score = 0;
+  if ((usage.presetCount || 0) === 0) score += 0.25;
+  if (!usage.installedInAgents || usage.installedInAgents.length === 0) score += 0.20;
+  if (!usage.installedInProjects || usage.installedInProjects.length === 0) score += 0.20;
+  if (!usage.hasRecentModification) score += 0.15;
+  if (!usage.lastActivityLogAt) score += 0.15;
+  if (descriptionQuality(skill) < 40) score += 0.05;
+
+  // Reduce score for plugin/third-party sources
+  if (protection === 'plugin') score *= 0.5;
+  else if (protection === 'thirdParty') score *= 0.75;
+
+  return clamp(score, 0, 1);
+}
+
+/**
+ * Get zombie severity label.
+ */
+function zombieLevel(score) {
+  if (score >= 0.8) return 'strong_suspicious_zombie';
+  if (score >= 0.6) return 'suspicious_zombie';
+  if (score >= 0.4) return 'low_activity';
+  return 'normal';
+}
+
+/**
+ * Get human-readable zombie level description.
+ */
+function zombieLevelDescription(level) {
+  switch (level) {
+    case 'strong_suspicious_zombie': return 'Strong suspected zombie skill - very low activity signals.';
+    case 'suspicious_zombie': return 'Suspected zombie skill - low activity signals.';
+    case 'low_activity': return 'Low activity skill - may be unused.';
+    default: return 'Normal activity level.';
+  }
+}
+
+/**
+ * Detect zombie skills from a list of skill records.
+ * Returns findings for skills with zombie score >= 0.4.
+ *
+ * @param {Array} skills
+ * @returns {Array} zombie findings
+ */
+function detectZombies(skills) {
+  const findings = [];
+
+  for (const skill of skills) {
+    const score = computeZombieScore(skill);
+    if (score < 0.4) continue;
+
+    const level = zombieLevel(score);
+    const participantKey = buildParticipantIdentityKey([skill]);
+    const reasons = [];
+
+    const usage = skill.usage || {};
+    const factors = [];
+    if ((usage.presetCount || 0) === 0) { reasons.push('not in any preset'); factors.push('presetCount==0 (+0.25)'); }
+    if (!usage.installedInAgents || usage.installedInAgents.length === 0) { reasons.push('not installed in any agent'); factors.push('noAgents (+0.20)'); }
+    if (!usage.installedInProjects || usage.installedInProjects.length === 0) { reasons.push('not installed in any project'); factors.push('noProjects (+0.20)'); }
+    if (!usage.hasRecentModification) { reasons.push('no recent modifications'); factors.push('noModification (+0.15)'); }
+    if (!usage.lastActivityLogAt) { reasons.push('no activity log entries'); factors.push('noActivityLog (+0.15)'); }
+    if (descriptionQuality(skill) < 40) { reasons.push('poor description quality'); factors.push('lowDescriptionQuality (+0.05)'); }
+
+    // Source protection discount
+    const protection = sourceProtectionLevel(skill);
+    if (protection === 'plugin') factors.push('sourcePlugin (*0.50)');
+    else if (protection === 'thirdParty') factors.push('sourceThirdParty (*0.75)');
+
+    const reasonText = reasons.join('; ');
+    const factorText = factors.join('; ');
+    const signature = sha256(`zombie:${level}:${Math.round(score * 100)}:${skill.slug || ''}`);
+    const id = sha256(`${participantKey}:zombie:zombie-detector:${level}:${signature}`);
+
+    findings.push({
+      id,
+      type: 'zombie',
+      severity: score >= 0.8 ? 'medium' : 'low',
+      detectorId: 'zombie-detector',
+      ruleId: level,
+      title: `Zombie candidate: ${skill.name || skill.slug}`,
+      description: `${zombieLevelDescription(level)} Score: ${score.toFixed(2)}. Factors: ${factorText}.`,
+      signature,
+      evidence: [{
+        file: skill.location?.path || skill.local_path || '',
+        text: `${skill.slug}: score=${score.toFixed(2)}, level=${level}, reasons=${reasonText}`,
+        anchor: `${skill.slug} zombie ${level}`,
+      }],
+      recommendation: 'Review whether this skill is still needed. Consider removing from presets or disabling if unused.',
+      score,
+      level,
+      skills: [skill],
+      links: [{ skillId: skill.id, role: 'primary' }],
+    });
+  }
+
+  // Sort by score descending
+  findings.sort((a, b) => (b.score || 0) - (a.score || 0));
+  return findings;
+}
+
+module.exports = { computeZombieScore, zombieLevel, zombieLevelDescription, detectZombies, descriptionQuality };