harness-auto-docs 0.1.0

package/tests/core/generator.test.ts

@@ -0,0 +1,93 @@
+// tests/core/generator.test.ts
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { generateDocs, writeResults } from '../../src/core/generator.js';
+import type { AIProvider } from '../../src/ai/interface.js';
+import type { DiffResult } from '../../src/core/diff.js';
+
+const TMP = join(import.meta.dirname, '../../tmp-generator-test');
+
+beforeEach(() => mkdirSync(TMP, { recursive: true }));
+afterEach(() => rmSync(TMP, { recursive: true, force: true }));
+
+const mockAI: AIProvider = {
+  generate: vi.fn().mockResolvedValue('AI generated content for this section'),
+};
+
+const fakeDiff: DiffResult = {
+  raw: 'diff --git a/src/auth/login.ts b/src/auth/login.ts\n+new code',
+  prevTag: 'v1.0.0',
+  currentTag: 'v1.1.0',
+  changedFiles: ['src/auth/login.ts'],
+  fileGroups: {
+    frontend: [],
+    schema: [],
+    auth: ['src/auth/login.ts'],
+    infra: [],
+    other: [],
+  },
+};
+
+describe('generateDocs', () => {
+  it('calls AI for each target and returns results', async () => {
+    const results = await generateDocs(mockAI, fakeDiff, ['AGENTS.md', 'ARCHITECTURE.md']);
+    expect(results).toHaveLength(2);
+    expect(results[0].target).toBe('AGENTS.md');
+    expect(results[0].content).toBe('AI generated content for this section');
+    expect(mockAI.generate).toHaveBeenCalledTimes(2);
+  });
+
+  it('captures errors without throwing', async () => {
+    const failingAI: AIProvider = {
+      generate: vi.fn().mockRejectedValue(new Error('API rate limit')),
+    };
+    const results = await generateDocs(failingAI, fakeDiff, ['AGENTS.md']);
+    expect(results[0].error).toContain('API rate limit');
+    expect(results[0].content).toBe('');
+  });
+
+  it('runs targets concurrently', async () => {
+    const timedAI: AIProvider = {
+      generate: vi.fn().mockImplementation(async () => {
+        await new Promise(r => setTimeout(r, 50));
+        return 'content';
+      }),
+    };
+    const start = Date.now();
+    await generateDocs(timedAI, fakeDiff, ['AGENTS.md', 'ARCHITECTURE.md', 'DESIGN.md']);
+    const elapsed = Date.now() - start;
+    expect(elapsed).toBeLessThan(130);
+  });
+});
+
+describe('writeResults', () => {
+  it('writes AGENTS.md as appended section', async () => {
+    const results = await generateDocs(mockAI, fakeDiff, ['AGENTS.md']);
+    const written = writeResults(results, fakeDiff, TMP);
+    expect(written).toContain(`${TMP}/AGENTS.md`);
+    const content = readFileSync(`${TMP}/AGENTS.md`, 'utf-8');
+    expect(content).toContain('## Changes in v1.1.0');
+  });
+
+  it('creates changelog file at versioned path', async () => {
+    const results = await generateDocs(mockAI, fakeDiff, ['changelog']);
+    writeResults(results, fakeDiff, TMP);
+    expect(existsSync(`${TMP}/changelog/v1.1.0.md`)).toBe(true);
+  });
+
+  it('creates design-doc at versioned path', async () => {
+    const results = await generateDocs(mockAI, fakeDiff, ['design-doc']);
+    writeResults(results, fakeDiff, TMP);
+    expect(existsSync(`${TMP}/docs/design-docs/v1.1.0.md`)).toBe(true);
+  });
+
+  it('skips results with errors', async () => {
+    const failingAI: AIProvider = {
+      generate: vi.fn().mockRejectedValue(new Error('fail')),
+    };
+    const results = await generateDocs(failingAI, fakeDiff, ['AGENTS.md']);
+    const written = writeResults(results, fakeDiff, TMP);
+    expect(written).toHaveLength(0);
+  });
+});

package/tests/core/openai.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect, vi } from 'vitest';
+import { OpenAIProvider } from '../../src/ai/openai.js';
+
+vi.mock('openai', () => ({
+  default: vi.fn().mockImplementation(() => ({
+    chat: {
+      completions: {
+        create: vi.fn().mockResolvedValue({
+          choices: [{ message: { content: 'gpt generated content' } }],
+        }),
+      },
+    },
+  })),
+}));
+
+describe('OpenAIProvider', () => {
+  it('returns text content from the API response', async () => {
+    const provider = new OpenAIProvider('test-key', 'gpt-4o');
+    const result = await provider.generate('write docs for this diff');
+    expect(result).toBe('gpt generated content');
+  });
+
+  it('returns empty string when message content is null', async () => {
+    const { default: OpenAI } = await import('openai');
+    vi.mocked(OpenAI).mockImplementationOnce(() => ({
+      chat: {
+        completions: {
+          create: vi.fn().mockResolvedValue({
+            choices: [{ message: { content: null } }],
+          }),
+        },
+      },
+    }) as any);
+    const provider = new OpenAIProvider('test-key', 'gpt-4o');
+    const result = await provider.generate('prompt');
+    expect(result).toBe('');
+  });
+});

package/tests/core/relevance.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import { selectTargets } from '../../src/core/relevance.js';
+import type { FileGroups } from '../../src/core/diff.js';
+
+const emptyGroups: FileGroups = {
+  frontend: [], schema: [], auth: [], infra: [], other: [],
+};
+
+describe('selectTargets', () => {
+  it('always includes core targets', () => {
+    const targets = selectTargets(emptyGroups, []);
+    expect(targets).toContain('AGENTS.md');
+    expect(targets).toContain('ARCHITECTURE.md');
+    expect(targets).toContain('DESIGN.md');
+    expect(targets).toContain('QUALITY_SCORE.md');
+    expect(targets).toContain('changelog');
+    expect(targets).toContain('design-doc');
+    expect(targets).toContain('design-doc-index');
+    expect(targets).toContain('tech-debt-tracker');
+  });
+
+  it('includes FRONTEND.md only when frontend files changed', () => {
+    const withFrontend = selectTargets(
+      { ...emptyGroups, frontend: ['src/ui/Button.tsx'] }, []
+    );
+    expect(withFrontend).toContain('FRONTEND.md');
+
+    const withoutFrontend = selectTargets(emptyGroups, []);
+    expect(withoutFrontend).not.toContain('FRONTEND.md');
+  });
+
+  it('includes SECURITY.md only when auth files changed', () => {
+    const targets = selectTargets(
+      { ...emptyGroups, auth: ['src/auth/login.ts'] }, []
+    );
+    expect(targets).toContain('SECURITY.md');
+  });
+
+  it('includes RELIABILITY.md only when infra files changed', () => {
+    const targets = selectTargets(
+      { ...emptyGroups, infra: ['infra/deploy.yaml'] }, []
+    );
+    expect(targets).toContain('RELIABILITY.md');
+  });
+
+  it('includes db-schema only when schema files changed', () => {
+    const targets = selectTargets(
+      { ...emptyGroups, schema: ['migrations/001.sql'] }, []
+    );
+    expect(targets).toContain('db-schema');
+  });
+
+  it('includes references when package.json changed', () => {
+    const targets = selectTargets(emptyGroups, ['package.json']);
+    expect(targets).toContain('references');
+  });
+
+  it('returns no duplicates', () => {
+    const targets = selectTargets(emptyGroups, []);
+    expect(targets.length).toBe(new Set(targets).size);
+  });
+});

package/tests/core/writer.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { appendSection, createFile } from '../../src/core/writer.js';
+
+const TMP = join(import.meta.dirname, '../../tmp-writer-test');
+
+beforeEach(() => mkdirSync(TMP, { recursive: true }));
+afterEach(() => rmSync(TMP, { recursive: true, force: true }));
+
+describe('appendSection', () => {
+  it('creates file if it does not exist', () => {
+    const path = join(TMP, 'AGENTS.md');
+    appendSection(path, 'Changes in v1.1.0', 'New auth module added.');
+    expect(existsSync(path)).toBe(true);
+    const content = readFileSync(path, 'utf-8');
+    expect(content).toContain('## Changes in v1.1.0');
+    expect(content).toContain('New auth module added.');
+  });
+
+  it('appends to existing file', () => {
+    const path = join(TMP, 'ARCHITECTURE.md');
+    appendSection(path, 'Changes in v1.0.0', 'Initial architecture.');
+    appendSection(path, 'Changes in v1.1.0', 'Added caching layer.');
+    const content = readFileSync(path, 'utf-8');
+    expect(content).toContain('## Changes in v1.0.0');
+    expect(content).toContain('## Changes in v1.1.0');
+  });
+
+  it('creates missing parent directories', () => {
+    const path = join(TMP, 'docs/design-docs/index.md');
+    appendSection(path, 'v1.0.0', 'entry');
+    expect(existsSync(path)).toBe(true);
+  });
+});
+
+describe('createFile', () => {
+  it('creates a file with the given content', () => {
+    const path = join(TMP, 'changelog/v1.0.0.md');
+    createFile(path, '# Changelog: v1.0.0\n\n## Added\n- First release');
+    expect(readFileSync(path, 'utf-8')).toContain('First release');
+  });
+
+  it('overwrites an existing file', () => {
+    const path = join(TMP, 'test.md');
+    createFile(path, 'first content');
+    createFile(path, 'second content');
+    expect(readFileSync(path, 'utf-8')).toBe('second content');
+  });
+
+  it('creates missing parent directories', () => {
+    const path = join(TMP, 'a/b/c/file.md');
+    createFile(path, 'content');
+    expect(existsSync(path)).toBe(true);
+  });
+});

package/tests/fixtures/diff-frontend.txt

@@ -0,0 +1,11 @@
+diff --git a/src/ui/Button.tsx b/src/ui/Button.tsx
+new file mode 100644
+index 0000000..aabbcc
+--- /dev/null
++++ b/src/ui/Button.tsx
+@@ -0,0 +1,8 @@
++export function Button({ label }: { label: string }) {
++  return <button>{label}</button>;
++}
+diff --git a/src/ui/styles.css b/src/ui/styles.css
+new file mode 100644

package/tests/fixtures/diff-schema.txt

@@ -0,0 +1,12 @@
+diff --git a/migrations/001_add_users.sql b/migrations/001_add_users.sql
+new file mode 100644
+index 0000000..aabbcc
+--- /dev/null
++++ b/migrations/001_add_users.sql
+@@ -0,0 +1,5 @@
++CREATE TABLE users (
++  id UUID PRIMARY KEY,
++  email TEXT NOT NULL UNIQUE
++);
+diff --git a/src/db/schema.ts b/src/db/schema.ts
+new file mode 100644

package/tests/fixtures/diff-small.txt

@@ -0,0 +1,16 @@
+diff --git a/src/auth/login.ts b/src/auth/login.ts
+index abc1234..def5678 100644
+--- a/src/auth/login.ts
++++ b/src/auth/login.ts
+@@ -1,5 +1,10 @@
++export function login(email: string, password: string) {
++  return { token: 'jwt' };
++}
+diff --git a/src/utils/helpers.ts b/src/utils/helpers.ts
+index 111aaaa..222bbbb 100644
+--- a/src/utils/helpers.ts
++++ b/src/utils/helpers.ts
+@@ -1,3 +1,6 @@
++export function sleep(ms: number) {
++  return new Promise(r => setTimeout(r, ms));
++}

package/tests/integration/generate.test.ts

@@ -0,0 +1,49 @@
+// tests/integration/generate.test.ts
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync } from 'fs';
+import { join } from 'path';
+import { generateDocs, writeResults } from '../../src/core/generator.js';
+import { selectTargets } from '../../src/core/relevance.js';
+import { parseChangedFiles, groupFiles } from '../../src/core/diff.js';
+import { readFileSync } from 'fs';
+import type { AIProvider } from '../../src/ai/interface.js';
+
+const TMP = join(import.meta.dirname, '../../tmp-integration-test');
+const FIXTURE = readFileSync(
+  join(import.meta.dirname, '../fixtures/diff-schema.txt'), 'utf-8'
+);
+
+beforeEach(() => mkdirSync(TMP, { recursive: true }));
+afterEach(() => rmSync(TMP, { recursive: true, force: true }));
+
+describe('full pipeline: diff → relevance → generate → write', () => {
+  it('generates and writes expected documents for schema diff', async () => {
+    const changedFiles = parseChangedFiles(FIXTURE);
+    const fileGroups = groupFiles(changedFiles);
+    const targets = selectTargets(fileGroups, changedFiles);
+
+    expect(targets).toContain('db-schema');
+    expect(targets).toContain('AGENTS.md');
+
+    const mockAI: AIProvider = {
+      generate: vi.fn().mockResolvedValue('Auto-generated documentation content'),
+    };
+
+    const diff = {
+      raw: FIXTURE,
+      prevTag: 'v1.0.0',
+      currentTag: 'v1.1.0',
+      changedFiles,
+      fileGroups,
+    };
+
+    const results = await generateDocs(mockAI, diff, targets);
+    const written = writeResults(results, diff, TMP);
+
+    expect(written.length).toBeGreaterThan(0);
+    expect(existsSync(`${TMP}/AGENTS.md`)).toBe(true);
+    expect(existsSync(`${TMP}/docs/generated/db-schema.md`)).toBe(true);
+    expect(existsSync(`${TMP}/changelog/v1.1.0.md`)).toBe(true);
+    expect(existsSync(`${TMP}/docs/design-docs/v1.1.0.md`)).toBe(true);
+  });
+});

package/tests/providers/github.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { GitHubProvider } from '../../src/providers/github.js';
+
+vi.mock('child_process', () => ({
+  execSync: vi.fn().mockReturnValue('git@github.com:myorg/myrepo.git\n'),
+}));
+
+const mockOctokit = {
+  pulls: {
+    list: vi.fn().mockResolvedValue({ data: [] }),
+    create: vi.fn().mockResolvedValue({
+      data: { html_url: 'https://github.com/myorg/myrepo/pull/42', number: 42 },
+    }),
+    update: vi.fn().mockResolvedValue({
+      data: { html_url: 'https://github.com/myorg/myrepo/pull/1' },
+    }),
+  },
+};
+
+vi.mock('@octokit/rest', () => ({
+  Octokit: vi.fn().mockImplementation(() => mockOctokit),
+}));
+
+describe('GitHubProvider', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('parses owner and repo from SSH remote URL', () => {
+    expect(() => new GitHubProvider('token')).not.toThrow();
+  });
+
+  it('creates a PR and returns its URL', async () => {
+    const provider = new GitHubProvider('token');
+    const url = await provider.createOrUpdatePR({
+      branch: 'harness-docs/v1.1.0',
+      title: 'docs: update for v1.1.0',
+      body: 'Auto-generated docs update',
+      baseBranch: 'main',
+    });
+    expect(url).toBe('https://github.com/myorg/myrepo/pull/42');
+    expect(mockOctokit.pulls.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        head: 'harness-docs/v1.1.0',
+        base: 'main',
+      })
+    );
+  });
+
+  it('updates existing PR if one already exists for the branch', async () => {
+    mockOctokit.pulls.list.mockResolvedValueOnce({
+      data: [{ number: 1, html_url: 'https://github.com/myorg/myrepo/pull/1' }],
+    });
+    const provider = new GitHubProvider('token');
+    const url = await provider.createOrUpdatePR({
+      branch: 'harness-docs/v1.1.0',
+      title: 'docs: update for v1.1.0',
+      body: 'Updated',
+      baseBranch: 'main',
+    });
+    expect(mockOctokit.pulls.update).toHaveBeenCalled();
+    expect(mockOctokit.pulls.create).not.toHaveBeenCalled();
+    expect(url).toBe('https://github.com/myorg/myrepo/pull/1');
+  });
+
+  it('throws on unrecognized remote URL', async () => {
+    const { execSync } = await import('child_process');
+    vi.mocked(execSync).mockReturnValueOnce('https://not-github.com/something\n' as any);
+    expect(() => new GitHubProvider('token')).toThrow('Cannot parse GitHub remote URL');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+  },
+});