Generated from the .d.ts files published in guardlink@2.2.0. Report problems against guardlink, not this page.

blame

Everything exported by guardlink/blame, from the .d.ts files published in guardlink@2.2.0. See the entry points for the other subpaths, and use guardlink as a library for worked examples.

Interfaces

AgentSummaryRow

The analytics every summary row carries beyond its counts.

Extends

SummaryRowRates

Properties

Property	Type	Description	Inherited from
`commits`	`number` \| `null`	Commits crediting this identity in the whole history; null when no counts were supplied.	`SummaryRowRates`.`commits`
`fixed`	`number`	-	-
`introduced`	`number`	-	-
`lines`	`number`	-	-
`median_time_to_fix_days`	`number` \| `null`	-	-
`model`	`string` \| `null`	-	-
`oldest_open_days`	`number` \| `null`	Whole days from the oldest open introduced exposure’s date to `as_of`; null when nothing is open or there is no as_of.	`SummaryRowRates`.`oldest_open_days`
`open`	`number`	-	-
`per_100_commits`	`number` \| `null`	introduced / commits × 100, one decimal; null when commits is null or 0.	`SummaryRowRates`.`per_100_commits`
`risk_score`	`number`	Over the exposures this identity introduced that are still open: critical 8, high 4, medium 2, low 1, anything else 1 (`P0..P3` alike, case-insensitively).	`SummaryRowRates`.`risk_score`
`tool`	`string`	-	-
`touched`	`number`	-	-

AiAttribution

One AI tool credited on a commit, from a trailer or a bot author identity.

Properties

Property	Type	Description
`model`	`string` \| `null`	Model name when the convention carries one, e.g. `Claude Opus 5 (1M context)`.
`raw`	`string`	The trailer value or author string this was derived from, verbatim.
`tool`	`string`	Rule id, e.g. `claude-code`, `copilot`; `unknown` only for an unparseable `Assisted-by:`.

BlameComputation

Properties

Property	Type	Description
`as_of`	`string` \| `null`	The HEAD commit’s author date — “now” for every age in the summary, so two runs on one HEAD agree. Null without git or when the walk was skipped.
`byRecord`	`Map`<`object`, `RecordBlame`>	Keyed by the model record object itself; never written back unless `attachBlame` is asked to.
`commits`	`CommitCounts` \| `null`	Null without git or when the walk was skipped (`history: false`).
`head`	`string` \| `null`	-
`identity_mode`	`IdentityMode`	-
`status`	`ComputationStatus`	-

BlameConfig

Properties

Property	Type	Description
`identity`	`IdentityMode`	-
`ignore_revs`	`string` \| `null`	Root-relative path handed to `git blame --ignore-revs-file` when it exists; null when unset or outside root.
`tools`	`ToolRule`[]	User rules first, then the shipped defaults. First match wins.

BlameEntry

Properties

Property	Type	Description
`asset`	`string`	-
`blame`	`RecordBlame`	-
`file`	`string`	-
`granularity`	`BlameGranularity`	-
`key`	`string`	The ledger claim key, so this joins to `.guardlink/verified.json`.
`line`	`number`	-
`severity`	`string` \| `null`	-
`span`	`string` \| `null`	`file#start-end` of the anchored span, `file#file` for a file-wide anchor, null without one. Claims sharing a span share its lines.
`threat`	`string`	-
`verb`	`BlameVerb`	-

BlamePayload

Properties

Property	Type
`entries`	`BlameEntry`[]
`head`	`string` \| `null`
`identity_mode`	`IdentityMode`
`root`	`string`
`schema`	`"guardlink.blame/v1"`
`status`	`ComputationStatus`
`summary`	`BlameSummary`

BlameSummary

Properties

Property	Type	Description
`as_of`	`string` \| `null`	The instant every age was measured against: the HEAD commit’s author date. Null without one.
`by_agent`	`AgentSummaryRow`[]	-
`by_human`	`HumanSummaryRow`[]	-
`comparison`	{ `ai`: `Cohort`; `human`: `Cohort`; } \| `null`	Null when no commit counts were available to divide by.
`hot_files`	`HotFile`[]	Hottest first: open desc, contributors desc, file asc; at most ten.
`trends`	`TrendBucket`[]	-

Cohort

Exposures whose introducing commit credits no AI tool (human) versus at least one (ai).

Properties

Property	Type	Description
`commits`	`number`	-
`fixed`	`number`	-
`introduced`	`number`	-
`median_time_to_fix_days`	`number` \| `null`	-
`open`	`number`	-
`per_100_commits`	`number` \| `null`	introduced / commits × 100, one decimal; null when commits is 0.

CommitCounts

Commit counts over the history reachable from HEAD, the denominator of every “per 100 commits” rate. Attributed with the same rules and identity mode as the records, so an identity key here is the same string the rows carry.

Properties

Property	Type	Description
`ai_assisted`	`number`	Commits that credit at least one AI tool (author bot or trailer).
`by_agent`	`Record`<`string`, { `commits`: `number`; `model`: `string` \| `null`; `tool`: `string`; }>	Commits credited to each AI tool+model, key `${tool} ${model ?? ''}` → { tool, model, commits }.
`by_human`	`Record`<`string`, `number`>	Commits credited to each human identity (author or human co-author), identity string → count.
`total`	`number`	Commits in the whole history.

CommitRef

Extended by

Properties

Property	Type	Description
`assisted_by`	`AiAttribution`[]	-
`author`	`string`	`human:<identity>` — or `agent:<tool>` when a bot authored the commit and no human co-author exists.
`co_authors`	`string`[]	Human co-authors from `Co-authored-by` trailers that matched no tool rule.
`date`	`string`	Author date, ISO-8601 as git prints `%aI`.
`sha`	`string`	-

CompiledRule

Properties

Property	Type
`email?`	`RegExp`
`model?`	`ModelRule`
`name?`	`RegExp`
`tool`	`string`

ComputeBlameOptions

Properties

Property	Type	Description
`config?`	`BlameConfig`	-
`exec?`	`GitExec`	-
`file?`	`string`	Root-relative path: compute only records declared in, or anchored to, this file.
`history?`	`boolean`	Walk the whole history for `commits` and `as_of` — one more git call. Default true; false leaves both null.

Contributor

Extends

CommitRef

Properties

Property	Type	Description	Inherited from
`assisted_by`	`AiAttribution`[]	-	`CommitRef`.`assisted_by`
`author`	`string`	`human:<identity>` — or `agent:<tool>` when a bot authored the commit and no human co-author exists.	`CommitRef`.`author`
`co_authors`	`string`[]	Human co-authors from `Co-authored-by` trailers that matched no tool rule.	`CommitRef`.`co_authors`
`date`	`string`	Author date, ISO-8601 as git prints `%aI`.	`CommitRef`.`date`
`lines`	`number`	Lines of the span this commit last touched.	-
`sha`	`string`	-	`CommitRef`.`sha`

ExposureBlame

Properties

Property	Type	Description
`contributors`	`Contributor`[]	Per-commit line ownership over the span, most lines first, then sha.
`error?`	`string`	-
`fixed_before_introduced?`	`true`	Set when the mitigation predates the introduction and the interval was clamped to 0.
`fixed_by`	`CommitRef` \| `null`	The earliest-declared `@mitigates` covering this exposure, or null while it is open.
`found_by`	`CommitRef` \| `null`	Blame of the annotation line itself — who declared the exposure.
`granularity`	`BlameGranularity`	-
`introduced_by`	`IntroducedBy` \| `null`	-
`kind`	`"exposure"`	-
`status`	`BlameStatus`	-
`time_to_fix_days`	`number` \| `null`	Days from `introduced_by.date` to `fixed_by.date`, never negative.

HotFile

Properties

Property	Type	Description
`ai_tools`	`number`	Distinct AI tool+model credited among those commits.
`contributors`	`number`	Distinct commits currently owning lines across those spans.
`file`	`string`	-
`open`	`number`	Open exposures whose span is in this file.

HumanSummaryRow

The analytics every summary row carries beyond its counts.

Extends

SummaryRowRates

Properties

Property	Type	Description	Inherited from
`commits`	`number` \| `null`	Commits crediting this identity in the whole history; null when no counts were supplied.	`SummaryRowRates`.`commits`
`fixed`	`number`	Exposures whose fixing commit credits this identity.	-
`identity`	`string`	-	-
`introduced`	`number`	Exposures whose introducing commit credits this identity.	-
`lines`	`number`	Lines of exposed spans this identity currently owns.	-
`median_time_to_fix_days`	`number` \| `null`	-	-
`oldest_open_days`	`number` \| `null`	Whole days from the oldest open introduced exposure’s date to `as_of`; null when nothing is open or there is no as_of.	`SummaryRowRates`.`oldest_open_days`
`open`	`number`	Introduced and not yet fixed.	-
`per_100_commits`	`number` \| `null`	introduced / commits × 100, one decimal; null when commits is null or 0.	`SummaryRowRates`.`per_100_commits`
`risk_score`	`number`	Over the exposures this identity introduced that are still open: critical 8, high 4, medium 2, low 1, anything else 1 (`P0..P3` alike, case-insensitively).	`SummaryRowRates`.`risk_score`
`touched`	`number`	Exposures whose span this identity currently owns lines of (any commit, not only the introducer).	-

IntroducedBy

Extends

CommitRef

Properties

Property	Type	Description	Inherited from
`assisted_by`	`AiAttribution`[]	-	`CommitRef`.`assisted_by`
`author`	`string`	`human:<identity>` — or `agent:<tool>` when a bot authored the commit and no human co-author exists.	`CommitRef`.`author`
`co_authors`	`string`[]	Human co-authors from `Co-authored-by` trailers that matched no tool rule.	`CommitRef`.`co_authors`
`date`	`string`	Author date, ISO-8601 as git prints `%aI`.	`CommitRef`.`date`
`lower_bound?`	`true`	The true introduction may be earlier: shallow clone, or a dirty file where -L could not run.	-
`method`	`IntroducedMethod`	-	-
`sha`	`string`	-	`CommitRef`.`sha`

MitigationBlame

Properties

Property	Type	Description
`contributors`	`Contributor`[]	-
`declared_by`	`CommitRef` \| `null`	Blame of the `@mitigates` line — who declared the fix.
`error?`	`string`	-
`granularity`	`BlameGranularity`	-
`kind`	`"mitigation"`	-
`status`	`BlameStatus`	-

RawCommit

One commit as git log printed it, before any rule is applied.

Properties

Property	Type	Description
`authorEmail`	`string`	-
`authorName`	`string`	-
`committerName`	`string`	-
`date`	`string`	-
`sha`	`string`	-
`trailers`	`string`	The unfolded trailer block, one `Key: value` per line.

RawPerson

Properties

Property	Type	Description
`email`	`string`	-
`name`	`string`	-
`raw`	`string`	The text this person was parsed from, trimmed.

SummaryRowRates

The analytics every summary row carries beyond its counts.

Extended by

Properties

Property	Type	Description
`commits`	`number` \| `null`	Commits crediting this identity in the whole history; null when no counts were supplied.
`oldest_open_days`	`number` \| `null`	Whole days from the oldest open introduced exposure’s date to `as_of`; null when nothing is open or there is no as_of.
`per_100_commits`	`number` \| `null`	introduced / commits × 100, one decimal; null when commits is null or 0.
`risk_score`	`number`	Over the exposures this identity introduced that are still open: critical 8, high 4, medium 2, low 1, anything else 1 (`P0..P3` alike, case-insensitively).

ToolRule

A row of blame.tools: a regex source for email and/or name, matched anchored and case-insensitively.

Properties

Property	Type
`email?`	`string`
`model?`	`ModelRule`
`name?`	`string`
`tool`	`string`

TrendBucket

One quarter of the introduced/fixed timeline. Quarters are contiguous from the first to the last seen, so a chart has an even axis.

Properties

Property	Type	Description
`fixed`	`number`	-
`introduced`	`number`	-
`introduced_ai`	`number`	Of `introduced`, those whose introducing commit credits an AI tool.
`open_end`	`number`	Cumulative introduced minus cumulative fixed at the end of the period.
`period`	`string`	`YYYY-Qn`, by UTC.

Type Aliases

BlameGranularity

BlameGranularity = "symbol" | "block" | "file" | "none"

How much code the span behind a record covers. none when there is no anchor.

BlameStatus

BlameStatus = "ok" | "no-git" | "shallow" | "uncommitted" | "no-anchor" | "file-missing" | "error"

BlameVerb

BlameVerb = "exposes" | "confirmed" | "mitigates"

ComputationStatus

ComputationStatus = "ok" | "no-git" | "shallow"

IdentityMode

IdentityMode = "name" | "email" | "hash"

What an identity string shows for a human: git name, email, or a 12-hex hash of the email.

IntroducedMethod

IntroducedMethod = "log-L" | "file-add" | "blame"

ModelRule

ModelRule = "name" | "after-token" | "parens"

How a matched name yields a model: the whole name, the name minus its leading tool token, or the text in parentheses.

RecordBlame

RecordBlame = ExposureBlame | MitigationBlame

Variables

BLAME_SCHEMA

const BLAME_SCHEMA: "guardlink.blame/v1" = "guardlink.blame/v1"

GuardLink Blame — shared types.

Attribution is computed from git at run time and never written into source. Every surface (CLI, MCP, TUI, dashboard, report) reads these shapes; the payload is versioned by BLAME_SCHEMA the way the verify output is.

Two vocabularies deliberately kept apart:

CommitRef.author is an identity string in the ledger’s scheme — human:<name> or agent:<tool> — so a gate can key on the prefix.
assisted_by[] is structured (tool, model) because “which model” is the question the dashboard groups by.

Comment

– “Pure type declarations for the blame module; no I/O. The optional blame field these describe is invisible to the annotation hash and stripped from the committed model.json, exactly like anchor”

DEFAULT_IGNORE_REVS

const DEFAULT_IGNORE_REVS: ".git-blame-ignore-revs" = ".git-blame-ignore-revs"

Functions

attributeCommit()

attributeCommit(raw, rules, mode): CommitRef

Parameters

Parameter	Type
`raw`	`RawCommit`
`rules`	readonly `CompiledRule`[]
`mode`	`IdentityMode`

Returns

CommitRef

classifyPerson()

classifyPerson(p, rules): AiAttribution | null

The AI attribution a person resolves to, or null when they match no rule (a human).

Parameters

Parameter	Type
`p`	`RawPerson`
`rules`	readonly `CompiledRule`[]

Returns

AiAttribution | null

compileRules()

compileRules(rules): CompiledRule[]

Compile rules for matching. A rule with no pattern, or with any pattern that is too long or invalid, is dropped whole: a rule that matched on email but lost its name pattern would attribute differently from what was written.

Parameters

Parameter	Type
`rules`	readonly `ToolRule`[]

Returns

CompiledRule[]

entriesFromModel()

entriesFromModel(model): BlameEntry[]

Entries from a model whose records already carry blame (after attachBlame). What the report and the dashboard read; empty when nothing was attached, which is how both know to render nothing.

Parameters

Parameter	Type
`model`	`ThreatModel`

Returns

BlameEntry[]

identityFor()

identityFor(name, email, mode): string

human:<shown> where shown follows the identity mode. email and hash fall back to the name when the commit carries no address; everything falls back to unknown rather than an empty string.

Parameters

Parameter	Type
`name`	`string`
`email`	`string`
`mode`	`IdentityMode`

Returns

string

listCommits()

listCommits(root, exec?): RawCommit[]

Every commit reachable from HEAD, newest first, with the fields resolveCommits reads — the denominator of every “per 100 commits” rate and the source of as_of. HEAD -- pins the argument as a revision even when a file is named HEAD. An empty repository (no HEAD yet) or a plain directory is an empty history, not an error.

Parameters

Parameter	Type
`root`	`string`
`exec?`	`GitExec`

Returns

RawCommit[]

Exposes

#blame to #dos [low] cwe:CWE-400 – “listCommits() runs git log over every commit reachable from HEAD and parseLogRecords() parses each trailer block; history size, not model size, sets the cost”

Mitigates

#blame against #dos using #resource-limits – “A single log call under the same 30 s timeout and 64 MiB output cap; nothing is spawned per commit, and compute.ts lets a caller skip the walk with history: false”

Handles

pii on #blame – “Author names, emails and co-author trailers of every commit in the history”

Flows

GitRepo -> #blame via listCommits – “The reachable history, for commit counts and the HEAD author date”

Comment

– “Reachable from HEAD only, never –all: what other branches carry is not this checkout’s history”

median()

median(values): number | null

Parameters

Parameter	Type
`values`	`number`[]

Returns

number | null

parseAssistedBy()

parseAssistedBy(value, rules): AiAttribution

Linux-kernel style Assisted-by: AGENT:MODEL [tool …]. The agent token is mapped through the rules by name (Claude → claude-code); an agent no rule knows keeps its own lowercased name. Only an empty value is unknown.

Parameters

Parameter	Type
`value`	`string`
`rules`	readonly `CompiledRule`[]

Returns

AiAttribution

parseTrailerBlock()

parseTrailerBlock(text): object

The two trailer keys attribution reads, from an unfolded trailer block.

Parameters

Parameter	Type
`text`	`string`

Returns

object

assistedBy

assistedBy: string[]

coAuthors

coAuthors: RawPerson[]

safeRelPath()

safeRelPath(root, file): string | null

The path with / separators when it stays inside root; null otherwise.

Parameters

Parameter	Type
`root`	`string`
`file`	`string`

Returns

string | null

splitPerson()

splitPerson(value): RawPerson

Name <email> → parts. A value without angle brackets is a bare name.

Parameters

Parameter	Type
`value`	`string`

Returns

RawPerson

summarise()

summarise(entries, ctx?): BlameSummary

Parameters

Parameter	Type
`entries`	`BlameEntry`[]
`ctx?`	`SummaryContext`

Returns

BlameSummary

References