@qulib/core 0.4.0 → 0.4.2

package/dist/tools/auth-detector.d.ts

@@ -1,4 +1,22 @@
+import type { Page } from '@playwright/test';
 import type { DetectedAuth } from '../schemas/config.schema.js';
 import type { AnalyzeProgressSink } from '../harness/progress-log.js';
+export declare function evaluateStorageStateValidity(signals: {
+    expectedOrigin: string;
+    finalUrl: string;
+    visiblePasswordCount: number;
+    hadUnauthorizedHttp: boolean;
+}): {
+    valid: boolean;
+    reason: string;
+};
+export declare function waitForReturnToOrigin(page: Page, baseUrl: string, timeoutMs?: number): Promise<{
+    returned: boolean;
+    finalUrl: string;
+}>;
+export declare function validateStorageState(url: string, storagePath: string, timeoutMs?: number): Promise<{
+    valid: boolean;
+    reason: string;
+}>;
 export declare function detectAuth(url: string, timeoutMs?: number, progress?: AnalyzeProgressSink): Promise<DetectedAuth>;
 //# sourceMappingURL=auth-detector.d.ts.map

package/dist/tools/auth-detector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-detector.d.ts","sourceRoot":"","sources":["../../src/tools/auth-detector.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAgEtE,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,YAAY,CAAC,CA8HvB"}
+{"version":3,"file":"auth-detector.d.ts","sourceRoot":"","sources":["../../src/tools/auth-detector.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAwQtE,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;CAC9B,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAWrC;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,SAAS,SAAQ,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAelD;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,SAAS,SAAQ,GAChB,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA+B7C;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,YAAY,CAAC,CAqJvB"}

package/dist/tools/auth-detector.js

@@ -1,4 +1,6 @@
+import { resolve } from 'node:path';
 import { launchBrowser } from './browser.js';
+import { BUILT_IN_OAUTH_PROVIDERS } from './oauth-providers.js';
 async function waitNetworkIdleBestEffort(page) {
     try {
         await page.waitForLoadState('networkidle', { timeout: 5000 });
@@ -7,27 +9,20 @@ async function waitNetworkIdleBestEffort(page) {
         // best-effort — analytics or polling can prevent networkidle
     }
 }
-const OAUTH_PROVIDERS = [
-    { provider: 'github', patterns: [/github/i, /sign in with github/i] },
-    {
-        provider: 'google',
-        patterns: [/google/i, /sign in with google/i, /accounts\.google\.com/i],
-    },
-    {
-        provider: 'microsoft',
-        patterns: [/microsoft/i, /sign in with microsoft/i, /login\.microsoftonline\.com/i],
-    },
-    { provider: 'apple', patterns: [/apple/i, /sign in with apple/i] },
-    { provider: 'auth0', patterns: [/auth0/i] },
-    { provider: 'okta', patterns: [/okta/i] },
-];
+const PROVIDER_LABELS = new Set(BUILT_IN_OAUTH_PROVIDERS.map((p) => p.label.toLowerCase()));
 function textLooksLikeOAuthIdpButton(text) {
     const t = text.trim();
     if (t.length === 0 || t.length > 120) {
         return false;
     }
-    return (/\b(sign in with|log in with|continue with|sign up with)\b/i.test(t) ||
-        /^(github|google|microsoft|apple)$/i.test(t));
+    if (/\b(sign in with|log in with|continue with|sign up with)\b/i.test(t)) {
+        return true;
+    }
+    // Accept single-word / short labels that exactly match a known provider name
+    if (PROVIDER_LABELS.has(t.toLowerCase())) {
+        return true;
+    }
+    return false;
 }
 const MAGIC_LINK_PATTERNS = [
     /email me a (sign[- ]?in )?link/i,
@@ -53,6 +48,250 @@ async function firstTextInputNameForLogin(page) {
 function debugAuth() {
     return process.env.QULIB_DEBUG === '1';
 }
+function slugify(label) {
+    const s = label
+        .toLowerCase()
+        .replace(/\s+/g, '-')
+        .replace(/[^a-z0-9-]+/g, '')
+        .replace(/^-+|-+$/g, '');
+    return s.length > 0 ? s : 'custom';
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+async function resolveVisibleFieldLabel(page, el) {
+    const id = await el.getAttribute('id');
+    if (id) {
+        const lt = await page.locator(`label[for="${id.replace(/"/g, '\\"')}"]`).first().textContent().catch(() => null);
+        const fromLabel = (lt ?? '').trim();
+        if (fromLabel)
+            return fromLabel;
+    }
+    const placeholder = (await el.getAttribute('placeholder'))?.trim();
+    if (placeholder)
+        return placeholder;
+    const aria = (await el.getAttribute('aria-label'))?.trim();
+    if (aria)
+        return aria;
+    const name = (await el.getAttribute('name'))?.trim();
+    if (name)
+        return name;
+    const typ = (await el.getAttribute('type'))?.trim();
+    return typ && typ !== 'select' ? typ : 'text';
+}
+async function deriveCredentialFieldName(el) {
+    const name = (await el.getAttribute('name'))?.trim();
+    if (name)
+        return name;
+    const placeholder = (await el.getAttribute('placeholder'))?.trim();
+    if (placeholder)
+        return slugify(placeholder);
+    const aria = (await el.getAttribute('aria-label'))?.trim();
+    if (aria)
+        return slugify(aria);
+    const id = (await el.getAttribute('id'))?.trim();
+    if (id)
+        return slugify(id);
+    return 'field';
+}
+async function buildCredentialFieldsFromVisibleForm(page) {
+    const fields = [];
+    const seen = new Set();
+    const loc = page.locator('input[type="text"]:visible, input[type="email"]:visible, input[type="password"]:visible, select:visible');
+    const count = await loc.count();
+    for (let i = 0; i < count; i++) {
+        const el = loc.nth(i);
+        const tag = await el.evaluate((node) => node.tagName.toLowerCase()).catch(() => '');
+        if (tag === 'select') {
+            const name = await deriveCredentialFieldName(el);
+            const label = await resolveVisibleFieldLabel(page, el);
+            const opts = await el.locator('option').allInnerTexts();
+            const observedOptions = opts.map((o) => o.trim()).filter((x) => x.length > 0).slice(0, 20);
+            const dedupeKey = `select|${name}|${label}`;
+            if (seen.has(dedupeKey))
+                continue;
+            seen.add(dedupeKey);
+            fields.push({ name, label, type: 'select', observedOptions });
+            continue;
+        }
+        const rawType = ((await el.getAttribute('type')) ?? 'text').toLowerCase();
+        if (rawType === 'hidden')
+            continue;
+        const fieldType = rawType === 'email' ? 'email' : rawType === 'password' ? 'password' : 'text';
+        const name = await deriveCredentialFieldName(el);
+        const label = await resolveVisibleFieldLabel(page, el);
+        const placeholder = (await el.getAttribute('placeholder'))?.trim() ?? '';
+        const dedupeKey = `${name}|${placeholder}`;
+        if (seen.has(dedupeKey))
+            continue;
+        seen.add(dedupeKey);
+        fields.push({ name, label, type: fieldType, observedOptions: [] });
+    }
+    return fields;
+}
+function authPathsFromOauthButtons(oauthButtons, loginUrl) {
+    return oauthButtons.map((b) => {
+        const isUnknown = b.provider === 'unknown';
+        const id = isUnknown ? slugify(b.text) : b.provider;
+        return {
+            id,
+            label: b.text,
+            type: isUnknown ? 'oauth-unknown' : 'oauth',
+            provider: isUnknown ? slugify(b.text) : b.provider,
+            source: isUnknown ? 'heuristic' : 'built-in',
+            automatable: false,
+            confidence: isUnknown ? 'low' : 'high',
+            requirements: {
+                method: 'storage-state',
+                instruction: `Run qulib auth init --base-url ${loginUrl}`,
+            },
+        };
+    });
+}
+async function probeClickToRevealForms(page, loginUrl, alreadyMatchedTexts, timeoutMs, progress) {
+    const out = [];
+    const buttons = page.locator('button');
+    const n = await buttons.count();
+    const seenLabels = new Set();
+    const SUBMIT_RE = /^(sign in|log in|submit|continue|next|cancel|close)$/i;
+    let candidateAttempts = 0;
+    for (let i = 0; i < n && candidateAttempts < 4; i++) {
+        const label = ((await buttons.nth(i).textContent()) ?? '').trim();
+        if (!label || label.length > 80)
+            continue;
+        if (alreadyMatchedTexts.has(label))
+            continue;
+        if (SUBMIT_RE.test(label))
+            continue;
+        if (seenLabels.has(label))
+            continue;
+        seenLabels.add(label);
+        candidateAttempts += 1;
+        const originBefore = new URL(page.url()).origin;
+        if (debugAuth()) {
+            progress?.debug(`detect_auth click-reveal try label="${label.slice(0, 80)}"`);
+        }
+        let clicked = false;
+        try {
+            await page.getByRole('button', { name: label, exact: true }).first().click({ timeout: 2000 });
+            clicked = true;
+        }
+        catch {
+            try {
+                await page
+                    .locator('button')
+                    .filter({ hasText: new RegExp(`^\\s*${escapeRegExp(label)}\\s*$`, 'i') })
+                    .first()
+                    .click({ timeout: 2000 });
+                clicked = true;
+            }
+            catch {
+                /* skip */
+            }
+        }
+        if (!clicked) {
+            continue;
+        }
+        try {
+            await page.waitForLoadState('domcontentloaded', { timeout: 5000 });
+        }
+        catch {
+            /* best-effort after navigation */
+        }
+        if (new URL(page.url()).origin !== originBefore) {
+            if (debugAuth()) {
+                progress?.debug(`detect_auth click-reveal aborted (cross-origin after click): was ${originBefore} now ${new URL(page.url()).origin}`);
+            }
+            await page.goto(loginUrl, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+            await waitNetworkIdleBestEffort(page);
+            continue;
+        }
+        try {
+            await page.locator('input[type="password"]:visible').first().waitFor({ state: 'visible', timeout: 2000 });
+        }
+        catch {
+            await page.goto(loginUrl, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+            await waitNetworkIdleBestEffort(page);
+            continue;
+        }
+        const fields = await buildCredentialFieldsFromVisibleForm(page);
+        const slug = slugify(label);
+        out.push({
+            id: slug,
+            label,
+            type: 'form-login',
+            provider: slug,
+            source: 'heuristic',
+            automatable: true,
+            confidence: 'medium',
+            requirements: {
+                method: 'credentials',
+                fields,
+            },
+        });
+        await page.goto(loginUrl, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+        await waitNetworkIdleBestEffort(page);
+    }
+    return out;
+}
+export function evaluateStorageStateValidity(signals) {
+    if (new URL(signals.finalUrl).origin !== signals.expectedOrigin) {
+        return { valid: false, reason: 'session redirected to external IdP' };
+    }
+    if (signals.visiblePasswordCount > 0) {
+        return { valid: false, reason: 'login form still visible after loading storage state' };
+    }
+    if (signals.hadUnauthorizedHttp) {
+        return { valid: false, reason: 'HTTP 401/403 on authenticated request' };
+    }
+    return { valid: true, reason: 'session appears active' };
+}
+export async function waitForReturnToOrigin(page, baseUrl, timeoutMs = 15000) {
+    const targetOrigin = new URL(baseUrl).origin;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const finalUrl = page.url();
+        try {
+            if (new URL(finalUrl).origin === targetOrigin) {
+                return { returned: true, finalUrl };
+            }
+        }
+        catch {
+            /* ignore transient invalid URLs */
+        }
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    return { returned: false, finalUrl: page.url() };
+}
+export async function validateStorageState(url, storagePath, timeoutMs = 10000) {
+    const storageAbs = resolve(process.cwd(), storagePath);
+    const expectedOrigin = new URL(url).origin;
+    let hadUnauthorizedHttp = false;
+    const browser = await launchBrowser();
+    try {
+        const context = await browser.newContext({ storageState: storageAbs });
+        const page = await context.newPage();
+        page.on('response', (res) => {
+            const s = res.status();
+            if (s === 401 || s === 403) {
+                hadUnauthorizedHttp = true;
+            }
+        });
+        await page.goto(url, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+        await waitNetworkIdleBestEffort(page);
+        const finalUrl = page.url();
+        const visiblePasswordCount = await page.locator('input[type="password"]:visible').count();
+        return evaluateStorageStateValidity({
+            expectedOrigin,
+            finalUrl,
+            visiblePasswordCount,
+            hadUnauthorizedHttp,
+        });
+    }
+    finally {
+        await browser.close();
+    }
+}
 export async function detectAuth(url, timeoutMs = 15000, progress) {
     const browser = await launchBrowser();
     try {
@@ -67,7 +306,7 @@ export async function detectAuth(url, timeoutMs = 15000, progress) {
         }
         let loginUrl = url;
         const looksLikeLoginPage = /login|sign[- ]?in|auth/i.test(page.url()) ||
-            (await page.locator('input[type="password"]').count()) > 0;
+            (await page.locator('input[type="password"]:visible').count()) > 0;
         if (!looksLikeLoginPage) {
             const loginLink = page.locator('a').filter({ hasText: /^(log ?in|sign ?in|sign in)$/i }).first();
             const loginLinkCount = await loginLink.count();
@@ -82,7 +321,7 @@ export async function detectAuth(url, timeoutMs = 15000, progress) {
                 }
             }
         }
-        const passwordInputs = page.locator('input[type="password"]');
+        const passwordInputs = page.locator('input[type="password"]:visible');
         const passwordCount = await passwordInputs.count();
         progress?.debug(`detect_auth selector input[type=password] count=${passwordCount}`);
         const hasFormLogin = passwordCount > 0;
@@ -96,18 +335,33 @@ export async function detectAuth(url, timeoutMs = 15000, progress) {
                 }
                 continue;
             }
-            for (const { provider, patterns } of OAUTH_PROVIDERS) {
+            let matchedAny = false;
+            for (const { id, patterns } of BUILT_IN_OAUTH_PROVIDERS) {
                 const matched = patterns.some((p) => p.test(trimmed));
                 if (debugAuth()) {
-                    progress?.debug(`detect_auth oauth pattern try provider=${provider} matched=${matched}`);
+                    progress?.debug(`detect_auth oauth pattern try provider=${id} matched=${matched}`);
                 }
                 if (matched) {
-                    if (!oauthButtons.find((b) => b.provider === provider)) {
-                        oauthButtons.push({ provider, text: trimmed.slice(0, 100) });
+                    if (!oauthButtons.find((b) => b.provider === id)) {
+                        oauthButtons.push({ provider: id, text: trimmed.slice(0, 100) });
                     }
+                    matchedAny = true;
+                }
+            }
+            if (!matchedAny) {
+                const builtIn = BUILT_IN_OAUTH_PROVIDERS.find((p) => p.label.toLowerCase() === trimmed.toLowerCase());
+                if (builtIn) {
+                    if (!oauthButtons.find((b) => b.provider === builtIn.id)) {
+                        oauthButtons.push({ provider: builtIn.id, text: trimmed.slice(0, 100) });
+                    }
+                }
+                else if (!oauthButtons.find((b) => b.text === trimmed.slice(0, 100))) {
+                    oauthButtons.push({ provider: 'unknown', text: trimmed.slice(0, 100) });
                 }
             }
         }
+        const skipProbeLabels = new Set(oauthButtons.map((b) => b.text.trim()));
+        const clickRevealForms = await probeClickToRevealForms(page, loginUrl, skipProbeLabels, timeoutMs, progress);
         const pageText = await page.locator('body').innerText().catch(() => '');
         const hasMagicLink = MAGIC_LINK_PATTERNS.some((p) => p.test(pageText));
         let type = 'none';
@@ -117,7 +371,7 @@ export async function detectAuth(url, timeoutMs = 15000, progress) {
         if (oauthButtons.length > 0) {
             type = 'oauth';
             provider = oauthButtons[0].provider;
-            recommendation = `OAuth detected (${oauthButtons.map((b) => b.provider).join(', ')}). OAuth cannot be automated. Run "qulib auth init --base-url ${url}" to log in manually once and save a reusable storage state file.`;
+            recommendation = `OAuth detected (${oauthButtons.map((b) => b.provider).join(', ')}). OAuth cannot be automated. Run "qulib auth init --base-url ${loginUrl}" to log in manually once and save a reusable storage state file.`;
         }
         else if (hasFormLogin) {
             type = 'form-login';
@@ -140,26 +394,31 @@ export async function detectAuth(url, timeoutMs = 15000, progress) {
         }
         else if (hasMagicLink) {
             type = 'magic-link';
-            recommendation = `Magic link / passwordless auth detected. Qulib cannot complete email-link flows. Run "qulib auth init --base-url ${url}" to log in manually once and save a storage state file.`;
+            recommendation = `Magic link / passwordless auth detected. Qulib cannot complete email-link flows. Run "qulib auth init --base-url ${loginUrl}" to log in manually once and save a storage state file.`;
         }
         else if (looksLikeLoginPage) {
             type = 'unknown';
-            recommendation = `Authentication required but the pattern is unrecognized. Use "qulib auth init --base-url ${url}" to capture a storage state by logging in manually.`;
+            recommendation = `Authentication required but the pattern is unrecognized. Use "qulib auth init --base-url ${loginUrl}" to capture a storage state by logging in manually.`;
         }
         else {
             type = 'none';
             recommendation = `No authentication required for the entry URL. Qulib can scan anonymously.`;
         }
+        if (clickRevealForms.length > 0) {
+            recommendation += `\nAutomatable form login detected via: ${clickRevealForms.map((f) => f.label).join(', ')}. Use type="form-login" with the observed selectors in authOptions.`;
+        }
         const providerList = oauthButtons.length > 0 ? oauthButtons.map((b) => b.provider).join(', ') : provider ?? 'none';
-        const automatable = type === 'form-login';
+        const automatable = type === 'form-login' || clickRevealForms.length > 0;
         progress?.info(`Auth detected: ${type} (${providerList}) automatable=${automatable}`);
+        const authOptions = [...authPathsFromOauthButtons(oauthButtons, loginUrl), ...clickRevealForms];
         return {
-            hasAuth: type !== 'none',
+            hasAuth: type !== 'none' || oauthButtons.length > 0 || clickRevealForms.length > 0,
             type,
             provider,
-            loginUrl: type === 'none' ? null : loginUrl,
+            loginUrl: type === 'none' && oauthButtons.length === 0 && clickRevealForms.length === 0 ? null : loginUrl,
             observedSelectors,
             oauthButtons,
+            ...(authOptions.length > 0 ? { authOptions } : {}),
             recommendation,
         };
     }

package/dist/tools/auth-surface-analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-surface-analyzer.d.ts","sourceRoot":"","sources":["../../src/tools/auth-surface-analyzer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mCAAmC,CAAC;AAW7D,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,GAAG,EAAE,CAAC,CAuJhB"}
+{"version":3,"file":"auth-surface-analyzer.d.ts","sourceRoot":"","sources":["../../src/tools/auth-surface-analyzer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mCAAmC,CAAC;AAW7D,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,GAAG,EAAE,CAAC,CAwKhB"}

package/dist/tools/auth-surface-analyzer.js

@@ -110,16 +110,32 @@ export async function analyzeAuthSurfaceGaps(url, detection, timeoutMs) {
         const hasEmailLink = await page.getByText(/magic link|email.*link|passwordless/i).count();
         const hasOAuthUi = detection.oauthButtons.length > 0 ||
             (await page.getByText(/sign in with|continue with google|microsoft|github/i).count()) > 0;
-        if (hasOAuthUi && !hasPassword && !hasEmailLink) {
-            gaps.push({
-                id: randomUUID(),
-                path: '/',
-                severity: 'medium',
-                category: 'auth-surface',
-                reason: 'OAuth-only entry with no visible password or magic-link fallback.',
-                description: 'Users who cannot use a social IdP need another path (email/password, help, or support).',
-                recommendation: 'Add a documented fallback (email/password, help desk link, or alternate IdP).',
-            });
+        const formLoginFallbacks = (detection.authOptions ?? []).filter((o) => o.type === 'form-login');
+        const hasFormLoginFallback = formLoginFallbacks.length > 0;
+        if (detection.type === 'oauth' && hasOAuthUi && !hasPassword && !hasEmailLink) {
+            if (hasFormLoginFallback) {
+                const labels = formLoginFallbacks.map((o) => o.label).join(', ');
+                gaps.push({
+                    id: randomUUID(),
+                    path: '/',
+                    severity: 'low',
+                    category: 'auth-surface',
+                    reason: `OAuth-primary login with form-login fallback detected via: ${labels}`,
+                    description: 'A form-based login path exists alongside OAuth. Automate via type="form-login" using the selectors in authOptions.',
+                    recommendation: `Automatable form option(s): ${labels}. Configure type="form-login" with credentials and selectors from detectedAuth.authOptions.`,
+                });
+            }
+            else {
+                gaps.push({
+                    id: randomUUID(),
+                    path: '/',
+                    severity: 'medium',
+                    category: 'auth-surface',
+                    reason: 'OAuth-only entry with no visible password or magic-link fallback.',
+                    description: 'Users who cannot use a social IdP need another path (email/password, help, or support).',
+                    recommendation: 'Add a documented fallback (email/password, help desk link, or alternate IdP).',
+                });
+            }
         }
         const errorSelectors = '[role="alert"], [data-testid*="error" i], .error, .alert-danger, [class*="error" i]';
         const errCount = await page.locator(errorSelectors).count();

package/dist/tools/automation-maturity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"automation-maturity.d.ts","sourceRoot":"","sources":["../../src/tools/automation-maturity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAA+B,MAAM,0CAA0C,CAAC;AAiDhH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,YAAY,GAAG,kBAAkB,CA6HhF"}
+{"version":3,"file":"automation-maturity.d.ts","sourceRoot":"","sources":["../../src/tools/automation-maturity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EACV,kBAAkB,EAGnB,MAAM,0CAA0C,CAAC;AAiDlD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,YAAY,GAAG,kBAAkB,CAuLhF"}

package/dist/tools/automation-maturity.js

@@ -97,16 +97,32 @@ export function computeAutomationMaturity(repo) {
         evidence: fwEvidence,
         recommendations: frameworkScore >= 80 ? [] : ['Standardize on Playwright or Cypress for E2E against deployed URLs.'],
     };
-    const hygienePenalty = Math.min(100, repo.missingTestIds.length * 6);
-    const hygieneScore = Math.max(0, 100 - hygienePenalty);
+    const missingIds = repo.missingTestIds.length;
+    const interactiveTsxScanned = repo.interactiveTsxFilesScanned ?? missingIds;
+    let hygieneScore = 0;
+    let hygieneApplicability = 'applicable';
+    let hygieneReason;
+    const hygieneEvidence = [];
+    if (interactiveTsxScanned === 0) {
+        hygieneApplicability = 'unknown';
+        hygieneReason = 'No interactive TSX files scanned — cannot compute a missing-id ratio honestly.';
+        hygieneEvidence.push(hygieneReason);
+    }
+    else {
+        const missingRatio = missingIds / interactiveTsxScanned;
+        hygieneScore = Math.round(Math.max(0, 100 * (1 - missingRatio)));
+        hygieneEvidence.push(`${missingIds}/${interactiveTsxScanned} interactive TSX file(s) lacked data-testid (heuristic scan).`);
+    }
     const hygieneDim = {
         dimension: 'test-id-hygiene',
         score: hygieneScore,
         weight: W_TEST_ID,
-        evidence: [
-            `${repo.missingTestIds.length} TSX file(s) with interactive markup but no data-testid (heuristic scan).`,
-        ],
-        recommendations: hygieneScore >= 85 ? [] : ['Add stable data-testid (or role-based selectors) on interactive components used in tests.'],
+        evidence: hygieneEvidence,
+        recommendations: hygieneApplicability === 'applicable' && hygieneScore < 85
+            ? ['Add stable data-testid (or role-based selectors) on interactive components used in tests.']
+            : [],
+        applicability: hygieneApplicability,
+        ...(hygieneReason && { reason: hygieneReason }),
     };
     const ci = hasCiAtRoot(repo.repoPath);
     const ciDim = {
@@ -117,36 +133,75 @@ export function computeAutomationMaturity(repo) {
         recommendations: ci.ok ? [] : ['Add a CI workflow that runs unit/E2E tests on every PR.'],
     };
     const authRe = /\/(login|auth|signin)(\/|$)/i;
+    const authRouteFileRe = /(login|auth|signin)/i;
     const authCovered = repo.testFiles.some((tf) => tf.coveredPaths.some((c) => authRe.test(c)));
-    const authScore = authCovered ? 90 : 25;
+    const repoHasAuthRoute = repo.routes.some((r) => authRe.test(r.path));
+    const repoHasAuthTestFile = repo.testFiles.some((tf) => authRouteFileRe.test(tf.file));
+    const repoHasAnyAuthSignal = repoHasAuthRoute || repoHasAuthTestFile || authCovered;
+    let authScore = 0;
+    let authApplicability = 'applicable';
+    let authReason;
+    const authEvidence = [];
+    if (!repoHasAnyAuthSignal) {
+        authApplicability = 'not_applicable';
+        authReason = 'No auth routes, auth-named test files, or auth path coverage detected — repo appears auth-free.';
+        authEvidence.push(authReason);
+    }
+    else {
+        authScore = authCovered ? 90 : 25;
+        authEvidence.push(authCovered
+            ? 'At least one test references /login, /auth, or /signin in coveredPaths.'
+            : 'Repo has auth-shaped routes or test files but no auth-route coverage in extracted test path strings.');
+    }
     const authDim = {
         dimension: 'auth-test-coverage',
         score: authScore,
         weight: W_AUTH_TESTS,
-        evidence: authCovered
-            ? ['At least one test references /login, /auth, or /signin in coveredPaths.']
-            : ['No obvious auth-route coverage in extracted test path strings.'],
-        recommendations: authCovered ? [] : ['Add focused tests for sign-in and post-auth landing behavior.'],
+        evidence: authEvidence,
+        recommendations: authApplicability === 'applicable' && !authCovered
+            ? ['Add focused tests for sign-in and post-auth landing behavior.']
+            : [],
+        applicability: authApplicability,
+        ...(authReason && { reason: authReason }),
     };
     const cypressE2e = repo.testFiles.filter((t) => t.type === 'cypress-e2e').length;
     const cypressComp = repo.testFiles.filter((t) => t.type === 'cypress-component').length;
     const cypressTotal = cypressE2e + cypressComp;
-    const compRatioScore = cypressTotal === 0 ? 50 : Math.round((100 * cypressComp) / cypressTotal);
+    let compRatioScore = 0;
+    let compApplicability = 'applicable';
+    let compReason;
+    const compEvidence = [];
+    if (cypressTotal === 0) {
+        compApplicability = 'not_applicable';
+        compReason = 'No Cypress (e2e or component) tests detected — component-test-ratio does not apply.';
+        compEvidence.push(compReason);
+    }
+    else {
+        compRatioScore = Math.round((100 * cypressComp) / cypressTotal);
+        compEvidence.push(`Cypress e2e files (matched): ${cypressE2e}, component: ${cypressComp}.`);
+    }
     const compDim = {
         dimension: 'component-test-ratio',
         score: compRatioScore,
         weight: W_COMPONENT_RATIO,
-        evidence: [
-            `Cypress e2e files (matched): ${cypressE2e}, component: ${cypressComp}.`,
-        ],
-        recommendations: cypressComp === 0 || cypressTotal === 0
-            ? []
-            : ['Balance component vs E2E Cypress tests so critical flows stay fast in CI.'],
+        evidence: compEvidence,
+        recommendations: compApplicability === 'applicable' && cypressComp > 0
+            ? ['Balance component vs E2E Cypress tests so critical flows stay fast in CI.']
+            : [],
+        applicability: compApplicability,
+        ...(compReason && { reason: compReason }),
     };
     const dimensions = [breadthDim, frameworkDim, hygieneDim, ciDim, authDim, compDim];
-    const overallScore = Math.round(dimensions.reduce((s, d) => s + d.score * d.weight, 0));
+    // Overall score normalizes over applicable dimensions only.
+    // overallScore = round( Σ score_i * weight_i / Σ weight_i ) for i ∈ applicable.
+    // If no dimension is applicable (degenerate repo), overall = 0 and level = L1.
+    const applicableDims = dimensions.filter((d) => (d.applicability ?? 'applicable') === 'applicable');
+    const weightSum = applicableDims.reduce((s, d) => s + d.weight, 0);
+    const overallScore = weightSum > 0
+        ? Math.round(applicableDims.reduce((s, d) => s + d.score * d.weight, 0) / weightSum)
+        : 0;
     const { level, label } = scoreLevel(overallScore);
-    const topRecommendations = [...dimensions]
+    const topRecommendations = [...applicableDims]
         .sort((a, b) => a.score - b.score)
         .flatMap((d) => d.recommendations)
         .filter(Boolean)
@@ -159,5 +214,6 @@ export function computeAutomationMaturity(repo) {
         label,
         dimensions,
         topRecommendations,
+        scoreFormula: 'overallScore = round( Σ (score * weight) / Σ weight ) for applicable dimensions only. not_applicable and unknown dimensions are excluded from the denominator.',
     });
 }

package/dist/tools/repo-scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repo-scanner.d.ts","sourceRoot":"","sources":["../../src/tools/repo-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAmC3F,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAyItE"}
+{"version":3,"file":"repo-scanner.d.ts","sourceRoot":"","sources":["../../src/tools/repo-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAmC3F,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA8ItE"}

package/dist/tools/repo-scanner.js

@@ -137,12 +137,16 @@ export async function scanRepo(repoPath) {
         ignore: [...IGNORE_PATTERNS, '**/*.spec.tsx'],
     });
     const missingTestIds = [];
+    let interactiveTsxFilesScanned = 0;
     for (const file of tsxFiles) {
         const rel = toPosix(relative(repoPath, file));
         const content = await readFile(file, 'utf8');
         const hasInteractive = content.includes('<button') || content.includes('<input') || content.includes('<a ');
-        if (hasInteractive && !content.includes('data-testid')) {
-            missingTestIds.push(rel);
+        if (hasInteractive) {
+            interactiveTsxFilesScanned += 1;
+            if (!content.includes('data-testid')) {
+                missingTestIds.push(rel);
+            }
         }
     }
     const base = {
@@ -151,6 +155,7 @@ export async function scanRepo(repoPath) {
         routes,
         testFiles,
         missingTestIds: [...new Set(missingTestIds)],
+        interactiveTsxFilesScanned,
         cypressStructure: {
             detected: cypressRoot.length > 0,
             e2eFolder: e2eFolder[0],