@decantr/verifier 1.0.5 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Decantr AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -16,7 +16,8 @@ npm install @decantr/verifier
 - `auditProject()` for project-level Decantr audits
 - `auditBuiltDist()` for built-output runtime verification against emitted HTML, assets, and route hints
 - `critiqueFile()` for file-level review against compiled review-pack contracts
-- schema-backed report types for project audits, file critiques, and showcase verification
+- schema-backed report types for project audits, Project Health, file critiques, and showcase verification
+- `ProjectHealthReport`, `ProjectHealthFinding`, and `ProjectHealthRemediation` types for the CLI's end-user health surface
 - 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:
   - root document
@@ -30,16 +31,21 @@ npm install @decantr/verifier
 ## Example
 
 ```ts
-import { auditProject, critiqueFile } from '@decantr/verifier';
+import { auditProject, critiqueFile, type ProjectHealthReport } from '@decantr/verifier';
 
 const audit = await auditProject(process.cwd());
 const critique = await critiqueFile('./src/pages/overview.tsx', process.cwd());
+
+function isBlocking(report: ProjectHealthReport) {
+  return report.status === 'error';
+}
 ```
 
 ## Schema Exports
 
 - `@decantr/verifier/schema/verification-report.common.v1.json`
 - `@decantr/verifier/schema/project-audit-report.v1.json`
+- `@decantr/verifier/schema/project-health-report.v1.json`
 - `@decantr/verifier/schema/file-critique-report.v1.json`
 - `@decantr/verifier/schema/showcase-shortlist-report.v1.json`
 

package/dist/index.d.ts

@@ -118,10 +118,13 @@ declare function listKnownInteractions(): string[];
 declare const VERIFICATION_SCHEMA_URLS: {
     readonly common: "https://decantr.ai/schemas/verification-report.common.v1.json";
     readonly projectAudit: "https://decantr.ai/schemas/project-audit-report.v1.json";
+    readonly projectHealth: "https://decantr.ai/schemas/project-health-report.v1.json";
     readonly fileCritique: "https://decantr.ai/schemas/file-critique-report.v1.json";
     readonly showcaseShortlist: "https://decantr.ai/schemas/showcase-shortlist-report.v1.json";
 };
 type VerificationSeverity = 'error' | 'warn' | 'info';
+type ProjectHealthStatus = 'healthy' | 'warning' | 'error';
+type ProjectHealthFindingSource = 'audit' | 'check' | 'brownfield' | 'runtime' | 'pack' | 'interaction';
 interface VerificationFinding {
     id: string;
     category: string;
@@ -183,6 +186,68 @@ interface ProjectAuditReport {
         pageCount: number;
     };
 }
+interface ProjectHealthRemediation {
+    summary: string;
+    prompt: string;
+    commands: string[];
+}
+interface ProjectHealthFinding {
+    id: string;
+    source: ProjectHealthFindingSource;
+    category: string;
+    severity: VerificationSeverity;
+    message: string;
+    evidence: string[];
+    target?: string;
+    file?: string;
+    rule?: string;
+    suggestedFix?: string;
+    remediation: ProjectHealthRemediation;
+}
+interface ProjectHealthRouteSummary {
+    declared: string[];
+    runtimeChecked: string[];
+    runtimeMatched: number;
+    runtimeCoverageOk: boolean | null;
+    issues: string[];
+}
+interface ProjectHealthPackSummary {
+    manifestPresent: boolean;
+    reviewPackPresent: boolean;
+    scaffoldPackPresent: boolean;
+    sectionPackCount: number;
+    pagePackCount: number;
+    mutationPackCount: number;
+    generatedAt: string | null;
+}
+interface ProjectHealthReport {
+    $schema: string;
+    generatedAt: string;
+    projectRoot: string;
+    status: ProjectHealthStatus;
+    score: number;
+    summary: {
+        errorCount: number;
+        warnCount: number;
+        infoCount: number;
+        findingCount: number;
+        workflowMode: string | null;
+        adoptionMode: string | null;
+        essenceVersion: string | null;
+        pageCount: number;
+        runtimeAuditChecked: boolean;
+        runtimePassed: boolean | null;
+        packManifestPresent: boolean;
+        reviewPackPresent: boolean;
+    };
+    routes: ProjectHealthRouteSummary;
+    packs: ProjectHealthPackSummary;
+    ci: {
+        recommendedCommand: string;
+        failOn: 'error' | 'warn' | 'none';
+    };
+    findings: ProjectHealthFinding[];
+}
 interface FileCritiqueReport {
     $schema: string;
     file: string;
@@ -297,4 +362,4 @@ declare function auditProject(projectRoot: string): Promise<ProjectAuditReport>;
 declare function critiqueSource({ filePath, code, reviewPack, packManifest, treatmentsCss, }: CritiqueSourceInput): FileCritiqueReport;
 declare function critiqueFile(filePath: string, projectRoot: string): Promise<FileCritiqueReport>;
 
-export { type BuiltDistAuditOptions, type CritiqueSourceInput, type FileCritiqueReport, INTERACTION_SIGNALS, type InteractionMissingFinding, type InteractionRequirement, type InteractionSignal, type PackManifest, type ProjectAuditReport, type RuntimeAudit, type ShowcaseShortlistVerificationEntry, type ShowcaseShortlistVerificationReport, VERIFICATION_SCHEMA_URLS, type VerificationFinding, type VerificationScore, type VerificationSeverity, auditBuiltDist, auditProject, critiqueFile, critiqueSource, emptyRuntimeAudit, extractRouteHintsFromEssence, listKnownInteractions, verifyInteractionsInSource };
+export { type BuiltDistAuditOptions, type CritiqueSourceInput, type FileCritiqueReport, INTERACTION_SIGNALS, type InteractionMissingFinding, type InteractionRequirement, type InteractionSignal, type PackManifest, type ProjectAuditReport, type ProjectHealthFinding, type ProjectHealthFindingSource, type ProjectHealthPackSummary, type ProjectHealthRemediation, type ProjectHealthReport, type ProjectHealthRouteSummary, type ProjectHealthStatus, type RuntimeAudit, type ShowcaseShortlistVerificationEntry, type ShowcaseShortlistVerificationReport, VERIFICATION_SCHEMA_URLS, type VerificationFinding, type VerificationScore, type VerificationSeverity, auditBuiltDist, auditProject, critiqueFile, critiqueSource, emptyRuntimeAudit, extractRouteHintsFromEssence, listKnownInteractions, verifyInteractionsInSource };

package/dist/index.js

@@ -610,6 +610,7 @@ function listKnownInteractions() {
 var VERIFICATION_SCHEMA_URLS = {
   common: "https://decantr.ai/schemas/verification-report.common.v1.json",
   projectAudit: "https://decantr.ai/schemas/project-audit-report.v1.json",
+  projectHealth: "https://decantr.ai/schemas/project-health-report.v1.json",
   fileCritique: "https://decantr.ai/schemas/file-critique-report.v1.json",
   showcaseShortlist: "https://decantr.ai/schemas/showcase-shortlist-report.v1.json"
 };
@@ -3312,8 +3313,30 @@ async function auditProject(projectRoot) {
   };
 }
 function buildDecoratorInventory(treatmentsCss) {
-  const decoratorMatches = treatmentsCss.match(/\.([\w-]+)\s*\{/g) || [];
-  return decoratorMatches.map((match) => match.slice(1).replace(/\s*\{$/, "")).filter((name) => !name.startsWith("d-") && !PERSONALITY_UTILS.includes(name));
+  const decoratorNames = /* @__PURE__ */ new Set();
+  for (let index = treatmentsCss.indexOf("."); index !== -1; index = treatmentsCss.indexOf(".", index + 1)) {
+    let cursor = index + 1;
+    while (cursor < treatmentsCss.length && isCssClassNameChar(treatmentsCss[cursor])) {
+      cursor += 1;
+    }
+    if (cursor === index + 1) continue;
+    const name = treatmentsCss.slice(index + 1, cursor);
+    let whitespaceCursor = cursor;
+    while (whitespaceCursor < treatmentsCss.length && whitespaceCursor - cursor <= 64 && isCssWhitespace(treatmentsCss[whitespaceCursor])) {
+      whitespaceCursor += 1;
+    }
+    if (treatmentsCss[whitespaceCursor] === "{") {
+      decoratorNames.add(name);
+    }
+  }
+  return [...decoratorNames].filter((name) => !name.startsWith("d-") && !PERSONALITY_UTILS.includes(name));
+}
+function isCssClassNameChar(char) {
+  const codePoint = char.charCodeAt(0);
+  return char === "_" || char === "-" || codePoint >= 48 && codePoint <= 57 || codePoint >= 65 && codePoint <= 90 || codePoint >= 97 && codePoint <= 122;
+}
+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;
@@ -3323,9 +3346,49 @@ function resolveSeverityFromChecks(reviewPack, fallback, checkIds) {
   return match?.severity ?? fallback;
 }
 function findHardcodedColors(code) {
-  const matches = code.match(/#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)|hsla?\([^)]*\)/g) ?? [];
+  const matches = [
+    ...findHexColors(code),
+    ...findColorFunctionCalls(code, "rgb("),
+    ...findColorFunctionCalls(code, "rgba("),
+    ...findColorFunctionCalls(code, "hsl("),
+    ...findColorFunctionCalls(code, "hsla(")
+  ];
   return [...new Set(matches)];
 }
+function findHexColors(code) {
+  const matches = [];
+  for (let index = 0; index < code.length; index += 1) {
+    if (code[index] !== "#") continue;
+    let cursor = index + 1;
+    while (cursor < code.length && cursor - index <= 8 && isHexDigit(code[cursor])) {
+      cursor += 1;
+    }
+    const length = cursor - index - 1;
+    if (length >= 3 && length <= 8 && !isHexDigit(code[cursor] ?? "")) {
+      matches.push(code.slice(index, cursor));
+    }
+  }
+  return matches;
+}
+function findColorFunctionCalls(code, functionName) {
+  const matches = [];
+  const lowerCode = code.toLowerCase();
+  for (let index = lowerCode.indexOf(functionName); index !== -1; index = lowerCode.indexOf(functionName, index + functionName.length)) {
+    let cursor = index + functionName.length;
+    const maxCursor = Math.min(code.length, cursor + 256);
+    while (cursor < maxCursor && code[cursor] !== ")" && code[cursor] !== "\n" && code[cursor] !== "\r") {
+      cursor += 1;
+    }
+    if (code[cursor] === ")") {
+      matches.push(code.slice(index, cursor + 1));
+    }
+  }
+  return matches;
+}
+function isHexDigit(char) {
+  const codePoint = char.charCodeAt(0);
+  return codePoint >= 48 && codePoint <= 57 || codePoint >= 65 && codePoint <= 70 || codePoint >= 97 && codePoint <= 102;
+}
 function findUtilityFrameworkSignals(code) {
   const matches = code.match(
     /\b(?:bg|text|border|shadow|rounded|px|py|mx|my|gap|grid-cols|col-span|row-span|sm|md|lg|xl|hover):[-\w/.[\]]+/g
@@ -4789,18 +4852,10 @@ function countAuthCallbackStateValidationSignals(code) {
   if (/\b(?:validateState|verifyState|assertState|compareState|checkState)\s*\(/i.test(code)) {
     count += 1;
   }
-  if (/\b(?:sessionStorage|localStorage)\.getItem\s*\(\s*['"`][^'"`]*(?:state|csrf)[^'"`]*['"`]\s*\)/i.test(
-    code
-  ) && /(?:state|providerState|callbackState|returnedState|expectedState|storedState|sessionState|oauthState|csrfState)\s*(?:===|==|!==|!=)/i.test(
-    code
-  )) {
+  if (countStateLikeMemberCalls(code, ["sessionStorage", "localStorage"], ["getItem"]) > 0 && hasStateComparison(code)) {
     count += 1;
   }
-  if (/\b(?:cookies?|cookieStore)\.(?:get|getAll)\s*\(\s*['"`][^'"`]*(?:state|csrf)[^'"`]*['"`]\s*\)/i.test(
-    code
-  ) && /(?:state|providerState|callbackState|returnedState|expectedState|storedState|sessionState|oauthState|csrfState)\s*(?:===|==|!==|!=)/i.test(
-    code
-  )) {
+  if (countStateLikeMemberCalls(code, ["cookies", "cookie", "cookieStore"], ["get", "getAll"]) > 0 && hasStateComparison(code)) {
     count += 1;
   }
   if (/\b(?:state|providerState|callbackState|returnedState)\b\s*(?:===|==|!==|!=)\s*\b(?:expectedState|storedState|sessionState|oauthState|csrfState)\b/i.test(
@@ -4812,21 +4867,142 @@ function countAuthCallbackStateValidationSignals(code) {
   }
   return count;
 }
+function hasStateComparison(code) {
+  return /(?:state|providerState|callbackState|returnedState|expectedState|storedState|sessionState|oauthState|csrfState)\s*(?:===|==|!==|!=)/i.test(
+    code
+  );
+}
+function countStateLikeMemberCalls(code, receivers, methods) {
+  const lowerCode = code.toLowerCase();
+  let count = 0;
+  for (const receiver of receivers) {
+    const receiverLower = receiver.toLowerCase();
+    for (let index = lowerCode.indexOf(receiverLower); index !== -1; index = lowerCode.indexOf(receiverLower, index + receiverLower.length)) {
+      let cursor = index + receiverLower.length;
+      cursor = skipInlineWhitespace(lowerCode, cursor);
+      if (lowerCode[cursor] !== ".") continue;
+      cursor = skipInlineWhitespace(lowerCode, cursor + 1);
+      for (const method of methods) {
+        const methodLower = method.toLowerCase();
+        if (!lowerCode.startsWith(methodLower, cursor)) continue;
+        const afterMethod = skipInlineWhitespace(lowerCode, cursor + methodLower.length);
+        if (lowerCode[afterMethod] !== "(") continue;
+        if (callHasStateLikeStringArgument(code, afterMethod)) {
+          count += 1;
+        }
+      }
+    }
+  }
+  return count;
+}
+function countStateLikeFunctionCalls(code, names) {
+  const lowerCode = code.toLowerCase();
+  let count = 0;
+  for (const name of names) {
+    const nameLower = name.toLowerCase();
+    for (let index = lowerCode.indexOf(nameLower); index !== -1; index = lowerCode.indexOf(nameLower, index + nameLower.length)) {
+      const afterName = skipInlineWhitespace(lowerCode, index + nameLower.length);
+      if (lowerCode[afterName] === "(" && callHasStateLikeStringArgument(code, afterName)) {
+        count += 1;
+      }
+    }
+  }
+  return count;
+}
+function skipInlineWhitespace(value, index) {
+  let cursor = index;
+  while (cursor < value.length) {
+    const char = value[cursor];
+    if (char !== " " && char !== "	" && char !== "\n" && char !== "\r") break;
+    cursor += 1;
+  }
+  return cursor;
+}
+function callHasStateLikeStringArgument(code, openParenIndex) {
+  const closeParenIndex = findCallCloseParen(code, openParenIndex, 240);
+  if (closeParenIndex === -1) return false;
+  return containsStateLikeStringLiteral(code.slice(openParenIndex + 1, closeParenIndex));
+}
+function findCallCloseParen(code, openParenIndex, maxLength) {
+  const maxIndex = Math.min(code.length, openParenIndex + maxLength);
+  let quote = null;
+  let escaped = false;
+  for (let index = openParenIndex + 1; index < maxIndex; index += 1) {
+    const char = code[index];
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === "'" || char === '"' || char === "`") {
+      quote = char;
+    } else if (char === ")") {
+      return index;
+    }
+  }
+  return -1;
+}
+function containsStateLikeStringLiteral(value) {
+  let quote = null;
+  let literal = "";
+  let escaped = false;
+  for (const char of value) {
+    if (!quote) {
+      if (char === "'" || char === '"' || char === "`") {
+        quote = char;
+        literal = "";
+      }
+      continue;
+    }
+    if (escaped) {
+      literal += char;
+      escaped = false;
+    } else if (char === "\\") {
+      escaped = true;
+    } else if (char === quote) {
+      const lowerLiteral = literal.toLowerCase();
+      if (lowerLiteral.includes("state") || lowerLiteral.includes("csrf")) return true;
+      quote = null;
+    } else {
+      literal += char;
+    }
+  }
+  return false;
+}
 function countAuthCallbackStateStorageSignals(code) {
-  const patterns = [
-    /\b(?:sessionStorage|localStorage)\.getItem\s*\(\s*['"`][^'"`]*(?:state|csrf)[^'"`]*['"`]\s*\)/gi,
-    /\b(?:cookies?|cookieStore)\.(?:get|getAll)\s*\(\s*['"`][^'"`]*(?:state|csrf)[^'"`]*['"`]\s*\)/gi
-  ];
-  return patterns.reduce((total, pattern) => total + (code.match(pattern)?.length ?? 0), 0);
+  return countStateLikeMemberCalls(code, ["sessionStorage", "localStorage"], ["getItem"]) + countStateLikeMemberCalls(code, ["cookies", "cookie", "cookieStore"], ["get", "getAll"]);
 }
 function countAuthCallbackStateStorageClearSignals(code) {
-  const patterns = [
-    /\b(?:sessionStorage|localStorage)\.removeItem\s*\(\s*['"`][^'"`]*(?:state|csrf)[^'"`]*['"`]\s*\)/gi,
-    /\b(?:deleteCookie|clearCookie|removeCookie)\s*\(\s*['"`][^'"`]*(?:state|csrf)[^'"`]*['"`]\s*\)/gi,
-    /\b(?:cookies?|cookieStore)\.(?:delete|remove)\s*\(\s*['"`][^'"`]*(?:state|csrf)[^'"`]*['"`]\s*\)/gi,
-    /\bdocument\.cookie\s*=\s*[^;\n]*(?:state|csrf)[^;\n]*(?:expires\s*=\s*Thu,\s*01 Jan 1970|max-age\s*=\s*0)/gi
-  ];
-  return patterns.reduce((total, pattern) => total + (code.match(pattern)?.length ?? 0), 0);
+  return countStateLikeMemberCalls(code, ["sessionStorage", "localStorage"], ["removeItem"]) + countStateLikeFunctionCalls(code, ["deleteCookie", "clearCookie", "removeCookie"]) + countStateLikeMemberCalls(code, ["cookies", "cookie", "cookieStore"], ["delete", "remove"]) + countDocumentCookieStateClears(code);
+}
+function countDocumentCookieStateClears(code) {
+  const lowerCode = code.toLowerCase();
+  let count = 0;
+  for (let index = lowerCode.indexOf("document.cookie"); index !== -1; index = lowerCode.indexOf("document.cookie", index + "document.cookie".length)) {
+    const assignmentIndex = lowerCode.indexOf("=", index + "document.cookie".length);
+    if (assignmentIndex === -1 || assignmentIndex - index > 48) continue;
+    const endIndex = findCookieAssignmentEnd(lowerCode, assignmentIndex + 1);
+    const assignment = lowerCode.slice(assignmentIndex + 1, endIndex);
+    const mentionsStateToken = assignment.includes("state") || assignment.includes("csrf");
+    const expiresImmediately = assignment.includes("max-age=0") || assignment.includes("max-age = 0") || assignment.includes("thu, 01 jan 1970");
+    if (mentionsStateToken && expiresImmediately) {
+      count += 1;
+    }
+  }
+  return count;
+}
+function findCookieAssignmentEnd(code, startIndex) {
+  const maxIndex = Math.min(code.length, startIndex + 320);
+  for (let index = startIndex; index < maxIndex; index += 1) {
+    const char = code[index];
+    if (char === "\n" || char === "\r") return index;
+  }
+  return maxIndex;
 }
 function countAuthCallbackUrlScrubSignals(code) {
   const patterns = [
@@ -8731,12 +8907,34 @@ function countHardcodedSecretSignals(code) {
   return patterns.reduce((count, pattern) => count + (code.match(pattern)?.length ?? 0), 0);
 }
 function countClientSecretEnvReferenceSignals(code) {
-  const patterns = [
-    /\bimport\.meta\.env\.[A-Z0-9_]*(?:SERVICE_ROLE|SECRET|PRIVATE_KEY)[A-Z0-9_]*\b/g,
-    /\bprocess\.env\.NEXT_PUBLIC_[A-Z0-9_]*(?:SERVICE_ROLE|SECRET|PRIVATE_KEY)[A-Z0-9_]*\b/g
-  ];
-  const useClientCount = /^\s*['"]use client['"]/m.test(code) ? code.match(/\bprocess\.env\.[A-Z0-9_]*(?:SERVICE_ROLE|SECRET|PRIVATE_KEY)[A-Z0-9_]*\b/g)?.length ?? 0 : 0;
-  return patterns.reduce((count, pattern) => count + (code.match(pattern)?.length ?? 0), 0) + useClientCount;
+  const useClientCount = /^\s*['"]use client['"]/m.test(code) ? countSensitiveEnvReferences(code, ["process.env."]) : 0;
+  return countSensitiveEnvReferences(code, ["import.meta.env.", "process.env.NEXT_PUBLIC_"]) + useClientCount;
+}
+function countSensitiveEnvReferences(code, prefixes) {
+  let count = 0;
+  for (const prefix of prefixes) {
+    for (let index = code.indexOf(prefix); index !== -1; index = code.indexOf(prefix, index + prefix.length)) {
+      const envName = readEnvIdentifier(code, index + prefix.length);
+      if (envName && isSensitiveEnvName(envName)) {
+        count += 1;
+      }
+    }
+  }
+  return count;
+}
+function readEnvIdentifier(code, startIndex) {
+  let cursor = startIndex;
+  while (cursor < code.length && isEnvIdentifierChar(code[cursor])) {
+    cursor += 1;
+  }
+  return code.slice(startIndex, cursor);
+}
+function isEnvIdentifierChar(char) {
+  const codePoint = char.charCodeAt(0);
+  return char === "_" || codePoint >= 48 && codePoint <= 57 || codePoint >= 65 && codePoint <= 90;
+}
+function isSensitiveEnvName(envName) {
+  return envName.includes("SERVICE_ROLE") || envName.includes("SECRET") || envName.includes("PRIVATE_KEY");
 }
 function countLocalhostEndpointSignals(code) {
   return code.match(