@textmode/tooling-scripts 0.1.0

package/src/scripts/lib/api-doc-checks.mjs

@@ -0,0 +1,147 @@
+import { hostedApiUrl, routeForReflection } from './api-doc-routes.mjs';
+import { getPrimaryLocation, getRelevantComments } from './reflection-policy.mjs';
+
+export const ISSUE_KIND = {
+	MISSING_DOCSTRING: 'missing-docstring',
+	MISSING_EXAMPLE: 'missing-example',
+	MISSING_API_LINK: 'missing-api-link',
+	INVALID_API_LINK: 'invalid-api-link',
+};
+
+export function hasDocstring(reflection) {
+	return getRelevantComments(reflection).length > 0;
+}
+
+export function hasExample(reflection) {
+	return getRelevantComments(reflection).some(({ comment }) =>
+		comment.getTags('@example').some((tag) => tag.content.some((part) => (part.text ?? '').trim().length > 0))
+	);
+}
+
+export function getApiLinkTargets(comment, apiBaseUrl) {
+	return comment
+		.getTags('@see')
+		.flatMap((tag) => tag.content)
+		.filter((part) => part.kind === 'inline-tag' && part.tag === '@link')
+		.map((part) => part.target)
+		.filter((target) => typeof target === 'string' && target.startsWith(`${apiBaseUrl}/`));
+}
+
+export function getInvalidApiLinkTargets(comment, routes, apiBaseUrl) {
+	return getApiLinkTargets(comment, apiBaseUrl).filter((target) => {
+		const routeWithAnchor = target.slice(`${apiBaseUrl}/`.length);
+		if (!routeWithAnchor || routeWithAnchor === 'index') {
+			return true;
+		}
+
+		const [route] = routeWithAnchor.split('#');
+		return !routes.has(route);
+	});
+}
+
+export function hasApiLink(comment, apiBaseUrl) {
+	return getApiLinkTargets(comment, apiBaseUrl).length > 0;
+}
+
+export function createApiLinkTargets(reflection, routes, apiBaseUrl) {
+	const route = routeForReflection(reflection, routes);
+	if (!route) {
+		return [];
+	}
+
+	const routeWithoutAnchor = route.split('#')[0];
+	if (!routes.has(routeWithoutAnchor)) {
+		return [];
+	}
+
+	const url = hostedApiUrl(apiBaseUrl, route);
+	const label = `${reflection.getFriendlyFullName()} API reference`;
+	const seeLine = `@see {@link ${url} | ${label}}`;
+
+	return getRelevantComments(reflection).map(({ source }) => ({
+		reflection,
+		source,
+		seeLine,
+	}));
+}
+
+export function createIssue(reflection, kind) {
+	const location = getPrimaryLocation(reflection);
+
+	return {
+		kind,
+		name: reflection.getFriendlyFullName(),
+		file: location.file,
+		line: location.line,
+		column: location.column,
+		location: location.printable,
+	};
+}
+
+export function createCommentIssue(reflection, commentSource, kind, detail) {
+	const location = commentSource
+		? {
+				file: commentSource.fullFileName || getPrimaryLocation(reflection).file,
+				line: commentSource.line || 1,
+				column: (commentSource.character ?? 0) + 1,
+			}
+		: getPrimaryLocation(reflection);
+
+	return {
+		kind,
+		name: reflection.getFriendlyFullName(),
+		file: location.file,
+		line: location.line,
+		column: location.column,
+		location: `${location.file}:${location.line}:${location.column}`,
+		detail,
+	};
+}
+
+export function collectApiDocIssues({
+	apiBaseUrl,
+	apiLinkReflections,
+	docstringReflections,
+	exampleReflections,
+	routes,
+}) {
+	const missingDocstrings = docstringReflections
+		.filter((reflection) => !hasDocstring(reflection))
+		.map((reflection) => createIssue(reflection, ISSUE_KIND.MISSING_DOCSTRING))
+		.sort(compareIssues);
+
+	const missingExamples = exampleReflections
+		.filter((reflection) => hasDocstring(reflection) && !hasExample(reflection))
+		.map((reflection) => createIssue(reflection, ISSUE_KIND.MISSING_EXAMPLE))
+		.sort(compareIssues);
+
+	const comments = apiLinkReflections.flatMap((reflection) =>
+		getRelevantComments(reflection).map(({ comment, source }) => ({ reflection, comment, source }))
+	);
+	const missingApiLinks = comments
+		.filter(({ comment }) => !hasApiLink(comment, apiBaseUrl))
+		.map(({ reflection, source }) => createCommentIssue(reflection, source, ISSUE_KIND.MISSING_API_LINK))
+		.sort(compareIssues);
+	const invalidApiLinks = comments
+		.flatMap(({ reflection, comment, source }) =>
+			getInvalidApiLinkTargets(comment, routes, apiBaseUrl).map((target) =>
+				createCommentIssue(reflection, source, ISSUE_KIND.INVALID_API_LINK, target)
+			)
+		)
+		.sort(compareIssues);
+
+	return { missingDocstrings, missingExamples, missingApiLinks, invalidApiLinks };
+}
+
+export function countApiDocIssues(issueGroups) {
+	return Object.values(issueGroups).reduce((total, issues) => total + issues.length, 0);
+}
+
+export function compareIssues(left, right) {
+	return (
+		left.file.localeCompare(right.file) ||
+		left.line - right.line ||
+		left.column - right.column ||
+		left.name.localeCompare(right.name)
+	);
+}

package/src/scripts/lib/api-doc-links-config.mjs

@@ -0,0 +1,32 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+async function loadConsumerConfig() {
+	const configPath = path.resolve(process.cwd(), 'textmode.tooling.config.mjs');
+
+	try {
+		const configModule = await import(pathToFileURL(configPath).href);
+		return configModule.default ?? configModule.config;
+	} catch (error) {
+		if (error?.code === 'ERR_MODULE_NOT_FOUND' || error?.code === 'ENOENT') {
+			throw new Error(`Missing textmode tooling config at ${configPath}.`);
+		}
+		throw error;
+	}
+}
+
+const config = await loadConsumerConfig();
+
+export const API_BASE_URL = config.API_BASE_URL;
+export const API_DOCS_DIR = config.API_DOCS_DIR;
+export const CHECK_EXAMPLE_GALLERY_SOURCE_BASE = config.CHECK_EXAMPLE_GALLERY_SOURCE_BASE;
+export const CHECK_EXAMPLE_SKETCHES = config.CHECK_EXAMPLE_SKETCHES;
+export const DOCSTRING_TARGET_KINDS = config.DOCSTRING_TARGET_KINDS;
+export const DOCSTRING_TARGET_KINDS_WITH_ACCESSORS = config.DOCSTRING_TARGET_KINDS_WITH_ACCESSORS;
+export const ENTRY_POINT = config.ENTRY_POINT;
+export const ENTRY_POINTS = config.ENTRY_POINTS;
+export const EXAMPLE_TARGET_KINDS = config.EXAMPLE_TARGET_KINDS;
+export const EXAMPLE_TARGET_KINDS_WITH_ACCESSORS = config.EXAMPLE_TARGET_KINDS_WITH_ACCESSORS;
+export const PACKAGE_LABEL = config.PACKAGE_LABEL;
+export const SOURCE_ROOTS = config.SOURCE_ROOTS;
+export const TARGET_KINDS = config.TARGET_KINDS;

package/src/scripts/lib/api-doc-routes.mjs

@@ -0,0 +1,118 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { ReflectionKind } from 'typedoc';
+
+export const KIND_DIRECTORIES = new Map([
+	[ReflectionKind.Class, 'classes'],
+	[ReflectionKind.Interface, 'interfaces'],
+	[ReflectionKind.TypeAlias, 'type-aliases'],
+	[ReflectionKind.Enum, 'enumerations'],
+	[ReflectionKind.Variable, 'variables'],
+	[ReflectionKind.Function, 'functions'],
+	[ReflectionKind.Method, 'methods'],
+	[ReflectionKind.Accessor, 'accessors'],
+	[ReflectionKind.Property, 'properties'],
+]);
+
+export function readMarkdownRoutes(apiDocsDir) {
+	const routes = new Set();
+
+	function walk(dir) {
+		for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+			const fullPath = path.join(dir, entry.name);
+			if (entry.isDirectory()) {
+				walk(fullPath);
+				continue;
+			}
+
+			if (!entry.name.endsWith('.md')) {
+				continue;
+			}
+
+			const relative = path.relative(apiDocsDir, fullPath).replaceAll(path.sep, '/');
+			const withoutExtension = relative.replace(/\.md$/, '');
+			const route = withoutExtension.endsWith('/index')
+				? withoutExtension.slice(0, -'/index'.length)
+				: withoutExtension;
+			routes.add(route);
+		}
+	}
+
+	walk(apiDocsDir);
+	return routes;
+}
+
+function generateTemporaryMarkdownRoutes() {
+	const outputDir = fs.mkdtempSync(path.join(tmpdir(), 'textmode-api-routes-'));
+
+	try {
+		execFileSync('npm', ['run', 'build:docs', '--', '--out', outputDir, '--logLevel', 'Error'], {
+			encoding: 'utf8',
+			maxBuffer: 1024 * 1024 * 20,
+			stdio: 'pipe',
+		});
+		return readMarkdownRoutes(outputDir);
+	} finally {
+		fs.rmSync(outputDir, { recursive: true, force: true });
+	}
+}
+
+export async function readOrGenerateMarkdownRoutes(apiDocsDir) {
+	if (fs.existsSync(apiDocsDir)) {
+		return readMarkdownRoutes(apiDocsDir);
+	}
+
+	return generateTemporaryMarkdownRoutes();
+}
+
+export function slugAnchor(name) {
+	return name
+		.toLowerCase()
+		.replace(/[^a-z0-9_-]+/g, '-')
+		.replace(/^-+|-+$/g, '');
+}
+
+export function routeForReflection(reflection, routes) {
+	if (reflection.isProject()) {
+		return '';
+	}
+
+	if (reflection.kind === ReflectionKind.Namespace) {
+		const parentRoute =
+			reflection.parent && !reflection.parent.isProject() ? routeForReflection(reflection.parent, routes) : '';
+		return [parentRoute, 'namespaces', reflection.name].filter(Boolean).join('/');
+	}
+
+	if (
+		reflection.kind === ReflectionKind.Method ||
+		reflection.kind === ReflectionKind.Accessor ||
+		reflection.kind === ReflectionKind.Property
+	) {
+		const ownerRoute = routeForReflection(reflection.parent, routes);
+		const ownPageRoute = [ownerRoute, KIND_DIRECTORIES.get(reflection.kind), reflection.name]
+			.filter(Boolean)
+			.join('/');
+
+		if (routes.has(ownPageRoute)) {
+			return ownPageRoute;
+		}
+
+		return `${ownerRoute}#${slugAnchor(reflection.name)}`;
+	}
+
+	const directory = KIND_DIRECTORIES.get(reflection.kind);
+	if (!directory) {
+		return undefined;
+	}
+
+	const parentRoute =
+		reflection.parent && !reflection.parent.isProject() ? routeForReflection(reflection.parent, routes) : '';
+	return [parentRoute, directory, reflection.name].filter(Boolean).join('/');
+}
+
+export function hostedApiUrl(apiBaseUrl, route) {
+	return `${apiBaseUrl}/${route}`;
+}

package/src/scripts/lib/example-checks.mjs

@@ -0,0 +1,389 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+import { CHECK_EXAMPLE_GALLERY_SOURCE_BASE } from './api-doc-links-config.mjs';
+
+const INCLUDE_CODE_PATTERN = /\{@includeCode\s+([^}\s]+)[^}]*\}/g;
+const MANIFEST_KEYS = new Set(['version', 'description', 'groups']);
+const GROUP_KEYS = new Set(['name', 'description', 'examples', 'subgroups']);
+const SUBGROUP_KEYS = new Set(['name', 'description', 'examples']);
+const EXAMPLE_KEYS = new Set(['title', 'description', 'sourceFile']);
+
+export const EXAMPLES_DIR = 'examples';
+export const EXAMPLES_INDEX = path.join(EXAMPLES_DIR, 'index.html');
+export const EXAMPLES_MANIFEST = path.join(EXAMPLES_DIR, 'manifest.json');
+export const SOURCE_DIR = 'src';
+
+export function isRecord(value) {
+	return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function getUnknownKeys(value, allowedKeys) {
+	return Object.keys(value).filter((key) => !allowedKeys.has(key));
+}
+
+export function toRepositoryPath(filePath) {
+	return path.relative(process.cwd(), filePath).split(path.sep).join('/');
+}
+
+export function getTypeScriptFiles(directory) {
+	const files = [];
+
+	for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+		const entryPath = path.join(directory, entry.name);
+
+		if (entry.isDirectory()) {
+			files.push(...getTypeScriptFiles(entryPath));
+		} else if (entry.isFile() && entry.name.endsWith('.ts')) {
+			files.push(entryPath);
+		}
+	}
+
+	return files;
+}
+
+export function readExamplesManifest(manifestPath = EXAMPLES_MANIFEST) {
+	return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+}
+
+export function readExamplesIndex(indexPath = EXAMPLES_INDEX) {
+	return fs.readFileSync(indexPath, 'utf8');
+}
+
+export function getSketchTitle(filePath) {
+	const content = fs.readFileSync(filePath, 'utf8');
+	const docstringMatch = content.match(/^\s*\/\*\*([\s\S]*?)\*\//);
+	const titleMatch = docstringMatch?.[1].match(/@title\s+([^\r\n]+)/);
+
+	return titleMatch?.[1].trim() ?? null;
+}
+
+export function getManifestExamples(manifest) {
+	return manifest.groups.flatMap((group) => {
+		if (Array.isArray(group.subgroups)) {
+			return group.subgroups.flatMap((sg) =>
+				Array.isArray(sg.examples)
+					? sg.examples.filter(isRecord).map((example) => ({
+							...example,
+							groupName: group.name,
+							groupDescription: group.description,
+							subgroupName: sg.name,
+						}))
+					: []
+			);
+		}
+
+		return Array.isArray(group.examples)
+			? group.examples.filter(isRecord).map((example) => ({
+					...example,
+					groupName: group.name,
+					groupDescription: group.description,
+				}))
+			: [];
+	});
+}
+
+export function getTypeDocExampleIncludes(sourceDir = SOURCE_DIR, examplesDir = EXAMPLES_DIR) {
+	const includes = [];
+
+	for (const file of getTypeScriptFiles(sourceDir)) {
+		const content = fs.readFileSync(file, 'utf8');
+		let match;
+
+		INCLUDE_CODE_PATTERN.lastIndex = 0;
+		while ((match = INCLUDE_CODE_PATTERN.exec(content)) !== null) {
+			const includeTarget = match[1];
+			const resolvedPath = path.resolve(path.dirname(file), includeTarget);
+			const sourceFile = toRepositoryPath(resolvedPath);
+
+			if (sourceFile.startsWith(`${examplesDir}/`)) {
+				includes.push({
+					file,
+					includeTarget,
+					sourceFile,
+				});
+			}
+		}
+	}
+
+	return includes;
+}
+
+export function validateExamplesGallery(
+	indexContent,
+	examplesIndex = EXAMPLES_INDEX,
+	examplesManifest = EXAMPLES_MANIFEST
+) {
+	const issues = [];
+
+	if (/const\s+GROUPS\s*=/.test(indexContent)) {
+		issues.push(`${examplesIndex} must not declare \`const GROUPS\`; ${examplesManifest} is authoritative.`);
+	}
+
+	if (!indexContent.includes('manifest.json')) {
+		issues.push(`${examplesIndex} must load ${examplesManifest}.`);
+	}
+
+	if (CHECK_EXAMPLE_GALLERY_SOURCE_BASE && /data-source-base\s*=/.test(indexContent)) {
+		issues.push(
+			`${examplesIndex} must not hardcode a source base; preview links should resolve from example paths.`
+		);
+	}
+
+	return issues;
+}
+
+export function validateExamplesManifest(manifest, options = {}) {
+	const examplesDir = options.examplesDir ?? EXAMPLES_DIR;
+	const examplesManifest = options.examplesManifest ?? EXAMPLES_MANIFEST;
+	const sourceDir = options.sourceDir ?? SOURCE_DIR;
+	const issues = [];
+
+	if (!isRecord(manifest)) {
+		return ['Manifest root must be an object.'];
+	}
+
+	for (const key of getUnknownKeys(manifest, MANIFEST_KEYS)) {
+		issues.push(`Manifest contains unknown top-level key: ${key}`);
+	}
+
+	if (manifest.version !== 1) {
+		issues.push('Manifest `version` must be `1`.');
+	}
+
+	if (typeof manifest.description !== 'string' || manifest.description.length === 0) {
+		issues.push('Manifest `description` must be a non-empty string.');
+	}
+
+	if (!Array.isArray(manifest.groups)) {
+		return ['Manifest `groups` must be an array.'];
+	}
+
+	for (const [groupIndex, group] of manifest.groups.entries()) {
+		if (!isRecord(group)) {
+			issues.push(`Manifest group ${groupIndex + 1} must be an object.`);
+			continue;
+		}
+
+		for (const key of getUnknownKeys(group, GROUP_KEYS)) {
+			issues.push(`Manifest group "${group.name ?? groupIndex + 1}" contains unknown key: ${key}`);
+		}
+
+		if (typeof group.name !== 'string' || group.name.length === 0) {
+			issues.push(`Manifest group ${groupIndex + 1} is missing a name.`);
+		}
+
+		if (typeof group.description !== 'string' || group.description.length === 0) {
+			issues.push(`Manifest group "${group.name ?? groupIndex + 1}" is missing a description.`);
+		}
+
+		const hasExamples = Array.isArray(group.examples);
+		const hasSubgroups = Array.isArray(group.subgroups);
+
+		if (hasExamples && hasSubgroups) {
+			issues.push(
+				`Manifest group "${group.name}" must not have both \`examples\` and \`subgroups\`. Use one or the other.`
+			);
+			continue;
+		}
+
+		if (!hasExamples && !hasSubgroups) {
+			issues.push(
+				`Manifest group "${group.name}" must have either an \`examples\` array or a \`subgroups\` array.`
+			);
+			continue;
+		}
+
+		if (hasSubgroups) {
+			for (const [sgIndex, sg] of group.subgroups.entries()) {
+				if (!isRecord(sg)) {
+					issues.push(`Manifest subgroup ${sgIndex + 1} in group "${group.name}" must be an object.`);
+					continue;
+				}
+
+				for (const key of getUnknownKeys(sg, SUBGROUP_KEYS)) {
+					issues.push(
+						`Manifest subgroup "${sg.name ?? sgIndex + 1}" in group "${group.name}" contains unknown key: ${key}`
+					);
+				}
+
+				if (typeof sg.name !== 'string' || sg.name.length === 0) {
+					issues.push(`Manifest subgroup ${sgIndex + 1} in group "${group.name}" is missing a name.`);
+				}
+
+				if (!Array.isArray(sg.examples)) {
+					issues.push(
+						`Manifest subgroup "${sg.name ?? sgIndex + 1}" in group "${group.name}" examples must be an array.`
+					);
+					continue;
+				}
+
+				for (const [exampleIndex, example] of sg.examples.entries()) {
+					if (!isRecord(example)) {
+						issues.push(
+							`Manifest example ${exampleIndex + 1} in subgroup "${sg.name}" of group "${group.name}" must be an object.`
+						);
+						continue;
+					}
+
+					for (const key of getUnknownKeys(example, EXAMPLE_KEYS)) {
+						issues.push(
+							`Manifest example "${example.sourceFile ?? `${group.name}.${sg.name}.${exampleIndex + 1}`}" contains unknown key: ${key}`
+						);
+					}
+				}
+			}
+		} else {
+			for (const [exampleIndex, example] of group.examples.entries()) {
+				if (!isRecord(example)) {
+					issues.push(`Manifest example ${exampleIndex + 1} in group "${group.name}" must be an object.`);
+					continue;
+				}
+
+				for (const key of getUnknownKeys(example, EXAMPLE_KEYS)) {
+					issues.push(
+						`Manifest example "${example.sourceFile ?? `${group.name}.${exampleIndex + 1}`}" contains unknown key: ${key}`
+					);
+				}
+			}
+		}
+	}
+
+	const manifestExamples = getManifestExamples(manifest);
+	const manifestFiles = manifestExamples.map((example) => example.sourceFile);
+
+	if (manifestFiles.length === 0) {
+		issues.push('Manifest must include at least one example.');
+	}
+
+	const seen = new Set();
+	for (const example of manifestExamples) {
+		if (typeof example.sourceFile !== 'string') {
+			issues.push('Manifest examples must include a string sourceFile.');
+			continue;
+		}
+
+		if (seen.has(example.sourceFile)) {
+			issues.push(`Manifest contains duplicate source file: ${example.sourceFile}`);
+		}
+		seen.add(example.sourceFile);
+
+		if (typeof example.title !== 'string' || example.title.length === 0) {
+			issues.push(`Manifest example "${example.sourceFile}" is missing a title.`);
+		}
+
+		if (!example.sourceFile.startsWith(`${examplesDir}/`) || !example.sourceFile.endsWith('/sketch.js')) {
+			issues.push(`Manifest example "${example.sourceFile}" sourceFile must be an examples/**/sketch.js path.`);
+		}
+
+		if (!fs.existsSync(example.sourceFile)) {
+			issues.push(`Manifest example is missing its sketch file: ${example.sourceFile}`);
+			continue;
+		}
+
+		const sketchTitle = getSketchTitle(example.sourceFile);
+
+		if (!sketchTitle) {
+			issues.push(`Manifest example "${example.sourceFile}" sketch is missing an @title tag.`);
+		} else if (sketchTitle !== example.title) {
+			issues.push(
+				`Manifest example "${example.sourceFile}" title "${example.title}" must match sketch @title "${sketchTitle}".`
+			);
+		}
+	}
+
+	const manifestFileSet = new Set(manifestFiles);
+	for (const include of getTypeDocExampleIncludes(sourceDir, examplesDir)) {
+		if (!manifestFileSet.has(include.sourceFile)) {
+			issues.push(
+				`TypeDoc includeCode in "${include.file}" references "${include.includeTarget}" (${include.sourceFile}), but that sketch is not in ${examplesManifest}.`
+			);
+		}
+	}
+
+	return issues;
+}
+
+export function checkSketch(filePath) {
+	const content = fs.readFileSync(filePath, 'utf8');
+	const issues = [];
+
+	if (content.includes('import ') || content.includes('export ')) {
+		return { skipped: true, issues };
+	}
+
+	const docstringMatch = content.match(/^\s*\/\*\*([\s\S]*?)\*\//);
+	if (!docstringMatch) {
+		issues.push('Missing JSDoc-style block comment header at the top of the file.');
+	} else {
+		const docstring = docstringMatch[1];
+		if (!docstring.includes('@title')) {
+			issues.push('Docstring header is missing `@title` tag.');
+		}
+	}
+
+	const createMatch = content.match(/textmode\.create\s*\(\s*\{([\s\S]*?)\}\s*\)/);
+	if (!createMatch) {
+		issues.push('Could not find `textmode.create({ ... })` call.');
+	} else {
+		const options = createMatch[1];
+
+		if (!options.match(/width:\s*window\.innerWidth/)) {
+			issues.push('`width` must be set to `window.innerWidth` in create options.');
+		}
+
+		if (!options.match(/height:\s*window\.innerHeight/)) {
+			issues.push('`height` must be set to `window.innerHeight` in create options.');
+		}
+
+		const fontSizeMatch = options.match(/fontSize:\s*(\d+)/);
+		if (fontSizeMatch) {
+			const size = parseInt(fontSizeMatch[1], 10);
+			if (size !== 8 && size !== 16 && size !== 32) {
+				issues.push(`\`fontSize\` is set to \`${size}\`, but must be exactly \`8\`, \`16\`, or \`32\`.`);
+			}
+		}
+	}
+
+	if (!content.includes('windowResized')) {
+		issues.push('Missing `windowResized` callback registration.');
+	}
+	if (!content.match(/resizeCanvas\(\s*window\.innerWidth\s*,\s*window\.innerHeight\s*\)/)) {
+		issues.push(
+			'`resizeCanvas` must be called with `window.innerWidth` and `window.innerHeight` inside the sketch.'
+		);
+	}
+
+	if (/\bvar\b/.test(content)) {
+		issues.push('Do not use `var`; prefer `const` or `let`.');
+	}
+
+	const lines = content.split('\n');
+	if (lines.length > 100) {
+		issues.push(`Sketch file has ${lines.length} lines, but must not exceed 100 lines.`);
+	}
+
+	if (!content.includes('layers.add(')) {
+		issues.push('Missing dedicated label layer registration (`t.layers.add()`).');
+	}
+
+	const leftMatch = content.includes('grid.cols / 2') || content.includes('grid.cols/2');
+	const topMatch = content.includes('grid.rows / 2') || content.includes('grid.rows/2');
+	if (!leftMatch || !topMatch) {
+		issues.push(
+			'Missing top-left labeling alignment coordinates calculation using grid center offset (`-Math.floor(t.grid.cols / 2)` and `-Math.floor(t.grid.rows / 2)`).'
+		);
+	}
+
+	const textDrawingRegex = /(?:drawText|drawCenteredText|t\.char)\s*\(\s*(['"`])(.*?)\1/g;
+	let match;
+	while ((match = textDrawingRegex.exec(content)) !== null) {
+		const text = match[2];
+		if (text.length > 40) {
+			issues.push(`Row of text exceeds 40 characters limit: "${text}" (${text.length} chars).`);
+		}
+	}
+
+	return { skipped: false, issues };
+}