@bizibot/contracts 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +131 -0
- package/conformance/patterns.json +12 -0
- package/dist/chunk-6OQSBZG4.js +709 -0
- package/dist/chunk-6OQSBZG4.js.map +1 -0
- package/dist/chunk-LONUJCLW.js +50 -0
- package/dist/chunk-LONUJCLW.js.map +1 -0
- package/dist/cli.js +258 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.js +41 -0
- package/dist/index.js.map +1 -0
- package/dist/package-T64HPNWA.js +7 -0
- package/dist/package-T64HPNWA.js.map +1 -0
- package/dist/src/artifacts/discover.d.ts +28 -0
- package/dist/src/check/release.d.ts +12 -0
- package/dist/src/check/repository.d.ts +19 -0
- package/dist/src/check/snapshot.d.ts +37 -0
- package/dist/src/check/version-transitions.d.ts +23 -0
- package/dist/src/ci.d.ts +20 -0
- package/dist/src/cli.d.ts +2 -0
- package/dist/src/contracts-file/matcher.d.ts +2 -0
- package/dist/src/contracts-file/parse.d.ts +26 -0
- package/dist/src/contracts-file/pin.d.ts +10 -0
- package/dist/src/contracts-file/ranges.d.ts +11 -0
- package/dist/src/contracts-file/resolve.d.ts +16 -0
- package/dist/src/index.d.ts +15 -0
- package/dist/src/local.d.ts +8 -0
- package/dist/src/managed.d.ts +17 -0
- package/dist/src/runtime/handoff.d.ts +11 -0
- package/dist/src/versioning/paths.d.ts +2 -0
- package/dist/src/versioning/validate.d.ts +13 -0
- package/dist/src/versioning/version.d.ts +3 -0
- package/docs/agents.md +65 -0
- package/docs/checks.md +102 -0
- package/docs/contracts-file.md +112 -0
- package/docs/cross-repo.md +39 -0
- package/docs/practices.md +40 -0
- package/docs/taxonomy.md +77 -0
- package/docs/versioning.md +73 -0
- package/docs/workflow.md +49 -0
- package/package.json +50 -0
- package/skills/contracts-adopt/SKILL.md +70 -0
- package/skills/contracts-change/SKILL.md +74 -0
- package/skills/contracts-triage/SKILL.md +46 -0
- package/skills/contracts-write/SKILL.md +80 -0
- package/skills/contracts-write/references/adr.md +34 -0
- package/skills/contracts-write/references/design.md +37 -0
- package/skills/contracts-write/references/prd.md +49 -0
- package/skills/contracts-write/references/procedure.md +34 -0
- package/skills/contracts-write/references/spec.md +41 -0
- package/skills/contracts-write/references/standard.md +31 -0
- package/templates/agents-section.md +16 -0
- package/templates/kinds/adr.md +21 -0
- package/templates/kinds/design.md +22 -0
- package/templates/kinds/prd.md +29 -0
- package/templates/kinds/procedure.md +16 -0
- package/templates/kinds/spec.md +17 -0
- package/templates/kinds/standard.md +16 -0
- package/templates/workflows/check.yml +28 -0
- package/templates/workflows/release.yml +29 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
export declare const DEFAULT_KIND_FOLDERS: {
|
|
2
|
+
readonly prd: "docs/prds";
|
|
3
|
+
readonly adr: "docs/adr";
|
|
4
|
+
readonly spec: "docs/specs";
|
|
5
|
+
readonly design: "docs/designs";
|
|
6
|
+
readonly standard: "docs/standards";
|
|
7
|
+
readonly procedure: "docs/procedures";
|
|
8
|
+
};
|
|
9
|
+
export type ArtifactKind = keyof typeof DEFAULT_KIND_FOLDERS;
|
|
10
|
+
export type Artifact = {
|
|
11
|
+
id: `${ArtifactKind}/${string}`;
|
|
12
|
+
kind: ArtifactKind;
|
|
13
|
+
path: string;
|
|
14
|
+
status?: "proposed" | "accepted" | "deprecated" | "superseded";
|
|
15
|
+
supersededBy?: string;
|
|
16
|
+
version?: string;
|
|
17
|
+
};
|
|
18
|
+
export type ArtifactDiscovery = {
|
|
19
|
+
artifact?: Artifact;
|
|
20
|
+
errors: string[];
|
|
21
|
+
};
|
|
22
|
+
export declare const extractFrontmatter: (source: string) => {
|
|
23
|
+
source?: string;
|
|
24
|
+
error?: string;
|
|
25
|
+
};
|
|
26
|
+
/** Reads a canonical artifact version even when the file is not yet in a kind folder. */
|
|
27
|
+
export declare const versionFromSource: (source: string) => string | undefined;
|
|
28
|
+
export declare const discoverArtifact: (path: string, source: string, folders?: Record<ArtifactKind, string>) => ArtifactDiscovery;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { checkRepository, type RepositoryDiagnostic } from "./repository.js";
|
|
2
|
+
import type { RepositorySnapshot } from "./snapshot.js";
|
|
3
|
+
/** Validates the merged tree against durable artifact tags, never commit text. */
|
|
4
|
+
export declare const checkReleaseSnapshot: (snapshot: RepositorySnapshot, tags: readonly string[]) => {
|
|
5
|
+
errors: RepositoryDiagnostic[];
|
|
6
|
+
artifacts: ReturnType<typeof checkRepository>["artifacts"];
|
|
7
|
+
};
|
|
8
|
+
/** Tags each versioned artifact whose recorded version has no tag yet (spec §5.3). */
|
|
9
|
+
export declare const tagsToCreate: (artifacts: readonly {
|
|
10
|
+
id: string;
|
|
11
|
+
version?: string;
|
|
12
|
+
}[], tags: readonly string[]) => string[];
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { type Artifact } from "../artifacts/discover.js";
|
|
2
|
+
import type { ContractLine } from "../contracts-file/parse.js";
|
|
3
|
+
export type RepositoryDiagnostic = {
|
|
4
|
+
path: string;
|
|
5
|
+
line?: number;
|
|
6
|
+
message: string;
|
|
7
|
+
};
|
|
8
|
+
export type RepositoryCheck = {
|
|
9
|
+
pin?: string;
|
|
10
|
+
artifacts: Artifact[];
|
|
11
|
+
lines: ContractLine[];
|
|
12
|
+
errors: RepositoryDiagnostic[];
|
|
13
|
+
warnings: RepositoryDiagnostic[];
|
|
14
|
+
};
|
|
15
|
+
/**
|
|
16
|
+
* Validates a complete repository snapshot supplied by a local filesystem or
|
|
17
|
+
* a trusted CI adapter. File contents are parsed only as data.
|
|
18
|
+
*/
|
|
19
|
+
export declare const checkRepository: (files: Readonly<Record<string, string>>, paths?: readonly string[]) => RepositoryCheck;
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { type RepositoryDiagnostic } from "./repository.js";
|
|
2
|
+
import { type ArtifactChange } from "./version-transitions.js";
|
|
3
|
+
import type { ArtifactVersionDiagnostic } from "../versioning/validate.js";
|
|
4
|
+
import type { Artifact } from "../artifacts/discover.js";
|
|
5
|
+
export type RepositorySnapshot = {
|
|
6
|
+
paths: readonly string[];
|
|
7
|
+
contents: Readonly<Record<string, string>>;
|
|
8
|
+
};
|
|
9
|
+
export type FileChange = {
|
|
10
|
+
status: "added" | "modified" | "renamed" | "deleted";
|
|
11
|
+
path: string;
|
|
12
|
+
previousPath?: string;
|
|
13
|
+
};
|
|
14
|
+
export type SnapshotCheckInput = {
|
|
15
|
+
snapshot: RepositorySnapshot;
|
|
16
|
+
base: RepositorySnapshot;
|
|
17
|
+
changes: FileChange[];
|
|
18
|
+
targetIsDefaultBranch: boolean;
|
|
19
|
+
managedFiles?: Readonly<Record<string, string>>;
|
|
20
|
+
};
|
|
21
|
+
export declare const deriveArtifactChanges: (changes: FileChange[], base: RepositorySnapshot, current: RepositorySnapshot, baseArtifacts: Artifact[], currentArtifacts: Artifact[]) => ArtifactChange[];
|
|
22
|
+
export type SnapshotCheckDiagnostic = ({
|
|
23
|
+
category: "repository";
|
|
24
|
+
} & RepositoryDiagnostic) | ({
|
|
25
|
+
category: "version";
|
|
26
|
+
} & ArtifactVersionDiagnostic) | {
|
|
27
|
+
category: "range";
|
|
28
|
+
path: "CONTRACTS";
|
|
29
|
+
line: number;
|
|
30
|
+
message: string;
|
|
31
|
+
};
|
|
32
|
+
export declare const requiresSnapshotContent: (path: string) => boolean;
|
|
33
|
+
export declare const isGoverningArtifactPath: (path: string) => boolean;
|
|
34
|
+
export declare const checkSnapshot: (input: SnapshotCheckInput) => {
|
|
35
|
+
errors: SnapshotCheckDiagnostic[];
|
|
36
|
+
warnings: RepositoryDiagnostic[];
|
|
37
|
+
};
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { type Artifact } from "../artifacts/discover.js";
|
|
2
|
+
import { type ArtifactVersionDiagnostic } from "../versioning/validate.js";
|
|
3
|
+
export type ArtifactChange = {
|
|
4
|
+
base?: Artifact;
|
|
5
|
+
current?: Artifact;
|
|
6
|
+
status: "added" | "modified" | "renamed" | "deleted";
|
|
7
|
+
/** Whether content other than the frontmatter version changed. */
|
|
8
|
+
changedBeyondVersion?: boolean;
|
|
9
|
+
/** Base content for a rename, including a move into a kind folder. */
|
|
10
|
+
previousSource?: string;
|
|
11
|
+
};
|
|
12
|
+
export type VersionTransitionCheck = {
|
|
13
|
+
errors: ArtifactVersionDiagnostic[];
|
|
14
|
+
};
|
|
15
|
+
export type VersionTransitionCheckOptions = {
|
|
16
|
+
/** The version rules begin only after the repository has adopted CONTRACTS. */
|
|
17
|
+
baseHasContracts?: boolean;
|
|
18
|
+
};
|
|
19
|
+
/**
|
|
20
|
+
* Applies document-owned version rules to changes supplied by either the local
|
|
21
|
+
* Git adapter or GitHub's authoritative PR-files API adapter.
|
|
22
|
+
*/
|
|
23
|
+
export declare const checkArtifactVersionTransitions: (changes: ArtifactChange[], { baseHasContracts }?: VersionTransitionCheckOptions) => VersionTransitionCheck;
|
package/dist/src/ci.d.ts
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { FileChange, RepositorySnapshot } from "./check/snapshot.js";
|
|
2
|
+
export type CiFileOverlay = {
|
|
3
|
+
status: "added" | "modified" | "deleted" | "renamed";
|
|
4
|
+
path: string;
|
|
5
|
+
previousPath?: string;
|
|
6
|
+
/** Present only when snapshot validation requires the file's bytes. */
|
|
7
|
+
content?: string;
|
|
8
|
+
};
|
|
9
|
+
/** Builds a post-PR sparse snapshot from trusted base data and inert API bytes. */
|
|
10
|
+
export declare const overlayCiSnapshot: (base: RepositorySnapshot, overlays: CiFileOverlay[]) => {
|
|
11
|
+
snapshot: RepositorySnapshot;
|
|
12
|
+
changes: FileChange[];
|
|
13
|
+
};
|
|
14
|
+
export type GitHubPullRequestData = {
|
|
15
|
+
baseSha: string;
|
|
16
|
+
targetIsDefaultBranch: boolean;
|
|
17
|
+
overlays: CiFileOverlay[];
|
|
18
|
+
};
|
|
19
|
+
/** Reads a pull request as inert API data; it never fetches or evaluates PR code. */
|
|
20
|
+
export declare const readGitHubPullRequest: (repository: string, pullNumber: string, token: string, apiUrl?: string, fetcher?: typeof fetch) => Promise<GitHubPullRequestData>;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
export type ContractEntry = {
|
|
2
|
+
kind: "linked";
|
|
3
|
+
path: string;
|
|
4
|
+
} | {
|
|
5
|
+
kind: "versioned";
|
|
6
|
+
id: string;
|
|
7
|
+
range: string;
|
|
8
|
+
} | {
|
|
9
|
+
kind: "external";
|
|
10
|
+
repository: string;
|
|
11
|
+
id: string;
|
|
12
|
+
range: string;
|
|
13
|
+
};
|
|
14
|
+
export type ContractLine = {
|
|
15
|
+
line: number;
|
|
16
|
+
pattern: string;
|
|
17
|
+
entries: ContractEntry[];
|
|
18
|
+
};
|
|
19
|
+
export type ContractParseResult = {
|
|
20
|
+
lines: ContractLine[];
|
|
21
|
+
errors: Array<{
|
|
22
|
+
line: number;
|
|
23
|
+
message: string;
|
|
24
|
+
}>;
|
|
25
|
+
};
|
|
26
|
+
export declare const parseContractsFile: (source: string) => ContractParseResult;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
export type ContractPin = {
|
|
2
|
+
version?: string;
|
|
3
|
+
error?: string;
|
|
4
|
+
};
|
|
5
|
+
/** Parses the required, first-line package pin without interpreting any rules. */
|
|
6
|
+
export declare const parseContractsPin: (source: string) => ContractPin;
|
|
7
|
+
/** Replaces any old pin while preserving all adopter-owned CONTRACTS rules. */
|
|
8
|
+
export declare const withContractsPin: (source: string | undefined, version: string) => string;
|
|
9
|
+
/** `init` only changes an adopted repository's pin when explicitly updating it. */
|
|
10
|
+
export declare const contractsSourceForInit: (source: string | undefined, version: string, update: boolean) => string;
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { Artifact } from "../artifacts/discover.js";
|
|
2
|
+
import type { ContractLine } from "./parse.js";
|
|
3
|
+
export type RangeDiagnostic = {
|
|
4
|
+
line: number;
|
|
5
|
+
message: string;
|
|
6
|
+
};
|
|
7
|
+
/**
|
|
8
|
+
* Checks ranges actually selected for each path in a complete snapshot. Local
|
|
9
|
+
* artifact files never select themselves, even through a broad pattern.
|
|
10
|
+
*/
|
|
11
|
+
export declare const validateContractRanges: (paths: Iterable<string>, lines: ContractLine[], artifacts: Artifact[]) => RangeDiagnostic[];
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { ContractEntry, ContractLine } from "./parse.js";
|
|
2
|
+
import type { Artifact } from "../artifacts/discover.js";
|
|
3
|
+
export type ResolvedContractEntry = {
|
|
4
|
+
entry: ContractEntry;
|
|
5
|
+
line: number;
|
|
6
|
+
};
|
|
7
|
+
export declare const resolveGoverningEntryDetails: (path: string, lines: ContractLine[], artifact?: Artifact) => ResolvedContractEntry[];
|
|
8
|
+
export declare const resolveGoverningEntries: (path: string, lines: ContractLine[], artifact?: Artifact) => ContractEntry[];
|
|
9
|
+
export declare const resolveArtifactGoverningEntries: (artifact: Artifact, lines: ContractLine[]) => ContractEntry[];
|
|
10
|
+
export declare const findDependentLines: (idOrPath: string, lines: ContractLine[]) => ContractLine[];
|
|
11
|
+
export type ContractDiagnostic = {
|
|
12
|
+
line: number;
|
|
13
|
+
message: string;
|
|
14
|
+
};
|
|
15
|
+
export declare const findArtifactWarnings: (lines: ContractLine[], artifacts: Artifact[]) => ContractDiagnostic[];
|
|
16
|
+
export declare const validateLinkedArtifactReferences: (lines: ContractLine[], artifacts: Artifact[]) => ContractDiagnostic[];
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
export declare const JSON_SCHEMA_VERSION = 1;
|
|
2
|
+
export type JsonEnvelope<T> = {
|
|
3
|
+
schemaVersion: typeof JSON_SCHEMA_VERSION;
|
|
4
|
+
data: T;
|
|
5
|
+
};
|
|
6
|
+
export declare const toJsonEnvelope: <T>(data: T) => JsonEnvelope<T>;
|
|
7
|
+
export { validateArtifactVersionTransition, type ArtifactVersionDiagnostic, type ArtifactVersionTransition } from "./versioning/validate.js";
|
|
8
|
+
export { checkArtifactVersionTransitions, type ArtifactChange, type VersionTransitionCheck, type VersionTransitionCheckOptions } from "./check/version-transitions.js";
|
|
9
|
+
export { checkRepository, type RepositoryCheck, type RepositoryDiagnostic } from "./check/repository.js";
|
|
10
|
+
export { checkSnapshot, type SnapshotCheckDiagnostic, type SnapshotCheckInput } from "./check/snapshot.js";
|
|
11
|
+
export { checkReleaseSnapshot } from "./check/release.js";
|
|
12
|
+
export { readGitSnapshot, readLocalBase, readLocalChanges, readLocalSnapshot, runGit } from "./local.js";
|
|
13
|
+
export { overlayCiSnapshot, readGitHubPullRequest, type CiFileOverlay, type GitHubPullRequestData } from "./ci.js";
|
|
14
|
+
export { validateContractRanges, type RangeDiagnostic } from "./contracts-file/ranges.js";
|
|
15
|
+
export { parseContractsPin, withContractsPin, contractsSourceForInit, type ContractPin } from "./contracts-file/pin.js";
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { RepositorySnapshot } from "./check/snapshot.js";
|
|
2
|
+
import type { FileChange } from "./check/snapshot.js";
|
|
3
|
+
export declare const readLocalSnapshot: (root: string) => Promise<RepositorySnapshot>;
|
|
4
|
+
export declare const runGit: (root: string, args: string[]) => Promise<string>;
|
|
5
|
+
export declare const readGitSnapshot: (root: string, revision: string, additionalContents?: readonly string[]) => Promise<RepositorySnapshot>;
|
|
6
|
+
export declare const readLocalChanges: (root: string, base: string) => Promise<FileChange[]>;
|
|
7
|
+
/** Uses the remote default branch for branch-wide local preview, with a safe single-commit fallback. */
|
|
8
|
+
export declare const readLocalBase: (root: string) => Promise<string>;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/** Canonical install folders used by `init --agents` and snapshot validation. */
|
|
2
|
+
export declare const AGENT_SKILL_FOLDERS: {
|
|
3
|
+
readonly claude: ".claude/skills";
|
|
4
|
+
readonly copilot: ".github/skills";
|
|
5
|
+
};
|
|
6
|
+
export declare const MANAGED_MARKER = "@bizibot/contracts";
|
|
7
|
+
export declare const managedProcedureSource: (version: string, workflow: string) => string;
|
|
8
|
+
/**
|
|
9
|
+
* Loads the exact package-owned bytes for managed files present in a snapshot.
|
|
10
|
+
* The caller supplies them to the pure checker, so CI can inspect PR data
|
|
11
|
+
* without executing or importing anything from the PR.
|
|
12
|
+
*/
|
|
13
|
+
export declare const loadManagedFileExpectations: (contents: Readonly<Record<string, string>>, pin?: string) => Promise<Record<string, string>>;
|
|
14
|
+
export declare const managedFileDiagnostics: (contents: Readonly<Record<string, string>>, expected: Readonly<Record<string, string>>) => {
|
|
15
|
+
path: string;
|
|
16
|
+
message: string;
|
|
17
|
+
}[];
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export declare const PINNED_REEXEC = "CONTRACTS_PINNED_REEXEC";
|
|
2
|
+
export declare class InvalidContractPinError extends Error {
|
|
3
|
+
}
|
|
4
|
+
export type HandoffPlan = {
|
|
5
|
+
version?: string;
|
|
6
|
+
error?: string;
|
|
7
|
+
};
|
|
8
|
+
export declare const handoffPlan: (contracts: string | undefined, ownVersion: string) => HandoffPlan;
|
|
9
|
+
export declare const handoffVersion: (plan: HandoffPlan, alreadyReexecuted: boolean) => string | undefined;
|
|
10
|
+
/** Re-executes the pinned package before command dispatch; intentionally tiny for old global installs. */
|
|
11
|
+
export declare const handoffToPinnedVersion: (root: string | undefined, ownVersion: string, args: readonly string[]) => Promise<number | undefined>;
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { Artifact } from "../artifacts/discover.js";
|
|
2
|
+
export type ArtifactVersionDiagnostic = {
|
|
3
|
+
artifact: string;
|
|
4
|
+
message: string;
|
|
5
|
+
};
|
|
6
|
+
export type ArtifactVersionTransition = {
|
|
7
|
+
base?: Artifact;
|
|
8
|
+
current?: Artifact;
|
|
9
|
+
changed: boolean;
|
|
10
|
+
changedBeyondVersion?: boolean;
|
|
11
|
+
};
|
|
12
|
+
/** Validates an author-selected, one-step SemVer transition. */
|
|
13
|
+
export declare const validateArtifactVersionTransition: (transition: ArtifactVersionTransition) => ArtifactVersionDiagnostic[];
|
package/docs/agents.md
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# Agents
|
|
2
|
+
|
|
3
|
+
`@bizibot/contracts` governs your work; it doesn't run it. Its agent material
|
|
4
|
+
does two things: it teaches agents to use the CLI, and it helps them write each
|
|
5
|
+
kind of doc well. Skills always call the CLI, so the logic stays deterministic.
|
|
6
|
+
|
|
7
|
+
## Always-on rules: `AGENTS.md`
|
|
8
|
+
|
|
9
|
+
A skill loads only when its description matches the task at hand, so rules an
|
|
10
|
+
agent must follow on *every* task can't live in a skill. `contracts init`
|
|
11
|
+
writes a managed section into your `AGENTS.md`:
|
|
12
|
+
|
|
13
|
+
- Before editing a file, run `contracts list <path>` and follow the docs that
|
|
14
|
+
govern it.
|
|
15
|
+
- When records conflict, the higher one wins (`prd → adr → spec → design → code`).
|
|
16
|
+
- After changing a versioned doc, set its next version with
|
|
17
|
+
`contracts version <level> <path>`. Use major when the change adds, changes,
|
|
18
|
+
or removes an obligation. The check verifies the result.
|
|
19
|
+
- Never edit a managed file.
|
|
20
|
+
- Run `contracts check` before pushing.
|
|
21
|
+
|
|
22
|
+
## Skills: loaded on demand
|
|
23
|
+
|
|
24
|
+
| Skill | Used when | Teaches |
|
|
25
|
+
|---|---|---|
|
|
26
|
+
| `contracts-write` | Writing or revising a doc | What belongs in each kind and what doesn't, its required sections, and how to state obligations so bumps are clear. One reference file per kind, loaded only for the kind being written |
|
|
27
|
+
| `contracts-change` | Changing a governing doc | Picking each changed doc's level, setting its version, and updating everything `list --dependents` shows, in the same PR |
|
|
28
|
+
| `contracts-triage` | Handling an Issue | Mapping the affected files to their contracts and labeling `defect` or `contract-gap` |
|
|
29
|
+
| `contracts-adopt` | Adopting in an existing repo | Sorting existing docs into kinds and proposing `CONTRACTS` lines |
|
|
30
|
+
|
|
31
|
+
Skills use the open Agent Skills `SKILL.md` format, with no vendor-specific
|
|
32
|
+
fields.
|
|
33
|
+
|
|
34
|
+
## Installation
|
|
35
|
+
|
|
36
|
+
`contracts init --agents claude,copilot` names the agents you use. For each one, it writes the skills
|
|
37
|
+
into that agent's skills folder (for example `.claude/skills/` or
|
|
38
|
+
`.github/skills/`) and writes the `AGENTS.md` section.
|
|
39
|
+
|
|
40
|
+
- The procedure, `AGENTS.md` section, and skills are managed files: `contracts
|
|
41
|
+
init --update` finds them by their markers and refreshes them after an
|
|
42
|
+
upgrade, and `contracts check` flags hand edits. The workflow shims are
|
|
43
|
+
adopter-owned so their runner and setup can be tailored safely.
|
|
44
|
+
- Your own files are never touched.
|
|
45
|
+
- Agents run `contracts` like people do. The global command, or
|
|
46
|
+
`npx @bizibot/contracts`, always runs the version pinned in `CONTRACTS`, so
|
|
47
|
+
an agent never needs the package installed in the project.
|
|
48
|
+
|
|
49
|
+
## Who runs what
|
|
50
|
+
|
|
51
|
+
| Command | Human | Agent | CI |
|
|
52
|
+
|---|---|---|---|
|
|
53
|
+
| `init` | Once, to adopt; `--update` after upgrades | When asked to adopt (`contracts-adopt`) | — |
|
|
54
|
+
| `new <kind> <slug>` | When starting a doc | When starting a doc (`contracts-write`) | — |
|
|
55
|
+
| `version <level> [path …]` | After changing a versioned doc | After changing a versioned doc (`contracts-change`) | — |
|
|
56
|
+
| `list <path-or-id>` | When reviewing or curious | Before editing any file (always-on rule) | — |
|
|
57
|
+
| `list … --dependents` | When planning a change | Before changing a doc (`contracts-change`) | — |
|
|
58
|
+
| `check` | Optional preview before pushing | Before pushing (always-on rule) | **The authority** on every PR |
|
|
59
|
+
| `release` | — | — | **Only** CI, after merge |
|
|
60
|
+
|
|
61
|
+
## AI review is yours to add
|
|
62
|
+
|
|
63
|
+
The package contains no AI. Every command supports `--json`, so you can add an
|
|
64
|
+
AI reviewer that reads a contract diff and suggests a bump level. It stays
|
|
65
|
+
advisory: the author's version is the decision, and review checks it.
|
package/docs/checks.md
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# Checks and CI
|
|
2
|
+
|
|
3
|
+
`contracts init` writes two adopter-owned thin GitHub workflows. All the logic
|
|
4
|
+
lives in the CLI. Each workflow reads the version pinned in `CONTRACTS` and runs
|
|
5
|
+
exactly that version with `npx`, with no install step. Customize the runner in
|
|
6
|
+
the shims without changing the contracts implementation.
|
|
7
|
+
|
|
8
|
+
## The PR check
|
|
9
|
+
|
|
10
|
+
It runs on every pull request. Make it a required status check.
|
|
11
|
+
|
|
12
|
+
It:
|
|
13
|
+
1. verifies every changed doc's version moved exactly one step, and every
|
|
14
|
+
unchanged doc kept its version (see
|
|
15
|
+
[Versioning](versioning.md#docs-are-versioned-in-the-pr));
|
|
16
|
+
2. fails if any versioned range in `CONTRACTS` is unsatisfied by the actual
|
|
17
|
+
versions in the PR. This applies only to PRs that target the default branch. PRs into
|
|
18
|
+
other branches (for example, stacked PRs) get the validity checks, and ranges are enforced once the change reaches a PR to the default
|
|
19
|
+
branch;
|
|
20
|
+
3. fails on:
|
|
21
|
+
- invalid `CONTRACTS`;
|
|
22
|
+
- a version rule violation: a changed doc that didn't move exactly one
|
|
23
|
+
step, an unchanged doc whose version moved, a new doc not at `0.1.0`, or
|
|
24
|
+
a removed version; and
|
|
25
|
+
- an edited managed file;
|
|
26
|
+
4. warns, without failing, about:
|
|
27
|
+
- dependencies on deprecated or superseded docs;
|
|
28
|
+
- dead patterns: `CONTRACTS` lines that match no file, usually left behind
|
|
29
|
+
by moved code; and
|
|
30
|
+
5. comments with the version changes, the failures, the warnings, and
|
|
31
|
+
reminders for linked docs.
|
|
32
|
+
|
|
33
|
+
### CI is the authority
|
|
34
|
+
|
|
35
|
+
Only the run in CI decides whether a PR passes. You or an agent can run
|
|
36
|
+
`contracts check` locally to catch problems before you push. It uses the same
|
|
37
|
+
logic, but it's only a preview.
|
|
38
|
+
|
|
39
|
+
### What it can't catch
|
|
40
|
+
|
|
41
|
+
The check reads versions and wiring, not behavior. It can't tell:
|
|
42
|
+
- that code doesn't do what its spec says (tests and review catch that);
|
|
43
|
+
- that a doc's chosen level is right, for example a breaking change bumped
|
|
44
|
+
as minor (review catches that); or
|
|
45
|
+
- that a linked doc has drifted (the reminders and review catch that).
|
|
46
|
+
|
|
47
|
+
### It never runs PR code
|
|
48
|
+
|
|
49
|
+
The check triggers on `pull_request_target`, which uses the workflow definition
|
|
50
|
+
from your default branch. It runs the version pinned in the default branch's
|
|
51
|
+
`CONTRACTS`, never the PR's, and reads the PR's changed files, `CONTRACTS` and
|
|
52
|
+
doc contents **as data**. It
|
|
53
|
+
never checks out, installs, or executes the PR branch.
|
|
54
|
+
|
|
55
|
+
The result:
|
|
56
|
+
- It's safe on **self-hosted runners**, including ones that share a host with
|
|
57
|
+
other services.
|
|
58
|
+
- A PR that changes the checker is checked by the default branch's version.
|
|
59
|
+
|
|
60
|
+
## The release job
|
|
61
|
+
|
|
62
|
+
It runs after a push to the default branch, ideally after your own verification
|
|
63
|
+
passes. It:
|
|
64
|
+
1. reruns the range check on the merged tree and confirms no doc's version
|
|
65
|
+
went below its latest tag or was removed from a doc, and stops without tagging
|
|
66
|
+
anything if either fails. It never reads commit messages, so any merge
|
|
67
|
+
method works;
|
|
68
|
+
2. tags every doc whose version has no tag yet (`spec/auth@3.0.0`), without
|
|
69
|
+
editing any file or making a commit; and
|
|
70
|
+
3. reports what it tagged, as text or `--json`.
|
|
71
|
+
|
|
72
|
+
**The framework never releases, publishes or deploys.** Versioning your
|
|
73
|
+
product, changelogs, npm publishing and deploys stay with your own release
|
|
74
|
+
tooling.
|
|
75
|
+
|
|
76
|
+
## Runners
|
|
77
|
+
|
|
78
|
+
| Runner | Works? | Notes |
|
|
79
|
+
|---|---|---|
|
|
80
|
+
| GitHub-hosted | ✅ | The default |
|
|
81
|
+
| Self-hosted | ✅ | The data-only design is what makes this safe |
|
|
82
|
+
|
|
83
|
+
Neither workflow installs your project's dependencies. `npx` downloads the
|
|
84
|
+
pinned package, checks it against the registry's hash, and runs it. A
|
|
85
|
+
self-hosted runner needs Node, which `actions/setup-node` provides.
|
|
86
|
+
|
|
87
|
+
## Customizing the workflows
|
|
88
|
+
|
|
89
|
+
`init` writes `.github/workflows/contracts-check.yml` and
|
|
90
|
+
`contracts-release.yml` once. They're yours: edit them freely, and `init
|
|
91
|
+
--update` never overwrites them. Keep the steps that read the pin and run
|
|
92
|
+
`contracts` as they are; change only how the job gets a runner.
|
|
93
|
+
|
|
94
|
+
Common edit:
|
|
95
|
+
- **Self-hosted runner:** replace `runs-on: ubuntu-latest` with your runner
|
|
96
|
+
labels, for example `runs-on: [self-hosted, macOS, ARM64]`.
|
|
97
|
+
|
|
98
|
+
## Enforcement caveat
|
|
99
|
+
|
|
100
|
+
The check blocks merges only where GitHub enforces your rulesets or branch
|
|
101
|
+
protection. GitHub Free doesn't enforce rulesets on private repositories, so
|
|
102
|
+
there the check reports failures but can't stop a merge.
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# The CONTRACTS file
|
|
2
|
+
|
|
3
|
+
`CONTRACTS` sits at the repository root. Each line maps a path pattern to the
|
|
4
|
+
docs that govern the matching files.
|
|
5
|
+
|
|
6
|
+
```
|
|
7
|
+
# @bizibot/contracts 0.1.0
|
|
8
|
+
* docs/standards/code-style.md
|
|
9
|
+
/src/auth/ spec/auth@^2 adr/sessions@^1
|
|
10
|
+
/src/auth/oauth/ spec/oauth@^1 spec/auth@^2.4
|
|
11
|
+
/scripts/release.ts docs/procedures/releasing.md
|
|
12
|
+
|
|
13
|
+
# docs govern docs too
|
|
14
|
+
/docs/specs/auth.md adr/sessions@^1
|
|
15
|
+
/docs/designs/sso.md spec/auth@^2
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Lines
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
<path-pattern> <entry> [<entry> ...]
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
- Lines starting with `#` are comments.
|
|
25
|
+
- Patterns can match code or docs, so one file covers every dependency.
|
|
26
|
+
|
|
27
|
+
## The version pin
|
|
28
|
+
|
|
29
|
+
The first line pins the exact `@bizibot/contracts` version this repository
|
|
30
|
+
uses:
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
# @bizibot/contracts 0.1.0
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`init` writes it and `init --update` changes it. Every `contracts` command and
|
|
37
|
+
both workflows run this version, so people, agents and CI always agree. The
|
|
38
|
+
check fails if the line is missing or isn't an exact version. See
|
|
39
|
+
[Installing and upgrading](../README.md#installing-and-upgrading).
|
|
40
|
+
|
|
41
|
+
## Pattern syntax
|
|
42
|
+
|
|
43
|
+
The syntax looks like `CODEOWNERS`, but it's defined exactly here, so every
|
|
44
|
+
command and every machine gets the same answer.
|
|
45
|
+
|
|
46
|
+
| Pattern | Matches |
|
|
47
|
+
|---|---|
|
|
48
|
+
| `README.md` | no `/` except at the end, so it matches at any depth: `README.md`, `a/b/README.md` |
|
|
49
|
+
| `/src/auth/` | a leading `/` or an inner `/` anchors it to the root; a trailing `/` means a directory and everything under it |
|
|
50
|
+
| `docs/` | any `docs` directory, at any depth |
|
|
51
|
+
| `*.md` | `*` = anything except `/` |
|
|
52
|
+
| `src/**/test.ts` | `**` = zero or more whole folders |
|
|
53
|
+
| `file?.ts` | `?` = one character except `/` |
|
|
54
|
+
| `my\ file.md` | `\` escapes the next character, here a space |
|
|
55
|
+
|
|
56
|
+
- Paths are relative to the repo root, use `/`, and are case-sensitive.
|
|
57
|
+
- No character classes, no braces, and **no `!` negation** in `CONTRACTS`.
|
|
58
|
+
Lines only add, so a narrower line can't remove what a broader line applies.
|
|
59
|
+
- The package ships a conformance suite of pattern, path and expected-result
|
|
60
|
+
cases. It's the definitive reference.
|
|
61
|
+
|
|
62
|
+
## Entries
|
|
63
|
+
|
|
64
|
+
| Entry | Kind | Behavior |
|
|
65
|
+
|---|---|---|
|
|
66
|
+
| `spec/auth@^2` | versioned | The range must be satisfied, or the PR check fails |
|
|
67
|
+
| `docs/standards/api-design.md` | linked | Non-blocking review reminders |
|
|
68
|
+
| `acme/platform:policy/secrets@^1` | versioned, other repo | Checked against that repo's tags (see [Across repos](cross-repo.md)) |
|
|
69
|
+
|
|
70
|
+
- Ranges use npm SemVer syntax (`^2`, `~2.4`, `>=2.1 <3`).
|
|
71
|
+
- A versioned entry must name a doc whose frontmatter has a `version`.
|
|
72
|
+
- Reference each doc in one form only. Linking `docs/specs/auth.md` on one line
|
|
73
|
+
and versioning `spec/auth@^2` on another is an error, because they're the
|
|
74
|
+
same doc.
|
|
75
|
+
- Another repo's docs are separate from yours: `acme/platform:spec/auth` isn't
|
|
76
|
+
your `spec/auth`.
|
|
77
|
+
|
|
78
|
+
## Matching: merge, not replace
|
|
79
|
+
|
|
80
|
+
**Every** line that matches a file applies, and their entries merge. If two
|
|
81
|
+
matching lines name the same id, the later line's range wins.
|
|
82
|
+
|
|
83
|
+
In the example above, `/src/auth/oauth/token.ts` is governed by:
|
|
84
|
+
- `docs/standards/code-style.md` (from `*`)
|
|
85
|
+
- `adr/sessions@^1` (from `/src/auth/`)
|
|
86
|
+
- `spec/oauth@^1`
|
|
87
|
+
- `spec/auth@^2.4` (the later line wins over `^2`)
|
|
88
|
+
|
|
89
|
+
This deliberately differs from `CODEOWNERS`, where the last match replaces the
|
|
90
|
+
others. A file has one set of owners, but it's usually governed by several docs.
|
|
91
|
+
|
|
92
|
+
## How CONTRACTS relates to CODEOWNERS
|
|
93
|
+
|
|
94
|
+
| | CODEOWNERS | CONTRACTS |
|
|
95
|
+
|---|---|---|
|
|
96
|
+
| Question it answers | Who must approve changes here? | What must this conform to? |
|
|
97
|
+
| Maps paths to | People and teams | Docs, at version ranges |
|
|
98
|
+
| Enforced by | Required reviews | A required check |
|
|
99
|
+
|
|
100
|
+
They complement each other. Give each governing doc an owner in `CODEOWNERS`,
|
|
101
|
+
and a breaking change will both request the right reviewers and show what else
|
|
102
|
+
must change.
|
|
103
|
+
|
|
104
|
+
## Validity
|
|
105
|
+
|
|
106
|
+
`contracts check` fails on:
|
|
107
|
+
- invalid syntax
|
|
108
|
+
- an unknown id
|
|
109
|
+
- a reference to a non-governing file
|
|
110
|
+
|
|
111
|
+
It doesn't judge which docs depend on which. That's what `CONTRACTS` declares,
|
|
112
|
+
and review decides whether it makes sense.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Across repos
|
|
2
|
+
|
|
3
|
+
> **Planned for after v1.**
|
|
4
|
+
|
|
5
|
+
A doc in one repository can govern code in another.
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
# CONTRACTS in acme/billing
|
|
9
|
+
/src/ acme/platform:policy/secrets@^2 spec/billing@^3
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## How it resolves
|
|
13
|
+
|
|
14
|
+
- **Tags are the registry.** `contracts release` in `acme/platform` already
|
|
15
|
+
tags `policy/secrets@2.1.0`, and the consumer's check reads those tags.
|
|
16
|
+
There's no extra service to run.
|
|
17
|
+
- Private repositories need a token, preferably from a GitHub App.
|
|
18
|
+
|
|
19
|
+
## When the upstream breaks
|
|
20
|
+
|
|
21
|
+
You can't merge atomically across repositories, so a cross-repo break notifies
|
|
22
|
+
instead of blocking.
|
|
23
|
+
|
|
24
|
+
1. `acme/platform` releases `policy/secrets@3.0.0`.
|
|
25
|
+
2. Its release job notifies its known consumers (`repository_dispatch`).
|
|
26
|
+
3. Each consumer opens a `contract-upgrade` Issue: "policy/secrets 3.0.0
|
|
27
|
+
released; you pin ^2".
|
|
28
|
+
4. The consumer stays valid on `^2` until it upgrades. The old version is still
|
|
29
|
+
readable at its tag.
|
|
30
|
+
|
|
31
|
+
Before the upstream merges, its PR check can comment with the consumers that the
|
|
32
|
+
change affects.
|
|
33
|
+
|
|
34
|
+
## The rule
|
|
35
|
+
|
|
36
|
+
| | Same repo | Across repos |
|
|
37
|
+
|---|---|---|
|
|
38
|
+
| A broken range | Blocks the merge | A warning plus an Issue in the consumer |
|
|
39
|
+
| Why | An atomic fix is possible | It isn't |
|