HTTP API: trace

Které větve a commity realizovaly úkol a kterému úkolu a milníku commit sloužil — odvozeno z gitu a z kanonického projektového modelu při každém volání, nikde se neukládá. Větev pojmenovává úkol, když je některá z jejích složek cesty identifikátorem úkolu; commit patří úkolu, jehož větve ho drží; commit, který žádná taková větev nedrží, se hlásí jako nepřiřazený, a ne vynechává, protože práce bez prováděcího kontraktu je přesně to, co má zpráva o dohledatelnosti zviditelnit. Pull requesty jsou fakt GitHubu a tento spustitelný soubor nevolá síť: čte je a k této odpovědi je připojuje podle názvu větve `scripts/traceability`.

Vykresleno z docs/generated/openapi.json, který spustitelný soubor generuje ze svého registru schopností a CI jej odmítne, je-li zastaralý. Surový dokument je na /openapi.json; běžící server servíruje stejný dokument na vlastní /openapi.json a Swagger UI na /swagger.

trasování

GET /api/v1/trace trace.report

Celý graf práce nad větví

Každý úkol, který jmenuje alespoň jedna větev, s jeho větvemi a commity, každý deklarovaný úkol, který nejmenuje žádná větev, a nejnovější úsek trunku s každým commitem přiřazeným úkolu, jehož větve jej drží, nebo ohlášeným jako nepřiřazený. Součty počítají obě strany, takže podíl trunku, který nezohledňuje žádný kontrakt provádění, je číslo, ne dojem. Čte se z gitu při každém volání: historie se mění mimo tento proces.

query
behaviorally_verified
vyžaduje se měření výkonu
cache vypnuta
nástroj MCP majordomus_traceability
zdroj MCP {"name": "traceability", "uri": "majordomus://traceability"}

Parametry dotazu

název	typ	povinné	popis	příklady
limit	integer (uint)	ne	Kolika commitům trunku přiřadit smlouvu, od nejnovějšího. Výchozí: 50. Cokoli nad 2000 se čte jako 2000 — report dohledatelnosti je čtení, ne export historie.	ten: 10

Vyzkoušejte

Port je ten, který server zalogoval; 8741 je ten, o který žádá jako první. Hodnoty jsou první příklad operace.

curl -s "http://127.0.0.1:8741/api/v1/trace?limit=10"

Testováno v apps/majordomus-cli/tests/http_serve.rs, který přehrává routu s těmito hodnotami proti serveru na skutečném socketu.

Odpovědi

status	tělo	význam
200	TraceReport	Celý graf práce nad větví: výsledek.
400	ErrorBody	`invalid_input`: Vstup neodpovídá schématu: parametr špatného typu, neznámý parametr nebo hodnota, kterou schopnost odmítne.
404	ErrorBody	`not_found`: Vstup pojmenovává něco, co repozitář nemá.
500	ErrorBody	`internal`: Schopnost selhala z vlastního důvodu; zpráva ho pojmenovává.
výchozí	ErrorBody	Jakékoli jiné selhání, které transport hlásí: 405 `method_not_allowed` pro jinou metodu na této cestě, 400 `invalid_input` pro tělo, které není objektem JSON.

GET /api/v1/trace/commit trace.commit

Jakému kontraktu tento commit sloužil

Jeden commit s úkolem a milníkem, kterým sloužil, nebo fakt, že žádný nelze najít. Přičtený, když ho drží větve právě jednoho úkolu, nejednoznačný, když ho drží větve pojmenovávající dva úkoly, a nepřičtený, když ho nedrží žádná větev pojmenovávající úkol — což je buď práce commitnutá bez kontraktu provedení, nebo větev smazaná po svém mergi, a odpověď to říká, místo aby mezi nimi hádala.

query
behaviorally_verified
vyžaduje se měření výkonu
cache vypnuta
nástroj MCP majordomus_trace_commit

Parametry dotazu

název	typ	povinné	popis	příklady
commit	string	ano	Cokoli, co git rozřeší na commit: plný nebo zkrácený název objektu, ref, `HEAD`, `master~3`.	head: "HEAD"

Vyzkoušejte

Port je ten, který server zalogoval; 8741 je ten, o který žádá jako první. Hodnoty jsou první příklad operace.

curl -s "http://127.0.0.1:8741/api/v1/trace/commit?commit=HEAD"

Testováno v apps/majordomus-cli/tests/http_serve.rs, který přehrává routu s těmito hodnotami proti serveru na skutečném socketu.

Odpovědi

status	tělo	význam
200	CommitAttribution	Jaké smlouvě tento commit sloužil: výsledek.
400	ErrorBody	`invalid_input`: Vstup neodpovídá schématu: parametr špatného typu, neznámý parametr nebo hodnota, kterou schopnost odmítne.
404	ErrorBody	`not_found`: Vstup pojmenovává něco, co repozitář nemá.
500	ErrorBody	`internal`: Schopnost selhala z vlastního důvodu; zpráva ho pojmenovává.
výchozí	ErrorBody	Jakékoli jiné selhání, které transport hlásí: 405 `method_not_allowed` pro jinou metodu na této cestě, 400 `invalid_input` pro tělo, které není objektem JSON.

GET /api/v1/trace/issue trace.issue

Co tento úkol realizovalo

Jeden úkol s větvemi, které ho pojmenovávají — lokálními i vzdálenými sledovacími, kde větev má už jen remote — a u každé s commity, které drží a trunk ne: měřeno proti trunku, dokud je větev otevřená, a proti prvnímu rodiči merge commitu, který ji přinesl, jakmile je mergnutá. Větev, která se dostala do trunku bez vlastního merge commitu, to říká a nic si nenárokuje, protože její commity nelze od trunkových rozeznat. Milník pochází z kanonického záznamu úkolu, což je jediná hrana, kterou git nedrží, a `declared` říká, zda projektový model toto id vůbec má — repozitář bez plánu stále dostane větve a překlep se stále nemůže číst jako práce, kterou nikdo neudělal.

query
behaviorally_verified
vyžaduje se měření výkonu
cache vypnuta
Nástroj MCP majordomus_trace_issue

Parametry dotazu

název	typ	povinné	popis	příklady
issue	string	ano	ID úkolu tak, jak jej píše projektový model (`I1305`). ID, které model nedeklaruje, se zodpoví `declared: false`, nezamítne se a neodpoví se holou prázdnou stopou: překlep čtený jako "nic tento úkol nerealizovalo" je jediná odpověď, kterou tato schopnost nesmí nikdy dát.	first-issue: "I0001"

Vyzkoušejte

Port je ten, který server zalogoval; 8741 je ten, o který žádá jako první. Hodnoty jsou první příklad operace.

curl -s "http://127.0.0.1:8741/api/v1/trace/issue?issue=I0001"

Testováno v apps/majordomus-cli/tests/http_serve.rs, který přehrává routu s těmito hodnotami proti serveru na skutečném socketu.

Odpovědi

status	tělo	význam
200	IssueTrace	Co realizovalo tento úkol: výsledek.
400	ErrorBody	`invalid_input`: Vstup neodpovídá schématu: parametr špatného typu, neznámý parametr nebo hodnota, kterou schopnost odmítne.
404	ErrorBody	`not_found`: Vstup pojmenovává něco, co repozitář nemá.
500	ErrorBody	`internal`: Schopnost selhala z vlastního důvodu; zpráva ho pojmenovává.
výchozí	ErrorBody	Jakékoli jiné selhání, které transport hlásí: 405 `method_not_allowed` pro jinou metodu na této cestě, 400 `invalid_input` pro tělo, které není objektem JSON.

Schémata

Komponenty, které používají jen operace tohoto tagu. Každý řádek je pole daného typu, jeho doc komentář je popis; typ vlastněný jinou stránkou na ni odkazuje.

Přiřazení

"attributed" | "unattributed" | "ambiguous"

Co je známo o kontraktu, kterému sloužil jeden commit.

attributedObsahují ho větve právě jednoho úkolu.
unattributedŽádná větev jmenující úkol jej neobsahuje.
ambiguousVětve jmenující více než jeden úkol jej obsahují.

Používá CommitAttribution

BranchTrace

object

Jedna větev, která jmenuje úkol, s commity, které drží.

vlastnost	typ	povinné	popis
název	string	ano	Ref, zkráceně: `feature/I1305-traceability`, nebo `origin/feature/I1305-traceability`, když ho má už jen vzdálený server.
remote	boolean	ano	Pravda, když je ref sledovaný vzdálený a žádná lokální větev stejného jména ho nezastupuje.
head	string	ano	Commit, na který ref ukazuje.
integrace	Integration → Integration	ano	Jak stojí vůči trunku.
merge_commit	string \| null	ne	Merge commit, který ji přinesl do trunku, pokud nějaký byl.
poznámka	string \| null	ne	Proč je seznam commitů takový, jaký je, když to stojí za větu.
commity	pole CommitRef → CommitRef	ano	Commity, které tato větev drží a trunk ne, nejnovější první, bez merge.

Používá IssueTrace

CommitAttribution

object

Jeden commit a smlouva, které sloužil, nebo fakt, že žádnou nelze najít.

vlastnost	typ	povinné	popis
commit	CommitRef → CommitRef	ano	Commit.
připsání	Attribution → Attribution	ano	Co je známo.
issue	string \| null	ne	Úkol, pokud si ho nárokuje právě jeden.
milestone	string \| null	ne	Milník, do kterého úkol patří, doplňuje volající, který má index.
úkoly	array of string	ano	Každý úkol, jehož větve jej obsahují: jeden, když je přiřazen, žádný, když není přiřazen, více než jeden, když je nejednoznačný.
branches	array of string	ano	Větve, které jej obsahují, pod názvy, které nesou jejich refs.
důvod	string	ano	Proč je verdikt takový, jaký je, v jednom řádku, podle kterého lze jednat.

Používá trace.commit TraceReport

CommitRef

object

Jeden commit, přesně tak, jak jej jmenuje git. Nic z toho se nikam neukládá: celý záznam se při každém volání čte znovu z databáze objektů.

vlastnost	typ	povinné	popis
id	string	ano	Úplný název objektu.
krátce	string	ano	Zkrácený název objektu, tak jak ho tento repozitář zkracuje.
autor	string	ano	Autor, jak jej commit zaznamenává.
datum	string	ano	Datum autora, ISO 8601, jak ho commit zaznamenává.
předmět	string	ano	Řádek předmětu.

Používá BranchTrace CommitAttribution

Integrace

"open" | "merged" | "absorbed" | "unknown"

Jak větev stojí vůči trunku, což rozhoduje, které commity jsou její vlastní.

openNení dosažitelné z trunku: jeho commity jsou ty, které trunk nemá.
mergedDosažitelné z trunku přes merge commit, který stopa jmenuje: jeho commity jsou ty, které tento merge přinesl.
absorbedDosažitelné z trunku bez vlastního merge commitu — fast-forward nebo rebase na něj. Jeho commity nelze od commitů trunku odlišit a žádné se nenárokují.
unknownKmen je neznámý, takže není s čím větev měřit.

Používá BranchTrace

IssueTrace

object

Vše, co git ví o realizaci jednoho úkolu.

vlastnost	typ	povinné	popis
issue	string	ano	Id úkolu tak, jak je píše model projektu.
deklarováno	boolean	ano	True, když model projektu deklaruje toto id. False není chyba ani prázdná odpověď: říká, že se id hledalo a model je nemá, což musí volající umět odlišit od „deklarováno a zatím to nic nerealizovalo“. Repozitář bez modelu projektu odpoví `false` pro každé id místo odmítnutí, protože větve jmenující id se tam dají odvodit i tak.
milestone	string \| null	ne	Milník, který pojmenovává kanonický záznam úkolu. Git tuto hranu nedrží a nic zde ji neodvozuje: doplňuje ji volající s indexem a v repozitáři, jehož záznam úkolu žádný nepojmenovává, je `null`.
trunk	string \| null	ne	Trunk, proti kterému se měřila každá branch.
branches	pole BranchTrace → BranchTrace	ano	Větve, které jej jmenují, lokální první.
commity	integer (uint)	ano	Kolik různých commitů mezi sebou větve drží.
dokončeno	boolean	ano	Pravda, když šlo odvodit commity každé větve. Nepravda, když alespoň jedna dosáhla trunku bez merge commitu, takže část práce nelze rozlišit.

Používá trace.issue TraceReport

TraceReport

object

Celá odpověď o dohledatelnosti: každý úkol, o kterém git může něco říct, a každý commit úseku trunku se smlouvou, které sloužil, nebo s faktem, že žádnou nemá.

vlastnost	typ	povinné	popis
trunk	string \| null	ne	Trunk, vůči kterému se měřila každá větev a commit.
zkoumáno	integer (uint)	ano	Kolik commitů trunku bylo přiřazeno.
úkoly	pole IssueTrace → IssueTrace	ano	Úkoly, které jmenuje alespoň jedna větev, v pořadí id.
without_branch	array of string	ano	Id úkolů, které model projektu deklaruje a žádný ref je nejmenuje. Není to závada: úkol, který nikdo nezačal, ještě nemá větev.
commity	pole CommitAttribution → CommitAttribution	ano	Zkoumané commity trunku, nejnovější první.
součty	TraceTallies → TraceTallies	ano	Počty, aby je volající nemusel sčítat.

Používá trace.report

TraceTallies

object

Počty jednoho reportu.

vlastnost	typ	povinné	popis
issues_declared	integer (uint)	ano	ID úkolů, která projektový model deklaruje.
issues_with_branch	integer (uint)	ano	Z nich ty, které jmenuje alespoň jeden ref.
branches	integer (uint)	ano	Větve jmenující úkol.
branch_commits	integer (uint)	ano	Odlišné commity, které tyto větve nárokují.
přisouzeno	integer (uint)	ano	Prozkoumané commity trunku s právě jedním úkolem.
nepřiřazeno	integer (uint)	ano	Prozkoumané commity trunku, které neobsahuje žádná větev jmenující úkol.
nejednoznačné	integer (uint)	ano	Prozkoumané commity trunku, které si nárokuje více než jeden úkol.

Používá TraceReport