@schemasentry/cli 0.1.0 → 0.3.1

package/dist/index.js

@@ -2,8 +2,9 @@
 
 // src/index.ts
 import { Command } from "commander";
-import { readFile } from "fs/promises";
-import path from "path";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { readFileSync } from "fs";
+import path4 from "path";
 import { stableStringify as stableStringify2 } from "@schemasentry/core";
 
 // src/report.ts
@@ -11,47 +12,290 @@ import {
   stableStringify,
   validateSchema
 } from "@schemasentry/core";
-var buildReport = (manifest, data) => {
-  const manifestRoutes = manifest.routes ?? {};
+
+// src/coverage.ts
+var buildCoverageResult = (input2, data) => {
+  const manifestRoutes = input2.expectedTypesByRoute ?? {};
   const dataRoutes = data.routes ?? {};
-  const allRoutes = /* @__PURE__ */ new Set([
-    ...Object.keys(manifestRoutes),
-    ...Object.keys(dataRoutes)
+  const derivedRequiredRoutes = Object.entries(manifestRoutes).filter(([, types]) => (types ?? []).length > 0).map(([route]) => route);
+  const requiredRoutes = /* @__PURE__ */ new Set([
+    ...input2.requiredRoutes ?? [],
+    ...derivedRequiredRoutes
   ]);
-  const routes = Array.from(allRoutes).sort().map((route) => {
+  const allRoutes = Array.from(
+    /* @__PURE__ */ new Set([
+      ...Object.keys(manifestRoutes),
+      ...requiredRoutes,
+      ...Object.keys(dataRoutes)
+    ])
+  ).sort();
+  const issuesByRoute = {};
+  const summary = {
+    missingRoutes: 0,
+    missingTypes: 0,
+    unlistedRoutes: 0
+  };
+  for (const route of allRoutes) {
+    const issues = [];
     const expectedTypes = manifestRoutes[route] ?? [];
     const nodes = dataRoutes[route] ?? [];
     const foundTypes = nodes.map((node) => node["@type"]).filter((type) => typeof type === "string");
-    const validation = validateSchema(nodes);
-    const issues = [...validation.issues];
-    if (expectedTypes.length > 0) {
-      if (nodes.length === 0) {
+    if (requiredRoutes.has(route) && nodes.length === 0) {
+      issues.push({
+        path: `routes["${route}"]`,
+        message: "No schema blocks found for route",
+        severity: "error",
+        ruleId: "coverage.missing_route"
+      });
+      summary.missingRoutes += 1;
+    }
+    for (const expectedType of expectedTypes) {
+      if (!foundTypes.includes(expectedType)) {
         issues.push({
-          path: `routes["${route}"]`,
-          message: "No schema blocks found for route",
+          path: `routes["${route}"].types`,
+          message: `Missing expected schema type '${expectedType}'`,
           severity: "error",
-          ruleId: "coverage.missing_route"
+          ruleId: "coverage.missing_type"
         });
-      }
-      for (const expectedType of expectedTypes) {
-        if (!foundTypes.includes(expectedType)) {
-          issues.push({
-            path: `routes["${route}"].types`,
-            message: `Missing expected schema type '${expectedType}'`,
-            severity: "error",
-            ruleId: "coverage.missing_type"
-          });
-        }
+        summary.missingTypes += 1;
       }
     }
-    if (!manifestRoutes[route] && nodes.length > 0) {
+    if (!manifestRoutes[route] && !requiredRoutes.has(route) && nodes.length > 0) {
       issues.push({
         path: `routes["${route}"]`,
         message: "Route has schema but is missing from manifest",
         severity: "warn",
         ruleId: "coverage.unlisted_route"
       });
+      summary.unlistedRoutes += 1;
+    }
+    if (issues.length > 0) {
+      issuesByRoute[route] = issues;
+    }
+  }
+  return {
+    allRoutes,
+    issuesByRoute,
+    summary
+  };
+};
+
+// src/report.ts
+var buildReport = (manifest, data, options = {}) => {
+  const manifestRoutes = manifest.routes ?? {};
+  const dataRoutes = data.routes ?? {};
+  const coverage = buildCoverageResult(
+    { expectedTypesByRoute: manifestRoutes },
+    data
+  );
+  const routes = coverage.allRoutes.map((route) => {
+    const expectedTypes = manifestRoutes[route] ?? [];
+    const nodes = dataRoutes[route] ?? [];
+    const foundTypes = nodes.map((node) => node["@type"]).filter((type) => typeof type === "string");
+    const validation = validateSchema(nodes, options);
+    const issues = [
+      ...validation.issues,
+      ...coverage.issuesByRoute[route] ?? []
+    ];
+    const errorCount = issues.filter((issue) => issue.severity === "error").length;
+    const warnCount = issues.filter((issue) => issue.severity === "warn").length;
+    const score = Math.max(0, validation.score - errorCount * 5 - warnCount * 2);
+    return {
+      route,
+      ok: errorCount === 0,
+      score,
+      issues,
+      expectedTypes,
+      foundTypes
+    };
+  });
+  const summaryErrors = routes.reduce(
+    (count, route) => count + route.issues.filter((i) => i.severity === "error").length,
+    0
+  );
+  const summaryWarnings = routes.reduce(
+    (count, route) => count + route.issues.filter((i) => i.severity === "warn").length,
+    0
+  );
+  const summaryScore = routes.length === 0 ? 0 : Math.round(
+    routes.reduce((total, route) => total + route.score, 0) / routes.length
+  );
+  return {
+    ok: summaryErrors === 0,
+    summary: {
+      routes: routes.length,
+      errors: summaryErrors,
+      warnings: summaryWarnings,
+      score: summaryScore,
+      coverage: coverage.summary
+    },
+    routes
+  };
+};
+
+// src/init.ts
+import { promises as fs } from "fs";
+import path from "path";
+import { SCHEMA_CONTEXT } from "@schemasentry/core";
+var DEFAULT_ANSWERS = {
+  siteName: "Acme Corp",
+  siteUrl: "https://acme.com",
+  authorName: "Jane Doe"
+};
+var getDefaultAnswers = () => ({ ...DEFAULT_ANSWERS });
+var buildManifest = (scannedRoutes = []) => {
+  const routes = {
+    "/": ["Organization", "WebSite"],
+    "/blog/[slug]": ["Article"]
+  };
+  for (const route of scannedRoutes) {
+    if (!routes[route]) {
+      routes[route] = ["WebPage"];
+    }
+  }
+  return { routes };
+};
+var formatDate = (value) => value.toISOString().slice(0, 10);
+var buildData = (answers, options = {}) => {
+  const { siteName, siteUrl, authorName } = answers;
+  const normalizedSiteUrl = normalizeUrl(siteUrl);
+  const today = options.today ?? /* @__PURE__ */ new Date();
+  const date = formatDate(today);
+  const logoUrl = new URL("/logo.png", normalizedSiteUrl).toString();
+  const articleUrl = new URL("/blog/hello-world", normalizedSiteUrl).toString();
+  const imageUrl = new URL("/blog/hello-world.png", normalizedSiteUrl).toString();
+  const routes = {
+    "/": [
+      {
+        "@context": SCHEMA_CONTEXT,
+        "@type": "Organization",
+        name: siteName,
+        url: normalizedSiteUrl,
+        logo: logoUrl,
+        description: `Official website of ${siteName}`
+      },
+      {
+        "@context": SCHEMA_CONTEXT,
+        "@type": "WebSite",
+        name: siteName,
+        url: normalizedSiteUrl,
+        description: `Learn more about ${siteName}`
+      }
+    ],
+    "/blog/[slug]": [
+      {
+        "@context": SCHEMA_CONTEXT,
+        "@type": "Article",
+        headline: "Hello World",
+        author: {
+          "@type": "Person",
+          name: authorName
+        },
+        datePublished: date,
+        dateModified: date,
+        description: `An introduction to ${siteName}`,
+        image: imageUrl,
+        url: articleUrl
+      }
+    ]
+  };
+  for (const route of options.scannedRoutes ?? []) {
+    if (routes[route]) {
+      continue;
     }
+    routes[route] = [
+      {
+        "@context": SCHEMA_CONTEXT,
+        "@type": "WebPage",
+        name: routeToName(route),
+        url: new URL(route, normalizedSiteUrl).toString()
+      }
+    ];
+  }
+  return { routes };
+};
+var writeInitFiles = async (options) => {
+  const {
+    manifestPath,
+    dataPath,
+    overwriteManifest,
+    overwriteData,
+    answers,
+    today,
+    scannedRoutes
+  } = options;
+  const manifest = buildManifest(scannedRoutes ?? []);
+  const data = buildData(answers, { today, scannedRoutes });
+  const manifestResult = await writeJsonFile(
+    manifestPath,
+    manifest,
+    overwriteManifest
+  );
+  const dataResult = await writeJsonFile(dataPath, data, overwriteData);
+  return {
+    manifest: manifestResult,
+    data: dataResult
+  };
+};
+var writeJsonFile = async (filePath, payload, overwrite) => {
+  const exists = await fileExists(filePath);
+  if (exists && !overwrite) {
+    return "skipped";
+  }
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const json = JSON.stringify(payload, null, 2);
+  await fs.writeFile(filePath, `${json}
+`, "utf8");
+  return exists ? "overwritten" : "created";
+};
+var fileExists = async (filePath) => {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var normalizeUrl = (value) => {
+  try {
+    return new URL(value).toString();
+  } catch {
+    return new URL(`https://${value}`).toString();
+  }
+};
+var routeToName = (route) => {
+  if (route === "/") {
+    return "Home";
+  }
+  const cleaned = route.replace(/\[|\]/g, "").split("/").filter(Boolean).join(" ");
+  return cleaned.split(/\s+/).map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1)).join(" ");
+};
+
+// src/audit.ts
+import {
+  validateSchema as validateSchema2
+} from "@schemasentry/core";
+var buildAuditReport = (data, options = {}) => {
+  const dataRoutes = data.routes ?? {};
+  const manifestRoutes = options.manifest?.routes ?? {};
+  const coverageEnabled = Boolean(options.manifest || options.requiredRoutes?.length);
+  const coverage = coverageEnabled ? buildCoverageResult(
+    {
+      expectedTypesByRoute: manifestRoutes,
+      requiredRoutes: options.requiredRoutes
+    },
+    data
+  ) : null;
+  const allRoutes = coverageEnabled ? coverage?.allRoutes ?? [] : Object.keys(dataRoutes).sort();
+  const routes = allRoutes.map((route) => {
+    const expectedTypes = coverageEnabled ? manifestRoutes[route] ?? [] : [];
+    const nodes = dataRoutes[route] ?? [];
+    const foundTypes = nodes.map((node) => node["@type"]).filter((type) => typeof type === "string");
+    const validation = validateSchema2(nodes, options);
+    const issues = [
+      ...validation.issues,
+      ...coverage?.issuesByRoute[route] ?? []
+    ];
     const errorCount = issues.filter((issue) => issue.severity === "error").length;
     const warnCount = issues.filter((issue) => issue.severity === "warn").length;
     const score = Math.max(0, validation.score - errorCount * 5 - warnCount * 2);
@@ -81,15 +325,340 @@ var buildReport = (manifest, data) => {
       routes: routes.length,
       errors: summaryErrors,
       warnings: summaryWarnings,
-      score: summaryScore
+      score: summaryScore,
+      ...coverageEnabled ? { coverage: coverage?.summary } : {}
     },
     routes
   };
 };
 
+// src/summary.ts
+var formatDuration = (durationMs) => {
+  if (!Number.isFinite(durationMs) || durationMs < 0) {
+    return "0ms";
+  }
+  if (durationMs < 1e3) {
+    return `${Math.round(durationMs)}ms`;
+  }
+  const seconds = durationMs / 1e3;
+  return `${seconds.toFixed(seconds < 10 ? 1 : 0)}s`;
+};
+var formatSummaryLine = (label, stats) => {
+  const parts = [
+    `Routes: ${stats.routes}`,
+    `Errors: ${stats.errors}`,
+    `Warnings: ${stats.warnings}`,
+    `Score: ${stats.score}`,
+    `Duration: ${formatDuration(stats.durationMs)}`
+  ];
+  if (stats.coverage) {
+    parts.push(
+      `Coverage: missing_routes=${stats.coverage.missingRoutes} missing_types=${stats.coverage.missingTypes} unlisted_routes=${stats.coverage.unlistedRoutes}`
+    );
+  }
+  return `${label} | ${parts.join(" | ")}`;
+};
+
+// src/config.ts
+import { promises as fs2 } from "fs";
+import path2 from "path";
+var ConfigError = class extends Error {
+  constructor(code, message, suggestion) {
+    super(message);
+    this.code = code;
+    this.suggestion = suggestion;
+  }
+};
+var DEFAULT_CONFIG_PATH = "schema-sentry.config.json";
+var loadConfig = async (options) => {
+  const cwd = options.cwd ?? process.cwd();
+  const explicit = Boolean(options.configPath);
+  const resolvedPath = path2.resolve(cwd, options.configPath ?? DEFAULT_CONFIG_PATH);
+  const exists = await fileExists2(resolvedPath);
+  if (!exists) {
+    if (explicit) {
+      throw new ConfigError(
+        "config.not_found",
+        `Config not found at ${resolvedPath}`,
+        "Provide a valid path or remove --config."
+      );
+    }
+    return null;
+  }
+  let raw;
+  try {
+    raw = await fs2.readFile(resolvedPath, "utf8");
+  } catch (error) {
+    throw new ConfigError(
+      "config.read_failed",
+      `Failed to read config at ${resolvedPath}`,
+      "Check file permissions or re-create the config file."
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new ConfigError(
+      "config.invalid_json",
+      "Config is not valid JSON",
+      "Check the JSON syntax or regenerate the file."
+    );
+  }
+  if (!isConfig(parsed)) {
+    throw new ConfigError(
+      "config.invalid_shape",
+      "Config must be a JSON object with optional boolean 'recommended'",
+      'Example: { "recommended": false }'
+    );
+  }
+  return parsed;
+};
+var resolveRecommended = (cliOverride, config) => cliOverride ?? config?.recommended ?? true;
+var isConfig = (value) => {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const config = value;
+  if (config.recommended !== void 0 && typeof config.recommended !== "boolean") {
+    return false;
+  }
+  return true;
+};
+var fileExists2 = async (filePath) => {
+  try {
+    await fs2.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// src/routes.ts
+import { promises as fs3 } from "fs";
+import path3 from "path";
+var scanRoutes = async (options) => {
+  const rootDir = options.rootDir;
+  const routes = /* @__PURE__ */ new Set();
+  if (options.includeApp !== false) {
+    const appDir = path3.join(rootDir, "app");
+    if (await dirExists(appDir)) {
+      const files = await walkDir(appDir);
+      for (const file of files) {
+        if (!isAppPageFile(file)) {
+          continue;
+        }
+        const route = toAppRoute(appDir, file);
+        if (route) {
+          routes.add(route);
+        }
+      }
+    }
+  }
+  if (options.includePages !== false) {
+    const pagesDir = path3.join(rootDir, "pages");
+    if (await dirExists(pagesDir)) {
+      const files = await walkDir(pagesDir);
+      for (const file of files) {
+        if (!isPagesFile(file)) {
+          continue;
+        }
+        const route = toPagesRoute(pagesDir, file);
+        if (route) {
+          routes.add(route);
+        }
+      }
+    }
+  }
+  return Array.from(routes).sort();
+};
+var isAppPageFile = (filePath) => /\/page\.(t|j)sx?$/.test(filePath) || /\/page\.mdx$/.test(filePath);
+var isPagesFile = (filePath) => /\.(t|j)sx?$/.test(filePath) || /\.mdx$/.test(filePath);
+var toAppRoute = (appDir, filePath) => {
+  const relative = path3.relative(appDir, filePath);
+  const segments = relative.split(path3.sep);
+  if (segments.length === 0) {
+    return null;
+  }
+  segments.pop();
+  const routeSegments = segments.filter((segment) => segment.length > 0).filter((segment) => !isGroupSegment(segment)).filter((segment) => !isParallelSegment(segment));
+  if (routeSegments.length === 0) {
+    return "/";
+  }
+  return `/${routeSegments.join("/")}`;
+};
+var toPagesRoute = (pagesDir, filePath) => {
+  const relative = path3.relative(pagesDir, filePath);
+  const segments = relative.split(path3.sep);
+  if (segments.length === 0) {
+    return null;
+  }
+  if (segments[0] === "api") {
+    return null;
+  }
+  const fileName = segments.pop();
+  if (!fileName) {
+    return null;
+  }
+  const baseName = fileName.replace(/\.[^/.]+$/, "");
+  if (baseName.startsWith("_")) {
+    return null;
+  }
+  const filtered = segments.filter((segment) => segment.length > 0);
+  if (baseName !== "index") {
+    filtered.push(baseName);
+  }
+  if (filtered.length === 0) {
+    return "/";
+  }
+  return `/${filtered.join("/")}`;
+};
+var isGroupSegment = (segment) => segment.startsWith("(") && segment.endsWith(")");
+var isParallelSegment = (segment) => segment.startsWith("@");
+var dirExists = async (dirPath) => {
+  try {
+    const stat = await fs3.stat(dirPath);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+};
+var walkDir = async (dirPath) => {
+  const entries = await fs3.readdir(dirPath, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const resolved = path3.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await walkDir(resolved));
+    } else if (entry.isFile()) {
+      files.push(resolved);
+    }
+  }
+  return files;
+};
+
+// src/html.ts
+var escapeHtml = (value) => String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+var renderRouteIssues = (route) => {
+  if (route.issues.length === 0) {
+    return '<p class="muted">No issues.</p>';
+  }
+  const items = route.issues.map((issue) => {
+    const severityClass = issue.severity === "error" ? "sev-error" : "sev-warn";
+    return `<li class="${severityClass}">
+        <span class="sev">${escapeHtml(issue.severity.toUpperCase())}</span>
+        <code>${escapeHtml(issue.ruleId)}</code>
+        <span>${escapeHtml(issue.message)}</span>
+        <small>${escapeHtml(issue.path)}</small>
+      </li>`;
+  }).join("");
+  return `<ul class="issues">${items}</ul>`;
+};
+var renderRoute = (route) => {
+  const statusClass = route.ok ? "ok" : "fail";
+  const expected = route.expectedTypes.length ? route.expectedTypes.join(", ") : "(none)";
+  const found = route.foundTypes.length ? route.foundTypes.join(", ") : "(none)";
+  return `<section class="route">
+    <header>
+      <h3>${escapeHtml(route.route)}</h3>
+      <span class="badge ${statusClass}">${route.ok ? "OK" : "FAIL"}</span>
+    </header>
+    <p><strong>Score:</strong> ${route.score}</p>
+    <p><strong>Expected types:</strong> ${escapeHtml(expected)}</p>
+    <p><strong>Found types:</strong> ${escapeHtml(found)}</p>
+    ${renderRouteIssues(route)}
+  </section>`;
+};
+var renderCoverage = (report) => {
+  if (!report.summary.coverage) {
+    return "<li><strong>Coverage:</strong> not enabled</li>";
+  }
+  const coverage = report.summary.coverage;
+  return `<li><strong>Coverage:</strong> missing_routes=${coverage.missingRoutes} missing_types=${coverage.missingTypes} unlisted_routes=${coverage.unlistedRoutes}</li>`;
+};
+var renderHtmlReport = (report, options) => {
+  const title = escapeHtml(options.title);
+  const generatedAt = escapeHtml(
+    (options.generatedAt ?? /* @__PURE__ */ new Date()).toISOString()
+  );
+  const routes = report.routes.map(renderRoute).join("");
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${title}</title>
+  <style>
+    :root { color-scheme: light dark; }
+    body { font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif; margin: 24px; line-height: 1.45; }
+    h1, h2, h3 { margin: 0 0 8px; }
+    .muted { color: #666; }
+    .summary, .routes { margin-top: 20px; }
+    .route { border: 1px solid #ddd; border-radius: 8px; padding: 12px; margin: 12px 0; }
+    .route header { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
+    .badge { padding: 2px 8px; border-radius: 999px; font-size: 12px; font-weight: 600; }
+    .badge.ok { background: #dcfce7; color: #166534; }
+    .badge.fail { background: #fee2e2; color: #991b1b; }
+    .issues { margin: 10px 0 0; padding-left: 16px; }
+    .issues li { margin: 8px 0; display: grid; gap: 2px; }
+    .sev { font-weight: 700; }
+    .sev-error .sev { color: #991b1b; }
+    .sev-warn .sev { color: #92400e; }
+    code { background: #f5f5f5; padding: 1px 5px; border-radius: 4px; }
+  </style>
+</head>
+<body>
+  <h1>${title}</h1>
+  <p class="muted">Generated at ${generatedAt}</p>
+
+  <section class="summary">
+    <h2>Summary</h2>
+    <ul>
+      <li><strong>OK:</strong> ${report.ok}</li>
+      <li><strong>Routes:</strong> ${report.summary.routes}</li>
+      <li><strong>Errors:</strong> ${report.summary.errors}</li>
+      <li><strong>Warnings:</strong> ${report.summary.warnings}</li>
+      <li><strong>Score:</strong> ${report.summary.score}</li>
+      ${renderCoverage(report)}
+    </ul>
+  </section>
+
+  <section class="routes">
+    <h2>Routes</h2>
+    ${routes}
+  </section>
+</body>
+</html>`;
+};
+
+// src/annotations.ts
+var escapeCommandValue = (value) => value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+var escapeCommandProperty = (value) => escapeCommandValue(value).replace(/:/g, "%3A").replace(/,/g, "%2C");
+var formatIssueMessage = (route, issue) => `[${route}] ${issue.ruleId}: ${issue.message} (${issue.path})`;
+var buildGitHubAnnotationLines = (report, commandLabel) => {
+  const title = escapeCommandProperty(`Schema Sentry ${commandLabel}`);
+  const lines = [];
+  for (const route of report.routes) {
+    for (const issue of route.issues) {
+      const level = issue.severity === "error" ? "error" : "warning";
+      const message = escapeCommandValue(formatIssueMessage(route.route, issue));
+      lines.push(`::${level} title=${title}::${message}`);
+    }
+  }
+  return lines;
+};
+var emitGitHubAnnotations = (report, commandLabel) => {
+  const lines = buildGitHubAnnotationLines(report, commandLabel);
+  for (const line of lines) {
+    console.error(line);
+  }
+};
+
 // src/index.ts
+import { createInterface } from "readline/promises";
+import { stdin as input, stdout as output } from "process";
 var program = new Command();
-program.name("schemasentry").description("Schema Sentry CLI").version("0.1.0");
+program.name("schemasentry").description("Schema Sentry CLI").version(resolveCliVersion());
 program.command("validate").description("Validate schema coverage and rules").option(
   "-m, --manifest <path>",
   "Path to manifest JSON",
@@ -98,23 +667,21 @@ program.command("validate").description("Validate schema coverage and rules").op
   "-d, --data <path>",
   "Path to schema data JSON",
   "schema-sentry.data.json"
-).action(async (options) => {
-  const manifestPath = path.resolve(process.cwd(), options.manifest);
-  const dataPath = path.resolve(process.cwd(), options.data);
+).option("-c, --config <path>", "Path to config JSON").option("--format <format>", "Report format (json|html)", "json").option("--annotations <provider>", "Emit CI annotations (none|github)", "none").option("-o, --output <path>", "Write report output to file").option("--recommended", "Enable recommended field checks").option("--no-recommended", "Disable recommended field checks").action(async (options) => {
+  const start = Date.now();
+  const format = resolveOutputFormat(options.format);
+  const annotationsMode = resolveAnnotationsMode(options.annotations);
+  const recommended = await resolveRecommendedOption(options.config);
+  const manifestPath = path4.resolve(process.cwd(), options.manifest);
+  const dataPath = path4.resolve(process.cwd(), options.data);
   let raw;
   try {
     raw = await readFile(manifestPath, "utf8");
   } catch (error) {
-    console.error(
-      stableStringify2({
-        ok: false,
-        errors: [
-          {
-            code: "manifest.not_found",
-            message: `Manifest not found at ${manifestPath}`
-          }
-        ]
-      })
+    printCliError(
+      "manifest.not_found",
+      `Manifest not found at ${manifestPath}`,
+      "Run `schemasentry init` to generate starter files."
     );
     process.exit(1);
     return;
@@ -123,31 +690,19 @@ program.command("validate").description("Validate schema coverage and rules").op
   try {
     manifest = JSON.parse(raw);
   } catch (error) {
-    console.error(
-      stableStringify2({
-        ok: false,
-        errors: [
-          {
-            code: "manifest.invalid_json",
-            message: "Manifest is not valid JSON"
-          }
-        ]
-      })
+    printCliError(
+      "manifest.invalid_json",
+      "Manifest is not valid JSON",
+      "Check the JSON syntax or regenerate with `schemasentry init`."
     );
     process.exit(1);
     return;
   }
   if (!isManifest(manifest)) {
-    console.error(
-      stableStringify2({
-        ok: false,
-        errors: [
-          {
-            code: "manifest.invalid_shape",
-            message: "Manifest must contain a 'routes' object with string array values"
-          }
-        ]
-      })
+    printCliError(
+      "manifest.invalid_shape",
+      "Manifest must contain a 'routes' object with string array values",
+      "Ensure each route maps to an array of schema type names."
     );
     process.exit(1);
     return;
@@ -156,16 +711,10 @@ program.command("validate").description("Validate schema coverage and rules").op
   try {
     dataRaw = await readFile(dataPath, "utf8");
   } catch (error) {
-    console.error(
-      stableStringify2({
-        ok: false,
-        errors: [
-          {
-            code: "data.not_found",
-            message: `Schema data not found at ${dataPath}`
-          }
-        ]
-      })
+    printCliError(
+      "data.not_found",
+      `Schema data not found at ${dataPath}`,
+      "Run `schemasentry init` to generate starter files."
     );
     process.exit(1);
     return;
@@ -174,41 +723,167 @@ program.command("validate").description("Validate schema coverage and rules").op
   try {
     data = JSON.parse(dataRaw);
   } catch (error) {
-    console.error(
-      stableStringify2({
-        ok: false,
-        errors: [
-          {
-            code: "data.invalid_json",
-            message: "Schema data is not valid JSON"
-          }
-        ]
-      })
+    printCliError(
+      "data.invalid_json",
+      "Schema data is not valid JSON",
+      "Check the JSON syntax or regenerate with `schemasentry init`."
     );
     process.exit(1);
     return;
   }
   if (!isSchemaData(data)) {
-    console.error(
-      stableStringify2({
-        ok: false,
-        errors: [
-          {
-            code: "data.invalid_shape",
-            message: "Schema data must contain a 'routes' object with array values"
-          }
-        ]
-      })
+    printCliError(
+      "data.invalid_shape",
+      "Schema data must contain a 'routes' object with array values",
+      "Ensure each route maps to an array of JSON-LD blocks."
     );
     process.exit(1);
     return;
   }
-  const report = buildReport(manifest, data);
-  console.log(formatReportOutput(report));
+  const report = buildReport(manifest, data, { recommended });
+  await emitReport({
+    report,
+    format,
+    outputPath: options.output,
+    title: "Schema Sentry Validate Report"
+  });
+  emitAnnotations(report, annotationsMode, "validate");
+  printValidateSummary(report, Date.now() - start);
   process.exit(report.ok ? 0 : 1);
 });
-program.parse();
-var isManifest = (value) => {
+program.command("init").description("Interactive setup wizard").option(
+  "-m, --manifest <path>",
+  "Path to manifest JSON",
+  "schema-sentry.manifest.json"
+).option(
+  "-d, --data <path>",
+  "Path to schema data JSON",
+  "schema-sentry.data.json"
+).option("-y, --yes", "Use defaults and skip prompts").option("-f, --force", "Overwrite existing files").option("--scan", "Scan the filesystem for routes and add WebPage entries").option("--root <path>", "Project root for scanning", ".").action(async (options) => {
+  const manifestPath = path4.resolve(process.cwd(), options.manifest);
+  const dataPath = path4.resolve(process.cwd(), options.data);
+  const force = options.force ?? false;
+  const useDefaults = options.yes ?? false;
+  const answers = useDefaults ? getDefaultAnswers() : await promptAnswers();
+  const scannedRoutes = options.scan ? await scanRoutes({ rootDir: path4.resolve(process.cwd(), options.root ?? ".") }) : [];
+  if (options.scan && scannedRoutes.length === 0) {
+    console.error("No routes found during scan.");
+  }
+  const [overwriteManifest, overwriteData] = await resolveOverwrites({
+    manifestPath,
+    dataPath,
+    force,
+    interactive: !useDefaults
+  });
+  const result = await writeInitFiles({
+    manifestPath,
+    dataPath,
+    overwriteManifest,
+    overwriteData,
+    answers,
+    scannedRoutes
+  });
+  printInitSummary({ manifestPath, dataPath, result });
+});
+program.command("audit").description("Analyze schema health and report issues").option(
+  "-d, --data <path>",
+  "Path to schema data JSON",
+  "schema-sentry.data.json"
+).option("-m, --manifest <path>", "Path to manifest JSON (optional)").option("--scan", "Scan the filesystem for routes").option("--root <path>", "Project root for scanning", ".").option("-c, --config <path>", "Path to config JSON").option("--format <format>", "Report format (json|html)", "json").option("--annotations <provider>", "Emit CI annotations (none|github)", "none").option("-o, --output <path>", "Write report output to file").option("--recommended", "Enable recommended field checks").option("--no-recommended", "Disable recommended field checks").action(async (options) => {
+  const start = Date.now();
+  const format = resolveOutputFormat(options.format);
+  const annotationsMode = resolveAnnotationsMode(options.annotations);
+  const recommended = await resolveRecommendedOption(options.config);
+  const dataPath = path4.resolve(process.cwd(), options.data);
+  let dataRaw;
+  try {
+    dataRaw = await readFile(dataPath, "utf8");
+  } catch (error) {
+    printCliError(
+      "data.not_found",
+      `Schema data not found at ${dataPath}`,
+      "Run `schemasentry init` to generate starter files."
+    );
+    process.exit(1);
+    return;
+  }
+  let data;
+  try {
+    data = JSON.parse(dataRaw);
+  } catch (error) {
+    printCliError(
+      "data.invalid_json",
+      "Schema data is not valid JSON",
+      "Check the JSON syntax or regenerate with `schemasentry init`."
+    );
+    process.exit(1);
+    return;
+  }
+  if (!isSchemaData(data)) {
+    printCliError(
+      "data.invalid_shape",
+      "Schema data must contain a 'routes' object with array values",
+      "Ensure each route maps to an array of JSON-LD blocks."
+    );
+    process.exit(1);
+    return;
+  }
+  let manifest;
+  if (options.manifest) {
+    const manifestPath = path4.resolve(process.cwd(), options.manifest);
+    let manifestRaw;
+    try {
+      manifestRaw = await readFile(manifestPath, "utf8");
+    } catch (error) {
+      printCliError(
+        "manifest.not_found",
+        `Manifest not found at ${manifestPath}`,
+        "Run `schemasentry init` to generate starter files."
+      );
+      process.exit(1);
+      return;
+    }
+    try {
+      manifest = JSON.parse(manifestRaw);
+    } catch (error) {
+      printCliError(
+        "manifest.invalid_json",
+        "Manifest is not valid JSON",
+        "Check the JSON syntax or regenerate with `schemasentry init`."
+      );
+      process.exit(1);
+      return;
+    }
+    if (!isManifest(manifest)) {
+      printCliError(
+        "manifest.invalid_shape",
+        "Manifest must contain a 'routes' object with string array values",
+        "Ensure each route maps to an array of schema type names."
+      );
+      process.exit(1);
+      return;
+    }
+  }
+  const requiredRoutes = options.scan ? await scanRoutes({ rootDir: path4.resolve(process.cwd(), options.root ?? ".") }) : [];
+  if (options.scan && requiredRoutes.length === 0) {
+    console.error("No routes found during scan.");
+  }
+  const report = buildAuditReport(data, {
+    recommended,
+    manifest,
+    requiredRoutes: requiredRoutes.length > 0 ? requiredRoutes : void 0
+  });
+  await emitReport({
+    report,
+    format,
+    outputPath: options.output,
+    title: "Schema Sentry Audit Report"
+  });
+  emitAnnotations(report, annotationsMode, "audit");
+  printAuditSummary(report, Boolean(manifest), Date.now() - start);
+  process.exit(report.ok ? 0 : 1);
+});
+function isManifest(value) {
   if (!value || typeof value !== "object") {
     return false;
   }
@@ -222,8 +897,8 @@ var isManifest = (value) => {
     }
   }
   return true;
-};
-var isSchemaData = (value) => {
+}
+function isSchemaData(value) {
   if (!value || typeof value !== "object") {
     return false;
   }
@@ -237,5 +912,198 @@ var isSchemaData = (value) => {
     }
   }
   return true;
-};
-var formatReportOutput = (report) => stableStringify2(report);
+}
+function resolveOutputFormat(value) {
+  const format = (value ?? "json").trim().toLowerCase();
+  if (format === "json" || format === "html") {
+    return format;
+  }
+  printCliError(
+    "output.invalid_format",
+    `Unsupported report format '${value ?? ""}'`,
+    "Use --format json or --format html."
+  );
+  process.exit(1);
+  return "json";
+}
+function resolveAnnotationsMode(value) {
+  const mode = (value ?? "none").trim().toLowerCase();
+  if (mode === "none" || mode === "github") {
+    return mode;
+  }
+  printCliError(
+    "annotations.invalid_provider",
+    `Unsupported annotations provider '${value ?? ""}'`,
+    "Use --annotations none or --annotations github."
+  );
+  process.exit(1);
+  return "none";
+}
+function formatReportOutput(report, format, title) {
+  if (format === "html") {
+    return renderHtmlReport(report, { title });
+  }
+  return stableStringify2(report);
+}
+async function emitReport(options) {
+  const { report, format, outputPath, title } = options;
+  const content = formatReportOutput(report, format, title);
+  if (!outputPath) {
+    console.log(content);
+    return;
+  }
+  const resolvedPath = path4.resolve(process.cwd(), outputPath);
+  try {
+    await mkdir(path4.dirname(resolvedPath), { recursive: true });
+    await writeFile(resolvedPath, content, "utf8");
+    console.error(`Report written to ${resolvedPath}`);
+  } catch (error) {
+    const reason = error instanceof Error && error.message.length > 0 ? error.message : "Unknown file system error";
+    printCliError(
+      "output.write_failed",
+      `Could not write report to ${resolvedPath}: ${reason}`
+    );
+    process.exit(1);
+  }
+}
+function emitAnnotations(report, mode, commandLabel) {
+  if (mode !== "github") {
+    return;
+  }
+  emitGitHubAnnotations(report, commandLabel);
+}
+function printCliError(code, message, suggestion) {
+  console.error(
+    stableStringify2({
+      ok: false,
+      errors: [
+        {
+          code,
+          message,
+          ...suggestion !== void 0 ? { suggestion } : {}
+        }
+      ]
+    })
+  );
+}
+async function resolveRecommendedOption(configPath) {
+  const override = getRecommendedOverride(process.argv);
+  try {
+    const config = await loadConfig({ configPath });
+    return resolveRecommended(override, config);
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      printCliError(error.code, error.message, error.suggestion);
+      process.exit(1);
+      return true;
+    }
+    throw error;
+  }
+}
+function getRecommendedOverride(argv) {
+  if (argv.includes("--recommended")) {
+    return true;
+  }
+  if (argv.includes("--no-recommended")) {
+    return false;
+  }
+  return void 0;
+}
+function resolveCliVersion() {
+  try {
+    const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+program.parse();
+function printValidateSummary(report, durationMs) {
+  console.error(
+    formatSummaryLine("validate", {
+      ...report.summary,
+      durationMs,
+      coverage: report.summary.coverage
+    })
+  );
+}
+function printAuditSummary(report, coverageEnabled, durationMs) {
+  console.error(
+    formatSummaryLine("audit", {
+      ...report.summary,
+      durationMs,
+      coverage: report.summary.coverage
+    })
+  );
+  if (!coverageEnabled) {
+    console.error("Coverage checks skipped (no manifest provided).");
+  }
+}
+async function promptAnswers() {
+  const defaults = getDefaultAnswers();
+  const rl = createInterface({ input, output });
+  try {
+    const siteName = await ask(rl, "Site name", defaults.siteName);
+    const siteUrl = await ask(rl, "Base URL", defaults.siteUrl);
+    const authorName = await ask(rl, "Primary author name", defaults.authorName);
+    return { siteName, siteUrl, authorName };
+  } finally {
+    rl.close();
+  }
+}
+async function ask(rl, question, fallback) {
+  const answer = (await rl.question(`${question} (${fallback}): `)).trim();
+  return answer.length > 0 ? answer : fallback;
+}
+async function resolveOverwrites(options) {
+  const { manifestPath, dataPath, force, interactive } = options;
+  if (force) {
+    return [true, true];
+  }
+  const manifestExists = await fileExists(manifestPath);
+  const dataExists = await fileExists(dataPath);
+  if (!interactive) {
+    return [false, false];
+  }
+  const rl = createInterface({ input, output });
+  try {
+    const overwriteManifest = manifestExists ? await confirm(rl, `Manifest exists at ${manifestPath}. Overwrite?`, false) : false;
+    const overwriteData = dataExists ? await confirm(rl, `Data file exists at ${dataPath}. Overwrite?`, false) : false;
+    return [overwriteManifest, overwriteData];
+  } finally {
+    rl.close();
+  }
+}
+async function confirm(rl, question, defaultValue) {
+  const hint = defaultValue ? "Y/n" : "y/N";
+  const answer = (await rl.question(`${question} (${hint}): `)).trim().toLowerCase();
+  if (!answer) {
+    return defaultValue;
+  }
+  return answer === "y" || answer === "yes";
+}
+function printInitSummary(options) {
+  const { manifestPath, dataPath, result } = options;
+  const created = [];
+  if (result.manifest !== "skipped") {
+    created.push(`${manifestPath} (${result.manifest})`);
+  }
+  if (result.data !== "skipped") {
+    created.push(`${dataPath} (${result.data})`);
+  }
+  if (created.length > 0) {
+    console.log("Schema Sentry init complete.");
+    console.log(`Created ${created.length} file(s):`);
+    created.forEach((entry) => console.log(`- ${entry}`));
+  }
+  if (result.manifest === "skipped" || result.data === "skipped") {
+    console.log("Some files were skipped. Use --force to overwrite.");
+  }
+  if (result.manifest === "skipped" && result.data === "skipped") {
+    console.log("No files were written.");
+  }
+  if (created.length > 0) {
+    console.log("Next: run `schemasentry validate` to verify your setup.");
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schemasentry/cli",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "CLI for Schema Sentry validation and reporting.",
   "license": "MIT",
   "type": "module",
@@ -33,10 +33,11 @@
   },
   "dependencies": {
     "commander": "^12.0.0",
-    "@schemasentry/core": "0.1.0"
+    "@schemasentry/core": "0.3.1"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean --tsconfig tsconfig.build.json",
+    "benchmark:200": "node ./scripts/benchmark-200-routes.mjs",
     "lint": "echo \"lint not configured\" && exit 0",
     "test": "vitest run"
   }