bitboss-ui 3.0.0-beta.47 → 3.0.0-beta.49

package/scripts/lib/local-components.mjs

@@ -14,23 +14,52 @@
  * `unknown-component` error (a typo, an invented or removed name).
  */
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { basename, join, relative, sep } from 'node:path';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 
 const BB_NAME = /^Bb[A-Z0-9]/;
 
+/**
+ * Whether an import source is the library itself. `bitboss-ui` always is.
+ * Inside the library's own repo the showcases import the SOURCE
+ * (`@/components/BbSelect/BbSelect.vue`, `../BbSelect.vue`): the rules'
+ * `libraryImports` option lists those prefixes (empty by default, so a
+ * consumer's own `Bb*` imports stay theirs). A relative source is resolved
+ * against the importing file and matched as a path from `cwd`, so
+ * `src/components/` covers `../BbSelect.vue` from a showcase.
+ * @param {string} source
+ * @param {{ libraryImports?: string[], filename?: string, cwd?: string }} [library]
+ */
+export function isLibrarySource(source, library) {
+	if (source === 'bitboss-ui' || source.startsWith('bitboss-ui/')) return true;
+	const prefixes = library?.libraryImports ?? [];
+	if (!prefixes.length) return false;
+	let candidate = source;
+	if (source.startsWith('.') && library?.filename) {
+		candidate = relative(
+			library.cwd ?? process.cwd(),
+			resolve(dirname(library.filename), source)
+		)
+			.split(sep)
+			.join('/');
+	}
+	return prefixes.some((prefix) => candidate.startsWith(prefix));
+}
+
 /**
  * `Bb*` names a file imports from anywhere but `bitboss-ui` (its subpaths
- * included) — default and named imports alike. Type-only imports are skipped.
+ * included, and the `libraryImports` prefixes, see `isLibrarySource`) —
+ * default and named imports alike. Type-only imports are skipped.
  * @param {string} code
+ * @param {{ libraryImports?: string[], filename?: string, cwd?: string }} [library]
  * @returns {Map<string, number>} name → 1-based line of the import
  */
-export function localBbImports(code) {
+export function localBbImports(code, library) {
 	const found = new Map();
 	const IMPORT = /\bimport\s+(type\s+)?([\s\S]*?)\s+from\s*['"]([^'"]+)['"]/g;
 	for (const match of code.matchAll(IMPORT)) {
 		const [, typeOnly, clause, source] = match;
 		if (typeOnly) continue;
-		if (source === 'bitboss-ui' || source.startsWith('bitboss-ui/')) continue;
+		if (isLibrarySource(source, library)) continue;
 		const line = code.slice(0, match.index).split('\n').length;
 		const names = [];
 		const defaultName = /^\s*([A-Za-z_$][\w$]*)/.exec(

package/scripts/lib/locale-check.mjs

@@ -0,0 +1,165 @@
+/**
+ * `check`: a locale the library does not ship (owner ruling 2026-10-07). The
+ * locale list is fixed and typed, so `locale: 'en-UK'` is a type error where
+ * TypeScript sees it — but a `vite.config.js`, a Nuxt config or a
+ * `setConfig({ locale })` in a plain `<script>` is not type-checked, and the
+ * plugin's own warning only reaches whoever reads the dev-server log.
+ *
+ * `unknown-locale` reads the build plugin's inline `locale` / `enabledLocales`
+ * literals and every `setConfig({ locale: '…' })` literal, and names the
+ * nearest shipped locale (`en-UK` → `en-GB`, `de-LU` → `de`). The shipped list
+ * is the manifest's `BuiltinLocaleKey` values; the aliases the runtime takes
+ * (`zh-cn`, `pt`, `it-IT`) are derived the way the runtime defines them: any
+ * case, and the full code of a language's default region (CLDR likely
+ * subtags, `Intl.Locale.prototype.maximize`). Regexes over comment-blanked
+ * source, the same trade the rest of `check` makes.
+ */
+
+import { readFileSync } from 'node:fs';
+import { readPluginOptions } from './hand-imported-styles.mjs';
+
+export const UNKNOWN_LOCALE_KIND = 'unknown-locale';
+
+/** The canonical keys, from the manifest. */
+const shippedKeys = (manifest) => {
+	const types = manifest?.types;
+	const list =
+		types instanceof Map ? [...types.values()] : Object.values(types ?? {});
+	return list.find((type) => type?.name === 'BuiltinLocaleKey')?.values ?? [];
+};
+
+/** `language-REGION` of a tag's likely subtags, or `undefined`. */
+const likely = (tag) => {
+	try {
+		const { language, region } = new Intl.Locale(tag).maximize();
+		return region ? `${language}-${region}` : language;
+	} catch {
+		return undefined;
+	}
+};
+
+/**
+ * Resolves a locale as written to its canonical key, or `undefined`.
+ * @param {string} input
+ * @param {string[]} keys the canonical keys
+ */
+export function resolveLocale(input, keys) {
+	const lower = input.trim().replace(/_/g, '-').toLowerCase();
+	const byLower = new Map(keys.map((key) => [key.toLowerCase(), key]));
+	if (byLower.has(lower)) return byLower.get(lower);
+	const [language] = lower.split('-');
+	const full = likely(lower)?.toLowerCase();
+	// A bare language whose default region is a key (`pt` → `pt-BR`).
+	if (!lower.includes('-') && full && byLower.has(full))
+		return byLower.get(full);
+	// The default region spelled out (`it-IT` → `it`, `en-US` → `en`).
+	if (byLower.has(language) && likely(language)?.toLowerCase() === lower)
+		return byLower.get(language);
+	return undefined;
+}
+
+/** The nearest shipped locale: same language, `UK` read as `GB`; else the bare language. */
+export function nearestLocale(input, keys) {
+	if (resolveLocale(input, keys)) return undefined;
+	const [language, region] = input.trim().replace(/_/g, '-').split('-');
+	if (!language) return undefined;
+	const fixed = region
+		? ({ UK: 'GB' }[region.toUpperCase()] ?? region.toUpperCase())
+		: undefined;
+	return (
+		(fixed && resolveLocale(`${language}-${fixed}`, keys)) ||
+		resolveLocale(language, keys)
+	);
+}
+
+const lineAt = (code, index) => code.slice(0, index).split('\n').length;
+const blank = (text) => text.replace(/[^\n]/g, ' ');
+const blankComments = (code) =>
+	code
+		.replace(/\/\*[\s\S]*?\*\//g, blank)
+		.replace(/(^|[^:\\])(\/\/[^\n]*)/g, (_, before, c) => before + blank(c))
+		.replace(/<!--[\s\S]*?-->/g, blank);
+
+const finding = (file, code, index, value, keys, where) => {
+	const near = nearestLocale(value, keys);
+	return {
+		file,
+		line: lineAt(code, index),
+		kind: UNKNOWN_LOCALE_KIND,
+		component: 'bitboss-ui',
+		attr: 'locale',
+		message: `${where} \`'${value}'\` is not a locale bitboss-ui ships${near ? ` — did you mean '${near}'?` : ''} Strings fall back to the default locale. The list: \`BuiltinLocaleKey\` (guides/installation-and-plugin-setup.md § Locales).`,
+		...(near ? { suggestion: near } : {}),
+	};
+};
+
+/** Every `locale: '…'` / `enabledLocales: [ … ]` literal in `text`, offset by `base`. */
+function optionLiterals(text, base) {
+	const out = [];
+	for (const match of text.matchAll(/\blocale\s*:\s*(['"])([^'"\n]+)\1/g))
+		out.push({
+			value: match[2],
+			index: base + match.index,
+			where: '`locale`',
+		});
+	for (const match of text.matchAll(/\benabledLocales\s*:\s*\[([^\]]*)\]/g)) {
+		const start = base + match.index + match[0].indexOf('[');
+		for (const entry of match[1].matchAll(/(['"])([^'"\n]+)\1/g))
+			out.push({
+				value: entry[2],
+				index: start + 1 + entry.index,
+				where: '`enabledLocales` entry',
+			});
+	}
+	return out;
+}
+
+/**
+ * Locales the library does not ship, in the build config and in
+ * `setConfig({ locale })` calls.
+ * @param {string} projectRoot
+ * @param {{ path: string, relPath: string }[]} files
+ * @param {object} manifest
+ * @param {(path: string) => string} [read]
+ */
+export function unknownLocaleFindings(
+	projectRoot,
+	files,
+	manifest,
+	read = (path) => readFileSync(path, 'utf-8')
+) {
+	const keys = shippedKeys(manifest);
+	if (!keys.length) return [];
+	const findings = [];
+	const plugin = readPluginOptions(projectRoot);
+	if (plugin?.options) {
+		const base = plugin.code.indexOf(plugin.options);
+		for (const { value, index, where } of optionLiterals(plugin.options, base))
+			if (!resolveLocale(value, keys))
+				findings.push(
+					finding(plugin.config, plugin.code, index, value, keys, where)
+				);
+	}
+	for (const { path, relPath } of files) {
+		if (!/\.(?:vue|[cm]?[jt]sx?)$/.test(relPath) || relPath === plugin?.config)
+			continue;
+		let code;
+		try {
+			code = blankComments(read(path));
+		} catch {
+			continue;
+		}
+		if (!code.includes('setConfig')) continue;
+		const CALL =
+			/\bsetConfig\s*\(\s*\{[^}]*?\blocale\s*:\s*(['"])([^'"\n]+)\1/g;
+		for (const match of code.matchAll(CALL)) {
+			const value = match[2];
+			if (resolveLocale(value, keys)) continue;
+			const index = match.index + match[0].lastIndexOf(value) - 1;
+			findings.push(
+				finding(relPath, code, index, value, keys, '`setConfig({ locale })`')
+			);
+		}
+	}
+	return findings;
+}

package/scripts/lib/portal-names.mjs

@@ -0,0 +1,458 @@
+/**
+ * Portal names (Q63.8, owner 2026-10-06): a named portal is a string on one
+ * side and a `<…Portal name>` on the other, so a typo, a portal of the wrong
+ * family or a forgotten declaration opens nothing, silently. Three findings:
+ *
+ * - `unknown-portal` (error): a call site names a portal no file declares,
+ *   with a did-you-mean;
+ * - `portal-family-mismatch` (error): the name belongs to the other family
+ *   (a hover-card portal opened by `v-bb-popover`);
+ * - `unused-portal` (warning): a declared portal nothing opens.
+ *
+ * Call sites: `v-bb-hover-card` / `v-bb-popover` with `"'name'"` or
+ * `{ portal: 'name' }`, and `confirm({ portal: 'name' })` in a script.
+ * Declarations: `<BbHoverCardPortal | BbPopoverPortal | BbConfirmPortal
+ * name="x">`. Everything else is dynamic and says nothing: a `:name` binding
+ * leaves its family's call sites unjudged, a non-literal call site (a variable,
+ * a template literal, `confirm(options)`) leaves its family's declarations
+ * unjudged, and a declared name that appears as ANY string literal in the
+ * project counts as opened. A false report costs more than a missed one.
+ *
+ * The project is scanned once per root (cached, like unimported-components),
+ * tests skipped. `check` and the ESLint rules (`bitboss-ui/portal-names`,
+ * `bitboss-ui/unused-portal`) share this module.
+ */
+import { readFileSync } from 'node:fs';
+import { parse } from 'vue/compiler-sfc';
+import { walk } from './unimported-components.mjs';
+import { nearestName } from './validate-bb-markup.mjs';
+
+/** Each family: its declaration tag, and how its call sites are written. */
+export const PORTAL_FAMILIES = {
+	hoverCard: {
+		component: 'BbHoverCardPortal',
+		directive: 'bb-hover-card',
+		opener: 'v-bb-hover-card',
+		openWith: (name) => `v-bb-hover-card="'${name}'"`,
+	},
+	popover: {
+		component: 'BbPopoverPortal',
+		directive: 'bb-popover',
+		opener: 'v-bb-popover',
+		openWith: (name) => `v-bb-popover="'${name}'"`,
+	},
+	confirm: {
+		component: 'BbConfirmPortal',
+		directive: null,
+		opener: 'confirm()',
+		openWith: (name) => `confirm({ portal: '${name}' })`,
+	},
+};
+
+const FAMILY_BY_COMPONENT = new Map(
+	Object.entries(PORTAL_FAMILIES).map(([family, f]) => [f.component, family])
+);
+const FAMILY_BY_DIRECTIVE = new Map(
+	Object.entries(PORTAL_FAMILIES)
+		.filter(([, f]) => f.directive)
+		.map(([family, f]) => [f.directive, family])
+);
+
+const NODE_ELEMENT = 1;
+const PROP_ATTRIBUTE = 6;
+const PROP_DIRECTIVE = 7;
+
+const pascal = (tag) =>
+	tag.includes('-')
+		? tag.replace(/(?:^|-)([a-z0-9])/g, (_, c) => c.toUpperCase())
+		: tag;
+
+/** `'name'` / `"name"` as a whole expression, else null. */
+const stringLiteral = (text) =>
+	/^\s*(['"])([^'"\\\n]+)\1\s*$/.exec(text ?? '')?.[2] ?? null;
+
+const LITERALS = /(['"])([^'"\\\n]{1,120})\1/g;
+
+/** Text that may hold a portal site: a quick test before any parse. */
+export const MAY_HAVE_PORTALS =
+	/Portal|portal|confirm|bb-popover|bb-hover-card/;
+
+/** Every quoted string in a piece of code: a name there may open a portal. */
+const literalsIn = (text, into) => {
+	for (const [, , value] of (text ?? '').matchAll(LITERALS)) into.add(value);
+};
+
+/**
+ * A PascalCase identifier the file imports or declares: a component portal,
+ * never a name. Anything else non-literal is dynamic.
+ */
+const isComponentBinding = (identifier, code) =>
+	/^[A-Z][\w$]*$/.test(identifier) &&
+	(new RegExp(`\\bimport\\b[^;]*\\b${identifier}\\b[^;]*\\bfrom\\b`).test(
+		code
+	) ||
+		new RegExp(`\\b(?:const|let|var|function|class)\\s+${identifier}\\b`).test(
+			code
+		));
+
+/**
+ * What a `portal` value is: `{ name }`, `{ component: true }` or
+ * `{ dynamic: true }`.
+ */
+const classifyPortalValue = (text, code) => {
+	const name = stringLiteral(text);
+	if (name) return { name };
+	const trimmed = (text ?? '').trim();
+	if (/^[A-Za-z_$][\w$]*$/.test(trimmed) && isComponentBinding(trimmed, code))
+		return { component: true };
+	return { dynamic: true };
+};
+
+/**
+ * The `portal` key of an object literal's source: a literal name (with its
+ * line offset inside `text`), a component, dynamic, or absent.
+ */
+const portalKey = (text, code) => {
+	const keyed = /\bportal\s*:\s*/.exec(text);
+	if (keyed) {
+		const start = keyed.index + keyed[0].length;
+		const rest = text.slice(start);
+		const quoted = /^(['"])([^'"\\\n]+)\1/.exec(rest);
+		const offset = (text.slice(0, start).match(/\n/g) ?? []).length;
+		if (quoted) return { name: quoted[2], offset };
+		const ident = /^([A-Za-z_$][\w$]*)\s*(?:[,}\n]|$)/.exec(rest)?.[1];
+		if (ident && isComponentBinding(ident, code)) return { component: true };
+		return { dynamic: true };
+	}
+	// `{ portal, portalProps }`: shorthand, a variable.
+	if (/[{,]\s*portal\s*[,}]/.test(text)) return { dynamic: true };
+	return null;
+};
+
+/** The text of a call's arguments, from the `(` at `open`. */
+const callArguments = (code, open) => {
+	let depth = 0;
+	let quote = null;
+	for (let i = open; i < code.length; i++) {
+		const c = code[i];
+		if (quote) {
+			if (c === '\\') i++;
+			else if (c === quote) quote = null;
+			continue;
+		}
+		if (c === "'" || c === '"' || c === '`') quote = c;
+		else if (c === '(') depth++;
+		else if (c === ')' && --depth === 0) return code.slice(open + 1, i);
+	}
+	return null;
+};
+
+const lineAt = (text, index) =>
+	(text.slice(0, index).match(/\n/g) ?? []).length;
+
+/**
+ * The script with its comments and template literals blanked (newlines
+ * kept, so lines still count): a `confirm({ portal: 'x' })` in a JSDoc
+ * example or inside a string is not a call. Quoted strings stay, they are
+ * the names.
+ */
+const maskScript = (code) => {
+	let out = '';
+	let state = null;
+	for (let i = 0; i < code.length; i++) {
+		const c = code[i];
+		const next = code[i + 1];
+		const blank = c === '\n' ? '\n' : ' ';
+		if (state === 'line') {
+			if (c === '\n') {
+				state = null;
+				out += c;
+			} else out += ' ';
+		} else if (state === 'block') {
+			if (c === '*' && next === '/') {
+				state = null;
+				out += '  ';
+				i++;
+			} else out += blank;
+		} else if (state === '`') {
+			if (c === '\\') {
+				out += '  ';
+				i++;
+			} else if (c === '`') {
+				state = null;
+				out += c;
+			} else out += blank;
+		} else if (state === "'" || state === '"') {
+			out += c;
+			if (c === '\\') {
+				out += next ?? '';
+				i++;
+			} else if (c === state || c === '\n') state = null;
+		} else if (c === '/' && next === '/') {
+			state = 'line';
+			out += '  ';
+			i++;
+		} else if (c === '/' && next === '*') {
+			state = 'block';
+			out += '  ';
+			i++;
+		} else {
+			if (c === "'" || c === '"' || c === '`') state = c;
+			out += c;
+		}
+	}
+	return out;
+};
+
+/**
+ * `confirm(…)` calls in a script: literal portals become call sites, any other
+ * argument that could carry a portal marks the confirm family dynamic.
+ */
+const scriptSites = (source, firstLine, code, sites) => {
+	const script = maskScript(source);
+	literalsIn(script, sites.literals);
+	// A template literal with no interpolation is a plain string too.
+	for (const [, value] of source.matchAll(/`([^`$\\\n]{1,120})`/g))
+		sites.literals.add(value);
+	for (const match of script.matchAll(/\bconfirm\s*\(/g)) {
+		const open = match.index + match[0].length - 1;
+		const args = callArguments(script, open);
+		if (args == null) continue;
+		const trimmed = args.trim();
+		if (!trimmed || /^(['"`])/.test(trimmed)) continue;
+		if (!trimmed.startsWith('{')) {
+			sites.dynamicCalls.add('confirm');
+			continue;
+		}
+		const portal = portalKey(trimmed, code);
+		if (!portal || portal.component) continue;
+		if (portal.dynamic) {
+			sites.dynamicCalls.add('confirm');
+			continue;
+		}
+		sites.calls.push({
+			family: 'confirm',
+			name: portal.name,
+			line:
+				firstLine +
+				lineAt(script, open) +
+				lineAt(args, args.indexOf(trimmed)) +
+				portal.offset,
+		});
+	}
+};
+
+/** A declaration's `name`: a static attribute, a literal binding, or dynamic. */
+const declarationName = (node) => {
+	for (const prop of node.props ?? []) {
+		if (prop.type === PROP_ATTRIBUTE && prop.name === 'name')
+			return { name: prop.value?.content ?? '', line: prop.loc.start.line };
+		if (
+			prop.type === PROP_DIRECTIVE &&
+			prop.name === 'bind' &&
+			prop.arg?.content === 'name'
+		) {
+			const name = stringLiteral(prop.exp?.content);
+			return name ? { name, line: prop.loc.start.line } : { dynamic: true };
+		}
+		// `v-bind="obj"`: the name may be in it.
+		if (prop.type === PROP_DIRECTIVE && prop.name === 'bind' && !prop.arg)
+			return { dynamic: true };
+	}
+	return { dynamic: true };
+};
+
+/**
+ * The portal sites of one file.
+ * @param {string} code
+ * @param {string} [path] decides `.vue` vs a script file
+ */
+export function fileSites(code, path = 'x.vue') {
+	const sites = {
+		declarations: [],
+		calls: [],
+		dynamicDeclarations: new Set(),
+		dynamicCalls: new Set(),
+		literals: new Set(),
+	};
+	if (!path.endsWith('.vue')) {
+		if (/\bconfirm\s*\(/.test(code) || /['"]/.test(code))
+			scriptSites(code, 1, code, sites);
+		return sites;
+	}
+	let descriptor;
+	try {
+		({ descriptor } = parse(code, { sourceMap: false }));
+	} catch {
+		return sites;
+	}
+	for (const block of [descriptor.script, descriptor.scriptSetup])
+		if (block) scriptSites(block.content, block.loc.start.line, code, sites);
+
+	const walkTemplate = (node) => {
+		if (!node || typeof node !== 'object') return;
+		if (node.type === NODE_ELEMENT) {
+			const family = FAMILY_BY_COMPONENT.get(pascal(node.tag));
+			if (family) {
+				const declared = declarationName(node);
+				if (declared.dynamic) sites.dynamicDeclarations.add(family);
+				else sites.declarations.push({ family, ...declared });
+			}
+			for (const prop of node.props ?? []) {
+				if (prop.type !== PROP_DIRECTIVE) continue;
+				const exp = prop.exp?.content;
+				literalsIn(exp, sites.literals);
+				const directiveFamily = FAMILY_BY_DIRECTIVE.get(prop.name);
+				if (!directiveFamily || !exp) continue;
+				const line = prop.exp.loc?.start?.line ?? prop.loc.start.line;
+				const trimmed = exp.trim();
+				if (trimmed.startsWith('{')) {
+					const portal = portalKey(trimmed, code);
+					if (!portal || portal.component) continue;
+					if (portal.dynamic) sites.dynamicCalls.add(directiveFamily);
+					else
+						sites.calls.push({
+							family: directiveFamily,
+							name: portal.name,
+							line: line + lineAt(exp, exp.indexOf(trimmed)) + portal.offset,
+						});
+					continue;
+				}
+				const value = classifyPortalValue(trimmed, code);
+				if (value.dynamic) sites.dynamicCalls.add(directiveFamily);
+				else if (value.name)
+					sites.calls.push({ family: directiveFamily, name: value.name, line });
+			}
+		}
+		for (const child of node.children ?? []) walkTemplate(child);
+	};
+	walkTemplate(descriptor.template?.ast);
+	return sites;
+}
+
+const SOURCE = /\.(?:vue|[cm]?[jt]sx?)$/;
+
+const cache = new Map();
+
+/**
+ * Every portal site of a project, scanned once per root (tests skipped).
+ * @param {string} projectRoot
+ */
+export function projectPortalIndex(projectRoot) {
+	if (cache.has(projectRoot)) return cache.get(projectRoot);
+	const index = emptyIndex();
+	for (const path of walk(projectRoot)) {
+		if (path.endsWith('.d.ts') || !SOURCE.test(path)) continue;
+		let code;
+		try {
+			code = readFileSync(path, 'utf-8');
+		} catch {
+			continue;
+		}
+		if (!MAY_HAVE_PORTALS.test(code)) {
+			// Still a source of string literals for `unused-portal`.
+			literalsIn(code, index.literals);
+			for (const [, value] of code.matchAll(/`([^`$\\\n]{1,120})`/g))
+				index.literals.add(value);
+			continue;
+		}
+		addSites(index, fileSites(code, path), path);
+	}
+	cache.set(projectRoot, index);
+	return index;
+}
+
+function emptyIndex() {
+	return {
+		/** family → name → files */
+		declared: new Map(Object.keys(PORTAL_FAMILIES).map((f) => [f, new Map()])),
+		dynamicDeclarations: new Set(),
+		dynamicCalls: new Set(),
+		literals: new Set(),
+	};
+}
+
+function addSites(index, sites, path) {
+	for (const { family, name } of sites.declarations) {
+		const byName = index.declared.get(family);
+		if (!byName.has(name)) byName.set(name, new Set());
+		byName.get(name).add(path);
+	}
+	for (const family of sites.dynamicDeclarations)
+		index.dynamicDeclarations.add(family);
+	for (const family of sites.dynamicCalls) index.dynamicCalls.add(family);
+	for (const value of sites.literals) index.literals.add(value);
+}
+
+/** For tests: forget cached project scans. */
+export const clearPortalCache = () => cache.clear();
+
+const quoteCall = (family, name) =>
+	family === 'confirm'
+		? `\`confirm({ portal: '${name}' })\``
+		: `\`${PORTAL_FAMILIES[family].openWith(name)}\``;
+
+/**
+ * The findings of one file against its project (`index`; `null` judges the
+ * file alone). The file's own sites are read fresh, so an editor sees its
+ * edits before the cached scan does.
+ * @param {string} code
+ * @param {string} path
+ * @param {ReturnType<typeof projectPortalIndex> | null} index
+ */
+export function portalFindings(code, path, index) {
+	const sites = fileSites(code, path);
+	if (!sites.calls.length && !sites.declarations.length) return [];
+	const merged = emptyIndex();
+	if (index) {
+		for (const [family, byName] of index.declared)
+			for (const [name, files] of byName)
+				merged.declared.get(family).set(name, new Set(files));
+		for (const family of index.dynamicDeclarations)
+			merged.dynamicDeclarations.add(family);
+		for (const family of index.dynamicCalls) merged.dynamicCalls.add(family);
+		for (const value of index.literals) merged.literals.add(value);
+	}
+	addSites(merged, sites, path);
+
+	const findings = [];
+	for (const { family, name, line } of sites.calls) {
+		const own = merged.declared.get(family);
+		if (own.has(name) || merged.dynamicDeclarations.has(family)) continue;
+		const f = PORTAL_FAMILIES[family];
+		const other = Object.keys(PORTAL_FAMILIES).find(
+			(g) => g !== family && merged.declared.get(g).has(name)
+		);
+		if (other) {
+			findings.push({
+				component: f.component,
+				attr: f.opener,
+				kind: 'portal-family-mismatch',
+				line,
+				message: `\`${name}\` is a \`<${PORTAL_FAMILIES[other].component}>\`, not a \`<${f.component}>\`, so ${quoteCall(family, name)} opens nothing; open it with ${quoteCall(other, name)} or declare \`<${f.component} name="${name}">\``,
+			});
+			continue;
+		}
+		const guess = nearestName(name, own.keys());
+		findings.push({
+			component: f.component,
+			attr: f.opener,
+			kind: 'unknown-portal',
+			line,
+			message: `${quoteCall(family, name)} opens nothing: no \`<${f.component} name="${name}">\` in this project${guess ? `; did you mean \`${guess}\`?` : ''}`,
+		});
+	}
+	for (const { family, name, line } of sites.declarations) {
+		if (merged.dynamicCalls.has(family) || merged.literals.has(name)) continue;
+		const f = PORTAL_FAMILIES[family];
+		findings.push({
+			component: f.component,
+			attr: 'name',
+			kind: 'unused-portal',
+			severity: 'warning',
+			line,
+			message: `no \`${f.opener}\` opens the portal \`${name}\`; open it with ${quoteCall(family, name)} or remove it`,
+		});
+	}
+	return findings;
+}