impact-compass 0.2.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "impact-compass",
+  "version": "0.2.0",
+  "description": "Purely statistical, deterministic project idea validator and market research CLI.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adityachauhan0/impact-compass.git"
+  },
+  "private": false,
+  "files": [
+    "assets/",
+    "src/",
+    "DOCUMENTATION.md",
+    "SKILLS.md",
+    "example-*.json",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "test": "vitest run",
+    "start": "next start",
+    "lint": "eslint",
+    "cli": "npx tsx src/cli.ts"
+  },
+  "dependencies": {
+    "katex": "^0.17.0",
+    "lucide-react": "^1.16.0",
+    "next": "16.2.6",
+    "react": "19.2.4",
+    "react-dom": "19.2.4"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.6",
+    "jsdom": "^29.1.1",
+    "playwright": "^1.60.0",
+    "tailwindcss": "^4",
+    "typescript": "^5",
+    "vitest": "^4.1.7"
+  },
+  "overrides": {
+    "postcss": "8.5.15"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,219 @@
+import { readFileSync, writeFileSync } from "fs";
+import { resolve } from "path";
+import { createLockedQueryBundle, type QueryBundleForm } from "./domain/queryBundle";
+import { loadPublicEvidenceReport } from "./services/publicEvidenceReport";
+import type { IdeaBrief } from "./services/reportTypes";
+
+// Simple ANSI color definitions
+const ANSI_RESET = "\x1b[0m";
+const ANSI_BOLD = "\x1b[1m";
+const ANSI_GREEN = "\x1b[32m";
+const ANSI_YELLOW = "\x1b[33m";
+const ANSI_CYAN = "\x1b[36m";
+const ANSI_GRAY = "\x1b[90m";
+
+type CliInput = {
+  idea: IdeaBrief;
+  queryBundleForm: QueryBundleForm;
+};
+
+function drawBar(score: number, width: number = 30): string {
+  const filledLength = Math.round((score / 100) * width);
+  const emptyLength = width - filledLength;
+  const filled = "█".repeat(filledLength);
+  const empty = "░".repeat(emptyLength);
+  
+  let color = ANSI_GREEN;
+  if (score < 50) color = ANSI_YELLOW;
+  if (score < 25) color = ANSI_GRAY;
+
+  return `${color}${filled}${ANSI_RESET}${ANSI_GRAY}${empty}${ANSI_RESET}`;
+}
+
+const banner = `
+${ANSI_CYAN}${ANSI_BOLD}  ___                            _      ____                                    
+ |_ _|_ __ ___  _ __   __ _  ___| |_   / ___|___  _ __ ___  _ __   __ _ ___ ___ 
+  | || '_ \` _ \\| '_ \\ / _\` |/ __| __| | |   / _ \\| '_ \` _ \\| '_ \\ / _\` / __/ __|
+  | || | | | | | |_) | (_| | (__| |_  | |__| (_) | | | | | | |_) | (_| \\__ \\__ \\
+ |___|_| |_| |_| .__/ \\__,_|\\___|\\__|  \\____\\___/|_| |_| |_| .__/ \\__,_|___/___/
+               |_|                                         |_|                  ${ANSI_RESET}
+`;
+
+function wrapText(text: string, width: number): string[] {
+  const words = text.split(" ");
+  const lines: string[] = [];
+  let currentLine = "";
+  
+  for (const word of words) {
+    if (currentLine.length + word.length + 1 > width) {
+      lines.push(currentLine);
+      currentLine = word;
+    } else {
+      currentLine = currentLine ? `${currentLine} ${word}` : word;
+    }
+  }
+  if (currentLine) lines.push(currentLine);
+  return lines;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length < 2) {
+    console.error(`Usage: npm run cli <input.json> <output.json>`);
+    process.exit(1);
+  }
+
+  const inputPath = resolve(process.cwd(), args[0]);
+  const outputPath = resolve(process.cwd(), args[1]);
+
+  let inputData: CliInput;
+  try {
+    const fileContent = readFileSync(inputPath, "utf-8");
+    inputData = JSON.parse(fileContent);
+  } catch (error) {
+    console.error(`Error reading or parsing input file: ${(error as Error).message}`);
+    process.exit(1);
+  }
+
+  // 1. Create Query Bundle
+  const queryBundle = createLockedQueryBundle(inputData.queryBundleForm);
+
+  // --- REAL EVIDENCE COLLECTION LOGS ---
+  console.log(`${ANSI_BOLD}${ANSI_GRAY}▶ INITIATING LIVE EVIDENCE COLLECTION PIPELINE...${ANSI_RESET}`);
+  
+  const fetchJson = async (url: string) => {
+    let apiName = "Live API";
+    try {
+      const hostname = new URL(url).hostname;
+      if (hostname.includes('github')) apiName = 'GitHub';
+      else if (hostname.includes('algolia') || url.includes('hn.')) apiName = 'HackerNews';
+      else if (hostname.includes('reddit')) apiName = 'Reddit';
+      else if (hostname.includes('stackexchange')) apiName = 'StackExchange';
+      else if (hostname.includes('npmjs')) apiName = 'NPM';
+      else if (hostname.includes('wikipedia')) apiName = 'Wikipedia';
+      else if (hostname.includes('apple')) apiName = 'App Store';
+      else apiName = hostname;
+    } catch {}
+    
+    console.log(`  ${ANSI_CYAN}FETCH${ANSI_RESET} [${apiName} API] => ${url}`);
+    const res = await fetch(url, { headers: { "User-Agent": "Impact-Compass-CLI" } });
+    if (!res.ok) {
+      throw new Error(`Failed to fetch ${url}: ${res.statusText}`);
+    }
+    return res.json();
+  };
+
+  // 2. Load Public Evidence Report using the full, robust architecture
+  const report = await loadPublicEvidenceReport({
+    idea: inputData.idea,
+    queryBundle,
+    fetchJson,
+    minimumLoadMs: 0 // Run fast in CLI
+  });
+  
+  console.log(`${ANSI_BOLD}${ANSI_GREEN}✔ API COLLECTION COMPLETE. (STRICT LIVE DATA ONLY)${ANSI_RESET}\n`);
+  
+  const summary = new Map<string, { count: number, typeLabel: string, sourceType: string, query: string, source: string }>();
+  
+  for (const item of report.evidence) {
+    if (!item.included) continue;
+    const typeLabel = `${ANSI_CYAN}LIVE${ANSI_RESET}`;
+    const key = `${typeLabel}-${item.source}-${item.query}`;
+    
+    if (!summary.has(key)) {
+      summary.set(key, { count: 1, typeLabel, sourceType: item.sourceType, query: item.query, source: item.source });
+    } else {
+      summary.get(key)!.count++;
+    }
+  }
+
+  for (const info of summary.values()) {
+    console.log(`  [${info.typeLabel}] ${info.source.padEnd(14, " ")} => Found ${info.count} ${info.sourceType}s for query: "${info.query}"`);
+  }
+  
+  console.log("");
+
+  // Output Aesthetic ASCII report
+  console.log(banner);
+
+  const boxWidth = 74;
+  const drawTop = (title: string) => ` ┌─ ${ANSI_BOLD}${title.padEnd(boxWidth - 5, " ")}${ANSI_RESET}┐`;
+  const drawBot = () => ` └${"─".repeat(boxWidth - 2)}┘`;
+  const drawLine = (text: string) => {
+    // Correctly strip ANSI codes matching the exact escape sequence
+    const rawLen = text.replace(/\x1b\[[0-9;]*m/g, "").length;
+    return ` │ ${text}${" ".repeat(Math.max(0, boxWidth - 4 - rawLen))} │`;
+  };
+
+  // IDEA BRIEF BOX
+  console.log(drawTop("IDEA BRIEF"));
+  console.log(drawLine(`${ANSI_GRAY}Name        :${ANSI_RESET} ${report.idea.name}`));
+  console.log(drawLine(`${ANSI_GRAY}Target User :${ANSI_RESET} ${report.idea.targetUser}`));
+  console.log(drawLine(`${ANSI_GRAY}Lens        :${ANSI_RESET} ${report.idea.lens}`));
+  const wrappedProblem = wrapText(report.idea.problem, boxWidth - 18);
+  console.log(drawLine(`${ANSI_GRAY}Problem     :${ANSI_RESET} ${wrappedProblem[0]}`));
+  for (let i = 1; i < wrappedProblem.length; i++) {
+    console.log(drawLine(`              ${wrappedProblem[i]}`));
+  }
+  console.log(drawBot());
+  console.log("");
+
+  // OVERALL SCORE BOX
+  let scoreColor = ANSI_GREEN;
+  if (report.summary.score < 60) scoreColor = ANSI_YELLOW;
+  if (report.summary.score < 40) scoreColor = ANSI_GRAY;
+  
+  console.log(drawTop("OVERALL COMPASS SCORE"));
+  console.log(drawLine(""));
+  const scoreStr = `[ ${scoreColor}${ANSI_BOLD}${report.summary.score} / 100${ANSI_RESET} ]`;
+  console.log(drawLine(`                              ${scoreStr}`));
+  console.log(drawLine(""));
+  console.log(drawLine(`${ANSI_GRAY}Confidence  :${ANSI_RESET} ${report.summary.confidence} (±${report.summary.uncertainty})`));
+  const wrappedQ = wrapText(report.queryQuality.warning, boxWidth - 18);
+  console.log(drawLine(`${ANSI_GRAY}Query Qual. :${ANSI_RESET} ${ANSI_BOLD}${report.queryQuality.label}${ANSI_RESET} - ${wrappedQ[0]}`));
+  for (let i = 1; i < wrappedQ.length; i++) {
+    console.log(drawLine(`              ${wrappedQ[i]}`));
+  }
+  if (report.integrity.warnings.length > 0) {
+    console.log(drawLine(""));
+    console.log(drawLine(`${ANSI_YELLOW}Warnings    :${ANSI_RESET} ${report.integrity.warnings[0]}`));
+  }
+  console.log(drawBot());
+  console.log("");
+
+  // PILLARS BOX
+  console.log(drawTop("PILLAR BREAKDOWN"));
+  console.log(drawLine(""));
+  for (const pillar of report.pillars) {
+    const label = pillar.label.padEnd(17, " ");
+    const bar = drawBar(pillar.score, 35);
+    const scoreText = pillar.score.toString().padStart(3, " ");
+    console.log(drawLine(`  ${ANSI_BOLD}${label}${ANSI_RESET} [${bar}] ${scoreText}`));
+  }
+  console.log(drawLine(""));
+  console.log(drawBot());
+  console.log("");
+
+  // INTERPRETATION
+  console.log(drawTop("INTERPRETATION"));
+  const wrappedInt = wrapText(report.interpretation, boxWidth - 4);
+  for (const line of wrappedInt) {
+    console.log(drawLine(line));
+  }
+  console.log(drawBot());
+  console.log("");
+  
+  // Write the output to a JSON file
+  try {
+    writeFileSync(outputPath, JSON.stringify(report, null, 2), "utf-8");
+    console.log(` ${ANSI_GREEN}✔ Report securely saved to ${outputPath}${ANSI_RESET}\n`);
+  } catch (error) {
+    console.error(`\nError writing output file: ${(error as Error).message}`);
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/src/domain/evidence.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import {
+  calculateEvidenceIntegrity,
+  filterEvidenceForBundle,
+  type EvidenceItem,
+} from "./evidence";
+import { createLockedQueryBundle } from "./queryBundle";
+
+const evidence: EvidenceItem[] = [
+  {
+    id: "pain-1",
+    source: "Reddit",
+    sourceType: "post",
+    date: "2026-05-08",
+    query: "therapist paperwork",
+    snippet: "Therapists mention too much paperwork after sessions.",
+    link: "https://www.reddit.com/",
+    metricContribution: "Pain",
+    included: true,
+    reason: "Seed inclusion",
+    duplicateCluster: "paperwork-1",
+    signalStrength: 82,
+  },
+  {
+    id: "excluded-1",
+    source: "Reddit",
+    sourceType: "post",
+    date: "2026-05-02",
+    query: "therapy notes",
+    snippet: "Physical therapy treatment notes workflow.",
+    link: "https://www.reddit.com/",
+    metricContribution: "Demand",
+    included: true,
+    reason: "Seed inclusion",
+    duplicateCluster: "physical-1",
+    signalStrength: 40,
+  },
+  {
+    id: "demand-1",
+    source: "YouTube",
+    sourceType: "video",
+    date: "2026-04-18",
+    query: "SOAP notes",
+    snippet: "Tutorial demand around writing faster SOAP notes.",
+    link: "https://www.youtube.com/",
+    metricContribution: "Demand",
+    included: true,
+    reason: "Seed inclusion",
+    duplicateCluster: "soap-1",
+    signalStrength: 64,
+  },
+];
+
+describe("evidence domain", () => {
+  it("marks evidence excluded when it hits bundle exclusions", () => {
+    const bundle = createLockedQueryBundle({
+      problemKeywords: "therapist paperwork, SOAP notes",
+      solutionKeywords: "session note automation",
+      audienceKeywords: "solo therapists",
+      competitorKeywords: "",
+      exclusions: "physical therapy",
+    });
+
+    const filtered = filterEvidenceForBundle(evidence, bundle);
+
+    expect(filtered.find((item) => item.id === "excluded-1")).toMatchObject({
+      included: false,
+      metricContribution: "Excluded",
+      reason: "Excluded by query bundle term: physical therapy.",
+    });
+    expect(filtered.find((item) => item.id === "pain-1")?.included).toBe(true);
+  });
+
+  it("calculates integrity inputs from included evidence only", () => {
+    const integrity = calculateEvidenceIntegrity(
+      filterEvidenceForBundle(
+        evidence,
+        createLockedQueryBundle({
+          problemKeywords: "therapist paperwork, SOAP notes",
+          solutionKeywords: "session note automation",
+          audienceKeywords: "solo therapists",
+          competitorKeywords: "",
+          exclusions: "physical therapy",
+        }),
+      ),
+    );
+
+    expect(integrity.sourceDiversity).toBe(2);
+    expect(integrity.relevantEvidenceCount).toBe(2);
+    expect(integrity.dominantSourceShare).toBe(0.5);
+    expect(integrity.relevancePrecision).toBe(67);
+  });
+});

package/src/domain/evidence.ts

@@ -0,0 +1,99 @@
+import type { QueryBundle } from "./queryBundle";
+
+export type EvidenceSource =
+  | "Hacker News"
+  | "Reddit"
+  | "GitHub"
+  | "Product Hunt"
+  | "Stack Exchange"
+  | "YouTube"
+  | "npm"
+  | "PyPI";
+
+export type SourceType =
+  | "post"
+  | "comment"
+  | "repo"
+  | "package"
+  | "launch"
+  | "question"
+  | "video";
+
+export type MetricContribution =
+  | "Demand"
+  | "Pain"
+  | "Momentum"
+  | "Competition Fit"
+  | "Activity"
+  | "Channel Fit"
+  | "Evidence Quality"
+  | "Excluded";
+
+export type EvidenceItem = {
+  id: string;
+  source: EvidenceSource;
+  sourceType: SourceType;
+  date: string;
+  query: string;
+  snippet: string;
+  link: string;
+  metricContribution: MetricContribution;
+  included: boolean;
+  reason: string;
+  duplicateCluster: string;
+  signalStrength: number;
+};
+
+export type EvidenceIntegrityInput = {
+  sourceDiversity: number;
+  relevancePrecision: number;
+  relevantEvidenceCount: number;
+  dominantSourceShare: number;
+};
+
+function includesTerm(value: string, term: string) {
+  return value.toLocaleLowerCase().includes(term.toLocaleLowerCase());
+}
+
+export function filterEvidenceForBundle(
+  evidence: EvidenceItem[],
+  bundle: QueryBundle,
+): EvidenceItem[] {
+  return evidence.map((item) => {
+    const searchableText = `${item.query} ${item.snippet}`;
+    const exclusion = bundle.exclusions.find((term) => includesTerm(searchableText, term));
+
+    if (!exclusion) {
+      return item;
+    }
+
+    return {
+      ...item,
+      included: false,
+      metricContribution: "Excluded",
+      reason: `Excluded by query bundle term: ${exclusion}.`,
+    };
+  });
+}
+
+export function calculateEvidenceIntegrity(
+  evidence: EvidenceItem[],
+): EvidenceIntegrityInput {
+  const included = evidence.filter((item) => item.included);
+  const sourceCounts = included.reduce<Record<string, number>>((counts, item) => {
+    counts[item.source] = (counts[item.source] ?? 0) + 1;
+    return counts;
+  }, {});
+  const dominantSourceCount = Math.max(0, ...Object.values(sourceCounts));
+
+  return {
+    sourceDiversity: Object.keys(sourceCounts).length,
+    relevancePrecision:
+      evidence.length === 0 ? 0 : Math.round((included.length / evidence.length) * 100),
+    relevantEvidenceCount: included.length,
+    dominantSourceShare:
+      included.length === 0
+        ? 0
+        : Number((dominantSourceCount / included.length).toFixed(2)),
+  };
+}

package/src/domain/queryBundle.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import {
+  createLockedQueryBundle,
+  evaluateQueryQuality,
+  parseTermList,
+} from "./queryBundle";
+
+describe("query bundle domain", () => {
+  it("parses comma and newline separated terms without duplicates", () => {
+    expect(
+      parseTermList("therapist paperwork, SOAP notes\nsoap notes; therapy docs,, "),
+    ).toEqual(["therapist paperwork", "SOAP notes", "therapy docs"]);
+  });
+
+  it("creates an immutable locked query bundle from editable form fields", () => {
+    const bundle = createLockedQueryBundle({
+      problemKeywords: "invoice follow up, late payments",
+      solutionKeywords: "invoice reminder automation",
+      audienceKeywords: "freelancers, consultants",
+      competitorKeywords: "HoneyBook alternative",
+      exclusions: "medical billing",
+    });
+
+    expect(bundle).toMatchObject({
+      version: 1,
+      locked: true,
+      problemKeywords: ["invoice follow up", "late payments"],
+      solutionKeywords: ["invoice reminder automation"],
+      audienceKeywords: ["freelancers", "consultants"],
+      competitorKeywords: ["HoneyBook alternative"],
+      exclusions: ["medical billing"],
+    });
+    expect(bundle.painPhrases).toContain("manual process");
+  });
+
+  it("labels a focused bundle with exclusions as strong", () => {
+    const quality = evaluateQueryQuality(
+      createLockedQueryBundle({
+        problemKeywords: "therapist paperwork, SOAP notes",
+        solutionKeywords: "session note automation",
+        audienceKeywords: "solo therapists",
+        competitorKeywords: "EHR notes",
+        exclusions: "physical therapy",
+      }),
+    );
+
+    expect(quality.label).toBe("Strong");
+    expect(quality.warning).toBe(
+      "Ambiguity controlled with audience terms and exclusions.",
+    );
+  });
+
+  it("flags broad bundles with weak precision", () => {
+    const quality = evaluateQueryQuality(
+      createLockedQueryBundle({
+        problemKeywords: "AI",
+        solutionKeywords: "",
+        audienceKeywords: "",
+        competitorKeywords: "",
+        exclusions: "",
+      }),
+    );
+
+    expect(quality.label).toBe("Too broad");
+    expect(quality.warning).toBe("Add audience terms and exclusions before scoring.");
+  });
+});

package/src/domain/queryBundle.ts

@@ -0,0 +1,116 @@
+export type QueryBundleForm = {
+  problemKeywords: string;
+  solutionKeywords: string;
+  audienceKeywords: string;
+  competitorKeywords: string;
+  exclusions: string;
+};
+
+export type QueryBundle = {
+  version: number;
+  locked: boolean;
+  problemKeywords: string[];
+  solutionKeywords: string[];
+  audienceKeywords: string[];
+  competitorKeywords: string[];
+  painPhrases: string[];
+  exclusions: string[];
+};
+
+export type QueryQualityLabel =
+  | "Too broad"
+  | "Too narrow"
+  | "Ambiguous"
+  | "Good enough"
+  | "Strong";
+
+export type QueryQuality = {
+  label: QueryQualityLabel;
+  warning: string;
+};
+
+const defaultPainPhrases = [
+  "manual process",
+  "too much paperwork",
+  "after-hours notes",
+  "how do I reduce",
+  "alternative to",
+  "too expensive",
+  "workaround",
+];
+
+export function parseTermList(value: string) {
+  const seen = new Set<string>();
+
+  return value
+    .split(/[,\n;]/)
+    .map((term) => term.trim())
+    .filter(Boolean)
+    .filter((term) => {
+      const key = term.toLocaleLowerCase();
+
+      if (seen.has(key)) {
+        return false;
+      }
+
+      seen.add(key);
+      return true;
+    });
+}
+
+export function createLockedQueryBundle(
+  form: QueryBundleForm,
+  options: { version?: number; painPhrases?: string[] } = {},
+): QueryBundle {
+  return {
+    version: options.version ?? 1,
+    locked: true,
+    problemKeywords: parseTermList(form.problemKeywords),
+    solutionKeywords: parseTermList(form.solutionKeywords),
+    audienceKeywords: parseTermList(form.audienceKeywords),
+    competitorKeywords: parseTermList(form.competitorKeywords),
+    painPhrases: options.painPhrases ?? defaultPainPhrases,
+    exclusions: parseTermList(form.exclusions),
+  };
+}
+
+export function evaluateQueryQuality(bundle: QueryBundle): QueryQuality {
+  const totalTerms =
+    bundle.problemKeywords.length +
+    bundle.solutionKeywords.length +
+    bundle.audienceKeywords.length +
+    bundle.competitorKeywords.length;
+
+  if (bundle.problemKeywords.length <= 1 && bundle.audienceKeywords.length === 0) {
+    return {
+      label: "Too broad",
+      warning: "Add audience terms and exclusions before scoring.",
+    };
+  }
+
+  if (totalTerms <= 2) {
+    return {
+      label: "Too narrow",
+      warning: "Add solution, audience, or competitor terms to improve coverage.",
+    };
+  }
+
+  if (bundle.exclusions.length === 0) {
+    return {
+      label: "Ambiguous",
+      warning: "Add exclusions for wrong meanings before scoring.",
+    };
+  }
+
+  if (bundle.audienceKeywords.length > 0 && bundle.exclusions.length > 0) {
+    return {
+      label: "Strong",
+      warning: "Ambiguity controlled with audience terms and exclusions.",
+    };
+  }
+
+  return {
+    label: "Good enough",
+    warning: "Query bundle has enough terms for a preview-quality scan.",
+  };
+}