jeduden
diff --git a/‎.github/workflows/release.yml‎
Lines changed: 10 additions & 0 deletions b/‎.github/workflows/release.yml‎
Lines changed: 10 additions & 0 deletions
diff --git a/‎LICENSE‎
Lines changed: 36 additions & 0 deletions b/‎LICENSE‎
Lines changed: 36 additions & 0 deletions
diff --git a/‎PLAN.md‎
Lines changed: 1 addition & 1 deletion b/‎PLAN.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎internal/lint/file.go‎
Lines changed: 56 additions & 3 deletions b/‎internal/lint/file.go‎
Lines changed: 56 additions & 3 deletions
diff --git a/‎internal/lint/file_test.go‎
Lines changed: 151 additions & 0 deletions b/‎internal/lint/file_test.go‎
Lines changed: 151 additions & 0 deletions
diff --git a/‎internal/mdtext/abbr.go‎
Lines changed: 0 additions & 81 deletions b/‎internal/mdtext/abbr.go‎
Lines changed: 0 additions & 81 deletions
@@ -330,6 +330,16 @@ jobs:
           for pkg in npm/dist/*; do
             (cd "$pkg" && npm publish --access public --provenance)
           done
+      - name: Stage LICENSE for root package
+        # The root @mdsmith/cli package directory has no checked-in
+        # LICENSE because the canonical one lives at repo root. npm
+        # auto-includes a top-level LICENSE in the published tarball,
+        # but only if it sits next to package.json at publish time —
+        # so copy it in before `npm publish`. The root LICENSE also
+        # carries the vendored neurosnap/sentences MIT notice for
+        # internal/punkt/, which is what makes this step legally
+        # required for the npm channel.
+        run: cp LICENSE npm/mdsmith/LICENSE
       - name: Publish root package
         working-directory: npm/mdsmith
         run: npm publish --access public --provenance
 
@@ -19,3 +19,39 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+================================================================================
+THIRD-PARTY LICENSES
+================================================================================
+
+This project incorporates source code from the following third-party projects.
+Each project's license appears verbatim below; a copy also lives alongside the
+vendored code in the indicated directory.
+
+--------------------------------------------------------------------------------
+internal/punkt/ — derived from github.com/neurosnap/sentences v1.1.2
+                  (https://github.com/neurosnap/sentences/tree/v1.1.2)
+                  Verbatim copy: internal/punkt/UPSTREAM_LICENSE
+--------------------------------------------------------------------------------
+
+The MIT License (MIT)
+
+Copyright (c) 2015 Eric Bower
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -119,6 +119,6 @@ footer: |
 | 190 | ✅     | opus   | [Intra-file rule parallelism for non-NodeChecker rules](plan/190_intra-file-rule-parallelism.md)                                        |
 | 191 | ✅     | opus   | [Hand-rolled DFA for Punkt's `reAbbr` to skip regex backtracking](plan/191_punkt-reabbr-dfa.md)                                         |
 | 192 | ✅     | opus   | [Run-scoped read cache for catalog cross-host redundancy](plan/192_catalog-run-scoped-readcache.md)                                     |
-| 193 | 🔲     | opus   | [Rework MDS024 to fit the per-rule allocation budget (≤ 10 allocs/op)](plan/193_mds024-allocation-budget.md)                            |
+| 193 | ✅     | opus   | [Rework MDS024 to fit the per-rule allocation budget (≤ 10 allocs/op)](plan/193_mds024-allocation-budget.md)                            |
 | 194 | ✅     | opus   | [Frontpage persona audit — reduce AI-first framing, surface non-AI path](plan/194_frontpage-persona-audit.md)                           |
 <?/catalog?>
@@ -6,6 +6,7 @@ import (
 	"os"
 	"sort"
 	"sync"
+	"sync/atomic"
 
 	"github.com/yuin/goldmark/ast"
 	"github.com/yuin/goldmark/parser"
@@ -108,10 +109,19 @@ type File struct {
 
 // memoEntry guards a single Memo key so build runs exactly once even
 // when several rule passes (or concurrent LSP readers) race for the
-// same key.
+// same key. atomic.Bool + mutex is used instead of sync.Once because
+// once.Do takes a function value as a parameter — the closure
+// `func() { e.val = build() }` Memo would pass captures `e` and
+// `build`, both escape-tracking pointers, so it allocates per call.
+// On hot per-File memos (astutil.CollectSectionParagraphs feeds
+// every paragraph-aware rule), that single closure escape is the
+// dominant per-Check allocation the MDS024 budget gate sees. The
+// atomic flag is a double-checked-lock pattern: cheap atomic load
+// on the warm path, mutex-guarded build on the cold path.
 type memoEntry struct {
-	once sync.Once
 	val  any
+	done atomic.Bool
+	mu   sync.Mutex
 }
 
 // Memo returns the value for key, computing it once via build on the
@@ -123,10 +133,53 @@ type memoEntry struct {
 // passes — three globs and front-matter reads of every matched file
 // per directive. The File is discarded after each Check, so nothing
 // is cached across files or runs.
+//
+// build is invoked directly (no wrapping closure) so the call adds
+// no per-Memo-call allocation beyond the cold-path memoEntry itself.
+//
+// Panic safety mirrors sync.Once: if build panics, the entry is
+// still marked done (via the deferred Store) and the mutex is
+// released (via the deferred Unlock), so the panic propagates
+// without leaving the per-File memo in a deadlocked state.
+// Subsequent calls on the same key serve the zero-value cached
+// result instead of re-running build, matching upstream sync.Once.
 func (f *File) Memo(key string, build func() any) any {
 	ei, _ := f.scratch.LoadOrStore(key, &memoEntry{})
 	e := ei.(*memoEntry)
-	e.once.Do(func() { e.val = build() })
+	if e.done.Load() {
+		return e.val
+	}
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	if !e.done.Load() {
+		defer e.done.Store(true)
+		e.val = build()
+	}
+	return e.val
+}
+
+// MemoFile is the *File-passing variant of Memo: build receives this
+// File as an argument instead of capturing it in a closure. Callers
+// whose build needs nothing beyond File data can pass a package-
+// level function value, which avoids the per-call closure allocation
+// the plain `Memo` form forces on every invocation. The hot
+// astutil.CollectSectionParagraphs path is the canonical user.
+//
+// Panic safety matches Memo's contract: defer Unlock + defer
+// done.Store(true) keep the per-entry mutex from leaking a lock and
+// match sync.Once's "panic still marks done" semantics.
+func (f *File) MemoFile(key string, build func(*File) any) any {
+	ei, _ := f.scratch.LoadOrStore(key, &memoEntry{})
+	e := ei.(*memoEntry)
+	if e.done.Load() {
+		return e.val
+	}
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	if !e.done.Load() {
+		defer e.done.Store(true)
+		e.val = build(f)
+	}
 	return e.val
 }
 
 
@@ -5,6 +5,7 @@ import (
 	"sync"
 	"sync/atomic"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -264,3 +265,153 @@ func TestFile_Memo_ConcurrentSingleBuild(t *testing.T) {
 	assert.Equal(t, int32(1), atomic.LoadInt32(&calls),
 		"build must run exactly once under concurrent access")
 }
+
+// TestFile_MemoFile pins the same contract Memo has — build runs
+// exactly once per key, every later call returns the cached value
+// (the warm-path `return e.val` early-out), and distinct keys are
+// independent — for the *File-passing variant. MemoFile exists so
+// callers can register a package-level builder instead of a closure
+// that captures the File; the *File argument is what makes that
+// possible. The build also asserts it received the same *File the
+// caller passed.
+func TestFile_MemoFile(t *testing.T) {
+	f := &File{Path: "t.md"}
+
+	var calls int32
+	var receivedFile *File
+	build := func(arg *File) any {
+		atomic.AddInt32(&calls, 1)
+		receivedFile = arg
+		return 42
+	}
+
+	require.Equal(t, 42, f.MemoFile("k", build),
+		"first call must compute and return the value")
+	require.Equal(t, 42, f.MemoFile("k", build),
+		"second call must hit the e.done.Load() warm-path return")
+	require.Equal(t, 42, f.MemoFile("k", build),
+		"third call must also serve the cached value")
+	assert.Equal(t, int32(1), atomic.LoadInt32(&calls),
+		"build must run exactly once per key under MemoFile")
+	assert.Same(t, f, receivedFile,
+		"build must receive the same *File the caller passed")
+
+	var otherCalls int32
+	require.Equal(t, "v2", f.MemoFile("k2", func(arg *File) any {
+		atomic.AddInt32(&otherCalls, 1)
+		return "v2"
+	}))
+	assert.Equal(t, int32(1), atomic.LoadInt32(&otherCalls))
+	assert.Equal(t, int32(1), atomic.LoadInt32(&calls),
+		"a distinct key must not re-run the first key's build")
+}
+
+// TestFile_MemoFile_ConcurrentSingleBuild pins that build runs
+// exactly once even under concurrent readers — the mutex-guarded
+// inner check after the atomic.Bool fast-path is what enforces
+// "run-once" between two goroutines that both find done=false on
+// first read. Drives both paths of the double-checked-lock pattern.
+func TestFile_MemoFile_ConcurrentSingleBuild(t *testing.T) {
+	f := &File{Path: "t.md"}
+
+	var calls int32
+	var wg sync.WaitGroup
+	for i := 0; i < 50; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			v := f.MemoFile("shared", func(arg *File) any {
+				atomic.AddInt32(&calls, 1)
+				return "once"
+			})
+			assert.Equal(t, "once", v)
+		}()
+	}
+	wg.Wait()
+	assert.Equal(t, int32(1), atomic.LoadInt32(&calls),
+		"build must run exactly once under concurrent MemoFile access")
+}
+
+// TestFile_MemoFile_IndependentFromMemo pins that the MemoFile and
+// Memo entry-points share the same scratch map — registering a key
+// under one is visible under the other. Without this, the per-key
+// dedup wouldn't compose when a future caller mixes the two forms.
+func TestFile_MemoFile_IndependentFromMemo(t *testing.T) {
+	f := &File{Path: "t.md"}
+	f.Memo("shared", func() any { return "via-Memo" })
+	// MemoFile under the same key must hit the cached entry the
+	// first call populated (the build below must not run).
+	var memoFileCalls int32
+	got := f.MemoFile("shared", func(_ *File) any {
+		atomic.AddInt32(&memoFileCalls, 1)
+		return "via-MemoFile"
+	})
+	assert.Equal(t, "via-Memo", got,
+		"MemoFile must return the value the prior Memo call cached")
+	assert.Equal(t, int32(0), atomic.LoadInt32(&memoFileCalls),
+		"the MemoFile build must not run when Memo populated the key")
+}
+
+// TestFile_Memo_PanicReleasesMutex pins that a panicking build does
+// not leave the per-entry mutex locked. Without `defer e.mu.Unlock()`
+// inside Memo, a panic inside the build would deadlock every later
+// Memo call on the same File (including under -race, where the
+// mutex order is checked). The recover here simulates a caller
+// that catches the panic; the subsequent Memo call must complete
+// within a short deadline rather than block forever.
+func TestFile_Memo_PanicReleasesMutex(t *testing.T) {
+	f := &File{Path: "t.md"}
+
+	func() {
+		defer func() { _ = recover() }()
+		f.Memo("panicky", func() any {
+			panic("boom")
+		})
+	}()
+
+	// If the mutex stayed locked, a second Memo call on the same
+	// key would block forever. Run it in a goroutine with a hard
+	// deadline so the test fails fast on a regression.
+	done := make(chan any, 1)
+	go func() {
+		done <- f.Memo("panicky", func() any { return "recovered" })
+	}()
+	select {
+	case got := <-done:
+		// sync.Once-style semantics: the first build marked the
+		// key done before propagating the panic, so subsequent
+		// calls serve the zero-value cached result without re-
+		// running the build. Either behaviour is acceptable as
+		// long as the call returns; the test pins "no deadlock".
+		t.Logf("Memo after panic returned %#v", got)
+	case <-time.After(2 * time.Second):
+		t.Fatal("Memo deadlocked after a panicking build — " +
+			"the per-entry mutex was not released")
+	}
+}
+
+// TestFile_MemoFile_PanicReleasesMutex is the MemoFile counterpart
+// of TestFile_Memo_PanicReleasesMutex — the same defer-Unlock
+// guarantee must hold for the *File-passing variant.
+func TestFile_MemoFile_PanicReleasesMutex(t *testing.T) {
+	f := &File{Path: "t.md"}
+
+	func() {
+		defer func() { _ = recover() }()
+		f.MemoFile("panicky", func(*File) any {
+			panic("boom")
+		})
+	}()
+
+	done := make(chan any, 1)
+	go func() {
+		done <- f.MemoFile("panicky", func(*File) any { return "recovered" })
+	}()
+	select {
+	case got := <-done:
+		t.Logf("MemoFile after panic returned %#v", got)
+	case <-time.After(2 * time.Second):
+		t.Fatal("MemoFile deadlocked after a panicking build — " +
+			"the per-entry mutex was not released")
+	}
+}