impact-compass 0.2.0

package/src/services/demoReport.ts

@@ -0,0 +1,32 @@
+import { createLockedQueryBundle } from "../domain/queryBundle";
+import { buildCompassReport } from "./reportBuilder";
+import type { CompassReportModel, IdeaBrief } from "./reportTypes";
+import { therapyEvidenceSeed, therapyPillarScores } from "./therapySeed";
+
+export type DemoReport = CompassReportModel;
+
+export const defaultIdea: IdeaBrief = {
+  name: "Privacy-safe session note drafts",
+  problem:
+    "Solo therapists lose unpaid time turning session context into structured notes.",
+  targetUser: "Solo therapists and small private clinics",
+  lens: "B2B Workflow / Vertical SaaS",
+};
+
+export const defaultQueryForm = {
+  problemKeywords: "therapist paperwork, therapy documentation, SOAP notes",
+  solutionKeywords: "session note drafts, therapy note automation",
+  audienceKeywords: "solo therapists, private practice therapists",
+  competitorKeywords: "therapy notes app, EHR notes",
+  exclusions: "physical therapy, school therapy notes",
+};
+
+export function createDemoReport(): DemoReport {
+  return buildCompassReport({
+    idea: defaultIdea,
+    queryBundle: createLockedQueryBundle(defaultQueryForm),
+    evidence: therapyEvidenceSeed,
+    pillarScores: therapyPillarScores,
+    uncertainty: 11,
+  });
+}

package/src/services/publicEvidenceReport.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { createLockedQueryBundle } from "../domain/queryBundle";
+import { loadPublicEvidenceReport } from "./publicEvidenceReport";
+
+const idea = {
+  name: "Invoice follow-up autopilot",
+  problem: "Freelancers lose time chasing late client payments.",
+  targetUser: "Freelancers and consultants",
+  lens: "Productivity / Prosumer SaaS",
+};
+
+describe("public evidence report loader", () => {
+  it("waits for free source scans before building the report", async () => {
+    const queryBundle = createLockedQueryBundle({
+      problemKeywords: "invoice reminders",
+      solutionKeywords: "invoice automation",
+      audienceKeywords: "freelancers",
+      competitorKeywords: "HoneyBook",
+      exclusions: "medical billing",
+    });
+    const requestedUrls: string[] = [];
+    const report = await loadPublicEvidenceReport({
+      idea,
+      queryBundle,
+      minimumLoadMs: 0,
+      fetchJson: async (url) => {
+        requestedUrls.push(url);
+
+        if (url.includes("api.github.com")) {
+          return {
+            items: [
+              {
+                id: 17,
+                html_url: "https://github.com/example/invoices",
+                full_name: "example/invoices",
+                description: "Invoice reminder automation",
+                updated_at: "2026-05-20T00:00:00Z",
+                stargazers_count: 25,
+                forks_count: 5,
+              },
+            ],
+          };
+        }
+
+        return {
+          hits: [
+            {
+              objectID: "42",
+              title: "Ask HN: Invoice reminder workflows",
+              created_at: "2026-02-02T00:00:00Z",
+              created_at_i: 1770000000,
+              points: 20,
+              num_comments: 10,
+            },
+          ],
+        };
+      },
+    });
+
+    expect(requestedUrls.some((url) => url.includes("api.github.com"))).toBe(true);
+    expect(requestedUrls.some((url) => url.includes("hn.algolia.com"))).toBe(true);
+    expect(report.evidence.some((item) => item.id === "gh-17")).toBe(true);
+    expect(report.evidence.some((item) => item.id === "hn-42")).toBe(true);
+    expect(report.idea.name).toBe("Invoice follow-up autopilot");
+  });
+});

package/src/services/publicEvidenceReport.ts

@@ -0,0 +1,82 @@
+import { createAll35Adapters } from "./sources/extendedAdapters";
+import type { FetchJson, SourceAdapter } from "./sources/sourceAdapter";
+import type { QueryBundle } from "../domain/queryBundle";
+import {
+  derivePillarScoresFromEvidence,
+  deriveUncertainty,
+} from "./queryDerivedReport";
+import { buildCompassReport } from "./reportBuilder";
+import type { CompassReportModel, IdeaBrief } from "./reportTypes";
+
+export type LoadPublicEvidenceReportInput = {
+  idea: IdeaBrief;
+  queryBundle: QueryBundle;
+  fetchJson?: FetchJson;
+  minimumLoadMs?: number;
+};
+
+const defaultMinimumLoadMs = 650;
+const requestTimeoutMs = 8000;
+
+async function defaultFetchJson(url: string) {
+  const controller = new AbortController();
+  const timeoutId = globalThis.setTimeout(() => controller.abort(), requestTimeoutMs);
+
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+
+    if (!response.ok) {
+      throw new Error(`Source request failed: ${response.status}`);
+    }
+
+    return response.json() as Promise<unknown>;
+  } finally {
+    globalThis.clearTimeout(timeoutId);
+  }
+}
+
+function delay(ms: number) {
+  return new Promise((resolve) => {
+    globalThis.setTimeout(resolve, ms);
+  });
+}
+
+async function scanSource(adapter: SourceAdapter, queryBundle: QueryBundle) {
+  try {
+    return await adapter.scan(queryBundle);
+  } catch {
+    return [];
+  }
+}
+
+export async function loadPublicEvidenceReport({
+  idea,
+  queryBundle,
+  fetchJson = defaultFetchJson,
+  minimumLoadMs = defaultMinimumLoadMs,
+}: LoadPublicEvidenceReportInput): Promise<CompassReportModel> {
+  const startedAt = Date.now();
+  // Load all 35 specialized adapters that target 7 distinct pillars
+  const adapters = createAll35Adapters({ fetchJson });
+  
+  const liveEvidence = (
+    await Promise.all(adapters.map((adapter) => scanSource(adapter, queryBundle)))
+  ).flat();
+  
+  const elapsed = Date.now() - startedAt;
+
+  if (elapsed < minimumLoadMs) {
+    await delay(minimumLoadMs - elapsed);
+  }
+
+  // 100% Honest Data - No fallback mocks used
+  const evidence = liveEvidence;
+
+  return buildCompassReport({
+    idea,
+    queryBundle,
+    evidence,
+    pillarScores: derivePillarScoresFromEvidence(evidence),
+    uncertainty: deriveUncertainty(queryBundle),
+  });
+}

package/src/services/queryDerivedReport.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { createLockedQueryBundle } from "../domain/queryBundle";
+import {
+  createQueryDerivedEvidence,
+  derivePillarScoresFromEvidence,
+  deriveUncertainty,
+} from "./queryDerivedReport";
+
+const idea = {
+  name: "Invoice follow-up autopilot",
+  problem: "Freelancers lose time chasing late client payments.",
+  targetUser: "Freelancers and consultants",
+  lens: "Productivity / Prosumer SaaS",
+};
+
+describe("query-derived report inputs", () => {
+  it("creates evidence ledger rows from the locked query bundle", () => {
+    const bundle = createLockedQueryBundle({
+      problemKeywords: "late client payments, unpaid invoices",
+      solutionKeywords: "invoice reminder automation",
+      audienceKeywords: "freelancers, consultants",
+      competitorKeywords: "HoneyBook alternative",
+      exclusions: "medical billing",
+    });
+    const evidence = createQueryDerivedEvidence(idea, bundle);
+
+    expect(evidence.map((item) => item.query)).toContain("late client payments");
+    expect(evidence.map((item) => item.query)).toContain("invoice reminder automation");
+    expect(evidence.map((item) => item.query)).toContain("freelancers");
+    expect(evidence.some((item) => item.snippet.includes("therapist"))).toBe(false);
+    expect(evidence.find((item) => item.metricContribution === "Excluded")).toMatchObject({
+      included: false,
+      query: "medical billing",
+    });
+  });
+
+  it("derives all seven pillar scores from generated evidence strengths", () => {
+    const bundle = createLockedQueryBundle({
+      problemKeywords: "late client payments",
+      solutionKeywords: "invoice reminder automation",
+      audienceKeywords: "freelancers",
+      competitorKeywords: "HoneyBook alternative",
+      exclusions: "medical billing",
+    });
+    const scores = derivePillarScoresFromEvidence(createQueryDerivedEvidence(idea, bundle));
+
+    expect(Object.values(scores).every((score) => score > 0 && score <= 100)).toBe(true);
+  });
+
+  it("lowers uncertainty as query controls become more specific", () => {
+    const broad = createLockedQueryBundle({
+      problemKeywords: "payments",
+      solutionKeywords: "",
+      audienceKeywords: "",
+      competitorKeywords: "",
+      exclusions: "",
+    });
+    const specific = createLockedQueryBundle({
+      problemKeywords: "late client payments",
+      solutionKeywords: "invoice reminder automation",
+      audienceKeywords: "freelancers",
+      competitorKeywords: "HoneyBook alternative",
+      exclusions: "medical billing",
+    });
+
+    expect(deriveUncertainty(specific)).toBeLessThan(deriveUncertainty(broad));
+  });
+});

package/src/services/queryDerivedReport.ts

@@ -0,0 +1,227 @@
+import type { EvidenceItem, EvidenceSource, MetricContribution, SourceType } from "../domain/evidence";
+import type { QueryBundle } from "../domain/queryBundle";
+import type { PillarScores } from "../domain/scoring";
+import type { IdeaBrief } from "./reportTypes";
+
+type EvidenceDraft = {
+  source: EvidenceSource;
+  sourceType: SourceType;
+  query: string;
+  snippet: string;
+  link: string;
+  metricContribution: MetricContribution;
+  reason: string;
+  signalStrength: number;
+};
+
+const generatedDate = "2026-05-24";
+
+function primary(terms: string[], fallback: string) {
+  return terms[0] ?? fallback;
+}
+
+function searchUrl(base: string, query: string) {
+  return `${base}${encodeURIComponent(query)}`;
+}
+
+function clamp(value: number) {
+  return Math.min(100, Math.max(0, Math.round(value)));
+}
+
+function sourceTermScore(termCount: number, bonus: number) {
+  return clamp(38 + termCount * 11 + bonus);
+}
+
+function aggregateVolumeWeighted(values: number[]) {
+  if (values.length === 0) {
+    return 0;
+  }
+
+  // Sort descending to get the highest quality signals first
+  const sorted = [...values].sort((a, b) => b - a);
+  
+  // Take average of top 3 (or fewer if we have less)
+  const topSignals = sorted.slice(0, 3);
+  const baseAverage = topSignals.reduce((sum, val) => sum + val, 0) / topSignals.length;
+  
+  // Apply a volume bonus for every additional piece of evidence (+2 points per item)
+  const volumeBonus = (values.length > 3 ? (values.length - 3) * 2 : 0);
+  
+  return clamp(baseAverage + volumeBonus);
+}
+
+function scoreByContribution(
+  evidence: EvidenceItem[],
+  contribution: MetricContribution,
+) {
+  return aggregateVolumeWeighted(
+    evidence
+      .filter((item) => item.included && item.metricContribution === contribution)
+      .map((item) => item.signalStrength),
+  );
+}
+
+export function createQueryDerivedEvidence(
+  idea: IdeaBrief,
+  bundle: QueryBundle,
+): EvidenceItem[] {
+  const problem = primary(bundle.problemKeywords, idea.problem);
+  const solution = primary(bundle.solutionKeywords, idea.name);
+  const audience = primary(bundle.audienceKeywords, idea.targetUser);
+  const competitor = primary(bundle.competitorKeywords, `${idea.name} alternative`);
+  const exclusion = primary(bundle.exclusions, "wrong meaning");
+  const specificity =
+    bundle.problemKeywords.length +
+    bundle.solutionKeywords.length +
+    bundle.audienceKeywords.length +
+    bundle.competitorKeywords.length;
+  const audienceBonus = bundle.audienceKeywords.length > 0 ? 8 : 0;
+  const exclusionBonus = bundle.exclusions.length > 0 ? 6 : 0;
+  const drafts: EvidenceDraft[] = [
+    {
+      source: "Reddit",
+      sourceType: "post",
+      query: problem,
+      snippet: `Reddit public-search target for "${problem}" and "${audience}".`,
+      link: searchUrl("https://www.reddit.com/search/?q=", `${problem} ${audience}`),
+      metricContribution: "Demand",
+      reason: "Generated from the locked problem and audience terms.",
+      signalStrength: sourceTermScore(bundle.problemKeywords.length, audienceBonus),
+    },
+    {
+      source: "YouTube",
+      sourceType: "video",
+      query: solution,
+      snippet: `YouTube public-search target for "${solution}" tutorials, reviews, and workflows.`,
+      link: searchUrl("https://www.youtube.com/results?search_query=", solution),
+      metricContribution: "Demand",
+      reason: "Generated from the locked solution terms.",
+      signalStrength: sourceTermScore(bundle.solutionKeywords.length, 4),
+    },
+    {
+      source: "Hacker News",
+      sourceType: "comment",
+      query: `${problem} workaround`,
+      snippet: `Hacker News search target for workaround language around "${problem}".`,
+      link: searchUrl("https://hn.algolia.com/?q=", `${problem} workaround`),
+      metricContribution: "Pain",
+      reason: "Uses problem terms plus pain/workaround phrasing.",
+      signalStrength: sourceTermScore(bundle.problemKeywords.length, 14),
+    },
+    {
+      source: "Product Hunt",
+      sourceType: "launch",
+      query: competitor,
+      snippet: `Product Hunt search target for comparable launches: "${competitor}".`,
+      link: searchUrl("https://www.producthunt.com/search?q=", competitor),
+      metricContribution: "Competition Fit",
+      reason: "Generated from locked competitor terms.",
+      signalStrength: sourceTermScore(bundle.competitorKeywords.length, 10),
+    },
+    {
+      source: "GitHub",
+      sourceType: "repo",
+      query: solution,
+      snippet: `GitHub public-search target for repositories matching "${solution}".`,
+      link: searchUrl("https://github.com/search?q=", solution),
+      metricContribution: "Activity",
+      reason: "Generated from locked solution terms as a free-source activity target.",
+      signalStrength: sourceTermScore(bundle.solutionKeywords.length, 0),
+    },
+    {
+      source: "Stack Exchange",
+      sourceType: "question",
+      query: audience,
+      snippet: `Stack Exchange search target for questions from or about "${audience}".`,
+      link: searchUrl("https://stackexchange.com/search?q=", audience),
+      metricContribution: "Channel Fit",
+      reason: "Generated from locked audience terms.",
+      signalStrength: sourceTermScore(bundle.audienceKeywords.length, 12),
+    },
+    {
+      source: "npm",
+      sourceType: "package",
+      query: solution,
+      snippet: `npm package-search target for builder activity around "${solution}".`,
+      link: searchUrl("https://www.npmjs.com/search?q=", solution),
+      metricContribution: "Momentum",
+      reason: "Generated from locked solution terms and free package-search surface.",
+      signalStrength: sourceTermScore(specificity, 2),
+    },
+    {
+      source: "Hacker News",
+      sourceType: "post",
+      query: `${problem} ${solution}`,
+      snippet: `Cross-source precision check for "${problem}" plus "${solution}".`,
+      link: searchUrl("https://hn.algolia.com/?q=", `${problem} ${solution}`),
+      metricContribution: "Evidence Quality",
+      reason: "Higher when the query bundle has audience and exclusion controls.",
+      signalStrength: sourceTermScore(specificity, audienceBonus + exclusionBonus),
+    },
+  ];
+
+  const evidence = drafts.map<EvidenceItem>((draft, index) => ({
+    id: `query-derived-${index + 1}`,
+    date: generatedDate,
+    included: true,
+    duplicateCluster: `query-derived-${draft.metricContribution.toLowerCase().replaceAll(" ", "-")}`,
+    ...draft,
+  }));
+
+  if (bundle.exclusions.length > 0) {
+    evidence.push({
+      id: "query-derived-exclusion-control",
+      source: "Reddit",
+      sourceType: "post",
+      date: generatedDate,
+      query: exclusion,
+      snippet: `Wrong-meaning control query for excluded term "${exclusion}".`,
+      link: searchUrl("https://www.reddit.com/search/?q=", exclusion),
+      metricContribution: "Excluded",
+      included: false,
+      reason: "Excluded by the locked query bundle before scoring.",
+      duplicateCluster: "query-derived-exclusion-control",
+      signalStrength: 0,
+    });
+  }
+
+  return evidence;
+}
+
+export function derivePillarScoresFromEvidence(evidence: EvidenceItem[]): PillarScores {
+  return {
+    demand: scoreByContribution(evidence, "Demand"),
+    pain: scoreByContribution(evidence, "Pain"),
+    momentum: scoreByContribution(evidence, "Momentum"),
+    competitionFit: clamp(100 - scoreByContribution(evidence, "Competition Fit")),
+    activity: scoreByContribution(evidence, "Activity"),
+    channelFit: scoreByContribution(evidence, "Channel Fit"),
+    evidenceQuality: scoreByContribution(evidence, "Evidence Quality"),
+  };
+}
+
+export function deriveUncertainty(bundle: QueryBundle) {
+  let uncertainty = 24;
+
+  if (bundle.problemKeywords.length > 0) {
+    uncertainty -= 3;
+  }
+
+  if (bundle.solutionKeywords.length > 0) {
+    uncertainty -= 3;
+  }
+
+  if (bundle.audienceKeywords.length > 0) {
+    uncertainty -= 4;
+  }
+
+  if (bundle.competitorKeywords.length > 0) {
+    uncertainty -= 2;
+  }
+
+  if (bundle.exclusions.length > 0) {
+    uncertainty -= 3;
+  }
+
+  return Math.max(7, uncertainty);
+}

package/src/services/reportBuilder.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { createLockedQueryBundle } from "../domain/queryBundle";
+import { buildCompassReport } from "./reportBuilder";
+import { therapyEvidenceSeed, therapyPillarScores } from "./therapySeed";
+
+describe("report builder service", () => {
+  it("builds a report from supplied idea and locked query bundle", () => {
+    const report = buildCompassReport({
+      idea: {
+        name: "Invoice follow-up autopilot",
+        problem: "Freelancers lose time chasing late client payments.",
+        targetUser: "Freelancers and consultants",
+        lens: "Productivity / Prosumer SaaS",
+      },
+      queryBundle: createLockedQueryBundle({
+        problemKeywords: "late client payments",
+        solutionKeywords: "invoice reminder automation",
+        audienceKeywords: "freelancers, consultants",
+        competitorKeywords: "HoneyBook alternative",
+        exclusions: "medical billing",
+      }),
+      evidence: therapyEvidenceSeed,
+      pillarScores: therapyPillarScores,
+      uncertainty: 11,
+    });
+
+    expect(report.idea.name).toBe("Invoice follow-up autopilot");
+    expect(report.queryBundle.problemKeywords).toEqual(["late client payments"]);
+    expect(report.summary.score).toBe(66);
+    expect(report.summary.range).toEqual({ lower: 55, upper: 77 });
+    expect(report.methodologyVersion).toBe("0.1");
+  });
+
+  it("filters evidence through bundle exclusions and derives integrity", () => {
+    const report = buildCompassReport({
+      idea: {
+        name: "Therapy notes",
+        problem: "Therapists need note help.",
+        targetUser: "Solo therapists",
+        lens: "B2B Workflow / Vertical SaaS",
+      },
+      queryBundle: createLockedQueryBundle({
+        problemKeywords: "therapist paperwork, SOAP notes",
+        solutionKeywords: "session note automation",
+        audienceKeywords: "solo therapists",
+        competitorKeywords: "therapy notes app",
+        exclusions: "physical therapy",
+      }),
+      evidence: therapyEvidenceSeed,
+      pillarScores: therapyPillarScores,
+      uncertainty: 11,
+    });
+
+    expect(report.evidence).toHaveLength(12);
+    expect(report.evidence.find((item) => item.id === "physical-therapy-notes")).toMatchObject({
+      included: false,
+      metricContribution: "Excluded",
+    });
+    expect(report.integrity.finalScoreAvailable).toBe(true);
+    expect(report.integrity.warnings).toEqual([]);
+  });
+
+  it("includes formula readouts for all seven pillars", () => {
+    const report = buildCompassReport({
+      idea: {
+        name: "Therapy notes",
+        problem: "Therapists need note help.",
+        targetUser: "Solo therapists",
+        lens: "B2B Workflow / Vertical SaaS",
+      },
+      queryBundle: createLockedQueryBundle({
+        problemKeywords: "therapist paperwork, SOAP notes",
+        solutionKeywords: "session note automation",
+        audienceKeywords: "solo therapists",
+        competitorKeywords: "therapy notes app",
+        exclusions: "physical therapy",
+      }),
+      evidence: therapyEvidenceSeed,
+      pillarScores: therapyPillarScores,
+      uncertainty: 11,
+    });
+
+    expect(report.formulas).toHaveLength(7);
+    expect(report.formulas[0]).toMatchObject({
+      pillar: "Demand",
+      formula: "0.45 volume + 0.25 unique authors + 0.20 questions + 0.10 engagement",
+      score: 64,
+    });
+  });
+});