Handle README.md

Author: bep

internal/lib/run.go

@@ -97,12 +97,35 @@ func processDependency(cfg Config, dep Dependency) error {
 	modulePath := path.Join(cfg.ModuleBase, relPath, majorVersionSuffix(requestedVersion))
 	outDir := filepath.Join(cfg.BaseOutputDir, filepath.FromSlash(relPath))
 
-	// Idempotency: if npmpackage.json already records the requested version,
-	// nothing on disk needs to change. We don't even hit the npm registry.
-	if existing, ok := readNpmPackageVersion(outDir); ok && existing == requestedVersion {
-		return nil
+	// Idempotency only covers the npm-version-driven work (network fetch,
+	// tarball unpack, npmpackage.json, hugo.toml). The go.mod module line and
+	// the README's import block depend on cfg.ModuleBase, which can change
+	// between runs even when the npm version doesn't — so those are always
+	// reconciled at the end.
+	existing, hasExisting := readNpmPackageVersion(outDir)
+	if !hasExisting || existing != requestedVersion {
+		if err := syncPackageFromNpm(dep, outDir); err != nil {
+			return err
+		}
 	}
 
+	// `hugo mod init` refuses to overwrite an existing go.mod. If one already
+	// exists, rewrite just the module statement if needed — that handles a
+	// major-version bump (or a --module-base change) without touching any
+	// require/replace lines the user may have added.
+	goModPath := filepath.Join(outDir, "go.mod")
+	if _, err := os.Stat(goModPath); err == nil {
+		if err := ensureGoModModulePath(goModPath, modulePath); err != nil {
+			return err
+		}
+	} else if err := runHugoModInit(outDir, modulePath); err != nil {
+		return err
+	}
+
+	return writeReadme(outDir, dep.Name, modulePath)
+}
+
+func syncPackageFromNpm(dep Dependency, outDir string) error {
 	npmv, err := FetchPackageVersion(dep.Name, stripRangePrefix(dep.VersionRange))
 	if err != nil {
 		return err
@@ -135,19 +158,72 @@ func processDependency(cfg Config, dep Dependency) error {
 	// The Hugo mount target keeps the original npm name (including any "@"
 	// scope prefix) so user code can write `import x from "@scope/pkg"`. Only
 	// Go module paths need the "@" stripped; the virtual assets path doesn't.
-	if err := writeHugoConfig(outDir, dep.Name); err != nil {
-		return err
+	return writeHugoConfig(outDir, dep.Name)
+}
+
+const (
+	readmeMarkerBegin = "<!-- npmtohugomod:imports:begin -->"
+	readmeMarkerEnd   = "<!-- npmtohugomod:imports:end -->"
+)
+
+// writeReadme creates the package README on first run, or refreshes the
+// marker-delimited "Hugo import" block on subsequent runs. If the file
+// exists but the markers were stripped, it's left untouched.
+func writeReadme(outDir, npmName, modulePath string) error {
+	readmePath := filepath.Join(outDir, "README.md")
+	importsBlock := renderReadmeImportsBlock(modulePath)
+
+	existing, err := os.ReadFile(readmePath)
+	if err != nil {
+		if !os.IsNotExist(err) {
+			return err
+		}
+		fresh := renderReadmeTemplate(npmName, importsBlock)
+		return writeTextFile(readmePath, []byte(fresh))
 	}
 
-	// `hugo mod init` refuses to overwrite an existing go.mod. If one already
-	// exists, rewrite just the module statement if needed — that handles a
-	// major-version bump that changes the "/vN" suffix without touching any
-	// require/replace lines the user may have added.
-	goModPath := filepath.Join(outDir, "go.mod")
-	if _, err := os.Stat(goModPath); err == nil {
-		return ensureGoModModulePath(goModPath, modulePath)
+	updated, ok := replaceBetweenMarkers(string(existing), readmeMarkerBegin, readmeMarkerEnd, importsBlock)
+	if !ok || updated == string(existing) {
+		return nil
+	}
+	return writeTextFile(readmePath, []byte(updated))
+}
+
+func renderReadmeImportsBlock(modulePath string) string {
+	var b strings.Builder
+	b.WriteString("\n## Hugo import\n\n")
+	b.WriteString("Add this to your Hugo project's `hugo.toml`:\n\n")
+	b.WriteString("```toml\n")
+	b.WriteString("[module]\n")
+	b.WriteString("  [[module.imports]]\n")
+	fmt.Fprintf(&b, "    path = %q\n", modulePath)
+	b.WriteString("```\n")
+	return b.String()
+}
+
+func renderReadmeTemplate(npmName, importsBlock string) string {
+	var b strings.Builder
+	fmt.Fprintf(&b, "# %s\n\n", npmName)
+	fmt.Fprintf(&b, "Hugo Module wrapper for the npm package [%s](https://www.npmjs.com/package/%s).\n\n", npmName, npmName)
+	b.WriteString(readmeMarkerBegin)
+	b.WriteString(importsBlock)
+	b.WriteString(readmeMarkerEnd)
+	b.WriteString("\n")
+	return b.String()
+}
+
+func replaceBetweenMarkers(content, begin, end, replacement string) (string, bool) {
+	beginIdx := strings.Index(content, begin)
+	if beginIdx == -1 {
+		return content, false
+	}
+	afterBegin := beginIdx + len(begin)
+	endRel := strings.Index(content[afterBegin:], end)
+	if endRel == -1 {
+		return content, false
 	}
-	return runHugoModInit(outDir, modulePath)
+	endIdx := afterBegin + endRel
+	return content[:afterBegin] + replacement + content[endIdx:], true
 }
 
 func ensureGoModModulePath(path, want string) error {

testscripts/hugodocs.txt

@@ -25,6 +25,12 @@ grep '^module example.com/test/alpinejs/persist/v3$' alpinejs/persist/go.mod
 grep '^module example.com/test/hotwired/turbo/v8$' hotwired/turbo/go.mod
 grep '^module example.com/test/alpinejs/v3$' alpinejs/go.mod
 
+# READMEs are generated with the matching module path.
+grep 'path = "example.com/test/alpinejs/focus/v3"' alpinejs/focus/README.md
+grep 'path = "example.com/test/alpinejs/persist/v3"' alpinejs/persist/README.md
+grep 'path = "example.com/test/hotwired/turbo/v8"' hotwired/turbo/README.md
+grep 'path = "example.com/test/alpinejs/v3"' alpinejs/README.md
+
 # Idempotency: re-running with the same package.json should be a no-op
 # (in particular it must not fail on `hugo mod init` complaining about an
 # existing go.mod).

testscripts/popper.txt

@@ -12,6 +12,20 @@ cmp popperjs/core/hugo.toml golden/popperjs/core/hugo.toml
 # local Hugo install, so we only assert the module line.
 grep '^module example.com/test/popperjs/core/v2$' popperjs/core/go.mod
 
+# README is generated with a marker-delimited Hugo import block.
+exists popperjs/core/README.md
+grep 'path = "example.com/test/popperjs/core/v2"' popperjs/core/README.md
+grep 'npmtohugomod:imports:begin' popperjs/core/README.md
+grep 'npmtohugomod:imports:end' popperjs/core/README.md
+
+# Changing --module-base updates the import path in both README and go.mod
+# even though the npm version is unchanged.
+npmtohugomod --module-base other.example.com/foo
+! stderr .
+grep '^module other.example.com/foo/popperjs/core/v2$' popperjs/core/go.mod
+grep 'path = "other.example.com/foo/popperjs/core/v2"' popperjs/core/README.md
+! grep 'example.com/test' popperjs/core/README.md
+
 # We read dependencies section only
 # We ignore any version range syntax, fetch specific versions only.
 -- package.json --