github-action-readme-generator 1.12.8 → 2.0.0

package/dist/mjs/index.d.ts

@@ -2,6 +2,5 @@
 /**
  * Creates a ReadmeGenerator instance and generates docs.
  */
-declare function generateReadme(): Promise<void>;
-//#endregion
-export { generateReadme };
+export declare function generateReadme(): Promise<void>;
+//#endregion

package/dist/mjs/index.js

@@ -10,7 +10,6 @@ import * as feather from "feather-icons";
 import { icons } from "feather-icons";
 import chalkPkg from "chalk";
 import { execFileSync, execSync } from "node:child_process";
-import { EOL } from "node:os";
 import * as markdown from "prettier/plugins/markdown";
 import * as yaml from "prettier/plugins/yaml";
 import { format } from "prettier/standalone";
@@ -717,14 +716,15 @@ function getCurrentVersionString(inputs) {
 		const actionDir = path$1.dirname(inputs.action.path);
 		log.debug(`version source: ${versionSource}`);
 		let detectedVersion;
-		if (versionSource === "explicit") if (override && override.length > 0) {
-			detectedVersion = override;
-			log.debug(`using explicit version override: ${detectedVersion}`);
+		if (versionSource === "explicit") {
+			if (override && override.length > 0) {
+				detectedVersion = override;
+				log.debug(`using explicit version override: ${detectedVersion}`);
+			} else {
+				log.debug("explicit mode but no version_override set, falling back to 0.0.0");
+				detectedVersion = "0.0.0";
+			}
 		} else {
-			log.debug("explicit mode but no version_override set, falling back to 0.0.0");
-			detectedVersion = "0.0.0";
-		}
-		else {
 			switch (versionSource) {
 				case "git-branch":
 					detectedVersion = getVersionFromGitBranch(actionDir, log);
@@ -859,14 +859,51 @@ const startTokenFormat = "(^|[^`\\\\])<!--\\s+start\\s+%s\\s+-->";
 * The format for the end token of a section.
 */
 const endTokenFormat = "(^|[^`\\\\])<!--\\s+end\\s+%s\\s+-->";
+/**
+* Lays out section content the way it sits between its markers.
+* @param {string} content - The trimmed section content.
+* @param {boolean} addNewlines - Whether to pad the content with newlines.
+* @returns {string} - The text that goes between the markers.
+*/
+function layoutSpan(content, addNewlines) {
+	return addNewlines ? `\n\n${content}\n` : content;
+}
+/**
+* True when every line break in `text` is CRLF, and there is at least one.
+*
+* Only a document that is CRLF throughout is edited as CRLF. Removing the `\r`
+* before each `\n` and adding it back is then an exact round trip, so the
+* bytes outside the markers survive. A document that mixes the two is left as
+* it is, since no single ending would reproduce it.
+* @param {string} text - The document.
+* @returns {boolean} - Whether the document uses CRLF line endings.
+*/
+function usesCrlf(text) {
+	return text.includes("\r\n") && !/(^|[^\r])\n/.test(text);
+}
 var ReadmeEditor = class {
 	log = new LogTask("ReadmeEditor");
 	/**
 	* The path to the README file.
 	*/
 	filePath;
+	/**
+	* The document with LF line endings, whatever the file uses. Every edit and
+	* every formatter pass works on LF; `dumpToFile` restores the file's own
+	* ending on the way out.
+	*/
 	fileContent;
 	/**
+	* Whether the file on disk is CRLF throughout — see `usesCrlf`.
+	*/
+	crlf = false;
+	/**
+	* The padded sections this editor has replaced, each against the content it
+	* wrote. `dumpToFile` formats these spans and nothing else — see
+	* `formatUpdatedSections`.
+	*/
+	updatedSections = /* @__PURE__ */ new Map();
+	/**
 	* Creates a new instance of `ReadmeEditor`.
 	* @param {string} filePath - The path to the README file.
 	*/
@@ -874,15 +911,17 @@ var ReadmeEditor = class {
 		this.filePath = filePath;
 		try {
 			fs.accessSync(filePath);
-			this.fileContent = fs.readFileSync(filePath, "utf8");
-			if (process.env.GITHUB_ACTIONS) core.setOutput("readme_before", this.fileContent);
+			const raw = fs.readFileSync(filePath, "utf8");
+			if (process.env.GITHUB_ACTIONS) core.setOutput("readme_before", raw);
+			this.crlf = usesCrlf(raw);
+			this.fileContent = this.crlf ? raw.replaceAll("\r\n", "\n") : raw;
 		} catch (error) {
 			this.log.fail(`Readme at '${filePath}' does not exist.`);
 			throw error;
 		}
 	}
 	/**
-	* Gets the current README content.
+	* Gets the current README content, with LF line endings.
 	* @returns {string} - The README file content.
 	*/
 	getReadmeContent() {
@@ -917,24 +956,66 @@ var ReadmeEditor = class {
 	*/
 	updateSection(name, providedContent, addNewlines = true) {
 		const log = new LogTask(name);
-		const content = (Array.isArray(providedContent) ? providedContent.join(EOL) : providedContent ?? "").trim();
+		const content = (Array.isArray(providedContent) ? providedContent.join("\n") : providedContent ?? "").replaceAll("\r\n", "\n").trim();
 		log.info(`Looking for the ${name} token in ${this.filePath}`);
 		const [startIndex, stopIndex] = this.getTokenIndexes(name, log);
 		if (startIndex && stopIndex) {
 			const beforeContent = this.fileContent.slice(0, startIndex);
 			const afterContent = this.fileContent.slice(stopIndex);
-			this.fileContent = addNewlines ? `${beforeContent}\n\n${content}\n${afterContent}` : `${beforeContent}${content}${afterContent}`;
+			this.fileContent = `${beforeContent}${layoutSpan(content, addNewlines)}${afterContent}`;
+			if (addNewlines) this.updatedSections.set(name, content);
 		}
 	}
 	/**
+	* Formats the span of one section in isolation and splices it back.
+	*
+	* The content is formatted on its own and reassembled with the same
+	* surrounding newlines `updateSection` wrote, so the markers and every byte
+	* outside them survive untouched.
+	*
+	* The span is formatted only while its markers still bound exactly the text
+	* `updateSection` wrote. The markers are paired again here, after every
+	* section has been written, and a marker another section wrote can win that
+	* pairing; the text between such a pair is not this tool's to format.
+	* @param {string} name - The name of the section.
+	* @param {string} content - The content `updateSection` wrote, padded.
+	*/
+	async formatSection(name, content) {
+		const [startIndex, stopIndex] = this.getTokenIndexes(name);
+		if (!startIndex || !stopIndex) return;
+		if (startIndex > stopIndex || this.fileContent.slice(startIndex, stopIndex) !== layoutSpan(content, true)) {
+			this.log.warn(`The '${name}' markers no longer bound the text written to them. Leaving the section unformatted`);
+			return;
+		}
+		const formatted = content === "" ? "" : (await formatMarkdown(content)).trim();
+		const span = formatted === "" ? "\n" : layoutSpan(formatted, true);
+		this.fileContent = `${this.fileContent.slice(0, startIndex)}${span}${this.fileContent.slice(stopIndex)}`;
+	}
+	/**
+	* Formats every span this editor replaced, one span at a time.
+	*
+	* Each span is located again before it is formatted, because formatting the
+	* previous one moves the indexes of the spans after it. A formatted span no
+	* longer holds the text `updateSection` wrote, so it is forgotten once
+	* formatted.
+	* @returns {Promise<void>}
+	*/
+	async formatUpdatedSections() {
+		for (const [name, content] of this.updatedSections) await this.formatSection(name, content);
+		this.updatedSections.clear();
+	}
+	/**
 	* Dumps the modified content back to the README file.
-	* @param {boolean} [prettier=true] - Run the result through prettier before
-	*   writing. Callers pass the resolved `pretty` input; it defaults to true so
-	*   constructing a ReadmeEditor directly keeps the formatting behaviour.
+	* @param {boolean} [prettier=true] - Run the replaced spans through prettier
+	*   before writing. Callers pass the resolved `pretty` input; it defaults to
+	*   true so constructing a ReadmeEditor directly keeps the formatting
+	*   behaviour. Text outside the markers is never formatted, whatever this
+	*   flag says — see `docs/tool-contract.md`.
 	* @returns {Promise<void>}
 	*/
 	async dumpToFile(prettier = true) {
-		const content = prettier ? await formatMarkdown(this.fileContent) : this.fileContent;
+		if (prettier) await this.formatUpdatedSections();
+		const content = this.crlf ? this.fileContent.replaceAll("\n", "\r\n") : this.fileContent;
 		if (process.env.GITHUB_ACTIONS) core.setOutput("readme_after", content);
 		return fs.promises.writeFile(this.filePath, content, "utf8");
 	}
@@ -1489,10 +1570,12 @@ function loadConfig(log, providedConfig, configFilePath) {
 	const config = providedConfig ?? new Provider();
 	if (process.env.GITHUB_ACTION === "true") log.info("Running in GitHub action");
 	config.argv(argvOptions);
-	if (configFilePath) if (fs.existsSync(configFilePath)) {
-		log.info(`Config file found: ${configFilePath}`);
-		config.file(configFilePath);
-	} else log.debug(`Config file not found: ${configFilePath}`);
+	if (configFilePath) {
+		if (fs.existsSync(configFilePath)) {
+			log.info(`Config file found: ${configFilePath}`);
+			config.file(configFilePath);
+		} else log.debug(`Config file not found: ${configFilePath}`);
+	}
 	config.env({
 		lowerCase: true,
 		parseValues: true,
@@ -2229,6 +2312,13 @@ function updateTitle(sectionToken, inputs) {
 }
 //#endregion
 //#region src/sections/update-usage.ts
+/**
+* Renders the `usage` section: a fenced workflow snippet naming every action input,
+* each preceded by its description and default as YAML comments.
+* @param {ReadmeSection} sectionToken - The README marker pair to write the section into.
+* @param {Inputs} inputs - The parsed action metadata and the README editor to write with.
+* @returns {Promise<Record<string, string>>} The rendered section, keyed by its section token.
+*/
 async function updateUsage(sectionToken, inputs) {
 	const log = new LogTask(sectionToken);
 	log.start();
@@ -2238,6 +2328,8 @@ async function updateUsage(sectionToken, inputs) {
 	log.info(`Version string: ${versionString}`);
 	const actionReference = `${actionName}@${versionString}`;
 	const indent = "    # ";
+	const defaultLabel = "Default: ";
+	const defaultHang = " ".repeat(9);
 	const content = [];
 	content.push("```yaml", `- uses: ${actionReference}`, "  with:");
 	const inp = inputs.action.inputs;
@@ -2264,7 +2356,11 @@ async function updateUsage(sectionToken, inputs) {
 			if (input !== void 0) {
 				if (!firstInput) content.push("");
 				content.push(...descriptions[key]);
-				if (input.default !== void 0) content.push(`${indent}Default: ${input.default}`);
+				if (input.default !== void 0) {
+					const [firstLine, ...rest] = `${input.default}`.split(/\r\n|\n|\r/);
+					content.push(`${indent}${defaultLabel}${firstLine}`.trimEnd());
+					for (const line of rest) content.push(`${indent}${defaultHang}${line}`.trimEnd());
+				}
 				content.push(`    ${key}: ''`);
 				firstInput = false;
 			}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "github-action-readme-generator",
   "displayName": "bitflight-devops/github-action-readme-generator",
-  "version": "1.12.8",
+  "version": "2.0.0",
   "description": "The docs generator for GitHub Actions. Auto-syncs action.yml to README.md with 8 sections: inputs, outputs, usage, badges, branding & more. Works as CLI or GitHub Action.",
   "keywords": [
     "github-actions",
@@ -128,7 +128,7 @@
       "@semantic-release/github",
       "@semantic-release/git"
     ],
-    "preset": "angular"
+    "preset": "conventionalcommits"
   },
   "dependencies": {
     "@actions/core": "^3.0.0",
@@ -149,13 +149,14 @@
     "@commitlint/prompt": "^21.0.1",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/exec": "^7.1.0",
-    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/git": "^11.0.1",
     "@tsconfig/node24": "^24.0.4",
     "@types/nconf": "^0.10.5",
     "@types/node": "^26.1.1",
-    "@vitest/coverage-v8": "4.1.10",
+    "@vitest/coverage-v8": "4.1.11",
     "@voidzero-dev/vite-plus-core": "0.2.8",
     "commitizen": "^4.3.1",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
     "conventional-commits": "^1.6.0",
     "cz-conventional-changelog": "^3.3.0",
     "dotenv": "^17.2.4",
@@ -168,7 +169,7 @@
     "semantic-release": "^25.0.2",
     "types-package-json": "^2.0.39",
     "typescript": "7.0.2",
-    "vite-plus": "0.2.8"
+    "vite-plus": "0.3.1"
   },
   "engines": {
     "node": ">=24.19.0 <30.0.0",