@rebasepro/server-postgresql 0.0.1-canary.c53f5db → 0.0.1-canary.cbdd980

package/src/schema/introspect-db-logic.ts

@@ -6,6 +6,7 @@
  * no process.exit.  It is imported by introspect-db.ts (the CLI entry-point)
  * and consumed directly by tests.
  */
+import { inferPropertyFromData } from "./introspect-db-inference";
 
 // ── Typed interfaces for SQL query results ────────────────────────────
 
@@ -254,6 +255,252 @@ export function identifyJoinTables(tablesMap: Map<string, TableMeta>): Set<strin
     return joinTables;
 }
 
+// ── Property ordering heuristics ──────────────────────────────────────
+
+/**
+ * Property metadata used to compute display priority.
+ * Keeps computePropertyPriority free of any TableMeta coupling.
+ */
+export interface PropertyOrderingContext {
+    /** The resolved Rebase property type (e.g. "string", "number", "date", "relation"). */
+    propType: string;
+    /** Whether this column is a primary key. */
+    isPk: boolean;
+    /** Whether this column is an enum (USER-DEFINED with matching values). */
+    isEnum: boolean;
+    /** Whether this is a storage/file-upload field (detected from column name). */
+    isStorage: boolean;
+    /** The PostgreSQL data_type (e.g. "text", "character varying", "jsonb"). */
+    pgDataType: string;
+    /** The original column index in PostgreSQL (for stable tiebreaking). */
+    originalIndex: number;
+}
+
+// — Tier 0: Identity (0–9) ————————————————————————————————————————————
+const IDENTITY_EXACT: Record<string, number> = {
+    id: 0,
+    uuid: 1,
+    _id: 2,
+};
+
+// — Tier 1: Title / Name — the "display column" (10–19) ———————————————
+const TITLE_EXACT: Record<string, number> = {
+    name: 10,
+    title: 11,
+    label: 12,
+    display_name: 13,
+    displayname: 13,
+    headline: 14,
+    subject: 15,
+    heading: 16,
+};
+
+// — Tier 2: Human identity fields (20–29) —————————————————————————————
+const HUMAN_IDENTITY_EXACT: Record<string, number> = {
+    first_name: 20,
+    firstname: 20,
+    last_name: 21,
+    lastname: 21,
+    full_name: 22,
+    fullname: 22,
+    given_name: 22,
+    family_name: 23,
+    middle_name: 24,
+    username: 25,
+    user_name: 25,
+    email: 26,
+    email_address: 26,
+    phone: 27,
+    phone_number: 27,
+    mobile: 27,
+};
+
+// — Tier 3: Core descriptors (30–39) ——————————————————————————————————
+const DESCRIPTOR_EXACT: Record<string, number> = {
+    slug: 30,
+    code: 31,
+    sku: 32,
+    reference: 33,
+    ref: 33,
+    type: 34,
+    kind: 34,
+    status: 35,
+    state: 35,
+    role: 36,
+    category: 37,
+    group: 38,
+    priority: 39,
+    order: 39,
+    sort_order: 39,
+    position: 39,
+};
+
+// — Tier 12: System timestamps (120–129) ——————————————————————————————
+const SYSTEM_TIMESTAMP_EXACT: Record<string, number> = {
+    created_at: 120,
+    createdat: 120,
+    creation_date: 120,
+    inserted_at: 121,
+    updated_at: 122,
+    updatedat: 122,
+    modified_at: 122,
+    last_modified: 122,
+    deleted_at: 123,
+    deletedat: 123,
+    archived_at: 124,
+};
+
+// — Pattern-based rules for partial matches ———————————————————————————
+const TITLE_PATTERNS = ["name", "title", "label"];
+const LONG_TEXT_NAMES = new Set(["description", "summary", "excerpt", "abstract", "overview", "bio", "biography", "about"]);
+const RICH_CONTENT_NAMES = new Set(["content", "body", "html", "markup", "text", "article_body", "post_body"]);
+const MEDIA_PATTERNS = ["image", "avatar", "photo", "logo", "cover", "thumbnail", "banner", "icon", "picture", "poster"];
+const JSON_MAP_NAMES = new Set(["metadata", "meta", "config", "configuration", "settings", "options", "preferences", "data", "payload", "attributes", "extra", "additional_info"]);
+
+/**
+ * Compute a numeric priority score for a property.
+ * Lower scores appear first in the generated `propertiesOrder` array.
+ *
+ * The system uses 14 tiers (0–139), with the original column index
+ * added as a fractional tiebreaker (originalIndex / 10000) to
+ * guarantee stable ordering within the same tier.
+ *
+ * Pure function — no side effects.
+ */
+export function computePropertyPriority(
+    columnName: string,
+    ctx: PropertyOrderingContext,
+): number {
+    // Normalize camelCase/PascalCase to snake_case, then lowercase
+    const col = columnName.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+    const tiebreaker = ctx.originalIndex / 10000;
+
+    // ── Tier 0: Primary key identity fields
+    if (ctx.isPk) {
+        const exactScore = IDENTITY_EXACT[col];
+        return (exactScore ?? 5) + tiebreaker;
+    }
+
+    // ── Tier 12: System timestamps (check early to prevent false matches)
+    const systemTs = SYSTEM_TIMESTAMP_EXACT[col];
+    if (systemTs !== undefined) {
+        return systemTs + tiebreaker;
+    }
+
+    // ── Tier 1: Title / Name exact matches
+    const titleExact = TITLE_EXACT[col];
+    if (titleExact !== undefined) {
+        return titleExact + tiebreaker;
+    }
+
+    // ── Tier 2: Human identity exact matches
+    const humanExact = HUMAN_IDENTITY_EXACT[col];
+    if (humanExact !== undefined) {
+        return humanExact + tiebreaker;
+    }
+
+    // ── Tier 3: Core descriptor exact matches
+    const descriptorExact = DESCRIPTOR_EXACT[col];
+    if (descriptorExact !== undefined) {
+        return descriptorExact + tiebreaker;
+    }
+
+    // ── Tier 1b: Title-like partial matches (e.g. "product_name", "page_title")
+    // Score 17–19 so they rank after exact matches but still in tier 1.
+    for (const pattern of TITLE_PATTERNS) {
+        if (col.includes(pattern) && col !== pattern) {
+            return 17 + tiebreaker;
+        }
+    }
+
+    // ── Tier 9: Media / file upload fields (check before general strings)
+    if (ctx.isStorage) {
+        return 90 + tiebreaker;
+    }
+    for (const pattern of MEDIA_PATTERNS) {
+        if (col.includes(pattern)) {
+            return 91 + tiebreaker;
+        }
+    }
+    if (col.endsWith("_url") || col.endsWith("_uri") || col.endsWith("_link")) {
+        return 92 + tiebreaker;
+    }
+
+    // ── Tier 7: Long text fields
+    if (LONG_TEXT_NAMES.has(col)) {
+        return 70 + tiebreaker;
+    }
+
+    // ── Tier 8: Rich content fields
+    if (RICH_CONTENT_NAMES.has(col)) {
+        return 80 + tiebreaker;
+    }
+
+    // ── Tier 10: JSON / Map types
+    if (ctx.propType === "map") {
+        return JSON_MAP_NAMES.has(col) ? 100 + tiebreaker : 105 + tiebreaker;
+    }
+
+    // ── Tier 11: Array types
+    if (ctx.propType === "array") {
+        return 110 + tiebreaker;
+    }
+
+    // ── Tier 6: Owning relations
+    if (ctx.propType === "relation") {
+        return 60 + tiebreaker;
+    }
+
+    // ── Tier 4: Short text, enums, booleans — "quick glance" fields
+    if (ctx.isEnum) {
+        return 40 + tiebreaker;
+    }
+    if (ctx.propType === "boolean") {
+        return 45 + tiebreaker;
+    }
+    if (ctx.propType === "string" && ctx.pgDataType !== "text") {
+        // Short string (varchar, char, uuid that's not a PK)
+        return 42 + tiebreaker;
+    }
+
+    // ── Tier 5: Numbers & user-facing dates
+    if (ctx.propType === "number") {
+        return 50 + tiebreaker;
+    }
+    if (ctx.propType === "date") {
+        // A date that isn't a system timestamp (already handled above)
+        return 55 + tiebreaker;
+    }
+
+    // ── Tier 7b: text data_type that didn't match long-text names
+    if (ctx.propType === "string" && ctx.pgDataType === "text") {
+        return 75 + tiebreaker;
+    }
+
+    // ── Tier 13: Fallback / unknown
+    return 130 + tiebreaker;
+}
+
+/**
+ * Sort a `propertiesOrder` array using the priority heuristic.
+ * Returns a new sorted array; does not mutate the input.
+ *
+ * @param entries - Array of { key, columnName, propType, ... } objects
+ *                  carrying the information needed to compute priority.
+ */
+export interface PropertyOrderEntry {
+    /** The property key in the generated collection (may differ from columnName for relations). */
+    key: string;
+    /** The ordering context for this property. */
+    ctx: PropertyOrderingContext;
+}
+
+export function sortPropertiesOrder(entries: PropertyOrderEntry[]): string[] {
+    return [...entries]
+        .sort((a, b) => computePropertyPriority(a.key, a.ctx) - computePropertyPriority(b.key, b.ctx))
+        .map((e) => e.key);
+}
+
 // ── Generate collection file content ──────────────────────────────────
 
 export interface GeneratedFile {
@@ -273,6 +520,7 @@ export function generateCollectionFile(
     joinTables: Set<string>,
     tablesMap: Map<string, TableMeta>,
     enumMap: Map<string, string[]>,
+    sampleData?: Record<string, unknown>[],
 ): string {
     const collectionName = humanize(tableName);
     const singular = singularize(collectionName);
@@ -281,7 +529,10 @@ export function generateCollectionFile(
     const imports = new Set<string>(['import { PostgresCollection } from "@rebasepro/types";']);
 
     let propsOutput = ``;
-    const propertiesOrder: string[] = [];
+    let relationsOutput = ``;
+    const orderEntries: PropertyOrderEntry[] = [];
+    const propertyBlocks = new Map<string, string>();
+    let columnIndex = 0;
 
     // Detect composite primary keys
     const isCompositePk = meta.pks.length > 1;
@@ -289,9 +540,10 @@ export function generateCollectionFile(
     // Map columns
     for (const col of meta.columns) {
         // Skip foreign keys since we handle them as relations
-        if (meta.fks.some((fk) => fk.column_name === col.column_name)) continue;
+        // Exception: Do not skip if it's part of the primary key!
+        if (meta.fks.some((fk) => fk.column_name === col.column_name) && !meta.pks.includes(col.column_name)) continue;
 
-        propertiesOrder.push(col.column_name);
+        const currentIndex = columnIndex++;
 
         // Check if this column uses a PostgreSQL enum type
         const colEnumValues = enumMap.get(col.udt_name);
@@ -302,92 +554,144 @@ export function generateCollectionFile(
 
         const colNameLower = col.column_name.toLowerCase();
 
-        // Enum values — generate real enumValues from the PG enum
+        // ── Data Inference Engine ────────────────────────────────────────────
+        let finalPropType = propType;
+        let inferenceExtra = "";
+        
+        if (!isEnumColumn && sampleData && sampleData.length > 0) {
+            const values = sampleData.map(r => r[col.column_name]);
+            const inferred = inferPropertyFromData(col.column_name, col.data_type, propType, values, meta.pks.includes(col.column_name));
+            if (inferred.propType) finalPropType = inferred.propType;
+            if (inferred.extra) inferenceExtra = inferred.extra;
+        }
+
+        // Enum values — generate real enum from the PG enum
         if (isEnumColumn && colEnumValues) {
             const enumEntries = colEnumValues
                 .map((v) => `{ id: "${v}", label: "${humanize(v)}" }`)
                 .join(", ");
-            extra = `\n            enumValues: [${enumEntries}],`;
+            extra += `\n            enum: [${enumEntries}],`;
         }
 
         // Date auto-value heuristics
-        if (propType === "date") {
+        if (finalPropType === "date") {
             if (colNameLower === "created_at" || colNameLower === "createdat") {
-                extra = `\n            autoValue: "on_create",\n            readOnly: true,\n            hideFromCollection: true,`;
+                extra += `\n            autoValue: "on_create",\n            ui: {\n                readOnly: true,\n                hideFromCollection: true\n            },`;
             } else if (colNameLower === "updated_at" || colNameLower === "updatedat") {
-                extra = `\n            autoValue: "on_update",\n            readOnly: true,\n            hideFromCollection: true,`;
+                extra += `\n            autoValue: "on_update",\n            ui: {\n                readOnly: true,\n                hideFromCollection: true\n            },`;
             } else if (col.column_default && (col.column_default.includes("now()") || col.column_default.includes("CURRENT_TIMESTAMP"))) {
-                extra = `\n            autoValue: "on_create",\n            readOnly: true,`;
+                extra += `\n            autoValue: "on_create",\n            ui: {\n                readOnly: true\n            },`;
             }
         }
 
-        // Array/Map heuristics
-        if (propType === "array") {
+        // Array/Map heuristics (Fallback if not inferred)
+        if (finalPropType === "array" && !inferenceExtra.includes("of: {")) {
             let innerType = "string";
             if (col.udt_name.startsWith("_")) {
                 const baseType = col.udt_name.substring(1);
-                // Simple recursive check or hardcoded for inner type:
-                // We'll just call mapPgType on the baseType
                 innerType = mapPgType(baseType);
             }
-            extra = `\n            of: { type: "${innerType}" },`;
-        } else if (propType === "map") {
-            extra = `\n            keyValue: true,`;
+            extra += `\n            of: { name: "${humanize(col.column_name)} Item", type: "${innerType}" },`;
+        } else if (finalPropType === "map" && !inferenceExtra.includes("keyValue: true") && !inferenceExtra.includes("properties: {")) {
+            extra += `\n            keyValue: true,`;
         }
 
-        // String sub-type heuristics (skip if already handled as enum)
-        if (propType === "string" && !isEnumColumn) {
-            if (colNameLower.includes("image") || colNameLower.includes("avatar") || colNameLower.includes("photo") || colNameLower.includes("logo") || colNameLower.includes("cover")) {
-                extra = `\n            storage: {\n                storagePath: "${tableName}/${col.column_name}"\n            },`;
+        // String sub-type heuristics (Fallback if not handled by inference or enum)
+        if (finalPropType === "string" && !isEnumColumn && !inferenceExtra) {
+            const isUrl = colNameLower.endsWith("_url") || colNameLower.endsWith("_uri") || colNameLower.endsWith("_link");
+            const isMedia = colNameLower.includes("image") || colNameLower.includes("avatar") || colNameLower.includes("photo") || colNameLower.includes("logo") || colNameLower.includes("cover");
+
+            if (isMedia) {
+                extra += `\n            storage: {\n                storagePath: "${tableName}/${col.column_name}"\n            },`;
+            } else if (isUrl) {
+                extra += `\n            ui: {\n                url: true\n            },`;
             } else if (colNameLower === "description" || colNameLower === "summary" || colNameLower === "excerpt") {
-                extra = `\n            multiline: true,`;
+                extra += `\n            multiline: true,`;
             } else if (colNameLower === "content" || colNameLower === "body") {
-                extra = `\n            multiline: true,\n            markdown: true,`;
+                extra += `\n            multiline: true,\n            markdown: true,`;
             } else if (col.data_type === "text") {
-                extra = `\n            multiline: true,`;
+                extra += `\n            multiline: true,`;
             }
         }
+        
+        // Append inference results
+        if (inferenceExtra) {
+            extra += inferenceExtra;
+            if (!extra.endsWith(",")) extra += ",";
+        }
 
-        // Identify IDs
+        // Identify IDs (unless already inferred as UUID/CUID by inferenceEngine)
         if (meta.pks.includes(col.column_name)) {
             if (isCompositePk) {
                 extra += `\n            // Part of composite primary key (${meta.pks.join(", ")})`;
-            } else if (propType === "number") {
+            } else if (finalPropType === "number" && !inferenceExtra.includes("isId:")) {
                 extra += `\n            isId: "increment",`;
-            } else if (col.data_type.toLowerCase() === "uuid") {
+            } else if (col.data_type.toLowerCase() === "uuid" && !inferenceExtra.includes("isId:")) {
                 extra += `\n            isId: "uuid",`;
-            } else {
+            } else if (!inferenceExtra.includes("isId:")) {
                 extra += `\n            isId: "uuid", // Verify if this is a UUID or CUID`;
             }
         }
 
         if (col.is_nullable === "NO" && !meta.pks.includes(col.column_name) && !col.column_default) {
-            extra += `\n            validation: {\n                required: true\n            },`;
+            if (extra.includes("validation: {")) {
+                extra = extra.replace("validation: {", "validation: {\n                required: true,");
+            } else {
+                extra += `\n            validation: {\n                required: true\n            },`;
+            }
         }
 
         const humanName = humanize(col.column_name);
 
-        propsOutput += `
+        orderEntries.push({
+            key: col.column_name,
+            ctx: {
+                propType: finalPropType,
+                isPk: meta.pks.includes(col.column_name),
+                isEnum: isEnumColumn,
+                isStorage: extra.includes("storage: {") || inferenceExtra.includes("storage: {"),
+                pgDataType: col.data_type,
+                originalIndex: currentIndex,
+            },
+        });
+
+        propertyBlocks.set(col.column_name, `
         ${col.column_name}: {
             name: "${humanName}",
-            type: "${propType}",${extra}
-        },`;
+            columnName: "${col.column_name}",
+            type: "${finalPropType}",${extra}
+        },`);
     }
 
     // Map Owning Relations (from this table's FKs to other tables)
     for (const fk of meta.fks) {
         const targetTableName = fk.foreign_table_name;
         if (!joinTables.has(targetTableName)) {
-            const relName = fk.column_name.replace(/_id$/, "");
+            let relName = fk.column_name.replace(/_id$/, "");
+            if (meta.pks.includes(fk.column_name) && relName === fk.column_name) {
+                // If the FK is also the PK and its name doesn't imply a relation (like "id"),
+                // use the target table name to avoid conflicting with the PK property.
+                relName = targetTableName;
+            }
             // Push the relation property key, not the FK column name
-            propertiesOrder.push(relName);
+            orderEntries.push({
+                key: relName,
+                ctx: {
+                    propType: "relation",
+                    isPk: false,
+                    isEnum: false,
+                    isStorage: false,
+                    pgDataType: "",
+                    originalIndex: columnIndex++,
+                },
+            });
 
             const targetCollectionCamel = toCollectionVarName(targetTableName);
             imports.add(`import ${targetCollectionCamel} from "./${targetTableName}";`);
 
             const relHumanName = humanize(relName);
 
-            propsOutput += `
+            propertyBlocks.set(relName, `
         ${relName}: {
             name: "${relHumanName}",
             type: "relation",
@@ -396,26 +700,24 @@ export function generateCollectionFile(
             direction: "owning",
             localKey: "${fk.column_name}",
             // mapped from foreign key: ${fk.column_name} -> ${targetTableName}(${fk.foreign_column_name})
-        },`;
+        },`);
         }
     }
 
     // Map Inverse Relations (1-to-many where OTHER table points to THIS table)
+    // These go into the `relations` array so they render as subcollection tabs.
     const inverseFks = allFks.filter((fk) => fk.foreign_table_name === tableName && !joinTables.has(fk.table_name));
     for (const fk of inverseFks) {
         const sourceTableName = fk.table_name;
-        propertiesOrder.push(sourceTableName);
 
         const targetCollectionCamel = toCollectionVarName(sourceTableName);
         imports.add(`import ${targetCollectionCamel} from "./${sourceTableName}";`);
 
         const inverseRelName = fk.column_name.replace(/_id$/, "");
-        const relHumanName = humanize(sourceTableName);
 
-        propsOutput += `
-        ${sourceTableName}: {
-            name: "${relHumanName}",
-            type: "relation",
+        relationsOutput += `
+        {
+            relationName: "${sourceTableName}",
             target: () => ${targetCollectionCamel},
             cardinality: "many",
             direction: "inverse",
@@ -425,6 +727,7 @@ export function generateCollectionFile(
     }
 
     // Map Many-to-Many Relations (Join Tables)
+    // These also go into the `relations` array so they render as subcollection tabs.
     const relatedJoinTables = Array.from(joinTables).filter((jt) => {
         const jtMeta = tablesMap.get(jt);
         return jtMeta ? jtMeta.fks.some((fk) => fk.foreign_table_name === tableName) : false;
@@ -444,15 +747,10 @@ export function generateCollectionFile(
             const otherFk = selfRefFks[1];
 
             const relPropName = `${tableName}_via_${otherFk.column_name.replace(/_id$/, "")}`;
-            propertiesOrder.push(relPropName);
 
-            // Self-ref: import is the same collection (use a lazy reference)
-            const relHumanName = humanize(otherFk.column_name.replace(/_id$/, ""));
-
-            propsOutput += `
-        ${relPropName}: {
-            name: "${relHumanName}",
-            type: "relation",
+            relationsOutput += `
+        {
+            relationName: "${relPropName}",
             target: () => ${tableName}Collection,
             cardinality: "many",
             direction: "owning",
@@ -469,7 +767,6 @@ export function generateCollectionFile(
 
         if (otherFk) {
             const targetTableName = otherFk.foreign_table_name;
-            propertiesOrder.push(targetTableName);
 
             const targetCollectionCamel = toCollectionVarName(targetTableName);
             imports.add(`import ${targetCollectionCamel} from "./${targetTableName}";`);
@@ -478,19 +775,17 @@ export function generateCollectionFile(
             const direction = tableName < targetTableName ? "owning" : "inverse";
 
             const thisFk = joinFks.find((fk) => fk.foreign_table_name === tableName);
-            const relHumanName = humanize(targetTableName);
 
             let throughCode = "";
             if (direction === "owning" && thisFk) {
-                throughCode = `\n            through: {\n                table: "${jt}",\n                sourceColumn: "${thisFk.column_name}",\n                targetColumn: "${otherFk.column_name}"\n            }`;
+                throughCode = `\n            through: {\n                table: "${jt}",\n                sourceColumn: "${thisFk.column_name}",\n                targetColumn: "${otherFk.column_name}"\n            },`;
             } else if (direction === "inverse") {
                 throughCode = `\n            // Make sure the target collection configures the 'through' property.`;
             }
 
-            propsOutput += `
-        ${targetTableName}: {
-            name: "${relHumanName}",
-            type: "relation",
+            relationsOutput += `
+        {
+            relationName: "${targetTableName}",
             target: () => ${targetCollectionCamel},
             cardinality: "many",
             direction: "${direction}",${throughCode}
@@ -498,21 +793,30 @@ export function generateCollectionFile(
         }
     }
 
+    const relationsBlock = relationsOutput
+        ? `\n    relations: [${relationsOutput}\n    ],`
+        : "";
+
+    const sortedPropertiesOrder = sortPropertiesOrder(orderEntries);
+    for (const key of sortedPropertiesOrder) {
+        propsOutput += propertyBlocks.get(key) || "";
+    }
+
+    const collectionVarName = toCollectionVarName(tableName);
     const fileContent = `${Array.from(imports).join("\n")}
 
-const ${tableName}Collection: PostgresCollection = {
+const ${collectionVarName}: PostgresCollection = {
     name: "${collectionName}",
     singularName: "${singular}",
     slug: "${tableName}",
     table: "${tableName}",
     icon: "${icon}",
-    group: "App",
     properties: {${propsOutput}
-    },
-    propertiesOrder: ${JSON.stringify(propertiesOrder, null, 8).replace(/]$/, "    ]")}
+    },${relationsBlock}
+    propertiesOrder: ${JSON.stringify(sortedPropertiesOrder, null, 8).replace(/]$/, "    ]")}
 };
 
-export default ${tableName}Collection;
+export default ${collectionVarName};
 `;
 
     return fileContent;