TypeScript API reference

Import from the package’s public export map. The declarations below are emitted from the current build and retain aliases, overloads, generic constraints and optional/readonly fields. They are not hand-maintained approximations of a historical API proposal. Use TypeScript library for installation and the complete installed-consumer compile/run commands.

Package and runtime boundaries

The package is ESM and declares Node 22 or newer. Root, core, language, policy, Git, GitHub and browser-specific entries have different responsibilities; the exact export list below is authoritative for this source. Language and policy compilation do not acquire credentials or perform provider writes. Host adapters acquire data or reconcile effects only when explicitly called. Importing a function is not invoking it, and an internal path that happens to exist is not a supported export.

The browser entries have their own environment boundary. Do not import a Node Git process adapter into a browser and call that portable embedding. The isolated manual uses its declared TypeScript compiler API to inspect emitted declarations; the application’s root build compiler and generated package declarations remain the source of the exported types. Public dependency re-exports retain the dependency’s declaration and lockfile identity, not an invented project-owned declaration.

Result, evidence and diagnostics

Result<T> distinguishes a successful value from diagnostics. Evaluation results then contain their own typed value, evidence and work. The two levels matter: result.ok does not imply an exact number, a true condition or an applied effect. unwrap provides an explicit throwing boundary for hosts that choose exceptions; callers can instead preserve and route structured diagnostics.

A numeric measurement retains exact, bounded, unknown or unmeasurable status. Optional structural absence and explicit null are different from those states. Do not cast arbitrary decoded JSON into a public report or opaque compiled handle. Use readers and compilation, and retain diagnostic source names and original spans.

Complete lifecycle specimen

The complete installed consumer accepts a supplied diff or a saved report. It reads and compiles policy, evaluates rules and a query, constructs a desired plan and reads the serialized plan back. The example repository/PR is inert: this code does not contact GitHub.

// SPDX-License-Identifier: MIT
// Run with: node out/inspect-change.mjs diff change.diff
// Or:       node out/inspect-change.mjs report report.json
// The example target is inert: this program never acquires or mutates GitHub.
import { readFileSync } from 'node:fs';
import { analyzeDiff, readReport, type Result } from '@wolfsblvt/diffdevil';
import {
  readPolicyYaml, compilePolicy, evaluatePolicy, evaluatePolicyQuery,
  createPlan, readPlan,
} from '@wolfsblvt/diffdevil/policy';

function requireResult<T>(result: Result<T>): T {
  if (!result.ok) {
    throw new Error(result.diagnostics.map(item => `${item.code}: ${item.message}`).join('\n'));
  }
  return result.value;
}

try {
  const [kind, path] = process.argv.slice(2);
  if ((kind !== 'diff' && kind !== 'report') || !path) {
    throw new Error('Usage: inspect-change.mjs diff|report PATH');
  }
  const input = readFileSync(path, 'utf8');
  const report = requireResult(kind === 'diff' ? analyzeDiff(input) : readReport(input));
  const source = requireResult(readPolicyYaml('version: 1\npresets: [size@1]\n', { name: 'example-policy.yml' }));
  const policy = requireResult(compilePolicy(source));
  const evaluated = requireResult(evaluatePolicy(policy, report));
  const query = requireResult(evaluatePolicyQuery(policy, report, 'totals.lines.changed < 100', { context: 'condition' }));
  const target = {
    repository: report.source.repository ?? 'example/repository',
    pullRequest: report.source.pullRequest ?? 42,
  };
  const plan = requireResult(createPlan(evaluated, target, { definitions: 'ensure' }));
  const transported = requireResult(readPlan(JSON.stringify(plan)));
  // Successful evaluation may contain an unknown value. Preserve its typed shape.
  console.log(JSON.stringify({
    changed: evaluated.report.totals.lines.changed,
    rawChurn: evaluated.report.totals.raw.churn,
    decision: query.result.value,
    desired: { stage: transported.stage, operations: transported.operations, held: transported.held },
  }, null, 2));
} catch (error) {
  console.error(error instanceof Error ? error.message : String(error));
  process.exitCode = 2;
}

Use the compile/run commands in the library guide. Against the small payments diff it retains 10 Changed and 16 churn, a resolved less-than-100 decision and a desired size label. Against incomplete evidence it must retain uncertainty instead of unwrapping a made-up scalar. A host choosing unwrap catches the failure rather than treating it as an empty successful result.

Analysis, policy and query lifecycle

analyzeDiff normalizes a complete patch; analyzeChanges consumes declared change data; Git and GitHub acquisition are explicit adapter calls. readReport validates a transported report’s structure and model relationships before it is reused. Path policies and scopes select views without deleting the observed comparison.

readPolicyJson and readPolicyYaml preserve original source locations. compilePolicy also accepts an inert version-1 object, plus explicitly supplied template text. It does not fetch config/template files. Successful compiled handles are immutable and cannot be restored by JSON deserialization or manufactured by casts. explainPolicy exposes normalized declarations, profiles and replacement origins.

evaluatePolicy defaults to rules phase. phase: 'analyze' computes metrics and bands without rules. evaluatePolicyQuery accepts supported text/source objects, shortcuts, saved queries or band selectors and evaluates required dependencies. Its condition context enforces a boolean result while permitting query-phase access to completed rule results; this does not relax a rule declaration’s phase boundary.

createPlan requires a genuine rules-phase result and a compatible target. readPlan validates transport, not freshness, policy trust, ownership or permissions. Policy identity includes bound parameter values and resolved template contents. Saved metrics preserve numeric types, but do not inherit guessed private formula correlations from a previous evaluator request.

Public symbols and exact declarations

The export index links each alias to its declaration anchor. Overloads stay together; full types remain open for intentional lookup without turning every symbol into another sidebar page. Edit source and regenerate this bounded inventory. Explanations and examples outside the markers remain authored.

@wolfsblvt/diffdevil

Public export	Declared symbol	Signature / type
AnalyzeOptions	AnalyzeOptions	Declaration
BandResult	BandResult	Declaration
BooleanValue	BooleanValue	Declaration
CollectionValue	CollectionValue	Declaration
CommentAuthor	CommentAuthor	Declaration
CompiledExpression	CompiledExpression	Declaration
CompiledPolicy	CompiledPolicy	Declaration
Decision	Decision	Declaration
DefinitionResult	DefinitionResult	Declaration
Diagnostic	Diagnostic	Declaration
DiffSourceIdentity	DiffSourceIdentity	Declaration
DiffdevilError	DiffdevilError	Declaration
EffectObservation	EffectObservation	Declaration
EffectOperation	EffectOperation	Declaration
EffectPlan	EffectPlan	Declaration
EvaluationEnvironment	EvaluationEnvironment	Declaration
EvaluationResult	EvaluationResult	Declaration
ExpressionSource	ExpressionSource	Declaration
FileRecord	FileRecord	Declaration
FileSet	FileSet	Declaration
GitHubApplyOptions	GitHubApplyOptions	Declaration
GitHubApplyResult	GitHubApplyResult	Declaration
GitHubClient	GitHubClient	Declaration
GitHubClientOptions	GitHubClientOptions	Declaration
GitHubPolicySource	GitHubPolicySource	Declaration
GitHubRequestError	GitHubRequestError	Declaration
GitOptions	GitOptions	Declaration
LabelDefinition	LabelDefinition	Declaration
LineMeasurements	LineMeasurements	Declaration
MeasurementSummary	MeasurementSummary	Declaration
NumberValue	NumberValue	Declaration
NumericMeasurement	NumericMeasurement	Declaration
NumericType	NumericType	Declaration
PathPolicy	PathPolicy	Declaration
PlanOptions	PlanOptions	Declaration
PlanTarget	PlanTarget	Declaration
PolicyCompileOptions	PolicyCompileOptions	Declaration
PolicyDocument	PolicyDocument	Declaration
PolicyEvaluateOptions	PolicyEvaluateOptions	Declaration
PolicyQueryResult	PolicyQueryResult	Declaration
PolicyQuerySelector	PolicyQuerySelector	Declaration
PolicyResult	PolicyResult	Declaration
PolicySource	PolicySource	Declaration
PresentationDetail	PresentationDetail	Declaration
RawMeasurements	RawMeasurements	Declaration
Reason	Reason	Declaration
Report	Report	Declaration
Result	Result	Declaration
RuleResult	RuleResult	Declaration
SEMANTICS	SEMANTICS	Declaration
SchemaKind	SchemaKind	Declaration
ScopeRecord	ScopeRecord	Declaration
Semantics	Semantics	Declaration
Shortcut	Shortcut	Declaration
SourceRange	SourceRange	Declaration
TextPresentationOptions	TextPresentationOptions	Declaration
Totals	Totals	Declaration
TypeDescriptor	TypeDescriptor	Declaration
Value	Value	Declaration
analyzeChanges	analyzeChanges	Declaration
analyzeDiff	analyzeDiff	Declaration
analyzeGit	analyzeGit	Declaration
analyzeGitHub	analyzeGitHub	Declaration
analyzeGitHubGit	analyzeGitHubGit	Declaration
applyGitHubPolicy	applyGitHubPolicy	Declaration
attachScopes	attachScopes	Declaration
compileExpression	compileExpression	Declaration
compilePolicy	compilePolicy	Declaration
compileShortcut	compileShortcut	Declaration
createEnvironment	createEnvironment	Declaration
createPlan	createPlan	Declaration
environmentFromReport	environmentFromReport	Declaration
evaluateExpression	evaluateExpression	Declaration
evaluatePolicy	evaluatePolicy	Declaration
evaluatePolicyQuery	evaluatePolicyQuery	Declaration
expandShortcut	expandShortcut	Declaration
explainPolicy	explainPolicy	Declaration
formatPlan	formatPlan	Declaration
formatQuery	formatQuery	Declaration
formatReport	formatReport	Declaration
loadGitHubPolicy	loadGitHubPolicy	Declaration
parseExpression	parseExpression	Declaration
parsePatch	parsePatch	Declaration
parseUnifiedDiff	parseUnifiedDiff	Declaration
readGitHubPolicy	readGitHubPolicy	Declaration
readPlan	readPlan	Declaration
readPolicyJson	readPolicyJson	Declaration
readPolicyYaml	readPolicyYaml	Declaration
readReport	readReport	Declaration
sourcePosition	sourcePosition	Declaration
syncGitHubLabels	syncGitHubLabels	Declaration
unwrap	unwrap	Declaration
validateSchema	validateSchema	Declaration
withParameters	withParameters	Declaration
withPathPolicy	withPathPolicy	Declaration

@wolfsblvt/diffdevil/core

Public export	Declared symbol	Signature / type
AnalyzeOptions	AnalyzeOptions	Declaration
BandResult	BandResult	Declaration
BooleanValue	BooleanValue	Declaration
ChangeInput	ChangeInput	Declaration
CollectionValue	CollectionValue	Declaration
Decision	Decision	Declaration
Diagnostic	Diagnostic	Declaration
DiffSourceIdentity	DiffSourceIdentity	Declaration
EffectOperation	EffectOperation	Declaration
EffectPlan	EffectPlan	Declaration
FileRecord	FileRecord	Declaration
FileSet	FileSet	Declaration
LabelDefinition	LabelDefinition	Declaration
LineMeasurements	LineMeasurements	Declaration
MeasurementSummary	MeasurementSummary	Declaration
NumberValue	NumberValue	Declaration
NumericMeasurement	NumericMeasurement	Declaration
NumericType	NumericType	Declaration
PathPolicy	PathPolicy	Declaration
PlanTarget	PlanTarget	Declaration
RawMeasurements	RawMeasurements	Declaration
Reason	Reason	Declaration
Report	Report	Declaration
Result	Result	Declaration
RuleResult	RuleResult	Declaration
SEMANTICS	SEMANTICS	Declaration
ScopeRecord	ScopeRecord	Declaration
Semantics	Semantics	Declaration
SourceRange	SourceRange	Declaration
Totals	Totals	Declaration
TypeDescriptor	TypeDescriptor	Declaration
Value	Value	Declaration
analyzeChanges	analyzeChanges	Declaration
analyzeDiff	analyzeDiff	Declaration
attachScopes	attachScopes	Declaration
parsePatch	parsePatch	Declaration
parseUnifiedDiff	parseUnifiedDiff	Declaration
readReport	readReport	Declaration
withPathPolicy	withPathPolicy	Declaration

@wolfsblvt/diffdevil/language

Public export	Declared symbol	Signature / type
Ast	Ast	Declaration
CompileOptions	CompileOptions	Declaration
CompiledExpression	CompiledExpression	Declaration
EvaluationEnvironment	EvaluationEnvironment	Declaration
EvaluationResult	EvaluationResult	Declaration
ExpressionSource	ExpressionSource	Declaration
Schema	Schema	Declaration
Shortcut	Shortcut	Declaration
Type	TypeDescriptor	Declaration
ast	ast	Declaration
boolValue	boolValue	Declaration
collection	collection	Declaration
compileAst	compileAst	Declaration
compileExpression	compileExpression	Declaration
compileShortcut	compileShortcut	Declaration
completeCollection	completeCollection	Declaration
createEnvironment	createEnvironment	Declaration
environmentFromReport	environmentFromReport	Declaration
evaluateExpression	evaluateExpression	Declaration
expandShortcut	expandShortcut	Declaration
integer	integer	Declaration
numberValue	numberValue	Declaration
optional	optional	Declaration
parseExpression	parseExpression	Declaration
recordType	recordType	Declaration
recordValue	recordValue	Declaration
sourcePosition	sourcePosition	Declaration
textValue	textValue	Declaration
withParameters	withParameters	Declaration

@wolfsblvt/diffdevil/policy

Public export	Declared symbol	Signature / type
ActionShortcutOptions	ActionShortcutOptions	Declaration
BandDefinition	BandDefinition	Declaration
BandLabels	BandLabels	Declaration
BandRange	BandRange	Declaration
BooleanLabels	BooleanLabels	Declaration
CommentDefinition	CommentDefinition	Declaration
CompiledBands	CompiledBands	Declaration
CompiledPolicy	CompiledPolicy	Declaration
CompiledTemplate	CompiledTemplate	Declaration
MetricDefinition	MetricDefinition	Declaration
NormalizedPolicy	NormalizedPolicy	Declaration
ParameterDefinition	ParameterDefinition	Declaration
ParameterType	ParameterType	Declaration
PathOverrides	PathOverrides	Declaration
PlanOptions	PlanOptions	Declaration
PolicyCompileOptions	PolicyCompileOptions	Declaration
PolicyDocument	PolicyDocument	Declaration
PolicyEvaluateOptions	PolicyEvaluateOptions	Declaration
PolicyOrigin	PolicyOrigin	Declaration
PolicyQueryResult	PolicyQueryResult	Declaration
PolicyQuerySelector	PolicyQuerySelector	Declaration
PolicyResult	PolicyResult	Declaration
PolicySource	PolicySource	Declaration
RuleDefinition	RuleDefinition	Declaration
SizeOverrides	SizeOverrides	Declaration
commentLifecycle	commentLifecycle	Declaration
compileActionShortcut	compileActionShortcut	Declaration
compileBands	compileBands	Declaration
compilePolicy	compilePolicy	Declaration
compileTemplate	compileTemplate	Declaration
createPlan	createPlan	Declaration
evaluatePolicy	evaluatePolicy	Declaration
evaluatePolicyQuery	evaluatePolicyQuery	Declaration
explainPolicy	explainPolicy	Declaration
formatPlan	formatPlan	Declaration
readPlan	readPlan	Declaration
readPolicyJson	readPolicyJson	Declaration
readPolicyYaml	readPolicyYaml	Declaration
renderTemplate	renderTemplate	Declaration
resolveBand	resolveBand	Declaration

@wolfsblvt/diffdevil/git

Public export	Declared symbol	Signature / type
GitOptions	GitOptions	Declaration
analyzeGit	analyzeGit	Declaration

@wolfsblvt/diffdevil/github

Public export	Declared symbol	Signature / type
CommentAuthor	CommentAuthor	Declaration
DefinitionResult	DefinitionResult	Declaration
EffectObservation	EffectObservation	Declaration
GitHubApplyOptions	GitHubApplyOptions	Declaration
GitHubApplyResult	GitHubApplyResult	Declaration
GitHubClient	GitHubClient	Declaration
GitHubClientOptions	GitHubClientOptions	Declaration
GitHubPolicySource	GitHubPolicySource	Declaration
GitHubRequestError	GitHubRequestError	Declaration
HostCommentRequest	HostCommentRequest	Declaration
HostCommentResult	HostCommentResult	Declaration
HostComposedComment	HostComposedComment	Declaration
HostLifecycles	HostLifecycles	Declaration
PendingWrite	PendingWrite	Declaration
analyzeGitHub	analyzeGitHub	Declaration
analyzeGitHubGit	analyzeGitHubGit	Declaration
applyGitHubPolicy	applyGitHubPolicy	Declaration
loadGitHubPolicy	loadGitHubPolicy	Declaration
readGitHubPolicy	readGitHubPolicy	Declaration
readHostCommentContext	readHostCommentContext	Declaration
readPullSnapshot	readPullSnapshot	Declaration
reconcileHostComment	reconcileHostComment	Declaration
syncGitHubLabels	syncGitHubLabels	Declaration

@wolfsblvt/diffdevil/browser

Public export	Declared symbol	Signature / type
AppReportIdentity	AppReportIdentity	Declaration
AppStanding	AppStanding	Declaration
BROWSER_ADAPTER	BROWSER_ADAPTER	Declaration
BrowserComparison	BrowserComparison	Declaration
BrowserInput	BrowserInput	Declaration
BrowserPolicy	BrowserPolicy	Declaration
Diagnostic	Diagnostic	Declaration
FileRecord	FileRecord	Declaration
HUMAN_VIEW_VERSION	HUMAN_VIEW_VERSION	Declaration
HumanReportView	HumanReportView	Declaration
MAX_ACQUISITION_BYTES	MAX_ACQUISITION_BYTES	Declaration
MeasureOutcome	MeasureOutcome	Declaration
NumericMeasurement	NumericMeasurement	Declaration
PatchEvidence	PatchEvidence	Declaration
PolicyLayers	PolicyLayers	Declaration
PolicyMode	PolicyMode	Declaration
Rail	Rail	Declaration
RailCell	RailCell	Declaration
Rendered	Rendered	Declaration
Report	Report	Declaration
ReportFormat	ReportFormat	Declaration
Result	Result	Declaration
SEMANTICS	SEMANTICS	Declaration
analyzeBrowserInput	analyzeBrowserInput	Declaration
appStanding	appStanding	Declaration
comparisonKey	comparisonKey	Declaration
compileBrowserPolicy	compileBrowserPolicy	Declaration
evidenceText	evidenceText	Declaration
formatReport	formatReport	Declaration
humanReport	humanReport	Declaration
measureBoundedFiles	measureBoundedFiles	Declaration
measurementText	measurementText	Declaration
readComparison	readComparison	Declaration
readPolicyText	readPolicyText	Declaration
requiredTemplates	requiredTemplates	Declaration
stringifyPolicy	stringify	Declaration

@wolfsblvt/diffdevil/browser/text

Public export	Declared symbol	Signature / type
evidenceText	evidenceText	Declaration
measurementText	measurementText	Declaration

Public declarations

analyzeBrowserInput

Canonical source

export declare function analyzeBrowserInput(json: string): Result<Report>;

BROWSER_ADAPTER

Canonical source

declare const BROWSER_ADAPTER = "diffdevil.browser/1";

BrowserComparison

Canonical source

export interface BrowserComparison {
    readonly host: 'github.com';
    readonly repository: string;
    readonly pullRequest: number;
    readonly base: string;
    readonly head: string;
    readonly changedFiles?: number;
    readonly additions?: number;
    readonly deletions?: number;
}

BrowserInput

Canonical source

export type BrowserInput = {
    readonly comparison: BrowserComparison;
    readonly complete: boolean;
} & ({
    readonly format: 'diff';
    readonly text: string;
} | {
    readonly format: 'github-files';
    readonly files: readonly unknown[];
    readonly diff?: string;
});

comparisonKey

Canonical source

export declare function comparisonKey(input: BrowserComparison): string;

MAX_ACQUISITION_BYTES

Canonical source

declare const MAX_ACQUISITION_BYTES: number;

readComparison

Canonical source

export declare function readComparison(input: unknown): BrowserComparison;

AppReportIdentity

Canonical source

export interface AppReportIdentity {
    readonly kind: 'diffdevil.browser-report';
    readonly version: 1;
    readonly comparison: BrowserComparison;
    readonly reportId: string;
    readonly policyDigest: string;
    readonly engine: string;
    readonly schema: string;
    readonly measurement: string;
    readonly presenter: string;
}

AppStanding

Canonical source

export type AppStanding = 'local' | 'matching' | 'policy-mismatch' | 'stale' | 'incompatible';

measureBoundedFiles

Canonical source

export declare function measureBoundedFiles(input: Report, patches: readonly PatchEvidence[]): Result<MeasureOutcome>;

MeasureOutcome

Canonical source

export interface MeasureOutcome {
    readonly report: Report;
    readonly measured: readonly string[];
    readonly rejected: readonly {
        readonly path: string;
        readonly code: string;
    }[];
}

PatchEvidence

Canonical source

export interface PatchEvidence {
    readonly path: string;
    readonly patch: string;
}

BrowserPolicy

Canonical source

export interface BrowserPolicy {
    readonly program: CompiledPolicy;
    readonly document: PolicyDocument;
    readonly origins: readonly PolicyOrigin[];
    readonly mode: PolicyMode;
    readonly digest: string;
    readonly layers: readonly string[];
}

compileBrowserPolicy

Canonical source

export declare function compileBrowserPolicy(json: string): Result<BrowserPolicy>;

PolicyLayers

Canonical source

export interface PolicyLayers {
    readonly mode: PolicyMode;
    readonly personal: string;
    readonly repository?: string;
    readonly override?: string;
    readonly templateFiles?: Readonly<Record<string, string>>;
}

PolicyMode

Canonical source

export type PolicyMode = 'composed' | 'repository' | 'personal-only';

readPolicyText

Canonical source

export declare function readPolicyText(text: string, name?: string): Result<PolicyDocument>;

requiredTemplates

Canonical source

export declare function requiredTemplates(json: string): Result<readonly string[]>;

evidenceText

Canonical source

export declare function evidenceText(status: NumericMeasurement['status']): string;

measurementText

Canonical source

export declare function measurementText(value: NumericMeasurement): string;

HUMAN_VIEW_VERSION

Canonical source

declare const HUMAN_VIEW_VERSION = "diffdevil.human-view/1";

humanReport

Canonical source

export declare function humanReport(input: Report, policy?: BrowserPolicy, path?: string, errors?: readonly Diagnostic[]): Result<HumanReportView>;

HumanReportView

Canonical source

export interface HumanReportView {
    readonly kind: typeof HUMAN_VIEW_VERSION;
    readonly report: Report;
    readonly focus?: FileRecord;
    readonly changed: NumericMeasurement;
    readonly added: NumericMeasurement;
    readonly deleted: NumericMeasurement;
    readonly modified: NumericMeasurement;
    readonly raw: Report['totals']['raw'];
    readonly evidence: Report['measurement'];
    readonly rails: readonly Rail[];
    readonly policy?: {
        readonly digest: string;
        readonly mode: string;
        readonly origins: BrowserPolicy['origins'];
        readonly layers: readonly string[];
    };
    readonly errors: readonly Diagnostic[];
}

Rail

Canonical source

export interface Rail {
    readonly id: string;
    readonly expression: string;
    readonly cells: readonly RailCell[];
    readonly selected?: string;
    readonly label?: string;
    readonly group?: string;
    readonly members?: readonly string[];
}

RailCell

Canonical source

export interface RailCell {
    readonly id: string;
    readonly name: string;
    readonly lower?: number;
    readonly upper?: number;
    readonly color?: string;
    readonly label?: string;
    readonly selected: boolean;
}

DiffdevilError

Canonical source

export declare class DiffdevilError extends Error {
    readonly diagnostic: Diagnostic;
    constructor(diagnostic: Diagnostic);
}

unwrap

Canonical source

export declare function unwrap<T>(result: Result<T>): T;

formatQuery

Canonical source

export declare function formatQuery(result: EvaluationResult, options?: {
    command?: 'query' | 'check';
    format?: QueryFormat;
    report?: Report;
}): Result<Rendered>;

formatReport

Canonical source

export declare function formatReport(report: Report, format?: ReportFormat, options?: TextPresentationOptions): Result<Rendered>;

Rendered

Canonical source

export interface Rendered {
    readonly stdout: string;
    readonly exitCode: 0 | 1 | 2 | 3;
}

ReportFormat

Canonical source

export type ReportFormat = 'human' | 'markdown' | 'agent' | 'json' | 'jsonl' | 'env';

applyGitHubPolicy

Canonical source

export declare function applyGitHubPolicy(client: GitHubClient, target: PlanTarget, policy: CompiledPolicy, options?: GitHubApplyOptions): Promise<Result<GitHubApplyResult>>;

GitHubApplyOptions

Canonical source

export interface GitHubApplyOptions extends Pick<PolicyEvaluateOptions, 'parameters' | 'limits'> {
    readonly definitions?: 'none' | 'ensure' | 'sync' | 'verify';
    readonly inputReport?: Report;
    readonly trustReport?: boolean;
    readonly inputPlan?: EffectPlan;
    readonly commentAuthor?: CommentAuthor;
    readonly occasionId?: string;
    readonly rules?: readonly string[];
    readonly expectedPolicyBase?: string;
    readonly localGit?: {
        readonly cwd?: string;
    };
    readonly beforeWrite?: (write: PendingWrite) => Promise<void>;
    readonly composeComments?: Readonly<Record<string, HostComposedComment>>;
}

GitHubApplyResult

Canonical source

export interface GitHubApplyResult {
    readonly kind: 'diffdevil.github-apply';
    readonly schemaVersion: '1.0';
    readonly status: 'verified' | 'incomplete';
    readonly changed: number;
    readonly report: Report;
    readonly plan: EffectPlan;
    readonly observations: readonly EffectObservation[];
    readonly diagnostics: readonly Diagnostic[];
}

HostComposedComment

Canonical source

export interface HostComposedComment {
    readonly lifecycle: string;
    readonly compose: (input: {
        readonly report: Report;
        readonly plan: EffectPlan;
        readonly previous: {
            readonly found: boolean;
            readonly context?: string;
        };
    }) => string | {
        readonly body: string;
        readonly context?: string;
    };
}

GitHubClient

Canonical source

export declare class GitHubClient {
    #private;
    readonly apiUrl: string;
    readonly responseBytes: number;
    constructor(options?: GitHubClientOptions);
    url(route: string): URL;
    request(route: string, options?: RequestOptions): Promise<GitHubResponse>;
    private discardBody;
    private retryDelay;
    json(route: string, options?: RequestOptions): Promise<unknown>;
    list(route: string, options?: {
        maximumItems?: number;
    }): Promise<{
        items: unknown[];
        truncated: boolean;
    }>;
}

GitHubClientOptions

Canonical source

export interface GitHubClientOptions {
    readonly token?: string;
    readonly apiUrl?: string;
    readonly fetch?: typeof globalThis.fetch;
    readonly signal?: AbortSignal;
    readonly timeoutMs?: number;
    readonly readRetries?: number;
    readonly responseBytes?: number;
    readonly sleep?: (milliseconds: number) => Promise<void>;
    readonly now?: () => number;
}

GitHubRequestError

Canonical source

export declare class GitHubRequestError extends DiffdevilError {
    readonly status: number | undefined;
    readonly ambiguous: boolean;
    constructor(status: number | undefined, ambiguous: boolean, message: string, phase: Diagnostic['phase'], rateLimited?: boolean);
}

CommentAuthor

Canonical source

export interface CommentAuthor {
    readonly login: string;
    readonly id?: number;
}

HostCommentRequest

Canonical source

export interface HostCommentRequest {
    readonly target: {
        readonly repository: string;
        readonly pullRequest: number;
    };
    readonly policyId: string;
    readonly rule: string;
    readonly host: string;
    readonly occasionId: string;
    readonly body: string;
}

HostCommentResult

Canonical source

export interface HostCommentResult {
    readonly status: 'created' | 'unchanged';
    readonly observations: readonly EffectObservation[];
}

HostLifecycles

Canonical source

export type HostLifecycles = Readonly<Record<string, string>>;

readHostCommentContext

Canonical source

export declare function readHostCommentContext(client: GitHubClient, target: HostCommentRequest['target'], request: {
    readonly rule: string;
    readonly host: string;
}, author: CommentAuthor): Promise<{
    readonly found: boolean;
    readonly context?: string;
}>;

reconcileHostComment

Canonical source

export declare function reconcileHostComment(client: GitHubClient, request: HostCommentRequest, author: CommentAuthor, options?: {
    readonly beforeWrite?: (write: PendingWrite) => Promise<void>;
}): Promise<HostCommentResult>;

DefinitionResult

Canonical source

export interface DefinitionResult {
    readonly kind: 'diffdevil.github-definitions';
    readonly schemaVersion: '1.0';
    readonly status: 'verified' | 'incomplete';
    readonly changed: number;
    readonly observations: readonly EffectObservation[];
    readonly diagnostics: readonly Diagnostic[];
}

syncGitHubLabels

Canonical source

export declare function syncGitHubLabels(client: GitHubClient, repository: string, definitions: Readonly<Record<string, LabelDefinition>>, mode?: 'verify' | 'ensure' | 'sync', options?: {
    readonly assertCurrent?: () => Promise<void>;
}): Promise<Result<DefinitionResult>>;

EffectObservation

Canonical source

export interface EffectObservation {
    readonly kind: string;
    readonly subject: string;
    outcome: 'changed' | 'unchanged' | 'unresolved';
    request: 'not-needed' | 'acknowledged' | 'ambiguous' | 'rejected';
    readback: 'verified' | 'failed' | 'unobserved';
}

PendingWrite

Canonical source

export interface PendingWrite {
    readonly kind: string;
    readonly subject: string;
}

GitHubPolicySource

Canonical source

export interface GitHubPolicySource {
    readonly repository: string;
    readonly ref: string;
    readonly path: string;
}

loadGitHubPolicy

Canonical source

export declare function loadGitHubPolicy(client: GitHubClient, source: GitHubPolicySource, options?: Pick<PolicyCompileOptions, 'presets' | 'paths' | 'limits'>): Promise<Result<CompiledPolicy>>;

readGitHubPolicy

Canonical source

export declare function readGitHubPolicy(client: GitHubClient, source: GitHubPolicySource, options?: Pick<PolicyCompileOptions, 'presets' | 'paths' | 'limits'>): Promise<CompiledPolicy>;

analyzeGitHub

Canonical source

export declare function analyzeGitHub(client: GitHubClient, target: PlanTarget, options?: Omit<AnalyzeOptions, 'source' | 'fileSet'>): Promise<Result<Report>>;

analyzeGitHubGit

Canonical source

export declare function analyzeGitHubGit(client: GitHubClient, target: PlanTarget, options?: Pick<GitOptions, 'cwd' | 'paths' | 'scopes' | 'maximumBytes'>): Promise<Result<Report>>;

readPullSnapshot

Canonical source

export declare function readPullSnapshot(client: GitHubClient, target: PlanTarget): Promise<PullSnapshot>;

Ast

Canonical source

export type Ast = (Node & {
    readonly kind: 'literal';
    readonly literalType: 'integer' | 'float' | 'string' | 'boolean' | 'null';
    readonly raw: string;
    readonly value: number | string | boolean | null;
}) | (Node & {
    readonly kind: 'identifier';
    readonly name: string;
}) | (Node & {
    readonly kind: 'member';
    readonly object: Ast;
    readonly key: string;
    readonly keySpan: SourceRange;
}) | (Node & {
    readonly kind: 'unary';
    readonly operator: UnaryOperator;
    readonly operatorSpan: SourceRange;
    readonly operand: Ast;
}) | (Node & {
    readonly kind: 'binary';
    readonly operator: BinaryOperator;
    readonly operatorSpan: SourceRange;
    readonly left: Ast;
    readonly right: Ast;
}) | (Node & {
    readonly kind: 'conditional';
    readonly condition: Ast;
    readonly whenTrue: Ast;
    readonly whenFalse: Ast;
}) | (Node & {
    readonly kind: 'call';
    readonly name: string;
    readonly nameSpan: SourceRange;
    readonly arguments: readonly Ast[];
}) | (Node & {
    readonly kind: 'lambda';
    readonly parameter: string;
    readonly parameterSpan: SourceRange;
    readonly body: Ast;
}) | (Node & {
    readonly kind: 'list';
    readonly items: readonly Ast[];
}) | (Node & {
    readonly kind: 'record';
    readonly fields: readonly {
        readonly key: string;
        readonly keySpan: SourceRange;
        readonly value: Ast;
    }[];
});

compileAst

Canonical source

export declare function compileAst(input: Ast, options: CompileOptions): Result<CompiledExpression>;

CompiledExpression

Canonical source

export interface CompiledExpression {
    readonly kind: 'diffdevil.expression';
    readonly language: 'diffdevil-expr/1';
    readonly resultType: Type;
    readonly schemaId: string;
    readonly dependencies: readonly string[];
}

CompileOptions

Canonical source

export interface CompileOptions {
    readonly environment: Schema;
    readonly context?: ExpressionContext;
    readonly limits?: EvaluationLimits;
}

createEnvironment

Canonical source

export declare function createEnvironment(inputSchema: Schema, inputValues: Readonly<Record<string, Value>>): Result<EvaluationEnvironment>;

environmentFromReport

Canonical source

export declare function environmentFromReport(input: Report): Result<EvaluationEnvironment>;

EvaluationEnvironment

Canonical source

export interface EvaluationEnvironment {
    readonly schema: Schema;
    readonly schemaId: string;
    readonly values: Readonly<Record<string, Value>>;
}

withParameters

Canonical source

export declare function withParameters(env: EvaluationEnvironment, schema: Schema, values: Readonly<Record<string, Value>>): Result<EvaluationEnvironment>;

evaluateExpression

Canonical source

export declare function evaluateExpression(program: CompiledExpression, environment: EvaluationEnvironment, options?: EvaluateOptions): Result<EvaluationResult>;

EvaluationResult

Canonical source

export interface EvaluationResult {
    readonly value: Value;
    readonly evidence: readonly Reason[];
    readonly work: number;
}

compileShortcut

Canonical source

export declare function compileShortcut(input: Shortcut, options: Omit<CompileOptions, 'context'>): Result<CompiledExpression>;

expandShortcut

Canonical source

export declare function expandShortcut(input: Shortcut): Result<{
    readonly expression: string;
}>;

Shortcut

Canonical source

export interface Shortcut {
    readonly kind: 'query' | 'check';
    readonly metric?: string;
    readonly files?: true | 'any' | 'all';
    readonly scope?: string;
    readonly paths?: readonly string[];
    readonly allFiles?: boolean;
    readonly certain?: boolean;
    readonly select?: readonly string[];
    readonly comparison?: {
        readonly operator: string;
        readonly value: number;
        readonly numericType?: NumericType;
    };
    readonly status?: 'exact' | 'bounded' | 'unknown' | 'unmeasurable';
}

ExpressionSource

Canonical source

export interface ExpressionSource {
    readonly text: string;
    readonly language: 'diffdevil-expr/1';
    readonly name?: string;
}

sourcePosition

Canonical source

export declare function sourcePosition(text: string, offset: number): {
    line: number;
    column: number;
};

compileExpression

Canonical source

export declare function compileExpression(source: string | ExpressionSource, options: CompileOptions): Result<CompiledExpression>;

parseExpression

Canonical source

export declare function parseExpression(source: string | ExpressionSource, options?: {
    readonly limits?: EvaluationLimits;
}): Result<Ast>;

collection

Canonical source

declare const collection: (item: Type) => Type;

optional

Canonical source

declare const optional: (item: Type) => Type;

recordType

Canonical source

declare const recordType: (fields: Schema) => Type;

Schema

Canonical source

export type Schema = Readonly<Record<string, Type>>;

boolValue

Canonical source

declare const boolValue: (value: boolean | Decision) => BooleanValue;

completeCollection

Canonical source

declare const completeCollection: (values: readonly Value[]) => CollectionValue;

recordValue

Canonical source

declare const recordValue: (fields: Readonly<Record<string, Value>>) => Value;

textValue

Canonical source

declare const textValue: (value: string) => Value;

BandResult

Canonical source

export type BandResult = {
    readonly status: 'resolved';
    readonly id: string;
    readonly lower?: number;
    readonly upper?: number;
} | {
    readonly status: 'unknown';
    readonly candidates: readonly string[];
    readonly reasons: readonly Reason[];
};

BooleanValue

Canonical source

export interface BooleanValue {
    readonly kind: 'boolean';
    readonly decision: Decision;
}

CollectionValue

Canonical source

export interface CollectionValue {
    readonly kind: 'collection';
    readonly items: readonly {
        readonly membership: 'definite' | 'possible';
        readonly value: Value;
    }[];
    readonly unseen: {
        readonly possible: boolean;
        readonly minimum: number;
        readonly maximum?: number;
    };
    readonly order: 'known' | 'unknown';
    readonly cardinality?: NumericMeasurement;
    readonly notes?: readonly Reason[];
}

Decision

Canonical source

export type Decision = {
    readonly status: 'resolved';
    readonly value: boolean;
} | {
    readonly status: 'unknown';
    readonly reasons: readonly Reason[];
};

Diagnostic

Canonical source

export interface Diagnostic {
    readonly code: string;
    readonly phase: 'source' | 'config' | 'lex' | 'parse' | 'bind' | 'type' | 'evaluate' | 'format' | 'plan' | 'apply';
    readonly severity: 'error' | 'warning' | 'information';
    readonly message: string;
    readonly range?: SourceRange;
    readonly precision?: 'character' | 'scalar';
    readonly configPath?: string;
    readonly related?: readonly {
        readonly message: string;
        readonly range: SourceRange;
    }[];
    readonly details?: Readonly<Record<string, unknown>>;
}

DiffSourceIdentity

Canonical source

export interface DiffSourceIdentity {
    readonly kind: 'git' | 'unified-diff' | 'github-api';
    readonly comparisonId: string;
    readonly base?: string;
    readonly head?: string;
    readonly baseTip?: string;
    readonly comparison?: 'three-dot' | 'direct' | 'worktree' | 'staged' | 'supplied';
    readonly repository?: string;
    readonly pullRequest?: number;
}

EffectOperation

Canonical source

export type EffectOperation = {
    readonly kind: 'label.ensure' | 'label.sync';
    readonly rule?: string;
    readonly name: string;
    readonly definition: LabelDefinition;
} | {
    readonly kind: 'label.add' | 'label.remove';
    readonly rule: string;
    readonly name: string;
} | {
    readonly kind: 'label.select';
    readonly rule: string;
    readonly group: string;
    readonly members: readonly string[];
    readonly selected: string;
} | {
    readonly kind: 'comment.reconcile';
    readonly rule: string;
    readonly mode: 'create' | 'once' | 'upsert' | 'once-per-transition';
    readonly trigger: 'always' | 'matched' | 'band-changed';
    readonly body: string;
    readonly occasionId?: string;
};

EffectPlan

Canonical source

export interface EffectPlan {
    readonly kind: 'diffdevil.plan';
    readonly schemaVersion: '1.0';
    readonly semantics: Semantics;
    readonly stage: 'desired' | 'materialized';
    readonly source: DiffSourceIdentity;
    readonly reportId: string;
    readonly policyId: string;
    readonly target: PlanTarget;
    readonly operations: readonly EffectOperation[];
    readonly held: readonly {
        readonly rule: string;
        readonly reasons: readonly Reason[];
    }[];
    readonly rules: Readonly<Record<string, RuleResult>>;
    readonly preconditions?: {
        readonly head?: string;
        readonly base?: string;
        readonly providerStateId?: string;
    };
}

FileRecord

Canonical source

export interface FileRecord {
    readonly id: string;
    readonly path: string;
    readonly oldPath?: string;
    readonly changeType: 'added' | 'deleted' | 'modified' | 'renamed' | 'copied' | 'type-changed' | 'unmerged';
    readonly kind: 'text' | 'binary' | 'submodule' | 'unknown';
    readonly included: boolean;
    readonly raw: RawMeasurements;
    readonly lines: LineMeasurements;
    readonly measurement: MeasurementSummary;
    readonly inclusionReasons?: readonly Reason[];
    readonly family?: {
        readonly id: string;
        readonly rawCountsExact: boolean;
        readonly blocksComplete: boolean;
    };
}

FileSet

Canonical source

export interface FileSet {
    readonly complete: boolean;
    readonly total: NumericMeasurement;
}

LabelDefinition

Canonical source

export interface LabelDefinition {
    readonly color: string;
    readonly description: string;
}

LineMeasurements

Canonical source

export interface LineMeasurements {
    readonly added: NumericMeasurement;
    readonly deleted: NumericMeasurement;
    readonly modified: NumericMeasurement;
    readonly changed: NumericMeasurement;
}

MeasurementSummary

Canonical source

export interface MeasurementSummary {
    readonly status: NumericMeasurement['status'];
    readonly reasons: readonly Reason[];
}

NumberValue

Canonical source

export interface NumberValue {
    readonly kind: 'number';
    readonly numericType: NumericType;
    readonly measurement: NumericMeasurement;
}

NumericMeasurement

Canonical source

export type NumericMeasurement = {
    readonly status: 'exact';
    readonly value: number;
} | {
    readonly status: 'bounded';
    readonly lower: number;
    readonly upper: number;
} | {
    readonly status: 'unknown';
    readonly reasons: readonly Reason[];
    readonly lower?: number;
    readonly upper?: number;
} | {
    readonly status: 'unmeasurable';
    readonly reasons: readonly Reason[];
};

NumericType

Canonical source

export type NumericType = 'integer' | 'float';

PathPolicy

Canonical source

export interface PathPolicy {
    readonly includeOnly?: readonly string[];
    readonly exclude?: readonly string[];
    readonly forceInclude?: readonly string[];
}

PlanTarget

Canonical source

export interface PlanTarget {
    readonly repository: string;
    readonly pullRequest: number;
}

RawMeasurements

Canonical source

export interface RawMeasurements {
    readonly added: NumericMeasurement;
    readonly deleted: NumericMeasurement;
    readonly churn: NumericMeasurement;
}

Reason

Canonical source

export interface Reason {
    readonly code: string;
    readonly subject?: string;
    readonly message?: string;
}

Report

Canonical source

export interface Report {
    readonly kind: 'diffdevil.report';
    readonly schemaVersion: '1.0';
    readonly semantics: Semantics;
    readonly source: DiffSourceIdentity;
    readonly measurement: MeasurementSummary;
    readonly fileSet: FileSet;
    readonly totals: Totals;
    readonly files: readonly FileRecord[];
    readonly scopes?: Readonly<Record<string, ScopeRecord>>;
    readonly rules?: Readonly<Record<string, RuleResult>>;
    readonly metrics?: Readonly<Record<string, NumericMeasurement>>;
    readonly metricTypes?: Readonly<Record<string, NumericType>>;
    readonly bands?: Readonly<Record<string, BandResult>>;
    readonly reportId?: string;
    readonly policyId?: string;
}

Result

Canonical source

export type Result<T> = {
    readonly ok: true;
    readonly value: T;
    readonly diagnostics: readonly Diagnostic[];
} | {
    readonly ok: false;
    readonly diagnostics: readonly Diagnostic[];
};

RuleResult

Canonical source

export interface RuleResult {
    readonly decision?: Decision;
    readonly band?: BandResult;
    readonly disposition: 'matched' | 'unmatched' | 'held' | 'fallback';
}

ScopeRecord

Canonical source

export interface ScopeRecord {
    readonly fileIds: readonly string[];
    readonly fileSet: FileSet;
    readonly totals: Totals;
}

SEMANTICS

Canonical source

declare const SEMANTICS: Semantics;

SourceRange

Canonical source

export interface SourceRange {
    readonly source?: string;
    readonly start: number;
    readonly end: number;
}

Totals

Canonical source

export interface Totals {
    readonly raw: RawMeasurements;
    readonly lines: LineMeasurements;
    readonly files: Readonly<Record<string, NumericMeasurement>>;
}

TypeDescriptor

Canonical source

export type TypeDescriptor = 'integer' | 'float' | 'boolean' | 'string' | 'null' | 'never' | {
    readonly kind: 'optional' | 'collection';
    readonly item: TypeDescriptor;
} | {
    readonly kind: 'record';
    readonly fields: Readonly<Record<string, TypeDescriptor>>;
};

Value

Canonical source

export type Value = NumberValue | BooleanValue | {
    readonly kind: 'string';
    readonly value: string;
} | {
    readonly kind: 'null' | 'missing';
} | {
    readonly kind: 'unknown';
    readonly type: TypeDescriptor;
    readonly reasons: readonly Reason[];
} | {
    readonly kind: 'record';
    readonly fields: Readonly<Record<string, Value>>;
} | CollectionValue;

stringify

node_modules/yaml/dist/public-api.d.ts · Dependency identity

export declare function stringify(value: any, options?: DocumentOptions & SchemaOptions & ParseOptions & CreateNodeOptions & ToStringOptions): string;
export declare function stringify(value: any, replacer?: Replacer | null, options?: string | number | (DocumentOptions & SchemaOptions & ParseOptions & CreateNodeOptions & ToStringOptions)): string;

integer

Canonical source

declare const integer: (value: number) => NumberValue;

numberValue

Canonical source

export declare function numberValue(measurement: NumericMeasurement, numericType?: NumericType): NumberValue;

ActionShortcutOptions

Canonical source

export interface ActionShortcutOptions extends Pick<PolicyCompileOptions, 'limits' | 'presets'> {
    readonly entryPoint?: 'root' | 'analyze';
}

compileActionShortcut

Canonical source

export declare function compileActionShortcut(input: Readonly<Record<string, string>>, options?: ActionShortcutOptions): ReturnType<typeof compilePolicyWithSyntax>;

BandDefinition

Canonical source

export interface BandDefinition {
    readonly minimum?: number;
    readonly ranges: readonly BandRange[];
}

BandRange

Canonical source

export interface BandRange {
    readonly id: string;
    readonly lt?: number;
    readonly otherwise?: true;
}

compileBands

Canonical source

export declare function compileBands(input: BandDefinition): Result<CompiledBands>;

CompiledBands

Canonical source

export interface CompiledBands {
    readonly ids: readonly string[];
}

resolveBand

Canonical source

export declare function resolveBand(program: CompiledBands, input: NumericMeasurement): Result<BandResult>;

CompiledPolicy

Canonical source

export interface CompiledPolicy {
    readonly kind: 'diffdevil.policy';
    readonly id: string;
    readonly semantics: Semantics;
    readonly requiredParameters: readonly string[];
}

compilePolicy

Canonical source

export declare function compilePolicy(input?: unknown, options?: PolicyCompileOptions): Result<CompiledPolicy>;

explainPolicy

Canonical source

export declare function explainPolicy(policy: CompiledPolicy): Omit<Normalization, 'generated'>;

PolicyCompileOptions

Canonical source

export interface PolicyCompileOptions extends NormalizeOptions {
    readonly sourceName?: string;
    readonly limits?: EvaluationLimits;
    readonly templateFiles?: Readonly<Record<string, string>>;
}

evaluatePolicy

Canonical source

export declare function evaluatePolicy(policy: CompiledPolicy, report: Report, options?: PolicyEvaluateOptions): Result<PolicyResult>;

evaluatePolicyQuery

Canonical source

export declare function evaluatePolicyQuery(policy: CompiledPolicy, report: Report, selector: PolicyQuerySelector, options?: PolicyEvaluateOptions & {
    readonly context?: 'query' | 'condition';
}): Result<PolicyQueryResult>;

PolicyEvaluateOptions

Canonical source

export interface PolicyEvaluateOptions {
    readonly parameters?: Readonly<Record<string, unknown>>;
    readonly limits?: EvaluationLimits;
    readonly phase?: 'analyze' | 'rules';
}

PolicyQueryResult

Canonical source

export interface PolicyQueryResult {
    readonly report: Report;
    readonly result: EvaluationResult;
}

PolicyQuerySelector

Canonical source

export type PolicyQuerySelector = string | ExpressionSource | Shortcut | {
    readonly query: string;
} | {
    readonly band: string;
};

PolicyResult

Canonical source

export interface PolicyResult {
    readonly report: Report;
    readonly policyId: string;
    readonly rules: Readonly<Record<string, RuleResult>>;
    readonly evidence: readonly Reason[];
    readonly work: number;
}

formatPlan

Canonical source

export declare function formatPlan(plan: EffectPlan, format?: string, options?: TextPresentationOptions): Result<Rendered>;

createPlan

Canonical source

export declare function createPlan(result: PolicyResult, target: PlanTarget, options?: PlanOptions): Result<EffectPlan>;

PlanOptions

Canonical source

export interface PlanOptions {
    readonly definitions?: 'none' | 'ensure' | 'sync';
    readonly rules?: readonly string[];
}

readPlan

Canonical source

export declare function readPlan(input: unknown): Result<EffectPlan>;

PolicySource

Canonical source

export interface PolicySource {
    readonly kind: 'diffdevil.policy-source';
    readonly format: 'json' | 'yaml';
    readonly name: string;
    readonly document: unknown;
}

readPolicyJson

Canonical source

export declare function readPolicyJson(text: string, options?: {
    readonly name?: string;
    readonly limits?: EvaluationLimits;
}): Result<PolicySource>;

commentLifecycle

Canonical source

export declare function commentLifecycle(mode: string | undefined, trigger: string | undefined, rule: 'boolean' | 'band'): {
    mode: 'create' | 'once' | 'upsert' | 'once-per-transition';
    trigger: 'always' | 'matched' | 'band-changed';
};

CompiledTemplate

Canonical source

export interface CompiledTemplate {
    readonly kind: 'diffdevil.template';
    readonly schemaId: string;
}

compileTemplate

Canonical source

export declare function compileTemplate(text: string, schema: Schema, limits?: EvaluationLimits): Result<CompiledTemplate>;

renderTemplate

Canonical source

export declare function renderTemplate(program: CompiledTemplate, environment: EvaluationEnvironment, limits?: EvaluationLimits): Result<string>;

BandLabels

Canonical source

export interface BandLabels {
    readonly group: string;
    readonly byBand: Readonly<Record<string, string>>;
    readonly unknown?: string;
}

BooleanLabels

Canonical source

export interface BooleanLabels {
    readonly add: readonly string[];
    readonly removeWhenFalse?: boolean;
}

CommentDefinition

Canonical source

export type CommentDefinition = {
    readonly mode: 'create' | 'once' | 'upsert' | 'once-per-transition';
    readonly trigger?: 'always' | 'matched' | 'band-changed';
} & ({
    readonly template: string;
    readonly templateFile?: never;
} | {
    readonly templateFile: string;
    readonly template?: never;
});

MetricDefinition

Canonical source

export type MetricDefinition = {
    readonly measure: string;
    readonly scope?: string;
    readonly formula?: never;
} | {
    readonly formula: string;
    readonly measure?: never;
    readonly scope?: never;
};

NormalizedPolicy

Canonical source

export interface NormalizedPolicy {
    readonly document: PolicyDocument;
    readonly semantics: Semantics;
    readonly origins: readonly PolicyOrigin[];
}

ParameterDefinition

Canonical source

export type ParameterDefinition = {
    readonly type: ParameterType;
} & ({
    readonly default: number | boolean | string;
    readonly required?: never;
} | {
    readonly required: true;
    readonly default?: never;
});

ParameterType

Canonical source

export type ParameterType = 'integer' | 'float' | 'boolean' | 'string';

PathOverrides

Canonical source

export interface PathOverrides extends PathPolicy {
    readonly excludeMode?: 'append' | 'replace';
    readonly includeOnlyMode?: 'append' | 'replace';
    readonly forceIncludeMode?: 'append' | 'replace';
}

PolicyDocument

Canonical source

export interface PolicyDocument {
    readonly version: 1;
    readonly language?: 'diffdevil-expr/1';
    readonly presets?: readonly 'size@1'[];
    readonly size?: SizeOverrides;
    readonly measurement?: {
        readonly replacementLines: 'replacement-lines-v1';
    };
    readonly defaults?: {
        readonly paths?: PathPolicy;
    };
    readonly scopes?: Readonly<Record<string, PathPolicy>>;
    readonly parameters?: Readonly<Record<string, ParameterDefinition>>;
    readonly metrics?: Readonly<Record<string, MetricDefinition>>;
    readonly bands?: Readonly<Record<string, BandDefinition & {
        readonly value: string;
    }>>;
    readonly queries?: Readonly<Record<string, {
        readonly expression: string;
    }>>;
    readonly labelGroups?: Readonly<Record<string, readonly string[]>>;
    readonly labelDefinitions?: Readonly<Record<string, LabelDefinition>>;
    readonly rules?: Readonly<Record<string, RuleDefinition>>;
}

PolicyOrigin

Canonical source

export interface PolicyOrigin {
    readonly path: string;
    readonly layer: string;
    readonly replaces?: string;
}

RuleDefinition

Canonical source

export type RuleDefinition = {
    readonly onUnknown?: 'hold' | 'fail';
} & ({
    readonly when: string;
    readonly band?: never;
    readonly effects?: {
        readonly labels?: BooleanLabels;
        readonly comment?: CommentDefinition;
    };
} | {
    readonly band: string;
    readonly when?: never;
    readonly effects?: {
        readonly labels?: BandLabels;
        readonly comment?: CommentDefinition;
    };
});

SizeOverrides

Canonical source

export interface SizeOverrides {
    readonly metric?: string;
    readonly thresholds?: {
        readonly xs: number;
        readonly s: number;
        readonly m: number;
        readonly l: number;
    };
    readonly labels?: {
        readonly xs: string;
        readonly s: string;
        readonly m: string;
        readonly l: string;
        readonly xl: string;
        readonly unknown: string;
    };
}

readPolicyYaml

Canonical source

export declare function readPolicyYaml(text: string, options?: {
    readonly name?: string;
    readonly limits?: EvaluationLimits;
}): Result<PolicySource>;

PresentationDetail

Canonical source

export type PresentationDetail = 'summary' | 'full';

TextPresentationOptions

Canonical source

export interface TextPresentationOptions {
    readonly detail?: PresentationDetail;
    readonly color?: boolean;
}

analyzeChanges

Canonical source

export declare function analyzeChanges(changes: readonly ChangeInput[], options?: AnalyzeOptions): Result<Report>;

analyzeDiff

Canonical source

export declare function analyzeDiff(text: string, options?: AnalyzeOptions): Result<Report>;

AnalyzeOptions

Canonical source

export interface AnalyzeOptions {
    readonly source?: DiffSourceIdentity;
    readonly fileSet?: FileSet;
    readonly paths?: PathPolicy;
    readonly scopes?: Readonly<Record<string, PathPolicy>>;
}

attachScopes

Canonical source

export declare function attachScopes(report: Report, definitions: Readonly<Record<string, PathPolicy>>): Report;

readReport

Canonical source

export declare function readReport(input: unknown): Result<Report>;

withPathPolicy

Canonical source

export declare function withPathPolicy(report: Report, policy?: PathPolicy, scopes?: Readonly<Record<string, PathPolicy>>): Report;

SchemaKind

Canonical source

export type SchemaKind = 'policy' | 'report' | 'plan' | 'query' | 'ast' | 'values';

validateSchema

Canonical source

export declare function validateSchema(kind: SchemaKind, input: unknown): Result<unknown>;

analyzeGit

Canonical source

export declare function analyzeGit(options?: GitOptions): Promise<Result<Report>>;

GitOptions

Canonical source

export interface GitOptions extends Omit<AnalyzeOptions, 'source' | 'fileSet'> {
    readonly cwd?: string;
    readonly base?: string;
    readonly head?: string;
    readonly staged?: boolean;
    readonly comparison?: 'three-dot' | 'direct';
    readonly maximumBytes?: number;
}

ChangeInput

Canonical source

export interface ChangeInput {
    readonly path: string;
    readonly oldPath?: string;
    readonly changeType: FileRecord['changeType'];
    readonly kind: FileRecord['kind'];
    readonly additions?: number;
    readonly deletions?: number;
    readonly patch?: ParsedPatch;
    readonly incompleteReason?: string;
}

parsePatch

Canonical source

export declare function parsePatch(text: string): ParsedPatch;

parseUnifiedDiff

Canonical source

export declare function parseUnifiedDiff(text: string): readonly ChangeInput[];

Readers, structural validation and host adapters

validateSchema validates and freezes inert structure using product-owned schemas. It is not equivalent to readReport, readPlan or compiling policy. Those owners also check relational constraints and supported semantic identities. There is no permission to execute a plan merely because a shape validator returned ok.

The GitHub entry is implemented, not an unavailable future interface. It owns explicit API/Git acquisition, trusted policy loading, label/comment application and definition reconciliation. Source identity, expected comment author, stable occasion, current target and readback remain part of that host contract. Library doubles and an installed consumer do not prove a live repository write.

Persist authored expression/policy source and canonical artifacts, not parser tokens, CSTs, VM instructions or opaque handles. The separate versioned declaration asset is useful contract history but does not override the current package exports. See Language and contracts and Schemas and compatibility for version selection and migration limits.