artifact-contracts 0.1.1 → 0.2.0

package/README.md

@@ -1,13 +1,265 @@
 # artifact-contracts
 
-Declarative contract DSL for managing AI-generated artifacts — versioning, validation, and lifecycle control.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Installation
+Declarative artifact registry — define file physical properties, resolve paths to artifact IDs, and detect definition overlaps. Part of the `*-contracts` family alongside [cli-contracts](https://www.npmjs.com/package/cli-contracts) and [agent-contracts](https://www.npmjs.com/package/agent-contracts).
+
+```text
+artifact-contracts          cli-contracts
+(file properties)            (command interfaces)
+      ▲                           ▲
+      │ $ref                       │ cli_contract
+      │                           │
+      └───────── agent-contracts ──┘
+                (team contracts)
+```
+
+artifact-contracts answers one question: **"What are the files in this project?"** It declares the physical nature of every file — type, authority, editability, change control — without referencing tools, agents, or commands. agent-contracts references artifact IDs when assigning ownership and permissions.
+
+## Quick Start
 
 ```bash
 npm install artifact-contracts
 ```
 
+Create `artifact-contracts.yaml` in your project root:
+
+```yaml
+artifactContracts: 0.1.0
+
+system:
+  id: my-project
+  name: My Project
+
+artifacts:
+  application-code:
+    type: source
+    authority: canonical
+    path_patterns:
+      - "src/**/*.ts"
+    exclude_patterns:
+      - "src/generated/**"
+
+  generated-api:
+    type: generated-code
+    authority: generated
+    path_patterns:
+      - "src/generated/**/*.ts"
+
+  migration-files:
+    type: source
+    authority: canonical
+    change_control: approval-required
+    path_patterns:
+      - "db/migrations/**/*.sql"
+```
+
+```bash
+# Validate definitions
+npx artifact-contracts validate
+
+# Check for file overlaps against real repository files
+npx artifact-contracts validate --check-files
+
+# Ask "what is this file?"
+npx artifact-contracts explain src/generated/client.ts
+# → artifact: generated-api
+#   authority: generated
+#   manual edit: forbidden
+#   change control: regeneration-required
+
+# LLM-powered semantic audit (requires agent-contracts-runtime + API key)
+npx artifact-contracts audit --adapter openai
+```
+
+## Design Principles
+
+- **Pure artifact registry**: Declares file properties only. No references to tools, agents, or commands — no circular dependencies
+- **Path → artifact ID resolution**: Every file in the project resolves to at most one artifact ID. Ambiguity (overlap) is a definition error
+- **Authority-driven defaults**: `authority` determines sensible defaults for `manual_edit` and `change_control`, reducing boilerplate
+- **Agent-native**: Structured output for all commands. LLM agents and CI systems consume the same interface as humans
+
+## DSL Schema
+
+### Required Fields
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `type` | string | Artifact kind: `source`, `generated-code`, `generated-doc`, `generated-config`, `config`, `lockfile`, `schema`, etc. |
+| `authority` | enum | `canonical` (human-authored SSoT), `derived` (derived from SSoT), `generated` (fully tool-generated), `control` (configuration/settings) |
+| `path_patterns` | string[] | Glob patterns for files belonging to this artifact |
+
+### Optional Fields
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `description` | string | Human-readable description |
+| `manual_edit` | enum | `allowed`, `discouraged`, `forbidden`. Default based on authority |
+| `change_control` | enum | `none`, `approval-required`, `regeneration-required`. Default based on authority |
+| `exclude_patterns` | string[] | Glob patterns to exclude from `path_patterns` |
+| `visibility` | enum | `public`, `internal`, `private`. Default: `internal` |
+| `states` | string[] | Valid states for this artifact |
+
+### Authority Defaults
+
+`authority` determines sensible defaults. Explicit values override these.
+
+| authority | manual_edit | change_control | Typical use |
+|-----------|-------------|----------------|-------------|
+| `canonical` | `allowed` | `none` | Human-authored source of truth |
+| `derived` | `forbidden` | `regeneration-required` | Derived from another SSoT |
+| `generated` | `forbidden` | `regeneration-required` | Fully tool-generated files |
+| `control` | `allowed` | `approval-required` | Configuration and settings |
+
+### Artifact ID Naming
+
+IDs are YAML keys used as stable identifiers across `agent-contracts` and `cli-contracts`.
+
+- Characters: lowercase alphanumeric and hyphens (`[a-z0-9-]+`)
+- Format: `kebab-case`
+- Reserved: IDs containing `.` are reserved for future namespace extension
+
+### Path Resolution
+
+A file matches an artifact if it matches any `path_patterns` glob AND does not match any `exclude_patterns` glob.
+
+```yaml
+application-code:
+  path_patterns: ["src/**/*.ts"]
+  exclude_patterns: ["src/generated/**"]
+
+generated-api:
+  path_patterns: ["src/generated/**/*.ts"]
+```
+
+If a file matches multiple artifacts, it is an **overlap** — a definition error detected by `validate --check-files`.
+
+### Variable Expansion
+
+`artifact-contracts.config.yaml` provides variables that expand `${vars.*}` references in the DSL:
+
+```yaml
+# artifact-contracts.config.yaml
+variables:
+  doc_patterns:
+    - "docs/**/*.md"
+    - "packages/*/README.md"
+```
+
+```yaml
+# artifact-contracts.yaml
+documentation:
+  path_patterns:
+    - "${vars.doc_patterns}"
+  # expands to: ["docs/**/*.md", "packages/*/README.md"]
+```
+
+## Commands
+
+### Deterministic Commands
+
+| Command | Description |
+|---------|-------------|
+| `validate [--check-files]` | Schema validation, ID naming check, and optional file-based overlap detection |
+| `resolve [--format yaml\|json]` | Output fully-resolved definitions with authority-based defaults applied |
+| `list [--authority TYPE] [--path FILE]` | List artifacts, optionally filtered by authority or reverse-lookup by path |
+| `explain <path> [--format text\|json\|yaml]` | Show full governance properties for a file path |
+
+### LLM-Powered Commands
+
+| Command | Description |
+|---------|-------------|
+| `audit [--adapter NAME]` | Semantic quality audit — naming consistency, authority appropriateness, coverage gaps |
+
+LLM commands require [agent-contracts-runtime](https://www.npmjs.com/package/agent-contracts-runtime) (optional peer dependency) and an adapter API key. Use `--show-prompt` or `--dry-run` to inspect the prompt without calling the LLM.
+
+```bash
+# Install LLM runtime
+npm install agent-contracts-runtime
+
+# Run semantic audit
+npx artifact-contracts audit --adapter openai
+
+# Preview the prompt
+npx artifact-contracts audit --show-prompt
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Validation errors / general error |
+| `2` | Overlap detected (path matches multiple artifacts) |
+| `3` | Config or input file not found / parse error |
+| `10` | Audit findings above `--fail-on` threshold |
+| `11` | `agent-contracts-runtime` not installed |
+| `12` | Adapter initialization error (missing API key, etc.) |
+
+## CI Integration
+
+```yaml
+name: Artifact Registry Check
+on:
+  pull_request:
+    paths: ['artifact-contracts.yaml', 'artifact-contracts.config.yaml']
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npx artifact-contracts validate --check-files
+```
+
+## Programmatic API
+
+```typescript
+import {
+  loadDocument,
+  resolveDocument,
+  lookupByPath,
+  validateDocument,
+} from "artifact-contracts/core";
+
+// Load and resolve definitions
+const loadResult = loadDocument();
+const resolved = resolveDocument(loadResult);
+
+// Reverse-lookup: path → artifact ID
+const matches = lookupByPath("src/generated/client.ts", resolved.artifacts);
+console.log(matches[0].id);        // "generated-api"
+console.log(matches[0].artifact);  // { type, authority, manual_edit, ... }
+
+// Validate
+const result = await validateDocument(loadResult, { checkFiles: true });
+if (!result.valid) {
+  console.error(result.diagnostics);
+}
+```
+
+## Agent-Readable Interface
+
+Tool capabilities are described in machine-readable form via [cli-contract.yaml](cli-contract.yaml). LLM agents can introspect available commands, their effects, exit codes, and output schemas without parsing help text.
+
+Agent and task definitions for LLM commands are in [dsl/](dsl/) using the [agent-contracts](https://www.npmjs.com/package/agent-contracts) DSL.
+
+## Technology Stack
+
+| Component | Technology |
+|-----------|-----------|
+| Language | TypeScript (Node.js) |
+| Schema validation | [zod](https://github.com/colinhacks/zod) |
+| Glob matching | [minimatch](https://github.com/isaacs/minimatch) |
+| CLI framework | [commander](https://github.com/tj/commander.js) |
+| CLI contract | [cli-contracts](https://www.npmjs.com/package/cli-contracts) |
+| Agent DSL | [agent-contracts](https://www.npmjs.com/package/agent-contracts) |
+| LLM integration | [agent-contracts-runtime](https://www.npmjs.com/package/agent-contracts-runtime) (optional peer dep) |
+
 ## License
 
 MIT