@olomonhelpdesk2/helpdesk 0.1.0

package/helpdesk.mjs

@@ -0,0 +1,1097 @@
+#!/usr/bin/env node
+
+// adapters/map-cli.ts
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join as join2 } from "node:path";
+
+// core/discovery/next-app-router.ts
+var PAGE_FILE = /(^|\/)page\.(tsx|ts|jsx|js)$/;
+var LAYOUT_FILE = /(^|\/)layout\.(tsx|ts|jsx|js)$/;
+var STATE_FILE = /(^|\/)(error|global-error|loading|not-found|template|default)\.(tsx|ts|jsx|js)$/;
+var ROUTE_GROUP = /^\((.+)\)$/;
+var DYNAMIC = /^\[{1,2}(\.{3})?(.+?)\]{1,2}$/;
+var PARALLEL = /^@/;
+var INTERCEPTING = /^\(\.+\)/;
+function classify(path) {
+  if (path === "/api" || path.startsWith("/api/")) {
+    return { skipped: "not-html", note: "an API route, not a screen" };
+  }
+  if (/(^|\/)(admin|internal|debug|_dev)(\/|$)/.test(path)) {
+    return { skipped: "internal-tooling", note: "internal tooling" };
+  }
+  if (/(^|\/)(login|logout|signin|sign-in|signup|sign-up|auth|verify|reset-password)(\/|$)/.test(path)) {
+    return { skipped: "unauthenticated-flow", note: "an authentication step" };
+  }
+  return void 0;
+}
+function detectRouterRoot(files) {
+  for (const candidate2 of ["src/app", "app"]) {
+    if (files.some((file) => file.startsWith(`${candidate2}/`) && PAGE_FILE.test(file))) {
+      return candidate2;
+    }
+  }
+  return void 0;
+}
+function readNextAppRouter(files, root = "src/app") {
+  const prefix = root.endsWith("/") ? root : `${root}/`;
+  const inRouter = [...new Set(files)].filter((file) => file.startsWith(prefix));
+  const layouts = inRouter.filter((file) => LAYOUT_FILE.test(file));
+  const routes = [];
+  const ignored = [];
+  for (const file of inRouter) {
+    if (!PAGE_FILE.test(file)) continue;
+    const segments = file.slice(prefix.length).split("/").slice(0, -1);
+    const parsed = toPath(segments);
+    if ("reason" in parsed) {
+      ignored.push({ file, reason: parsed.reason });
+      continue;
+    }
+    const classification = classify(parsed.path);
+    routes.push({
+      path: parsed.path,
+      // The page, then what sits beside it, then the layouts that wrap it.
+      //
+      // Co-located files matter as much as the page: a route's server actions
+      // and client components are where its behaviour actually lives, so an
+      // article about the screen goes stale when THEY change. Taking only the
+      // page would leave change detection blind to the part most likely to move.
+      sourceFiles: [file, ...siblings(file, inRouter), ...enclosingLayouts(file, layouts)],
+      params: parsed.params,
+      groups: parsed.groups,
+      states: declaredStates(file, inRouter, prefix),
+      ...classification ?? {}
+    });
+  }
+  routes.sort((a, b) => depth(a.path) - depth(b.path) || a.path.localeCompare(b.path));
+  return { framework: "next-app-router", routes, ignored };
+}
+function declaredStates(pageFile, files, prefix) {
+  const directory = pageFile.slice(0, pageFile.lastIndexOf("/"));
+  const own = new Set(
+    files.filter((file) => file.slice(0, file.lastIndexOf("/")) === directory)
+  );
+  const found = /* @__PURE__ */ new Map();
+  for (let at = directory; at.length >= prefix.length - 1; ) {
+    for (const file of files) {
+      if (file.slice(0, file.lastIndexOf("/")) !== at) continue;
+      const kind = stateKindOf(file);
+      if (!kind || found.has(kind)) continue;
+      found.set(kind, {
+        kind,
+        file,
+        segment: at.slice(prefix.length - 1).replace(/^\//, ""),
+        inherited: !own.has(file)
+      });
+    }
+    const up = at.lastIndexOf("/");
+    if (up < 0 || at.length <= prefix.length - 1) break;
+    at = at.slice(0, up);
+  }
+  return [...found.values()].sort((a, b) => a.kind.localeCompare(b.kind));
+}
+function stateKindOf(file) {
+  const match = /(^|\/)(error|global-error|loading|not-found)\.(tsx|ts|jsx|js)$/.exec(file);
+  return match ? match[2] : void 0;
+}
+function toPath(segments) {
+  const parts = [];
+  const params = [];
+  const groups = [];
+  for (const segment of segments) {
+    if (INTERCEPTING.test(segment)) return { reason: "an intercepting route, not its own URL" };
+    if (PARALLEL.test(segment)) return { reason: "a parallel route slot, not its own URL" };
+    const group = ROUTE_GROUP.exec(segment);
+    if (group) {
+      groups.push(group[1]);
+      continue;
+    }
+    const dynamic = DYNAMIC.exec(segment);
+    if (dynamic) {
+      params.push(dynamic[2]);
+      parts.push(segment);
+      continue;
+    }
+    parts.push(segment);
+  }
+  return { path: `/${parts.join("/")}`.replace(/\/+$/, "") || "/", params, groups };
+}
+function siblings(pageFile, files) {
+  const dir = pageFile.slice(0, pageFile.lastIndexOf("/") + 1);
+  return files.filter((file) => file !== pageFile && file.startsWith(dir) && !file.slice(dir.length).includes("/")).filter((file) => !/(^|\/)(opengraph-image|twitter-image|icon|apple-icon|sitemap|robots)\./.test(file)).filter((file) => !STATE_FILE.test(file)).filter((file) => !LAYOUT_FILE.test(file)).sort();
+}
+function enclosingLayouts(pageFile, layouts) {
+  const dir = pageFile.slice(0, pageFile.lastIndexOf("/"));
+  return layouts.filter((layout) => dir.startsWith(layout.slice(0, layout.lastIndexOf("/")))).sort((a, b) => a.length - b.length);
+}
+function depth(path) {
+  return path === "/" ? 0 : path.split("/").filter(Boolean).length;
+}
+
+// core/discovery/article-plan.ts
+var MONEY_OR_ACCESS = /* @__PURE__ */ new Set([
+  "billing",
+  "invoice",
+  "invoices",
+  "payment",
+  "payments",
+  "subscription",
+  "subscriptions",
+  "plan",
+  "plans",
+  "pricing",
+  "seat",
+  "seats",
+  "permission",
+  "permissions",
+  "role",
+  "roles",
+  "member",
+  "members"
+]);
+var ENTRY_POINT = /* @__PURE__ */ new Set([
+  "onboard",
+  "onboarding",
+  "setup",
+  "get-started",
+  "getting-started",
+  "welcome",
+  "install",
+  "import",
+  "connect",
+  "integration",
+  "integrations"
+]);
+function hasSegment(path, vocabulary) {
+  return path.split("/").filter(Boolean).some((segment) => vocabulary.has(segment.toLowerCase()));
+}
+function score(route, signals) {
+  const because = [];
+  const segments = route.path.split("/").filter(Boolean);
+  let total = 0;
+  const depthPenalty = Math.min(segments.length, 5) * 8;
+  total += 40 - depthPenalty;
+  if (segments.length <= 1) because.push("a top-level destination");
+  if (route.params.length > 0) {
+    total += 10;
+    because.push("a record detail screen");
+  }
+  if (signals.writes && signals.writes > 0) {
+    total += Math.min(signals.writes, 4) * 7;
+    because.push(
+      signals.writes === 1 ? "somewhere a user changes something" : `${signals.writes} actions a user can take here`
+    );
+  }
+  if (signals.fanIn && signals.fanIn > 2) {
+    total += Math.min(signals.fanIn, 8) * 2;
+    because.push("linked to from across the app");
+  }
+  if (hasSegment(route.path, MONEY_OR_ACCESS)) {
+    total += 18;
+    because.push("money or access \u2014 asked about out of proportion to its traffic");
+  }
+  if (hasSegment(route.path, ENTRY_POINT)) {
+    total += 16;
+    because.push("one of the first things a new customer does");
+  }
+  return { score: total, because };
+}
+function tierFor(rank, count) {
+  if (rank <= Math.max(3, Math.ceil(count * 0.1))) return "critical";
+  if (rank <= Math.max(8, Math.ceil(count * 0.3))) return "core";
+  if (rank <= Math.max(16, Math.ceil(count * 0.6))) return "supporting";
+  return "minor";
+}
+function slugFor(path) {
+  const segments = path.split("/").filter(Boolean).filter((segment) => !segment.startsWith("["));
+  return segments.length ? segments.join("/") : "overview";
+}
+function titleFor(route) {
+  const segments = route.path.split("/").filter(Boolean).filter((s) => !s.startsWith("["));
+  if (!segments.length) return "Getting around";
+  const words = segments[segments.length - 1].replace(/[-_]/g, " ");
+  const subject = words.charAt(0).toUpperCase() + words.slice(1);
+  if (!route.params.length) return subject;
+  return `Working with ${article(singular(subject.toLowerCase()))}`;
+}
+function singular(word) {
+  if (/(sis|ss|us|is)$/.test(word)) return word;
+  if (/(ches|shes|xes|zes)$/.test(word)) return word.slice(0, -2);
+  if (/[^aeiou]ies$/.test(word)) return `${word.slice(0, -3)}y`;
+  if (/s$/.test(word)) return word.slice(0, -1);
+  return word;
+}
+function article(word) {
+  return /^[aeiou]/.test(word) ? `an ${word}` : `a ${word}`;
+}
+function buildArticlePlan(options) {
+  const existing = new Set(options.existingSlugs ?? []);
+  const excluded = [];
+  const scored = [];
+  for (const route of options.routes) {
+    if (route.skipped) {
+      excluded.push({ route: route.path, reason: route.note ?? route.skipped });
+      continue;
+    }
+    scored.push({ route, ...score(route, options.signals?.[route.path] ?? {}) });
+  }
+  scored.sort((a, b) => b.score - a.score || a.route.path.localeCompare(b.route.path));
+  const merged = /* @__PURE__ */ new Map();
+  for (const entry of scored) {
+    const slug = slugFor(entry.route.path);
+    const existingNeed = merged.get(slug);
+    if (!existingNeed) {
+      merged.set(slug, {
+        entry,
+        routes: [entry.route.path],
+        files: [...entry.route.sourceFiles],
+        because: [...entry.because],
+        ...entry.route.title ? { title: entry.route.title } : {}
+      });
+      continue;
+    }
+    if (!existingNeed.title && entry.route.title) existingNeed.title = entry.route.title;
+    existingNeed.routes.push(entry.route.path);
+    for (const file of entry.route.sourceFiles) {
+      if (!existingNeed.files.includes(file)) existingNeed.files.push(file);
+    }
+    for (const reason of entry.because) {
+      if (!existingNeed.because.includes(reason)) existingNeed.because.push(reason);
+    }
+  }
+  let covered = 0;
+  const needs = [...merged.entries()].map(([slug, group], index) => {
+    const rank = index + 1;
+    const claimed = [group.entry.route.path, ...group.routes.slice(1) ?? []].map((path) => options.documented?.[path]).find(Boolean);
+    const already = existing.has(slug) || Boolean(claimed);
+    if (already) covered += 1;
+    return {
+      slug,
+      title: group.title ?? titleFor(group.entry.route),
+      route: group.entry.route.path,
+      ...group.routes.length > 1 ? { alsoCovers: group.routes.slice(1) } : {},
+      tier: tierFor(rank, merged.size),
+      rank,
+      sourceRefs: group.files,
+      because: group.because,
+      ...already ? { covered: claimed ?? slug } : {}
+    };
+  });
+  return { needs, excluded, covered };
+}
+function formatArticlePlan(plan, limit = 12) {
+  const missing = plan.needs.filter((need) => !need.covered);
+  const lines = [];
+  lines.push(
+    `${missing.length} article${missing.length === 1 ? "" : "s"} to write \xB7 ${plan.covered} already covered`,
+    ""
+  );
+  let tier;
+  for (const need of missing.slice(0, limit)) {
+    if (need.tier !== tier) {
+      tier = need.tier;
+      lines.push(`  ${tier.toUpperCase()}`);
+    }
+    lines.push(`    ${need.slug.padEnd(34)} ${need.route}`);
+    if (need.because.length) lines.push(`      ${need.because.join("; ")}`);
+  }
+  if (missing.length > limit) {
+    lines.push("", `  \u2026and ${missing.length - limit} more, in priority order.`);
+  }
+  if (plan.excluded.length) {
+    lines.push("", `  ${plan.excluded.length} route(s) excluded:`);
+    for (const item of plan.excluded.slice(0, 5)) {
+      lines.push(`    ${item.route.padEnd(34)} ${item.reason}`);
+    }
+    if (plan.excluded.length > 5) lines.push(`    \u2026and ${plan.excluded.length - 5} more.`);
+  }
+  return lines.join("\n");
+}
+
+// core/discovery/screen-modules.ts
+var SOURCE = /\.(tsx|ts|jsx|js|mjs|cjs)$/;
+var EVERYTHING = "*";
+function screenModules(entries, options) {
+  const known = new Set(options.files);
+  const aliases = options.aliases ?? {};
+  const baseUrl = options.baseUrl;
+  const maxDepth = options.maxDepth ?? 4;
+  const maxFiles = options.maxFiles ?? 40;
+  const kept = [];
+  const visited = /* @__PURE__ */ new Map();
+  let frontier = entries.filter((entry) => known.has(entry)).map((entry) => ({ path: entry, wanted: /* @__PURE__ */ new Set([EVERYTHING]) }));
+  for (let depth2 = 0; depth2 <= maxDepth && frontier.length && kept.length < maxFiles; depth2 += 1) {
+    const next = /* @__PURE__ */ new Map();
+    for (const { path, wanted } of frontier) {
+      if (kept.length >= maxFiles) break;
+      const already = visited.get(path);
+      if (already && [...wanted].every((name) => already.has(name) || already.has(EVERYTHING))) {
+        continue;
+      }
+      visited.set(path, /* @__PURE__ */ new Set([...already ?? [], ...wanted]));
+      if (!already) kept.push({ path, depth: depth2 });
+      if (!SOURCE.test(path)) continue;
+      const contents = options.read(path);
+      if (!contents) continue;
+      for (const edge of edgesFrom(contents, wanted)) {
+        const resolved = resolve(edge.specifier, path, known, aliases, baseUrl);
+        if (!resolved) continue;
+        next.set(resolved, /* @__PURE__ */ new Set([...next.get(resolved) ?? [], ...edge.wanted]));
+      }
+    }
+    frontier = [...next].map(([path, wanted]) => ({ path, wanted }));
+  }
+  return kept;
+}
+function edgesFrom(contents, wanted) {
+  const reExports = reExportsIn(contents);
+  const edges = [];
+  const everything = wanted.has(EVERYTHING);
+  for (const reExport of reExports.named) {
+    if (everything || wanted.has(reExport.exposedAs)) {
+      edges.push({ specifier: reExport.specifier, wanted: /* @__PURE__ */ new Set([reExport.localName]) });
+    }
+  }
+  for (const specifier of reExports.stars) {
+    edges.push({ specifier, wanted: /* @__PURE__ */ new Set([EVERYTHING]) });
+  }
+  if (isPureBarrel(contents, reExports)) return edges;
+  for (const imported of importsIn(contents)) {
+    edges.push({ specifier: imported.specifier, wanted: imported.names });
+  }
+  return edges;
+}
+var RE_EXPORT_NAMED = /(?:^|[\n;])\s*export\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/g;
+var RE_EXPORT_STAR = /(?:^|[\n;])\s*export\s*\*(?:\s+as\s+[\w$]+)?\s*from\s*["']([^"']+)["']/g;
+function reExportsIn(contents) {
+  const named = [];
+  const stars = [];
+  for (const match of contents.matchAll(RE_EXPORT_NAMED)) {
+    for (const clause of match[1].split(",")) {
+      const parts = clause.trim().replace(/^type\s+/, "").split(/\s+as\s+/);
+      if (!parts[0]) continue;
+      named.push({
+        localName: parts[0].trim(),
+        exposedAs: (parts[1] ?? parts[0]).trim(),
+        specifier: match[2]
+      });
+    }
+  }
+  for (const match of contents.matchAll(RE_EXPORT_STAR)) stars.push(match[1]);
+  return { named, stars };
+}
+function isPureBarrel(contents, reExports) {
+  if (!reExports.named.length && !reExports.stars.length) return false;
+  const remainder = contents.replace(RE_EXPORT_NAMED, " ").replace(RE_EXPORT_STAR, " ").replace(/\/\*[\s\S]*?\*\//g, " ").replace(/^[ \t]*\/\/.*$/gm, " ").replace(/(?:^|[\n;])\s*import\b[^;\n]*(?:;|\n)/g, " ").trim();
+  return remainder.length < 40;
+}
+var IMPORT = /(?:^|[\n;])\s*import\s+([^;'"]*?)\s*from\s*["']([^"']+)["']/g;
+var SIDE_EFFECT_IMPORT = /(?:^|[\n;])\s*import\s*["']([^"']+)["']/g;
+var DYNAMIC_IMPORT = /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+function importsIn(contents) {
+  const found = [];
+  for (const match of contents.matchAll(IMPORT)) {
+    found.push({ specifier: match[2], names: namesIn(match[1]) });
+  }
+  for (const match of contents.matchAll(SIDE_EFFECT_IMPORT)) {
+    found.push({ specifier: match[1], names: /* @__PURE__ */ new Set([EVERYTHING]) });
+  }
+  for (const match of contents.matchAll(DYNAMIC_IMPORT)) {
+    found.push({ specifier: match[1], names: /* @__PURE__ */ new Set([EVERYTHING]) });
+  }
+  return found;
+}
+function namesIn(clause) {
+  const names = /* @__PURE__ */ new Set();
+  const braces = /\{([^}]*)\}/.exec(clause);
+  if (/\*\s+as\s+/.test(clause)) names.add(EVERYTHING);
+  const beforeBraces = (braces ? clause.slice(0, braces.index) : clause).replace(/,\s*$/, "").trim();
+  if (beforeBraces && !beforeBraces.startsWith("*")) names.add("default");
+  for (const clauseName of braces?.[1]?.split(",") ?? []) {
+    const local = clauseName.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim();
+    if (local) names.add(local);
+  }
+  return names.size ? names : /* @__PURE__ */ new Set([EVERYTHING]);
+}
+function resolve(specifier, importer, known, aliases, baseUrl) {
+  if (specifier.startsWith(".")) {
+    return candidate(join(dirname(importer), specifier), known);
+  }
+  for (const [from, to] of Object.entries(aliases)) {
+    if (!specifier.startsWith(from)) continue;
+    const mapped = candidate(normalise(to + specifier.slice(from.length)), known);
+    if (mapped) return mapped;
+  }
+  if (baseUrl !== void 0) {
+    return candidate(join(baseUrl, specifier), known);
+  }
+  return void 0;
+}
+function candidate(base, known) {
+  if (known.has(base) && SOURCE.test(base)) return base;
+  const stem = base.replace(/\.(js|jsx|mjs|cjs)$/, "");
+  for (const extension of ["tsx", "ts", "jsx", "js"]) {
+    for (const path of [`${stem}.${extension}`, `${stem}/index.${extension}`]) {
+      if (known.has(path)) return path;
+    }
+  }
+  return void 0;
+}
+function dirname(path) {
+  const cut = path.lastIndexOf("/");
+  return cut < 0 ? "" : path.slice(0, cut);
+}
+function join(dir, relative) {
+  return normalise(dir ? `${dir}/${relative}` : relative);
+}
+function normalise(path) {
+  const out = [];
+  for (const segment of path.split("/")) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      out.pop();
+      continue;
+    }
+    out.push(segment);
+  }
+  return out.join("/");
+}
+function parseTsconfig(source) {
+  if (source === void 0) return {};
+  let out = "";
+  let inString = false;
+  for (let index = 0; index < source.length; index += 1) {
+    const character = source[index];
+    const next = source[index + 1];
+    if (inString) {
+      out += character;
+      if (character === "\\") {
+        out += next ?? "";
+        index += 1;
+      } else if (character === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (character === '"') {
+      inString = true;
+      out += character;
+      continue;
+    }
+    if (character === "/" && next === "/") {
+      while (index < source.length && source[index] !== "\n") index += 1;
+      out += "\n";
+      continue;
+    }
+    if (character === "/" && next === "*") {
+      const close = source.indexOf("*/", index + 2);
+      index = close < 0 ? source.length : close + 1;
+      out += " ";
+      continue;
+    }
+    out += character;
+  }
+  try {
+    return JSON.parse(out.replace(/,(\s*[}\]])/g, "$1"));
+  } catch {
+    return {};
+  }
+}
+function aliasesFromTsconfig(tsconfig) {
+  const paths = tsconfig?.compilerOptions?.paths;
+  if (!paths || typeof paths !== "object") return {};
+  const aliases = {};
+  for (const [pattern, targets] of Object.entries(paths)) {
+    if (!pattern.endsWith("/*") || !Array.isArray(targets)) continue;
+    const target = targets.find(
+      (value) => typeof value === "string" && value.endsWith("/*")
+    );
+    if (!target) continue;
+    aliases[pattern.slice(0, -1)] = `${normalise(target.slice(0, -1))}/`;
+  }
+  return aliases;
+}
+function baseUrlFromTsconfig(tsconfig) {
+  const baseUrl = tsconfig?.compilerOptions?.baseUrl;
+  if (typeof baseUrl !== "string") return void 0;
+  const cleaned = normalise(baseUrl.replace(/^\.\/+/, "").replace(/\/+$/, ""));
+  return cleaned === "." ? "" : cleaned;
+}
+
+// core/discovery/screen-facts.ts
+function noScreenFacts() {
+  return { headings: [], actions: [], links: [], fields: [], notices: [], warnings: [], readFrom: [] };
+}
+var LIMITS = {
+  headings: 12,
+  actions: 24,
+  links: 24,
+  fields: 24,
+  notices: 20,
+  warnings: 12,
+  choices: 12,
+  /** Longer than this is a paragraph of copy, not a label. */
+  label: 120,
+  sentence: 300
+};
+var IRREVERSIBLE = /\b(cannot be undone|can't be undone|permanently|permanent|irreversible|no way back|cannot be recovered|unrecoverable|this cannot be reversed)\b/i;
+var DESTRUCTIVE = /\b(delete|deletes|deleting|remove|removes|revoke|revokes|erase|wipe|discard|destroy|overwrite|overwrites|reset|disconnect|unpublish|cancel subscription)\b/i;
+var PERMISSION = /\b(only (?:an?\s+)?(?:owner|admin|administrator)s?\b|your role|not allowed|do(?:es)? not have permission|don't have permission|permission to|requires? (?:an? )?(?:owner|admin|editing|editor)|admins? only|read[- ]only)\b/i;
+function readScreenFacts(files, options = {}) {
+  const facts = noScreenFacts();
+  const headings = [];
+  const actions = [];
+  const links = [];
+  const fields = [];
+  const notices = [];
+  const warnings = [];
+  const messageDepth = options.messageDepth ?? 2;
+  for (const file of files) {
+    if (options.skip?.(file.path)) continue;
+    const source = withoutComments(file.contents);
+    const before = headings.length + actions.length + links.length + fields.length + notices.length;
+    readElements(source, { headings, actions, links, fields });
+    if ((file.depth ?? 0) <= messageDepth) readMessages(source, notices);
+    const after = headings.length + actions.length + links.length + fields.length + notices.length;
+    if (after > before) facts.readFrom.push(file.path);
+  }
+  return finishScreenFacts({ headings, actions, links, fields, notices, readFrom: facts.readFrom });
+}
+function finishScreenFacts(parts) {
+  const warnings = [];
+  for (const sentence of parts.notices) {
+    if (IRREVERSIBLE.test(sentence) || PERMISSION.test(sentence)) warnings.push(sentence);
+  }
+  for (const label of parts.actions) {
+    if (DESTRUCTIVE.test(label)) warnings.push(`"${label}" destroys or replaces something.`);
+  }
+  return {
+    headings: capped(parts.headings, LIMITS.headings),
+    actions: capped(parts.actions, LIMITS.actions),
+    links: cappedBy(parts.links, (link) => `${link.label ?? ""}|${link.href}`, LIMITS.links),
+    fields: cappedBy(parts.fields, (field) => `${field.label}|${field.kind}`, LIMITS.fields),
+    notices: capped(parts.notices, LIMITS.notices),
+    warnings: capped(warnings, LIMITS.warnings),
+    readFrom: parts.readFrom
+  };
+}
+var HEADING_TAG = /^h[1-4]$/;
+var BUTTON_TAG = /^(button|Button|MenuItem|Tab)$/;
+var LINK_TAG = /^(a|Link|NavLink)$/;
+var FIELD_TAG = /^(input|Input|textarea|Textarea|select|Select|Checkbox|Radio|Switch|Toggle)$/;
+function readElements(source, into) {
+  for (const tag of tagsIn(source)) {
+    const attributes = readAttributes(tag.attributes);
+    if (HEADING_TAG.test(tag.name)) {
+      push(into.headings, visibleText(childrenOf(source, tag)));
+      continue;
+    }
+    push(into.headings, attributes["heading"]);
+    if (BUTTON_TAG.test(tag.name)) {
+      push(into.actions, visibleText(childrenOf(source, tag)) || attributes["label"] || attributes["aria-label"]);
+      continue;
+    }
+    if (LINK_TAG.test(tag.name)) {
+      const href = attributes["href"];
+      if (href && !href.startsWith("{")) {
+        const label = visibleText(childrenOf(source, tag)) || attributes["aria-label"];
+        into.links.push(label ? { label, href } : { href });
+      }
+      continue;
+    }
+    if (FIELD_TAG.test(tag.name)) {
+      const field = fieldFrom(tag.name, attributes, source, tag);
+      if (field) into.fields.push(field);
+    }
+  }
+  for (const tag of tagsIn(source)) {
+    if (tag.name !== "label") continue;
+    const text = visibleText(childrenOf(source, tag));
+    if (text && !into.fields.some((field) => field.label === text)) {
+      into.fields.push({ label: text, kind: "text" });
+    }
+  }
+  for (const match of source.matchAll(NAVIGATION)) {
+    const href = match[1];
+    if (href.startsWith("/") && !into.links.some((link) => link.href === href)) {
+      into.links.push({ href });
+    }
+  }
+}
+var NAVIGATION = /\b(?:router\.(?:push|replace)|redirect|navigate)\s*\(\s*["'`]([^"'`${}]+)["'`]/g;
+function fieldFrom(name, attributes, source, tag) {
+  const label = attributes["label"] ?? attributes["aria-label"] ?? attributes["placeholder"] ?? humanise(attributes["name"] ?? attributes["id"] ?? "");
+  if (!label) return void 0;
+  const kind = /select/i.test(name) ? "select" : /textarea/i.test(name) ? "textarea" : /checkbox|switch|toggle/i.test(name) ? "checkbox" : /radio/i.test(name) ? "radio" : attributes["type"] ?? "text";
+  if (kind !== "select") return { label: trim(label, LIMITS.label), kind };
+  const choices = [];
+  for (const option of tagsIn(childrenOf(source, tag))) {
+    if (option.name !== "option") continue;
+    const text = visibleText(childrenOf(childrenOf(source, tag), option));
+    if (text) choices.push(text);
+  }
+  return choices.length ? { label: trim(label, LIMITS.label), kind, choices: capped(choices, LIMITS.choices) } : { label: trim(label, LIMITS.label), kind };
+}
+var MESSAGE_CALL = /\b(?:setError|setMessage|setStatus|setWarning|toast(?:\.\w+)?|confirm|alert|notify)\s*\(\s*(["'`])((?:(?!\1)[\s\S]){12,}?)\1/g;
+var MESSAGE_THROW = /\bthrow new (?:\w*Error)\s*\(\s*(["'`])((?:(?!\1)[\s\S]){12,}?)\1/g;
+var MESSAGE_PROPERTY = /(?:^|[\s,{(])(?:error|message|reason|warning|hint|emptyState|helpText)\s*:\s*(["'`])((?:(?!\1)[\s\S]){12,}?)\1/g;
+function isCustomerFacing(text) {
+  if (!/[a-z]/i.test(text)) return false;
+  const words = text.split(/\s+/).filter(Boolean);
+  if (words.length < 4) return false;
+  const codey = words.filter((word) => /[._]|[a-z][A-Z]/.test(word)).length;
+  if (codey * 3 >= words.length) return false;
+  return /[.!?]$/.test(text) || words.length >= 8;
+}
+function readMessages(source, into) {
+  for (const pattern of [MESSAGE_CALL, MESSAGE_THROW, MESSAGE_PROPERTY]) {
+    for (const match of source.matchAll(pattern)) {
+      const text = match[2].replace(/\$\{[^}]*\}/g, "\u2026").replace(/\s+/g, " ").trim();
+      if (isCustomerFacing(text)) push(into, trim(text, LIMITS.sentence));
+    }
+  }
+}
+function* tagsIn(source) {
+  for (let index = 0; index < source.length; index += 1) {
+    if (source[index] !== "<") continue;
+    const nameMatch = /^<([A-Za-z][\w.-]*)/.exec(source.slice(index, index + 64));
+    if (!nameMatch) continue;
+    const name = nameMatch[1];
+    let cursor = index + nameMatch[0].length;
+    let depth2 = 0;
+    let quote;
+    while (cursor < source.length) {
+      const character = source[cursor];
+      if (quote) {
+        if (character === quote) quote = void 0;
+        else if (character === "\\") cursor += 1;
+      } else if (character === '"' || character === "'" || character === "`") {
+        quote = character;
+      } else if (character === "{") {
+        depth2 += 1;
+      } else if (character === "}") {
+        depth2 -= 1;
+      } else if (character === ">" && depth2 <= 0) {
+        break;
+      }
+      cursor += 1;
+    }
+    if (cursor >= source.length) return;
+    const raw = source.slice(index + nameMatch[0].length, cursor);
+    yield {
+      name,
+      attributes: raw,
+      selfClosing: raw.trimEnd().endsWith("/"),
+      end: cursor + 1
+    };
+    index = cursor;
+  }
+}
+function childrenOf(source, tag) {
+  if (tag.selfClosing) return "";
+  const open = new RegExp(`<${escapeName(tag.name)}[\\s/>]`, "g");
+  const close = `</${tag.name}>`;
+  let depth2 = 1;
+  let cursor = tag.end;
+  while (cursor < source.length) {
+    const closeAt = source.indexOf(close, cursor);
+    if (closeAt < 0) return "";
+    open.lastIndex = cursor;
+    let openAt = -1;
+    const nested = open.exec(source);
+    if (nested && nested.index < closeAt) openAt = nested.index;
+    if (openAt >= 0) {
+      depth2 += 1;
+      cursor = openAt + 1;
+      continue;
+    }
+    depth2 -= 1;
+    if (depth2 === 0) return source.slice(tag.end, closeAt);
+    cursor = closeAt + close.length;
+  }
+  return "";
+}
+function escapeName(name) {
+  return name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function visibleText(fragment) {
+  if (!fragment) return "";
+  let text = fragment;
+  let previous = "";
+  while (text !== previous) {
+    previous = text;
+    text = text.replace(/\{[^{}]*\}/g, " ");
+  }
+  text = text.replace(/<[^>]*>/g, " ").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&mdash;/g, "\u2014").replace(/&ndash;/g, "\u2013").replace(/&(?:l|r)squo;/g, "'").replace(/&(?:l|r)dquo;/g, '"').replace(/&#\d+;/g, " ").replace(/\s+/g, " ").trim();
+  return /[A-Za-z]/.test(text) ? trim(text, LIMITS.label) : "";
+}
+function readAttributes(raw) {
+  const attributes = {};
+  for (const match of raw.matchAll(/([A-Za-z_:][\w:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*["'`]([^"'`]*)["'`]\s*\})/g)) {
+    const value = match[2] ?? match[3] ?? match[4];
+    if (value !== void 0 && value.trim()) attributes[match[1]] = value.trim();
+  }
+  return attributes;
+}
+function withoutComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/^[ \t]*\/\/.*$/gm, "");
+}
+function humanise(name) {
+  const words = name.replace(/[_-]+/g, " ").replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/\s+/g, " ").trim();
+  return words ? words.charAt(0).toUpperCase() + words.slice(1).toLowerCase() : "";
+}
+function scrubExpressions(value) {
+  return value.replace(/\$\{[^}]*\}/g, "\u2026").replace(/\s+/g, " ").trim();
+}
+function push(into, value) {
+  const text = value === void 0 ? "" : scrubExpressions(value);
+  if (!text || !/[A-Za-z]/.test(text)) return;
+  if ((text.match(/…/g)?.length ?? 0) > 1) return;
+  into.push(trim(text, LIMITS.label));
+}
+function trim(value, limit) {
+  return value.length <= limit ? value : `${value.slice(0, limit - 1).trimEnd()}\u2026`;
+}
+function capped(values, limit) {
+  return [...new Set(values)].slice(0, limit);
+}
+function cappedBy(values, key, limit) {
+  const seen = /* @__PURE__ */ new Set();
+  const kept = [];
+  for (const value of values) {
+    const identity = key(value);
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    kept.push(value);
+    if (kept.length >= limit) break;
+  }
+  return kept;
+}
+
+// core/discovery/read-product.ts
+function readProduct(routes, options) {
+  const maxScreens = options.maxScreens ?? 200;
+  const opened = /* @__PURE__ */ new Set();
+  const contents = /* @__PURE__ */ new Map();
+  const read = (path) => {
+    if (contents.has(path)) return contents.get(path);
+    const found = options.read(path);
+    if (found !== void 0) {
+      contents.set(path, found);
+      opened.add(path);
+    }
+    return found;
+  };
+  const documentable = routes.filter((route) => !route.skipped);
+  const total = Math.min(documentable.length, maxScreens);
+  let done = 0;
+  let withFacts = 0;
+  const out = routes.map((route) => {
+    if (route.skipped || done >= maxScreens) return route;
+    const modules = screenModules(route.sourceFiles, { ...options, read });
+    const files = [];
+    for (const reached of modules) {
+      const source = read(reached.path);
+      if (source !== void 0) files.push({ path: reached.path, contents: source, depth: reached.depth });
+    }
+    const facts = readScreenFacts(files);
+    done += 1;
+    options.onScreen?.(route, done, total);
+    if (!hasAnything(facts)) return route;
+    withFacts += 1;
+    return { ...route, facts };
+  });
+  return { routes: out, read: withFacts, filesOpened: opened.size };
+}
+function hasAnything(facts) {
+  return Boolean(
+    facts.headings.length || facts.actions.length || facts.links.length || facts.fields.length || facts.notices.length
+  );
+}
+function describeReading(routes) {
+  const documentable = routes.filter((route) => !route.skipped);
+  const read = documentable.filter((route) => route.facts && hasAnything(route.facts)).length;
+  return { screens: documentable.length, read, pathsOnly: read === 0 };
+}
+
+// core/markers/propose.ts
+function toLines(contents) {
+  const lines = contents.split("\n");
+  if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}
+var COMMENT = {
+  ts: "//",
+  tsx: "//",
+  js: "//",
+  jsx: "//",
+  mjs: "//",
+  cjs: "//",
+  go: "//",
+  rs: "//",
+  java: "//",
+  kt: "//",
+  swift: "//",
+  cs: "//",
+  php: "//",
+  scala: "//",
+  dart: "//",
+  rb: "#",
+  py: "#",
+  sh: "#",
+  bash: "#",
+  yml: "#",
+  yaml: "#",
+  ex: "#",
+  exs: "#",
+  erb: "#"
+};
+var DIRECTIVE = /^\s*["'](use (client|server|strict))["'];?\s*$/;
+var SHEBANG = /^#!/;
+function commentFor(path) {
+  const extension = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
+  return COMMENT[extension];
+}
+function insertionLine(lines) {
+  let index = 0;
+  if (lines[0] && SHEBANG.test(lines[0])) index += 1;
+  while (index < lines.length && (lines[index].trim() === "" || DIRECTIVE.test(lines[index]))) {
+    index += 1;
+  }
+  if (lines[index]?.trimStart().startsWith("/*")) {
+    while (index < lines.length && !lines[index].includes("*/")) index += 1;
+    index += 1;
+  }
+  return index + 1;
+}
+function proposeMarkers(options) {
+  const proposals = [];
+  const matched = /* @__PURE__ */ new Set();
+  const allSlugs = new Set(Object.values(options.slugsByFile));
+  let alreadyMarked = 0;
+  for (const file of options.files) {
+    const slug = options.slugsByFile[file.path];
+    if (!slug) continue;
+    const comment = commentFor(file.path);
+    if (!comment) continue;
+    matched.add(slug);
+    if (new RegExp(`@helpdoc[:\\s]+${escapeRegExp(slug)}(?![A-Za-z0-9._/-])`).test(file.contents)) {
+      alreadyMarked += 1;
+      continue;
+    }
+    const lines = toLines(file.contents);
+    proposals.push({
+      file: file.path,
+      line: insertionLine(lines),
+      slug,
+      text: `${comment} @helpdoc ${slug}`,
+      because: `this file is part of the screen "${slug}" documents`
+    });
+  }
+  return {
+    proposals,
+    alreadyMarked,
+    // Named rather than hidden: an article nothing points at can never be
+    // flagged, and the gate should be honest about its own coverage.
+    unmatchedSlugs: [...allSlugs].filter((slug) => !matched.has(slug)).sort()
+  };
+}
+function markersToDiff(files, proposals) {
+  const byFile = /* @__PURE__ */ new Map();
+  for (const proposal of proposals) {
+    const list = byFile.get(proposal.file);
+    if (list) list.push(proposal);
+    else byFile.set(proposal.file, [proposal]);
+  }
+  const contents = new Map(files.map((file) => [file.path, file.contents]));
+  const chunks = [];
+  for (const [path, fileProposals] of [...byFile.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const source = contents.get(path);
+    if (source === void 0) continue;
+    const lines = toLines(source);
+    chunks.push(`--- a/${path}`, `+++ b/${path}`);
+    for (const proposal of [...fileProposals].sort((a, b) => a.line - b.line)) {
+      const start = Math.max(1, proposal.line - 3);
+      const before = lines.slice(start - 1, proposal.line - 1);
+      const after = lines.slice(proposal.line - 1, proposal.line - 1 + 3);
+      chunks.push(
+        `@@ -${start},${before.length + after.length} +${start},${before.length + after.length + 1} @@`,
+        ...before.map((line) => ` ${line}`),
+        `+${proposal.text}`,
+        ...after.map((line) => ` ${line}`)
+      );
+    }
+  }
+  return chunks.join("\n");
+}
+function markersPullRequestBody(result) {
+  const lines = [
+    "This adds one-line comments that link screens in this repository to the help articles that describe them.",
+    "",
+    "**Nothing here changes behaviour.** Each line is a comment. Once merged, a change to one of these files tells our help desk which article may now be out of date, so somebody can check it before a customer does.",
+    "",
+    `${result.proposals.length} marker${result.proposals.length === 1 ? "" : "s"} proposed.`
+  ];
+  if (result.alreadyMarked > 0) {
+    lines.push(`${result.alreadyMarked} file${result.alreadyMarked === 1 ? " already carries" : "s already carry"} the right marker and ${result.alreadyMarked === 1 ? "was" : "were"} left alone.`);
+  }
+  lines.push(
+    "",
+    "**A wrong one costs nothing.** Delete the line and the article stops being linked to that file. If we missed one, the screen is still matched by its route \u2014 this only makes the match more precise."
+  );
+  if (result.unmatchedSlugs.length > 0) {
+    lines.push(
+      "",
+      `We could not find code for ${result.unmatchedSlugs.length} article${result.unmatchedSlugs.length === 1 ? "" : "s"}: ${result.unmatchedSlugs.join(", ")}. Those will not be flagged when the code behind them changes.`
+    );
+  }
+  return lines.join("\n");
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function slugsByFileFromPlan(needs) {
+  const mapping = {};
+  const rankOf = {};
+  for (const need of needs) {
+    for (const file of need.sourceRefs) {
+      const incumbent = rankOf[file];
+      if (incumbent === void 0 || need.rank < incumbent) {
+        mapping[file] = need.slug;
+        rankOf[file] = need.rank;
+      }
+    }
+  }
+  return mapping;
+}
+
+// adapters/map-cli.ts
+function repositoryFiles(cwd) {
+  return execFileSync("git", ["ls-files"], { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }).split("\n").filter(Boolean);
+}
+async function runMap(options) {
+  const files = repositoryFiles(options.cwd);
+  const inventory = readNextAppRouter(files, options.root);
+  if (!inventory.routes.length) {
+    throw new Error(
+      `No routes found under ${options.root}. Run this from your repository root, or pass --root.`
+    );
+  }
+  const lines = [`Found ${inventory.routes.length} screens under ${options.root}.`];
+  let routes = inventory.routes;
+  if (options.facts !== false) {
+    const tsconfig = readTsconfig(options.cwd);
+    const read = readProduct(inventory.routes, {
+      files,
+      read: (path) => {
+        try {
+          return readFileSync(join2(options.cwd, path), "utf8");
+        } catch {
+          return void 0;
+        }
+      },
+      aliases: aliasesFromTsconfig(tsconfig),
+      baseUrl: baseUrlFromTsconfig(tsconfig)
+    });
+    routes = read.routes;
+    const reading = describeReading(routes);
+    lines.push(
+      reading.pathsOnly ? "Could not read what any of them show. The help desk will have their addresses and nothing else, so its articles will be written from URLs. Check --root points at your app." : `Read what ${reading.read} of ${reading.screens} of them show, from ${read.filesOpened} files.`
+    );
+  }
+  const plan = buildArticlePlan({ routes });
+  lines.push("", formatArticlePlan(plan, 10));
+  if (options.markersOut) {
+    const mapping = slugsByFileFromPlan(plan.needs);
+    const sources = Object.keys(mapping).map((path) => ({
+      path,
+      contents: readFileSync(join2(options.cwd, path), "utf8")
+    }));
+    const proposed = proposeMarkers({ files: sources, slugsByFile: mapping });
+    const diff = markersToDiff(sources, proposed.proposals);
+    writeFileSync(options.markersOut, diff ? `${diff}
+` : "");
+    writeFileSync(`${options.markersOut}.md`, markersPullRequestBody(proposed));
+    lines.push(
+      "",
+      proposed.proposals.length ? `Wrote ${proposed.proposals.length} marker(s) to ${options.markersOut}. Apply with:
+  git apply ${options.markersOut}` : "Every file already carries its marker \u2014 nothing to propose."
+    );
+  }
+  let sent = false;
+  if (options.token && options.to) {
+    const response = await fetch(new URL("/api/helpdesk/map", options.to).toString(), {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${options.token}` },
+      body: JSON.stringify({
+        framework: inventory.framework,
+        repository: originOf(options.cwd),
+        // Where these were read from, so the workflow the founder installs
+        // later watches this folder rather than guessing `src/app`.
+        routerRoot: options.root,
+        // Paths, filenames, and the words printed on each screen. Never source.
+        routes
+      })
+    });
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new Error(`The help desk refused the map (${response.status}). ${body}`);
+    }
+    sent = true;
+    lines.push("", "Sent. Whoever asked you to run this can see it now \u2014 you are done.");
+  } else if (options.token) {
+    lines.push("", "No destination given. Pass --to https://your-helpdesk.example to send this.");
+  }
+  return {
+    routes: routes.length,
+    read: describeReading(routes).read,
+    sent,
+    report: lines.join("\n")
+  };
+}
+function readTsconfig(cwd) {
+  for (const name of ["tsconfig.json", "jsconfig.json"]) {
+    try {
+      return parseTsconfig(readFileSync(join2(cwd, name), "utf8"));
+    } catch {
+      continue;
+    }
+  }
+  return {};
+}
+function originOf(cwd) {
+  try {
+    return execFileSync("git", ["remote", "get-url", "origin"], { cwd, encoding: "utf8" }).trim();
+  } catch {
+    return void 0;
+  }
+}
+
+// adapters/map-bin.ts
+function arg(name) {
+  const index = process.argv.indexOf(`--${name}`);
+  return index === -1 ? void 0 : process.argv[index + 1];
+}
+async function main() {
+  const cwd = process.cwd();
+  const root = arg("root") ?? detectRouterRoot(repositoryFiles(cwd));
+  if (!root) {
+    console.error(
+      "Could not find a Next.js app router here. Run this from your repository root, or pass --root <dir>."
+    );
+    process.exit(1);
+  }
+  const result = await runMap({
+    cwd,
+    root,
+    ...arg("token") === void 0 ? {} : { token: arg("token") },
+    ...arg("to") === void 0 ? {} : { to: arg("to") },
+    ...arg("markers") === void 0 ? {} : { markersOut: arg("markers") },
+    ...arg("facts") === "off" ? { facts: false } : {}
+  });
+  console.log(result.report);
+}
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});