@schemasentry/cli 0.4.0 → 0.5.0

package/README.md

@@ -81,6 +81,40 @@ pnpm schemasentry collect \
   --data ./schema-sentry.data.json
 ```
 
+### `scaffold`
+
+Auto-generate schema stubs for routes without schema (dry-run by default):
+
+```bash
+pnpm schemasentry scaffold --manifest ./schema-sentry.manifest.json --data ./schema-sentry.data.json
+```
+
+Preview what would be generated without writing files:
+
+```bash
+pnpm schemasentry scaffold
+```
+
+Apply scaffolded schema to your files:
+
+```bash
+pnpm schemasentry scaffold --write
+```
+
+Skip confirmation prompts:
+
+```bash
+pnpm schemasentry scaffold --write --force
+```
+
+**Pattern-based auto-detection** infers schema types from URL patterns:
+- `/blog/*` → BlogPosting
+- `/products/*` → Product
+- `/faq` → FAQPage
+- `/events/*` → Event
+- `/howto/*` → HowTo
+- and more...
+
 ## Options
 
 | Option | Description |
@@ -88,10 +122,12 @@ pnpm schemasentry collect \
 | `--format json\|html` | Output format |
 | `--annotations none\|github` | CI annotations |
 | `-o, --output <path>` | Write output to file |
-| `--root <path>` | Root directory to scan for HTML output (`collect`) |
+| `--root <path>` | Root directory to scan (`collect`, `scaffold`) |
 | `--routes <routes...>` | Collect only specific routes (`collect`) |
 | `--strict-routes` | Fail when any route passed to `--routes` is missing (`collect`) |
 | `--check` | Compare collected output with existing data and fail on drift (`collect`) |
+| `--write` | Apply scaffolded changes to files (`scaffold`) |
+| `--force` | Skip confirmation prompts (`scaffold`) |
 | `--recommended / --no-recommended` | Enable recommended field checks |
 
 ## Documentation

package/dist/index.js

@@ -4,8 +4,8 @@
 import { Command } from "commander";
 import { mkdir, readFile, writeFile } from "fs/promises";
 import { readFileSync } from "fs";
-import path5 from "path";
-import { stableStringify as stableStringify3 } from "@schemasentry/core";
+import path6 from "path";
+import { stableStringify as stableStringify4 } from "@schemasentry/core";
 
 // src/report.ts
 import {
@@ -877,6 +877,235 @@ var schemaTypeLabel = (node) => {
   return typeof type === "string" && type.trim().length > 0 ? type : "(unknown)";
 };
 
+// src/scaffold.ts
+import { promises as fs5 } from "fs";
+import path5 from "path";
+import { stableStringify as stableStringify3 } from "@schemasentry/core";
+
+// src/patterns.ts
+var DEFAULT_PATTERNS = [
+  { pattern: "/blog/*", schemaType: "BlogPosting", priority: 10 },
+  { pattern: "/blog", schemaType: "WebPage", priority: 5 },
+  { pattern: "/products/*", schemaType: "Product", priority: 10 },
+  { pattern: "/product/*", schemaType: "Product", priority: 10 },
+  { pattern: "/faq", schemaType: "FAQPage", priority: 10 },
+  { pattern: "/faqs", schemaType: "FAQPage", priority: 10 },
+  { pattern: "/how-to/*", schemaType: "HowTo", priority: 10 },
+  { pattern: "/howto/*", schemaType: "HowTo", priority: 10 },
+  { pattern: "/events/*", schemaType: "Event", priority: 10 },
+  { pattern: "/event/*", schemaType: "Event", priority: 10 },
+  { pattern: "/reviews/*", schemaType: "Review", priority: 10 },
+  { pattern: "/review/*", schemaType: "Review", priority: 10 },
+  { pattern: "/videos/*", schemaType: "VideoObject", priority: 10 },
+  { pattern: "/video/*", schemaType: "VideoObject", priority: 10 },
+  { pattern: "/images/*", schemaType: "ImageObject", priority: 10 },
+  { pattern: "/image/*", schemaType: "ImageObject", priority: 10 },
+  { pattern: "/about", schemaType: "WebPage", priority: 10 },
+  { pattern: "/contact", schemaType: "WebPage", priority: 10 },
+  { pattern: "/", schemaType: "WebSite", priority: 1 }
+];
+var matchRouteToPatterns = (route, patterns = DEFAULT_PATTERNS) => {
+  const matches = [];
+  for (const rule of patterns) {
+    if (routeMatchesPattern(route, rule.pattern)) {
+      matches.push({
+        type: rule.schemaType,
+        priority: rule.priority ?? 5
+      });
+    }
+  }
+  matches.sort((a, b) => b.priority - a.priority);
+  return [...new Set(matches.map((m) => m.type))];
+};
+var routeMatchesPattern = (route, pattern) => {
+  if (pattern === route) {
+    return true;
+  }
+  if (pattern.endsWith("/*")) {
+    const prefix = pattern.slice(0, -1);
+    return route.startsWith(prefix);
+  }
+  const patternRegex = pattern.replace(/\*/g, "[^/]+").replace(/\?/g, ".");
+  const regex = new RegExp(`^${patternRegex}$`);
+  return regex.test(route);
+};
+var inferSchemaTypes = (routes, customPatterns) => {
+  const patterns = customPatterns ?? DEFAULT_PATTERNS;
+  const result = /* @__PURE__ */ new Map();
+  for (const route of routes) {
+    const types = matchRouteToPatterns(route, patterns);
+    if (types.length > 0) {
+      result.set(route, types);
+    }
+  }
+  return result;
+};
+var generateManifestEntries = (routes, customPatterns) => {
+  const inferred = inferSchemaTypes(routes, customPatterns);
+  const entries = {};
+  for (const [route, types] of inferred) {
+    entries[route] = types;
+  }
+  return entries;
+};
+
+// src/scaffold.ts
+var scaffoldSchema = async (options) => {
+  const manifest = await loadManifest(options.manifestPath);
+  const data = await loadData(options.dataPath);
+  const discoveredRoutes = await scanRoutes({ rootDir: options.rootDir });
+  const routesNeedingSchema = discoveredRoutes.filter(
+    (route) => !data.routes[route] || data.routes[route].length === 0
+  );
+  const inferredTypes = inferSchemaTypes(routesNeedingSchema, options.customPatterns);
+  const manifestEntries = generateManifestEntries(
+    routesNeedingSchema,
+    options.customPatterns
+  );
+  const generatedSchemas = /* @__PURE__ */ new Map();
+  for (const [route, types] of inferredTypes) {
+    const schemas = types.map((type) => generateSchemaStub(type, route));
+    generatedSchemas.set(route, schemas);
+  }
+  const wouldUpdate = routesNeedingSchema.length > 0;
+  return {
+    routesToScaffold: routesNeedingSchema,
+    generatedSchemas,
+    manifestUpdates: manifestEntries,
+    wouldUpdate
+  };
+};
+var loadManifest = async (manifestPath) => {
+  try {
+    const raw = await fs5.readFile(manifestPath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return { routes: {} };
+  }
+};
+var loadData = async (dataPath) => {
+  try {
+    const raw = await fs5.readFile(dataPath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return { routes: {} };
+  }
+};
+var generateSchemaStub = (type, route) => {
+  const base = {
+    "@context": "https://schema.org",
+    "@type": type
+  };
+  switch (type) {
+    case "BlogPosting":
+      return {
+        ...base,
+        headline: "Blog Post Title",
+        author: {
+          "@type": "Person",
+          name: "Author Name"
+        },
+        datePublished: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+        url: route
+      };
+    case "Product":
+      return {
+        ...base,
+        name: "Product Name",
+        description: "Product description",
+        offers: {
+          "@type": "Offer",
+          price: "0.00",
+          priceCurrency: "USD"
+        }
+      };
+    case "FAQPage":
+      return {
+        ...base,
+        mainEntity: []
+      };
+    case "HowTo":
+      return {
+        ...base,
+        name: "How-To Title",
+        step: []
+      };
+    case "Event":
+      return {
+        ...base,
+        name: "Event Name",
+        startDate: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    case "Organization":
+      return {
+        ...base,
+        name: "Organization Name",
+        url: route
+      };
+    case "WebSite":
+      return {
+        ...base,
+        name: "Website Name",
+        url: route
+      };
+    case "Article":
+      return {
+        ...base,
+        headline: "Article Headline",
+        author: {
+          "@type": "Person",
+          name: "Author Name"
+        },
+        datePublished: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
+      };
+    default:
+      return {
+        ...base,
+        name: `${type} Name`
+      };
+  }
+};
+var formatScaffoldPreview = (result) => {
+  if (result.routesToScaffold.length === 0) {
+    return "No routes need schema generation.";
+  }
+  const lines = [
+    `Routes to scaffold: ${result.routesToScaffold.length}`,
+    ""
+  ];
+  for (const route of result.routesToScaffold) {
+    const types = result.manifestUpdates[route] || [];
+    lines.push(`  ${route}`);
+    lines.push(`    Schema types: ${types.join(", ") || "None detected"}`);
+  }
+  return lines.join("\n");
+};
+var applyScaffold = async (result, options) => {
+  if (!result.wouldUpdate) {
+    return;
+  }
+  const manifest = await loadManifest(options.manifestPath);
+  const data = await loadData(options.dataPath);
+  for (const [route, types] of Object.entries(result.manifestUpdates)) {
+    if (!manifest.routes[route]) {
+      manifest.routes[route] = types;
+    }
+  }
+  for (const [route, schemas] of result.generatedSchemas) {
+    if (!data.routes[route]) {
+      data.routes[route] = schemas;
+    }
+  }
+  await fs5.mkdir(path5.dirname(options.manifestPath), { recursive: true });
+  await fs5.mkdir(path5.dirname(options.dataPath), { recursive: true });
+  await fs5.writeFile(
+    options.manifestPath,
+    stableStringify3(manifest),
+    "utf8"
+  );
+  await fs5.writeFile(options.dataPath, stableStringify3(data), "utf8");
+};
+
 // src/index.ts
 import { createInterface } from "readline/promises";
 import { stdin as input, stdout as output } from "process";
@@ -895,8 +1124,8 @@ program.command("validate").description("Validate schema coverage and rules").op
   const format = resolveOutputFormat(options.format);
   const annotationsMode = resolveAnnotationsMode(options.annotations);
   const recommended = await resolveRecommendedOption(options.config);
-  const manifestPath = path5.resolve(process.cwd(), options.manifest);
-  const dataPath = path5.resolve(process.cwd(), options.data);
+  const manifestPath = path6.resolve(process.cwd(), options.manifest);
+  const dataPath = path6.resolve(process.cwd(), options.data);
   let raw;
   try {
     raw = await readFile(manifestPath, "utf8");
@@ -983,12 +1212,12 @@ program.command("init").description("Interactive setup wizard").option(
   "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 = path5.resolve(process.cwd(), options.manifest);
-  const dataPath = path5.resolve(process.cwd(), options.data);
+  const manifestPath = path6.resolve(process.cwd(), options.manifest);
+  const dataPath = path6.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: path5.resolve(process.cwd(), options.root ?? ".") }) : [];
+  const scannedRoutes = options.scan ? await scanRoutes({ rootDir: path6.resolve(process.cwd(), options.root ?? ".") }) : [];
   if (options.scan && scannedRoutes.length === 0) {
     console.error("No routes found during scan.");
   }
@@ -1017,7 +1246,7 @@ program.command("audit").description("Analyze schema health and report issues").
   const format = resolveOutputFormat(options.format);
   const annotationsMode = resolveAnnotationsMode(options.annotations);
   const recommended = await resolveRecommendedOption(options.config);
-  const dataPath = path5.resolve(process.cwd(), options.data);
+  const dataPath = path6.resolve(process.cwd(), options.data);
   let dataRaw;
   try {
     dataRaw = await readFile(dataPath, "utf8");
@@ -1053,7 +1282,7 @@ program.command("audit").description("Analyze schema health and report issues").
   }
   let manifest;
   if (options.manifest) {
-    const manifestPath = path5.resolve(process.cwd(), options.manifest);
+    const manifestPath = path6.resolve(process.cwd(), options.manifest);
     let manifestRaw;
     try {
       manifestRaw = await readFile(manifestPath, "utf8");
@@ -1087,7 +1316,7 @@ program.command("audit").description("Analyze schema health and report issues").
       return;
     }
   }
-  const requiredRoutes = options.scan ? await scanRoutes({ rootDir: path5.resolve(process.cwd(), options.root ?? ".") }) : [];
+  const requiredRoutes = options.scan ? await scanRoutes({ rootDir: path6.resolve(process.cwd(), options.root ?? ".") }) : [];
   if (options.scan && requiredRoutes.length === 0) {
     console.error("No routes found during scan.");
   }
@@ -1113,7 +1342,7 @@ program.command("collect").description("Collect JSON-LD blocks from built HTML o
 ).action(async (options) => {
   const start = Date.now();
   const format = resolveCollectOutputFormat(options.format);
-  const rootDir = path5.resolve(process.cwd(), options.root ?? ".");
+  const rootDir = path6.resolve(process.cwd(), options.root ?? ".");
   const check = options.check ?? false;
   const requestedRoutes = normalizeRouteFilter(options.routes ?? []);
   const strictRoutes = options.strictRoutes ?? false;
@@ -1150,7 +1379,7 @@ program.command("collect").description("Collect JSON-LD blocks from built HTML o
   }
   let driftDetected = false;
   if (check) {
-    const existingPath = path5.resolve(process.cwd(), options.data);
+    const existingPath = path6.resolve(process.cwd(), options.data);
     let existingRaw;
     try {
       existingRaw = await readFile(existingPath, "utf8");
@@ -1195,9 +1424,9 @@ program.command("collect").description("Collect JSON-LD blocks from built HTML o
   }
   const content = formatCollectOutput(collected.data, format);
   if (options.output) {
-    const resolvedPath = path5.resolve(process.cwd(), options.output);
+    const resolvedPath = path6.resolve(process.cwd(), options.output);
     try {
-      await mkdir(path5.dirname(resolvedPath), { recursive: true });
+      await mkdir(path6.dirname(resolvedPath), { recursive: true });
       await writeFile(resolvedPath, `${content}
 `, "utf8");
       console.error(`Collected data written to ${resolvedPath}`);
@@ -1225,6 +1454,65 @@ program.command("collect").description("Collect JSON-LD blocks from built HTML o
   });
   process.exit(driftDetected ? 1 : 0);
 });
+program.command("scaffold").description("Generate schema stubs for routes without schema (dry-run by default)").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("--root <path>", "Project root for scanning", ".").option("--write", "Apply changes (default is dry-run)").option("-f, --force", "Skip confirmation prompts").action(async (options) => {
+  const start = Date.now();
+  const manifestPath = path6.resolve(process.cwd(), options.manifest);
+  const dataPath = path6.resolve(process.cwd(), options.data);
+  const rootDir = path6.resolve(process.cwd(), options.root ?? ".");
+  const dryRun = !(options.write ?? false);
+  const force = options.force ?? false;
+  const result = await scaffoldSchema({
+    manifestPath,
+    dataPath,
+    rootDir,
+    dryRun,
+    force
+  });
+  console.error(formatScaffoldPreview(result));
+  if (!result.wouldUpdate) {
+    process.exit(0);
+    return;
+  }
+  if (dryRun) {
+    console.error("\nDry run complete. Use --write to apply changes.");
+    process.exit(0);
+    return;
+  }
+  if (!force) {
+    console.error("\nScaffolding will update:");
+    console.error(`  - ${manifestPath}`);
+    console.error(`  - ${dataPath}`);
+    console.error("\nUse --force to skip this confirmation.");
+  }
+  try {
+    await applyScaffold(result, {
+      manifestPath,
+      dataPath,
+      rootDir,
+      dryRun,
+      force
+    });
+    console.error(`
+Scaffold complete in ${Date.now() - start}ms`);
+    process.exit(0);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    printCliError(
+      "scaffold.apply_failed",
+      `Failed to apply scaffold: ${message}`,
+      "Check file permissions or disk space."
+    );
+    process.exit(1);
+  }
+});
 function isManifest(value) {
   if (!value || typeof value !== "object") {
     return false;
@@ -1298,13 +1586,13 @@ function formatReportOutput(report, format, title) {
   if (format === "html") {
     return renderHtmlReport(report, { title });
   }
-  return stableStringify3(report);
+  return stableStringify4(report);
 }
 function formatCollectOutput(data, format) {
   if (format === "json") {
-    return stableStringify3(data);
+    return stableStringify4(data);
   }
-  return stableStringify3(data);
+  return stableStringify4(data);
 }
 async function emitReport(options) {
   const { report, format, outputPath, title } = options;
@@ -1313,9 +1601,9 @@ async function emitReport(options) {
     console.log(content);
     return;
   }
-  const resolvedPath = path5.resolve(process.cwd(), outputPath);
+  const resolvedPath = path6.resolve(process.cwd(), outputPath);
   try {
-    await mkdir(path5.dirname(resolvedPath), { recursive: true });
+    await mkdir(path6.dirname(resolvedPath), { recursive: true });
     await writeFile(resolvedPath, content, "utf8");
     console.error(`Report written to ${resolvedPath}`);
   } catch (error) {
@@ -1335,7 +1623,7 @@ function emitAnnotations(report, mode, commandLabel) {
 }
 function printCliError(code, message, suggestion) {
   console.error(
-    stableStringify3({
+    stableStringify4({
       ok: false,
       errors: [
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schemasentry/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "CLI for Schema Sentry validation and reporting.",
   "license": "MIT",
   "type": "module",
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "commander": "^12.0.0",
-    "@schemasentry/core": "0.4.0"
+    "@schemasentry/core": "0.5.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean --tsconfig tsconfig.build.json",