@vectoriox/iox-ui 5.46.0 → 5.48.0

package/src/harness-core/site-analysis.ts

@@ -0,0 +1,180 @@
+import { MOOD_IDS, MoodId } from '@vectoriox/iox-ui/design-core';
+import {
+    FACT_KEYS, FactKey, isPlainObject, PathIssue, PathIssueCollector, pathAt, PlainObject, requiredShapeKeys, ShapeEntry,
+    shapeKeys,
+} from '@vectoriox/iox-ui/generation-core';
+
+import { BUSINESS_TYPE_IDS, NEED_IDS, USER_AVOID_IDS, UserAvoidId } from './business-types';
+import { SPEC_ANALYSIS_SHAPE } from './harness-spec.generated';
+import { NeedSource, SiteNeed } from './needs';
+
+/**
+ * What the reading of a prompt returns (AI plan rev 3 §3d): one of the 30 kinds of business (and the two
+ * nearest), who it is for, what the site needs, the facts the prompt STATES (each with the words it came from)
+ * and those it does not, the owner's voice, moods, what they asked to avoid, a hero line, the language. A model
+ * writes it; `validateSiteAnalysis` is the gate — it refuses with a path and never repairs (a model gets the
+ * issues back and rewrites; the caller decides what to drop).
+ */
+
+export enum AnalysisLocale {
+    He = 'he',
+    En = 'en',
+}
+export enum VoicePerson {
+    We = 'we',
+    I = 'I',
+}
+export enum VoiceFormality {
+    Casual = 'casual',
+    Neutral = 'neutral',
+    Formal = 'formal',
+}
+
+export interface FactRead {
+    value: string;
+    /** The words of the prompt it came from — checked: every quote is in the prompt. */
+    quote: string;
+}
+
+export interface SiteAnalysis {
+    businessType: string;
+    alternatives: [string, string];
+    business: { name: string; audience: string };
+    needs: SiteNeed[];
+    facts: Partial<Record<FactKey, FactRead>>;
+    missingFacts: FactKey[];
+    voice: { tone: string; person: `${VoicePerson}`; formality: `${VoiceFormality}`; avoidWords: string[] };
+    moods: MoodId[];
+    avoid: UserAvoidId[];
+    hero: { headline: string; lead: string };
+    locale: `${AnalysisLocale}`;
+}
+
+export enum AnalysisIssueCode {
+    Shape = 'shape',
+    UnknownKey = 'unknown-key',
+    Duplicate = 'duplicate',
+    UnknownBusinessType = 'unknown-business-type',
+    UnknownNeed = 'unknown-need',
+    UnknownFact = 'unknown-fact',
+    /** A fact's quote is not words of the prompt: it was not stated, so it may not be filled. */
+    QuoteNotInPrompt = 'quote-not-in-prompt',
+    /** A fact reported both found and missing. */
+    FactFoundAndMissing = 'fact-found-and-missing',
+    UnknownMood = 'unknown-mood',
+    TooManyMoods = 'too-many-moods',
+    UnknownAvoid = 'unknown-avoid',
+    InvalidValue = 'invalid-value',
+}
+
+export type AnalysisIssue = PathIssue<AnalysisIssueCode>;
+
+export interface AnalysisValidation {
+    valid: boolean;
+    issues: AnalysisIssue[];
+}
+
+export interface AnalysisContext {
+    /** The owner's own words — every fact's quote must be found in them. */
+    prompt: string;
+}
+
+/** At most this many moods (the closed list a preset carries too). */
+export const MAX_ANALYSIS_MOODS = 3;
+const ALTERNATIVES = 2;
+
+const SHAPE: Readonly<Record<string, ShapeEntry>> = SPEC_ANALYSIS_SHAPE;
+const KEYS = Object.fromEntries(Object.keys(SHAPE).map(k => [k, shapeKeys(SHAPE[k])])) as Record<string, string[]>;
+const REQUIRED = Object.fromEntries(Object.keys(SHAPE).map(k => [k, requiredShapeKeys(SHAPE[k])])) as Record<string, string[]>;
+
+class Collector extends PathIssueCollector<AnalysisIssueCode> {
+    constructor() {
+        super('analysis', { shape: AnalysisIssueCode.Shape, unknownKey: AnalysisIssueCode.UnknownKey, duplicate: AnalysisIssueCode.Duplicate });
+    }
+    /** An object of `shape` at `path`: no unknown key, every required key present. */
+    object(value: unknown, shape: string, path: string): PlainObject | null {
+        if (!isPlainObject(value)) { this.add(AnalysisIssueCode.Shape, path, 'must be an object'); return null; }
+        this.keys(value, KEYS[shape], path);
+        for (const key of REQUIRED[shape]) if (value[key] === undefined) this.add(AnalysisIssueCode.Shape, pathAt(path, key), 'is required');
+        return value;
+    }
+    oneOf(obj: PlainObject, key: string, allowed: ReadonlyArray<string>, path: string, code = AnalysisIssueCode.InvalidValue): void {
+        const v = obj[key];
+        if (v !== undefined && (typeof v !== 'string' || !allowed.includes(v))) this.add(code, pathAt(path, key), `must be one of ${allowed.join(', ')}`);
+    }
+    strings(obj: PlainObject, key: string, path: string): string[] {
+        const list = this.array(obj, key, path);
+        list.forEach((v, i) => { if (typeof v !== 'string') this.add(AnalysisIssueCode.Shape, `${pathAt(path, key)}[${i}]`, 'must be a string'); });
+        return list.filter((v): v is string => typeof v === 'string');
+    }
+}
+
+/** Whitespace and case never decide whether words are the prompt's. */
+const normalise = (s: string) => s.toLowerCase().replace(/\s+/g, ' ').trim();
+
+export function validateSiteAnalysis(value: unknown, ctx: AnalysisContext): AnalysisValidation {
+    const c = new Collector();
+    const a = c.object(value, 'analysis', '');
+    if (!a) return { valid: false, issues: c.issues };
+
+    c.oneOf(a, 'businessType', BUSINESS_TYPE_IDS, '', AnalysisIssueCode.UnknownBusinessType);
+    const alternatives = c.strings(a, 'alternatives', '');
+    if (Array.isArray(a['alternatives']) && a['alternatives'].length !== ALTERNATIVES) c.add(AnalysisIssueCode.Shape, 'alternatives', `must name ${ALTERNATIVES} business types`);
+    alternatives.forEach((id, i) => {
+        if (!BUSINESS_TYPE_IDS.includes(id)) c.add(AnalysisIssueCode.UnknownBusinessType, `alternatives[${i}]`, `"${id}" is not a business type`);
+        else if (id === a['businessType']) c.add(AnalysisIssueCode.Duplicate, `alternatives[${i}]`, 'is the business type itself');
+    });
+
+    const business = c.object(a['business'], 'business', 'business');
+    if (business) { c.string(business, 'name', 'business'); c.string(business, 'audience', 'business'); }
+
+    const needs = c.array(a, 'needs', '');
+    c.unique(needs.map(n => (isPlainObject(n) && typeof n['id'] === 'string' ? n['id'] : null)), i => `needs[${i}].id`, 'need');
+    needs.forEach((raw, i) => {
+        const path = `needs[${i}]`;
+        const need = c.object(raw, 'need', path);
+        if (!need) return;
+        c.oneOf(need, 'id', NEED_IDS, path, AnalysisIssueCode.UnknownNeed);
+        c.oneOf(need, 'from', Object.values(NeedSource), path);
+        c.string(need, 'name', path, false);
+    });
+
+    const promptWords = normalise(ctx.prompt ?? '');
+    const found = new Set<string>();
+    if (!isPlainObject(a['facts'])) c.add(AnalysisIssueCode.Shape, 'facts', 'must be an object');
+    else for (const [key, raw] of Object.entries(a['facts'])) {
+        const path = `facts.${key}`;
+        if (!(FACT_KEYS as ReadonlyArray<string>).includes(key)) { c.add(AnalysisIssueCode.UnknownFact, path, `"${key}" is not a fact (${FACT_KEYS.join(', ')})`); continue; }
+        const fact = c.object(raw, 'factRead', path);
+        if (!fact) continue;
+        c.string(fact, 'value', path);
+        const quote = c.string(fact, 'quote', path);
+        if (quote && !promptWords.includes(normalise(quote))) c.add(AnalysisIssueCode.QuoteNotInPrompt, pathAt(path, 'quote'), 'is not words of the prompt — a fact the prompt does not state is missing, never filled');
+        found.add(key);
+    }
+    c.strings(a, 'missingFacts', '').forEach((key, i) => {
+        if (!(FACT_KEYS as ReadonlyArray<string>).includes(key)) c.add(AnalysisIssueCode.UnknownFact, `missingFacts[${i}]`, `"${key}" is not a fact`);
+        else if (found.has(key)) c.add(AnalysisIssueCode.FactFoundAndMissing, `missingFacts[${i}]`, `"${key}" is also in facts`);
+    });
+
+    const voice = c.object(a['voice'], 'voice', 'voice');
+    if (voice) {
+        c.string(voice, 'tone', 'voice');
+        c.oneOf(voice, 'person', Object.values(VoicePerson), 'voice');
+        c.oneOf(voice, 'formality', Object.values(VoiceFormality), 'voice');
+        c.strings(voice, 'avoidWords', 'voice');
+    }
+
+    const moods = c.strings(a, 'moods', '');
+    if (moods.length > MAX_ANALYSIS_MOODS) c.add(AnalysisIssueCode.TooManyMoods, 'moods', `at most ${MAX_ANALYSIS_MOODS}`);
+    moods.forEach((m, i) => { if (!(MOOD_IDS as ReadonlyArray<string>).includes(m)) c.add(AnalysisIssueCode.UnknownMood, `moods[${i}]`, `"${m}" is not a mood`); });
+    c.strings(a, 'avoid', '').forEach((id, i) => {
+        if (!(USER_AVOID_IDS as ReadonlyArray<string>).includes(id)) c.add(AnalysisIssueCode.UnknownAvoid, `avoid[${i}]`, `"${id}" is not something an owner may ask to avoid`);
+    });
+
+    const hero = c.object(a['hero'], 'hero', 'hero');
+    if (hero) { c.string(hero, 'headline', 'hero'); c.string(hero, 'lead', 'hero'); }
+    c.oneOf(a, 'locale', Object.values(AnalysisLocale), '');
+
+    return { valid: c.issues.length === 0, issues: c.issues };
+}