describe.ts

1// §21.5: a description is the file's own words, found by syntax alone; no comment means none.2// Every function returns Markdown source (hard-wrapped lines kept) or null.34import MarkdownIt from "markdown-it";56type Style = "bang" | "slash" | "jvm" | "hash" | "python" | "markdown";78const STYLES: Record<string, Style> = {9	zig: "bang",10	rs: "bang",11	py: "python",12	md: "markdown",13	markdown: "markdown",14};15for (const ext of "v go c h cc cpp cxx hpp hh js mjs cjs jsx ts tsx mts cts".split(" ")) {16	STYLES[ext] = "slash";17}18for (const ext of "kt kts java swift".split(" ")) STYLES[ext] = "jvm";19for (const ext of "sh bash zsh nix toml yaml yml".split(" ")) STYLES[ext] = "hash";2021const SHELL_SHEBANG = /^#!.*\b(ba|z|da|k)?sh\b/;22const MODULE_FILES = ["mod.zig", "mod.rs", "index.ts", "__init__.py"];23const README = /^readme\.(md|markdown)$/i;2425/**26 * A license header is the first comment block when it has a license header's shape: an SPDX tag,27 * "Copyright (c)", "Copyright ©", "Copyright <year>", "© <year>", "licensed under" or "all rights28 * reserved". Only that one block is skipped, and the word "copyright" alone is not enough, so29 * `// Renders copyright notices.` keeps its description.30 */31const LICENSE =32	/SPDX-License-Identifier|\bcopyright\s*(\(c\)|©|\d{4})|©\s*\d{4}|\blicensed under\b|\ball rights reserved\b/i;33/**34 * Kotlin, Java and Swift put a file's words on its main declaration, after `package` and35 * `import`; those lines only name the file's place, so they are passed over, not counted as code.36 */37const PREAMBLE = /^(package|import)\s|^@file:/;38// Go build constraints are comments that describe nothing.39const DIRECTIVE = /^\/\/(go:|\s*\+build\b)/;4041// Parsing only: with HTML on, a leading `<!-- -->` or `<p align>` block is not taken for a paragraph.42const markdown = new MarkdownIt({ html: true });4344/** The description of one file from its text, by the kind its name says it is. */45export function describeFile(path: string, text: string): string | null {46	const name = path.split("/").pop() ?? path;47	const lines = text.replace(/^\uFEFF/, "").split(/\r?\n/);48	const ext = name.includes(".") ? (name.split(".").pop() as string).toLowerCase() : "";49	const style = STYLES[ext] ?? (ext === "" && SHELL_SHEBANG.test(lines[0] ?? "") ? "hash" : null);50	if (style === "bang") return bangLines(lines);51	if (style === "slash") return slashBlock(lines);52	if (style === "jvm") return slashBlock(lines.filter((line) => !PREAMBLE.test(line.trim())));53	if (style === "hash") return hashBlock(lines);54	if (style === "python") return docstring(lines);55	if (style === "markdown") return firstParagraph(text);56	return null;57}5859/** A folder's description: its README's, else its module file's, given each child's own. */60export function describeFolder(61	children: { name: string; description: string | null }[],62): string | null {63	const readme = children.find((child) => README.test(child.name))?.description;64	const moduleFile = MODULE_FILES.map((name) => children.find((c) => c.name === name)).find(65		Boolean,66	);67	return readme ?? moduleFile?.description ?? null;68}6970/** The first sentence of the first paragraph, with hard-wrapped lines joined: the row's one-liner. */71export function firstSentence(description: string): string {72	const paragraph = (description.trim().split(/\n\s*\n/)[0] as string).replace(/\s*\n\s*/g, " ");73	let inCode = false;74	for (let i = 0; i < paragraph.length; i++) {75		const c = paragraph[i] as string;76		if (c === "`") inCode = !inCode;77		const ends = i + 1 === paragraph.length || /\s/.test(paragraph[i + 1] as string);78		if (!inCode && ".!?".includes(c) && ends && !ABBREVIATION.test(paragraph.slice(0, i + 1))) {79			return paragraph.slice(0, i + 1);80		}81	}82	return paragraph;83}8485const ABBREVIATION = /\b(e\.g|i\.e|etc|vs|cf)\.$/i;8687function joined(lines: string[]): string | null {88	const text = lines.join("\n").trim();89	return text === "" ? null : text;90}9192// Zig and Rust: the `//!` lines at the top, after ordinary comments such as a license header.93function bangLines(lines: string[]): string | null {94	const body: string[] = [];95	for (const raw of lines) {96		const line = raw.trim();97		if (line.startsWith("//!")) body.push(line.replace(/^\/\/! ?/, ""));98		else if (body.length > 0 || !(line === "" || line.startsWith("//"))) break;99	}100	return joined(body);101}102103function slashBlock(lines: string[]): string | null {104	const block = commentBlocks(lines, (line) => line.startsWith("//"), true).find(105		(b) => !b.lines.every((line) => DIRECTIVE.test(line)),106	);107	if (!block) return null;108	if (!block.starred) return joined(block.lines.map((line) => line.replace(/^\/\/[/!]? ?/, "")));109	return joined(110		block.lines.map((line) => line.replace(/\s*\*\/$/, "").replace(/^(\/\*[*!]?|\*(?!\/)) ?/, "")),111	);112}113114// Shell, Nix, TOML, YAML: `#` lines at the top, after a shebang and a license header.115function hashBlock(lines: string[]): string | null {116	const rest = lines[0]?.startsWith("#!") ? lines.slice(1) : lines;117	const block = commentBlocks(rest, (line) => line.startsWith("#"))[0];118	return block ? joined(block.lines.map((line) => line.replace(/^#+ ?/, ""))) : null;119}120121type Block = { lines: string[]; starred: boolean };122123/**124 * The comment blocks before the first line of code, license header dropped. A block is a run of125 * line comments, or with `starred` one `/* … *\/` comment; blank lines separate blocks.126 */127function commentBlocks(128	lines: string[],129	isComment: (trimmed: string) => boolean,130	starred = false,131): Block[] {132	const blocks: Block[] = [];133	let i = 0;134	while (i < lines.length) {135		const line = (lines[i] as string).trim();136		if (line === "") {137			i++;138		} else if (starred && line.startsWith("/*")) {139			const start = i;140			while (i < lines.length && !(lines[i] as string).includes("*/")) i++;141			if (i === lines.length) break;142			const body = lines.slice(start, ++i).map((l) => l.trim());143			blocks.push({ lines: body, starred: true });144			if (!(lines[i - 1] as string).trim().endsWith("*/")) break;145		} else if (isComment(line)) {146			const body: string[] = [];147			while (i < lines.length && isComment((lines[i] as string).trim())) {148				body.push((lines[i++] as string).trim());149			}150			blocks.push({ lines: body, starred: false });151		} else {152			break;153		}154	}155	if (blocks[0] && LICENSE.test(blocks[0].lines.join("\n"))) blocks.shift();156	return blocks;157}158159// Python: the module docstring, the first statement when it is a string; comments may precede it.160function docstring(lines: string[]): string | null {161	let i = 0;162	while (i < lines.length && /^\s*(#.*)?$/.test(lines[i] as string)) i++;163	const open = /^[rRuU]?("""|'''|"|')/.exec(lines[i] ?? "");164	if (!open) return null;165	const quote = open[1] as string;166	const first = (lines[i] as string).slice(open[0].length);167	const body: string[] = [];168	for (let line = first, n = i; n < lines.length; line = lines[++n] ?? "") {169		const close = line.indexOf(quote);170		if (close >= 0) {171			body.push(line.slice(0, close));172			return joined(dedent(body));173		}174		if (quote.length === 1) return null;175		body.push(line);176	}177	return null;178}179180// Like Python's inspect.cleandoc: continuation lines lose their common indent.181function dedent(lines: string[]): string[] {182	const rest = lines.slice(1).filter((line) => line.trim() !== "");183	const indent = Math.min(...rest.map((line) => (/^\s*/.exec(line) as RegExpExecArray)[0].length));184	return [185		(lines[0] as string).trim(),186		...lines.slice(1).map((line) => line.slice(Number.isFinite(indent) ? indent : 0)),187	];188}189190function firstParagraph(text: string): string | null {191	const tokens = markdown.parse(text, {});192	const map = tokens.find((token) => token.type === "paragraph_open" && token.level === 0)?.map;193	return map ? joined(text.split(/\r?\n/).slice(map[0], map[1])) : null;194}