taste-lint 0.2.0 → 0.3.0

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { Command, CommanderError, Option } from "commander";
 import fs from "node:fs";
 import path from "node:path";
+import os from "node:os";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { parse } from "yaml";
@@ -9,12 +10,11 @@ import { fromMarkdown } from "mdast-util-from-markdown";
 import { gfmFromMarkdown } from "mdast-util-gfm";
 import { gfm } from "micromark-extension-gfm";
 import { parseSync } from "oxc-parser";
-import os from "node:os";
 import { mdxFromMarkdown } from "mdast-util-mdx";
 import { mdxjs } from "micromark-extension-mdxjs";
 import { styleText } from "node:util";
 //#region packages/cli/package.json
-var version = "0.2.0";
+var version = "0.3.0";
 //#endregion
 //#region src/lib/stats.ts
 const makePRNG = (seed) => {
@@ -862,7 +862,10 @@ const DEFAULT_EXCLUDE = [
 	"**/.next/**",
 	"**/.git/**",
 	"**/results/**",
-	"**/coverage/**"
+	"**/coverage/**",
+	"**/LICENSE",
+	"**/LICENSE.*",
+	"**/CHANGELOG.md"
 ];
 const globToRegExp = (glob) => {
 	let out = "^";
@@ -1071,10 +1074,12 @@ function validateConfig(raw) {
 		"smartQuotesAtBuild",
 		"docTypes",
 		"components",
-		"tailwind"
+		"tailwind",
+		"rules"
 	], "");
 	if (value.$schema !== void 0 && typeof value.$schema !== "string") invalid("$schema", "a string");
 	if (value.exclude !== void 0) strings(value.exclude, "exclude");
+	if (value.rules !== void 0) strings(value.rules, "rules");
 	if (value.smartQuotesAtBuild !== void 0 && typeof value.smartQuotesAtBuild !== "boolean") invalid("smartQuotesAtBuild", "a boolean");
 	if (value.docTypes !== void 0) {
 		if (!Array.isArray(value.docTypes)) invalid("docTypes", "an array");
@@ -1099,6 +1104,22 @@ function validateConfig(raw) {
 		}
 	}
 }
+const ruleDir = (root, raw) => {
+	const expanded = raw.replace(/^~(?=$|\/)/u, os.homedir()).replaceAll(/\$\{?(\w+)\}?/gu, (_, name) => {
+		const value = process.env[name];
+		if (!value) throw new InputError("INVALID_CONFIG", `taste-lint.config.json: rules entry ${raw} names ${name}, which is not set.`, {
+			field: "rules",
+			variable: name
+		});
+		return value;
+	});
+	const dir = path.resolve(root, expanded);
+	if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) throw new InputError("INVALID_CONFIG", `taste-lint.config.json: rules entry ${raw} is not a directory (${dir}).`, {
+		field: "rules",
+		path: dir
+	});
+	return dir;
+};
 const loadConfig = (root, defaults = []) => {
 	const absRoot = path.resolve(root);
 	try {
@@ -1133,6 +1154,7 @@ const loadConfig = (root, defaults = []) => {
 		],
 		exclude: user.exclude ?? [],
 		root: absRoot,
+		rules: (user.rules ?? []).map((raw) => ruleDir(absRoot, raw)),
 		smartQuotesAtBuild: typeof user.smartQuotesAtBuild === "boolean" ? user.smartQuotesAtBuild : detectSmartQuotesAtBuild(absRoot),
 		tailwind: { theme: user.tailwind?.theme ?? {} }
 	};
@@ -1890,11 +1912,54 @@ const smartQuotes = (prose) => prose.replaceAll(OPENING_DOUBLE, "$1“").replace
 const ellipsis = (prose) => prose.replaceAll("...", "…");
 const multiplicationSign = (prose) => prose.replaceAll(/(?<![\w.])([1-9]\d*)\s?x\s?(\d+)(?![\w.%])/gu, "$1×$2");
 const nbspValueUnit = (prose) => prose.replaceAll(/(\d) (?=(?:px|pt|em|rem|ms|min|KB|MB|GB|TB|kg|km|cm|mm|fps|%)(?![\p{L}\d]))/gu, "$1\xA0");
+const stripUtm = (prose) => prose.replaceAll(/\?utm_source=chatgpt\.com(?![\w&=-])/gu, "").replaceAll(/([?&])utm_source=chatgpt\.com&/gu, "$1").replaceAll("&utm_source=chatgpt.com", "");
+const AU_SPELLING = {
+	analyze: "analyse",
+	analyzed: "analysed",
+	apologize: "apologise",
+	behavior: "behaviour",
+	behaviors: "behaviours",
+	canceled: "cancelled",
+	canceling: "cancelling",
+	catalog: "catalogue",
+	color: "colour",
+	colored: "coloured",
+	colors: "colours",
+	customize: "customise",
+	customized: "customised",
+	favorite: "favourite",
+	favorites: "favourites",
+	gray: "grey",
+	honor: "honour",
+	labeled: "labelled",
+	labeling: "labelling",
+	modeling: "modelling",
+	neighbor: "neighbour",
+	optimize: "optimise",
+	optimized: "optimised",
+	organization: "organisation",
+	organizations: "organisations",
+	organize: "organise",
+	organized: "organised",
+	prioritize: "prioritise",
+	realize: "realise",
+	realized: "realised",
+	recognize: "recognise",
+	traveling: "travelling"
+};
+const AU_SPELLING_PATTERN = String.raw`(?<!\S*/\S*)\b(?:${Object.keys(AU_SPELLING).join("|")})\b(?!\S*/)`;
+const auSpelling = (prose) => prose.replaceAll(new RegExp(AU_SPELLING_PATTERN, "giu"), (word) => {
+	const au = AU_SPELLING[word.toLowerCase()];
+	if (!au || word !== word.toLowerCase() && word !== `${word[0]}${word.slice(1).toLowerCase()}`) return word;
+	return word[0] === word[0].toUpperCase() ? `${au[0].toUpperCase()}${au.slice(1)}` : au;
+});
 const FIXES = {
+	auSpelling,
 	ellipsis,
 	multiplicationSign,
 	nbspValueUnit,
-	smartQuotes
+	smartQuotes,
+	stripUtm
 };
 //#endregion
 //#region src/rules/validate-sections.ts
@@ -2550,7 +2615,7 @@ const codeRule = (spec, module) => {
 //#endregion
 //#region src/rules/code/classes.ts
 const MODULE$1 = "src/rules/code/classes.ts";
-const ANIMATION = "skills/ui-animation/references";
+const ANIMATION$1 = "skills/ui-animation/references";
 const bases = (unit) => (unit.classes ?? []).map(baseClass);
 const animates = (list) => list.some((c) => c.startsWith("transition") && c !== "transition-none" || c.startsWith("duration-") || c.startsWith("animate-") && c !== "animate-none");
 const durationMs = (cls) => {
@@ -2615,7 +2680,7 @@ const CLASS_RULES = [
 		id: "motion-ease-in-on-transition",
 		source: {
 			line: 27,
-			path: `${ANIMATION}/debugging-symptoms.md`
+			path: `${ANIMATION$1}/debugging-symptoms.md`
 		},
 		title: "Transition eases in, so it starts slow while the user is watching"
 	}),
@@ -2630,7 +2695,7 @@ const CLASS_RULES = [
 		id: "motion-linear-easing-on-transition",
 		source: {
 			line: 37,
-			path: `${ANIMATION}/debugging-symptoms.md`
+			path: `${ANIMATION$1}/debugging-symptoms.md`
 		},
 		title: "Linear easing on motion that is not a spinner or marquee"
 	}),
@@ -2646,7 +2711,7 @@ const CLASS_RULES = [
 		id: "motion-duration-over-300ms",
 		source: {
 			line: 29,
-			path: `${ANIMATION}/debugging-symptoms.md`
+			path: `${ANIMATION$1}/debugging-symptoms.md`
 		},
 		title: "Transition longer than 300ms on product UI"
 	}),
@@ -2657,7 +2722,7 @@ const CLASS_RULES = [
 		id: "motion-transition-all",
 		source: {
 			line: 58,
-			path: `${ANIMATION}/review-format.md`
+			path: `${ANIMATION$1}/review-format.md`
 		},
 		title: "transition-all animates every property, layout included"
 	}),
@@ -2672,7 +2737,7 @@ const CLASS_RULES = [
 		id: "motion-scale-from-zero",
 		source: {
 			line: 46,
-			path: `${ANIMATION}/debugging-symptoms.md`
+			path: `${ANIMATION$1}/debugging-symptoms.md`
 		},
 		title: "Entrance from scale zero"
 	}),
@@ -2688,7 +2753,7 @@ const CLASS_RULES = [
 		id: "motion-animate-without-reduced-motion",
 		source: {
 			line: 57,
-			path: `${ANIMATION}/live-tuning.md`
+			path: `${ANIMATION$1}/live-tuning.md`
 		},
 		status: "review-only",
 		title: "Animation has no local reduced-motion guard"
@@ -2871,7 +2936,7 @@ const document = (unit) => {
 	return unit.facts.document;
 };
 const nodes = (unit) => descendants(document(unit));
-const make$1 = (name, title, source, include, check, hint, authoring = false) => codeRule({
+const make$1 = (name, title, source, include, check, hint, authoring = false, status = "review-only") => codeRule({
 	categoryId: authoring ? "instruction-quality" : "reference-reading",
 	check,
 	hint,
@@ -2882,7 +2947,7 @@ const make$1 = (name, title, source, include, check, hint, authoring = false) =>
 		path: `skills/${source}`,
 		repo: "mblode/agent-skills"
 	},
-	status: "review-only",
+	status,
 	title,
 	unit: ["source"]
 }, "src/rules/code/documents.ts");
@@ -2893,7 +2958,7 @@ const INSTRUCTIONS = [
 	"**/SKILL.md"
 ];
 const DOCS = ["**/*.md"];
-const README_SOURCE = "readme-creator/references/quality-checklist.md";
+const README_SOURCE = "ghostwriter/references/readme.md";
 const DOCUMENT_RULES = [
 	make$1("readme-scaffold", "README still contains scaffold instructions", README_SOURCE, README, (u) => {
 		const n = nodes(u).find((candidate) => candidate.type === "paragraph" && /This is a \[?Next\.js.*bootstrapped with|This template provides a minimal setup to get React working in Vite/i.test(nodeText(candidate)));
@@ -2916,7 +2981,7 @@ const DOCUMENT_RULES = [
 		}
 		return none;
 	}, "Provide a complete first-run example; move intentionally partial examples to a tutorial."),
-	make$1("document-empty-heading", "A section has no content", "docs-writing/rules/structure-no-filler-sections.md", DOCS, (u) => {
+	make$1("document-empty-heading", "A section has no content", "ghostwriter/references/docs.md", DOCS, (u) => {
 		const children = document(u).children ?? [];
 		for (const [i, n] of children.entries()) {
 			if (n.type !== "heading") continue;
@@ -2925,7 +2990,7 @@ const DOCUMENT_RULES = [
 		}
 		return none;
 	}, "Add the section's content or remove its heading."),
-	make$1("document-heading-order", "Heading skips a structural level", "docs-writing/rules/format-semantic-html.md", DOCS, (u) => {
+	make$1("document-heading-order", "Heading skips a structural level", "ghostwriter/references/docs.md", DOCS, (u) => {
 		let previous = 0;
 		for (const n of nodes(u).filter((candidate) => candidate.type === "heading")) {
 			const depth = n.depth ?? 1;
@@ -2934,7 +2999,11 @@ const DOCUMENT_RULES = [
 		}
 		return none;
 	}, "Nest heading levels in order so the document outline reflects its structure."),
-	make$1("document-broken-local-link", "Document links to a missing local file", "docs-writing/rules/review-verify-links.md", DOCS, (u) => {
+	make$1("document-code-fence-language", "Code fence has no language tag", "ghostwriter/references/docs.md", DOCS, (u) => {
+		const n = nodes(u).find((candidate) => candidate.type === "code" && !candidate.lang);
+		return n ? at(n, "Fence without a language tag") : none;
+	}, "Tag the fence: ```bash, ```ts, or ```text for output. The tag drives highlighting and tells the reader what to paste where."),
+	make$1("document-broken-local-link", "Document links to a missing local file", "ghostwriter/references/docs.md", DOCS, (u) => {
 		const repo = u.facts.repository;
 		for (const n of nodes(u).filter((candidate) => [
 			"link",
@@ -2955,7 +3024,7 @@ const DOCUMENT_RULES = [
 			if (!repo.exists(resolved)) return at(n, `Missing local target: ${target}`);
 		}
 		return none;
-	}, "Correct the link or provide the referenced file. Generated site routes need a route-aware check."),
+	}, "Correct the link or provide the referenced file. Generated site routes need a route-aware check.", false, "active"),
 	make$1("instruction-missing-script", "Instruction invokes an undefined package script", "agents-md/references/quick-checklist.md", INSTRUCTIONS, (u) => {
 		const manifest = u.facts.repository.manifest(u.file);
 		if (!manifest) throw new UnresolvedError("No readable package manifest for this instruction file");
@@ -3024,6 +3093,7 @@ const IMAGE_RULES = [{
 	id: "interaction-a11y-image-alt-text",
 	required: ["alt"],
 	source: "a11y-image-alt-text",
+	status: "active",
 	title: "Image is missing an alt attribute"
 }, {
 	categoryId: "resilience",
@@ -3031,6 +3101,7 @@ const IMAGE_RULES = [{
 	id: "craft-image-dimensions-and-priority",
 	required: ["width", "height"],
 	source: "perf-image-dimensions-and-priority",
+	status: "review-only",
 	title: "Image has no declared dimensions or style"
 }].map((spec) => codeRule({
 	categoryId: spec.categoryId,
@@ -3056,11 +3127,62 @@ const IMAGE_RULES = [{
 		repo: "mblode/agent-skills",
 		ruleId: spec.source
 	},
-	status: "review-only",
+	status: spec.status,
 	title: spec.title,
 	unit: ["source"]
 }, "src/rules/code/images.ts"));
 //#endregion
+//#region src/rules/code/motion-source.ts
+const ANIMATION = "skills/ui-animation/SKILL.md";
+const stripComments = (text) => text.replaceAll(/\/\*[\s\S]*?\*\/|(?<![:"'\w])\/\/[^\n]*/gu, (m) => m.replaceAll(/[^\n]/gu, " "));
+const first = (unit, re, evidence) => {
+	const m = re.exec(stripComments(unit.text));
+	return m ? {
+		evidence,
+		fired: true,
+		offset: m.index
+	} : none;
+};
+const MOTION_SOURCE_RULES = [codeRule({
+	categoryId: "motion-restraint",
+	check: (unit) => first(unit, /(?:^|[{;\s])transition(?:-property)?\s*:\s*["'`]?all\b/mu, "transition: all"),
+	hint: "List the properties: transition: transform 200ms, opacity 200ms. `all` animates layout and silently adopts properties added later.",
+	id: "motion-css-transition-all",
+	scope: { include: [
+		"**/*.css",
+		"**/*.scss",
+		"**/*.tsx",
+		"**/*.jsx"
+	] },
+	source: {
+		line: 67,
+		path: ANIMATION,
+		repo: "mblode/agent-skills"
+	},
+	title: "transition: all animates every property, layout included",
+	unit: ["source"]
+}, "src/rules/code/motion-source.ts"), codeRule({
+	categoryId: "motion-restraint",
+	check: (unit) => first(unit, /\bfrom\s*["']framer-motion(?:\/[^"']*)?["']|\b(?:import|require)\s*\(\s*["']framer-motion["']/u, "imports framer-motion"),
+	hint: "Install `motion` and import from \"motion/react\". A mixed codebase compiles but ships two copies of the library.",
+	id: "motion-framer-motion-import",
+	scope: { include: [
+		"**/*.tsx",
+		"**/*.jsx",
+		"**/*.ts",
+		"**/*.js",
+		"**/*.mjs",
+		"**/*.mts"
+	] },
+	source: {
+		line: 153,
+		path: ANIMATION,
+		repo: "mblode/agent-skills"
+	},
+	title: "Imports framer-motion instead of motion/react",
+	unit: ["source"]
+}, "src/rules/code/motion-source.ts")];
+//#endregion
 //#region src/rules/code/skill-classes.ts
 const make = (id, title, categoryId, source, check, hint) => codeRule({
 	categoryId,
@@ -3320,7 +3442,7 @@ const CODE_RULES = [
 		rule({
 			categoryId: "machine-prose",
 			check: (unit) => {
-				const long = unit.text.split(/(?<=[.!?])\s+/u).map((s) => [s, countWords(s)]).filter(([, n]) => n > 25);
+				const long = unit.text.split(/(?<=[.!?])\s+/u).map((s) => [s, countWords(s)]).filter(([s, n]) => n > 25 && (s.match(/\b(?:and|but)\b/giu)?.length ?? 0) >= 2);
 				if (long.length === 0) return none;
 				const [sentence, n] = long[0];
 				return hit(`${n} words: "${sentence.slice(0, 80)}${sentence.length > 80 ? "..." : ""}"`);
@@ -3342,18 +3464,19 @@ const CODE_RULES = [
 				notInCode: true
 			},
 			source: {
-				line: 7,
-				path: "skills/docs-writing/rules/clarity-one-idea-per-sentence.md",
+				line: 17,
+				path: "skills/ghostwriter/references/docs.md",
 				repo: "mblode/agent-skills"
 			},
-			title: "Sentence over 25 words",
+			title: "Sentence over 25 words joins several clauses",
 			unit: ["paragraph", "jsx-text"]
 		})
 	],
 	...CLASS_RULES,
 	...DOCUMENT_RULES,
 	...IMAGE_RULES,
-	...SKILL_CLASS_RULES
+	...SKILL_CLASS_RULES,
+	...MOTION_SOURCE_RULES
 ];
 //#endregion
 //#region src/rules/load.ts
@@ -3416,10 +3539,8 @@ const readTuning = (rulesDir) => {
 	}
 	return out;
 };
-const loadRules = (rulesDir, options = {}) => {
-	const tuning = readTuning(rulesDir);
+const readYamlRules = (rulesDir) => {
 	const rules = [];
-	const seen = /* @__PURE__ */ new Set();
 	const domains = fs.readdirSync(rulesDir, { withFileTypes: true }).filter((d) => d.isDirectory() && d.name !== "schema").map((d) => d.name).toSorted();
 	for (const domain of domains) {
 		const dir = path.join(rulesDir, domain);
@@ -3427,24 +3548,49 @@ const loadRules = (rulesDir, options = {}) => {
 			if (!name.endsWith(".yaml")) continue;
 			const file = path.join(dir, name);
 			const expectedId = name.slice(0, -5);
-			let raw;
 			try {
-				raw = parse(fs.readFileSync(file, "utf-8"));
+				let raw;
+				try {
+					raw = parse(fs.readFileSync(file, "utf-8"));
+				} catch (error) {
+					throw new Error(`Invalid rule ${file}: YAML did not parse (${error.message})`, { cause: error });
+				}
+				const rule = validateRule(raw, file, expectedId);
+				if (rule.domain !== domain) throw new Error(`Invalid rule ${file}: domain ${rule.domain} does not match folder ${domain}`);
+				rules.push(rule);
 			} catch (error) {
-				throw new Error(`Invalid rule ${file}: YAML did not parse (${error.message})`, { cause: error });
+				const invalid = new InputError("INVALID_RULE", error.message, { file });
+				invalid.cause = error;
+				throw invalid;
 			}
-			const rule = validateRule(raw, file, expectedId);
-			if (rule.domain !== domain) throw new Error(`Invalid rule ${file}: domain ${rule.domain} does not match folder ${domain}`);
-			rules.push(rule);
 		}
 	}
+	return rules;
+};
+const loadRules = (rulesDir, options = {}) => {
+	const tuning = readTuning(rulesDir);
+	const rules = [];
+	const seen = /* @__PURE__ */ new Map();
+	rules.push(...readYamlRules(rulesDir));
+	for (const dir of options.extraDirs ?? []) {
+		const extra = readYamlRules(dir);
+		if (extra.length === 0) throw new InputError("INVALID_CONFIG", `rules entry ${dir} holds no rules; put YAML rule files in a domain folder such as ${path.join(dir, "copywriting")}/`, {
+			field: "rules",
+			path: dir
+		});
+		rules.push(...extra);
+	}
 	for (const code of CODE_RULES) rules.push({
 		...code,
 		thresholds: { ...code.thresholds }
 	});
 	for (const rule of rules) {
-		if (seen.has(rule.id)) throw new Error(`Duplicate rule id ${rule.id}`);
-		seen.add(rule.id);
+		const first = seen.get(rule.id);
+		if (first !== void 0) throw new InputError("DUPLICATE_RULE", `Rule id ${rule.id} is defined in ${first} and ${rule.file}; rename one.`, {
+			files: [first, rule.file],
+			id: rule.id
+		});
+		seen.set(rule.id, rule.file);
 		const overlay = tuning[rule.id];
 		if (isCandidateRule(rule) && (rule.status === "active" || overlay?.status === "active")) throw new Error(`Candidate-only rule ${rule.id} cannot be active; add an evidence-based check before promotion.`);
 		if (overlay) {
@@ -5375,7 +5521,10 @@ const runLint = async (options = {}, ctx = {}) => {
 	const config = loadConfig(options.root ?? process.cwd());
 	const rulesDir = resolveRulesDir(options.rulesDir);
 	const profile = options.profile ? profileFor(options.profile) : void 0;
-	const loaded = loadRules(rulesDir, { only: options.only });
+	const loaded = loadRules(rulesDir, {
+		extraDirs: config.rules,
+		only: options.only
+	});
 	const rules = profile && !options.only?.length ? profileRules(profile, loaded) : loaded;
 	if (rules.length === 0) throw new InputError("EMPTY_RULE_SELECTION", "No rules match the selected profile and ids.");
 	const model = options.model ?? "jev-latest";