playwright-intelligence-engine 0.0.0-stage → 2.0.0

package/src/authoring/naming/naming-linter.ts

@@ -0,0 +1,292 @@
+import type { NamePlan } from './name-plan.js';
+
+export interface NamingLintViolation {
+  kind:
+    | 'INDEX_DERIVED_IDENTIFIER'
+    | 'DUPLICATE_PROPERTY'
+    | 'DUPLICATE_METHOD'
+    | 'DUPLICATE_WORD_IN_IDENTIFIER'
+    | 'CLASS_NAME_CASING'
+    | 'RESERVED_WORD_COLLISION'
+    | 'MISSING_VERB'
+    | 'ZERO_SEMANTIC_OVERLAP'
+    | 'UNGROUNDED_IDENTIFIER';
+  message: string;
+  identifier: string;
+  ref?: string | undefined;
+}
+
+export interface NamingLintReport {
+  passed: boolean;
+  violations: NamingLintViolation[];
+  totalIdentifiers: number;
+  indexDerivedIdentifierCount: number;
+  duplicateSymbolCount: number;
+  semanticNameCoverage: number | null;
+  namingConformanceRate: number | null;
+}
+
+const RESERVED_WORDS = new Set([
+  'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
+  'else', 'export', 'extends', 'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof',
+  'new', 'return', 'super', 'switch', 'this', 'throw', 'try', 'typeof', 'var', 'void', 'while',
+  'with', 'yield', 'enum', 'implements', 'interface', 'let', 'package', 'private', 'protected',
+  'public', 'static', 'await', 'abstract', 'boolean', 'byte', 'char', 'double', 'final', 'float',
+  'goto', 'int', 'long', 'native', 'short', 'synchronized', 'throws', 'transient', 'volatile',
+  'page', 'constructor', 'locator',
+]);
+
+const ALLOWED_VERBS = new Set([
+  'fill', 'enter', 'click', 'submit', 'signIn', 'signUp', 'open', 'goTo', 'select', 'check',
+  'uncheck', 'expectVisible', 'expectText', 'expectHidden', 'perform', 'press', 'hover', 'clear',
+  'add', 'create', 'update', 'edit', 'delete', 'remove', 'toggle', 'filter', 'search', 'navigate',
+  'login', 'logout', 'register', 'verify', 'assert', 'wait', 'proceed', 'confirm', 'cancel',
+  'complete', 'reset', 'sort', 'apply', 'upload', 'download', 'type', 'focus', 'get', 'is', 'has',
+]);
+
+/** Generic role-derived identifiers with no accessible name (actionButton, buttonButton). */
+const GENERIC_ROLE_NAME_RE = /^(action|button|input|element|field|link|text|heading|checkbox|combobox|radio|select|tab|cell|status|dialog|content|widget)(Button|Input|Element|Field|Link|Text|Heading|Checkbox|Combobox|Radio|Select|Tab|Cell|Status|Dialog|Content|Widget)?$/i;
+
+const SEMANTIC_SYNONYMS: Record<string, string[]> = {
+  register: ['signup', 'sign', 'up', 'register', 'enroll'],
+  signup: ['register', 'sign', 'up', 'signup', 'enroll'],
+  login: ['signin', 'sign', 'in', 'login', 'auth'],
+  signin: ['login', 'sign', 'in', 'signin', 'auth'],
+  checkout: ['order', 'buy', 'purchase', 'submit', 'pay'],
+  save: ['submit', 'confirm', 'apply'],
+  apply: ['submit', 'save', 'application'],
+};
+
+function extractWords(identifier: string): string[] {
+  const tokens = identifier
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[^a-zA-Z0-9]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+
+  const words: string[] = [];
+  for (const token of tokens) {
+    if (token.length >= 6 && token.length % 2 === 0) {
+      const half = token.slice(0, token.length / 2);
+      const secondHalf = token.slice(token.length / 2);
+      if (half.toLowerCase() === secondHalf.toLowerCase()) {
+        words.push(half, secondHalf);
+        continue;
+      }
+    }
+    words.push(token);
+  }
+  return words;
+}
+
+function hasDuplicateAdjacentWords(identifier: string): boolean {
+  const words = extractWords(identifier);
+  if (words.length < 2) return false;
+  for (let i = 0; i < words.length - 1; i++) {
+    if (words[i]!.toLowerCase() === words[i + 1]!.toLowerCase()) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export class NamingLinter {
+  public static lint(plan: NamePlan): NamingLintReport {
+    const violations: NamingLintViolation[] = [];
+    const seenProperties = new Set<string>();
+    const seenMethods = new Set<string>();
+
+    let indexDerivedCount = 0;
+    let duplicateCount = 0;
+    let semanticMatches = 0;
+    let totalAssessed = 0;
+
+    // Check class name casing
+    if (plan.pageClassName) {
+      totalAssessed++;
+      if (!/^[A-Z][a-zA-Z0-9]*Page$/.test(plan.pageClassName)) {
+        violations.push({
+          kind: 'CLASS_NAME_CASING',
+          message: `Class name '${plan.pageClassName}' must be PascalCase and end with 'Page'`,
+          identifier: plan.pageClassName,
+        });
+      }
+
+      // Detect flattened casing (e.g. OrderreviewPage vs OrderReviewPage)
+      const base = plan.pageClassName.replace(/Page$/, '');
+      const words = extractWords(base);
+      if (words.length === 1 && words[0]!.length > 8 && /^[A-Z][a-z]+$/.test(words[0]!)) {
+        // Known compound keywords that should not be flattened
+        const commonCompounds = ['orderreview', 'userlogin', 'customersignup', 'productsearch', 'shoppingcart'];
+        if (commonCompounds.some((c) => words[0]!.toLowerCase().includes(c))) {
+          violations.push({
+            kind: 'CLASS_NAME_CASING',
+            message: `Class name '${plan.pageClassName}' exhibits flattened compound casing`,
+            identifier: plan.pageClassName,
+          });
+        }
+      }
+    }
+
+    for (let stepIndex = 0; stepIndex < plan.symbols.length; stepIndex++) {
+      const sym = plan.symbols[stepIndex]!;
+      const expectedNum = stepIndex + 1;
+
+      // 1. Check property
+      totalAssessed++;
+
+      // Check positional correlation for index derivation
+      const propDigitMatch = sym.property.match(/\d+$/);
+      const isPropPositionalIndex = propDigitMatch && (parseInt(propDigitMatch[0], 10) === expectedNum || parseInt(propDigitMatch[0], 10) === stepIndex);
+      const isPropGenericIndexed = /^(actionButton|inputField|button|input|action|field|element)\d+$/i.test(sym.property);
+
+      if (isPropPositionalIndex || isPropGenericIndexed) {
+        indexDerivedCount++;
+        violations.push({
+          kind: 'INDEX_DERIVED_IDENTIFIER',
+          message: `Property '${sym.property}' is derived from a raw index (matched step ${expectedNum})`,
+          identifier: sym.property,
+          ref: sym.ref,
+        });
+      }
+
+      // Check duplicate adjacent words
+      if (hasDuplicateAdjacentWords(sym.property)) {
+        violations.push({
+          kind: 'DUPLICATE_WORD_IN_IDENTIFIER',
+          message: `Property '${sym.property}' contains duplicated adjacent word`,
+          identifier: sym.property,
+          ref: sym.ref,
+        });
+      }
+
+      if (seenProperties.has(sym.property)) {
+        duplicateCount++;
+        violations.push({
+          kind: 'DUPLICATE_PROPERTY',
+          message: `Duplicate property '${sym.property}' declared in Page Object`,
+          identifier: sym.property,
+          ref: sym.ref,
+        });
+      }
+      seenProperties.add(sym.property);
+
+      if (RESERVED_WORDS.has(sym.property.toLowerCase())) {
+        violations.push({
+          kind: 'RESERVED_WORD_COLLISION',
+          message: `Property '${sym.property}' collides with reserved language keyword`,
+          identifier: sym.property,
+          ref: sym.ref,
+        });
+      }
+
+      // 2. Check method
+      totalAssessed++;
+
+      const methodDigitMatch = sym.method.match(/\d+$/);
+      const isMethodPositionalIndex = methodDigitMatch && (parseInt(methodDigitMatch[0], 10) === expectedNum || parseInt(methodDigitMatch[0], 10) === stepIndex);
+      const isMethodGenericIndexed = /^(click|fill|action|perform|open)\d+$/i.test(sym.method);
+
+      if (isMethodPositionalIndex || isMethodGenericIndexed) {
+        indexDerivedCount++;
+        violations.push({
+          kind: 'INDEX_DERIVED_IDENTIFIER',
+          message: `Method '${sym.method}' is derived from a raw index (matched step ${expectedNum})`,
+          identifier: sym.method,
+          ref: sym.ref,
+        });
+      }
+
+      // Check duplicate adjacent words
+      if (hasDuplicateAdjacentWords(sym.method)) {
+        violations.push({
+          kind: 'DUPLICATE_WORD_IN_IDENTIFIER',
+          message: `Method '${sym.method}' contains duplicated adjacent word`,
+          identifier: sym.method,
+          ref: sym.ref,
+        });
+      }
+
+      if (seenMethods.has(sym.method)) {
+        duplicateCount++;
+        violations.push({
+          kind: 'DUPLICATE_METHOD',
+          message: `Duplicate method '${sym.method}' declared in Page Object`,
+          identifier: sym.method,
+          ref: sym.ref,
+        });
+      }
+      seenMethods.add(sym.method);
+
+      if (RESERVED_WORDS.has(sym.method.toLowerCase())) {
+        violations.push({
+          kind: 'RESERVED_WORD_COLLISION',
+          message: `Method '${sym.method}' collides with reserved language keyword`,
+          identifier: sym.method,
+          ref: sym.ref,
+        });
+      }
+
+      if (!ALLOWED_VERBS.has(sym.verb)) {
+        violations.push({
+          kind: 'MISSING_VERB',
+          message: `Method '${sym.method}' has unapproved verb '${sym.verb}'`,
+          identifier: sym.method,
+          ref: sym.ref,
+        });
+      }
+
+      // 3. Check semantic overlap with accessibleName (evaluating BOTH property and method)
+      if (sym.accessibleName && sym.accessibleName.trim().length > 0) {
+        const tokens = sym.accessibleName.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+        const propLower = sym.property.toLowerCase();
+        const methodLower = sym.method.toLowerCase();
+        const meaningfulTokens = tokens.filter((t) => t.length > 2 && !['the', 'and', 'for', 'with'].includes(t));
+        const candidateTerms = [
+          ...meaningfulTokens,
+          ...meaningfulTokens.flatMap((t) => SEMANTIC_SYNONYMS[t] ?? []),
+        ];
+
+        const propOverlap = candidateTerms.some((t) => propLower.includes(t));
+        const methodOverlap = candidateTerms.some((t) => methodLower.includes(t));
+
+        if (propOverlap && methodOverlap) {
+          semanticMatches++;
+        } else {
+          // Zero semantic overlap violation: applies to both heuristic and LLM sources
+          violations.push({
+            kind: 'ZERO_SEMANTIC_OVERLAP',
+            message: `Symbol '${sym.property}'/'${sym.method}' shares insufficient semantic tokens with accessible name '${sym.accessibleName}'`,
+            identifier: `${sym.property} / ${sym.method}`,
+            ref: sym.ref,
+          });
+        }
+      } else if (GENERIC_ROLE_NAME_RE.test(sym.property)) {
+        violations.push({
+          kind: 'UNGROUNDED_IDENTIFIER',
+          message: `Property '${sym.property}' is a generic role-derived name with no accessible name`,
+          identifier: sym.property,
+          ref: sym.ref,
+        });
+      }
+      // Note: If no accessibleName is provided, semanticMatches is NOT incremented (absent evidence is not covered)
+    }
+
+    const totalSymbols = plan.symbols.length;
+    // Empty denominator rule: n === 0 -> null (never 1.0 or 100%)
+    const semanticNameCoverage = totalSymbols > 0 ? Number((semanticMatches / totalSymbols).toFixed(4)) : null;
+    const nonViolating = Math.max(0, totalAssessed - violations.length);
+    const namingConformanceRate = totalAssessed > 0 ? Number((nonViolating / totalAssessed).toFixed(4)) : null;
+
+    return {
+      passed: violations.length === 0 && totalAssessed > 0 && totalSymbols > 0,
+      violations,
+      totalIdentifiers: totalAssessed,
+      indexDerivedIdentifierCount: indexDerivedCount,
+      duplicateSymbolCount: duplicateCount,
+      semanticNameCoverage,
+      namingConformanceRate,
+    };
+  }
+}

package/src/authoring/template-author.ts

@@ -0,0 +1,39 @@
+import { Author, AuthorInput, CandidateChange } from './author.js';
+import { planArchitecture, toSlug } from '../generator/architecture-generator.js';
+import { NamePlanner } from './naming/name-planner.js';
+
+export class TemplateAuthor implements Author {
+  public readonly kind = 'template';
+
+  public async propose(input: AuthorInput): Promise<CandidateChange> {
+    const steps = input.steps ?? [{ action: 'navigate' }, { action: 'assert-visible', role: 'heading', name: input.featureName }];
+    const symbols = NamePlanner.planNames(input.featureName, steps, { source: 'heuristic' });
+
+    const plan = planArchitecture({
+      featureName: input.featureName,
+      mode: input.mode,
+      baseUrl: input.baseUrl,
+      requirements: input.requirements,
+      steps,
+      profile: input.profile,
+      existingFiles: input.existingFiles,
+      namePlan: symbols,
+    });
+
+    return {
+      files: plan.files.map((f) => ({
+        relativePath: f.relativePath,
+        content: f.content,
+        purpose: f.purpose,
+        action: f.action,
+      })),
+      symbols,
+      rationale: 'Template-authored scaffold with deterministic heuristic symbol mapping.',
+      authorKind: 'template',
+      featureName: input.featureName,
+      slug: toSlug(input.featureName),
+      mode: input.mode,
+    };
+  }
+}
+