@decantr/verifier 2.4.0 → 2.5.1

package/dist/index.js

@@ -1,8 +1,8 @@
 // src/index.ts
 import { createHash } from "crypto";
-import { existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, realpathSync, statSync as statSync2 } from "fs";
+import { existsSync as existsSync3, readdirSync as readdirSync3, readFileSync as readFileSync3, realpathSync, statSync as statSync3 } from "fs";
 import { readFile } from "fs/promises";
-import { basename, dirname, extname as extname2, isAbsolute, join as join2, relative, resolve } from "path";
+import { basename, dirname, extname as extname3, isAbsolute as isAbsolute2, join as join3, relative as relative2, resolve } from "path";
 import { evaluateGuard, isV4, validateEssence } from "@decantr/essence-spec";
 import * as ts from "typescript";
 
@@ -754,6 +754,850 @@ function listKnownInteractions() {
   return Object.keys(INTERACTION_SIGNALS).sort();
 }
 
+// src/scan.ts
+import { existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, statSync as statSync2 } from "fs";
+import { extname as extname2, isAbsolute, join as join2, relative } from "path";
+var SCAN_REPORT_SCHEMA_URL = "https://decantr.ai/schemas/scan-report.v1.json";
+var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue", ".svelte"]);
+var STYLE_EXTENSIONS = /* @__PURE__ */ new Set([".css", ".scss", ".sass", ".less"]);
+var PAGE_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".vue", ".svelte", ".html"]);
+var MAX_FILE_READ_BYTES = 512 * 1024;
+var MAX_WALK_FILES = 5e3;
+var MAX_REPORT_ROUTES = 80;
+var SKIP_DIRS = /* @__PURE__ */ new Set([
+  ".git",
+  ".next",
+  ".nuxt",
+  ".svelte-kit",
+  "coverage",
+  "dist",
+  "build",
+  "node_modules",
+  "out",
+  "target",
+  "vendor"
+]);
+var RULE_FILES = [
+  "CLAUDE.md",
+  "AGENTS.md",
+  "GEMINI.md",
+  ".cursorrules",
+  ".cursor/rules",
+  ".claude/rules",
+  ".github/copilot-instructions.md",
+  "copilot-instructions.md",
+  ".windsurfrules"
+];
+var WEB_FRAMEWORKS = /* @__PURE__ */ new Set([
+  "angular",
+  "astro",
+  "html",
+  "nextjs",
+  "nuxt",
+  "react",
+  "solid",
+  "svelte",
+  "vue"
+]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readTextFile(path, maxBytes = MAX_FILE_READ_BYTES) {
+  try {
+    const stat = statSync2(path);
+    if (!stat.isFile() || stat.size > maxBytes) return null;
+    return readFileSync2(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function readPackageJson(projectRoot) {
+  const path = join2(projectRoot, "package.json");
+  if (!existsSync2(path)) return { value: null, present: false, valid: false };
+  const content = readTextFile(path);
+  if (!content) return { value: null, present: true, valid: false };
+  try {
+    const parsed = JSON.parse(content);
+    return { value: isRecord(parsed) ? parsed : null, present: true, valid: isRecord(parsed) };
+  } catch {
+    return { value: null, present: true, valid: false };
+  }
+}
+function dependencyVersion(dependencies, names) {
+  for (const name of names) {
+    const version = dependencies[name];
+    if (version) return version.replace(/^[~^]/, "");
+  }
+  return null;
+}
+function hasAnyFile(projectRoot, paths) {
+  return paths.some((path) => existsSync2(join2(projectRoot, path)));
+}
+function detectPackageManager(projectRoot, pkg) {
+  const declared = pkg?.packageManager?.split("@")[0];
+  if (declared === "npm" || declared === "pnpm" || declared === "yarn" || declared === "bun") {
+    return declared;
+  }
+  if (existsSync2(join2(projectRoot, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync2(join2(projectRoot, "yarn.lock"))) return "yarn";
+  if (existsSync2(join2(projectRoot, "bun.lockb"))) return "bun";
+  if (existsSync2(join2(projectRoot, "package-lock.json"))) return "npm";
+  return "unknown";
+}
+function detectPrimaryLanguage(projectRoot, packageJsonPresent) {
+  if (packageJsonPresent) return "javascript";
+  if (hasAnyFile(projectRoot, ["pyproject.toml", "requirements.txt", "setup.py", "Pipfile"])) return "python";
+  if (hasAnyFile(projectRoot, ["go.mod"])) return "go";
+  if (hasAnyFile(projectRoot, ["Cargo.toml"])) return "rust";
+  if (hasAnyFile(projectRoot, ["index.html", "docs/index.html"])) return "html";
+  return "unknown";
+}
+function detectProject(projectRoot) {
+  const packageRead = readPackageJson(projectRoot);
+  const pkg = packageRead.value;
+  const dependencies = { ...pkg?.dependencies ?? {}, ...pkg?.devDependencies ?? {} };
+  let framework = "unknown";
+  let frameworkVersion = null;
+  if (hasAnyFile(projectRoot, ["next.config.js", "next.config.ts", "next.config.mjs"]) || dependencies.next) {
+    framework = "nextjs";
+    frameworkVersion = dependencyVersion(dependencies, ["next"]);
+  } else if (hasAnyFile(projectRoot, ["nuxt.config.js", "nuxt.config.ts"]) || dependencies.nuxt) {
+    framework = "nuxt";
+    frameworkVersion = dependencyVersion(dependencies, ["nuxt"]);
+  } else if (hasAnyFile(projectRoot, ["astro.config.mjs", "astro.config.ts"]) || dependencies.astro) {
+    framework = "astro";
+    frameworkVersion = dependencyVersion(dependencies, ["astro"]);
+  } else if (hasAnyFile(projectRoot, ["svelte.config.js", "svelte.config.ts"]) || dependencies.svelte || dependencies["@sveltejs/kit"]) {
+    framework = "svelte";
+    frameworkVersion = dependencyVersion(dependencies, ["svelte", "@sveltejs/kit"]);
+  } else if (hasAnyFile(projectRoot, ["angular.json"]) || dependencies["@angular/core"]) {
+    framework = "angular";
+    frameworkVersion = dependencyVersion(dependencies, ["@angular/core"]);
+  } else if (dependencies["solid-js"]) {
+    framework = "solid";
+    frameworkVersion = dependencyVersion(dependencies, ["solid-js"]);
+  } else if (dependencies.vue) {
+    framework = "vue";
+    frameworkVersion = dependencyVersion(dependencies, ["vue"]);
+  } else if (dependencies.react) {
+    framework = "react";
+    frameworkVersion = dependencyVersion(dependencies, ["react"]);
+  } else if (hasAnyFile(projectRoot, ["index.html", "docs/index.html"])) {
+    framework = "html";
+  }
+  return {
+    framework,
+    frameworkVersion,
+    packageManager: detectPackageManager(projectRoot, pkg),
+    primaryLanguage: detectPrimaryLanguage(projectRoot, packageRead.present),
+    hasTypeScript: hasAnyFile(projectRoot, ["tsconfig.json"]),
+    hasTailwind: hasAnyFile(projectRoot, [
+      "tailwind.config.js",
+      "tailwind.config.ts",
+      "tailwind.config.mjs",
+      "tailwind.config.cjs"
+    ]),
+    hasDecantr: existsSync2(join2(projectRoot, "decantr.essence.json")) || existsSync2(join2(projectRoot, ".decantr")) || Boolean(dependencies["@decantr/cli"] || dependencies["@decantr/css"]),
+    packageName: typeof pkg?.name === "string" ? pkg.name : null,
+    packageJsonValid: packageRead.valid,
+    packageJsonPresent: packageRead.present,
+    dependencies
+  };
+}
+function shouldSkipDir(name) {
+  return SKIP_DIRS.has(name) || name.startsWith(".") && name !== ".github";
+}
+function walkFiles(projectRoot, options = {}) {
+  const files = [];
+  function walk(dir) {
+    if (files.length >= MAX_WALK_FILES) return;
+    let entries;
+    try {
+      entries = readdirSync2(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (files.length >= MAX_WALK_FILES) return;
+      const fullPath = join2(dir, entry);
+      let stat;
+      try {
+        stat = statSync2(fullPath);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        if (shouldSkipDir(entry) && !options.includeHidden) continue;
+        walk(fullPath);
+        continue;
+      }
+      if (!stat.isFile()) continue;
+      const rel = relative(projectRoot, fullPath).replace(/\\/g, "/");
+      const ext = extname2(entry).toLowerCase();
+      if (!options.extensions || options.extensions.has(ext)) {
+        files.push(rel);
+      }
+    }
+  }
+  walk(projectRoot);
+  return files;
+}
+function segmentToRoute(segment) {
+  if (segment.startsWith("(") && segment.endsWith(")")) return null;
+  if (segment.startsWith("[") && segment.endsWith("]")) {
+    const param = segment.slice(1, -1);
+    if (param.startsWith("...")) return `:${param.slice(3)}*`;
+    if (param.startsWith("[...") && param.endsWith("]")) return `:${param.slice(4, -1)}*`;
+    return `:${param}`;
+  }
+  return segment;
+}
+function walkNextAppRoutes(dir, projectRoot, segments) {
+  let entries;
+  try {
+    entries = readdirSync2(dir);
+  } catch {
+    return [];
+  }
+  const routes = [];
+  const pageFile = entries.find((entry) => /^page\.(tsx|ts|jsx|js)$/.test(entry));
+  const hasLayout = entries.some((entry) => /^layout\.(tsx|ts|jsx|js)$/.test(entry));
+  if (pageFile) {
+    routes.push({
+      path: `/${segments.filter(Boolean).join("/")}` || "/",
+      file: relative(projectRoot, join2(dir, pageFile)).replace(/\\/g, "/"),
+      hasLayout
+    });
+  }
+  for (const entry of entries) {
+    if (shouldSkipDir(entry)) continue;
+    const fullPath = join2(dir, entry);
+    try {
+      if (!statSync2(fullPath).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    const routeSegment = segmentToRoute(entry);
+    routes.push(...walkNextAppRoutes(fullPath, projectRoot, routeSegment === null ? segments : [...segments, routeSegment]));
+  }
+  return routes;
+}
+function fileRouteFromPath(file, baseDir) {
+  let withoutExt = file.slice(0, -extname2(file).length);
+  if (withoutExt.endsWith("/index")) withoutExt = withoutExt.slice(0, -"/index".length);
+  withoutExt = withoutExt.replace(new RegExp(`^${baseDir.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`), "");
+  const parts = withoutExt.split("/").filter(Boolean).map((part) => segmentToRoute(part)).filter(Boolean);
+  return `/${parts.join("/")}` || "/";
+}
+function scanFileRoutes(projectRoot, baseDir, extensions = PAGE_EXTENSIONS) {
+  const fullBase = join2(projectRoot, baseDir);
+  if (!existsSync2(fullBase)) return [];
+  return walkFiles(fullBase, { extensions }).map((file) => {
+    const rel = relative(projectRoot, join2(fullBase, file)).replace(/\\/g, "/");
+    return { path: fileRouteFromPath(rel, baseDir), file: rel, hasLayout: false };
+  });
+}
+function scanReactRouter(projectRoot) {
+  const files = walkFiles(projectRoot, { extensions: SOURCE_EXTENSIONS });
+  const routes = /* @__PURE__ */ new Map();
+  let hashRouting = false;
+  for (const file of files) {
+    const content = readTextFile(join2(projectRoot, file));
+    if (!content) continue;
+    if (content.includes("HashRouter") || content.includes("createHashRouter")) hashRouting = true;
+    const jsxRouteRegex = /<Route\b[^>]*\bpath\s*=\s*["']([^"']+)["']/g;
+    let match;
+    while ((match = jsxRouteRegex.exec(content)) !== null) {
+      const route = match[1] || "/";
+      routes.set(route, { path: route, file, hasLayout: false });
+    }
+    const objectRouteRegex = /\bpath\s*:\s*["']([^"']+)["']/g;
+    while ((match = objectRouteRegex.exec(content)) !== null) {
+      const route = match[1] || "/";
+      if (route.startsWith("/")) routes.set(route, { path: route, file, hasLayout: false });
+    }
+  }
+  return { routes: [...routes.values()], hashRouting };
+}
+function scanRoutes(projectRoot, detection) {
+  const appRoutes = ["src/app", "app"].flatMap(
+    (dir) => existsSync2(join2(projectRoot, dir)) ? walkNextAppRoutes(join2(projectRoot, dir), projectRoot, []) : []
+  );
+  const pagesRoutes = ["src/pages", "pages"].flatMap((dir) => scanFileRoutes(projectRoot, dir));
+  if (detection.framework === "nextjs") {
+    if (appRoutes.length > 0 && pagesRoutes.length > 0) return { strategy: "mixed-next-router", routes: [...appRoutes, ...pagesRoutes] };
+    if (appRoutes.length > 0) return { strategy: "app-router", routes: appRoutes };
+    if (pagesRoutes.length > 0) return { strategy: "pages-router", routes: pagesRoutes };
+  }
+  if (detection.framework === "svelte") {
+    const routes = scanFileRoutes(projectRoot, "src/routes", /* @__PURE__ */ new Set([".svelte", ".ts", ".js"]));
+    if (routes.length > 0) return { strategy: "sveltekit-router", routes };
+  }
+  if (detection.framework === "nuxt") {
+    const routes = ["pages", "app/pages"].flatMap((dir) => scanFileRoutes(projectRoot, dir, /* @__PURE__ */ new Set([".vue"])));
+    if (routes.length > 0) return { strategy: "nuxt-router", routes };
+  }
+  if (detection.framework === "vue") {
+    const router = scanReactRouter(projectRoot);
+    if (router.routes.length > 0) return { strategy: "vue-router", routes: router.routes };
+  }
+  const reactRouter = scanReactRouter(projectRoot);
+  if (reactRouter.routes.length > 0) return { strategy: "react-router", routes: reactRouter.routes };
+  if (pagesRoutes.length > 0) return { strategy: "pages-router", routes: pagesRoutes };
+  if (existsSync2(join2(projectRoot, "index.html"))) {
+    return { strategy: "static-html", routes: [{ path: "/", file: "index.html", hasLayout: false }] };
+  }
+  if (existsSync2(join2(projectRoot, "docs", "index.html"))) {
+    return { strategy: "static-html", routes: [{ path: "/", file: "docs/index.html", hasLayout: false }] };
+  }
+  return { strategy: "none", routes: [] };
+}
+function countComponents(projectRoot, routes) {
+  const sourceFiles = walkFiles(projectRoot, { extensions: SOURCE_EXTENSIONS });
+  const componentFiles = sourceFiles.filter((file) => {
+    const base = file.split("/").pop() ?? file;
+    return /^[A-Z][\w-]*\.(tsx|ts|jsx|js|vue|svelte)$/.test(base);
+  });
+  const directories = [...new Set(componentFiles.map((file) => file.split("/").slice(0, -1).join("/")).filter(Boolean))].slice(0, 16);
+  return {
+    pageCount: routes.routes.length,
+    componentCount: componentFiles.length,
+    directories
+  };
+}
+function extractCssEvidence(content) {
+  const variableMatches = [...content.matchAll(/--[\w-]+\s*:/g)];
+  const colorMatches = [...content.matchAll(/#[0-9a-fA-F]{3,8}\b|rgb[a]?\(|hsl[a]?\(/g)];
+  const themeSignals = /* @__PURE__ */ new Set();
+  if (/\bdark\b|color-scheme:\s*dark|\[data-theme=['"]dark['"]|\.dark\b/.test(content)) themeSignals.add("dark mode");
+  if (/\[data-theme=|data-theme|theme-\w+/.test(content)) themeSignals.add("theme selector");
+  if (/prefers-color-scheme/.test(content)) themeSignals.add("system color preference");
+  return {
+    variables: variableMatches.length,
+    colors: colorMatches.length,
+    dark: themeSignals.has("dark mode") || themeSignals.has("system color preference"),
+    themeSignals: [...themeSignals]
+  };
+}
+function scanStyling(projectRoot, detection) {
+  const deps = detection.dependencies;
+  const cssFiles = walkFiles(projectRoot, { extensions: STYLE_EXTENSIONS });
+  const themeSignals = /* @__PURE__ */ new Set();
+  let cssVariableCount = 0;
+  let colorTokenCount = 0;
+  let darkMode = false;
+  let configFile = null;
+  let approach = "unknown";
+  const tailwindConfig = ["tailwind.config.js", "tailwind.config.ts", "tailwind.config.mjs", "tailwind.config.cjs"].find(
+    (file) => existsSync2(join2(projectRoot, file))
+  );
+  if (tailwindConfig || deps.tailwindcss) {
+    approach = "tailwind";
+    configFile = tailwindConfig ?? "package.json";
+  } else if (deps["@decantr/css"] || existsSync2(join2(projectRoot, "src/styles/tokens.css")) && existsSync2(join2(projectRoot, "src/styles/treatments.css"))) {
+    approach = "decantr-css";
+    configFile = deps["@decantr/css"] ? "package.json" : "src/styles/tokens.css";
+  } else if (deps.bootstrap) {
+    approach = "bootstrap";
+    configFile = "package.json";
+  } else if (deps["@mui/material"]) {
+    approach = "mui";
+    configFile = "package.json";
+  } else if (deps["@chakra-ui/react"]) {
+    approach = "chakra";
+    configFile = "package.json";
+  } else if (cssFiles.some((file) => file.endsWith(".module.css"))) {
+    approach = "css-modules";
+  } else if (cssFiles.length > 0) {
+    approach = "css";
+  }
+  for (const file of cssFiles.slice(0, 80)) {
+    const content = readTextFile(join2(projectRoot, file), 256 * 1024);
+    if (!content) continue;
+    const evidence = extractCssEvidence(content);
+    cssVariableCount += evidence.variables;
+    colorTokenCount += evidence.colors;
+    darkMode ||= evidence.dark;
+    for (const signal of evidence.themeSignals) themeSignals.add(signal);
+  }
+  return {
+    approach,
+    configFile,
+    cssVariableCount,
+    colorTokenCount,
+    darkMode,
+    themeSignals: [...themeSignals]
+  };
+}
+function findAssistantRules(projectRoot) {
+  return RULE_FILES.filter((file) => existsSync2(join2(projectRoot, file)));
+}
+function scanStaticHosting(projectRoot, detection) {
+  const packageRead = readPackageJson(projectRoot);
+  const pkg = packageRead.value;
+  const evidence = [];
+  const homepageUrl = typeof pkg?.homepage === "string" ? pkg.homepage : null;
+  let basePath = null;
+  let hashRouting = false;
+  if (homepageUrl?.includes("github.io")) {
+    evidence.push("package.json homepage points at GitHub Pages");
+    try {
+      const url = new URL(homepageUrl);
+      basePath = url.pathname && url.pathname !== "/" ? url.pathname : null;
+    } catch {
+    }
+  }
+  if (detection.dependencies["gh-pages"] || pkg?.scripts?.deploy?.includes("gh-pages")) {
+    evidence.push("package scripts or dependencies reference gh-pages");
+  }
+  if (existsSync2(join2(projectRoot, "docs", "index.html"))) evidence.push("docs/index.html can serve GitHub Pages");
+  if (existsSync2(join2(projectRoot, "404.html")) || existsSync2(join2(projectRoot, "docs", "404.html"))) {
+    evidence.push("404.html fallback is present");
+  }
+  const workflowDir = join2(projectRoot, ".github", "workflows");
+  if (existsSync2(workflowDir)) {
+    for (const file of walkFiles(workflowDir, { extensions: /* @__PURE__ */ new Set([".yml", ".yaml"]) }).slice(0, 20)) {
+      const content = readTextFile(join2(workflowDir, file));
+      if (content && /pages|gh-pages|upload-pages-artifact|deploy-pages/i.test(content)) {
+        evidence.push(`GitHub Pages workflow hint: .github/workflows/${file}`);
+        break;
+      }
+    }
+  }
+  const sourceFiles = walkFiles(projectRoot, { extensions: SOURCE_EXTENSIONS });
+  for (const file of sourceFiles.slice(0, 200)) {
+    const content = readTextFile(join2(projectRoot, file), 128 * 1024);
+    if (!content) continue;
+    if (content.includes("HashRouter") || content.includes("createHashRouter")) {
+      hashRouting = true;
+      evidence.push(`hash routing detected in ${file}`);
+      break;
+    }
+  }
+  for (const config of ["vite.config.ts", "vite.config.js", "vite.config.mjs"]) {
+    const content = readTextFile(join2(projectRoot, config), 128 * 1024);
+    const baseMatch = content?.match(/\bbase\s*:\s*['"]([^'"]+)['"]/);
+    if (baseMatch?.[1]) {
+      basePath = baseMatch[1];
+      evidence.push(`Vite base path configured in ${config}`);
+      break;
+    }
+  }
+  return {
+    githubPagesLikely: evidence.some((item) => item.toLowerCase().includes("github") || item.toLowerCase().includes("pages")),
+    evidence: [...new Set(evidence)].slice(0, 12),
+    homepageUrl,
+    basePath,
+    hashRouting
+  };
+}
+function buildApplicability(detection, routes, components) {
+  if (!WEB_FRAMEWORKS.has(detection.framework)) {
+    const label = detection.primaryLanguage === "python" ? "Not a Brownfield UI target" : "No web UI target detected";
+    return {
+      status: "not_applicable",
+      label,
+      reasons: [
+        detection.primaryLanguage === "python" ? "This looks like a Python/backend repository rather than a frontend app." : "Decantr did not find a supported frontend framework or static HTML entrypoint."
+      ]
+    };
+  }
+  if (routes.routes.length > 0 || components.componentCount > 0) {
+    return {
+      status: "strong_fit",
+      label: "Good Brownfield scan target",
+      reasons: ["A supported web UI framework or static site entrypoint was detected.", "Routes or UI component files are present."]
+    };
+  }
+  return {
+    status: "partial_fit",
+    label: "Partial Brownfield signal",
+    reasons: ["A web framework was detected, but route/component evidence is thin."]
+  };
+}
+function buildConfidence(applicability, detection, routes, styling) {
+  let score = 20;
+  const reasons = [];
+  if (detection.packageJsonPresent && detection.packageJsonValid) {
+    score += 15;
+    reasons.push("package.json was readable");
+  }
+  if (WEB_FRAMEWORKS.has(detection.framework)) {
+    score += 25;
+    reasons.push(`${detection.framework} framework signal found`);
+  }
+  if (routes.routes.length > 0) {
+    score += 20;
+    reasons.push(`${routes.routes.length} route signal(s) found`);
+  }
+  if (styling.approach !== "unknown") {
+    score += 10;
+    reasons.push(`${styling.approach} styling signal found`);
+  }
+  if (applicability.status === "not_applicable") score = Math.min(score, 35);
+  const clamped = Math.max(5, Math.min(98, score));
+  return {
+    score: clamped,
+    level: clamped >= 75 ? "high" : clamped >= 45 ? "medium" : "low",
+    reasons: reasons.length > 0 ? reasons : ["Only weak project signals were found."]
+  };
+}
+function buildFindings(input) {
+  const findings = [];
+  const { detection, routes, styling, hosting, assistantRules, applicability, pagesProbe } = input;
+  if (!detection.packageJsonPresent && detection.primaryLanguage !== "html") {
+    findings.push({
+      id: "package-manifest-missing",
+      severity: "warn",
+      title: "No JavaScript package manifest",
+      message: "Decantr could not find package.json, so framework and dependency confidence is limited.",
+      evidence: ["package.json missing"]
+    });
+  } else if (detection.packageJsonPresent && !detection.packageJsonValid) {
+    findings.push({
+      id: "package-manifest-invalid",
+      severity: "warn",
+      title: "package.json could not be parsed",
+      message: "The scan continued with file-system evidence, but dependency confidence is limited.",
+      evidence: ["package.json parse failed"]
+    });
+  }
+  if (applicability.status === "not_applicable") {
+    findings.push({
+      id: "not-brownfield-ui-target",
+      severity: "info",
+      title: "Not a Brownfield UI target",
+      message: "This repository does not look like a supported frontend application for Decantr adoption.",
+      evidence: [`primary language: ${detection.primaryLanguage}`, `framework: ${detection.framework}`],
+      recommendation: "Use Decantr scan on a frontend app or GitHub Pages site."
+    });
+    return findings;
+  }
+  if (routes.routes.length === 0) {
+    findings.push({
+      id: "route-map-thin",
+      severity: "warn",
+      title: "Route map is thin",
+      message: "No route declarations were detected, so a future Decantr contract would need manual route confirmation.",
+      evidence: [`route strategy: ${routes.strategy}`],
+      recommendation: "Run `decantr analyze` locally when you are ready for a proposal-backed attach."
+    });
+  } else {
+    findings.push({
+      id: "route-map-detected",
+      severity: "success",
+      title: "Route map detected",
+      message: `Decantr found ${routes.routes.length} route signal(s) that can seed a Brownfield contract.`,
+      evidence: routes.routes.slice(0, 5).map((route) => `${route.path} -> ${route.file}`)
+    });
+  }
+  if (styling.approach === "unknown") {
+    findings.push({
+      id: "style-authority-unclear",
+      severity: "warn",
+      title: "Style authority is unclear",
+      message: "The scan did not find Tailwind, Decantr CSS, a common component library, or clear CSS files.",
+      evidence: ["styling approach: unknown"]
+    });
+  } else {
+    findings.push({
+      id: "style-authority-detected",
+      severity: "success",
+      title: "Style authority detected",
+      message: `The project appears to use ${styling.approach}. Decantr should preserve that authority during Brownfield adoption.`,
+      evidence: [styling.configFile ? `${styling.approach}: ${styling.configFile}` : `styling approach: ${styling.approach}`]
+    });
+  }
+  if (hosting.githubPagesLikely) {
+    findings.push({
+      id: "github-pages-signal",
+      severity: "info",
+      title: "GitHub Pages signal",
+      message: "The repository has static-hosting evidence. The report separates repo evidence from published-site evidence.",
+      evidence: hosting.evidence.slice(0, 5)
+    });
+  }
+  if (hosting.githubPagesLikely && !hosting.hashRouting && detection.framework === "react") {
+    findings.push({
+      id: "github-pages-routing-risk",
+      severity: "warn",
+      title: "Static routing risk",
+      message: "React apps on GitHub Pages usually need hash routing or a 404 fallback for direct routes.",
+      evidence: ["HashRouter not detected"],
+      recommendation: "Confirm whether the published site uses hash routing or a Pages 404 fallback."
+    });
+  }
+  if (assistantRules.length === 0) {
+    findings.push({
+      id: "assistant-rules-missing",
+      severity: "info",
+      title: "No assistant rules detected",
+      message: "No common AI-assistant rule file was found. Decantr can add scoped task context after adoption.",
+      evidence: ["No CLAUDE.md, AGENTS.md, .cursorrules, or Copilot instructions detected"]
+    });
+  }
+  if (pagesProbe?.checked && !pagesProbe.reachable) {
+    findings.push({
+      id: "published-site-unreachable",
+      severity: "warn",
+      title: "Published site was not reachable",
+      message: "Decantr could inspect the repository, but the inferred published site did not return a usable response.",
+      evidence: [pagesProbe.error ?? `status: ${pagesProbe.status ?? "unknown"}`]
+    });
+  }
+  return findings;
+}
+function buildCommands(applicability) {
+  const commands = ["npx @decantr/cli scan"];
+  if (applicability.status === "strong_fit" || applicability.status === "partial_fit") {
+    commands.push("npx @decantr/cli adopt --yes");
+    commands.push("npx @decantr/cli doctor");
+  }
+  return commands;
+}
+async function scanProject(projectRoot, options = {}) {
+  const detection = detectProject(projectRoot);
+  const routes = scanRoutes(projectRoot, detection);
+  routes.routes = routes.routes.slice(0, MAX_REPORT_ROUTES);
+  const components = countComponents(projectRoot, routes);
+  const styling = scanStyling(projectRoot, detection);
+  const assistantRules = findAssistantRules(projectRoot);
+  const staticHosting = scanStaticHosting(projectRoot, detection);
+  const pagesProbe = options.pagesProbe ?? null;
+  const applicability = buildApplicability(detection, routes, components);
+  const confidence = buildConfidence(applicability, detection, routes, styling);
+  const rawInput = options.input ?? { kind: "local", value: "." };
+  const input = rawInput.kind === "local" && isAbsolute(rawInput.value) ? { ...rawInput, value: "." } : rawInput;
+  return {
+    $schema: SCAN_REPORT_SCHEMA_URL,
+    schemaVersion: "scan-report.v1",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    input,
+    source: {
+      repository: options.repository ?? null,
+      publishedSiteUrl: options.publishedSiteUrl ?? staticHosting.homepageUrl ?? null
+    },
+    confidence,
+    applicability,
+    project: {
+      framework: detection.framework,
+      frameworkVersion: detection.frameworkVersion,
+      packageManager: detection.packageManager,
+      primaryLanguage: detection.primaryLanguage,
+      hasTypeScript: detection.hasTypeScript,
+      hasTailwind: detection.hasTailwind,
+      hasDecantr: detection.hasDecantr,
+      packageName: detection.packageName
+    },
+    routes: {
+      strategy: routes.strategy,
+      count: routes.routes.length,
+      items: routes.routes
+    },
+    components,
+    styling,
+    staticHosting,
+    assistant: {
+      ruleFiles: assistantRules
+    },
+    pagesProbe,
+    findings: buildFindings({ detection, routes, styling, hosting: staticHosting, assistantRules, applicability, pagesProbe }),
+    recommendedCommands: buildCommands(applicability),
+    privacy: {
+      sourceUploaded: input.kind !== "local",
+      persistedByDecantr: false,
+      notes: [
+        "V1 scans are read-only and do not install dependencies, build projects, execute scripts, or open pull requests.",
+        "Hosted scans use temporary public-repo checkouts and return an ephemeral report."
+      ]
+    }
+  };
+}
+function createUnavailableScanReport(input) {
+  return {
+    $schema: SCAN_REPORT_SCHEMA_URL,
+    schemaVersion: "scan-report.v1",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    input: input.scanInput,
+    source: {
+      repository: input.repository ?? null,
+      publishedSiteUrl: input.publishedSiteUrl ?? null
+    },
+    confidence: {
+      level: "low",
+      score: 5,
+      reasons: ["Repository source could not be inspected."]
+    },
+    applicability: {
+      status: "unknown",
+      label: "Scan unavailable",
+      reasons: [input.message]
+    },
+    project: {
+      framework: "unknown",
+      frameworkVersion: null,
+      packageManager: "unknown",
+      primaryLanguage: "unknown",
+      hasTypeScript: false,
+      hasTailwind: false,
+      hasDecantr: false,
+      packageName: null
+    },
+    routes: { strategy: "none", count: 0, items: [] },
+    components: { pageCount: 0, componentCount: 0, directories: [] },
+    styling: {
+      approach: "unknown",
+      configFile: null,
+      cssVariableCount: 0,
+      colorTokenCount: 0,
+      darkMode: false,
+      themeSignals: []
+    },
+    staticHosting: {
+      githubPagesLikely: false,
+      evidence: [],
+      homepageUrl: null,
+      basePath: null,
+      hashRouting: false
+    },
+    assistant: { ruleFiles: [] },
+    pagesProbe: input.pagesProbe ?? null,
+    findings: [
+      {
+        id: "source-unavailable",
+        severity: "error",
+        title: input.title,
+        message: input.message,
+        evidence: input.evidence ?? []
+      }
+    ],
+    recommendedCommands: ["npx @decantr/cli scan"],
+    privacy: {
+      sourceUploaded: input.scanInput.kind !== "local",
+      persistedByDecantr: false,
+      notes: [
+        "Decantr did not persist this report.",
+        "No dependencies were installed, no scripts were executed, and no pull requests were opened."
+      ]
+    }
+  };
+}
+function decodeHtml(value) {
+  return value.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").trim();
+}
+function extractHtmlAttribute(tag, attr) {
+  const match = tag.match(new RegExp(`${attr}\\s*=\\s*["']([^"']+)["']`, "i"));
+  return match?.[1] ? decodeHtml(match[1]) : null;
+}
+async function probePublishedSite(url, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 6e3);
+  try {
+    const response = await fetchImpl(url, {
+      method: "GET",
+      redirect: "follow",
+      signal: controller.signal,
+      headers: {
+        Accept: "text/html,application/xhtml+xml",
+        "User-Agent": "Decantr-Scan/1.0 (+https://decantr.ai/scan)"
+      }
+    });
+    const text = (await response.text()).slice(0, MAX_FILE_READ_BYTES);
+    const titleMatch = text.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    const descriptionTag = text.match(/<meta\b[^>]*(?:name|property)=["']description["'][^>]*>/i)?.[0] ?? null;
+    const canonicalTag = text.match(/<link\b[^>]*rel=["']canonical["'][^>]*>/i)?.[0] ?? null;
+    const assetSamples = [...text.matchAll(/\b(?:src|href)=["']([^"']+)["']/gi)].map((match) => match[1]).filter((value) => Boolean(value)).slice(0, 40);
+    const routingHints = [];
+    if (text.includes("/#/") || text.includes("#/")) routingHints.push("hash route URLs present");
+    if (text.includes("data-reactroot") || text.includes('id="root"') || text.includes("id='root'")) {
+      routingHints.push("client app mount detected");
+    }
+    return {
+      url,
+      finalUrl: response.url || url,
+      checked: true,
+      reachable: response.ok,
+      status: response.status,
+      title: titleMatch?.[1] ? decodeHtml(titleMatch[1].replace(/\s+/g, " ")) : null,
+      description: descriptionTag ? extractHtmlAttribute(descriptionTag, "content") : null,
+      canonicalUrl: canonicalTag ? extractHtmlAttribute(canonicalTag, "href") : null,
+      assetHints: {
+        rootRelative: assetSamples.filter((item) => item.startsWith("/") && !item.startsWith("//")).length,
+        relative: assetSamples.filter((item) => !item.startsWith("/") && !/^https?:\/\//.test(item)).length,
+        absolute: assetSamples.filter((item) => /^https?:\/\//.test(item) || item.startsWith("//")).length,
+        samples: assetSamples.slice(0, 8)
+      },
+      routingHints,
+      error: null
+    };
+  } catch (error) {
+    return {
+      url,
+      finalUrl: null,
+      checked: true,
+      reachable: false,
+      status: null,
+      title: null,
+      description: null,
+      canonicalUrl: null,
+      assetHints: { rootRelative: 0, relative: 0, absolute: 0, samples: [] },
+      routingHints: [],
+      error: error instanceof Error ? error.message : "Published site probe failed."
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function resolveGitHubScanInput(input) {
+  let url;
+  try {
+    url = new URL(input.trim());
+  } catch {
+    throw new Error("Enter a valid GitHub repository URL or GitHub Pages URL.");
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error("Scan URLs must use http or https.");
+  }
+  const host = url.hostname.toLowerCase();
+  if (host === "github.com" || host === "www.github.com") {
+    const [owner, repoSegment] = url.pathname.split("/").filter(Boolean);
+    if (!owner || !repoSegment) {
+      throw new Error("GitHub repository URLs must include owner and repository.");
+    }
+    const repo = repoSegment.replace(/\.git$/, "");
+    return {
+      inputKind: "github-repo",
+      normalizedInput: `https://github.com/${owner}/${repo}`,
+      repository: {
+        owner,
+        repo,
+        url: `https://github.com/${owner}/${repo}`
+      },
+      publishedSiteUrl: `https://${owner}.github.io/${repo}/`,
+      warnings: url.pathname.split("/").filter(Boolean).length > 2 ? ["Extra GitHub URL path segments were ignored."] : []
+    };
+  }
+  if (host.endsWith(".github.io")) {
+    const owner = host.slice(0, -".github.io".length);
+    const segments = url.pathname.split("/").filter(Boolean);
+    const repo = segments[0] ?? `${owner}.github.io`;
+    const publishedSiteUrl = segments[0] ? `https://${owner}.github.io/${repo}/` : `https://${owner}.github.io/`;
+    return {
+      inputKind: "github-pages",
+      normalizedInput: publishedSiteUrl,
+      repository: {
+        owner,
+        repo,
+        url: `https://github.com/${owner}/${repo}`
+      },
+      publishedSiteUrl,
+      warnings: segments.length > 1 ? ["Only the first GitHub Pages path segment was used to infer the repository."] : []
+    };
+  }
+  throw new Error("V1 hosted scans support GitHub repositories and GitHub Pages URLs.");
+}
+
 // src/index.ts
 var VERIFICATION_SCHEMA_URLS = {
   common: "https://decantr.ai/schemas/verification-report.common.v1.json",
@@ -761,6 +1605,7 @@ var VERIFICATION_SCHEMA_URLS = {
   projectHealth: "https://decantr.ai/schemas/project-health-report.v1.json",
   decantrCi: "https://decantr.ai/schemas/decantr-ci-report.v1.json",
   evidenceBundle: "https://decantr.ai/schemas/evidence-bundle.v1.json",
+  scanReport: "https://decantr.ai/schemas/scan-report.v1.json",
   workspaceHealth: "https://decantr.ai/schemas/workspace-health-report.v1.json",
   fileCritique: "https://decantr.ai/schemas/file-critique-report.v1.json",
   showcaseShortlist: "https://decantr.ai/schemas/showcase-shortlist-report.v1.json"
@@ -770,16 +1615,16 @@ function hashString(value) {
   return createHash("sha256").update(value).digest("hex").slice(0, 16);
 }
 function hashFile(path) {
-  if (!existsSync2(path)) return null;
+  if (!existsSync3(path)) return null;
   try {
-    return createHash("sha256").update(readFileSync2(path)).digest("hex");
+    return createHash("sha256").update(readFileSync3(path)).digest("hex");
   } catch {
     return null;
   }
 }
 function provenanceEntry(projectRoot, relativePath) {
-  const path = join2(projectRoot, relativePath);
-  if (!existsSync2(path)) {
+  const path = join3(projectRoot, relativePath);
+  if (!existsSync3(path)) {
     return {
       path: relativePath,
       present: false,
@@ -789,7 +1634,7 @@ function provenanceEntry(projectRoot, relativePath) {
   }
   let generatedAt = null;
   try {
-    generatedAt = statSync2(path).mtime.toISOString();
+    generatedAt = statSync3(path).mtime.toISOString();
   } catch {
     generatedAt = null;
   }
@@ -801,7 +1646,7 @@ function provenanceEntry(projectRoot, relativePath) {
   };
 }
 function provenanceForPath(projectRoot, path) {
-  const rel = isAbsolute(path) ? relative(projectRoot, path).replace(/\\/g, "/") : path;
+  const rel = isAbsolute2(path) ? relative2(projectRoot, path).replace(/\\/g, "/") : path;
   return provenanceEntry(projectRoot, rel && !rel.startsWith("..") ? rel : basename(path));
 }
 function redactEvidenceText(projectRoot, value) {
@@ -825,7 +1670,7 @@ function createContractAssertions(projectRoot, audit) {
   const assertions = [];
   const essence = audit?.essence;
   const v4 = essence && isV4(essence) ? essence : null;
-  const contextDir = join2(projectRoot, ".decantr", "context");
+  const contextDir = join3(projectRoot, ".decantr", "context");
   const packManifest = audit?.packManifest ?? null;
   assertions.push(
     assertion({
@@ -835,7 +1680,7 @@ function createContractAssertions(projectRoot, audit) {
       rule: "essence-present",
       status: essence ? "passed" : "failed",
       message: essence ? "Decantr Essence contract is present." : "No Decantr Essence contract was found.",
-      evidence: [redactEvidenceText(projectRoot, join2(projectRoot, "decantr.essence.json"))],
+      evidence: [redactEvidenceText(projectRoot, join3(projectRoot, "decantr.essence.json"))],
       suggestedFix: essence ? void 0 : "Run `decantr init` or restore decantr.essence.json."
     })
   );
@@ -907,7 +1752,7 @@ function createContractAssertions(projectRoot, audit) {
       rule: "pack-manifest-present",
       status: packManifest ? "passed" : "failed",
       message: packManifest ? "Compiled execution pack manifest is present." : "Compiled execution pack manifest is missing.",
-      evidence: [redactEvidenceText(projectRoot, join2(contextDir, "pack-manifest.json"))],
+      evidence: [redactEvidenceText(projectRoot, join3(contextDir, "pack-manifest.json"))],
       suggestedFix: packManifest ? void 0 : "Run `decantr registry compile-packs decantr.essence.json --write-context` to hydrate the full context pack bundle."
     })
   );
@@ -919,21 +1764,21 @@ function createContractAssertions(projectRoot, audit) {
       rule: "review-pack-present",
       status: audit?.reviewPack ? "passed" : "failed",
       message: audit?.reviewPack ? "Compiled review pack is present." : "Compiled review pack is missing.",
-      evidence: [redactEvidenceText(projectRoot, join2(contextDir, "review-pack.json"))],
+      evidence: [redactEvidenceText(projectRoot, join3(contextDir, "review-pack.json"))],
       suggestedFix: audit?.reviewPack ? void 0 : "Run `decantr registry compile-packs decantr.essence.json --write-context` so critique has the compiled review contract."
     })
   );
-  const tokensPath = join2(projectRoot, "src", "styles", "tokens.css");
+  const tokensPath = join3(projectRoot, "src", "styles", "tokens.css");
   assertions.push(
     assertion({
       id: "contract.design-token.tokens-file",
       category: "design-token",
-      severity: existsSync2(tokensPath) ? "info" : "warn",
+      severity: existsSync3(tokensPath) ? "info" : "warn",
       rule: "tokens-file-present",
-      status: existsSync2(tokensPath) ? "passed" : "failed",
-      message: existsSync2(tokensPath) ? "Decantr token CSS file is present." : "Decantr token CSS file was not found.",
+      status: existsSync3(tokensPath) ? "passed" : "failed",
+      message: existsSync3(tokensPath) ? "Decantr token CSS file is present." : "Decantr token CSS file was not found.",
       evidence: [redactEvidenceText(projectRoot, tokensPath)],
-      suggestedFix: existsSync2(tokensPath) ? void 0 : "Run `decantr refresh` or map Decantr tokens into the existing styling system."
+      suggestedFix: existsSync3(tokensPath) ? void 0 : "Run `decantr refresh` or map Decantr tokens into the existing styling system."
     })
   );
   return assertions;
@@ -1038,21 +1883,21 @@ function scoreRatio(numerator, denominator) {
   return Math.min(5, Math.max(1, Math.round(numerator / denominator * 5)));
 }
 function readJsonIfExists(path) {
-  if (!existsSync2(path)) return null;
+  if (!existsSync3(path)) return null;
   try {
-    return JSON.parse(readFileSync2(path, "utf-8"));
+    return JSON.parse(readFileSync3(path, "utf-8"));
   } catch {
     return null;
   }
 }
 function loadReviewPack(projectRoot) {
   return readJsonIfExists(
-    join2(projectRoot, ".decantr", "context", "review-pack.json")
+    join3(projectRoot, ".decantr", "context", "review-pack.json")
   );
 }
 function loadPackManifest(projectRoot) {
   return readJsonIfExists(
-    join2(projectRoot, ".decantr", "context", "pack-manifest.json")
+    join3(projectRoot, ".decantr", "context", "pack-manifest.json")
   );
 }
 function collectPackManifestReferences(packManifest) {
@@ -1101,14 +1946,14 @@ function collectPackManifestReferences(packManifest) {
 }
 function collectMissingPackManifestFiles(projectRoot, packManifest = loadPackManifest(projectRoot)) {
   if (!packManifest) return [];
-  const contextDir = join2(projectRoot, ".decantr", "context");
+  const contextDir = join3(projectRoot, ".decantr", "context");
   const missing = [];
   for (const reference of collectPackManifestReferences(packManifest)) {
     for (const field of ["markdown", "json"]) {
       const fileName = reference[field];
       if (!fileName) continue;
-      const absolutePath = join2(contextDir, fileName);
-      if (existsSync2(absolutePath)) continue;
+      const absolutePath = join3(contextDir, fileName);
+      if (existsSync3(absolutePath)) continue;
       missing.push({
         entryId: reference.entryId,
         kind: reference.kind,
@@ -1122,13 +1967,13 @@ function collectMissingPackManifestFiles(projectRoot, packManifest = loadPackMan
 }
 function readTextIfExists(path) {
   try {
-    return existsSync2(path) ? readFileSync2(path, "utf-8") : "";
+    return existsSync3(path) ? readFileSync3(path, "utf-8") : "";
   } catch {
     return "";
   }
 }
 function readProjectAdoptionMode(projectRoot) {
-  const projectJson = readJsonIfExists(join2(projectRoot, ".decantr", "project.json"));
+  const projectJson = readJsonIfExists(join3(projectRoot, ".decantr", "project.json"));
   const adoptionMode = projectJson?.initialized?.adoptionMode;
   return typeof adoptionMode === "string" ? adoptionMode : null;
 }
@@ -1214,7 +2059,7 @@ function collectProjectSourceFiles(projectRoot) {
     "hooks",
     "providers",
     "server"
-  ].map((dir) => join2(projectRoot, dir)).filter((dir) => existsSync2(dir));
+  ].map((dir) => join3(projectRoot, dir)).filter((dir) => existsSync3(dir));
   const rootFileCandidates = [
     "middleware.ts",
     "middleware.tsx",
@@ -1228,7 +2073,7 @@ function collectProjectSourceFiles(projectRoot) {
     "proxy.jsx",
     "proxy.mts",
     "proxy.cts"
-  ].map((file) => join2(projectRoot, file)).filter((file) => existsSync2(file));
+  ].map((file) => join3(projectRoot, file)).filter((file) => existsSync3(file));
   const files = /* @__PURE__ */ new Set();
   const ignoredDirNames = /* @__PURE__ */ new Set([
     "node_modules",
@@ -1239,9 +2084,9 @@ function collectProjectSourceFiles(projectRoot) {
     "coverage"
   ]);
   const walk = (dir) => {
-    for (const entry of readdirSync2(dir, { withFileTypes: true })) {
+    for (const entry of readdirSync3(dir, { withFileTypes: true })) {
       if (ignoredDirNames.has(entry.name)) continue;
-      const absolutePath = join2(dir, entry.name);
+      const absolutePath = join3(dir, entry.name);
       if (entry.isDirectory()) {
         walk(absolutePath);
         continue;
@@ -1272,7 +2117,7 @@ function isAuditableStyleFile(filePath) {
   return /\.css$/i.test(filePath);
 }
 function collectProjectStyleFiles(projectRoot) {
-  const candidates = ["src", "app", "styles"].map((dir) => join2(projectRoot, dir)).filter((dir) => existsSync2(dir));
+  const candidates = ["src", "app", "styles"].map((dir) => join3(projectRoot, dir)).filter((dir) => existsSync3(dir));
   const files = /* @__PURE__ */ new Set();
   const ignoredDirNames = /* @__PURE__ */ new Set([
     "node_modules",
@@ -1283,9 +2128,9 @@ function collectProjectStyleFiles(projectRoot) {
     "coverage"
   ]);
   const walk = (dir) => {
-    for (const entry of readdirSync2(dir, { withFileTypes: true })) {
+    for (const entry of readdirSync3(dir, { withFileTypes: true })) {
       if (ignoredDirNames.has(entry.name)) continue;
-      const absolutePath = join2(dir, entry.name);
+      const absolutePath = join3(dir, entry.name);
       if (entry.isDirectory()) {
         walk(absolutePath);
         continue;
@@ -1359,7 +2204,7 @@ function collectRuntimeImportSpecifiers(entry) {
 function resolveSourceImportTarget(projectRoot, sourceAbsolutePath, specifier) {
   let basePath = null;
   if (specifier.startsWith("@/")) {
-    basePath = join2(projectRoot, "src", specifier.slice(2));
+    basePath = join3(projectRoot, "src", specifier.slice(2));
   } else if (specifier.startsWith("./") || specifier.startsWith("../")) {
     basePath = resolve(dirname(sourceAbsolutePath), specifier);
   }
@@ -1372,14 +2217,14 @@ function resolveSourceImportTarget(projectRoot, sourceAbsolutePath, specifier) {
     `${basePath}.jsx`,
     `${basePath}.mts`,
     `${basePath}.cts`,
-    join2(basePath, "index.ts"),
-    join2(basePath, "index.tsx"),
-    join2(basePath, "index.js"),
-    join2(basePath, "index.jsx")
+    join3(basePath, "index.ts"),
+    join3(basePath, "index.tsx"),
+    join3(basePath, "index.js"),
+    join3(basePath, "index.jsx")
   ];
   for (const candidate of candidates) {
-    if (existsSync2(candidate) && isAuditableSourceFile(candidate)) {
-      return relative(projectRoot, candidate) || candidate;
+    if (existsSync3(candidate) && isAuditableSourceFile(candidate)) {
+      return relative2(projectRoot, candidate) || candidate;
     }
   }
   return null;
@@ -1428,8 +2273,8 @@ function auditProjectSourceTree(projectRoot) {
   const sourceFiles = collectProjectSourceFiles(projectRoot);
   const sourceEntries = sourceFiles.map((sourceFile) => ({
     absolutePath: sourceFile,
-    relativePath: relative(projectRoot, sourceFile) || sourceFile,
-    code: readFileSync2(sourceFile, "utf-8")
+    relativePath: relative2(projectRoot, sourceFile) || sourceFile,
+    code: readFileSync3(sourceFile, "utf-8")
   })).filter((entry) => !isNonProductionSourceAuditFile(entry.relativePath));
   const clientReachableFiles = collectClientReachableSourceFiles(projectRoot, sourceEntries);
   const summary = {
@@ -1742,8 +2587,8 @@ function auditProjectStyleContracts(projectRoot) {
     reducedMotionSignals: createSourceAuditBucket()
   };
   for (const styleFile of styleFiles) {
-    const relativePath = relative(projectRoot, styleFile) || styleFile;
-    const css = readFileSync2(styleFile, "utf-8");
+    const relativePath = relative2(projectRoot, styleFile) || styleFile;
+    const css = readFileSync3(styleFile, "utf-8");
     recordSourceAudit(summary.focusVisibleSignals, relativePath, countFocusVisibleSignals(css));
     recordSourceAudit(summary.reducedMotionSignals, relativePath, countReducedMotionSignals(css));
   }
@@ -1752,15 +2597,15 @@ function auditProjectStyleContracts(projectRoot) {
 function buildRegistryContext(projectRoot) {
   const themeRegistry = /* @__PURE__ */ new Map();
   const patternRegistry = /* @__PURE__ */ new Map();
-  const cacheDir = join2(projectRoot, ".decantr", "cache");
-  const customDir = join2(projectRoot, ".decantr", "custom");
-  const cachedThemesDir = join2(cacheDir, "@official", "themes");
+  const cacheDir = join3(projectRoot, ".decantr", "cache");
+  const customDir = join3(projectRoot, ".decantr", "custom");
+  const cachedThemesDir = join3(cacheDir, "@official", "themes");
   try {
-    if (existsSync2(cachedThemesDir)) {
-      for (const file of readdirSync2(cachedThemesDir).filter(
+    if (existsSync3(cachedThemesDir)) {
+      for (const file of readdirSync3(cachedThemesDir).filter(
         (name) => name.endsWith(".json") && name !== "index.json"
       )) {
-        const data = JSON.parse(readFileSync2(join2(cachedThemesDir, file), "utf-8"));
+        const data = JSON.parse(readFileSync3(join3(cachedThemesDir, file), "utf-8"));
         if (data.id && !themeRegistry.has(data.id)) {
           themeRegistry.set(data.id, { modes: data.modes || ["light", "dark"] });
         }
@@ -1768,11 +2613,11 @@ function buildRegistryContext(projectRoot) {
     }
   } catch {
   }
-  const customThemesDir = join2(customDir, "themes");
+  const customThemesDir = join3(customDir, "themes");
   try {
-    if (existsSync2(customThemesDir)) {
-      for (const file of readdirSync2(customThemesDir).filter((name) => name.endsWith(".json"))) {
-        const data = JSON.parse(readFileSync2(join2(customThemesDir, file), "utf-8"));
+    if (existsSync3(customThemesDir)) {
+      for (const file of readdirSync3(customThemesDir).filter((name) => name.endsWith(".json"))) {
+        const data = JSON.parse(readFileSync3(join3(customThemesDir, file), "utf-8"));
         if (data.id) {
           themeRegistry.set(`custom:${data.id}`, { modes: data.modes || ["light", "dark"] });
         }
@@ -1780,13 +2625,13 @@ function buildRegistryContext(projectRoot) {
     }
   } catch {
   }
-  const cachedPatternsDir = join2(cacheDir, "@official", "patterns");
+  const cachedPatternsDir = join3(cacheDir, "@official", "patterns");
   try {
-    if (existsSync2(cachedPatternsDir)) {
-      for (const file of readdirSync2(cachedPatternsDir).filter(
+    if (existsSync3(cachedPatternsDir)) {
+      for (const file of readdirSync3(cachedPatternsDir).filter(
         (name) => name.endsWith(".json") && name !== "index.json"
       )) {
-        const data = JSON.parse(readFileSync2(join2(cachedPatternsDir, file), "utf-8"));
+        const data = JSON.parse(readFileSync3(join3(cachedPatternsDir, file), "utf-8"));
         if (data.id && !patternRegistry.has(data.id)) {
           patternRegistry.set(data.id, data);
         }
@@ -2100,8 +2945,8 @@ function extractFailedRouteDocumentHardening(runtimeAudit) {
   return runtimeAudit.failures.filter((failure) => failure.startsWith("route-document-hardening-failed:")).map((failure) => normalizeRouteHint2(failure.slice("route-document-hardening-failed:".length))).filter(Boolean);
 }
 function appendRuntimeAuditFindings(findings, runtimeAudit, projectRoot, topology, sourceAudit) {
-  const distPath = join2(projectRoot, "dist");
-  const indexPath = join2(distPath, "index.html");
+  const distPath = join3(projectRoot, "dist");
+  const indexPath = join3(distPath, "index.html");
   const isFrameworkBuildOutput = runtimeAudit.failures.includes("next-build-output");
   if (!runtimeAudit.distPresent) {
     findings.push(
@@ -2648,20 +3493,20 @@ function appendSourceAuditFindings(findings, sourceAudit, essence, reviewPack, a
   if (sourceAudit.filesChecked === 0) {
     return;
   }
-  const isContractOnly = adoptionMode === "contract-only";
+  const isProjectOwnedStyling = adoptionMode === "contract-only" || adoptionMode === "style-bridge";
   if (sourceAudit.inlineStyles.count > 0) {
     findings.push(
       makeFinding({
         id: "source-inline-styles-present",
         category: "Source Audit",
         severity: "warn",
-        message: isContractOnly ? "Source files contain inline style attributes; contract-only projects should route static visual decisions through project-owned styling law." : "Source files still contain disallowed inline style attributes, which undermines the compiled treatment contract.",
+        message: isProjectOwnedStyling ? "Source files contain inline style attributes; project-owned styling projects should route static visual decisions through local law or the style bridge." : "Source files still contain disallowed inline style attributes, which undermines the compiled treatment contract.",
         evidence: buildSourceAuditEvidence(
           sourceAudit,
           sourceAudit.inlineStyles,
           "Disallowed inline style attributes"
         ),
-        suggestedFix: isContractOnly ? "Move static visual styling into the app design system, Tailwind/theme tokens, component variants, or accepted local rules. Keep inline style only for truly dynamic geometry." : "Move static visual styling into treatments, atoms, or design-token-backed classes. Inline style remains acceptable for Decantr CSS-variable writes and truly dynamic geometry."
+        suggestedFix: isProjectOwnedStyling ? "Move static visual styling into the app design system, Tailwind/theme tokens, component variants, or accepted local rules. Keep inline style only for truly dynamic geometry." : "Move static visual styling into treatments, atoms, or design-token-backed classes. Inline style remains acceptable for Decantr CSS-variable writes and truly dynamic geometry."
       })
     );
   }
@@ -2671,17 +3516,17 @@ function appendSourceAuditFindings(findings, sourceAudit, essence, reviewPack, a
         id: "source-component-style-tags-present",
         category: "Source Audit",
         severity: "warn",
-        message: isContractOnly ? "Source files inject component-scoped style tags or dynamic style elements, which makes project-owned styling rules harder to enforce." : "Source files inject component-scoped style tags or dynamic style elements, which bypass the compiled Decantr layer contract.",
+        message: isProjectOwnedStyling ? "Source files inject component-scoped style tags or dynamic style elements, which makes project-owned styling rules harder to enforce." : "Source files inject component-scoped style tags or dynamic style elements, which bypass the compiled Decantr layer contract.",
         evidence: buildSourceAuditEvidence(
           sourceAudit,
           sourceAudit.componentStyleTags,
           "Component-level style tag signals"
         ),
-        suggestedFix: isContractOnly ? "Move shared keyframes, media queries, and visual rules into the project stylesheet, component library, or accepted local pattern/rule manifest." : "Move shared keyframes, media queries, and visual rules into global.css or treatments.css so styling stays inside the reviewed Decantr layer stack."
+        suggestedFix: isProjectOwnedStyling ? "Move shared keyframes, media queries, and visual rules into the project stylesheet, component library, or accepted local pattern/rule manifest." : "Move shared keyframes, media queries, and visual rules into global.css or treatments.css so styling stays inside the reviewed Decantr layer stack."
       })
     );
   }
-  if (!isContractOnly && sourceAudit.localCssRuntimeSignals.count > 0) {
+  if (!isProjectOwnedStyling && sourceAudit.localCssRuntimeSignals.count > 0) {
     findings.push(
       makeFinding({
         id: "source-local-css-runtime-stub-present",
@@ -3780,15 +4625,15 @@ function appendStyleContractFindings(findings, styleAudit, essence) {
   }
 }
 async function auditProject(projectRoot) {
-  const essencePath = join2(projectRoot, "decantr.essence.json");
+  const essencePath = join3(projectRoot, "decantr.essence.json");
   const findings = [];
   const reviewPack = loadReviewPack(projectRoot);
   const packManifest = loadPackManifest(projectRoot);
   const adoptionMode = readProjectAdoptionMode(projectRoot);
-  const packHydrationOptional = adoptionMode === "contract-only";
+  const packHydrationOptional = adoptionMode === "contract-only" || adoptionMode === "style-bridge";
   const packHydrationSeverity = packHydrationOptional ? "info" : "warn";
   const runtimeAudit = emptyRuntimeAudit();
-  if (!existsSync2(essencePath)) {
+  if (!existsSync3(essencePath)) {
     findings.push(
       makeFinding({
         id: "essence-missing",
@@ -3823,7 +4668,7 @@ async function auditProject(projectRoot) {
   }
   let essence = null;
   try {
-    essence = JSON.parse(readFileSync2(essencePath, "utf-8"));
+    essence = JSON.parse(readFileSync3(essencePath, "utf-8"));
   } catch (error) {
     findings.push(
       makeFinding({
@@ -3865,8 +4710,8 @@ async function auditProject(projectRoot) {
         id: "pack-manifest-missing",
         category: "Execution Packs",
         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")],
+        message: packHydrationOptional ? "Compiled execution pack manifest is not hydrated yet; this is optional for contract-only/style-bridge Brownfield adoption." : "Compiled execution pack manifest is missing.",
+        evidence: [join3(projectRoot, ".decantr", "context", "pack-manifest.json")],
         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."
       })
     );
@@ -3929,8 +4774,8 @@ async function auditProject(projectRoot) {
         id: "review-pack-file-missing",
         category: "Review Contract",
         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")],
+        message: packHydrationOptional ? "The compiled review pack file is not hydrated yet; contract-only/style-bridge Brownfield projects can continue without it." : "The compiled review pack file is missing.",
+        evidence: [join3(projectRoot, ".decantr", "context", "review-pack.json")],
         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."
       })
     );
@@ -4071,7 +4916,7 @@ function countKeyboardShortcutSignals(code) {
   return matches.length;
 }
 function getScriptKind(filePath) {
-  switch (extname2(filePath).toLowerCase()) {
+  switch (extname3(filePath).toLowerCase()) {
     case ".tsx":
       return ts.ScriptKind.TSX;
     case ".jsx":
@@ -10358,16 +11203,16 @@ function critiqueSource({
   const findings = [];
   const scores = [];
   const antiPatternIds = new Set(reviewPack?.antiPatterns.map((entry) => entry.id) ?? []);
-  const isContractOnly = adoptionMode === "contract-only";
+  const isProjectOwnedStyling = adoptionMode === "contract-only" || adoptionMode === "style-bridge";
   const usedTreatments = TREATMENT_CLASSES.filter((token) => code.includes(token));
-  if (isContractOnly) {
+  if (isProjectOwnedStyling) {
     scores.push({
       category: "Styling Authority",
       focusArea: "treatment-usage",
       score: 3,
-      details: "Contract-only adoption does not require Decantr d-* treatment classes in source files.",
+      details: "Contract-only/style-bridge adoption does not require Decantr d-* treatment classes in source files.",
       suggestions: [
-        "Codify project-owned component variants and local rules when button/card/surface drift needs mechanical enforcement."
+        "Codify project-owned component variants, local rules, or a style bridge when button/card/surface drift needs stronger enforcement."
       ]
     });
   } else {
@@ -10404,12 +11249,12 @@ function critiqueSource({
   const decoratorNames = buildDecoratorInventory(treatmentsCss);
   const usedDecorators = decoratorNames.filter((name) => code.includes(name));
   const usesCssVars = code.includes("var(--");
-  if (isContractOnly) {
+  if (isProjectOwnedStyling) {
     scores.push({
       category: "Theme Consistency",
       focusArea: "theme-consistency",
       score: usesCssVars ? 4 : 3,
-      details: `Contract-only mode: Decantr decorators are not required; CSS vars: ${usesCssVars ? "yes" : "no"}.`,
+      details: `Contract-only/style-bridge mode: Decantr decorators are not required; CSS vars: ${usesCssVars ? "yes" : "no"}.`,
       suggestions: [
         "Use the app design system, Tailwind theme, Sass variables, component variants, or accepted local rules as the styling authority."
       ]
@@ -11436,7 +12281,7 @@ function critiqueSource({
           `Disallowed inline style attributes: ${astSignals.inlineStyleAttributeCount}`
         ],
         file: filePath,
-        suggestedFix: isContractOnly ? "Replace static inline visual values with the project design system, accepted component variants, or local style rules. Keep inline style only for truly dynamic geometry." : "Replace static inline visual values with treatments, decorators, and CSS variables from the compiled contract. Keep inline style only for Decantr CSS-variable writes and truly dynamic geometry."
+        suggestedFix: isProjectOwnedStyling ? "Replace static inline visual values with the project design system, accepted component variants, or local style rules. Keep inline style only for truly dynamic geometry." : "Replace static inline visual values with treatments, decorators, and CSS variables from the compiled contract. Keep inline style only for Decantr CSS-variable writes and truly dynamic geometry."
       })
     );
   }
@@ -11453,7 +12298,7 @@ function critiqueSource({
         message: "Component-scoped style tags or dynamic style elements were detected in the reviewed file.",
         evidence: [filePath, `Component style tag signals: ${componentStyleTagSignals}`],
         file: filePath,
-        suggestedFix: isContractOnly ? "Move shared keyframes, media queries, and visual rules into the project stylesheet, component library, or accepted local pattern/rule manifest." : "Move shared keyframes, media queries, and visual rules into global.css or treatments.css so the file stays aligned with the Decantr layer contract."
+        suggestedFix: isProjectOwnedStyling ? "Move shared keyframes, media queries, and visual rules into the project stylesheet, component library, or accepted local pattern/rule manifest." : "Move shared keyframes, media queries, and visual rules into global.css or treatments.css so the file stays aligned with the Decantr layer contract."
       })
     );
   }
@@ -12091,11 +12936,11 @@ function critiqueSource({
   };
 }
 function resolveProjectFilePath(projectRoot, filePath) {
-  const root = existsSync2(projectRoot) ? realpathSync.native(projectRoot) : resolve(projectRoot);
-  const candidatePath = isAbsolute(filePath) ? resolve(filePath) : resolve(root, filePath);
-  const resolvedPath = existsSync2(candidatePath) ? realpathSync.native(candidatePath) : candidatePath;
-  const relativePath = relative(root, resolvedPath);
-  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+  const root = existsSync3(projectRoot) ? realpathSync.native(projectRoot) : resolve(projectRoot);
+  const candidatePath = isAbsolute2(filePath) ? resolve(filePath) : resolve(root, filePath);
+  const resolvedPath = existsSync3(candidatePath) ? realpathSync.native(candidatePath) : candidatePath;
+  const relativePath = relative2(root, resolvedPath);
+  if (relativePath.startsWith("..") || isAbsolute2(relativePath)) {
     throw new Error(`Path escapes the project root: ${filePath}`);
   }
   return resolvedPath;
@@ -12103,7 +12948,7 @@ function resolveProjectFilePath(projectRoot, filePath) {
 async function critiqueFile(filePath, projectRoot) {
   const resolvedPath = resolveProjectFilePath(projectRoot, filePath);
   const code = await readFile(resolvedPath, "utf-8");
-  const treatmentsCss = readTextIfExists(join2(projectRoot, "src", "styles", "treatments.css"));
+  const treatmentsCss = readTextIfExists(join3(projectRoot, "src", "styles", "treatments.css"));
   const reviewPack = loadReviewPack(projectRoot);
   const packManifest = loadPackManifest(projectRoot);
   const adoptionMode = readProjectAdoptionMode(projectRoot);
@@ -12119,17 +12964,22 @@ async function critiqueFile(filePath, projectRoot) {
 export {
   EVIDENCE_BUNDLE_SCHEMA_URL,
   INTERACTION_SIGNALS,
+  SCAN_REPORT_SCHEMA_URL,
   VERIFICATION_SCHEMA_URLS,
   auditBuiltDist,
   auditProject,
   collectMissingPackManifestFiles,
   createContractAssertions,
   createEvidenceBundle,
+  createUnavailableScanReport,
   critiqueFile,
   critiqueSource,
   emptyRuntimeAudit,
   extractRouteHintsFromEssence,
   listKnownInteractions,
+  probePublishedSite,
+  resolveGitHubScanInput,
+  scanProject,
   verifyInteractionsInSource
 };
 //# sourceMappingURL=index.js.map