validate-app-entry.js

#!/usr/bin/env node

/**
 * Validate App Entry Script
 *
 * Usage: node validate-app-entry.js <app-name>
 * Example: node validate-app-entry.js dsub
 */

const fs = require("fs");
const path = require("path");
const { execFileSync } = require("child_process");

// Detect if running in CI environment
const isCI = process.env.CI === "true" || process.env.GITHUB_ACTIONS === "true";

// Minimum stars an open source app's public repository should have.
// Keep in sync with content/en/docs/developers/adding-apps.md
const MIN_REPO_STARS = 15;

// Limits every catalog image must meet. convert-app-images.js produces
// images within them. Keep in sync with content/en/docs/developers/adding-apps.md
const MAX_IMAGE_DIMENSION = 1200;
const MAX_IMAGE_KB = 500;

const KEBAB_CASE = /^[a-z0-9]+(-[a-z0-9]+)*$/;

// Hosts known to expose a star count, so a lookup that comes back empty there
// is a broken check rather than an unsupported forge
const KNOWN_STAR_HOSTS = ["github.com", "gitlab.com", "codeberg.org"];

const USER_AGENT = "Navidrome-App-Validator/1.0";
// Deadline for a whole request, not a per-socket idle timer
const REQUEST_TIMEOUT = 10000; // 10 seconds

// A host that resolves to nothing is worth reporting; a dropped connection is
// noise, so it is ignored the way the URL check has always ignored it
const UNREACHABLE_ERROR_CODES = ["ENOTFOUND", "ECONNREFUSED"];
const TRANSIENT_ERROR_CODES = ["ETIMEDOUT", "ECONNRESET"];

// Classify a request that produced no response. fetch reports network trouble
// as a TypeError and keeps the real code and message on the cause.
function classifyRequestError(err) {
  if (err.name === "TimeoutError") return { kind: "timeout" };

  const cause = err.cause || err;
  if (UNREACHABLE_ERROR_CODES.includes(cause.code)) {
    return { kind: "unreachable" };
  }
  if (TRANSIENT_ERROR_CODES.includes(cause.code)) return { kind: "transient" };

  return { kind: "failed", message: cause.message || err.message };
}

// Release the connection for a reply whose body will never be read. A HEAD
// reply has no body at all, hence the optional chain.
function discardBody(res) {
  return res.body?.cancel().catch(() => {});
}

// Token that lifts the anonymous GitHub API rate limit. HUGO_GITHUB_TOKEN is
// the name the site build already uses, see layouts/partials/last-updated/
function githubToken() {
  return process.env.GITHUB_TOKEN || process.env.HUGO_GITHUB_TOKEN;
}

// Run a git command, reporting only whether it succeeded
function gitSucceeds(args) {
  try {
    execFileSync("git", args, { stdio: "ignore" });
    return true;
  } catch (err) {
    return false;
  }
}

// The branch a new entry would be merged into. GITHUB_BASE_REF is set by
// GitHub Actions on pull requests; the rest covers local runs.
let cachedBaseRef;
function baseRef() {
  if (cachedBaseRef !== undefined) return cachedBaseRef;

  const candidates = [
    process.env.VALIDATE_BASE_REF,
    process.env.GITHUB_BASE_REF && `origin/${process.env.GITHUB_BASE_REF}`,
    "origin/master",
    "master",
  ].filter(Boolean);

  cachedBaseRef =
    candidates.find((ref) =>
      // Resolve the ref first: cat-file alone cannot tell a missing ref from a
      // missing path, and those two must not mean the same thing here
      gitSucceeds(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`])
    ) || null;

  return cachedBaseRef;
}

// Is this entry absent from the base branch? Rules that only bind new entries
// ask this. Whenever git cannot answer - no repo, shallow clone, unknown base
// ref - the answer is "not new", so a rule can never block an existing entry.
function isNewApp(appName) {
  const ref = baseRef();
  if (!ref) return false;

  return !gitSucceeds([
    "cat-file",
    "-e",
    `${ref}:assets/apps/${appName}/index.yaml`,
  ]);
}

// Single HTTP entry point for every check in this file. Never throws -
// validation is advisory, so a broken host must not abort the run. Returns
// { res } for any reply, or { error } when nothing came back.
async function request(
  url,
  { method = "GET", redirect = "follow", headers = {} } = {}
) {
  try {
    const res = await fetch(url, {
      method,
      redirect,
      headers: { "User-Agent": USER_AGENT, ...headers },
      signal: AbortSignal.timeout(REQUEST_TIMEOUT),
    });
    return { res };
  } catch (err) {
    return { error: classifyRequestError(err) };
  }
}

// Status-only request. Redirects are reported rather than followed, and any
// body that does come back is dropped rather than read.
async function requestStatus(url, method) {
  const { res, error } = await request(url, { method, redirect: "manual" });
  if (res) await discardBody(res);
  return { status: res?.status, error };
}

// Fetch and parse a JSON endpoint. Never throws. Returns the status next to
// the body, so callers can tell "this host has no such API" (404, or a
// non-JSON reply) from "the lookup failed" (no answer, throttled, server
// error). A null status means nothing usable came back at all.
async function fetchJson(url) {
  const headers = { Accept: "application/json" };

  // CI runners share outbound IPs, so anonymous GitHub API calls can be
  // throttled by unrelated traffic. Authenticate whenever a token is around.
  const token = githubToken();
  if (token && url.startsWith("https://api.github.com/")) {
    headers.Authorization = `Bearer ${token}`;
  }

  const { res, error } = await request(url, { headers });
  if (error) return { status: null, json: null, error };

  if (!res.ok) {
    await discardBody(res);
    return { status: res.status, json: null };
  }

  try {
    return { status: res.status, json: await res.json() };
  } catch (err) {
    // Timing out mid-body is a failed lookup; anything else means the host
    // answered with something that is not JSON, so it lacks this API
    if (err.name === "TimeoutError") {
      return { status: null, json: null, error: classifyRequestError(err) };
    }
    return { status: res.status, json: null };
  }
}

// Split a repo URL into the pieces the star lookup needs, or null when it
// cannot be parsed. Deep links such as /tree/<ref>/... or /-/blob/... and a
// trailing .git are trimmed so the repository itself is left.
function parseRepoUrl(repoUrl) {
  let parsedUrl;
  try {
    parsedUrl = new URL(repoUrl);
  } catch (err) {
    return null;
  }

  return {
    host: parsedUrl.hostname.replace(/^www\./, ""),
    origin: parsedUrl.origin,
    repoPath: parsedUrl.pathname
      .replace(/\.git$/, "")
      .replace(/\/(-|tree|blob|src|commit)\/.*$/, "")
      .replace(/^\/+|\/+$/g, ""),
  };
}

// Build the API endpoints that can report a star count for a repo. GitHub
// gets a dedicated probe; any other host is tried as Gitea/Forgejo first and
// GitLab second, which covers Codeberg, self-hosted Gitea, and both
// gitlab.com and self-hosted GitLab.
function getStarProbes(repo) {
  const [owner, name] = repo.repoPath.split("/");
  if (!name) return [];

  const ownerRepo = `${owner}/${name}`;

  if (repo.host === "github.com") {
    return [
      {
        host: "api.github.com",
        url: `https://api.github.com/repos/${ownerRepo}`,
        field: "stargazers_count",
      },
    ];
  }

  return [
    {
      host: repo.host,
      url: `${repo.origin}/api/v1/repos/${ownerRepo}`,
      field: "stars_count",
    },
    {
      host: repo.host,
      // GitLab supports subgroups, so keep the full path here
      url: `${repo.origin}/api/v4/projects/${encodeURIComponent(
        repo.repoPath
      )}`,
      field: "star_count",
    },
  ];
}

// Explain why a probe could not answer, or return null when the host simply
// does not speak that API and the next probe should be tried. A 404 or a
// non-JSON reply means "wrong forge"; a timeout, throttle, or server error
// means the check itself is broken and must not pass silently.
function probeFailure(host, status, error) {
  // Reuse the vocabulary validateUrl already reports network trouble with
  if (error) {
    if (error.kind === "timeout") return `${host} request timed out`;
    if (error.kind === "unreachable") return `${host} appears unreachable`;
    if (error.kind === "transient") return `${host} dropped the connection`;
    return `${host} lookup failed: ${error.message}`;
  }

  if (status === 401) return `${host} rejected the token (401)`;
  if (status === 403 || status === 429) {
    return host === "api.github.com"
      ? `${host} rate limit reached, set GITHUB_TOKEN to raise it`
      : `${host} refused the request (${status})`;
  }
  if (status >= 500) return `${host} returned ${status}`;

  return null;
}

// Color codes for terminal output (disabled in CI)
const colors = isCI
  ? {
      reset: "",
      red: "",
      green: "",
      yellow: "",
      blue: "",
      cyan: "",
    }
  : {
      reset: "\x1b[0m",
      red: "\x1b[31m",
      green: "\x1b[32m",
      yellow: "\x1b[33m",
      blue: "\x1b[34m",
      cyan: "\x1b[36m",
    };

class AppValidator {
  constructor(appName, options = {}) {
    this.appName = appName;
    this.appDir = path.join(process.cwd(), "assets", "apps", appName);
    this.yamlPath = path.join(this.appDir, "index.yaml");
    this.schemaPath = path.join(
      process.cwd(),
      "assets",
      "apps",
      "app-schema.json"
    );
    this.errors = [];
    this.warnings = [];
    this.quiet = options.quiet || false;
  }

  log(message, color = "reset") {
    if (isCI) {
      // In CI, just output plain text
      console.log(message);
    } else {
      console.log(`${colors[color]}${message}${colors.reset}`);
    }
  }

  addError(message) {
    this.errors.push(message);
  }

  addWarning(message) {
    this.warnings.push(message);
  }

  // Check if app directory exists
  checkDirectory() {
    if (!fs.existsSync(this.appDir)) {
      this.addError(`App directory not found: ${this.appDir}`);
      return false;
    }

    // The rule binds new entries, so older folders named before it existed
    // only get a warning
    if (!KEBAB_CASE.test(this.appName)) {
      const message = `Folder name "${this.appName}" is not kebab-case (e.g. my-awesome-app)`;
      if (isNewApp(this.appName)) {
        this.addError(message);
      } else {
        this.addWarning(`${message} (existing entry, not blocking)`);
      }
    }
    return true;
  }

  // Check if index.yaml exists and is valid YAML
  async validateYaml() {
    if (!fs.existsSync(this.yamlPath)) {
      this.addError("index.yaml file not found");
      return null;
    }

    try {
      const yaml = require("js-yaml");
      const content = fs.readFileSync(this.yamlPath, "utf8");
      const data = yaml.load(content);
      return data;
    } catch (err) {
      this.addError(`Invalid YAML syntax: ${err.message}`);
      return null;
    }
  }

  // Validate against JSON Schema
  async validateSchema(data) {
    if (!data) return;

    try {
      const Ajv = require("ajv");
      const addFormats = require("ajv-formats");

      const ajv = new Ajv({ allErrors: true, strict: false });
      addFormats(ajv);

      const schema = JSON.parse(fs.readFileSync(this.schemaPath, "utf8"));
      const validate = ajv.compile(schema);
      const valid = validate(data);

      if (!valid) {
        validate.errors.forEach((err) => {
          const field = err.instancePath || "root";
          const message = err.message;
          const detail = err.params ? JSON.stringify(err.params) : "";
          this.addError(
            `Schema validation: ${field} ${message} ${detail}`.trim()
          );
        });
      }
    } catch (err) {
      this.addError(`Schema validation failed: ${err.message}`);
    }
  }

  // Check that image files exist and meet the catalog limits
  async validateImages(data) {
    if (!data || !data.screenshots) return;

    const images = [];
    if (data.screenshots.thumbnail) {
      images.push({ file: data.screenshots.thumbnail, label: "Thumbnail image" });
    }
    if (Array.isArray(data.screenshots.gallery)) {
      data.screenshots.gallery.forEach((file) =>
        images.push({ file, label: "Gallery image" })
      );
    }

    for (const image of images) {
      await this.validateImage(image);
    }
  }

  async validateImage({ file, label }) {
    const fullPath = path.join(this.appDir, file);
    if (!fs.existsSync(fullPath)) {
      this.addError(`${label} not found: ${file}`);
      return;
    }

    const sharp = require("sharp");
    let metadata;
    try {
      metadata = await sharp(fullPath).metadata();
    } catch (err) {
      this.addError(`${label} ${file} is not a readable image: ${err.message}`);
      return;
    }

    // Everything convert-app-images.js fixes goes into one error, with the
    // command that fixes it
    const problems = [];
    if (metadata.format !== "webp") {
      problems.push(`is ${metadata.format}, not WebP`);
    } else if (path.extname(file).toLowerCase() !== ".webp") {
      problems.push("is WebP but its name does not end in .webp");
    }

    const { width, height } = metadata;
    if (Math.max(width, height) > MAX_IMAGE_DIMENSION) {
      problems.push(
        `is ${width}x${height}px (maximum: ${MAX_IMAGE_DIMENSION}px on the longest side)`
      );
    }

    const sizeInKB = fs.statSync(fullPath).size / 1024;
    if (sizeInKB > MAX_IMAGE_KB) {
      problems.push(
        `is ${Math.round(sizeInKB)}KB (maximum: ${MAX_IMAGE_KB}KB)`
      );
    }

    if (problems.length > 0) {
      this.addError(
        `${label} ${file} ${problems.join(", ")}. Fix with: npm run convert:images ${this.appName}`
      );
    }
  }

  // Check for image files in the app folder that are not referenced in index.yaml
  validateDanglingImages(data) {
    if (!data) return;

    // Collect all images referenced by the entry
    const referenced = new Set();
    if (data.screenshots) {
      if (data.screenshots.thumbnail) {
        referenced.add(data.screenshots.thumbnail);
      }
      if (Array.isArray(data.screenshots.gallery)) {
        data.screenshots.gallery.forEach((img) => referenced.add(img));
      }
    }

    const imageExtensions = [".png", ".webp", ".jpg", ".jpeg"];

    let files;
    try {
      files = fs.readdirSync(this.appDir, { withFileTypes: true });
    } catch (err) {
      this.addError(`Unable to read app directory: ${err.message}`);
      return;
    }

    files.forEach((dirent) => {
      if (!dirent.isFile()) return;
      const ext = path.extname(dirent.name).toLowerCase();
      if (!imageExtensions.includes(ext)) return;
      if (!referenced.has(dirent.name)) {
        this.addError(
          `Dangling image not referenced in index.yaml: ${dirent.name}`
        );
      }
    });
  }

  // Validate URL (checks if it's reachable)
  async validateUrl(url, description) {
    if (!url) return;

    // Basic URL format check
    try {
      new URL(url);
    } catch (err) {
      this.addError(`Invalid URL format for ${description}: ${url}`);
      return;
    }

    // HEAD is enough to prove a URL resolves, and is cheaper than GET
    let { status, error } = await requestStatus(url, "HEAD");

    // Retry with GET if the server doesn't support HEAD
    if (status === 405) {
      ({ status, error } = await requestStatus(url, "GET"));
      // Only a timeout on the retry is worth reporting
      if (error && error.kind !== "timeout") return;
    }

    if (error) {
      if (error.kind === "timeout") {
        this.addWarning(`${description} request timed out: ${url}`);
      } else if (error.kind === "unreachable") {
        this.addWarning(`${description} appears unreachable: ${url}`);
      } else if (error.kind === "failed") {
        this.addWarning(`${description} validation failed: ${error.message}`);
      }
      // "transient" stays quiet on purpose: a dropped connection says more
      // about the network than about the URL. validateRepoStars is stricter,
      // because a star lookup that fails quietly would look like a clean pass.
      return;
    }

    // A redirect still proves the URL resolves, so only 4xx/5xx is a problem
    if (status >= 400) {
      this.addWarning(`${description} returned status ${status}: ${url}`);
    }
  }

  // Validate all URLs in the app data
  async validateUrls(data) {
    if (!data) return;

    const urlChecks = [];

    // Main app URL
    if (data.url) {
      urlChecks.push(this.validateUrl(data.url, "App URL"));
    }

    // Repository URL
    if (data.repoUrl) {
      urlChecks.push(this.validateUrl(data.repoUrl, "Repository URL"));
    }

    // Platform store URLs
    if (data.platforms) {
      ["android", "ios", "macos"].forEach((platform) => {
        if (
          data.platforms[platform] &&
          typeof data.platforms[platform] === "object"
        ) {
          if (data.platforms[platform].store) {
            urlChecks.push(
              this.validateUrl(
                data.platforms[platform].store,
                `${platform} store URL`
              )
            );
          }
        }
      });
    }

    await Promise.all(urlChecks);
  }

  // Warn when an open source app's public repository has too few stars.
  // Hosts without a usable star API (cgit, tangled, ...) are skipped silently.
  async validateRepoStars(data) {
    if (!data || !data.repoUrl) return;
    // Same rule the site renders with, see layouts/partials/app-card.html
    if (data.isOpenSource === false) return;

    const repo = parseRepoUrl(data.repoUrl);
    if (!repo) return; // validateUrl already reports a malformed repoUrl

    let failure = null;

    for (const probe of getStarProbes(repo)) {
      const { status, json, error } = await fetchJson(probe.url);
      const stars = json?.[probe.field];

      if (typeof stars === "number") {
        if (stars < MIN_REPO_STARS) {
          // The rule binds new entries. An app already on the base branch
          // keeps a warning, so the rule cannot block a PR that merely
          // touches it - its star count can drop long after it was merged.
          if (isNewApp(this.appName)) {
            this.addError(
              `Repository has ${stars} star(s), below the required minimum of ${MIN_REPO_STARS}: ${data.repoUrl}`
            );
          } else {
            this.addWarning(
              `Repository has ${stars} star(s), below the minimum of ${MIN_REPO_STARS} (existing entry, not blocking): ${data.repoUrl}`
            );
          }
        }
        return;
      }

      failure ??= probeFailure(probe.host, status, error);
    }

    // Keeping quiet here would make a broken lookup look like a clean pass, so
    // say so - but only when the host was supposed to be able to answer
    if (!failure && !KNOWN_STAR_HOSTS.includes(repo.host)) return;

    const reason = failure ? ` - ${failure}` : "";
    this.addWarning(
      `Could not verify the star count (minimum ${MIN_REPO_STARS}): ${data.repoUrl}${reason}`
    );
  }

  // Main validation method
  async validate() {
    if (!this.quiet) {
      if (isCI) {
        console.log(`App: ${this.appName}`);
      } else {
        this.log(
          `\nValidating app: ${colors.cyan}${this.appName}${colors.reset}\n`
        );
      }
    }

    // Check directory
    if (!this.checkDirectory()) {
      return this.printResults();
    }

    // Validate YAML
    const data = await this.validateYaml();

    // Validate against schema
    await this.validateSchema(data);

    // Validate images
    await this.validateImages(data);

    // Check for dangling (unreferenced) images
    this.validateDanglingImages(data);

    // Validate URLs
    if (!isCI && !this.quiet) {
      this.log("Checking URLs (this may take a moment)...", "blue");
    }
    // Both only read data and append warnings, so they can run together
    await Promise.all([this.validateUrls(data), this.validateRepoStars(data)]);

    return this.printResults();
  }

  // Print validation results
  printResults() {
    if (this.errors.length === 0 && this.warnings.length === 0) {
      if (!this.quiet) {
        if (isCI) {
          console.log("Status: PASSED ✅");
        } else {
          console.log("");
          this.log(
            "✅ Validation passed! No errors or warnings found.",
            "green"
          );
        }
      }
      return 0;
    }

    if (isCI) {
      console.log("Status: FAILED ❌\n");
    }

    if (this.errors.length > 0) {
      if (isCI) {
        console.log(`Errors (${this.errors.length}):`);
        this.errors.forEach((error, index) => {
          console.log(`  ${index + 1}. ${error}`);
        });
      } else {
        this.log(`\n❌ Found ${this.errors.length} error(s):`, "red");
        this.errors.forEach((error, index) => {
          this.log(`  ${index + 1}. ${error}`, "red");
        });
      }
    }

    if (this.warnings.length > 0) {
      if (isCI) {
        console.log(`\nWarnings (${this.warnings.length}):`);
        this.warnings.forEach((warning, index) => {
          console.log(`  ${index + 1}. ${warning}`);
        });
      } else {
        this.log(`\n⚠️  Found ${this.warnings.length} warning(s):`, "yellow");
        this.warnings.forEach((warning, index) => {
          this.log(`  ${index + 1}. ${warning}`, "yellow");
        });
      }
    }

    console.log("");
    return this.errors.length > 0 ? 1 : 0;
  }
}

// Main execution
async function main() {
  // Parse arguments
  const args = process.argv.slice(2);
  const quiet = args.includes("-q") || args.includes("--quiet");
  const appName = args.find((arg) => !arg.startsWith("-"));

  // Check for required dependencies
  const requiredModules = ["js-yaml", "ajv", "ajv-formats", "sharp"];
  const missingModules = [];

  for (const mod of requiredModules) {
    try {
      require.resolve(mod);
    } catch (e) {
      missingModules.push(mod);
    }
  }

  if (missingModules.length > 0) {
    console.error(
      `${colors.red}Error: Missing required dependencies${colors.reset}`
    );
    console.log(`\nPlease install the following packages:`);
    console.log(`  npm install ${missingModules.join(" ")}\n`);
    process.exit(1);
  }

  // If no app name provided, validate all apps
  if (!appName) {
    const appsDir = path.join(process.cwd(), "assets", "apps");

    if (!fs.existsSync(appsDir)) {
      console.error(
        `${colors.red}Error: Apps directory not found: ${appsDir}${colors.reset}`
      );
      process.exit(1);
    }

    const appDirs = fs
      .readdirSync(appsDir, { withFileTypes: true })
      .filter((dirent) => dirent.isDirectory() && dirent.name !== "_template")
      .map((dirent) => dirent.name)
      .sort();

    if (appDirs.length === 0) {
      console.log("No app entries found to validate");
      process.exit(0);
    }

    // One GitHub API call per app busts the 60/hour anonymous limit, which
    // would turn every star check into an "unverified" warning. Say it once
    // here rather than once per app.
    if (!githubToken()) {
      console.log(
        `${colors.yellow}Note:${colors.reset} checking every app needs a GitHub token.`
      );
      console.log(
        "Without one the anonymous API limit runs out and star counts stay unverified."
      );
      console.log("  export GITHUB_TOKEN=$(gh auth token)\n");
    }

    if (!quiet) {
      console.log(`Validating ${appDirs.length} app(s)...\n`);
    }

    let totalErrors = 0;
    let failedApps = [];

    for (const app of appDirs) {
      const validator = new AppValidator(app, { quiet });
      const exitCode = await validator.validate();

      if (exitCode !== 0) {
        totalErrors++;
        failedApps.push(app);
      }

      // Add separator between apps (except for last one) when not quiet
      if (!quiet && app !== appDirs[appDirs.length - 1]) {
        console.log("\n" + "=".repeat(60) + "\n");
      }
    }

    console.log("\n" + "=".repeat(60));
    console.log("\nValidation Summary:");
    console.log(`  Total apps: ${appDirs.length}`);
    console.log(`  Passed: ${appDirs.length - totalErrors}`);
    console.log(`  Failed: ${totalErrors}`);

    if (failedApps.length > 0) {
      console.log(`\nFailed apps: ${failedApps.join(", ")}`);
    }

    process.exit(totalErrors > 0 ? 1 : 0);
  }

  // Single app validation
  const validator = new AppValidator(appName, { quiet });
  const exitCode = await validator.validate();
  process.exit(exitCode);
}

main().catch((err) => {
  console.error(`${colors.red}Unexpected error: ${err.message}${colors.reset}`);
  process.exit(1);
});