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 });3031 test("a comment after the first code does not count", () => {32 expect(describeFile("x.kt", "val x = 1\n/** Too late. */\nobject X\n")).toBeNull();33 expect(describeFile("x.go", "package main\n// Too late.\n")).toBeNull();34 expect(describeFile("x.ts", "import x from 'y';\n// Too late.\n")).toBeNull();35 });3637 test("Kotlin, Java and Swift pass over package and import lines first", () => {38 const kt =39 "// SPDX-License-Identifier: MIT\npackage com.peach\n\nimport a.B\n\n/**\n * Idle auto-lock timer.\n */\nclass T\n";40 expect(describeFile("T.kt", kt)).toBe("Idle auto-lock timer.");41 expect(describeFile("X.java", "package a;\nimport b.C;\n// Reads C.\nclass X {}\n")).toBe(42 "Reads C.",43 );44 expect(describeFile("X.swift", "import Foundation\n\n/// A view.\nstruct X {}\n")).toBe(45 "A view.",46 );47 });4849 test("Go build constraints are not a description", () => {50 const go = "//go:build linux\n\n// Package tty talks to terminals.\npackage tty\n";51 expect(describeFile("tty.go", go)).toBe("Package tty talks to terminals.");52 });5354 test("Python takes the module docstring, after comments and a shebang", () => {55 const py =56 '#!/usr/bin/env python3\n# -*- coding: utf-8 -*-\n"""Sync tool.\n\n Indented body.\n"""\nimport os\n';57 expect(describeFile("tool.py", py)).toBe("Sync tool.\n\nIndented body.");58 expect(describeFile("one.py", "'''One line.'''\n")).toBe("One line.");59 expect(describeFile("x.py", 'import os\n"""Not a docstring."""\n')).toBeNull();60 expect(describeFile("x.py", "# Just a comment.\nimport os\n")).toBeNull();61 });6263 test("Shell, Nix, TOML and YAML take the leading # lines after any shebang", () => {64 for (const ext of "sh nix toml yaml".split(" ")) {65 expect(describeFile(`x.${ext}`, "# Builds the thing.\n# Quickly.\nvalue = 1\n")).toBe(66 "Builds the thing.\nQuickly.",67 );68 }69 expect(describeFile("install.sh", "#!/bin/sh\n# Installs kepr.\nset -e\n")).toBe(70 "Installs kepr.",71 );72 expect(describeFile("bin/run", "#!/usr/bin/env bash\n\n# Runs it.\nexec x\n")).toBe("Runs it.");73 expect(describeFile("install.sh", "#!/bin/sh\nset -e\n# Too late.\n")).toBeNull();74 expect(describeFile("bin/tool", "#!/usr/bin/env python3\n# Not shell.\n")).toBeNull();75 });7677 test("Markdown takes the first paragraph, not a heading", () => {78 const md = "# Guide\n\nRead **this** first,\nthen the rest.\n\nMore.\n";79 expect(describeFile("docs/guide.md", md)).toBe("Read **this** first,\nthen the rest.");80 expect(describeFile("empty.md", "# Only a heading\n")).toBeNull();81 });8283 test("no comment, an unknown kind or a binary file means no description", () => {84 expect(describeFile("x.ts", "export const one = 1;\n")).toBeNull();85 expect(describeFile("x.ts", "")).toBeNull();86 expect(describeFile("logo.png", "// looks like a comment\n")).toBeNull();87 expect(describeFile("x.c", "//\n//\nint x;\n")).toBeNull();88 });89});9091describe("license headers", () => {92 test("the first block is skipped when it carries SPDX, copyright or licence wording", () => {93 const headers = [94 "// SPDX-License-Identifier: MIT\n",95 "/*\n * Copyright (c) 2026 June\n */\n",96 "// Licensed under the Apache License, Version 2.0.\n// See LICENSE.\n",97 "/* © 2026 Asha. All rights reserved. */\n",98 ];99 for (const header of headers) {100 expect(describeFile("x.ts", `${header}\n// Real description.\ncode();\n`)).toBe(101 "Real description.",102 );103 expect(describeFile("x.ts", `${header}\ncode();\n`)).toBeNull();104 }105 expect(describeFile("x.nix", "# SPDX-License-Identifier: MIT\n\n# The flake.\n{ }\n")).toBe(106 "The flake.",107 );108 });109110 test("the word copyright alone is not a license header", () => {111 expect(describeFile("x.ts", "// Renders copyright notices for every package.\ncode();\n")).toBe(112 "Renders copyright notices for every package.",113 );114 expect(describeFile("x.ts", "// Copyright © Asha.\n\n// Real.\ncode();\n")).toBe("Real.");115 });116117 test("only the first block, so a description mentioning a licence survives", () => {118 expect(describeFile("x.ts", "// Checks each repo's license file.\ncode();\n")).toBe(119 "Checks each repo's license file.",120 );121 const two = "// Copyright 2026.\n\n// Copyright notices, rendered.\ncode();\n";122 expect(describeFile("x.ts", two)).toBe("Copyright notices, rendered.");123 });124});125126describe("real sources, verbatim headers", () => {127 const lines = (...text: string[]) => `${text.join("\n")}\n`;128129 test("Koh 3, V with //! lines", () => {130 const v = lines(131 "//! AWS Signature Version 4, the part S3 needs.",132 "//!",133 "//! Signing is a fixed recipe: canonicalise the request, hash it, derive a key",134 "//! from the secret for that day and region, and sign the string-to-sign. It is",135 "",136 "module remote",137 );138 expect(firstSentence(describeFile("src/remote/sigv4.v", v) ?? "")).toBe(139 "AWS Signature Version 4, the part S3 needs.",140 );141 });142143 test("Peach, Kotlin with package and imports before the KDoc", () => {144 const kt = lines(145 "package com.peachpasswords.vault",146 "",147 "import androidx.annotation.VisibleForTesting",148 "import kotlinx.coroutines.CoroutineScope",149 "import javax.inject.Singleton",150 "",151 "/**",152 " * Idle auto-lock timer. The vault locks [VaultSettings.autoLockMinutes] after the",153 ' * last user interaction; a null (or non-positive) setting means "never". [poke]',154 " */",155 "@Singleton",156 );157 expect(firstSentence(describeFile("vault/VaultLockTimer.kt", kt) ?? "")).toBe(158 "Idle auto-lock timer.",159 );160 });161162 test("nina, Nix and shell", () => {163 const nix = lines(164 "# Standalone NixOS module for nina — no flake inputs needed.",165 "# Generated by the installer into ~/nina.nix. Also importable directly.",166 "#",167 "# Usage (in configuration.nix):",168 "{ config, lib, pkgs, ... }:",169 );170 expect(firstSentence(describeFile("nixos-module.nix", nix) ?? "")).toBe(171 "Standalone NixOS module for nina — no flake inputs needed.",172 );173 const sh = lines(174 "#!/usr/bin/env sh",175 "# G-01/G-02/G-03 generations validation, run inside the VM. Creates distinct",176 "# system generations by changing the config between applies (a tiny /etc file via",177 "set -u",178 );179 expect(firstSentence(describeFile("test/vm/tests/gen.sh", sh) ?? "")).toBe(180 "G-01/G-02/G-03 generations validation, run inside the VM.",181 );182 });183});184185describe("folders", () => {186 const child = (name: string, text: string) => ({ name, description: describeFile(name, text) });187188 test("a README's leading HTML comment or raw <p align> block is not its first paragraph", () => {189 const readme = '<!-- badges -->\n\n<p align="center">LOGO</p>\n\n# Title\n\nThe intro.\n';190 expect(describeFile("README.md", readme)).toBe("The intro.");191 });192193 test("a README's first paragraph wins over the module file", () => {194 const children = [195 child("mod.zig", "//! From the module.\n"),196 child("README.md", "# Pages\n\nFrom the readme.\n"),197 ];198 expect(describeFolder(children)).toBe("From the readme.");199 });200201 test("else the module file's header, else nothing", () => {202 expect(describeFolder([child("mod.rs", "//! Rust module.\n")])).toBe("Rust module.");203 expect(describeFolder([child("index.ts", "// TS module.\nx();\n")])).toBe("TS module.");204 expect(describeFolder([child("__init__.py", '"""Py package."""\n')])).toBe("Py package.");205 expect(206 describeFolder([child("README.md", "# Only a title\n"), child("mod.zig", "//! Mod.\n")]),207 ).toBe("Mod.");208 expect(describeFolder([child("other.ts", "// Not a module file.\n")])).toBeNull();209 });210});211212describe("the one-line description", () => {213 test("joins hard-wrapped lines and stops at the first sentence", () => {214 expect(firstSentence("Reads the\nbucket. Then more.\n\nNext paragraph.")).toBe(215 "Reads the bucket.",216 );217 });218219 test("ignores full stops inside code, versions and common abbreviations", () => {220 expect(firstSentence("Reads `koh.build`, e.g. v3.0.72 files. More.")).toBe(221 "Reads `koh.build`, e.g. v3.0.72 files.",222 );223 expect(firstSentence("`a. b` is code! Next.")).toBe("`a. b` is code!");224 });225226 test("a paragraph without a full stop is the whole line", () => {227 expect(firstSentence("Command line entry: dispatch table")).toBe(228 "Command line entry: dispatch table",229 );230 });231});