harness-auto-docs 0.1.0

package/src/core/diff.ts

@@ -0,0 +1,77 @@
+// src/core/diff.ts
+import { execSync } from 'child_process';
+
+export interface FileGroups {
+  frontend: string[];
+  schema: string[];
+  auth: string[];
+  infra: string[];
+  other: string[];
+}
+
+export interface DiffResult {
+  raw: string;
+  prevTag: string;
+  currentTag: string;
+  changedFiles: string[];
+  fileGroups: FileGroups;
+}
+
+export function extractDiff(): DiffResult {
+  const tags = execSync('git tag --sort=version:refname')
+    .toString()
+    .trim()
+    .split('\n')
+    .filter(Boolean);
+
+  if (tags.length === 0) throw new Error('No tags found in repository');
+
+  const currentTag = tags[tags.length - 1];
+  const prevTag = tags.length >= 2 ? tags[tags.length - 2] : null;
+
+  const raw = prevTag
+    ? execSync(`git diff ${prevTag} ${currentTag}`).toString()
+    : execSync(`git show ${currentTag} --format='' -p`).toString();
+
+  const changedFiles = parseChangedFiles(raw);
+  const fileGroups = groupFiles(changedFiles);
+
+  return {
+    raw,
+    prevTag: prevTag ?? '(initial)',
+    currentTag,
+    changedFiles,
+    fileGroups,
+  };
+}
+
+export function parseChangedFiles(diff: string): string[] {
+  const matches = diff.match(/^diff --git a\/.+ b\/(.+)$/gm) ?? [];
+  return matches.map(line => {
+    const match = line.match(/^diff --git a\/.+ b\/(.+)$/);
+    return match ? match[1] : '';
+  }).filter(Boolean);
+}
+
+export function groupFiles(files: string[]): FileGroups {
+  const isFrontend = (f: string) =>
+    /\.(tsx?|jsx?|css|scss|html|vue|svelte)$/.test(f) ||
+    /\b(ui|frontend|components|pages|views)\b/.test(f);
+
+  const isSchema = (f: string) =>
+    /\.sql$/.test(f) || /\b(schema|migration|migrate)\b/i.test(f);
+
+  const isAuth = (f: string) =>
+    /\b(auth|permission|security|oauth|jwt|session|token)\b/i.test(f);
+
+  const isInfra = (f: string) =>
+    /\b(infra|deploy|k8s|docker|compose|helm|terraform|service|gateway)\b/i.test(f);
+
+  return {
+    frontend: files.filter(isFrontend),
+    schema: files.filter(isSchema),
+    auth: files.filter(isAuth),
+    infra: files.filter(isInfra),
+    other: files.filter(f => !isFrontend(f) && !isSchema(f) && !isAuth(f) && !isInfra(f)),
+  };
+}

package/src/core/generator.ts

@@ -0,0 +1,294 @@
+// src/core/generator.ts
+import type { AIProvider } from '../ai/interface.js';
+import type { DocTarget } from './relevance.js';
+import type { DiffResult } from './diff.js';
+import { appendSection, createFile } from './writer.js';
+
+type PromptFn = (diff: DiffResult) => string;
+
+const PROMPTS: Record<DocTarget, PromptFn> = {
+  'AGENTS.md': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, write a section for AGENTS.md.
+Describe what AI coding agents need to know: new modules, interfaces, APIs, navigation patterns, new conventions.
+Write in present tense. Be specific and actionable. 2-4 paragraphs max.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'ARCHITECTURE.md': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, write a section for ARCHITECTURE.md.
+Focus on: new layers, modules, dependency changes, new abstractions, removed or restructured components.
+Write in present tense. 2-3 paragraphs max.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'DESIGN.md': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, write a section for docs/DESIGN.md.
+Focus on key design decisions, why certain approaches were chosen, trade-offs made.
+Write in present tense. 2-3 paragraphs max.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'FRONTEND.md': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, write a section for FRONTEND.md.
+Focus on new components, UI patterns, styling changes, frontend architecture changes.
+Write in present tense. 2-3 paragraphs max.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'SECURITY.md': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, write a section for SECURITY.md.
+Focus on auth changes, permission model updates, new security boundaries, data handling changes.
+Write in present tense. 2-3 paragraphs max.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'RELIABILITY.md': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, write a section for RELIABILITY.md.
+Focus on error handling improvements, retry logic, circuit breakers, observability changes.
+Write in present tense. 2-3 paragraphs max.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'QUALITY_SCORE.md': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, write a quality assessment section.
+Assess test coverage changes, code complexity, technical debt introduced or resolved.
+Write in present tense. 1-2 paragraphs max.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'changelog': (diff) =>
+    `Write a changelog entry in Markdown for changes from ${diff.prevTag} to ${diff.currentTag}.
+
+Format:
+# Changelog: ${diff.currentTag}
+
+## Added
+- ...
+
+## Changed
+- ...
+
+## Fixed
+- ...
+
+## Removed
+- ...
+
+Be specific and engineer-focused. Only include sections with actual content.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'design-doc': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Write a design document for changes from ${diff.prevTag} to ${diff.currentTag}.
+
+Format:
+# Design: ${diff.currentTag}
+
+## Summary
+[What changed and why]
+
+## Design Decisions
+[Key decisions with rationale]
+
+## Agent Legibility Notes
+[What an AI coding agent needs to know to work in the updated codebase]
+
+## Technical Debt
+[Any shortcuts taken, what should be cleaned up later — or "None identified"]
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'design-doc-index': (diff) =>
+    `Return only a single Markdown list item for a docs index. Format:
+- [${diff.currentTag}](${diff.currentTag}.md) — One-sentence summary of changes.
+
+Changed files: ${diff.changedFiles.slice(0, 20).join(', ')}
+
+Return only the list item, nothing else.`,
+
+  'tech-debt-tracker': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, identify technical debt.
+
+Write this section:
+## ${diff.currentTag}
+
+### New debt
+- [Shortcuts, hacks, or deferred work visible in the diff — or "None identified"]
+
+### Resolved debt
+- [Cleanup or refactoring that resolves known issues — or "None identified"]
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'db-schema': (diff) =>
+    `You are a technical writer.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, document database schema changes.
+Focus only on schema changes visible in the diff: new tables, columns, indexes, constraints.
+Format as Markdown with clear table descriptions.
+If no schema changes: write "No schema changes in this release."
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'product-specs-index': (diff) =>
+    `Return only a single Markdown list item for a product specs index, or an empty string if no clear new feature.
+Format (if applicable): - [Feature Name](feature-name.md) — One-sentence description.
+
+Changed files: ${diff.changedFiles.slice(0, 20).join(', ')}
+
+Return only the list item or empty string, nothing else.`,
+
+  'references': (diff) =>
+    `You are a technical writer.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, identify new external libraries introduced.
+For each new library write:
+
+# library-name
+
+One paragraph: what it does and how it is used in this codebase.
+
+If no new external libraries: return an empty string.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+};
+
+export interface GenerationResult {
+  target: DocTarget;
+  content: string;
+  error?: string;
+}
+
+export async function generateDocs(
+  ai: AIProvider,
+  diff: DiffResult,
+  targets: DocTarget[]
+): Promise<GenerationResult[]> {
+  return Promise.all(
+    targets.map(async (target): Promise<GenerationResult> => {
+      try {
+        const prompt = PROMPTS[target](diff);
+        const content = await ai.generate(prompt);
+        return { target, content };
+      } catch (err) {
+        return { target, content: '', error: String(err) };
+      }
+    })
+  );
+}
+
+export function writeResults(
+  results: GenerationResult[],
+  diff: DiffResult,
+  cwd: string
+): string[] {
+  const written: string[] = [];
+  for (const result of results) {
+    if (result.error || !result.content.trim()) continue;
+    const path = writeResult(result, diff, cwd);
+    if (path) written.push(path);
+  }
+  return written;
+}
+
+function writeResult(
+  result: GenerationResult,
+  diff: DiffResult,
+  cwd: string
+): string | null {
+  const tag = diff.currentTag;
+  const heading = `Changes in ${tag}`;
+
+  const appendTargets: DocTarget[] = [
+    'AGENTS.md', 'ARCHITECTURE.md', 'DESIGN.md', 'FRONTEND.md',
+    'SECURITY.md', 'RELIABILITY.md', 'QUALITY_SCORE.md',
+  ];
+
+  const rootTargets: DocTarget[] = ['AGENTS.md', 'ARCHITECTURE.md'];
+
+  if ((appendTargets as string[]).includes(result.target)) {
+    const dir = (rootTargets as string[]).includes(result.target) ? '' : 'docs/';
+    const path = `${cwd}/${dir}${result.target}`;
+    appendSection(path, heading, result.content);
+    return path;
+  }
+
+  switch (result.target) {
+    case 'changelog': {
+      const path = `${cwd}/changelog/${tag}.md`;
+      createFile(path, result.content);
+      return path;
+    }
+    case 'design-doc': {
+      const path = `${cwd}/docs/design-docs/${tag}.md`;
+      createFile(path, result.content);
+      return path;
+    }
+    case 'design-doc-index': {
+      const path = `${cwd}/docs/design-docs/index.md`;
+      appendSection(path, heading, result.content);
+      return path;
+    }
+    case 'tech-debt-tracker': {
+      const path = `${cwd}/docs/exec-plans/tech-debt-tracker.md`;
+      appendSection(path, heading, result.content);
+      return path;
+    }
+    case 'db-schema': {
+      const path = `${cwd}/docs/generated/db-schema.md`;
+      appendSection(path, heading, result.content);
+      return path;
+    }
+    case 'product-specs-index': {
+      if (!result.content.trim()) return null;
+      const path = `${cwd}/docs/product-specs/index.md`;
+      appendSection(path, heading, result.content);
+      return path;
+    }
+    case 'references': {
+      if (!result.content.trim()) return null;
+      const libName = extractLibName(result.content);
+      if (!libName) return null;
+      const path = `${cwd}/docs/references/${libName}-llms.txt`;
+      createFile(path, result.content);
+      return path;
+    }
+    default:
+      return null;
+  }
+}
+
+function extractLibName(content: string): string | null {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].toLowerCase().replace(/[^a-z0-9-]/g, '-') : null;
+}

package/src/core/relevance.ts

@@ -0,0 +1,53 @@
+// src/core/relevance.ts
+import type { FileGroups } from './diff.js';
+
+export type DocTarget =
+  | 'AGENTS.md'
+  | 'ARCHITECTURE.md'
+  | 'DESIGN.md'
+  | 'FRONTEND.md'
+  | 'SECURITY.md'
+  | 'RELIABILITY.md'
+  | 'QUALITY_SCORE.md'
+  | 'changelog'
+  | 'design-doc'
+  | 'design-doc-index'
+  | 'tech-debt-tracker'
+  | 'db-schema'
+  | 'product-specs-index'
+  | 'references';
+
+const CORE_TARGETS: DocTarget[] = [
+  'AGENTS.md',
+  'ARCHITECTURE.md',
+  'DESIGN.md',
+  'QUALITY_SCORE.md',
+  'changelog',
+  'design-doc',
+  'design-doc-index',
+  'tech-debt-tracker',
+];
+
+export function selectTargets(
+  fileGroups: FileGroups,
+  changedFiles: string[]
+): DocTarget[] {
+  const targets: DocTarget[] = [...CORE_TARGETS];
+
+  if (fileGroups.frontend.length > 0) targets.push('FRONTEND.md');
+  if (fileGroups.auth.length > 0) targets.push('SECURITY.md');
+  if (fileGroups.infra.length > 0) targets.push('RELIABILITY.md');
+  if (fileGroups.schema.length > 0) targets.push('db-schema');
+
+  const packageFiles = ['package.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'];
+  if (changedFiles.some(f => packageFiles.includes(f))) {
+    targets.push('references');
+  }
+
+  const looksLikeNewFeature = changedFiles.some(f =>
+    /\b(feature|feat|new)\b/i.test(f) || f.startsWith('src/features/')
+  );
+  if (looksLikeNewFeature) targets.push('product-specs-index');
+
+  return [...new Set(targets)];
+}

package/src/core/writer.ts

@@ -0,0 +1,25 @@
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+export function appendSection(filePath: string, heading: string, content: string): void {
+  ensureDir(filePath);
+  const section = `\n## ${heading}\n\n${content}\n`;
+  if (existsSync(filePath)) {
+    const existing = readFileSync(filePath, 'utf-8');
+    writeFileSync(filePath, existing + section, 'utf-8');
+  } else {
+    writeFileSync(filePath, section.trimStart(), 'utf-8');
+  }
+}
+
+export function createFile(filePath: string, content: string): void {
+  ensureDir(filePath);
+  writeFileSync(filePath, content, 'utf-8');
+}
+
+function ensureDir(filePath: string): void {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}

package/src/providers/github.ts

@@ -0,0 +1,53 @@
+import { Octokit } from '@octokit/rest';
+import { execSync } from 'child_process';
+import type { PlatformProvider } from './interface.js';
+
+export class GitHubProvider implements PlatformProvider {
+  private octokit: Octokit;
+  private owner: string;
+  private repo: string;
+
+  constructor(token: string) {
+    this.octokit = new Octokit({ auth: token });
+    const remoteUrl = execSync('git remote get-url origin').toString().trim();
+    const match = remoteUrl.match(/github\.com[/:](.+?)\/(.+?)(?:\.git)?$/);
+    if (!match) throw new Error(`Cannot parse GitHub remote URL: ${remoteUrl}`);
+    this.owner = match[1];
+    this.repo = match[2];
+  }
+
+  async createOrUpdatePR(opts: {
+    branch: string;
+    title: string;
+    body: string;
+    baseBranch: string;
+  }): Promise<string> {
+    const { data: existingPRs } = await this.octokit.pulls.list({
+      owner: this.owner,
+      repo: this.repo,
+      head: `${this.owner}:${opts.branch}`,
+      state: 'open',
+    });
+
+    if (existingPRs.length > 0) {
+      const { data: pr } = await this.octokit.pulls.update({
+        owner: this.owner,
+        repo: this.repo,
+        pull_number: existingPRs[0].number,
+        title: opts.title,
+        body: opts.body,
+      });
+      return pr.html_url;
+    }
+
+    const { data: pr } = await this.octokit.pulls.create({
+      owner: this.owner,
+      repo: this.repo,
+      title: opts.title,
+      body: opts.body,
+      head: opts.branch,
+      base: opts.baseBranch,
+    });
+    return pr.html_url;
+  }
+}

package/src/providers/gitlab.ts

@@ -0,0 +1,16 @@
+// src/providers/gitlab.ts
+import type { PlatformProvider } from './interface.js';
+
+export class GitLabProvider implements PlatformProvider {
+  async createOrUpdatePR(_opts: {
+    branch: string;
+    title: string;
+    body: string;
+    baseBranch: string;
+  }): Promise<string> {
+    throw new Error(
+      'GitLab provider is not yet implemented. ' +
+      'Contributions welcome: https://github.com/your-org/harness-engineering-auto-docs'
+    );
+  }
+}

package/src/providers/interface.ts

@@ -0,0 +1,9 @@
+// src/providers/interface.ts
+export interface PlatformProvider {
+  createOrUpdatePR(opts: {
+    branch: string;
+    title: string;
+    body: string;
+    baseBranch: string;
+  }): Promise<string>;
+}

package/tests/core/anthropic.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect, vi } from 'vitest';
+import { AnthropicProvider } from '../../src/ai/anthropic.js';
+
+vi.mock('@anthropic-ai/sdk', () => ({
+  default: vi.fn().mockImplementation(() => ({
+    messages: {
+      create: vi.fn().mockResolvedValue({
+        content: [{ type: 'text', text: 'generated content' }],
+      }),
+    },
+  })),
+}));
+
+describe('AnthropicProvider', () => {
+  it('returns text content from the API response', async () => {
+    const provider = new AnthropicProvider('test-key', 'claude-sonnet-4-6');
+    const result = await provider.generate('write docs for this diff');
+    expect(result).toBe('generated content');
+  });
+
+  it('throws if response content is not text', async () => {
+    const { default: Anthropic } = await import('@anthropic-ai/sdk');
+    vi.mocked(Anthropic).mockImplementationOnce(() => ({
+      messages: {
+        create: vi.fn().mockResolvedValue({
+          content: [{ type: 'image', source: {} }],
+        }),
+      },
+    }) as any);
+    const provider = new AnthropicProvider('test-key', 'claude-sonnet-4-6');
+    await expect(provider.generate('prompt')).rejects.toThrow('Unexpected response type');
+  });
+});

package/tests/core/diff.test.ts

@@ -0,0 +1,49 @@
+// tests/core/diff.test.ts
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { parseChangedFiles, groupFiles } from '../../src/core/diff.js';
+
+const smallDiff = readFileSync(
+  join(import.meta.dirname, '../fixtures/diff-small.txt'), 'utf-8'
+);
+const schemaDiff = readFileSync(
+  join(import.meta.dirname, '../fixtures/diff-schema.txt'), 'utf-8'
+);
+const frontendDiff = readFileSync(
+  join(import.meta.dirname, '../fixtures/diff-frontend.txt'), 'utf-8'
+);
+
+describe('parseChangedFiles', () => {
+  it('extracts file paths from diff output', () => {
+    const files = parseChangedFiles(smallDiff);
+    expect(files).toContain('src/auth/login.ts');
+    expect(files).toContain('src/utils/helpers.ts');
+    expect(files).toHaveLength(2);
+  });
+
+  it('returns empty array for empty diff', () => {
+    expect(parseChangedFiles('')).toEqual([]);
+  });
+});
+
+describe('groupFiles', () => {
+  it('puts auth files in auth group', () => {
+    const groups = groupFiles(['src/auth/login.ts', 'src/utils/helpers.ts']);
+    expect(groups.auth).toContain('src/auth/login.ts');
+    expect(groups.auth).not.toContain('src/utils/helpers.ts');
+  });
+
+  it('puts sql files in schema group', () => {
+    const files = parseChangedFiles(schemaDiff);
+    const groups = groupFiles(files);
+    expect(groups.schema.length).toBeGreaterThan(0);
+  });
+
+  it('puts tsx files in frontend group', () => {
+    const files = parseChangedFiles(frontendDiff);
+    const groups = groupFiles(files);
+    expect(groups.frontend).toContain('src/ui/Button.tsx');
+    expect(groups.frontend).toContain('src/ui/styles.css');
+  });
+});