@hugojosefson/cli 0.13.0 → 0.14.1

package/esm/deno.js

@@ -1,6 +1,6 @@
 export default {
     "name": "@hugojosefson/cli",
-    "version": "0.13.0",
+    "version": "0.14.1",
     "license": "MIT",
     "hj": {
         "commandName": "hj"
@@ -170,6 +170,10 @@ export default {
                 "publish-check",
                 "readme-check"
             ]
+        },
+        "validation-compare": {
+            "description": "Compare two fresh validation observation reports without reusing test results",
+            "command": "deno run --allow-read scripts/compare-validation.ts"
         }
     },
     "coverage": {

package/esm/src/cli/partition-readme-contributions.js

@@ -1,4 +1,4 @@
-const pattern = /<!-- hj:readme ([\w:-]+) ([a-f0-9]+) -->\n[\s\S]*?\n<!-- \/hj:readme -->\n?/g;
+import { contributionPattern as pattern } from "../readme/badge-layout.js";
 /** Restore reached owners when a later captured snapshot predates their block. */
 export function partitionReadmeContributions(baseline, features, final) {
     const provider = features.find((feature) => feature.plan.featureId === "readme-build" &&

package/esm/src/features/readme-badge-layout.js

@@ -0,0 +1,16 @@
+import { badgeLayoutResolution, layoutBadges } from "../readme/badge-layout.js";
+export function badgeLayoutDetection(text, path) {
+    if (layoutBadges(text) === text)
+        return undefined;
+    return {
+        state: "drifted",
+        evidence: [],
+        issues: [{
+                code: "readme-badge-layout",
+                kind: "readme",
+                subject: { kind: "repository-path", identifier: path },
+                observation: `${path} badges are not one ordered row after the first paragraph.`,
+                resolution: badgeLayoutResolution(text, path),
+            }],
+    };
+}

package/esm/src/features/readme-build-checks.js

@@ -1,11 +1,13 @@
 /** @module Generated README operation safety checks. */
+import { layoutBadges } from "../readme/badge-layout.js";
 import { fileAccess } from "../repository/file-access.js";
 import { sameJson } from "../operations/local-plan-state.js";
 import { denoTaskDefinitions, readmeTaskDefinition } from "./deno-tasks.js";
 import { inspectReadmeBuild, readmeBuildDirectoryPath, readmeBuildFeatureId, readmeBuildRootPath, } from "./readme-build-state.js";
 export async function checkEnableReadmeBuild(context) {
     const state = await inspectReadmeBuild(context);
-    if (exact(state)) {
+    if (exact(state) && state.source.kind === "file" &&
+        layoutBadges(state.source.content) === state.source.content) {
         return noOp("Generated README is already adopted.");
     }
     if (state.legacy.kind === "conflict")

package/esm/src/features/readme-build-detection.js

@@ -1,4 +1,5 @@
 /** @module Generated README feature detection. */
+import { badgeLayoutDetection } from "./readme-badge-layout.js";
 import { fileAccess } from "../repository/file-access.js";
 import { inspectReadmeBuild, readmeBuildRootPath, } from "./readme-build-state.js";
 /** Detects exact generated README source, task, aggregate, output, and mode. */
@@ -35,6 +36,9 @@ export async function detectReadmeBuild(context) {
     if (state.exactTask && state.exactDefault && state.rootMatches &&
         state.root.kind === "file" && !fileAccess(state.root).writable &&
         state.source.kind === "file" && fileAccess(state.source).writable) {
+        const badges = badgeLayoutDetection(state.source.content, "readme/README.md");
+        if (badges)
+            return badges;
         return {
             state: "enabled",
             evidence: [{

package/esm/src/features/readme-build-plans.js

@@ -1,4 +1,5 @@
 /** @module Guarded generated README change plans. */
+import { layoutBadges } from "../readme/badge-layout.js";
 import { fileAccess, repairFileMode } from "../repository/file-access.js";
 import { legacyReadmePreview } from "./readme-build-checks.js";
 import { denoTaskDefinitions, readmeTaskDefinition } from "./deno-tasks.js";
@@ -21,7 +22,7 @@ export async function planEnableReadmeBuild(context, allowed) {
     const initialSource = state.source.kind === "file"
         ? state.source.content
         : state.initialSource;
-    const sourceContent = buildSourceContent(context, state.legacy.kind === "recognized" ? state.legacy.source : initialSource);
+    const sourceContent = layoutBadges(buildSourceContent(context, state.legacy.kind === "recognized" ? state.legacy.source : initialSource));
     if (state.source.kind === "absent") {
         changes.push({ kind: "create-directory", path: readmeBuildDirectoryPath }, {
             kind: "write-file",

package/esm/src/features/readme-contribution-plans.js

@@ -140,6 +140,10 @@ export async function reconcileReadmePlans(context, plans) {
         ?.enabled !== false &&
         (!npmName || context.detections.get(npmBadgeOwner)?.state === "ambiguous" ||
             context.detections.get(npmBadgeOwner) === undefined);
+    // Ambiguous badge ownership cannot safely be composed with other README edits.
+    if (context.detections.get(npmBadgeOwner)?.state === "ambiguous" &&
+        preserveNpmBadge)
+        return plans;
     const provider = build ? "readme-build" : "readme-static";
     // Remove unchanged legacy JSR API blocks before the library adds its block.
     const owners = [

package/esm/src/features/readme-static-feature.js

@@ -1,4 +1,5 @@
 /** @module Built-in exact starter README feature. */
+import { badgeLayoutDetection } from "./readme-badge-layout.js";
 import { fileAccess } from "../repository/file-access.js";
 import { inspectReadmeStatic, readmeStaticFeatureId, readmeStaticIssue, readmeStaticSubject, } from "./readme-static-artifact.js";
 import { checkDisableReadmeStatic, checkEnableReadmeStatic, planDisableReadmeStatic, planEnableReadmeStatic, } from "./readme-static-operations.js";
@@ -18,6 +19,9 @@ async function detectReadmeStatic(context) {
     if (inspection.result !== "unreadable" &&
         inspection.observation.kind === "file" &&
         fileAccess(inspection.observation).writable) {
+        const badges = badgeLayoutDetection(inspection.observation.content, "README.md");
+        if (badges)
+            return badges;
         return {
             state: "enabled",
             evidence: [{

package/esm/src/features/readme-static-operations.js

@@ -1,4 +1,5 @@
 /** @module Exact starter README checks and plans. */
+import { layoutBadges } from "../readme/badge-layout.js";
 import { fileAccess } from "../repository/file-access.js";
 import { planArtifactCreation, planArtifactRemoval, } from "../artifacts/plan-artifact-change.js";
 import { inspectReadmeStatic, readmeStaticBlocker, readmeStaticFeatureId, readmeStaticPath, } from "./readme-static-artifact.js";
@@ -12,6 +13,26 @@ export async function checkEnableReadmeStatic(context) {
     if (inspection.result !== "absent" && inspection.result !== "unreadable" &&
         inspection.observation.kind === "file" &&
         fileAccess(inspection.observation).writable) {
+        if (layoutBadges(inspection.observation.content) !==
+            inspection.observation.content) {
+            return context.repair?.kind === "all-drifted" ||
+                context.repair?.kind === "features" &&
+                    context.repair.featureIds.includes(readmeStaticFeatureId)
+                ? allowed()
+                : {
+                    result: "blocked",
+                    warnings: [],
+                    blockers: [{
+                            code: "readme-badge-layout",
+                            message: "README.md badge layout differs.",
+                            subjects: [{
+                                    kind: "repository-path",
+                                    identifier: readmeStaticPath,
+                                }],
+                            resolution: "Use --repair to move the badges after the first paragraph.",
+                        }],
+                };
+        }
         return {
             result: "no-op",
             reason: "README.md is already writable.",
@@ -90,7 +111,18 @@ export async function checkDisableReadmeStatic(context) {
 export async function planEnableReadmeStatic(context, allowed) {
     if (replacesBuild(context))
         return changePlan("enable", allowed, []);
-    const plan = planArtifactCreation(await inspectReadmeStatic(context));
+    const inspection = await inspectReadmeStatic(context);
+    if (inspection.result !== "absent" && inspection.result !== "unreadable" &&
+        inspection.observation.kind === "file" &&
+        fileAccess(inspection.observation).writable) {
+        return changePlan("enable", allowed, [{
+                kind: "write-file",
+                path: readmeStaticPath,
+                content: layoutBadges(inspection.observation.content),
+                expectedDigest: inspection.observation.digest,
+            }]);
+    }
+    const plan = planArtifactCreation(inspection);
     const repair = await planRepairReadmeStatic(context, allowed);
     if (repair)
         return repair;

package/esm/src/readme/badge-layout.js

@@ -0,0 +1,150 @@
+/** @module Shared README badge ordering and placement without claiming custom badges. */
+/** Markers may surround block content or appear inline between badges. */
+export const contributionPattern = /<!-- hj:readme ([\w:-]+) ([a-f0-9]+) -->([\s\S]*?)<!-- \/hj:readme -->/g;
+const start = "<!-- deno-fmt-ignore-start -->";
+const end = "<!-- deno-fmt-ignore-end -->";
+const target = String.raw `\((?:[^()\n]|\([^()\n]*\))*\)|\[[^\]\n]*\]`;
+const image = String.raw `!\[[^\]\n]*\](?:${target})`;
+const badgePattern = new RegExp(String
+    .raw `\[${image}\](?:${target})|${image}|<a\b[^>]*>\s*<img\b[^>]*>\s*</a>|<img\b[^>]*>`, "gi");
+function isBadge(text, document) {
+    const references = [...text.matchAll(/\[([^\]\n]+)\]/g)].map((match) => match[1].toLowerCase());
+    const destinations = document.split("\n").filter((line) => {
+        const label = /^ {0,3}\[([^\]]+)\]:/.exec(line)?.[1].toLowerCase();
+        return label && references.includes(label);
+    }).join(" ");
+    return /badge|shields\.io|badgen\.net|coveralls\.io/i.test(text + destinations) ||
+        /(?:!\[|alt=["'])(?:ci|npm|jsr|build|status|coverage|license|version|score)(?:[\]"' ]|$)/i
+            .test(text);
+}
+/** Keep fenced examples, inline code, comments and non-badge owned sections intact. */
+function visibleText(text) {
+    let fence;
+    return text.split(/(?<=\n)/).map((line) => {
+        const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+        const hidden = !!fence || !!marker || /^(?: {4}|\t)/.test(line);
+        if (marker) {
+            if (!fence)
+                fence = marker;
+            else if (marker[0] === fence[0] && marker.length >= fence.length) {
+                fence = undefined;
+            }
+        }
+        return hidden ? line.replace(/[^\n]/g, " ") : line;
+    }).join("").replace(/(`+)[^\n]*?\1/g, (code) => " ".repeat(code.length));
+}
+function badges(text) {
+    let visible = visibleText(text);
+    const result = [];
+    for (const match of visible.matchAll(contributionPattern)) {
+        const body = match[3].trim();
+        if (/:badges?$/.test(match[1]) && body.replace(badgePattern, "").trim() === "") {
+            result.push({
+                start: match.index,
+                end: match.index + match[0].length,
+                text: text.slice(match.index, match.index + match[0].length),
+                owner: match[1].split(":")[0],
+            });
+        }
+        visible = visible.slice(0, match.index) +
+            match[0].replace(/[^\n]/g, " ") +
+            visible.slice(match.index + match[0].length);
+    }
+    visible = visible.replace(/<!--[\s\S]*?-->/g, (comment) => comment.replace(/[^\n]/g, " "));
+    for (const match of visible.matchAll(badgePattern)) {
+        // A linked screenshot is still an illustration. Recognize badge labels,
+        // provider URLs and reference destinations without adopting their ownership.
+        if (!isBadge(match[0], text))
+            continue;
+        result.push({
+            start: match.index,
+            end: match.index + match[0].length,
+            text: text.slice(match.index, match.index + match[0].length),
+        });
+    }
+    return result.sort((a, b) => a.start - b.start);
+}
+function order(badge) {
+    const owner = badge.owner === "jsr-package"
+        ? "github-release-publish-jsr"
+        : badge.owner;
+    return owner?.startsWith("github-release-publish-")
+        ? `0:${owner}`
+        : owner
+            ? `1:${owner}`
+            : "2:";
+}
+/** Locate the first prose paragraph, skipping titles, metadata and other blocks. */
+function paragraphEnd(text) {
+    const visible = visibleText(text).replace(/<!--[\s\S]*?-->/g, (comment) => comment.replace(/[^\n]/g, " "));
+    let offset = 0;
+    let frontmatter = visible.startsWith("---\n");
+    for (const block of visible.split(/\n[ \t]*\n/)) {
+        const at = visible.indexOf(block, offset);
+        offset = at + block.length;
+        if (frontmatter) {
+            const close = block.indexOf("\n---", 3);
+            if (close >= 0)
+                frontmatter = false;
+            continue;
+        }
+        const body = block.trim();
+        // A section body is not the README introduction. With no introduction,
+        // place badges after the title instead of nesting them inside an owned guide.
+        if (/^#{2,6}\s/.test(body))
+            break;
+        if (!body ||
+            /^(?:#{1,6}\s|[>|]|[-*+]\s|\d+[.)]\s|@@include\(|<|\[[^\]]+\]:)/.test(body) || /\n[=-]+\s*$/.test(body))
+            continue;
+        const containing = [...text.matchAll(contributionPattern)].find((match) => match.index < offset && offset < match.index + match[0].length);
+        return containing ? containing.index + containing[0].length : offset;
+    }
+    const title = /^# .*(?:\n|$)/m.exec(visible);
+    return title ? title.index + title[0].trimEnd().length : 0;
+}
+/** Returns a stable single-line badge row directly after the introduction. */
+export function layoutBadges(text) {
+    const found = badges(text);
+    if (!found.length) {
+        return text.replace(new RegExp(`${start}\\s*${end}\\n?`, "g"), "");
+    }
+    const removed = "\0hj-badge\0";
+    let remaining = text;
+    for (const badge of [...found].reverse()) {
+        remaining = remaining.slice(0, badge.start) + removed +
+            remaining.slice(badge.end);
+    }
+    // Retire only a formatter wrapper containing badges and whitespace.
+    remaining = remaining.replace(new RegExp(`${start}\\s*(?:${removed}\\s*)+${end}`, "g"), removed);
+    const gaps = new RegExp(`[ \\t\\r\\n]*(?:${removed}[ \\t\\r\\n]*)+`, "g");
+    remaining = remaining.replace(gaps, (gap, at) => {
+        if (gap.includes("\n")) {
+            return at === 0
+                ? ""
+                : at + gap.length === remaining.length
+                    ? "\n"
+                    : "\n\n";
+        }
+        return /\s/.test(gap) ? " " : "";
+    });
+    const row = found.sort((a, b) => order(a).localeCompare(order(b)))
+        .map((badge) => badge.text.replace(/\s+/g, " ").trim()).join(" ");
+    // An initial comment must be a separate HTML block so the badges render as Markdown.
+    const rendered = row.replace(/^(<!-- hj:readme [\w:-]+ [a-f0-9]+ -->) /, "$1\n\n");
+    const at = paragraphEnd(remaining);
+    const before = remaining.slice(0, at).trimEnd();
+    const after = remaining.slice(at).replace(/^\s*\n/, "");
+    const result = (before ? before + "\n\n" : "") + start + "\n" + rendered +
+        "\n" +
+        end + "\n" +
+        (after ? "\n" + after : "");
+    const withoutWrapper = (value) => value.replaceAll(start + "\n", "").replaceAll("\n" + end, "");
+    return withoutWrapper(result) === withoutWrapper(text) ? text : result;
+}
+/** Specific repair details, including the resulting badge identities and order. */
+export function badgeLayoutResolution(text, path) {
+    const names = badges(text).sort((a, b) => order(a).localeCompare(order(b)))
+        .map((badge) => badge.owner ?? badge.text);
+    return `Move all badges in ${path} onto one horizontal line immediately after the first paragraph. ` +
+        `Set badge order to: ${names.join("; ")}. Preserve badge links and ownership comments.`;
+}

package/esm/src/readme/contribution-blocks.js

@@ -1,6 +1,6 @@
 /** @module Individually owned README blocks that preserve user edits. */
 import { digestBytes } from "../repository/digest-bytes.js";
-const pattern = /<!-- hj:readme ([\w:-]+) ([a-f0-9]+) -->\n([\s\S]*?)\n<!-- \/hj:readme -->\n?/g;
+import { contributionPattern as pattern, layoutBadges, } from "./badge-layout.js";
 export async function blockHash(content) {
     return await digestBytes(new TextEncoder().encode(content));
 }
@@ -53,9 +53,8 @@ export async function reconcileBlocks(text, desired, owner) {
             text = text.replace(match[0], await wrap(item));
         else {
             const at = text.indexOf(match[0]);
-            const before = text.slice(0, at).replace(/\n+$/, "");
-            const after = text.slice(at + match[0].length).replace(/^\n+/, "");
-            text = before + (after ? "\n\n" + after : "\n");
+            text = text.slice(0, at) + text.slice(at + match[0].length);
+            text = text.replace(/\n{3,}/g, "\n\n").replace(/\n+$/, "\n");
         }
     }
     for (const item of pending.values()) {
@@ -72,23 +71,12 @@ export async function reconcileBlocks(text, desired, owner) {
                 ? text.includes("[![JSR")
                 : item.id === "github-ci:badge"
                     ? text.includes("[![CI]")
-                    : npmBadgeImages(text).length > 0))
+                    : item.id === "github-release-publish-npm:badge" &&
+                        npmBadgeImages(text).length > 0))
             continue;
         const block = await wrap(item);
         if (item.position === "badges") {
-            const section = text.search(/^## /m);
-            const marker = text.indexOf("<!-- hj:readme ");
-            let at = Math.min(section < 0 ? text.length : section, marker < 0 ? text.length : marker);
-            const order = [
-                "jsr-package:badges",
-                "github-release-publish-npm:badge",
-                "github-ci:badge",
-            ];
-            const earlier = [...text.matchAll(pattern)].filter((match) => order.indexOf(match[1]) >= 0 &&
-                order.indexOf(match[1]) < order.indexOf(item.id)).at(-1);
-            if (earlier)
-                at = earlier.index + earlier[0].length;
-            text = insert(text, at, block);
+            text = insert(text, text.length, block);
         }
         else {
             const order = [
@@ -104,10 +92,10 @@ export async function reconcileBlocks(text, desired, owner) {
             text = insert(text, at, block);
         }
     }
-    return text;
+    return layoutBadges(text);
 }
 async function wrap(item) {
-    return `<!-- hj:readme ${item.id} ${await contributionHash(item.content)} -->\n${item.content}\n<!-- /hj:readme -->\n`;
+    return `<!-- hj:readme ${item.id} ${await contributionHash(item.content)} -->\n${item.content}\n<!-- /hj:readme -->`;
 }
 function insert(text, at, block) {
     const before = text.slice(0, at).replace(/\n*$/, "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hugojosefson/cli",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Repository tools for Deno, Node.js and Bun.",
   "repository": {
     "type": "git",
@@ -10,7 +10,7 @@
   "bin": {
     "hj": "./esm/hj.js"
   },
-  "gitHead": "47f0f3cdb7ded4b6389f41adf02a78e2926d1733",
+  "gitHead": "c532d6081af46b7cbadf62d754784ed5baa3b158",
   "type": "module",
   "engines": {
     "node": ">=24.0.0",
@@ -29,7 +29,7 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "hjNpmArchive": "hugojosefson-cli-0.13.0.tgz",
+  "hjNpmArchive": "hugojosefson-cli-0.14.1.tgz",
   "_generatedBy": "dnt@0.43.2",
   "files": [
     "esm",