flappa-doormal 2.9.0 → 2.10.0

package/dist/index.mjs

@@ -155,6 +155,154 @@ const makeDiacriticInsensitive = (text) => {
 	return Array.from(norm).map((ch) => getEquivClass(ch) + diacriticsMatcher).join("");
 };
 
+//#endregion
+//#region src/segmentation/types.ts
+/**
+* Pattern type key names for split rules.
+*
+* Use this array to dynamically iterate over pattern types in UIs,
+* or use the `PatternTypeKey` type for type-safe string unions.
+*
+* @example
+* // Build a dropdown/select in UI
+* PATTERN_TYPE_KEYS.map(key => <option value={key}>{key}</option>)
+*
+* @example
+* // Type-safe pattern key validation
+* const validateKey = (k: string): k is PatternTypeKey =>
+*   (PATTERN_TYPE_KEYS as readonly string[]).includes(k);
+*/
+const PATTERN_TYPE_KEYS = [
+	"lineStartsWith",
+	"lineStartsAfter",
+	"lineEndsWith",
+	"template",
+	"regex"
+];
+
+//#endregion
+//#region src/segmentation/optimize-rules.ts
+/**
+* Rule optimization utilities for merging and sorting split rules.
+*
+* Provides `optimizeRules()` to:
+* 1. Merge compatible rules with same pattern type and options
+* 2. Deduplicate patterns within each rule
+* 3. Sort rules by specificity (longer patterns first)
+*
+* @module optimize-rules
+*/
+const MERGEABLE_KEYS = new Set([
+	"lineStartsWith",
+	"lineStartsAfter",
+	"lineEndsWith"
+]);
+/**
+* Get the pattern type key for a rule.
+*/
+const getPatternKey = (rule) => {
+	for (const key of PATTERN_TYPE_KEYS) if (key in rule) return key;
+	return "regex";
+};
+/**
+* Get the pattern array for a mergeable rule.
+*/
+const getPatternArray = (rule, key) => {
+	const value = rule[key];
+	return Array.isArray(value) ? value : [];
+};
+/**
+* Get a string representation of the pattern value (for specificity scoring).
+*/
+const getPatternString = (rule, key) => {
+	const value = rule[key];
+	if (typeof value === "string") return value;
+	if (Array.isArray(value)) return value.join("\n");
+	return "";
+};
+/**
+* Deduplicate and sort patterns by length (longest first).
+*/
+const normalizePatterns = (patterns) => {
+	return [...new Set(patterns)].sort((a, b) => b.length - a.length || a.localeCompare(b));
+};
+/**
+* Calculate specificity score for a rule (higher = more specific).
+* Based on the longest pattern length.
+*/
+const getSpecificityScore = (rule) => {
+	const key = getPatternKey(rule);
+	if (MERGEABLE_KEYS.has(key)) return getPatternArray(rule, key).reduce((max, p) => Math.max(max, p.length), 0);
+	return getPatternString(rule, key).length;
+};
+/**
+* Create a merge key for a rule based on pattern type and all non-pattern properties.
+* Rules with the same merge key can have their patterns combined.
+*/
+const createMergeKey = (rule) => {
+	const patternKey = getPatternKey(rule);
+	const { [patternKey]: _pattern, ...rest } = rule;
+	return `${patternKey}|${JSON.stringify(rest)}`;
+};
+/**
+* Optimize split rules by merging compatible rules and sorting by specificity.
+*
+* This function:
+* 1. **Merges compatible rules**: Rules with the same pattern type and identical
+*    options (meta, fuzzy, min/max, etc.) have their pattern arrays combined
+* 2. **Deduplicates patterns**: Removes duplicate patterns within each rule
+* 3. **Sorts by specificity**: Rules with longer patterns come first
+*
+* Only array-based pattern types (`lineStartsWith`, `lineStartsAfter`, `lineEndsWith`)
+* can be merged. `template` and `regex` rules are kept separate.
+*
+* @param rules - Array of split rules to optimize
+* @returns Optimized rules and count of merged rules
+*
+* @example
+* import { optimizeRules } from 'flappa-doormal';
+*
+* const { rules, mergedCount } = optimizeRules([
+*   { lineStartsWith: ['{{kitab}}'], fuzzy: true, meta: { type: 'header' } },
+*   { lineStartsWith: ['{{bab}}'], fuzzy: true, meta: { type: 'header' } },
+*   { lineStartsAfter: ['{{numbered}}'], meta: { type: 'entry' } },
+* ]);
+*
+* // rules[0] = { lineStartsWith: ['{{kitab}}', '{{bab}}'], fuzzy: true, meta: { type: 'header' } }
+* // rules[1] = { lineStartsAfter: ['{{numbered}}'], meta: { type: 'entry' } }
+* // mergedCount = 1
+*/
+const optimizeRules = (rules) => {
+	const output = [];
+	const indexByMergeKey = /* @__PURE__ */ new Map();
+	let mergedCount = 0;
+	for (const rule of rules) {
+		const patternKey = getPatternKey(rule);
+		if (!MERGEABLE_KEYS.has(patternKey)) {
+			output.push(rule);
+			continue;
+		}
+		const mergeKey = createMergeKey(rule);
+		const existingIndex = indexByMergeKey.get(mergeKey);
+		if (existingIndex === void 0) {
+			indexByMergeKey.set(mergeKey, output.length);
+			output.push({
+				...rule,
+				[patternKey]: normalizePatterns(getPatternArray(rule, patternKey))
+			});
+			continue;
+		}
+		const existing = output[existingIndex];
+		existing[patternKey] = normalizePatterns([...getPatternArray(existing, patternKey), ...getPatternArray(rule, patternKey)]);
+		mergedCount++;
+	}
+	output.sort((a, b) => getSpecificityScore(b) - getSpecificityScore(a));
+	return {
+		mergedCount,
+		rules: output
+	};
+};
+
 //#endregion
 //#region src/segmentation/tokens.ts
 /**
@@ -626,6 +774,51 @@ const shouldDefaultToFuzzy = (patterns) => {
 		return FUZZY_TOKEN_REGEX.test(p);
 	});
 };
+/**
+* Apply token mappings to a template string.
+*
+* Transforms `{{token}}` into `{{token:name}}` based on the provided mappings.
+* Useful for applying user-configured capture names to a raw template.
+*
+* - Only affects exact matches of `{{token}}`.
+* - Does NOT affect tokens that already have a capture name (e.g. `{{token:existing}}`).
+* - Does NOT affect capture-only tokens (e.g. `{{:name}}`).
+*
+* @param template - The template string to transform
+* @param mappings - Array of mappings from token name to capture name
+* @returns Transformed template string with captures applied
+*
+* @example
+* applyTokenMappings('{{raqms}} {{dash}}', [{ token: 'raqms', name: 'num' }])
+* // → '{{raqms:num}} {{dash}}'
+*/
+const applyTokenMappings = (template, mappings) => {
+	let result = template;
+	for (const { token, name } of mappings) {
+		if (!token || !name) continue;
+		const regex = new RegExp(`\\{\\{${token}\\}\\}`, "g");
+		result = result.replace(regex, `{{${token}:${name}}}`);
+	}
+	return result;
+};
+/**
+* Strip token mappings from a template string.
+*
+* Transforms `{{token:name}}` back into `{{token}}`.
+* Also transforms `{{:name}}` patterns (capture-only) into `{{}}` (which is invalid/empty).
+*
+* Useful for normalizing templates for storage or comparison.
+*
+* @param template - The template string to strip
+* @returns Template string with capture names removed
+*
+* @example
+* stripTokenMappings('{{raqms:num}} {{dash}}')
+* // → '{{raqms}} {{dash}}'
+*/
+const stripTokenMappings = (template) => {
+	return template.replace(/\{\{([^:}]+):[^}]+\}\}/g, "{{$1}}");
+};
 
 //#endregion
 //#region src/segmentation/pattern-validator.ts
@@ -651,6 +844,7 @@ const validatePattern = (pattern, seenPatterns) => {
 	};
 	if (seenPatterns.has(pattern)) return {
 		message: `Duplicate pattern: "${pattern}"`,
+		pattern,
 		type: "duplicate"
 	};
 	seenPatterns.add(pattern);
@@ -660,6 +854,7 @@ const validatePattern = (pattern, seenPatterns) => {
 		if (!KNOWN_TOKENS.has(tokenName)) return {
 			message: `Unknown token: {{${tokenName}}}. Available tokens: ${[...KNOWN_TOKENS].slice(0, 5).join(", ")}...`,
 			suggestion: `Check spelling or use a known token`,
+			token: tokenName,
 			type: "unknown_token"
 		};
 	}
@@ -674,6 +869,7 @@ const validatePattern = (pattern, seenPatterns) => {
 		if (before !== "{{" && after !== "}}") return {
 			message: `Token "${tokenName}" appears to be missing {{}}. Did you mean "{{${fullMatch}}}"?`,
 			suggestion: `{{${fullMatch}}}`,
+			token: tokenName,
 			type: "missing_braces"
 		};
 	}
@@ -742,6 +938,39 @@ const validateRules = (rules) => {
 		return hasIssues ? result : void 0;
 	});
 };
+/**
+* Formats a validation result array into a list of human-readable error messages.
+*
+* Useful for displaying validation errors in UIs.
+*
+* @param results - The result array from `validateRules()`
+* @returns Array of formatted error strings
+*
+* @example
+* const issues = validateRules(rules);
+* const errors = formatValidationReport(issues);
+* // ["Rule 1, lineStartsWith: Missing {{}} around token..."]
+*/
+const formatValidationReport = (results) => {
+	const errors = [];
+	results.forEach((result, ruleIndex) => {
+		if (!result) return;
+		const formatIssue = (issue, location) => {
+			if (!issue) return;
+			const type = issue.type;
+			if (type === "missing_braces" && issue.token) errors.push(`${location}: Missing {{}} around token "${issue.token}"`);
+			else if (type === "unknown_token" && issue.token) errors.push(`${location}: Unknown token "{{${issue.token}}}"`);
+			else if (type === "duplicate" && issue.pattern) errors.push(`${location}: Duplicate pattern "${issue.pattern}"`);
+			else if (issue.message) errors.push(`${location}: ${issue.message}`);
+			else errors.push(`${location}: ${type}`);
+		};
+		for (const [patternType, issues] of Object.entries(result)) {
+			const list = Array.isArray(issues) ? issues : [issues];
+			for (const issue of list) if (issue) formatIssue(issue, `Rule ${ruleIndex + 1}, ${patternType}`);
+		}
+	});
+	return errors;
+};
 
 //#endregion
 //#region src/segmentation/replace.ts
@@ -2536,7 +2765,7 @@ const buildTokenPriority = () => {
 	return TOKEN_PRIORITY_ORDER$1.filter((t) => allTokens.has(t));
 };
 const collapseWhitespace = (s) => s.replace(/\s+/g, " ").trim();
-const stripArabicDiacritics = (s) => s.replace(/[\u064B-\u065F\u0670\u06D6-\u06ED\u0640]/gu, "");
+const stripArabicDiacritics = (s) => s.replace(/[\u064B-\u065F\u0670\u06D6-\u06ED]/gu, "");
 const compileTokenRegexes = (tokenNames) => {
 	const compiled = [];
 	for (const token of tokenNames) {
@@ -3618,5 +3847,5 @@ function recoverMistakenMarkersForRuns(runs, opts) {
 }
 
 //#endregion
-export { TOKEN_PATTERNS, analyzeCommonLineStarts, analyzeRepeatingSequences, analyzeTextForRule, applyReplacements, containsTokens, detectTokenPatterns, escapeRegex, escapeTemplateBrackets, expandCompositeTokensInTemplate, expandTokens, expandTokensWithCaptures, generateTemplateFromText, getAvailableTokens, getTokenPattern, makeDiacriticInsensitive, recoverMistakenLineStartsAfterMarkers, recoverMistakenMarkersForRuns, segmentPages, suggestPatternConfig, templateToRegex, validateRules };
+export { PATTERN_TYPE_KEYS, TOKEN_PATTERNS, analyzeCommonLineStarts, analyzeRepeatingSequences, analyzeTextForRule, applyReplacements, applyTokenMappings, containsTokens, detectTokenPatterns, escapeRegex, escapeTemplateBrackets, expandCompositeTokensInTemplate, expandTokens, expandTokensWithCaptures, formatValidationReport, generateTemplateFromText, getAvailableTokens, getTokenPattern, makeDiacriticInsensitive, optimizeRules, recoverMistakenLineStartsAfterMarkers, recoverMistakenMarkersForRuns, segmentPages, shouldDefaultToFuzzy, stripTokenMappings, suggestPatternConfig, templateToRegex, validateRules };
 //# sourceMappingURL=index.mjs.map