@clivly/core 0.1.0 → 0.2.0

package/dist/entity-heuristics.cjs

@@ -0,0 +1,344 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/entity-heuristics.ts
+const TARGET_CONCEPTS = [
+	"contact",
+	"company",
+	"deal",
+	"activity",
+	"conversation",
+	"note"
+];
+const TABLE_PATTERNS = [
+	{
+		concept: "contact",
+		names: [
+			"users",
+			"customers",
+			"clients",
+			"accounts",
+			"participants",
+			"attendees",
+			"people",
+			"members",
+			"contacts"
+		]
+	},
+	{
+		concept: "company",
+		names: [
+			"companies",
+			"organizations",
+			"organisations",
+			"orgs",
+			"teams",
+			"businesses",
+			"accounts"
+		]
+	},
+	{
+		concept: "deal",
+		names: [
+			"deals",
+			"opportunities",
+			"subscriptions",
+			"orders",
+			"invoices",
+			"sales"
+		]
+	},
+	{
+		concept: "conversation",
+		names: [
+			"conversations",
+			"messages",
+			"tickets",
+			"threads",
+			"chats",
+			"inbox"
+		]
+	},
+	{
+		concept: "activity",
+		names: [
+			"events",
+			"activities",
+			"jobs",
+			"logs",
+			"audit",
+			"shifts",
+			"scans",
+			"sessions"
+		]
+	},
+	{
+		concept: "note",
+		names: [
+			"notes",
+			"comments",
+			"annotations"
+		]
+	}
+];
+const CONCEPT_FIELDS = {
+	contact: [{
+		field: "name",
+		candidates: [
+			"name",
+			"full_name",
+			"fullname",
+			"display_name"
+		],
+		required: false
+	}, {
+		field: "email",
+		candidates: ["email", "email_address"],
+		required: true
+	}],
+	company: [{
+		field: "name",
+		candidates: [
+			"name",
+			"company_name",
+			"legal_name",
+			"title"
+		],
+		required: true
+	}, {
+		field: "domain",
+		candidates: [
+			"domain",
+			"website",
+			"url"
+		],
+		required: false
+	}],
+	deal: [
+		{
+			field: "name",
+			candidates: ["name", "title"],
+			required: false
+		},
+		{
+			field: "value",
+			candidates: [
+				"value",
+				"amount",
+				"total",
+				"price"
+			],
+			required: false
+		},
+		{
+			field: "stage",
+			candidates: [
+				"stage",
+				"status",
+				"state"
+			],
+			required: false
+		}
+	],
+	activity: [
+		{
+			field: "type",
+			candidates: [
+				"type",
+				"kind",
+				"event_type"
+			],
+			required: false
+		},
+		{
+			field: "summary",
+			candidates: [
+				"summary",
+				"description",
+				"message",
+				"title"
+			],
+			required: false
+		},
+		{
+			field: "createdAt",
+			candidates: [
+				"created_at",
+				"createdat",
+				"timestamp"
+			],
+			required: false
+		}
+	],
+	conversation: [{
+		field: "status",
+		candidates: ["status", "state"],
+		required: false
+	}, {
+		field: "subject",
+		candidates: [
+			"subject",
+			"title",
+			"preview"
+		],
+		required: false
+	}],
+	note: [{
+		field: "body",
+		candidates: [
+			"body",
+			"content",
+			"text",
+			"note"
+		],
+		required: true
+	}]
+};
+const CURSOR_CANDIDATES = [
+	"updatedat",
+	"updated_at",
+	"modifiedat",
+	"modified_at",
+	"createdat",
+	"created_at"
+];
+function suggestCursorField(columnKeys) {
+	const lowerToActual = new Map(columnKeys.map((c) => [c.toLowerCase(), c]));
+	for (const candidate of CURSOR_CANDIDATES) {
+		const match = lowerToActual.get(candidate);
+		if (match) return match;
+	}
+	return null;
+}
+function suggestConcept(tableName) {
+	const normalized = tableName.toLowerCase();
+	for (const { concept, names } of TABLE_PATTERNS) if (names.includes(normalized)) return concept;
+	for (const { concept, names } of TABLE_PATTERNS) if (names.some((name) => normalized.includes(name))) return concept;
+	return null;
+}
+function matchesConcept(tableName, concept) {
+	const normalized = tableName.toLowerCase();
+	const entry = TABLE_PATTERNS.find((p) => p.concept === concept);
+	if (!entry) return null;
+	if (entry.names.includes(normalized)) return { exact: true };
+	if (entry.names.some((name) => normalized.includes(name))) return { exact: false };
+	return null;
+}
+function suggestFieldMap(concept, columns) {
+	const lowerToActual = new Map(columns.map((c) => [c.toLowerCase(), c]));
+	const map = {};
+	for (const { field, candidates } of CONCEPT_FIELDS[concept]) for (const candidate of candidates) {
+		const match = lowerToActual.get(candidate);
+		if (match) {
+			map[field] = match;
+			break;
+		}
+	}
+	return map;
+}
+function requiredFieldsFor(concept) {
+	return CONCEPT_FIELDS[concept].filter((f) => f.required).map((f) => f.field);
+}
+function validateMapping(requiredFields, fieldMap) {
+	const missing = requiredFields.filter((field) => !fieldMap[field]);
+	return {
+		valid: missing.length === 0,
+		missing
+	};
+}
+const DISCRIMINATOR_COLUMNS = [
+	"role",
+	"type",
+	"kind",
+	"status",
+	"state",
+	"category",
+	"tier"
+];
+function suggestDiscriminatorColumns(columns) {
+	const lowerToActual = new Map(columns.map((c) => [c.toLowerCase(), c]));
+	const out = [];
+	for (const name of DISCRIMINATOR_COLUMNS) {
+		const match = lowerToActual.get(name);
+		if (match) out.push(match);
+	}
+	return out;
+}
+const CONTACT_FK_HINTS = [
+	"user_id",
+	"owner_id",
+	"contact_id",
+	"member_id",
+	"person_id",
+	"created_by"
+];
+const COMPANY_FK_HINTS = [
+	"organization_id",
+	"organisation_id",
+	"org_id",
+	"company_id",
+	"account_id",
+	"team_id"
+];
+function firstMatchingColumn(columns, hints) {
+	const lowerToActual = new Map(columns.map((c) => [c.toLowerCase(), c]));
+	for (const hint of hints) {
+		const match = lowerToActual.get(hint);
+		if (match) return match;
+	}
+	return null;
+}
+/**
+* Suggest contact→company relationships for a contact-concept source table by
+* inspecting FK column names across the discovered schema. Detects all three
+* DSL shapes: FK-on-contact, FK-on-company, and a join table. Suggestions are
+* candidates only — the developer confirms.
+*/
+function suggestRelationships(source, allTables) {
+	const companyTables = allTables.filter((t) => t.name !== source.name && suggestConcept(t.name) === "company");
+	if (companyTables.length === 0) return [];
+	const suggestions = [];
+	const contactFk = firstMatchingColumn(source.columns, COMPANY_FK_HINTS);
+	if (contactFk) suggestions.push({
+		name: "company",
+		entityTable: companyTables[0]?.name ?? "",
+		via: {
+			fkOn: "contact",
+			column: `${source.name}.${contactFk}`
+		}
+	});
+	for (const company of companyTables) {
+		const companyFk = firstMatchingColumn(company.columns, CONTACT_FK_HINTS);
+		if (companyFk) suggestions.push({
+			name: "company",
+			entityTable: company.name,
+			via: {
+				fkOn: "company",
+				column: `${company.name}.${companyFk}`
+			}
+		});
+	}
+	for (const table of allTables) {
+		if (table.name === source.name) continue;
+		const localKey = firstMatchingColumn(table.columns, CONTACT_FK_HINTS);
+		const foreignKey = firstMatchingColumn(table.columns, COMPANY_FK_HINTS);
+		if (localKey && foreignKey) suggestions.push({
+			name: "company",
+			entityTable: companyTables.find((c) => c.name !== table.name)?.name ?? companyTables[0]?.name ?? "",
+			via: {
+				through: table.name,
+				localKey,
+				foreignKey
+			}
+		});
+	}
+	return suggestions;
+}
+//#endregion
+exports.TARGET_CONCEPTS = TARGET_CONCEPTS;
+exports.matchesConcept = matchesConcept;
+exports.requiredFieldsFor = requiredFieldsFor;
+exports.suggestConcept = suggestConcept;
+exports.suggestCursorField = suggestCursorField;
+exports.suggestDiscriminatorColumns = suggestDiscriminatorColumns;
+exports.suggestFieldMap = suggestFieldMap;
+exports.suggestRelationships = suggestRelationships;
+exports.validateMapping = validateMapping;

package/dist/entity-heuristics.d.cts

@@ -0,0 +1,43 @@
+//#region src/entity-heuristics.d.ts
+declare const TARGET_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
+type TargetConcept = (typeof TARGET_CONCEPTS)[number];
+declare function suggestCursorField(columnKeys: string[]): string | null;
+declare function suggestConcept(tableName: string): TargetConcept | null;
+declare function matchesConcept(tableName: string, concept: TargetConcept): {
+  exact: boolean;
+} | null;
+declare function suggestFieldMap(concept: TargetConcept, columns: string[]): Record<string, string>;
+declare function requiredFieldsFor(concept: TargetConcept): string[];
+declare function validateMapping(requiredFields: string[], fieldMap: Record<string, string>): {
+  valid: boolean;
+  missing: string[];
+};
+declare function suggestDiscriminatorColumns(columns: string[]): string[];
+type SuggestedVia = {
+  fkOn: "company" | "contact";
+  column: string;
+} | {
+  through: string;
+  localKey: string;
+  foreignKey: string;
+};
+interface RelationshipSuggestion {
+  /** The related host table. */
+  entityTable: string;
+  /** Suggested relationship name (defaults to the related concept). */
+  name: string;
+  via: SuggestedVia;
+}
+interface HeuristicTable {
+  columns: string[];
+  name: string;
+}
+/**
+ * Suggest contact→company relationships for a contact-concept source table by
+ * inspecting FK column names across the discovered schema. Detects all three
+ * DSL shapes: FK-on-contact, FK-on-company, and a join table. Suggestions are
+ * candidates only — the developer confirms.
+ */
+declare function suggestRelationships(source: HeuristicTable, allTables: HeuristicTable[]): RelationshipSuggestion[];
+//#endregion
+export { RelationshipSuggestion, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, suggestConcept, suggestCursorField, suggestDiscriminatorColumns, suggestFieldMap, suggestRelationships, validateMapping };

package/dist/entity-heuristics.d.mts

@@ -0,0 +1,43 @@
+//#region src/entity-heuristics.d.ts
+declare const TARGET_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
+type TargetConcept = (typeof TARGET_CONCEPTS)[number];
+declare function suggestCursorField(columnKeys: string[]): string | null;
+declare function suggestConcept(tableName: string): TargetConcept | null;
+declare function matchesConcept(tableName: string, concept: TargetConcept): {
+  exact: boolean;
+} | null;
+declare function suggestFieldMap(concept: TargetConcept, columns: string[]): Record<string, string>;
+declare function requiredFieldsFor(concept: TargetConcept): string[];
+declare function validateMapping(requiredFields: string[], fieldMap: Record<string, string>): {
+  valid: boolean;
+  missing: string[];
+};
+declare function suggestDiscriminatorColumns(columns: string[]): string[];
+type SuggestedVia = {
+  fkOn: "company" | "contact";
+  column: string;
+} | {
+  through: string;
+  localKey: string;
+  foreignKey: string;
+};
+interface RelationshipSuggestion {
+  /** The related host table. */
+  entityTable: string;
+  /** Suggested relationship name (defaults to the related concept). */
+  name: string;
+  via: SuggestedVia;
+}
+interface HeuristicTable {
+  columns: string[];
+  name: string;
+}
+/**
+ * Suggest contact→company relationships for a contact-concept source table by
+ * inspecting FK column names across the discovered schema. Detects all three
+ * DSL shapes: FK-on-contact, FK-on-company, and a join table. Suggestions are
+ * candidates only — the developer confirms.
+ */
+declare function suggestRelationships(source: HeuristicTable, allTables: HeuristicTable[]): RelationshipSuggestion[];
+//#endregion
+export { RelationshipSuggestion, SuggestedVia, TARGET_CONCEPTS, TargetConcept, matchesConcept, requiredFieldsFor, suggestConcept, suggestCursorField, suggestDiscriminatorColumns, suggestFieldMap, suggestRelationships, validateMapping };