1import { describe, expect, test } from "bun:test";2import { describeFile, describeFolder, firstSentence } from "../src/describe/describe.ts";34describe("descriptions by kind (§21.5)", () => {5 test("Zig and Rust take the leading //! lines, not /// or //", () => {6 const zig = '//! Tree rendering.\n//!\n//! Second paragraph.\n\nconst std = @import("std");\n';7 expect(describeFile("src/tree.zig", zig)).toBe("Tree rendering.\n\nSecond paragraph.");8 const rust = "// Copyright 2026 June\n\n//! Parses things.\nuse std::io;\n";9 expect(describeFile("src/lib.rs", rust)).toBe("Parses things.");10 expect(describeFile("a.zig", "// main.zig — entry point\nconst std = 1;\n")).toBeNull();11 expect(describeFile("a.rs", "/// Doc of a function.\nfn main() {}\n")).toBeNull();12 });1314 test("V, Go, C, C++, Swift, Kotlin, Java, JS and TS take the leading // block", () => {15 for (const ext of "v go c h cpp swift kt java js ts".split(" ")) {16 expect(describeFile(`x.${ext}`, "// Reads the bucket.\n// Two lines.\n\ncode();\n")).toBe(17 "Reads the bucket.\nTwo lines.",18 );19 }20 expect(describeFile("cli.v", "//! Command line parsing.\n\nmodule cli\n")).toBe(21 "Command line parsing.",22 );23 });2425 test("the /** */ block counts, with its stars and delimiters removed", () => {26 const ts = "/**\n * Markup that is `safe`.\n *\n * More.\n */\nexport class Html {}\n";27 expect(describeFile("html.ts", ts)).toBe("Markup that is `safe`.\n\nMore.");28 expect(describeFile("x.java", "/** One line. */\nclass X {}\n")).toBe("One line.");29 expect(describeFile("x.ts", "/** Describes x. */ export const x = 1;\n")).toBe("Describes x.");30 expect(describeFile("x.ts", "/**\n * Two lines.\n */ export const x = 1;\n")).toBe(31 "Two lines.",32 );33 });3435 test("a comment after the first code does not count", () => {36 expect(describeFile("x.kt", "val x = 1\n/** Too late. */\nobject X\n")).toBeNull();37 expect(describeFile("x.go", "package main\n// Too late.\n")).toBeNull();38 expect(describeFile("x.ts", "import x from 'y';\n// Too late.\n")).toBeNull();39 });4041 test("Kotlin, Java and Swift pass over package and import lines first", () => {42 const kt =43 "// SPDX-License-Identifier: MIT\npackage com.peach\n\nimport a.B\n\n/**\n * Idle auto-lock timer.\n */\nclass T\n";44 expect(describeFile("T.kt", kt)).toBe("Idle auto-lock timer.");45 expect(describeFile("X.java", "package a;\nimport b.C;\n// Reads C.\nclass X {}\n")).toBe(46 "Reads C.",47 );48 expect(describeFile("X.swift", "import Foundation\n\n/// A view.\nstruct X {}\n")).toBe(49 "A view.",50 );51 });5253 test("Go build constraints are not a description", () => {54 const go = "//go:build linux\n\n// Package tty talks to terminals.\npackage tty\n";55 expect(describeFile("tty.go", go)).toBe("Package tty talks to terminals.");56 });5758 test("Python takes the module docstring, after comments and a shebang", () => {59 const py =60 '#!/usr/bin/env python3\n# -*- coding: utf-8 -*-\n"""Sync tool.\n\n Indented body.\n"""\nimport os\n';61 expect(describeFile("tool.py", py)).toBe("Sync tool.\n\nIndented body.");62 expect(describeFile("one.py", "'''One line.'''\n")).toBe("One line.");63 expect(describeFile("x.py", 'import os\n"""Not a docstring."""\n')).toBeNull();64 expect(describeFile("x.py", "# Just a comment.\nimport os\n")).toBeNull();65 });6667 test("Shell, Nix, TOML and YAML take the leading # lines after any shebang", () => {68 for (const ext of "sh nix toml yaml".split(" ")) {69 expect(describeFile(`x.${ext}`, "# Builds the thing.\n# Quickly.\nvalue = 1\n")).toBe(70 "Builds the thing.\nQuickly.",71 );72 }73 expect(describeFile("install.sh", "#!/bin/sh\n# Installs kepr.\nset -e\n")).toBe(74 "Installs kepr.",75 );76 expect(describeFile("bin/run", "#!/usr/bin/env bash\n\n# Runs it.\nexec x\n")).toBe("Runs it.");77 expect(describeFile("install.sh", "#!/bin/sh\nset -e\n# Too late.\n")).toBeNull();78 expect(describeFile("bin/tool", "#!/usr/bin/env python3\n# Not shell.\n")).toBeNull();79 });8081 test("Markdown takes the first paragraph, not a heading", () => {82 const md = "# Guide\n\nRead **this** first,\nthen the rest.\n\nMore.\n";83 expect(describeFile("docs/guide.md", md)).toBe("Read **this** first,\nthen the rest.");84 expect(describeFile("empty.md", "# Only a heading\n")).toBeNull();85 });8687 test("no comment, an unknown kind or a binary file means no description", () => {88 expect(describeFile("x.ts", "export const one = 1;\n")).toBeNull();89 expect(describeFile("x.ts", "")).toBeNull();90 expect(describeFile("logo.png", "// looks like a comment\n")).toBeNull();91 expect(describeFile("x.c", "//\n//\nint x;\n")).toBeNull();92 });93});9495describe("license headers", () => {96 test("the first block is skipped when it carries SPDX, copyright or licence wording", () => {97 const headers = [98 "// SPDX-License-Identifier: MIT\n",99 "/*\n * Copyright (c) 2026 June\n */\n",100 "// Licensed under the Apache License, Version 2.0.\n// See LICENSE.\n",101 "/* © 2026 Asha. All rights reserved. */\n",102 ];103 for (const header of headers) {104 expect(describeFile("x.ts", `${header}\n// Real description.\ncode();\n`)).toBe(105 "Real description.",106 );107 expect(describeFile("x.ts", `${header}\ncode();\n`)).toBeNull();108 }109 expect(describeFile("x.nix", "# SPDX-License-Identifier: MIT\n\n# The flake.\n{ }\n")).toBe(110 "The flake.",111 );112 });113114 test("the word copyright alone is not a license header", () => {115 expect(describeFile("x.ts", "// Renders copyright notices for every package.\ncode();\n")).toBe(116 "Renders copyright notices for every package.",117 );118 expect(describeFile("x.ts", "// Copyright © Asha.\n\n// Real.\ncode();\n")).toBe("Real.");119 });120121 test("only the first block, so a description mentioning a licence survives", () => {122 expect(describeFile("x.ts", "// Checks each repo's license file.\ncode();\n")).toBe(123 "Checks each repo's license file.",124 );125 const two = "// Copyright 2026.\n\n// Copyright notices, rendered.\ncode();\n";126 expect(describeFile("x.ts", two)).toBe("Copyright notices, rendered.");127 });128});129130describe("real sources, verbatim headers", () => {131 const lines = (...text: string[]) => `${text.join("\n")}\n`;132133 test("Koh 3, V with //! lines", () => {134 const v = lines(135 "//! AWS Signature Version 4, the part S3 needs.",136 "//!",137 "//! Signing is a fixed recipe: canonicalise the request, hash it, derive a key",138 "//! from the secret for that day and region, and sign the string-to-sign. It is",139 "",140 "module remote",141 );142 expect(firstSentence(describeFile("src/remote/sigv4.v", v) ?? "")).toBe(143 "AWS Signature Version 4, the part S3 needs.",144 );145 });146147 test("Peach, Kotlin with package and imports before the KDoc", () => {148 const kt = lines(149 "package com.peachpasswords.vault",150 "",151 "import androidx.annotation.VisibleForTesting",152 "import kotlinx.coroutines.CoroutineScope",153 "import javax.inject.Singleton",154 "",155 "/**",156 " * Idle auto-lock timer. The vault locks [VaultSettings.autoLockMinutes] after the",157 ' * last user interaction; a null (or non-positive) setting means "never". [poke]',158 " */",159 "@Singleton",160 );161 expect(firstSentence(describeFile("vault/VaultLockTimer.kt", kt) ?? "")).toBe(162 "Idle auto-lock timer.",163 );164 });165166 test("nina, Nix and shell", () => {167 const nix = lines(168 "# Standalone NixOS module for nina — no flake inputs needed.",169 "# Generated by the installer into ~/nina.nix. Also importable directly.",170 "#",171 "# Usage (in configuration.nix):",172 "{ config, lib, pkgs, ... }:",173 );174 expect(firstSentence(describeFile("nixos-module.nix", nix) ?? "")).toBe(175 "Standalone NixOS module for nina — no flake inputs needed.",176 );177 const sh = lines(178 "#!/usr/bin/env sh",179 "# G-01/G-02/G-03 generations validation, run inside the VM. Creates distinct",180 "# system generations by changing the config between applies (a tiny /etc file via",181 "set -u",182 );183 expect(firstSentence(describeFile("test/vm/tests/gen.sh", sh) ?? "")).toBe(184 "G-01/G-02/G-03 generations validation, run inside the VM.",185 );186 });187});188189describe("folders", () => {190 const child = (name: string, text: string) => ({ name, description: describeFile(name, text) });191192 test("a README's leading HTML comment or raw <p align> block is not its first paragraph", () => {193 const readme = '<!-- badges -->\n\n<p align="center">LOGO</p>\n\n# Title\n\nThe intro.\n';194 expect(describeFile("README.md", readme)).toBe("The intro.");195 });196197 test("a README's first paragraph wins over the module file", () => {198 const children = [199 child("mod.zig", "//! From the module.\n"),200 child("README.md", "# Pages\n\nFrom the readme.\n"),201 ];202 expect(describeFolder(children)).toBe("From the readme.");203 });204205 test("else the module file's header, else nothing", () => {206 expect(describeFolder([child("mod.rs", "//! Rust module.\n")])).toBe("Rust module.");207 expect(describeFolder([child("index.ts", "// TS module.\nx();\n")])).toBe("TS module.");208 expect(describeFolder([child("__init__.py", '"""Py package."""\n')])).toBe("Py package.");209 expect(210 describeFolder([child("README.md", "# Only a title\n"), child("mod.zig", "//! Mod.\n")]),211 ).toBe("Mod.");212 expect(describeFolder([child("other.ts", "// Not a module file.\n")])).toBeNull();213 });214});215216describe("the one-line description", () => {217 test("joins hard-wrapped lines and stops at the first sentence", () => {218 expect(firstSentence("Reads the\nbucket. Then more.\n\nNext paragraph.")).toBe(219 "Reads the bucket.",220 );221 });222223 test("ignores full stops inside code, versions and common abbreviations", () => {224 expect(firstSentence("Reads `koh.build`, e.g. v3.0.72 files. More.")).toBe(225 "Reads `koh.build`, e.g. v3.0.72 files.",226 );227 expect(firstSentence("`a. b` is code! Next.")).toBe("`a. b` is code!");228 });229230 test("a paragraph without a full stop is the whole line", () => {231 expect(firstSentence("Command line entry: dispatch table")).toBe(232 "Command line entry: dispatch table",233 );234 });235});