@monster-orange/den 0.0.0-stage → 0.1.0

package/src/shared/environment-manager/derivation/rules-http.ts

@@ -0,0 +1,247 @@
+/**
+ * Rule B — synchronous service dependencies (HTTP / JWKS).
+ *
+ * Three corroborating signals, all caller→callee:
+ *   - SDK imports: go.mod / package.json / pyproject.toml referencing a peer's SDK.
+ *   - env URLs: *_API_URL / *_SERVICE_URL / *_JWKS_URL / *_URL whose key token or
+ *     value host resolves to a peer (matched via the alias map).
+ *   - IaC stack refs: Pulumi `pulumi_<svc>_project_name` / `<svc>__internal_dns_hostname`.
+ *
+ * All edges are emitted `soft` here; blocking is finalized in derive-graph via the
+ * central `edges:` override (the source of truth for functional-hard edges).
+ */
+
+import type { AliasResolver } from "./alias.js";
+import type {
+  Confidence,
+  DerivedEdge,
+  EdgeKind,
+  ScannedFile,
+  ScannedRepo,
+} from "./types.js";
+import { evidenceAt, isCommentedLine, lineNumberAt } from "./text.js";
+
+const SDK_FILES = /(^|\/)(package\.json|go\.mod|pyproject\.toml)$/;
+const ENV_FILES = /(^|\/)(stack\.yml|\.env)/;
+const IAC_FILE = /\.py$/;
+
+// Longer suffixes first so e.g. SHOP_BACKEND_INTERNAL_URL → token "shop-backend".
+const URL_KEY =
+  /\b([A-Z0-9_]+?)_(API_URL|SERVICE_URL|JWKS_URL|BASE_URL|INTERNAL_URL|ENDPOINT_URL|ENDPOINT|URL|HOST|BASE)\b/g;
+const URL_VALUE = /https?:\/\/([a-z0-9][a-z0-9.-]*)/g;
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** `github.com/<org>/<repo>` for any configured SDK org (none → never matches). */
+const goSdk = (orgs: string[]) =>
+  orgs.length
+    ? new RegExp(
+        `github\\.com\\/(?:${orgs.map(escapeRe).join("|")})\\/([a-z0-9-]+)`,
+        "g",
+      )
+    : null;
+/** `@<scope>/<pkg>` for any configured npm scope (none → never matches). */
+const npmSdk = (scopes: string[]) =>
+  scopes.length
+    ? new RegExp(`@(?:${scopes.map(escapeRe).join("|")})\\/([a-z0-9-]+)`, "g")
+    : null;
+const PY_SDK = /\b([a-z][a-z0-9-]*-(?:sdk|events|client))\b/g;
+const PULUMI_REF =
+  /(?:pulumi_([a-z0-9_]+)_(?:project_name|stack_name)|([a-z0-9_]+)__internal_dns_hostname)/g;
+
+interface Candidate {
+  token: string;
+  kind: EdgeKind;
+  signal: string;
+  index: number;
+  confidence: Confidence;
+}
+
+/** matchAll results always carry an index; this just narrows the type. */
+const at = (m: RegExpMatchArray): number => m.index ?? 0;
+
+/**
+ * The assigned value on the line containing `index` — text after the first
+ * `:` or `=`, trimmed, surrounding quotes stripped. `""`, `KEY:`, and
+ * `KEY=` all read as empty.
+ */
+function lineValueAt(content: string, index: number): string {
+  const start = content.lastIndexOf("\n", index - 1) + 1;
+  let end = content.indexOf("\n", index);
+  if (end === -1) end = content.length;
+  const line = content.slice(start, end);
+  const sep = line.search(/[:=]/);
+  if (sep === -1) return "";
+  return line
+    .slice(sep + 1)
+    .trim()
+    .replace(/^["']|["']$/g, "")
+    .trim();
+}
+
+/**
+ * Compact evidence for an SDK-import edge: `<file>:<line>  <name> <version>`
+ * instead of the raw line — npm SDK deps resolve to a long api-specs `.tgz`
+ * URL that swamps the graph. The version is the last semver-ish token on the
+ * line (works for `…-0.2.18.tgz`, go `v0.2.6`, and npm `^1.2.3`).
+ */
+function sdkEvidence(file: ScannedFile, index: number, token: string): string {
+  const start = file.content.lastIndexOf("\n", index - 1) + 1;
+  let end = file.content.indexOf("\n", index);
+  if (end === -1) end = file.content.length;
+  const line = file.content.slice(start, end);
+  // Core semver + optional hyphenated pre-release only — a hyphen won't attach
+  // a file extension the way `[-.]` did (`…-0.1.14.tgz` → "0.1.14", not
+  // "0.1.14.tgz"), while `1.2.3-rc1` is still captured whole.
+  const versions = line.match(/\d+\.\d+(?:\.\d+)?(?:-[A-Za-z0-9.]+)?/g);
+  const version = versions?.[versions.length - 1];
+  return `${file.rel}:${lineNumberAt(file.content, index)}  ${token}${version ? ` ${version}` : ""}`;
+}
+
+/**
+ * go.mod hygiene: only DIRECT `require` entries are real dependencies. Skips
+ * transitive modules (`// indirect`) and `replace`/`exclude` directive lines —
+ * a replace target is a local override, not a new callee.
+ */
+function isDirectGoRequire(content: string, index: number): boolean {
+  const start = content.lastIndexOf("\n", index - 1) + 1;
+  let end = content.indexOf("\n", index);
+  if (end === -1) end = content.length;
+  const line = content.slice(start, end);
+  if (/\/\/\s*indirect\b/.test(line)) return false;
+  const head = line.trimStart();
+  return (
+    !head.startsWith("replace") &&
+    !head.startsWith("exclude") &&
+    !line.includes("=>")
+  );
+}
+
+function pushEdge(
+  out: DerivedEdge[],
+  repo: ScannedRepo,
+  alias: AliasResolver,
+  file: ScannedFile,
+  c: Candidate,
+): void {
+  const to = alias.resolve(c.token);
+  if (!to || to === repo.repoName || to === alias.infraRepo) return;
+  if (isCommentedLine(file.content, c.index)) return; // skip commented-out config
+  out.push({
+    from: repo.repoName,
+    to,
+    kind: c.kind,
+    blocking: "soft",
+    signal: c.signal,
+    evidence:
+      c.signal === "http:sdk-import"
+        ? sdkEvidence(file, c.index, c.token)
+        : evidenceAt(file, c.index),
+    confidence: c.confidence,
+  });
+}
+
+function scanFile(
+  out: DerivedEdge[],
+  repo: ScannedRepo,
+  alias: AliasResolver,
+  file: ScannedFile,
+): void {
+  const add = (c: Candidate) => pushEdge(out, repo, alias, file, c);
+
+  if (SDK_FILES.test(file.rel)) {
+    const NPM_SDK = npmSdk(alias.npmScopes);
+    const GO_SDK = goSdk(alias.sdkOrgs);
+    if (NPM_SDK)
+      for (const m of file.content.matchAll(NPM_SDK))
+        add({
+          token: m[1],
+          kind: "http",
+          signal: "http:sdk-import",
+          index: at(m),
+          confidence: "high",
+        });
+    if (GO_SDK)
+      for (const m of file.content.matchAll(GO_SDK)) {
+        if (
+          file.rel.endsWith("go.mod") &&
+          !isDirectGoRequire(file.content, at(m))
+        )
+          continue;
+        add({
+          token: m[1],
+          kind: "http",
+          signal: "http:sdk-import",
+          index: at(m),
+          confidence: "high",
+        });
+      }
+    if (file.rel.endsWith("pyproject.toml"))
+      for (const m of file.content.matchAll(PY_SDK))
+        add({
+          token: m[1],
+          kind: "http",
+          signal: "http:sdk-import",
+          index: at(m),
+          confidence: "high",
+        });
+  }
+
+  if (ENV_FILES.test(file.rel)) {
+    // stack.yml declares keys once with an EMPTY value (`SHOP_JWKS_URL:`) and
+    // fills them in per-env sections below. Group matches per key and cite the
+    // first occurrence that actually carries a value, so the graph evidence
+    // reads `TOKEN_SERVICE_URL: http://tokens` instead of a bare key.
+    const bestByKey = new Map<string, RegExpMatchArray>();
+    for (const m of file.content.matchAll(URL_KEY)) {
+      if (isCommentedLine(file.content, at(m))) continue;
+      const cur = bestByKey.get(m[0]);
+      if (!cur) {
+        bestByKey.set(m[0], m);
+      } else if (
+        lineValueAt(file.content, at(cur)) === "" &&
+        lineValueAt(file.content, at(m)) !== ""
+      ) {
+        bestByKey.set(m[0], m);
+      }
+    }
+    for (const m of bestByKey.values()) {
+      const kind: EdgeKind = m[2].includes("JWKS") ? "jwks" : "http";
+      add({
+        token: m[1],
+        kind,
+        signal: "http:env-url",
+        index: at(m),
+        confidence: "high",
+      });
+    }
+    for (const m of file.content.matchAll(URL_VALUE)) {
+      const host = m[1].split(/[.:]/)[0];
+      add({
+        token: host,
+        kind: "http",
+        signal: "http:env-url",
+        index: at(m),
+        confidence: "medium",
+      });
+    }
+  }
+
+  if (IAC_FILE.test(file.rel)) {
+    for (const m of file.content.matchAll(PULUMI_REF))
+      add({
+        token: m[1] ?? m[2],
+        kind: "http",
+        signal: "http:iac-stack-ref",
+        index: at(m),
+        confidence: "medium",
+      });
+  }
+}
+
+export function deriveHttpEdges(
+  repo: ScannedRepo,
+  alias: AliasResolver,
+): DerivedEdge[] {
+  const out: DerivedEdge[] = [];
+  for (const file of repo.files) scanFile(out, repo, alias, file);
+  return out;
+}

package/src/shared/environment-manager/derivation/rules-infra.ts

@@ -0,0 +1,64 @@
+/**
+ * Rule A — the shared local-infra repo (`graph.infra` in the org config).
+ *
+ * When an org runs shared local infra (databases, cloud emulators, …) from one
+ * repo, backends must not start until it is healthy. A repo whose infra files
+ * (stack.yml, manifest, Makefile, env files) match a configured signal gets a
+ * single hard `repo → <infra repo>` edge. No `graph.infra`: no edges.
+ */
+
+import { product } from "../../product.js";
+import type { AliasResolver } from "./alias.js";
+import type { DerivedEdge, ScannedRepo } from "./types.js";
+import { evidenceAt, isCommentedLine } from "./text.js";
+
+const escapeRe = (s: string): string =>
+  s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** Files that carry local-infra wiring. */
+const infraFiles = (): RegExp =>
+  new RegExp(
+    `(^|/)(stack\\.yml|${product().manifestFiles.map(escapeRe).join("|")}|Makefile|\\.env)`,
+  );
+
+export function deriveInfraEdges(
+  repo: ScannedRepo,
+  alias: AliasResolver,
+): DerivedEdge[] {
+  const infra = alias.infraRepo;
+  if (!infra || repo.repoName === infra) return [];
+  if (!alias.knownRepos.has(infra)) return [];
+  // Configured signals are strong (concrete wiring); a bare mention of the
+  // infra repo's name is weak and only used when no strong signal is found.
+  const STRONG_SIGNALS = alias.infraSignals;
+  const WEAK_SIGNALS = [new RegExp(`\\b${escapeRe(infra)}\\b`)];
+
+  const filesRe = infraFiles();
+  const infraFilesOf = repo.files.filter((f) => filesRe.test(f.rel));
+  const edgeAt = (file: (typeof infraFilesOf)[number], index: number) => [
+    {
+      from: repo.repoName,
+      to: infra,
+      kind: "infra" as const,
+      blocking: "hard" as const,
+      signal: "infra",
+      evidence: evidenceAt(file, index),
+      confidence: "high" as const,
+    },
+  ];
+
+  // Signal-major: exhaust the strong signals across every file first, so a
+  // concrete `:4566` in one file wins over a bare-name mention in another.
+  for (const signals of [STRONG_SIGNALS, WEAK_SIGNALS]) {
+    for (const re of signals) {
+      for (const file of infraFilesOf) {
+        for (const m of file.content.matchAll(new RegExp(re, "g"))) {
+          const index = m.index ?? 0;
+          if (isCommentedLine(file.content, index)) continue;
+          return edgeAt(file, index);
+        }
+      }
+    }
+  }
+  return [];
+}

package/src/shared/environment-manager/derivation/rules-readiness.ts

@@ -0,0 +1,96 @@
+/**
+ * Rule D — readiness-probe dependencies (the "read the /readyz code" signal).
+ *
+ * A peer service referenced inside a DEDICATED readiness/health handler
+ * (`readyz_get`, `healthz_get`, `health.go`, `health_router.py`, …) is, by
+ * convention, a startup gate: the service declares it isn't ready until that
+ * peer is reachable. So we emit a HARD edge for it.
+ *
+ * This is forward-looking: today every surveyed `/readyz` checks only its own
+ * DB/redis, so this rule yields nothing. It activates automatically once a team
+ * adopts the convention (make `/readyz` 200 only when hard deps are reachable).
+ * We deliberately scan only dedicated handler files — never broad files like
+ * main.py — to avoid false positives. Comments are blanked before matching, and
+ * bare single-word aliases ("app", "token", "backend") only count as URL hosts —
+ * in prose they are far too ambiguous to mint a hard startup gate from.
+ */
+
+import type { AliasResolver } from "./alias.js";
+import type { DerivedEdge, ScannedRepo } from "./types.js";
+import { evidenceAt } from "./text.js";
+
+const HANDLER_FILE = /(readyz|healthz|health_router|(^|\/)health\.go$)/;
+const TOKEN = /[A-Za-z][A-Za-z0-9_.-]+/g;
+const URL_HOST = /https?:\/\/([a-z0-9][a-z0-9.-]*)/g;
+/** Multi-segment tokens (`files-api`, `shop.web`, `token_service`) only. */
+const MULTI_SEGMENT = /[-._]/;
+
+/**
+ * Where an inline `//` or `#` comment starts on `line`, or -1. A `//` preceded
+ * by `:` is a URL scheme separator (`http://…`), not a comment.
+ */
+function commentStart(line: string): number {
+  let slashes = line.indexOf("//");
+  while (slashes > 0 && line[slashes - 1] === ":") {
+    slashes = line.indexOf("//", slashes + 1);
+  }
+  const hash = line.indexOf("#");
+  if (slashes === -1) return hash;
+  if (hash === -1) return slashes;
+  return Math.min(slashes, hash);
+}
+
+/**
+ * Blank full-line AND inline comments with spaces. Lengths and newlines are
+ * preserved so match indexes still map onto the original content for evidence.
+ */
+function blankComments(content: string): string {
+  return content
+    .split("\n")
+    .map((line) => {
+      const cut = commentStart(line);
+      return cut === -1
+        ? line
+        : line.slice(0, cut) + " ".repeat(line.length - cut);
+    })
+    .join("\n");
+}
+
+export function deriveReadinessEdges(
+  repo: ScannedRepo,
+  alias: AliasResolver,
+): DerivedEdge[] {
+  const out: DerivedEdge[] = [];
+  const seen = new Set<string>();
+  for (const file of repo.files) {
+    if (!HANDLER_FILE.test(file.rel)) continue;
+    const code = blankComments(file.content);
+    const emit = (token: string, index: number): void => {
+      const to = alias.resolve(token);
+      if (!to || to === repo.repoName || to === alias.infraRepo || seen.has(to))
+        return;
+      seen.add(to);
+      out.push({
+        from: repo.repoName,
+        to,
+        kind: "http",
+        blocking: "hard",
+        signal: "readiness-probe",
+        evidence: evidenceAt(file, index),
+        confidence: "high",
+      });
+    };
+    // A URL host is structured context — a bare word counts there
+    // (`http://tokens:8080/healthz` really does gate on the tokens service).
+    for (const m of code.matchAll(URL_HOST)) {
+      emit(m[1].split(/[.:]/)[0], m.index ?? 0);
+    }
+    // Everywhere else only multi-segment tokens count: bare alias words like
+    // "app" or "token" are just as often prose, and every readiness edge is a
+    // HARD startup gate — too costly to mint from a stray word.
+    for (const m of code.matchAll(TOKEN)) {
+      if (MULTI_SEGMENT.test(m[0])) emit(m[0], m.index ?? 0);
+    }
+  }
+  return out;
+}

package/src/shared/environment-manager/derivation/scan.ts

@@ -0,0 +1,160 @@
+/**
+ * Filesystem scanning helpers for dependency derivation.
+ *
+ * Discovery reads a small, fixed allow-list of files per repo (manifests, SDK
+ * descriptors, env config, root Makefile, IaC) — never a full-repo walk — so a
+ * cold derive of one repo is a few dozen small reads (tens of ms). The same
+ * file list is the cache fingerprint key (see cache.ts).
+ */
+
+import {
+  heldManifestPath,
+  repoManifestPath,
+} from "../../manifest/read-manifest.js";
+import * as fs from "fs";
+import * as path from "path";
+import type { ScannedFile, ScannedRepo } from "./types.js";
+
+import { product } from "../../product.js";
+/** Root-relative files probed in every repo (those that exist are read). */
+const ROOT_CANDIDATES = [
+  `${product().manifestYml}`,
+  `${product().manifestJson}`,
+  "package.json",
+  "go.mod",
+  "pyproject.toml",
+  "stack.yml",
+  "Makefile",
+  ".env",
+  ".env.example",
+  ".env.local.example",
+  ".env.op",
+  // shop keeps its backend config one level down.
+  "apps/backend/.env",
+  "apps/backend/.env.example",
+  "apps/backend/env.example",
+  "apps/backend/stack.yml",
+] as const;
+
+/** Directories whose `.py` files carry IaC (Pulumi/EventBridge) signals. */
+const IAC_DIRS: Array<{ dir: string; depth: number }> = [
+  { dir: "pulumi", depth: 1 },
+  { dir: "infra", depth: 2 },
+];
+
+/**
+ * Conventional, DEDICATED readiness/health-handler files (stack layout). A peer
+ * service referenced here is a startup gate (see rules-readiness.ts). We list
+ * exact paths — never broad files like main.py — to avoid false positives. The
+ * Python package dir varies, so it is resolved with a one-level `src/*` glob.
+ */
+const GO_HEALTH_HANDLERS = [
+  "internal/apis/health/health.go",
+  "internal/apis/health/readyz_get.go",
+  "internal/apis/health/healthz_get.go",
+  "internal/apis/shop/readyz_get.go",
+  "internal/apis/shop/healthz_get.go",
+];
+const PY_HEALTH_HANDLERS = [
+  "internal/apis/health/readyz_get.py",
+  "internal/apis/health/healthz_get.py",
+  "internal/routers/health_router.py",
+];
+
+function healthHandlerFiles(repoPath: string): string[] {
+  const out: string[] = [];
+  for (const rel of GO_HEALTH_HANDLERS) {
+    const abs = path.join(repoPath, rel);
+    if (fs.existsSync(abs)) out.push(abs);
+  }
+  let pkgs: fs.Dirent[];
+  try {
+    pkgs = fs.readdirSync(path.join(repoPath, "src"), { withFileTypes: true });
+  } catch {
+    pkgs = [];
+  }
+  for (const pkg of pkgs) {
+    if (!pkg.isDirectory()) continue;
+    for (const rel of PY_HEALTH_HANDLERS) {
+      const abs = path.join(repoPath, "src", pkg.name, rel);
+      if (fs.existsSync(abs)) out.push(abs);
+    }
+  }
+  return out;
+}
+
+/** A repo "exists" for graph purposes if it has any of these markers. */
+export function hasRepoMarker(dir: string): boolean {
+  return (
+    fs.existsSync(path.join(dir, `${product().manifestYml}`)) ||
+    fs.existsSync(path.join(dir, `${product().manifestJson}`)) ||
+    (fs.existsSync(dir) && heldManifestPath(dir) !== null) ||
+    fs.existsSync(path.join(dir, "Makefile")) ||
+    fs.existsSync(path.join(dir, ".git"))
+  );
+}
+
+export function readFileSafe(abs: string): string | null {
+  try {
+    return fs.readFileSync(abs, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+function listPyFiles(dir: string, depth: number): string[] {
+  const out: string[] = [];
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (e.name.startsWith(".")) continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (depth > 0) out.push(...listPyFiles(p, depth - 1));
+    } else if (e.isFile() && e.name.endsWith(".py")) {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+/**
+ * Absolute paths of the input files that exist for a repo — the exact set the
+ * rules read and the cache fingerprints. Order is stable for a given tree.
+ */
+export function repoInputFiles(repoPath: string): string[] {
+  const files: string[] = [];
+  for (const rel of ROOT_CANDIDATES) {
+    const abs = path.join(repoPath, rel);
+    if (fs.existsSync(abs)) files.push(abs);
+  }
+  for (const { dir, depth } of IAC_DIRS) {
+    files.push(...listPyFiles(path.join(repoPath, dir), depth));
+  }
+  files.push(...healthHandlerFiles(repoPath));
+  // A den-held manifest stands in for a missing .den.yml.
+  if (!repoManifestPath(repoPath)) {
+    const held = heldManifestPath(repoPath);
+    if (held) files.push(held);
+  }
+  return files;
+}
+
+/** Read all of a repo's input files into memory for the rules to scan. */
+export function scanRepo(repoName: string, repoPath: string): ScannedRepo {
+  const files: ScannedFile[] = [];
+  for (const abs of repoInputFiles(repoPath)) {
+    const content = readFileSafe(abs);
+    if (content === null) continue;
+    // A held manifest lives outside the repo; rules see it as .den.yml.
+    const rel = abs.startsWith(repoPath + path.sep)
+      ? path.relative(repoPath, abs)
+      : `${product().manifestYml}`;
+    files.push({ abs, rel, content });
+  }
+  return { repoName, repoPath, files };
+}

package/src/shared/environment-manager/derivation/text.ts

@@ -0,0 +1,40 @@
+/**
+ * Small text helpers shared by the derivation rules — turning a regex match
+ * into human-readable `file:line  snippet` evidence.
+ */
+
+import type { ScannedFile } from "./types.js";
+
+export function lineNumberAt(content: string, index: number): number {
+  let line = 1;
+  for (let i = 0; i < index && i < content.length; i++) {
+    if (content[i] === "\n") line++;
+  }
+  return line;
+}
+
+/** The trimmed source line containing `index`, capped for display. */
+function lineTextAt(content: string, index: number): string {
+  const start = content.lastIndexOf("\n", index - 1) + 1;
+  let end = content.indexOf("\n", index);
+  if (end === -1) end = content.length;
+  const text = content.slice(start, end).trim();
+  return text.length > 160 ? `${text.slice(0, 157)}…` : text;
+}
+
+export function evidenceAt(file: ScannedFile, index: number): string {
+  return `${file.rel}:${lineNumberAt(file.content, index)}  ${lineTextAt(file.content, index)}`;
+}
+
+/**
+ * Whether the source line containing `index` is commented out (`#` for
+ * yaml/env/toml/python, `//` for go/js). Used to skip false-positive matches on
+ * commented-out config like `# FILES_API_URL=...`.
+ */
+export function isCommentedLine(content: string, index: number): boolean {
+  const start = content.lastIndexOf("\n", index - 1) + 1;
+  let end = content.indexOf("\n", index);
+  if (end === -1) end = content.length;
+  const line = content.slice(start, end).trimStart();
+  return line.startsWith("#") || line.startsWith("//");
+}

package/src/shared/environment-manager/derivation/types.ts

@@ -0,0 +1,69 @@
+/**
+ * Types for the derived dependency graph (`den graph` / derived `den up`).
+ *
+ * The graph is derived from real signals in each repo (SDK imports, service
+ * URLs, IaC stack refs, EventBridge rules) rather than trusting each repo's
+ * hand-written `.den.yml` `depends_on`. See derive-graph.ts for the engine.
+ */
+
+/**
+ * What kind of dependency an edge represents — this drives whether `den up`
+ * orders on it:
+ *   infra — shared local infra (infra-stack / LocalStack). Hard foundation.
+ *   http  — synchronous HTTP call to a peer service.
+ *   jwks  — peer's JWKS endpoint used for JWT verification (a kind of http).
+ *   event — EventBridge producer→consumer data-flow. Shown, never ordered.
+ */
+export type EdgeKind = "infra" | "http" | "jwks" | "event";
+
+/**
+ * Whether the edge constrains startup order:
+ *   hard — `from`'s `make up` fails / `from` is non-functional unless `to` is up first.
+ *   soft — started as part of the dev stack but does not constrain order.
+ */
+export type EdgeBlocking = "hard" | "soft";
+
+export type Confidence = "high" | "medium" | "low";
+
+export interface DerivedEdge {
+  /** Source repo-system name (catalog/repo key). */
+  from: string;
+  /** Target repo-system name (alias-normalized). */
+  to: string;
+  kind: EdgeKind;
+  blocking: EdgeBlocking;
+  /** Rule id that produced the edge, e.g. "http:env-url" or "event:eventbridge-rule". */
+  signal: string;
+  /** Human-readable evidence: file (relative to repo) + short snippet. */
+  evidence: string;
+  confidence: Confidence;
+  /**
+   * Whether this edge constrains startup ORDER. Tolerant edges (JWKS auth,
+   * redirect URLs, reconcilers) are still shown and still pull the target into
+   * the start set, but don't gate sequence. Defaults to true when omitted.
+   */
+  ordering?: boolean;
+}
+
+export interface DerivedGraph {
+  /** Repo-system names present in the graph. */
+  nodes: string[];
+  /** Deduped edges between nodes. */
+  edges: DerivedEdge[];
+}
+
+/** A file read from a repo during discovery (content cached for the rules). */
+export interface ScannedFile {
+  /** Path relative to the repo root (used in evidence + filtering). */
+  rel: string;
+  /** Absolute path. */
+  abs: string;
+  content: string;
+}
+
+/** A repo's scanned inputs, passed to the rule functions. */
+export interface ScannedRepo {
+  repoName: string;
+  repoPath: string;
+  files: ScannedFile[];
+}