codebaseiq 0.1.0

package/docs/schemas/cli-json-envelope.schema.json

@@ -0,0 +1,237 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ainsleyclark/codebaseiq/blob/main/docs/schemas/cli-json-envelope.schema.json",
+  "title": "codebaseiq CLI JSON envelope v1",
+  "description": "The public transport record emitted by codebaseiq commands that accept --json.",
+  "type": "object",
+  "required": ["kind", "schemaVersion", "producer", "command", "resultSchemaVersion", "args", "options", "result"],
+  "properties": {
+    "kind": { "const": "codebaseiq-result" },
+    "schemaVersion": { "const": 1 },
+    "producer": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "const": "codebaseiq" },
+        "version": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": true
+    },
+    "command": { "type": "string", "minLength": 1 },
+    "operationRole": {
+      "enum": [
+        "repository-observation",
+        "repository-preview",
+        "mutation",
+        "composite",
+        "environment-observation",
+        "tool-information"
+      ]
+    },
+    "resultSchemaVersion": { "type": "integer", "minimum": 1 },
+    "evidence": { "enum": ["graph-fact", "heuristic", "mixed"] },
+    "analysisBudget": {},
+    "args": { "type": "array" },
+    "options": { "type": "object", "additionalProperties": true },
+    "result": {},
+    "coverage": {},
+    "agentResult": {},
+    "evidenceContext": { "$ref": "#/$defs/evidenceContextV1" }
+  },
+  "$defs": {
+    "evidenceContextV1": {
+      "type": "object",
+      "required": ["schemaVersion", "receipt", "analysisManifest"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "operationRole": {
+          "enum": [
+            "repository-observation",
+            "repository-preview",
+            "mutation",
+            "composite",
+            "environment-observation",
+            "tool-information"
+          ]
+        },
+        "receipt": { "$ref": "./observation-receipt.schema.json" },
+        "analysisManifest": { "$ref": "#/$defs/analysisManifestV1" }
+      },
+      "additionalProperties": true
+    },
+    "analysisManifestV1": {
+      "type": "object",
+      "required": ["schemaVersion"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "evidence": { "enum": ["graph-fact", "heuristic", "mixed"] },
+        "analysisBudget": {},
+        "coverage": {},
+        "claimQualification": { "$ref": "#/$defs/claimQualificationV1" }
+      },
+      "additionalProperties": true
+    },
+    "claimQualificationV1": {
+      "type": "object",
+      "required": ["schemaVersion", "origin", "coverage", "producerValidation", "stateAuthority", "repositoryPolicy"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "origin": {
+          "enum": [
+            "compiler-graph",
+            "semantic-analysis",
+            "repository-source",
+            "change-history",
+            "runtime-measurement",
+            "heuristic",
+            "mixed",
+            "unknown"
+          ]
+        },
+        "coverage": { "$ref": "#/$defs/claimCoverage" },
+        "producerValidation": { "$ref": "#/$defs/producerValidation" },
+        "stateAuthority": { "$ref": "#/$defs/stateAuthority" },
+        "repositoryPolicy": { "$ref": "#/$defs/repositoryPolicyAction" },
+        "families": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/claimFamily" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "claimCoverage": {
+      "type": "object",
+      "required": ["state", "returned", "totalKnown"],
+      "properties": {
+        "state": { "enum": ["complete", "partial", "unknown"] },
+        "returned": { "type": "integer", "minimum": 0 },
+        "totalKnown": { "type": "boolean" },
+        "total": { "type": "integer", "minimum": 0 },
+        "omitted": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": true
+    },
+    "producerValidation": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": { "enum": ["validated", "failed", "not-evaluated", "not-applicable"] },
+        "certification": {
+          "type": "object",
+          "required": ["id", "version", "corpus"],
+          "properties": {
+            "id": { "type": "string", "minLength": 1 },
+            "version": { "type": "integer", "minimum": 1 },
+            "corpus": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": true
+        }
+      },
+      "oneOf": [
+        {
+          "required": ["status", "certification"],
+          "properties": {
+            "status": { "enum": ["validated", "failed"] }
+          }
+        },
+        {
+          "required": ["status"],
+          "properties": {
+            "status": { "enum": ["not-evaluated", "not-applicable"] },
+            "certification": false
+          }
+        }
+      ],
+      "additionalProperties": true
+    },
+    "stateAuthority": {
+      "type": "object",
+      "required": ["policyVersion", "authority", "requiredRelationships", "reasons"],
+      "properties": {
+        "policyVersion": { "type": "integer", "minimum": 1 },
+        "authority": { "enum": ["completion", "advisory", "none"] },
+        "requiredRelationships": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "reasons": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      },
+      "additionalProperties": true
+    },
+    "repositoryPolicyAction": {
+      "type": "object",
+      "required": ["policyId", "policyVersion", "permission", "reasons"],
+      "properties": {
+        "policyId": { "type": "string", "minLength": 1 },
+        "policyVersion": { "const": 1 },
+        "permission": {
+          "enum": ["observe", "advise", "require-adjudication", "block", "not-established"]
+        },
+        "reasons": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      },
+      "additionalProperties": true
+    },
+    "claimFamily": {
+      "type": "object",
+      "required": ["id", "selector", "origin"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "selector": { "type": "string", "minLength": 1 },
+        "origin": {
+          "oneOf": [
+            {
+              "type": "object",
+              "required": ["kind", "origin"],
+              "properties": {
+                "kind": { "const": "fixed" },
+                "origin": {
+                  "enum": [
+                    "compiler-graph",
+                    "semantic-analysis",
+                    "repository-source",
+                    "change-history",
+                    "runtime-measurement",
+                    "heuristic",
+                    "unknown"
+                  ]
+                }
+              },
+              "additionalProperties": true
+            },
+            {
+              "type": "object",
+              "required": ["kind", "field", "values"],
+              "properties": {
+                "kind": { "const": "result-field" },
+                "field": { "type": "string", "minLength": 1 },
+                "values": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "enum": [
+                      "compiler-graph",
+                      "semantic-analysis",
+                      "repository-source",
+                      "change-history",
+                      "runtime-measurement",
+                      "heuristic",
+                      "unknown"
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": true
+            }
+          ]
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/docs/schemas/cli-output-page.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ainsleyclark/codebaseiq/blob/main/docs/schemas/cli-output-page.schema.json",
+  "title": "codebaseiq CLI output page v1",
+  "description": "A bounded, resumable page of rendered codebaseiq output.",
+  "type": "object",
+  "required": ["kind", "schemaVersion", "producer", "command", "contentType", "page", "content"],
+  "properties": {
+    "kind": {
+      "const": "codebaseiq-output-page"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "producer": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": {
+          "const": "codebaseiq"
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "command": {
+      "type": "string",
+      "minLength": 1
+    },
+    "contentType": {
+      "enum": ["text/plain", "application/json"]
+    },
+    "agentInstruction": {
+      "type": "string",
+      "minLength": 1,
+      "description": "A direct instruction for an AI agent consuming this page."
+    },
+    "page": {
+      "type": "object",
+      "required": [
+        "offset",
+        "returnedCharacters",
+        "totalCharacters",
+        "omittedCharacters",
+        "remainingCharacters",
+        "complete",
+        "outputHash"
+      ],
+      "properties": {
+        "offset": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "returnedCharacters": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "totalCharacters": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "omittedCharacters": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "remainingCharacters": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "complete": {
+          "type": "boolean"
+        },
+        "outputHash": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "continuation": {
+          "type": "object",
+          "required": ["cursor", "command"],
+          "properties": {
+            "cursor": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 4096
+            },
+            "command": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "content": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": false
+}

package/docs/schemas/npm-release-state.schema.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/PlunderStruck/codebaseiq/blob/main/docs/schemas/npm-release-state.schema.json",
+  "title": "codebaseiq npm release state",
+  "description": "Durable local progress for one exact main-package and Windows-sidecar npm release.",
+  "type": "object",
+  "required": [
+    "kind",
+    "schemaVersion",
+    "releaseId",
+    "source",
+    "packages",
+    "completedStages",
+    "createdAt",
+    "updatedAt",
+    "writer"
+  ],
+  "properties": {
+    "kind": {
+      "const": "codebaseiq-npm-release-state"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "releaseId": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "source": {
+      "type": "object",
+      "required": ["gitRevision", "registry"],
+      "properties": {
+        "gitRevision": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{40,64}$"
+        },
+        "registry": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https://",
+          "allOf": [
+            {
+              "not": {
+                "pattern": "^https://[^/]*@"
+              }
+            },
+            {
+              "not": {
+                "pattern": "[?#]"
+              }
+            }
+          ]
+        }
+      },
+      "additionalProperties": true
+    },
+    "packages": {
+      "type": "object",
+      "required": ["main", "sidecar"],
+      "properties": {
+        "main": {
+          "$ref": "#/$defs/packageIdentity"
+        },
+        "sidecar": {
+          "$ref": "#/$defs/packageIdentity"
+        }
+      },
+      "additionalProperties": true
+    },
+    "completedStages": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "enum": ["local-preflight-complete", "sidecar-registry-verified", "main-registry-verified"]
+      },
+      "oneOf": [
+        {
+          "const": ["local-preflight-complete"]
+        },
+        {
+          "const": ["local-preflight-complete", "sidecar-registry-verified"]
+        },
+        {
+          "const": ["local-preflight-complete", "main-registry-verified"]
+        },
+        {
+          "const": ["local-preflight-complete", "sidecar-registry-verified", "main-registry-verified"]
+        }
+      ]
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "writer": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": {
+          "const": "codebaseiq"
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The main-package version that produced this state; the executable reader requires it to equal packages.main.version."
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "packageIdentity": {
+      "type": "object",
+      "required": ["name", "version", "size", "shasum", "integrity"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "shasum": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{40}$"
+        },
+        "integrity": {
+          "type": "string",
+          "pattern": "^sha512-[A-Za-z0-9+/]+={0,2}$"
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/docs/schemas/observation-receipt.schema.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/codebaseiq/docs/schemas/observation-receipt.schema.json",
+  "title": "codebaseiq observation receipt",
+  "description": "Versioned facts naming the repository state sources one operation actually observed. Version 1 remains readable legacy provenance; version 2 keeps collaboration, workspace, content, index, source, and stability facts independent.",
+  "oneOf": [{ "$ref": "#/$defs/observationReceiptV1" }, { "$ref": "#/$defs/observationReceiptV2" }],
+  "$defs": {
+    "observationReceiptV1": {
+      "type": "object",
+      "required": ["schemaVersion", "authorityKind", "observedAt", "projectIdentity"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "authorityKind": {
+          "enum": ["index-worktree", "index-only", "worktree-only", "process-local"]
+        },
+        "observedAt": { "type": "string", "format": "date-time" },
+        "projectIdentity": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "index": {
+          "type": "object",
+          "required": ["generationIdentity", "source", "alignment"],
+          "properties": {
+            "generationIdentity": { "type": "string", "minLength": 1, "maxLength": 256 },
+            "source": { "enum": ["immutable", "legacy"] },
+            "alignment": { "enum": ["not-certified", "leased"] }
+          },
+          "additionalProperties": true
+        },
+        "worktree": {
+          "type": "object",
+          "required": ["identity", "clean"],
+          "properties": {
+            "identity": { "type": "string", "minLength": 1, "maxLength": 256 },
+            "clean": { "type": "boolean" },
+            "headCommit": { "type": "string", "minLength": 1, "maxLength": 256 },
+            "treeOid": { "type": "string", "minLength": 1, "maxLength": 256 }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "observationReceiptV2": {
+      "type": "object",
+      "required": ["schemaVersion", "observedAt", "facts", "observedSources", "stabilityProofs"],
+      "properties": {
+        "schemaVersion": { "const": 2 },
+        "observedAt": { "type": "string", "format": "date-time" },
+        "facts": {
+          "type": "object",
+          "properties": {
+            "collaborationDomain": { "$ref": "#/$defs/observationIdentity" },
+            "repositoryLineage": { "$ref": "#/$defs/observationIdentity" },
+            "workspaceInstance": { "$ref": "#/$defs/observationIdentity" },
+            "wholeContent": { "$ref": "#/$defs/observationIdentity" },
+            "relevantInputs": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["subject", "identity"],
+                "properties": {
+                  "subject": { "type": "string", "minLength": 1, "maxLength": 256 },
+                  "identity": { "$ref": "#/$defs/observationIdentity" }
+                },
+                "additionalProperties": true
+              }
+            },
+            "index": {
+              "type": "object",
+              "required": ["generation", "source"],
+              "properties": {
+                "generation": { "$ref": "#/$defs/observationIdentity" },
+                "inputs": { "$ref": "#/$defs/observationIdentity" },
+                "source": { "enum": ["immutable", "legacy"] }
+              },
+              "additionalProperties": true
+            }
+          },
+          "additionalProperties": true
+        },
+        "observedSources": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/observationSourceFact" }
+        },
+        "stabilityProofs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/observationStabilityProof" }
+        },
+        "diagnostics": {
+          "type": "object",
+          "properties": {
+            "clean": { "type": "boolean" },
+            "headCommit": { "type": "string", "minLength": 1, "maxLength": 256 },
+            "treeOid": { "type": "string", "minLength": 1, "maxLength": 256 }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "observationIdentity": {
+      "type": "object",
+      "required": ["schemaVersion", "canonicalizationVersion", "hashAlgorithm", "projection", "digest"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "canonicalizationVersion": { "const": 1 },
+        "hashAlgorithm": { "const": "sha256" },
+        "projection": {
+          "type": "object",
+          "required": ["name", "version"],
+          "properties": {
+            "name": { "type": "string", "minLength": 1, "maxLength": 256 },
+            "version": { "type": "integer", "minimum": 1 }
+          },
+          "additionalProperties": true
+        },
+        "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      },
+      "additionalProperties": true
+    },
+    "observationSourceFact": {
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "enum": ["index-generation", "repository-snapshot", "live-workspace", "process"]
+        },
+        "identity": { "$ref": "#/$defs/observationIdentity" }
+      },
+      "additionalProperties": true
+    },
+    "observationStabilityProof": {
+      "type": "object",
+      "required": ["source", "kind"],
+      "oneOf": [
+        {
+          "properties": {
+            "source": { "const": "index-generation" },
+            "kind": { "enum": ["immutable", "not-established", "invalidated"] }
+          }
+        },
+        {
+          "properties": {
+            "source": { "const": "repository-snapshot" },
+            "kind": { "enum": ["fixed-snapshot", "not-established", "invalidated"] }
+          }
+        },
+        {
+          "properties": {
+            "source": { "const": "live-workspace" },
+            "kind": { "enum": ["bracketed", "not-established", "invalidated"] }
+          }
+        },
+        {
+          "properties": {
+            "source": { "const": "process" },
+            "kind": { "enum": ["not-established", "invalidated"] }
+          }
+        }
+      ],
+      "additionalProperties": true
+    }
+  }
+}