${renderMarkdown(document.summary)}
`
- // Title, provenance, and summary are one opening, so they share one card. The layout
- // toggle lives in the sticky map instead: it is a reading control, wanted while
- // scrolled into a diff, and the card scrolls away.
+ // Title, provenance, attribution, and summary are one opening, so they share one card.
+ // The layout toggle lives in the sticky map instead: it is a reading control, wanted
+ // while scrolled into a diff, and the card scrolls away.
const markup = `
${reviewMap}
@@ -74,7 +75,7 @@ ${reviewMap}
@@ -108,7 +109,7 @@ export function renderHostedReport(
options: ReportOptions = {},
): string {
return renderShell(
- renderReportBody(document, options),
+ renderReportBody(document, options, true),
``,
``,
)
@@ -240,6 +241,28 @@ function sectionIndex(index: number): string {
return String(index + 1).padStart(2, '0')
}
+function renderAttribution(metadata: ExplainDocument['metadata'], hosted: boolean): string {
+ if (metadata === undefined) return ''
+ const rows: string[] = []
+ if (metadata.explainedBy !== undefined) {
+ rows.push(`Explained by ${escapeHtml(metadata.explainedBy)} `)
+ }
+ // A local preview or export must not claim a publisher or a publication time, even if
+ // a document somehow carries one. Only the review service renders those rows.
+ if (hosted && metadata.publishedBy !== undefined) {
+ rows.push(`Published by ${escapeHtml(metadata.publishedBy)} `)
+ }
+ if (hosted && metadata.publishedAt !== undefined) {
+ rows.push(`Published at ${escapeHtml(metadata.publishedAt)} `)
+ }
+ if (rows.length === 0) return ''
+ return `
+
+ From ${renderEndpoint(source.from)}
@@ -314,6 +337,17 @@ body {
.source-metadata dt { color: #7e8d82; font-weight: 600; text-transform: uppercase; letter-spacing: .08em; }
.source-metadata dd { margin: 0; min-width: 0; overflow: hidden; color: #4e5d53; text-overflow: ellipsis; white-space: nowrap; }
.source-metadata code { color: #263a2d; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; }
+.attribution-metadata {
+ display: grid;
+ grid-template-columns: max-content minmax(0, 1fr);
+ gap: 0 8px;
+ margin: 12px 0 0;
+ font-size: 11px;
+ line-height: 1.5;
+}
+.attribution-metadata dt { color: #7e8d82; font-weight: 600; text-transform: uppercase; letter-spacing: .08em; }
+.attribution-metadata dd { min-width: 0; margin: 0; color: #4e5d53; overflow-wrap: anywhere; }
+.attribution-note { margin: 6px 0 0; color: #7e8d82; font-size: 11px; font-style: italic; }
.review-controls {
display: grid;
gap: 8px;
diff --git a/test/authoring.test.ts b/test/authoring.test.ts
index 581d571..78b3916 100644
--- a/test/authoring.test.ts
+++ b/test/authoring.test.ts
@@ -452,6 +452,20 @@ describe('explain materialization', () => {
expect(duplicatedChangeIds(allChangesAssigned(capture))).toEqual([])
})
+ test('preserves the authored explainedBy attribution and omits absent metadata', () => {
+ const capture = captureWithTwoChanges()
+
+ const attributed = {
+ ...allChangesAssigned(capture),
+ metadata: { explainedBy: 'Claude Code' },
+ }
+ expect(materializeExplainDocument(capture, attributed).metadata).toEqual({
+ explainedBy: 'Claude Code',
+ })
+
+ expect(materializeExplainDocument(capture, allChangesAssigned(capture)).metadata).toBeUndefined()
+ })
+
test('rejects a change block that no longer matches captured content', () => {
const capture = captureWithTwoChanges()
const explanations = allChangesAssigned(capture)
diff --git a/test/cli.test.ts b/test/cli.test.ts
index fedc35b..12b12c1 100644
--- a/test/cli.test.ts
+++ b/test/cli.test.ts
@@ -1053,6 +1053,46 @@ describe('JSON export', () => {
})
})
+describe('author attribution', () => {
+ async function authorWithAttribution(repo: string) {
+ await runCli(['inspect'], repo)
+ await authorEveryChange(repo)
+ await writeExplanations(
+ repo,
+ (await readExplanationsYaml(repo)).replace(
+ 'title: A change set',
+ 'title: A change set\nmetadata:\n explainedBy: Claude Code',
+ ),
+ )
+ }
+
+ test('retains explainedBy in the JSON export', async () => {
+ const repo = await fixtureRepo()
+ await authorWithAttribution(repo)
+ const output = join(repo, 'out', 'document.json')
+
+ const result = await runCli(['export', 'json', '--output', output], repo)
+
+ expect(result.exitCode).toBe(0)
+ const document = JSON.parse(await readFile(output, 'utf8')) as { metadata?: unknown }
+ expect(document.metadata).toEqual({ explainedBy: 'Claude Code' })
+ })
+
+ test('displays explainedBy locally without claiming a publisher or time', async () => {
+ const repo = await fixtureRepo()
+ await authorWithAttribution(repo)
+ const output = join(repo, 'out', 'report.html')
+
+ const result = await runCli(['export', 'html', '--output', output], repo)
+
+ expect(result.exitCode).toBe(0)
+ const html = await readFile(output, 'utf8')
+ expect(html).toContain('Explained by Claude Code ')
+ expect(html).not.toContain('Published by')
+ expect(html).not.toContain('Published at')
+ })
+})
+
interface FakeService {
origin: string
published: unknown[]
@@ -1142,6 +1182,62 @@ describe('publish', () => {
}
})
+ test('adds the Git user name without rewriting the authoring files', async () => {
+ const repo = await fixtureRepo()
+ await runCli(['inspect'], repo)
+ await authorEveryChange(repo)
+ await writeExplanations(
+ repo,
+ (await readExplanationsYaml(repo)).replace(
+ 'title: A change set',
+ 'title: A change set\nmetadata:\n explainedBy: Claude Code',
+ ),
+ )
+ const explanationsPath = join(await currentWalkDir(repo), 'explanations.yaml')
+ const capturePath = join(await currentWalkDir(repo), 'capture.json')
+ const explanationsBefore = await readFile(explanationsPath, 'utf8')
+ const captureBefore = await readFile(capturePath, 'utf8')
+ const service = startFakeService()
+
+ try {
+ const result = await runCli(['publish', '--service', service.origin], repo)
+
+ expect(result.exitCode).toBe(0)
+ const uploaded = service.published[0] as { metadata?: Record }
+ expect(uploaded.metadata).toEqual({ explainedBy: 'Claude Code', publishedBy: 'Test' })
+ expect(JSON.stringify(uploaded)).not.toContain('test@example.com')
+ expect(await readFile(explanationsPath, 'utf8')).toBe(explanationsBefore)
+ expect(await readFile(capturePath, 'utf8')).toBe(captureBefore)
+ } finally {
+ service.stop()
+ }
+ })
+
+ test('omits the publisher when Git has no user name', async () => {
+ const repo = await fixtureRepo()
+ await runCli(['inspect'], repo)
+ await authorEveryChange(repo)
+ await writeExplanations(
+ repo,
+ (await readExplanationsYaml(repo)).replace(
+ 'title: A change set',
+ 'title: A change set\nmetadata:\n explainedBy: Claude Code',
+ ),
+ )
+ await git(['config', 'user.name', ''], repo)
+ const service = startFakeService()
+
+ try {
+ const result = await runCli(['publish', '--service', service.origin], repo)
+
+ expect(result.exitCode).toBe(0)
+ const uploaded = service.published[0] as { metadata?: unknown }
+ expect(uploaded.metadata).toEqual({ explainedBy: 'Claude Code' })
+ } finally {
+ service.stop()
+ }
+ })
+
test('publishing without authored explanations fails before contacting the service', async () => {
const repo = await fixtureRepo()
await runCli(['inspect'], repo)
diff --git a/test/explanations.test.ts b/test/explanations.test.ts
index fe25e15..ab76ad2 100644
--- a/test/explanations.test.ts
+++ b/test/explanations.test.ts
@@ -181,4 +181,28 @@ sections: []
`),
).toThrow()
})
+
+ test('parses an optional explainedBy attribution author', () => {
+ const explanations = parseExplanations(`${head}metadata:
+ explainedBy: Claude Code
+sections: []
+`)
+
+ expect(explanations.metadata).toEqual({ explainedBy: 'Claude Code' })
+ })
+
+ test('omits author metadata when the file does not name one', () => {
+ expect(parseExplanations(`${head}sections: []\n`).metadata).toBeUndefined()
+ })
+
+ test('rejects metadata keys the authoring file must not set', () => {
+ for (const body of [
+ `metadata:\n publishedBy: Art\n`,
+ `metadata:\n publishedAt: "2026-09-02T06:10:00.000Z"\n`,
+ `metadata:\n explainedBy: Claude Code\n extra: nope\n`,
+ `metadata:\n explainedBy: 7\n`,
+ ]) {
+ expect(() => parseExplanations(`${head}${body}sections: []\n`)).toThrow()
+ }
+ })
})
diff --git a/test/format.test.ts b/test/format.test.ts
index eb4eaa0..2056ab6 100644
--- a/test/format.test.ts
+++ b/test/format.test.ts
@@ -222,6 +222,65 @@ describe('document source variants', () => {
})
})
+describe('document metadata', () => {
+ function attributed(metadata: unknown): unknown {
+ return {
+ formatVersion: 1,
+ title: 'Attribution',
+ source: proposalSource,
+ metadata,
+ sections: [{ title: 'Attribution', steps: [{ text: 'Text.', diff: diff() }] }],
+ }
+ }
+
+ test('accepts full, partial, and absent attribution metadata', () => {
+ const full = explainDocumentSchema.parse(
+ attributed({
+ explainedBy: 'Claude Code',
+ publishedBy: 'Art',
+ publishedAt: '2026-09-02T06:10:00.000Z',
+ }),
+ )
+ expect(full.metadata).toEqual({
+ explainedBy: 'Claude Code',
+ publishedBy: 'Art',
+ publishedAt: '2026-09-02T06:10:00.000Z',
+ })
+
+ for (const metadata of [
+ { explainedBy: 'Claude Code' },
+ { publishedBy: 'Art' },
+ { publishedAt: '2026-09-02T06:10:00.000Z' },
+ {},
+ ]) {
+ expect(explainDocumentSchema.parse(attributed(metadata)).metadata).toEqual(metadata)
+ }
+
+ expect(explainDocumentSchema.parse(attributed(undefined)).metadata).toBeUndefined()
+ expect(explainDocumentSchema.parse(attributed({})).metadata).toEqual({})
+ })
+
+ test('rejects unknown metadata keys and malformed values', () => {
+ for (const metadata of [
+ { explainedBy: 'Claude Code', extra: 'nope' },
+ { explainedBy: '' },
+ { publishedBy: 7 },
+ { publishedAt: 'yesterday' },
+ { publishedAt: '2026-09-02' },
+ 'not an object',
+ ]) {
+ expect(() => explainDocumentSchema.parse(attributed(metadata))).toThrow()
+ }
+ })
+
+ test('round-trips attribution metadata through JSON', () => {
+ const document = explainDocumentSchema.parse(
+ attributed({ explainedBy: 'Claude Code', publishedBy: 'Art' }),
+ )
+ expect(explainDocumentSchema.parse(JSON.parse(JSON.stringify(document)))).toEqual(document)
+ })
+})
+
describe('capture schema', () => {
test('accepts the machine-owned capture shape with no sections', () => {
const parsed = captureSchema.parse(capture)
@@ -378,4 +437,30 @@ describe('explanations schema', () => {
}),
).toThrow()
})
+
+ test('accepts an optional explainedBy author and nothing else', () => {
+ const withAuthor = explanationsSchema.parse({
+ captureId: 'x',
+ title: 'x',
+ metadata: { explainedBy: 'Claude Code' },
+ sections: [],
+ })
+ expect(withAuthor.metadata).toEqual({ explainedBy: 'Claude Code' })
+ expect(
+ explanationsSchema.parse({ captureId: 'x', title: 'x', sections: [] }).metadata,
+ ).toBeUndefined()
+
+ // publishedBy and publishedAt are supplied by other layers, so the authoring file
+ // rejects them instead of silently dropping authored data.
+ for (const metadata of [
+ { publishedBy: 'Art' },
+ { publishedAt: '2026-09-02T06:10:00.000Z' },
+ { explainedBy: 'Claude Code', extra: 'nope' },
+ { explainedBy: '' },
+ ]) {
+ expect(() =>
+ explanationsSchema.parse({ captureId: 'x', title: 'x', metadata, sections: [] }),
+ ).toThrow()
+ }
+ })
})
diff --git a/test/git.test.ts b/test/git.test.ts
index 222225a..6b00620 100644
--- a/test/git.test.ts
+++ b/test/git.test.ts
@@ -2,7 +2,7 @@ import { afterEach, describe, expect, test } from 'bun:test'
import { chmod, mkdir, mkdtemp, rename, rm, symlink, unlink, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
-import { captureGitChanges, captureGitRevisionChanges } from '../src/authoring/git'
+import { captureGitChanges, captureGitRevisionChanges, gitUserName } from '../src/authoring/git'
const directories: string[] = []
@@ -712,6 +712,48 @@ describe('captureGitChanges selection', () => {
})
})
+describe('gitUserName', () => {
+ test('reads the configured Git user name', async () => {
+ const directory = await mkdtemp(join(tmpdir(), 'diffwalk-git-'))
+ directories.push(directory)
+ await initializeRepository(directory)
+
+ expect(await gitUserName(directory)).toBe('Test')
+ })
+
+ test('returns undefined when Git has no user name to report', async () => {
+ const directory = await mkdtemp(join(tmpdir(), 'diffwalk-git-'))
+ directories.push(directory)
+ await initializeRepository(directory)
+ await git(['config', 'user.name', ''], directory)
+
+ expect(await gitUserName(directory)).toBeUndefined()
+ })
+
+ test('returns undefined instead of throwing when the config cannot be read', async () => {
+ const directory = await mkdtemp(join(tmpdir(), 'diffwalk-git-'))
+ directories.push(directory)
+ await git(['init', '-q'], directory)
+ const previous = {
+ global: process.env['GIT_CONFIG_GLOBAL'],
+ system: process.env['GIT_CONFIG_SYSTEM'],
+ }
+ process.env['GIT_CONFIG_GLOBAL'] = '/dev/null'
+ process.env['GIT_CONFIG_SYSTEM'] = '/dev/null'
+ try {
+ expect(await gitUserName(directory)).toBeUndefined()
+ } finally {
+ for (const [key, value] of [
+ ['GIT_CONFIG_GLOBAL', previous.global],
+ ['GIT_CONFIG_SYSTEM', previous.system],
+ ] as const) {
+ if (value === undefined) delete process.env[key]
+ else process.env[key] = value
+ }
+ }
+ })
+})
+
async function initializeRepository(directory: string) {
await git(['init', '-q'], directory)
await git(['config', 'user.name', 'Test'], directory)
diff --git a/test/publish.test.ts b/test/publish.test.ts
index 7b2f32e..ebc0f7f 100644
--- a/test/publish.test.ts
+++ b/test/publish.test.ts
@@ -1,6 +1,12 @@
import { afterEach, describe, expect, test } from 'bun:test'
import type { ExplainDocument } from '../src/format'
-import { publishDocument, reportService, unpublishDocument, updateDocument } from '../src/publish'
+import {
+ publishDocument,
+ reportService,
+ unpublishDocument,
+ updateDocument,
+ withPublisher,
+} from '../src/publish'
const originalFetch = globalThis.fetch
const originalEnvironment = { ...process.env }
@@ -85,6 +91,25 @@ describe('reportService', () => {
})
})
+describe('withPublisher', () => {
+ test('adds the Git user name beside the authored author without mutating the source', () => {
+ const authored: ExplainDocument = {
+ ...document,
+ metadata: { explainedBy: 'Claude Code' },
+ }
+
+ const outgoing = withPublisher(authored, 'Art')
+
+ expect(outgoing.metadata).toEqual({ explainedBy: 'Claude Code', publishedBy: 'Art' })
+ expect(authored.metadata).toEqual({ explainedBy: 'Claude Code' })
+ expect(outgoing.sections).toBe(authored.sections)
+ })
+
+ test('returns the document unchanged when Git has no user name', () => {
+ expect(withPublisher(document, undefined)).toBe(document)
+ })
+})
+
describe('publishDocument', () => {
test('sends the document as anonymous JSON and returns the report', async () => {
const calls = stubFetch(() => json(201, { id: 'abc', revocationToken: 'revoke-me' }))
diff --git a/test/report.test.ts b/test/report.test.ts
index c79eed7..eb19c2f 100644
--- a/test/report.test.ts
+++ b/test/report.test.ts
@@ -5,7 +5,7 @@ import { join } from 'node:path'
import type { ExplainDocument } from '../src/format'
import { renderMarkdown } from '../src/report/markdown'
import { fileDiffStats, parseSectionPatch } from '../src/report/patches'
-import { loadReportClient, renderReport, writeReport } from '../src/report'
+import { loadReportClient, renderHostedReport, renderReport, writeReport } from '../src/report'
import { reportTargets } from '../src/report/targets'
const directories: string[] = []
@@ -756,3 +756,92 @@ describe('writeReport', () => {
expect((await readdir(directory)).filter((name) => name.endsWith('.tmp'))).toEqual([])
})
})
+
+describe('attribution metadata', () => {
+ const assets = { stylesHref: '/report.css', clientSrc: '/report-client.js' }
+
+ function attributed(metadata: ExplainDocument['metadata']): ExplainDocument {
+ return { ...document([section(simplePatch(), 'Plain')]), metadata }
+ }
+
+ test('a hosted report shows the author, publisher, and publication time', () => {
+ const html = renderHostedReport(
+ attributed({
+ explainedBy: 'Claude Code',
+ publishedBy: 'Art',
+ publishedAt: '2026-09-02T06:10:00.000Z',
+ }),
+ assets,
+ )
+
+ expect(html).toContain('Explained by Claude Code ')
+ expect(html).toContain('Published by Art ')
+ expect(html).toContain('Published at 2026-09-02T06:10:00.000Z ')
+ expect(html).toContain('class="attribution-note"')
+ expect(html).toContain('self-reported attribution, not verified identity')
+ })
+
+ test('a local report keeps the author but never claims a publisher or time', () => {
+ const html = renderReport(
+ attributed({
+ explainedBy: 'Claude Code',
+ publishedBy: 'Art',
+ publishedAt: '2026-09-02T06:10:00.000Z',
+ }),
+ stubClient,
+ )
+
+ expect(html).toContain('Explained by Claude Code ')
+ expect(html).not.toContain('Published by')
+ expect(html).not.toContain('Published at')
+ expect(html).not.toContain('Art ')
+ })
+
+ test('partial metadata renders only the rows that are present', () => {
+ const authorOnly = renderHostedReport(attributed({ explainedBy: 'Claude Code' }), assets)
+ expect(authorOnly).toContain('Explained by ')
+ expect(authorOnly).not.toContain('Published by ')
+ expect(authorOnly).not.toContain('Published at ')
+
+ const timeOnly = renderHostedReport(attributed({ publishedAt: '2026-09-02T06:10:00.000Z' }), assets)
+ expect(timeOnly).toContain('Published at ')
+ expect(timeOnly).not.toContain('Explained by ')
+ expect(timeOnly).not.toContain('Published by ')
+ })
+
+ test('absent metadata adds no attribution markup at all', () => {
+ const html = renderHostedReport(document([section(simplePatch(), 'Plain')]), assets)
+
+ expect(html).not.toContain('attribution-metadata')
+ expect(html).not.toContain('attribution-note')
+ expect(html).not.toContain('Explained by')
+ })
+
+ test('local output with only service fields renders no attribution block', () => {
+ const html = renderReport(
+ attributed({ publishedBy: 'Art', publishedAt: '2026-09-02T06:10:00.000Z' }),
+ stubClient,
+ )
+
+ expect(html).not.toContain('
The names are self-reported attribution, not verified identity.
` +} + function renderSourceMetadata(source: ExplainDocument['source']): string { if (source.kind === 'commit-diff') { return `- ')
+ expect(html).not.toContain('Published by')
+ expect(html).not.toContain('Published at')
+ })
+
+ test('attribution values are escaped', () => {
+ const html = renderHostedReport(
+ attributed({
+ explainedBy: '',
+ publishedBy: '