@gluecharm-lab/easyspecs-cli 0.0.3

package/resources/schemas/context-lists/coordination-duplicates-report.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/coordination-duplicates-report.schema.json",
+  "title": "coordination-duplicates-report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "version",
+    "generatedAt",
+    "sourceRoot",
+    "contextDirAbsolute",
+    "lists",
+    "duplicateGroups",
+    "orphanCoordinationMarkdown"
+  ],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.coordination-duplicates-report"
+    },
+    "version": { "type": "integer", "const": 1 },
+    "generatedAt": { "type": "string", "minLength": 1 },
+    "sourceRoot": { "type": "string", "enum": ["workspace", "worktree"] },
+    "contextDirAbsolute": { "type": "string", "minLength": 1 },
+    "lists": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["basename", "status"],
+        "properties": {
+          "basename": { "type": "string", "minLength": 1 },
+          "status": {
+            "type": "string",
+            "enum": ["ok", "missing", "parse_error", "invalid_shape"]
+          },
+          "error": { "type": "string" },
+          "rowCount": { "type": "integer", "minimum": 0 }
+        }
+      }
+    },
+    "duplicateGroups": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["listBasename", "rules", "matchOn", "normalizedValue", "members"],
+        "properties": {
+          "listBasename": { "type": "string", "minLength": 1 },
+          "rules": {
+            "type": "array",
+            "items": { "type": "string", "enum": ["D1", "D2"] },
+            "minItems": 1
+          },
+          "matchOn": {
+            "type": "string",
+            "enum": ["slug", "name", "slug_and_name"]
+          },
+          "normalizedValue": { "type": "string", "minLength": 1 },
+          "members": {
+            "type": "array",
+            "minItems": 2,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["code", "name", "sourceReferencePaths"],
+              "properties": {
+                "code": { "type": "string", "minLength": 1 },
+                "name": { "type": "string" },
+                "slug": { "type": ["string", "null"] },
+                "sourceReferencePaths": {
+                  "type": "array",
+                  "items": { "type": "string", "minLength": 1 }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "orphanCoordinationMarkdown": {
+      "type": "array",
+      "description": "Coordination-shaped detail .md files under context root that are not current discoverDetailMarkdownGroups targets (e.g. stale FE-nn-old-slug.md after slug change).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["basename", "kind"],
+        "properties": {
+          "basename": { "type": "string", "minLength": 1 },
+          "kind": { "type": "string", "const": "orphan_detail_markdown" },
+          "hint": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/resources/schemas/context-lists/coverage-reference-validation.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/coverage-reference-validation.schema.json",
+  "title": "coverage-reference-validation",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "generatedAt",
+    "repositoryRoot",
+    "granularity",
+    "referencedFiles",
+    "nonReferencedFiles",
+    "references",
+    "metrics"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Document format version."
+    },
+    "generatedAt": {
+      "type": "string",
+      "minLength": 1,
+      "description": "ISO-8601 UTC timestamp when the document was produced."
+    },
+    "repositoryRoot": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Absolute path to the analyzed repository root (workspace folder)."
+    },
+    "granularity": {
+      "type": "string",
+      "enum": ["file"],
+      "description": "v0.1: LOC metrics treat any cited file as fully referenced."
+    },
+    "ignoreDirs": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Directory basenames skipped during repository enumeration (includes **`.opencode/`** — OpenCode tooling, not product source)."
+    },
+    "referencedFiles": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Repo-relative POSIX paths with at least one reference. Paths under `.gluecharm/` at repo root are not listed. Files named **`.gitignore`** (any directory) and known **image / icon** extensions are omitted from the corpus. When `.git` exists and `git ls-files` succeeds, paths ignored by **`.gitignore` rules** (Git exclude-standard) are not listed."
+    },
+    "nonReferencedFiles": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Authoritative list of in-scope repo files with **zero** citations from context artefacts (same as “files with zero references”). Sorted like the LOC walk. Same corpus rules as **referencedFiles** (**`.gitignore`** files excluded, image extensions excluded, `.gluecharm/` root tree, Git exclude-standard when applicable, **`.opencode/`** dirs skipped)."
+    },
+    "references": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "sourceArtefact", "sourceKind"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Repo-relative path to a file."
+          },
+          "startLine": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "1-based start line when known."
+          },
+          "endLine": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "1-based end line when known."
+          },
+          "sourceArtefact": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Path relative to .gluecharm/context/ (e.g. features-list.json)."
+          },
+          "sourceKind": {
+            "type": "string",
+            "minLength": 1,
+            "description": "e.g. json_source_reference, markdown_evidence_index."
+          }
+        }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "totalLoc",
+        "referencedLoc",
+        "nonReferencedLoc",
+        "percentNonReferenced"
+      ],
+      "properties": {
+        "totalLoc": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Sum of physical lines over scanned files only; **`.gitignore`** files excluded; known image/icon extensions excluded; `.gluecharm/` at repo root excluded; **`.opencode/`** dirs skipped; when `.git` exists and `git ls-files` works, only tracked + untracked non-ignored paths (Git exclude-standard / **`.gitignore` rules**)."
+        },
+        "referencedLoc": { "type": "integer", "minimum": 0 },
+        "nonReferencedLoc": { "type": "integer", "minimum": 0 },
+        "percentNonReferenced": { "type": "integer", "minimum": 0, "maximum": 100 }
+      }
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "excludedFiles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "reason"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/resources/schemas/context-lists/data-model-list.schema.json

@@ -0,0 +1,157 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/data-model-list.schema.json",
+  "title": "data-model-list",
+  "$defs": {
+    "sourceReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "startLine", "endLine"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[^/]+(/[^/]+)*$",
+          "description": "Repo-relative path to a single file (forward slashes). Not a directory: no trailing slash; list each file in a folder as its own sourceReferences entry."
+        },
+        "startLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive start line."
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive end line; should be >= startLine."
+        },
+        "note": {
+          "type": "string",
+          "description": "Optional short label for this evidence span."
+        }
+      }
+    },
+    "sourceReferenceList": {
+      "type": "array",
+      "description": "Evidence spans: each item references one file + line range, never a folder path.",
+      "items": { "$ref": "#/$defs/sourceReference" }
+    },
+    "embeddedField": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["code", "name", "sourceReferences"],
+      "description": "Optional inline field row on an entity (legacy); prefer DM-nn-fields-list.json when using per-entity list files.",
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^FD-[0-9]+$"
+        },
+        "name": { "type": "string", "minLength": 1 },
+        "slug": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+        },
+        "description": { "type": "string" },
+        "order": { "type": "integer" },
+        "sourceReferences": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Required: at least one file + line range per inline field row.",
+          "items": { "$ref": "#/$defs/sourceReference" }
+        }
+      }
+    },
+    "embeddedRelationship": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["code", "name", "sourceReferences"],
+      "description": "Optional relationship row on an entity (legacy); detail markdown may carry full RL-* specs.",
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^RL-[0-9]+$"
+        },
+        "name": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "order": { "type": "integer" },
+        "sourceReferences": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Required: at least one file + line range per inline relationship row.",
+          "items": { "$ref": "#/$defs/sourceReference" }
+        }
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["entities"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.data-model-list",
+      "description": "Optional coordination document id; when present must be this value."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional coordination format version when present."
+    },
+    "entities": {
+      "type": "array",
+      "description": "Registry of domain entities (DM-*). Fields and relationships may live in per-entity `DM-nn-fields-list.json` or optionally inline here for compatibility with the index assembler.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "name", "slug", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^DM-[0-9]+$"
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          },
+          "description": { "type": "string" },
+          "order": { "type": "integer" },
+          "sourceReferences": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Required: at least one file + line range per entity row.",
+            "items": { "$ref": "#/$defs/sourceReference" }
+          },
+          "fields": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/embeddedField" }
+          },
+          "relationships": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/embeddedRelationship" }
+          }
+        }
+      }
+    },
+    "revisionLog": {
+      "type": "array",
+      "description": "Append-only log of substantive edits; add an entry whenever this pass changes rows, merges, or refines the coordination file.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["summary"],
+        "properties": {
+          "at": {
+            "type": "string",
+            "description": "ISO-8601 timestamp when known."
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000,
+            "description": "What was added, changed, or refined in this write."
+          }
+        }
+      }
+    }
+  }
+}

package/resources/schemas/context-lists/entity-fields-list.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/entity-fields-list.schema.json",
+  "title": "DM-nn-fields-list",
+  "$defs": {
+    "sourceReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "startLine", "endLine"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[^/]+(/[^/]+)*$",
+          "description": "Repo-relative path to a single file (forward slashes). Not a directory: no trailing slash; list each file in a folder as its own sourceReferences entry."
+        },
+        "startLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive start line."
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive end line; should be >= startLine."
+        },
+        "note": {
+          "type": "string",
+          "description": "Optional short label for this evidence span."
+        }
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["entityCode", "fields"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.entity-fields-list",
+      "description": "Optional coordination document id; when present must be this value."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional coordination format version when present."
+    },
+    "entityCode": {
+      "type": "string",
+      "pattern": "^DM-[0-9]+$",
+      "description": "Must match the entity row in data-model-list.json and the output basename DM-nn-fields-list.json."
+    },
+    "fields": {
+      "type": "array",
+      "description": "Each field must include implementation evidence via sourceReferences (same shape as other coordination lists).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "name", "slug", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^FD-[0-9]+$"
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "description": "URL-safe slug for DM-nn_FD-ff-<slug>.md detail basename."
+          },
+          "description": { "type": "string" },
+          "order": { "type": "integer" },
+          "sourceReferences": {
+            "type": "array",
+            "minItems": 1,
+            "description": "At least one file + line span per field; each path is a single repo file (never a directory). Do not use readme.md basenames.",
+            "items": { "$ref": "#/$defs/sourceReference" }
+          }
+        }
+      }
+    },
+    "revisionLog": {
+      "type": "array",
+      "description": "Append-only log of substantive edits; add an entry whenever this pass changes rows, merges, or refines the coordination file.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["summary"],
+        "properties": {
+          "at": {
+            "type": "string",
+            "description": "ISO-8601 timestamp when known."
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000,
+            "description": "What was added, changed, or refined in this write."
+          }
+        }
+      }
+    }
+  }
+}

package/resources/schemas/context-lists/experiences-list.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/experiences-list.schema.json",
+  "title": "experiences-list",
+  "$defs": {
+    "sourceReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "startLine", "endLine"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[^/]+(/[^/]+)*$",
+          "description": "Repo-relative path to a single file (forward slashes). Not a directory: no trailing slash; list each file in a folder as its own sourceReferences entry."
+        },
+        "startLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive start line."
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive end line; should be >= startLine."
+        },
+        "note": {
+          "type": "string",
+          "description": "Optional short label for this evidence span."
+        }
+      }
+    },
+    "sourceReferenceList": {
+      "type": "array",
+      "description": "Evidence spans: each item references one file + line range, never a folder path.",
+      "items": { "$ref": "#/$defs/sourceReference" }
+    },
+    "interactionItem": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["code", "name", "sourceReferences"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^BH-[0-9]+$"
+        },
+        "name": { "type": "string", "minLength": 1 },
+        "slug": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+          "description": "Recommended for XP-<nn>_BH-<ii>-<slug>.md detail basenames."
+        },
+        "description": { "type": "string" },
+        "order": { "type": "integer" },
+        "sourceReferences": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Required: at least one file + line range per interaction row.",
+          "items": { "$ref": "#/$defs/sourceReference" }
+        }
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["views"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.experiences-list",
+      "description": "Optional coordination document id; when present must be this value."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional coordination format version when present."
+    },
+    "views": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["code", "name", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^XP-[0-9]+$"
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "description": "Recommended for XP-<nn>-<slug>.md detail basenames."
+          },
+          "description": { "type": "string" },
+          "order": { "type": "integer" },
+          "sourceReferences": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Required: at least one file + line range per view row.",
+            "items": { "$ref": "#/$defs/sourceReference" }
+          },
+          "interactions": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/interactionItem" }
+          }
+        }
+      }
+    },
+    "revisionLog": {
+      "type": "array",
+      "description": "Append-only log of substantive edits; add an entry whenever this pass changes rows, merges, or refines the coordination file.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["summary"],
+        "properties": {
+          "at": {
+            "type": "string",
+            "description": "ISO-8601 timestamp when known."
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000,
+            "description": "What was added, changed, or refined in this write."
+          }
+        }
+      }
+    }
+  }
+}