From raw idea to
deployed product
in one session

## The Job

Core job statement:
When I merge a PR that changes an API,
I need to update the documentation
immediately, so that developers using
my API don't get silently broken by
stale docs.

## Why Current Solutions Fall Short

| Pain                | Why it persists     |
|---------------------|---------------------|
| Discovery reactive  | No spec watcher     |
| Context lost by     | PR author moved on  |
|  update time        |                     |
| Tools render docs   | Don't write them    |

## Key JTBD Insight

The primary job is NOT "write docs."
It's "never let a shipped change go
undocumented."

# This means the core loop is:
detect → draft → route → publish

## User Stories

| # | As a...           | I want to...              |
|---|-------------------|---------------------------|
| 1 | Dev-rel engineer  | Get a PR automatically    |
|   |                   | when an endpoint changes  |
| 2 | Technical writer  | Review AI draft in plain  |
|   |                   | English, not raw YAML     |
| 3 | Backend engineer  | Merge API changes without |
|   |                   | filing a separate ticket  |

## Success Criteria

1. Merged PR triggers doc PR
   within 90 seconds
2. Generated prose accurate for
   85%+ of endpoint changes
3. Zero false-positive triggers
4. Setup time under 15 minutes

## Out of Scope (v1)
- GitLab / Bitbucket
- Auto-publish without review
- Multi-spec monorepo

interface SpecChange {
  type: 'added' | 'removed' | 'modified';
  path: string;        // e.g. "/payments/{id}"
  method: string;      // e.g. "POST"
  before?: EndpointDef;
  after?: EndpointDef;
  breakingChange: boolean;
}

interface DocDraft {
  filePath: string;    // which .md to update
  section: string;     // which section
  content: string;     // generated markdown
  change: SpecChange;
}

// Build order
// 1. config.ts
// 2. diff/parser.ts
// 3. diff/engine.ts
// 4. generate/drafter.ts
// 5. publish/github.ts
// 6. publish/slack.ts
// 7. src/index.ts (wire all)
// 8. GitHub Actions workflow
// 9. Tests

export function detectChanges(
  before: OpenAPIObject,
  after: OpenAPIObject
): SpecChange[] {
  const changes: SpecChange[] = [];
  const allPaths = new Set([
    ...Object.keys(before.paths ?? {}),
    ...Object.keys(after.paths ?? {}),
  ]);

  for (const path of allPaths) {
    for (const method of HTTP_METHODS) {
      const beforeOp = beforePath[method];
      const afterOp = afterPath[method];

      if (!beforeOp && afterOp) {
        changes.push({
          type: "added", path, method,
          after: afterOp,
          breakingChange: false
        });
      } else if (beforeOp && !afterOp) {
        changes.push({
          type: "removed", path, method,
          before: beforeOp,
          breakingChange: true // removal is always breaking
        });
      }
    }
  }
  return changes;
}

export async function draftUpdates(
  changes: SpecChange[],
  config: DocDeltaConfig
): Promise<DocDraft[]> {

  const message = await client.messages.create({
    model: "claude-haiku-4-5-20251001", // cost-optimized
    max_tokens: 4096,
    messages: [{
      role: "user",
      content: buildPrompt(changes)
    }]
  });

  // Extract JSON array from response
  const jsonMatch = responseText.match(/\[[\s\S]*\]/);
  const drafts = JSON.parse(jsonMatch[0]);

  return drafts.map(d => ({
    filePath: d.filePath,
    section: `${d.method} ${d.path}`,
    content: d.content,  // ready-to-commit markdown
    change: changes.find(c =>
      c.path === d.path && c.method === d.method
    )
  }));
}

test('removed endpoint is breaking', () => {
  const changes = detectChanges(baseSpec, noPaymentsSpec);
  expect(changes[0].type).toBe('removed');
  expect(changes[0].breakingChange).toBe(true);
});

test('added endpoint is not breaking', () => {
  const changes = detectChanges(baseSpec, withRefundSpec);
  expect(changes[0].breakingChange).toBe(false);
});

test('parameter type change is breaking', () => {
  // id: string → integer (breaking for API consumers)
  const changes = detectChanges(baseSpec, intIdSpec);
  expect(changes[0].breakingChange).toBe(true);
});

test('no changes returns empty array', () => {
  const changes = detectChanges(baseSpec, baseSpec);
  expect(changes).toHaveLength(0);
});

name: DocDelta — Auto-update API docs

on:
  push:
    branches: [main]
    paths:
      - "openapi.yaml"

jobs:
  docdelta:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2 # need both commits for diff

      - name: Run DocDelta
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: npx ts-node src/index.ts