@documentation-robotics/cli 0.2.0 → 0.4.0

package/dist/analyzers/edge-relationships.js

@@ -0,0 +1,49 @@
+function edgePreferences(m) {
+  if (m.usage !== "verification_and_mapping")
+    return [];
+  const listed = m.conditions?.predicates;
+  return Array.isArray(listed) && listed.length ? listed.map((p, i) => {
+    if (typeof p == "string")
+      return { predicate: p, invert: !1 };
+    if (p && typeof p == "object" && typeof p.predicate == "string") {
+      const o = p, types = (v) => Array.isArray(v) ? v.filter((t) => typeof t == "string") : void 0, from = types(o.from_types), to = types(o.to_types);
+      return { predicate: o.predicate, invert: o.invert === !0, ...from ? { from_types: from } : {}, ...to ? { to_types: to } : {} };
+    }
+    throw new Error(`Edge mapping ${m.cbm_edge}: conditions.predicates[${i}] must be a predicate name or {predicate, invert}`);
+  }) : m.dr_relationship ? [{ predicate: m.dr_relationship, invert: m.directionality_transform === "invert" }] : [];
+}
+function typeAllowed(allowed, type) {
+  return !Array.isArray(allowed) || !allowed.length ? !0 : allowed.some((a) => typeof a == "string" && (a === type || a.endsWith(".*") && type.startsWith(a.slice(0, -1))));
+}
+function edgeAllowed(m, fromType, toType) {
+  const c = m.conditions ?? {};
+  return typeAllowed(c.from_types, fromType) && typeAllowed(c.to_types, toType);
+}
+function relationshipFor(m, fromType, toType, hasTriple) {
+  if (!edgeAllowed(m, fromType, toType))
+    return null;
+  for (const pref of edgePreferences(m)) {
+    if (!typeAllowed(pref.from_types, fromType) || !typeAllowed(pref.to_types, toType))
+      continue;
+    const [source, destination] = pref.invert ? [toType, fromType] : [fromType, toType], id = `${source}.${pref.predicate}.${destination}`;
+    if (hasTriple(id))
+      return { id, source, predicate: pref.predicate, destination, inverted: pref.invert };
+  }
+  return null;
+}
+function dedupeRelationships(items) {
+  const seen = /* @__PURE__ */ new Set();
+  return items.filter((x) => {
+    if (x.sourceId === x.destinationId)
+      return !1;
+    const key = `${x.sourceId}|${x.relationship.id}|${x.destinationId}`;
+    return seen.has(key) ? !1 : (seen.add(key), !0);
+  });
+}
+export {
+  dedupeRelationships,
+  edgeAllowed,
+  edgePreferences,
+  relationshipFor
+};
+//# sourceMappingURL=edge-relationships.js.map

package/dist/analyzers/edge-relationships.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/analyzers/edge-relationships.ts"],
+  "sourcesContent": ["/**\n * Turn a CBM edge between two classified symbols into a DR relationship.\n *\n * An edge mapping (spec/analyzers/<name>/edge-mapping.json) that creates relationships\n * (`usage: \"verification_and_mapping\"`) lists, in `conditions.predicates`, the predicates that can\n * express it in order of preference, each optionally inverted (the DR relationship runs against\n * the CBM edge). The relationship is the first catalog triple\n * `{source type}.{predicate}.{destination type}` that exists for the two element types the ends\n * were classified as; the relationship catalog stays the authority on which triples are valid.\n * Without `conditions.predicates` the mapping's own `dr_relationship` and\n * `directionality_transform` are the only preference. A preference may carry its own `from_types`\n * / `to_types`: it applies only between those types (CALLS from a test case is `tests`).\n *\n * `conditions.from_types` / `conditions.to_types`, when present, restrict the element types the\n * CBM edge's source and target may have (\"layer.type\", or \"layer.*\" for any type of a layer); an\n * edge between other types creates no relationship, whatever the catalog holds.\n *\n * Example: CALLS prefers depends-on, then uses, then accesses. A call from an\n * application.applicationfunction to another becomes\n * application.applicationfunction.depends-on.application.applicationfunction; a call from an\n * application.applicationservice to an application.dataobject has no depends-on or uses triple and\n * becomes application.applicationservice.accesses.application.dataobject.\n *\n * Callers pass only edges between two different accepted elements, and should collapse duplicates\n * with dedupeRelationships: CALLS, CALL_REFERENCE and USAGE can all link the same pair.\n */\nimport type { AnalyzerEdgeMapping } from \"./types.js\";\n\nexport interface EdgePreference {\n  predicate: string;\n  /** true when the DR relationship runs from the CBM edge's target to its source */\n  invert: boolean;\n  /** Only when the CBM edge's source is one of these types (\"layer.type\" or \"layer.*\"). */\n  from_types?: string[];\n  /** Only when the CBM edge's target is one of these types. */\n  to_types?: string[];\n}\n\nexport interface EdgeRelationship {\n  id: string;\n  source: string;\n  predicate: string;\n  destination: string;\n  inverted: boolean;\n}\n\n/** The predicates an edge mapping may use, in order of preference. */\nexport function edgePreferences(m: AnalyzerEdgeMapping): EdgePreference[] {\n  if (m.usage !== \"verification_and_mapping\") return [];\n  const listed = (m.conditions as { predicates?: unknown } | undefined)?.predicates;\n  if (Array.isArray(listed) && listed.length) {\n    return listed.map((p, i) => {\n      if (typeof p === \"string\") return { predicate: p, invert: false };\n      if (p && typeof p === \"object\" && typeof (p as { predicate?: unknown }).predicate === \"string\") {\n        const o = p as { predicate: string; invert?: unknown; from_types?: unknown; to_types?: unknown };\n        const types = (v: unknown) => (Array.isArray(v) ? v.filter((t): t is string => typeof t === \"string\") : undefined);\n        const from = types(o.from_types);\n        const to = types(o.to_types);\n        return { predicate: o.predicate, invert: o.invert === true, ...(from ? { from_types: from } : {}), ...(to ? { to_types: to } : {}) };\n      }\n      throw new Error(`Edge mapping ${m.cbm_edge}: conditions.predicates[${i}] must be a predicate name or {predicate, invert}`);\n    });\n  }\n  return m.dr_relationship ? [{ predicate: m.dr_relationship, invert: m.directionality_transform === \"invert\" }] : [];\n}\n\nfunction typeAllowed(allowed: unknown, type: string): boolean {\n  if (!Array.isArray(allowed) || !allowed.length) return true;\n  return allowed.some((a) => typeof a === \"string\" && (a === type || (a.endsWith(\".*\") && type.startsWith(a.slice(0, -1)))));\n}\n\n/** Whether an edge mapping allows an edge between these two element types (CBM direction). */\nexport function edgeAllowed(m: AnalyzerEdgeMapping, fromType: string, toType: string): boolean {\n  const c = (m.conditions ?? {}) as { from_types?: unknown; to_types?: unknown };\n  return typeAllowed(c.from_types, fromType) && typeAllowed(c.to_types, toType);\n}\n\n/**\n * The relationship a CBM edge `from \u2192 to` becomes, given the DR element types its ends were\n * classified as, or null when no preferred predicate has a catalog triple for that pair.\n */\nexport function relationshipFor(\n  m: AnalyzerEdgeMapping,\n  fromType: string,\n  toType: string,\n  hasTriple: (id: string) => boolean\n): EdgeRelationship | null {\n  if (!edgeAllowed(m, fromType, toType)) return null;\n  for (const pref of edgePreferences(m)) {\n    if (!typeAllowed(pref.from_types, fromType) || !typeAllowed(pref.to_types, toType)) continue;\n    const [source, destination] = pref.invert ? [toType, fromType] : [fromType, toType];\n    const id = `${source}.${pref.predicate}.${destination}`;\n    if (hasTriple(id)) return { id, source, predicate: pref.predicate, destination, inverted: pref.invert };\n  }\n  return null;\n}\n\n/**\n * One relationship per (source element, relationship id, destination element), keeping the first.\n * `items` carry the element ids of the two ends alongside the relationship.\n */\nexport function dedupeRelationships<T extends { sourceId: string; destinationId: string; relationship: EdgeRelationship }>(items: T[]): T[] {\n  const seen = new Set<string>();\n  return items.filter((x) => {\n    if (x.sourceId === x.destinationId) return false;\n    const key = `${x.sourceId}|${x.relationship.id}|${x.destinationId}`;\n    if (seen.has(key)) return false;\n    seen.add(key);\n    return true;\n  });\n}\n"],
+  "mappings": "AA+CM,SAAU,gBAAgB,GAAsB;AACpD,MAAI,EAAE,UAAU;AAA4B,WAAO,CAAA;AACnD,QAAM,SAAU,EAAE,YAAqD;AACvE,SAAI,MAAM,QAAQ,MAAM,KAAK,OAAO,SAC3B,OAAO,IAAI,CAAC,GAAG,MAAK;AACzB,QAAI,OAAO,KAAM;AAAU,aAAO,EAAE,WAAW,GAAG,QAAQ,GAAK;AAC/D,QAAI,KAAK,OAAO,KAAM,YAAY,OAAQ,EAA8B,aAAc,UAAU;AAC9F,YAAM,IAAI,GACJ,QAAQ,CAAC,MAAgB,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,MAAmB,OAAO,KAAM,QAAQ,IAAI,QAClG,OAAO,MAAM,EAAE,UAAU,GACzB,KAAK,MAAM,EAAE,QAAQ;AAC3B,aAAO,EAAE,WAAW,EAAE,WAAW,QAAQ,EAAE,WAAW,IAAM,GAAI,OAAO,EAAE,YAAY,KAAI,IAAK,CAAA,GAAK,GAAI,KAAK,EAAE,UAAU,GAAE,IAAK,CAAA,EAAG;IACpI;AACA,UAAM,IAAI,MAAM,gBAAgB,EAAE,QAAQ,2BAA2B,CAAC,mDAAmD;EAC3H,CAAC,IAEI,EAAE,kBAAkB,CAAC,EAAE,WAAW,EAAE,iBAAiB,QAAQ,EAAE,6BAA6B,SAAQ,CAAE,IAAI,CAAA;AACnH;AAEA,SAAS,YAAY,SAAkB,MAAY;AACjD,SAAI,CAAC,MAAM,QAAQ,OAAO,KAAK,CAAC,QAAQ,SAAe,KAChD,QAAQ,KAAK,CAAC,MAAM,OAAO,KAAM,aAAa,MAAM,QAAS,EAAE,SAAS,IAAI,KAAK,KAAK,WAAW,EAAE,MAAM,GAAG,EAAE,CAAC,EAAG;AAC3H;AAGM,SAAU,YAAY,GAAwB,UAAkB,QAAc;AAClF,QAAM,IAAK,EAAE,cAAc,CAAA;AAC3B,SAAO,YAAY,EAAE,YAAY,QAAQ,KAAK,YAAY,EAAE,UAAU,MAAM;AAC9E;AAMM,SAAU,gBACd,GACA,UACA,QACA,WAAkC;AAElC,MAAI,CAAC,YAAY,GAAG,UAAU,MAAM;AAAG,WAAO;AAC9C,aAAW,QAAQ,gBAAgB,CAAC,GAAG;AACrC,QAAI,CAAC,YAAY,KAAK,YAAY,QAAQ,KAAK,CAAC,YAAY,KAAK,UAAU,MAAM;AAAG;AACpF,UAAM,CAAC,QAAQ,WAAW,IAAI,KAAK,SAAS,CAAC,QAAQ,QAAQ,IAAI,CAAC,UAAU,MAAM,GAC5E,KAAK,GAAG,MAAM,IAAI,KAAK,SAAS,IAAI,WAAW;AACrD,QAAI,UAAU,EAAE;AAAG,aAAO,EAAE,IAAI,QAAQ,WAAW,KAAK,WAAW,aAAa,UAAU,KAAK,OAAM;EACvG;AACA,SAAO;AACT;AAMM,SAAU,oBAA2G,OAAU;AACnI,QAAM,OAAO,oBAAI,IAAG;AACpB,SAAO,MAAM,OAAO,CAAC,MAAK;AACxB,QAAI,EAAE,aAAa,EAAE;AAAe,aAAO;AAC3C,UAAM,MAAM,GAAG,EAAE,QAAQ,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa;AACjE,WAAI,KAAK,IAAI,GAAG,IAAU,MAC1B,KAAK,IAAI,GAAG,GACL;EACT,CAAC;AACH;",
+  "names": []
+}

package/dist/analyzers/extraction-plan.js

@@ -0,0 +1,541 @@
+import path from "node:path";
+import { toKebabCase } from "../utils/id-generator.js";
+import { changedInRange } from "./code-changes.js";
+import { dedupeRelationships, relationshipFor } from "./edge-relationships.js";
+import { FILE_JOINED_EDGES, parseRouteName, shortQualifiedName, symbolSpellings } from "./cards/extract.js";
+const REFERENCE_EDGES = /* @__PURE__ */ new Set(["USAGE", "IMPORTS", "CALLS"]);
+function refersToClass(refs, cls) {
+  if (!refs)
+    return !1;
+  const simple = cls.slice(cls.lastIndexOf(".") + 1);
+  return refs.has(cls) || refs.has(`${cls}.${simple}`) || refs.has(`${cls}.constructor`) || refs.has(`${cls}.__init__`);
+}
+function decisionKey(file, symbol) {
+  return `${file ?? ""}#${routeKey(symbol) ?? symbol}`;
+}
+function routePathOf(s, route) {
+  return s.routePath ?? route.path;
+}
+function sourceSymbolOf(s, project) {
+  const { card } = s, route = parseRouteName(card.name);
+  if (route)
+    return `${route.method} ${routePathOf(s, route)}`;
+  if (card.label === "Module")
+    return shortQualifiedName(s.qualifiedName, project);
+  if (card.label === "Method" && card.parent_class) {
+    const parent = card.parent_class.split(".").pop();
+    if (parent)
+      return `${parent}.${card.name}`;
+  }
+  return card.name;
+}
+function baseNameOf(s, project) {
+  const route = parseRouteName(s.card.name);
+  return route ? `${route.method} ${routePathOf(s, route).replace(/\{\}/g, "{param}")}` : s.card.label === "Module" ? (s.card.file_path || s.card.name).replace(/\.[^./]+$/, "") : sourceSymbolOf(s, project);
+}
+function modelAddName(name) {
+  const root = /^\s*([A-Z]+)\s+\/\s*$/.exec(name), out = root ? `${root[1]} root` : /[/{}]/.test(name) ? name.replace(/[./{}]+/g, " ").replace(/\s+/g, " ").trim() : name.replace(/([\w$)])\.(?=[A-Za-z_$])/g, "$1 ");
+  return out !== name ? out : void 0;
+}
+function extractedElementId(layer, type, name) {
+  const root = /^\s*([A-Z]+)\s+\/\s*$/.exec(name);
+  return `${layer}.${type}.${toKebabCase(root ? `${root[1]} root` : name.replace(/[./{}]+/g, " "))}`;
+}
+function describeDocstring(doc) {
+  if (!doc)
+    return;
+  const text = doc.replace(/^\s*\/\*\*?/, "").replace(/\*\/\s*$/, "").split(`
+`).map((l) => l.replace(/^\s*(\*|\/\/\/?|#)\s?/, "").trim()).join(`
+`).replace(/^["']{3}|["']{3}$/g, "").trim().split(/\n\s*\n/)[0].replace(/\s+/g, " ").trim();
+  if (!(!text || text.startsWith("@")))
+    return text.length > 280 ? `${text.slice(0, 277)}...` : text;
+}
+function deriveAttributes(layer, type, s) {
+  const key = `${layer}.${type}`, route = parseRouteName(s.card.name);
+  switch (key) {
+    case "api.operation": {
+      if (!route)
+        return { facts: {}, defaults: {} };
+      const p = routePathOf(s, route), segment = p.split("/").find((x) => x && !x.startsWith("{") && !x.startsWith(":")) ?? "default", words = p.replace(/[/{}:]+/g, " ").trim();
+      return {
+        facts: { http_method: route.method, http_path: p },
+        defaults: {
+          operationId: toKebabCase(`${route.method} ${words || "root"}`),
+          summary: `${route.method} ${p}`,
+          tags: segment
+        }
+      };
+    }
+    case "testing.testcasesketch":
+      return { facts: {}, defaults: { status: "automated" } };
+    case "application.applicationinterface":
+      return { facts: {}, defaults: { protocol: s.facts.decorator_names.includes("RestController") ? "REST" : "HTTP" } };
+    case "application.applicationcomponent":
+      return { facts: {}, defaults: { type: "internal" } };
+    case "application.applicationservice":
+      return { facts: {}, defaults: { serviceType: "synchronous" } };
+    case "data-model.objectschema":
+      return { facts: {}, defaults: { type: "object" } };
+    case "data-store.accesspattern": {
+      const entity = /Repository\s*<\s*([\w.]+)/.exec(s.card.source ?? s.card.signature ?? "")?.[1];
+      return { facts: {}, defaults: { patternType: "CUSTOM", ...entity ? { targetCollection: entity.split(".").pop() } : {} } };
+    }
+    default:
+      return { facts: {}, defaults: {} };
+  }
+}
+function codeLocations(e) {
+  return (e.sourceReference?.locations ?? []).filter((l) => typeof l.file == "string" && l.file).map((l) => ({ file: l.file.replace(/\\/g, "/").replace(/^\.\//, ""), ...l.symbol ? { symbol: l.symbol } : {} }));
+}
+function normPath(p) {
+  return p.replace(/\{[^}]*\}|:[A-Za-z_]\w*/g, "{}").replace(/\/+$/, "") || "/";
+}
+function indexExisting(graph) {
+  const bySymbol = /* @__PURE__ */ new Map(), byRouteSymbol = /* @__PURE__ */ new Map(), byRouteSymbolAnyFile = /* @__PURE__ */ new Map(), byRoute = /* @__PURE__ */ new Map(), byId = /* @__PURE__ */ new Map(), live = [], push = (m, k, e) => (m.get(k) ?? m.set(k, []).get(k)).push(e);
+  for (const e of graph.elements.values()) {
+    if (byId.set(e.id, e), e.status === "deleted")
+      continue;
+    live.push(e);
+    const locations = codeLocations(e);
+    for (const loc of locations) {
+      if (!loc.symbol)
+        continue;
+      push(bySymbol, `${loc.file}#${loc.symbol}`, e);
+      const route = routeKey(loc.symbol);
+      route && (push(byRouteSymbol, `${loc.file}#${route}`, e), push(byRouteSymbolAnyFile, route, e));
+    }
+    if (e.layer === "api" && e.type === "operation" && !locations.length) {
+      const method = e.attributes.http_method, p = e.attributes.http_path;
+      typeof method == "string" && typeof p == "string" && push(byRoute, `${method.toUpperCase()} ${normPath(p)}`, e);
+    }
+  }
+  return { bySymbol, byRouteSymbol, byRouteSymbolAnyFile, byRoute, byId, live };
+}
+function findBySymbol(index, file, spellings) {
+  for (const s of spellings)
+    if (file) {
+      const hit = index.bySymbol.get(`${file}#${s}`);
+      if (hit?.length)
+        return hit[0];
+    }
+}
+function hasSymbol(spellings, symbol) {
+  return !!spellings && spellings.has(symbol);
+}
+const LABEL_ORDER = ["Route", "Class", "Interface", "Type", "Enum", "Trait", "Struct", "Function", "Method", "Module"], KIND_ORDER = ["needs-attributes", "ambiguous", "narrowed", "no-rule", "unhandled-route"];
+function inLayers(layer, layers) {
+  return !layers || layers.has(layer);
+}
+function sortCards(cards) {
+  const rank = (l) => {
+    const i = LABEL_ORDER.indexOf(l);
+    return i < 0 ? LABEL_ORDER.length : i;
+  };
+  return cards.sort((a, b) => (a.changedInRange ? 0 : 1) - (b.changedInRange ? 0 : 1) || KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind) || rank(a.label) - rank(b.label) || (a.file ?? "").localeCompare(b.file ?? "") || a.qualifiedName.localeCompare(b.qualifiedName));
+}
+function cardOf(s, project, kind, reason, extra = {}, hunks, renamedTo) {
+  const { card } = s, doc = describeDocstring(card.docstring), name = modelAddName(baseNameOf(s, project)), ranges = hunks && card.file_path ? hunks.get(card.file_path) : void 0, changed = card.label === "Module" ? !!hunks && !!card.file_path && (ranges === "all" || !!renamedTo?.has(card.file_path)) : changedInRange(ranges, card.start_line, card.end_line);
+  return {
+    cardId: card.id,
+    kind,
+    label: card.label,
+    symbol: sourceSymbolOf(s, project),
+    ...changed ? { changedInRange: !0 } : {},
+    ...name ? { name } : {},
+    file: card.file_path,
+    lines: card.start_line !== null ? `${card.start_line}-${card.end_line ?? card.start_line}` : null,
+    qualifiedName: card.qualified_name,
+    ...card.signature ? { signature: card.signature.slice(0, 200) } : {},
+    ...doc ? { docstring: doc } : {},
+    ...s.facts.decorator_names.length ? { decorators: s.facts.decorator_names } : {},
+    candidates: [],
+    reason,
+    ...extra
+  };
+}
+function planElements(extraction, existing, options) {
+  const { project, config } = extraction, layers = options.layers?.length ? new Set(options.layers) : null, index = indexExisting(existing), taken = new Set(index.byId.keys()), plan = {
+    adds: [],
+    updates: [],
+    unchanged: 0,
+    modelled: 0,
+    rejected: 0,
+    skipped: 0,
+    outsideLayers: 0,
+    retyped: [],
+    undecided: [],
+    candidateDeletes: [],
+    elementOf: /* @__PURE__ */ new Map(),
+    descriptions: {}
+  }, matched = /* @__PURE__ */ new Set(), hunks = options.changes?.hunks, renamedTo = renameTargets(options.changes), cardFor = (s, kind, reason, extra = {}) => cardOf(s, project, kind, reason, extra, hunks, renamedTo), notElements = options.notElements ?? /* @__PURE__ */ new Set(), symbols = [...extraction.symbols].sort((a, b) => (a.card.file_path ?? "").localeCompare(b.card.file_path ?? "") || a.qualifiedName.localeCompare(b.qualifiedName)), claimed = /* @__PURE__ */ new Set(), matchOf = /* @__PURE__ */ new Map(), ambiguousWith = /* @__PURE__ */ new Map(), pick = (candidates, prefer) => {
+    if (!candidates?.length)
+      return;
+    const free = candidates.filter((e) => !claimed.has(e.id));
+    return free.length ? (prefer && free.find(prefer)) ?? free[0] : "claimed";
+  }, tryLookups = (s, lookups) => {
+    for (const lookup of lookups) {
+      const hit = lookup();
+      if (hit === "claimed") {
+        const owner = lookupOwner(s);
+        owner && ambiguousWith.set(s, owner);
+        continue;
+      }
+      if (hit) {
+        claimed.add(hit.id), matchOf.set(s, hit), ambiguousWith.delete(s);
+        return;
+      }
+    }
+  }, lookupOwner = (s) => {
+    const file = s.card.file_path, route = parseRouteName(s.card.name);
+    return (route ? [file ? index.byRouteSymbol.get(`${file}#${routeKey(s.card.name)}`) : index.byRouteSymbolAnyFile.get(routeKey(s.card.name)), index.byRoute.get(`${route.method} ${normPath(route.path)}`)] : [file ? index.bySymbol.get(`${file}#${s.card.name}`) : void 0]).find((k) => k?.length)?.[0]?.id;
+  }, strongSpellings = (s) => {
+    const symbol = sourceSymbolOf(s, project);
+    return [symbol, ...symbolSpellings(s.qualifiedName, s.card.name, project)].filter((sp, i, all) => all.indexOf(sp) === i && (sp === symbol || sp !== s.card.name));
+  };
+  for (const s of symbols) {
+    const file = s.card.file_path;
+    file && tryLookups(s, strongSpellings(s).map((sp) => () => pick(index.bySymbol.get(`${file}#${sp}`))));
+  }
+  for (const s of symbols) {
+    if (matchOf.has(s))
+      continue;
+    const { card, tier0 } = s, file = card.file_path, route = parseRouteName(card.name), lookups = [];
+    if (route) {
+      const key = routeKey(card.name), exact = (e) => e.attributes.http_path === route.path;
+      lookups.push(() => pick(file ? index.byRouteSymbol.get(`${file}#${key}`) : index.byRouteSymbolAnyFile.get(key))), lookups.push(() => pick(index.byRoute.get(`${route.method} ${normPath(route.path)}`), exact));
+    } else file && sourceSymbolOf(s, project) !== card.name && lookups.push(() => pick(index.bySymbol.get(`${file}#${card.name}`)));
+    if (tier0?.kind === "decide") {
+      const decided = tier0;
+      lookups.push(() => {
+        const byId = index.byId.get(extractedElementId(decided.layer, decided.type, baseNameOf(s, project)));
+        if (!(!byId || byId.status === "deleted" || byId.layer !== decided.layer || byId.type !== decided.type || codeLocations(byId).length))
+          return pick([byId]);
+      });
+    }
+    tryLookups(s, lookups);
+  }
+  for (const s of symbols) {
+    const { card, tier0 } = s, file = card.file_path, symbol = sourceSymbolOf(s, project), decided = tier0?.kind === "decide" ? tier0 : null, spellings = [symbol, ...symbolSpellings(s.qualifiedName, card.name, project)], match = matchOf.get(s);
+    if (!match && notElements.has(decisionKey(file, symbol))) {
+      plan.skipped++;
+      continue;
+    }
+    const ambiguous = !match && tier0?.kind !== "reject" ? ambiguousWith.get(s) : void 0;
+    if (ambiguous) {
+      if (decided && !inLayers(decided.layer, layers)) {
+        plan.outsideLayers++;
+        continue;
+      }
+      plan.undecided.push(cardFor(s, "ambiguous", `Its name also matches ${ambiguous}, which another symbol already matched. If it is a separate element, stage it under its own symbol; if it is that one, add this location to it.`, {
+        candidates: decided ? [`${decided.layer}.${decided.type}`] : tier0?.kind === "narrow" ? tier0.candidates.map((c) => `${c.layer}.${c.type ?? "*"}`) : [],
+        ...tier0 && tier0.kind !== "reject" ? { rule: tier0.rule } : {}
+      }));
+      continue;
+    }
+    if (match) {
+      if (matched.add(match.id), plan.elementOf.set(s.qualifiedName, match.id), !decided) {
+        plan.modelled++;
+        continue;
+      }
+      if (match.layer !== decided.layer || match.type !== decided.type) {
+        plan.retyped.push({ id: match.id, currentType: `${match.layer}.${match.type}`, decidedType: `${decided.layer}.${decided.type}`, rule: decided.rule, file, symbol });
+        continue;
+      }
+      if (!inLayers(decided.layer, layers)) {
+        plan.outsideLayers++;
+        continue;
+      }
+      const fields = changedFields(match, s, symbol, spellings, decided.layer, decided.type, options.extractedDescriptions ?? {});
+      typeof fields.description == "string" && (plan.descriptions[match.id] = fields.description), Object.keys(fields).length ? plan.updates.push({ id: match.id, layer: match.layer, fields, symbol: s }) : plan.unchanged++;
+      continue;
+    }
+    if (s.unhandled) {
+      if (layers && !layers.has("api")) {
+        plan.outsideLayers++;
+        continue;
+      }
+      plan.undecided.push(cardFor(s, "unhandled-route", "Nothing in this code handles this route (no handler, no file of its own): it is most likely a URL that tests or client code call. Model it as an api.operation only if this codebase serves it; otherwise reject it.", { candidates: ["api.operation"] }));
+      continue;
+    }
+    if (!tier0 || tier0.kind === "narrow") {
+      const candidates = tier0 ? tier0.candidates.map((c) => `${c.layer}.${c.type ?? "*"}`) : [], hint = config.labelDefaults[card.label];
+      if (!(layers ? tier0 ? tier0.candidates.some((c) => layers.has(c.layer)) : !!hint && layers.has(hint.split(".")[0]) : !0)) {
+        plan.outsideLayers++;
+        continue;
+      }
+      plan.undecided.push(tier0 ? cardFor(s, "narrowed", `Tier 0 rule ${tier0.rule} narrows it to these types; choosing needs judgment (Tier 1 is not wired).`, {
+        candidates: candidates.filter((c) => !layers || layers.has(c.split(".")[0])),
+        rule: tier0.rule
+      }) : cardFor(s, "no-rule", `No Tier-0 rule covers this ${card.label}: decide whether it is a model element, and which.`, {
+        ...hint ? { hint } : {}
+      }));
+      continue;
+    }
+    if (tier0.kind === "reject") {
+      plan.rejected++;
+      continue;
+    }
+    if (!inLayers(tier0.layer, layers)) {
+      plan.outsideLayers++;
+      continue;
+    }
+    const { facts, defaults } = deriveAttributes(tier0.layer, tier0.type, s), base = baseNameOf(s, project), name = uniqueName(base, s, tier0.layer, tier0.type, taken), id = extractedElementId(tier0.layer, tier0.type, name);
+    taken.add(id);
+    const description = describeDocstring(card.docstring);
+    description && (plan.descriptions[id] = description), plan.adds.push({
+      id,
+      layer: tier0.layer,
+      type: tier0.type,
+      name,
+      ...description ? { description } : {},
+      attributes: { ...defaults, ...facts },
+      ...file ? { sourceReference: { provenance: "extracted", locations: [{ file, symbol }] } } : {},
+      symbol: s,
+      rule: tier0.rule
+    }), plan.elementOf.set(s.qualifiedName, id);
+  }
+  return plan.candidateDeletes = candidateDeletes(extraction, index, matched, plan.adds, options, layers), plan.undecided = sortCards(plan.undecided), plan;
+}
+function renameTargets(changes) {
+  return new Set([...changes?.deleted.values() ?? []].filter((to) => !!to));
+}
+function needsAttributesCard(add, project, errors, hunks) {
+  return cardOf(add.symbol, project, "needs-attributes", `Tier 0 decided ${add.layer}.${add.type} (${add.rule}), but its attributes don't validate: ${errors.map((e) => e.replace(/^Element '[^']*':\s*/, "")).join("; ")}. Stage it with valid attributes (model_add with proposed.name gives it proposed.id), or reject it if it is not an element.`, {
+    candidates: [`${add.layer}.${add.type}`],
+    rule: add.rule,
+    proposed: { layer: add.layer, type: add.type, name: modelAddName(add.name) ?? add.name, id: add.id, attributes: add.attributes }
+  }, hunks);
+}
+function lineSpan(card) {
+  const m = /^(\d+)-(\d+)$/.exec(card.lines ?? "");
+  return m ? [Number(m[1]), Number(m[2])] : null;
+}
+function attributeChangedLines(cards, hunks) {
+  if (!hunks)
+    return cards;
+  const flagged = cards.filter((c) => c.changedInRange && c.file);
+  return cards.map((card) => {
+    if (!card.changedInRange || !card.file || card.label === "Module")
+      return card;
+    const ranges = hunks.get(card.file), own = lineSpan(card);
+    if (!ranges || ranges === "all" || !own)
+      return card;
+    const members = flagged.filter((m) => m !== card && m.file === card.file && m.qualifiedName.startsWith(card.qualifiedName + ".")).map(lineSpan).filter((span) => span !== null);
+    if (!members.length)
+      return card;
+    const inMember = (line) => members.some(([a, b]) => line >= a && line <= b);
+    if (ranges.some(([a, b, deletion]) => {
+      if (deletion)
+        return a >= own[0] && a < own[1] && !members.some(([m0, m1]) => a >= m0 && a < m1);
+      for (let line = Math.max(a, own[0]); line <= Math.min(b, own[1]); line++)
+        if (!inMember(line))
+          return !0;
+      return !1;
+    }))
+      return card;
+    const { changedInRange: _changed, ...rest } = card;
+    return rest;
+  });
+}
+function sortUndecided(cards) {
+  return sortCards(cards);
+}
+function uniqueName(base, s, layer, type, taken) {
+  const file = s.card.file_path ?? "", stem = path.posix.basename(file).replace(/\.[^.]+$/, ""), dir = path.posix.dirname(file), options = [base, `${stem} ${base}`, `${dir}/${stem} ${base}`, s.card.qualified_name];
+  for (const name of options)
+    if (!taken.has(extractedElementId(layer, type, name)))
+      return name;
+  for (let i = 2; ; i++) {
+    const name = `${s.card.qualified_name} ${i}`;
+    if (!taken.has(extractedElementId(layer, type, name)))
+      return name;
+  }
+}
+function changedFields(match, s, symbol, spellings, layer, type, extractedDescriptions) {
+  const fields = {}, file = s.card.file_path, locations = codeLocations(match), route = routeKey(s.card.name), names = (l) => !!l.symbol && (spellings.includes(l.symbol) || !!route && routeKey(l.symbol) === route);
+  if (file && !locations.some((l) => l.file === file && names(l))) {
+    const ref = match.sourceReference;
+    fields.source_reference = {
+      provenance: ref?.provenance ?? "extracted",
+      locations: [...ref?.locations ?? [], { file, symbol }],
+      ...ref?.repository ? { repository: ref.repository } : {}
+    };
+  }
+  const { facts } = deriveAttributes(layer, type, s);
+  for (const [k, v] of Object.entries(facts))
+    sameFact(k, match.attributes[k], v) || (fields[`attributes.${k}`] = v);
+  const description = describeDocstring(s.card.docstring), current = match.description ?? "";
+  return description && current !== description && (!current || current === extractedDescriptions[match.id]) && (fields.description = description), fields;
+}
+function sameFact(key, current, fromCode) {
+  if (typeof current == "string" && typeof fromCode == "string") {
+    if (key === "http_path")
+      return normPath(current) === normPath(fromCode);
+    if (key === "http_method")
+      return current.toUpperCase() === fromCode.toUpperCase();
+  }
+  return current === fromCode;
+}
+function candidateDeletes(extraction, index, matched, adds, options, layers) {
+  const routes = new Set(extraction.routes.map(routeKey).filter((k) => !!k)), fileSymbols = new Map(Object.entries(extraction.fileSymbols).map(([f, s]) => [f, new Set(s)])), addAt = /* @__PURE__ */ new Map();
+  for (const a of adds)
+    for (const l of a.sourceReference?.locations ?? [])
+      addAt.set(`${l.file}#${l.symbol ?? ""}`, a.id);
+  const out = [];
+  for (const e of index.live) {
+    if (matched.has(e.id) || !inLayers(e.layer, layers))
+      continue;
+    const locations = codeLocations(e);
+    if (!locations.length)
+      continue;
+    let gone = null, present = !1;
+    for (const loc of locations) {
+      const verdict = judgeLocation(loc, options, fileSymbols, routes, addAt);
+      verdict ? gone ??= verdict : present = !0;
+    }
+    gone && !present && out.push({ id: e.id, layer: e.layer, type: e.type, ...gone });
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+function judgeLocation(loc, options, fileSymbols, routes, addAt) {
+  const base = { file: loc.file, ...loc.symbol ? { symbol: loc.symbol } : {} }, changes = options.changes;
+  if (changes) {
+    if (changes.deleted.has(loc.file)) {
+      const to = changes.deleted.get(loc.file);
+      if (to) {
+        const replacedBy = loc.symbol ? addAt.get(`${to}#${loc.symbol}`) : void 0;
+        return { ...base, evidence: "file-renamed", detail: `${loc.file} was renamed to ${to} in the range`, ...replacedBy ? { replacedBy } : {} };
+      }
+      return { ...base, evidence: "file-deleted", detail: `${loc.file} was deleted in the range` };
+    }
+    if (!changes.changed.has(loc.file))
+      return null;
+  } else if (!options.fileExists(loc.file))
+    return { ...base, evidence: "file-missing", detail: `${loc.file} does not exist in the codebase` };
+  if (!loc.symbol)
+    return null;
+  const route = routeKey(loc.symbol);
+  if (route)
+    return routes.has(route) ? null : { ...base, evidence: "symbol-missing", detail: `the code has no route ${loc.symbol}` };
+  if (!/^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/.test(loc.symbol))
+    return null;
+  const symbols = fileSymbols.get(loc.file);
+  if (hasSymbol(symbols, loc.symbol))
+    return null;
+  const last = loc.symbol.split(".").pop().replace(/\$/g, "\\$"), names = (text2) => new RegExp(`(^|[^\\w$])${last}($|[^\\w$])`).test(text2), text = options.fileText?.(loc.file) ?? null;
+  if (text === null) {
+    if (!symbols)
+      return null;
+  } else if (names(text))
+    return null;
+  if (changes?.fileAtBase) {
+    const oldPath = [...changes.deleted].find(([, to]) => to === loc.file)?.[0], before = changes.fileAtBase(oldPath ?? loc.file);
+    return before === void 0 ? { ...base, evidence: "symbol-missing", detail: `${loc.file} has no ${loc.symbol} (not among its symbols, and the name is not in the file); its text at the start of the range couldn't be read` } : before === null || !names(before) ? {
+      ...base,
+      evidence: "reference-never-matched",
+      detail: `The model's reference to ${loc.symbol} matches nothing in ${loc.file}, and ${before === null ? "the file didn't exist" : "the file didn't have it either"} at the start of the range: the range didn't remove it, the reference was wrong before it`
+    } : { ...base, evidence: "symbol-missing", detail: `${loc.file} had ${loc.symbol} at the start of the range and doesn't now (not among its symbols, and the name is not in the file)` };
+  }
+  return { ...base, evidence: "symbol-missing", detail: `${loc.file} has no ${loc.symbol} (not among its symbols, and the name is not in the file)` };
+}
+function routeKey(symbol) {
+  const parsed = parseRouteName(symbol);
+  if (parsed)
+    return `${parsed.method} ${normPath(parsed.path)}`;
+  const m = /^([A-Z]+) (\/\S*)$/.exec(symbol);
+  return m ? `${m[1]} ${normPath(m[2])}` : null;
+}
+function planRelationships(extraction, existing, elementOf, elements, hasTriple, layers) {
+  const { project } = extraction, index = indexExisting(existing), inScope = new Set(extraction.symbols.map((s) => s.qualifiedName)), moduleOf = /* @__PURE__ */ new Map();
+  for (const s of extraction.symbols) {
+    const id = elementOf.get(s.qualifiedName);
+    s.card.label === "Module" && s.card.file_path && id && moduleOf.set(s.card.file_path, id);
+  }
+  const moduleIds = new Set(moduleOf.values()), layerSet = layers?.length ? new Set(layers) : null, mappings = new Map(extraction.config.edgeMappings.map((m) => [m.cbm_edge, m])), referencedIn = /* @__PURE__ */ new Map();
+  for (const e of extraction.edges) {
+    if (!REFERENCE_EDGES.has(e.type) || !e.from.file)
+      continue;
+    let refs = referencedIn.get(e.from.file);
+    refs || referencedIn.set(e.from.file, refs = /* @__PURE__ */ new Set()), refs.add(e.to.qualifiedName);
+  }
+  const direct = (qualifiedName, name, file) => {
+    const own = elementOf.get(qualifiedName);
+    if (own)
+      return own;
+    if (inScope.has(qualifiedName))
+      return;
+    const route = parseRouteName(name) ?? parseRouteName(qualifiedName);
+    if (route) {
+      const key = `${route.method} ${normPath(route.path)}`;
+      return (index.byRouteSymbolAnyFile.get(key)?.[0] ?? index.byRoute.get(key)?.[0])?.id;
+    }
+    return findBySymbol(index, file, symbolSpellings(qualifiedName, name, project))?.id;
+  }, resolve = (end, fileJoined) => {
+    const own = direct(end.qualifiedName, end.name, end.file);
+    if (own)
+      return { id: own };
+    if (fileJoined)
+      return end.file && moduleOf.has(end.file) ? { id: moduleOf.get(end.file) } : void 0;
+    if (parseRouteName(end.name))
+      return;
+    const cut = end.qualifiedName.lastIndexOf("."), parent = cut > 0 ? end.qualifiedName.slice(0, cut) : "";
+    if (!parent || parent === project)
+      return;
+    const id = direct(parent, parent.slice(parent.lastIndexOf(".") + 1), end.file);
+    return id ? { id, rolledUp: parent } : void 0;
+  }, found = [];
+  for (const edge of extraction.edges) {
+    const m = mappings.get(edge.type);
+    if (!m)
+      continue;
+    const fileJoined = FILE_JOINED_EDGES.has(edge.type), ra = resolve(edge.from, fileJoined), rb = resolve(edge.to, fileJoined);
+    if (!ra || !rb || ra.rolledUp && edge.to.qualifiedName.startsWith(ra.rolledUp + ".") || rb.rolledUp && edge.from.qualifiedName.startsWith(rb.rolledUp + "."))
+      continue;
+    const a = ra.id, b = rb.id;
+    if (a === b)
+      continue;
+    const ea = elements.get(a), eb = elements.get(b);
+    if (!ea || !eb || ea.layer === "testing" && rb.rolledUp && !moduleIds.has(b) && !(edge.from.file && refersToClass(referencedIn.get(edge.from.file), rb.rolledUp)))
+      continue;
+    const rel = relationshipFor(m, `${ea.layer}.${ea.type}`, `${eb.layer}.${eb.type}`, hasTriple);
+    if (!rel)
+      continue;
+    const [sourceId, destinationId] = rel.inverted ? [b, a] : [a, b];
+    found.push({ sourceId, destinationId, relationship: rel, edge: edge.type });
+  }
+  const relationships = [];
+  let alreadyPresent = 0;
+  for (const r of dedupeRelationships(found)) {
+    const source = elements.get(r.sourceId), target = elements.get(r.destinationId);
+    if (!(layerSet && !layerSet.has(source.layer) && !layerSet.has(target.layer))) {
+      if (existing.getRelationship(r.sourceId, r.relationship.predicate, r.destinationId)) {
+        alreadyPresent++;
+        continue;
+      }
+      relationships.push({
+        source: r.sourceId,
+        predicate: r.relationship.predicate,
+        target: r.destinationId,
+        sourceLayer: source.layer,
+        targetLayer: target.layer,
+        edge: r.edge
+      });
+    }
+  }
+  return relationships.sort((x, y) => x.source.localeCompare(y.source) || x.predicate.localeCompare(y.predicate) || x.target.localeCompare(y.target)), { relationships, alreadyPresent };
+}
+export {
+  attributeChangedLines,
+  decisionKey,
+  deriveAttributes,
+  describeDocstring,
+  extractedElementId,
+  modelAddName,
+  needsAttributesCard,
+  planElements,
+  planRelationships,
+  sameFact,
+  sortUndecided,
+  sourceSymbolOf
+};
+//# sourceMappingURL=extraction-plan.js.map