agent-contracts 0.32.5 → 0.33.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 (10) hide show
  1. package/cli-contract.yaml +1 -1
  2. package/dist/agent-contracts.bundle.mjs +2908 -0
  3. package/dist/agent-contracts.bundle.mjs.map +7 -0
  4. package/dist/index.js +75956 -37586
  5. package/dist/index.js.map +1 -1
  6. package/docs/cli-reference.md +50 -433
  7. package/package.json +24 -26
  8. package/dist/cli.d.ts +0 -1
  9. package/dist/cli.js +0 -54938
  10. package/dist/cli.js.map +0 -1
package/docs/cli-reference.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent development workflows. Provides static validation, semantic linting, prompt rendering, guardrail generation, and completeness scoring for agent contract definitions.
4
4
 
5
- **Version:** 0.30.0
5
+ **Version:** 0.33.0
6
6
 
7
7
  ## Table of Contents
8
8
 
@@ -16,6 +16,7 @@ Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent
16
16
  - [audit](#agent-contracts-audit)
17
17
  - [generate](#agent-contracts-generate)
18
18
  - [navigation-index](#agent-contracts-navigation-index)
19
+ - [artifact-coverage](#agent-contracts-artifact-coverage)
19
20
 
20
21
  ---
21
22
 
@@ -389,222 +390,6 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
389
390
 
390
391
  - **stdout:** format=`{options.format}`
391
392
 
392
- | Property | Type | Required | Description |
393
- |---|---|---|---|
394
- | `summary` | `string` | Yes | |
395
- | `risk_level` | `"low" \| "medium" \| "high" \| "critical"` | Yes | |
396
- | `findings` | `object[]` | Yes | |
397
- | `findings[].id` | `string` | No | Unique finding identifier. |
398
- | `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes | |
399
- | `findings[].category` | `string` | Yes | Finding category (e.g. missing-policy, inconsistent-risk). |
400
- | `findings[].target` | `string` | No | Target of the finding (command ID, schema path). |
401
- | `findings[].location` | `string` | No | Location within the target. |
402
- | `findings[].message` | `string` | Yes | |
403
- | `findings[].recommendation` | `string` | No | |
404
- | `findings[].confidence` | `number (min: 0, max: 1)` | No | Confidence score (0-1) for LLM-generated findings. |
405
- | `findings[].evidence` | `object[]` | No | |
406
- | `findings[].evidence[].kind` | `enum(7 values)` | Yes | |
407
- | `findings[].evidence[].target` | `string` | No | Target identifier (file path, command ID, schema name). |
408
- | `findings[].evidence[].location` | `string` | No | Location within the target (line number, JSON pointer). |
409
- | `findings[].evidence[].excerpt` | `string` | No | Relevant excerpt from the target. |
410
- | `findings[].details` | `Record<string, any>` | No | |
411
- | `recommended_actions` | `object[]` | No | |
412
- | `recommended_actions[].kind` | `enum(6 values)` | Yes | |
413
- | `recommended_actions[].title` | `string` | Yes | |
414
- | `recommended_actions[].command` | `string` | No | CLI command to run (for run_command kind). |
415
- | `recommended_actions[].target` | `string` | No | Target file or resource. |
416
- | `recommended_actions[].rationale` | `string` | No | |
417
- | `metadata` | `object` | No | |
418
- | `metadata.tool` | `string` | No | |
419
- | `metadata.command` | `string` | No | |
420
- | `metadata.version` | `string` | No | |
421
- | `metadata.generated_at` | `string` | No | |
422
- | `metadata.adapter` | `string` | No | |
423
- | `metadata.model` | `string` | No | |
424
-
425
- <details>
426
- <summary>JSON Schema</summary>
427
-
428
- ```json
429
- {
430
- "type": "object",
431
- "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
432
- "required": [
433
- "summary",
434
- "risk_level",
435
- "findings"
436
- ],
437
- "properties": {
438
- "summary": {
439
- "type": "string"
440
- },
441
- "risk_level": {
442
- "type": "string",
443
- "enum": [
444
- "low",
445
- "medium",
446
- "high",
447
- "critical"
448
- ]
449
- },
450
- "findings": {
451
- "type": "array",
452
- "items": {
453
- "type": "object",
454
- "description": "A single finding from an agent audit or analysis.",
455
- "required": [
456
- "severity",
457
- "category",
458
- "message"
459
- ],
460
- "properties": {
461
- "id": {
462
- "type": "string",
463
- "description": "Unique finding identifier."
464
- },
465
- "severity": {
466
- "type": "string",
467
- "enum": [
468
- "info",
469
- "warning",
470
- "error",
471
- "critical"
472
- ]
473
- },
474
- "category": {
475
- "type": "string",
476
- "description": "Finding category (e.g. missing-policy, inconsistent-risk)."
477
- },
478
- "target": {
479
- "type": "string",
480
- "description": "Target of the finding (command ID, schema path)."
481
- },
482
- "location": {
483
- "type": "string",
484
- "description": "Location within the target."
485
- },
486
- "message": {
487
- "type": "string"
488
- },
489
- "recommendation": {
490
- "type": "string"
491
- },
492
- "confidence": {
493
- "type": "number",
494
- "minimum": 0,
495
- "maximum": 1,
496
- "description": "Confidence score (0-1) for LLM-generated findings."
497
- },
498
- "evidence": {
499
- "type": "array",
500
- "items": {
501
- "type": "object",
502
- "description": "Evidence supporting an agent finding.",
503
- "required": [
504
- "kind"
505
- ],
506
- "properties": {
507
- "kind": {
508
- "type": "string",
509
- "enum": [
510
- "file",
511
- "command",
512
- "schema",
513
- "diff",
514
- "stdout",
515
- "stderr",
516
- "text"
517
- ]
518
- },
519
- "target": {
520
- "type": "string",
521
- "description": "Target identifier (file path, command ID, schema name)."
522
- },
523
- "location": {
524
- "type": "string",
525
- "description": "Location within the target (line number, JSON pointer)."
526
- },
527
- "excerpt": {
528
- "type": "string",
529
- "description": "Relevant excerpt from the target."
530
- }
531
- }
532
- }
533
- },
534
- "details": {
535
- "type": "object",
536
- "additionalProperties": true
537
- }
538
- }
539
- }
540
- },
541
- "recommended_actions": {
542
- "type": "array",
543
- "items": {
544
- "type": "object",
545
- "description": "A recommended action from an agent audit.",
546
- "required": [
547
- "kind",
548
- "title"
549
- ],
550
- "properties": {
551
- "kind": {
552
- "type": "string",
553
- "enum": [
554
- "run_command",
555
- "edit_file",
556
- "review",
557
- "confirm",
558
- "block",
559
- "ignore"
560
- ]
561
- },
562
- "title": {
563
- "type": "string"
564
- },
565
- "command": {
566
- "type": "string",
567
- "description": "CLI command to run (for run_command kind)."
568
- },
569
- "target": {
570
- "type": "string",
571
- "description": "Target file or resource."
572
- },
573
- "rationale": {
574
- "type": "string"
575
- }
576
- }
577
- }
578
- },
579
- "metadata": {
580
- "type": "object",
581
- "properties": {
582
- "tool": {
583
- "type": "string"
584
- },
585
- "command": {
586
- "type": "string"
587
- },
588
- "version": {
589
- "type": "string"
590
- },
591
- "generated_at": {
592
- "type": "string"
593
- },
594
- "adapter": {
595
- "type": "string"
596
- },
597
- "model": {
598
- "type": "string"
599
- }
600
- }
601
- }
602
- }
603
- }
604
- ```
605
-
606
- </details>
607
-
608
393
  **Exit 1:** Unexpected error (invalid input, config error, or internal failure).
609
394
 
610
395
  - **stderr:** format=`text`
@@ -613,222 +398,6 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
613
398
 
614
399
  - **stdout:** format=`{options.format}`
615
400
 
616
- | Property | Type | Required | Description |
617
- |---|---|---|---|
618
- | `summary` | `string` | Yes | |
619
- | `risk_level` | `"low" \| "medium" \| "high" \| "critical"` | Yes | |
620
- | `findings` | `object[]` | Yes | |
621
- | `findings[].id` | `string` | No | Unique finding identifier. |
622
- | `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes | |
623
- | `findings[].category` | `string` | Yes | Finding category (e.g. missing-policy, inconsistent-risk). |
624
- | `findings[].target` | `string` | No | Target of the finding (command ID, schema path). |
625
- | `findings[].location` | `string` | No | Location within the target. |
626
- | `findings[].message` | `string` | Yes | |
627
- | `findings[].recommendation` | `string` | No | |
628
- | `findings[].confidence` | `number (min: 0, max: 1)` | No | Confidence score (0-1) for LLM-generated findings. |
629
- | `findings[].evidence` | `object[]` | No | |
630
- | `findings[].evidence[].kind` | `enum(7 values)` | Yes | |
631
- | `findings[].evidence[].target` | `string` | No | Target identifier (file path, command ID, schema name). |
632
- | `findings[].evidence[].location` | `string` | No | Location within the target (line number, JSON pointer). |
633
- | `findings[].evidence[].excerpt` | `string` | No | Relevant excerpt from the target. |
634
- | `findings[].details` | `Record<string, any>` | No | |
635
- | `recommended_actions` | `object[]` | No | |
636
- | `recommended_actions[].kind` | `enum(6 values)` | Yes | |
637
- | `recommended_actions[].title` | `string` | Yes | |
638
- | `recommended_actions[].command` | `string` | No | CLI command to run (for run_command kind). |
639
- | `recommended_actions[].target` | `string` | No | Target file or resource. |
640
- | `recommended_actions[].rationale` | `string` | No | |
641
- | `metadata` | `object` | No | |
642
- | `metadata.tool` | `string` | No | |
643
- | `metadata.command` | `string` | No | |
644
- | `metadata.version` | `string` | No | |
645
- | `metadata.generated_at` | `string` | No | |
646
- | `metadata.adapter` | `string` | No | |
647
- | `metadata.model` | `string` | No | |
648
-
649
- <details>
650
- <summary>JSON Schema</summary>
651
-
652
- ```json
653
- {
654
- "type": "object",
655
- "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
656
- "required": [
657
- "summary",
658
- "risk_level",
659
- "findings"
660
- ],
661
- "properties": {
662
- "summary": {
663
- "type": "string"
664
- },
665
- "risk_level": {
666
- "type": "string",
667
- "enum": [
668
- "low",
669
- "medium",
670
- "high",
671
- "critical"
672
- ]
673
- },
674
- "findings": {
675
- "type": "array",
676
- "items": {
677
- "type": "object",
678
- "description": "A single finding from an agent audit or analysis.",
679
- "required": [
680
- "severity",
681
- "category",
682
- "message"
683
- ],
684
- "properties": {
685
- "id": {
686
- "type": "string",
687
- "description": "Unique finding identifier."
688
- },
689
- "severity": {
690
- "type": "string",
691
- "enum": [
692
- "info",
693
- "warning",
694
- "error",
695
- "critical"
696
- ]
697
- },
698
- "category": {
699
- "type": "string",
700
- "description": "Finding category (e.g. missing-policy, inconsistent-risk)."
701
- },
702
- "target": {
703
- "type": "string",
704
- "description": "Target of the finding (command ID, schema path)."
705
- },
706
- "location": {
707
- "type": "string",
708
- "description": "Location within the target."
709
- },
710
- "message": {
711
- "type": "string"
712
- },
713
- "recommendation": {
714
- "type": "string"
715
- },
716
- "confidence": {
717
- "type": "number",
718
- "minimum": 0,
719
- "maximum": 1,
720
- "description": "Confidence score (0-1) for LLM-generated findings."
721
- },
722
- "evidence": {
723
- "type": "array",
724
- "items": {
725
- "type": "object",
726
- "description": "Evidence supporting an agent finding.",
727
- "required": [
728
- "kind"
729
- ],
730
- "properties": {
731
- "kind": {
732
- "type": "string",
733
- "enum": [
734
- "file",
735
- "command",
736
- "schema",
737
- "diff",
738
- "stdout",
739
- "stderr",
740
- "text"
741
- ]
742
- },
743
- "target": {
744
- "type": "string",
745
- "description": "Target identifier (file path, command ID, schema name)."
746
- },
747
- "location": {
748
- "type": "string",
749
- "description": "Location within the target (line number, JSON pointer)."
750
- },
751
- "excerpt": {
752
- "type": "string",
753
- "description": "Relevant excerpt from the target."
754
- }
755
- }
756
- }
757
- },
758
- "details": {
759
- "type": "object",
760
- "additionalProperties": true
761
- }
762
- }
763
- }
764
- },
765
- "recommended_actions": {
766
- "type": "array",
767
- "items": {
768
- "type": "object",
769
- "description": "A recommended action from an agent audit.",
770
- "required": [
771
- "kind",
772
- "title"
773
- ],
774
- "properties": {
775
- "kind": {
776
- "type": "string",
777
- "enum": [
778
- "run_command",
779
- "edit_file",
780
- "review",
781
- "confirm",
782
- "block",
783
- "ignore"
784
- ]
785
- },
786
- "title": {
787
- "type": "string"
788
- },
789
- "command": {
790
- "type": "string",
791
- "description": "CLI command to run (for run_command kind)."
792
- },
793
- "target": {
794
- "type": "string",
795
- "description": "Target file or resource."
796
- },
797
- "rationale": {
798
- "type": "string"
799
- }
800
- }
801
- }
802
- },
803
- "metadata": {
804
- "type": "object",
805
- "properties": {
806
- "tool": {
807
- "type": "string"
808
- },
809
- "command": {
810
- "type": "string"
811
- },
812
- "version": {
813
- "type": "string"
814
- },
815
- "generated_at": {
816
- "type": "string"
817
- },
818
- "adapter": {
819
- "type": "string"
820
- },
821
- "model": {
822
- "type": "string"
823
- }
824
- }
825
- }
826
- }
827
- }
828
- ```
829
-
830
- </details>
831
-
832
401
  - **stderr:** format=`text`
833
402
 
834
403
  **Exit 11:** Runtime dependency missing (agent-contracts-runtime not installed).
@@ -980,3 +549,51 @@ agent-contracts navigation-index -c agent-contracts.config.yaml
980
549
  - **stderr:** format=`text`
981
550
 
982
551
  ---
552
+
553
+ ### artifact-coverage
554
+
555
+ Measure file coverage by artifact path_patterns definitions.
556
+
557
+ Cross-references git ls-files output against compiled artifact path_patterns / exclude_patterns to measure what percentage of a project's tracked files are covered by artifact definitions. Reports uncovered files, overlapping files, and per-artifact match counts. Supports CI gating via --min-coverage.
558
+
559
+ **Usage:**
560
+
561
+ ```
562
+ agent-contracts artifact-coverage
563
+ ```
564
+ ```
565
+ agent-contracts artifact-coverage -c agent-contracts.config.yaml
566
+ ```
567
+ ```
568
+ agent-contracts artifact-coverage --format json
569
+ ```
570
+ ```
571
+ agent-contracts artifact-coverage --min-coverage 80
572
+ ```
573
+
574
+ #### Arguments
575
+
576
+ | Name | Required | Description |
577
+ |---|---|---|
578
+ | `dir` | No | Path to agent-contracts.yaml. |
579
+
580
+ #### Options
581
+
582
+ | Option | Aliases | Required | Default | Description |
583
+ |---|---|---|---|---|
584
+ | `--config` | -c | No | | Path to agent-contracts.config.yaml. |
585
+ | `--team` | | No | | Limit to one team (multi-team config only). |
586
+ | `--format` | | No | `"text"` | Output format. |
587
+ | `--min-coverage` | | No | | Minimum coverage percentage; exit 1 if below (for CI gates). |
588
+
589
+ #### Exit Codes
590
+
591
+ **Exit 0:** Coverage report generated (and above threshold if --min-coverage specified).
592
+
593
+ - **stdout:** format=`{options.format}`
594
+
595
+ **Exit 1:** Coverage below threshold, schema validation failed, or unexpected error.
596
+
597
+ - **stderr:** format=`text`
598
+
599
+ ---
package/package.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "agent-contracts",
3
- "version": "0.32.5",
3
+ "version": "0.33.0",
4
4
  "description": "Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent development workflows",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
7
7
  "types": "dist/index.d.ts",
8
8
  "bin": {
9
- "agent-contracts": "./dist/cli.js"
9
+ "agent-contracts": "dist/agent-contracts.bundle.mjs"
10
10
  },
11
11
  "exports": {
12
12
  ".": {
@@ -15,7 +15,11 @@
15
15
  }
16
16
  },
17
17
  "files": [
18
- "dist",
18
+ "dist/agent-contracts.bundle.mjs",
19
+ "dist/agent-contracts.bundle.mjs.map",
20
+ "dist/index.js",
21
+ "dist/index.js.map",
22
+ "dist/index.d.ts",
19
23
  "dsl_base",
20
24
  "cli-contract.yaml",
21
25
  "docs/cli-reference.md",
@@ -34,7 +38,10 @@
34
38
  "generate:cli": "cli-contracts generate typescript",
35
39
  "generate:docs": "cli-contracts docs",
36
40
  "version": "node -e \"const fs=require('fs');const f='cli-contract.yaml';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace(/^ version: .*/m,' version: '+process.env.npm_package_version))\" && git add cli-contract.yaml",
37
- "prepublishOnly": "npm run clean && npm run build"
41
+ "prepublishOnly": "npm run clean && npm run build && npm run bundle:min",
42
+ "test:ci": "vitest run",
43
+ "bundle": "node esbuild.bundle.mjs",
44
+ "bundle:min": "node esbuild.bundle.mjs --minify"
38
45
  },
39
46
  "keywords": [
40
47
  "agent",
@@ -59,42 +66,33 @@
59
66
  "bugs": {
60
67
  "url": "https://github.com/foo-log-inc/agent-contracts/issues"
61
68
  },
62
- "dependencies": {
63
- "@stoplight/spectral-core": "^1.22.0",
64
- "@stoplight/spectral-functions": "^1.9.0",
65
- "@stoplight/spectral-rulesets": "^1.22.1",
66
- "ajv": "^8.18.0",
67
- "cli-contracts": "^0.31.0",
68
- "commander": "^14.0.3",
69
- "handlebars": "^4.7.9",
70
- "minimatch": "^10.2.5",
71
- "yaml": "^2.8.3",
72
- "zod": "^4.3.6",
73
- "zod-to-json-schema": "^3.25.2"
74
- },
75
69
  "devDependencies": {
76
70
  "@anthropic-ai/claude-agent-sdk": "^0.2.138",
77
71
  "@eslint/js": "^10.0.1",
78
72
  "@google/genai": "^2.0.1",
79
73
  "@openai/agents": "^0.11.1",
74
+ "@stoplight/spectral-core": "^1.22.0",
75
+ "@stoplight/spectral-functions": "^1.9.0",
76
+ "@stoplight/spectral-rulesets": "^1.22.1",
80
77
  "@types/node": "^25.6.0",
81
78
  "agent-contracts-runtime": "^0.31.4",
79
+ "ajv": "^8.18.0",
80
+ "cli-contracts": "^0.32.0",
81
+ "commander": "^14.0.3",
82
+ "esbuild": "^0.28.0",
82
83
  "eslint": "^10.2.0",
83
84
  "globals": "^17.5.0",
85
+ "handlebars": "^4.7.9",
86
+ "minimatch": "^10.2.5",
84
87
  "prettier": "^3.8.2",
85
88
  "tsup": "^8.5.1",
86
89
  "tsx": "^4.21.0",
87
90
  "typescript": "^6.0.2",
88
91
  "typescript-eslint": "^8.58.1",
89
- "vitest": "^4.1.4"
90
- },
91
- "peerDependencies": {
92
- "agent-contracts-runtime": "^0.31.0 || ^0.32.0"
93
- },
94
- "peerDependenciesMeta": {
95
- "agent-contracts-runtime": {
96
- "optional": true
97
- }
92
+ "vitest": "^4.1.4",
93
+ "yaml": "^2.8.3",
94
+ "zod": "^4.3.6",
95
+ "zod-to-json-schema": "^3.25.2"
98
96
  },
99
97
  "engines": {
100
98
  "node": ">=20.0.0"
package/dist/cli.d.ts DELETED
@@ -1 +0,0 @@
1
- #!/usr/bin/env node