cli.ts

#!/usr/bin/env node
/**
 * Markdown Reference Validator
 *
 * Checks every skill's markdown files to ensure:
 *   1. Every local markdown link points to an actual file.
 *   2. Every local markdown link resolves to a path inside the skill's
 *      own directory.
 *   3. No local markdown link points to a directory instead of a file.
 *   4. All files in the skill's "references" directory are reachable
 *      through a chain of markdown links starting from SKILL.md.
 *
 * Usage:
 *   npm run references                       # Validate all skills
 *   npm run references <pluginDirname> <skill>      # Validate a single skill. Both <pluginDirname> and <skill> are optional, but <skill> can only be used if <pluginDirname> is provided. Note that pluginDirname is the name of the directory containing the plugin files, not the name of the plugin. For example, use "azure-skills" instead of "azure".
 *   npm run references -- --json             # Emit validation results as JSON
 *   npm run references -- --list             # Emit every discovered local
 *                                            # and remote link as JSON
 *
 * Tip: when redirecting JSON output to a file, pass `--silent` to npm so it
 * does not prepend its own banner lines (which would corrupt the JSON):
 *
 *   npm run --silent references -- --list > out.json
 */

import { resolve, relative, normalize, dirname } from "node:path";
import { existsSync, readdirSync, statSync } from "node:fs";
import { extractLocalLinks, extractRemoteLinks } from "./link-helpers.js";
import { parseArgs } from "node:util";
import { getRepoRoot, listPlugins, listSkills, SkillRef } from "../shared/skill-helper.js";

// ── Paths ────────────────────────────────────────────────────────────────────

const REPO_ROOT = getRepoRoot();

const FILTERED_REMOTE_HOSTS = new Set<string>([]);
const FILTERED_REMOTE_HOST_SUFFICES: string[] = [];

function shouldPrintRemoteHost(host: string): boolean {
  const normalizedHost = host.toLowerCase().replace(/:\d+$/, "");
  if (FILTERED_REMOTE_HOSTS.has(normalizedHost)) {
    return false;
  }
  if (FILTERED_REMOTE_HOST_SUFFICES.some(s => host.endsWith(s))) {
    return false;
  }
  return true;
}

// ── Types ────────────────────────────────────────────────────────────────────

interface LinkIssue {
  file: string;       // Markdown file that contains the link
  line: number;       // 1-based line number
  link: string;       // Raw link target from the markdown
  reason: string;     // Human-readable explanation
}

interface OrphanedFile {
  file: string;       // Path to the orphaned file
  reason: string;     // Human-readable explanation
}

interface RemoteLinkDetail {
  file: string;
  line: number;
  link: string;
  protocol: "http" | "https";
  host: string;
  path: string;
}

interface LocalLinkDetail {
  file: string;
  line: number;
  link: string;
  absPath: string;
  exists: boolean;
  isDirectory?: boolean;
}

interface ValidationResult {
  skillRef: SkillRef;
  issues: LinkIssue[];
  orphanedFiles: OrphanedFile[];
  remoteLinks: RemoteLinkDetail[];
  localLinks: LocalLinkDetail[];
}

// ── Markdown file discovery ──────────────────────────────────────────────────

function findMarkdownFiles(dir: string): string[] {
  const results: string[] = [];

  function walk(current: string): void {
    let entries: string[];
    try {
      entries = readdirSync(current);
    } catch {
      return;
    }
    for (const entry of entries) {
      const fullPath = resolve(current, entry);
      try {
        const stat = statSync(fullPath);
        if (stat.isDirectory()) {
          walk(fullPath);
        } else if (entry.endsWith(".md")) {
          results.push(fullPath);
        }
      } catch {
        // skip inaccessible entries
      }
    }
  }

  walk(dir);
  return results;
}

/**
 * Collect all files under the "references" directory (non-recursively for 
 * directories, but recursively for files).
 */
function findReferenceFiles(skillDir: string): string[] {
  const referencesDir = resolve(skillDir, "references");
  if (!existsSync(referencesDir)) {
    return [];
  }

  const results: string[] = [];

  function walk(current: string): void {
    let entries: string[];
    try {
      entries = readdirSync(current);
    } catch {
      return;
    }
    for (const entry of entries) {
      const fullPath = resolve(current, entry);
      try {
        const stat = statSync(fullPath);
        if (stat.isDirectory()) {
          walk(fullPath);
        } else {
          results.push(fullPath);
        }
      } catch {
        // skip inaccessible entries
      }
    }
  }

  walk(referencesDir);
  return results;
}

// ── Validation logic ─────────────────────────────────────────────────────────

function validateFile(mdFile: string, skillDir: string): {
  issues: LinkIssue[];
  remoteLinks: RemoteLinkDetail[];
  localLinks: LocalLinkDetail[];
} {
  const skillsDir = dirname(skillDir);

  // Local links
  const localLinks = extractLocalLinks(mdFile, skillDir);
  const remoteLinks = extractRemoteLinks(mdFile, skillDir);
  const issues: LinkIssue[] = [];

  // Check 1: find all references that don't exist
  issues.push(...localLinks.filter((item) => {
    return !item.exists;
  }).map((item) => {
    return {
      file: mdFile,
      line: item.line,
      link: item.link,
      reason: `Target does not exist: ${item.link}`,
    };
  }));

  // Check 2: find all references that are directories
  issues.push(...localLinks.filter((item) => {
    return item.exists && item.isDirectory;
  }).map((item) => {
    return {
      file: mdFile,
      line: item.line,
      link: item.link,
      reason: `Reference points to a directory, not a file: ${item.link}`,
    };
  }));

  // Check 3: find all references outside the skills directory
  issues.push(...localLinks.map((item) => {
    const normalizedResolved = normalize(item.absPath).toLowerCase();
    const normalizedSkillDir = normalize(skillDir).toLowerCase();

    const insideSkill = normalizedResolved.startsWith(normalizedSkillDir + "\\")
      || normalizedResolved.startsWith(normalizedSkillDir + "/")
      || normalizedResolved === normalizedSkillDir;

    if (!insideSkill) {
      const rel = relative(skillsDir, item.absPath).replace(/\\/g, "/");
      return {
        file: mdFile,
        line: item.line,
        link: item.link,
        reason: `Reference escapes skill directory → resolves to: ${rel}`,
      };
    } else {
      return undefined;
    }
  }).filter((issue) => issue !== undefined));

  return {
    issues,
    remoteLinks: remoteLinks.filter((item) => {
      return shouldPrintRemoteHost(item.host);
    }).map((item) => {
      return {
        file: mdFile,
        line: item.line,
        link: item.link,
        protocol: item.protocol,
        host: item.host,
        path: item.path,
      };
    }),
    localLinks: localLinks.map((item) => {
      return {
        file: mdFile,
        line: item.line,
        link: item.link,
        absPath: item.absPath,
        exists: item.exists,
        isDirectory: item.isDirectory,
      };
    }),
  };
}

function validateSkill(skillRef: SkillRef): ValidationResult {
  const skillDir = resolve(REPO_ROOT, `plugins/${skillRef.pluginDirname}/skills/${skillRef.name}`);
  const mdFiles = findMarkdownFiles(skillDir);
  const issues: LinkIssue[] = [];
  const remoteLinks: RemoteLinkDetail[] = [];
  const localLinks: LocalLinkDetail[] = [];

  // Validate all markdown files for link issues
  for (const mdFile of mdFiles) {
    const result = validateFile(mdFile, skillDir);
    issues.push(...result.issues);
    remoteLinks.push(...result.remoteLinks);
    localLinks.push(...result.localLinks);
  }

  // Track visited files for orphan detection
  // Using case-insensitive comparison for cross-platform compatibility (Windows)
  const visited = new Set<string>();
  const queue: string[] = [];

  // Start from SKILL.md if it exists
  const skillMd = resolve(skillDir, "SKILL.md");
  if (existsSync(skillMd)) {
    queue.push(skillMd);
    visited.add(normalize(skillMd).toLowerCase());
  }

  // BFS traversal to track all reachable files
  while (queue.length > 0) {
    const current = queue.shift()!;
    const links = extractLocalLinks(current, skillDir);

    for (const link of links) {

      const normalizedLink = normalize(link.absPath).toLowerCase();
      if (!visited.has(normalizedLink)) {
        visited.add(normalizedLink);
        // Only follow markdown links
        if (link.exists && !link.isDirectory && link.absPath.endsWith(".md")) {
          queue.push(link.absPath);
        }
      }
    }
  }

  // Find orphaned files in the references directory
  const orphanedFiles: OrphanedFile[] = [];
  const referenceFiles = findReferenceFiles(skillDir);

  for (const refFile of referenceFiles) {
    const normalizedRefFile = normalize(refFile).toLowerCase();
    if (!visited.has(normalizedRefFile)) {
      const relPath = relative(skillDir, refFile).replace(/\\/g, "/");
      orphanedFiles.push({
        file: refFile,
        reason: `File exists in references directory but is not linked from SKILL.md: ${relPath}`,
      });
    }
  }

  return { skillRef: skillRef, issues, orphanedFiles, remoteLinks, localLinks };
}

// ── JSON output ──────────────────────────────────────────────────────────────

export interface ReferenceEntry {
  source: string;
  target: string;
  status: "valid" | "broken" | "warning";
  message?: string;
}

export interface ReferencesJsonResult {
  references: ReferenceEntry[];
  summary: {
    total: number;
    valid: number;
    broken: number;
    warnings: number;
  };
}

function buildReferencesJson(
  skills: SkillRef[],
  results: ValidationResult[],
): ReferencesJsonResult {
  const references: ReferenceEntry[] = [];
  let validCount = 0;
  let brokenCount = 0;
  let warningCount = 0;

  for (const result of results) {
    const hasIssues = result.issues.length > 0 || result.orphanedFiles.length > 0;

    if (!hasIssues) {
      validCount++;
      continue;
    }

    // Link issues → broken
    for (const issue of result.issues) {
      references.push({
        source: formatPath(issue.file),
        target: issue.link,
        status: "broken",
        message: issue.reason,
      });
      brokenCount++;
    }

    // Orphaned files → warning
    for (const orphan of result.orphanedFiles) {
      references.push({
        source: formatPath(orphan.file),
        target: result.skillRef + "/SKILL.md",
        status: "warning",
        message: orphan.reason,
      });
      warningCount++;
    }
  }

  return {
    references,
    summary: {
      total: skills.length,
      valid: validCount,
      broken: brokenCount,
      warnings: warningCount,
    },
  };
}

// ── List output ─────────────────────────────────────────────────────────────

export interface LinkListEntry {
  source: string;
  sourceLine: number;
  link: string;
}

export interface LocalLinkListEntry extends LinkListEntry {
  resolved: string;
  status: "file" | "directory" | "missing";
}

export interface RemoteLinkListEntry extends LinkListEntry {
  protocol: "http" | "https";
  host: string;
  path: string;
}

export interface SkillLinkList {
  skill: SkillRef;
  localLinks: LocalLinkListEntry[];
  remoteLinks: RemoteLinkListEntry[];
}

export interface ReferencesListResult {
  skills: SkillLinkList[];
  summary: {
    totalSkills: number;
    totalLocalLinks: number;
    totalRemoteLinks: number;
  };
}

function buildListJson(results: ValidationResult[]): ReferencesListResult {
  let totalLocal = 0;
  let totalRemote = 0;

  const skills: SkillLinkList[] = results.map((result) => {
    const localLinks: LocalLinkListEntry[] = result.localLinks.map((l) => ({
      source: formatPath(l.file),
      sourceLine: l.line,
      link: l.link,
      resolved: formatPath(l.absPath),
      status: !l.exists ? "missing" : l.isDirectory ? "directory" : "file",
    }));
    const remoteLinks: RemoteLinkListEntry[] = result.remoteLinks.map((r) => ({
      source: formatPath(r.file),
      sourceLine: r.line,
      link: r.link,
      protocol: r.protocol,
      host: r.host,
      path: r.path,
    }));
    totalLocal += localLinks.length;
    totalRemote += remoteLinks.length;
    return { skill: result.skillRef, localLinks, remoteLinks };
  });

  return {
    skills,
    summary: {
      totalSkills: results.length,
      totalLocalLinks: totalLocal,
      totalRemoteLinks: totalRemote,
    },
  };
}

// ── CLI entry point ──────────────────────────────────────────────────────────

function formatPath(absPath: string): string {
  return relative(REPO_ROOT, absPath).replace(/\\/g, "/");
}

function main(): void {
  const { values, positionals } = parseArgs({
    args: process.argv.slice(2),
    options: {
      json: { type: "boolean", default: false },
      list: { type: "boolean", default: false },
    },
    strict: false,
    allowPositionals: true,
  });

  const jsonOutput = values.json ?? false;
  const listOutput = values.list ?? false;
  const requestedPluginDirname = positionals[0];
  const requestedSkill = positionals[1];

  let skills: SkillRef[] = [];
  if (requestedPluginDirname && requestedSkill) {
    skills = [{
      pluginDirname: requestedPluginDirname,
      name: requestedSkill
    }];
  } else {
    if (requestedPluginDirname) {
      skills = listSkills(requestedPluginDirname);
    } else {
      const plugins = listPlugins();
      for (const plugin of plugins) {
        skills.push(...plugin.skills);
      }
    }
  }

  // Validate all skills
  const results: ValidationResult[] = [];
  for (const skill of skills) {
    results.push(validateSkill(skill));
  }

  // ── List output mode ────────────────────────────────────────────────────
  if (listOutput) {
    const listResult = buildListJson(results);
    console.log(JSON.stringify(listResult, null, 2));
    return;
  }

  // ── JSON output mode ────────────────────────────────────────────────────
  if (jsonOutput) {
    const jsonResult = buildReferencesJson(skills, results);
    console.log(JSON.stringify(jsonResult, null, 2));
    const hasErrors = results.some(r => r.issues.length > 0);
    if (hasErrors) {
      process.exitCode = 1;
    }
    return;
  }

  // ── Console output mode (default) ───────────────────────────────────────
  console.log("\n🔗 Markdown Reference Validator\n");
  console.log("────────────────────────────────────────────────────────────");

  let totalIssues = 0;
  let totalOrphanedFiles = 0;
  let skillsWithIssues = 0;

  for (const result of results) {
    const hasLinkIssues = result.issues.length > 0;
    const hasOrphanedFiles = result.orphanedFiles.length > 0;

    if (!hasLinkIssues && !hasOrphanedFiles) {
      console.log(`  ✅ ${result.skillRef.pluginDirname} - ${result.skillRef.name}`);
    } else {
      skillsWithIssues++;
      const issueCount = result.issues.length + result.orphanedFiles.length;
      totalIssues += result.issues.length;
      totalOrphanedFiles += result.orphanedFiles.length;

      console.log(`  ❌ ${result.skillRef} — ${issueCount} issue(s)`);

      // Report link issues
      for (const issue of result.issues) {
        const loc = `${formatPath(issue.file)}:${issue.line}`;
        console.log(`     ${loc}`);
        console.log(`       Link: ${issue.link}`);
        console.log(`       ${issue.reason}`);
      }

      // Report orphaned files
      for (const orphan of result.orphanedFiles) {
        console.log(`     ${formatPath(orphan.file)}`);
        console.log(`       ${orphan.reason}`);
      }
    }
  }

  console.log("\n────────────────────────────────────────────────────────────");

  const allIssuesCount = totalIssues + totalOrphanedFiles;
  if (allIssuesCount === 0) {
    console.log(`\n✅ All ${skills.length} skill(s) passed — no broken or escaped references, no orphaned files.\n`);
  } else {
    let message = `\n❌ ${allIssuesCount} issue(s) found in ${skillsWithIssues} skill(s)`;
    if (totalIssues > 0 && totalOrphanedFiles > 0) {
      message += ` (${totalIssues} link issue(s), ${totalOrphanedFiles} orphaned file(s))`;
    } else if (totalOrphanedFiles > 0) {
      message += ` (${totalOrphanedFiles} orphaned file(s))`;
    }
    message += ".\n";
    console.log(message);
    process.exitCode = 1;
  }
}

main();