@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.
Files changed (60) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +131 -0
  3. package/conformance/patterns.json +12 -0
  4. package/dist/chunk-6OQSBZG4.js +709 -0
  5. package/dist/chunk-6OQSBZG4.js.map +1 -0
  6. package/dist/chunk-LONUJCLW.js +50 -0
  7. package/dist/chunk-LONUJCLW.js.map +1 -0
  8. package/dist/cli.js +258 -0
  9. package/dist/cli.js.map +1 -0
  10. package/dist/index.js +41 -0
  11. package/dist/index.js.map +1 -0
  12. package/dist/package-T64HPNWA.js +7 -0
  13. package/dist/package-T64HPNWA.js.map +1 -0
  14. package/dist/src/artifacts/discover.d.ts +28 -0
  15. package/dist/src/check/release.d.ts +12 -0
  16. package/dist/src/check/repository.d.ts +19 -0
  17. package/dist/src/check/snapshot.d.ts +37 -0
  18. package/dist/src/check/version-transitions.d.ts +23 -0
  19. package/dist/src/ci.d.ts +20 -0
  20. package/dist/src/cli.d.ts +2 -0
  21. package/dist/src/contracts-file/matcher.d.ts +2 -0
  22. package/dist/src/contracts-file/parse.d.ts +26 -0
  23. package/dist/src/contracts-file/pin.d.ts +10 -0
  24. package/dist/src/contracts-file/ranges.d.ts +11 -0
  25. package/dist/src/contracts-file/resolve.d.ts +16 -0
  26. package/dist/src/index.d.ts +15 -0
  27. package/dist/src/local.d.ts +8 -0
  28. package/dist/src/managed.d.ts +17 -0
  29. package/dist/src/runtime/handoff.d.ts +11 -0
  30. package/dist/src/versioning/paths.d.ts +2 -0
  31. package/dist/src/versioning/validate.d.ts +13 -0
  32. package/dist/src/versioning/version.d.ts +3 -0
  33. package/docs/agents.md +65 -0
  34. package/docs/checks.md +102 -0
  35. package/docs/contracts-file.md +112 -0
  36. package/docs/cross-repo.md +39 -0
  37. package/docs/practices.md +40 -0
  38. package/docs/taxonomy.md +77 -0
  39. package/docs/versioning.md +73 -0
  40. package/docs/workflow.md +49 -0
  41. package/package.json +50 -0
  42. package/skills/contracts-adopt/SKILL.md +70 -0
  43. package/skills/contracts-change/SKILL.md +74 -0
  44. package/skills/contracts-triage/SKILL.md +46 -0
  45. package/skills/contracts-write/SKILL.md +80 -0
  46. package/skills/contracts-write/references/adr.md +34 -0
  47. package/skills/contracts-write/references/design.md +37 -0
  48. package/skills/contracts-write/references/prd.md +49 -0
  49. package/skills/contracts-write/references/procedure.md +34 -0
  50. package/skills/contracts-write/references/spec.md +41 -0
  51. package/skills/contracts-write/references/standard.md +31 -0
  52. package/templates/agents-section.md +16 -0
  53. package/templates/kinds/adr.md +21 -0
  54. package/templates/kinds/design.md +22 -0
  55. package/templates/kinds/prd.md +29 -0
  56. package/templates/kinds/procedure.md +16 -0
  57. package/templates/kinds/spec.md +17 -0
  58. package/templates/kinds/standard.md +16 -0
  59. package/templates/workflows/check.yml +28 -0
  60. 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;
@@ -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,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
@@ -0,0 +1,2 @@
1
+ export declare const validatePattern: (rawPattern: string) => void;
2
+ export declare const matchesPattern: (path: string, rawPattern: string) => boolean;
@@ -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,2 @@
1
+ /** Normalizes requested document paths and rejects anything the version command cannot change. */
2
+ export declare const selectVersionPaths: (root: string, cwd: string, requested: readonly string[], changedVersionedPaths: ReadonlySet<string>) => ReadonlySet<string>;
@@ -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[];
@@ -0,0 +1,3 @@
1
+ export type BumpLevel = "major" | "minor" | "patch";
2
+ export declare const nextVersion: (version: string, level: BumpLevel) => string;
3
+ export declare const versionArtifactSource: (source: string, baseVersion: string, level: BumpLevel) => string;
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 |