From a33b847205178d44564937f2e769c85721d64987 Mon Sep 17 00:00:00 2001
From: dacharyc <dc@dacharycarey.com>
Date: Mon, 23 Mar 2026 22:30:15 -0400
Subject: [PATCH] fix: llms-txt-links-markdown: false positive

---
 .../llms-txt/llms-txt-links-markdown.ts       | 22 ++++++++
 .../checks/llms-txt-links-markdown.test.ts    | 53 +++++++++++++++++++
 2 files changed, 75 insertions(+)

diff --git a/src/checks/llms-txt/llms-txt-links-markdown.ts b/src/checks/llms-txt/llms-txt-links-markdown.ts
index 200993a..1510b90 100644
--- a/src/checks/llms-txt/llms-txt-links-markdown.ts
+++ b/src/checks/llms-txt/llms-txt-links-markdown.ts
@@ -1,6 +1,7 @@
 import { registerCheck } from '../registry.js';
 import { extractMarkdownLinks } from './llms-txt-valid.js';
 import { toMdUrls } from '../../helpers/to-md-urls.js';
+import { looksLikeMarkdown } from '../../helpers/detect-markdown.js';
 import type { CheckContext, CheckResult, DiscoveredFile } from '../../types.js';
 
 interface LinkMarkdownResult {
@@ -107,6 +108,27 @@ async function checkLlmsTxtLinksMarkdown(ctx: CheckContext): Promise<CheckResult
               };
             }
 
+            // For .txt URLs (e.g. llms-full.txt, llms-small.txt companion files),
+            // content-sniff because they may contain markdown served as text/plain
+            if (new URL(url).pathname.endsWith('.txt')) {
+              try {
+                const getResp = await ctx.http.fetch(url);
+                if (getResp.ok) {
+                  const body = await getResp.text();
+                  if (looksLikeMarkdown(body)) {
+                    return {
+                      url,
+                      hasMarkdownExtension: false,
+                      servesMarkdown: true,
+                      status: response.status,
+                    };
+                  }
+                }
+              } catch {
+                // Fall through to .md variant check
+              }
+            }
+
             // Try .md variant candidates
             const candidates = toMdUrls(url);
             for (const mdUrl of candidates) {
diff --git a/test/unit/checks/llms-txt-links-markdown.test.ts b/test/unit/checks/llms-txt-links-markdown.test.ts
index 3367bf7..d778bdf 100644
--- a/test/unit/checks/llms-txt-links-markdown.test.ts
+++ b/test/unit/checks/llms-txt-links-markdown.test.ts
@@ -210,6 +210,59 @@ Just text, no links here.
     expect(result.message).toContain('sampled links');
   });
 
+  it('passes for .txt companion files that contain markdown', async () => {
+    server.use(
+      http.head(
+        'http://test.local/llms-full.txt',
+        () =>
+          new HttpResponse(null, {
+            status: 200,
+            headers: { 'content-type': 'text/plain' },
+          }),
+      ),
+      http.get(
+        'http://test.local/llms-full.txt',
+        () =>
+          new HttpResponse(
+            '# Full docs\n\n## API Reference\n\n- [Endpoint](http://test.local/api.md): API',
+            {
+              status: 200,
+              headers: { 'content-type': 'text/plain' },
+            },
+          ),
+      ),
+    );
+
+    const content = `# Test\n> Summary\n## Links\n- [Full docs](http://test.local/llms-full.txt): Complete documentation\n`;
+    const result = await check.run(makeCtx(content));
+    expect(result.status).toBe('pass');
+  });
+
+  it('fails for .txt files that do not contain markdown', async () => {
+    server.use(
+      http.head(
+        'http://test.local/robots.txt',
+        () =>
+          new HttpResponse(null, {
+            status: 200,
+            headers: { 'content-type': 'text/plain' },
+          }),
+      ),
+      http.get(
+        'http://test.local/robots.txt',
+        () =>
+          new HttpResponse('User-agent: *\nDisallow: /private/', {
+            status: 200,
+            headers: { 'content-type': 'text/plain' },
+          }),
+      ),
+    );
+
+    const content = `# Test\n> Summary\n## Links\n- [Robots](http://test.local/robots.txt): Robots file\n`;
+    const result = await check.run(makeCtx(content));
+    expect(result.status).toBe('fail');
+  });
+
   it('uses toMdUrls to find .md variants (handles trailing slash and .html)', async () => {
     server.use(
       http.head(