feat(scripts): add README truthiness checker

Author: Agent

package.json

@@ -41,6 +41,7 @@
     "test": "turbo run test",
     "test:web:focused": "bun run --cwd apps/web test",
     "brand:check": "node scripts/check-brand-identity.ts",
+    "readme:truthiness": "node scripts/check-readme-truthiness.ts",
     "migrations:check": "node scripts/check-migration-lineage.ts",
     "test:desktop-smoke": "turbo run smoke-test --filter=@synara/desktop",
     "test:device": "bun scripts/device-helper-smoke.ts",

scripts/check-readme-truthiness.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  detectReadmeTruthiness,
+  parseUpstreamRemoteSignals,
+  type ReadmeTruthinessEvidence,
+} from "./check-readme-truthiness";
+
+describe("readme truthiness checker", () => {
+  it("flags a built-from-scratch claim when upstream metadata exists", () => {
+    const readme = "Forkara was built from the ground up and is a masterpiece.";
+    const evidence: ReadmeTruthinessEvidence = {
+      upstreamRef: "origin/main",
+      hasUpstreamRemote: true,
+      remotes: [{ name: "origin", fetchUrl: "https://github.com/example/forkara.git" }],
+    };
+
+    const findings = detectReadmeTruthiness(readme, evidence);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      id: "technically-ambitious",
+      title: "Technically Ambitious",
+      readmeClaims: [{ line: 1, text: "Forkara was built from the ground up and is a masterpiece." }],
+    });
+    expect(findings[0]!.evidence[0]).toContain("upstream ref: origin/main");
+  });
+
+  it("flags a no-fork claim when a non-origin tracked remote exists", () => {
+    const readme = "Technically: not a fork and never meant to be related.";
+    const evidence: ReadmeTruthinessEvidence = {
+      upstreamRef: null,
+      hasUpstreamRemote: false,
+      remotes: [{ name: "origin", fetchUrl: "https://github.com/example/forkara.git" }],
+    };
+    const upstreamRemote = { name: "upstream", fetchUrl: "https://github.com/original/forkara.git" };
+
+    const findingsWithFakeUpstream = detectReadmeTruthiness(readme, {
+      ...evidence,
+      hasUpstreamRemote: true,
+      remotes: [evidence.remotes[0]!, upstreamRemote],
+    });
+
+    expect(findingsWithFakeUpstream).toHaveLength(1);
+    expect(findingsWithFakeUpstream[0]).toMatchObject({
+      id: "factual-fork-relationship",
+      title: "Factual Fork Relationship",
+      readmeClaims: [{ line: 1 }],
+    });
+    expect(findingsWithFakeUpstream[0]!.evidence[1]).toContain("upstream: https://github.com/original/forkara.git");
+  });
+
+  it("returns no findings when no upstream signal exists", () => {
+    const readme = "Forkara was built from the ground up.";
+    const evidence: ReadmeTruthinessEvidence = {
+      upstreamRef: null,
+      hasUpstreamRemote: false,
+      remotes: [{ name: "origin", fetchUrl: "https://github.com/example/forkara.git" }],
+    };
+    expect(detectReadmeTruthiness(readme, evidence)).toEqual([]);
+  });
+
+  it("parses git remote -v lines and keeps only one entry per remote name", () => {
+    const lines = [
+      "origin https://github.com/example/forkara.git (fetch)",
+      "origin https://github.com/example/forkara.git (push)",
+      "upstream https://github.com/original/forkara.git (fetch)",
+      "upstream https://github.com/original/forkara.git (push)",
+    ];
+    expect(parseUpstreamRemoteSignals(lines)).toEqual([
+      { name: "origin", fetchUrl: "https://github.com/example/forkara.git" },
+      { name: "upstream", fetchUrl: "https://github.com/original/forkara.git" },
+    ]);
+  });
+});

scripts/check-readme-truthiness.ts

@@ -0,0 +1,210 @@
+// FILE: check-readme-truthiness.ts
+// Purpose: Parody-safe checker for README claims that conflict with local git facts.
+
+import { execFileSync, type ExecSyncOptions } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+interface RemoteEntry {
+  readonly name: string;
+  readonly fetchUrl: string;
+}
+
+export interface ReadmeTruthinessEvidence {
+  readonly upstreamRef: string | null;
+  readonly remotes: readonly RemoteEntry[];
+  readonly hasUpstreamRemote: boolean;
+}
+
+interface ReadmeClaim {
+  readonly line: number;
+  readonly text: string;
+  readonly pattern: string;
+}
+
+export interface ReadmeTruthinessFinding {
+  readonly id: string;
+  readonly title: string;
+  readonly message: string;
+  readonly readmeClaims: readonly ReadmeClaim[];
+  readonly evidence: readonly string[];
+}
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const README_PATH = resolve(REPO_ROOT, "README.md");
+
+const BUILT_FROM_SCRATCH_PATTERNS = [
+  /\bbuilt\s+from\s+the\s+ground\s+up\b/i,
+  /\bbuilt\s+from\s+scratch\b/i,
+  /\bfrom\s+scratch\b/i,
+] as const;
+
+const NO_FORK_RELATIONSHIP_PATTERNS = [
+  /\bno\s+fork\s+relationship\b/i,
+  /\bthis\s+is\s+not\s+a\s+fork\b/i,
+  /\bnot\s+a\s+fork\b/i,
+  /\bnot\s+technically\s+a\s+fork\b/i,
+] as const;
+
+function runGit(args: readonly string[], cwd: string): string | null {
+  const options: ExecSyncOptions = {
+    cwd,
+    encoding: "utf8",
+    stdio: [\"ignore\", \"pipe\", \"pipe\"],
+  };
+  try {
+    return execFileSync("git", [...args], options).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function parseUpstreamRemoteSignals(lines: readonly string[]): readonly RemoteEntry[] {
+  const remoteLine = /^([^\s]+)\s+([^\s]+)\s+\((fetch|push)\)$/u;
+  const remotesByName = new Map<string, string>();
+
+  for (const raw of lines) {
+    const match = remoteLine.exec(raw.trim());
+    if (!match || match[1] === undefined || match[2] === undefined) continue;
+    const [name, url] = [match[1], match[2]!] as const;
+    if (!remotesByName.has(name)) {
+      remotesByName.set(name, url);
+    }
+  }
+
+  return [...remotesByName.entries()].map(([name, fetchUrl]) => ({ name, fetchUrl }));
+}
+
+export function collectGitEvidence(cwd = process.cwd()): ReadmeTruthinessEvidence {
+  const upstreamRef = runGit(["rev-parse", "--abbrev-ref", "@{upstream}"], cwd);
+  const remoteLines = runGit(["remote", "-v"], cwd);
+  const remotes =
+    remoteLines === null || remoteLines.length === 0 ? [] : parseUpstreamRemoteSignals(remoteLines.split("\n"));
+  const hasUpstreamRemote = remotes.some((remote) => remote.name === "upstream");
+
+  return {
+    upstreamRef,
+    remotes,
+    hasUpstreamRemote,
+  };
+}
+
+function collectReadmeClaims(readmeContents: string): {
+  readonly builtFromScratch: readonly ReadmeClaim[];
+  readonly noFork: readonly ReadmeClaim[];
+} {
+  const builtFromScratch: ReadmeClaim[] = [];
+  const noFork: ReadmeClaim[] = [];
+  const lines = readmeContents.split(/\r?\n/);
+
+  for (const [index, line] of lines.entries()) {
+    const lineNumber = index + 1;
+    for (const pattern of BUILT_FROM_SCRATCH_PATTERNS) {
+      if (pattern.test(line)) {
+        builtFromScratch.push({ line: lineNumber, text: line.trim(), pattern: pattern.source });
+        break;
+      }
+    }
+    for (const pattern of NO_FORK_RELATIONSHIP_PATTERNS) {
+      if (pattern.test(line)) {
+        noFork.push({ line: lineNumber, text: line.trim(), pattern: pattern.source });
+        break;
+      }
+    }
+  }
+
+  return { builtFromScratch, noFork };
+}
+
+function hasUpstreamFact(evidence: ReadmeTruthinessEvidence): boolean {
+  const hasAnyRemotes = evidence.remotes.length > 0;
+  const hasNonOriginRemote = evidence.remotes.some((remote) => remote.name !== "origin");
+  return (
+    Boolean(evidence.upstreamRef) ||
+    evidence.hasUpstreamRemote ||
+    (hasAnyRemotes && hasNonOriginRemote)
+  );
+}
+
+function formatEvidence(evidence: ReadmeTruthinessEvidence): readonly string[] {
+  const remoteLines = evidence.remotes.map(
+    (remote) => `${remote.name}: ${remote.fetchUrl}`,
+  );
+  return [
+    evidence.upstreamRef !== null ? `upstream ref: ${evidence.upstreamRef}` : "upstream ref: none",
+    remoteLines.length > 0 ? `remotes: ${remoteLines.join(", ")}` : "remotes: none",
+  ];
+}
+
+export function detectReadmeTruthiness(
+  readmeContents: string,
+  gitEvidence: ReadmeTruthinessEvidence,
+): readonly ReadmeTruthinessFinding[] {
+  const claims = collectReadmeClaims(readmeContents);
+  const evidence = formatEvidence(gitEvidence);
+  const findings: ReadmeTruthinessFinding[] = [];
+
+  if (!hasUpstreamFact(gitEvidence)) {
+    return [];
+  }
+
+  if (claims.builtFromScratch.length > 0) {
+    findings.push({
+      id: "technically-ambitious",
+      title: "Technically Ambitious",
+      message:
+        "The README says this was built from the ground up, but local git still remembers where the lineage came from.",
+      readmeClaims: claims.builtFromScratch,
+      evidence,
+    });
+  }
+
+  if (claims.noFork.length > 0) {
+    findings.push({
+      id: "factual-fork-relationship",
+      title: "Factual Fork Relationship",
+      message:
+        "The README calls this unrelated, yet git metadata points to a tracked upstream lineage.",
+      readmeClaims: claims.noFork,
+      evidence,
+    });
+  }
+
+  return findings;
+}
+
+function renderConsoleFinding(finding: ReadmeTruthinessFinding): void {
+  console.error(`- ${finding.title}: ${finding.message}`);
+  for (const claim of finding.readmeClaims) {
+    console.error(`  - README ${String(claim.line)}: ${claim.text}`);
+  }
+  for (const source of finding.evidence) {
+    console.error(`  - evidence: ${source}`);
+  }
+}
+
+function main(): void {
+  let readmeContents: string;
+  try {
+    readmeContents = readFileSync(README_PATH, "utf8");
+  } catch {
+    console.error("README truthiness checker could not read README.md from repository root.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const findings = detectReadmeTruthiness(readmeContents, collectGitEvidence(REPO_ROOT));
+  if (findings.length === 0) {
+    console.log("README truthiness check passed with nothing suspicious.");
+    return;
+  }
+
+  console.error("README Truthiness Checker: local facts disagree with README bravado.");
+  for (const finding of findings) {
+    renderConsoleFinding(finding);
+  }
+  process.exitCode = 1;
+}
+
+if (import.meta.main) main();