Documentation
¶
Overview ¶
Package sharedschema derives byte-identical mirror copies of the shared error envelope schema from its single canonical source.
Purpose ¶
contracts/shared/errors/error-response-v1.schema.json is the single source-of-truth for the GoCell HTTP error response envelope. Several sub-trees in the repository (example projects, contract test fixtures) need a local copy of that file to validate against; those copies are declared in Mirrors and regenerated by Generate / verified by Verify.
AI-robust grade ¶
Upstream: Medium — the A1 reverse-enum archtest (SHARED-SCHEMA-MIRROR-FUNNEL-01) detects new rogue copies at CI time; the Go type system cannot prevent creating a JSON file. gh issue #954 tracks Hard-ening this side.
Downstream: Medium — the A2 caller-allowlist archtest restricts Headerless usage to this package; the WriteOptions struct field is exported so it cannot be sealed at compile time. Same gh issue #954 tracks upgrading to a typed-funnel construction pattern that seals the escape-hatch.
Symbols ¶
- Mirrors — manifest: canonical path → []destination root prefixes
- Generate — write byte-identical mirror copies (or dry-run preview)
- Verify — report destination paths whose content has drifted
archtest ID: SHARED-SCHEMA-MIRROR-FUNNEL-01 ADR ref: docs/architecture/202605250900-adr-shared-error-schema-mirror-codegen.md Hard-ening tracking: gh issue #954
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Mirrors = map[string][]string{
"contracts/shared/errors/error-response-v1.schema.json": {
"examples/demo",
"examples/iotdevice",
"examples/orderfulfillment",
"examples/todoorder",
"tests/contracttest/testdata",
},
}
Mirrors maps each canonical schema path (module-relative, slash-separated) to the list of destination root prefixes where a byte-identical copy must exist. The destination file path is:
<repoRoot>/<destRoot>/<canonicalRel>
The key is the canonical path; callers must not add entries here without also deleting any existing copy that would otherwise become an undeclared fork (caught by archtest SHARED-SCHEMA-MIRROR-FUNNEL-01 A1).
Functions ¶
func Generate ¶
Generate reads each canonical schema file from root and writes byte-identical copies to every declared mirror destination. When dryRun is true no files are written; the returned written list still contains the paths that would have been written.
written contains module-relative slash paths for every file that was actually written (ActionWritten) or would have been written (ActionWouldWrite when dryRun=true). Already-up-to-date mirrors (ActionUnchanged) are omitted. The slice is sorted for deterministic output.
func Verify ¶
Verify checks that every declared mirror destination is byte-identical to the canonical source. It returns the module-relative slash paths of every destination that differs (or is missing). An empty drifted slice means all mirrors are in sync. The slice is sorted for deterministic output.
Types ¶
This section is empty.
Source Files