Phase 141: author HTTP route full parity

POST /analysis/author now accepts since, detail, includeCommits, hybrid,
and bm25Weight, threaded through to the same computeAuthorContributions/
hybridSearch/searchCommits logic the CLI author command uses. Also accepts
chunks/level/vss for flag-surface parity (deliberately no-op, matching the
CLI's own dead-flag behavior for these three). Model-override triplet
stays out of scope (tracked separately in Phase 140).

Breaking change: response shape is now { authors, commits? } instead of a
bare array, to carry includeCommits results, per parity.md's parity-over-
API-stability rule.

Author: claude

.changeset/author-http-route-parity.md

@@ -0,0 +1,5 @@
+---
+"gitsema": minor
+---
+
+`POST /analysis/author` (HTTP API) now supports the full `gitsema author` CLI flag surface: `since`, `detail`, `includeCommits`, `hybrid`, and `bm25Weight` are wired through to the same author-attribution logic the CLI uses, plus `chunks`/`level`/`vss` are accepted for flag-surface parity (no-op, matching the CLI's own behavior for these three). Breaking change: the response shape is now `{ authors, commits? }` instead of a bare array, to carry `includeCommits` results.

docs/PLAN.md

@@ -5439,7 +5439,21 @@ Update `docs/parity.md`, `docs/features.md`, `README.md`.
 `src/core/search/authorSearch.ts` (or wherever author attribution lives),
 `docs/parity.md`, test files.
 
-**Status:** not started.
+**Status:** ✅ complete. `AuthorBodySchema` in `src/server/routes/analysis.ts`
+gained `since`, `detail`, `includeCommits`, `hybrid`, `bm25Weight` (all
+threaded through to `computeAuthorContributions`/`hybridSearch`/
+`searchCommits`, mirroring `src/cli/commands/author.ts` exactly) plus
+`chunks`/`level`/`vss` for flag-surface parity — these three are accepted
+but deliberately not wired to anything, matching the CLI's own dead-flag
+behavior (`computeAuthorContributions` is blob-level only; the CLI's
+`--vss` on `author` is itself just a warn-and-ignore no-op). Model-override
+triplet (`model`/`textModel`/`codeModel`) intentionally excluded — tracked
+separately in Phase 140. **Deviation from spec:** response shape changed
+from a bare `AuthorContribution[]` array to `{ authors, commits? }` (the
+`commits` key populated only when `includeCommits` is set) — a breaking
+change, taken deliberately per `docs/parity.md` §4's "parity over API
+response stability" rule, since a bare array had no room for
+`includeCommits`'s second result set.
 
 ---
 

docs/features.md

@@ -250,7 +250,7 @@ Start with `gitsema tools serve [--port n] [--key token] [--ui]`.
 | `GET /api/v1/remote/jobs/metrics`, `GET /api/v1/remote/jobs/:id/progress` | Job progress |
 | `POST /api/v1/analysis/clusters` | Clustering |
 | `POST /api/v1/analysis/change-points` | Change-point detection |
-| `POST /api/v1/analysis/author` | Author attribution |
+| `POST /api/v1/analysis/author` | Author attribution — full CLI flag parity (Phase 141): `since`, `detail`, `includeCommits`, `hybrid`, `bm25Weight` all wired through; response is `{ authors, commits? }` |
 | `POST /api/v1/analysis/impact` | Impact analysis |
 | `POST /api/v1/analysis/semantic-diff` | Semantic diff |
 | `POST /api/v1/analysis/semantic-blame` | Semantic blame |

docs/parity.md

@@ -323,6 +323,11 @@ This table shows less common flags used by specific commands or command groups.
 | `--sort-by-date` | `search-history` (MCP only) | bool | false | Sort by first-seen date instead of score |
 | `--include-content` | `evolution`, `concept-evolution` | bool | false | Add stored file text in JSON output |
 | `--include-commits` | `first-seen` | bool | false | Also search commit messages |
+| `--since` | `author` | date | — | Only consider contributions since this date (HTTP: also accepted by `POST /analysis/author`, Phase 141) |
+| `--detail` | `author` | bool | false | Include per-blob contribution detail (HTTP: also accepted by `POST /analysis/author`, Phase 141) |
+| `--hybrid` | `author` | bool | false | Use hybrid (vector + BM25) candidate selection (HTTP: also accepted by `POST /analysis/author`, Phase 141) |
+| `--bm25-weight` | `author` | float | 0.3 | BM25 weight when `--hybrid` is set (HTTP: also accepted by `POST /analysis/author`, Phase 141) |
+| `--chunks` / `--level` / `--vss` | `author` | bool/enum/bool | false/—/false | Declared on the CLI but not wired to anything in `computeAuthorContributions` (blob-level only); `--vss` prints a warning and is ignored. HTTP's `POST /analysis/author` accepts all three for flag-surface parity with the same no-op behavior (Phase 141) — not a gap, a documented CLI limitation mirrored intentionally. |
 
 ### 2.3 Flag Coherence Issues
 
@@ -535,7 +540,15 @@ this section's prior open-ended bullets into concrete, numbered
 - **Phase 140:** systemic `--model`/`--text-model`/`--code-model` gap
   across `analysis.ts` HTTP routes (one shared fix, not 8 per-route ones).
 - **Phase 141:** `author` HTTP route full parity (largest single-command
-  gap found).
+  gap found). ✅ done — `POST /analysis/author` now accepts `since`,
+  `detail`, `includeCommits`, `hybrid`, `bm25Weight` (all wired to
+  `computeAuthorContributions`/`hybridSearch`/`searchCommits`, mirroring the
+  CLI `author` command exactly) plus `chunks`/`level`/`vss` for flag-surface
+  parity (accepted, no-op — matching the CLI's own dead-flag behavior for
+  these three). Response shape changed from a bare array to `{ authors,
+  commits? }` (breaking change, per §4's parity-over-stability rule) to
+  carry `includeCommits` results. Model-override triplet intentionally
+  excluded — tracked separately in Phase 140.
 - **Phase 142:** `workflow` HTTP route parity — 3/8 templates exposed
   today, all 8 on CLI.
 - **Phase 143:** analysis-route small-fixes bundle (merge-audit,

src/server/routes/analysis.ts

@@ -15,6 +15,8 @@ import type { Embedding } from '../../core/models/types.js'
 import { computeClusters, getBlobHashesOnBranch } from '../../core/search/clustering/clustering.js'
 import { computeConceptChangePoints } from '../../core/search/temporal/changePoints.js'
 import { computeAuthorContributions } from '../../core/search/authorSearch.js'
+import { hybridSearch } from '../../core/search/analysis/hybridSearch.js'
+import { searchCommits } from '../../core/search/commitSearch.js'
 import { computeExperts } from '../../core/search/experts.js'
 import { computeImpact } from '../../core/search/impact.js'
 import { parseDateArg } from '../../core/search/temporal/timeSearch.js'
@@ -57,6 +59,19 @@ const AuthorBodySchema = z.object({
   topK: z.number().int().positive().optional().default(50),
   topAuthors: z.number().int().positive().optional().default(10),
   branch: z.string().optional(),
+  since: z.string().optional(),
+  detail: z.boolean().optional().default(false),
+  includeCommits: z.boolean().optional().default(false),
+  hybrid: z.boolean().optional().default(false),
+  bm25Weight: z.number().min(0).max(1).optional().default(0.3),
+  // `chunks`/`level`/`vss` are accepted for CLI flag-surface parity but are
+  // not wired to anything — `computeAuthorContributions` is blob-level only,
+  // and the CLI's `author` command itself treats these three the same way
+  // (declared flags with no effect on results; `--vss` just prints a
+  // warning). See docs/parity.md for the audit note.
+  chunks: z.boolean().optional().default(false),
+  level: z.enum(['file', 'chunk', 'symbol']).optional(),
+  vss: z.boolean().optional().default(false),
 })
 
 const ImpactBodySchema = z.object({
@@ -139,6 +154,15 @@ export function analysisRouter(deps: AnalysisRouterDeps): Router {
       return
     }
     const opts = parsed.data
+
+    let since: number | undefined
+    try {
+      if (opts.since) since = parseDateArg(opts.since)
+    } catch (err) {
+      res.status(400).json({ error: `Date parse error: ${err instanceof Error ? err.message : String(err)}` })
+      return
+    }
+
     let queryEmbedding: Embedding
     try {
       queryEmbedding = await textProvider.embed(opts.query)
@@ -147,12 +171,35 @@ export function analysisRouter(deps: AnalysisRouterDeps): Router {
       return
     }
     try {
+      // Mirrors the CLI `author` command (src/cli/commands/author.ts): when
+      // --hybrid is set, use hybridSearch to get pre-scored candidate blobs
+      // instead of scoring the whole embeddings table by cosine similarity.
+      let candidateBlobs: Array<{ blobHash: string; score: number }> | undefined
+      if (opts.hybrid) {
+        const hybridResults = await hybridSearch(opts.query, queryEmbedding, {
+          topK: 50,
+          bm25Weight: opts.bm25Weight,
+          branch: opts.branch,
+        })
+        candidateBlobs = hybridResults.map((r) => ({ blobHash: r.blobHash, score: r.score }))
+      }
+
       const contributions = await computeAuthorContributions(queryEmbedding, {
         topK: opts.topK,
         topAuthors: opts.topAuthors,
         branch: opts.branch,
+        since,
+        detail: opts.detail,
+        candidateBlobs,
       })
-      res.json(contributions)
+
+      if (opts.includeCommits) {
+        const commitResults = await searchCommits(queryEmbedding, { topK: opts.topK, model: textProvider.model })
+        res.json({ authors: contributions, commits: commitResults })
+        return
+      }
+
+      res.json({ authors: contributions })
     } catch (err) {
       res.status(500).json({ error: err instanceof Error ? err.message : String(err) })
     }

tests/serverRoutes.test.ts

@@ -562,12 +562,70 @@ describe('POST /api/v1/analysis/author', () => {
     expect(res.status).toBe(400)
   })
 
-  it('returns 200 with contributions structure (empty DB)', async () => {
+  it('returns 200 with { authors } structure (empty DB)', async () => {
     const res = await request(app)
       .post('/api/v1/analysis/author')
       .send({ query: 'authentication' })
     expect(res.status).toBe(200)
     expect(typeof res.body).toBe('object')
+    expect(Array.isArray(res.body.authors)).toBe(true)
+    expect(res.body.authors.length).toBe(0)
+    expect(res.body.commits).toBeUndefined()
+  })
+
+  it('accepts --since (Phase 141) and returns 200 with a valid date', async () => {
+    const res = await request(app)
+      .post('/api/v1/analysis/author')
+      .send({ query: 'authentication', since: '2020-01-01' })
+    expect(res.status).toBe(200)
+    expect(Array.isArray(res.body.authors)).toBe(true)
+  })
+
+  it('returns 400 for an unparseable --since value', async () => {
+    const res = await request(app)
+      .post('/api/v1/analysis/author')
+      .send({ query: 'authentication', since: 'not-a-date-at-all-!!' })
+    expect(res.status).toBe(400)
+  })
+
+  it('accepts --detail (Phase 141) without error', async () => {
+    const res = await request(app)
+      .post('/api/v1/analysis/author')
+      .send({ query: 'authentication', detail: true })
+    expect(res.status).toBe(200)
+    expect(Array.isArray(res.body.authors)).toBe(true)
+  })
+
+  it('accepts --hybrid + --bm25-weight (Phase 141) without error', async () => {
+    const res = await request(app)
+      .post('/api/v1/analysis/author')
+      .send({ query: 'authentication', hybrid: true, bm25Weight: 0.5 })
+    expect(res.status).toBe(200)
+    expect(Array.isArray(res.body.authors)).toBe(true)
+  })
+
+  it('accepts --include-commits (Phase 141) and returns a commits array', async () => {
+    const res = await request(app)
+      .post('/api/v1/analysis/author')
+      .send({ query: 'authentication', includeCommits: true })
+    expect(res.status).toBe(200)
+    expect(Array.isArray(res.body.authors)).toBe(true)
+    expect(Array.isArray(res.body.commits)).toBe(true)
+  })
+
+  it('accepts chunks/level/vss (Phase 141 flag-surface parity, no-op like the CLI)', async () => {
+    const res = await request(app)
+      .post('/api/v1/analysis/author')
+      .send({ query: 'authentication', chunks: true, level: 'symbol', vss: true })
+    expect(res.status).toBe(200)
+    expect(Array.isArray(res.body.authors)).toBe(true)
+  })
+
+  it('returns 400 for an invalid level enum value', async () => {
+    const res = await request(app)
+      .post('/api/v1/analysis/author')
+      .send({ query: 'authentication', level: 'not-a-real-level' })
+    expect(res.status).toBe(400)
   })
 })