@ivorycanvas/qamap 0.3.0

package/dist/verify.d.ts

@@ -0,0 +1,27 @@
+import type { EvalOptions, EvalResult } from "./eval.js";
+import type { VerificationManifestMatch } from "./manifest.js";
+import type { ReviewResult } from "./review.js";
+import type { ScanOptions } from "./types.js";
+export interface VerifyOptions extends EvalOptions {
+    scanOptions?: ScanOptions;
+    manifestPath?: string;
+}
+export interface VerifyResult {
+    tool: {
+        name: string;
+        version: string;
+    };
+    root: string;
+    workspaceRoot?: string;
+    generatedAt: string;
+    base: string;
+    head: string;
+    review: ReviewResult;
+    evaluation: EvalResult;
+    verificationManifestPath?: string;
+    verificationManifestMatches: VerificationManifestMatch[];
+    recommendations: string[];
+}
+export declare function verifyChange(rootInput: string, options?: VerifyOptions): Promise<VerifyResult>;
+export declare function formatVerifyReport(result: VerifyResult): string;
+export declare function formatMarkdownVerifyReport(result: VerifyResult): string;

package/dist/verify.js

@@ -0,0 +1,244 @@
+import { evaluateChangeReadiness } from "./eval.js";
+import { changedFilesRelativeToManifestRoot, loadVerificationManifest, matchVerificationManifest, } from "./manifest.js";
+import { reviewProject } from "./review.js";
+import { TOOL_NAME, VERSION } from "./version.js";
+export async function verifyChange(rootInput, options = {}) {
+    const scanOptions = options.workspaceRoot
+        ? { ...options.scanOptions, workspaceRoot: options.workspaceRoot }
+        : options.scanOptions;
+    const review = await reviewProject(rootInput, {
+        base: options.base,
+        head: options.head,
+        scanOptions,
+    });
+    const evaluation = await evaluateChangeReadiness(rootInput, {
+        base: options.base,
+        head: options.head,
+        workspaceRoot: options.workspaceRoot ?? scanOptions?.workspaceRoot,
+        includeWorkingTree: options.includeWorkingTree,
+        prBody: options.prBody,
+        prBodyFile: options.prBodyFile,
+        validationCommands: options.validationCommands,
+    });
+    const manifestRoot = evaluation.workspaceRoot ?? evaluation.root;
+    const verificationManifest = await loadVerificationManifest(manifestRoot, { manifestPath: options.manifestPath });
+    const manifestChangedFiles = changedFilesRelativeToManifestRoot(evaluation.changedFiles, evaluation.root, manifestRoot);
+    const verificationManifestMatches = matchVerificationManifest(verificationManifest, manifestChangedFiles);
+    return {
+        tool: {
+            name: TOOL_NAME,
+            version: VERSION,
+        },
+        root: evaluation.root,
+        workspaceRoot: evaluation.workspaceRoot,
+        generatedAt: new Date().toISOString(),
+        base: evaluation.base,
+        head: evaluation.head,
+        review,
+        evaluation,
+        verificationManifestPath: verificationManifest.path,
+        verificationManifestMatches,
+        recommendations: buildRecommendations(review, evaluation),
+    };
+}
+export function formatVerifyReport(result) {
+    const lines = [];
+    lines.push(`${result.tool.name} Verify`);
+    lines.push(`Root: ${result.root}`);
+    if (result.workspaceRoot) {
+        lines.push(`Workspace root: ${result.workspaceRoot}`);
+    }
+    lines.push(`Base: ${result.base}`);
+    lines.push(`Head: ${result.head}`);
+    lines.push(`Readiness: ${result.evaluation.score}/${result.evaluation.maxScore} (${result.evaluation.rating})`);
+    lines.push(`Changed files: ${result.evaluation.changedFiles.length}`);
+    lines.push(`New findings: ${result.review.newFindings.length}`);
+    lines.push(`Changed risky files: ${result.review.changedRiskyFindings.length}`);
+    if (result.verificationManifestPath) {
+        lines.push(`Verification manifest: ${result.verificationManifestPath}`);
+        lines.push(`Manifest recommendations: ${result.verificationManifestMatches.length}`);
+    }
+    lines.push("");
+    lines.push("Verification gates:");
+    for (const check of result.evaluation.checks) {
+        lines.push(`- ${check.status.toUpperCase()} ${check.title}: ${check.score}/${check.maxScore} - ${check.reason}`);
+    }
+    if (result.evaluation.testPlanItems.length > 0) {
+        lines.push("");
+        lines.push("Suggested domain tests:");
+        for (const item of result.evaluation.testPlanItems) {
+            lines.push(`- ${item.title}: ${item.checks[0]}`);
+        }
+    }
+    if (result.verificationManifestMatches.length > 0) {
+        lines.push("");
+        lines.push("Manifest recommendations:");
+        for (const match of result.verificationManifestMatches.slice(0, 8)) {
+            lines.push(`- ${match.name}: ${match.reason}`);
+            if (match.evidenceSources.length > 0) {
+                lines.push(`  Evidence sources: ${match.evidenceSources.join(", ")}`);
+            }
+            lines.push(`  Evidence: ${match.manifestPath}`);
+            lines.push(`  If wrong: update ${match.updatePath}`);
+            if (match.nextActions.length > 0) {
+                lines.push("  Next actions:");
+                for (const action of match.nextActions.slice(0, 4)) {
+                    lines.push(`  - ${action}`);
+                }
+            }
+            if (match.repairHints.length > 0) {
+                lines.push("  Repair hints:");
+                for (const hint of match.repairHints.slice(0, 4)) {
+                    lines.push(`  - ${hint}`);
+                }
+            }
+        }
+    }
+    if (result.evaluation.suggestedCommands.length > 0) {
+        lines.push("");
+        lines.push("Suggested commands:");
+        for (const command of result.evaluation.suggestedCommands) {
+            lines.push(`- ${command}`);
+        }
+    }
+    if (result.recommendations.length > 0) {
+        lines.push("");
+        lines.push("Next actions:");
+        for (const recommendation of result.recommendations) {
+            lines.push(`- ${recommendation}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function formatMarkdownVerifyReport(result) {
+    const lines = [];
+    lines.push("# QAMap Verify");
+    lines.push("");
+    lines.push(`- Root: \`${escapeMarkdownInline(result.root)}\``);
+    if (result.workspaceRoot) {
+        lines.push(`- Workspace root: \`${escapeMarkdownInline(result.workspaceRoot)}\``);
+    }
+    lines.push(`- Base: \`${escapeMarkdownInline(result.base)}\``);
+    lines.push(`- Head: \`${escapeMarkdownInline(result.head)}\``);
+    if (result.evaluation.includeWorkingTree) {
+        lines.push("- Includes working tree changes: yes");
+    }
+    lines.push(`- Readiness: **${result.evaluation.score}/${result.evaluation.maxScore}** (${result.evaluation.rating})`);
+    lines.push(`- Changed files: ${result.evaluation.changedFiles.length}`);
+    lines.push(`- New findings: ${result.review.newFindings.length}`);
+    lines.push(`- Changed risky files: ${result.review.changedRiskyFindings.length}`);
+    if (result.verificationManifestPath) {
+        lines.push(`- Verification manifest: \`${escapeMarkdownInline(result.verificationManifestPath)}\``);
+        lines.push(`- Manifest recommendations: ${result.verificationManifestMatches.length}`);
+    }
+    lines.push("");
+    lines.push("## Verification Gates");
+    lines.push("");
+    lines.push("| Gate | Status | Score | Reason |");
+    lines.push("| --- | --- | ---: | --- |");
+    for (const check of result.evaluation.checks) {
+        lines.push(`| ${escapeMarkdownCell(check.title)} | ${check.status} | ${check.score}/${check.maxScore} | ${escapeMarkdownCell(check.reason)} |`);
+    }
+    lines.push("");
+    lines.push("## Review Findings");
+    lines.push("");
+    if (result.review.newFindings.length === 0 && result.review.changedRiskyFindings.length === 0) {
+        lines.push("No new QAMap findings or changed risky files were introduced by this branch.");
+    }
+    else {
+        for (const finding of [...result.review.newFindings, ...result.review.changedRiskyFindings].slice(0, 12)) {
+            const fileSuffix = finding.file ? ` (${escapeMarkdownInline(finding.file)})` : "";
+            lines.push(`- \`${finding.id}\` **${escapeMarkdownInline(finding.title)}**${fileSuffix}`);
+            lines.push(`  - ${escapeMarkdownInline(finding.message)}`);
+            lines.push(`  - Fix: ${escapeMarkdownInline(finding.recommendation)}`);
+        }
+    }
+    lines.push("");
+    if (result.evaluation.testPlanItems.length > 0) {
+        lines.push("## Suggested Domain Tests");
+        lines.push("");
+        for (const [index, item] of result.evaluation.testPlanItems.entries()) {
+            lines.push(`### ${index + 1}. ${escapeMarkdownInline(item.title)}`);
+            lines.push("");
+            lines.push(item.reason);
+            lines.push("");
+            lines.push("Checks:");
+            for (const check of item.checks) {
+                lines.push(`- ${escapeMarkdownInline(check)}`);
+            }
+            lines.push("");
+        }
+    }
+    if (result.verificationManifestMatches.length > 0) {
+        lines.push("## Manifest Recommendations");
+        lines.push("");
+        lines.push("These recommendations come from `.qamap/manifest.yaml`. If they are wrong, update the manifest path shown below so future PRs get better suggestions.");
+        lines.push("");
+        for (const match of result.verificationManifestMatches.slice(0, 8)) {
+            lines.push(`### ${escapeMarkdownInline(match.name)} \`${escapeMarkdownInline(match.id)}\``);
+            lines.push("");
+            lines.push(`- Kind: ${match.kind}`);
+            lines.push(`- Confidence: ${match.confidence}`);
+            lines.push(`- Why this was recommended: ${escapeMarkdownInline(match.reason)}`);
+            if (match.evidenceSources.length > 0) {
+                lines.push(`- Evidence sources: ${match.evidenceSources.map(escapeMarkdownInline).join(", ")}`);
+            }
+            lines.push(`- Manifest evidence: \`${escapeMarkdownInline(match.manifestPath)}\``);
+            lines.push(`- If this is wrong: update \`${escapeMarkdownInline(match.updatePath)}\``);
+            if (match.nextActions.length > 0) {
+                lines.push("- Next actions:");
+                for (const action of match.nextActions.slice(0, 4)) {
+                    lines.push(`  - ${escapeMarkdownInline(action)}`);
+                }
+            }
+            if (match.repairHints.length > 0) {
+                lines.push("- Repair hints:");
+                for (const hint of match.repairHints.slice(0, 4)) {
+                    lines.push(`  - ${escapeMarkdownInline(hint)}`);
+                }
+            }
+            if (match.matchedFiles.length > 0) {
+                lines.push("- Matched files:");
+                for (const file of match.matchedFiles.slice(0, 8)) {
+                    lines.push(`  - \`${escapeMarkdownInline(file)}\``);
+                }
+            }
+            lines.push("");
+        }
+    }
+    if (result.evaluation.suggestedCommands.length > 0) {
+        lines.push("## Suggested Commands");
+        lines.push("");
+        for (const command of result.evaluation.suggestedCommands) {
+            lines.push(`- \`${escapeMarkdownInline(command)}\``);
+        }
+        lines.push("");
+    }
+    if (result.recommendations.length > 0) {
+        lines.push("## Next Actions");
+        lines.push("");
+        for (const recommendation of result.recommendations) {
+            lines.push(`- ${escapeMarkdownInline(recommendation)}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function buildRecommendations(review, evaluation) {
+    return [
+        ...reviewRecommendations(review),
+        ...evaluation.recommendations,
+    ].filter((recommendation, index, recommendations) => recommendations.indexOf(recommendation) === index);
+}
+function reviewRecommendations(review) {
+    return [...review.newFindings, ...review.changedRiskyFindings]
+        .map((finding) => finding.recommendation)
+        .filter((recommendation, index, recommendations) => recommendations.indexOf(recommendation) === index);
+}
+function escapeMarkdownInline(value) {
+    return value.replaceAll("`", "'");
+}
+function escapeMarkdownCell(value) {
+    return escapeMarkdownInline(value).replaceAll("|", "\\|").replace(/\s+/g, " ").trim();
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const TOOL_NAME = "QAMap";
+export declare const VERSION = "0.3.0";

package/dist/version.js

@@ -0,0 +1,3 @@
+export const TOOL_NAME = "QAMap";
+export const VERSION = "0.3.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,SAAS,GAAG,OAAO,CAAC;AACjC,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/docs/adoption.md

@@ -0,0 +1,166 @@
+# Adopting QAMap
+
+QAMap works best when teams treat it as the local QA pass for AI-assisted PRs, not as a replacement for review or security tooling.
+
+## First Run
+
+Start with the PR QA draft on a changed branch — no manifest, no config:
+
+```sh
+pnpm dlx @ivorycanvas/qamap qa . --base origin/main --head HEAD
+```
+
+For coding agents, request the compact machine-readable summary instead:
+
+```sh
+pnpm dlx @ivorycanvas/qamap qa . --base origin/main --head HEAD --format agent
+```
+
+When the qa output looks useful, preview and then write the draft E2E files:
+
+```sh
+pnpm dlx @ivorycanvas/qamap e2e draft . --base origin/main --head HEAD --dry-run
+pnpm dlx @ivorycanvas/qamap e2e draft . --base origin/main --head HEAD
+```
+
+For a combined PR verification report with readiness gates, add `verify`:
+
+```sh
+pnpm dlx @ivorycanvas/qamap verify . --base origin/main --head HEAD --pr-body-file pr-body.md
+```
+
+When developing QAMap itself from source:
+
+```sh
+git clone https://github.com/IvoryCanvas/qamap.git
+cd qamap
+pnpm install
+pnpm build
+node dist/cli.js scan /path/to/repo
+```
+
+## Build A Verification Base
+
+QAMap works best when the repository becomes the source of truth for verification language, not when every PR starts with a fresh prompt to an external agent.
+
+Start with generated output, then promote only durable knowledge:
+
+- keep generated run history local with `qamap history init .` and `--record-history`
+- commit `.qamap/domains.yml` when the team agrees on product/domain names
+- commit `.qamap/flows.yml` when the team agrees a journey is important enough to protect repeatedly
+- keep draft E2E files reviewable until selectors, fixtures, assertions, and runner config make them real regression coverage
+
+This gives teams a small lifecycle: observe a branch, review the proposed language and flows, promote the stable parts, then let the next branch reuse that context without another LLM call.
+
+## Recommended Rollout
+
+Start advisory, then tighten the gate once the findings are understood.
+
+| Phase | Command | Goal |
+| --- | --- | --- |
+| 1. PR QA draft | `qamap qa . --base origin/main --head HEAD` | Get the affected flow, suggested E2E/checklist draft, missing evidence, and PR checklist for a branch. |
+| 2. Agent handoff | `qamap qa . --base origin/main --head HEAD --format agent` | Give coding agents the same decision content as compact JSON instead of a long report. |
+| 3. E2E preview | `qamap e2e draft . --base origin/main --head HEAD --dry-run` | Preview generated draft paths, readiness, action items, and blockers before writing files. |
+| 4. E2E apply | `qamap e2e draft . --base origin/main --head HEAD` | Write draft files once the preview looks useful enough to review. |
+| 5. QA memory | `qamap manifest init .` (from the default branch) | Create `.qamap/manifest.yaml` so future PR recommendations reuse reviewed team QA language. |
+| 6. Verify | `qamap verify . --base origin/main --head HEAD --pr-body-file pr-body.md` | Combine review findings, readiness score, suggested domain tests, and next actions. |
+| 7. PR Action | `uses: IvoryCanvas/qamap@main` | Add annotations, a step summary, a test plan, eval, and a sticky PR comment. |
+| 8. Guardrail baseline | `qamap scan .` | See repo-level AI agent risks (guardrails layer) without blocking work. |
+| 9. High-risk gate | `qamap scan . --fail-on high` | Block obvious risks such as committed env files or unsafe scripts. |
+| 10. Medium-risk gate | `qamap scan . --fail-on medium` | Require stronger agent guidance, tests, and workflow permissions. |
+
+`doctor`, `review`, `test-plan`, `eval`, and `report` remain available for teams that want the individual reports behind `verify`.
+
+## Monorepos
+
+When scanning a package inside a larger workspace, pass the workspace root so QAMap can separate package-local risks from repository guardrails:
+
+```sh
+qamap doctor services/offer --workspace-root . --format markdown
+qamap scan services/offer --workspace-root . --json
+```
+
+With `--workspace-root`, QAMap reads package-local files such as `package.json`, `.env.*`, and MCP config from the package path. It reads repo-level guardrails such as `AGENTS.md`, `.github/workflows`, `LICENSE`, `SECURITY.md`, and `CONTRIBUTING.md` from the workspace root.
+
+## What To Fix First
+
+Fix high-severity findings before letting an agent work broadly in the repo.
+
+1. Remove committed local environment files and rotate any exposed secrets.
+2. Move publish, push, merge, and destructive scripts out of normal agent workflows.
+3. Remove suspicious instruction text or fence it clearly as an example.
+4. Narrow GitHub Actions permissions.
+5. Add a real test command that agents and reviewers can run consistently.
+
+## CI Guidance
+
+For early rollout, fail only on high-severity findings:
+
+```yaml
+name: QAMap
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  qamap:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: IvoryCanvas/qamap@main
+        with:
+          mode: review
+          base: ${{ github.event.pull_request.base.sha }}
+          head: HEAD
+          fail-on: high
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+When the repository is stable, consider `--fail-on medium`.
+
+For all inputs, see [github-action.md](github-action.md).
+
+## Change Readiness Eval
+
+For the most useful PR-facing report, start with `verify`:
+
+```sh
+qamap verify . --base origin/main --head HEAD --pr-body-file pr-body.md --format markdown
+```
+
+Use `qamap eval` when an AI-assisted branch looks plausible but reviewers need a faster way to decide what still needs human attention:
+
+```sh
+qamap eval . --base origin/main --head HEAD --pr-body-file pr-body.md --format markdown
+```
+
+The eval report scores validation commands, changed-test coverage, intent capture, risk explanation, generated domain test scenarios, and review size. A low score does not mean the code is wrong; it means the branch is expensive or risky to verify.
+
+## Interpreting Findings
+
+QAMap findings are meant to be explainable. Each finding includes:
+
+- a rule id such as `QM009`
+- severity
+- file path when available
+- message
+- recommendation
+- short evidence when safe to print
+
+Prefer severity overrides over broad ignores when a rule is useful but too noisy for a specific repository.
+
+```json
+{
+  "severity": {
+    "QM007": "info"
+  }
+}
+```
+
+Use `ignoreRules` only for findings that the team intentionally accepts.

package/docs/agent-skill.md

@@ -0,0 +1,94 @@
+# QAMap As A Local QA Skill
+
+QAMap can be used as a small local tool that an AI coding agent runs before opening, updating, or finalizing a pull request.
+
+The goal is not to replace a reviewer or claim QA passed. The goal is to remove the repeated setup question:
+
+```txt
+What user flow did this PR touch, what should be tested, and what evidence is missing?
+```
+
+## Recommended Agent Step
+
+Run this before writing a PR body or asking for review. Agents should prefer the compact agent format — one minified JSON object (about 2 KB for a typical small PR) instead of a long report:
+
+```sh
+pnpm dlx @ivorycanvas/qamap qa . --base origin/main --head HEAD --format agent
+```
+
+The result carries `flows[]` (draft path, runnable status, entry route, steps, selectors), `requiredEvidence[]`, `requiredBootstrap[]`, `prChecklist[]`, and `commands[]` under `schema: qamap.qa`.
+
+For a human-readable report, drop the flag; for installed projects write it to a file:
+
+```sh
+pnpm exec qamap qa . --base origin/main --head HEAD --output QAMAP_QA.md
+```
+
+The command writes no test files. It only previews the QA work that should be attached to the PR.
+
+## Packaged Skill Template
+
+QAMap ships a portable skill template at:
+
+```txt
+skills/qamap-pr-qa/SKILL.md
+```
+
+Use it when an agent surface supports local skill folders, instruction folders, or reusable workflow prompts. The template is intentionally vendor-neutral: it tells an agent when to run `qamap qa`, how to pick a base branch, what sections to copy into the PR, and when to suggest manifest repair.
+
+After installing QAMap as a dev dependency, inspect the template:
+
+```sh
+cat node_modules/qamap/skills/qamap-pr-qa/SKILL.md
+```
+
+Or from a cloned QAMap repository:
+
+```sh
+cat skills/qamap-pr-qa/SKILL.md
+```
+
+If your agent supports symlinked skills, point its skill directory at `skills/qamap-pr-qa`. If it only supports instruction text, copy the contents of `SKILL.md` into that system's reusable instruction format.
+
+## What The Agent Should Do With The Output
+
+Use the `PR Comment Draft` section as review context:
+
+- affected flow
+- recommended runner
+- draft E2E or checklist path
+- missing fixture, selector, assertion, runner, or validation evidence
+- PR checklist items
+
+If the command says a generated recommendation is wrong, do not keep re-prompting the agent with the same context. Update the repo-local manifest after human review:
+
+```sh
+pnpm exec qamap manifest init .
+```
+
+Then edit `.qamap/manifest.yaml` so future branches can reuse the corrected team QA language.
+
+## Minimal Agent Instruction
+
+```txt
+Before finalizing a PR, run:
+pnpm dlx @ivorycanvas/qamap qa . --base origin/main --head HEAD --format agent
+
+Paste the affected flow, suggested E2E/checklist, missing evidence, and PR checklist into the PR body or review note.
+If the recommendation is wrong, ask the maintainer which manifest domain, flow, anchor, or check should be corrected.
+Do not treat QAMap output as proof that browser, device, API, or manual QA already passed.
+```
+
+## Manifest Is An Upgrade, Not A Gate
+
+First use should work without manifest setup. QAMap starts from PR diff and repo signals.
+
+Add `.qamap/manifest.yaml` when the team wants higher precision:
+
+- team-owned domain names
+- critical user flows
+- routes, files, components, APIs, or tests that anchor those flows
+- success, failure, edge, contract, or visual checks
+- preferred runner per flow
+
+That makes QAMap closer to a repo-local QA memory layer instead of a one-off prompt.

package/docs/api-contracts.md

@@ -0,0 +1,30 @@
+# API Contract Source Of Truth
+
+Frontend and backend teams often coordinate through API documents. That works best when the document is generated from a single contract source, not hand-maintained separately from code and client types.
+
+QAMap looks for a narrow drift signal:
+
+- Markdown or text docs that list HTTP endpoints in a method-plus-path form
+- No machine-readable API contract source in the repository
+
+When both are true, QAMap reports `QM013`.
+
+## Accepted Contract Sources
+
+QAMap currently treats these as machine-readable contract sources:
+
+- OpenAPI or Swagger: `openapi.yaml`, `openapi.yml`, `openapi.json`, `swagger.yaml`, `swagger.yml`, `swagger.json`
+- AsyncAPI: `asyncapi.yaml`, `asyncapi.yml`, `asyncapi.json`
+- Protocol Buffers: `*.proto`, `buf.yaml`, `buf.gen.yaml`
+- GraphQL SDL: `*.graphql`, `*.graphqls`, `schema.graphql`, `schema.graphqls`
+
+## Why It Matters
+
+AI coding agents can edit frontend clients, backend handlers, tests, and docs in the same pull request. If the API contract exists only as prose, agents and reviewers have a harder time knowing which representation is authoritative.
+
+Prefer one source of truth that can generate docs, validation, mock servers, or client types. This keeps API design review close to the code and reduces drift between documentation and implementation.
+
+## References
+
+- [Why frontend developers design APIs](https://blog.gangnamunni.com/post/saas-why-do-frontend-developers-design-api)
+- [Single source of truth](https://ko.wikipedia.org/wiki/%EB%8B%A8%EC%9D%BC_%EC%A7%84%EC%8B%A4_%EA%B3%B5%EA%B8%89%EC%9B%90)