@decantr/verifier 2.3.2 → 2.4.0

package/README.md

@@ -23,6 +23,8 @@ npm install @decantr/verifier
 - interaction findings now include scanned file counts, file line ranges, and expected signal evidence where available, so CLI health/check output can point agents at source-grounded remediation
 - contract-only Brownfield critique avoids requiring Decantr treatments/decorators when the project keeps its own styling authority
 - project audits check that `pack-manifest.json` references real pack markdown/JSON files on disk
+- project audits tolerate partial or malformed generated review packs without crashing Project Health, so half-attached Brownfield projects still receive actionable findings
+- Next.js static/document outputs are treated as framework-rendered documents instead of requiring a Vite-style `id="root"` mount element
 - project source audits ignore test, spec, story, fixture, and mock files for production drift warnings such as localhost endpoints and unsafe rendering patterns
 - published verifier report schemas are exercised by AJV-backed round-trip tests against real audit, critique, and shortlist-report outputs
 - project audits include runtime evidence when a built `dist/` output is present:
@@ -65,6 +67,10 @@ function isBlocking(report: ProjectHealthReport) {
 - `@decantr/verifier/schema/file-critique-report.v1.json`
 - `@decantr/verifier/schema/showcase-shortlist-report.v1.json`
 
+## Security And Permissions
+
+The verifier is a local library. It reads selected project source, Decantr context, and built `dist`/`.next` output when callers request project or runtime audits. Built-output runtime audit starts a temporary loopback static server and fetches from that local server only; it does not contact external hosts. The verifier does not write files, spawn processes, emit telemetry, or upload source by itself. See [security permissions](https://decantr.ai/reference/security-permissions.md).
+
 ## Compatibility
 
 `@decantr/verifier` is stable in the `2.x` line for the documented verifier APIs and published report-schema exports.

package/dist/index.js

@@ -349,6 +349,17 @@ function normalizeRouteHint(route) {
   }
   return route;
 }
+function isNextProject(projectRoot) {
+  if (existsSync(join(projectRoot, "next.config.js")) || existsSync(join(projectRoot, "next.config.ts")) || existsSync(join(projectRoot, "next.config.mjs")) || existsSync(join(projectRoot, "next.config.cjs"))) {
+    return true;
+  }
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf-8"));
+    return Boolean(pkg.dependencies?.next || pkg.devDependencies?.next);
+  } catch {
+    return false;
+  }
+}
 async function startStaticServer(rootDir) {
   const server = createServer((req, res) => {
     const requestedUrl = new URL(req.url ?? "/", "http://127.0.0.1");
@@ -410,14 +421,15 @@ async function auditBuiltDist(projectRoot, options = {}) {
     };
   }
   const routeHints = Array.isArray(options.routeHints) && options.routeHints.length > 0 ? options.routeHints.map((route) => normalizeRouteHint(route)).filter(Boolean).slice(0, 8) : ["/"];
+  const frameworkDocumentOutput = isNextProject(projectRoot);
   const indexHtml = readFileSync(indexPath, "utf-8");
   const assetPaths = extractAssetPaths(indexHtml);
   const server = await startStaticServer(distDir);
   try {
     const rootResponse = await fetch(`${server.baseUrl}/`);
     const rootHtml = await rootResponse.text();
-    const failures = [];
-    const rootDocumentOk = rootResponse.ok && /id="root"/.test(rootHtml);
+    const failures = frameworkDocumentOutput ? ["next-build-output"] : [];
+    const rootDocumentOk = rootResponse.ok && (frameworkDocumentOutput || /id="root"/.test(rootHtml));
     const titleOk = /<title>[^<]+<\/title>/i.test(rootHtml);
     const langOk = /<html[^>]*\slang=(["'])[^"']+\1/i.test(rootHtml);
     const viewportOk = /<meta[^>]+name=(["'])viewport\1[^>]*>/i.test(rootHtml);
@@ -497,7 +509,7 @@ async function auditBuiltDist(projectRoot, options = {}) {
     for (const routeHint of routeHints) {
       const routeResponse = await fetch(`${server.baseUrl}${routeHint}`);
       const routeHtml = await routeResponse.text();
-      const routeRootDocumentOk = routeResponse.ok && /id="root"/.test(routeHtml);
+      const routeRootDocumentOk = routeResponse.ok && (frameworkDocumentOutput || /id="root"/.test(routeHtml));
       const routeTitleOk = /<title>[^<]+<\/title>/i.test(routeHtml);
       const routeLangOk = /<html[^>]*\slang=(["'])[^"']+\1/i.test(routeHtml);
       const routeViewportOk = /<meta[^>]+name=(["'])viewport\1[^>]*>/i.test(routeHtml);
@@ -1900,7 +1912,7 @@ function extractRouteHintsFromEssence(essence) {
   return [...routes].filter(Boolean).slice(0, 8);
 }
 function summarizeTopology(essence, reviewPack) {
-  const features = new Set(reviewPack?.data.features ?? []);
+  const features = new Set(reviewPack?.data?.features ?? []);
   const sectionRoles = /* @__PURE__ */ new Set();
   const gatewayRoutes = /* @__PURE__ */ new Set();
   const primaryRoutes = /* @__PURE__ */ new Set();
@@ -2117,7 +2129,7 @@ function appendRuntimeAuditFindings(findings, runtimeAudit, projectRoot, topolog
     );
     return;
   }
-  if (runtimeAudit.rootDocumentOk === false) {
+  if (runtimeAudit.rootDocumentOk === false && !isFrameworkBuildOutput) {
     findings.push(
       makeFinding({
         id: "runtime-root-document-invalid",
@@ -3773,6 +3785,8 @@ async function auditProject(projectRoot) {
   const reviewPack = loadReviewPack(projectRoot);
   const packManifest = loadPackManifest(projectRoot);
   const adoptionMode = readProjectAdoptionMode(projectRoot);
+  const packHydrationOptional = adoptionMode === "contract-only";
+  const packHydrationSeverity = packHydrationOptional ? "info" : "warn";
   const runtimeAudit = emptyRuntimeAudit();
   if (!existsSync2(essencePath)) {
     findings.push(
@@ -3850,10 +3864,10 @@ async function auditProject(projectRoot) {
       makeFinding({
         id: "pack-manifest-missing",
         category: "Execution Packs",
-        severity: "warn",
-        message: "Compiled execution pack manifest is missing.",
+        severity: packHydrationSeverity,
+        message: packHydrationOptional ? "Compiled execution pack manifest is not hydrated yet; this is optional for contract-only Brownfield adoption." : "Compiled execution pack manifest is missing.",
         evidence: [join2(projectRoot, ".decantr", "context", "pack-manifest.json")],
-        suggestedFix: "Run `decantr registry compile-packs decantr.essence.json --write-context` to hydrate scaffold, review, mutation, section, and page packs."
+        suggestedFix: packHydrationOptional ? "Optional: run `decantr registry compile-packs decantr.essence.json --write-context` when you want hosted page packs and review packs for richer assistant context." : "Run `decantr registry compile-packs decantr.essence.json --write-context` to hydrate scaffold, review, mutation, section, and page packs."
       })
     );
   } else {
@@ -3914,10 +3928,10 @@ async function auditProject(projectRoot) {
       makeFinding({
         id: "review-pack-file-missing",
         category: "Review Contract",
-        severity: "warn",
-        message: "The compiled review pack file is missing.",
+        severity: packHydrationSeverity,
+        message: packHydrationOptional ? "The compiled review pack file is not hydrated yet; contract-only Brownfield projects can continue without it." : "The compiled review pack file is missing.",
         evidence: [join2(projectRoot, ".decantr", "context", "review-pack.json")],
-        suggestedFix: "Hydrate the full hosted context bundle with `decantr registry compile-packs decantr.essence.json --write-context` so critique consumers can anchor findings to the compiled review contract."
+        suggestedFix: packHydrationOptional ? "Optional: hydrate hosted packs later if you want critique consumers to anchor findings to the compiled review contract." : "Hydrate the full hosted context bundle with `decantr registry compile-packs decantr.essence.json --write-context` so critique consumers can anchor findings to the compiled review contract."
       })
     );
   }
@@ -3985,10 +3999,10 @@ function isCssWhitespace(char) {
   return char === " " || char === "	" || char === "\n" || char === "\r" || char === "\f";
 }
 function resolveFocusAreas(reviewPack) {
-  return reviewPack?.data.focusAreas?.length ? reviewPack.data.focusAreas : DEFAULT_FOCUS_AREAS;
+  return reviewPack?.data?.focusAreas?.length ? reviewPack.data.focusAreas : DEFAULT_FOCUS_AREAS;
 }
 function resolveSeverityFromChecks(reviewPack, fallback, checkIds) {
-  const match = reviewPack?.successChecks.find((check) => checkIds.includes(check.id));
+  const match = reviewPack?.successChecks?.find((check) => checkIds.includes(check.id));
   return match?.severity ?? fallback;
 }
 function findHardcodedColors(code) {
@@ -10990,11 +11004,16 @@ function critiqueSource({
       })
     );
   }
-  const hasProtectedRouteInReview = reviewPack?.data.routes.some((route) => isProtectedLikeRoute(route.path)) ?? false;
-  const hasRecoveryRouteInReview = reviewPack?.data.routes.some((route) => isRecoveryLikeRoute(route.path)) ?? false;
-  const hasSignInRouteInReview = reviewPack?.data.routes.some((route) => isSignInLikeRoute(route.path)) ?? false;
-  const hasRegistrationRouteInReview = reviewPack?.data.routes.some((route) => isRegistrationLikeRoute(route.path)) ?? false;
-  const hasAnonymousEntryRouteInReview = reviewPack?.data.routes.some((route) => isAnonymousEntryLikeRoute(route.path)) ?? false;
+  const reviewRoutes = reviewPack?.data?.routes ?? [];
+  const hasProtectedRouteInReview = reviewRoutes.some((route) => isProtectedLikeRoute(route.path));
+  const hasRecoveryRouteInReview = reviewRoutes.some((route) => isRecoveryLikeRoute(route.path));
+  const hasSignInRouteInReview = reviewRoutes.some((route) => isSignInLikeRoute(route.path));
+  const hasRegistrationRouteInReview = reviewRoutes.some(
+    (route) => isRegistrationLikeRoute(route.path)
+  );
+  const hasAnonymousEntryRouteInReview = reviewRoutes.some(
+    (route) => isAnonymousEntryLikeRoute(route.path)
+  );
   const signInFlowSignals = countSignInFlowSignals(code, filePath);
   const recoveryFlowSignals = countRecoveryFlowSignals(code, filePath);
   const signUpFlowSignals = countSignUpFlowSignals(code, filePath);
@@ -11030,7 +11049,7 @@ function critiqueSource({
         evidence: [
           filePath,
           `Sign-in flow signals: ${signInFlowSignals}`,
-          `Reviewed recovery routes: ${reviewPack?.data.routes.filter((route) => isRecoveryLikeRoute(route.path)).map((route) => route.path).join(", ") || "none"}`,
+          `Reviewed recovery routes: ${reviewRoutes.filter((route) => isRecoveryLikeRoute(route.path)).map((route) => route.path).join(", ") || "none"}`,
           `Recovery route signals: ${authRecoveryRouteSignalCount}`
         ],
         file: filePath,
@@ -11048,7 +11067,7 @@ function critiqueSource({
         evidence: [
           filePath,
           `Sign-in flow signals: ${signInFlowSignals}`,
-          `Reviewed registration routes: ${reviewPack?.data.routes.filter((route) => isRegistrationLikeRoute(route.path)).map((route) => route.path).join(", ") || "none"}`,
+          `Reviewed registration routes: ${reviewRoutes.filter((route) => isRegistrationLikeRoute(route.path)).map((route) => route.path).join(", ") || "none"}`,
           `Registration route signals: ${registrationRouteSignalCount}`
         ],
         file: filePath,
@@ -11066,7 +11085,7 @@ function critiqueSource({
         evidence: [
           filePath,
           `Recovery flow signals: ${recoveryFlowSignals}`,
-          `Reviewed anonymous entry routes: ${reviewPack?.data.routes.filter((route) => isAnonymousEntryLikeRoute(route.path)).map((route) => route.path).join(", ") || "none"}`,
+          `Reviewed anonymous entry routes: ${reviewRoutes.filter((route) => isAnonymousEntryLikeRoute(route.path)).map((route) => route.path).join(", ") || "none"}`,
           `Anonymous entry route signals: ${anonymousEntryRouteSignalCount}`
         ],
         file: filePath,
@@ -11084,7 +11103,7 @@ function critiqueSource({
         evidence: [
           filePath,
           `Registration flow signals: ${signUpFlowSignals}`,
-          `Reviewed sign-in routes: ${reviewPack?.data.routes.filter((route) => isSignInLikeRoute(route.path)).map((route) => route.path).join(", ") || "none"}`,
+          `Reviewed sign-in routes: ${reviewRoutes.filter((route) => isSignInLikeRoute(route.path)).map((route) => route.path).join(", ") || "none"}`,
           `Sign-in route signals: ${signInRouteSignalCount}`
         ],
         file: filePath,
@@ -11105,7 +11124,7 @@ function critiqueSource({
           `Auth callback error signals: ${authCallbackErrorSignalCount}`,
           `Auth callback exchange signals: ${authCallbackExchangeSignalCount}`,
           `Auth callback exchange error signals: ${authCallbackExchangeErrorSignalCount}`,
-          `Reviewed sign-in routes: ${reviewPack?.data.routes.filter((route) => isSignInLikeRoute(route.path)).map((route) => route.path).join(", ") || "none"}`,
+          `Reviewed sign-in routes: ${reviewRoutes.filter((route) => isSignInLikeRoute(route.path)).map((route) => route.path).join(", ") || "none"}`,
           `Sign-in route signals: ${signInRouteSignalCount}`
         ],
         file: filePath,
@@ -11348,7 +11367,7 @@ function critiqueSource({
       })
     );
   }
-  const knownRoutes = reviewPack?.data.routes.length ?? packManifest?.pages.length ?? 0;
+  const knownRoutes = reviewPack?.data?.routes?.length ?? packManifest?.pages.length ?? 0;
   const placeholderNavigationTargets = astSignals.placeholderNavigationTargetCount;
   scores.push({
     category: "Topology Context",