qa-boot 0.1.0

package/dist/providers/qaradar-provider.js

@@ -0,0 +1,30 @@
+import { spawnSync } from "node:child_process";
+import { parseQaradar } from "./qaradar-parse.js";
+import { qaradarEnabled } from "../config/config.js";
+function which() {
+    const probe = spawnSync("qaradar", ["--version"], { encoding: "utf8" });
+    return probe.status === 0;
+}
+export const qaradarProvider = {
+    name: "qaradar",
+    async isAvailable(ctx) {
+        if (qaradarEnabled(ctx.config) === "false")
+            return false;
+        return which();
+    },
+    async collect(ctx) {
+        const { days, top } = ctx.config.evidence_providers.qaradar;
+        const run = spawnSync("qaradar", ["analyze", ctx.repoPath, "--json-output", "--days", String(days), "--top", String(top)], { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+        if (run.status !== 0 || !run.stdout) {
+            return [];
+        }
+        let report;
+        try {
+            report = JSON.parse(run.stdout);
+        }
+        catch {
+            return [];
+        }
+        return parseQaradar(report);
+    },
+};

package/dist/scanners/agent-config-scanner.js

@@ -0,0 +1,23 @@
+const MARKERS = [
+    ["CLAUDE.md", "CLAUDE.md"],
+    ["AGENTS.md", "AGENTS.md"],
+    [".claude/**", ".claude"],
+    [".cursor/**", ".cursor"],
+    [".cursorrules", ".cursorrules"],
+];
+export function scanAgentConfig(ctx) {
+    const ev = [];
+    const seen = new Set();
+    for (const [glob, name] of MARKERS) {
+        const hits = ctx.match(glob);
+        if (hits.length && !seen.has(name)) {
+            seen.add(name);
+            ev.push({ kind: "agent-config", path: hits[0], detail: { name } });
+        }
+    }
+    if (ctx.has(".claude/skills/**"))
+        ev.push({ kind: "agent-skills", path: ".claude/skills" });
+    if (ctx.has(".claude/**/*mcp*"))
+        ev.push({ kind: "agent-mcp", path: ".claude" });
+    return ev;
+}

package/dist/scanners/build-scanner.js

@@ -0,0 +1,27 @@
+const SCRIPT_KINDS = ["build", "start", "test", "package"];
+export function scanBuild(ctx) {
+    const ev = [];
+    const pkg = ctx.readJson("package.json");
+    for (const name of SCRIPT_KINDS) {
+        const cmd = pkg?.scripts?.[name];
+        if (cmd)
+            ev.push({ kind: "build-command", path: "package.json", detail: { name, cmd } });
+    }
+    if (ctx.has("Makefile"))
+        ev.push({ kind: "build-file", path: "Makefile", detail: { name: "make" } });
+    if (ctx.has("Dockerfile"))
+        ev.push({ kind: "build-file", path: "Dockerfile", detail: { name: "docker" } });
+    for (const f of ctx.match("docker-compose*.{yml,yaml}")) {
+        ev.push({ kind: "build-file", path: f, detail: { name: "docker-compose" } });
+    }
+    if (ctx.has("fastlane/**") || ctx.has("Fastfile")) {
+        ev.push({ kind: "build-file", path: "fastlane", detail: { name: "fastlane" } });
+    }
+    if (ctx.has("build.gradle") || ctx.has("build.gradle.kts") || ctx.has("gradlew") || ctx.has("settings.gradle") || ctx.has("settings.gradle.kts")) {
+        ev.push({ kind: "build-file", path: "build.gradle", detail: { name: "gradle" } });
+    }
+    if (ctx.has("pom.xml") || ctx.has("mvnw")) {
+        ev.push({ kind: "build-file", path: "pom.xml", detail: { name: "maven" } });
+    }
+    return ev;
+}

package/dist/scanners/ci-scanner.js

@@ -0,0 +1,51 @@
+import { parse as parseYaml } from "yaml";
+const CI_SYSTEMS = [
+    [".github/workflows/*.yml", "github-actions"],
+    [".github/workflows/*.yaml", "github-actions"],
+    [".gitlab-ci.yml", "gitlab-ci"],
+    ["Jenkinsfile", "jenkins"],
+    [".circleci/config.yml", "circleci"],
+    [".buildkite/**", "buildkite"],
+    ["bitbucket-pipelines.yml", "bitbucket-pipelines"],
+];
+const JOB_HINTS = [
+    [/test|spec|lint|check/i, "test"],
+    [/build|compile|package/i, "build"],
+    [/deploy|release|publish/i, "deploy"],
+];
+function classifyJobName(name) {
+    for (const [re, kind] of JOB_HINTS)
+        if (re.test(name))
+            return kind;
+    return null;
+}
+export function scanCi(ctx) {
+    const ev = [];
+    const systems = new Set();
+    for (const [glob, name] of CI_SYSTEMS) {
+        const hits = ctx.match(glob);
+        if (hits.length && !systems.has(name)) {
+            systems.add(name);
+            ev.push({ kind: "ci-system", path: hits[0], detail: { name } });
+        }
+    }
+    for (const wf of ctx.match(".github/workflows/*.{yml,yaml}")) {
+        const text = ctx.read(wf);
+        if (!text)
+            continue;
+        let doc;
+        try {
+            doc = parseYaml(text);
+        }
+        catch {
+            continue;
+        }
+        const jobs = doc?.jobs;
+        for (const jobName of Object.keys(jobs ?? {})) {
+            const kind = classifyJobName(jobName);
+            if (kind)
+                ev.push({ kind: "ci-job", path: wf, detail: { name: jobName, kind } });
+        }
+    }
+    return ev;
+}

package/dist/scanners/docs-scanner.js

@@ -0,0 +1,24 @@
+const DOC_MARKERS = [
+    ["README*", "readme"],
+    ["CONTRIBUTING*", "contributing"],
+    ["docs/**", "docs-dir"],
+    ["CODEOWNERS", "codeowners"],
+    [".github/CODEOWNERS", "codeowners"],
+    [".github/PULL_REQUEST_TEMPLATE*", "pr-template"],
+    [".github/ISSUE_TEMPLATE/**", "issue-template"],
+    ["CHANGELOG*", "changelog"],
+    ["docs/decisions/**", "adr"],
+    ["docs/adr/**", "adr"],
+];
+export function scanDocs(ctx) {
+    const ev = [];
+    const seen = new Set();
+    for (const [glob, kind] of DOC_MARKERS) {
+        const hits = ctx.match(glob);
+        if (hits.length && !seen.has(kind)) {
+            seen.add(kind);
+            ev.push({ kind: "doc", path: hits[0], detail: { kind } });
+        }
+    }
+    return ev;
+}

package/dist/scanners/raw-evidence.js

@@ -0,0 +1 @@
+export {};

package/dist/scanners/repo-scanner.js

@@ -0,0 +1,41 @@
+export function scanRepo(ctx) {
+    const ev = [];
+    const langMarkers = [
+        ["package.json", "language:javascript/typescript", "npm"],
+        ["pyproject.toml", "python", "pip"],
+        ["go.mod", "go", "go"],
+        ["pom.xml", "java", "maven"],
+        ["build.gradle", "java/kotlin", "gradle"],
+        ["build.gradle.kts", "java/kotlin", "gradle"],
+        ["Cargo.toml", "rust", "cargo"],
+        ["Gemfile", "ruby", "bundler"],
+    ];
+    for (const [file, lang, pm] of langMarkers) {
+        if (ctx.has(file)) {
+            const name = lang.startsWith("language:") ? lang.slice("language:".length) : lang;
+            ev.push({ kind: "language", path: file, detail: { name } });
+            ev.push({ kind: "package-manager", path: file, detail: { name: pm } });
+        }
+    }
+    const pkg = ctx.readJson("package.json");
+    if (pkg) {
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        for (const [name] of Object.entries(deps)) {
+            ev.push({ kind: "dependency", path: "package.json", detail: { name } });
+        }
+        for (const [script, cmd] of Object.entries(pkg.scripts ?? {})) {
+            ev.push({ kind: "npm-script", path: "package.json", detail: { name: script, cmd } });
+        }
+    }
+    if (ctx.has("Dockerfile"))
+        ev.push({ kind: "dockerfile", path: "Dockerfile" });
+    if (ctx.has("Makefile"))
+        ev.push({ kind: "makefile", path: "Makefile" });
+    for (const marker of ["pnpm-workspace.yaml", "lerna.json", "nx.json"]) {
+        if (ctx.has(marker))
+            ev.push({ kind: "monorepo", path: marker, detail: { name: marker } });
+    }
+    for (const r of ctx.match("README*"))
+        ev.push({ kind: "readme", path: r });
+    return ev;
+}

package/dist/scanners/test-scanner.js

@@ -0,0 +1,85 @@
+const FRAMEWORK_CONFIGS = [
+    ["playwright.config.*", "playwright"],
+    ["cypress.config.*", "cypress"],
+    ["jest.config.*", "jest"],
+    ["vitest.config.*", "vitest"],
+    ["pytest.ini", "pytest"],
+    ["tox.ini", "pytest"],
+];
+const DEP_FRAMEWORKS = [
+    ["@playwright/test", "playwright"],
+    ["cypress", "cypress"],
+    ["jest", "jest"],
+    ["vitest", "vitest"],
+    ["mocha", "mocha"],
+];
+const FRAMEWORK_KEYWORDS = [
+    ["junit", "junit"],
+    ["testng", "testng"],
+    ["rest-assured", "rest-assured"],
+    ["restassured", "rest-assured"],
+    ["selenium", "selenium"],
+    ["seleniumhq", "selenium"],
+    ["selenide", "selenide"],
+    ["cucumber", "cucumber"],
+    ["appium", "appium"],
+    ["espresso", "espresso"],
+    ["xcuitest", "xcuitest"],
+    ["k6", "k6"],
+    ["jmeter", "jmeter"],
+    ["gatling", "gatling"],
+];
+const BUILD_FILES = ["build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts", "pom.xml"];
+const TEST_DIRS = ["test/", "tests/", "__tests__/", "spec/", "e2e/", "src/test/"];
+const COVERAGE_MARKERS = [
+    ["**/coverage/**", "coverage-dir"],
+    ["**/.nyc_output/**", "nyc"],
+    ["**/jacoco*.xml", "jacoco"],
+];
+export function scanTests(ctx) {
+    const ev = [];
+    const seen = new Set();
+    for (const [glob, name] of FRAMEWORK_CONFIGS) {
+        if (ctx.has(glob) && !seen.has(name)) {
+            seen.add(name);
+            ev.push({ kind: "test-framework", path: glob, detail: { name, source: "config" } });
+        }
+    }
+    const pkg = ctx.readJson("package.json");
+    if (pkg) {
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        for (const [dep, name] of DEP_FRAMEWORKS) {
+            if (deps[dep] && !seen.has(name)) {
+                seen.add(name);
+                ev.push({ kind: "test-framework", path: "package.json", detail: { name, source: "dependency" } });
+            }
+        }
+    }
+    const pyproject = ctx.read("pyproject.toml");
+    if (pyproject && /\[tool\.pytest/.test(pyproject) && !seen.has("pytest")) {
+        seen.add("pytest");
+        ev.push({ kind: "test-framework", path: "pyproject.toml", detail: { name: "pytest", source: "config" } });
+    }
+    for (const buildFile of BUILD_FILES) {
+        const text = ctx.read(buildFile);
+        if (!text)
+            continue;
+        const lower = text.toLowerCase();
+        for (const [keyword, name] of FRAMEWORK_KEYWORDS) {
+            if (lower.includes(keyword) && !seen.has(name)) {
+                seen.add(name);
+                ev.push({ kind: "test-framework", path: buildFile, detail: { name, source: "build-file" } });
+            }
+        }
+    }
+    for (const dir of TEST_DIRS) {
+        if (ctx.has(`${dir}**`) || ctx.has(dir)) {
+            ev.push({ kind: "test-dir", path: dir });
+        }
+    }
+    for (const [glob, name] of COVERAGE_MARKERS) {
+        if (ctx.has(glob))
+            ev.push({ kind: "coverage-tool", detail: { name } });
+    }
+    return ev;
+}

package/dist/tell/interview-log.js

@@ -0,0 +1,22 @@
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+const HEADER = "# QA Interview Log\n\nAppend-only record of human-told QA knowledge. Written by `qa-boot tell`; do not hand-edit.\n";
+export function formatLogEntry(e) {
+    const lines = ["", `## ${e.date} — ${e.by}`];
+    if (e.unknownId && e.question) {
+        lines.push(`**Q (${e.unknownId}):** ${e.question}`, `**A:** ${e.statement}`);
+    }
+    else {
+        lines.push(`**Told (${e.domain}):** ${e.statement}`);
+    }
+    lines.push(`→ fact \`${e.factId}\` (scope: ${e.scope})`, "");
+    return lines.join("\n");
+}
+export function appendInterviewLog(repoPath, entry) {
+    const path = join(repoPath, "qa-context", "qa-interview-log.md");
+    mkdirSync(dirname(path), { recursive: true });
+    if (!existsSync(path))
+        writeFileSync(path, HEADER, "utf8");
+    appendFileSync(path, formatLogEntry(entry), "utf8");
+    return path;
+}

package/dist/tell/tell.js

@@ -0,0 +1,77 @@
+import { makeFact } from "../core/fact.js";
+import { slug } from "../core/slug.js";
+import { knownUnknownIds, unknownSpec } from "../unknowns/unknowns.js";
+export const TELLABLE_DOMAINS = [
+    "build",
+    "release",
+    "environment",
+    "test_data",
+    "ownership",
+    "business_priority",
+    "agent_permissions",
+    "test_trust",
+    "knowledge_sources",
+];
+export class TellError extends Error {
+}
+export function applyTell(store, input, today) {
+    if (!input.by?.trim())
+        throw new TellError("Missing --by <who>. Told facts must record who said them.");
+    if (!input.statement?.trim())
+        throw new TellError("Missing statement text.");
+    if (input.unknownId)
+        return answerMode(store, input, today);
+    if (input.domain)
+        return freeformMode(store, input, today);
+    throw new TellError(`Provide an unknown id to answer, or --domain for free-form knowledge.\nKnown unknown ids:\n  ${knownUnknownIds().join("\n  ")}`);
+}
+function answerMode(store, input, today) {
+    const spec = unknownSpec(input.unknownId);
+    if (!spec) {
+        throw new TellError(`Unknown id "${input.unknownId}" is not one of qa-boot's unknowns. Valid ids:\n  ${knownUnknownIds().join("\n  ")}`);
+    }
+    const fact = buildToldFact({ factId: `${spec.id}.answer`, domain: spec.domain, input, answersUnknown: spec.id }, today);
+    const removedUnknown = store.remove(spec.id);
+    store.upsert([fact]);
+    return { fact, question: spec.question, removedUnknown, remainingUnknowns: countOpenUnknowns(store) };
+}
+function freeformMode(store, input, today) {
+    const domain = input.domain;
+    if (!TELLABLE_DOMAINS.includes(domain)) {
+        throw new TellError(`Domain "${domain}" is not tellable. Valid domains: ${TELLABLE_DOMAINS.join(", ")}`);
+    }
+    const s = input.idSlug ? slug(input.idSlug) : slug(input.statement);
+    if (!s)
+        throw new TellError("Could not derive an id from the statement; pass --id <slug>.");
+    const factId = `${domain}.${s}`;
+    if (unknownSpec(factId)) {
+        throw new TellError(`Fact id "${factId}" collides with a known unknown. To answer that question run \`qa-boot tell ${factId} "..." --by <who>\`; otherwise pass --id <slug> to pick a different id.`);
+    }
+    const existing = store.byId(factId);
+    if (existing && existing.provenance !== "told") {
+        throw new TellError(`Fact id "${factId}" already exists with provenance "${existing.provenance}". Pass --id <slug> to pick a different id.`);
+    }
+    const fact = buildToldFact({ factId, domain, input }, today);
+    store.upsert([fact]);
+    return { fact, removedUnknown: false, remainingUnknowns: countOpenUnknowns(store) };
+}
+function buildToldFact(args, today) {
+    return makeFact({
+        id: args.factId,
+        domain: args.domain,
+        statement: args.input.statement.trim(),
+        provenance: "told",
+        confidence: 0.9,
+        evidence_provider: "human-interview",
+        evidence: [`qa-interview-log.md ${today}`],
+        limitations: ["Human-stated knowledge; may go stale. Re-confirm when expired."],
+        expires_after_days: 180,
+        told_by: args.input.by.trim(),
+        scope: "repo",
+        ...(args.input.source ? { source: args.input.source } : {}),
+        ...(args.answersUnknown ? { answers_unknown: args.answersUnknown } : {}),
+    }, today);
+}
+function countOpenUnknowns(store) {
+    return store.all().filter((f) => f.provenance === "unknown").length;
+}

package/dist/unknowns/unknowns.js

@@ -0,0 +1,101 @@
+import { makeFact } from "../core/fact.js";
+const PROVIDER = "unknowns-generator";
+const SPECS = [
+    {
+        id: "build.qa-build-process",
+        domain: "build",
+        statement: "The QA build / artifact generation process was not found.",
+        question: "Who or what system produces QA builds, where are artifacts stored, and who owns that workflow?",
+        risk_if_wrong: "The agent may invent wrong build instructions or point QA at the wrong artifact.",
+    },
+    {
+        id: "release.blocking-gates",
+        domain: "release",
+        statement: "It is unclear which checks block a release.",
+        question: "Which CI checks or approvals actually block a release, and who can override them?",
+        risk_if_wrong: "The agent may claim a change is releasable when a real gate is unmet.",
+    },
+    {
+        id: "environment.list",
+        domain: "environment",
+        statement: "Which environments exist and which is stable is unknown.",
+        question: "What test environments exist (dev/staging/prod), which is stable, and how is test data reset?",
+        risk_if_wrong: "The agent may direct QA to test on an unstable or wrong environment.",
+    },
+    {
+        id: "test_data.reset-process",
+        domain: "test_data",
+        statement: "The test data setup/reset process is unknown.",
+        question: "How is test data created and reset, and are there fixtures or seed scripts?",
+        risk_if_wrong: "The agent may assume a clean dataset that does not exist.",
+    },
+    {
+        id: "ownership.approvers",
+        domain: "ownership",
+        statement: "Who approves risky changes is unknown.",
+        question: "Who owns and approves risky changes in this repo?",
+        risk_if_wrong: "The agent may route review to the wrong people or skip required approval.",
+        suppressIfPrefix: ["knowledge_sources.codeowners"],
+    },
+    {
+        id: "business_priority.critical-areas",
+        domain: "business_priority",
+        statement: "Business criticality of repo areas is unknown.",
+        question: "Which areas of this repo are business-critical or customer-facing?",
+        risk_if_wrong: "The agent may treat technical risk as business priority.",
+    },
+    {
+        id: "agent_permissions.boundaries",
+        domain: "agent_permissions",
+        statement: "What an AI agent is permitted to do here is unknown.",
+        question: "What is an AI agent allowed to do in this repo (comment on PRs, trigger CI, open PRs)?",
+        risk_if_wrong: "The agent may take an action it is not authorized to take.",
+    },
+    {
+        id: "test_trust.confidence",
+        domain: "test_trust",
+        statement: "Whether the team trusts the existing tests is unknown.",
+        question: "Do you trust the current test suite, and are failures treated as real?",
+        risk_if_wrong: "The agent may over-trust a flaky or ignored suite.",
+    },
+    {
+        id: "repo_quality.risk-analysis",
+        domain: "repo_quality",
+        statement: "Deterministic repo-risk analysis (QA Radar) was not available, so technical risk hotspots are unknown.",
+        question: "Is QA Radar (or similar churn/coverage risk analysis) available to run on this repo?",
+        risk_if_wrong: "The agent may give generic 'what to test first' advice without knowing where technical risk concentrates.",
+        suppressIfPrefix: ["repo_quality.high-churn-untested"],
+    },
+];
+export function knownUnknownIds() {
+    return SPECS.map((s) => s.id);
+}
+export function unknownSpec(id) {
+    const s = SPECS.find((x) => x.id === id);
+    return s ? { id: s.id, domain: s.domain, question: s.question } : undefined;
+}
+export function deriveUnknownFacts(facts, today) {
+    const ids = facts.map((f) => f.id);
+    const answered = new Set(facts.filter((f) => f.provenance === "told" && f.answers_unknown && !f.stale).map((f) => f.answers_unknown));
+    const out = [];
+    for (const spec of SPECS) {
+        if (answered.has(spec.id))
+            continue;
+        const suppressed = (spec.suppressIfPrefix ?? []).some((p) => ids.some((id) => id.startsWith(p)));
+        if (suppressed)
+            continue;
+        out.push(makeFact({
+            id: spec.id,
+            domain: spec.domain,
+            statement: spec.statement,
+            provenance: "unknown",
+            confidence: 0,
+            evidence_provider: PROVIDER,
+            evidence: [],
+            value: { question: spec.question },
+            risk_if_wrong: spec.risk_if_wrong,
+            needs_human_confirmation: true,
+        }, today));
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "qa-boot",
+  "version": "0.1.0",
+  "description": "Bootstrap QA context for AI coding agents.",
+  "keywords": ["qa", "testing", "claude-code", "ai-agents", "onboarding", "qa-context", "cli"],
+  "author": "Murat Kus",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MuratKus/qa-boot.git"
+  },
+  "homepage": "https://github.com/MuratKus/qa-boot#readme",
+  "bugs": {
+    "url": "https://github.com/MuratKus/qa-boot/issues"
+  },
+  "type": "module",
+  "bin": {
+    "qa-boot": "dist/cli/index.js"
+  },
+  "files": ["dist"],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build && npm run typecheck && npm test"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "fast-glob": "^3.3.2",
+    "minimatch": "^9.0.9",
+    "yaml": "^2.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}