@appaflytech/zeyrek-ai-mcp 0.0.43 → 0.0.45

package/dist/tools/textHookGuard.js

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+import { applyPolicyMode, enforcePolicy } from '../knowledge/policy.js';
+import { readProjectLanguages } from '../knowledge/languages.js';
+import { logStep } from '../observability/trace.js';
+import { addedHooks, addedWords, comparedWordsIn, displayTextsIn, textHooksIn } from '../knowledge/textHooks.js';
+/**
+ * Sayfa / layout / widget yazan araçların kaçış girdisi. Ad bilerek akış araçlarınınkiyle aynı: PolicyBlockError
+ * "aynı çağrıyı policyOverride: true ile tekrarlayın" der ve o alan bu araçlarda da var olmalı (S-12 dersi).
+ */
+export const textHookOverrideParam = z.boolean().optional().describe("true: görünen metne bağlı mantık (metin kancası, TR-005) bilinçli istisna olarak yazılır — yalnız sunucu metin döndürüyor ve karşılaştırılacak kod yoksa. Bulgu yanıtta uyarı olarak kalır. Varsayılan false: bu yazımla gelen kanca isteği durdurur");
+const GUIDE = 'ngapps://guides/translation';
+const DICTIONARY_TTL_MS = 5 * 60 * 1000;
+const FAILED_DICTIONARY_TTL_MS = 30 * 1000;
+const LISTED = 5;
+// Her akış / şema yazımında sözlüğü okumamak için: qm sözlüğü ≈ 7.700 satır (2026-10-15). Okuma düşerse boş
+// sonuç da önbelleğe girer — kapı yalnız sayfa yazılarıyla karar verir, platformu dövmez.
+const dictionaryCache = new Map();
+/** Testler birbirinin önbelleğini görmesin diye. */
+export function clearTextHookDictionaryCache() {
+    dictionaryCache.clear();
+}
+async function defaultLanguageTexts(platform, project, environment, applicationId) {
+    const key = `${platform.resolveProject(project)}|${environment ?? ''}|${applicationId.toLowerCase()}`;
+    const cached = dictionaryCache.get(key);
+    if (cached && Date.now() - cached.at < cached.ttl)
+        return cached.values;
+    const values = new Map();
+    let ttl = DICTIONARY_TTL_MS;
+    try {
+        const language = readProjectLanguages(await platform.org('GET', `/p/${platform.resolveProject(project)}`))?.defaultLanguage;
+        if (language) {
+            const listed = await platform.tenant('GET', project, `/translations/${applicationId}`, { environment });
+            for (const row of listed?.data ?? []) {
+                const text = (row.value ?? '').trim();
+                if (row.language === language && text !== '' && row.key && !values.has(text))
+                    values.set(text, row.key);
+            }
+        }
+    }
+    catch (error) {
+        // Sözlük okunamadı: TR-006 ve belirsiz kanca yalnız barındırıcının yazılarına bakar; kısa süre sonra yeniden denenir.
+        ttl = FAILED_DICTIONARY_TTL_MS;
+        logStep('metin kancası', `sözlük okunamadı (${key}) — yalnız sayfa yazıları kullanıldı`, [error instanceof Error ? error.message : String(error)]);
+    }
+    dictionaryCache.set(key, { at: Date.now(), ttl, values });
+    return values;
+}
+function listed(hooks) {
+    const shown = hooks.slice(0, LISTED).map(hook => `'${hook.text}' ← ${hook.excerpt}`).join(' · ');
+    return hooks.length > LISTED ? `${shown} · ve ${hooks.length - LISTED} tane daha` : shown;
+}
+const RIGHT_WAY = "Kararı yazıya değil değişmeyen bir değere bağlayın: kayıttaki kod (status === 'Approved'), state ya da değişken, Page.queryParams, element kimliği ya da sekme key'i, sınıf ya da data-* özniteliği. Renk eşlemesinde (colorMap) value koda, görünen yazı label'a (çeviri sarmalı) gider; yazıyı t('anahtar') ile ayrıca basın.";
+/**
+ * TR-005: görünen metne bağlı mantık — bu yazımla gelen `block`, kayıtta duran `warn` (karar D1, kullanıcı 2026-10-16).
+ * TR-006: biçimden ayırt edilemeyen tek kelime / ASCII boşluklu metin sözlükte (varsayılan dil) ya da sayfa yazısında
+ * geçiyorsa — tek kelime `warn` (karar D2), boşluklu metin kesin sayılıp TR-005 olur.
+ */
+export async function textHookFindings(scope) {
+    const afterHooks = textHooksIn(scope.after);
+    const afterWords = comparedWordsIn(scope.after);
+    if (afterHooks.length === 0 && afterWords.length === 0)
+        return [];
+    let beforeUnreadable = false;
+    const before = scope.before
+        ? await scope.before().catch(() => {
+            beforeUnreadable = true;
+            return undefined;
+        })
+        : undefined;
+    const added = addedHooks(textHooksIn(before ?? []), afterHooks);
+    const kept = addedHooks(added, afterHooks);
+    const words = [...new Set(addedWords(comparedWordsIn(before ?? []), afterWords))];
+    const needsTexts = words.length > 0 || [...added, ...kept].some(hook => !hook.certain);
+    const pageTexts = needsTexts ? displayTextsIn([scope.hostTree ? await scope.hostTree().catch(() => undefined) : undefined, scope.after]) : new Set();
+    const dictionary = needsTexts ? await defaultLanguageTexts(scope.platform, scope.project, scope.environment, scope.applicationId) : new Map();
+    const knownAs = (text) => dictionary.has(text) ? `sözlükte ${dictionary.get(text)}` : pageTexts.has(text) ? 'sayfadaki yazı' : undefined;
+    const isHook = (hook) => hook.certain || knownAs(hook.text) !== undefined;
+    const newHooks = added.filter(isHook);
+    const oldHooks = kept.filter(isHook);
+    const wordHits = words.flatMap(word => {
+        const known = knownAs(word);
+        return known ? [`'${word}' (${known})`] : [];
+    });
+    const findings = [];
+    if (newHooks.length > 0) {
+        findings.push({
+            ruleId: 'TR-005',
+            severity: 'block',
+            message: `${scope.where}: görünen metne bağlı mantık yazılamaz (metin kancası) — ${listed(newHooks)}.${beforeUnreadable ? ' (Kayıtlı hâl okunamadı: kancaların hepsi yeni sayıldı.)' : ''} Ekrandaki yazı dile, çeviriye ve tasarımcının düzeltmesine göre değişir; değişince karşılaştırma sessizce tutmaz (qm'de İngilizceye geçince ev ikonu kayboldu, onay düğmeleri görünür oldu). ${RIGHT_WAY} Sunucu yalnız metin döndürüyor ve kod yoksa bilinçli istisnadır.`,
+            guide: GUIDE
+        });
+    }
+    if (oldHooks.length > 0) {
+        findings.push({
+            ruleId: 'TR-005',
+            severity: 'warn',
+            message: `${scope.where}: kayıtta önceden duran metin kancası (bu yazım eklemedi) — ${listed(oldHooks)}. Dokunduğunuz yerdeyse aynı değişiklikte koda çevirin; bu metni çevirmeyin, karşılaştırma kırılır. ${RIGHT_WAY}`,
+            guide: GUIDE
+        });
+    }
+    if (wordHits.length > 0) {
+        findings.push({
+            ruleId: 'TR-006',
+            severity: 'warn',
+            message: `${scope.where}: karşılaştırılan tek kelime görünen bir yazıyla aynı — ${wordHits.slice(0, LISTED).join(' · ')}${wordHits.length > LISTED ? ` · ve ${wordHits.length - LISTED} tane daha` : ''}. Görünen yazıysa kararı koda bağlayın (TR-005 ile aynı yol); bir kod değeriyse (sunucu enum'u) bu uyarıyı yok sayın.`,
+            guide: GUIDE
+        });
+    }
+    return findings;
+}
+/** Kapı: POLICY=off'ta susar, `policyOverride` block'u warn'a indirir, kalan block isteği platforma gitmeden durdurur. */
+export async function enforceTextHooks(config, scope, policyOverride) {
+    if (config.policyMode === 'off')
+        return [];
+    return enforcePolicy(applyPolicyMode(config, await textHookFindings(scope), policyOverride === true));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appaflytech/zeyrek-ai-mcp",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "type": "module",
   "description": "Zeyrek (NgApps) platform APIs as MCP tools — data, logic and Studio design surface in one gateway",
   "license": "UNLICENSED",
@@ -60,4 +60,4 @@
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"
   }
-}
+}