@topogram/cli 0.3.63 → 0.3.65

package/src/import/core/shared/api-routes.js

@@ -0,0 +1,221 @@
+import { canonicalCandidateTerm, idHintify, pluralizeCandidateTerm, slugify } from "./candidates.js";
+
+/**
+ * @param {string} pathValue
+ * @returns {any}
+ */
+export function normalizeOpenApiPath(pathValue) {
+  return String(pathValue || "")
+    .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "{$1}")
+    .replace(/\/+$/, "") || "/";
+}
+
+/**
+ * @param {string} pathValue
+ * @returns {any}
+ */
+export function normalizeEndpointPathForMatch(pathValue) {
+  const normalizedPath = normalizeOpenApiPath(pathValue);
+  const segments = normalizedPath
+    .split("/")
+    .filter(Boolean)
+    .map(/** @param {any} segment */ (segment) => {
+      if (/^\{[^}]+\}$/.test(segment)) {
+        return "{}";
+      }
+      return segment
+        .split("-")
+        .map(/** @param {any} part */ (part) => canonicalCandidateTerm(part))
+        .join("-");
+    });
+  return `/${segments.join("/")}`.replace(/\/+$/, "") || "/";
+}
+
+/**
+ * @param {string} pathValue
+ * @returns {any}
+ */
+export function nonParamEndpointSegments(pathValue) {
+  return normalizeOpenApiPath(pathValue)
+    .split("/")
+    .filter(Boolean)
+    .filter(/** @param {any} segment */ (segment) => segment !== "{}" && !/^\{[^}]+\}$/.test(segment))
+    .map(/** @param {any} segment */ (segment) => canonicalCandidateTerm(segment));
+}
+
+/**
+ * @param {string} pathValue
+ * @returns {any}
+ */
+function trimmedApiSegments(pathValue) {
+  const segments = nonParamEndpointSegments(pathValue);
+  if (segments[0] === "api" && segments.length > 1) {
+    return segments.slice(1);
+  }
+  if (segments[0] === "admin" && segments.length > 1) {
+    return segments.slice(1);
+  }
+  return segments;
+}
+
+/**
+ * @param {string} pathValue
+ * @param {any} options
+ * @returns {any}
+ */
+export function inferApiEntityIdFromPath(pathValue, options = {}) {
+  const tags = (options.tags || []).map(/** @param {any} tag */ (tag) => canonicalCandidateTerm(tag));
+  const summary = String(options.summary || "").toLowerCase();
+  const normalizedPath = normalizeOpenApiPath(pathValue);
+  const segments = trimmedApiSegments(normalizedPath);
+
+  if (/\/(login|signin|sign-in|signup|register)$/.test(normalizedPath) || tags.includes("authentication")) {
+    return "entity_account";
+  }
+  if (normalizedPath === "/me" || segments.includes("profile") || /profile/.test(summary)) {
+    return "entity_profile";
+  }
+  if (tags.includes("member") || tags.includes("members") || segments.includes("membership") || segments.includes("memberships") || segments.includes("member") || segments.includes("members")) {
+    return "entity_workspace-membership";
+  }
+  if (segments.includes("audit-log") || segments.includes("audit-logs")) {
+    return "entity_audit-log";
+  }
+  if (segments.includes("account") || segments.includes("accounts")) {
+    return "entity_account";
+  }
+  if (segments.includes("workspace") || segments.includes("workspaces")) {
+    return "entity_workspace";
+  }
+  const nestedResourceActions = new Set(["favorite", "follow", "feed", "stats", "role", "status", "login", "signin", "sign-in", "signup", "register", "search", "payment", "delivery"]);
+  const lastSegment = segments[segments.length - 1];
+  const resource = segments.length > 1 && lastSegment && !nestedResourceActions.has(lastSegment)
+    ? lastSegment
+    : (segments[0] || "item");
+  return `entity_${canonicalCandidateTerm(resource)}`;
+}
+
+/**
+ * @param {any} operation
+ * @returns {any}
+ */
+export function inferApiCapabilityIdFromOperation(operation) {
+  const method = String(operation.method || "").toUpperCase();
+  const pathValue = normalizeOpenApiPath(operation.path || "");
+  const summary = String(operation.summary || "").toLowerCase();
+  const tags = operation.tags || [];
+  const segments = trimmedApiSegments(pathValue);
+  const rawSegments = normalizeOpenApiPath(pathValue)
+    .split("/")
+    .filter(Boolean)
+    .filter(/** @param {any} segment */ (segment) => !/^\{[^}]+\}$/.test(segment));
+  const trimmedRawSegments = rawSegments[0] === "api" && rawSegments.length > 1
+    ? rawSegments.slice(1)
+    : rawSegments[0] === "admin" && rawSegments.length > 1
+      ? rawSegments.slice(1)
+      : rawSegments;
+  const hasPathParams = /\{[^}]+\}/.test(pathValue);
+  const entityStem = inferApiEntityIdFromPath(pathValue, { tags, summary }).replace(/^entity_/, "").replace(/-/g, "_");
+  const last = segments[segments.length - 1] || entityStem;
+  const rawLast = trimmedRawSegments[trimmedRawSegments.length - 1] || "";
+
+  if (/(^|\/)(login|signin|sign-in)$/.test(pathValue) || /(sign in|login)/.test(summary)) {
+    return `cap_sign_in_${entityStem}`;
+  }
+  if (/(^|\/)(signup|register)$/.test(pathValue) || /(sign up|signup|registration|register)/.test(summary)) {
+    return `cap_register_${entityStem}`;
+  }
+  if (/(^|\/)search\/\{[^}]+\}$/.test(pathValue) || /(search)/.test(summary)) {
+    return `cap_search_${pluralizeCandidateTerm(entityStem)}`;
+  }
+  if (pathValue === "/me") {
+    return `cap_get_${entityStem}`;
+  }
+  if (method === "GET" && /\/feed$/.test(pathValue)) {
+    return `cap_feed_${entityStem}`;
+  }
+  if (method === "POST" && /\/favorite$/.test(pathValue)) {
+    return `cap_favorite_${entityStem}`;
+  }
+  if (method === "DELETE" && /\/favorite$/.test(pathValue)) {
+    return `cap_unfavorite_${entityStem}`;
+  }
+  if (method === "POST" && /\/follow$/.test(pathValue)) {
+    return `cap_follow_${entityStem}`;
+  }
+  if (method === "DELETE" && /\/follow$/.test(pathValue)) {
+    return `cap_unfollow_${entityStem}`;
+  }
+  if (method === "POST" && /\/payment$/.test(pathValue)) {
+    return `cap_pay_${entityStem}`;
+  }
+  if (method === "POST" && /\/delivery$/.test(pathValue)) {
+    return `cap_delivery_${entityStem}`;
+  }
+
+  if ((method === "PATCH" || method === "PUT") && ["role", "status"].includes(last)) {
+    return `cap_update_${entityStem}_${last}`;
+  }
+  if (method === "GET" && last === "stats") {
+    return `cap_get_${entityStem}_stats`;
+  }
+
+  if (method === "GET" && segments.length <= 1 && !hasPathParams) {
+    const singularPath = rawLast && canonicalCandidateTerm(rawLast) === rawLast;
+    return singularPath ? `cap_get_${entityStem}` : `cap_list_${pluralizeCandidateTerm(entityStem)}`;
+  }
+  if (method === "GET" && segments.length <= 1 && hasPathParams) return `cap_get_${entityStem}`;
+  if (method === "GET" && segments.length > 1 && !["role", "status", "stats"].includes(last)) {
+    if (!/\{[^}]+\}$/.test(pathValue) && rawLast && canonicalCandidateTerm(rawLast) !== rawLast) {
+      return `cap_list_${pluralizeCandidateTerm(entityStem)}`;
+    }
+    if (segments.includes("member") || segments.includes("membership") || segments.includes("memberships")) {
+      return `cap_list_${pluralizeCandidateTerm(entityStem)}`;
+    }
+    return `cap_get_${entityStem}`;
+  }
+  if (method === "POST") return `cap_create_${entityStem}`;
+  if (method === "PATCH" || method === "PUT") return `cap_update_${entityStem}`;
+  if (method === "DELETE") return `cap_delete_${entityStem}`;
+  return `candidate_${String(operation.method || "unknown").toLowerCase()}_${slugify(pathValue)}`;
+}
+
+/**
+ * @param {import("./types.d.ts").ImportRouteRecord} route
+ * @returns {any}
+ */
+export function inferRouteCapabilityId(route) {
+  if (route.handler_hint) {
+    const genericHttpHandler = /^(get|post|put|patch|delete)$/i.test(route.handler_hint);
+    if (!genericHttpHandler) {
+      const normalizedHandler = route.handler_hint
+        .replace(/^(handle|on)/i, "")
+        .replace(/(handler|route|controller|action)$/i, "");
+      const handlerTokens = normalizedHandler
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map(/** @param {any} token */ (token) => token.toLowerCase());
+      if (handlerTokens.length > 0) {
+        return `cap_${handlerTokens.join("_")}`;
+      }
+    }
+  }
+  return inferApiCapabilityIdFromOperation(route);
+}
+
+/**
+ * @param {import("./types.d.ts").ImportRouteRecord} record
+ * @returns {any}
+ */
+export function inferCapabilityEntityId(record) {
+  if (record.entity_id) {
+    return record.entity_id;
+  }
+  const pathSegments = normalizeEndpointPathForMatch(record.endpoint?.path || "")
+    .split("/")
+    .filter(Boolean)
+    .filter(/** @param {any} segment */ (segment) => segment !== "{}");
+  const resourceSegment = pathSegments[0] || String(record.id_hint || "").replace(/^cap_(create|update|delete|get|list)_/, "");
+  return `entity_${idHintify(canonicalCandidateTerm(resourceSegment))}`;
+}

package/src/import/core/shared/candidates.js

@@ -0,0 +1,97 @@
+import {
+  canonicalCandidateTerm,
+  ensureTrailingNewline,
+  idHintify,
+  pluralizeCandidateTerm,
+  slugify,
+  titleCase
+} from "../../../text-helpers.js";
+
+export {
+  canonicalCandidateTerm,
+  ensureTrailingNewline,
+  idHintify,
+  pluralizeCandidateTerm,
+  slugify,
+  titleCase
+};
+
+/**
+ * @param {import("./types.d.ts").ImportCandidateRecord} arg1
+ * @returns {any}
+ */
+export function makeCandidateRecord(arg1) {
+  const {
+    kind,
+    idHint,
+    label,
+    confidence = "medium",
+    sourceKind,
+    sourceOfTruth = "imported",
+    provenance,
+    track = null,
+    ...payload
+  } = arg1;
+  const inferredTrack =
+    track ||
+    (["entity", "enum", "relation", "index"].includes(kind)
+      ? "db"
+      : kind === "capability"
+        ? "api"
+        : kind === "widget"
+          ? "ui"
+          : null);
+  return {
+    kind,
+    id_hint: idHint,
+    label,
+    confidence,
+    source_kind: sourceKind,
+    source_of_truth: sourceOfTruth,
+    provenance: Array.isArray(provenance) ? provenance : [provenance].filter(Boolean),
+    track: inferredTrack,
+    ...payload
+  };
+}
+
+/**
+ * @param {import("./types.d.ts").ImportCandidateRecord[]} records
+ * @param {any} keyFn
+ * @returns {any}
+ */
+export function dedupeCandidateRecords(records, keyFn) {
+  const seen = new Map();
+  for (const record of records) {
+    const key = keyFn(record);
+    const recordProvenance = Array.isArray(record.provenance) ? record.provenance : [record.provenance].filter(Boolean);
+    if (!seen.has(key)) {
+      seen.set(key, { ...record, provenance: recordProvenance });
+      continue;
+    }
+    const current = seen.get(key);
+    const currentProvenance = Array.isArray(current.provenance) ? current.provenance : [current.provenance].filter(Boolean);
+    current.provenance = [...new Set([...currentProvenance, ...recordProvenance])];
+  }
+  return [...seen.values()];
+}
+
+/**
+ * @param {any} typeName
+ * @returns {any}
+ */
+export function normalizePrismaType(typeName) {
+  const normalized = String(typeName || "").toLowerCase();
+  switch (normalized) {
+    case "string": return "string";
+    case "int": return "int";
+    case "bigint": return "bigint";
+    case "float": return "float";
+    case "decimal": return "decimal";
+    case "boolean":
+    case "bool": return "boolean";
+    case "datetime": return "datetime";
+    case "bytes": return "bytes";
+    case "json": return "json";
+    default: return typeName;
+  }
+}

package/src/import/core/shared/files.js

@@ -0,0 +1,177 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { relativeTo } from "../../../path-helpers.js";
+
+export const DEFAULT_IGNORED_DIRS = new Set([
+  ".git",
+  ".next",
+  ".turbo",
+  ".yarn",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "tmp"
+]);
+
+/**
+ * @param {string} filePath
+ * @returns {any}
+ */
+export function readTextIfExists(filePath) {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : null;
+}
+
+/**
+ * @param {string} filePath
+ * @returns {any}
+ */
+export function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+/**
+ * @param {string} rootDir
+ * @param {(filePath: any) => boolean} predicate
+ * @param {any} options
+ * @returns {any[]}
+ */
+export function listFilesRecursive(rootDir, predicate = () => true, options = {}) {
+  if (!fs.existsSync(rootDir)) {
+    return [];
+  }
+  const ignoredDirs = options.ignoredDirs || DEFAULT_IGNORED_DIRS;
+  const files = /** @type {any[]} */ ([]);
+  const walk = /** @param {any} currentDir */ (currentDir) => {
+    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+      const childPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (ignoredDirs.has(entry.name)) {
+          continue;
+        }
+        walk(childPath);
+        continue;
+      }
+      if (entry.isFile() && predicate(childPath)) {
+        files.push(childPath);
+      }
+    }
+  };
+  walk(rootDir);
+  return files.sort();
+}
+
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @returns {any}
+ */
+export function importSearchRoots(paths) {
+  return [...new Set([paths.workspaceRoot, paths.topogramRoot].filter(Boolean))];
+}
+
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {string} filePath
+ * @returns {any}
+ */
+export function normalizeImportRelativePath(paths, filePath) {
+  return relativeTo(paths.repoRoot, filePath);
+}
+
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {string} filePath
+ * @param {any} kind
+ * @returns {any}
+ */
+export function canonicalSourceRank(paths, filePath, kind) {
+  const relativePath = normalizeImportRelativePath(paths, filePath);
+  const normalizedPath = relativePath.replaceAll(path.sep, "/");
+  const penalties = [
+    { pattern: /\/apps\/local-stack\//, weight: 80 },
+    { pattern: /\/artifacts\/environment\//, weight: 60 },
+    { pattern: /\/artifacts\/deploy\//, weight: 60 },
+    { pattern: /\/artifacts\/compile-check\//, weight: 50 },
+    { pattern: /\/artifacts\/db-lifecycle\//, weight: 50 },
+    { pattern: /\/artifacts\/migrations\//, weight: 40 }
+  ];
+
+  let rank = 100;
+  if (kind === "prisma") {
+    if (/\/prisma\/schema\.prisma$/i.test(normalizedPath) && !normalizedPath.includes("/artifacts/")) {
+      rank = 0;
+    } else if (/\/apps\/backend\/prisma\/schema\.prisma$/i.test(normalizedPath)) {
+      rank = 0;
+    } else if (/\/artifacts\/prisma\/schema\.prisma$/i.test(normalizedPath)) {
+      rank = 10;
+    }
+  } else if (kind === "sql") {
+    if (/\/db\/schema\.sql$/i.test(normalizedPath) || /\/schema\.sql$/i.test(normalizedPath)) {
+      rank = 0;
+    } else if (/\/artifacts\/db\/.+\.sql$/i.test(normalizedPath)) {
+      rank = 10;
+    } else if (/migration/i.test(path.basename(normalizedPath))) {
+      rank = 30;
+    }
+  } else if (kind === "openapi") {
+    if (/\/artifacts\/openapi\/openapi\.(json|ya?ml)$/i.test(normalizedPath)) {
+      rank = 0;
+    } else if (/\/openapi\.(json|ya?ml)$/i.test(normalizedPath) || /\/swagger\.(json|ya?ml)$/i.test(normalizedPath)) {
+      rank = 10;
+    }
+  }
+
+  for (const penalty of penalties) {
+    if (penalty.pattern.test(normalizedPath)) {
+      rank += penalty.weight;
+    }
+  }
+  return rank;
+}
+
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {any} files
+ * @param {any} kind
+ * @returns {any}
+ */
+export function selectPreferredImportFiles(paths, files, kind) {
+  if (files.length === 0) {
+    return [];
+  }
+  const rankedFiles = files.map(/** @param {string} filePath */ (filePath) => ({
+    filePath,
+    rank: canonicalSourceRank(paths, filePath, kind)
+  }));
+  const bestRank = Math.min(...rankedFiles.map(/** @param {any} entry */ (entry) => entry.rank));
+  return rankedFiles
+    .filter(/** @param {any} entry */ (entry) => entry.rank === bestRank)
+    .map(/** @param {any} entry */ (entry) => entry.filePath)
+    .sort();
+}
+
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {any} predicate
+ * @returns {any}
+ */
+export function findImportFiles(paths, predicate) {
+  const files = new Set();
+  for (const rootDir of importSearchRoots(paths)) {
+    for (const filePath of listFilesRecursive(rootDir, predicate)) {
+      if (
+        filePath.includes(`${path.sep}candidates${path.sep}`) ||
+        filePath.includes(`${path.sep}docs-generated${path.sep}`) ||
+        filePath.includes(`${path.sep}topogram${path.sep}tests${path.sep}fixtures${path.sep}expected${path.sep}`)
+      ) {
+        continue;
+      }
+      files.add(filePath);
+    }
+  }
+  return [...files].sort();
+}