@company-semantics/contracts 0.6.0 → 0.8.0

package/README.md

@@ -25,6 +25,11 @@ import type { IntentCategory, InsightConfidence } from '@company-semantics/contr
 - Frontend-only extensions
 - Implementation details
 
+## Package Format
+
+This package intentionally exports TypeScript source.
+It does not emit `.d.ts` files. Consumers are expected to compile TS.
+
 ## Versioning
 
 Follows semver:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -9,33 +9,44 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./index.ts"
-    }
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./schemas/guard-result.schema.json": "./schemas/guard-result.schema.json"
   },
-  "types": "./index.ts",
+  "types": "./src/index.ts",
   "files": [
-    "index.ts",
-    "system/",
-    "README.md"
+    "src",
+    "schemas"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc -b --noEmit",
     "lint:md": "markdownlint-cli2 '**/*.md' '#node_modules'",
     "lint:json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\"",
-    "prepare": "husky"
+    "prepare": "husky",
+    "guard:decision": "npx tsx scripts/ci/decision-guard.ts",
+    "guard:decision:json": "npx tsx scripts/ci/decision-guard.ts --json",
+    "guard:export": "npx tsx scripts/ci/export-guard.ts",
+    "guard:export:json": "npx tsx scripts/ci/export-guard.ts --json",
+    "guard:vocabulary": "npx tsx scripts/ci/vocabulary-guard.ts",
+    "guard:vocabulary:json": "npx tsx scripts/ci/vocabulary-guard.ts --json",
+    "guard:test": "vitest run scripts/ci/__tests__"
   },
   "packageManager": "pnpm@10.25.0",
   "devDependencies": {
+    "@types/node": "^25.0.3",
     "husky": "^9",
     "lint-staged": "^15",
     "markdownlint-cli2": "^0.17",
-    "typescript": "^5"
+    "tsx": "^4.21.0",
+    "typescript": "^5",
+    "vitest": "^4.0.16"
   },
   "lint-staged": {
-    "*.ts": "tsc --noEmit",
+    "*.ts": "bash -c 'tsc -b --noEmit'",
     "*.md": "markdownlint-cli2",
     "package.json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\""
   }

package/schemas/guard-result.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://company-semantics.dev/schemas/guard-result.json",
+  "title": "Guard Result",
+  "description": "JSON output envelope for CI guard --json mode. schemaVersion reflects the JSON schema version, not the guard tool version.",
+  "type": "object",
+  "required": ["tool", "schemaVersion", "timestamp", "results"],
+  "properties": {
+    "tool": {
+      "type": "string",
+      "description": "The guard tool name (e.g., 'architecture-guard', 'vocabulary-guard')"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "description": "Schema version (not tool version). Bump on breaking schema changes.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of when the guard ran"
+    },
+    "results": {
+      "type": "object",
+      "description": "Flat structure: all errors/warnings from all tiers are aggregated here",
+      "required": ["errors", "warnings"],
+      "properties": {
+        "errors": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/GuardMessage" }
+        },
+        "warnings": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/GuardMessage" }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "GuardMessage": {
+      "type": "object",
+      "required": ["file", "message"],
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": "Path to the file with the issue"
+        },
+        "message": {
+          "type": "string",
+          "description": "Human-readable description of the issue"
+        },
+        "line": {
+          "type": "number",
+          "description": "Optional line number (when available)"
+        },
+        "rule": {
+          "type": "string",
+          "description": "Optional rule identifier (when available)"
+        }
+      }
+    }
+  }
+}

package/{system → src/system}/diagram.ts

@@ -1,5 +1,5 @@
 /**
- * Diagram Specification Types (v0.4.0)
+ * Diagram Specification Types (v0.6.0)
  *
  * Tree-based semantic model for system diagrams.
  * These types define MEANING, not presentation.
@@ -8,6 +8,14 @@
  * - No render hints — renderers decide presentation independently
  * - parentId creates hierarchy (tree structure), not edges
  * - Graphs can be rendered as ASCII, SVG, canvas, or any future format
+ * - meta is opaque — engine interprets, contracts stay neutral
+ *
+ * v0.6.0 changes:
+ * - meta is now Record<string, unknown> (opaque, engine-interpreted)
+ * - Removed DiagramMeta and DiagramTiming (moved to engine)
+ *
+ * v0.5.0 changes:
+ * - Added 'feedback' and 'async' edge relations
  *
  * v0.4.0 changes:
  * - 'layer' kind renamed to 'group'
@@ -29,8 +37,10 @@ export type DiagramNodeKind = 'group' | 'feature' | 'artifact'
 /**
  * The semantic relationship between nodes.
  * Note: 'contains' removed in v0.4.0 — hierarchy now via parentId
+ *
+ * v0.5.0: Added 'feedback' and 'async' for richer flow semantics
  */
-export type DiagramEdgeRelation = 'flows_to' | 'depends_on'
+export type DiagramEdgeRelation = 'flows_to' | 'depends_on' | 'feedback' | 'async'
 
 /**
  * A node in the diagram graph.
@@ -51,6 +61,8 @@ export interface DiagramNode {
   focusable?: boolean
   /** Feature maturity status (only for 'feature' nodes) */
   status?: FeatureStatus
+  /** Opaque metadata — engine interprets, contracts stay neutral */
+  meta?: Record<string, unknown>
 }
 
 /**

package/{system → src/system}/index.ts

@@ -1,5 +1,5 @@
 /**
- * System Diagram Types (v0.4.0)
+ * System Diagram Types (v0.6.0)
  *
  * Schema for the Living ASCII System Diagram feature.
  * These types define the contract between:
@@ -11,6 +11,8 @@
  *   - Client displays pre-rendered ASCII
  *   - Snapshots pushed via CI automation
  *
+ * v0.6.0: meta is now opaque (Record<string, unknown>), engine interprets
+ *
  * @see docs/LIVING_ASCII_DIAGRAM_SPEC.md
  */
 

package/src/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "composite": true,
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["**/*.test.ts", "**/*.spec.ts"]
+}