eaa-kit 0.2.1 → 0.4.0

package/dist/collect-CFM8gEVv.js

@@ -0,0 +1,134 @@
+import { i as toPosix, t as exists } from "./fs-BmPtmFke.js";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { glob } from "tinyglobby";
+//#region src/audit/collect.ts
+/** Every HTML document a static build is expected to emit. */
+const DEFAULT_INCLUDE = ["**/*.html", "**/*.htm"];
+/** Vendored and tooling directories are never part of the shipped site. */
+const DEFAULT_EXCLUDE = ["**/node_modules/**", "**/.git/**"];
+/** Number of files read in parallel; keeps large builds under the fd limit. */
+const READ_CONCURRENCY = 24;
+/** A UTF-8 byte-order mark is not markup, and jsdom treats it as text. */
+function stripBom(html) {
+	return html.charCodeAt(0) === 65279 ? html.slice(1) : html;
+}
+/**
+* Thrown when the build directory itself is unusable. A missing or wrong
+* `dist/` is a user mistake worth reporting loudly, unlike a directory that
+* simply holds no HTML.
+*/
+var BuildDirectoryError = class extends Error {
+	dir;
+	name = "BuildDirectoryError";
+	constructor(message, dir) {
+		super(message);
+		this.dir = dir;
+	}
+};
+/**
+* Glob HTML files out of a build directory and read them.
+*
+* Returns pages sorted by relative path so reports and snapshots are stable
+* across platforms. An empty array means "no HTML found" — the caller decides
+* whether that is an error.
+*/
+async function collectPages(dir, options = {}) {
+	const root = path.resolve(dir);
+	await assertDirectory(root, dir);
+	const relativePaths = (await glob(options.include ?? DEFAULT_INCLUDE, {
+		cwd: root,
+		ignore: options.exclude ?? DEFAULT_EXCLUDE,
+		onlyFiles: true,
+		dot: false,
+		absolute: false
+	})).map(toPosix).sort();
+	const pages = [];
+	for (let i = 0; i < relativePaths.length; i += READ_CONCURRENCY) {
+		const batch = relativePaths.slice(i, i + READ_CONCURRENCY);
+		const read = await Promise.all(batch.map((relativePath) => readPage(root, relativePath, options.onUnreadable)));
+		for (const page of read) if (page !== void 0) pages.push(page);
+	}
+	return pages;
+}
+async function assertDirectory(root, original) {
+	let stats;
+	try {
+		stats = await stat(root);
+	} catch (cause) {
+		if (cause.code === "ENOENT") throw new BuildDirectoryError(`Build directory not found: ${original}`, root);
+		throw new BuildDirectoryError(`Build directory is not readable: ${original} (${cause.message})`, root);
+	}
+	if (!stats.isDirectory()) throw new BuildDirectoryError(`Build path is not a directory: ${original}`, root);
+}
+async function readPage(root, relativePath, onUnreadable) {
+	const absolutePath = path.join(root, relativePath);
+	try {
+		return {
+			absolutePath,
+			relativePath,
+			html: stripBom(await readFile(absolutePath, "utf8"))
+		};
+	} catch (cause) {
+		if (onUnreadable === void 0) throw cause;
+		onUnreadable(relativePath, cause.message);
+		return;
+	}
+}
+/**
+* What to suggest when a directory holds no HTML, or is not there at all.
+*
+* Nearly always the wrong directory rather than a site with no pages, and the
+* commonest way to arrive is a framework whose build emits no browsable HTML —
+* so rather than repeating "check the path", this works out what the project is
+* and names the next step for it. Where static output is not possible at all,
+* that step is `--url` rather than advice that cannot apply.
+*/
+async function emptyDirectoryHint(dir, cwd = process.cwd()) {
+	const head = await exists(dir, cwd) ? `${dir} holds no HTML files.` : `${dir} does not exist.`;
+	const { detectFramework } = await import("./frameworks-etFg_O8K.js");
+	const { readPackageJson } = await import("./project-MFrXcw1M.js");
+	const detected = await detectFramework(cwd, await readPackageJson(cwd));
+	if (detected !== void 0) return frameworkAdvice(head, detected, cwd, dir);
+	return await siblingAdvice(head, cwd, dir) ?? generic(head);
+}
+/** Advice built from what the registry knows about this framework. */
+async function frameworkAdvice(head, detected, cwd, dir) {
+	const { framework, outputs } = detected;
+	const given = dir.replace(/^\.\//, "");
+	for (const output of outputs) if (output !== given && await exists(output, cwd)) return `${head} ${framework.name} writes to ${output}/, not ${dir}.\n  Try: eaa-kit audit ./${output}`;
+	const lines = [`${head} This is ${article(framework.name)} ${framework.name} project.`];
+	if (outputs.length === 0) {
+		lines.push(`  It renders every page on a server and writes no HTML to disk, so there is`, `  no build directory to audit. Start it, then audit what it serves:`, ...framework.serveCommand === void 0 ? [] : [`    ${framework.serveCommand}`], "    eaa-kit audit --url http://localhost:8000");
+		return lines.join("\n");
+	}
+	if (framework.staticOutput !== void 0) lines.push(`  Static output takes ${framework.staticOutput.needs} — ${framework.staticOutput.how},`, `  then: eaa-kit audit ./${outputs[0]}`);
+	else if (outputs.length === 1 && outputs[0] === given) lines.push(`  That is where it writes, so the build has not run yet — or it failed.`);
+	else lines.push(`  It writes to ${outputs.map((output) => `${output}/`).join(" or ")}. Run your build, then:`, `    eaa-kit audit ./${outputs[0]}`);
+	if (framework.serves) lines.push("  A site that renders on a server cannot be written to disk at all. Audit it", "  running instead:", "    eaa-kit audit --url http://localhost:3000");
+	return lines.join("\n");
+}
+/** Naming a build directory that is actually there beats listing the usual ones. */
+async function siblingAdvice(head, cwd, dir) {
+	const { FALLBACK_OUTPUTS } = await import("./frameworks-etFg_O8K.js");
+	const given = dir.replace(/^\.\//, "");
+	const others = (await Promise.all(FALLBACK_OUTPUTS.map(async (name) => name !== given && await exists(name, cwd) ? name : void 0))).filter((name) => name !== void 0);
+	if (others.length === 0) return void 0;
+	return `${head} This project also has ${others.map((name) => `${name}/`).join(", ")} — try one of those.`;
+}
+function generic(head) {
+	return `${head} Point eaa-kit at the directory your build fills with .html files —\n  commonly dist/, build/, out/ or _site/, depending on the builder.
+  If your site renders on a server and never writes HTML, audit it running:
+    eaa-kit audit --url http://localhost:3000`;
+}
+/**
+* "a Next.js project", "an Eleventy project".
+*
+* By letter rather than by sound, which is wrong for words like "hour" and
+* right for every framework name in the registry.
+*/
+function article(name) {
+	return /^[aeiou]/i.test(name) ? "an" : "a";
+}
+//#endregion
+export { stripBom as i, collectPages as n, emptyDirectoryHint as r, BuildDirectoryError as t };

package/dist/command-D8l_oYbV.js

@@ -0,0 +1,77 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import pc from "picocolors";
+//#region src/cli/command.ts
+/**
+* What every command does around the audit itself: say what is happening, run
+* the engine, and put the document somewhere.
+*
+* `audit` and `baseline` are siblings — one reports what a run found and the
+* other writes it down — so they take the same flags, choose between the same
+* two engines and fail on the same setup problems. Keeping that in one place is
+* what stops the two commands drifting into disagreeing about what a run is.
+*/
+/** Progress and diagnostics go to stderr, so the report can be piped away. */
+function note(message) {
+	process.stderr.write(pc.dim(`${message}\n`));
+}
+function warn(message) {
+	process.stderr.write(`${pc.yellow("warning")} ${message}\n`);
+}
+function fail(message) {
+	process.stderr.write(`${pc.red("error")} ${message}\n`);
+}
+/**
+* Advice the reader should not miss, without the `warning` prefix: nothing has
+* gone wrong, but what happens next is theirs to get right.
+*/
+function advise(message) {
+	process.stderr.write(pc.yellow(`${message}\n`));
+}
+/**
+* Audit the pages with whichever engine was asked for.
+*
+* Returns undefined when the browser was asked for and is not usable, having
+* already said so: Playwright missing is a setup problem with a specific fix,
+* not a crash, and both commands turn it into exit 2.
+*/
+async function runEngine(pages, options) {
+	const runnerOptions = {
+		cwd: options.cwd,
+		...options.baseUrl === void 0 ? {} : { baseUrl: options.baseUrl },
+		...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+	};
+	if (!options.browser) {
+		const { runPooledAudit } = await import("./pool-BMevaLWD.js");
+		return runPooledAudit(pages, {
+			...runnerOptions,
+			...options.concurrency === void 0 ? {} : { concurrency: options.concurrency }
+		});
+	}
+	const { BrowserUnavailableError, runBrowserAudit } = await import("./playwright-BWniOain.js");
+	try {
+		return await runBrowserAudit(options.directory, pages, runnerOptions);
+	} catch (cause) {
+		if (cause instanceof BrowserUnavailableError) {
+			fail(cause.message);
+			return;
+		}
+		throw cause;
+	}
+}
+/**
+* Write a document to `output`, or to stdout when there is none. Parent
+* directories are created, since a report path in CI usually names one that is
+* not there yet.
+*/
+async function emitDocument(body, output, cwd) {
+	if (output === void 0) {
+		process.stdout.write(body);
+		return;
+	}
+	const target = path.resolve(cwd, output);
+	await mkdir(path.dirname(target), { recursive: true });
+	await writeFile(target, body, "utf8");
+}
+//#endregion
+export { runEngine as a, note as i, emitDocument as n, warn as o, fail as r, advise as t };

package/dist/component-C3GL1Mnu.js

@@ -0,0 +1,146 @@
+import { i as toPosix } from "./fs-BmPtmFke.js";
+import { t as collapse } from "./text-CKKpzkYM.js";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { glob } from "tinyglobby";
+//#region src/audit/component.ts
+/**
+* Which source file a failing element was written in.
+*
+* Route mapping names the page, and on a site built from components the page is
+* not where the fix goes: a header with a missing `alt` appears on every page
+* that renders it and is written in none of them. The Issues view can already
+* tell that one element is shared across pages; this says which file to open.
+*
+* The method is deliberately dumb. Take a literal out of the failing markup —
+* an image path, a link target, an id — and look for it in the project's own
+* source. Frameworks do emit source positions, but only in development builds,
+* and an auditor runs against production output. A literal survives every
+* compiler.
+*
+* It never guesses. A literal found in two files names neither, because a wrong
+* file is worse than none: it sends somebody to edit code that was not the
+* cause, and costs more than the minute it saved.
+*/
+/** Where component source is expected to live. */
+const SOURCE_GLOBS = ["**/*.{tsx,jsx,ts,js,mjs,vue,svelte,astro,mdx,md,html,php,erb,twig,liquid,hbs}"];
+/** Never source: dependencies, build output, version control. */
+const NEVER = [
+	"**/node_modules/**",
+	"**/.git/**",
+	"**/dist/**",
+	"**/build/**",
+	"**/out/**",
+	"**/_site/**",
+	"**/.next/**",
+	"**/.nuxt/**",
+	"**/.svelte-kit/**",
+	"**/.output/**",
+	"**/coverage/**",
+	"**/*.min.js"
+];
+/** Files read into the index. A ceiling, not a target. */
+const MAX_FILES = 2e3;
+/** Bytes per file. A source file past this is generated or vendored. */
+const MAX_BYTES = 524288;
+/**
+* Read the project's source once, so every element can be looked up against it.
+*
+* Once rather than per element: a site with forty violations would otherwise
+* walk the tree forty times for an answer that does not change.
+*/
+async function buildComponentIndex(cwd) {
+	const found = await glob([...SOURCE_GLOBS], {
+		cwd,
+		ignore: [...NEVER],
+		onlyFiles: true,
+		dot: false
+	});
+	const files = /* @__PURE__ */ new Map();
+	for (const relative of found.slice(0, MAX_FILES).sort()) try {
+		const source = await readFile(path.resolve(cwd, relative), "utf8");
+		if (source.length <= MAX_BYTES) files.set(toPosix(relative), source);
+	} catch {}
+	return { files };
+}
+/**
+* Literals worth searching for, most distinctive first.
+*
+* An image path or a link target is written by hand and survives compilation.
+* A class name may be generated, and text content may be interpolated, so both
+* come after. Anything short is dropped: `/` appears in every file.
+*/
+function searchTermsFor(html) {
+	const terms = [];
+	const add = (value) => {
+		if (value === void 0) return;
+		const trimmed = value.trim();
+		if (trimmed.length < 4 || trimmed.includes("${")) return;
+		if (!terms.includes(trimmed)) terms.push(trimmed);
+	};
+	for (const attribute of [
+		"src",
+		"href",
+		"id",
+		"data-testid",
+		"name",
+		"action"
+	]) add(new RegExp(`\\s${attribute}\\s*=\\s*["']([^"']+)["']`, "i").exec(html)?.[1]);
+	const text = collapse(html.replace(/<[^>]*>/g, " "));
+	if (text.length >= 8) add(text.slice(0, 60));
+	return terms;
+}
+/**
+* The one source file this element was written in, if exactly one claims it.
+*
+* Returns undefined when nothing matches and when more than one does. The
+* second case is the important one: naming a file that merely happens to
+* contain the same path sends somebody to edit the wrong component.
+*
+* The position comes free. The search already has to find the literal to know
+* the file contains it, so recording where it found it costs one more scan of
+* one string — and a report that says `Header.astro:12` opens an editor where a
+* report that says `Header.astro` starts a search.
+*/
+function componentFor(index, html) {
+	for (const term of searchTermsFor(html)) {
+		const matches = [];
+		for (const [file, source] of index.files) {
+			const offset = source.indexOf(term);
+			if (offset !== -1) {
+				matches.push({
+					file,
+					offset
+				});
+				if (matches.length > 1) break;
+			}
+		}
+		const only = matches.length === 1 ? matches[0] : void 0;
+		if (only !== void 0) {
+			const source = index.files.get(only.file);
+			return {
+				file: only.file,
+				...positionOf(source, only.offset)
+			};
+		}
+	}
+}
+/** 1-based line and column of a byte offset in a source file. */
+function positionOf(source, offset) {
+	let line = 1;
+	let lineStart = 0;
+	for (let i = 0; i < offset; i += 1) if (source[i] === "\n") {
+		line += 1;
+		lineStart = i + 1;
+	}
+	return {
+		line,
+		column: offset - lineStart + 1
+	};
+}
+/** `components/Header.astro:12`, as both reports name a component. */
+function componentPath(location) {
+	return `${location.file}:${location.line}`;
+}
+//#endregion
+export { searchTermsFor as i, componentFor as n, componentPath as r, buildComponentIndex as t };

package/dist/component-DKd3EHOg.js

@@ -0,0 +1,2 @@
+import { n as componentFor, t as buildComponentIndex } from "./component-C3GL1Mnu.js";
+export { buildComponentIndex, componentFor };